@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/src/engine/index.ts

@@ -3,6 +3,7 @@
 export { hasAccess } from "./access";
 export { validateBoot } from "./boot-validator";
 export { buildAppSchema } from "./build-app-schema";
+export { buildTarget } from "./build-target";
 export { access, createSystemConfig, createTenantConfig, createUserConfig } from "./config-helpers";
 export type { SystemHookName } from "./constants";
 export {
@@ -18,9 +19,16 @@ export {
 export type { App, AppConfig } from "./create-app";
 export { createApp } from "./create-app";
 export { defineFeature } from "./define-feature";
-export type { QueryHandlerDefinition, WriteHandlerDefinition } from "./define-handler";
+export type {
+  QueryHandlerDefinition,
+  WriteHandlerDefinition,
+  WriteHandlerInput,
+} from "./define-handler";
 export { defineQueryHandler, defineWriteHandler } from "./define-handler";
 export { defineRoles } from "./define-roles";
+export { defineStep, getStep, listStepKinds } from "./define-step";
+export type { WorkflowDefinition, WorkflowInput, WorkflowTrigger } from "./define-workflow";
+export { computeDefinitionFingerprint, defineWorkflow } from "./define-workflow";
 export type { ToggleReader } from "./effective-features";
 export { computeEffectiveFeatures } from "./effective-features";
 export {
@@ -41,7 +49,25 @@ export {
 } from "./entity-handlers";
 export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";
+export type { KumikoExtensionName } from "./extension-names";
+export {
+  EXT_EXTERNAL_RESOURCE,
+  EXT_INFRA_RESOURCE,
+  EXT_SEARCH_ADAPTER,
+  EXT_STORAGE_PROVIDER,
+  EXT_TENANT_DATA,
+  EXT_USER_DATA,
+} from "./extension-names";
+export type {
+  UserDataDeleteHook,
+  UserDataDeleteStrategy,
+  UserDataExportHook,
+  UserDataExportSnippet,
+  UserDataExtensionHooks,
+  UserDataHookCtx,
+} from "./extensions/user-data";
 export {
+  createBigIntField,
   createBooleanField,
   createDateField,
   createEmbeddedField,
@@ -107,6 +133,7 @@ export {
 } from "./field-access";
 export type { OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule } from "./ownership";
 export { from } from "./ownership";
+export { buildPipelineSteps, pipeline } from "./pipeline";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers";
 export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name";
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name";
@@ -115,9 +142,22 @@ export { createRegistry } from "./registry";
 export type { ClampInfo, ResolveOptions } from "./resolve-config-or-param";
 export { resolveConfigOrParam } from "./resolve-config-or-param";
 export { runsInLane } from "./run-in";
+export type { StepListOutcome } from "./run-pipeline";
+export { runPipeline, runStepList } from "./run-pipeline";
 export { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";
+export {
+  SUSPEND_SENTINEL,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RESUMED_TYPE,
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+  WORKFLOW_WAITING_FOR_EVENT_TYPE,
+  WORKFLOW_WAITING_TYPE,
+} from "./steps/_step-dispatch-constants";
 export {
   ANONYMOUS_ROLE,
   ANONYMOUS_USER_ID,
@@ -139,11 +179,11 @@ export type {
   AppContext,
   AppendEventArgs,
   AppendEventFn,
-  AppendEventUnsafeFn,
   AuthClaimsContext,
   AuthClaimsFn,
   AuthClaimsHookDef,
   BelongsToRelation,
+  BigIntFieldDef,
   BooleanFieldDef,
   CamelToKebab,
   ClaimKeyDefinition,
@@ -220,6 +260,7 @@ export type {
   NotifyPriority,
   NumberFieldDef,
   OnDeleteStrategy,
+  PiiAnnotations,
   PlatformComponent,
   PostDeleteHookFn,
   PostSaveHookFn,
@@ -234,17 +275,28 @@ export type {
   QueryHandlerFn,
   Registry,
   RelationDefinition,
+  RetentionDef,
   RowAction,
   SaveContext,
   ScreenDefinition,
   ScreenSlots,
   SelectFieldDef,
   SessionUser,
+  Subscribe,
+  TargetRef,
   TenantId,
   TextFieldDef,
   ToolbarAction,
   TranslationKeys,
   TranslationsDef,
+  TreeAction,
+  TreeActionDef,
+  TreeActionsHandle,
+  TreeChildrenSubscribe,
+  TreeContext,
+  TreeNode,
+  TreeNodeState,
+  UnsafeAppendEventFn,
   ValidationError,
   ValidationHookFn,
   WorkspaceDefinition,
@@ -257,4 +309,16 @@ export { DEFAULT_CURRENCIES, HookPhases } from "./types";
 export { resolveName, withResponseData } from "./types/handlers";
 export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
 export { normalizeEditField, normalizeListColumn } from "./types/screen";
+export type {
+  PipelineBuildCtx,
+  PipelineCtx,
+  PipelineDef,
+  StepBuilder,
+  StepDef,
+  StepFailureStrategy,
+  StepInstance,
+  StepKind,
+  StepNamespace,
+  StepResolver,
+} from "./types/step";
 export { runValidation } from "./validation";

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -55,6 +55,10 @@ const ALL_KINDS: readonly FeaturePatternKind[] = [
   "defineEvent",
   "eventMigration",
   "extendsRegistrar",
+  "usesApi",
+  "exposesApi",
+  "treeActions",
+  "tree",
   "unknown",
 ];
 
@@ -338,8 +342,15 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
         extensionName: "x",
         defBody: PLACEHOLDER_BODY_LOC,
       };
+    case "treeActions":
+      return { kind, source: PLACEHOLDER_LOC, definitions: {} };
+    case "tree":
+      return { kind, source: PLACEHOLDER_LOC, providerBody: PLACEHOLDER_BODY_LOC };
     case "unknown":
       return { kind, source: PLACEHOLDER_LOC, methodName: "x" };
+    case "usesApi":
+    case "exposesApi":
+      return { kind, source: PLACEHOLDER_LOC, apiName: "demo.api" };
     default: {
       const _exhaustive: never = kind;
       return _exhaustive;

package/src/engine/pattern-library/library.ts

@@ -597,7 +597,7 @@ const writeHandlerSchema: PatternFormSchema = {
       input: "json-readonly",
     },
     {
-      path: "skipTransitionGuard",
+      path: "unsafeSkipTransitionGuard",
       label: { en: "Skip transition guard", de: "Übergangs-Guard überspringen" },
       input: "boolean",
     },
@@ -1020,6 +1020,78 @@ const extendsRegistrarSchema: PatternFormSchema = {
   ],
 };
 
+const usesApiSchema: PatternFormSchema = {
+  kind: "usesApi",
+  label: { en: "Uses API", de: "Nutzt API" },
+  summary: {
+    en: "Cross-feature handler-ID dependency. Boot fails if no other feature exposes it.",
+  },
+  category: "advanced",
+  editability: "static",
+  fields: [
+    {
+      path: "apiName",
+      label: { en: "API name", de: "API-Name" },
+      input: "text",
+      required: true,
+    },
+  ],
+};
+
+const exposesApiSchema: PatternFormSchema = {
+  kind: "exposesApi",
+  label: { en: "Exposes API", de: "Stellt API bereit" },
+  summary: { en: "Declares this feature provides a handler matching the cross-feature contract." },
+  category: "advanced",
+  editability: "static",
+  fields: [
+    {
+      path: "apiName",
+      label: { en: "API name", de: "API-Name" },
+      input: "text",
+      required: true,
+    },
+  ],
+};
+
+// Visual-Tree pattern schemas. treeActions is a static map (Designer
+// renders the action-name → ActionDef pairs as a nested form), tree is
+// closure-only (Designer shows the provider body as read-only code).
+const treeActionsSchema: PatternFormSchema = {
+  kind: "treeActions",
+  label: { en: "Tree actions", de: "Tree-Actions" },
+  summary: { en: "Action verbs the Visual-Tree dispatches via buildTarget." },
+  category: "ui",
+  editability: "static",
+  singleton: true,
+  fields: [
+    {
+      path: "definitions",
+      label: { en: "Action definitions", de: "Action-Definitionen" },
+      input: "json-readonly",
+      readOnly: true,
+    },
+  ],
+};
+
+const treeSchema: PatternFormSchema = {
+  kind: "tree",
+  label: { en: "Tree provider", de: "Tree-Provider" },
+  summary: { en: "Subscribe-Function emitting top-level Visual-Tree nodes." },
+  category: "ui",
+  editability: "opaque",
+  singleton: true,
+  fields: [
+    {
+      path: "providerBody",
+      label: { en: "Provider body (source)", de: "Provider-Body (Source)" },
+      input: "code-block",
+      language: "typescript",
+      readOnly: true,
+    },
+  ],
+};
+
 const unknownSchema: PatternFormSchema = {
   kind: "unknown",
   label: { en: "Unknown call", de: "Unbekannter Call" },
@@ -1077,8 +1149,12 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   defineEvent: defineEventSchema,
   eventMigration: eventMigrationSchema,
   extendsRegistrar: extendsRegistrarSchema,
+  usesApi: usesApiSchema,
+  exposesApi: exposesApiSchema,
+  treeActions: treeActionsSchema,
+  tree: treeSchema,
   unknown: unknownSchema,
-};
+} satisfies Readonly<Record<FeaturePatternKind, PatternFormSchema>>;
 
 /**
  * Lookup helper — convenience over `PATTERN_LIBRARY[kind]`. Throws when

package/src/engine/pipeline.ts

@@ -0,0 +1,88 @@
+// pipeline() — public factory used in defineWriteHandler({ perform: pipeline(...) }).
+//
+// The closure receives { event, r } and returns the immutable list of
+// step instances. `r` is the StepBuilder singleton; new tier-1 steps
+// add a builder factory in steps/<x>.ts and expose it under `step` below.
+//
+// `steps` and `scope` are NOT exposed at build time — they only exist on
+// the resolver-side PipelineCtx (run-pipeline.ts). Resolvers that need
+// prior step results destructure them from the resolver's ctx.
+//
+// Naming note (Followup #1): the public `pipeline()` helper shares its
+// name with the internal `packages/framework/src/pipeline/` directory
+// (dispatcher, lifecycle, outbox-poller). No user-visible collision —
+// the internal directory isn't an export — but maintainer repo-wide
+// grep for `pipeline` returns mixed results. If a rename ever lands,
+// candidates are `r.steps([...])` for the public API or
+// `engine-pipeline/` / `runtime/` for the internal directory.
+// Decision-cost grows with each new caller; the rename window narrows
+// after the first external consumer.
+
+import { buildAggregateAppendEventStep } from "./steps/aggregate-append-event";
+import { buildAggregateCreateStep } from "./steps/aggregate-create";
+import { buildAggregateUpdateStep } from "./steps/aggregate-update";
+import { buildBranchStep } from "./steps/branch";
+import { buildCallFeatureStep } from "./steps/call-feature";
+import { buildComputeStep } from "./steps/compute";
+import { buildForEachStep } from "./steps/for-each";
+import { buildMailSendStep } from "./steps/mail-send";
+import { buildReadFindManyStep } from "./steps/read-find-many";
+import { buildReadFindOneStep } from "./steps/read-find-one";
+import { buildRetryStep } from "./steps/retry";
+import { buildReturnStep } from "./steps/return";
+import { buildUnsafeProjectionDeleteStep } from "./steps/unsafe-projection-delete";
+import { buildUnsafeProjectionUpsertStep } from "./steps/unsafe-projection-upsert";
+import { buildWaitStep } from "./steps/wait";
+import { buildWaitForEventStep } from "./steps/wait-for-event";
+import { buildWebhookSendStep } from "./steps/webhook-send";
+import type { WriteEvent } from "./types/handlers";
+import type { PipelineBuildCtx, PipelineDef, StepBuilder, StepInstance } from "./types/step";
+
+const stepBuilder: StepBuilder = {
+  step: {
+    return: buildReturnStep,
+    compute: buildComputeStep,
+    branch: buildBranchStep,
+    forEach: buildForEachStep,
+    unsafeProjectionUpsert: buildUnsafeProjectionUpsertStep,
+    unsafeProjectionDelete: buildUnsafeProjectionDeleteStep,
+    aggregate: {
+      create: buildAggregateCreateStep,
+      update: buildAggregateUpdateStep,
+      appendEvent: buildAggregateAppendEventStep,
+    },
+    read: {
+      findOne: buildReadFindOneStep,
+      findMany: buildReadFindManyStep,
+    },
+    webhook: {
+      send: buildWebhookSendStep,
+    },
+    mail: {
+      send: buildMailSendStep,
+    },
+    callFeature: buildCallFeatureStep,
+    // Tier-3 / Workflow-only steps
+    wait: buildWaitStep,
+    waitForEvent: buildWaitForEventStep,
+    retry: buildRetryStep,
+  },
+};
+
+export function pipeline<TPayload = unknown, TData = unknown>(
+  closure: (ctx: PipelineBuildCtx<TPayload>) => readonly StepInstance[],
+): PipelineDef<TPayload, TData> {
+  return {
+    __kind: "pipeline",
+    build: closure,
+  };
+}
+
+// Internal: invoked by run-pipeline.ts to materialise the step list.
+// Not exported from the engine barrel — pipeline-internal plumbing.
+export function buildPipelineSteps<TPayload>(
+  pipelineDef: PipelineDef<TPayload>,
+  event: WriteEvent<TPayload>,
+): readonly StepInstance[] {
+  return pipelineDef.build({ event, r: stepBuilder });
+}

package/src/engine/projection-helpers.ts

@@ -76,7 +76,7 @@ export function setFields(
     // strict about the concrete row, so we feed it the erased value; the
     // type-safety guarantee for `values` lives at the setFields call-site.
     // biome-ignore lint/suspicious/noExplicitAny: see note above.
-    const set = values as any;
+    const set = values as any; // @cast-boundary engine-bridge
     await tx
       .update(table)
       .set(set)

package/src/engine/read-claim.ts

@@ -27,5 +27,5 @@ export function readClaim<T extends ClaimKeyType>(
   if (!claims) return undefined;
   const raw = claims[handle.name];
   if (raw === undefined || raw === null) return undefined;
-  return raw as ClaimKeyJsType<T>;
+  return raw as ClaimKeyJsType<T>; // @cast-boundary schema-walk
 }

package/src/engine/registry.ts

@@ -35,6 +35,8 @@ import type {
   ScreenDefinition,
   SecretKeyDefinition,
   TranslationKeys,
+  TreeActionDef,
+  TreeChildrenSubscribe,
   WorkspaceDefinition,
   WriteHandlerDef,
 } from "./types";
@@ -198,6 +200,14 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   const navsByWorkspace = new Map<string, string[]>();
   let defaultWorkspace: WorkspaceDefinition | undefined;
 
+  // Visual-Tree-Provider — keyed by declaring feature name (NOT qualified;
+  // ein Feature liefert genau einen Provider). Visual-Tree-Component
+  // iteriert die Map zur Mount-Zeit. Tree-Actions parallel — featureName
+  // → erased Action-Map (compile-time-typed Variante geht über
+  // setup-export-handle, siehe FeatureRegistrar.treeActions docs).
+  const treeProvidersMap = new Map<string, TreeChildrenSubscribe>();
+  const treeActionsMap = new Map<string, Readonly<Record<string, TreeActionDef>>>();
+
   // Local alias for readability — `qualifyEntityName` is the shared helper
   // from qualified-name.ts, also used by validateBoot to keep ingest and
   // validation in lockstep on the qualification rule.
@@ -596,6 +606,16 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       }
     }
 
+    // Visual-Tree slots — at-most-one per feature (only-once-guard im
+    // registrar). Erased Maps für Runtime-Lookup; compile-time-typed
+    // Surface läuft über FeatureDefinition.exports (TreeActionsHandle).
+    if (feature.treeProvider !== undefined) {
+      treeProvidersMap.set(feature.name, feature.treeProvider);
+    }
+    if (feature.treeActions !== undefined) {
+      treeActionsMap.set(feature.name, feature.treeActions);
+    }
+
     // Auth-claims hooks: order of registration is preserved. Feature name is
     // captured alongside so the resolver can apply the auto-prefix at merge
     // time — the feature author never ships pre-prefixed keys.
@@ -984,7 +1004,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   const allHandlerNames = new Set([...writeHandlerMap.keys(), ...queryHandlerMap.keys()]);
   for (const [qualifiedName, notifDef] of notificationMap) {
     // Both maps are populated in lockstep — same key-set by construction.
-    const featureName = notificationFeatureMap.get(qualifiedName) as string;
+    const featureName = notificationFeatureMap.get(qualifiedName) as string; // @cast-boundary engine-bridge
     // I'll try the easy path first: if the trigger is already a fully qualified QN
     // (cross-feature), I take it as-is. Otherwise I qualify with the own feature —
     // as a write handler first (the common case), then as a query. If nothing
@@ -1124,7 +1144,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     },
 
     getRelations(entityName: string): EntityRelations {
-      return (relationMap.get(entityName) ?? {}) as EntityRelations;
+      return (relationMap.get(entityName) ?? {}) as EntityRelations; // @cast-boundary schema-walk
     },
 
     getSearchIncludes(entityName: string): ReadonlyMap<string, readonly string[]> {
@@ -1355,6 +1375,14 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     getDefaultWorkspace(): WorkspaceDefinition | undefined {
       return defaultWorkspace;
     },
+
+    getTreeProviders(): ReadonlyMap<string, TreeChildrenSubscribe> {
+      return treeProvidersMap;
+    },
+
+    getTreeActions(featureName: string): Readonly<Record<string, TreeActionDef>> | undefined {
+      return treeActionsMap.get(featureName);
+    },
   };
 }
 

package/src/engine/resolve-config-or-param.ts

@@ -141,6 +141,10 @@ export async function resolveConfigOrParam<T extends ConfigKeyType>(
       // The caller is signalling intent; we honour the constraint instead.
       return ctx.config(handle);
     }
+    default: {
+      const _exhaustive: never = keyDef.type;
+      throw new Error(`resolveConfigOrParam: unhandled config key type "${_exhaustive}"`);
+    }
   }
 }
 

package/src/engine/run-pipeline.ts

@@ -0,0 +1,162 @@
+// run-pipeline — executes a PipelineDef against (event, ctx) and
+// returns a WriteResult.
+//
+// Execution model:
+//   1. Build the immutable step list by invoking the pipeline closure.
+//   2. Walk the list sequentially via runStepList. For each step:
+//      - Look up the registered StepDef by kind.
+//      - Build the live PipelineCtx (handler-ctx + accumulated steps + scope).
+//      - Call step.run(args, ctx) — capture its return value.
+//      - Detect the sentinel RETURN_RESULT_KEY → end pipeline with that
+//        WriteResult; otherwise stash the value under resultKey if any.
+//   3. If the loop exhausts without a `return` step, surface a loud error
+//      so a forgotten r.step.return doesn't fall through silently.
+//
+// runStepList is exported for sub-step builders (branch/forEach in M.1.6)
+// — they invoke it recursively over their own step-arrays, sharing the
+// outer pipeline's stepsAcc + scopeAcc maps so sub-step results
+// propagate up to subsequent top-level steps.
+//
+// Failure-strategy is "throw" only in M.1 — runPipeline lets thrown
+// errors propagate to the dispatcher's catch which maps them to
+// WriteFailure / HTTP. "return" / "skip" / fallback strategies land in
+// later slices together with their own integration tests.
+
+import { getStep } from "./define-step";
+import { buildPipelineSteps } from "./pipeline";
+import { SUSPEND_SENTINEL } from "./steps/_step-dispatch-constants";
+import { RETURN_RESULT_KEY } from "./steps/return";
+import type { KumikoEventTypeMap } from "./types/event-type-map";
+import type { HandlerContext, WriteEvent, WriteResult } from "./types/handlers";
+import type { PipelineCtx, PipelineDef, StepInstance } from "./types/step";
+
+// Result of walking a step-list. "return" surfaces the WriteResult of an
+// r.step.return; "exhausted" means all steps ran without hitting a return
+// — the caller (top-level pipeline) treats that as an error, sub-step
+// callers (branch/forEach) treat it as normal completion.
+// "suspended" means a Tier-3 step returned SUSPEND_SENTINEL — the pipeline
+// is paused pending external (time/event) and must be resumed later.
+export type StepListOutcome =
+  | { readonly kind: "return"; readonly result: WriteResult<unknown> }
+  | { readonly kind: "suspended"; readonly stepIndex: number }
+  | { readonly kind: "exhausted" };
+
+export async function runPipeline<TPayload, TData, TMap extends object = KumikoEventTypeMap>(
+  pipelineDef: PipelineDef<TPayload, TData>,
+  event: WriteEvent<TPayload>,
+  handlerCtx: HandlerContext<TMap>,
+  workflow?: PipelineCtx["workflow"],
+  resumeFrom?: number,
+): Promise<WriteResult<TData>> {
+  const steps = buildPipelineSteps(pipelineDef, event);
+  const stepsAcc: Record<string, unknown> = {};
+  const scopeAcc: Record<string, unknown> = {};
+
+  const outcome = await runStepList(
+    steps,
+    event,
+    handlerCtx,
+    stepsAcc,
+    scopeAcc,
+    workflow,
+    resumeFrom,
+  );
+  if (outcome.kind === "return") {
+    // RETURN_RESULT_KEY is only produced by r.step.return, whose run()
+    // returns WriteResult<unknown>. The pipeline's generic TData is
+    // bound at build time (defineWriteHandler ↔ pipeline<P, D>(...));
+    // matching the runtime value to that compile-time type is the
+    // contract user-side. Cast crosses that boundary.
+    return outcome.result as WriteResult<TData>;
+  }
+
+  if (outcome.kind === "suspended") {
+    // Suspension is only valid when running inside a workflow context.
+    // The caller (workflow-engine) handles the suspension lifecycle;
+    // we throw here because runPipeline's contract requires a WriteResult.
+    // The workflow engine calls runStepList directly to detect suspension.
+    if (!workflow) {
+      throw new Error(
+        "Pipeline suspended without a workflow context — Tier-3 steps are only allowed inside defineWorkflow.",
+      );
+    }
+    // Return a minimal WriteResult signalling suspension. The workflow
+    // engine extracts the outcome from runStepList directly.
+    return { isSuccess: true, data: undefined } as unknown as WriteResult<TData>;
+  }
+
+  throw new Error(
+    "Pipeline ended without an r.step.return(...) — every pipeline must explicitly return a WriteResult.",
+  );
+}
+
+/**
+ * Walk a step-list. Stateful in `stepsAcc` + `scopeAcc` (the caller's
+ * mutable maps) — sub-step builders share those with the outer pipeline
+ * so step results propagate. Returns either an early r.step.return
+ * outcome or an "exhausted" signal.
+ *
+ * Sub-step builders (branch.run, forEach.run) re-enter via this
+ * function. The same TMap-variance bridge applies — sub-steps treat
+ * ctx as PipelineCtx<unknown, KumikoEventTypeMap>, the runtime value
+ * is the outer's full HandlerContext.
+ */
+export async function runStepList<TPayload, TMap extends object = KumikoEventTypeMap>(
+  steps: readonly StepInstance[],
+  event: WriteEvent<TPayload>,
+  handlerCtx: HandlerContext<TMap>,
+  stepsAcc: Record<string, unknown>,
+  scopeAcc: Record<string, unknown>,
+  workflow?: PipelineCtx["workflow"],
+  resumeFrom?: number,
+): Promise<StepListOutcome> {
+  for (const [i, instance] of steps.entries()) {
+    // On resume, skip steps at or before the resume point — their
+    // effects (waiting/retry-scheduled events) were already written
+    // during the original pipeline run. The next unexecuted step
+    // is at resumeFrom + 1.
+    if (resumeFrom !== undefined && i < resumeFrom) {
+      continue;
+    }
+
+    // When resuming, re-execute the suspended step itself. Steps
+    // like wait/waitForEvent detect resumption by checking if a
+    // waiting event for their stepIndex already exists; retry
+    // uses retryAttempt from the workflow context.
+    // Steps that don't handle resumption (read/compute/aggregate)
+    // re-execute naturally — idempotent reads are safe, and
+    // event-sourced writes append new positions.
+    const stepDef = getStep(instance.kind);
+    if (!stepDef) {
+      throw new Error(`Unknown step kind "${instance.kind}" at step index ${i}`);
+    }
+
+    const pipelineCtx: PipelineCtx<TPayload, TMap> = {
+      ...handlerCtx,
+      event,
+      steps: stepsAcc,
+      scope: scopeAcc,
+      ...(workflow && {
+        workflow: { ...workflow, stepIndex: i },
+      }),
+    } as PipelineCtx<TPayload, TMap>;
+
+    const value = await stepDef.run(instance.args, pipelineCtx as unknown as PipelineCtx);
+
+    // Tier-3 suspension: the step wrote a waiting event and returned
+    // SUSPEND_SENTINEL to signal the pipeline should stop. The caller
+    // (defineWorkflow/workflow-engine) persists the suspension state.
+    if (value === SUSPEND_SENTINEL) {
+      return { kind: "suspended", stepIndex: i };
+    }
+
+    const key = stepDef.resultKey?.(instance.args);
+    if (key === RETURN_RESULT_KEY) {
+      return { kind: "return", result: value as WriteResult<unknown> };
+    }
+    if (key !== undefined) {
+      stepsAcc[key] = value;
+    }
+  }
+  return { kind: "exhausted" };
+}

package/src/engine/schema-builder.ts

@@ -60,6 +60,14 @@ function fieldToZod(field: FieldDefinition, currencies: readonly string[]): z.Zo
       const schema = z.number();
       return field.default !== undefined ? schema.default(field.default) : schema;
     }
+    case "bigInt": {
+      // JS-`number`-Round-trip via mode:"number"; sicher bis 2^53.
+      // safe-integer-Cap ist explizit damit ein Caller, der einen
+      // Float reinwirft (z.B. parseFloat-Bug), beim Insert sofort
+      // failed statt silent-Truncation zu kassieren.
+      const schema = z.number().int().safe();
+      return field.default !== undefined ? schema.default(field.default) : schema;
+    }
     case "money": {
       const [first, ...rest] = currencies;
       if (!first) throw new Error("No currencies configured");
@@ -165,10 +173,8 @@ export function buildUpdateSchema(
     // data via the event-store-executor's `changes` payload.
     // Cast widens the discriminated union so destructure works for variants
     // without a `default` field; remainder is structurally a FieldDefinition.
-    const { default: _default, ...stripped } = field as FieldDefinition & {
-      default?: unknown;
-    };
-    shape[name] = fieldToZod(stripped as FieldDefinition, currencies).optional();
+    const { default: _default, ...stripped } = field as FieldDefinition & { default?: unknown }; // @cast-boundary schema-walk
+    shape[name] = fieldToZod(stripped as FieldDefinition, currencies).optional(); // @cast-boundary schema-walk
   }
 
   return z.object(shape);

package/src/engine/state-machine.ts

@@ -36,7 +36,7 @@ export function defineTransitions<const TMap extends Record<string, readonly str
     canTransition: (from, to) => internal.get(from)?.has(to) === true,
     allowedFrom: (from) => {
       const set = internal.get(from);
-      return set ? ([...set] as TStates[]) : [];
+      return set ? ([...set] as TStates[]) : []; // @cast-boundary schema-walk
     },
     assertTransition: (from, to) => {
       const set = internal.get(from);