@astrale-os/sdk 0.6.0-beta.41 → 0.6.0-beta.43

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

@@ -0,0 +1,50 @@
+function sentence(code, details) {
+    switch (code) {
+        case 'NOT_FOUND':
+            return details.target === undefined
+                ? `no ${String(details.class)} was found`
+                : `no ${String(details.class)} ${String(details.target)} was found`;
+        case 'NOT_READABLE':
+            return `${String(details.class)} ${typeof details.id === 'string' ? details.id : JSON.stringify(details.id)} may not be read`;
+        case 'INTEGRITY': {
+            const of = details.parent === undefined ? '' : ` of ${String(details.parent)}`;
+            return details.found === 0
+                ? `${String(details.relation)}${of} found none where one is required`
+                : `${String(details.relation)}${of} found a second row where one is allowed`;
+        }
+        case 'TOO_MANY':
+            return `past ${String(details.bound)} ${details.limit === 'max' ? 'rows (max)' : String(details.limit)}`;
+        case 'REFUSED':
+            return `the Kernel refused the read (${String(details.kernelCode)})`;
+        case 'INPUT_INVALID':
+            return details.limit === 'in'
+                ? `an in takes at most 16 values (at ${String(details.path)})`
+                : `the Kernel refused the query (${String(details.kernelCode)}${details.path === undefined ? '' : ` at ${String(details.path)}`})`;
+        case 'OUTDATED':
+            return "the Host's Registry no longer matches this Domain's build";
+        case 'UNSUPPORTED':
+            return details.feature === 'v7'
+                ? 'the Host does not serve Query v7'
+                : 'the Host does not give the Class of each row';
+    }
+}
+export class QueryError extends Error {
+    code;
+    recipe;
+    details;
+    name = 'QueryError';
+    constructor(code, 
+    /** The recipe's id. */
+    recipe, details, options) {
+        const reason = options?.reason === undefined ? '' : `: ${options.reason}`;
+        super(`${recipe}: ${sentence(code, details)}${reason}`, options);
+        this.code = code;
+        this.recipe = recipe;
+        this.details = details;
+        Object.freeze(this.details);
+    }
+}
+/** Whether `error` is a `QueryError`, of `code` if given. */
+export function isQueryError(error, code) {
+    return error instanceof QueryError && (code === undefined || error.code === code);
+}

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

@@ -1,13 +1,8 @@
-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 { QueryClient } from '../legacy/v6/execution/execute.js';
 import type { QueryDefinition } from '../query.js';
-export interface QueryClient {
-    query<Ast extends QueryAST>(ast: Ast, options: {
-        readonly page: QueryPageRequest;
-    }): Promise<QueryResponse<QueryResultFor<Ast>>>;
-}
+export type { QueryClient } from '../legacy/v6/execution/execute.js';
 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>;

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

@@ -1,21 +1,13 @@
-import { COLLECTION_QUERY_LIMITS } from '../collection/limits.js';
-import { compileCollectionUnion, partitionCollectionUnion } from '../collection/union.js';
 import { createQueryComposition, executeQueryPlan } from '../composite/index.js';
-import { requireConformance } from '../conformance.js';
 import { realizeQuery } from '../define.js';
+import { isPromiseLike } from '../definition.js';
 import { queryFailure } from '../failure.js';
-import { completeSelection, queryResult } from '../single/index.js';
-import { executePages } from './pages.js';
+import { conformingClient, realizeSingle, runCollectionUnion, runSingle, } from '../legacy/v6/execution/execute.js';
 export async function executeQuery(client, domain, query, input) {
     if (client === null || typeof client !== 'object' || typeof client.query !== 'function') {
         throw new TypeError('Query execution requires a Client query capability.');
     }
-    // The Kernel answers in its active Schema; each value is checked against this client's Domain.
-    const execute = async (ast, options) => {
-        const response = await client.query(ast, options);
-        requireConformance(domain, response.result);
-        return response;
-    };
+    const execute = conformingClient(client, domain);
     const operation = realizeQuery(query, domain);
     try {
         if (operation.kind === 'single') {
@@ -38,43 +30,3 @@ export async function executeQuery(client, domain, query, input) {
         throw cause;
     }
 }
-async function runCollectionUnion(execute, domain, definitions, outputPath) {
-    const compiled = compileCollectionUnion(domain, definitions, outputPath);
-    const pages = await executePages(execute, compiled.ast, { size: COLLECTION_QUERY_LIMITS.pageSize }, { maximumPages: COLLECTION_QUERY_LIMITS.maximumPages });
-    const context = outputPath.length === 0 ? 'collection union' : outputPath.join('.');
-    const values = compiled.kind === 'node'
-        ? queryResult.completeNodeValues(pages, context)
-        : Object.freeze(pages.flatMap((page) => queryResult.edgeItems(page, context).map((item) => {
-            if (item.edge.kind !== 'value') {
-                throw new TypeError(`${context} must project Edge values.`);
-            }
-            return item.edge.value;
-        })));
-    return partitionCollectionUnion(domain, compiled, values);
-}
-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/recipe.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Run a v7 recipe (WP-S3): its steps in order, each one's reads together, at most 8 in flight,
+ * each read at its own snapshot (the stand-in); then `output`. A step's bounds (S11) are checked
+ * before it sends anything, and every Kernel refusal of a read is a `QueryError`.
+ */
+import type { Domain } from '../../../platform/schema/index.js';
+import type { ReadPlan } from '../handles/plan.js';
+import type { AnyQuery } from '../language/query.js';
+import type { Errors, InputOf, OutputContext, OutputOf, Recipe } from '../recipe/recipe.js';
+import { type Model } from '../handles/model.js';
+import { type DeclaredClass } from './crossings.js';
+/** What a recipe sends a read with: the cursor a page continues. */
+export interface RecipeQueryOptions {
+    readonly paging?: {
+        readonly after: string;
+    };
+}
+/** The client a recipe reads through: one v7 document per request. */
+export interface RecipeClient {
+    query(document: AnyQuery, options: RecipeQueryOptions): Promise<unknown>;
+}
+/** A page recipe's call: its size, from 1 to its `max` (by default), and the cursor it continues. */
+export interface RecipeCallOptions {
+    readonly size?: number;
+    readonly after?: string;
+}
+/** A recipe call's options: the authority it reads under, and a page recipe's size and cursor. */
+export type RecipeOptions<R, As extends string> = {
+    readonly as: As;
+} & ('~page' extends keyof R ? RecipeCallOptions : {});
+type Step = (...parameters: readonly unknown[]) => unknown;
+/** One recipe call: its reads so far, against S11, and the Classes they cross, against S12. */
+export declare class Run {
+    #private;
+    readonly client: RecipeClient;
+    readonly domain: Domain;
+    readonly recipe: string;
+    readonly model: Model;
+    constructor(client: RecipeClient, domain: Domain, recipe: string, declared?: readonly DeclaredClass[]);
+    /**
+     * S11, before a step sends: its reads, its verbs' bounds, its rows and each property `in` its
+     * documents write. Then S12: each foreign Class its relations cross.
+     */
+    admit(plans: readonly ReadPlan[]): void;
+    /** One read's result: its verb's empty answer, or its documents' answers merged and rendered. */
+    read(plan: ReadPlan, paging?: RecipeCallOptions): Promise<unknown>;
+}
+/** What `steps(…)` returned: its first record of facets, and the functions of the next ones. */
+interface StepsOf {
+    readonly first: unknown;
+    readonly next: readonly Step[];
+}
+/**
+ * The `steps` a recipe's `build` receives: two to eight steps, the first a record of facets and
+ * each next one a function of the merged results before it. It reads nothing: what it returns is
+ * read when `build` returns it.
+ */
+export declare function stepsFor(recipe: string): (...steps: readonly unknown[]) => object;
+/** The steps `build` returned, or `undefined` for one read or one record of facets. */
+export declare function stepsOf(built: unknown): StepsOf | undefined;
+/** Where each facet's results go: one read's index, a list of them, or nothing. */
+type Shape = readonly (readonly [string, number | readonly number[] | undefined])[];
+/**
+ * The reads of one step, admitted (S11, S12): a single read, or each facet's in order and the
+ * shape that puts their results back. A facet takes a name no `earlier` step read: the merged
+ * results keep one value per name.
+ */
+export declare function planStep(run: Run, built: unknown, single: boolean, earlier?: Readonly<Record<string, unknown>>): {
+    readonly plans: readonly ReadPlan[];
+    readonly shape?: Shape;
+};
+/**
+ * Run a recipe for `input` against `domain`, the resolved Domain it was written for: what `build`
+ * returns, each of its steps in order, then its `output`. A page recipe takes its call's `size`
+ * and `after`. A read the Kernel refuses raises a `QueryError`; `output` raises the recipe's
+ * declared errors. With the Class requirements
+ * the Domain's build `declared`, each step's relations are checked against them first (S12).
+ */
+export declare function runQueryRecipe<R extends Recipe>(client: RecipeClient, domain: Domain, recipe: R, input: InputOf<R>, call?: RecipeCallOptions, declared?: readonly DeclaredClass[]): Promise<OutputOf<R>>;
+/**
+ * The context a recipe's `output`, or a Mutation recipe's `reject`, receives: its declared errors,
+ * and `is`, which narrows a row by Class.
+ */
+export declare function outputContext(recipe: object, model: Model): OutputContext<unknown, Errors>;
+export {};

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

@@ -0,0 +1,324 @@
+import * as errors from '@astrale-os/kernel-protocol/errors';
+import { isSnapshotStale, ResponseError, retryAfterOf } from '../../../platform/client/index.js';
+import { declaredErrorFactory } from '../../error/error.js';
+import { requireAnswerConformance } from '../answer/conformance.js';
+import { handlesOf } from '../handles/build.js';
+import { modelOf } from '../handles/model.js';
+import { isRead, planOf } from '../handles/plan.js';
+import { describe } from '../handles/terms.js';
+import { recipeSpecOf } from '../recipe/define.js';
+import { MAXIMUM_BOUND, MAXIMUM_READS, MAXIMUM_ROWS, MAXIMUM_STEPS, pastPage, rowsOf, wideIn, } from './bounds.js';
+import { Crossings } from './crossings.js';
+import { QueryError } from './error.js';
+import { describeRefusals, isUnserved, refusalsOf } from './refusal.js';
+import { emptyResult, rootResult } from './rows.js';
+import { merge, split } from './split.js';
+/** Reads of one step in flight at once. */
+const IN_FLIGHT = 8;
+/** `QUERY_SNAPSHOT_STALE`: nothing was read, so the read is sent again at once, this many times. */
+const STALE_RESENDS = 3;
+/** A refusal's protocol code by name, for one that gives no reason. */
+const CODE_NAMES = new Map(Object.entries(errors.CODES).map(([name, code]) => [code, name]));
+/** One recipe call: its reads so far, against S11, and the Classes they cross, against S12. */
+export class Run {
+    client;
+    domain;
+    recipe;
+    #reads = 0;
+    #rows = 0;
+    model;
+    #crossings;
+    constructor(client, domain, recipe, declared) {
+        this.client = client;
+        this.domain = domain;
+        this.recipe = recipe;
+        this.model = modelOf(domain);
+        this.#crossings =
+            declared === undefined ? undefined : new Crossings(this.model, domain, declared);
+    }
+    /**
+     * S11, before a step sends: its reads, its verbs' bounds, its rows and each property `in` its
+     * documents write. Then S12: each foreign Class its relations cross.
+     */
+    admit(plans) {
+        this.#reads += plans.length;
+        if (this.#reads > MAXIMUM_READS)
+            throw new QueryError('TOO_MANY', this.recipe, { limit: 'reads', bound: MAXIMUM_READS });
+        if (plans.some(pastPage))
+            throw new QueryError('TOO_MANY', this.recipe, { limit: 'rows', bound: MAXIMUM_BOUND });
+        this.#rows += plans.reduce((total, plan) => total + rowsOf(plan), 0);
+        if (this.#rows > MAXIMUM_ROWS)
+            throw new QueryError('TOO_MANY', this.recipe, { limit: 'rows', bound: MAXIMUM_ROWS });
+        for (const plan of plans) {
+            const path = plan.document === undefined ? undefined : wideIn(plan.document);
+            // Into the request `{ document, paging }`, as the Kernel's refusals point.
+            if (path !== undefined)
+                throw new QueryError('INPUT_INVALID', this.recipe, {
+                    limit: 'in',
+                    path: `/document${path}`,
+                });
+        }
+        for (const plan of plans)
+            this.#crossings?.check(this.recipe, plan);
+    }
+    /** One read's result: its verb's empty answer, or its documents' answers merged and rendered. */
+    async read(plan, paging) {
+        if (plan.empty)
+            return emptyResult(this.recipe, plan);
+        let document = plan.document;
+        if (plan.verb === 'page' && paging?.size !== undefined)
+            document = withLimit(document, paging.size);
+        const documents = plan.verb === 'page' || plan.verb === 'document'
+            ? [document]
+            : split(document, document.list?.orderBy !== undefined);
+        const answers = [];
+        for (const sent of documents) {
+            const answer = await this.#send(sent, paging?.after);
+            if ('list' in answer)
+                requireAnswerConformance(this.domain, answer);
+            answers.push(answer);
+        }
+        return rootResult(this.recipe, this.model, plan, merge(document, answers));
+    }
+    async #send(document, after) {
+        const paging = after === undefined ? {} : { paging: { after } };
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                return await this.client.query(document, paging);
+            }
+            catch (error) {
+                if (isSnapshotStale(error) && attempt < STALE_RESENDS)
+                    continue;
+                throw this.#refusal(error);
+            }
+        }
+    }
+    /**
+     * A Kernel refusal as a `QueryError`. A network failure, or a refusal that prescribes when to
+     * send again (capacity, draining), is not the read's: it passes as it came, for the caller to
+     * retry.
+     */
+    #refusal(error) {
+        if (!(error instanceof ResponseError) || retryAfterOf(error) !== undefined)
+            return error;
+        const kernelCode = error.reason?.code ?? CODE_NAMES.get(error.code) ?? String(error.code);
+        const details = (error.reason?.details ?? {});
+        const cause = { cause: error };
+        if (isSnapshotStale(error))
+            return new QueryError('REFUSED', this.recipe, { kernelCode, retryable: true }, cause);
+        const refusals = refusalsOf(error);
+        if (refusals !== undefined) {
+            const path = refusals[0]?.path ?? (typeof details.path === 'string' ? details.path : undefined);
+            return new QueryError('INPUT_INVALID', this.recipe, {
+                kernelCode,
+                ...(typeof details.phase === 'string' ? { phase: details.phase } : {}),
+                ...(path === undefined ? {} : { path }),
+            }, { ...cause, ...(refusals.length === 0 ? {} : { reason: describeRefusals(refusals) }) });
+        }
+        if (kernelCode === 'QUERY_EXPECTATION_MISMATCH')
+            return new QueryError('OUTDATED', this.recipe, { kernelCode: 'QUERY_EXPECTATION_MISMATCH' }, cause);
+        // A Kernel that predates v7 refuses its request at the Function's input.
+        if (isUnserved(error))
+            return new QueryError('UNSUPPORTED', this.recipe, { feature: 'v7' }, cause);
+        // Only a trusted backend answers v7 (a maintenance session's refusal says when to retry).
+        if (kernelCode === 'QUERY_BACKEND_CONTRACT')
+            return new QueryError('UNSUPPORTED', this.recipe, { feature: 'v7' }, cause);
+        return new QueryError('REFUSED', this.recipe, { kernelCode, retryable: false }, cause);
+    }
+}
+/** A page document of `size` rows. */
+function withLimit(document, size) {
+    const list = document.list;
+    return { ...document, list: { ...list, limit: size } };
+}
+/** Each task, at most `limit` at once, the results in order; after a failure, no task starts. */
+async function pooled(tasks, limit) {
+    const results = [];
+    let next = 0;
+    let failed = false;
+    const worker = async () => {
+        while (!failed && next < tasks.length) {
+            const index = next++;
+            try {
+                results[index] = await tasks[index]();
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, worker));
+    return results;
+}
+const stepped = new WeakMap();
+/**
+ * The `steps` a recipe's `build` receives: two to eight steps, the first a record of facets and
+ * each next one a function of the merged results before it. It reads nothing: what it returns is
+ * read when `build` returns it.
+ */
+export function stepsFor(recipe) {
+    return (...steps) => {
+        if (steps.length < 2 || steps.length > MAXIMUM_STEPS)
+            throw new TypeError(`Recipe ${recipe}: steps takes 2 to ${MAXIMUM_STEPS} steps; got ${steps.length}. ${steps.length < 2
+                ? 'Reads that wait for none are what build returns: one read, or a record of facets.'
+                : 'Read the facets that wait for the same results in one step.'}`);
+        const [first, ...next] = steps;
+        if (!isFacets(first))
+            throw new TypeError(`Recipe ${recipe}: the first step is a record of facets; got ${described(first)}.`);
+        const position = next.findIndex((step) => typeof step !== 'function');
+        if (position !== -1)
+            throw new TypeError(`Recipe ${recipe}: each step after the first is a function of the results before it; step ${position + 2} is ${describe(next[position])}.`);
+        const value = Object.freeze({});
+        stepped.set(value, Object.freeze({ first, next: Object.freeze(next) }));
+        return value;
+    };
+}
+/** A record of facets: a plain object, neither a read nor what `steps` returned. */
+function isFacets(value) {
+    if (typeof value !== 'object' || value === null || isRead(value) || stepped.has(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** What a step was, for its refusal: `steps(…)` and a Promise are named with their fix. */
+function described(value) {
+    if (typeof value === 'object' && value !== null && stepped.has(value))
+        return 'steps(…), which only build returns';
+    if (value instanceof Promise)
+        return 'a Promise: build and its steps are not async';
+    return describe(value);
+}
+/** The steps `build` returned, or `undefined` for one read or one record of facets. */
+export function stepsOf(built) {
+    return typeof built === 'object' && built !== null ? stepped.get(built) : undefined;
+}
+/**
+ * The facets a step returned, each a read, a list of reads (`items.map`) or nothing. One read is
+ * `build`'s alone, without steps: each step returns a record of facets.
+ */
+function facetsOf(recipe, built, single) {
+    if (!isFacets(built)) {
+        const expected = single
+            ? 'build returns one read, a record of facets, or steps(…)'
+            : 'each step returns a record of facets';
+        throw new TypeError(`Recipe ${recipe}: ${expected}; got ${described(built)}.`);
+    }
+    return Object.entries(built);
+}
+/** A page is a recipe's single read: one step that returns it. */
+function refusePage(recipe, plan) {
+    if (plan.verb === 'page')
+        throw new TypeError(`Recipe ${recipe}: a page is a recipe's single read (D22); read the others with first or all.`);
+}
+/**
+ * The reads of one step, admitted (S11, S12): a single read, or each facet's in order and the
+ * shape that puts their results back. A facet takes a name no `earlier` step read: the merged
+ * results keep one value per name.
+ */
+export function planStep(run, built, single, earlier = {}) {
+    if (single && isRead(built)) {
+        const plans = [planOf(built)];
+        run.admit(plans);
+        return { plans };
+    }
+    const facets = facetsOf(run.recipe, built, single);
+    for (const [name] of facets)
+        if (Object.hasOwn(earlier, name))
+            throw new TypeError(`Recipe ${run.recipe}: an earlier step read the facet ${name}; name this step's facet otherwise.`);
+    const plans = [];
+    const shape = [];
+    for (const [name, facet] of facets) {
+        if (facet === undefined)
+            shape.push([name, undefined]);
+        else if (Array.isArray(facet))
+            shape.push([name, facet.map((read) => plans.push(planOf(read)) - 1)]);
+        else
+            shape.push([name, plans.push(planOf(facet)) - 1]);
+    }
+    plans.forEach((plan) => refusePage(run.recipe, plan));
+    run.admit(plans);
+    return { plans, shape };
+}
+/** The results of one step: a read's result, or a record of each facet's. */
+async function runStep(run, built, single, call, earlier) {
+    const { plans, shape } = planStep(run, built, single, earlier);
+    if (shape === undefined) {
+        const plan = plans[0];
+        return run.read(plan, plan.verb === 'page' ? call : undefined);
+    }
+    const results = await pooled(plans.map((plan) => () => run.read(plan)), IN_FLIGHT);
+    const record = {};
+    for (const [name, at] of shape)
+        record[name] =
+            at === undefined
+                ? undefined
+                : typeof at === 'number'
+                    ? results[at]
+                    : Object.freeze(at.map((index) => results[index]));
+    return Object.freeze(record);
+}
+/** The size and cursor of a page call, checked against the page's `max`. */
+function pageCall(recipe, call, max) {
+    const { size, after } = call;
+    if (max === undefined) {
+        if (size !== undefined || after !== undefined)
+            throw new TypeError(`Recipe ${recipe} is not a page: size and after continue a page recipe.`);
+        return {};
+    }
+    if (size !== undefined && (!Number.isInteger(size) || size < 1 || size > max))
+        throw new TypeError(`Recipe ${recipe}: size is a whole number from 1 to the page's max, ${max}; got ${describe(size)}.`);
+    if (after !== undefined && (typeof after !== 'string' || after.length === 0))
+        throw new TypeError(`Recipe ${recipe}: after is the cursor a page returned as next.`);
+    return { size: size ?? max, ...(after === undefined ? {} : { after }) };
+}
+/**
+ * Run a recipe for `input` against `domain`, the resolved Domain it was written for: what `build`
+ * returns, each of its steps in order, then its `output`. A page recipe takes its call's `size`
+ * and `after`. A read the Kernel refuses raises a `QueryError`; `output` raises the recipe's
+ * declared errors. With the Class requirements
+ * the Domain's build `declared`, each step's relations are checked against them first (S12).
+ */
+export async function runQueryRecipe(client, domain, recipe, input, call = {}, declared) {
+    const spec = recipeSpecOf(recipe);
+    if (spec === undefined)
+        throw new TypeError(`Not a v7 recipe: define one with defineQuery<Schema>()(id, { build }); got ${describe(recipe)}.`);
+    const run = new Run(client, domain, recipe.id, declared);
+    const built = spec.build(input, handlesOf(domain), stepsFor(recipe.id));
+    const steps = stepsOf(built);
+    let answered;
+    if (steps === undefined) {
+        const page = isRead(built) && planOf(built).verb === 'page';
+        const options = pageCall(recipe.id, call, page ? planOf(built).bound : undefined);
+        answered = await runStep(run, built, true, options, {});
+    }
+    else {
+        pageCall(recipe.id, call, undefined);
+        let merged = {};
+        for (const step of [() => steps.first, ...steps.next]) {
+            const results = await runStep(run, step(Object.freeze({ ...merged })), false, {}, merged);
+            merged = { ...merged, ...results };
+        }
+        answered = Object.freeze(merged);
+    }
+    if (spec.output === undefined)
+        return answered;
+    return spec.output(answered, input, outputContext(recipe, run.model));
+}
+/**
+ * The context a recipe's `output`, or a Mutation recipe's `reject`, receives: its declared errors,
+ * and `is`, which narrows a row by Class.
+ */
+export function outputContext(recipe, model) {
+    return {
+        error: declaredErrorFactory(recipe),
+        is: (row, cls) => {
+            try {
+                return model.satisfies(model.classOf(row.$class)).has(cls);
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}

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

@@ -0,0 +1,37 @@
+/**
+ * The Kernel's rejections of a v7 Query, made readable: its refusals (`QUERY_INPUT_INVALID`), and
+ * a Host that does not serve v7 at all (`FUNCTION_INPUT_INVALID`).
+ */
+import { ResponseError } from '../../../platform/client/index.js';
+/** A decode refusal, as the wire writes it: the fault's JSON pointer, what it takes, a fix. */
+export interface QueryDecodeRefusal {
+    readonly phase: 'decode';
+    readonly code: string;
+    /** RFC 6901, into the request `{document, paging}` the SDK sent. */
+    readonly path: string;
+    readonly expected: string;
+    readonly fix: string;
+    readonly tier?: string;
+}
+/** A planning refusal: the issue and its pointer into the request. */
+export interface QueryPlanRefusal {
+    readonly phase: 'plan';
+    readonly issue: string;
+    readonly path?: string;
+}
+/** A caller-visible plan bound the Query exceeds. */
+export interface QueryLimitRefusal {
+    readonly phase: 'plan';
+    readonly issue: 'QUERY_PLAN_LIMIT_EXCEEDED';
+    readonly limit: string;
+    readonly maximum: number;
+    readonly actual: number;
+    readonly path?: string;
+}
+export type QueryRefusal = QueryDecodeRefusal | QueryPlanRefusal | QueryLimitRefusal;
+/** The refusals a `QUERY_INPUT_INVALID` rejection carries, or `undefined` for any other error. */
+export declare function refusalsOf(error: unknown): readonly QueryRefusal[] | undefined;
+/** The refusals in one line: the first three, then how many more. */
+export declare function describeRefusals(refusals: readonly QueryRefusal[]): string;
+/** Whether a rejection of a v7 request says the Host does not serve it. */
+export declare function isUnserved(error: unknown): error is ResponseError;

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

@@ -0,0 +1,80 @@
+/**
+ * The Kernel's rejections of a v7 Query, made readable: its refusals (`QUERY_INPUT_INVALID`), and
+ * a Host that does not serve v7 at all (`FUNCTION_INPUT_INVALID`).
+ */
+import { ResponseError } from '../../../platform/client/index.js';
+const SHOWN = 3;
+const text = (value) => (typeof value === 'string' ? value : undefined);
+const count = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+/** The refusals a `QUERY_INPUT_INVALID` rejection carries, or `undefined` for any other error. */
+export function refusalsOf(error) {
+    if (!(error instanceof ResponseError) || error.reason?.code !== 'QUERY_INPUT_INVALID')
+        return undefined;
+    const details = error.reason.details;
+    if (details.phase === 'decode' && Array.isArray(details.refusals)) {
+        return Object.freeze(details.refusals.flatMap((entry) => {
+            const refusal = (entry ?? {});
+            const code = text(refusal.code);
+            const path = text(refusal.path);
+            if (code === undefined || path === undefined)
+                return [];
+            const tier = text(refusal.tier);
+            return [
+                Object.freeze({
+                    phase: 'decode',
+                    code,
+                    path,
+                    expected: text(refusal.expected) ?? '',
+                    fix: text(refusal.fix) ?? '',
+                    ...(tier === undefined ? {} : { tier }),
+                }),
+            ];
+        }));
+    }
+    const issue = text(details.issue);
+    if (details.phase !== 'plan' || issue === undefined)
+        return Object.freeze([]);
+    const path = text(details.path);
+    const limit = text(details.limit);
+    const maximum = count(details.maximum);
+    const actual = count(details.actual);
+    if (issue === 'QUERY_PLAN_LIMIT_EXCEEDED' &&
+        limit !== undefined &&
+        maximum !== undefined &&
+        actual !== undefined) {
+        return Object.freeze([
+            Object.freeze({
+                phase: 'plan',
+                issue,
+                limit,
+                maximum,
+                actual,
+                ...(path === undefined ? {} : { path }),
+            }),
+        ]);
+    }
+    return Object.freeze([
+        Object.freeze({ phase: 'plan', issue, ...(path === undefined ? {} : { path }) }),
+    ]);
+}
+function describe(refusal) {
+    if (refusal.phase === 'decode') {
+        const fix = refusal.fix.length === 0 ? '' : ` (${refusal.fix})`;
+        return `${refusal.code} at ${refusal.path}: expected ${refusal.expected}${fix}`;
+    }
+    const at = refusal.path === undefined ? '' : ` at ${refusal.path}`;
+    if ('limit' in refusal) {
+        return `${refusal.issue}${at}: its ${refusal.limit} limit is ${String(refusal.maximum)}, it needs ${String(refusal.actual)}`;
+    }
+    return `${refusal.issue}${at}`;
+}
+/** The refusals in one line: the first three, then how many more. */
+export function describeRefusals(refusals) {
+    const listed = refusals.slice(0, SHOWN).map(describe);
+    const rest = refusals.length > SHOWN ? `; and ${String(refusals.length - SHOWN)} more` : '';
+    return `${listed.join('; ')}${rest}`;
+}
+/** Whether a rejection of a v7 request says the Host does not serve it. */
+export function isUnserved(error) {
+    return error instanceof ResponseError && error.reason?.code === 'FUNCTION_INPUT_INVALID';
+}