@jini-ai/chat 0.3.10 → 0.5.0

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

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

@@ -0,0 +1,49 @@
+/**
+ * @module store/sqlite/schema
+ *
+ * Canonical unchanged DDL for ai_chats and ai_chat_messages. Hosts own their database,
+ * migration ledger and connection configuration. A host with migrations retains its frozen
+ * migration statements; a fresh fixture or host without a migrator may call the explicit helper.
+ * Store construction never invokes it, chooses a file, or sets connection-wide pragmas.
+ */
+import type { SqliteClient } from '@jini-ai/db/sqlite';
+/**
+ * The canonical chat-history schema.
+ *
+ * Notes on the parts that are easy to get wrong:
+ *
+ * - **`scope_id`** is the host's partition key (workspace/tenant/project). It is `NOT NULL` from
+ *   the first migration on purpose: adding it later is trivial, but *backfilling* it is not —
+ *   pre-existing rows carry no evidence of which partition they belonged to, so a late addition
+ *   forces a choice between deleting history and guessing.
+ * - **`owner_kind` + the CHECK pair** make "a guest row with a `user_id`" unrepresentable rather
+ *   than merely discouraged.
+ * - **`owner_id`** holds a user id for `user`, and a *hash* of the session key for `guest`. The
+ *   raw token never reaches this table.
+ * - **`title_source`** exists so an agent-generated title cannot clobber a manual rename. That
+ *   rule is enforced in the store, but it needs a column to be enforceable at all.
+ * - **`position`** orders messages, not `created_at`: two inserts inside the same millisecond
+ *   are ordinary under concurrent writers, and a tie there corrupts replay order permanently.
+ *   `UNIQUE (conversation_id, position)` turns a position-assignment bug into a loud constraint
+ *   violation instead of a silently scrambled transcript.
+ * - **`expires_at NULL`** means "never expires". The retention sweep filters on
+ *   `expires_at IS NOT NULL`, so authenticated history is out of its reach by construction, not
+ *   by a predicate that could drift.
+ */
+export declare const CHAT_HISTORY_DDL = "\nCREATE TABLE IF NOT EXISTS ai_chats (\n  id            TEXT PRIMARY KEY,\n  scope_id      TEXT NOT NULL,\n  owner_kind    TEXT NOT NULL CHECK (owner_kind IN ('user','guest')),\n  owner_id      TEXT NOT NULL,\n  title         TEXT,\n  title_source  TEXT NOT NULL DEFAULT 'fallback'\n                CHECK (title_source IN ('fallback','generated','manual')),\n  created_at    INTEGER NOT NULL,\n  updated_at    INTEGER NOT NULL,\n  expires_at    INTEGER\n);\n\nCREATE INDEX IF NOT EXISTS idx_ai_chats_owner\n  ON ai_chats(scope_id, owner_kind, owner_id, updated_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_ai_chats_expiry\n  ON ai_chats(expires_at) WHERE expires_at IS NOT NULL;\n\nCREATE TABLE IF NOT EXISTS ai_chat_messages (\n  id              TEXT PRIMARY KEY,\n  conversation_id TEXT NOT NULL REFERENCES ai_chats(id) ON DELETE CASCADE,\n  role            TEXT NOT NULL CHECK (role IN ('user','assistant')),\n  content         TEXT NOT NULL,\n  agent_id        TEXT,\n  agent_name      TEXT,\n  events_json     TEXT,\n  attachments_json TEXT,\n  run_id          TEXT,\n  run_status      TEXT,\n  position        INTEGER NOT NULL,\n  created_at      INTEGER NOT NULL,\n  started_at      INTEGER,\n  ended_at        INTEGER,\n  UNIQUE (conversation_id, position)\n);\n\nCREATE INDEX IF NOT EXISTS idx_ai_chat_messages_order\n  ON ai_chat_messages(conversation_id, position);\n";
+/**
+ * Creates the chat-history tables in the given database if they are absent.
+ *
+ * Idempotent, matching `ensureToolCatalogTables`'s convention. For a host whose database is
+ * managed by its own migration system, prefer copying {@link CHAT_HISTORY_DDL} into a numbered
+ * migration instead — see this module's header for why two migrators over one file is a hazard.
+ *
+ * The caller is responsible for `PRAGMA foreign_keys = ON`; without it the `ON DELETE CASCADE`
+ * above is silently inert and deleting a conversation orphans its messages. This function does
+ * not set it, because pragmas are connection-wide and a library has no business reconfiguring a
+ * handle it was merely lent.
+ */
+export declare function ensureChatHistoryTables({ db }: {
+    db: Pick<SqliteClient, 'exec'>;
+}): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/store/sqlite/schema.js

@@ -0,0 +1,80 @@
+/**
+ * The canonical chat-history schema.
+ *
+ * Notes on the parts that are easy to get wrong:
+ *
+ * - **`scope_id`** is the host's partition key (workspace/tenant/project). It is `NOT NULL` from
+ *   the first migration on purpose: adding it later is trivial, but *backfilling* it is not —
+ *   pre-existing rows carry no evidence of which partition they belonged to, so a late addition
+ *   forces a choice between deleting history and guessing.
+ * - **`owner_kind` + the CHECK pair** make "a guest row with a `user_id`" unrepresentable rather
+ *   than merely discouraged.
+ * - **`owner_id`** holds a user id for `user`, and a *hash* of the session key for `guest`. The
+ *   raw token never reaches this table.
+ * - **`title_source`** exists so an agent-generated title cannot clobber a manual rename. That
+ *   rule is enforced in the store, but it needs a column to be enforceable at all.
+ * - **`position`** orders messages, not `created_at`: two inserts inside the same millisecond
+ *   are ordinary under concurrent writers, and a tie there corrupts replay order permanently.
+ *   `UNIQUE (conversation_id, position)` turns a position-assignment bug into a loud constraint
+ *   violation instead of a silently scrambled transcript.
+ * - **`expires_at NULL`** means "never expires". The retention sweep filters on
+ *   `expires_at IS NOT NULL`, so authenticated history is out of its reach by construction, not
+ *   by a predicate that could drift.
+ */
+export const CHAT_HISTORY_DDL = `
+CREATE TABLE IF NOT EXISTS ai_chats (
+  id            TEXT PRIMARY KEY,
+  scope_id      TEXT NOT NULL,
+  owner_kind    TEXT NOT NULL CHECK (owner_kind IN ('user','guest')),
+  owner_id      TEXT NOT NULL,
+  title         TEXT,
+  title_source  TEXT NOT NULL DEFAULT 'fallback'
+                CHECK (title_source IN ('fallback','generated','manual')),
+  created_at    INTEGER NOT NULL,
+  updated_at    INTEGER NOT NULL,
+  expires_at    INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_ai_chats_owner
+  ON ai_chats(scope_id, owner_kind, owner_id, updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_ai_chats_expiry
+  ON ai_chats(expires_at) WHERE expires_at IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS ai_chat_messages (
+  id              TEXT PRIMARY KEY,
+  conversation_id TEXT NOT NULL REFERENCES ai_chats(id) ON DELETE CASCADE,
+  role            TEXT NOT NULL CHECK (role IN ('user','assistant')),
+  content         TEXT NOT NULL,
+  agent_id        TEXT,
+  agent_name      TEXT,
+  events_json     TEXT,
+  attachments_json TEXT,
+  run_id          TEXT,
+  run_status      TEXT,
+  position        INTEGER NOT NULL,
+  created_at      INTEGER NOT NULL,
+  started_at      INTEGER,
+  ended_at        INTEGER,
+  UNIQUE (conversation_id, position)
+);
+
+CREATE INDEX IF NOT EXISTS idx_ai_chat_messages_order
+  ON ai_chat_messages(conversation_id, position);
+`;
+/**
+ * Creates the chat-history tables in the given database if they are absent.
+ *
+ * Idempotent, matching `ensureToolCatalogTables`'s convention. For a host whose database is
+ * managed by its own migration system, prefer copying {@link CHAT_HISTORY_DDL} into a numbered
+ * migration instead — see this module's header for why two migrators over one file is a hazard.
+ *
+ * The caller is responsible for `PRAGMA foreign_keys = ON`; without it the `ON DELETE CASCADE`
+ * above is silently inert and deleting a conversation orphans its messages. This function does
+ * not set it, because pragmas are connection-wide and a library has no business reconfiguring a
+ * handle it was merely lent.
+ */
+export function ensureChatHistoryTables({ db }) {
+    db.exec(CHAT_HISTORY_DDL);
+}
+//# sourceMappingURL=schema.js.map