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
8.0 KB
Raw Blame
/**
 * The one entry point of `o2b brain migrate-store` without `--dry-run`:
 * it picks what this machine has to do (tasks 2.3 and 2.4).
 *
 *  - `transition`: this device already switched. It imports the late
 *    writes machines still on an old release left in the legacy tree, and
 *    names those machines (`transition.ts`). A vault configured after the
 *    switch also brings its operator settings, and is bound to the store
 *    once nothing of it was left behind.
 *  - `first` / `later`: the migration (`migrate.ts`); a later machine
 *    first waits for the first machine's cut.
 *  - `waiting`: a later machine whose store does not hold that cut yet.
 *    Nothing was written; the report names what it waits for.
 *
 * {@link removeLegacy} and {@link rollback} are the `--remove-legacy` and
 * `--rollback` forms (tasks 2.5 and 2.6).
 */

import { deviceSwitchedHere } from "../store/store-only.ts";
import { legacyPermissionsConflict } from "../brain/doctor/permissions-check.ts";
import { storedPermissionsText } from "../brain/permissions/document-source.ts";
import { readVaultIdentity } from "../brain/vault-identity.ts";
import { bindVaultToStore, vaultBindingStatus } from "../vault-adapter/vault-binding.ts";
import { importBrainSettings, type BrainSettingsImport } from "./brain-settings.ts";
import { unseenHeldShards } from "./journal.ts";
import { writeDeviceSettings, type DeviceConfigWrite } from "./device-config.ts";
import type { CutWait } from "./later.ts";
import {
  finishInterruptedSwitch,
  MigrationWaitingError,
  openMigrationStore,
  runMigration,
  safeAgent,
  type MigrationOptions,
  type MigrationResult,
} from "./migrate.ts";
import { removeLegacyTree, type RemovalResult } from "./removal.ts";
import { rollbackMigration, type RollbackHooks, type RollbackResult } from "./rollback.ts";
import { importLateLegacyWrites, type TransitionResult } from "./transition.ts";

/**
 * What the transition did with a vault configured after this machine
 * switched (not the bound one): its operator settings, and whether its
 * deny rules conflict with the stored permissions document.
 */
export interface TransitionSettings {
  /** `_brain.yaml` and `_permissions.yaml` imported (null for the bound vault). */
  readonly settings: BrainSettingsImport | null;
  readonly device_config: DeviceConfigWrite | null;
  /**
   * The vault's `_permissions.yaml` holds deny rules the stored document
   * does not: the store's document stays, and the vault is not bound.
   */
  readonly permissions_conflict: boolean;
  /** Whether the vault is the one bound to the store after this run. */
  readonly bound: boolean;
  /**
   * Held store shards whose records this machine could not all see
   * (`<partition>/<rel>`): a record of the vault's items may be in one,
   * so the vault is not bound while any is listed.
   */
  readonly unseen_shards: ReadonlyArray<string>;
}

export type MigrateStoreOutcome =
  | ({ readonly mode: "migration" } & MigrationResult)
  | ({
      readonly mode: "transition";
      readonly ok: boolean;
      readonly device: string;
    } & TransitionResult &
      TransitionSettings)
  | {
      readonly mode: "waiting";
      readonly ok: false;
      readonly device: string;
      readonly wait: CutWait;
    };

export function migrateStore(vault: string, options: MigrationOptions = {}): MigrateStoreOutcome {
  const store = openMigrationStore(vault, options.configPath);
  if (deviceSwitchedHere(store, store.device)) {
    const agent = options.agent ?? safeAgent(options.configPath);
    // A run killed after its switch record still has to bind the vault it
    // migrated, claim the view writer and open the gate. Another vault
    // configured since is not bound by it: it takes the checks below.
    finishInterruptedSwitch(vault, store, agent);
    const bindingOptions =
      options.configPath !== undefined ? { configPath: options.configPath } : {};
    const alreadyBound = vaultBindingStatus(vault, bindingOptions).state === "match";
    // A vault configured after this machine switched brings its operator
    // settings, as a migration does (design D14 item 3): `_brain.yaml` and
    // `_permissions.yaml` at human authority (the operator runs this
    // command), never over a value the store already holds. The settings
    // go in first, so a deny rule is in force before any record of the
    // vault is. The bound vault's settings were imported by its migration;
    // its files went stale at the switch and are not read again.
    let settings: BrainSettingsImport | null = null;
    let deviceConfig: DeviceConfigWrite | null = null;
    let permissionsConflict = false;
    if (!alreadyBound) {
      settings = importBrainSettings(vault, store, agent);
      deviceConfig = writeDeviceSettings(settings.device, options.configPath);
      // Deny rules the stored document does not hold: two operator
      // policies are not merged by guesswork; the vault stays unbound
      // (its migration offered) and doctor names the file
      // (`permissions-legacy-only`) until the operator reconciles them.
      permissionsConflict = legacyPermissionsConflict(
        vault,
        storedPermissionsText(options.configPath),
      );
    }
    const vaultId = readVaultIdentity(vault)?.vault_id ?? null;
    // The import records the automatic import's watermark at its final
    // pass, so that import starts from a point whose content is in the
    // store (`transition-watermark.ts`).
    const result = importLateLegacyWrites(vault, store, agent, vaultId, {
      recordWatermark: true,
      ...(options.hooks !== undefined ? { hooks: options.hooks } : {}),
    });
    // Everything of the vault is in the store only when the import settled
    // and held nothing back for a partition this machine lacks, as the
    // migration's verification demands. Only then does a vault configured
    // after the switch become the bound one (its migration no longer
    // offered); a held-back item keeps it offered, and the next run
    // imports the item once the partition is here.
    // The journal may count an item as imported whose record sits in a
    // shard this machine cannot see: the binding waits until every held
    // shard reads in full, as the removal and the rollback do.
    const unseen = unseenHeldShards(store);
    const unseenShards = [...unseen.unreadable, ...unseen.partial].toSorted();
    const complete = result.converged && result.held_back === 0 && unseenShards.length === 0;
    let bound = alreadyBound;
    if (!alreadyBound && complete && !permissionsConflict) {
      bindVaultToStore(vault, { store });
      bound = true;
    }
    return {
      mode: "transition",
      ok: complete && !permissionsConflict,
      device: store.device,
      ...result,
      settings,
      device_config: deviceConfig,
      permissions_conflict: permissionsConflict,
      bound,
      unseen_shards: unseenShards,
    };
  }
  try {
    return { mode: "migration", ...runMigration(vault, options) };
  } catch (error) {
    if (error instanceof MigrationWaitingError) {
      return { mode: "waiting", ok: false, device: store.device, wait: error.wait };
    }
    throw error;
  }
}

/** `--remove-legacy [--force]`: move the legacy tree out of the vault when the cohort allows. */
export function removeLegacy(
  vault: string,
  options: { readonly configPath?: string; readonly agent?: string; readonly force?: boolean } = {},
): RemovalResult {
  const store = openMigrationStore(vault, options.configPath);
  const agent = options.agent ?? safeAgent(options.configPath);
  return removeLegacyTree(vault, store, { agent, ...(options.force ? { force: true } : {}) });
}

/** `--rollback`: take this machine back to the legacy layout. */
export function rollback(
  vault: string,
  options: {
    readonly configPath?: string;
    readonly agent?: string;
    readonly hooks?: RollbackHooks;
  } = {},
): RollbackResult {
  const store = openMigrationStore(vault, options.configPath);
  const agent = options.agent ?? safeAgent(options.configPath);
  return rollbackMigration(vault, store, {
    agent,
    ...(options.hooks ? { hooks: options.hooks } : {}),
  });
}