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

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

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

@@ -0,0 +1,48 @@
+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, 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;
+    };
+};
+type AuthoredProjected<Input, Output, Ast extends QueryAST> = Omit<ProjectedQuery<Input, Output, Ast>, 'kind' | 'page'> & {
+    readonly page?: {
+        readonly size: number;
+    };
+};
+type AuthoredPaginated<Input, Output, Ast extends QueryAST> = Omit<PaginatedQuery<Input, Output, Ast>, 'kind' | 'page'> & {
+    readonly page?: {
+        readonly size: number;
+    };
+};
+type ResolvedDomainOf<Schema extends schema.DomainSchema> = Extract<schema.DomainOf<Schema>, Domain>;
+interface SingleQueryProjector<Schema extends schema.DomainSchema> {
+    <Input, Ast extends QueryAST>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredRaw<Input, Ast>): SingleQueryDefinition<ResolvedDomainOf<Schema>, Input, RawQuery<Input, Ast> extends SingleQuery<Input, infer Output> ? Output : never>;
+    <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, 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>(query: QueryDefinition<DomainValue, Input, Output>, domain: DomainValue): RealizedQuery<Input, Output>;
+export {};

package/dist/application/query/define.js

@@ -0,0 +1,162 @@
+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();
+const realized = new WeakMap();
+/** Define one inert single Query recipe projected from its exact loaded Domain. */
+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(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(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 = query.kind === 'query' ? admitSingle(authored) : admitComposite(authored);
+    if (byDomain === undefined) {
+        byDomain = new WeakMap();
+        realized.set(query, byDomain);
+    }
+    byDomain.set(domain, admitted);
+    return admitted;
+}
+function recipe(kind, project) {
+    if (typeof project !== 'function')
+        throw new TypeError('Query projection must be a function.');
+    const definition = Object.freeze({ kind });
+    projectors.set(definition, project);
+    return definition;
+}
+function admitSingle(definition) {
+    definitionBase(definition, 'build');
+    const page = pageOf(definition.page);
+    const pagination = definition.pagination;
+    if (pagination !== undefined) {
+        if (typeof definition.project !== 'function') {
+            throw new TypeError('Paginated Query requires a project function.');
+        }
+        if (pagination === null ||
+            typeof pagination !== 'object' ||
+            Array.isArray(pagination) ||
+            Reflect.ownKeys(pagination).length !== 1 ||
+            !Object.hasOwn(pagination, 'maximumPages')) {
+            throw new TypeError('Query pagination is invalid.');
+        }
+        const maximumPages = Reflect.get(pagination, 'maximumPages');
+        if (!Number.isSafeInteger(maximumPages) ||
+            maximumPages < 1 ||
+            maximumPages > MAXIMUM_PAGES) {
+            throw new TypeError(`Query pagination must be bounded from 1 through ${MAXIMUM_PAGES}.`);
+        }
+    }
+    return Object.freeze({ ...definition, page, kind: 'single' });
+}
+function admitComposite(definition) {
+    definitionBase(definition, 'compose');
+    if (Object.hasOwn(definition, 'page') || Object.hasOwn(definition, 'pagination')) {
+        throw new TypeError('Composite Query cannot declare pagination.');
+    }
+    return Object.freeze({ ...definition, kind: 'composite' });
+}
+function definitionBase(definition, operation) {
+    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[operation] !== 'function') {
+        invalid();
+    }
+    for (const optional of ['prepare', 'project', 'reject']) {
+        if (definition[optional] !== undefined && typeof definition[optional] !== 'function')
+            invalid();
+    }
+    const allowed = new Set([
+        'id',
+        operation,
+        'prepare',
+        'project',
+        'reject',
+        ...(operation === 'build' ? ['page', 'pagination'] : []),
+    ]);
+    if (Reflect.ownKeys(definition).some((key) => typeof key !== 'string' || !allowed.has(key))) {
+        invalid();
+    }
+}
+function pageOf(input) {
+    if (input === undefined)
+        return Object.freeze({ size: DEFAULT_PAGE_SIZE });
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        Reflect.ownKeys(input).length !== 1 ||
+        !Object.hasOwn(input, 'size') ||
+        !Number.isSafeInteger(Reflect.get(input, 'size')) ||
+        Reflect.get(input, 'size') < 1) {
+        throw new TypeError('Query page size must be a positive safe integer.');
+    }
+    return Object.freeze({ size: Reflect.get(input, 'size') });
+}
+function invalid() {
+    throw new TypeError('Query definition is invalid.');
+}
+function isPromiseLike(input) {
+    return (input !== null &&
+        (typeof input === 'object' || typeof input === 'function') &&
+        typeof input.then === 'function');
+}

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

@@ -0,0 +1,14 @@
+import type { QueryPageRequest, QueryResponse } from '@astrale-os/kernel-client/graph';
+import type { QueryAST, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
+import type { Domain } from '../../../platform/schema/index.js';
+import type { CompositeQuery } from '../composite/index.js';
+import type { QueryDefinition } from '../query.js';
+export interface QueryClient {
+    query<Ast extends QueryAST>(ast: Ast, options: {
+        readonly page: QueryPageRequest;
+        readonly expected?: Domain['closure'];
+    }): Promise<QueryResponse<QueryResultFor<Ast>>>;
+}
+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>;