@astrale-os/sdk 0.5.0-beta.64 → 0.5.0-beta.65

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.5.0-beta.65](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.64...sdk-v0.5.0-beta.65) (2026-08-27)
+
+
+### Features
+
+* **query:** add portable collection unions ([#291](https://github.com/astrale-os/sdk/issues/291)) ([1ea53bc](https://github.com/astrale-os/sdk/commit/1ea53bcf4767ae5adb9637a5942e674d839fb231))
+
+
+### Bug Fixes
+
+* document safe remote route refresh ([#298](https://github.com/astrale-os/sdk/issues/298)) ([bd0d9b4](https://github.com/astrale-os/sdk/commit/bd0d9b479b61ba5007fed3abd30e7aeee1035df4))
+
 ## [0.5.0-beta.64](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.63...sdk-v0.5.0-beta.64) (2026-08-27)
 
 

package/dist/application/query/collection/identity.d.ts

@@ -0,0 +1,4 @@
+import type { Edge } from '../../../platform/graph/edge/index.js';
+import type { Node } from '../../../platform/graph/node/index.js';
+export declare function collectionIdentityOf(value: Node | Edge): string;
+export declare function requireUniqueCollectionValues<Value extends Node | Edge>(values: readonly Value[], context: string): readonly Value[];

package/dist/application/query/collection/identity.js

@@ -0,0 +1,15 @@
+import { edgeKeyOf, encodeEdgeKey } from '@astrale-os/kernel-core/graph/edge';
+export function collectionIdentityOf(value) {
+    return 'id' in value ? `node:${value.id}` : `edge:${encodeEdgeKey(edgeKeyOf(value))}`;
+}
+export function requireUniqueCollectionValues(values, context) {
+    const identities = new Set();
+    for (const value of values) {
+        const identity = collectionIdentityOf(value);
+        if (identities.has(identity)) {
+            throw new TypeError(`${context} returned duplicate identity ${identity}.`);
+        }
+        identities.add(identity);
+    }
+    return values;
+}

package/dist/application/query/collection/limits.d.ts

@@ -0,0 +1,5 @@
+export declare const COLLECTION_QUERY_LIMITS: Readonly<{
+    pageSize: 256;
+    maximumPages: 1024;
+    maximumLogicalAssignments: 262144;
+}>;

package/dist/application/query/collection/limits.js

@@ -0,0 +1,5 @@
+export const COLLECTION_QUERY_LIMITS = Object.freeze({
+    pageSize: 256,
+    maximumPages: 1_024,
+    maximumLogicalAssignments: 262_144,
+});

package/dist/application/query/collection/metadata.d.ts

@@ -0,0 +1,11 @@
+import type { AnyResolvedClass } from '@astrale-os/kernel-dsl/v1';
+import type { Domain } from '../../../platform/schema/index.js';
+export interface CollectionQuerySpec<Class extends AnyResolvedClass = AnyResolvedClass> {
+    readonly id: string;
+    readonly class: Class;
+}
+type CollectionProject = (domain: Domain) => CollectionQuerySpec;
+export declare function registerCollectionQuery(definition: object, project: CollectionProject): void;
+export declare function isCollectionQueryDefinition(definition: unknown): definition is object;
+export declare function realizeCollectionQuery(definition: object, domain: Domain, memberPath?: string): CollectionQuerySpec;
+export {};

package/dist/application/query/collection/metadata.js

@@ -0,0 +1,62 @@
+const projects = new WeakMap();
+const specifications = new WeakMap();
+export function registerCollectionQuery(definition, project) {
+    if (projects.has(definition))
+        throw new TypeError('Collection Query is already registered.');
+    projects.set(definition, project);
+}
+export function isCollectionQueryDefinition(definition) {
+    return definition !== null && typeof definition === 'object' && projects.has(definition);
+}
+export function realizeCollectionQuery(definition, domain, memberPath = 'Collection Query') {
+    const cached = specifications.get(definition)?.get(domain);
+    if (cached !== undefined)
+        return cached;
+    const project = projects.get(definition);
+    if (project === undefined) {
+        invalid(`${memberPath} is not a registered collection Query definition.`);
+    }
+    const authored = project(domain);
+    if (isPromiseLike(authored))
+        invalid(`${memberPath} projection must be synchronous.`);
+    if (!isExactSpec(authored))
+        invalid(`${memberPath} specification is invalid.`);
+    if (domain.definition(authored.class.key) !== authored.class) {
+        invalid(`${memberPath} selected a Class outside its Domain closure.`);
+    }
+    const admitted = Object.freeze({ id: authored.id, class: authored.class });
+    let byDomain = specifications.get(definition);
+    if (byDomain === undefined) {
+        byDomain = new WeakMap();
+        specifications.set(definition, byDomain);
+    }
+    byDomain.set(domain, admitted);
+    return admitted;
+}
+function isExactSpec(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        return false;
+    const keys = Reflect.ownKeys(input);
+    if (keys.length !== 2 ||
+        !Object.hasOwn(input, 'id') ||
+        !Object.hasOwn(input, 'class') ||
+        typeof Reflect.get(input, 'id') !== 'string' ||
+        Reflect.get(input, 'id').length === 0 ||
+        Reflect.get(input, 'id').trim() !== Reflect.get(input, 'id')) {
+        return false;
+    }
+    const selected = Reflect.get(input, 'class');
+    return (selected !== null &&
+        typeof selected === 'object' &&
+        Reflect.get(selected, 'ref') !== undefined &&
+        Reflect.get(Reflect.get(selected, 'ref'), 'kind') === 'class' &&
+        (Reflect.get(selected, 'kind') === 'node' || Reflect.get(selected, 'kind') === 'edge'));
+}
+function isPromiseLike(input) {
+    return (input !== null &&
+        (typeof input === 'object' || typeof input === 'function') &&
+        typeof input.then === 'function');
+}
+function invalid(message) {
+    throw new TypeError(message);
+}

package/dist/application/query/collection/union.d.ts

@@ -0,0 +1,19 @@
+import type { QueryAST } from '@astrale-os/kernel-core/graph/query';
+import type { AnyResolvedClass } from '@astrale-os/kernel-dsl/v1';
+import type { Edge } from '../../../platform/graph/edge/index.js';
+import type { Node } from '../../../platform/graph/node/index.js';
+import type { Domain } from '../../../platform/schema/index.js';
+export type CollectionDefinitionRecord = Readonly<Record<string, object>>;
+export interface CollectionUnionMember {
+    readonly name: string;
+    readonly id: string;
+    readonly class: AnyResolvedClass;
+}
+export interface CompiledCollectionUnion {
+    readonly ast: QueryAST;
+    readonly kind: 'node' | 'edge';
+    readonly members: readonly CollectionUnionMember[];
+}
+export declare function admitCollectionDefinitions(definitions: unknown): readonly (readonly [string, object])[];
+export declare function compileCollectionUnion(domain: Domain, definitions: CollectionDefinitionRecord, outputPath: readonly string[]): CompiledCollectionUnion;
+export declare function partitionCollectionUnion(domain: Domain, compiled: CompiledCollectionUnion, values: readonly (Node | Edge)[], maximumLogicalAssignments?: number): Readonly<Record<string, readonly (Node | Edge)[]>>;

package/dist/application/query/collection/union.js

@@ -0,0 +1,157 @@
+import { Query, QueryAST as QueryDocument } from '@astrale-os/kernel-core/graph/query';
+import { ClassKey } from '@astrale-os/kernel-dsl/v1/addressing';
+import { QueryCompositionError } from '../composite/errors.js';
+import { collectionIdentityOf } from './identity.js';
+import { COLLECTION_QUERY_LIMITS } from './limits.js';
+import { isCollectionQueryDefinition, realizeCollectionQuery, } from './metadata.js';
+export function admitCollectionDefinitions(definitions) {
+    if (!isPlainRecord(definitions))
+        invalid('Collection union must be a plain record.');
+    const keys = Reflect.ownKeys(definitions);
+    if (keys.length < 2)
+        invalid('Collection union requires at least two members.');
+    if (keys.some((key) => typeof key !== 'string' ||
+        key.length === 0 ||
+        key.trim() !== key ||
+        Object.getOwnPropertyDescriptor(definitions, key)?.enumerable !== true)) {
+        invalid('Collection union members must be own enumerable non-empty string keys.');
+    }
+    return Object.freeze(keys.map((name) => {
+        if (typeof name !== 'string')
+            invalid('Collection union member key is invalid.');
+        const definition = definitions[name];
+        if (!isCollectionQueryDefinition(definition)) {
+            invalid(`${name} is not a collection Query definition.`);
+        }
+        return Object.freeze([name, definition]);
+    }));
+}
+export function compileCollectionUnion(domain, definitions, outputPath) {
+    const realized = admitCollectionDefinitions(definitions).map(([name, definition]) => ({
+        name,
+        specification: realizeMember(definition, domain, outputPath, name),
+    }));
+    if (realized.length > QueryDocument.limits.sourceTerms) {
+        limit(`${pathOf(outputPath)} has ${realized.length} collection members; maximum is ${QueryDocument.limits.sourceTerms}.`);
+    }
+    const ids = new Map();
+    const classes = new Map();
+    for (const { name, specification } of realized) {
+        const memberPath = pathOf(outputPath, name);
+        const priorId = ids.get(specification.id);
+        if (priorId !== undefined) {
+            invalid(`${memberPath} duplicates Query ID selected by ${priorId}.`);
+        }
+        ids.set(specification.id, memberPath);
+        const priorClass = classes.get(specification.class.key);
+        if (priorClass !== undefined) {
+            invalid(`${memberPath} duplicates Class selected by ${priorClass}.`);
+        }
+        classes.set(specification.class.key, memberPath);
+    }
+    const first = realized[0];
+    const kind = first.specification.class.kind;
+    const mismatched = realized.find(({ specification }) => specification.class.kind !== kind);
+    if (mismatched !== undefined) {
+        invalid(`${pathOf(outputPath, mismatched.name)} selected an ${mismatched.specification.class.kind} Class; expected ${kind} selected by ${pathOf(outputPath, first.name)}.`);
+    }
+    const selected = realized
+        .map(({ specification }) => specification.class)
+        .sort((left, right) => (left.key < right.key ? -1 : left.key > right.key ? 1 : 0));
+    const ast = kind === 'node'
+        ? nodeUnion(selected)
+        : edgeUnion(selected);
+    return Object.freeze({
+        ast,
+        kind,
+        members: Object.freeze(realized.map(({ name, specification }) => Object.freeze({ name, id: specification.id, class: specification.class }))),
+    });
+}
+export function partitionCollectionUnion(domain, compiled, values, maximumLogicalAssignments = COLLECTION_QUERY_LIMITS.maximumLogicalAssignments) {
+    if (!Number.isSafeInteger(maximumLogicalAssignments) || maximumLogicalAssignments < 1) {
+        limit('Collection union logical-assignment bound is invalid.');
+    }
+    const accepted = Object.fromEntries(compiled.members.map(({ name }) => [name, []]));
+    const memberships = new Map();
+    const identities = new Set();
+    let assignments = 0;
+    for (const value of values) {
+        const identity = collectionIdentityOf(value);
+        if (identities.has(identity))
+            invalid(`Collection union returned duplicate identity ${identity}.`);
+        identities.add(identity);
+        const names = memberships.get(value.class) ?? memberNames(domain, compiled, value);
+        memberships.set(value.class, names);
+        if (names.length === 0) {
+            invalid(`Collection union returned ${value.class} outside every member extent.`);
+        }
+        assignments += names.length;
+        if (assignments > maximumLogicalAssignments) {
+            limit(`Collection union exceeded ${maximumLogicalAssignments} logical assignments.`);
+        }
+        for (const name of names)
+            accepted[name].push(value);
+    }
+    return Object.freeze(Object.fromEntries(Object.entries(accepted).map(([name, members]) => [name, Object.freeze(members)])));
+}
+function realizeMember(definition, domain, outputPath, name) {
+    try {
+        return realizeCollectionQuery(definition, domain, pathOf(outputPath, name));
+    }
+    catch (cause) {
+        if (cause instanceof QueryCompositionError)
+            throw cause;
+        throw new QueryCompositionError('QUERY_COMPOSITION_INVALID', cause instanceof Error ? cause.message : `${pathOf(outputPath, name)} realization failed.`);
+    }
+}
+function memberNames(domain, compiled, value) {
+    const exact = domain.definition(ClassKey.ref(ClassKey(value.class)));
+    const kind = valueKind(value);
+    if (exact?.ref.kind !== 'class' || exact.kind !== kind || exact.abstract) {
+        invalid(`Collection union returned inactive ${kind} Class ${value.class}.`);
+    }
+    const names = compiled.members.flatMap((member) => {
+        const satisfies = exact.kind === 'node'
+            ? member.class.kind === 'node' && exact.satisfies(member.class)
+            : member.class.kind === 'edge' && exact.satisfies(member.class);
+        return satisfies ? [member.name] : [];
+    });
+    return Object.freeze(names);
+}
+function nodeUnion(selected) {
+    const [first, second, ...rest] = selected;
+    if (first === undefined || second === undefined)
+        invalid('Node collection union is undersized.');
+    return Query.from({ nodes: [first, second, ...rest] }).select({
+        kind: 'nodes',
+        projection: { kind: 'value' },
+    });
+}
+function edgeUnion(selected) {
+    const [first, second, ...rest] = selected;
+    if (first === undefined || second === undefined)
+        invalid('Edge collection union is undersized.');
+    return Query.from({ edges: [first, second, ...rest] }).select({
+        kind: 'edges',
+        projection: { edge: 'value', source: 'reference', target: 'reference' },
+    });
+}
+function valueKind(value) {
+    return 'id' in value ? 'node' : 'edge';
+}
+function pathOf(path, member) {
+    const parts = member === undefined ? path : [...path, member];
+    return parts.length === 0 ? 'collection union' : parts.join('.');
+}
+function isPlainRecord(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        return false;
+    const prototype = Object.getPrototypeOf(input);
+    return prototype === Object.prototype || prototype === null;
+}
+function invalid(message) {
+    throw new QueryCompositionError('QUERY_COMPOSITION_INVALID', message);
+}
+function limit(message) {
+    throw new QueryCompositionError('QUERY_COMPOSITION_LIMIT', message);
+}

package/dist/application/query/composite/builder.d.ts

@@ -1,4 +1,5 @@
 import type { Domain } from '../../../platform/schema/index.js';
+import type { CollectionDefinitionRecord } from '../collection/union.js';
 import type { SingleQueryDefinition } from '../query.js';
 import type { QueryComposition, QueryPlan } from './query.js';
 declare const PLAN: unique symbol;
@@ -19,7 +20,12 @@ export interface CombinedPlan {
     readonly key: number;
     readonly plans: Readonly<Record<string, InternalPlan>>;
 }
-export type PlanNode = LeafPlan | CombinedPlan;
+export interface UnionPlan {
+    readonly kind: 'union';
+    readonly key: number;
+    readonly definitions: CollectionDefinitionRecord;
+}
+export type PlanNode = LeafPlan | CombinedPlan | UnionPlan;
 export interface InternalPlan extends QueryPlan<unknown> {
     readonly [PLAN]: Readonly<{
         token: object;

package/dist/application/query/composite/builder.js

@@ -1,3 +1,4 @@
+import { admitCollectionDefinitions } from '../collection/union.js';
 import { QueryCompositionError } from './errors.js';
 const PLAN = Symbol('astrale.sdk.query.plan');
 const REFERENCE = Symbol('astrale.sdk.query.reference');
@@ -21,6 +22,12 @@ export function createQueryComposition() {
                 input,
             }));
         },
+        union(definitions) {
+            requireOpen(open);
+            const entries = admitCollectionDefinitions(definitions);
+            const accepted = Object.freeze(Object.fromEntries(entries));
+            return createPlan(token, Object.freeze({ kind: 'union', key: nextKey++, definitions: accepted }));
+        },
         combine(plans) {
             requireOpen(open);
             if (!isPlainRecord(plans) || Object.keys(plans).length === 0) {

package/dist/application/query/composite/plan.d.ts

@@ -1,9 +1,24 @@
 import type { Domain } from '../../../platform/schema/index.js';
+import type { CollectionDefinitionRecord } from '../collection/union.js';
 import type { SingleQueryDefinition } from '../query.js';
 import type { InternalPlan } from './builder.js';
+export declare const QUERY_COMPOSITION_LIMITS: Readonly<{
+    maximumPhysicalQueries: 32;
+    maximumDependencyDepth: 8;
+}>;
 export interface QueryPlanAnalysis {
+    /** @deprecated Use physicalQueries. */
     readonly queries: number;
+    /** @deprecated Use dependencyDepth. */
     readonly depth: number;
+    readonly logicalQueries: number;
+    readonly physicalQueries: number;
+    readonly dependencyDepth: number;
+    readonly maximumLogicalAssignments: number;
+    readonly unionGroups: readonly {
+        readonly outputPath: readonly string[];
+        readonly members: number;
+    }[];
 }
 export declare function analyzeQueryPlan(plan: InternalPlan): QueryPlanAnalysis;
-export declare function executeQueryPlan(plan: InternalPlan, run: (definition: SingleQueryDefinition<Domain, unknown, unknown>, input: unknown) => Promise<unknown>): Promise<unknown>;
+export declare function executeQueryPlan(plan: InternalPlan, run: (definition: SingleQueryDefinition<Domain, unknown, unknown>, input: unknown) => Promise<unknown>, runUnion: (definitions: CollectionDefinitionRecord, outputPath: readonly string[]) => Promise<unknown>): Promise<unknown>;

package/dist/application/query/composite/plan.js

@@ -1,12 +1,17 @@
+import { COLLECTION_QUERY_LIMITS } from '../collection/limits.js';
 import { inspectPlan, referencesIn, resolveInput } from './builder.js';
 import { QueryCompositionError } from './errors.js';
-const MAX_QUERIES = 32;
-const MAX_DEPTH = 8;
+export const QUERY_COMPOSITION_LIMITS = Object.freeze({
+    maximumPhysicalQueries: 32,
+    maximumDependencyDepth: 8,
+});
 export function analyzeQueryPlan(plan) {
-    const leafKeys = new Set();
+    const physicalKeys = new Set();
+    const logicalByKey = new Map();
     const visiting = new Set();
     const depths = new Map();
-    const depth = (candidate) => {
+    const unionGroups = [];
+    const depth = (candidate, outputPath = []) => {
         const { node } = inspectPlan(candidate);
         const cached = depths.get(node.key);
         if (cached !== undefined)
@@ -16,36 +21,60 @@ export function analyzeQueryPlan(plan) {
         visiting.add(node.key);
         let value;
         if (node.kind === 'combine') {
-            value = Math.max(...Object.values(node.plans).map(depth));
+            value = Math.max(...Object.entries(node.plans).map(([name, child]) => depth(child, [...outputPath, name])));
+        }
+        else if (node.kind === 'union') {
+            physicalKeys.add(node.key);
+            const members = Object.keys(node.definitions).length;
+            logicalByKey.set(node.key, members);
+            unionGroups.push(Object.freeze({ outputPath: Object.freeze([...outputPath]), members }));
+            value = 1;
         }
         else {
-            leafKeys.add(node.key);
+            physicalKeys.add(node.key);
+            logicalByKey.set(node.key, 1);
             const dependencies = referencesIn(node.input).map((reference) => reference.plan);
-            value = 1 + (dependencies.length === 0 ? 0 : Math.max(...dependencies.map(depth)));
+            value =
+                1 +
+                    (dependencies.length === 0
+                        ? 0
+                        : Math.max(...dependencies.map((dependency) => depth(dependency))));
         }
         visiting.delete(node.key);
         depths.set(node.key, value);
         return value;
     };
     const maximumDepth = depth(plan);
-    if (leafKeys.size < 2)
-        invalid('Composite Query must contain at least two leaves.');
-    if (leafKeys.size > MAX_QUERIES || maximumDepth > MAX_DEPTH) {
-        throw new QueryCompositionError('QUERY_COMPOSITION_LIMIT', `Composite Query exceeds ${MAX_QUERIES} leaves or dependency depth ${MAX_DEPTH}.`);
+    const logicalQueries = [...logicalByKey.values()].reduce((total, count) => total + count, 0);
+    if (logicalQueries < 2)
+        invalid('Composite Query must contain at least two logical Queries.');
+    if (physicalKeys.size > QUERY_COMPOSITION_LIMITS.maximumPhysicalQueries ||
+        maximumDepth > QUERY_COMPOSITION_LIMITS.maximumDependencyDepth) {
+        throw new QueryCompositionError('QUERY_COMPOSITION_LIMIT', `Composite Query exceeds ${QUERY_COMPOSITION_LIMITS.maximumPhysicalQueries} physical Queries or dependency depth ${QUERY_COMPOSITION_LIMITS.maximumDependencyDepth}.`);
     }
-    return Object.freeze({ queries: leafKeys.size, depth: maximumDepth });
+    return Object.freeze({
+        queries: physicalKeys.size,
+        depth: maximumDepth,
+        logicalQueries,
+        physicalQueries: physicalKeys.size,
+        dependencyDepth: maximumDepth,
+        maximumLogicalAssignments: COLLECTION_QUERY_LIMITS.maximumLogicalAssignments,
+        unionGroups: Object.freeze(unionGroups),
+    });
 }
-export async function executeQueryPlan(plan, run) {
+export async function executeQueryPlan(plan, run, runUnion) {
     analyzeQueryPlan(plan);
     const results = new Map();
-    const execute = (candidate) => {
+    const execute = (candidate, outputPath = []) => {
         const { node } = inspectPlan(candidate);
         const existing = results.get(node.key);
         if (existing !== undefined)
             return existing;
         const pending = node.kind === 'combine'
-            ? Promise.all(Object.entries(node.plans).map(async ([name, child]) => [name, await execute(child)])).then((entries) => Object.freeze(Object.fromEntries(entries)))
-            : resolveInput(node.input, execute).then((input) => run(node.definition, input));
+            ? Promise.all(Object.entries(node.plans).map(async ([name, child]) => [name, await execute(child, [...outputPath, name])])).then((entries) => Object.freeze(Object.fromEntries(entries)))
+            : node.kind === 'union'
+                ? runUnion(node.definitions, outputPath)
+                : resolveInput(node.input, (dependency) => execute(dependency)).then((input) => run(node.definition, input));
         results.set(node.key, pending);
         return pending;
     };

package/dist/application/query/composite/query.d.ts

@@ -1,5 +1,6 @@
+import type { ResolvedClass } from '@astrale-os/kernel-dsl/v1';
 import type { Domain } from '../../../platform/schema/index.js';
-import type { SingleQueryDefinition } from '../query.js';
+import type { CollectionQueryDefinition, QueryOutputOf, SingleQueryDefinition } from '../query.js';
 import type { QueryLifecycle } from '../single/index.js';
 declare const QUERY_PLAN_OUTPUT: unique symbol;
 declare const QUERY_PLAN_VALUE: unique symbol;
@@ -16,8 +17,15 @@ export interface QueryPlan<Output> {
     readonly value: QueryPlanValue<Output>;
 }
 export type QueryPlanOutput<Plan extends QueryPlan<unknown>> = Plan[typeof QUERY_PLAN_OUTPUT];
+type CollectionOutputs<Definitions extends Readonly<Record<string, unknown>>> = Readonly<{
+    [Name in Extract<keyof Definitions, string>]: QueryOutputOf<Definitions[Name]>;
+}>;
+type StringOwnKeys<Definitions> = Record<Exclude<keyof Definitions, string>, never>;
 export interface QueryComposition<DomainValue extends Domain = Domain> {
-    query<Input, Output>(id: string, definition: SingleQueryDefinition<DomainValue, Input, Output>, input: QueryPlanInput<Input>): QueryPlan<Output>;
+    query<Output>(id: string, query: SingleQueryDefinition<DomainValue, void, Output>): QueryPlan<Output>;
+    query<Input, Output>(id: string, query: SingleQueryDefinition<DomainValue, Input, Output>, input: QueryPlanInput<Input>): QueryPlan<Output>;
+    union<const Definitions extends Readonly<Record<string, CollectionQueryDefinition<DomainValue, ResolvedClass<'node'>>>>>(definitions: Definitions & StringOwnKeys<Definitions>): QueryPlan<CollectionOutputs<Definitions>>;
+    union<const Definitions extends Readonly<Record<string, CollectionQueryDefinition<DomainValue, ResolvedClass<'edge'>>>>>(definitions: Definitions & StringOwnKeys<Definitions>): QueryPlan<CollectionOutputs<Definitions>>;
     combine<const Plans extends Readonly<Record<string, QueryPlan<unknown>>>>(plans: Plans): QueryPlan<{
         readonly [Name in keyof Plans]: QueryPlanOutput<Plans[Name]>;
     }>;

package/dist/application/query/define.d.ts

@@ -1,8 +1,10 @@
 import type { QueryAST } from '@astrale-os/kernel-core/graph/query';
+import type { AnyResolvedClass } from '@astrale-os/kernel-dsl/v1';
 import type { Domain, schema } from '../../platform/schema/index.js';
-import type { ProjectedCompositeQuery, RawCompositeQuery } from './composite/index.js';
-import type { CompositeQueryDefinition, QueryDefinition, RealizedQuery, SingleQueryDefinition } from './query.js';
+import type { ProjectedCompositeQuery, QueryComposition, QueryPlan, QueryPlanOutput, RawCompositeQuery } from './composite/index.js';
+import type { CompositeQueryDefinition, CollectionQueryDefinition, QueryDefinition, RealizedQuery, SingleQueryDefinition } from './query.js';
 import type { PaginatedQuery, ProjectedQuery, RawQuery, SingleQuery } from './single/index.js';
+import { type CollectionQuerySpec } from './collection/metadata.js';
 type AuthoredRaw<Input, Ast extends QueryAST> = Omit<RawQuery<Input, Ast>, 'kind' | 'page'> & {
     readonly page?: {
         readonly size: number;
@@ -24,13 +26,23 @@ interface SingleQueryProjector<Schema extends schema.DomainSchema> {
     <Input, Output, Ast extends QueryAST>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredProjected<Input, Output, Ast>): SingleQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
     <Input, Output, Ast extends QueryAST>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredPaginated<Input, Output, Ast>): SingleQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
 }
+interface CollectionQueryProjector<Schema extends schema.DomainSchema> {
+    <Class extends AnyResolvedClass>(project: (domain: ResolvedDomainOf<Schema>) => CollectionQuerySpec<Class>): CollectionQueryDefinition<ResolvedDomainOf<Schema>, Class>;
+}
+type AuthoredInferredComposite<Input, Composed, Plan extends QueryPlan<unknown>, Output, DomainValue extends Domain> = Omit<ProjectedCompositeQuery<Input, Composed, Output, DomainValue>, 'kind' | 'compose' | 'project'> & {
+    compose(builder: QueryComposition<DomainValue>, input: Input): Plan;
+    project(value: QueryPlanOutput<Plan>, input: Input): Output;
+};
 interface CompositeQueryProjector<Schema extends schema.DomainSchema> {
+    <Plan extends QueryPlan<unknown>, Output>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredInferredComposite<void, QueryPlanOutput<Plan>, Plan, Output, ResolvedDomainOf<Schema>>): CompositeQueryDefinition<ResolvedDomainOf<Schema>, void, Output>;
     <Input, Output>(project: (domain: ResolvedDomainOf<Schema>) => Omit<RawCompositeQuery<Input, Output, ResolvedDomainOf<Schema>>, 'kind'>): CompositeQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
-    <Input, Composed, Output>(project: (domain: ResolvedDomainOf<Schema>) => Omit<ProjectedCompositeQuery<Input, Composed, Output, ResolvedDomainOf<Schema>>, 'kind'>): CompositeQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
+    <Input, Composed, Output, Plan extends QueryPlan<Composed> = QueryPlan<Composed>>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredInferredComposite<Input, Composed, Plan, Output, ResolvedDomainOf<Schema>>): CompositeQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
 }
 /** Define one inert single Query recipe projected from its exact loaded Domain. */
 export declare function defineQuery<Schema extends schema.DomainSchema>(): SingleQueryProjector<Schema>;
+/** Define one reusable complete polymorphic Class-extent Query. */
+export declare function defineCollectionQuery<Schema extends schema.DomainSchema>(): CollectionQueryProjector<Schema>;
 /** Define one inert composite Query recipe projected from its exact loaded Domain. */
 export declare function defineCompositeQuery<Schema extends schema.DomainSchema>(): CompositeQueryProjector<Schema>;
-export declare function realizeQuery<DomainValue extends Domain, Input, Output>(definition: QueryDefinition<DomainValue, Input, Output>, domain: DomainValue): RealizedQuery<Input, Output>;
+export declare function realizeQuery<DomainValue extends Domain, Input, Output>(query: QueryDefinition<DomainValue, Input, Output>, domain: DomainValue): RealizedQuery<Input, Output>;
 export {};

package/dist/application/query/define.js

@@ -1,4 +1,9 @@
+import { Query } from '@astrale-os/kernel-core/graph/query';
 import { isDomain } from '@astrale-os/kernel-dsl/v1/domain';
+import { requireUniqueCollectionValues } from './collection/identity.js';
+import { COLLECTION_QUERY_LIMITS } from './collection/limits.js';
+import { realizeCollectionQuery, registerCollectionQuery, } from './collection/metadata.js';
+import { queryResult } from './single/index.js';
 const DEFAULT_PAGE_SIZE = 256;
 const MAXIMUM_PAGES = 1_024;
 const projectors = new WeakMap();
@@ -7,27 +12,65 @@ const realized = new WeakMap();
 export function defineQuery() {
     return ((project) => recipe('query', project));
 }
+/** Define one reusable complete polymorphic Class-extent Query. */
+export function defineCollectionQuery() {
+    return ((project) => {
+        const definition = defineQuery()((domain) => {
+            const specification = realizeCollectionQuery(definition, domain);
+            const selected = specification.class;
+            if (selected.kind === 'node') {
+                return {
+                    id: specification.id,
+                    page: { size: COLLECTION_QUERY_LIMITS.pageSize },
+                    pagination: { maximumPages: COLLECTION_QUERY_LIMITS.maximumPages },
+                    build: () => Query.from({ nodes: [selected] }).select({
+                        kind: 'nodes',
+                        projection: { kind: 'value' },
+                    }),
+                    project: (pages) => requireUniqueCollectionValues(queryResult.completeNodeValues(pages, specification.id), `Collection Query ${specification.id}`),
+                };
+            }
+            return {
+                id: specification.id,
+                page: { size: COLLECTION_QUERY_LIMITS.pageSize },
+                pagination: { maximumPages: COLLECTION_QUERY_LIMITS.maximumPages },
+                build: () => Query.from({ edges: [selected] }).select({
+                    kind: 'edges',
+                    projection: { edge: 'value', source: 'reference', target: 'reference' },
+                }),
+                project: (pages) => requireUniqueCollectionValues(Object.freeze(pages.flatMap((page) => queryResult.edgeItems(page, specification.id).map((item) => {
+                    if (item.edge.kind !== 'value') {
+                        throw new TypeError(`Collection Query ${specification.id} must project Edge values.`);
+                    }
+                    return item.edge.value;
+                }))), `Collection Query ${specification.id}`),
+            };
+        });
+        registerCollectionQuery(definition, project);
+        return definition;
+    });
+}
 /** Define one inert composite Query recipe projected from its exact loaded Domain. */
 export function defineCompositeQuery() {
     return ((project) => recipe('composite-query', project));
 }
-export function realizeQuery(definition, domain) {
-    const project = projectors.get(definition);
+export function realizeQuery(query, domain) {
+    const project = projectors.get(query);
     if (project === undefined)
         throw new TypeError('Query must be produced by defineQuery.');
     if (!isDomain(domain))
         throw new TypeError('Query projection requires an admitted Domain.');
-    let byDomain = realized.get(definition);
+    let byDomain = realized.get(query);
     const cached = byDomain?.get(domain);
     if (cached !== undefined)
         return cached;
     const authored = project(domain);
     if (isPromiseLike(authored))
         throw new TypeError('Query projection must be synchronous.');
-    const admitted = definition.kind === 'query' ? admitSingle(authored) : admitComposite(authored);
+    const admitted = query.kind === 'query' ? admitSingle(authored) : admitComposite(authored);
     if (byDomain === undefined) {
         byDomain = new WeakMap();
-        realized.set(definition, byDomain);
+        realized.set(query, byDomain);
     }
     byDomain.set(domain, admitted);
     return admitted;

package/dist/application/query/execution/execute.d.ts

@@ -9,5 +9,6 @@ export interface QueryClient {
         readonly expected?: Domain['closure'];
     }): Promise<QueryResponse<QueryResultFor<Ast>>>;
 }
-export declare function executeQuery<DomainValue extends Domain, Input, Output>(client: QueryClient, domain: DomainValue, definition: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
+export declare function executeQuery<DomainValue extends Domain, Output>(client: QueryClient, domain: DomainValue, query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
+export declare function executeQuery<DomainValue extends Domain, Input, Output>(client: QueryClient, domain: DomainValue, query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
 export type ExecutableCompositeQuery = CompositeQuery<unknown, unknown, unknown>;