@astrale-os/kernel-client 0.6.0-beta.2 → 0.6.0-beta.20

package/dist/store/store.js

@@ -1,4 +1,5 @@
 import { ClientError } from '../errors/index.js';
+import { captureExpected } from '../graph/expectation.js';
 import { GraphMemory } from './memory.js';
 import { mutateStore } from './mutation.js';
 import { observeStore } from './observe.js';
@@ -105,7 +106,7 @@ export class GraphStore {
         const identity = this.identity(query, options);
         return {
             ...identity,
-            shape: this.memory.ensure(identity.key, identity.ast, identity.page),
+            shape: this.memory.ensure(identity.key, identity.ast, identity.page, identity.expected),
             options: options,
         };
     }
@@ -121,6 +122,7 @@ export class GraphStore {
             throw new TypeError('Store freshness option is invalid.');
         }
         const page = admitPage(options.page);
+        const expected = captureExpected(options.expected);
         if (options.timeoutMs !== undefined &&
             (!Number.isSafeInteger(options.timeoutMs) ||
                 options.timeoutMs < 1 ||
@@ -128,8 +130,8 @@ export class GraphStore {
             throw new TypeError('Store read timeoutMs must be a positive platform integer.');
         }
         const ast = admitQuery(query);
-        const key = queryKey(ast, page);
-        return { key, ast, page };
+        const key = queryKey(ast, page, expected);
+        return { key, ast, page, expected };
     }
     requireOpen() {
         if (this.closed)
@@ -142,4 +144,3 @@ function positive(input, label) {
     }
     return input;
 }
-//# sourceMappingURL=store.js.map

package/dist/store/store.typecheck.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=store.typecheck.d.ts.map

package/dist/store/store.typecheck.js

@@ -1,11 +1,11 @@
 import { Query } from '../graph/index.js';
 const options = { page: { size: 32 } };
-const nodeGraph = Query.from({ kind: 'node', paths: [path] }).select({ kind: 'graph' });
-const nodeProjection = Query.from({ kind: 'node', paths: [path] }).select({
+const nodeGraph = Query.from({ nodes: [path] }).select({ kind: 'graph' });
+const nodeProjection = Query.from({ nodes: [path] }).select({
     kind: 'nodes',
     projection: { kind: 'reference' },
 });
-const edgeSource = Query.from({ kind: 'edge', definitions: [edge] });
+const edgeSource = Query.from({ edges: [edge] });
 const edgeProjection = edgeSource.select({
     kind: 'edges',
     projection: { edge: 'reference', source: 'value', target: 'reference' },
@@ -38,4 +38,3 @@ store.observe(nodeGraph, () => undefined);
 // @ts-expect-error watch is reserved for a future remote-liveness protocol.
 store.watch(nodeGraph, () => undefined, options);
 void {};
-//# sourceMappingURL=store.typecheck.js.map

package/dist/transport/auto/decision.d.ts

@@ -20,4 +20,3 @@ export declare class AutoDecision {
     release(): void;
     close(): void;
 }
-//# sourceMappingURL=decision.d.ts.map

package/dist/transport/auto/decision.js

@@ -46,4 +46,3 @@ export class AutoDecision {
         this.pending = undefined;
     }
 }
-//# sourceMappingURL=decision.js.map

package/dist/transport/auto/fallback.d.ts

@@ -14,4 +14,3 @@ export declare class InvocationBudget {
 }
 export declare function mayFallback(error: unknown): error is TransportError;
 export declare function warningTarget(input: TransportRequest): TransportRequest['call']['target'];
-//# sourceMappingURL=fallback.d.ts.map

package/dist/transport/auto/fallback.js

@@ -1,4 +1,5 @@
 import { TransportError } from '../../errors/index.js';
+import { invocationFailure } from '../failure.js';
 import { positiveInteger } from '../index.js';
 const MAXIMUM_TIMEOUT_MS = 2_147_483_647;
 /** One invocation-owned total timeout budget shared by selection and fallback. */
@@ -33,10 +34,7 @@ export class InvocationBudget {
         let timer;
         let abort;
         const interrupted = new Promise((_resolve, reject) => {
-            timer = setTimeout(() => reject(new TransportError('Automatic transport decision exceeded its timeout.', {
-                phase: 'timeout',
-                delivery: 'not-sent',
-            })), remaining);
+            timer = setTimeout(() => reject(invocationFailure('Automatic transport decision exceeded its timeout.', 'timeout')), remaining);
             if (this.input?.signal) {
                 abort = () => reject(abortReason(this.input.signal));
                 this.input.signal.addEventListener('abort', abort, { once: true });
@@ -55,16 +53,17 @@ export class InvocationBudget {
     remaining() {
         const remaining = Math.min(MAXIMUM_TIMEOUT_MS, this.timeoutMs - (Date.now() - this.started));
         if (remaining < 1) {
-            throw new TransportError('Automatic transport invocation exceeded its timeout.', {
-                phase: 'timeout',
-                delivery: 'not-sent',
-            });
+            throw invocationFailure('Automatic transport invocation exceeded its timeout.', 'timeout');
         }
         return remaining;
     }
 }
 export function mayFallback(error) {
-    return error instanceof TransportError && error.phase !== 'closed' && error.phase !== 'timeout';
+    return (error instanceof TransportError &&
+        error.context.kind === 'invocation' &&
+        error.context.delivery === 'not-sent' &&
+        error.phase !== 'closed' &&
+        error.phase !== 'timeout');
 }
 export function warningTarget(input) {
     return input.call.target;
@@ -74,4 +73,3 @@ function abortReason(signal) {
         ? signal.reason
         : new Error(signal.reason === undefined ? 'request was cancelled' : String(signal.reason));
 }
-//# sourceMappingURL=fallback.js.map

package/dist/transport/auto/index.d.ts

@@ -1,3 +1,2 @@
 export { AutoTransport, type AutoTransportOptions } from './transport.js';
 export { formatClientWarning, type ClientWarning } from './warning.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/transport/auto/index.js

@@ -1,3 +1,2 @@
 export { AutoTransport } from './transport.js';
 export { formatClientWarning } from './warning.js';
-//# sourceMappingURL=index.js.map

package/dist/transport/auto/transport.d.ts

@@ -35,4 +35,3 @@ export declare class AutoTransport implements Transport {
     private tryWebsocket;
     private requireOpen;
 }
-//# sourceMappingURL=transport.d.ts.map

package/dist/transport/auto/transport.js

@@ -1,4 +1,5 @@
 import { TransportError } from '../../errors/index.js';
+import { invocationFailure } from '../failure.js';
 import { HttpTransport } from '../http/index.js';
 import { positiveInteger } from '../index.js';
 import { WebSocketTransport } from '../websocket/index.js';
@@ -104,7 +105,9 @@ export class AutoTransport {
                     this.decision.release();
                 throw error;
             }
-            if (error instanceof TransportError && error.delivery === 'unknown') {
+            if (error instanceof TransportError &&
+                error.context.kind === 'invocation' &&
+                error.context.delivery === 'unknown') {
                 this.decision.demote();
                 throw error;
             }
@@ -132,10 +135,6 @@ export class AutoTransport {
     requireOpen() {
         if (!this.closed)
             return;
-        throw new TransportError('AutoTransport is closed.', {
-            phase: 'closed',
-            delivery: 'not-sent',
-        });
+        throw invocationFailure('AutoTransport is closed.', 'closed');
     }
 }
-//# sourceMappingURL=transport.js.map

package/dist/transport/auto/warning.d.ts

@@ -11,4 +11,3 @@ export interface ClientWarning {
 }
 export declare function formatClientWarning(warning: ClientWarning): string;
 export declare function emitWarning(warning: ClientWarning, observer: ((warning: ClientWarning) => void) | undefined): void;
-//# sourceMappingURL=warning.d.ts.map

package/dist/transport/auto/warning.js

@@ -16,4 +16,3 @@ export function emitWarning(warning, observer) {
         // Warning observation cannot change invocation settlement.
     }
 }
-//# sourceMappingURL=warning.js.map

package/dist/transport/deadline.d.ts

@@ -9,4 +9,3 @@ export declare function controlledSignal(parent: AbortSignal | undefined, timeou
 export declare function positiveInteger(input: number, label: string): number;
 export declare function requireLive(control: ControlledSignal): void;
 export declare function asError(value: unknown): Error;
-//# sourceMappingURL=deadline.d.ts.map

package/dist/transport/deadline.js

@@ -37,4 +37,3 @@ export function requireLive(control) {
 export function asError(value) {
     return value instanceof Error ? value : new Error(String(value));
 }
-//# sourceMappingURL=deadline.js.map

package/dist/transport/failure.d.ts

@@ -0,0 +1,7 @@
+import { TransportError, type InvocationTransportErrorOptions } from '../errors/index.js';
+type InvocationFailureEvidence = Omit<InvocationTransportErrorOptions, 'delivery' | 'phase'> & {
+    readonly delivery?: InvocationTransportErrorOptions['delivery'];
+};
+/** Create invocation transport evidence with the common not-sent default. */
+export declare function invocationFailure(message: string, phase: InvocationTransportErrorOptions['phase'], evidence?: InvocationFailureEvidence): TransportError;
+export {};

package/dist/transport/failure.js

@@ -0,0 +1,9 @@
+import { TransportError } from '../errors/index.js';
+/** Create invocation transport evidence with the common not-sent default. */
+export function invocationFailure(message, phase, evidence = {}) {
+    return TransportError.invocation(message, {
+        ...evidence,
+        phase,
+        delivery: evidence.delivery ?? 'not-sent',
+    });
+}

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

@@ -0,0 +1,17 @@
+import type { ControlledSignal } from '../index.js';
+/** Single-consumer HTTP byte stream preserving invocation lifetime and backpressure. */
+export declare class HttpByteStream implements AsyncIterable<Uint8Array> {
+    private readonly maximumBytes;
+    private readonly control;
+    private readonly reader;
+    private claimed;
+    private terminal;
+    private bytes;
+    private interruption;
+    constructor(body: ReadableStream<Uint8Array>, maximumBytes: number, control: ControlledSignal);
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+    cancel(reason?: unknown): Promise<void>;
+    private next;
+    private interrupt;
+    private cancelReader;
+}

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

@@ -0,0 +1,86 @@
+import { ProtocolError } from '../../errors/index.js';
+import { asError } from '../index.js';
+/** Single-consumer HTTP byte stream preserving invocation lifetime and backpressure. */
+export class HttpByteStream {
+    maximumBytes;
+    control;
+    reader;
+    claimed = false;
+    terminal = false;
+    bytes = 0;
+    interruption;
+    constructor(body, maximumBytes, control) {
+        this.maximumBytes = maximumBytes;
+        this.control = control;
+        this.reader = body.getReader();
+        const abort = () => void this.interrupt(control.signal.reason);
+        if (control.signal.aborted)
+            abort();
+        else
+            control.signal.addEventListener('abort', abort, { once: true });
+    }
+    [Symbol.asyncIterator]() {
+        if (this.claimed)
+            throw new TypeError('streaming binary admits exactly one consumer.');
+        this.claimed = true;
+        return {
+            next: () => this.next(),
+            return: async () => {
+                await this.cancel('streaming binary consumer stopped');
+                return { done: true, value: undefined };
+            },
+            throw: async (error) => {
+                await this.cancel('streaming binary consumer failed');
+                throw error;
+            },
+        };
+    }
+    async cancel(reason = 'streaming binary cancelled') {
+        if (this.terminal)
+            return;
+        this.terminal = true;
+        this.control.cancel(reason);
+        await this.cancelReader(reason);
+        this.control.close();
+    }
+    async next() {
+        if (this.interruption !== undefined)
+            throw this.interruption;
+        if (this.terminal)
+            return { done: true, value: undefined };
+        try {
+            const next = await this.reader.read();
+            if (this.interruption !== undefined)
+                throw this.interruption;
+            if (next.done) {
+                this.terminal = true;
+                this.control.close();
+                return { done: true, value: undefined };
+            }
+            this.bytes += next.value.byteLength;
+            if (this.bytes > this.maximumBytes) {
+                throw new ProtocolError(`streaming binary exceeds maximumResponseBytes (${this.maximumBytes}).`);
+            }
+            return { done: false, value: new Uint8Array(next.value) };
+        }
+        catch (error) {
+            await this.cancel(error);
+            throw error;
+        }
+    }
+    async interrupt(reason) {
+        if (this.terminal || this.interruption !== undefined)
+            return;
+        this.interruption = asError(reason ?? new Error('streaming binary was cancelled.'));
+        await this.cancelReader(this.interruption);
+        this.control.close();
+    }
+    async cancelReader(reason) {
+        try {
+            await this.reader.cancel(reason);
+        }
+        catch {
+            // Cancellation follows an already chosen terminal outcome.
+        }
+    }
+}

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

@@ -1,2 +1 @@
 export { HttpTransport, type Fetch, type HttpTransportOptions } from './transport.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/transport/http/index.js

@@ -1,2 +1 @@
 export { HttpTransport } from './transport.js';
-//# sourceMappingURL=index.js.map

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

@@ -1,8 +1,8 @@
-import { codecs, invocation as protocol } from '@astrale-os/kernel-protocol';
+import * as codecs from '@astrale-os/kernel-protocol/codecs';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
 export declare function codecForResponse(contentType: string | null): Promise<codecs.Codec | undefined>;
 export declare function readBoundedBody(response: Response, maximumBytes: number, signal: AbortSignal): Promise<Uint8Array>;
 export declare function requireId(expected: protocol.RequestId, received: protocol.RequestId): void;
 export declare function decodeProtocol<T>(label: string, decode: () => T): T;
 export declare function normalizeMediaType(input: string | null): string | undefined;
 export declare function binaryHeaders(input: Headers, names: readonly string[]): Readonly<Record<string, string>>;
-//# sourceMappingURL=response.d.ts.map

package/dist/transport/http/response.js

@@ -1,4 +1,5 @@
-import { codecs, invocation as protocol } from '@astrale-os/kernel-protocol';
+import * as codecs from '@astrale-os/kernel-protocol/codecs';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
 import { ProtocolError, ResponseError } from '../../errors/index.js';
 import { asError } from '../index.js';
 export async function codecForResponse(contentType) {
@@ -76,4 +77,3 @@ export function binaryHeaders(input, names) {
     }
     return Object.freeze(output);
 }
-//# sourceMappingURL=response.js.map

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

@@ -1,18 +1,20 @@
 import type { Value } from '@astrale-os/kernel-dsl/value';
-import type { Stream } from '@astrale-os/kernel-ports/functions';
-import { invocation as protocol, type codecs } from '@astrale-os/kernel-protocol';
+import type * as codecs from '@astrale-os/kernel-protocol/codecs';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
+import type { Stream } from '../../client/index.js';
 import { type ControlledSignal } from '../index.js';
 export declare class HttpStream implements Stream {
     private readonly frames;
     private readonly codec;
-    private readonly id;
+    private readonly requestId;
     private readonly control;
+    invocation: protocol.InvocationId;
     private claimed;
     private terminal;
     private index;
     private interruption;
     private constructor();
-    static open(response: Response, codec: codecs.Codec, id: protocol.RequestId, maximumFrameBytes: number, control: ControlledSignal): Promise<HttpStream>;
+    static open(response: Response, codec: codecs.Codec, requestId: protocol.RequestId, maximumFrameBytes: number, control: ControlledSignal): Promise<HttpStream>;
     [Symbol.asyncIterator](): AsyncIterator<Value>;
     cancel(reason?: string): Promise<void>;
     private next;
@@ -22,4 +24,3 @@ export declare class HttpStream implements Stream {
     private stop;
     private abortFailure;
 }
-//# sourceMappingURL=stream.d.ts.map

package/dist/transport/http/stream.js

@@ -1,20 +1,22 @@
-import { invocation as protocol } from '@astrale-os/kernel-protocol';
+import * as protocol from '@astrale-os/kernel-protocol/invocation';
 import { ProtocolError, ResponseError, TransportError } from '../../errors/index.js';
+import { invocationFailure } from '../failure.js';
 import { asError } from '../index.js';
 import { decodeProtocol, requireId } from './response.js';
 export class HttpStream {
     frames;
     codec;
-    id;
+    requestId;
     control;
+    invocation;
     claimed = false;
     terminal = false;
     index = 0;
     interruption;
-    constructor(frames, codec, id, control) {
+    constructor(frames, codec, requestId, control) {
         this.frames = frames;
         this.codec = codec;
-        this.id = id;
+        this.requestId = requestId;
         this.control = control;
         const abort = () => void this.interrupt(this.abortFailure(control.signal.reason));
         if (control.signal.aborted)
@@ -22,15 +24,16 @@ export class HttpStream {
         else
             control.signal.addEventListener('abort', abort, { once: true });
     }
-    static async open(response, codec, id, maximumFrameBytes, control) {
+    static async open(response, codec, requestId, maximumFrameBytes, control) {
         if (response.body === null)
             throw new ProtocolError('stream has no body.');
-        const stream = new HttpStream(new LengthPrefixedFrames(response.body.getReader(), maximumFrameBytes), codec, id, control);
+        const stream = new HttpStream(new LengthPrefixedFrames(response.body.getReader(), maximumFrameBytes), codec, requestId, control);
         const first = await stream.readFrame();
         if (first === null || first.kind !== 'stream.start') {
             await stream.stop('invalid stream start');
             throw new ProtocolError('stream did not begin with stream.start.');
         }
+        stream.invocation = first.invocation;
         return stream;
     }
     [Symbol.asyncIterator]() {
@@ -71,7 +74,7 @@ export class HttpStream {
             }
             if (frame.kind === 'stream.error') {
                 await this.finish();
-                throw new ResponseError(frame.error.code, frame.error.message, frame.error.data);
+                throw new ResponseError(frame.error.code, frame.error.message, this.invocation, frame.error.data);
             }
             if (frame.kind !== 'stream.end') {
                 throw new ProtocolError(`Unexpected ${frame.kind} frame inside stream.`);
@@ -83,7 +86,7 @@ export class HttpStream {
             return { done: true, value: undefined };
         }
         catch (error) {
-            const failure = this.interruption ?? error;
+            const failure = this.interruption ?? retainInvocationId(error, this.invocation);
             await this.stop(failure);
             throw failure;
         }
@@ -95,7 +98,7 @@ export class HttpStream {
         if (payload === null)
             return null;
         const frame = decodeProtocol('stream frame', () => protocol.decodeStreamFrame(this.codec.decode(payload)));
-        requireId(this.id, frame.id);
+        requireId(this.requestId, frame.requestId);
         return frame;
     }
     async finish() {
@@ -122,15 +125,30 @@ export class HttpStream {
     }
     abortFailure(reason) {
         if (this.control.timedOut) {
-            return new TransportError('stream exceeded its invocation timeout.', {
+            return invocationFailure('stream exceeded its invocation timeout.', 'timeout', {
                 cause: asError(reason),
-                phase: 'timeout',
                 delivery: 'unknown',
+                invocation: this.invocation,
             });
         }
         return asError(reason ?? new Error('stream was cancelled.'));
     }
 }
+function retainInvocationId(input, invocation) {
+    if (input instanceof ProtocolError && input.invocation === undefined) {
+        return new ProtocolError(input.message, { cause: input, invocation });
+    }
+    if (input instanceof TransportError &&
+        input.context.kind === 'invocation' &&
+        input.context.invocation === undefined) {
+        return invocationFailure(input.message, input.phase, {
+            cause: input,
+            delivery: input.context.delivery,
+            invocation,
+        });
+    }
+    return input;
+}
 class LengthPrefixedFrames {
     reader;
     maximumFrameBytes;
@@ -194,4 +212,3 @@ class LengthPrefixedFrames {
         return output;
     }
 }
-//# sourceMappingURL=stream.js.map

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

@@ -30,4 +30,3 @@ export declare class HttpTransport implements Transport {
     private nextRequestId;
     private requestCodec;
 }
-//# sourceMappingURL=transport.d.ts.map