@cosmicdrift/kumiko-bundled-features 0.223.0 → 0.224.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.223.0",
+  "version": "0.224.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -124,15 +124,16 @@
     "./managed-pages/web": "./src/managed-pages/web/index.ts",
     "./managed-pages/seeding": "./src/managed-pages/seeding.ts",
     "./seo": "./src/seo/index.ts",
-    "./step-dispatcher": "./src/step-dispatcher/index.ts"
+    "./step-dispatcher": "./src/step-dispatcher/index.ts",
+    "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.223.0",
-    "@cosmicdrift/kumiko-framework": "0.223.0",
-    "@cosmicdrift/kumiko-headless": "0.223.0",
-    "@cosmicdrift/kumiko-renderer": "0.223.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.223.0",
-    "@cosmicdrift/kumiko-types": "0.223.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.224.0",
+    "@cosmicdrift/kumiko-framework": "0.224.0",
+    "@cosmicdrift/kumiko-headless": "0.224.0",
+    "@cosmicdrift/kumiko-renderer": "0.224.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.224.0",
+    "@cosmicdrift/kumiko-types": "0.224.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -161,7 +162,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.223.0",
-    "@cosmicdrift/kumiko-locale-es": "0.223.0"
+    "@cosmicdrift/kumiko-locale-de": "0.224.0",
+    "@cosmicdrift/kumiko-locale-es": "0.224.0"
   }
 }

package/src/workflow-runner/__tests__/workflow-runner.integration.test.ts

@@ -0,0 +1,155 @@
+// workflow-runner — event-triggered run-envelope integration test.
+//
+// Exercises registerEventTrigger end to end through a real event-dispatcher
+// pass: a raw domain event is inserted, stack.eventDispatcher.runOnce()
+// delivers it to the MSP, and the resulting run-envelope rows on the
+// workflow-run aggregate stream are asserted against real Postgres rows.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import {
+  computeDefinitionFingerprint,
+  defineFeature,
+  defineWorkflow,
+  stepsPipeline,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+  type WorkflowDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { workflowRunAggregateId } from "../aggregate-id";
+import { registerEventTrigger } from "../event-trigger";
+import { workflowRunnerFeature } from "../feature";
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+const happyWorkflow: WorkflowDefinition = defineWorkflow({
+  name: "wr-integration-happy",
+  trigger: { kind: "event", eventType: "wr-test.happy" },
+  idempotencyKey: ({ payload }) => (payload as { runKey: string }).runKey,
+  steps: stepsPipeline(({ r }) => [
+    r.step.compute("doubled", (ctx) => (ctx.event.payload as { n: number }).n * 2),
+    r.step.return({ isSuccess: true, data: undefined }),
+  ]),
+});
+
+const failingWorkflow: WorkflowDefinition = defineWorkflow({
+  name: "wr-integration-failure",
+  trigger: { kind: "event", eventType: "wr-test.failure" },
+  idempotencyKey: ({ payload }) => (payload as { runKey: string }).runKey,
+  steps: stepsPipeline(({ r }) => [
+    r.step.compute("boom", () => {
+      throw new Error("boom-explicit-failure");
+    }),
+    r.step.return({ isSuccess: true, data: undefined }),
+  ]),
+});
+
+const suspendingWorkflow: WorkflowDefinition = defineWorkflow({
+  name: "wr-integration-suspend",
+  trigger: { kind: "event", eventType: "wr-test.suspend" },
+  idempotencyKey: ({ payload }) => (payload as { runKey: string }).runKey,
+  steps: stepsPipeline(({ r }) => [
+    r.step.wait({ for: "PT1H" }),
+    r.step.return({ isSuccess: true, data: undefined }),
+  ]),
+});
+
+const testTriggersFeature = defineFeature("workflow-runner-integration-test-triggers", (r) => {
+  registerEventTrigger(r, happyWorkflow);
+  registerEventTrigger(r, failingWorkflow);
+  registerEventTrigger(r, suspendingWorkflow);
+});
+
+async function fireTrigger(eventType: string, payload: Record<string, unknown>): Promise<void> {
+  await insertOne(stack.db, eventsTable, {
+    aggregateId: crypto.randomUUID(),
+    aggregateType: "wr-test-source",
+    tenantId: admin.tenantId,
+    version: 1,
+    type: eventType,
+    eventVersion: 1,
+    payload,
+    metadata: { userId: admin.id },
+    createdBy: admin.id,
+  });
+  await stack.eventDispatcher?.runOnce();
+}
+
+async function loadRunEvents(runId: string) {
+  return selectMany(
+    stack.db,
+    eventsTable,
+    { aggregateId: runId },
+    { orderBy: { col: "version", direction: "asc" } },
+  );
+}
+
+describe("workflow-runner event-trigger", () => {
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [workflowRunnerFeature, testTriggersFeature] });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("happy path: no suspension writes run-started then run-completed with canonical payloads", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(happyWorkflow.name, runKey);
+
+    await fireTrigger("wr-test.happy", { runKey, n: 21 });
+
+    const rows = await loadRunEvents(runId);
+    expect(rows).toHaveLength(2);
+    expect(rows[0]!["type"]).toBe(WORKFLOW_RUN_STARTED_TYPE);
+    expect(rows[0]!["payload"]).toMatchObject({
+      workflowName: happyWorkflow.name,
+      triggerEventType: "wr-test.happy",
+      triggerPayload: { runKey, n: 21 },
+      definitionFingerprint: computeDefinitionFingerprint(happyWorkflow),
+    });
+    expect(rows[1]!["type"]).toBe(WORKFLOW_RUN_COMPLETED_TYPE);
+    expect(rows[1]!["payload"]).toEqual({
+      workflowName: happyWorkflow.name,
+      stepIndex: 2,
+    });
+  });
+
+  test("error path: a throwing step writes run-failed with the error text, no run-completed", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(failingWorkflow.name, runKey);
+
+    await fireTrigger("wr-test.failure", { runKey });
+
+    const rows = await loadRunEvents(runId);
+    expect(rows.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_RUN_FAILED_TYPE,
+    ]);
+    expect(rows[1]!["payload"]).toMatchObject({ workflowName: failingWorkflow.name, stepIndex: 0 });
+    expect(String(rows[1]!["payload"]["error"])).toContain("boom-explicit-failure");
+  });
+
+  test("suspension: a wait step fails the run instead of leaving it silently pending, no run-completed", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(suspendingWorkflow.name, runKey);
+
+    await fireTrigger("wr-test.suspend", { runKey });
+
+    const rows = await loadRunEvents(runId);
+    const types = rows.map((row) => row["type"]);
+    expect(types).toContain(WORKFLOW_RUN_STARTED_TYPE);
+    expect(types).not.toContain(WORKFLOW_RUN_COMPLETED_TYPE);
+    expect(types).toContain(WORKFLOW_RUN_FAILED_TYPE);
+
+    const failed = rows.find((row) => row["type"] === WORKFLOW_RUN_FAILED_TYPE)!;
+    const errorText = String(failed["payload"]["error"]);
+    expect(errorText).toContain("WorkflowSuspensionUnsupportedError");
+    expect(errorText).toContain(suspendingWorkflow.name);
+    expect(errorText).toContain("resume-loop");
+  });
+});

package/src/workflow-runner/aggregate-id.ts

@@ -0,0 +1,20 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Fixed UUID namespace for workflow-run aggregate-id derivation. Frozen —
+// changing it would re-key every existing run stream on replay.
+const WORKFLOW_RUN_NAMESPACE = "1f8a6c3e-7d2b-4a91-9e3f-5c8b2a41d6f0";
+
+/**
+ * Deterministic aggregate-id for a workflow run keyed by (workflowName,
+ * idempotencyKey). `aggregate_id` is a `uuid` column — a human-readable
+ * `wf-<name>-<key>` string isn't a valid value. Same key always maps to the
+ * same stream, which is what lets two *concurrent* triggers for that key
+ * race on `expectedVersion` and have the loser fail the unique constraint
+ * instead of silently double-running. It does NOT dedup sequential
+ * re-triggers of the same key — those land as version 2, 3, ... on the same
+ * stream and each starts its own run; that's out of scope for #2478.
+ */
+// @wrapper-known uuid-domain
+export function workflowRunAggregateId(workflowName: string, key: string): string {
+  return uuidv5(`${workflowName}|${key}`, WORKFLOW_RUN_NAMESPACE);
+}

package/src/workflow-runner/changes.json

@@ -0,0 +1 @@
+[]

package/src/workflow-runner/event-trigger.ts

@@ -0,0 +1,95 @@
+// event-trigger — MultiStreamProjection that listens for domain events and
+// starts + runs a workflow when the event matches its trigger.
+//
+// Registration pattern:
+//   registerEventTrigger(r, myWorkflow)
+//
+// The MSP apply-fn runs in the dispatcher's own tx, so `workflow.run-started`
+// plus the synchronous portion of the pipeline land atomically. Any throw
+// from startAndRunWorkflow — including WorkflowSuspensionUnsupportedError,
+// since no resume-loop is mounted yet (framework#2480) — is recorded as
+// `workflow.run-failed` and rethrown so the dispatcher's retry/dead-letter
+// handling still applies.
+
+import type {
+  FeatureRegistrar,
+  MultiStreamProjectionDefinition,
+  WorkflowDefinition,
+  WriteEvent,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { workflowRunAggregateId } from "./aggregate-id";
+import { startAndRunWorkflow, type WorkflowRunFailedPayload } from "./runner";
+
+export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefinition): void {
+  // skip: cron-triggered workflows have no domain event to project off — they
+  // need a scheduler, not an MSP, so there is nothing to register here.
+  if (workflow.trigger.kind !== "event") return;
+
+  const eventType = workflow.trigger.eventType;
+
+  r.multiStreamProjection({
+    name: `workflow-${workflow.name}`,
+    apply: {
+      [eventType]: async (event, _tx, ctx) => {
+        // skip: unreachable — the guard above already established this, but the
+        // closure does not carry that narrowing, and re-narrowing here keeps
+        // `trigger.filter` below typed without a cast.
+        if (workflow.trigger.kind !== "event") return;
+        if (workflow.trigger.filter) {
+          const matches = workflow.trigger.filter(event as never);
+          // skip: the workflow's own trigger filter rejected this event — not
+          // this run's concern, so no run is started and nothing is recorded.
+          if (!matches) return;
+        }
+
+        // @cast-boundary msp-to-write-event — the MSP delivers a StoredEvent
+        // (event-store shape); the workflow runner expects a WriteEvent
+        // (handler shape). The fields workflow steps read (type, payload)
+        // overlap exactly — the missing `.user` field is acceptable because
+        // workflow triggers run system-level, not user-scoped.
+        const triggerEvent = event as unknown as WriteEvent;
+        let idempotencyKey: string | undefined;
+        if (typeof workflow.idempotencyKey === "function") {
+          idempotencyKey = workflow.idempotencyKey(triggerEvent);
+        } else if (typeof workflow.idempotencyKey === "string") {
+          idempotencyKey = workflow.idempotencyKey;
+        }
+
+        const runId = idempotencyKey
+          ? workflowRunAggregateId(workflow.name, idempotencyKey)
+          : crypto.randomUUID();
+
+        try {
+          await startAndRunWorkflow({
+            runId,
+            workflow,
+            triggerEvent,
+            ...(idempotencyKey && { idempotencyKey }),
+            // @cast-boundary msp-to-handler-ctx — MultiStreamApplyContext only
+            // exposes unsafeAppendEvent/loadAggregate, a subset of
+            // HandlerContext. The step vocabulary this runner drives (wait,
+            // compute, return) only ever calls unsafeAppendEvent on it.
+            handlerCtx: ctx as never,
+          });
+        } catch (error) {
+          const failedPayload: WorkflowRunFailedPayload = {
+            workflowName: workflow.name,
+            stepIndex: 0,
+            error: String(error),
+          };
+          await ctx.unsafeAppendEvent({
+            aggregateId: runId,
+            aggregateType: WORKFLOW_AGGREGATE_TYPE,
+            type: WORKFLOW_RUN_FAILED_TYPE,
+            payload: failedPayload,
+          });
+          throw error;
+        }
+      },
+    },
+  } satisfies MultiStreamProjectionDefinition);
+}

package/src/workflow-runner/feature.ts

@@ -0,0 +1,32 @@
+// kumiko-feature-version: 1
+//
+// workflow-runner — writes the run-envelope (run-started / run-completed /
+// run-failed) for a workflow run onto its workflow-run aggregate stream.
+//
+// This feature registers no workflows of its own — consumers define a
+// WorkflowDefinition via `defineWorkflow` and wire it up with
+// `registerEventTrigger(r, myWorkflow)` inside their own feature. Mounting
+// `workflowRunnerFeature` documents that dependency and reserves the
+// picker/manifest slot; it has no MSPs or entities to register itself.
+//
+// No resume-loop is bundled yet (framework#2480) — workflows that use
+// suspending steps (wait / waitForEvent / retry) fail loud via
+// WorkflowSuspensionUnsupportedError instead of hanging silently.
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+// Kebab-case matching the "./workflow-runner" export subpath — every other
+// bundled feature's runtime name follows this convention, and
+// FEATURE_IMPORT_REGISTRY (use-all-bundled) keys off it.
+const FEATURE_NAME = "workflow-runner";
+
+export const workflowRunnerFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    "Writes the run-envelope (`workflow.run-started` / `workflow.run-completed` / `workflow.run-failed`) for a workflow run onto its `workflow-run` aggregate stream. Provides `startAndRunWorkflow` and `registerEventTrigger` for consumer features to wire up `defineWorkflow`-based workflows against domain events. Registers no workflows itself. No resume-loop is bundled yet (framework#2480) — suspending steps (wait/waitForEvent/retry) fail the run instead of pausing it.",
+  );
+  r.uiHints({
+    displayLabel: "Workflow Runner",
+    category: "infrastructure",
+    recommended: false,
+  });
+});

package/src/workflow-runner/index.ts

@@ -0,0 +1,12 @@
+// Public API of the workflow-runner bundled-feature.
+
+export { workflowRunAggregateId } from "./aggregate-id";
+export { registerEventTrigger } from "./event-trigger";
+export { workflowRunnerFeature } from "./feature";
+export {
+  startAndRunWorkflow,
+  type WorkflowRunCompletedPayload,
+  type WorkflowRunFailedPayload,
+  type WorkflowRunStartedPayload,
+  WorkflowSuspensionUnsupportedError,
+} from "./runner";

package/src/workflow-runner/runner.ts

@@ -0,0 +1,128 @@
+// runner — starts a workflow-run by writing run-started, executing the
+// pipeline until first suspension or completion, and writing run-completed.
+//
+// No resume-loop is mounted yet (framework#2480): a suspending step
+// (wait / waitForEvent / retry) would leave the run stuck forever with
+// nothing to wake it. startAndRunWorkflow surfaces that case as a loud
+// WorkflowSuspensionUnsupportedError instead of returning a silent
+// "suspended" outcome — callers (registerEventTrigger) treat it like any
+// other pipeline failure and record it as a failed run.
+
+import type {
+  HandlerContext,
+  WorkflowDefinition,
+  WriteEvent,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  buildPipelineSteps,
+  computeDefinitionFingerprint,
+  runStepList,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export type WorkflowRunStartedPayload = {
+  readonly workflowName: string;
+  readonly triggerEventType: string;
+  readonly triggerPayload: unknown;
+  readonly definitionFingerprint: string;
+  readonly idempotencyKey?: string;
+};
+
+// Canonical run-completed shape — the sample this was hoisted from had two
+// writers disagree (`{workflowName}` here, `{stepIndex}` in the not-yet-
+// mounted resume-loop). `stepIndex` is the pipeline's top-level step count
+// (sub-lists inside branch/forEach aren't counted); every run that reaches
+// this event ran to completion in one pass (suspension throws instead of
+// returning here).
+export type WorkflowRunCompletedPayload = {
+  readonly workflowName: string;
+  readonly stepIndex: number;
+};
+
+export type WorkflowRunFailedPayload = {
+  readonly workflowName: string;
+  readonly stepIndex: number;
+  readonly error: string;
+};
+
+export class WorkflowSuspensionUnsupportedError extends Error {
+  constructor(
+    readonly workflowName: string,
+    readonly stepIndex: number,
+  ) {
+    super(
+      `Workflow "${workflowName}" suspended at step ${stepIndex}, but no resume-loop is mounted to wake it (framework#2480) — the run would hang forever. Use only synchronous steps until a resume-loop is mounted.`,
+    );
+    this.name = "WorkflowSuspensionUnsupportedError";
+  }
+}
+
+/**
+ * Start + execute a workflow run.
+ *
+ * 1. Append `workflow.run-started` with the Q7 snapshot fingerprint.
+ * 2. Run the pipeline. If it suspends, throw — see module doc.
+ * 3. On completion, append `workflow.run-completed`. Throws from the
+ *    pipeline itself bubble up to the caller (event-trigger), which
+ *    records `workflow.run-failed`.
+ */
+export async function startAndRunWorkflow(args: {
+  readonly runId: string;
+  readonly workflow: WorkflowDefinition;
+  readonly triggerEvent: WriteEvent;
+  readonly idempotencyKey?: string;
+  readonly handlerCtx: HandlerContext;
+}): Promise<{ readonly outcome: "completed" }> {
+  const fingerprint = computeDefinitionFingerprint(args.workflow);
+
+  const startedPayload: WorkflowRunStartedPayload = {
+    workflowName: args.workflow.name,
+    triggerEventType: args.triggerEvent.type,
+    triggerPayload: args.triggerEvent.payload,
+    definitionFingerprint: fingerprint,
+    ...(args.idempotencyKey && { idempotencyKey: args.idempotencyKey }),
+  };
+
+  await args.handlerCtx.unsafeAppendEvent({
+    aggregateId: args.runId,
+    aggregateType: WORKFLOW_AGGREGATE_TYPE,
+    type: WORKFLOW_RUN_STARTED_TYPE,
+    payload: startedPayload,
+  });
+
+  const steps = buildPipelineSteps(args.workflow.pipelineDef, args.triggerEvent);
+
+  const outcome = await runStepList(
+    steps,
+    args.triggerEvent,
+    args.handlerCtx,
+    {},
+    {},
+    {
+      runId: args.runId,
+      workflowName: args.workflow.name,
+      stepIndex: 0,
+      definitionFingerprint: fingerprint,
+    },
+  );
+
+  if (outcome.kind === "suspended") {
+    throw new WorkflowSuspensionUnsupportedError(args.workflow.name, outcome.stepIndex);
+  }
+
+  const completedPayload: WorkflowRunCompletedPayload = {
+    workflowName: args.workflow.name,
+    stepIndex: steps.length,
+  };
+
+  await args.handlerCtx.unsafeAppendEvent({
+    aggregateId: args.runId,
+    aggregateType: WORKFLOW_AGGREGATE_TYPE,
+    type: WORKFLOW_RUN_COMPLETED_TYPE,
+    payload: completedPayload,
+  });
+
+  return { outcome: "completed" };
+}