@jeffober/thatch 0.1.18 → 0.1.19

package/docs/qa/use-cases/UC-022-prediction-dedup.md

@@ -0,0 +1,19 @@
+# UC-022: Prediction create-on-existing (dedup + link)
+
+**Preconditions**
+- An opencode session with at least one existing prediction (from UC-021 or seeded directly)
+- The existing prediction's matcher context is semantically similar to a new observation
+
+**Steps**
+
+1. Seed a prediction: `prediction_update(matcher="reviewing a PR", prediction="go through findings one at a time using a todo list", signal="create")`.
+2. In the same or a new session, call `prediction_update(matcher="code review session", prediction="go through findings one at a time using a todo list", signal="create")`.
+3. Call `prediction_update(matcher="code review session", prediction="go through findings one at a time using a todo list", signal="confirm")`.
+4. Call `prediction_list` to inspect the model.
+
+**Expected**
+- Step 2: `findNearestPrediction` finds the existing prediction (cosine > 0.85). The tool returns `[linked]` (not `[created]`). The new matcher is linked via an edge. No duplicate prediction is created. Confidence is unchanged (create is confidence-neutral).
+- Step 3: Same prediction is found. The matcher edge already exists (ON CONFLICT DO NOTHING). Confidence is adjusted upward by the confirm signal. Returns `[confirm]` with updated confidence.
+- Step 4: `prediction_list` shows one prediction with two matchers ("reviewing a PR" and "code review session"), confidence reflecting one confirm, and provenance entries for both the create and confirm signals.
+
+_Automatable: yes — the create-on-existing path is tested in `tool-defs.test.ts` (prediction_update create on existing prediction links without disconfirming). The dedup + edge + confidence behavior is verified with assertions on the return value and prediction_list output._

package/docs/qa/use-cases/UC-023-prediction-confidence-model.md

@@ -0,0 +1,23 @@
+# UC-023: Prediction confidence and signal model
+
+**Preconditions**
+- An opencode or Claude Code / Cursor session with the prediction model seeded
+
+**Steps**
+
+1. `prediction_update(matcher="X", prediction="Y", signal="create")` — seeds at p0 (0.50, 0 evidence).
+2. `prediction_update(matcher="X", prediction="Y", signal="confirm")` — user confirmed.
+3. `prediction_update(matcher="X", prediction="Y", signal="soft")` — user partially disagreed.
+4. `prediction_update(matcher="X", prediction="Y", signal="disconfirm")` — user pushed back.
+5. `prediction_list` to inspect confidence and evidence counts.
+6. `prediction_query(context="X")` to query the model.
+
+**Expected**
+- Step 1: Returns `[created]`, confidence=0.50, counts (0/0).
+- Step 2: Returns `[confirm]`, confidence > 0.50. Formula: (1 + 5*0.5) / (1 + 0 + 5) = 0.583. Counts (1/0).
+- Step 3: Returns `[soft]`, confidence drops slightly. Soft adds 0.25 to disconfirm_count. Formula: (1 + 2.5) / (1 + 0.25 + 5) = 0.571. Counts (1/0.25).
+- Step 4: Returns `[disconfirm]`, confidence drops further. Formula: (1 + 2.5) / (1 + 1.25 + 5) = 0.524. Counts (1/1.25).
+- Step 5: `prediction_list` shows the prediction with accumulated provenance entries (create, confirm, soft, disconfirm) sorted newest-first.
+- Step 6: `prediction_query` returns the prediction with the current confidence and evidence count. Uses "you may prefer" for 0-evidence and "you tend to" for predictions with evidence. Threshold (0.45) filters out matchers below the relevance floor.
+
+_Automatable: yes — the confidence math and signal mapping are tested in `prediction.test.ts` (adjustConfidence confirm/disconfirm/soft/multiple) and `tool-defs.test.ts` (prediction_update confirm applies signal immediately)._

package/docs/qa/use-cases/UC-024-prediction-delete.md

@@ -0,0 +1,20 @@
+# UC-024: Prediction delete and provenance inspection
+
+**Preconditions**
+- An opencode or Claude Code / Cursor session with predictions in the model
+
+**Steps**
+
+1. Seed two predictions in the same store.
+2. `prediction_list` to see both predictions with matchers, confidence, and provenance.
+3. `prediction_delete(statement="first prediction text")` to remove one.
+4. `prediction_list` to verify only one prediction remains.
+5. `prediction_delete(statement="nonexistent prediction")` to test not-found handling.
+
+**Expected**
+- Step 2: Both predictions listed with confidence, evidence count, matchers (with weights), and provenance entries (signal type, detail, date).
+- Step 3: Returns `[deleted]` with the matched prediction's statement. Matching is semantic (cosine >= 0.85), not exact string match. Edges and provenance are cascade-deleted via FK ON DELETE CASCADE.
+- Step 4: Only the remaining prediction is listed. No orphaned edges or provenance entries.
+- Step 5: Returns "No prediction matching ... found" for a statement with no semantic match above threshold.
+
+_Automatable: yes — prediction_delete is tested in `tool-defs.test.ts` (found and not-found cases), and deletePrediction cascade is tested in `prediction.test.ts` (cascade to edges and provenance, non-existent ID)._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/db.ts

@@ -34,6 +34,46 @@ export interface DedupCandidate {
   score: number;
 }
 
+export interface MatcherRow {
+  id: string;
+  store: string;
+  description: string;
+  embedding: Uint8Array | null;
+  model: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface PredictionRow {
+  id: string;
+  store: string;
+  statement: string;
+  rationale: string | null;
+  confidence: number;
+  confirm_count: number;
+  disconfirm_count: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface PredictionNudgeItem {
+  confidence: number;
+  evidence_count: number;
+  matcher_description: string;
+  statement: string;
+}
+
+export interface ScoredPrediction {
+  matcher_id: string;
+  matcher_description: string;
+  prediction_id: string;
+  statement: string;
+  confidence: number;
+  evidence_count: number;
+  score: number;
+  rationale: string | null;
+}
+
 /**
  * SQLite-backed store for thatch. All stores live in a single database
  * partitioned by a `store` column. Embeddings are raw Float32Array bytes
@@ -46,6 +86,12 @@ export class ThatchDB {
     this.#db = new Database(path, { create: true });
     this.#db.run("PRAGMA journal_mode = WAL");
     this.#db.run("PRAGMA busy_timeout = 5000");
+    // Enforce FK constraints per connection. The prediction tables use
+    // ON DELETE CASCADE for edges and provenance; enabling this pragma
+    // ensures those cascades fire. Also enforces the entries table's
+    // existing FK to stores(name), which was declarative but unenforced
+    // before this branch.
+    this.#db.run("PRAGMA foreign_keys = ON");
     this.#initSchema();
   }
 
@@ -90,6 +136,57 @@ export class ThatchDB {
       )
     `);
 
+    this.#db.run(`
+      CREATE TABLE IF NOT EXISTS prediction_matchers (
+        id          TEXT PRIMARY KEY,
+        store       TEXT NOT NULL REFERENCES stores(name),
+        description TEXT NOT NULL,
+        embedding   BLOB,
+        model       TEXT,
+        created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+        updated_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+      )
+    `);
+
+    this.#db.run(`
+      CREATE TABLE IF NOT EXISTS predictions (
+        id              TEXT PRIMARY KEY,
+        store           TEXT NOT NULL REFERENCES stores(name),
+        statement       TEXT NOT NULL,
+        rationale       TEXT,
+        embedding       BLOB,
+        model           TEXT,
+        confidence      REAL NOT NULL DEFAULT 0.5,
+        confirm_count   REAL NOT NULL DEFAULT 0,
+        disconfirm_count REAL NOT NULL DEFAULT 0,
+        created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+        updated_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+      )
+    `);
+
+    this.#db.run(`
+      CREATE TABLE IF NOT EXISTS prediction_edges (
+        matcher_id    TEXT NOT NULL,
+        prediction_id TEXT NOT NULL,
+        weight        REAL NOT NULL DEFAULT 1.0,
+        created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+        PRIMARY KEY (matcher_id, prediction_id),
+        FOREIGN KEY (matcher_id) REFERENCES prediction_matchers(id) ON DELETE CASCADE,
+        FOREIGN KEY (prediction_id) REFERENCES predictions(id) ON DELETE CASCADE
+      )
+    `);
+
+    this.#db.run(`
+      CREATE TABLE IF NOT EXISTS prediction_provenance (
+        id            TEXT PRIMARY KEY,
+        prediction_id TEXT NOT NULL,
+        signal        TEXT NOT NULL,
+        detail        TEXT,
+        created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+        FOREIGN KEY (prediction_id) REFERENCES predictions(id) ON DELETE CASCADE
+      )
+    `);
+
     this.#db.run("INSERT OR IGNORE INTO stores (name) VALUES ('global')");
 
     this.#migrateColumns();
@@ -456,6 +553,383 @@ export class ThatchDB {
     return new Set(rows.map((r: any) => [r.slug_a, r.slug_b].sort().join("|")));
   }
 
+  // ---------------------------------------------------------------------------
+  // Prediction engine: matchers, predictions, edges, provenance
+  // ---------------------------------------------------------------------------
+
+  // Bayesian confidence model constants. The posterior is:
+  //   p = (confirm_count + K * P0) / (confirm_count + disconfirm_count + K)
+  // K is the prior strength (pseudo-evidence count): K=5 means 5
+  // pseudo-evidence "anchors" the prior. P0 is the prior probability
+  // (p=0.5 = "no preference either way"). W_SOFT is the fractional
+  // weight for a soft (weak) signal: 0.25 means a soft disconfirm counts
+  // as 1/4 of a full disconfirm.
+  static readonly PREDICTION_K = 5;
+  static readonly PREDICTION_P0 = 0.5;
+  static readonly PREDICTION_W_SOFT = 0.25;
+
+  /**
+   * Brute-force cosine search over the matchers table for auto-fire.
+   * Returns matchers ranked by similarity to the query embedding,
+   * filtered by a noise floor (cosine >= 0.01) to exclude near-zero
+   * and negative scores, and by model-space compatibility (dimension
+   * match). Callers apply the actual relevance threshold (0.45 for
+   * auto-fire in index.ts, caller-specified for sideband).
+   */
+  findMatchers(
+    stores: string[],
+    queryEmbedding: Float32Array,
+    opts?: { limit?: number },
+  ): { id: string; description: string; score: number }[] {
+    if (stores.length === 0) return [];
+    const limit = opts?.limit ?? 5;
+    const placeholders = stores.map(() => "?").join(", ");
+    const rows = this.#db
+      .query(
+        `SELECT id, description, embedding FROM prediction_matchers
+         WHERE store IN (${placeholders}) AND embedding IS NOT NULL`,
+      )
+      .all(...(stores as [string, ...string[]])) as any[];
+
+    const scored: { id: string; description: string; score: number }[] = [];
+    for (const r of rows) {
+      const emb = blobToVector(r.embedding);
+      if (emb.length !== queryEmbedding.length) continue;
+      const score = cosineSimilarity(queryEmbedding, emb);
+      if (score >= 0.01) {
+        scored.push({ id: r.id, description: r.description, score: Math.round(score * 1000) / 1000 });
+      }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit);
+  }
+
+  /**
+   * Follows edges from matchers to scored predictions. Returns all
+   * predictions reachable from any matching matcher, ranked by
+   * cosine * weight * confidence.
+   */
+  scorePredictions(
+    matchers: { id: string; description: string; score: number }[],
+  ): ScoredPrediction[] {
+    if (matchers.length === 0) return [];
+    const matcherIds = matchers.map((m) => m.id);
+    const placeholders = matcherIds.map(() => "?").join(", ");
+    const rows = this.#db
+      .query(
+        `SELECT p.id, p.statement, p.rationale, p.confidence, p.confirm_count, p.disconfirm_count,
+                e.matcher_id, e.weight
+         FROM prediction_edges e
+         JOIN predictions p ON e.prediction_id = p.id
+         WHERE e.matcher_id IN (${placeholders})
+         ORDER BY p.statement`,
+      )
+      .all(...(matcherIds as [string, ...string[]])) as any[];
+
+    const matcherMap = new Map(matchers.map((m) => [m.id, m]));
+    const scored: ScoredPrediction[] = [];
+    for (const r of rows) {
+      const matcher = matcherMap.get(r.matcher_id);
+      if (!matcher) continue;
+
+      const confidence = r.confidence as number;
+      const evidence = Math.round(r.confirm_count + r.disconfirm_count);
+      const score = matcher.score * (r.weight as number) * confidence;
+      scored.push({
+        matcher_id: r.matcher_id,
+        matcher_description: matcher.description,
+        prediction_id: r.id,
+        statement: r.statement,
+        confidence: Math.round(confidence * 1000) / 1000,
+        evidence_count: evidence,
+        score: Math.round(score * 1000) / 1000,
+        rationale: r.rationale,
+      });
+    }
+    scored.sort((a, b) => b.score - a.score);
+
+    // Dedup by prediction_id: multiple matchers may link to the same
+    // prediction via separate edges. Keep only the highest-scoring
+    // entry per prediction so the nudge doesn't repeat the same
+    // prediction with different matcher contexts.
+    const seen = new Set<string>();
+    return scored.filter((s) => {
+      if (seen.has(s.prediction_id)) return false;
+      seen.add(s.prediction_id);
+      return true;
+    });
+  }
+
+  /**
+   * Full scoring pipeline for auto-fire and sideband: findMatchers,
+   * filter by threshold, scorePredictions (which includes dedup by
+   * prediction_id), slice, and map to PredictionNudgeItem. Shared by
+   * index.ts (auto-fire) and sideband.ts (MCP path) to prevent
+   * scoring-logic drift between the two host paths.
+   */
+  scorePredictionNudge(
+    stores: string[],
+    embedding: Float32Array,
+    threshold: number,
+    limit = 5,
+  ): PredictionNudgeItem[] {
+    const matchers = this.findMatchers(stores, embedding, { limit })
+      .filter((m) => m.score >= threshold);
+    if (matchers.length === 0) return [];
+    return this.scorePredictions(matchers)
+      .slice(0, limit)
+      .map((s) => ({
+        confidence: s.confidence,
+        evidence_count: s.evidence_count,
+        matcher_description: s.matcher_description,
+        statement: s.statement,
+      }));
+  }
+
+  /**
+   * Finds the nearest matcher by cosine similarity above a caller-
+   * specified threshold. Used for dedup at prediction_update time
+   * (threshold 0.85), not auto-fire (use findMatchers for that).
+   */
+  findNearestMatcher(
+    store: string,
+    embedding: Float32Array,
+    threshold: number,
+  ): MatcherRow | null {
+    const rows = this.#db
+      .query("SELECT id, store, description, embedding, model, created_at, updated_at FROM prediction_matchers WHERE store = ? AND embedding IS NOT NULL")
+      .all(store) as any[];
+
+    let best: { row: any; score: number } | null = null;
+    for (const r of rows) {
+      const emb = blobToVector(r.embedding);
+      if (emb.length !== embedding.length) continue;
+      const score = cosineSimilarity(embedding, emb);
+      if (score >= threshold && (!best || score > best.score)) {
+        best = { row: r, score };
+      }
+    }
+    if (!best) return null;
+    return best.row as MatcherRow;
+  }
+
+  /** Creates a new matcher (context pattern) in the store, returning its id. */
+  createMatcher(
+    store: string,
+    description: string,
+    embedding: Float32Array,
+    model: string,
+  ): string {
+    this.ensureStore(store);
+    const id = crypto.randomUUID();
+    const blob = new Uint8Array(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+    const now = new Date().toISOString();
+    this.#db.run(
+      "INSERT INTO prediction_matchers (id, store, description, embedding, model, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
+      [id, store, description, blob, model, now, now] as any,
+    );
+    return id;
+  }
+
+  /**
+   * Finds the nearest prediction by cosine similarity across the
+   * entire store (not scoped to a single matcher's edges). This
+   * prevents duplicate predictions: when a new matcher is created,
+   * it can link to an existing prediction via a new edge rather
+   * than creating a second row with the same statement.
+   */
+  findNearestPrediction(
+    store: string,
+    embedding: Float32Array,
+    threshold: number,
+  ): PredictionRow | null {
+    const rows = this.#db
+      .query(
+        `SELECT id, store, statement, rationale, confidence, confirm_count, disconfirm_count, created_at, updated_at, embedding
+         FROM predictions
+         WHERE store = ? AND embedding IS NOT NULL`,
+      )
+      .all(store) as any[];
+
+    let best: { row: any; score: number } | null = null;
+    for (const r of rows) {
+      const emb = blobToVector(r.embedding);
+      if (emb.length !== embedding.length) continue;
+      const score = cosineSimilarity(embedding, emb);
+      if (score >= threshold && (!best || score > best.score)) {
+        best = { row: r, score };
+      }
+    }
+    if (!best) return null;
+    const { embedding: _, ...rest } = best.row;
+    return rest as PredictionRow;
+  }
+
+  /**
+   * Creates a new prediction, returning its id. Confidence is seeded
+   * at p0 (the population prior).
+   */
+  createPrediction(
+    store: string,
+    statement: string,
+    rationale: string,
+    embedding: Float32Array,
+    model: string,
+  ): string {
+    this.ensureStore(store);
+    const id = crypto.randomUUID();
+    const blob = new Uint8Array(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+    const now = new Date().toISOString();
+    this.#db.run(
+      `INSERT INTO predictions (id, store, statement, rationale, embedding, model, confidence, confirm_count, disconfirm_count, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 0, 0, ?, ?)`,
+      [id, store, statement, rationale, blob, model, ThatchDB.PREDICTION_P0, now, now] as any,
+    );
+    return id;
+  }
+
+  /** Ensures an edge links a matcher to a prediction. Does not overwrite existing edge weight. */
+  createEdge(matcherId: string, predictionId: string, weight: number): void {
+    const now = new Date().toISOString();
+    this.#db.run(
+      `INSERT INTO prediction_edges (matcher_id, prediction_id, weight, created_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(matcher_id, prediction_id) DO NOTHING`,
+      [matcherId, predictionId, weight, now] as any,
+    );
+  }
+
+/**
+   * Adjusts a prediction's confidence by applying a signal, then
+   * recomputing the Bayesian posterior. Mirrors samskara's
+   * samskara_apply_evaluation: discount prior evidence is NOT applied
+   * in v1 (no wall-clock decay), so counts accumulate monotonically.
+   *
+   * Signal mapping: "confirm" adds 1 to confirm_count; "disconfirm"
+   * adds 1 to disconfirm_count; "soft" adds W_SOFT (0.25) to
+   * disconfirm_count. The asymmetry (soft is a weak disconfirm, not
+   * a weak confirm) is intentional: a soft signal means the user
+   * partially disagreed, not partially agreed. There is no soft
+   * confirm; use "confirm" for weak agreement.
+   */
+  adjustConfidence(predictionId: string, signal: "confirm" | "disconfirm" | "soft"): void {
+    const deltaConfirm = signal === "confirm" ? 1 : 0;
+    const deltaDisconfirm = signal === "disconfirm" ? 1 : (signal === "soft" ? ThatchDB.PREDICTION_W_SOFT : 0);
+    const k = ThatchDB.PREDICTION_K;
+    const p0 = ThatchDB.PREDICTION_P0;
+    const now = new Date().toISOString();
+    // Atomic UPDATE: uses the OLD column values in the confidence
+    // expression, so (confirm_count + deltaConfirm) equals the new
+    // confirm_count. No read-modify-write race between connections.
+    this.#db.run(
+      `UPDATE predictions
+       SET confirm_count = confirm_count + ?,
+           disconfirm_count = disconfirm_count + ?,
+           confidence = (confirm_count + ? + ? * ?) / (confirm_count + ? + disconfirm_count + ? + ?),
+           updated_at = ?
+       WHERE id = ?`,
+      [deltaConfirm, deltaDisconfirm, deltaConfirm, k, p0, deltaConfirm, deltaDisconfirm, k, now, predictionId] as any,
+    );
+  }
+
+  /**
+   * Returns the population prior p0 for a store. Falls back to
+   * PREDICTION_P0 (0.5) when total evidence < 20; otherwise returns
+   * confirm_count / total_evidence. v2 feature: not yet wired into
+   * createPrediction, which uses flat PREDICTION_P0. v1 uses the
+   * flat prior until enough evidence exists to derive a population rate.
+   */
+  populationP0(store: string): number {
+    const row = this.#db
+      .query(
+        `SELECT SUM(confirm_count) AS c, SUM(disconfirm_count) AS d FROM predictions WHERE store = ?`,
+      )
+      .get(store) as { c: number | null; d: number | null } | null;
+    const total = (row?.c ?? 0) + (row?.d ?? 0);
+    if (total < 20) return ThatchDB.PREDICTION_P0;
+    return row!.c! / total;
+  }
+
+  /**
+   * Returns a prediction's metadata by id. Does not return the
+   * embedding/model columns (creation-only, used by findNearestPrediction
+   * for dedup at write time, not needed for display or scoring).
+   */
+  getPrediction(predictionId: string): PredictionRow | null {
+    const row = this.#db
+      .query(
+        "SELECT id, store, statement, rationale, confidence, confirm_count, disconfirm_count, created_at, updated_at FROM predictions WHERE id = ?",
+      )
+      .get(predictionId) as any;
+    if (!row) return null;
+    return row as PredictionRow;
+  }
+
+  /**
+   * Records a provenance entry (signal type + detail) for a prediction.
+   * Provenance is an audit trail for the inspector and agent.
+   */
+  addProvenance(predictionId: string, signal: string, detail: string): void {
+    const id = crypto.randomUUID();
+    this.#db.run(
+      "INSERT INTO prediction_provenance (id, prediction_id, signal, detail) VALUES (?, ?, ?, ?)",
+      [id, predictionId, signal, detail] as any,
+    );
+  }
+
+  /** Returns recent provenance entries for a prediction (newest first). */
+  getProvenance(predictionId: string): { signal: string; detail: string | null; created_at: string }[] {
+    return this.#db
+      .query("SELECT signal, detail, created_at FROM prediction_provenance WHERE prediction_id = ? ORDER BY rowid DESC LIMIT 10")
+      .all(predictionId) as any[];
+  }
+
+  /** Deletes a prediction. Edges and provenance cascade via FK ON DELETE CASCADE. */
+  deletePrediction(predictionId: string): boolean {
+    const result = this.#db.run("DELETE FROM predictions WHERE id = ?", [predictionId]);
+    return result.changes > 0;
+  }
+
+  /** Lists all predictions with their matchers, for the inspector. */
+  listPredictions(store: string): {
+    id: string;
+    statement: string;
+    rationale: string | null;
+    confidence: number;
+    evidence_count: number;
+    matchers: { id: string; description: string; weight: number }[];
+  }[] {
+    const predRows = this.#db
+      .query(
+        `SELECT id, statement, rationale, confidence, confirm_count, disconfirm_count
+         FROM predictions WHERE store = ? ORDER BY confidence DESC`,
+      )
+      .all(store) as any[];
+
+    return predRows.map((p) => {
+      const edgeRows = this.#db
+        .query(
+          `SELECT e.matcher_id, e.weight, m.description
+           FROM prediction_edges e
+           JOIN prediction_matchers m ON e.matcher_id = m.id
+           WHERE e.prediction_id = ?`,
+        )
+        .all(p.id) as any[];
+      return {
+        id: p.id,
+        statement: p.statement,
+        rationale: p.rationale,
+        confidence: Math.round(p.confidence * 1000) / 1000,
+        evidence_count: Math.round(p.confirm_count + p.disconfirm_count),
+        matchers: edgeRows.map((e) => ({
+          id: e.matcher_id,
+          description: e.description,
+          weight: e.weight,
+        })),
+      };
+    });
+  }
+
   // ---------------------------------------------------------------------------
   // Hygiene — signals for the session-start heartbeat. Staleness means
   // neither written nor recalled since the cutoff; recall telemetry keeps
@@ -501,6 +975,12 @@ export class ThatchDB {
     );
   }
 
+  /** Runs fn inside a SQLite transaction (BEGIN/COMMIT/ROLLBACK). */
+  transaction<T>(fn: () => T): T {
+    const t = this.#db.transaction(fn);
+    return t();
+  }
+
   close(): void {
     this.#db.close();
   }