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

package/dist/application/query/execution/{recipe.js → run.js}

@@ -2,69 +2,69 @@ 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 { querySpecOf } from '../defined/define.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 { 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 stage in flight at once. */
+/** 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. */
+/** One Query call: its reads so far, against S11, and the Classes they cross, against S12. */
 export class Run {
     client;
     domain;
-    recipe;
+    query;
     #reads = 0;
     #rows = 0;
     model;
     #crossings;
-    constructor(client, domain, recipe, declared) {
+    constructor(client, domain, query, declared) {
         this.client = client;
         this.domain = domain;
-        this.recipe = recipe;
+        this.query = query;
         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
+     * 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 });
+            throw new QueryError('TOO_MANY', this.query, { limit: 'reads', bound: MAXIMUM_READS });
         if (plans.some(pastPage))
-            throw new QueryError('TOO_MANY', this.recipe, { limit: 'rows', bound: MAXIMUM_BOUND });
+            throw new QueryError('TOO_MANY', this.query, { 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 });
+            throw new QueryError('TOO_MANY', this.query, { 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, {
+                throw new QueryError('INPUT_INVALID', this.query, {
                     limit: 'in',
                     path: `/document${path}`,
                 });
         }
         for (const plan of plans)
-            this.#crossings?.check(this.recipe, plan);
+            this.#crossings?.check(this.query, 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);
+            return emptyResult(this.query, plan);
         let document = plan.document;
         if (plan.verb === 'page' && paging?.size !== undefined)
             document = withLimit(document, paging.size);
@@ -78,7 +78,7 @@ export class Run {
                 requireAnswerConformance(this.domain, answer);
             answers.push(answer);
         }
-        return rootResult(this.recipe, this.model, plan, merge(document, answers));
+        return rootResult(this.query, this.model, plan, merge(document, answers));
     }
     async #send(document, after) {
         const paging = after === undefined ? {} : { paging: { after } };
@@ -105,25 +105,25 @@ export class Run {
         const details = (error.reason?.details ?? {});
         const cause = { cause: error };
         if (isSnapshotStale(error))
-            return new QueryError('REFUSED', this.recipe, { kernelCode, retryable: true }, cause);
+            return new QueryError('REFUSED', this.query, { 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, {
+            return new QueryError('INPUT_INVALID', this.query, {
                 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);
+            return new QueryError('OUTDATED', this.query, { 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);
+            return new QueryError('UNSUPPORTED', this.query, { 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);
+            return new QueryError('UNSUPPORTED', this.query, { feature: 'v7' }, cause);
+        return new QueryError('REFUSED', this.query, { kernelCode, retryable: false }, cause);
     }
 }
 /** A page document of `size` rows. */
@@ -151,37 +151,81 @@ async function pooled(tasks, limit) {
     await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, worker));
     return results;
 }
+const stepped = new WeakMap();
 /**
- * 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.
+ * The `steps` a Query'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.
  */
-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)}.`);
+export function stepsFor(query) {
+    return (...steps) => {
+        if (steps.length < 2 || steps.length > MAXIMUM_STEPS)
+            throw new TypeError(`Query ${query}: 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(`Query ${query}: 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(`Query ${query}: 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(query, 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(`Query ${query}: ${expected}; got ${described(built)}.`);
     }
     return Object.entries(built);
 }
-/** A page is a recipe's single read: one stage that returns it. */
-function refusePage(recipe, plan) {
+/** A page is a Query's single read: one step that returns it. */
+function refusePage(query, 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.`);
+        throw new TypeError(`Query ${query}: a page is a Query'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
+ * 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 planStage(run, built, single, earlier = {}) {
+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);
+    const facets = facetsOf(run.query, 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.`);
+            throw new TypeError(`Query ${run.query}: an earlier step read the facet ${name}; name this step's facet otherwise.`);
     const plans = [];
     const shape = [];
     for (const [name, facet] of facets) {
@@ -192,13 +236,13 @@ export function planStage(run, built, single, earlier = {}) {
         else
             shape.push([name, plans.push(planOf(facet)) - 1]);
     }
-    plans.forEach((plan) => refusePage(run.recipe, plan));
+    plans.forEach((plan) => refusePage(run.query, 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);
+/** 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);
@@ -215,55 +259,59 @@ async function runStage(run, built, single, call, earlier) {
     return Object.freeze(record);
 }
 /** The size and cursor of a page call, checked against the page's `max`. */
-function pageCall(recipe, call, max) {
+function pageCall(query, 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.`);
+            throw new TypeError(`Query ${query} is not a page: size and after continue a page Query.`);
         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)}.`);
+        throw new TypeError(`Query ${query}: 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.`);
+        throw new TypeError(`Query ${query}: 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).
+ * Run a Query 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 Query takes its call's `size`
+ * and `after`. A read the Kernel refuses raises a `QueryError`; `output` raises the Query'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);
+export async function runQuery(client, domain, query, input, call = {}, declared) {
+    const spec = querySpecOf(query);
     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 };
+        throw new TypeError(`Not a Query v7: define one with defineQuery<Schema>()(id, { build }); got ${describe(query)}.`);
+    const run = new Run(client, domain, query.id, declared);
+    const built = spec.build(input, handlesOf(domain), stepsFor(query.id));
+    const steps = stepsOf(built);
+    let answered;
+    if (steps === undefined) {
+        const page = isRead(built) && planOf(built).verb === 'page';
+        const options = pageCall(query.id, call, page ? planOf(built).bound : undefined);
+        answered = await runStep(run, built, true, options, {});
+    }
+    else {
+        pageCall(query.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);
     }
-    const answered = single ? results : Object.freeze(merged);
     if (spec.output === undefined)
         return answered;
-    return spec.output(answered, input, outputContext(recipe, run.model));
+    return spec.output(answered, input, outputContext(query, run.model));
 }
 /**
- * The context a recipe's `output`, or a Mutation recipe's `reject`, receives: its declared errors,
+ * The context a Query's `output`, or a defined Mutation's `reject`, receives: its declared errors,
  * and `is`, which narrows a row by Class.
  */
-export function outputContext(recipe, model) {
+export function outputContext(query, model) {
     return {
-        error: declaredErrorFactory(recipe),
+        error: declaredErrorFactory(query),
         is: (row, cls) => {
             try {
                 return model.satisfies(model.classOf(row.$class)).has(cls);

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

@@ -1,5 +1,5 @@
 import type { QueryCountAnswer, QueryExistsAnswer, QueryListAnswer } from '../answer/answer.js';
-import type { AnyQuery } from '../language/query.js';
+import type { QueryDocument } from '../language/query.js';
 /** The Kernel's set members per v7 document: ids and value-set points, guards included. */
 export declare const MAXIMUM_MEMBERS = 32768;
 type ListAnswer = QueryListAnswer<unknown, unknown>;
@@ -15,10 +15,10 @@ export declare function membersOf(value: unknown): number;
  * an ordered read can merge. A document whose members lie elsewhere is sent whole, and the Kernel
  * names the limit.
  */
-export declare function split(document: AnyQuery, values: boolean): readonly AnyQuery[];
+export declare function split(document: QueryDocument, values: boolean): readonly QueryDocument[];
 /**
  * The answers of a split read as one: a list merged in the document's order and cut to its limit,
  * `exists` if any slice has one, a count summed up to its bound.
  */
-export declare function merge(document: AnyQuery, answers: readonly Answer[]): Answer;
+export declare function merge(document: QueryDocument, answers: readonly Answer[]): Answer;
 export {};

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

@@ -1,5 +1,5 @@
 /**
- * Long id lists (spec § Recipes: the contract, § Semantics): a document past the Kernel's set
+ * Long id lists (spec § Queries: the contract, § Semantics): a document past the Kernel's set
  * members is sent as several, its root id list split, and their answers merged back in the
  * Kernel's order and cut to the read's limit. Only a Node root's id list splits, and only for a
  * read that is not a page: a page's cursor continues one document.

package/dist/application/query/handles/build.d.ts

@@ -1,5 +1,5 @@
 /**
- * The handles a recipe's `build` receives (S1), built once per resolved Domain: its own Classes,
+ * The handles a Query's `build` receives (S1), built once per resolved Domain: its own Classes,
  * each dependency under its alias, the Kernel's Classes under `kernel`, its Core nodes under
  * `core`, `origin`, and `document`, the escape hatch (D23). The fixed names win over a Class or
  * an alias of the same name.

package/dist/application/query/handles/domain.d.ts

@@ -1,5 +1,5 @@
 /**
- * The Domain a recipe reads, indexed once per Schema (spike designs D1, D3 and D10).
+ * The Domain a Query reads, indexed once per Schema (spike designs D1, D3 and D10).
  *
  * Every generic is keyed by the Schema type `S` and Class keys, never by resolved Classes:
  * instantiations are cached per (Schema, key), and messages print the key. The Domain is indexed

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

@@ -1,5 +1,5 @@
 /**
- * Typed handles over a Domain (spec § Recipes: the read layer): what a recipe's `build` receives,
+ * Typed handles over a Domain (spec § Queries: the read layer): what a Query's `build` receives,
  * and the reads it returns. Handles are interfaces with lazy members; the per-Class parts
  * (Properties, named relations, rows) are mapped types computed once per Class key (D5).
  */
@@ -11,7 +11,7 @@ import type { Cond, Conditions, HandleMembers, IsCond, Ordering, PropOf, PropsOf
 import type { Cls, Dom, KeyOf, LayoutOf, OriginOf, PropNamesOf, Satisfies, Single, Untyped, ValueOfEntry } from './domain.js';
 import type { Far, RelationsOf, SourceKeys, SourceRole, TargetKeys, TargetRole, ViaCheck, ViaOptions } from './relations.js';
 import type { Count, EdgeRootRef, EdgeRootRow, EdgeValues, Page, Ref, Row, RowKeys, WithheldEdgeRow, WithheldRow } from './rows.js';
-/** A read: what a verb returns, an opaque description the recipe runs, typed by its answer `T`. */
+/** A read: what a verb returns, an opaque description the Query runs, typed by its answer `T`. */
 export interface Read<out T> {
     readonly '~read': T;
 }
@@ -19,7 +19,7 @@ export interface Read<out T> {
 export interface RelationRead<out T> extends Read<T> {
     readonly '~relation': true;
 }
-/** One page of a root: only as a recipe's single read (D22). */
+/** One page of a root: only as a Query's single read (D22). */
 export interface PageRead<out T> {
     readonly '~page': T;
 }
@@ -39,21 +39,23 @@ type Answers<X> = {
  * at that name.
  */
 type WithCheck<S, K, W, X> = {
-    readonly [P in keyof X as P extends PropNamesOf<Cls<S, K>> | RowKeys | keyof W | `$${string}` ? P : X[P] extends RelationRead<unknown> ? never : P]: P extends PropNamesOf<Cls<S, K>> | RowKeys | keyof W | `$${string}` ? `✗ "${P & string}" is already a row key of this Class: give the .with another name` : `✗ "${P & string}" reads another root: read it as a facet of the recipe`;
+    readonly [P in keyof X as P extends PropNamesOf<Cls<S, K>> | RowKeys | keyof W | `$${string}` ? P : X[P] extends RelationRead<unknown> ? never : P]: P extends PropNamesOf<Cls<S, K>> | RowKeys | keyof W | `$${string}` ? `✗ "${P & string}" is already a row key of this Class: give the .with another name` : `✗ "${P & string}" reads another root: read it as a facet of the Query`;
 };
 type RowOf<S, K, W, M extends Rendering, H extends boolean> = ((M extends 'reference' ? Ref<S, K> : Row<S, K>) & W) | (H extends true ? WithheldRow<S, K> : never);
 /** The id of a Node, its path, or a Core node of the Domain. */
-export type Target = NodeId | NodePath | CoreNode<string>;
+export type Target = NodeId | NodePath | CoreNodeHandle<string>;
 /** A Core node of the Domain (`d.core.<node>`). */
-export interface CoreNode<Key extends string> {
+export interface CoreNodeHandle<Key extends string> {
     readonly '~core': Key;
 }
-interface IdProp {
+/** The `id` of a Node handle: its identity, matched by id, path or Core node. */
+export interface IdProp {
     eq(id: Target): Cond;
     /** Any length. */
     in(ids: readonly Target[]): Cond;
 }
-interface PathProp {
+/** The `path` of a Node handle. */
+export interface PathProp {
     eq(path: NodePath): Cond;
     in(paths: readonly NodePath[]): Cond;
 }
@@ -137,7 +139,7 @@ export interface NodeSet<S, K extends string, W, M extends Rendering, H extends
         readonly rows: readonly RowOf<S, K, W, M, H>[];
         readonly more: boolean;
     }>;
-    /** Only as a recipe's single read: the call sets the size, up to `max`, and continues it. */
+    /** Only as a Query's single read: the call sets the size, up to `max`, and continues it. */
     page(options: {
         readonly max: number;
     }): PageRead<RowOf<S, K, W, M, H>>;
@@ -233,10 +235,10 @@ type ClassHandles<S, Classes> = {
 type CoreHandles<Core> = Core extends {
     readonly nodes: infer Nodes;
 } ? {
-    readonly [N in keyof Nodes]: CoreNode<KeyOf<Nodes[N]>>;
+    readonly [N in keyof Nodes]: CoreNodeHandle<KeyOf<Nodes[N]>>;
 } : never;
 /** The escape hatch: one canonical document, its rows typed `unknown` (D23). */
-interface DocumentRead<S> {
+export interface DocumentRead<S> {
     document(query: Extract<SizedQuery<S>, {
         readonly list: unknown;
     }>): Read<readonly unknown[]>;
@@ -248,7 +250,7 @@ interface DocumentRead<S> {
     }>): Read<Count>;
 }
 /**
- * The handles a recipe's `build` receives (S1): the Domain's own Classes, each dependency under
+ * The handles a Query's `build` receives (S1): the Domain's own Classes, each dependency under
  * its alias, the Kernel's Classes under `d.kernel`, the Domain's Core nodes under `d.core`, and
  * `d.origin`. A Class the Domain neither declares nor depends on has no handle.
  */

package/dist/application/query/handles/plan.d.ts

@@ -1,11 +1,11 @@
 /**
- * What a read lowers to: its canonical v7 document, and the plan the recipe runtime answers it
+ * What a read lowers to: its canonical v7 document, and the plan the Query runtime answers it
  * by (WP-S3): the verb, its bound, and for each pattern the Classes its rows may be, how they
  * render and the relations they carry. A read whose condition can match nothing is `empty`: it
  * has no document, and the runtime answers it without sending. When the input folds a condition
  * (an empty list), the read keeps its document as written: the one S12 checks.
  */
-import type { AnyQuery } from '../language/query.js';
+import type { QueryDocument } from '../language/query.js';
 import type { Scope } from './terms.js';
 /** The verbs of a root read; `document` is the escape hatch (D23). */
 export type Verb = 'get' | 'find' | 'first' | 'firstN' | 'firstMore' | 'page' | 'all' | 'exists' | 'count' | 'document';
@@ -34,16 +34,17 @@ export interface BranchPlan extends Pattern {
     readonly bound?: number;
     /** Its condition matches nothing: it is not sent, and every parent gets the empty answer. */
     readonly empty: boolean;
-    /** Each row carries `$edge` (`.withEdge()`). */
-    readonly edge: boolean;
+    /** Each row carries `$edge` (`.withEdge()`): the Edge's Class, and its values when selected. */
+    readonly edge?: Rendering;
 }
 export interface NodeRootPlan extends Pattern {
     readonly kind: 'nodes';
 }
-/** One end of an Edge root: its role on the rows, and the Classes it accepts. */
+/** One end of an Edge root: its role on the rows, the Classes it accepts, how it is answered. */
 export interface EndPlan {
     readonly role: string;
     readonly classes: readonly string[];
+    readonly select: Rendering;
 }
 export interface EdgeRootPlan {
     readonly kind: 'edges';
@@ -61,9 +62,9 @@ export interface ReadPlan {
     /** Its condition matches nothing: answered without sending. */
     readonly empty: boolean;
     /** Absent when `empty`. */
-    readonly document?: AnyQuery;
+    readonly document?: QueryDocument;
     /** The document as written, when the input folds it: as no empty list folds it. */
-    readonly written?: AnyQuery;
+    readonly written?: QueryDocument;
     /** Absent for `document`, whose rows are unknown. */
     readonly root?: NodeRootPlan | EdgeRootPlan;
     /** The id or path `get`, `find` or `exists` was given, as `NOT_FOUND` names it. */
@@ -91,9 +92,9 @@ export declare class RelationRead {
     /** The handle it was read from: a `.with` takes only its own handle's relations. */
     scope: Scope, lower: (key: string, name: string) => LoweredBranch);
 }
-/** Whether a value is a read a recipe runs (a root read). */
+/** Whether a value is a read a Query runs (a root read). */
 export declare function isRead(value: unknown): value is RootRead;
 /** The plan of a root read. */
 export declare function planOf(read: unknown): ReadPlan;
 /** The canonical document of a root read; an `empty` read has none. */
-export declare function lower(read: unknown): AnyQuery | undefined;
+export declare function lower(read: unknown): QueryDocument | undefined;

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

@@ -18,7 +18,7 @@ export class RelationRead {
         Object.freeze(this);
     }
 }
-/** Whether a value is a read a recipe runs (a root read). */
+/** Whether a value is a read a Query runs (a root read). */
 export function isRead(value) {
     return value instanceof RootRead;
 }

package/dist/application/query/handles/reads.js

@@ -2,7 +2,7 @@ var _a, _b, _c;
 import { QUERY } from '../language/query.js';
 import { HANDLE_MEMBERS, ROW_KEYS } from './model.js';
 import { RelationRead, RootRead } from './plan.js';
-import { and, atom, Condition, describe, foldedTo, folding, kept, orderKeys, propertyHandle, scope, targetCondition, targetLabel, whereOf, within, } from './terms.js';
+import { and, atom, Condition, describe, foldedTo, folding, isPathText, kept, orderKeys, propertyHandle, scope, targetCondition, targetLabel, whereOf, within, } from './terms.js';
 const defined = (fields) => Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
 const nonEmpty = (items) => items.length > 0 ? items : undefined;
 const keysOf = (classes) => classes.map((c) => c.key);
@@ -221,8 +221,8 @@ function pathCondition(context, paths) {
     if (paths.length === 0)
         return foldedTo(Condition.NEVER, atom(context, { op: 'path', paths: [] }));
     for (const path of paths)
-        if (typeof path !== 'string' || !path.startsWith('/'))
-            throw new TypeError(`A path starts with "/"; got ${describe(path)}.`);
+        if (!isPathText(path))
+            throw new TypeError(`A path starts with "/" or "@"; got ${describe(path)}.`);
     return atom(context, { op: 'path', paths });
 }
 /** The named to-one relation of a handle's Classes: on a union, one every Class names alike. */
@@ -280,7 +280,7 @@ function withsOf(value, handleScope, taken, earlier) {
             throw new TypeError(`"${name}" is already a row key of this Class: give the .with another name.`);
         const read = entry instanceof Exists ? entry.read : entry;
         if (read instanceof RootRead)
-            throw new TypeError(`"${name}" reads another root: read it as a facet of the recipe.`);
+            throw new TypeError(`"${name}" reads another root: read it as a facet of the Query.`);
         if (!(read instanceof RelationRead))
             throw new TypeError(`"${name}" is not a relation read: end the relation with a verb (find, first, all, count, exists).`);
         if (read.scope !== handleScope)
@@ -445,7 +445,7 @@ export class Relation {
                 verb,
                 ...(bound === undefined ? {} : { bound }),
                 empty: sent === undefined,
-                edge: s.selectEdge,
+                ...(s.selectEdge ? { edge: 'value' } : {}),
                 classes: keysOf(s.far),
                 select: s.select,
                 withheld: s.withheld,
@@ -780,8 +780,8 @@ export class EdgeSet {
             classes: [edge.key],
             select: this.#s.select,
             withheld: this.#s.withheld,
-            source: { role: source.role, classes: keysOf(model.far(source)) },
-            target: { role: target.role, classes: keysOf(model.far(target)) },
+            source: { role: source.role, classes: keysOf(model.far(source)), select: this.#s.select },
+            target: { role: target.role, classes: keysOf(model.far(target)), select: this.#s.select },
         };
     }
     #list(verb, limit, bound) {

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

@@ -38,7 +38,7 @@ export type WithheldRow<S, K> = K extends unknown ? {
     readonly $withheld: readonly PropNamesOf<Cls<S, K>>[];
 } : never;
 /**
- * An Edge's identity: its Class and both ends. An object type, not an interface: a recipe's
+ * An Edge's identity: its Class and both ends. An object type, not an interface: a Query's
  * exported declaration then spells it out.
  */
 type EdgeIdentity<E> = {

package/dist/application/query/handles/terms.d.ts

@@ -89,7 +89,15 @@ export declare class CoreNode {
     readonly '~core': string;
     constructor(key: string, path: string);
 }
-/** The condition a list of targets gives: ids by `id`, paths and Core nodes by `path`. */
+/**
+ * Whether text is written as a NodePath: it starts with `/` (a Domain anchor) or `@` (a Node's id
+ * as its anchor). A NodeId holds neither, so the two never meet.
+ */
+export declare function isPathText(value: unknown): value is string;
+/**
+ * The condition a list of targets gives: ids by `id`, an `@<id>` path by its id, so a long list
+ * splits as ids do; any other path, and a Core node, by `path`.
+ */
 export declare function targetCondition(context: Context, targets: readonly unknown[]): Condition;
 /** A target as an error names it: its id or its path. */
 export declare function targetLabel(target: unknown): string;