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

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

@@ -1,6 +1,6 @@
 /**
- * The one error a recipe's reads raise (spec § Errors): a code, the recipe's id and the details
- * of that code. A recipe's own business refusals are its declared errors, raised by `output`.
+ * The one error a Query's reads raise (spec § Errors): a code, the Query's id and the details
+ * of that code. A Query's own business refusals are its declared errors, raised by `output`.
  */
 import type { NodeId } from '../../../platform/graph/node/index.js';
 import type { EdgeKey } from '../handles/rows.js';
@@ -25,7 +25,7 @@ export interface QueryErrorDetails {
         readonly parent?: NodeId;
         readonly found: 0 | 2;
     };
-    /** Past a verb's `max`, the recipe's 100,000 rows or its 32 reads. */
+    /** Past a verb's `max`, the Query's 100,000 rows or its 32 reads. */
     TOO_MANY: {
         readonly limit: 'max' | 'rows' | 'reads';
         readonly bound: number;
@@ -35,7 +35,7 @@ export interface QueryErrorDetails {
         readonly kernelCode: string;
         readonly retryable: boolean;
     };
-    /** The Kernel refused the query the recipe built, before reading anything. */
+    /** The Kernel refused the document the Query built, before reading anything. */
     INPUT_INVALID: {
         readonly kernelCode?: string;
         readonly phase?: string;
@@ -54,13 +54,13 @@ export interface QueryErrorDetails {
 export type QueryErrorCode = keyof QueryErrorDetails;
 export declare class QueryError<C extends QueryErrorCode = QueryErrorCode> extends Error {
     readonly code: C;
-    /** The recipe's id. */
-    readonly recipe: string;
+    /** The Query's id. */
+    readonly query: string;
     readonly details: QueryErrorDetails[C];
     readonly name = "QueryError";
     constructor(code: C, 
-    /** The recipe's id. */
-    recipe: string, details: QueryErrorDetails[C], options?: ErrorOptions & {
+    /** The Query's id. */
+    query: string, details: QueryErrorDetails[C], options?: ErrorOptions & {
         readonly reason?: string;
     });
 }

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

@@ -30,16 +30,16 @@ function sentence(code, details) {
 }
 export class QueryError extends Error {
     code;
-    recipe;
+    query;
     details;
     name = 'QueryError';
     constructor(code, 
-    /** The recipe's id. */
-    recipe, details, options) {
+    /** The Query's id. */
+    query, details, options) {
         const reason = options?.reason === undefined ? '' : `: ${options.reason}`;
-        super(`${recipe}: ${sentence(code, details)}${reason}`, options);
+        super(`${query}: ${sentence(code, details)}${reason}`, options);
         this.code = code;
-        this.recipe = recipe;
+        this.query = query;
         this.details = details;
         Object.freeze(this.details);
     }

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

@@ -1,8 +1,8 @@
 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 { QueryV6Client } from '../legacy/v6/execution/execute.js';
 import type { QueryDefinition } from '../query.js';
-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 { QueryClient } from './client.js';
+export declare function executeQuery<DomainValue extends Domain, Output>(client: QueryV6Client, domain: DomainValue, query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
+export declare function executeQuery<DomainValue extends Domain, Input, Output>(client: QueryV6Client, domain: DomainValue, query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
 export type ExecutableCompositeQuery = CompositeQuery<unknown, unknown, unknown>;

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

@@ -1,6 +1,6 @@
 import type { Domain, schema } from '../../../platform/schema/index.js';
+import type { QueryV6Client } from '../legacy/v6/execution/execute.js';
 import type { QueryDefinition } from '../query.js';
-import type { QueryClient } from './execute.js';
 /** Invocation-bound executor for authored Query definitions. */
 export interface QueryExecutor<DomainValue extends Domain = Domain> {
     <Output>(query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
@@ -10,5 +10,5 @@ type ExecutableDomain<DomainValue extends Domain> = DomainValue extends {
     readonly source: infer Source extends schema.DomainSchema;
 } ? Extract<schema.DomainOf<Source>, Domain> : DomainValue;
 /** Private Runtime binding to one Client and the exact loaded root Domain. */
-export declare function bindQuery<DomainValue extends Domain>(client: QueryClient, domain: DomainValue): QueryExecutor<ExecutableDomain<DomainValue>>;
+export declare function bindQuery<DomainValue extends Domain>(client: QueryV6Client, domain: DomainValue): QueryExecutor<ExecutableDomain<DomainValue>>;
 export {};

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

@@ -20,12 +20,12 @@ interface 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. */
+/** What renders one answer: the Query it errs for, the Domain's Classes, the answer's facts. */
 export declare class Renderer {
     #private;
-    readonly recipe: string;
+    readonly query: string;
     readonly model: Model;
-    constructor(recipe: string, model: Model, answer: QueryListAnswer<unknown, unknown>);
+    constructor(query: 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. */
@@ -36,7 +36,7 @@ export declare class Renderer {
     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;
+export declare function emptyResult(query: 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 declare function rootResult(query: string, model: Model, plan: ReadPlan, answer: unknown): unknown;
 export {};

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

@@ -1,15 +1,16 @@
 import { factKey, factsOf } from '../answer/facts.js';
+import { QueryValueMismatchError } from '../failure.js';
 import { ROW_KEYS } from '../handles/model.js';
 import { QueryError } from './error.js';
 const NO_TAKEN = new Set();
 const freeze = (value) => Object.freeze(value);
-/** What renders one answer: the recipe it errs for, the Domain's Classes, the answer's facts. */
+/** What renders one answer: the Query it errs for, the Domain's Classes, the answer's facts. */
 export class Renderer {
-    recipe;
+    query;
     model;
     #facts;
-    constructor(recipe, model, answer) {
-        this.recipe = recipe;
+    constructor(query, model, answer) {
+        this.query = query;
         this.model = model;
         this.#facts = factsOf(answer);
     }
@@ -22,7 +23,7 @@ export class Renderer {
     }
     #class(item) {
         if (item.class === undefined)
-            throw new QueryError('UNSUPPORTED', this.recipe, { feature: 'classes' });
+            throw new QueryError('UNSUPPORTED', this.query, { feature: 'classes' });
         return item.class;
     }
     /**
@@ -46,11 +47,19 @@ export class Renderer {
         return (candidates.find((c) => candidates.every((o) => this.model.satisfies(c).has(o.key))) ??
             candidates[0]);
     }
-    /** The values of a fact by the layout of a Class: flat names, then groups (F6). */
+    /**
+     * The values of a fact by the layout of a Class: flat names, then groups (F6). The row types a
+     * required value as present, so a fact without one breaks the Domain as a value that does not
+     * match its Property does.
+     */
     #values(fact, c, taken) {
         if (c === undefined)
             return {};
         const values = (this.#fact(fact)?.values ?? {});
+        for (const property of c.properties) {
+            if (property.definition.required && values[property.key] === undefined)
+                throw new QueryValueMismatchError(`${factKey(fact)} has no value for ${property.key}, which its Property requires in this Domain`);
+        }
         const { flat, groups } = this.model.layout(c, taken);
         const row = {};
         for (const [name, key] of flat)
@@ -83,12 +92,15 @@ export class Renderer {
             Object.assign(row, this.#values(id, layout, ROW_KEYS));
         for (const branch of pattern.branches)
             row[branch.key] = this.#relation(item, branch);
-        if ('edge' in pattern && pattern.edge && item.edge !== undefined)
-            row.$edge = this.#edgeValues(item.edge);
+        const edge = pattern.edge;
+        if (edge !== undefined && item.edge !== undefined)
+            row.$edge = this.#edgeValues(item.edge, edge);
         return freeze(row);
     }
-    /** What `.withEdge()` adds: the Edge's Class and values, or the names it withholds. */
-    #edgeValues(edge) {
+    /** What `.withEdge()` adds: the Edge's Class, and its values or the names it withholds. */
+    #edgeValues(edge, select) {
+        if (select === 'reference')
+            return freeze({ $class: edge.class });
         const c = this.#known(edge.class);
         if (this.#withheld(edge))
             return freeze({ $class: edge.class, $withheld: this.#names(c) });
@@ -116,14 +128,13 @@ export class Renderer {
         const row = { ...identity };
         if (plan.select === 'value')
             Object.assign(row, this.#values(key, c, roles));
-        const end = (rendered, classes) => {
+        const end = (rendered, { classes, select }) => {
             if (rendered === undefined)
                 return undefined;
-            const pattern = { classes, select: plan.select, withheld: true, branches: [] };
-            return this.node(rendered, pattern);
+            return this.node(rendered, { classes, select, withheld: true, branches: [] });
         };
-        row[plan.source.role] = end(item.source, plan.source.classes);
-        row[plan.target.role] = end(item.target, plan.target.classes);
+        row[plan.source.role] = end(item.source, plan.source);
+        row[plan.target.role] = end(item.target, plan.target);
         return freeze(row);
     }
     /** A relation's answer for one parent, by its verb. */
@@ -154,7 +165,7 @@ export class Renderer {
                 return items[0] === undefined ? undefined : this.node(items[0], plan);
             case 'all':
                 if (items.length > plan.bound)
-                    throw new QueryError('TOO_MANY', this.recipe, { limit: 'max', bound: plan.bound });
+                    throw new QueryError('TOO_MANY', this.query, { limit: 'max', bound: plan.bound });
                 return this.#rows(items, plan);
             default:
                 return this.#rows(items, plan);
@@ -176,12 +187,12 @@ export class Renderer {
         }
     }
     #integrity(at, found) {
-        return new QueryError('INTEGRITY', this.recipe, { ...at, found });
+        return new QueryError('INTEGRITY', this.query, { ...at, found });
     }
     /** The one row `get` or `find` gives: one the reader may not read is an error, since it exists. */
     #one(item, pattern) {
         if (this.#withheld(item.fact))
-            throw new QueryError('NOT_READABLE', this.recipe, { class: this.#class(item), id: item.fact });
+            throw new QueryError('NOT_READABLE', this.query, { class: this.#class(item), id: item.fact });
         return this.node(item, pattern);
     }
     #rows(items, pattern) {
@@ -195,7 +206,7 @@ export class Renderer {
     rootOne(item, root) {
         if (this.#withheld(item.fact)) {
             const fact = item.fact;
-            throw new QueryError('NOT_READABLE', this.recipe, {
+            throw new QueryError('NOT_READABLE', this.query, {
                 class: typeof fact === 'string' ? this.#class(item) : fact.class,
                 id: fact,
             });
@@ -208,10 +219,10 @@ function classLabel(plan) {
     return plan.root?.classes.join(' | ') ?? '';
 }
 /** The answer of a root read with nothing to read: its verb's empty answer. */
-export function emptyResult(recipe, plan) {
+export function emptyResult(query, plan) {
     switch (plan.verb) {
         case 'get':
-            throw new QueryError('NOT_FOUND', recipe, {
+            throw new QueryError('NOT_FOUND', query, {
                 class: classLabel(plan),
                 ...(plan.target === undefined ? {} : { target: plan.target }),
             });
@@ -231,24 +242,24 @@ export function emptyResult(recipe, plan) {
     }
 }
 /** A root read's result from its answer, by its verb. */
-export function rootResult(recipe, model, plan, answer) {
+export function rootResult(query, model, plan, answer) {
     const json = answer;
     if ('exists' in json)
         return json.exists === true;
     if ('count' in json)
         return freeze({ count: json.count, more: json.more === true });
     const listAnswer = answer;
-    const renderer = new Renderer(recipe, model, listAnswer);
+    const renderer = new Renderer(query, model, listAnswer);
     const { items, complete, cursor } = listAnswer.list;
     const root = plan.root ?? documentRoot(plan);
     switch (plan.verb) {
         case 'get':
         case 'find': {
             if (items.length > 1)
-                throw new QueryError('INTEGRITY', recipe, { relation: classLabel(plan), found: 2 });
+                throw new QueryError('INTEGRITY', query, { relation: classLabel(plan), found: 2 });
             const [item] = items;
             if (item === undefined)
-                return emptyResult(recipe, plan);
+                return emptyResult(query, plan);
             return renderer.rootOne(item, root);
         }
         case 'first':
@@ -264,7 +275,7 @@ export function rootResult(recipe, model, plan, answer) {
             });
         case 'all':
             if (items.length > plan.bound)
-                throw new QueryError('TOO_MANY', recipe, { limit: 'max', bound: plan.bound });
+                throw new QueryError('TOO_MANY', query, { limit: 'max', bound: plan.bound });
             return renderer.rootRows(items, root);
         default:
             return renderer.rootRows(items, root);
@@ -282,7 +293,7 @@ function documentRoot(plan) {
         relation: b.name,
         verb: b.mode === 'count' ? 'count' : 'firstN',
         empty: false,
-        edge: b.selectEdge !== undefined,
+        edge: b.selectEdge,
         classes: [],
         select: b.select === 'value' ? 'value' : 'reference',
         withheld: false,
@@ -297,12 +308,13 @@ function documentRoot(plan) {
             branches: branches(list),
         };
     const select = (list.select ?? {});
+    const rendering = (side) => (select[side] === 'value' ? 'value' : 'reference');
     return {
         kind: 'edges',
         classes: [],
-        select: select.edge === 'value' ? 'value' : 'reference',
+        select: rendering('edge'),
         withheld: false,
-        source: { role: 'source', classes: [] },
-        target: { role: 'target', classes: [] },
+        source: { role: 'source', classes: [], select: rendering('source') },
+        target: { role: 'target', classes: [], select: rendering('target') },
     };
 }

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

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