@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/gateway/sessions.js

@@ -0,0 +1,701 @@
+import { randomUUID } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+/**
+ * Durable session storage on `node:sqlite`.
+ *
+ * Conventions mirror `packages/scheduler/src/store.ts`: `CREATE TABLE IF NOT
+ * EXISTS` migrations, WAL mode, foreign keys on, `node:sqlite` built-in.
+ * One instance per gateway process, backed by `<dataDir>/sessions.sqlite`.
+ *
+ * Also checkpoints HITL approval requests (`turn_approvals`): each
+ * `turn.approval_required` pause is recorded as `pending` and later resolved
+ * to `approved` | `rejected` | `timeout`. Rows still `pending` at `open()`
+ * died with the previous process (their in-memory resolvers are gone), so
+ * they are reaped as `timeout` — the history stays truthful across restarts.
+ *
+ * Message variants (P2-3, linear variant-set branching): any message can hold
+ * alternate contents in `message_variants`, keyed by
+ * `(session_id, message_id, variant_index)` with `variant_index >= 1`. The
+ * base row keeps the original content; `session_messages.select_index`
+ * (0 = base) points at the active variant. Reads (`getMessages`,
+ * `getRecentMessages`) resolve to the selected variant, so the prompt always
+ * sees the active content; the journal never loses the base row. Lighter
+ * than a branch tree: one pointer per position, no graph.
+ */
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  config_snapshot_json TEXT
+);
+CREATE TABLE IF NOT EXISTS session_messages (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system', 'tool')),
+  content TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  metadata TEXT,
+  is_checkpoint INTEGER NOT NULL DEFAULT 0,
+  select_index INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS session_messages_by_session
+  ON session_messages (session_id, created_at);
+CREATE TABLE IF NOT EXISTS message_variants (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  message_id TEXT NOT NULL REFERENCES session_messages(id) ON DELETE CASCADE,
+  variant_index INTEGER NOT NULL CHECK (variant_index >= 1),
+  content TEXT NOT NULL,
+  metadata TEXT,
+  created_at TEXT NOT NULL,
+  UNIQUE (session_id, message_id, variant_index)
+);
+CREATE INDEX IF NOT EXISTS message_variants_by_message
+  ON message_variants (message_id, variant_index);
+CREATE VIRTUAL TABLE IF NOT EXISTS session_messages_fts USING fts5(
+  content,
+  content = 'session_messages',
+  content_rowid = 'rowid',
+  tokenize = 'unicode61 remove_diacritics 2'
+);
+CREATE TRIGGER IF NOT EXISTS session_messages_fts_insert AFTER INSERT ON session_messages BEGIN
+  INSERT INTO session_messages_fts(rowid, content) VALUES (new.rowid, new.content);
+END;
+CREATE TRIGGER IF NOT EXISTS session_messages_fts_delete AFTER DELETE ON session_messages BEGIN
+  INSERT INTO session_messages_fts(session_messages_fts, rowid, content)
+  VALUES ('delete', old.rowid, old.content);
+END;
+CREATE TABLE IF NOT EXISTS turn_approvals (
+  run_id TEXT PRIMARY KEY,
+  turn_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  tool_name TEXT NOT NULL,
+  args_json TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('pending', 'approved', 'rejected', 'timeout')),
+  created_at TEXT NOT NULL,
+  resolved_at TEXT
+);
+CREATE INDEX IF NOT EXISTS turn_approvals_by_session
+  ON turn_approvals (session_id, created_at);
+`;
+const ROLES = new Set(['user', 'assistant', 'system', 'tool']);
+/** Thrown by mutating operations when the target session does not exist. */
+export class SessionNotFoundError extends Error {
+    code = 'SESSION_NOT_FOUND';
+    constructor(sessionId) {
+        super(`Session not found: ${sessionId}`);
+        this.name = 'SessionNotFoundError';
+    }
+}
+/** Thrown when a variant operation targets a message or variant that does not exist. */
+export class VariantNotFoundError extends Error {
+    code = 'VARIANT_NOT_FOUND';
+    constructor(message) {
+        super(message);
+        this.name = 'VariantNotFoundError';
+    }
+}
+function sessionFromRow(row) {
+    return {
+        id: row.id,
+        title: row.title,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        messageCount: row.message_count,
+        ...(row.config_snapshot_json == null
+            ? {}
+            : { configSnapshot: parseConfigSnapshot(row.config_snapshot_json) }),
+    };
+}
+function messageFromRow(row) {
+    const role = ROLES.has(row.role) ? row.role : 'user';
+    return {
+        id: row.id,
+        sessionId: row.session_id,
+        role,
+        content: row.content,
+        createdAt: row.created_at,
+        ...(row.metadata == null ? {} : { metadata: parseMessageMetadata(row.metadata) }),
+        ...(row.is_checkpoint === 1 ? { isCheckpoint: true } : {}),
+    };
+}
+function variantFromRow(row) {
+    return {
+        id: row.id,
+        sessionId: row.session_id,
+        messageId: row.message_id,
+        variantIndex: row.variant_index,
+        content: row.content,
+        createdAt: row.created_at,
+        ...(row.metadata == null ? {} : { metadata: parseMessageMetadata(row.metadata) }),
+    };
+}
+/**
+ * Resolve each message row to its active variant (P2-3). `select_index` 0
+ * (or a dangling pointer to a deleted variant) reads the base row; any other
+ * index swaps in the variant's content and metadata so history reads and the
+ * prompt projection always see the selected variant.
+ */
+function resolveVariants(rows, variants) {
+    const byMessage = new Map();
+    for (const variant of variants) {
+        let perMessage = byMessage.get(variant.message_id);
+        if (perMessage === undefined) {
+            perMessage = new Map();
+            byMessage.set(variant.message_id, perMessage);
+        }
+        perMessage.set(variant.variant_index, variant);
+    }
+    return rows.map((row) => {
+        const message = messageFromRow(row);
+        const selected = row.select_index ?? 0;
+        if (selected <= 0)
+            return message;
+        const variant = byMessage.get(row.id)?.get(selected);
+        if (variant === undefined)
+            return message; // fail-safe: dangling pointer reads the base row
+        // The variant fully replaces the base row: content AND tool-call
+        // metadata, so a selected variant never inherits the base message's
+        // tool_call pairing.
+        const resolved = {
+            id: message.id,
+            sessionId: message.sessionId,
+            role: message.role,
+            content: variant.content,
+            createdAt: message.createdAt,
+            variantIndex: selected,
+        };
+        if (message.isCheckpoint === true)
+            resolved.isCheckpoint = true;
+        const variantMetadata = variant.metadata == null ? undefined : parseMessageMetadata(variant.metadata);
+        if (variantMetadata !== undefined)
+            resolved.metadata = variantMetadata;
+        return resolved;
+    });
+}
+/** Fetch every variant row for the given message ids (one query, no N+1). */
+function fetchVariants(db, messageIds) {
+    if (messageIds.length === 0)
+        return [];
+    const placeholders = messageIds.map(() => '?').join(',');
+    return db
+        .prepare(`SELECT * FROM message_variants WHERE message_id IN (${placeholders}) ORDER BY variant_index ASC`)
+        .all(...messageIds);
+}
+/**
+ * Parse the `metadata` JSON column. Corrupt or unexpected shapes degrade to
+ * `undefined` (fail-safe: the message is still usable, just without pairing).
+ */
+function parseMessageMetadata(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    const metadata = {};
+    if (Array.isArray(record['toolCalls'])) {
+        const toolCalls = record['toolCalls'].filter((tc) => typeof tc === 'object' &&
+            tc !== null &&
+            typeof tc['id'] === 'string' &&
+            typeof tc['name'] === 'string');
+        if (toolCalls.length > 0)
+            metadata.toolCalls = toolCalls;
+    }
+    if (typeof record['toolCallId'] === 'string' && record['toolCallId'] !== '') {
+        metadata.toolCallId = record['toolCallId'];
+    }
+    if (typeof record['toolName'] === 'string' && record['toolName'] !== '') {
+        metadata.toolName = record['toolName'];
+    }
+    return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+/**
+ * Parse the `config_snapshot_json` column. Corrupt or unexpected shapes
+ * degrade to `undefined` (fail-safe: the session is still usable, just
+ * without its config record) — same contract as `parseMessageMetadata`.
+ */
+function parseConfigSnapshot(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    const toolsEnabled = record['toolsEnabled'];
+    const systemPromptHash = record['systemPromptHash'];
+    if (typeof toolsEnabled !== 'number' ||
+        !Number.isInteger(toolsEnabled) ||
+        toolsEnabled < 0 ||
+        typeof systemPromptHash !== 'string' ||
+        systemPromptHash === '') {
+        return undefined;
+    }
+    const model = record['model'];
+    const provider = record['provider'];
+    return {
+        ...(typeof model === 'string' && model !== '' ? { model } : {}),
+        ...(typeof provider === 'string' && provider !== '' ? { provider } : {}),
+        toolsEnabled,
+        systemPromptHash,
+    };
+}
+const APPROVAL_STATUSES = new Set(['pending', 'approved', 'rejected', 'timeout']);
+function approvalFromRow(row) {
+    const status = APPROVAL_STATUSES.has(row.status) ? row.status : 'timeout';
+    return {
+        runId: row.run_id,
+        turnId: row.turn_id,
+        sessionId: row.session_id,
+        toolName: row.tool_name,
+        argsJson: row.args_json,
+        reason: row.reason,
+        status,
+        createdAt: row.created_at,
+        resolvedAt: row.resolved_at,
+    };
+}
+function newId(prefix) {
+    return `${prefix}_${randomUUID().replace(/-/g, '')}`;
+}
+const SESSION_WITH_COUNT = `
+  SELECT s.*, (SELECT COUNT(*) FROM session_messages m WHERE m.session_id = s.id) AS message_count
+  FROM sessions s
+`;
+export class SqliteSessionStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    static open(path) {
+        const db = new DatabaseSync(path);
+        db.exec('PRAGMA journal_mode = WAL;');
+        db.exec('PRAGMA foreign_keys = ON;');
+        const hadSearchIndex = db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'session_messages_fts'`).get() !== undefined;
+        db.exec(SCHEMA_SQL);
+        // Migration for databases created before the `metadata` column existed
+        // (tool-call pairing, P0-1): `CREATE TABLE IF NOT EXISTS` never adds it.
+        const hasMetadataColumn = db
+            .prepare(`SELECT 1 FROM pragma_table_info('session_messages') WHERE name = 'metadata'`)
+            .get() !== undefined;
+        if (!hasMetadataColumn) {
+            db.exec('ALTER TABLE session_messages ADD COLUMN metadata TEXT');
+        }
+        // Migration for the context checkpoint flag (P1-6): marks the message a
+        // prompt projection must start from; older messages are dropped from the
+        // model prompt (the journal keeps them).
+        const hasCheckpointColumn = db
+            .prepare(`SELECT 1 FROM pragma_table_info('session_messages') WHERE name = 'is_checkpoint'`)
+            .get() !== undefined;
+        if (!hasCheckpointColumn) {
+            db.exec('ALTER TABLE session_messages ADD COLUMN is_checkpoint INTEGER NOT NULL DEFAULT 0');
+        }
+        // Migration for the variant-set pointer (P2-3): which variant of a
+        // message is active (0 = the base row). Old databases keep working:
+        // every existing message reads as select_index 0.
+        const hasSelectIndexColumn = db
+            .prepare(`SELECT 1 FROM pragma_table_info('session_messages') WHERE name = 'select_index'`)
+            .get() !== undefined;
+        if (!hasSelectIndexColumn) {
+            db.exec('ALTER TABLE session_messages ADD COLUMN select_index INTEGER NOT NULL DEFAULT 0');
+        }
+        // Migration for the per-session config snapshot (P1-7): point-in-time
+        // record of the model/provider/tools/system prompt serving the session.
+        const hasSnapshotColumn = db
+            .prepare(`SELECT 1 FROM pragma_table_info('sessions') WHERE name = 'config_snapshot_json'`)
+            .get() !== undefined;
+        if (!hasSnapshotColumn) {
+            db.exec('ALTER TABLE sessions ADD COLUMN config_snapshot_json TEXT');
+        }
+        if (!hadSearchIndex) {
+            db.exec(`INSERT INTO session_messages_fts(session_messages_fts) VALUES ('rebuild');`);
+        }
+        // Reap stale approvals: any request still `pending` died with the
+        // previous process — its in-memory resolver is gone, so mark `timeout`.
+        db.prepare(`UPDATE turn_approvals SET status = 'timeout', resolved_at = ? WHERE status = 'pending'`).run(new Date().toISOString());
+        return new SqliteSessionStore(db);
+    }
+    static openMemory() {
+        return SqliteSessionStore.open(':memory:');
+    }
+    close() {
+        this.db.close();
+    }
+    create(title, id) {
+        const now = new Date().toISOString();
+        const finalId = id ?? newId('ses');
+        const finalTitle = title ?? '';
+        this.db
+            .prepare('INSERT INTO sessions (id, title, created_at, updated_at) VALUES (?, ?, ?, ?)')
+            .run(finalId, finalTitle, now, now);
+        return { id: finalId, title: finalTitle, createdAt: now, updatedAt: now, messageCount: 0 };
+    }
+    list() {
+        const rows = this.db
+            .prepare(`${SESSION_WITH_COUNT} ORDER BY s.updated_at DESC, s.rowid DESC`)
+            .all();
+        return rows.map(sessionFromRow);
+    }
+    get(id) {
+        const row = this.db
+            .prepare(`${SESSION_WITH_COUNT} WHERE s.id = ?`)
+            .get(id);
+        return row === undefined ? undefined : sessionFromRow(row);
+    }
+    rename(id, title) {
+        // Single process, no await between check and write: no TOCTOU window.
+        if (this.get(id) === undefined) {
+            throw new SessionNotFoundError(id);
+        }
+        const now = new Date().toISOString();
+        this.db.prepare('UPDATE sessions SET title = ?, updated_at = ? WHERE id = ?').run(title, now, id);
+        const renamed = this.get(id);
+        if (renamed === undefined) {
+            throw new SessionNotFoundError(id);
+        }
+        return renamed;
+    }
+    branch(id, title) {
+        const source = this.get(id);
+        if (source === undefined)
+            throw new SessionNotFoundError(id);
+        const now = new Date().toISOString();
+        const branchId = newId('ses');
+        const branchTitle = (title?.trim() || `${source.title || 'Chat'} (branch)`).slice(0, 200);
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            this.db
+                .prepare('INSERT INTO sessions (id, title, created_at, updated_at) VALUES (?, ?, ?, ?)')
+                .run(branchId, branchTitle, now, now);
+            // Raw rows, not getMessages(): the branch keeps the full variant set
+            // (base content + select_index + every variant), never the resolved view.
+            const rows = this.db
+                .prepare('SELECT * FROM session_messages WHERE session_id = ? ORDER BY created_at ASC, rowid ASC')
+                .all(id);
+            const insert = this.db.prepare('INSERT INTO session_messages (id, session_id, role, content, created_at, metadata, is_checkpoint, select_index) VALUES (?, ?, ?, ?, ?, ?, ?, ?)');
+            const idMap = new Map();
+            for (const row of rows) {
+                const newMessageId = newId('msg');
+                idMap.set(row.id, newMessageId);
+                insert.run(newMessageId, branchId, row.role, row.content, row.created_at, row.metadata, row.is_checkpoint ?? 0, row.select_index ?? 0);
+            }
+            const variantRows = this.db
+                .prepare('SELECT * FROM message_variants WHERE session_id = ?')
+                .all(id);
+            const insertVariant = this.db.prepare('INSERT INTO message_variants (id, session_id, message_id, variant_index, content, metadata, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)');
+            for (const variant of variantRows) {
+                const newMessageId = idMap.get(variant.message_id);
+                if (newMessageId === undefined)
+                    continue; // defensive: orphan variant rows never cross sessions
+                insertVariant.run(newId('var'), branchId, newMessageId, variant.variant_index, variant.content, variant.metadata, variant.created_at);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // Preserve the original database error.
+            }
+            throw error;
+        }
+        const branch = this.get(branchId);
+        if (branch === undefined)
+            throw new SessionNotFoundError(branchId);
+        return branch;
+    }
+    delete(id) {
+        const result = this.db.prepare('DELETE FROM sessions WHERE id = ?').run(id);
+        return Number(result.changes) === 1;
+    }
+    /**
+     * Record the session's config snapshot (P1-7): model, provider, tool count
+     * and system prompt hash serving this session's turns. Written once — the
+     * turn service only calls this while the snapshot is still absent — so
+     * later config drift cannot rewrite history.
+     */
+    setConfigSnapshot(sessionId, snapshot) {
+        if (this.get(sessionId) === undefined) {
+            throw new SessionNotFoundError(sessionId);
+        }
+        this.db
+            .prepare('UPDATE sessions SET config_snapshot_json = ?, updated_at = ? WHERE id = ?')
+            .run(JSON.stringify(snapshot), new Date().toISOString(), sessionId);
+        const updated = this.get(sessionId);
+        if (updated === undefined) {
+            throw new SessionNotFoundError(sessionId);
+        }
+        return updated;
+    }
+    /**
+     * Mark a message as a context checkpoint (P1-6). Prompt projection drops
+     * every message before the newest checkpoint; the journal keeps them.
+     * With no `messageId` the latest message becomes the checkpoint. Earlier
+     * checkpoints are kept (append-only journal) — only the newest one cuts.
+     */
+    markCheckpoint(sessionId, messageId) {
+        if (this.get(sessionId) === undefined) {
+            throw new SessionNotFoundError(sessionId);
+        }
+        let target;
+        if (messageId === undefined) {
+            const rows = this.db
+                .prepare(`SELECT * FROM session_messages
+           WHERE session_id = ?
+           ORDER BY created_at DESC, rowid DESC LIMIT 1`)
+                .all(sessionId);
+            target = rows.length === 0 ? undefined : messageFromRow(rows[0]);
+        }
+        else {
+            const row = this.db
+                .prepare('SELECT * FROM session_messages WHERE id = ? AND session_id = ?')
+                .get(messageId, sessionId);
+            target = row === undefined ? undefined : messageFromRow(row);
+        }
+        if (target === undefined) {
+            throw new Error(messageId === undefined
+                ? `Cannot checkpoint an empty session: ${sessionId}`
+                : `Message not found in session ${sessionId}: ${messageId}`);
+        }
+        this.db.prepare('UPDATE session_messages SET is_checkpoint = 1 WHERE id = ?').run(target.id);
+        return { ...target, isCheckpoint: true };
+    }
+    /**
+     * Append a new variant at a message position (P2-3). The variant index is
+     * assigned as max+1 (starting at 1); creating a variant never moves
+     * `select_index` — selecting stays an explicit `selectVariant` call.
+     */
+    createVariant(sessionId, messageId, content, metadata) {
+        if (this.get(sessionId) === undefined) {
+            throw new SessionNotFoundError(sessionId);
+        }
+        const anchor = this.readMessageRow(sessionId, messageId);
+        if (anchor === undefined) {
+            throw new VariantNotFoundError(`Message not found in session ${sessionId}: ${messageId}`);
+        }
+        if (typeof content !== 'string') {
+            throw new Error('Variant content must be a string');
+        }
+        const maxIndex = this.db
+            .prepare('SELECT COALESCE(MAX(variant_index), 0) AS max_index FROM message_variants WHERE message_id = ?')
+            .get(anchor.id);
+        const now = new Date().toISOString();
+        const id = newId('var');
+        const variantIndex = Number(maxIndex.max_index) + 1;
+        this.db
+            .prepare('INSERT INTO message_variants (id, session_id, message_id, variant_index, content, metadata, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
+            .run(id, sessionId, anchor.id, variantIndex, content, metadata === undefined ? null : JSON.stringify(metadata), now);
+        this.db.prepare('UPDATE sessions SET updated_at = ? WHERE id = ?').run(now, sessionId);
+        return {
+            id,
+            sessionId,
+            messageId: anchor.id,
+            variantIndex,
+            content,
+            createdAt: now,
+            ...(metadata === undefined ? {} : { metadata }),
+        };
+    }
+    /**
+     * List every variant stored at a message position, oldest first.
+     * The base row (index 0) is not a variant and is not listed.
+     */
+    listVariants(sessionId, messageId) {
+        if (this.get(sessionId) === undefined) {
+            throw new SessionNotFoundError(sessionId);
+        }
+        const anchor = this.readMessageRow(sessionId, messageId);
+        if (anchor === undefined) {
+            throw new VariantNotFoundError(`Message not found in session ${sessionId}: ${messageId}`);
+        }
+        const rows = this.db
+            .prepare('SELECT * FROM message_variants WHERE session_id = ? AND message_id = ? ORDER BY variant_index ASC')
+            .all(sessionId, anchor.id);
+        return rows.map(variantFromRow);
+    }
+    /**
+     * Point `select_index` at a variant (P2-3). Index 0 re-selects the base
+     * row; any other index must already exist. Returns the message resolved
+     * to the newly selected content — the same shape history reads return.
+     */
+    selectVariant(sessionId, messageId, variantIndex) {
+        if (this.get(sessionId) === undefined) {
+            throw new SessionNotFoundError(sessionId);
+        }
+        const anchor = this.readMessageRow(sessionId, messageId);
+        if (anchor === undefined) {
+            throw new VariantNotFoundError(`Message not found in session ${sessionId}: ${messageId}`);
+        }
+        if (!Number.isInteger(variantIndex) || variantIndex < 0) {
+            throw new Error(`Variant index must be a non-negative integer, got: ${String(variantIndex)}`);
+        }
+        if (variantIndex > 0) {
+            const exists = this.db
+                .prepare('SELECT 1 FROM message_variants WHERE session_id = ? AND message_id = ? AND variant_index = ?')
+                .get(sessionId, anchor.id, variantIndex) !== undefined;
+            if (!exists) {
+                throw new VariantNotFoundError(`Variant ${variantIndex} does not exist at message ${messageId} in session ${sessionId}`);
+            }
+        }
+        this.db
+            .prepare('UPDATE session_messages SET select_index = ? WHERE id = ?')
+            .run(variantIndex, anchor.id);
+        this.db
+            .prepare('UPDATE sessions SET updated_at = ? WHERE id = ?')
+            .run(new Date().toISOString(), sessionId);
+        const resolved = this.readMessageRow(sessionId, anchor.id);
+        if (resolved === undefined)
+            throw new VariantNotFoundError(`Message vanished: ${messageId}`);
+        return resolveVariants([resolved], fetchVariants(this.db, variantIndex > 0 ? [resolved.id] : []))[0];
+    }
+    /**
+     * Raw message row for this session, or `undefined`. Used by variant
+     * operations so they work on the stored row, never the resolved view.
+     */
+    readMessageRow(sessionId, messageId) {
+        return this.db
+            .prepare('SELECT * FROM session_messages WHERE id = ? AND session_id = ?')
+            .get(messageId, sessionId);
+    }
+    undoLastExchange(id) {
+        if (this.get(id) === undefined)
+            throw new SessionNotFoundError(id);
+        const boundary = this.db
+            .prepare(`SELECT rowid FROM session_messages
+         WHERE session_id = ? AND role = 'user'
+         ORDER BY created_at DESC, rowid DESC LIMIT 1`)
+            .get(id);
+        if (boundary === undefined)
+            return 0;
+        let removedCount = 0;
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = this.db
+                .prepare('DELETE FROM session_messages WHERE session_id = ? AND rowid >= ?')
+                .run(id, boundary.rowid);
+            removedCount = Number(result.changes);
+            this.db
+                .prepare('UPDATE sessions SET updated_at = ? WHERE id = ?')
+                .run(new Date().toISOString(), id);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                // Preserve the original database error.
+            }
+            throw error;
+        }
+        return removedCount;
+    }
+    appendMessage(sessionId, role, text, metadata) {
+        if (!ROLES.has(role)) {
+            throw new Error(`Invalid session message role: ${String(role)}`);
+        }
+        // Single process, no await between check and write: no TOCTOU window.
+        if (this.get(sessionId) === undefined) {
+            throw new SessionNotFoundError(sessionId);
+        }
+        const now = new Date().toISOString();
+        const id = newId('msg');
+        this.db
+            .prepare('INSERT INTO session_messages (id, session_id, role, content, created_at, metadata) VALUES (?, ?, ?, ?, ?, ?)')
+            .run(id, sessionId, role, text, now, metadata === undefined ? null : JSON.stringify(metadata));
+        this.db.prepare('UPDATE sessions SET updated_at = ? WHERE id = ?').run(now, sessionId);
+        return {
+            id,
+            sessionId,
+            role,
+            content: text,
+            createdAt: now,
+            ...(metadata === undefined ? {} : { metadata }),
+        };
+    }
+    getMessages(sessionId) {
+        const rows = this.db
+            .prepare('SELECT * FROM session_messages WHERE session_id = ? ORDER BY created_at ASC, rowid ASC')
+            .all(sessionId);
+        // P2-3: history reads resolve to the selected variant, so the journal
+        // and the prompt projection (via the session adapter) see the same
+        // active content.
+        return resolveVariants(rows, fetchVariants(this.db, rows.filter((row) => (row.select_index ?? 0) > 0).map((row) => row.id)));
+    }
+    getRecentMessages(sessionId, limit) {
+        const boundedLimit = Math.min(1_000, Math.max(1, Math.trunc(limit)));
+        const rows = this.db.prepare(`
+      SELECT id, session_id, role, content, created_at, metadata, is_checkpoint, select_index FROM (
+        SELECT rowid AS sort_rowid, * FROM session_messages
+        WHERE session_id = ?
+        ORDER BY created_at DESC, rowid DESC
+        LIMIT ?
+      )
+      ORDER BY created_at ASC, sort_rowid ASC
+    `).all(sessionId, boundedLimit);
+        return resolveVariants(rows, fetchVariants(this.db, rows.filter((row) => (row.select_index ?? 0) > 0).map((row) => row.id)));
+    }
+    searchMessages(query, limit = 5) {
+        const terms = query.trim().match(/[\p{L}\p{N}_]+/gu)?.slice(0, 16) ?? [];
+        if (terms.length === 0)
+            return [];
+        const boundedLimit = Math.min(20, Math.max(1, Math.trunc(limit)));
+        const match = terms.map((term) => `"${term.replaceAll('"', '""')}"*`).join(' AND ');
+        const rows = this.db.prepare(`
+      SELECT m.id AS message_id, m.session_id, s.title AS session_title, m.role,
+             snippet(session_messages_fts, 0, '[', ']', ' … ', 24) AS excerpt,
+             m.created_at
+      FROM session_messages_fts
+      JOIN session_messages m ON m.rowid = session_messages_fts.rowid
+      JOIN sessions s ON s.id = m.session_id
+      WHERE session_messages_fts MATCH ?
+      ORDER BY bm25(session_messages_fts), m.created_at DESC
+      LIMIT ?
+    `).all(match, boundedLimit);
+        return rows.map((row) => ({
+            messageId: row.message_id,
+            sessionId: row.session_id,
+            sessionTitle: row.session_title,
+            role: ROLES.has(row.role) ? row.role : 'user',
+            excerpt: row.excerpt,
+            createdAt: row.created_at,
+        }));
+    }
+    /**
+     * Checkpoint a new HITL approval request as `pending`. Called by the turn
+     * service right after publishing `turn.approval_required`.
+     */
+    recordApprovalRequest(row) {
+        const now = new Date().toISOString();
+        this.db
+            .prepare(`INSERT INTO turn_approvals
+           (run_id, turn_id, session_id, tool_name, args_json, reason, status, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, 'pending', ?)`)
+            .run(row.runId, row.turnId, row.sessionId, row.toolName, row.argsJson, row.reason, now);
+    }
+    /** Resolve a checkpointed approval request (`approved` | `rejected` | `timeout`). */
+    resolveApproval(runId, status, resolvedAt) {
+        this.db
+            .prepare('UPDATE turn_approvals SET status = ?, resolved_at = ? WHERE run_id = ?')
+            .run(status, resolvedAt, runId);
+    }
+    /** Fetch one checkpointed approval request, if it exists. */
+    getApproval(runId) {
+        const row = this.db
+            .prepare('SELECT * FROM turn_approvals WHERE run_id = ?')
+            .get(runId);
+        return row === undefined ? undefined : approvalFromRow(row);
+    }
+}