soulbridge 0.0.26 → 0.0.98

package/dist/packages/core/src/sqlite.js

@@ -6,11 +6,13 @@
  * Older databases are upgraded in place after a one-off backup; a database
  * from a newer binary is refused instead of being silently written.
  */
-import { copyFileSync, existsSync } from 'node:fs';
+import { copyFileSync, existsSync, renameSync } from 'node:fs';
 import { DatabaseSync } from 'node:sqlite';
 import { DEFAULT_EMOTION } from './types.js';
+import { FACT_STATUS, MEMORY_STATUS } from './config/status.js';
+import { LEGACY_ROLE_BY_TYPE } from './config/domains.js';
 import { bm25, buildCorpusStats, tokenize } from './scoring.js';
-export const SCHEMA_VERSION = 4;
+export const SCHEMA_VERSION = 9;
 /** How many recent pairs are considered before scoring. Bounded so recall stays O(candidates). */
 const RECALL_CANDIDATES = 500;
 export const AFFECT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
@@ -106,6 +108,130 @@ CREATE INDEX IF NOT EXISTS idx_turn_pairs_scope ON turn_pairs(soul_id, user_id,
 -- Idempotency: one exchange per (session, turn). A repeat is ignored, not merged.
 CREATE UNIQUE INDEX IF NOT EXISTS idx_turn_pairs_turn
   ON turn_pairs(soul_id, user_id, session_id, turn);
+
+-- v5: a turn is the unit of memory; its steps are the shape (briefs/0014).
+-- assistant_text stays denormalized so recall keeps one row per turn.
+CREATE TABLE IF NOT EXISTS turns (
+  id             TEXT PRIMARY KEY,
+  soul_id        TEXT NOT NULL,
+  user_id        TEXT NOT NULL,
+  session_id     TEXT NOT NULL,
+  turn_no        INTEGER NOT NULL,
+  started_at     INTEGER NOT NULL,
+  ended_at       INTEGER,
+  user_text      TEXT NOT NULL,
+  assistant_text TEXT NOT NULL DEFAULT '',
+  outcome        TEXT,
+  status         TEXT NOT NULL DEFAULT 'closed',
+  created_at     INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_turns_scope ON turns(soul_id, user_id, started_at DESC);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_turns_turn
+  ON turns(soul_id, user_id, session_id, turn_no);
+
+CREATE TABLE IF NOT EXISTS steps (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  turn_id           TEXT NOT NULL,
+  idx               INTEGER NOT NULL,
+  kind              TEXT NOT NULL,
+  text              TEXT,
+  tool_name         TEXT,
+  tool_args_chars   INTEGER,
+  tool_result_chars INTEGER,
+  ok                INTEGER,
+  at                INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_steps_turn ON steps(turn_id, idx);
+
+-- v6: the model proper (spec/model.v0.md). A fact is a connection; slots are
+-- its ends; gaps are the connections that have not happened yet.
+CREATE TABLE IF NOT EXISTS entities (
+  id                TEXT PRIMARY KEY,
+  soul_id           TEXT NOT NULL,
+  user_id           TEXT NOT NULL,
+  type              TEXT NOT NULL,
+  name              TEXT NOT NULL,
+  aliases           TEXT NOT NULL DEFAULT '[]',
+  attrs             TEXT NOT NULL DEFAULT '{}',
+  first_seen_at     INTEGER NOT NULL,
+  last_mentioned_at INTEGER NOT NULL,
+  created_at        INTEGER NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_entities_name
+  ON entities(soul_id, user_id, type, name);
+CREATE INDEX IF NOT EXISTS idx_entities_recent
+  ON entities(soul_id, user_id, last_mentioned_at DESC);
+
+CREATE TABLE IF NOT EXISTS facts (
+  id             TEXT PRIMARY KEY,
+  soul_id        TEXT NOT NULL,
+  user_id        TEXT NOT NULL,
+  statement      TEXT NOT NULL,
+  type_name      TEXT,
+  role           TEXT NOT NULL DEFAULT 'observation',
+  holder         TEXT NOT NULL DEFAULT 'world',
+  at             INTEGER,
+  at_text        TEXT,
+  at_end         INTEGER,
+  at_precision   TEXT NOT NULL DEFAULT 'unknown',
+  place_id       TEXT,
+  status         TEXT NOT NULL DEFAULT 'none',
+  confidence     REAL NOT NULL DEFAULT 1,
+  source         TEXT NOT NULL DEFAULT 'experienced',
+  source_turn_id TEXT,
+  superseded_by  TEXT,
+  created_at     INTEGER NOT NULL,
+  recall_count   INTEGER NOT NULL DEFAULT 0,
+  last_recalled_at INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_facts_scope ON facts(soul_id, user_id, at DESC);
+CREATE INDEX IF NOT EXISTS idx_facts_status ON facts(soul_id, user_id, status);
+CREATE INDEX IF NOT EXISTS idx_facts_created ON facts(soul_id, user_id, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS fact_slots (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  fact_id     TEXT NOT NULL,
+  slot        TEXT NOT NULL,
+  value_type  TEXT NOT NULL,
+  entity_id   TEXT,
+  value_num   REAL,
+  value_text  TEXT,
+  ref_fact_id TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_fact_slots_fact ON fact_slots(fact_id);
+CREATE INDEX IF NOT EXISTS idx_fact_slots_entity ON fact_slots(entity_id);
+
+CREATE TABLE IF NOT EXISTS gaps (
+  id                TEXT PRIMARY KEY,
+  soul_id           TEXT NOT NULL,
+  user_id           TEXT NOT NULL,
+  about_entity_id   TEXT,
+  about_fact_id     TEXT,
+  topic             TEXT NOT NULL,
+  tension           REAL NOT NULL DEFAULT 0,
+  status            TEXT NOT NULL DEFAULT 'open',
+  opened_at         INTEGER NOT NULL,
+  closed_at         INTEGER,
+  closed_by_fact_id TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_gaps_open ON gaps(soul_id, user_id, status, tension DESC);
+
+-- A topic is a thread, not a segment: its turns need not be adjacent, because a
+-- conversation can interleave (A B A) and come back. Consolidation runs when a
+-- thread closes, not when a batch of facts fills up.
+CREATE TABLE IF NOT EXISTS threads (
+  id          TEXT PRIMARY KEY,
+  soul_id     TEXT NOT NULL,
+  user_id     TEXT NOT NULL,
+  session_id  TEXT NOT NULL,
+  topic       TEXT NOT NULL,
+  status      TEXT NOT NULL DEFAULT 'open',
+  opened_at   INTEGER NOT NULL,
+  closed_at   INTEGER,
+  last_turn_no INTEGER,
+  summary_fact_id TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_threads_open ON threads(soul_id, user_id, status, opened_at DESC);
 `;
 const sleepSync = (ms) => {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
@@ -167,22 +293,126 @@ function upgradeToV3(db) {
   )`);
     db.exec('CREATE INDEX IF NOT EXISTS idx_corrections ON corrections(soul_id, user_id, at DESC)');
 }
+/**
+ * v3/v4 → v5: turns become the unit of memory (briefs/0014). Existing exchanges
+ * are copied across as turns with a single text step, so nothing is lost; the
+ * old table stays as a read-only legacy copy.
+ */
+/** v6 → v7: turn threads (a topic's turns need not be adjacent) plus turns.thread_id. */
+export function upgradeToV9(db) {
+    // Time became locatability (ADR 0032): a fact may be known to exist without a
+    // date, and that is a value — unknown — not a reason to discard it.
+    ensureColumn(db, 'facts', 'at_precision', "TEXT NOT NULL DEFAULT 'unknown'");
+    // What a fact is *for* (config/domains.ts FACT_ROLES). Backfill from the old type label so
+    // rows written before this column still reach the right consumer.
+    ensureColumn(db, 'facts', 'role', "TEXT NOT NULL DEFAULT 'observation'");
+}
+export function upgradeToV8(db) {
+    // What decays is the chance of being recalled, so the store has to know how
+    // often and how recently that happened (0019).
+    ensureColumn(db, 'facts', 'recall_count', 'INTEGER NOT NULL DEFAULT 0');
+    ensureColumn(db, 'facts', 'last_recalled_at', 'INTEGER');
+    db.exec('CREATE INDEX IF NOT EXISTS idx_facts_created ON facts(soul_id, user_id, created_at DESC)');
+}
+export function upgradeToV7(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS threads (
+    id          TEXT PRIMARY KEY,
+    soul_id     TEXT NOT NULL,
+    user_id     TEXT NOT NULL,
+    session_id  TEXT NOT NULL,
+    topic       TEXT NOT NULL,
+    status      TEXT NOT NULL DEFAULT 'open',
+    opened_at   INTEGER NOT NULL,
+    closed_at   INTEGER,
+    last_turn_no INTEGER,
+    summary_fact_id TEXT
+  )`);
+    db.exec('CREATE INDEX IF NOT EXISTS idx_threads_open ON threads(soul_id, user_id, status, opened_at DESC)');
+    ensureColumn(db, 'turns', 'thread_id', 'TEXT');
+}
+export function upgradeToV5(db) {
+    const hasLegacy = db
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'turn_pairs'")
+        .get();
+    if (!hasLegacy)
+        return;
+    const rows = db.prepare('SELECT * FROM turn_pairs').all();
+    const insertTurn = db.prepare(`INSERT OR IGNORE INTO turns
+       (id, soul_id, user_id, session_id, turn_no, started_at, ended_at,
+        user_text, assistant_text, outcome, status, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 'closed', ?)`);
+    const insertStep = db.prepare("INSERT INTO steps (turn_id, idx, kind, text, at) VALUES (?, 0, 'text', ?, ?)");
+    for (const row of rows) {
+        const id = String(row.id);
+        const assistant = String(row.assistant_text ?? '');
+        const inserted = insertTurn.run(id, String(row.soul_id), String(row.user_id), String(row.session_id), Number(row.turn), Number(row.at), Number(row.at), String(row.user_text), assistant, Number(row.created_at));
+        // Only a freshly inserted turn gets a step. The migration can be re-run after an
+        // interruption before the version bump, and steps has no unique key — writing it
+        // unconditionally appended a second copy of the same reply on every retry.
+        if (Number(inserted.changes) > 0 && assistant.length > 0)
+            insertStep.run(id, assistant, Number(row.at));
+    }
+}
 /**
  * Copy the database aside before a schema upgrade.
  *
- * In WAL mode the most recent commits can live in the `-wal` sidecar, so a copy
- * of the main file alone can be missing data exactly when it matters. Checkpoint
- * first (TRUNCATE moves the WAL back into the main file and empties it), then
- * copy. Exported for the upgrade test.
+ * The backup is the only way back from a bad migration, so it has to be *valid*,
+ * not merely present. Two failures were possible before: a plain file copy after
+ * `wal_checkpoint(TRUNCATE)` dropped the newest commits when another connection
+ * pinned an old snapshot (the checkpoint returns busy and only partially flushes,
+ * and that return value was ignored), and an existing backup file was trusted
+ * forever even if it was the broken one from an earlier attempt.
+ *
+ * `VACUUM INTO` reads through the WAL and writes a consistent snapshot regardless
+ * of other readers, so it is the primary path; a checkpoint+copy remains as the
+ * fallback, and whatever it produces is opened and integrity-checked. A copy that
+ * fails its own check is moved aside (kept for forensics) and the upgrade refuses
+ * to run — a corrupt backup is worse than none, because it is the one thing we
+ * would trust when everything else failed.
+ *
+ * Exported for the upgrade test.
  */
 export function backupBeforeUpgrade(db, file, from) {
     if (file === ':memory:' || !existsSync(file))
         return;
     const backup = `${file}.bak-v${from}`;
-    if (existsSync(backup))
-        return;
-    db.exec('PRAGMA wal_checkpoint(TRUNCATE);');
-    copyFileSync(file, backup);
+    if (existsSync(backup)) {
+        if (integrityOf(backup))
+            return;
+        const corrupt = `${backup}.corrupt-${Date.now()}`;
+        renameSync(backup, corrupt);
+        throw new Error(`existing backup ${backup} is not readable; moved aside to ${corrupt}`);
+    }
+    try {
+        // Quotes are escaped because the path is spliced into SQL; VACUUM INTO takes a
+        // string expression, and binding it is not supported on every SQLite build.
+        db.exec(`VACUUM INTO '${backup.replace(/'/g, "''")}'`);
+    }
+    catch {
+        db.exec('PRAGMA wal_checkpoint(TRUNCATE);');
+        copyFileSync(file, backup);
+    }
+    if (!integrityOf(backup)) {
+        const corrupt = `${backup}.corrupt-${Date.now()}`;
+        renameSync(backup, corrupt);
+        throw new Error(`backup for schema v${from} failed its integrity check (kept at ${corrupt})`);
+    }
+}
+/** Does this file open and report `integrity_check = ok`? */
+function integrityOf(file) {
+    try {
+        const copy = new DatabaseSync(file, { readOnly: true });
+        try {
+            const row = copy.prepare('PRAGMA integrity_check').get();
+            return row.integrity_check === 'ok';
+        }
+        finally {
+            copy.close();
+        }
+    }
+    catch {
+        return false;
+    }
 }
 export function openSqlite(file) {
     const db = new DatabaseSync(file);
@@ -196,11 +426,38 @@ export function openSqlite(file) {
     }
     if (version < SCHEMA_VERSION) {
         backupBeforeUpgrade(db, file, version);
-        if (version < 2)
-            upgradeToV2(db);
-        if (version < 3)
-            upgradeToV3(db);
-        setVersion(db, SCHEMA_VERSION);
+        // All upgrades and the version bump commit together. Before this, an interruption
+        // left the version at the old value with half the migration applied, so the next
+        // open re-ran it against its own output (v5 appended duplicate steps).
+        // VACUUM INTO in the backup runs before the transaction: it cannot run inside one.
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            if (version < 2)
+                upgradeToV2(db);
+            if (version < 3)
+                upgradeToV3(db);
+            if (version < 5)
+                upgradeToV5(db);
+            if (version < 7)
+                upgradeToV7(db);
+            if (version < 8)
+                upgradeToV8(db);
+            if (version < 9)
+                upgradeToV9(db);
+            // v6 adds tables only; SCHEMA creates them on every open, nothing to copy.
+            setVersion(db, SCHEMA_VERSION);
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch {
+                /* the error below is the one worth reporting */
+            }
+            db.close();
+            throw error;
+        }
     }
     const stmtPut = db.prepare(`
     INSERT INTO memories (
@@ -298,11 +555,25 @@ export function openSqlite(file) {
             if (!replacement)
                 return false;
             const result = withRetry(() => db
-                .prepare(`UPDATE memories SET status = 'superseded', superseded_by = ?, updated_at = ?
-             WHERE id = ? AND status = 'active' AND deleted_at IS NULL`)
+                .prepare(`UPDATE memories SET status = '${MEMORY_STATUS.superseded}', superseded_by = ?, updated_at = ?
+             WHERE id = ? AND status = '${MEMORY_STATUS.active}' AND deleted_at IS NULL`)
                 .run(newId, now, oldId));
             return Number(result.changes ?? 0) > 0;
         },
+        /**
+         * Retire a legacy memory pointing at something outside this table.
+         *
+         * `supersede()` requires the replacement to be a memory, which is right while the
+         * table is live. The migration replaces rows with facts, so it needs the same
+         * bookkeeping without that check — the row stays for audit, the pointer is kept.
+         */
+        retireMemory(oldId, replacedBy, now = Date.now()) {
+            const result = withRetry(() => db
+                .prepare(`UPDATE memories SET status = '${MEMORY_STATUS.superseded}', superseded_by = ?, updated_at = ?
+             WHERE id = ? AND status = '${MEMORY_STATUS.active}' AND deleted_at IS NULL`)
+                .run(replacedBy ?? null, now, oldId));
+            return Number(result.changes ?? 0) > 0;
+        },
         saveAffect(soulId, userId, signal, at, deviceId) {
             withRetry(() => {
                 db.prepare(`INSERT OR IGNORE INTO affect_samples
@@ -367,24 +638,526 @@ export function openSqlite(file) {
                 .get(soulId, userId);
             return Number(row.n);
         },
-        putTurnPair(pair) {
+        putTurn(spec) {
             // INSERT OR IGNORE + the unique index is the whole idempotency story:
-            // one exchange per (session, turn), repeats are dropped, never merged.
+            // one turn per (session, turn_no); repeats are dropped, never merged.
+            const id = spec.id ?? `tn_${spec.sessionId}_${spec.turnNo}`;
+            const createdAt = spec.createdAt ?? spec.startedAt;
+            const assistantText = spec.steps
+                .filter((step) => step.kind === 'text' && typeof step.text === 'string')
+                .map((step) => step.text)
+                .join('\n');
+            withRetry(() => {
+                const inserted = db
+                    .prepare(`INSERT OR IGNORE INTO turns
+               (id, soul_id, user_id, session_id, turn_no, started_at, ended_at,
+                user_text, assistant_text, outcome, status, created_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(id, spec.soulId, spec.userId, spec.sessionId, spec.turnNo, spec.startedAt, spec.endedAt ?? spec.startedAt, spec.userText, assistantText, spec.outcome ?? null, spec.status ?? 'closed', createdAt);
+                // Steps are rewritten whenever the turn is written, so a retry after a
+                // partial write converges on the same shape instead of duplicating.
+                if (Number(inserted.changes) > 0) {
+                    const insertStep = db.prepare(`INSERT INTO steps (turn_id, idx, kind, text, tool_name, tool_args_chars,
+                                tool_result_chars, ok, at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+                    for (const step of spec.steps) {
+                        insertStep.run(id, step.idx, step.kind, step.text ?? null, step.toolName ?? null, step.toolArgsChars ?? null, step.toolResultChars ?? null, step.ok === undefined ? null : step.ok ? 1 : 0, step.at);
+                    }
+                }
+            });
+        },
+        findTurns(spec) {
+            // Substring match, deliberately not the tokenizer: an exhaustive fetch is
+            // a filter, and CJK bigrams would miss short needle text (eval-boundary-0027).
+            const where = ['soul_id = ?', 'user_id = ?'];
+            const args = [spec.soulId, spec.userId];
+            if (spec.text) {
+                const needle = `%${spec.text.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+                where.push("(user_text LIKE ? ESCAPE '\\' OR assistant_text LIKE ? ESCAPE '\\')");
+                args.push(needle, needle);
+            }
+            if (spec.sessionId) {
+                where.push('session_id = ?');
+                args.push(spec.sessionId);
+            }
+            if (spec.since !== undefined) {
+                where.push('started_at >= ?');
+                args.push(spec.since);
+            }
+            if (spec.until !== undefined) {
+                where.push('started_at <= ?');
+                args.push(spec.until);
+            }
+            const clause = where.join(' AND ');
+            const total = Number(db.prepare(`SELECT COUNT(*) AS n FROM turns WHERE ${clause}`).get(...args).n);
+            const limit = spec.limit ?? 200;
+            const rows = db
+                .prepare(`SELECT * FROM turns WHERE ${clause} ORDER BY started_at DESC LIMIT ?`)
+                .all(...args, limit);
+            return { turns: rows.map(rowToTurnPair), total, truncated: total > limit };
+        },
+        /* ---------------- entities ---------------- */
+        putEntity(spec) {
+            const now = spec.seenAt ?? Date.now();
+            const id = spec.id ?? `en_${spec.type}_${encodeURIComponent(spec.name)}`;
+            // A refresh that only names the entity must not erase what is known about it.
+            // The upsert used to write `excluded.aliases` unconditionally, so every
+            // "just mention them again" call wiped the nickname and the attributes —
+            // and `latestAbout` lost its alias match, meaning the person stopped being
+            // recognized by anything but their full name.
+            const existingRow = db
+                .prepare('SELECT aliases, attrs FROM entities WHERE soul_id = ? AND user_id = ? AND type = ? AND name = ?')
+                .get(spec.soulId, spec.userId, spec.type, spec.name);
+            const readJson = (raw, fallback) => {
+                if (raw === undefined)
+                    return fallback;
+                try {
+                    return JSON.parse(raw);
+                }
+                catch {
+                    return fallback;
+                }
+            };
+            const existingAliases = readJson(existingRow?.aliases, []);
+            const existingAttrs = readJson(existingRow?.attrs, {});
+            const aliases = spec.aliases === undefined ? existingAliases : [...new Set([...existingAliases, ...spec.aliases])];
+            const attrs = spec.attrs === undefined ? existingAttrs : { ...existingAttrs, ...spec.attrs };
+            withRetry(() => db
+                .prepare(`INSERT INTO entities
+               (id, soul_id, user_id, type, name, aliases, attrs,
+                first_seen_at, last_mentioned_at, created_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+             ON CONFLICT(soul_id, user_id, type, name) DO UPDATE SET
+               last_mentioned_at = excluded.last_mentioned_at,
+               aliases = excluded.aliases,
+               attrs = excluded.attrs`)
+                .run(id, spec.soulId, spec.userId, spec.type, spec.name, JSON.stringify(aliases), JSON.stringify(attrs), now, now, now));
+            const row = db
+                .prepare('SELECT * FROM entities WHERE soul_id = ? AND user_id = ? AND type = ? AND name = ?')
+                .get(spec.soulId, spec.userId, spec.type, spec.name);
+            return rowToEntity(row);
+        },
+        entity(id) {
+            const row = db.prepare('SELECT * FROM entities WHERE id = ?').get(id);
+            return row ? rowToEntity(row) : null;
+        },
+        findEntities(query) {
+            const where = ['soul_id = ?', 'user_id = ?'];
+            const args = [query.soulId, query.userId];
+            if (query.type) {
+                where.push('type = ?');
+                args.push(query.type);
+            }
+            if (query.name) {
+                where.push("(name LIKE ? ESCAPE '\\' OR aliases LIKE ? ESCAPE '\\')");
+                const needle = `%${query.name.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+                args.push(needle, needle);
+            }
+            const rows = db
+                .prepare(`SELECT * FROM entities WHERE ${where.join(' AND ')}
+           ORDER BY last_mentioned_at DESC LIMIT ?`)
+                .all(...args, query.limit ?? 20);
+            return rows.map(rowToEntity);
+        },
+        /* ---------------- facts ---------------- */
+        putFact(spec) {
+            const id = spec.id ?? `fc_${Date.now().toString(36)}_${(factSeq += 1).toString(36)}`;
+            const createdAt = Date.now();
+            // The writer assigns the role: callers may set one explicitly, otherwise the old type
+            // label decides. Without this every new row would default to observation and quietly
+            // disappear from rules()/profile()/conclusions().
+            const role = spec.role ?? LEGACY_ROLE_BY_TYPE[spec.typeName ?? ''] ?? 'observation';
+            withRetry(() => {
+                const inserted = db
+                    .prepare(`INSERT OR IGNORE INTO facts
+               (id, soul_id, user_id, statement, type_name, role, holder, at, at_text, at_end, at_precision,
+                place_id, status, confidence, source, source_turn_id, superseded_by, created_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(id, spec.soulId, spec.userId, spec.statement, spec.typeName ?? null, role, spec.holder ?? 'world', spec.at ?? null, spec.atText ?? null, spec.atEnd ?? null, spec.atPrecision ?? 'unknown', spec.placeId ?? null, spec.status ?? 'active', spec.confidence ?? 1, spec.source ?? 'experienced', spec.sourceTurnId ?? null, spec.supersededBy ?? null, createdAt);
+                if (Number(inserted.changes) > 0) {
+                    const insertSlot = db.prepare(`INSERT INTO fact_slots (fact_id, slot, value_type, entity_id, value_num, value_text, ref_fact_id)
+             VALUES (?, ?, ?, ?, ?, ?, ?)`);
+                    for (const s of spec.slots ?? []) {
+                        insertSlot.run(id, s.slot, s.value.kind, s.value.kind === 'entity' ? s.value.entityId : null, s.value.kind === 'number' ? s.value.value : null, s.value.kind === 'text' ? s.value.value : null, s.value.kind === 'fact' ? s.value.factId : null);
+                    }
+                }
+            });
+            const fact = this.fact(id);
+            if (!fact)
+                throw new Error(`fact ${id} disappeared right after writing`);
+            return fact;
+        },
+        fact(id) {
+            const row = db.prepare('SELECT * FROM facts WHERE id = ?').get(id);
+            if (!row)
+                return null;
+            return rowToFact(row, slotsOfRows(db, [id]));
+        },
+        facts(query) {
+            const where = ['f.soul_id = ?', 'f.user_id = ?'];
+            const args = [query.soulId, query.userId];
+            if (query.entityId) {
+                where.push('EXISTS (SELECT 1 FROM fact_slots s WHERE s.fact_id = f.id AND s.entity_id = ?)');
+                args.push(query.entityId);
+            }
+            if (query.since !== undefined) {
+                where.push('f.at >= ?');
+                args.push(query.since);
+            }
+            if (query.until !== undefined) {
+                where.push('f.at <= ?');
+                args.push(query.until);
+            }
+            if (query.status) {
+                where.push('f.status = ?');
+                args.push(query.status);
+            }
+            if (query.holder) {
+                where.push('f.holder = ?');
+                args.push(query.holder);
+            }
+            const direction = query.order === 'asc' ? 'ASC' : 'DESC';
+            const rows = db
+                .prepare(`SELECT f.* FROM facts f WHERE ${where.join(' AND ')}
+           ORDER BY COALESCE(f.at, f.created_at) ${direction} LIMIT ?`)
+                .all(...args, query.limit ?? 200);
+            const ids = rows.map((r) => String(r.id));
+            const slots = slotsOfRows(db, ids);
+            return rows.map((row) => rowToFact(row, slots));
+        },
+        supersedeFact(oldId, newId) {
+            withRetry(() => db
+                .prepare(`UPDATE facts SET status = '${FACT_STATUS.superseded}', superseded_by = ? WHERE id = ?`)
+                .run(newId, oldId));
+        },
+        /* ---------------- gaps ---------------- */
+        putGap(spec) {
+            const id = spec.id ?? `gp_${Date.now().toString(36)}_${(gapSeq += 1).toString(36)}`;
+            withRetry(() => db
+                .prepare(`INSERT OR IGNORE INTO gaps
+               (id, soul_id, user_id, about_entity_id, about_fact_id, topic,
+                tension, status, opened_at, closed_at, closed_by_fact_id)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(id, spec.soulId, spec.userId, spec.aboutEntityId ?? null, spec.aboutFactId ?? null, spec.topic, spec.tension ?? 0, spec.status ?? 'open', spec.openedAt ?? Date.now(), spec.closedAt ?? null, spec.closedByFactId ?? null));
+            const row = db.prepare('SELECT * FROM gaps WHERE id = ?').get(id);
+            return rowToGap(row);
+        },
+        openGaps(soulId, userId, limit = 20) {
+            const rows = db
+                .prepare(`SELECT * FROM gaps WHERE soul_id = ? AND user_id = ? AND status = 'open'
+           ORDER BY tension DESC, opened_at ASC LIMIT ?`)
+                .all(soulId, userId, limit);
+            return rows.map(rowToGap);
+        },
+        closeGap(id, closedByFactId, at = Date.now()) {
             withRetry(() => db
-                .prepare(`INSERT OR IGNORE INTO turn_pairs
-               (id, soul_id, user_id, session_id, turn, at, user_text, assistant_text,
-                metadata_json, created_at)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                .run(pair.id, pair.soulId, pair.userId, pair.sessionId, pair.turn, pair.at, pair.userText, pair.assistantText, JSON.stringify(pair.metadata), pair.createdAt));
+                .prepare(`UPDATE gaps SET status = 'closed', closed_at = ?, closed_by_fact_id = ?
+             WHERE id = ?`)
+                .run(at, closedByFactId ?? null, id));
+        },
+        turn(id) {
+            const row = db.prepare('SELECT * FROM turns WHERE id = ?').get(id);
+            return row ? rowToTurnPair(row) : null;
+        },
+        openThread(spec) {
+            const id = spec.id ?? `th_${spec.openedAt.toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+            withRetry(() => db
+                .prepare(`INSERT INTO threads (id, soul_id, user_id, session_id, topic, status, opened_at, last_turn_no)
+             VALUES (?, ?, ?, ?, ?, 'open', ?, ?)`)
+                .run(id, spec.soulId, spec.userId, spec.sessionId, spec.topic, spec.openedAt, spec.turnNo ?? null));
+            return {
+                id,
+                soulId: spec.soulId,
+                userId: spec.userId,
+                sessionId: spec.sessionId,
+                topic: spec.topic,
+                status: 'open',
+                openedAt: spec.openedAt,
+                lastTurnNo: spec.turnNo,
+            };
+        },
+        attachTurn(turnId, threadId) {
+            withRetry(() => db.prepare('UPDATE turns SET thread_id = ? WHERE id = ?').run(threadId, turnId));
+        },
+        touchThread(id, turnNo) {
+            withRetry(() => db.prepare('UPDATE threads SET last_turn_no = ? WHERE id = ?').run(turnNo, id));
+        },
+        updateThreadTopic(id, topic) {
+            withRetry(() => db.prepare('UPDATE threads SET topic = ? WHERE id = ?').run(topic, id));
+        },
+        openThreads(soulId, userId, limit = 5) {
+            const rows = db
+                .prepare(`SELECT * FROM threads WHERE soul_id = ? AND user_id = ? AND status = 'open'
+           ORDER BY COALESCE(last_turn_no, 0) DESC, opened_at DESC LIMIT ?`)
+                .all(soulId, userId, limit);
+            return rows.map(rowToThread);
+        },
+        thread(id) {
+            const row = db.prepare('SELECT * FROM threads WHERE id = ?').get(id);
+            return row ? rowToThread(row) : null;
+        },
+        closeThread(id, at, summaryFactId) {
+            withRetry(() => db
+                .prepare("UPDATE threads SET status = 'closed', closed_at = ?, summary_fact_id = ? WHERE id = ?")
+                .run(at, summaryFactId ?? null, id));
+        },
+        /**
+         * Close topics the conversation has moved past.
+         *
+         * Three signals, ordered by how much they actually know:
+         *
+         *   - `archived`: the user put the session away. A declaration, not an
+         *     inference — the strongest signal, so it wins even over recency.
+         *   - `quiet-turns`: inside the running session, the conversation moved on N
+         *     turns. Counted as **rows**, because the host's turn number is not a
+         *     per-exchange counter (it jumps by 10–30 per message).
+         *   - `quiet-time`: silence in another session. The weakest signal, kept only
+         *     as a safety net, and deliberately long: closing early writes a partial
+         *     conclusion into durable memory, while closing late only delays one.
+         *
+         * The reason is returned so the log can say which signal actually fired, and
+         * so a threshold that fires too early is visible instead of silent.
+         */
+        closeIdleThreads(soulId, userId, sessionId, idleTurns, idleMs, archivedSessionIds, at) {
+            const archived = new Set(archivedSessionIds);
+            const open = db
+                .prepare(`SELECT t.id AS id, t.session_id AS session_id,
+                  COALESCE((SELECT MAX(x.started_at) FROM turns x WHERE x.session_id = t.session_id),
+                           t.opened_at) AS last_activity,
+                  (SELECT COUNT(*) FROM turns x
+                   WHERE x.session_id = t.session_id
+                     AND x.turn_no > COALESCE(t.last_turn_no, 0)) AS quiet_turns
+           FROM threads t
+           WHERE t.soul_id = ? AND t.user_id = ? AND t.status = 'open'`)
+                .all(soulId, userId);
+            const cutoff = at - Math.max(60_000, idleMs);
+            const closing = [];
+            for (const row of open) {
+                const threadSession = String(row.session_id);
+                if (threadSession === sessionId) {
+                    if (Number(row.quiet_turns) >= Math.max(1, idleTurns)) {
+                        closing.push({ id: String(row.id), reason: 'quiet-turns' });
+                    }
+                }
+                else if (archived.has(threadSession)) {
+                    closing.push({ id: String(row.id), reason: 'archived' });
+                }
+                else if (Number(row.last_activity) <= cutoff) {
+                    closing.push({ id: String(row.id), reason: 'quiet-time' });
+                }
+            }
+            const close = db.prepare("UPDATE threads SET status = 'closed', closed_at = ? WHERE id = ?");
+            for (const thread of closing)
+                withRetry(() => close.run(at, thread.id));
+            return closing;
+        },
+        threadTurns(threadId) {
+            const rows = db
+                .prepare('SELECT * FROM turns WHERE thread_id = ? ORDER BY turn_no ASC')
+                .all(threadId);
+            return rows.map(rowToTurnPair);
+        },
+        /**
+         * The thread worth handing over: a finished topic that produced a conclusion.
+         *
+         * A one-message question also closes as a "thread", and handing that over tells
+         * the next session nothing but noise ("we last talked about: who am I"). So a
+         * summary comes first; otherwise a topic needs at least two turns to qualify.
+         */
+        lastClosedThread(soulId, userId) {
+            const summarised = db
+                .prepare(`SELECT * FROM threads WHERE soul_id = ? AND user_id = ? AND status = 'closed'
+             AND summary_fact_id IS NOT NULL
+           ORDER BY COALESCE(closed_at, 0) DESC LIMIT 1`)
+                .get(soulId, userId);
+            if (summarised)
+                return rowToThread(summarised);
+            const substantial = db
+                .prepare(`SELECT t.* FROM threads t WHERE t.soul_id = ? AND t.user_id = ? AND t.status = 'closed'
+             AND (SELECT COUNT(*) FROM turns x WHERE x.thread_id = t.id) >= 2
+           ORDER BY COALESCE(t.closed_at, 0) DESC LIMIT 1`)
+                .get(soulId, userId);
+            return substantial ? rowToThread(substantial) : null;
+        },
+        /** The thread the previous turn belonged to, if any — the cheapest continuity hint. */
+        threadBefore(sessionId, turnNo) {
+            const row = db
+                .prepare(`SELECT thread_id FROM turns
+           WHERE session_id = ? AND turn_no < ? AND thread_id IS NOT NULL
+           ORDER BY turn_no DESC LIMIT 1`)
+                .get(sessionId, turnNo);
+            return row ? String(row.thread_id) : null;
+        },
+        previousTurnText(sessionId, turnNo) {
+            const row = db
+                .prepare(`SELECT user_text FROM turns
+           WHERE session_id = ? AND turn_no < ?
+           ORDER BY turn_no DESC LIMIT 1`)
+                .get(sessionId, turnNo);
+            const text = row ? String(row.user_text ?? '').trim() : '';
+            return text === '' ? null : text;
+        },
+        factsByTurns(turnIds) {
+            if (turnIds.length === 0)
+                return [];
+            const placeholders = turnIds.map(() => '?').join(',');
+            const rows = db
+                .prepare(`SELECT f.* FROM facts f WHERE f.source_turn_id IN (${placeholders}) ORDER BY f.created_at ASC`)
+                .all(...turnIds);
+            const slots = slotsOfRows(db, rows.map((row) => String(row.id)));
+            return rows.map((row) => rowToFact(row, slots));
+        },
+        /**
+         * Append slots to an existing fact, skipping ones it already has.
+         *
+         * Used when a duplicate conclusion is merged into the held one: the holder
+         * keeps its statement, and gains the new evidence so it gets stronger rather
+         * than being restated.
+         */
+        addSlots(factId, slots) {
+            const existing = new Set(db
+                .prepare("SELECT ref_fact_id, value_text, slot FROM fact_slots WHERE fact_id = ?")
+                .all(factId).map((row) => `${String(row.slot)}|${String(row.ref_fact_id ?? row.value_text ?? '')}`));
+            const insert = db.prepare(`INSERT INTO fact_slots (fact_id, slot, value_type, entity_id, value_num, value_text, ref_fact_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`);
+            let added = 0;
+            for (const s of slots) {
+                const key = `${s.slot}|${s.value.kind === 'fact' ? s.value.factId : s.value.kind === 'entity' ? s.value.entityId : s.value.kind === 'text' ? s.value.value : String(s.value.value)}`;
+                if (existing.has(key))
+                    continue;
+                insert.run(factId, s.slot, s.value.kind, s.value.kind === 'entity' ? s.value.entityId : null, s.value.kind === 'number' ? s.value.value : null, s.value.kind === 'text' ? s.value.value : null, s.value.kind === 'fact' ? s.value.factId : null);
+                existing.add(key);
+                added += 1;
+            }
+            return added;
+        },
+        /** Retag a fact, e.g. a lesson that turned out to be a rule (ADR 0033). */
+        setFactTypeName(factId, typeName) {
+            // Role follows the label: markRule/markProfile change what the row is for, and a stale
+            // role would send it to the wrong consumer (the exact split this refactor removes).
+            const role = LEGACY_ROLE_BY_TYPE[typeName] ?? 'observation';
+            withRetry(() => db.prepare('UPDATE facts SET type_name = ?, role = ? WHERE id = ?').run(typeName, role, factId));
+        },
+        setFactConfidence(factId, confidence) {
+            withRetry(() => db.prepare('UPDATE facts SET confidence = ? WHERE id = ?').run(confidence, factId));
+        },
+        /**
+         * Count that retrieval surfaced these facts.
+         *
+         * This is the rehearsal in 0019: a memory used often decays more slowly, so the
+         * counter is the mechanism, not a statistic.
+         */
+        recordRecalls(factIds, at) {
+            if (factIds.length === 0)
+                return;
+            const stmt = db.prepare('UPDATE facts SET recall_count = recall_count + 1, last_recalled_at = ? WHERE id = ?');
+            for (const id of factIds)
+                withRetry(() => stmt.run(at, id));
+        },
+        /**
+         * The entity timeline: facts about one person/thing, newest event first.
+         *
+         * This is the primitive behind "上次和 a 吃饭" — the subject decides what is
+         * fetched, and `predicate` narrows within that subject's own facts. It must
+         * never look outside the subject: answering about b when asked about a is the
+         * one error worse than saying nothing.
+         */
+        /**
+         * The entity timeline: facts about one person/thing, ranked.
+         *
+         * This is the primitive behind "上次和 a 吃饭". Recency alone is not enough — an
+         * entity with a thousand facts would return its three most recent ones, which
+         * answers "what happened to a lately", not "the meal". So the ranking is
+         * relevance to the question × power-law recency × recall practice, the same
+         * weights the relevance primitive uses (0019, 0020).
+         *
+         * It must never look outside the subject: answering about b when asked about a
+         * is the one error worse than saying nothing.
+         */
+        latestAbout(soulId, userId, entityName, options = {}) {
+            const limit = Math.max(1, options.limit ?? 5);
+            const predicate = options.predicate?.trim();
+            // Bounded so a long-lived entity cannot make this unbounded.
+            const CANDIDATES = 500;
+            const rows = db
+                .prepare(`SELECT DISTINCT f.* FROM facts f
+           JOIN fact_slots s ON s.fact_id = f.id AND s.value_type = 'entity'
+           JOIN entities e ON e.id = s.entity_id
+           WHERE f.soul_id = ? AND f.user_id = ? AND f.status != '${FACT_STATUS.superseded}'
+             AND (e.name = ? OR e.aliases LIKE ?)
+             AND (? IS NULL OR f.statement LIKE ? OR COALESCE(f.type_name, '') LIKE ?)
+           ORDER BY COALESCE(f.at, f.created_at) DESC
+           LIMIT ?`)
+                .all(soulId, userId, entityName, `%${entityName}%`, predicate ?? null, predicate ? `%${predicate}%` : null, predicate ? `%${predicate}%` : null, CANDIDATES);
+            const slots = slotsOfRows(db, rows.map((row) => String(row.id)));
+            const facts = rows.map((row) => rowToFact(row, slots));
+            const query = options.query?.trim();
+            if (!query)
+                return facts.slice(0, limit);
+            const now = options.now ?? Date.now();
+            const queryTokens = tokenize(query);
+            const stats = buildCorpusStats(facts.map((fact) => tokenize(fact.statement)));
+            const scored = facts.map((fact) => {
+                const relevanceScore = bm25(queryTokens, tokenize(fact.statement), stats);
+                const ageDays = Math.max(0, (now - (fact.at ?? fact.createdAt)) / 86_400_000);
+                // Power law, not exponential: the tail of a memory stays reachable (0019).
+                const decay = 1 / Math.sqrt(1 + ageDays);
+                const practice = 1 + 0.2 * Math.log(1 + fact.recallCount);
+                return { fact, score: relevanceScore * decay * practice };
+            });
+            scored.sort((a, b) => b.score - a.score);
+            return scored.slice(0, limit).map((entry) => entry.fact);
+        },
+        turnByTurnNo(sessionId, turnNo) {
+            const row = db
+                .prepare('SELECT * FROM turns WHERE session_id = ? AND turn_no = ? LIMIT 1')
+                .get(sessionId, turnNo);
+            return row ? rowToTurnPair(row) : null;
+        },
+        stepsOf(turnId) {
+            const rows = db
+                .prepare('SELECT * FROM steps WHERE turn_id = ? ORDER BY idx ASC')
+                .all(turnId);
+            return rows.map((row) => ({
+                idx: Number(row.idx),
+                kind: String(row.kind),
+                text: row.text === null ? undefined : String(row.text),
+                toolName: row.tool_name === null ? undefined : String(row.tool_name),
+                toolArgsChars: row.tool_args_chars === null ? undefined : Number(row.tool_args_chars),
+                toolResultChars: row.tool_result_chars === null ? undefined : Number(row.tool_result_chars),
+                ok: row.ok === null ? undefined : Number(row.ok) === 1,
+                at: Number(row.at),
+            }));
+        },
+        putTurnPair(pair, steps) {
+            this.putTurn({
+                id: pair.id,
+                soulId: pair.soulId,
+                userId: pair.userId,
+                sessionId: pair.sessionId,
+                turnNo: pair.turn,
+                startedAt: pair.at,
+                endedAt: pair.at,
+                userText: pair.userText,
+                status: 'closed',
+                createdAt: pair.createdAt,
+                // Adapters may hand over the real step list (reasoning, text, tool) so a
+                // turn keeps its shape; otherwise the reply collapses into one text step.
+                steps: steps && steps.length > 0
+                    ? steps
+                    : pair.assistantText
+                        ? [{ idx: 0, kind: 'text', text: pair.assistantText, at: pair.at }]
+                        : [],
+            });
         },
         recallTurnPairs(spec) {
             // No cap by default: every related exchange is returned (bounded only by
             // RECALL_CANDIDATES, which limits rows read, not rows injected).
             const limit = spec.limit ?? RECALL_CANDIDATES;
             const rows = db
-                .prepare(`SELECT * FROM turn_pairs
-           WHERE soul_id = ? AND user_id = ? AND at >= ?
-           ORDER BY at DESC LIMIT ?`)
+                .prepare(`SELECT * FROM turns
+           WHERE soul_id = ? AND user_id = ? AND started_at >= ?
+           ORDER BY started_at DESC LIMIT ?`)
                 .all(spec.soulId, spec.userId, spec.since ?? 0, Math.max(limit, RECALL_CANDIDATES));
             const pairs = rows.map(rowToTurnPair);
             const query = spec.query?.trim();
@@ -402,12 +1175,45 @@ export function openSqlite(file) {
                 .slice(0, limit)
                 .map((scored) => scored.pair);
         },
-        countTurnPairs(soulId, userId) {
-            const row = db
-                .prepare('SELECT COUNT(*) AS n FROM turn_pairs WHERE soul_id = ? AND user_id = ?')
-                .get(soulId, userId);
+        countTurnPairs(soulId, userId, sessionId) {
+            const row = sessionId
+                ? db
+                    .prepare('SELECT COUNT(*) AS n FROM turns WHERE soul_id = ? AND user_id = ? AND session_id = ?')
+                    .get(soulId, userId, sessionId)
+                : db
+                    .prepare('SELECT COUNT(*) AS n FROM turns WHERE soul_id = ? AND user_id = ?')
+                    .get(soulId, userId);
             return Number(row.n);
         },
+        listSessions(soulId, userId, limit) {
+            const rows = db
+                .prepare(`SELECT session_id, MIN(started_at) AS start, MAX(started_at) AS end, COUNT(*) AS turns
+           FROM turns WHERE soul_id = ? AND user_id = ?
+           GROUP BY session_id ORDER BY MAX(started_at) DESC LIMIT ?`)
+                .all(soulId, userId, limit);
+            return rows.map((row) => ({
+                sessionId: String(row.session_id),
+                start: Number(row.start),
+                end: Number(row.end),
+                turns: Number(row.turns),
+            }));
+        },
+        sessionPairs(sessionId, soulId, userId, limit) {
+            const rows = db
+                .prepare(`SELECT * FROM turns
+           WHERE soul_id = ? AND user_id = ? AND session_id = ?
+           ORDER BY started_at ASC LIMIT ?`)
+                .all(soulId, userId, sessionId, limit);
+            return rows.map(rowToTurnPair);
+        },
+        sessionTail(sessionId, soulId, userId, limit) {
+            const rows = db
+                .prepare(`SELECT * FROM turns
+           WHERE soul_id = ? AND user_id = ? AND session_id = ?
+           ORDER BY started_at DESC LIMIT ?`)
+                .all(soulId, userId, sessionId, limit);
+            return rows.map(rowToTurnPair).reverse();
+        },
         close() {
             db.close();
         },
@@ -417,6 +1223,111 @@ export function openSqlite(file) {
 function pairTokens(pair) {
     return [...tokenize(pair.userText), ...tokenize(pair.assistantText)];
 }
+/** Id counters keep fact/gap ids unique within a process without extra deps. */
+let factSeq = 0;
+let gapSeq = 0;
+function parseJson(raw, fallback) {
+    try {
+        return raw ? JSON.parse(String(raw)) : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+function rowToEntity(row) {
+    return {
+        id: String(row.id),
+        soulId: String(row.soul_id),
+        userId: String(row.user_id),
+        type: String(row.type),
+        name: String(row.name),
+        aliases: parseJson(row.aliases, []),
+        attrs: parseJson(row.attrs, {}),
+        firstSeenAt: Number(row.first_seen_at),
+        lastMentionedAt: Number(row.last_mentioned_at),
+        createdAt: Number(row.created_at),
+    };
+}
+/** Slots of many facts in one query, grouped by fact id. */
+function slotsOfRows(db, factIds) {
+    const map = new Map();
+    if (factIds.length === 0)
+        return map;
+    const placeholders = factIds.map(() => '?').join(',');
+    const rows = db
+        .prepare(`SELECT * FROM fact_slots WHERE fact_id IN (${placeholders}) ORDER BY id ASC`)
+        .all(...factIds);
+    for (const row of rows) {
+        const factId = String(row.fact_id);
+        const list = map.get(factId) ?? [];
+        const valueType = String(row.value_type);
+        const value = valueType === 'entity'
+            ? { kind: 'entity', entityId: String(row.entity_id) }
+            : valueType === 'number'
+                ? { kind: 'number', value: Number(row.value_num) }
+                : valueType === 'fact'
+                    ? { kind: 'fact', factId: String(row.ref_fact_id) }
+                    : { kind: 'text', value: String(row.value_text ?? '') };
+        list.push({ slot: String(row.slot), value });
+        map.set(factId, list);
+    }
+    return map;
+}
+function rowToFact(row, slots) {
+    const id = String(row.id);
+    return {
+        id,
+        soulId: String(row.soul_id),
+        userId: String(row.user_id),
+        statement: String(row.statement),
+        typeName: row.type_name === null ? undefined : String(row.type_name),
+        role: row.role === null || row.role === undefined ? undefined : String(row.role),
+        holder: String(row.holder),
+        at: row.at === null ? undefined : Number(row.at),
+        atText: row.at_text === null ? undefined : String(row.at_text),
+        atEnd: row.at_end === null ? undefined : Number(row.at_end),
+        atPrecision: (row.at_precision ?? 'unknown'),
+        placeId: row.place_id === null ? undefined : String(row.place_id),
+        status: String(row.status),
+        confidence: Number(row.confidence),
+        source: String(row.source),
+        sourceTurnId: row.source_turn_id === null ? undefined : String(row.source_turn_id),
+        supersededBy: row.superseded_by === null ? undefined : String(row.superseded_by),
+        createdAt: Number(row.created_at),
+        recallCount: Number(row.recall_count ?? 0),
+        lastRecalledAt: row.last_recalled_at === null || row.last_recalled_at === undefined ? undefined : Number(row.last_recalled_at),
+        slots: slots.get(id) ?? [],
+    };
+}
+function rowToThread(row) {
+    return {
+        id: String(row.id),
+        soulId: String(row.soul_id),
+        userId: String(row.user_id),
+        sessionId: String(row.session_id),
+        topic: String(row.topic),
+        status: String(row.status),
+        openedAt: Number(row.opened_at),
+        closedAt: row.closed_at === null || row.closed_at === undefined ? undefined : Number(row.closed_at),
+        lastTurnNo: row.last_turn_no === null || row.last_turn_no === undefined ? undefined : Number(row.last_turn_no),
+        summaryFactId: row.summary_fact_id === null || row.summary_fact_id === undefined ? undefined : String(row.summary_fact_id),
+    };
+}
+function rowToGap(row) {
+    return {
+        id: String(row.id),
+        soulId: String(row.soul_id),
+        userId: String(row.user_id),
+        aboutEntityId: row.about_entity_id === null ? undefined : String(row.about_entity_id),
+        aboutFactId: row.about_fact_id === null ? undefined : String(row.about_fact_id),
+        topic: String(row.topic),
+        tension: Number(row.tension),
+        status: String(row.status),
+        openedAt: Number(row.opened_at),
+        closedAt: row.closed_at === null ? undefined : Number(row.closed_at),
+        closedByFactId: row.closed_by_fact_id === null ? undefined : String(row.closed_by_fact_id),
+    };
+}
 function rowToTurnPair(row) {
     let metadata = {};
     try {
@@ -430,8 +1341,8 @@ function rowToTurnPair(row) {
         soulId: String(row.soul_id),
         userId: String(row.user_id),
         sessionId: String(row.session_id),
-        turn: Number(row.turn),
-        at: Number(row.at),
+        turn: Number(row.turn ?? row.turn_no),
+        at: Number(row.at ?? row.started_at),
         userText: String(row.user_text),
         assistantText: String(row.assistant_text),
         metadata,