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
18.7 KB
Raw Blame
/**
 * D1 (t_7965b04b): snapshot-before-destructive-write gate.
 *
 * `withDestructiveSnapshot(vault, reason, op)` is the thin wrapper that
 * guarantees no destructive brain mutation runs without a recovery
 * point on disk first. The contract:
 *
 *   - it mints a valid, unique run id of the shape `<reason>-<stamp>`;
 *   - it calls `takeSnapshot` BEFORE `op`, so a snapshot failure
 *     aborts the operation (the destructive work never runs);
 *   - if `op` throws, the error propagates but the snapshot stays put
 *     (that IS the recovery point);
 *   - retention is enforced around the recovery point it just wrote.
 *
 * U7 adds one structural assertion to that list: the standalone
 * `takeSnapshot` entry point and the wrapper must produce byte-identical
 * archives for the same input, because the wrapper delegates to it rather
 * than carrying a second copy of the snapshot path.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
  cpSync,
  existsSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  statSync,
  utimesSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import {
  createUniqueSnapshot,
  takeSnapshot,
  withDestructiveSnapshot,
} from "../../../src/core/brain/snapshot-gate.ts";
import {
  BrainSnapshotError,
  BrainSnapshotStoreError,
  listSnapshots,
} from "../../../src/core/brain/snapshot.ts";
import { createSnapshot } from "../../../src/core/brain/snapshot.ts";
import { dream } from "../../../src/core/brain/dream.ts";
import { isFileAlreadyExists } from "../../../src/core/fs-atomic.ts";
import { brainDirs, snapshotPath, validateRunId } from "../../../src/core/brain/paths.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { BRAIN_SNAPSHOT_REASON } from "../../../src/core/brain/types.ts";
import { FileAlreadyExistsError, atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { extractSnapshotArchive } from "../../helpers/snapshot-archive.ts";

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

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

  const dirs = brainDirs(vault);
  writeFileSync(
    join(dirs.inbox, "sig-2026-05-14-foo.md"),
    "---\nkind: brain-signal\n---\n\n## Raw\n\nseed\n",
  );
});

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

describe("withDestructiveSnapshot", () => {
  test("mints a valid run id and snapshots before running op", () => {
    let archiveCountWhenOpRan = -1;
    const out = withDestructiveSnapshot(
      vault,
      BRAIN_SNAPSHOT_REASON.deleteBySource,
      () => {
        // The snapshot archive must already exist by the time op runs.
        archiveCountWhenOpRan = listSnapshots(vault).snapshots.length;
        return "result-value";
      },
      { now: new Date("2026-06-01T00:00:00Z") },
    );
    expect(out.result).toBe("result-value");
    expect(out.snapshot.runId).toMatch(/^delete-by-source-/);
    // The minted id is a valid filesystem-safe run id.
    expect(() => validateRunId(out.snapshot.runId)).not.toThrow();
    expect(existsSync(out.snapshot.path)).toBe(true);
    expect(archiveCountWhenOpRan).toBe(1);
  });

  test("op runs after the snapshot exists (order proven)", () => {
    let order: string[] = [];
    const before = listSnapshots(vault).snapshots.length;
    withDestructiveSnapshot(vault, BRAIN_SNAPSHOT_REASON.entityPrune, () => {
      order.push(`snapshots=${listSnapshots(vault).snapshots.length}`);
    });
    expect(order).toEqual([`snapshots=${before + 1}`]);
  });

  test("aborts the operation when the snapshot cannot be created", () => {
    // Force createSnapshot to fail by making `tar` unfindable: point PATH
    // at an empty dir so tooling detection reports tar missing.
    const emptyDir = mkdtempSync(join(tmpdir(), "o2b-empty-path-"));
    const savedPath = process.env["PATH"];
    process.env["PATH"] = emptyDir;
    let opRan = false;
    try {
      expect(() =>
        withDestructiveSnapshot(vault, BRAIN_SNAPSHOT_REASON.deleteBySource, () => {
          opRan = true;
        }),
      ).toThrow();
      expect(opRan).toBe(false);
    } finally {
      process.env["PATH"] = savedPath;
      rmSync(emptyDir, { recursive: true, force: true });
    }
  });

  test("aborts the operation when derived-store coverage cannot be honoured", () => {
    // Coverage on, and no derived store in this vault. `createSnapshot`
    // refuses rather than downgrading to a snapshot that omits what it
    // was asked to protect - and because the gate snapshots FIRST, the
    // destructive operation simply never runs. No new plumbing: the
    // property follows from refusing in the right place.
    const brainYaml = join(brainDirs(vault).brain, "_brain.yaml");
    atomicWriteFileSync(
      brainYaml,
      "schema_version: 1\nsnapshots:\n  include_derived_store: true\n",
    );
    let opRan = false;
    expect(() =>
      withDestructiveSnapshot(vault, BRAIN_SNAPSHOT_REASON.deleteBySource, () => {
        opRan = true;
      }),
    ).toThrow(BrainSnapshotStoreError);
    expect(opRan).toBe(false);
    expect(listSnapshots(vault).snapshots).toHaveLength(0);
  });

  test("op error propagates but the snapshot is retained as recovery point", () => {
    const before = listSnapshots(vault).snapshots.length;
    expect(() =>
      withDestructiveSnapshot(vault, BRAIN_SNAPSHOT_REASON.deleteBySource, () => {
        throw new Error("op blew up");
      }),
    ).toThrow("op blew up");
    // The snapshot survives - it is the recovery point.
    expect(listSnapshots(vault).snapshots.length).toBe(before + 1);
  });

  test("prunes to the configured retention after a successful op", () => {
    // Retention default is 10; write config with retention_count: 2.
    const brainYaml = join(brainDirs(vault).brain, "_brain.yaml");
    atomicWriteFileSync(brainYaml, "schema_version: 1\nsnapshots:\n  retention_count: 2\n");

    // Create three snapshots through the gate; only the two newest survive.
    for (let i = 0; i < 3; i++) {
      withDestructiveSnapshot(vault, BRAIN_SNAPSHOT_REASON.deleteBySource, () => undefined, {
        now: new Date(`2026-06-0${i + 1}T00:00:00Z`),
      });
    }
    expect(listSnapshots(vault).snapshots.length).toBe(2);
  });

  test("mints unique run ids when the base id already exists", () => {
    const now = new Date("2026-06-01T00:00:00Z");
    const a = withDestructiveSnapshot(
      vault,
      BRAIN_SNAPSHOT_REASON.deleteBySource,
      () => undefined,
      { now },
    );
    const b = withDestructiveSnapshot(
      vault,
      BRAIN_SNAPSHOT_REASON.deleteBySource,
      () => undefined,
      { now },
    );
    expect(a.snapshot.runId).not.toBe(b.snapshot.runId);
    expect(b.snapshot.runId).toBe(`${a.snapshot.runId}-2`);
  });

  test("the minted snapshot archive contains the seeded Brain content", () => {
    const out = withDestructiveSnapshot(
      vault,
      BRAIN_SNAPSHOT_REASON.deleteBySource,
      () => undefined,
    );
    // Extract and confirm the seeded signal is present.
    const tmp = mkdtempSync(join(tmpdir(), "o2b-gate-verify-"));
    try {
      extractSnapshotArchive(out.snapshot.path, tmp);
      expect(existsSync(join(tmp, "Brain", "inbox", "sig-2026-05-14-foo.md"))).toBe(true);
    } finally {
      rmSync(tmp, { recursive: true, force: true });
    }
  });

  test("stamps the reason it was given into the snapshot's sidecar", () => {
    const out = withDestructiveSnapshot(vault, BRAIN_SNAPSHOT_REASON.entityPrune, () => undefined);
    const listed = listSnapshots(vault).snapshots.find((s) => s.run_id === out.snapshot.runId);
    expect(listed?.reason).toBe(BRAIN_SNAPSHOT_REASON.entityPrune);
  });
});

/**
 * U7: the extraction must not have forked the snapshot path.
 *
 * `takeSnapshot` exists so a caller that wants a recovery point WITHOUT
 * an operation behind it has somewhere to go other than a second copy of
 * the id-minting and archiving logic. The proof that it is not a second
 * copy is that the wrapper's archive and its own are byte-identical over
 * the same tree.
 *
 * The comparison runs over two vaults rather than two snapshots of one,
 * because a snapshot appends its own log event into `Brain/log/` - so a
 * second archive of the SAME vault legitimately differs, and comparing
 * them would prove nothing about the code path. Both trees are stamped to
 * one fixed mtime first: tar records per-entry mtimes, and the copy's are
 * otherwise the moment it was made.
 */
describe("takeSnapshot and withDestructiveSnapshot share one archive path", () => {
  /** Stamp every entry under `root` to one instant, deepest-last. */
  function stampTree(root: string, when: Date): void {
    const stack = [root];
    const seen: string[] = [];
    while (stack.length > 0) {
      const dir = stack.pop()!;
      seen.push(dir);
      for (const name of readdirSync(dir)) {
        const abs = join(dir, name);
        if (statSync(abs).isDirectory()) stack.push(abs);
        else utimesSync(abs, when, when);
      }
    }
    // Directories last: touching a child rewrites its parent's mtime.
    for (const dir of seen.toReversed()) utimesSync(dir, when, when);
  }

  test("both entry points produce byte-identical archives for the same input", () => {
    const twin = mkdtempSync(join(tmpdir(), "o2b-snap-gate-twin-"));
    try {
      // Copy BEFORE either vault has a `.snapshots/` directory, so the two
      // trees under `Brain/` are identical in content and in structure.
      cpSync(join(vault, "Brain"), join(twin, "Brain"), { recursive: true });
      const fixed = new Date("2026-06-01T00:00:00Z");
      stampTree(join(vault, "Brain"), fixed);
      stampTree(join(twin, "Brain"), fixed);

      const viaEntryPoint = takeSnapshot(vault, BRAIN_SNAPSHOT_REASON.manual, { now: fixed });
      const viaWrapper = withDestructiveSnapshot(
        twin,
        BRAIN_SNAPSHOT_REASON.manual,
        () => undefined,
        { now: fixed },
      );

      // Same minting rule, so the same id from the same reason and clock.
      expect(viaWrapper.snapshot.runId).toBe(viaEntryPoint.runId);
      expect(readFileSync(viaWrapper.snapshot.path)).toEqual(readFileSync(viaEntryPoint.path));
    } finally {
      rmSync(twin, { recursive: true, force: true });
    }
  });

  test("the standalone entry point requires a reason and records it", () => {
    const snap = takeSnapshot(vault, BRAIN_SNAPSHOT_REASON.manual);
    expect(snap.runId).toMatch(/^manual-/);
    expect(existsSync(snap.path)).toBe(true);
    expect(listSnapshots(vault).snapshots.find((s) => s.run_id === snap.runId)?.reason).toBe(
      BRAIN_SNAPSHOT_REASON.manual,
    );
  });

  test("the standalone entry point refuses when the snapshot cannot be created", () => {
    // Same refusal as the wrapper's: an entry point that returned a
    // plausible-looking result on a host without tar would hand back a
    // recovery point that does not exist.
    const emptyDir = mkdtempSync(join(tmpdir(), "o2b-empty-path-take-"));
    const savedPath = process.env["PATH"];
    process.env["PATH"] = emptyDir;
    try {
      expect(() => takeSnapshot(vault, BRAIN_SNAPSHOT_REASON.manual)).toThrow();
      expect(listSnapshots(vault).snapshots).toHaveLength(0);
    } finally {
      process.env["PATH"] = savedPath;
      rmSync(emptyDir, { recursive: true, force: true });
    }
  });
});

describe("createUniqueSnapshot - the retry discriminator", () => {
  /**
   * The injected-creator tests below replay a collision with a synthetic
   * typed error, which proves the LOOP but not the WIRE: they would keep
   * passing if the real creator stopped producing a recognisable collision,
   * and a snapshot gate that cannot recognise one aborts the destructive
   * operation it exists to protect instead of laddering past a taken name.
   * So this one drives the real `createSnapshot` against an archive a peer
   * already wrote.
   */
  test("the real creator's collision is recognisable to the discriminator", () => {
    // The injected tests below prove the LOOP. This proves the WIRE: they
    // would keep passing if `createSnapshot` stopped producing an error the
    // discriminator recognises, and a gate that cannot recognise one aborts
    // the destructive operation it exists to protect rather than laddering
    // past a taken name.
    const taken = "dream-2026-06-01-120000";
    atomicWriteFileSync(snapshotPath(vault, taken), "a peer got here first");
    let thrown: unknown;
    try {
      createSnapshot(vault, taken, { reason: "dream" });
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeDefined();
    expect(isFileAlreadyExists(thrown)).toBe(true);
  });

  test("ladders past a name a peer takes after the availability probe", () => {
    // The gate's own probe skips a name already on disk, so the only way to
    // reach the creator's collision is to let the peer win in the window the
    // probe cannot see: the callback writes the winner's archive and then
    // runs the REAL creator against it.
    const base = "dream-2026-06-01-130000";
    const calls: string[] = [];
    const snapshot = createUniqueSnapshot(vault, base, (runId) => {
      calls.push(runId);
      if (calls.length === 1) {
        atomicWriteFileSync(snapshotPath(vault, runId), "a peer got here first");
      }
      return createSnapshot(vault, runId, { reason: "dream" }).path;
    });

    expect(calls).toEqual([base, `${base}-2`]);
    expect(snapshot.runId).toBe(`${base}-2`);
    expect(readFileSync(snapshotPath(vault, base), "utf8")).toBe("a peer got here first");
    expect(existsSync(snapshot.path)).toBe(true);
  });

  test("retries the next run id on a typed collision", () => {
    const calls: string[] = [];
    const snapshot = createUniqueSnapshot(vault, "dream-2026-06-01-000000", (runId) => {
      calls.push(runId);
      const path = snapshotPath(vault, runId);
      if (calls.length === 1) {
        atomicWriteFileSync(path, "winner");
        throw new FileAlreadyExistsError(path);
      }
      atomicWriteFileSync(path, "loser");
      return path;
    });

    expect(calls).toEqual(["dream-2026-06-01-000000", "dream-2026-06-01-000000-2"]);
    expect(snapshot.runId).toBe("dream-2026-06-01-000000-2");
    expect(snapshot.path).toBe(snapshotPath(vault, "dream-2026-06-01-000000-2"));
  });

  test("an unrelated failure propagates even when the archive path exists", () => {
    // The defect this replaces: the retry used to be discriminated by
    // re-running `existsSync` AFTER the throw, so a real failure that
    // left bytes behind (a compressor that died part-way through its
    // output) was read as a collision, retried, and finally reported as
    // an id-exhaustion that named neither the failure nor its cause.
    const real = new Error("zstd exited with status 1: No space left on device");
    const calls: string[] = [];
    expect(() =>
      createUniqueSnapshot(vault, "dream-2026-06-01-000000", (runId) => {
        calls.push(runId);
        atomicWriteFileSync(snapshotPath(vault, runId), "partial");
        throw real;
      }),
    ).toThrow(real);
    expect(calls).toHaveLength(1);
  });

  test("exhausts a bounded number of ids and says so", () => {
    let calls = 0;
    let thrown: unknown;
    try {
      createUniqueSnapshot(
        vault,
        "dream-2026-06-01-000000",
        (runId) => {
          calls += 1;
          throw new FileAlreadyExistsError(snapshotPath(vault, runId));
        },
        3,
      );
    } catch (err) {
      thrown = err;
    }
    expect(calls).toBe(3);
    expect((thrown as Error).message).toMatch(/could not reserve a unique snapshot run id/);
    expect((thrown as Error).message).toMatch(/after 3 attempts/);
    expect((thrown as Error).cause).toBeInstanceOf(FileAlreadyExistsError);
  });

  test("an EEXIST naming some other path propagates on the first attempt", () => {
    // GitHub #167. The discriminator used to be the errno alone, so ANY
    // EEXIST anywhere in the cause chain read as "a peer took this run id" -
    // including the one `createSnapshot` raises before it has touched a
    // single archive, when `mkdir Brain/.snapshots` fails. The ladder then
    // burned all 64 candidates and reported an id exhaustion that had never
    // happened, with the real errno buried on `cause`. A collision that does
    // not name THIS candidate's archive is not this loop's business.
    const calls: string[] = [];
    const unrelated = new Error(
      "EEXIST: file already exists, mkdir '/somewhere/entirely/else'",
    ) as NodeJS.ErrnoException;
    unrelated.code = "EEXIST";
    unrelated.path = "/somewhere/entirely/else";

    expect(() =>
      createUniqueSnapshot(vault, "dream-2026-06-01-000000", (runId) => {
        calls.push(runId);
        throw unrelated;
      }),
    ).toThrow(unrelated);
    expect(calls).toEqual(["dream-2026-06-01-000000"]);
  });
});

describe("an unusable Brain/.snapshots is diagnosed, not laddered past", () => {
  /**
   * The reproduction from GitHub #167, driven end to end on the two layers
   * that both got it wrong: `createSnapshot`, which raised a bare errno from
   * its very first `mkdir` and named nothing an operator could act on, and
   * the gate above it, which read that errno as a lost race.
   */
  const replaceSnapshotsDirWithFile = (): string => {
    const path = brainDirs(vault).snapshots;
    rmSync(path, { recursive: true, force: true });
    writeFileSync(path, "not a directory\n");
    return path;
  };

  test("createSnapshot names the archive directory and what is really there", () => {
    const path = replaceSnapshotsDirWithFile();
    let thrown: unknown;
    try {
      createSnapshot(vault, "dream-2026-06-01-000000", { reason: "dream" });
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(BrainSnapshotError);
    expect((thrown as Error).message).toContain(path);
    expect((thrown as Error).message).toContain("regular file");
    // The errno is kept, not replaced: the diagnosis explains it, and a
    // reader who wants the syscall still has it.
    expect(((thrown as Error).cause as NodeJS.ErrnoException).code).toBe("EEXIST");
  });

  test("dream reports the archive directory, not a fictional id exhaustion", () => {
    const path = replaceSnapshotsDirWithFile();
    let thrown: unknown;
    try {
      dream(vault, { now: new Date("2026-05-27T12:00:00Z") });
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeDefined();
    expect((thrown as Error).message).toContain(path);
    expect((thrown as Error).message).not.toMatch(/could not reserve a unique snapshot run id/);
  });
});