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
7.6 KB
Raw Blame
/**
 * `o2b search restamp` — record this build's sqlite-vec version as the
 * one the stored vectors are accepted under (nothing-writes-silently,
 * unit G).
 *
 * `embedding_vec_version` is an ABI marker, not a property of any
 * vector: it says which sqlite-vec build wrote the storage, and two
 * peers on different builds each read the other's index as drifted.
 * That is precisely why `integrity.embedding_abi` defaults to `warn`
 * rather than refusing - a hard gate would loop a synced vault through
 * rebuilds - and until this verb existed the only way to clear the
 * warning was `o2b search reindex --embeddings`, which pays provider
 * prices to re-derive vectors that were never the problem.
 *
 * What this verb claims, exactly: that the operator accepts the stored
 * vectors under the extension this build loads. It does not verify
 * them. Nothing can - a vector's bytes do not carry the version that
 * wrote them - and a verb that implied otherwise would be the kind of
 * unearned reassurance this wave removes.
 *
 * Three properties are deliberate:
 *
 *   - Dry run is the DEFAULT, as on every other repair verb in this
 *     family. `--apply` is the only path that writes a cell.
 *   - It refuses BY NAME when the recorded model or dimension disagrees
 *     with this build. Those two describe the vectors themselves;
 *     writing a new token over them would record an identity nobody
 *     checked. Repairing that needs re-embedding under a verified
 *     identity, which is deferred by design - the recon that scoped
 *     this wave put it behind the same explicit cost gate
 *     `planVectorBackfill` uses, and it is not built.
 *   - It contacts no provider on any path. The only outside thing it
 *     touches is the sqlite-vec extension, loaded into an in-memory
 *     database to ask its version.
 *
 * The write does NOT go through `Store.open(…, { mode: "write" })`.
 * That path runs `ensureEmbeddingModel`, which CLEARS every stored
 * vector when the model or dimension changed - exactly the destructive
 * repair this verb refuses to perform. It takes the writer lock and
 * writes the one cell instead, the same way `search check --integrity`
 * records its verdict.
 */

import { Database } from "bun:sqlite";

import { compareStamps, formatStampMismatch } from "../../../core/integrity/stamp.ts";
import {
  acquireWriterLock,
  contradictedAbiFields,
  EMBEDDING_ABI_FIX_COMMAND,
  EMBEDDING_VEC_VERSION_STATE_KEY,
  peekEmbeddingAbiSync,
  runtimeEmbeddingAbi,
} from "../../../core/search/store.ts";
import { describeUnreadableIndex, setState } from "../../../core/search/store/state.ts";
import { loadVecExtension } from "../../../core/search/store/vectors.ts";
import { SearchError } from "../../../core/search/types.ts";
import { info, ok } from "../../output.ts";
import { flagBoolean, parseFlags, resolveConfig, VAULT_FLAGS } from "../helpers.ts";
import { closeDatabase } from "../../../core/sqlite-close.ts";

/** What one restamp run concluded, before it is rendered. */
interface RestampResult {
  /** The token the index records, or null when it never recorded one. */
  readonly recorded: string | null;
  /** The version this build's extension reports. */
  readonly runtime: string;
  /** Whether the two differ at all. */
  readonly changed: boolean;
  /** Whether this run wrote the cell. False on every dry run. */
  readonly applied: boolean;
}

/**
 * The sqlite-vec version this build reports, from an in-memory database
 * so the real index is not opened to answer a question about the
 * extension.
 */
function runtimeVecVersion(): string {
  const probe = new Database(":memory:");
  try {
    const version = loadVecExtension(probe);
    if (version === null) {
      throw new SearchError(
        "VEC_EXTENSION_UNAVAILABLE",
        "sqlite-vec did not load in this build, so there is no version to record. " +
          "Run `o2b search check` for the extension's own diagnosis",
      );
    }
    return version;
  } finally {
    closeDatabase(probe);
  }
}

/**
 * Refuse, naming every field, when the record disagrees with this build
 * about something a restamp cannot fix. Only fields the index actually
 * RECORDED count - an unrecorded token is a store written before that
 * token existed, which `contradictedAbiFields` already declines to
 * treat as wrong.
 */
function refuseUnrepairableDrift(
  recorded: Record<string, string | null>,
  runtime: Record<string, string | null>,
): void {
  const blocking = contradictedAbiFields(compareStamps(recorded, runtime)).filter(
    (m) => m.field !== EMBEDDING_VEC_VERSION_STATE_KEY,
  );
  if (blocking.length === 0) return;
  throw new SearchError(
    "EMBEDDING_DIMENSION_MISMATCH",
    `restamp refuses: ${blocking.map(formatStampMismatch).join("; ")}. Those fields describe ` +
      `the stored vectors, so recording a new token over them would claim an identity nothing ` +
      `verified. The repair is re-embedding under a verified identity, which is deferred by ` +
      `design and not built; today's honest fix is a rebuild. Run: ${EMBEDDING_ABI_FIX_COMMAND}`,
  );
}

/** Write the one cell, under the writer lock, and nothing else. */
async function applyRestamp(dbPath: string, version: string): Promise<void> {
  const release = await acquireWriterLock(dbPath);
  try {
    const db = new Database(dbPath);
    try {
      setState(db, EMBEDDING_VEC_VERSION_STATE_KEY, version);
    } finally {
      closeDatabase(db);
    }
  } finally {
    await release();
  }
}

function jsonForResult(r: RestampResult): Record<string, unknown> {
  return {
    dry_run: !r.applied,
    field: EMBEDDING_VEC_VERSION_STATE_KEY,
    recorded: r.recorded,
    runtime: r.runtime,
    changed: r.changed,
    applied: r.applied,
  };
}

function renderHuman(r: RestampResult): void {
  if (!r.changed) {
    ok(`restamp: ${EMBEDDING_VEC_VERSION_STATE_KEY} already records ${r.runtime}; nothing to do`);
    return;
  }
  const change = `${EMBEDDING_VEC_VERSION_STATE_KEY} ${r.recorded ?? "unrecorded"} -> ${r.runtime}`;
  if (r.applied) {
    ok(`restamp: ${change} recorded`);
    return;
  }
  ok(`restamp dry-run: ${change}`);
  info("  nothing was written; pass --apply to record it");
}

export async function cmdSearchRestamp(argv: ReadonlyArray<string>): Promise<number> {
  const { flags } = parseFlags(argv, {
    ...VAULT_FLAGS,
    apply: { type: "boolean" },
    json: { type: "boolean" },
  });
  const cfg = resolveConfig(flags);
  if (!cfg.semantic.enabled) {
    throw new SearchError(
      "EMBEDDING_DISABLED",
      "semantic search is disabled in this configuration, so there is no embedder identity to restamp",
    );
  }

  const peek = peekEmbeddingAbiSync(cfg.dbPath);
  if (peek.kind !== "read") {
    // An index that is not there and one that will not open are
    // different faults and are named as the different faults they are.
    throw new SearchError(
      peek.kind === "absent" ? "INDEX_MISSING" : "INDEX_UNREADABLE",
      peek.kind === "absent"
        ? `no search index at ${cfg.dbPath}; there is nothing to restamp`
        : `the search index at ${describeUnreadableIndex(cfg.dbPath, peek.detail)}`,
    );
  }

  const runtime = runtimeVecVersion();
  refuseUnrepairableDrift(peek.value, runtimeEmbeddingAbi(cfg, runtime));

  const recorded = peek.value[EMBEDDING_VEC_VERSION_STATE_KEY] ?? null;
  const changed = recorded !== runtime;
  const apply = flagBoolean(flags, "apply");
  if (changed && apply) await applyRestamp(cfg.dbPath, runtime);

  const result: RestampResult = { recorded, runtime, changed, applied: changed && apply };
  if (flagBoolean(flags, "json")) {
    process.stdout.write(JSON.stringify(jsonForResult(result)) + "\n");
  } else {
    renderHuman(result);
  }
  return 0;
}