@astrale-os/kernel-client 0.6.0-beta.3 → 0.6.0-beta.30

package/dist/store/mutation.d.ts

@@ -3,4 +3,3 @@ import type { GraphApi, MutationAuthor } from '../graph/index.js';
 import type { GraphMemory } from './memory.js';
 import type { StoreMutationOptions } from './store.js';
 export declare function mutateStore(graph: GraphApi, memory: GraphMemory, input: MutationAuthor | MutationASTValue | MutationInput, options?: StoreMutationOptions): Promise<MutationResult>;
-//# sourceMappingURL=mutation.d.ts.map

package/dist/store/mutation.js

@@ -32,4 +32,3 @@ export async function mutateStore(graph, memory, input, options = {}) {
         throw error;
     }
 }
-//# sourceMappingURL=mutation.js.map

package/dist/store/observe.d.ts

@@ -1,4 +1,3 @@
 import type { StoreQuery, StoreReadOptions, StoreSnapshot } from './store.js';
 import type { GraphStore } from './store.js';
 export declare function observeStore<Query extends StoreQuery>(store: GraphStore, query: Query, listener: (snapshot: StoreSnapshot<Query>) => void, options: StoreReadOptions): () => void;
-//# sourceMappingURL=observe.d.ts.map

package/dist/store/observe.js

@@ -15,4 +15,3 @@ export function observeStore(store, query, listener, options) {
     void store.read(admitted, options).catch(() => undefined);
     return unsubscribe;
 }
-//# sourceMappingURL=observe.js.map

package/dist/store/optimistic.d.ts

@@ -10,4 +10,3 @@ export declare class OptimisticOverlay {
     node(id: NodeId, entities: EntityIndex): Node | undefined;
     clear(): void;
 }
-//# sourceMappingURL=optimistic.d.ts.map

package/dist/store/optimistic.js

@@ -41,4 +41,3 @@ function nodeId(input) {
         ? path.ast.anchor.id
         : undefined;
 }
-//# sourceMappingURL=optimistic.js.map

package/dist/store/query-key.d.ts

@@ -1,6 +1,6 @@
 import type { QueryAST as QueryASTValue } from '@astrale-os/kernel-core/graph/query';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
 import type { QueryPageRequest } from '../graph/index.js';
 export declare function admitQuery(input: QueryASTValue): QueryASTValue;
 export declare function admitPage(input: QueryPageRequest): QueryPageRequest;
-export declare function queryKey(ast: QueryASTValue, page: QueryPageRequest): string;
-//# sourceMappingURL=query-key.d.ts.map
+export declare function queryKey(ast: QueryASTValue, page: QueryPageRequest, expected: readonly DomainDependency[] | undefined): string;

package/dist/store/query-key.js

@@ -17,7 +17,11 @@ export function admitPage(input) {
         ...(input.after === undefined ? {} : { after: input.after }),
     });
 }
-export function queryKey(ast, page) {
-    return JSON.stringify([QueryAST.fingerprint(ast), page.size, page.after ?? null]);
+export function queryKey(ast, page, expected) {
+    return JSON.stringify([
+        QueryAST.fingerprint(ast),
+        page.size,
+        page.after ?? null,
+        expected ?? null,
+    ]);
 }
-//# sourceMappingURL=query-key.js.map

package/dist/store/shape.d.ts

@@ -1,5 +1,6 @@
 import type { NodeId } from '@astrale-os/kernel-core/graph/node';
 import type { QueryAST } from '@astrale-os/kernel-core/graph/query';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
 import type { QueryPageRequest } from '../graph/index.js';
 import type { FactReferences } from './entity-index.js';
 import type { StoreQueryResponse, StoreSnapshot } from './store.js';
@@ -8,6 +9,7 @@ export declare class QueryShape {
     readonly key: string;
     readonly ast: QueryAST;
     readonly page: QueryPageRequest;
+    readonly expected: readonly DomainDependency[] | undefined;
     readonly listeners: Set<() => void>;
     state: ShapeState;
     confirmed?: StoreQueryResponse;
@@ -18,9 +20,8 @@ export declare class QueryShape {
     accessedAt: number;
     refreshedAt?: number;
     snapshot: StoreSnapshot;
-    constructor(key: string, ast: QueryAST, page: QueryPageRequest, now: number);
+    constructor(key: string, ast: QueryAST, page: QueryPageRequest, expected: readonly DomainDependency[] | undefined, now: number);
     get observed(): boolean;
     referencesAny(nodes: ReadonlySet<NodeId>, edges: ReadonlySet<string>): boolean;
 }
 export declare const COLD_SNAPSHOT: StoreSnapshot;
-//# sourceMappingURL=shape.d.ts.map

package/dist/store/shape.js

@@ -2,6 +2,7 @@ export class QueryShape {
     key;
     ast;
     page;
+    expected;
     listeners = new Set();
     state = 'cold';
     confirmed;
@@ -12,10 +13,11 @@ export class QueryShape {
     accessedAt;
     refreshedAt;
     snapshot = COLD_SNAPSHOT;
-    constructor(key, ast, page, now) {
+    constructor(key, ast, page, expected, now) {
         this.key = key;
         this.ast = ast;
         this.page = page;
+        this.expected = expected;
         this.accessedAt = now;
     }
     get observed() {
@@ -27,4 +29,3 @@ export class QueryShape {
     }
 }
 export const COLD_SNAPSHOT = Object.freeze({ state: 'cold' });
-//# sourceMappingURL=shape.js.map

package/dist/store/store.d.ts

@@ -1,14 +1,13 @@
 import type { MutationAST, MutationInput, MutationResult } from '@astrale-os/kernel-core/graph/mutate';
 import type { QueryAST, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
 import type { QueryResponse } from '../graph/index.js';
-import type { GraphApi, GraphQueryOptions, MutationAuthor } from '../graph/index.js';
-import type { RequestOptions } from '../transport/index.js';
+import type { GraphApi, GraphMutationOptions, GraphQueryOptions, MutationAuthor } from '../graph/index.js';
 export type StoreQuery = QueryAST;
 export type StoreQueryResponse<Query extends StoreQuery = StoreQuery> = QueryResponse<QueryResultFor<Query>>;
 export interface StoreReadOptions extends GraphQueryOptions {
     readonly freshness?: 'cached' | 'refresh';
 }
-export interface StoreMutationOptions extends RequestOptions {
+export interface StoreMutationOptions extends GraphMutationOptions {
     readonly optimistic?: boolean;
 }
 export type StoreSnapshot<Query extends StoreQuery = StoreQuery> = {
@@ -66,4 +65,3 @@ export declare class GraphStore {
     private identity;
     private requireOpen;
 }
-//# sourceMappingURL=store.d.ts.map

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,5 +1,6 @@
 import type { Value } from '@astrale-os/kernel-dsl/value';
-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 {
@@ -23,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,5 +1,6 @@
-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 {
@@ -124,9 +125,8 @@ 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,
             });
@@ -138,11 +138,12 @@ function retainInvocationId(input, invocation) {
     if (input instanceof ProtocolError && input.invocation === undefined) {
         return new ProtocolError(input.message, { cause: input, invocation });
     }
-    if (input instanceof TransportError && input.invocation === undefined) {
-        return new TransportError(input.message, {
+    if (input instanceof TransportError &&
+        input.context.kind === 'invocation' &&
+        input.context.invocation === undefined) {
+        return invocationFailure(input.message, input.phase, {
             cause: input,
-            phase: input.phase,
-            delivery: input.delivery,
+            delivery: input.context.delivery,
             invocation,
         });
     }
@@ -211,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