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
24.2 KB
Raw Blame
/**
 * Tests for `src/core/brain/manifest.ts`.
 *
 * Covered:
 *   - empty Brain → empty files map
 *   - regular files hashed; output keys sorted lexicographically
 *   - `.snapshots/` excluded
 *   - symlinks skipped (defense against malicious archive contents)
 *   - byte-stable sha256 across runs on identical inputs
 *   - `diffManifests` classifies added / removed / changed
 *   - sidecar read / write roundtrip; corrupt and missing sidecars
 *     surface as `null` rather than throwing
 */

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

import {
  BRAIN_MANIFEST_SCHEMA_VERSION,
  buildManifest,
  diffManifests,
  manifestDiffHasDrift,
  manifestSidecarPath,
  readManifestSidecar,
  SNAPSHOT_STORE_EXCLUSION,
  writeManifestSidecar,
  type BrainManifest,
} from "../../../src/core/brain/manifest.ts";
import { BRAIN_SNAPSHOT_REASON, BRAIN_SNAPSHOT_REASONS } from "../../../src/core/brain/types.ts";

let vault: string;
let brain: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-manifest-"));
  brain = join(vault, "Brain");
  mkdirSync(brain, { recursive: true });
  mkdirSync(join(brain, ".snapshots"), { recursive: true });
});
afterEach(() => rmSync(vault, { recursive: true, force: true }));

describe("buildManifest", () => {
  test("empty Brain → empty files map, schema_version 1, brain_root 'Brain'", () => {
    const m = buildManifest(brain);
    expect(m.schema_version).toBe(BRAIN_MANIFEST_SCHEMA_VERSION);
    expect(m.brain_root).toBe("Brain");
    expect(Object.keys(m.files)).toEqual([]);
    expect(m.generated_at).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
  });

  test("missing brainRoot directory → empty manifest, no throw", () => {
    rmSync(brain, { recursive: true, force: true });
    const m = buildManifest(brain);
    expect(Object.keys(m.files)).toEqual([]);
  });

  test("two preferences → two entries sorted by relative path", () => {
    mkdirSync(join(brain, "preferences"), { recursive: true });
    writeFileSync(join(brain, "preferences", "pref-b.md"), "beta\n");
    writeFileSync(join(brain, "preferences", "pref-a.md"), "alpha\n");
    const m = buildManifest(brain);
    expect(Object.keys(m.files)).toEqual(["preferences/pref-a.md", "preferences/pref-b.md"]);
    expect(m.files["preferences/pref-a.md"]!.size).toBe(6);
    expect(m.files["preferences/pref-a.md"]!.sha256).toMatch(/^[0-9a-f]{64}$/);
    // sha256("alpha\n") == "31c0c4dee7f8eeeb27ff4f64ff5a7a9d97a6b6f49ad22082f6c12f9f0c5b9d27" → guard via length only.
    expect(m.files["preferences/pref-a.md"]!.sha256.length).toBe(64);
  });

  test(".snapshots/ is excluded from the walk", () => {
    writeFileSync(join(brain, ".snapshots", "phantom.tar.zst"), "binary");
    writeFileSync(join(brain, ".snapshots", "phantom.manifest.json"), "{}");
    mkdirSync(join(brain, "preferences"));
    writeFileSync(join(brain, "preferences", "pref-x.md"), "x");
    const m = buildManifest(brain);
    expect(Object.keys(m.files)).toEqual(["preferences/pref-x.md"]);
  });

  test(".artifacts/ is excluded from the walk", () => {
    // Documented as never backed up, yet hashed into every manifest -
    // so TTL'd tool output churning between a snapshot and a rollback
    // tripped the drift gate on a directory no restore ever touches.
    mkdirSync(join(brain, ".artifacts", "run-1"), { recursive: true });
    writeFileSync(join(brain, ".artifacts", "run-1", "a.json"), "{}");
    mkdirSync(join(brain, "preferences"));
    writeFileSync(join(brain, "preferences", "pref-x.md"), "x");
    const m = buildManifest(brain);
    expect(Object.keys(m.files)).toEqual(["preferences/pref-x.md"]);
  });

  test("symlink under Brain/ is skipped (security)", () => {
    mkdirSync(join(brain, "preferences"));
    writeFileSync(join(brain, "preferences", "pref-real.md"), "real");
    const targetOutside = join(vault, "secret.txt");
    writeFileSync(targetOutside, "should-not-be-hashed");
    symlinkSync(targetOutside, join(brain, "preferences", "pref-link.md"));
    const m = buildManifest(brain);
    expect(Object.keys(m.files)).toEqual(["preferences/pref-real.md"]);
  });

  test("identical bytes → identical sha256 across two runs", () => {
    mkdirSync(join(brain, "preferences"));
    writeFileSync(join(brain, "preferences", "pref-a.md"), "deterministic");
    const m1 = buildManifest(brain);
    const m2 = buildManifest(brain);
    expect(m1.files["preferences/pref-a.md"]!.sha256).toBe(
      m2.files["preferences/pref-a.md"]!.sha256,
    );
  });

  test("config files at Brain/ root are hashed (e.g. _brain.yaml)", () => {
    writeFileSync(join(brain, "_brain.yaml"), "schema_version: 1\n");
    writeFileSync(join(brain, "_BRAIN.md"), "# manual\n");
    const m = buildManifest(brain);
    expect(Object.keys(m.files).toSorted()).toEqual(["_BRAIN.md", "_brain.yaml"]);
  });
});

describe("diffManifests", () => {
  function fakeManifest(files: Record<string, { sha: string; size: number }>): BrainManifest {
    const sortedKeys = Object.keys(files).toSorted();
    const out: Record<string, { readonly sha256: string; readonly size: number }> = {};
    for (const k of sortedKeys) {
      out[k] = Object.freeze({ sha256: files[k]!.sha, size: files[k]!.size });
    }
    return Object.freeze({
      schema_version: BRAIN_MANIFEST_SCHEMA_VERSION,
      generated_at: "2026-05-18T00:00:00Z",
      brain_root: "Brain",
      files: Object.freeze(out),
    });
  }

  test("identical manifests → empty diff in all three buckets", () => {
    const a = fakeManifest({ "preferences/pref-a.md": { sha: "x", size: 1 } });
    const b = fakeManifest({ "preferences/pref-a.md": { sha: "x", size: 1 } });
    const d = diffManifests(a, b);
    expect(d.added).toEqual([]);
    expect(d.removed).toEqual([]);
    expect(d.changed).toEqual([]);
    expect(manifestDiffHasDrift(d)).toBe(false);
  });

  test("right has extra file → 'added'", () => {
    const a = fakeManifest({});
    const b = fakeManifest({ "preferences/pref-a.md": { sha: "x", size: 1 } });
    const d = diffManifests(a, b);
    expect(d.added.map((e) => e.path)).toEqual(["preferences/pref-a.md"]);
    expect(d.added[0]!.before).toBeNull();
    expect(d.added[0]!.after!.sha256).toBe("x");
    expect(manifestDiffHasDrift(d)).toBe(true);
  });

  test("left has extra file → 'removed'", () => {
    const a = fakeManifest({ "preferences/pref-a.md": { sha: "x", size: 1 } });
    const b = fakeManifest({});
    const d = diffManifests(a, b);
    expect(d.removed.map((e) => e.path)).toEqual(["preferences/pref-a.md"]);
    expect(d.removed[0]!.after).toBeNull();
    expect(manifestDiffHasDrift(d)).toBe(true);
  });

  test("same path different sha256 → 'changed'", () => {
    const a = fakeManifest({ "preferences/pref-a.md": { sha: "x", size: 1 } });
    const b = fakeManifest({ "preferences/pref-a.md": { sha: "y", size: 1 } });
    const d = diffManifests(a, b);
    expect(d.changed.map((e) => e.path)).toEqual(["preferences/pref-a.md"]);
    expect(d.changed[0]!.before!.sha256).toBe("x");
    expect(d.changed[0]!.after!.sha256).toBe("y");
  });

  test("same path same sha256 different size → 'changed' (defensive)", () => {
    const a = fakeManifest({ "preferences/pref-a.md": { sha: "x", size: 1 } });
    const b = fakeManifest({ "preferences/pref-a.md": { sha: "x", size: 2 } });
    const d = diffManifests(a, b);
    expect(d.changed.length).toBe(1);
  });

  test("multiple changes → each bucket sorted by path", () => {
    const a = fakeManifest({
      "z.md": { sha: "old", size: 1 },
      "a.md": { sha: "old", size: 1 },
    });
    const b = fakeManifest({
      "z.md": { sha: "new", size: 1 },
      "b.md": { sha: "new", size: 1 },
    });
    const d = diffManifests(a, b);
    expect(d.added.map((e) => e.path)).toEqual(["b.md"]);
    expect(d.removed.map((e) => e.path)).toEqual(["a.md"]);
    expect(d.changed.map((e) => e.path)).toEqual(["z.md"]);
  });
});

describe("sidecar I/O", () => {
  test("manifestSidecarPath lands inside Brain/.snapshots/", () => {
    expect(manifestSidecarPath(vault, "abc")).toBe(join(brain, ".snapshots", "abc.manifest.json"));
  });

  test("read of missing path → null (no throw)", () => {
    expect(readManifestSidecar(vault, "ghost")).toBeNull();
  });

  test("read of malformed JSON → null", () => {
    writeFileSync(manifestSidecarPath(vault, "torn"), "not json {");
    expect(readManifestSidecar(vault, "torn")).toBeNull();
  });

  test("read of wrong schema_version → null", () => {
    writeFileSync(
      manifestSidecarPath(vault, "old"),
      JSON.stringify({
        schema_version: 99,
        generated_at: "2026-05-18T00:00:00Z",
        brain_root: "Brain",
        files: {},
      }),
    );
    expect(readManifestSidecar(vault, "old")).toBeNull();
  });

  test("read of tampered entry (null) → null, does not crash", () => {
    writeFileSync(
      manifestSidecarPath(vault, "tampered-null"),
      JSON.stringify({
        schema_version: 1,
        generated_at: "2026-05-18T00:00:00Z",
        brain_root: "Brain",
        files: { "preferences/pref-x.md": null },
      }),
    );
    expect(readManifestSidecar(vault, "tampered-null")).toBeNull();
  });

  test("read of tampered entry (missing sha256) → null", () => {
    writeFileSync(
      manifestSidecarPath(vault, "tampered-shape"),
      JSON.stringify({
        schema_version: 1,
        generated_at: "2026-05-18T00:00:00Z",
        brain_root: "Brain",
        files: { "preferences/pref-x.md": { size: 12 } },
      }),
    );
    expect(readManifestSidecar(vault, "tampered-shape")).toBeNull();
  });

  test("read of tampered entry (wrong sha256 type) → null", () => {
    writeFileSync(
      manifestSidecarPath(vault, "tampered-type"),
      JSON.stringify({
        schema_version: 1,
        generated_at: "2026-05-18T00:00:00Z",
        brain_root: "Brain",
        files: { "preferences/pref-x.md": { sha256: 42, size: 12 } },
      }),
    );
    expect(readManifestSidecar(vault, "tampered-type")).toBeNull();
  });

  test("write then read roundtrip yields equal structure", () => {
    mkdirSync(join(brain, "preferences"));
    writeFileSync(join(brain, "preferences", "pref-rt.md"), "roundtrip");
    const original = buildManifest(brain);
    writeManifestSidecar(vault, "rt", original);
    const back = readManifestSidecar(vault, "rt");
    expect(back).not.toBeNull();
    expect(back!.schema_version).toBe(BRAIN_MANIFEST_SCHEMA_VERSION);
    expect(back!.brain_root).toBe("Brain");
    expect(Object.keys(back!.files)).toEqual(Object.keys(original.files));
    expect(back!.files["preferences/pref-rt.md"]!.sha256).toBe(
      original.files["preferences/pref-rt.md"]!.sha256,
    );
  });
});

/**
 * The derived-store record travels on the same distribution channel as
 * the rest of the sidecar - Syncthing, a manual copy, an operator who
 * lost their nerves - so every field is validated on read and a single
 * malformation fails the WHOLE manifest closed, exactly as one bad file
 * entry already does. Anything looser would let a half-written record
 * claim a coverage the archive does not have, and the restore acts on
 * that claim.
 */
describe("the derived-store field on the sidecar", () => {
  /** A sidecar carrying `derived_store` verbatim, written to disk. */
  function writeSidecarWithStore(runId: string, derivedStore: unknown): void {
    writeFileSync(
      manifestSidecarPath(vault, runId),
      JSON.stringify({
        schema_version: 1,
        generated_at: "2026-05-18T00:00:00Z",
        brain_root: "Brain",
        files: {},
        derived_store: derivedStore,
      }),
    );
  }

  const INCLUDED = Object.freeze({
    included: true,
    source_path: "/vault/.open-second-brain/brain.sqlite",
    archive_name: "run.store.sqlite.zst",
    archive_sha256: "a".repeat(64),
    archive_size: 4096,
    live_size: 8192,
    exclusion_reason: null,
  });

  const EXCLUDED = Object.freeze({
    included: false,
    source_path: "/vault/.open-second-brain/brain.sqlite",
    archive_name: null,
    archive_sha256: null,
    archive_size: null,
    live_size: 8192,
    exclusion_reason: SNAPSHOT_STORE_EXCLUSION.not_requested,
  });

  test("an absent key parses and reads as unknown, never as excluded", () => {
    writeFileSync(
      manifestSidecarPath(vault, "pre-feature"),
      JSON.stringify({
        schema_version: 1,
        generated_at: "2026-05-18T00:00:00Z",
        brain_root: "Brain",
        files: {},
      }),
    );
    const back = readManifestSidecar(vault, "pre-feature");
    // The manifest itself is valid - an older peer's sidecar must keep
    // its drift guarantee, which is why the schema version was not
    // bumped for this field.
    expect(back).not.toBeNull();
    expect(back!.derived_store).toBeUndefined();
  });

  test("a well-formed inclusion record roundtrips", () => {
    writeSidecarWithStore("included", INCLUDED);
    expect(readManifestSidecar(vault, "included")!.derived_store).toEqual(INCLUDED);
  });

  test("a well-formed exclusion record roundtrips", () => {
    writeSidecarWithStore("excluded", EXCLUDED);
    expect(readManifestSidecar(vault, "excluded")!.derived_store).toEqual(EXCLUDED);
  });

  test("a live size of zero is kept, because zero is a real size", () => {
    writeSidecarWithStore("zero-size", { ...EXCLUDED, live_size: 0 });
    expect(readManifestSidecar(vault, "zero-size")!.derived_store!.live_size).toBe(0);
  });

  test("an explicit null record is contained to the field, not the record", () => {
    writeSidecarWithStore("null-record", null);
    const contained = readManifestSidecar(vault, "null-record");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.derived_store).toBeUndefined();
    expect(contained!.derived_store_unreadable).toBe(true);
  });

  test("a non-object record is contained to the field, not the record", () => {
    writeSidecarWithStore("scalar-record", "included");
    const contained = readManifestSidecar(vault, "scalar-record");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.derived_store).toBeUndefined();
    expect(contained!.derived_store_unreadable).toBe(true);
  });

  test("a missing `included` flag is contained to the field, not the record", () => {
    const { included: _drop, ...rest } = INCLUDED;
    writeSidecarWithStore("no-flag", rest);
    const contained = readManifestSidecar(vault, "no-flag");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.derived_store).toBeUndefined();
    expect(contained!.derived_store_unreadable).toBe(true);
  });

  test("a non-integer archive size is contained to the field, not the record", () => {
    writeSidecarWithStore("fractional", { ...INCLUDED, archive_size: 4096.5 });
    const contained = readManifestSidecar(vault, "fractional");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.derived_store).toBeUndefined();
    expect(contained!.derived_store_unreadable).toBe(true);
  });

  test("an unregistered exclusion reason is contained to the field, not the record", () => {
    writeSidecarWithStore("unknown-reason", { ...EXCLUDED, exclusion_reason: "ran-out-of-disk" });
    const contained = readManifestSidecar(vault, "unknown-reason");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.derived_store).toBeUndefined();
    expect(contained!.derived_store_unreadable).toBe(true);
  });

  test("inclusion without a digest is contained to the field, not the record", () => {
    // Not a weaker record - a false one. Nothing could verify the
    // archive it claims to have written.
    writeSidecarWithStore("no-digest", { ...INCLUDED, archive_sha256: null });
    const contained = readManifestSidecar(vault, "no-digest");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.derived_store).toBeUndefined();
    expect(contained!.derived_store_unreadable).toBe(true);
  });

  test("inclusion that also names an exclusion reason is contained to the field, not the record", () => {
    writeSidecarWithStore("both", {
      ...INCLUDED,
      exclusion_reason: SNAPSHOT_STORE_EXCLUSION.absent,
    });
    const contained = readManifestSidecar(vault, "both");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.derived_store).toBeUndefined();
    expect(contained!.derived_store_unreadable).toBe(true);
  });

  test("an exclusion that names no reason is contained to the field, not the record", () => {
    writeSidecarWithStore("reasonless", { ...EXCLUDED, exclusion_reason: null });
    const contained = readManifestSidecar(vault, "reasonless");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.derived_store).toBeUndefined();
    expect(contained!.derived_store_unreadable).toBe(true);
  });
});

/**
 * U7: the snapshot-reason field on the sidecar.
 *
 * Additive at the existing schema version for the same reason the
 * derived-store field is, and validated through the same closed guard.
 * The load-bearing negative is the last case here: the reason is also a
 * run-id PREFIX at every call site that writes one, so guessing it from
 * the run id would look right in almost every test and would manufacture
 * provenance for a hand-named archive the code never stamped.
 */
describe("the snapshot-reason field on the sidecar", () => {
  /** A sidecar carrying `snapshot_reason` verbatim, written to disk. */
  function writeSidecarWithReason(runId: string, reason: unknown): void {
    writeFileSync(
      manifestSidecarPath(vault, runId),
      JSON.stringify({
        schema_version: 1,
        generated_at: "2026-05-18T00:00:00Z",
        brain_root: "Brain",
        files: {},
        snapshot_reason: reason,
      }),
    );
  }

  test("buildManifest stamps the reason it was given", () => {
    const m = buildManifest(brain, { snapshotReason: BRAIN_SNAPSHOT_REASON.entityPrune });
    expect(m.snapshot_reason).toBe(BRAIN_SNAPSHOT_REASON.entityPrune);
    // Still the same schema version: an older peer ignores the key and
    // keeps its own drift detection, which is why it was not bumped.
    expect(m.schema_version).toBe(BRAIN_MANIFEST_SCHEMA_VERSION);
  });

  test("buildManifest omits the key entirely when given no reason", () => {
    const m = buildManifest(brain);
    expect("snapshot_reason" in m).toBe(false);
  });

  test("every registered reason roundtrips through the sidecar", () => {
    for (const reason of BRAIN_SNAPSHOT_REASONS) {
      writeSidecarWithReason(`roundtrip-${reason}`, reason);
      expect(readManifestSidecar(vault, `roundtrip-${reason}`)?.snapshot_reason).toBe(reason);
    }
  });

  test("a sidecar written before the feature reads as no reason at all", () => {
    writeFileSync(
      manifestSidecarPath(vault, "dream-2026-05-18-070000"),
      JSON.stringify({
        schema_version: 1,
        generated_at: "2026-05-18T00:00:00Z",
        brain_root: "Brain",
        files: {},
      }),
    );
    const back = readManifestSidecar(vault, "dream-2026-05-18-070000");
    expect(back).not.toBeNull();
    // The run id begins with a registered reason. It is NOT read back as
    // one: the archive does not carry that provenance, and inventing it
    // would make an unstamped snapshot indistinguishable from a stamped
    // one.
    expect(back!.snapshot_reason).toBeUndefined();
  });

  test("an unregistered reason is contained to the field, not the record", () => {
    writeSidecarWithReason("bogus", "spring-cleaning");
    const contained = readManifestSidecar(vault, "bogus");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.snapshot_reason).toBeUndefined();
    expect(contained!.snapshot_reason_unreadable).toBe(true);
  });

  test("an explicit null reason is contained to the field, not the record", () => {
    // Absence is spelled by omitting the key. A null is a present field
    // that names nothing, which no writer here produces.
    writeSidecarWithReason("null-reason", null);
    const contained = readManifestSidecar(vault, "null-reason");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.snapshot_reason).toBeUndefined();
    expect(contained!.snapshot_reason_unreadable).toBe(true);
  });

  test("a non-string reason is contained to the field, not the record", () => {
    writeSidecarWithReason("numeric", 3);
    const contained = readManifestSidecar(vault, "numeric");
    // Drift detection runs on the mandatory part, so an unreadable
    // optional field must not take it down: discarding the record
    // here reports no sidecar at all and skips the gate, which is
    // the silent-overwrite path this field was added beside.
    expect(contained).not.toBeNull();
    expect(contained!.generated_at).toBe("2026-05-18T00:00:00Z");
    expect(contained!.snapshot_reason).toBeUndefined();
    expect(contained!.snapshot_reason_unreadable).toBe(true);
  });

  test("write then read roundtrip preserves the reason", () => {
    writeFileSync(join(brain, "_brain.yaml"), "schema_version: 1\n");
    const original = buildManifest(brain, { snapshotReason: BRAIN_SNAPSHOT_REASON.manual });
    writeManifestSidecar(vault, "reason-rt", original);
    expect(readManifestSidecar(vault, "reason-rt")!.snapshot_reason).toBe(
      BRAIN_SNAPSHOT_REASON.manual,
    );
  });
});