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
39.5 KB
Raw Blame
/**
 * Per-page write-time lint (evidence-at-the-boundary, task A4).
 *
 * The vault-wide pass is 359 ms and cannot run per write, so this module
 * re-uses the detectors that already exist against exactly the pages one
 * write touched. These tests pin the properties the envelope promises:
 * a clean page contributes NO key at all, a truncated list declares its
 * truncation, an over-cap page is skipped rather than dropped, and a
 * failure of the lint itself is a named `unavailable` rather than an
 * absence that would read as clean.
 */

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

import {
  NEAR_DUPLICATE_CODE,
  NEAR_DUPLICATE_JACCARD,
  NEAR_DUPLICATE_MAX_CANDIDATES,
  PAGE_LINT_KEY,
  PAGE_LINT_MAX_FINDINGS,
  PAGE_LINT_SKIP_REASON,
  PAGE_LINT_UNAVAILABLE_CODE,
  UNDATED_QUANTITY_CODE,
  comparePageLintFindings,
  lintPagesWithContext,
  lintWrittenPages,
  pageLintField,
  type LintContext,
  type NearDuplicateCandidate,
} from "../../../src/core/brain/page-lint.ts";
import { LINT_CONSOLIDATE_KIND } from "../../../src/core/brain/lint-consolidate.ts";
import {
  NEAR_DUPLICATE_MIN_TOKENS,
  NEAR_DUPLICATE_THRESHOLDS,
  READ_ALL_REFS,
} from "../../../src/core/brain/near-duplicate.ts";
import { loadSchemaPack } from "../../../src/core/brain/schema-pack.ts";
import { tokenise } from "../../../src/core/brain/similarity.ts";
import { ARTIFACT_MAX_BYTES } from "../../../src/core/brain/write-session/validate.ts";

let vault: string;

/** Operator reach: every page readable. */
const READ_ALL = { readable: READ_ALL_REFS } as const;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-page-lint-"));
  for (const dir of ["preferences", "retired", "log", "inbox"]) {
    mkdirSync(join(vault, "Brain", dir), { recursive: true });
  }
  mkdirSync(join(vault, "Notes"), { recursive: true });
});

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

function writeNote(rel: string, text: string): string {
  const abs = join(vault, rel);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(abs, text, "utf8");
  return rel;
}

/** The report's near-duplicate findings, filtered by the one detector code. */
function nearDuplicateFindings(report: ReturnType<typeof lintWrittenPages>) {
  return report.findings.filter((f) => f.code === NEAR_DUPLICATE_CODE);
}

function writePref(slug: string, fields: Record<string, string> = {}): void {
  const lines = ["---", `id: pref-${slug}`, "topic: x", "principle: y"];
  for (const [k, v] of Object.entries(fields)) lines.push(`${k}: ${v}`);
  lines.push("---", "");
  writeFileSync(join(vault, "Brain", "preferences", `pref-${slug}.md`), lines.join("\n"), "utf8");
}

describe("lintWrittenPages - the clean path", () => {
  test("a valid page with no broken links yields nothing to say", () => {
    const rel = writeNote("Notes/Clean.md", "---\ntitle: Clean\n---\n\nplain prose\n");
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings).toEqual([]);
    expect(report.total).toBe(0);
    expect(report.returned).toBe(0);
    expect(report.truncated).toBe(false);
    expect(report.skipped).toEqual([]);
    expect(report.unavailable).toBeUndefined();
    expect(pageLintField(report)).toEqual({});
  });

  test("a wikilink to a non-Brain note is nobody's business here", () => {
    writeNote("Notes/Other.md", "---\ntitle: Other\n---\n\nx\n");
    const rel = writeNote("Notes/Links.md", "---\ntitle: Links\n---\n\nsee [[Other]]\n");
    expect(lintWrittenPages(vault, [rel], READ_ALL).findings).toEqual([]);
  });
});

describe("lintWrittenPages - findings", () => {
  test("a broken Brain wikilink is one warning carrying a next command", () => {
    const rel = writeNote("Notes/Broken.md", "---\ntitle: B\n---\n\nsee [[pref-ghost]]\n");
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings.length).toBe(1);
    expect(report.findings[0]).toMatchObject({
      severity: "warning",
      code: "broken-wikilink",
      page: rel,
      path: "pref-ghost",
      next_command: "o2b brain doctor --repair --apply",
    });
    expect(report.total).toBe(1);
    expect(report.returned).toBe(1);
    expect(report.truncated).toBe(false);
  });

  test("an escaped bracket opens no wikilink to lint", () => {
    // `\[[pref-ghost]]` is literal text by the same odd-backslash-run
    // rule every link reader applies; it names no target, so it raises
    // no broken-link row, while a link after an even run stays live.
    const escaped = writeNote("Notes/Escaped.md", "---\ntitle: E\n---\n\nsee \\[[pref-ghost]]\n");
    expect(lintWrittenPages(vault, [escaped], READ_ALL).findings).toEqual([]);
    const closed = writeNote("Notes/EscClose.md", "---\ntitle: C\n---\n\nsee [[pref-ghost\\]]\n");
    expect(lintWrittenPages(vault, [closed], READ_ALL).findings).toEqual([]);
    const live = writeNote("Notes/Live.md", "---\ntitle: L\n---\n\nsee \\\\[[pref-ghost]]\n");
    const report = lintWrittenPages(vault, [live], READ_ALL);
    expect(report.findings.length).toBe(1);
    expect(report.findings[0]).toMatchObject({ code: "broken-wikilink", path: "pref-ghost" });
  });

  test("a link to a merged page names the FULLY resolved canonical target", () => {
    writePref("canon");
    writePref("mid", { merged_into: "pref-canon" });
    writePref("dup", { merged_into: "pref-mid" });
    const rel = writeNote("Notes/Merged.md", "---\ntitle: M\n---\n\nsee [[pref-dup]]\n");
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings.length).toBe(1);
    expect(report.findings[0]).toMatchObject({
      severity: "warning",
      code: LINT_CONSOLIDATE_KIND.mergedLink,
      page: rel,
      path: "pref-dup",
    });
    expect(report.findings[0]!.message).toContain("pref-canon");
    expect(report.findings[0]!.next_command).toBe("o2b brain lint --consolidate --apply --yes");
  });

  test("an invalid document reports error findings, ranked ahead of warnings", () => {
    const rel = writeNote("Notes/Invalid.md", "no frontmatter at all, see [[pref-ghost]]\n");
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings.length).toBeGreaterThanOrEqual(2);
    expect(report.findings[0]!.severity).toBe("error");
    expect(report.findings[0]!.code).toBe("frontmatter-missing");
    expect(report.findings.at(-1)!.severity).toBe("warning");
    expect(pageLintField(report)).toMatchObject({ [PAGE_LINT_KEY]: { total: report.total } });
  });

  test("a declared type outside the schema pack is an error finding", () => {
    const rel = writeNote("Notes/Typed.md", "---\ntitle: T\ntype: not-a-declared-type\n---\n\nx\n");
    const codes = lintWrittenPages(vault, [rel], READ_ALL).findings.map((f) => f.code);
    expect(codes).toContain("schema-type-unknown");
  });
});

/**
 * The fifth detector (write-honesty, F4, t_fb442a24). A count or amount
 * with no structural date is an advisory warning on the `body` path: the
 * page states a quantity a reader cannot place in time. The escape hatches
 * are structural, never natural language - `valid_from` in frontmatter, an
 * ISO date in the body's claim-bearing prose, or a
 * `[Source: <name>, YYYY-MM-DD]` marker.
 */
describe("lintWrittenPages - undated-quantity findings", () => {
  const BODY = "We onboarded 5,000 users.";
  const QUANTITY = "5,000 users";

  function undatedFindings(report: ReturnType<typeof lintWrittenPages>) {
    return report.findings.filter((f) => f.code === UNDATED_QUANTITY_CODE);
  }

  test("an undated numeric note is exactly one warning on the body path", () => {
    const rel = writeNote("Notes/Undated.md", `---\ntitle: U\n---\n\n${BODY}\n`);
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    const findings = undatedFindings(report);
    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      severity: "warning",
      code: UNDATED_QUANTITY_CODE,
      page: rel,
      path: "body",
    });
    // The finding quotes the lexeme and its offset, never the raw line.
    expect(findings[0]!.message).toContain(JSON.stringify(QUANTITY));
    expect(findings[0]!.message).toContain(`offset ${BODY.indexOf(QUANTITY)}`);
    expect(findings[0]!.message).not.toContain("onboarded");
    expect(report.total).toBe(1);
    expect(pageLintField(report)).toMatchObject({ [PAGE_LINT_KEY]: { total: 1 } });
  });

  test("valid_from in frontmatter silences the finding and keeps the key absent", () => {
    const rel = writeNote(
      "Notes/DatedFrontmatter.md",
      `---\ntitle: D\nvalid_from: 2026-10-01\n---\n\n${BODY}\n`,
    );
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings).toEqual([]);
    expect(pageLintField(report)).toEqual({});
  });

  test("a valid_from that names no date does not silence the finding", () => {
    // The hatch is structural: a value that places nothing in time (TBD,
    // unknown, soon) is not a date, and treating any non-empty string as
    // one let a placeholder boundary quiet the lint.
    const rel = writeNote(
      "Notes/UndatedFrontmatter.md",
      `---\ntitle: D\nvalid_from: TBD\n---\n\n${BODY}\n`,
    );
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings.map((f) => f.code)).toContain(UNDATED_QUANTITY_CODE);
  });

  test("an ISO date in the body silences the finding", () => {
    const rel = writeNote(
      "Notes/DatedBody.md",
      `---\ntitle: D\n---\n\nOn 2026-10-01 ${BODY.toLowerCase()}\n`,
    );
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(undatedFindings(report)).toEqual([]);
    expect(pageLintField(report)).toEqual({});
  });

  test("a date inside a fence, a URL or a wikilink target silences nothing", () => {
    // The hatch reads the masked view the scanner scans: a date in a
    // region that carries no claim must not quiet the quantities in the
    // prose around it.
    const rel = writeNote(
      "Notes/MaskedDate.md",
      "---\ntitle: M\n---\n\n```\n2026-10-01\n```\n\n" +
        "see https://x.com/posts/2026-10-01 and [[Report 2026-10-01]]\n\n" +
        `${BODY}\n`,
    );
    const findings = undatedFindings(lintWrittenPages(vault, [rel], READ_ALL));
    expect(findings).toHaveLength(1);
    expect(findings[0]!.message).toContain(JSON.stringify(QUANTITY));
  });

  test("the offset is named as a post-frontmatter body coordinate, not a file offset", () => {
    const raw = `---\ntitle: U\n---\n\n   ${BODY}\n`;
    const rel = writeNote("Notes/OffsetCoordinate.md", raw);
    const finding = undatedFindings(lintWrittenPages(vault, [rel], READ_ALL))[0]!;
    // The scanner sees the trimmed body, so the lexeme sits at its body
    // offset; in the raw file it sits later by the frontmatter and the
    // leading blank line and spaces. The message names the coordinate
    // system, so the number can be located honestly.
    expect(finding.message).toContain(
      `at body offset ${BODY.indexOf(QUANTITY)} (after frontmatter)`,
    );
    expect(finding.message).not.toContain(`offset ${raw.indexOf(QUANTITY)}`);
  });

  test("a [Source: <name>, YYYY-MM-DD] marker silences the finding", () => {
    const rel = writeNote(
      "Notes/Cited.md",
      `---\ntitle: C\n---\n\n${QUANTITY} [Source: annual report, 2026-10-01]\n`,
    );
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(undatedFindings(report)).toEqual([]);
    expect(pageLintField(report)).toEqual({});
  });

  test("a version token, a table row and a code span are not quantities", () => {
    const rel = writeNote(
      "Notes/NotQuantities.md",
      "---\ntitle: N\n---\n\nupgraded to v1.73.0\n\n| 5,000 users | 35% |\n\n`5,000 users`\n",
    );
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(undatedFindings(report)).toEqual([]);
    expect(pageLintField(report)).toEqual({});
  });

  test("the finding cap still counts what it drops", () => {
    const lines = Array.from({ length: PAGE_LINT_MAX_FINDINGS + 2 }, () => "5 users").join("\n");
    const rel = writeNote("Notes/ManyUndated.md", `---\ntitle: M\n---\n\n${lines}\n`);
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.total).toBe(PAGE_LINT_MAX_FINDINGS + 2);
    expect(report.returned).toBe(PAGE_LINT_MAX_FINDINGS);
    expect(report.truncated).toBe(true);
    expect(report.findings.every((f) => f.code === UNDATED_QUANTITY_CODE)).toBe(true);
  });
});

describe("lintWrittenPages - bounds", () => {
  test("a page over the artifact byte cap is skipped with a reason, never dropped", () => {
    const filler = "x".repeat(ARTIFACT_MAX_BYTES + 1024);
    const rel = writeNote("Notes/Huge.md", `---\ntitle: H\n---\n\n${filler}\n`);
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings).toEqual([]);
    expect(report.skipped).toEqual([
      { page: rel, reason: PAGE_LINT_SKIP_REASON.overByteCap, detail: expect.any(String) },
    ]);
    expect(pageLintField(report)).toMatchObject({ [PAGE_LINT_KEY]: { skipped: report.skipped } });
  });

  test("a truncated finding list declares total, returned and truncated", () => {
    const links = Array.from(
      { length: PAGE_LINT_MAX_FINDINGS + 5 },
      (_, i) => `see [[pref-ghost-${i}]]`,
    ).join("\n");
    const rel = writeNote("Notes/Many.md", `---\ntitle: M\n---\n\n${links}\n`);
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.total).toBe(PAGE_LINT_MAX_FINDINGS + 5);
    expect(report.returned).toBe(PAGE_LINT_MAX_FINDINGS);
    expect(report.findings.length).toBe(PAGE_LINT_MAX_FINDINGS);
    expect(report.truncated).toBe(true);
  });

  test("an unreadable page is skipped with its own reason", () => {
    const report = lintWrittenPages(vault, ["Notes/NeverWritten.md"], READ_ALL);
    expect(report.findings).toEqual([]);
    expect(report.skipped.map((s) => s.reason)).toEqual([PAGE_LINT_SKIP_REASON.unreadable]);
  });
});

/**
 * The report crosses the MCP wire on all four write tools, so it obeys the
 * rule the rest of this release applies to that channel: identifiers and
 * integers, never a path and never a kernel sentence. Node renders an errno
 * as `ENOENT: no such file or directory, stat '/home/<user>/<vault>/x.md'`,
 * which is the operator's home directory in a write receipt.
 */
describe("lintWrittenPages - nothing of the operator's filesystem crosses the wire", () => {
  test("an unreadable page carries the errno CODE, not the kernel's sentence", () => {
    const report = lintWrittenPages(vault, ["Notes/NeverWritten.md"], READ_ALL);
    expect(report.skipped).toEqual([
      {
        page: "Notes/NeverWritten.md",
        reason: PAGE_LINT_SKIP_REASON.unreadable,
        detail: "ENOENT",
      },
    ]);
    expect(JSON.stringify(report)).not.toContain(vault);
  });

  test("a lint that cannot start names its errno code and no path", () => {
    mkdirSync(join(vault, "Brain", "_brain.yaml"), { recursive: true });
    const rel = writeNote("Notes/Any.md", "---\ntitle: A\n---\n\nx\n");
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.unavailable!.message).not.toContain(vault);
    expect(report.unavailable!.message).toMatch(/could not start: [A-Za-z][A-Za-z0-9_]*$/);
  });

  test("an over-cap skip is stated in bytes, which name nothing on disk", () => {
    const rel = writeNote("Notes/Huge.md", "x".repeat(ARTIFACT_MAX_BYTES + 8));
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.skipped[0]!.reason).toBe(PAGE_LINT_SKIP_REASON.overByteCap);
    expect(JSON.stringify(report)).not.toContain(vault);
  });
});

/**
 * A page the lint THREW on is one page's worth of bad news, not the whole
 * report's. The failure is accumulated per page so the findings already
 * collected survive and the pages after it are still linted - the report
 * already has an honest shape for saying part of it could not be produced.
 *
 * No filesystem state reaches this branch (every reader inside `lintOnePage`
 * either cannot throw or catches its own errors), so it is exercised through
 * the context seam with a resolver that throws.
 */
describe("lintPagesWithContext - one page's failure is not the report's", () => {
  function throwingContext(reason: Error): LintContext {
    return {
      basenames: new Set<string>(),
      vocabulary: loadSchemaPack(vault).vocabulary,
      nearDuplicateCandidates: new Map<string, ReadonlyArray<NearDuplicateCandidate>>(),
      readable: READ_ALL_REFS,
      mergedLinks: {
        resolve() {
          throw reason;
        },
      },
    };
  }

  test("the failing page is a skip and the pages around it still report", () => {
    const first = writeNote("Notes/First.md", "---\ntitle: F\n---\n\nsee [[pref-ghost]]\n");
    const second = writeNote("Notes/Second.md", "no frontmatter at all\n");
    const report = lintPagesWithContext(
      vault,
      throwingContext(Object.assign(new Error("read failed"), { code: "EIO" })),
      [first, second],
    );
    expect(report.skipped).toEqual([
      { page: first, reason: PAGE_LINT_SKIP_REASON.lintFailed, detail: "EIO" },
    ]);
    // The second page never reaches the resolver (it has no wikilink), so its
    // finding is the proof that the walk continued past the failure.
    expect(report.findings.map((f) => f.code)).toEqual(["frontmatter-missing"]);
    expect(report.total).toBe(1);
    expect(report.unavailable).toBeUndefined();
  });

  test("a failure carrying no errno is named by its class, never by its message", () => {
    const rel = writeNote("Notes/Third.md", "---\ntitle: T\n---\n\nsee [[pref-ghost]]\n");
    const report = lintPagesWithContext(vault, throwingContext(new TypeError("/home/x/vault/x")), [
      rel,
    ]);
    expect(report.skipped).toEqual([
      { page: rel, reason: PAGE_LINT_SKIP_REASON.lintFailed, detail: "TypeError" },
    ]);
    expect(JSON.stringify(report)).not.toContain("/home/x/vault");
  });
});

describe("lintWrittenPages - failure is named, never absent", () => {
  test("a lint that cannot run reports unavailable rather than a missing key", () => {
    // `Brain/_brain.yaml` as a directory: the schema pack read throws
    // EISDIR, which is a failure of the LINT, not of the page.
    mkdirSync(join(vault, "Brain", "_brain.yaml"), { recursive: true });
    const rel = writeNote("Notes/Any.md", "---\ntitle: A\n---\n\nx\n");
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.unavailable).toMatchObject({ code: PAGE_LINT_UNAVAILABLE_CODE });
    expect(report.unavailable!.message.length).toBeGreaterThan(0);
    expect(report.total).toBe(0);
    expect(report.returned).toBe(0);
    expect(report.truncated).toBe(false);
    expect(report.skipped).toEqual([]);
    // The whole point: the key is PRESENT, so absence still means clean.
    expect(pageLintField(report)).toMatchObject({
      [PAGE_LINT_KEY]: { unavailable: report.unavailable },
    });
  });
});

describe("comparePageLintFindings", () => {
  test("errors sort ahead of warnings, then by page, then by code", () => {
    const warning = {
      severity: "warning",
      code: "broken-wikilink",
      page: "a.md",
      path: "pref-x",
      message: "m",
    } as const;
    const error = {
      severity: "error",
      code: "tags-malformed",
      page: "z.md",
      path: "tags",
      message: "m",
    } as const;
    expect(comparePageLintFindings(warning, error)).toBeGreaterThan(0);
    expect(comparePageLintFindings(error, warning)).toBeLessThan(0);
    expect(comparePageLintFindings(error, error)).toBe(0);
  });
});

describe("pageLintField", () => {
  test("null contributes no key whatsoever", () => {
    expect(pageLintField(null)).toEqual({});
    expect(PAGE_LINT_KEY in pageLintField(null)).toBe(false);
  });
});

/**
 * The near-duplicate detector (t_d30c0548). A write that closely matches an
 * existing page in the SAME directory and the SAME composite scope bucket is
 * reported on the receipt as a `near-duplicate` finding - never gating the
 * write, never touching frontmatter, and never normalizing the body. The
 * comparison reuses the shared `tokenise`/`jaccard` primitives against the
 * named NEAR_DUPLICATE_JACCARD constant.
 */
describe("lintWrittenPages - near-duplicate findings", () => {
  const ALPHA_BODY = "alpha beta gamma delta epsilon";

  function alphaNote(title: string, frontmatterLines: string[] = []): string {
    const lines = ["---", `title: ${title}`, ...frontmatterLines, "---", "", ALPHA_BODY, ""];
    return lines.join("\n");
  }

  test("NEAR_DUPLICATE_JACCARD is the designed threshold, a named constant", () => {
    expect(NEAR_DUPLICATE_JACCARD).toBe(0.8);
    expect(NEAR_DUPLICATE_JACCARD).toBe(NEAR_DUPLICATE_THRESHOLDS.writeHint);
  });

  test("a same-directory finding is byte-identical to the shipped receipt", () => {
    const first = writeNote("Notes/Alpha.md", alphaNote("Alpha"));
    const rel = writeNote("Notes/Beta.md", alphaNote("Beta"));
    expect(nearDuplicateFindings(lintWrittenPages(vault, [rel], READ_ALL))).toEqual([
      {
        severity: "warning",
        code: NEAR_DUPLICATE_CODE,
        page: rel,
        path: first,
        message: `body resembles [[${first}]] jaccard=1.000 (threshold 0.8)`,
      },
    ]);
  });

  test("same-directory stubs below the kernel's token floor are not reported", () => {
    // Three tokens each: identical bodies, a jaccard=1.000 finding before the
    // shared kernel's minimum token count.
    const stub = "alpha beta gamma";
    expect(tokenise(stub).size).toBe(NEAR_DUPLICATE_MIN_TOKENS - 1);
    writeNote("Notes/Alpha.md", `---\ntitle: Alpha\n---\n\n${stub}\n`);
    const rel = writeNote("Notes/Beta.md", `---\ntitle: Beta\n---\n\n${stub}\n`);
    expect(nearDuplicateFindings(lintWrittenPages(vault, [rel], READ_ALL))).toEqual([]);
  });

  test("a write closely matching a same-directory same-scope page yields the finding", () => {
    const first = writeNote("Notes/Alpha.md", alphaNote("Alpha"));
    const rel = writeNote("Notes/Beta.md", alphaNote("Beta"));
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    const findings = nearDuplicateFindings(report);
    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      severity: "warning",
      page: rel,
      path: first,
    });
    // Evidence is in the message: the pair and the exact score.
    expect(findings[0]!.message).toContain(first);
    expect(findings[0]!.message).toContain("jaccard=1.000");
    // An advisory with a content-judgement repair carries no registered exit.
    expect(findings[0]!.next_command).toBeUndefined();
  });

  test("a resemblance at exactly the threshold is reported, carrying its score", () => {
    // 4 shared tokens over a 5-token union is exactly 4/5 = 0.8.
    writeNote("Notes/Alpha.md", `---\ntitle: Alpha\n---\n\n${ALPHA_BODY}\n`);
    const rel = writeNote("Notes/Beta.md", "---\ntitle: Beta\n---\n\nalpha beta gamma delta\n");
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    const findings = nearDuplicateFindings(report);
    expect(findings).toHaveLength(1);
    expect(findings[0]!.message).toContain("jaccard=0.800");
  });

  test("a below-threshold resemblance yields nothing", () => {
    writeNote("Notes/Alpha.md", alphaNote("Alpha"));
    const rel = writeNote("Notes/Beta.md", "---\ntitle: Beta\n---\n\nalpha zeta eta theta iota\n");
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings).toEqual([]);
    expect(pageLintField(report)).toEqual({});
  });

  test("a same-body page in a different directory is not a candidate", () => {
    writeNote("Elsewhere/Alpha.md", alphaNote("Alpha"));
    const rel = writeNote("Notes/Beta.md", alphaNote("Beta"));
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings).toEqual([]);
  });

  test("a same-body page in a different scope bucket is not a candidate", () => {
    writeNote("Notes/Alpha.md", alphaNote("Alpha", ["session: atlas"]));
    const rel = writeNote("Notes/Beta.md", alphaNote("Beta"));
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings).toEqual([]);
  });

  test("a same-body page in the SAME scope bucket is a candidate", () => {
    writeNote("Notes/Alpha.md", alphaNote("Alpha", ["session: atlas"]));
    const rel = writeNote("Notes/Beta.md", alphaNote("Beta", ["session: atlas"]));
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(nearDuplicateFindings(report)).toHaveLength(1);
  });

  test("frontmatter is never compared: differing frontmatter does not suppress the finding", () => {
    // Same authored body, different non-scope frontmatter. (`owner` would
    // be a REAL difference - it is a scope axis - so it must not appear here.)
    writeNote("Notes/Alpha.md", `---\ntitle: Alpha\ntype: note\n---\n\n${ALPHA_BODY}\n`);
    const rel = writeNote("Notes/Beta.md", alphaNote("Beta"));
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(nearDuplicateFindings(report)).toHaveLength(1);
  });

  test("frontmatter is never compared: identical frontmatter alone creates no finding", () => {
    writeNote("Notes/Alpha.md", "---\ntitle: Same\ntype: note\n---\n\none kind of prose\n");
    const rel = writeNote(
      "Notes/Beta.md",
      "---\ntitle: Same\ntype: note\n---\n\nanother kind entirely\n",
    );
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings).toEqual([]);
  });

  test("a directory over the candidate cap reads only the newest siblings and counts the rest", () => {
    const extra = 3;
    const oldest = Date.parse("2026-01-01T00:00:00Z");
    for (let i = 0; i < NEAR_DUPLICATE_MAX_CANDIDATES + extra; i++) {
      const rel = writeNote(`Notes/Filler-${i}.md`, `---\ntitle: F${i}\n---\n\nfiller ${i}\n`);
      const at = new Date(oldest + i * 1000);
      utimesSync(join(vault, rel), at, at);
    }
    const rel = writeNote("Notes/Beta.md", alphaNote("Beta"));
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    // The written page is the newest sibling, so the cap leaves out the oldest fillers.
    expect(report.candidates_skipped).toBe(extra + 1);
    expect(pageLintField(report)).toHaveProperty("lint");
  });

  test("the written page never resembles itself", () => {
    const rel = writeNote("Notes/Alpha.md", alphaNote("Alpha"));
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.findings).toEqual([]);
  });

  test("two near-identical pages written in one call report each other", () => {
    const first = writeNote("Notes/Alpha.md", alphaNote("Alpha"));
    const second = writeNote("Notes/Beta.md", alphaNote("Beta"));
    const report = lintWrittenPages(vault, [first, second], READ_ALL);
    const pairs = nearDuplicateFindings(report)
      .map((f) => `${f.page} -> ${f.path}`)
      .toSorted();
    expect(pairs).toEqual([`${first} -> ${second}`, `${second} -> ${first}`]);
  });

  test("a candidate that cannot be read is excluded by name, not a lint failure", () => {
    // A DIRECTORY named like a page: reading it throws EISDIR. It cannot
    // provide evidence, so it is not a candidate - the same posture the
    // write-conflict advisory takes toward corrupt preference files.
    mkdirSync(join(vault, "Notes", "Stuck.md"), { recursive: true });
    const rel = writeNote("Notes/Beta.md", alphaNote("Beta"));
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.unavailable).toBeUndefined();
    expect(report.findings).toEqual([]);
    // Excluded by name, with the errno code, never silently.
    expect(report.candidates_unreadable).toEqual([{ page: "Notes/Stuck.md", detail: "EISDIR" }]);
  });

  test("a candidate over the artifact byte cap is not read as a candidate", () => {
    const filler = `${ALPHA_BODY} `.repeat(ARTIFACT_MAX_BYTES / ALPHA_BODY.length + 1);
    writeNote("Notes/Alpha.md", `---\ntitle: Alpha\n---\n\n${filler}\n`);
    const rel = writeNote("Notes/Beta.md", alphaNote("Beta"));
    const report = lintWrittenPages(vault, [rel], READ_ALL);
    expect(report.unavailable).toBeUndefined();
    expect(report.findings).toEqual([]);
    // The skip list stays reserved for WRITTEN pages.
    expect(report.skipped).toEqual([]);
  });

  test("a page spelled outside the vault collects no candidates from outside it", () => {
    // The write kernel refuses traversal, so this spelling can only reach
    // the lint from a caller; the candidate walk must still stop at the
    // vault boundary instead of reading the vault's parent directory.
    const outside = mkdtempSync(join(tmpdir(), "o2b-page-lint-out-"));
    try {
      const alphaNoteText = alphaNote("Sibling");
      writeFileSync(join(outside, "Sibling.md"), alphaNoteText, "utf8");
      writeFileSync(join(outside, "Escaped.md"), alphaNoteText, "utf8");
      // vault/../Escaped.md IS the file written above - the same bytes as
      // its neighbor, yet no near-duplicate may be reported about them.
      const report = lintWrittenPages(vault, ["../Escaped.md"], READ_ALL);
      expect(report.unavailable).toBeUndefined();
      expect(report.findings.filter((f) => f.code === NEAR_DUPLICATE_CODE)).toEqual([]);
    } finally {
      rmSync(outside, { recursive: true, force: true });
    }
  });
});

/**
 * The receipt answers at the caller's reach. A sibling the caller may not
 * read is dropped before it is scored and before any census counts it, so
 * neither a finding nor `candidates_skipped` nor `candidates_unreadable`
 * can disclose that it exists.
 */
describe("lintWrittenPages - near-duplicate candidates at the caller's reach", () => {
  const BODY = "alpha beta gamma delta epsilon";
  const HIDDEN_PREFIX = "Notes/Hidden-";
  const withholdHidden = { readable: (rel: string) => !rel.startsWith(HIDDEN_PREFIX) } as const;

  function note(title: string): string {
    return `---\ntitle: ${title}\n---\n\n${BODY}\n`;
  }

  test("a withheld near-identical sibling is neither scored nor named", () => {
    writeNote("Notes/Hidden-Alpha.md", note("Alpha"));
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const report = lintWrittenPages(vault, [rel], withholdHidden);
    expect(report.findings).toEqual([]);
    expect(JSON.stringify(report)).not.toContain("Hidden-Alpha");
    // A clean write still contributes no key at all.
    expect(pageLintField(report)).toEqual({});
  });

  test("the same sibling at full reach is reported, so the filter is what hid it", () => {
    const sibling = writeNote("Notes/Hidden-Alpha.md", note("Alpha"));
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const findings = nearDuplicateFindings(lintWrittenPages(vault, [rel], READ_ALL));
    expect(findings.map((f) => f.path)).toEqual([sibling]);
  });

  test("a withheld sibling that cannot be read is not counted as unreadable", () => {
    mkdirSync(join(vault, "Notes", "Hidden-Stuck.md"), { recursive: true });
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const report = lintWrittenPages(vault, [rel], withholdHidden);
    expect(report.candidates_unreadable).toBeUndefined();
    expect(pageLintField(report)).toEqual({});
  });

  test("withheld siblings never count toward the candidate cap", () => {
    const oldest = Date.parse("2026-01-01T00:00:00Z");
    for (let i = 0; i < NEAR_DUPLICATE_MAX_CANDIDATES + 3; i++) {
      const rel = writeNote(`${HIDDEN_PREFIX}${i}.md`, `---\ntitle: H${i}\n---\n\nfiller ${i}\n`);
      const at = new Date(oldest + i * 1000);
      utimesSync(join(vault, rel), at, at);
    }
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const report = lintWrittenPages(vault, [rel], withholdHidden);
    expect(report.candidates_skipped).toBeUndefined();
    expect(pageLintField(report)).toEqual({});
  });

  test("the predicate is asked about vault-relative paths", () => {
    writeNote("Notes/Alpha.md", note("Alpha"));
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const asked: string[] = [];
    lintWrittenPages(vault, [rel], {
      readable: (path) => {
        asked.push(path);
        return true;
      },
    });
    expect([...new Set(asked)].toSorted()).toEqual(["Notes/Alpha.md", "Notes/Beta.md"]);
  });
});

/**
 * The wikilink and merged-link findings answer at the caller's reach too. A
 * Brain page the caller may not read must produce the receipt a vault
 * without that page produces, byte for byte, whichever finding it would
 * otherwise have shaped.
 */
describe("lintWrittenPages - link findings at the caller's reach", () => {
  const prefPath = (slug: string) => `Brain/preferences/pref-${slug}.md`;
  const withhold = (slug: string) => ({ readable: (rel: string) => rel !== prefPath(slug) });

  /** The report with `slug` withheld, then the report with `slug` deleted. */
  function withheldThenAbsent(slug: string, rel: string): [string, string] {
    const withheld = JSON.stringify(lintWrittenPages(vault, [rel], withhold(slug)));
    unlinkSync(join(vault, prefPath(slug)));
    return [withheld, JSON.stringify(lintWrittenPages(vault, [rel], READ_ALL))];
  }

  test("a link to a withheld page is reported as broken, as an absent one is", () => {
    writePref("hidden");
    const rel = writeNote("Notes/Links.md", "---\ntitle: L\n---\n\nsee [[pref-hidden]]\n");
    expect(lintWrittenPages(vault, [rel], READ_ALL).findings).toEqual([]);
    const [withheld, absent] = withheldThenAbsent("hidden", rel);
    expect(withheld).toBe(absent);
    expect(withheld).toContain("broken-wikilink");
  });

  test("a withheld merged-away target is not followed into its canonical", () => {
    writePref("canon");
    writePref("dup", { merged_into: "pref-canon" });
    const rel = writeNote("Notes/Merged.md", "---\ntitle: M\n---\n\nsee [[pref-dup]]\n");
    const [withheld, absent] = withheldThenAbsent("dup", rel);
    expect(withheld).toBe(absent);
    expect(withheld).not.toContain("pref-canon");
  });

  test("a merge chain ends at a withheld hop and names nothing past it", () => {
    writePref("canon");
    writePref("mid", { merged_into: "pref-canon" });
    writePref("dup", { merged_into: "pref-mid" });
    const rel = writeNote("Notes/Merged.md", "---\ntitle: M\n---\n\nsee [[pref-dup]]\n");
    const [withheld, absent] = withheldThenAbsent("mid", rel);
    expect(withheld).toBe(absent);
    expect(withheld).toContain("merged into pref-mid");
    expect(withheld).not.toContain("pref-canon");
  });
});

/**
 * Widening: candidates from outside the written page's directory, handed in
 * by the keyword-index collector. They are scored through the same kernel
 * under the same scope-bucket rule; a cross-directory finding keeps the
 * `near-duplicate` code and names its method, and the report states whether
 * widening ran only when the caller says it was asked to.
 */
describe("lintWrittenPages - widened near-duplicate candidates", () => {
  const BODY = "alpha beta gamma delta epsilon";

  function note(title: string): string {
    return `---\ntitle: ${title}\n---\n\n${BODY}\n`;
  }

  function candidate(page: string, scopeKey = ""): NearDuplicateCandidate {
    return { page, scopeKey, tokens: new Set(BODY.split(" ")) };
  }

  test("a cross-directory candidate yields the same code with the method in the message", () => {
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const report = lintWrittenPages(vault, [rel], {
      ...READ_ALL,
      extraCandidates: [candidate("Projects/Alpha.md")],
      widening: "used",
    });
    expect(nearDuplicateFindings(report)).toEqual([
      {
        severity: "warning",
        code: NEAR_DUPLICATE_CODE,
        page: rel,
        path: "Projects/Alpha.md",
        message:
          "body resembles [[Projects/Alpha.md]] jaccard=1.000 (threshold 0.8) method=lexical",
      },
    ]);
    expect(report.widening).toBe("used");
  });

  test("a widened candidate already in the directory is reported once, as shipped", () => {
    const first = writeNote("Notes/Alpha.md", note("Alpha"));
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const findings = nearDuplicateFindings(
      lintWrittenPages(vault, [rel], {
        ...READ_ALL,
        extraCandidates: [candidate(first)],
        widening: "used",
      }),
    );
    expect(findings.map((f) => f.message)).toEqual([
      `body resembles [[${first}]] jaccard=1.000 (threshold 0.8)`,
    ]);
  });

  test("a widened candidate in another scope bucket is not reported", () => {
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const report = lintWrittenPages(vault, [rel], {
      ...READ_ALL,
      extraCandidates: [candidate("Projects/Alpha.md", "session=atlas")],
      widening: "used",
    });
    expect(report.findings).toEqual([]);
  });

  test("a widened candidate outside the caller's reach is not reported", () => {
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const report = lintWrittenPages(vault, [rel], {
      readable: (page) => page !== "Projects/Alpha.md",
      extraCandidates: [candidate("Projects/Alpha.md")],
      widening: "used",
    });
    expect(report.findings).toEqual([]);
  });

  test("the widening status is absent unless passed, and a clean used widening says nothing", () => {
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const off = lintWrittenPages(vault, [rel], READ_ALL);
    expect("widening" in off).toBe(false);
    const used = lintWrittenPages(vault, [rel], { ...READ_ALL, widening: "used" });
    expect(used.widening).toBe("used");
    expect(pageLintField(used)).toEqual({});
  });

  test("an unavailable index is stated on the receipt", () => {
    const rel = writeNote("Notes/Beta.md", note("Beta"));
    const report = lintWrittenPages(vault, [rel], {
      ...READ_ALL,
      extraCandidates: [],
      widening: "index_unavailable",
      wideningDetail: "INDEX_LOCKED",
    });
    expect(pageLintField(report)).toMatchObject({
      [PAGE_LINT_KEY]: { widening: "index_unavailable", widening_detail: "INDEX_LOCKED" },
    });
  });
});

/**
 * A caller already holding the indexes can lint with them - including the
 * near-duplicate candidate index, so the seam stays honest about what is
 * precomputed per call versus read per page.
 */
describe("lintPagesWithContext - caller-supplied near-duplicate candidates", () => {
  test("a candidate in the index drives the same finding", () => {
    const rel = writeNote(
      "Notes/Beta.md",
      "---\ntitle: Beta\n---\n\nalpha beta gamma delta epsilon\n",
    );
    const candidates: ReadonlyArray<NearDuplicateCandidate> = [
      {
        page: "Notes/Alpha.md",
        scopeKey: "",
        tokens: new Set(["alpha", "beta", "gamma", "delta", "epsilon"]),
      },
    ];
    const ctx: LintContext = {
      basenames: new Set<string>(),
      vocabulary: loadSchemaPack(vault).vocabulary,
      nearDuplicateCandidates: new Map([["Notes", candidates]]),
      readable: READ_ALL_REFS,
      mergedLinks: { resolve: () => ({ canonical: null, unresolvable: null }) },
    };
    const report = lintPagesWithContext(vault, ctx, [rel]);
    const findings = report.findings.filter((f) => f.code === NEAR_DUPLICATE_CODE);
    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({ page: rel, path: "Notes/Alpha.md" });
  });

  test("a written page is never its own candidate, even when indexed", () => {
    const rel = writeNote(
      "Notes/Beta.md",
      "---\ntitle: Beta\n---\n\nalpha beta gamma delta epsilon\n",
    );
    const candidates: ReadonlyArray<NearDuplicateCandidate> = [
      {
        page: rel,
        scopeKey: "",
        tokens: new Set(["alpha", "beta", "gamma", "delta", "epsilon"]),
      },
    ];
    const ctx: LintContext = {
      basenames: new Set<string>(),
      vocabulary: loadSchemaPack(vault).vocabulary,
      nearDuplicateCandidates: new Map([["Notes", candidates]]),
      readable: READ_ALL_REFS,
      mergedLinks: { resolve: () => ({ canonical: null, unresolvable: null }) },
    };
    expect(lintPagesWithContext(vault, ctx, [rel]).findings).toEqual([]);
  });
});