@jini-ai/chat 0.6.17 → 0.6.21

package/dist/store/runtime/checkpoint-delta.js

@@ -0,0 +1,75 @@
+import { dedupeToolUsesById } from "../../core/tool-events.js";
+/** Compare unchanged prefix values; compacting text creates fresh objects, while large tool
+ * payloads normally retain their reference. Never parse the saved SQL column here. */
+function sameEvent(left, right) {
+    return left === right || JSON.stringify(left) === JSON.stringify(right);
+}
+/** A delta may append events or replace the final coalesced text event. Every earlier event
+ * must match; replay reordering, thinking replacement and tool identity deduplication fall back.
+ * @complexity O(prefix bytes + new suffix bytes) time; O(new suffix bytes) temporary space. */
+export function checkpointDelta({ previous, progress }, _options = {}) {
+    if (progress.content.length < previous.content.length)
+        return undefined;
+    const incoming = progress.events;
+    const saved = previous.events;
+    if (incoming.length < saved.length)
+        return undefined;
+    if (dedupeToolUsesById({ events: incoming }).length !== incoming.length)
+        return undefined;
+    const prefix = saved.slice(0, -1);
+    if (!prefix.every((event, index) => sameEvent(event, incoming[index])))
+        return undefined;
+    const last = saved.at(-1);
+    const next = incoming[saved.length - 1];
+    const replacing = last !== undefined && !sameEvent(last, next);
+    if (replacing && !extendsText({ last, next }))
+        return undefined;
+    return { ...deltaSuffix({ previous, incoming, replacing }),
+        grown: progress.content.length > previous.content.length || hasNewToolProgress({ saved, incoming }) };
+}
+/** SQL counts characters in the removed tail, so non-BMP text never uses JS UTF-16 offsets. */
+function deltaSuffix({ previous, incoming, replacing }, _options = {}) {
+    const from = previous.events.length - (replacing ? 1 : 0);
+    const suffixEvents = incoming.slice(from);
+    const separator = !replacing && from > 0 && suffixEvents.length > 0 ? ',' : '';
+    return { removeCharacters: replacing ? previous.tailLength : 1,
+        suffix: separator + JSON.stringify(suffixEvents).slice(1) };
+}
+/** Extending text must retain every other field (including any future event metadata). */
+function extendsText({ last, next }, _options = {}) {
+    if (last.kind !== 'text' || next?.kind !== 'text')
+        return false;
+    return next.text.startsWith(last.text) && sameEvent({ ...last, text: next.text }, next);
+}
+/** Same tool identity rule as the full checkpoint's progress check. O(saved + incoming events). */
+export function hasNewToolProgress({ saved, incoming }, _options = {}) {
+    const keys = new Set(saved.map(event => toolKey({ event })));
+    return incoming.some(event => { const key = toolKey({ event }); return key !== '' && !keys.has(key); });
+}
+/** Durable tool identity shared by the full merge and delta progress check. */
+export function toolKey({ event }, _options = {}) {
+    if (event.kind === 'tool_use')
+        return 'use:' + event.id;
+    if (event.kind === 'tool_result')
+        return 'result:' + event.toolUseId;
+    return '';
+}
+/** Build a receipt only for an exact incoming projection; callers own its watch lifetime.
+ * SQL supplies content/event lengths; the removed tail counts Unicode code points. Retain only
+ * a bounded suffix for CAS, so a multi-MB tool result never becomes a guard parameter twice.
+ * @complexity O(last event bytes) serialization/counting; O(last event bytes) transient space,
+ * with at most 256 UTF-16 units retained beyond the existing projection references.
+ */
+export function checkpointState({ progress, length, contentLength, version }, _options = {}) {
+    const last = progress.events.at(-1);
+    const fullTail = last === undefined ? '[]' : JSON.stringify(last) + ']';
+    // Count SQL characters without allocating an array of code points for a multi-MB tool result.
+    let tailLength = 0;
+    for (const _character of fullTail)
+        tailLength++;
+    let tail = fullTail.slice(-256);
+    if (/^[\uDC00-\uDFFF]/u.test(tail))
+        tail = tail.slice(1);
+    return { content: progress.content, events: progress.events, version, length, contentLength, tailLength, tail };
+}
+//# sourceMappingURL=checkpoint-delta.js.map

package/dist/store/runtime/durable-run-store.js

@@ -1,3 +1,4 @@
+import { sqliteReadVersion } from '../sql/read-version.js';
 import { acceptedInputEvent, acceptedInputUserEvent } from "../../core/accepted-input.js";
 import { redactUserMessage } from "../../core/user-text-redaction.js";
 import { recoveredRunEvents } from "../../core/index.js";
@@ -8,7 +9,8 @@ import { RECOVERY_WINDOW_MS } from "../../core/durable-runs/policies.js";
 import { createChatHistoryStore } from "./chat-history-store.js";
 import { runLockKey } from "../../core/durable-runs/run-lock.js";
 import { runContentFromEvents } from "../../core/run-events/entry.js";
-import { toMessage } from "../sql/store.js";
+import { appendedEventsJson } from "./events-json.js";
+import { toMessage, validatedEventsJson } from "../sql/store.js";
 export const RUN_SLOT_BUSY = "Another answer in this chat is still running. This turn is queued in your browser.";
 export class RunSlotBusyError extends Error {
     constructor() { super(RUN_SLOT_BUSY); }
@@ -150,15 +152,6 @@ function continuationEvents({ current, incoming }, _optional = {}) {
     }
     return runContentFromEvents({ events: incoming }).length >= current.message.content.length ? incoming : saved;
 }
-/** `events_json` with one more event, built in SQL: no dialect parses or re-serializes the saved
- * array in JS. Writers store `JSON.stringify` output (no whitespace), so a non-empty array is
- * `[...]` and gains `,event`; `[]`, NULL and anything not array-shaped (a truncated legacy value,
- * which the old JS read also treated as no events) become `[event]`. Plain `substr`/`length`/`||`
- * run unchanged on SQLite and PostgreSQL. */
-function appendedEventsJson({ event }, _optional = {}) {
-    const item = sql `cast(${JSON.stringify(event)} as text)`;
-    return sql `case when events_json like '[_%]' then substr(events_json, 1, length(events_json) - 1) || ',' || ${item} || ']' else '[' || ${item} || ']' end`;
-}
 function sameOwner({ run, required }, _optional = {}) {
     return run.principalId === required.principalId && run.conversationId === required.conversationId;
 }
@@ -176,10 +169,28 @@ export function createDurableRunStore({ kernel: hostKernel, isDaemonRunId }, _op
             .select(eventsColumn.as("events_json"))
             .where(match.column, "=", match.value).where("role", "=", "assistant").executeTakeFirst());
     }
-    /** Every message of the run's conversation; only `load` and legacy rows without attempt metadata pay this. */
-    async function conversationTranscript({ row }, _options = {}) {
+    /** Conversation projection: callers can omit assistant event payloads; legacy heads need only content. */
+    async function conversationTranscript({ row }, { includeEvents = true } = {}) {
         const history = createChatHistoryStore({ kernel, isDaemonRunId, scope: { scopeId: row.scope_id, ownerKind: row.owner_kind, ownerId: row.owner_id } }, {});
-        return history.messages({ conversationId: row.conversation_id });
+        return history.messages({ conversationId: row.conversation_id }, { includeEvents });
+    }
+    /** Legacy accepted requests and recovery reconstruction consume prior text only. */
+    async function readTranscript({ row, metadata }, options = {}) {
+        if (!options.transcript && metadata)
+            return [];
+        const includeEvents = transcriptEventProjection(options);
+        return conversationTranscript({ row }, { includeEvents });
+    }
+    /** Accepted user receipts split queued inputs and hold folder references. Keep that small
+     * public metadata even when recovery omits prior assistant event payloads. */
+    function transcriptEventProjection(options) {
+        if (options.includeTranscriptEvents === false && options.transcript)
+            return 'user';
+        return options.includeTranscriptEvents ?? options.transcript === true;
+    }
+    function currentMessage({ row, transcript }, options = {}) {
+        return options.transcript && options.includeTranscriptEvents !== false
+            ? transcript.find(item => item.id === row.id) : toMessage(row);
     }
     /** One run's head, plus its transcript when that was read (`[]` otherwise). */
     async function readRun({ match }, options = {}) {
@@ -189,11 +200,12 @@ export function createDurableRunStore({ kernel: hostKernel, isDaemonRunId }, _op
         const messageId = row.id;
         const metadata = await kernel.run((db) => db.selectFrom("assistant_run_attempts").selectAll().where("message_id", "=", messageId).executeTakeFirst());
         // A legacy row's accepted request is derived from its transcript, so only it reads one here.
-        const transcript = options.transcript || !metadata ? await conversationTranscript({ row }) : [];
-        const message = options.transcript ? transcript.find((item) => item.id === messageId) : toMessage(row);
+        const transcript = await readTranscript({ row, metadata }, options);
+        const message = currentMessage({ row, transcript }, options);
         if (!message)
             return null; // Deletion may have cascaded between the two reads.
-        return { head: runHead({ row, runId: row.run_id, metadata, message, transcript }, { isDaemonRunId }), transcript };
+        return { head: runHead({ row, runId: row.run_id, metadata, message, transcript }, { isDaemonRunId }),
+            transcript: transcript.map(item => item.id === messageId ? message : item) };
     }
     /** Locked read of one message; `transcript` decides whether it is a whole run or only its head. */
     async function lockedRead({ messageId, conversationId }, options = {}) {
@@ -204,15 +216,70 @@ export function createDurableRunStore({ kernel: hostKernel, isDaemonRunId }, _op
             return readRun({ match: { column: "ai_chat_messages.id", value: messageId } }, options);
         });
     }
-    async function load({ messageId }, _options = {}) {
+    async function load({ messageId }, { includeTranscriptEvents = true } = {}) {
         const binding = await kernel.run((db) => db.selectFrom("ai_chat_messages").select("conversation_id")
             .where("id", "=", messageId).executeTakeFirst());
         if (!binding)
             return null;
-        // The message comes from the transcript, so its row's events are not selected twice.
-        const read = await lockedRead({ messageId, conversationId: binding.conversation_id }, { transcript: true });
+        // Full reads take the message from the transcript. Lean reads select its own events once,
+        // omitting prior assistant payloads while retaining accepted user receipts.
+        const read = await lockedRead({ messageId, conversationId: binding.conversation_id }, { transcript: true, includeTranscriptEvents, events: !includeTranscriptEvents });
         return read && { ...read.head, transcript: read.transcript };
     }
+    /** Single-message read; message identity survives continuation while run_id changes.
+     * Legacy request reconstruction needs only transcript content, never its old event columns. */
+    async function head({ messageId }, { events = true } = {}) {
+        const binding = await kernel.run((db) => db.selectFrom("ai_chat_messages").select("conversation_id")
+            .where("id", "=", messageId).executeTakeFirst());
+        if (!binding)
+            return null;
+        return (await lockedRead({ messageId, conversationId: binding.conversation_id }, { events }))?.head ?? null;
+    }
+    /** Read only one owned projection, without a run lock or accepted-request reconstruction.
+     * Native database versions follow checkpoint growth, replacements, attempts and settlement. SQL omits
+     * content/events on a hit; only changed rows cross into JS as raw JSON, never parsed events.
+     * @complexity One indexed row read; O(1) unchanged payload and JS space; changed payload is O(current message bytes).
+     */
+    async function poll({ messageId, principalId, workspaceId }, { cursor } = {}) {
+        // SQLite has no per-row version: combine this connection's writes with the external-commit
+        // generation. Unrelated writes may invalidate the cursor, but equal-length rewrites cannot
+        // hide. PostgreSQL supplies the row's own MVCC version. Neither reads the event column.
+        const version = kernel.dialect === 'sqlite'
+            ? sqliteReadVersion({ kernel })
+            : sql `cast(ai_chat_messages.xmin as text)`;
+        const changed = sql `${version} <> ${cursor ?? ''}`;
+        // Run writers persist compact JSON arrays on both engines. SQLite also tolerates malformed
+        // legacy rows through its native validator; PG14 has no safe try-cast (do not parse in JS).
+        const valid = kernel.dialect === 'sqlite' ? sql `json_valid(events_json)` : sql `1`;
+        const row = await kernel.run(db => db.selectFrom('ai_chat_messages')
+            .innerJoin('ai_chats', 'ai_chats.id', 'ai_chat_messages.conversation_id')
+            .select(['ai_chat_messages.id', 'conversation_id', 'role'])
+            .select([
+            sql `case when ${changed} then run_id else null end`.as('run_id'),
+            sql `case when ${changed} then run_status else null end`.as('run_status'),
+            sql `case when ${changed} then agent_id else null end`.as('agent_id'),
+            sql `case when ${changed} then agent_name else null end`.as('agent_name'),
+            sql `case when ${changed} then attachments_json else null end`.as('attachments_json'),
+            sql `case when ${changed} then ai_chat_messages.created_at else 0 end`.as('created_at'),
+            sql `case when ${changed} then started_at else null end`.as('started_at'),
+            sql `case when ${changed} then ended_at else null end`.as('ended_at')
+        ])
+            .select([version.as('cursor'),
+            sql `case when ${changed} then content else '' end`.as('content'),
+            sql `case when ${changed} then events_json else null end`.as('events_json'),
+            sql `case when ${changed} then ${valid} else null end`.as('events_json_valid')])
+            .where('ai_chat_messages.id', '=', messageId).where('role', '=', 'assistant')
+            .where('owner_kind', '=', 'user').where('owner_id', '=', principalId).where('scope_id', '=', workspaceId)
+            .executeTakeFirst());
+        if (!row)
+            return null;
+        if (row.cursor === cursor)
+            return { cursor: row.cursor };
+        const metadata = JSON.stringify(toMessage({ ...row, events_json: null }));
+        const events = validatedEventsJson({ row });
+        const messageJson = events === undefined ? metadata : metadata.slice(0, -1) + ',"events":' + events + '}';
+        return { cursor: row.cursor, conversationId: row.conversation_id, messageJson };
+    }
     /** Unlocked probe: the message and conversation an attempt id currently names. */
     async function probeRun({ runId }, _options = {}) {
         return kernel.run((db) => db.selectFrom("ai_chat_messages").select(["id", "conversation_id"])
@@ -267,7 +334,7 @@ export function createDurableRunStore({ kernel: hostKernel, isDaemonRunId }, _op
             const history = await lockOwnedConversation({ required });
             if (!history)
                 return null;
-            const existing = await load({ messageId: required.messageId }, {});
+            const existing = await load({ messageId: required.messageId }, { includeTranscriptEvents: false });
             if (existing)
                 return sameOwner({ run: existing, required }) ? existing : null;
             await assertSlotFree({ conversationId: required.conversationId });
@@ -282,7 +349,7 @@ export function createDurableRunStore({ kernel: hostKernel, isDaemonRunId }, _op
                 recovery_elapsed_ms: 0, attempt_started_at: required.now,
                 session_id: null, session_confirmed: 0, child_pid: null, child_started_at: null, attempt_base_json: "[]",
             }).execute());
-            return load({ messageId: required.messageId }, {});
+            return load({ messageId: required.messageId }, { includeTranscriptEvents: false });
         });
     }
     async function writeAttemptMetadata({ values, updates }) {
@@ -340,18 +407,18 @@ export function createDurableRunStore({ kernel: hostKernel, isDaemonRunId }, _op
             const history = await lockOwnedConversation({ required });
             if (!history)
                 return null;
-            const existing = await load({ messageId: required.messageId }, {});
+            const existing = await load({ messageId: required.messageId }, { includeTranscriptEvents: false });
             if (existing) {
                 if (!sameOwner({ run: existing, required }))
                     return null;
                 await cancel({ runId: existing.runId, reason: "user-stop" }, {});
-                return load({ messageId: existing.messageId }, {});
+                return load({ messageId: existing.messageId }, { includeTranscriptEvents: false });
             }
             // Stop may beat acceptance or its response. A terminal tombstone for the same logical
             // identity makes any later duplicate acceptance a no-op, without reserving the chat slot.
             await history.appendMessage({ conversationId: required.conversationId, message: { id: required.messageId, role: "assistant", content: "",
                     events: [{ kind: "status", label: "Stopped." }], runId: required.runId, runStatus: "canceled", createdAt: required.now, endedAt: required.now } });
-            return load({ messageId: required.messageId }, {});
+            return load({ messageId: required.messageId }, { includeTranscriptEvents: false });
         });
     }
     async function saveAgentSession({ run, sessionId }) {
@@ -430,6 +497,6 @@ export function createDurableRunStore({ kernel: hostKernel, isDaemonRunId }, _op
             await writeAttemptMetadata({ values: { ...row, recovery_deadline: deadline, recovery_elapsed_ms: elapsed }, updates: { recovery_deadline: deadline, recovery_elapsed_ms: elapsed } });
         });
     }
-    return { load, find, accept, advance, cancel, cancelPending, captureSession, clearSession, guardTool, completeTool, recoveryClock };
+    return { load, head, poll, find, accept, advance, cancel, cancelPending, captureSession, clearSession, guardTool, completeTool, recoveryClock };
 }
 //# sourceMappingURL=durable-run-store.js.map

package/dist/store/runtime/events-json.d.ts

@@ -0,0 +1,17 @@
+import type { AgentEvent } from "../../core/index.js";
+/** Replace a compact array's suffix without transferring the stored prefix to JS.
+ * SQL length/substr count characters on SQLite and PostgreSQL, including non-BMP text.
+ * @complexity One SQL string splice; only the new suffix crosses the kernel boundary. */
+export declare function spliceEventsJson({ removeCharacters, suffix }: {
+    removeCharacters: number;
+    suffix: string;
+}, _options?: {}): import("kysely").RawBuilder<string>;
+/** `events_json` with one more event, built in SQL: no dialect parses or re-serializes the saved
+ * array in JS. Writers store `JSON.stringify` output (no whitespace), so a non-empty array is
+ * `[...]` and gains `,event`; `[]`, NULL and anything not array-shaped (a truncated legacy value,
+ * which the old JS read also treated as no events) become `[event]`. Plain `substr`/`length`/`||`
+ * run unchanged on SQLite and PostgreSQL. */
+export declare function appendedEventsJson({ event }: {
+    event: AgentEvent;
+}, _optional?: {}): import("kysely").RawBuilder<string>;
+//# sourceMappingURL=events-json.d.ts.map

package/dist/store/runtime/events-json.js

@@ -0,0 +1,19 @@
+import { sql } from "kysely";
+/** Replace a compact array's suffix without transferring the stored prefix to JS.
+ * SQL length/substr count characters on SQLite and PostgreSQL, including non-BMP text.
+ * @complexity One SQL string splice; only the new suffix crosses the kernel boundary. */
+export function spliceEventsJson({ removeCharacters, suffix }, _options = {}) {
+    return sql `substr(events_json, 1, length(events_json) - ${removeCharacters}) || cast(${suffix} as text)`;
+}
+/** `events_json` with one more event, built in SQL: no dialect parses or re-serializes the saved
+ * array in JS. Writers store `JSON.stringify` output (no whitespace), so a non-empty array is
+ * `[...]` and gains `,event`; `[]`, NULL and anything not array-shaped (a truncated legacy value,
+ * which the old JS read also treated as no events) become `[event]`. Plain `substr`/`length`/`||`
+ * run unchanged on SQLite and PostgreSQL. */
+export function appendedEventsJson({ event }, _optional = {}) {
+    const item = JSON.stringify(event);
+    const suffix = spliceEventsJson({ removeCharacters: 1, suffix: ',' + item + ']' });
+    const empty = '[' + item + ']';
+    return sql `case when events_json like '[_%]' then ${suffix} else cast(${empty} as text) end`;
+}
+//# sourceMappingURL=events-json.js.map

package/dist/store/runtime/run-guarded-chat-store.js

@@ -1,5 +1,11 @@
 /** Bind the server-owned run write fence to an already owner-scoped transcript. */
 export function createRunGuardedChatStore({ store, ledger, isDaemonRunId }, _optional = {}) {
+    async function savedMessage({ conversationId, messageId }, _optional = {}) {
+        if (store.message)
+            return store.message({ conversationId, messageId }, {});
+        // Compatibility for hosts/fakes without the indexed read capability.
+        return (await store.messages({ conversationId })).find(message => message.id === messageId) ?? null;
+    }
     return {
         ...store,
         /*
@@ -24,7 +30,7 @@ export function createRunGuardedChatStore({ store, ledger, isDaemonRunId }, _opt
                     // attempt id or a transport-only failure; returning the stored row fences both without
                     // matching presentation text. BYOK/AG-UI remain request-bound.
                     if (isDaemonRunId({ runId })) {
-                        const saved = (await store.messages({ conversationId })).find((m) => m.id === message.id);
+                        const saved = await savedMessage({ conversationId, messageId: message.id });
                         if (saved)
                             return saved;
                         if (message.runStatus !== "queued" && message.runStatus !== "running")
@@ -34,8 +40,7 @@ export function createRunGuardedChatStore({ store, ledger, isDaemonRunId }, _opt
                 } }, {});
             if (outcome.written)
                 return outcome.value;
-            const saved = await store.messages({ conversationId });
-            return saved.find((m) => m.id === message.id) ?? null;
+            return savedMessage({ conversationId, messageId: message.id });
         },
     };
 }

package/dist/store/runtime/run-ledger.d.ts

@@ -6,8 +6,8 @@ export { runLockKey } from "../../core/durable-runs/run-lock.js";
 /**
  * @param store the chat kernel, or the open `chat.db` handle `createChatStoreFactory` also wraps.
  * @param now Injectable epoch-millisecond clock for progress stamps and the default cancel time.
- * @complexity each method is one or two indexed statements, except `reconcileInterrupted`, which
- *   is O(stuck rows).
+ * @complexity indexed guards; checkpoints cost O(delta bytes) plus a SQLite scalar receipt read,
+ *   or O(saved + incoming bytes) on fallback. Reconcile costs O(stuck rows + their event bytes).
  */
 export declare function createChatRunLedger<DB extends ChatDatabase>({ kernel: hostKernel, isDaemonRunId }: {
     kernel: ChatKernel<DB>;

package/dist/store/runtime/run-ledger.js

@@ -1,4 +1,8 @@
 import { dedupeToolUsesById } from "../../core/tool-events.js";
+import { sql } from "kysely";
+import { sqliteReadVersion } from "../sql/read-version.js";
+import { spliceEventsJson } from "./events-json.js";
+import { checkpointDelta, checkpointState, hasNewToolProgress, toolKey } from "./checkpoint-delta.js";
 import { chatKernelTables } from "../sql/boundary.js";
 import { createDurableRunStore } from "./durable-run-store.js";
 /**
@@ -48,18 +52,6 @@ function readEvents(eventsJson) {
     }
     return Array.isArray(events) ? events : [];
 }
-/** Tool identity shared by progress detection and checkpoint merging; "" for non-tool events. */
-function toolKey(event) {
-    if (event.kind === "tool_use")
-        return `use:${event.id}`;
-    if (event.kind === "tool_result")
-        return `result:${event.toolUseId}`;
-    return "";
-}
-function hasNewToolProgress(current, next) {
-    const saved = new Set(current.map(toolKey));
-    return next.some((event) => { const id = toolKey(event); return id !== "" && !saved.has(id); });
-}
 /** Retain a longer checkpoint's text and merge non-text replay events under the shared ID rule.
  * @complexity O(b + n) time and space for b serialized bytes across n events. */
 function retainSavedEvents(saved, incoming) {
@@ -72,9 +64,11 @@ function retainSavedEvents(saved, incoming) {
  *
  * The saved `events_json` is parsed ONCE and reused by both the merge and the progress check:
  * a long turn's column is many MB, and a host checkpoints every second (memory cause 3).
- * Appending only new events instead of rewriting the column is NOT equivalent: storage coalesces
- * text deltas (the last text event grows in place) and the merge puts saved-only tool barriers
- * after the replay's events, so an existing element or the tail changes on most checkpoints.
+ * Blindly appending only new events is NOT equivalent: storage coalesces text deltas (the last
+ * text event grows in place) and the merge puts saved-only tool barriers after replay events.
+ * The watch-owned delta may replace that text tail only after an exact incoming write; saved-only
+ * barriers disable it. Native versions, SQL lengths and bounded suffix CAS detect concurrent
+ * appends and equal-length replacements; any miss uses this authoritative merge, never a ledger cache or freshness stamp.
  * @complexity O(b + n) time and space for b serialized bytes across n events; one parse, one stringify.
  */
 function planCheckpoint({ current, progress }, _optional = {}) {
@@ -86,27 +80,30 @@ function planCheckpoint({ current, progress }, _optional = {}) {
     const runStatus = current.run_status === "queued" ? "running" : current.run_status;
     return {
         eventsJson,
+        exact: events.length === progress.events.length && events.every((event, index) => event === progress.events[index]),
         runStatus,
-        grown: progress.content.length > current.content.length || hasNewToolProgress(saved, events),
+        grown: progress.content.length > current.content.length || hasNewToolProgress({ saved, incoming: events }),
         unchanged: runStatus === current.run_status && progress.content === current.content && eventsJson === current.events_json,
     };
 }
 /** Preserve tool barriers absent from a replay, with one persisted use per tool ID.
  * @complexity O(n) time and space in the combined saved and incoming event count. */
 function keepToolCheckpoints(saved, incoming) {
-    const seen = new Set(incoming.map(toolKey));
+    const seen = new Set(incoming.map(event => toolKey({ event })));
     // Deduplicate after merging: a legacy checkpoint or replay can repeat an ID with different
     // serialized input. The shared ID rule owns identity; JSON equality does not.
-    return dedupeToolUsesById({ events: [...incoming, ...saved.filter((event) => { const id = toolKey(event); return id !== "" && !seen.has(id); })] });
+    return dedupeToolUsesById({ events: [...incoming, ...saved.filter((event) => { const id = toolKey({ event }); return id !== "" && !seen.has(id); })] });
 }
 /**
  * @param store the chat kernel, or the open `chat.db` handle `createChatStoreFactory` also wraps.
  * @param now Injectable epoch-millisecond clock for progress stamps and the default cancel time.
- * @complexity each method is one or two indexed statements, except `reconcileInterrupted`, which
- *   is O(stuck rows).
+ * @complexity indexed guards; checkpoints cost O(delta bytes) plus a SQLite scalar receipt read,
+ *   or O(saved + incoming bytes) on fallback. Reconcile costs O(stuck rows + their event bytes).
  */
 export function createChatRunLedger({ kernel: hostKernel, isDaemonRunId }, { now = () => Date.now() } = {}) {
     const kernel = chatKernelTables({ kernel: hostKernel }, {});
+    const version = kernel.dialect === 'sqlite' ? sqliteReadVersion({ kernel }) : sql `cast(ai_chat_messages.xmin as text)`;
+    const returnedVersion = kernel.dialect === 'sqlite' ? sql `null` : version;
     async function isSettled(run) {
         const row = await kernel.run((db) => db
             .selectFrom("ai_chat_messages")
@@ -117,8 +114,99 @@ export function createChatRunLedger({ kernel: hostKernel, isDaemonRunId }, { now
             .executeTakeFirst());
         return isTerminal(row?.run_status);
     }
+    /** Progress earns a fresh recovery budget. Replayed prefixes/dividers cannot keep a failing
+     * attempt alive forever. Kept separate so full and delta writes use exactly the same reset. */
+    async function recordProgress({ progress }, _options = {}) {
+        await kernel.run((db) => db.updateTable("assistant_run_attempts")
+            .set({ recovery_count: 0, recovery_deadline: null, recovery_elapsed_ms: 0, last_progress_at: now() })
+            .where("message_id", "=", progress.messageId).execute());
+    }
+    /** One guarded delta UPDATE, no saved-column read or parse. A miss is deliberately indistinguishable
+     * from an ineligible delta: both must consult the authoritative checkpoint path under this lock. */
+    async function writeDelta({ progress, optional }, _options = {}) {
+        const { previous, expected } = optional;
+        if (!previous || expected !== previous.length)
+            return false;
+        const delta = checkpointDelta({ previous, progress });
+        if (!delta)
+            return false;
+        const result = await kernel.run((db) => db.updateTable("ai_chat_messages")
+            .set({ content: progress.content, events_json: spliceEventsJson(delta),
+            run_status: sql `case when run_status = 'queued' then 'running' else run_status end` })
+            .where(activeRunPredicate({ run: progress }))
+            .where(sql `${version} = ${previous.version}`)
+            .where(sql `length(events_json) = ${expected}`)
+            // BYOK/AG-UI browser upserts can replace a queued/running projection at the same length.
+            // Durable tool appends grow the length; recovery replacements also change run_id.
+            .where(sql `substr(events_json, length(events_json) - length(cast(${previous.tail} as text)) + 1) = ${previous.tail}`)
+            .where(sql `length(content) = ${previous.contentLength}`)
+            .returning([sql `length(events_json)`.as("length"), sql `length(content)`.as("contentLength"), returnedVersion.as("version")])
+            .executeTakeFirst());
+        if (!result)
+            return false;
+        if (delta.grown)
+            await recordProgress({ progress });
+        await notifyPersisted({ progress, optional, length: Number(result.length), contentLength: Number(result.contentLength), nativeVersion: result.version, exact: true });
+        return true;
+    }
+    /** A saved-only barrier invalidates the receipt. SQLite samples its connection/external-commit
+     * generation after ALL writes, while still under the transaction lock. Never capture a later
+     * writer's version beside this projection. PG returns the updated row's own MVCC version.
+     * @complexity O(1) scalar SQLite read per requested receipt; no payload query or PG extra read.
+     */
+    async function notifyPersisted({ progress, optional, length, contentLength, nativeVersion, exact }, _options = {}) {
+        if (!optional.onPersisted)
+            return;
+        if (!exact) {
+            optional.onPersisted(undefined);
+            return;
+        }
+        const receiptVersion = kernel.dialect === 'sqlite'
+            ? (await kernel.query(sql `select ${version} as version`))[0].version : nativeVersion;
+        optional.onPersisted(checkpointState({ progress, length, contentLength, version: receiptVersion }));
+    }
+    /** Full merge fallback, including identical-checkpoint write elision. One parse/stringify only. */
+    async function writeFullCheckpoint({ progress, optional }, _options = {}) {
+        const current = await kernel.run((db) => db.selectFrom("ai_chat_messages")
+            .select(["content", "events_json", "run_status", sql `length(events_json)`.as("length"), sql `length(content)`.as("contentLength"), returnedVersion.as("version")])
+            .where(activeRunPredicate({ run: progress })).executeTakeFirst());
+        if (!current || progress.content.length < current.content.length)
+            return false;
+        const plan = planCheckpoint({ current, progress });
+        // Identical content/events are not progress; accepting without rewriting leaves both the
+        // multi-MB column and recovery budget exactly as the guarded UPDATE would have.
+        // Under this lock the row was just matched by the update's own predicate, so the update
+        // would match (true); returning true without writing preserves that contract.
+        if (plan.unchanged) {
+            await notifyPersisted({ progress, optional, length: Number(current.length), contentLength: Number(current.contentLength), nativeVersion: current.version, exact: plan.exact });
+            return true;
+        }
+        const result = await kernel.run((db) => db.updateTable("ai_chat_messages")
+            .set({ content: progress.content, events_json: plan.eventsJson, run_status: plan.runStatus })
+            .where(activeRunPredicate({ run: progress }))
+            .returning([sql `length(events_json)`.as("length"), sql `length(content)`.as("contentLength"), returnedVersion.as("version")]).executeTakeFirst());
+        if (!result)
+            return false;
+        if (plan.grown)
+            await recordProgress({ progress });
+        await notifyPersisted({ progress, optional, length: Number(result.length), contentLength: Number(result.contentLength), nativeVersion: result.version, exact: plan.exact });
+        return true;
+    }
     return {
         durable: createDurableRunStore({ kernel, isDaemonRunId }, {}),
+        /** One bounded existence read, across owners and engines. Stale active rows conservatively
+         * keep the host awake; recovery belongs to the serving boot, never an idle probe.
+         * @complexity O(log n) covering-index lookup for n messages; O(1) returned space, no payload reads.
+         */
+        async hasActiveRuns(_required = {}, _optional = {}) {
+            const row = await kernel.run(db => db.selectFrom("ai_chat_messages").select("id")
+                .where("role", "=", "assistant")
+                // Keep the fixed literal predicate identical to the partial index. Parameterized IN
+                // cannot establish SQLite's partial-index implication at plan time.
+                .where(sql `run_status in ('queued', 'running')`)
+                .limit(1).executeTakeFirst());
+            return row !== undefined;
+        },
         unlessSettled({ run, write }, _optional = {}) {
             return kernel.transaction(async () => {
                 await kernel.lockKey(runLockKey(run));
@@ -161,34 +249,21 @@ export function createChatRunLedger({ kernel: hostKernel, isDaemonRunId }, { now
                 return true;
             });
         },
-        async checkpoint(progress, _optional = {}) {
-            return kernel.transaction(async () => {
+        async checkpoint(progress, optional = {}) {
+            let persisted = false;
+            let receipt;
+            // Publish the watch receipt only after COMMIT. A rollback must not advance its CAS base.
+            const transactionOptions = optional.onPersisted
+                ? { ...optional, onPersisted: (value) => { persisted = true; receipt = value; } } : optional;
+            const written = await kernel.transaction(async () => {
                 await kernel.lockKey(runLockKey(progress));
-                const current = await kernel.run((db) => db.selectFrom("ai_chat_messages").select(["content", "events_json", "run_status"])
-                    .where(activeRunPredicate({ run: progress })).executeTakeFirst());
-                if (!current || progress.content.length < current.content.length)
-                    return false;
-                const { eventsJson, runStatus, grown, unchanged } = planCheckpoint({ current, progress });
-                // An identical checkpoint would rewrite the same multi-MB column for nothing. Under this lock
-                // the row was just matched by the update's own predicate, so the update would match (true),
-                // and identical content and events are never progress (`grown` is false), so skipping it
-                // leaves the row and the recovery budget exactly as the write would have.
-                if (unchanged)
+                if (await writeDelta({ progress, optional: transactionOptions }))
                     return true;
-                const result = await kernel.run((db) => db
-                    .updateTable("ai_chat_messages")
-                    .set({ content: progress.content, events_json: eventsJson, run_status: runStatus })
-                    .where(activeRunPredicate({ run: progress }))
-                    .executeTakeFirst());
-                if (Number(result.numUpdatedRows) > 0 && grown) {
-                    // Progress earns a fresh recovery budget. Replayed prefixes and the coordinator's
-                    // divider are not progress and cannot keep a repeatedly failing attempt alive forever.
-                    await kernel.run((db) => db.updateTable("assistant_run_attempts")
-                        .set({ recovery_count: 0, recovery_deadline: null, recovery_elapsed_ms: 0, last_progress_at: now() })
-                        .where("message_id", "=", progress.messageId).execute());
-                }
-                return Number(result.numUpdatedRows) > 0;
+                return writeFullCheckpoint({ progress, optional: transactionOptions });
             });
+            if (persisted)
+                optional.onPersisted?.(receipt);
+            return written;
         },
         async reconcileInterrupted(required = {}, optional = {}) {
             const stuck = await kernel.run((db) => db

package/dist/store/sql/read-version.d.ts

@@ -0,0 +1,15 @@
+import { type RawBuilder } from 'kysely';
+/** SQLite invalidation without scanning message rows. Both same-connection writes and external
+ * commits invalidate; the kernel epoch prevents counters reused after reopen from hiding changes.
+ * @param required.kernel The existing borrowed connection identity; never opens or changes it.
+ * @param optional.mintEpoch Injectable epoch source, called once per live kernel.
+ * @returns A SQL scalar with bounded output, without event/content reads or writes.
+ * @complexity O(1) time and weak identity space per kernel.
+ * @example sqliteReadVersion({ kernel });
+ */
+export declare function sqliteReadVersion({ kernel }: {
+    kernel: object;
+}, { mintEpoch }?: {
+    mintEpoch?: () => string;
+}): RawBuilder<string>;
+//# sourceMappingURL=read-version.d.ts.map

package/dist/store/sql/read-version.js

@@ -0,0 +1,21 @@
+import { sql } from 'kysely';
+// Weak identity metadata only, never row data. Closing/replacing a kernel releases its epoch with GC.
+const epochs = new WeakMap();
+/** SQLite invalidation without scanning message rows. Both same-connection writes and external
+ * commits invalidate; the kernel epoch prevents counters reused after reopen from hiding changes.
+ * @param required.kernel The existing borrowed connection identity; never opens or changes it.
+ * @param optional.mintEpoch Injectable epoch source, called once per live kernel.
+ * @returns A SQL scalar with bounded output, without event/content reads or writes.
+ * @complexity O(1) time and weak identity space per kernel.
+ * @example sqliteReadVersion({ kernel });
+ */
+export function sqliteReadVersion({ kernel }, { mintEpoch = () => globalThis.crypto.randomUUID() } = {}) {
+    let epoch = epochs.get(kernel);
+    if (epoch === undefined) {
+        epoch = mintEpoch();
+        epochs.set(kernel, epoch);
+    }
+    // Connection-wide counters invalidate every row on any chat.db write; concurrent chats can erase the cache savings.
+    return sql `${epoch} || ':' || cast(total_changes() as text) || ':' || cast((select data_version from pragma_data_version) as text)`;
+}
+//# sourceMappingURL=read-version.js.map