@cosmicdrift/kumiko-framework 0.2.3 → 0.3.0

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 };
+}

package/src/engine/steps/read-find-many.ts

@@ -0,0 +1,51 @@
+// r.step.read.findMany — load multiple rows from a projection table.
+//
+// Sibling to read.findOne — same tenant-filter caveat (caller-owned),
+// same drizzle-boundary cast. Resolves to a row-array (possibly empty),
+// landed under steps.<name>.
+//
+// Optional `limit` — defaults to no-limit (caller-chosen, NOT a
+// guard-rail). Most legitimate uses iterate via r.step.forEach (M.1.6)
+// over the result, where unbounded arrays would be the bug. Set
+// `limit` explicitly when the row-count could grow without bound.
+
+import type { SQL, Table } from "drizzle-orm";
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { asQueryTarget } from "./_drizzle-boundary";
+import { resolveOptional } from "./_resolver-utils";
+
+type ReadFindManyArgs = {
+  readonly name: string;
+  readonly table: Table;
+  readonly where?: StepResolver<SQL | undefined>;
+  readonly limit?: number;
+};
+
+defineStep<ReadFindManyArgs, readonly Record<string, unknown>[]>({
+  kind: "read.findMany",
+  defaultFailureStrategy: "throw",
+  resultKey: (args) => args.name,
+  run: async (args, ctx: PipelineCtx) => {
+    const where = resolveOptional(args.where, ctx);
+    const baseQuery = ctx.db.select().from(asQueryTarget(args.table));
+    const filteredQuery = where === undefined ? baseQuery : baseQuery.where(where);
+    const finalQuery = args.limit === undefined ? filteredQuery : filteredQuery.limit(args.limit);
+    const rows = await finalQuery;
+    return rows as readonly Record<string, unknown>[];
+  },
+});
+
+export function buildReadFindManyStep(
+  name: string,
+  opts: {
+    readonly table: Table;
+    readonly where?: StepResolver<SQL | undefined>;
+    readonly limit?: number;
+  },
+): StepInstance {
+  return {
+    kind: "read.findMany",
+    args: { name, ...opts } satisfies ReadFindManyArgs,
+  };
+}

package/src/engine/steps/read-find-one.ts

@@ -0,0 +1,58 @@
+// r.step.read.findOne — load a single row from a projection table.
+//
+// Thin wrapper on ctx.db.select().from(table).where(where).limit(1).
+// Resolves to the first row or null. Tenant-isolation: the caller's
+// `where` clause is responsible for any tenantId filter — read.findOne
+// does NOT auto-inject one (different from ctx.queryProjection which
+// does). That's deliberate: most read-step uses are aggregate-lookups
+// where the where-clause already pins a uuid that's globally unique;
+// auto-tenant-filtering would be redundant and would surprise users
+// who pass an explicit tenantId.
+//
+// Use when a subsequent step needs a row from the read-side. For
+// cross-feature reads, prefer `r.step.callFeature(...)` (M.2) so the
+// other feature's query-handler runs (with its access-rules + audit).
+//
+// `where` should resolve to a clause that matches at most one row
+// (typical: equality on PK / unique-constraint). When multiple rows
+// satisfy the clause, the LIMIT 1 picks one in driver-defined order
+// (Postgres: insertion order in practice, but not specified) — that's
+// fine for "find by uuid", a footgun for "find by tenantId". No
+// runtime check; reviewer responsibility.
+
+import type { SQL, Table } from "drizzle-orm";
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { asQueryTarget } from "./_drizzle-boundary";
+import { resolveRequired } from "./_resolver-utils";
+
+type ReadFindOneArgs = {
+  readonly name: string;
+  readonly table: Table;
+  readonly where: StepResolver<SQL | undefined>;
+};
+
+defineStep<ReadFindOneArgs, Record<string, unknown> | null>({
+  kind: "read.findOne",
+  defaultFailureStrategy: "throw",
+  resultKey: (args) => args.name,
+  run: async (args, ctx: PipelineCtx) => {
+    const where = resolveRequired(args.where, ctx);
+    const query = ctx.db.select().from(asQueryTarget(args.table));
+    const rows = where === undefined ? await query.limit(1) : await query.where(where).limit(1);
+    return (rows[0] as Record<string, unknown> | undefined) ?? null;
+  },
+});
+
+export function buildReadFindOneStep(
+  name: string,
+  opts: {
+    readonly table: Table;
+    readonly where: StepResolver<SQL | undefined>;
+  },
+): StepInstance {
+  return {
+    kind: "read.findOne",
+    args: { name, ...opts } satisfies ReadFindOneArgs,
+  };
+}

package/src/engine/steps/retry.ts

@@ -0,0 +1,87 @@
+// r.step.retry — wrap a sub-pipeline with retry+backoff.
+// Tier-3 / Workflow-only: only available inside defineWorkflow.
+//
+// On first execution, runs the `do` sub-pipeline inside a try-catch.
+// If it throws and retries remain, writes a kumiko:system:workflow.retry.scheduled
+// event and returns SUSPEND_SENTINEL to suspend. The Resume-Loop picks it up
+// after the backoff duration and re-enters the step at the same index.
+// After all attempts exhausted, the original error propagates.
+
+import { defineStep } from "../define-step";
+import { runStepList } from "../run-pipeline";
+import type { PipelineCtx, StepInstance } from "../types/step";
+import {
+  SUSPEND_SENTINEL,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+} from "./_step-dispatch-constants";
+
+type RetryStepArgs = {
+  readonly times: number;
+  readonly backoff: "exponential" | "linear";
+  readonly do: readonly StepInstance[];
+};
+
+defineStep<RetryStepArgs, undefined | typeof SUSPEND_SENTINEL>({
+  kind: "workflow.retry",
+  tier: 3,
+  defaultFailureStrategy: "throw",
+  subPaths: ["do"],
+  run: async (args, ctx: PipelineCtx): Promise<undefined | typeof SUSPEND_SENTINEL> => {
+    if (!ctx.workflow) {
+      throw new Error(
+        "r.step.retry is only allowed inside defineWorkflow — " + "sync handlers cannot suspend.",
+      );
+    }
+
+    const stepsAcc = ctx.steps as Record<string, unknown>;
+    const scopeAcc = ctx.scope as Record<string, unknown>;
+    const maxAttempts = args.times;
+    const attempt = ctx.workflow.retryAttempt ?? 1;
+
+    try {
+      await runStepList(args.do, ctx.event, ctx, stepsAcc, scopeAcc, ctx.workflow);
+      return undefined;
+    } catch (error) {
+      if (attempt >= maxAttempts) {
+        throw error;
+      }
+
+      const backoffMs = calculateBackoff(attempt, args.backoff);
+      const wakeAt = Temporal.Now.instant().add({ milliseconds: backoffMs }).toString();
+
+      await ctx.unsafeAppendEvent({
+        aggregateId: ctx.workflow.runId,
+        aggregateType: WORKFLOW_AGGREGATE_TYPE,
+        type: WORKFLOW_RETRY_SCHEDULED_TYPE,
+        payload: {
+          stepIndex: ctx.workflow.stepIndex,
+          attempt,
+          maxAttempts,
+          wakeAt,
+          workflowName: ctx.workflow.workflowName,
+          error: String(error),
+          triggerEventType: ctx.event.type,
+          triggerPayload: ctx.event.payload,
+          ...(ctx.workflow.definitionFingerprint && {
+            definitionFingerprint: ctx.workflow.definitionFingerprint,
+          }),
+        },
+      });
+
+      return SUSPEND_SENTINEL;
+    }
+  },
+});
+
+export function buildRetryStep(args: RetryStepArgs): StepInstance {
+  return { kind: "workflow.retry", args };
+}
+
+export function calculateBackoff(attempt: number, strategy: "exponential" | "linear"): number {
+  const baseMs = 10_000;
+  if (strategy === "linear") {
+    return baseMs * attempt;
+  }
+  return baseMs * 2 ** (attempt - 1);
+}