spexcode 0.6.7 → 0.6.8

package/node_modules/@spexcode/session-protocol/dist/engine.js

@@ -0,0 +1,478 @@
+import { randomBytes } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, sep } from 'node:path';
+import { normalizeMessage, requireSessionId } from './canonical.js';
+import { classifySqliteError, fail, ProtocolError, rethrowProtocolError } from './errors.js';
+import { MIN_SQLITE_VERSION, migrateComponent, migrateProtocol, registerMigrationTarget, } from './schema.js';
+const require = createRequire(import.meta.url);
+const { DatabaseSync } = require('node:sqlite');
+const JOURNAL_MODE = 'delete';
+const SELECT_COLUMNS = `enqueue_seq, message_id, target_session_id, sender_session_id, protocol_version,
+  kind, body, headers_json, idempotency_key, payload_hash, enqueued_at_ms, dequeued_at_ms`;
+const SQL = {
+    session: 'SELECT session_id, created_at_ms, retired_at_ms FROM protocol_sessions WHERE session_id=?',
+    head: `SELECT ${SELECT_COLUMNS} FROM protocol_messages INDEXED BY protocol_messages_pending_fifo
+         WHERE target_session_id=? AND dequeued_at_ms IS NULL ORDER BY enqueue_seq LIMIT 1`,
+    pending: `SELECT ${SELECT_COLUMNS} FROM protocol_messages INDEXED BY protocol_messages_pending_fifo
+            WHERE target_session_id=? AND dequeued_at_ms IS NULL ORDER BY enqueue_seq`,
+    history: `SELECT ${SELECT_COLUMNS} FROM protocol_messages INDEXED BY protocol_messages_history
+            WHERE target_session_id=? AND enqueue_seq>? ORDER BY enqueue_seq`,
+    byKey: `SELECT ${SELECT_COLUMNS} FROM protocol_messages INDEXED BY protocol_messages_idempotency
+          WHERE target_session_id=? AND idempotency_key=?`,
+};
+const inspections = new WeakMap();
+export function inspectProtocol(protocol) {
+    const inspection = inspections.get(protocol);
+    if (!inspection)
+        fail('PROTOCOL_TRANSACTION_INVALID', 'inspection requires a live protocol handle');
+    return inspection;
+}
+export function isSupportedSqliteVersion(version) {
+    if (typeof version !== 'string')
+        return false;
+    const parse = (value) => value.split('.').map(Number);
+    const [major, minor, patch] = parse(version);
+    if (![major, minor, patch].every(Number.isInteger))
+        return false;
+    const [minimumMajor, minimumMinor, minimumPatch] = parse(MIN_SQLITE_VERSION);
+    if (major !== minimumMajor)
+        return major > minimumMajor;
+    if (minor !== minimumMinor)
+        return minor > minimumMinor;
+    return patch >= minimumPatch;
+}
+function validateDatabasePath(databasePath) {
+    if (typeof databasePath !== 'string'
+        || databasePath.length === 0
+        || databasePath.startsWith('file:')
+        || !isAbsolute(databasePath)) {
+        fail('PROTOCOL_PATH_NOT_ABSOLUTE', 'databasePath must be an absolute filesystem path string');
+    }
+    if (databasePath.includes('\0'))
+        fail('PROTOCOL_PATH_INVALID', 'databasePath must not contain a NUL byte');
+    if (databasePath.endsWith(sep))
+        fail('PROTOCOL_PATH_INVALID', 'databasePath must name a file, not a directory');
+}
+function checkParentDirectory(databasePath) {
+    const directory = dirname(databasePath);
+    let stat;
+    try {
+        stat = statSync(directory);
+    }
+    catch (error) {
+        fail('PROTOCOL_PATH_PARENT_MISSING', `database parent directory does not exist: ${directory}`, error);
+    }
+    if (!stat.isDirectory()) {
+        fail('PROTOCOL_PATH_PARENT_MISSING', `database parent is not a directory: ${directory}`);
+    }
+}
+function normalizeBusyTimeout(value) {
+    const timeout = value ?? 5000;
+    if (typeof timeout !== 'number' || !Number.isFinite(timeout) || timeout < 0) {
+        fail('PROTOCOL_PRAGMA_UNSUPPORTED', 'busyTimeoutMs must be a non-negative finite number');
+    }
+    return Math.trunc(timeout);
+}
+function normalizeNow(value) {
+    if (value !== undefined && typeof value !== 'function') {
+        fail('PROTOCOL_TRANSACTION_INVALID', 'now must be a synchronous function');
+    }
+    const now = (value ?? (() => Date.now()));
+    return () => {
+        const timestamp = now();
+        if (!Number.isSafeInteger(timestamp) || timestamp < 0) {
+            fail('PROTOCOL_SQLITE_ERROR', 'now() must return a non-negative safe integer');
+        }
+        return timestamp;
+    };
+}
+function sleepSync(milliseconds) {
+    const buffer = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(buffer, 0, 0, milliseconds);
+}
+function retryWhileBusy(budgetMs, body) {
+    const deadline = Date.now() + Math.max(budgetMs, 1);
+    for (;;) {
+        try {
+            return body();
+        }
+        catch (error) {
+            const busy = error instanceof ProtocolError
+                ? error.code === 'PROTOCOL_DATABASE_BUSY'
+                : classifySqliteError(error) === 'PROTOCOL_DATABASE_BUSY';
+            if (!busy || Date.now() >= deadline)
+                throw error;
+            sleepSync(20);
+        }
+    }
+}
+function toMessage(row) {
+    return {
+        enqueueSeq: Number(row.enqueue_seq),
+        messageId: row.message_id,
+        targetSessionId: row.target_session_id,
+        senderSessionId: row.sender_session_id,
+        protocolVersion: Number(row.protocol_version),
+        kind: row.kind,
+        body: Buffer.from(row.body),
+        headers: JSON.parse(row.headers_json),
+        idempotencyKey: row.idempotency_key,
+        payloadHash: Buffer.from(row.payload_hash).toString('hex'),
+        enqueuedAtMs: Number(row.enqueued_at_ms),
+        dequeuedAtMs: row.dequeued_at_ms === null ? null : Number(row.dequeued_at_ms),
+    };
+}
+function requireSql(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        fail('PROTOCOL_TRANSACTION_INVALID', 'transaction SQL must be a non-empty string');
+    }
+    return value;
+}
+function requireSqlParams(params) {
+    for (const value of params) {
+        if (value !== null
+            && typeof value !== 'string'
+            && typeof value !== 'bigint'
+            && !(value instanceof Uint8Array)
+            && !(typeof value === 'number' && Number.isFinite(value))) {
+            fail('PROTOCOL_TRANSACTION_INVALID', 'transaction parameters must be SqlParam values');
+        }
+    }
+}
+function buildHandle(database, config) {
+    const { readOnly, now } = config;
+    let transactionActive = false;
+    let closed = false;
+    const ensureOpen = () => {
+        if (closed)
+            fail('PROTOCOL_SQLITE_ERROR', 'protocol handle is closed');
+    };
+    const rejectReentry = (operation) => {
+        if (transactionActive) {
+            fail('PROTOCOL_TRANSACTION_INVALID', `${operation} cannot be called inside withTransaction; use tx.enqueue for messages and tx.exec or tx.query for SQL`);
+        }
+    };
+    const write = (operation, body) => {
+        ensureOpen();
+        rejectReentry(operation);
+        if (readOnly)
+            fail('PROTOCOL_DATABASE_READONLY', 'this handle was opened read-only');
+        try {
+            database.exec('BEGIN IMMEDIATE');
+        }
+        catch (error) {
+            rethrowProtocolError(error);
+        }
+        try {
+            const value = body();
+            database.exec('COMMIT');
+            return value;
+        }
+        catch (error) {
+            try {
+                database.exec('ROLLBACK');
+            }
+            catch { }
+            rethrowProtocolError(error);
+        }
+    };
+    const read = (body) => {
+        ensureOpen();
+        try {
+            return body();
+        }
+        catch (error) {
+            rethrowProtocolError(error);
+        }
+    };
+    const requireAddress = (sessionId, allowRetired = false) => {
+        const row = database.prepare(SQL.session).get(sessionId);
+        if (!row)
+            fail('PROTOCOL_SESSION_UNKNOWN', `unknown protocol address: ${sessionId}`);
+        if (!allowRetired && row.retired_at_ms !== null) {
+            fail('PROTOCOL_SESSION_RETIRED', `protocol address is retired: ${sessionId}`);
+        }
+        return row;
+    };
+    const insertNormalizedMessage = (message) => {
+        const sessionId = message.targetSessionId;
+        requireAddress(sessionId);
+        if (message.idempotencyKey !== null) {
+            const prior = database.prepare(SQL.byKey).get(sessionId, message.idempotencyKey);
+            if (prior) {
+                if (Buffer.compare(Buffer.from(prior.payload_hash), Buffer.from(message.hash)) !== 0) {
+                    fail('PROTOCOL_IDEMPOTENCY_CONFLICT', `idempotency key ${message.idempotencyKey} was reused with different message bytes`);
+                }
+                return toMessage(prior);
+            }
+        }
+        const messageId = randomBytes(16).toString('hex');
+        const enqueuedAtMs = now();
+        database.prepare(`INSERT INTO protocol_messages
+      (message_id, target_session_id, sender_session_id, protocol_version, kind, body,
+       headers_json, idempotency_key, payload_hash, enqueued_at_ms, dequeued_at_ms)
+      VALUES (?,?,?,?,?,?,?,?,?,?,NULL)`).run(messageId, sessionId, message.senderSessionId, message.protocolVersion, message.kind, message.body, message.headersJson, message.idempotencyKey, message.hash, enqueuedAtMs);
+        const row = database.prepare(`SELECT ${SELECT_COLUMNS} FROM protocol_messages WHERE message_id=?`)
+            .get(messageId);
+        if (!row)
+            fail('PROTOCOL_SQLITE_ERROR', 'inserted message could not be read back');
+        return toMessage(row);
+    };
+    const insertMessage = (sessionId, input) => insertNormalizedMessage(normalizeMessage(sessionId, input));
+    const transaction = {
+        exec(sql, ...params) {
+            requireSql(sql);
+            requireSqlParams(params);
+            try {
+                const result = database.prepare(sql).run(...params);
+                return { changes: Number(result.changes), lastInsertRowid: Number(result.lastInsertRowid) };
+            }
+            catch (error) {
+                rethrowProtocolError(error);
+            }
+        },
+        query(sql, ...params) {
+            requireSql(sql);
+            requireSqlParams(params);
+            try {
+                return database.prepare(sql).all(...params);
+            }
+            catch (error) {
+                rethrowProtocolError(error);
+            }
+        },
+        enqueue(sessionId, message) {
+            requireSessionId(sessionId);
+            return insertMessage(sessionId, message);
+        },
+    };
+    const handle = {
+        databasePath: config.databasePath,
+        readOnly,
+        initialize(sessionId) {
+            rejectReentry('protocol.initialize');
+            requireSessionId(sessionId);
+            return write('protocol.initialize', () => {
+                const existing = database.prepare(SQL.session).get(sessionId);
+                if (existing) {
+                    if (existing.retired_at_ms !== null) {
+                        fail('PROTOCOL_SESSION_RETIRED', `protocol address is retired and cannot be resurrected: ${sessionId}`);
+                    }
+                    return { sessionId, createdAtMs: Number(existing.created_at_ms), retiredAtMs: null };
+                }
+                const createdAtMs = now();
+                database.prepare('INSERT INTO protocol_sessions(session_id, created_at_ms, retired_at_ms) VALUES(?,?,NULL)')
+                    .run(sessionId, createdAtMs);
+                return { sessionId, createdAtMs, retiredAtMs: null };
+            });
+        },
+        enqueue(sessionId, input) {
+            rejectReentry('protocol.enqueue');
+            requireSessionId(sessionId);
+            const normalized = normalizeMessage(sessionId, input);
+            return write('protocol.enqueue', () => insertNormalizedMessage(normalized));
+        },
+        dequeue(sessionId) {
+            rejectReentry('protocol.dequeue');
+            requireSessionId(sessionId);
+            return write('protocol.dequeue', () => {
+                requireAddress(sessionId);
+                const row = database.prepare(SQL.head).get(sessionId);
+                if (!row)
+                    return null;
+                const dequeuedAtMs = now();
+                const result = database.prepare('UPDATE protocol_messages SET dequeued_at_ms=? WHERE enqueue_seq=? AND dequeued_at_ms IS NULL').run(dequeuedAtMs, row.enqueue_seq);
+                if (Number(result.changes) !== 1) {
+                    fail('PROTOCOL_SQLITE_ERROR', 'FIFO head changed inside a write transaction');
+                }
+                return toMessage({ ...row, dequeued_at_ms: dequeuedAtMs });
+            });
+        },
+        listPending(sessionId) {
+            requireSessionId(sessionId);
+            return read(() => {
+                requireAddress(sessionId, true);
+                return database.prepare(SQL.pending).all(sessionId).map(row => toMessage(row));
+            });
+        },
+        readMessages(sessionId, afterSequence = 0) {
+            requireSessionId(sessionId);
+            if (!Number.isSafeInteger(afterSequence) || afterSequence < 0) {
+                fail('PROTOCOL_CURSOR_INVALID', 'afterSequence must be a non-negative safe integer');
+            }
+            return read(() => {
+                requireAddress(sessionId, true);
+                return database.prepare(SQL.history).all(sessionId, afterSequence).map(row => toMessage(row));
+            });
+        },
+        retire(sessionId) {
+            rejectReentry('protocol.retire');
+            requireSessionId(sessionId);
+            return write('protocol.retire', () => {
+                const row = requireAddress(sessionId, true);
+                if (row.retired_at_ms !== null) {
+                    return {
+                        sessionId,
+                        createdAtMs: Number(row.created_at_ms),
+                        retiredAtMs: Number(row.retired_at_ms),
+                    };
+                }
+                const pending = database.prepare(`SELECT 1 AS present FROM protocol_messages INDEXED BY protocol_messages_pending_fifo
+           WHERE target_session_id=? AND dequeued_at_ms IS NULL LIMIT 1`).get(sessionId);
+                if (pending) {
+                    fail('PROTOCOL_RETIRE_NON_EMPTY', `cannot retire an address with pending messages: ${sessionId}`);
+                }
+                const retiredAtMs = now();
+                database.prepare('UPDATE protocol_sessions SET retired_at_ms=? WHERE session_id=? AND retired_at_ms IS NULL')
+                    .run(retiredAtMs, sessionId);
+                return { sessionId, createdAtMs: Number(row.created_at_ms), retiredAtMs };
+            });
+        },
+        withTransaction(body) {
+            rejectReentry('protocol.withTransaction');
+            ensureOpen();
+            if (typeof body !== 'function') {
+                fail('PROTOCOL_TRANSACTION_INVALID', 'a transaction body is required');
+            }
+            if (body.constructor?.name === 'AsyncFunction') {
+                fail('PROTOCOL_TRANSACTION_INVALID', 'a transaction body must be synchronous; use tx.enqueue inside it');
+            }
+            if (readOnly)
+                fail('PROTOCOL_DATABASE_READONLY', 'this handle was opened read-only');
+            try {
+                database.exec('BEGIN IMMEDIATE');
+            }
+            catch (error) {
+                rethrowProtocolError(error);
+            }
+            transactionActive = true;
+            let value;
+            try {
+                value = body(transaction);
+                if (value && typeof value.then === 'function') {
+                    fail('PROTOCOL_TRANSACTION_INVALID', 'a transaction body must not return a promise; use tx.enqueue');
+                }
+            }
+            catch (error) {
+                transactionActive = false;
+                try {
+                    database.exec('ROLLBACK');
+                }
+                catch { }
+                throw error;
+            }
+            transactionActive = false;
+            try {
+                database.exec('COMMIT');
+                return value;
+            }
+            catch (error) {
+                try {
+                    database.exec('ROLLBACK');
+                }
+                catch { }
+                rethrowProtocolError(error);
+            }
+        },
+        dataVersion() {
+            return read(() => Number(database.prepare('PRAGMA data_version').get()?.data_version));
+        },
+        close() {
+            rejectReentry('protocol.close');
+            if (closed)
+                return;
+            database.close();
+            closed = true;
+        },
+    };
+    const inspection = {
+        pragmas: () => ({
+            journal_mode: String(database.prepare('PRAGMA journal_mode').get()?.journal_mode),
+            foreign_keys: Number(database.prepare('PRAGMA foreign_keys').get()?.foreign_keys),
+            synchronous: Number(database.prepare('PRAGMA synchronous').get()?.synchronous),
+            busy_timeout: Number(database.prepare('PRAGMA busy_timeout').get()?.timeout),
+        }),
+        counts: () => ({
+            sessions: Number(database.prepare('SELECT count(*) AS count FROM protocol_sessions').get()?.count),
+            messages: Number(database.prepare('SELECT count(*) AS count FROM protocol_messages').get()?.count),
+        }),
+        queryPlans: () => {
+            const plan = (sql, ...params) => database
+                .prepare(`EXPLAIN QUERY PLAN ${sql}`)
+                .all(...params)
+                .map(row => String(row.detail))
+                .join(' | ');
+            return {
+                dequeueHead: plan(SQL.head, 's'),
+                listPending: plan(SQL.pending, 's'),
+                readMessages: plan(SQL.history, 's', 0),
+                idempotencyLookup: plan(SQL.byKey, 's', 'k'),
+            };
+        },
+    };
+    inspections.set(handle, inspection);
+    registerMigrationTarget(handle, {
+        readOnly,
+        apply(component, migrations) {
+            ensureOpen();
+            rejectReentry('applyComponentMigrations');
+            try {
+                return migrateComponent(database, component, migrations, now);
+            }
+            catch (error) {
+                rethrowProtocolError(error);
+            }
+        },
+    });
+    return handle;
+}
+export function openProtocol(databasePath, options = {}) {
+    validateDatabasePath(databasePath);
+    checkParentDirectory(databasePath);
+    const readOnly = options.readOnly === true;
+    const busyTimeoutMs = normalizeBusyTimeout(options.busyTimeoutMs);
+    const now = normalizeNow(options.now);
+    let database;
+    try {
+        database = new DatabaseSync(databasePath, { readOnly });
+    }
+    catch (error) {
+        rethrowProtocolError(error);
+    }
+    try {
+        database.exec(`PRAGMA busy_timeout=${busyTimeoutMs}`);
+        if (Number(database.prepare('PRAGMA busy_timeout').get()?.timeout) !== busyTimeoutMs) {
+            fail('PROTOCOL_PRAGMA_UNSUPPORTED', 'busy_timeout did not read back the requested value');
+        }
+        const version = database.prepare('SELECT sqlite_version() AS version').get()?.version;
+        if (!isSupportedSqliteVersion(version)) {
+            fail('PROTOCOL_SQLITE_VERSION_UNSUPPORTED', `SQLite ${String(version)} is below ${MIN_SQLITE_VERSION}`);
+        }
+        database.exec('PRAGMA foreign_keys=ON');
+        if (Number(database.prepare('PRAGMA foreign_keys').get()?.foreign_keys) !== 1) {
+            fail('PROTOCOL_PRAGMA_UNSUPPORTED', 'foreign_keys could not be enabled');
+        }
+        const mode = String(database.prepare('PRAGMA journal_mode').get()?.journal_mode);
+        if (mode !== JOURNAL_MODE) {
+            fail('PROTOCOL_JOURNAL_MODE_UNSUPPORTED', `journal_mode is ${mode}, not ${JOURNAL_MODE}; this version does not convert a database`);
+        }
+        retryWhileBusy(busyTimeoutMs, () => {
+            if (!readOnly) {
+                database.exec('PRAGMA synchronous=FULL');
+                if (Number(database.prepare('PRAGMA synchronous').get()?.synchronous) !== 2) {
+                    fail('PROTOCOL_PRAGMA_UNSUPPORTED', 'synchronous could not be set to FULL');
+                }
+            }
+            migrateProtocol(database, readOnly, now);
+        });
+    }
+    catch (error) {
+        try {
+            database.close();
+        }
+        catch { }
+        rethrowProtocolError(error);
+    }
+    return buildHandle(database, { databasePath, readOnly, now });
+}

package/node_modules/@spexcode/session-protocol/dist/errors.d.ts

@@ -0,0 +1,8 @@
+export type ProtocolErrorCode = 'PROTOCOL_PATH_NOT_ABSOLUTE' | 'PROTOCOL_PATH_INVALID' | 'PROTOCOL_PATH_PARENT_MISSING' | 'PROTOCOL_SQLITE_VERSION_UNSUPPORTED' | 'PROTOCOL_JOURNAL_MODE_UNSUPPORTED' | 'PROTOCOL_PRAGMA_UNSUPPORTED' | 'PROTOCOL_SCHEMA_CHECKSUM_MISMATCH' | 'PROTOCOL_SCHEMA_GENERATION_UNSUPPORTED' | 'PROTOCOL_SCHEMA_REGISTRY_INCONSISTENT' | 'PROTOCOL_SESSION_ID_INVALID' | 'PROTOCOL_SESSION_UNKNOWN' | 'PROTOCOL_SESSION_RETIRED' | 'PROTOCOL_RETIRE_NON_EMPTY' | 'PROTOCOL_IDEMPOTENCY_CONFLICT' | 'PROTOCOL_MESSAGE_INVALID' | 'PROTOCOL_CURSOR_INVALID' | 'PROTOCOL_TRANSACTION_INVALID' | 'PROTOCOL_DATABASE_BUSY' | 'PROTOCOL_DATABASE_READONLY' | 'PROTOCOL_DATABASE_UNAVAILABLE' | 'PROTOCOL_DATABASE_CORRUPT' | 'PROTOCOL_SQLITE_ERROR';
+export declare class ProtocolError extends Error {
+    readonly code: ProtocolErrorCode;
+    constructor(code: ProtocolErrorCode, message: string, cause?: unknown);
+}
+export declare function fail(code: ProtocolErrorCode, message: string, cause?: unknown): never;
+export declare function classifySqliteError(error: unknown): ProtocolErrorCode | null;
+export declare function rethrowProtocolError(error: unknown): never;

package/node_modules/@spexcode/session-protocol/dist/errors.js

@@ -0,0 +1,39 @@
+export class ProtocolError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, { cause });
+        this.name = 'ProtocolError';
+        this.code = code;
+    }
+}
+export function fail(code, message, cause) {
+    throw new ProtocolError(code, message, cause);
+}
+export function classifySqliteError(error) {
+    const value = error;
+    const code = String(value?.code ?? '');
+    if (code === 'SQLITE_BUSY' || code === 'SQLITE_LOCKED')
+        return 'PROTOCOL_DATABASE_BUSY';
+    if (code === 'SQLITE_READONLY')
+        return 'PROTOCOL_DATABASE_READONLY';
+    if (code === 'SQLITE_CORRUPT' || code === 'SQLITE_NOTADB')
+        return 'PROTOCOL_DATABASE_CORRUPT';
+    if (code === 'SQLITE_CANTOPEN')
+        return 'PROTOCOL_DATABASE_UNAVAILABLE';
+    const text = String(value?.message ?? error);
+    if (/database is locked|database table is locked|SQLITE_BUSY/i.test(text))
+        return 'PROTOCOL_DATABASE_BUSY';
+    if (/readonly|read-only|attempt to write/i.test(text))
+        return 'PROTOCOL_DATABASE_READONLY';
+    if (/malformed|not a database|disk image|corrupt/i.test(text))
+        return 'PROTOCOL_DATABASE_CORRUPT';
+    if (/unable to open database/i.test(text))
+        return 'PROTOCOL_DATABASE_UNAVAILABLE';
+    return null;
+}
+export function rethrowProtocolError(error) {
+    if (error instanceof ProtocolError)
+        throw error;
+    const message = String(error?.message ?? error);
+    fail(classifySqliteError(error) ?? 'PROTOCOL_SQLITE_ERROR', message, error);
+}

package/node_modules/@spexcode/session-protocol/dist/index.d.ts

@@ -0,0 +1,60 @@
+export type SqlParam = null | number | bigint | string | Uint8Array;
+export interface MessageInput {
+    kind: string;
+    body: Uint8Array;
+    headers?: Record<string, string>;
+    senderSessionId?: string | null;
+    idempotencyKey?: string | null;
+    protocolVersion?: number;
+}
+export interface Message {
+    enqueueSeq: number;
+    messageId: string;
+    targetSessionId: string;
+    senderSessionId: string | null;
+    protocolVersion: number;
+    kind: string;
+    body: Uint8Array;
+    headers: Record<string, string>;
+    idempotencyKey: string | null;
+    payloadHash: string;
+    enqueuedAtMs: number;
+    dequeuedAtMs: number | null;
+}
+export interface SessionAddress {
+    sessionId: string;
+    createdAtMs: number;
+    retiredAtMs: number | null;
+}
+export interface ProtocolTransaction {
+    exec(sql: string, ...params: SqlParam[]): {
+        changes: number;
+        lastInsertRowid: number;
+    };
+    query(sql: string, ...params: SqlParam[]): Record<string, unknown>[];
+    enqueue(sessionId: string, message: MessageInput): Message;
+}
+export interface SessionProtocol {
+    readonly databasePath: string;
+    readonly readOnly: boolean;
+    initialize(sessionId: string): SessionAddress;
+    enqueue(sessionId: string, message: MessageInput): Message;
+    dequeue(sessionId: string): Message | null;
+    listPending(sessionId: string): Message[];
+    readMessages(sessionId: string, afterSequence?: number): Message[];
+    retire(sessionId: string): SessionAddress;
+    withTransaction<T>(body: (tx: ProtocolTransaction) => T): T;
+    dataVersion(): number;
+    close(): void;
+}
+export interface OpenOptions {
+    readOnly?: boolean;
+    busyTimeoutMs?: number;
+    now?: () => number;
+}
+export { canonicalPreimage, LIMITS, payloadHash, PROTOCOL_VERSION } from './canonical.js';
+export { ProtocolError } from './errors.js';
+export type { ProtocolErrorCode } from './errors.js';
+export { openProtocol } from './engine.js';
+export { applyComponentMigrations, MIN_SQLITE_VERSION } from './schema.js';
+export type { ComponentMigration } from './schema.js';

package/node_modules/@spexcode/session-protocol/dist/index.js

@@ -0,0 +1,4 @@
+export { canonicalPreimage, LIMITS, payloadHash, PROTOCOL_VERSION } from './canonical.js';
+export { ProtocolError } from './errors.js';
+export { openProtocol } from './engine.js';
+export { applyComponentMigrations, MIN_SQLITE_VERSION } from './schema.js';

package/node_modules/@spexcode/session-protocol/dist/schema.d.ts

@@ -0,0 +1,36 @@
+import type { SessionProtocol, SqlParam } from './index.js';
+export interface ComponentMigration {
+    readonly version: number;
+    readonly sql: string;
+}
+interface StatementResult {
+    changes: number | bigint;
+    lastInsertRowid: number | bigint;
+}
+export interface StatementLike {
+    get(...params: SqlParam[]): Record<string, unknown> | undefined;
+    all(...params: SqlParam[]): Record<string, unknown>[];
+    run(...params: SqlParam[]): StatementResult;
+}
+export interface DatabaseLike {
+    exec(sql: string): void;
+    prepare(sql: string): StatementLike;
+    close(): void;
+}
+interface PreparedMigration extends ComponentMigration {
+    checksum: string;
+}
+interface MigrationTarget {
+    readonly readOnly: boolean;
+    apply(component: string, migrations: readonly ComponentMigration[]): number;
+}
+export declare const MIN_SQLITE_VERSION = "3.38.0";
+export declare const PROTOCOL_COMPONENT = "session-protocol";
+export declare const PROTOCOL_MIGRATION_SQL = "\nCREATE TABLE protocol_sessions (\n  session_id     TEXT    NOT NULL PRIMARY KEY,\n  created_at_ms  INTEGER NOT NULL,\n  retired_at_ms  INTEGER,\n  CHECK (length(session_id) BETWEEN 1 AND 256),\n  CHECK (session_id NOT GLOB '*[^0-9A-Za-z_-]*'),\n  CHECK (session_id NOT GLOB '-*'),\n  CHECK (created_at_ms >= 0),\n  CHECK (retired_at_ms IS NULL OR retired_at_ms >= 0)\n) STRICT;\n\nCREATE TABLE protocol_messages (\n  enqueue_seq        INTEGER PRIMARY KEY AUTOINCREMENT,\n  message_id         TEXT    NOT NULL UNIQUE,\n  target_session_id  TEXT    NOT NULL REFERENCES protocol_sessions(session_id),\n  sender_session_id  TEXT,\n  protocol_version   INTEGER NOT NULL,\n  kind               TEXT    NOT NULL,\n  body               BLOB    NOT NULL,\n  headers_json       TEXT    NOT NULL,\n  idempotency_key    TEXT,\n  payload_hash       BLOB    NOT NULL,\n  enqueued_at_ms     INTEGER NOT NULL,\n  dequeued_at_ms     INTEGER,\n  CHECK (message_id GLOB '[0-9a-f]*' AND length(message_id) = 32),\n  CHECK (protocol_version >= 1),\n  CHECK (length(kind) BETWEEN 1 AND 64),\n  CHECK (kind NOT GLOB '*[^0-9A-Za-z._-]*'),\n  CHECK (length(body) <= 1048576),\n  CHECK (json_valid(headers_json) AND json_type(headers_json) = 'object'),\n  CHECK (length(CAST(headers_json AS BLOB)) <= 65536),\n  CHECK (idempotency_key IS NULL OR length(idempotency_key) BETWEEN 1 AND 256),\n  CHECK (length(payload_hash) = 32),\n  CHECK (enqueued_at_ms >= 0),\n  CHECK (dequeued_at_ms IS NULL OR dequeued_at_ms >= 0),\n  CHECK (sender_session_id IS NULL OR length(sender_session_id) BETWEEN 1 AND 256)\n) STRICT;\n\nCREATE UNIQUE INDEX protocol_messages_idempotency\n  ON protocol_messages (target_session_id, idempotency_key)\n  WHERE idempotency_key IS NOT NULL;\n\nCREATE INDEX protocol_messages_pending_fifo\n  ON protocol_messages (target_session_id, enqueue_seq)\n  WHERE dequeued_at_ms IS NULL;\n\nCREATE INDEX protocol_messages_history\n  ON protocol_messages (target_session_id, enqueue_seq);\n";
+export declare const REGISTRY_SQL = "\nCREATE TABLE IF NOT EXISTS schema_migrations (\n  component      TEXT    NOT NULL,\n  version        INTEGER NOT NULL,\n  checksum       TEXT    NOT NULL,\n  applied_at_ms  INTEGER NOT NULL,\n  PRIMARY KEY (component, version)\n) STRICT;\n";
+export declare const PROTOCOL_MIGRATIONS: readonly PreparedMigration[];
+export declare function registerMigrationTarget(protocol: SessionProtocol, target: MigrationTarget): void;
+export declare function migrateProtocol(database: DatabaseLike, readOnly: boolean, now: () => number): number;
+export declare function migrateComponent(database: DatabaseLike, component: string, migrations: readonly ComponentMigration[], now: () => number): number;
+export declare function applyComponentMigrations(protocol: SessionProtocol, component: string, migrations: readonly ComponentMigration[]): number;
+export {};