@astrale-os/kernel-client 0.6.0-beta.71 → 0.6.0-beta.74

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

@@ -3,6 +3,15 @@ import type { SessionControlOptions } from '../context/index.js';
 export type SessionEnvelopeTransport = 'auto' | 'http' | 'websocket';
 export interface SessionRequestOptions extends SessionControlOptions {
     readonly idempotencyKey?: invocation.IdempotencyKey;
+    readonly body?: never;
 }
+export type SessionRequestOptionsWithBody = Omit<SessionRequestOptions, 'body' | 'idempotencyKey'> & {
+    readonly body: Blob;
+    readonly idempotencyKey?: never;
+};
+export declare function admitInvocationOptions(input: SessionRequestOptions | SessionRequestOptionsWithBody | undefined): {
+    readonly options: Readonly<SessionRequestOptions>;
+    readonly body?: Blob;
+};
 export declare function admitRequestOptions(input?: SessionRequestOptions): Readonly<SessionRequestOptions>;
 export declare function admitEnvelopeTransport(input: SessionEnvelopeTransport): SessionEnvelopeTransport;

package/dist/session/routing/request.js

@@ -1,5 +1,22 @@
 import * as invocationProtocol from '@astrale-os/kernel-protocol/invocation';
 import { admitControlOptions } from '../context/index.js';
+export function admitInvocationOptions(input) {
+    if (input === undefined)
+        return Object.freeze({ options: admitRequestOptions() });
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Session request options are invalid.');
+    }
+    if (!Object.hasOwn(input, 'body')) {
+        return Object.freeze({ options: admitRequestOptions(input) });
+    }
+    const { body, ...options } = input;
+    if (!(body instanceof Blob))
+        throw new TypeError('Binary input must be a Blob or File.');
+    if (options.idempotencyKey !== undefined) {
+        throw new TypeError('Binary requests cannot carry an idempotency key.');
+    }
+    return Object.freeze({ options: admitRequestOptions(options), body });
+}
 export function admitRequestOptions(input = {}) {
     if (input === null || typeof input !== 'object' || Array.isArray(input)) {
         throw new TypeError('Session request options are invalid.');

package/dist/session/session.d.ts

@@ -10,10 +10,13 @@ import type { SchemaApi } from '../schema/index.js';
 import type { ClientWarning } from '../transport/auto/index.js';
 import type { Fetch } from '../transport/http/index.js';
 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 { CallableReference, InputOfReference, OutputOfReference } from './reference.js';
-import type { SessionRouteStore, SessionAuth, SessionEnvelopeTransport, SessionRequestOptions } from './routing/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';
 import type { ViewCatalog } from './views/index.js';
 export interface ClientSessionOptions {
     /** Exact canonical source Kernel identity; its invocation and discovery endpoints are derived. */
@@ -23,6 +26,12 @@ export interface ClientSessionOptions {
     readonly pool?: Pick<ClientPoolType, 'clientFor'>;
     readonly websocket?: WebSocketConstructor;
     readonly auth?: SessionAuth;
+    /**
+     * 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.
+     */
+    readonly exchange?: SessionExchangeOptions;
     /** Optional caller-owned persistence for bounded confidential route artifacts. */
     readonly routeStore?: SessionRouteStore;
     readonly policy: SessionPolicy;
@@ -44,24 +53,38 @@ export declare class ClientSession {
     readonly schema: SchemaApi;
     readonly graph: GraphApi;
     readonly auth: AuthApi;
+    readonly content: ContentApi;
     private readonly ownedPool?;
     private readonly discovery;
     private readonly dispatcher;
     private readonly lifecycle;
     private readonly timeoutMs;
     private readonly routes;
+    private readonly exchangeDependencies;
+    private readonly callExchange?;
     private readonly admitTargetViews;
     private closed;
     constructor(options: ClientSessionOptions);
     /** Bind one admitted DSL Domain to authenticated graph projection and Method dispatch. */
     bind<const DomainValue extends Domain>(domain: DomainValue): DomainBinding<DomainValue>;
+    /**
+     * Delegate this Session's caller to one Domain issuer and exchange that delegation for the
+     * Domain's credential to this Kernel. Nothing is cached: hold the result, for example through
+     * `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. */
     publication(options?: SessionControlOptions): Promise<publication.Publication>;
     snapshot(options?: SessionControlOptions): Promise<SessionSnapshot>;
     viewsFor(target: PathLike, options?: SessionControlOptions): Promise<ViewCatalog>;
     dispatch(call: Call, options?: SessionRequestOptions): Promise<Result>;
+    dispatch(call: Call, options: SessionRequestOptionsWithBody): Promise<Result>;
     call(call: Call, options?: SessionRequestOptions): Promise<Input>;
-    invoke<const Reference extends CallableReference<unknown>>(reference: Reference, input: InputOfReference<Reference>, options?: SessionRequestOptions): Promise<OutputOfReference<Reference>>;
+    call(call: Call, options: SessionRequestOptionsWithBody): Promise<Input>;
+    invoke<const Reference extends CallableReference<unknown>>(reference: InputModeOfReference<Reference> extends 'binary' ? never : Reference, input: InputOfReference<Reference>, options?: SessionRequestOptions): Promise<OutputOfReference<Reference>>;
+    invoke<const Reference extends CallableReference<unknown, unknown, 'binary'>>(reference: Reference, input: InputOfReference<Reference>, options: SessionRequestOptionsWithBody): Promise<OutputOfReference<Reference>>;
+    private dispatchWith;
+    private invokeWith;
     stream(call: Call, options?: SessionRequestOptions): Promise<import("../client/result.js").Stream>;
     binary(call: Call, options?: SessionRequestOptions): Promise<import("@astrale-os/kernel-core/callable").BinaryOutput>;
     close(): void;

package/dist/session/session.js

@@ -11,10 +11,12 @@ import { AutoTransport } from '../transport/auto/index.js';
 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 { createSessionDiscovery } from './discovery/index.js';
+import { acquireDomainCredential, admitExchangeOptions, admitExchangeRequest, createSessionExchange, } from './exchange/index.js';
 import { admitReference } from './reference.js';
-import { admitEnvelopeTransport, admitRequestOptions, admitSessionAuth, requireResultKind, RouteCache, SessionDispatcher, } from './routing/index.js';
+import { admitEnvelopeTransport, admitInvocationOptions, admitSessionAuth, requireResultKind, RouteCache, SessionDispatcher, } from './routing/index.js';
 import { resolveViewsFor, targetViewCatalog } from './views/index.js';
 const DEFAULT_SESSION_POLICY = Object.freeze({ maximumRouteAgeMs: 60_000 });
 /** Caller-owned discovery and redirect-following conversation with one exact source Kernel. */
@@ -23,12 +25,15 @@ export class ClientSession {
     schema;
     graph;
     auth;
+    content;
     ownedPool;
     discovery;
     dispatcher;
     lifecycle = new AbortController();
     timeoutMs;
     routes;
+    exchangeDependencies;
+    callExchange;
     admitTargetViews;
     closed = false;
     constructor(options) {
@@ -84,28 +89,45 @@ export class ClientSession {
         });
         this.routes = new RouteCache(policy.maximumRouteAgeMs, undefined, options.routeStore);
         const auth = admitSessionAuth(options.auth);
-        const admission = {
+        const exchange = admitExchangeOptions(options.exchange, auth);
+        this.exchangeDependencies = Object.freeze({
             kernel: this.kernel,
-            auth,
             source: () => {
                 allowEndpoint(sourceEndpoint, policy);
                 return pool.clientFor({ transport: 'http', url: sourceEndpoint });
             },
+            ...(auth === undefined ? {} : { auth }),
             fetch: fetchImpl,
             policy,
             limits: { maximumPublicationBytes, maximumBundleBytes },
             maximumResponseBytes,
-        };
+            operation: (signal) => this.operation(signal === undefined ? undefined : { signal }),
+        });
+        this.callExchange =
+            exchange === undefined || auth === undefined
+                ? undefined
+                : createSessionExchange({ ...this.exchangeDependencies, auth }, exchange);
         this.dispatcher = new SessionDispatcher({
             kernel: this.kernel,
             sourceEndpoint,
             pool,
             websocketAvailable,
             auth,
+            ...(this.callExchange === undefined ? {} : { exchange: this.callExchange }),
             cache: this.routes,
             policy,
             envelopeTransport: admitEnvelopeTransport(options.envelopeTransport ?? 'http'),
             requireOpen: () => this.requireOpen(),
+            streamingHttp: {
+                fetch: fetchImpl,
+                maximumResponseBytes: 100 * 1024 * 1024,
+                timeoutMs: 30 * 60 * 1_000,
+            },
+        });
+        this.content = createContentApi({
+            operation: (options) => this.operation(options),
+            invoke: (reference, input, options, operation) => this.invokeWith(reference, input, options, operation),
+            dispatch: (target, input, operation, body) => this.dispatcher.dispatchHttp({ target, input }, {}, operation, body),
         });
         this.schema = createSchema((request, options) => this.dispatch(request, options), {
             maximumPublicationBytes,
@@ -115,13 +137,22 @@ export class ClientSession {
         this.graph = createGraph((call, options) => this.call(call, options));
         this.auth = createAuth((target, input, options) => this.call({ target, input }, options), (call, options) => {
             const operation = this.operation(admitControlOptions(options));
-            return admitFunction(admission, acceptCall(call), options, operation);
+            return admitFunction(this.exchangeDependencies, acceptCall(call), options, operation);
         });
     }
     /** Bind one admitted DSL Domain to authenticated graph projection and Method dispatch. */
     bind(domain) {
         return createDomainBinding(domain, this.graph, (node, method, input) => this.invokeDomainMethod(domain, node, method, input));
     }
+    /**
+     * Delegate this Session's caller to one Domain issuer and exchange that delegation for the
+     * Domain's credential to this Kernel. Nothing is cached: hold the result, for example through
+     * `createSessionCredentialProvider`, for as long as it covers the calls it carries.
+     */
+    async exchange(domain, options) {
+        const request = admitExchangeRequest(domain, options);
+        return acquireDomainCredential(this.exchangeDependencies, request, this.operation(request.control));
+    }
     /** Revalidate the intrinsic Publication without acquiring its bundle or Views. */
     publication(options) {
         return this.discovery.publication(this.operation(admitControlOptions(options)));
@@ -134,23 +165,32 @@ export class ClientSession {
         return resolveViewsFor(async (call, operation) => requireResultKind('value', await this.dispatcher.dispatch(call, {}, operation)).value, this.admitTargetViews, target, this.operation(admitControlOptions(options)));
     }
     dispatch(call, options) {
-        const admitted = admitRequestOptions(options);
-        return this.dispatcher.dispatch(call, admitted, this.operation(admitted));
+        return this.dispatchWith(call, options);
     }
     async call(call, options) {
-        const result = await this.dispatch(call, options);
+        const result = await this.dispatchWith(call, options);
         return requireResultKind('value', result).value;
     }
     async invoke(reference, input, options) {
+        return this.invokeWith(reference, input, options);
+    }
+    dispatchWith(call, options, requireHttp = false) {
+        const admitted = admitInvocationOptions(options);
+        const operation = this.operation(admitted.options);
+        return admitted.body === undefined && !requireHttp
+            ? this.dispatcher.dispatch(call, admitted.options, operation)
+            : this.dispatcher.dispatchHttp(call, admitted.options, operation, admitted.body);
+    }
+    async invokeWith(reference, input, options, sharedOperation) {
         const admittedReference = admitReference(reference);
-        const admittedOptions = admitRequestOptions(options);
+        const admitted = admitInvocationOptions(options);
         const { anchor, steps } = admittedReference.target.ast;
         const last = steps.at(-1);
         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 still pins the revision.
-        const result = await this.dispatcher.dispatch({
+        const call = {
             target: Object.freeze({
                 callable: admittedReference.callable,
                 ...(admittedReference.fingerprint === undefined
@@ -159,20 +199,24 @@ export class ClientSession {
                 ...(instance === undefined ? {} : { instance }),
             }),
             input,
-        }, admittedOptions, this.operation(admittedOptions));
+        };
+        const operation = sharedOperation ?? this.operation(admitted.options);
+        const result = await (admitted.body === undefined && admittedReference.outputMode !== 'binary'
+            ? this.dispatcher.dispatch(call, admitted.options, operation)
+            : this.dispatcher.dispatchHttp(call, admitted.options, operation, admitted.body));
         const narrowed = requireResultKind(admittedReference.outputMode, result);
-        return (narrowed.kind === 'value'
+        return narrowed.kind === 'value'
             ? narrowed.value
             : narrowed.kind === 'stream'
                 ? narrowed.stream
-                : narrowed.value);
+                : narrowed.value;
     }
     async stream(call, options) {
         const result = await this.dispatch(call, options);
         return requireResultKind('stream', result).stream;
     }
     async binary(call, options) {
-        const result = await this.dispatch(call, options);
+        const result = await this.dispatchWith(call, options, true);
         return requireResultKind('binary', result).value;
     }
     close() {
@@ -183,6 +227,7 @@ export class ClientSession {
         this.ownedPool?.close();
         this.routes.clear();
         this.discovery.clear();
+        this.callExchange?.clear();
     }
     requireOpen() {
         if (this.closed)

package/dist/session/session.typecheck.js

@@ -2,7 +2,9 @@ import { NodeId } from '@astrale-os/kernel-core/graph/node';
 import { Path } from '@astrale-os/kernel-core/path';
 import { K, KernelSchema } from '@astrale-os/kernel-core/schema';
 import { defineSchema, func, method, nodeClass, schema, valueSchema, } from '@astrale-os/kernel-dsl/v1';
-import { ClientSession, createSessionCredentialProvider, reference } from './index.js';
+import { isBinaryInput } from '@astrale-os/kernel-dsl/v1/language';
+import { call } from '../client/index.js';
+import { ClientSession, createSessionCredentialProvider, execution, reference } from './index.js';
 void new ClientSession(options);
 void auth;
 void control;
@@ -40,7 +42,10 @@ const renameInput = valueSchema()({
     required: ['name'],
     additionalProperties: false,
 });
-const registrationInput = valueSchema()(K.functions.register.input);
+const registerInput = K.functions.register.input;
+if (isBinaryInput(registerInput))
+    throw new TypeError('Register input must be a Value.');
+const registrationInput = valueSchema()(registerInput);
 const booleanOutput = valueSchema()({ type: 'boolean' });
 const typedDomain = schema.resolve(defineSchema('client.input-witness.typecheck', {
     dependencies: { kernel: KernelSchema },
@@ -68,9 +73,42 @@ const typedDomain = schema.resolve(defineSchema('client.input-witness.typecheck'
 const registerReference = reference(typedDomain, typedDomain.functions.registerIdentity);
 const staticRegisterReference = reference(typedDomain, typedDomain.classes.Person.static.methods.registerIdentity);
 const renameReference = reference(typedDomain, typedDomain.classes.Person.methods.rename)(Path.id(NodeId('person')));
+const blobReceipt = session.content
+    .upload(blobBytes, { mediaType: 'image/png' })
+    .then(({ receipt }) => receipt);
+const boundBlobReceipt = boundSession.content
+    .upload(blobBytes, { mediaType: 'image/png' })
+    .then(({ receipt }) => receipt);
+void blobReceipt;
+void boundBlobReceipt;
 void session.invoke(registerReference, registration);
 void boundSession.invoke(staticRegisterReference, registration);
 void session.invoke(renameReference, renameRequest);
+const binaryUploadReference = reference(K, K.functions.upload);
+void session.invoke(binaryUploadReference, { mediaType: 'image/png' }, { body: new Blob() });
+void boundSession.invoke(binaryUploadReference, { mediaType: 'image/png' }, { body: new Blob() });
+const rawBinaryCall = call(Path.parse('/:example.test:function.write'), { mediaType: 'image/png' });
+void client.dispatch(rawBinaryCall, { body: new Blob() });
+void client.as('credential').call(rawBinaryCall, { body: new Blob() });
+// @ts-expect-error Binary Functions require a byte source.
+void session.invoke(binaryUploadReference, { mediaType: 'image/png' });
+// @ts-expect-error Value Functions reject binary bodies.
+void session.invoke(registerReference, registration, { body: new Blob() });
+// @ts-expect-error Bound binary Functions require a byte source.
+void boundSession.invoke(binaryUploadReference, { mediaType: 'image/png' });
+// @ts-expect-error Bound value Functions reject binary bodies.
+void boundSession.invoke(registerReference, registration, { body: new Blob() });
+void session.invoke(binaryUploadReference, { mediaType: 'image/png' }, 
+// @ts-expect-error Binary invocations cannot carry an idempotency key.
+{ body: new Blob(), idempotencyKey: 'retry' });
+// @ts-expect-error Raw Session binary calls cannot carry an idempotency key.
+void session.dispatch(rawBinaryCall, { body: new Blob(), idempotencyKey: 'retry' });
+// @ts-expect-error Raw Client binary calls cannot carry an idempotency key.
+void client.dispatch(rawBinaryCall, { body: new Blob(), idempotencyKey: 'retry' });
+// @ts-expect-error Authenticated Client binary calls cannot carry an idempotency key.
+void client.as('credential').call(rawBinaryCall, { body: new Blob(), idempotencyKey: 'retry' });
+void session.dispatch({ target: Path.parse('/:example.test:function.write'), input: {} }, { body: new Blob() });
+void session.call({ target: Path.parse('/:example.test:function.write'), input: {} }, { body: new Blob() });
 const registerInputIsRequest = true;
 const renameInputIsInterface = true;
 const renameOutputIsBoolean = true;
@@ -98,6 +136,37 @@ const abstractDomain = schema.resolve(defineSchema('client.reference.typecheck',
         AbstractItem: nodeClass({ abstract: true, methods: { abstractMethod } }),
     },
 }));
+const reminderOutput = valueSchema()({
+    type: 'object',
+    properties: { reminder: { type: 'string' } },
+    required: ['reminder'],
+    additionalProperties: false,
+});
+const durableDomain = schema.resolve(defineSchema('client.durable.typecheck', {
+    classes: {
+        Invoice: nodeClass({
+            methods: {
+                remind: method({
+                    auth: 'authenticated',
+                    input: renameInput,
+                    output: reminderOutput,
+                    execution: { durable: true },
+                }),
+            },
+        }),
+    },
+}));
+const remindReference = reference(durableDomain, durableDomain.classes.Invoice.methods.remind)(Path.id(NodeId('invoice-1')));
+const durableReturnsExecution = true;
+const outcomeIsTyped = true;
+const statusIsTyped = true;
+void session.invoke(execution.result(run), { waitMs: 1_000 });
+void session.invoke(execution.signal(run), { name: 'approval', value: { by: 'billing' } });
+// @ts-expect-error Force is the only cancellation option.
+void session.invoke(execution.cancel(run), { waitMs: 1_000 });
+void durableReturnsExecution;
+void outcomeIsTyped;
+void statusIsTyped;
 // @ts-expect-error Abstract Methods are declarations and cannot become Client references.
 reference(abstractDomain, abstractDomain.classes.AbstractItem.methods.abstractMethod);
 // @ts-expect-error Exact identity is derived internally, never supplied as a Session option.

package/dist/transport/http/byte-stream.d.ts

@@ -3,12 +3,13 @@ import type { ControlledSignal } from '../index.js';
 export declare class HttpByteStream implements AsyncIterable<Uint8Array> {
     private readonly maximumBytes;
     private readonly control;
+    private readonly expectedBytes?;
     private readonly reader;
     private claimed;
     private terminal;
     private bytes;
     private interruption;
-    constructor(body: ReadableStream<Uint8Array>, maximumBytes: number, control: ControlledSignal);
+    constructor(body: ReadableStream<Uint8Array>, maximumBytes: number, control: ControlledSignal, expectedBytes?: number | undefined);
     [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
     cancel(reason?: unknown): Promise<void>;
     private next;

package/dist/transport/http/byte-stream.js

@@ -4,14 +4,16 @@ import { asError } from '../index.js';
 export class HttpByteStream {
     maximumBytes;
     control;
+    expectedBytes;
     reader;
     claimed = false;
     terminal = false;
     bytes = 0;
     interruption;
-    constructor(body, maximumBytes, control) {
+    constructor(body, maximumBytes, control, expectedBytes) {
         this.maximumBytes = maximumBytes;
         this.control = control;
+        this.expectedBytes = expectedBytes;
         this.reader = body.getReader();
         const abort = () => void this.interrupt(control.signal.reason);
         if (control.signal.aborted)
@@ -53,11 +55,17 @@ export class HttpByteStream {
             if (this.interruption !== undefined)
                 throw this.interruption;
             if (next.done) {
+                if (this.expectedBytes !== undefined && this.bytes !== this.expectedBytes) {
+                    throw new ProtocolError(`streaming binary ended after ${this.bytes} bytes; expected ${this.expectedBytes}.`);
+                }
                 this.terminal = true;
                 this.control.close();
                 return { done: true, value: undefined };
             }
             this.bytes += next.value.byteLength;
+            if (this.expectedBytes !== undefined && this.bytes > this.expectedBytes) {
+                throw new ProtocolError(`streaming binary exceeded declared Content-Length (${this.expectedBytes}).`);
+            }
             if (this.bytes > this.maximumBytes) {
                 throw new ProtocolError(`streaming binary exceeds maximumResponseBytes (${this.maximumBytes}).`);
             }

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

@@ -25,6 +25,9 @@ export declare class HttpTransport implements Transport {
     private nextId;
     constructor(options: HttpTransportOptions);
     dispatch(input: TransportRequest, options?: RequestOptions): Promise<TransportResult>;
+    /** HTTP-only binary invocation; each call may replay a re-readable Blob. */
+    dispatchBinary(input: TransportRequest, body: Blob, options?: RequestOptions): Promise<TransportResult>;
+    private dispatchWith;
     private fetchResponse;
     private decodeBinary;
     private nextRequestId;

package/dist/transport/http/transport.js

@@ -1,10 +1,11 @@
+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 { ProtocolError, ResponseError, TransportError } from '../../errors/index.js';
 import { invocationFailure } from '../failure.js';
 import { asError, controlledSignal, positiveInteger, requireLive, } from '../index.js';
 import { HttpByteStream } from './byte-stream.js';
-import { binaryHeaders, codecForResponse, decodeProtocol, normalizeMediaType, readBoundedBody, requireId, } from './response.js';
+import { binaryHeaders, codecForResponse, decodeProtocol, readBoundedBody, requireId, } from './response.js';
 import { HttpStream } from './stream.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAXIMUM_REQUEST_BYTES = 16 * 1024 * 1024;
@@ -32,6 +33,18 @@ export class HttpTransport {
         this.maximumResponseBytes = positiveInteger(options.maximumResponseBytes ?? DEFAULT_MAXIMUM_RESPONSE_BYTES, 'maximumResponseBytes');
     }
     async dispatch(input, options = {}) {
+        return this.dispatchWith(input, options);
+    }
+    /** HTTP-only binary invocation; each call may replay a re-readable Blob. */
+    async dispatchBinary(input, body, options = {}) {
+        if (!(body instanceof Blob))
+            throw new TypeError('Binary request body must be a Blob.');
+        if (options.idempotencyKey !== undefined) {
+            throw new TypeError('Binary requests cannot carry an idempotency key.');
+        }
+        return this.dispatchWith(input, options, body);
+    }
+    async dispatchWith(input, options, binaryBody) {
         const requestId = this.nextRequestId();
         const timeoutMs = positiveInteger(options.timeoutMs ?? this.timeoutMs, 'timeoutMs');
         const codec = await this.requestCodec();
@@ -43,19 +56,21 @@ export class HttpTransport {
             ...invocationInput,
             ...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
         });
-        const encoded = codec.encode(request);
+        const encoded = binaryBody === undefined
+            ? codec.encode(request)
+            : protocol.http.encodeBinaryRequestEnvelope(request);
         const control = controlledSignal(options.signal, timeoutMs);
         let handedOff = false;
         let phase = 'connect';
         let delivery = 'not-sent';
         try {
             requireLive(control);
-            if (encodedByteLength(encoded) > this.maximumRequestBytes) {
+            if (binaryBody === undefined && encodedByteLength(encoded) > this.maximumRequestBytes) {
                 throw invocationFailure(`request exceeds maximumRequestBytes (${this.maximumRequestBytes}).`, 'send');
             }
             phase = 'send';
             delivery = 'unknown';
-            const response = await this.fetchResponse(codec, encoded, trace, control);
+            const response = await this.fetchResponse(codec, encoded, trace, control, binaryBody);
             phase = 'receive';
             requireLive(control);
             if (response.status >= 300 && response.status < 400) {
@@ -143,20 +158,26 @@ export class HttpTransport {
                 control.close();
         }
     }
-    async fetchResponse(codec, encoded, trace, control) {
+    async fetchResponse(codec, encoded, trace, control, binaryBody) {
         const init = {
             method: 'POST',
             redirect: 'manual',
             credentials: 'omit',
-            cache: 'no-store',
             referrerPolicy: 'no-referrer',
+            // Fetch owns Content-Length; the protocol carries Blob.size across Fetch runtimes.
             headers: {
                 ...this.headers,
                 ...protocol.http.encodeTraceHeaders(trace),
-                'content-type': codec.contentType,
+                'content-type': binaryBody === undefined ? codec.contentType : protocol.http.BINARY_REQUEST_CONTENT_TYPE,
                 accept: codec.contentType,
+                ...(binaryBody === undefined
+                    ? {}
+                    : {
+                        [protocol.http.REQUEST_ENVELOPE_FIELD]: encoded,
+                        [protocol.http.BINARY_LENGTH_FIELD]: String(binaryBody.size),
+                    }),
             },
-            body: toBody(encoded),
+            body: binaryBody ?? toBody(encoded),
             signal: control.signal,
         };
         return this.fetchImpl(this.url, init);
@@ -165,22 +186,32 @@ export class HttpTransport {
         if (binaryId !== String(requestId)) {
             throw new ProtocolError(`binary response requestId ${JSON.stringify(binaryId)} does not match request requestId ${requestId}.`);
         }
-        const mediaType = normalizeMediaType(response.headers.get('content-type'));
-        if (mediaType === undefined) {
+        const contentType = response.headers.get('content-type');
+        if (contentType === null) {
             throw new ProtocolError('binary response has no media type.');
         }
+        const mediaType = decodeProtocol('binary media type', () => canonicalMediaType(contentType));
         const headerNames = decodeProtocol('binary application-header manifest', () => protocol.http.decodeBinaryHeaderNames(response.headers.get(protocol.http.BINARY_HEADERS_FIELD)));
         const headers = binaryHeaders(response.headers, headerNames);
         const invocation = decodeProtocol('binary InvocationId field', () => protocol.http.decodeInvocationId(response.headers.get(protocol.http.INVOCATION_FIELD)));
         if (streaming) {
             if (response.body === null)
                 throw new ProtocolError('streaming binary has no body.');
+            const length = response.headers.get('content-length');
+            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 Content-Length.');
+            }
+            if (expectedBytes !== undefined && expectedBytes > this.maximumResponseBytes) {
+                throw new ProtocolError(`streaming binary exceeds maximumResponseBytes (${this.maximumResponseBytes}).`);
+            }
             requireLive(control);
             return {
                 kind: 'binary',
                 invocation,
                 value: {
-                    body: new HttpByteStream(response.body, this.maximumResponseBytes, control),
+                    body: new HttpByteStream(response.body, this.maximumResponseBytes, control, expectedBytes),
                     mediaType,
                     ...(response.status === 200 ? {} : { status: response.status }),
                     ...(Object.keys(headers).length === 0 ? {} : { headers }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-client",
-  "version": "0.6.0-beta.71",
+  "version": "0.6.0-beta.74",
   "description": "Universal Client — protocol-first, transport-agnostic",
   "keywords": [
     "astrale",
@@ -65,14 +65,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "0.9.0-beta.54",
-    "@astrale-os/kernel-dsl": "0.2.0-beta.39",
-    "@astrale-os/kernel-protocol": "0.5.0-beta.60",
+    "@astrale-os/kernel-core": "0.9.0-beta.56",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.41",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.62",
     "@tanstack/pacer": "0.20.1",
     "msgpackr": "^2.0.5"
   },
   "devDependencies": {
-    "@astrale-os/kernel-server": "0.5.0-beta.62",
+    "@astrale-os/kernel-server": "0.5.0-beta.64",
     "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~1.1.0",
     "@types/node": "^22.0.0",
     "typescript": "7.0.2",