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
37.5 KB
Raw Blame
/**
 * The note-file lifecycle's own correctness and honesty defects.
 *
 * Nine, and the thread running through them is that a surface whose
 * headline claim is "what this call did, and on what evidence" was
 * reporting several things that were not so.
 *
 *   2. a move read the note with `readFileSync(..., "utf8")` and wrote
 *      the string back, so a note that is not valid UTF-8 came out with
 *      every unpaired byte replaced by U+FFFD - and the source was then
 *      unlinked, with relocations deliberately not snapshotted, so the
 *      original bytes were gone. The module header claimed the move
 *      "copies rather than re-renders" so formatting survives it; that
 *      was false for bytes.
 *   3. bytes moved first and the rewrite pass ran second, so a file that
 *      could not be written threw the raw error and the caller got NO
 *      result - no `from`, no `to`, no evidence - leaving a
 *      half-applied rename indistinguishable from one that never
 *      started.
 *   5. the bare-basename guard counted carriers of the SOURCE basename
 *      only, so renaming `A/Old.md` to `A/New.md` while `B/New.md`
 *      existed reported `applied` and produced two `[[New]]` links -
 *      which, by this project's own resolution ladder, then resolved to
 *      neither note.
 *   7. a plan-only run reported `index: stale`. Nothing happened, so the
 *      premise of the staleness claim failed.
 *   8. a user-note rename edited `Brain/log/`, the append-only record of
 *      what an agent said at an instant.
 *  10. `--expect` excluded the note itself while the rewrite pass
 *      rewrote it, so `expect: 0` passed and then `filesRewritten: 1`.
 *  11. a DIRECTORY named `*.md` reached `readFileSync` and produced a
 *      raw `EISDIR` where `source_missing` belongs.
 *  12. a destination that names the same filesystem entry as the source
 *      - the shape a case-only rename has on macOS and Windows - was
 *      refused as `destination_occupied`.
 *  14. a vault-wide in-place rewrite of hand-authored notes reported
 *      `nothing_at_risk`.
 *  15. a bare-name repair derived its reported `to` spelling from a
 *      third-party note without asking whether the caller may read that
 *      note, so a restricted caller's report named a page withheld from
 *      it.
 *  16. the repair rules joined the destination-collapsing rules in one
 *      ordered reduce, so a repair rule whose `from` was the
 *      destination's own bare basename rewrote the spellings the main
 *      pass had JUST written - repointing the renamed note's inbound
 *      links onto an unrelated note.
 *  17. the counting probe matched only the moved note's own spellings,
 *      so the files the repair pass writes were absent from the plan's
 *      `inbound_files` and from `--expect`'s number.
 *  18. the forced post-write refresh spawned no matter how young the
 *      index stamp was, so writes arriving in a steady stream chained
 *      one detached indexer run after another forever.
 *  19. a refused refresh claim recorded nothing on the diagnostic when
 *      the freshen machinery answered with a skip token instead of
 *      throwing, and one transient failure read as broken forever
 *      because a successful claim never cleared the slot.
 *  20. the reason a refused refresh gave lived only in a process-global
 *      that no production surface rendered - and in a multi-vault server
 *      that global could answer one vault's reason for another. The
 *      reason now travels on the report that refused, as
 *      `references.refresh_reason`, read from that call's own decision.
 *  21. the renamed note's own bare `[[Old]]` links were withheld from
 *      the rewrite whenever the DESTINATION basename was contested -
 *      sound when the target was the bare basename, but the rewrite now
 *      aims at the minimal spelling, which is unambiguous by
 *      construction. The withholding broke links that resolved before
 *      the move. The bare pair is now emitted whenever `[[Old]]`
 *      uniquely resolved to the source before it, and is withheld only
 *      for a nested source the bare spelling never uniquely named.
 */

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

import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
import {
  BASENAME_REWRITE,
  INDEX_EVIDENCE,
  INDEX_REFRESH,
  NOTE_LIFECYCLE_ACTION,
  noteLifecycle,
  NoteLifecycleError,
} from "../../../../src/core/brain/notes/lifecycle.ts";
import { RECOVERABILITY_STATE } from "../../../../src/core/brain/gates/recoverability.ts";
import { CountGuardError } from "../../../../src/core/brain/count-guard.ts";
import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
import { writeFreshenState } from "../../../../src/core/search/freshen.ts";
import { CHMOD_CANNOT_DENY } from "../../../helpers/platform.ts";

let vault: string;
let configHome: string;
let configPath: string;

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

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

/** Write a note verbatim, creating its parents. */
function note(rel: string, body: string | Uint8Array): void {
  const abs = join(vault, rel);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(abs, body);
}

function read(rel: string): string {
  return readFileSync(join(vault, rel), "utf8");
}

function bytes(rel: string): Uint8Array {
  return new Uint8Array(readFileSync(join(vault, rel)));
}

describe("bytes that are not valid UTF-8 (2)", () => {
  test("survive a move exactly, byte for byte", async () => {
    // `ff fe` is not a valid UTF-8 sequence. Decoding and re-encoding
    // replaces each byte with U+FFFD (`ef bf bd`), which is the
    // corruption - and the source is unlinked immediately afterwards.
    const original = Uint8Array.from([0x68, 0x69, 0x20, 0xff, 0xfe, 0x0a]);
    note("Inbox/Binary.md", original);

    await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.move,
      path: "Inbox/Binary.md",
      to: "Projects/Binary.md",
      apply: true,
    });

    expect([...bytes("Projects/Binary.md")]).toEqual([...original]);
    expect(existsSync(join(vault, "Inbox/Binary.md"))).toBe(false);
  });

  test("survive a rename and an archive the same way", async () => {
    const original = Uint8Array.from([0xc0, 0x80, 0x0a]);
    note("Projects/Odd.md", original);

    await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Odd.md",
      to: "Projects/Even.md",
      apply: true,
    });
    expect([...bytes("Projects/Even.md")]).toEqual([...original]);

    await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.archive,
      path: "Projects/Even.md",
      apply: true,
    });
    expect([...bytes("Archive/Projects/Even.md")]).toEqual([...original]);
  });
});

describe("a rewrite that cannot be written (3)", () => {
  // chmod cannot make a directory refuse new files on Windows (or as root).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "returns a result that names the split point instead of throwing",
    async () => {
      note("Projects/Old.md", "x\n");
      note("Aaa/Ref.md", "see [[Projects/Old]]\n");
      note("Docs/Ref.md", "see [[Projects/Old]]\n");
      chmodSync(join(vault, "Docs"), 0o500);

      let res;
      try {
        res = await noteLifecycle(vault, {
          action: NOTE_LIFECYCLE_ACTION.rename,
          path: "Projects/Old.md",
          to: "Projects/New.md",
          apply: true,
        });
      } finally {
        chmodSync(join(vault, "Docs"), 0o700);
      }

      // The whole of the previous failure was that none of this existed.
      expect(res.applied).toBe(true);
      expect(res.from).toBe("Projects/Old.md");
      expect(res.to).toBe("Projects/New.md");
      expect(res.references.filesRewritten).toBe(1);
      expect(res.references.rewriteFailures.map((f) => f.path)).toEqual(["Docs/Ref.md"]);
      expect(res.references.rewriteFailures[0]!.reason.length).toBeGreaterThan(0);
      expect(res.references.rewrittenSpellings.length).toBeGreaterThan(0);
      expect(res.references.index.state).toBe(INDEX_EVIDENCE.absent);

      // And the vault is in exactly the state the result describes.
      expect(existsSync(join(vault, "Projects/New.md"))).toBe(true);
      expect(read("Aaa/Ref.md")).toContain("[[New]]");
      expect(read("Docs/Ref.md")).toContain("[[Projects/Old]]");
    },
  );

  test("a clean run reports no failures at all", async () => {
    note("Projects/Old.md", "x\n");
    note("Notes/Ref.md", "see [[Projects/Old]]\n");
    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
      apply: true,
    });
    expect(res.references.rewriteFailures).toEqual([]);
  });
});

describe("the bare-basename guard (5)", () => {
  test("repairs the third-party bare spelling the rename turns from unique to ambiguous, and rewrites the moved note's own", async () => {
    note("A/Old.md", "x\n");
    note("B/New.md", "a different note that already owns the name\n");
    note("Notes/Ref.md", "bare [[Old]] and bare [[New]]\n");

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "A/Old.md",
      to: "A/New.md",
      apply: true,
    });

    // `[[New]]` named exactly one note (B/New.md) before the rename and
    // two nested carriers after it: the repair re-points it to the
    // shortest spelling of its pre-rename target that still resolves.
    // `[[Old]]` named the moved note - the only carrier there was - so
    // it is rewritten TOO, aimed at the minimal spelling of the
    // destination, which is unambiguous by construction: with B/New.md
    // standing, that spelling is `A/New`, and the link resolves to the
    // same note it named before the move (21).
    expect(res.references.basename).toBe(BASENAME_REWRITE.applied);
    const ref = read("Notes/Ref.md");
    expect(ref).toBe("bare [[A/New]] and bare [[B/New]]\n");
    expect(res.references.rewrittenSpellings).toContainEqual({ from: "Old", to: "A/New" });
    expect(res.references.rewrittenSpellings).toContainEqual({ from: "New", to: "B/New" });
  });

  test("the review's scenario: a contested destination basename no longer strands the moved note's own bare links", async () => {
    // A/Old.md, B/Foo.md, and X.md holding `[[Old]] [[Foo]]`. Renaming
    // A/Old.md to A/Foo.md used to leave `[[Old]]` dangling: the old
    // rule withheld the bare rewrite because `Foo` was contested, even
    // though the rewrite target is the minimal spelling `A/Foo`, which
    // is unambiguous by construction. `[[Old]]` named exactly one note
    // before the move; after it, both of X's links resolve.
    note("A/Old.md", "x\n");
    note("B/Foo.md", "a different note that already owns the name\n");
    note("X.md", "[[Old]] [[Foo]]\n");

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "A/Old.md",
      to: "A/Foo.md",
      apply: true,
    });

    expect(read("X.md")).toBe("[[A/Foo]] [[B/Foo]]\n");
    // Both rewrites are on the report: the third-party repair first,
    // then the moved note's own bare spelling onto the minimal form.
    expect(res.references.rewrittenSpellings).toContainEqual({ from: "Foo", to: "B/Foo" });
    expect(res.references.rewrittenSpellings).toContainEqual({ from: "Old", to: "A/Foo" });
  });

  test("an already-ambiguous bare spelling stays untouched, and a dangling one is not adopted", async () => {
    note("A/Old.md", "x\n");
    note("C/Old.md", "a second carrier of the old name\n");
    note("Notes/Ref.md", "bare [[Old]] and bare [[New]]\n");

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "A/Old.md",
      to: "A/New.md",
      apply: true,
    });

    // `[[Old]]` named one of TWO notes before the move - unprovable
    // which, so nothing may rewrite it. `[[New]]` had no carrier before
    // the move; that it resolves NOW is luck, and adopting a link that
    // never resolved here would be a guess dressed as a repair.
    expect(res.references.basename).toBe(BASENAME_REWRITE.ambiguous);
    expect(read("Notes/Ref.md")).toBe("bare [[Old]] and bare [[New]]\n");
  });

  test("a single TOP-LEVEL carrier keeps owning the bare spelling, so no repair fires", async () => {
    note("A/Old.md", "x\n");
    note("New.md", "the top-level owner of the name\n");
    note("Notes/Ref.md", "bare [[New]]\n");

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "A/Old.md",
      to: "A/New.md",
      apply: true,
    });

    // The ladder's exact-path rung hands `New` to the top-level note
    // before any carrier counting starts, whatever the nested count
    // becomes - the resolution did not change, so the link must not.
    expect(read("Notes/Ref.md")).toBe("bare [[New]]\n");
    expect(res.references.rewrittenSpellings.some((pair) => pair.from === "New")).toBe(false);
  });

  test("still applies when neither basename is contested", async () => {
    note("A/Old.md", "x\n");
    note("Notes/Ref.md", "bare [[Old]]\n");
    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "A/Old.md",
      to: "A/New.md",
      apply: true,
    });
    expect(res.references.basename).toBe(BASENAME_REWRITE.applied);
    expect(read("Notes/Ref.md")).toContain("[[New]]");
  });
});

describe("the refresh claim beside the index evidence (7)", () => {
  test("a claimed refresh does not pretend the index has already caught up", async () => {
    note("Projects/Old.md", "x\n");
    const { resolveSearchConfig } = await import("../../../../src/core/search/index.ts");
    const { LAST_INDEXED_AT_STATE_KEY, Store } =
      await import("../../../../src/core/search/store.ts");
    const store = await Store.open(resolveSearchConfig({ vault }), { mode: "write" });
    store.setState(LAST_INDEXED_AT_STATE_KEY, "2026-08-15T00:00:00.000Z");
    await store.close();
    // Freshen ON, the stamp far older than any interval: this write
    // claims the detached refresh.
    const saved = process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"];
    process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"] = "60";
    let res;
    try {
      res = await noteLifecycle(vault, {
        action: NOTE_LIFECYCLE_ACTION.rename,
        path: "Projects/Old.md",
        to: "Projects/New.md",
        apply: true,
        refreshSpawn: () => {},
      });
    } finally {
      process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"] = saved ?? "0";
    }
    expect(res.references.refresh).toBe(INDEX_REFRESH.claimed);
    // The claim says a run is IN FLIGHT, nothing more: the evidence
    // still reports the pre-refresh stamp and the stale state, and the
    // next command stays on the report.
    expect(res.references.index.state).toBe(INDEX_EVIDENCE.stale);
    expect(res.references.index.lastIndexedAt).toBe("2026-08-15T00:00:00.000Z");
    expect(res.references.index.nextCommand.length).toBeGreaterThan(0);
  });
});

describe("the refresh claim decision on the injected clock", () => {
  test("a backoff ahead of input.now is honoured even though the wall clock has passed it", async () => {
    note("Projects/Old.md", "x\n");
    const { resolveSearchConfig } = await import("../../../../src/core/search/index.ts");
    const { LAST_INDEXED_AT_STATE_KEY, Store } =
      await import("../../../../src/core/search/store.ts");
    const config = resolveSearchConfig({ vault });
    const store = await Store.open(config, { mode: "write" });
    store.setState(LAST_INDEXED_AT_STATE_KEY, "2026-08-15T00:00:00.000Z");
    await store.close();
    // A failed run left a backoff that ended in 2021: long behind the
    // wall clock this suite runs at, and still ahead of the instant the
    // caller injects below. The claim decision has to be made on THAT
    // instant - a deterministic run may not have its behaviour moved by
    // whichever wall clock happens to execute it.
    writeFreshenState(dirname(config.dbPath), {
      failures: 1,
      backoffUntil: "2021-01-01T00:00:00.000Z",
      lastOutcome: "failed",
      lastRunAt: "2020-12-01T00:00:00.000Z",
      lastDurationMs: 5,
      lastError: "injected failure",
      lastChanged: null,
    });
    const saved = process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"];
    process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"] = "60";
    let res;
    try {
      res = await noteLifecycle(vault, {
        action: NOTE_LIFECYCLE_ACTION.rename,
        path: "Projects/Old.md",
        to: "Projects/New.md",
        apply: true,
        now: new Date("2020-06-01T00:00:00.000Z"),
        refreshSpawn: () => {},
      });
    } finally {
      process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"] = saved ?? "0";
    }
    // Under the injected instant the failure backoff is still active, so
    // the forced refresh refuses: force skips the freshness interval
    // gate only, and the backoff stands. Deciding on the wall clock
    // instead would spawn right past a refusal the caller's own timeline
    // says is active.
    expect(res.references.refresh).toBe(INDEX_REFRESH.notClaimed);
  });
});

describe("a refresh claim whose machinery raises", () => {
  // 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.
  const FRESHEN_MODULE = "../../../../src/core/search/freshen.ts";
  let realFreshen: Record<string, unknown> | null = null;

  afterEach(() => {
    if (realFreshen !== null) mock.module(FRESHEN_MODULE, () => realFreshen);
    mock.restore();
    realFreshen = null;
  });

  test("still answers not_claimed, and the report names the failure (20)", async () => {
    // Force the freshen machinery to raise when the claim invokes it -
    // the shape of a permanently broken freshen path, as opposed to one
    // deliberately configured off. The token stays `not_claimed` either
    // way (the public vocabulary does not grow for this), but the old
    // bare catch swallowed the distinction entirely: a broken spawn was
    // indistinguishable from a disabled one. The reason now lands on the
    // result itself, read from THIS call's decision - never from a
    // process-global another vault could have written.
    realFreshen = { ...(await import(FRESHEN_MODULE)) };
    mock.module(FRESHEN_MODULE, () => ({
      maybeFreshenIndex: () => {
        throw new Error("freshen machinery exploded");
      },
    }));
    note("Projects/Old.md", "x\n");
    const { resolveSearchConfig } = await import("../../../../src/core/search/index.ts");
    const { LAST_INDEXED_AT_STATE_KEY, Store } =
      await import("../../../../src/core/search/store.ts");
    const store = await Store.open(resolveSearchConfig({ vault }), { mode: "write" });
    store.setState(LAST_INDEXED_AT_STATE_KEY, "2026-08-15T00:00:00.000Z");
    await store.close();

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
      apply: true,
      refreshSpawn: () => {},
    });

    expect(res.references.refresh).toBe(INDEX_REFRESH.notClaimed);
    expect(res.applied).toBe(true);
    expect(res.references.refreshReason).toBe("freshen machinery exploded");
  });

  test("a refusal that answers instead of throwing names its skip token, and a later success clears it (19)", async () => {
    // The freshen machinery refuses INSIDE itself - a spawn that failed
    // there answers with a skip token and does not throw - so the bare
    // catch above never ran for it: the diagnostic stayed empty and a
    // broken freshen path was indistinguishable from a silent one.
    realFreshen = { ...(await import(FRESHEN_MODULE)) };
    mock.module(FRESHEN_MODULE, () => ({
      maybeFreshenIndex: () => "spawn_failed",
    }));
    note("Projects/Old.md", "x\n");
    const { resolveSearchConfig } = await import("../../../../src/core/search/index.ts");
    const { LAST_INDEXED_AT_STATE_KEY, Store } =
      await import("../../../../src/core/search/store.ts");
    const stampIndex = async (): Promise<void> => {
      const store = await Store.open(resolveSearchConfig({ vault }), { mode: "write" });
      store.setState(LAST_INDEXED_AT_STATE_KEY, "2026-08-15T00:00:00.000Z");
      await store.close();
    };
    await stampIndex();

    const refused = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
      apply: true,
      refreshSpawn: () => {},
    });

    expect(refused.references.refresh).toBe(INDEX_REFRESH.notClaimed);
    // The skip token IS the reason: it lands on the report verbatim.
    expect(refused.references.refreshReason).toBe("spawn_failed");

    // And a claim that succeeds carries no reason, so one transient
    // refusal is not misread later as a permanently broken freshen path.
    mock.module(FRESHEN_MODULE, () => realFreshen!);
    const saved = process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"];
    process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"] = "60";
    try {
      await stampIndex();
      const claimed = await noteLifecycle(vault, {
        action: NOTE_LIFECYCLE_ACTION.rename,
        path: "Projects/New.md",
        to: "Projects/Newer.md",
        apply: true,
        refreshSpawn: () => {},
      });
      expect(claimed.references.refresh).toBe(INDEX_REFRESH.claimed);
      expect(claimed.references.refreshReason).toBeNull();
    } finally {
      process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"] = saved ?? "0";
    }
  });
});

describe("index evidence on a plan-only run (7)", () => {
  test("an existing index is reported unchanged, not stale", async () => {
    note("Projects/Old.md", "x\n");
    const { resolveSearchConfig } = await import("../../../../src/core/search/index.ts");
    const { LAST_INDEXED_AT_STATE_KEY, Store } =
      await import("../../../../src/core/search/store.ts");
    const config = resolveSearchConfig({ vault });
    const store = await Store.open(config, { mode: "write" });
    store.setState(LAST_INDEXED_AT_STATE_KEY, "2026-08-15T00:00:00.000Z");
    await store.close();

    const planned = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
    });
    expect(planned.applied).toBe(false);
    expect(planned.references.index.state).toBe(INDEX_EVIDENCE.unchanged);
    expect(planned.references.index.lastIndexedAt).toBe("2026-08-15T00:00:00.000Z");

    // The very same vault, applied: now something DID happen to it.
    const applied = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
      apply: true,
    });
    expect(applied.references.index.state).toBe(INDEX_EVIDENCE.stale);
  });
});

describe("a repair derived from a page the caller may not read (15)", () => {
  test("is applied for the readers who can see it, but names no pair in the report", async () => {
    note("A/Old.md", "x\n");
    note("B/New.md", "a different note that already owns the name\n");
    note("Notes/Ref.md", "bare [[Old]] and bare [[New]]\n");

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "A/Old.md",
      to: "A/New.md",
      apply: true,
      readable: (rel) => rel !== "B/New.md",
    });

    // The REPAIR pair was derived from the carrier of the contested
    // basename. That carrier is withheld here, so the report answers as
    // a vault without the page would: no `to` naming it.
    expect(res.references.rewrittenSpellings).not.toContainEqual({ from: "New", to: "B/New" });
    // The moved note's OWN bare rewrite is different: its pair derives
    // from the paths the caller itself supplied, so it is applied AND
    // reported (21) - and the file on disk carries both rewrites.
    expect(res.references.rewrittenSpellings).toContainEqual({ from: "Old", to: "A/New" });
    // The repair itself still ran - the readers who CAN see the carrier
    // are not left with a spelling that resolves to neither note.
    expect(read("Notes/Ref.md")).toBe("bare [[A/New]] and bare [[B/New]]\n");
  });

  test("a caller who may read the carrier keeps the pair", async () => {
    note("A/Old.md", "x\n");
    note("B/New.md", "a different note that already owns the name\n");
    note("Notes/Ref.md", "bare [[Old]] and bare [[New]]\n");

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "A/Old.md",
      to: "A/New.md",
      apply: true,
      readable: () => true,
    });

    expect(res.references.rewrittenSpellings).toContainEqual({ from: "New", to: "B/New" });
  });
});

describe("a destination-collapsing pass that chained into the repair rules (16)", () => {
  test("a repair rule never rewrites a link the main pass just produced", async () => {
    note("Projects/Widget.md", "x\n");
    note("Docs/Old.md", "the sole carrier of the contested bare name\n");
    note("Notes/Ref.md", "[[Projects/Widget]] and [[Old]]\n");

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.move,
      path: "Projects/Widget.md",
      to: "Old.md",
      apply: true,
    });

    // The first link names the moved note, now at Old.md; the second
    // names the note that always lived at Docs/Old.md. Chained rules
    // collapsed both onto Docs/Old - every inbound reference to the
    // renamed note repointed at a note it never named.
    expect(read("Notes/Ref.md")).toBe("[[Old]] and [[Docs/Old]]\n");
    expect(res.references.filesRewritten).toBe(1);
  });
});

describe("the plan's blast radius covers the repair pass (17)", () => {
  test("a file mentioning only the contested basename is listed on the plan", async () => {
    note("A/Old.md", "x\n");
    note("B/New.md", "a different note that already owns the name\n");
    note("Notes/Ref.md", "pathed [[A/Old]]\n");
    note("Notes/Casualty.md", "See [[New]].\n");

    const planned = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "A/Old.md",
      to: "A/New.md",
    });

    expect(planned.applied).toBe(false);
    expect(planned.references.inboundFiles).toContain("Notes/Casualty.md");
    expect(planned.references.inboundFiles).toContain("Notes/Ref.md");
    expect(existsSync(join(vault, "Notes/Casualty.md"))).toBe(true);

    // And the apply does exactly what the plan listed: both files are
    // rewritten, so the plan's number is the number `--expect` guards.
    const applied = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "A/Old.md",
      to: "A/New.md",
      apply: true,
      expect: 2,
    });
    expect(applied.references.filesRewritten).toBe(2);
    expect(read("Notes/Casualty.md")).toBe("See [[B/New]].\n");
  });
});

describe("the forced refresh against the write's own instant (18)", () => {
  test("an index stamped after the write began still claims this write's run", async () => {
    note("Projects/Old.md", "x\n");
    const { resolveSearchConfig } = await import("../../../../src/core/search/index.ts");
    const { LAST_INDEXED_AT_STATE_KEY, Store } =
      await import("../../../../src/core/search/store.ts");
    const store = await Store.open(resolveSearchConfig({ vault }), { mode: "write" });
    store.setState(LAST_INDEXED_AT_STATE_KEY, "2026-08-15T00:00:00.000Z");
    await store.close();
    // Freshen ON, and the write's own clock is BEFORE the stamp. The
    // stamp still claims nothing about this write: it marks when a run
    // FINISHED, and a run that finished after the write began may have
    // scanned before the write landed - so a stamp cannot prove the
    // index has seen the write, and a floor that skipped on one would
    // silently leave this write unindexed until the next interval or
    // the next write. The claim therefore spawns.
    const saved = process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"];
    process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"] = "60";
    const spawned: string[][] = [];
    try {
      const res = await noteLifecycle(vault, {
        action: NOTE_LIFECYCLE_ACTION.rename,
        path: "Projects/Old.md",
        to: "Projects/New.md",
        apply: true,
        now: new Date("2026-08-01T00:00:00.000Z"),
        refreshSpawn: (argv: string[]) => spawned.push(argv),
      });
      expect(res.references.refresh).toBe(INDEX_REFRESH.claimed);
    } finally {
      // Restore whatever the environment ACTUALLY held, including its
      // absence - writing "0" back when the variable was unset leaks a
      // freshen setting onto every follower test file in the process.
      if (saved === undefined) delete process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"];
      else process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"] = saved;
    }
    expect(spawned).toHaveLength(1);
  });

  test("a write that began after the last stamp still claims its refresh", async () => {
    note("Projects/Old.md", "x\n");
    const { resolveSearchConfig } = await import("../../../../src/core/search/index.ts");
    const { LAST_INDEXED_AT_STATE_KEY, Store } =
      await import("../../../../src/core/search/store.ts");
    const store = await Store.open(resolveSearchConfig({ vault }), { mode: "write" });
    store.setState(LAST_INDEXED_AT_STATE_KEY, "2026-08-15T00:00:00.000Z");
    await store.close();
    // The ordinary post-write shape: the stamp predates the write, so
    // the index has not seen the write and the claim must spawn.
    const saved = process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"];
    process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"] = "60";
    const spawned: string[][] = [];
    try {
      const res = await noteLifecycle(vault, {
        action: NOTE_LIFECYCLE_ACTION.rename,
        path: "Projects/Old.md",
        to: "Projects/New.md",
        apply: true,
        now: new Date("2026-09-01T00:00:00.000Z"),
        refreshSpawn: (argv: string[]) => spawned.push(argv),
      });
      expect(res.references.refresh).toBe(INDEX_REFRESH.claimed);
    } finally {
      if (saved === undefined) delete process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"];
      else process.env["OPEN_SECOND_BRAIN_SEARCH_FRESHEN_INTERVAL_S"] = saved;
    }
    expect(spawned).toHaveLength(1);
  });
});

describe("the append-only observation log (8)", () => {
  test("is reported as an inbound reference and never rewritten", async () => {
    note("Projects/Old.md", "x\n");
    note("Brain/log/2026-08-15.md", "- agent said [[Projects/Old]] at 10:00\n");
    note("Notes/Ref.md", "see [[Projects/Old]]\n");

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
      apply: true,
    });

    // The disclosure stands...
    expect(res.references.inboundFiles).toContain("Brain/log/2026-08-15.md");
    // ...and the record does not change.
    expect(read("Brain/log/2026-08-15.md")).toBe("- agent said [[Projects/Old]] at 10:00\n");
    expect(res.references.filesRewritten).toBe(1);
    expect(read("Notes/Ref.md")).toContain("[[New]]");
  });
});

describe("the count guard and the note's own self-reference (10)", () => {
  test("counts the file the rewrite pass will write, so expect:0 is refused", async () => {
    note("Projects/Old.md", "this note links to itself: [[Projects/Old]]\n");

    await expect(
      noteLifecycle(vault, {
        action: NOTE_LIFECYCLE_ACTION.rename,
        path: "Projects/Old.md",
        to: "Projects/New.md",
        apply: true,
        expect: 0,
      }),
    ).rejects.toThrow(CountGuardError);
    expect(existsSync(join(vault, "Projects/Old.md"))).toBe(true);

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
      apply: true,
      expect: 1,
    });
    expect(res.references.filesRewritten).toBe(1);
    expect(read("Projects/New.md")).toContain("[[New]]");
  });

  test("a delete still excludes its own file, which strands nothing", async () => {
    note("Projects/Gone.md", "self [[Projects/Gone]]\n");
    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.delete,
      path: "Projects/Gone.md",
      apply: true,
      confirm: true,
      expect: 0,
    });
    expect(res.references.inboundFiles).toEqual([]);
  });
});

describe("a directory named like a note (11)", () => {
  test("is a typed source_missing, not a raw EISDIR", async () => {
    mkdirSync(join(vault, "Projects", "Folder.md"), { recursive: true });

    const attempt = noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Folder.md",
      to: "Projects/Other.md",
      apply: true,
    });
    await expect(attempt).rejects.toThrow(NoteLifecycleError);
    await expect(attempt).rejects.toMatchObject({ code: "source_missing" });
    expect(existsSync(join(vault, "Projects/Folder.md"))).toBe(true);
  });

  test("holds for a delete as well", async () => {
    mkdirSync(join(vault, "Projects", "Folder.md"), { recursive: true });
    await expect(
      noteLifecycle(vault, {
        action: NOTE_LIFECYCLE_ACTION.delete,
        path: "Projects/Folder.md",
        apply: true,
        confirm: true,
      }),
    ).rejects.toMatchObject({ code: "source_missing" });
  });
});

describe("a destination naming the same entry as the source (12)", () => {
  test("is renamed rather than refused as occupied", async () => {
    // On a case-insensitive filesystem `Old.md` and `OLD.md` ARE one
    // entry, which is what makes a capitalisation fix impossible there.
    // A hard link is the same shape on Linux: two names, one inode, so
    // `existsSync(destination)` is true and nothing is occupying it.
    note("Projects/Old.md", "the only copy\n");
    linkSync(join(vault, "Projects/Old.md"), join(vault, "Projects/Alias.md"));

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/Alias.md",
      apply: true,
    });

    expect(res.applied).toBe(true);
    expect(res.to).toBe("Projects/Alias.md");
    expect(read("Projects/Alias.md")).toBe("the only copy\n");
    expect(existsSync(join(vault, "Projects/Old.md"))).toBe(false);
  });

  test("a genuinely different file at the destination is still refused", async () => {
    note("Projects/Old.md", "old\n");
    note("Projects/New.md", "occupied\n");
    await expect(
      noteLifecycle(vault, {
        action: NOTE_LIFECYCLE_ACTION.rename,
        path: "Projects/Old.md",
        to: "Projects/New.md",
        apply: true,
      }),
    ).rejects.toMatchObject({ code: "destination_occupied" });
    expect(read("Projects/New.md")).toBe("occupied\n");
  });
});

describe("the recoverability verdict of a relocation (14)", () => {
  test("an in-place rewrite of a user note is not nothing_at_risk", async () => {
    note("Projects/Old.md", "x\n");
    note("Notes/Handwritten.md", "Handwritten log. See [[Projects/Old]] for details.\n");

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
      apply: true,
    });

    // The file was overwritten and nothing regenerates a user's prose.
    expect(read("Notes/Handwritten.md")).toContain("[[New]]");
    expect(res.recoverability.state).toBe(RECOVERABILITY_STATE.unproven);
    expect(res.recoverability.blockers).toContain("no_recovery_point");
    expect(res.recoverability.blockers).toContain("outside_brain_root");
    expect(res.recoverability.coverage).toEqual([]);
  });

  test("a rewrite confined to Brain/ names that region and not the other", async () => {
    note("Projects/Old.md", "x\n");
    note("Brain/reports/weekly.md", "see [[Projects/Old]]\n");

    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
      apply: true,
    });

    expect(res.recoverability.state).toBe(RECOVERABILITY_STATE.unproven);
    expect(res.recoverability.blockers).toContain("no_recovery_point");
    expect(res.recoverability.blockers).not.toContain("outside_brain_root");
  });

  test("a relocation that rewrites nothing destroys nothing, and says so", async () => {
    note("Projects/Old.md", "x\n");
    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
      apply: true,
    });
    expect(res.recoverability.state).toBe(RECOVERABILITY_STATE.nothingAtRisk);
  });

  test("a plan-only run wrote nothing, so nothing was at risk", async () => {
    note("Projects/Old.md", "x\n");
    note("Notes/Handwritten.md", "see [[Projects/Old]]\n");
    const res = await noteLifecycle(vault, {
      action: NOTE_LIFECYCLE_ACTION.rename,
      path: "Projects/Old.md",
      to: "Projects/New.md",
    });
    expect(res.applied).toBe(false);
    expect(res.recoverability.state).toBe(RECOVERABILITY_STATE.nothingAtRisk);
    // The warning a caller needs before applying is the file list, and
    // it is there.
    expect(res.references.inboundFiles).toEqual(["Notes/Handwritten.md"]);
  });
});