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
16.4 KB
Raw Blame
/**
 * Skill contract completeness (no-dead-ends, Unit I / Task 20).
 *
 * Three things this pins:
 *   1. acceptance WRITES prerequisites / rollback / side effects /
 *      verification and the procedural-memory reader READS them back, so
 *      they are a contract rather than frontmatter decoration;
 *   2. a proposal's self-reported evidence is resolved against the
 *      independently recorded procedural outcome ledger, keeping the three
 *      outcome states distinct (failures, successes, nothing recorded);
 *   3. the accept sequence is a compensating transaction - a crash at each
 *      of its three gaps leaves neither a duplicate nor an orphan.
 */

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

import { appendContinuityRecord } from "../../../src/core/brain/continuity/store.ts";
import { parseFrontmatter } from "../../../src/core/vault.ts";
import {
  procedurePath,
  proceduralMemoryIndexPath,
  skillProposalAcceptedPath,
  skillProposalPendingPath,
} from "../../../src/core/brain/paths.ts";
import {
  acceptSkillProposal,
  learnSkillProposals,
  listPendingSkillProposals,
  recoverSkillProposalAccepts,
  resolveSkillProposalEvidence,
} from "../../../src/core/brain/skill-proposals.ts";
import {
  listSkillAcceptJournals,
  writeSkillAcceptJournal,
} from "../../../src/core/brain/skill-accept-journal.ts";
import {
  listProceduralMemory,
  proceduralEntryId,
  recordProceduralOutcome,
} from "../../../src/core/brain/procedural-memory.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-skill-contract-"));
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

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

const ACCEPTED_AT = new Date("2026-06-01T10:00:00.000Z");
const LEARNED_AT = new Date("2026-06-01T09:00:00.000Z");

/** Seed three records of one repeated action; returns the drafted slug. */
function seedAndLearn(action: string): string {
  for (let i = 0; i < 3; i++) {
    const mm = String(10 + i).padStart(2, "0");
    appendContinuityRecord(vault, {
      kind: "session_turn",
      createdAt: `2026-05-20T08:${mm}:00Z`,
      sourceRefs: [{ id: `src-${action.replaceAll("_", "-")}-${i}` }],
      payload: { action, summary: `did ${action} run ${i}` },
    });
  }
  learnSkillProposals(vault, { now: LEARNED_AT, minSupport: 3 });
  const target = listPendingSkillProposals(vault).find((p) => p.patternKind === "repeated_action");
  if (!target) throw new Error("test setup: no repeated_action draft was created");
  return target.slug;
}

function frontmatterOf(path: string): Record<string, unknown> {
  const [fm] = parseFrontmatter(path);
  return fm as Record<string, unknown>;
}

const CONTRACT = {
  prerequisites: ["o2b brain doctor --json reports zero blocking issues"],
  rollback: ["o2b brain restore --snapshot pre-rotate"],
  sideEffects: ["rewrites Brain/procedural-memory/index.json"],
  verification: ["o2b brain procedures list --json"],
} as const;

describe("the skill contract is written on acceptance", () => {
  test("acceptance writes the four contract fields and the reader returns them", () => {
    const slug = seedAndLearn("rotate_keys");
    const accepted = acceptSkillProposal(vault, slug, { now: ACCEPTED_AT, contract: CONTRACT });

    const archiveFm = frontmatterOf(accepted.proposalPath);
    expect(archiveFm["prerequisites"]).toEqual([...CONTRACT.prerequisites]);
    expect(archiveFm["rollback"]).toEqual([...CONTRACT.rollback]);
    expect(archiveFm["side_effects"]).toEqual([...CONTRACT.sideEffects]);
    expect(archiveFm["verification"]).toEqual([...CONTRACT.verification]);

    const procFm = frontmatterOf(procedurePath(vault, slug));
    expect(procFm["prerequisites"]).toEqual([...CONTRACT.prerequisites]);
    expect(procFm["rollback"]).toEqual([...CONTRACT.rollback]);
    expect(procFm["side_effects"]).toEqual([...CONTRACT.sideEffects]);
    expect(procFm["verification"]).toEqual([...CONTRACT.verification]);

    // The contract is read BACK by the procedural-memory reader, so it
    // reaches a consumer instead of decorating a file nobody parses.
    const entry = listProceduralMemory(vault).find(
      (e) => e.sourcePath === `Brain/procedures/proc-${slug}.md`,
    );
    expect(entry).toBeDefined();
    expect(entry!.prerequisites).toEqual([...CONTRACT.prerequisites]);
    expect(entry!.rollback).toEqual([...CONTRACT.rollback]);
    expect(entry!.sideEffects).toEqual([...CONTRACT.sideEffects]);
    expect(entry!.verification).toEqual([...CONTRACT.verification]);
  });

  test("an empty contract entry is refused by name instead of silently dropped", () => {
    const slug = seedAndLearn("rotate_keys");
    expect(() =>
      acceptSkillProposal(vault, slug, {
        now: ACCEPTED_AT,
        contract: { prerequisites: ["   "] },
      }),
    ).toThrow(/skill contract field 'prerequisites'/);
    // Nothing was written: the draft is still pending and unreviewed.
    expect(existsSync(skillProposalPendingPath(vault, slug))).toBe(true);
    expect(existsSync(skillProposalAcceptedPath(vault, slug))).toBe(false);
    expect(existsSync(procedurePath(vault, slug))).toBe(false);
  });
});

describe("byte-identical when the contract is absent", () => {
  test("accepting with no contract produces exactly the pre-contract bytes", () => {
    const slug = seedAndLearn("rotate_keys");
    expect(slug).toBe("repeated_action-rotate-keys-0e4b812f");
    acceptSkillProposal(vault, slug, { now: ACCEPTED_AT });

    // Golden bytes captured from the accept path BEFORE this unit landed.
    expect(readFileSync(skillProposalAcceptedPath(vault, slug), "utf8")).toBe(
      '---\nschema_version: 1\nkind: brain-skill-proposal\nid: prop-repeated_action-rotate-keys-0e4b812f\nslug: repeated_action-rotate-keys-0e4b812f\nstatus: accepted\npattern_kind: repeated_action\nname_key: "repeated_action:rotate_keys"\nversion: 1\nconfidence: 0.550\npayload_hash: 0e4b812f12089af795a186a2ac11330f26cdefb4f8e4d216d8ac6b3465bc64e0\ncreated_at: "2026-06-01T09:00:00.000Z"\nupdated_at: "2026-06-01T10:00:00.000Z"\nwatermark_from: ""\nwatermark_to: "2026-05-20T08:12:00Z"\nevidence_count: 3\nsource_refs: [ctn_20260520081000_d9c5e970465448f3, src-rotate-keys-0, ctn_20260520081100_5917efe2f4a20f97, src-rotate-keys-1, ctn_20260520081200_3d2812bae9bdffbe, src-rotate-keys-2]\nreviewed_at: "2026-06-01T10:00:00.000Z"\n---\n\n# Repeated action: rotate_keys\n\n## Pattern\n- kind: repeated_action\n- key: rotate_keys\n\n## Suggested skill body\nWhen pattern `rotate_keys` appears, follow the observed repeatable workflow.\nCapture inputs first, execute steps in stable order, and emit audit-friendly outputs.\n\n## Evidence\n- 2026-05-20T08:10:00Z :: session_turn :: ctn_20260520081000_d9c5e970465448f3 :: did rotate_keys run 0\n- 2026-05-20T08:11:00Z :: session_turn :: ctn_20260520081100_5917efe2f4a20f97 :: did rotate_keys run 1\n- 2026-05-20T08:12:00Z :: session_turn :: ctn_20260520081200_3d2812bae9bdffbe :: did rotate_keys run 2\n',
    );
    expect(readFileSync(procedurePath(vault, slug), "utf8")).toBe(
      '---\nschema_version: 1\nkind: brain-procedure\nid: proc-repeated_action-rotate-keys-0e4b812f\nslug: repeated_action-rotate-keys-0e4b812f\nsource_proposal: prop-repeated_action-rotate-keys-0e4b812f\nversion: 1\ncreated_at: "2026-06-01T10:00:00.000Z"\nupdated_at: "2026-06-01T10:00:00.000Z"\nstatus: active\n---\n\n# Procedure\n\nAccepted from proposal: [[prop-repeated_action-rotate-keys-0e4b812f]]\n\nWhen pattern `rotate_keys` appears, follow the observed repeatable workflow.\nCapture inputs first, execute steps in stable order, and emit audit-friendly outputs.\n\n## Evidence\n- 2026-05-20T08:10:00Z :: session_turn :: ctn_20260520081000_d9c5e970465448f3 :: did rotate_keys run 0\n- 2026-05-20T08:11:00Z :: session_turn :: ctn_20260520081100_5917efe2f4a20f97 :: did rotate_keys run 1\n- 2026-05-20T08:12:00Z :: session_turn :: ctn_20260520081200_3d2812bae9bdffbe :: did rotate_keys run 2\n',
    );
    // The journal is a transient repair marker, not a residue.
    expect(listSkillAcceptJournals(vault)).toHaveLength(0);
  });
});

describe("claimed evidence resolved against the recorded outcome ledger", () => {
  test("no recorded outcome, recorded successes and recorded failures stay three distinct states", () => {
    const slug = seedAndLearn("rotate_keys");
    acceptSkillProposal(vault, slug, { now: ACCEPTED_AT });
    const entryId = proceduralEntryId(`Brain/procedures/proc-${slug}.md`);

    // State 1 - nothing recorded. NOT "no failures": the rate is null.
    const fresh = resolveSkillProposalEvidence(vault, slug);
    expect(fresh.claimedEvidenceCount).toBe(3);
    expect(fresh.proceduralEntryId).toBe(entryId);
    expect(fresh.proceduralEntryPresent).toBe(true);
    expect(fresh.recordedSuccesses).toBe(0);
    expect(fresh.recordedFailures).toBe(0);
    expect(fresh.recordedSuccessRate).toBeNull();
    expect(fresh.outcomeState).toBe("unrecorded");

    // State 2 - recorded failures.
    expect(recordProceduralOutcome(vault, entryId, "failure")).not.toBeNull();
    const failing = resolveSkillProposalEvidence(vault, slug);
    expect(failing.recordedFailures).toBe(1);
    expect(failing.recordedSuccessRate).toBe(0);
    expect(failing.outcomeState).toBe("failing");

    // State 3 - recorded successes alongside them is a fourth, honest state.
    expect(recordProceduralOutcome(vault, entryId, "success")).not.toBeNull();
    const mixed = resolveSkillProposalEvidence(vault, slug);
    expect(mixed.recordedSuccesses).toBe(1);
    expect(mixed.recordedFailures).toBe(1);
    expect(mixed.outcomeState).toBe("mixed");

    // Success-only is distinguishable from all of the above.
    const other = seedAndLearnSecond();
    acceptSkillProposal(vault, other, { now: ACCEPTED_AT });
    const otherId = proceduralEntryId(`Brain/procedures/proc-${other}.md`);
    expect(recordProceduralOutcome(vault, otherId, "success")).not.toBeNull();
    const successful = resolveSkillProposalEvidence(vault, other);
    expect(successful.recordedSuccessRate).toBe(1);
    expect(successful.outcomeState).toBe("successful");
  });

  test("a pending proposal has no ledger entry, which is not the same as zero outcomes", () => {
    const slug = seedAndLearn("rotate_keys");
    const pending = resolveSkillProposalEvidence(vault, slug);
    expect(pending.phase).toBe("pending");
    expect(pending.proceduralEntryPresent).toBe(false);
    expect(pending.recordedSuccesses).toBeNull();
    expect(pending.recordedFailures).toBeNull();
    expect(pending.recordedSuccessRate).toBeNull();
    expect(pending.outcomeState).toBe("unrecorded");
  });

  test("an unknown slug raises a named error rather than an empty resolution", () => {
    expect(() => resolveSkillProposalEvidence(vault, "no-such-slug")).toThrow(
      /skill proposal not found in any phase: no-such-slug/,
    );
  });
});

/** Seed a second distinct pattern in the same vault; returns its slug. */
function seedAndLearnSecond(): string {
  const before = new Set(listPendingSkillProposals(vault).map((p) => p.slug));
  for (let i = 0; i < 3; i++) {
    const mm = String(20 + i).padStart(2, "0");
    appendContinuityRecord(vault, {
      kind: "session_turn",
      createdAt: `2026-05-21T08:${mm}:00Z`,
      sourceRefs: [{ id: `src-publish-${i}` }],
      payload: { action: "publish_release", summary: `did publish_release run ${i}` },
    });
  }
  learnSkillProposals(vault, { now: new Date("2026-06-02T09:00:00Z"), minSupport: 3 });
  const target = listPendingSkillProposals(vault).find(
    (p) => p.patternKind === "repeated_action" && !before.has(p.slug),
  );
  if (!target) throw new Error("test setup: no second repeated_action draft was created");
  return target.slug;
}

describe("the accept sequence survives a crash at each of its three gaps", () => {
  /**
   * Reproduce the on-disk state a crash would leave at `phase` by running a
   * real accept and then undoing the steps that would not yet have happened.
   */
  function crashAfter(slug: string, phase: "archive" | "materialize" | "commit"): void {
    const pendingPath = skillProposalPendingPath(vault, slug);
    const pendingBytes = readFileSync(pendingPath, "utf8");
    acceptSkillProposal(vault, slug, { now: ACCEPTED_AT });
    if (phase === "archive") {
      rmSync(procedurePath(vault, slug));
      writeFileSync(pendingPath, pendingBytes, "utf8");
    } else if (phase === "materialize") {
      writeFileSync(pendingPath, pendingBytes, "utf8");
    } else {
      rmSync(join(vault, "Brain", "procedural-memory"), { recursive: true, force: true });
    }
    writeSkillAcceptJournal(vault, {
      slug,
      id: `prop-${slug}`,
      phase,
      startedAt: ACCEPTED_AT.toISOString(),
      acceptedExisted: false,
      materializedExisted: false,
    });
  }

  test("gap 1 - crash before the procedure was written leaves no orphaned archive", () => {
    const slug = seedAndLearn("rotate_keys");
    crashAfter(slug, "archive");

    const recovered = recoverSkillProposalAccepts(vault);
    expect(recovered.map((r) => r.action)).toEqual(["rolled_back"]);
    expect(existsSync(skillProposalAcceptedPath(vault, slug))).toBe(false);
    expect(existsSync(procedurePath(vault, slug))).toBe(false);
    expect(existsSync(skillProposalPendingPath(vault, slug))).toBe(true);
    expect(listSkillAcceptJournals(vault)).toHaveLength(0);
  });

  test("gap 2 - crash before the pending copy was removed leaves no duplicate", () => {
    const slug = seedAndLearn("rotate_keys");
    crashAfter(slug, "materialize");
    // The duplicate is real before recovery: pending AND accepted both exist.
    expect(existsSync(skillProposalPendingPath(vault, slug))).toBe(true);
    expect(existsSync(skillProposalAcceptedPath(vault, slug))).toBe(true);

    const recovered = recoverSkillProposalAccepts(vault);
    expect(recovered.map((r) => r.action)).toEqual(["rolled_back"]);
    expect(existsSync(skillProposalAcceptedPath(vault, slug))).toBe(false);
    expect(existsSync(procedurePath(vault, slug))).toBe(false);
    expect(existsSync(skillProposalPendingPath(vault, slug))).toBe(true);
  });

  test("gap 3 - crash before the projections were rebuilt repairs them instead of leaving them stale", () => {
    const slug = seedAndLearn("rotate_keys");
    crashAfter(slug, "commit");
    expect(existsSync(proceduralMemoryIndexPath(vault))).toBe(false);

    const recovered = recoverSkillProposalAccepts(vault);
    expect(recovered.map((r) => r.action)).toEqual(["completed"]);
    // Rolled FORWARD: the pending copy is gone, so the accept had committed.
    expect(existsSync(skillProposalPendingPath(vault, slug))).toBe(false);
    expect(existsSync(skillProposalAcceptedPath(vault, slug))).toBe(true);
    expect(existsSync(procedurePath(vault, slug))).toBe(true);
    expect(
      listProceduralMemory(vault).some((e) => e.sourcePath === `Brain/procedures/proc-${slug}.md`),
    ).toBe(true);
    expect(listSkillAcceptJournals(vault)).toHaveLength(0);
  });

  test("an exception materializing the procedure rolls the archive back and clears the journal", () => {
    const slug = seedAndLearn("rotate_keys");
    // A procedure already at the target path makes the exclusive write throw.
    mkdirSync(dirname(procedurePath(vault, slug)), { recursive: true });
    writeFileSync(procedurePath(vault, slug), "---\nkind: brain-procedure\n---\n\n# Squatter\n", {
      encoding: "utf8",
    });

    expect(() => acceptSkillProposal(vault, slug, { now: ACCEPTED_AT })).toThrow(
      /procedure already exists/,
    );
    expect(existsSync(skillProposalAcceptedPath(vault, slug))).toBe(false);
    expect(existsSync(skillProposalPendingPath(vault, slug))).toBe(true);
    // The pre-existing file was NOT deleted by the rollback.
    expect(readFileSync(procedurePath(vault, slug), "utf8")).toContain("# Squatter");
    expect(listSkillAcceptJournals(vault)).toHaveLength(0);
  });

  test("a stale journal is swept by the next accept, not left for a human", () => {
    const slug = seedAndLearn("rotate_keys");
    crashAfter(slug, "materialize");
    const second = seedAndLearnSecond();

    acceptSkillProposal(vault, second, { now: ACCEPTED_AT });
    // Accepting an unrelated draft resolved the abandoned sequence.
    expect(existsSync(skillProposalAcceptedPath(vault, slug))).toBe(false);
    expect(existsSync(skillProposalPendingPath(vault, slug))).toBe(true);
    expect(existsSync(skillProposalAcceptedPath(vault, second))).toBe(true);
  });
});