@astrale-os/kernel-client 0.5.1 → 0.6.0-beta.10

package/dist/client/request.js

@@ -0,0 +1,100 @@
+import * as invocationProtocol from '@astrale-os/kernel-protocol/invocation';
+import { acceptCall } from './admission.js';
+export function call(target, input) {
+    return Object.freeze({ target, input });
+}
+export function admitRequest(input, options, lifecycle) {
+    const call = acceptCall(input);
+    const admittedOptions = lifecycleOptions(admitRequestOptions(options), lifecycle);
+    const delegate = admitDelegate(options?.delegate);
+    const routing = admitRouting(options?.routing);
+    const schema = admitSchemaTarget(options?.schema);
+    return Object.freeze({
+        call,
+        ...(delegate === undefined ? {} : { delegate }),
+        ...(routing === undefined ? {} : { routing }),
+        ...(schema === undefined ? {} : { schema }),
+        options: admittedOptions,
+    });
+}
+export function invocation(request, credential, trace) {
+    const admittedTrace = trace === undefined ? undefined : invocationProtocol.admitTrace(trace);
+    if (request.routing?.kind === 'via') {
+        if (request.delegate !== undefined) {
+            throw new TypeError('Destination Client requests cannot carry a delegation request.');
+        }
+        if (request.schema !== undefined) {
+            throw new TypeError('Destination Client requests cannot carry a Schema target.');
+        }
+    }
+    else if ((credential === undefined) !== (request.delegate === undefined)) {
+        throw new TypeError('Source Client credentials and delegation requests must occur together.');
+    }
+    return Object.freeze({
+        call: request.call,
+        ...(credential === undefined ? {} : { credential }),
+        ...(request.delegate === undefined ? {} : { delegate: request.delegate }),
+        ...(request.routing === undefined ? {} : { routing: request.routing }),
+        ...(request.schema === undefined ? {} : { schema: request.schema }),
+        ...(admittedTrace === undefined ? {} : { trace: admittedTrace }),
+    });
+}
+function admitRequestOptions(input) {
+    if (input === undefined)
+        return undefined;
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Client request options must be an object.');
+    }
+    if (input.timeoutMs !== undefined &&
+        (!Number.isSafeInteger(input.timeoutMs) ||
+            input.timeoutMs < 1 ||
+            input.timeoutMs > 2_147_483_647)) {
+        throw new TypeError('Client request timeoutMs must be a positive safe platform integer.');
+    }
+    const idempotencyKey = input.idempotencyKey === undefined
+        ? undefined
+        : invocationProtocol.acceptIdempotencyKey(input.idempotencyKey, 'request.idempotencyKey');
+    return Object.freeze({
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+        ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+        ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+    });
+}
+function admitDelegate(input) {
+    if (input === undefined)
+        return undefined;
+    try {
+        return invocationProtocol.acceptDelegate(input);
+    }
+    catch (cause) {
+        throw new TypeError('Client delegation request is invalid.', { cause });
+    }
+}
+function admitRouting(input) {
+    if (input === undefined)
+        return undefined;
+    try {
+        return invocationProtocol.acceptRouting(input);
+    }
+    catch (cause) {
+        throw new TypeError('Client routing context is invalid.', { cause });
+    }
+}
+function admitSchemaTarget(input) {
+    if (input === undefined)
+        return undefined;
+    try {
+        return invocationProtocol.acceptSchemaTarget(input);
+    }
+    catch (cause) {
+        throw new TypeError('Client Schema target is invalid.', { cause });
+    }
+}
+function lifecycleOptions(input, lifecycle) {
+    const signal = input?.signal === undefined ? lifecycle : AbortSignal.any([input.signal, lifecycle]);
+    return Object.freeze({
+        signal,
+        ...(input?.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+        ...(input?.idempotencyKey === undefined ? {} : { idempotencyKey: input.idempotencyKey }),
+    });
+}

package/dist/client/result.d.ts

@@ -0,0 +1,35 @@
+import type { BinaryResult, CallableResult } from '@astrale-os/kernel-core/callable';
+import type { Value } from '@astrale-os/kernel-dsl/value';
+import type { invocation as protocol } from '@astrale-os/kernel-protocol';
+/** Caller-visible value accepted from one admitted remote invocation. */
+export type Input = Value;
+/** Caller-visible finite binary response. */
+export type Binary = BinaryResult;
+/** Caller-owned remote stream. */
+export interface Stream extends AsyncIterable<Value> {
+    cancel(reason?: string): Promise<void>;
+}
+/** Complete result observed by a Client before result-mode narrowing. */
+type Correlated<Result> = Result & {
+    readonly invocation: protocol.InvocationId;
+};
+type Callable = CallableResult<Value, Stream>;
+export type ValueResult = Correlated<Extract<Callable, {
+    readonly kind: 'value';
+}>>;
+export type StreamResult = Correlated<Extract<Callable, {
+    readonly kind: 'stream';
+}>>;
+export type BinaryResponse = Correlated<Extract<Callable, {
+    readonly kind: 'binary';
+}>>;
+export interface RedirectResult {
+    readonly kind: 'redirect';
+    readonly redirect: protocol.Redirection;
+    readonly invocation: protocol.InvocationId;
+}
+export type Result = ValueResult | StreamResult | BinaryResponse | RedirectResult;
+export declare function requireValue(result: Promise<Result>): Promise<ValueResult>;
+export declare function requireStream(result: Promise<Result>): Promise<StreamResult>;
+export declare function requireBinary(result: Promise<Result>): Promise<BinaryResponse>;
+export {};

package/dist/client/result.js

@@ -0,0 +1,28 @@
+import { ClientError } from '../errors/index.js';
+export async function requireValue(result) {
+    const settled = await result;
+    if (settled.kind !== 'value')
+        return rejectMismatch('value', settled);
+    return settled;
+}
+export async function requireStream(result) {
+    const settled = await result;
+    if (settled.kind !== 'stream')
+        mismatch('stream', settled.kind);
+    return settled;
+}
+export async function requireBinary(result) {
+    const settled = await result;
+    if (settled.kind !== 'binary')
+        return rejectMismatch('binary', settled);
+    return settled;
+}
+function mismatch(expected, received) {
+    throw new ClientError(`Function returned ${received}; ${expected} was required.`);
+}
+async function rejectMismatch(expected, result) {
+    if (result.kind === 'stream') {
+        await result.stream.cancel(`Expected ${expected} Function result.`).catch(() => undefined);
+    }
+    mismatch(expected, result.kind);
+}

package/dist/client/routing-control.d.ts

@@ -0,0 +1,10 @@
+import type { invocation as protocol, publication } from '@astrale-os/kernel-protocol';
+import { MissError, StaleRouteError } from '../errors/index.js';
+/** Create a private routing witness only after exact reserved-control decoding. */
+export declare function admittedMissError(invocation: protocol.InvocationId): MissError;
+/** Create a private routing witness only after exact reserved-control decoding. */
+export declare function admittedStaleRouteError(currentEtag: publication.Etag, invocation: protocol.InvocationId): StaleRouteError;
+/** Distinguish decoded routing control from public or caller-supplied lookalike errors. */
+export declare function isAdmittedMissError(input: unknown): input is MissError;
+/** Distinguish decoded routing control from public or caller-supplied lookalike errors. */
+export declare function isAdmittedStaleRouteError(input: unknown): input is StaleRouteError;

package/dist/client/routing-control.js

@@ -0,0 +1,23 @@
+import { MissError, StaleRouteError } from '../errors/index.js';
+const admittedMisses = new WeakSet();
+const admittedStaleRoutes = new WeakSet();
+/** Create a private routing witness only after exact reserved-control decoding. */
+export function admittedMissError(invocation) {
+    const error = new MissError(invocation);
+    admittedMisses.add(error);
+    return error;
+}
+/** Create a private routing witness only after exact reserved-control decoding. */
+export function admittedStaleRouteError(currentEtag, invocation) {
+    const error = new StaleRouteError(currentEtag, invocation);
+    admittedStaleRoutes.add(error);
+    return error;
+}
+/** Distinguish decoded routing control from public or caller-supplied lookalike errors. */
+export function isAdmittedMissError(input) {
+    return input instanceof MissError && admittedMisses.has(input);
+}
+/** Distinguish decoded routing control from public or caller-supplied lookalike errors. */
+export function isAdmittedStaleRouteError(input) {
+    return input instanceof StaleRouteError && admittedStaleRoutes.has(input);
+}

package/dist/errors/client-error.d.ts

@@ -0,0 +1,3 @@
+export declare class ClientError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/errors/client-error.js

@@ -0,0 +1,8 @@
+export class ClientError extends Error {
+    constructor(message, options) {
+        if (message.trim() === '')
+            throw new TypeError('Client error message must be non-blank.');
+        super(message, options);
+        this.name = 'ClientError';
+    }
+}

package/dist/errors/index.d.ts

@@ -1,6 +1,7 @@
-export { AuthBatchError, AuthenticationError, ConnectionError, DisconnectedError, InternalKernelError, InvalidTransportError, InvalidRequestError, InvariantViolationError, KernelError, NodeUnavailableError, NotFoundError, ParseError, PermissionDeniedError, TimeoutError, UnsupportedTransportError, ValidationError, WebOSError, mapServerError, withDetails, } from './errors.js';
-export type { AuthBatchOutcome, AuthReason, ClientErrorDetails } from './errors.js';
-export { classifyKernelError, isAuthBatchError, isAuthenticationError, isClientSessionError, isDelegationMintError, isDelegationPolicyError, isDelegationRefusedError, isHopLimitExceededError, isIdentityError, isInternalKernelError, isInvalidRequestError, isInvalidTransportError, isInvariantViolationError, isKernelError, isNodeUnavailableError, isNotFoundError, isParseError, isPermissionDeniedError, isPersistenceLoadFailedError, isPoolClosedError, isRedirectPolicyError, isRedirectRefusedError, isRegistryWriteFailedError, isSchemaOwnershipConflictError, isTransportError, isUnsupportedTransportError, isValidationError, isWebOSError, } from './guards.js';
-export type { IdentityError, KernelErrorKind, TransportError } from './guards.js';
-export { ClientSessionError } from './session-error.js';
-//# sourceMappingURL=index.d.ts.map
+export * from './client-error.js';
+export * from './miss-error.js';
+export * from './protocol-error.js';
+export * from './response-error.js';
+export * from './session-error.js';
+export * from './stale-route-error.js';
+export * from './transport-error.js';

package/dist/errors/index.js

@@ -1,4 +1,7 @@
-export { AuthBatchError, AuthenticationError, ConnectionError, DisconnectedError, InternalKernelError, InvalidTransportError, InvalidRequestError, InvariantViolationError, KernelError, NodeUnavailableError, NotFoundError, ParseError, PermissionDeniedError, TimeoutError, UnsupportedTransportError, ValidationError, WebOSError, mapServerError, withDetails, } from './errors.js';
-export { classifyKernelError, isAuthBatchError, isAuthenticationError, isClientSessionError, isDelegationMintError, isDelegationPolicyError, isDelegationRefusedError, isHopLimitExceededError, isIdentityError, isInternalKernelError, isInvalidRequestError, isInvalidTransportError, isInvariantViolationError, isKernelError, isNodeUnavailableError, isNotFoundError, isParseError, isPermissionDeniedError, isPersistenceLoadFailedError, isPoolClosedError, isRedirectPolicyError, isRedirectRefusedError, isRegistryWriteFailedError, isSchemaOwnershipConflictError, isTransportError, isUnsupportedTransportError, isValidationError, isWebOSError, } from './guards.js';
-export { ClientSessionError } from './session-error.js';
-//# sourceMappingURL=index.js.map
+export * from './client-error.js';
+export * from './miss-error.js';
+export * from './protocol-error.js';
+export * from './response-error.js';
+export * from './session-error.js';
+export * from './stale-route-error.js';
+export * from './transport-error.js';

package/dist/errors/miss-error.d.ts

@@ -0,0 +1,8 @@
+import type { invocation as protocol } from '@astrale-os/kernel-protocol';
+import { ClientError } from './client-error.js';
+/** Client-visible indication that the current Path is no longer served at the learned destination. */
+export declare class MissError extends ClientError {
+    readonly invocation: protocol.InvocationId;
+    readonly name = "MissError";
+    constructor(invocation: protocol.InvocationId);
+}

package/dist/errors/miss-error.js

@@ -0,0 +1,10 @@
+import { ClientError } from './client-error.js';
+/** Client-visible indication that the current Path is no longer served at the learned destination. */
+export class MissError extends ClientError {
+    invocation;
+    name = 'MissError';
+    constructor(invocation) {
+        super('The destination no longer serves this Path.');
+        this.invocation = invocation;
+    }
+}

package/dist/errors/protocol-error.d.ts

@@ -0,0 +1,9 @@
+import type { invocation as protocol } from '@astrale-os/kernel-protocol';
+import { ClientError } from './client-error.js';
+export interface ProtocolErrorOptions extends ErrorOptions {
+    readonly invocation?: protocol.InvocationId;
+}
+export declare class ProtocolError extends ClientError {
+    readonly invocation?: protocol.InvocationId;
+    constructor(message: string, options?: ProtocolErrorOptions);
+}

package/dist/errors/protocol-error.js

@@ -0,0 +1,9 @@
+import { ClientError } from './client-error.js';
+export class ProtocolError extends ClientError {
+    invocation;
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ProtocolError';
+        this.invocation = options?.invocation;
+    }
+}

package/dist/errors/response-error.d.ts

@@ -0,0 +1,11 @@
+import type { Value } from '@astrale-os/kernel-dsl/value';
+import type * as protocol from '@astrale-os/kernel-protocol/invocation';
+import * as errors from '@astrale-os/kernel-protocol/errors';
+import { ClientError } from './client-error.js';
+export declare class ResponseError extends ClientError {
+    readonly code: errors.ErrorCode;
+    readonly invocation: protocol.InvocationId;
+    readonly data?: Value | undefined;
+    readonly reason?: errors.ErrorReason;
+    constructor(code: errors.ErrorCode, message: string, invocation: protocol.InvocationId, data?: Value | undefined);
+}

package/dist/errors/response-error.js

@@ -0,0 +1,16 @@
+import * as errors from '@astrale-os/kernel-protocol/errors';
+import { ClientError } from './client-error.js';
+export class ResponseError extends ClientError {
+    code;
+    invocation;
+    data;
+    reason;
+    constructor(code, message, invocation, data) {
+        super(message);
+        this.code = code;
+        this.invocation = invocation;
+        this.data = data;
+        this.name = 'ResponseError';
+        this.reason = errors.reasonOf(data);
+    }
+}

package/dist/errors/session-error.d.ts

@@ -1,21 +1,9 @@
-import { WebOSError } from './errors.js';
-/**
- * Base class for every error ClientSession adds on top of the wire client's
- * `WebOSError` hierarchy.
- *
- * Instances carry a string `kind` discriminator that narrows across
- * every ClientSessionError subclass — consumers can `switch (e.kind)` as a
- * one-namespace alternative to chains of `instanceof`. The choice of
- * `kind` (not `type`) avoids ambiguity with `KernelError.type` which
- * carries server-error-category strings.
- *
- * Lives in `@astrale-os/kernel-client/errors` (alongside `WebOSError`)
- * rather than `session/errors` so that helper subpaths (`redirect`,
- * `delegation`) can extend it without importing from `session/` —
- * keeping the `session → helpers → errors` dep graph (§17.3) intact.
- */
-export declare class ClientSessionError extends WebOSError {
-    readonly kind: string;
-    constructor(message: string, kind: string, options?: ErrorOptions);
+import { ClientError } from './client-error.js';
+export type SessionFailure = 'cancelled' | 'closed' | 'timeout';
+export interface SessionErrorOptions extends ErrorOptions {
+    readonly failure: SessionFailure;
+}
+export declare class SessionError extends ClientError {
+    readonly failure: SessionFailure;
+    constructor(message: string, options: SessionErrorOptions);
 }
-//# sourceMappingURL=session-error.d.ts.map

package/dist/errors/session-error.js

@@ -1,25 +1,9 @@
-import { WebOSError } from './errors.js';
-/**
- * Base class for every error ClientSession adds on top of the wire client's
- * `WebOSError` hierarchy.
- *
- * Instances carry a string `kind` discriminator that narrows across
- * every ClientSessionError subclass — consumers can `switch (e.kind)` as a
- * one-namespace alternative to chains of `instanceof`. The choice of
- * `kind` (not `type`) avoids ambiguity with `KernelError.type` which
- * carries server-error-category strings.
- *
- * Lives in `@astrale-os/kernel-client/errors` (alongside `WebOSError`)
- * rather than `session/errors` so that helper subpaths (`redirect`,
- * `delegation`) can extend it without importing from `session/` —
- * keeping the `session → helpers → errors` dep graph (§17.3) intact.
- */
-export class ClientSessionError extends WebOSError {
-    kind;
-    constructor(message, kind, options) {
+import { ClientError } from './client-error.js';
+export class SessionError extends ClientError {
+    failure;
+    constructor(message, options) {
         super(message, options);
-        this.kind = kind;
-        this.name = 'ClientSessionError';
+        this.name = 'SessionError';
+        this.failure = options.failure;
     }
 }
-//# sourceMappingURL=session-error.js.map

package/dist/errors/stale-route-error.d.ts

@@ -0,0 +1,9 @@
+import type { invocation as protocol, publication } from '@astrale-os/kernel-protocol';
+import { ClientError } from './client-error.js';
+/** Client-visible stale-route error shape; public instances are not routing-control witnesses. */
+export declare class StaleRouteError extends ClientError {
+    readonly currentEtag: publication.Etag;
+    readonly invocation: protocol.InvocationId;
+    readonly name = "StaleRouteError";
+    constructor(currentEtag: publication.Etag, invocation: protocol.InvocationId);
+}

package/dist/errors/stale-route-error.js

@@ -0,0 +1,12 @@
+import { ClientError } from './client-error.js';
+/** Client-visible stale-route error shape; public instances are not routing-control witnesses. */
+export class StaleRouteError extends ClientError {
+    currentEtag;
+    invocation;
+    name = 'StaleRouteError';
+    constructor(currentEtag, invocation) {
+        super('The destination Publication route is stale.');
+        this.currentEtag = currentEtag;
+        this.invocation = invocation;
+    }
+}

package/dist/errors/transport-error.d.ts

@@ -0,0 +1,30 @@
+import type { invocation as protocol } from '@astrale-os/kernel-protocol';
+import { ClientError } from './client-error.js';
+/** Whether an invocation is proven not to have crossed the transport boundary. */
+export type TransportDelivery = 'not-sent' | 'unknown';
+/** Observable transport phase in which communication stopped. */
+export type TransportPhase = 'connect' | 'send' | 'receive' | 'timeout' | 'closed' | 'unknown';
+export type TransportContext = {
+    readonly kind: 'acquisition';
+    readonly resource: 'publication' | 'bundle';
+} | {
+    readonly kind: 'invocation';
+    readonly delivery: TransportDelivery;
+    readonly invocation?: protocol.InvocationId;
+};
+export interface AcquisitionTransportErrorOptions extends ErrorOptions {
+    readonly phase: TransportPhase;
+    readonly resource: 'publication' | 'bundle';
+}
+export interface InvocationTransportErrorOptions extends ErrorOptions {
+    readonly phase: TransportPhase;
+    readonly delivery: TransportDelivery;
+    readonly invocation?: protocol.InvocationId;
+}
+export declare class TransportError extends ClientError {
+    readonly phase: TransportPhase;
+    readonly context: TransportContext;
+    private constructor();
+    static acquisition(message: string, options: AcquisitionTransportErrorOptions): TransportError;
+    static invocation(message: string, options: InvocationTransportErrorOptions): TransportError;
+}

package/dist/errors/transport-error.js

@@ -0,0 +1,18 @@
+import { ClientError } from './client-error.js';
+export class TransportError extends ClientError {
+    phase;
+    context;
+    constructor(message, phase, context, options) {
+        super(message, options);
+        this.phase = phase;
+        this.context = context;
+        this.name = 'TransportError';
+        Object.freeze(context);
+    }
+    static acquisition(message, options) {
+        return new TransportError(message, options.phase, { kind: 'acquisition', resource: options.resource }, options);
+    }
+    static invocation(message, options) {
+        return new TransportError(message, options.phase, { kind: 'invocation', delivery: options.delivery, invocation: options.invocation }, options);
+    }
+}

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

@@ -0,0 +1,22 @@
+import type { Edge } from '@astrale-os/kernel-core/graph/edge';
+import type { Node } from '@astrale-os/kernel-core/graph/node';
+import type { QueryAST, QuerySingleSourceClassOf } from '@astrale-os/kernel-core/graph/query';
+import type { Domain } from '@astrale-os/kernel-dsl/v1/domain';
+import type { AnyResolvedClass, ResolvedClass } from '@astrale-os/kernel-dsl/v1/language';
+import type { GraphApi, GraphQueryOptions } from '../graph.js';
+import type { BoundEdge, BoundNode } from './model.js';
+import type { BoundQueryPage } from './page.js';
+import type { MethodCall } from './project.js';
+export type DomainQueryOptions = Omit<GraphQueryOptions, 'expected'>;
+type AdmittedSourceClasses<Query extends QueryAST> = [QuerySingleSourceClassOf<Query>] extends [
+    never
+] ? never : QuerySingleSourceClassOf<Query> extends AnyResolvedClass ? unknown : never;
+export interface DomainBinding<DomainValue extends Domain = Domain> {
+    readonly domain: DomainValue;
+    readonly graph: GraphApi;
+    query<Query extends QueryAST>(query: Query & AdmittedSourceClasses<Query>, options: DomainQueryOptions): Promise<BoundQueryPage<Query>>;
+    wrapNode<Class extends ResolvedClass<'node'>>(selected: Class, node: Node): BoundNode<Class>;
+    wrapEdge<Class extends ResolvedClass<'edge'>>(selected: Class, edge: Edge): BoundEdge<Class>;
+}
+export declare function createDomainBinding<DomainValue extends Domain>(domain: DomainValue, graph: GraphApi, call: MethodCall): DomainBinding<DomainValue>;
+export {};

package/dist/graph/domain/binding.js

@@ -0,0 +1,123 @@
+import { ClassKey } from '@astrale-os/kernel-dsl/v1/addressing';
+import { isDomain } from '@astrale-os/kernel-dsl/v1/domain';
+import { provenanceOfGraphValue, provenanceOfResponse } from '../provenance.js';
+import { selectedEdges, selectedNodes } from './page.js';
+import { projectEdge, projectNode } from './project.js';
+import { provenanceOfProjectedValue, sameClosure } from './provenance.js';
+export function createDomainBinding(domain, graph, call) {
+    if (!isDomain(domain))
+        throw new TypeError('Domain binding requires an admitted DSL Domain.');
+    const wrapNode = (selected, node) => {
+        requireOwnedClass(domain, selected);
+        const provenance = requireProvenance(domain, node);
+        const exact = requireExactClass(domain, node.class, 'node');
+        if (!exact.satisfies(selected))
+            throw new TypeError(`${exact.key} does not satisfy ${selected.key}.`);
+        const diagnostics = exact.validateProperties(node.props);
+        if (diagnostics.length > 0)
+            throw new TypeError(`Node ${node.id} has invalid exact Properties.`);
+        return projectNode(selected, node, provenance, call);
+    };
+    const wrapEdge = (selected, edge) => {
+        requireOwnedClass(domain, selected);
+        const provenance = requireProvenance(domain, edge);
+        const exact = requireExactClass(domain, edge.class, 'edge');
+        if (!exact.satisfies(selected))
+            throw new TypeError(`${exact.key} does not satisfy ${selected.key}.`);
+        const diagnostics = exact.validateProperties(edge.props);
+        if (diagnostics.length > 0)
+            throw new TypeError('Edge has invalid exact Properties.');
+        return projectEdge(selected, edge, provenance);
+    };
+    return Object.freeze({
+        domain,
+        graph,
+        async query(query, options) {
+            const selected = selectedSourceClass(domain, query);
+            const response = await graph.query(query, { ...options, expected: domain.closure });
+            const provenance = provenanceOfResponse(response);
+            if (provenance === undefined || !sameClosure(provenance.closure, domain.closure)) {
+                throw new TypeError('Authenticated query provenance was not retained.');
+            }
+            const next = response.page.next === undefined
+                ? undefined
+                : () => this.query(query, {
+                    ...options,
+                    page: { ...options.page, after: response.page.next },
+                });
+            if (selected.kind === 'node') {
+                const nodes = selectedNodes(response).map((node) => wrapNode(selected, node));
+                return Object.freeze({
+                    nodes: Object.freeze(nodes),
+                    raw: response,
+                    ...(next === undefined ? {} : { next }),
+                    refine: (value, target) => refineNode(domain, call, value, target, provenance),
+                });
+            }
+            const edges = selectedEdges(response).map((edge) => wrapEdge(selected, edge));
+            return Object.freeze({
+                edges: Object.freeze(edges),
+                raw: response,
+                ...(next === undefined ? {} : { next }),
+                refine: (value, target) => refineEdge(domain, value, target, provenance),
+            });
+        },
+        wrapNode,
+        wrapEdge,
+    });
+}
+function selectedSourceClass(domain, query) {
+    if (query.steps.some((step) => step.op === 'expand')) {
+        throw new TypeError('Rich Domain queries do not yet project expanded bindings.');
+    }
+    if (query.source.terms.length !== 1 || query.source.terms[0]?.kind !== 'class') {
+        throw new TypeError('Rich Domain queries require one exact Class source term.');
+    }
+    const sourceBinding = query.source.kind === 'node' ? query.source.binding : query.source.bindings.edge;
+    if (query.select.binding !== sourceBinding) {
+        throw new TypeError('Rich Domain queries must select their original source binding.');
+    }
+    const selected = domain.definition(query.source.terms[0].class);
+    if (selected?.ref.kind !== 'class' || selected.kind !== query.source.kind) {
+        throw new TypeError('Query source Class is absent or has the wrong graph kind.');
+    }
+    return selected;
+}
+function refineNode(domain, call, value, target, page) {
+    requireOwnedClass(domain, target);
+    const provenance = requirePageProvenance(value, page);
+    const exact = requireExactClass(domain, value.class, 'node');
+    return exact.satisfies(target) ? projectNode(target, value, provenance, call) : undefined;
+}
+function refineEdge(domain, value, target, page) {
+    requireOwnedClass(domain, target);
+    const provenance = requirePageProvenance(value, page);
+    const exact = requireExactClass(domain, value.class, 'edge');
+    return exact.satisfies(target) ? projectEdge(target, value, provenance) : undefined;
+}
+function requirePageProvenance(value, page) {
+    const provenance = provenanceOfProjectedValue(value);
+    if (provenance?.page !== page.page) {
+        throw new TypeError('Refinement requires a value from this exact result page.');
+    }
+    return provenance;
+}
+function requireOwnedClass(domain, selected) {
+    if (domain.definition(selected.key) !== selected) {
+        throw new TypeError('Selected Class does not belong to the bound Domain closure.');
+    }
+}
+function requireProvenance(domain, value) {
+    const provenance = provenanceOfGraphValue(value);
+    if (provenance === undefined || !sameClosure(provenance.closure, domain.closure)) {
+        throw new TypeError('Graph value lacks matching authenticated query provenance.');
+    }
+    return provenance;
+}
+function requireExactClass(domain, key, kind) {
+    const exact = domain.definition(ClassKey.ref(ClassKey(key)));
+    if (exact?.ref.kind !== 'class' || exact.kind !== kind || exact.abstract) {
+        throw new TypeError(`Exact ${kind} Class ${key} is not active and concrete.`);
+    }
+    return exact;
+}

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

@@ -0,0 +1 @@
+export {};