pi-mega-compact 0.9.2 → 0.11.0

package/dist/src/store/turns/schema.js

@@ -0,0 +1,115 @@
+/** Schema version stamp (written once into turns_meta). */
+const SCHEMA_VERSION = 1;
+/** Create the unified turn-store schema if absent. Idempotent. */
+export function initTurnSchema(db) {
+    // ── Contract tables (master's SqliteTurnStore shape) ──────────────────
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS turns_meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )
+  `);
+    // One row per turn_end. role/source/pressure_band use the contract enums.
+    // epoch_id is the S50B additive column (links a turn to the compact epoch).
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS turns (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      conversation_id TEXT    NOT NULL,
+      session_id      TEXT    NOT NULL,
+      turn_index      INTEGER NOT NULL,
+      role            TEXT    NOT NULL CHECK(role IN ('user','assistant','system','tool')),
+      started_at      INTEGER,
+      ended_at        INTEGER NOT NULL,
+      ctx_tokens      INTEGER,
+      ctx_percent     REAL,
+      pressure_band   TEXT    CHECK(pressure_band IS NULL OR pressure_band IN ('green','yellow','red')),
+      model           TEXT,
+      epoch_id        TEXT,
+      UNIQUE(conversation_id, turn_index)
+    )
+  `);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_turns_conversation ON turns(conversation_id, turn_index)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_turns_session ON turns(session_id)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_turns_ended_at ON turns(ended_at)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_turns_pressure ON turns(pressure_band) WHERE pressure_band IS NOT NULL`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_turns_epoch ON turns(epoch_id) WHERE epoch_id IS NOT NULL`);
+    // Recall provenance — which checkpoints / cluster summaries were injected
+    // at a turn, with score + source path. source uses the contract enum.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS turn_recall (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      turn_id       INTEGER NOT NULL REFERENCES turns(id) ON DELETE CASCADE,
+      checkpoint_id TEXT    NOT NULL,
+      score         REAL    NOT NULL,
+      source        TEXT    NOT NULL CHECK(source IN ('checkpoint','cluster_summary','memory')),
+      raptor_level  INTEGER,
+      UNIQUE(turn_id, checkpoint_id)
+    )
+  `);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_turn_recall_turn ON turn_recall(turn_id)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_turn_recall_cp ON turn_recall(checkpoint_id)`);
+    // Conversation fork registry (contract: ConversationFork).
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS conversation_forks (
+      id                     INTEGER PRIMARY KEY AUTOINCREMENT,
+      parent_conversation_id TEXT NOT NULL,
+      child_conversation_id  TEXT NOT NULL,
+      fork_turn_index        INTEGER NOT NULL,
+      created_at             INTEGER NOT NULL,
+      UNIQUE(child_conversation_id)
+    )
+  `);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_forks_parent ON conversation_forks(parent_conversation_id)`);
+    // Session → active conversation map (contract: one current conversation per session).
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS session_conversations (
+      session_id      TEXT PRIMARY KEY,
+      conversation_id TEXT NOT NULL
+    )
+  `);
+    // ── Program additive shells (this branch) ───────────────────────────
+    // S52: rewind-and-fork intents written by an external surface (dashboard)
+    // and consumed by the host at a safe lifecycle point. Pre-created → S52
+    // adds no migration.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS pending_fork (
+      id                     INTEGER PRIMARY KEY AUTOINCREMENT,
+      target_conversation_id TEXT NOT NULL,
+      target_turn_id         INTEGER NOT NULL,
+      requested_at           INTEGER NOT NULL,
+      consumed_at            INTEGER
+    )
+  `);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_pending_fork_unconsumed ON pending_fork(consumed_at) WHERE consumed_at IS NULL`);
+    // S51: auto-categorizing wiki topics (k-means over real embeddings + TF-IDF
+    // labels — see docs/specs/s47-auto-categorizing-wiki.md). Pre-created → S51
+    // adds no migration. Derived at rebuild time; no seed data.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS topics (
+      id                     TEXT PRIMARY KEY,
+      label                  TEXT NOT NULL,
+      term_scores            TEXT,
+      memory_count           INTEGER DEFAULT 0,
+      last_updated           INTEGER,
+      cluster_model_built_at INTEGER
+    )
+  `);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS memory_topics (
+      memory_id   TEXT NOT NULL,
+      topic_id    TEXT NOT NULL REFERENCES topics(id),
+      confidence  REAL,
+      assigned_at INTEGER,
+      method      TEXT CHECK(method IN ('kmeans+tfidf')),
+      PRIMARY KEY (memory_id, topic_id)
+    )
+  `);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_memory_topics_topic ON memory_topics(topic_id)`);
+    // Stamp schema version once.
+    const existing = db
+        .prepare("SELECT value FROM turns_meta WHERE key = 'schema_version'")
+        .get();
+    if (!existing) {
+        db.prepare("INSERT INTO turns_meta (key, value) VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
+    }
+}

package/dist/src/store/turns/sqlite-store.js

@@ -0,0 +1,455 @@
+/**
+ * sqlite-store.ts — SqliteTurnStore: the reference implementation.
+ *
+ * Private schema (SQL lives here + connection.ts, not in types.ts).
+ * All methods satisfy the TurnStore contract from types.ts.
+ * Append-only: no UPDATE on turns/turn_recall after INSERT (only in migration).
+ *
+ * PREVENT-PI-004: node:sqlite in-process only.
+ * PREVENT-002: all queries use bound parameters.
+ * PREVENT-001: safeJson not needed — no JSON columns in turns.db.
+ */
+import { randomBytes } from "node:crypto";
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { openTurnDb, closeTurnDb } from "./connection.js";
+// ─── Helpers ──────────────────────────────────────────────────────
+function newConversationId() {
+    return `conv_${randomBytes(8).toString("hex")}`;
+}
+function normalizeSessionId(sid) {
+    // Matches the existing normalizeSessionId in src/store.ts
+    return sid.replace(/-.*$/, "");
+}
+function rowToEntry(r) {
+    return {
+        conversationId: r.conversation_id,
+        sessionId: r.session_id,
+        turnIndex: r.turn_index,
+        role: r.role,
+        endedAt: r.ended_at,
+        ctxTokens: r.ctx_tokens ?? undefined,
+        ctxPercent: r.ctx_percent ?? undefined,
+        pressureBand: r.pressure_band ?? undefined,
+        model: r.model ?? undefined,
+        epochId: r.epoch_id ?? undefined,
+    };
+}
+function rowToRecall(r) {
+    return {
+        turnId: String(r.turn_id),
+        checkpointId: r.checkpoint_id,
+        score: r.score,
+        source: r.source,
+        raptorLevel: r.raptor_level ?? undefined,
+    };
+}
+function rowToFork(r) {
+    return {
+        parentConversationId: r.parent_conversation_id,
+        childConversationId: r.child_conversation_id,
+        forkTurnIndex: r.fork_turn_index,
+        createdAt: r.created_at,
+    };
+}
+// ─── SqliteTurnStore ──────────────────────────────────────────────
+export class SqliteTurnStore {
+    db;
+    stateDir;
+    opts;
+    constructor(options) {
+        this.opts = options;
+        this.stateDir = options.stateDir;
+        this.db = openTurnDb(options.stateDir, {
+            dbPath: options.dbPath,
+            inMemory: options.inMemory,
+        });
+    }
+    // ── TurnReader ──────────────────────────────────────────────
+    query(filter) {
+        const clauses = [];
+        const params = [];
+        if (filter.conversationId !== undefined) {
+            clauses.push("conversation_id = ?");
+            params.push(filter.conversationId);
+        }
+        if (filter.sessionId !== undefined) {
+            clauses.push("session_id = ?");
+            params.push(normalizeSessionId(filter.sessionId));
+        }
+        if (filter.sinceMs !== undefined) {
+            clauses.push("ended_at >= ?");
+            params.push(filter.sinceMs);
+        }
+        if (filter.untilMs !== undefined) {
+            clauses.push("ended_at <= ?");
+            params.push(filter.untilMs);
+        }
+        if (filter.pressureBand !== undefined) {
+            clauses.push("pressure_band = ?");
+            params.push(filter.pressureBand);
+        }
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+        const limit = filter.limit ?? 1000;
+        const offset = filter.offset ?? 0;
+        const rows = this.db
+            .prepare(`SELECT * FROM turns ${where} ORDER BY ended_at ASC LIMIT ? OFFSET ?`)
+            .all(...params, limit, offset);
+        return rows.map(rowToEntry);
+    }
+    getTurn(turnId) {
+        const row = this.db
+            .prepare("SELECT * FROM turns WHERE id = ?")
+            .get(Number(turnId));
+        return row ? rowToEntry(row) : undefined;
+    }
+    getTurnByIndex(conversationId, turnIndex) {
+        const row = this.db
+            .prepare("SELECT * FROM turns WHERE conversation_id = ? AND turn_index = ?")
+            .get(conversationId, turnIndex);
+        return row ? rowToEntry(row) : undefined;
+    }
+    listRecall(turnId) {
+        const rows = this.db
+            .prepare("SELECT * FROM turn_recall WHERE turn_id = ? ORDER BY score DESC")
+            .all(Number(turnId));
+        return rows.map(rowToRecall);
+    }
+    listRecallByIndex(conversationId, turnIndex) {
+        const row = this.db
+            .prepare("SELECT id FROM turns WHERE conversation_id = ? AND turn_index = ?")
+            .get(conversationId, turnIndex);
+        if (!row)
+            return [];
+        return this.listRecall(String(row.id));
+    }
+    listForks(conversationId) {
+        const rows = this.db
+            .prepare("SELECT * FROM conversation_forks WHERE parent_conversation_id = ? ORDER BY created_at ASC")
+            .all(conversationId);
+        return rows.map(rowToFork);
+    }
+    countTurns(conversationId) {
+        const row = this.db
+            .prepare("SELECT COUNT(*) as cnt FROM turns WHERE conversation_id = ?")
+            .get(conversationId);
+        return row.cnt;
+    }
+    conversationStats(conversationId) {
+        const rows = this.db
+            .prepare("SELECT ended_at, ctx_percent, pressure_band FROM turns WHERE conversation_id = ? ORDER BY ended_at ASC")
+            .all(conversationId);
+        if (rows.length === 0) {
+            return {
+                turnCount: 0,
+                firstTurnAt: 0,
+                lastTurnAt: 0,
+                avgCtxPercent: 0,
+                pressureBands: {},
+            };
+        }
+        let ctxSum = 0;
+        let ctxCount = 0;
+        const bands = {};
+        for (const r of rows) {
+            if (r.ctx_percent !== null) {
+                ctxSum += r.ctx_percent;
+                ctxCount++;
+            }
+            const band = r.pressure_band;
+            if (band)
+                bands[band] = (bands[band] ?? 0) + 1;
+        }
+        return {
+            turnCount: rows.length,
+            firstTurnAt: rows[0].ended_at,
+            lastTurnAt: rows[rows.length - 1].ended_at,
+            avgCtxPercent: ctxCount > 0 ? ctxSum / ctxCount : 0,
+            pressureBands: bands,
+        };
+    }
+    // ── TurnWriter ──────────────────────────────────────────────
+    appendTurn(entry) {
+        const sid = normalizeSessionId(entry.sessionId);
+        this.persistSessionConv(sid, entry.conversationId);
+        this.db
+            .prepare(`INSERT INTO turns (conversation_id, session_id, turn_index, role, ended_at,
+                                   ctx_tokens, ctx_percent, pressure_band, model)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(entry.conversationId, sid, entry.turnIndex, entry.role, entry.endedAt, entry.ctxTokens ?? null, entry.ctxPercent ?? null, entry.pressureBand ?? null, entry.model ?? null);
+        const row = this.db
+            .prepare("SELECT id FROM turns WHERE conversation_id = ? AND turn_index = ?")
+            .get(entry.conversationId, entry.turnIndex);
+        return String(row.id);
+    }
+    /** Persist the session → conversation mapping when a turn is written. */
+    persistSessionConv(sid, conversationId) {
+        this.db
+            .prepare("INSERT OR IGNORE INTO session_conversations (session_id, conversation_id) VALUES (?, ?)")
+            .run(sid, conversationId);
+    }
+    appendRecall(entry) {
+        this.db
+            .prepare(`INSERT OR IGNORE INTO turn_recall (turn_id, checkpoint_id, score, source, raptor_level)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(Number(entry.turnId), entry.checkpointId, entry.score, entry.source, entry.raptorLevel ?? null);
+    }
+    ensureConversationId(sessionId) {
+        const sid = normalizeSessionId(sessionId);
+        // Check session_conversations table first (persistent mapping)
+        const row = this.db
+            .prepare("SELECT conversation_id FROM session_conversations WHERE session_id = ?")
+            .get(sid);
+        if (row)
+            return row.conversation_id;
+        // Check if any turn exists for this session (fallback)
+        const turnRow = this.db
+            .prepare("SELECT conversation_id FROM turns WHERE session_id = ? ORDER BY ended_at DESC LIMIT 1")
+            .get(sid);
+        if (turnRow) {
+            // Persist the mapping so future calls are consistent
+            this.db
+                .prepare("INSERT OR IGNORE INTO session_conversations (session_id, conversation_id) VALUES (?, ?)")
+                .run(sid, turnRow.conversation_id);
+            return turnRow.conversation_id;
+        }
+        // No turns yet — generate and persist a new conversation id
+        const convId = newConversationId();
+        this.db
+            .prepare("INSERT OR IGNORE INTO session_conversations (session_id, conversation_id) VALUES (?, ?)")
+            .run(sid, convId);
+        return convId;
+    }
+    forkConversation(parentId, forkTurnIndex) {
+        const childId = newConversationId();
+        const now = Date.now();
+        // 1. Record the fork lineage
+        this.db
+            .prepare(`INSERT INTO conversation_forks (parent_conversation_id, child_conversation_id, fork_turn_index, created_at)
+         VALUES (?, ?, ?, ?)`)
+            .run(parentId, childId, forkTurnIndex, now);
+        // 2. Find the parent's turn at forkTurnIndex
+        const parentTurn = this.db
+            .prepare("SELECT id FROM turns WHERE conversation_id = ? AND turn_index = ?")
+            .get(parentId, forkTurnIndex);
+        if (!parentTurn)
+            return childId; // no parent turn at that index — nothing to seed
+        // 3. Create a seed turn in the child conversation (turnIndex 0, role system)
+        this.db
+            .prepare(`INSERT INTO turns (conversation_id, session_id, turn_index, role, ended_at)
+         VALUES (?, ?, 0, 'system', ?)`)
+            .run(childId, `fork_${childId}`, now);
+        const childTurnRow = this.db
+            .prepare("SELECT id FROM turns WHERE conversation_id = ? AND turn_index = 0")
+            .get(childId);
+        if (!childTurnRow)
+            return childId;
+        // 4. Copy the parent's recall entries into the child's seed turn
+        const parentRecall = this.db
+            .prepare("SELECT checkpoint_id, score, source, raptor_level FROM turn_recall WHERE turn_id = ?")
+            .all(parentTurn.id);
+        const insertRecall = this.db.prepare(`INSERT OR IGNORE INTO turn_recall (turn_id, checkpoint_id, score, source, raptor_level)
+         VALUES (?, ?, ?, ?, ?)`);
+        for (const r of parentRecall) {
+            insertRecall.run(childTurnRow.id, r.checkpoint_id, r.score, r.source, r.raptor_level ?? null);
+        }
+        return childId;
+    }
+    // ── TurnAdmin ───────────────────────────────────────────────
+    prune(policy) {
+        const beforeSize = this.dbSizeBytes();
+        const cutoff = Date.now() - policy.maxTurnAgeMs;
+        // Find conversations with turns to potentially prune
+        const convRows = this.db
+            .prepare("SELECT DISTINCT conversation_id FROM turns")
+            .all();
+        let turnsRemoved = 0;
+        let recallRemoved = 0;
+        for (const { conversation_id } of convRows) {
+            // Count total turns in this conversation
+            const total = this.db
+                .prepare("SELECT COUNT(*) as cnt FROM turns WHERE conversation_id = ?")
+                .get(conversation_id);
+            // Keep at least keepMinPerConversation — delete only the oldest
+            const canDelete = Math.max(0, total.cnt - policy.keepMinPerConversation);
+            if (canDelete === 0)
+                continue;
+            // Find old turns to delete
+            const oldTurns = this.db
+                .prepare(`SELECT id FROM turns WHERE conversation_id = ? AND ended_at < ?
+           ORDER BY ended_at ASC LIMIT ?`)
+                .all(conversation_id, cutoff, canDelete);
+            if (oldTurns.length === 0)
+                continue;
+            const ids = oldTurns.map((t) => t.id);
+            const placeholders = ids.map(() => "?").join(",");
+            // Delete recall for those turns
+            const delRecall = this.db
+                .prepare(`DELETE FROM turn_recall WHERE turn_id IN (${placeholders})`)
+                .run(...ids);
+            recallRemoved += Number(delRecall.changes);
+            // Delete the turns
+            const delTurns = this.db
+                .prepare(`DELETE FROM turns WHERE id IN (${placeholders})`)
+                .run(...ids);
+            turnsRemoved += Number(delTurns.changes);
+        }
+        // Count preserved branches
+        const branchesPreserved = this.db
+            .prepare("SELECT COUNT(*) as cnt FROM conversation_forks")
+            .get().cnt;
+        if (policy.vacuumAfterPrune && (turnsRemoved > 0 || recallRemoved > 0)) {
+            this.vacuum();
+        }
+        const afterSize = this.dbSizeBytes();
+        return {
+            turnsRemoved,
+            recallRemoved,
+            branchesPreserved,
+            freedBytes: Math.max(0, beforeSize - afterSize),
+        };
+    }
+    vacuum() {
+        this.db.exec("VACUUM");
+    }
+    checkpoint() {
+        // Query turns in row-id order (ended_at ASC with unique constraint)
+        const turnRows = this.db
+            .prepare("SELECT * FROM turns ORDER BY ended_at ASC")
+            .all();
+        const turns = turnRows.map(rowToEntry);
+        // Build mapping: row_id → 1-based position in turns array
+        const rowIdToPos = new Map();
+        for (let i = 0; i < turnRows.length; i++) {
+            rowIdToPos.set(turnRows[i].id, i + 1);
+        }
+        const recallRows = this.db
+            .prepare("SELECT * FROM turn_recall ORDER BY turn_id ASC")
+            .all();
+        // Replace recall's turnId with the 1-based position of the referenced turn
+        // in the turns array. This makes the TurnId stable across restore.
+        const recall = recallRows.map((r) => {
+            const originalTurnId = r.turn_id;
+            const stableTurnId = rowIdToPos.get(originalTurnId) ?? originalTurnId;
+            return {
+                turnId: String(stableTurnId),
+                checkpointId: r.checkpoint_id,
+                score: r.score,
+                source: r.source,
+                raptorLevel: r.raptor_level ?? undefined,
+            };
+        });
+        const forks = this.db
+            .prepare("SELECT * FROM conversation_forks ORDER BY created_at ASC")
+            .all().map(rowToFork);
+        return {
+            version: 1,
+            exportedAt: Date.now(),
+            turns,
+            recall,
+            forks,
+        };
+    }
+    restore(from) {
+        this.clear();
+        const insertTurn = this.db.prepare(`INSERT INTO turns (conversation_id, session_id, turn_index, role, ended_at,
+                               ctx_tokens, ctx_percent, pressure_band, model)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        const insertRecall = this.db.prepare(`INSERT INTO turn_recall (turn_id, checkpoint_id, score, source, raptor_level)
+       VALUES (?, ?, ?, ?, ?)`);
+        const insertFork = this.db.prepare(`INSERT INTO conversation_forks (parent_conversation_id, child_conversation_id, fork_turn_index, created_at)
+       VALUES (?, ?, ?, ?)`);
+        this.db.exec("BEGIN TRANSACTION");
+        try {
+            // Map: 1-based position → new auto-increment row ID
+            const posToNewId = new Map();
+            for (let i = 0; i < from.turns.length; i++) {
+                const t = from.turns[i];
+                insertTurn.run(t.conversationId, normalizeSessionId(t.sessionId), t.turnIndex, t.role, t.endedAt, t.ctxTokens ?? null, t.ctxPercent ?? null, t.pressureBand ?? null, t.model ?? null);
+                const row = this.db
+                    .prepare("SELECT id FROM turns WHERE conversation_id = ? AND turn_index = ?")
+                    .get(t.conversationId, t.turnIndex);
+                if (row)
+                    posToNewId.set(i + 1, row.id);
+            }
+            // Recall's turnId is now the 1-based position from checkpoint().
+            // Map it to the new row ID.
+            for (const r of from.recall) {
+                const targetTurnId = posToNewId.get(Number(r.turnId)) ?? Number(r.turnId);
+                insertRecall.run(targetTurnId, r.checkpointId, r.score, r.source, r.raptorLevel ?? null);
+            }
+            for (const f of from.forks) {
+                insertFork.run(f.parentConversationId, f.childConversationId, f.forkTurnIndex, f.createdAt);
+            }
+            this.db.exec("COMMIT");
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    clear() {
+        this.db.exec("DELETE FROM turn_recall");
+        this.db.exec("DELETE FROM conversation_forks");
+        this.db.exec("DELETE FROM turns");
+        this.db.exec("DELETE FROM session_conversations");
+        // Reset autoincrement
+        this.db.exec("DELETE FROM sqlite_sequence WHERE name IN ('turns','turn_recall','conversation_forks')");
+    }
+    stampTurnsEpoch(sessionId, epochId) {
+        const sid = normalizeSessionId(sessionId);
+        const res = this.db
+            .prepare("UPDATE turns SET epoch_id = ? WHERE session_id = ? AND epoch_id IS NULL")
+            .run(epochId, sid);
+        return Number(res.changes ?? 0);
+    }
+    // ── Capability gating ───────────────────────────────────────
+    asReader() {
+        return {
+            query: (f) => this.query(f),
+            getTurn: (id) => this.getTurn(id),
+            getTurnByIndex: (c, t) => this.getTurnByIndex(c, t),
+            listRecall: (id) => this.listRecall(id),
+            listRecallByIndex: (c, t) => this.listRecallByIndex(c, t),
+            listForks: (id) => this.listForks(id),
+            countTurns: (id) => this.countTurns(id),
+            conversationStats: (id) => this.conversationStats(id),
+        };
+    }
+    asWriter() {
+        return {
+            appendTurn: (e) => this.appendTurn(e),
+            appendRecall: (e) => this.appendRecall(e),
+            ensureConversationId: (s) => this.ensureConversationId(s),
+            forkConversation: (p, t) => this.forkConversation(p, t),
+        };
+    }
+    asAdmin() {
+        return {
+            prune: (p) => this.prune(p),
+            vacuum: () => this.vacuum(),
+            checkpoint: () => this.checkpoint(),
+            restore: (s) => this.restore(s),
+            clear: () => this.clear(),
+            stampTurnsEpoch: (s, e) => this.stampTurnsEpoch(s, e),
+        };
+    }
+    close() {
+        closeTurnDb(this.stateDir, {
+            dbPath: this.opts.dbPath,
+            inMemory: this.opts.inMemory,
+        });
+    }
+    // ── Private helpers ─────────────────────────────────────────
+    dbSizeBytes() {
+        if (this.opts.inMemory)
+            return 0;
+        try {
+            const path = this.opts.dbPath ?? join(this.stateDir, "turns.db");
+            return statSync(path).size;
+        }
+        catch {
+            return 0;
+        }
+    }
+}