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
21.1 KB
Raw Blame
/**
 * `o2b brain migrate-store --rollback` (task 2.6, design D11 "Rollback"):
 * take this machine back to the legacy layout, until the legacy tree
 * leaves the vault.
 *
 *  1. Hold the device-local migration gate, so no content writer on this
 *     machine writes while the tree is rebuilt.
 *  2. Import the late legacy writes (design D11a: what a machine on the
 *     old release wrote into this tree since the last transition import),
 *     then restore `Brain/` from the migration snapshot (the copy kept in the
 *     backup when the archive is gone from `.snapshots/`), then every
 *     backed-up surface. The restore loses nothing the import could not
 *     take: an import that did not settle, or that held items back for a
 *     partition this machine does not hold, refuses the rollback; when it
 *     left unparseable items, the tree is first copied aside into the
 *     device-local migration folder and the copy is named in the report.
 *  3. Replay, in fold order, every store record whose identity is absent
 *     from the restored tree, through the legacy exporters
 *     (`exporters.ts`). An imported record is present when the restored
 *     tree holds its item with the same checksum; any other record is
 *     present when a restored item builds a record of the same kind and
 *     body (the multiset match the migration uses for dual-written
 *     copies). Both matches are per vault, as the migration journal's: a
 *     record another vault's import marked, or a dual write stamped with
 *     another vault's marker, is that vault's own occurrence and is
 *     written back beside this vault's. That covers records written after
 *     the switch and remote records that arrived late, from every device.
 *     Kinds with no legacy form stay in the store and are counted in the
 *     report.
 *  4. Record `device-unswitched` for this device (`isDeviceSwitched` then
 *     answers false), clear the sticky store-only marker for this device,
 *     and mark the migration rolled back.
 *
 * The run is journaled per replayed record in the device-local state (a
 * start line before each write, the id after it), so a resumed rollback
 * skips the restore it already did and every record it already replayed.
 *
 * Refused: once the legacy tree left the vault (this machine's removal
 * marker, or any device's `legacy-tree-removed` record for the vault),
 * for a vault the migration backup was not taken of (a vault configured
 * after the switch, imported by the transition, has none: its legacy tree
 * was never changed), and on a device that is not switched unless an unfinished rollback is
 * resumed, so a finished rollback run again never restores the old
 * snapshot over the legacy writes made since. Refused too, with the
 * shards named and the switch kept, while any held store shard cannot be
 * read in full (unreadable, gone since this machine read it, or read only
 * in part): a record in one would never be written back once the switch
 * is cleared. That is checked before anything is touched, and again over
 * the records the replay uses, before the restore.
 */

import {
  appendFileSync,
  cpSync,
  existsSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { join } from "node:path";

import { BRAIN_ROOT_REL, BRAIN_SNAPSHOT_EXCLUDED_ENTRIES } from "../brain/path-constants.ts";
import { snapshotPath } from "../brain/paths.ts";
import { extractSnapshotToTemp } from "../brain/snapshot.ts";
import { readVaultIdentity } from "../brain/vault-identity.ts";
import { appendRecord } from "../store/appender.ts";
import { AUTHORITY_FIELD, LEDGER_ROW_KIND } from "../store/constants.ts";
import { readPartition } from "../store/state-digest.ts";
import { partitionDir } from "../store/store-paths.ts";
import { compareRecords, type StoreRecord } from "../store/envelope.ts";
import { clearSwitchMarker, deviceSwitchedHere } from "../store/store-only.ts";
import { unbindVaultFromStore } from "../vault-adapter/vault-binding.ts";
import type { StoreHandle } from "../store/store-open.ts";
import {
  backupVaultMismatch,
  journalScopeFor,
  readMigrationBackup,
  restoreMigrationBackups,
  snapshotCopyIn,
} from "./backup.ts";
import { removeDeviceTokens } from "./device-config.ts";
import { itemRecords, migrationCatalogue, recordDestination } from "./catalogue.ts";
import { contentKey, itemKey, itemSum } from "./convert.ts";
import { EXPORTED_KINDS, exportRecords, type RefusedRecord, type StartMark } from "./exporters.ts";
import {
  describeUnseen,
  migrationDir,
  readHeldRecords,
  readMigrationState,
  unseenHeldShards,
  writeMigrationState,
  type UnseenShards,
} from "./journal.ts";
import {
  copyNamesOtherVault,
  markVault,
  sameJournalVault,
  type JournalScope,
} from "./journal-scope.ts";
import { emptyTally, scanLocator } from "./legacy-scan.ts";
import {
  DEVICE_UNSWITCHED_KIND,
  legacyTreeRemovedRecords,
  MIGRATION_STREAM,
  migratedMark,
} from "./migration-records.ts";
import { holdGateFor, releaseGateFor } from "./quiesce.ts";
import { readRemovalInProgress } from "./removal.ts";
import { readRemovalMarker, sameVaultPath } from "./removal-marker.ts";
import {
  GATED_IMPORT_WAIT_MS,
  importLateLegacyWrites,
  type TransitionResult,
} from "./transition.ts";

const ROLLBACK_STATE = "rollback.json";
const ROLLBACK_JOURNAL = "rollback-journal.jsonl";
/** Where a rollback copies a legacy tree holding late items it could not import. */
const ROLLBACK_KEPT_DIR = "rollback-kept";

/**
 * Fault-injection point; the CLI never sets it. It stays because the crash
 * test must kill a rollback between two replayed records (the kill-child
 * test SIGKILLs itself here), which a kill from outside cannot time.
 */
export interface RollbackHooks {
  readonly afterReplayed?: (count: number) => void;
}

export interface RollbackResult {
  readonly device: string;
  readonly restored_files: number;
  readonly restored_backups: number;
  /** Ids of the records written back this run, in fold order. */
  readonly replayed: ReadonlyArray<string>;
  /** Records left in the store because their kind has no legacy form, by kind. */
  readonly no_legacy_form: Readonly<Record<string, number>>;
  /**
   * Ledger rows written after the switch (or arrived late) that stay in the
   * store only, by ledger: the legacy ledgers do not get them back, so the
   * old release does not see them (idempotency receipts, continuity,
   * truth claims). Reported as a warning.
   */
  readonly ledger_rows_kept: Readonly<Record<string, number>>;
  /**
   * Records not written back because a path they name leaves `Brain/` (or
   * a log timestamp is no date, a preference id no slug), with the reason:
   * a synced peer can write any body (`exporters.ts`).
   */
  readonly refused: ReadonlyArray<RefusedRecord>;
  readonly unswitched: string;
  /**
   * The device-config MCP token map the migration copied, set aside
   * because it changed since (null when it was removed or there was none):
   * the per-vault file is the token map again.
   */
  readonly device_tokens_aside: string | null;
  /**
   * Where the legacy tree was copied before the restore because the late
   * import left items it could not read (null when it left none): those
   * items are in neither the store nor the snapshot.
   */
  readonly legacy_tree_kept: string | null;
}

/** A rollback that cannot run, with the reason. */
export class RollbackRefusedError extends Error {
  override readonly name = "RollbackRefusedError";
}

interface RollbackState {
  readonly restored: boolean;
  readonly restored_files: number;
  readonly restored_backups: number;
}

function readState(dir: string): RollbackState | null {
  try {
    return JSON.parse(readFileSync(join(dir, ROLLBACK_STATE), "utf8")) as RollbackState;
  } catch {
    return null;
  }
}

/** The journal line a record gets before its write; its id alone follows the write. */
const STARTED_PREFIX = "start ";
/** The tail a start line names for a shard that had no chained row yet. */
const NO_TAIL = "-";

/** The records an earlier run wrote back, and those it began without finishing. */
function replayJournal(dir: string): { done: Set<string>; started: Map<string, StartMark> } {
  let lines: string[] = [];
  try {
    lines = readFileSync(join(dir, ROLLBACK_JOURNAL), "utf8").split("\n").filter(Boolean);
  } catch {
    // no journal: a fresh run
  }
  const done = new Set(lines.filter((l) => !l.startsWith(STARTED_PREFIX)));
  const started = new Map<string, StartMark>();
  for (const line of lines) {
    if (!line.startsWith(STARTED_PREFIX)) continue;
    // `start <id> <tail hash, or - for an empty shard>`; an older line has no tail.
    const [id, tail] = line.slice(STARTED_PREFIX.length).split(" ");
    if (id === undefined || done.has(id)) continue;
    started.set(id, tail === undefined ? {} : { tail: tail === NO_TAIL ? null : tail });
  }
  return { done, started };
}

/** Replace `Brain/` (minus the snapshot folders) with the snapshot's tree. */
function restoreBrain(vault: string, runId: string, archiveCopy: string | null): number {
  const archive = snapshotPath(vault, runId);
  if (!existsSync(archive)) {
    if (archiveCopy === null)
      throw new RollbackRefusedError(`the migration snapshot ${runId} is gone`);
    mkdirSync(join(archive, ".."), { recursive: true });
    cpSync(archiveCopy, archive);
  }
  const extracted = extractSnapshotToTemp(vault, runId);
  try {
    const brain = join(vault, BRAIN_ROOT_REL);
    for (const name of readdirSync(brain)) {
      if (BRAIN_SNAPSHOT_EXCLUDED_ENTRIES.includes(name)) continue;
      rmSync(join(brain, name), { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
    }
    let files = 0;
    for (const name of readdirSync(extracted.brainRoot)) {
      if (BRAIN_SNAPSHOT_EXCLUDED_ENTRIES.includes(name)) continue;
      cpSync(join(extracted.brainRoot, name), join(brain, name), { recursive: true });
      files += 1;
    }
    return files;
  } finally {
    extracted.cleanup();
  }
}

/** What the restored tree already holds: item keys with checksums, and record contents. */
function restoredIdentity(vault: string): { items: Set<string>; contents: Map<string, number> } {
  const items = new Set<string>();
  const contents = new Map<string, number>();
  for (const entry of migrationCatalogue(vault)) {
    const destination = recordDestination(entry);
    if (destination === null) continue;
    const tally = emptyTally();
    for (const locator of entry.locators) {
      scanLocator(locator, tally, (item) => {
        items.add(`${itemKey(vault, item)}\u0000${itemSum(item)}`);
        for (const record of itemRecords(vault, destination, item)) {
          const key = contentKey(record.kind, record.body);
          contents.set(key, (contents.get(key) ?? 0) + 1);
        }
      });
    }
  }
  return { items, contents };
}

/**
 * Records absent from the restored tree, in fold order. A record is
 * present only as an occurrence of THIS vault (`journal-scope.ts`, the
 * rule the migration journal matches by): a `migrated` mark counts when
 * it names this vault and the tree holds its item with the same checksum;
 * a mark of another vault is that vault's own occurrence of an identical
 * item, and is written back beside this vault's. An unmarked copy that a
 * dual write stamped with another vault's marker is never matched by
 * content either. An unmarked copy that names no vault keeps the content
 * match: it may be this vault's own copy, and writing it back would
 * duplicate the row the restored tree already holds.
 */
function recordsToReplay(
  vault: string,
  scope: JournalScope,
  all: ReadonlyArray<StoreRecord>,
): StoreRecord[] {
  const { items, contents } = restoredIdentity(vault);
  const out: StoreRecord[] = [];
  for (const record of [...all].toSorted(compareRecords)) {
    const mark = migratedMark(record);
    if (mark !== null) {
      const own = sameJournalVault(markVault(scope, mark.vault, record), scope.vault);
      if (!own || !items.has(`${mark.key}\u0000${mark.sum}`)) out.push(record);
      continue;
    }
    if (copyNamesOtherVault(scope, record)) {
      out.push(record);
      continue;
    }
    const key = contentKey(record.kind, record.body);
    const left = contents.get(key) ?? 0;
    if (left > 0) contents.set(key, left - 1);
    else out.push(record);
  }
  return out;
}

/** The ledger each held `ledgers` record sits in (`ledgers/<name>/...`), by record id. */
function ledgerOfRecords(store: StoreHandle): Map<string, string> {
  const out = new Map<string, string>();
  for (const partition of store.partitions) {
    for (const shard of readPartition(partitionDir(store.root, partition), {
      onUnreadable: () => {},
    })) {
      if (shard.stream !== "ledgers") continue;
      const ledger = shard.rel.split("/")[1] ?? "unknown";
      for (const record of shard.all) out.set(record.id, ledger);
    }
  }
  return out;
}

/** Refuse while a held shard's records cannot all be seen, naming the shards. */
function refuseUnseen(unseen: UnseenShards, done: string): void {
  const named = describeUnseen(unseen);
  if (named === null) return;
  throw new RollbackRefusedError(
    `${named}; a record in one would never be written back, so ${done} and this machine ` +
      "stays switched. Let sync finish, fix their permissions or repair the shard, then run " +
      "the rollback again",
  );
}

/** Every held record, once every shard reads in full (see {@link refuseUnseen}). */
function completeRecords(store: StoreHandle, done: string): StoreRecord[] {
  const read = readHeldRecords(store);
  refuseUnseen(read.unseen, done);
  return read.records;
}

export interface RollbackOptions {
  readonly agent: string;
  readonly hooks?: RollbackHooks;
}

/**
 * Refuse a restore that would lose late legacy writes the import could not
 * take (see the module header); when it left unparseable items, copy the
 * tree aside first and return where.
 */
function guardLateImport(vault: string, dir: string, late: TransitionResult): string | null {
  if (!late.converged) {
    throw new RollbackRefusedError(
      `the legacy tree kept changing through ${late.passes} import passes; nothing was ` +
        "restored. Run the rollback again once the machines on the old release are quiet",
    );
  }
  if (late.held_back > 0) {
    throw new RollbackRefusedError(
      `${late.held_back} late legacy item(s) belong to a store partition this machine does ` +
        "not hold, and the restore would delete them; nothing was restored. Roll back on a " +
        "machine that holds every partition, or bring the missing partition here first",
    );
  }
  if (late.unparseable === 0) return null;
  const kept = join(dir, ROLLBACK_KEPT_DIR, new Date().toISOString().replace(/[:.]/g, "-"));
  cpSync(join(vault, BRAIN_ROOT_REL), kept, { recursive: true });
  return kept;
}

/** Roll this machine back to the legacy layout; see the module header. */
export function rollbackMigration(
  vault: string,
  store: StoreHandle,
  options: RollbackOptions,
): RollbackResult {
  const dir = migrationDir(store);
  const vaultId = readVaultIdentity(vault)?.vault_id ?? null;
  // Another device's removal counts too: its record may arrive before
  // sync deletes the tree here, and a tree rebuilt now would sync back to
  // every device while no switched device imports from it any more.
  const removedElsewhere = legacyTreeRemovedRecords(store).some(
    (r) => r.body["vault_id"] === vaultId,
  );
  const removing = readRemovalInProgress(store);
  if (
    readRemovalMarker(store, vault) !== null ||
    removedElsewhere ||
    (removing !== null && sameVaultPath(removing.vault, vault)) ||
    !existsSync(join(vault, BRAIN_ROOT_REL))
  ) {
    throw new RollbackRefusedError(
      "the legacy tree has left the vault; a rollback is only possible until then",
    );
  }
  const migration = readMigrationState(dir);
  const backup = readMigrationBackup(dir);
  if (migration === null || backup === null || backup.snapshot === null) {
    throw new RollbackRefusedError("this machine holds no migration backup to roll back to");
  }
  // The backup is device-wide but of one vault: a vault configured after
  // the switch was imported by the transition, which never changes its
  // legacy tree and takes no backup of it. Restoring another vault's
  // snapshot into it would replace its tree, so it is refused before
  // anything is touched.
  const mismatch = backupVaultMismatch(backup, vault);
  if (mismatch !== null) {
    throw new RollbackRefusedError(
      `${mismatch}; nothing was restored. A vault whose legacy data the transition imported ` +
        "keeps its legacy tree unchanged and has no backup of its own to roll back to; roll " +
        "back with the vault this machine migrated",
    );
  }
  // Only an unfinished rollback (its state file is still there) runs on a
  // device that is not switched: a finished one, run again, would restore
  // the old snapshot over everything written to the legacy tree since.
  if (readState(dir) === null && !deviceSwitchedHere(store, store.device)) {
    throw new RollbackRefusedError(
      migration.phase === "rolled-back"
        ? "this machine was already rolled back to the legacy layout"
        : "this machine has not switched to the brain store; there is nothing to roll back",
    );
  }
  // Every record of the store is written back or counted, so a shard
  // whose records this machine cannot all see refuses the rollback before
  // anything is touched: the switch would be cleared over a legacy tree
  // that lacks them, and nothing would write them back later.
  refuseUnseen(unseenHeldShards(store), "nothing was restored");
  const scope = journalScopeFor(vault, store.device, dir, vaultId);
  const gateRun = `rollback-${migration.run_id}`;
  holdGateFor(vault, gateRun);
  try {
    let state = readState(dir);
    let legacyTreeKept: string | null = null;
    let all: StoreRecord[] | null = null;
    if (state === null || !state.restored) {
      // Late legacy writes first, as the removal does (design D11a): what a
      // machine on the old release wrote into this tree since the last
      // transition import is in neither the snapshot nor the store yet, so
      // the restore below would wipe it. Imported now, the replay writes it
      // back.
      const late = importLateLegacyWrites(vault, store, options.agent, vaultId, {
        waitMs: GATED_IMPORT_WAIT_MS,
      });
      all = completeRecords(store, "nothing was restored");
      legacyTreeKept = guardLateImport(vault, dir, late);
      const restored_files = restoreBrain(vault, backup.snapshot, snapshotCopyIn(backup));
      const restored_backups = restoreMigrationBackups(vault, backup);
      state = { restored: true, restored_files, restored_backups };
      mkdirSync(dir, { recursive: true });
      writeFileSync(join(dir, ROLLBACK_STATE), JSON.stringify(state));
    }

    // A resumed rollback reads them now; the tree it restored waits.
    all ??= completeRecords(store, "the restored tree waits for a resumed rollback");
    const absent = recordsToReplay(vault, scope, all);
    const replayed: string[] = [];
    const refused = exportRecords(
      vault,
      store.device,
      { records: absent.filter((r) => EXPORTED_KINDS.has(r.kind)), all },
      {
        ...replayJournal(dir),
        onStart: (record, tail) => {
          appendFileSync(
            join(dir, ROLLBACK_JOURNAL),
            `${STARTED_PREFIX}${record.id} ${tail ?? NO_TAIL}\n`,
          );
        },
        onRecord: (record) => {
          appendFileSync(join(dir, ROLLBACK_JOURNAL), `${record.id}\n`);
          replayed.push(record.id);
          options.hooks?.afterReplayed?.(replayed.length);
        },
      },
    );

    // Absent from the restored tree with no exporter: they stay in the store.
    const noLegacy: Record<string, number> = {};
    const ledgerKept: Record<string, number> = {};
    const ledgers = ledgerOfRecords(store);
    for (const record of absent) {
      if (EXPORTED_KINDS.has(record.kind)) continue;
      noLegacy[record.kind] = (noLegacy[record.kind] ?? 0) + 1;
      if (record.kind === LEDGER_ROW_KIND) {
        const ledger = ledgers.get(record.id) ?? "unknown";
        ledgerKept[ledger] = (ledgerKept[ledger] ?? 0) + 1;
      }
    }

    let unswitched = "";
    if (deviceSwitchedHere(store, store.device)) {
      unswitched = appendRecord(store, {
        partition: "shared",
        stream: MIGRATION_STREAM,
        kind: DEVICE_UNSWITCHED_KIND,
        agent: options.agent,
        body: { [AUTHORITY_FIELD]: "human", device: store.device, run_id: migration.run_id },
      }).record.id;
    }
    clearSwitchMarker(store.root, store.device);
    unbindVaultFromStore(store.root);
    const tokensAside = removeDeviceTokens(dir, vault);
    writeMigrationState(dir, {
      ...migration,
      phase: "rolled-back",
      updated_at: new Date().toISOString(),
    });
    rmSync(join(dir, ROLLBACK_STATE), { force: true });
    rmSync(join(dir, ROLLBACK_JOURNAL), { force: true });
    return {
      device: store.device,
      restored_files: state.restored_files,
      restored_backups: state.restored_backups,
      replayed,
      no_legacy_form: noLegacy,
      ledger_rows_kept: ledgerKept,
      refused,
      unswitched,
      device_tokens_aside: tokensAside,
      legacy_tree_kept: legacyTreeKept,
    };
  } finally {
    releaseGateFor(vault, gateRun);
  }
}