spexcode 0.6.7 → 0.7.0-next.0

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

@@ -0,0 +1,46 @@
+import type { ProtocolTransaction, SessionProtocol } from '@spexcode/session-protocol';
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface NewSessionEvent {
+    eventId: string;
+    type: string;
+    schemaVersion: number;
+    subjectSessionId: string;
+    payload: Uint8Array;
+    occurredAtMs: number;
+    ignorable?: boolean;
+}
+export interface SessionEvent {
+    eventId: string;
+    eventSeq: number;
+    type: string;
+    schemaVersion: number;
+    subjectSessionId: string;
+    payload: Uint8Array;
+    occurredAtMs: number;
+    ignorable: boolean;
+}
+export interface EventReadOptions {
+    afterSequence?: number;
+    atSequence?: number;
+}
+export type SessionEventReducer<State> = (state: State, event: SessionEvent) => State;
+export type SessionEventReducers<State> = Readonly<Record<string, SessionEventReducer<State>>>;
+export interface ReplayOptions<State> extends EventReadOptions {
+    initialState: State;
+    reducers: SessionEventReducers<State>;
+}
+export interface SessionEventStore {
+    append(tx: ProtocolTransaction, input: NewSessionEvent): SessionEvent;
+    hasMessageEvent(tx: ProtocolTransaction, subjectSessionId: string, messageId: string): boolean;
+    read(subjectSessionId: string, options?: EventReadOptions, tx?: ProtocolTransaction): readonly SessionEvent[];
+    replay<State>(subjectSessionId: string, options: ReplayOptions<State>, tx?: ProtocolTransaction): State;
+}
+export declare function encodeEventJson(value: unknown): Uint8Array;
+export declare function decodeEventJson(payload: Uint8Array): JsonValue;
+export declare function openSessionEvents(protocol: SessionProtocol): SessionEventStore;
+export { SessionEventError } from './errors.js';
+export type { SessionEventErrorCode } from './errors.js';
+export { SESSION_EVENTS_MIGRATION_SQL, SESSION_EVENTS_MIGRATIONS } from './schema.js';

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

@@ -0,0 +1,245 @@
+import { applyComponentMigrations } from '@spexcode/session-protocol';
+import { failSessionEvent, SessionEventError } from './errors.js';
+import { SESSION_EVENTS_MIGRATIONS } from './schema.js';
+const EVENT_ID = /^[0-9a-f]{32}$/;
+const EVENT_TYPE = /^[0-9A-Za-z._:-]{1,128}$/;
+const SESSION_ID = /^(?!-)[0-9A-Za-z_-]{1,256}$/;
+const MAX_PAYLOAD_BYTES = 1_048_576;
+const SELECT_COLUMNS = `subject_session_id, event_seq, event_id, event_type,
+  schema_version, ignorable, payload, occurred_at_ms`;
+const requireTransaction = (tx) => {
+    if (!tx || typeof tx.exec !== 'function' || typeof tx.query !== 'function') {
+        failSessionEvent('EVENT_TRANSACTION_INVALID', 'a live protocol transaction context is required');
+    }
+    return tx;
+};
+const requireSessionId = (subjectSessionId) => {
+    if (typeof subjectSessionId !== 'string' || !SESSION_ID.test(subjectSessionId)) {
+        failSessionEvent('EVENT_SESSION_ID_INVALID', 'subject session id has an invalid grammar');
+    }
+};
+const requireSequence = (value, name, defaultValue) => {
+    const resolved = value ?? defaultValue;
+    if (!Number.isSafeInteger(resolved) || resolved < 0) {
+        failSessionEvent('EVENT_SEQUENCE_INVALID', `${name} must be a non-negative safe integer`);
+    }
+    return resolved;
+};
+const requireEnvelope = (input) => {
+    if (!input || typeof input !== 'object') {
+        failSessionEvent('EVENT_PAYLOAD_INVALID', 'event input must be an object');
+    }
+    if (typeof input.eventId !== 'string' || !EVENT_ID.test(input.eventId)) {
+        failSessionEvent('EVENT_ID_INVALID', 'event id must be exactly 32 lowercase hexadecimal characters');
+    }
+    if (typeof input.type !== 'string' || !EVENT_TYPE.test(input.type)) {
+        failSessionEvent('EVENT_TYPE_INVALID', 'event type has an invalid grammar');
+    }
+    if (!Number.isSafeInteger(input.schemaVersion) || input.schemaVersion < 1) {
+        failSessionEvent('EVENT_SCHEMA_VERSION_INVALID', 'schema version must be a positive safe integer');
+    }
+    requireSessionId(input.subjectSessionId);
+    if (!(input.payload instanceof Uint8Array) || input.payload.byteLength > MAX_PAYLOAD_BYTES) {
+        failSessionEvent('EVENT_PAYLOAD_INVALID', `payload must be Uint8Array at most ${MAX_PAYLOAD_BYTES} bytes`);
+    }
+    if (!Number.isSafeInteger(input.occurredAtMs) || input.occurredAtMs < 0) {
+        failSessionEvent('EVENT_TIMESTAMP_INVALID', 'occurredAtMs must be a non-negative safe integer');
+    }
+    if (input.ignorable !== undefined && typeof input.ignorable !== 'boolean') {
+        failSessionEvent('EVENT_PAYLOAD_INVALID', 'ignorable must be a boolean when present');
+    }
+    return new Uint8Array(input.payload);
+};
+const eventFromRow = (row) => Object.freeze({
+    eventId: String(row.event_id),
+    eventSeq: Number(row.event_seq),
+    type: String(row.event_type),
+    schemaVersion: Number(row.schema_version),
+    subjectSessionId: String(row.subject_session_id),
+    payload: new Uint8Array(row.payload),
+    occurredAtMs: Number(row.occurred_at_ms),
+    ignorable: Number(row.ignorable) === 1,
+});
+const snapshotJson = (value, path, active) => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || Object.is(value, -0)) {
+            failSessionEvent('EVENT_JSON_INVALID', `${path} contains a non-lossless JSON number`);
+        }
+        return value;
+    }
+    if (typeof value !== 'object') {
+        failSessionEvent('EVENT_JSON_INVALID', `${path} contains a non-JSON value`);
+    }
+    if (active.has(value))
+        failSessionEvent('EVENT_JSON_INVALID', `${path} contains a cycle`);
+    active.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const keys = Reflect.ownKeys(value);
+            if (keys.some(key => key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9][0-9]*)$/.test(key)))) {
+                failSessionEvent('EVENT_JSON_INVALID', `${path} contains non-index array properties`);
+            }
+            const result = [];
+            for (let index = 0; index < value.length; index++) {
+                if (!Object.prototype.hasOwnProperty.call(value, index)) {
+                    failSessionEvent('EVENT_JSON_INVALID', `${path} contains a sparse array`);
+                }
+                result.push(snapshotJson(value[index], `${path}[${index}]`, active));
+            }
+            return result;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            failSessionEvent('EVENT_JSON_INVALID', `${path} must contain only plain JSON objects`);
+        }
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const symbols = Object.getOwnPropertySymbols(value);
+        if (symbols.length > 0)
+            failSessionEvent('EVENT_JSON_INVALID', `${path} contains symbol keys`);
+        const result = {};
+        for (const key of Object.keys(descriptors).sort()) {
+            const descriptor = descriptors[key];
+            if (!descriptor.enumerable || !('value' in descriptor)) {
+                failSessionEvent('EVENT_JSON_INVALID', `${path}.${key} is not an enumerable data property`);
+            }
+            result[key] = snapshotJson(descriptor.value, `${path}.${key}`, active);
+        }
+        return result;
+    }
+    finally {
+        active.delete(value);
+    }
+};
+export function encodeEventJson(value) {
+    const snapshot = snapshotJson(value, '$', new Set());
+    return new TextEncoder().encode(JSON.stringify(snapshot));
+}
+export function decodeEventJson(payload) {
+    if (!(payload instanceof Uint8Array)) {
+        failSessionEvent('EVENT_JSON_INVALID', 'JSON payload must be Uint8Array');
+    }
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(payload);
+    }
+    catch (error) {
+        failSessionEvent('EVENT_JSON_INVALID', 'JSON payload is not valid UTF-8', error);
+    }
+    try {
+        return snapshotJson(JSON.parse(text), '$', new Set());
+    }
+    catch (error) {
+        if (error instanceof SessionEventError)
+            throw error;
+        failSessionEvent('EVENT_JSON_INVALID', 'payload is not valid JSON', error);
+    }
+}
+export function openSessionEvents(protocol) {
+    try {
+        applyComponentMigrations(protocol, 'session-events', SESSION_EVENTS_MIGRATIONS);
+    }
+    catch (error) {
+        failSessionEvent('EVENT_STORAGE', 'session event component migration failed', error);
+    }
+    const requireSubject = (tx, subjectSessionId) => {
+        const rows = tx.query('SELECT 1 AS present FROM protocol_sessions WHERE session_id=?', subjectSessionId);
+        if (rows.length === 0) {
+            failSessionEvent('EVENT_SESSION_UNKNOWN', `unknown protocol session: ${subjectSessionId}`);
+        }
+    };
+    const append = (txInput, input) => {
+        const tx = requireTransaction(txInput);
+        const payload = requireEnvelope(input);
+        requireSubject(tx, input.subjectSessionId);
+        if (tx.query('SELECT 1 AS present FROM session_events WHERE event_id=?', input.eventId).length > 0) {
+            failSessionEvent('EVENT_ID_EXISTS', `event id already exists: ${input.eventId}`);
+        }
+        const nextRows = tx.query('SELECT COALESCE(MAX(event_seq), 0) + 1 AS next_seq FROM session_events WHERE subject_session_id=?', input.subjectSessionId);
+        const eventSeq = Number(nextRows[0]?.next_seq);
+        if (!Number.isSafeInteger(eventSeq) || eventSeq < 1) {
+            failSessionEvent('EVENT_SEQUENCE_INVALID', 'next event sequence is not a positive safe integer');
+        }
+        try {
+            tx.exec(`INSERT INTO session_events
+          (subject_session_id,event_seq,event_id,event_type,schema_version,ignorable,payload,occurred_at_ms)
+         VALUES(?,?,?,?,?,?,?,?)`, input.subjectSessionId, eventSeq, input.eventId, input.type, input.schemaVersion, input.ignorable === true ? 1 : 0, payload, input.occurredAtMs);
+        }
+        catch (error) {
+            failSessionEvent('EVENT_STORAGE', 'event insert failed', error);
+        }
+        return Object.freeze({
+            eventId: input.eventId,
+            eventSeq,
+            type: input.type,
+            schemaVersion: input.schemaVersion,
+            subjectSessionId: input.subjectSessionId,
+            payload: new Uint8Array(payload),
+            occurredAtMs: input.occurredAtMs,
+            ignorable: input.ignorable === true,
+        });
+    };
+    const readInTransaction = (txInput, subjectSessionId, options) => {
+        const tx = requireTransaction(txInput);
+        requireSessionId(subjectSessionId);
+        const address = tx.query('SELECT 1 AS present FROM protocol_sessions WHERE session_id=?', subjectSessionId);
+        if (address.length === 0) {
+            failSessionEvent('EVENT_SESSION_UNKNOWN', `unknown protocol session: ${subjectSessionId}`);
+        }
+        const afterSequence = requireSequence(options.afterSequence, 'afterSequence', 0);
+        const atSequence = requireSequence(options.atSequence, 'atSequence', Number.MAX_SAFE_INTEGER);
+        if (atSequence < afterSequence) {
+            failSessionEvent('EVENT_SEQUENCE_INVALID', 'atSequence must not precede afterSequence');
+        }
+        const rows = tx.query(`SELECT ${SELECT_COLUMNS} FROM session_events
+       WHERE subject_session_id=? AND event_seq>? AND event_seq<=? ORDER BY event_seq`, subjectSessionId, afterSequence, atSequence);
+        const events = rows.map(eventFromRow);
+        for (let index = 0; index < events.length; index++) {
+            const expected = afterSequence + index + 1;
+            if (events[index].eventSeq !== expected) {
+                failSessionEvent('EVENT_SEQUENCE_INVALID', `subject ${subjectSessionId} has a sequence gap: expected ${expected}, found ${events[index].eventSeq}`);
+            }
+        }
+        return Object.freeze(events);
+    };
+    const hasMessageEvent = (txInput, subjectSessionId, messageId) => {
+        const tx = requireTransaction(txInput);
+        requireSubject(tx, subjectSessionId);
+        if (typeof messageId !== 'string' || messageId.length === 0)
+            return false;
+        // Message events are JSON envelopes. Keep the lookup in the event package so adopters do not scan and
+        // decode an entire session history merely to make a retry idempotent. json_valid makes malformed legacy
+        // payloads non-matching instead of turning a delivery check into a transaction failure.
+        return tx.query(`SELECT 1 AS present FROM session_events
+       WHERE subject_session_id=? AND event_type='session.message.sent.v1'
+         AND json_valid(CAST(payload AS TEXT))
+         AND json_extract(CAST(payload AS TEXT), '$.messageId')=? LIMIT 1`, subjectSessionId, messageId).length > 0;
+    };
+    const read = (subjectSessionId, options = {}, tx) => {
+        if (tx !== undefined)
+            return readInTransaction(tx, subjectSessionId, options);
+        return protocol.withTransaction(active => readInTransaction(active, subjectSessionId, options));
+    };
+    const replay = (subjectSessionId, options, tx) => {
+        if (!options || typeof options !== 'object' || !options.reducers || typeof options.reducers !== 'object') {
+            failSessionEvent('EVENT_TYPE_UNKNOWN', 'replay requires a reducer table');
+        }
+        let state = options.initialState;
+        for (const event of read(subjectSessionId, options, tx)) {
+            const reducer = Object.prototype.hasOwnProperty.call(options.reducers, event.type)
+                ? options.reducers[event.type]
+                : undefined;
+            if (typeof reducer !== 'function') {
+                if (event.ignorable)
+                    continue;
+                failSessionEvent('EVENT_TYPE_UNKNOWN', `required event type has no reducer: ${event.type}`);
+            }
+            state = reducer(state, event);
+        }
+        return state;
+    };
+    return Object.freeze({ append, hasMessageEvent, read, replay });
+}
+export { SessionEventError } from './errors.js';
+export { SESSION_EVENTS_MIGRATION_SQL, SESSION_EVENTS_MIGRATIONS } from './schema.js';

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

@@ -0,0 +1,3 @@
+import type { ComponentMigration } from '@spexcode/session-protocol';
+export declare const SESSION_EVENTS_MIGRATION_SQL = "\nCREATE TABLE session_events (\n  subject_session_id  TEXT    NOT NULL REFERENCES protocol_sessions(session_id),\n  event_seq           INTEGER NOT NULL,\n  event_id            TEXT    NOT NULL UNIQUE,\n  event_type          TEXT    NOT NULL,\n  schema_version      INTEGER NOT NULL,\n  ignorable           INTEGER NOT NULL,\n  payload              BLOB    NOT NULL,\n  occurred_at_ms      INTEGER NOT NULL,\n  PRIMARY KEY (subject_session_id, event_seq),\n  CHECK (event_seq >= 1),\n  CHECK (length(event_id) = 32 AND event_id NOT GLOB '*[^0-9a-f]*'),\n  CHECK (length(event_type) BETWEEN 1 AND 128),\n  CHECK (event_type NOT GLOB '*[^0-9A-Za-z._:-]*'),\n  CHECK (schema_version >= 1),\n  CHECK (ignorable IN (0, 1)),\n  CHECK (length(payload) <= 1048576),\n  CHECK (occurred_at_ms >= 0)\n) STRICT;\n\nCREATE INDEX session_events_subject_history\n  ON session_events (subject_session_id, event_seq);\n\nCREATE TRIGGER session_events_append_only_update\nBEFORE UPDATE ON session_events\nBEGIN\n  SELECT RAISE(ABORT, 'session_events is append-only');\nEND;\n\nCREATE TRIGGER session_events_append_only_delete\nBEFORE DELETE ON session_events\nBEGIN\n  SELECT RAISE(ABORT, 'session_events is append-only');\nEND;\n";
+export declare const SESSION_EVENTS_MIGRATIONS: readonly ComponentMigration[];

package/node_modules/@spexcode/session-events/dist/schema.js

@@ -0,0 +1,44 @@
+export const SESSION_EVENTS_MIGRATION_SQL = `
+CREATE TABLE session_events (
+  subject_session_id  TEXT    NOT NULL REFERENCES protocol_sessions(session_id),
+  event_seq           INTEGER NOT NULL,
+  event_id            TEXT    NOT NULL UNIQUE,
+  event_type          TEXT    NOT NULL,
+  schema_version      INTEGER NOT NULL,
+  ignorable           INTEGER NOT NULL,
+  payload              BLOB    NOT NULL,
+  occurred_at_ms      INTEGER NOT NULL,
+  PRIMARY KEY (subject_session_id, event_seq),
+  CHECK (event_seq >= 1),
+  CHECK (length(event_id) = 32 AND event_id NOT GLOB '*[^0-9a-f]*'),
+  CHECK (length(event_type) BETWEEN 1 AND 128),
+  CHECK (event_type NOT GLOB '*[^0-9A-Za-z._:-]*'),
+  CHECK (schema_version >= 1),
+  CHECK (ignorable IN (0, 1)),
+  CHECK (length(payload) <= 1048576),
+  CHECK (occurred_at_ms >= 0)
+) STRICT;
+
+CREATE INDEX session_events_subject_history
+  ON session_events (subject_session_id, event_seq);
+
+CREATE TRIGGER session_events_append_only_update
+BEFORE UPDATE ON session_events
+BEGIN
+  SELECT RAISE(ABORT, 'session_events is append-only');
+END;
+
+CREATE TRIGGER session_events_append_only_delete
+BEFORE DELETE ON session_events
+BEGIN
+  SELECT RAISE(ABORT, 'session_events is append-only');
+END;
+`;
+export const SESSION_EVENTS_MIGRATIONS = [
+    { version: 1, sql: SESSION_EVENTS_MIGRATION_SQL },
+    { version: 2, sql: `
+CREATE INDEX session_events_message_lookup
+  ON session_events (subject_session_id, event_type)
+  WHERE event_type = 'session.message.sent.v1';
+` },
+];

package/node_modules/@spexcode/session-events/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@spexcode/session-events",
+  "version": "0.7.0-next.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "description": "Append-only session facts and deterministic ordered replay inputs.",
+  "files": ["dist"],
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "build": "node ../../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../../scripts/release-publish.mjs --from-package-publish",
+    "test": "npm run build && tsx --import ../../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "dependencies": { "@spexcode/session-protocol": "0.7.0-next.0" },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

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

@@ -0,0 +1,36 @@
+import type { MessageInput } from './index.js';
+interface CanonicalMessage {
+    protocolVersion: number;
+    targetSessionId: string;
+    senderSessionId?: string | null;
+    kind: string;
+    headers?: Record<string, string>;
+    body: Uint8Array;
+}
+export interface NormalizedMessage {
+    protocolVersion: number;
+    targetSessionId: string;
+    senderSessionId: string | null;
+    kind: string;
+    headers: Record<string, string>;
+    headersJson: string;
+    body: Uint8Array;
+    idempotencyKey: string | null;
+    hash: Uint8Array;
+}
+export declare const PROTOCOL_VERSION = 1;
+export declare const LIMITS: {
+    readonly sessionId: 256;
+    readonly messageKind: 64;
+    readonly idempotencyKey: 256;
+    readonly headerKey: 64;
+    readonly headerValueBytes: 4096;
+    readonly headerCount: 64;
+    readonly headersJsonBytes: 65536;
+    readonly bodyBytes: 1048576;
+};
+export declare function canonicalPreimage(message: CanonicalMessage): Uint8Array;
+export declare function payloadHash(message: CanonicalMessage): Uint8Array;
+export declare function requireSessionId(value: unknown, label?: string): string;
+export declare function normalizeMessage(targetSessionId: string, input: MessageInput): NormalizedMessage;
+export {};

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

@@ -0,0 +1,139 @@
+import { createHash } from 'node:crypto';
+import { fail } from './errors.js';
+export const PROTOCOL_VERSION = 1;
+export const LIMITS = {
+    sessionId: 256,
+    messageKind: 64,
+    idempotencyKey: 256,
+    headerKey: 64,
+    headerValueBytes: 4096,
+    headerCount: 64,
+    headersJsonBytes: 65536,
+    bodyBytes: 1048576,
+};
+const SESSION_ID_RE = /^[0-9A-Za-z_][0-9A-Za-z_-]*$/;
+const KIND_RE = /^[0-9A-Za-z._-]+$/;
+const HEADER_KEY_RE = /^[0-9A-Za-z._-]+$/;
+const u32 = (value) => {
+    const bytes = Buffer.alloc(4);
+    bytes.writeUInt32BE(value);
+    return bytes;
+};
+const u64 = (value) => {
+    const bytes = Buffer.alloc(8);
+    bytes.writeBigUInt64BE(BigInt(value));
+    return bytes;
+};
+const field = (value) => {
+    const bytes = Buffer.from(value, 'utf8');
+    return Buffer.concat([u32(bytes.length), bytes]);
+};
+const optionalField = (value) => value === null || value === undefined
+    ? Buffer.from([0])
+    : Buffer.concat([Buffer.from([1]), field(value)]);
+const sortedHeaderKeys = (headers) => Object.keys(headers).sort((left, right) => Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8')));
+export function canonicalPreimage(message) {
+    const headers = message.headers ?? {};
+    const keys = sortedHeaderKeys(headers);
+    const body = Buffer.from(message.body);
+    return Buffer.concat([
+        u32(message.protocolVersion),
+        field(message.targetSessionId),
+        optionalField(message.senderSessionId ?? null),
+        field(message.kind),
+        u32(keys.length),
+        ...keys.flatMap(key => [field(key), field(headers[key])]),
+        u64(body.length),
+        body,
+    ]);
+}
+export function payloadHash(message) {
+    return createHash('sha256').update(canonicalPreimage(message)).digest();
+}
+export function requireSessionId(value, label = 'sessionId') {
+    if (typeof value !== 'string')
+        fail('PROTOCOL_SESSION_ID_INVALID', `${label} must be a string`);
+    if (value.length < 1 || value.length > LIMITS.sessionId) {
+        fail('PROTOCOL_SESSION_ID_INVALID', `${label} must be 1..${LIMITS.sessionId} characters`);
+    }
+    if (!SESSION_ID_RE.test(value)) {
+        fail('PROTOCOL_SESSION_ID_INVALID', `${label} must match [0-9A-Za-z_][0-9A-Za-z_-]* (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+export function normalizeMessage(targetSessionId, input) {
+    if (!input || typeof input !== 'object')
+        fail('PROTOCOL_MESSAGE_INVALID', 'message must be an object');
+    const record = input;
+    if ('messageId' in record) {
+        fail('PROTOCOL_MESSAGE_INVALID', 'messageId is generated by the protocol; producers must not supply one');
+    }
+    if ('targetSessionId' in record && record.targetSessionId !== targetSessionId) {
+        fail('PROTOCOL_MESSAGE_INVALID', 'targetSessionId must equal the enqueue address');
+    }
+    const protocolVersion = input.protocolVersion ?? PROTOCOL_VERSION;
+    if (!Number.isInteger(protocolVersion) || protocolVersion < 1 || protocolVersion > 0xffffffff) {
+        fail('PROTOCOL_MESSAGE_INVALID', 'protocolVersion must be a positive unsigned 32-bit integer');
+    }
+    const kind = input.kind;
+    if (typeof kind !== 'string'
+        || kind.length < 1
+        || kind.length > LIMITS.messageKind
+        || !KIND_RE.test(kind)) {
+        fail('PROTOCOL_MESSAGE_INVALID', `kind must match [0-9A-Za-z._-]{1,${LIMITS.messageKind}}`);
+    }
+    if (!(input.body instanceof Uint8Array)) {
+        fail('PROTOCOL_MESSAGE_INVALID', 'body must be a Uint8Array; encode strings before enqueue');
+    }
+    const body = Buffer.from(input.body);
+    if (body.length > LIMITS.bodyBytes) {
+        fail('PROTOCOL_MESSAGE_INVALID', `body exceeds ${LIMITS.bodyBytes} bytes`);
+    }
+    const senderSessionId = input.senderSessionId ?? null;
+    if (senderSessionId !== null)
+        requireSessionId(senderSessionId, 'senderSessionId');
+    const idempotencyKey = input.idempotencyKey ?? null;
+    if (idempotencyKey !== null
+        && (typeof idempotencyKey !== 'string'
+            || idempotencyKey.length < 1
+            || idempotencyKey.length > LIMITS.idempotencyKey)) {
+        fail('PROTOCOL_MESSAGE_INVALID', `idempotencyKey must be 1..${LIMITS.idempotencyKey} characters`);
+    }
+    const headersInput = input.headers ?? {};
+    const headerPrototype = typeof headersInput === 'object' && headersInput !== null
+        ? Object.getPrototypeOf(headersInput)
+        : undefined;
+    if (typeof headersInput !== 'object'
+        || headersInput === null
+        || Array.isArray(headersInput)
+        || (headerPrototype !== Object.prototype && headerPrototype !== null)) {
+        fail('PROTOCOL_MESSAGE_INVALID', 'headers must be a plain object');
+    }
+    const keys = Object.keys(headersInput);
+    if (keys.length > LIMITS.headerCount) {
+        fail('PROTOCOL_MESSAGE_INVALID', `at most ${LIMITS.headerCount} headers are allowed`);
+    }
+    for (const key of keys) {
+        if (key.length < 1 || key.length > LIMITS.headerKey || !HEADER_KEY_RE.test(key)) {
+            fail('PROTOCOL_MESSAGE_INVALID', `header key must match [0-9A-Za-z._-]{1,${LIMITS.headerKey}} (got ${JSON.stringify(key)})`);
+        }
+        const value = headersInput[key];
+        if (typeof value !== 'string')
+            fail('PROTOCOL_MESSAGE_INVALID', `header ${key} must be a string`);
+        if (Buffer.byteLength(value, 'utf8') > LIMITS.headerValueBytes) {
+            fail('PROTOCOL_MESSAGE_INVALID', `header ${key} exceeds ${LIMITS.headerValueBytes} bytes`);
+        }
+    }
+    const headers = Object.fromEntries(sortedHeaderKeys(headersInput).map(key => [key, headersInput[key]]));
+    const headersJson = JSON.stringify(headers);
+    if (Buffer.byteLength(headersJson, 'utf8') > LIMITS.headersJsonBytes) {
+        fail('PROTOCOL_MESSAGE_INVALID', `headers exceed ${LIMITS.headersJsonBytes} bytes`);
+    }
+    const envelope = { protocolVersion, targetSessionId, senderSessionId, kind, headers, body };
+    return {
+        ...envelope,
+        idempotencyKey,
+        headersJson,
+        hash: payloadHash(envelope),
+    };
+}

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

@@ -0,0 +1,22 @@
+import type { OpenOptions, SessionProtocol } from './index.js';
+export interface ProtocolInspection {
+    pragmas(): {
+        journal_mode: string;
+        foreign_keys: number;
+        synchronous: number;
+        busy_timeout: number;
+    };
+    counts(): {
+        sessions: number;
+        messages: number;
+    };
+    queryPlans(): {
+        dequeueHead: string;
+        listPending: string;
+        readMessages: string;
+        idempotencyLookup: string;
+    };
+}
+export declare function inspectProtocol(protocol: SessionProtocol): ProtocolInspection;
+export declare function isSupportedSqliteVersion(version: unknown): boolean;
+export declare function openProtocol(databasePath: string, options?: OpenOptions): SessionProtocol;