@affordance/core 0.1.0 → 0.2.0

package/dist/model/casetype.js.map

@@ -1 +1 @@
-{"version":3,"file":"casetype.js","sourceRoot":"","sources":["../../src/model/casetype.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAmDrE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,OAAmC,EACJ,EAAE;IACjC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IACtC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACnD,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAA;IAClE,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CACjB,aAAa,IAAI,wDAAwD,CAC1E,CAAA;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CACjB,aAAa,IAAI,oDAAoD,CACtE,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAGnB,CAAA;IACH,KAAK,MAAM,UAAU,IAAI,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC,uBAAuB,CAAC,UAAU,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,SAAS,CACjB,aAAa,IAAI,4CAA4C,CAC9D,CAAA;QACH,CAAC;QACD,IAAI,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,SAAS,CACjB,aAAa,IAAI,2BAA2B,UAAU,CAAC,IAAI,GAAG,CAC/D,CAAA;QACH,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IACzC,CAAC;IAED,OAAO;QACL,IAAI;QACJ,KAAK;QACL,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC;QACjB,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;KAC5C,CAAA;AACH,CAAC,CAAA","sourcesContent":["/**\n * Case type definitions.\n *\n * A **case type** declares exactly two things: a typed state schema and a set\n * of steps. Nothing else — no flow, stages, graph, or completion test; a\n * case's only \"position\" is its state.\n *\n * There is deliberately no completion predicate. Whether a\n * matter is finished is a fact about the matter, and outcomes are state: a\n * closed purchase has `closedAt`. The framework's own answer to \"is there\n * anything to do here\" is the affordance listing being empty for the actor\n * asking — no declaration required, and correct again the moment state moves.\n */\n\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type { StepDefinition } from './step.js'\nimport { isStandardSchema, looksLikeStepDefinition } from './step.js'\n\n/** Options for {@link caseType}. */\nexport interface CaseTypeOptions<S extends StandardSchemaV1, TActor = unknown> {\n  /**\n   * The case type's name — what `cases.case_type` records. Only the name is\n   * stored: the code definition floats, meaning existing cases always run\n   * against the latest deployed definition.\n   */\n  readonly name: string\n  /** The Case State schema (any Standard Schema — zod v4 qualifies). */\n  readonly state: S\n  /** The case type's steps, in declaration order (which affordance listings preserve). */\n  readonly steps: readonly StepDefinition<\n    StandardSchemaV1.InferOutput<S>,\n    TActor\n  >[]\n}\n\n/** A validated case type definition — the unit the engine registers. */\nexport interface CaseTypeDefinition<\n  S extends StandardSchemaV1 = StandardSchemaV1,\n  TActor = unknown,\n> {\n  readonly name: string\n  readonly state: S\n  readonly steps: readonly StepDefinition<\n    StandardSchemaV1.InferOutput<S>,\n    TActor\n  >[]\n  /** Look up a step by name; `undefined` when the case type declares no such step. */\n  readonly getStep: (\n    name: string,\n  ) => StepDefinition<StandardSchemaV1.InferOutput<S>, TActor> | undefined\n}\n\n/**\n * A case type with its schema and actor generics erased — what heterogeneous\n * registries (the engine's `caseTypes`) hold. `any` is deliberate: it is the\n * only way a `CaseTypeDefinition<PurchaseSchema, Ops>` and a\n * `CaseTypeDefinition<LoanSchema, Servicer>` fit one list; every use is\n * re-anchored by the state schema validation the engine performs on load.\n */\n// deliberate `any`: the existential form of CaseTypeDefinition — \"some case\n// type\", its schema deliberately unstated (see doc above). The schema slot\n// must be bare `any` — CaseTypeDefinition is invariant in S, meaning no wider\n// or narrower schema type is assignable (S feeds both the state property and\n// condition/handler parameters), so any narrower existential would reject\n// every concrete schema.\nexport type AnyCaseType = CaseTypeDefinition<any, any>\n\n/**\n * Define a case type. Validates loudly at construction time:\n *\n * - `name` must be a non-empty string and `state` a Standard Schema\n * - every element of `steps` must be a `step(...)` definition\n * - step names must be unique within the case type — a duplicate would make\n *   affordance identity (step × scope key) ambiguous\n */\nexport const caseType = <S extends StandardSchemaV1, TActor = unknown>(\n  options: CaseTypeOptions<S, TActor>,\n): CaseTypeDefinition<S, TActor> => {\n  const { name, state, steps } = options\n  if (typeof name !== 'string' || name.trim() === '') {\n    throw new TypeError('caseType: name must be a non-empty string')\n  }\n  if (!isStandardSchema(state)) {\n    throw new TypeError(\n      `caseType '${name}': state must be a Standard Schema (e.g. a zod schema)`,\n    )\n  }\n  if (!Array.isArray(steps)) {\n    throw new TypeError(\n      `caseType '${name}': steps must be an array of step(...) definitions`,\n    )\n  }\n\n  const byName = new Map<\n    string,\n    StepDefinition<StandardSchemaV1.InferOutput<S>, TActor>\n  >()\n  for (const definition of steps) {\n    if (!looksLikeStepDefinition(definition)) {\n      throw new TypeError(\n        `caseType '${name}': every step must be built with step(...)`,\n      )\n    }\n    if (byName.has(definition.name)) {\n      throw new TypeError(\n        `caseType '${name}': duplicate step name '${definition.name}'`,\n      )\n    }\n    byName.set(definition.name, definition)\n  }\n\n  return {\n    name,\n    state,\n    steps: [...steps],\n    getStep: (stepName) => byName.get(stepName),\n  }\n}\n"]}
+{"version":3,"file":"casetype.js","sourceRoot":"","sources":["../../src/model/casetype.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAgErE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAKtB,OAA4C,EACJ,EAAE;IAC1C,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IACtC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACnD,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAA;IAClE,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CACjB,aAAa,IAAI,wDAAwD,CAC1E,CAAA;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CACjB,aAAa,IAAI,oDAAoD,CACtE,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAGnB,CAAA;IACH,KAAK,MAAM,UAAU,IAAI,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC,uBAAuB,CAAC,UAAU,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,SAAS,CACjB,aAAa,IAAI,4CAA4C,CAC9D,CAAA;QACH,CAAC;QACD,IAAI,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,SAAS,CACjB,aAAa,IAAI,2BAA2B,UAAU,CAAC,IAAI,GAAG,CAC/D,CAAA;QACH,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IACzC,CAAC;IAED,OAAO;QACL,IAAI;QACJ,KAAK;QACL,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC;QACjB,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;KAC5C,CAAA;AACH,CAAC,CAAA","sourcesContent":["/**\n * Case type definitions.\n *\n * A **case type** declares exactly two things: a typed state schema and a set\n * of steps. Nothing else — no flow, stages, graph, or completion test; a\n * case's only \"position\" is its state.\n *\n * There is deliberately no completion predicate. Whether a\n * matter is finished is a fact about the matter, and outcomes are state: a\n * closed purchase has `closedAt`. The framework's own answer to \"is there\n * anything to do here\" is the affordance listing being empty for the actor\n * asking — no declaration required, and correct again the moment state moves.\n */\n\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type { StepDefinition } from './step.js'\nimport { isStandardSchema, looksLikeStepDefinition } from './step.js'\n\n/** Options for {@link caseType}. */\nexport interface CaseTypeOptions<\n  S extends StandardSchemaV1,\n  TActor = unknown,\n  TCommit = unknown,\n> {\n  /**\n   * The case type's name — what the persisted case records. Only the name is\n   * stored: the code definition floats, meaning existing cases always run\n   * against the latest deployed definition.\n   */\n  readonly name: string\n  /** The Case State schema (any Standard Schema — zod v4 qualifies). */\n  readonly state: S\n  /** The case type's steps, in declaration order (which affordance listings preserve). */\n  readonly steps: readonly StepDefinition<\n    StandardSchemaV1.InferOutput<S>,\n    TActor,\n    TCommit\n  >[]\n}\n\n/** A validated case type definition — the unit the engine registers. */\nexport interface CaseTypeDefinition<\n  S extends StandardSchemaV1 = StandardSchemaV1,\n  TActor = unknown,\n  TCommit = unknown,\n> {\n  readonly name: string\n  readonly state: S\n  readonly steps: readonly StepDefinition<\n    StandardSchemaV1.InferOutput<S>,\n    TActor,\n    TCommit\n  >[]\n  /** Look up a step by name; `undefined` when the case type declares no such step. */\n  readonly getStep: (\n    name: string,\n  ) =>\n    | StepDefinition<StandardSchemaV1.InferOutput<S>, TActor, TCommit>\n    | undefined\n}\n\n/**\n * A case type with its schema and actor generics erased — what heterogeneous\n * registries (the engine's `caseTypes`) hold. `any` is deliberate: it is the\n * only way a `CaseTypeDefinition<PurchaseSchema, Ops>` and a\n * `CaseTypeDefinition<LoanSchema, Servicer>` fit one list; every use is\n * re-anchored by the state schema validation the engine performs on load.\n */\n// deliberate `any`: the existential form of CaseTypeDefinition — \"some case\n// type\", its schema deliberately unstated (see doc above). The schema slot\n// must be bare `any` — CaseTypeDefinition is invariant in S, meaning no wider\n// or narrower schema type is assignable (S feeds both the state property and\n// condition/handler parameters), so any narrower existential would reject\n// every concrete schema.\nexport type AnyCaseType<TCommit = unknown> = CaseTypeDefinition<\n  any,\n  any,\n  TCommit\n>\n\n/**\n * Define a case type. Validates loudly at construction time:\n *\n * - `name` must be a non-empty string and `state` a Standard Schema\n * - every element of `steps` must be a `step(...)` definition\n * - step names must be unique within the case type — a duplicate would make\n *   affordance identity (step × scope key) ambiguous\n */\nexport const caseType = <\n  S extends StandardSchemaV1,\n  TActor = unknown,\n  TCommit = unknown,\n>(\n  options: CaseTypeOptions<S, TActor, TCommit>,\n): CaseTypeDefinition<S, TActor, TCommit> => {\n  const { name, state, steps } = options\n  if (typeof name !== 'string' || name.trim() === '') {\n    throw new TypeError('caseType: name must be a non-empty string')\n  }\n  if (!isStandardSchema(state)) {\n    throw new TypeError(\n      `caseType '${name}': state must be a Standard Schema (e.g. a zod schema)`,\n    )\n  }\n  if (!Array.isArray(steps)) {\n    throw new TypeError(\n      `caseType '${name}': steps must be an array of step(...) definitions`,\n    )\n  }\n\n  const byName = new Map<\n    string,\n    StepDefinition<StandardSchemaV1.InferOutput<S>, TActor, TCommit>\n  >()\n  for (const definition of steps) {\n    if (!looksLikeStepDefinition(definition)) {\n      throw new TypeError(\n        `caseType '${name}': every step must be built with step(...)`,\n      )\n    }\n    if (byName.has(definition.name)) {\n      throw new TypeError(\n        `caseType '${name}': duplicate step name '${definition.name}'`,\n      )\n    }\n    byName.set(definition.name, definition)\n  }\n\n  return {\n    name,\n    state,\n    steps: [...steps],\n    getStep: (stepName) => byName.get(stepName),\n  }\n}\n"]}

package/dist/model/handler.d.ts

@@ -12,12 +12,11 @@
  * external effect must be deduplicated on `ctx.executionId`. Nothing in the
  * model layer ever invokes a handler — `packages/core/src/execution` does.
  */
-import type { Queryable } from '../store/index.js';
+import type { CorrelationRegistration } from '../ingestion/correlation.js';
 /**
  * A write to run inside the framework's **commit** transaction, registered
- * from a handler via `ctx.onCommit`. It receives the transaction handle
- * the framework is committing Case State on, so app-table writes land
- * atomically with the case row and the journal entry. This is the
+ * from a handler via `ctx.onCommit`. It receives an adapter-defined transaction or repository context. Those writes
+ * commit atomically with Case State and the journal entry. This is the
  * shared-transaction seam — the one point where app writes join the
  * framework's transaction — and it avoids holding a transaction open across
  * the handler's external calls.
@@ -25,7 +24,7 @@ import type { Queryable } from '../store/index.js';
  * A callback that throws aborts the whole commit: nothing is written, the
  * attempt is journaled as failed, and the retry policy applies.
  */
-export type CommitWrite = (tx: Queryable) => Promise<void>;
+export type CommitWrite<TCommit = unknown> = (tx: TCommit) => Promise<void>;
 /**
  * What a handler registers when it hands work to an external system
  *: "this envelope id is how the answer will come back". The case
@@ -51,7 +50,7 @@ export interface CorrelationRequest {
  * external effect must be deduplicated on it. `attempt` /
  * `maxAttempts` let a handler tell a first try from a retry.
  */
-export interface HandlerContext<TActor = unknown, TInput = undefined> {
+export interface HandlerContext<TActor = unknown, TInput = undefined, TCommit = unknown> {
     /** Unique id of this Execution — the handler's idempotency key. */
     readonly executionId: string;
     /** The case this Execution runs on. */
@@ -68,21 +67,20 @@ export interface HandlerContext<TActor = unknown, TInput = undefined> {
     /** Total attempts this Execution is allowed, from the step's retry policy. */
     readonly maxAttempts: number;
     /**
-     * Register an app-table write to run inside the framework's commit
+     * Register an application write to run inside the framework's commit
      * transaction, so it commits atomically with the new Case State.
      * Callbacks run in registration order; registrations from a failed attempt
      * are discarded before the next attempt.
      */
-    onCommit(write: CommitWrite): void;
+    onCommit(write: CommitWrite<TCommit>): void;
     /**
      * Register an external identifier against this case (and, on a scoped
      * step, this element) so the eventual webhook can be routed back.
      * Correlation is one half of integrating an external system; Ingestion —
      * executing the routed event as an ordinary step — is the other.
      *
-     * Written inside the commit transaction, like any `onCommit` write: a case
-     * cannot end up having sent an envelope whose answer it could not route,
-     * because the sending and the mapping are the same commit.
+     * Written atomically with Case State and other commit effects. External
+     * provider calls are outside this atomic operation and must be idempotent.
      */
     correlate(request: CorrelationRequest): void;
     /**
@@ -97,7 +95,7 @@ export interface HandlerContext<TActor = unknown, TInput = undefined> {
     reopen(): void;
 }
 /** The context a scoped step's handler receives: the base context plus the scope binding. */
-export interface ScopedHandlerContext<TElement, TActor = unknown, TInput = undefined> extends HandlerContext<TActor, TInput> {
+export interface ScopedHandlerContext<TElement, TActor = unknown, TInput = undefined, TCommit = unknown> extends HandlerContext<TActor, TInput, TCommit> {
     /** The bound scope element the Execution is about (e.g. one buyer). */
     readonly scope: TElement;
     /** The element's scope key — half of the affordance's identity. */
@@ -107,9 +105,9 @@ export interface ScopedHandlerContext<TElement, TActor = unknown, TInput = undef
  * An unscoped step's handler: async, receives the current Case State and the
  * execution context, and returns the **next** Case State document.
  */
-export type StepHandler<TState, TActor = unknown, TInput = undefined> = (state: TState, ctx: HandlerContext<TActor, TInput>) => Promise<TState>;
+export type StepHandler<TState, TActor = unknown, TInput = undefined, TCommit = unknown> = (state: TState, ctx: HandlerContext<TActor, TInput, TCommit>) => Promise<TState>;
 /** A scoped step's handler: as {@link StepHandler}, with the scope binding on ctx. */
-export type ScopedStepHandler<TState, TElement, TActor = unknown, TInput = undefined> = (state: TState, ctx: ScopedHandlerContext<TElement, TActor, TInput>) => Promise<TState>;
+export type ScopedStepHandler<TState, TElement, TActor = unknown, TInput = undefined, TCommit = unknown> = (state: TState, ctx: ScopedHandlerContext<TElement, TActor, TInput, TCommit>) => Promise<TState>;
 /**
  * A handler as held on a normalized {@link StepDefinition}: the authoring
  * generics (input, scope element) erased. The execution lifecycle invokes
@@ -117,4 +115,12 @@ export type ScopedStepHandler<TState, TElement, TActor = unknown, TInput = undef
  * (the model layer guarantees input was validated and, for scoped steps, a
  * scope is bound).
  */
-export type ErasedStepHandler<TState, TActor = unknown> = (state: TState, ctx: HandlerContext<TActor, unknown> | ScopedHandlerContext<unknown, TActor, unknown>) => Promise<TState>;
+export type ErasedStepHandler<TState, TActor = unknown, TCommit = unknown> = (state: TState, ctx: HandlerContext<TActor, unknown, TCommit> | ScopedHandlerContext<unknown, TActor, unknown, TCommit>) => Promise<TState>;
+/** Registrations share one ordered queue and are discarded on a failed attempt. */
+export type CommitEffect<TCommit = unknown> = {
+    readonly kind: 'write';
+    readonly write: CommitWrite<TCommit>;
+} | {
+    readonly kind: 'correlation';
+    readonly registration: CorrelationRegistration;
+};

package/dist/model/handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../src/model/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG","sourcesContent":["/**\n * Handler types.\n *\n * A **handler** is a step's effect function — the only thing that mutates\n * Case State (CONTEXT.md). It receives the current Case State and an\n * execution context, and returns the **next** Case State document; the\n * execution lifecycle derives the journaled delta from\n * (previous, next).\n *\n * Handlers are short-lived, at-least-once and idempotent: the\n * same handler may run more than once for the same Execution, so every\n * external effect must be deduplicated on `ctx.executionId`. Nothing in the\n * model layer ever invokes a handler — `packages/core/src/execution` does.\n */\n\nimport type { Queryable } from '../store/index.js'\n\n/**\n * A write to run inside the framework's **commit** transaction, registered\n * from a handler via `ctx.onCommit`. It receives the transaction handle\n * the framework is committing Case State on, so app-table writes land\n * atomically with the case row and the journal entry. This is the\n * shared-transaction seam — the one point where app writes join the\n * framework's transaction — and it avoids holding a transaction open across\n * the handler's external calls.\n *\n * A callback that throws aborts the whole commit: nothing is written, the\n * attempt is journaled as failed, and the retry policy applies.\n */\nexport type CommitWrite = (tx: Queryable) => Promise<void>\n\n/**\n * What a handler registers when it hands work to an external system\n *: \"this envelope id is how the answer will come back\". The case\n * is implicit — it is the one the handler is running on — and for a scoped\n * step the scope element is too.\n */\nexport interface CorrelationRequest {\n  /** The external system, as the app names it: `'esign'`, `'verify'`, `'escrow'`. */\n  readonly system: string\n  /** The identifier that system will quote back. */\n  readonly externalId: string\n  /** Defaults to the Execution's own scope key on a scoped step; pass `null` for case-level. */\n  readonly scopeKey?: string | null\n  /** The step an event on this identifier should execute — usually the materializing step. */\n  readonly step?: string | null\n  /** Anything the app wants to keep alongside the mapping. */\n  readonly metadata?: unknown\n}\n\n/**\n * The context a handler receives alongside Case State.\n *\n * `executionId` is the idempotency key: handlers run at-least-once, so any\n * external effect must be deduplicated on it. `attempt` /\n * `maxAttempts` let a handler tell a first try from a retry.\n */\nexport interface HandlerContext<TActor = unknown, TInput = undefined> {\n  /** Unique id of this Execution — the handler's idempotency key. */\n  readonly executionId: string\n  /** The case this Execution runs on. */\n  readonly caseId: string\n  /** The Actor the step is being executed as (app-defined shape). */\n  readonly actor: TActor\n  /**\n   * The step's input, validated against the step's `input` schema before the\n   * handler runs (`undefined` for steps that declare no input schema).\n   */\n  readonly input: TInput\n  /** 1-based attempt number for this Execution; > 1 means a retry of the same `executionId`. */\n  readonly attempt: number\n  /** Total attempts this Execution is allowed, from the step's retry policy. */\n  readonly maxAttempts: number\n\n  /**\n   * Register an app-table write to run inside the framework's commit\n   * transaction, so it commits atomically with the new Case State.\n   * Callbacks run in registration order; registrations from a failed attempt\n   * are discarded before the next attempt.\n   */\n  onCommit(write: CommitWrite): void\n\n  /**\n   * Register an external identifier against this case (and, on a scoped\n   * step, this element) so the eventual webhook can be routed back.\n   * Correlation is one half of integrating an external system; Ingestion —\n   * executing the routed event as an ordinary step — is the other.\n   *\n   * Written inside the commit transaction, like any `onCommit` write: a case\n   * cannot end up having sent an envelope whose answer it could not route,\n   * because the sending and the mapping are the same commit.\n   */\n  correlate(request: CorrelationRequest): void\n\n  /**\n   * Mark the case dormant: a journaled terminal marker written with this\n   * Execution's commit. Dormancy means exclusion from\n   * default active listings — **never** a freeze: a dormant case still\n   * computes affordances, and a step guarded on ended state can still claim\n   * and {@link HandlerContext.reopen} it.\n   */\n  end(): void\n\n  /** Clear the dormancy marker — un-ending is an ordinary step. */\n  reopen(): void\n}\n\n/** The context a scoped step's handler receives: the base context plus the scope binding. */\nexport interface ScopedHandlerContext<\n  TElement,\n  TActor = unknown,\n  TInput = undefined,\n> extends HandlerContext<TActor, TInput> {\n  /** The bound scope element the Execution is about (e.g. one buyer). */\n  readonly scope: TElement\n  /** The element's scope key — half of the affordance's identity. */\n  readonly scopeKey: string\n}\n\n/**\n * An unscoped step's handler: async, receives the current Case State and the\n * execution context, and returns the **next** Case State document.\n */\nexport type StepHandler<TState, TActor = unknown, TInput = undefined> = (\n  state: TState,\n  ctx: HandlerContext<TActor, TInput>,\n) => Promise<TState>\n\n/** A scoped step's handler: as {@link StepHandler}, with the scope binding on ctx. */\nexport type ScopedStepHandler<\n  TState,\n  TElement,\n  TActor = unknown,\n  TInput = undefined,\n> = (\n  state: TState,\n  ctx: ScopedHandlerContext<TElement, TActor, TInput>,\n) => Promise<TState>\n\n/**\n * A handler as held on a normalized {@link StepDefinition}: the authoring\n * generics (input, scope element) erased. The execution lifecycle invokes\n * through this type, constructing a context that satisfies the authored shape\n * (the model layer guarantees input was validated and, for scoped steps, a\n * scope is bound).\n */\nexport type ErasedStepHandler<TState, TActor = unknown> = (\n  state: TState,\n  ctx:\n    | HandlerContext<TActor, unknown>\n    | ScopedHandlerContext<unknown, TActor, unknown>,\n) => Promise<TState>\n"]}
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../src/model/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG","sourcesContent":["/**\n * Handler types.\n *\n * A **handler** is a step's effect function — the only thing that mutates\n * Case State (CONTEXT.md). It receives the current Case State and an\n * execution context, and returns the **next** Case State document; the\n * execution lifecycle derives the journaled delta from\n * (previous, next).\n *\n * Handlers are short-lived, at-least-once and idempotent: the\n * same handler may run more than once for the same Execution, so every\n * external effect must be deduplicated on `ctx.executionId`. Nothing in the\n * model layer ever invokes a handler — `packages/core/src/execution` does.\n */\n\nimport type { CorrelationRegistration } from '../ingestion/correlation.js'\n\n/**\n * A write to run inside the framework's **commit** transaction, registered\n * from a handler via `ctx.onCommit`. It receives an adapter-defined transaction or repository context. Those writes\n * commit atomically with Case State and the journal entry. This is the\n * shared-transaction seam — the one point where app writes join the\n * framework's transaction — and it avoids holding a transaction open across\n * the handler's external calls.\n *\n * A callback that throws aborts the whole commit: nothing is written, the\n * attempt is journaled as failed, and the retry policy applies.\n */\nexport type CommitWrite<TCommit = unknown> = (tx: TCommit) => Promise<void>\n\n/**\n * What a handler registers when it hands work to an external system\n *: \"this envelope id is how the answer will come back\". The case\n * is implicit — it is the one the handler is running on — and for a scoped\n * step the scope element is too.\n */\nexport interface CorrelationRequest {\n  /** The external system, as the app names it: `'esign'`, `'verify'`, `'escrow'`. */\n  readonly system: string\n  /** The identifier that system will quote back. */\n  readonly externalId: string\n  /** Defaults to the Execution's own scope key on a scoped step; pass `null` for case-level. */\n  readonly scopeKey?: string | null\n  /** The step an event on this identifier should execute — usually the materializing step. */\n  readonly step?: string | null\n  /** Anything the app wants to keep alongside the mapping. */\n  readonly metadata?: unknown\n}\n\n/**\n * The context a handler receives alongside Case State.\n *\n * `executionId` is the idempotency key: handlers run at-least-once, so any\n * external effect must be deduplicated on it. `attempt` /\n * `maxAttempts` let a handler tell a first try from a retry.\n */\nexport interface HandlerContext<\n  TActor = unknown,\n  TInput = undefined,\n  TCommit = unknown,\n> {\n  /** Unique id of this Execution — the handler's idempotency key. */\n  readonly executionId: string\n  /** The case this Execution runs on. */\n  readonly caseId: string\n  /** The Actor the step is being executed as (app-defined shape). */\n  readonly actor: TActor\n  /**\n   * The step's input, validated against the step's `input` schema before the\n   * handler runs (`undefined` for steps that declare no input schema).\n   */\n  readonly input: TInput\n  /** 1-based attempt number for this Execution; > 1 means a retry of the same `executionId`. */\n  readonly attempt: number\n  /** Total attempts this Execution is allowed, from the step's retry policy. */\n  readonly maxAttempts: number\n\n  /**\n   * Register an application write to run inside the framework's commit\n   * transaction, so it commits atomically with the new Case State.\n   * Callbacks run in registration order; registrations from a failed attempt\n   * are discarded before the next attempt.\n   */\n  onCommit(write: CommitWrite<TCommit>): void\n\n  /**\n   * Register an external identifier against this case (and, on a scoped\n   * step, this element) so the eventual webhook can be routed back.\n   * Correlation is one half of integrating an external system; Ingestion —\n   * executing the routed event as an ordinary step — is the other.\n   *\n   * Written atomically with Case State and other commit effects. External\n   * provider calls are outside this atomic operation and must be idempotent.\n   */\n  correlate(request: CorrelationRequest): void\n\n  /**\n   * Mark the case dormant: a journaled terminal marker written with this\n   * Execution's commit. Dormancy means exclusion from\n   * default active listings — **never** a freeze: a dormant case still\n   * computes affordances, and a step guarded on ended state can still claim\n   * and {@link HandlerContext.reopen} it.\n   */\n  end(): void\n\n  /** Clear the dormancy marker — un-ending is an ordinary step. */\n  reopen(): void\n}\n\n/** The context a scoped step's handler receives: the base context plus the scope binding. */\nexport interface ScopedHandlerContext<\n  TElement,\n  TActor = unknown,\n  TInput = undefined,\n  TCommit = unknown,\n> extends HandlerContext<TActor, TInput, TCommit> {\n  /** The bound scope element the Execution is about (e.g. one buyer). */\n  readonly scope: TElement\n  /** The element's scope key — half of the affordance's identity. */\n  readonly scopeKey: string\n}\n\n/**\n * An unscoped step's handler: async, receives the current Case State and the\n * execution context, and returns the **next** Case State document.\n */\nexport type StepHandler<\n  TState,\n  TActor = unknown,\n  TInput = undefined,\n  TCommit = unknown,\n> = (\n  state: TState,\n  ctx: HandlerContext<TActor, TInput, TCommit>,\n) => Promise<TState>\n\n/** A scoped step's handler: as {@link StepHandler}, with the scope binding on ctx. */\nexport type ScopedStepHandler<\n  TState,\n  TElement,\n  TActor = unknown,\n  TInput = undefined,\n  TCommit = unknown,\n> = (\n  state: TState,\n  ctx: ScopedHandlerContext<TElement, TActor, TInput, TCommit>,\n) => Promise<TState>\n\n/**\n * A handler as held on a normalized {@link StepDefinition}: the authoring\n * generics (input, scope element) erased. The execution lifecycle invokes\n * through this type, constructing a context that satisfies the authored shape\n * (the model layer guarantees input was validated and, for scoped steps, a\n * scope is bound).\n */\nexport type ErasedStepHandler<TState, TActor = unknown, TCommit = unknown> = (\n  state: TState,\n  ctx:\n    | HandlerContext<TActor, unknown, TCommit>\n    | ScopedHandlerContext<unknown, TActor, unknown, TCommit>,\n) => Promise<TState>\n\n/** Registrations share one ordered queue and are discarded on a failed attempt. */\nexport type CommitEffect<TCommit = unknown> =\n  | { readonly kind: 'write'; readonly write: CommitWrite<TCommit> }\n  | {\n      readonly kind: 'correlation'\n      readonly registration: CorrelationRegistration\n    }\n"]}

package/dist/model/index.d.ts

@@ -14,11 +14,11 @@
 export type { AnyCaseType, CaseTypeDefinition, CaseTypeOptions, } from './casetype.js';
 export { caseType } from './casetype.js';
 export { ScopeKeyError, UnknownStepError } from './errors.js';
-export type { CommitWrite, CorrelationRequest, ErasedStepHandler, HandlerContext, ScopedHandlerContext, ScopedStepHandler, StepHandler, } from './handler.js';
+export type { CommitEffect, CommitWrite, CorrelationRequest, ErasedStepHandler, HandlerContext, ScopedHandlerContext, ScopedStepHandler, StepHandler, } from './handler.js';
 export type { RetryOptions, RetryPolicy } from './retry.js';
 export { DEFAULT_RETRY, normalizeRetry } from './retry.js';
 export type { ScopeDeclaration, ScopedCondition, ScopedConditionContext, ScopedConditionMap, ScopedConditionMapEntry, } from './scope.js';
-export type { ActorMarker, BoundStep, ScopedStepOptions, StepDefinition, StepMetadata, StepOptions, } from './step.js';
-export { actor, StepInputValidationError, step, stepsOf, validateStepInput, } from './step.js';
+export type { ActorMarker, BoundStep, CommitContextMarker, ScopedStepOptions, StepDefinition, StepMetadata, StepOptions, } from './step.js';
+export { actor, commitContext, StepInputValidationError, step, stepsOf, validateStepInput, } from './step.js';
 export type { ComputationContext, ScopeBinding, StepTarget, TargetAddress, TargetAddressFailure, TargetSelection, } from './target.js';
 export { addressTarget, evaluateTarget, resolveTarget, SCOPE_FAILURE_CONDITION, scopeFailureEvaluation, selectTargets, } from './target.js';

package/dist/model/index.js

@@ -14,6 +14,6 @@
 export { caseType } from './casetype.js';
 export { ScopeKeyError, UnknownStepError } from './errors.js';
 export { DEFAULT_RETRY, normalizeRetry } from './retry.js';
-export { actor, StepInputValidationError, step, stepsOf, validateStepInput, } from './step.js';
+export { actor, commitContext, StepInputValidationError, step, stepsOf, validateStepInput, } from './step.js';
 export { addressTarget, evaluateTarget, resolveTarget, SCOPE_FAILURE_CONDITION, scopeFailureEvaluation, selectTargets, } from './target.js';
 //# sourceMappingURL=index.js.map

package/dist/model/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/model/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAW7D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAgB1D,OAAO,EACL,KAAK,EACL,wBAAwB,EACxB,IAAI,EACJ,OAAO,EACP,iBAAiB,GAClB,MAAM,WAAW,CAAA;AASlB,OAAO,EACL,aAAa,EACb,cAAc,EACd,aAAa,EACb,uBAAuB,EACvB,sBAAsB,EACtB,aAAa,GACd,MAAM,aAAa,CAAA","sourcesContent":["/**\n * The definition API: case types and steps.\n *\n * A **case type** declares a typed state schema and a set of guarded\n * **steps** — nothing else. A **step** is a\n * guard plus a handler; a step may declare a **scope** over a state\n * collection, yielding one affordance per selected element with identity\n * (step × scope key). Handlers are declared here and executed by the\n * execution lifecycle; this module never invokes one.\n *\n * See CONTEXT.md for the vocabulary and the guards module for the condition\n * algebra these definitions are built from.\n */\n\nexport type {\n  AnyCaseType,\n  CaseTypeDefinition,\n  CaseTypeOptions,\n} from './casetype.js'\nexport { caseType } from './casetype.js'\nexport { ScopeKeyError, UnknownStepError } from './errors.js'\nexport type {\n  CommitWrite,\n  CorrelationRequest,\n  ErasedStepHandler,\n  HandlerContext,\n  ScopedHandlerContext,\n  ScopedStepHandler,\n  StepHandler,\n} from './handler.js'\nexport type { RetryOptions, RetryPolicy } from './retry.js'\nexport { DEFAULT_RETRY, normalizeRetry } from './retry.js'\nexport type {\n  ScopeDeclaration,\n  ScopedCondition,\n  ScopedConditionContext,\n  ScopedConditionMap,\n  ScopedConditionMapEntry,\n} from './scope.js'\nexport type {\n  ActorMarker,\n  BoundStep,\n  ScopedStepOptions,\n  StepDefinition,\n  StepMetadata,\n  StepOptions,\n} from './step.js'\nexport {\n  actor,\n  StepInputValidationError,\n  step,\n  stepsOf,\n  validateStepInput,\n} from './step.js'\nexport type {\n  ComputationContext,\n  ScopeBinding,\n  StepTarget,\n  TargetAddress,\n  TargetAddressFailure,\n  TargetSelection,\n} from './target.js'\nexport {\n  addressTarget,\n  evaluateTarget,\n  resolveTarget,\n  SCOPE_FAILURE_CONDITION,\n  scopeFailureEvaluation,\n  selectTargets,\n} from './target.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/model/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAY7D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAiB1D,OAAO,EACL,KAAK,EACL,aAAa,EACb,wBAAwB,EACxB,IAAI,EACJ,OAAO,EACP,iBAAiB,GAClB,MAAM,WAAW,CAAA;AASlB,OAAO,EACL,aAAa,EACb,cAAc,EACd,aAAa,EACb,uBAAuB,EACvB,sBAAsB,EACtB,aAAa,GACd,MAAM,aAAa,CAAA","sourcesContent":["/**\n * The definition API: case types and steps.\n *\n * A **case type** declares a typed state schema and a set of guarded\n * **steps** — nothing else. A **step** is a\n * guard plus a handler; a step may declare a **scope** over a state\n * collection, yielding one affordance per selected element with identity\n * (step × scope key). Handlers are declared here and executed by the\n * execution lifecycle; this module never invokes one.\n *\n * See CONTEXT.md for the vocabulary and the guards module for the condition\n * algebra these definitions are built from.\n */\n\nexport type {\n  AnyCaseType,\n  CaseTypeDefinition,\n  CaseTypeOptions,\n} from './casetype.js'\nexport { caseType } from './casetype.js'\nexport { ScopeKeyError, UnknownStepError } from './errors.js'\nexport type {\n  CommitEffect,\n  CommitWrite,\n  CorrelationRequest,\n  ErasedStepHandler,\n  HandlerContext,\n  ScopedHandlerContext,\n  ScopedStepHandler,\n  StepHandler,\n} from './handler.js'\nexport type { RetryOptions, RetryPolicy } from './retry.js'\nexport { DEFAULT_RETRY, normalizeRetry } from './retry.js'\nexport type {\n  ScopeDeclaration,\n  ScopedCondition,\n  ScopedConditionContext,\n  ScopedConditionMap,\n  ScopedConditionMapEntry,\n} from './scope.js'\nexport type {\n  ActorMarker,\n  BoundStep,\n  CommitContextMarker,\n  ScopedStepOptions,\n  StepDefinition,\n  StepMetadata,\n  StepOptions,\n} from './step.js'\nexport {\n  actor,\n  commitContext,\n  StepInputValidationError,\n  step,\n  stepsOf,\n  validateStepInput,\n} from './step.js'\nexport type {\n  ComputationContext,\n  ScopeBinding,\n  StepTarget,\n  TargetAddress,\n  TargetAddressFailure,\n  TargetSelection,\n} from './target.js'\nexport {\n  addressTarget,\n  evaluateTarget,\n  resolveTarget,\n  SCOPE_FAILURE_CONDITION,\n  scopeFailureEvaluation,\n  selectTargets,\n} from './target.js'\n"]}

package/dist/model/step.d.ts

@@ -14,7 +14,7 @@ import type { ErasedStepHandler, ScopedStepHandler, StepHandler } from './handle
 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> {
+export interface StepOptions<TState, TActor = unknown, TInput = undefined, TCommit = unknown> {
     /** The step's name — unique within its case type; half of a scoped affordance's identity. */
     readonly name: string;
     /**
@@ -46,10 +46,10 @@ export interface StepOptions<TState, TActor = unknown, TInput = undefined> {
      */
     readonly retry?: RetryOptions;
     /** The step's effect function — the only thing that mutates Case State. */
-    readonly handler: StepHandler<TState, TActor, TInput>;
+    readonly handler: StepHandler<TState, TActor, TInput, TCommit>;
 }
 /** Options for a scoped step: an unscoped step plus the scope declaration. */
-export interface ScopedStepOptions<TState, TElement, TActor = unknown, TInput = undefined> {
+export interface ScopedStepOptions<TState, TElement, TActor = unknown, TInput = undefined, TCommit = unknown> {
     readonly name: string;
     readonly title?: string;
     readonly description?: string;
@@ -59,7 +59,7 @@ export interface ScopedStepOptions<TState, TElement, TActor = unknown, TInput =
     readonly permits?: ScopedConditionMap<TState, TElement, TActor>;
     readonly input?: StandardSchemaV1<unknown, TInput>;
     readonly retry?: RetryOptions;
-    readonly handler: ScopedStepHandler<TState, TElement, TActor, TInput>;
+    readonly handler: ScopedStepHandler<TState, TElement, TActor, TInput, TCommit>;
 }
 /**
  * A step definition as held by a case type and consumed by the engine — the
@@ -67,7 +67,7 @@ export interface ScopedStepOptions<TState, TElement, TActor = unknown, TInput =
  * The options types above carry the precise authoring shapes; this is the
  * machine-facing normal form.
  */
-export interface StepDefinition<TState, TActor = unknown> {
+export interface StepDefinition<TState, TActor = unknown, TCommit = unknown> {
     readonly name: string;
     /** The declared human label, or `null` — clients fall back to `name`. */
     readonly title: string | null;
@@ -89,7 +89,7 @@ export interface StepDefinition<TState, TActor = unknown> {
     /** 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>;
+    readonly handler: ErasedStepHandler<TState, TActor, TCommit>;
 }
 /**
  * A step's declared human metadata, as `Engine.stepMetadataFor` answers it —
@@ -143,8 +143,8 @@ export declare const looksLikeStepDefinition: (value: unknown) => value is StepD
  * (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>;
+export declare function step<TState, TElement, TActor = unknown, TInput = undefined, TCommit = unknown>(options: ScopedStepOptions<TState, TElement, TActor, TInput, TCommit>): StepDefinition<TState, TActor, TCommit>;
+export declare function step<TState, TActor = unknown, TInput = undefined, TCommit = unknown>(options: StepOptions<TState, TActor, TInput, TCommit>): StepDefinition<TState, TActor, TCommit>;
 /**
  * The `step()` authoring surface with the case's state and actor types fixed.
  *
@@ -156,9 +156,9 @@ export declare function step<TState, TActor = unknown, TInput = undefined>(optio
  * 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>;
+export interface BoundStep<TState, TActor = unknown, TCommit = unknown> {
+    <TElement, TInput = undefined>(options: ScopedStepOptions<TState, TElement, TActor, TInput, TCommit>): StepDefinition<TState, TActor, TCommit>;
+    <TInput = undefined>(options: StepOptions<TState, TActor, TInput, TCommit>): StepDefinition<TState, TActor, TCommit>;
 }
 /**
  * A value-level carrier for `stepsOf`'s actor type — nothing but the type.
@@ -215,7 +215,7 @@ export declare const actor: <TActor>() => ActorMarker<TActor>;
  * 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>;
+export declare const stepsOf: <S extends StandardSchemaV1, TActor = unknown, TCommit = unknown>(state: S, _actor?: ActorMarker<TActor>, _commit?: CommitContextMarker<TCommit>) => BoundStep<StandardSchemaV1.InferOutput<S>, TActor, TCommit>;
 /** A step's declared input failed validation against its input schema. */
 export declare class StepInputValidationError extends AffordanceError {
     readonly stepName: string;
@@ -229,4 +229,9 @@ export declare class StepInputValidationError extends AffordanceError {
  * 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>;
+export declare const validateStepInput: <TState, TActor, TCommit>(definition: StepDefinition<TState, TActor, TCommit>, input: unknown) => Promise<unknown>;
+/** Name the transaction/repository context supplied to onCommit callbacks. */
+export interface CommitContextMarker<TCommit> {
+    readonly __commit?: TCommit;
+}
+export declare const commitContext: <TCommit>() => CommitContextMarker<TCommit>;

package/dist/model/step.js

@@ -169,7 +169,7 @@ export const actor = () => ACTOR_MARKER;
  * 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) => {
+export const stepsOf = (state, _actor, _commit) => {
     if (!isStandardSchema(state)) {
         throw new TypeError('stepsOf: state must be a Standard Schema (e.g. a zod schema)');
     }
@@ -207,4 +207,5 @@ export const validateStepInput = async (definition, input) => {
         throw new StepInputValidationError(definition.name, result.issues);
     return result.value;
 };
+export const commitContext = () => ({});
 //# sourceMappingURL=step.js.map

package/dist/model/step.js.map

@@ -1 +1 @@
-{"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/model/step.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAOjD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAkGpD,qFAAqF;AACrF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAA6B,EAAE,CAC5E,OAAO,KAAK,KAAK,QAAQ;IACzB,KAAK,KAAK,IAAI;IACd,OAAQ,KAAmC,CAAC,WAAW,CAAC,KAAK,QAAQ,CAAA;AAEvE;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,KAAc,EAC6B,EAAE,CAC7C,OAAO,KAAK,KAAK,QAAQ;IACzB,KAAK,KAAK,IAAI;IACd,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ;IACtD,OAAQ,KAA+B,CAAC,OAAO,KAAK,UAAU;IAC9D,OAAQ,KAA6B,CAAC,KAAK,KAAK,QAAQ,CAAA;AAE1D;;;;;;;;;GASG;AACH,MAAM,oBAAoB,GAAG,CAC3B,QAAgB,EAChB,OAAqB,EACrB,GAAkD,EAClD,UAAmB,EACb,EAAE;IACR,IAAI,GAAG,KAAK,SAAS;QAAE,OAAM;IAC7B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,SAAS,CACjB,SAAS,QAAQ,MAAM,OAAO,6CAA6C,CAC5E,CAAA;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,GAAG,EAA6B,CAAA;IAC9D,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3C,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW;YAAE,SAAQ;QACxC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,UAAU;YAAE,SAAQ;QAClD,MAAM,OAAO,GAAG,UAAU;YACxB,CAAC,CAAC,6CAA6C;YAC/C,CAAC,CAAC,sEAAsE,CAAA;QAC1E,MAAM,IAAI,SAAS,CACjB,SAAS,QAAQ,MAAM,KAAK,CAAC,OAAO,YAAY,OAAO,EAAE,CAC1D,CAAA;IACH,CAAC;AACH,CAAC,CAAA;AAED,MAAM,cAAc,GAAG,CAAC,OAMvB,EAAU,EAAE;IACX,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAA;IACxB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACnD,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAA;IAC9D,CAAC;IACD,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QAC1C,MAAM,IAAI,SAAS,CAAC,SAAS,IAAI,sCAAsC,CAAC,CAAA;IAC1E,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,SAAS,CACjB,SAAS,IAAI,wDAAwD,CACtE,CAAA;IACH,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,CAAC,OAAO,EAAE,aAAa,CAAU,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;QAC5B,IACE,KAAK,KAAK,SAAS;YACnB,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAClD,CAAC;YACD,MAAM,IAAI,SAAS,CACjB,SAAS,IAAI,MAAM,KAAK,wCAAwC,CACjE,CAAA;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AA4CD,MAAM,UAAU,IAAI,CAClB,OAEuD;IAEvD,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IACpC,MAAM,MAAM,GAAG,OAAO,IAAI,OAAO,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,CAAA;IAChE,IAAI,KAAK,GAA4C,IAAI,CAAA;IACzD,IAAI,KAA4B,CAAA;IAEhC,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,WAAW,GACf,OACD,CAAC,KAAK,CAAA;QACP,IACE,OAAO,WAAW,KAAK,QAAQ;YAC/B,WAAW,KAAK,IAAI;YACpB,OAAO,WAAW,CAAC,MAAM,KAAK,UAAU;YACxC,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,EACrC,CAAC;YACD,MAAM,IAAI,SAAS,CACjB,SAAS,IAAI,wEAAwE,CACtF,CAAA;QACH,CAAC;QACD,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;QAC/D,oBAAoB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QAC7D,KAAK,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,CAAA;QAC5D,yEAAyE;QACzE,qEAAqE;QACrE,MAAM,aAAa,GAAG,OAKrB,CAAA;QACD,KAAK,GAAG;YACN,GAAG,CAAC,aAAa,CAAC,QAAQ,KAAK,SAAS,IAAI;gBAC1C,QAAQ,EAAE,uBAAuB,CAAC,aAAa,CAAC,QAAQ,CAAC;aAC1D,CAAC;YACF,GAAG,CAAC,aAAa,CAAC,OAAO,KAAK,SAAS,IAAI;gBACzC,OAAO,EAAE,uBAAuB,CAAC,aAAa,CAAC,OAAO,CAAC;aACxD,CAAC;SACH,CAAA;IACH,CAAC;SAAM,CAAC;QACN,MAAM,QAAQ,GAAG,OAA+C,CAAA;QAChE,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;QAC/D,oBAAoB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QAC7D,KAAK,GAAG;YACN,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACvE,GAAG,CAAC,QAAQ,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;SACrE,CAAA;IACH,CAAC;IAED,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI;QAC5B,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,KAAK;QACL,KAAK;QACL,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI;QAC5B,KAAK,EAAE,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC;QAC1C,wEAAwE;QACxE,uEAAuE;QACvE,qBAAqB;QACrB,OAAO,EAAE,OAAO,CAAC,OAAuD;KACzE,CAAA;AACH,CAAC;AAiCD,MAAM,YAAY,GAAuB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;AAE1D,oGAAoG;AACpG,MAAM,CAAC,MAAM,KAAK,GAAG,GAAgC,EAAE,CAAC,YAAY,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,KAAQ,EACR,MAA4B,EACwB,EAAE;IACtD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CACjB,8DAA8D,CAC/D,CAAA;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED,0EAA0E;AAC1E,MAAM,OAAO,wBAAyB,SAAQ,eAAe;IAClD,QAAQ,CAAQ;IAChB,MAAM,CAAmC;IAElD,YAAY,QAAgB,EAAE,MAAyC;QACrE,KAAK,CACH,eAAe,EACf,2BAA2B,QAAQ,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3F,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAA;QACtC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,UAA0C,EAC1C,KAAc,EACI,EAAE;IACpB,IAAI,UAAU,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAC9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,wBAAwB,CAAC,UAAU,CAAC,IAAI,EAAE;gBAClD,EAAE,OAAO,EAAE,uDAAuD,EAAE;aACrE,CAAC,CAAA;QACJ,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IAClE,IAAI,MAAM,CAAC,MAAM;QACf,MAAM,IAAI,wBAAwB,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IACpE,OAAO,MAAM,CAAC,KAAK,CAAA;AACrB,CAAC,CAAA","sourcesContent":["/**\n * Step definitions.\n *\n * A **step** is an independently-defined unit of possible work on a case: a\n * guard plus a handler (CONTEXT.md). Steps never declare ordering —\n * sequencing is data dependencies between guards. `step()` validates the\n * definition loudly at construction time: a malformed step should fail the\n * deploy, not an evaluation.\n */\n\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport { AffordanceError } from '../errors.js'\nimport type { ConditionMap, Guard, GuardSection } from '../guards/index.js'\nimport { guardEntries } from '../guards/index.js'\nimport type {\n  ErasedStepHandler,\n  ScopedStepHandler,\n  StepHandler,\n} from './handler.js'\nimport type { RetryOptions, RetryPolicy } from './retry.js'\nimport { normalizeRetry } from './retry.js'\nimport type { ScopeDeclaration, ScopedConditionMap } from './scope.js'\nimport { eraseScopedConditionMap } from './scope.js'\n\n/** Options for an unscoped step. */\nexport interface StepOptions<TState, TActor = unknown, TInput = undefined> {\n  /** The step's name — unique within its case type; half of a scoped affordance's identity. */\n  readonly name: string\n  /**\n   * A short human label for the step (\"Issue the funding call\"). Definition\n   * metadata, not identity: journal entries and refusals name the step by\n   * `name`; adapters serialize the title so a client renders steps without\n   * an out-of-band label table.\n   */\n  readonly title?: string\n  /**\n   * A sentence on what the step does and when to take it — what makes the\n   * affordance contract a usable tool list for a caller (an agent included)\n   * that has never seen this case type.\n   */\n  readonly description?: string\n  /** Case conditions: when one fails the step is not possible on this case, for anyone. */\n  readonly requires?: ConditionMap<TState, TActor>\n  /** Actor conditions: when one fails the step is possible but not permitted for this actor. */\n  readonly permits?: ConditionMap<TState, TActor>\n  /**\n   * Optional input schema (any Standard Schema — zod v4 qualifies). Validated\n   * by `validateStepInput` before the handler runs.\n   */\n  readonly input?: StandardSchemaV1<unknown, TInput>\n  /**\n   * How many times a failed attempt is retried, and how long between\n   * attempts. Defaults to three attempts with exponential backoff; set\n   * `{ maxAttempts: 1 }` to disable retry for this step.\n   */\n  readonly retry?: RetryOptions\n  /** The step's effect function — the only thing that mutates Case State. */\n  readonly handler: StepHandler<TState, TActor, TInput>\n}\n\n/** Options for a scoped step: an unscoped step plus the scope declaration. */\nexport interface ScopedStepOptions<\n  TState,\n  TElement,\n  TActor = unknown,\n  TInput = undefined,\n> {\n  readonly name: string\n  readonly title?: string\n  readonly description?: string\n  /** The collection the step ranges over and how each element is identified. */\n  readonly scope: ScopeDeclaration<TState, TElement>\n  readonly requires?: ScopedConditionMap<TState, TElement, TActor>\n  readonly permits?: ScopedConditionMap<TState, TElement, TActor>\n  readonly input?: StandardSchemaV1<unknown, TInput>\n  readonly retry?: RetryOptions\n  readonly handler: ScopedStepHandler<TState, TElement, TActor, TInput>\n}\n\n/**\n * A step definition as held by a case type and consumed by the engine — the\n * authoring generics (scope element, input) erased to the case-state level.\n * The options types above carry the precise authoring shapes; this is the\n * machine-facing normal form.\n */\nexport interface StepDefinition<TState, TActor = unknown> {\n  readonly name: string\n  /** The declared human label, or `null` — clients fall back to `name`. */\n  readonly title: string | null\n  /** The declared what-and-when sentence, or `null`. */\n  readonly description: string | null\n  /**\n   * The step's guard in the guards module's shape, ready for `evaluateGuard`.\n   * For a scoped step the engine evaluates it once per selected element with\n   * the element bound as `scope`.\n   */\n  readonly guard: Guard<TState, TActor>\n  /** The scope declaration (element type erased), or `null` for an unscoped step. */\n  readonly scope: {\n    readonly select: (state: TState) => readonly unknown[]\n    readonly key: (element: unknown) => string\n  } | null\n  /** The declared input schema, or `null` when the step takes no input. */\n  readonly input: StandardSchemaV1 | null\n  /** The normalized retry policy the execution lifecycle applies to this step. */\n  readonly retry: RetryPolicy\n  /** The step's handler — invoked only by the execution lifecycle. */\n  readonly handler: ErasedStepHandler<TState, TActor>\n}\n\n/**\n * A step's declared human metadata, as `Engine.stepMetadataFor` answers it —\n * the serializable slice of a {@link StepDefinition} an adapter puts on the\n * wire.\n */\nexport interface StepMetadata {\n  readonly title: string | null\n  readonly description: string | null\n}\n\n/** Whether a value is a Standard-Schema instance — the one spelling of the check. */\nexport const isStandardSchema = (value: unknown): value is StandardSchemaV1 =>\n  typeof value === 'object' &&\n  value !== null &&\n  typeof (value as { '~standard'?: unknown })['~standard'] === 'object'\n\n/**\n * Whether a value is plausibly a {@link StepDefinition} — the structural\n * check `caseType()` applies to every step it is given.\n */\nexport const looksLikeStepDefinition = (\n  value: unknown,\n): value is StepDefinition<unknown, unknown> =>\n  typeof value === 'object' &&\n  value !== null &&\n  typeof (value as { name?: unknown }).name === 'string' &&\n  typeof (value as { handler?: unknown }).handler === 'function' &&\n  typeof (value as { guard?: unknown }).guard === 'object'\n\n/**\n * Validate one guard section map at definition time: every entry must be a\n * condition function or an `anyOf(...)` group\n * (unscoped only — scoped maps admit conditions alone).\n *\n * The classification and the `requires.escrowReady` addressing both come from\n * `guardEntries`, so what a definition is allowed to contain is decided\n * against the same walk evaluation uses — a definition `step()` accepts is\n * one `evaluateGuard` can read.\n */\nconst validateConditionMap = (\n  stepName: string,\n  section: GuardSection,\n  map: Readonly<Record<string, unknown>> | undefined,\n  allowAnyOf: boolean,\n): void => {\n  if (map === undefined) return\n  if (typeof map !== 'object' || map === null || Array.isArray(map)) {\n    throw new TypeError(\n      `step '${stepName}': ${section} must be a plain object of named conditions`,\n    )\n  }\n  const section_ = { [section]: map } as Guard<unknown, unknown>\n  for (const entry of guardEntries(section_)) {\n    if (entry.kind === 'condition') continue\n    if (entry.kind === 'anyOf' && allowAnyOf) continue\n    const allowed = allowAnyOf\n      ? 'a condition function or an anyOf(...) group'\n      : 'a condition function (anyOf is not part of the scoped guard surface)'\n    throw new TypeError(\n      `step '${stepName}': ${entry.address} must be ${allowed}`,\n    )\n  }\n}\n\nconst validateCommon = (options: {\n  name: unknown\n  title?: unknown\n  description?: unknown\n  input?: unknown\n  handler: unknown\n}): string => {\n  const { name } = options\n  if (typeof name !== 'string' || name.trim() === '') {\n    throw new TypeError('step: name must be a non-empty string')\n  }\n  if (typeof options.handler !== 'function') {\n    throw new TypeError(`step '${name}': handler must be an async function`)\n  }\n  if (options.input !== undefined && !isStandardSchema(options.input)) {\n    throw new TypeError(\n      `step '${name}': input must be a Standard Schema (e.g. a zod schema)`,\n    )\n  }\n  for (const field of ['title', 'description'] as const) {\n    const value = options[field]\n    if (\n      value !== undefined &&\n      (typeof value !== 'string' || value.trim() === '')\n    ) {\n      throw new TypeError(\n        `step '${name}': ${field} must be a non-empty string when given`,\n      )\n    }\n  }\n  return name\n}\n\n/**\n * Define a step. Two shapes, discriminated by the presence of `scope`:\n *\n * ```ts\n * // Standalone form (internal — apps author through {@link stepsOf}, which\n * // binds the generics once and takes the same options annotation-free):\n * // type parameters are inferred from annotations in the options — annotate\n * // the state parameter of a condition (and the actor on a permits ctx).\n * step({\n *   name: 'issue-funding-call',\n *   requires: { escrowReady: (s: Purchase) => s.escrow?.status === 'open' },\n *   permits: { isOrganizer: (_s: Purchase, ctx: ConditionContext<Ops>) => ctx.actor.roles.includes('organizer') },\n *   handler: async (s, ctx) => s,\n * })\n *\n * // Scoped, standalone form: annotating scope.select anchors both the state\n * // and element types; conditions then read the bound element as ctx.scope,\n * // fully typed (through stepsOf, even the select annotation goes away):\n * step({\n *   name: 'escalate-verification',\n *   scope: { select: (s: Purchase) => s.buyers.filter(b => b.verification?.status === 'review'), key: b => b.id },\n *   requires: { flagged: (s: Purchase, ctx) => (ctx.scope as Buyer).verification?.flaggedAt != null },\n *   handler: async (s, ctx) => s,\n * })\n * ```\n *\n * Validates loudly at construction time — malformed guard entries, a\n * malformed scope declaration, a non-function handler, or a non-schema\n * `input` all throw `TypeError` (definition-time validation; a definition\n * bug should fail the deploy, not an evaluation).\n *\n * The scoped overload is declared first: type parameters are meant to be\n * inferred, and inference resolves each call shape against its own overload\n * (explicit type-argument lists interact badly with overloaded\n * context-sensitive options — annotate inside the options instead).\n */\nexport function step<TState, TElement, TActor = unknown, TInput = undefined>(\n  options: ScopedStepOptions<TState, TElement, TActor, TInput>,\n): StepDefinition<TState, TActor>\nexport function step<TState, TActor = unknown, TInput = undefined>(\n  options: StepOptions<TState, TActor, TInput>,\n): StepDefinition<TState, TActor>\nexport function step<TState, TActor>(\n  options:\n    | StepOptions<TState, TActor, unknown>\n    | ScopedStepOptions<TState, unknown, TActor, unknown>,\n): StepDefinition<TState, TActor> {\n  const name = validateCommon(options)\n  const scoped = 'scope' in options && options.scope !== undefined\n  let scope: StepDefinition<TState, TActor>['scope'] = null\n  let guard: Guard<TState, TActor>\n\n  if (scoped) {\n    const declaration = (\n      options as ScopedStepOptions<TState, unknown, TActor, unknown>\n    ).scope\n    if (\n      typeof declaration !== 'object' ||\n      declaration === null ||\n      typeof declaration.select !== 'function' ||\n      typeof declaration.key !== 'function'\n    ) {\n      throw new TypeError(\n        `step '${name}': scope must be { select: state => elements, key: element => string }`,\n      )\n    }\n    validateConditionMap(name, 'requires', options.requires, false)\n    validateConditionMap(name, 'permits', options.permits, false)\n    scope = { select: declaration.select, key: declaration.key }\n    // Erasure, not conversion: scoped maps are runtime-identical to unscoped\n    // ones; evaluation binds the scope element the scoped types promise.\n    const scopedOptions = options as ScopedStepOptions<\n      TState,\n      unknown,\n      TActor,\n      unknown\n    >\n    guard = {\n      ...(scopedOptions.requires !== undefined && {\n        requires: eraseScopedConditionMap(scopedOptions.requires),\n      }),\n      ...(scopedOptions.permits !== undefined && {\n        permits: eraseScopedConditionMap(scopedOptions.permits),\n      }),\n    }\n  } else {\n    const unscoped = options as StepOptions<TState, TActor, unknown>\n    validateConditionMap(name, 'requires', unscoped.requires, true)\n    validateConditionMap(name, 'permits', unscoped.permits, true)\n    guard = {\n      ...(unscoped.requires !== undefined && { requires: unscoped.requires }),\n      ...(unscoped.permits !== undefined && { permits: unscoped.permits }),\n    }\n  }\n\n  return {\n    name,\n    title: options.title ?? null,\n    description: options.description ?? null,\n    guard,\n    scope,\n    input: options.input ?? null,\n    retry: normalizeRetry(name, options.retry),\n    // The one erasure cast for handlers: the authored context (typed input,\n    // typed scope element) is what the execution lifecycle constructs; see\n    // ErasedStepHandler.\n    handler: options.handler as unknown as ErasedStepHandler<TState, TActor>,\n  }\n}\n\n/**\n * The `step()` authoring surface with the case's state and actor types fixed.\n *\n * Same two call shapes as `step()` — scoped first, discriminated by the\n * presence of `scope` — but `TState`/`TActor` are already substituted, so\n * only the per-step generics (scope element, input) remain to be inferred.\n * That is what makes annotation-free authoring work: conditions and handlers\n * no longer participate in inferring the state type, they just receive it\n * contextually, and a scoped step's element type anchors on `scope.select`\n * alone (so `ctx.scope` is the element, with no `undefined` to narrow away).\n */\nexport interface BoundStep<TState, TActor = unknown> {\n  <TElement, TInput = undefined>(\n    options: ScopedStepOptions<TState, TElement, TActor, TInput>,\n  ): StepDefinition<TState, TActor>\n  <TInput = undefined>(\n    options: StepOptions<TState, TActor, TInput>,\n  ): StepDefinition<TState, TActor>\n}\n\n/**\n * A value-level carrier for `stepsOf`'s actor type — nothing but the type.\n * Exists because `TActor` has no value to be inferred from (a case's actor\n * shape is app-defined and never materializes at definition time), and\n * spelling it as a type argument would force spelling the schema's type too\n * (TypeScript has no partial type-argument inference).\n */\nexport interface ActorMarker<TActor> {\n  readonly __actor?: TActor\n}\n\nconst ACTOR_MARKER: ActorMarker<never> = Object.freeze({})\n\n/** Name the actor type of a `stepsOf` factory: `stepsOf(PurchaseState, actor<PurchaseActor>())`. */\nexport const actor = <TActor>(): ActorMarker<TActor> => ACTOR_MARKER\n\n/**\n * Bind `step()` to a case's state schema — the schema-anchored authoring\n * factory.\n *\n * ```ts\n * const purchaseStep = stepsOf(PurchaseState, actor<PurchaseActor>())\n *\n * purchaseStep({\n *   name: 'issue-funding-call',\n *   requires: { escrowReady: s => s.escrow.status === 'open' },        // s: inferred from the schema\n *   permits:  { isOrganizer: (_s, ctx) => hasRole(ctx.actor, 'organizer') },\n *   handler: async s => s,\n * })\n *\n * purchaseStep({\n *   name: 'escalate-verification',\n *   scope: { select: s => s.buyers.filter(b => b.verification.status === 'review'), key: b => b.id },\n *   requires: { flagged: (_s, ctx) => ctx.scope.verification.flaggedAt !== null },  // ctx.scope: Buyer\n *   handler: async s => s,\n * })\n * ```\n *\n * The state type is derived from the schema *value* — the same\n * `InferOutput` derivation `caseType` performs — so the factory and the case\n * type are anchored to one declaration and cannot drift apart: the state a\n * condition sees is definitionally the state the engine validates against.\n * The per-condition annotations the bare `step()` needs\n * (`(s: Purchase) => …`) disappear, because `TState` is no longer inferred\n * from the options.\n *\n * The second argument exists only to name the actor type and carries no\n * runtime information; omit it for an untyped actor. Define one factory per\n * case type module, next to the schema, and author every step of that case\n * type through it.\n *\n * Returns `step` itself, re-typed — a step authored through the factory is\n * bit-for-bit an ordinary step definition. `step` is deliberately not part\n * of the package barrel: this factory is the public authoring surface, and\n * a helper that builds steps generically should accept a\n * {@link BoundStep} rather than reach for the unbound `step`.\n * Throws at definition time when `state` is not a Standard Schema, like\n * every other malformed-definition case in this module.\n */\nexport const stepsOf = <S extends StandardSchemaV1, TActor = unknown>(\n  state: S,\n  _actor?: ActorMarker<TActor>,\n): BoundStep<StandardSchemaV1.InferOutput<S>, TActor> => {\n  if (!isStandardSchema(state)) {\n    throw new TypeError(\n      'stepsOf: state must be a Standard Schema (e.g. a zod schema)',\n    )\n  }\n  return step\n}\n\n/** A step's declared input failed validation against its input schema. */\nexport class StepInputValidationError extends AffordanceError {\n  readonly stepName: string\n  readonly issues: readonly StandardSchemaV1.Issue[]\n\n  constructor(stepName: string, issues: readonly StandardSchemaV1.Issue[]) {\n    super(\n      'invalid-input',\n      `invalid input for step '${stepName}': ${issues.map((issue) => issue.message).join('; ')}`,\n    )\n    this.name = 'StepInputValidationError'\n    this.stepName = stepName\n    this.issues = issues\n  }\n}\n\n/**\n * Validate a step's input against its declared input schema — the validation\n * plumbing the execution lifecycle runs before invoking the handler (\"validated before the\n * handler runs\"). Returns the schema *output* (defaults applied). A step\n * without an input schema accepts only `undefined` and yields `undefined`;\n * anything else is a caller bug and throws.\n */\nexport const validateStepInput = async <TState, TActor>(\n  definition: StepDefinition<TState, TActor>,\n  input: unknown,\n): Promise<unknown> => {\n  if (definition.input === null) {\n    if (input !== undefined) {\n      throw new StepInputValidationError(definition.name, [\n        { message: 'step declares no input schema, but input was provided' },\n      ])\n    }\n    return undefined\n  }\n  const result = await definition.input['~standard'].validate(input)\n  if (result.issues)\n    throw new StepInputValidationError(definition.name, result.issues)\n  return result.value\n}\n"]}
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/model/step.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Step definitions.\n *\n * A **step** is an independently-defined unit of possible work on a case: a\n * guard plus a handler (CONTEXT.md). Steps never declare ordering —\n * sequencing is data dependencies between guards. `step()` validates the\n * definition loudly at construction time: a malformed step should fail the\n * deploy, not an evaluation.\n */\n\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport { AffordanceError } from '../errors.js'\nimport type { ConditionMap, Guard, GuardSection } from '../guards/index.js'\nimport { guardEntries } from '../guards/index.js'\nimport type {\n  ErasedStepHandler,\n  ScopedStepHandler,\n  StepHandler,\n} from './handler.js'\nimport type { RetryOptions, RetryPolicy } from './retry.js'\nimport { normalizeRetry } from './retry.js'\nimport type { ScopeDeclaration, ScopedConditionMap } from './scope.js'\nimport { eraseScopedConditionMap } from './scope.js'\n\n/** Options for an unscoped step. */\nexport interface StepOptions<\n  TState,\n  TActor = unknown,\n  TInput = undefined,\n  TCommit = unknown,\n> {\n  /** The step's name — unique within its case type; half of a scoped affordance's identity. */\n  readonly name: string\n  /**\n   * A short human label for the step (\"Issue the funding call\"). Definition\n   * metadata, not identity: journal entries and refusals name the step by\n   * `name`; adapters serialize the title so a client renders steps without\n   * an out-of-band label table.\n   */\n  readonly title?: string\n  /**\n   * A sentence on what the step does and when to take it — what makes the\n   * affordance contract a usable tool list for a caller (an agent included)\n   * that has never seen this case type.\n   */\n  readonly description?: string\n  /** Case conditions: when one fails the step is not possible on this case, for anyone. */\n  readonly requires?: ConditionMap<TState, TActor>\n  /** Actor conditions: when one fails the step is possible but not permitted for this actor. */\n  readonly permits?: ConditionMap<TState, TActor>\n  /**\n   * Optional input schema (any Standard Schema — zod v4 qualifies). Validated\n   * by `validateStepInput` before the handler runs.\n   */\n  readonly input?: StandardSchemaV1<unknown, TInput>\n  /**\n   * How many times a failed attempt is retried, and how long between\n   * attempts. Defaults to three attempts with exponential backoff; set\n   * `{ maxAttempts: 1 }` to disable retry for this step.\n   */\n  readonly retry?: RetryOptions\n  /** The step's effect function — the only thing that mutates Case State. */\n  readonly handler: StepHandler<TState, TActor, TInput, TCommit>\n}\n\n/** Options for a scoped step: an unscoped step plus the scope declaration. */\nexport interface ScopedStepOptions<\n  TState,\n  TElement,\n  TActor = unknown,\n  TInput = undefined,\n  TCommit = unknown,\n> {\n  readonly name: string\n  readonly title?: string\n  readonly description?: string\n  /** The collection the step ranges over and how each element is identified. */\n  readonly scope: ScopeDeclaration<TState, TElement>\n  readonly requires?: ScopedConditionMap<TState, TElement, TActor>\n  readonly permits?: ScopedConditionMap<TState, TElement, TActor>\n  readonly input?: StandardSchemaV1<unknown, TInput>\n  readonly retry?: RetryOptions\n  readonly handler: ScopedStepHandler<TState, TElement, TActor, TInput, TCommit>\n}\n\n/**\n * A step definition as held by a case type and consumed by the engine — the\n * authoring generics (scope element, input) erased to the case-state level.\n * The options types above carry the precise authoring shapes; this is the\n * machine-facing normal form.\n */\nexport interface StepDefinition<TState, TActor = unknown, TCommit = unknown> {\n  readonly name: string\n  /** The declared human label, or `null` — clients fall back to `name`. */\n  readonly title: string | null\n  /** The declared what-and-when sentence, or `null`. */\n  readonly description: string | null\n  /**\n   * The step's guard in the guards module's shape, ready for `evaluateGuard`.\n   * For a scoped step the engine evaluates it once per selected element with\n   * the element bound as `scope`.\n   */\n  readonly guard: Guard<TState, TActor>\n  /** The scope declaration (element type erased), or `null` for an unscoped step. */\n  readonly scope: {\n    readonly select: (state: TState) => readonly unknown[]\n    readonly key: (element: unknown) => string\n  } | null\n  /** The declared input schema, or `null` when the step takes no input. */\n  readonly input: StandardSchemaV1 | null\n  /** The normalized retry policy the execution lifecycle applies to this step. */\n  readonly retry: RetryPolicy\n  /** The step's handler — invoked only by the execution lifecycle. */\n  readonly handler: ErasedStepHandler<TState, TActor, TCommit>\n}\n\n/**\n * A step's declared human metadata, as `Engine.stepMetadataFor` answers it —\n * the serializable slice of a {@link StepDefinition} an adapter puts on the\n * wire.\n */\nexport interface StepMetadata {\n  readonly title: string | null\n  readonly description: string | null\n}\n\n/** Whether a value is a Standard-Schema instance — the one spelling of the check. */\nexport const isStandardSchema = (value: unknown): value is StandardSchemaV1 =>\n  typeof value === 'object' &&\n  value !== null &&\n  typeof (value as { '~standard'?: unknown })['~standard'] === 'object'\n\n/**\n * Whether a value is plausibly a {@link StepDefinition} — the structural\n * check `caseType()` applies to every step it is given.\n */\nexport const looksLikeStepDefinition = (\n  value: unknown,\n): value is StepDefinition<unknown, unknown> =>\n  typeof value === 'object' &&\n  value !== null &&\n  typeof (value as { name?: unknown }).name === 'string' &&\n  typeof (value as { handler?: unknown }).handler === 'function' &&\n  typeof (value as { guard?: unknown }).guard === 'object'\n\n/**\n * Validate one guard section map at definition time: every entry must be a\n * condition function or an `anyOf(...)` group\n * (unscoped only — scoped maps admit conditions alone).\n *\n * The classification and the `requires.escrowReady` addressing both come from\n * `guardEntries`, so what a definition is allowed to contain is decided\n * against the same walk evaluation uses — a definition `step()` accepts is\n * one `evaluateGuard` can read.\n */\nconst validateConditionMap = (\n  stepName: string,\n  section: GuardSection,\n  map: Readonly<Record<string, unknown>> | undefined,\n  allowAnyOf: boolean,\n): void => {\n  if (map === undefined) return\n  if (typeof map !== 'object' || map === null || Array.isArray(map)) {\n    throw new TypeError(\n      `step '${stepName}': ${section} must be a plain object of named conditions`,\n    )\n  }\n  const section_ = { [section]: map } as Guard<unknown, unknown>\n  for (const entry of guardEntries(section_)) {\n    if (entry.kind === 'condition') continue\n    if (entry.kind === 'anyOf' && allowAnyOf) continue\n    const allowed = allowAnyOf\n      ? 'a condition function or an anyOf(...) group'\n      : 'a condition function (anyOf is not part of the scoped guard surface)'\n    throw new TypeError(\n      `step '${stepName}': ${entry.address} must be ${allowed}`,\n    )\n  }\n}\n\nconst validateCommon = (options: {\n  name: unknown\n  title?: unknown\n  description?: unknown\n  input?: unknown\n  handler: unknown\n}): string => {\n  const { name } = options\n  if (typeof name !== 'string' || name.trim() === '') {\n    throw new TypeError('step: name must be a non-empty string')\n  }\n  if (typeof options.handler !== 'function') {\n    throw new TypeError(`step '${name}': handler must be an async function`)\n  }\n  if (options.input !== undefined && !isStandardSchema(options.input)) {\n    throw new TypeError(\n      `step '${name}': input must be a Standard Schema (e.g. a zod schema)`,\n    )\n  }\n  for (const field of ['title', 'description'] as const) {\n    const value = options[field]\n    if (\n      value !== undefined &&\n      (typeof value !== 'string' || value.trim() === '')\n    ) {\n      throw new TypeError(\n        `step '${name}': ${field} must be a non-empty string when given`,\n      )\n    }\n  }\n  return name\n}\n\n/**\n * Define a step. Two shapes, discriminated by the presence of `scope`:\n *\n * ```ts\n * // Standalone form (internal — apps author through {@link stepsOf}, which\n * // binds the generics once and takes the same options annotation-free):\n * // type parameters are inferred from annotations in the options — annotate\n * // the state parameter of a condition (and the actor on a permits ctx).\n * step({\n *   name: 'issue-funding-call',\n *   requires: { escrowReady: (s: Purchase) => s.escrow?.status === 'open' },\n *   permits: { isOrganizer: (_s: Purchase, ctx: ConditionContext<Ops>) => ctx.actor.roles.includes('organizer') },\n *   handler: async (s, ctx) => s,\n * })\n *\n * // Scoped, standalone form: annotating scope.select anchors both the state\n * // and element types; conditions then read the bound element as ctx.scope,\n * // fully typed (through stepsOf, even the select annotation goes away):\n * step({\n *   name: 'escalate-verification',\n *   scope: { select: (s: Purchase) => s.buyers.filter(b => b.verification?.status === 'review'), key: b => b.id },\n *   requires: { flagged: (s: Purchase, ctx) => (ctx.scope as Buyer).verification?.flaggedAt != null },\n *   handler: async (s, ctx) => s,\n * })\n * ```\n *\n * Validates loudly at construction time — malformed guard entries, a\n * malformed scope declaration, a non-function handler, or a non-schema\n * `input` all throw `TypeError` (definition-time validation; a definition\n * bug should fail the deploy, not an evaluation).\n *\n * The scoped overload is declared first: type parameters are meant to be\n * inferred, and inference resolves each call shape against its own overload\n * (explicit type-argument lists interact badly with overloaded\n * context-sensitive options — annotate inside the options instead).\n */\nexport function step<\n  TState,\n  TElement,\n  TActor = unknown,\n  TInput = undefined,\n  TCommit = unknown,\n>(\n  options: ScopedStepOptions<TState, TElement, TActor, TInput, TCommit>,\n): StepDefinition<TState, TActor, TCommit>\nexport function step<\n  TState,\n  TActor = unknown,\n  TInput = undefined,\n  TCommit = unknown,\n>(\n  options: StepOptions<TState, TActor, TInput, TCommit>,\n): StepDefinition<TState, TActor, TCommit>\nexport function step<TState, TActor, TCommit>(\n  options:\n    | StepOptions<TState, TActor, unknown, TCommit>\n    | ScopedStepOptions<TState, unknown, TActor, unknown, TCommit>,\n): StepDefinition<TState, TActor, TCommit> {\n  const name = validateCommon(options)\n  const scoped = 'scope' in options && options.scope !== undefined\n  let scope: StepDefinition<TState, TActor, TCommit>['scope'] = null\n  let guard: Guard<TState, TActor>\n\n  if (scoped) {\n    const declaration = (\n      options as ScopedStepOptions<TState, unknown, TActor, unknown, TCommit>\n    ).scope\n    if (\n      typeof declaration !== 'object' ||\n      declaration === null ||\n      typeof declaration.select !== 'function' ||\n      typeof declaration.key !== 'function'\n    ) {\n      throw new TypeError(\n        `step '${name}': scope must be { select: state => elements, key: element => string }`,\n      )\n    }\n    validateConditionMap(name, 'requires', options.requires, false)\n    validateConditionMap(name, 'permits', options.permits, false)\n    scope = { select: declaration.select, key: declaration.key }\n    // Erasure, not conversion: scoped maps are runtime-identical to unscoped\n    // ones; evaluation binds the scope element the scoped types promise.\n    const scopedOptions = options as ScopedStepOptions<\n      TState,\n      unknown,\n      TActor,\n      unknown,\n      TCommit\n    >\n    guard = {\n      ...(scopedOptions.requires !== undefined && {\n        requires: eraseScopedConditionMap(scopedOptions.requires),\n      }),\n      ...(scopedOptions.permits !== undefined && {\n        permits: eraseScopedConditionMap(scopedOptions.permits),\n      }),\n    }\n  } else {\n    const unscoped = options as StepOptions<TState, TActor, unknown, TCommit>\n    validateConditionMap(name, 'requires', unscoped.requires, true)\n    validateConditionMap(name, 'permits', unscoped.permits, true)\n    guard = {\n      ...(unscoped.requires !== undefined && { requires: unscoped.requires }),\n      ...(unscoped.permits !== undefined && { permits: unscoped.permits }),\n    }\n  }\n\n  return {\n    name,\n    title: options.title ?? null,\n    description: options.description ?? null,\n    guard,\n    scope,\n    input: options.input ?? null,\n    retry: normalizeRetry(name, options.retry),\n    // The one erasure cast for handlers: the authored context (typed input,\n    // typed scope element) is what the execution lifecycle constructs; see\n    // ErasedStepHandler.\n    handler: options.handler as unknown as ErasedStepHandler<\n      TState,\n      TActor,\n      TCommit\n    >,\n  }\n}\n\n/**\n * The `step()` authoring surface with the case's state and actor types fixed.\n *\n * Same two call shapes as `step()` — scoped first, discriminated by the\n * presence of `scope` — but `TState`/`TActor` are already substituted, so\n * only the per-step generics (scope element, input) remain to be inferred.\n * That is what makes annotation-free authoring work: conditions and handlers\n * no longer participate in inferring the state type, they just receive it\n * contextually, and a scoped step's element type anchors on `scope.select`\n * alone (so `ctx.scope` is the element, with no `undefined` to narrow away).\n */\nexport interface BoundStep<TState, TActor = unknown, TCommit = unknown> {\n  <TElement, TInput = undefined>(\n    options: ScopedStepOptions<TState, TElement, TActor, TInput, TCommit>,\n  ): StepDefinition<TState, TActor, TCommit>\n  <TInput = undefined>(\n    options: StepOptions<TState, TActor, TInput, TCommit>,\n  ): StepDefinition<TState, TActor, TCommit>\n}\n\n/**\n * A value-level carrier for `stepsOf`'s actor type — nothing but the type.\n * Exists because `TActor` has no value to be inferred from (a case's actor\n * shape is app-defined and never materializes at definition time), and\n * spelling it as a type argument would force spelling the schema's type too\n * (TypeScript has no partial type-argument inference).\n */\nexport interface ActorMarker<TActor> {\n  readonly __actor?: TActor\n}\n\nconst ACTOR_MARKER: ActorMarker<never> = Object.freeze({})\n\n/** Name the actor type of a `stepsOf` factory: `stepsOf(PurchaseState, actor<PurchaseActor>())`. */\nexport const actor = <TActor>(): ActorMarker<TActor> => ACTOR_MARKER\n\n/**\n * Bind `step()` to a case's state schema — the schema-anchored authoring\n * factory.\n *\n * ```ts\n * const purchaseStep = stepsOf(PurchaseState, actor<PurchaseActor>())\n *\n * purchaseStep({\n *   name: 'issue-funding-call',\n *   requires: { escrowReady: s => s.escrow.status === 'open' },        // s: inferred from the schema\n *   permits:  { isOrganizer: (_s, ctx) => hasRole(ctx.actor, 'organizer') },\n *   handler: async s => s,\n * })\n *\n * purchaseStep({\n *   name: 'escalate-verification',\n *   scope: { select: s => s.buyers.filter(b => b.verification.status === 'review'), key: b => b.id },\n *   requires: { flagged: (_s, ctx) => ctx.scope.verification.flaggedAt !== null },  // ctx.scope: Buyer\n *   handler: async s => s,\n * })\n * ```\n *\n * The state type is derived from the schema *value* — the same\n * `InferOutput` derivation `caseType` performs — so the factory and the case\n * type are anchored to one declaration and cannot drift apart: the state a\n * condition sees is definitionally the state the engine validates against.\n * The per-condition annotations the bare `step()` needs\n * (`(s: Purchase) => …`) disappear, because `TState` is no longer inferred\n * from the options.\n *\n * The second argument exists only to name the actor type and carries no\n * runtime information; omit it for an untyped actor. Define one factory per\n * case type module, next to the schema, and author every step of that case\n * type through it.\n *\n * Returns `step` itself, re-typed — a step authored through the factory is\n * bit-for-bit an ordinary step definition. `step` is deliberately not part\n * of the package barrel: this factory is the public authoring surface, and\n * a helper that builds steps generically should accept a\n * {@link BoundStep} rather than reach for the unbound `step`.\n * Throws at definition time when `state` is not a Standard Schema, like\n * every other malformed-definition case in this module.\n */\nexport const stepsOf = <\n  S extends StandardSchemaV1,\n  TActor = unknown,\n  TCommit = unknown,\n>(\n  state: S,\n  _actor?: ActorMarker<TActor>,\n  _commit?: CommitContextMarker<TCommit>,\n): BoundStep<StandardSchemaV1.InferOutput<S>, TActor, TCommit> => {\n  if (!isStandardSchema(state)) {\n    throw new TypeError(\n      'stepsOf: state must be a Standard Schema (e.g. a zod schema)',\n    )\n  }\n  return step\n}\n\n/** A step's declared input failed validation against its input schema. */\nexport class StepInputValidationError extends AffordanceError {\n  readonly stepName: string\n  readonly issues: readonly StandardSchemaV1.Issue[]\n\n  constructor(stepName: string, issues: readonly StandardSchemaV1.Issue[]) {\n    super(\n      'invalid-input',\n      `invalid input for step '${stepName}': ${issues.map((issue) => issue.message).join('; ')}`,\n    )\n    this.name = 'StepInputValidationError'\n    this.stepName = stepName\n    this.issues = issues\n  }\n}\n\n/**\n * Validate a step's input against its declared input schema — the validation\n * plumbing the execution lifecycle runs before invoking the handler (\"validated before the\n * handler runs\"). Returns the schema *output* (defaults applied). A step\n * without an input schema accepts only `undefined` and yields `undefined`;\n * anything else is a caller bug and throws.\n */\nexport const validateStepInput = async <TState, TActor, TCommit>(\n  definition: StepDefinition<TState, TActor, TCommit>,\n  input: unknown,\n): Promise<unknown> => {\n  if (definition.input === null) {\n    if (input !== undefined) {\n      throw new StepInputValidationError(definition.name, [\n        { message: 'step declares no input schema, but input was provided' },\n      ])\n    }\n    return undefined\n  }\n  const result = await definition.input['~standard'].validate(input)\n  if (result.issues)\n    throw new StepInputValidationError(definition.name, result.issues)\n  return result.value\n}\n\n/** Name the transaction/repository context supplied to onCommit callbacks. */\nexport interface CommitContextMarker<TCommit> {\n  readonly __commit?: TCommit\n}\nexport const commitContext = <TCommit>(): CommitContextMarker<TCommit> => ({})\n"]}

package/dist/model/target.d.ts

@@ -35,7 +35,6 @@
  * with one deliberate exception — a `defective-selector` failure is
  * *answered*, because the listing published that exact link).
  */
-import { SCOPE_FAILURE_CONDITION } from '@affordance/contract';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { GuardEvaluation, Instant } from '../guards/index.js';
 import type { CaseTypeDefinition } from './casetype.js';
@@ -44,11 +43,9 @@ import type { StepDefinition } from './step.js';
 /**
  * The synthetic condition name under which a throwing or malformed scope
  * selector is reported. `$`-prefixed so it can never collide with an
- * author's condition names. Declared by `@affordance/contract` — it reaches
- * clients through `blocked[].unmet[].name`, so it is wire vocabulary, and
- * the wire owns it; re-exported here for the engine's own consumers.
+ * author's condition names. This is engine guard vocabulary.
  */
-export { SCOPE_FAILURE_CONDITION };
+export declare const SCOPE_FAILURE_CONDITION = "$scope";
 /**
  * A defective selection as a full evaluation record — the
  * possible/permitted/available verdict stated once. The selection failed, so
@@ -80,8 +77,8 @@ export interface ScopeBinding {
  * A step addressed by name (× scope key, if scoped): the step definition and
  * its scope binding, resolved against a given Case State.
  */
-export interface StepTarget<TState, TActor = unknown> {
-    readonly step: StepDefinition<TState, TActor>;
+export interface StepTarget<TState, TActor = unknown, TCommit = unknown> {
+    readonly step: StepDefinition<TState, TActor, TCommit>;
     /**
      * The Case State the target was resolved against — the document its guard
      * is evaluated over. Carried on the target so a binding can never be
@@ -92,8 +89,8 @@ export interface StepTarget<TState, TActor = unknown> {
     readonly binding: ScopeBinding | null;
 }
 /** The outcome of scope fan-out: the step's targets, or why selection produced none. */
-export interface TargetSelection<TState, TActor = unknown> {
-    readonly targets: readonly StepTarget<TState, TActor>[];
+export interface TargetSelection<TState, TActor = unknown, TCommit = unknown> {
+    readonly targets: readonly StepTarget<TState, TActor, TCommit>[];
     /** The selection failure — a defective selector — or `null` when selection succeeded. */
     readonly failure: {
         readonly reason: string;
@@ -109,7 +106,7 @@ export interface TargetSelection<TState, TActor = unknown> {
  * defective. {@link ScopeKeyError} — identity corruption — propagates: it is
  * never a selection failure, and no caller may absorb it into "no targets".
  */
-export declare const selectTargets: <TState, TActor>(step: StepDefinition<TState, TActor>, state: TState) => TargetSelection<TState, TActor>;
+export declare const selectTargets: <TState, TActor, TCommit>(step: StepDefinition<TState, TActor, TCommit>, state: TState) => TargetSelection<TState, TActor, TCommit>;
 /**
  * Why an address does not resolve, by kind. Each failure carries the error
  * the loud filter would throw, so the diagnosis (including the
@@ -140,8 +137,8 @@ export type TargetAddressFailure = {
     readonly error: ScopeKeyError;
 };
 /** The outcome of addressing a step: the target, or the precise failure. */
-export type TargetAddress<TState, TActor = unknown> = {
-    readonly target: StepTarget<TState, TActor>;
+export type TargetAddress<TState, TActor = unknown, TCommit = unknown> = {
+    readonly target: StepTarget<TState, TActor, TCommit>;
     readonly failure: null;
 } | {
     readonly target: null;
@@ -156,7 +153,7 @@ export type TargetAddress<TState, TActor = unknown> = {
  * corruption, from {@link selectScope}) still propagates — no filter may
  * absorb it.
  */
-export declare const addressTarget: <S extends StandardSchemaV1, TActor>(definition: CaseTypeDefinition<S, TActor>, state: StandardSchemaV1.InferOutput<S>, stepName: string, scopeKey?: string) => TargetAddress<StandardSchemaV1.InferOutput<S>, TActor>;
+export declare const addressTarget: <S extends StandardSchemaV1, TActor, TCommit>(definition: CaseTypeDefinition<S, TActor, TCommit>, state: StandardSchemaV1.InferOutput<S>, stepName: string, scopeKey?: string) => TargetAddress<StandardSchemaV1.InferOutput<S>, TActor, TCommit>;
 /**
  * Resolve "step X (of element K) on this state" — the addressing shared by
  * `explain` (a targeted probe) and the execution lifecycle's claim.
@@ -166,10 +163,10 @@ export declare const addressTarget: <S extends StandardSchemaV1, TActor>(definit
  * failing to address throws with its precise message. Addressing a step you
  * cannot name is a caller bug, not a blocked affordance.
  */
-export declare const resolveTarget: <S extends StandardSchemaV1, TActor>(definition: CaseTypeDefinition<S, TActor>, state: StandardSchemaV1.InferOutput<S>, stepName: string, scopeKey?: string) => StepTarget<StandardSchemaV1.InferOutput<S>, TActor>;
+export declare const resolveTarget: <S extends StandardSchemaV1, TActor, TCommit>(definition: CaseTypeDefinition<S, TActor, TCommit>, state: StandardSchemaV1.InferOutput<S>, stepName: string, scopeKey?: string) => StepTarget<StandardSchemaV1.InferOutput<S>, TActor, TCommit>;
 /**
  * Evaluate one addressed step's guard against the state it was resolved on —
  * the single evaluation shared by `explain` and the claim, so the enforcement
  * moment and the explanation of it can never drift apart.
  */
-export declare const evaluateTarget: <TState, TActor>(target: StepTarget<TState, TActor>, ctx: ComputationContext<TActor>) => GuardEvaluation;
+export declare const evaluateTarget: <TState, TActor, TCommit>(target: StepTarget<TState, TActor, TCommit>, ctx: ComputationContext<TActor>) => GuardEvaluation;

package/dist/model/target.js

@@ -35,18 +35,15 @@
  * with one deliberate exception — a `defective-selector` failure is
  * *answered*, because the listing published that exact link).
  */
-import { SCOPE_FAILURE_CONDITION } from '@affordance/contract';
 import { thrownMessage } from '../errors.js';
 import { evaluateGuard } from '../guards/index.js';
 import { ScopeKeyError, UnknownStepError } from './errors.js';
 /**
  * The synthetic condition name under which a throwing or malformed scope
  * selector is reported. `$`-prefixed so it can never collide with an
- * author's condition names. Declared by `@affordance/contract` — it reaches
- * clients through `blocked[].unmet[].name`, so it is wire vocabulary, and
- * the wire owns it; re-exported here for the engine's own consumers.
+ * author's condition names. This is engine guard vocabulary.
  */
-export { SCOPE_FAILURE_CONDITION };
+export const SCOPE_FAILURE_CONDITION = '$scope';
 /**
  * The synthetic `$scope` entry as a condition result — the one spelling of
  * how a failed scope selection reports into an evaluation-shaped record: a