@astrale-os/kernel-client 0.6.0-beta.8 → 0.6.0-beta.81

package/dist/session/bound.js

@@ -0,0 +1,110 @@
+import { createAuth } from '../auth/auth.js';
+import { call as createCall, } from '../client/index.js';
+import { createGraph } from '../graph/index.js';
+/** Capture one Session into the ordinary graph, auth, and invocation Kernel journey. */
+export function bindSession(source, controls) {
+    if (source === null || typeof source !== 'object')
+        invalid();
+    const admittedControls = admitControls(controls);
+    const dispatchSource = capture(source, 'dispatch');
+    const admitSource = capture(source.auth, 'admit');
+    const callSource = capture(source, 'call');
+    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 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 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));
+    const inspect = (origin, options) => schemaSource.inspect(origin, controlOptions(options, admittedControls));
+    const bundle = (origin, options) => schemaSource.bundle(origin, controlOptions(options, admittedControls));
+    const dependencies = (origin, options) => schemaSource.dependencies(origin, controlOptions(options, admittedControls));
+    const schema = Object.freeze({ install, uninstall, inspect, bundle, dependencies });
+    const graph = createGraph(call);
+    const auth = createAuth((target, input, options) => call(createCall(target, input), options), admit);
+    return Object.freeze({
+        ...graph,
+        kernel: source.kernel,
+        auth,
+        schema,
+        dispatch,
+        call,
+        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;
+    if (input === null ||
+        typeof input !== 'object' ||
+        !(input.signal instanceof AbortSignal) ||
+        !Number.isFinite(input.deadline)) {
+        invalid();
+    }
+    return Object.freeze({ signal: input.signal, deadline: input.deadline });
+}
+function requestOptions(options, controls) {
+    return mergeOptions(options, controls);
+}
+function controlOptions(options, controls) {
+    return mergeOptions(options, controls);
+}
+function mergeOptions(options, controls) {
+    if (controls === undefined)
+        return options;
+    if (options?.signal !== undefined && options.signal !== controls.signal) {
+        throw new TypeError('Bound ClientSession cancellation cannot be replaced.');
+    }
+    if (controls.signal.aborted)
+        throw controls.signal.reason ?? new Error('Invocation cancelled.');
+    const remaining = Math.max(1, Math.ceil(controls.deadline - Date.now()));
+    const timeoutMs = options?.timeoutMs === undefined ? remaining : Math.min(options.timeoutMs, remaining);
+    return Object.freeze({ ...options, signal: controls.signal, timeoutMs });
+}
+function capture(source, key) {
+    const value = source[key];
+    if (typeof value !== 'function')
+        invalid();
+    return value.bind(source);
+}
+function captureSchema(input) {
+    if (input === null || typeof input !== 'object')
+        invalid();
+    return Object.freeze({
+        install: capture(input, 'install'),
+        uninstall: capture(input, 'uninstall'),
+        inspect: capture(input, 'inspect'),
+        bundle: capture(input, 'bundle'),
+        dependencies: capture(input, 'dependencies'),
+    });
+}
+function invalid() {
+    throw new TypeError('Bound ClientSession source is invalid.');
+}

package/dist/session/content.d.ts

@@ -0,0 +1,27 @@
+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';
+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 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,158 @@
+import { NodeId } from '@astrale-os/kernel-core/graph/node';
+import { Path } from '@astrale-os/kernel-core/path';
+import { download, upload } 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 { requireResultKind } from './routing/index.js';
+const UPLOAD = Path.project(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.dispatch(UPLOAD, { mediaType }, operation, body);
+                return uploadResult(requireResultKind('value', result).value);
+            }
+            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/control.d.ts

@@ -3,4 +3,3 @@ export interface SessionControlOptions {
     readonly timeoutMs?: number;
 }
 export declare function admitControlOptions(input: SessionControlOptions | undefined): Readonly<SessionControlOptions>;
-//# sourceMappingURL=control.d.ts.map

package/dist/session/context/control.js

@@ -15,4 +15,3 @@ export function admitControlOptions(input) {
             : { timeoutMs: platformDuration(input.timeoutMs, 'timeoutMs') }),
     });
 }
-//# sourceMappingURL=control.js.map

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

@@ -2,4 +2,3 @@ export { admitControlOptions, type SessionControlOptions } from './control.js';
 export { DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_MAXIMUM_ROUTES, DEFAULT_TIMEOUT_MS, platformDuration, positive, } from './limits.js';
 export { createSessionOperation, runSessionOperation, sessionTransportOptions, type SessionOperation, } from './operation.js';
 export { admitKernel, admitPolicy, allowEndpoint, kernelInvocationEndpoint, type SessionPolicy, } from './policy.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/session/context/index.js

@@ -2,4 +2,3 @@ export { admitControlOptions } from './control.js';
 export { DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_MAXIMUM_ROUTES, DEFAULT_TIMEOUT_MS, platformDuration, positive, } from './limits.js';
 export { createSessionOperation, runSessionOperation, sessionTransportOptions, } from './operation.js';
 export { admitKernel, admitPolicy, allowEndpoint, kernelInvocationEndpoint, } from './policy.js';
-//# sourceMappingURL=index.js.map

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

@@ -5,4 +5,3 @@ export declare const DEFAULT_TIMEOUT_MS = 30000;
 export declare const DEFAULT_MAXIMUM_ROUTES = 256;
 export declare function positive(input: number, label: string): number;
 export declare function platformDuration(input: number, label: string): number;
-//# sourceMappingURL=limits.d.ts.map

package/dist/session/context/limits.js

@@ -16,4 +16,3 @@ export function platformDuration(input, label) {
     }
     return admitted;
 }
-//# sourceMappingURL=limits.js.map

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

@@ -13,8 +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;
-//# sourceMappingURL=operation.d.ts.map

package/dist/session/context/operation.js

@@ -1,4 +1,4 @@
-import { ClientError } from '../../errors/index.js';
+import { SessionError } from '../../errors/index.js';
 /** Create one total wall-clock budget for a complete public Client Session operation. */
 export function createSessionOperation(lifecycle, input, defaultTimeoutMs) {
     const timeoutMs = input?.timeoutMs ?? defaultTimeoutMs;
@@ -22,7 +22,7 @@ export function remainingSessionTime(operation) {
     requireSessionOperation(operation);
     const remaining = operation.deadline - Date.now();
     if (remaining < 1)
-        throw new ClientError('Session operation timed out.');
+        throw new SessionError('Session operation timed out.', { failure: 'timeout' });
     return remaining;
 }
 export function sessionTransportOptions(operation, idempotencyKey) {
@@ -33,13 +33,8 @@ export function sessionTransportOptions(operation, idempotencyKey) {
     });
 }
 /** Settle independently of a caller capability that ignores its supplied AbortSignal. */
-export function runSessionOperation(operation, task) {
-    try {
-        requireSessionOperation(operation);
-    }
-    catch (error) {
-        return Promise.reject(error);
-    }
+export async function runSessionOperation(operation, task) {
+    requireSessionOperation(operation);
     let abort;
     const interrupted = new Promise((_resolve, reject) => {
         abort = () => reject(sessionInterruption(operation.signal.reason));
@@ -49,9 +44,14 @@ export function runSessionOperation(operation, task) {
         requireSessionOperation(operation);
         return task(operation.signal);
     });
-    return Promise.race([execution, interrupted]).finally(() => {
-        if (abort !== undefined)
-            operation.signal.removeEventListener('abort', abort);
+    return Promise.race([execution, interrupted])
+        .catch((cause) => {
+        if (operation.signal.aborted)
+            throw sessionInterruption(operation.signal.reason);
+        throw cause;
+    })
+        .finally(() => {
+        operation.signal.removeEventListener('abort', abort);
     });
 }
 export function requireSessionOperation(operation) {
@@ -60,11 +60,13 @@ export function requireSessionOperation(operation) {
     throw sessionInterruption(operation.signal.reason);
 }
 function sessionInterruption(reason) {
+    if (reason instanceof SessionError)
+        return reason;
     if (reason instanceof DOMException && reason.name === 'TimeoutError') {
-        return new ClientError('Session operation timed out.', { cause: reason });
+        return new SessionError('Session operation timed out.', { cause: reason, failure: 'timeout' });
     }
-    return reason instanceof Error
-        ? reason
-        : new ClientError('Session operation was cancelled.', { cause: reason });
+    return new SessionError('Session operation was cancelled.', {
+        cause: reason,
+        failure: 'cancelled',
+    });
 }
-//# sourceMappingURL=operation.js.map

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

@@ -9,4 +9,3 @@ export declare function admitKernel(input: string, insecure: boolean): IssuerId;
 export declare function kernelInvocationEndpoint(input: IssuerId): string;
 export declare function websocketEndpoint(input: string, insecure: boolean): string;
 export declare function allowEndpoint(url: string, policy: Readonly<SessionPolicy>): void;
-//# sourceMappingURL=policy.d.ts.map

package/dist/session/context/policy.js

@@ -67,4 +67,3 @@ export function allowEndpoint(url, policy) {
         throw new ClientError('Endpoint is denied by Session policy.');
     }
 }
-//# sourceMappingURL=policy.js.map

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

@@ -0,0 +1 @@
+export { createSessionCredentialProvider, delegationCoverageMs, type SessionCredential, type SessionCredentialProvider, type SessionCredentialProviderOptions, type SessionCredentialState, } from './provider.js';

package/dist/session/credential/index.js

@@ -0,0 +1 @@
+export { createSessionCredentialProvider, delegationCoverageMs, } from './provider.js';

package/dist/session/credential/limits.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Settlement allowance added to the declared delegation TTL to form the refresh threshold. It
+ * matches the destination-credential skew routing already applies to a warm entry, so a credential
+ * served here cannot expire between admission and delivery.
+ */
+export declare const SETTLEMENT_SKEW_MS = 5000;
+/** Total budget for one mint, matching the default Session operation budget. */
+export declare const MINT_TIMEOUT_MS = 30000;
+/** Bounded backoff between anticipation attempts after a failed mint. */
+export declare const BACKOFF_MS: readonly [1000, 2000, 4000];
+/** Steady retry interval once the bounded backoff is exhausted. */
+export declare const RETRY_INTERVAL_MS = 4000;

package/dist/session/credential/limits.js

@@ -0,0 +1,12 @@
+/**
+ * Settlement allowance added to the declared delegation TTL to form the refresh threshold. It
+ * matches the destination-credential skew routing already applies to a warm entry, so a credential
+ * served here cannot expire between admission and delivery.
+ */
+export const SETTLEMENT_SKEW_MS = 5_000;
+/** Total budget for one mint, matching the default Session operation budget. */
+export const MINT_TIMEOUT_MS = 30_000;
+/** Bounded backoff between anticipation attempts after a failed mint. */
+export const BACKOFF_MS = [1_000, 2_000, 4_000];
+/** Steady retry interval once the bounded backoff is exhausted. */
+export const RETRY_INTERVAL_MS = 4_000;

package/dist/session/credential/provider.d.ts

@@ -0,0 +1,56 @@
+import type { SessionAuth } from '../routing/index.js';
+/** One source credential and the exact instant it stops being accepted. */
+export interface SessionCredential {
+    readonly credential: string;
+    /** Absolute Unix time in milliseconds. */
+    readonly expiresAt: number;
+}
+/** Observable lifecycle of the single credential one provider owns. */
+export type SessionCredentialState = {
+    readonly status: 'empty';
+} | {
+    readonly status: 'valid';
+    readonly credential: SessionCredential;
+} | {
+    readonly status: 'refreshing';
+    readonly credential?: SessionCredential;
+} | {
+    readonly status: 'degraded';
+    readonly credential: SessionCredential;
+    readonly error: unknown;
+} | {
+    readonly status: 'expired';
+    readonly error: unknown;
+};
+export interface SessionCredentialProviderOptions {
+    /** Delegation TTL every served credential must still cover; also the SessionAuth TTL. */
+    readonly ttlSeconds: number;
+    /** Acquire one fresh credential; the supplied signal is owned by the provider. */
+    mint(signal: AbortSignal): Promise<SessionCredential>;
+    /** Caller-held credential admitted as the initial entry; it need only be unexpired. */
+    readonly initial?: SessionCredential;
+    readonly onChange?: (state: SessionCredentialState) => void;
+}
+/**
+ * Caller-owned source credential with a derived refresh threshold and shared minting.
+ *
+ * The provider is a SessionAuth, so a ClientSession consumes it directly. Anticipation is opt-in:
+ * an ephemeral process or a request-scoped worker never holds a pending timer it did not ask for.
+ */
+export interface SessionCredentialProvider extends SessionAuth {
+    state(): SessionCredentialState;
+    /** Serve a credential that still covers the delegation TTL; concurrent callers share one mint. */
+    acquire(signal?: AbortSignal): Promise<SessionCredential>;
+    /** Mint regardless of the current credential, joining a mint already in flight. */
+    refresh(signal?: AbortSignal): Promise<SessionCredential>;
+    /** Begin anticipating expiry: threshold timer, bounded backoff, and an expiry watchdog. */
+    start(): void;
+    /** Stop anticipating; a mint already in flight still settles. */
+    stop(): void;
+}
+/**
+ * Remaining lifetime a credential must exceed to carry a delegation of `ttlSeconds`: the TTL itself
+ * plus the settlement skew, so it cannot expire between admission and delivery.
+ */
+export declare function delegationCoverageMs(ttlSeconds: number): number;
+export declare function createSessionCredentialProvider(options: SessionCredentialProviderOptions): SessionCredentialProvider;