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
16.6 KB
Raw Blame
/**
 * Unit J - vault identity marker, read, write, and comparison.
 *
 * `resolveVault` has five branches and four of them return a path with
 * ZERO existence validation: the `VAULT_DIR` env var, the active
 * profile, and the config `vault:` key are taken at face value, and the
 * pointer branch stats but fails soft. Every Brain write then funnels
 * through `brainDirs` - a containment check only - into `withTempFile`,
 * which calls `mkdirSync(dir, {recursive: true})`. The consequence is
 * that the FIRST WRITE materializes a mis-resolved root: a typo in
 * `VAULT_DIR` does not fail, it creates a second, empty memory store
 * that looks exactly like a vault where nothing has been recorded yet.
 *
 * This module supplies the identity that makes such a root nameable.
 *
 * Scope after the store (design D14 item 13, task 2.10): this guard covers
 * vault writes. A store-only write is guarded by the store identity check
 * (`../store/store-identity.ts`, run by `storeWrite`), and the note tools
 * reach this guard through the vault adapter (`assertNoteVaultForWrite`
 * in `../vault-adapter/`), which also refuses when there is no vault.
 *
 * ## Absent WARNS, present-and-different REFUSES
 *
 * The two conditions are not symmetric and must not be treated alike.
 *
 *   - An ABSENT marker is ambiguous by construction. A fresh directory,
 *     a vault predating markers, and a completely wrong root all look
 *     identical, and refusing would break `o2b brain init` on the very
 *     path it exists to serve. So absence is reported as a
 *     `vault-marker-absent` notice and the write proceeds.
 *   - A marker that is PRESENT and does not match what this process has
 *     already been writing to is unambiguous: the store under this path
 *     is not the store the process started with. That refuses.
 *
 * Because the condition is binary, no gate mode is involved. Units whose
 * condition is genuinely environment-dependent (the embedding ABI, the
 * owner-scope delivery filter) carry modes; this one does not.
 *
 * ## The marker carries NO absolute path
 *
 * A vault is Syncthing-shared across devices, so any machine-local
 * absolute path stored inside it is stale on every peer. A marker
 * recording where it was written would therefore refuse every write on
 * the second device - the exact class of defect this repository already
 * names for index keys. The marker records only an opaque random id, so
 * it is identical on every peer and survives a `mv` of the vault.
 *
 * The comparison is consequently against the identity THIS PROCESS
 * pinned on its first write, not against an external expectation.
 *
 * ## Exactly what the guard can and cannot catch
 *
 * Stated precisely, because the previous wording implied more.
 *
 * The ONLY condition that raises {@link VaultIdentityMismatchError} is:
 * a root this process has already written to, whose marker is present
 * and now holds a DIFFERENT id than the one pinned on that first write.
 * That is the store changing underneath a live process - a profile
 * switch, a remount, a restored backup of a different vault.
 *
 * Everything else passes, by construction and not by oversight:
 *
 *   - A COLD-START MIS-RESOLUTION passes. A typo in `VAULT_DIR` yields a
 *     root with no marker, the first write pins nothing, and the write
 *     proceeds. Nothing durable records which vault the process meant,
 *     so there is no expectation to compare against; inventing one from
 *     a machine-local path would refuse every write on a synced peer.
 *     What this case gets instead is a `vault-marker-absent` notice -
 *     see {@link vaultMarkerAbsentNotice}, which the runtime-notice
 *     channel reports on any Brain tree lacking a marker.
 *   - A DELETED marker passes. Absence is indistinguishable from a fresh
 *     vault and refusing would break `o2b brain init`.
 *   - A CORRUPT marker passes, as absence, for the same reason.
 *   - TWO DISTINCT VAULTS in one process both pass. Pins are keyed by
 *     resolved root, deliberately: a CLI or MCP server legitimately
 *     serves more than one vault.
 *
 * The mechanism is therefore a same-path, same-process consistency
 * check plus a standing report on unmarked roots. It is not, and does
 * not claim to be, proof that the resolved root is the intended one.
 */

import { randomBytes } from "node:crypto";
import { existsSync, readFileSync, statSync } from "node:fs";
import { join, resolve } from "node:path";

import { atomicWriteFileSync } from "../fs-atomic.ts";
import { ensureInsideVault } from "../path-safety.ts";
import {
  DEGRADATION_CODE,
  degradationNotice,
  emitDegradationNotice,
  formatDegradationNotice,
  type DegradationNotice,
} from "../integrity/degradation.ts";
import { compareStamps, formatStampMismatch, type StampMismatch } from "../integrity/stamp.ts";
import { assertVaultNotFrozen, WRITE_LANE, type WriteLane } from "./freeze-marker.ts";
import { assertNoMigrationInProgress } from "../migration-gate.ts";
import { BRAIN_ROOT_REL } from "./path-constants.ts";

/** Marker schema version. Bumped only on an incompatible field change. */
export const VAULT_IDENTITY_SCHEMA_VERSION = 1;

/** Marker filename inside `Brain/`. */
export const VAULT_IDENTITY_FILE = "vault-id.json";

/** Site name carried by every notice this module emits. */
const SITE = "vault-identity";

/** Stamp field name shared by the notice and the mismatch record. */
const VAULT_ID_FIELD = "vault_id";

/** Bytes of entropy behind a vault id (rendered as 32 hex characters). */
const VAULT_ID_BYTES = 16;

/**
 * A vault's durable identity. Deliberately minimal: an opaque id and
 * when it was minted. Nothing here is machine-local, so the record is
 * byte-identical on every synced peer.
 */
export interface VaultIdentity {
  readonly schema_version: number;
  readonly vault_id: string;
  readonly created_at: string;
}

/** Path of the identity marker: `<vault>/Brain/vault-id.json`. */
export function vaultIdentityPath(vault: string): string {
  return ensureInsideVault(join(vault, BRAIN_ROOT_REL, VAULT_IDENTITY_FILE), vault);
}

/**
 * Read the marker, or `null` when there is none.
 *
 * An unreadable or malformed marker also reads as `null` - that is, as
 * ABSENT rather than as a mismatch. Treating corruption as a mismatch
 * would refuse writes on a truncated sync, which is the failure mode a
 * warn-on-absence design exists to avoid.
 */
export function readVaultIdentity(vault: string): VaultIdentity | null {
  const path = vaultIdentityPath(vault);
  if (!existsSync(path)) return null;
  try {
    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<VaultIdentity>;
    if (typeof parsed.vault_id !== "string" || parsed.vault_id.length === 0) return null;
    return Object.freeze({
      schema_version:
        typeof parsed.schema_version === "number"
          ? parsed.schema_version
          : VAULT_IDENTITY_SCHEMA_VERSION,
      vault_id: parsed.vault_id,
      created_at: typeof parsed.created_at === "string" ? parsed.created_at : "",
    });
  } catch {
    return null;
  }
}

export interface WriteVaultIdentityOptions {
  /** Clock for `created_at`; injected so a test can pin the stamp. */
  readonly now?: Date;
}

/**
 * Stamp the marker, or return the one already there.
 *
 * IDEMPOTENT BY CONTRACT. Re-running the bootstrap path must never mint
 * a new id: the id is what makes a synced peer's vault recognisable as
 * the same store, and rotating it on every `o2b brain init` would make
 * the identity meaningless.
 */
export function writeVaultIdentity(
  vault: string,
  opts: WriteVaultIdentityOptions = {},
): VaultIdentity {
  const existing = readVaultIdentity(vault);
  if (existing !== null) return existing;
  const identity: VaultIdentity = Object.freeze({
    schema_version: VAULT_IDENTITY_SCHEMA_VERSION,
    vault_id: randomBytes(VAULT_ID_BYTES).toString("hex"),
    created_at: (opts.now ?? new Date()).toISOString(),
  });
  atomicWriteFileSync(vaultIdentityPath(vault), `${JSON.stringify(identity, null, 2)}\n`);
  return identity;
}

/**
 * A write was attempted against a root whose recorded identity is not
 * the one this process has been writing to. Carries the structured
 * notice and the stamp mismatch behind the message so a caller can
 * report the evidence rather than re-parse the string.
 */
export class VaultIdentityMismatchError extends Error {
  readonly notice: DegradationNotice;
  readonly mismatch: StampMismatch;

  constructor(notice: DegradationNotice, mismatch: StampMismatch) {
    super(formatDegradationNotice(notice));
    this.name = "VaultIdentityMismatchError";
    this.notice = notice;
    this.mismatch = mismatch;
  }
}

/**
 * Identity this process pinned per resolved root, on its first write.
 *
 * Module state is the right scope: the question the guard answers is
 * "is this still the store I have been writing to?", which is a
 * property of the running process and of nothing durable. Keying by the
 * resolved path keeps two roots in one process independent.
 */
const PINNED_IDENTITIES = new Map<string, string>();

/**
 * Inode identity of the marker file the last assertion parsed, per
 * resolved root.
 *
 * The guard sits on EVERY write, including append-heavy telemetry loops
 * that record tens of thousands of rows in one run, so the per-call cost
 * has to be one syscall rather than an open-read-parse. `writeVaultIdentity`
 * goes through `atomicWriteFileSync` - a temp file plus a rename - so a
 * replaced marker always arrives with a new inode. Matching on
 * (inode, size, mtime) therefore proves the bytes are the ones already
 * parsed; anything else falls through to a full re-read.
 */
interface MarkerStamp {
  readonly ino: number;
  readonly size: number;
  readonly mtimeMs: number;
  readonly vaultId: string;
}
const MARKER_STAMPS = new Map<string, MarkerStamp>();

/** Resolved marker path per root; see {@link currentVaultId}. */
const MARKER_PATHS = new Map<string, string>();

/**
 * Drop every pin. Exported for tests, which run many vaults in one
 * process; production code has no reason to call it.
 */
export function resetVaultIdentityPins(): void {
  PINNED_IDENTITIES.clear();
  MARKER_STAMPS.clear();
  MARKER_PATHS.clear();
}

/**
 * The marker's `vault_id`, re-read only when the file on disk is not
 * byte-for-byte the one the last call parsed. `null` for absent,
 * unreadable, or malformed - the same collapse {@link readVaultIdentity}
 * performs, for the same reason.
 */
function currentVaultId(root: string): string | null {
  // `vaultIdentityPath` runs the full containment check (lexical plus a
  // realpath walk of the deepest existing ancestor). That is the right
  // price once per root and the wrong price once per appended row, so
  // the resolved path is memoized alongside the marker stamp.
  let path = MARKER_PATHS.get(root);
  if (path === undefined) {
    path = vaultIdentityPath(root);
    MARKER_PATHS.set(root, path);
  }
  // `throwIfNoEntry: false` matters for cost, not for semantics. An
  // ABSENT marker is the steady state of every unmarked root, and this
  // function runs once per written row - so the throwing form built and
  // discarded one Error, with its stack, per append. Measured over 20k
  // guarded writes (median of 5): 159ms -> 76ms on an unmarked root,
  // unchanged on a marked one, where the stat simply succeeds and
  // nothing ever threw.
  //
  // The `catch` stays. The option suppresses ENOENT only, and every
  // other stat failure (EACCES, ELOOP) must still collapse to "absent"
  // exactly as before, rather than propagate out of a write guard.
  let stat;
  try {
    stat = statSync(path, { throwIfNoEntry: false });
  } catch {
    stat = undefined;
  }
  if (stat === undefined) {
    MARKER_STAMPS.delete(root);
    return null;
  }
  const cached = MARKER_STAMPS.get(root);
  if (
    cached !== undefined &&
    cached.ino === stat.ino &&
    cached.size === stat.size &&
    cached.mtimeMs === stat.mtimeMs
  ) {
    return cached.vaultId;
  }
  const identity = readVaultIdentity(root);
  if (identity === null) {
    MARKER_STAMPS.delete(root);
    return null;
  }
  MARKER_STAMPS.set(root, {
    ino: stat.ino,
    size: stat.size,
    mtimeMs: stat.mtimeMs,
    vaultId: identity.vault_id,
  });
  return identity.vault_id;
}

/**
 * The `vault-marker-absent` notice for `vault`, or `null` when the
 * resolved root carries a readable marker.
 *
 * This is the READ-SIDE half of the unit, and the only place the absent
 * branch is described. Two callers exist and they need the same record
 * for different reasons: {@link assertVaultIdentityForWrite} emits it
 * into a write-path sink, and the diagnostic surfaces report it as a
 * standing condition of the root.
 *
 * A corrupt or unparseable marker reads as ABSENT here, exactly as it
 * does in {@link readVaultIdentity}: the two cannot be distinguished
 * without guessing, and guessing wrong turns a truncated sync into a
 * refusal.
 */
export function vaultMarkerAbsentNotice(vault: string): DegradationNotice | null {
  const root = resolve(vault);
  if (currentVaultId(root) !== null) return null;
  return degradationNotice({
    code: DEGRADATION_CODE.vaultMarkerAbsent,
    site: SITE,
    path: root,
    detail:
      "resolved vault root carries no identity marker; " +
      "run `o2b brain init` on this root if it is the intended vault",
  });
}

/**
 * Assert that a write may proceed against `vault`.
 *
 * Emits a `vault-marker-absent` notice into `sink` (when one is given)
 * for an unmarked root and returns; throws
 * {@link VaultIdentityMismatchError} when the root's marker differs from
 * the one this process pinned. Never throws for an absent, unreadable,
 * or malformed marker.
 *
 * ## Two call surfaces, one assertion
 *
 * Brain writers reach the vault tree two ways, and both funnel here.
 *
 *   - Writers that resolve a whole directory set call
 *     `brainDirsForWrite`, which is a thin wrapper over this function.
 *   - Writers that build a single path with one of the `paths.ts`
 *     builders (`preferencePath`, `entityPath`, `decisionPath`, …) call
 *     this function DIRECTLY, at their own entry point.
 *
 * The second surface exists because the builders are intent-neutral by
 * construction: `preferencePath` serves `parsePreference` and
 * `writePreference` alike, so asserting inside the builder would refuse
 * reads. The assertion therefore belongs to the writer, and it belongs
 * BEFORE the writer's first byte - a refusal that arrives after the page
 * is on disk has already materialized the wrong store.
 *
 * ## The freeze rides here, and why here rather than at the note seam
 *
 * `lane` selects which half of the write surface the caller belongs to
 * (who-wrote-what, Task C). The default, {@link WRITE_LANE.content},
 * refuses while `Brain/.state/frozen.json` exists - and it is checked
 * FIRST, ahead of the identity comparison, because a frozen vault is a
 * decision an operator made and an identity mismatch is a condition they
 * have not seen yet; reporting the second while the first holds would
 * answer a question nobody asked.
 *
 * This guard is the freeze's seam because it is the only position every
 * content writer already passes. Hooking the note-write seam instead
 * would have left the dream pass, hygiene, page-dedup and the
 * write-session engine writing preferences, signals and state straight
 * through a freeze.
 */
export function assertVaultIdentityForWrite(
  vault: string,
  sink?: DegradationNotice[],
  lane: WriteLane = WRITE_LANE.content,
): void {
  const root = resolve(vault);
  if (lane === WRITE_LANE.content) {
    assertVaultNotFrozen(root);
    // A brain store migration running on this machine (design D11 step 2).
    assertNoMigrationInProgress(root);
  }
  const vaultId = currentVaultId(root);
  if (vaultId === null) {
    if (sink !== undefined) {
      const absent = vaultMarkerAbsentNotice(root);
      // `currentVaultId` just reported no readable marker, so the notice
      // is non-null; the check keeps the types honest rather than casting.
      if (absent !== null) emitDegradationNotice(sink, absent);
    }
    return;
  }

  const pinned = PINNED_IDENTITIES.get(root);
  if (pinned === undefined) {
    PINNED_IDENTITIES.set(root, vaultId);
    return;
  }
  if (pinned === vaultId) return;

  const mismatch = compareStamps({ [VAULT_ID_FIELD]: pinned }, { [VAULT_ID_FIELD]: vaultId })[0];
  // compareStamps reports every differing field and the two ids differ,
  // so exactly one mismatch is guaranteed here.
  const evidence = mismatch as StampMismatch;
  throw new VaultIdentityMismatchError(
    degradationNotice({
      code: DEGRADATION_CODE.vaultMarkerMismatch,
      site: SITE,
      path: root,
      detail: `refusing to write: the store at this root is not the one this process opened (${formatStampMismatch(evidence)})`,
    }),
    evidence,
  );
}