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

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

@@ -11,7 +11,7 @@ interface CompositeQueryProjector<Schema extends schema.DomainSchema> {
     <Input, Output>(project: (domain: ResolvedDomainOf<Schema>) => Omit<RawCompositeQuery<Input, Output, ResolvedDomainOf<Schema>>, 'kind'>): CompositeQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
     <Input, Composed, Output, Plan extends QueryPlan<Composed> = QueryPlan<Composed>>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredInferredComposite<Input, Composed, Plan, Output, ResolvedDomainOf<Schema>>): CompositeQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
 }
-/** Define one inert composite Query recipe projected from its exact loaded Domain. */
+/** Define one inert composite Query projected from its exact loaded Domain. */
 export declare function defineCompositeQuery<Schema extends schema.DomainSchema>(): CompositeQueryProjector<Schema>;
 export declare function realizeQuery<DomainValue extends Domain, Input, Output>(query: QueryDefinition<DomainValue, Input, Output>, domain: DomainValue): RealizedQuery<Input, Output>;
 export {};

package/dist/application/query/define.js

@@ -1,10 +1,10 @@
 import { isDomain } from '@astrale-os/kernel-dsl/v1/domain';
-import { definitionBase, isPromiseLike, projectorOf, recipe } from './definition.js';
+import { definitionBase, isPromiseLike, projectorOf, inertQuery } from './definition.js';
 import { admitSingle } from './legacy/v6/define.js';
 const realized = new WeakMap();
-/** Define one inert composite Query recipe projected from its exact loaded Domain. */
+/** Define one inert composite Query projected from its exact loaded Domain. */
 export function defineCompositeQuery() {
-    return ((project) => recipe('composite-query', project));
+    return ((project) => inertQuery('composite-query', project));
 }
 export function realizeQuery(query, domain) {
     const project = projectorOf(query);

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

@@ -0,0 +1,45 @@
+/**
+ * `defineQuery<Schema>()`: one name for both forms. A string id first defines a Query v7; a
+ * function first defines a V6 Query, which stays in `legacy/v6`. A Query v7 is inert: its id and
+ * the errors it declares are public, and what it reads is kept for the runtime (WP-S3).
+ */
+import type { schema } from '../../../platform/schema/index.js';
+import type { SingleQueryProjector } from '../legacy/v6/define.js';
+import type { DefinedQuery, DefinedQueryFactory } from './query.js';
+/** A Query or Mutation id: lowercase segments of letters, digits and hyphens, joined by dots. */
+export declare const DEFINITION_ID: RegExp;
+export declare const MAXIMUM_DEFINITION_ID = 128;
+type Callback = (...parameters: never[]) => unknown;
+/** What a Query reads and answers: its `build`, of `(input, d, steps)`, and its `output`. */
+export interface QuerySpec {
+    readonly build: Callback;
+    readonly output?: Callback;
+}
+/** The build and the output of a Query v7; `undefined` for anything else. */
+export declare function querySpecOf(query: unknown): QuerySpec | undefined;
+/** A definition of the Domain's namespace, a Query's or a Mutation's: its id, and its errors. */
+export type NamedDefinition = Pick<DefinedQuery, 'id' | 'errors'>;
+/**
+ * Keep the errors a definition declares, a Query's or a Mutation's, and collect it into the
+ * collections open: a defined Mutation shares its Domain's Query ids and error definitions.
+ */
+export declare function collectDefinition(query: NamedDefinition): void;
+/**
+ * Collect into `queries` each Query or Mutation defined while `load` runs: a build collects the
+ * definitions that loading its Domain defines, and checks them with `admitDefinitions`. A module an
+ * earlier load of the same process evaluated defines nothing again, so its definitions were checked
+ * with that load.
+ */
+export declare function collectDefinitions<T>(queries: NamedDefinition[], load: () => Promise<T>): Promise<T>;
+/**
+ * Refuse two definitions of one Domain under one id: a refusal and a call name a Query or Mutation
+ * by its id. Refuse two that declare one code with different definitions: a Function that spreads
+ * both errors keeps one of them, and would redact the other definition's error.
+ */
+export declare function admitDefinitions(queries: readonly NamedDefinition[]): void;
+/**
+ * Define a Query: `defineQuery<Schema>()('services.service.owner', { build, output?, errors? })`.
+ * The V6 form, `defineQuery<Schema>()((domain) => ({ id, build, project? }))`, stays.
+ */
+export declare function defineQuery<Schema extends schema.DomainSchema>(): SingleQueryProjector<Schema> & DefinedQueryFactory<Schema>;
+export {};

package/dist/application/query/defined/define.js

@@ -0,0 +1,96 @@
+import { rememberDefinedErrors } from '../../error/error.js';
+import { describe } from '../handles/terms.js';
+import { defineQuery as defineV6Query } from '../legacy/v6/define.js';
+/** A Query or Mutation id: lowercase segments of letters, digits and hyphens, joined by dots. */
+export const DEFINITION_ID = /^[a-z0-9-]+(?:\.[a-z0-9-]+)*$/u;
+export const MAXIMUM_DEFINITION_ID = 128;
+const FIELDS = new Set(['build', 'output', 'errors']);
+const specs = new WeakMap();
+/** The collections open while a build loads a Domain; no definition is kept outside one. */
+const collections = new Set();
+/** The build and the output of a Query v7; `undefined` for anything else. */
+export function querySpecOf(query) {
+    return typeof query === 'object' && query !== null ? specs.get(query) : undefined;
+}
+function defineV7Query(id, spec) {
+    if (typeof id !== 'string' || id.length > MAXIMUM_DEFINITION_ID || !DEFINITION_ID.test(id))
+        throw new TypeError(`A Query id is lowercase segments of letters, digits and hyphens joined by dots, at most ${MAXIMUM_DEFINITION_ID} characters ('services.service.owner'); got ${describe(id)}.`);
+    if (typeof spec !== 'object' || spec === null || Array.isArray(spec))
+        throw new TypeError(`Query ${id} takes { build, output?, errors? }; got ${describe(spec)}.`);
+    const fields = spec;
+    const unknown = Reflect.ownKeys(fields).filter((key) => typeof key !== 'string' || !FIELDS.has(key));
+    if (unknown.length > 0)
+        throw new TypeError(`Query ${id} takes build, output and errors only; got ${unknown.map(String).join(', ')}: do that work in build or output.`);
+    const { build, output } = fields;
+    if (typeof build !== 'function')
+        throw new TypeError(`Query ${id}'s build is a function of (input, d, steps) that returns a read, a record of facets, or steps(first, (earlier) => next, …); got ${describe(build)}.`);
+    if (output !== undefined && typeof output !== 'function')
+        throw new TypeError(`Query ${id}'s output is a function of (results, input, context); got ${describe(output)}.`);
+    const errors = fields.errors ?? {};
+    if (typeof errors !== 'object' || errors === null || Array.isArray(errors))
+        throw new TypeError(`Query ${id}'s errors is a record of declared errors by UPPER_SNAKE code; got ${describe(errors)}.`);
+    const query = Object.freeze({ id, errors: Object.freeze({ ...errors }) });
+    collectDefinition(query);
+    specs.set(query, Object.freeze({
+        build: build,
+        ...(output !== undefined ? { output: output } : {}),
+    }));
+    return query;
+}
+/**
+ * Keep the errors a definition declares, a Query's or a Mutation's, and collect it into the
+ * collections open: a defined Mutation shares its Domain's Query ids and error definitions.
+ */
+export function collectDefinition(query) {
+    rememberDefinedErrors(query, query.id, query.errors);
+    for (const collection of collections)
+        collection.push(query);
+}
+/**
+ * Collect into `queries` each Query or Mutation defined while `load` runs: a build collects the
+ * definitions that loading its Domain defines, and checks them with `admitDefinitions`. A module an
+ * earlier load of the same process evaluated defines nothing again, so its definitions were checked
+ * with that load.
+ */
+export async function collectDefinitions(queries, load) {
+    collections.add(queries);
+    try {
+        return await load();
+    }
+    finally {
+        collections.delete(queries);
+    }
+}
+/**
+ * Refuse two definitions of one Domain under one id: a refusal and a call name a Query or Mutation
+ * by its id. Refuse two that declare one code with different definitions: a Function that spreads
+ * both errors keeps one of them, and would redact the other definition's error.
+ */
+export function admitDefinitions(queries) {
+    const ids = new Set();
+    for (const { id } of queries) {
+        if (ids.has(id))
+            throw new TypeError(`Two Queries or Mutations of the Domain are named ${id}: an id is unique in its Domain.`);
+        ids.add(id);
+    }
+    const first = new Map();
+    for (const query of queries) {
+        for (const [code, declaration] of Object.entries(query.errors)) {
+            const seen = first.get(code);
+            if (seen === undefined)
+                first.set(code, { query: query.id, declaration });
+            else if (seen.declaration !== declaration)
+                throw new TypeError(`${seen.query} and ${query.id} declare ${code} with different definitions: declare it once and share that object, so a Function that re-declares both keeps each.`);
+        }
+    }
+}
+/**
+ * Define a Query: `defineQuery<Schema>()('services.service.owner', { build, output?, errors? })`.
+ * The V6 form, `defineQuery<Schema>()((domain) => ({ id, build, project? }))`, stays.
+ */
+export function defineQuery() {
+    const v6 = defineV6Query();
+    return ((first, spec) => typeof first === 'string'
+        ? defineV7Query(first, spec)
+        : v6(first));
+}

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

@@ -0,0 +1,135 @@
+/**
+ * A Query (spec § Queries: the contract): an id, a `build` over the Domain's handles, an optional
+ * `output` and the errors it declares. `build` returns one read, a record of facets read together,
+ * or, when reads wait for others, `steps(first, (earlier) => next, …)`: two to eight records of
+ * facets, each function receiving the merged results of the steps before it.
+ */
+import type { z } from 'zod';
+import type { DeclaredErrorDefinition } from '../../../platform/schema/error.js';
+import type { ClassOf, Index, KeyOf, Values } from '../handles/domain.js';
+import type { Handles, PageRead, Read } from '../handles/handles.js';
+import type { Page } from '../handles/rows.js';
+/** One facet: a read, a list of reads (`items.map(…)`), or nothing (a read that is optional). */
+export type Facet = Read<unknown> | readonly Read<unknown>[] | undefined;
+/** Facets read together, by name. */
+export type Facets = {
+    readonly [facet: string]: Facet;
+};
+/** What `build` returns without steps, and the first step: one read, or a record of facets. */
+export type Built = Read<unknown> | Facets;
+/** A read gives its answer; a list of reads a list of answers; nothing gives `undefined`. */
+export type FacetResult<F> = F extends Read<infer T> ? T : F extends readonly Read<infer T>[] ? readonly T[] : F extends undefined ? undefined : never;
+/** The results of one step; a page read, a Query's single read, gives its `Page`. */
+export type Results<B> = B extends Read<infer T> ? T : B extends PageRead<infer T> ? Page<T> : {
+    readonly [K in keyof B]: FacetResult<B[K]>;
+};
+/** What a page Query's `output` keeps: the page shape. */
+type PageShape<B> = B extends PageRead<unknown> ? Page<unknown> : unknown;
+/** One object type: a Domain's exported declarations spell it out, naming no SDK internal. */
+type Flat<T> = T extends unknown ? {
+    readonly [K in keyof T]: T[K];
+} : never;
+/**
+ * A later step's facets: none takes a name an earlier step read, whose result the merge would
+ * replace. An index signature (its `string` and `number` keys) names no facet in particular, so it
+ * refuses none.
+ */
+type Later<Earlier> = Facets & {
+    readonly [K in keyof Earlier as string extends K ? never : number extends K ? never : K]?: '✗ an earlier step read this facet: name it otherwise';
+};
+/** The results of the steps so far, merged. */
+export type Merged<B1, B2, B3 = {}, B4 = {}, B5 = {}, B6 = {}, B7 = {}, B8 = {}> = Flat<Results<B1> & Results<B2> & Results<B3> & Results<B4> & Results<B5> & Results<B6> & Results<B7> & Results<B8>>;
+/** The errors a Query or Mutation declares, by UPPER_SNAKE code: at most 32. */
+export type Errors = {
+    readonly [code: string]: DeclaredErrorDefinition;
+};
+/** The key of any Class of the Domain, its dependencies' or the Kernel's. */
+export type ClassKeyOf<S> = KeyOf<Values<Index<S>>>;
+/** A declared error of a Query, for `output` to throw. */
+export interface DeclaredError<out C extends string> extends Error {
+    readonly '~code'?: C;
+}
+/** A row narrowed to a Class or any of its subclasses: the union members it may be, and `$class`. */
+export type Narrowed<S, R extends {
+    readonly $class: string;
+}, K> = R extends unknown ? [Extract<R['$class'], ClassOf<S, K>>] extends [never] ? never : R & {
+    readonly $class: Extract<R['$class'], ClassOf<S, K>>;
+} : never;
+/** What `output` receives besides the results and the input. */
+export interface OutputContext<S, E extends Errors> {
+    /** A declared error, for `output` to throw: `throw error('SERVICE_NOT_FOUND', { service })`. */
+    error<C extends keyof E & string>(code: C, details: z.input<E[C]['details']>): DeclaredError<C>;
+    /** Narrows a row to a Class or any of its subclasses, by Class key. */
+    is<R extends {
+        readonly $class: string;
+    }, K extends ClassKeyOf<S>>(row: R, cls: K): row is Narrowed<S, R, K>;
+}
+/** A Query v7: its id, and the errors it declares, to spread into a Function's errors. */
+export interface DefinedQuery<Id extends string = string, Input = unknown, Output = unknown, E extends Errors = Errors> {
+    readonly id: Id;
+    readonly errors: E;
+    /** A defined Mutation, `kind: 'mutation'`, writes: no read takes one. */
+    readonly kind?: never;
+    readonly '~input'?: Input;
+    readonly '~output'?: Output;
+}
+/**
+ * A Query whose single read is a page: the call sets its size and continues it. A `DefinedQuery`
+ * with its row type, not an interface of its own: a Domain's exported declaration names only
+ * `DefinedQuery`.
+ */
+export type PageQuery<Id extends string = string, Input = unknown, Output = unknown, E extends Errors = Errors, Row = unknown> = DefinedQuery<Id, Input, Output, E> & {
+    readonly '~page'?: Row;
+};
+/** The input a Query is called with; a Query with no input is called with `undefined`. */
+export type InputOf<R> = R extends DefinedQuery<string, infer I, unknown, Errors> ? I : never;
+/** The output a Query answers. */
+export type OutputOf<R> = R extends DefinedQuery<string, unknown, infer O, Errors> ? O : never;
+type Output<S, Results, I, O, E extends Errors> = (results: Results, input: I, context: OutputContext<S, E>) => O;
+/**
+ * Whether a type is portable JSON as far as its type can tell: a function, or an object that
+ * carries one (a Promise, a Date, a Map, a class with methods), is not. A value typed `unknown`
+ * may be JSON, so it passes, as does anything past eight levels.
+ */
+type Portable<T, Depth extends readonly unknown[] = []> = unknown extends T ? true : Depth['length'] extends 8 ? true : T extends string | number | boolean | null | undefined ? true : T extends bigint | symbol | ((...args: never) => unknown) ? false : T extends readonly (infer Item)[] ? Portable<Item, [...Depth, unknown]> : {
+    [K in keyof T]-?: Portable<T[K], [...Depth, unknown]>;
+}[keyof T] extends true ? true : false;
+/** `output` returns portable JSON, checked by type (spec § API reference: Queries). */
+type PortableOutput<O> = [Portable<O>] extends [true] ? unknown : '✗ output returns portable JSON: no function, Promise, Date, Map or other object with methods';
+/** What `steps(…)` returns: the merged results of its steps, for `output`. */
+export interface Stepped<out R> {
+    readonly '~stepped': R;
+}
+/** The results of what `build` returns: a read's, a page's, a record of facets', or the steps'. */
+export type BuiltResults<B> = B extends Stepped<infer R> ? R : Results<B>;
+/**
+ * `build`'s third parameter: reads that wait for others. The first step is a record of facets;
+ * each next one a function of the merged results of the steps before it, returning a record of
+ * facets none of them read. Two to eight steps, one overload per count, so a call's error is its
+ * own count's.
+ */
+export interface Steps {
+    <B1 extends Facets, B2 extends Later<Results<B1>>>(first: B1, second: (earlier: Results<B1>) => B2): Stepped<Merged<B1, B2>>;
+    <B1 extends Facets, B2 extends Later<Results<B1>>, B3 extends Later<Merged<B1, B2>>>(first: B1, second: (earlier: Results<B1>) => B2, third: (earlier: Merged<B1, B2>) => B3): Stepped<Merged<B1, B2, B3>>;
+    <B1 extends Facets, B2 extends Later<Results<B1>>, B3 extends Later<Merged<B1, B2>>, B4 extends Later<Merged<B1, B2, B3>>>(first: B1, second: (earlier: Results<B1>) => B2, third: (earlier: Merged<B1, B2>) => B3, fourth: (earlier: Merged<B1, B2, B3>) => B4): Stepped<Merged<B1, B2, B3, B4>>;
+    <B1 extends Facets, B2 extends Later<Results<B1>>, B3 extends Later<Merged<B1, B2>>, B4 extends Later<Merged<B1, B2, B3>>, B5 extends Later<Merged<B1, B2, B3, B4>>>(first: B1, second: (earlier: Results<B1>) => B2, third: (earlier: Merged<B1, B2>) => B3, fourth: (earlier: Merged<B1, B2, B3>) => B4, fifth: (earlier: Merged<B1, B2, B3, B4>) => B5): Stepped<Merged<B1, B2, B3, B4, B5>>;
+    <B1 extends Facets, B2 extends Later<Results<B1>>, B3 extends Later<Merged<B1, B2>>, B4 extends Later<Merged<B1, B2, B3>>, B5 extends Later<Merged<B1, B2, B3, B4>>, B6 extends Later<Merged<B1, B2, B3, B4, B5>>>(first: B1, second: (earlier: Results<B1>) => B2, third: (earlier: Merged<B1, B2>) => B3, fourth: (earlier: Merged<B1, B2, B3>) => B4, fifth: (earlier: Merged<B1, B2, B3, B4>) => B5, sixth: (earlier: Merged<B1, B2, B3, B4, B5>) => B6): Stepped<Merged<B1, B2, B3, B4, B5, B6>>;
+    <B1 extends Facets, B2 extends Later<Results<B1>>, B3 extends Later<Merged<B1, B2>>, B4 extends Later<Merged<B1, B2, B3>>, B5 extends Later<Merged<B1, B2, B3, B4>>, B6 extends Later<Merged<B1, B2, B3, B4, B5>>, B7 extends Later<Merged<B1, B2, B3, B4, B5, B6>>>(first: B1, second: (earlier: Results<B1>) => B2, third: (earlier: Merged<B1, B2>) => B3, fourth: (earlier: Merged<B1, B2, B3>) => B4, fifth: (earlier: Merged<B1, B2, B3, B4>) => B5, sixth: (earlier: Merged<B1, B2, B3, B4, B5>) => B6, seventh: (earlier: Merged<B1, B2, B3, B4, B5, B6>) => B7): Stepped<Merged<B1, B2, B3, B4, B5, B6, B7>>;
+    <B1 extends Facets, B2 extends Later<Results<B1>>, B3 extends Later<Merged<B1, B2>>, B4 extends Later<Merged<B1, B2, B3>>, B5 extends Later<Merged<B1, B2, B3, B4>>, B6 extends Later<Merged<B1, B2, B3, B4, B5>>, B7 extends Later<Merged<B1, B2, B3, B4, B5, B6>>, B8 extends Later<Merged<B1, B2, B3, B4, B5, B6, B7>>>(first: B1, second: (earlier: Results<B1>) => B2, third: (earlier: Merged<B1, B2>) => B3, fourth: (earlier: Merged<B1, B2, B3>) => B4, fifth: (earlier: Merged<B1, B2, B3, B4>) => B5, sixth: (earlier: Merged<B1, B2, B3, B4, B5>) => B6, seventh: (earlier: Merged<B1, B2, B3, B4, B5, B6>) => B7, eighth: (earlier: Merged<B1, B2, B3, B4, B5, B6, B7>) => B8): Stepped<Merged<B1, B2, B3, B4, B5, B6, B7, B8>>;
+}
+/** `defineQuery<Schema>()`'s v7 form: a string id first. */
+export interface DefinedQueryFactory<S> {
+    /**
+     * `build` returns one read, a record of facets, `steps(…)`, or a page as its single read, whose
+     * `output` keeps the page shape (the cursor stays the Kernel's). Its type is spelled out, not
+     * `PageQuery`: a Domain's exported declarations then name only `DefinedQuery`.
+     */
+    <const Id extends string, I, B extends Built | PageRead<unknown> | Stepped<unknown>, O = BuiltResults<B>, E extends Errors = {}>(id: Id, spec: {
+        readonly build: (input: I, d: Handles<S>, steps: Steps) => B;
+        readonly output?: Output<S, BuiltResults<B>, I, O & PageShape<B>, E> & PortableOutput<O>;
+        readonly errors?: E;
+    }): B extends PageRead<infer T> ? DefinedQuery<Id, I, O, E> & {
+        readonly '~page'?: T;
+    } : DefinedQuery<Id, I, O, E>;
+}
+export {};

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

@@ -1,12 +1,12 @@
 import type { Domain, schema } from '../../platform/schema/index.js';
 import type { QueryDefinition } from './query.js';
-/** The private projection of one recipe from its exact loaded Domain. */
+/** The private projection of one Query definition from its exact loaded Domain. */
 export type QueryProjector = (domain: Domain) => Readonly<Record<string, unknown>>;
 export type ResolvedDomainOf<Schema extends schema.DomainSchema> = Extract<schema.DomainOf<Schema>, Domain>;
-/** One inert recipe of `kind`; its projector is retained privately. */
-export declare function recipe(kind: QueryDefinition['kind'], project: QueryProjector): QueryDefinition;
-/** The projector a recipe was registered with, if it was. */
+/** One inert Query definition of `kind`; its projector is retained privately. */
+export declare function inertQuery(kind: QueryDefinition['kind'], project: QueryProjector): QueryDefinition;
+/** The projector a Query definition was registered with, if it was. */
 export declare function projectorOf(definition: object): QueryProjector | undefined;
-/** The fields every authored recipe shares: `id`, its operation, `prepare`, `project`, `reject`. */
+/** The fields every authored Query definition shares: `id`, its operation, `prepare`, `project`, `reject`. */
 export declare function definitionBase(definition: Readonly<Record<string, unknown>>, operation: 'build' | 'compose'): void;
 export declare function isPromiseLike(input: unknown): input is PromiseLike<unknown>;

package/dist/application/query/definition.js

@@ -1,17 +1,17 @@
 const projectors = new WeakMap();
-/** One inert recipe of `kind`; its projector is retained privately. */
-export function recipe(kind, project) {
+/** One inert Query definition of `kind`; its projector is retained privately. */
+export function inertQuery(kind, project) {
     if (typeof project !== 'function')
         throw new TypeError('Query projection must be a function.');
     const definition = Object.freeze({ kind });
     projectors.set(definition, project);
     return definition;
 }
-/** The projector a recipe was registered with, if it was. */
+/** The projector a Query definition was registered with, if it was. */
 export function projectorOf(definition) {
     return projectors.get(definition);
 }
-/** The fields every authored recipe shares: `id`, its operation, `prepare`, `project`, `reject`. */
+/** The fields every authored Query definition shares: `id`, its operation, `prepare`, `project`, `reject`. */
 export function definitionBase(definition, operation) {
     if (definition === null || typeof definition !== 'object' || Array.isArray(definition))
         invalid();

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

@@ -1,12 +1,14 @@
 /**
- * The bounds a recipe keeps before anything is sent (S11, spec § Recipes: the contract): its
+ * The bounds a Query keeps before anything is sent (S11, spec § Queries: the contract): its
  * reads, its rows, each verb's bound, and the values of a property's `in`.
  */
 import type { ReadPlan } from '../handles/plan.js';
-import type { AnyQuery } from '../language/query.js';
-/** Each read of each stage, and each element of an `items.map`. */
+import type { QueryDocument } from '../language/query.js';
+/** Each read of each step, and each element of an `items.map`. */
 export declare const MAXIMUM_READS = 32;
-/** Across a recipe's nested lists. */
+/** Steps of one Query: `steps(first, (earlier) => next, …)` takes two to this many. */
+export declare const MAXIMUM_STEPS = 8;
+/** Across a Query's nested lists. */
 export declare const MAXIMUM_ROWS = 100000;
 /** A verb's bound: its list, plus one for `all` and `first(n, { more })`, fits a Kernel page. */
 export declare const MAXIMUM_BOUND = 83332;
@@ -17,4 +19,4 @@ export declare function pastPage(plan: ReadPlan): boolean;
 /** The rows a read may answer, counted as the product of its verbs' bounds. */
 export declare function rowsOf(plan: ReadPlan): number;
 /** The first property `in` past its values, as a pointer into the document. */
-export declare function wideIn(document: AnyQuery): string | undefined;
+export declare function wideIn(document: QueryDocument): string | undefined;

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

@@ -1,6 +1,8 @@
-/** Each read of each stage, and each element of an `items.map`. */
+/** Each read of each step, and each element of an `items.map`. */
 export const MAXIMUM_READS = 32;
-/** Across a recipe's nested lists. */
+/** Steps of one Query: `steps(first, (earlier) => next, …)` takes two to this many. */
+export const MAXIMUM_STEPS = 8;
+/** Across a Query's nested lists. */
 export const MAXIMUM_ROWS = 100_000;
 /** A verb's bound: its list, plus one for `all` and `first(n, { more })`, fits a Kernel page. */
 export const MAXIMUM_BOUND = 83_332;

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

@@ -0,0 +1,20 @@
+import type { QueryPageRequest, QueryResponse } from '@astrale-os/kernel-client/graph';
+import type { QueryAST, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
+import type { QueryDocument } from '../language/query.js';
+/** What a Query v7 read is sent with: the cursor of the page it continues. */
+export interface QueryRequestOptions {
+    readonly paging?: {
+        readonly after: string;
+    };
+}
+/**
+ * The client a Query reads through, as a Kernel Client session serves it: a v7 document per
+ * request, or a V6 Query's AST page by page.
+ */
+export interface QueryClient {
+    query<Query extends QueryDocument>(query: Query, options: QueryRequestOptions): Promise<unknown>;
+    /** A V6 Query's read. It stays the last overload, which `Parameters` and `ReturnType` read. */
+    query<Ast extends QueryAST>(ast: Ast, options: {
+        readonly page: QueryPageRequest;
+    }): Promise<QueryResponse<QueryResultFor<Ast>>>;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -12,8 +12,8 @@ export interface DeclaredClass {
  */
 export declare class UndeclaredCrossing extends TypeError {
     #private;
-    constructor(recipe: string, message: string);
-    get recipe(): string;
+    constructor(query: string, message: string);
+    get query(): string;
 }
 /** The S12 check of one Domain: its dependencies, and the operations it declares on their Classes. */
 export declare class Crossings {
@@ -21,5 +21,5 @@ export declare class Crossings {
     readonly model: Model;
     constructor(model: Model, domain: Domain, declared: readonly DeclaredClass[]);
     /** Throw when a relation of the read crosses a foreign Class its Domain does not declare. */
-    check(recipe: string, plan: ReadPlan): void;
+    check(query: string, plan: ReadPlan): void;
 }

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

@@ -1,33 +1,40 @@
 /**
- * The Classes a recipe's relations cross, checked against what its Domain declares (S12, spec §
- * Details settled: "When S12 runs"). A relation that crosses a Class of a dependency needs `read`
- * and `traverse` on it in the Domain's requirements, or the read is a programming error, raised at
- * lowering before anything is sent, never answered as empty. It reads the document as written,
- * so an empty list the input gives refuses what any other list does. A requirement on a parent
- * covers its children, and an abstract Class with concrete children, each covered, is covered:
- * the check refuses only what no declaration serves.
+ * The Classes a Query's relations cross, checked against what its Domain declares (S12, spec §
+ * Details settled: "When S12 runs"). A relation that crosses a Class of a dependency other than the
+ * Kernel needs `read` and `traverse` on it in the Domain's requirements, or the read is a
+ * programming error, raised at lowering before anything is sent, never answered as empty. It reads
+ * the document as written, so an empty list the input gives refuses what any other list does. A
+ * requirement on a parent covers its children, and an abstract Class with concrete children, each
+ * covered, is covered: the check refuses only what no declaration serves.
  */
 import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
 /** What a relation needs on each foreign Class it crosses. */
 const NEEDED = ['read', 'traverse'];
+/**
+ * The Kernel's origin. Its Classes need nothing, even when the Domain declares it a dependency, but
+ * the dependency Classes under an abstract one (`Identity`, `Node`) each do.
+ */
+const KERNEL = 'kernel.astrale.ai';
+/** The Kernel's abstract Edge Class. Every Edge Class is under it, though none names it a parent. */
+const EDGE = `${KERNEL}:class.Edge`;
 /**
  * The S12 refusal: a `TypeError`, the same for every input and every attempt, so a durable Step
  * fails at once on it.
  */
 export class UndeclaredCrossing extends TypeError {
-    #recipe;
-    constructor(recipe, message) {
+    #query;
+    constructor(query, message) {
         super(message);
-        this.#recipe = recipe;
+        this.#query = query;
     }
-    get recipe() {
-        return this.#recipe;
+    get query() {
+        return this.#query;
     }
 }
 /** The S12 check of one Domain: its dependencies, and the operations it declares on their Classes. */
 export class Crossings {
     model;
-    /** Each direct dependency's origin, by the alias the Domain gives it. */
+    /** Each direct dependency's origin but the Kernel's, by the alias the Domain gives it. */
     #dependencies = new Map();
     /** The operations declared on each Class, by key. */
     #declared = new Map();
@@ -36,7 +43,8 @@ export class Crossings {
     constructor(model, domain, declared) {
         this.model = model;
         for (const [alias, dependency] of Object.entries(domain.dependencies))
-            this.#dependencies.set(dependency.origin, alias);
+            if (dependency.origin !== KERNEL)
+                this.#dependencies.set(dependency.origin, alias);
         for (const requirement of declared) {
             const key = Key.of(requirement.class);
             const operations = this.#declared.get(key) ?? new Set();
@@ -48,52 +56,52 @@ export class Crossings {
             .filter((c) => !c.abstract);
     }
     /** Throw when a relation of the read crosses a foreign Class its Domain does not declare. */
-    check(recipe, plan) {
+    check(query, plan) {
         const document = (plan.written ?? plan.document);
         const root = (document?.list ?? document?.exists ?? document?.count);
         if (root === undefined)
             return;
         const branches = plan.root?.kind === 'nodes' ? plan.root.branches : undefined;
-        this.#where(recipe, root.where, undefined);
-        this.#branches(recipe, root.with, branches, undefined);
+        this.#where(query, root.where, undefined);
+        this.#branches(query, root.with, branches, undefined);
     }
-    #branches(recipe, value, plans, parent) {
+    #branches(query, value, plans, parent) {
         for (const branch of (value ?? [])) {
             const plan = plans?.find((p) => p.name === branch.name);
             const name = plan?.key ?? branch.name;
             const relation = parent === undefined ? name : `${parent}.${name}`;
-            this.#traversal(recipe, branch, `its relation ${relation}`);
-            this.#branches(recipe, branch.with, plan?.branches, relation);
+            this.#traversal(query, branch, `its relation ${relation}`);
+            this.#branches(query, branch.with, plan?.branches, relation);
         }
     }
     /** The traversals a condition holds, at any depth. */
-    #where(recipe, value, at) {
+    #where(query, value, at) {
         const where = value;
         switch (where?.op) {
             case 'and':
             case 'or':
                 for (const operand of where.operands)
-                    this.#where(recipe, operand, at);
+                    this.#where(query, operand, at);
                 return;
             case 'not':
             case 'source':
             case 'target':
-                return this.#where(recipe, where.operand, at);
+                return this.#where(query, where.operand, at);
             case 'exists':
-                return this.#traversal(recipe, where, at === undefined ? 'a condition' : `${at}'s condition`);
+                return this.#traversal(query, where, at === undefined ? 'a condition' : `${at}'s condition`);
         }
     }
     /** The Edge Classes of `via`, the Node Classes they reach, then the traversal's own conditions. */
-    #traversal(recipe, traversal, label) {
+    #traversal(query, traversal, label) {
         const via = traversal.via;
         const direction = traversal.direction;
         const edges = via.flatMap((key) => this.#known(key));
         const relation = `${label} (via ${via.join(', ')}, ${direction})`;
         const reached = this.#narrowed(this.model.reached(edges, direction), traversal.node);
         for (const c of [...edges, ...reached])
-            this.#require(recipe, relation, c);
-        this.#where(recipe, traversal.edge, label);
-        this.#where(recipe, traversal.node, label);
+            this.#require(query, relation, c);
+        this.#where(query, traversal.edge, label);
+        this.#where(query, traversal.node, label);
     }
     /**
      * The reached Classes the node condition keeps. An `is` or `isExactly` conjunct, or an `or` of
@@ -114,27 +122,42 @@ export class Crossings {
         }
         return [...new Set(classes)];
     }
-    #require(recipe, relation, c) {
+    #require(query, relation, c) {
+        if (c.ref.origin === KERNEL) {
+            if (c.abstract)
+                for (const child of this.#under(c))
+                    this.#require(query, relation, child);
+            return;
+        }
         const alias = this.#dependencies.get(c.ref.origin);
         if (alias === undefined)
             return;
         const missing = this.#missing(c);
         if (missing.length === 0 || (c.abstract && this.#covered(c)))
             return;
-        throw new UndeclaredCrossing(recipe, `Recipe ${recipe}: ${relation} crosses ${c.key}, a Class of the dependency ${alias}, on ` +
+        throw new UndeclaredCrossing(query, `Query ${query}: ${relation} crosses ${c.key}, a Class of the dependency ${alias}, on ` +
             `which the Domain declares no ${missing.join(' or ')}. Its requirements need ` +
             `{ class: ${c.key}, operations: ['read', 'traverse'] } in classes.`);
     }
     /** What a Class lacks of `read` and `traverse`, declared on it or on a parent. */
     #missing(c) {
-        const declared = new Set([...this.model.satisfies(c)].flatMap((key) => [...(this.#declared.get(key) ?? [])]));
+        const declared = new Set([...this.#satisfies(c)].flatMap((key) => [...(this.#declared.get(key) ?? [])]));
         return NEEDED.filter((operation) => !declared.has(operation));
     }
     /** An abstract Class has concrete Classes under it, and the Domain may cross each. */
     #covered(c) {
-        const children = this.#concrete.filter((k) => this.model.satisfies(k).has(c.key));
+        const children = this.#under(c);
         return children.length > 0 && children.every((k) => this.#served(k));
     }
+    /** The concrete Classes under a Class, of the Domain and its dependencies. */
+    #under(c) {
+        return this.#concrete.filter((k) => this.#satisfies(k).has(c.key));
+    }
+    /** The keys a Class satisfies, the Kernel's `Edge` included for an Edge Class. */
+    #satisfies(c) {
+        const keys = this.model.satisfies(c);
+        return c.kind === 'edge' ? new Set([...keys, EDGE]) : keys;
+    }
     /** Whether a relation may cross a Class: the Domain's own, or a dependency's it declares. */
     #served(c) {
         return !this.#dependencies.has(c.ref.origin) || this.#missing(c).length === 0;