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.8 KB
Raw Blame
/**
 * `o2b search restamp` (nothing-writes-silently, unit G).
 *
 * The sqlite-vec version an index recorded is a pure ABI token: it
 * describes the extension build the vectors were written under, not the
 * vectors themselves. Two peers on different sqlite-vec builds each see
 * the other's store as drifted, which is exactly why the ABI gate
 * defaults to `warn` rather than refusing - and until now the only way
 * to clear that warning was to re-embed the whole vault at provider
 * prices for a token no vector depends on.
 *
 * The claims pinned here:
 *
 *   1. Dry run is the DEFAULT: it prints the change it would make and
 *      leaves `index_state` byte-identical.
 *   2. `--apply` restamps the vec_version cell and nothing else.
 *   3. A second run has nothing to do and says so, rather than
 *      re-writing a cell that already holds the value.
 *   4. A recorded model or dimension that disagrees with this build is
 *      REFUSED by name, with the deferral stated: that repair needs
 *      re-embedding, which this verb will not do behind an operator's
 *      back.
 *   5. An absent index is refused, naming the path.
 *   6. No path through the verb contacts an embedding provider.
 */

import { afterEach, beforeEach, expect, setDefaultTimeout, test } from "bun:test";
import { Database } from "bun:sqlite";
import { join } from "node:path";

import { indexVault } from "../../src/core/search/indexer.ts";
import {
  EMBEDDING_DIMENSION_STATE_KEY,
  EMBEDDING_MODEL_STATE_KEY,
  EMBEDDING_VEC_VERSION_STATE_KEY,
} from "../../src/core/search/store.ts";
import { getState, setState } from "../../src/core/search/store/state.ts";
import { createTempVault, makeConfig, writeMd } from "../helpers/search-fixtures.ts";
import { startFakeHttp, type FakeHttp } from "../helpers/fake-http.ts";
import { runCli } from "../helpers/run-cli.ts";
import { sqliteVecLoadable } from "../helpers/sqlite-vec.ts";
import { FAKE_PROVIDER_KEY } from "../helpers/fake-credentials.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

const VEC_LOADABLE = sqliteVecLoadable();

/** A version string no sqlite-vec build reports, so the drift is real. */
const STALE_VEC_VERSION = "v0.0.0-from-another-machine";

let vault: string;
let dbPath: string;
let configPath: string;
let cleanup: () => void;
let server: FakeHttp;

beforeEach(async () => {
  const v = createTempVault("search-restamp");
  vault = v.vault;
  dbPath = v.dbPath;
  cleanup = v.cleanup;
  server = await startFakeHttp();
  configPath = join(vault, "cli-config.yaml");
});

afterEach(async () => {
  cleanup();
  await server.close();
});

function semanticConfig() {
  return makeConfig({
    vault,
    dbPath,
    semantic: {
      enabled: true,
      provider: "openai-compat",
      baseUrl: server.url,
      model: "fake-model",
      apiKey: FAKE_PROVIDER_KEY,
      dimension: 4,
      timeoutMs: 5_000,
    },
  });
}

async function writeConfig(): Promise<void> {
  await Bun.write(
    configPath,
    [
      `vault: "${vault}"`,
      "search_semantic_enabled: true",
      "embedding_provider: openai-compat",
      `embedding_base_url: "${server.url}"`,
      "embedding_model: fake-model",
      "embedding_api_key: test-key",
      "embedding_dimension: 4",
      "",
    ].join("\n"),
  );
}

function readState(key: string): string | null {
  const db = new Database(dbPath, { readonly: true });
  try {
    return getState(db, key);
  } finally {
    db.close();
  }
}

function writeStateDirectly(key: string, value: string): void {
  const db = new Database(dbPath);
  try {
    setState(db, key, value);
  } finally {
    db.close();
  }
}

async function indexWithVectors(): Promise<void> {
  writeMd(vault, "a.md", "# A\n\nA note with vectors.");
  await indexVault(semanticConfig(), { embeddings: true });
  await writeConfig();
}

function restamp(...extra: ReadonlyArray<string>) {
  return runCli(
    ["search", "restamp", "--vault", vault, "--db", dbPath, "--config", configPath, ...extra],
    { env: { OPEN_SECOND_BRAIN_CONFIG: configPath } },
  );
}

test.skipIf(!VEC_LOADABLE)("the dry run prints the change and writes nothing", async () => {
  await indexWithVectors();
  const current = readState(EMBEDDING_VEC_VERSION_STATE_KEY);
  expect(typeof current).toBe("string");
  writeStateDirectly(EMBEDDING_VEC_VERSION_STATE_KEY, STALE_VEC_VERSION);

  const callsBefore = server.callCount();
  const run = await restamp();
  expect(run.returncode).toBe(0);
  expect(run.stdout).toContain("dry-run");
  expect(run.stdout).toContain(STALE_VEC_VERSION);
  expect(run.stdout).toContain(current as string);
  expect(run.stdout).toContain("--apply");
  // The cell is exactly as the dry run found it.
  expect(readState(EMBEDDING_VEC_VERSION_STATE_KEY)).toBe(STALE_VEC_VERSION);
  // Nothing here asks a provider anything: the only calls on the record
  // are the ones the fixture's own indexing run made.
  expect(server.callCount()).toBe(callsBefore);
});

test.skipIf(!VEC_LOADABLE)("--apply restamps the vec_version cell and nothing else", async () => {
  await indexWithVectors();
  const current = readState(EMBEDDING_VEC_VERSION_STATE_KEY) as string;
  const model = readState(EMBEDDING_MODEL_STATE_KEY);
  const dimension = readState(EMBEDDING_DIMENSION_STATE_KEY);
  writeStateDirectly(EMBEDDING_VEC_VERSION_STATE_KEY, STALE_VEC_VERSION);

  const callsBefore = server.callCount();
  const run = await restamp("--apply", "--json");
  expect(run.returncode).toBe(0);
  const payload = JSON.parse(run.stdout) as Record<string, unknown>;
  expect(payload["applied"]).toBe(true);
  expect(payload["field"]).toBe(EMBEDDING_VEC_VERSION_STATE_KEY);
  expect(payload["recorded"]).toBe(STALE_VEC_VERSION);
  expect(payload["runtime"]).toBe(current);

  expect(readState(EMBEDDING_VEC_VERSION_STATE_KEY)).toBe(current);
  expect(readState(EMBEDDING_MODEL_STATE_KEY)).toBe(model);
  expect(readState(EMBEDDING_DIMENSION_STATE_KEY)).toBe(dimension);
  expect(server.callCount()).toBe(callsBefore);
});

test.skipIf(!VEC_LOADABLE)("a store already at this version has nothing to do", async () => {
  await indexWithVectors();

  const run = await restamp("--json");
  expect(run.returncode).toBe(0);
  const payload = JSON.parse(run.stdout) as Record<string, unknown>;
  expect(payload["changed"]).toBe(false);
  expect(payload["applied"]).toBe(false);
});

test.skipIf(!VEC_LOADABLE)(
  "a recorded dimension that disagrees is refused by name, with the deferral stated",
  async () => {
    await indexWithVectors();
    writeStateDirectly(EMBEDDING_VEC_VERSION_STATE_KEY, STALE_VEC_VERSION);
    writeStateDirectly(EMBEDDING_DIMENSION_STATE_KEY, "8");

    const callsBefore = server.callCount();
    const run = await restamp("--apply");
    expect(run.returncode).not.toBe(0);
    expect(run.stderr).toContain(EMBEDDING_DIMENSION_STATE_KEY);
    expect(run.stderr).toContain("deferred");
    // The refusal wrote nothing: the stale token is still there.
    expect(readState(EMBEDDING_VEC_VERSION_STATE_KEY)).toBe(STALE_VEC_VERSION);
    expect(server.callCount()).toBe(callsBefore);
  },
);

test.skipIf(!VEC_LOADABLE)("a recorded model that disagrees is refused by name too", async () => {
  await indexWithVectors();
  writeStateDirectly(EMBEDDING_VEC_VERSION_STATE_KEY, STALE_VEC_VERSION);
  writeStateDirectly(EMBEDDING_MODEL_STATE_KEY, "some-other-model");

  const run = await restamp("--apply");
  expect(run.returncode).not.toBe(0);
  expect(run.stderr).toContain(EMBEDDING_MODEL_STATE_KEY);
  expect(readState(EMBEDDING_VEC_VERSION_STATE_KEY)).toBe(STALE_VEC_VERSION);
});

test("an absent index is refused, naming the path", async () => {
  await writeConfig();
  const run = await restamp();
  expect(run.returncode).not.toBe(0);
  expect(run.stderr).toContain(dbPath);
  expect(server.callCount()).toBe(0);
});