@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/src/engine/steps/_drizzle-boundary.ts

@@ -0,0 +1,19 @@
+// Drizzle-boundary cast helper — drizzle's `db.insert()/select()/delete()`
+// expect a PgTable<...> shape with `enableRLS` (driver-added). The
+// abstract `Table` we accept on step args is missing that method, so
+// TS rejects direct assignment. Runtime is identical — drizzle's
+// builder methods only read the table-name + column-defs, both of
+// which `Table` carries. Cast at the boundary, document it once.
+//
+// Used by read-find-one, read-find-many, unsafe-projection-upsert,
+// unsafe-projection-delete. Followup #13 (closed at the M.1.6
+// cleanup-pass).
+
+import type { Table } from "drizzle-orm";
+
+// biome-ignore lint/suspicious/noExplicitAny: drizzle type-boundary
+type DrizzleQueryTarget = any;
+
+export function asQueryTarget(t: Table): DrizzleQueryTarget {
+  return t;
+}

package/src/engine/steps/_duration-utils.ts

@@ -0,0 +1,33 @@
+// ISO-8601 duration arithmetic — shared by wait and waitForEvent steps.
+// Accepts "P1D", "PT1H", "P1Y2M3DT4H5M6S" etc.
+// Uses approximate calendar math (365d/year, 30d/month). See #23.
+
+export function addDuration(baseIso: string, duration: string): string {
+  const pattern = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/;
+  const match = duration.match(pattern);
+  if (!match) {
+    throw new Error(
+      `Invalid ISO-8601 duration "${duration}" — expected format like "PT1H", "P1D", "P7D"`,
+    );
+  }
+
+  const parts = match.slice(1).map((n) => Number(n) || 0);
+  const years = parts[0] ?? 0;
+  const months = parts[1] ?? 0;
+  const days = parts[2] ?? 0;
+  const hours = parts[3] ?? 0;
+  const minutes = parts[4] ?? 0;
+  const seconds = parts[5] ?? 0;
+
+  // Compute in ms (Temporal.Instant.add accepts only smaller units below
+  // hours for calendar-agnostic shifts; we approximate years/months as
+  // fixed-length days, see file header).
+  let ms = years * 365 * 24 * 60 * 60 * 1000;
+  ms += months * 30 * 24 * 60 * 60 * 1000;
+  ms += days * 24 * 60 * 60 * 1000;
+  ms += hours * 60 * 60 * 1000;
+  ms += minutes * 60 * 1000;
+  ms += seconds * 1000;
+
+  return Temporal.Instant.from(baseIso).add({ milliseconds: ms }).toString();
+}

package/src/engine/steps/_no-return-guard.ts

@@ -0,0 +1,21 @@
+// Build-time guard for Q12 — sub-pipelines (branch.onTrue/onFalse,
+// forEach.do) may not contain r.step.return. Centralised here so the
+// error message is wordlaut-identical across both sub-step-builders;
+// inline duplication would drift the moment someone edits one site.
+//
+// Extracted at the second sub-step-builder rather than the third because
+// the drift-risk on the Q12 wording is real (advisor M.1.6 cleanup), not
+// because the line-count alone justifies it.
+
+import type { StepInstance } from "../types/step";
+
+export function validateNoReturnSteps(steps: readonly StepInstance[], where: string): void {
+  for (const step of steps) {
+    if (step.kind === "return") {
+      throw new Error(
+        `r.step.return is not allowed inside ${where} — branch/forEach are side-effect containers (Q12). ` +
+          `Restructure the pipeline so the return happens at the top level.`,
+      );
+    }
+  }
+}

package/src/engine/steps/_resolver-utils.ts

@@ -0,0 +1,42 @@
+// Resolver-call helpers — eliminate the typeof-narrow boilerplate that
+// was repeated across 11 step files (return, compute, branch, forEach,
+// read.findOne/findMany, aggregate.create/update/appendEvent,
+// unsafeProjectionUpsert/Delete).
+//
+// Pattern before:
+//   const value = typeof args.x === "function" ? args.x(ctx) : args.x;
+//
+// Pattern after:
+//   const value = resolveRequired(args.x, ctx);
+//
+// The local-alias version (`const r = args.x; typeof r === "function" ? ...`)
+// was needed to satisfy TS narrowing on a property-access; passing the
+// arg through a function-call achieves the same narrowing trivially via
+// the function-parameter binding.
+//
+// Followup #10 (closed at the M.1.6 cleanup-pass).
+
+import type { PipelineCtx, StepResolver } from "../types/step";
+
+/**
+ * Resolve a required StepResolver — either a static value or a function.
+ * Throws if `arg` is undefined; caller must guarantee presence.
+ */
+export function resolveRequired<T>(arg: StepResolver<T>, ctx: PipelineCtx): T {
+  if (typeof arg === "function") {
+    return (arg as (c: PipelineCtx) => T)(ctx);
+  }
+  return arg;
+}
+
+/**
+ * Resolve an optional StepResolver — returns undefined when arg is
+ * undefined, otherwise the resolved value.
+ */
+export function resolveOptional<T>(
+  arg: StepResolver<T> | undefined,
+  ctx: PipelineCtx,
+): T | undefined {
+  if (arg === undefined) return undefined;
+  return resolveRequired(arg, ctx);
+}

package/src/engine/steps/_step-dispatch-constants.ts

@@ -0,0 +1,38 @@
+// Shared constants for the deferred-step dispatcher pipeline. Extracted
+// so individual step-builders (webhook.send, mail.send, ...) don't
+// import from each other and silently break on a future split.
+
+export const STEP_DISPATCH_AGGREGATE_TYPE = "step-dispatch";
+// System-event namespace (kumiko:system:*) — bypasses registry +
+// ownership checks in append-event-core. Reserved for framework-internal
+// step-engine coordination. The bundled step-dispatcher MSP listens
+// for the literal type-string.
+export const STEP_DISPATCH_REQUESTED_TYPE = "kumiko:system:step.dispatch-requested";
+export const STEP_DISPATCHED_TYPE = "kumiko:system:step.dispatched";
+export const STEP_DISPATCH_FAILED_TYPE = "kumiko:system:step.dispatch-failed";
+
+// --- Tier-3 / Workflow async step constants ---
+// Written by wait / waitForEvent / retry steps onto the workflow-run stream.
+// The Resume-Loop reads these to decide when to resume a suspended run.
+export const WORKFLOW_WAITING_TYPE = "kumiko:system:workflow.step.waiting";
+export const WORKFLOW_WAITING_FOR_EVENT_TYPE = "kumiko:system:workflow.step.waiting-for-event";
+export const WORKFLOW_RESUMED_TYPE = "kumiko:system:workflow.step.resumed";
+
+// Workflow-run aggregate type — each workflow run is an event-sourced
+// aggregate stream.
+export const WORKFLOW_AGGREGATE_TYPE = "workflow-run";
+
+// Workflow-run lifecycle events — written by the event-trigger subscriber
+// and the resume-loop onto a workflow-run aggregate stream.
+export const WORKFLOW_RUN_STARTED_TYPE = "kumiko:system:workflow.run-started";
+export const WORKFLOW_RUN_COMPLETED_TYPE = "kumiko:system:workflow.run-completed";
+export const WORKFLOW_RUN_FAILED_TYPE = "kumiko:system:workflow.run-failed";
+
+// Step return sentinel — when a step's run() returns this value,
+// runStepList stops and yields a "suspended" outcome. The caller
+// (defineWorkflow / workflow-engine) persists the suspension state.
+export const SUSPEND_SENTINEL = Symbol("kumiko:step:suspend");
+
+// Workflow retry scheduled — written by the retry step when a sub-pipeline
+// fails and a retry attempt is scheduled with backoff.
+export const WORKFLOW_RETRY_SCHEDULED_TYPE = "kumiko:system:workflow.retry.scheduled";

package/src/engine/steps/aggregate-append-event.ts

@@ -0,0 +1,56 @@
+// r.step.aggregate.appendEvent — write an additional domain-event onto
+// an existing aggregate stream.
+//
+// Wraps ctx.unsafeAppendEvent: the event lands on the named aggregate
+// stream in the active TX, downstream projections (multiStreamProjection)
+// fire, audit-trail captures it. Used when a write-handler needs to
+// record a domain event that's NOT one of the auto-generated CRUD
+// events (e.g. "incident.update-posted" on the same incident stream
+// that already carries "incident.created").
+//
+// Why `unsafeAppendEvent` (not the strict `appendEvent`): step.run sees
+// `ctx` as PipelineCtx<unknown, KumikoEventTypeMap> after the variance-
+// bridge cast in run-pipeline.ts. The strict TMap-typed appendEvent
+// would collapse `keyof TMap` to `never` from the framework-side. Strict
+// typing of appendEvent inside steps is a deferred pass (post-M.1.5).
+// At the call-site users still spell `type` as a string-literal — TS
+// catches typos against the QualifiedEventName union when the literal
+// matches a registered EventDef.
+//
+// No result-key — appendEvent doesn't surface a value to subsequent
+// steps (the event-store assigns the position, but consumers don't
+// need it during the same handler call).
+
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { resolveOptional, resolveRequired } from "./_resolver-utils";
+
+type AggregateAppendEventArgs = {
+  readonly aggregateId: StepResolver<string>;
+  readonly aggregateType: string;
+  readonly type: string;
+  readonly payload: StepResolver<unknown>;
+  readonly headers?: StepResolver<Readonly<Record<string, string | number | boolean>>>;
+};
+
+defineStep<AggregateAppendEventArgs, void>({
+  kind: "aggregate.appendEvent",
+  defaultFailureStrategy: "throw",
+  run: async (args, ctx: PipelineCtx) => {
+    const aggregateId = resolveRequired(args.aggregateId, ctx);
+    const payload = resolveRequired(args.payload, ctx);
+    const headers = resolveOptional(args.headers, ctx);
+
+    await ctx.unsafeAppendEvent({
+      aggregateId,
+      aggregateType: args.aggregateType,
+      type: args.type,
+      payload,
+      ...(headers !== undefined && { headers }),
+    });
+  },
+});
+
+export function buildAggregateAppendEventStep(args: AggregateAppendEventArgs): StepInstance {
+  return { kind: "aggregate.appendEvent", args };
+}

package/src/engine/steps/aggregate-create.ts

@@ -0,0 +1,56 @@
+// r.step.aggregate.create — open a new event-sourced aggregate stream.
+//
+// Wraps the existing createEventStoreExecutor.create(): writes the
+// `<entity>.created` event to the aggregate stream + applies the inline
+// projection, both in the active TX. Lifecycle hooks (postSave),
+// field-access write rules, crypto-shredding, audit-trail and the rest
+// of the framework-protections all run because we go through the
+// executor (the canonical aggregate-mutation path).
+//
+// Returns the SaveContext { id, data, changes, previous, isNew, event }
+// — landed under steps.<name> so subsequent steps can read steps.<name>.id.
+//
+// Failure-handling: M.1.1's "throw"-only strategy applies. If the
+// executor returns a WriteFailure, we re-raise as a KumikoError so the
+// dispatcher's catch maps it to the standard write-failure shape on the
+// HTTP response.
+
+import type { EventStoreExecutor } from "../../db/event-store-executor";
+import { reraiseAsKumikoError } from "../../errors/write-error-info";
+import { defineStep } from "../define-step";
+import type { SaveContext } from "../types/hooks";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { resolveRequired } from "./_resolver-utils";
+
+type AggregateCreateArgs = {
+  readonly name: string;
+  readonly executor: EventStoreExecutor;
+  readonly data: StepResolver<Record<string, unknown>>;
+};
+
+defineStep<AggregateCreateArgs, SaveContext>({
+  kind: "aggregate.create",
+  defaultFailureStrategy: "throw",
+  resultKey: (args) => args.name,
+  run: async (args, ctx: PipelineCtx) => {
+    const data = resolveRequired(args.data, ctx);
+    const result = await args.executor.create(data, ctx.event.user, ctx.db);
+    if (!result.isSuccess) {
+      throw reraiseAsKumikoError(result.error);
+    }
+    return result.data;
+  },
+});
+
+export function buildAggregateCreateStep(
+  name: string,
+  opts: {
+    readonly executor: EventStoreExecutor;
+    readonly data: StepResolver<Record<string, unknown>>;
+  },
+): StepInstance {
+  return {
+    kind: "aggregate.create",
+    args: { name, executor: opts.executor, data: opts.data } satisfies AggregateCreateArgs,
+  };
+}

package/src/engine/steps/aggregate-update.ts

@@ -0,0 +1,68 @@
+// r.step.aggregate.update — apply a delta to an existing aggregate stream.
+//
+// Wraps the existing createEventStoreExecutor.update(): writes the
+// `<entity>.updated` event + applies the inline projection in the
+// active TX. Optimistic-locking via the optional `version` field —
+// pipeline-author can supply the loaded version (often via a prior
+// r.step.read.findOne) or skip with skipOptimisticLock.
+//
+// Returns the SaveContext { id, data, changes, previous, isNew, event }
+// — landed under steps.<name>. `changes` and `previous` are useful for
+// hooks/audit consumers; the `id` matches the input id.
+//
+// Failure-handling mirrors aggregate.create: WriteFailure → re-raised
+// as KumikoError → dispatcher catches and maps.
+
+import type { EventStoreExecutor } from "../../db/event-store-executor";
+import { reraiseAsKumikoError } from "../../errors/write-error-info";
+import { defineStep } from "../define-step";
+import type { SaveContext } from "../types/hooks";
+import type { EntityId } from "../types/identifiers";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { resolveOptional, resolveRequired } from "./_resolver-utils";
+
+type AggregateUpdateArgs = {
+  readonly name: string;
+  readonly executor: EventStoreExecutor;
+  readonly id: StepResolver<EntityId>;
+  readonly changes: StepResolver<Record<string, unknown>>;
+  readonly version?: StepResolver<number | undefined>;
+  readonly skipOptimisticLock?: boolean;
+};
+
+defineStep<AggregateUpdateArgs, SaveContext>({
+  kind: "aggregate.update",
+  defaultFailureStrategy: "throw",
+  resultKey: (args) => args.name,
+  run: async (args, ctx: PipelineCtx) => {
+    const id = resolveRequired(args.id, ctx);
+    const changes = resolveRequired(args.changes, ctx);
+    const version = resolveOptional(args.version, ctx);
+    const result = await args.executor.update(
+      { id, version, changes },
+      ctx.event.user,
+      ctx.db,
+      args.skipOptimisticLock ? { skipOptimisticLock: true } : undefined,
+    );
+    if (!result.isSuccess) {
+      throw reraiseAsKumikoError(result.error);
+    }
+    return result.data;
+  },
+});
+
+export function buildAggregateUpdateStep(
+  name: string,
+  opts: {
+    readonly executor: EventStoreExecutor;
+    readonly id: StepResolver<EntityId>;
+    readonly changes: StepResolver<Record<string, unknown>>;
+    readonly version?: StepResolver<number | undefined>;
+    readonly skipOptimisticLock?: boolean;
+  },
+): StepInstance {
+  return {
+    kind: "aggregate.update",
+    args: { name, ...opts } satisfies AggregateUpdateArgs,
+  };
+}

package/src/engine/steps/branch.ts

@@ -0,0 +1,84 @@
+// r.step.branch — conditional sub-pipeline execution.
+//
+// Evaluates the `if` resolver, runs the `then` step-array if truthy,
+// otherwise the `else` step-array (if provided). Branch is a
+// side-effect container: it doesn't surface a result-key, doesn't
+// allow mid-flight `r.step.return`. Use it to gate ES-mutations or
+// projection-writes on a condition derived from prior steps.
+//
+// ```ts
+// r.step.branch({
+//   if: ({ steps }) => (steps["user"] as User | null) !== null,
+//   onTrue: [r.step.aggregate.appendEvent({...})],
+//   onFalse: [r.step.unsafeProjectionUpsert({...})],
+// })
+// ```
+//
+// Naming-note (Q14 revised): `onTrue`/`onFalse` instead of `then`/`else`
+// because Biome's `noThenProperty` lint flags `then` as a thenable-trap
+// (await-on-the-args-object would invoke the array, not awaited
+// resolution). `if` remains as JS-keyword-as-property — string-key access
+// is allowed and reads as natural English.
+//
+// Sub-pipeline-form (Q11): `onTrue` / `onFalse` are static StepInstance
+// arrays — `r` is captured from the outer pipeline closure, no nested
+// r-arg. Boot-validator walks them recursively (Q17). Build-time guard
+// (Q12) rejects nested `r.step.return` — branch is not a mid-flight
+// exit (would trigger the discriminated-union TData-Inference trap).
+
+import { defineStep } from "../define-step";
+import { runStepList } from "../run-pipeline";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { validateNoReturnSteps } from "./_no-return-guard";
+import { resolveRequired } from "./_resolver-utils";
+import { SUSPEND_SENTINEL } from "./_step-dispatch-constants";
+
+type BranchArgs = {
+  readonly if: StepResolver<boolean>;
+  readonly onTrue: readonly StepInstance[];
+  readonly onFalse?: readonly StepInstance[];
+};
+
+defineStep<BranchArgs, undefined | typeof SUSPEND_SENTINEL>({
+  kind: "branch",
+  defaultFailureStrategy: "throw",
+  subPaths: ["onTrue", "onFalse"],
+  run: async (args, ctx: PipelineCtx) => {
+    const condition = resolveRequired(args.if, ctx);
+    const branchSteps = condition ? args.onTrue : (args.onFalse ?? []);
+
+    // Recursive sub-step execution. The acc-maps in ctx are typed
+    // Readonly for the public-facing PipelineCtx (resolvers shouldn't
+    // mutate them directly), but the runtime objects are the same
+    // mutable maps that runPipeline owns. Casting back to mutable here
+    // is a framework-internal boundary, not a user-API boundary.
+    const stepsAcc = ctx.steps as Record<string, unknown>;
+    const scopeAcc = ctx.scope as Record<string, unknown>;
+
+    const outcome = await runStepList(
+      branchSteps,
+      ctx.event,
+      ctx,
+      stepsAcc,
+      scopeAcc,
+      ctx.workflow,
+    );
+    if (outcome.kind === "return") {
+      // Build-time guard (validateNoReturnSteps) rejects any return-step
+      // inside onTrue/onFalse. If we land here at runtime, someone
+      // hand-crafted a StepInstance with kind="return" and bypassed the
+      // builder. Fail loud rather than silently bubbling the return up to
+      // the outer pipeline (would shadow Q12).
+      throw new Error("r.step.return is not allowed inside r.step.branch onTrue/onFalse (Q12)");
+    }
+    if (outcome.kind === "suspended") {
+      return SUSPEND_SENTINEL;
+    }
+  },
+});
+
+export function buildBranchStep(args: BranchArgs): StepInstance {
+  validateNoReturnSteps(args.onTrue, "r.step.branch.onTrue");
+  if (args.onFalse) validateNoReturnSteps(args.onFalse, "r.step.branch.onFalse");
+  return { kind: "branch", args };
+}

package/src/engine/steps/call-feature.ts

@@ -0,0 +1,49 @@
+// r.step.callFeature — typed sub-command on another Kumiko feature.
+// Tier-2: requires r.requires.step("callFeature"). Sync (no dispatcher).
+// Cross-tenant via opts.as (Sysadmin-role-checked at the dispatcher layer).
+
+import { defineStep } from "../define-step";
+import type { SessionUser } from "../types";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { resolveRequired } from "./_resolver-utils";
+
+type CallFeatureArgs = {
+  readonly name: string;
+  readonly handler: string;
+  readonly payload: StepResolver<unknown>;
+  readonly as?: SessionUser;
+};
+
+defineStep<CallFeatureArgs, unknown>({
+  kind: "callFeature",
+  tier: 2,
+  defaultFailureStrategy: "throw",
+  resultKey: (args) => args.name,
+  run: async (args, ctx: PipelineCtx) => {
+    const payload = resolveRequired(args.payload, ctx);
+    const result = args.as
+      ? await ctx.writeAs(args.as, args.handler, payload)
+      : await ctx.write(args.handler, payload);
+    if (!result.isSuccess) {
+      // Preserve the structured WriteFailure as `cause` so the
+      // dispatcher's catch maps it back to a typed error response
+      // (e.g. validation_failed stays validation_failed, not a
+      // generic internal_error).
+      const err = new Error(`callFeature("${args.handler}") returned failure`);
+      (err as Error & { cause?: unknown }).cause = result.error;
+      throw err;
+    }
+    return result.data;
+  },
+});
+
+export function buildCallFeatureStep(
+  name: string,
+  opts: {
+    readonly handler: string;
+    readonly payload: StepResolver<unknown>;
+    readonly as?: SessionUser;
+  },
+): StepInstance {
+  return { kind: "callFeature", args: { name, ...opts } };
+}

package/src/engine/steps/compute.ts

@@ -0,0 +1,41 @@
+// r.step.compute — derive a value from the pipeline-context and stash
+// it under `steps.<name>` for subsequent steps to consume.
+//
+// Typical use:
+//   r.step.compute("startedAt", () => Temporal.Now.instant()),
+//   r.step.compute("isPriority", ({ event }) => event.payload.tier === "Pro"),
+//
+// `compute` is the simplest non-trivial step — it shows how the
+// `steps`-accumulator carries values forward across the pipeline. The
+// runtime side is a single function call; the value of this step lies
+// in being the smallest building block that exercises step-result
+// threading end-to-end.
+//
+// Type-safety note: in M.1, `steps` is Record<string, unknown> — call
+// sites cast or guard at the read end. Strict-typed result-key
+// accumulation is a follow-up (see step-vocabulary.md M.1-Followups).
+
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance } from "../types/step";
+
+type ComputeStepArgs = {
+  readonly name: string;
+  readonly fn: (ctx: PipelineCtx) => unknown;
+};
+
+defineStep<ComputeStepArgs, unknown>({
+  kind: "compute",
+  defaultFailureStrategy: "throw",
+  resultKey: (args) => args.name,
+  run: (args, ctx) => args.fn(ctx),
+});
+
+export function buildComputeStep<TResult>(
+  name: string,
+  fn: (ctx: PipelineCtx) => TResult,
+): StepInstance {
+  return {
+    kind: "compute",
+    args: { name, fn } satisfies ComputeStepArgs,
+  };
+}

package/src/engine/steps/for-each.ts

@@ -0,0 +1,111 @@
+// r.step.forEach — iterate a sub-pipeline over an array.
+//
+// The sub-pipeline (`do`) runs once per item; the current item lands
+// under `scope[as]` for resolvers inside `do` to read. After the loop,
+// `scope[as]` is restored to its prior value (or deleted if it didn't
+// exist before) — scope-keys are forEach-local, not bleeding into
+// subsequent top-level steps.
+//
+// ```ts
+// r.step.forEach({
+//   over: ({ steps }) => steps["componentIds"] as string[],
+//   as: "componentId",
+//   do: [
+//     r.step.unsafeProjectionUpsert({
+//       table: incidentComponentsTable,
+//       on: ["incidentId", "componentId"],
+//       row: ({ scope, steps }) => ({
+//         incidentId: (steps["incident"] as { id: string }).id,
+//         componentId: scope["componentId"] as string,
+//       }),
+//     }),
+//   ],
+// })
+// ```
+//
+// M.1.6 supports `concurrency: 1` only (sequential). Concurrent
+// execution (Promise.all-style) is Followup #12 — TX-sharing,
+// AbortSignal-cancellation, and lifecycle-hook ordering each warrant
+// their own audit cycle (Q16).
+//
+// Q15: `as` is required — without it, the current item is unreachable
+// from the sub-pipeline's resolvers. Q12: r.step.return inside `do` is
+// rejected at build time (would trigger the discriminated-union
+// TData-Inference trap).
+
+import { defineStep } from "../define-step";
+import { runStepList } from "../run-pipeline";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { validateNoReturnSteps } from "./_no-return-guard";
+import { resolveRequired } from "./_resolver-utils";
+import { SUSPEND_SENTINEL } from "./_step-dispatch-constants";
+
+type ForEachArgs<TItem = unknown> = {
+  readonly over: StepResolver<readonly TItem[]>;
+  readonly as: string;
+  readonly do: readonly StepInstance[];
+  // Reserved for Followup #12. Today only `1` is accepted; adding `N`
+  // requires the work documented in step-vocabulary.md Q16.
+  readonly concurrency?: 1;
+};
+
+defineStep<ForEachArgs, undefined | typeof SUSPEND_SENTINEL>({
+  kind: "forEach",
+  defaultFailureStrategy: "throw",
+  subPaths: ["do"],
+  run: async (args, ctx: PipelineCtx) => {
+    const items = resolveRequired(args.over, ctx);
+    if (!Array.isArray(items)) {
+      throw new Error(`r.step.forEach: 'over' resolver must return an array (got ${typeof items})`);
+    }
+
+    // Mutable-acc cast — same framework-internal boundary as branch.run.
+    // The runtime objects are the maps that runPipeline owns; readonly
+    // typing in PipelineCtx is for resolver-API hygiene.
+    const stepsAcc = ctx.steps as Record<string, unknown>;
+    const scopeAcc = ctx.scope as Record<string, unknown>;
+
+    // Save-and-restore so the scope-key is forEach-local. Without this,
+    // a nested `r.step.compute` reading scope[as] AFTER the forEach
+    // would silently see the last iteration's item.
+    const hadKey = Object.hasOwn(scopeAcc, args.as);
+    const previousValue = scopeAcc[args.as];
+
+    try {
+      for (const item of items) {
+        scopeAcc[args.as] = item;
+        const outcome = await runStepList(
+          args.do,
+          ctx.event,
+          ctx,
+          stepsAcc,
+          scopeAcc,
+          ctx.workflow,
+        );
+        if (outcome.kind === "return") {
+          throw new Error("r.step.return is not allowed inside r.step.forEach.do (Q12)");
+        }
+        if (outcome.kind === "suspended") {
+          return SUSPEND_SENTINEL;
+        }
+      }
+    } finally {
+      if (hadKey) {
+        scopeAcc[args.as] = previousValue;
+      } else {
+        delete scopeAcc[args.as];
+      }
+    }
+  },
+});
+
+export function buildForEachStep<TItem = unknown>(args: ForEachArgs<TItem>): StepInstance {
+  validateNoReturnSteps(args.do, "r.step.forEach.do");
+  if (args.concurrency !== undefined && args.concurrency !== 1) {
+    throw new Error(
+      `r.step.forEach: concurrency=${args.concurrency} not supported in M.1.6 (only 1). ` +
+        `Concurrent forEach is Followup #12 — TX-sharing, AbortSignal, hook-ordering each need their own slice.`,
+    );
+  }
+  return { kind: "forEach", args };
+}

package/src/engine/steps/mail-send.ts

@@ -0,0 +1,44 @@
+// r.step.mail.send — deferred transactional e-mail via the step-dispatcher.
+// Tier-2: requires r.requires.step("mail.send"). Mirrors webhook.send.
+
+import { randomUUID } from "node:crypto";
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { resolveOptional, resolveRequired } from "./_resolver-utils";
+import {
+  STEP_DISPATCH_AGGREGATE_TYPE,
+  STEP_DISPATCH_REQUESTED_TYPE,
+} from "./_step-dispatch-constants";
+
+type MailSendArgs = {
+  readonly to: StepResolver<string | readonly string[]>;
+  readonly subject: StepResolver<string>;
+  readonly body: StepResolver<string>;
+  readonly from?: StepResolver<string>;
+  readonly mode: "deferred";
+};
+
+defineStep<MailSendArgs, void>({
+  kind: "mail.send",
+  tier: 2,
+  defaultFailureStrategy: "throw",
+  run: async (args, ctx: PipelineCtx) => {
+    const to = resolveRequired(args.to, ctx);
+    const subject = resolveRequired(args.subject, ctx);
+    const body = resolveRequired(args.body, ctx);
+    const from = resolveOptional(args.from, ctx);
+    await ctx.unsafeAppendEvent({
+      aggregateId: randomUUID(),
+      aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+      type: STEP_DISPATCH_REQUESTED_TYPE,
+      payload: {
+        stepKind: "mail.send",
+        spec: { to, subject, body, ...(from && { from }) },
+      },
+    });
+  },
+});
+
+export function buildMailSendStep(args: MailSendArgs): StepInstance {
+  return { kind: "mail.send", args };
+}