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

package/README.md

@@ -58,7 +58,8 @@ Install the URL printed by `astrale-domain deploy` on each intended instance.
 
 ## Handler authority and dependencies
 
-Handlers use Domain self authority for `kernel`, `graph`, `query`, and `mutate`.
+Handlers use Domain self authority for `kernel`, `graph`, Query V6 definitions, and a `mutate`
+given no options; a Query recipe, and a `mutate` given `{ as }`, name their authority on each call.
 `dependencies.directory.caller.invoke(d => d.functions.lookup, input)` calls a direct declared
 dependency on behalf of the incoming caller Identity; `.self` calls it as the executing Domain.
 Explicit `caller` or `self` authority is also available on `kernel` and `graph`; the former
@@ -66,6 +67,19 @@ handler `client` is removed. A call to an `auth: 'anonymous'` callable that carr
 has no caller: its handler acts as the Domain alone, without the `caller` selections. See
 [the API and migration guide](docs/handler-dependencies.md).
 
+## Queries
+
+`defineQuery<Schema>()(id, { build, output?, errors? })` defines a Query recipe: typed handles over
+the Domain (`d.Article.where((a) => a.state.eq('published')).first(50)`), reads bounded by
+their verbs, a pure `output` and declared errors. An Action calls
+`query(recipe, input, { as: 'executor' | 'caller' })`; a durable Workflow reads in
+`step.query(step, recipe, input, { as: 'executor' })`. Before anything is sent, the SDK checks the
+recipe's bounds and the requirements its relations need; `checkRecipe` from
+`@astrale-os/sdk/testing` runs both checks in a test, on the first stage it builds for a sample
+input. A recipe reads on a Host whose Kernel serves Query v7 and the Class of each row. Query V6
+definitions keep their meaning and are deprecated. See [the Query guide](docs/queries.md) and
+[Query V6 and the move to v7](docs/legacy/query-v6.md).
+
 ## Durable Workflows
 
 A callable declared with `execution: { durable: true }` is implemented by `defineWorkflow` and runs
@@ -332,7 +346,13 @@ a missing association makes that simulation unavailable.
 Use `session.release()` for the intrinsic Kernel's Release without its schema bundle or Views.
 It revalidates issuer, URL, size and ETag. Concurrent release and snapshot observations share
 acquisition; cancelling one observer does not cancel another. `session.snapshot()` returns one
-coherent Release, Bundle and View catalog observation.
+coherent Release and Bundle observation.
+
+A View is a Node that carries its own placement, whether its Domain declares it or a Mutation
+created it. Read Views from the graph, under the caller's read authority: `session.view(path)`
+reads one View by any Path, a Domain's entrypoint included, and `session.view({ domain })` lists
+the Views a Domain declares. The snapshot's `views` catalog and `session.viewsFor` are deprecated:
+they read Views from the Release rather than from their Nodes.
 
 ## Headless scripts and Domain callables
 

package/dist/application/action/context.d.ts

@@ -1,3 +1,4 @@
+import type { BinaryRequestBody } from '@astrale-os/kernel-core/callable';
 import type { AuthenticationEvidence, IdentityId } from '../../platform/auth/index.js';
 import type { BoundClientSession } from '../../platform/client/session/index.js';
 import type { NodeId } from '../../platform/graph/node/index.js';
@@ -5,15 +6,15 @@ import type { CallableInputOf, CallableInputModeOf, Domain, ResolvedFunction, Re
 import type { HandlerDependencies } from '../dependency/index.js';
 import type { DeclaredErrorFactory, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { IntegrationClients, Integrations } from '../integration/index.js';
-import type { MutationExecutor } from '../mutation/index.js';
-import type { QueryExecutor } from '../query/index.js';
+import type { Mutation, MutationExecutor, MutationInputOf, MutationOutputOf, MutationRecipe } from '../mutation/index.js';
+import type { InputOf, OutputOf, QueryDefinition, QueryExecutor, Recipe, RecipeOptions } from '../query/index.js';
 export type ResolvedCallable = ResolvedFunction | ResolvedMethod;
 /** Bearer-free caller evidence established before an Action or Workflow runs. */
 export interface AuthenticatedCaller {
     readonly kind: 'authenticated';
     /** The one Identity whose authority this invocation exercises: ownership and attribution. */
     readonly identity: IdentityId;
-    /** Executor whose credential directly authenticated this invocation (for example this Domain). */
+    /** Identity whose credential directly authenticated this invocation (for example this Domain). */
     readonly principal: IdentityId;
     readonly authentication: AuthenticationEvidence;
 }
@@ -33,11 +34,11 @@ export interface ActionExecution {
         body(): Uint8Array;
     };
 }
-/** One admitted, single-consumer binary Function request body. */
-export interface ActionBinaryInput {
-    readonly body: ReadableStream<Uint8Array>;
-    readonly length: number;
-}
+/**
+ * One admitted, single-consumer binary Function request body: the Core request body itself, so a
+ * handler can hand it as it is to the Kernel's content upload without reading it first.
+ */
+export type ActionBinaryInput = BinaryRequestBody;
 type BinaryInputOf<Callable> = CallableInputModeOf<Callable> extends 'binary' ? {
     readonly body: ActionBinaryInput;
 } : {
@@ -47,8 +48,35 @@ export interface DomainGraphExecutor<DomainValue extends Domain = Domain> {
     readonly query: QueryExecutor<DomainValue>;
     readonly mutate: MutationExecutor<DomainValue>;
 }
-/** Whose authority one Kernel call exercises: the incoming caller's or the installed Domain's. */
+/** Whose authority one Kernel call exercises: the incoming caller's or the executor's (`self`). */
 export type AuthorityMode = 'caller' | 'self';
+/**
+ * The name a call gives an authority with `as`: `executor` is `self`, the authority the handler
+ * executes with.
+ */
+export type AuthorityName<Authority extends AuthorityMode = AuthorityMode> = Authority extends 'self' ? 'executor' : 'caller';
+/**
+ * Reads under the authority `as` names. A recipe names it on every call; a V6 Query definition
+ * reads as the executor.
+ */
+export interface DomainQuery<DomainValue extends Domain = Domain, As extends AuthorityName = AuthorityName> {
+    <R extends Recipe>(recipe: R, input: InputOf<R>, options: RecipeOptions<R, As>): Promise<OutputOf<R>>;
+    <Output>(query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
+    <Input, Output>(query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
+}
+/**
+ * Writes under the authority `as` names. A Mutation recipe names it on every call; a Mutation of
+ * the closure form may omit it, and writes as the executor.
+ */
+export interface DomainMutate<DomainValue extends Domain = Domain, As extends AuthorityName = AuthorityName> {
+    <M extends MutationRecipe>(mutation: M, input: MutationInputOf<M>, options: {
+        readonly as: As;
+    }): Promise<MutationOutputOf<M>>;
+    <Input, Output>(definition: Mutation<DomainValue, Input, Output>, input: Input, options: {
+        readonly as: As;
+    }): Promise<Output>;
+    <Input, Output>(definition: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;
+}
 /**
  * One value per authority the code may act under. `self` exists in every invocation; `caller`
  * exists only when the call carried a credential, so it is absent from a call that carried none.
@@ -60,21 +88,24 @@ export type DomainGraphExecutors<DomainValue extends Domain = Domain, Authority
 /** Self-default Kernel session with one level of explicit authority selection. */
 export type DomainKernelSessions<Authority extends AuthorityMode = AuthorityMode> = Readonly<BoundClientSession & AuthoritySelection<BoundClientSession, Authority>>;
 /**
- * What code acting under `Authority` holds toward the Kernel and its dependencies, with the
- * installed Domain authority by default. An Action and a durable Step receive the same capabilities.
+ * What code acting under `Authority` holds toward the Kernel and its dependencies: `kernel` and
+ * `graph` act with the executor's authority by default. An Action and a durable Step receive the
+ * same capabilities.
+ * `query` and `mutate` take the authorities `As` names.
  */
-export interface DomainCapabilities<DomainValue extends Domain = Domain, Authority extends AuthorityMode = AuthorityMode> {
+export interface DomainCapabilities<DomainValue extends Domain = Domain, Authority extends AuthorityMode = AuthorityMode, As extends AuthorityName = AuthorityName<Authority>> {
     readonly dependencies: HandlerDependencies<DomainValue, Authority>;
     readonly kernel: DomainKernelSessions<Authority>;
     readonly graph: DomainGraphExecutors<DomainValue, Authority>;
-    /** Convenience executor using the installed Domain authority (`graph.self`). */
-    readonly query: QueryExecutor<DomainValue>;
-    /** Convenience executor using the installed Domain authority (`graph.self`). */
-    readonly mutate: MutationExecutor<DomainValue>;
+    /** A recipe under `as`; a V6 Query definition as the executor (`graph.self`). */
+    readonly query: DomainQuery<DomainValue, As>;
+    /** A Mutation under `as`, or as the executor (`graph.self`). */
+    readonly mutate: DomainMutate<DomainValue, As>;
 }
 /**
  * A call to an `anonymous` callable that carries no credential has no caller, and its handler acts
- * as the installed Domain alone. Every other call also selects its authenticated caller.
+ * as the executor alone. Every other call also selects its authenticated caller. An `anonymous`
+ * callable's `query` and `mutate` name the executor alone, whichever call it is.
  */
 type AuthorityOf<Callable, DomainValue extends Domain> = Callable extends {
     readonly auth: 'anonymous';
@@ -82,7 +113,7 @@ type AuthorityOf<Callable, DomainValue extends Domain> = Callable extends {
     readonly caller: AnonymousCaller;
 } & DomainCapabilities<DomainValue, 'self'>) | ({
     readonly caller: AuthenticatedCaller;
-} & DomainCapabilities<DomainValue, AuthorityMode>) : {
+} & DomainCapabilities<DomainValue, AuthorityMode, 'executor'>) : {
     readonly caller: AuthenticatedCaller;
 } & DomainCapabilities<DomainValue, AuthorityMode>;
 type SelfOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false> ? {

package/dist/application/action/index.d.ts

@@ -1,5 +1,5 @@
 export { defineAction, isAction } from './define.js';
 export type { Action, ActionAddress, ActionAddressOf, ActionDefinition, CallableAtAddress, LocalCallable, ResolvedDomainOf, } from './action.js';
-export type { ActionContext, ActionBinaryInput, ActionExecution, AnonymousCaller, AuthenticatedCaller, AuthorityMode, AuthoritySelection, Caller, DomainCapabilities, DomainGraphExecutor, DomainGraphExecutors, DomainKernelSessions, ResolvedCallable, } from './context.js';
+export type { ActionContext, ActionBinaryInput, ActionExecution, AnonymousCaller, AuthenticatedCaller, AuthorityMode, AuthorityName, AuthoritySelection, Caller, DomainCapabilities, DomainGraphExecutor, DomainGraphExecutors, DomainKernelSessions, DomainMutate, DomainQuery, ResolvedCallable, } from './context.js';
 export type { ActionBinary, ActionOutputOf } from './output.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, } from '../error/index.js';

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

@@ -10,6 +10,8 @@ export interface DeclaredErrorOptions<out Errors extends DeclaredErrors = Declar
 export type DeclaredErrorFactory<Errors extends DeclaredErrors> = <Code extends Extract<keyof Errors, string>>(code: Code, details: z.input<Errors[Code]['details']>) => Error;
 interface DeclaredErrorRecord {
     readonly definition: object;
+    /** The declaration as written: the object a Function re-declares a recipe's error with. */
+    readonly declaration: object;
     readonly code: string;
     readonly family: DeclaredErrorDefinition['family'];
     readonly message: string;
@@ -17,7 +19,20 @@ interface DeclaredErrorRecord {
 }
 /** Retain one implementation-local expected-error contract without publishing it in the Schema. */
 export declare function rememberDeclaredErrors(definition: object, input: unknown): void;
+/**
+ * Retain a recipe's declared errors, as an implementation's are. A Function that declares one of
+ * its codes with the same definition object exposes that error to its own caller.
+ */
+export declare function rememberRecipeErrors(recipe: object, id: string, input: unknown): void;
 /** Create a receiver-free factory closed over one admitted Action or Workflow definition. */
 export declare function declaredErrorFactory<Errors extends DeclaredErrors>(definition: object): DeclaredErrorFactory<Errors>;
-/** Return admitted evidence only when the error belongs to the active implementation. */
+/**
+ * Return admitted evidence only when the error belongs to the active implementation: raised by it,
+ * or by a recipe whose code it declares with the same definition object.
+ */
 export declare function declaredErrorOf(input: unknown, definition: object): DeclaredErrorRecord | undefined;
+/** The code and the recipe id of a recipe's declared error, whichever Function it reaches. */
+export declare function recipeErrorOf(input: unknown): {
+    readonly code: string;
+    readonly recipe: string;
+} | undefined;

package/dist/application/error/error.js

@@ -5,6 +5,8 @@ const MAXIMUM_DETAILS_BYTES = 16 * 1024;
 const CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,127}$/u;
 const declarations = new WeakMap();
 const errors = new WeakMap();
+/** Each recipe's id, by recipe: a recipe's errors cross into a Function that re-declares them. */
+const recipes = new WeakMap();
 class BusinessError extends Error {
     name = 'BusinessError';
     constructor(code) {
@@ -25,17 +27,29 @@ export function rememberDeclaredErrors(definition, input) {
     for (const [code, candidate] of entries) {
         if (!CODE_PATTERN.test(code))
             throw new TypeError(`Declared error code ${JSON.stringify(code)} is invalid.`);
-        accepted.set(code, acceptErrorDefinition(candidate, `Declared error ${JSON.stringify(code)}`));
+        accepted.set(code, {
+            accepted: acceptErrorDefinition(candidate, `Declared error ${JSON.stringify(code)}`),
+            declaration: candidate,
+        });
     }
     declarations.set(definition, accepted);
 }
+/**
+ * Retain a recipe's declared errors, as an implementation's are. A Function that declares one of
+ * its codes with the same definition object exposes that error to its own caller.
+ */
+export function rememberRecipeErrors(recipe, id, input) {
+    rememberDeclaredErrors(recipe, { errors: input });
+    recipes.set(recipe, id);
+}
 /** Create a receiver-free factory closed over one admitted Action or Workflow definition. */
 export function declaredErrorFactory(definition) {
     return ((code, input) => {
-        const declaration = declarations.get(definition)?.get(code);
-        if (declaration === undefined) {
+        const declared = declarations.get(definition)?.get(code);
+        if (declared === undefined) {
             throw new TypeError(`Business error ${JSON.stringify(code)} is not declared by this implementation.`);
         }
+        const { accepted: declaration } = declared;
         const parsed = declaration.details.safeParse(input);
         if (!parsed.success) {
             throw new TypeError(`Business error ${code} details are invalid.`, { cause: parsed.error });
@@ -56,6 +70,7 @@ export function declaredErrorFactory(definition) {
         const error = new BusinessError(code);
         errors.set(error, Object.freeze({
             definition,
+            declaration: declared.declaration,
             code,
             family: declaration.family,
             message: declaration.message,
@@ -64,12 +79,31 @@ export function declaredErrorFactory(definition) {
         return error;
     });
 }
-/** Return admitted evidence only when the error belongs to the active implementation. */
+/**
+ * Return admitted evidence only when the error belongs to the active implementation: raised by it,
+ * or by a recipe whose code it declares with the same definition object.
+ */
 export function declaredErrorOf(input, definition) {
     if (!(input instanceof Error))
         return undefined;
     const record = errors.get(input);
-    return record?.definition === definition ? record : undefined;
+    if (record === undefined)
+        return undefined;
+    if (record.definition === definition)
+        return record;
+    if (!recipes.has(record.definition))
+        return undefined;
+    return declarations.get(definition)?.get(record.code)?.declaration === record.declaration
+        ? record
+        : undefined;
+}
+/** The code and the recipe id of a recipe's declared error, whichever Function it reaches. */
+export function recipeErrorOf(input) {
+    const record = input instanceof Error ? errors.get(input) : undefined;
+    if (record === undefined)
+        return undefined;
+    const recipe = recipes.get(record.definition);
+    return recipe === undefined ? undefined : { code: record.code, recipe };
 }
 function isRecord(input) {
     return input !== null && typeof input === 'object' && !Array.isArray(input);

package/dist/application/error/index.d.ts

@@ -1,2 +1,2 @@
 export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, NoDeclaredErrors, } from './error.js';
-export { declaredErrorFactory, declaredErrorOf, rememberDeclaredErrors } from './error.js';
+export { declaredErrorFactory, declaredErrorOf, recipeErrorOf, rememberDeclaredErrors, rememberRecipeErrors, } from './error.js';

package/dist/application/error/index.js

@@ -1 +1 @@
-export { declaredErrorFactory, declaredErrorOf, rememberDeclaredErrors } from './error.js';
+export { declaredErrorFactory, declaredErrorOf, recipeErrorOf, rememberDeclaredErrors, rememberRecipeErrors, } from './error.js';

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

@@ -1,55 +1,103 @@
 import type { EdgeSlug } from '@astrale-os/kernel-core/graph/edge';
 import type { MutationBuilder } from '@astrale-os/kernel-core/graph/mutate';
-import type { QueryEdgeAST, QueryNodeAST } from '@astrale-os/kernel-core/graph/query';
 import type { ResolvedClass } from '@astrale-os/kernel-dsl/v1';
+import type { Cls } from '../../query/handles/domain.js';
+import type { EdgeSet, NodeSet } from '../../query/handles/handles.js';
+import type { ClosureMutationBuilder } from '../legacy/v6/builder.js';
 import type { CreatedNode, ExistingEndpoint, MutationEndpoint } from './endpoint.js';
-import type { QueryPrecondition } from './precondition.js';
+import type { CountBounds, GuardIdentity, GuardRange, PreconditionOptions } from './guard.js';
 import type { RichPropertyConditions, RichPropertyDelta, RichPropertyInput } from './properties.js';
+import { type PreconditionNames } from './names.js';
 import { type EventOfTopology, type StatePropertyName, type StatePropertyTopology, type StateOfTopology, type StateTransitionInput } from './transition.js';
-export interface RichMutationBuilder {
+/**
+ * The builder a Mutation's `build` receives: of the recipe form over `Schema`
+ * (`RichMutationBuilder<Schema>`), or of the deprecated closure form (`RichMutationBuilder`).
+ */
+export type RichMutationBuilder<Schema = never> = [Schema] extends [never] ? ClosureMutationBuilder : RecipeMutationBuilder<Schema>;
+/** A write names one Class: the handle of a union, `d.A.union(d.B)`, names none. */
+type OneClass<K, All = K> = K extends unknown ? [All] extends [K] ? unknown : '✗ a write names one Class, not a union' : never;
+/** A Node Class handle, `d.<Class>`, on which no method was called. */
+type NodeClassHandle<S, K extends string> = NodeSet<S, K, {}, 'value', false> & OneClass<K>;
+/** An Edge Class handle, `d.<Edge>`, on which no method was called. */
+type EdgeClassHandle<S, E extends string> = EdgeSet<S, E, 'value', false>;
+type NodeClassOf<S, K extends string> = Extract<Cls<S, K>, ResolvedClass<'node'>>;
+interface HandleEdgeSelector<S, E extends string> {
+    readonly source: ExistingEndpoint;
+    readonly target: ExistingEndpoint;
+    readonly class: EdgeClassHandle<S, E>;
+}
+/**
+ * The builder a Mutation recipe's `build` receives (D31): each verb names its Class by its handle,
+ * `d.<Class>`, and each guard takes a range. Each precondition verb (`expect.*`) takes `{ name }`
+ * last: a refusal of the Mutation because that precondition fails carries the name as
+ * `failure.precondition`. A name is unique in its Mutation.
+ */
+export interface RecipeMutationBuilder<S> {
     readonly expect: {
-        node<Class extends ResolvedClass<'node'>>(input: {
+        /** The Node exists, of this Class, and its Properties meet `props`. */
+        node<K extends string>(input: {
             readonly node: ExistingEndpoint;
-            readonly class: Class;
-            readonly props?: RichPropertyConditions<Class>;
-        }): RichMutationBuilder;
-        edge<Class extends ResolvedClass<'edge'>>(input: EdgeSelector<Class> & {
+            readonly class: NodeClassHandle<S, K>;
+            readonly props?: RichPropertyConditions<Cls<S, K>>;
+        }, options?: PreconditionOptions): RecipeMutationBuilder<S>;
+        /** The Edge exists, its slug is `slug`, and its Properties meet `props`. */
+        edge<E extends string>(input: HandleEdgeSelector<S, E> & {
             readonly slug?: EdgeSlug | null;
-            readonly props?: RichPropertyConditions<Class>;
-        }): RichMutationBuilder;
-        query<Query extends QueryNodeAST | QueryEdgeAST>(input: QueryPrecondition<Query>): RichMutationBuilder;
+            readonly props?: RichPropertyConditions<Cls<S, E>>;
+        }, options?: PreconditionOptions): RecipeMutationBuilder<S>;
+        /**
+         * A guard (Mutation v4): no root of the range matches. A range is a Class handle after
+         * `where`, `union` and `orderBy`, `d.<Class>.where(…)`, or a canonical v7 Query.
+         */
+        none<K extends string>(range: GuardRange<S, K>, options?: PreconditionOptions): RecipeMutationBuilder<S>;
+        /** A guard (Mutation v4): a root of the range matches. */
+        exists<K extends string>(range: GuardRange<S, K>, options?: PreconditionOptions): RecipeMutationBuilder<S>;
+        /**
+         * A guard (Mutation v4): the number of the range's roots is `bounds`, or lies within
+         * `{ atLeast?, atMost? }`, bounded at least once.
+         */
+        count<K extends string>(range: GuardRange<S, K>, bounds: CountBounds, options?: PreconditionOptions): RecipeMutationBuilder<S>;
+        /**
+         * A guard (Mutation v4): the range's roots, in its `orderBy`, are exactly these identities, in
+         * the order a read of them returned them: a `NodeId` per Node, an `EdgeKey` per Edge.
+         */
+        unchanged<K extends string>(range: GuardRange<S, K>, ids: readonly GuardIdentity[], options?: PreconditionOptions): RecipeMutationBuilder<S>;
     };
-    createNode<Class extends ResolvedClass<'node'>>(input: {
+    createNode<K extends string>(input: {
         readonly as: string;
-        readonly class: Class;
-        readonly props?: RichPropertyInput<Class>;
-    }): CreatedNode<Class>;
-    updateNode<Class extends ResolvedClass<'node'>>(input: {
+        readonly class: NodeClassHandle<S, K>;
+        readonly props?: RichPropertyInput<Cls<S, K>>;
+    }): CreatedNode<NodeClassOf<S, K>>;
+    updateNode<K extends string>(input: {
         readonly node: ExistingEndpoint;
-        readonly class: Class;
-        readonly props: RichPropertyDelta<Class>;
+        readonly class: NodeClassHandle<S, K>;
+        readonly props: RichPropertyDelta<Cls<S, K>>;
     }): this;
-    transition<Class extends ResolvedClass<'node'>, Property extends StatePropertyName<Class>, From extends StateOfTopology<StatePropertyTopology<Class, Property>>, Event extends EventOfTopology<StatePropertyTopology<Class, Property>, From>>(input: StateTransitionInput<Class, Property, From, Event>): this;
-    deleteNode<Class extends ResolvedClass<'node'>>(input: {
+    transition<K extends string, Property extends StatePropertyName<NodeClassOf<S, K>>, From extends StateOfTopology<StatePropertyTopology<NodeClassOf<S, K>, Property>>, Event extends EventOfTopology<StatePropertyTopology<NodeClassOf<S, K>, Property>, From>>(input: StateTransitionInput<NodeClassOf<S, K>, Property, From, Event, NodeClassHandle<S, K>>): this;
+    deleteNode<K extends string>(input: {
         readonly node: ExistingEndpoint;
-        readonly class: Class;
+        readonly class: NodeClassHandle<S, K>;
     }): this;
-    createEdge<Class extends ResolvedClass<'edge'>>(input: {
-        readonly class: Class;
+    createEdge<E extends string>(input: {
+        readonly class: EdgeClassHandle<S, E>;
         readonly source: MutationEndpoint;
         readonly target: MutationEndpoint;
         readonly slug?: EdgeSlug;
-        readonly props?: RichPropertyInput<Class>;
+        readonly props?: RichPropertyInput<Cls<S, E>>;
     }): this;
-    updateEdge<Class extends ResolvedClass<'edge'>>(input: EdgeSelector<Class> & {
+    updateEdge<E extends string>(input: HandleEdgeSelector<S, E> & {
         readonly slug?: EdgeSlug | null;
-        readonly props?: RichPropertyDelta<Class>;
+        readonly props?: RichPropertyDelta<Cls<S, E>>;
     }): this;
-    deleteEdge<Class extends ResolvedClass<'edge'>>(input: EdgeSelector<Class>): this;
-}
-export interface EdgeSelector<Class extends ResolvedClass<'edge'>> {
-    readonly source: ExistingEndpoint;
-    readonly target: ExistingEndpoint;
-    readonly class: Class;
+    deleteEdge<E extends string>(input: HandleEdgeSelector<S, E>): this;
 }
-export declare function richMutationBuilder(core: MutationBuilder): RichMutationBuilder;
+/** The form of the Mutation a builder writes: a recipe's, or the deprecated closure form's. */
+export type BuilderForm = 'recipe' | 'closure';
+/**
+ * The SDK's builder over the core one, for both forms: a verb's Class is a Class handle
+ * (`d.<Class>`) or, in the closure form only, the resolved Class, and only the closure form has a
+ * V6 Query precondition (`expect.query`). `names` keeps the names of its preconditions, so that
+ * the Mutation's execution can name the one a refusal points at.
+ */
+export declare function richMutationBuilder(portable: MutationBuilder, names?: PreconditionNames, form?: BuilderForm): ClosureMutationBuilder;
+export {};

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

@@ -1,77 +1,125 @@
 import { ClassKey } from '@astrale-os/kernel-dsl/v1/addressing';
 import { LocalAlias } from '../../../platform/graph/alias.js';
+import { handleClass } from '../../query/handles/reads.js';
+import { precondition } from '../legacy/v6/precondition.js';
 import { endpoint, existingEndpoint } from './endpoint.js';
-import { precondition } from './precondition.js';
+import { countGuard, existsGuard, sequenceGuard } from './guard.js';
+import { preconditionNames } from './names.js';
 import { conditions, delta, properties } from './properties.js';
 import { authorStateTransition, } from './transition.js';
-export function richMutationBuilder(core) {
-    const expectation = Object.freeze({
-        node(input) {
-            core.expect.node({
-                node: existingEndpoint(input.node),
-                class: classKey(input.class),
-                ...(input.props === undefined ? {} : { props: conditions(input.class, input.props) }),
+/**
+ * The SDK's builder over the core one, for both forms: a verb's Class is a Class handle
+ * (`d.<Class>`) or, in the closure form only, the resolved Class, and only the closure form has a
+ * V6 Query precondition (`expect.query`). `names` keeps the names of its preconditions, so that
+ * the Mutation's execution can name the one a refusal points at.
+ */
+export function richMutationBuilder(portable, names = preconditionNames(), form = 'closure') {
+    const core = names.track(portable);
+    const nodeClass = (selected) => writtenClass(selected, 'node', form);
+    const edgeClass = (selected) => writtenClass(selected, 'edge', form);
+    const guards = {
+        node(input, options) {
+            const cls = nodeClass(input.class);
+            names.name(nameOf(options), () => {
+                core.expect.node({
+                    node: existingEndpoint(input.node),
+                    class: classKey(cls),
+                    ...(input.props === undefined ? {} : { props: conditions(cls, input.props) }),
+                });
             });
             return rich;
         },
-        edge(input) {
-            core.expect.edge({
-                source: existingEndpoint(input.source),
-                target: existingEndpoint(input.target),
-                class: classKey(input.class),
-                ...(Object.hasOwn(input, 'slug') ? { slug: input.slug ?? null } : {}),
-                ...(input.props === undefined ? {} : { props: conditions(input.class, input.props) }),
+        edge(input, options) {
+            const cls = edgeClass(input.class);
+            names.name(nameOf(options), () => {
+                core.expect.edge({
+                    source: existingEndpoint(input.source),
+                    target: existingEndpoint(input.target),
+                    class: classKey(cls),
+                    ...(Object.hasOwn(input, 'slug') ? { slug: input.slug ?? null } : {}),
+                    ...(input.props === undefined ? {} : { props: conditions(cls, input.props) }),
+                });
             });
             return rich;
         },
-        query(input) {
-            precondition(core, input);
+        none(range, options) {
+            names.name(nameOf(options), () => core.expect.query(existsGuard(range, false)));
             return rich;
         },
-    });
+        exists(range, options) {
+            names.name(nameOf(options), () => core.expect.query(existsGuard(range, true)));
+            return rich;
+        },
+        count(range, bounds, options) {
+            names.name(nameOf(options), () => core.expect.query(countGuard(range, bounds)));
+            return rich;
+        },
+        unchanged(range, ids, options) {
+            names.name(nameOf(options), () => core.expect.query(sequenceGuard(range, ids)));
+            return rich;
+        },
+    };
+    const expectation = Object.freeze(form === 'recipe'
+        ? guards
+        : {
+            ...guards,
+            query(input) {
+                precondition(core, input);
+                return rich;
+            },
+        });
     const rich = Object.freeze({
         expect: expectation,
         createNode(input) {
+            const cls = nodeClass(input.class);
             const created = core.createNode({
                 as: LocalAlias(input.as),
-                class: classKey(input.class),
-                ...(input.props === undefined ? {} : { props: properties(input.class, input.props) }),
+                class: classKey(cls),
+                ...(input.props === undefined ? {} : { props: properties(cls, input.props) }),
             });
-            return Object.freeze({ ...created, class: input.class });
+            return Object.freeze({ ...created, class: cls });
         },
         updateNode(input) {
+            const cls = nodeClass(input.class);
             core.updateNode({
                 node: existingEndpoint(input.node),
-                class: classKey(input.class),
-                props: delta(input.class, input.props),
+                class: classKey(cls),
+                props: delta(cls, input.props),
             });
             return rich;
         },
         transition(input) {
-            authorStateTransition(core, input);
+            // Each coordinate is read once: the copy is what the transition reads.
+            const coordinates = { ...input };
+            authorStateTransition(core, { ...coordinates, class: nodeClass(coordinates.class) });
             return rich;
         },
         deleteNode(input) {
-            core.deleteNode({ node: existingEndpoint(input.node), class: classKey(input.class) });
+            core.deleteNode({
+                node: existingEndpoint(input.node),
+                class: classKey(nodeClass(input.class)),
+            });
             return rich;
         },
         createEdge(input) {
+            const cls = edgeClass(input.class);
             core.createEdge({
-                class: classKey(input.class),
+                class: classKey(cls),
                 source: endpoint(input.source),
                 target: endpoint(input.target),
                 ...(input.slug === undefined ? {} : { slug: input.slug }),
-                ...(input.props === undefined ? {} : { props: properties(input.class, input.props) }),
+                ...(input.props === undefined ? {} : { props: properties(cls, input.props) }),
             });
             return rich;
         },
         updateEdge(input) {
+            const cls = edgeClass(input.class);
             const selector = {
                 source: existingEndpoint(input.source),
                 target: existingEndpoint(input.target),
-                class: classKey(input.class),
+                class: classKey(cls),
             };
-            const patch = input.props === undefined ? undefined : delta(input.class, input.props);
+            const patch = input.props === undefined ? undefined : delta(cls, input.props);
             if (Object.hasOwn(input, 'slug')) {
                 core.updateEdge({
                     ...selector,
@@ -90,13 +138,35 @@ export function richMutationBuilder(core) {
             core.deleteEdge({
                 source: existingEndpoint(input.source),
                 target: existingEndpoint(input.target),
-                class: classKey(input.class),
+                class: classKey(edgeClass(input.class)),
             });
             return rich;
         },
     });
     return rich;
 }
+/** The Class a verb names: by its handle, or, in the closure form, as resolved. */
+function writtenClass(selected, kind, form) {
+    const cls = handleClass(selected);
+    if (cls === undefined) {
+        if (form === 'recipe')
+            throw new TypeError('A Mutation recipe names each Class by its handle, `d.<Class>`.');
+        return selected;
+    }
+    if (kind === 'node' && cls.kind === 'edge')
+        throw new TypeError(`This verb writes a Node, and ${cls.key} is an Edge Class.`);
+    if (kind === 'edge' && cls.kind !== 'edge')
+        throw new TypeError(`This verb writes an Edge, and ${cls.key} is a Node Class.`);
+    return cls;
+}
 function classKey(selected) {
     return ClassKey(selected.key);
 }
+function nameOf(options) {
+    if (options === undefined)
+        return undefined;
+    if (options === null || typeof options !== 'object') {
+        throw new TypeError("A precondition's options are `{ name }`.");
+    }
+    return options.name;
+}