Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
14.2 KB
Raw Blame
/**
 * The applier capability table (no-dead-ends, task 8).
 *
 * Three Finding-to-apply pipelines ship in this codebase - `applyRepair`
 * (`diagnostics.ts`), `applyHygienePlan` (`hygiene/apply.ts`) and
 * `applyRemediation` (`health/remediation.ts`) - plus the self-healing
 * consolidation pass in `lint-consolidate.ts`. Each one used to decide
 * privately what it could repair, so the question "is this finding
 * mechanically fixable, and if not why not?" had four partial answers and
 * no single one. This module is that answer: per finding code, either
 * MECHANICAL (naming the fixer that performs the repair) or REFUSED
 * (naming the reason it is not attempted).
 *
 * One surface is a verb rather than one of those four: the preview-first
 * privacy-marker restamp is run by an operator against a named vault, so
 * its MECHANICAL entry names that module's planner instead of an applier
 * that routes a Finding. The verdict answers the same question - a
 * deterministic, idempotent repair exists - and the separate exits table
 * still says why the doctor names no single command for it.
 *
 * A refusal is a deliverable here. Every entry below that declines a
 * repair states why in a non-empty reason, because a finding whose exit
 * is "nothing happens" is exactly the dead end this release removes.
 *
 * ## Why this is its own module, and why it imports nothing
 *
 * The design left the placement open, to be decided by import surface.
 * The table's consumers are the three appliers plus `hygiene/plan.ts`,
 * and its natural alternative home - `diagnostics.ts`, beside the fixer
 * registry - transitively pulls in `doctor.ts`, the whole detection pass.
 * Hosting the table there would make `health/remediation.ts` and
 * `hygiene/plan.ts` import the detector in order to ask a question about
 * repair, and would make the dependency circular the moment
 * `diagnostics.ts` consulted the table itself.
 *
 * So this module is a plain-data leaf with NO imports, and every code in
 * it is written as a literal rather than referenced from the constant
 * that also spells it. The literals are bound to their sources by
 * `tests/core/brain/applier-capability.test.ts`, which re-derives the
 * same population from the fixer registry, the remediation planner, the
 * hygiene plan builder and the lint fix kinds, and fails on any
 * disagreement in either direction. The binding is a test rather than an
 * import on purpose: it is the only form that also catches a fixer added
 * without a table entry.
 *
 * ## Write-guard placement: the one rule
 *
 * The three appliers used to place `assertVaultIdentityForWrite` three
 * different ways - hygiene after its dry-run return, repair before it and
 * conditional on it, remediation unconditionally including on dry runs.
 * The unified rule, which all four write paths now follow:
 *
 *   ASSERT AT THE APPLIER'S ENTRY POINT, BEFORE ANY OTHER WORK, AND ONLY
 *   WHEN THE CALL WILL WRITE.
 *
 * Both halves carry a reason and both come from a placement that already
 * existed.
 *
 *   - "Before any other work" is hygiene's rationale, generalised. Its
 *     per-finding loop is fail-soft, so an assertion reached from inside
 *     an executor would be recorded as one finding's error instead of
 *     refusing the run; and more generally a refusal that arrives after
 *     the first byte is on disk has already materialized the wrong store.
 *   - "Only when the call will write" is the repair path's rationale, and
 *     it is what the guard's own contract says: it is a WRITE guard. A
 *     dry run writes nothing, so gating it turns a preview - the very
 *     thing an operator reaches for to find out what is wrong - into a
 *     refusal. Remediation's unconditional placement was the outlier and
 *     is the behaviour that changed.
 *
 * `lint-consolidate.ts` follows the same rule (task 10): it used to
 * assert unconditionally, which let the read-only `o2b brain actions`
 * verb fail with a write-path error.
 */

/** Whether a finding code has a mechanical repair, or a stated refusal. */
export const REPAIR_VERDICT = Object.freeze({
  mechanical: "mechanical",
  refused: "refused",
} as const);

export type RepairVerdict = (typeof REPAIR_VERDICT)[keyof typeof REPAIR_VERDICT];

/**
 * The module that owns the repair (or the refusal). `detectorOnly` is for
 * codes a detector reports and no applier claims - those can only ever be
 * refusals, asserted by the capability test.
 */
export const REPAIR_SURFACE = Object.freeze({
  diagnostics: "diagnostics",
  healthRemediation: "health/remediation",
  hygieneApply: "hygiene/apply",
  lintConsolidate: "lint-consolidate",
  // A repair pipeline that is a verb rather than one of the three
  // appliers: the preview-first restamp rewrites frontmatter and is
  // invoked by an operator, not routed from a Finding.
  privacyMarkerRestamp: "privacy-marker-restamp",
  detectorOnly: "detector-only",
} as const);

export type RepairSurface = (typeof REPAIR_SURFACE)[keyof typeof REPAIR_SURFACE];

interface RepairCapabilityBase {
  /** The finding code, exactly as the detecting surface emits it. */
  readonly code: string;
  readonly surface: RepairSurface;
}

/** A code a named fixer repairs safely, deterministically and idempotently. */
export interface MechanicalRepair extends RepairCapabilityBase {
  readonly verdict: typeof REPAIR_VERDICT.mechanical;
  /** The function that performs the repair, named so the claim is checkable. */
  readonly fixer: string;
}

/** A code no applier will repair, with the reason it will not. */
export interface RefusedRepair extends RepairCapabilityBase {
  readonly verdict: typeof REPAIR_VERDICT.refused;
  /** Why the repair is not attempted. Never empty. */
  readonly reason: string;
}

export type RepairCapability = MechanicalRepair | RefusedRepair;

/** A code that appears in no table entry. Never resolved to a guess. */
export class UnclassifiedRepairCodeError extends Error {
  readonly code: string;
  constructor(code: string) {
    super(
      `no applier capability is published for finding code ${JSON.stringify(code)}; ` +
        "add an entry to APPLIER_CAPABILITY declaring it mechanical or refused",
    );
    this.name = "UnclassifiedRepairCodeError";
    this.code = code;
  }
}

/** A mechanical repair was demanded for a code the table refuses. */
export class RefusedRepairError extends Error {
  readonly code: string;
  readonly reason: string;
  constructor(entry: RefusedRepair) {
    super(`finding code ${JSON.stringify(entry.code)} has no mechanical repair: ${entry.reason}`);
    this.name = "RefusedRepairError";
    this.code = entry.code;
    this.reason = entry.reason;
  }
}

/** Two entries claimed the same code - the table would silently lose one. */
export class DuplicateRepairCodeError extends Error {
  constructor(code: string) {
    super(`APPLIER_CAPABILITY declares finding code ${JSON.stringify(code)} more than once`);
    this.name = "DuplicateRepairCodeError";
  }
}

const ENTRIES: ReadonlyArray<RepairCapability> = [
  // --- diagnostics: the two guarded doctor fixers -------------------------
  {
    code: "wal-gap",
    surface: REPAIR_SURFACE.diagnostics,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "diagnostics.walGapFixer",
  },
  {
    code: "orphaned-reference",
    surface: REPAIR_SURFACE.diagnostics,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "diagnostics.orphanedReferenceFixer",
  },

  // --- health/remediation: bookkeeping repairs, semantic review -----------
  {
    code: "content-hash-drift",
    surface: REPAIR_SURFACE.healthRemediation,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "health/remediation.restampContentHash",
  },
  {
    code: "wide-permissions",
    surface: REPAIR_SURFACE.healthRemediation,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "health/remediation.hardenPermissions",
  },
  {
    code: "contradictory-preferences",
    surface: REPAIR_SURFACE.healthRemediation,
    verdict: REPAIR_VERDICT.refused,
    reason:
      "which of the two rules survives is a judgment about what the operator " +
      "currently believes; an applier picking one would retire a rule nobody " +
      "decided to retire",
  },
  {
    code: "stale-claim",
    surface: REPAIR_SURFACE.healthRemediation,
    verdict: REPAIR_VERDICT.refused,
    reason:
      "age is evidence that a claim needs re-confirming, not evidence that it " +
      "is wrong; only the operator can tell an obsolete rule from a durable one " +
      "that simply has not come up",
  },
  {
    code: "concept-gap",
    surface: REPAIR_SURFACE.healthRemediation,
    verdict: REPAIR_VERDICT.refused,
    reason:
      "the repair is to write a preference that does not exist yet, which is " +
      "authoring content rather than repairing a record",
  },

  // --- hygiene/apply: one executor per proposed action --------------------
  {
    code: "merge",
    surface: REPAIR_SURFACE.hygieneApply,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "hygiene/apply.executeFinding -> mergePreferences",
  },
  {
    code: "supersede",
    surface: REPAIR_SURFACE.hygieneApply,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "hygiene/apply.executeFinding -> appendClaimEvent",
  },
  {
    code: "recompile",
    surface: REPAIR_SURFACE.hygieneApply,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "hygiene/apply.executeFinding -> executeRecompile",
  },
  {
    code: "archive",
    surface: REPAIR_SURFACE.hygieneApply,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "hygiene/apply.executeFinding -> archivePage",
  },
  {
    code: "forget",
    surface: REPAIR_SURFACE.hygieneApply,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "hygiene/apply.executeFinding -> archivePage",
  },
  {
    code: "retire",
    surface: REPAIR_SURFACE.hygieneApply,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "hygiene/apply.executeFinding -> retireDocumentCopies",
  },
  {
    code: "review",
    surface: REPAIR_SURFACE.hygieneApply,
    verdict: REPAIR_VERDICT.refused,
    reason:
      "the closed action vocabulary's safe default: a detector routes a finding " +
      "here precisely when it cannot name an executor for it, so there is nothing " +
      "to run",
  },

  // --- lint-consolidate: the self-healing structural pass -----------------
  {
    code: "fix-merged-link",
    surface: REPAIR_SURFACE.lintConsolidate,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "lint-consolidate.scanFileForMergedLinks",
  },
  {
    code: "demote-stale-stable",
    surface: REPAIR_SURFACE.lintConsolidate,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "lint-consolidate.applyDemotion",
  },

  // --- privacy-marker-restamp: the operator-run additive repair ------------
  {
    code: "privacy-marker-unstamped",
    surface: REPAIR_SURFACE.privacyMarkerRestamp,
    verdict: REPAIR_VERDICT.mechanical,
    fixer: "privacy-marker-restamp.planPrivacyMarkerRestamp",
  },

  // --- detector-only: reported, deliberately never repaired ---------------
  {
    code: "stale-lock",
    surface: REPAIR_SURFACE.detectorOnly,
    verdict: REPAIR_VERDICT.refused,
    reason:
      "the lock primitive is a single-attempt exclusive create with no breaker, " +
      "so no timeout distinguishes a crashed writer from a slow live one; " +
      "removing a live writer's lock corrupts what it protects",
  },
  {
    code: "vault-marker-absent",
    surface: REPAIR_SURFACE.detectorOnly,
    verdict: REPAIR_VERDICT.refused,
    reason:
      "an absent marker is ambiguous by construction - a fresh directory, a vault " +
      "predating markers and a mis-resolved root are indistinguishable - so " +
      "stamping one would name whichever root the typo produced",
  },
  {
    code: "frontmatter-line-dropped",
    surface: REPAIR_SURFACE.detectorOnly,
    verdict: REPAIR_VERDICT.refused,
    reason:
      "the frontmatter scanner is line-based, so a dropped line is by definition " +
      "grammar it has no branch for; repairing it means choosing a target shape " +
      "per case, which is a policy decision rather than a mechanical fix",
  },
  {
    code: "link_integrity",
    surface: REPAIR_SURFACE.detectorOnly,
    verdict: REPAIR_VERDICT.refused,
    reason:
      "the ratchet measurement yields scalar counts over the search index and no " +
      "per-link rows, so there is no individual finding for an applier to act on",
  },
  {
    code: "chunk-holds-active",
    surface: REPAIR_SURFACE.detectorOnly,
    verdict: REPAIR_VERDICT.refused,
    reason:
      "a hold is the embedding configuration declining a chunk it provably cannot " +
      "take, not damage to repair; the levers - narrower chunking or leaving the " +
      "page unembedded - are per-document editorial decisions, and the index-side " +
      "release is automatic the moment the configuration changes",
  },
];

/**
 * The published table, keyed by finding code. Built eagerly so a
 * duplicate code fails at import rather than silently losing an entry.
 */
export const APPLIER_CAPABILITY: ReadonlyMap<string, RepairCapability> = (() => {
  const table = new Map<string, RepairCapability>();
  for (const entry of ENTRIES) {
    if (table.has(entry.code)) throw new DuplicateRepairCodeError(entry.code);
    table.set(entry.code, Object.freeze(entry));
  }
  return table;
})();

/** The published capability for `code`, or `null` when none is published. */
export function repairCapability(code: string): RepairCapability | null {
  return APPLIER_CAPABILITY.get(code) ?? null;
}

/**
 * The published capability for `code`, or {@link UnclassifiedRepairCodeError}.
 * Callers that must route a finding use this rather than defaulting: an
 * unpublished code means the table and the applier have drifted, and
 * guessing a route is how a finding gets silently dropped.
 */
export function requireRepairCapability(code: string): RepairCapability {
  const entry = APPLIER_CAPABILITY.get(code);
  if (entry === undefined) throw new UnclassifiedRepairCodeError(code);
  return entry;
}

/**
 * The mechanical repair for `code`. Raises {@link RefusedRepairError}
 * (carrying the published reason) when the table refuses the code, and
 * {@link UnclassifiedRepairCodeError} when it does not know it.
 */
export function requireMechanicalRepair(code: string): MechanicalRepair {
  const entry = requireRepairCapability(code);
  if (entry.verdict === REPAIR_VERDICT.refused) throw new RefusedRepairError(entry);
  return entry;
}