spexcode 0.6.6 → 0.6.8

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

@@ -0,0 +1,192 @@
+import { createHash } from 'node:crypto';
+import { fail } from './errors.js';
+export const MIN_SQLITE_VERSION = '3.38.0';
+export const PROTOCOL_COMPONENT = 'session-protocol';
+export const PROTOCOL_MIGRATION_SQL = `
+CREATE TABLE protocol_sessions (
+  session_id     TEXT    NOT NULL PRIMARY KEY,
+  created_at_ms  INTEGER NOT NULL,
+  retired_at_ms  INTEGER,
+  CHECK (length(session_id) BETWEEN 1 AND 256),
+  CHECK (session_id NOT GLOB '*[^0-9A-Za-z_-]*'),
+  CHECK (session_id NOT GLOB '-*'),
+  CHECK (created_at_ms >= 0),
+  CHECK (retired_at_ms IS NULL OR retired_at_ms >= 0)
+) STRICT;
+
+CREATE TABLE protocol_messages (
+  enqueue_seq        INTEGER PRIMARY KEY AUTOINCREMENT,
+  message_id         TEXT    NOT NULL UNIQUE,
+  target_session_id  TEXT    NOT NULL REFERENCES protocol_sessions(session_id),
+  sender_session_id  TEXT,
+  protocol_version   INTEGER NOT NULL,
+  kind               TEXT    NOT NULL,
+  body               BLOB    NOT NULL,
+  headers_json       TEXT    NOT NULL,
+  idempotency_key    TEXT,
+  payload_hash       BLOB    NOT NULL,
+  enqueued_at_ms     INTEGER NOT NULL,
+  dequeued_at_ms     INTEGER,
+  CHECK (message_id GLOB '[0-9a-f]*' AND length(message_id) = 32),
+  CHECK (protocol_version >= 1),
+  CHECK (length(kind) BETWEEN 1 AND 64),
+  CHECK (kind NOT GLOB '*[^0-9A-Za-z._-]*'),
+  CHECK (length(body) <= 1048576),
+  CHECK (json_valid(headers_json) AND json_type(headers_json) = 'object'),
+  CHECK (length(CAST(headers_json AS BLOB)) <= 65536),
+  CHECK (idempotency_key IS NULL OR length(idempotency_key) BETWEEN 1 AND 256),
+  CHECK (length(payload_hash) = 32),
+  CHECK (enqueued_at_ms >= 0),
+  CHECK (dequeued_at_ms IS NULL OR dequeued_at_ms >= 0),
+  CHECK (sender_session_id IS NULL OR length(sender_session_id) BETWEEN 1 AND 256)
+) STRICT;
+
+CREATE UNIQUE INDEX protocol_messages_idempotency
+  ON protocol_messages (target_session_id, idempotency_key)
+  WHERE idempotency_key IS NOT NULL;
+
+CREATE INDEX protocol_messages_pending_fifo
+  ON protocol_messages (target_session_id, enqueue_seq)
+  WHERE dequeued_at_ms IS NULL;
+
+CREATE INDEX protocol_messages_history
+  ON protocol_messages (target_session_id, enqueue_seq);
+`;
+export const REGISTRY_SQL = `
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  component      TEXT    NOT NULL,
+  version        INTEGER NOT NULL,
+  checksum       TEXT    NOT NULL,
+  applied_at_ms  INTEGER NOT NULL,
+  PRIMARY KEY (component, version)
+) STRICT;
+`;
+const migrationChecksum = (sql) => createHash('sha256').update(Buffer.from(sql, 'utf8')).digest('hex');
+export const PROTOCOL_MIGRATIONS = [
+    { version: 1, sql: PROTOCOL_MIGRATION_SQL, checksum: migrationChecksum(PROTOCOL_MIGRATION_SQL) },
+];
+const targets = new WeakMap();
+export function registerMigrationTarget(protocol, target) {
+    targets.set(protocol, target);
+}
+function registryExists(database) {
+    return Boolean(database.prepare("SELECT 1 AS present FROM sqlite_master WHERE type='table' AND name='schema_migrations'").get());
+}
+function readApplied(database, component) {
+    if (!registryExists(database))
+        return null;
+    return database.prepare('SELECT version, checksum FROM schema_migrations WHERE component=? ORDER BY version').all(component).map(row => ({
+        version: Number(row.version),
+        checksum: String(row.checksum),
+    }));
+}
+function verifyApplied(component, applied, migrations) {
+    const highest = migrations.length;
+    if (applied.length > 0 && applied[applied.length - 1].version > highest) {
+        fail('PROTOCOL_SCHEMA_GENERATION_UNSUPPORTED', `${component} carries schema generation ${applied[applied.length - 1].version}; this build understands ${highest}`);
+    }
+    for (let index = 0; index < applied.length; index++) {
+        if (applied[index].version !== index + 1) {
+            fail('PROTOCOL_SCHEMA_GENERATION_UNSUPPORTED', `${component} migration sequence has a gap at version ${index + 1}`);
+        }
+        if (applied[index].checksum !== migrations[index].checksum) {
+            fail('PROTOCOL_SCHEMA_CHECKSUM_MISMATCH', `${component} migration ${applied[index].version} was rewritten after it was applied`);
+        }
+    }
+    return applied.length;
+}
+function prepareMigrations(migrations) {
+    if (!Array.isArray(migrations)) {
+        fail('PROTOCOL_SCHEMA_GENERATION_UNSUPPORTED', 'migrations must be an array');
+    }
+    return migrations.map((migration, index) => {
+        if (!migration
+            || typeof migration !== 'object'
+            || migration.version !== index + 1
+            || typeof migration.sql !== 'string') {
+            fail('PROTOCOL_SCHEMA_GENERATION_UNSUPPORTED', `migration versions must be contiguous from 1; invalid entry at ${index + 1}`);
+        }
+        return { ...migration, checksum: migrationChecksum(migration.sql) };
+    });
+}
+function validTimestamp(now) {
+    const value = now();
+    if (!Number.isSafeInteger(value) || value < 0) {
+        fail('PROTOCOL_SQLITE_ERROR', 'now() must return a non-negative safe integer');
+    }
+    return value;
+}
+function applyPending(database, component, migrations, done, now) {
+    const insert = database.prepare('INSERT INTO schema_migrations(component,version,checksum,applied_at_ms) VALUES(?,?,?,?)');
+    for (const migration of migrations.slice(done)) {
+        database.exec(migration.sql);
+        insert.run(component, migration.version, migration.checksum, validTimestamp(now));
+    }
+}
+function inImmediateTransaction(database, body) {
+    database.exec('BEGIN IMMEDIATE');
+    try {
+        const value = body();
+        database.exec('COMMIT');
+        return value;
+    }
+    catch (error) {
+        try {
+            database.exec('ROLLBACK');
+        }
+        catch { }
+        throw error;
+    }
+}
+const protocolObjectsExist = (database) => Boolean(database.prepare("SELECT 1 AS present FROM sqlite_master WHERE type='table' AND name='protocol_sessions'").get());
+export function migrateProtocol(database, readOnly, now) {
+    const applied = readApplied(database, PROTOCOL_COMPONENT);
+    if (readOnly) {
+        if (applied === null || applied.length !== PROTOCOL_MIGRATIONS.length) {
+            fail('PROTOCOL_SCHEMA_GENERATION_UNSUPPORTED', 'read-only database is not migrated to this schema generation');
+        }
+        return verifyApplied(PROTOCOL_COMPONENT, applied, PROTOCOL_MIGRATIONS);
+    }
+    if (applied !== null && verifyApplied(PROTOCOL_COMPONENT, applied, PROTOCOL_MIGRATIONS) === PROTOCOL_MIGRATIONS.length) {
+        return PROTOCOL_MIGRATIONS.length;
+    }
+    return inImmediateTransaction(database, () => {
+        database.exec(REGISTRY_SQL);
+        const done = verifyApplied(PROTOCOL_COMPONENT, readApplied(database, PROTOCOL_COMPONENT) ?? [], PROTOCOL_MIGRATIONS);
+        if (done === 0 && protocolObjectsExist(database)) {
+            fail('PROTOCOL_SCHEMA_REGISTRY_INCONSISTENT', 'protocol tables exist but schema_migrations does not account for them');
+        }
+        applyPending(database, PROTOCOL_COMPONENT, PROTOCOL_MIGRATIONS, done, now);
+        return PROTOCOL_MIGRATIONS.length;
+    });
+}
+export function migrateComponent(database, component, migrations, now) {
+    const prepared = prepareMigrations(migrations);
+    const applied = readApplied(database, component);
+    if (applied !== null && verifyApplied(component, applied, prepared) === prepared.length) {
+        return prepared.length;
+    }
+    return inImmediateTransaction(database, () => {
+        database.exec(REGISTRY_SQL);
+        const done = verifyApplied(component, readApplied(database, component) ?? [], prepared);
+        applyPending(database, component, prepared, done, now);
+        return prepared.length;
+    });
+}
+function invalidComponent(message) {
+    fail('PROTOCOL_TRANSACTION_INVALID', message);
+}
+export function applyComponentMigrations(protocol, component, migrations) {
+    if (typeof component !== 'string' || !/^[0-9A-Za-z._-]{1,64}$/.test(component)) {
+        invalidComponent('component must match [0-9A-Za-z._-]{1,64}');
+    }
+    if (component === PROTOCOL_COMPONENT) {
+        invalidComponent('session-protocol migrations are owned by openProtocol');
+    }
+    const target = targets.get(protocol);
+    if (!target)
+        invalidComponent('protocol must be a live handle returned by openProtocol');
+    if (target.readOnly)
+        fail('PROTOCOL_DATABASE_READONLY', 'component migrations require a writable handle');
+    return target.apply(component, migrations);
+}

package/node_modules/@spexcode/{session-core → session-protocol}/package.json

@@ -1,14 +1,13 @@
 {
-  "name": "@spexcode/session-core",
-  "version": "0.6.6",
+  "name": "@spexcode/session-protocol",
+  "version": "0.6.8",
   "type": "module",
-  "description": "SpexCode's durable file-based session communication protocol.",
+  "description": "A durable SQLite session message protocol.",
   "files": [
     "dist"
   ],
   "exports": {
     ".": "./dist/index.js",
-    "./internal": "./dist/internal.js",
     "./package.json": "./package.json"
   },
   "engines": {
@@ -20,10 +19,7 @@
   "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 && node --test scripts/public-boundary.test.mjs"
-  },
-  "dependencies": {
-    "@spexcode/spec-core": "0.6.6"
+    "test": "npm run build && tsx --import ../../scripts/test-home.mjs --test src/*.test.ts"
   },
   "devDependencies": {
     "@types/node": "^20.16.0",

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

@@ -0,0 +1,6 @@
+export type RuntimeBindingErrorCode = 'RUNTIME_BINDING_TRANSACTION_INVALID' | 'RUNTIME_BINDING_NAMESPACE_INVALID' | 'RUNTIME_BINDING_SESSION_ID_INVALID' | 'RUNTIME_BINDING_SESSION_UNKNOWN' | 'RUNTIME_BINDING_SESSION_RETIRED' | 'RUNTIME_BINDING_IDENTITY_INVALID' | 'RUNTIME_BINDING_METADATA_INVALID' | 'RUNTIME_BINDING_GENERATION_REQUIRED' | 'RUNTIME_BINDING_GENERATION_STALE' | 'RUNTIME_BINDING_NOT_FOUND' | 'RUNTIME_BINDING_NOT_BOUND' | 'RUNTIME_BINDING_STORAGE';
+export declare class RuntimeBindingError extends Error {
+    readonly code: RuntimeBindingErrorCode;
+    constructor(code: RuntimeBindingErrorCode, message: string, cause?: unknown);
+}
+export declare function failRuntimeBinding(code: RuntimeBindingErrorCode, message: string, cause?: unknown): never;

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

@@ -0,0 +1,11 @@
+export class RuntimeBindingError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, { cause });
+        this.name = 'RuntimeBindingError';
+        this.code = code;
+    }
+}
+export function failRuntimeBinding(code, message, cause) {
+    throw new RuntimeBindingError(code, message, cause);
+}

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

@@ -0,0 +1,33 @@
+import type { ProtocolTransaction, SessionProtocol } from '@spexcode/session-protocol';
+import { RuntimeBindingError } from './errors.js';
+export interface RuntimeIdentity {
+    namespace: string;
+    runtimeKind: string;
+    nativeSessionId: string;
+    nativeStartToken: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RuntimeBinding {
+    namespace: string;
+    protocolSessionId: string;
+    runtimeKind: string;
+    nativeSessionId: string;
+    nativeStartToken: string;
+    bindingGeneration: number;
+    status: 'bound' | 'unbound';
+    boundAtMs: number;
+    unboundAtMs: number | null;
+    metadata: Record<string, unknown>;
+}
+export interface BindingOptions {
+    expectedGeneration?: number;
+    now?: number;
+}
+export interface SessionRuntimeBindings {
+    bind(tx: ProtocolTransaction, protocolSessionId: string, identity: RuntimeIdentity, options?: BindingOptions): RuntimeBinding;
+    unbind(tx: ProtocolTransaction, namespace: string, protocolSessionId: string, options?: BindingOptions): RuntimeBinding;
+    resolve(namespace: string, protocolSessionId: string, tx?: ProtocolTransaction): RuntimeBinding | null;
+}
+export declare function openRuntimeBindings(protocol: SessionProtocol): SessionRuntimeBindings;
+export { RuntimeBindingError };
+export type { RuntimeBindingErrorCode } from './errors.js';

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

@@ -0,0 +1,193 @@
+import { applyComponentMigrations } from '@spexcode/session-protocol';
+import { failRuntimeBinding, RuntimeBindingError } from './errors.js';
+import { RUNTIME_BINDINGS_MIGRATIONS } from './schema.js';
+const NAMESPACE = /^[0-9A-Za-z._:/-]{1,128}$/;
+const SESSION_ID = /^(?!-)[0-9A-Za-z_-]{1,256}$/;
+const RUNTIME_KIND = /^[0-9A-Za-z._:-]{1,64}$/;
+const MAX_METADATA_BYTES = 8192;
+const SELECT_COLUMNS = `namespace, protocol_session_id, runtime_kind, native_session_id,
+  native_start_token, binding_generation, status, bound_at_ms, unbound_at_ms, metadata_json`;
+export function openRuntimeBindings(protocol) {
+    applyComponentMigrations(protocol, 'session-runtime-bindings', RUNTIME_BINDINGS_MIGRATIONS);
+    const requireTransaction = (tx) => {
+        if (!tx || typeof tx.exec !== 'function' || typeof tx.query !== 'function') {
+            failRuntimeBinding('RUNTIME_BINDING_TRANSACTION_INVALID', 'a live protocol transaction context is required');
+        }
+        return tx;
+    };
+    const requireNamespace = (namespace) => {
+        if (typeof namespace !== 'string' || !NAMESPACE.test(namespace)) {
+            failRuntimeBinding('RUNTIME_BINDING_NAMESPACE_INVALID', 'namespace has an invalid grammar');
+        }
+    };
+    const requireSessionId = (sessionId) => {
+        if (typeof sessionId !== 'string' || !SESSION_ID.test(sessionId)) {
+            failRuntimeBinding('RUNTIME_BINDING_SESSION_ID_INVALID', 'protocol session id has an invalid grammar');
+        }
+    };
+    const requireIdentity = (identity) => {
+        if (!identity || typeof identity !== 'object') {
+            failRuntimeBinding('RUNTIME_BINDING_IDENTITY_INVALID', 'runtime identity must be an object');
+        }
+        requireNamespace(identity.namespace);
+        if (typeof identity.runtimeKind !== 'string' || !RUNTIME_KIND.test(identity.runtimeKind)) {
+            failRuntimeBinding('RUNTIME_BINDING_IDENTITY_INVALID', 'runtime kind has an invalid grammar');
+        }
+        if (typeof identity.nativeSessionId !== 'string' || identity.nativeSessionId.length < 1 || identity.nativeSessionId.length > 512) {
+            failRuntimeBinding('RUNTIME_BINDING_IDENTITY_INVALID', 'native session id must be nonempty and bounded');
+        }
+        if (typeof identity.nativeStartToken !== 'string' || identity.nativeStartToken.length < 1 || identity.nativeStartToken.length > 512) {
+            failRuntimeBinding('RUNTIME_BINDING_IDENTITY_INVALID', 'native start token must be nonempty and bounded');
+        }
+        const metadata = identity.metadata ?? {};
+        if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+            failRuntimeBinding('RUNTIME_BINDING_METADATA_INVALID', 'metadata must be a JSON object');
+        }
+        let encoded;
+        try {
+            encoded = JSON.stringify(metadata);
+        }
+        catch (error) {
+            failRuntimeBinding('RUNTIME_BINDING_METADATA_INVALID', 'metadata must be JSON serializable', error);
+        }
+        if (encoded === undefined || Buffer.byteLength(encoded, 'utf8') > MAX_METADATA_BYTES) {
+            failRuntimeBinding('RUNTIME_BINDING_METADATA_INVALID', 'metadata exceeds the 8192-byte limit');
+        }
+        try {
+            const roundTrip = JSON.parse(encoded);
+            if (!roundTrip || typeof roundTrip !== 'object' || Array.isArray(roundTrip)) {
+                failRuntimeBinding('RUNTIME_BINDING_METADATA_INVALID', 'metadata must round-trip as an object');
+            }
+        }
+        catch (error) {
+            failRuntimeBinding('RUNTIME_BINDING_METADATA_INVALID', 'metadata must be valid JSON', error);
+        }
+        return encoded;
+    };
+    const requireNow = (now) => {
+        const value = now ?? Date.now();
+        if (!Number.isSafeInteger(value) || value < 0) {
+            failRuntimeBinding('RUNTIME_BINDING_IDENTITY_INVALID', 'timestamp must be a non-negative safe integer');
+        }
+        return value;
+    };
+    const addressState = (tx, sessionId) => {
+        const rows = tx.query('SELECT retired_at_ms FROM protocol_sessions WHERE session_id=?', sessionId);
+        if (rows.length === 0)
+            failRuntimeBinding('RUNTIME_BINDING_SESSION_UNKNOWN', `unknown protocol session: ${sessionId}`);
+        return rows[0].retired_at_ms === null ? 'active' : 'retired';
+    };
+    const rowToBinding = (row) => {
+        let metadata;
+        try {
+            metadata = JSON.parse(row.metadata_json);
+        }
+        catch (error) {
+            failRuntimeBinding('RUNTIME_BINDING_STORAGE', 'stored metadata is not valid JSON', error);
+        }
+        if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+            failRuntimeBinding('RUNTIME_BINDING_STORAGE', 'stored metadata is not a JSON object');
+        }
+        return {
+            namespace: String(row.namespace),
+            protocolSessionId: String(row.protocol_session_id),
+            runtimeKind: String(row.runtime_kind),
+            nativeSessionId: String(row.native_session_id),
+            nativeStartToken: String(row.native_start_token),
+            bindingGeneration: Number(row.binding_generation),
+            status: row.status,
+            boundAtMs: Number(row.bound_at_ms),
+            unboundAtMs: row.unbound_at_ms === null ? null : Number(row.unbound_at_ms),
+            metadata: metadata,
+        };
+    };
+    const read = (tx, namespace, sessionId) => {
+        const rows = tx.query(`SELECT ${SELECT_COLUMNS} FROM session_runtime_bindings WHERE namespace=? AND protocol_session_id=?`, namespace, sessionId);
+        return rows.length === 0 ? null : rowToBinding(rows[0]);
+    };
+    const checkGeneration = (existing, expectedGeneration) => {
+        if (!existing) {
+            if (expectedGeneration !== undefined) {
+                failRuntimeBinding('RUNTIME_BINDING_GENERATION_STALE', 'expected generation has no binding to match');
+            }
+            return;
+        }
+        if (expectedGeneration === undefined) {
+            failRuntimeBinding('RUNTIME_BINDING_GENERATION_REQUIRED', 'expected generation is required for an existing binding');
+        }
+        if (!Number.isSafeInteger(expectedGeneration) || expectedGeneration !== existing.bindingGeneration) {
+            failRuntimeBinding('RUNTIME_BINDING_GENERATION_STALE', 'binding generation is stale');
+        }
+    };
+    const bind = (txInput, protocolSessionId, identity, options = {}) => {
+        const tx = requireTransaction(txInput);
+        requireSessionId(protocolSessionId);
+        const metadataJson = requireIdentity(identity);
+        if (addressState(tx, protocolSessionId) === 'retired') {
+            failRuntimeBinding('RUNTIME_BINDING_SESSION_RETIRED', `protocol session is retired: ${protocolSessionId}`);
+        }
+        const existing = read(tx, identity.namespace, protocolSessionId);
+        checkGeneration(existing, options.expectedGeneration);
+        const generation = existing ? existing.bindingGeneration + 1 : 1;
+        const now = requireNow(options.now);
+        try {
+            if (existing) {
+                tx.exec(`UPDATE session_runtime_bindings SET runtime_kind=?, native_session_id=?, native_start_token=?,
+             binding_generation=?, status='bound', bound_at_ms=?, unbound_at_ms=NULL, metadata_json=?
+           WHERE namespace=? AND protocol_session_id=?`, identity.runtimeKind, identity.nativeSessionId, identity.nativeStartToken, generation, now, metadataJson, identity.namespace, protocolSessionId);
+            }
+            else {
+                tx.exec(`INSERT INTO session_runtime_bindings
+             (namespace, protocol_session_id, runtime_kind, native_session_id, native_start_token,
+              binding_generation, status, bound_at_ms, unbound_at_ms, metadata_json)
+           VALUES (?,?,?,?,?,?, 'bound', ?, NULL, ?)`, identity.namespace, protocolSessionId, identity.runtimeKind, identity.nativeSessionId, identity.nativeStartToken, generation, now, metadataJson);
+            }
+        }
+        catch (error) {
+            if (error instanceof RuntimeBindingError)
+                throw error;
+            failRuntimeBinding('RUNTIME_BINDING_STORAGE', 'failed to persist runtime binding', error);
+        }
+        const result = read(tx, identity.namespace, protocolSessionId);
+        if (!result)
+            failRuntimeBinding('RUNTIME_BINDING_STORAGE', 'binding disappeared after bind');
+        return result;
+    };
+    const unbind = (txInput, namespace, protocolSessionId, options = {}) => {
+        const tx = requireTransaction(txInput);
+        requireNamespace(namespace);
+        requireSessionId(protocolSessionId);
+        if (addressState(tx, protocolSessionId) === 'retired') {
+            failRuntimeBinding('RUNTIME_BINDING_SESSION_RETIRED', `protocol session is retired: ${protocolSessionId}`);
+        }
+        const existing = read(tx, namespace, protocolSessionId);
+        if (!existing)
+            failRuntimeBinding('RUNTIME_BINDING_NOT_FOUND', 'runtime binding does not exist');
+        checkGeneration(existing, options.expectedGeneration);
+        if (existing.status !== 'bound')
+            failRuntimeBinding('RUNTIME_BINDING_NOT_BOUND', 'runtime binding is already unbound');
+        const now = requireNow(options.now);
+        try {
+            tx.exec(`UPDATE session_runtime_bindings SET status='unbound', binding_generation=?, unbound_at_ms=?
+         WHERE namespace=? AND protocol_session_id=? AND binding_generation=?`, existing.bindingGeneration + 1, now, namespace, protocolSessionId, existing.bindingGeneration);
+        }
+        catch (error) {
+            if (error instanceof RuntimeBindingError)
+                throw error;
+            failRuntimeBinding('RUNTIME_BINDING_STORAGE', 'failed to persist runtime unbinding', error);
+        }
+        const result = read(tx, namespace, protocolSessionId);
+        if (!result)
+            failRuntimeBinding('RUNTIME_BINDING_STORAGE', 'binding disappeared after unbind');
+        return result;
+    };
+    const resolve = (namespace, protocolSessionId, txInput) => {
+        requireNamespace(namespace);
+        requireSessionId(protocolSessionId);
+        if (txInput)
+            return read(requireTransaction(txInput), namespace, protocolSessionId);
+        return protocol.withTransaction(tx => read(tx, namespace, protocolSessionId));
+    };
+    return { bind, unbind, resolve };
+}
+export { RuntimeBindingError };

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

@@ -0,0 +1,2 @@
+import type { ComponentMigration } from '@spexcode/session-protocol';
+export declare const RUNTIME_BINDINGS_MIGRATIONS: readonly ComponentMigration[];

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

@@ -0,0 +1,37 @@
+export const RUNTIME_BINDINGS_MIGRATIONS = [
+    {
+        version: 1,
+        sql: `
+CREATE TABLE session_runtime_bindings (
+  namespace             TEXT    NOT NULL,
+  protocol_session_id   TEXT    NOT NULL REFERENCES protocol_sessions(session_id),
+  runtime_kind          TEXT    NOT NULL,
+  native_session_id     TEXT    NOT NULL,
+  native_start_token    TEXT    NOT NULL,
+  binding_generation    INTEGER NOT NULL,
+  status                TEXT    NOT NULL,
+  bound_at_ms           INTEGER NOT NULL,
+  unbound_at_ms         INTEGER,
+  metadata_json         TEXT    NOT NULL,
+  PRIMARY KEY (namespace, protocol_session_id),
+  CHECK (length(namespace) BETWEEN 1 AND 128),
+  CHECK (namespace NOT GLOB '*[^0-9A-Za-z._:/-]*'),
+  CHECK (length(runtime_kind) BETWEEN 1 AND 64),
+  CHECK (runtime_kind NOT GLOB '*[^0-9A-Za-z._:-]*'),
+  CHECK (length(native_session_id) BETWEEN 1 AND 512),
+  CHECK (length(native_start_token) BETWEEN 1 AND 512),
+  CHECK (binding_generation >= 1),
+  CHECK (status IN ('bound', 'unbound')),
+  CHECK (bound_at_ms >= 0),
+  CHECK (unbound_at_ms IS NULL OR unbound_at_ms >= bound_at_ms),
+  CHECK (json_valid(metadata_json) AND json_type(metadata_json) = 'object'),
+  CHECK (length(metadata_json) <= 8192),
+  CHECK ((status = 'bound' AND unbound_at_ms IS NULL)
+      OR (status = 'unbound' AND unbound_at_ms IS NOT NULL))
+) STRICT;
+
+CREATE INDEX session_runtime_bindings_native
+  ON session_runtime_bindings (runtime_kind, native_session_id, status);
+`,
+    },
+];

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

@@ -0,0 +1,24 @@
+{
+  "name": "@spexcode/session-runtime",
+  "version": "0.6.8",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "description": "Adopter-owned bindings between protocol addresses and native runtime identities.",
+  "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.6.8" },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/node_modules/@spexcode/session-selflaunch/bin/spex-session.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from '../dist/cli.js'
+
+process.exitCode = await runCli()

package/node_modules/@spexcode/session-selflaunch/dist/cli.d.ts

@@ -0,0 +1,25 @@
+import type { SessionProtocol } from '@spexcode/session-protocol';
+import type { SelfLaunchEnvironment } from './path.js';
+type CommandName = 'initialize' | 'enqueue' | 'dequeue' | 'pending';
+interface ParsedCommand {
+    readonly command: CommandName;
+    readonly values: ReadonlyMap<string, string>;
+    readonly headers: readonly [string, string][];
+    readonly assumeLocal: boolean;
+}
+export declare function parseCommand(argv: readonly string[]): ParsedCommand;
+interface CliDependencies {
+    readonly open: (databasePath: string) => SessionProtocol;
+    readonly requireLocal: (databasePath: string, options: {
+        assumeLocal?: boolean;
+    }) => string;
+}
+export interface CliRunOptions {
+    readonly argv?: readonly string[];
+    readonly env?: SelfLaunchEnvironment;
+    readonly stdout?: (text: string) => void;
+    readonly stderr?: (text: string) => void;
+    readonly dependencies?: CliDependencies;
+}
+export declare function runCli(options?: CliRunOptions): Promise<number>;
+export {};