@cosmicdrift/kumiko-framework 0.2.3 → 0.3.0

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",
     },
@@ -1054,6 +1054,44 @@ const exposesApiSchema: PatternFormSchema = {
   ],
 };
 
+// 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" },
@@ -1113,8 +1151,10 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   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

@@ -173,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);

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