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
10.8 KB
Raw Blame
/**
 * no-dead-ends, task 8: the applier capability table.
 *
 * Three Finding-to-apply pipelines ship in this codebase and each one used
 * to decide privately what it could repair. The table is the published
 * answer - per finding code, mechanical (naming the fixer) or refused
 * (naming the reason) - and this file is the mechanism that stops the
 * table and the appliers from drifting apart.
 *
 * The table module imports nothing, deliberately (see its docblock), so
 * every code in it is a literal. That is only safe because the checks
 * below re-derive the same population from the appliers themselves and
 * fail on any disagreement in either direction.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import {
  APPLIER_CAPABILITY,
  REPAIR_SURFACE,
  REPAIR_VERDICT,
  RefusedRepairError,
  UnclassifiedRepairCodeError,
  repairCapability,
  requireMechanicalRepair,
  requireRepairCapability,
} from "../../../src/core/brain/applier-capability.ts";
import {
  REPAIR_CODE,
  REPAIR_FIXER_CODES,
  applyRepair,
} from "../../../src/core/brain/diagnostics.ts";
import { PRIVACY_MARKER_UNSTAMPED_CODE } from "../../../src/core/brain/doctor/privacy-marker-check.ts";
import { LINT_CONSOLIDATE_KIND } from "../../../src/core/brain/lint-consolidate.ts";
import { applyHygienePlan } from "../../../src/core/brain/hygiene/apply.ts";
import {
  UNATTENDED_EXCLUDED_ACTIONS,
  buildHygienePlan,
} from "../../../src/core/brain/hygiene/plan.ts";
import {
  HYGIENE_PROPOSED_ACTIONS,
  type HygieneFinding,
  type HygieneProposedAction,
  type HygieneScanReport,
} from "../../../src/core/brain/hygiene/types.ts";
import { applyRemediation, planRemediation } from "../../../src/core/brain/health/remediation.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import {
  VaultIdentityMismatchError,
  assertVaultIdentityForWrite,
  resetVaultIdentityPins,
  vaultIdentityPath,
  writeVaultIdentity,
} from "../../../src/core/brain/vault-identity.ts";

/** Codes whose surface is one of the appliers, per the table. */
function codesForSurface(surface: string): string[] {
  return [...APPLIER_CAPABILITY.values()]
    .filter((entry) => entry.surface === surface)
    .map((entry) => entry.code)
    .toSorted();
}

describe("applier capability table - shape", () => {
  test("every entry is keyed by its own code", () => {
    for (const [code, entry] of APPLIER_CAPABILITY) expect(entry.code).toBe(code);
    expect(APPLIER_CAPABILITY.size).toBeGreaterThan(0);
  });

  test("every mechanical entry names a fixer and every refusal names a reason", () => {
    for (const entry of APPLIER_CAPABILITY.values()) {
      if (entry.verdict === REPAIR_VERDICT.mechanical) {
        expect(entry.fixer.length).toBeGreaterThan(0);
      } else {
        expect(entry.verdict).toBe(REPAIR_VERDICT.refused);
        // A refusal with an empty reason is the dead end this release
        // exists to remove, so the emptiness check is the point.
        expect(entry.reason.trim().length).toBeGreaterThan(0);
      }
    }
  });

  test("a code no applier owns can only be a refusal", () => {
    for (const entry of APPLIER_CAPABILITY.values()) {
      if (entry.surface !== REPAIR_SURFACE.detectorOnly) continue;
      expect(entry.verdict).toBe(REPAIR_VERDICT.refused);
    }
    // The five refusals reconnaissance verified as stated-and-deliberate.
    expect(codesForSurface(REPAIR_SURFACE.detectorOnly)).toEqual([
      "chunk-holds-active",
      "frontmatter-line-dropped",
      "link_integrity",
      "stale-lock",
      "vault-marker-absent",
    ]);
  });

  test("lookup refuses to invent an answer for an unregistered code", () => {
    expect(repairCapability("no-such-code")).toBeNull();
    expect(() => requireRepairCapability("no-such-code")).toThrow(UnclassifiedRepairCodeError);
    expect(() => requireMechanicalRepair("stale-lock")).toThrow(RefusedRepairError);
  });
});

describe("applier capability table - cannot disagree with the fixers", () => {
  test("the diagnostics fixer registry and the table name the same codes", () => {
    expect([...REPAIR_FIXER_CODES].toSorted()).toEqual(codesForSurface(REPAIR_SURFACE.diagnostics));
    for (const code of REPAIR_FIXER_CODES) {
      expect(requireMechanicalRepair(code).code).toBe(code);
    }
    expect(REPAIR_FIXER_CODES.has(REPAIR_CODE.walGap)).toBe(true);
    expect(REPAIR_FIXER_CODES.has(REPAIR_CODE.orphanedReference)).toBe(true);
  });

  test("the remediation planner's classification matches the table verdict", () => {
    const plan = planRemediation(
      {
        driftedSlugs: ["drifted"],
        contradictions: [{ aId: "pref-a", bId: "pref-b" }],
        staleClaims: [{ id: "pref-c" }],
        conceptGaps: [{ term: "concept" }],
        widePermissions: [{ path: "Brain/wide.md", isDir: false, mode: 0o644 }],
      },
      { stepCap: 10 },
    );
    const seen = new Set<string>();
    for (const step of plan.steps) {
      seen.add(step.code);
      const entry = requireRepairCapability(step.code);
      const expected =
        entry.verdict === REPAIR_VERDICT.mechanical ? "auto-safe" : ("needs-review" as const);
      expect(step.classification).toBe(expected);
    }
    // Both directions: nothing in the table claims a remediation code the
    // planner cannot produce.
    expect([...seen].toSorted()).toEqual(codesForSurface(REPAIR_SURFACE.healthRemediation));
  });

  test("the hygiene plan executes exactly the actions the table calls mechanical", () => {
    const mechanical: string[] = [];
    const heldForAttendance: string[] = [];
    const refused: string[] = [];
    for (const action of HYGIENE_PROPOSED_ACTIONS) {
      const unattended = buildHygienePlan(reportWithAction(action));
      if (unattended.selected.length === 1) {
        mechanical.push(action);
        continue;
      }
      if (unattended.excluded_review.length !== 1) {
        throw new Error(`hygiene action '${action}' was neither selected nor excluded`);
      }
      if (requireRepairCapability(action).verdict === REPAIR_VERDICT.refused) {
        refused.push(action);
        continue;
      }
      // A mechanical action the unattended default holds back is the
      // destructive class: it must still select when the caller names it
      // by id - that is the whole attended path.
      const attended = buildHygienePlan(reportWithAction(action), { ids: [`probe:${action}`] });
      expect(attended.selected.map((finding) => finding.id)).toEqual([`probe:${action}`]);
      heldForAttendance.push(action);
    }
    expect(mechanical.toSorted()).toEqual(
      codesForSurface(REPAIR_SURFACE.hygieneApply)
        .filter((code) => APPLIER_CAPABILITY.get(code)!.verdict === REPAIR_VERDICT.mechanical)
        .filter((code) => !UNATTENDED_EXCLUDED_ACTIONS.has(code as HygieneProposedAction)),
    );
    expect(heldForAttendance).toEqual(["retire"]);
    expect(refused).toEqual(["review"]);
  });

  test("the lint-consolidate fix kinds are the table's lint entries", () => {
    const kinds: string[] = Object.values(LINT_CONSOLIDATE_KIND);
    expect(kinds.toSorted()).toEqual(codesForSurface(REPAIR_SURFACE.lintConsolidate));
  });

  test("the privacy-marker restamp owns exactly its one code", () => {
    // The surface is an operator-run verb rather than a Finding router, so
    // the binding is by name in both directions: the table's row names the
    // restamp's planner, and the detector's code is the one it repairs.
    expect(codesForSurface(REPAIR_SURFACE.privacyMarkerRestamp)).toEqual([
      PRIVACY_MARKER_UNSTAMPED_CODE,
    ]);
    const entry = requireMechanicalRepair(PRIVACY_MARKER_UNSTAMPED_CODE);
    expect(entry.surface).toBe(REPAIR_SURFACE.privacyMarkerRestamp);
    expect(entry.fixer).toBe("privacy-marker-restamp.planPrivacyMarkerRestamp");
  });
});

function reportWithAction(action: HygieneProposedAction): HygieneScanReport {
  const finding: HygieneFinding = {
    id: `probe:${action}`,
    detector: "dedup",
    severity: "action",
    title: `probe for ${action}`,
    targets: ["pref-a", "pref-b"],
    proposed_action: action,
    evidence: {},
  };
  return {
    generated_at: "2026-07-25T00:00:00Z",
    detectors_run: ["dedup"],
    findings: [finding],
    counts: { dedup: 1 },
    errors: [],
  };
}

// ----- Write-guard placement ------------------------------------------------

let vault: string;
let configDir: string;

beforeEach(() => {
  resetVaultIdentityPins();
  vault = mkdtempSync(join(tmpdir(), "o2b-capability-vault-"));
  configDir = mkdtempSync(join(tmpdir(), "o2b-capability-cfg-"));
  const configPath = join(configDir, "config.yaml");
  atomicWriteFileSync(configPath, `vault: ${vault}\n`);
  bootstrapBrain(vault, { configPath });
});

afterEach(() => {
  resetVaultIdentityPins();
  rmSync(vault, { recursive: true, force: true });
  rmSync(configDir, { recursive: true, force: true });
});

/**
 * Put the resolved root into the ONE state the guard refuses: a marker
 * this process already pinned, replaced by a different one.
 */
function makeVaultIdentityMismatch(): void {
  writeVaultIdentity(vault);
  assertVaultIdentityForWrite(vault);
  atomicWriteFileSync(
    vaultIdentityPath(vault),
    `${JSON.stringify(
      { schema_version: 1, vault_id: "f".repeat(32), created_at: "2026-01-01T00:00:00.000Z" },
      null,
      2,
    )}\n`,
  );
}

describe("write-guard placement is identical across the three appliers", () => {
  const emptyHygienePlan = Object.freeze({
    selected: Object.freeze([]),
    excluded_review: Object.freeze([]),
    unknown_ids: Object.freeze([]),
  });
  const now = new Date("2026-07-25T00:00:00Z");

  test("a dry run previews against a root the guard would refuse to write", async () => {
    makeVaultIdentityMismatch();

    expect(applyRepair(vault, { dryRun: true }).dryRun).toBe(true);
    expect(
      (await applyHygienePlan(vault, emptyHygienePlan, { dryRun: true, agent: "t", now })).dry_run,
    ).toBe(true);
    expect(
      applyRemediation(vault, planRemediation(NO_FINDINGS, { stepCap: 1 }), { dryRun: true })
        .dryRun,
    ).toBe(true);
  });

  test("a real apply refuses on the same root", async () => {
    makeVaultIdentityMismatch();

    expect(() => applyRepair(vault, { dryRun: false })).toThrow(VaultIdentityMismatchError);
    await expect(
      applyHygienePlan(vault, emptyHygienePlan, { dryRun: false, agent: "t", now }),
    ).rejects.toThrow(VaultIdentityMismatchError);
    expect(() =>
      applyRemediation(vault, planRemediation(NO_FINDINGS, { stepCap: 1 }), { dryRun: false }),
    ).toThrow(VaultIdentityMismatchError);
  });
});

const NO_FINDINGS = Object.freeze({
  driftedSlugs: Object.freeze([]),
  contradictions: Object.freeze([]),
  staleClaims: Object.freeze([]),
  conceptGaps: Object.freeze([]),
});