@spexcode/session-runtime 0.6.8

package/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/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/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/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/dist/schema.d.ts

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

package/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/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"
+  }
+}