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
32.2 KB
Raw Blame
/**
 * The one-off pledge page family (`Brain/pledges/`): a promise made in
 * prose, with a due date, a cited source page and evidence quotes verified
 * against that source at write time. Mirrors the recurring-obligation
 * family's CRUD discipline; the acceptance cases below are the ones the
 * wave plan pins for A1.
 */

import { afterEach, beforeEach, expect, setDefaultTimeout, spyOn, test } from "bun:test";
import * as fs from "node:fs";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  rmSync,
  statSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import {
  addPledge,
  fulfillPledge,
  listPledges,
  noPledgeError,
  pledgeExists,
  removePledge,
  showPledge,
  PledgeError,
} from "../../../src/core/brain/pledges.ts";
import { formatFrontmatter, parseFrontmatter } from "../../../src/core/vault.ts";
import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../../src/core/graph/visibility.ts";
import { acquireLockSync, LOCK_WAIT_BUDGET_ENV } from "../../../src/core/brain/sync-lockfile.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

const NOW = new Date("2026-06-19T12:00:00Z");

const SOURCE_REL = "notes/team-meeting.md";
const SOURCE_TEXT = [
  "We synced on the rollout plan.",
  "",
  "- Ada asked for a written recap of the migration steps.",
  "- The storage budget review moves to next quarter.",
  "",
  "Grace will review the incident timeline before Friday.",
].join("\n");

/** Every pledge in this suite cites this source page, so containment is real. */
function cite(evidence: string[]): Parameters<typeof addPledge>[1] {
  return {
    title: "Recap pledge",
    due: "2026-06-25",
    source: SOURCE_REL,
    evidence,
    agent: "test-agent",
    now: NOW,
  };
}

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "osb-pledges-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
  mkdirSync(join(vault, "notes"), { recursive: true });
  writeFileSync(join(vault, SOURCE_REL), SOURCE_TEXT, "utf8");
});

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

test("addPledge creates a page under Brain/pledges and reads back round-trip", () => {
  const page = addPledge(vault, {
    title: "Send Ada the migration recap",
    due: "2026-06-25",
    source: SOURCE_REL,
    evidence: ["Ada asked for a written recap of the migration steps"],
    text: "Send the written migration recap to Ada.",
    notes: "She asked twice.",
    counterparties: ["ent-people-ada"],
    agent: "test-agent",
    now: NOW,
  });
  expect(page.slug).toBe("send-ada-the-migration-recap");
  expect(page.path.endsWith(join("Brain", "pledges", "send-ada-the-migration-recap.md"))).toBe(
    true,
  );
  const raw = readFileSync(page.path, "utf8");
  for (const key of [
    "title:",
    "created_at:",
    "due:",
    "source:",
    "evidence:",
    "promised_to:",
    "fulfilled:",
    "agent:",
  ]) {
    expect(raw).toContain(key);
  }
  expect(raw).toContain("due: 2026-06-25");
  expect(pledgeExists(vault, page.slug)).toBe(true);

  const shown = showPledge(vault, { slug: page.slug });
  expect(shown).not.toBeNull();
  expect(shown!.title).toBe("Send Ada the migration recap");
  expect(shown!.due).toBe("2026-06-25");
  expect(shown!.source).toBe(SOURCE_REL);
  expect(shown!.evidence).toEqual(["Ada asked for a written recap of the migration steps"]);
  expect(shown!.counterparties).toEqual(["ent-people-ada"]);
  expect(shown!.fulfilled).toBeNull();
  expect(shown!.text).toBe("Send the written migration recap to Ada.");
  expect(shown!.notes).toBe("She asked twice.");
  expect(shown!.agent).toBe("test-agent");
  expect(shown!.createdAt).toBe("2026-06-19T12:00:00Z");
  // The round-trip alone would echo the injected instant even from a broken
  // formatter, so pin the canonical shape independently: whole-second UTC,
  // no milliseconds and no date-only fallback.
  expect(shown!.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/u);
  expect(raw).toMatch(/^created_at: "?\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z"?$/mu);
});

test("addPledge accepts a [[wikilink]] source reference and stores the vault path", () => {
  // A differently spelled source - backslash separators and surrounding
  // whitespace - proves normalization, where echoing the input would not.
  const page = addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    source: "  notes\\team-meeting.md  ",
  });
  expect(page.source).toBe(SOURCE_REL);
  const linked = addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Linked source pledge",
    source: `[[${SOURCE_REL}]]`,
  });
  expect(linked.source).toBe(SOURCE_REL);
});

test("addPledge refuses a taken slug with a named error", () => {
  addPledge(vault, cite(["Grace will review the incident timeline"]));
  let duplicate: unknown;
  try {
    addPledge(vault, cite(["Grace will review the incident timeline"]));
  } catch (err) {
    duplicate = err;
  }
  expect(duplicate).toBeInstanceOf(PledgeError);
  expect((duplicate as Error).name).toBe("PledgeError");
  expect(noPledgeError("x").name).toBe("PledgeError");
  expect(() => addPledge(vault, cite(["Grace will review the incident timeline"]))).toThrow(
    /pledge already exists: recap-pledge/,
  );
  expect(() => addPledge(vault, cite(["Grace will review the incident timeline"]))).toThrow(
    PledgeError,
  );
});

test("addPledge honors the pledge-path lock and still refuses a taken slug after release", () => {
  const path = join(vault, "Brain", "pledges", "recap-pledge.md");
  const held = acquireLockSync(path);
  const originalBudget = process.env[LOCK_WAIT_BUDGET_ENV];
  let collision: unknown;
  try {
    process.env[LOCK_WAIT_BUDGET_ENV] = "0";
    try {
      addPledge(vault, cite(["Grace will review the incident timeline"]));
    } catch (err) {
      collision = err;
    }
  } finally {
    held.release();
    if (originalBudget === undefined) delete process.env[LOCK_WAIT_BUDGET_ENV];
    else process.env[LOCK_WAIT_BUDGET_ENV] = originalBudget;
  }
  expect((collision as NodeJS.ErrnoException | undefined)?.code).toBe("ELOCKED");
  expect(existsSync(path)).toBe(false);
  const page = addPledge(vault, cite(["Grace will review the incident timeline"]));
  const before = readFileSync(page.path, "utf8");
  expect(() => addPledge(vault, cite(["Grace will review the incident timeline"]))).toThrow(
    PledgeError,
  );
  expect(readFileSync(page.path, "utf8")).toBe(before);
  expect(existsSync(`${path}.lock`)).toBe(false);
});

test("addPledge refuses a missing, empty or non-ISO due date", () => {
  const withoutDue = {
    title: "Recap pledge",
    source: SOURCE_REL,
    evidence: ["Grace will review the incident timeline"],
    agent: "test-agent",
    now: NOW,
  } as unknown as Parameters<typeof addPledge>[1];
  expect(() => addPledge(vault, withoutDue)).toThrow(PledgeError);
  expect(() => addPledge(vault, withoutDue)).toThrow(/due is not a valid calendar date: undefined/);
  expect(() =>
    addPledge(vault, {
      ...cite(["Grace will review the incident timeline"]),
      due: "",
    }),
  ).toThrow(PledgeError);
  expect(() =>
    addPledge(vault, {
      ...cite(["Grace will review the incident timeline"]),
      due: "",
    }),
  ).toThrow(/due is not a valid calendar date: ""/);
  expect(() =>
    addPledge(vault, {
      ...cite(["Grace will review the incident timeline"]),
      due: "2026-13-40",
    }),
  ).toThrow(/not a valid calendar date/);
  expect(() =>
    addPledge(vault, {
      ...cite(["Grace will review the incident timeline"]),
      due: "next Friday",
    }),
  ).toThrow(PledgeError);
  // The due check runs before the lock and the write: no page, and not even
  // the pledges directory, may exist after any of these refusals.
  expect(pledgeExists(vault, "recap-pledge")).toBe(false);
  expect(existsSync(join(vault, "Brain", "pledges"))).toBe(false);
});

test("addPledge refuses an empty evidence list", () => {
  expect(() => addPledge(vault, { ...cite([]) })).toThrow(/evidence/);
  expect(() => addPledge(vault, { ...cite(["   "]) })).toThrow(/evidence/);
});

test("addPledge refuses a quote absent from the source page", () => {
  expect(() => addPledge(vault, { ...cite(["The board approved unlimited headcount"]) })).toThrow(
    /does not occur in the source page/,
  );
  expect(() => addPledge(vault, { ...cite(["The board approved unlimited headcount"]) })).toThrow(
    PledgeError,
  );
});

test("addPledge refuses a source page the vault does not hold", () => {
  expect(() =>
    addPledge(vault, {
      title: "Ghost source",
      due: "2026-06-25",
      source: "notes/absent.md",
      evidence: ["anything"],
      agent: "a",
      now: NOW,
    }),
  ).toThrow(/source page not found/);
});

test("addPledge refuses a source path that names a directory with the same named error", () => {
  // A directory exists, so the existence probe alone would let the read
  // through and the failure would surface as a raw fs error past the
  // typed error boundary.
  expect(() =>
    addPledge(vault, {
      title: "Directory source",
      due: "2026-06-25",
      source: "notes",
      evidence: ["anything"],
      agent: "a",
      now: NOW,
    }),
  ).toThrow(PledgeError);
  expect(() =>
    addPledge(vault, {
      title: "Directory source",
      due: "2026-06-25",
      source: "notes",
      evidence: ["anything"],
      agent: "a",
      now: NOW,
    }),
  ).toThrow(/source page not found/);
});

test("addPledge refuses an unreadable source before reading it", () => {
  // Reading this directory as a page would throw EISDIR instead of the reach refusal.
  rmSync(join(vault, SOURCE_REL));
  mkdirSync(join(vault, SOURCE_REL));
  const checked: string[] = [];
  const input = {
    ...cite(["Grace will review the incident timeline"]),
    source: `[[${SOURCE_REL}]]`,
    readable: (rel: string) => {
      checked.push(rel);
      return false;
    },
  };
  const refuse = () => addPledge(vault, input);
  expect(refuse).toThrow(PledgeError);
  expect(refuse).toThrow(/source page is not readable or absent/);
  expect(checked).toEqual([SOURCE_REL, SOURCE_REL]);
  expect(pledgeExists(vault, "recap-pledge")).toBe(false);
});

test("addPledge inherits source visibility and omits it for public sources", () => {
  const publicPage = addPledge(vault, cite(["Grace will review the incident timeline"]));
  expect(parseFrontmatter(publicPage.path)[0]).not.toHaveProperty("visibility");
  writeFileSync(
    join(vault, SOURCE_REL),
    `---\nvisibility: ${REMOTE_DENY_VISIBILITY_TOKEN}\n---\n\n${SOURCE_TEXT}`,
  );
  const privatePage = addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Private-source pledge",
  });
  expect(parseFrontmatter(privatePage.path)[0]["visibility"]).toEqual([
    REMOTE_DENY_VISIBILITY_TOKEN,
  ]);
});

test("addPledge inherits an informal privacy marker from the source", () => {
  // No `visibility:` key - the reservation is stated only under the
  // pre-convention informal key, and the evidence quotes the source, so
  // the derived page must inherit the reservation through the union.
  writeFileSync(join(vault, SOURCE_REL), `---\naccess: private\n---\n\n${SOURCE_TEXT}`, "utf8");
  const page = addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Marker-source pledge",
  });
  expect(parseFrontmatter(page.path)[0]["visibility"]).toEqual([REMOTE_DENY_VISIBILITY_TOKEN]);
});

test("evidence containment forgives presentation, never wording", () => {
  // The shared comparator strips Markdown emphasis and line markers, so a
  // quote over a list item or emphasis passes; wording and word boundaries
  // never bend ("view" must not verify inside "review").
  const page = addPledge(vault, cite(["budget review moves to next quarter"]));
  expect(page.evidence).toEqual(["budget review moves to next quarter"]);
  expect(() => addPledge(vault, { ...cite(["view moves to next quarter"]) })).toThrow(PledgeError);
});

test("addPledge refuses a forged notes header in text or notes without writing", () => {
  for (const field of ["text", "notes"] as const) {
    for (const header of ["## Notes", "  ## Notes  "]) {
      expect(() =>
        addPledge(vault, {
          ...cite(["Grace will review the incident timeline"]),
          [field]: `Promise line one.\n${header}\nPromise line two.`,
        }),
      ).toThrow(PledgeError);
      expect(pledgeExists(vault, "recap-pledge")).toBe(false);
    }
  }
});

test("addPledge refuses an empty title", () => {
  expect(() =>
    addPledge(vault, { ...cite(["Grace will review the incident timeline"]), title: "   " }),
  ).toThrow(/title must not be empty/);
});

test("fulfillPledge stamps the fulfillment date and refuses a second stamp", () => {
  addPledge(vault, cite(["Ada asked for a written recap of the migration steps"]));
  const done = fulfillPledge(vault, { slug: "recap-pledge", date: "2026-06-20" });
  expect(done.fulfilled).toBe("2026-06-20");
  expect(showPledge(vault, { slug: "recap-pledge" })!.fulfilled).toBe("2026-06-20");
  expect(() => fulfillPledge(vault, { slug: "recap-pledge" })).toThrow(/already fulfilled/);
});

test("fulfill preserves visibility and unknown frontmatter keys", () => {
  const page = addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    text: "Review the timeline.",
    notes: "Keep the record.",
  });
  const [meta, body] = parseFrontmatter(page.path);
  meta["visibility"] = [REMOTE_DENY_VISIBILITY_TOKEN];
  meta["review_marker"] = ["hand-added", "retain"];
  meta["owner"] = "operator";
  writeFileSync(page.path, formatFrontmatter(meta, body));
  fulfillPledge(vault, { slug: page.slug, date: "2026-06-20" });
  const [after, afterBody] = parseFrontmatter(page.path);
  expect(after).toEqual({ ...meta, fulfilled: "2026-06-20" });
  expect(afterBody).toBe(body);
});

test("fulfillPledge defaults the date to the injected now and shares the no-pledge refusal", () => {
  addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Timeline pass",
  });
  const done = fulfillPledge(vault, { slug: "timeline-pass", now: NOW });
  expect(done.fulfilled).toBe("2026-06-19");
  expect(() => fulfillPledge(vault, { slug: "ghost" })).toThrow(noPledgeError("ghost"));
  expect(() => removeAbsentPledge()).toThrow(/no pledge: ghost/);
});

// The no-pledge refusal is one named error shared by every slug-addressed
// operation; this helper keeps that assertion next to the error import.
function removeAbsentPledge(): unknown {
  return removePledge(vault, { slug: "ghost" });
}

test("listPledges sorts by due then slug with overdue and daysUntilDue boundaries", () => {
  addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Beta yesterday",
    due: "2026-06-18",
  });
  addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Alpha yesterday",
    due: "2026-06-18",
  });
  addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Today item",
    due: "2026-06-19",
  });
  addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Tomorrow item",
    due: "2026-06-20",
  });

  for (const title of ["Zeta undated", "Alpha undated"]) {
    const page = addPledge(vault, {
      ...cite(["Grace will review the incident timeline"]),
      title,
    });
    writeFileSync(
      page.path,
      readFileSync(page.path, "utf8").replace(`due: ${page.due}`, "due: invalid"),
    );
  }

  const items = listPledges(vault, { now: NOW });
  expect(items.map((i) => i.slug)).toEqual([
    "alpha-yesterday",
    "beta-yesterday",
    "today-item",
    "tomorrow-item",
    "alpha-undated",
    "zeta-undated",
  ]);
  expect(items[0]!.overdue).toBe(true);
  expect(items[0]!.daysUntilDue).toBe(-1);
  expect(items[1]!.overdue).toBe(true);
  expect(items[2]!.overdue).toBe(false);
  expect(items[2]!.daysUntilDue).toBe(0);
  expect(items[3]!.daysUntilDue).toBe(1);
  expect(items[4]!.daysUntilDue).toBeNull();
  expect(items[4]!.overdue).toBe(false);
  expect(items[5]!.daysUntilDue).toBeNull();
  expect(items[0]!.title).toBe("Alpha yesterday");
  expect(items[0]!.source).toBe(SOURCE_REL);
});

test("listPledges hides fulfilled pledges unless includeFulfilled", () => {
  addPledge(vault, { ...cite(["Grace will review the incident timeline"]), title: "Done deal" });
  addPledge(vault, { ...cite(["Grace will review the incident timeline"]), title: "Still open" });
  fulfillPledge(vault, { slug: "done-deal", date: "2026-06-19" });
  expect(listPledges(vault, { now: NOW }).map((i) => i.slug)).toEqual(["still-open"]);
  const withDone = listPledges(vault, { now: NOW, includeFulfilled: true });
  expect(withDone.map((i) => i.slug).toSorted()).toEqual(["done-deal", "still-open"]);
  expect(withDone.find((i) => i.slug === "done-deal")!.fulfilled).toBe("2026-06-19");
});

test("fulfillPledge honors the pledge-path lock across its read and write", () => {
  // The stamp is a read-modify-write of the whole frontmatter: holding the
  // page's lock must hold the writer off, or a fulfill racing the intake's
  // re-anchor rewrite can silently drop one of the two edits.
  const page = addPledge(vault, cite(["Grace will review the incident timeline"]));
  const held = acquireLockSync(page.path);
  const originalBudget = process.env[LOCK_WAIT_BUDGET_ENV];
  let collision: unknown;
  try {
    process.env[LOCK_WAIT_BUDGET_ENV] = "0";
    try {
      fulfillPledge(vault, { slug: page.slug });
    } catch (err) {
      collision = err;
    }
  } finally {
    held.release();
    if (originalBudget === undefined) delete process.env[LOCK_WAIT_BUDGET_ENV];
    else process.env[LOCK_WAIT_BUDGET_ENV] = originalBudget;
  }
  expect((collision as NodeJS.ErrnoException | undefined)?.code).toBe("ELOCKED");
  expect(showPledge(vault, { slug: page.slug })!.fulfilled).toBeNull();
  fulfillPledge(vault, { slug: page.slug, date: "2026-06-19" });
  expect(showPledge(vault, { slug: page.slug })!.fulfilled).toBe("2026-06-19");
});

test("listPledges reports a fulfilled past-due pledge as not overdue", () => {
  addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Late but done",
    due: "2026-06-10",
  });
  fulfillPledge(vault, { slug: "late-but-done", date: "2026-06-18" });
  const items = listPledges(vault, { now: NOW, includeFulfilled: true });
  expect(items).toHaveLength(1);
  expect(items[0]!.fulfilled).toBe("2026-06-18");
  // Overdue is a fact about an OPEN promise: a done pledge reports false
  // however long past its due date, so an overdue filter never shows it.
  expect(items[0]!.overdue).toBe(false);
  // The calendar delta itself is unchanged: nine days past due.
  expect(items[0]!.daysUntilDue).toBe(-9);
});

test("removePledge honors the pledge-path lock across the archive move", () => {
  const page = addPledge(vault, cite(["Grace will review the incident timeline"]));
  const held = acquireLockSync(page.path);
  const originalBudget = process.env[LOCK_WAIT_BUDGET_ENV];
  let collision: unknown;
  try {
    process.env[LOCK_WAIT_BUDGET_ENV] = "0";
    try {
      removePledge(vault, { slug: page.slug });
    } catch (err) {
      collision = err;
    }
  } finally {
    held.release();
    if (originalBudget === undefined) delete process.env[LOCK_WAIT_BUDGET_ENV];
    else process.env[LOCK_WAIT_BUDGET_ENV] = originalBudget;
  }
  expect((collision as NodeJS.ErrnoException | undefined)?.code).toBe("ELOCKED");
  expect(pledgeExists(vault, page.slug)).toBe(true);
});

test("removePledge names the absent pledge when the page vanishes under the lock", async () => {
  // Two removers can pass an existence probe taken before the lock and then
  // race the archive move: the winner renames the page, and the loser's
  // fallback reads the vanished file. The refusal must be the shared named
  // no-pledge error, not the fallback arm's raw ENOENT.
  const page = addPledge(vault, cite(["Grace will review the incident timeline"]));
  const child = join(vault, "remove-pledge.ts");
  writeFileSync(
    child,
    [
      `import { removePledge } from ${JSON.stringify(join(import.meta.dir, "../../../src/core/brain/pledges.ts"))};`,
      "const [vault, slug] = process.argv.slice(2);",
      "try {",
      "  removePledge(vault, { slug });",
      "  console.log(JSON.stringify({ ok: true }));",
      "} catch (err) {",
      "  const e = err;",
      "  console.log(JSON.stringify({ ok: false, name: e.name, message: e.message, code: e.code ?? null }));",
      "}",
    ].join("\n"),
    "utf8",
  );

  const held = acquireLockSync(page.path);
  const baseSize = statSync(`${page.path}.lock`).size;
  const proc = Bun.spawn(["bun", child, vault, page.slug], {
    stdout: "pipe",
    stderr: "pipe",
    env: { ...process.env },
  });
  let exitCode = -1;
  let stdout = "";
  let stderr = "";
  try {
    // The child's probe passes, then it queues on the pledge lock; only then
    // does the page disappear, exactly as the winning remover leaves it.
    const until = Date.now() + 20_000;
    while (statSync(`${page.path}.lock`).size <= baseSize) {
      if (Date.now() > until || proc.exitCode !== null) {
        throw new Error("the remover never reached the pledge lock");
      }
      // oxlint-disable-next-line no-await-in-loop -- polling the child's progress, one wait at a time by design
      await Bun.sleep(5);
    }
    rmSync(page.path);
    held.release();
  } finally {
    held.release();
    exitCode = await proc.exited;
    stdout = await new Response(proc.stdout).text();
    stderr = await new Response(proc.stderr).text();
  }

  expect(stderr.trim()).toBe("");
  expect(exitCode).toBe(0);
  const outcome = JSON.parse(stdout) as {
    ok: boolean;
    name?: string;
    message?: string;
    code?: string | null;
  };
  expect(outcome.ok).toBe(false);
  expect(outcome.name).toBe("PledgeError");
  expect(outcome.message).toBe(`no pledge: ${page.slug}`);
  expect(outcome.code).toBeNull();
}, 60_000);

test("a hand-edited frontmatter date soft-parses instead of crashing the family", () => {
  const page = addPledge(vault, cite(["Ada asked for a written recap of the migration steps"]));
  const edited = readFileSync(page.path, "utf8").replace(`due: ${page.due}`, "due: not-a-date");
  writeFileSync(page.path, edited, "utf8");
  const shown = showPledge(vault, { slug: page.slug });
  expect(shown!.due).toBe("");
  const items = listPledges(vault, { now: NOW });
  expect(items).toHaveLength(1);
  expect(items[0]!.due).toBe("");
  expect(items[0]!.daysUntilDue).toBeNull();
  expect(items[0]!.overdue).toBe(false);
});

test("removePledge archives the page and a recreated slug archives with a collision suffix", () => {
  const first = addPledge(vault, cite(["Ada asked for a written recap of the migration steps"]));
  const removed = removePledge(vault, { slug: first.slug });
  expect(existsSync(first.path)).toBe(false);
  expect(existsSync(removed.archivePath)).toBe(true);
  expect(removed.slug).toBe(first.slug);
  expect(removed.archivePath.endsWith(join("Brain", "pledges", "archive", "recap-pledge.md"))).toBe(
    true,
  );
  expect(showPledge(vault, { slug: first.slug })).toBeNull();
  expect(pledgeExists(vault, first.slug)).toBe(false);

  const second = addPledge(vault, cite(["Ada asked for a written recap of the migration steps"]));
  expect(second.slug).toBe(first.slug);
  const again = removePledge(vault, { slug: second.slug });
  expect(existsSync(again.archivePath)).toBe(true);
  expect(again.archivePath.endsWith(join("recap-pledge-2.md"))).toBe(true);
});

test("removePledge throws the shared no-pledge refusal for an unknown slug", () => {
  expect(() => removePledge(vault, { slug: "ghost" })).toThrow(noPledgeError("ghost"));
});

test("a withheld pledge page answers show as null and drops from list", () => {
  const page = addPledge(vault, cite(["Ada asked for a written recap of the migration steps"]));
  const rel = `Brain/pledges/${page.slug}.md`;
  expect(showPledge(vault, { slug: page.slug, readable: (r) => r !== rel })).toBeNull();
  expect(showPledge(vault, { slug: page.slug, readable: () => true })).not.toBeNull();
  expect(showPledge(vault, { slug: page.slug })).not.toBeNull();
  expect(listPledges(vault, { now: NOW, readable: (r) => r !== rel })).toEqual([]);
  const kept = listPledges(vault, { now: NOW, readable: () => true });
  expect(kept).toHaveLength(1);
  expect(kept[0]!.slug).toBe(page.slug);
});

test("listPledges readCap bounds readable page reads in stable name order", () => {
  for (const title of ["Echo", "Delta", "Charlie", "Bravo", "Alpha"]) {
    addPledge(vault, { ...cite(["Grace will review the incident timeline"]), title });
  }
  expect(listPledges(vault, { now: NOW, readCap: 2 }).map((item) => item.slug)).toEqual([
    "alpha",
    "bravo",
  ]);
  expect(listPledges(vault, { now: NOW, readCap: 0 })).toEqual([]);
  fulfillPledge(vault, { slug: "bravo", date: "2026-06-20" });
  // Withheld pages spend no reads; a fulfilled page the filter drops spends
  // no read budget either, so the cap still admits the next two open pages.
  expect(
    listPledges(vault, {
      now: NOW,
      readCap: 2,
      readable: (rel) => rel !== "Brain/pledges/alpha.md",
    }).map((item) => item.slug),
  ).toEqual(["charlie", "delta"]);
  expect(listPledges(vault, { now: NOW }).map((item) => item.slug)).toEqual([
    "alpha",
    "charlie",
    "delta",
    "echo",
  ]);
});

test("listPledges readCap counts only the pages the open-only filter keeps", () => {
  // The active directory keeps every fulfilled pledge in place, so a run of
  // fulfilled pages that sort before an open one must not consume the whole
  // window: the counterparty brief's pledge arm reads through listPledges
  // under a 24-page cap, and fulfilled pages filling it would hide every
  // open promise behind them.
  for (let index = 0; index < 24; index++) {
    const page = addPledge(vault, {
      ...cite(["Grace will review the incident timeline"]),
      title: `A${String(index).padStart(2, "0")} done`,
      due: "2026-06-01",
    });
    fulfillPledge(vault, { slug: page.slug, date: "2026-06-02" });
  }
  addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Z ship the parser",
    due: "2026-07-01",
  });
  expect(listPledges(vault, { now: NOW, readCap: 24 }).map((item) => item.slug)).toEqual([
    "z-ship-the-parser",
  ]);
});

/**
 * How many of the recorded fs reads named a page under `Brain/pledges/`:
 * the page parses the walk spends on that page, counted on any platform's
 * separators.
 */
const pledgePageReads = (calls: ReadonlyArray<ReadonlyArray<unknown>>): number =>
  calls.filter((args) => String(args[0]).replaceAll("\\", "/").includes("/Brain/pledges/")).length;

test("listPledges scanCap bounds the pages one call parses", () => {
  // The scan ceiling bounds the FILESYSTEM work, not only the kept window:
  // the walk parses at most scanCap pages, so the reads cannot grow with
  // the number of pledge pages on disk.
  for (const title of ["Alpha", "Bravo", "Charlie", "Delta", "Echo"]) {
    addPledge(vault, { ...cite(["Grace will review the incident timeline"]), title });
  }
  const read = spyOn(fs, "readFileSync");
  try {
    const kept = listPledges(vault, { now: NOW, readCap: 10, scanCap: 2 });
    // Two pages parsed, two pages kept: the kept window (10) never bound
    // here, the scan ceiling did.
    expect(pledgePageReads(read.mock.calls)).toBe(2);
    expect(kept.map((item) => item.slug)).toEqual(["alpha", "bravo"]);
  } finally {
    read.mockRestore();
  }
});

test("listPledges scanCap charges a dropped page and leaves the kept window alone", () => {
  // A fulfilled page the walk parses and then drops still spends the scan
  // budget, so the open promise behind it is never parsed. The kept
  // window on its own is unchanged: the same open promise is still the
  // one the call returns.
  for (let index = 0; index < 3; index++) {
    const page = addPledge(vault, {
      ...cite(["Grace will review the incident timeline"]),
      title: `A${index} done`,
      due: "2026-06-01",
    });
    fulfillPledge(vault, { slug: page.slug, date: "2026-06-02" });
  }
  addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Z ship the parser",
    due: "2026-07-01",
  });
  const read = spyOn(fs, "readFileSync");
  try {
    const kept = listPledges(vault, { now: NOW, readCap: 24, scanCap: 3 });
    expect(pledgePageReads(read.mock.calls)).toBe(3);
    expect(kept).toEqual([]);
  } finally {
    read.mockRestore();
  }
  expect(listPledges(vault, { now: NOW, readCap: 24 }).map((item) => item.slug)).toEqual([
    "z-ship-the-parser",
  ]);
});

test("listPledges scanCap does not charge a page the readable predicate refuses", () => {
  // A withheld page is never parsed, so it spends no scan budget: the open
  // promises behind it are still parsed, and still kept.
  addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "A withheld",
  });
  for (const title of ["B open", "C open"]) {
    addPledge(vault, { ...cite(["Grace will review the incident timeline"]), title });
  }
  const read = spyOn(fs, "readFileSync");
  try {
    const kept = listPledges(vault, {
      now: NOW,
      readCap: 10,
      scanCap: 2,
      readable: (rel) => rel !== "Brain/pledges/a-withheld.md",
    });
    expect(pledgePageReads(read.mock.calls)).toBe(2);
    expect(kept.map((item) => item.slug)).toEqual(["b-open", "c-open"]);
  } finally {
    read.mockRestore();
  }
});

test("two titles differing only in diacritics land as distinct pages", () => {
  // `slugify` folds every non-ASCII letter into a separator, so Müller and
  // Möller share one title slug. Promises to different people are the
  // family's core use case: the second add files under an identity suffix
  // instead of refusing or overwriting the first page.
  const muller = addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Ship the parser to Müller",
  });
  const moeller = addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Ship the parser to Möller",
  });
  expect(muller.slug).toBe("ship-the-parser-to-m-ller");
  expect(moeller.slug).toMatch(/^ship-the-parser-to-m-ller-[0-9a-f]{6}$/u);
  expect(showPledge(vault, { slug: muller.slug })!.title).toBe("Ship the parser to Müller");
  expect(showPledge(vault, { slug: moeller.slug })!.title).toBe("Ship the parser to Möller");
  // A true duplicate keeps the family's taken-slug refusal: identity, not
  // title-suffix chance, decides what is a repeat.
  expect(() =>
    addPledge(vault, {
      ...cite(["Grace will review the incident timeline"]),
      title: "Ship the parser to Müller",
    }),
  ).toThrow(/pledge already exists: ship-the-parser-to-m-ller/);
  expect(listPledges(vault, { now: NOW })).toHaveLength(2);
});

test("a re-post of a suffix-filed pledge refuses once the title slug's holder is gone", () => {
  // The unblocked re-post is the trap: the freed base slug invites a second
  // page for an identity that already lives at the suffix, so the
  // true-duplicate check has to run across ALL candidates before any create.
  const muller = addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Ship the parser to Müller",
  });
  const moeller = addPledge(vault, {
    ...cite(["Grace will review the incident timeline"]),
    title: "Ship the parser to Möller",
  });
  removePledge(vault, { slug: muller.slug });
  expect(() =>
    addPledge(vault, {
      ...cite(["Grace will review the incident timeline"]),
      title: "Ship the parser to Möller",
    }),
  ).toThrow(/pledge already exists: /);
  expect(showPledge(vault, { slug: muller.slug })).toBeNull();
  expect(showPledge(vault, { slug: moeller.slug })).not.toBeNull();
  expect(listPledges(vault, { now: NOW })).toHaveLength(1);
});

test("listPledges answers an empty list for a vault without the pledges directory", () => {
  // The fixture never creates Brain/pledges/, so the empty answer is only
  // attributable to the missing directory if the same call finds a page once
  // that directory exists.
  expect(existsSync(join(vault, "Brain", "pledges"))).toBe(false);
  expect(listPledges(vault, { now: NOW })).toEqual([]);

  addPledge(vault, cite(["Grace will review the incident timeline"]));
  expect(existsSync(join(vault, "Brain", "pledges"))).toBe(true);
  expect(listPledges(vault, { now: NOW }).map((item) => item.slug)).toEqual(["recap-pledge"]);
});