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

package/dist/application/mutation/authoring/guard.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Mutation v4 guards (S7): a condition the Kernel decides with the Mutation, on the roots of a
+ * range. Each verb takes a range built from the handles, or a canonical v7 Query, and writes the
+ * document of the guard's own family: the range (`nodes` or `edges`, `as`, `where`) for `none`,
+ * `exists` and `count`, its ordered root list for `unchanged`. A range is never rendered, sized
+ * or read with a verb, so nothing written on it is left out of the guard.
+ */
+import type { MutationGuardInput } from '@astrale-os/kernel-core/graph/mutate';
+import type { NodeId } from '../../../platform/graph/node/index.js';
+import type { EdgeSet, NodeSet } from '../../query/handles/handles.js';
+import type { EdgeKey } from '../../query/handles/rows.js';
+import type { AnyQuery } from '../../query/language/query.js';
+/**
+ * What a guard reads: a range, the Nodes or Edges of a Class handle `build` receives after
+ * `where`, `union` and `orderBy`, or a canonical v7 Query.
+ */
+export type GuardRange<S, K extends string> = NodeSet<S, K, {}, 'value', false> | EdgeSet<S, K, 'value', false> | AnyQuery;
+/** How many roots a `count` guard admits: exactly `n`, or within bounds, bounded at least once. */
+export type CountBounds = number | {
+    readonly atLeast?: number;
+    readonly atMost?: number;
+};
+/** The identity of one root of a list, as a read returns it: a Node's id, or an Edge's key. */
+export type GuardIdentity = NodeId | EdgeKey;
+/** What a precondition verb takes after its condition: the name a refusal reports it by. */
+export interface PreconditionOptions {
+    readonly name: string;
+}
+/** `none` and `exists`: whether the range has a root. */
+export declare function existsGuard(range: unknown, expected: boolean): MutationGuardInput;
+/**
+ * `count`: the number of the range's roots lies in the bounds. The document counts up to the
+ * largest bound, and at least one, so the Kernel tells every bound from the count it reads.
+ */
+export declare function countGuard(range: unknown, bounds: CountBounds): MutationGuardInput;
+/** `unchanged`: the range's root list is exactly these identities, in its order. */
+export declare function sequenceGuard(range: unknown, ids: readonly GuardIdentity[]): MutationGuardInput;

package/dist/application/mutation/authoring/guard.js

@@ -0,0 +1,150 @@
+import { RelationRead, RootRead } from '../../query/handles/plan.js';
+import { rangeRead } from '../../query/handles/reads.js';
+import { QUERY } from '../../query/language/query.js';
+/** The fields of a root its range keeps, and those its ordered list keeps, in grammar order. */
+const RANGE = ['nodes', 'edges', 'as', 'where'];
+const ORDERED = [...RANGE, 'orderBy'];
+/** The fields of a root by family: a list's, and a range's (`exists`, `count`). */
+const LIST_FIELDS = new Set([...ORDERED, 'select', 'with', 'limit']);
+const RANGE_FIELDS = new Set(RANGE);
+const FAMILIES = ['list', 'exists', 'count'];
+/** `none` and `exists`: whether the range has a root. */
+export function existsGuard(range, expected) {
+    return guard({ kind: 'exists', document: { query: QUERY, exists: root(range, RANGE) }, expected });
+}
+/**
+ * `count`: the number of the range's roots lies in the bounds. The document counts up to the
+ * largest bound, and at least one, so the Kernel tells every bound from the count it reads.
+ */
+export function countGuard(range, bounds) {
+    const { atLeast, atMost } = countBounds(bounds);
+    const upTo = Math.max(1, atLeast ?? 0, atMost ?? 0);
+    return guard({
+        kind: 'count',
+        document: { query: QUERY, count: root(range, RANGE), upTo },
+        ...(atLeast === undefined ? {} : { atLeast }),
+        ...(atMost === undefined ? {} : { atMost }),
+    });
+}
+/** `unchanged`: the range's root list is exactly these identities, in its order. */
+export function sequenceGuard(range, ids) {
+    if (!Array.isArray(ids)) {
+        throw new TypeError('An unchanged guard names the identities of the list, in its order: an array.');
+    }
+    const list = root(range, ORDERED);
+    const edges = list.edges !== undefined;
+    for (const id of ids)
+        if (edges ? !isEdgeKey(id) : typeof id !== 'string') {
+            throw new TypeError(`An unchanged guard names each root by its identity, as its read returned it: ${edges ? 'an EdgeKey ({ source, target, class }) per Edge' : 'a NodeId per Node'}, \`rows.map((row) => row.id)\`.`);
+        }
+    return guard({
+        kind: 'sequence',
+        document: { query: QUERY, list },
+        equals: Object.freeze([...ids]),
+    });
+}
+/**
+ * The fields of the range's root among `keep`, in grammar order, frozen. A field the grammar does
+ * not name is refused, never dropped: dropping a misspelled `where` would widen the guard.
+ */
+function root(range, keep) {
+    const document = documentOf(range, keep === ORDERED);
+    const families = FAMILIES.filter((family) => document[family] !== undefined);
+    if (families.length !== 1)
+        invalidRange();
+    const family = families[0];
+    const extra = Object.keys(document).find((key) => key !== 'query' && key !== family && !(family === 'count' && key === 'upTo'));
+    if (extra !== undefined)
+        unknownField(extra);
+    const read = document[family];
+    if (read === null || typeof read !== 'object' || Array.isArray(read))
+        invalidRange();
+    const fields = read;
+    const known = family === 'list' ? LIST_FIELDS : RANGE_FIELDS;
+    const unknown = Object.keys(fields).find((key) => !known.has(key));
+    if (unknown !== undefined)
+        unknownField(`${family}.${unknown}`);
+    if ((fields.nodes === undefined) === (fields.edges === undefined)) {
+        throw new TypeError("A guard's range starts from `nodes` or from `edges`, exactly one.");
+    }
+    if (fields.with !== undefined && !Array.isArray(fields.with))
+        unknownField(`${family}.with`);
+    if (Array.isArray(fields.with) && fields.with.some(isRequired)) {
+        throw new TypeError("A guard reads its range's roots without their relations, and a required one narrows the " +
+            'roots: write it as a condition, `.where((t) => t.via(edge).exists())`.');
+    }
+    const out = {};
+    for (const name of keep)
+        if (fields[name] !== undefined)
+            out[name] = fields[name];
+    return Object.freeze(out);
+}
+/** The canonical document of a range, `ordered` or not, or the canonical v7 Query itself. */
+function documentOf(range, ordered) {
+    const read = rangeRead(range, ordered);
+    if (read !== undefined) {
+        if (read.plan.empty || read.plan.document === undefined) {
+            throw new TypeError('A guard on a range whose condition matches nothing (`in([])`, `id.in([])`) has no ' +
+                'document to send: decide that guard in build, from the input.');
+        }
+        return read.plan.document;
+    }
+    if (range instanceof RelationRead) {
+        throw new TypeError("A guard reads a root, and a relation is read per parent: start the guard's range from a " +
+            'Class handle, `d.<Class>`.');
+    }
+    if (range instanceof RootRead) {
+        throw new TypeError(range.plan.verb === 'document'
+            ? `A guard takes a canonical ${QUERY} Query itself, not \`d.document\` of it.`
+            : "A guard takes a range, not a read: the Class handle after `where`, `union` and `orderBy`, `d.<Class>.where(…)`, with no verb. A verb's bound would not reach the guard.");
+    }
+    const document = range;
+    if (document === null || typeof document !== 'object' || document.query !== QUERY)
+        invalidRange();
+    return document;
+}
+function invalidRange() {
+    throw new TypeError(`A guard takes a range built from the handles, \`d.<Class>.where(…)\`, or a canonical ${QUERY} Query.`);
+}
+function unknownField(path) {
+    throw new TypeError(`A guard's Query holds ${path}, which the ${QUERY} grammar does not name there: a guard is never wider than its Query, so it is refused rather than dropped.`);
+}
+function isEdgeKey(id) {
+    const key = id;
+    return (key !== null &&
+        typeof key === 'object' &&
+        typeof key.source === 'string' &&
+        typeof key.target === 'string' &&
+        typeof key.class === 'string');
+}
+function isRequired(branch) {
+    return branch?.mode === 'required';
+}
+function countBounds(bounds) {
+    if (bounds === null || typeof bounds !== 'object') {
+        const exactly = bound(bounds, 'count');
+        return { atLeast: exactly, atMost: exactly };
+    }
+    const fields = (bounds ?? {});
+    const atLeast = fields.atLeast === undefined ? undefined : bound(fields.atLeast, 'atLeast');
+    const atMost = fields.atMost === undefined ? undefined : bound(fields.atMost, 'atMost');
+    if (atLeast === undefined && atMost === undefined) {
+        throw new TypeError('A count guard is bounded at least once: `atLeast`, `atMost` or both.');
+    }
+    if (atLeast !== undefined && atMost !== undefined && atLeast > atMost) {
+        throw new TypeError(`A count guard's atLeast (${atLeast}) exceeds its atMost (${atMost}).`);
+    }
+    return {
+        ...(atLeast === undefined ? {} : { atLeast }),
+        ...(atMost === undefined ? {} : { atMost }),
+    };
+}
+function bound(value, name) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`A count guard's ${name} is a non-negative integer.`);
+    }
+    return value;
+}
+function guard(input) {
+    return Object.freeze(input);
+}

package/dist/application/mutation/authoring/index.d.ts

@@ -1,4 +1,7 @@
-export { richMutationBuilder, type EdgeSelector, type RichMutationBuilder } from './builder.js';
+export { richMutationBuilder, type BuilderForm, type RecipeMutationBuilder, type RichMutationBuilder, } from './builder.js';
 export type { CreatedNode, ExistingEndpoint, MutationEndpoint } from './endpoint.js';
 export type { RichPropertyConditions, RichPropertyDelta, RichPropertyInput, RichPropertyName, } from './properties.js';
-export type { QueryPrecondition } from './precondition.js';
+export type { CountBounds, GuardIdentity, GuardRange, PreconditionOptions } from './guard.js';
+export { preconditionNames, type PreconditionNames } from './names.js';
+export type { ClosureMutationBuilder, EdgeSelector } from '../legacy/v6/builder.js';
+export type { QueryPrecondition } from '../legacy/v6/precondition.js';

package/dist/application/mutation/authoring/index.js

@@ -1 +1,2 @@
-export { richMutationBuilder } from './builder.js';
+export { richMutationBuilder, } from './builder.js';
+export { preconditionNames } from './names.js';

package/dist/application/mutation/authoring/names.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The names a Mutation gives its preconditions, and the name of the one a refusal points at.
+ *
+ * The Kernel points at a failed precondition by its index in the Mutation's `preconditions`, which
+ * the Mutation document orders by canonical JSON, not as written. So a name is not kept by
+ * position: each named precondition is built again on its own, with the Mutation's writes, and
+ * its entry is matched by value against the entry the refusal points at.
+ */
+import type { MutationBuilder } from '@astrale-os/kernel-core/graph/mutate';
+import { MutationAST } from '@astrale-os/kernel-core/graph/mutate';
+export interface PreconditionNames {
+    /** `core`, its every call kept so that a named precondition can be built again on its own. */
+    track(core: MutationBuilder): MutationBuilder;
+    /** Gives `name` to the one precondition `write` adds; a name is unique in its Mutation. */
+    name(name: string | undefined, write: () => void): void;
+    /** The name of the precondition at `index` of the built Mutation, when it has one. */
+    at(ast: MutationAST, index: number): string | undefined;
+}
+export declare function preconditionNames(): PreconditionNames;

package/dist/application/mutation/authoring/names.js

@@ -0,0 +1,83 @@
+import { MutationAST } from '@astrale-os/kernel-core/graph/mutate';
+import { equal } from '@astrale-os/kernel-dsl/value';
+export function preconditionNames() {
+    const steps = [];
+    const used = new Set();
+    let pending;
+    const precondition = (core, call) => {
+        const name = pending;
+        pending = undefined;
+        call(core);
+        steps.push({ call, precondition: name === undefined ? {} : { name } });
+    };
+    const write = (core, call) => {
+        const result = call(core);
+        steps.push({ call });
+        return result;
+    };
+    return Object.freeze({
+        track(core) {
+            const tracked = Object.freeze({
+                expect: Object.freeze({
+                    node: (input) => (precondition(core, (to) => to.expect.node(input)), tracked),
+                    edge: (input) => (precondition(core, (to) => to.expect.edge(input)), tracked),
+                    query: (input) => (precondition(core, (to) => to.expect.query(input)), tracked),
+                }),
+                createNode: (input) => write(core, (to) => to.createNode(input)),
+                updateNode: (input) => (write(core, (to) => to.updateNode(input)), tracked),
+                deleteNode: (input) => (write(core, (to) => to.deleteNode(input)), tracked),
+                createEdge: (input) => (write(core, (to) => to.createEdge(input)), tracked),
+                updateEdge: (input) => (write(core, (to) => to.updateEdge(input)), tracked),
+                deleteEdge: (input) => (write(core, (to) => to.deleteEdge(input)), tracked),
+            });
+            return tracked;
+        },
+        name(name, add) {
+            if (name === undefined)
+                return add();
+            if (typeof name !== 'string' || name.length === 0) {
+                throw new TypeError("A precondition's name is a non-empty string.");
+            }
+            if (used.has(name)) {
+                throw new TypeError(`Two preconditions of one Mutation are named "${name}".`);
+            }
+            used.add(name);
+            pending = name;
+            try {
+                add();
+            }
+            finally {
+                pending = undefined;
+            }
+        },
+        at(ast, index) {
+            const failed = ast.preconditions[index];
+            if (failed === undefined)
+                return undefined;
+            const writes = steps.filter((step) => step.precondition === undefined);
+            for (const step of steps) {
+                const name = step.precondition?.name;
+                if (name === undefined)
+                    continue;
+                const alone = entryAlone(step, writes);
+                if (alone !== undefined && equal(alone, failed))
+                    return name;
+            }
+            return undefined;
+        },
+    });
+}
+/** The entry `step`'s precondition has in a Mutation of the writes and it alone. */
+function entryAlone(step, writes) {
+    try {
+        const ast = MutationAST.build((core) => {
+            step.call(core);
+            for (const write of writes)
+                write.call(core);
+        });
+        return ast.preconditions[0];
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/application/mutation/authoring/transition.d.ts

@@ -12,9 +12,10 @@ export type StatePropertyTopology<Class extends ResolvedClass<'node'>, Property
 }>>;
 export type StateOfTopology<Topology extends StateTopology> = Extract<keyof Topology['transitions'], string>;
 export type EventOfTopology<Topology extends StateTopology, State extends StateOfTopology<Topology>> = State extends StateOfTopology<Topology> ? Extract<keyof Topology['transitions'][State], string> : never;
-export interface StateTransitionInput<Class extends ResolvedClass<'node'>, Property extends StatePropertyName<Class>, From extends StateOfTopology<StatePropertyTopology<Class, Property>>, Event extends EventOfTopology<StatePropertyTopology<Class, Property>, From>> {
+/** `Selected` is how the input names `Class`: the resolved Class, or its handle (`d.<Class>`). */
+export interface StateTransitionInput<Class extends ResolvedClass<'node'>, Property extends StatePropertyName<Class>, From extends StateOfTopology<StatePropertyTopology<Class, Property>>, Event extends EventOfTopology<StatePropertyTopology<Class, Property>, From>, Selected = Class> {
     readonly node: ExistingEndpoint;
-    readonly class: Class;
+    readonly class: Selected;
     readonly property: Property;
     readonly from: From;
     readonly event: Event;

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

@@ -1,12 +1,26 @@
-import type { MutationResult } from '@astrale-os/kernel-core/graph/mutate';
-import type { Domain, schema } from '../../platform/schema/index.js';
-import type { Mutation, MutationDefinition } from './mutation.js';
-type ResolvedDomainOf<Schema extends schema.DomainSchema> = Extract<schema.DomainOf<Schema>, Domain>;
-type AuthoringDomainOf<Schema extends schema.DomainSchema> = ResolvedDomainOf<Schema>;
-interface MutationProjector<Schema extends schema.DomainSchema> {
-    <Input, Output = MutationResult>(project: (domain: AuthoringDomainOf<Schema>) => MutationDefinition<Input, Output>): Mutation<ResolvedDomainOf<Schema>, Input, Output>;
+/**
+ * `defineMutation<Schema>()`: one name for both forms. A string id first defines a Mutation recipe
+ * (D31); a function first defines a Mutation of the closure form, deprecated, which stays in
+ * `legacy/v6`. A recipe is inert: its id and the errors it declares are public, and what it
+ * writes is kept for the runtime.
+ */
+import type { schema } from '../../platform/schema/index.js';
+import type { MutationProjector } from './legacy/v6/define.js';
+import type { MutationRecipeDefinitions } from './mutation.js';
+type Callback = (...parameters: never[]) => unknown;
+/** What a Mutation recipe writes and answers: its `build`, `output` and `reject`. */
+export interface MutationRecipeSpec {
+    /** Receives `(input, d, mutation)`. */
+    readonly build: Callback;
+    readonly output?: Callback;
+    readonly reject?: Callback;
 }
-/** Define one inert Mutation recipe projected from its exact loaded Domain. */
-export declare function defineMutation<Schema extends schema.DomainSchema>(): MutationProjector<Schema>;
-export declare function realizeMutation<DomainValue extends Domain, Input, Output>(mutation: Mutation<DomainValue, Input, Output>, domain: DomainValue): MutationDefinition<Input, Output>;
+/** The `build`, `output` and `reject` of a Mutation recipe; `undefined` for anything else. */
+export declare function mutationRecipeSpecOf(recipe: unknown): MutationRecipeSpec | undefined;
+/**
+ * Define a Mutation: `defineMutation<Schema>()('issues.issue.open', { build, output?, reject?,
+ * errors? })`. The closure form, `defineMutation<Schema>()((domain) => ({ id, build, project? }))`,
+ * stays, deprecated.
+ */
+export declare function defineMutation<Schema extends schema.DomainSchema>(): MutationRecipeDefinitions<Schema> & MutationProjector<Schema>;
 export {};

package/dist/application/mutation/define.js

@@ -1,56 +1,52 @@
-import { isDomain } from '@astrale-os/kernel-dsl/v1/domain';
-const projectors = new WeakMap();
-const realized = new WeakMap();
-/** Define one inert Mutation recipe projected from its exact loaded Domain. */
-export function defineMutation() {
-    return ((project) => {
-        if (typeof project !== 'function')
-            throw new TypeError('Mutation projection must be a function.');
-        const mutation = Object.freeze({ kind: 'mutation' });
-        projectors.set(mutation, project);
-        return mutation;
-    });
-}
-export function realizeMutation(mutation, domain) {
-    const project = projectors.get(mutation);
-    if (project === undefined)
-        throw new TypeError('Mutation must be produced by defineMutation.');
-    if (!isDomain(domain))
-        throw new TypeError('Mutation projection requires an admitted Domain.');
-    let byDomain = realized.get(mutation);
-    const cached = byDomain?.get(domain);
-    if (cached !== undefined)
-        return cached;
-    const authored = project(domain);
-    if (isPromiseLike(authored))
-        throw new TypeError('Mutation projection must be synchronous.');
-    const admitted = admitMutation(authored);
-    if (byDomain === undefined) {
-        byDomain = new WeakMap();
-        realized.set(mutation, byDomain);
-    }
-    byDomain.set(domain, admitted);
-    return admitted;
+import { describe } from '../query/handles/terms.js';
+import { collectRecipe, MAXIMUM_RECIPE_ID, RECIPE_ID } from '../query/recipe/define.js';
+import { defineMutation as defineClosureMutation } from './legacy/v6/define.js';
+const FIELDS = new Set(['build', 'output', 'reject', 'errors']);
+const specs = new WeakMap();
+/** The `build`, `output` and `reject` of a Mutation recipe; `undefined` for anything else. */
+export function mutationRecipeSpecOf(recipe) {
+    return typeof recipe === 'object' && recipe !== null ? specs.get(recipe) : undefined;
 }
-function admitMutation(definition) {
-    if (definition === null || typeof definition !== 'object' || Array.isArray(definition))
-        invalid();
-    if (typeof definition.id !== 'string' ||
-        definition.id.length === 0 ||
-        definition.id.trim() !== definition.id ||
-        typeof definition.build !== 'function' ||
-        (definition.project !== undefined && typeof definition.project !== 'function') ||
-        (definition.reject !== undefined && typeof definition.reject !== 'function') ||
-        Reflect.ownKeys(definition).some((key) => key !== 'id' && key !== 'build' && key !== 'project' && key !== 'reject')) {
-        invalid();
-    }
-    return Object.freeze({ ...definition });
-}
-function invalid() {
-    throw new TypeError('Mutation definition is invalid.');
+function defineMutationRecipe(id, spec) {
+    if (typeof id !== 'string' || id.length > MAXIMUM_RECIPE_ID || !RECIPE_ID.test(id))
+        throw new TypeError(`A Mutation id is lowercase segments of letters, digits and hyphens joined by dots, at most ${MAXIMUM_RECIPE_ID} characters ('issues.issue.open'); got ${describe(id)}.`);
+    if (typeof spec !== 'object' || spec === null || Array.isArray(spec))
+        throw new TypeError(`Mutation ${id} takes { build, output?, reject?, 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(`Mutation ${id} takes build, output, reject and errors only; got ${unknown.map(String).join(', ')}.`);
+    const { build, output, reject } = fields;
+    if (typeof build !== 'function')
+        throw new TypeError(`Mutation ${id}'s build is a function of (input, d, mutation); got ${describe(build)}.`);
+    if (output !== undefined && typeof output !== 'function')
+        throw new TypeError(`Mutation ${id}'s output is a function of (result, input); got ${describe(output)}.`);
+    if (reject !== undefined && typeof reject !== 'function')
+        throw new TypeError(`Mutation ${id}'s reject is a function of (failure, input, context); got ${describe(reject)}.`);
+    const errors = fields.errors ?? {};
+    if (typeof errors !== 'object' || errors === null || Array.isArray(errors))
+        throw new TypeError(`Mutation ${id}'s errors is a record of declared errors by UPPER_SNAKE code; got ${describe(errors)}.`);
+    const recipe = Object.freeze({
+        kind: 'mutation',
+        id,
+        errors: Object.freeze({ ...errors }),
+    });
+    collectRecipe(recipe);
+    specs.set(recipe, Object.freeze({
+        build: build,
+        ...(output === undefined ? {} : { output: output }),
+        ...(reject === undefined ? {} : { reject: reject }),
+    }));
+    return recipe;
 }
-function isPromiseLike(input) {
-    return (input !== null &&
-        (typeof input === 'object' || typeof input === 'function') &&
-        typeof input.then === 'function');
+/**
+ * Define a Mutation: `defineMutation<Schema>()('issues.issue.open', { build, output?, reject?,
+ * errors? })`. The closure form, `defineMutation<Schema>()((domain) => ({ id, build, project? }))`,
+ * stays, deprecated.
+ */
+export function defineMutation() {
+    const closure = defineClosureMutation();
+    return ((first, spec) => typeof first === 'string'
+        ? defineMutationRecipe(first, spec)
+        : closure(first));
 }

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

@@ -1,9 +1,9 @@
 import { type MutationAST as MutationASTValue, type MutationResult } from '@astrale-os/kernel-core/graph/mutate';
 import type { GraphMutationOptions } from '../../../platform/client/index.js';
 import type { Domain } from '../../../platform/schema/index.js';
-import type { Mutation } from '../mutation.js';
+import type { Mutation, MutationRecipe } from '../mutation.js';
 /** Exact caller-scoped canonical document capability required by Mutation execution. */
 export type MutationClient = Readonly<{
     mutate(ast: MutationASTValue, options?: GraphMutationOptions): Promise<MutationResult>;
 }>;
-export declare function executeMutation<DomainValue extends Domain, Input, Output>(client: MutationClient, domain: DomainValue, definition: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;
+export declare function executeMutation<DomainValue extends Domain, Input, Output>(client: MutationClient, domain: DomainValue, definition: Mutation<DomainValue, Input, Output> | MutationRecipe<string, Input, Output>, input: Input): Promise<Output>;

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

@@ -1,21 +1,92 @@
 import { MutationAST, } from '@astrale-os/kernel-core/graph/mutate';
-import { richMutationBuilder } from '../authoring/index.js';
-import { realizeMutation } from '../define.js';
+import { outputContext } from '../../query/execution/recipe.js';
+import { handlesOf } from '../../query/handles/build.js';
+import { modelOf } from '../../query/handles/model.js';
+import { preconditionNames, richMutationBuilder } from '../authoring/index.js';
+import { mutationRecipeSpecOf } from '../define.js';
 import { mutationFailure } from '../failure.js';
+import { realizeMutation } from '../legacy/v6/define.js';
 import { projectMutation } from './projection.js';
 export async function executeMutation(client, domain, definition, input) {
     if (client === null || typeof client !== 'object' || typeof client.mutate !== 'function') {
         throw new TypeError('Mutation execution requires a Client mutate capability.');
     }
-    const operation = realizeMutation(definition, domain);
+    const spec = mutationRecipeSpecOf(definition);
+    const operation = spec === undefined
+        ? closureOperation(definition, domain)
+        : recipeOperation(definition, spec, domain);
+    const names = preconditionNames();
+    let ast;
     try {
-        const ast = MutationAST.build((builder) => operation.build(input, richMutationBuilder(builder)));
-        return projectMutation(operation, await client.mutate(ast), input);
+        // `build` receives the handles a recipe's does, for the Classes it names and the ranges its
+        // guards take.
+        const d = lazyHandles(domain);
+        // What `build` returns reaches the core builder, which refuses a promise or a value.
+        ast = MutationAST.build((builder) => operation.build(input, richMutationBuilder(builder, names, operation.form), d));
+        return operation.output(await client.mutate(ast), input);
     }
     catch (cause) {
-        const expected = mutationFailure(cause);
+        // A refusal points at a precondition of the built Mutation by its index.
+        const built = ast;
+        const expected = mutationFailure(cause, built === undefined ? undefined : (index) => names.at(built, index));
         if (operation.reject !== undefined && expected !== undefined)
-            return operation.reject(expected);
+            return operation.reject(expected, input);
         throw cause;
     }
 }
+function closureOperation(mutation, domain) {
+    const definition = realizeMutation(mutation, domain);
+    return {
+        form: 'closure',
+        build: (input, builder, d) => definition.build(input, builder, d),
+        output: (result, input) => projectMutation(definition, result, input),
+        ...(definition.reject === undefined
+            ? {}
+            : { reject: (failure) => definition.reject(failure) }),
+    };
+}
+function recipeOperation(recipe, spec, domain) {
+    const { build, output, reject } = spec;
+    return {
+        form: 'recipe',
+        build: (input, builder, d) => {
+            const written = build(input, d, builder);
+            if (isPromiseLike(written)) {
+                // Refused before any write is sent: a write after its first await fails, and is observed.
+                ;
+                written.then(undefined, () => undefined);
+                throw new TypeError(`Mutation ${recipe.id}'s build is synchronous: it writes the Mutation, and awaits nothing.`);
+            }
+            return written;
+        },
+        output: (result, input) => (output === undefined ? result : output(result, input)),
+        ...(reject === undefined
+            ? {}
+            : {
+                reject: (failure, input) => reject(failure, input, outputContext(recipe, modelOf(domain))),
+            }),
+    };
+}
+function isPromiseLike(value) {
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+/**
+ * The Domain's handles, built on first use: a `build` that reads none never loads the Kernel's
+ * Classes they include.
+ */
+function lazyHandles(domain) {
+    let handles;
+    const resolved = () => (handles ??= handlesOf(domain));
+    // An extensible, empty target: every trap may then answer from the handles.
+    return new Proxy(Object.create(null), {
+        get: (_, key) => Reflect.get(resolved(), key),
+        has: (_, key) => Reflect.has(resolved(), key),
+        ownKeys: () => Reflect.ownKeys(resolved()),
+        getOwnPropertyDescriptor: (_, key) => {
+            const descriptor = Reflect.getOwnPropertyDescriptor(resolved(), key);
+            return descriptor === undefined ? undefined : { ...descriptor, configurable: true };
+        },
+    });
+}

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

@@ -1,7 +1,10 @@
 import type { Domain, schema } from '../../../platform/schema/index.js';
 import type { Mutation } from '../mutation.js';
 import type { MutationClient } from './execute.js';
-/** Invocation-bound executor for authored Mutation definitions. */
+/**
+ * Invocation-bound executor for Mutations of the closure form. A Mutation recipe names its
+ * authority on each call, `mutate(recipe, input, { as })`, so it is refused here.
+ */
 export interface MutationExecutor<DomainValue extends Domain = Domain> {
     <Input, Output>(definition: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;
 }

package/dist/application/mutation/execution/executor.js

@@ -1,7 +1,12 @@
+import { mutationRecipeSpecOf } from '../define.js';
 import { executeMutation } from './execute.js';
 /** Private Runtime binding to one Client and the exact loaded root Domain. */
 export function bindMutation(client, domain) {
     const executable = domain;
-    const execute = (definition, input) => executeMutation(client, executable, definition, input);
+    const execute = async (definition, input) => {
+        if (mutationRecipeSpecOf(definition) !== undefined)
+            throw new TypeError(`Mutation ${definition.id} is called with mutate(mutation, input, { as: 'executor' | 'caller' }).`);
+        return executeMutation(client, executable, definition, input);
+    };
     return execute;
 }

package/dist/application/mutation/failure.d.ts

@@ -7,6 +7,12 @@ export interface KernelMutationFailure extends Error {
      * refusal.
      */
     readonly rule?: string;
+    /**
+     * The name of the precondition a `MUTATION_PRECONDITION_FAILED` refusal points at: the `name`
+     * its `expect.*` verb was given. Absent when that precondition has no name, when the Kernel
+     * points at none, and for every other refusal.
+     */
+    readonly precondition?: string;
 }
 export interface StateTransitionFailure extends Error {
     readonly code: 'STATE_TRANSITION_ILLEGAL';
@@ -16,4 +22,8 @@ export interface StateTransitionFailure extends Error {
 }
 export type MutationFailure = KernelMutationFailure | StateTransitionFailure;
 export declare function stateTransitionFailure(from: string, event: string): StateTransitionFailure;
-export declare function mutationFailure(input: unknown): MutationFailure | undefined;
+/**
+ * The Mutation refusal `input` carries, if any. `nameAt` names the precondition at an index of
+ * the built Mutation's `preconditions`, the index a precondition refusal points at.
+ */
+export declare function mutationFailure(input: unknown, nameAt?: (index: number) => string | undefined): MutationFailure | undefined;