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
24.3 KB
Raw Blame
/**
 * Batch-plan step (A3, t_9eeb8ca2). `planBatches` discovers ingestible files
 * under a source dir, consults A1's content-hash manifest to skip `unchanged`
 * sources, then splits the `new`/`modified` remainder into size+count-bounded
 * batches an agent/CLI can dispatch as parallel subagents. The kernel runs no
 * ingestion here - it only plans. The plan is deterministic (sort by path, fill
 * greedily to the byte cap then the count cap).
 */

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

import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
import {
  hashFile,
  readManifest,
  updateManifest,
} from "../../../../src/core/brain/ingest/content-manifest.ts";
import {
  DEFAULT_INGESTIBLE_EXTENSIONS as PLANNER_DEFAULT_EXTENSIONS,
  planBatches,
  type BatchPlan,
} from "../../../../src/core/brain/ingest/batch-plan.ts";
import { DEFAULT_INGESTIBLE_EXTENSIONS } from "../../../../src/core/brain/ingest/source-formats.ts";
import { recordCompleted } from "../../../../src/core/brain/ingest/checkpoint.ts";
import { SKIPPED_PAGE_REASON } from "../../../../src/core/brain/ingest/extractable-gate.ts";
import { serializeBatchPlan } from "../../../../src/mcp/brain/ingest-tools.ts";

let vault: string;
let configHome: string;

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

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

/** Write a source file of exactly `bytes` bytes (ASCII "x" fill). */
function writeSized(rel: string, bytes: number): void {
  const abs = join(vault, rel);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(abs, "x".repeat(bytes), "utf8");
}

function allPlannedPaths(plan: ReturnType<typeof planBatches>): string[] {
  return plan.batches.flatMap((b) => b.files.map((f) => f.path));
}

const CAPS = { maxBatchBytes: 10_000, maxBatchFiles: 100 } as const;

/**
 * Mark one recorded manifest entry `retired_into` the given canonical page,
 * the way the retirement core does: the pinned record keeps the digest and
 * fingerprint it was recorded under and gains the marker.
 */
function markRetired(vaultDir: string, rel: string, canonicalPage: string): void {
  const recorded = readManifest(vaultDir).entries[rel];
  if (recorded === undefined) throw new Error(`fixture bug: ${rel} is not in the manifest`);
  updateManifest(vaultDir, [rel], {
    [rel]: { ...recorded, retired_into: canonicalPage },
  });
}

/** Write a page carrying an optional `schema_type` frontmatter field. */
function page(rel: string, schemaType?: string): void {
  const abs = join(vault, rel);
  mkdirSync(join(abs, ".."), { recursive: true });
  const fm = schemaType === undefined ? "" : `schema_type: ${schemaType}\n`;
  writeFileSync(abs, `---\ntitle: ${rel}\n${fm}---\n\nbody text\n`, "utf8");
}

/** Point the schema pack at an `extractable` allowlist (gates discovery). */
function setExtractable(tokens: string[]): void {
  const block = tokens.map((t) => `    - ${t}`).join("\n");
  writeFileSync(
    join(vault, "Brain", "_brain.yaml"),
    `schema_version: 1\nschema:\n  page_types:\n    - paper\n    - memo\n  extractable:\n${block}\n`,
    "utf8",
  );
}

describe("planBatches — discovery + skip-unchanged", () => {
  test("skips `unchanged` files (via the manifest) and plans only new/modified", () => {
    writeSized("Inbox/keep.md", 100);
    writeSized("Inbox/edit.md", 100);
    writeSized("Inbox/fresh.md", 100);
    // Seed the manifest for keep + edit, then modify edit so it re-classifies.
    updateManifest(vault, ["Inbox/keep.md", "Inbox/edit.md"]);
    writeSized("Inbox/edit.md", 120);

    const plan = planBatches(vault, "Inbox", { maxBatchBytes: 10_000, maxBatchFiles: 100 });

    // keep is unchanged → skipped, never batched.
    expect(plan.skipped).toEqual(["Inbox/keep.md"]);
    const planned = allPlannedPaths(plan);
    expect(planned).toContain("Inbox/edit.md"); // modified
    expect(planned).toContain("Inbox/fresh.md"); // new
    expect(planned).not.toContain("Inbox/keep.md");
    expect(plan.totalFiles).toBe(2);
  });

  test("a retired source whose bytes are unchanged is never queued", () => {
    // The resurrect guard (H3): a near-duplicate retirement marks the
    // entry `retired_into` instead of dropping it, and the planner skips
    // the marked entry while its bytes stay unchanged.
    writeSized("Inbox/retired.md", 100);
    writeSized("Inbox/live.md", 100);
    updateManifest(vault, ["Inbox/retired.md", "Inbox/live.md"]);
    markRetired(vault, "Inbox/retired.md", "Brain/sources/src-live.md");

    const plan = planBatches(vault, "Inbox", CAPS);
    // Both recorded sources are queued-out: the plain-unchanged one through
    // the ordinary skip, the retired one through the resurrect guard.
    expect(allPlannedPaths(plan)).toEqual([]);
    expect(plan.skipped).toEqual(["Inbox/live.md"]);
    expect(plan.skippedRetired).toEqual(["Inbox/retired.md"]);

    // A content change re-admits the retired source as `modified`.
    writeSized("Inbox/retired.md", 120);
    const changed = planBatches(vault, "Inbox", CAPS);
    expect(allPlannedPaths(changed)).toContain("Inbox/retired.md");
    expect(changed.skippedRetired).toEqual([]);
  });

  test("a retired source stays queued-out even under a changed contract", () => {
    // A contract change reprocesses `unchanged` sources; a retirement is
    // not a content change, so the marked entry keeps its skip.
    setExtractable(["paper"]);
    writeSized("Inbox/retired.md", 100);
    page("Inbox/retired.md", "paper");
    updateManifest(vault, ["Inbox/retired.md"]);
    markRetired(vault, "Inbox/retired.md", "Brain/sources/src-elsewhere.md");
    // Widen the allowlist: the contract changes, the bytes do not.
    setExtractable(["paper", "memo"]);

    const plan = planBatches(vault, "Inbox", CAPS);
    expect(plan.contractChanged).toBe(true);
    expect(allPlannedPaths(plan)).toEqual([]);
    expect(plan.skippedRetired).toEqual(["Inbox/retired.md"]);
  });

  test("the wire carries skipped_retired only when non-empty", () => {
    writeSized("Docs/a.md", 50);
    updateManifest(vault, ["Docs/a.md"]);

    // No retired entry: byte-identical to the pre-H3 wire shape.
    const plain = serializeBatchPlan(planBatches(vault, "Docs", CAPS));
    expect(Object.keys(plain)).not.toContain("skipped_retired");

    markRetired(vault, "Docs/a.md", "Brain/sources/src-a.md");
    const wire = serializeBatchPlan(planBatches(vault, "Docs", CAPS));
    expect(wire["skipped_retired"]).toEqual(["Docs/a.md"]);
    expect(wire["total_files"]).toBe(0);
  });

  test("only ingestible (text-bearing) files are discovered; binaries/media ignored", () => {
    writeSized("Docs/a.md", 50);
    writeSized("Docs/b.txt", 50);
    writeSized("Docs/image.png", 50);
    writeSized("Docs/archive.zip", 50);

    const plan = planBatches(vault, "Docs", { maxBatchBytes: 10_000, maxBatchFiles: 100 });
    const planned = allPlannedPaths(plan).toSorted();
    expect(planned).toEqual(["Docs/a.md", "Docs/b.txt"]);
  });

  test("hidden files and dot-directories are not discovered", () => {
    writeSized("Notes/real.md", 50);
    writeSized("Notes/.secret.md", 50);
    writeSized("Notes/.git/config.md", 50);

    const plan = planBatches(vault, "Notes", { maxBatchBytes: 10_000, maxBatchFiles: 100 });
    expect(allPlannedPaths(plan)).toEqual(["Notes/real.md"]);
  });
});

describe("planBatches — bounded batches", () => {
  test("no batch exceeds the byte cap or the file-count cap", () => {
    // 6 files of 100 bytes each. Byte cap 250 → at most 2 per batch (200 ok,
    // 300 would exceed). File cap 5 is looser, so the byte cap governs here.
    for (let i = 0; i < 6; i++) writeSized(`Big/f${i}.md`, 100);

    const plan = planBatches(vault, "Big", { maxBatchBytes: 250, maxBatchFiles: 5 });
    expect(plan.totalFiles).toBe(6);
    for (const b of plan.batches) {
      expect(b.totalBytes).toBeLessThanOrEqual(250);
      expect(b.files.length).toBeLessThanOrEqual(5);
    }
    // Every file lands in exactly one batch.
    expect(allPlannedPaths(plan).length).toBe(6);
  });

  test("file-count cap governs when it is tighter than the byte cap", () => {
    for (let i = 0; i < 5; i++) writeSized(`Small/f${i}.md`, 10);

    const plan = planBatches(vault, "Small", { maxBatchBytes: 1_000_000, maxBatchFiles: 2 });
    // 5 files, cap 2 → batches of 2, 2, 1.
    expect(plan.batches.map((b) => b.files.length)).toEqual([2, 2, 1]);
  });

  test("a single file larger than the byte cap forms its own singleton batch", () => {
    writeSized("Huge/small.md", 10);
    writeSized("Huge/whale.md", 5_000);

    const plan = planBatches(vault, "Huge", { maxBatchBytes: 1_000, maxBatchFiles: 100 });
    // The oversize file cannot be split, so it lands alone; the small file is
    // its own batch. No batch mixes them.
    const whaleBatch = plan.batches.find((b) => b.files.some((f) => f.path === "Huge/whale.md"));
    expect(whaleBatch!.files.length).toBe(1);
    expect(whaleBatch!.totalBytes).toBe(5_000);
  });

  test("rejects non-positive caps (no silent fallback)", () => {
    writeSized("X/a.md", 10);
    expect(() => planBatches(vault, "X", { maxBatchBytes: 0, maxBatchFiles: 10 })).toThrow();
    expect(() => planBatches(vault, "X", { maxBatchBytes: 100, maxBatchFiles: 0 })).toThrow();
  });
});

describe("planBatches — determinism + empty", () => {
  test("same dir → identical plan, stable path ordering", () => {
    // Write out of lexical order to prove the plan sorts.
    writeSized("D/zebra.md", 100);
    writeSized("D/alpha.md", 100);
    writeSized("D/mango.md", 100);

    const p1 = planBatches(vault, "D", { maxBatchBytes: 250, maxBatchFiles: 10 });
    const p2 = planBatches(vault, "D", { maxBatchBytes: 250, maxBatchFiles: 10 });
    expect(p1).toEqual(p2);

    // Files are batched in sorted-by-path order.
    expect(allPlannedPaths(p1)).toEqual(["D/alpha.md", "D/mango.md", "D/zebra.md"]);
  });

  test("an empty dir yields an empty plan (no spurious batches)", () => {
    mkdirSync(join(vault, "Empty"), { recursive: true });
    const plan = planBatches(vault, "Empty", { maxBatchBytes: 100, maxBatchFiles: 10 });
    expect(plan.batches).toEqual([]);
    expect(plan.skipped).toEqual([]);
    expect(plan.totalFiles).toBe(0);
  });

  test("an all-unchanged dir yields an empty plan but reports the skipped files", () => {
    writeSized("Stable/a.md", 100);
    writeSized("Stable/b.md", 100);
    updateManifest(vault, ["Stable/a.md", "Stable/b.md"]);

    const plan = planBatches(vault, "Stable", { maxBatchBytes: 100, maxBatchFiles: 10 });
    expect(plan.batches).toEqual([]);
    expect(plan.totalFiles).toBe(0);
    expect(plan.skipped.toSorted()).toEqual(["Stable/a.md", "Stable/b.md"]);
  });

  test("a non-existent source dir is a hard error, not an empty plan", () => {
    expect(() => planBatches(vault, "Nope", { maxBatchBytes: 100, maxBatchFiles: 10 })).toThrow();
  });
});

describe("planBatches — resume (t_ba1fa5f6)", () => {
  test("resume excludes checkpointed items but keeps the plan id stable", () => {
    writeSized("Big/a.md", 100);
    writeSized("Big/b.md", 100);
    writeSized("Big/c.md", 100);

    // Fresh plan sees all three; its id is derived from the full discovered set.
    const fresh = planBatches(vault, "Big", { maxBatchBytes: 10_000, maxBatchFiles: 100 });
    expect(fresh.totalFiles).toBe(3);
    expect(fresh.resumedCompleted).toBe(0);

    // Simulate an interruption after two items completed.
    recordCompleted(vault, fresh.planId, "Big", ["Big/a.md", "Big/b.md"], new Date());

    const resumed = planBatches(vault, "Big", {
      maxBatchBytes: 10_000,
      maxBatchFiles: 100,
      resume: true,
    });
    expect(resumed.planId).toBe(fresh.planId);
    expect(allPlannedPaths(resumed)).toEqual(["Big/c.md"]);
    expect(resumed.totalFiles).toBe(1);
    expect(resumed.resumedCompleted).toBe(2);
  });

  test("without resume the checkpoint is ignored", () => {
    writeSized("Big/a.md", 100);
    writeSized("Big/b.md", 100);
    const planId = planBatches(vault, "Big", {
      maxBatchBytes: 10_000,
      maxBatchFiles: 100,
    }).planId;
    recordCompleted(vault, planId, "Big", ["Big/a.md"], new Date());

    const plan = planBatches(vault, "Big", { maxBatchBytes: 10_000, maxBatchFiles: 100 });
    expect(plan.totalFiles).toBe(2);
    expect(plan.resumedCompleted).toBe(0);
  });

  test("OSB_INGEST_NO_CHECKPOINT makes resume a no-op (nothing excluded)", () => {
    writeSized("Big/a.md", 100);
    writeSized("Big/b.md", 100);
    const fresh = planBatches(vault, "Big", { maxBatchBytes: 10_000, maxBatchFiles: 100 });
    try {
      process.env["OSB_INGEST_NO_CHECKPOINT"] = "1";
      // record is inert under the opt-out, and so is the resume read.
      recordCompleted(vault, fresh.planId, "Big", ["Big/a.md"], new Date());
      const plan = planBatches(vault, "Big", {
        maxBatchBytes: 10_000,
        maxBatchFiles: 100,
        resume: true,
      });
      expect(plan.totalFiles).toBe(2);
      expect(plan.resumedCompleted).toBe(0);
    } finally {
      delete process.env["OSB_INGEST_NO_CHECKPOINT"];
    }
  });
});

describe("planBatches — typed skip reasons + per-reason counts (P4)", () => {
  test("the plan counts skipped pages per typed reason token", () => {
    page("Sources/a.md", "paper");
    page("Sources/b.md", "memo");
    page("Sources/c.md", "memo");
    page("Sources/d.md", "paper");
    setExtractable(["paper"]);

    const plan: BatchPlan = planBatches(vault, "Sources", CAPS);
    expect(plan.skippedNonExtractable).toHaveLength(2);
    expect(plan.skipReasonCounts).toEqual({ [SKIPPED_PAGE_REASON.notExtractable]: 2 });
  });

  test("a plan with no skips counts nothing", () => {
    page("Sources/a.md", "paper");
    page("Sources/b.md", "memo");
    const plan = planBatches(vault, "Sources", CAPS);
    expect(Object.keys(plan.skipReasonCounts)).toEqual([]);
  });

  test("serializeBatchPlan emits the counts only when non-empty (byte-identical when absent)", () => {
    writeSized("Docs/a.md", 50);
    const clean = planBatches(vault, "Docs", CAPS);
    expect("skip_reason_counts" in serializeBatchPlan(clean)).toBe(false);

    page("Sources/b.md", "memo");
    setExtractable(["paper"]);
    const gated = planBatches(vault, "Sources", CAPS);
    const wire = serializeBatchPlan(gated);
    expect(wire["skip_reason_counts"]).toEqual({ [SKIPPED_PAGE_REASON.notExtractable]: 1 });
    expect(wire["skipped_non_extractable"]).toEqual([
      { path: "Sources/b.md", reason: SKIPPED_PAGE_REASON.notExtractable, detail: "memo" },
    ]);
  });
});

describe("planBatches — unclassifiable files (P4)", () => {
  test("counts files dropped for a non-ingestible extension, per extension", () => {
    writeSized("Docs/a.md", 50);
    writeSized("Docs/pic.bin", 50);
    writeSized("Docs/data.dat", 50);

    const plan = planBatches(vault, "Docs", CAPS);
    expect(plan.unclassifiable.total).toBe(2);
    expect(plan.unclassifiable.byExtension).toEqual({ ".bin": 1, ".dat": 1 });

    // Counting must not alter the discovered set: the plan id (derived from
    // the ingestible set) is the same with and without the foreign files.
    rmSync(join(vault, "Docs", "pic.bin"));
    rmSync(join(vault, "Docs", "data.dat"));
    expect(planBatches(vault, "Docs", CAPS).planId).toBe(plan.planId);
  });

  test("hidden entries and ignore-rule matches are excluded by declaration, not counted", () => {
    writeSized("Docs/a.md", 50);
    writeSized("Docs/.hidden.bin", 50);
    writeSized("Docs/.hid/x.bin", 50);
    writeSized("Docs/node_modules/lib/x.bin", 50);
    writeFileSync(join(vault, "Docs", ".gitignore"), "node_modules/\n", "utf8");

    const plan = planBatches(vault, "Docs", CAPS);
    expect(plan.unclassifiable.total).toBe(0);
    expect(allPlannedPaths(plan)).toEqual(["Docs/a.md"]);
  });

  test("serializeBatchPlan emits the aggregate only when non-empty", () => {
    writeSized("Docs/a.md", 50);
    const clean = planBatches(vault, "Docs", CAPS);
    expect("unclassifiable" in serializeBatchPlan(clean)).toBe(false);

    writeSized("Docs/pic.bin", 50);
    writeSized("Docs/data.dat", 50);
    const withDrops = planBatches(vault, "Docs", CAPS);
    expect(serializeBatchPlan(withDrops)["unclassifiable"]).toEqual({
      total: 2,
      by_extension: { ".bin": 1, ".dat": 1 },
    });
  });
});

describe("planBatches — source formats", () => {
  test("plans HTML and CSV with their format, names PDF and images as format skips, counts the rest", () => {
    writeSized("Clips/notes.md", 15);
    writeSized("Clips/page.html", 40);
    writeSized("Clips/parts.csv", 22);
    writeSized("Clips/report.pdf", 9);
    writeSized("Clips/shot.png", 12);
    writeSized("Clips/blob.bin", 3);

    const plan = planBatches(vault, "Clips", CAPS);
    expect(plan.batches.flatMap((b) => b.files)).toEqual([
      { path: "Clips/notes.md", bytes: 15, status: "new" },
      { path: "Clips/page.html", bytes: 40, status: "new", format: "html" },
      { path: "Clips/parts.csv", bytes: 22, status: "new", format: "csv" },
    ]);
    expect(plan.skippedNonExtractable).toEqual([
      { path: "Clips/report.pdf", reason: SKIPPED_PAGE_REASON.formatNotExtractable, detail: "pdf" },
      { path: "Clips/shot.png", reason: SKIPPED_PAGE_REASON.formatNotExtractable, detail: "image" },
    ]);
    expect(plan.skipReasonCounts).toEqual({ [SKIPPED_PAGE_REASON.formatNotExtractable]: 2 });
    expect(plan.unclassifiable).toEqual({ total: 1, byExtension: { ".bin": 1 } });
  });

  test("format skips precede schema skips, each sorted by path", () => {
    page("Mixed/b.md", "memo");
    page("Mixed/a.md", "paper");
    writeSized("Mixed/z.pdf", 9);
    writeSized("Mixed/c.docx", 9);
    writeFileSync(
      join(vault, "Brain", "_brain.yaml"),
      "schema_version: 1\nschema:\n  page_types:\n    - paper\n    - memo\n  extractable:\n    - paper\n",
      "utf8",
    );

    const plan = planBatches(vault, "Mixed", CAPS);
    expect(plan.skippedNonExtractable.map((s) => [s.path, s.reason, s.detail])).toEqual([
      ["Mixed/c.docx", "format-not-extractable", "docx"],
      ["Mixed/z.pdf", "format-not-extractable", "pdf"],
      ["Mixed/b.md", "schema-type-not-extractable", "memo"],
    ]);
    expect(Object.keys(plan.skipReasonCounts)).toEqual([
      "format-not-extractable",
      "schema-type-not-extractable",
    ]);
  });

  test("a caller's extensions override that lists .pdf plans it, with its format", () => {
    writeSized("Clips/notes.md", 15);
    writeSized("Clips/report.pdf", 9);

    const plan = planBatches(vault, "Clips", { ...CAPS, extensions: [".md", ".pdf"] });
    expect(plan.batches.flatMap((b) => b.files)).toEqual([
      { path: "Clips/notes.md", bytes: 15, status: "new" },
      { path: "Clips/report.pdf", bytes: 9, status: "new", format: "pdf" },
    ]);
    expect(plan.skippedNonExtractable).toEqual([]);
  });

  test("a Markdown-only tree serializes with no format key and no skip keys", () => {
    writeSized("Docs/a.md", 10);
    writeSized("Docs/b.txt", 20);

    const wire = serializeBatchPlan(planBatches(vault, "Docs", CAPS));
    expect(wire["batches"]).toEqual([
      {
        index: 0,
        total_bytes: 30,
        files: [
          { path: "Docs/a.md", bytes: 10, status: "new" },
          { path: "Docs/b.txt", bytes: 20, status: "new" },
        ],
      },
    ]);
    expect(Object.keys(wire)).toEqual([
      "source_dir",
      "max_batch_bytes",
      "max_batch_files",
      "total_files",
      "total_bytes",
      "skipped",
      "plan_id",
      "resumed_completed",
      "batches",
    ]);
  });

  test("a planned non-text file serializes format right after status", () => {
    writeSized("Clips/page.html", 40);

    const wire = serializeBatchPlan(planBatches(vault, "Clips", CAPS));
    const files = (wire["batches"] as Array<{ files: Array<Record<string, unknown>> }>)[0]!.files;
    expect(JSON.stringify(files[0])).toBe(
      '{"path":"Clips/page.html","bytes":40,"status":"new","format":"html"}',
    );
  });

  test("the planner re-exports the registry's default extensions", () => {
    expect(PLANNER_DEFAULT_EXTENSIONS).toBe(DEFAULT_INGESTIBLE_EXTENSIONS);
  });
});

describe("planBatches — extraction contract (t_586d5d8b)", () => {
  test("a changed contract reprocesses `unchanged` files with the distinct reason", () => {
    page("Inbox/a.md", "paper");
    setExtractable(["paper"]);
    updateManifest(vault, ["Inbox/a.md"]); // stamped under the live contract
    // Widen the allowlist: the contract changes while the file's bytes and
    // its gate outcome stay exactly the same.
    setExtractable(["paper", "memo"]);

    const plan = planBatches(vault, "Inbox", CAPS);
    expect(plan.contractChanged).toBe(true);
    expect(plan.contractChangedFiles).toBe(1);
    expect(plan.skipped).toEqual([]); // nothing skips under a changed contract
    expect(allPlannedPaths(plan)).toEqual(["Inbox/a.md"]);
    expect(plan.batches[0]!.files[0]!.status).toBe("contract-changed");
  });

  test("bytes-changed and contract-changed stay distinct tokens in one plan", () => {
    page("Inbox/same.md", "paper");
    page("Inbox/edited.md", "paper");
    setExtractable(["paper"]);
    updateManifest(vault, ["Inbox/same.md", "Inbox/edited.md"]);
    writeFileSync(
      join(vault, "Inbox/edited.md"),
      "---\ntitle: edited\nschema_type: paper\n---\n\nnew body\n",
      "utf8",
    );
    setExtractable(["paper", "memo"]);

    const plan = planBatches(vault, "Inbox", CAPS);
    const byStatus = new Map(
      plan.batches.flatMap((b) => b.files.map((f) => [f.status, f.path] as const)),
    );
    expect(byStatus.get("modified")).toBe("Inbox/edited.md"); // bytes changed
    expect(byStatus.get("contract-changed")).toBe("Inbox/same.md"); // contract only
    expect(plan.contractChangedFiles).toBe(1);
  });

  test("a v1 manifest (never contract-stamped) reprocesses unchanged bytes once", () => {
    page("Inbox/a.md", "paper");
    setExtractable(["paper"]);
    const manifest = join(vault, ".open-second-brain", "ingest-manifest.json");
    mkdirSync(join(manifest, ".."), { recursive: true });
    writeFileSync(
      manifest,
      JSON.stringify({
        schema_version: 1,
        entries: { "Inbox/a.md": hashFile(join(vault, "Inbox", "a.md")) },
      }),
      "utf8",
    );

    const plan = planBatches(vault, "Inbox", CAPS);
    expect(plan.contractChanged).toBe(true);
    expect(plan.batches[0]!.files[0]!.status).toBe("contract-changed");
  });

  test("an unchanged contract skips exactly as before and emits no contract keys", () => {
    page("Inbox/a.md", "paper");
    setExtractable(["paper"]);
    updateManifest(vault, ["Inbox/a.md"]);

    const plan = planBatches(vault, "Inbox", CAPS);
    expect(plan.contractChanged).toBe(false);
    expect(plan.contractChangedFiles).toBe(0);
    expect(plan.skipped).toEqual(["Inbox/a.md"]);
    expect(JSON.stringify(serializeBatchPlan(plan))).not.toContain("contract_changed");
  });

  test("serializeBatchPlan emits the contract fields only when the contract changed", () => {
    page("Inbox/a.md", "paper");
    setExtractable(["paper"]);
    updateManifest(vault, ["Inbox/a.md"]);
    setExtractable(["paper", "memo"]);

    const wire = serializeBatchPlan(planBatches(vault, "Inbox", CAPS));
    expect(wire["contract_changed"]).toBe(true);
    expect(wire["contract_changed_files"]).toBe(1);
  });

  test("resume does not consume a checkpoint recorded under the old contract", () => {
    page("Inbox/a.md", "paper");
    setExtractable(["paper"]);
    updateManifest(vault, ["Inbox/a.md"]);
    const before = planBatches(vault, "Inbox", CAPS);
    recordCompleted(
      vault,
      before.planId,
      "Inbox",
      ["Inbox/a.md"],
      new Date("2026-06-13T12:00:00Z"),
    );

    setExtractable(["paper", "memo"]); // the contract, hence the plan id, changes
    const resumed = planBatches(vault, "Inbox", { ...CAPS, resume: true });
    expect(resumed.planId).not.toBe(before.planId);
    expect(resumed.resumedCompleted).toBe(0); // the old checkpoint cannot resume-skip
    expect(resumed.batches[0]!.files[0]!.status).toBe("contract-changed");
  });
});