@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/user-profile/web/profile-screen.tsx

@@ -0,0 +1,234 @@
+// @runtime client
+// Change-password and change-email sections for the declarative `profile`
+// projectionDetail screen (fw#2312, ../feature.ts). Both keep re-auth flows
+// a declarative action can't express, so they stay React `EditExtensionSection`
+// components; account deletion moved to declarative fields/actions on the
+// screen itself — same split as user-data-rights' privacy-center
+// (../../user-data-rights/web/privacy-center-screen.tsx), which this file
+// mirrors.
+
+import {
+  type ExtensionSectionProps,
+  useDispatcher,
+  usePrimitives,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { AuthHandlers } from "../../auth-email-password/constants.js";
+import { requestEmailVerification } from "../../auth-email-password/web/index.js";
+import { UserProfileHandlers } from "../constants.js";
+
+type SectionStatus =
+  | { kind: "idle" }
+  | { kind: "submitting" }
+  | { kind: "success"; messageKey: string }
+  | { kind: "error"; messageKey: string };
+
+// Dispatcher failures carry an i18nKey only when the handler sets one —
+// boundary read with a generic fallback.
+function failureKey(error: unknown): string {
+  const key = (error as { i18nKey?: unknown } | null)?.i18nKey; // @cast-boundary dispatcher-error
+  return typeof key === "string" ? key : "profile.errors.generic";
+}
+
+function StatusBanner({ status }: { readonly status: SectionStatus }): ReactNode {
+  const t = useTranslation();
+  const { Banner } = usePrimitives();
+  if (status.kind === "success") {
+    return <Banner variant="info">{t(status.messageKey)}</Banner>;
+  }
+  if (status.kind === "error") {
+    return <Banner variant="error">{t(status.messageKey)}</Banner>;
+  }
+  return null;
+}
+
+// Mounted by the renderer's ExtensionSectionMount (already wrapped in
+// <Section title={...} testId="section-extension-...">) — takes no props of
+// its own. Deliberately NOT a <Form>: RenderEdit already renders a host
+// <form> around the whole singleton screen (render-edit.tsx), so a second
+// nested <form> here is invalid DOM and silently degrades the submit button
+// into a native GET navigation instead of a write dispatch (same failure
+// mode write-form-section.tsx documents and avoids the same way — a plain
+// button click, not a second <form>).
+export function ChangePasswordSection(): ReactNode {
+  const t = useTranslation();
+  const { Field, Input, Button } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const [oldPassword, setOldPassword] = useState("");
+  const [newPassword, setNewPassword] = useState("");
+  const [confirm, setConfirm] = useState("");
+  const [status, setStatus] = useState<SectionStatus>({ kind: "idle" });
+
+  const onSubmit = (): void => {
+    void (async () => {
+      if (newPassword !== confirm) {
+        setStatus({ kind: "error", messageKey: "profile.password.mismatch" });
+        return;
+      }
+      setStatus({ kind: "submitting" });
+      const res = await dispatcher.write(AuthHandlers.changePassword, {
+        oldPassword,
+        newPassword,
+      });
+      if (!res.isSuccess) {
+        setStatus({ kind: "error", messageKey: failureKey(res.error) });
+        return;
+      }
+      setOldPassword("");
+      setNewPassword("");
+      setConfirm("");
+      setStatus({ kind: "success", messageKey: "profile.password.success" });
+    })();
+  };
+
+  const submitting = status.kind === "submitting";
+  return (
+    <div data-testid="profile-password" className="flex flex-col gap-4">
+      <Field id="profile-old-password" label={t("profile.password.old")} required>
+        <Input
+          kind="password"
+          id="profile-old-password"
+          name="profile-old-password"
+          value={oldPassword}
+          onChange={setOldPassword}
+          disabled={submitting}
+          required
+          autoComplete="current-password"
+        />
+      </Field>
+      <Field id="profile-new-password" label={t("profile.password.new")} required>
+        <Input
+          kind="password"
+          id="profile-new-password"
+          name="profile-new-password"
+          value={newPassword}
+          onChange={setNewPassword}
+          disabled={submitting}
+          required
+          autoComplete="new-password"
+        />
+      </Field>
+      <Field id="profile-confirm-password" label={t("profile.password.confirm")} required>
+        <Input
+          kind="password"
+          id="profile-confirm-password"
+          name="profile-confirm-password"
+          value={confirm}
+          onChange={setConfirm}
+          disabled={submitting}
+          required
+          autoComplete="new-password"
+        />
+      </Field>
+      <StatusBanner status={status} />
+      <div className="flex items-center justify-end gap-2">
+        <Button
+          type="button"
+          disabled={submitting}
+          onClick={() => onSubmit()}
+          testId="profile-password-submit"
+        >
+          {t("profile.password.submit")}
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+// Mounted by the renderer's ExtensionSectionMount analogous to
+// ChangePasswordSection above. `values.email` is the host projectionDetail's
+// current `me` row (seeded from the `user:query:user:me` query, ../feature.ts)
+// — ExtensionSectionProps carries no refetch hook, so a successful change
+// pushes the new address back into the host form via `patch` instead of
+// relying on a full-screen refetch to un-stale the "current email" line.
+export function ChangeEmailSection({ values, patch }: ExtensionSectionProps): ReactNode {
+  const t = useTranslation();
+  const { Field, Input, Button, Text } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const [newEmail, setNewEmail] = useState("");
+  const [currentPassword, setCurrentPassword] = useState("");
+  const [status, setStatus] = useState<SectionStatus>({ kind: "idle" });
+
+  const currentEmail = typeof values?.["email"] === "string" ? values["email"] : "";
+
+  const onSubmit = (): void => {
+    void (async () => {
+      setStatus({ kind: "submitting" });
+      const res = await dispatcher.write(UserProfileHandlers.changeEmail, {
+        currentPassword,
+        newEmail,
+      });
+      if (!res.isSuccess) {
+        setStatus({ kind: "error", messageKey: failureKey(res.error) });
+        return;
+      }
+      // Verification mail to the new address. The change is already
+      // persisted → a send failure must not reverse the success, but it is
+      // NOT swallowed (otherwise the user waits for a mail that never
+      // arrives). The success message accordingly promises no send.
+      try {
+        const verification = await requestEmailVerification(newEmail);
+        if (!verification.ok) {
+          // biome-ignore lint/suspicious/noConsole: operator-visibility for verification-send-failure
+          console.warn(
+            "[user-profile] email changed but the verification email could not be sent to the new address.",
+          );
+        }
+      } catch (err) {
+        // biome-ignore lint/suspicious/noConsole: operator-visibility for verification-send-failure
+        console.warn(
+          `[user-profile] email changed but the verification email send threw: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      patch?.({ email: newEmail });
+      setNewEmail("");
+      setCurrentPassword("");
+      setStatus({ kind: "success", messageKey: "profile.email.success" });
+    })();
+  };
+
+  const submitting = status.kind === "submitting";
+  return (
+    <div data-testid="profile-email" className="flex flex-col gap-4">
+      <Text variant="muted" testId="profile-email-current">
+        {t("profile.email.current")}: {currentEmail}
+      </Text>
+      <Field id="profile-new-email" label={t("profile.email.new")} required>
+        <Input
+          kind="email"
+          id="profile-new-email"
+          name="profile-new-email"
+          value={newEmail}
+          onChange={setNewEmail}
+          disabled={submitting}
+          required
+          autoComplete="email"
+        />
+      </Field>
+      <Field id="profile-email-password" label={t("profile.email.currentPassword")} required>
+        <Input
+          kind="password"
+          id="profile-email-password"
+          name="profile-email-password"
+          value={currentPassword}
+          onChange={setCurrentPassword}
+          disabled={submitting}
+          required
+          autoComplete="current-password"
+        />
+      </Field>
+      <StatusBanner status={status} />
+      <div className="flex items-center justify-end gap-2">
+        <Button
+          type="button"
+          disabled={submitting}
+          onClick={() => onSubmit()}
+          testId="profile-email-submit"
+        >
+          {t("profile.email.submit")}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/packages/bundled-features/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/packages/bundled-features/src/workflow-runner/changes.json

@@ -0,0 +1,20 @@
+[
+  {
+    "version": "0.337.0",
+    "type": "fix",
+    "title": "workflow resume batches due runs, tenant handover merges discovered rows per type",
+    "detail": "The workflow resume job now picks up at most 100 due runs per tick, oldest first, so a backlog drains over several ticks. Tenant handover merges rows discovered per entity type so each outgoing edge runs once per round."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "resume-run no longer appends run-failed to an already settled run",
+    "detail": "The workflow-runner's resume-run handler now checks whether a run is already settled before resolving the workflow definition. A second resume tick racing a finished run no longer appends a `run-failed` event after `run-completed` when the definition changed or was removed meanwhile. The `runId` payload is validated as a UUID, and the due-runs SELECT drops its ineffective `FOR UPDATE SKIP LOCKED`."
+  },
+  {
+    "version": "0.327.0",
+    "type": "breaking",
+    "title": "Workflow run-failed and retry.scheduled events store a generic error text instead of the raw error",
+    "migration": "The `error` field of workflow.run-failed and workflow.retry.scheduled events is now generic, \"workflow step failed (<error class>)\" (or \"(unknown error)\" for non-Error throwables), because the raw text can contain recipients or payload fragments and would survive an erase. The raw error goes to the log (namespace workflow-runner, and the framework logger for retry). Code that parses the `error` text must switch to `reason` (machine-readable, set for definition changes) or to the logs. Already stored events keep their old text. The texts for an unregistered workflow and a definition-fingerprint mismatch are unchanged. describeWorkflowStepError is exported from @cosmicdrift/kumiko-framework/engine."
+  }
+]

package/packages/bundled-features/src/workflow-runner/db/queries/due-runs.ts

@@ -0,0 +1,24 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+export type DueRow = { readonly run_id: string; readonly step_index: number };
+
+// Oldest first and capped, so a backlog after an outage drains over several
+// ticks instead of holding one tick's `concurrency: "skip"` slot for minutes.
+export const DUE_RUNS_BATCH_SIZE = 100;
+
+// Dedup happens solely via resume-run's VersionConflictError-checked claim
+// (ctx.tryAppendEvent on WORKFLOW_RESUMED) — a second dispatch for the same
+// row loses that race and no-ops. No row locks: in an autocommit statement
+// they would be released right after the SELECT and guard nothing.
+export async function selectDueWorkflowRunPending(
+  db: DbConnection,
+  tenantId: TenantId,
+): Promise<readonly DueRow[]> {
+  // kumiko-lint-ignore raw-sql tenant-scoped due-row pickup
+  return (await asRawClient(db).unsafe(
+    `SELECT run_id, step_index FROM workflow_run_pending WHERE tenant_id = $1 AND wake_at < now() ORDER BY wake_at ASC LIMIT ${DUE_RUNS_BATCH_SIZE}`,
+    [tenantId],
+  )) as readonly DueRow[];
+}

package/packages/bundled-features/src/workflow-runner/event-subscriber.ts

@@ -0,0 +1,113 @@
+// event-subscriber — wakes up pending waitForEvent suspensions when their
+// awaited domain event arrives (framework#2513 Phase 3b, D4 in
+// workflow-resume-loop.md).
+//
+// registerEventTrigger (event-trigger.ts) calls registerEventWakeup for
+// every workflow it registers, building ONE MultiStreamProjection PER
+// WORKFLOW from that workflow's own `awaits` declaration — not a single
+// shared MSP built by scanning the process-global workflow-registry.
+// Reason: the registrar throws synchronously if an MSP's apply-map is
+// empty at r.multiStreamProjection() call time (feature-ui-extensions.ts).
+// workflow-runner's own feature.ts is imported independently of whatever
+// app-specific feature module calls registerEventTrigger — a shared MSP
+// built by reading the registry inside feature.ts's registration would
+// depend on every awaits-declaring feature already having run
+// registerEventTrigger() first, which is an unenforced app-import-order
+// hazard. Building the map right here, from the `workflow` argument
+// already in hand, has no such hazard — same reasoning event-trigger.ts
+// already applies to the run-start MSP.
+//
+// This subscriber never resumes a run itself (D3, workflow-resume-loop.md):
+// the MultiStreamApplyContext it runs in has no callFeature/runStepList
+// access, only unsafeAppendEvent/loadAggregate. It writes triggerEventType
+// + triggerPayload + wakeAt=now() onto the matching pending row(s); the
+// existing resume-due-runs job (Phase 2) picks the row up on its next
+// cron tick — the one resume path stays exactly the one Phase 2 built.
+
+import { selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type {
+  FeatureRegistrar,
+  MultiStreamApplyFn,
+  MultiStreamProjectionDefinition,
+  WorkflowDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { evaluateEventMatch } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { workflowRunPendingTable } from "./tables.js";
+
+type CandidateRow = {
+  readonly runId: string;
+  readonly tenantId: string;
+  readonly stepIndex: number;
+  readonly matchExpr: unknown | null;
+};
+
+const log = createFallbackLogger("workflow-runner");
+
+// A row whose persisted matchExpr cannot be evaluated (unknown version from a
+// rolling deploy, corrupt AST) must not abort the whole projection: that would
+// block every other waiting run of this event type on the same event forever.
+function rowMatchesEvent(row: CandidateRow, eventType: string, payload: unknown): boolean {
+  if (!row.matchExpr) return true;
+  try {
+    return evaluateEventMatch(
+      // @cast-boundary engine-payload — matchExpr round-trips through
+      // jsonb as the EventMatch AST waitForEvent's `match` resolver
+      // persisted (see steps/wait-for-event.ts); evaluateEventMatch
+      // rejects a malformed shape itself.
+      row.matchExpr as Parameters<typeof evaluateEventMatch>[0],
+      payload,
+    );
+  } catch (error) {
+    log.error("workflow wakeup skipped a pending row with an unevaluable matchExpr", {
+      runId: row.runId,
+      stepIndex: row.stepIndex,
+      eventType,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return false;
+  }
+}
+
+const wakeupApply: MultiStreamApplyFn = async (event, tx) => {
+  const rows = await selectMany<CandidateRow>(tx, workflowRunPendingTable, {
+    tenantId: event.tenantId,
+    waitEventType: event.type,
+  });
+
+  for (const row of rows) {
+    const matches = rowMatchesEvent(row, event.type, event.payload);
+    // skip: this row's matchExpr rejected the event — not this row's
+    // resume, leave wakeAt/triggerEventType untouched.
+    if (!matches) continue;
+
+    await updateMany(
+      tx,
+      workflowRunPendingTable,
+      {
+        triggerEventType: event.type,
+        triggerPayload: event.payload,
+        wakeAt: getTemporal().Now.instant().toString(),
+      },
+      { tenantId: row.tenantId, runId: row.runId, stepIndex: row.stepIndex },
+    );
+  }
+};
+
+export function registerEventWakeup(r: FeatureRegistrar, workflow: WorkflowDefinition): void {
+  const eventTypes = Object.values(workflow.awaits ?? {});
+  // skip: no `awaits` declared — nothing to subscribe to, and an empty
+  // apply-map throws at r.multiStreamProjection() registration time.
+  if (eventTypes.length === 0) return;
+
+  const apply: Record<string, MultiStreamApplyFn> = {};
+  for (const eventType of eventTypes) {
+    apply[eventType] = wakeupApply;
+  }
+
+  r.multiStreamProjection({
+    name: `workflow-${workflow.name}-wakeup`,
+    apply,
+  } satisfies MultiStreamProjectionDefinition);
+}

package/packages/bundled-features/src/workflow-runner/event-trigger.ts

@@ -0,0 +1,121 @@
+// 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 apply-fn does NOT run in the dispatcher's cursor tx (the server's MSP
+// wiring uses the unbound pool), so `workflow.run-started` and the rest of
+// the pipeline are not atomic. A throw from startAndRunWorkflow is recorded
+// as `workflow.run-failed` and swallowed, so the dispatcher moves on.
+
+import type {
+  FeatureRegistrar,
+  MultiStreamProjectionDefinition,
+  WorkflowDefinition,
+  WriteEvent,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  describeWorkflowStepError,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { workflowRunAggregateId } from "./aggregate-id.js";
+import { registerEventWakeup } from "./event-subscriber.js";
+import { startAndRunWorkflow, type WorkflowRunFailedPayload } from "./runner.js";
+import { registerWorkflow } from "./workflow-registry.js";
+
+const log = createFallbackLogger("workflow-runner");
+
+export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefinition): void {
+  // Populate the workflow-registry unconditionally, before the event-trigger
+  // guard below — resume-run (framework#2513 Phase 2) looks workflows up by
+  // name regardless of trigger kind, and a cron-triggered workflow that never
+  // reaches the MSP branch still needs to be resumable.
+  registerWorkflow(workflow);
+
+  // Independent of trigger.kind — a cron-triggered workflow can still have
+  // waitForEvent steps in its pipeline (framework#2513 Phase 3b, D4).
+  registerEventWakeup(r, workflow);
+
+  // 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}`,
+    // Mounting an event-triggered workflow into an existing app must not
+    // replay the historical log and fire every side-effect step retroactively.
+    startFrom: "now",
+    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) {
+          log.warn("workflow run failed", {
+            runId,
+            workflowName: workflow.name,
+            stepIndex: 0,
+            error: String(error),
+          });
+          const failedPayload: WorkflowRunFailedPayload = {
+            workflowName: workflow.name,
+            stepIndex: 0,
+            error: describeWorkflowStepError(error),
+          };
+          await ctx.unsafeAppendEvent({
+            aggregateId: runId,
+            aggregateType: WORKFLOW_AGGREGATE_TYPE,
+            type: WORKFLOW_RUN_FAILED_TYPE,
+            payload: failedPayload,
+          });
+          // No rethrow: the failure is now durably recorded as
+          // workflow.run-failed. Rethrowing would make the dispatcher
+          // redeliver the same trigger event up to maxAttempts, re-running
+          // every side-effect step and eventually killing the consumer.
+        }
+      },
+    },
+  } satisfies MultiStreamProjectionDefinition);
+}

package/packages/bundled-features/src/workflow-runner/feature.ts

@@ -0,0 +1,96 @@
+// 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 also registers the resume loop (framework#2513 Phase 2 + 3b):
+//   - the workflow_run_pending MSP (Phase 1) materialises suspended
+//     wait/waitForEvent/retry steps into a pending-set table
+//   - the `resume-due-runs` cron job (perTenant) scans that table for
+//     `wakeAt < now()` rows and dispatches `resume-run` per row — the job
+//     itself does no resume logic, only SELECT + dispatch
+//   - the `resume-run` write handler (r.systemScope(), SYSTEM_ROLE-only)
+//     does the actual Q7-check + claim + pipeline re-entry
+//   - `registerEventTrigger` (event-trigger.ts) additionally registers an
+//     event-wakeup MSP per workflow that declares `awaits` — it marks the
+//     matching pending row due as soon as the awaited event arrives,
+//     instead of waiting out the full timeout (event-subscriber.ts)
+//
+// wait/retry/waitForEvent suspensions all resume automatically now.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { selectDueWorkflowRunPending } from "./db/queries/due-runs.js";
+import { resumeRunHandler } from "./handlers/resume-run.write.js";
+import { registerWorkflowRunPendingProjection } from "./pending-projection.js";
+import { workflowRunPendingTableMeta } from "./tables.js";
+
+// 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. Runs the resume loop for suspended `wait`/`retry`/`waitForEvent` steps (`resume-due-runs` job + `resume-run` handler); `registerEventTrigger` wires an event-wakeup subscriber per workflow that declares `awaits` so a `waitForEvent` step resumes as soon as its awaited event arrives, not just on timeout.",
+  );
+  r.uiHints({
+    displayLabel: "Workflow Runner",
+    category: "infrastructure",
+    recommended: false,
+  });
+  // resume-run needs a full HandlerContext + ctx.systemDb (the pending-row
+  // scan crosses whatever tenant the row belongs to relative to the job's
+  // own tenant loop iteration) — same reasoning as tenant/feature.ts.
+  r.systemScope();
+  r.storeTable(workflowRunPendingTableMeta, {
+    reason: "resume_loop.pending_suspended_steps",
+  });
+  registerWorkflowRunPendingProjection(r);
+  r.writeHandler(resumeRunHandler);
+
+  r.job(
+    "resume-due-runs",
+    { trigger: { cron: "* * * * *" }, perTenant: true, concurrency: "skip" },
+    async (_payload, ctx) => {
+      if (!ctx.systemDb) {
+        throw new Error("resume-due-runs: ctx.systemDb required (r.systemScope() feature)");
+      }
+      const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+      if (tenantId === undefined) {
+        // skip: cron fired without a perTenant fan-out tenant — nothing scoped
+        return;
+      }
+
+      ctx.systemDb.assertTenantMatch(tenantId);
+      const dueRows = await selectDueWorkflowRunPending(
+        ctx.systemDb.unsafeRaw(
+          "due-row pickup needs FOR UPDATE SKIP LOCKED raw SQL; the query filters by this job's tenantId",
+        ) as DbConnection, // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
+        tenantId,
+      );
+
+      for (const row of dueRows) {
+        try {
+          await ctx.write("workflow-runner:write:resume-run", {
+            runId: row.run_id,
+            stepIndex: row.step_index,
+          });
+        } catch (error) {
+          // skip: one row's dispatch failing (infra hiccup, not a business
+          // outcome — resume-run itself never throws for expected cases)
+          // must not stop the rest of this tenant's due rows from resuming.
+          ctx.log.warn(
+            `[workflow-runner:resume-due-runs] runId=${row.run_id} stepIndex=${row.step_index} dispatch failed: ${String(error)}`,
+          );
+        }
+      }
+    },
+  );
+});