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

package/dist/graph/domain/project.js

@@ -0,0 +1,124 @@
+import { MethodKey, PropertyKey } from '@astrale-os/kernel-dsl/v1/addressing';
+import { retainProjectedProvenance } from './provenance.js';
+export function projectNode(selected, node, provenance, call) {
+    const invoke = async (receiver, method, input) => {
+        if (receiver.class !== method.owner.key) {
+            throw new TypeError(`Method ${method.key} requires an exact ${method.owner.key} receiver.`);
+        }
+        return call(receiver, method, input);
+    };
+    const property = propertyAccessor(selected, node.props);
+    const method = methodAccessor(selected, node, invoke);
+    const value = {
+        id: node.id,
+        class: node.class,
+        props: node.props,
+        property,
+        method,
+    };
+    installPropertyShortcuts(value, selected, node.props, NODE_RESERVED);
+    installMethodShortcuts(value, selected, node, invoke, NODE_RESERVED);
+    const projected = Object.freeze(value);
+    retainProjectedProvenance(projected, provenance);
+    return projected;
+}
+export function projectEdge(selected, edge, provenance) {
+    const value = {
+        source: edge.source,
+        target: edge.target,
+        class: edge.class,
+        ...(edge.slug === undefined ? {} : { slug: edge.slug }),
+        props: edge.props,
+        property: propertyAccessor(selected, edge.props),
+    };
+    installPropertyShortcuts(value, selected, edge.props, EDGE_RESERVED);
+    const projected = Object.freeze(value);
+    retainProjectedProvenance(projected, provenance);
+    return projected;
+}
+const NODE_RESERVED = new Set(['id', 'class', 'props', 'property', 'method']);
+const EDGE_RESERVED = new Set(['source', 'target', 'class', 'slug', 'props', 'property']);
+function propertyAccessor(selected, props) {
+    return (input) => {
+        const property = resolveProperty(selected, input);
+        return props[property.key];
+    };
+}
+function methodAccessor(selected, node, call) {
+    return (input) => {
+        const method = resolveMethod(selected, input);
+        if (!method.executable) {
+            throw new TypeError(`Abstract Method ${method.key} cannot be invoked.`);
+        }
+        return (value) => call(node, method, value);
+    };
+}
+function resolveProperty(selected, input) {
+    if (typeof input !== 'string') {
+        const member = selected.properties.get(input.key);
+        if (member !== input)
+            throw new TypeError('Property does not belong to the selected Class.');
+        return member;
+    }
+    if (PropertyKey.is(input)) {
+        const member = selected.properties.get(input);
+        if (member === undefined)
+            throw new TypeError(`Property ${input} is not effective.`);
+        return member;
+    }
+    const member = named(selected.properties, input);
+    if (member === undefined || typeof member !== 'object') {
+        throw new TypeError(`Property name ${JSON.stringify(input)} is absent or ambiguous.`);
+    }
+    return member;
+}
+function resolveMethod(selected, input) {
+    if (typeof input !== 'string') {
+        const member = selected.methods.get(input.key);
+        if (member !== input)
+            throw new TypeError('Method does not belong to the selected Class.');
+        return member;
+    }
+    if (MethodKey.is(input)) {
+        const member = selected.methods.get(input);
+        if (member === undefined)
+            throw new TypeError(`Method ${input} is not effective.`);
+        return member;
+    }
+    const member = named(selected.methods, input);
+    if (member === undefined || typeof member !== 'object') {
+        throw new TypeError(`Method name ${JSON.stringify(input)} is absent or ambiguous.`);
+    }
+    return member;
+}
+function installPropertyShortcuts(target, selected, props, reserved) {
+    for (const property of selected.properties) {
+        if (reserved.has(property.name) || hasOwn(target, property.name))
+            continue;
+        if (named(selected.properties, property.name) !== property)
+            continue;
+        if (selected.kind === 'node' && named(selected.methods, property.name) !== undefined)
+            continue;
+        install(target, property.name, props[property.key]);
+    }
+}
+function installMethodShortcuts(target, selected, node, call, reserved) {
+    for (const member of selected.methods) {
+        if (!member.executable || reserved.has(member.name) || hasOwn(target, member.name))
+            continue;
+        if (named(selected.methods, member.name) !== member)
+            continue;
+        if (named(selected.properties, member.name) !== undefined)
+            continue;
+        install(target, member.name, (input) => call(node, member, input));
+    }
+}
+function named(collection, name) {
+    return hasOwn(collection, name) ? Reflect.get(collection, name) : undefined;
+}
+function hasOwn(value, name) {
+    return Object.prototype.hasOwnProperty.call(value, name);
+}
+function install(target, name, value) {
+    Object.defineProperty(target, name, { enumerable: true, value });
+}

package/dist/graph/domain/provenance.d.ts

@@ -0,0 +1,6 @@
+import type { Domain } from '@astrale-os/kernel-dsl/v1/domain';
+import type { QueryProvenance } from '../provenance.js';
+export declare function retainProjectedProvenance(value: object, provenance: QueryProvenance): void;
+export declare function provenanceOfProjectedValue(value: object): QueryProvenance | undefined;
+export declare function sameClosure(left: Domain['closure'], right: Domain['closure']): boolean;
+export type { QueryProvenance };

package/dist/graph/domain/provenance.js

@@ -0,0 +1,11 @@
+const projectedValues = new WeakMap();
+export function retainProjectedProvenance(value, provenance) {
+    projectedValues.set(value, provenance);
+}
+export function provenanceOfProjectedValue(value) {
+    return projectedValues.get(value);
+}
+export function sameClosure(left, right) {
+    return (left.length === right.length &&
+        left.every((identity, index) => identity.origin === right[index]?.origin && identity.revision === right[index]?.revision));
+}

package/dist/graph/errors.d.ts

@@ -1,9 +1,8 @@
-import type { NodePath, PathLike } from '@astrale-os/kernel-core/path';
+import type { NodePath, NodeTarget } from '@astrale-os/kernel-core/path';
 import { ClientError } from '../errors/index.js';
 /** Required point read whose absence and authorization masking are intentionally indistinguishable. */
 export declare class NodeUnavailableError extends ClientError {
     readonly code: 'NODE_UNAVAILABLE';
     readonly path: NodePath;
-    constructor(path: PathLike);
+    constructor(path: NodeTarget);
 }
-//# sourceMappingURL=errors.d.ts.map

package/dist/graph/errors.js

@@ -5,10 +5,9 @@ export class NodeUnavailableError extends ClientError {
     code = 'NODE_UNAVAILABLE';
     path;
     constructor(path) {
-        const admitted = Path.from(path).raw;
+        const admitted = Path.target(path).raw;
         super(`Node ${JSON.stringify(admitted)} is unavailable.`);
         this.name = 'NodeUnavailableError';
         this.path = admitted;
     }
 }
-//# sourceMappingURL=errors.js.map

package/dist/graph/expectation.d.ts

@@ -0,0 +1,3 @@
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
+/** Detach one caller-owned expected closure before crossing the Client boundary. */
+export declare function captureExpected(input: readonly DomainDependency[] | undefined): readonly DomainDependency[] | undefined;

package/dist/graph/expectation.js

@@ -0,0 +1,6 @@
+/** Detach one caller-owned expected closure before crossing the Client boundary. */
+export function captureExpected(input) {
+    if (input === undefined)
+        return undefined;
+    return Object.freeze(input.map(({ origin, revision }) => Object.freeze({ origin, revision })));
+}

package/dist/graph/graph.d.ts

@@ -1,25 +1,29 @@
 import type { GraphSpec } from '@astrale-os/kernel-core/graph/graph';
 import type { MutationAST as MutationASTValue, MutationBuilder, MutationInput, MutationResult as MutationResultValue } from '@astrale-os/kernel-core/graph/mutate';
 import type { Node } from '@astrale-os/kernel-core/graph/node';
-import type { QueryAST as QueryASTValue, QueryDefinitionRef, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
-import type { PathLike } from '@astrale-os/kernel-core/path';
+import type { QueryAST as QueryASTValue, QueryEdgeClassInput, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
+import type { NodeTarget } from '@astrale-os/kernel-core/path';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
 import type { Call, Input } from '../client/index.js';
 import type { RequestOptions } from '../transport/index.js';
 import type { QueryPageRequest, QueryResponse } from './page-contract.js';
 import type { NeighborsOptions, NodePage } from './page/index.js';
 export type GraphCall = (call: Call, options?: RequestOptions) => Promise<Input>;
 export interface GraphQueryOptions extends RequestOptions {
+    readonly expected?: readonly DomainDependency[];
     readonly page: QueryPageRequest;
 }
+export interface GraphMutationOptions extends RequestOptions {
+    readonly expected?: readonly DomainDependency[];
+}
 export type MutationAuthor = (mutation: MutationBuilder) => undefined;
 export interface GraphApi {
     query<Query extends QueryASTValue>(ast: Query, options: GraphQueryOptions): Promise<QueryResponse<QueryResultFor<Query>>>;
-    mutate(author: MutationAuthor, options?: RequestOptions): Promise<MutationResultValue>;
-    mutate(ast: MutationASTValue | MutationInput | GraphSpec, options?: RequestOptions): Promise<MutationResultValue>;
-    get(target: PathLike, options?: RequestOptions): Promise<Node | null>;
-    getOrThrow(target: PathLike, options?: RequestOptions): Promise<Node>;
-    neighbors(source: PathLike, via: QueryDefinitionRef | readonly [QueryDefinitionRef, ...QueryDefinitionRef[]], options: NeighborsOptions): Promise<NodePage>;
+    mutate(author: MutationAuthor, options?: GraphMutationOptions): Promise<MutationResultValue>;
+    mutate(ast: MutationASTValue | MutationInput | GraphSpec, options?: GraphMutationOptions): Promise<MutationResultValue>;
+    get(target: NodeTarget, options?: RequestOptions): Promise<Node | null>;
+    getOrThrow(target: NodeTarget, options?: RequestOptions): Promise<Node>;
+    neighbors(source: NodeTarget, via: QueryEdgeClassInput | readonly [QueryEdgeClassInput, ...QueryEdgeClassInput[]], options: NeighborsOptions): Promise<NodePage>;
 }
 /** Bind Core's canonical graph documents to one caller-scoped value-call capability. */
 export declare function createGraph(call: GraphCall): GraphApi;
-//# sourceMappingURL=graph.d.ts.map

package/dist/graph/graph.js

@@ -16,4 +16,3 @@ export function createGraph(call) {
         neighbors: (source, via, options) => readNeighbors(query, source, via, options),
     });
 }
-//# sourceMappingURL=graph.js.map

package/dist/graph/index.d.ts

@@ -1,8 +1,8 @@
-export { createGraph, type GraphApi, type GraphCall, type GraphQueryOptions, type MutationAuthor, } from './graph.js';
+export { createGraph, type GraphApi, type GraphCall, type GraphMutationOptions, type GraphQueryOptions, type MutationAuthor, } from './graph.js';
 export type { QueryPageRequest, QueryResponse } from './page-contract.js';
+export { type BoundEdge, type BoundEdgePage, type BoundGraphValue, type BoundNode, type BoundNodeFor, type BoundNodePage, type BoundQueryPage, type DomainBinding, type DomainQueryOptions, } from './domain/index.js';
 export { NodeUnavailableError } from './errors.js';
 export type { NeighborsOptions, NodePage } from './page/index.js';
 export { LocalBinding, type GraphSpec } from '@astrale-os/kernel-core/graph/graph';
 export { MutationAST, MutationResult, type MutationBuilder, type MutationInput, } from '@astrale-os/kernel-core/graph/mutate';
 export { Query, QueryAST, QueryResult } from '@astrale-os/kernel-core/graph/query';
-//# sourceMappingURL=index.d.ts.map

package/dist/graph/index.js

@@ -1,6 +1,6 @@
 export { createGraph, } from './graph.js';
+export {} from './domain/index.js';
 export { NodeUnavailableError } from './errors.js';
 export { LocalBinding } from '@astrale-os/kernel-core/graph/graph';
 export { MutationAST, MutationResult, } from '@astrale-os/kernel-core/graph/mutate';
 export { Query, QueryAST, QueryResult } from '@astrale-os/kernel-core/graph/query';
-//# sourceMappingURL=index.js.map

package/dist/graph/mutation.d.ts

@@ -1,6 +1,4 @@
 import type { GraphSpec } from '@astrale-os/kernel-core/graph/graph';
 import type { MutationAST as MutationASTValue, MutationInput, MutationResult as MutationResultValue } from '@astrale-os/kernel-core/graph/mutate';
-import type { RequestOptions } from '../transport/index.js';
-import type { GraphCall, MutationAuthor } from './graph.js';
-export declare function mutateGraph(call: GraphCall, input: MutationAuthor | MutationASTValue | MutationInput | GraphSpec, options?: RequestOptions): Promise<MutationResultValue>;
-//# sourceMappingURL=mutation.d.ts.map
+import type { GraphCall, GraphMutationOptions, MutationAuthor } from './graph.js';
+export declare function mutateGraph(call: GraphCall, input: MutationAuthor | MutationASTValue | MutationInput | GraphSpec, options?: GraphMutationOptions): Promise<MutationResultValue>;

package/dist/graph/mutation.js

@@ -2,10 +2,19 @@ import { MutationAST, MutationResult } from '@astrale-os/kernel-core/graph/mutat
 import { Path } from '@astrale-os/kernel-core/path';
 import { mutate } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
 import { call as invocation } from '../client/index.js';
+import { captureExpected } from './expectation.js';
 const KERNEL_MUTATE_PATH = Path.project(mutate).raw;
 export async function mutateGraph(call, input, options) {
     const ast = typeof input === 'function' ? MutationAST.build(input) : admitMutation(input);
-    const output = await call(invocation(KERNEL_MUTATE_PATH, ast), options);
+    const expected = options?.expected;
+    const request = options === undefined
+        ? undefined
+        : (({ expected: _expected, ...rest }) => rest)(options);
+    const capturedExpected = captureExpected(expected);
+    const output = await call(invocation(KERNEL_MUTATE_PATH, Object.freeze({
+        ast,
+        ...(capturedExpected === undefined ? {} : { expected: capturedExpected }),
+    })), request);
     return MutationResult.decode(output);
 }
 function admitMutation(input) {
@@ -15,4 +24,3 @@ function admitMutation(input) {
             ? MutationAST.create(input)
             : MutationAST.fromGraph(input);
 }
-//# sourceMappingURL=mutation.js.map

package/dist/graph/page/index.d.ts

@@ -1,3 +1,2 @@
 export { type NeighborsOptions, type NeighborSource, type NeighborVia, readNeighbors, } from './neighbors.js';
 export type { NodePage, PageQuery, PageQueryOptions } from './page.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/graph/page/index.js

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

package/dist/graph/page/neighbors.d.ts

@@ -1,10 +1,9 @@
-import type { QueryDefinitionRef, QueryDirection } from '@astrale-os/kernel-core/graph/query';
-import type { PathLike } from '@astrale-os/kernel-core/path';
+import type { QueryDirection, QueryEdgeClassInput } from '@astrale-os/kernel-core/graph/query';
+import type { NodeTarget } from '@astrale-os/kernel-core/path';
 import type { NodePage, PageQuery, PageQueryOptions } from './page.js';
 export interface NeighborsOptions extends PageQueryOptions {
     readonly direction: QueryDirection;
 }
-export type NeighborSource = PathLike;
-export type NeighborVia = QueryDefinitionRef | readonly [QueryDefinitionRef, ...QueryDefinitionRef[]];
+export type NeighborSource = NodeTarget;
+export type NeighborVia = QueryEdgeClassInput | readonly [QueryEdgeClassInput, ...QueryEdgeClassInput[]];
 export declare function readNeighbors(query: PageQuery, source: NeighborSource, via: NeighborVia, options: NeighborsOptions): Promise<NodePage>;
-//# sourceMappingURL=neighbors.d.ts.map

package/dist/graph/page/neighbors.js

@@ -1,13 +1,14 @@
 import { Query } from '@astrale-os/kernel-core/graph/query';
+import { queryNodePath } from '../query.js';
 import { createNodePage } from './page.js';
 export async function readNeighbors(query, source, via, options) {
     if (options === null || typeof options !== 'object') {
         throw new TypeError('Neighbor read options are invalid.');
     }
-    const definitions = Array.isArray(via) ? via : [via];
-    const [definition, ...additionalDefinitions] = definitions;
-    if (definition === undefined)
-        throw new TypeError('Neighbor read requires at least one Definition.');
+    const classes = Array.isArray(via) ? via : [via];
+    const [classInput, ...additionalClasses] = classes;
+    if (classInput === undefined)
+        throw new TypeError('Neighbor read requires at least one Class.');
     const direction = options.direction === 'outgoing'
         ? options.direction
         : options.direction === 'incoming'
@@ -15,8 +16,8 @@ export async function readNeighbors(query, source, via, options) {
             : options.direction === 'incident'
                 ? options.direction
                 : invalidDirection(options.direction);
-    const ast = Query.from({ kind: 'node', paths: [source] })
-        .expand({ via: [definition, ...additionalDefinitions], direction })
+    const ast = Query.from({ nodes: [queryNodePath(source)] })
+        .expand({ via: [classInput, ...additionalClasses], direction })
         .select({ kind: 'graph' });
     const { direction: _, page, ...request } = options;
     const { idempotencyKey: ___, ...basis } = request;
@@ -32,4 +33,3 @@ export async function readNeighbors(query, source, via, options) {
 function invalidDirection(input) {
     throw new TypeError(`Unsupported neighbor direction ${JSON.stringify(input)}.`);
 }
-//# sourceMappingURL=neighbors.js.map

package/dist/graph/page/page.d.ts

@@ -1,6 +1,7 @@
 import type { GraphData } from '@astrale-os/kernel-core/graph/graph';
 import type { Node, NodeCollection } from '@astrale-os/kernel-core/graph/node';
 import type { NodeBinding, QueryAST, QueryGraphSelect, QueryNodeGraphResult, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
 import type { RequestOptions } from '../../transport/index.js';
 import type { QueryPageRequest, QueryResponse } from '../page-contract.js';
 export interface NodePage {
@@ -23,12 +24,14 @@ export interface NodePage {
         readonly cursor: string | null;
     }>;
 }
-type PageBasis = Pick<RequestOptions, 'signal' | 'timeoutMs'>;
+type PageBasis = Pick<RequestOptions, 'signal' | 'timeoutMs'> & {
+    readonly expected?: readonly DomainDependency[];
+};
 export interface PageQueryOptions extends RequestOptions {
+    readonly expected?: readonly DomainDependency[];
     readonly page: QueryPageRequest;
 }
 export type PageQuery = <Query extends QueryAST>(ast: Query, options: PageQueryOptions) => Promise<QueryResponse<QueryResultFor<Query>>>;
 type NodeGraphQueryAST = QueryAST<QueryGraphSelect<NodeBinding>>;
 export declare function createNodePage(query: PageQuery, ast: NodeGraphQueryAST, response: QueryResponse<QueryNodeGraphResult>, basis: PageBasis, size: number): NodePage;
 export {};
-//# sourceMappingURL=page.d.ts.map

package/dist/graph/page/page.js

@@ -53,4 +53,3 @@ function requireMaximumPages(value) {
         throw new TypeError('NodePage maximumPages must be a positive safe integer.');
     }
 }
-//# sourceMappingURL=page.js.map

package/dist/graph/page-contract.d.ts

@@ -4,11 +4,10 @@ export interface QueryPageRequest {
     readonly size: number;
     readonly after?: string;
 }
-/** Admitted graph result and its optional opaque continuation. */
+/** Decoded graph result and its optional opaque continuation. */
 export interface QueryResponse<Result extends QueryResult = QueryResult> {
     readonly result: Result;
     readonly page: {
         readonly next?: string;
     };
 }
-//# sourceMappingURL=page-contract.d.ts.map

package/dist/graph/page-contract.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=page-contract.js.map

package/dist/graph/provenance.d.ts

@@ -0,0 +1,14 @@
+import type { Edge } from '@astrale-os/kernel-core/graph/edge';
+import type { Node } from '@astrale-os/kernel-core/graph/node';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
+import type { QueryResponse } from './page-contract.js';
+export interface QueryProvenance {
+    readonly closure: readonly DomainDependency[];
+    readonly page: object;
+}
+/** Retain authenticated query provenance without adding serialized response metadata. */
+export declare function retainQueryProvenance(response: QueryResponse, closure: readonly DomainDependency[]): QueryResponse;
+/** Reattach the exact authenticated closure when Store materialization replaces response objects. */
+export declare function retainDerivedQueryProvenance(source: QueryResponse, derived: QueryResponse): QueryResponse;
+export declare function provenanceOfGraphValue(value: Node | Edge): QueryProvenance | undefined;
+export declare function provenanceOfResponse(value: QueryResponse): QueryProvenance | undefined;

package/dist/graph/provenance.js

@@ -0,0 +1,42 @@
+const graphValues = new WeakMap();
+const responses = new WeakMap();
+/** Retain authenticated query provenance without adding serialized response metadata. */
+export function retainQueryProvenance(response, closure) {
+    const provenance = Object.freeze({ closure, page: Object.freeze({}) });
+    responses.set(response, provenance);
+    const { result } = response;
+    if (result.kind === 'graph') {
+        for (const node of result.graph.nodes)
+            graphValues.set(node, provenance);
+        for (const edge of result.graph.edges)
+            graphValues.set(edge, provenance);
+    }
+    else if (result.kind === 'nodes') {
+        for (const item of result.nodes) {
+            if (item.kind === 'value')
+                graphValues.set(item.value, provenance);
+        }
+    }
+    else {
+        for (const item of result.edges) {
+            if (item.edge.kind === 'value')
+                graphValues.set(item.edge.value, provenance);
+            if (item.source.kind === 'value')
+                graphValues.set(item.source.value, provenance);
+            if (item.target.kind === 'value')
+                graphValues.set(item.target.value, provenance);
+        }
+    }
+    return response;
+}
+/** Reattach the exact authenticated closure when Store materialization replaces response objects. */
+export function retainDerivedQueryProvenance(source, derived) {
+    const provenance = responses.get(source);
+    return provenance === undefined ? derived : retainQueryProvenance(derived, provenance.closure);
+}
+export function provenanceOfGraphValue(value) {
+    return graphValues.get(value);
+}
+export function provenanceOfResponse(value) {
+    return responses.get(value);
+}

package/dist/graph/query.d.ts

@@ -1,5 +1,7 @@
 import type { QueryAST as QueryASTValue, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
+import { Path, type NodeTarget } from '@astrale-os/kernel-core/path';
 import type { GraphCall, GraphQueryOptions } from './graph.js';
 import type { QueryResponse } from './page-contract.js';
+/** Point/neighbor reads are exact targets, unlike Query's overloaded Class sources. */
+export declare function queryNodePath(target: NodeTarget): Path;
 export declare function queryGraph<Query extends QueryASTValue>(call: GraphCall, input: Query, options: GraphQueryOptions): Promise<QueryResponse<QueryResultFor<Query>>>;
-//# sourceMappingURL=query.d.ts.map

package/dist/graph/query.js

@@ -1,14 +1,36 @@
-import { QueryAST, QueryResult } from '@astrale-os/kernel-core/graph/query';
-import { Path } from '@astrale-os/kernel-core/path';
+import { QueryAST, QueryASTDecodeError, QueryResult } from '@astrale-os/kernel-core/graph/query';
+import { Path, PathError } from '@astrale-os/kernel-core/path';
 import { query } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
 import { call as invocation } from '../client/index.js';
+import { captureExpected } from './expectation.js';
+import { retainQueryProvenance } from './provenance.js';
 const KERNEL_QUERY_PATH = Path.project(query).raw;
+/** Point/neighbor reads are exact targets, unlike Query's overloaded Class sources. */
+export function queryNodePath(target) {
+    try {
+        return Path.target(target);
+    }
+    catch (cause) {
+        // Preserve the graph-read Query error contract; do not relabel unexpected defects.
+        if (!(cause instanceof PathError))
+            throw cause;
+        throw new QueryASTDecodeError('/source/nodes/0', 'Invalid Node target', { cause });
+    }
+}
 export async function queryGraph(call, input, options) {
     const ast = QueryAST.decode(input);
-    const { page, ...request } = options;
+    const { expected, page, ...request } = options;
     const admittedPage = admitPage(page);
-    const output = await call(invocation(KERNEL_QUERY_PATH, Object.freeze({ ast, page: admittedPage })), request);
-    return decodeResponse(output);
+    const capturedExpected = captureExpected(expected);
+    const output = await call(invocation(KERNEL_QUERY_PATH, Object.freeze({
+        ast,
+        ...(capturedExpected === undefined ? {} : { expected: capturedExpected }),
+        page: admittedPage,
+    })), request);
+    const response = decodeResponse(output);
+    return capturedExpected === undefined
+        ? response
+        : retainQueryProvenance(response, capturedExpected);
 }
 function admitPage(input) {
     if (input === null || typeof input !== 'object' || Array.isArray(input)) {
@@ -33,11 +55,11 @@ function decodeResponse(input) {
     if (!hasExactKeys(value, ['result', 'page'])) {
         throw new TypeError('Graph query response is invalid.');
     }
-    const page = value.page;
-    if (page === null || typeof page !== 'object' || Array.isArray(page)) {
+    const pageInput = value.page;
+    if (pageInput === null || typeof pageInput !== 'object' || Array.isArray(pageInput)) {
         throw new TypeError('Graph query response page is invalid.');
     }
-    const pageValue = page;
+    const pageValue = pageInput;
     if (!hasExactKeys(pageValue, pageValue.next === undefined ? [] : ['next'])) {
         throw new TypeError('Graph query response page is invalid.');
     }
@@ -45,13 +67,11 @@ function decodeResponse(input) {
         (typeof pageValue.next !== 'string' || pageValue.next.length === 0)) {
         throw new TypeError('Graph query response continuation is invalid.');
     }
-    return Object.freeze({
-        result: QueryResult.decode(value.result),
-        page: Object.freeze(pageValue.next === undefined ? {} : { next: pageValue.next }),
-    });
+    const result = QueryResult.decode(value.result);
+    const page = Object.freeze(pageValue.next === undefined ? {} : { next: pageValue.next });
+    return Object.freeze({ result, page });
 }
 function hasExactKeys(input, expected) {
     const keys = Object.keys(input);
     return keys.length === expected.length && keys.every((key) => expected.includes(key));
 }
-//# sourceMappingURL=query.js.map

package/dist/graph/read.d.ts

@@ -1,7 +1,6 @@
 import type { Node } from '@astrale-os/kernel-core/graph/node';
-import type { PathLike } from '@astrale-os/kernel-core/path';
+import type { NodeTarget } from '@astrale-os/kernel-core/path';
 import type { RequestOptions } from '../transport/index.js';
 import type { GraphCall } from './graph.js';
-export declare function getNode(call: GraphCall, path: PathLike, options?: RequestOptions): Promise<Node | null>;
-export declare function requireNode(call: GraphCall, path: PathLike, options?: RequestOptions): Promise<Node>;
-//# sourceMappingURL=read.d.ts.map
+export declare function getNode(call: GraphCall, path: NodeTarget, options?: RequestOptions): Promise<Node | null>;
+export declare function requireNode(call: GraphCall, path: NodeTarget, options?: RequestOptions): Promise<Node>;

package/dist/graph/read.js

@@ -1,8 +1,8 @@
 import { Query } from '@astrale-os/kernel-core/graph/query';
 import { NodeUnavailableError } from './errors.js';
-import { queryGraph } from './query.js';
+import { queryGraph, queryNodePath } from './query.js';
 export async function getNode(call, path, options) {
-    const ast = Query.from({ kind: 'node', paths: [path] }).select({ kind: 'graph' });
+    const ast = Query.from({ nodes: [queryNodePath(path)] }).select({ kind: 'graph' });
     const response = await queryGraph(call, ast, { ...options, page: { size: 1 } });
     const { result } = response;
     if (result.kind !== 'graph')
@@ -10,9 +10,10 @@ export async function getNode(call, path, options) {
     return result.graph.nodes[0] ?? null;
 }
 export async function requireNode(call, path, options) {
-    const node = await getNode(call, path, options);
+    // Retain one immutable target across I/O, including unavailable-error rendering.
+    const target = queryNodePath(path);
+    const node = await getNode(call, target, options);
     if (node === null)
-        throw new NodeUnavailableError(path);
+        throw new NodeUnavailableError(target);
     return node;
 }
-//# sourceMappingURL=read.js.map

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { Client, call, type AuthenticatedClient, type Call, type ClientDispatchOptions, type ClientOptions, type Binary, type BinaryResponse, type Input, type RemoteCredential, type Result, type Stream, type StreamResult, type ValueResult, } from './client/index.js';
-export { ClientError, MissError, ProtocolError, type ProtocolErrorOptions, ResponseError, StaleRouteError, TransportError, type TransportDelivery, type TransportErrorOptions, type TransportPhase, } from './errors/index.js';
+export { Target, targetPath } from '@astrale-os/kernel-core/callable';
+export { Client, call, type AuthenticatedClient, type Call, type ClientDispatchOptions, type ClientDispatchOptionsWithBody, type ClientOptions, type Binary, type BinaryResponse, type Input, type RemoteCredential, type Result, type Stream, type StreamResult, type ValueResult, } from './client/index.js';
+export * from './errors/index.js';
 export { type RequestOptions, type MissControl, type StaleControl, type Transport, type TransportRequest, type TransportResult, } from './transport/index.js';
 export { HttpTransport, type Fetch, type HttpTransportOptions } from './transport/http/index.js';
 export { WebSocketTransport, type WebSocketConstructor, type WebSocketTransportOptions, } from './transport/websocket/index.js';
 export { AutoTransport, formatClientWarning, type AutoTransportOptions, type ClientWarning, } from './transport/auto/index.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,7 +1,7 @@
+export { Target, targetPath } from '@astrale-os/kernel-core/callable';
 export { Client, call, } from './client/index.js';
-export { ClientError, MissError, ProtocolError, ResponseError, StaleRouteError, TransportError, } from './errors/index.js';
+export * from './errors/index.js';
 export {} from './transport/index.js';
 export { HttpTransport } from './transport/http/index.js';
 export { WebSocketTransport, } from './transport/websocket/index.js';
 export { AutoTransport, formatClientWarning, } from './transport/auto/index.js';
-//# sourceMappingURL=index.js.map

package/dist/pacer/batcher/batcher.d.ts

@@ -5,4 +5,3 @@ export type BatchOptions<Value> = Omit<AsyncBatcherOptions<Value>, 'maxSize' | '
     readonly wait?: number;
 };
 export declare function createBatcher<Value>(consume: (values: Value[]) => Promise<unknown>, options?: BatchOptions<Value>): AsyncBatcher<Value>;
-//# sourceMappingURL=batcher.d.ts.map

package/dist/pacer/batcher/batcher.js

@@ -11,4 +11,3 @@ export function createBatcher(consume, options = {}) {
         wait: options.wait ?? DEFAULT_BATCH_WAIT_MS,
     });
 }
-//# sourceMappingURL=batcher.js.map

package/dist/pacer/batcher/defaults.d.ts

@@ -1,3 +1,2 @@
 export declare const DEFAULT_BATCH_SIZE = 100;
 export declare const DEFAULT_BATCH_WAIT_MS = 10;
-//# sourceMappingURL=defaults.d.ts.map

package/dist/pacer/batcher/defaults.js

@@ -1,3 +1,2 @@
 export const DEFAULT_BATCH_SIZE = 100;
 export const DEFAULT_BATCH_WAIT_MS = 10;
-//# sourceMappingURL=defaults.js.map

package/dist/pacer/batcher/index.d.ts

@@ -1,2 +1 @@
 export { createBatcher, type BatchOptions } from './batcher.js';
-//# sourceMappingURL=index.d.ts.map