@jini-ai/chat 0.6.6 → 0.6.10

package/dist/store/runtime/history-tools.js

@@ -37,25 +37,38 @@ function capMessage({ view }, _options = {}) {
     }
     return view;
 }
+function toolOutcome({ isError }, _options = {}) {
+    if (isError === true)
+        return 'failed';
+    return isError === false ? 'succeeded' : 'unknown';
+}
+/** Outcome per tool-use id; malformed historical events are ignored. */
+function toolOutcomes({ events }, _options = {}) {
+    const outcomes = new Map();
+    for (const raw of events) {
+        const event = raw;
+        if (event?.kind === 'tool_result' && typeof event.toolUseId === 'string')
+            outcomes.set(event.toolUseId, toolOutcome({ isError: event.isError }));
+    }
+    return outcomes;
+}
+/** Well-formed tool-use events in stored order; malformed historical events are ignored. */
+function toolUses({ events }, _options = {}) {
+    return events.filter((raw) => {
+        const event = raw;
+        return event?.kind === 'tool_use' && typeof event.name === 'string';
+    });
+}
 /** Only bounded names and status cross this boundary; malformed historical events are ignored.
  * @complexity O(e) time/space in persisted events; output is capped at 50 summaries.
  */
 function summarizeTools({ events, redact }, _options = {}) {
     if (!Array.isArray(events))
         return { items: [], truncated: false };
-    const outcomes = new Map();
-    for (const raw of events) {
-        const event = raw;
-        if (event?.kind === 'tool_result' && typeof event.toolUseId === 'string') {
-            outcomes.set(event.toolUseId, event.isError === true ? 'failed' : event.isError === false ? 'succeeded' : 'unknown');
-        }
-    }
+    const outcomes = toolOutcomes({ events });
     const items = [];
     let truncated = false;
-    for (const raw of events) {
-        const event = raw;
-        if (event?.kind !== 'tool_use' || typeof event.name !== 'string')
-            continue;
+    for (const event of toolUses({ events })) {
         if (items.length === TOOL_EVENT_CAP) {
             truncated = true;
             break;
@@ -82,6 +95,98 @@ function inputRecord({ input, keys }, _options = {}) {
         throw new ToolInputError({ message: 'Unexpected chat history input field. Use the published schema.' });
     return record;
 }
+/** The scoped store's bounded reader; hosts without one fail closed for both tools. */
+async function openHistory({ ports, principalId }, _options = {}) {
+    const store = await ports.getStore({ principalId }, {});
+    if (!store.history)
+        throw new ToolInputError({ message: 'Chat history is unavailable on this site.' });
+    return { store, history: store.history };
+}
+function listInput({ input: raw }, _options = {}) {
+    const input = inputRecord({ input: raw, keys: ['query', 'limit'] });
+    if (input.query !== undefined && (typeof input.query !== 'string' || input.query.length > 200))
+        throw new ToolInputError({ message: 'query must be a string of at most 200 characters.' });
+    const limit = integerOption({ input, key: 'limit', fallback: 20, max: 50 });
+    return { ...(input.query === undefined ? {} : { query: input.query }), limit };
+}
+function projectChatRow({ row, redact }, _options = {}) {
+    // Redact BEFORE slicing: a cap must not turn a credential into an undetectable fragment.
+    const title = redact({ text: row.title ?? '' }).text;
+    const first = redact({ text: row.firstUserLine }).text.split(/\r?\n/, 1)[0];
+    const truncated = title.length > 300 || first.length > 500 || row.id.length > 128;
+    return { truncated, chat: { id: redact({ text: row.id }).text.slice(0, 128), title: title.slice(0, 300), updatedAt: row.updatedAt,
+            messageCount: row.messageCount, firstUserLine: first.slice(0, 500) } };
+}
+async function listChats({ ports, redact, ctx }, _options = {}) {
+    const options = listInput({ input: ctx.input });
+    const { history } = await openHistory({ ports, principalId: ctx.principal.id });
+    const projected = (await history.list({}, options)).map(row => projectChatRow({ row, redact }));
+    const chats = projected.map(item => item.chat);
+    let truncated = projected.some(item => item.truncated);
+    // List is bounded too; serialized escaping can make text larger than its character count.
+    while (JSON.stringify({ chats, truncated }).length > HISTORY_TOTAL_CHAR_CAP) {
+        chats.pop();
+        truncated = true;
+    }
+    return { chats, truncated };
+}
+function readInput({ input: raw }, _options = {}) {
+    const input = inputRecord({ input: raw, keys: ['chatId', 'fromPosition', 'limit', 'includeToolEvents'] });
+    if (typeof input.chatId !== 'string' || !input.chatId.trim() || input.chatId.length > 128)
+        throw new ToolInputError({ message: 'chatId must be an id returned by assistant_chats_list.' });
+    const limit = integerOption({ input, key: 'limit', fallback: 50, max: 100 });
+    const fromPosition = input.fromPosition === undefined ? undefined : integerOption({ input, key: 'fromPosition', fallback: 0, max: Number.MAX_SAFE_INTEGER, min: 0 });
+    if (input.includeToolEvents !== undefined && typeof input.includeToolEvents !== 'boolean')
+        throw new ToolInputError({ message: 'includeToolEvents must be boolean.' });
+    return { chatId: input.chatId, limit, ...(fromPosition === undefined ? {} : { fromPosition }), includeToolEvents: input.includeToolEvents === true };
+}
+function projectMessage({ row, includeToolEvents, redact }, _options = {}) {
+    const content = redact({ text: row.content }).text;
+    const tools = includeToolEvents ? summarizeTools({ events: row.events, redact }) : undefined;
+    return capMessage({ view: { id: redact({ text: row.id }).text.slice(0, 128), role: row.role === 'user' ? 'user' : 'assistant', position: row.position,
+            content: content.slice(0, HISTORY_MESSAGE_CHAR_CAP), truncated: content.length > HISTORY_MESSAGE_CHAR_CAP || row.id.length > 128 || tools?.truncated === true,
+            ...(tools ? { toolEvents: tools.items } : {}) } });
+}
+/** Fill the serialized page budget in candidate order; the first row always fits. */
+function fillPage({ candidates, project }, _options = {}) {
+    const messages = [];
+    let truncated = false;
+    // Reserve result envelope/continuation space; measure serialized messages, including escapes.
+    let remaining = HISTORY_TOTAL_CHAR_CAP - 512;
+    for (const row of candidates) {
+        const view = project(row);
+        if (JSON.stringify(view).length > remaining && messages.length > 0) {
+            truncated = true;
+            break;
+        }
+        // Advance only over returned positions; the next page must include the omitted row.
+        messages.push(view);
+        remaining -= JSON.stringify(view).length + 1;
+        if (view.truncated)
+            truncated = true;
+    }
+    return { messages, truncated };
+}
+async function readChat({ ports, redact, ctx }, _options = {}) {
+    const { chatId, limit, fromPosition, includeToolEvents } = readInput({ input: ctx.input });
+    const { store, history } = await openHistory({ ports, principalId: ctx.principal.id });
+    if (!await store.get({ id: chatId }, {}))
+        throw new ToolInputError({ message: 'Chat is unavailable to this caller. Choose an id from assistant_chats_list.' });
+    const tail = fromPosition === undefined;
+    const page = await history.read({ chatId }, { ...(tail ? {} : { fromPosition }), limit, includeToolEvents });
+    const filled = fillPage({ candidates: tail ? [...page.messages].reverse() : page.messages, project: row => projectMessage({ row, includeToolEvents, redact }) });
+    return pageResult({ chatId: redact({ text: chatId }).text, tail, page, filled });
+}
+/** Continuation envelope: positions come only from returned rows, so no row is ever skipped. */
+function pageResult({ chatId, tail, page, filled }, _options = {}) {
+    const messages = tail ? filled.messages.reverse() : filled.messages;
+    const last = messages.at(-1), first = messages.at(0);
+    const more = messages.length < page.messages.length || page.hasMore;
+    return { chatId, messages, truncated: page.hasMore || filled.truncated, hasMore: !tail && more,
+        ...(last ? { nextPosition: last.position + 1 } : {}),
+        ...(first ? { firstPosition: first.position } : {}),
+        hasMoreBefore: tail && more };
+}
 /** Build both history registrations, using the existing catalog/risk/metadata contract.
  * @param ports Authenticated scoped-store port; denied/missing history must fail closed.
  * @param options Optional stricter redaction policy (the secret-card policy is the default).
@@ -92,77 +197,8 @@ export function buildAssistantHistoryRegistrations({ ports }, { redact = redactU
     return buildDomainRegistrations({ domain: 'assistant-history', catalogModule: 'chat/store/runtime/history-tools', catalog: assistantHistoryToolCatalog,
         derivedRisk: assistantHistoryDerivedRisk, metadata: assistantHistoryToolMetadata,
         handlers: {
-            assistant_chats_list: async (ctx) => {
-                const input = inputRecord({ input: ctx.input, keys: ['query', 'limit'] });
-                if (input.query !== undefined && (typeof input.query !== 'string' || input.query.length > 200))
-                    throw new ToolInputError({ message: 'query must be a string of at most 200 characters.' });
-                const limit = integerOption({ input, key: 'limit', fallback: 20, max: 50 });
-                const store = await ports.getStore({ principalId: ctx.principal.id }, {});
-                if (!store.history)
-                    throw new ToolInputError({ message: 'Chat history is unavailable on this site.' });
-                const rows = await store.history.list({}, { ...(input.query === undefined ? {} : { query: input.query }), limit });
-                let truncated = false;
-                const chats = rows.map(row => {
-                    // Redact BEFORE slicing: a cap must not turn a credential into an undetectable fragment.
-                    const title = redact({ text: row.title ?? '' }).text;
-                    const first = redact({ text: row.firstUserLine }).text.split(/\r?\n/, 1)[0];
-                    if (title.length > 300 || first.length > 500 || row.id.length > 128)
-                        truncated = true;
-                    return { id: redact({ text: row.id }).text.slice(0, 128), title: title.slice(0, 300), updatedAt: row.updatedAt,
-                        messageCount: row.messageCount, firstUserLine: first.slice(0, 500) };
-                });
-                // List is bounded too; serialized escaping can make text larger than its character count.
-                while (JSON.stringify({ chats, truncated }).length > HISTORY_TOTAL_CHAR_CAP) {
-                    chats.pop();
-                    truncated = true;
-                }
-                return { chats, truncated };
-            },
-            assistant_chat_read: async (ctx) => {
-                const input = inputRecord({ input: ctx.input, keys: ['chatId', 'fromPosition', 'limit', 'includeToolEvents'] });
-                if (typeof input.chatId !== 'string' || !input.chatId.trim() || input.chatId.length > 128)
-                    throw new ToolInputError({ message: 'chatId must be an id returned by assistant_chats_list.' });
-                const limit = integerOption({ input, key: 'limit', fallback: 50, max: 100 });
-                const fromPosition = input.fromPosition === undefined ? undefined : integerOption({ input, key: 'fromPosition', fallback: 0, max: Number.MAX_SAFE_INTEGER, min: 0 });
-                if (input.includeToolEvents !== undefined && typeof input.includeToolEvents !== 'boolean')
-                    throw new ToolInputError({ message: 'includeToolEvents must be boolean.' });
-                const store = await ports.getStore({ principalId: ctx.principal.id }, {});
-                if (!store.history)
-                    throw new ToolInputError({ message: 'Chat history is unavailable on this site.' });
-                if (!await store.get({ id: input.chatId }, {}))
-                    throw new ToolInputError({ message: 'Chat is unavailable to this caller. Choose an id from assistant_chats_list.' });
-                const page = await store.history.read({ chatId: input.chatId }, { ...(fromPosition === undefined ? {} : { fromPosition }), limit, includeToolEvents: input.includeToolEvents === true });
-                const messages = [];
-                let truncated = page.hasMore;
-                // Reserve result envelope/continuation space; measure serialized messages, including escapes.
-                let remaining = HISTORY_TOTAL_CHAR_CAP - 512;
-                const candidates = fromPosition === undefined ? [...page.messages].reverse() : page.messages;
-                for (const row of candidates) {
-                    const content = redact({ text: row.content }).text;
-                    const tools = input.includeToolEvents === true ? summarizeTools({ events: row.events, redact }) : undefined;
-                    const view = capMessage({ view: { id: redact({ text: row.id }).text.slice(0, 128), role: row.role === 'user' ? 'user' : 'assistant', position: row.position,
-                            content: content.slice(0, HISTORY_MESSAGE_CHAR_CAP), truncated: content.length > HISTORY_MESSAGE_CHAR_CAP || row.id.length > 128 || tools?.truncated === true,
-                            ...(tools ? { toolEvents: tools.items } : {}) } });
-                    if (JSON.stringify(view).length > remaining && messages.length > 0) {
-                        truncated = true;
-                        break;
-                    }
-                    // Advance only over returned positions; the next page must include the omitted row.
-                    messages.push(view);
-                    remaining -= JSON.stringify(view).length + 1;
-                    if (view.truncated)
-                        truncated = true;
-                }
-                if (fromPosition === undefined)
-                    messages.reverse();
-                const last = messages.at(-1), first = messages.at(0);
-                const omitted = messages.length < page.messages.length;
-                const hasMore = fromPosition !== undefined && (omitted || page.hasMore);
-                return { chatId: redact({ text: input.chatId }).text, messages, truncated, hasMore,
-                    ...(last ? { nextPosition: last.position + 1 } : {}),
-                    ...(first ? { firstPosition: first.position } : {}),
-                    hasMoreBefore: fromPosition === undefined && (omitted || page.hasMore) };
-            },
+            assistant_chats_list: ctx => listChats({ ports, redact, ctx }),
+            assistant_chat_read: ctx => readChat({ ports, redact, ctx }),
         },
     });
 }

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

@@ -5,11 +5,14 @@ import type { ChatRunLedger } from "../../core/durable-runs/ledger-contracts.js"
 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).
  */
 export declare function createChatRunLedger<DB extends ChatDatabase>({ kernel: hostKernel, isDaemonRunId }: {
     kernel: ChatKernel<DB>;
     isDaemonRunId: RunIdPolicy;
-}, _optional?: {}): ChatRunLedger;
+}, { now }?: {
+    now?: () => number;
+}): ChatRunLedger;
 //# sourceMappingURL=run-ledger.d.ts.map

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

@@ -1,3 +1,4 @@
+import { dedupeToolUsesById } from "../../core/tool-events.js";
 import { chatKernelTables } from "../sql/boundary.js";
 import { createDurableRunStore } from "./durable-run-store.js";
 /**
@@ -47,27 +48,64 @@ 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 key = (event) => event.kind === "tool_use" ? `use:${event.id}` : event.kind === "tool_result" ? `result:${event.toolUseId}` : "";
-    const saved = new Set(current.map(key));
-    return next.some((event) => { const id = key(event); return id !== "" && !saved.has(id); });
+    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) {
     const keys = new Set(saved.map((event) => JSON.stringify(event)));
     const additions = incoming.filter((event) => event.kind !== "text" && !keys.has(JSON.stringify(event)));
-    return [...saved, ...additions];
+    return dedupeToolUsesById({ events: [...saved, ...additions] });
+}
+/**
+ * The row a checkpoint writes, whether it is progress, and whether it changes anything.
+ *
+ * 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.
+ * @complexity O(b + n) time and space for b serialized bytes across n events; one parse, one stringify.
+ */
+function planCheckpoint({ current, progress }, _optional = {}) {
+    const saved = readEvents(current.events_json);
+    const events = keepToolCheckpoints(saved, progress.events);
+    const eventsJson = JSON.stringify(events);
+    // A checkpoint is the run producing output, so an accepted (`queued`) row is now `running`;
+    // nothing else moves it there, and a streaming answer must not read as still waiting.
+    const runStatus = current.run_status === "queued" ? "running" : current.run_status;
+    return {
+        eventsJson,
+        runStatus,
+        grown: progress.content.length > current.content.length || hasNewToolProgress(saved, 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 key = (event) => event.kind === "tool_use" ? `use:${event.id}` : event.kind === "tool_result" ? `result:${event.toolUseId}` : "";
-    const seen = new Set(incoming.map(key));
-    return [...incoming, ...saved.filter((event) => { const id = key(event); return id !== "" && !seen.has(id); })];
+    const seen = new Set(incoming.map(toolKey));
+    // 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); })] });
 }
 /**
  * @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).
  */
-export function createChatRunLedger({ kernel: hostKernel, isDaemonRunId }, _optional = {}) {
+export function createChatRunLedger({ kernel: hostKernel, isDaemonRunId }, { now = () => Date.now() } = {}) {
     const kernel = chatKernelTables({ kernel: hostKernel }, {});
     async function isSettled(run) {
         const row = await kernel.run((db) => db
@@ -130,21 +168,23 @@ export function createChatRunLedger({ kernel: hostKernel, isDaemonRunId }, _opti
                     .where((eb) => eb.and([isRunRow(eb, progress), notTerminal(eb)])).executeTakeFirst());
                 if (!current || progress.content.length < current.content.length)
                     return false;
-                const events = keepToolCheckpoints(readEvents(current.events_json), progress.events);
-                const grown = progress.content.length > current.content.length || hasNewToolProgress(readEvents(current.events_json), events);
-                // A checkpoint is the run producing output, so an accepted (`queued`) row is now `running`;
-                // nothing else moves it there, and a streaming answer must not read as still waiting.
-                const runStatus = current.run_status === "queued" ? "running" : current.run_status;
+                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)
+                    return true;
                 const result = await kernel.run((db) => db
                     .updateTable("ai_chat_messages")
-                    .set({ content: progress.content, events_json: JSON.stringify(events), run_status: runStatus })
+                    .set({ content: progress.content, events_json: eventsJson, run_status: runStatus })
                     .where((eb) => eb.and([isRunRow(eb, progress), notTerminal(eb)]))
                     .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: Date.now() })
+                        .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;
@@ -188,7 +228,7 @@ export function createChatRunLedger({ kernel: hostKernel, isDaemonRunId }, _opti
                         .where(matches).executeTakeFirst());
                     if (!current)
                         return false;
-                    const endedAt = required.now ?? Date.now();
+                    const endedAt = required.now ?? now();
                     const events = [...readEvents(current.events_json), { kind: "status", label: "Stopped. Saved work is above." }];
                     const result = await kernel.run((db) => db.updateTable("ai_chat_messages")
                         .set({ run_status: "canceled", ended_at: endedAt, events_json: JSON.stringify(events) })

package/dist/store/sql/cursor.js

@@ -16,34 +16,54 @@ export function encodeCursor({ kind, scope, conversation, anchor }) {
     const binary = Array.from(bytes, byte => String.fromCharCode(byte)).join('');
     return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
 }
-/** Validate version, exact structure, scope and read bindings before a query can run. */
-export function decodeCursor({ cursor, kind, scope, conversation }) {
-    if (cursor === undefined)
-        return undefined;
-    if (typeof cursor !== 'string' || cursor.length === 0 || cursor.length > 8192 || !/^[A-Za-z0-9_-]+$/.test(cursor)) {
-        throw new ChatStoreError({ code: 'invalid-cursor' });
-    }
-    let value;
+/** Every structural failure is the same refusal; callers never learn which check rejected it. */
+function invalidCursor() {
+    throw new ChatStoreError({ code: 'invalid-cursor' });
+}
+/** Shape check before decoding: a non-empty, bounded base64url string. Carries no cause. */
+function assertCursorText({ cursor }) {
+    if (typeof cursor !== 'string' || cursor.length === 0 || cursor.length > 8192 || !/^[A-Za-z0-9_-]+$/.test(cursor))
+        invalidCursor();
+}
+/** base64url -> strict UTF-8 -> JSON; any decode failure is wrapped with its cause attached. */
+function decodeBody({ cursor }) {
     try {
         const binary = atob(cursor.replaceAll('-', '+').replaceAll('_', '/'));
         const bytes = Uint8Array.from(binary, char => char.charCodeAt(0));
-        value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
     }
     catch (cause) {
         throw new ChatStoreError({ code: 'invalid-cursor' }, { cause });
     }
-    if (!Array.isArray(value) || value.length !== 5 || value[0] !== 1 || value[1] !== kind || value[3] !== conversation) {
-        throw new ChatStoreError({ code: 'invalid-cursor' });
-    }
-    const owner = value[2], anchor = value[4];
-    if (!Array.isArray(owner) || owner.length !== 3 || owner.some((part, i) => part !== ownerTuple(scope)[i])) {
-        throw new ChatStoreError({ code: 'invalid-cursor' });
-    }
+}
+/** Version, exact length, read kind and conversation binding. */
+function readEnvelope({ value, kind, conversation }) {
+    if (!Array.isArray(value) || value.length !== 5 || value[0] !== 1 || value[1] !== kind || value[3] !== conversation)
+        invalidCursor();
+    return value;
+}
+/** The cursor must carry exactly this scope's owner tuple. */
+function assertOwner({ owner, scope }) {
+    const expected = ownerTuple(scope);
+    if (!Array.isArray(owner) || owner.length !== 3 || owner.some((part, i) => part !== expected[i]))
+        invalidCursor();
+}
+/** A [finite number, string] pair; message positions must also be non-negative safe integers. */
+function readAnchor({ anchor, kind }) {
     if (!Array.isArray(anchor) || anchor.length !== 2 || typeof anchor[0] !== 'number' || !Number.isFinite(anchor[0]) || typeof anchor[1] !== 'string') {
-        throw new ChatStoreError({ code: 'invalid-cursor' });
+        invalidCursor();
     }
     if (kind === 'messages' && (!Number.isSafeInteger(anchor[0]) || anchor[0] < 0))
-        throw new ChatStoreError({ code: 'invalid-cursor' });
+        invalidCursor();
     return [anchor[0], anchor[1]];
 }
+/** Validate version, exact structure, scope and read bindings before a query can run. */
+export function decodeCursor({ cursor, kind, scope, conversation }) {
+    if (cursor === undefined)
+        return undefined;
+    assertCursorText({ cursor });
+    const envelope = readEnvelope({ value: decodeBody({ cursor }), kind, conversation });
+    assertOwner({ owner: envelope[2], scope });
+    return readAnchor({ anchor: envelope[4], kind });
+}
 //# sourceMappingURL=cursor.js.map

package/dist/store/sql/store.d.ts

@@ -1,8 +1,25 @@
 import { type Clock } from '@jini-ai/core/primitives';
 import { type StorageKernel } from '@jini-ai/db/kernel';
 import { type UserTextRedactionOptions } from '../../core/user-text-redaction.js';
+import type { ChatMessage } from '../../core/messages.js';
 import type { ChatStore, ChatOwnerScope } from '../ports.js';
 import type { ChatDatabase } from './tables.js';
+interface MessageRow {
+    id: string;
+    role: string;
+    content: string;
+    agent_id: string | null;
+    agent_name: string | null;
+    events_json: string | null;
+    attachments_json: string | null;
+    run_id: string | null;
+    run_status: string | null;
+    created_at: number;
+    started_at: number | null;
+    ended_at: number | null;
+}
+/** Project only existing ai_* fields: resumable and lastRunEventId belong to run state. */
+export declare function toMessage(row: MessageRow): ChatMessage;
 /**
  * Returns a {@link ChatHistoryStore} that can only ever see `scope`'s own conversations.
  *
@@ -20,4 +37,5 @@ export declare function createSqlChatStore<DB extends ChatDatabase>({ kernel, sc
 }, { clock, ...redactionOptions }?: {
     clock?: Clock;
 } & UserTextRedactionOptions): ChatStore;
+export {};
 //# sourceMappingURL=store.d.ts.map

package/dist/store/sql/store.js

@@ -27,9 +27,10 @@ function conversationLockKey(conversationId) {
 function toConversation(row) {
     return {
         id: row.id,
-        title: row.title ?? null,
-        titleSource: (row.title_source ?? "fallback"),
-        messageCount: Number(row.message_count ?? 0),
+        title: row.title,
+        titleSource: row.title_source,
+        // COUNT(*) never yields null; Number() also maps a driver's string/bigint count.
+        messageCount: Number(row.message_count),
         createdAt: Number(row.created_at),
         updatedAt: Number(row.updated_at),
         ...(row.expires_at === null ? {} : { expiresAt: Number(row.expires_at) }),
@@ -47,6 +48,10 @@ function safeParse(value) {
         return undefined;
     }
 }
+/** A NULL (or empty) JSON column is absent; anything else goes through {@link safeParse}. */
+function parseJsonColumn(value) {
+    return value ? safeParse(value) : undefined;
+}
 /** Project only existing ai_* fields: resumable and lastRunEventId belong to run state. */
 // Both fields disappear on a transcript round trip today. Adding columns alone would let the
 // browser persist claims about a run it does not own. First associate the run with its conversation
@@ -54,22 +59,52 @@ function safeParse(value) {
 // The legacy messages store does retain last_run_event_id; that is a separate trust model, not
 // evidence that this projection preserves it. A schema extension also needs host-owned follow-up
 // migrations, because changing the DDL constant cannot update databases already migrated.
-function toMessage(row) {
-    const events = row.events_json ? safeParse(row.events_json) : undefined;
-    const attachments = row.attachments_json ? safeParse(row.attachments_json) : undefined;
+export function toMessage(row) {
     return {
         id: row.id, role: row.role, content: row.content,
+        ...agentFields(row),
+        ...jsonFields(row),
+        ...runFields(row),
+        createdAt: Number(row.created_at),
+        ...(row.started_at === null ? {} : { startedAt: Number(row.started_at) }),
+        ...(row.ended_at === null ? {} : { endedAt: Number(row.ended_at) }),
+    };
+}
+/** Empty agent columns are omitted, not projected as empty strings. */
+function agentFields(row) {
+    return {
         ...(row.agent_id ? { agentId: row.agent_id } : {}),
         ...(row.agent_name ? { agentName: row.agent_name } : {}),
+    };
+}
+/** Unparseable or absent JSON columns are omitted rather than failing the read. */
+function jsonFields(row) {
+    const events = parseJsonColumn(row.events_json);
+    const attachments = parseJsonColumn(row.attachments_json);
+    return {
         ...(events === undefined ? {} : { events }),
         ...(attachments === undefined ? {} : { attachments }),
+    };
+}
+/** Empty run columns are omitted. */
+function runFields(row) {
+    return {
         ...(row.run_id ? { runId: row.run_id } : {}),
         ...(row.run_status ? { runStatus: row.run_status } : {}),
-        ...(row.created_at === null ? {} : { createdAt: Number(row.created_at) }),
-        ...(row.started_at === null ? {} : { startedAt: Number(row.started_at) }),
-        ...(row.ended_at === null ? {} : { endedAt: Number(row.ended_at) }),
     };
 }
+/** Reject an unbounded or malformed history read before any query runs. */
+function assertHistoryReadBounds({ limit, fromPosition }) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100 || (fromPosition !== undefined && (!Number.isSafeInteger(fromPosition) || fromPosition < 0))) {
+        throw new ChatStoreError({ code: 'invalid-input' });
+    }
+}
+/** Project one history row; `events` is present (possibly undefined) only when tool events were asked for. */
+function toHistoryMessage(row, { includeToolEvents }) {
+    return { id: row.id, role: row.role, content: row.content,
+        position: Number(row.position), createdAt: Number(row.created_at),
+        ...(includeToolEvents ? { events: parseJsonColumn(row.events_json) } : {}), };
+}
 /**
  * Returns a {@link ChatHistoryStore} that can only ever see `scope`'s own conversations.
  *
@@ -240,9 +275,7 @@ export function createSqlChatStore({ kernel, scope: inputScope }, { clock = crea
             },
             /** No attachment column is read. O(limit) rows; default tail is reversed into position order. */
             async read({ chatId }, { fromPosition, limit = 50, includeToolEvents = false } = {}) {
-                if (!Number.isInteger(limit) || limit < 1 || limit > 100 || (fromPosition !== undefined && (!Number.isSafeInteger(fromPosition) || fromPosition < 0))) {
-                    throw new ChatStoreError({ code: 'invalid-input' });
-                }
+                assertHistoryReadBounds({ limit, fromPosition });
                 const rows = await run(db => {
                     let statement = ownedMessages(db, chatId).clearSelect().select([
                         'm.id', 'm.role', 'm.content', 'm.position', 'm.created_at',
@@ -255,9 +288,7 @@ export function createSqlChatStore({ kernel, scope: inputScope }, { clock = crea
                 const page = rows.slice(0, limit);
                 if (fromPosition === undefined)
                     page.reverse();
-                return { messages: page.map(row => ({ id: row.id, role: row.role, content: row.content,
-                        position: Number(row.position), createdAt: Number(row.created_at),
-                        ...(includeToolEvents ? { events: row.events_json ? safeParse(row.events_json) : undefined } : {}), })), hasMore: rows.length > limit };
+                return { messages: page.map(row => toHistoryMessage(row, { includeToolEvents })), hasMore: rows.length > limit };
             },
         },
         async list() {