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
/**
* MCP integration tests for `brain_write_batch` (W2, t_7718ab22): the
* general atomic batch write tool, the second consumer of kernel 2.
*
* A mixed batch commits all-or-nothing; the first invalid operation
* aborts with a typed error naming the operation index and no disk write
* happens. Single-operation batches produce results equal to the
* dedicated brain_create_note / brain_update_note / brain_append_note
* tools.
*
* The nothing-writes-silently wave (unit B) adds `allow_empty` to the
* `update_note` op object and pins the two refusals the batch inherits
* from the shared projection: a blank body over a note that has one, and
* a target the host cannot read - each aborting the whole batch before
* any operation commits.
*/
import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
import {
existsSync,
mkdirSync,
readdirSync,
readFileSync,
rmSync,
statSync,
utimesSync,
writeFileSync,
} from "node:fs";
import { mkdtempSync } 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 { readLogDay } from "../../src/core/brain/log-jsonl.ts";
import { writeImagesDir } from "../../src/core/brain/paths.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../src/core/brain/types.ts";
import { WRITE_BATCH_TOOLS } from "../../src/mcp/brain/write-batch-tools.ts";
import { NOTES_TOOLS } from "../../src/mcp/brain/notes-tools.ts";
import { MAX_BATCH_OPERATIONS } from "../../src/core/brain/write-batch.ts";
import * as ledger from "../../src/core/brain/idempotency-ledger.ts";
import { PAGE_LINT_KEY, UNDATED_QUANTITY_CODE } from "../../src/core/brain/page-lint.ts";
import { INVALID_PARAMS, MCPError } from "../../src/mcp/protocol.ts";
import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
import type { ServerContext } from "../../src/mcp/tool-contract.ts";
/**
* Shape of a note-write id, as `noteWriteId` spells it (who-wrote-what,
* Task A). Its value carries the instant of the write, so a receipt test
* pins the shape rather than a literal.
*/
const NOTE_WRITE_ID_RE = /^nw_\d{14}_[0-9a-f]{16}$/;
let vault: string;
let configHome: string;
let ctx: ServerContext;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-write-batch-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-write-batch-cfg-"));
const configPath = join(configHome, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
bootstrapBrain(vault, { configPath });
ctx = { vault, configPath, repoRoot: null };
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
function seedNote(rel: string, body: string, frontmatter = ""): void {
const abs = join(vault, rel);
mkdirSync(join(abs, ".."), { recursive: true });
const fm = frontmatter ? `---\n${frontmatter}\n---\n\n` : "";
writeFileSync(abs, `${fm}${body}\n`, "utf8");
}
function writePref(slug: string): void {
writeFileSync(
join(vault, "Brain", "preferences", `pref-${slug}.md`),
[
"---",
"kind: brain-preference",
`id: pref-${slug}`,
"tags: [brain, brain/preference]",
`topic: ${slug}`,
"_status: confirmed",
"principle: always test first",
"created_at: 2026-01-01T00:00:00Z",
"unconfirmed_until: 2026-01-15T00:00:00Z",
"---",
"",
].join("\n"),
"utf8",
);
}
const tool = WRITE_BATCH_TOOLS.find((t) => t.name === "brain_write_batch")!;
type BatchResponse = {
readonly applied: number;
readonly results: ReadonlyArray<Record<string, unknown>>;
readonly done: true;
readonly [PAGE_LINT_KEY]?: {
readonly findings: ReadonlyArray<Record<string, unknown>>;
readonly total: number;
readonly returned: number;
readonly truncated: boolean;
readonly skipped: ReadonlyArray<Record<string, unknown>>;
};
};
async function runBatch(operations: unknown[]): Promise<BatchResponse> {
return (await tool.handler(ctx, { operations })) as unknown as BatchResponse;
}
describe("brain_write_batch", () => {
test("is registered and requires operations", () => {
expect(tool).toBeDefined();
expect(tool.inputSchema.required).toContain("operations");
});
test("commits a mixed batch all-or-nothing", async () => {
writePref("test-first");
seedNote("Notes/Existing.md", "old", "title: E");
const res = await runBatch([
{ op: "create_note", path: "Notes/New.md", content: "fresh" },
{ op: "update_note", path: "Notes/Existing.md", content: "updated" },
{
op: "apply_evidence",
pref_id: "test-first",
artifact: "[[Notes/New.md]]",
result: "applied",
},
{ op: "append_log_line", text: "batch landed" },
]);
expect(res.applied).toBe(4);
expect(existsSync(join(vault, "Notes/New.md"))).toBe(true);
expect(readFileSync(join(vault, "Notes/Existing.md"), "utf8")).toContain("updated");
});
test("a later invalid op aborts the batch: earlier ops do not land", async () => {
await expect(
tool.handler(ctx, {
operations: [
{ op: "create_note", path: "Notes/First.md", content: "one" },
// op 1 is invalid: the preference does not exist.
{ op: "apply_evidence", pref_id: "ghost", artifact: "[[x]]", result: "applied" },
],
}),
).rejects.toThrow(MCPError);
// Op 0 must not have landed.
expect(existsSync(join(vault, "Notes/First.md"))).toBe(false);
});
test("the typed error names the offending operation index", async () => {
let thrown: unknown;
try {
await tool.handler(ctx, {
operations: [
{ op: "create_note", path: "Notes/Ok.md", content: "x" },
{ op: "update_note", path: "Notes/Ghost.md", content: "y" },
],
});
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(MCPError);
expect((thrown as MCPError).data).toMatchObject({ index: 1, code: "target_missing" });
expect(existsSync(join(vault, "Notes/Ok.md"))).toBe(false);
});
test("an empty operations array is rejected", async () => {
await expect(tool.handler(ctx, { operations: [] })).rejects.toThrow(MCPError);
});
test("a batch over the operation cap is rejected before any write", async () => {
const tooMany = Array.from({ length: MAX_BATCH_OPERATIONS + 1 }, (_, i) => ({
op: "create_note",
path: `Notes/Over-${i}.md`,
content: "x",
}));
let thrown: unknown;
try {
await tool.handler(ctx, { operations: tooMany });
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(MCPError);
expect((thrown as MCPError).data).toMatchObject({
code: "too_many_operations",
index: -1,
max: MAX_BATCH_OPERATIONS,
count: MAX_BATCH_OPERATIONS + 1,
});
// Nothing landed: the cap is enforced during validation, before commit.
expect(existsSync(join(vault, "Notes/Over-0.md"))).toBe(false);
});
test("the inputSchema advertises the operation cap via maxItems", () => {
const schema = tool.inputSchema as {
properties: { operations: { maxItems?: number } };
};
expect(schema.properties.operations.maxItems).toBe(MAX_BATCH_OPERATIONS);
});
test("the operation object declares allow_empty with a description", () => {
const schema = tool.inputSchema as {
properties: {
operations: {
items: { properties: Record<string, { type?: string; description?: string }> };
};
};
};
const allowEmpty = schema.properties.operations.items.properties["allow_empty"];
expect(allowEmpty?.type).toBe("boolean");
expect((allowEmpty?.description ?? "").length).toBeGreaterThan(0);
});
test("an update_note op refuses to blank a note that has a body", async () => {
seedNote("Notes/Doc.md", "worth keeping", "title: Doc");
let thrown: unknown;
try {
await runBatch([{ op: "update_note", path: "Notes/Doc.md", content: "" }]);
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(MCPError);
expect((thrown as MCPError).data).toMatchObject({
code: "blank_overwrite_refused",
index: 0,
path: "Notes/Doc.md",
});
expect(readFileSync(join(vault, "Notes/Doc.md"), "utf8")).toContain("worth keeping");
});
test("allow_empty on the op clears the body deliberately", async () => {
seedNote("Notes/Doc.md", "worth keeping", "title: Doc");
const res = await runBatch([
{ op: "update_note", path: "Notes/Doc.md", content: "", allow_empty: true },
]);
expect(res.applied).toBe(1);
const md = readFileSync(join(vault, "Notes/Doc.md"), "utf8");
expect(md).toContain("title: Doc");
expect(md).not.toContain("worth keeping");
});
test("an unreadable note aborts the batch before any op lands", async () => {
mkdirSync(join(vault, "Notes/Unreadable.md"), { recursive: true });
let thrown: unknown;
try {
// At local reach: a remote caller is answered as for a missing
// note, because a page nobody can measure is treated as one that
// reserved itself. The diagnostic is for the operator.
await tool.handler(
{ ...ctx, reach: TRANSPORT_REACH.local },
{
operations: [
{ op: "create_note", path: "Notes/First.md", content: "one" },
{ op: "update_note", path: "Notes/Unreadable.md", content: "two" },
],
},
);
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(MCPError);
expect((thrown as MCPError).data).toMatchObject({ code: "target_unreadable", index: 1 });
expect(existsSync(join(vault, "Notes/First.md"))).toBe(false);
});
test("single-op create parity with brain_create_note", async () => {
const createTool = NOTES_TOOLS.find((t) => t.name === "brain_create_note")!;
const direct = await createTool.handler(ctx, { path: "Notes/Direct.md", content: "d" });
const batch = await runBatch([{ op: "create_note", path: "Notes/Batch.md", content: "d" }]);
const batchResult = batch.results[0]!;
expect(batchResult).toMatchObject({ kind: "create_note", created: true });
expect(direct).toMatchObject({ created: true });
});
test("single-op update parity with brain_update_note", async () => {
seedNote("Notes/A.md", "old", "title: A");
seedNote("Notes/B.md", "old", "title: B");
const updateTool = NOTES_TOOLS.find((t) => t.name === "brain_update_note")!;
const direct = await updateTool.handler(ctx, { path: "Notes/A.md", content: "new" });
const batch = await runBatch([{ op: "update_note", path: "Notes/B.md", content: "new" }]);
const batchResult = batch.results[0]!;
expect(direct).toMatchObject({ updated: true, path: "Notes/A.md" });
expect(batchResult).toMatchObject({ kind: "update_note", updated: true, path: "Notes/B.md" });
expect(readFileSync(join(vault, "Notes/A.md"), "utf8")).toBe(
readFileSync(join(vault, "Notes/B.md"), "utf8").replace("title: B", "title: A"),
);
});
test("single-op append parity with brain_append_note", async () => {
seedNote("Notes/A.md", "base", "title: A");
seedNote("Notes/B.md", "base", "title: A");
const appendTool = NOTES_TOOLS.find((t) => t.name === "brain_append_note")!;
await appendTool.handler(ctx, { path: "Notes/A.md", content: "more" });
await tool.handler(ctx, {
operations: [{ op: "append_note", path: "Notes/B.md", content: "more" }],
});
expect(readFileSync(join(vault, "Notes/A.md"), "utf8")).toBe(
readFileSync(join(vault, "Notes/B.md"), "utf8"),
);
});
test("refuses the Brain machinery root in a create op", async () => {
await expect(
tool.handler(ctx, { operations: [{ op: "create_note", path: "Brain/x.md", content: "y" }] }),
).rejects.toThrow(MCPError);
});
});
/**
* Write-time page lint (evidence-at-the-boundary, task A4). The batch ran
* no document validation at all; the lint runs once over every page the
* batch committed, with the basename index and schema pack computed ONCE
* per call rather than once per operation.
*/
describe("brain_write_batch - the lint attached to the receipt", () => {
test("a clean batch carries the counts, the results and each write id", async () => {
const res = await runBatch([
{
op: "create_note",
path: "Notes/CleanBatch.md",
frontmatter: { title: "Clean" },
content: "prose",
},
]);
expect(Object.keys(res)).toEqual(["applied", "results", "done"]);
const only = (res["results"] as ReadonlyArray<Record<string, unknown>>)[0]!;
expect(Object.keys(only)).toEqual(["kind", "path", "created", "write_id"]);
expect(only).toMatchObject({
kind: "create_note",
path: "Notes/CleanBatch.md",
created: true,
});
// Each note result names the event that attributes it; the batch
// envelope itself is unchanged (who-wrote-what, Task A).
expect(only["write_id"]).toMatch(NOTE_WRITE_ID_RE);
expect(res["applied"]).toBe(1);
expect(res["done"]).toBe(true);
expect(PAGE_LINT_KEY in res).toBe(false);
});
test("one report spans every page the batch wrote, each finding naming its page", async () => {
const res = await runBatch([
{
op: "create_note",
path: "Notes/One.md",
frontmatter: { title: "One" },
content: "see [[pref-ghost]]",
},
{
op: "create_note",
path: "Notes/Two.md",
frontmatter: { title: "Two" },
content: "see [[pref-other-ghost]]",
},
{ op: "append_log_line", text: "batch landed" },
]);
const lint = res[PAGE_LINT_KEY]!;
expect(lint.total).toBe(2);
expect(lint.returned).toBe(2);
expect(lint.truncated).toBe(false);
expect(lint.findings.map((f) => f["page"]).toSorted()).toEqual([
"Notes/One.md",
"Notes/Two.md",
]);
});
test("a log-only batch writes no page and lints nothing", async () => {
const res = await runBatch([{ op: "append_log_line", text: "just a line" }]);
expect(res.applied).toBe(1);
expect(PAGE_LINT_KEY in res).toBe(false);
});
test("a byte-identical rewrite that skipped names no page for the lint", async () => {
// The write that happened carries its finding; the re-apply that
// skipped carries the receipt but no lint, the same rule the
// single-write receipts follow - nothing was committed, so the
// envelope names no page as one the batch wrote.
seedNote("Notes/SkipLint.md", "v1");
const body = "see [[pref-ghost]]";
const first = await runBatch([{ op: "update_note", path: "Notes/SkipLint.md", content: body }]);
expect(PAGE_LINT_KEY in first).toBe(true);
const second = await runBatch([
{ op: "update_note", path: "Notes/SkipLint.md", content: body },
]);
expect(second.results[0]).toMatchObject({ kind: "update_note", updated: false });
expect(PAGE_LINT_KEY in second).toBe(false);
});
test("an undated numeric create reports the finding on the batch envelope", async () => {
const res = await runBatch([
{
op: "create_note",
path: "Notes/UndatedBatch.md",
frontmatter: { title: "Undated" },
content: "We onboarded 5,000 users.",
},
]);
expect(res["applied"]).toBe(1);
const lint = res[PAGE_LINT_KEY]!;
expect(lint.findings).toEqual([
expect.objectContaining({
severity: "warning",
code: UNDATED_QUANTITY_CODE,
page: "Notes/UndatedBatch.md",
path: "body",
}),
]);
});
test("the same batch create with valid_from keeps the clean envelope", async () => {
const res = await runBatch([
{
op: "create_note",
path: "Notes/DatedBatch.md",
frontmatter: { title: "Dated", valid_from: "2026-10-01" },
content: "We onboarded 5,000 users.",
},
]);
expect(Object.keys(res)).toEqual(["applied", "results", "done"]);
expect(PAGE_LINT_KEY in res).toBe(false);
});
});
/**
* The absolute-path advisory (p4-silent-failure-hardening, Task 3). A
* note body embedding an absolute home path used to land with no word
* about it. The advisory rides each note result like page-lint rides the
* envelope: non-blocking, and absent entirely when there is nothing to
* say. Path fragments are composed so this file stays clean under the
* repo hygiene gate's grammar.
*/
describe("brain_write_batch - the absolute-path advisory on the receipt", () => {
const HOME = "/home/";
const leaky = `see ${HOME}alice-dev/notes/x.md for details`;
test("an update authoring a home path carries the advisory and still applies", async () => {
seedNote("Notes/Leaky.md", "old", "title: Leaky");
const res = await runBatch([{ op: "update_note", path: "Notes/Leaky.md", content: leaky }]);
// Non-blocking: the batch applies and the bytes land.
expect(res.applied).toBe(1);
expect(readFileSync(join(vault, "Notes/Leaky.md"), "utf8")).toContain("alice-dev");
const only = res.results[0]!;
const advisory = only["path_advisory"] as
| { total: number; findings: ReadonlyArray<Record<string, unknown>> }
| undefined;
expect(advisory).toBeDefined();
expect(advisory!.total).toBe(1);
expect(advisory!.findings).toEqual([
{ page: "Notes/Leaky.md", line: 1, detector: "unix-home" },
]);
// The advisory echoes identifiers and integers, never the path itself.
expect(JSON.stringify(res)).not.toContain(`${HOME}alice-dev`);
});
test("a clean update carries no advisory key at all", async () => {
seedNote("Notes/Clean.md", "old", "title: Clean");
const res = await runBatch([{ op: "update_note", path: "Notes/Clean.md", content: "new" }]);
const only = res.results[0]!;
expect(Object.keys(only)).toEqual(["kind", "path", "updated", "write_id"]);
expect("path_advisory" in only).toBe(false);
});
test("a frontmatter-only update authors no body and carries no advisory", async () => {
seedNote("Notes/Fm.md", "prose with no leak", "title: Fm");
const res = await runBatch([
{ op: "update_note", path: "Notes/Fm.md", frontmatter: { title: "Fm2" } },
]);
expect(res.applied).toBe(1);
expect("path_advisory" in res.results[0]!).toBe(false);
});
test("create and append ops carry the advisory; log-line ops do not", async () => {
seedNote("Notes/AppTarget.md", "base", "title: AppTarget");
const res = await runBatch([
{ op: "create_note", path: "Notes/Created.md", content: leaky },
{ op: "append_note", path: "Notes/AppTarget.md", content: leaky },
{ op: "append_log_line", text: "batch landed" },
]);
expect(res.applied).toBe(3);
const [created, appended, logLine] = res.results;
expect("path_advisory" in created!).toBe(true);
expect("path_advisory" in appended!).toBe(true);
expect("path_advisory" in logLine!).toBe(false);
});
test("brain_update_note passes the advisory through on its receipt", async () => {
seedNote("Notes/Single.md", "old", "title: Single");
const updateTool = NOTES_TOOLS.find((t) => t.name === "brain_update_note")!;
const leakyBody = `body with ${HOME}alice-dev/leak.md inside`;
const res = (await updateTool.handler(ctx, {
path: "Notes/Single.md",
content: leakyBody,
})) as Record<string, unknown>;
expect(res["updated"]).toBe(true);
const advisory = res["path_advisory"] as {
total: number;
findings: ReadonlyArray<Record<string, unknown>>;
};
expect(advisory.total).toBe(1);
expect(advisory.findings[0]).toMatchObject({ page: "Notes/Single.md", line: 1 });
expect(JSON.stringify(res)).not.toContain(`${HOME}alice-dev`);
});
test("brain_append_note carries no advisory key on a clean receipt", async () => {
seedNote("Notes/App.md", "base", "title: App");
const appendTool = NOTES_TOOLS.find((t) => t.name === "brain_append_note")!;
const res = (await appendTool.handler(ctx, {
path: "Notes/App.md",
content: "clean addition",
})) as Record<string, unknown>;
// The refresh-claim marker rides the append receipt under the same
// vocabulary the update receipt carries (freshening is off
// suite-wide, so it reads not_claimed with its reason); no advisory.
expect(Object.keys(res)).toEqual([
"appended",
"path",
"write_id",
"index_refresh",
"index_refresh_reason",
]);
expect("path_advisory" in res).toBe(false);
});
});
/** Note-write events recorded in today's log shard. */
function noteWriteEvents(): number {
const day = readLogDay(vault, new Date().toISOString().slice(0, 10));
return day.entries.filter((e) => e.eventType === BRAIN_LOG_EVENT_KIND.noteWrite).length;
}
function writeImages(): number {
const dir = writeImagesDir(vault);
return existsSync(dir) ? readdirSync(dir).length : 0;
}
/** Stamp a note's mtime one minute into the past, measurably. */
function ageMtime(abs: string): number {
const past = Date.now() / 1000 - 60;
utimesSync(abs, past, past);
return statSync(abs).mtimeMs;
}
/**
* mtime stability on byte-identical rewrites (p4-silent-failure-hardening,
* Task 6). The atomic write pipeline lands a fresh inode on every call,
* so re-applying a byte-identical update used to bump the note's mtime -
* poisoning recency ranking, validity windows and vault-delta counts -
* while storing a before-image and recording a note-write event for a
* write that never happened. The commit now skips unchanged targets, and
* the receipt says what actually occurred.
*/
describe("brain_write_batch - mtime stability on byte-identical rewrites", () => {
test("a byte-identical update re-applied writes nothing and says updated: false", async () => {
seedNote("Notes/Stable.md", "v1");
const first = await runBatch([{ op: "update_note", path: "Notes/Stable.md", content: "v2" }]);
expect(first.results[0]).toMatchObject({ kind: "update_note", updated: true });
const abs = join(vault, "Notes/Stable.md");
const mtime = ageMtime(abs);
const events = noteWriteEvents();
const images = writeImages();
const second = await runBatch([{ op: "update_note", path: "Notes/Stable.md", content: "v2" }]);
const only = second.results[0]!;
expect(only).toMatchObject({ kind: "update_note", path: "Notes/Stable.md", updated: false });
// The mtime is untouched: no temp file, no rename, no fresh inode.
expect(statSync(abs).mtimeMs).toBe(mtime);
// No audit line exists for a write that did not happen - no note-write
// event, no before-image, and no null write_id that could be mistaken
// for a lost one.
expect(noteWriteEvents()).toBe(events);
expect(writeImages()).toBe(images);
expect("write_id" in only).toBe(false);
expect("audit_reason" in only).toBe(false);
});
test("a real change still bumps the mtime and reports updated: true", async () => {
seedNote("Notes/Real.md", "v1");
const abs = join(vault, "Notes/Real.md");
const mtime = ageMtime(abs);
const res = await runBatch([{ op: "update_note", path: "Notes/Real.md", content: "v2" }]);
const only = res.results[0]!;
expect(only).toMatchObject({ kind: "update_note", path: "Notes/Real.md", updated: true });
expect(statSync(abs).mtimeMs).toBeGreaterThan(mtime);
// A write that happened stays attributed.
expect("write_id" in only).toBe(true);
});
test("an append with a fresh body reports appended: true", async () => {
seedNote("Notes/Appended.md", "base", "title: Appended");
const res = await runBatch([{ op: "append_note", path: "Notes/Appended.md", content: "more" }]);
expect(res.results[0]).toMatchObject({
kind: "append_note",
path: "Notes/Appended.md",
appended: true,
});
expect(readFileSync(join(vault, "Notes/Appended.md"), "utf8")).toContain("base");
expect(readFileSync(join(vault, "Notes/Appended.md"), "utf8")).toContain("more");
});
});
describe("brain_write_batch request receipts (t_b34439d9)", () => {
const OPS = [{ op: "create_note", path: "Notes/Receipted.md", content: "written once" }];
test("a request_id returns a receipt, and a retry returns the retained duplicate", async () => {
const first = (await tool.handler(ctx, {
operations: OPS,
request_id: "req-42",
})) as Record<string, unknown>;
expect(first["request_id"]).toBe("req-42");
expect(first["receipt"]).toBe("applied");
expect(first["applied"]).toBe(1);
const retry = (await tool.handler(ctx, {
operations: OPS,
request_id: "req-42",
})) as Record<string, unknown>;
expect(retry["request_id"]).toBe("req-42");
expect(retry["receipt"]).toBe("duplicate");
// The retained original receipt: the batch reports what the FIRST call
// applied, and nothing new lands.
expect(retry["applied"]).toBe(1);
expect(existsSync(join(vault, "Notes/Receipted.md"))).toBe(true);
});
test("a request_id omitted leaves the payload without receipt fields", async () => {
const res = (await tool.handler(ctx, { operations: OPS })) as Record<string, unknown>;
expect(Object.hasOwn(res, "request_id")).toBe(false);
expect(Object.hasOwn(res, "receipt")).toBe(false);
});
test("a concurrent duplicate recorded mid-batch reaches the caller by its own status", async () => {
const LOG_OPS = [{ op: "append_log_line", text: "concurrent receipt line" }];
await tool.handler(ctx, { operations: LOG_OPS, request_id: "req-race" });
// The unlocked consult misses the rival's record, as under a concurrent call.
const spy = spyOn(ledger, "lookupKey").mockReturnValueOnce(null);
try {
const res = (await tool.handler(ctx, {
operations: LOG_OPS,
request_id: "req-race",
})) as Record<string, unknown>;
expect(res["receipt"]).toBe("concurrent_duplicate");
} finally {
spy.mockRestore();
}
});
test("a concurrent record of the same id with another payload: this call's writes landed and the receipt says so", async () => {
await tool.handler(ctx, {
operations: [{ op: "append_log_line", text: "the rival line" }],
request_id: "req-conflict",
});
const spy = spyOn(ledger, "lookupKey").mockReturnValueOnce(null);
try {
const res = (await tool.handler(ctx, {
operations: OPS,
request_id: "req-conflict",
})) as Record<string, unknown>;
expect(res["receipt"]).toBe("payload_conflict");
expect(res["applied"]).toBe(1);
expect(res["done"]).toBe(true);
expect(String(res["receipt_note"])).toMatch(/writes of this call landed/);
expect(existsSync(join(vault, "Notes/Receipted.md"))).toBe(true);
} finally {
spy.mockRestore();
}
});
test.each([
["a number", 7],
["an empty string", ""],
["whitespace", " "],
["an over-long id", "x".repeat(300)],
])("request_id as %s is INVALID_PARAMS before any write", async (_label, requestId) => {
let thrown: unknown = null;
try {
await tool.handler(ctx, { operations: OPS, request_id: requestId });
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(MCPError);
expect((thrown as MCPError).code).toBe(INVALID_PARAMS);
expect((thrown as MCPError).message).toMatch(/request_id|idempotency key/);
expect(existsSync(join(vault, "Notes/Receipted.md"))).toBe(false);
});
test("a duplicate retry lints nothing: the call wrote no page", async () => {
const first = (await tool.handler(ctx, { operations: OPS, request_id: "req-lint" })) as Record<
string,
unknown
>;
const retry = (await tool.handler(ctx, { operations: OPS, request_id: "req-lint" })) as Record<
string,
unknown
>;
expect(retry["receipt"]).toBe("duplicate");
expect(PAGE_LINT_KEY in first).toBe(true);
expect(PAGE_LINT_KEY in retry).toBe(false);
});
});