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

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, dispatchTrace, isAdmittedMissError, isAdmittedStaleRouteError, } from '../../client/index.js';
+import { acceptCall, Client, dispatchTrace, isAdmittedMissError, isAdmittedStaleRouteError, } from '../../client/index.js';
 import { ClientError, ResponseError } from '../../errors/index.js';
 import { runSessionOperation, sessionTransportOptions, allowEndpoint } from '../context/index.js';
 import { resolveAuth } from './auth.js';
@@ -11,6 +11,13 @@ export class SessionDispatcher {
         this.state = state;
     }
     async dispatch(input, options, operation) {
+        return this.dispatchWith(input, options, operation);
+    }
+    /** Reuse Session authority and route recovery while forcing HTTP for streaming calls. */
+    async dispatchHttp(input, options, operation, body) {
+        return this.dispatchWith(input, options, operation, { body });
+    }
+    async dispatchWith(input, options, operation, streaming) {
         this.state.requireOpen();
         const call = acceptCall(input);
         // Authority is resolved before warm lookup so changed credentials or delegation cannot reuse a
@@ -27,7 +34,7 @@ export class SessionDispatcher {
         let learned = await this.state.cache.get(cacheKey, auth.credential);
         if (learned !== undefined) {
             try {
-                requireCachedRoute(learned, source, call.target, this.state.envelopeTransport, this.state.websocketAvailable, this.state.policy);
+                requireCachedRoute(learned, source, call.target, streaming === undefined ? this.state.envelopeTransport : 'http', this.state.websocketAvailable, this.state.policy);
             }
             catch {
                 this.state.cache.delete(cacheKey);
@@ -35,22 +42,31 @@ export class SessionDispatcher {
             }
         }
         if (learned !== undefined) {
-            return this.dispatchDestinationWithRecovery(learned, dispatch, options, operation);
+            return this.dispatchDestinationWithRecovery(learned, dispatch, options, operation, undefined, streaming);
         }
-        const result = await this.dispatchSource(dispatch, undefined, options, operation);
-        return this.followSource(result, dispatch, options, operation);
+        const result = await this.dispatchSource(dispatch, undefined, options, operation, streaming);
+        return this.followSource(result, dispatch, options, operation, streaming);
     }
-    async dispatchSource(state, routing, options, operation) {
+    async dispatchSource(state, routing, options, operation, streaming) {
         this.state.requireOpen();
         allowEndpoint(this.state.sourceEndpoint, this.state.policy);
-        const client = this.state.pool.clientFor(Object.freeze({ transport: 'http', url: this.state.sourceEndpoint }));
-        return runSessionOperation(operation, () => authenticated(client, state.auth.credential).dispatch(state.call, {
-            ...sessionTransportOptions(operation, options.idempotencyKey),
-            ...(state.auth.delegate === undefined ? {} : { delegate: state.auth.delegate }),
-            ...(routing === undefined ? {} : { routing }),
-        }));
+        const client = streaming === undefined
+            ? this.state.pool.clientFor(Object.freeze({ transport: 'http', url: this.state.sourceEndpoint }))
+            : this.streamingClientFor(this.state.sourceEndpoint);
+        return runSessionOperation(operation, () => streaming?.body === undefined
+            ? authenticated(client, state.auth.credential).dispatch(state.call, {
+                ...sessionTransportOptions(operation, options.idempotencyKey),
+                ...(state.auth.delegate === undefined ? {} : { delegate: state.auth.delegate }),
+                ...(routing === undefined ? {} : { routing }),
+            })
+            : authenticated(client, state.auth.credential).dispatch(state.call, {
+                ...sessionTransportOptions(operation),
+                ...(state.auth.delegate === undefined ? {} : { delegate: state.auth.delegate }),
+                ...(routing === undefined ? {} : { routing }),
+                body: streaming.body,
+            }));
     }
-    async followSource(result, state, options, operation) {
+    async followSource(result, state, options, operation, streaming) {
         if (result.kind !== 'redirect')
             return result;
         const redirect = result.redirect;
@@ -59,11 +75,11 @@ export class SessionDispatcher {
         }
         requireTargetPublication(redirect.route, state.call.target);
         const learned = await this.state.cache.learn(state.cacheKey, redirect.route, redirect.credential, state.auth.credential);
-        return this.dispatchDestinationWithRecovery(learned, state, options, operation, redirect.trace);
+        return this.dispatchDestinationWithRecovery(learned, state, options, operation, redirect.trace, streaming);
     }
-    async dispatchDestinationWithRecovery(learned, state, options, operation, trace) {
+    async dispatchDestinationWithRecovery(learned, state, options, operation, trace, streaming) {
         try {
-            return await this.dispatchDestination(learned, state.call, options, operation, state.source, trace);
+            return await this.dispatchDestination(learned, state.call, options, operation, state.source, trace, streaming);
         }
         catch (cause) {
             const stale = isAdmittedStaleRouteError(cause);
@@ -83,20 +99,31 @@ export class SessionDispatcher {
                     stale: learned.route.via.publication.etag,
                 })
                 : undefined;
-            const refreshed = await this.dispatchSource(state, routing, options, operation);
-            return this.followSource(refreshed, state, options, operation);
+            const refreshed = await this.dispatchSource(state, routing, options, operation, streaming);
+            return this.followSource(refreshed, state, options, operation, streaming);
         }
     }
-    async dispatchDestination(learned, call, options, operation, source, trace) {
+    async dispatchDestination(learned, call, options, operation, source, trace, streaming) {
         if (learned.route.via.issuer !== source) {
             throw new ClientError('Learned route issuer differs from the session-pinned source Kernel.');
         }
         requireTargetPublication(learned.route, call.target);
-        const envelope = selectEnvelope(learned.route.endpoint, this.state.envelopeTransport, this.state.websocketAvailable, this.state.pool, this.state.policy);
+        const destination = streaming === undefined
+            ? undefined
+            : selectEnvelopeTarget(learned.route.endpoint, 'http', this.state.websocketAvailable, this.state.policy);
+        const client = streaming === undefined
+            ? selectEnvelope(learned.route.endpoint, this.state.envelopeTransport, this.state.websocketAvailable, this.state.pool, this.state.policy).client
+            : destination?.transport === 'http'
+                ? this.streamingClientFor(destination.url)
+                : invalidStreamingDestination();
         const requestOptions = {
             ...sessionTransportOptions(operation, options.idempotencyKey),
             routing: learned.route.via,
         };
+        const binaryRequestOptions = {
+            ...sessionTransportOptions(operation),
+            routing: learned.route.via,
+        };
         // The source has admitted this fingerprint against the exact Publication carried by Via.
         // Pin that revision at the destination so existing Workers can execute the same admitted
         // callable without understanding the newer fingerprint Target representation. The cache
@@ -111,14 +138,32 @@ export class SessionDispatcher {
                 }),
             }
             : call;
-        const result = await runSessionOperation(operation, () => trace === undefined
-            ? authenticated(envelope.client, learned.credential).dispatch(destinationCall, requestOptions)
-            : dispatchTrace(envelope.client, learned.credential, destinationCall, requestOptions, trace));
+        const result = await runSessionOperation(operation, () => streaming?.body !== undefined
+            ? trace === undefined
+                ? authenticated(client, learned.credential).dispatch(destinationCall, {
+                    ...binaryRequestOptions,
+                    body: streaming.body,
+                })
+                : dispatchTrace(client, learned.credential, destinationCall, { ...binaryRequestOptions, body: streaming.body }, trace)
+            : trace === undefined
+                ? authenticated(client, learned.credential).dispatch(destinationCall, requestOptions)
+                : dispatchTrace(client, learned.credential, destinationCall, requestOptions, trace));
         if (result.kind === 'redirect') {
             throw new ClientError('A destination redirect is invalid; only the source Kernel may redirect.');
         }
         return result;
     }
+    streamingClientFor(url) {
+        return new Client({
+            url,
+            fetch: this.state.streamingHttp.fetch,
+            timeoutMs: this.state.streamingHttp.timeoutMs,
+            maximumResponseBytes: this.state.streamingHttp.maximumResponseBytes,
+        });
+    }
+}
+function invalidStreamingDestination() {
+    throw new ClientError('Streaming route has no HTTP endpoint.');
 }
 function requireCachedRoute(learned, source, target, envelopeTransport, websocketAvailable, policy) {
     if (learned.route.via.issuer !== source) {

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

@@ -2,4 +2,4 @@ export { admitSessionAuth, resolveAuth, type Auth, type EffectiveAuth, type Sess
 export { RouteCache, type LearnedRoute, type PersistedRoute, type SessionRouteArtifact, type SessionRouteStore, } from './cache.js';
 export { requireResultKind, SessionDispatcher, type SessionDispatcherOptions } from './dispatch.js';
 export { type ClientPoolCapability, type EnvelopeSelection } from './envelope.js';
-export { admitEnvelopeTransport, admitRequestOptions, type SessionEnvelopeTransport, type SessionRequestOptions, } from './request.js';
+export { admitEnvelopeTransport, admitInvocationOptions, admitRequestOptions, type SessionEnvelopeTransport, type SessionRequestOptions, type SessionRequestOptionsWithBody, } from './request.js';

package/dist/session/routing/index.js

@@ -2,4 +2,4 @@ export { admitSessionAuth, resolveAuth, } from './auth.js';
 export { RouteCache, } from './cache.js';
 export { requireResultKind, SessionDispatcher } from './dispatch.js';
 export {} from './envelope.js';
-export { admitEnvelopeTransport, admitRequestOptions, } from './request.js';
+export { admitEnvelopeTransport, admitInvocationOptions, admitRequestOptions, } from './request.js';

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,11 @@ 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 { 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 { 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. */
@@ -44,6 +45,7 @@ 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;
@@ -60,8 +62,13 @@ export declare class ClientSession {
     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,11 @@ 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 { 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,6 +24,7 @@ export class ClientSession {
     schema;
     graph;
     auth;
+    content;
     ownedPool;
     discovery;
     dispatcher;
@@ -106,6 +108,16 @@ export class ClientSession {
             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,
@@ -134,23 +146,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 +180,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() {

package/dist/session/session.typecheck.js

@@ -2,6 +2,8 @@ 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 { isBinaryInput } from '@astrale-os/kernel-dsl/v1/language';
+import { call } from '../client/index.js';
 import { ClientSession, createSessionCredentialProvider, reference } from './index.js';
 void new ClientSession(options);
 void auth;
@@ -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;

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,27 @@ 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 +187,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.72",
   "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.55",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.40",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.61",
     "@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.63",
     "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~1.1.0",
     "@types/node": "^22.0.0",
     "typescript": "7.0.2",