@afora/core 0.0.8 → 0.0.11

package/dist/core/use-case/steps/types/check.interface.d.ts

@@ -0,0 +1,233 @@
+/**
+ * The compile-time checking of `useCaseOf({ steps })`: the steps are inferred
+ * as a tuple and folded in order. Each step sees the values in scope (the
+ * input, the context, the environments and the names bound by the earlier
+ * steps with `as`); its references must name a path of one of them, and its
+ * `args`, `values`, `value` or `input` must fit what the called function,
+ * record, repository or use case takes. A reference that does not fit is
+ * replaced by the references that would, which is the error TypeScript shows
+ * and what the editor offers inside a `"$…"` string.
+ *
+ * The list of the paths of the scope is computed only for a reference that
+ * does not fit, so that right steps cost little to check. The conditionals on
+ * the steps are not distributive (`[Step] extends [...]`): TypeScript then
+ * never evaluates them with the constraint of the steps while it infers them.
+ */
+import type { BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection } from "../../../blueprint/types/blueprint.interface.js";
+import type { AnyEnvironment, EnvironmentValue } from "../../../environment/environment.js";
+import type { Meta } from "../../../symbols/meta.js";
+import type { AnyUseCaseClass, UseCaseInput, UseCaseResponse } from "../../use-case.js";
+/** The values the first step can reference: the input, the context (if declared) and the environments. */
+export type StepsInitialScope<Input extends IBlueprintCollection, Context extends IBlueprintCollection | undefined, Dependencies> = {
+    readonly input: BlueprintValue<Input>;
+    readonly env: {
+        readonly [Key in keyof Dependencies as Dependencies[Key] extends AnyEnvironment ? Key : never]: Dependencies[Key] extends AnyEnvironment ? EnvironmentValue<Dependencies[Key]> : never;
+    };
+} & (Context extends IBlueprintCollection ? {
+    readonly context: BlueprintValue<Context>;
+} : unknown);
+type Split<Path extends string> = Path extends `${infer Head}.${infer Tail}` ? [Head, ...Split<Tail>] : [Path];
+/** `Value[Key]` for a value that is not `null` or `undefined`: by index (or `length`) in a list; `never` when absent. */
+type GetDefined<Value, Key extends string> = Value extends readonly unknown[] ? Key extends `${number}` ? Key extends keyof Value ? Value[Key] : Value[number] : Key extends "length" ? number : never : Key extends keyof Value ? Value[Key] : never;
+/**
+ * `Value[Key]` as `followPath` reads it: `undefined` through a value that
+ * may be `undefined` or `null`, and `never` when no value of the type has
+ * the key; `unknown` stays `unknown`.
+ */
+type Get<Value, Key extends string> = unknown extends Value ? unknown : [GetDefined<NonNullable<Value>, Key>] extends [infer Found] ? [Found] extends [never] ? never : Found | (Value extends null | undefined ? undefined : never) : never;
+type Walk<Value, Path extends readonly string[]> = Path extends readonly [
+    infer Key extends string,
+    ...infer Rest extends string[]
+] ? Walk<Get<Value, Key>, Rest> : Value;
+/** The type of the value the reference `$root.a.b` stands for in `Scope`; `never` when it names nothing. */
+export type StepReferenceType<Scope, Reference> = [Reference] extends [
+    `$${infer Path}`
+] ? Split<Path> extends [
+    infer Root extends string,
+    ...infer Rest extends string[]
+] ? Root extends "env" ? Rest extends [string, ...string[]] ? Walk<Get<Scope, Root>, Rest> : never : Walk<Get<Scope, Root>, Rest> : never : never;
+/** What a path walks into: the value of a record, not its methods. */
+type DataOf<Value> = Value extends {
+    readonly [Meta]: {
+        readonly blueprint: IBlueprint<infer Properties>;
+    };
+} ? BlueprintValue<Properties> : Value;
+type Leaf = string | number | boolean | bigint | symbol | null | undefined | Date | readonly unknown[] | ((...args: any[]) => unknown);
+type Below<Value, Prefix extends string, Expected, Depth extends unknown[]> = Depth["length"] extends 3 ? never : DataOf<NonNullable<Value>> extends infer Data ? Data extends Leaf ? never : {
+    [Key in keyof Data & string]-?: PathsFrom<Data[Key] | (Value extends null | undefined ? undefined : never), `${Prefix}.${Key}`, Expected, [
+        ...Depth,
+        0
+    ]>;
+}[keyof Data & string] : never;
+type PathsFrom<Value, Path extends string, Expected, Depth extends unknown[]> = Path extends unknown ? ([Value] extends [Expected] ? Path : never) | Below<Value, Path, Expected, Depth> : never;
+/** Every reference of `Scope` whose value fits `Expected` (three keys deep at most). */
+export type StepReferencesOf<Scope, Expected = unknown> = Scope extends unknown ? {
+    [Root in keyof Scope & string]-?: Root extends "env" ? Below<Scope[Root], `$${Root}`, Expected, [0]> : PathsFrom<Scope[Root], `$${Root}`, Expected, []>;
+}[keyof Scope & string] : never;
+/**
+ * The references of `Scope` that fit `Expected`, or `Expected` itself when
+ * none does, so that the error names the type that is taken rather than `never`.
+ */
+type Suggested<Expected, Scope> = [StepReferencesOf<Scope, Expected>] extends [
+    infer References
+] ? [References] extends [never] ? Expected : References : never;
+/**
+ * `Reference` when it names a value of `Scope` that fits `Expected`; else the
+ * references that would, and, when it only fails because it may be
+ * `undefined`, a hint to ensure it exists first.
+ */
+type CheckReference<Reference, Expected, Scope> = [
+    StepReferenceType<Scope, Reference>
+] extends [infer Type] ? [Type] extends [never] ? Suggested<Expected, Scope> : [Type] extends [Expected] ? Reference : [NonNullable<Type>] extends [Expected] ? Suggested<Expected, Scope> | `${Reference & string} may be undefined: ensure it exists first` : Suggested<Expected, Scope> : never;
+type Primitive = string | number | boolean | null;
+/** The type of the key `Key` in what `Expected` takes, over each object of it. */
+type ExpectedAt<Expected, Key> = Expected extends object ? Key extends keyof Expected ? Expected[Key] : never : never;
+/** The keys `Expected` takes in a mapping. */
+type KnownKeys<Expected> = Expected extends object ? keyof Expected : never;
+/** The keys the plain objects of `Expected` require (a record instance is not built from a mapping). */
+type RequiredKeys<Expected> = Expected extends {
+    readonly [Meta]: unknown;
+} ? never : Expected extends object ? {
+    [Key in keyof Expected]-?: undefined extends Expected[Key] ? never : Key;
+}[keyof Expected] : never;
+/** The keys of `Value` that `Expected` takes, each checked; the others are excess properties. */
+type CheckKeys<Value, Expected, Scope> = Value extends unknown ? {
+    readonly [Key in keyof Value as Key extends KnownKeys<Expected> ? Key : never]: StepValueCheck<Value[Key], ExpectedAt<Expected, Key>, Scope>;
+} : never;
+type CheckMapping<Value, Expected, Scope> = unknown extends Expected ? {
+    readonly [Key in keyof Value]: StepValueCheck<Value[Key], unknown, Scope>;
+} : [Exclude<RequiredKeys<Expected>, keyof Value>] extends [never] ? CheckKeys<Value, Expected, Scope> : CheckKeys<Value, Expected, Scope> & {
+    readonly [Key in Exclude<RequiredKeys<Expected>, keyof Value>]: ExpectedAt<Expected, Key>;
+};
+type ElementAt<Expected, Index> = unknown extends Expected ? unknown : Expected extends readonly unknown[] ? Index extends keyof Expected ? Expected[Index] : Expected[number] : never;
+/**
+ * What the step value `Value` must be where `Expected` is taken: itself when
+ * it fits; else, for a reference, the references that would fit, and for a
+ * literal, `Expected`. A mapping is checked key by key, a list item by item.
+ */
+export type StepValueCheck<Value, Expected, Scope> = [Value] extends [
+    `$${string}`
+] ? CheckReference<Value, Expected, Scope> : [Value] extends [Primitive] ? [Value] extends [Expected] ? Value : Expected : [Value] extends [{
+    readonly literal: unknown;
+}] ? Value : [Value] extends [readonly unknown[]] ? {
+    readonly [Index in keyof Value]: StepValueCheck<Value[Index], ElementAt<Expected, Index>, Scope>;
+} : [Value] extends [object] ? CheckMapping<Value, Expected, Scope> : Value;
+/** The parameter `Index` of a function whose parameters are `Parameters`. */
+type ParameterAt<Parameters extends readonly unknown[], Index> = Index extends keyof Parameters ? Parameters[Index] : number extends Parameters["length"] ? Parameters[number] : undefined;
+/** What the `args` of a call must be: each against its parameter, or one reference to a list. */
+type CheckArgs<Args, Parameters extends readonly unknown[], Scope> = [
+    Args
+] extends [`$${string}`] ? CheckReference<Args, readonly unknown[], Scope> : {
+    readonly [Index in keyof Args]: StepValueCheck<Args[Index], ParameterAt<Parameters, Index>, Scope>;
+};
+type Fn = (...args: any[]) => unknown;
+type ParametersOf<Value> = [Value] extends [Fn] ? Parameters<Value> : unknown[];
+type FirstParameter<Value> = [Value] extends [never] ? unknown : [Value] extends [Fn] ? Parameters<Value>[0] : unknown;
+type ResultOf<Value> = [Value] extends [Fn] ? Awaited<ReturnType<Value>> : unknown;
+/** `Dependencies[Key][Member]`, or `unknown`. */
+type MemberOf<Dependencies, Key, Member> = Key extends keyof Dependencies ? Member extends keyof Dependencies[Key] ? Dependencies[Key][Member] : unknown : unknown;
+/** The method `"users.findByEmail"` names among `Dependencies`. */
+type FindMethod<Dependencies, Target> = Target extends `${infer Repository}.${infer Action}` ? MemberOf<Dependencies, Repository, Action> : unknown;
+/** The members of a record no `invoke` may call. */
+type ForbiddenMethod = "set" | "emit" | "constructor" | "toLocaleString" | "valueOf" | "hasOwnProperty" | "isPrototypeOf" | "propertyIsEnumerable";
+/** The public methods of the record `Record`: what `invoke.method` names. */
+type StepInvokeMethod<Record> = Record extends unknown ? {
+    [Key in keyof Record & string]-?: Record[Key] extends Fn ? Key : never;
+}[Exclude<keyof Record & string, ForbiddenMethod>] : never;
+type ChangeOf<Record> = Record extends {
+    readonly change: infer Change;
+} ? Change : never;
+type UseCaseOf<Dependencies, Key> = Key extends keyof Dependencies ? Dependencies[Key] extends AnyUseCaseClass ? Dependencies[Key] : never : never;
+/** A step that calls `Method` with its `args`: `[checked step, result]`. */
+type CallStep<Step, Method, Scope> = [
+    {
+        readonly [Key in keyof Step]: Key extends "args" ? CheckArgs<Step[Key], ParametersOf<Method>, Scope> : Step[Key];
+    },
+    ResultOf<Method>
+];
+/** A step whose `Field` is checked against `Expected`: `[checked step, result]`. */
+type ValueStep<Step, Field, Expected, Result, Scope> = [
+    {
+        readonly [Key in keyof Step]: Key extends Field ? StepValueCheck<Step[Key], Expected, Scope> : Step[Key];
+    },
+    Result
+];
+type InvokeStep<Step, Record, Scope> = [Record] extends [never] ? ValueStep<Step, "invoke", object, unknown, Scope> : [Step] extends [{
+    readonly method: infer Method;
+}] ? Method extends keyof Record ? CallStep<Step, Record[Method], Scope> : [
+    {
+        readonly [Key in keyof Step]: Key extends "method" ? StepInvokeMethod<Record> : Step[Key];
+    },
+    unknown
+] : [Step, unknown];
+type ChangeStep<Step, Record, Scope> = [Record] extends [never] ? ValueStep<Step, "change", object, unknown, Scope> : [Step] extends [{
+    readonly key: infer Name;
+}] ? Name extends keyof ChangeOf<Record> ? ValueStep<Step, "value", FirstParameter<ChangeOf<Record>[Name]>, Record, Scope> : [
+    {
+        readonly [Key in keyof Step]: Key extends "key" ? keyof ChangeOf<Record> & string : Step[Key];
+    },
+    Record
+] : [Step, Record];
+/** `[what Step must be, what it gives to its as]`, read against `Scope`. */
+type CheckStep<Step, Dependencies, Scope, Response> = [Step] extends [
+    {
+        readonly find: infer Target;
+    }
+] ? CallStep<Step, FindMethod<Dependencies, Target>, Scope> : [Step] extends [{
+    readonly run: unknown;
+    readonly fn: infer Run;
+}] ? CallStep<Step, Run, Scope> : [Step] extends [{
+    readonly invoke: infer Reference;
+}] ? InvokeStep<Step, NonNullable<StepReferenceType<Scope, Reference>>, Scope> : [Step] extends [{
+    readonly change: infer Reference;
+}] ? ChangeStep<Step, NonNullable<StepReferenceType<Scope, Reference>>, Scope> : [Step] extends [
+    {
+        readonly build: abstract new (value: infer Input) => infer Built;
+    }
+] ? ValueStep<Step, "values", Input, Built, Scope> : [Step] extends [{
+    readonly call: infer Name;
+}] ? ValueStep<Step, "input", UseCaseInput<UseCaseOf<Dependencies, Name>>, UseCaseResponse<UseCaseOf<Dependencies, Name>>, Scope> : [Step] extends [{
+    readonly create: infer Repository;
+}] ? WriteStep<Step, MemberOf<Dependencies, Repository, "create">, Scope> : [Step] extends [{
+    readonly update: infer Repository;
+}] ? WriteStep<Step, MemberOf<Dependencies, Repository, "update">, Scope> : [Step] extends [{
+    readonly delete: infer Repository;
+}] ? WriteStep<Step, MemberOf<Dependencies, Repository, "delete">, Scope> : [Step] extends [{
+    readonly restore: infer Repository;
+}] ? WriteStep<Step, MemberOf<Dependencies, Repository, "restore">, Scope> : [Step] extends [{
+    readonly return: unknown;
+}] ? ValueStep<Step, "return", ResponseInput<Response>, unknown, Scope> : ValueStep<Step, "value" | "other" | "details", unknown, unknown, Scope>;
+/** What the response blueprint `Response` takes, or anything when it is not known. */
+type ResponseInput<Response> = [Response] extends [IBlueprintCollection] ? BlueprintInput<Response> : unknown;
+type WriteStep<Step, Method, Scope> = ValueStep<Step, "value", FirstParameter<Method>, ResultOf<Method>, Scope>;
+/** The scope after `Step`: its result bound to its `as`, or a value it ensures exists. */
+type ScopeAfter<Step, Result, Scope> = [Step] extends [
+    {
+        readonly as: infer Name extends string;
+    }
+] ? Scope & {
+    readonly [Key in Name]: Result;
+} : [Step] extends [
+    {
+        readonly ensure: "exists";
+        readonly value: `$${infer Name}`;
+    }
+] ? Name extends keyof Scope ? Scope & {
+    readonly [Key in Name]: NonNullable<Scope[Name]>;
+} : Scope : Scope;
+/** The steps folded in order, each checked against the scope the earlier ones built. */
+type CheckSteps<Steps extends readonly unknown[], Dependencies, Scope, Response, Checked extends readonly unknown[] = []> = [Steps] extends [readonly [infer Step, ...infer Rest]] ? CheckStep<Step, Dependencies, Scope, Response> extends [
+    infer Current,
+    infer Result
+] ? CheckSteps<Rest, Dependencies, ScopeAfter<Step, Result, Scope>, Response, [
+    ...Checked,
+    Current
+]> : never : readonly [...Checked];
+/**
+ * What `useCaseOf` takes as `steps`: the steps, inferred as a tuple, each
+ * checked against the values in scope, and the `return` against what the
+ * response blueprint (the collection `Response`) takes. Steps that are not a tuple (built at
+ * run time) are checked only when the use case is declared.
+ */
+export type CheckedSteps<Steps, Input extends IBlueprintCollection, Context extends IBlueprintCollection | undefined, Dependencies, Response extends IBlueprintCollection | undefined = undefined> = [Steps] extends [readonly [unknown, ...unknown[]]] ? CheckSteps<Steps, Dependencies, StepsInitialScope<Input, Context, Dependencies>, Response> : Steps;
+export {};

package/dist/core/use-case/steps/types/steps.interface.d.ts

@@ -1,4 +1,5 @@
-import type { AnyRecordClass } from "../../../blueprint/types/blueprint.interface.js";
+import type { FieldsDescription } from "../../../application/types/application.interface.js";
+import type { AnyBlueprint, AnyRecordClass } from "../../../blueprint/types/blueprint.interface.js";
 import type { AnyRepository } from "../../../repository/types/repository.interface.js";
 import type { AnyExceptionClass, AnyUseCaseClass, UseCaseCollection } from "../../use-case.js";
 /** A reference to a value: `$input.email`, `$context.userId`, `$env.mail`, `$saved.tags.0`. */
@@ -103,6 +104,11 @@ export type UseCaseStep<Dependencies extends UseCaseCollection = UseCaseCollecti
     readonly run: string;
     readonly fn: (...args: any[]) => unknown;
     readonly args?: StepArgs;
+    /**
+     * Checks the `args` at execution: each against the key of the blueprint
+     * at its position; `fn` gets the values as the keys handled them.
+     */
+    readonly params?: AnyBlueprint;
     readonly as?: string;
 } | {
     readonly return: StepValue;
@@ -163,6 +169,7 @@ export type UseCaseStepDescription = {
         readonly kind: "opaque";
     };
     readonly args?: StepArgs;
+    readonly params?: FieldsDescription;
     readonly as?: string;
 } | {
     readonly return: StepValue;

package/dist/core/use-case/steps/validate.js

@@ -0,0 +1,368 @@
+import { isBlueprint } from "../../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../../blueprint/list.js";
+import { isRecordClass, recordFieldOf } from "../../blueprint/record-field.js";
+import {
+  blueprintOfVariant,
+  isBlueprintVariant
+} from "../../blueprint/variant.js";
+import { isEnvironment } from "../../environment/environment.js";
+import { isDeclaredException } from "../../exception/exception.js";
+import { isRepository } from "../../repository/repository.js";
+import { Kind } from "../../symbols/kind.js";
+import { InvalidUseCaseStep } from "../exceptions.js";
+import {
+  isPlain,
+  isStepName,
+  parseReference,
+  RESERVED_NAMES,
+  walkValue
+} from "./references.js";
+const SHAPES = {
+  find: { required: ["find"], optional: ["args", "as"] },
+  ensure: {
+    required: ["ensure", "value", "error"],
+    optional: ["other", "details"]
+  },
+  build: { required: ["build", "values", "as"], optional: [] },
+  change: {
+    required: ["change", "key", "value"],
+    optional: ["ifPresent", "as"]
+  },
+  invoke: { required: ["invoke", "method"], optional: ["args", "as"] },
+  create: { required: ["create", "value"], optional: ["as"] },
+  update: { required: ["update", "value"], optional: ["as"] },
+  delete: { required: ["delete", "value"], optional: ["as"] },
+  restore: { required: ["restore", "value"], optional: ["as"] },
+  call: { required: ["call", "input"], optional: ["as"] },
+  run: { required: ["run", "fn"], optional: ["args", "params", "as"] },
+  return: { required: ["return"], optional: [] }
+};
+const KINDS = Object.keys(SHAPES);
+const ENSURE_KINDS = new Set([
+  "exists",
+  "absent",
+  "equals",
+  "notEquals",
+  "true",
+  "false"
+]);
+const READ_ACTION = /^(?:findBy.+|findManyBy.+|findMany|exists|findPage|findCursor|count)$/;
+const WRITE_ACTIONS = new Set([
+  "create",
+  "update",
+  "delete",
+  "restore",
+  "increment"
+]);
+const INDEX = /^(?:0|[1-9][0-9]*)$/;
+const LENGTH = Symbol("length");
+const PRIMITIVE_SCHEMA_TYPES = new Set([
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "null"
+]);
+function isPrimitiveProperty(field) {
+  const schema = field?.type?.schema;
+  if (typeof field !== "function" || schema === undefined)
+    return false;
+  try {
+    const type = JSON.parse(schema.toString()).type;
+    return typeof type === "string" && PRIMITIVE_SCHEMA_TYPES.has(type);
+  } catch {
+    return false;
+  }
+}
+function missingSegment(field, path) {
+  let current = field;
+  for (const segment of path) {
+    if (current === LENGTH)
+      return segment;
+    if (isBlueprint(current)) {
+      if (!Object.hasOwn(current.properties, segment))
+        return segment;
+      current = current.properties[segment];
+      continue;
+    }
+    if (isBlueprintList(current)) {
+      if (segment === "length") {
+        current = LENGTH;
+        continue;
+      }
+      if (!INDEX.test(segment))
+        return segment;
+      current = current.item;
+      continue;
+    }
+    if (isBlueprintVariant(current)) {
+      if (segment === current.key)
+        return;
+      const variants = current.variants;
+      const holder = Object.values(variants).map(blueprintOfVariant).find((variant) => Object.hasOwn(variant.properties, segment));
+      if (!holder)
+        return segment;
+      current = holder.properties[segment];
+      continue;
+    }
+    const record = recordFieldOf(current)?.record;
+    if (record) {
+      const { properties } = record.blueprint;
+      if (Object.hasOwn(properties, segment)) {
+        current = properties[segment];
+        continue;
+      }
+      return segment in record.prototype ? undefined : segment;
+    }
+    return isPrimitiveProperty(current) ? segment : undefined;
+  }
+  return;
+}
+export function validateSteps(declaration, steps) {
+  const { name } = declaration;
+  const fail = (index, code, reason) => {
+    throw new InvalidUseCaseStep({
+      source: name,
+      details: { index, reason, code }
+    });
+  };
+  if (!Array.isArray(steps) || steps.length === 0) {
+    fail(0, "missing_return", "Expected steps to be a list ending in return.");
+  }
+  const list = steps;
+  const bound = new Map;
+  const runs = new Set;
+  let returned = false;
+  const useCaseDependency = (key) => typeof key === "string" && Object.hasOwn(declaration.dependencies, key) ? declaration.dependencies[key] : undefined;
+  const checkReference = (index, text) => {
+    const reference = parseReference(text);
+    if (!reference) {
+      fail(index, "invalid_reference", `"${text}" is not a valid reference.`);
+      return;
+    }
+    const { root, path } = reference;
+    const firstKey = path[0];
+    if (root === "input" || root === "context") {
+      const blueprint = root === "input" ? declaration.blueprint : declaration.context;
+      if (blueprint === undefined) {
+        fail(index, "invalid_reference", `"${text}" uses $context, but the use case declares no context.`);
+        return;
+      }
+      const missing = missingSegment(blueprint, path);
+      if (missing !== undefined) {
+        fail(index, "unknown_key", `"${text}" names "${missing}", which the ${root} does not declare.`);
+      }
+      return;
+    }
+    if (root === "env") {
+      if (firstKey === undefined || !isEnvironment(useCaseDependency(firstKey))) {
+        fail(index, "unknown_dependency", `"${text}" must name an environment dependency.`);
+      }
+      return;
+    }
+    if (RESERVED_NAMES.includes(root)) {
+      fail(index, "invalid_reference", `"${root}" is reserved.`);
+      return;
+    }
+    if (!bound.has(root)) {
+      fail(index, "unbound_reference", `"${text}" uses "${root}", which no earlier step binds.`);
+    }
+  };
+  const checkValue = (index, value, field) => {
+    walkValue(value, (_reference, text) => checkReference(index, text), (issue, text) => fail(index, issue, issue === "invalid_reference" ? `"${text}" is not a valid reference.` : `${field} must hold only JSON values and references.`));
+  };
+  const checkArgs = (index, args) => {
+    if (args === undefined)
+      return;
+    if (typeof args === "string" && args.startsWith("$")) {
+      checkReference(index, args);
+      return;
+    }
+    if (!Array.isArray(args)) {
+      fail(index, "invalid_step", "args must be a list of values or a reference to one.");
+    }
+    checkValue(index, args, "args");
+  };
+  const checkTarget = (index, target, kind) => {
+    if (typeof target !== "string" || !target.startsWith("$")) {
+      fail(index, "invalid_reference", `${kind} must be a reference.`);
+      return;
+    }
+    checkReference(index, target);
+  };
+  const repositoryOf = (index, key, action) => {
+    const dependency = useCaseDependency(key);
+    if (!isRepository(dependency)) {
+      return fail(index, "unknown_dependency", `"${String(key)}" is not a repository dependency.`);
+    }
+    const actions = dependency.actions;
+    if (!actions.includes(action)) {
+      fail(index, "unknown_action", `The repository "${String(key)}" has no "${action}" action.`);
+    }
+    return { actions };
+  };
+  for (const [index, step] of list.entries()) {
+    if (!isPlain(step) || Array.isArray(step)) {
+      fail(index, "unknown_step", "A step must be an object.");
+    }
+    const record = step;
+    const kinds = KINDS.filter((kind) => Object.hasOwn(record, kind));
+    if (kinds.length !== 1) {
+      fail(index, "unknown_step", kinds.length === 0 ? `Unknown step; expected one of ${KINDS.join(", ")}.` : `A step has one kind, found ${kinds.join(" and ")}.`);
+    }
+    const kind = kinds[0];
+    const shape = SHAPES[kind];
+    for (const key of shape.required) {
+      if (!Object.hasOwn(record, key) || record[key] === undefined) {
+        fail(index, "invalid_step", `A ${kind} step needs "${key}".`);
+      }
+    }
+    for (const key of Object.keys(record)) {
+      if (!shape.required.includes(key) && !shape.optional.includes(key)) {
+        fail(index, "invalid_step", `A ${kind} step has no "${key}".`);
+      }
+    }
+    const as = record.as;
+    if (as !== undefined) {
+      if (!isStepName(as) || RESERVED_NAMES.includes(as) || bound.has(as)) {
+        fail(index, "invalid_step_name", `"${String(as)}" must be an identifier, not reserved, bound once.`);
+      }
+    }
+    let knownRecord;
+    switch (kind) {
+      case "find": {
+        const target = record.find;
+        const parts = typeof target === "string" ? target.split(".") : [];
+        const [repository, action] = parts;
+        if (parts.length !== 2 || !repository || !action) {
+          fail(index, "invalid_step", 'find must be "<repository>.<action>".');
+        }
+        if (WRITE_ACTIONS.has(action)) {
+          fail(index, "write_in_find", `find cannot call "${action}".`);
+        }
+        if (action === "forEachPage") {
+          fail(index, "unknown_action", '"forEachPage" runs a function on each page and cannot be a step; call it from a use case written in TypeScript.');
+        }
+        if (!READ_ACTION.test(action)) {
+          fail(index, "unknown_action", `"${action}" is not a read action.`);
+        }
+        repositoryOf(index, repository, action);
+        checkArgs(index, record.args);
+        break;
+      }
+      case "ensure": {
+        if (!ENSURE_KINDS.has(record.ensure)) {
+          fail(index, "invalid_step", `ensure must be one of ${[...ENSURE_KINDS].join(", ")}.`);
+        }
+        const compares = record.ensure === "equals" || record.ensure === "notEquals";
+        if (compares && record.other === undefined) {
+          fail(index, "invalid_step", `ensure "${record.ensure}" needs other.`);
+        }
+        if (!compares && record.other !== undefined) {
+          fail(index, "invalid_step", `ensure "${String(record.ensure)}" has no other.`);
+        }
+        if (!isDeclaredException(record.error) || !declaration.errors.includes(record.error)) {
+          fail(index, "undeclared_error", "ensure.error must be a class made by exceptionOf, listed in errors.");
+        }
+        checkValue(index, record.value, "value");
+        if (record.other !== undefined)
+          checkValue(index, record.other, "other");
+        if (record.details !== undefined) {
+          checkValue(index, record.details, "details");
+        }
+        break;
+      }
+      case "build": {
+        if (!isRecordClass(record.build)) {
+          fail(index, "invalid_class", "build must be a record or entity class.");
+        }
+        const values = record.values;
+        if (!(typeof values === "string" && values.startsWith("$")) && !isPlain(values)) {
+          fail(index, "invalid_step", "build.values must be a mapping or a reference.");
+        }
+        checkValue(index, values, "values");
+        knownRecord = record.build;
+        break;
+      }
+      case "change": {
+        checkTarget(index, record.change, "change");
+        if (typeof record.key !== "string" || record.key === "") {
+          fail(index, "invalid_step", "change.key must be a string.");
+        }
+        if (record.ifPresent !== undefined && typeof record.ifPresent !== "boolean") {
+          fail(index, "invalid_step", "change.ifPresent must be a boolean.");
+        }
+        const reference = parseReference(record.change);
+        const known = reference && reference.path.length === 0 ? bound.get(reference.root)?.record : undefined;
+        if (known) {
+          const keys = known.options?.change ?? [];
+          if (!keys.includes(record.key)) {
+            fail(index, "invalid_change_key", `"${String(record.key)}" is not a change key of ${known.name}.`);
+          }
+        }
+        checkValue(index, record.value, "value");
+        knownRecord = known;
+        break;
+      }
+      case "invoke": {
+        checkTarget(index, record.invoke, "invoke");
+        if (typeof record.method !== "string" || record.method === "") {
+          fail(index, "invalid_step", "invoke.method must be a string.");
+        }
+        checkArgs(index, record.args);
+        break;
+      }
+      case "create":
+      case "update":
+      case "delete":
+      case "restore": {
+        repositoryOf(index, record[kind], kind);
+        checkValue(index, record.value, "value");
+        break;
+      }
+      case "call": {
+        const dependency = useCaseDependency(record.call);
+        if (typeof dependency !== "function" || dependency[Kind] !== "use-case") {
+          fail(index, "unknown_dependency", `"${String(record.call)}" is not a use case dependency.`);
+        }
+        checkValue(index, record.input, "input");
+        break;
+      }
+      case "run": {
+        const runName = record.run;
+        if (!isStepName(runName) || runs.has(runName)) {
+          fail(index, "invalid_step_name", `run "${String(runName)}" must be an identifier, unique in the use case.`);
+        }
+        if (typeof record.fn !== "function") {
+          fail(index, "invalid_step", "run.fn must be a function.");
+        }
+        runs.add(runName);
+        checkArgs(index, record.args);
+        if (record.params !== undefined) {
+          if (!isBlueprint(record.params)) {
+            fail(index, "invalid_step", "run.params must be a blueprint.");
+          }
+          const declared = Object.keys(record.params.properties).length;
+          const given = record.args === undefined ? 0 : Array.isArray(record.args) ? record.args.length : undefined;
+          if (given !== undefined && given !== declared) {
+            fail(index, "invalid_args", `run.params declares ${declared} parameter(s), args gives ${given}.`);
+          }
+        }
+        break;
+      }
+      case "return": {
+        checkValue(index, record.return, "return");
+        returned = true;
+        if (index !== list.length - 1) {
+          fail(index, "misplaced_return", "return must be the last step, exactly once.");
+        }
+        break;
+      }
+    }
+    if (typeof as === "string")
+      bound.set(as, { record: knownRecord });
+  }
+  if (!returned) {
+    fail(list.length, "missing_return", "The steps must end with return.");
+  }
+}