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
14.7 KB
Raw Blame
/**
 * The vault binding of a store-only vault (design D14 items 8 and 13,
 * task 2.10).
 *
 * A legacy vault carries its identity marker inside the tree it guards
 * (`Brain/vault-id.json`, `../brain/vault-identity.ts`), and keeps it until
 * the legacy tree is removed (D11a). A store-only vault has no machine
 * file at all, so its identity is kept beside the store's own binding, in
 * the device-local state (never synced): for each store root, the vault's
 * real path and the identity of its root directory (device and inode on
 * POSIX, volume serial and file id on Windows, as `fs.statSync` reports
 * them).
 *
 * `o2b init --vault` binds, and the store migration binds when it
 * switches a machine (it calls {@link bindVaultToStore} with its store).
 * The note tools' write guard (`./index.ts`) compares the vault they were
 * handed against the binding and refuses a vault that is not the bound
 * one:
 *
 *  - the same directory (same identity) is the bound vault, even at
 *    another path (the vault was moved or is mounted elsewhere);
 *  - another directory at the bound path is a vault replaced under the
 *    binding (a restore, a sync tool recreating the folder);
 *  - another directory at another path is another vault.
 *
 * When the identity is unknown on either side (a file system that reports
 * no inode), the real paths decide. A vault never bound passes: binding is
 * what init and the migration add, and an older install has none yet.
 * Running `o2b init --vault <path>` again is the remedy a refusal names.
 */

import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync } from "node:fs";
import { dirname, join, resolve } from "node:path";

import { readDeviceId } from "../config.ts";
import { atomicWriteFileSync, sleepSync } from "../fs-atomic.ts";
import { processDirsEnv } from "../platform-dirs.ts";
import { withLocalLock } from "../store/local-lock.ts";
import { inspectStore } from "../store/store-open.ts";
import { resolveConfiguredStoreRoot, storesStateDir } from "../store/store-paths.ts";

/** Device-local file holding the vault bindings, beside the store bindings. */
export const VAULT_BINDING_FILE = "vault-binding.json";

/** One binding: the vault a store root is used with on this machine. */
export interface VaultBinding {
  readonly root: string;
  readonly store_id: string;
  readonly device: string;
  /** The vault's real path when it was bound. */
  readonly vault: string;
  /** Device (volume) of the vault's root directory, or null when unknown. */
  readonly dev: string | null;
  /** Inode (file id) of the vault's root directory, or null when unknown. */
  readonly ino: string | null;
  readonly bound_at: string;
}

/** Whether the vault is the bound one. */
export type VaultBindingStatus =
  | { readonly state: "unbound" }
  /** The binding file exists but cannot be read: nothing can be checked. */
  | { readonly state: "unreadable"; readonly path: string }
  | { readonly state: "match"; readonly binding: VaultBinding }
  | {
      readonly state: "mismatch";
      readonly binding: VaultBinding;
      /** What differs, with both paths (for a local reader). */
      readonly detail: string;
      /** What differs, naming no path. */
      readonly reason: string;
    };

/** The refusal code of a note write to a vault that is not the bound one. */
export const VAULT_BINDING_MISMATCH_CODE = "vault_binding_mismatch";

/** Why a vault that is not the bound one is refused, naming no path. */
const OTHER_VAULT_REASON = "the vault is not the vault bound to the brain store";

/**
 * A note write refused because the vault is not the one bound to the
 * store. The message names the vault handed in (the caller's own vault,
 * which every reach redacts) and never the bound one: that is another
 * vault's device path, which no redaction knows. `detail` keeps both for
 * a local reader.
 */
export class VaultBindingMismatchError extends Error {
  readonly code = VAULT_BINDING_MISMATCH_CODE;
  constructor(
    readonly vault: string,
    readonly detail: string,
    reason: string = OTHER_VAULT_REASON,
  ) {
    super(
      `refusing to write: ${reason}. If this is the vault you mean to use, run ` +
        `\`o2b init --vault ${vault}\` to bind it.`,
    );
    this.name = "VaultBindingMismatchError";
  }
}

export interface VaultBindingOptions {
  /** The machine config the store root and the device id come from. */
  readonly configPath?: string;
}

/** The binding file of this machine. */
export function vaultBindingPath(): string {
  return join(storesStateDir(processDirsEnv()), VAULT_BINDING_FILE);
}

interface DirIdentity {
  readonly path: string;
  readonly dev: string | null;
  readonly ino: string | null;
}

function realPathOf(vault: string): string {
  try {
    return realpathSync(vault);
  } catch {
    return resolve(vault);
  }
}

/** The vault's real path and root directory identity. */
function identityOf(vault: string): DirIdentity {
  const path = realPathOf(vault);
  try {
    const stat = statSync(path, { bigint: true });
    if (stat.ino === 0n) return { path, dev: null, ino: null };
    return { path, dev: stat.dev.toString(), ino: stat.ino.toString() };
  } catch {
    return { path, dev: null, ino: null };
  }
}

function samePath(a: string, b: string): boolean {
  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
}

function nullableString(x: unknown): boolean {
  return x === null || typeof x === "string";
}

function isBinding(value: unknown): value is VaultBinding {
  if (typeof value !== "object" || value === null) return false;
  const v = value as Record<string, unknown>;
  return (
    typeof v["root"] === "string" &&
    typeof v["store_id"] === "string" &&
    typeof v["device"] === "string" &&
    typeof v["vault"] === "string" &&
    nullableString(v["dev"]) &&
    nullableString(v["ino"]) &&
    typeof v["bound_at"] === "string"
  );
}

/**
 * The binding file exists but cannot be read or parsed. It shares the
 * mismatch's wire code on purpose: either way the vault cannot be shown
 * to be the bound one, and `o2b init --vault <path>` is the remedy of
 * both (it rebinds the vault, and moves a damaged file aside); the
 * message tells the two apart.
 */
export class VaultBindingsUnreadableError extends Error {
  readonly code = VAULT_BINDING_MISMATCH_CODE;
  /**
   * `damaged`: the file was read and is not a binding file (the bind
   * moves it aside); `io`: it could not be read at all (a lock, a denied
   * permission), so it is left as it is.
   */
  constructor(
    readonly path: string,
    readonly failure: "damaged" | "io" = "damaged",
  ) {
    super(
      failure === "io"
        ? "refusing to write: this machine's vault binding file cannot be read right now, so " +
            "the vault cannot be checked against the one bound to the brain store. Check the " +
            "file's permissions, or try again once no other program holds it."
        : "refusing to write: this machine's vault binding file cannot be read, so the vault " +
            "cannot be checked against the one bound to the brain store. Run `o2b init --vault " +
            "<path>` to bind the vault again (the unreadable file is kept beside the new one).",
    );
    this.name = "VaultBindingsUnreadableError";
  }
}

/** Attempts and pause of a binding file read that hits an I/O error (a short sharing lock). */
const READ_ATTEMPTS = 3;
const READ_RETRY_MS = 25;

/**
 * The bindings on file. An absent file holds none; a file that exists but
 * cannot be read or parsed is a {@link VaultBindingsUnreadableError}, so a
 * damaged file neither reads as "no vault bound" (the note guard would
 * pass any vault) nor is overwritten with the bindings of other stores
 * lost.
 */
export function readVaultBindings(path: string = vaultBindingPath()): VaultBinding[] {
  let text: string | null = null;
  for (let attempt = 0; attempt < READ_ATTEMPTS && text === null; attempt++) {
    if (attempt > 0) sleepSync(READ_RETRY_MS);
    try {
      text = readFileSync(path, "utf8");
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
    }
  }
  if (text === null) throw new VaultBindingsUnreadableError(path, "io");
  let parsed: unknown;
  try {
    parsed = JSON.parse(text);
  } catch {
    throw new VaultBindingsUnreadableError(path);
  }
  const bindings = (parsed as { bindings?: unknown } | null)?.bindings;
  if (!Array.isArray(bindings)) throw new VaultBindingsUnreadableError(path);
  return bindings.filter(isBinding);
}

/**
 * The bindings an explicit bind keeps: the file's, or none once a damaged
 * file is moved aside (`<file>.unreadable-<time>`), so the bind repairs
 * the file and the damaged one is kept for a look. A file that cannot be
 * read at all is not moved (it may be whole, behind a short lock): the
 * refusal is rethrown.
 */
function bindingsToKeep(path: string): VaultBinding[] {
  try {
    return readVaultBindings(path);
  } catch (err) {
    if (!(err instanceof VaultBindingsUnreadableError) || err.failure === "io") throw err;
    renameSync(path, `${path}.unreadable-${Date.now()}`);
    return [];
  }
}

/**
 * Whether two store roots name the same store: the same store id when
 * both stores can be inspected, else the same real path (case folded on
 * Windows). A store recreated at the same root has a new id, so the
 * binding of the old one no longer applies.
 */
function sameStore(binding: VaultBinding, root: string, storeId: string | null): boolean {
  if (storeId !== null) return binding.store_id === storeId;
  return samePath(realPathOf(binding.root), realPathOf(root));
}

function storeIdAt(root: string): string | null {
  try {
    return inspectStore(root)?.storeId ?? null;
  } catch {
    return null;
  }
}

/**
 * The store a binding is for: an explicit one, or the configured store. A
 * store handle (`StoreHandle`, as the migration holds it) also names the
 * device that binds.
 */
export interface VaultBindingStore {
  readonly root: string;
  readonly storeId: string;
  readonly device?: string;
}

/**
 * Bind `vault` to the store on this machine, replacing any earlier binding
 * of that store root. The store is `store` when given, else the configured
 * one. Returns `null`, binding nothing, when there is no store or this
 * machine has no device id: the binding is device-local state, and a
 * machine without a device id keeps none (it cannot write store records
 * either).
 *
 * The store migration's integration point: once it has switched this
 * machine it calls `bindVaultToStore(vault, { store })` with its own
 * store handle, so the vault it migrated is the bound one.
 */
export function bindVaultToStore(
  vault: string,
  options: VaultBindingOptions & { readonly store?: VaultBindingStore } = {},
): VaultBinding | null {
  const device = options.store?.device ?? readDeviceId(options.configPath ?? null);
  if (device === null || device === "") return null;
  let store: VaultBindingStore | null = options.store ?? null;
  if (store === null) {
    const root = resolveConfiguredStoreRoot(options.configPath).root;
    const found = inspectStore(root);
    if (found === null) return null;
    store = { root, storeId: found.storeId };
  }
  const identity = identityOf(vault);
  const binding: VaultBinding = {
    root: store.root,
    store_id: store.storeId,
    device,
    vault: identity.path,
    dev: identity.dev,
    ino: identity.ino,
    bound_at: new Date().toISOString(),
  };
  const path = vaultBindingPath();
  mkdirSync(dirname(path), { recursive: true });
  withLocalLock(path, () => {
    const kept = bindingsToKeep(path).filter((b) => !sameStore(b, store.root, store.storeId));
    const bindings = [...kept, binding];
    atomicWriteFileSync(path, `${JSON.stringify({ bindings }, null, 2)}\n`);
  });
  return binding;
}

/**
 * Drop the binding of the store root `root` on this machine: a rollback
 * took the vault back to the legacy layout, where its identity marker
 * guards it again. A root never bound is a no-op. A file that cannot be
 * read is left as it is: it keeps refusing note writes until an explicit
 * bind repairs it, and the other stores' bindings it may hold are not
 * dropped with it.
 */
export function unbindVaultFromStore(root: string): void {
  const path = vaultBindingPath();
  if (!existsSync(path)) return;
  const storeId = storeIdAt(root);
  withLocalLock(path, () => {
    let known: VaultBinding[];
    try {
      known = readVaultBindings(path);
    } catch (err) {
      if (err instanceof VaultBindingsUnreadableError) return;
      throw err;
    }
    const bindings = known.filter((b) => !sameStore(b, root, storeId));
    if (bindings.length === known.length) return;
    atomicWriteFileSync(path, `${JSON.stringify({ bindings }, null, 2)}\n`);
  });
}

/** Whether `vault` is the vault bound to the configured store on this machine. */
export function vaultBindingStatus(
  vault: string,
  options: VaultBindingOptions = {},
): VaultBindingStatus {
  let root: string;
  try {
    root = resolveConfiguredStoreRoot(options.configPath).root;
  } catch {
    return { state: "unbound" };
  }
  const storeId = storeIdAt(root);
  let bindings: VaultBinding[];
  try {
    bindings = readVaultBindings();
  } catch (err) {
    if (err instanceof VaultBindingsUnreadableError) return { state: "unreadable", path: err.path };
    throw err;
  }
  const binding = bindings.find((b) => sameStore(b, root, storeId));
  if (binding === undefined) return { state: "unbound" };
  const current = identityOf(vault);
  const known = binding.ino !== null && current.ino !== null;
  if (known && binding.dev === current.dev && binding.ino === current.ino) {
    return { state: "match", binding };
  }
  const atBoundPath = samePath(binding.vault, current.path);
  if (!known) {
    return atBoundPath
      ? { state: "match", binding }
      : {
          state: "mismatch",
          binding,
          detail: `the vault ${current.path} is not the vault ${binding.vault} bound to the brain store`,
          reason: OTHER_VAULT_REASON,
        };
  }
  return {
    state: "mismatch",
    binding,
    detail: atBoundPath
      ? `the vault directory at ${current.path} was replaced since it was bound to the brain store`
      : `the vault ${current.path} is not the vault ${binding.vault} bound to the brain store`,
    reason: atBoundPath
      ? "the vault directory was replaced since it was bound to the brain store"
      : OTHER_VAULT_REASON,
  };
}

/** Refuse a note write to a vault that is not the one bound to the store. */
export function assertVaultBindingForWrite(vault: string, options: VaultBindingOptions = {}): void {
  const status = vaultBindingStatus(vault, options);
  if (status.state === "unreadable") throw new VaultBindingsUnreadableError(status.path);
  if (status.state === "mismatch") {
    throw new VaultBindingMismatchError(vault, status.detail, status.reason);
  }
}