@astrale-os/sdk 0.5.0-beta.4 → 0.5.0-beta.41

package/dist/application/mutation/failure.js

@@ -0,0 +1,28 @@
+const UNKNOWN_OUTCOME_CODES = new Set(['MUTATION_OUTCOME_UNKNOWN']);
+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;
+    return Object.assign(input, {
+        code,
+        outcomeKnown: explicit !== false && !UNKNOWN_OUTCOME_CODES.has(code),
+    });
+}
+function mutationCode(input) {
+    const value = input;
+    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/composite/builder.d.ts

@@ -0,0 +1,40 @@
+import type { Domain } from '../../../platform/schema/index.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 type PlanNode = LeafPlan | CombinedPlan;
+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,169 @@
+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,
+            }));
+        },
+        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,9 @@
+import type { Domain } from '../../../platform/schema/index.js';
+import type { SingleQueryDefinition } from '../query.js';
+import type { InternalPlan } from './builder.js';
+export interface QueryPlanAnalysis {
+    readonly queries: number;
+    readonly depth: 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>;

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

@@ -0,0 +1,56 @@
+import { inspectPlan, referencesIn, resolveInput } from './builder.js';
+import { QueryCompositionError } from './errors.js';
+const MAX_QUERIES = 32;
+const MAX_DEPTH = 8;
+export function analyzeQueryPlan(plan) {
+    const leafKeys = new Set();
+    const visiting = new Set();
+    const depths = new Map();
+    const depth = (candidate) => {
+        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.values(node.plans).map(depth));
+        }
+        else {
+            leafKeys.add(node.key);
+            const dependencies = referencesIn(node.input).map((reference) => reference.plan);
+            value = 1 + (dependencies.length === 0 ? 0 : Math.max(...dependencies.map(depth)));
+        }
+        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}.`);
+    }
+    return Object.freeze({ queries: leafKeys.size, depth: maximumDepth });
+}
+export async function executeQueryPlan(plan, run) {
+    analyzeQueryPlan(plan);
+    const results = new Map();
+    const execute = (candidate) => {
+        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));
+        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,36 @@
+import type { Domain } from '../../../platform/schema/index.js';
+import type { 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];
+export interface QueryComposition<DomainValue extends Domain = Domain> {
+    query<Input, Output>(id: string, definition: SingleQueryDefinition<DomainValue, Input, Output>, input: QueryPlanInput<Input>): QueryPlan<Output>;
+    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,36 @@
+import type { QueryAST } from '@astrale-os/kernel-core/graph/query';
+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 { PaginatedQuery, ProjectedQuery, RawQuery, SingleQuery } from './single/index.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 CompositeQueryProjector<Schema extends schema.DomainSchema> {
+    <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>;
+}
+/** Define one inert single Query recipe projected from its exact loaded Domain. */
+export declare function defineQuery<Schema extends schema.DomainSchema>(): SingleQueryProjector<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 {};

package/dist/application/query/define.js

@@ -0,0 +1,119 @@
+import { isDomain } from '@astrale-os/kernel-dsl/v1/domain';
+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 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);
+    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);
+    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);
+    if (byDomain === undefined) {
+        byDomain = new WeakMap();
+        realized.set(definition, 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,13 @@
+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, Input, Output>(client: QueryClient, domain: DomainValue, definition: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
+export type ExecutableCompositeQuery = CompositeQuery<unknown, unknown, unknown>;

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

@@ -0,0 +1,57 @@
+import { createQueryComposition, executeQueryPlan } from '../composite/index.js';
+import { realizeQuery } from '../define.js';
+import { queryFailure } from '../failure.js';
+import { completeSelection } from '../single/index.js';
+import { executePages } from './pages.js';
+export async function executeQuery(client, domain, definition, input) {
+    if (client === null || typeof client !== 'object' || typeof client.query !== 'function') {
+        throw new TypeError('Query execution requires a Client query capability.');
+    }
+    const execute = (ast, options) => client.query(ast, { ...options, expected: domain.closure });
+    const operation = realizeQuery(definition, domain);
+    try {
+        if (operation.kind === 'single')
+            return (await runSingle(execute, operation, input));
+        const prepared = operation.prepare?.(input) ?? input;
+        const session = createQueryComposition();
+        const composed = operation.compose(session.builder, prepared);
+        if (isPromiseLike(composed))
+            throw new TypeError('Composite Query composition must be synchronous.');
+        const plan = session.close(composed);
+        const result = await executeQueryPlan(plan, (child, childInput) => runSingle(execute, realizeSingle(child, domain), childInput));
+        return (operation.project === undefined ? result : operation.project(result, prepared));
+    }
+    catch (cause) {
+        const expected = queryFailure(cause);
+        if (operation.reject !== undefined && expected !== undefined) {
+            return operation.reject(expected);
+        }
+        throw cause;
+    }
+}
+function realizeSingle(definition, domain) {
+    const operation = realizeQuery(definition, domain);
+    if (operation.kind !== 'single')
+        throw new TypeError('Composite Query leaves must be single.');
+    return operation;
+}
+async function runSingle(execute, definition, input) {
+    const prepared = definition.prepare?.(input) ?? input;
+    const ast = definition.build(prepared);
+    if (definition.pagination !== undefined) {
+        const collected = await executePages(execute, ast, definition.page, definition.pagination);
+        return definition.project(collected, prepared, {
+            ast,
+            complete: completeSelection(collected),
+        });
+    }
+    const response = await execute(ast, { page: definition.page });
+    return definition.project === undefined
+        ? response.result
+        : definition.project(response.result, prepared, { ast });
+}
+function isPromiseLike(input) {
+    return (input !== null &&
+        (typeof input === 'object' || typeof input === 'function') &&
+        typeof input.then === 'function');
+}

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

@@ -0,0 +1,9 @@
+import type { Domain } from '../../../platform/schema/index.js';
+import type { QueryDefinition } from '../query.js';
+import type { QueryClient } from './execute.js';
+/** Invocation-bound executor for authored Query definitions. */
+export interface QueryExecutor<DomainValue extends Domain = Domain> {
+    <Input, Output>(definition: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
+}
+/** Private Runtime binding to one Client and the exact loaded root Domain. */
+export declare function bindQuery<DomainValue extends Domain>(client: QueryClient, domain: DomainValue): QueryExecutor<DomainValue>;