@astrale-os/sdk 0.5.0-beta.8 → 0.5.0-beta.80

package/dist/application/mutation/define.js

@@ -0,0 +1,56 @@
+import { isDomain } from '@astrale-os/kernel-dsl/v1/domain';
+const projectors = new WeakMap();
+const realized = new WeakMap();
+/** Define one inert Mutation recipe projected from its exact loaded Domain. */
+export function defineMutation() {
+    return ((project) => {
+        if (typeof project !== 'function')
+            throw new TypeError('Mutation projection must be a function.');
+        const mutation = Object.freeze({ kind: 'mutation' });
+        projectors.set(mutation, project);
+        return mutation;
+    });
+}
+export function realizeMutation(mutation, domain) {
+    const project = projectors.get(mutation);
+    if (project === undefined)
+        throw new TypeError('Mutation must be produced by defineMutation.');
+    if (!isDomain(domain))
+        throw new TypeError('Mutation projection requires an admitted Domain.');
+    let byDomain = realized.get(mutation);
+    const cached = byDomain?.get(domain);
+    if (cached !== undefined)
+        return cached;
+    const authored = project(domain);
+    if (isPromiseLike(authored))
+        throw new TypeError('Mutation projection must be synchronous.');
+    const admitted = admitMutation(authored);
+    if (byDomain === undefined) {
+        byDomain = new WeakMap();
+        realized.set(mutation, byDomain);
+    }
+    byDomain.set(domain, admitted);
+    return admitted;
+}
+function admitMutation(definition) {
+    if (definition === null || typeof definition !== 'object' || Array.isArray(definition))
+        invalid();
+    if (typeof definition.id !== 'string' ||
+        definition.id.length === 0 ||
+        definition.id.trim() !== definition.id ||
+        typeof definition.build !== 'function' ||
+        (definition.project !== undefined && typeof definition.project !== 'function') ||
+        (definition.reject !== undefined && typeof definition.reject !== 'function') ||
+        Reflect.ownKeys(definition).some((key) => key !== 'id' && key !== 'build' && key !== 'project' && key !== 'reject')) {
+        invalid();
+    }
+    return Object.freeze({ ...definition });
+}
+function invalid() {
+    throw new TypeError('Mutation definition is invalid.');
+}
+function isPromiseLike(input) {
+    return (input !== null &&
+        (typeof input === 'object' || typeof input === 'function') &&
+        typeof input.then === 'function');
+}

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

@@ -0,0 +1,9 @@
+import { type MutationAST as MutationASTValue, type MutationResult } from '@astrale-os/kernel-core/graph/mutate';
+import type { GraphMutationOptions } from '../../../platform/client/index.js';
+import type { Domain } from '../../../platform/schema/index.js';
+import type { Mutation } from '../mutation.js';
+/** Exact caller-scoped canonical document capability required by Mutation execution. */
+export type MutationClient = Readonly<{
+    mutate(ast: MutationASTValue, options?: GraphMutationOptions): Promise<MutationResult>;
+}>;
+export declare function executeMutation<DomainValue extends Domain, Input, Output>(client: MutationClient, domain: DomainValue, definition: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;

package/dist/application/mutation/execution/execute.js

@@ -0,0 +1,21 @@
+import { MutationAST, } from '@astrale-os/kernel-core/graph/mutate';
+import { richMutationBuilder } from '../authoring/index.js';
+import { realizeMutation } from '../define.js';
+import { mutationFailure } from '../failure.js';
+import { projectMutation } from './projection.js';
+export async function executeMutation(client, domain, definition, input) {
+    if (client === null || typeof client !== 'object' || typeof client.mutate !== 'function') {
+        throw new TypeError('Mutation execution requires a Client mutate capability.');
+    }
+    const operation = realizeMutation(definition, domain);
+    try {
+        const ast = MutationAST.build((builder) => operation.build(input, richMutationBuilder(builder)));
+        return projectMutation(operation, await client.mutate(ast, { expected: domain.closure }), input);
+    }
+    catch (cause) {
+        const expected = mutationFailure(cause);
+        if (operation.reject !== undefined && expected !== undefined)
+            return operation.reject(expected);
+        throw cause;
+    }
+}

package/dist/application/mutation/execution/executor.d.ts

@@ -0,0 +1,13 @@
+import type { Domain, schema } from '../../../platform/schema/index.js';
+import type { Mutation } from '../mutation.js';
+import type { MutationClient } from './execute.js';
+/** Invocation-bound executor for authored Mutation definitions. */
+export interface MutationExecutor<DomainValue extends Domain = Domain> {
+    <Input, Output>(definition: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;
+}
+type ExecutableDomain<DomainValue extends Domain> = DomainValue extends {
+    readonly source: infer Source extends schema.DomainSchema;
+} ? Extract<schema.DomainOf<Source>, Domain> : DomainValue;
+/** Private Runtime binding to one Client and the exact loaded root Domain. */
+export declare function bindMutation<DomainValue extends Domain>(client: MutationClient, domain: DomainValue): MutationExecutor<ExecutableDomain<DomainValue>>;
+export {};

package/dist/application/mutation/execution/executor.js

@@ -0,0 +1,7 @@
+import { executeMutation } from './execute.js';
+/** Private Runtime binding to one Client and the exact loaded root Domain. */
+export function bindMutation(client, domain) {
+    const executable = domain;
+    const execute = (definition, input) => executeMutation(client, executable, definition, input);
+    return execute;
+}

package/dist/application/mutation/execution/index.d.ts

@@ -0,0 +1,2 @@
+export { executeMutation, type MutationClient } from './execute.js';
+export type { MutationExecutor } from './executor.js';

package/dist/application/mutation/execution/index.js

@@ -0,0 +1 @@
+export { executeMutation } from './execute.js';

package/dist/application/mutation/execution/projection.d.ts

@@ -0,0 +1,3 @@
+import type { MutationResult } from '@astrale-os/kernel-core/graph/mutate';
+import type { MutationDefinition } from '../mutation.js';
+export declare function projectMutation<Input, Output>(definition: MutationDefinition<Input, Output>, result: MutationResult, input: Input): Output;

package/dist/application/mutation/execution/projection.js

@@ -0,0 +1,3 @@
+export function projectMutation(definition, result, input) {
+    return (definition.project === undefined ? result : definition.project(result, input));
+}

package/dist/application/mutation/failure.d.ts

@@ -0,0 +1,13 @@
+export interface KernelMutationFailure extends Error {
+    readonly code: `MUTATION_${string}`;
+    readonly outcomeKnown: boolean;
+}
+export interface StateTransitionFailure extends Error {
+    readonly code: 'STATE_TRANSITION_ILLEGAL';
+    readonly outcomeKnown: true;
+    readonly from: string;
+    readonly event: string;
+}
+export type MutationFailure = KernelMutationFailure | StateTransitionFailure;
+export declare function stateTransitionFailure(from: string, event: string): StateTransitionFailure;
+export declare function mutationFailure(input: unknown): MutationFailure | undefined;

package/dist/application/mutation/failure.js

@@ -0,0 +1,51 @@
+const UNKNOWN_OUTCOME_CODES = new Set(['MUTATION_OUTCOME_UNKNOWN']);
+const localStateTransitionFailures = new WeakSet();
+export function stateTransitionFailure(from, event) {
+    const failure = Object.assign(new Error(`State transition is illegal: ${from} + ${event}.`), {
+        code: 'STATE_TRANSITION_ILLEGAL',
+        outcomeKnown: true,
+        from,
+        event,
+    });
+    localStateTransitionFailures.add(failure);
+    return failure;
+}
+export function mutationFailure(input) {
+    if (!(input instanceof Error))
+        return undefined;
+    const code = mutationCode(input);
+    if (code === undefined)
+        return undefined;
+    const explicit = input.outcomeKnown;
+    if (explicit !== undefined && typeof explicit !== 'boolean')
+        return undefined;
+    if (code === 'STATE_TRANSITION_ILLEGAL') {
+        if (!localStateTransitionFailures.has(input))
+            return undefined;
+        const from = Reflect.get(input, 'from');
+        const event = Reflect.get(input, 'event');
+        if (typeof from !== 'string' || typeof event !== 'string' || explicit === false)
+            return undefined;
+        return Object.assign(input, { code, outcomeKnown: true, from, event });
+    }
+    return Object.assign(input, {
+        code,
+        outcomeKnown: explicit !== false && !UNKNOWN_OUTCOME_CODES.has(code),
+    });
+}
+function mutationCode(input) {
+    const value = input;
+    if (value.code === 'STATE_TRANSITION_ILLEGAL')
+        return value.code;
+    for (const candidate of [value.code, nestedCode(value.reason), nestedCode(value.data)]) {
+        if (typeof candidate === 'string' && candidate.startsWith('MUTATION_')) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function nestedCode(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input)
+        ? Reflect.get(input, 'code')
+        : undefined;
+}

package/dist/application/mutation/index.d.ts

@@ -0,0 +1,7 @@
+export { defineMutation } from './define.js';
+export { executeMutation, type MutationClient, type MutationExecutor } from './execution/index.js';
+export type { MutationFailure } from './failure.js';
+export type { Mutation, MutationDefinition, MutationInputOf, MutationOutputOf } from './mutation.js';
+export type { CreatedNode, EdgeSelector, ExistingEndpoint, MutationEndpoint, QueryPrecondition, RichMutationBuilder, RichPropertyConditions, RichPropertyDelta, RichPropertyInput, RichPropertyName, } from './authoring/index.js';
+/** Canonical low-level Mutation documents remain available as the explicit escape hatch. */
+export * from '@astrale-os/kernel-core/graph/mutate';

package/dist/application/mutation/index.js

@@ -0,0 +1,4 @@
+export { defineMutation } from './define.js';
+export { executeMutation } from './execution/index.js';
+/** Canonical low-level Mutation documents remain available as the explicit escape hatch. */
+export * from '@astrale-os/kernel-core/graph/mutate';

package/dist/application/mutation/mutation.d.ts

@@ -0,0 +1,24 @@
+import type { MutationResult } from '@astrale-os/kernel-core/graph/mutate';
+import type { Domain } from '../../platform/schema/index.js';
+import type { RichMutationBuilder } from './authoring/index.js';
+import type { MutationFailure } from './failure.js';
+declare const MUTATION_DOMAIN: unique symbol;
+declare const MUTATION_INPUT: unique symbol;
+declare const MUTATION_OUTPUT: unique symbol;
+/** Inert Domain-bound Mutation recipe. Its projector is retained privately by the SDK. */
+export interface Mutation<DomainValue extends Domain = Domain, Input = unknown, Output = MutationResult> {
+    readonly kind: 'mutation';
+    readonly [MUTATION_DOMAIN]: (domain: DomainValue) => DomainValue;
+    readonly [MUTATION_INPUT]?: Input;
+    readonly [MUTATION_OUTPUT]?: Output;
+}
+/** Canonical admitted operation produced by realizing one Mutation recipe. */
+export interface MutationDefinition<Input, Output = MutationResult> {
+    readonly id: string;
+    build(input: Input, mutation: RichMutationBuilder): undefined;
+    project?(result: MutationResult, input: NoInfer<Input>): Output;
+    reject?(failure: MutationFailure): Output;
+}
+export type MutationInputOf<Value> = Value extends Mutation<infer _Domain, infer Input, infer _Output> ? Input : Value extends MutationDefinition<infer Input, infer _Output> ? Input : never;
+export type MutationOutputOf<Value> = Value extends Mutation<infer _Domain, infer _Input, infer Output> ? Output : Value extends MutationDefinition<infer _Input, infer Output> ? Output : never;
+export {};

package/dist/application/mutation/mutation.js

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

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

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