@affordance/core 0.1.0

package/dist/model/retry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-step retry policy.
+ *
+ * Handlers are short-lived, at-least-once and idempotent, so a
+ * failed attempt is retried in place: same Execution, same `ctx.executionId`
+ * (the idempotency key), same claim. Retries are bounded — "exhausted retries
+ * journal a *failed* execution and release the case" — so a permanently
+ * failing handler can never hold a case hostage.
+ *
+ * Only *indeterminate* failures are retried: a handler that threw. A
+ * deterministic failure (the returned Case State does not satisfy the case
+ * type's schema) fails the Execution immediately — retrying is guaranteed to
+ * produce the same defect.
+ */
+/** A normalized retry policy, as held on a {@link StepDefinition}. */
+export interface RetryPolicy {
+    /** Total attempts, including the first — 1 disables retry. */
+    readonly maxAttempts: number;
+    /** Delay before the attempt *after* the given (1-based) failed attempt, in milliseconds. */
+    readonly delayMs: (attempt: number) => number;
+}
+/** Retry configuration as authored on a step; every field optional. */
+export interface RetryOptions {
+    /** Total attempts, including the first. Integer ≥ 1; defaults to 3. */
+    readonly maxAttempts?: number;
+    /**
+     * Delay between attempts: a fixed number of milliseconds, or a function of
+     * the (1-based) attempt that just failed. Defaults to exponential backoff
+     * (100ms, 200ms, 400ms …) capped at 5s.
+     */
+    readonly delayMs?: number | ((attempt: number) => number);
+}
+/** The policy a step gets when it declares none: three attempts, exponential backoff. */
+export declare const DEFAULT_RETRY: RetryPolicy;
+/**
+ * Normalize authored retry options into a {@link RetryPolicy}, validating
+ * loudly (definition-time validation: a malformed policy should fail the
+ * deploy, not an execution).
+ */
+export declare const normalizeRetry: (stepName: string, options: RetryOptions | undefined) => RetryPolicy;

package/dist/model/retry.js

@@ -0,0 +1,51 @@
+/**
+ * Per-step retry policy.
+ *
+ * Handlers are short-lived, at-least-once and idempotent, so a
+ * failed attempt is retried in place: same Execution, same `ctx.executionId`
+ * (the idempotency key), same claim. Retries are bounded — "exhausted retries
+ * journal a *failed* execution and release the case" — so a permanently
+ * failing handler can never hold a case hostage.
+ *
+ * Only *indeterminate* failures are retried: a handler that threw. A
+ * deterministic failure (the returned Case State does not satisfy the case
+ * type's schema) fails the Execution immediately — retrying is guaranteed to
+ * produce the same defect.
+ */
+/** Exponential backoff from 100ms, capped at 5s. */
+const defaultDelayMs = (attempt) => Math.min(5_000, 100 * 2 ** (attempt - 1));
+/** The policy a step gets when it declares none: three attempts, exponential backoff. */
+export const DEFAULT_RETRY = {
+    maxAttempts: 3,
+    delayMs: defaultDelayMs,
+};
+/**
+ * Normalize authored retry options into a {@link RetryPolicy}, validating
+ * loudly (definition-time validation: a malformed policy should fail the
+ * deploy, not an execution).
+ */
+export const normalizeRetry = (stepName, options) => {
+    if (options === undefined)
+        return DEFAULT_RETRY;
+    if (typeof options !== 'object' ||
+        options === null ||
+        Array.isArray(options)) {
+        throw new TypeError(`step '${stepName}': retry must be { maxAttempts?, delayMs? }`);
+    }
+    const { maxAttempts = DEFAULT_RETRY.maxAttempts, delayMs = defaultDelayMs } = options;
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new TypeError(`step '${stepName}': retry.maxAttempts must be an integer >= 1`);
+    }
+    if (typeof delayMs === 'number') {
+        if (!Number.isFinite(delayMs) || delayMs < 0) {
+            throw new TypeError(`step '${stepName}': retry.delayMs must be a non-negative number or a function`);
+        }
+        const fixed = delayMs;
+        return { maxAttempts, delayMs: () => fixed };
+    }
+    if (typeof delayMs !== 'function') {
+        throw new TypeError(`step '${stepName}': retry.delayMs must be a non-negative number or a function`);
+    }
+    return { maxAttempts, delayMs };
+};
+//# sourceMappingURL=retry.js.map

package/dist/model/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/model/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsBH,oDAAoD;AACpD,MAAM,cAAc,GAAG,CAAC,OAAe,EAAU,EAAE,CACjD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAA;AAE3C,yFAAyF;AACzF,MAAM,CAAC,MAAM,aAAa,GAAgB;IACxC,WAAW,EAAE,CAAC;IACd,OAAO,EAAE,cAAc;CACxB,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,QAAgB,EAChB,OAAiC,EACpB,EAAE;IACf,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,aAAa,CAAA;IAC/C,IACE,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EACtB,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,SAAS,QAAQ,6CAA6C,CAC/D,CAAA;IACH,CAAC;IACD,MAAM,EAAE,WAAW,GAAG,aAAa,CAAC,WAAW,EAAE,OAAO,GAAG,cAAc,EAAE,GACzE,OAAO,CAAA;IACT,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,SAAS,CACjB,SAAS,QAAQ,8CAA8C,CAChE,CAAA;IACH,CAAC;IACD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,SAAS,CACjB,SAAS,QAAQ,8DAA8D,CAChF,CAAA;QACH,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAA;QACrB,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,CAAA;IAC9C,CAAC;IACD,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,SAAS,CACjB,SAAS,QAAQ,8DAA8D,CAChF,CAAA;IACH,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAA;AACjC,CAAC,CAAA","sourcesContent":["/**\n * Per-step retry policy.\n *\n * Handlers are short-lived, at-least-once and idempotent, so a\n * failed attempt is retried in place: same Execution, same `ctx.executionId`\n * (the idempotency key), same claim. Retries are bounded — \"exhausted retries\n * journal a *failed* execution and release the case\" — so a permanently\n * failing handler can never hold a case hostage.\n *\n * Only *indeterminate* failures are retried: a handler that threw. A\n * deterministic failure (the returned Case State does not satisfy the case\n * type's schema) fails the Execution immediately — retrying is guaranteed to\n * produce the same defect.\n */\n\n/** A normalized retry policy, as held on a {@link StepDefinition}. */\nexport interface RetryPolicy {\n  /** Total attempts, including the first — 1 disables retry. */\n  readonly maxAttempts: number\n  /** Delay before the attempt *after* the given (1-based) failed attempt, in milliseconds. */\n  readonly delayMs: (attempt: number) => number\n}\n\n/** Retry configuration as authored on a step; every field optional. */\nexport interface RetryOptions {\n  /** Total attempts, including the first. Integer ≥ 1; defaults to 3. */\n  readonly maxAttempts?: number\n  /**\n   * Delay between attempts: a fixed number of milliseconds, or a function of\n   * the (1-based) attempt that just failed. Defaults to exponential backoff\n   * (100ms, 200ms, 400ms …) capped at 5s.\n   */\n  readonly delayMs?: number | ((attempt: number) => number)\n}\n\n/** Exponential backoff from 100ms, capped at 5s. */\nconst defaultDelayMs = (attempt: number): number =>\n  Math.min(5_000, 100 * 2 ** (attempt - 1))\n\n/** The policy a step gets when it declares none: three attempts, exponential backoff. */\nexport const DEFAULT_RETRY: RetryPolicy = {\n  maxAttempts: 3,\n  delayMs: defaultDelayMs,\n}\n\n/**\n * Normalize authored retry options into a {@link RetryPolicy}, validating\n * loudly (definition-time validation: a malformed policy should fail the\n * deploy, not an execution).\n */\nexport const normalizeRetry = (\n  stepName: string,\n  options: RetryOptions | undefined,\n): RetryPolicy => {\n  if (options === undefined) return DEFAULT_RETRY\n  if (\n    typeof options !== 'object' ||\n    options === null ||\n    Array.isArray(options)\n  ) {\n    throw new TypeError(\n      `step '${stepName}': retry must be { maxAttempts?, delayMs? }`,\n    )\n  }\n  const { maxAttempts = DEFAULT_RETRY.maxAttempts, delayMs = defaultDelayMs } =\n    options\n  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {\n    throw new TypeError(\n      `step '${stepName}': retry.maxAttempts must be an integer >= 1`,\n    )\n  }\n  if (typeof delayMs === 'number') {\n    if (!Number.isFinite(delayMs) || delayMs < 0) {\n      throw new TypeError(\n        `step '${stepName}': retry.delayMs must be a non-negative number or a function`,\n      )\n    }\n    const fixed = delayMs\n    return { maxAttempts, delayMs: () => fixed }\n  }\n  if (typeof delayMs !== 'function') {\n    throw new TypeError(\n      `step '${stepName}': retry.delayMs must be a non-negative number or a function`,\n    )\n  }\n  return { maxAttempts, delayMs }\n}\n"]}

package/dist/model/scope.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Scoped steps.
+ *
+ * A step may declare a **scope** over a state collection: each element the
+ * scope selects yields one independent affordance, and the affordance's
+ * identity is (step name × scope key) — `escalate-verification(buyer_007)`. Journal
+ * entries, correlation keys, and execution requests all address a scoped
+ * step by that pair, so the key must be **stable**: derived from the
+ * element's own identity (an id the app owns), never from its position in
+ * the collection.
+ */
+import type { ConditionContext, ConditionMapEntry, ConditionOutcome } from '../guards/index.js';
+/**
+ * A step's scope declaration: which elements of case state the step ranges
+ * over, and how each element is identified.
+ *
+ * - `select` — pure selector over case state returning the matching elements
+ *   (e.g. `s => s.buyers.filter(b => b.verification?.status === 'review')`).
+ *   Subject to the same discipline as conditions: synchronous,
+ *   side-effect-free, total over historical state.
+ * - `key` — derives the element's **scope key**, a non-empty string that is
+ *   stable for the life of the element and unique within one selection
+ *   (typically `i => i.id`). The framework deliberately does not require an
+ *   `id` field on elements: state schemas are app-owned, so identity
+ *   derivation is declared, not assumed. Duplicate or invalid keys are an
+ *   identity-corruption bug and fail affordance computation loudly
+ *   ({@link ScopeKeyError}).
+ */
+export interface ScopeDeclaration<TState, TElement> {
+    readonly select: (state: TState) => readonly TElement[];
+    readonly key: (element: TElement) => string;
+}
+/**
+ * The context a scoped step's conditions receive: the base condition context
+ * with the bound scope element present and typed. Authors read the element
+ * as `ctx.scope` with no need to narrow away `undefined` — the engine always
+ * binds it when evaluating a scoped step.
+ */
+export type ScopedConditionContext<TElement, TActor = unknown> = ConditionContext<TActor, TElement> & {
+    readonly scope: TElement;
+};
+/**
+ * A condition of a scoped step: same contract as {@link Condition} — pure,
+ * synchronous, total, clock-free — receiving the whole case state first and
+ * the bound scope element via `ctx.scope`, so cross-cutting facts stay
+ * expressible (`(s, ctx) => (ctx.scope.committed ?? 0) <
+ * (s.fundingCall?.amount ?? 0)`).
+ */
+export type ScopedCondition<TState, TElement, TActor = unknown> = (state: TState, ctx: ScopedConditionContext<TElement, TActor>) => ConditionOutcome;
+/**
+ * What may sit under a name in a scoped step's `requires`/`permits`: a
+ * scoped condition.
+ *
+ * `anyOf` groups are not part of the scoped guard surface (the unscoped
+ * algebra keeps them); adding a scoped-typed `anyOf` later is an additive
+ * change.
+ */
+export type ScopedConditionMapEntry<TState, TElement, TActor = unknown> = ScopedCondition<TState, TElement, TActor>;
+/** A flat AND-map of named scoped conditions — the scoped counterpart of `ConditionMap`. */
+export type ScopedConditionMap<TState, TElement, TActor = unknown> = Readonly<Record<string, ScopedConditionMapEntry<TState, TElement, TActor>>>;
+/**
+ * Erase a scoped condition map to the guards module's entry shape so the
+ * engine can hand a scoped step's guard to `evaluateGuard` unchanged. Sound
+ * because evaluation of a scoped guard always binds `scope` (which the
+ * scoped condition context requires).
+ */
+export declare const eraseScopedConditionMap: <TState, TElement, TActor>(map: ScopedConditionMap<TState, TElement, TActor> | undefined) => Readonly<Record<string, ConditionMapEntry<TState, TActor>>> | undefined;

package/dist/model/scope.js

@@ -0,0 +1,19 @@
+/**
+ * Scoped steps.
+ *
+ * A step may declare a **scope** over a state collection: each element the
+ * scope selects yields one independent affordance, and the affordance's
+ * identity is (step name × scope key) — `escalate-verification(buyer_007)`. Journal
+ * entries, correlation keys, and execution requests all address a scoped
+ * step by that pair, so the key must be **stable**: derived from the
+ * element's own identity (an id the app owns), never from its position in
+ * the collection.
+ */
+/**
+ * Erase a scoped condition map to the guards module's entry shape so the
+ * engine can hand a scoped step's guard to `evaluateGuard` unchanged. Sound
+ * because evaluation of a scoped guard always binds `scope` (which the
+ * scoped condition context requires).
+ */
+export const eraseScopedConditionMap = (map) => map;
+//# sourceMappingURL=scope.js.map

package/dist/model/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/model/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,GAA6D,EACY,EAAE,CAC3E,GAEa,CAAA","sourcesContent":["/**\n * Scoped steps.\n *\n * A step may declare a **scope** over a state collection: each element the\n * scope selects yields one independent affordance, and the affordance's\n * identity is (step name × scope key) — `escalate-verification(buyer_007)`. Journal\n * entries, correlation keys, and execution requests all address a scoped\n * step by that pair, so the key must be **stable**: derived from the\n * element's own identity (an id the app owns), never from its position in\n * the collection.\n */\n\nimport type {\n  ConditionContext,\n  ConditionMapEntry,\n  ConditionOutcome,\n} from '../guards/index.js'\n\n/**\n * A step's scope declaration: which elements of case state the step ranges\n * over, and how each element is identified.\n *\n * - `select` — pure selector over case state returning the matching elements\n *   (e.g. `s => s.buyers.filter(b => b.verification?.status === 'review')`).\n *   Subject to the same discipline as conditions: synchronous,\n *   side-effect-free, total over historical state.\n * - `key` — derives the element's **scope key**, a non-empty string that is\n *   stable for the life of the element and unique within one selection\n *   (typically `i => i.id`). The framework deliberately does not require an\n *   `id` field on elements: state schemas are app-owned, so identity\n *   derivation is declared, not assumed. Duplicate or invalid keys are an\n *   identity-corruption bug and fail affordance computation loudly\n *   ({@link ScopeKeyError}).\n */\nexport interface ScopeDeclaration<TState, TElement> {\n  readonly select: (state: TState) => readonly TElement[]\n  readonly key: (element: TElement) => string\n}\n\n/**\n * The context a scoped step's conditions receive: the base condition context\n * with the bound scope element present and typed. Authors read the element\n * as `ctx.scope` with no need to narrow away `undefined` — the engine always\n * binds it when evaluating a scoped step.\n */\nexport type ScopedConditionContext<\n  TElement,\n  TActor = unknown,\n> = ConditionContext<TActor, TElement> & {\n  readonly scope: TElement\n}\n\n/**\n * A condition of a scoped step: same contract as {@link Condition} — pure,\n * synchronous, total, clock-free — receiving the whole case state first and\n * the bound scope element via `ctx.scope`, so cross-cutting facts stay\n * expressible (`(s, ctx) => (ctx.scope.committed ?? 0) <\n * (s.fundingCall?.amount ?? 0)`).\n */\nexport type ScopedCondition<TState, TElement, TActor = unknown> = (\n  state: TState,\n  ctx: ScopedConditionContext<TElement, TActor>,\n) => ConditionOutcome\n\n/**\n * What may sit under a name in a scoped step's `requires`/`permits`: a\n * scoped condition.\n *\n * `anyOf` groups are not part of the scoped guard surface (the unscoped\n * algebra keeps them); adding a scoped-typed `anyOf` later is an additive\n * change.\n */\nexport type ScopedConditionMapEntry<\n  TState,\n  TElement,\n  TActor = unknown,\n> = ScopedCondition<TState, TElement, TActor>\n\n/** A flat AND-map of named scoped conditions — the scoped counterpart of `ConditionMap`. */\nexport type ScopedConditionMap<TState, TElement, TActor = unknown> = Readonly<\n  Record<string, ScopedConditionMapEntry<TState, TElement, TActor>>\n>\n\n/**\n * Erase a scoped condition map to the guards module's entry shape so the\n * engine can hand a scoped step's guard to `evaluateGuard` unchanged. Sound\n * because evaluation of a scoped guard always binds `scope` (which the\n * scoped condition context requires).\n */\nexport const eraseScopedConditionMap = <TState, TElement, TActor>(\n  map: ScopedConditionMap<TState, TElement, TActor> | undefined,\n): Readonly<Record<string, ConditionMapEntry<TState, TActor>>> | undefined =>\n  map as unknown as\n    | Readonly<Record<string, ConditionMapEntry<TState, TActor>>>\n    | undefined\n"]}

package/dist/model/step.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Step definitions.
+ *
+ * A **step** is an independently-defined unit of possible work on a case: a
+ * guard plus a handler (CONTEXT.md). Steps never declare ordering —
+ * sequencing is data dependencies between guards. `step()` validates the
+ * definition loudly at construction time: a malformed step should fail the
+ * deploy, not an evaluation.
+ */
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { AffordanceError } from '../errors.js';
+import type { ConditionMap, Guard } from '../guards/index.js';
+import type { ErasedStepHandler, ScopedStepHandler, StepHandler } from './handler.js';
+import type { RetryOptions, RetryPolicy } from './retry.js';
+import type { ScopeDeclaration, ScopedConditionMap } from './scope.js';
+/** Options for an unscoped step. */
+export interface StepOptions<TState, TActor = unknown, TInput = undefined> {
+    /** The step's name — unique within its case type; half of a scoped affordance's identity. */
+    readonly name: string;
+    /**
+     * A short human label for the step ("Issue the funding call"). Definition
+     * metadata, not identity: journal entries and refusals name the step by
+     * `name`; adapters serialize the title so a client renders steps without
+     * an out-of-band label table.
+     */
+    readonly title?: string;
+    /**
+     * A sentence on what the step does and when to take it — what makes the
+     * affordance contract a usable tool list for a caller (an agent included)
+     * that has never seen this case type.
+     */
+    readonly description?: string;
+    /** Case conditions: when one fails the step is not possible on this case, for anyone. */
+    readonly requires?: ConditionMap<TState, TActor>;
+    /** Actor conditions: when one fails the step is possible but not permitted for this actor. */
+    readonly permits?: ConditionMap<TState, TActor>;
+    /**
+     * Optional input schema (any Standard Schema — zod v4 qualifies). Validated
+     * by `validateStepInput` before the handler runs.
+     */
+    readonly input?: StandardSchemaV1<unknown, TInput>;
+    /**
+     * How many times a failed attempt is retried, and how long between
+     * attempts. Defaults to three attempts with exponential backoff; set
+     * `{ maxAttempts: 1 }` to disable retry for this step.
+     */
+    readonly retry?: RetryOptions;
+    /** The step's effect function — the only thing that mutates Case State. */
+    readonly handler: StepHandler<TState, TActor, TInput>;
+}
+/** Options for a scoped step: an unscoped step plus the scope declaration. */
+export interface ScopedStepOptions<TState, TElement, TActor = unknown, TInput = undefined> {
+    readonly name: string;
+    readonly title?: string;
+    readonly description?: string;
+    /** The collection the step ranges over and how each element is identified. */
+    readonly scope: ScopeDeclaration<TState, TElement>;
+    readonly requires?: ScopedConditionMap<TState, TElement, TActor>;
+    readonly permits?: ScopedConditionMap<TState, TElement, TActor>;
+    readonly input?: StandardSchemaV1<unknown, TInput>;
+    readonly retry?: RetryOptions;
+    readonly handler: ScopedStepHandler<TState, TElement, TActor, TInput>;
+}
+/**
+ * A step definition as held by a case type and consumed by the engine — the
+ * authoring generics (scope element, input) erased to the case-state level.
+ * The options types above carry the precise authoring shapes; this is the
+ * machine-facing normal form.
+ */
+export interface StepDefinition<TState, TActor = unknown> {
+    readonly name: string;
+    /** The declared human label, or `null` — clients fall back to `name`. */
+    readonly title: string | null;
+    /** The declared what-and-when sentence, or `null`. */
+    readonly description: string | null;
+    /**
+     * The step's guard in the guards module's shape, ready for `evaluateGuard`.
+     * For a scoped step the engine evaluates it once per selected element with
+     * the element bound as `scope`.
+     */
+    readonly guard: Guard<TState, TActor>;
+    /** The scope declaration (element type erased), or `null` for an unscoped step. */
+    readonly scope: {
+        readonly select: (state: TState) => readonly unknown[];
+        readonly key: (element: unknown) => string;
+    } | null;
+    /** The declared input schema, or `null` when the step takes no input. */
+    readonly input: StandardSchemaV1 | null;
+    /** The normalized retry policy the execution lifecycle applies to this step. */
+    readonly retry: RetryPolicy;
+    /** The step's handler — invoked only by the execution lifecycle. */
+    readonly handler: ErasedStepHandler<TState, TActor>;
+}
+/**
+ * A step's declared human metadata, as `Engine.stepMetadataFor` answers it —
+ * the serializable slice of a {@link StepDefinition} an adapter puts on the
+ * wire.
+ */
+export interface StepMetadata {
+    readonly title: string | null;
+    readonly description: string | null;
+}
+/** Whether a value is a Standard-Schema instance — the one spelling of the check. */
+export declare const isStandardSchema: (value: unknown) => value is StandardSchemaV1;
+/**
+ * Whether a value is plausibly a {@link StepDefinition} — the structural
+ * check `caseType()` applies to every step it is given.
+ */
+export declare const looksLikeStepDefinition: (value: unknown) => value is StepDefinition<unknown, unknown>;
+/**
+ * Define a step. Two shapes, discriminated by the presence of `scope`:
+ *
+ * ```ts
+ * // Standalone form (internal — apps author through {@link stepsOf}, which
+ * // binds the generics once and takes the same options annotation-free):
+ * // type parameters are inferred from annotations in the options — annotate
+ * // the state parameter of a condition (and the actor on a permits ctx).
+ * step({
+ *   name: 'issue-funding-call',
+ *   requires: { escrowReady: (s: Purchase) => s.escrow?.status === 'open' },
+ *   permits: { isOrganizer: (_s: Purchase, ctx: ConditionContext<Ops>) => ctx.actor.roles.includes('organizer') },
+ *   handler: async (s, ctx) => s,
+ * })
+ *
+ * // Scoped, standalone form: annotating scope.select anchors both the state
+ * // and element types; conditions then read the bound element as ctx.scope,
+ * // fully typed (through stepsOf, even the select annotation goes away):
+ * step({
+ *   name: 'escalate-verification',
+ *   scope: { select: (s: Purchase) => s.buyers.filter(b => b.verification?.status === 'review'), key: b => b.id },
+ *   requires: { flagged: (s: Purchase, ctx) => (ctx.scope as Buyer).verification?.flaggedAt != null },
+ *   handler: async (s, ctx) => s,
+ * })
+ * ```
+ *
+ * Validates loudly at construction time — malformed guard entries, a
+ * malformed scope declaration, a non-function handler, or a non-schema
+ * `input` all throw `TypeError` (definition-time validation; a definition
+ * bug should fail the deploy, not an evaluation).
+ *
+ * The scoped overload is declared first: type parameters are meant to be
+ * inferred, and inference resolves each call shape against its own overload
+ * (explicit type-argument lists interact badly with overloaded
+ * context-sensitive options — annotate inside the options instead).
+ */
+export declare function step<TState, TElement, TActor = unknown, TInput = undefined>(options: ScopedStepOptions<TState, TElement, TActor, TInput>): StepDefinition<TState, TActor>;
+export declare function step<TState, TActor = unknown, TInput = undefined>(options: StepOptions<TState, TActor, TInput>): StepDefinition<TState, TActor>;
+/**
+ * The `step()` authoring surface with the case's state and actor types fixed.
+ *
+ * Same two call shapes as `step()` — scoped first, discriminated by the
+ * presence of `scope` — but `TState`/`TActor` are already substituted, so
+ * only the per-step generics (scope element, input) remain to be inferred.
+ * That is what makes annotation-free authoring work: conditions and handlers
+ * no longer participate in inferring the state type, they just receive it
+ * contextually, and a scoped step's element type anchors on `scope.select`
+ * alone (so `ctx.scope` is the element, with no `undefined` to narrow away).
+ */
+export interface BoundStep<TState, TActor = unknown> {
+    <TElement, TInput = undefined>(options: ScopedStepOptions<TState, TElement, TActor, TInput>): StepDefinition<TState, TActor>;
+    <TInput = undefined>(options: StepOptions<TState, TActor, TInput>): StepDefinition<TState, TActor>;
+}
+/**
+ * A value-level carrier for `stepsOf`'s actor type — nothing but the type.
+ * Exists because `TActor` has no value to be inferred from (a case's actor
+ * shape is app-defined and never materializes at definition time), and
+ * spelling it as a type argument would force spelling the schema's type too
+ * (TypeScript has no partial type-argument inference).
+ */
+export interface ActorMarker<TActor> {
+    readonly __actor?: TActor;
+}
+/** Name the actor type of a `stepsOf` factory: `stepsOf(PurchaseState, actor<PurchaseActor>())`. */
+export declare const actor: <TActor>() => ActorMarker<TActor>;
+/**
+ * Bind `step()` to a case's state schema — the schema-anchored authoring
+ * factory.
+ *
+ * ```ts
+ * const purchaseStep = stepsOf(PurchaseState, actor<PurchaseActor>())
+ *
+ * purchaseStep({
+ *   name: 'issue-funding-call',
+ *   requires: { escrowReady: s => s.escrow.status === 'open' },        // s: inferred from the schema
+ *   permits:  { isOrganizer: (_s, ctx) => hasRole(ctx.actor, 'organizer') },
+ *   handler: async s => s,
+ * })
+ *
+ * purchaseStep({
+ *   name: 'escalate-verification',
+ *   scope: { select: s => s.buyers.filter(b => b.verification.status === 'review'), key: b => b.id },
+ *   requires: { flagged: (_s, ctx) => ctx.scope.verification.flaggedAt !== null },  // ctx.scope: Buyer
+ *   handler: async s => s,
+ * })
+ * ```
+ *
+ * The state type is derived from the schema *value* — the same
+ * `InferOutput` derivation `caseType` performs — so the factory and the case
+ * type are anchored to one declaration and cannot drift apart: the state a
+ * condition sees is definitionally the state the engine validates against.
+ * The per-condition annotations the bare `step()` needs
+ * (`(s: Purchase) => …`) disappear, because `TState` is no longer inferred
+ * from the options.
+ *
+ * The second argument exists only to name the actor type and carries no
+ * runtime information; omit it for an untyped actor. Define one factory per
+ * case type module, next to the schema, and author every step of that case
+ * type through it.
+ *
+ * Returns `step` itself, re-typed — a step authored through the factory is
+ * bit-for-bit an ordinary step definition. `step` is deliberately not part
+ * of the package barrel: this factory is the public authoring surface, and
+ * a helper that builds steps generically should accept a
+ * {@link BoundStep} rather than reach for the unbound `step`.
+ * Throws at definition time when `state` is not a Standard Schema, like
+ * every other malformed-definition case in this module.
+ */
+export declare const stepsOf: <S extends StandardSchemaV1, TActor = unknown>(state: S, _actor?: ActorMarker<TActor>) => BoundStep<StandardSchemaV1.InferOutput<S>, TActor>;
+/** A step's declared input failed validation against its input schema. */
+export declare class StepInputValidationError extends AffordanceError {
+    readonly stepName: string;
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    constructor(stepName: string, issues: readonly StandardSchemaV1.Issue[]);
+}
+/**
+ * Validate a step's input against its declared input schema — the validation
+ * plumbing the execution lifecycle runs before invoking the handler ("validated before the
+ * handler runs"). Returns the schema *output* (defaults applied). A step
+ * without an input schema accepts only `undefined` and yields `undefined`;
+ * anything else is a caller bug and throws.
+ */
+export declare const validateStepInput: <TState, TActor>(definition: StepDefinition<TState, TActor>, input: unknown) => Promise<unknown>;

package/dist/model/step.js

@@ -0,0 +1,210 @@
+/**
+ * Step definitions.
+ *
+ * A **step** is an independently-defined unit of possible work on a case: a
+ * guard plus a handler (CONTEXT.md). Steps never declare ordering —
+ * sequencing is data dependencies between guards. `step()` validates the
+ * definition loudly at construction time: a malformed step should fail the
+ * deploy, not an evaluation.
+ */
+import { AffordanceError } from '../errors.js';
+import { guardEntries } from '../guards/index.js';
+import { normalizeRetry } from './retry.js';
+import { eraseScopedConditionMap } from './scope.js';
+/** Whether a value is a Standard-Schema instance — the one spelling of the check. */
+export const isStandardSchema = (value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value['~standard'] === 'object';
+/**
+ * Whether a value is plausibly a {@link StepDefinition} — the structural
+ * check `caseType()` applies to every step it is given.
+ */
+export const looksLikeStepDefinition = (value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value.name === 'string' &&
+    typeof value.handler === 'function' &&
+    typeof value.guard === 'object';
+/**
+ * Validate one guard section map at definition time: every entry must be a
+ * condition function or an `anyOf(...)` group
+ * (unscoped only — scoped maps admit conditions alone).
+ *
+ * The classification and the `requires.escrowReady` addressing both come from
+ * `guardEntries`, so what a definition is allowed to contain is decided
+ * against the same walk evaluation uses — a definition `step()` accepts is
+ * one `evaluateGuard` can read.
+ */
+const validateConditionMap = (stepName, section, map, allowAnyOf) => {
+    if (map === undefined)
+        return;
+    if (typeof map !== 'object' || map === null || Array.isArray(map)) {
+        throw new TypeError(`step '${stepName}': ${section} must be a plain object of named conditions`);
+    }
+    const section_ = { [section]: map };
+    for (const entry of guardEntries(section_)) {
+        if (entry.kind === 'condition')
+            continue;
+        if (entry.kind === 'anyOf' && allowAnyOf)
+            continue;
+        const allowed = allowAnyOf
+            ? 'a condition function or an anyOf(...) group'
+            : 'a condition function (anyOf is not part of the scoped guard surface)';
+        throw new TypeError(`step '${stepName}': ${entry.address} must be ${allowed}`);
+    }
+};
+const validateCommon = (options) => {
+    const { name } = options;
+    if (typeof name !== 'string' || name.trim() === '') {
+        throw new TypeError('step: name must be a non-empty string');
+    }
+    if (typeof options.handler !== 'function') {
+        throw new TypeError(`step '${name}': handler must be an async function`);
+    }
+    if (options.input !== undefined && !isStandardSchema(options.input)) {
+        throw new TypeError(`step '${name}': input must be a Standard Schema (e.g. a zod schema)`);
+    }
+    for (const field of ['title', 'description']) {
+        const value = options[field];
+        if (value !== undefined &&
+            (typeof value !== 'string' || value.trim() === '')) {
+            throw new TypeError(`step '${name}': ${field} must be a non-empty string when given`);
+        }
+    }
+    return name;
+};
+export function step(options) {
+    const name = validateCommon(options);
+    const scoped = 'scope' in options && options.scope !== undefined;
+    let scope = null;
+    let guard;
+    if (scoped) {
+        const declaration = options.scope;
+        if (typeof declaration !== 'object' ||
+            declaration === null ||
+            typeof declaration.select !== 'function' ||
+            typeof declaration.key !== 'function') {
+            throw new TypeError(`step '${name}': scope must be { select: state => elements, key: element => string }`);
+        }
+        validateConditionMap(name, 'requires', options.requires, false);
+        validateConditionMap(name, 'permits', options.permits, false);
+        scope = { select: declaration.select, key: declaration.key };
+        // Erasure, not conversion: scoped maps are runtime-identical to unscoped
+        // ones; evaluation binds the scope element the scoped types promise.
+        const scopedOptions = options;
+        guard = {
+            ...(scopedOptions.requires !== undefined && {
+                requires: eraseScopedConditionMap(scopedOptions.requires),
+            }),
+            ...(scopedOptions.permits !== undefined && {
+                permits: eraseScopedConditionMap(scopedOptions.permits),
+            }),
+        };
+    }
+    else {
+        const unscoped = options;
+        validateConditionMap(name, 'requires', unscoped.requires, true);
+        validateConditionMap(name, 'permits', unscoped.permits, true);
+        guard = {
+            ...(unscoped.requires !== undefined && { requires: unscoped.requires }),
+            ...(unscoped.permits !== undefined && { permits: unscoped.permits }),
+        };
+    }
+    return {
+        name,
+        title: options.title ?? null,
+        description: options.description ?? null,
+        guard,
+        scope,
+        input: options.input ?? null,
+        retry: normalizeRetry(name, options.retry),
+        // The one erasure cast for handlers: the authored context (typed input,
+        // typed scope element) is what the execution lifecycle constructs; see
+        // ErasedStepHandler.
+        handler: options.handler,
+    };
+}
+const ACTOR_MARKER = Object.freeze({});
+/** Name the actor type of a `stepsOf` factory: `stepsOf(PurchaseState, actor<PurchaseActor>())`. */
+export const actor = () => ACTOR_MARKER;
+/**
+ * Bind `step()` to a case's state schema — the schema-anchored authoring
+ * factory.
+ *
+ * ```ts
+ * const purchaseStep = stepsOf(PurchaseState, actor<PurchaseActor>())
+ *
+ * purchaseStep({
+ *   name: 'issue-funding-call',
+ *   requires: { escrowReady: s => s.escrow.status === 'open' },        // s: inferred from the schema
+ *   permits:  { isOrganizer: (_s, ctx) => hasRole(ctx.actor, 'organizer') },
+ *   handler: async s => s,
+ * })
+ *
+ * purchaseStep({
+ *   name: 'escalate-verification',
+ *   scope: { select: s => s.buyers.filter(b => b.verification.status === 'review'), key: b => b.id },
+ *   requires: { flagged: (_s, ctx) => ctx.scope.verification.flaggedAt !== null },  // ctx.scope: Buyer
+ *   handler: async s => s,
+ * })
+ * ```
+ *
+ * The state type is derived from the schema *value* — the same
+ * `InferOutput` derivation `caseType` performs — so the factory and the case
+ * type are anchored to one declaration and cannot drift apart: the state a
+ * condition sees is definitionally the state the engine validates against.
+ * The per-condition annotations the bare `step()` needs
+ * (`(s: Purchase) => …`) disappear, because `TState` is no longer inferred
+ * from the options.
+ *
+ * The second argument exists only to name the actor type and carries no
+ * runtime information; omit it for an untyped actor. Define one factory per
+ * case type module, next to the schema, and author every step of that case
+ * type through it.
+ *
+ * Returns `step` itself, re-typed — a step authored through the factory is
+ * bit-for-bit an ordinary step definition. `step` is deliberately not part
+ * of the package barrel: this factory is the public authoring surface, and
+ * a helper that builds steps generically should accept a
+ * {@link BoundStep} rather than reach for the unbound `step`.
+ * Throws at definition time when `state` is not a Standard Schema, like
+ * every other malformed-definition case in this module.
+ */
+export const stepsOf = (state, _actor) => {
+    if (!isStandardSchema(state)) {
+        throw new TypeError('stepsOf: state must be a Standard Schema (e.g. a zod schema)');
+    }
+    return step;
+};
+/** A step's declared input failed validation against its input schema. */
+export class StepInputValidationError extends AffordanceError {
+    stepName;
+    issues;
+    constructor(stepName, issues) {
+        super('invalid-input', `invalid input for step '${stepName}': ${issues.map((issue) => issue.message).join('; ')}`);
+        this.name = 'StepInputValidationError';
+        this.stepName = stepName;
+        this.issues = issues;
+    }
+}
+/**
+ * Validate a step's input against its declared input schema — the validation
+ * plumbing the execution lifecycle runs before invoking the handler ("validated before the
+ * handler runs"). Returns the schema *output* (defaults applied). A step
+ * without an input schema accepts only `undefined` and yields `undefined`;
+ * anything else is a caller bug and throws.
+ */
+export const validateStepInput = async (definition, input) => {
+    if (definition.input === null) {
+        if (input !== undefined) {
+            throw new StepInputValidationError(definition.name, [
+                { message: 'step declares no input schema, but input was provided' },
+            ]);
+        }
+        return undefined;
+    }
+    const result = await definition.input['~standard'].validate(input);
+    if (result.issues)
+        throw new StepInputValidationError(definition.name, result.issues);
+    return result.value;
+};
+//# sourceMappingURL=step.js.map