@astrale-os/sdk 0.5.0-beta.13 → 0.5.0-beta.131

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

@@ -0,0 +1,46 @@
+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;
+export interface PlanReference {
+    readonly token: object;
+    readonly plan: InternalPlan;
+    readonly path: readonly PropertyKey[];
+}
+export interface LeafPlan {
+    readonly kind: 'leaf';
+    readonly key: number;
+    readonly id: string;
+    readonly definition: SingleQueryDefinition<Domain, unknown, unknown>;
+    readonly input: unknown;
+}
+export interface CombinedPlan {
+    readonly kind: 'combine';
+    readonly key: number;
+    readonly plans: Readonly<Record<string, InternalPlan>>;
+}
+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;
+        node: PlanNode;
+    }>;
+}
+export interface QueryCompositionSession<DomainValue extends Domain = Domain> {
+    readonly builder: QueryComposition<DomainValue>;
+    close(output: unknown): InternalPlan;
+}
+export declare function createQueryComposition<DomainValue extends Domain>(): QueryCompositionSession<DomainValue>;
+export declare function inspectPlan(plan: InternalPlan): Readonly<{
+    token: object;
+    node: PlanNode;
+}>;
+export declare function referencesIn(input: unknown, found?: PlanReference[]): readonly PlanReference[];
+export declare function resolveInput(input: unknown, execute: (plan: InternalPlan) => Promise<unknown>): Promise<unknown>;
+export {};

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

@@ -0,0 +1,176 @@
+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');
+export function createQueryComposition() {
+    const token = Object.freeze({});
+    const ids = new Set();
+    let nextKey = 0;
+    let open = true;
+    const builder = Object.freeze({
+        query(id, definition, input) {
+            requireOpen(open);
+            requireLocalId(id, ids);
+            if (definition?.kind !== 'query')
+                invalid('Composite leaves must be single Query recipes.');
+            requireLocalReferences(input, token);
+            return createPlan(token, Object.freeze({
+                kind: 'leaf',
+                key: nextKey++,
+                id,
+                definition: definition,
+                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) {
+                invalid('Query composition must combine at least one named plan.');
+            }
+            const accepted = {};
+            for (const [name, plan] of Object.entries(plans)) {
+                if (name.length === 0)
+                    invalid('Query composition result names must not be empty.');
+                const internal = acceptPlan(plan);
+                if (inspectPlan(internal).token !== token)
+                    invalid('Cannot combine a foreign Query plan.');
+                accepted[name] = internal;
+            }
+            return createPlan(token, Object.freeze({
+                kind: 'combine',
+                key: nextKey++,
+                plans: Object.freeze(accepted),
+            }));
+        },
+    });
+    return Object.freeze({
+        builder,
+        close(output) {
+            requireOpen(open);
+            open = false;
+            const plan = acceptPlan(output);
+            if (inspectPlan(plan).token !== token)
+                invalid('Composite Query must return its own plan.');
+            return plan;
+        },
+    });
+}
+export function inspectPlan(plan) {
+    return plan[PLAN];
+}
+export function referencesIn(input, found = []) {
+    const reference = referenceOf(input);
+    if (reference !== undefined) {
+        found.push(reference);
+    }
+    else if (Array.isArray(input)) {
+        for (const value of input)
+            referencesIn(value, found);
+    }
+    else if (isPlainRecord(input)) {
+        for (const value of Object.values(input))
+            referencesIn(value, found);
+    }
+    return found;
+}
+export async function resolveInput(input, execute) {
+    const reference = referenceOf(input);
+    if (reference !== undefined) {
+        let value = await execute(reference.plan);
+        for (const part of reference.path) {
+            if (value === null || (typeof value !== 'object' && typeof value !== 'function')) {
+                invalid(`Query dependency has no ${String(part)} value.`);
+            }
+            value = value[part];
+        }
+        return value;
+    }
+    if (Array.isArray(input))
+        return Promise.all(input.map((value) => resolveInput(value, execute)));
+    if (isPlainRecord(input)) {
+        const entries = await Promise.all(Object.entries(input).map(async ([key, value]) => [key, await resolveInput(value, execute)]));
+        return Object.freeze(Object.fromEntries(entries));
+    }
+    return input;
+}
+function createPlan(token, node) {
+    const plan = {};
+    Object.defineProperty(plan, PLAN, {
+        value: Object.freeze({ token, node }),
+        enumerable: false,
+    });
+    Object.defineProperty(plan, 'value', {
+        value: symbolicValue(token, plan, []),
+        enumerable: true,
+    });
+    return Object.freeze(plan);
+}
+function symbolicValue(token, plan, path) {
+    return new Proxy(Object.create(null), {
+        get(_target, property) {
+            if (property === REFERENCE)
+                return Object.freeze({ token, plan, path });
+            if (property === Symbol.toStringTag)
+                return 'QueryPlanValue';
+            if (property === 'then')
+                return undefined;
+            return symbolicValue(token, plan, Object.freeze([...path, property]));
+        },
+    });
+}
+function acceptPlan(input) {
+    if (input === null || typeof input !== 'object' || !(PLAN in input)) {
+        invalid('Composite Query must return a Query plan.');
+    }
+    return input;
+}
+function referenceOf(input) {
+    if (input === null || (typeof input !== 'object' && typeof input !== 'function'))
+        return undefined;
+    try {
+        const reference = input[REFERENCE];
+        if (reference !== null &&
+            typeof reference === 'object' &&
+            'token' in reference &&
+            'plan' in reference &&
+            'path' in reference) {
+            return reference;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function requireLocalReferences(input, token) {
+    if (referencesIn(input).some((reference) => reference.token !== token)) {
+        invalid('Query leaf input cannot reference a foreign composition.');
+    }
+}
+function requireLocalId(id, ids) {
+    if (typeof id !== 'string' || id.length === 0 || id.trim() !== id) {
+        invalid('Query leaf id must be a non-empty stable string.');
+    }
+    if (ids.has(id))
+        invalid(`Query leaf id ${id} occurs more than once.`);
+    ids.add(id);
+}
+function requireOpen(open) {
+    if (!open)
+        invalid('Query composition builder is closed.');
+}
+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);
+}

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

@@ -0,0 +1,7 @@
+import type { QueryFailure } from '../failure.js';
+export type QueryCompositionErrorCode = 'QUERY_COMPOSITION_INVALID' | 'QUERY_COMPOSITION_LIMIT';
+export declare class QueryCompositionError extends Error implements QueryFailure {
+    readonly code: QueryCompositionErrorCode;
+    readonly name = "QueryCompositionError";
+    constructor(code: QueryCompositionErrorCode, message: string);
+}

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

@@ -0,0 +1,8 @@
+export class QueryCompositionError extends Error {
+    code;
+    name = 'QueryCompositionError';
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}

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

@@ -0,0 +1,4 @@
+export { createQueryComposition, type QueryCompositionSession } from './builder.js';
+export { QueryCompositionError, type QueryCompositionErrorCode } from './errors.js';
+export { analyzeQueryPlan, executeQueryPlan, type QueryPlanAnalysis } from './plan.js';
+export type { CompositeQuery, ProjectedCompositeQuery, QueryComposition, QueryPlan, QueryPlanInput, QueryPlanOutput, QueryPlanValue, RawCompositeQuery, } from './query.js';

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

@@ -0,0 +1,3 @@
+export { createQueryComposition } from './builder.js';
+export { QueryCompositionError } from './errors.js';
+export { analyzeQueryPlan, executeQueryPlan } from './plan.js';

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

@@ -0,0 +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>, runUnion: (definitions: CollectionDefinitionRecord, outputPath: readonly string[]) => Promise<unknown>): Promise<unknown>;

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

@@ -0,0 +1,85 @@
+import { COLLECTION_QUERY_LIMITS } from '../collection/limits.js';
+import { inspectPlan, referencesIn, resolveInput } from './builder.js';
+import { QueryCompositionError } from './errors.js';
+export const QUERY_COMPOSITION_LIMITS = Object.freeze({
+    maximumPhysicalQueries: 32,
+    maximumDependencyDepth: 8,
+});
+export function analyzeQueryPlan(plan) {
+    const physicalKeys = new Set();
+    const logicalByKey = new Map();
+    const visiting = new Set();
+    const depths = new Map();
+    const unionGroups = [];
+    const depth = (candidate, outputPath = []) => {
+        const { node } = inspectPlan(candidate);
+        const cached = depths.get(node.key);
+        if (cached !== undefined)
+            return cached;
+        if (visiting.has(node.key))
+            invalid('Query composition contains a dependency cycle.');
+        visiting.add(node.key);
+        let value;
+        if (node.kind === 'combine') {
+            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 {
+            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((dependency) => depth(dependency))));
+        }
+        visiting.delete(node.key);
+        depths.set(node.key, value);
+        return value;
+    };
+    const maximumDepth = depth(plan);
+    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: 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, runUnion) {
+    analyzeQueryPlan(plan);
+    const results = new Map();
+    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, [...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;
+    };
+    return execute(plan);
+}
+function invalid(message) {
+    throw new QueryCompositionError('QUERY_COMPOSITION_INVALID', message);
+}

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

@@ -0,0 +1,44 @@
+import type { ResolvedClass } from '@astrale-os/kernel-dsl/v1';
+import type { Domain } from '../../../platform/schema/index.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;
+export type QueryPlanValue<Value> = Readonly<{
+    [QUERY_PLAN_VALUE]: Value;
+}> & (Value extends readonly (infer Item)[] ? ReadonlyArray<QueryPlanValue<Item>> : Value extends object ? {
+    readonly [Key in keyof Value]: QueryPlanValue<Value[Key]>;
+} : object);
+export type QueryPlanInput<Value> = QueryPlanValue<Value> | (Value extends readonly (infer Item)[] ? readonly QueryPlanInput<Item>[] : Value extends object ? {
+    readonly [Key in keyof Value]: QueryPlanInput<Value[Key]>;
+} : Value);
+export interface QueryPlan<Output> {
+    readonly [QUERY_PLAN_OUTPUT]: 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<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]>;
+    }>;
+}
+export interface CompositeQueryBase<Input, Composed, Output, DomainValue extends Domain = Domain> extends QueryLifecycle<Input, Output> {
+    readonly kind: 'composite';
+    compose(builder: QueryComposition<DomainValue>, input: Input): QueryPlan<Composed>;
+}
+export interface RawCompositeQuery<Input, Output, DomainValue extends Domain = Domain> extends CompositeQueryBase<Input, Output, Output, DomainValue> {
+    readonly project?: undefined;
+}
+export interface ProjectedCompositeQuery<Input, Composed, Output, DomainValue extends Domain = Domain> extends CompositeQueryBase<Input, Composed, Output, DomainValue> {
+    project(value: Composed, input: Input): Output;
+}
+export type CompositeQuery<Input, Composed, Output = Composed, DomainValue extends Domain = Domain> = RawCompositeQuery<Input, Composed, DomainValue> | ProjectedCompositeQuery<Input, Composed, Output, DomainValue>;
+export {};

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

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