@jini-ai/chat 0.3.11 → 0.5.0

package/dist/store/postgres/index.js

@@ -0,0 +1,17 @@
+import { createSqlChatStore } from '../sql/store.js';
+import { createSqlChatMaintenance } from '../sql/maintenance.js';
+import { validateKernel } from '../sql/boundary.js';
+/** Borrow an existing kernel, with no configuration, migration or connection lifecycle effects.
+ * @example createPostgresChatStore({ kernel, scope }, { clock: { nowMs: () => 42 } })
+ * @throws ChatStoreError invalid-input for a mismatched dialect/transport or owner scope.
+ */
+export function createPostgresChatStore(required, optional = {}) {
+    validateKernel({ kernel: required.kernel, transports: ['node-postgres'], dialect: 'postgres' });
+    return createSqlChatStore(required, optional);
+}
+/** Privileged bounded expiry maintenance; never hand this collaborator to request handlers. */
+export function createPostgresChatMaintenance(required) {
+    validateKernel({ kernel: required.kernel, transports: ['node-postgres'], dialect: 'postgres' });
+    return createSqlChatMaintenance(required);
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,28 @@
+/** SQL boundary validation and opaque driver error translation. */
+import type { StorageKernel, StorageTransport } from '@jini-ai/db/kernel';
+import type { Kysely } from 'kysely';
+import type { ChatDatabase } from './tables.js';
+import type { ChatOwnerScope } from '../ports.js';
+/** Construction is validation-only: never query, migrate, reconfigure, open or close a kernel. */
+export declare function validateKernel<DB>({ kernel, transports, dialect }: {
+    kernel: StorageKernel<DB>;
+    transports: readonly StorageTransport[];
+    dialect: 'sqlite' | 'postgres';
+}): void;
+/** Copy primitive identity fields so subsequent caller mutation cannot rebind the store. */
+export declare function copyScope({ scope }: {
+    scope: ChatOwnerScope;
+}): ChatOwnerScope;
+/** Preserve structured errors and causes; no driver details appear in public messages. */
+export declare function atStoreBoundary<T>({ operation }: {
+    operation: () => Promise<T>;
+}): Promise<T>;
+/** The single audited table-subset projection. Required table types are proven by DB's bound;
+ * host extra tables and all transaction/locking effects stay on the original kernel object.
+ * Kysely's invariant DB parameter requires this one erasure; it never bridges driver/version copies.
+ */
+export declare function runChatQuery<DB extends ChatDatabase, T>({ kernel, body }: {
+    kernel: StorageKernel<DB>;
+    body: (db: Kysely<ChatDatabase>) => T | Promise<T>;
+}): Promise<T>;
+//# sourceMappingURL=boundary.d.ts.map

package/dist/store/sql/boundary.js

@@ -0,0 +1,32 @@
+import { ChatStoreError } from '../errors.js';
+/** Construction is validation-only: never query, migrate, reconfigure, open or close a kernel. */
+export function validateKernel({ kernel, transports, dialect }) {
+    if (!kernel || kernel.dialect !== dialect || !transports.includes(kernel.transport))
+        throw new ChatStoreError({ code: 'invalid-input' });
+}
+/** Copy primitive identity fields so subsequent caller mutation cannot rebind the store. */
+export function copyScope({ scope }) {
+    if (!scope || typeof scope.scopeId !== 'string' || !scope.scopeId || typeof scope.ownerId !== 'string' || !scope.ownerId || !['user', 'guest'].includes(scope.ownerKind)) {
+        throw new ChatStoreError({ code: 'invalid-input' });
+    }
+    return { scopeId: scope.scopeId, ownerKind: scope.ownerKind, ownerId: scope.ownerId };
+}
+/** Preserve structured errors and causes; no driver details appear in public messages. */
+export async function atStoreBoundary({ operation }) {
+    try {
+        return await operation();
+    }
+    catch (cause) {
+        if (cause instanceof ChatStoreError)
+            throw cause;
+        throw new ChatStoreError({ code: 'unavailable' }, { cause });
+    }
+}
+/** The single audited table-subset projection. Required table types are proven by DB's bound;
+ * host extra tables and all transaction/locking effects stay on the original kernel object.
+ * Kysely's invariant DB parameter requires this one erasure; it never bridges driver/version copies.
+ */
+export function runChatQuery({ kernel, body }) {
+    return kernel.run(db => body(db));
+}
+//# sourceMappingURL=boundary.js.map

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

@@ -0,0 +1,24 @@
+/** Versioned keyset continuations. Encoding grants no authority; all queries remain scoped. */
+import type { ChatOwnerScope, ChatPageOptions } from '../ports.js';
+type ReadKind = 'conversations' | 'messages';
+export type Anchor = readonly [number, string];
+/** Reject bad limits before accessing any storage. */
+export declare function pageLimit({ options }: {
+    options: ChatPageOptions | undefined;
+}): number;
+/** UTF-8/base64url preserves arbitrary opaque IDs; cursors represent live views, not snapshots. */
+export declare function encodeCursor({ kind, scope, conversation, anchor }: {
+    kind: ReadKind;
+    scope: ChatOwnerScope;
+    conversation: string | null;
+    anchor: Anchor;
+}): string;
+/** Validate version, exact structure, scope and read bindings before a query can run. */
+export declare function decodeCursor({ cursor, kind, scope, conversation }: {
+    cursor: string | undefined;
+    kind: ReadKind;
+    scope: ChatOwnerScope;
+    conversation: string | null;
+}): Anchor | undefined;
+export {};
+//# sourceMappingURL=cursor.d.ts.map

package/dist/store/sql/cursor.js

@@ -0,0 +1,49 @@
+import { ChatStoreError } from '../errors.js';
+/** Reject bad limits before accessing any storage. */
+export function pageLimit({ options }) {
+    const limit = options?.limit === undefined ? 50 : options.limit;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200)
+        throw new ChatStoreError({ code: 'invalid-input' });
+    return limit;
+}
+/** Scope binding uses the host's already-hashed guest ID, never a bearer token. */
+function ownerTuple(scope) {
+    return [scope.scopeId, scope.ownerKind, scope.ownerId];
+}
+/** UTF-8/base64url preserves arbitrary opaque IDs; cursors represent live views, not snapshots. */
+export function encodeCursor({ kind, scope, conversation, anchor }) {
+    const bytes = new TextEncoder().encode(JSON.stringify([1, kind, ownerTuple(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;
+    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));
+    }
+    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' });
+    }
+    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' });
+    }
+    if (kind === 'messages' && (!Number.isSafeInteger(anchor[0]) || anchor[0] < 0))
+        throw new ChatStoreError({ code: 'invalid-cursor' });
+    return [anchor[0], anchor[1]];
+}
+//# sourceMappingURL=cursor.js.map

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

@@ -0,0 +1,9 @@
+/** Privileged bounded retention, kept separate from every request-scoped store. */
+import type { StorageKernel } from '@jini-ai/db/kernel';
+import type { ChatDatabase } from './tables.js';
+import type { ChatHistoryMaintenance } from '../ports.js';
+/** Delete at most 500 expired parents; the host schema/foreign-key policy supplies cascades. */
+export declare function createSqlChatMaintenance<DB extends ChatDatabase>({ kernel }: {
+    kernel: StorageKernel<DB>;
+}): ChatHistoryMaintenance;
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/store/sql/maintenance.js

@@ -0,0 +1,16 @@
+import { ChatStoreError } from '../errors.js';
+import { atStoreBoundary, runChatQuery } from './boundary.js';
+/** Delete at most 500 expired parents; the host schema/foreign-key policy supplies cascades. */
+export function createSqlChatMaintenance({ kernel }) {
+    return {
+        sweepExpired: ({ now }, { limit = 500 } = {}) => atStoreBoundary({ operation: async () => {
+                // Drain a backlog in chunks: an unbounded delete can hold the write lock until concurrent
+                // inserts exhaust their busy timeout. NULL expiry remains structurally outside the sweep.
+                if (!Number.isFinite(now) || !Number.isInteger(limit) || limit < 1 || limit > 500)
+                    throw new ChatStoreError({ code: 'invalid-input' });
+                const result = await runChatQuery({ kernel: kernel, body: db => db.deleteFrom('ai_chats').where('id', 'in', db.selectFrom('ai_chats').select('id').where('expires_at', 'is not', null).where('expires_at', '<=', now).limit(limit)).executeTakeFirst() });
+                return Number(result.numDeletedRows);
+            } }),
+    };
+}
+//# sourceMappingURL=maintenance.js.map

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

@@ -0,0 +1,22 @@
+import { type Clock } from '@jini-ai/core/primitives';
+import { type StorageKernel } from '@jini-ai/db/kernel';
+import type { ChatStore, ChatOwnerScope } from '../ports.js';
+import type { ChatDatabase } from './tables.js';
+/**
+ * Returns a {@link ChatHistoryStore} that can only ever see `scope`'s own conversations.
+ *
+ * @param kernel the borrowed kernel. Nothing here opens, closes or configures a database; SQLite's
+ *   `ON DELETE CASCADE` needs `foreign_keys = ON`, which the host must enable.
+ * @param scope the isolation predicate, resolved from the host's authentication. For a guest,
+ *   `ownerId` must already be a hash of the session key (`tenant-scope.ts`).
+ * @param optional Optional core Clock for deterministic host/tests; defaults to system wall time.
+ * @complexity each method is one to four indexed statements; `list` is O(owned conversations),
+ *   `messages` O(messages in the conversation).
+ */
+export declare function createSqlChatStore<DB extends ChatDatabase>({ kernel, scope: inputScope }: {
+    kernel: StorageKernel<DB>;
+    scope: ChatOwnerScope;
+}, { clock }?: {
+    clock?: Clock;
+}): ChatStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/store/sql/store.js

@@ -0,0 +1,340 @@
+/** One SQL query body upstreamed from the existing host adapter; no resource/schema ownership. */
+// Legacy project/conversation CRUD trusts access to a local database file; this owner-bound store
+// serves shared databases instead. Choose by trust model: borrowing a handle must not grant access
+// to every tenant, and this adapter neither chooses that handle's file nor owns its lifetime.
+/**
+ * Every read/write uses the authenticated (scope_id, owner_kind, owner_id) tuple; store construction
+ * must not turn a shared database into access to other owners' conversations. Append reads and
+ * assigns position in one transaction under the conversation lock: PostgreSQL READ COMMITTED alone
+ * cannot serialize two appends as SQLite BEGIN IMMEDIATE does. The unique conversation/position
+ * constraint remains the backstop, and nested appends join the host's existing transaction.
+ */
+import { sql } from 'kysely';
+import { createSystemClock } from '@jini-ai/core/primitives';
+import { isUniqueViolation } from '@jini-ai/db/kernel';
+import { ChatStoreError } from '../errors.js';
+import { copyScope, atStoreBoundary, runChatQuery } from './boundary.js';
+import { pageLimit, decodeCursor, encodeCursor } from './cursor.js';
+/** UTF-8 byte ordinal ordering, identical on SQLite BINARY and PostgreSQL C collation. */
+function ordinalId(dialect, column) {
+    return dialect === 'sqlite' ? sql `${sql.ref(column)} collate BINARY` : sql `${sql.ref(column)} collate "C"`;
+}
+/** The lock every position-assigning append to one conversation takes. */
+function conversationLockKey(conversationId) {
+    return `chat-conversation:${conversationId}`;
+}
+function toConversation(row) {
+    return {
+        id: row.id,
+        title: row.title ?? null,
+        titleSource: (row.title_source ?? "fallback"),
+        messageCount: Number(row.message_count ?? 0),
+        createdAt: Number(row.created_at),
+        updatedAt: Number(row.updated_at),
+        ...(row.expires_at === null ? {} : { expiresAt: Number(row.expires_at) }),
+    };
+}
+/**
+ * A malformed JSON column yields `undefined` rather than throwing: one half-written `events_json`
+ * must not make the whole conversation unreadable (same rule as Jini's store).
+ */
+function safeParse(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return 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
+// and let the daemon persist authoritative stream/terminal state, then extend storage for it.
+// 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;
+    return {
+        id: row.id, role: row.role, content: row.content,
+        ...(row.agent_id ? { agentId: row.agent_id } : {}),
+        ...(row.agent_name ? { agentName: row.agent_name } : {}),
+        ...(events === undefined ? {} : { events }),
+        ...(attachments === undefined ? {} : { attachments }),
+        ...(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) }),
+    };
+}
+/**
+ * Returns a {@link ChatHistoryStore} that can only ever see `scope`'s own conversations.
+ *
+ * @param kernel the borrowed kernel. Nothing here opens, closes or configures a database; SQLite's
+ *   `ON DELETE CASCADE` needs `foreign_keys = ON`, which the host must enable.
+ * @param scope the isolation predicate, resolved from the host's authentication. For a guest,
+ *   `ownerId` must already be a hash of the session key (`tenant-scope.ts`).
+ * @param optional Optional core Clock for deterministic host/tests; defaults to system wall time.
+ * @complexity each method is one to four indexed statements; `list` is O(owned conversations),
+ *   `messages` O(messages in the conversation).
+ */
+export function createSqlChatStore({ kernel, scope: inputScope }, { clock = createSystemClock() } = {}) {
+    const scope = copyScope({ scope: inputScope });
+    const { scopeId, ownerKind, ownerId } = scope;
+    // The single subset boundary: DB must contain both required table definitions. Extra host tables
+    // stay on the exact borrowed kernel; its transaction context is never projected or recreated.
+    const run = (body) => runChatQuery({ kernel: kernel, body: body });
+    /** This scope's conversations, projected as {@link ConversationRow}s with their message count. */
+    function ownedConversations(db) {
+        return db
+            .selectFrom("ai_chats as c")
+            .select((eb) => [
+            "c.id",
+            "c.title",
+            "c.title_source",
+            "c.created_at",
+            "c.updated_at",
+            "c.expires_at",
+            eb
+                .selectFrom("ai_chat_messages as m")
+                .select((sb) => sb.fn.countAll().as("n"))
+                .whereRef("m.conversation_id", "=", "c.id")
+                .as("message_count"),
+        ])
+            .where("c.scope_id", "=", scopeId)
+            .where("c.owner_kind", "=", ownerKind)
+            .where("c.owner_id", "=", ownerId);
+    }
+    /** One owner-filtered indexed lookup; missing and foreign IDs both return null. */
+    async function get({ id }, _optional = {}) {
+        const row = await run((db) => ownedConversations(db).where("c.id", "=", id).executeTakeFirst());
+        return row ? toConversation(row) : null;
+    }
+    /** One scoped projection for all message reads, including the row returned by an upsert. */
+    function ownedMessages(db, conversationId) {
+        return db
+            .selectFrom("ai_chat_messages as m")
+            .innerJoin("ai_chats as c", "c.id", "m.conversation_id")
+            .select([
+            "m.id",
+            "m.role",
+            "m.content",
+            "m.agent_id",
+            "m.agent_name",
+            "m.events_json",
+            "m.attachments_json",
+            "m.run_id",
+            "m.run_status",
+            "m.created_at",
+            "m.started_at",
+            "m.ended_at",
+        ])
+            .where("m.conversation_id", "=", conversationId)
+            .where("c.scope_id", "=", scopeId)
+            .where("c.owner_kind", "=", ownerKind)
+            .where("c.owner_id", "=", ownerId);
+    }
+    /** Read owned messages in persisted position order; foreign IDs produce no rows. */
+    async function messages({ conversationId }, _optional = {}) {
+        const rows = await run(db => ownedMessages(db, conversationId).orderBy('m.position').execute());
+        return rows.map(toMessage);
+    }
+    /** Writes and projects one message inside the borrowed transaction; null for absent/foreign IDs. */
+    function writeMessage(conversationId, m) {
+        return kernel.transaction(async () => {
+            await kernel.lockKey(conversationLockKey(conversationId));
+            const owned = await run((db) => db
+                .selectFrom("ai_chats")
+                .select("id")
+                .where("id", "=", conversationId)
+                .where("scope_id", "=", scopeId)
+                .where("owner_kind", "=", ownerKind)
+                .where("owner_id", "=", ownerId)
+                .executeTakeFirst());
+            if (!owned)
+                return null;
+            const existing = await run((db) => db
+                .selectFrom("ai_chat_messages")
+                .select("position")
+                .where("id", "=", m.id)
+                .where("conversation_id", "=", conversationId)
+                .executeTakeFirst());
+            const position = existing ? Number(existing.position) : await nextPosition(conversationId);
+            // The conflict target is `id`, the GLOBAL key: the `where` keeps an id that already lives in
+            // another conversation from updating THAT row (the contract's "colliding id to its OWN chat" case).
+            await run((db) => db
+                .insertInto("ai_chat_messages")
+                .values({
+                id: m.id,
+                conversation_id: conversationId,
+                role: m.role,
+                content: m.content,
+                agent_id: m.agentId ?? null,
+                agent_name: m.agentName ?? null,
+                events_json: m.events ? JSON.stringify(m.events) : null,
+                attachments_json: m.attachments ? JSON.stringify(m.attachments) : null,
+                run_id: m.runId ?? null,
+                run_status: m.runStatus ?? null,
+                position,
+                created_at: m.createdAt ?? clock.nowMs(),
+                started_at: m.startedAt ?? null,
+                ended_at: m.endedAt ?? null,
+            })
+                .onConflict((oc) => oc
+                .column("id")
+                .doUpdateSet((eb) => ({
+                content: eb.ref("excluded.content"),
+                events_json: eb.ref("excluded.events_json"),
+                attachments_json: eb.ref("excluded.attachments_json"),
+                run_id: eb.ref("excluded.run_id"),
+                run_status: eb.ref("excluded.run_status"),
+                started_at: eb.ref("excluded.started_at"),
+                ended_at: eb.ref("excluded.ended_at"),
+            }))
+                .where((eb) => eb("ai_chat_messages.conversation_id", "=", eb.ref("excluded.conversation_id"))))
+                .execute());
+            // A new message is activity: the list orders by `updated_at`.
+            await run((db) => db.updateTable("ai_chats").set({ updated_at: clock.nowMs() }).where("id", "=", conversationId).execute());
+            // Re-read only the written row, while still in the same transaction and conversation lock.
+            const saved = await run(db => ownedMessages(db, conversationId).where('m.id', '=', m.id).executeTakeFirst());
+            return saved ? toMessage(saved) : null;
+        });
+    }
+    async function nextPosition(conversationId) {
+        const row = await run((db) => db
+            .selectFrom("ai_chat_messages")
+            .select((eb) => eb.fn.max("position").as("max"))
+            .where("conversation_id", "=", conversationId)
+            .executeTakeFirst());
+        return row?.max === null || row?.max === undefined ? 0 : Number(row.max) + 1;
+    }
+    const store = {
+        async list() {
+            const rows = await run((db) => ownedConversations(db).orderBy("c.updated_at", "desc").execute());
+            return rows.map((row) => toConversation(row));
+        },
+        get,
+        async create(input, _optional = {}) {
+            const ts = clock.nowMs();
+            try {
+                await run((db) => db
+                    .insertInto("ai_chats")
+                    .values({
+                    id: input.id,
+                    scope_id: scopeId,
+                    owner_kind: ownerKind,
+                    owner_id: ownerId,
+                    title: input.title ?? null,
+                    title_source: input.titleSource ?? "fallback",
+                    created_at: ts,
+                    updated_at: ts,
+                    expires_at: input.expiresAt ?? null,
+                })
+                    .execute());
+            }
+            catch (cause) {
+                if (isUniqueViolation(cause))
+                    throw new ChatStoreError({ code: 'conflict' }, { cause });
+                throw cause;
+            }
+            const created = await get({ id: input.id });
+            // Unreachable: the insert used this exact scope. Asserted so a future change to either
+            // statement fails loudly instead of returning a malformed conversation.
+            if (!created)
+                throw new Error(`ai_chats: created conversation ${input.id} was not readable in its own scope`);
+            return created;
+        },
+        async rename({ id, title }, { source = "manual" } = {}) {
+            // A generated title never overwrites a typed one: in the WHERE clause, so a concurrent
+            // rename cannot slip between a read and this write.
+            await run((db) => db
+                .updateTable("ai_chats")
+                .set({ title, title_source: source, updated_at: clock.nowMs() })
+                .where("id", "=", id)
+                .where("scope_id", "=", scopeId)
+                .where("owner_kind", "=", ownerKind)
+                .where("owner_id", "=", ownerId)
+                .$if(source === "generated", (qb) => qb.where("title_source", "<>", "manual"))
+                .execute());
+            return get({ id });
+        },
+        async touch({ id }, options = {}) {
+            const ts = clock.nowMs();
+            await run((db) => db
+                .updateTable("ai_chats")
+                .set(options?.expiresAt === undefined ? { updated_at: ts } : { updated_at: ts, expires_at: options.expiresAt })
+                .where("id", "=", id)
+                .where("scope_id", "=", scopeId)
+                .where("owner_kind", "=", ownerKind)
+                .where("owner_id", "=", ownerId)
+                .execute());
+        },
+        async delete({ id }, _optional = {}) {
+            // Messages, agent sessions and tool approvals go with it through `ON DELETE CASCADE`.
+            await run((db) => db
+                .deleteFrom("ai_chats")
+                .where("id", "=", id)
+                .where("scope_id", "=", scopeId)
+                .where("owner_kind", "=", ownerKind)
+                .where("owner_id", "=", ownerId)
+                .execute());
+        },
+        messages,
+        async appendMessage({ conversationId, message }, _optional = {}) {
+            return writeMessage(conversationId, message);
+        },
+        async pageConversations(_required, options = {}) {
+            const limit = pageLimit({ options: options });
+            const anchor = decodeCursor({ cursor: options?.cursor, kind: 'conversations', scope: scope, conversation: null });
+            const id = ordinalId(kernel.dialect, 'c.id');
+            const rows = await run(db => {
+                let query = ownedConversations(db);
+                if (anchor)
+                    query = query.where(eb => eb.or([
+                        eb('c.updated_at', '<', anchor[0]),
+                        eb.and([eb('c.updated_at', '=', anchor[0]), eb(id, '>', anchor[1])]),
+                    ]));
+                return query.orderBy('c.updated_at', 'desc').orderBy(id, 'asc').limit(limit + 1).execute();
+            });
+            const items = rows.slice(0, limit).map(row => toConversation(row));
+            const last = items.at(-1);
+            return { items, ...(rows.length > limit && last ? {
+                    nextCursor: encodeCursor({ kind: 'conversations', scope: scope, conversation: null, anchor: [last.updatedAt, last.id] }),
+                } : {}) };
+        },
+        async pageMessages(input, options = {}) {
+            const limit = pageLimit({ options: options });
+            const anchor = decodeCursor({ cursor: options?.cursor, kind: 'messages', scope: scope, conversation: input.conversationId });
+            const id = ordinalId(kernel.dialect, 'm.id');
+            // One join, at most limit+1 rows, including the ownership check; no parent pre-read.
+            const rows = await run(db => {
+                let query = ownedMessages(db, input.conversationId).select('m.position');
+                if (anchor)
+                    query = query.where(eb => eb.or([
+                        eb('m.position', '>', anchor[0]),
+                        eb.and([eb('m.position', '=', anchor[0]), eb(id, '>', anchor[1])]),
+                    ]));
+                return query.orderBy('m.position', 'asc').orderBy(id, 'asc').limit(limit + 1).execute();
+            });
+            const page = rows.slice(0, limit), last = page.at(-1);
+            return { items: page.map(toMessage), ...(rows.length > limit && last ? {
+                    nextCursor: encodeCursor({ kind: 'messages', scope: scope, conversation: input.conversationId, anchor: [Number(last.position), last.id] }),
+                } : {}) };
+        },
+    };
+    return {
+        list: () => atStoreBoundary({ operation: () => store.list() }),
+        get: (required, optional = {}) => atStoreBoundary({ operation: () => store.get(required, optional) }),
+        create: (required, optional = {}) => atStoreBoundary({ operation: () => store.create(required, optional) }),
+        rename: (required, optional = {}) => atStoreBoundary({ operation: () => store.rename(required, optional) }),
+        touch: (required, optional = {}) => atStoreBoundary({ operation: () => store.touch(required, optional) }),
+        delete: (required, optional = {}) => atStoreBoundary({ operation: () => store.delete(required, optional) }),
+        messages: (required, optional = {}) => atStoreBoundary({ operation: () => store.messages(required, optional) }),
+        appendMessage: (required, optional = {}) => atStoreBoundary({ operation: () => store.appendMessage(required, optional) }),
+        pageConversations: (required, optional = {}) => atStoreBoundary({ operation: () => store.pageConversations(required, optional) }),
+        pageMessages: (required, optional = {}) => atStoreBoundary({ operation: () => store.pageMessages(required, optional) }),
+    };
+}
+//# sourceMappingURL=store.js.map

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

@@ -0,0 +1,34 @@
+/** Existing ai_* schema, owned and migrated by the host. No schema creation on construction. */
+import type { Generated } from 'kysely';
+export type AiChatsTable = {
+    id: string;
+    scope_id: string;
+    owner_kind: string;
+    owner_id: string;
+    title: string | null;
+    title_source: Generated<string>;
+    created_at: number;
+    updated_at: number;
+    expires_at: number | null;
+};
+export type AiChatMessagesTable = {
+    id: string;
+    conversation_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;
+    position: number;
+    created_at: number;
+    started_at: number | null;
+    ended_at: number | null;
+};
+export type ChatDatabase = {
+    ai_chats: AiChatsTable;
+    ai_chat_messages: AiChatMessagesTable;
+};
+//# sourceMappingURL=tables.d.ts.map

package/dist/store/sql/tables.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tables.js.map

package/dist/store/sqlite/index.d.ts

@@ -0,0 +1,36 @@
+/** Sqlite transcript adapter. The host owns the opened, migrated kernel and its lifetime. */
+import type { Clock } from '@jini-ai/core/primitives';
+import type { StorageKernel } from '@jini-ai/db/kernel';
+import type { ChatDatabase } from '../sql/tables.js';
+import type { ChatOwnerScope, ChatStore, ChatHistoryMaintenance } from '../ports.js';
+export type { ChatDatabase, AiChatsTable, AiChatMessagesTable } from '../sql/tables.js';
+/** Borrow an existing kernel, with no configuration, migration or connection lifecycle effects.
+ * @example createSqliteChatStore({ kernel, scope }, { clock: { nowMs: () => 42 } })
+ * @throws ChatStoreError invalid-input for a mismatched dialect/transport or owner scope.
+ */
+export declare function createSqliteChatStore<DB extends ChatDatabase>(required: {
+    kernel: StorageKernel<DB>;
+    scope: ChatOwnerScope;
+}, optional?: {
+    clock?: Clock;
+}): ChatStore;
+/** Privileged bounded expiry maintenance; never hand this collaborator to request handlers. */
+export declare function createSqliteChatMaintenance<DB extends ChatDatabase>(required: {
+    kernel: StorageKernel<DB>;
+}): ChatHistoryMaintenance;
+import { type SqliteConnectionSource } from '@jini-ai/db/kernel/sqlite';
+export { CHAT_HISTORY_DDL, ensureChatHistoryTables } from './schema.js';
+/** Compatibility wrapper over db's memoized kernel; joins the exact raw-handle kernel context.
+ * @example createChatHistoryStore({ db, scope }, { clock: { nowMs: () => 42 } })
+ */
+export declare function createChatHistoryStore({ db, scope }: {
+    db: SqliteConnectionSource;
+    scope: ChatOwnerScope;
+}, optional?: {
+    clock?: Clock;
+}): ChatStore;
+/** Compatibility retention wrapper; the caller still owns the handle and its configuration. */
+export declare function createChatHistoryMaintenance({ db }: {
+    db: SqliteConnectionSource;
+}): ChatHistoryMaintenance;
+//# sourceMappingURL=index.d.ts.map

package/dist/store/sqlite/index.js

@@ -0,0 +1,29 @@
+import { createSqlChatStore } from '../sql/store.js';
+import { createSqlChatMaintenance } from '../sql/maintenance.js';
+import { validateKernel } from '../sql/boundary.js';
+/** Borrow an existing kernel, with no configuration, migration or connection lifecycle effects.
+ * @example createSqliteChatStore({ kernel, scope }, { clock: { nowMs: () => 42 } })
+ * @throws ChatStoreError invalid-input for a mismatched dialect/transport or owner scope.
+ */
+export function createSqliteChatStore(required, optional = {}) {
+    validateKernel({ kernel: required.kernel, transports: ['better-sqlite3'], dialect: 'sqlite' });
+    return createSqlChatStore(required, optional);
+}
+/** Privileged bounded expiry maintenance; never hand this collaborator to request handlers. */
+export function createSqliteChatMaintenance(required) {
+    validateKernel({ kernel: required.kernel, transports: ['better-sqlite3'], dialect: 'sqlite' });
+    return createSqlChatMaintenance(required);
+}
+import { sqliteKernel } from '@jini-ai/db/kernel/sqlite';
+export { CHAT_HISTORY_DDL, ensureChatHistoryTables } from './schema.js';
+/** Compatibility wrapper over db's memoized kernel; joins the exact raw-handle kernel context.
+ * @example createChatHistoryStore({ db, scope }, { clock: { nowMs: () => 42 } })
+ */
+export function createChatHistoryStore({ db, scope }, optional = {}) {
+    return createSqliteChatStore({ kernel: sqliteKernel(db), scope }, optional);
+}
+/** Compatibility retention wrapper; the caller still owns the handle and its configuration. */
+export function createChatHistoryMaintenance({ db }) {
+    return createSqliteChatMaintenance({ kernel: sqliteKernel(db) });
+}
+//# sourceMappingURL=index.js.map