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
/**
 * A machine already switched for vault A that is then pointed at a vault
 * B still on the legacy layout (task 2.4, design D11 and D14): the
 * transition import takes B's records and its operator settings, binds B
 * only once nothing of B is left behind, and a rollback never restores
 * A's backup into B.
 */
import { afterEach, describe, expect, test } from "bun:test";
import { createHash } from "node:crypto";
import {
  appendFileSync,
  existsSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  realpathSync,
  renameSync,
  rmSync,
  statSync,
  writeFileSync,
} from "node:fs";
import { join, relative, sep } from "node:path";

import type { DoctorCheckContext, DoctorFindings } from "../../../src/core/brain/doctor/check.ts";
import {
  PERMISSIONS_LEGACY_ONLY_CODE,
  permissionsLegacyOnlyCheck,
} from "../../../src/core/brain/doctor/permissions-check.ts";
import { loadPermissionsDocumentFor } from "../../../src/core/brain/permissions/document-source.ts";
import { PERMISSIONS_DOCUMENT_SETTING } from "../../../src/core/brain/permissions/document.ts";
import { readVaultIdentity, writeVaultIdentity } from "../../../src/core/brain/vault-identity.ts";
import { appendRecord } from "../../../src/core/store/appender.ts";
import { buildRecord, type StoreRecord } from "../../../src/core/store/envelope.ts";
import { readPartition } from "../../../src/core/store/state-digest.ts";
import { openStore } from "../../../src/core/store/store-open.ts";
import { AUTHORITY_FIELD, SETTING_SET_KIND } from "../../../src/core/store/constants.ts";
import { holdMigrationGate, readMigrationGate } from "../../../src/core/migration-gate.ts";
import {
  migrationDir,
  readMigrationState,
  writeMigrationState,
} from "../../../src/core/store-migration/journal.ts";
import { runMigration } from "../../../src/core/store-migration/migrate.ts";
import { isDeviceSwitched } from "../../../src/core/store-migration/migration-records.ts";
import { migrateStore, rollback } from "../../../src/core/store-migration/outcome.ts";
import { RollbackRefusedError } from "../../../src/core/store-migration/rollback.ts";
import { migrationAvailability } from "../../../src/core/store/migration-availability.ts";
import {
  readVaultBindings,
  vaultBindingPath,
} from "../../../src/core/vault-adapter/vault-binding.ts";
import { makeFleet, type Fleet, type Machine } from "./fixtures/fleet.ts";
import {
  makeLegacyVault,
  UNMAPPED_LEGACY_ENTRIES,
  type LegacyVaultFixture,
} from "./fixtures/legacy-vault.ts";
import { moveNeverHeld } from "../../helpers/held-partitions.ts";

const FAST = { settleMs: 0 } as const;
const DENY_ALL = "version: 1\ndefault_action: deny\n";
const ALLOW_ALL = "version: 1\ndefault_action: allow\n";

let fleet: Fleet | null = null;
let second: LegacyVaultFixture | null = null;
afterEach(() => {
  fleet?.cleanup();
  fleet = null;
  second?.cleanup();
  second = null;
});

/**
 * The items of vault B a machine without `private` holds back: the
 * fixture's five private items (B's own, though A holds the same ones at
 * the same paths) and the secret page a test adds.
 */
const B_PRIVATE_ITEMS = 6;

const SIGNAL = (id: string, extra = ""): string =>
  `---\nid: ${id}\ntopic: ${id}\nprinciple: ${id}\n${extra}---\nRaw.\n`;

/** Every file below `dir` with its content hash, vault-relative. */
function treeDigest(dir: string): Record<string, string> {
  const out: Record<string, string> = {};
  const walk = (at: string): void => {
    for (const name of readdirSync(at)) {
      const path = join(at, name);
      if (statSync(path).isDirectory()) walk(path);
      else {
        out[relative(dir, path).split(sep).join("/")] = createHash("sha256")
          .update(readFileSync(path))
          .digest("hex");
      }
    }
  };
  walk(dir);
  return out;
}

/**
 * Machine dev-a switched for its own vault A (with an identity marker),
 * then a second legacy vault B with an identity of its own and a signal
 * the store does not hold.
 */
function switchedForA(withIdentity = true): { a: Machine; vaultB: string } {
  fleet = makeFleet(["dev-a"]);
  const a = fleet.machine("dev-a");
  a.use();
  if (withIdentity) writeVaultIdentity(a.vault);
  expect(runMigration(a.vault, FAST).ok).toBe(true);
  second = makeLegacyVault("osb-second-vault-");
  for (const rel of UNMAPPED_LEGACY_ENTRIES) {
    rmSync(join(second.vault, ...rel.split("/")), { force: true });
  }
  if (withIdentity) writeVaultIdentity(second.vault);
  second.write("Brain/inbox/2026-11-08-only-b.md", SIGNAL("sig-only-b"));
  return { a, vaultB: second.vault };
}

describe("rollback after a second vault was imported through the transition", () => {
  test("refuses for vault B, whose backup this machine never took, and touches nothing", () => {
    const { a, vaultB } = switchedForA();
    const outcome = migrateStore(vaultB, FAST);
    expect(outcome.mode).toBe("transition");
    const before = treeDigest(vaultB);
    const records = a.records().length;
    expect(() => rollback(vaultB)).toThrow(RollbackRefusedError);
    expect(() => rollback(vaultB)).toThrow(/backup .*another vault|not of this vault/);
    expect(treeDigest(vaultB)).toEqual(before);
    expect(a.records()).toHaveLength(records);
    expect(isDeviceSwitched(a.store(), "dev-a")).toBe(true);
  });

  test("decides by the vault path when neither vault has an identity marker", () => {
    const { a, vaultB } = switchedForA(false);
    migrateStore(vaultB, FAST);
    const before = treeDigest(vaultB);
    expect(() => rollback(vaultB)).toThrow(RollbackRefusedError);
    expect(treeDigest(vaultB)).toEqual(before);
    // Vault A, whose backup it is, still rolls back.
    expect(rollback(a.vault).unswitched).not.toBe("");
  });
});

describe("a private page of vault B on a machine that holds only shared", () => {
  test("keeps B unbound and the outcome not ok, then binds once the partition is back", () => {
    const { a, vaultB } = switchedForA();
    second!.write(
      "Brain/inbox/2026-11-08-secret.md",
      SIGNAL("sig-secret-b", "visibility: private\n"),
    );
    const aside = join(fleet!.parent, "private-aside");
    moveNeverHeld(a.storeRoot, aside);
    const held = migrateStore(vaultB, FAST);
    if (held.mode !== "transition") throw new Error("expected the transition");
    expect(held.held_back).toBe(B_PRIVATE_ITEMS);
    expect(held.ok).toBe(false);
    expect(held.bound).toBe(false);
    expect(readVaultBindings().map((v) => v.vault)).not.toContain(realpathSync(vaultB));
    expect(migrationAvailability({ vault: vaultB }).available).toBe(true);

    renameSync(aside, join(a.storeRoot, "private"));
    const again = migrateStore(vaultB, FAST);
    if (again.mode !== "transition") throw new Error("expected the transition");
    expect(again.held_back).toBe(0);
    expect(again.ok).toBe(true);
    expect(again.bound).toBe(true);
    expect(a.byKey().has("Brain/inbox/2026-11-08-secret.md")).toBe(true);
    expect(migrationAvailability({ vault: vaultB }).available).toBe(false);
  });
});

describe("vault B while a store shard cannot be seen", () => {
  test("is imported but not bound, the shard named, and bound once it reads again", () => {
    const { a, vaultB } = switchedForA();
    // A peer's shard this machine reads, then it is gone.
    const shard = appendRecord(openStore({ root: a.storeRoot, device: "dev-p" }), {
      partition: "shared",
      stream: "events",
      kind: "log-event",
      agent: "t",
      body: { timestamp: "2026-11-08T10:00:00Z", event_type: "note", body: { text: "peer" } },
    }).path;
    expect(a.records().length).toBeGreaterThan(0);
    const bytes = readFileSync(shard);
    rmSync(shard);
    const outcome = migrateStore(vaultB, FAST);
    if (outcome.mode !== "transition") throw new Error(`mode ${outcome.mode}`);
    expect(outcome.ok).toBe(false);
    expect(outcome.bound).toBe(false);
    expect(outcome.unseen_shards.join(",")).toContain("shared/events/dev-p/");
    expect(readVaultBindings().map((v) => realpathSync(v.vault))).toEqual([realpathSync(a.vault)]);
    writeFileSync(shard, bytes);
    const again = migrateStore(vaultB, FAST);
    if (again.mode !== "transition") throw new Error(`mode ${again.mode}`);
    expect(again.unseen_shards).toEqual([]);
    expect(again.bound).toBe(true);
  });
});

describe("operator settings of vault B", () => {
  test("its deny rules become the permissions document when the store holds none", () => {
    const { vaultB } = switchedForA();
    second!.write("Brain/_permissions.yaml", DENY_ALL);
    const outcome = migrateStore(vaultB, FAST);
    if (outcome.mode !== "transition") throw new Error("expected the transition");
    expect(outcome.settings?.written).toContain(PERMISSIONS_DOCUMENT_SETTING);
    expect(outcome.ok).toBe(true);
    expect(loadPermissionsDocumentFor(vaultB).document?.default_action).toBe("deny");
  });

  test("deny rules that differ from the stored document refuse the binding", () => {
    const { a, vaultB } = switchedForA();
    appendRecord(a.store(), {
      partition: "shared",
      stream: "settings",
      kind: SETTING_SET_KIND,
      agent: "o",
      body: { [AUTHORITY_FIELD]: "human", key: PERMISSIONS_DOCUMENT_SETTING, value: ALLOW_ALL },
    });
    second!.write("Brain/_permissions.yaml", DENY_ALL);
    const outcome = migrateStore(vaultB, FAST);
    if (outcome.mode !== "transition") throw new Error("expected the transition");
    // The stored document stays (never overwritten), B stays unbound and
    // offered, and the outcome names the conflict.
    expect(outcome.ok).toBe(false);
    expect(outcome.bound).toBe(false);
    expect(outcome.permissions_conflict).toBe(true);
    expect(loadPermissionsDocumentFor(vaultB).document?.default_action).toBe("allow");
    expect(migrationAvailability({ vault: vaultB }).available).toBe(true);
    // Doctor names the deny rules no gate reads.
    const out: DoctorFindings = { issues: [], uncertain: [] };
    permissionsLegacyOnlyCheck.run(
      {
        vault: vaultB,
        now: new Date("2026-11-08T12:00:00Z"),
        config: undefined,
        dbPath: undefined,
        configPath: undefined,
        knownBasenames: new Set(),
        idIndex: new Map(),
        preferences: [],
        logs: [],
      } satisfies DoctorCheckContext,
      out,
    );
    expect(out.issues.map((i) => i.code)).toContain(PERMISSIONS_LEGACY_ONLY_CODE);
  });

  test("the transition for the vault the machine switched with imports no settings", () => {
    const { a } = switchedForA();
    a.write("Brain/_permissions.yaml", DENY_ALL);
    const outcome = migrateStore(a.vault, FAST);
    if (outcome.mode !== "transition") throw new Error("expected the transition");
    expect(outcome.settings).toBeNull();
    expect(outcome.ok).toBe(true);
    expect(existsSync(join(a.vault, "Brain", "_permissions.yaml"))).toBe(true);
  });
});

describe("a migration of vault A killed after its switch record, then vault B configured", () => {
  /** What a kill right after `device-switched` leaves: the run in progress, the gate held, A unbound. */
  function interruptA(a: Machine): string {
    const dir = migrationDir(a.store());
    const state = readMigrationState(dir)!;
    writeMigrationState(dir, { ...state, phase: "in-progress" });
    holdMigrationGate(a.vault, state.run_id);
    rmSync(vaultBindingPath(), { force: true });
    return dir;
  }

  test("finishes A's switch and binds A, and B still passes the permissions check", () => {
    const { a, vaultB } = switchedForA();
    const dir = interruptA(a);
    appendRecord(a.store(), {
      partition: "shared",
      stream: "settings",
      kind: SETTING_SET_KIND,
      agent: "o",
      body: { [AUTHORITY_FIELD]: "human", key: PERMISSIONS_DOCUMENT_SETTING, value: ALLOW_ALL },
    });
    second!.write("Brain/_permissions.yaml", DENY_ALL);

    const outcome = migrateStore(vaultB, FAST);
    if (outcome.mode !== "transition") throw new Error("expected the transition");
    expect(readMigrationState(dir)?.phase).toBe("done");
    expect(readMigrationGate()).toBeNull();
    const bound = readVaultBindings().map((b) => b.vault);
    expect(bound).toContain(realpathSync(a.vault));
    expect(bound).not.toContain(realpathSync(vaultB));
    expect(outcome.settings).not.toBeNull();
    expect(outcome.permissions_conflict).toBe(true);
    expect(outcome.bound).toBe(false);
    expect(outcome.ok).toBe(false);
  });

  test("decides by the vault path when neither vault has an identity marker", () => {
    const { a, vaultB } = switchedForA(false);
    interruptA(a);
    second!.write(
      "Brain/inbox/2026-11-08-secret.md",
      SIGNAL("sig-secret-b", "visibility: private\n"),
    );
    moveNeverHeld(a.storeRoot, join(fleet!.parent, "private-aside"));
    const outcome = migrateStore(vaultB, FAST);
    if (outcome.mode !== "transition") throw new Error("expected the transition");
    expect(outcome.held_back).toBe(B_PRIVATE_ITEMS);
    expect(outcome.bound).toBe(false);
    const bound = readVaultBindings().map((b) => b.vault);
    expect(bound).toContain(realpathSync(a.vault));
    expect(bound).not.toContain(realpathSync(vaultB));
  });
});

describe("an item of vault B identical to one of vault A at the same path", () => {
  const LOG = "Brain/log/2026-10-01.jsonl";
  const imported = (a: Machine) =>
    a.records().filter((r) => {
      const mark = r.body["migrated"] as { key?: unknown } | undefined;
      return typeof mark?.key === "string" && mark.key.startsWith(`${LOG}#`);
    });

  test.each([true, false])("gets a store record of its own (identity marker: %p)", (marker) => {
    const { a, vaultB } = switchedForA(marker);
    // Both vaults hold the same first log row at the same relative path.
    expect(readFileSync(join(vaultB, ...LOG.split("/")), "utf8")).toBe(
      readFileSync(join(a.vault, ...LOG.split("/")), "utf8"),
    );
    expect(imported(a)).toHaveLength(1);
    const outcome = migrateStore(vaultB, FAST);
    expect(outcome.mode).toBe("transition");
    const records = imported(a);
    expect(records).toHaveLength(2);
    if (marker) {
      expect(new Set(records.map((r) => r.body["vault_id"])).size).toBe(2);
    }
    // A second run of either vault imports nothing more.
    migrateStore(vaultB, FAST);
    migrateStore(a.vault, FAST);
    expect(imported(a)).toHaveLength(2);
  });
});

describe("a rollback of vault A after vault B imported an identical row", () => {
  test.each([true, false])(
    "writes B's occurrence back beside A's (identity marker: %p)",
    (marker) => {
      const { a, vaultB } = switchedForA(marker);
      expect(migrateStore(vaultB, FAST).mode).toBe("transition");
      rollback(a.vault);
      // A's row is restored from its snapshot; B's separate occurrence of the
      // same row is replayed into this device's shard of the day.
      expect(rowsOfDay(a.vault, "2026-10-01")).toBe(2);
    },
  );
});

/** How many legacy log rows of `day` the vault holds, over every shard of the day. */
function rowsOfDay(vault: string, day: string): number {
  const dir = join(vault, "Brain", "log");
  return readdirSync(dir)
    .filter((name) => name.startsWith(day) && name.endsWith(".jsonl"))
    .flatMap((name) => readFileSync(join(dir, name), "utf8").split("\n"))
    .filter((line) => line.includes('"text":"x"')).length;
}

describe("a dual-written copy of an item vault B also holds", () => {
  const LOG = "Brain/log/2026-10-01.jsonl";
  const STORE_ONLY = ["vault_id", "legacy_device", "migrated"];

  /** A's imported record of the shared log row, its partition and its shard dir. */
  function sharedRow(a: Machine): { record: StoreRecord; partition: string; stream: string } {
    for (const partition of ["shared", "private"]) {
      for (const shard of readPartition(join(a.storeRoot, partition))) {
        const record = shard.all.find(
          (r) => (r.body["migrated"] as { key?: string } | undefined)?.key === `${LOG}#1`,
        );
        if (record !== undefined) return { record, partition, stream: shard.stream };
      }
    }
    throw new Error("A's log row is not in the store");
  }

  /**
   * Plant a copy of the row as a dual write left it: `device`'s bytes,
   * stamped before every record A's migration wrote (so not native), with
   * `vaultId` as its vault.
   */
  function plantCopy(a: Machine, device: string, vaultId: string | null): void {
    const { record, partition, stream } = sharedRow(a);
    const body: Record<string, unknown> = { ...record.body };
    for (const field of STORE_ONLY) delete body[field];
    if (vaultId !== null) body["vault_id"] = vaultId;
    const copy = buildRecord({
      hlc: { physical: Date.UTC(2026, 0, 1), counter: 0 },
      device,
      agent: record.agent,
      kind: record.kind,
      scope: record.scope,
      topic: null,
      body,
    });
    const dir = join(a.storeRoot, partition, stream, device);
    mkdirSync(dir, { recursive: true });
    appendFileSync(join(dir, "2026-01.jsonl"), `${JSON.stringify(copy)}\n`);
  }

  /** The records of B's own import of the shared row: marked with B's vault. */
  function importedForB(a: Machine, vaultB: string): StoreRecord[] {
    const pathSum = createHash("sha256").update(realpathSync(vaultB)).digest("hex");
    return a.records().filter((r) => {
      const mark = r.body["migrated"] as
        | { key?: string; vault?: { path_sum?: string } }
        | undefined;
      return mark?.key === `${LOG}#1` && mark.vault?.path_sum === pathSum;
    });
  }

  const cases: ReadonlyArray<[string, string, "a" | null]> = [
    ["another device, no vault", "dev-x", null],
    ["another device, vault A's marker", "dev-x", "a"],
    ["this device, no vault (A is the vault it migrated)", "dev-a", null],
    ["this device, vault A's marker", "dev-a", "a"],
  ];
  test.each(cases)("from %s is no import of B's item", (_label, device, vault) => {
    const { a, vaultB } = switchedForA(true);
    const markerA = readVaultIdentity(a.vault)!.vault_id;
    plantCopy(a, device, vault === "a" ? markerA : null);
    expect(migrateStore(vaultB, FAST).mode).toBe("transition");
    expect(importedForB(a, vaultB)).toHaveLength(1);
  });

  test("dual-written from vault B itself, it stands in for B's item", () => {
    const { a, vaultB } = switchedForA(true);
    plantCopy(a, "dev-a", readVaultIdentity(vaultB)!.vault_id);
    expect(migrateStore(vaultB, FAST).mode).toBe("transition");
    expect(importedForB(a, vaultB)).toHaveLength(0);
  });

  test("dual-written from vault B, a rollback of A writes it back beside A's row", () => {
    const { a, vaultB } = switchedForA(true);
    plantCopy(a, "dev-a", readVaultIdentity(vaultB)!.vault_id);
    expect(migrateStore(vaultB, FAST).mode).toBe("transition");
    rollback(a.vault);
    expect(rowsOfDay(a.vault, "2026-10-01")).toBe(2);
  });

  test.each(cases)("from %s, a rollback of A counts it as A's row", (_label, device, vault) => {
    const { a } = switchedForA(true);
    const markerA = readVaultIdentity(a.vault)!.vault_id;
    plantCopy(a, device, vault === "a" ? markerA : null);
    rollback(a.vault);
    expect(rowsOfDay(a.vault, "2026-10-01")).toBe(1);
  });
});