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
29.0 KB
Raw Blame
/**
 * MCP integration tests for `brain_update_note` and `brain_append_note`
 * (W1, t_3ff3fe77). Both tools are single-operation batches over the
 * atomic write-batch core (kernel 2). They reuse the create-note safety
 * envelope and refuse a missing target with a typed error mapped to
 * INVALID_PARAMS.
 *
 * The nothing-writes-silently wave (unit B) adds the `allow_empty`
 * argument to `brain_update_note` and three refusals pinned here: a
 * blank body over a note that has one (INVALID_PARAMS,
 * `blank_overwrite_refused`, naming the note), an existing note the host
 * cannot read (INTERNAL_ERROR, `target_unreadable` - the caller's
 * request is right and the host is not), and an explicit empty `content`
 * read as a clear request rather than as an absent argument.
 */

import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { mkdtempSync } from "node:fs";
import { dirname, 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 { NOTES_TOOLS, writeBatchErrorToMcp } from "../../src/mcp/brain/notes-tools.ts";
import { WriteBatchError } from "../../src/core/brain/write-batch.ts";
import { PAGE_LINT_KEY, UNDATED_QUANTITY_CODE } from "../../src/core/brain/page-lint.ts";
import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../../src/mcp/protocol.ts";
import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
import { resolveSearchConfig } from "../../src/core/search/index.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}$/;

/** Await `result`, assert it rejected with an MCPError, and return it. */
async function rejectedMcpError(result: unknown): Promise<MCPError> {
  let thrown: unknown;
  try {
    await result;
  } catch (err) {
    thrown = err;
  }
  expect(thrown).toBeInstanceOf(MCPError);
  return thrown as MCPError;
}

let vault: string;
let configHome: string;
let ctx: ServerContext;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-update-note-vault-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-update-note-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");
}

const updateTool = NOTES_TOOLS.find((t) => t.name === "brain_update_note")!;
const appendTool = NOTES_TOOLS.find((t) => t.name === "brain_append_note")!;

// The freshen seam both claim describes below intercept. Module scope so
// the update and the append tests share ONE registration and ONE
// teardown - two private copies of a mock that must be un-registered is
// exactly how a leaked mock starts.
const FRESHEN_MODULE = "../../src/core/search/freshen.ts";
let realFreshen: Record<string, unknown> | null = null;
let forcedCalls: Array<{ vault: string; opts: Record<string, unknown> }> = [];

/** Intercept the freshen machinery at the deferred-import seam. */
async function mockFreshenSpawned(): Promise<void> {
  realFreshen = { ...(await import(FRESHEN_MODULE)) };
  forcedCalls = [];
  mock.module(FRESHEN_MODULE, () => ({
    ...realFreshen,
    maybeFreshenIndex: (config: { vault: string }, opts: Record<string, unknown>) => {
      forcedCalls.push({ vault: config.vault, opts });
      return "spawned" as const;
    },
  }));
}

afterEach(() => {
  // This runner's mock registration outlives mock.restore() across test
  // FILES, so the teardown re-registers the REAL module object instead:
  // whatever leaks past this file is freshen.ts itself, byte for byte.
  if (realFreshen !== null) mock.module(FRESHEN_MODULE, () => realFreshen);
  mock.restore();
  realFreshen = null;
  forcedCalls = [];
});

/** Stamp the vault's index with an old instant: the claim's stale gate must pass. */
async function stampIndexStale(): Promise<void> {
  const { LAST_INDEXED_AT_STATE_KEY, Store } = await import("../../src/core/search/store.ts");
  const store = await Store.open(resolveSearchConfig({ vault, configPath: ctx.configPath! }), {
    mode: "write",
  });
  store.setState(LAST_INDEXED_AT_STATE_KEY, "2026-08-15T00:00:00.000Z");
  await store.close();
}

function withIntervalEnv(value: string): () => void {
  const key = "OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S";
  const saved = process.env[key];
  process.env[key] = value;
  return () => {
    if (saved === undefined) delete process.env[key];
    else process.env[key] = saved;
  };
}

/**
 * The post-write index refresh a content edit claims.
 *
 * The release notes promise that a content edit claims a refresh, so an
 * applied update claims the SAME detached, claim-guarded refresh a
 * lifecycle write claims - fire-and-forget, with the claim marker and
 * its refusal reason on the receipt under the same vocabulary
 * (`index_refresh`, `index_refresh_reason`). The seam is the freshen
 * module itself, mocked here so the assertion sees the forced call
 * without ever spawning a real indexer; the suite-wide freshen-off
 * default keeps every OTHER test in this file inert.
 */
describe("brain_update_note - the post-write refresh claim", () => {
  test("a content edit claims one forced refresh: the seam sees force, and the receipt says claimed", async () => {
    seedNote("Notes/Doc.md", "old body", "title: Doc");
    // An index exists and is stale: the claim's stale gate passes and
    // the forced machinery is what the seam intercepts.
    await stampIndexStale();
    await mockFreshenSpawned();
    const restore = withIntervalEnv("60");
    try {
      const res = (await updateTool.handler(ctx, {
        path: "Notes/Doc.md",
        content: "new body",
      })) as Record<string, unknown>;

      expect(res["updated"]).toBe(true);
      // The same claim marker vocabulary the lifecycle tool renders, on
      // the update receipt: a run is IN FLIGHT, never landed.
      expect(res["index_refresh"]).toBe("claimed");
      expect(res["index_refresh_reason"]).toBeNull();
      // The seam assertion: one forced call for THIS vault - force past
      // the freshness gate, because the edit is due by definition.
      expect(forcedCalls).toHaveLength(1);
      expect(forcedCalls[0]!.vault).toBe(vault);
      expect(forcedCalls[0]!.opts["force"]).toBe(true);
    } finally {
      restore();
    }
  });

  test("config off does not claim: the receipt says not_claimed and names off", async () => {
    seedNote("Notes/Doc.md", "old body", "title: Doc");
    // An index exists (so the stale gate passes and the machinery is
    // what refuses), and no mock: with the interval at 0 the REAL
    // machinery answers before any spawn could be considered, so nothing
    // can leak out of this test either.
    await stampIndexStale();
    const restore = withIntervalEnv("0");
    try {
      const res = (await updateTool.handler(ctx, {
        path: "Notes/Doc.md",
        content: "new body",
      })) as Record<string, unknown>;

      expect(res["updated"]).toBe(true);
      expect(res["index_refresh"]).toBe("not_claimed");
      expect(res["index_refresh_reason"]).toBe("off");
    } finally {
      restore();
    }
  });

  test("a writer-locked index still queues the write: the receipt names writer_lock and the marker stands", async () => {
    seedNote("Notes/Doc.md", "old body", "title: Doc");
    // An index exists and is stale, the interval is on, and the REAL
    // machinery runs - no seam. The index writer lock is HELD: the shape
    // of a detached refresh mid-pass, which holds it for the bulk of its
    // run, where the lock probe answers before the claim is ever
    // consulted. A write that took the lock's answer home unmarked would
    // be dropped for a whole interval by the run's fresh stamp - the
    // exact mid-refresh drop the pending marker exists to prevent.
    await stampIndexStale();
    const { acquireWriterLockSync } = await import("../../src/core/search/store/writer-lock.ts");
    const { FRESHEN_PENDING_FILE, readFreshenPending } = await import(FRESHEN_MODULE);
    const dbPath = resolveSearchConfig({ vault, configPath: ctx.configPath! }).dbPath;
    const release = acquireWriterLockSync(dbPath);
    const scanStart = Date.now();
    const restore = withIntervalEnv("60");
    try {
      const res = (await updateTool.handler(ctx, {
        path: "Notes/Doc.md",
        content: "new body",
      })) as Record<string, unknown>;

      expect(res["updated"]).toBe(true);
      expect(res["index_refresh"]).toBe("not_claimed");
      expect(res["index_refresh_reason"]).toBe("writer_lock");
      // The queue: a durable marker beside the freshen state says a
      // write is pending since an instant after this test's own scan
      // start, so the in-flight child's settle runs the one bounded
      // extra pass that covers it before it releases the claim.
      const stateDir = dirname(dbPath);
      const marker = readFreshenPending(stateDir);
      expect(marker).not.toBeNull();
      expect(marker!.since).toBeGreaterThanOrEqual(scanStart);
      expect(existsSync(join(stateDir, FRESHEN_PENDING_FILE))).toBe(true);
    } finally {
      release();
      restore();
    }
  });

  test("the claim resolves through the server's own config file, not the environment alone", async () => {
    seedNote("Notes/Doc.md", "old body", "title: Doc");
    // The freshen-off decision arrives by CONFIG FILE here - the env
    // var the suite defaults to 0 is scrubbed - and the claim reads it
    // only because it resolves the search config through the server's
    // configPath. Resolved without it, the default interval stands and
    // the edit claims a run the operator's config refused.
    await stampIndexStale();
    atomicWriteFileSync(
      join(configHome, "config.yaml"),
      `vault: ${vault}\nagent_name: claude\nsearch_freshen_interval_s: 0\n`,
    );
    const key = "OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S";
    const saved = process.env[key];
    delete process.env[key];
    try {
      const res = (await updateTool.handler(ctx, {
        path: "Notes/Doc.md",
        content: "new body",
      })) as Record<string, unknown>;

      expect(res["updated"]).toBe(true);
      expect(res["index_refresh"]).toBe("not_claimed");
      expect(res["index_refresh_reason"]).toBe("off");
    } finally {
      if (saved === undefined) delete process.env[key];
      else process.env[key] = saved;
    }
  });

  test("a byte-identical re-apply wrote nothing, so it carries no refresh marker at all", async () => {
    seedNote("Notes/Doc.md", "same body", "title: Doc");
    const res = (await updateTool.handler(ctx, {
      path: "Notes/Doc.md",
      content: "same body",
    })) as Record<string, unknown>;

    expect(res["updated"]).toBe(false);
    // Byte-identical-when-absent: a receipt for a write that did not
    // happen says nothing about a refresh it did not claim.
    expect("index_refresh" in res).toBe(false);
    expect("index_refresh_reason" in res).toBe(false);
  });
});

describe("brain_update_note", () => {
  test("is registered and requires a path", () => {
    expect(updateTool).toBeDefined();
    expect(updateTool.inputSchema.required).toContain("path");
  });

  test("merges frontmatter and replaces the body of an existing note", async () => {
    seedNote("Notes/Doc.md", "old body", "title: Doc\nstatus: draft");
    const res = await updateTool.handler(ctx, {
      path: "Notes/Doc.md",
      frontmatter: { status: "final" },
      content: "new body",
    });
    expect(res).toMatchObject({ updated: true, path: "Notes/Doc.md" });
    const md = readFileSync(join(vault, "Notes/Doc.md"), "utf8");
    expect(md).toContain("title: Doc");
    expect(md).toContain("status: final");
    expect(md).toContain("new body");
    expect(md).not.toContain("old body");
  });

  test("a missing target is rejected with INVALID_PARAMS and writes nothing", async () => {
    const err = await rejectedMcpError(
      updateTool.handler(ctx, { path: "Notes/Ghost.md", content: "x" }),
    );
    expect(err.code).toBe(INVALID_PARAMS);
    expect(err.data).toMatchObject({ code: "target_missing", index: 0, path: "Notes/Ghost.md" });
    expect(existsSync(join(vault, "Notes/Ghost.md"))).toBe(false);
  });

  test("requires at least frontmatter or content", async () => {
    seedNote("Notes/Doc.md", "body", "title: Doc");
    const err = await rejectedMcpError(updateTool.handler(ctx, { path: "Notes/Doc.md" }));
    expect(err.code).toBe(INVALID_PARAMS);
  });

  test("declares the optional allow_empty boolean with a description", () => {
    const schema = updateTool.inputSchema as {
      properties: Record<string, { type?: string; description?: string }>;
      required: ReadonlyArray<string>;
    };
    expect(schema.properties["allow_empty"]?.type).toBe("boolean");
    expect((schema.properties["allow_empty"]?.description ?? "").length).toBeGreaterThan(0);
    expect(schema.required).not.toContain("allow_empty");
  });

  test("a blank body over a note that has one is refused, naming the note", async () => {
    seedNote("Notes/Doc.md", "worth keeping", "title: Doc");
    const err = await rejectedMcpError(
      updateTool.handler(ctx, { path: "Notes/Doc.md", content: "   " }),
    );
    expect(err.code).toBe(INVALID_PARAMS);
    expect(err.data).toMatchObject({ code: "blank_overwrite_refused", path: "Notes/Doc.md" });
    expect(err.message).toContain("Notes/Doc.md");
    expect(readFileSync(join(vault, "Notes/Doc.md"), "utf8")).toContain("worth keeping");
  });

  test("allow_empty clears the body deliberately", async () => {
    seedNote("Notes/Doc.md", "worth keeping", "title: Doc");
    const res = await updateTool.handler(ctx, {
      path: "Notes/Doc.md",
      content: "",
      allow_empty: true,
    });
    expect(res).toMatchObject({ updated: true, path: "Notes/Doc.md" });
    const md = readFileSync(join(vault, "Notes/Doc.md"), "utf8");
    expect(md).toContain("title: Doc");
    expect(md).not.toContain("worth keeping");
  });

  test("an explicit empty content beside frontmatter is a clear request, not an absent one", async () => {
    // It used to collapse to "argument not sent": the frontmatter merge
    // landed, the body the caller asked to clear stayed, and the receipt
    // said updated: true.
    seedNote("Notes/Doc.md", "worth keeping", "title: Doc");
    const err = await rejectedMcpError(
      updateTool.handler(ctx, {
        path: "Notes/Doc.md",
        frontmatter: { status: "final" },
        content: "",
      }),
    );
    expect(err.data).toMatchObject({ code: "blank_overwrite_refused", path: "Notes/Doc.md" });
    const md = readFileSync(join(vault, "Notes/Doc.md"), "utf8");
    expect(md).toContain("worth keeping");
    expect(md).not.toContain("status: final");
  });

  test("allow_empty clears the body while merging frontmatter", async () => {
    seedNote("Notes/Doc.md", "worth keeping", "title: Doc");
    await updateTool.handler(ctx, {
      path: "Notes/Doc.md",
      frontmatter: { status: "final" },
      content: "",
      allow_empty: true,
    });
    const md = readFileSync(join(vault, "Notes/Doc.md"), "utf8");
    expect(md).toContain("status: final");
    expect(md).not.toContain("worth keeping");
  });

  test("an existing note the host cannot read is refused, not blanked", async () => {
    // A directory where the note should be: it exists, and reading it
    // raises EISDIR regardless of the running user.
    mkdirSync(join(vault, "Notes/Doc.md"), { recursive: true });
    // 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 who can fix the file.
    const err = await rejectedMcpError(
      updateTool.handler(
        { ...ctx, reach: TRANSPORT_REACH.local },
        { path: "Notes/Doc.md", content: "replacement" },
      ),
    );
    expect(err.code).toBe(INTERNAL_ERROR);
    expect(err.data).toMatchObject({ code: "target_unreadable", path: "Notes/Doc.md" });
  });

  test("path traversal is refused with INVALID_PARAMS", async () => {
    const err = await rejectedMcpError(
      updateTool.handler(ctx, { path: "../escape.md", content: "x" }),
    );
    expect(err.code).toBe(INVALID_PARAMS);
    expect(err.data).toMatchObject({ code: "invalid_path", index: 0 });
    expect(existsSync(join(vault, "..", "escape.md"))).toBe(false);
  });
});

describe("brain_append_note - the post-write refresh claim", () => {
  test("an applied append claims one forced refresh: the seam sees force, and the receipt says claimed", async () => {
    // An append writes body bytes, so it is a content edit: the release
    // notes' "a content edit claims" covers it, and an append that left
    // the index stale for an interval would be the gap the claim exists
    // to close.
    seedNote("Notes/Doc.md", "first", "title: Doc");
    await stampIndexStale();
    await mockFreshenSpawned();
    const restore = withIntervalEnv("60");
    try {
      const res = (await appendTool.handler(ctx, {
        path: "Notes/Doc.md",
        content: "second",
      })) as Record<string, unknown>;

      expect(res["appended"]).toBe(true);
      expect(res["index_refresh"]).toBe("claimed");
      expect(res["index_refresh_reason"]).toBeNull();
      expect(forcedCalls).toHaveLength(1);
      expect(forcedCalls[0]!.vault).toBe(vault);
      expect(forcedCalls[0]!.opts["force"]).toBe(true);
    } finally {
      restore();
    }
  });

  test("config off does not claim: the receipt says not_claimed and names off", async () => {
    seedNote("Notes/Doc.md", "first", "title: Doc");
    await stampIndexStale();
    const restore = withIntervalEnv("0");
    try {
      const res = (await appendTool.handler(ctx, {
        path: "Notes/Doc.md",
        content: "second",
      })) as Record<string, unknown>;

      expect(res["appended"]).toBe(true);
      expect(res["index_refresh"]).toBe("not_claimed");
      expect(res["index_refresh_reason"]).toBe("off");
    } finally {
      restore();
    }
  });

  test("a refused append wrote nothing, so it claims nothing", async () => {
    // The typed refusal is thrown before any claim is attempted. The
    // mock is installed and freshening is ON (with a stamped stale
    // index, so a claim that DID run would reach the seam) - the
    // assertion has something to catch: a claim hoisted above the write
    // would light the seam up on its way to the refusal.
    await stampIndexStale();
    await mockFreshenSpawned();
    const restore = withIntervalEnv("60");
    try {
      await rejectedMcpError(appendTool.handler(ctx, { path: "Notes/Ghost.md", content: "x" }));
      expect(forcedCalls).toHaveLength(0);
    } finally {
      restore();
    }
  });
});

describe("brain_append_note", () => {
  test("is registered and requires path and content", () => {
    expect(appendTool).toBeDefined();
    expect(appendTool.inputSchema.required).toContain("path");
    expect(appendTool.inputSchema.required).toContain("content");
  });

  test("appends to the body of an existing note", async () => {
    seedNote("Notes/Doc.md", "first", "title: Doc");
    const res = await appendTool.handler(ctx, { path: "Notes/Doc.md", content: "second" });
    expect(res).toMatchObject({ appended: true, path: "Notes/Doc.md" });
    const md = readFileSync(join(vault, "Notes/Doc.md"), "utf8");
    expect(md).toContain("first");
    expect(md).toContain("second");
    expect(md.indexOf("first")).toBeLessThan(md.indexOf("second"));
  });

  test("a missing target is rejected with INVALID_PARAMS", async () => {
    const err = await rejectedMcpError(
      appendTool.handler(ctx, { path: "Notes/Ghost.md", content: "x" }),
    );
    expect(err.code).toBe(INVALID_PARAMS);
    expect(err.data).toMatchObject({ code: "target_missing", index: 0, path: "Notes/Ghost.md" });
  });

  test("an existing note the host cannot read is refused, not overwritten", async () => {
    mkdirSync(join(vault, "Notes/Doc.md"), { recursive: true });
    // At local reach, for the reason the update case above gives.
    const err = await rejectedMcpError(
      appendTool.handler(
        { ...ctx, reach: TRANSPORT_REACH.local },
        { path: "Notes/Doc.md", content: "more" },
      ),
    );
    expect(err.code).toBe(INTERNAL_ERROR);
    expect(err.data).toMatchObject({ code: "target_unreadable", path: "Notes/Doc.md" });
  });

  test("declares no allow_empty: an append never replaces a body", () => {
    const schema = appendTool.inputSchema as { properties: Record<string, unknown> };
    expect("allow_empty" in schema.properties).toBe(false);
  });

  test("refuses to author into the Brain machinery root", async () => {
    const err = await rejectedMcpError(
      appendTool.handler(ctx, { path: "Brain/x.md", content: "y" }),
    );
    expect(err.code).toBe(INVALID_PARAMS);
    expect(err.data).toMatchObject({ code: "excluded", index: 0 });
  });
});

describe("writeBatchErrorToMcp", () => {
  test("wraps a non-WriteBatchError into a structured INTERNAL_ERROR MCPError", () => {
    const mapped = writeBatchErrorToMcp(new Error("disk exploded"), "brain_update_note");
    expect(mapped).toBeInstanceOf(MCPError);
    expect(mapped.code).toBe(INTERNAL_ERROR);
    expect(mapped.message).toContain("disk exploded");
  });

  test("maps a WriteBatchError onto a structured INVALID_PARAMS", () => {
    const mapped = writeBatchErrorToMcp(
      new WriteBatchError("target_missing", 2, "note does not exist", { path: "Notes/x.md" }),
      "brain_write_batch",
    );
    expect(mapped).toBeInstanceOf(MCPError);
    expect(mapped.code).toBe(INVALID_PARAMS);
    expect(mapped.data).toMatchObject({ code: "target_missing", index: 2, path: "Notes/x.md" });
  });
});

/**
 * Write-time page lint (evidence-at-the-boundary, task A4). Update and
 * append ran NO document validation at all before this: they returned a
 * hardcoded `{updated: true}` over a document that could have no
 * frontmatter, a bogus type, or malformed tags. The lint runs after the
 * commit, reports what a strict create would have refused, and never
 * gates the write.
 */
describe("the lint attached to the update / append receipts", () => {
  /** The handler's declared return is `unknown`; every case here reads keys. */
  const call = async (
    tool: typeof updateTool,
    args: Record<string, unknown>,
  ): Promise<Record<string, unknown>> => (await tool.handler(ctx, args)) as Record<string, unknown>;

  test("a clean update carries the flag, the path and the write id, in that order", async () => {
    seedNote("Notes/Clean.md", "old body", "title: Clean");
    const res = await call(updateTool, { path: "Notes/Clean.md", content: "new body" });
    // The shape is pinned in full so a field cannot arrive unannounced.
    // `write_id` joined it with the note-write record (who-wrote-what,
    // Task A) and is the one key whose VALUE cannot be a literal: it is
    // derived from the instant of the write. The refresh-claim marker
    // joined it when content edits started claiming a refresh (freshening
    // is off suite-wide, so it reads not_claimed with its reason).
    expect(Object.keys(res)).toEqual([
      "updated",
      "path",
      "write_id",
      "index_refresh",
      "index_refresh_reason",
    ]);
    expect(res).toMatchObject({ updated: true, path: "Notes/Clean.md" });
    expect(res["write_id"]).toMatch(NOTE_WRITE_ID_RE);
    // An id present means no audit reason is owed, and the lint has
    // nothing to say about a clean page.
    expect("audit_reason" in res).toBe(false);
    expect(PAGE_LINT_KEY in res).toBe(false);
  });

  test("a clean append carries the flag, the path and the write id, in that order", async () => {
    seedNote("Notes/CleanA.md", "first", "title: CleanA");
    const res = await call(appendTool, { path: "Notes/CleanA.md", content: "second" });
    // The shape is pinned in full so a field cannot arrive unannounced.
    // The refresh-claim marker joined the update receipt when content
    // edits started claiming a refresh, and the append - a content edit
    // of its own - claims under the same vocabulary (freshening is off
    // suite-wide, so it reads not_claimed with its reason).
    expect(Object.keys(res)).toEqual([
      "appended",
      "path",
      "write_id",
      "index_refresh",
      "index_refresh_reason",
    ]);
    expect(res).toMatchObject({ appended: true, path: "Notes/CleanA.md" });
    expect(res["write_id"]).toMatch(NOTE_WRITE_ID_RE);
    expect("audit_reason" in res).toBe(false);
    expect(PAGE_LINT_KEY in res).toBe(false);
  });

  test("an update that breaks the document reports error findings first", async () => {
    seedNote("Notes/Doc.md", "body", "title: Doc");
    const res = await call(updateTool, {
      path: "Notes/Doc.md",
      frontmatter: { type: "not-a-declared-type" },
      content: "see [[pref-ghost]]",
    });
    expect(res).toMatchObject({ updated: true, path: "Notes/Doc.md" });
    const lint = res[PAGE_LINT_KEY] as { findings: ReadonlyArray<Record<string, unknown>> };
    expect(lint.findings[0]).toMatchObject({ severity: "error", code: "schema-type-unknown" });
    expect(lint.findings.map((f) => f["code"])).toContain("broken-wikilink");
  });

  test("an append that introduces a broken link says so without refusing", async () => {
    seedNote("Notes/App.md", "first", "title: App");
    const res = await call(appendTool, {
      path: "Notes/App.md",
      content: "see [[pref-ghost]]",
    });
    expect(res).toMatchObject({ appended: true });
    const lint = res[PAGE_LINT_KEY] as Record<string, unknown>;
    expect(lint).toMatchObject({ total: 1, returned: 1, truncated: false, skipped: [] });
    expect(readFileSync(join(vault, "Notes/App.md"), "utf8")).toContain("[[pref-ghost]]");
  });
});

/**
 * Undated-quantity lint on update and append receipts (write-honesty, F4,
 * t_fb442a24). Both writes succeed; the advisory rides the receipt with the
 * new code. A page already declaring `valid_from` keeps the clean receipt,
 * with no lint key at all.
 */
describe("the undated-quantity lint on update / append receipts", () => {
  const call = async (
    tool: typeof updateTool,
    args: Record<string, unknown>,
  ): Promise<Record<string, unknown>> => (await tool.handler(ctx, args)) as Record<string, unknown>;

  test("an undated numeric update succeeds and carries the finding", async () => {
    seedNote("Notes/UndatedUpdate.md", "old body", "title: U");
    const res = await call(updateTool, {
      path: "Notes/UndatedUpdate.md",
      content: "We onboarded 5,000 users.",
    });
    expect(res).toMatchObject({ updated: true, path: "Notes/UndatedUpdate.md" });
    const lint = res[PAGE_LINT_KEY] as { findings: ReadonlyArray<Record<string, unknown>> };
    expect(lint.findings).toEqual([
      expect.objectContaining({
        severity: "warning",
        code: UNDATED_QUANTITY_CODE,
        page: "Notes/UndatedUpdate.md",
        path: "body",
      }),
    ]);
  });

  test("an update onto a page with valid_from keeps the clean receipt", async () => {
    seedNote("Notes/DatedUpdate.md", "old body", "title: D\nvalid_from: 2026-10-01");
    const res = await call(updateTool, {
      path: "Notes/DatedUpdate.md",
      content: "We onboarded 5,000 users.",
    });
    expect(PAGE_LINT_KEY in res).toBe(false);
    expect(Object.keys(res)).toEqual([
      "updated",
      "path",
      "write_id",
      "index_refresh",
      "index_refresh_reason",
    ]);
  });

  test("an undated numeric append succeeds and carries the finding", async () => {
    seedNote("Notes/UndatedAppend.md", "first", "title: A");
    const res = await call(appendTool, {
      path: "Notes/UndatedAppend.md",
      content: "We onboarded 5,000 users.",
    });
    expect(res).toMatchObject({ appended: true, path: "Notes/UndatedAppend.md" });
    const lint = res[PAGE_LINT_KEY] as { findings: ReadonlyArray<Record<string, unknown>> };
    expect(lint.findings).toEqual([
      expect.objectContaining({
        severity: "warning",
        code: UNDATED_QUANTITY_CODE,
        page: "Notes/UndatedAppend.md",
        path: "body",
      }),
    ]);
  });

  test("an append onto a page with valid_from keeps the clean receipt", async () => {
    seedNote("Notes/DatedAppend.md", "first", "title: D\nvalid_from: 2026-10-01");
    const res = await call(appendTool, {
      path: "Notes/DatedAppend.md",
      content: "We onboarded 5,000 users.",
    });
    expect(PAGE_LINT_KEY in res).toBe(false);
    expect(Object.keys(res)).toEqual([
      "appended",
      "path",
      "write_id",
      "index_refresh",
      "index_refresh_reason",
    ]);
  });
});