spexcode 0.6.6 → 0.6.8

package/node_modules/@spexcode/session-selflaunch/dist/cli.js

@@ -0,0 +1,156 @@
+import { LocalityError, requireLocalDatabasePath } from './locality.js';
+import { DatabasePathError, resolveDatabasePath } from './path.js';
+class UsageError extends Error {
+    code = 'USAGE';
+}
+const VALUE_FLAGS = {
+    initialize: new Set(['session-id', 'database-path']),
+    enqueue: new Set(['session-id', 'kind', 'body', 'sender-session-id', 'idempotency-key', 'database-path']),
+    dequeue: new Set(['session-id', 'database-path']),
+    pending: new Set(['session-id', 'database-path']),
+};
+const usage = () => {
+    throw new UsageError('usage: spex-session initialize|enqueue|dequeue|pending --session-id ID [command options]');
+};
+const isCommandName = (value) => (value === 'initialize' || value === 'enqueue' || value === 'dequeue' || value === 'pending');
+export function parseCommand(argv) {
+    const command = argv[0];
+    if (!isCommandName(command))
+        return usage();
+    const commandName = command;
+    const values = new Map();
+    const headers = [];
+    let assumeLocal = false;
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--assume-local-storage') {
+            if (assumeLocal)
+                throw new UsageError('duplicate --assume-local-storage');
+            assumeLocal = true;
+            continue;
+        }
+        if (!token.startsWith('--'))
+            throw new UsageError(`unexpected argument ${token}`);
+        const name = token.slice(2);
+        if (name === 'header' && commandName === 'enqueue') {
+            const raw = argv[++index];
+            if (raw === undefined)
+                throw new UsageError('missing value for --header');
+            const separator = raw.indexOf('=');
+            if (separator <= 0)
+                throw new UsageError('--header must be K=V');
+            headers.push([raw.slice(0, separator), raw.slice(separator + 1)]);
+            continue;
+        }
+        if (!VALUE_FLAGS[commandName].has(name))
+            throw new UsageError(`unknown option --${name}`);
+        if (values.has(name))
+            throw new UsageError(`duplicate --${name}`);
+        const value = argv[++index];
+        if (value === undefined)
+            throw new UsageError(`missing value for --${name}`);
+        values.set(name, value);
+    }
+    if (!values.has('session-id'))
+        throw new UsageError('missing --session-id');
+    if (commandName === 'enqueue' && !values.has('kind'))
+        throw new UsageError('missing --kind');
+    if (commandName === 'enqueue' && !values.has('body'))
+        throw new UsageError('missing --body');
+    return { command: commandName, values, headers, assumeLocal };
+}
+const renderMessage = (message) => {
+    const { body, ...fields } = message;
+    return { ...fields, bodyBase64: Buffer.from(body).toString('base64') };
+};
+const errorCode = (error) => {
+    if (error instanceof UsageError)
+        return error.code;
+    if (error instanceof DatabasePathError)
+        return error.code;
+    if (error instanceof LocalityError)
+        return error.code;
+    if (typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && typeof error.code === 'string'
+        && error.code.startsWith('PROTOCOL_'))
+        return error.code;
+    return 'INTERNAL';
+};
+const SQLITE_EXPERIMENTAL_WARNING = 'SQLite is an experimental feature and might change at any time';
+// @@@node-sqlite-warning - Node 22 emits this during import; suppress only that exact warning so the
+// CLI's stderr remains its frozen single line while every unrelated warning keeps its normal path.
+const loadOpenProtocol = async () => {
+    const originalEmitWarning = process.emitWarning;
+    process.emitWarning = ((warning, ...args) => {
+        const message = warning instanceof Error ? warning.message : warning;
+        if (message === SQLITE_EXPERIMENTAL_WARNING)
+            return;
+        Reflect.apply(originalEmitWarning, process, [warning, ...args]);
+    });
+    try {
+        return (await import('@spexcode/session-protocol')).openProtocol;
+    }
+    finally {
+        process.emitWarning = originalEmitWarning;
+    }
+};
+export async function runCli(options = {}) {
+    const stdout = options.stdout ?? (text => process.stdout.write(text));
+    const stderr = options.stderr ?? (text => process.stderr.write(text));
+    let protocol;
+    try {
+        const parsed = parseCommand(options.argv ?? process.argv.slice(2));
+        const databasePath = resolveDatabasePath({
+            databasePath: parsed.values.get('database-path'),
+            env: options.env,
+        });
+        const dependencies = options.dependencies ?? {
+            open: await loadOpenProtocol(),
+            requireLocal: requireLocalDatabasePath,
+        };
+        dependencies.requireLocal(databasePath, { assumeLocal: parsed.assumeLocal });
+        protocol = dependencies.open(databasePath);
+        const sessionId = parsed.values.get('session-id');
+        let result;
+        if (parsed.command === 'initialize') {
+            result = protocol.initialize(sessionId);
+        }
+        else if (parsed.command === 'enqueue') {
+            const headers = Object.fromEntries(parsed.headers);
+            result = renderMessage(protocol.enqueue(sessionId, {
+                kind: parsed.values.get('kind'),
+                body: Buffer.from(parsed.values.get('body'), 'utf8'),
+                ...(parsed.values.has('sender-session-id')
+                    ? { senderSessionId: parsed.values.get('sender-session-id') }
+                    : {}),
+                ...(parsed.values.has('idempotency-key')
+                    ? { idempotencyKey: parsed.values.get('idempotency-key') }
+                    : {}),
+                ...(parsed.headers.length > 0 ? { headers } : {}),
+            }));
+        }
+        else if (parsed.command === 'dequeue') {
+            const message = protocol.dequeue(sessionId);
+            result = message === null ? null : renderMessage(message);
+        }
+        else {
+            result = protocol.listPending(sessionId).map(renderMessage);
+        }
+        stdout(`${JSON.stringify(result)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const code = errorCode(error);
+        const message = error instanceof Error ? error.message : String(error);
+        const repair = code === 'PROTOCOL_PATH_PARENT_MISSING'
+            ? '; create the parent directory or choose --database-path with an existing parent'
+            : '';
+        stderr(`spex-session: ${code}: ${message}${repair}\n`);
+        return code === 'USAGE' ? 2 : 1;
+    }
+    finally {
+        protocol?.close();
+    }
+}

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

@@ -0,0 +1,28 @@
+export { LocalityError, requireLocalDatabasePath } from './locality.js';
+export type { LocalityRefusalCode } from './locality.js';
+export { resolveDatabasePath } from './path.js';
+export type { ResolveDatabasePathOptions, SelfLaunchEnvironment } from './path.js';
+import type { ProtocolTransaction } from '@spexcode/session-protocol';
+import { type BindingOptions, type RuntimeBinding } from '@spexcode/session-runtime';
+/**
+ * Native identity supplied by the harness adapter that owns this self-launch.
+ * The CLI session id is deliberately not accepted as a native identity.
+ */
+export interface SelfLaunchRuntimeIdentity {
+    nativeSessionId: string;
+    nativeStartToken: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SelfLaunchProtocol {
+    withTransaction<T>(body: (tx: ProtocolTransaction) => T): T;
+}
+export interface SelfLaunchBindingOptions extends BindingOptions {
+    runtimeKind?: string;
+}
+/**
+ * Attach a caller-owned native harness identity to an existing protocol address.
+ * This is the only self-launch/runtime seam; it does not launch, probe, or stop a harness.
+ */
+export declare function bindSelfLaunchRuntime(protocol: SelfLaunchProtocol, protocolSessionId: string, identity: SelfLaunchRuntimeIdentity, options?: SelfLaunchBindingOptions): RuntimeBinding;
+export declare function resolveSelfLaunchRuntime(protocol: SelfLaunchProtocol, protocolSessionId: string): RuntimeBinding | null;
+export declare function unbindSelfLaunchRuntime(protocol: SelfLaunchProtocol, protocolSessionId: string, options?: BindingOptions): RuntimeBinding;

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

@@ -0,0 +1,25 @@
+export { LocalityError, requireLocalDatabasePath } from './locality.js';
+export { resolveDatabasePath } from './path.js';
+import { openRuntimeBindings, } from '@spexcode/session-runtime';
+const SELF_LAUNCH_NAMESPACE = 'self-launch';
+/**
+ * Attach a caller-owned native harness identity to an existing protocol address.
+ * This is the only self-launch/runtime seam; it does not launch, probe, or stop a harness.
+ */
+export function bindSelfLaunchRuntime(protocol, protocolSessionId, identity, options = {}) {
+    const bindings = openRuntimeBindings(protocol);
+    return protocol.withTransaction(tx => bindings.bind(tx, protocolSessionId, {
+        namespace: SELF_LAUNCH_NAMESPACE,
+        runtimeKind: options.runtimeKind ?? 'self-launch',
+        nativeSessionId: identity.nativeSessionId,
+        nativeStartToken: identity.nativeStartToken,
+        metadata: identity.metadata,
+    }, options));
+}
+export function resolveSelfLaunchRuntime(protocol, protocolSessionId) {
+    return openRuntimeBindings(protocol).resolve(SELF_LAUNCH_NAMESPACE, protocolSessionId);
+}
+export function unbindSelfLaunchRuntime(protocol, protocolSessionId, options = {}) {
+    const bindings = openRuntimeBindings(protocol);
+    return protocol.withTransaction(tx => bindings.unbind(tx, SELF_LAUNCH_NAMESPACE, protocolSessionId, options));
+}

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

@@ -0,0 +1,20 @@
+export type LocalityRefusalCode = 'LOCALITY_NETWORK_FILESYSTEM' | 'LOCALITY_UNDETERMINED' | 'LOCALITY_DETECTOR_UNAVAILABLE' | 'LOCALITY_PROBE_FAILED';
+export declare class LocalityError extends Error {
+    readonly code: LocalityRefusalCode;
+    constructor(code: LocalityRefusalCode, message: string, cause?: unknown);
+}
+export interface FilesystemClassification {
+    readonly locality: 'local' | 'network' | 'undetermined';
+    readonly name: string;
+}
+export declare function classifyFilesystemType(type: number | bigint): FilesystemClassification;
+export interface LocalityDetector {
+    readonly platform: string;
+    statfsType(parentPath: string): number | bigint;
+}
+export declare function requireLocalDatabasePathWithDetector(databasePath: string, options: {
+    assumeLocal?: boolean;
+}, detector: LocalityDetector): string;
+export declare function requireLocalDatabasePath(databasePath: string, options?: {
+    assumeLocal?: boolean;
+}): string;

package/node_modules/@spexcode/session-selflaunch/dist/locality.js

@@ -0,0 +1,83 @@
+import { statfsSync } from 'node:fs';
+import { isAbsolute, dirname } from 'node:path';
+import { DatabasePathError } from './path.js';
+export class LocalityError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'LocalityError';
+        this.code = code;
+    }
+}
+// @@@network-magic-evidence - These header values drive classifier vectors, not real-mount evidence;
+// this host has no corresponding network mount on which to run them.
+const NETWORK_FILESYSTEM_TYPES = [
+    { name: 'NFS', type: 0x6969 },
+    { name: 'SMB', type: 0x517b },
+    { name: 'CIFS', type: 0xff534d42 },
+    { name: 'SMB2', type: 0xfe534d42 },
+    { name: '9P', type: 0x01021997 },
+    { name: 'CEPH', type: 0x00c36400 },
+    { name: 'AFS', type: 0x5346414f },
+    { name: 'AFS_FS', type: 0x6b414653 },
+    { name: 'CODA', type: 0x73757245 },
+    { name: 'OCFS2', type: 0x7461636f },
+    { name: 'NCP', type: 0x564c },
+];
+const LOCAL_FILESYSTEM_TYPES = [
+    { name: 'EXT2/3/4', type: 0xef53 },
+    { name: 'BTRFS', type: 0x9123683e },
+    { name: 'XFS', type: 0x58465342 },
+    { name: 'F2FS', type: 0xf2f52010 },
+    { name: 'TMPFS', type: 0x01021994 },
+    { name: 'OVERLAYFS', type: 0x794c7630 },
+    { name: 'ZFS', type: 0x2fc12fc1 },
+];
+const unsignedMagic = (type) => Number(BigInt.asUintN(32, BigInt(type)));
+export function classifyFilesystemType(type) {
+    const magic = unsignedMagic(type);
+    const network = NETWORK_FILESYSTEM_TYPES.find(candidate => candidate.type === magic);
+    if (network)
+        return { locality: 'network', name: network.name };
+    const local = LOCAL_FILESYSTEM_TYPES.find(candidate => candidate.type === magic);
+    if (local)
+        return { locality: 'local', name: local.name };
+    return { locality: 'undetermined', name: `0x${magic.toString(16)}` };
+}
+export function requireLocalDatabasePathWithDetector(databasePath, options, detector) {
+    if (!isAbsolute(databasePath)) {
+        throw new DatabasePathError('PROTOCOL_PATH_NOT_ABSOLUTE', 'databasePath must be absolute before locality detection');
+    }
+    if (options.assumeLocal)
+        return databasePath;
+    const parent = dirname(databasePath);
+    if (detector.platform !== 'linux') {
+        throw new LocalityError('LOCALITY_DETECTOR_UNAVAILABLE', `no filesystem locality detector for platform ${detector.platform}; pass --assume-local-storage only after auditing ${parent}`);
+    }
+    let type;
+    try {
+        type = detector.statfsType(parent);
+    }
+    catch (error) {
+        // @@@missing-parent - Preserve the actionable path error without pretending locality was established.
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+            throw new DatabasePathError('PROTOCOL_PATH_PARENT_MISSING', `database parent directory does not exist: ${parent}`, error);
+        }
+        throw new LocalityError('LOCALITY_PROBE_FAILED', `could not determine the filesystem of ${parent}`, error);
+    }
+    const classification = classifyFilesystemType(type);
+    if (classification.locality === 'network') {
+        throw new LocalityError('LOCALITY_NETWORK_FILESYSTEM', `${parent} is ${classification.name}; advisory locking is not admitted there`);
+    }
+    if (classification.locality === 'undetermined') {
+        throw new LocalityError('LOCALITY_UNDETERMINED', `filesystem type ${classification.name} at ${parent} is not on the audited local allow-list`);
+    }
+    return databasePath;
+}
+const linuxDetector = {
+    platform: process.platform,
+    statfsType: parentPath => statfsSync(parentPath).type,
+};
+export function requireLocalDatabasePath(databasePath, options = {}) {
+    return requireLocalDatabasePathWithDetector(databasePath, options, linuxDetector);
+}

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

@@ -0,0 +1,13 @@
+type DatabasePathErrorCode = 'PROTOCOL_PATH_NOT_ABSOLUTE' | 'PROTOCOL_PATH_INVALID' | 'PROTOCOL_PATH_PARENT_MISSING';
+export declare class DatabasePathError extends Error {
+    readonly code: DatabasePathErrorCode;
+    constructor(code: DatabasePathErrorCode, message: string, cause?: unknown);
+}
+export type SelfLaunchEnvironment = Readonly<Record<string, string | undefined>>;
+export interface ResolveDatabasePathOptions {
+    databasePath?: string;
+    env?: SelfLaunchEnvironment;
+    readFile?: (path: string) => string;
+}
+export declare function resolveDatabasePath(options?: ResolveDatabasePathOptions): string;
+export {};

package/node_modules/@spexcode/session-selflaunch/dist/path.js

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+export class DatabasePathError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'DatabasePathError';
+        this.code = code;
+    }
+}
+export function resolveDatabasePath(options = {}) {
+    const env = options.env ?? process.env;
+    let databasePath = options.databasePath ?? env.SPEX_SESSION_DATABASE_PATH;
+    if (databasePath === undefined && env.SPEX_SESSION_CONFIG) {
+        const configPath = env.SPEX_SESSION_CONFIG;
+        let config;
+        try {
+            config = JSON.parse((options.readFile ?? ((path) => readFileSync(path, 'utf8')))(configPath));
+        }
+        catch (error) {
+            throw new DatabasePathError('PROTOCOL_PATH_INVALID', `could not read session config ${configPath}`, error);
+        }
+        if (typeof config !== 'object'
+            || config === null
+            || typeof config.databasePath !== 'string'
+            || !config.databasePath) {
+            throw new DatabasePathError('PROTOCOL_PATH_INVALID', `session config ${configPath} must contain databasePath`);
+        }
+        databasePath = config.databasePath;
+    }
+    if (databasePath === undefined) {
+        const home = env.SPEXCODE_HOME || (env.HOME ? join(env.HOME, '.spexcode') : undefined);
+        if (!home) {
+            throw new DatabasePathError('PROTOCOL_PATH_INVALID', 'HOME or SPEXCODE_HOME is required for the default database path');
+        }
+        databasePath = join(home, 'sessions.sqlite');
+    }
+    if (databasePath.length === 0) {
+        throw new DatabasePathError('PROTOCOL_PATH_INVALID', 'databasePath must not be empty');
+    }
+    if (!isAbsolute(databasePath)) {
+        throw new DatabasePathError('PROTOCOL_PATH_NOT_ABSOLUTE', 'databasePath must be absolute and is never resolved from cwd');
+    }
+    return databasePath;
+}

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

@@ -0,0 +1,35 @@
+{
+  "name": "@spexcode/session-selflaunch",
+  "version": "0.6.8",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "description": "A fail-closed self-launch adopter for the SpexCode session protocol.",
+  "bin": {
+    "spex-session": "./bin/spex-session.mjs"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "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",
+    "@spexcode/session-runtime": "0.6.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

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

@@ -0,0 +1,6 @@
+export type TopologyErrorCode = 'TOPOLOGY_EDGE_ID_INVALID' | 'TOPOLOGY_EDGE_UNKNOWN' | 'TOPOLOGY_EDGE_EXISTS' | 'TOPOLOGY_CYCLE_REFUSED' | 'TOPOLOGY_RELATION_TYPE_INVALID' | 'TOPOLOGY_SESSION_ID_INVALID' | 'TOPOLOGY_SESSION_UNKNOWN' | 'TOPOLOGY_SELF_EDGE' | 'TOPOLOGY_TRANSACTION_INVALID' | 'TOPOLOGY_STORAGE_ERROR';
+export declare class TopologyError extends Error {
+    readonly code: TopologyErrorCode;
+    constructor(code: TopologyErrorCode, message: string, cause?: unknown);
+}
+export declare function failTopology(code: TopologyErrorCode, message: string, cause?: unknown): never;

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

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

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

@@ -0,0 +1,24 @@
+import type { ProtocolTransaction, SessionProtocol } from '@spexcode/session-protocol';
+import { TopologyError } from './errors.js';
+export interface TopologyEdge {
+    edgeId: string;
+    fromSessionId: string;
+    toSessionId: string;
+    relationType: string;
+    createdAtMs: number;
+    removedAtMs: number | null;
+}
+export interface SessionTopology {
+    attach(tx: ProtocolTransaction, fromSessionId: string, toSessionId: string, relationType: string): TopologyEdge;
+    detach(tx: ProtocolTransaction, edgeId: string): TopologyEdge;
+    reparent(tx: ProtocolTransaction, subjectSessionId: string, nextFromSessionId: string, relationType: string): TopologyEdge;
+    subscribe(tx: ProtocolTransaction, watcherSessionId: string, subjectSessionId: string, channel: string): TopologyEdge;
+    unsubscribe(tx: ProtocolTransaction, watcherSessionId: string, subjectSessionId: string, channel: string): TopologyEdge;
+    parents(sessionId: string, relationType?: string, tx?: ProtocolTransaction): TopologyEdge[];
+    children(sessionId: string, relationType?: string, tx?: ProtocolTransaction): TopologyEdge[];
+    subscriptions(sessionId: string, tx?: ProtocolTransaction): TopologyEdge[];
+    recipients(subjectSessionId: string, tx?: ProtocolTransaction): string[];
+}
+export declare function openTopology(protocol: SessionProtocol): SessionTopology;
+export { TopologyError };
+export type { TopologyErrorCode } from './errors.js';

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

@@ -0,0 +1,173 @@
+import { randomBytes } from 'node:crypto';
+import { applyComponentMigrations } from '@spexcode/session-protocol';
+import { failTopology, TopologyError } from './errors.js';
+import { TOPOLOGY_MIGRATIONS } from './schema.js';
+const EDGE_ID = /^[0-9a-f]{32}$/;
+const RELATION_TYPE = /^[0-9A-Za-z._:-]{1,64}$/;
+const SESSION_ID = /^(?!-)[0-9A-Za-z_-]{1,256}$/;
+const EDGE_COLUMNS = `edge_id, from_session_id, to_session_id, relation_type, created_at_ms, removed_at_ms`;
+export function openTopology(protocol) {
+    applyComponentMigrations(protocol, 'session-topology', TOPOLOGY_MIGRATIONS);
+    const requireTransaction = (tx) => {
+        if (!tx
+            || typeof tx.exec !== 'function'
+            || typeof tx.query !== 'function'
+            || typeof tx.enqueue !== 'function') {
+            failTopology('TOPOLOGY_TRANSACTION_INVALID', 'a live protocol transaction context is required');
+        }
+        return tx;
+    };
+    const requireSessionId = (sessionId) => {
+        if (typeof sessionId !== 'string' || !SESSION_ID.test(sessionId)) {
+            failTopology('TOPOLOGY_SESSION_ID_INVALID', 'session id must match the protocol address grammar');
+        }
+    };
+    const requireRelationType = (relationType) => {
+        if (typeof relationType !== 'string' || !RELATION_TYPE.test(relationType)) {
+            failTopology('TOPOLOGY_RELATION_TYPE_INVALID', 'relation type must match [0-9A-Za-z._:-]{1,64}');
+        }
+    };
+    const requireEdgeId = (edgeId) => {
+        if (typeof edgeId !== 'string' || !EDGE_ID.test(edgeId)) {
+            failTopology('TOPOLOGY_EDGE_ID_INVALID', 'edge id must be 32 lowercase hexadecimal characters');
+        }
+    };
+    const toEdge = (row) => ({
+        edgeId: String(row.edge_id),
+        fromSessionId: String(row.from_session_id),
+        toSessionId: String(row.to_session_id),
+        relationType: String(row.relation_type),
+        createdAtMs: Number(row.created_at_ms),
+        removedAtMs: row.removed_at_ms === null ? null : Number(row.removed_at_ms),
+    });
+    const asEdgeRows = (rows) => rows;
+    const requireAddresses = (tx, fromSessionId, toSessionId) => {
+        const rows = tx.query('SELECT session_id FROM protocol_sessions WHERE session_id IN (?,?) ORDER BY session_id', fromSessionId, toSessionId);
+        const found = new Set(rows.map(row => String(row.session_id)));
+        if (!found.has(fromSessionId) || !found.has(toSessionId)) {
+            failTopology('TOPOLOGY_SESSION_UNKNOWN', 'one or more topology session addresses are unknown');
+        }
+    };
+    const cycleExists = (tx, fromSessionId, toSessionId, relationType) => tx.query(`WITH RECURSIVE reachable(session_id) AS (
+       VALUES (?)
+       UNION
+       SELECT edge.to_session_id
+       FROM topology_edges AS edge INDEXED BY topology_active_edge
+       JOIN reachable ON edge.from_session_id=reachable.session_id
+       WHERE edge.relation_type=? AND edge.removed_at_ms IS NULL
+     )
+     SELECT 1 AS present FROM reachable WHERE session_id=? LIMIT 1`, toSessionId, relationType, fromSessionId).length > 0;
+    const validateNewEdge = (tx, fromSessionId, toSessionId, relationType) => {
+        requireTransaction(tx);
+        requireSessionId(fromSessionId);
+        requireSessionId(toSessionId);
+        requireRelationType(relationType);
+        if (fromSessionId === toSessionId) {
+            failTopology('TOPOLOGY_SELF_EDGE', 'an edge cannot point from a session to itself');
+        }
+        requireAddresses(tx, fromSessionId, toSessionId);
+        if (cycleExists(tx, fromSessionId, toSessionId, relationType)) {
+            failTopology('TOPOLOGY_CYCLE_REFUSED', 'the edge would create a relation cycle');
+        }
+    };
+    const activeEdge = (tx, fromSessionId, toSessionId, relationType) => asEdgeRows(tx.query(`SELECT ${EDGE_COLUMNS} FROM topology_edges INDEXED BY topology_active_edge
+     WHERE from_session_id=? AND to_session_id=? AND relation_type=? AND removed_at_ms IS NULL`, fromSessionId, toSessionId, relationType))[0];
+    const insertEdge = (tx, fromSessionId, toSessionId, relationType) => {
+        const edgeId = randomBytes(16).toString('hex');
+        const createdAtMs = Date.now();
+        try {
+            tx.exec(`INSERT INTO topology_edges
+         (edge_id, from_session_id, to_session_id, relation_type, created_at_ms, removed_at_ms)
+         VALUES (?,?,?,?,?,NULL)`, edgeId, fromSessionId, toSessionId, relationType, createdAtMs);
+        }
+        catch (error) {
+            const code = String(error?.code ?? '');
+            if (code.includes('UNIQUE') || code.includes('PRIMARYKEY')) {
+                failTopology('TOPOLOGY_EDGE_EXISTS', 'the active topology edge already exists', error);
+            }
+            if (code.includes('FOREIGNKEY')) {
+                failTopology('TOPOLOGY_SESSION_UNKNOWN', 'one or more topology session addresses are unknown', error);
+            }
+            failTopology('TOPOLOGY_STORAGE_ERROR', 'the topology edge could not be stored', error);
+        }
+        return { edgeId, fromSessionId, toSessionId, relationType, createdAtMs, removedAtMs: null };
+    };
+    const attach = (tx, fromSessionId, toSessionId, relationType) => {
+        validateNewEdge(tx, fromSessionId, toSessionId, relationType);
+        if (activeEdge(tx, fromSessionId, toSessionId, relationType)) {
+            failTopology('TOPOLOGY_EDGE_EXISTS', 'the active topology edge already exists');
+        }
+        return insertEdge(tx, fromSessionId, toSessionId, relationType);
+    };
+    const detach = (tx, edgeId) => {
+        requireTransaction(tx);
+        requireEdgeId(edgeId);
+        const row = asEdgeRows(tx.query(`SELECT ${EDGE_COLUMNS} FROM topology_edges WHERE edge_id=? AND removed_at_ms IS NULL`, edgeId))[0];
+        if (!row)
+            failTopology('TOPOLOGY_EDGE_UNKNOWN', 'the active topology edge does not exist');
+        const removedAtMs = Date.now();
+        const result = tx.exec('UPDATE topology_edges SET removed_at_ms=? WHERE edge_id=? AND removed_at_ms IS NULL', removedAtMs, edgeId);
+        if (result.changes !== 1) {
+            failTopology('TOPOLOGY_EDGE_UNKNOWN', 'the active topology edge does not exist');
+        }
+        return { ...toEdge(row), removedAtMs };
+    };
+    const withRead = (tx, query) => {
+        if (tx !== undefined)
+            return query(requireTransaction(tx));
+        return protocol.withTransaction(query);
+    };
+    const queryEdges = (sessionId, relationType, tx, direction) => {
+        requireSessionId(sessionId);
+        if (relationType !== undefined)
+            requireRelationType(relationType);
+        return withRead(tx, active => {
+            const index = direction === 'from' ? 'topology_active_edge' : 'topology_active_to';
+            const column = direction === 'from' ? 'from_session_id' : 'to_session_id';
+            const relation = relationType === undefined ? '' : ' AND relation_type=?';
+            const params = relationType === undefined ? [sessionId] : [sessionId, relationType];
+            return asEdgeRows(active.query(`SELECT ${EDGE_COLUMNS} FROM topology_edges INDEXED BY ${index}
+         WHERE ${column}=? AND removed_at_ms IS NULL${relation}
+         ORDER BY relation_type, from_session_id, to_session_id, created_at_ms, edge_id`, ...params)).map(toEdge);
+        });
+    };
+    return {
+        attach,
+        detach,
+        reparent(tx, subjectSessionId, nextFromSessionId, relationType) {
+            validateNewEdge(tx, nextFromSessionId, subjectSessionId, relationType);
+            const removedAtMs = Date.now();
+            tx.exec(`UPDATE topology_edges SET removed_at_ms=?
+         WHERE to_session_id=? AND relation_type=? AND removed_at_ms IS NULL`, removedAtMs, subjectSessionId, relationType);
+            return insertEdge(tx, nextFromSessionId, subjectSessionId, relationType);
+        },
+        subscribe(tx, watcherSessionId, subjectSessionId, channel) {
+            return attach(tx, watcherSessionId, subjectSessionId, channel);
+        },
+        unsubscribe(tx, watcherSessionId, subjectSessionId, channel) {
+            requireTransaction(tx);
+            requireSessionId(watcherSessionId);
+            requireSessionId(subjectSessionId);
+            requireRelationType(channel);
+            const row = activeEdge(tx, watcherSessionId, subjectSessionId, channel);
+            if (!row)
+                failTopology('TOPOLOGY_EDGE_UNKNOWN', 'the active topology edge does not exist');
+            return detach(tx, String(row.edge_id));
+        },
+        parents(sessionId, relationType, tx) {
+            return queryEdges(sessionId, relationType, tx, 'to');
+        },
+        children(sessionId, relationType, tx) {
+            return queryEdges(sessionId, relationType, tx, 'from');
+        },
+        subscriptions(sessionId, tx) {
+            return queryEdges(sessionId, undefined, tx, 'from');
+        },
+        recipients(subjectSessionId, tx) {
+            requireSessionId(subjectSessionId);
+            return withRead(tx, active => active.query(`SELECT DISTINCT from_session_id FROM topology_edges INDEXED BY topology_active_to
+         WHERE to_session_id=? AND removed_at_ms IS NULL ORDER BY from_session_id`, subjectSessionId).map(row => String(row.from_session_id)));
+        },
+    };
+}
+export { TopologyError };

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

@@ -0,0 +1,3 @@
+import type { ComponentMigration } from '@spexcode/session-protocol';
+export declare const TOPOLOGY_MIGRATION_SQL = "\nCREATE TABLE topology_edges (\n  edge_id          TEXT    NOT NULL PRIMARY KEY,\n  from_session_id  TEXT    NOT NULL REFERENCES protocol_sessions(session_id),\n  to_session_id    TEXT    NOT NULL REFERENCES protocol_sessions(session_id),\n  relation_type    TEXT    NOT NULL,\n  created_at_ms    INTEGER NOT NULL,\n  removed_at_ms    INTEGER,\n  CHECK (length(edge_id) = 32 AND edge_id NOT GLOB '*[^0-9a-f]*'),\n  CHECK (from_session_id <> to_session_id),\n  CHECK (length(relation_type) BETWEEN 1 AND 64),\n  CHECK (relation_type NOT GLOB '*[^0-9A-Za-z._:-]*'),\n  CHECK (created_at_ms >= 0),\n  CHECK (removed_at_ms IS NULL OR removed_at_ms >= 0)\n) STRICT;\n\nCREATE UNIQUE INDEX topology_active_edge\n  ON topology_edges (from_session_id, to_session_id, relation_type)\n  WHERE removed_at_ms IS NULL;\n\nCREATE INDEX topology_active_to\n  ON topology_edges (to_session_id, relation_type, from_session_id)\n  WHERE removed_at_ms IS NULL;\n";
+export declare const TOPOLOGY_MIGRATIONS: readonly ComponentMigration[];