@astrale-os/kernel-client 0.6.0-beta.1 → 0.6.0-beta.10

package/dist/session/discovery/publication.d.ts

@@ -1,22 +1,23 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { publication } from '@astrale-os/kernel-protocol';
 import type { Fetch } from '../../transport/http/index.js';
 import type { SessionOperation } from '../context/index.js';
 import { type SessionPolicy } from '../context/index.js';
 export interface PublicationDiscoveryOptions {
+    readonly kernel: IssuerId;
     readonly fetch: Fetch;
     readonly policy: Readonly<SessionPolicy>;
     readonly maximumBytes: number;
 }
 export declare class PublicationDiscovery {
     private readonly options;
-    private readonly publications;
+    private publication;
+    private revision;
     constructor(options: PublicationDiscoveryOptions);
-    current(url: string): publication.Publication | undefined;
-    get(url: string, operation: SessionOperation): Promise<publication.Publication>;
-    revalidate(url: string, operation: SessionOperation): Promise<publication.Publication>;
-    invalidate(url?: string): void;
+    current(): publication.Publication | undefined;
+    revalidate(operation: SessionOperation): Promise<publication.Publication>;
+    invalidate(): void;
     private fetch;
 }
 export declare function boundedResponse(response: Response, maximum: number, signal: AbortSignal): Promise<Uint8Array>;
 export declare function requireExactResponse(response: Response, expected: string, label: string): void;
-//# sourceMappingURL=publication.d.ts.map

package/dist/session/discovery/publication.js

@@ -1,39 +1,36 @@
-import { codecs, publication as publicationCodec } from '@astrale-os/kernel-protocol';
+import * as codecs from '@astrale-os/kernel-protocol/codecs';
+import * as publicationCodec from '@astrale-os/kernel-protocol/publication/publication';
 import { ClientError } from '../../errors/index.js';
-import { allowEndpoint, runSessionOperation } from '../context/index.js';
+import { allowEndpoint } from '../context/index.js';
+import { runAcquisition } from './transport.js';
 export class PublicationDiscovery {
     options;
-    publications = new Map();
+    publication;
+    revision = 0;
     constructor(options) {
         this.options = options;
     }
-    current(url) {
-        return this.publications.get(new URL(url).origin);
+    current() {
+        return this.publication;
     }
-    async get(url, operation) {
-        return this.current(url) ?? this.revalidate(url, operation);
-    }
-    async revalidate(url, operation) {
-        const origin = new URL(url).origin;
-        const previous = this.publications.get(origin);
-        const discovered = await this.fetch(origin, operation, previous);
-        const current = this.publications.get(origin);
-        if (current !== previous)
-            return current ?? this.revalidate(origin, operation);
+    async revalidate(operation) {
+        const revision = this.revision;
+        const previous = this.publication;
+        const discovered = await this.fetch(operation, previous);
+        if (revision !== this.revision)
+            return this.revalidate(operation);
         const retained = previous?.etag === discovered.etag ? previous : discovered;
-        this.publications.set(origin, retained);
+        this.publication = retained;
         return retained;
     }
-    invalidate(url) {
-        if (url === undefined)
-            this.publications.clear();
-        else
-            this.publications.delete(new URL(url).origin);
+    invalidate() {
+        this.revision += 1;
+        this.publication = undefined;
     }
-    async fetch(origin, operation, previous) {
-        const url = new URL(publicationCodec.PATH, origin).toString();
+    async fetch(operation, previous) {
+        const url = publicationCodec.url(this.options.kernel);
         allowEndpoint(url, this.options.policy);
-        const response = await runSessionOperation(operation, (signal) => this.options.fetch(url, {
+        const response = await runAcquisition(operation, 'publication', 'unknown', 'Kernel Publication could not be retrieved.', (signal) => this.options.fetch(url, {
             headers: {
                 accept: 'application/json',
                 ...(previous === undefined ? {} : { 'if-none-match': `"${previous.etag}"` }),
@@ -55,8 +52,11 @@ export class PublicationDiscovery {
         if (!response.ok) {
             throw new ClientError(`Publication discovery returned HTTP ${response.status}.`);
         }
-        const body = await runSessionOperation(operation, (signal) => boundedResponse(response, this.options.maximumBytes, signal));
+        const body = await runAcquisition(operation, 'publication', 'receive', 'Kernel Publication response could not be read.', (signal) => boundedResponse(response, this.options.maximumBytes, signal));
         const admitted = publicationCodec.accept(codecs.json.decode(body));
+        if (admitted.identity.issuer !== this.options.kernel) {
+            throw new ClientError('Publication issuer differs from the requested Kernel issuer.');
+        }
         const etag = response.headers.get('etag');
         if (etag !== null && etag !== `"${admitted.etag}"`) {
             throw new ClientError('Publication response ETag differs from its canonical content.');
@@ -121,4 +121,3 @@ function join(parts, length) {
     }
     return output;
 }
-//# sourceMappingURL=publication.js.map

package/dist/session/discovery/snapshot.d.ts

@@ -1,12 +1,12 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { bundle } from '@astrale-os/kernel-dsl/v1';
 import type { publication } from '@astrale-os/kernel-protocol';
 import type { ViewCatalog } from '../views/index.js';
 /** Coherent public observation acquired through one Client Session at one Publication ETag. */
 export interface SessionSnapshot {
-    readonly url: string;
+    readonly kernel: IssuerId;
     readonly publication: publication.Publication;
     readonly bundle: bundle.Bundle;
     readonly views: ViewCatalog;
 }
-export declare function createSessionSnapshot(url: string, publication: publication.Publication, artifact: bundle.Bundle, views: ViewCatalog): SessionSnapshot;
-//# sourceMappingURL=snapshot.d.ts.map
+export declare function createSessionSnapshot(kernel: IssuerId, publication: publication.Publication, artifact: bundle.Bundle, views: ViewCatalog): SessionSnapshot;

package/dist/session/discovery/snapshot.js

@@ -1,4 +1,3 @@
-export function createSessionSnapshot(url, publication, artifact, views) {
-    return Object.freeze({ url, publication, bundle: artifact, views });
+export function createSessionSnapshot(kernel, publication, artifact, views) {
+    return Object.freeze({ kernel, publication, bundle: artifact, views });
 }
-//# sourceMappingURL=snapshot.js.map

package/dist/session/discovery/transport.d.ts

@@ -0,0 +1,6 @@
+import type { TransportPhase } from '../../errors/index.js';
+import type { SessionOperation } from '../context/index.js';
+type AcquisitionResource = 'publication' | 'bundle';
+/** Normalize only unknown failures from one injected acquisition capability. */
+export declare function runAcquisition<Result>(operation: SessionOperation, resource: AcquisitionResource, phase: Extract<TransportPhase, 'receive' | 'unknown'>, message: string, task: (signal: AbortSignal) => Result | PromiseLike<Result>): Promise<Result>;
+export {};

package/dist/session/discovery/transport.js

@@ -0,0 +1,13 @@
+import { ClientError, TransportError } from '../../errors/index.js';
+import { runSessionOperation } from '../context/index.js';
+/** Normalize only unknown failures from one injected acquisition capability. */
+export async function runAcquisition(operation, resource, phase, message, task) {
+    try {
+        return await runSessionOperation(operation, task);
+    }
+    catch (cause) {
+        if (cause instanceof ClientError)
+            throw cause;
+        throw TransportError.acquisition(message, { cause, phase, resource });
+    }
+}

package/dist/session/index.d.ts

@@ -1,6 +1,10 @@
 export type { SessionControlOptions, SessionPolicy } from './context/index.js';
+export { bindSession, type BoundClientSession, type BoundSessionControls, type BoundSessionSource, } from './bound.js';
+export type { ReadyInstallation } from '../schema/index.js';
 export type { SessionSnapshot } from './discovery/index.js';
 export type { Auth, SessionAuth, SessionEnvelopeTransport, SessionRequestOptions, } from './routing/index.js';
-export { ClientSession, type ClientSessionOptions } from './session.js';
+export { ClientSession, connect, type ClientSessionOptions, type ConnectOptions, } from './session.js';
+export type { CallableReference, InputOfReference, InstanceCallableReference, OutputOfReference, } from './reference.js';
+export { reference } from './reference.js';
 export type { ResolvedView, ViewCatalog } from './views/index.js';
-//# sourceMappingURL=index.d.ts.map
+export type { DomainBinding } from '../graph/domain/index.js';

package/dist/session/index.js

@@ -1,2 +1,3 @@
-export { ClientSession } from './session.js';
-//# sourceMappingURL=index.js.map
+export { bindSession, } from './bound.js';
+export { ClientSession, connect, } from './session.js';
+export { reference } from './reference.js';

package/dist/session/reference.d.ts

@@ -0,0 +1,36 @@
+import type { Path as PathValue, PathLike } from '@astrale-os/kernel-core/path';
+import type { CallableInputOf, CallableOutputOf, CallableResultOf, Domain, MethodInheritance, ResolvedFunction, ResolvedMethod } from '@astrale-os/kernel-dsl/v1';
+import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import { type Key as KeyType } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { Binary, Input, Result } from '../client/index.js';
+declare const REFERENCE_INPUT: unique symbol;
+declare const REFERENCE_OUTPUT: unique symbol;
+export interface CallableReference<InputValue extends Input = Input, Output = unknown> {
+    readonly origin: KeyType.Origin;
+    readonly revision: Revision;
+    readonly callable: KeyType.Callable;
+    readonly target: PathValue;
+    readonly outputMode: Exclude<Result['kind'], 'redirect'>;
+    readonly [REFERENCE_INPUT]?: InputValue;
+    readonly [REFERENCE_OUTPUT]?: Output;
+}
+export interface InstanceCallableReference<InputValue extends Input = Input, Output = unknown> {
+    (receiver: PathLike): CallableReference<InputValue, Output>;
+    readonly origin: KeyType.Origin;
+    readonly revision: Revision;
+    readonly callable: KeyType.Callable;
+    readonly outputMode: Exclude<Result['kind'], 'redirect'>;
+}
+export type InputOfReference<Reference extends CallableReference> = Reference extends CallableReference<infer InputValue, unknown> ? InputValue : never;
+export type OutputOfReference<Reference extends CallableReference> = Reference extends CallableReference<infer _Input, infer Output> ? Output : never;
+type ReferenceInput<Callable> = unknown extends CallableInputOf<Callable> ? Input : Extract<CallableInputOf<Callable>, Input>;
+type ReferenceOutput<Callable> = unknown extends CallableOutputOf<Callable> ? unknown : CallableResultOf<Callable, Binary>;
+type ExecutableMethodInheritance = Exclude<MethodInheritance, 'abstract'>;
+type ExecutableStaticMethod = ResolvedMethod<unknown, unknown, true, ExecutableMethodInheritance>;
+type ExecutableInstanceMethod = ResolvedMethod<unknown, unknown, false, ExecutableMethodInheritance>;
+/** Project one exact resolved Function or static Method into a typed Client reference. */
+export declare function reference<const Callable extends ResolvedFunction | ExecutableStaticMethod>(domain: Pick<Domain, 'origin' | 'revision'>, callable: Callable): CallableReference<ReferenceInput<Callable>, ReferenceOutput<Callable>>;
+/** Project one exact resolved instance Method into a receiver-bound typed Client reference. */
+export declare function reference<const Callable extends ExecutableInstanceMethod>(domain: Pick<Domain, 'origin' | 'revision'>, callable: Callable): InstanceCallableReference<ReferenceInput<Callable>, ReferenceOutput<Callable>>;
+export declare function admitReference(input: CallableReference): CallableReference;
+export {};

package/dist/session/reference.js

@@ -0,0 +1,74 @@
+import { Path } from '@astrale-os/kernel-core/path';
+import { callableAddress, Key, patterns, } from '@astrale-os/kernel-dsl/v1/addressing';
+export function reference(domain, callable) {
+    if ('owner' in callable && callable.inheritance === 'abstract')
+        invalid();
+    const common = Object.freeze({
+        origin: domain.origin,
+        revision: domain.revision,
+        callable: callable.key,
+        outputMode: callable.output.mode,
+    });
+    if ('owner' in callable && !callable.static) {
+        const bind = (receiver) => admitReference({
+            ...common,
+            target: Path.instanceMethod(Path.from(receiver), callable.name),
+        });
+        return Object.assign(bind, common);
+    }
+    const target = 'owner' in callable
+        ? Path.staticMethod(Path.project(callable.owner.ref), callable.name)
+        : Path.project(callable.ref);
+    return admitReference({ ...common, target });
+}
+export function admitReference(input) {
+    if (input === null || typeof input !== 'object')
+        invalid();
+    if (typeof input.origin !== 'string' ||
+        !patterns.origin.test(input.origin) ||
+        typeof input.revision !== 'string' ||
+        !patterns.revision.test(input.revision) ||
+        typeof input.callable !== 'string' ||
+        !Key.is(input.callable) ||
+        Key.origin(input.callable) !== input.origin ||
+        !['value', 'stream', 'binary'].includes(input.outputMode))
+        invalid();
+    const target = Path.from(input.target);
+    if (!matchesCallable(target, input.callable))
+        invalid();
+    return Object.freeze({
+        origin: input.origin,
+        revision: input.revision,
+        callable: input.callable,
+        target,
+        outputMode: input.outputMode,
+    });
+}
+function matchesCallable(target, callable) {
+    const coordinate = callableAddress(callable);
+    const { anchor, steps } = target.ast;
+    const last = steps.at(-1);
+    if (coordinate.kind === 'method') {
+        if (last?.kind !== 'method' || last.name !== coordinate.name)
+            return false;
+        if (last.dispatch === 'instance')
+            return true;
+        const owner = steps.at(-2);
+        return (anchor.kind === 'domain' &&
+            anchor.origin === Key.origin(callable) &&
+            steps.length === 2 &&
+            owner?.kind === 'projection' &&
+            owner.projection.kind === 'class' &&
+            owner.projection.name === coordinate.owner.name);
+    }
+    const projection = steps[0];
+    return (anchor.kind === 'domain' &&
+        anchor.origin === Key.origin(callable) &&
+        steps.length === 1 &&
+        projection?.kind === 'projection' &&
+        projection.projection.kind === 'function' &&
+        projection.projection.name === coordinate.name);
+}
+function invalid() {
+    throw new TypeError('Callable reference is invalid.');
+}

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

@@ -1,4 +1,4 @@
-import type { invocation } from '@astrale-os/kernel-protocol';
+import type * as invocation from '@astrale-os/kernel-protocol/invocation';
 import type { SessionOperation } from '../context/index.js';
 export interface Auth {
     readonly credential?: string;
@@ -16,4 +16,3 @@ export interface EffectiveAuth {
 }
 export declare function admitSessionAuth(input: SessionAuth | undefined): SessionAuth | undefined;
 export declare function resolveAuth(resolver: SessionAuth | undefined, call: invocation.Call, operation: SessionOperation): Promise<EffectiveAuth>;
-//# sourceMappingURL=auth.d.ts.map

package/dist/session/routing/auth.js

@@ -1,4 +1,4 @@
-import { invocation as protocol } from '@astrale-os/kernel-protocol';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
 import { ClientError } from '../../errors/index.js';
 import { runSessionOperation } from '../context/index.js';
 export function admitSessionAuth(input) {
@@ -33,11 +33,7 @@ export async function resolveAuth(resolver, call, operation) {
     if (credential === undefined)
         return Object.freeze({});
     const delegate = input.delegate === undefined
-        ? protocol.acceptDelegate({
-            ttlSeconds: resolver.ttlSeconds,
-            delegation: { kind: 'identity', self: true },
-        })
+        ? protocol.acceptDelegate({ ttlSeconds: resolver.ttlSeconds })
         : protocol.acceptDelegate(input.delegate);
     return Object.freeze({ credential, delegate });
 }
-//# sourceMappingURL=auth.js.map

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

@@ -1,5 +1,6 @@
 import type { invocation } from '@astrale-os/kernel-protocol';
 import type { EffectiveAuth } from './auth.js';
+import type { SchemaExpectation } from './expectation.js';
 export interface LearnedRoute {
     readonly route: invocation.Route;
     readonly credential?: string;
@@ -11,10 +12,9 @@ export declare class RouteCache {
     private readonly maximumSize;
     private readonly entries;
     constructor(maximumAgeMs: number, maximumSize?: number);
-    key(source: string, call: invocation.Call, auth: EffectiveAuth): Promise<string>;
+    key(source: string, call: invocation.Call, auth: EffectiveAuth, expected?: SchemaExpectation): Promise<string>;
     get(key: string, now?: number): LearnedRoute | undefined;
     learn(key: string, route: invocation.Route, credential: string | undefined, now?: number): LearnedRoute;
     delete(key: string): void;
     clear(): void;
 }
-//# sourceMappingURL=cache.d.ts.map

package/dist/session/routing/cache.js

@@ -8,10 +8,16 @@ export class RouteCache {
         this.maximumAgeMs = maximumAgeMs;
         this.maximumSize = maximumSize;
     }
-    async key(source, call, auth) {
+    async key(source, call, auth, expected) {
         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]);
+        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);
@@ -58,7 +64,7 @@ export class RouteCache {
 function canonicalDelegate(input) {
     return JSON.stringify({
         ttlSeconds: input.ttlSeconds,
-        delegation: canonicalExpr(input.delegation),
+        ...(input.attenuation === undefined ? {} : { attenuation: canonicalExpr(input.attenuation) }),
     });
 }
 function canonicalExpr(input) {
@@ -107,4 +113,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,15 +1,15 @@
-import type { IssuerId } from '@astrale-os/kernel-core/auth';
-import type { Result } from '@astrale-os/kernel-ports/functions';
-import type { Call } from '../../client/index.js';
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { Call, Result } from '../../client/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 { RouteCache } from './cache.js';
 import type { ClientPoolCapability } from './envelope.js';
+import type { SchemaExpectation } from './expectation.js';
 import type { SessionEnvelopeTransport, SessionRequestOptions } from './request.js';
 export interface SessionDispatcherOptions {
-    readonly url: string;
-    readonly sourceIssuer?: IssuerId;
+    readonly kernel: IssuerId;
+    readonly sourceEndpoint: string;
     readonly pool: ClientPoolCapability;
     readonly websocketAvailable: boolean;
     readonly auth?: SessionAuth;
@@ -22,7 +22,7 @@ export interface SessionDispatcherOptions {
 export declare class SessionDispatcher {
     private readonly state;
     constructor(state: SessionDispatcherOptions);
-    dispatch(input: Call, options: SessionRequestOptions, operation: SessionOperation): Promise<Result>;
+    dispatch(input: Call, options: SessionRequestOptions, operation: SessionOperation, expected?: SchemaExpectation): Promise<Result>;
     private dispatchSource;
     private followSource;
     private dispatchDestinationWithRecovery;
@@ -32,4 +32,3 @@ export declare class SessionDispatcher {
 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,5 +1,6 @@
-import { acceptCall, isAdmittedMissError, isAdmittedStaleRouteError } from '../../client/index.js';
-import { ClientError } from '../../errors/index.js';
+import * as invocationProtocol from '@astrale-os/kernel-protocol/invocation';
+import { acceptCall, 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';
@@ -8,15 +9,21 @@ export class SessionDispatcher {
     constructor(state) {
         this.state = state;
     }
-    async dispatch(input, options, operation) {
+    async dispatch(input, options, operation, expected) {
         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);
-        const dispatch = Object.freeze({ call, auth, source, cacheKey });
+        const cacheKey = await this.state.cache.key(source.issuer, call, auth, expected);
+        const dispatch = Object.freeze({
+            call,
+            auth,
+            source,
+            cacheKey,
+            ...(expected === undefined ? {} : { expected }),
+        });
         const learned = this.state.cache.get(cacheKey);
         if (learned !== undefined) {
             return this.dispatchDestinationWithRecovery(learned, dispatch, options, operation);
@@ -26,12 +33,13 @@ export class SessionDispatcher {
     }
     async dispatchSource(state, routing, options, operation) {
         this.state.requireOpen();
-        allowEndpoint(this.state.url, this.state.policy);
-        const client = this.state.pool.clientFor(Object.freeze({ transport: 'http', url: this.state.url }));
+        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 } }),
         }));
     }
     async followSource(result, state, options, operation) {
@@ -41,16 +49,21 @@ export class SessionDispatcher {
         if (redirect.route.via.issuer !== state.source.issuer) {
             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);
+        return this.dispatchDestinationWithRecovery(learned, state, options, operation, redirect.trace);
     }
-    async dispatchDestinationWithRecovery(learned, state, options, operation) {
+    async dispatchDestinationWithRecovery(learned, state, options, operation, trace) {
         try {
-            return await this.dispatchDestination(learned, state.call, options, operation);
+            return await this.dispatchDestination(learned, state.call, options, operation, state.expected, trace);
         }
         catch (cause) {
             const stale = isAdmittedStaleRouteError(cause);
             const miss = isAdmittedMissError(cause);
+            if (isRouteCompatibilityConflict(cause)) {
+                this.state.cache.delete(state.cacheKey);
+                throw cause;
+            }
             if (!stale && !miss)
                 throw cause;
             this.state.cache.delete(state.cacheKey);
@@ -66,26 +79,50 @@ export class SessionDispatcher {
             return this.followSource(refreshed, state, options, operation);
         }
     }
-    async dispatchDestination(learned, call, options, operation) {
+    async dispatchDestination(learned, call, options, operation, expected, trace) {
         if (learned.route.via.issuer !== (await this.sourceKernel(operation)).issuer) {
             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);
-        const result = await runSessionOperation(operation, () => authenticated(envelope.client, learned.credential).dispatch(call, {
+        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));
         if (result.kind === 'redirect') {
             throw new ClientError('A destination redirect is invalid; only the source Kernel may redirect.');
         }
         return result;
     }
     async sourceKernel(operation) {
-        if (this.state.sourceIssuer !== undefined) {
-            return Object.freeze({ issuer: this.state.sourceIssuer });
+        const snapshot = await this.state.discovery.snapshot(operation);
+        if (snapshot.kernel !== this.state.kernel) {
+            throw new ClientError('Session discovery returned another Kernel identity.');
         }
-        const discovered = await this.state.discovery.discover(this.state.url, operation);
-        return Object.freeze({ issuer: discovered.publication.identity.issuer });
+        return Object.freeze({ issuer: snapshot.publication.identity.issuer });
+    }
+}
+function isRouteCompatibilityConflict(input) {
+    if (!(input instanceof ResponseError))
+        return false;
+    const failure = invocationProtocol.serviceErrorOf({
+        code: input.code,
+        message: input.message,
+        ...(input.data === undefined ? {} : { data: input.data }),
+    });
+    return (failure?.data.code === invocationProtocol.SCHEMA_UPGRADE_REQUIRED ||
+        failure?.data.code === invocationProtocol.SCHEMA_REVISION_MISMATCH ||
+        failure?.data.code === invocationProtocol.SERVICE_TRUST_REQUIRED);
+}
+function requireExpectedPublication(route, expected) {
+    if (expected === undefined)
+        return;
+    const actual = route.via.publication;
+    if (actual.origin !== expected.origin || actual.revision !== expected.revision) {
+        throw new ClientError('Resolved route does not match the expected Schema revision.');
     }
 }
 export function requireResultKind(expected, result) {
@@ -98,4 +135,3 @@ export function requireResultKind(expected, result) {
 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,3 @@ 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

package/dist/session/routing/envelope.js

@@ -33,4 +33,3 @@ export function selectEnvelope(endpoints, preference, websocketAvailable, pool,
     }
     return Object.freeze({ client, destination });
 }
-//# sourceMappingURL=envelope.js.map

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

@@ -0,0 +1,6 @@
+import type { Key, Revision } from '@astrale-os/kernel-dsl/v1';
+/** Private static-consumer expectation carried only by ClientSession.invoke. */
+export interface SchemaExpectation {
+    readonly origin: Key.Origin;
+    readonly revision: Revision;
+}

package/dist/session/routing/expectation.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,6 +1,6 @@
 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 { 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

package/dist/session/routing/index.js

@@ -3,4 +3,3 @@ 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

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

@@ -1,4 +1,4 @@
-import type { invocation } from '@astrale-os/kernel-protocol';
+import type * as invocation from '@astrale-os/kernel-protocol/invocation';
 import type { SessionControlOptions } from '../context/index.js';
 export type SessionEnvelopeTransport = 'auto' | 'http' | 'websocket';
 export interface SessionRequestOptions extends SessionControlOptions {
@@ -6,4 +6,3 @@ export interface SessionRequestOptions extends SessionControlOptions {
 }
 export declare function admitRequestOptions(input?: SessionRequestOptions): Readonly<SessionRequestOptions>;
 export declare function admitEnvelopeTransport(input: SessionEnvelopeTransport): SessionEnvelopeTransport;
-//# sourceMappingURL=request.d.ts.map

package/dist/session/routing/request.js

@@ -1,4 +1,4 @@
-import { invocation as invocationProtocol } from '@astrale-os/kernel-protocol';
+import * as invocationProtocol from '@astrale-os/kernel-protocol/invocation';
 import { admitControlOptions } from '../context/index.js';
 export function admitRequestOptions(input = {}) {
     if (input === null || typeof input !== 'object' || Array.isArray(input)) {
@@ -23,4 +23,3 @@ export function admitEnvelopeTransport(input) {
     }
     return input;
 }
-//# sourceMappingURL=request.js.map