@astrale-os/kernel-client 0.6.0-beta.8 → 0.6.0-beta.80

package/dist/session/routing/cache.js

@@ -1,39 +1,51 @@
+import { invocation } from '@astrale-os/kernel-protocol';
 import { DEFAULT_MAXIMUM_ROUTES } from '../context/index.js';
-/** Confidential, process-local warm routing state owned by exactly one ClientSession. */
+const DESTINATION_CREDENTIAL_REFRESH_SKEW_MS = 5_000;
+/** Confidential warm routing state owned by exactly one ClientSession. */
 export class RouteCache {
     maximumAgeMs;
     maximumSize;
     entries = new Map();
-    constructor(maximumAgeMs, maximumSize = DEFAULT_MAXIMUM_ROUTES) {
+    keyTokens = new Map();
+    store;
+    constructor(maximumAgeMs, maximumSize = DEFAULT_MAXIMUM_ROUTES, store) {
         this.maximumAgeMs = maximumAgeMs;
         this.maximumSize = maximumSize;
+        this.store = store === undefined ? undefined : captureSessionRouteStore(store);
+        this.restore();
     }
-    async key(source, call, auth, expected) {
+    async key(source, call, auth) {
         const credential = auth.credential === undefined ? 'anonymous' : await digestText(auth.credential);
         const delegate = auth.delegate === undefined ? 'anonymous' : await digestText(canonicalDelegate(auth.delegate));
-        return JSON.stringify([
-            source,
-            call.target,
-            credential,
-            delegate,
-            expected === undefined ? null : [expected.origin, expected.revision],
-        ]);
-    }
-    get(key, now = Date.now()) {
-        const entry = this.entries.get(key);
-        if (entry === undefined)
+        return JSON.stringify([source, call.target, credential, delegate]);
+    }
+    async get(key, sourceCredential, now = Date.now()) {
+        const cached = this.entries.get(key);
+        if (cached === undefined)
             return undefined;
-        if (entry.expiresAt <= now) {
-            this.entries.delete(key);
+        const token = this.keyTokens.get(key);
+        if (cached.learned.expiresAt <= now) {
+            this.invalidate(key);
             return undefined;
         }
+        if (cached.integrity !== undefined) {
+            const matches = sourceCredential !== undefined &&
+                (await matchesIntegrity(sourceCredential, key, cached.sealed ?? cached.learned, cached.integrity));
+            if (this.keyTokens.get(key) !== token || this.entries.get(key) !== cached) {
+                return undefined;
+            }
+            if (!matches) {
+                this.invalidate(key);
+                return undefined;
+            }
+        }
         this.entries.delete(key);
-        this.entries.set(key, entry);
-        return entry;
+        this.entries.set(key, cached);
+        return cached.learned;
     }
-    learn(key, route, credential, now = Date.now()) {
+    async learn(key, route, credential, sourceCredential, now = Date.now()) {
         const credentialExpiry = credential === undefined ? undefined : jwtExpiry(credential);
-        const expiresAt = Math.min(now + this.maximumAgeMs, credentialExpiry ?? Number.POSITIVE_INFINITY);
+        const expiresAt = Math.min(now + this.maximumAgeMs, refreshBoundary(credentialExpiry));
         const entry = Object.freeze({
             route,
             ...(credential === undefined ? {} : { credential }),
@@ -44,22 +56,203 @@ export class RouteCache {
             return entry;
         if (expiresAt <= now)
             return entry;
+        const token = this.reserve(key);
+        let integrity;
+        if (this.store !== undefined && sourceCredential !== undefined) {
+            try {
+                integrity = await routeIntegrity(sourceCredential, key, entry);
+            }
+            catch {
+                // Integrity support is a persistence optimization; the learned route remains usable in memory.
+            }
+        }
+        if (this.keyTokens.get(key) !== token) {
+            return entry;
+        }
         this.entries.delete(key);
         while (this.entries.size >= this.maximumSize) {
             const oldest = this.entries.keys().next().value;
             if (oldest === undefined)
                 break;
             this.entries.delete(oldest);
+            this.keyTokens.delete(oldest);
         }
-        this.entries.set(key, entry);
+        this.entries.set(key, Object.freeze({
+            learned: entry,
+            ...(integrity === undefined ? {} : { sealed: entry, integrity }),
+        }));
+        this.persist();
         return entry;
     }
     delete(key) {
-        this.entries.delete(key);
+        this.invalidate(key);
     }
+    /** Clear this Session's memory without deleting caller-owned persistent state. */
     clear() {
+        this.keyTokens.clear();
         this.entries.clear();
     }
+    invalidate(key) {
+        this.keyTokens.delete(key);
+        if (this.entries.delete(key))
+            this.persist();
+    }
+    reserve(key) {
+        const token = Object.freeze({});
+        this.keyTokens.set(key, token);
+        return token;
+    }
+    restore(now = Date.now()) {
+        if (this.store === undefined)
+            return;
+        try {
+            this.restoreInput(this.store.read(), now);
+        }
+        catch {
+            this.keyTokens.clear();
+            this.entries.clear();
+        }
+    }
+    restoreInput(input, now) {
+        if (input === undefined)
+            return;
+        if (typeof input !== 'object' || input === null || Array.isArray(input))
+            return;
+        const artifact = input;
+        if (artifact.version !== 1 ||
+            typeof artifact.entries !== 'object' ||
+            artifact.entries === null ||
+            Array.isArray(artifact.entries)) {
+            return;
+        }
+        let count = 0;
+        for (const key in artifact.entries) {
+            if (!Object.hasOwn(artifact.entries, key))
+                continue;
+            count += 1;
+            if (count > this.maximumSize) {
+                this.keyTokens.clear();
+                this.entries.clear();
+                return;
+            }
+            const value = Reflect.get(artifact.entries, key);
+            const entry = admitStoredEntry(value, now, this.maximumAgeMs);
+            if (entry === undefined)
+                continue;
+            this.reserve(key);
+            this.entries.set(key, entry);
+        }
+    }
+    persist() {
+        if (this.store === undefined)
+            return;
+        const entries = Object.fromEntries([...this.entries].flatMap(([key, cached]) => cached.integrity === undefined
+            ? []
+            : [
+                [
+                    key,
+                    Object.freeze({
+                        ...(cached.sealed ?? cached.learned),
+                        integrity: cached.integrity,
+                    }),
+                ],
+            ]));
+        try {
+            this.store.write(Object.freeze({ version: 1, entries: Object.freeze(entries) }));
+        }
+        catch {
+            // A cache-store outage must not turn a valid invocation into a product failure.
+        }
+    }
+}
+function captureSessionRouteStore(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        typeof input.read !== 'function' ||
+        typeof input.write !== 'function') {
+        throw new TypeError('Session route store capability is invalid.');
+    }
+    const read = input.read;
+    const write = input.write;
+    return Object.freeze({
+        read: () => read.call(input),
+        write: (artifact) => write.call(input, artifact),
+    });
+}
+function admitStoredEntry(input, now, maximumAgeMs) {
+    try {
+        if (typeof input !== 'object' || input === null || Array.isArray(input))
+            return undefined;
+        const value = input;
+        if ((value.credential !== undefined && typeof value.credential !== 'string') ||
+            typeof value.expiresAt !== 'number' ||
+            !Number.isSafeInteger(value.expiresAt) ||
+            typeof value.integrity !== 'string' ||
+            !/^[A-Za-z0-9_-]{43}$/u.test(value.integrity)) {
+            return undefined;
+        }
+        const credentialExpiry = value.credential === undefined ? undefined : jwtExpiry(value.credential);
+        if (value.credential !== undefined && credentialExpiry === undefined)
+            return undefined;
+        const sealed = Object.freeze({
+            route: invocation.acceptRoute(value.route),
+            ...(value.credential === undefined ? {} : { credential: value.credential }),
+            expiresAt: value.expiresAt,
+        });
+        const expiresAt = Math.min(value.expiresAt, now + maximumAgeMs, refreshBoundary(credentialExpiry));
+        if (expiresAt <= now)
+            return undefined;
+        return Object.freeze({
+            learned: Object.freeze({
+                route: sealed.route,
+                ...(sealed.credential === undefined ? {} : { credential: sealed.credential }),
+                expiresAt,
+            }),
+            sealed,
+            integrity: value.integrity,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function refreshBoundary(credentialExpiry) {
+    return credentialExpiry === undefined
+        ? Number.POSITIVE_INFINITY
+        : credentialExpiry - DESTINATION_CREDENTIAL_REFRESH_SKEW_MS;
+}
+async function routeIntegrity(sourceCredential, key, learned) {
+    const webCrypto = typeof crypto === 'undefined' ? undefined : crypto;
+    if (webCrypto?.subtle === undefined) {
+        throw new TypeError('Persistent Session route integrity requires Web Crypto HMAC support.');
+    }
+    const algorithm = Object.freeze({ name: 'HMAC', hash: 'SHA-256' });
+    const cryptographicKey = await webCrypto.subtle.importKey('raw', new TextEncoder().encode(sourceCredential), algorithm, false, ['sign']);
+    const signature = await webCrypto.subtle.sign(algorithm, cryptographicKey, new TextEncoder().encode(integrityMaterial(key, learned)));
+    return encodeBase64Url(new Uint8Array(signature));
+}
+async function matchesIntegrity(sourceCredential, key, learned, expected) {
+    try {
+        return (await routeIntegrity(sourceCredential, key, learned)) === expected;
+    }
+    catch {
+        return false;
+    }
+}
+function integrityMaterial(key, learned) {
+    return JSON.stringify({
+        version: 1,
+        key,
+        route: learned.route,
+        ...(learned.credential === undefined ? {} : { credential: learned.credential }),
+        expiresAt: learned.expiresAt,
+    });
+}
+function encodeBase64Url(input) {
+    let binary = '';
+    for (const byte of input)
+        binary += String.fromCharCode(byte);
+    return globalThis.btoa(binary).replace(/\+/gu, '-').replace(/\//gu, '_').replace(/=+$/gu, '');
 }
 function canonicalDelegate(input) {
     return JSON.stringify({
@@ -83,10 +276,11 @@ function canonicalExpr(input) {
     return { kind: input.kind, operands: input.operands.map(canonicalExpr) };
 }
 async function digestText(input) {
-    if (globalThis.crypto?.subtle === undefined) {
+    const webCrypto = typeof crypto === 'undefined' ? undefined : crypto;
+    if (webCrypto?.subtle === undefined) {
         throw new TypeError('Session route caching requires Web Crypto SHA-256 support.');
     }
-    const bytes = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
+    const bytes = await webCrypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
     return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
 }
 function jwtExpiry(input) {
@@ -113,4 +307,3 @@ function decodeBase64(input) {
     }
     throw new TypeError('Session route caching requires base64 decoding support.');
 }
-//# sourceMappingURL=cache.js.map

package/dist/session/routing/dispatch.d.ts

@@ -1,35 +1,42 @@
 import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
-import type { Call, Result } from '../../client/index.js';
+import type { Result } from '../../client/index.js';
+import type { Fetch } from '../../transport/http/index.js';
 import type { SessionOperation, SessionPolicy } from '../context/index.js';
-import type { SessionDiscovery } from '../discovery/index.js';
-import type { SessionAuth } from './auth.js';
+import type { AuthExchange, SessionAuth } from './auth.js';
 import type { RouteCache } from './cache.js';
 import type { ClientPoolCapability } from './envelope.js';
-import type { SchemaExpectation } from './expectation.js';
 import type { SessionEnvelopeTransport, SessionRequestOptions } from './request.js';
+import { acceptCall } from '../../client/index.js';
 export interface SessionDispatcherOptions {
     readonly kernel: IssuerId;
     readonly sourceEndpoint: string;
     readonly pool: ClientPoolCapability;
     readonly websocketAvailable: boolean;
     readonly auth?: SessionAuth;
+    readonly exchange?: AuthExchange;
     readonly cache: RouteCache;
     readonly policy: Readonly<SessionPolicy>;
     readonly envelopeTransport: SessionEnvelopeTransport;
-    readonly discovery: SessionDiscovery;
     readonly requireOpen: () => void;
+    readonly streamingHttp: {
+        readonly fetch: Fetch;
+        readonly maximumResponseBytes: number;
+        readonly timeoutMs: number;
+    };
 }
 export declare class SessionDispatcher {
     private readonly state;
     constructor(state: SessionDispatcherOptions);
-    dispatch(input: Call, options: SessionRequestOptions, operation: SessionOperation, expected?: SchemaExpectation): Promise<Result>;
+    dispatch(input: Parameters<typeof acceptCall>[0], options: SessionRequestOptions, operation: SessionOperation): Promise<Result>;
+    /** Reuse Session authority and route recovery while forcing HTTP for streaming calls. */
+    dispatchHttp(input: Parameters<typeof acceptCall>[0], options: SessionRequestOptions, operation: SessionOperation, body?: Blob): Promise<Result>;
+    private dispatchWith;
     private dispatchSource;
     private followSource;
     private dispatchDestinationWithRecovery;
     private dispatchDestination;
-    private sourceKernel;
+    private streamingClientFor;
 }
 export declare function requireResultKind<Kind extends 'value' | 'stream' | 'binary'>(expected: Kind, result: Result): Extract<Result, {
     kind: Kind;
 }>;
-//# sourceMappingURL=dispatch.d.ts.map

package/dist/session/routing/dispatch.js

@@ -1,61 +1,88 @@
+import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
 import * as invocationProtocol from '@astrale-os/kernel-protocol/invocation';
-import { acceptCall, dispatchTrace, isAdmittedMissError, isAdmittedStaleRouteError, } from '../../client/index.js';
+import { acceptCall, Client, dispatchTrace, isAdmittedMissError, isAdmittedStaleRouteError, } from '../../client/index.js';
 import { ClientError, ResponseError } from '../../errors/index.js';
 import { runSessionOperation, sessionTransportOptions, allowEndpoint } from '../context/index.js';
 import { resolveAuth } from './auth.js';
-import { selectEnvelope } from './envelope.js';
+import { selectEnvelope, selectEnvelopeTarget } from './envelope.js';
 export class SessionDispatcher {
     state;
     constructor(state) {
         this.state = state;
     }
-    async dispatch(input, options, operation, expected) {
+    async dispatch(input, options, operation) {
+        return this.dispatchWith(input, options, operation);
+    }
+    /** Reuse Session authority and route recovery while forcing HTTP for streaming calls. */
+    async dispatchHttp(input, options, operation, body) {
+        return this.dispatchWith(input, options, operation, { body });
+    }
+    async dispatchWith(input, options, operation, streaming) {
         this.state.requireOpen();
         const call = acceptCall(input);
         // Authority is resolved before warm lookup so changed credentials or delegation cannot reuse a
-        // carrier minted for a different caller partition.
-        const auth = await resolveAuth(this.state.auth, call, operation);
-        const source = await this.sourceKernel(operation);
-        const cacheKey = await this.state.cache.key(source.issuer, call, auth, expected);
+        // carrier minted for a different caller partition. An exchanged credential is its own partition.
+        const resolved = await resolveAuth(this.state.auth, call, operation);
+        const auth = this.state.exchange === undefined
+            ? resolved
+            : await this.state.exchange.resolve(call, resolved, operation);
+        const source = this.state.kernel;
+        const cacheKey = await this.state.cache.key(source, call, auth);
         const dispatch = Object.freeze({
             call,
             auth,
             source,
             cacheKey,
-            ...(expected === undefined ? {} : { expected }),
         });
-        const learned = this.state.cache.get(cacheKey);
+        let learned = await this.state.cache.get(cacheKey, auth.credential);
         if (learned !== undefined) {
-            return this.dispatchDestinationWithRecovery(learned, dispatch, options, operation);
+            try {
+                requireCachedRoute(learned, source, call.target, streaming === undefined ? this.state.envelopeTransport : 'http', this.state.websocketAvailable, this.state.policy);
+            }
+            catch {
+                this.state.cache.delete(cacheKey);
+                learned = undefined;
+            }
         }
-        const result = await this.dispatchSource(dispatch, undefined, options, operation);
-        return this.followSource(result, dispatch, options, operation);
+        if (learned !== undefined) {
+            return this.dispatchDestinationWithRecovery(learned, dispatch, options, operation, undefined, streaming);
+        }
+        const result = await this.dispatchSource(dispatch, undefined, options, operation, streaming);
+        return this.followSource(result, dispatch, options, operation, streaming);
     }
-    async dispatchSource(state, routing, options, operation) {
+    async dispatchSource(state, routing, options, operation, streaming) {
         this.state.requireOpen();
         allowEndpoint(this.state.sourceEndpoint, this.state.policy);
-        const client = this.state.pool.clientFor(Object.freeze({ transport: 'http', url: this.state.sourceEndpoint }));
-        return runSessionOperation(operation, () => authenticated(client, state.auth.credential).dispatch(state.call, {
-            ...sessionTransportOptions(operation, options.idempotencyKey),
-            ...(state.auth.delegate === undefined ? {} : { delegate: state.auth.delegate }),
-            ...(routing === undefined ? {} : { routing }),
-            ...(state.expected === undefined ? {} : { schema: { revision: state.expected.revision } }),
-        }));
+        const client = streaming === undefined
+            ? this.state.pool.clientFor(Object.freeze({ transport: 'http', url: this.state.sourceEndpoint }))
+            : this.streamingClientFor(this.state.sourceEndpoint);
+        return runSessionOperation(operation, () => streaming?.body === undefined
+            ? authenticated(client, state.auth.credential).dispatch(state.call, {
+                ...sessionTransportOptions(operation, options.idempotencyKey),
+                ...(state.auth.delegate === undefined ? {} : { delegate: state.auth.delegate }),
+                ...(routing === undefined ? {} : { routing }),
+            })
+            : authenticated(client, state.auth.credential).dispatch(state.call, {
+                ...sessionTransportOptions(operation),
+                ...(state.auth.delegate === undefined ? {} : { delegate: state.auth.delegate }),
+                ...(routing === undefined ? {} : { routing }),
+                body: streaming.body,
+            }));
     }
-    async followSource(result, state, options, operation) {
+    async followSource(result, state, options, operation, streaming) {
         if (result.kind !== 'redirect')
             return result;
         const redirect = result.redirect;
-        if (redirect.route.via.issuer !== state.source.issuer) {
+        if (redirect.route.via.issuer !== state.source) {
             throw new ClientError('Redirect issuer differs from the session-pinned source Kernel identity.');
         }
-        requireExpectedPublication(redirect.route, state.expected);
-        const learned = this.state.cache.learn(state.cacheKey, redirect.route, redirect.credential);
-        return this.dispatchDestinationWithRecovery(learned, state, options, operation, redirect.trace);
+        requireTargetPublication(redirect.route, state.call.target);
+        const learned = await this.state.cache.learn(state.cacheKey, redirect.route, redirect.credential, state.auth.credential);
+        return this.dispatchDestinationWithRecovery(learned, state, options, operation, redirect.trace, streaming);
     }
-    async dispatchDestinationWithRecovery(learned, state, options, operation, trace) {
+    async dispatchDestinationWithRecovery(learned, state, options, operation, trace, streaming) {
         try {
-            return await this.dispatchDestination(learned, state.call, options, operation, state.expected, trace);
+            return await this.dispatchDestination(learned, state.call, options, operation, state.source, trace, streaming);
         }
         catch (cause) {
             const stale = isAdmittedStaleRouteError(cause);
@@ -75,36 +102,79 @@ export class SessionDispatcher {
                     stale: learned.route.via.publication.etag,
                 })
                 : undefined;
-            const refreshed = await this.dispatchSource(state, routing, options, operation);
-            return this.followSource(refreshed, state, options, operation);
+            const refreshed = await this.dispatchSource(state, routing, options, operation, streaming);
+            return this.followSource(refreshed, state, options, operation, streaming);
         }
     }
-    async dispatchDestination(learned, call, options, operation, expected, trace) {
-        if (learned.route.via.issuer !== (await this.sourceKernel(operation)).issuer) {
+    async dispatchDestination(learned, call, options, operation, source, trace, streaming) {
+        if (learned.route.via.issuer !== source) {
             throw new ClientError('Learned route issuer differs from the session-pinned source Kernel.');
         }
-        requireExpectedPublication(learned.route, expected);
-        const envelope = selectEnvelope(learned.route.endpoint, this.state.envelopeTransport, this.state.websocketAvailable, this.state.pool, this.state.policy);
+        requireTargetPublication(learned.route, call.target);
+        const destination = streaming === undefined
+            ? undefined
+            : selectEnvelopeTarget(learned.route.endpoint, 'http', this.state.websocketAvailable, this.state.policy);
+        const client = streaming === undefined
+            ? selectEnvelope(learned.route.endpoint, this.state.envelopeTransport, this.state.websocketAvailable, this.state.pool, this.state.policy).client
+            : destination?.transport === 'http'
+                ? this.streamingClientFor(destination.url)
+                : invalidStreamingDestination();
         const requestOptions = {
             ...sessionTransportOptions(operation, options.idempotencyKey),
             routing: learned.route.via,
         };
-        const result = await runSessionOperation(operation, () => trace === undefined
-            ? authenticated(envelope.client, learned.credential).dispatch(call, requestOptions)
-            : dispatchTrace(envelope.client, learned.credential, call, requestOptions, trace));
+        const binaryRequestOptions = {
+            ...sessionTransportOptions(operation),
+            routing: learned.route.via,
+        };
+        // The source has admitted this fingerprint against the exact Publication carried by Via.
+        // Pin that revision at the destination so existing Workers can execute the same admitted
+        // callable without understanding the newer fingerprint Target representation. The cache
+        // remains partitioned by the original fingerprint, and stale recovery re-admits it at source.
+        const destinationCall = typeof call.target !== 'string' && call.target.fingerprint !== undefined
+            ? {
+                ...call,
+                target: invocationProtocol.Target({
+                    callable: call.target.callable,
+                    revision: learned.route.via.publication.revision,
+                    ...(call.target.instance === undefined ? {} : { instance: call.target.instance }),
+                }),
+            }
+            : call;
+        const result = await runSessionOperation(operation, () => streaming?.body !== undefined
+            ? trace === undefined
+                ? authenticated(client, learned.credential).dispatch(destinationCall, {
+                    ...binaryRequestOptions,
+                    body: streaming.body,
+                })
+                : dispatchTrace(client, learned.credential, destinationCall, { ...binaryRequestOptions, body: streaming.body }, trace)
+            : trace === undefined
+                ? authenticated(client, learned.credential).dispatch(destinationCall, requestOptions)
+                : dispatchTrace(client, learned.credential, destinationCall, requestOptions, trace));
         if (result.kind === 'redirect') {
             throw new ClientError('A destination redirect is invalid; only the source Kernel may redirect.');
         }
         return result;
     }
-    async sourceKernel(operation) {
-        const snapshot = await this.state.discovery.snapshot(operation);
-        if (snapshot.kernel !== this.state.kernel) {
-            throw new ClientError('Session discovery returned another Kernel identity.');
-        }
-        return Object.freeze({ issuer: snapshot.publication.identity.issuer });
+    streamingClientFor(url) {
+        return new Client({
+            url,
+            fetch: this.state.streamingHttp.fetch,
+            timeoutMs: this.state.streamingHttp.timeoutMs,
+            maximumResponseBytes: this.state.streamingHttp.maximumResponseBytes,
+        });
     }
 }
+function invalidStreamingDestination() {
+    throw new ClientError('Streaming route has no HTTP endpoint.');
+}
+function requireCachedRoute(learned, source, target, envelopeTransport, websocketAvailable, policy) {
+    if (learned.route.via.issuer !== source) {
+        throw new ClientError('Learned route issuer differs from the session-pinned source Kernel.');
+    }
+    requireTargetPublication(learned.route, target);
+    selectEnvelopeTarget(learned.route.endpoint, envelopeTransport, websocketAvailable, policy);
+}
 function isRouteCompatibilityConflict(input) {
     if (!(input instanceof ResponseError))
         return false;
@@ -113,15 +183,16 @@ function isRouteCompatibilityConflict(input) {
         message: input.message,
         ...(input.data === undefined ? {} : { data: input.data }),
     });
-    return (failure?.data.code === invocationProtocol.SCHEMA_UPGRADE_REQUIRED ||
-        failure?.data.code === invocationProtocol.SCHEMA_REVISION_MISMATCH ||
+    return (failure?.data.code === invocationProtocol.SCHEMA_REVISION_MISMATCH ||
+        failure?.data.code === invocationProtocol.CALLABLE_FINGERPRINT_MISMATCH ||
         failure?.data.code === invocationProtocol.SERVICE_TRUST_REQUIRED);
 }
-function requireExpectedPublication(route, expected) {
-    if (expected === undefined)
+function requireTargetPublication(route, target) {
+    if (typeof target === 'string')
         return;
     const actual = route.via.publication;
-    if (actual.origin !== expected.origin || actual.revision !== expected.revision) {
+    if (actual.origin !== Key.origin(target.callable) ||
+        (target.revision !== undefined && actual.revision !== target.revision)) {
         throw new ClientError('Resolved route does not match the expected Schema revision.');
     }
 }
@@ -130,9 +201,11 @@ export function requireResultKind(expected, result) {
         return result;
     if (result.kind === 'stream')
         void result.stream.cancel(`Expected ${expected} result.`);
+    if (result.kind === 'binary' && !(result.value.body instanceof Uint8Array)) {
+        void result.value.body[Symbol.asyncIterator]().return?.();
+    }
     throw new ClientError(`Function returned ${result.kind}; ${expected} was required.`);
 }
 function authenticated(client, credential) {
     return credential === undefined ? client : client.as(credential);
 }
-//# sourceMappingURL=dispatch.js.map

package/dist/session/routing/envelope.d.ts

@@ -11,4 +11,5 @@ export interface EnvelopeSelection {
     readonly destination: ClientTarget;
 }
 export declare function selectEnvelope(endpoints: publication.InvocationEndpoints, preference: SessionEnvelopeTransport, websocketAvailable: boolean, pool: ClientPoolCapability, policy: Readonly<SessionPolicy>): EnvelopeSelection;
-//# sourceMappingURL=envelope.d.ts.map
+/** Resolve and admit one route endpoint without acquiring a transport Client. */
+export declare function selectEnvelopeTarget(endpoints: publication.InvocationEndpoints, preference: SessionEnvelopeTransport, websocketAvailable: boolean, policy: Readonly<SessionPolicy>): ClientTarget;

package/dist/session/routing/envelope.js

@@ -1,6 +1,19 @@
 import { ClientError } from '../../errors/index.js';
 import { allowEndpoint } from '../context/index.js';
 export function selectEnvelope(endpoints, preference, websocketAvailable, pool, policy) {
+    const destination = selectEnvelopeTarget(endpoints, preference, websocketAvailable, policy);
+    const client = pool.clientFor(destination);
+    if (client === null ||
+        typeof client !== 'object' ||
+        typeof client.dispatch !== 'function' ||
+        typeof client.as !== 'function' ||
+        typeof client.close !== 'function') {
+        throw new TypeError('Session client pool capability returned an invalid Client.');
+    }
+    return Object.freeze({ client, destination });
+}
+/** Resolve and admit one route endpoint without acquiring a transport Client. */
+export function selectEnvelopeTarget(endpoints, preference, websocketAvailable, policy) {
     let destination;
     if (preference === 'websocket') {
         if (endpoints.websocket === undefined) {
@@ -23,14 +36,5 @@ export function selectEnvelope(endpoints, preference, websocketAvailable, pool,
         allowEndpoint(endpoints.http, policy);
         destination = Object.freeze({ transport: 'http', url: endpoints.http });
     }
-    const client = pool.clientFor(destination);
-    if (client === null ||
-        typeof client !== 'object' ||
-        typeof client.dispatch !== 'function' ||
-        typeof client.as !== 'function' ||
-        typeof client.close !== 'function') {
-        throw new TypeError('Session client pool capability returned an invalid Client.');
-    }
-    return Object.freeze({ client, destination });
+    return destination;
 }
-//# sourceMappingURL=envelope.js.map

package/dist/session/routing/index.d.ts

@@ -1,7 +1,5 @@
-export { admitSessionAuth, resolveAuth, type Auth, type EffectiveAuth, type SessionAuth, } from './auth.js';
-export type { SchemaExpectation } from './expectation.js';
-export { RouteCache, type LearnedRoute } from './cache.js';
+export { admitSessionAuth, resolveAuth, type Auth, type AuthExchange, type EffectiveAuth, type SessionAuth, } from './auth.js';
+export { RouteCache, type LearnedRoute, type PersistedRoute, type SessionRouteArtifact, type SessionRouteStore, } from './cache.js';
 export { requireResultKind, SessionDispatcher, type SessionDispatcherOptions } from './dispatch.js';
 export { type ClientPoolCapability, type EnvelopeSelection } from './envelope.js';
-export { admitEnvelopeTransport, admitRequestOptions, type SessionEnvelopeTransport, type SessionRequestOptions, } from './request.js';
-//# sourceMappingURL=index.d.ts.map
+export { admitEnvelopeTransport, admitInvocationOptions, admitRequestOptions, type SessionEnvelopeTransport, type SessionRequestOptions, type SessionRequestOptionsWithBody, } from './request.js';

package/dist/session/routing/index.js

@@ -1,6 +1,5 @@
 export { admitSessionAuth, resolveAuth, } from './auth.js';
-export { RouteCache } from './cache.js';
+export { RouteCache, } from './cache.js';
 export { requireResultKind, SessionDispatcher } from './dispatch.js';
 export {} from './envelope.js';
-export { admitEnvelopeTransport, admitRequestOptions, } from './request.js';
-//# sourceMappingURL=index.js.map
+export { admitEnvelopeTransport, admitInvocationOptions, admitRequestOptions, } from './request.js';