spexcode 0.6.7 → 0.7.0-next.0

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,31 @@
+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;
+    readonly classify?: (parentPath: string) => FilesystemClassification;
+}
+export declare const linuxLocalityDetector: (statfsType: (parentPath: string) => number | bigint) => LocalityDetector;
+interface DarwinMountEntry {
+    readonly mountPoint: string;
+    readonly fstype: string;
+    readonly flags: ReadonlySet<string>;
+}
+export declare function parseDarwinMountTable(output: string): DarwinMountEntry[];
+export declare function classifyDarwinMount(mountTable: string, resolvedPath: string): FilesystemClassification;
+export declare const darwinLocalityDetector: (readMountTable: () => string) => LocalityDetector;
+export declare function requireLocalDatabasePathWithDetector(databasePath: string, options: {
+    assumeLocal?: boolean;
+}, detector: LocalityDetector): string;
+export declare function localityDetectorForPlatform(platform: string): LocalityDetector;
+export declare function requireLocalDatabasePath(databasePath: string, options?: {
+    assumeLocal?: boolean;
+}): string;
+export {};

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

@@ -0,0 +1,135 @@
+import { execFileSync } from 'node:child_process';
+import { realpathSync, statSync, 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 const linuxLocalityDetector = (statfsType) => ({
+    platform: 'linux',
+    classify: parentPath => classifyFilesystemType(statfsType(parentPath)),
+});
+// Darwin filesystem type names that are network transports even when the mount table omits MNT_LOCAL. `local`
+// wins when present (it is the kernel's own verdict); this list only names the refusal, so the operator reads
+// "smbfs" instead of a bare "undetermined".
+const DARWIN_NETWORK_FILESYSTEM_NAMES = new Set(['nfs', 'smbfs', 'afpfs', 'webdav', 'cifs', 'ftp']);
+// `/sbin/mount` prints one `<device> on <mount point> (<fstype>, <flag>, …)` line per mount. The mount point may
+// contain spaces (`/Volumes/My Disk`); the parenthesised list is always last and never contains `)`.
+const DARWIN_MOUNT_LINE = /^.+ on (.+) \(([^)]*)\)$/;
+export function parseDarwinMountTable(output) {
+    const entries = [];
+    for (const line of output.split('\n')) {
+        const match = DARWIN_MOUNT_LINE.exec(line.trim());
+        if (!match)
+            continue;
+        const [fstype = '', ...flags] = match[2].split(',').map(part => part.trim()).filter(Boolean);
+        entries.push({ mountPoint: match[1], fstype, flags: new Set(flags) });
+    }
+    return entries;
+}
+const mountPointCovers = (mountPoint, path) => mountPoint === '/' || path === mountPoint || path.startsWith(mountPoint.endsWith('/') ? mountPoint : `${mountPoint}/`);
+export function classifyDarwinMount(mountTable, resolvedPath) {
+    let entry;
+    for (const candidate of parseDarwinMountTable(mountTable)) {
+        if (!mountPointCovers(candidate.mountPoint, resolvedPath))
+            continue;
+        if (!entry || candidate.mountPoint.length > entry.mountPoint.length)
+            entry = candidate;
+    }
+    if (!entry)
+        return { locality: 'undetermined', name: 'no mount table entry' };
+    if (entry.flags.has('local'))
+        return { locality: 'local', name: entry.fstype };
+    if (DARWIN_NETWORK_FILESYSTEM_NAMES.has(entry.fstype))
+        return { locality: 'network', name: entry.fstype };
+    return { locality: 'undetermined', name: entry.fstype };
+}
+export const darwinLocalityDetector = (readMountTable) => ({
+    platform: 'darwin',
+    classify: parentPath => {
+        // `mount` never fails for a missing directory, so the parent's absence must be raised here for the resolver
+        // to keep its actionable PROTOCOL_PATH_PARENT_MISSING error.
+        statSync(parentPath);
+        return classifyDarwinMount(readMountTable(), realpathSync(parentPath));
+    },
+});
+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.classify) {
+        throw new LocalityError('LOCALITY_DETECTOR_UNAVAILABLE', `no filesystem locality detector for platform ${detector.platform}; pass --assume-local-storage only after auditing ${parent}`);
+    }
+    let classification;
+    try {
+        classification = detector.classify(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);
+    }
+    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 readDarwinMountTable = () => execFileSync('/sbin/mount', [], { encoding: 'utf8', timeout: 5_000, stdio: ['ignore', 'pipe', 'ignore'] });
+export function localityDetectorForPlatform(platform) {
+    if (platform === 'linux')
+        return linuxLocalityDetector(parentPath => statfsSync(parentPath).type);
+    if (platform === 'darwin')
+        return darwinLocalityDetector(readDarwinMountTable);
+    return { platform };
+}
+export function requireLocalDatabasePath(databasePath, options = {}) {
+    return requireLocalDatabasePathWithDetector(databasePath, options, localityDetectorForPlatform(process.platform));
+}

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.7.0-next.0",
+  "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.7.0-next.0",
+    "@spexcode/session-runtime": "0.7.0-next.0"
+  },
+  "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';