@jini-ai/chat 0.3.11 → 0.5.0

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

@@ -0,0 +1,6 @@
+/** Sync legacy conversations/messages over a borrowed host handle. */
+export * from './conversations.js';
+export * from './messages.js';
+export { LEGACY_CHAT_DDL } from './schema.js';
+export type { ChatSessionMode } from '../index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/store/legacy/sqlite/index.js

@@ -0,0 +1,5 @@
+/** Sync legacy conversations/messages over a borrowed host handle. */
+export * from './conversations.js';
+export * from './messages.js';
+export { LEGACY_CHAT_DDL } from './schema.js';
+//# sourceMappingURL=index.js.map

package/dist/store/legacy/sqlite/messages.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @module db/messages/messages
+ * Chat message CRUD, streamed-event append, and telemetry finalization. Imports only the
+ * core/ kernel (SqliteDb, DbRow, ChatSessionMode, parseJsonOrUndef).
+ *
+ * NOTE (neutral port): drops six OD-product JSON columns with no generic engine equivalent —
+ * `comment_attachments_json` (the preview-comments/canvas-annotation feature, explicitly out of
+ * scope for this port), `produced_files_json` and `trace_object_files_json` (design-canvas file
+ * output tracking), `feedback_json` (Critique Theater's scoring feedback), `pre_turn_file_names_json`
+ * (design-canvas per-turn file context), and `applied_plugin_snapshot_json` (OD's plugin host). The
+ * already-ported `schema/migrate.ts` messages table was pre-trimmed to match; see that file and
+ * `source-map.md`'s Design Decisions for the same drop list.
+ */
+import type { SqliteDb } from '@jini-ai/db/sqlite';
+import type { DbRow } from '@jini-ai/db/core';
+import type { ChatSessionMode } from '../index.js';
+/**
+ * Returns all messages for a conversation in ascending position order, with JSON columns parsed.
+ * @param db - Open SQLite connection.
+ * @param conversationId - Conversation whose messages to fetch.
+ * @returns Normalized message objects ready for API serialization.
+ */
+export declare function listMessages({ db, conversationId }: {
+    db: SqliteDb;
+    conversationId: string;
+}): {
+    id: any;
+    role: any;
+    content: any;
+    agentId: any;
+    agentName: any;
+    runId: any;
+    runStatus: any;
+    lastRunEventId: any;
+    events: any;
+    attachments: any;
+    sessionMode: ChatSessionMode | undefined;
+    runContext: any;
+    createdAt: any;
+    startedAt: any;
+    endedAt: any;
+}[];
+/**
+ * Thrown by `upsertMessage` when the caller presents a message `id` together with a
+ * `conversationId` that does not match the conversation the row already belongs to (`id` is a
+ * global primary key, not scoped per-conversation, so this is the only signal available). Rather
+ * than silently updating the wrong conversation's message — or silently doing nothing — while
+ * still bumping the caller-supplied `conversationId`'s `updated_at`, this is a hard failure: it is
+ * always a caller/transport bug (a confused id, or a multi-tenant mixup) and never a legitimate
+ * state to paper over.
+ */
+export declare class MessageConversationMismatchError extends Error {
+    readonly messageId: string;
+    readonly actualConversationId: string;
+    readonly requestedConversationId: string;
+    constructor({ messageId, actualConversationId, requestedConversationId }: {
+        messageId: string;
+        actualConversationId: string;
+        requestedConversationId: string;
+    });
+}
+/**
+ * Inserts or updates a message row and bumps the parent conversation's `updated_at` for recency sorting.
+ * On insert, appends to the end of the conversation's position sequence.
+ * On update, preserves `telemetry_finalized_at` once set (one-way latch).
+ *
+ * The existence check, position calculation, insert-or-update, and conversation `updated_at` bump
+ * all run inside one `better-sqlite3` transaction (opened with `BEGIN IMMEDIATE` via `.immediate()`,
+ * not the default deferred `BEGIN`) so the whole read-then-write sequence is atomic: a concurrent
+ * connection's own `upsertMessage` call for the same conversation cannot read the pre-write
+ * `MAX(position)` while this one is still in flight and thereby compute the same next position —
+ * `BEGIN IMMEDIATE` acquires the write lock before this transaction's first read, so a concurrent
+ * writer blocks (or fails with `SQLITE_BUSY`, per its own busy-timeout policy) until this one
+ * commits, rather than interleaving.
+ *
+ * `id` is the messages table's global primary key (not scoped per-conversation), so a row can only
+ * ever belong to one conversation. If the caller-supplied `m.id` already exists under a different
+ * `conversationId`, this throws {@link MessageConversationMismatchError} instead of silently
+ * updating the wrong conversation's row (or the wrong conversation's `updated_at`).
+ *
+ * @param db - Open SQLite connection.
+ * @param conversationId - Owning conversation id.
+ * @param m - Message fields; JSON sub-fields are stringified automatically.
+ * @returns The normalized, re-fetched message row, or null if the row vanished between write and read.
+ * @throws {MessageConversationMismatchError} if `m.id` already exists under a different conversation.
+ */
+export declare function upsertMessage({ db, conversationId, m }: {
+    db: SqliteDb;
+    conversationId: string;
+    m: DbRow;
+}): {
+    id: any;
+    role: any;
+    content: any;
+    agentId: any;
+    agentName: any;
+    runId: any;
+    runStatus: any;
+    lastRunEventId: any;
+    events: any;
+    attachments: any;
+    sessionMode: ChatSessionMode | undefined;
+    runContext: any;
+    createdAt: any;
+    startedAt: any;
+    endedAt: any;
+} | null;
+/**
+ * Reads whether telemetry has been finalized for a message without loading the full row.
+ * Used to decide whether to enqueue a finalization job.
+ * @returns `{ exists: false }` when the message is not found; otherwise `{ exists: true, finalizedAt }`.
+ */
+export declare function getMessageTelemetryFinalizationState({ db, messageId }: {
+    db: SqliteDb;
+    messageId: string;
+}): {
+    exists: boolean;
+    finalizedAt: number | null;
+};
+/**
+ * Appends a `{ kind: 'status', label, detail? }` event to the message's events array.
+ * Deduplicates consecutive identical status events so the UI does not stutter on repeated flushes.
+ * @param db - Open SQLite connection.
+ * @param messageId - Target message id.
+ * @param event - Must carry a non-empty `label`; `detail` is optional.
+ * @returns The updated events array, or null if the message does not exist or label is empty.
+ */
+export declare function appendMessageStatusEvent({ db, messageId, event }: {
+    db: SqliteDb;
+    messageId: string;
+    event: DbRow;
+}): any[] | null;
+/**
+ * Appends an arbitrary agent event to the message's events array, also streaming `text` deltas
+ * into the `content` column so the message text grows incrementally during a run.
+ * Deduplicates byte-identical consecutive events.
+ * @param db - Open SQLite connection.
+ * @param messageId - Target message id.
+ * @param event - Must carry a non-empty `kind`; `text` field is appended to content when kind is 'text'.
+ * @returns The updated events array, or null if the message does not exist or kind is empty.
+ */
+export declare function appendMessageAgentEvent({ db, messageId, event }: {
+    db: SqliteDb;
+    messageId: string;
+    event: DbRow;
+}): any[] | null;
+/**
+ * Hard-deletes a single message row by id.
+ * @param db - Open SQLite connection.
+ * @param id - Message id to remove.
+ */
+export declare function deleteMessage({ db, id }: {
+    db: SqliteDb;
+    id: string;
+}): void;
+//# sourceMappingURL=messages.d.ts.map

package/dist/store/legacy/sqlite/messages.js

@@ -0,0 +1,246 @@
+import { parseJsonOrUndef } from '@jini-ai/db/core';
+/** @internal Column alias list used by both `listMessages` and `upsertMessage`'s re-fetch. */
+const MESSAGE_COLS = `id, role, content, agent_id AS agentId, agent_name AS agentName,
+  run_id AS runId, run_status AS runStatus,
+  last_run_event_id AS lastRunEventId,
+  events_json AS eventsJson,
+  attachments_json AS attachmentsJson,
+  session_mode AS sessionMode,
+  run_context_json AS runContextJson,
+  created_at AS createdAt, started_at AS startedAt, ended_at AS endedAt,
+  position`;
+/**
+ * Returns all messages for a conversation in ascending position order, with JSON columns parsed.
+ * @param db - Open SQLite connection.
+ * @param conversationId - Conversation whose messages to fetch.
+ * @returns Normalized message objects ready for API serialization.
+ */
+export function listMessages({ db, conversationId }) {
+    return db
+        .prepare(`SELECT ${MESSAGE_COLS}
+         FROM messages
+        WHERE conversation_id = ?
+        ORDER BY position ASC`)
+        .all(conversationId)
+        .map(normalizeMessage);
+}
+/**
+ * Thrown by `upsertMessage` when the caller presents a message `id` together with a
+ * `conversationId` that does not match the conversation the row already belongs to (`id` is a
+ * global primary key, not scoped per-conversation, so this is the only signal available). Rather
+ * than silently updating the wrong conversation's message — or silently doing nothing — while
+ * still bumping the caller-supplied `conversationId`'s `updated_at`, this is a hard failure: it is
+ * always a caller/transport bug (a confused id, or a multi-tenant mixup) and never a legitimate
+ * state to paper over.
+ */
+export class MessageConversationMismatchError extends Error {
+    messageId;
+    actualConversationId;
+    requestedConversationId;
+    constructor({ messageId, actualConversationId, requestedConversationId }) {
+        super(`upsertMessage: message id ${JSON.stringify(messageId)} belongs to a different conversation ` +
+            `(${JSON.stringify(actualConversationId)}), not ${JSON.stringify(requestedConversationId)}`);
+        this.name = 'MessageConversationMismatchError';
+        this.messageId = messageId;
+        this.actualConversationId = actualConversationId;
+        this.requestedConversationId = requestedConversationId;
+    }
+}
+/**
+ * Inserts or updates a message row and bumps the parent conversation's `updated_at` for recency sorting.
+ * On insert, appends to the end of the conversation's position sequence.
+ * On update, preserves `telemetry_finalized_at` once set (one-way latch).
+ *
+ * The existence check, position calculation, insert-or-update, and conversation `updated_at` bump
+ * all run inside one `better-sqlite3` transaction (opened with `BEGIN IMMEDIATE` via `.immediate()`,
+ * not the default deferred `BEGIN`) so the whole read-then-write sequence is atomic: a concurrent
+ * connection's own `upsertMessage` call for the same conversation cannot read the pre-write
+ * `MAX(position)` while this one is still in flight and thereby compute the same next position —
+ * `BEGIN IMMEDIATE` acquires the write lock before this transaction's first read, so a concurrent
+ * writer blocks (or fails with `SQLITE_BUSY`, per its own busy-timeout policy) until this one
+ * commits, rather than interleaving.
+ *
+ * `id` is the messages table's global primary key (not scoped per-conversation), so a row can only
+ * ever belong to one conversation. If the caller-supplied `m.id` already exists under a different
+ * `conversationId`, this throws {@link MessageConversationMismatchError} instead of silently
+ * updating the wrong conversation's row (or the wrong conversation's `updated_at`).
+ *
+ * @param db - Open SQLite connection.
+ * @param conversationId - Owning conversation id.
+ * @param m - Message fields; JSON sub-fields are stringified automatically.
+ * @returns The normalized, re-fetched message row, or null if the row vanished between write and read.
+ * @throws {MessageConversationMismatchError} if `m.id` already exists under a different conversation.
+ */
+export function upsertMessage({ db, conversationId, m }) {
+    const runUpsert = db.transaction(() => {
+        const existing = db
+            .prepare(`SELECT conversation_id AS conversationId, position FROM messages WHERE id = ?`)
+            .get(m.id);
+        if (existing && existing.conversationId !== conversationId) {
+            throw new MessageConversationMismatchError({ messageId: m.id, actualConversationId: existing.conversationId, requestedConversationId: conversationId });
+        }
+        const now = Date.now();
+        if (existing) {
+            db.prepare(`UPDATE messages
+            SET role = ?, content = ?, agent_id = ?, agent_name = ?,
+                run_id = ?, run_status = ?, last_run_event_id = ?,
+                events_json = ?, attachments_json = ?,
+                session_mode = ?, run_context_json = ?,
+                telemetry_finalized_at = CASE
+                  WHEN ? THEN COALESCE(telemetry_finalized_at, ?)
+                  ELSE telemetry_finalized_at
+                END,
+                started_at = ?, ended_at = ?
+          WHERE id = ? AND conversation_id = ?`).run(m.role, m.content, m.agentId ?? null, m.agentName ?? null, m.runId ?? null, m.runStatus ?? null, m.lastRunEventId ?? null, m.events ? JSON.stringify(m.events) : null, m.attachments ? JSON.stringify(m.attachments) : null, normalizeMessageSessionModeForStorage(m.sessionMode), m.runContext ? JSON.stringify(m.runContext) : null, m.telemetryFinalized === true ? 1 : 0, now, m.startedAt ?? null, m.endedAt ?? null, m.id, conversationId);
+        }
+        else {
+            const max = db
+                .prepare(`SELECT COALESCE(MAX(position), -1) AS m FROM messages WHERE conversation_id = ?`)
+                .get(conversationId);
+            const position = (max?.m ?? -1) + 1;
+            const createdAt = typeof m.createdAt === 'number' && Number.isFinite(m.createdAt)
+                ? m.createdAt
+                : now;
+            // 18 values: id, conversation_id, role, content, agent_id, agent_name,
+            // run_id, run_status, last_run_event_id, events_json, attachments_json,
+            // session_mode, run_context_json, telemetry_finalized_at, started_at,
+            // ended_at, position, created_at.
+            db.prepare(`INSERT INTO messages
+           (id, conversation_id, role, content, agent_id, agent_name,
+            run_id, run_status, last_run_event_id, events_json,
+            attachments_json, session_mode, run_context_json,
+            telemetry_finalized_at, started_at, ended_at, position, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(m.id, conversationId, m.role, m.content, m.agentId ?? null, m.agentName ?? null, m.runId ?? null, m.runStatus ?? null, m.lastRunEventId ?? null, m.events ? JSON.stringify(m.events) : null, m.attachments ? JSON.stringify(m.attachments) : null, normalizeMessageSessionModeForStorage(m.sessionMode), m.runContext ? JSON.stringify(m.runContext) : null, m.telemetryFinalized === true ? now : null, m.startedAt ?? null, m.endedAt ?? null, position, createdAt);
+        }
+        // Bump conversation activity so recency-sorted listings (e.g. `listConversations`) reflect this write.
+        db.prepare(`UPDATE conversations SET updated_at = ? WHERE id = ?`).run(now, conversationId);
+        const row = db
+            .prepare(`SELECT ${MESSAGE_COLS} FROM messages WHERE id = ? AND conversation_id = ?`)
+            .get(m.id, conversationId);
+        return row ? normalizeMessage(row) : null;
+    });
+    return runUpsert.immediate();
+}
+/**
+ * Reads whether telemetry has been finalized for a message without loading the full row.
+ * Used to decide whether to enqueue a finalization job.
+ * @returns `{ exists: false }` when the message is not found; otherwise `{ exists: true, finalizedAt }`.
+ */
+export function getMessageTelemetryFinalizationState({ db, messageId }) {
+    const row = db
+        .prepare(`SELECT telemetry_finalized_at AS telemetryFinalizedAt
+         FROM messages
+        WHERE id = ?`)
+        .get(messageId);
+    if (!row) {
+        return {
+            exists: false,
+            finalizedAt: null,
+        };
+    }
+    return {
+        exists: true,
+        finalizedAt: typeof row.telemetryFinalizedAt === 'number' ? row.telemetryFinalizedAt : null,
+    };
+}
+/**
+ * Appends a `{ kind: 'status', label, detail? }` event to the message's events array.
+ * Deduplicates consecutive identical status events so the UI does not stutter on repeated flushes.
+ * @param db - Open SQLite connection.
+ * @param messageId - Target message id.
+ * @param event - Must carry a non-empty `label`; `detail` is optional.
+ * @returns The updated events array, or null if the message does not exist or label is empty.
+ */
+export function appendMessageStatusEvent({ db, messageId, event }) {
+    const label = typeof event?.label === 'string' ? event.label.trim() : '';
+    const detail = typeof event?.detail === 'string' ? event.detail.trim() : '';
+    if (!label)
+        return null;
+    const row = db
+        .prepare(`SELECT events_json AS eventsJson FROM messages WHERE id = ?`)
+        .get(messageId);
+    if (!row)
+        return null;
+    const parsed = parseJsonOrUndef(row.eventsJson);
+    const events = Array.isArray(parsed) ? parsed : [];
+    const last = events[events.length - 1];
+    if (last?.kind === 'status' && last.label === label && (last.detail ?? '') === detail) {
+        return events;
+    }
+    const nextEvent = detail
+        ? { kind: 'status', label, detail }
+        : { kind: 'status', label };
+    const next = [...events, nextEvent];
+    db.prepare(`UPDATE messages SET events_json = ? WHERE id = ?`)
+        .run(JSON.stringify(next), messageId);
+    return next;
+}
+/**
+ * Appends an arbitrary agent event to the message's events array, also streaming `text` deltas
+ * into the `content` column so the message text grows incrementally during a run.
+ * Deduplicates byte-identical consecutive events.
+ * @param db - Open SQLite connection.
+ * @param messageId - Target message id.
+ * @param event - Must carry a non-empty `kind`; `text` field is appended to content when kind is 'text'.
+ * @returns The updated events array, or null if the message does not exist or kind is empty.
+ */
+export function appendMessageAgentEvent({ db, messageId, event }) {
+    if (!event || typeof event !== 'object')
+        return null;
+    const kind = typeof event.kind === 'string' ? event.kind : '';
+    if (!kind)
+        return null;
+    const row = db
+        .prepare(`SELECT content, events_json AS eventsJson FROM messages WHERE id = ?`)
+        .get(messageId);
+    if (!row)
+        return null;
+    const parsed = parseJsonOrUndef(row.eventsJson);
+    const events = Array.isArray(parsed) ? parsed : [];
+    const last = events[events.length - 1];
+    if (last && JSON.stringify(last) === JSON.stringify(event)) {
+        return events;
+    }
+    const next = [...events, event];
+    const textDelta = kind === 'text' && typeof event.text === 'string' ? event.text : '';
+    db.prepare(`UPDATE messages SET content = COALESCE(content, '') || ?, events_json = ? WHERE id = ?`)
+        .run(textDelta, JSON.stringify(next), messageId);
+    return next;
+}
+/**
+ * Hard-deletes a single message row by id.
+ * @param db - Open SQLite connection.
+ * @param id - Message id to remove.
+ */
+export function deleteMessage({ db, id }) {
+    db.prepare(`DELETE FROM messages WHERE id = ?`).run(id);
+}
+/** @internal Converts a raw SQLite row to a plain object with JSON columns parsed and null coerced to undefined. */
+function normalizeMessage(row) {
+    return {
+        id: row.id,
+        role: row.role,
+        content: row.content,
+        agentId: row.agentId ?? undefined,
+        agentName: row.agentName ?? undefined,
+        runId: row.runId ?? undefined,
+        runStatus: row.runStatus ?? undefined,
+        lastRunEventId: row.lastRunEventId ?? undefined,
+        events: parseJsonOrUndef(row.eventsJson),
+        attachments: parseJsonOrUndef(row.attachmentsJson),
+        sessionMode: normalizeMessageSessionMode(row.sessionMode),
+        runContext: parseJsonOrUndef(row.runContextJson),
+        createdAt: row.createdAt ?? undefined,
+        startedAt: row.startedAt ?? undefined,
+        endedAt: row.endedAt ?? undefined,
+    };
+}
+/** @internal Validates that a stored session_mode value is a known ChatSessionMode; returns undefined for unrecognised values. */
+function normalizeMessageSessionMode(value) {
+    return value === 'chat' || value === 'design' || value === 'plan' ? value : undefined;
+}
+/** @internal Same validation as normalizeMessageSessionMode but returns null (SQLite-safe) for unrecognised values. */
+function normalizeMessageSessionModeForStorage(value) {
+    return value === 'chat' || value === 'design' || value === 'plan' ? value : null;
+}
+//# sourceMappingURL=messages.js.map

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

@@ -0,0 +1,3 @@
+/** Unchanged legacy local-chat tables; explicitly bootstrapped by server storage. */
+export declare const LEGACY_CHAT_DDL = "    CREATE TABLE IF NOT EXISTS conversations (\n      id TEXT PRIMARY KEY,\n      project_id TEXT NOT NULL,\n      title TEXT,\n      session_mode TEXT NOT NULL DEFAULT 'design',\n      created_at INTEGER NOT NULL,\n      updated_at INTEGER NOT NULL,\n      FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE\n    );\n\n    CREATE INDEX IF NOT EXISTS idx_conv_project\n      ON conversations(project_id, updated_at DESC);\n\n    CREATE TABLE IF NOT EXISTS messages (\n      id TEXT PRIMARY KEY,\n      conversation_id TEXT NOT NULL,\n      role TEXT NOT NULL,\n      content TEXT NOT NULL,\n      agent_id TEXT,\n      agent_name TEXT,\n      events_json TEXT,\n      attachments_json TEXT,\n      run_context_json TEXT,\n      session_mode TEXT,\n      run_id TEXT,\n      run_status TEXT,\n      last_run_event_id TEXT,\n      telemetry_finalized_at INTEGER,\n      started_at INTEGER,\n      ended_at INTEGER,\n      position INTEGER NOT NULL,\n      created_at INTEGER NOT NULL,\n      FOREIGN KEY(conversation_id) REFERENCES conversations(id) ON DELETE CASCADE\n    );\n\n    CREATE INDEX IF NOT EXISTS idx_messages_conv\n      ON messages(conversation_id, position);\n  ";
+//# sourceMappingURL=schema.d.ts.map

package/dist/store/legacy/sqlite/schema.js

@@ -0,0 +1,40 @@
+/** Unchanged legacy local-chat tables; explicitly bootstrapped by server storage. */
+export const LEGACY_CHAT_DDL = `    CREATE TABLE IF NOT EXISTS conversations (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      title TEXT,
+      session_mode TEXT NOT NULL DEFAULT 'design',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_conv_project
+      ON conversations(project_id, updated_at DESC);
+
+    CREATE TABLE IF NOT EXISTS messages (
+      id TEXT PRIMARY KEY,
+      conversation_id TEXT NOT NULL,
+      role TEXT NOT NULL,
+      content TEXT NOT NULL,
+      agent_id TEXT,
+      agent_name TEXT,
+      events_json TEXT,
+      attachments_json TEXT,
+      run_context_json TEXT,
+      session_mode TEXT,
+      run_id TEXT,
+      run_status TEXT,
+      last_run_event_id TEXT,
+      telemetry_finalized_at INTEGER,
+      started_at INTEGER,
+      ended_at INTEGER,
+      position INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY(conversation_id) REFERENCES conversations(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_messages_conv
+      ON messages(conversation_id, position);
+  `;
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1,21 @@
+/** Pglite 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 createPgliteChatStore({ kernel, scope }, { clock: { nowMs: () => 42 } })
+ * @throws ChatStoreError invalid-input for a mismatched dialect/transport or owner scope.
+ */
+export declare function createPgliteChatStore<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 createPgliteChatMaintenance<DB extends ChatDatabase>(required: {
+    kernel: StorageKernel<DB>;
+}): ChatHistoryMaintenance;
+//# sourceMappingURL=index.d.ts.map

package/dist/store/pglite/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 createPgliteChatStore({ kernel, scope }, { clock: { nowMs: () => 42 } })
+ * @throws ChatStoreError invalid-input for a mismatched dialect/transport or owner scope.
+ */
+export function createPgliteChatStore(required, optional = {}) {
+    validateKernel({ kernel: required.kernel, transports: ['pglite', 'pglite-socket'], dialect: 'postgres' });
+    return createSqlChatStore(required, optional);
+}
+/** Privileged bounded expiry maintenance; never hand this collaborator to request handlers. */
+export function createPgliteChatMaintenance(required) {
+    validateKernel({ kernel: required.kernel, transports: ['pglite', 'pglite-socket'], dialect: 'postgres' });
+    return createSqlChatMaintenance(required);
+}
+//# sourceMappingURL=index.js.map

package/dist/store/ports.d.ts

@@ -0,0 +1,121 @@
+/** Owner-scoped, provider-neutral durable transcripts. See README for paging and composition. */
+import type { ChatMessage } from '../core/messages.js';
+export type ChatOwnerKind = 'user' | 'guest';
+export type ChatTitleSource = 'fallback' | 'generated' | 'manual';
+export interface ChatOwnerScope {
+    readonly scopeId: string;
+    readonly ownerKind: ChatOwnerKind;
+    /** Guest identifier is already hashed by the host. Never a raw bearer token. */
+    readonly ownerId: string;
+}
+export interface ChatConversation {
+    readonly id: string;
+    readonly title: string | null;
+    readonly titleSource: ChatTitleSource;
+    readonly messageCount: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    /** Epoch milliseconds; absence means retained until explicitly deleted. */
+    readonly expiresAt?: number;
+}
+export interface CreateChatConversationInput {
+    readonly id: string;
+    readonly title?: string | null;
+    readonly titleSource?: ChatTitleSource;
+    readonly expiresAt?: number;
+}
+/** Versioned opaque continuation, not an offset or a driver cursor object. */
+export type ChatPageCursor = string;
+export interface ChatPageOptions {
+    /** Default 50; integer from 1 through 200. */
+    readonly limit?: number;
+    readonly cursor?: ChatPageCursor;
+}
+export interface ChatPage<T> {
+    readonly items: readonly T[];
+    /** Absent when this page has no continuation. */
+    readonly nextCursor?: ChatPageCursor;
+}
+export interface ChatMessagePageInput {
+    readonly conversationId: string;
+}
+export interface ChatSearchInput {
+    /** Plain human text, never an FTS expression or SQL fragment. */
+    readonly query: string;
+    readonly conversationId?: string;
+}
+export interface ChatSearchHit {
+    readonly conversationId: string;
+    readonly messageId: string;
+    readonly excerpt: string;
+    /** Relative relevance within this response only, never cross-provider comparable. */
+    readonly score?: number;
+}
+/** Optional capability. No implementation of this interface is promised in this move. */
+export interface ChatSearchCapability {
+    readonly consistency: 'immediate' | 'eventual';
+    search(input: ChatSearchInput, options?: ChatPageOptions): Promise<ChatPage<ChatSearchHit>>;
+}
+/**
+ * Every instance is permanently bound to one immutable owner scope.
+ * Required identity/payload arguments and optional policy/paging arguments occupy separate bags.
+ * Omitted rename source is manual; omitted touch expiry preserves the persisted expiry.
+ * @example store.rename({ id, title }, { source: 'generated' }); store.pageConversations({}, { limit: 50 })
+ */
+export interface ChatStore {
+    /** Compatibility read: all owned conversations, updatedAt descending. */
+    list(): Promise<ChatConversation[]>;
+    /** Unknown and other-owned IDs both return null. */
+    get(required: {
+        readonly id: string;
+    }, optional?: Record<string, never>): Promise<ChatConversation | null>;
+    create(input: CreateChatConversationInput, optional?: Record<string, never>): Promise<ChatConversation>;
+    /** A generated title must not overwrite a manual title. Default source: manual. */
+    rename(required: {
+        readonly id: string;
+        readonly title: string;
+    }, optional?: {
+        readonly source?: ChatTitleSource;
+    }): Promise<ChatConversation | null>;
+    touch(required: {
+        readonly id: string;
+    }, optional?: {
+        readonly expiresAt?: number;
+    }): Promise<void>;
+    /** Cascades messages; unknown/other-owned IDs are no-ops. */
+    delete(required: {
+        readonly id: string;
+    }, optional?: Record<string, never>): Promise<void>;
+    /** Compatibility read: all messages in stored position order; unauthorized returns []. */
+    messages(required: ChatMessagePageInput, optional?: Record<string, never>): Promise<ChatMessage[]>;
+    /** Idempotent update by message ID within its original conversation; unauthorized: null. */
+    appendMessage(required: {
+        readonly conversationId: string;
+        readonly message: ChatMessage;
+    }, optional?: Record<string, never>): Promise<ChatMessage | null>;
+    pageConversations(required: Record<string, never>, optional?: ChatPageOptions): Promise<ChatPage<ChatConversation>>;
+    pageMessages(input: ChatMessagePageInput, options?: ChatPageOptions): Promise<ChatPage<ChatMessage>>;
+    readonly search?: ChatSearchCapability;
+}
+/** Eight-method subset for hosts/fakes without paging; shares the object call contract. */
+export type ChatHistoryStore = Pick<ChatStore, 'list' | 'get' | 'create' | 'rename' | 'touch' | 'delete' | 'messages' | 'appendMessage'>;
+/** Authority for cross-owner retention must never reach ordinary request handlers. */
+export interface ChatHistoryMaintenance {
+    /** Delete at most limit conversations; default 500, integer 1..500. */
+    sweepExpired(required: {
+        readonly now: number;
+    }, optional?: {
+        readonly limit?: number;
+    }): Promise<number>;
+}
+/** Bind one immutable owner scope; no per-call escape to an unscoped store. */
+export type ChatStoreFactory = (required: {
+    readonly scope: ChatOwnerScope;
+}, optional?: Record<string, never>) => ChatStore;
+export type ChatStoreErrorCode = 'invalid-input' | 'invalid-cursor' | 'conflict' | 'unavailable';
+/** Runtime error class in src/store/errors.ts; preserve the original error as cause. */
+export interface ChatStoreError extends Error {
+    readonly name: 'ChatStoreError';
+    readonly code: ChatStoreErrorCode;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/store/ports.js

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

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

@@ -0,0 +1,21 @@
+/** Postgres 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 createPostgresChatStore({ kernel, scope }, { clock: { nowMs: () => 42 } })
+ * @throws ChatStoreError invalid-input for a mismatched dialect/transport or owner scope.
+ */
+export declare function createPostgresChatStore<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 createPostgresChatMaintenance<DB extends ChatDatabase>(required: {
+    kernel: StorageKernel<DB>;
+}): ChatHistoryMaintenance;
+//# sourceMappingURL=index.d.ts.map