@peers-app/peers-sdk 0.19.13 → 0.20.0

package/dist/contracts/contract-proxy.js

@@ -0,0 +1,663 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sameUserContractPermissionCheck = exports.CONTRACT_CALL_RPC = void 0;
+exports.createContractConsumer = createContractConsumer;
+exports.createContractProvider = createContractProvider;
+exports.createContractProviderEndpoint = createContractProviderEndpoint;
+exports.createContractProviderSession = createContractProviderSession;
+const decorators_1 = require("../data/orm/decorators");
+const observable_1 = require("../observable");
+const utils_1 = require("../utils");
+const contract_transport_1 = require("./contract-transport");
+const STANDARD_REMOTE_TABLE_METHODS = new Set([
+    "get",
+    "list",
+    "count",
+    "findOne",
+    "save",
+    "insert",
+    "update",
+    "delete",
+]);
+const FORBIDDEN_REMOTE_TABLE_PROPERTIES = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+    "dataChanged",
+    "dataChangedEmitter",
+    "subscribe",
+    "unsubscribe",
+    "then",
+    "toString",
+    "valueOf",
+]);
+/**
+ * The RPC event name used to proxy a single {@link IContractCall} over a
+ * {@link Connection} (`connection.emit(CONTRACT_CALL_RPC, call)` on the consumer
+ * side; `connection.exposeRPC(CONTRACT_CALL_RPC, handler)` on the provider side).
+ *
+ * Alias of {@link CONTRACT_REQUEST_CHANNEL} — the fixed request/response channel of an
+ * {@link IContractTransport}. Kept for existing provider registrations that reference it.
+ */
+exports.CONTRACT_CALL_RPC = contract_transport_1.CONTRACT_REQUEST_CHANNEL;
+/**
+ * Build the **consumer** side of a contract proxy from a contract definition and a
+ * transport. Member names come from the contract shape; table members are backed by a
+ * `Proxy` that forwards accessed method names. The provider accepts only standard data
+ * operations and custom methods marked by `ProxyClientTableMethodCalls`.
+ *
+ * Every access is turned into an {@link IContractCall} sent on the transport's fixed
+ * {@link CONTRACT_REQUEST_CHANNEL}; the resolved ack is the provider's return value.
+ *
+ * The consumer also subscribes to provider pushes: `events[name].subscribe(handler)` and
+ * `tables[name].dataChanged.subscribe(handler)` both send a `"subscribe"` request and
+ * demultiplex provider pushes arriving on {@link CONTRACT_NOTIFY_CHANNEL} by their
+ * `subscriptionId` (shared `subscribeVia` path). Observables use the same push channel but
+ * are *not* gated: each `observables[name]` is a live {@link Observable} mirror that subscribes
+ * implicitly at creation, loads an initial snapshot (awaitable via
+ * {@link IContractConsumer.loadingPromise}), and streams every subsequent change; local writes
+ * send a fire-and-forget `set`. Call {@link IContractConsumer.dispose} to remove the notify
+ * listener and unsubscribe every stream. Read-only observable writes are rejected on both
+ * consumer and provider boundaries. Disposal is idempotent and prevents new remote operations;
+ * cached observable reads remain available afterward.
+ *
+ * @param contract   The contract definition (shape) being consumed.
+ * @param transport  Bidirectional channel to the provider; requests go out on
+ *   {@link CONTRACT_REQUEST_CHANNEL}, notifications arrive on {@link CONTRACT_NOTIFY_CHANNEL}.
+ * @param opts.dataContextId  Optional data context to scope every call to.
+ */
+function createContractConsumer(contract, transport, opts = {}) {
+    const { contractId, version } = contract;
+    const { dataContextId } = opts;
+    let disposed = false;
+    const emitRequest = (call) => transport.emit(contract_transport_1.CONTRACT_REQUEST_CHANNEL, call);
+    const request = (call) => disposed
+        ? Promise.reject(new Error(`Contract consumer ${contractId} v${version} is disposed`))
+        : emitRequest(call);
+    // Notify demux: one listener on the shared notify channel routes each push to the
+    // handler that owns its subscriptionId. Notifications for other consumers' ids
+    // (a shared transport is multiplexed) simply find no handler and are dropped.
+    const notifyHandlers = new Map();
+    const subscriptions = new Set();
+    const observableWriteSubscriptions = [];
+    const offNotify = transport.on(contract_transport_1.CONTRACT_NOTIFY_CHANNEL, (n) => {
+        notifyHandlers.get(n.subscriptionId)?.(n.value);
+    });
+    /**
+     * Shared subscribe path for every subscription-gated surface (generic events and table
+     * `dataChanged`). Registers `handler` under a fresh `subscriptionId` before asking the
+     * provider to start sending (so no push can arrive before its handler exists), fires the
+     * subscribe request fire-and-forget (like the local {@link Event} API), and returns an
+     * idempotent {@link ISubscriptionResult}. If unsubscribe or disposal happens before the
+     * subscribe ack, the wire unsubscribe is queued behind that ack; a failed subscribe sends
+     * no redundant unsubscribe. `buildCall` maps the `(subscriptionId, operation)` pair to the
+     * exact wire call for that surface.
+     */
+    const subscribeVia = (buildCall) => (handler) => {
+        if (disposed) {
+            throw new Error(`Contract consumer ${contractId} v${version} is disposed`);
+        }
+        const subscriptionId = (0, utils_1.newid)();
+        let active = true;
+        let unsubscribeSent = false;
+        notifyHandlers.set(subscriptionId, handler);
+        const subscribeAck = emitRequest(buildCall(subscriptionId, "subscribe"))
+            .then(() => true)
+            .catch((err) => {
+            active = false;
+            notifyHandlers.delete(subscriptionId);
+            subscriptions.delete(subscription);
+            console.error("Contract subscribe failed", err);
+            return false;
+        });
+        const sendUnsubscribe = async () => {
+            if (unsubscribeSent) {
+                return;
+            }
+            unsubscribeSent = true;
+            try {
+                await emitRequest(buildCall(subscriptionId, "unsubscribe"));
+            }
+            catch (err) {
+                console.error("Contract unsubscribe failed", err);
+            }
+        };
+        const subscription = {
+            unsubscribe: () => {
+                if (!active) {
+                    return false;
+                }
+                active = false;
+                notifyHandlers.delete(subscriptionId);
+                subscriptions.delete(subscription);
+                void subscribeAck.then((subscribed) => {
+                    if (subscribed) {
+                        return sendUnsubscribe();
+                    }
+                });
+                return true;
+            },
+        };
+        subscriptions.add(subscription);
+        return subscription;
+    };
+    const tables = {};
+    for (const table of contract.tables) {
+        const name = table.name;
+        // `dataChanged` is a subscribable that rides the notify channel (created lazily and
+        // cached); every other accessed name forwards as a remote method call.
+        let dataChanged;
+        tables[name] = new Proxy({}, {
+            get(_target, operation) {
+                if (typeof operation !== "string") {
+                    return undefined;
+                }
+                if (operation === "dataChanged") {
+                    dataChanged ??= {
+                        subscribe: subscribeVia((subscriptionId, op) => ({
+                            contractId,
+                            version,
+                            member: "table",
+                            name,
+                            operation: op,
+                            event: "dataChanged",
+                            subscriptionId,
+                            args: [],
+                            dataContextId,
+                        })),
+                    };
+                    return dataChanged;
+                }
+                return (...args) => request({
+                    contractId,
+                    version,
+                    member: "table",
+                    name,
+                    operation,
+                    args,
+                    dataContextId,
+                });
+            },
+        });
+    }
+    const tools = {};
+    for (const tool of contract.tools) {
+        const name = tool.name;
+        tools[name] = (...args) => request({
+            contractId,
+            version,
+            member: "tool",
+            name,
+            operation: "run",
+            args,
+            dataContextId,
+        });
+    }
+    const events = {};
+    for (const evt of contract.events ?? []) {
+        const name = evt.name;
+        events[name] = {
+            subscribe: subscribeVia((subscriptionId, operation) => ({
+                contractId,
+                version,
+                member: "event",
+                name,
+                operation,
+                subscriptionId,
+                args: [],
+                dataContextId,
+            })),
+        };
+    }
+    // Observables are backed by real, callable Observable mirrors (see below).
+    const observables = {};
+    const observableLoads = [];
+    const dispose = () => {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        for (const sub of [...subscriptions]) {
+            sub.unsubscribe();
+        }
+        for (const sub of observableWriteSubscriptions) {
+            sub.dispose();
+        }
+        offNotify();
+        notifyHandlers.clear();
+    };
+    const consumer = {
+        contractId,
+        version,
+        tables,
+        tools,
+        observables,
+        events,
+        loadingPromise: Promise.resolve(),
+        dispose,
+    };
+    // Build each observable as a locally-mirrored Observable kept current by provider pushes
+    // (decision 4: observables are always streamed so reads are synchronous). Writes are
+    // fire-and-forget and chained onto the proxy-level loadingPromise for awaitable durability
+    // — the same shape as a persistent var (see data/persistent-vars.ts).
+    for (const obs of contract.observables) {
+        const name = obs.name;
+        const mirror = (0, observable_1.observable)();
+        // Guards against echo loops: while applying a provider push we must not re-`set` it, and
+        // once a push has updated the mirror a later (possibly stale) initial `get` is ignored.
+        let applyingRemote = false;
+        let pushed = false;
+        const applyRemote = (value) => {
+            if (disposed) {
+                return;
+            }
+            pushed = true;
+            applyingRemote = true;
+            try {
+                mirror(value);
+            }
+            finally {
+                applyingRemote = false;
+            }
+        };
+        // Implicit, always-on subscription (not gated). `subscribeVia` registers the handler
+        // before asking the provider to start streaming, so no push can arrive unhandled.
+        subscribeVia((subscriptionId, operation) => ({
+            contractId,
+            version,
+            member: "observable",
+            name,
+            operation,
+            subscriptionId,
+            args: [],
+            dataContextId,
+        }))(applyRemote);
+        // Expose a guarded callable facade: cached reads remain available after disposal, while
+        // writes are rejected because they would otherwise mutate a dead mirror without reaching
+        // the provider. Provider pushes bypass this facade through applyRemote above.
+        const exposedMirror = ((...args) => {
+            if (args.length === 0) {
+                return mirror();
+            }
+            if (disposed) {
+                throw new Error(`Contract consumer ${contractId} v${version} is disposed`);
+            }
+            if (!obs.writable) {
+                throw new Error(`Observable '${name}' is read-only`);
+            }
+            return mirror(args[0]);
+        });
+        exposedMirror.subscribe = mirror.subscribe;
+        exposedMirror.notifySubscribers = mirror.notifySubscribers;
+        exposedMirror.subscriberCount = mirror.subscriberCount;
+        // Initial snapshot so the mirror has a value to read synchronously. A push that arrived
+        // first wins — the snapshot may already be stale by the time it resolves.
+        observableLoads.push(request({
+            contractId,
+            version,
+            member: "observable",
+            name,
+            operation: "get",
+            args: [],
+            dataContextId,
+        })
+            .then((value) => {
+            if (!disposed && !pushed) {
+                applyRemote(value);
+            }
+        })
+            .catch((err) => console.error("Contract observable initial get failed", err)));
+        // Local writes → fire-and-forget `set`, chained onto loadingPromise for durability.
+        observableWriteSubscriptions.push(mirror.subscribe((value) => {
+            if (applyingRemote || disposed) {
+                return;
+            }
+            consumer.loadingPromise = consumer.loadingPromise.then(() => request({
+                contractId,
+                version,
+                member: "observable",
+                name,
+                operation: "set",
+                args: [value],
+                dataContextId,
+            })
+                .then(() => undefined)
+                .catch((err) => console.error("Contract observable set failed", err)));
+        }));
+        observables[name] = exposedMirror;
+    }
+    consumer.loadingPromise = Promise.all(observableLoads).then(() => undefined);
+    return consumer;
+}
+/**
+ * Legacy gate that allows calls only when caller and provider user ids match.
+ *
+ * @deprecated Production connection routing uses the signed-identity, provider-personal
+ * Self-trust policy in `createUserContextContractProviderRouter`. Keep this helper only
+ * for compatibility and isolated in-process providers that intentionally need the old gate.
+ */
+const sameUserContractPermissionCheck = (_call, context) => {
+    return Boolean(context.localUserId) && context.callerUserId === context.localUserId;
+};
+exports.sameUserContractPermissionCheck = sameUserContractPermissionCheck;
+/**
+ * Build the **provider** side of a contract proxy: an async handler that permission-checks
+ * an {@link IContractCall} and dispatches it to the live table method / tool fn / observable
+ * accessor in the given resolution. Table dispatch is constrained to standard serializable
+ * data operations plus custom methods explicitly marked by `ProxyClientTableMethodCalls`;
+ * internal helpers, event properties, document/cursor helpers, and prototype properties
+ * are not remotely callable.
+ *
+ * @param resolution  The live contract implementation to dispatch to.
+ * @param opts.permissionCheck  Optional gate run before every dispatch.
+ */
+function createContractProvider(resolution, opts = {}) {
+    const { permissionCheck } = opts;
+    return async (call, context = {}) => {
+        if (call.contractId !== resolution.contractId || call.version !== resolution.version) {
+            throw new Error(`Contract mismatch: resolution provides ${resolution.contractId} v${resolution.version} ` +
+                `but call targets ${call.contractId} v${call.version}`);
+        }
+        if (permissionCheck) {
+            const allowed = await permissionCheck(call, context);
+            if (!allowed) {
+                throw new Error(`Permission denied: ${call.member} '${call.name}'.${call.operation} on contract ${call.contractId}`);
+            }
+        }
+        switch (call.member) {
+            case "table": {
+                const table = resolution.tables?.[call.name];
+                if (!table) {
+                    throw new Error(`Contract ${call.contractId} does not provide table '${call.name}'`);
+                }
+                if (FORBIDDEN_REMOTE_TABLE_PROPERTIES.has(call.operation)) {
+                    throw new Error(`Table method '${call.name}.${call.operation}' is not remotely callable`);
+                }
+                const method = table[call.operation];
+                // Unwrap client-proxy methods so we call the real implementation, not a
+                // method that would re-forward the call (see ProxyClientTableMethodCalls).
+                const impl = typeof method === "function" ? (method.__original ?? method) : undefined;
+                if (typeof impl !== "function") {
+                    throw new Error(`Table '${call.name}' has no method '${call.operation}'`);
+                }
+                if (!STANDARD_REMOTE_TABLE_METHODS.has(call.operation) &&
+                    !(0, decorators_1.isContractRemoteTableMethod)(method)) {
+                    throw new Error(`Table method '${call.name}.${call.operation}' is not remotely callable`);
+                }
+                return impl.apply(table, call.args);
+            }
+            case "tool": {
+                if (call.operation !== "run") {
+                    throw new Error(`Unsupported tool operation '${call.operation}' on '${call.name}'`);
+                }
+                const tool = resolution.tools?.[call.name];
+                if (!tool) {
+                    throw new Error(`Contract ${call.contractId} does not provide tool '${call.name}'`);
+                }
+                return tool.toolFn(...call.args);
+            }
+            case "observable": {
+                const obs = resolution.observables?.[call.name];
+                if (!obs) {
+                    throw new Error(`Contract ${call.contractId} does not provide observable '${call.name}'`);
+                }
+                if (call.operation === "get") {
+                    return obs();
+                }
+                if (call.operation === "set") {
+                    if (resolution.observableWritability?.[call.name] !== true) {
+                        throw new Error(`Observable '${call.name}' is read-only`);
+                    }
+                    return obs(call.args[0]);
+                }
+                throw new Error(`Unsupported observable operation '${call.operation}' on '${call.name}'`);
+            }
+            default:
+                throw new Error(`Unsupported contract member type '${call.member}'`);
+        }
+    };
+}
+/**
+ * Build a stateful **provider endpoint**: it serves the same request/response dispatch as
+ * {@link createContractProvider} for table/tool/observable calls, and additionally serves
+ * subscriptions on any streamable member — generic `event` calls, table events (a `table`
+ * member with `"subscribe"` / `"unsubscribe"`, resolving `dataChanged` by default), and
+ * observable value streams (an `observable` member with `"subscribe"` / `"unsubscribe"`;
+ * `get`/`set` still flow to the stateless dispatch).
+ *
+ * The live source — an {@link Event} (`resolution.events[name]` or a table's `dataChanged`)
+ * or an {@link Observable} (`resolution.observables[name]`) — is only subscribed to while at
+ * least one consumer holds a subscription (refcounted by a resolved key), and each payload is
+ * fanned out through the supplied {@link ContractNotificationSink} as an
+ * {@link IContractNotification}. The endpoint owns no request listener, which lets a
+ * connection-wide router multiplex many endpoints through one request channel and later
+ * substitute sandbox-backed endpoint implementations.
+ *
+ * @param resolution  The live contract implementation to dispatch to and stream from.
+ * @param opts         Notification sink plus optional permission gate and default context.
+ */
+function createContractProviderEndpoint(resolution, opts) {
+    const { notify, permissionCheck, context: defaultContext } = opts;
+    const dispatch = createContractProvider(resolution, { permissionCheck });
+    // One live subscription per resolved subscription key, refcounted by the set of
+    // consumer subscription ids currently attached to it, plus a reverse index for
+    // unsubscribe. Keys namespace generic events (`event:<name>`), table events
+    // (`table:<name>:<event>`), and observable streams (`observable:<name>`) so the same
+    // machinery serves all three.
+    const byKey = new Map();
+    const subIdToKey = new Map();
+    const pendingSubIds = new Set();
+    let disposed = false;
+    const notifySink = (subscriptionId, value, debugName) => notify({
+        subscriptionId,
+        value,
+        contractId: resolution.contractId,
+        name: debugName,
+    });
+    /**
+     * Resolve a subscription call to a stable refcount `key` plus an `attach` function that
+     * hooks a payload handler onto the live source and returns a detach callback. This
+     * normalizes the three streamable sources behind one interface:
+     * - generic `event` → `resolution.events[name]` (an {@link Event}; `subscribe` returns
+     *   `{ unsubscribe }`), key `event:<name>`.
+     * - observable value stream → `resolution.observables[name]` (an {@link Observable};
+     *   `subscribe` returns `{ dispose }`), key `observable:<name>`.
+     * - table event → `resolution.tables[name][event ?? "dataChanged"]` (an {@link Event};
+     *   a `Table` exposes `dataChanged` as a plain `Event`), key `table:<name>:<event>`.
+     */
+    const resolveSubscription = (call) => {
+        if (call.member === "event") {
+            const liveEvent = resolution.events?.[call.name];
+            if (!liveEvent) {
+                throw new Error(`Contract ${resolution.contractId} does not provide event '${call.name}'`);
+            }
+            return {
+                key: `event:${call.name}`,
+                attach: (handler) => {
+                    const sub = liveEvent.subscribe(handler);
+                    return () => sub.unsubscribe();
+                },
+            };
+        }
+        if (call.member === "observable") {
+            const obs = resolution.observables?.[call.name];
+            if (!obs) {
+                throw new Error(`Contract ${resolution.contractId} does not provide observable '${call.name}'`);
+            }
+            return {
+                key: `observable:${call.name}`,
+                attach: (handler) => {
+                    const sub = obs.subscribe(handler);
+                    return () => sub.dispose();
+                },
+            };
+        }
+        const table = resolution.tables?.[call.name];
+        if (!table) {
+            throw new Error(`Contract ${resolution.contractId} does not provide table '${call.name}'`);
+        }
+        const evtName = call.event ?? "dataChanged";
+        const liveEvent = table[evtName];
+        if (!liveEvent || typeof liveEvent.subscribe !== "function") {
+            throw new Error(`Table '${call.name}' does not provide event '${evtName}'`);
+        }
+        return {
+            key: `table:${call.name}:${evtName}`,
+            attach: (handler) => {
+                const sub = liveEvent.subscribe(handler);
+                return () => sub.unsubscribe();
+            },
+        };
+    };
+    const subscribe = (key, attach, subscriptionId) => {
+        if (subIdToKey.has(subscriptionId)) {
+            throw new Error(`Duplicate contract subscriptionId '${subscriptionId}'`);
+        }
+        let entry = byKey.get(key);
+        if (!entry) {
+            // First subscriber for this key: attach the single live subscription.
+            const subIds = new Set();
+            const detach = attach((payload) => {
+                // Start each notification independently. A slow or rejected destination must not
+                // block sibling subscribers, and every rejection is handled because Observable
+                // callbacks do not await returned promises.
+                for (const sid of [...subIds]) {
+                    void notifySink(sid, payload, key).catch((err) => {
+                        console.error(`Contract notify failed for subscription '${sid}'`, err);
+                    });
+                }
+            });
+            entry = { liveUnsub: detach, subIds };
+            byKey.set(key, entry);
+        }
+        subIdToKey.set(subscriptionId, key);
+        entry.subIds.add(subscriptionId);
+    };
+    const unsubscribe = (subscriptionId) => {
+        const key = subIdToKey.get(subscriptionId);
+        if (!key) {
+            return;
+        }
+        subIdToKey.delete(subscriptionId);
+        const entry = byKey.get(key);
+        if (!entry) {
+            return;
+        }
+        entry.subIds.delete(subscriptionId);
+        if (entry.subIds.size === 0) {
+            // Last subscriber left: detach the live subscription (nothing more is pushed).
+            entry.liveUnsub();
+            byKey.delete(key);
+        }
+    };
+    const validateSubscriptionCall = (call) => {
+        if (call.member !== "event" && call.member !== "table" && call.member !== "observable") {
+            throw new Error(`Contract member type '${call.member}' does not support subscriptions`);
+        }
+        if (call.operation !== "subscribe" && call.operation !== "unsubscribe") {
+            throw new Error(`Unsupported subscription operation '${call.operation}' on '${call.name}'`);
+        }
+        if (call.member === "table" && call.event !== undefined && call.event !== "dataChanged") {
+            throw new Error(`Unsupported table event '${call.event}' on '${call.name}'`);
+        }
+        if (call.member !== "table" && call.event !== undefined) {
+            throw new Error(`Contract ${call.member} '${call.name}'.${call.operation} cannot specify a table event`);
+        }
+    };
+    const handleSubscriptionCall = async (call, context) => {
+        if (call.contractId !== resolution.contractId || call.version !== resolution.version) {
+            throw new Error(`Contract mismatch: resolution provides ${resolution.contractId} v${resolution.version} ` +
+                `but call targets ${call.contractId} v${call.version}`);
+        }
+        validateSubscriptionCall(call);
+        if (!call.subscriptionId) {
+            throw new Error(`${call.member} '${call.name}'.${call.operation} requires a subscriptionId`);
+        }
+        if (call.operation === "subscribe") {
+            if (subIdToKey.has(call.subscriptionId) || pendingSubIds.has(call.subscriptionId)) {
+                throw new Error(`Duplicate contract subscriptionId '${call.subscriptionId}'`);
+            }
+            pendingSubIds.add(call.subscriptionId);
+            try {
+                if (permissionCheck) {
+                    const allowed = await permissionCheck(call, context);
+                    if (!allowed) {
+                        throw new Error(`Permission denied: ${call.member} '${call.name}'.subscribe on contract ${call.contractId}`);
+                    }
+                }
+                if (disposed) {
+                    throw new Error(`Contract provider endpoint ${resolution.contractId} v${resolution.version} is disposed`);
+                }
+                const { key, attach } = resolveSubscription(call);
+                subscribe(key, attach, call.subscriptionId);
+            }
+            finally {
+                pendingSubIds.delete(call.subscriptionId);
+            }
+            return;
+        }
+        if (call.operation === "unsubscribe") {
+            unsubscribe(call.subscriptionId);
+            return;
+        }
+        throw new Error(`Unsupported subscription operation '${call.operation}' on '${call.name}'`);
+    };
+    return {
+        handleCall(call, suppliedContext) {
+            if (disposed) {
+                return Promise.reject(new Error(`Contract provider endpoint ${resolution.contractId} v${resolution.version} is disposed`));
+            }
+            const context = suppliedContext ?? defaultContext ?? {};
+            // The reserved subscribe/unsubscribe operations are subscription traffic on every
+            // streamable member (generic events, table events, and observable value streams);
+            // everything else (table methods, tool runs, observable get/set) is stateless dispatch.
+            const isSubscription = call.member === "event" ||
+                call.operation === "subscribe" ||
+                call.operation === "unsubscribe";
+            return isSubscription ? handleSubscriptionCall(call, context) : dispatch(call, context);
+        },
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            for (const entry of byKey.values()) {
+                entry.liveUnsub();
+            }
+            byKey.clear();
+            subIdToKey.clear();
+            pendingSubIds.clear();
+        },
+    };
+}
+/**
+ * Build the backward-compatible transport-bound provider session. The session owns the
+ * transport's request listener while its underlying {@link IContractProviderEndpoint} owns
+ * request dispatch and live subscription state.
+ *
+ * Use {@link createContractProviderEndpoint} behind a connection-wide router when multiple
+ * contracts or data contexts share one transport.
+ *
+ * @param resolution  The live contract implementation to dispatch to and stream from.
+ * @param transport   Requests arrive on {@link CONTRACT_REQUEST_CHANNEL}; notifications are
+ *   emitted on {@link CONTRACT_NOTIFY_CHANNEL}.
+ * @param opts        Optional permission gate and default caller context.
+ */
+function createContractProviderSession(resolution, transport, opts = {}) {
+    const endpoint = createContractProviderEndpoint(resolution, {
+        ...opts,
+        notify: (notification) => transport.emit(contract_transport_1.CONTRACT_NOTIFY_CHANNEL, notification),
+    });
+    const offRequest = transport.on(contract_transport_1.CONTRACT_REQUEST_CHANNEL, (call, context) => endpoint.handleCall(call, context));
+    let disposed = false;
+    return {
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            offRequest();
+            endpoint.dispose();
+        },
+    };
+}