@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/src/engine/steps/read-find-many.ts

@@ -0,0 +1,51 @@
+// r.step.read.findMany — load multiple rows from a projection table.
+//
+// Sibling to read.findOne — same tenant-filter caveat (caller-owned),
+// same drizzle-boundary cast. Resolves to a row-array (possibly empty),
+// landed under steps.<name>.
+//
+// Optional `limit` — defaults to no-limit (caller-chosen, NOT a
+// guard-rail). Most legitimate uses iterate via r.step.forEach (M.1.6)
+// over the result, where unbounded arrays would be the bug. Set
+// `limit` explicitly when the row-count could grow without bound.
+
+import type { SQL, Table } from "drizzle-orm";
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { asQueryTarget } from "./_drizzle-boundary";
+import { resolveOptional } from "./_resolver-utils";
+
+type ReadFindManyArgs = {
+  readonly name: string;
+  readonly table: Table;
+  readonly where?: StepResolver<SQL | undefined>;
+  readonly limit?: number;
+};
+
+defineStep<ReadFindManyArgs, readonly Record<string, unknown>[]>({
+  kind: "read.findMany",
+  defaultFailureStrategy: "throw",
+  resultKey: (args) => args.name,
+  run: async (args, ctx: PipelineCtx) => {
+    const where = resolveOptional(args.where, ctx);
+    const baseQuery = ctx.db.select().from(asQueryTarget(args.table));
+    const filteredQuery = where === undefined ? baseQuery : baseQuery.where(where);
+    const finalQuery = args.limit === undefined ? filteredQuery : filteredQuery.limit(args.limit);
+    const rows = await finalQuery;
+    return rows as readonly Record<string, unknown>[];
+  },
+});
+
+export function buildReadFindManyStep(
+  name: string,
+  opts: {
+    readonly table: Table;
+    readonly where?: StepResolver<SQL | undefined>;
+    readonly limit?: number;
+  },
+): StepInstance {
+  return {
+    kind: "read.findMany",
+    args: { name, ...opts } satisfies ReadFindManyArgs,
+  };
+}

package/src/engine/steps/read-find-one.ts

@@ -0,0 +1,58 @@
+// r.step.read.findOne — load a single row from a projection table.
+//
+// Thin wrapper on ctx.db.select().from(table).where(where).limit(1).
+// Resolves to the first row or null. Tenant-isolation: the caller's
+// `where` clause is responsible for any tenantId filter — read.findOne
+// does NOT auto-inject one (different from ctx.queryProjection which
+// does). That's deliberate: most read-step uses are aggregate-lookups
+// where the where-clause already pins a uuid that's globally unique;
+// auto-tenant-filtering would be redundant and would surprise users
+// who pass an explicit tenantId.
+//
+// Use when a subsequent step needs a row from the read-side. For
+// cross-feature reads, prefer `r.step.callFeature(...)` (M.2) so the
+// other feature's query-handler runs (with its access-rules + audit).
+//
+// `where` should resolve to a clause that matches at most one row
+// (typical: equality on PK / unique-constraint). When multiple rows
+// satisfy the clause, the LIMIT 1 picks one in driver-defined order
+// (Postgres: insertion order in practice, but not specified) — that's
+// fine for "find by uuid", a footgun for "find by tenantId". No
+// runtime check; reviewer responsibility.
+
+import type { SQL, Table } from "drizzle-orm";
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { asQueryTarget } from "./_drizzle-boundary";
+import { resolveRequired } from "./_resolver-utils";
+
+type ReadFindOneArgs = {
+  readonly name: string;
+  readonly table: Table;
+  readonly where: StepResolver<SQL | undefined>;
+};
+
+defineStep<ReadFindOneArgs, Record<string, unknown> | null>({
+  kind: "read.findOne",
+  defaultFailureStrategy: "throw",
+  resultKey: (args) => args.name,
+  run: async (args, ctx: PipelineCtx) => {
+    const where = resolveRequired(args.where, ctx);
+    const query = ctx.db.select().from(asQueryTarget(args.table));
+    const rows = where === undefined ? await query.limit(1) : await query.where(where).limit(1);
+    return (rows[0] as Record<string, unknown> | undefined) ?? null;
+  },
+});
+
+export function buildReadFindOneStep(
+  name: string,
+  opts: {
+    readonly table: Table;
+    readonly where: StepResolver<SQL | undefined>;
+  },
+): StepInstance {
+  return {
+    kind: "read.findOne",
+    args: { name, ...opts } satisfies ReadFindOneArgs,
+  };
+}

package/src/engine/steps/retry.ts

@@ -0,0 +1,87 @@
+// r.step.retry — wrap a sub-pipeline with retry+backoff.
+// Tier-3 / Workflow-only: only available inside defineWorkflow.
+//
+// On first execution, runs the `do` sub-pipeline inside a try-catch.
+// If it throws and retries remain, writes a kumiko:system:workflow.retry.scheduled
+// event and returns SUSPEND_SENTINEL to suspend. The Resume-Loop picks it up
+// after the backoff duration and re-enters the step at the same index.
+// After all attempts exhausted, the original error propagates.
+
+import { defineStep } from "../define-step";
+import { runStepList } from "../run-pipeline";
+import type { PipelineCtx, StepInstance } from "../types/step";
+import {
+  SUSPEND_SENTINEL,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+} from "./_step-dispatch-constants";
+
+type RetryStepArgs = {
+  readonly times: number;
+  readonly backoff: "exponential" | "linear";
+  readonly do: readonly StepInstance[];
+};
+
+defineStep<RetryStepArgs, undefined | typeof SUSPEND_SENTINEL>({
+  kind: "workflow.retry",
+  tier: 3,
+  defaultFailureStrategy: "throw",
+  subPaths: ["do"],
+  run: async (args, ctx: PipelineCtx): Promise<undefined | typeof SUSPEND_SENTINEL> => {
+    if (!ctx.workflow) {
+      throw new Error(
+        "r.step.retry is only allowed inside defineWorkflow — " + "sync handlers cannot suspend.",
+      );
+    }
+
+    const stepsAcc = ctx.steps as Record<string, unknown>;
+    const scopeAcc = ctx.scope as Record<string, unknown>;
+    const maxAttempts = args.times;
+    const attempt = ctx.workflow.retryAttempt ?? 1;
+
+    try {
+      await runStepList(args.do, ctx.event, ctx, stepsAcc, scopeAcc, ctx.workflow);
+      return undefined;
+    } catch (error) {
+      if (attempt >= maxAttempts) {
+        throw error;
+      }
+
+      const backoffMs = calculateBackoff(attempt, args.backoff);
+      const wakeAt = Temporal.Now.instant().add({ milliseconds: backoffMs }).toString();
+
+      await ctx.unsafeAppendEvent({
+        aggregateId: ctx.workflow.runId,
+        aggregateType: WORKFLOW_AGGREGATE_TYPE,
+        type: WORKFLOW_RETRY_SCHEDULED_TYPE,
+        payload: {
+          stepIndex: ctx.workflow.stepIndex,
+          attempt,
+          maxAttempts,
+          wakeAt,
+          workflowName: ctx.workflow.workflowName,
+          error: String(error),
+          triggerEventType: ctx.event.type,
+          triggerPayload: ctx.event.payload,
+          ...(ctx.workflow.definitionFingerprint && {
+            definitionFingerprint: ctx.workflow.definitionFingerprint,
+          }),
+        },
+      });
+
+      return SUSPEND_SENTINEL;
+    }
+  },
+});
+
+export function buildRetryStep(args: RetryStepArgs): StepInstance {
+  return { kind: "workflow.retry", args };
+}
+
+export function calculateBackoff(attempt: number, strategy: "exponential" | "linear"): number {
+  const baseMs = 10_000;
+  if (strategy === "linear") {
+    return baseMs * attempt;
+  }
+  return baseMs * 2 ** (attempt - 1);
+}

package/src/engine/steps/return.ts

@@ -0,0 +1,34 @@
+// r.step.return — terminate the pipeline with an explicit WriteResult.
+//
+// Most pipelines end with a return so the handler shape stays explicit
+// (`isSuccess: true, data: {...}`). When a pipeline omits an explicit
+// return, run-pipeline throws — silent fallthrough would mask the most
+// common authoring mistake (forgotten r.step.return at the end).
+
+import { defineStep } from "../define-step";
+import type { WriteResult } from "../types/handlers";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { resolveRequired } from "./_resolver-utils";
+
+type ReturnStepArgs = {
+  readonly resolver: StepResolver<WriteResult<unknown>>;
+};
+
+// Sentinel result-key consumed by run-pipeline to detect "this step
+// terminates the pipeline with this WriteResult". Leading double-underscore
+// is reserved for runtime-internal results — user code can't collide.
+export const RETURN_RESULT_KEY = "__return";
+
+defineStep<ReturnStepArgs, WriteResult<unknown>>({
+  kind: "return",
+  defaultFailureStrategy: "throw",
+  resultKey: () => RETURN_RESULT_KEY,
+  run: (args, ctx: PipelineCtx) => resolveRequired(args.resolver, ctx),
+});
+
+export function buildReturnStep<TData>(resolver: StepResolver<WriteResult<TData>>): StepInstance {
+  return {
+    kind: "return",
+    args: { resolver } satisfies ReturnStepArgs,
+  };
+}

package/src/engine/steps/unsafe-projection-delete.ts

@@ -0,0 +1,46 @@
+// r.step.unsafeProjectionDelete — delete row(s) from a read-side
+// projection table.
+//
+// Sibling to unsafeProjectionUpsert with the same boot-validation
+// contract: target table must be in the owning feature's
+// r.requires.projection allowlist, must NOT be a registered
+// r.entity-aggregate-table. Skips the same set of framework-protections
+// (lifecycle hooks, field-access, audit-trail, etc.) — see
+// step-vocabulary.md "Was unsafeProjection.* überspringt".
+//
+// Convention (not enforced): most legitimate read-side deletions are
+// downstream of an aggregate event (e.g. delete-user → cascading
+// subscription rows vanish). The right home for those is
+// `r.multiStreamProjection.apply` keyed on the aggregate event, not
+// an inline-step. The inline-step is appropriate when the deletion
+// must commit in the same TX as the aggregate-mutation that triggered
+// it (stronger consistency than an async projection). Reviewer judges.
+
+import type { SQL, Table } from "drizzle-orm";
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { asQueryTarget } from "./_drizzle-boundary";
+import { resolveRequired } from "./_resolver-utils";
+
+// `where` is REQUIRED — table-wide DELETE without a clause is a TRUNCATE
+// in disguise, exactly the footgun the `unsafe`-prefix is meant to
+// surface. If a real use-case needs full-table purge, add an explicit
+// `r.step.unsafeProjectionTruncate` step rather than loosening this
+// type to `SQL | undefined`.
+type UnsafeProjectionDeleteArgs = {
+  readonly table: Table;
+  readonly where: StepResolver<SQL>;
+};
+
+defineStep<UnsafeProjectionDeleteArgs, void>({
+  kind: "unsafeProjectionDelete",
+  defaultFailureStrategy: "throw",
+  run: async (args, ctx: PipelineCtx) => {
+    const where = resolveRequired(args.where, ctx);
+    await ctx.db.delete(asQueryTarget(args.table)).where(where);
+  },
+});
+
+export function buildUnsafeProjectionDeleteStep(args: UnsafeProjectionDeleteArgs): StepInstance {
+  return { kind: "unsafeProjectionDelete", args };
+}

package/src/engine/steps/unsafe-projection-upsert.ts

@@ -0,0 +1,69 @@
+// r.step.unsafeProjectionUpsert — inline read-side-projection write.
+//
+// Idempotent on the supplied conflict-key columns (typically the
+// natural key + tenantId). Skips lifecycle hooks, field-access,
+// crypto-shredding, schema-versioning, audit-trail, read-access-log.
+// See "Was unsafeProjection.* überspringt" in
+// docs/plans/architecture/intern/step-vocabulary.md.
+//
+// Use only on tables explicitly declared via r.requires.projection in
+// the owning feature. Aggregate-tables (registered via r.entity) are
+// rejected by boot-validation — domain mutation MUST go through
+// r.step.aggregate.*.
+
+import { getTableColumns, type Table } from "drizzle-orm";
+import type { PgColumn } from "drizzle-orm/pg-core";
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { asQueryTarget } from "./_drizzle-boundary";
+import { resolveRequired } from "./_resolver-utils";
+
+type UnsafeProjectionUpsertArgs = {
+  readonly table: Table;
+  readonly on: readonly string[];
+  readonly row: StepResolver<Record<string, unknown>>;
+};
+
+defineStep<UnsafeProjectionUpsertArgs, void>({
+  kind: "unsafeProjectionUpsert",
+  defaultFailureStrategy: "throw",
+  run: async (args, ctx: PipelineCtx) => {
+    const resolvedRow = resolveRequired(args.row, ctx);
+
+    const columns = getTableColumns(args.table) as Record<string, unknown>;
+    const conflictTargets = args.on.map((key) => {
+      const col = columns[key];
+      if (!col) {
+        throw new Error(`unsafeProjectionUpsert: column "${key}" not found on target table`);
+      }
+      return col;
+    });
+
+    // SET clause is the same row minus the conflict-key columns —
+    // updating a key to itself is harmless but verbose.
+    const updateSet: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(resolvedRow)) {
+      if (!args.on.includes(k)) updateSet[k] = v;
+    }
+
+    // @cast-boundary drizzle-bridge — The values + set + target casts
+    // cross the drizzle type-boundary for the same reason as
+    // asQueryTarget: resolvedRow is Record<string, unknown> by design
+    // (M.1 phantom-typing limit), drizzle's typed-builder expects
+    // table-specific shapes. Step-author owns shape correctness.
+    // `as never` (not `as any`) — never is contravariantly assignable to
+    // every drizzle Insert-shape; explicit "this bypass cannot be made
+    // type-safe without lifting <TTable extends Table>" marker.
+    await ctx.db
+      .insert(asQueryTarget(args.table))
+      .values(resolvedRow as never)
+      .onConflictDoUpdate({
+        target: conflictTargets as unknown as PgColumn[],
+        set: updateSet as never,
+      });
+  },
+});
+
+export function buildUnsafeProjectionUpsertStep(args: UnsafeProjectionUpsertArgs): StepInstance {
+  return { kind: "unsafeProjectionUpsert", args };
+}

package/src/engine/steps/wait-for-event.ts

@@ -0,0 +1,71 @@
+// r.step.waitForEvent — suspend the workflow until a matching domain event
+// is observed, or a timeout expires.
+// Tier-3 / Workflow-only: only available inside defineWorkflow.
+//
+// Writes a kumiko:system:workflow.step.waiting-for-event event onto the
+// workflow-run stream and returns the SUSPEND_SENTINEL. The Resume-Loop
+// monitors for matching events (via subscription or poll); when matched,
+// it writes workflow.step.resumed with the matched event's data.
+//
+// The `match` resolver is optional — when omitted, any event of the given
+// type resumes the workflow. When provided, it receives the event payload
+// and must return true for the event to trigger resume.
+
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { addDuration } from "./_duration-utils";
+import { resolveRequired } from "./_resolver-utils";
+import {
+  SUSPEND_SENTINEL,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_WAITING_FOR_EVENT_TYPE,
+} from "./_step-dispatch-constants";
+
+type WaitForEventArgs = {
+  readonly event: string;
+  readonly match?: StepResolver<(payload: unknown) => boolean>;
+  readonly timeout: StepResolver<string>;
+};
+
+defineStep<WaitForEventArgs, undefined | typeof SUSPEND_SENTINEL>({
+  kind: "workflow.waitForEvent",
+  tier: 3,
+  defaultFailureStrategy: "throw",
+  run: async (args, ctx: PipelineCtx): Promise<undefined | typeof SUSPEND_SENTINEL> => {
+    if (!ctx.workflow) {
+      throw new Error(
+        "r.step.waitForEvent is only allowed inside defineWorkflow — " +
+          "sync handlers cannot suspend.",
+      );
+    }
+
+    const timeout = resolveRequired(args.timeout, ctx);
+
+    const now = Temporal.Now.instant().toString();
+    const timeoutAt =
+      timeout.startsWith("P") || timeout.startsWith("PT") ? addDuration(now, timeout) : timeout;
+
+    await ctx.unsafeAppendEvent({
+      aggregateId: ctx.workflow.runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      type: WORKFLOW_WAITING_FOR_EVENT_TYPE,
+      payload: {
+        eventType: args.event,
+        timeoutAt,
+        stepIndex: ctx.workflow.stepIndex,
+        workflowName: ctx.workflow.workflowName,
+        triggerEventType: ctx.event.type,
+        triggerPayload: ctx.event.payload,
+        ...(ctx.workflow.definitionFingerprint && {
+          definitionFingerprint: ctx.workflow.definitionFingerprint,
+        }),
+      },
+    });
+
+    return SUSPEND_SENTINEL;
+  },
+});
+
+export function buildWaitForEventStep(args: WaitForEventArgs): StepInstance {
+  return { kind: "workflow.waitForEvent", args };
+}

package/src/engine/steps/wait.ts

@@ -0,0 +1,69 @@
+// r.step.wait — suspend the workflow run for a given duration.
+// Tier-3 / Workflow-only: only available inside defineWorkflow.
+//
+// Writes a kumiko:system:workflow.step.waiting event onto the workflow-run
+// stream and returns the SUSPEND_SENTINEL to halt the pipeline. The
+// Resume-Loop picks up waiting runs when the duration expires, writes
+// workflow.step.resumed, and re-executes from the next step.
+//
+// The `for` resolver accepts ISO-8601 duration strings ("PT1H", "P1D")
+// or absolute ISO timestamps ("2026-05-16T12:00:00Z").
+
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { addDuration } from "./_duration-utils";
+import { resolveRequired } from "./_resolver-utils";
+import {
+  SUSPEND_SENTINEL,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_WAITING_TYPE,
+} from "./_step-dispatch-constants";
+
+type WaitStepArgs = {
+  readonly for: StepResolver<string>;
+};
+
+defineStep<WaitStepArgs, undefined | typeof SUSPEND_SENTINEL>({
+  kind: "workflow.wait",
+  tier: 3,
+  defaultFailureStrategy: "throw",
+  run: async (args, ctx: PipelineCtx): Promise<undefined | typeof SUSPEND_SENTINEL> => {
+    if (!ctx.workflow) {
+      throw new Error(
+        "r.step.wait is only allowed inside defineWorkflow — " +
+          "sync handlers cannot suspend (use r.step.webhook.send with mode: 'deferred' instead).",
+      );
+    }
+
+    const duration = resolveRequired(args.for, ctx);
+
+    const now = Temporal.Now.instant().toString();
+    const wakeAt =
+      duration.startsWith("P") || duration.startsWith("PT") ? addDuration(now, duration) : duration;
+
+    await ctx.unsafeAppendEvent({
+      aggregateId: ctx.workflow.runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      type: WORKFLOW_WAITING_TYPE,
+      payload: {
+        wakeAt,
+        stepIndex: ctx.workflow.stepIndex,
+        workflowName: ctx.workflow.workflowName,
+        // Trigger snapshot: pinned so the resume-loop re-feeds the
+        // pipeline with what the original run saw. event-sourcing across
+        // suspensions hinges on this being stable.
+        triggerEventType: ctx.event.type,
+        triggerPayload: ctx.event.payload,
+        ...(ctx.workflow.definitionFingerprint && {
+          definitionFingerprint: ctx.workflow.definitionFingerprint,
+        }),
+      },
+    });
+
+    return SUSPEND_SENTINEL;
+  },
+});
+
+export function buildWaitStep(args: WaitStepArgs): StepInstance {
+  return { kind: "workflow.wait", args };
+}

package/src/engine/steps/webhook-send.ts

@@ -0,0 +1,71 @@
+// r.step.webhook.send — deferred HTTP-POST via the step-dispatcher.
+// Tier-2: requires `r.requires.step("webhook.send")` in the owning feature.
+//
+// Writes a `kumiko:step:dispatch-requested` event onto a fresh step-dispatch
+// stream in the current TX. The step-dispatcher subscription (bundled-feature
+// `step-dispatcher`) reads after COMMIT and performs the fetch with retry.
+
+import { randomUUID } from "node:crypto";
+import { defineStep } from "../define-step";
+import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { resolveOptional, resolveRequired } from "./_resolver-utils";
+import {
+  STEP_DISPATCH_AGGREGATE_TYPE,
+  STEP_DISPATCH_REQUESTED_TYPE,
+} from "./_step-dispatch-constants";
+
+// Re-export for back-compat callers (bundled step-dispatcher imports
+// these). The canonical home is _step-dispatch-constants.ts.
+export {
+  STEP_DISPATCH_AGGREGATE_TYPE,
+  STEP_DISPATCH_FAILED_TYPE,
+  STEP_DISPATCH_REQUESTED_TYPE,
+  STEP_DISPATCHED_TYPE,
+} from "./_step-dispatch-constants";
+
+type WebhookHttpMethod = "POST" | "PUT" | "PATCH";
+
+type WebhookAuth =
+  | { readonly kind: "bearer"; readonly secretRef: string }
+  | { readonly kind: "header"; readonly name: string; readonly secretRef: string };
+
+type WebhookSendArgs = {
+  readonly url: StepResolver<string>;
+  readonly method?: WebhookHttpMethod;
+  readonly headers?: StepResolver<Readonly<Record<string, string>>>;
+  readonly body?: StepResolver<unknown>;
+  readonly auth?: WebhookAuth;
+  readonly mode: "deferred";
+  readonly retry?: { readonly times: number; readonly backoff: "exponential" | "linear" };
+};
+
+defineStep<WebhookSendArgs, void>({
+  kind: "webhook.send",
+  tier: 2,
+  defaultFailureStrategy: "throw",
+  run: async (args, ctx: PipelineCtx) => {
+    const url = resolveRequired(args.url, ctx);
+    const headers = resolveOptional(args.headers, ctx) ?? {};
+    const body = resolveOptional(args.body, ctx);
+    await ctx.unsafeAppendEvent({
+      aggregateId: randomUUID(),
+      aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+      type: STEP_DISPATCH_REQUESTED_TYPE,
+      payload: {
+        stepKind: "webhook.send",
+        spec: {
+          url,
+          method: args.method ?? "POST",
+          headers,
+          body,
+          ...(args.auth && { auth: args.auth }),
+        },
+        retry: args.retry ?? { times: 3, backoff: "exponential" },
+      },
+    });
+  },
+});
+
+export function buildWebhookSendStep(args: WebhookSendArgs): StepInstance {
+  return { kind: "webhook.send", args };
+}

package/src/engine/system-user.ts

@@ -1,5 +1,5 @@
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { SessionUser } from "./types";
+import type { TenantId } from "./types/identifiers";
 
 // Stringified so it round-trips through SessionUser.id (string UUID-shape).
 // Not a real UUID — SYSTEM acts as an alias for "no human caller" and event-