synabun 1.3.0 → 2.0.0

package/mcp-server/src/services/typesafe.ts

@@ -0,0 +1,390 @@
+/**
+ * TypeSafe System One client (Jev).
+ *
+ * Returns typed judgments — Choice / Noul / Score — where SynaBun would
+ * otherwise hard-code a regex or a similarity constant. Raw `fetch` rather
+ * than `@typesafe-ai/sdk`: the wire format is three fields and mcp-server
+ * keeps a deliberately small dependency list.
+ *
+ * Contract (verified against the live API, 2026-09-18):
+ *   POST https://api.typesafe.ai/v1/systemone
+ *   { model, state, questions } -> { model, usage, answers }
+ *   - noul   -> { type, noul }                                  P(yes); there is NO confidence field
+ *   - choice -> { type, choice, confidence, probabilities }      probabilities sum to 1
+ *   - score  -> { type, score, confidence, legend, probabilities }
+ * The response `model` does not echo the request verbatim — never assert on it.
+ *
+ * Every call site must survive `null`. `judge()` never throws and never
+ * rejects: on a missing key, a disabled surface, timeout, non-2xx or
+ * malformed body it returns null and the caller falls back to its original
+ * heuristic. That is error handling, not a feature flag — a network blip must
+ * not break `remember`.
+ *
+ * Runtime knobs (master switch, per-surface enable/timeout, model, base URL)
+ * come from typesafe-config.ts, which reads kv_config so the Judgments tab
+ * changes them for every process without a restart. Only the API key and the
+ * SYNABUN_TYPESAFE=off kill switch stay in the environment.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { getEnvPath } from '../config.js';
+import { callerMemoryContext } from './identity.js';
+import {
+  typesafeConfig, surfaceConfig, writeTypeSafeLog, statePreview, cleanSessionId,
+  DEFAULT_BASE_URL, DEFAULT_MODEL, type JudgeOrigin,
+} from './typesafe-config.js';
+
+const API_PATH = '/v1/systemone';
+const CACHE_LIMIT = 500;
+
+// --- Question builders (mirror the SDK's, so docs examples port verbatim) ---
+
+export type Instructions = string | Record<string, unknown> | unknown[] | null;
+
+export interface NoulQuestion { type: 'noul'; instructions: Instructions; criteria?: { true?: string; false?: string } }
+export interface ChoiceQuestion { type: 'choice'; instructions: Instructions; criteria: Record<string, string | null> }
+export interface ScoreQuestion { type: 'score'; instructions: Instructions; criteria: (string | null)[] }
+export type Question = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+
+/** Yes/no. The answer is P(yes) — 0.5 means "equally likely", not "medium intensity". */
+export function noul(instructions: Instructions, criteria?: { true?: string; false?: string }): NoulQuestion {
+  return { type: 'noul', instructions, criteria };
+}
+
+/** One of a named set. `criteria` maps label -> description (null for undescribed). */
+export function choice(instructions: Instructions, criteria: Record<string, string | null>): ChoiceQuestion {
+  return { type: 'choice', instructions, criteria };
+}
+
+/** Ordered rubric; `criteria[0]` is the lowest level. At least two are required. */
+export function score(instructions: Instructions, criteria: (string | null)[]): ScoreQuestion {
+  if (criteria.length < 2) throw new Error('Score questions need at least two ordered levels.');
+  return { type: 'score', instructions, criteria };
+}
+
+// --- Answers ---
+
+export interface NoulAnswer { type: 'noul'; noul: number }
+export interface ChoiceAnswer { type: 'choice'; choice: string; confidence: number; probabilities: Record<string, number> }
+export interface ScoreAnswer { type: 'score'; score: number; confidence: number; legend: Record<string, string>; probabilities: Record<string, number> }
+export type Answer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+export type Answers = Record<string, Answer>;
+
+// --- Key resolution ---
+
+let cachedKey: string | null | undefined;
+
+function readDotenvKey(): string | null {
+  try {
+    const envPath = getEnvPath();
+    if (!existsSync(envPath)) return null;
+    for (const line of readFileSync(envPath, 'utf-8').split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eq = trimmed.indexOf('=');
+      if (eq < 0) continue;
+      if (trimmed.slice(0, eq).trim() !== 'TYPESAFE_API_KEY') continue;
+      const value = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, '');
+      return value || null;
+    }
+  } catch { /* unreadable .env is the same as no key */ }
+  return null;
+}
+
+/**
+ * Environment first, then SynaBun's own .env. The `:3344` server inherits the
+ * shell that launched it, which is not necessarily the shell that exported the
+ * key — reading the .env as a fallback keeps a launcher-started server working.
+ */
+export function typesafeApiKey(): string | null {
+  // Operational kill switch, not a privacy toggle: it exists so the test suite
+  // is deterministic and so an operator can stop outbound calls during an
+  // incident without editing code or revoking a key.
+  if (process.env.SYNABUN_TYPESAFE === 'off') return null;
+  if (cachedKey !== undefined) return cachedKey;
+  const fromEnv = process.env.TYPESAFE_API_KEY?.trim();
+  if (fromEnv) return (cachedKey = fromEnv);
+  return (cachedKey = readDotenvKey());
+}
+
+/** Forget the resolved key so a .env edit takes effect without a restart. */
+export function resetTypeSafeKey(): void { cachedKey = undefined; }
+
+export interface KeyInfo { hasKey: boolean; last4: string | null; source: 'env' | 'dotenv' | 'none'; shadowed: boolean }
+
+/**
+ * Where the key in use comes from, read fresh (bypasses the cache and the kill
+ * switch). `shadowed` means a key saved in .env is being ignored because the
+ * process was launched from a shell that exported a different one — the
+ * settings page has to say so, or "Save" looks broken.
+ */
+export function typesafeKeyInfo(): KeyInfo {
+  const fromEnv = process.env.TYPESAFE_API_KEY?.trim() || null;
+  const fromFile = readDotenvKey();
+  const active = fromEnv ?? fromFile;
+  if (!active) return { hasKey: false, last4: null, source: 'none', shadowed: false };
+  const source: KeyInfo['source'] = fromEnv && fromEnv !== fromFile ? 'env' : 'dotenv';
+  return { hasKey: true, last4: active.slice(-4), source, shadowed: Boolean(fromEnv && fromFile && fromEnv !== fromFile) };
+}
+
+export interface BaseUrlInfo { url: string; source: 'env' | 'config' | 'default'; shadowed: boolean }
+
+export function typesafeBaseUrl(): BaseUrlInfo {
+  const fromEnv = process.env.TYPESAFE_BASE_URL?.trim().replace(/\/+$/, '') || null;
+  const fromConfig = typesafeConfig().baseUrl?.replace(/\/+$/, '') || null;
+  if (fromEnv) return { url: fromEnv, source: 'env', shadowed: Boolean(fromConfig && fromConfig !== fromEnv) };
+  if (fromConfig) return { url: fromConfig, source: 'config', shadowed: false };
+  return { url: DEFAULT_BASE_URL, source: 'default', shadowed: false };
+}
+
+/** Env kill switch off, kv master switch on, and a key resolved. */
+export function typesafeEnabled(): boolean {
+  if (process.env.SYNABUN_TYPESAFE === 'off') return false;
+  if (!typesafeConfig().enabled) return false;
+  return typesafeApiKey() !== null;
+}
+
+// --- Cache ---
+
+/**
+ * Judgments are pure in (state, questions, model), so identical inputs reuse
+ * the answer. Insertion-ordered Map evicting the oldest entry is enough: the
+ * hot case is a maintenance re-index over rows whose content did not change.
+ */
+const cache = new Map<string, Answers>();
+
+function cacheKey(model: string, state: unknown, questions: Record<string, Question>): string {
+  return createHash('sha256').update(JSON.stringify({ model, state, questions })).digest('hex');
+}
+
+export function typesafeCacheSize(): number { return cache.size; }
+export function clearTypeSafeCache(): void { cache.clear(); }
+
+// --- Metrics (surfaced through /api/typesafe/config for cost/latency review) ---
+
+export interface SurfaceMetrics { calls: number; hits: number; failures: number; cached: number; skipped: number; inputTokens: number; outputTokens: number; totalMs: number }
+
+const emptySurface = (): SurfaceMetrics => ({ calls: 0, hits: 0, failures: 0, cached: 0, skipped: 0, inputTokens: 0, outputTokens: 0, totalMs: 0 });
+
+export const typesafeMetrics = {
+  calls: 0, hits: 0, failures: 0, cached: 0, skipped: 0,
+  inputTokens: 0, outputTokens: 0, totalMs: 0,
+  lastError: null as string | null,
+  lastErrorAt: null as string | null,
+  /** Set from a 429's retry-after header; the backfill waits it out. */
+  retryAfterUntil: 0,
+  surfaces: {} as Record<string, SurfaceMetrics>,
+};
+
+function surfaceMetrics(name: string): SurfaceMetrics {
+  return (typesafeMetrics.surfaces[name] ??= emptySurface());
+}
+
+export function resetTypeSafeMetrics(): void {
+  Object.assign(typesafeMetrics, { calls: 0, hits: 0, failures: 0, cached: 0, skipped: 0, inputTokens: 0, outputTokens: 0, totalMs: 0, lastError: null, lastErrorAt: null, retryAfterUntil: 0, surfaces: {} });
+}
+
+export function typesafeStats() {
+  const surfaces: Record<string, SurfaceMetrics & { avgMs: number }> = {};
+  for (const [name, m] of Object.entries(typesafeMetrics.surfaces)) surfaces[name] = { ...m, avgMs: m.hits ? Math.round(m.totalMs / m.hits) : 0 };
+  return {
+    calls: typesafeMetrics.calls, hits: typesafeMetrics.hits, failures: typesafeMetrics.failures, cached: typesafeMetrics.cached, skipped: typesafeMetrics.skipped,
+    inputTokens: typesafeMetrics.inputTokens, outputTokens: typesafeMetrics.outputTokens, totalMs: typesafeMetrics.totalMs,
+    lastError: typesafeMetrics.lastError, lastErrorAt: typesafeMetrics.lastErrorAt,
+    retryAfterMs: Math.max(0, typesafeMetrics.retryAfterUntil - Date.now()),
+    enabled: typesafeEnabled(),
+    killSwitch: process.env.SYNABUN_TYPESAFE === 'off',
+    masterEnabled: typesafeConfig().enabled,
+    cacheSize: cache.size,
+    avgMs: typesafeMetrics.hits ? Math.round(typesafeMetrics.totalMs / typesafeMetrics.hits) : 0,
+    surfaces,
+  };
+}
+
+/** Milliseconds a 429 asked us to wait, or 0. */
+export function typesafeRetryAfterMs(): number { return Math.max(0, typesafeMetrics.retryAfterUntil - Date.now()); }
+
+// --- The call ---
+
+export interface JudgeUsage {
+  inputTokens: number; outputTokens: number; latencyMs: number; cached: boolean;
+  /** The versioned id the API says answered; for reports only, never asserted on. */
+  model?: string | null;
+}
+
+export interface JudgeOptions {
+  model?: string;
+  timeoutMs?: number;
+  /** Skip the cache for this call (used by the bench, which measures cold latency). */
+  noCache?: boolean;
+  /** Caller cancellation. Combined with the timeout, never instead of it. */
+  signal?: AbortSignal;
+  /**
+   * What the log row shows instead of a preview of `state`. Browser surfaces
+   * judge page content, which must not reach typesafe_log; they pass metadata
+   * here, and a `browser-*` or `desktop-*` call that forgets to is logged as `[withheld]`.
+   * Still credential-redacted and cut like any other preview.
+   */
+  logPreview?: string;
+  /** Which SynaBun surface is asking; drives the enable/timeout lookup and the log row. */
+  surface?: string;
+  origin?: JudgeOrigin;
+  /** The memory (or other entity) this judgment is about, for the log. */
+  entityId?: string;
+  /** Which session asked (Claude session, loop run). Defaults to the MCP caller's memory session. */
+  sessionId?: string | null;
+  /** Which project it was asked for. Defaults to the MCP caller's project. */
+  project?: string | null;
+  /** Surfaces whose questions ride in this request, logged beside the lead `surface`. */
+  riders?: string[];
+  /** Called with the log row id, so the caller can annotate what it did with the answer. */
+  onLogged?: (id: number | null) => void;
+  /** Called with token/latency usage on every answered call, including cache hits. */
+  onUsage?: (usage: JudgeUsage) => void;
+}
+
+function parseRetryAfter(header: string | null): number {
+  if (!header) return 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const at = Date.parse(header);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : 0;
+}
+
+/**
+ * Ask one or more independent judgments over a single state.
+ *
+ * Batch freely: questions in one request run in parallel and cannot see each
+ * other's answers, so N judgments over the same evidence cost one round trip.
+ * Split into a second request only when an answer is needed to build the next
+ * state. Returns null on any failure — callers fall back to their heuristic.
+ */
+export async function judge(
+  state: unknown,
+  questions: Record<string, Question>,
+  options: JudgeOptions = {},
+): Promise<Answers | null> {
+  const surface = options.surface ?? 'unknown';
+  const origin: JudgeOrigin = options.origin ?? 'live';
+  if (!typesafeEnabled()) return null;
+  if (!Object.keys(questions).length) return null;
+  const settings = surfaceConfig(surface);
+  if (options.surface && !settings.enabled) {
+    // A disabled surface is a decision, not a failure: no request, no log
+    // row, so the counters show it was skipped rather than that it broke.
+    surfaceMetrics(surface).skipped++;
+    typesafeMetrics.skipped++;
+    return null;
+  }
+  const key = typesafeApiKey();
+  if (!key) return null;
+
+  const cfg = typesafeConfig();
+  const model = options.model ?? cfg.model ?? DEFAULT_MODEL;
+  const questionCount = Object.keys(questions).length;
+  const metrics = surfaceMetrics(surface);
+  // Withheld by default for browser and desktop surfaces: one forgotten call
+  // site must not put 500 characters of someone's page or screen into the log.
+  const preview = options.logPreview !== undefined ? statePreview(options.logPreview)
+    : /^(?:browser|desktop)-/.test(surface) ? '[withheld]' : statePreview(state);
+  // Attribution: an explicit session/project wins; otherwise the MCP caller's
+  // own context (the HTTP identity or the stdio server's environment).
+  let caller: { project?: string; session?: string } = {};
+  if (options.sessionId === undefined || options.project === undefined) { try { caller = callerMemoryContext() ?? {}; } catch { caller = {}; } }
+  const sessionId = cleanSessionId(options.sessionId === undefined ? caller.session : options.sessionId);
+  const project = (options.project === undefined ? caller.project : options.project) || null;
+  const riders = options.riders?.filter(r => r && r !== surface) ?? [];
+  const log = (fields: { answers?: Answers | null; latencyMs: number; inputTokens: number; outputTokens: number; cached: boolean; error: string | null; model?: string | null }) => {
+    const id = writeTypeSafeLog({
+      surface, origin, entity_id: options.entityId ?? null, model: fields.model ?? model,
+      question_count: questionCount, state_preview: preview, answers: fields.answers ?? null,
+      latency_ms: fields.latencyMs, input_tokens: fields.inputTokens, output_tokens: fields.outputTokens,
+      cached: fields.cached ? 1 : 0, error: fields.error,
+      session_id: sessionId, project, surfaces: riders.length ? [surface, ...riders] : null,
+    });
+    try { options.onLogged?.(id); } catch { /* a caller's bookkeeping must not break the judgment */ }
+  };
+
+  const hash = cacheKey(model, state, questions);
+  if (!options.noCache) {
+    const cached = cache.get(hash);
+    if (cached) {
+      typesafeMetrics.cached++; metrics.cached++;
+      options.onUsage?.({ inputTokens: 0, outputTokens: 0, latencyMs: 0, cached: true });
+      log({ answers: cached, latencyMs: 0, inputTokens: 0, outputTokens: 0, cached: true, error: null });
+      return cached;
+    }
+  }
+
+  const baseUrl = typesafeBaseUrl().url;
+  const timeoutMs = options.timeoutMs ?? settings.timeoutMs ?? cfg.defaultTimeoutMs;
+  const started = Date.now();
+  typesafeMetrics.calls++; metrics.calls++;
+  const fail = (message: string) => {
+    typesafeMetrics.failures++; metrics.failures++;
+    typesafeMetrics.lastError = message;
+    typesafeMetrics.lastErrorAt = new Date().toISOString();
+    log({ latencyMs: Date.now() - started, inputTokens: 0, outputTokens: 0, cached: false, error: message });
+    return null;
+  };
+  try {
+    const response = await fetch(`${baseUrl}${API_PATH}`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${key}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        'User-Agent': 'synabun-mcp',
+      },
+      body: JSON.stringify({ model, state, questions }),
+      // A caller's signal used to replace the timeout, so a cancellable call
+      // could wait forever. Both hold now.
+      signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) {
+      // Never surface the body verbatim: it echoes the request, which carries
+      // memory content. Status alone is enough to tell quota from outage.
+      if (response.status === 429) {
+        const wait = parseRetryAfter(response.headers?.get?.('retry-after') ?? null) || 30_000;
+        typesafeMetrics.retryAfterUntil = Date.now() + wait;
+      }
+      return fail(`HTTP ${response.status}`);
+    }
+    const body = await response.json() as { model?: string; answers?: Answers; usage?: { input_tokens?: number; output_tokens?: number } };
+    if (!body?.answers || typeof body.answers !== 'object') return fail('malformed response');
+    const latencyMs = Date.now() - started;
+    const inputTokens = body.usage?.input_tokens ?? 0;
+    const outputTokens = body.usage?.output_tokens ?? 0;
+    typesafeMetrics.hits++; metrics.hits++;
+    typesafeMetrics.totalMs += latencyMs; metrics.totalMs += latencyMs;
+    typesafeMetrics.inputTokens += inputTokens; metrics.inputTokens += inputTokens;
+    typesafeMetrics.outputTokens += outputTokens; metrics.outputTokens += outputTokens;
+    if (!options.noCache) {
+      if (cache.size >= CACHE_LIMIT) cache.delete(cache.keys().next().value as string);
+      cache.set(hash, body.answers);
+    }
+    const answeredBy = typeof body.model === 'string' ? body.model : null;
+    options.onUsage?.({ inputTokens, outputTokens, latencyMs, cached: false, model: answeredBy });
+    log({ answers: body.answers, latencyMs, inputTokens, outputTokens, cached: false, error: null, model: answeredBy ?? model });
+    return body.answers;
+  } catch (error) {
+    return fail((error as Error).name === 'TimeoutError' ? 'timeout' : (error as Error).message);
+  }
+}
+
+// --- Typed answer readers (a wrong-typed answer is a miss, not a crash) ---
+
+export function readNoul(answer: Answer | undefined): number | null {
+  return answer?.type === 'noul' && Number.isFinite(answer.noul) ? answer.noul : null;
+}
+
+export function readChoice(answer: Answer | undefined): { choice: string; confidence: number } | null {
+  if (answer?.type !== 'choice' || typeof answer.choice !== 'string') return null;
+  return { choice: answer.choice, confidence: Number.isFinite(answer.confidence) ? answer.confidence : 0 };
+}
+
+export function readScore(answer: Answer | undefined): { score: number; confidence: number } | null {
+  if (answer?.type !== 'score' || !Number.isFinite(answer.score)) return null;
+  return { score: answer.score, confidence: Number.isFinite(answer.confidence) ? answer.confidence : 0 };
+}

package/mcp-server/src/services/vector-cache.ts

@@ -0,0 +1,255 @@
+/**
+ * In-memory vector cache for similarity search.
+ *
+ * Holds all row vectors of one table in a single contiguous Float32Array
+ * matrix (~14MB for 9k memories at 384 dims), so a search is one dot-product
+ * sweep instead of a full-table scan with per-row BLOB decode.
+ *
+ * Coherence model:
+ * - Same-process writes patch the cache incrementally via set()/remove(),
+ *   or call invalidate() for bulk operations.
+ * - Cross-process writes are detected with `PRAGMA data_version`, which
+ *   changes whenever ANOTHER connection commits to the database file.
+ *   On change the cache fully reloads (one scan, amortized across queries).
+ */
+
+import type { DatabaseSync } from 'node:sqlite';
+
+interface TopKResult {
+  id: string;
+  score: number;
+}
+
+export class VectorCache {
+  private ids: string[] = [];
+  private rowIndexById = new Map<string, number>();
+  private matrix: Float32Array = new Float32Array(0);
+  private dim = 0;
+  private count = 0;
+  private capacity = 0;
+  private loaded = false;
+  private lastDataVersion = -1;
+  private lastSequence = -1;
+  private refreshing = false;
+  public reloadCount = 0;
+  private connection: DatabaseSync | null = null;
+
+  constructor(
+    private getDb: () => DatabaseSync,
+    private loadSql: string, // must select (id, vector)
+    private getVectorSql: string, // must select (vector) by id = ?
+    private entity?: string,
+  ) {}
+
+  /** Drop everything; next query reloads from the database. */
+  invalidate(): void {
+    this.loaded = false;
+    this.ids = [];
+    this.rowIndexById.clear();
+    this.matrix = new Float32Array(0);
+    this.count = 0;
+    this.capacity = 0;
+    this.dim = 0;
+    this.lastDataVersion = -1;
+    this.lastSequence = -1;
+  }
+
+  private dataVersion(): number {
+    const row = this.getDb().prepare('PRAGMA data_version').get() as { data_version: number };
+    return row.data_version;
+  }
+
+  private ensureFresh(): void {
+    if (this.refreshing) return;
+    const connection = this.getDb();
+    if(connection !== this.connection) {this.invalidate();this.connection=connection;}
+    if (this.entity && this.loaded) {
+      this.refreshing = true;
+      try {
+        const rows = this.getDb().prepare('SELECT seq,id FROM memory_changes WHERE entity=? AND seq>? ORDER BY seq LIMIT 2049')
+          .all(this.entity, this.lastSequence) as Array<{seq:number;id:string}>;
+        if (rows.length > 2048) { this.reload(); return; }
+        for (const id of new Set(rows.map(r => r.id))) {
+          this.remove(id);
+          this.setFromDb(id);
+        }
+        if (rows.length) this.lastSequence = rows[rows.length - 1].seq;
+        return;
+      } finally { this.refreshing = false; }
+    }
+    if (this.loaded) {
+      // data_version only changes when another connection commits —
+      // our own writes are already applied incrementally.
+      const v = this.dataVersion();
+      if (v === this.lastDataVersion) return;
+    }
+    this.reload();
+  }
+
+  private reload(): void {
+    this.reloadCount++;
+    // Read the watermark BEFORE the rows. A concurrent commit will then be
+    // replayed on the next call instead of accidentally marked as observed.
+    if (this.entity) this.lastSequence = Number((this.getDb().prepare('SELECT COALESCE(MAX(seq),0) AS seq FROM memory_changes WHERE entity=?').get(this.entity) as {seq:number}).seq);
+    const rows = this.getDb().prepare(this.loadSql).all() as Array<{ id: string; vector: Uint8Array }>;
+    this.ids = [];
+    this.rowIndexById.clear();
+    this.count = 0;
+
+    // Establish dimensions from the first valid row
+    this.dim = 0;
+    for (const row of rows) {
+      if (row.vector && row.vector.byteLength >= 4) {
+        this.dim = row.vector.byteLength / 4;
+        break;
+      }
+    }
+    this.capacity = Math.max(rows.length, 64);
+    this.matrix = new Float32Array(this.capacity * Math.max(this.dim, 1));
+
+    for (const row of rows) {
+      if (!row.vector || row.vector.byteLength !== this.dim * 4) continue; // skip malformed
+      const vec = new Float32Array(row.vector.buffer, row.vector.byteOffset, this.dim);
+      this.matrix.set(vec, this.count * this.dim);
+      this.rowIndexById.set(row.id, this.count);
+      this.ids.push(row.id);
+      this.count++;
+    }
+
+    this.lastDataVersion = this.dataVersion();
+    this.loaded = true;
+  }
+
+  private grow(): void {
+    this.capacity = Math.max(this.capacity * 2, 64);
+    const next = new Float32Array(this.capacity * Math.max(this.dim, 1));
+    next.set(this.matrix.subarray(0, this.count * this.dim));
+    this.matrix = next;
+  }
+
+  /**
+   * Reclaim backing memory after deletions. grow() only ever doubles capacity,
+   * so a long-lived process with churn (add then delete) keeps the matrix sized
+   * to its historical peak. When utilization drops below 25% of a non-trivial
+   * capacity, reallocate down to ~2x count so the freed slots return to the heap.
+   */
+  private maybeShrink(): void {
+    if (this.capacity <= 64 || this.dim === 0) return;
+    if (this.count >= this.capacity / 4) return;
+    const nextCap = Math.max(this.count * 2, 64);
+    if (nextCap >= this.capacity) return;
+    const next = new Float32Array(nextCap * this.dim);
+    next.set(this.matrix.subarray(0, this.count * this.dim));
+    this.matrix = next;
+    this.capacity = nextCap;
+  }
+
+  /** Insert or replace a row's vector (same-process write hook). */
+  set(id: string, vector: number[] | Float32Array): void {
+    if (!this.loaded) return; // nothing cached yet — next query loads fresh
+    if (this.dim === 0) {
+      this.dim = vector.length;
+      this.matrix = new Float32Array(this.capacity * this.dim);
+    }
+    if (vector.length !== this.dim) { this.invalidate(); return; }
+
+    let idx = this.rowIndexById.get(id);
+    if (idx === undefined) {
+      if (this.count >= this.capacity) this.grow();
+      idx = this.count;
+      this.rowIndexById.set(id, idx);
+      this.ids.push(id);
+      this.count++;
+    }
+    this.matrix.set(vector instanceof Float32Array ? vector : new Float32Array(vector), idx * this.dim);
+  }
+
+  /** Re-add a row by reading its vector back from the database. */
+  setFromDb(id: string): void {
+    if (!this.loaded) return;
+    try {
+      const row = this.getDb().prepare(this.getVectorSql).get(id) as { vector: Uint8Array } | undefined;
+      if (!row?.vector) return;
+      const vec = new Float32Array(row.vector.buffer, row.vector.byteOffset, row.vector.byteLength / 4);
+      this.set(id, vec);
+    } catch {
+      this.invalidate();
+    }
+  }
+
+  /** Remove a row (swap-with-last keeps the matrix dense). */
+  remove(id: string): void {
+    if (!this.loaded) return;
+    const idx = this.rowIndexById.get(id);
+    if (idx === undefined) return;
+
+    const last = this.count - 1;
+    if (idx !== last) {
+      this.matrix.copyWithin(idx * this.dim, last * this.dim, (last + 1) * this.dim);
+      const movedId = this.ids[last];
+      this.ids[idx] = movedId;
+      this.rowIndexById.set(movedId, idx);
+    }
+    this.ids.pop();
+    this.rowIndexById.delete(id);
+    this.count--;
+    this.maybeShrink();
+  }
+
+  /**
+   * Score all (or a filtered subset of) rows against the query vector and
+   * return the top K above the threshold, sorted by score descending.
+   * Vectors are unit-length, so the dot product IS the cosine similarity.
+   */
+  topK(query: number[] | Float32Array, k: number, threshold: number, allowedIds?: Set<string>): TopKResult[] {
+    this.ensureFresh();
+    if (this.count === 0 || this.dim === 0) return [];
+
+    const q = query instanceof Float32Array ? query : new Float32Array(query);
+    if (q.length !== this.dim || !q.every(Number.isFinite) || k < 1) return [];
+    const dim = this.dim;
+    const m = this.matrix;
+    const hits: TopKResult[] = [];
+
+    const selected = allowedIds && allowedIds.size < this.count / 2
+      ? [...allowedIds].map(id=>this.rowIndexById.get(id)).filter((r): r is number=>r !== undefined) : undefined;
+    for (let index = 0; index < (selected?.length ?? this.count); index++) {
+      const r = selected ? selected[index] : index;
+      if (allowedIds && !allowedIds.has(this.ids[r])) continue;
+      const base = r * dim;
+      let dot = 0;
+      for (let i = 0; i < dim; i++) dot += q[i] * m[base + i];
+      if (dot < threshold) continue;
+      const hit = { id: this.ids[r], score: dot };
+      if (hits.length < k) {
+        hits.push(hit);
+        let i = hits.length - 1;
+        while (i > 0) {
+          const parent = (i - 1) >> 1;
+          if (hits[parent].score <= hits[i].score) break;
+          [hits[parent], hits[i]] = [hits[i], hits[parent]];
+          i = parent;
+        }
+      } else if (dot > hits[0].score) {
+        hits[0] = hit;
+        let i = 0;
+        while (true) {
+          let child = i * 2 + 1;
+          if (child >= hits.length) break;
+          if (child + 1 < hits.length && hits[child + 1].score < hits[child].score) child++;
+          if (hits[i].score <= hits[child].score) break;
+          [hits[i], hits[child]] = [hits[child], hits[i]];
+          i = child;
+        }
+      }
+    }
+
+    hits.sort((a, b) => b.score - a.score);
+    return hits.length > k ? hits.slice(0, k) : hits;
+  }
+
+  size(): number {
+    this.ensureFresh();
+    return this.count;
+  }
+}