@astrale-os/kernel-client 0.6.0-beta.81 → 0.6.0-beta.83

package/dist/session/routing/cache.js

@@ -19,12 +19,12 @@ export class RouteCache {
         const delegate = auth.delegate === undefined ? 'anonymous' : await digestText(canonicalDelegate(auth.delegate));
         return JSON.stringify([source, call.target, credential, delegate]);
     }
-    async get(key, sourceCredential, now = Date.now()) {
+    async get(key, sourceCredential, now, operationDeadline) {
         const cached = this.entries.get(key);
         if (cached === undefined)
             return undefined;
         const token = this.keyTokens.get(key);
-        if (cached.learned.expiresAt <= now) {
+        if (cached.learned.expiresAt <= (now ?? Date.now())) {
             this.invalidate(key);
             return undefined;
         }
@@ -38,6 +38,17 @@ export class RouteCache {
                 this.invalidate(key);
                 return undefined;
             }
+            // HMAC verification can outlast route age. Check the exact-entry fence before live facts.
+            if (cached.learned.expiresAt <= (now ?? Date.now())) {
+                this.invalidate(key);
+                return undefined;
+            }
+        }
+        if (operationDeadline !== undefined &&
+            cached.credentialRefreshBoundary !== undefined &&
+            cached.credentialRefreshBoundary <= operationDeadline) {
+            // This operation needs a fresh carrier; a shorter concurrent operation may still reuse it.
+            return undefined;
         }
         this.entries.delete(key);
         this.entries.set(key, cached);
@@ -45,6 +56,7 @@ export class RouteCache {
     }
     async learn(key, route, credential, sourceCredential, now = Date.now()) {
         const credentialExpiry = credential === undefined ? undefined : jwtExpiry(credential);
+        const credentialRefreshBoundary = credentialExpiry === undefined ? undefined : refreshBoundary(credentialExpiry);
         const expiresAt = Math.min(now + this.maximumAgeMs, refreshBoundary(credentialExpiry));
         const entry = Object.freeze({
             route,
@@ -79,6 +91,7 @@ export class RouteCache {
         }
         this.entries.set(key, Object.freeze({
             learned: entry,
+            ...(credentialRefreshBoundary === undefined ? {} : { credentialRefreshBoundary }),
             ...(integrity === undefined ? {} : { sealed: entry, integrity }),
         }));
         this.persist();
@@ -210,6 +223,9 @@ function admitStoredEntry(input, now, maximumAgeMs) {
             }),
             sealed,
             integrity: value.integrity,
+            ...(credentialExpiry === undefined
+                ? {}
+                : { credentialRefreshBoundary: refreshBoundary(credentialExpiry) }),
         });
     }
     catch {

package/dist/session/routing/dispatch.js

@@ -1,8 +1,8 @@
 import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
 import * as invocationProtocol from '@astrale-os/kernel-protocol/invocation';
-import { acceptCall, Client, dispatchTrace, isAdmittedMissError, isAdmittedStaleRouteError, } from '../../client/index.js';
+import { acceptCall, Client, dispatchTrace, isAdmittedDeploymentRetiredError, isAdmittedMissError, isAdmittedStaleRouteError, } from '../../client/index.js';
 import { ClientError, ResponseError } from '../../errors/index.js';
-import { runSessionOperation, sessionTransportOptions, allowEndpoint } from '../context/index.js';
+import { runSessionOperation, remainingSessionTime, sessionTransportOptions, allowEndpoint, } from '../context/index.js';
 import { resolveAuth } from './auth.js';
 import { selectEnvelope, selectEnvelopeTarget } from './envelope.js';
 export class SessionDispatcher {
@@ -27,14 +27,14 @@ export class SessionDispatcher {
             ? 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 cacheKey = await runSessionOperation(operation, () => this.state.cache.key(source, call, auth));
         const dispatch = Object.freeze({
             call,
             auth,
             source,
             cacheKey,
         });
-        let learned = await this.state.cache.get(cacheKey, auth.credential);
+        let learned = await runSessionOperation(operation, () => this.state.cache.get(cacheKey, auth.credential, undefined, operation.deadline));
         if (learned !== undefined) {
             try {
                 requireCachedRoute(learned, source, call.target, streaming === undefined ? this.state.envelopeTransport : 'http', this.state.websocketAvailable, this.state.policy);
@@ -52,6 +52,7 @@ export class SessionDispatcher {
     }
     async dispatchSource(state, routing, options, operation, streaming) {
         this.state.requireOpen();
+        remainingSessionTime(operation);
         allowEndpoint(this.state.sourceEndpoint, this.state.policy);
         const client = streaming === undefined
             ? this.state.pool.clientFor(Object.freeze({ transport: 'http', url: this.state.sourceEndpoint }))
@@ -77,7 +78,7 @@ export class SessionDispatcher {
             throw new ClientError('Redirect issuer differs from the session-pinned source Kernel identity.');
         }
         requireTargetPublication(redirect.route, state.call.target);
-        const learned = await this.state.cache.learn(state.cacheKey, redirect.route, redirect.credential, state.auth.credential);
+        const learned = await runSessionOperation(operation, () => 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, streaming) {
@@ -85,28 +86,29 @@ export class SessionDispatcher {
             return await this.dispatchDestination(learned, state.call, options, operation, state.source, trace, streaming);
         }
         catch (cause) {
-            const stale = isAdmittedStaleRouteError(cause);
-            const miss = isAdmittedMissError(cause);
-            if (isRouteCompatibilityConflict(cause)) {
-                this.state.cache.delete(state.cacheKey);
+            const control = routingControl(cause);
+            if (control === undefined) {
+                if (isRouteCompatibilityConflict(cause))
+                    this.state.cache.delete(state.cacheKey);
                 throw cause;
             }
-            if (!stale && !miss)
-                throw cause;
             this.state.cache.delete(state.cacheKey);
             if (!operation.claimRecovery())
                 throw cause;
-            const routing = stale
-                ? Object.freeze({
+            // A stale or retired route names the release the destination no longer serves; a miss
+            // names a Path, so the source receives no digest for it.
+            const routing = control === 'miss'
+                ? undefined
+                : Object.freeze({
                     kind: 'refresh',
-                    stale: learned.route.via.publication.etag,
-                })
-                : undefined;
+                    stale: invocationProtocol.routedDigest(learned.route.via),
+                });
             const refreshed = await this.dispatchSource(state, routing, options, operation, streaming);
             return this.followSource(refreshed, state, options, operation, streaming);
         }
     }
     async dispatchDestination(learned, call, options, operation, source, trace, streaming) {
+        remainingSessionTime(operation);
         if (learned.route.via.issuer !== source) {
             throw new ClientError('Learned route issuer differs from the session-pinned source Kernel.');
         }
@@ -127,30 +129,16 @@ export class SessionDispatcher {
             ...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, {
+                ? authenticated(client, learned.credential).dispatch(call, {
                     ...binaryRequestOptions,
                     body: streaming.body,
                 })
-                : dispatchTrace(client, learned.credential, destinationCall, { ...binaryRequestOptions, body: streaming.body }, trace)
+                : dispatchTrace(client, learned.credential, call, { ...binaryRequestOptions, body: streaming.body }, trace)
             : trace === undefined
-                ? authenticated(client, learned.credential).dispatch(destinationCall, requestOptions)
-                : dispatchTrace(client, learned.credential, destinationCall, requestOptions, trace));
+                ? authenticated(client, learned.credential).dispatch(call, requestOptions)
+                : dispatchTrace(client, learned.credential, call, requestOptions, trace));
         if (result.kind === 'redirect') {
             throw new ClientError('A destination redirect is invalid; only the source Kernel may redirect.');
         }
@@ -175,6 +163,20 @@ function requireCachedRoute(learned, source, target, envelopeTransport, websocke
     requireTargetPublication(learned.route, target);
     selectEnvelopeTarget(learned.route.endpoint, envelopeTransport, websocketAvailable, policy);
 }
+/** The privately witnessed pre-handler control a destination failure carries, if any. */
+function routingControl(input) {
+    if (isAdmittedStaleRouteError(input))
+        return 'stale';
+    if (isAdmittedMissError(input))
+        return 'miss';
+    if (isAdmittedDeploymentRetiredError(input))
+        return 'retired';
+    return undefined;
+}
+/**
+ * A failure that proves the warm route can no longer serve this call without witnessing a
+ * pre-handler control: the route is evicted for later calls, but the invocation is never replayed.
+ */
 function isRouteCompatibilityConflict(input) {
     if (!(input instanceof ResponseError))
         return false;
@@ -183,17 +185,16 @@ function isRouteCompatibilityConflict(input) {
         message: input.message,
         ...(input.data === undefined ? {} : { data: input.data }),
     });
-    return (failure?.data.code === invocationProtocol.SCHEMA_REVISION_MISMATCH ||
-        failure?.data.code === invocationProtocol.CALLABLE_FINGERPRINT_MISMATCH ||
-        failure?.data.code === invocationProtocol.SERVICE_TRUST_REQUIRED);
+    return (failure?.data.code === invocationProtocol.CALLABLE_FINGERPRINT_MISMATCH ||
+        failure?.data.code === invocationProtocol.SERVICE_TRUST_REQUIRED ||
+        failure?.data.code === invocationProtocol.DEPLOYMENT_RETIRED);
 }
 function requireTargetPublication(route, target) {
     if (typeof target === 'string')
         return;
-    const actual = route.via.publication;
-    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.');
+    const actual = 'release' in route.via ? route.via.release : route.via.publication;
+    if (actual.origin !== Key.origin(target.callable)) {
+        throw new ClientError('Resolved route does not match the Target origin.');
     }
 }
 export function requireResultKind(expected, result) {

package/dist/session/session.d.ts

@@ -13,7 +13,7 @@ import type { WebSocketConstructor } from '../transport/websocket/index.js';
 import type { ContentApi } from './content.js';
 import type { SessionControlOptions, SessionPolicy } from './context/index.js';
 import type { SessionCredential } from './credential/index.js';
-import type { SessionSnapshot } from './discovery/index.js';
+import type { IntrinsicRelease, SessionSnapshot } from './discovery/index.js';
 import type { SessionExchangeOptions, SessionExchangeRequest } from './exchange/index.js';
 import type { CallableReference, InputModeOfReference, InputOfReference, OutputOfReference } from './reference.js';
 import type { SessionRouteStore, SessionAuth, SessionEnvelopeTransport, SessionRequestOptions, SessionRequestOptionsWithBody } from './routing/index.js';
@@ -29,7 +29,8 @@ export interface ClientSessionOptions {
     /**
      * Present each Domain callable with a credential its declaring Domain exchanges for the `auth`
      * caller, so the Domain is the principal and the caller is `auth`. Kernel and local callables keep
-     * the `auth` credential.
+     * the `auth` credential. `connect` defaults to `auto` when `auth` is present; `new ClientSession`
+     * keeps source authority when this option is omitted. `{ mode: 'source' }` keeps it for every Call.
      */
     readonly exchange?: SessionExchangeOptions;
     /** Optional caller-owned persistence for bounded confidential route artifacts. */
@@ -37,6 +38,12 @@ export interface ClientSessionOptions {
     readonly policy: SessionPolicy;
     readonly envelopeTransport?: SessionEnvelopeTransport;
     readonly onWarning?: (warning: ClientWarning) => void;
+    /** Bounds the source Kernel's own `release.json`. */
+    readonly maximumReleaseBytes?: number;
+    /**
+     * Bounds every Publication the Session reads: the version 3 `domain.json` a Host that predates
+     * `release.json` serves, and the Publications Schema results carry.
+     */
     readonly maximumPublicationBytes?: number;
     readonly maximumBundleBytes?: number;
     readonly maximumResponseBytes?: number;
@@ -73,7 +80,17 @@ export declare class ClientSession {
      * `createSessionCredentialProvider`, for as long as it covers the calls it carries.
      */
     exchange(domain: string, options?: SessionExchangeRequest): Promise<SessionCredential>;
-    /** Revalidate the intrinsic Publication without acquiring its bundle or Views. */
+    /**
+     * Revalidate the source Kernel's own release (`release.json`) without acquiring its bundle or
+     * Views; a Host that predates intrinsic `release.json` yields its version 3 Publication instead.
+     */
+    release(options?: SessionControlOptions): Promise<IntrinsicRelease>;
+    /**
+     * Revalidate the intrinsic release and return its v3 document: the Host's own version 3
+     * Publication, or the frozen v3 projection of its `DomainRelease`.
+     *
+     * @deprecated Use `release()`. Deleted when no supported Host predates intrinsic `release.json`.
+     */
     publication(options?: SessionControlOptions): Promise<publication.Publication>;
     snapshot(options?: SessionControlOptions): Promise<SessionSnapshot>;
     viewsFor(target: PathLike, options?: SessionControlOptions): Promise<ViewCatalog>;
@@ -91,5 +108,5 @@ export declare class ClientSession {
     private invokeDomainMethod;
     private operation;
 }
-/** Open one caller-owned conversation with a Kernel using secure defaults. */
+/** Open a Kernel conversation with secure defaults and automatic Domain exchange when authenticated. */
 export declare function connect(options: ConnectOptions): ClientSession;

package/dist/session/session.js

@@ -12,7 +12,7 @@ import { HttpTransport } from '../transport/http/index.js';
 import { WebSocketTransport } from '../transport/websocket/index.js';
 import { admitFunction } from './admission.js';
 import { createContentApi } from './content.js';
-import { admitControlOptions, admitPolicy, createSessionOperation, DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_TIMEOUT_MS, admitKernel, allowEndpoint, kernelInvocationEndpoint, platformDuration, positive, } from './context/index.js';
+import { admitControlOptions, admitPolicy, createSessionOperation, DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RELEASE_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_TIMEOUT_MS, admitKernel, allowEndpoint, kernelInvocationEndpoint, platformDuration, positive, } from './context/index.js';
 import { createSessionDiscovery } from './discovery/index.js';
 import { acquireDomainCredential, admitExchangeOptions, admitExchangeRequest, createSessionExchange, } from './exchange/index.js';
 import { admitReference } from './reference.js';
@@ -51,6 +51,7 @@ export class ClientSession {
         if (options.client !== undefined && options.pool !== undefined) {
             throw new TypeError('ClientSession accepts either client or pool, not both.');
         }
+        const maximumReleaseBytes = positive(options.maximumReleaseBytes ?? DEFAULT_MAXIMUM_RELEASE_BYTES, 'maximumReleaseBytes');
         const maximumPublicationBytes = positive(options.maximumPublicationBytes ?? DEFAULT_MAXIMUM_PUBLICATION_BYTES, 'maximumPublicationBytes');
         const maximumBundleBytes = positive(options.maximumBundleBytes ?? DEFAULT_MAXIMUM_BUNDLE_BYTES, 'maximumBundleBytes');
         const maximumResponseBytes = positive(options.maximumResponseBytes ?? DEFAULT_MAXIMUM_RESPONSE_BYTES, 'maximumResponseBytes');
@@ -82,6 +83,7 @@ export class ClientSession {
             kernel: this.kernel,
             fetch: fetchImpl,
             policy,
+            maximumReleaseBytes,
             maximumPublicationBytes,
             maximumBundleBytes,
             requireOpen: () => this.requireOpen(),
@@ -152,7 +154,19 @@ export class ClientSession {
         const request = admitExchangeRequest(domain, options);
         return acquireDomainCredential(this.exchangeDependencies, request, this.operation(request.control));
     }
-    /** Revalidate the intrinsic Publication without acquiring its bundle or Views. */
+    /**
+     * Revalidate the source Kernel's own release (`release.json`) without acquiring its bundle or
+     * Views; a Host that predates intrinsic `release.json` yields its version 3 Publication instead.
+     */
+    release(options) {
+        return this.discovery.release(this.operation(admitControlOptions(options)));
+    }
+    /**
+     * Revalidate the intrinsic release and return its v3 document: the Host's own version 3
+     * Publication, or the frozen v3 projection of its `DomainRelease`.
+     *
+     * @deprecated Use `release()`. Deleted when no supported Host predates intrinsic `release.json`.
+     */
     publication(options) {
         return this.discovery.publication(this.operation(admitControlOptions(options)));
     }
@@ -178,16 +192,14 @@ export class ClientSession {
         const instance = last?.kind === 'method' && last.dispatch === 'instance'
             ? Path.fromAST({ anchor, steps: steps.slice(0, -1) }).raw
             : undefined;
-        // A generated reference pins the callable meaning, a hand-written one its revision, and a Kernel
-        // reference nothing, like every other syscall the Session addresses.
+        // A generated reference pins the callable meaning; a Kernel reference pins nothing, like every
+        // other syscall the Session addresses.
         const call = {
             target: Object.freeze({
                 callable: admittedReference.callable,
-                ...(admittedReference.fingerprint !== undefined
-                    ? { fingerprint: admittedReference.fingerprint }
-                    : admittedReference.revision !== undefined
-                        ? { revision: admittedReference.revision }
-                        : {}),
+                ...(admittedReference.fingerprint === undefined
+                    ? {}
+                    : { fingerprint: admittedReference.fingerprint }),
                 ...(instance === undefined ? {} : { instance }),
             }),
             input,
@@ -241,7 +253,6 @@ export class ClientSession {
             throw new TypeError(`Method owner ${method.owner.ref.origin} is absent.`);
         return this.invoke({
             origin: owner.origin,
-            revision: owner.revision,
             fingerprint: callableFingerprint(method),
             callable: method.key,
             target: Path.instanceMethod(Path.id(node.id), method.key),
@@ -253,16 +264,17 @@ export class ClientSession {
         return createSessionOperation(this.lifecycle.signal, options, this.timeoutMs);
     }
 }
-/** Open one caller-owned conversation with a Kernel using secure defaults. */
+/** Open a Kernel conversation with secure defaults and automatic Domain exchange when authenticated. */
 export function connect(options) {
     if (options === null || typeof options !== 'object') {
         throw new TypeError('Connect options are invalid.');
     }
-    const { url, ...rest } = options;
+    const { url, exchange, ...rest } = options;
     return new ClientSession({
         ...rest,
         kernel: url,
-        policy: options.policy ?? DEFAULT_SESSION_POLICY,
+        exchange: exchange === undefined && rest.auth !== undefined ? { mode: 'auto' } : exchange,
+        policy: rest.policy ?? DEFAULT_SESSION_POLICY,
     });
 }
 function admitClientPool(input) {

package/dist/session/session.typecheck.js

@@ -12,6 +12,9 @@ void envelope;
 void policy;
 void request;
 void snapshot;
+const observedRelease = session.release(control);
+void observedRelease;
+void observedRelease.then((current) => current.version === 4 ? current.build.digest : current.etag);
 const observedPublication = session.publication(control);
 void observedPublication;
 const admitted = session.auth.admit({
@@ -28,6 +31,23 @@ const credentials = createSessionCredentialProvider({
 // A credential provider is a Session authentication resolver; no adapter stands between them.
 const credentialAuth = credentials;
 void new ClientSession({ ...options, auth: credentialAuth });
+void new ClientSession({ ...options, auth: credentialAuth, exchange: { mode: 'auto' } });
+void new ClientSession({
+    ...options,
+    auth: credentialAuth,
+    exchange: { mode: 'auto', ttlSeconds: 300 },
+});
+void new ClientSession({ ...options, auth: credentialAuth, exchange: { mode: 'source' } });
+// @ts-expect-error Exchange options always name their mode.
+void new ClientSession({ ...options, auth: credentialAuth, exchange: {} });
+// @ts-expect-error Exchange options always name their mode.
+void new ClientSession({ ...options, auth: credentialAuth, exchange: { ttlSeconds: 300 } });
+// @ts-expect-error Source mode requests no Domain credential lifetime.
+void new ClientSession({ ...options, exchange: { mode: 'source', ttlSeconds: 300 } });
+// @ts-expect-error Exchange accepts named modes, not a boolean switch.
+void new ClientSession({ ...options, exchange: true });
+// @ts-expect-error Unknown exchange modes are not admitted.
+void new ClientSession({ ...options, exchange: { mode: 'invalid' } });
 // @ts-expect-error A minted credential must carry its own absolute expiry.
 void createSessionCredentialProvider({ ttlSeconds: 60, mint: async () => minted.credential });
 const dynamicReference = reference(dynamicDomain, dynamicMethod)(Path.id(NodeId('dynamic-node')));

package/dist/transport/auto/transport.d.ts

@@ -7,7 +7,6 @@ export interface AutoTransportOptions {
         readonly http: string;
         readonly websocket: string;
     };
-    readonly codec?: 'json' | 'msgpack';
     readonly fetch?: Fetch;
     readonly websocket?: WebSocketConstructor;
     readonly headers?: Readonly<Record<string, string>>;

package/dist/transport/auto/transport.js

@@ -26,7 +26,6 @@ export class AutoTransport {
         this.onWarning = options.onWarning;
         this.http = new HttpTransport({
             url: options.endpoints.http,
-            ...(options.codec === undefined ? {} : { codec: options.codec }),
             ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
             ...(options.headers === undefined ? {} : { headers: options.headers }),
             timeoutMs: this.timeoutMs,
@@ -39,7 +38,6 @@ export class AutoTransport {
         });
         this.websocket = new WebSocketTransport({
             url: options.endpoints.websocket,
-            ...(options.codec === undefined ? {} : { codec: options.codec }),
             ...(options.websocket === undefined ? {} : { websocket: options.websocket }),
             timeoutMs: this.timeoutMs,
             ...(options.maximumRequestBytes === undefined

package/dist/transport/http/response.d.ts

@@ -1,6 +1,6 @@
 import * as codecs from '@astrale-os/kernel-protocol/codecs';
 import * as protocol from '@astrale-os/kernel-protocol/invocation';
-export declare function codecForResponse(contentType: string | null): Promise<codecs.Codec | undefined>;
+export declare function codecForResponse(contentType: string | null): codecs.Codec | undefined;
 export declare function readBoundedBody(response: Response, maximumBytes: number, signal: AbortSignal): Promise<Uint8Array>;
 export declare function requireId(expected: protocol.RequestId, received: protocol.RequestId): void;
 export declare function decodeProtocol<T>(label: string, decode: () => T): T;

package/dist/transport/http/response.js

@@ -2,12 +2,8 @@ import * as codecs from '@astrale-os/kernel-protocol/codecs';
 import * as protocol from '@astrale-os/kernel-protocol/invocation';
 import { ProtocolError, ResponseError } from '../../errors/index.js';
 import { asError } from '../index.js';
-export async function codecForResponse(contentType) {
-    const mediaType = normalizeMediaType(contentType);
-    const supported = mediaType === codecs.CONTENT_TYPE_MSGPACK
-        ? [codecs.json, await codecs.loadMsgpack()]
-        : [codecs.json];
-    return protocol.http.codecForContentType(contentType, supported);
+export function codecForResponse(contentType) {
+    return protocol.http.codecForContentType(contentType, [codecs.json]);
 }
 export async function readBoundedBody(response, maximumBytes, signal) {
     const declared = response.headers.get('content-length');

package/dist/transport/http/transport.d.ts

@@ -3,7 +3,6 @@ import type { RequestOptions, Transport, TransportRequest, TransportResult } fro
 export type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 export interface HttpTransportOptions {
     readonly url: string;
-    readonly codec?: 'json' | 'msgpack';
     /** Inject this capability when the host does not provide global Fetch. */
     readonly fetch?: Fetch;
     readonly headers?: Readonly<Record<string, string>>;
@@ -16,7 +15,6 @@ export interface HttpTransportOptions {
 /** HTTP implementation of the universal invocation protocol. */
 export declare class HttpTransport implements Transport {
     readonly url: string;
-    private readonly codecName;
     private readonly fetchImpl;
     private readonly headers;
     private readonly timeoutMs;
@@ -29,7 +27,11 @@ export declare class HttpTransport implements Transport {
     dispatchBinary(input: TransportRequest, body: Blob, options?: RequestOptions): Promise<TransportResult>;
     private dispatchWith;
     private fetchResponse;
+    /**
+     * Admit the reserved retirement control only as the exact 410, header and envelope triple; the
+     * header beside any other status, value or body is an invalid response, never an ordinary error.
+     */
+    private decodeDeploymentRetired;
     private decodeBinary;
     private nextRequestId;
-    private requestCodec;
 }

package/dist/transport/http/transport.js

@@ -1,6 +1,7 @@
 import { canonicalMediaType } from '@astrale-os/kernel-protocol/artifact';
 import * as codecs from '@astrale-os/kernel-protocol/codecs';
 import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import * as retirement from '@astrale-os/kernel-protocol/routes/deployment-retired';
 import { ProtocolError, ResponseError, TransportError } from '../../errors/index.js';
 import { invocationFailure } from '../failure.js';
 import { asError, controlledSignal, positiveInteger, requireLive, } from '../index.js';
@@ -13,7 +14,6 @@ const DEFAULT_MAXIMUM_RESPONSE_BYTES = 16 * 1024 * 1024;
 /** HTTP implementation of the universal invocation protocol. */
 export class HttpTransport {
     url;
-    codecName;
     fetchImpl;
     headers;
     timeoutMs;
@@ -25,7 +25,6 @@ export class HttpTransport {
             throw new TypeError('HttpTransport options must be an object.');
         }
         this.url = normalizeUrl(options.url);
-        this.codecName = admitCodecName(options.codec);
         this.fetchImpl = admitFetch(options.fetch);
         this.headers = admitHeaders(options.headers ?? {});
         this.timeoutMs = positiveInteger(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 'timeoutMs');
@@ -47,7 +46,7 @@ export class HttpTransport {
     async dispatchWith(input, options, binaryBody) {
         const requestId = this.nextRequestId();
         const timeoutMs = positiveInteger(options.timeoutMs ?? this.timeoutMs, 'timeoutMs');
-        const codec = await this.requestCodec();
+        const codec = codecs.json;
         const { trace: traceInput, ...invocationInput } = input;
         const trace = traceInput === undefined ? undefined : protocol.admitTrace(traceInput);
         const request = protocol.decodeRequest({
@@ -82,7 +81,15 @@ export class HttpTransport {
             const binaryDelivery = response.headers.get(protocol.http.BINARY_DELIVERY_FIELD);
             const hasStreamSignal = streamFraming !== null;
             const hasBinarySignal = binaryId !== null || binaryManifest !== null || binaryDelivery !== null;
-            const responseCodec = await codecForResponse(response.headers.get('content-type'));
+            const responseCodec = codecForResponse(response.headers.get('content-type'));
+            if (response.headers.has(retirement.HTTP_DEPLOYMENT_RETIRED)) {
+                if (hasStreamSignal || hasBinarySignal) {
+                    throw new ProtocolError('server returned a deployment-retired control with a stream or binary signal.');
+                }
+                const retired = await this.decodeDeploymentRetired(response, responseCodec, control);
+                requireLive(control);
+                return retired;
+            }
             if (!response.ok && responseCodec === undefined && !hasStreamSignal && !hasBinarySignal) {
                 throw invocationFailure(`server returned HTTP ${response.status} without an invocation response.`, 'receive', { delivery: 'unknown' });
             }
@@ -182,6 +189,29 @@ export class HttpTransport {
         };
         return this.fetchImpl(this.url, init);
     }
+    /**
+     * Admit the reserved retirement control only as the exact 410, header and envelope triple; the
+     * header beside any other status, value or body is an invalid response, never an ordinary error.
+     */
+    async decodeDeploymentRetired(response, codec, control) {
+        if (codec === undefined) {
+            throw new ProtocolError('server returned a deployment-retired control without an envelope.');
+        }
+        requireNoStore(response);
+        const body = await readBoundedBody(response, this.maximumResponseBytes, control.signal);
+        const decoded = decodeProtocol('deployment-retired body', () => codec.decode(body));
+        const retired = decodeProtocol('deployment-retired control', () => retirement.decodeDeploymentRetired(response.status, response.headers, decoded));
+        const envelope = decodeProtocol('deployment-retired envelope', () => protocol.decodeResponse(decoded));
+        if (retired === undefined || !('error' in envelope)) {
+            throw new ProtocolError('server returned an invalid deployment-retired control.');
+        }
+        return Object.freeze({
+            kind: 'deployment-retired',
+            reason: retired.reason,
+            message: envelope.error.message,
+            invocation: envelope.invocation,
+        });
+    }
     async decodeBinary(response, requestId, binaryId, streaming, control) {
         if (binaryId !== String(requestId)) {
             throw new ProtocolError(`binary response requestId ${JSON.stringify(binaryId)} does not match request requestId ${requestId}.`);
@@ -197,14 +227,13 @@ export class HttpTransport {
         if (streaming) {
             if (response.body === null)
                 throw new ProtocolError('streaming binary has no body.');
-            // An intermediary may rewrite Content-Length (for example when it compresses the body), so the
-            // protocol length wins; Content-Length only counts for a Server that predates the field.
-            const declared = response.headers.get(protocol.http.BINARY_LENGTH_FIELD);
-            const length = declared ?? response.headers.get('content-length');
+            // An intermediary may rewrite Content-Length (for example when it compresses the body), so
+            // only the protocol length counts.
+            const length = response.headers.get(protocol.http.BINARY_LENGTH_FIELD);
             const expectedBytes = length === null ? undefined : Number(length);
             if (length !== null &&
                 (!/^(?:0|[1-9][0-9]*)$/u.test(length) || !Number.isSafeInteger(expectedBytes))) {
-                throw new ProtocolError(`streaming binary has an invalid ${declared === null ? 'Content-Length' : protocol.http.BINARY_LENGTH_FIELD}.`);
+                throw new ProtocolError(`streaming binary has an invalid ${protocol.http.BINARY_LENGTH_FIELD}.`);
             }
             if (expectedBytes !== undefined && expectedBytes > this.maximumResponseBytes) {
                 throw new ProtocolError(`streaming binary exceeds maximumResponseBytes (${this.maximumResponseBytes}).`);
@@ -215,6 +244,8 @@ export class HttpTransport {
                 invocation,
                 value: {
                     body: new HttpByteStream(response.body, this.maximumResponseBytes, control, expectedBytes),
+                    // The byte stream enforces this exact count through its final read.
+                    ...(expectedBytes === undefined ? {} : { length: expectedBytes }),
                     mediaType,
                     ...(response.status === 200 ? {} : { status: response.status }),
                     ...(Object.keys(headers).length === 0 ? {} : { headers }),
@@ -249,9 +280,6 @@ export class HttpTransport {
         this.nextId = requestId === Number.MAX_SAFE_INTEGER ? 1 : requestId + 1;
         return requestId;
     }
-    requestCodec() {
-        return this.codecName === 'msgpack' ? codecs.loadMsgpack() : Promise.resolve(codecs.json);
-    }
 }
 function redirectResult(response) {
     return Object.freeze({
@@ -340,13 +368,6 @@ function transportFailure(input, control, parent, timeoutMs, url, phase, deliver
             delivery,
         });
 }
-function admitCodecName(input) {
-    if (input === undefined || input === 'json')
-        return 'json';
-    if (input === 'msgpack')
-        return input;
-    throw new TypeError('codec must be "json" or "msgpack".');
-}
 function admitFetch(input) {
     const implementation = input ?? globalThis.fetch;
     if (typeof implementation !== 'function') {

package/dist/transport/index.d.ts

@@ -1,2 +1,2 @@
-export type { RequestOptions, MissControl, StaleControl, Transport, TransportRequest, TransportResult, } from './transport.js';
+export type { RequestOptions, DeploymentRetired, MissControl, StaleControl, Transport, TransportRequest, TransportResult, } from './transport.js';
 export { asError, controlledSignal, positiveInteger, requireLive, type ControlledSignal, } from './deadline.js';

package/dist/transport/transport.d.ts

@@ -1,4 +1,4 @@
-import type { invocation as protocol } from '@astrale-os/kernel-protocol';
+import type { invocation as protocol, routes } from '@astrale-os/kernel-protocol';
 import type { Result } from '../client/result.js';
 export interface RequestOptions {
     readonly signal?: AbortSignal;
@@ -25,7 +25,15 @@ export interface MissControl {
     readonly kind: 'miss';
     readonly invocation: protocol.InvocationId;
 }
-export type TransportResult = Result | StaleControl | MissControl;
+/**
+ * A retired deployment's reserved 410 control: its typed `DEPLOYMENT_RETIRED` reason with the
+ * message and invocation of the envelope it carried, which Client raises unchanged.
+ */
+export interface DeploymentRetired extends routes.DeploymentRetired {
+    readonly message: string;
+    readonly invocation: protocol.InvocationId;
+}
+export type TransportResult = Result | StaleControl | MissControl | DeploymentRetired;
 export interface Transport {
     /** Primary embedding-environment adapter for a complete invocation boundary. */
     dispatch(input: TransportRequest, options?: RequestOptions): Promise<TransportResult>;