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

package/dist/auth/credential.d.ts

@@ -13,7 +13,11 @@ export interface ImpersonateOptions extends MintOptions {
 export interface DelegateOptions {
     readonly audience: string;
     readonly ttlSeconds: number;
-    readonly attenuation: UnresolvedIdentityExpr;
+    /**
+     * Sent only when present; the Kernel reads absence as self. A Kernel whose `Identity.delegate`
+     * still requires it rejects the omission.
+     */
+    readonly attenuation?: UnresolvedIdentityExpr;
 }
 export declare const IDENTITY_IMPERSONATE_PATH: NodePath;
 export declare const IDENTITY_MINT_PATH: NodePath;

package/dist/client/client.d.ts

@@ -1,14 +1,14 @@
 import type { invocation as protocol } from '@astrale-os/kernel-protocol';
 import type { Transport } from '../transport/index.js';
 import type { AuthenticatedClient, RemoteCredential } from './credential.js';
-import type { Call, ClientDispatchOptions } from './request.js';
+import type { Call, ClientDispatchOptions, ClientDispatchOptionsWithBody } from './request.js';
 import type { BinaryResponse, Result, StreamResult, ValueResult } from './result.js';
 import { type HttpTransportOptions } from '../transport/http/index.js';
 export type ClientOptions = HttpTransportOptions | {
     readonly transport: Transport;
 };
 /** Package-private redirect continuation path; intentionally absent from the public Client facade. */
-export declare function dispatchTrace(client: Client, credential: RemoteCredential | undefined, call: Call, options: ClientDispatchOptions | undefined, trace: protocol.Trace): Promise<Result>;
+export declare function dispatchTrace(client: Client, credential: RemoteCredential | undefined, call: Call, options: ClientDispatchOptions | ClientDispatchOptionsWithBody | undefined, trace: protocol.Trace): Promise<Result>;
 /** Pure client for the universal remote Function invocation boundary. */
 export declare class Client implements AuthenticatedClient {
     private readonly transport;
@@ -16,7 +16,9 @@ export declare class Client implements AuthenticatedClient {
     private closed;
     constructor(options: ClientOptions);
     dispatch(call: Call, options?: ClientDispatchOptions): Promise<Result>;
+    dispatch(call: Call, options: ClientDispatchOptionsWithBody): Promise<Result>;
     call(call: Call, options?: ClientDispatchOptions): Promise<ValueResult>;
+    call(call: Call, options: ClientDispatchOptionsWithBody): Promise<ValueResult>;
     stream(call: Call, options?: ClientDispatchOptions): Promise<StreamResult>;
     binary(call: Call, options?: ClientDispatchOptions): Promise<BinaryResponse>;
     as(credential: RemoteCredential): AuthenticatedClient;

package/dist/client/client.js

@@ -30,7 +30,7 @@ export class Client {
         return this.dispatchWith(undefined, call, options);
     }
     call(call, options) {
-        return requireValue(this.dispatch(call, options));
+        return requireValue(this.dispatchWith(undefined, call, options));
     }
     stream(call, options) {
         return requireStream(this.dispatch(call, options));
@@ -57,7 +57,18 @@ export class Client {
             ? undefined
             : await resolveCredential(credential, request.options.signal);
         requireRequestLive(request.options.signal);
-        const result = await this.transport.dispatch(invocation(request, resolved, trace), request.options);
+        const envelope = invocation(request, resolved, trace);
+        let result;
+        if (request.body === undefined) {
+            result = await this.transport.dispatch(envelope, request.options);
+        }
+        else {
+            const transport = this.transport;
+            if (!(transport instanceof HttpTransport)) {
+                throw new TypeError('Binary dispatch requires HTTP transport.');
+            }
+            result = await transport.dispatchBinary(envelope, request.body, request.options);
+        }
         if (result.kind === 'stale')
             throw admittedStaleRouteError(result.current, result.invocation);
         if (result.kind === 'miss')

package/dist/client/credential.d.ts

@@ -1,12 +1,14 @@
-import type { Call, ClientDispatchOptions } from './request.js';
+import type { Call, ClientDispatchOptions, ClientDispatchOptionsWithBody } from './request.js';
 import type { BinaryResponse, Result, StreamResult, ValueResult } from './result.js';
 export type RemoteCredential = string | (() => string | Promise<string>);
 export interface AuthenticatedClient {
     dispatch(call: Call, options?: ClientDispatchOptions): Promise<Result>;
+    dispatch(call: Call, options: ClientDispatchOptionsWithBody): Promise<Result>;
     call(call: Call, options?: ClientDispatchOptions): Promise<ValueResult>;
+    call(call: Call, options: ClientDispatchOptionsWithBody): Promise<ValueResult>;
     stream(call: Call, options?: ClientDispatchOptions): Promise<StreamResult>;
     binary(call: Call, options?: ClientDispatchOptions): Promise<BinaryResponse>;
 }
-export type CredentialDispatch = (credential: RemoteCredential, call: Call, options?: ClientDispatchOptions) => Promise<Result>;
+export type CredentialDispatch = (credential: RemoteCredential, call: Call, options?: ClientDispatchOptions | ClientDispatchOptionsWithBody) => Promise<Result>;
 export declare function authenticated(dispatchWith: CredentialDispatch, credential: RemoteCredential): AuthenticatedClient;
 export declare function resolveCredential(input: RemoteCredential, signal?: AbortSignal): Promise<string>;

package/dist/client/credential.js

@@ -1,10 +1,15 @@
 import { ClientError } from '../errors/index.js';
 import { requireBinary, requireStream, requireValue } from './result.js';
 export function authenticated(dispatchWith, credential) {
-    const dispatch = (call, options) => dispatchWith(credential, call, options);
+    function dispatch(call, options) {
+        return dispatchWith(credential, call, options);
+    }
+    function call(request, options) {
+        return requireValue(dispatchWith(credential, request, options));
+    }
     return Object.freeze({
         dispatch,
-        call: (call, options) => requireValue(dispatch(call, options)),
+        call,
         stream: (call, options) => requireStream(dispatch(call, options)),
         binary: (call, options) => requireBinary(dispatch(call, options)),
     });

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
 export { Client, dispatchTrace, type ClientOptions } from './client.js';
 export { acceptCall } from './admission.js';
 export type { AuthenticatedClient, RemoteCredential } from './credential.js';
-export { call, type Call, type ClientDispatchOptions } from './request.js';
+export { call, type Call, type ClientDispatchOptions, type ClientDispatchOptionsWithBody, } from './request.js';
 export type { Binary, BinaryResponse, Input, RedirectResult, Result, Stream, StreamResult, ValueResult, } from './result.js';
 export { isAdmittedMissError, isAdmittedStaleRouteError } from './routing-control.js';

package/dist/client/index.js

@@ -1,4 +1,4 @@
 export { Client, dispatchTrace } from './client.js';
 export { acceptCall } from './admission.js';
-export { call } from './request.js';
+export { call, } from './request.js';
 export { isAdmittedMissError, isAdmittedStaleRouteError } from './routing-control.js';

package/dist/client/request.d.ts

@@ -9,19 +9,25 @@ export interface Call {
     readonly input: Input;
 }
 export interface ClientDispatchOptions extends RequestOptions {
+    readonly body?: never;
     /** Untrusted delivery context; it changes neither Call meaning nor authority. */
     readonly delegate?: protocol.Delegate;
     readonly routing?: protocol.Routing;
     /** Package-owned local-target or remote-revision precondition for a bound invocation. */
     readonly schema?: protocol.SchemaTarget;
 }
+export type ClientDispatchOptionsWithBody = Omit<ClientDispatchOptions, 'body' | 'idempotencyKey'> & {
+    readonly body: Blob;
+    readonly idempotencyKey?: never;
+};
 export interface AdmittedRequest {
     readonly call: protocol.Call;
     readonly delegate?: protocol.Delegate;
     readonly routing?: protocol.Routing;
     readonly schema?: protocol.SchemaTarget;
     readonly options: RequestOptions;
+    readonly body?: Blob;
 }
 export declare function call(target: PathLike | Target, input: Input): Call;
-export declare function admitRequest(input: Call, options: ClientDispatchOptions | undefined, lifecycle: AbortSignal): AdmittedRequest;
+export declare function admitRequest(input: Call, options: ClientDispatchOptions | ClientDispatchOptionsWithBody | undefined, lifecycle: AbortSignal): AdmittedRequest;
 export declare function invocation(request: AdmittedRequest, credential?: string, trace?: protocol.Trace): TransportRequest;

package/dist/client/request.js

@@ -5,7 +5,8 @@ export function call(target, input) {
 }
 export function admitRequest(input, options, lifecycle) {
     const call = acceptCall(input);
-    const admittedOptions = lifecycleOptions(admitRequestOptions(options), lifecycle);
+    const admitted = admitRequestOptions(options);
+    const admittedOptions = lifecycleOptions(admitted.options, lifecycle);
     const delegate = admitDelegate(options?.delegate);
     const routing = admitRouting(options?.routing);
     const schema = admitSchemaTarget(options?.schema);
@@ -14,6 +15,7 @@ export function admitRequest(input, options, lifecycle) {
         ...(delegate === undefined ? {} : { delegate }),
         ...(routing === undefined ? {} : { routing }),
         ...(schema === undefined ? {} : { schema }),
+        ...(admitted.body === undefined ? {} : { body: admitted.body }),
         options: admittedOptions,
     });
 }
@@ -41,11 +43,19 @@ export function invocation(request, credential, trace) {
 }
 function admitRequestOptions(input) {
     if (input === undefined)
-        return undefined;
+        return {};
     if (input === null || typeof input !== 'object' || Array.isArray(input)) {
         throw new TypeError('Client request options must be an object.');
     }
-    if (Reflect.ownKeys(input).some((field) => !['signal', 'timeoutMs', 'idempotencyKey', 'delegate', 'routing', 'schema'].includes(String(field)))) {
+    if (Reflect.ownKeys(input).some((field) => ![
+        'signal',
+        'timeoutMs',
+        'idempotencyKey',
+        'delegate',
+        'routing',
+        'schema',
+        'body',
+    ].includes(String(field)))) {
         throw new TypeError('Client request options contain unsupported fields.');
     }
     if (input.timeoutMs !== undefined &&
@@ -54,13 +64,28 @@ function admitRequestOptions(input) {
             input.timeoutMs > 2_147_483_647)) {
         throw new TypeError('Client request timeoutMs must be a positive safe platform integer.');
     }
+    const hasBody = Object.hasOwn(input, 'body');
+    let body;
+    if (hasBody) {
+        const candidate = input.body;
+        if (!(candidate instanceof Blob)) {
+            throw new TypeError('Binary input must be a Blob or File.');
+        }
+        body = candidate;
+    }
+    if (body !== undefined && input.idempotencyKey !== undefined) {
+        throw new TypeError('Binary requests cannot carry an idempotency key.');
+    }
     const idempotencyKey = input.idempotencyKey === undefined
         ? undefined
         : invocationProtocol.acceptIdempotencyKey(input.idempotencyKey, 'request.idempotencyKey');
     return Object.freeze({
-        ...(input.signal === undefined ? {} : { signal: input.signal }),
-        ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
-        ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+        options: Object.freeze({
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+            ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+        }),
+        ...(body === undefined ? {} : { body }),
     });
 }
 function admitDelegate(input) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Target, targetPath } from '@astrale-os/kernel-core/callable';
-export { Client, call, type AuthenticatedClient, type Call, type ClientDispatchOptions, type ClientOptions, type Binary, type BinaryResponse, type Input, type RemoteCredential, type Result, type Stream, type StreamResult, type ValueResult, } from './client/index.js';
+export { Client, call, type AuthenticatedClient, type Call, type ClientDispatchOptions, type ClientDispatchOptionsWithBody, type ClientOptions, type Binary, type BinaryResponse, type Input, type RemoteCredential, type Result, type Stream, type StreamResult, type ValueResult, } from './client/index.js';
 export * from './errors/index.js';
 export { type RequestOptions, type MissControl, type StaleControl, type Transport, type TransportRequest, type TransportResult, } from './transport/index.js';
 export { HttpTransport, type Fetch, type HttpTransportOptions } from './transport/http/index.js';

package/dist/session/bound.d.ts

@@ -1,21 +1,22 @@
 import type { IssuerId } from '@astrale-os/kernel-core/auth';
 import type { AuthApi } from '../auth/index.js';
 import type { SchemaApi } from '../schema/index.js';
+import type { ContentApi } from './content.js';
 import type { SessionControlOptions } from './context/index.js';
-import type { CallableReference, InputOfReference, OutputOfReference } from './reference.js';
 import type { SessionRequestOptions } from './routing/index.js';
 import type { ClientSession } from './session.js';
 import type { ViewCatalog } from './views/index.js';
-import { type Binary, type Call, type Input, type Result, type Stream } from '../client/index.js';
+import { type Binary, type Call, type Stream } from '../client/index.js';
 import { type GraphApi } from '../graph/index.js';
 /** Exact live Session surface captured by one credential-bound Kernel view. */
 export interface BoundSessionSource {
     readonly kernel: IssuerId;
     readonly schema: SchemaApi;
     readonly auth: Pick<AuthApi, 'admit'>;
-    dispatch(call: Call, options?: SessionRequestOptions): 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>>;
+    readonly content?: ContentApi;
+    dispatch: ClientSession['dispatch'];
+    call: ClientSession['call'];
+    invoke: ClientSession['invoke'];
     stream(call: Call, options?: SessionRequestOptions): Promise<Stream>;
     binary(call: Call, options?: SessionRequestOptions): Promise<Binary>;
     viewsFor(target: Parameters<ClientSession['viewsFor']>[0], options?: SessionControlOptions): Promise<ViewCatalog>;
@@ -35,9 +36,10 @@ export interface BoundClientSession extends GraphApi {
     readonly kernel: IssuerId;
     readonly auth: AuthApi;
     readonly schema: SchemaApi;
-    dispatch(call: Call, options?: SessionRequestOptions): 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>>;
+    readonly content: ContentApi;
+    dispatch: ClientSession['dispatch'];
+    call: ClientSession['call'];
+    invoke: ClientSession['invoke'];
     stream(call: Call, options?: SessionRequestOptions): Promise<Stream>;
     binary(call: Call, options?: SessionRequestOptions): Promise<Binary>;
     viewsFor: BoundSessionSource['viewsFor'];

package/dist/session/bound.js

@@ -12,14 +12,22 @@ export function bindSession(source, controls) {
     const invokeSource = capture(source, 'invoke');
     const streamSource = capture(source, 'stream');
     const binarySource = capture(source, 'binary');
+    const contentSource = source.content === undefined ? unavailableContent : source.content;
+    if (contentSource === null || typeof contentSource !== 'object')
+        invalid();
+    const uploadSource = capture(contentSource, 'upload');
+    const downloadSource = capture(contentSource, 'download');
     const viewsForSource = capture(source, 'viewsFor');
     const schemaSource = captureSchema(source.schema);
-    const dispatch = (input, options) => dispatchSource(input, requestOptions(options, admittedControls));
+    const dispatch = ((input, options) => dispatchSource(input, requestOptions(options, admittedControls)));
     const admit = (input, options) => admitSource(input, mergeOptions(options, admittedControls));
-    const call = (input, options) => callSource(input, requestOptions(options, admittedControls));
-    const invoke = (reference, input, options) => invokeSource(reference, input, requestOptions(options, admittedControls));
+    const call = ((input, options) => callSource(input, requestOptions(options, admittedControls)));
+    const invoke = ((reference, input, options) => invokeSource(reference, input, requestOptions(options, admittedControls)));
     const stream = (input, options) => streamSource(input, requestOptions(options, admittedControls));
     const binary = (input, options) => binarySource(input, requestOptions(options, admittedControls));
+    const upload = (input, options) => uploadSource(input, mergeOptions(options, admittedControls));
+    const download = (location, options) => downloadSource(location, controlOptions(options, admittedControls));
+    const content = Object.freeze({ upload, download });
     const viewsFor = (target, options) => viewsForSource(target, controlOptions(options, admittedControls));
     const install = (request, options) => schemaSource.install(request, controlOptions(options, admittedControls));
     const uninstall = (request, options) => schemaSource.uninstall(request, controlOptions(options, admittedControls));
@@ -39,9 +47,18 @@ export function bindSession(source, controls) {
         invoke,
         stream,
         binary,
+        content,
         viewsFor,
     });
 }
+const unavailableContent = Object.freeze({
+    upload: (() => {
+        throw new TypeError('Content transfer is unavailable from this bound Session source.');
+    }),
+    download: () => {
+        throw new TypeError('Content transfer is unavailable from this bound Session source.');
+    },
+});
 function admitControls(input) {
     if (input === undefined)
         return undefined;

package/dist/session/content.d.ts

@@ -0,0 +1,30 @@
+import type { schema } from '@astrale-os/kernel-dsl/v1';
+import type { Ref } from '@astrale-os/kernel-protocol/artifact';
+import { Path } from '@astrale-os/kernel-core/path';
+import type { Binary, Input, Result } from '../client/index.js';
+import type { SessionControlOptions, SessionOperation } from './context/index.js';
+import type { CallableReference } from './reference.js';
+import type { SessionRequestOptionsWithBody } from './routing/index.js';
+export interface ContentLocation {
+    readonly node: string;
+    readonly property: string;
+}
+export interface ContentUploadOptions extends SessionControlOptions {
+    readonly mediaType: string;
+}
+export interface ContentUploadResult {
+    readonly receipt: schema.values.BlobReceipt;
+    readonly ref: Ref;
+    readonly expiresAt: string;
+}
+export interface ContentApi {
+    upload(source: Blob | Uint8Array, options: ContentUploadOptions): Promise<ContentUploadResult>;
+    download(location: ContentLocation, options?: SessionControlOptions): Promise<Binary>;
+}
+export interface ContentSessionDependencies {
+    readonly operation: (options: SessionControlOptions) => SessionOperation;
+    readonly invoke: (reference: CallableReference<unknown, unknown, 'binary'>, input: unknown, options: SessionRequestOptionsWithBody, operation: SessionOperation) => Promise<unknown>;
+    readonly dispatch: (target: Path, input: Input, operation: SessionOperation, body?: Blob) => Promise<Result>;
+}
+/** Transfer immutable content over the authenticated Session routing conversation. */
+export declare function createContentApi(dependencies: ContentSessionDependencies): ContentApi;

package/dist/session/content.js

@@ -0,0 +1,160 @@
+import { NodeId } from '@astrale-os/kernel-core/graph/node';
+import { Path } from '@astrale-os/kernel-core/path';
+import { K } from '@astrale-os/kernel-core/schema';
+import { download } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
+import { PropertyKey } from '@astrale-os/kernel-dsl/v1/addressing';
+import * as artifact from '@astrale-os/kernel-protocol/artifact';
+import { CODES } from '@astrale-os/kernel-protocol/errors';
+import { ClientError, ProtocolError, ResponseError, TransportError } from '../errors/index.js';
+import { admitControlOptions, runSessionOperation } from './context/index.js';
+import { reference } from './reference.js';
+import { requireResultKind } from './routing/index.js';
+const UPLOAD = reference(K, K.functions.upload);
+const DOWNLOAD = Path.project(download);
+const CONTENT_TIMEOUT_MS = 30 * 60 * 1_000;
+const MAXIMUM_ATTEMPTS = 3;
+/** Transfer immutable content over the authenticated Session routing conversation. */
+export function createContentApi(dependencies) {
+    async function upload(source, options) {
+        const body = admitBody(source);
+        const mediaType = admitMediaType(options?.mediaType);
+        const operation = dependencies.operation(contentControls(options));
+        let last;
+        for (let attempt = 0; attempt < MAXIMUM_ATTEMPTS; attempt++) {
+            try {
+                const result = await dependencies.invoke(UPLOAD, { mediaType }, { body }, operation);
+                return uploadResult(result);
+            }
+            catch (cause) {
+                last = cause;
+                if (!retryable(cause) || attempt + 1 === MAXIMUM_ATTEMPTS || operation.signal.aborted) {
+                    throw cause;
+                }
+                await runSessionOperation(operation, (signal) => delay(200 * 2 ** attempt, signal));
+            }
+        }
+        throw last;
+    }
+    async function download(location, options) {
+        const operation = dependencies.operation(contentControls(options));
+        const result = await dependencies.dispatch(DOWNLOAD, admitLocation(location), operation);
+        return verifiedDownload(requireResultKind('binary', result).value);
+    }
+    return Object.freeze({ upload, download });
+}
+function admitLocation(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Content location is invalid.');
+    }
+    return Object.freeze({ node: NodeId(input.node), property: PropertyKey(input.property) });
+}
+function admitBody(input) {
+    if (typeof Blob !== 'undefined' && input instanceof Blob)
+        return input;
+    if (input instanceof Uint8Array) {
+        // Blob snapshots an ArrayBuffer view; a SharedArrayBuffer view needs an owned copy.
+        const bytes = input.buffer instanceof ArrayBuffer
+            ? input
+            : new Uint8Array(input);
+        return new Blob([bytes]);
+    }
+    throw new TypeError('Content upload source must be a Blob, File, or Uint8Array.');
+}
+function admitMediaType(input) {
+    if (typeof input !== 'string')
+        throw new TypeError('Content upload mediaType is required.');
+    return artifact.identify(new Uint8Array(), input).mediaType;
+}
+function contentControls(input) {
+    const controls = admitControlOptions(input);
+    return Object.freeze({ ...controls, timeoutMs: controls.timeoutMs ?? CONTENT_TIMEOUT_MS });
+}
+function uploadResult(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new ClientError('Content upload returned an invalid receipt.');
+    }
+    const value = input;
+    if (typeof value.receipt !== 'string' ||
+        value.receipt.length === 0 ||
+        typeof value.expiresAt !== 'string' ||
+        !Number.isFinite(Date.parse(value.expiresAt))) {
+        throw new ClientError('Content upload returned an invalid receipt.');
+    }
+    let ref;
+    try {
+        ref = artifact.accept(value.ref);
+    }
+    catch (cause) {
+        throw new ClientError('Content upload returned an invalid Ref.', { cause });
+    }
+    return Object.freeze({
+        receipt: value.receipt,
+        ref,
+        expiresAt: value.expiresAt,
+    });
+}
+function retryable(cause) {
+    return ((cause instanceof TransportError && cause.context.kind === 'invocation') ||
+        (cause instanceof ResponseError &&
+            (cause.reason?.code === 'BLOB_UNAVAILABLE' ||
+                cause.code === CODES.CANCELLED ||
+                cause.code === CODES.DEADLINE_EXCEEDED ||
+                cause.code === CODES.OUTCOME_UNKNOWN)));
+}
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', abort);
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', abort, { once: true });
+    });
+}
+async function verifiedDownload(input) {
+    const raw = input.headers?.['x-astrale-blob-size'];
+    if (raw === undefined || !/^(?:0|[1-9][0-9]*)$/u.test(raw)) {
+        await cancelBinary(input);
+        throw new ProtocolError('Content download omitted its exact content size.');
+    }
+    const expected = Number(raw);
+    if (!Number.isSafeInteger(expected)) {
+        await cancelBinary(input);
+        throw new ProtocolError('Content download content size is invalid.');
+    }
+    if (input.body instanceof Uint8Array) {
+        if (input.body.byteLength !== expected) {
+            throw new ProtocolError('Content download ended before its exact content size.');
+        }
+        return input;
+    }
+    return Object.freeze({ ...input, body: exactContentBytes(input.body, expected) });
+}
+async function cancelBinary(input) {
+    if (input.body instanceof Uint8Array)
+        return;
+    try {
+        await input.body[Symbol.asyncIterator]().return?.();
+    }
+    catch {
+        // Preserve the admission error after the response stream has been closed.
+    }
+}
+async function* exactContentBytes(body, expected) {
+    let received = 0;
+    for await (const bytes of body) {
+        received += bytes.byteLength;
+        if (received > expected) {
+            throw new ProtocolError('Content download exceeded its exact content size.');
+        }
+        yield bytes;
+    }
+    if (received !== expected) {
+        throw new ProtocolError('Content download ended before its exact content size.');
+    }
+}

package/dist/session/context/operation.d.ts

@@ -13,7 +13,11 @@ export declare function createSessionOperation(lifecycle: AbortSignal, input: {
     readonly idempotencyKey?: RequestOptions['idempotencyKey'];
 } | undefined, defaultTimeoutMs: number): SessionOperation;
 export declare function remainingSessionTime(operation: SessionOperation): number;
-export declare function sessionTransportOptions(operation: SessionOperation, idempotencyKey?: RequestOptions['idempotencyKey']): RequestOptions;
+export declare function sessionTransportOptions(operation: SessionOperation): {
+    readonly signal: AbortSignal;
+    readonly timeoutMs: number;
+};
+export declare function sessionTransportOptions(operation: SessionOperation, idempotencyKey: RequestOptions['idempotencyKey']): RequestOptions;
 /** Settle independently of a caller capability that ignores its supplied AbortSignal. */
 export declare function runSessionOperation<Result>(operation: SessionOperation, task: (signal: AbortSignal) => Result | PromiseLike<Result>): Promise<Result>;
 export declare function requireSessionOperation(operation: SessionOperation): void;

package/dist/session/index.d.ts

@@ -1,10 +1,11 @@
 export type { SessionControlOptions, SessionPolicy } from './context/index.js';
+export type { ContentApi, ContentLocation, ContentUploadOptions, ContentUploadResult, } from './content.js';
 export { bindSession, type BoundClientSession, type BoundSessionControls, type BoundSessionSource, } from './bound.js';
 export { createSessionCredentialProvider, type SessionCredential, type SessionCredentialProvider, type SessionCredentialProviderOptions, type SessionCredentialState, } from './credential/index.js';
 export type { SessionSnapshot } from './discovery/index.js';
-export type { Auth, PersistedRoute, SessionRouteArtifact, SessionRouteStore, SessionAuth, SessionEnvelopeTransport, SessionRequestOptions, } from './routing/index.js';
+export type { Auth, PersistedRoute, SessionRouteArtifact, SessionRouteStore, SessionAuth, SessionEnvelopeTransport, SessionRequestOptions, SessionRequestOptionsWithBody, } from './routing/index.js';
 export { ClientSession, connect, type ClientSessionOptions, type ConnectOptions, } from './session.js';
-export type { CallableReference, InputOfReference, InstanceCallableReference, OutputOfReference, } from './reference.js';
+export type { CallableReference, InputOfReference, InputModeOfReference, InstanceCallableReference, OutputOfReference, } from './reference.js';
 export { reference } from './reference.js';
 export type { ResolvedView, ViewCatalog } from './views/index.js';
 export type { DomainBinding } from '../graph/domain/index.js';

package/dist/session/reference.d.ts

@@ -1,12 +1,13 @@
 import type { Path as PathValue, PathLike } from '@astrale-os/kernel-core/path';
-import type { CallableInputOf, CallableOutputOf, CallableResultOf, Domain, ResolvedFunction, ExecutableMethod } from '@astrale-os/kernel-dsl/v1';
+import type { CallableInputOf, CallableInputModeOf, CallableOutputOf, CallableResultOf, Domain, ResolvedFunction, ExecutableMethod } from '@astrale-os/kernel-dsl/v1';
 import type { Revision } 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';
 declare const REFERENCE_INPUT: unique symbol;
+declare const REFERENCE_INPUT_MODE: unique symbol;
 declare const REFERENCE_OUTPUT: unique symbol;
-export interface CallableReference<InputValue = Input, Output = unknown> {
+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;
@@ -16,6 +17,7 @@ export interface CallableReference<InputValue = Input, Output = unknown> {
     readonly target: PathValue;
     readonly outputMode: 'value' | 'stream' | 'binary';
     readonly [REFERENCE_INPUT]?: InputValue;
+    readonly [REFERENCE_INPUT_MODE]?: InputMode;
     readonly [REFERENCE_OUTPUT]?: Output;
 }
 export interface InstanceCallableReference<InputValue = Input, Output = unknown> {
@@ -28,12 +30,13 @@ export interface InstanceCallableReference<InputValue = Input, Output = unknown>
 }
 export type InputOfReference<Reference extends CallableReference<unknown>> = Reference extends CallableReference<infer InputValue, unknown> ? InputValue : never;
 export type OutputOfReference<Reference extends CallableReference<unknown>> = Reference extends CallableReference<infer _Input, infer Output> ? Output : never;
+export type InputModeOfReference<Reference extends CallableReference<unknown>> = Reference extends CallableReference<infer _Input, infer _Output, infer Mode> ? Mode : never;
 type ReferenceInput<Callable> = unknown extends CallableInputOf<Callable> ? Input : CallableInputOf<Callable>;
 type ReferenceOutput<Callable> = unknown extends CallableOutputOf<Callable> ? unknown : CallableResultOf<Callable, Binary>;
 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>>;
+export declare function reference<const Callable extends ResolvedFunction | ExecutableStaticMethod>(domain: Pick<Domain, 'origin' | 'revision'>, 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 admitReference(input: CallableReference<unknown>): CallableReference<unknown>;

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

@@ -1,5 +1,6 @@
 import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { Result } from '../../client/index.js';
+import type { Fetch } from '../../transport/http/index.js';
 import type { SessionOperation, SessionPolicy } from '../context/index.js';
 import type { SessionAuth } from './auth.js';
 import type { RouteCache } from './cache.js';
@@ -16,15 +17,24 @@ export interface SessionDispatcherOptions {
     readonly policy: Readonly<SessionPolicy>;
     readonly envelopeTransport: SessionEnvelopeTransport;
     readonly requireOpen: () => void;
+    readonly streamingHttp: {
+        readonly fetch: Fetch;
+        readonly maximumResponseBytes: number;
+        readonly timeoutMs: number;
+    };
 }
 export declare class SessionDispatcher {
     private readonly state;
     constructor(state: SessionDispatcherOptions);
     dispatch(input: Parameters<typeof acceptCall>[0], options: SessionRequestOptions, operation: SessionOperation): Promise<Result>;
+    /** Reuse Session authority and route recovery while forcing HTTP for streaming calls. */
+    dispatchHttp(input: Parameters<typeof acceptCall>[0], options: SessionRequestOptions, operation: SessionOperation, body?: Blob): Promise<Result>;
+    private dispatchWith;
     private dispatchSource;
     private followSource;
     private dispatchDestinationWithRecovery;
     private dispatchDestination;
+    private streamingClientFor;
 }
 export declare function requireResultKind<Kind extends 'value' | 'stream' | 'binary'>(expected: Kind, result: Result): Extract<Result, {
     kind: Kind;