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
/**
* Moving a vault's state, and putting it back.
*
* The unit under test is the one operation in this project where a
* half-completed run is worse than no run at all: bytes that exist in
* neither the old place nor the new one are gone, and the surfaces the
* inventory calls `vault-content` do not rebuild. So the tests below are
* organised around the two guarantees that follow from that, rather than
* around the functions:
*
* - FAIL BEFORE COMMIT. Every refusal is driven with the source tree
* otherwise perfectly movable, and each one drives `applyStateMigration`
* and asserts that NOTHING moved - not that the call threw. A plan
* that reported a refusal and still copied half a tree would pass a
* throw-shaped assertion. Three of the seven used to stop at the
* plan: `reserved_namespace`, the unreadable-lock case and
* `unreadable_surface` never called apply at all, so their
* `expect(existsSync(dest)).toBe(false)` was true of a destination
* nothing had ever been asked to write.
* - PUT BACK ONLY WHAT IS STILL THE SAME. The rollback tests change a
* migrated file behind the tool's back and assert it is named,
* refused, and STILL THERE afterwards. Deleting a file the operator
* edited after the migration is the failure this half exists to
* prevent, and it is invisible to a test that only checks the exit
* code.
*/
import { afterEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
renameSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { canonicalJson, sealWithDigest, sha256Hex } from "../../../src/core/integrity/digest.ts";
import {
applyStateMigration,
applyStateRollback,
MIGRATION_MANIFEST_FILE,
MIGRATION_REFUSAL,
MIGRATION_SOURCE_TYPE,
planStateMigration,
planStateRollback,
renderRollbackPlan,
ROLLBACK_REFUSAL,
StateMigrationError,
type MigrationPlan,
} from "../../../src/core/state/migrate.ts";
import { STATE_SURFACE_ID, STATE_SURFACES } from "../../../src/core/state/surfaces.ts";
import { CHMOD_CANNOT_DENY, IS_WINDOWS } from "../../helpers/platform.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
const temps: string[] = [];
afterEach(() => {
while (temps.length > 0) rmSync(temps.pop()!, { recursive: true, force: true });
});
function tempDir(): string {
const dir = mkdtempSync(join(tmpdir(), "osb-state-migrate-"));
temps.push(dir);
return dir;
}
function write(path: string, body: string): void {
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, body);
}
/** The resolved location of one declared surface in `vault`, no overrides. */
function surfacePath(vault: string, id: string): string {
const surface = STATE_SURFACES.find((s) => s.id === id);
if (surface === undefined) throw new Error(`no such surface: ${id}`);
return surface.derive(vault, null);
}
/**
* A vault with real bytes under both roots, including one surface nested
* inside another so the canonical-root collapse is exercised by default
* rather than by a test that has to remember to arrange it.
*/
function seedVault(): string {
const vault = tempDir();
write(surfacePath(vault, STATE_SURFACE_ID.searchIndex), "index-bytes");
write(surfacePath(vault, STATE_SURFACE_ID.ingestContentManifest), "{}\n");
write(join(surfacePath(vault, STATE_SURFACE_ID.brainLog), "2026-08-16.md"), "# today\n");
write(join(surfacePath(vault, STATE_SURFACE_ID.dreamRuns), "run-1.jsonl"), "{}\n");
write(join(surfacePath(vault, STATE_SURFACE_ID.metrics), "recall.jsonl"), "{}\n");
return vault;
}
function plan(
vault: string,
destination: string,
extra: Record<string, unknown> = {},
): MigrationPlan {
return planStateMigration({
vault,
destination,
env: {},
config: {},
now: new Date("2026-08-16T10:00:00.000Z"),
...extra,
});
}
/** Every file under `root`, as vault-relative paths. */
function tree(root: string): string[] {
const out: string[] = [];
const walk = (dir: string, prefix: string): void => {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
if (entry.isDirectory()) walk(join(dir, entry.name), rel);
else out.push(rel);
}
};
if (existsSync(root)) walk(root, "");
return out.toSorted();
}
function refusalCodes(p: MigrationPlan): string[] {
return p.refusals.map((r) => r.code).toSorted();
}
/**
* The bar a remedy has to clear.
*
* It was `remedy.length > 20`, applied to one of the seven refusal codes,
* and `"TODO: fix this later!!"` is twenty-two characters. A remedy is
* the sentence that turns a refusal into something the operator can act
* on; the shortest real one in this module - "name an empty directory, or
* a path that does not exist yet" - is fifty-seven.
*/
const MIN_REMEDY_LENGTH = 50;
/** Words that mean nobody has decided yet, which is not a remedy. */
const LAZY_REMEDY_RE = /\bTODO\b|\bfor now\b|\blater\b/i;
/** Every refusal in `refusals` says what to DO, named when one does not. */
function expectActionableRemedies(
refusals: ReadonlyArray<{ readonly code: string; readonly remedy: string }>,
): void {
// Folded into one expectation whose value NAMES the offender: asserting
// per refusal would stop at the first and hide the rest.
const thin = refusals
.filter((r) => r.remedy.trim().length < MIN_REMEDY_LENGTH || LAZY_REMEDY_RE.test(r.remedy))
.map((r) => `${r.code}: ${r.remedy.trim()}`);
expect(thin.toSorted().join("\n")).toBe("");
}
describe("state migration plan", () => {
test("inventories every file under both roots with its byte count and digest", () => {
const vault = seedVault();
const p = plan(vault, join(tempDir(), "moved"));
expect(p.refusals).toEqual([]);
expect(p.manifest.source_type).toBe(MIGRATION_SOURCE_TYPE.vault);
expect(p.manifest.entries.map((e) => e.relative_path)).toEqual([
".open-second-brain/brain.sqlite",
".open-second-brain/ingest-manifest.json",
"Brain/log/2026-08-16.md",
"Brain/log/dream-runs/run-1.jsonl",
"Brain/metrics/recall.jsonl",
]);
const index = p.manifest.entries.find(
(e) => e.relative_path === ".open-second-brain/brain.sqlite",
);
expect(index?.bytes).toBe("index-bytes".length);
expect(index?.digest).toBe(sha256Hex("index-bytes"));
expect(p.manifest.total_bytes).toBe(p.manifest.entries.reduce((sum, e) => sum + e.bytes, 0));
});
test("collapses a nested surface into the canonical root that contains it", () => {
const vault = seedVault();
const p = plan(vault, join(tempDir(), "moved"));
// A root is a DECLARED surface, never its parent directory: the two
// files under the derived store are two surfaces and stay two roots,
// so nothing undeclared beside them is swept along. `Brain/log/dream-
// runs` IS declared and IS under `Brain/log`, so it is absorbed;
// without the collapse its files would be bound twice.
expect(p.manifest.canonical_roots).toEqual([
".open-second-brain/brain.sqlite",
".open-second-brain/ingest-manifest.json",
"Brain/log",
"Brain/metrics",
]);
});
test("binds the manifest through canonicalJson so a byte edit invalidates it", () => {
const vault = seedVault();
const p = plan(vault, join(tempDir(), "moved"));
const { digest, ...bound } = p.manifest;
expect(digest).toBe(sha256Hex(canonicalJson(bound)));
});
test("the manifest seal is the integrity module's seal, byte for byte", () => {
// The module's private seal became a thin alias over the lifted
// `sealWithDigest`; this pins the aliasing as behavior-preserving:
// the sealed manifest is exactly what the shared primitive returns
// for the same bound body.
const vault = seedVault();
const p = plan(vault, join(tempDir(), "moved"));
const { digest: _digest, ...bound } = p.manifest;
expect(sealWithDigest(bound)).toEqual(p.manifest);
});
});
describe("state migration refuses before it commits", () => {
test("a symlink in the source tree, by name", () => {
const vault = seedVault();
const link = join(surfacePath(vault, STATE_SURFACE_ID.metrics), "elsewhere.jsonl");
symlinkSync("/etc/hostname", link);
const dest = join(tempDir(), "moved");
const p = plan(vault, dest);
expect(refusalCodes(p)).toContain(MIGRATION_REFUSAL.symlink);
const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.symlink)!;
expect(refusal.path).toBe(link);
// The link target as the host reports it (`C:\etc\hostname` on Windows).
expect(refusal.found).toContain(resolve("/etc/hostname"));
expectActionableRemedies(p.refusals);
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
expect(existsSync(dest)).toBe(false);
});
// Windows has no FIFOs (mkfifo), so the special-file refusal cannot be staged.
test.skipIf(IS_WINDOWS)("a special file in the source tree, by name", () => {
const vault = seedVault();
const fifo = join(surfacePath(vault, STATE_SURFACE_ID.metrics), "pipe");
const made = Bun.spawnSync(["mkfifo", fifo]);
expect(made.exitCode).toBe(0);
const dest = join(tempDir(), "moved");
const p = plan(vault, dest);
const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.specialFile);
expect(refusal?.path).toBe(fifo);
expect(refusal?.found).toContain("FIFO");
expectActionableRemedies(p.refusals);
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
expect(existsSync(dest)).toBe(false);
});
test("a destination that already holds content", () => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
write(join(dest, "notes", "keep.md"), "mine\n");
const p = plan(vault, dest);
const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.destinationOccupied);
expect(refusal?.path).toBe(dest);
expect(refusal?.found).toContain("notes");
expectActionableRemedies(p.refusals);
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
expect(tree(dest)).toEqual(["notes/keep.md"]);
});
test("a destination inside the source vault, as a reserved namespace", () => {
const vault = seedVault();
const dest = join(vault, "inside");
const p = plan(vault, dest);
const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.reservedNamespace);
expect(refusal?.path).toBe(dest);
expect(refusal?.found).toContain(vault);
expectActionableRemedies(p.refusals);
// The apply is the assertion. Without it `existsSync(dest)` was true
// of a path nothing had been asked to create, which is a fact about
// this test rather than about the module.
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
expect(existsSync(dest)).toBe(false);
for (const entry of p.manifest.entries) {
expect(existsSync(join(vault, entry.relative_path))).toBe(true);
}
});
test("insufficient free space at the destination", () => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
const p = plan(vault, dest, { freeBytesAt: () => 1 });
const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.insufficientSpace);
expect(refusal?.found).toContain("1 byte");
expectActionableRemedies(p.refusals);
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
expect(existsSync(dest)).toBe(false);
});
test("a held search writer lock, which is the one loss a digest cannot undo", () => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
const p = plan(vault, dest, { writerLockHeldAt: () => true });
const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.writerLockHeld);
expect(refusal?.path).toBe(surfacePath(vault, STATE_SURFACE_ID.searchIndex));
expect(refusal?.remedy).toContain("reindex");
expectActionableRemedies(p.refusals);
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
expect(existsSync(dest)).toBe(false);
});
test("a lock whose state could not be determined is refused, not assumed free", () => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
const p = plan(vault, dest, {
writerLockHeldAt: () => {
throw Object.assign(new Error("permission denied"), { code: "EACCES" });
},
});
const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.writerLockHeld);
expect(refusal?.found).toContain("EACCES");
expectActionableRemedies(p.refusals);
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
expect(existsSync(dest)).toBe(false);
});
test("a surface that could not be probed, rather than silently leaving it behind", () => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
const p = plan(vault, dest, {
statAt: (path: string) => {
if (path.endsWith("metrics")) throw Object.assign(new Error("nope"), { code: "EACCES" });
return undefined;
},
});
const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.unreadableSurface);
expect(refusal?.path).toBe(surfacePath(vault, STATE_SURFACE_ID.metrics));
expect(refusal?.found).toContain("EACCES");
expectActionableRemedies(p.refusals);
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
expect(existsSync(dest)).toBe(false);
// Named rather than looped over `p.manifest.entries`: the stub
// reports every OTHER surface absent, so that list is empty here and
// a loop over it would assert nothing at all.
expect(existsSync(join(surfacePath(vault, STATE_SURFACE_ID.metrics), "recall.jsonl"))).toBe(
true,
);
expect(existsSync(surfacePath(vault, STATE_SURFACE_ID.searchIndex))).toBe(true);
});
test("a destination that reaches the vault through a symlink, which resolve() cannot see", () => {
// `resolve` is a string operation: it collapses `..` and knows
// nothing about links, so a destination whose parent is a link INTO
// the vault passed every prefix test while landing the whole state
// tree inside the vault being migrated.
const vault = seedVault();
const link = join(tempDir(), "link");
symlinkSync(join(vault, "Brain"), link);
const dest = join(link, "state");
const p = plan(vault, dest);
const refusal = p.refusals.find((r) => r.code === MIGRATION_REFUSAL.reservedNamespace);
expect(refusal?.path).toBe(dest);
expect(refusal?.found).toContain(vault);
expectActionableRemedies(p.refusals);
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
expect(existsSync(dest)).toBe(false);
});
// chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
test.skipIf(CHMOD_CANNOT_DENY)(
"a directory in the state tree that cannot be listed, as a refusal not a stack",
() => {
const vault = seedVault();
const locked = surfacePath(vault, STATE_SURFACE_ID.metrics);
chmodSync(locked, 0o000);
try {
const p = plan(vault, join(tempDir(), "moved"), { writerLockHeldAt: () => true });
const refusal = p.refusals.find(
(r) => r.code === MIGRATION_REFUSAL.unreadableSurface && r.path === locked,
);
expect(refusal?.found).toContain("EACCES");
// The headline contract: an unreadable directory is one refusal
// among all of them, not a throw that leaves the rest uncomputed.
expectActionableRemedies(p.refusals);
expect(refusalCodes(p)).toContain(MIGRATION_REFUSAL.writerLockHeld);
expect(p.manifest.entries.map((e) => e.relative_path)).toContain(
".open-second-brain/brain.sqlite",
);
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
} finally {
chmodSync(locked, 0o755);
}
},
);
test("a surface root that is a DANGLING symlink reaches the symlink refusal", () => {
// `statSync` follows the link and reports the missing target as
// ENOENT, so the surface read as `absent` and the migration skipped
// it in silence - the one outcome a refusal-shaped module must not
// have. Deeper in the tree the same link is caught by name.
const vault = seedVault();
const metrics = surfacePath(vault, STATE_SURFACE_ID.metrics);
rmSync(metrics, { recursive: true, force: true });
symlinkSync(join(vault, "nowhere"), metrics);
const p = plan(vault, join(tempDir(), "moved"));
const refusal = p.refusals.find(
(r) => r.code === MIGRATION_REFUSAL.symlink && r.path === metrics,
);
expect(refusal?.found).toContain("nowhere");
expectActionableRemedies(p.refusals);
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
});
test("every refusal is collected, so one run tells the operator all of it", () => {
const vault = seedVault();
symlinkSync("/etc/hostname", join(surfacePath(vault, STATE_SURFACE_ID.metrics), "link"));
const dest = join(vault, "inside");
write(join(dest, "already.md"), "here first\n");
const p = plan(vault, dest, { freeBytesAt: () => 0, writerLockHeldAt: () => true });
expect(refusalCodes(p)).toEqual(
[
MIGRATION_REFUSAL.destinationOccupied,
MIGRATION_REFUSAL.insufficientSpace,
MIGRATION_REFUSAL.reservedNamespace,
MIGRATION_REFUSAL.symlink,
MIGRATION_REFUSAL.writerLockHeld,
].toSorted(),
);
});
});
describe("state migration apply", () => {
test("lands every bound file, writes the manifest, and empties the source", () => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
const p = plan(vault, dest);
const result = applyStateMigration(p);
expect(result.manifest_path).toBe(join(dest, MIGRATION_MANIFEST_FILE));
expect(tree(dest).filter((f) => f !== MIGRATION_MANIFEST_FILE)).toEqual(
p.manifest.entries.map((e) => e.relative_path),
);
expect(readFileSync(join(dest, ".open-second-brain/brain.sqlite"), "utf8")).toBe("index-bytes");
for (const entry of p.manifest.entries) {
expect(existsSync(join(vault, entry.relative_path))).toBe(false);
}
expect(result.moved).toEqual(p.manifest.entries.map((e) => e.relative_path));
});
test("a manifest written by apply is the plan's manifest, digest and all", () => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
const p = plan(vault, dest);
applyStateMigration(p);
const onDisk = JSON.parse(readFileSync(join(dest, MIGRATION_MANIFEST_FILE), "utf8"));
expect(onDisk.digest).toBe(p.manifest.digest);
const { digest, ...bound } = onDisk;
expect(digest).toBe(sha256Hex(canonicalJson(bound)));
});
/**
* The module's stated core guarantee, driven by a REAL mid-copy failure
* rather than a mocked one: the bytes of the third bound file change
* after the plan measured them, so its copy lands, fails the digest
* check, and aborts the pass with two files already at the destination.
*/
test("a copy that fails half way unwinds the destination and leaves the source as it was", () => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
const p = plan(vault, dest);
const before = p.manifest.entries.map((e) =>
readFileSync(join(vault, e.relative_path), "utf8"),
);
writeFileSync(join(vault, "Brain/log/2026-08-16.md"), "# today, rewritten after the plan\n");
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
// Nothing of ours is left at the destination, not even the directory
// skeleton `mkdirSync` created on the way down: the identical command
// is retried, not refused with `destination_occupied`.
expect(existsSync(dest)).toBe(false);
expect(plan(vault, dest).refusals).toEqual([]);
// And the source is exactly as the run found it - the one file this
// test rewrote aside, which is the failure it drove.
p.manifest.entries.forEach((entry, at) => {
expect(existsSync(join(vault, entry.relative_path))).toBe(true);
if (entry.relative_path === "Brain/log/2026-08-16.md") return;
expect(readFileSync(join(vault, entry.relative_path), "utf8")).toBe(before[at]!);
});
});
test("a file that appeared at the destination after the plan is never overwritten", () => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
const p = plan(vault, dest);
// `destination_occupied` was measured before the operator read the
// plan. What arrives afterwards used to be copied over AND then
// deleted by the unwind, which cannot tell a file it created from one
// it clobbered.
const theirs = join(dest, "Brain/metrics/recall.jsonl");
write(theirs, "SOMEONE-ELSES-FILE\n");
expect(() => applyStateMigration(p)).toThrow(StateMigrationError);
expect(readFileSync(theirs, "utf8")).toBe("SOMEONE-ELSES-FILE\n");
expect(tree(dest)).toEqual(["Brain/metrics/recall.jsonl"]);
for (const entry of p.manifest.entries) {
expect(existsSync(join(vault, entry.relative_path))).toBe(true);
}
});
// chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
test.skipIf(CHMOD_CANNOT_DENY)(
"a source it cannot remove says the bytes are safe and names the manifest",
() => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
const p = plan(vault, dest);
// Readable and traversable, but not writable: every file lands and
// verifies, and the unlink pass is the thing that fails.
const metrics = surfacePath(vault, STATE_SURFACE_ID.metrics);
chmodSync(metrics, 0o500);
try {
let caught: unknown;
try {
applyStateMigration(p);
} catch (error) {
caught = error;
}
expect(caught).toBeInstanceOf(StateMigrationError);
expect((caught as Error).message).toContain(join(dest, MIGRATION_MANIFEST_FILE));
expect((caught as Error).message).toContain("rollback");
expect(readFileSync(join(dest, "Brain/metrics/recall.jsonl"), "utf8")).toBe("{}\n");
} finally {
chmodSync(metrics, 0o755);
}
},
);
});
describe("state rollback", () => {
function migrated(): { vault: string; dest: string } {
const vault = seedVault();
const dest = join(tempDir(), "moved");
applyStateMigration(plan(vault, dest));
return { vault, dest };
}
test("restores every entry whose digest still matches", () => {
const { vault, dest } = migrated();
const p = planStateRollback({ destination: dest });
expect(p.refusals).toEqual([]);
const result = applyStateRollback(p);
expect(result.restored).toEqual(p.restore.map((e) => e.relative_path));
expect(readFileSync(join(vault, ".open-second-brain/brain.sqlite"), "utf8")).toBe(
"index-bytes",
);
expect(existsSync(join(dest, ".open-second-brain/brain.sqlite"))).toBe(false);
expect(existsSync(join(dest, MIGRATION_MANIFEST_FILE))).toBe(false);
});
test("refuses a file changed after the migration BY NAME and leaves it alone", () => {
const { vault, dest } = migrated();
const edited = join(dest, "Brain/log/2026-08-16.md");
writeFileSync(edited, "# today\nplus a line the operator added\n");
const p = planStateRollback({ destination: dest });
const refusal = p.refusals.find((r) => r.code === ROLLBACK_REFUSAL.digestMismatch);
expect(refusal?.relative_path).toBe("Brain/log/2026-08-16.md");
expect(refusal?.remedy).toContain("copy");
expectActionableRemedies(p.refusals);
const result = applyStateRollback(p);
expect(result.refused.map((r) => r.relative_path)).toEqual(["Brain/log/2026-08-16.md"]);
expect(readFileSync(edited, "utf8")).toContain("the operator added");
expect(existsSync(join(vault, "Brain/log/2026-08-16.md"))).toBe(false);
// The manifest survives an incomplete rollback: the refused entry is
// still bound by it, and deleting it would strand the only record of
// where that file came from.
expect(existsSync(join(dest, MIGRATION_MANIFEST_FILE))).toBe(true);
});
test("refuses an entry missing from the destination rather than inventing one", () => {
const { dest } = migrated();
rmSync(join(dest, "Brain/metrics/recall.jsonl"));
const p = planStateRollback({ destination: dest });
const refusal = p.refusals.find((r) => r.code === ROLLBACK_REFUSAL.missingAtDestination);
expect(refusal?.relative_path).toBe("Brain/metrics/recall.jsonl");
expectActionableRemedies(p.refusals);
});
test("refuses to clobber a source path that diverged since the migration", () => {
const { vault, dest } = migrated();
write(join(vault, "Brain/metrics/recall.jsonl"), "written again since\n");
const p = planStateRollback({ destination: dest });
const refusal = p.refusals.find((r) => r.code === ROLLBACK_REFUSAL.sourceDiverged);
expect(refusal?.relative_path).toBe("Brain/metrics/recall.jsonl");
expectActionableRemedies(p.refusals);
applyStateRollback(p);
expect(readFileSync(join(vault, "Brain/metrics/recall.jsonl"), "utf8")).toBe(
"written again since\n",
);
expect(existsSync(join(dest, "Brain/metrics/recall.jsonl"))).toBe(true);
});
test("a source path already back in place with the same bytes counts as restored", () => {
const { vault, dest } = migrated();
// The shape a crash between the copy and the removal leaves behind.
write(join(vault, "Brain/metrics/recall.jsonl"), "{}\n");
const p = planStateRollback({ destination: dest });
expect(p.refusals).toEqual([]);
const result = applyStateRollback(p);
expect(result.restored).toContain("Brain/metrics/recall.jsonl");
});
test("a source path that appeared between the plan and the apply is never overwritten", () => {
const { vault, dest } = migrated();
const p = planStateRollback({ destination: dest });
expect(p.refusals).toEqual([]);
// The plan cleared this entry against an empty source path. The
// operator wrote there while reading it, and the apply used to copy
// straight over them.
const target = join(vault, "Brain/metrics/recall.jsonl");
write(target, "OPERATOR-WROTE-THIS-AFTER-PLANNING\n");
const result = applyStateRollback(p);
expect(readFileSync(target, "utf8")).toBe("OPERATOR-WROTE-THIS-AFTER-PLANNING\n");
expect(result.restored).not.toContain("Brain/metrics/recall.jsonl");
expect(result.refused.map((r) => r.code)).toContain(ROLLBACK_REFUSAL.sourceDiverged);
expect(existsSync(join(dest, "Brain/metrics/recall.jsonl"))).toBe(true);
expect(result.manifest_removed).toBe(false);
expect(existsSync(join(dest, MIGRATION_MANIFEST_FILE))).toBe(true);
});
test("one entry it cannot read is refused by name and the rest still go back", () => {
const { vault, dest } = migrated();
// The source path recreated as a DIRECTORY: reading it for a digest
// fails with EISDIR, which used to abort the whole plan and take
// every other restorable entry with it.
mkdirSync(join(vault, "Brain/metrics/recall.jsonl"), { recursive: true });
const p = planStateRollback({ destination: dest });
const refusal = p.refusals.find((r) => r.code === ROLLBACK_REFUSAL.unreadable);
expect(refusal?.relative_path).toBe("Brain/metrics/recall.jsonl");
expect(refusal?.found).toContain("EISDIR");
expectActionableRemedies(p.refusals);
expect(p.restore.map((e) => e.relative_path)).toContain("Brain/log/2026-08-16.md");
const result = applyStateRollback(p);
expect(result.restored).toContain("Brain/log/2026-08-16.md");
expect(existsSync(join(dest, "Brain/metrics/recall.jsonl"))).toBe(true);
expect(result.manifest_removed).toBe(false);
});
test("a directory the prune cannot look inside is left alone, not judged empty", () => {
const { dest } = migrated();
// Listable, but its children cannot be stat'ed. Reading that as
// "empty" made the `rmdir` below throw ENOTEMPTY out of a rollback
// that had in fact succeeded.
const opaque = join(dest, "Brain/metrics/extra");
write(join(opaque, "keep.jsonl"), "not ours\n");
chmodSync(opaque, 0o444);
try {
const result = applyStateRollback(planStateRollback({ destination: dest }));
expect(result.restored).toContain("Brain/metrics/recall.jsonl");
expect(existsSync(opaque)).toBe(true);
} finally {
chmodSync(opaque, 0o755);
}
});
test("refuses a source root that is no longer there rather than recreating it", () => {
const { vault, dest } = migrated();
const renamed = `${vault}-renamed`;
renameSync(vault, renamed);
temps.push(renamed);
let caught: unknown;
try {
planStateRollback({ destination: dest });
} catch (error) {
caught = error;
}
expect(caught).toBeInstanceOf(StateMigrationError);
expect((caught as Error).message).toContain(vault);
expect((caught as Error).message).toContain("--to");
// The dead path stays dead, and the only copies stay where they are.
expect(existsSync(vault)).toBe(false);
expect(existsSync(join(dest, ".open-second-brain/brain.sqlite"))).toBe(true);
expect(existsSync(join(dest, MIGRATION_MANIFEST_FILE))).toBe(true);
});
test("--to restores into the vault's new location and still reports the recorded root", () => {
const { vault, dest } = migrated();
const renamed = `${vault}-renamed`;
renameSync(vault, renamed);
temps.push(renamed);
const p = planStateRollback({ destination: dest, vault: renamed });
expect(p.source).toBe(renamed);
expect(p.manifest.source_root).toBe(vault);
expect(renderRollbackPlan(p)).toContain(vault);
const result = applyStateRollback(p);
expect(result.restored).toContain(".open-second-brain/brain.sqlite");
expect(readFileSync(join(renamed, ".open-second-brain/brain.sqlite"), "utf8")).toBe(
"index-bytes",
);
expect(existsSync(vault)).toBe(false);
});
test("refuses a manifest whose own digest does not verify", () => {
const { dest } = migrated();
const manifestPath = join(dest, MIGRATION_MANIFEST_FILE);
const doc = JSON.parse(readFileSync(manifestPath, "utf8"));
doc.entries[0].bytes = 0;
writeFileSync(manifestPath, JSON.stringify(doc));
expect(() => planStateRollback({ destination: dest })).toThrow(StateMigrationError);
});
});
/**
* Every declared refusal code is REACHED by something here.
*
* A code nobody drives is a branch nobody has read: `ROLLBACK_REFUSAL.
* unreadable` was declared and produced nowhere for a release, and the
* suite was as green then as it is now. This block builds the conditions
* itself rather than accumulating codes seen by the tests above, so it
* says the same thing when one test is run in isolation as it does when
* the file is run whole.
*/
describe("every declared refusal code is reachable", () => {
// Windows has no FIFOs (mkfifo), so the special-file refusal cannot be staged.
test.skipIf(IS_WINDOWS)("the migration codes, all seven, with a remedy each", () => {
// Six from one plan, because they are independent conditions and a
// plan collects all of them; the seventh needs a probe that throws,
// which would hide the surfaces the other six are read from.
const vault = seedVault();
const metrics = surfacePath(vault, STATE_SURFACE_ID.metrics);
symlinkSync("/etc/hostname", join(metrics, "link"));
expect(Bun.spawnSync(["mkfifo", join(metrics, "pipe")]).exitCode).toBe(0);
const occupied = join(vault, "inside");
write(join(occupied, "already.md"), "here first\n");
const many = plan(vault, occupied, { freeBytesAt: () => 0, writerLockHeldAt: () => true });
const unreadable = plan(vault, join(tempDir(), "moved"), {
statAt: (path: string) => {
if (path.endsWith("metrics")) throw Object.assign(new Error("nope"), { code: "EACCES" });
return undefined;
},
});
const seen = new Set([...refusalCodes(many), ...refusalCodes(unreadable)]);
const unreached = Object.values(MIGRATION_REFUSAL).filter((code) => !seen.has(code));
expect(unreached.toSorted().join("\n")).toBe("");
expectActionableRemedies([...many.refusals, ...unreadable.refusals]);
});
test("the rollback codes, all four, with a remedy each", () => {
const vault = seedVault();
const dest = join(tempDir(), "moved");
applyStateMigration(plan(vault, dest));
// One condition per bound entry, so no two of them compete for the
// same file and the plan has to report all four.
writeFileSync(join(dest, ".open-second-brain/brain.sqlite"), "edited at the destination");
rmSync(join(dest, ".open-second-brain/ingest-manifest.json"));
write(join(vault, "Brain/log/2026-08-16.md"), "# written again since\n");
mkdirSync(join(vault, "Brain/log/dream-runs/run-1.jsonl"), { recursive: true });
const p = planStateRollback({ destination: dest });
const seen = new Set(p.refusals.map((r) => r.code));
const unreached = Object.values(ROLLBACK_REFUSAL).filter((code) => !seen.has(code));
expect(unreached.toSorted().join("\n")).toBe("");
expectActionableRemedies(p.refusals);
});
});