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
/**
* 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");
});
});