@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/user-profile/index.ts

@@ -1,6 +1,6 @@
-// Bewusst OHNE i18n-Export: das Server-Barrel muss von Server-Samples
-// ohne jsx-tsconfig kompilierbar bleiben (i18n zieht kumiko-renderer →
-// .tsx). Translations kommen via ./web (userProfileClient).
+// Deliberately no i18n export: the server barrel must remain compilable by server samples
+// without a JSX tsconfig (i18n pulls in kumiko-renderer → .tsx). Translations are provided
+// through ./web (userProfileClient).
 
 export { createUserProfileFeature, type UserProfileFeatureOptions } from "./feature.ts";
 export {

package/packages/bundled-features/src/user-profile/web/client-plugin.ts

@@ -25,7 +25,7 @@ export type UserProfileClientFeature = {
 };
 
 // Supplies the ChangeEmail/ChangePassword extension components for the
-// declarative `profile` projectionDetail screen (fw#2312, ../feature.ts,
+// declarative `profile` projectionDetail screen (../feature.ts,
 // registered there server-side) plus the default translations. Apps add it
 // via createKumikoApp({ clientFeatures: [userProfileClient()] }) and place
 // the screen (id "profile") via r.nav — the screen itself has no r.nav of

package/packages/bundled-features/src/user-profile/web/constants.ts

@@ -5,7 +5,7 @@ export const USER_PROFILE_FEATURE = "user-profile" as const;
 
 export const PROFILE_SCREEN_ID = "profile" as const;
 
-// EditExtensionSection `__component` markers (fw#2312) — change-password and
+// EditExtensionSection `__component` markers — change-password and
 // change-email stay React components (re-auth flows a declarative action
 // can't express); deletion moved to declarative fields/actions on the screen
 // itself (feature.ts), same split as user-data-rights' privacy-center.

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

@@ -1,5 +1,5 @@
 // Change-password and change-email sections for the declarative `profile`
-// projectionDetail screen (fw#2312, ../feature.ts). Both keep re-auth flows
+// projectionDetail screen (../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

package/packages/bundled-features/src/workflow-runner/aggregate-id.ts

@@ -12,7 +12,7 @@ const WORKFLOW_RUN_NAMESPACE = "1f8a6c3e-7d2b-4a91-9e3f-5c8b2a41d6f0";
  * 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.
+ * stream and each starts its own run; that's out of scope.
  */
 // @wrapper-known uuid-domain
 export function workflowRunAggregateId(workflowName: string, key: string): string {

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

@@ -1,6 +1,5 @@
 // event-subscriber — wakes up pending waitForEvent suspensions when their
-// awaited domain event arrives (framework#2513 Phase 3b, D4 in
-// workflow-resume-loop.md).
+// awaited domain event arrives (in workflow-resume-loop.md).
 //
 // registerEventTrigger (event-trigger.ts) calls registerEventWakeup for
 // every workflow it registers, building ONE MultiStreamProjection PER
@@ -17,12 +16,12 @@
 // 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):
+// This subscriber never resumes a run itself (in workflow-resume-loop.md):
 // the MultiStreamApplyContext it runs in has no callFeature/runStepList
 // access, only unsafeAppendEvent/loadAggregate. It writes triggerEventType
 // + triggerEventRef + 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.
+// existing resume-due-runs job picks the row up on its next
+// cron tick — the resume path remains unchanged.
 
 import { selectMany, updateMany } from "@cosmicdrift/kumiko-framework/db";
 import type {

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

@@ -26,6 +26,7 @@ import {
   WORKFLOW_AGGREGATE_TYPE,
   WORKFLOW_RUN_FAILED_TYPE,
   WorkflowStepError,
+  walkStepInstances,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { workflowRunAggregateId } from "./aggregate-id.ts";
@@ -51,18 +52,6 @@ const STEP_KINDS_NEEDING_HANDLER_CONTEXT: ReadonlySet<string> = new Set([
   "unsafeProjectionDelete",
 ]);
 
-function* walkStepInstances(steps: readonly StepInstance[]): Generator<StepInstance, void, void> {
-  for (const step of steps) {
-    yield step;
-    const { args } = step;
-    if (typeof args !== "object" || args === null) continue;
-    for (const path of getStep(step.kind)?.subPaths ?? []) {
-      const nested: unknown = path in args ? Reflect.get(args, path) : undefined;
-      if (Array.isArray(nested)) yield* walkStepInstances(nested);
-    }
-  }
-}
-
 export function assertEventTriggerStepsSupported(workflow: WorkflowDefinition): void {
   let steps: readonly StepInstance[];
   try {
@@ -80,7 +69,7 @@ export function assertEventTriggerStepsSupported(workflow: WorkflowDefinition):
       { cause: error },
     );
   }
-  for (const step of walkStepInstances(steps)) {
+  for (const step of walkStepInstances(steps, `workflow "${workflow.name}" eventTrigger`)) {
     if (getStep(step.kind) === undefined) {
       throw new Error(`Workflow "${workflow.name}" uses unknown step kind "${step.kind}"`);
     }
@@ -95,13 +84,13 @@ export function assertEventTriggerStepsSupported(workflow: WorkflowDefinition):
 
 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
+  // guard below — resume-run 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).
+  // waitForEvent steps in its pipeline.
   registerEventWakeup(r, workflow);
 
   // skip: cron-triggered workflows have no domain event to project off — they

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

@@ -9,8 +9,8 @@
 // `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
+// It also registers the resume loop:
+//   - the workflow_run_pending MSP 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

package/packages/bundled-features/src/workflow-runner/handlers/resume-run.write.ts

@@ -1,10 +1,10 @@
 // resume-run — wakes one suspended workflow step. Dispatched by the
-// resume-due-runs job (framework#2513 Phase 2), never called directly by a
+// resume-due-runs job, never called directly by a
 // user — r.systemScope() + access: { roles: [SYSTEM_ROLE] } enforce that.
 //
 // The job does nothing but SELECT + dispatch; all resume logic lives here,
 // adapted from samples/recipes/workflow-engine/src/resume-loop.ts:
-//   1. Q7 fingerprint check FIRST — before claiming, before any pipeline
+//   1. Fingerprint check FIRST — before claiming, before any pipeline
 //      work. A changed workflow definition fails loud (WORKFLOW_RUN_FAILED,
 //      reason "workflow_definition_changed"), never a silent skip.
 //   2. Claim via a savepoint-scoped WORKFLOW_RESUMED append (ctx.tryAppendEvent,
@@ -23,8 +23,8 @@
 // shows up here in its shredded form, and an unloadable one (archived
 // stream) fails the run. The pending row's own
 // triggerEventType/triggerEventRef columns are a DIFFERENT thing: for a
-// waitForEvent suspension they point at the AWAITED event the Phase 3b
-// event-subscriber matched (NULL until then, and NULL forever on a
+// waitForEvent suspension they point at the AWAITED event the event-subscriber
+// matched (NULL until then, and NULL forever on a
 // timeout-without-a-match). That event's payload becomes the resumed
 // pipeline's result for the skipped waitForEvent step itself (see
 // resultKey on steps/wait-for-event.ts) — pre-seeded into stepsAcc below so

package/packages/bundled-features/src/workflow-runner/pending-projection.ts

@@ -4,13 +4,12 @@
 // Insert (upsert, for idempotent at-least-once redelivery) on every
 // suspension: wait, waitForEvent, retry. Delete on WORKFLOW_RESUMED or a
 // terminal run outcome (completed/failed) — a run only ever has one row
-// pending at a time (D1: a later suspension always targets a fresh
-// stepIndex, since the prior one was resumed away first), so deleting by
+// pending at a time (a later suspension always targets a fresh stepIndex,
+// since the prior one was resumed away first), so deleting by
 // (tenantId, runId) alone is exact.
 //
-// No resume logic here — framework#2513 Phase 2 owns the job that reads
-// this table and dispatches the actual resume. This projection only writes
-// the rows.
+// No resume logic here — the job that reads this table and dispatches the
+// actual resume is separate. This projection only writes the rows.
 
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { deleteMany, fetchOne, upsertOnConflict } from "@cosmicdrift/kumiko-framework/db";
@@ -81,8 +80,8 @@ async function upsertPending(tx: DbRunner, row: PendingRow): Promise<void> {
     workflowRunPendingTable,
     {
       ...row,
-      // Phase 3's event-subscriber writes these when the awaited event
-      // arrives — Phase 1 never touches them, insert or update.
+      // The event-subscriber writes these when the awaited event
+      // arrives — they are never touched here, on insert or update.
       triggerEventType: null,
       triggerEventRef: null,
       triggerPayload: null,

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

@@ -2,12 +2,12 @@
 // pipeline until first suspension or completion, and writing run-completed.
 //
 // wait / retry / waitForEvent suspensions are all resumable — the
-// resume-due-runs job + resume-run handler (framework#2513 Phase 2) wake
-// wait/retry via a plain wakeAt timeout; waitForEvent additionally gets
-// woken early by the event-subscriber (Phase 3b, event-subscriber.ts) when
-// its awaited event arrives, and by the same wakeAt timeout otherwise
-// (D1's `wakeAt ?? timeoutAt`). startAndRunWorkflow returns a silent
-// "suspended" outcome for all three instead of throwing.
+// resume-due-runs job + resume-run handler wake wait/retry via a plain
+// wakeAt timeout; waitForEvent additionally gets woken early by the
+// event-subscriber (event-subscriber.ts) when its awaited event arrives,
+// and by the same wakeAt timeout otherwise (D1's `wakeAt ?? timeoutAt`).
+// startAndRunWorkflow returns a silent "suspended" outcome for all three
+// instead of throwing.
 
 import type {
   HandlerContext,

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

@@ -12,12 +12,12 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 
 // workflow_run_pending — one row per currently-suspended workflow step.
-// Read-side of the resume loop (framework#2513 Phase 1): the wait /
+// Read-side of the resume loop: the wait /
 // waitForEvent / retry steps already write their suspension onto the
 // workflow-run event stream, but scanning kumiko_events for due runs
 // doesn't scale (see samples/recipes/workflow-engine/postgres-resume-loop.ts,
 // which does exactly that). This table is kept in sync by
-// pending-projection.ts's MultiStreamProjection so Phase 2's resume job can
+// pending-projection.ts's MultiStreamProjection so the resume job can
 // do an indexed `wakeAt < now()` scan instead.
 //
 // **Unmanaged table** — same reasoning as delivery/tables.ts'
@@ -31,7 +31,7 @@ import {
 // key only, see aggregate-id.ts), so two tenants triggering the same
 // workflow with the same idempotencyKey get the SAME run_id. Without
 // tenant_id in the key, a same-stepIndex suspension from tenant B would
-// upsert onto tenant A's row and silently steal it (framework#2513).
+// upsert onto tenant A's row and silently steal it.
 export const workflowRunPendingTable = pgTable(
   "workflow_run_pending",
   {
@@ -45,14 +45,14 @@ export const workflowRunPendingTable = pgTable(
     // which step suspended.
     wakeAt: instant("wake_at").notNull(),
     retryAttempt: integer("retry_attempt"),
-    // Q7 snapshot fingerprint — Phase 2 compares this against the current
+    // Snapshot fingerprint — compares this against the current
     // workflow definition's fingerprint before resuming.
     definitionFingerprint: text("definition_fingerprint"),
     // Set only for waitForEvent suspensions; NULL for wait/retry.
     waitEventType: text("wait_event_type"),
     matchExpr: jsonb("match_expr"),
-    // Written by the Phase 3 event-subscriber when the awaited event
-    // arrives — always NULL in Phase 1/2. The row points at the awaited event
+    // Written by the event subscriber when the awaited event
+    // arrives — always NULL initially. The row points at the awaited event
     // ({ eventId, aggregateId, version }); resume-run re-reads it from the
     // event store, so erasing the event also covers the workflow.
     triggerEventType: text("trigger_event_type"),

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

@@ -1,6 +1,6 @@
 // workflow-registry — process-local lookup from workflow name to its
 // WorkflowDefinition. registerEventTrigger populates it at feature-
-// registration time; resume-run (Phase 2) is the only reader — it has
+// registration time; resume-run is the only reader — it has
 // nothing but a workflow name on the pending row and needs the live
 // definition to rebuild the pipeline + recompute the Q7 fingerprint.
 //