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

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

@@ -0,0 +1,19 @@
+import { ClientError } from './client-error.js';
+/**
+ * Why a Domain token exchange failed.
+ *
+ * - `discovery`: the Domain issuer's configuration could not be read or admitted.
+ * - `unsupported`: the Domain issuer advertises no token exchange endpoint.
+ * - `unavailable`: a Domain issuer endpoint could not be reached.
+ * - `rejected`: the Domain refused the delegation; its public error is the `cause`.
+ * - `invalid-response`: the exchange response or its credential failed admission.
+ * - `source-exhausted`: the source credential can no longer grant the lifetime the exchange needs.
+ */
+export type ExchangeFailure = 'discovery' | 'unsupported' | 'unavailable' | 'rejected' | 'invalid-response' | 'source-exhausted';
+export interface ExchangeErrorOptions extends ErrorOptions {
+    readonly failure: ExchangeFailure;
+}
+export declare class ExchangeError extends ClientError {
+    readonly failure: ExchangeFailure;
+    constructor(message: string, options: ExchangeErrorOptions);
+}

package/dist/errors/exchange-error.js

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

package/dist/errors/index.d.ts

@@ -1,7 +1,8 @@
-export { ClientError } from './client-error.js';
-export { MissError } from './miss-error.js';
-export { ProtocolError, type ProtocolErrorOptions } from './protocol-error.js';
-export { ResponseError } from './response-error.js';
-export { StaleRouteError } from './stale-route-error.js';
-export { TransportError, type TransportDelivery, type TransportErrorOptions, type TransportPhase, } from './transport-error.js';
-//# sourceMappingURL=index.d.ts.map
+export * from './client-error.js';
+export * from './exchange-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,7 +1,8 @@
-export { ClientError } from './client-error.js';
-export { MissError } from './miss-error.js';
-export { ProtocolError } from './protocol-error.js';
-export { ResponseError } from './response-error.js';
-export { StaleRouteError } from './stale-route-error.js';
-export { TransportError, } from './transport-error.js';
-//# sourceMappingURL=index.js.map
+export * from './client-error.js';
+export * from './exchange-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

@@ -6,4 +6,3 @@ export declare class MissError extends ClientError {
     readonly name = "MissError";
     constructor(invocation: protocol.InvocationId);
 }
-//# sourceMappingURL=miss-error.d.ts.map

package/dist/errors/miss-error.js

@@ -8,4 +8,3 @@ export class MissError extends ClientError {
         this.invocation = invocation;
     }
 }
-//# sourceMappingURL=miss-error.js.map

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

@@ -7,4 +7,3 @@ export declare class ProtocolError extends ClientError {
     readonly invocation?: protocol.InvocationId;
     constructor(message: string, options?: ProtocolErrorOptions);
 }
-//# sourceMappingURL=protocol-error.d.ts.map

package/dist/errors/protocol-error.js

@@ -7,4 +7,3 @@ export class ProtocolError extends ClientError {
         this.invocation = options?.invocation;
     }
 }
-//# sourceMappingURL=protocol-error.js.map

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

@@ -9,4 +9,3 @@ export declare class ResponseError extends ClientError {
     readonly reason?: errors.ErrorReason;
     constructor(code: errors.ErrorCode, message: string, invocation: protocol.InvocationId, data?: Value | undefined);
 }
-//# sourceMappingURL=response-error.d.ts.map

package/dist/errors/response-error.js

@@ -14,4 +14,3 @@ export class ResponseError extends ClientError {
         this.reason = errors.reasonOf(data);
     }
 }
-//# sourceMappingURL=response-error.js.map

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

@@ -0,0 +1,9 @@
+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);
+}

package/dist/errors/session-error.js

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

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

@@ -7,4 +7,3 @@ export declare class StaleRouteError extends ClientError {
     readonly name = "StaleRouteError";
     constructor(currentEtag: publication.Etag, invocation: protocol.InvocationId);
 }
-//# sourceMappingURL=stale-route-error.d.ts.map

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

@@ -10,4 +10,3 @@ export class StaleRouteError extends ClientError {
         this.invocation = invocation;
     }
 }
-//# sourceMappingURL=stale-route-error.js.map

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

@@ -3,16 +3,28 @@ 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';
-export interface TransportErrorOptions extends ErrorOptions {
-    readonly phase: TransportPhase;
+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 declare class TransportError extends ClientError {
+export interface InvocationTransportErrorOptions extends ErrorOptions {
     readonly phase: TransportPhase;
     readonly delivery: TransportDelivery;
     readonly invocation?: protocol.InvocationId;
-    constructor(message: string, options: TransportErrorOptions);
 }
-//# sourceMappingURL=transport-error.d.ts.map
+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

@@ -1,14 +1,18 @@
 import { ClientError } from './client-error.js';
 export class TransportError extends ClientError {
     phase;
-    delivery;
-    invocation;
-    constructor(message, options) {
+    context;
+    constructor(message, phase, context, options) {
         super(message, options);
+        this.phase = phase;
+        this.context = context;
         this.name = 'TransportError';
-        this.phase = options.phase;
-        this.delivery = options.delivery;
-        this.invocation = options.invocation;
+        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);
     }
 }
-//# sourceMappingURL=transport-error.js.map

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 {};

package/dist/graph/domain/domain.typecheck.js

@@ -0,0 +1,147 @@
+import { NodeId } from '@astrale-os/kernel-core/graph/node';
+import { Query, QueryAST } from '@astrale-os/kernel-core/graph/query';
+import { Path } from '@astrale-os/kernel-core/path';
+import { schema } from '@astrale-os/kernel-dsl/v1';
+import { defineSchema, edgeClass, method, nodeClass, property, valueSchema, } from '@astrale-os/kernel-dsl/v1/builder';
+const Resource = nodeClass({
+    abstract: true,
+    properties: {
+        title: property(valueSchema()({ type: 'string' }), { required: true }),
+    },
+    methods: {
+        rename: method({
+            auth: 'authenticated',
+            input: valueSchema()({
+                type: 'object',
+                properties: { title: { type: 'string' } },
+                required: ['title'],
+                additionalProperties: false,
+            }),
+            output: valueSchema()({ type: 'string' }),
+        }),
+    },
+});
+const Document = nodeClass({
+    extends: [Resource],
+    properties: { body: property(valueSchema()({ type: 'string' })) },
+});
+const MethodlessParent = nodeClass({
+    abstract: true,
+    properties: {},
+});
+const MethodlessChild = nodeClass({
+    extends: [MethodlessParent],
+    properties: {},
+});
+const PrototypeMembers = nodeClass({
+    properties: {
+        toString: property(valueSchema()({ type: 'string' }), { required: true }),
+    },
+    methods: {
+        constructor: method({
+            auth: 'authenticated',
+            input: valueSchema()({ type: 'string' }),
+            output: valueSchema()({ type: 'string' }),
+        }),
+    },
+});
+const Work = schema.resolve(defineSchema('client-binding-types.example', {
+    classes: {
+        Resource,
+        Document,
+        MethodlessParent,
+        MethodlessChild,
+        PrototypeMembers,
+        Related: edgeClass.directed({
+            source: { as: 'source', accepts: [Resource], outgoing: '0..*' },
+            target: { as: 'target', accepts: [Resource], incoming: '0..*' },
+        }),
+    },
+}));
+const source = Query.from({ nodes: [Work.classes.Resource] });
+const query = source.select({ kind: 'nodes', projection: { kind: 'value' } });
+const prototypeSource = Query.from({ nodes: [Work.classes.PrototypeMembers] });
+const prototypeQuery = prototypeSource.select({ kind: 'nodes', projection: { kind: 'value' } });
+// @ts-expect-error Concrete Method shortcuts are absent from a child-selected projection.
+const resourceAcceptsDocument = documentProjection;
+void resourceAcceptsDocument;
+const resourceReceiverAcceptsDocument = documentProjection;
+void resourceReceiverAcceptsDocument;
+// @ts-expect-error A projection selected for another unrelated Class is not a Resource projection.
+const resourceRejectsPrototype = prototypeProjection;
+void resourceRejectsPrototype;
+// @ts-expect-error Receiver evidence selected for an unrelated Class is not accepted.
+const resourceReceiverRejectsPrototype = prototypeProjection;
+void resourceReceiverRejectsPrototype;
+const methodlessParentAcceptsChild = methodlessChildProjection;
+void methodlessParentAcceptsChild;
+// @ts-expect-error Selected ancestor provenance cannot be widened into a child projection.
+const documentRejectsResource = resourceProjection;
+void documentRejectsResource;
+async function typeProof() {
+    await graph.get(definitionRef);
+    await graph.getOrThrow(definitionRef);
+    await graph.get(Work.classes.Resource.ref);
+    await graph.neighbors(definitionRef, Work.classes.Related.ref, {
+        direction: 'outgoing',
+        page: { size: 1 },
+    });
+    const page = await binding.query(query, { page: { size: 10 } });
+    const resource = page.nodes[0];
+    const title = resource.title;
+    const renamed = await resource.rename({ title: 'next' });
+    // @ts-expect-error Ancestor projection does not expose child-only Properties.
+    resource.body;
+    const document = page.refine(resource, Work.classes.Document);
+    const body = document?.body;
+    const detached = QueryAST.decode(query);
+    // @ts-expect-error Decoding destroys the authoring Class provenance required for rich projection.
+    await binding.query(detached, { page: { size: 10 } });
+    const multipleClasses = Query.from({
+        nodes: [Work.classes.Resource, Work.classes.Document],
+    }).select({ kind: 'nodes', projection: { kind: 'value' } });
+    // @ts-expect-error Multiple Class terms do not establish one rich selected-Class contract.
+    await binding.query(multipleClasses, { page: { size: 10 } });
+    const mixedSource = Query.from({
+        nodes: [NodeId('document'), Work.classes.Resource],
+    }).select({ kind: 'nodes', projection: { kind: 'value' } });
+    // @ts-expect-error Path and Class terms do not establish one rich selected-Class contract.
+    await binding.query(mixedSource, { page: { size: 10 } });
+    const detachedRefSource = Query.from({ nodes: [Work.classes.Resource.ref] }).select({
+        kind: 'nodes',
+        projection: { kind: 'value' },
+    });
+    // @ts-expect-error A ClassRef has no resolved schema witness for rich projection.
+    await binding.query(detachedRefSource, { page: { size: 10 } });
+    const detachedKeySource = Query.from({ nodes: [Work.classes.Resource.key] }).select({
+        kind: 'nodes',
+        projection: { kind: 'value' },
+    });
+    // @ts-expect-error A ClassKey has no resolved schema witness for rich projection.
+    await binding.query(detachedKeySource, { page: { size: 10 } });
+    const prototypePage = await binding.query(prototypeQuery, { page: { size: 1 } });
+    const prototype = prototypePage.nodes[0];
+    const toString = prototype.toString;
+    const constructed = await prototype.constructor('input');
+    const structural = Path.project(Work.classes.Resource.ref).raw;
+    await graph.get(structural);
+    await graph.getOrThrow(structural);
+    await graph.neighbors(structural, Work.classes.Related, {
+        direction: 'outgoing',
+        page: { size: 1 },
+    });
+    const exact = NodeId('document');
+    await graph.get(exact);
+    await graph.getOrThrow(exact);
+    await graph.neighbors(exact, Work.classes.Related, {
+        direction: 'outgoing',
+        page: { size: 1 },
+    });
+    // @ts-expect-error Neighbor traversal requires Edge Classes, not Node Classes.
+    await graph.neighbors(exact, Work.classes.Resource, {
+        direction: 'outgoing',
+        page: { size: 1 },
+    });
+    return { title, renamed, body, toString, constructed };
+}
+void typeProof;

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

@@ -0,0 +1,3 @@
+export type { DomainBinding, DomainQueryOptions } from './binding.js';
+export type { BoundEdge, BoundGraphValue, BoundNode, BoundNodeFor } from './model.js';
+export type { BoundEdgePage, BoundNodePage, BoundQueryPage } from './page.js';

package/dist/graph/domain/index.js

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

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

@@ -0,0 +1,18 @@
+import type { Edge } from '@astrale-os/kernel-core/graph/edge';
+import type { Node } from '@astrale-os/kernel-core/graph/node';
+import type { DefinitionKey, Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { AnyResolvedClass, BoundMethodShortcutsOf, ClassSatisfactionKeysOf, MethodAccessOf, PropertyAccessOf, PropertyShortcutsOf, ResolvedClass } from '@astrale-os/kernel-dsl/v1/language';
+import type { Binary } from '../../client/index.js';
+type NodeReserved = keyof Node | 'property' | 'method';
+type EdgeReserved = keyof Edge | 'property';
+declare const BOUND_CLASS: unique symbol;
+/** Node evidence selected as one exact Class key, without duplicating its rich projection. */
+export type BoundNodeFor<ClassKey extends DefinitionKey<Key.Origin, 'class'> = DefinitionKey<Key.Origin, 'class'>> = Node & {
+    readonly [BOUND_CLASS]: Readonly<Record<ClassKey, true>>;
+};
+/** One selected-Class view over an exact admitted Node. */
+export type BoundNode<Class extends ResolvedClass<'node'> = ResolvedClass<'node'>, BinaryValue = Binary> = BoundNodeFor<ClassSatisfactionKeysOf<Class>> & PropertyShortcutsOf<Class, NodeReserved> & BoundMethodShortcutsOf<Class, BinaryValue, NodeReserved> & PropertyAccessOf<Class> & MethodAccessOf<Class, BinaryValue>;
+/** One selected-Class view over an exact admitted Edge. */
+export type BoundEdge<Class extends ResolvedClass<'edge'> = ResolvedClass<'edge'>> = Edge & PropertyShortcutsOf<Class, EdgeReserved> & PropertyAccessOf<Class>;
+export type BoundGraphValue<Class extends AnyResolvedClass> = Class extends ResolvedClass<'node'> ? BoundNode<Class> : Class extends ResolvedClass<'edge'> ? BoundEdge<Class> : never;
+export {};

package/dist/graph/domain/model.js

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

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

@@ -0,0 +1,23 @@
+import type { Edge } from '@astrale-os/kernel-core/graph/edge';
+import type { Node } from '@astrale-os/kernel-core/graph/node';
+import type { QueryAST, QueryEdgeGraphResult, QueryEdgeResult, QueryNodeGraphResult, QueryNodeResult, QueryResultFor, QuerySingleSourceClassOf } from '@astrale-os/kernel-core/graph/query';
+import type { AnyResolvedClass, ResolvedClass } from '@astrale-os/kernel-dsl/v1/language';
+import type { QueryResponse } from '../page-contract.js';
+import type { BoundEdge, BoundNode } from './model.js';
+type SourceClass<Query> = Extract<QuerySingleSourceClassOf<Query>, AnyResolvedClass>;
+export interface BoundNodePage<Query extends QueryAST = QueryAST, Class extends ResolvedClass<'node'> = Extract<SourceClass<Query>, ResolvedClass<'node'>>> {
+    readonly nodes: readonly BoundNode<Class>[];
+    readonly raw: QueryResponse<QueryResultFor<Query>>;
+    readonly next?: () => Promise<BoundNodePage<Query, Class>>;
+    refine<Target extends ResolvedClass<'node'>>(value: BoundNode<Class>, target: Target): BoundNode<Target> | undefined;
+}
+export interface BoundEdgePage<Query extends QueryAST = QueryAST, Class extends ResolvedClass<'edge'> = Extract<SourceClass<Query>, ResolvedClass<'edge'>>> {
+    readonly edges: readonly BoundEdge<Class>[];
+    readonly raw: QueryResponse<QueryResultFor<Query>>;
+    readonly next?: () => Promise<BoundEdgePage<Query, Class>>;
+    refine<Target extends ResolvedClass<'edge'>>(value: BoundEdge<Class>, target: Target): BoundEdge<Target> | undefined;
+}
+export type BoundQueryPage<Query extends QueryAST> = QueryResultFor<Query> extends QueryNodeGraphResult | QueryNodeResult ? BoundNodePage<Query> : QueryResultFor<Query> extends QueryEdgeGraphResult | QueryEdgeResult ? BoundEdgePage<Query> : never;
+export declare function selectedNodes(response: QueryResponse): readonly Node[];
+export declare function selectedEdges(response: QueryResponse): readonly Edge[];
+export {};

package/dist/graph/domain/page.js

@@ -0,0 +1,42 @@
+import { edgeKeyOf, equalEdgeKeys } from '@astrale-os/kernel-core/graph/edge';
+export function selectedNodes(response) {
+    const result = response.result;
+    if (result.kind === 'graph') {
+        if (result.selection.kind !== 'node')
+            throw new TypeError('Query did not select Nodes.');
+        const byId = new Map(result.graph.nodes.map((node) => [node.id, node]));
+        return result.selection.ids.map((id) => {
+            const node = byId.get(id);
+            if (node === undefined)
+                throw new TypeError(`Selected Node ${id} is absent.`);
+            return node;
+        });
+    }
+    if (result.kind !== 'nodes')
+        throw new TypeError('Query did not select Nodes.');
+    return result.nodes.map((item) => {
+        if (item.kind !== 'value')
+            throw new TypeError('Rich Node queries require value projection.');
+        return item.value;
+    });
+}
+export function selectedEdges(response) {
+    const result = response.result;
+    if (result.kind === 'graph') {
+        if (result.selection.kind !== 'edge')
+            throw new TypeError('Query did not select Edges.');
+        return result.selection.keys.map((key) => {
+            const edge = result.graph.edges.find((candidate) => equalEdgeKeys(edgeKeyOf(candidate), key));
+            if (edge === undefined)
+                throw new TypeError('Selected Edge is absent.');
+            return edge;
+        });
+    }
+    if (result.kind !== 'edges')
+        throw new TypeError('Query did not select Edges.');
+    return result.edges.map((item) => {
+        if (item.edge.kind !== 'value')
+            throw new TypeError('Rich Edge queries require value projection.');
+        return item.edge.value;
+    });
+}

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

@@ -0,0 +1,8 @@
+import type { Edge } from '@astrale-os/kernel-core/graph/edge';
+import type { Node } from '@astrale-os/kernel-core/graph/node';
+import type { ResolvedClass, ResolvedMethod } from '@astrale-os/kernel-dsl/v1/language';
+import type { BoundEdge, BoundNode } from './model.js';
+import type { QueryProvenance } from './provenance.js';
+export type MethodCall = (node: Node, method: ResolvedMethod, input: unknown) => Promise<unknown>;
+export declare function projectNode<Class extends ResolvedClass<'node'>>(selected: Class, node: Node, provenance: QueryProvenance, call: MethodCall): BoundNode<Class>;
+export declare function projectEdge<Class extends ResolvedClass<'edge'>>(selected: Class, edge: Edge, provenance: QueryProvenance): BoundEdge<Class>;