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

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/discovery/index.d.ts

@@ -4,6 +4,7 @@ import type { Fetch } from '../../transport/http/index.js';
 import type { SessionOperation, SessionPolicy } from '../context/index.js';
 import type { SessionSnapshot } from './snapshot.js';
 export type { SessionSnapshot } from './snapshot.js';
+export { boundedResponse, requireExactResponse } from './publication.js';
 export interface SessionDiscovery {
     readonly kernel: IssuerId;
     publication(operation: SessionOperation): Promise<publication.Publication>;

package/dist/session/discovery/index.js

@@ -1,6 +1,7 @@
 import { BundleDiscovery } from './bundle.js';
 import { SessionDiscovery as SessionDiscoveryImplementation } from './discovery.js';
 import { PublicationDiscovery } from './publication.js';
+export { boundedResponse, requireExactResponse } from './publication.js';
 export function createSessionDiscovery(options) {
     return new SessionDiscoveryImplementation(options.kernel, options.policy, new PublicationDiscovery({
         kernel: options.kernel,

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,13 +30,15 @@ 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>;
+export declare function matchesCallable(target: PathValue, callable: KeyType.Callable): boolean;
 export {};

package/dist/session/reference.js

@@ -52,7 +52,7 @@ export function admitReference(input) {
         outputMode: input.outputMode,
     });
 }
-function matchesCallable(target, callable) {
+export function matchesCallable(target, callable) {
     const coordinate = callableAddress(callable);
     const { anchor, steps } = target.ast;
     const last = steps.at(-1);

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;

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

@@ -2,6 +2,7 @@ import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { PathLike } from '@astrale-os/kernel-core/path';
 import type { Domain } from '@astrale-os/kernel-dsl/v1/domain';
 import type { publication } from '@astrale-os/kernel-protocol';
+import type { AuthApi } from '../auth/index.js';
 import type { Call, Input, Result } from '../client/index.js';
 import type { DomainBinding, GraphApi } from '../graph/index.js';
 import type { ClientFactory, ClientPool as ClientPoolType } from '../pool/index.js';
@@ -9,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. */
@@ -42,6 +44,8 @@ export declare class ClientSession {
     readonly kernel: IssuerId;
     readonly schema: SchemaApi;
     readonly graph: GraphApi;
+    readonly auth: AuthApi;
+    readonly content: ContentApi;
     private readonly ownedPool?;
     private readonly discovery;
     private readonly dispatcher;
@@ -58,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;