@mquan/portal 0.0.1

package/dist/src/storage/repository.js

@@ -0,0 +1,1291 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { cosineSimilarity, embeddingBuckets } from "../recall/embedding.js";
+const DEFAULT_INSTALLATION = "local";
+const DEFAULT_ACCOUNT = "default";
+export class PortalRepository {
+    database;
+    constructor(database) {
+        this.database = database;
+    }
+    upsertSession(input) {
+        const installation = input.installation ?? DEFAULT_INSTALLATION;
+        const accountFingerprint = input.accountFingerprint ?? DEFAULT_ACCOUNT;
+        const portalSessionId = stableId("ps", input.provider, installation, accountFingerprint, input.vendorSessionId);
+        this.database.connection
+            .prepare(`
+        INSERT INTO sessions (
+          portal_session_id, provider, installation, account_fingerprint,
+          vendor_session_id, workspace, title, managed_name, observed_at, updated_at, state,
+          state_confidence, indexed, connected, messageable
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(provider, installation, account_fingerprint, vendor_session_id)
+        DO UPDATE SET
+          workspace = excluded.workspace,
+          title = excluded.title,
+          managed_name = coalesce(excluded.managed_name, sessions.managed_name),
+          observed_at = excluded.observed_at,
+          updated_at = excluded.updated_at,
+          state = excluded.state,
+          state_confidence = excluded.state_confidence,
+          indexed = max(sessions.indexed, excluded.indexed),
+          connected = excluded.connected,
+          messageable = excluded.messageable
+      `)
+            .run(portalSessionId, input.provider, installation, accountFingerprint, input.vendorSessionId, input.workspace, input.title, input.managedName ?? null, (input.observedAt ?? new Date()).getTime(), toEpoch(input.updatedAt), input.state, input.stateConfidence, Number(input.indexed), Number(input.connected), Number(input.messageable));
+        const stored = this.findSession({
+            provider: input.provider,
+            installation,
+            accountFingerprint,
+            vendorSessionId: input.vendorSessionId,
+        });
+        if (stored === null)
+            throw new Error(`failed to load upserted session ${portalSessionId}`);
+        return stored;
+    }
+    getSession(portalSessionId) {
+        const row = this.database.connection
+            .prepare("SELECT * FROM sessions WHERE portal_session_id = ?")
+            .get(portalSessionId);
+        return row === undefined ? null : mapSession(row);
+    }
+    bindSessionVendorId(portalSessionId, vendorSessionId) {
+        if (vendorSessionId.trim().length === 0)
+            throw new TypeError("vendor session ID cannot be empty");
+        try {
+            const changed = this.database.connection
+                .prepare("UPDATE sessions SET vendor_session_id = ?, observed_at = ? WHERE portal_session_id = ?")
+                .run(vendorSessionId, Date.now(), portalSessionId);
+            if (Number(changed.changes) !== 1)
+                throw new Error(`unknown Portal session: ${portalSessionId}`);
+        }
+        catch (error) {
+            if (String(error).includes("UNIQUE constraint failed")) {
+                throw new Error(`Codex session is already bound in Portal: ${vendorSessionId}`);
+            }
+            throw error;
+        }
+        const session = this.getSession(portalSessionId);
+        if (session === null)
+            throw new Error(`failed to bind Portal session: ${portalSessionId}`);
+        return session;
+    }
+    findSession(identity) {
+        const row = this.database.connection
+            .prepare(`
+        SELECT * FROM sessions
+        WHERE provider = ? AND installation = ? AND account_fingerprint = ?
+          AND vendor_session_id = ?
+      `)
+            .get(identity.provider, identity.installation ?? DEFAULT_INSTALLATION, identity.accountFingerprint ?? DEFAULT_ACCOUNT, identity.vendorSessionId);
+        return row === undefined ? null : mapSession(row);
+    }
+    listSessions(workspace) {
+        const rows = (workspace === undefined
+            ? this.database.connection.prepare("SELECT * FROM sessions ORDER BY updated_at DESC").all()
+            : this.database.connection
+                .prepare("SELECT * FROM sessions WHERE workspace = ? ORDER BY updated_at DESC")
+                .all(workspace));
+        return rows.map(mapSession);
+    }
+    upsertSessionProfile(input) {
+        if (this.getSession(input.sessionId) === null) {
+            throw new Error(`unknown Portal session: ${input.sessionId}`);
+        }
+        const displayName = input.displayName.trim();
+        if (displayName.length === 0)
+            throw new TypeError("session profile display name cannot be empty");
+        const topics = input.topics.map((topic) => topic.trim()).filter((topic) => topic.length > 0);
+        const updatedAt = input.updatedAt ?? new Date();
+        if (!Number.isFinite(updatedAt.getTime()))
+            throw new TypeError("session profile updatedAt is invalid");
+        this.database.connection.prepare(`
+      INSERT INTO session_profiles (
+        session_id, display_name, description, topics_json, source,
+        transcript_watermark, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(session_id) DO UPDATE SET
+        display_name = excluded.display_name,
+        description = excluded.description,
+        topics_json = excluded.topics_json,
+        source = excluded.source,
+        transcript_watermark = excluded.transcript_watermark,
+        updated_at = excluded.updated_at
+    `).run(input.sessionId, displayName, input.description.trim(), JSON.stringify(topics), input.source, input.transcriptWatermark, updatedAt.getTime());
+        const profile = this.getSessionProfile(input.sessionId);
+        if (profile === null)
+            throw new Error(`failed to upsert session profile: ${input.sessionId}`);
+        return profile;
+    }
+    getSessionProfile(sessionId) {
+        const row = this.database.connection
+            .prepare("SELECT * FROM session_profiles WHERE session_id = ?")
+            .get(sessionId);
+        return row === undefined ? null : mapSessionProfile(row);
+    }
+    listSessionProfiles(workspace) {
+        const rows = (workspace === undefined
+            ? this.database.connection
+                .prepare("SELECT * FROM session_profiles ORDER BY updated_at DESC, session_id")
+                .all()
+            : this.database.connection.prepare(`
+          SELECT p.* FROM session_profiles p
+          JOIN sessions s ON s.portal_session_id = p.session_id
+          WHERE s.workspace = ?
+          ORDER BY p.updated_at DESC, p.session_id
+        `).all(workspace));
+        return rows.map(mapSessionProfile);
+    }
+    ingestTranscript(portalSessionId, entries) {
+        const owningSession = this.getSession(portalSessionId);
+        if (owningSession === null) {
+            throw new Error(`unknown Portal session: ${portalSessionId}`);
+        }
+        const result = { inserted: 0, updated: 0, unchanged: 0, removed: 0, chunkIds: [] };
+        const now = Date.now();
+        this.database.transaction(() => {
+            const findEntry = this.database.connection.prepare("SELECT entry_id, content_hash FROM transcript_entries WHERE session_id = ? AND source_id = ?");
+            const insertEntry = this.database.connection.prepare(`
+        INSERT INTO transcript_entries (
+          entry_id, session_id, source_id, role, text, occurred_at,
+          content_hash, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+            const updateEntry = this.database.connection.prepare(`
+        UPDATE transcript_entries
+        SET role = ?, text = ?, occurred_at = ?, content_hash = ?, updated_at = ?
+        WHERE entry_id = ?
+      `);
+            const deleteChunks = this.database.connection.prepare("DELETE FROM chunks WHERE first_entry_id = ?");
+            const insertChunk = this.database.connection.prepare(`
+        INSERT INTO chunks (
+          chunk_id, session_id, first_entry_id, last_entry_id, ordinal,
+          text, content_hash, occurred_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+            this.database.connection.exec(`
+        CREATE TEMP TABLE IF NOT EXISTS portal_current_transcript_sources (
+          source_id TEXT PRIMARY KEY
+        ) WITHOUT ROWID;
+        DELETE FROM portal_current_transcript_sources;
+      `);
+            const markSourcePresent = this.database.connection.prepare("INSERT OR IGNORE INTO portal_current_transcript_sources(source_id) VALUES (?)");
+            for (const entry of entries) {
+                markSourcePresent.run(entry.sourceId);
+                if (entry.vendorSessionId.length > 0) {
+                    if (owningSession.vendorSessionId !== entry.vendorSessionId) {
+                        throw new Error(`transcript entry ${entry.sourceId} belongs to ${entry.vendorSessionId}, expected ${owningSession.vendorSessionId}`);
+                    }
+                }
+                const entryId = stableId("te", portalSessionId, entry.sourceId);
+                const contentHash = digest(entry.role, entry.text, entry.occurredAt?.toISOString() ?? "");
+                const existing = findEntry.get(portalSessionId, entry.sourceId);
+                if (existing?.content_hash === contentHash) {
+                    result.unchanged += 1;
+                    continue;
+                }
+                if (existing === undefined) {
+                    insertEntry.run(entryId, portalSessionId, entry.sourceId, entry.role, entry.text, toEpoch(entry.occurredAt), contentHash, now, now);
+                    result.inserted += 1;
+                }
+                else {
+                    updateEntry.run(entry.role, entry.text, toEpoch(entry.occurredAt), contentHash, now, existing.entry_id);
+                    deleteChunks.run(existing.entry_id);
+                    result.updated += 1;
+                }
+                const chunks = splitIntoChunks(entry.text);
+                for (let ordinal = 0; ordinal < chunks.length; ordinal += 1) {
+                    const text = chunks[ordinal];
+                    if (text === undefined)
+                        continue;
+                    const chunkHash = digest(text);
+                    const chunkId = stableId("ch", entryId, String(ordinal), chunkHash);
+                    insertChunk.run(chunkId, portalSessionId, entryId, entryId, ordinal, text, chunkHash, toEpoch(entry.occurredAt));
+                    result.chunkIds.push(chunkId);
+                }
+            }
+            const removed = this.database.connection.prepare(`
+        DELETE FROM transcript_entries
+        WHERE session_id = ?
+          AND NOT EXISTS (
+            SELECT 1 FROM portal_current_transcript_sources current
+            WHERE current.source_id = transcript_entries.source_id
+          )
+      `).run(portalSessionId);
+            result.removed = Number(removed.changes);
+        });
+        return result;
+    }
+    markSessionIndexed(portalSessionId) {
+        const changed = this.database.connection
+            .prepare("UPDATE sessions SET indexed = 1 WHERE portal_session_id = ?")
+            .run(portalSessionId);
+        if (Number(changed.changes) !== 1)
+            throw new Error(`unknown Portal session: ${portalSessionId}`);
+    }
+    chunksNeedingEmbedding(portalSessionId, model) {
+        const rows = this.database.connection
+            .prepare(`
+        SELECT chunk_id, session_id, text, embedding_model, embedding_json
+        FROM chunks
+        WHERE session_id = ? AND (embedding_model IS NULL OR embedding_model != ?)
+        ORDER BY occurred_at, chunk_id
+      `)
+            .all(portalSessionId, model);
+        return rows.map(mapChunk);
+    }
+    saveEmbedding(chunkId, model, vector) {
+        this.saveEmbeddings(model, [{ chunkId, vector }]);
+    }
+    saveEmbeddings(model, embeddings) {
+        for (const { vector } of embeddings) {
+            if (vector.some((value) => !Number.isFinite(value))) {
+                throw new TypeError("embedding contains a non-finite value");
+            }
+        }
+        if (embeddings.length === 0)
+            return;
+        this.database.transaction(() => {
+            const update = this.database.connection.prepare("UPDATE chunks SET embedding_model = ?, embedding_json = ? WHERE chunk_id = ?");
+            const removeBuckets = this.database.connection.prepare("DELETE FROM embedding_buckets WHERE chunk_id = ?");
+            const insert = this.database.connection.prepare("INSERT INTO embedding_buckets(model, bucket, chunk_id) VALUES (?, ?, ?)");
+            for (const { chunkId, vector } of embeddings) {
+                const changed = update.run(model, JSON.stringify(Array.from(vector)), chunkId);
+                if (Number(changed.changes) !== 1)
+                    throw new Error(`unknown chunk: ${chunkId}`);
+                removeBuckets.run(chunkId);
+                for (const bucket of embeddingBuckets(vector))
+                    insert.run(model, bucket, chunkId);
+            }
+        });
+    }
+    lexicalCandidates(ftsQuery, query) {
+        if (ftsQuery.length === 0)
+            return [];
+        const { sql, parameters } = candidateSql(query, true);
+        const rows = this.database.connection
+            .prepare(sql)
+            .all(ftsQuery, query.workspace, ...parameters, query.limit);
+        return rows.map((row) => ({
+            chunkId: row.chunk_id,
+            text: row.text,
+            lexicalRank: row.lexical_rank,
+            citation: mapCitation(row),
+        }));
+    }
+    semanticCandidates(model, vector, query) {
+        const buckets = embeddingBuckets(vector);
+        if (buckets.length === 0)
+            return [];
+        const providerClause = providerFilter(query.providers);
+        const timeClause = timeFilter(query);
+        const placeholders = buckets.map(() => "?").join(", ");
+        const sql = `
+      SELECT
+        c.chunk_id, c.text, c.embedding_json,
+        s.portal_session_id, s.vendor_session_id, s.provider, s.workspace,
+        e.source_id, e.entry_id, c.occurred_at,
+        count(*) AS bucket_hits
+      FROM embedding_buckets b
+      JOIN chunks c ON c.chunk_id = b.chunk_id
+      JOIN sessions s ON s.portal_session_id = c.session_id
+      JOIN transcript_entries e ON e.entry_id = c.first_entry_id
+      WHERE b.model = ? AND b.bucket IN (${placeholders})
+        AND s.workspace = ?
+        ${providerClause.sql}
+        ${timeClause.sql}
+      GROUP BY c.chunk_id
+      ORDER BY bucket_hits DESC
+      LIMIT ?
+    `;
+        const rows = this.database.connection
+            .prepare(sql)
+            .all(model, ...buckets, query.workspace, ...providerClause.parameters, ...timeClause.parameters, query.limit);
+        return rows
+            .map((row) => ({
+            chunkId: row.chunk_id,
+            text: row.text,
+            similarity: cosineSimilarity(vector, JSON.parse(row.embedding_json)),
+            citation: mapCitation(row),
+        }))
+            .filter(({ similarity }) => similarity > 0.01)
+            .sort((left, right) => right.similarity - left.similarity || left.chunkId.localeCompare(right.chunkId));
+    }
+    explainLexicalQuery(ftsQuery, query) {
+        const { sql, parameters } = candidateSql(query, true);
+        const rows = this.database.connection
+            .prepare(`EXPLAIN QUERY PLAN ${sql}`)
+            .all(ftsQuery, query.workspace, ...parameters, query.limit);
+        return rows.map(({ detail }) => detail);
+    }
+    workspaceFreshness(workspace) {
+        const row = this.database.connection
+            .prepare(`
+        SELECT max(e.updated_at) AS freshness
+        FROM transcript_entries e
+        JOIN sessions s ON s.portal_session_id = e.session_id
+        WHERE s.workspace = ?
+      `)
+            .get(workspace);
+        return fromEpoch(row?.freshness ?? null);
+    }
+    upsertCursor(input) {
+        const updatedAt = Date.now();
+        this.database.connection
+            .prepare(`
+        INSERT INTO ingestion_cursors (
+          provider, source_scope, cursor, watermark, last_success, last_error, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(provider, source_scope) DO UPDATE SET
+          cursor = excluded.cursor,
+          watermark = excluded.watermark,
+          last_success = excluded.last_success,
+          last_error = excluded.last_error,
+          updated_at = excluded.updated_at
+      `)
+            .run(input.provider, input.sourceScope, input.cursor, input.watermark, toEpoch(input.lastSuccess), input.lastError, updatedAt);
+        const cursor = this.getCursor(input.provider, input.sourceScope);
+        if (cursor === null)
+            throw new Error("failed to upsert ingestion cursor");
+        return cursor;
+    }
+    getCursor(provider, sourceScope) {
+        const row = this.database.connection
+            .prepare("SELECT * FROM ingestion_cursors WHERE provider = ? AND source_scope = ?")
+            .get(provider, sourceScope);
+        if (row === undefined)
+            return null;
+        return {
+            provider: row.provider,
+            sourceScope: row.source_scope,
+            cursor: row.cursor,
+            watermark: row.watermark,
+            lastSuccess: fromEpoch(row.last_success),
+            lastError: row.last_error,
+            updatedAt: new Date(row.updated_at),
+        };
+    }
+    countTranscriptEntries(sessionId) {
+        const row = this.database.connection
+            .prepare("SELECT count(*) AS count FROM transcript_entries WHERE session_id = ?")
+            .get(sessionId);
+        return row.count;
+    }
+    enqueueMessage(input) {
+        const sender = this.getSession(input.senderSessionId);
+        const target = this.getSession(input.targetSessionId);
+        if (sender === null || target === null)
+            throw new Error("message sender and target must exist");
+        if (sender.workspace === null || sender.workspace !== target.workspace) {
+            throw new Error("cross-workspace messages are not allowed");
+        }
+        if (input.idempotencyKey.length > 200)
+            throw new Error("message idempotency key is too long");
+        if (input.replyTo !== undefined && input.replyTo !== null) {
+            this.validateReply(input.replyTo, sender.workspace, input.senderSessionId, input.targetSessionId, 4);
+        }
+        const prior = this.getMessageByIdempotency(input.senderSessionId, input.idempotencyKey);
+        if (prior !== null) {
+            if (prior.targetSessionId !== input.targetSessionId ||
+                prior.body !== input.body ||
+                prior.replyTo !== (input.replyTo ?? null)) {
+                throw new Error("message idempotency key was reused with a different payload");
+            }
+            return prior;
+        }
+        const messageId = stableId("msg", input.senderSessionId, input.idempotencyKey);
+        this.database.connection
+            .prepare(`
+        INSERT INTO messages (
+          message_id, sender_session_id, target_session_id, body, state,
+          created_at, reply_to, idempotency_key
+        ) VALUES (?, ?, ?, ?, 'queued', ?, ?, ?)
+        ON CONFLICT(sender_session_id, idempotency_key) DO NOTHING
+      `)
+            .run(messageId, input.senderSessionId, input.targetSessionId, input.body, Date.now(), input.replyTo ?? null, input.idempotencyKey);
+        const stored = this.getMessage(messageId);
+        if (stored === null)
+            throw new Error("failed to enqueue message");
+        return stored;
+    }
+    createMessageIdempotencyKey() {
+        return randomUUID();
+    }
+    countMessagesSince(senderSessionId, since) {
+        const row = this.database.connection
+            .prepare("SELECT count(*) AS count FROM messages WHERE sender_session_id = ? AND created_at >= ?")
+            .get(senderSessionId, since.getTime());
+        return row.count;
+    }
+    hasRunningDelivery(senderSessionId, targetSessionId) {
+        const row = this.database.connection.prepare(`
+      SELECT 1 AS running FROM messages m
+      JOIN message_receipts r ON r.message_id = m.message_id
+      WHERE m.sender_session_id = ? AND m.target_session_id = ?
+        AND m.state = 'delivering' AND r.status = 'running'
+      LIMIT 1
+    `).get(senderSessionId, targetSessionId);
+        return row?.running === 1;
+    }
+    getMessage(messageId) {
+        const row = this.database.connection
+            .prepare("SELECT * FROM messages WHERE message_id = ?")
+            .get(messageId);
+        return row === undefined ? null : mapMessage(row);
+    }
+    getMessageByIdempotency(senderSessionId, idempotencyKey) {
+        const row = this.database.connection
+            .prepare("SELECT * FROM messages WHERE sender_session_id = ? AND idempotency_key = ?")
+            .get(senderSessionId, idempotencyKey);
+        return row === undefined ? null : mapMessage(row);
+    }
+    updateMessageState(messageId, state, options = {}) {
+        const change = this.database.connection
+            .prepare("UPDATE messages SET state = ?, delivered_at = ?, error = ? WHERE message_id = ?")
+            .run(state, toEpoch(options.deliveredAt ?? null), options.error ?? null, messageId);
+        if (Number(change.changes) !== 1)
+            throw new Error(`unknown message: ${messageId}`);
+        const message = this.getMessage(messageId);
+        if (message === null)
+            throw new Error(`failed to load message: ${messageId}`);
+        return message;
+    }
+    listInbox(targetSessionId, state) {
+        const rows = (state === undefined
+            ? this.database.connection
+                .prepare("SELECT * FROM messages WHERE target_session_id = ? ORDER BY created_at, message_id")
+                .all(targetSessionId)
+            : this.database.connection
+                .prepare("SELECT * FROM messages WHERE target_session_id = ? AND state = ? ORDER BY created_at, message_id")
+                .all(targetSessionId, state));
+        return rows.map(mapMessage);
+    }
+    receiveQueuedMessages(targetSessionId, acknowledgements = [], claimTtlMs = 60_000) {
+        if (acknowledgements.length > 100)
+            throw new Error("at most 100 inbox messages can be acknowledged at once");
+        const claimedAt = Date.now();
+        const staleBefore = claimedAt - claimTtlMs;
+        return this.database.transaction(() => {
+            const acknowledge = this.database.connection.prepare(`
+        UPDATE messages
+        SET state = 'delivered', delivered_at = ?, delivery_claimed_at = NULL, error = NULL
+        WHERE message_id = ? AND target_session_id = ? AND state = 'delivering'
+      `);
+            for (const messageId of new Set(acknowledgements)) {
+                acknowledge.run(claimedAt, messageId, targetSessionId);
+            }
+            const rows = this.database.connection
+                .prepare(`
+          SELECT * FROM messages
+          WHERE target_session_id = ? AND (
+            state = 'queued' OR
+            (state = 'delivering' AND delivery_claimed_at IS NOT NULL AND delivery_claimed_at <= ?)
+          )
+          ORDER BY created_at, message_id
+        `)
+                .all(targetSessionId, staleBefore);
+            const claim = this.database.connection.prepare(`
+        UPDATE messages
+        SET state = 'delivering', delivery_claimed_at = ?, delivery_attempts = delivery_attempts + 1, error = NULL
+        WHERE message_id = ? AND target_session_id = ? AND (
+          state = 'queued' OR
+          (state = 'delivering' AND delivery_claimed_at IS NOT NULL AND delivery_claimed_at <= ?)
+        )
+      `);
+            const received = [];
+            for (const row of rows) {
+                const changed = claim.run(claimedAt, row.message_id, targetSessionId, staleBefore);
+                if (Number(changed.changes) === 1) {
+                    received.push(mapMessage({ ...row, state: "delivering", delivered_at: null }));
+                }
+            }
+            return received;
+        });
+    }
+    touchRunnerLease(sessionId, ttlMs = 45_000) {
+        if (this.getSession(sessionId) === null)
+            throw new Error(`unknown Portal session: ${sessionId}`);
+        const now = Date.now();
+        const expiresAt = new Date(now + ttlMs);
+        this.database.connection.prepare(`
+      INSERT INTO runner_leases (session_id, last_seen, expires_at) VALUES (?, ?, ?)
+      ON CONFLICT(session_id) DO UPDATE SET last_seen = excluded.last_seen, expires_at = excluded.expires_at
+    `).run(sessionId, now, expiresAt.getTime());
+        return expiresAt;
+    }
+    hasActiveRunnerLease(sessionId, now = new Date()) {
+        const row = this.database.connection
+            .prepare("SELECT 1 AS active FROM runner_leases WHERE session_id = ? AND expires_at > ?")
+            .get(sessionId, now.getTime());
+        return row?.active === 1;
+    }
+    clearRunnerLease(sessionId) {
+        this.database.connection.prepare("DELETE FROM runner_leases WHERE session_id = ?").run(sessionId);
+    }
+    claimNextRunnerMessage(targetSessionId, claimTtlMs = 60_000) {
+        const now = Date.now();
+        const staleBefore = now - claimTtlMs;
+        return this.database.transaction(() => {
+            const row = this.database.connection.prepare(`
+        SELECT * FROM messages
+        WHERE target_session_id = ? AND (
+          state = 'queued' OR (state = 'delivering' AND delivery_claimed_at <= ?
+            AND NOT EXISTS (SELECT 1 FROM message_receipts r WHERE r.message_id = messages.message_id AND r.status = 'running'))
+        )
+        ORDER BY created_at, message_id LIMIT 1
+      `).get(targetSessionId, staleBefore);
+            if (row === undefined)
+                return null;
+            const changed = this.database.connection.prepare(`
+        UPDATE messages SET state = 'delivering', delivery_claimed_at = ?,
+          delivery_attempts = delivery_attempts + 1, error = NULL
+        WHERE message_id = ? AND target_session_id = ? AND (
+          state = 'queued' OR (state = 'delivering' AND delivery_claimed_at <= ?)
+        )
+      `).run(now, row.message_id, targetSessionId, staleBefore);
+            if (Number(changed.changes) !== 1)
+                return null;
+            this.database.connection.prepare(`
+        INSERT INTO message_receipts(message_id, status) VALUES (?, 'claimed')
+        ON CONFLICT(message_id) DO UPDATE SET status = 'claimed', error = NULL
+      `).run(row.message_id);
+            return mapMessage({ ...row, state: "delivering", delivered_at: null });
+        });
+    }
+    markRunnerMessageReceived(messageId, targetSessionId, turnId) {
+        const now = Date.now();
+        const changed = this.database.connection.prepare(`
+      UPDATE message_receipts SET target_turn_id = ?, received_at = ?, status = 'running', error = NULL
+      WHERE message_id = ? AND EXISTS (
+        SELECT 1 FROM messages WHERE message_id = ? AND target_session_id = ? AND state = 'delivering'
+      )
+    `).run(turnId, now, messageId, messageId, targetSessionId);
+        if (Number(changed.changes) !== 1)
+            throw new Error(`message is not claimed by this runner: ${messageId}`);
+        return this.requireMessageReceipt(messageId);
+    }
+    markRunnerMessageStarting(messageId, targetSessionId) {
+        const changed = this.database.connection.prepare(`
+      UPDATE message_receipts SET status = 'running', error = NULL
+      WHERE message_id = ? AND status = 'claimed' AND EXISTS (
+        SELECT 1 FROM messages WHERE message_id = ? AND target_session_id = ? AND state = 'delivering'
+      )
+    `).run(messageId, messageId, targetSessionId);
+        if (Number(changed.changes) !== 1)
+            throw new Error(`message is not claimed by this runner: ${messageId}`);
+        return this.requireMessageReceipt(messageId);
+    }
+    completeRunnerMessage(messageId, targetSessionId, input) {
+        const now = Date.now();
+        return this.database.transaction(() => {
+            const changed = this.database.connection.prepare(`
+        UPDATE messages SET state = 'delivered', delivered_at = ?, delivery_claimed_at = NULL, error = NULL
+        WHERE message_id = ? AND target_session_id = ? AND state = 'delivering'
+      `).run(now, messageId, targetSessionId);
+            if (Number(changed.changes) !== 1)
+                throw new Error(`message is not running for this target: ${messageId}`);
+            this.database.connection.prepare(`
+        UPDATE message_receipts SET target_turn_id = ?, completed_at = ?, status = 'completed',
+          answer = ?, tool_results_json = ?, error = NULL WHERE message_id = ?
+      `).run(input.turnId, now, input.answer?.slice(0, 65_536) ?? null, JSON.stringify(input.toolResults).slice(0, 65_536), messageId);
+            return this.requireMessageReceipt(messageId);
+        });
+    }
+    failRunnerMessage(messageId, targetSessionId, error) {
+        const now = Date.now();
+        return this.database.transaction(() => {
+            const receipt = this.getMessageReceipt(messageId);
+            if (receipt === null)
+                throw new Error(`unknown message receipt: ${messageId}`);
+            const started = receipt.status === "running";
+            this.database.connection.prepare(`
+        UPDATE messages SET state = ?, delivery_claimed_at = NULL, error = ?
+        WHERE message_id = ? AND target_session_id = ? AND state = 'delivering'
+      `).run(started ? "failed" : "queued", error.slice(0, 4096), messageId, targetSessionId);
+            this.database.connection.prepare(`
+        UPDATE message_receipts SET completed_at = ?, status = 'failed', error = ? WHERE message_id = ?
+      `).run(now, error.slice(0, 4096), messageId);
+            return this.requireMessageReceipt(messageId);
+        });
+    }
+    getMessageReceipt(messageId) {
+        const row = this.database.connection.prepare("SELECT * FROM message_receipts WHERE message_id = ?")
+            .get(messageId);
+        return row === undefined ? null : mapMessageReceipt(row);
+    }
+    requireMessageReceipt(messageId) {
+        const receipt = this.getMessageReceipt(messageId);
+        if (receipt === null)
+            throw new Error(`unknown message receipt: ${messageId}`);
+        return receipt;
+    }
+    recordRemoteTaskEvent(input) {
+        const serverUrl = requireText(input.serverUrl, "remote server URL");
+        const taskId = requireText(input.taskId, "remote task ID");
+        const eventId = requireText(input.eventId, "remote event ID");
+        const envelopeId = requireText(input.envelopeId, "remote envelope ID");
+        const localRouteId = requireText(input.localRouteId, "local route ID");
+        const remoteRouteId = requireText(input.remoteRouteId, "remote route ID");
+        const senderLabel = requireText(input.senderLabel, "remote sender label");
+        const senderReference = requireText(input.senderReference, "remote sender reference");
+        const occurredAt = requireDate(input.occurredAt, "remote event occurredAt");
+        const expiresAt = requireDate(input.expiresAt, "remote task expiresAt");
+        const recordedAt = requireDate(input.recordedAt ?? new Date(), "remote event recordedAt");
+        if (expiresAt.getTime() <= occurredAt.getTime()) {
+            throw new Error("remote task expiry must be after the event timestamp");
+        }
+        validateRemoteKindState(input.kind, input.state);
+        const payloadJson = canonicalJson(input.payload);
+        const authenticated = input.authenticated ?? false;
+        if (this.getSession(input.localSessionId) === null) {
+            throw new Error(`unknown Portal session: ${input.localSessionId}`);
+        }
+        if (input.localMessageId !== undefined && input.localMessageId !== null) {
+            this.validateRemoteLocalMessage(input.localSessionId, input.localMessageId);
+        }
+        return this.database.transaction(() => {
+            const priorEvent = this.getRemoteTaskEvent(serverUrl, eventId);
+            if (priorEvent !== null) {
+                assertRemoteEventIdempotent(priorEvent, {
+                    ...input,
+                    serverUrl,
+                    taskId,
+                    eventId,
+                    envelopeId,
+                    localRouteId,
+                    remoteRouteId,
+                    senderLabel,
+                    senderReference,
+                    authenticated,
+                    payload: JSON.parse(payloadJson),
+                    occurredAt,
+                    expiresAt,
+                });
+                return { task: this.requireRemoteTask(serverUrl, taskId), event: priorEvent, inserted: false };
+            }
+            const priorEnvelope = this.getRemoteTaskEventByEnvelope(serverUrl, envelopeId);
+            if (priorEnvelope !== null) {
+                throw new Error(`remote envelope ID conflict: ${envelopeId}`);
+            }
+            let task = this.getRemoteTask(serverUrl, taskId);
+            if (task === null) {
+                if (input.kind !== "offer" || input.state !== "offered") {
+                    throw new Error("a remote task must begin with an offered event");
+                }
+                this.database.connection.prepare(`
+          INSERT INTO remote_tasks (
+            server_url, task_id, local_session_id, local_route_id, remote_route_id,
+            direction, state, created_at, updated_at, expires_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(serverUrl, taskId, input.localSessionId, localRouteId, remoteRouteId, input.direction, input.state, occurredAt.getTime(), occurredAt.getTime(), expiresAt.getTime());
+            }
+            else {
+                assertRemoteTaskIdentity(task, input.localSessionId, localRouteId, remoteRouteId, expiresAt);
+                validateRemoteTransition(task.state, input.state);
+                this.database.connection.prepare(`
+          UPDATE remote_tasks SET state = ?, updated_at = max(updated_at, ?)
+          WHERE server_url = ? AND task_id = ?
+        `).run(input.state, occurredAt.getTime(), serverUrl, taskId);
+            }
+            this.database.connection.prepare(`
+        INSERT INTO remote_task_events (
+          server_url, event_id, envelope_id, task_id, local_session_id,
+          local_route_id, remote_route_id, direction, kind, state, payload_json,
+          sender_label, sender_reference, authenticated, local_message_id,
+          occurred_at, expires_at, recorded_at, delivery_state
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(serverUrl, eventId, envelopeId, taskId, input.localSessionId, localRouteId, remoteRouteId, input.direction, input.kind, input.state, payloadJson, senderLabel, senderReference, Number(authenticated), input.localMessageId ?? null, occurredAt.getTime(), expiresAt.getTime(), recordedAt.getTime(), input.direction === "inbound" ? "queued" : "not_applicable");
+            task = this.requireRemoteTask(serverUrl, taskId);
+            return {
+                task,
+                event: this.requireRemoteTaskEvent(serverUrl, eventId),
+                inserted: true,
+            };
+        });
+    }
+    getRemoteTask(serverUrl, taskId) {
+        const row = this.database.connection.prepare(`
+      SELECT * FROM remote_tasks WHERE server_url = ? AND task_id = ?
+    `).get(serverUrl, taskId);
+        return row === undefined ? null : mapRemoteTask(row);
+    }
+    getRemoteTaskEvent(serverUrl, eventId) {
+        const row = this.database.connection.prepare(`
+      SELECT * FROM remote_task_events WHERE server_url = ? AND event_id = ?
+    `).get(serverUrl, eventId);
+        return row === undefined ? null : mapRemoteTaskEvent(row);
+    }
+    getRemoteTaskEventByEnvelope(serverUrl, envelopeId) {
+        const row = this.database.connection.prepare(`
+      SELECT * FROM remote_task_events WHERE server_url = ? AND envelope_id = ?
+    `).get(serverUrl, envelopeId);
+        return row === undefined ? null : mapRemoteTaskEvent(row);
+    }
+    getRemoteTaskEventByLocalMessage(localMessageId) {
+        const row = this.database.connection.prepare(`
+      SELECT * FROM remote_task_events WHERE local_message_id = ?
+    `).get(localMessageId);
+        return row === undefined ? null : mapRemoteTaskEvent(row);
+    }
+    listRemoteTaskEvents(serverUrl, taskId) {
+        const rows = this.database.connection.prepare(`
+      SELECT * FROM remote_task_events
+      WHERE server_url = ? AND task_id = ?
+      ORDER BY occurred_at, event_id
+    `).all(serverUrl, taskId);
+        return rows.map(mapRemoteTaskEvent);
+    }
+    linkRemoteTaskEventToLocalMessage(serverUrl, eventId, localMessageId) {
+        const event = this.requireRemoteTaskEvent(serverUrl, eventId);
+        if (event.localMessageId !== null) {
+            if (event.localMessageId !== localMessageId) {
+                throw new Error(`remote event is already linked to another local message: ${eventId}`);
+            }
+            return event;
+        }
+        this.validateRemoteLocalMessage(event.localSessionId, localMessageId);
+        try {
+            const changed = this.database.connection.prepare(`
+        UPDATE remote_task_events SET local_message_id = ?
+        WHERE server_url = ? AND event_id = ? AND local_message_id IS NULL
+      `).run(localMessageId, serverUrl, eventId);
+            if (Number(changed.changes) !== 1)
+                throw new Error(`failed to link remote event: ${eventId}`);
+        }
+        catch (error) {
+            if (String(error).includes("UNIQUE constraint failed")) {
+                throw new Error(`local message is already linked to another remote event: ${localMessageId}`);
+            }
+            throw error;
+        }
+        return this.requireRemoteTaskEvent(serverUrl, eventId);
+    }
+    claimNextRemoteTaskEvent(localSessionId, claimTtlMs = 60_000) {
+        const now = Date.now();
+        const staleBefore = now - claimTtlMs;
+        return this.database.transaction(() => {
+            this.database.connection.prepare(`
+        UPDATE remote_task_events SET delivery_state = 'failed', delivery_claimed_at = NULL,
+          completed_at = ?, error = 'remote event expired before delivery'
+        WHERE local_session_id = ? AND direction = 'inbound'
+          AND delivery_state IN ('queued', 'delivering') AND runner_started_at IS NULL
+          AND expires_at <= ?
+      `).run(now, localSessionId, now);
+            const row = this.database.connection.prepare(`
+        SELECT * FROM remote_task_events
+        WHERE local_session_id = ? AND direction = 'inbound' AND (
+          delivery_state = 'queued' OR
+          (delivery_state = 'delivering' AND delivery_claimed_at <= ? AND runner_started_at IS NULL)
+        ) AND expires_at > ?
+        ORDER BY occurred_at, event_id LIMIT 1
+      `).get(localSessionId, staleBefore, now);
+            if (row === undefined)
+                return null;
+            const changed = this.database.connection.prepare(`
+        UPDATE remote_task_events SET delivery_state = 'delivering',
+          delivery_claimed_at = ?, delivery_attempts = delivery_attempts + 1, error = NULL
+        WHERE server_url = ? AND event_id = ? AND (
+          delivery_state = 'queued' OR
+          (delivery_state = 'delivering' AND delivery_claimed_at <= ? AND runner_started_at IS NULL)
+        ) AND expires_at > ?
+      `).run(now, row.server_url, row.event_id, staleBefore, now);
+            if (Number(changed.changes) !== 1)
+                return null;
+            return this.requireRemoteTaskEvent(row.server_url, row.event_id);
+        });
+    }
+    markRemoteTaskEventStarting(serverUrl, eventId, localSessionId) {
+        const changed = this.database.connection.prepare(`
+      UPDATE remote_task_events SET runner_started_at = coalesce(runner_started_at, ?), error = NULL
+      WHERE server_url = ? AND event_id = ? AND local_session_id = ?
+        AND direction = 'inbound' AND delivery_state = 'delivering'
+    `).run(Date.now(), serverUrl, eventId, localSessionId);
+        if (Number(changed.changes) !== 1)
+            throw new Error(`remote event is not claimed by this runner: ${eventId}`);
+        return this.requireRemoteTaskEvent(serverUrl, eventId);
+    }
+    markRemoteTaskEventReceived(serverUrl, eventId, localSessionId, turnId) {
+        const now = Date.now();
+        const changed = this.database.connection.prepare(`
+      UPDATE remote_task_events SET runner_started_at = coalesce(runner_started_at, ?),
+        target_turn_id = ?, received_at = ?, error = NULL
+      WHERE server_url = ? AND event_id = ? AND local_session_id = ?
+        AND direction = 'inbound' AND delivery_state = 'delivering'
+    `).run(now, requireText(turnId, "target turn ID"), now, serverUrl, eventId, localSessionId);
+        if (Number(changed.changes) !== 1)
+            throw new Error(`remote event is not claimed by this runner: ${eventId}`);
+        return this.requireRemoteTaskEvent(serverUrl, eventId);
+    }
+    completeRemoteTaskEvent(serverUrl, eventId, localSessionId, input) {
+        const now = Date.now();
+        const toolResultsJson = canonicalJson(input.toolResults);
+        const changed = this.database.connection.prepare(`
+      UPDATE remote_task_events SET delivery_state = 'delivered', delivery_claimed_at = NULL,
+        target_turn_id = ?, completed_at = ?, answer = ?, tool_results_json = ?, error = NULL
+      WHERE server_url = ? AND event_id = ? AND local_session_id = ?
+        AND direction = 'inbound' AND delivery_state = 'delivering' AND runner_started_at IS NOT NULL
+    `).run(requireText(input.turnId, "target turn ID"), now, input.answer?.slice(0, 65_536) ?? null, toolResultsJson, serverUrl, eventId, localSessionId);
+        if (Number(changed.changes) !== 1)
+            throw new Error(`remote event is not running for this target: ${eventId}`);
+        return this.requireRemoteTaskEvent(serverUrl, eventId);
+    }
+    failRemoteTaskEvent(serverUrl, eventId, localSessionId, error) {
+        const event = this.requireRemoteTaskEvent(serverUrl, eventId);
+        if (event.localSessionId !== localSessionId || event.direction !== "inbound"
+            || event.deliveryState !== "delivering") {
+            throw new Error(`remote event is not claimed by this runner: ${eventId}`);
+        }
+        const started = event.runnerStartedAt !== null;
+        const now = Date.now();
+        this.database.connection.prepare(`
+      UPDATE remote_task_events SET delivery_state = ?, delivery_claimed_at = NULL,
+        completed_at = ?, error = ?
+      WHERE server_url = ? AND event_id = ?
+    `).run(started ? "failed" : "queued", started ? now : null, error.slice(0, 4096), serverUrl, eventId);
+        return this.requireRemoteTaskEvent(serverUrl, eventId);
+    }
+    requireRemoteTask(serverUrl, taskId) {
+        const task = this.getRemoteTask(serverUrl, taskId);
+        if (task === null)
+            throw new Error(`unknown remote task: ${taskId}`);
+        return task;
+    }
+    requireRemoteTaskEvent(serverUrl, eventId) {
+        const event = this.getRemoteTaskEvent(serverUrl, eventId);
+        if (event === null)
+            throw new Error(`unknown remote task event: ${eventId}`);
+        return event;
+    }
+    validateRemoteLocalMessage(localSessionId, localMessageId) {
+        const message = this.getMessage(localMessageId);
+        if (message === null)
+            throw new Error(`unknown message: ${localMessageId}`);
+        if (message.senderSessionId !== localSessionId && message.targetSessionId !== localSessionId) {
+            throw new Error("local message does not belong to the remote task session");
+        }
+    }
+    issueSessionCredential(sessionId) {
+        if (this.getSession(sessionId) === null)
+            throw new Error(`unknown Portal session: ${sessionId}`);
+        const credentialId = randomUUID();
+        const secret = randomBytes(32).toString("base64url");
+        this.database.connection
+            .prepare(`
+        INSERT INTO session_credentials (
+          credential_id, session_id, secret_hash, created_at, expires_at
+        ) VALUES (?, ?, ?, ?, ?)
+      `)
+            .run(credentialId, sessionId, digest(secret), Date.now(), Date.now() + 86_400_000);
+        return `pc_${credentialId}_${secret}`;
+    }
+    authenticateSession(sessionId, token) {
+        const parsed = parseCredential(token);
+        if (parsed === null)
+            throw new Error("invalid Portal session credential");
+        const row = this.database.connection
+            .prepare(`
+        SELECT session_id, secret_hash FROM session_credentials
+        WHERE credential_id = ? AND revoked_at IS NULL
+          AND (expires_at IS NULL OR expires_at > ?)
+      `)
+            .get(parsed.credentialId, Date.now());
+        const candidate = digest(parsed.secret);
+        if (row === undefined ||
+            row.session_id !== sessionId ||
+            !safeEqual(candidate, row.secret_hash)) {
+            throw new Error("invalid Portal session credential");
+        }
+        const session = this.getSession(sessionId);
+        if (session === null)
+            throw new Error("credential references an unknown Portal session");
+        return session;
+    }
+    revokeSessionCredential(token) {
+        const parsed = parseCredential(token);
+        if (parsed === null)
+            return;
+        this.database.connection
+            .prepare("UPDATE session_credentials SET revoked_at = ? WHERE credential_id = ?")
+            .run(Date.now(), parsed.credentialId);
+    }
+    touchConnectionLease(sessionId, ttlMs = 120_000) {
+        if (!Number.isInteger(ttlMs) || ttlMs < 10_000)
+            throw new RangeError("connection lease TTL is too small");
+        if (this.getSession(sessionId) === null)
+            throw new Error(`unknown Portal session: ${sessionId}`);
+        const now = Date.now();
+        const expiresAt = new Date(now + ttlMs);
+        this.database.connection
+            .prepare(`
+        INSERT INTO connection_leases (session_id, last_seen, expires_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT(session_id) DO UPDATE SET
+          last_seen = excluded.last_seen,
+          expires_at = excluded.expires_at
+      `)
+            .run(sessionId, now, expiresAt.getTime());
+        return expiresAt;
+    }
+    hasActiveConnectionLease(sessionId, now = new Date()) {
+        const row = this.database.connection
+            .prepare("SELECT 1 AS active FROM connection_leases WHERE session_id = ? AND expires_at > ?")
+            .get(sessionId, now.getTime());
+        return row?.active === 1;
+    }
+    clearConnectionLease(sessionId) {
+        this.database.connection.prepare("DELETE FROM connection_leases WHERE session_id = ?").run(sessionId);
+    }
+    validateReply(messageId, workspace, senderSessionId, targetSessionId, maxDepth) {
+        let current = messageId;
+        const visited = new Set();
+        for (let depth = 0; current !== null; depth += 1) {
+            if (depth >= maxDepth)
+                throw new Error(`message reply depth exceeds ${maxDepth}`);
+            if (visited.has(current))
+                throw new Error("message reply chain contains a cycle");
+            visited.add(current);
+            const row = this.database.connection
+                .prepare(`
+          SELECT m.reply_to, m.sender_session_id, m.target_session_id,
+                 sender.workspace AS sender_workspace, target.workspace AS target_workspace
+          FROM messages m
+          JOIN sessions sender ON sender.portal_session_id = m.sender_session_id
+          JOIN sessions target ON target.portal_session_id = m.target_session_id
+          WHERE m.message_id = ?
+        `)
+                .get(current);
+            if (row === undefined)
+                throw new Error(`unknown reply message: ${current}`);
+            if (row.sender_workspace !== workspace || row.target_workspace !== workspace) {
+                throw new Error("reply message is outside the sender workspace");
+            }
+            if (depth === 0 && (row.target_session_id !== senderSessionId || row.sender_session_id !== targetSessionId)) {
+                throw new Error("reply participants must reverse the parent message participants");
+            }
+            current = row.reply_to;
+        }
+    }
+}
+function mapSession(row) {
+    return {
+        portalSessionId: row.portal_session_id,
+        provider: row.provider,
+        installation: row.installation,
+        accountFingerprint: row.account_fingerprint,
+        vendorSessionId: row.vendor_session_id,
+        workspace: row.workspace,
+        title: row.title,
+        managedName: row.managed_name,
+        observedAt: new Date(row.observed_at),
+        updatedAt: fromEpoch(row.updated_at),
+        state: row.state,
+        stateConfidence: row.state_confidence,
+        indexed: row.indexed === 1,
+        connected: row.connected === 1,
+        messageable: row.messageable === 1,
+    };
+}
+function mapChunk(row) {
+    return {
+        chunkId: row.chunk_id,
+        sessionId: row.session_id,
+        text: row.text,
+        embeddingModel: row.embedding_model,
+        embedding: row.embedding_json === null ? null : JSON.parse(row.embedding_json),
+    };
+}
+function mapSessionProfile(row) {
+    return {
+        sessionId: row.session_id,
+        displayName: row.display_name,
+        description: row.description,
+        topics: JSON.parse(row.topics_json),
+        source: row.source,
+        transcriptWatermark: row.transcript_watermark,
+        updatedAt: new Date(row.updated_at),
+    };
+}
+function mapCitation(row) {
+    return {
+        portalSessionId: row.portal_session_id,
+        vendorSessionId: row.vendor_session_id,
+        provider: row.provider,
+        workspace: row.workspace,
+        sourceId: row.source_id,
+        entryId: row.entry_id,
+        occurredAt: fromEpoch(row.occurred_at),
+        uri: `portal://session/${encodeURIComponent(row.portal_session_id)}/entry/${encodeURIComponent(row.entry_id)}`,
+    };
+}
+function mapMessage(row) {
+    return {
+        messageId: row.message_id,
+        senderSessionId: row.sender_session_id,
+        targetSessionId: row.target_session_id,
+        body: row.body,
+        state: row.state,
+        createdAt: new Date(row.created_at),
+        deliveredAt: fromEpoch(row.delivered_at),
+        replyTo: row.reply_to,
+        idempotencyKey: row.idempotency_key,
+        error: row.error,
+    };
+}
+function mapMessageReceipt(row) {
+    return {
+        messageId: row.message_id,
+        targetTurnId: row.target_turn_id,
+        receivedAt: fromEpoch(row.received_at),
+        completedAt: fromEpoch(row.completed_at),
+        status: row.status,
+        answer: row.answer,
+        toolResults: row.tool_results_json === null ? [] : JSON.parse(row.tool_results_json),
+        error: row.error,
+    };
+}
+function mapRemoteTask(row) {
+    return {
+        serverUrl: row.server_url,
+        taskId: row.task_id,
+        localSessionId: row.local_session_id,
+        localRouteId: row.local_route_id,
+        remoteRouteId: row.remote_route_id,
+        direction: row.direction,
+        state: row.state,
+        createdAt: new Date(row.created_at),
+        updatedAt: new Date(row.updated_at),
+        expiresAt: new Date(row.expires_at),
+    };
+}
+function mapRemoteTaskEvent(row) {
+    return {
+        serverUrl: row.server_url,
+        taskId: row.task_id,
+        eventId: row.event_id,
+        envelopeId: row.envelope_id,
+        localSessionId: row.local_session_id,
+        localRouteId: row.local_route_id,
+        remoteRouteId: row.remote_route_id,
+        direction: row.direction,
+        kind: row.kind,
+        state: row.state,
+        payload: JSON.parse(row.payload_json),
+        senderLabel: row.sender_label,
+        senderReference: row.sender_reference,
+        authenticated: row.authenticated === 1,
+        localMessageId: row.local_message_id,
+        occurredAt: new Date(row.occurred_at),
+        expiresAt: new Date(row.expires_at),
+        recordedAt: new Date(row.recorded_at),
+        deliveryState: row.delivery_state,
+        deliveryClaimedAt: fromEpoch(row.delivery_claimed_at),
+        deliveryAttempts: row.delivery_attempts,
+        runnerStartedAt: fromEpoch(row.runner_started_at),
+        targetTurnId: row.target_turn_id,
+        receivedAt: fromEpoch(row.received_at),
+        completedAt: fromEpoch(row.completed_at),
+        answer: row.answer,
+        toolResults: row.tool_results_json === null ? [] : JSON.parse(row.tool_results_json),
+        error: row.error,
+    };
+}
+const REMOTE_EVENT_STATES = {
+    offer: "offered",
+    accepted: "accepted",
+    declined: "declined",
+    running: "running",
+    progress: "running",
+    question: "running",
+    answer: "running",
+    completed: "completed",
+    failed: "failed",
+};
+const REMOTE_TRANSITIONS = {
+    offered: new Set(["offered", "accepted", "declined", "failed"]),
+    accepted: new Set(["accepted", "running", "completed", "failed"]),
+    declined: new Set(),
+    running: new Set(["running", "completed", "failed"]),
+    completed: new Set(),
+    failed: new Set(),
+};
+function validateRemoteKindState(kind, state) {
+    if (REMOTE_EVENT_STATES[kind] !== state) {
+        throw new Error(`remote event kind ${kind} cannot have task state ${state}`);
+    }
+}
+function validateRemoteTransition(from, to) {
+    if (!REMOTE_TRANSITIONS[from].has(to)) {
+        throw new Error(`invalid remote task state transition: ${from} -> ${to}`);
+    }
+}
+function assertRemoteTaskIdentity(task, localSessionId, localRouteId, remoteRouteId, expiresAt) {
+    if (task.localSessionId !== localSessionId
+        || task.localRouteId !== localRouteId
+        || task.remoteRouteId !== remoteRouteId
+        || task.expiresAt.getTime() !== expiresAt.getTime()) {
+        throw new Error(`remote task identity conflict: ${task.taskId}`);
+    }
+}
+function assertRemoteEventIdempotent(existing, input) {
+    const matches = existing.taskId === input.taskId
+        && existing.envelopeId === input.envelopeId
+        && existing.localSessionId === input.localSessionId
+        && existing.localRouteId === input.localRouteId
+        && existing.remoteRouteId === input.remoteRouteId
+        && existing.direction === input.direction
+        && existing.kind === input.kind
+        && existing.state === input.state
+        && canonicalJson(existing.payload) === canonicalJson(input.payload)
+        && existing.senderLabel === input.senderLabel
+        && existing.senderReference === input.senderReference
+        && existing.authenticated === input.authenticated
+        && existing.occurredAt.getTime() === input.occurredAt.getTime()
+        && existing.expiresAt.getTime() === input.expiresAt.getTime();
+    if (!matches)
+        throw new Error(`remote event ID conflict: ${existing.eventId}`);
+}
+function requireText(value, label) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        throw new TypeError(`${label} cannot be empty`);
+    return trimmed;
+}
+function requireDate(value, label) {
+    if (!Number.isFinite(value.getTime()))
+        throw new TypeError(`${label} is invalid`);
+    return value;
+}
+function canonicalJson(value) {
+    const seen = new Set();
+    const normalize = (candidate) => {
+        if (candidate === null || typeof candidate === "string" || typeof candidate === "boolean")
+            return candidate;
+        if (typeof candidate === "number") {
+            if (!Number.isFinite(candidate))
+                throw new TypeError("remote event payload contains a non-finite number");
+            return candidate;
+        }
+        if (Array.isArray(candidate))
+            return candidate.map(normalize);
+        if (typeof candidate === "object") {
+            if (seen.has(candidate))
+                throw new TypeError("remote event payload contains a cycle");
+            seen.add(candidate);
+            const result = {};
+            for (const key of Object.keys(candidate).sort()) {
+                const normalized = normalize(candidate[key]);
+                if (normalized !== undefined)
+                    result[key] = normalized;
+            }
+            seen.delete(candidate);
+            return result;
+        }
+        if (candidate === undefined)
+            throw new TypeError("remote event payload cannot be undefined");
+        throw new TypeError(`remote event payload contains unsupported ${typeof candidate}`);
+    };
+    return JSON.stringify(normalize(value));
+}
+function stableId(prefix, ...parts) {
+    return `${prefix}_${digest(...parts).slice(0, 32)}`;
+}
+function digest(...parts) {
+    const hash = createHash("sha256");
+    for (const part of parts) {
+        hash.update(String(Buffer.byteLength(part)));
+        hash.update(":");
+        hash.update(part);
+        hash.update(";");
+    }
+    return hash.digest("hex");
+}
+function parseCredential(token) {
+    const match = /^pc_([0-9a-f-]{36})_([A-Za-z0-9_-]+)$/.exec(token);
+    return match?.[1] && match[2] ? { credentialId: match[1], secret: match[2] } : null;
+}
+function safeEqual(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+function toEpoch(date) {
+    return date?.getTime() ?? null;
+}
+function fromEpoch(value) {
+    return value === null ? null : new Date(value);
+}
+function splitIntoChunks(text, maxCharacters = 900) {
+    const normalized = text.replace(/\r\n?/g, "\n").trim();
+    if (normalized.length === 0)
+        return [];
+    const chunks = [];
+    let remaining = normalized;
+    while (remaining.length > maxCharacters) {
+        const window = remaining.slice(0, maxCharacters + 1);
+        const paragraphBoundary = window.lastIndexOf("\n\n");
+        const sentenceBoundary = Math.max(window.lastIndexOf(". "), window.lastIndexOf("? "), window.lastIndexOf("! "));
+        const wordBoundary = window.lastIndexOf(" ");
+        const boundary = Math.max(paragraphBoundary >= Math.floor(maxCharacters * 0.45) ? paragraphBoundary + 2 : -1, sentenceBoundary >= Math.floor(maxCharacters * 0.55) ? sentenceBoundary + 1 : -1, wordBoundary >= Math.floor(maxCharacters * 0.7) ? wordBoundary : -1, maxCharacters);
+        chunks.push(remaining.slice(0, boundary).trim());
+        remaining = remaining.slice(boundary).trim();
+    }
+    if (remaining.length > 0)
+        chunks.push(remaining);
+    return chunks;
+}
+export function compileFtsQuery(query) {
+    const tokens = query
+        .normalize("NFKD")
+        .replace(/\p{Mark}/gu, "")
+        .toLocaleLowerCase("en-US")
+        .match(/[\p{Letter}\p{Number}]+/gu);
+    if (tokens === null || tokens.length === 0)
+        return "";
+    return [...new Set(tokens)].map((token) => `"${token.replaceAll('"', '""')}"`).join(" OR ");
+}
+function candidateSql(query, lexical) {
+    const providerClause = providerFilter(query.providers);
+    const timeClause = timeFilter(query);
+    const source = lexical
+        ? "chunks_fts JOIN chunks c ON c.rowid = chunks_fts.rowid"
+        : "chunks c";
+    return {
+        sql: `
+      SELECT
+        c.chunk_id, c.text,
+        s.portal_session_id, s.vendor_session_id, s.provider, s.workspace,
+        e.source_id, e.entry_id, c.occurred_at
+        ${lexical ? ", bm25(chunks_fts) AS lexical_rank" : ""}
+      FROM ${source}
+      JOIN sessions s ON s.portal_session_id = c.session_id
+      JOIN transcript_entries e ON e.entry_id = c.first_entry_id
+      WHERE ${lexical ? "chunks_fts MATCH ? AND" : ""} s.workspace = ?
+        ${providerClause.sql}
+        ${timeClause.sql}
+      ${lexical ? "ORDER BY lexical_rank, c.chunk_id" : "ORDER BY c.chunk_id"}
+      LIMIT ?
+    `,
+        parameters: [...providerClause.parameters, ...timeClause.parameters],
+    };
+}
+function providerFilter(providers) {
+    if (providers === undefined || providers.length === 0)
+        return { sql: "", parameters: [] };
+    return {
+        sql: `AND s.provider IN (${providers.map(() => "?").join(", ")})`,
+        parameters: [...providers],
+    };
+}
+function timeFilter(query) {
+    const clauses = [];
+    const parameters = [];
+    if (query.occurredAfter !== undefined) {
+        clauses.push("AND c.occurred_at >= ?");
+        parameters.push(query.occurredAfter.getTime());
+    }
+    if (query.occurredBefore !== undefined) {
+        clauses.push("AND c.occurred_at <= ?");
+        parameters.push(query.occurredBefore.getTime());
+    }
+    return { sql: clauses.join("\n"), parameters };
+}
+//# sourceMappingURL=repository.js.map