@jini-ai/daemon 0.6.12 → 0.6.15-rc.2

package/dist/remote-tool-executor.js

@@ -0,0 +1,250 @@
+/**
+ * @module remote-tool-executor
+ *
+ * A `ToolExecutor` whose calls run in ANOTHER process on the same machine: the client end of
+ * `@jini-ai/daemon/http`'s `registerToolExecutionRoutes`. A host whose agent runtime lives in one
+ * process and whose gated tool surface lives in another (a slim daemon beside a site server) wires
+ * this in where an in-process executor would go; the far side's own executor still authorizes,
+ * confirms, audits and runs the call, so nothing is gated twice here and nothing is gated less.
+ *
+ * Wire protocol (one POST per call, `application/x-ndjson` response):
+ * - request body `{ executionId, principal, run: { id }, toolId, input, context? }`, where `context`
+ *   is opaque host JSON from `contextFor`;
+ * - a 200 status line is flushed BEFORE the far executor is called, then zero or more
+ *   `{"type":"surface","emission":…}` lines, then exactly one `{"type":"result","result":…}` or
+ *   `{"type":"throw","error":{"name","message","code?"}}` line;
+ * - every refusal (400/401/403/413/503) is a non-200 status sent before the far executor runs.
+ *
+ * At-most-once. This client never retries. A failure is thrown as a {@link ToolRpcError} with one of
+ * two codes, and a caller decides what to tell the model from the code alone:
+ * - `TOOL_NOT_DISPATCHED`: the socket never connected, or the far side answered with a non-200
+ *   status. Nothing ran, so the caller may retry.
+ * - `TOOL_OUTCOME_UNKNOWN`: anything else after the request was written — a reset, a hang-up, an end
+ *   with no terminal line, a malformed line (including a terminal line missing a field a settled call
+ *   must carry). "No headers seen yet" is NOT proof that nothing ran: a TCP reset can discard bytes
+ *   the far side already sent, so the call may have committed.
+ *
+ * Transport is `node:http.request` (`node:https.request` for an `https:` base URL, which honours the
+ * process trust store including `NODE_EXTRA_CA_CERTS`) with a fresh connection per call
+ * (`agent: false`), never `fetch` and never a pooled keep-alive socket: a reused socket the far side
+ * already closed fails with a reset after the write, which would turn a call that never ran into an
+ * "outcome unknown" one. There is no idle timeout because a tool may legitimately park on a human for
+ * a long time.
+ */
+import { randomUUID } from 'node:crypto';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { TLSSocket } from 'node:tls';
+import { ToolInputError } from '@jini-ai/core';
+/** A remote tool call that failed in transport. `code` says whether the call may have run; see the module doc. */
+export class ToolRpcError extends Error {
+    code;
+    constructor({ code, message }, optional = {}) {
+        super(message, optional);
+        this.name = 'ToolRpcError';
+        this.code = code;
+    }
+}
+export const TOOL_EXECUTIONS_ROUTE_PATH = '/internal/tool-executions';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const TOOL_EXECUTION_STATUSES = new Set(['completed', 'denied', 'confirmation-denied', 'timed-out', 'cancelled', 'failed']);
+/**
+ * The shape each line type must carry. A terminal line settles the call, so it must hold every field
+ * a settled call needs: `{"type":"result","result":{}}` accepted as-is would record an ordinary
+ * result and let a continuation repeat a call that may have committed.
+ */
+const LINE_SHAPES = new Map([
+    ['surface', (line) => isRecord(line.emission)],
+    ['result', ({ result }) => isRecord(result) && typeof result.executionId === 'string' && TOOL_EXECUTION_STATUSES.has(result.status)],
+    ['throw', ({ error }) => isRecord(error) && typeof error.message === 'string'],
+]);
+/** Parses one NDJSON line; `null` means malformed, which the caller treats as outcome unknown. */
+export function parseToolExecutionLine({ text }, _optional = {}) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const valid = isRecord(value) && LINE_SHAPES.get(value.type)?.(value) === true;
+    return valid ? value : null;
+}
+/**
+ * Turns a far-side throw back into an error a local caller can branch on. `ToolInputError` keeps its
+ * class, because the in-process executor throws it for an unknown tool id and callers test it with
+ * `instanceof`. Anything else becomes a plain `Error` carrying the same name, message and code.
+ */
+export function rehydrateToolExecutionError({ error }, _optional = {}) {
+    if (error.name === 'ToolInputError')
+        return new ToolInputError({ message: error.message });
+    const rebuilt = new Error(error.message);
+    rebuilt.name = typeof error.name === 'string' ? error.name : 'Error';
+    if (typeof error.code === 'string')
+        rebuilt.code = error.code;
+    return rebuilt;
+}
+function rpcError(code, detail, cause) {
+    const prefix = code === 'TOOL_NOT_DISPATCHED' ? 'remote tool call was not dispatched' : 'remote tool call outcome is unknown';
+    return new ToolRpcError({ code, message: `${prefix}: ${detail}` }, cause === undefined ? {} : { cause });
+}
+/**
+ * Marks `connected` once the request's socket can carry the request (or immediately for an open one).
+ * For TLS that is the finished handshake, not the TCP connect: a refused certificate fails before a
+ * byte of the request is written, so nothing ran.
+ */
+function trackConnect(req, onConnect) {
+    req.once('socket', (socket) => {
+        if (socket.connecting)
+            socket.once(socket instanceof TLSSocket ? 'secureConnect' : 'connect', onConnect);
+        else
+            onConnect();
+    });
+}
+/** Opens the POST, or returns `TOOL_NOT_DISPATCHED` when the adapter refuses synchronously (e.g. `ERR_INVALID_PROTOCOL`): nothing was written. */
+function openRequest({ url, token, body, request }, _optional = {}) {
+    try {
+        return request(url, {
+            method: 'POST',
+            agent: false,
+            headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) },
+        });
+    }
+    catch (error) {
+        return rpcError('TOOL_NOT_DISPATCHED', error instanceof Error ? error.message : String(error), error);
+    }
+}
+/**
+ * Reads the NDJSON stream. Surfaces are forwarded strictly in order and the terminal line settles
+ * only after every earlier surface was delivered. A surface the local emitter rejects is dropped: the
+ * far handler cannot observe that rejection, and failing the call over a display-only message
+ * would turn a committed call into an unknown one.
+ */
+function readToolStream({ res, settle, fail }, { emitSurface }) {
+    let buffer = '';
+    let terminal = false;
+    let surfaces = Promise.resolve();
+    const onLine = (text) => {
+        if (terminal || text.trim() === '')
+            return;
+        const line = parseToolExecutionLine({ text });
+        if (line === null) {
+            terminal = true;
+            fail('malformed response line');
+            return;
+        }
+        if (line.type === 'surface') {
+            surfaces = surfaces.then(() => emitSurface?.(line.emission)).catch(() => undefined);
+            return;
+        }
+        terminal = true;
+        void surfaces.then(() => settle(line));
+    };
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+        buffer += chunk;
+        const lines = buffer.split('\n');
+        buffer = lines.pop() ?? '';
+        lines.forEach(onLine);
+    });
+    // Once the terminal line is in hand the outcome is known, so a later reset cannot unsettle it.
+    const failUnlessTerminal = (detail) => { if (!terminal)
+        fail(detail); };
+    res.on('end', () => { onLine(buffer); failUnlessTerminal('response ended without a terminal line'); });
+    res.on('aborted', () => failUnlessTerminal('response aborted'));
+    res.on('error', (error) => failUnlessTerminal(`response error: ${error.message}`));
+}
+function settleTerminal(line, settlers) {
+    if (line.type === 'result')
+        settlers.resolve(line.result);
+    else
+        settlers.reject(rehydrateToolExecutionError({ error: line.error }));
+}
+/** Starts one POST that settles through `settlers`; returns a cancel that destroys it and resolves `cancelled`. */
+function startCall({ url, token, body, executionId, settlers }, { request, emitSurface }) {
+    const req = openRequest({ url, token, body, request });
+    if (req instanceof ToolRpcError) {
+        settlers.reject(req);
+        return () => undefined;
+    }
+    let settled = false;
+    let connected = false;
+    const finish = (outcome, destroy) => {
+        if (settled)
+            return;
+        settled = true;
+        if (destroy)
+            req.destroy();
+        outcome();
+    };
+    const unknown = (detail, cause) => finish(() => settlers.reject(rpcError('TOOL_OUTCOME_UNKNOWN', detail, cause)), true);
+    trackConnect(req, () => { connected = true; });
+    req.on('error', (error) => {
+        if (!connected)
+            finish(() => settlers.reject(rpcError('TOOL_NOT_DISPATCHED', error.message, error)), true);
+        else
+            unknown(error.message, error);
+    });
+    req.on('response', (res) => {
+        if (res.statusCode !== 200) {
+            res.resume();
+            finish(() => settlers.reject(rpcError('TOOL_NOT_DISPATCHED', `HTTP ${res.statusCode ?? 'unknown'}`)), true);
+            return;
+        }
+        readToolStream({
+            res,
+            settle: (line) => finish(() => settleTerminal(line, settlers), false),
+            fail: (detail) => unknown(detail),
+        }, { emitSurface });
+    });
+    req.end(body);
+    return () => finish(() => settlers.resolve({ executionId, status: 'cancelled' }), true);
+}
+function wireBody({ executionId, principal, run, toolId, input, context }) {
+    return JSON.stringify({ executionId, principal, run: { id: run.id }, toolId, input, ...(context === undefined ? {} : { context }) });
+}
+/**
+ * Creates the client `ToolExecutor` for a far `registerToolExecutionRoutes` endpoint.
+ *
+ * - `execute` streams one call; a caller `signal` (or `cancel` with the id sent on the wire) destroys
+ *   the request, which the far route turns into its own abort, and settles locally as `cancelled`
+ *   — the same result an in-process executor gives a cancelled call.
+ * - `getAuditRecord` returns `null`: the far side owns the audit trail.
+ * - `resumeConfirmation` throws: confirmations park on, and are answered on, the far side.
+ *
+ * @complexity O(response bytes) per call; `cancel` is an O(1) map lookup.
+ */
+export function createRemoteToolExecutor({ baseUrl, token }, { request: injectedRequest, contextFor } = {}) {
+    const url = new URL(TOOL_EXECUTIONS_ROUTE_PATH, baseUrl);
+    const request = injectedRequest ?? (url.protocol === 'https:' ? https.request : http.request);
+    const inFlight = new Map();
+    async function execute({ principal, run, toolId, input }, { signal, emitSurface } = {}) {
+        const executionId = randomUUID();
+        if (signal?.aborted)
+            return { executionId, status: 'cancelled' };
+        const body = wireBody({ executionId, principal, run, toolId, input, context: contextFor?.({ principal, run, toolId }) });
+        let settlers;
+        const promise = new Promise((resolve, reject) => { settlers = { resolve, reject }; });
+        const cancel = startCall({ url, token, body, executionId, settlers }, { request, emitSurface });
+        inFlight.set(executionId, cancel);
+        signal?.addEventListener('abort', cancel, { once: true });
+        try {
+            return await promise;
+        }
+        finally {
+            inFlight.delete(executionId);
+            signal?.removeEventListener('abort', cancel);
+        }
+    }
+    return {
+        execute,
+        resumeConfirmation: () => {
+            throw new Error('remote tool executions are confirmed on the executing server');
+        },
+        cancel: ({ executionId }) => inFlight.get(executionId)?.(),
+        getAuditRecord: () => null,
+    };
+}
+//# sourceMappingURL=remote-tool-executor.js.map

package/dist/routing-tool-executor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module routing-tool-executor
+ *
+ * One `ToolExecutor` over two: tools this process registered run locally, every other id goes to a
+ * remote executor (`createRemoteToolExecutor`). The routing key is only "is this id in the local
+ * registry". Remote descriptors are never registered locally as executable placeholders, so a
+ * remote id can never reach a local handler, and an id nobody knows is refused by the far side's
+ * executor exactly as an in-process one would refuse it.
+ *
+ * Execution ids are not tracked here. `cancel` goes to both executors, each of which ignores ids it
+ * does not own; `getAuditRecord` asks the local one first (the remote one has none); and
+ * `resumeConfirmation` is local-only because remote confirmations park on the far side. That keeps
+ * routing correct without a per-call map that would grow for the life of the process.
+ */
+import type { ToolExecutor } from './tool-executor.js';
+export interface RoutingToolExecutorRequired {
+    readonly local: ToolExecutor;
+    readonly remote: ToolExecutor;
+    /** True when `toolId` is in the local registry. */
+    readonly isLocal: (required: {
+        readonly toolId: string;
+    }, optional?: Record<string, never>) => boolean;
+}
+/**
+ * Creates the routing executor.
+ * @complexity O(1) plus `isLocal`'s own cost per call.
+ */
+export declare function createRoutingToolExecutor({ local, remote, isLocal }: RoutingToolExecutorRequired, _optional?: Record<string, never>): ToolExecutor;
+//# sourceMappingURL=routing-tool-executor.d.ts.map

package/dist/routing-tool-executor.js

@@ -0,0 +1,16 @@
+/**
+ * Creates the routing executor.
+ * @complexity O(1) plus `isLocal`'s own cost per call.
+ */
+export function createRoutingToolExecutor({ local, remote, isLocal }, _optional = {}) {
+    return {
+        execute: (args, optional) => (isLocal({ toolId: args.toolId }) ? local : remote).execute(args, optional),
+        resumeConfirmation: (args) => local.resumeConfirmation(args),
+        cancel: (args) => {
+            local.cancel(args);
+            remote.cancel(args);
+        },
+        getAuditRecord: (args) => local.getAuditRecord(args) ?? remote.getAuditRecord(args),
+    };
+}
+//# sourceMappingURL=routing-tool-executor.js.map

package/dist/run-lifecycle.d.ts

@@ -137,9 +137,12 @@ export interface RunLifecycle {
     resumeSlowRunNotice(args: {
         readonly runId: string;
     }): void;
-    /** Resolves once `runId` reaches a terminal state; resolves immediately if it already has. */
+    /** Resolves once `runId` reaches a terminal state; resolves immediately if it already has.
+     * Aborting `signal` rejects with its reason and unregisters the waiter (a caller tearing down). */
     waitForTerminal(args: {
         readonly runId: string;
+    }, optional?: {
+        readonly signal?: AbortSignal;
     }): Promise<RunStatus>;
     /**
      * Replays buffered history after `options.afterCursor` (or from the

package/dist/run-lifecycle.js

@@ -375,6 +375,36 @@ export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
             // Reported to `start()`'s caller — see above.
         }
     }
+    /** Settles like `promise`, or rejects with the signal's reason once it aborts; the listener is always released. */
+    function abortable({ promise }, { signal }) {
+        if (!signal)
+            return Promise.resolve(promise);
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
+        return new Promise((resolve, reject) => {
+            const onAbort = () => { reject(signal.reason); };
+            signal.addEventListener('abort', onAbort, { once: true });
+            Promise.resolve(promise).then(resolve, reject).finally(() => { signal.removeEventListener('abort', onAbort); });
+        });
+    }
+    /** Registers a terminal waiter; an abort removes it again so a cancelled wait retains nothing. */
+    function parkTerminalWaiter({ record }, { signal }) {
+        signal?.throwIfAborted();
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const index = record.terminalWaiters.indexOf(waiter);
+                if (index >= 0)
+                    record.terminalWaiters.splice(index, 1);
+                reject(signal?.reason);
+            };
+            const waiter = (status) => {
+                signal?.removeEventListener('abort', onAbort);
+                resolve(status);
+            };
+            record.terminalWaiters.push(waiter);
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
     function resolveTerminalWaiters(record) {
         const waiters = record.terminalWaiters.splice(0, record.terminalWaiters.length);
         const status = toPublicStatus(record);
@@ -792,20 +822,20 @@ export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
                     void handleSlowRunNotice(runId);
                 } });
         },
-        async waitForTerminal({ runId }) {
+        async waitForTerminal({ runId }, { signal } = {}) {
             const record = requireRun(runId);
             // Awaited (and *propagated*, unlike in `get`/`list`) before any waiter is registered. A run
             // whose durable start append rejects is unwound, and nothing ever calls `finish()` for it — so
             // a waiter parked inside that window would never be resolved by anyone. Failing the wait with
             // the same error that failed the start is the only honest terminal answer, and awaiting first
             // means `terminalWaiters` can only ever hold waiters for a run that really does exist.
-            await record.startPromise;
+            // The abort signal is observed during that wait too: a stalled start append must not strand
+            // a caller that has already given up (a pre-aborted signal rejects at once).
+            await abortable({ promise: record.startPromise }, { signal });
             if (isTerminalRunState({ state: record.status.state })) {
                 return toPublicStatus(record);
             }
-            return new Promise((resolve) => {
-                record.terminalWaiters.push(resolve);
-            });
+            return parkTerminalWaiter({ record }, { signal });
         },
         async stream({ runId, onEvent }, options = {}) {
             const record = runs.get(runId);

package/dist/store/event-log/sqlite-kernel.d.ts

@@ -0,0 +1,18 @@
+import type { StorageKernel } from '@jini-ai/db/kernel';
+import { type SqliteEventLogDatabase, type SqliteEventLogOptions, type SqliteEventLogWithReceipts } from './sqlite-policy.js';
+/**
+ * Borrow a SQLite kernel, awaiting its readiness and optionally ensuring the owner's schema.
+ * Every operation joins the caller's kernel context; append/drop/replay use kernel transactions.
+ * Refusals are values: hosts aborting a composed operation must use their exception/rollback path.
+ * Close leaves the borrowed kernel open. Driver, readiness and serialization failures propagate.
+ * @param required Host kernel with the event-log table subset.
+ * @param optional Schema setup, retention cap and clock; defaults match the synchronous adapter.
+ * @returns Concrete log with optional conflict/capacity receipts.
+ * @complexity Setup uses a fixed number of statements; replay is O(n) in retained entries.
+ * @example
+ * const log = await createKernelSqliteEventLog({ kernel }, { schemaSetup: 'host' });
+ */
+export declare function createKernelSqliteEventLog<DB extends SqliteEventLogDatabase>(required: {
+    kernel: StorageKernel<DB>;
+}, optional?: SqliteEventLogOptions): Promise<SqliteEventLogWithReceipts>;
+//# sourceMappingURL=sqlite-kernel.d.ts.map

package/dist/store/event-log/sqlite-kernel.js

@@ -0,0 +1,135 @@
+/** Async SQLite execution over the host kernel; event-log policy lives in sqlite-policy. */
+import { createSystemClock } from '@jini-ai/core/primitives';
+import { SQLITE_EVENT_LOG_SCHEMA, resolveMaxEntriesPerRun, assertValidReplayCursor, existingAppendResult, replayResult, rowToEntry, } from './sqlite-policy.js';
+/**
+ * Borrow a SQLite kernel, awaiting its readiness and optionally ensuring the owner's schema.
+ * Every operation joins the caller's kernel context; append/drop/replay use kernel transactions.
+ * Refusals are values: hosts aborting a composed operation must use their exception/rollback path.
+ * Close leaves the borrowed kernel open. Driver, readiness and serialization failures propagate.
+ * @param required Host kernel with the event-log table subset.
+ * @param optional Schema setup, retention cap and clock; defaults match the synchronous adapter.
+ * @returns Concrete log with optional conflict/capacity receipts.
+ * @complexity Setup uses a fixed number of statements; replay is O(n) in retained entries.
+ * @example
+ * const log = await createKernelSqliteEventLog({ kernel }, { schemaSetup: 'host' });
+ */
+export async function createKernelSqliteEventLog(required, optional = {}) {
+    const { kernel } = required;
+    const maxEntriesPerRun = resolveMaxEntriesPerRun(optional.maxEntriesPerRun);
+    if (!kernel || kernel.dialect !== 'sqlite' || kernel.transport !== 'better-sqlite3') {
+        throw new Error('createKernelSqliteEventLog: pass a SQLite better-sqlite3 kernel');
+    }
+    await kernel.ready;
+    // Narrow the query type to required tables; keep the same kernel and its async transaction scope.
+    const run = (body) => kernel.run(db => body(db));
+    await run(db => setupSchema({ db }, optional));
+    const clock = optional.clock ?? createSystemClock();
+    const appendWithResult = (input, options = {}) => kernel.transaction(() => run(db => appendInKernel({ db, input, clock, maxEntriesPerRun }, options)));
+    return {
+        appendWithResult,
+        async append(input, options = {}) {
+            // Select only the protocol's dedupe option so the legacy method cannot opt into refusal.
+            const result = await appendWithResult(input, options.dedupeKey === undefined ? {} : { dedupeKey: options.dedupeKey });
+            return result.entry;
+        },
+        async replay({ runId, afterCursor }) {
+            // Validate even when the run is unknown, matching the synchronous adapter.
+            assertValidReplayCursor(afterCursor);
+            // One statement for all three reads: another process cannot evict between the gap check
+            // and the entry read, which would otherwise return a gap reported as ok. A statement, not a
+            // transaction, so replay works on read-only kernels and inside a host's run() body.
+            return run(db => replayInKernel({ db, runId, afterCursor }));
+        },
+        listRunIds(_args) {
+            return run(async (db) => (await db.selectFrom('jini_event_log_runs').select('run_id')
+                .orderBy('run_id').execute()).map(row => row.run_id));
+        },
+        drop({ runId }) {
+            return kernel.transaction(() => run(async (db) => {
+                await db.deleteFrom('jini_event_log_entries').where('run_id', '=', runId).execute();
+                await db.deleteFrom('jini_event_log_runs').where('run_id', '=', runId).execute();
+            }));
+        },
+        async close(_args) { },
+    };
+}
+/** Ensure using the shared DDL, or validate all required columns without issuing DDL/writes. */
+async function setupSchema({ db }, options = {}) {
+    if (options.schemaSetup !== 'host') {
+        // Keep the existing synchronous factory free of a new eager peer import.
+        const { sql } = await import('kysely');
+        // Kysely executes one statement at a time; the owner DDL contains no embedded semicolons.
+        for (const statement of SQLITE_EVENT_LOG_SCHEMA.split(';').filter(part => part.trim())) {
+            await sql.raw(statement).execute(db);
+        }
+    }
+    await db.selectFrom('jini_event_log_runs').select(['run_id', 'next_cursor']).limit(0).execute();
+    await db.selectFrom('jini_event_log_entries')
+        .select(['run_id', 'cursor', 'event', 'data', 'recorded_at', 'dedupe_key']).limit(0).execute();
+}
+/**
+ * Dedupe precedes the cap; refusals allocate nothing. The caller holds a kernel transaction,
+ * which serializes SQLite cursor allocation with projection writes and concurrent appends.
+ * @complexity Fixed statement count; count/eviction scan the bounded per-run retained rows.
+ */
+async function appendInKernel({ db, input, clock, maxEntriesPerRun }, options = {}) {
+    if (options.dedupeKey !== undefined) {
+        const row = await db.selectFrom('jini_event_log_entries').selectAll()
+            .where('run_id', '=', input.runId).where('dedupe_key', '=', options.dedupeKey).executeTakeFirst();
+        if (row)
+            return existingAppendResult({ row, input }, options);
+    }
+    const { count } = await db.selectFrom('jini_event_log_entries')
+        .select(db.fn.countAll().as('count')).where('run_id', '=', input.runId).executeTakeFirstOrThrow();
+    if (options.retentionPolicy === 'reject' && count >= maxEntriesPerRun) {
+        return { kind: 'capacity-exceeded', maxEntriesPerRun };
+    }
+    let run = await db.selectFrom('jini_event_log_runs').selectAll()
+        .where('run_id', '=', input.runId).executeTakeFirst();
+    if (!run) {
+        run = { run_id: input.runId, next_cursor: 1 };
+        await db.insertInto('jini_event_log_runs').values(run).execute();
+    }
+    const cursor = run.next_cursor;
+    const recordedAt = clock.nowMs();
+    await db.insertInto('jini_event_log_entries').values({
+        run_id: input.runId, cursor, event: input.event, data: JSON.stringify(input.data ?? null),
+        recorded_at: recordedAt, dedupe_key: options.dedupeKey ?? null,
+    }).execute();
+    await db.updateTable('jini_event_log_runs').set({ next_cursor: cursor + 1 })
+        .where('run_id', '=', input.runId).execute();
+    if (count + 1 > maxEntriesPerRun) {
+        await db.deleteFrom('jini_event_log_entries').where('run_id', '=', input.runId)
+            .where('cursor', 'in', db.selectFrom('jini_event_log_entries').select('cursor')
+            .where('run_id', '=', input.runId).orderBy('cursor').limit(count + 1 - maxEntriesPerRun)).execute();
+    }
+    return { kind: 'inserted', entry: { id: String(cursor), event: input.event, data: input.data, recordedAt } };
+}
+/**
+ * Read the run, its oldest retained cursor and the entries after the cursor in ONE statement
+ * (SQLite reads a statement from one snapshot), then decide gaps/truncation from that snapshot.
+ * A gap loads payloads it then discards; the price of needing no transaction.
+ * @complexity One statement; O(n) in retained entries after the cursor.
+ */
+async function replayInKernel({ db, runId, afterCursor }) {
+    // Cursors start at 1, so "after 0" is every retained entry.
+    const after = afterCursor === null ? 0 : Number(afterCursor);
+    const rows = await db.selectFrom('jini_event_log_runs as r')
+        .leftJoin('jini_event_log_entries as e', join => join.onRef('e.run_id', '=', 'r.run_id').on('e.cursor', '>', after))
+        .select(eb => [
+        'r.next_cursor', 'e.cursor', 'e.event', 'e.data', 'e.recorded_at',
+        eb.selectFrom('jini_event_log_entries').select(eb.fn.min('cursor').as('m'))
+            .where('run_id', '=', runId).as('oldest_cursor'),
+    ])
+        .where('r.run_id', '=', runId).orderBy('e.cursor').execute();
+    const [first] = rows;
+    if (!first)
+        return { kind: 'unknown-run' };
+    const oldest = first.oldest_cursor === null ? undefined : { cursor: first.oldest_cursor };
+    const result = replayResult({ run: { run_id: runId, next_cursor: first.next_cursor }, oldest, afterCursor });
+    if (result.kind !== 'ok')
+        return result;
+    const entries = rows.flatMap(({ cursor, event, data, recorded_at }) => cursor === null || event === null || data === null || recorded_at === null ? [] : [rowToEntry({ cursor, event, data, recorded_at })]);
+    return { ...result, entries };
+}
+//# sourceMappingURL=sqlite-kernel.js.map

package/dist/store/event-log/sqlite-policy.d.ts

@@ -0,0 +1,93 @@
+/** Shared event-log schema and policies; synchronous and kernel execution retain distinct transactions. */
+import type { Clock } from '@jini-ai/core/primitives';
+import type { EventLog, EventLogAppendInput, EventLogAppendOptions, EventLogEntry, EventLogReplayResult } from '@jini-ai/protocol';
+/**
+ * Default per-run retention cap applied when `SqliteEventLogOptions.maxEntriesPerRun` is
+ * omitted — see that option's doc for why a durable adapter defaults to a bound instead of
+ * mirroring the in-memory reference adapter's unbounded-by-default behavior.
+ */
+export declare const DEFAULT_MAX_ENTRIES_PER_RUN = 2000;
+export interface SqliteEventLogOptions {
+    /**
+     * Maximum entries retained per run before the oldest are evicted. Defaults to
+     * {@link DEFAULT_MAX_ENTRIES_PER_RUN} (2000) when omitted — unlike the in-memory reference
+     * adapter (`@jini-ai/daemon`'s `createInMemoryEventLog`), where an omitted cap means unbounded,
+     * a durable on-disk store defaults to a bounded retention window because unbounded persistent
+     * growth is a real, unattended operational risk (disk exhaustion across long-lived runs) in a
+     * way an in-process, GC'd, process-lifetime-bounded structure is not. Pass an explicit value
+     * (larger, smaller, or `0`) to override the default in either direction — the caller then
+     * owns that tradeoff explicitly. Must be a non-negative safe integer; anything else (negative,
+     * fractional, `NaN`, `Infinity`) throws at construction time.
+     */
+    readonly maxEntriesPerRun?: number;
+    /** Core Clock for durable recordedAt values; omitted clock preserves system wall time. */
+    readonly clock?: Clock;
+    /** Ensure tables by default; host skips DDL and requires an already migrated schema. */
+    readonly schemaSetup?: 'ensure' | 'host';
+}
+/** @internal Validates and resolves `options.maxEntriesPerRun`, applying the documented default. */
+export declare function resolveMaxEntriesPerRun(value: number | undefined): number;
+/** @internal Validates a `replay(runId, afterCursor)` cursor. `null` ("from the beginning") is always valid. */
+export declare function assertValidReplayCursor(afterCursor: string | null): void;
+/** A `@jini-ai/daemon` `EventLog` backed by a `better-sqlite3` database, plus a `close()` to release the file handle. */
+export interface SqliteEventLog extends EventLog {
+    close(_args: Record<string, never>): Promise<void>;
+}
+export interface RunRow {
+    run_id: string;
+    next_cursor: number;
+}
+export interface EntryRow {
+    run_id: string;
+    cursor: number;
+    event: string;
+    data: string;
+    recorded_at: number;
+    dedupe_key: string | null;
+}
+/** Decode the persisted JSON boundary while preserving the original cursor and timestamp. */
+export declare function rowToEntry(row: Pick<EntryRow, 'cursor' | 'event' | 'data' | 'recorded_at'>): EventLogEntry;
+/** The existing event-log tables; hosts may extend this database with their own tables. */
+export interface SqliteEventLogDatabase {
+    jini_event_log_runs: RunRow;
+    jini_event_log_entries: EntryRow;
+}
+/** Opt-in append policies; omitted options preserve legacy dedupe and FIFO retention. */
+export type SqliteEventLogAppendOptions = EventLogAppendOptions & {
+    detectConflicts?: boolean;
+    retentionPolicy?: 'evict-oldest' | 'reject';
+};
+/** Refusals carry no entry because no write or cursor allocation took place. */
+export type SqliteEventLogAppendResult<P> = {
+    kind: 'inserted' | 'existing';
+    entry: EventLogEntry<P>;
+} | {
+    kind: 'conflict';
+} | {
+    kind: 'capacity-exceeded';
+    maxEntriesPerRun: number;
+};
+/** Concrete factories expose receipts without widening the protocol's append return type. */
+export interface SqliteEventLogWithReceipts extends SqliteEventLog {
+    /**
+     * Compare exact persisted JSON only when detectConflicts is true; dedupe precedes capacity.
+     * SQL/serialization failures reject. Conflicts/capacity refusals leave all state untouched.
+     * @example
+     * await log.appendWithResult({ runId: 'r', event: 'update', data: 1 }, { dedupeKey: 'k', detectConflicts: true });
+     */
+    appendWithResult<P>(required: EventLogAppendInput<P>, optional?: SqliteEventLogAppendOptions): Promise<SqliteEventLogAppendResult<P>>;
+}
+/** Resolve an existing row without writes; legacy retries do not serialize the new payload. */
+export declare function existingAppendResult<P>({ row, input }: {
+    row: EntryRow;
+    input: EventLogAppendInput<P>;
+}, options?: SqliteEventLogAppendOptions): SqliteEventLogAppendResult<P>;
+/** Decide replay status before loading payloads, keeping a replay gap to indexed lookups only. */
+export declare function replayResult({ run, oldest, afterCursor }: {
+    run: RunRow;
+    oldest: Pick<EntryRow, 'cursor'> | undefined;
+    afterCursor: string | null;
+}): EventLogReplayResult;
+/** Owner's DDL for both automatic setup and host-managed migrations; no schema fork. */
+export declare const SQLITE_EVENT_LOG_SCHEMA: string;
+//# sourceMappingURL=sqlite-policy.d.ts.map