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

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,70 @@
+/**
+ * Run a v7 recipe (WP-S3): its stages in order, each one's reads together, at most 8 in flight,
+ * each read at its own snapshot (the stand-in); then `output`. A stage'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 : {});
+/** 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 stage 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>;
+}
+/** 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 stage, 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` stage read: the merged
+ * results keep one value per name.
+ */
+export declare function planStage(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: its stages,
+ * 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 stage'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,276 @@
+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, 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 stage 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 stage 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;
+}
+/**
+ * The facets a stage returned, each a read, a list of reads (`items.map`) or nothing. One read is
+ * a single stage's alone: each of several returns a record of facets.
+ */
+function facetsOf(recipe, built, single) {
+    if (typeof built !== 'object' || built === null || Array.isArray(built) || isRead(built)) {
+        const expected = single ? 'a stage returns one read or' : 'each of several stages returns';
+        throw new TypeError(`Recipe ${recipe}: ${expected} a record of facets; got ${describe(built)}.`);
+    }
+    return Object.entries(built);
+}
+/** A page is a recipe's single read: one stage 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 stage, 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` stage read: the merged
+ * results keep one value per name.
+ */
+export function planStage(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 stage read the facet ${name}; name this stage'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 stage: a read's result, or a record of each facet's. */
+async function runStage(run, built, single, call, earlier) {
+    const { plans, shape } = planStage(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: its stages,
+ * 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 stage'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 d = handlesOf(domain);
+    const single = spec.stages.length === 1;
+    let results;
+    let merged = {};
+    for (const [index, stage] of spec.stages.entries()) {
+        const built = index === 0
+            ? stage(input, d)
+            : stage(Object.freeze({ ...merged }), input, d);
+        const page = single && isRead(built) && planOf(built).verb === 'page';
+        const options = pageCall(recipe.id, call, page ? planOf(built).bound : undefined);
+        results = await runStage(run, built, single, options, merged);
+        merged = { ...merged, ...results };
+    }
+    const answered = single ? results : 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';
+}

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

@@ -0,0 +1,42 @@
+/**
+ * A read's answer as rows (spec § Semantics): each item rendered by the layout of the Class the
+ * plan reads it as, each verb's rule applied (`get` exactly one, `find` at most one, `all` at most
+ * `max`), and a fact the reader may not read left out, kept by `.includeWithheld()`, or an error
+ * where `get` and `find` meet one. Rows and lists are frozen portable JSON.
+ */
+import type { NodeId } from '../../../platform/graph/node/index.js';
+import type { QueryListAnswer } from '../answer/answer.js';
+import type { Model } from '../handles/model.js';
+import type { EdgeRootPlan, NodeRootPlan, Pattern, ReadPlan } from '../handles/plan.js';
+import type { EdgeKey } from '../handles/rows.js';
+type Json = Readonly<Record<string, unknown>>;
+type FactId = NodeId | EdgeKey;
+/** One delivered item; a Kernel with K-C gives each Node item its Class. */
+interface Item {
+    readonly fact: FactId;
+    readonly class?: string;
+    readonly edge?: EdgeKey;
+    readonly source?: Item;
+    readonly target?: Item;
+    readonly branches: Readonly<Record<string, unknown>>;
+}
+/** What renders one answer: the recipe it errs for, the Domain's Classes, the answer's facts. */
+export declare class Renderer {
+    #private;
+    readonly recipe: string;
+    readonly model: Model;
+    constructor(recipe: string, model: Model, answer: QueryListAnswer<unknown, unknown>);
+    /** A Node row, or `undefined` when the reader may not read it and the read does not keep it. */
+    node(item: Item, pattern: Pattern): Json | undefined;
+    /** An Edge root row: its identity, its values and both ends by role. */
+    edge(item: Item, plan: EdgeRootPlan): Json | undefined;
+    /** The rows of a root list, Node or Edge, leaving out what the reader may not read. */
+    rootRows(items: readonly Item[], root: NodeRootPlan | EdgeRootPlan): readonly Json[];
+    /** The one root row `get` or `find` gives. */
+    rootOne(item: Item, root: NodeRootPlan | EdgeRootPlan): Json;
+}
+/** The answer of a root read with nothing to read: its verb's empty answer. */
+export declare function emptyResult(recipe: string, plan: ReadPlan): unknown;
+/** A root read's result from its answer, by its verb. */
+export declare function rootResult(recipe: string, model: Model, plan: ReadPlan, answer: unknown): unknown;
+export {};