@astrale-os/kernel-client 0.6.0-beta.82 → 0.6.0-beta.84

package/dist/session/reference.d.ts

@@ -1,6 +1,6 @@
 import type { Path as PathValue, PathLike } from '@astrale-os/kernel-core/path';
 import type { CallableInputOf, CallableInputModeOf, CallableOutputOf, CallableResultOf, Domain, ResolvedFunction, ExecutableMethod } from '@astrale-os/kernel-dsl/v1';
-import type { MethodAddress, Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { MethodAddress } from '@astrale-os/kernel-dsl/v1/addressing';
 import type { MeaningFingerprint } from '@astrale-os/kernel-dsl/v1/schema/fingerprint';
 import { type Key as KeyType } from '@astrale-os/kernel-dsl/v1/addressing';
 import type { Binary, Input } from '../client/index.js';
@@ -10,8 +10,6 @@ declare const REFERENCE_INPUT_MODE: unique symbol;
 declare const REFERENCE_OUTPUT: unique symbol;
 export interface CallableReference<InputValue = Input, Output = unknown, InputMode extends 'value' | 'binary' = 'value' | 'binary'> {
     readonly origin: KeyType.Origin;
-    /** @deprecated Informational only; dispatch pins `fingerprint` and revision pinning will be removed. */
-    readonly revision?: Revision;
     /** Meaning fingerprint of the callable; a generated reference always carries one. */
     readonly fingerprint?: MeaningFingerprint;
     readonly callable: KeyType.Callable;
@@ -24,7 +22,6 @@ export interface CallableReference<InputValue = Input, Output = unknown, InputMo
 export interface InstanceCallableReference<InputValue = Input, Output = unknown> {
     (receiver: PathLike): CallableReference<InputValue, Output>;
     readonly origin: KeyType.Origin;
-    readonly revision?: Revision;
     readonly fingerprint?: MeaningFingerprint;
     readonly callable: KeyType.Callable;
     readonly outputMode: 'value' | 'stream' | 'binary';
@@ -42,9 +39,9 @@ type ReferenceOutput<Callable> = Callable extends {
 type ExecutableStaticMethod = ExecutableMethod<unknown, unknown, true>;
 type ExecutableInstanceMethod = ExecutableMethod<unknown, unknown, false>;
 /** 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>, CallableInputModeOf<Callable>>;
+export declare function reference<const Callable extends ResolvedFunction | ExecutableStaticMethod>(domain: Pick<Domain, 'origin'>, callable: Callable): CallableReference<ReferenceInput<Callable>, ReferenceOutput<Callable>, CallableInputModeOf<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 reference<const Callable extends ExecutableInstanceMethod>(domain: Pick<Domain, 'origin'>, callable: Callable): InstanceCallableReference<ReferenceInput<Callable>, ReferenceOutput<Callable>>;
 /**
  * Reference a Kernel instance Method by its Core coordinate, without a meaning pin, as the Session
  * addresses every Kernel syscall. Loading the Session therefore never resolves the Kernel Schema.

package/dist/session/reference.js

@@ -9,7 +9,6 @@ export function reference(domain, callable) {
         invalid();
     const common = Object.freeze({
         origin: domain.origin,
-        revision: domain.revision,
         fingerprint: callableFingerprint(callable),
         callable: callable.key,
         outputMode: callable.output.mode,
@@ -45,8 +44,6 @@ export function admitReference(input) {
         invalid();
     if (typeof input.origin !== 'string' ||
         !patterns.origin.test(input.origin) ||
-        (input.revision !== undefined &&
-            (typeof input.revision !== 'string' || !patterns.revision.test(input.revision))) ||
         typeof input.callable !== 'string' ||
         !Key.is(input.callable) ||
         Key.origin(input.callable) !== input.origin ||
@@ -59,7 +56,6 @@ export function admitReference(input) {
         invalid();
     return Object.freeze({
         origin: input.origin,
-        ...(input.revision === undefined ? {} : { revision: input.revision }),
         ...(input.fingerprint === undefined ? {} : { fingerprint: input.fingerprint }),
         callable: input.callable,
         target,

package/dist/session/routing/dispatch.js

@@ -1,6 +1,6 @@
 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, remainingSessionTime, sessionTransportOptions, allowEndpoint, } from '../context/index.js';
 import { resolveAuth } from './auth.js';
@@ -86,23 +86,23 @@ 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);
         }
@@ -129,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.');
         }
@@ -177,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;
@@ -185,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';
@@ -31,7 +31,6 @@ export interface ClientSessionOptions {
      * caller, so the Domain is the principal and the caller is `auth`. Kernel and local callables keep
      * 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.
-     * Legacy `{}` and `{ ttlSeconds }` options remain equivalent to `{ mode: 'auto' }`.
      */
     readonly exchange?: SessionExchangeOptions;
     /** Optional caller-owned persistence for bounded confidential route artifacts. */
@@ -39,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;
@@ -75,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>;

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),

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,11 +31,19 @@ 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 });
-// Automatic exchange remains compatible with the original empty and TTL-only options.
-void new ClientSession({ ...options, auth: credentialAuth, exchange: {} });
-void new ClientSession({ ...options, auth: credentialAuth, exchange: { ttlSeconds: 300 } });
 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.

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>;

package/dist/transport/websocket/transport.d.ts

@@ -3,7 +3,6 @@ import type { RequestOptions, Transport, TransportRequest, TransportResult } fro
 export type WebSocketConstructor = new (url: string | URL, protocols?: string | string[]) => WebSocket;
 export interface WebSocketTransportOptions {
     readonly url: string;
-    readonly codec?: 'json' | 'msgpack';
     /** Inject this capability when the host does not provide a global WebSocket. */
     readonly websocket?: WebSocketConstructor;
     readonly timeoutMs?: number;
@@ -22,7 +21,6 @@ export interface WebSocketTransportOptions {
 export declare class WebSocketTransport implements Transport {
     readonly url: string;
     private readonly connectionUrl;
-    private readonly codecName;
     private readonly WebSocketConstructor;
     private readonly timeoutMs;
     private readonly maximumRequestBytes;
@@ -42,5 +40,4 @@ export declare class WebSocketTransport implements Transport {
     private connectionClosed;
     private acquire;
     private nextRequestId;
-    private codec;
 }