@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/dist/engine/steps/branch.js

@@ -0,0 +1,66 @@
+// r.step.branch — conditional sub-pipeline execution.
+//
+// Evaluates the `if` resolver, runs the `then` step-array if truthy,
+// otherwise the `else` step-array (if provided). Branch is a
+// side-effect container: it doesn't surface a result-key, doesn't
+// allow mid-flight `r.step.return`. Use it to gate ES-mutations or
+// projection-writes on a condition derived from prior steps.
+//
+// ```ts
+// r.step.branch({
+//   if: ({ steps }) => (steps["user"] as User | null) !== null,
+//   onTrue: [r.step.aggregate.appendEvent({...})],
+//   onFalse: [r.step.unsafeProjectionUpsert({...})],
+// })
+// ```
+//
+// Naming-note (Q14 revised): `onTrue`/`onFalse` instead of `then`/`else`
+// because Biome's `noThenProperty` lint flags `then` as a thenable-trap
+// (await-on-the-args-object would invoke the array, not awaited
+// resolution). `if` remains as JS-keyword-as-property — string-key access
+// is allowed and reads as natural English.
+//
+// Sub-pipeline-form (Q11): `onTrue` / `onFalse` are static StepInstance
+// arrays — `r` is captured from the outer pipeline closure, no nested
+// r-arg. Boot-validator walks them recursively (Q17). Build-time guard
+// (Q12) rejects nested `r.step.return` — branch is not a mid-flight
+// exit (would trigger the discriminated-union TData-Inference trap).
+import { defineStep } from "../define-step.js";
+import { runStepList } from "../run-pipeline.js";
+import { validateNoReturnSteps } from "./_no-return-guard.js";
+import { resolveRequired } from "./_resolver-utils.js";
+import { SUSPEND_SENTINEL } from "./_step-dispatch-constants.js";
+defineStep({
+    kind: "branch",
+    defaultFailureStrategy: "throw",
+    subPaths: ["onTrue", "onFalse"],
+    run: async (args, ctx) => {
+        const condition = resolveRequired(args.if, ctx);
+        const branchSteps = condition ? args.onTrue : (args.onFalse ?? []);
+        // Recursive sub-step execution. The acc-maps in ctx are typed
+        // Readonly for the public-facing PipelineCtx (resolvers shouldn't
+        // mutate them directly), but the runtime objects are the same
+        // mutable maps that runPipeline owns. Casting back to mutable here
+        // is a framework-internal boundary, not a user-API boundary.
+        const stepsAcc = ctx.steps;
+        const scopeAcc = ctx.scope;
+        const outcome = await runStepList(branchSteps, ctx.event, ctx, stepsAcc, scopeAcc, ctx.workflow);
+        if (outcome.kind === "return") {
+            // Build-time guard (validateNoReturnSteps) rejects any return-step
+            // inside onTrue/onFalse. If we land here at runtime, someone
+            // hand-crafted a StepInstance with kind="return" and bypassed the
+            // builder. Fail loud rather than silently bubbling the return up to
+            // the outer pipeline (would shadow Q12).
+            throw new Error("r.step.return is not allowed inside r.step.branch onTrue/onFalse (Q12)");
+        }
+        if (outcome.kind === "suspended") {
+            return SUSPEND_SENTINEL;
+        }
+    },
+});
+export function buildBranchStep(args) {
+    validateNoReturnSteps(args.onTrue, "r.step.branch.onTrue");
+    if (args.onFalse)
+        validateNoReturnSteps(args.onFalse, "r.step.branch.onFalse");
+    return { kind: "branch", args };
+}

package/dist/engine/steps/call-feature.d.ts

@@ -0,0 +1,7 @@
+import type { SessionUser } from "../types/index.js";
+import type { StepInstance, StepResolver } from "../types/step.js";
+export declare function buildCallFeatureStep(name: string, opts: {
+    readonly handler: string;
+    readonly payload: StepResolver<unknown>;
+    readonly as?: SessionUser;
+}): StepInstance;

package/dist/engine/steps/call-feature.js

@@ -0,0 +1,30 @@
+// r.step.callFeature — typed sub-command on another Kumiko feature.
+// Tier-2: requires r.requires.step("callFeature"). Sync (no dispatcher).
+// opts.as other than the caller itself needs escapeHatch on the handler (system-identity-switch.ts).
+import { defineStep } from "../define-step.js";
+import { resolveRequired } from "./_resolver-utils.js";
+defineStep({
+    kind: "callFeature",
+    tier: 2,
+    defaultFailureStrategy: "throw",
+    resultKey: (args) => args.name,
+    run: async (args, ctx) => {
+        const payload = resolveRequired(args.payload, ctx);
+        const result = args.as
+            ? await ctx.writeAs(args.as, args.handler, payload)
+            : await ctx.write(args.handler, payload);
+        if (!result.isSuccess) {
+            // Preserve the structured WriteFailure as `cause` so the
+            // dispatcher's catch maps it back to a typed error response
+            // (e.g. validation_failed stays validation_failed, not a
+            // generic internal_error).
+            const err = new Error(`callFeature("${args.handler}") returned failure`);
+            err.cause = result.error;
+            throw err;
+        }
+        return result.data;
+    },
+});
+export function buildCallFeatureStep(name, opts) {
+    return { kind: "callFeature", args: { name, ...opts } };
+}

package/dist/engine/steps/compute.d.ts

@@ -0,0 +1,2 @@
+import type { PipelineCtx, StepInstance } from "../types/step.js";
+export declare function buildComputeStep<TResult>(name: string, fn: (ctx: PipelineCtx) => TResult): StepInstance;

package/dist/engine/steps/compute.js

@@ -0,0 +1,29 @@
+// r.step.compute — derive a value from the pipeline-context and stash
+// it under `steps.<name>` for subsequent steps to consume.
+//
+// Typical use:
+//   r.step.compute("startedAt", () => Temporal.Now.instant()),
+//   r.step.compute("isPriority", ({ event }) => event.payload.tier === "Pro"),
+//
+// `compute` is the simplest non-trivial step — it shows how the
+// `steps`-accumulator carries values forward across the pipeline. The
+// runtime side is a single function call; the value of this step lies
+// in being the smallest building block that exercises step-result
+// threading end-to-end.
+//
+// Type-safety note: in M.1, `steps` is Record<string, unknown> — call
+// sites cast or guard at the read end. Strict-typed result-key
+// accumulation is a follow-up (see step-vocabulary.md M.1-Followups).
+import { defineStep } from "../define-step.js";
+defineStep({
+    kind: "compute",
+    defaultFailureStrategy: "throw",
+    resultKey: (args) => args.name,
+    run: (args, ctx) => args.fn(ctx), // @wrapper-known semantic-alias
+});
+export function buildComputeStep(name, fn) {
+    return {
+        kind: "compute",
+        args: { name, fn },
+    };
+}

package/dist/engine/steps/describe-workflow-step-error.d.ts

@@ -0,0 +1 @@
+export declare function describeWorkflowStepError(error: unknown): string;

package/dist/engine/steps/describe-workflow-step-error.js

@@ -0,0 +1,6 @@
+// Workflow events (run-failed, retry.scheduled) outlive an Art. 17 erase, and a
+// raw error message can echo recipients or payload fragments. Events carry only
+// this generic text; the raw error goes to the log.
+export function describeWorkflowStepError(error) {
+    return `workflow step failed (${error instanceof Error ? error.name : "unknown error"})`;
+}

package/dist/engine/steps/for-each.d.ts

@@ -0,0 +1,9 @@
+import type { StepInstance, StepResolver } from "../types/step.js";
+type ForEachArgs<TItem = unknown> = {
+    readonly over: StepResolver<readonly TItem[]>;
+    readonly as: string;
+    readonly do: readonly StepInstance[];
+    readonly concurrency?: 1;
+};
+export declare function buildForEachStep<TItem = unknown>(args: ForEachArgs<TItem>): StepInstance;
+export {};

package/dist/engine/steps/for-each.js

@@ -0,0 +1,88 @@
+// r.step.forEach — iterate a sub-pipeline over an array.
+//
+// The sub-pipeline (`do`) runs once per item; the current item lands
+// under `scope[as]` for resolvers inside `do` to read. After the loop,
+// `scope[as]` is restored to its prior value (or deleted if it didn't
+// exist before) — scope-keys are forEach-local, not bleeding into
+// subsequent top-level steps.
+//
+// ```ts
+// r.step.forEach({
+//   over: ({ steps }) => steps["componentIds"] as string[],
+//   as: "componentId",
+//   do: [
+//     r.step.unsafeProjectionUpsert({
+//       table: incidentComponentsTable,
+//       on: ["incidentId", "componentId"],
+//       row: ({ scope, steps }) => ({
+//         incidentId: (steps["incident"] as { id: string }).id,
+//         componentId: scope["componentId"] as string,
+//       }),
+//     }),
+//   ],
+// })
+// ```
+//
+// M.1.6 supports `concurrency: 1` only (sequential). Concurrent
+// execution (Promise.all-style) is Followup #12 — TX-sharing,
+// AbortSignal-cancellation, and lifecycle-hook ordering each warrant
+// their own audit cycle (Q16).
+//
+// Q15: `as` is required — without it, the current item is unreachable
+// from the sub-pipeline's resolvers. Q12: r.step.return inside `do` is
+// rejected at build time (would trigger the discriminated-union
+// TData-Inference trap).
+import { defineStep } from "../define-step.js";
+import { runStepList } from "../run-pipeline.js";
+import { validateNoReturnSteps } from "./_no-return-guard.js";
+import { resolveRequired } from "./_resolver-utils.js";
+import { SUSPEND_SENTINEL } from "./_step-dispatch-constants.js";
+defineStep({
+    kind: "forEach",
+    defaultFailureStrategy: "throw",
+    subPaths: ["do"],
+    run: async (args, ctx) => {
+        const items = resolveRequired(args.over, ctx);
+        if (!Array.isArray(items)) {
+            throw new Error(`r.step.forEach: 'over' resolver must return an array (got ${typeof items})`);
+        }
+        // Mutable-acc cast — same framework-internal boundary as branch.run.
+        // The runtime objects are the maps that runPipeline owns; readonly
+        // typing in PipelineCtx is for resolver-API hygiene.
+        const stepsAcc = ctx.steps;
+        const scopeAcc = ctx.scope;
+        // Save-and-restore so the scope-key is forEach-local. Without this,
+        // a nested `r.step.compute` reading scope[as] AFTER the forEach
+        // would silently see the last iteration's item.
+        const hadKey = Object.hasOwn(scopeAcc, args.as);
+        const previousValue = scopeAcc[args.as];
+        try {
+            for (const item of items) {
+                scopeAcc[args.as] = item;
+                const outcome = await runStepList(args.do, ctx.event, ctx, stepsAcc, scopeAcc, ctx.workflow);
+                if (outcome.kind === "return") {
+                    throw new Error("r.step.return is not allowed inside r.step.forEach.do (Q12)");
+                }
+                if (outcome.kind === "suspended") {
+                    return SUSPEND_SENTINEL;
+                }
+            }
+        }
+        finally {
+            if (hadKey) {
+                scopeAcc[args.as] = previousValue;
+            }
+            else {
+                delete scopeAcc[args.as];
+            }
+        }
+    },
+});
+export function buildForEachStep(args) {
+    validateNoReturnSteps(args.do, "r.step.forEach.do");
+    if (args.concurrency !== undefined && args.concurrency !== 1) {
+        throw new Error(`r.step.forEach: concurrency=${args.concurrency} not supported in M.1.6 (only 1). ` +
+            `Concurrent forEach is Followup #12 — TX-sharing, AbortSignal, hook-ordering each need their own slice.`);
+    }
+    return { kind: "forEach", args };
+}

package/dist/engine/steps/mail-send.d.ts

@@ -0,0 +1,10 @@
+import type { StepInstance, StepResolver } from "../types/step.js";
+type MailSendArgs = {
+    readonly to: StepResolver<string | readonly string[]>;
+    readonly subject: StepResolver<string>;
+    readonly body: StepResolver<string>;
+    readonly from?: StepResolver<string>;
+    readonly mode: "deferred";
+};
+export declare function buildMailSendStep(args: MailSendArgs): StepInstance;
+export {};

package/dist/engine/steps/mail-send.js

@@ -0,0 +1,33 @@
+// r.step.mail.send — deferred transactional e-mail via the step-dispatcher.
+// Tier-2: requires r.requires.step("mail.send"). Mirrors webhook.send.
+import { randomUUID } from "node:crypto";
+import { defineStep } from "../define-step.js";
+import { resolveOptional, resolveRequired } from "./_resolver-utils.js";
+import { STEP_DISPATCH_AGGREGATE_TYPE, STEP_DISPATCH_REQUESTED_TYPE, } from "./_step-dispatch-constants.js";
+defineStep({
+    kind: "mail.send",
+    tier: 2,
+    defaultFailureStrategy: "throw",
+    run: async (args, ctx) => {
+        const to = resolveRequired(args.to, ctx);
+        const subject = resolveRequired(args.subject, ctx);
+        const body = resolveRequired(args.body, ctx);
+        const from = resolveOptional(args.from, ctx);
+        await ctx.unsafeAppendEvent({
+            aggregateId: randomUUID(),
+            aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+            type: STEP_DISPATCH_REQUESTED_TYPE,
+            payload: {
+                stepKind: "mail.send",
+                // Flat string fields: event PII encryption only handles top-level strings.
+                to: JSON.stringify(to),
+                subject,
+                body,
+                ...(from && { from }),
+            },
+        });
+    },
+});
+export function buildMailSendStep(args) {
+    return { kind: "mail.send", args };
+}

package/dist/engine/steps/read-find-many.d.ts

@@ -0,0 +1,10 @@
+import { type WhereObject } from "../../db/query.js";
+import type { StepInstance, StepResolver } from "../types/step.js";
+export declare function buildReadFindManyStep(name: string, opts: {
+    readonly table: unknown;
+    readonly where?: StepResolver<WhereObject | undefined>;
+    readonly limit?: number;
+    readonly unsafeAllTenants?: {
+        readonly reason: string;
+    };
+}): StepInstance;

package/dist/engine/steps/read-find-many.js

@@ -0,0 +1,32 @@
+// r.step.read.findMany — load multiple rows from a projection table.
+//
+// Sibling to read.findOne — same tenant-filtering: own tenant +
+// SYSTEM_TENANT_ID reference rows by default, `unsafeAllTenants: { reason }`
+// plus `escapeHatch: { reason }` on the handler to read across tenants.
+// 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 { selectMany } from "../../db/query.js";
+import { defineStep } from "../define-step.js";
+import { readSourceFor } from "./_read-source.js";
+import { resolveOptional } from "./_resolver-utils.js";
+defineStep({
+    kind: "read.findMany",
+    defaultFailureStrategy: "throw",
+    resultKey: (args) => args.name,
+    run: async (args, ctx) => {
+        const where = resolveOptional(args.where, ctx);
+        const source = readSourceFor(ctx, args.unsafeAllTenants);
+        const rows = await selectMany(source, args.table, where, args.limit !== undefined ? { limit: args.limit } : undefined);
+        return rows;
+    },
+});
+export function buildReadFindManyStep(name, opts) {
+    return {
+        kind: "read.findMany",
+        args: { name, ...opts },
+    };
+}

package/dist/engine/steps/read-find-one.d.ts

@@ -0,0 +1,9 @@
+import { type WhereObject } from "../../db/query.js";
+import type { StepInstance, StepResolver } from "../types/step.js";
+export declare function buildReadFindOneStep(name: string, opts: {
+    readonly table: unknown;
+    readonly where: StepResolver<WhereObject | undefined>;
+    readonly unsafeAllTenants?: {
+        readonly reason: string;
+    };
+}): StepInstance;

package/dist/engine/steps/read-find-one.js

@@ -0,0 +1,41 @@
+// r.step.read.findOne — load a single row from a projection table.
+//
+// Thin wrapper on selectMany(db, table, where, { limit: 1 }) (bun-db).
+// Resolves to the first row or null. Tenant-filtered like ctx.db
+// method-form reads (own tenant + SYSTEM_TENANT_ID reference rows); a
+// foreign `where.tenantId` is narrowed to the caller's own scope.
+// Cross-tenant reads require `unsafeAllTenants: { reason }` here AND
+// `escapeHatch: { reason }` on the handler — reported as an "unsafe-raw"
+// escape-hatch audit event.
+//
+// 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 { selectMany } from "../../db/query.js";
+import { defineStep } from "../define-step.js";
+import { readSourceFor } from "./_read-source.js";
+import { resolveRequired } from "./_resolver-utils.js";
+defineStep({
+    kind: "read.findOne",
+    defaultFailureStrategy: "throw",
+    resultKey: (args) => args.name,
+    run: async (args, ctx) => {
+        const where = resolveRequired(args.where, ctx);
+        const source = readSourceFor(ctx, args.unsafeAllTenants);
+        const rows = await selectMany(source, args.table, where, { limit: 1 });
+        return rows[0] ?? null;
+    },
+});
+export function buildReadFindOneStep(name, opts) {
+    return {
+        kind: "read.findOne",
+        args: { name, ...opts },
+    };
+}

package/dist/engine/steps/retry.d.ts

@@ -0,0 +1,9 @@
+import type { StepInstance } from "../types/step.js";
+type RetryStepArgs = {
+    readonly times: number;
+    readonly backoff: "exponential" | "linear";
+    readonly do: readonly StepInstance[];
+};
+export declare function buildRetryStep(args: RetryStepArgs): StepInstance;
+export declare function calculateBackoff(attempt: number, strategy: "exponential" | "linear"): number;
+export {};

package/dist/engine/steps/retry.js

@@ -0,0 +1,76 @@
+// 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 { createFallbackLogger } from "../../logging/index.js";
+import { defineStep } from "../define-step.js";
+import { runStepList } from "../run-pipeline.js";
+import { SUSPEND_SENTINEL, WORKFLOW_AGGREGATE_TYPE, WORKFLOW_RETRY_SCHEDULED_TYPE, } from "./_step-dispatch-constants.js";
+import { describeWorkflowStepError } from "./describe-workflow-step-error.js";
+const log = createFallbackLogger("workflow-retry");
+defineStep({
+    kind: "workflow.retry",
+    tier: 3,
+    defaultFailureStrategy: "throw",
+    subPaths: ["do"],
+    run: async (args, ctx) => {
+        if (!ctx.workflow) {
+            throw new Error("r.step.retry is only allowed inside defineWorkflow — " + "sync handlers cannot suspend.");
+        }
+        const stepsAcc = ctx.steps;
+        const scopeAcc = ctx.scope;
+        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;
+            }
+            log.warn("workflow step failed, retry scheduled", {
+                runId: ctx.workflow.runId,
+                workflowName: ctx.workflow.workflowName,
+                stepIndex: ctx.workflow.stepIndex,
+                attempt,
+                error: String(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: describeWorkflowStepError(error),
+                    triggerEventType: ctx.event.type,
+                    triggerPayload: ctx.event.payload,
+                    ...(ctx.workflow.definitionFingerprint && {
+                        definitionFingerprint: ctx.workflow.definitionFingerprint,
+                    }),
+                },
+            });
+            return SUSPEND_SENTINEL;
+        }
+    },
+});
+export function buildRetryStep(args) {
+    return { kind: "workflow.retry", args };
+}
+export function calculateBackoff(attempt, strategy) {
+    const baseMs = 10_000;
+    if (strategy === "linear") {
+        return baseMs * attempt;
+    }
+    return baseMs * 2 ** (attempt - 1);
+}

package/dist/engine/steps/return.d.ts

@@ -0,0 +1,4 @@
+import type { WriteResult } from "../types/handlers.js";
+import type { StepInstance, StepResolver } from "../types/step.js";
+export declare const RETURN_RESULT_KEY = "__return";
+export declare function buildReturnStep<TData>(resolver: StepResolver<WriteResult<TData>>): StepInstance;

package/dist/engine/steps/return.js

@@ -0,0 +1,25 @@
+// 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.js";
+import { resolveRequired } from "./_resolver-utils.js";
+// 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({
+    kind: "return",
+    defaultFailureStrategy: "throw",
+    resultKey: () => RETURN_RESULT_KEY,
+    // @wrapper-known semantic-alias
+    run: (args, ctx) => resolveRequired(args.resolver, ctx),
+});
+export function buildReturnStep(resolver) {
+    return {
+        kind: "return",
+        args: { resolver },
+    };
+}

package/dist/engine/steps/unsafe-projection-delete.d.ts

@@ -0,0 +1,8 @@
+import { type WhereObject } from "../../db/query.js";
+import type { StepInstance, StepResolver } from "../types/step.js";
+type UnsafeProjectionDeleteArgs = {
+    readonly table: unknown;
+    readonly where: StepResolver<WhereObject>;
+};
+export declare function buildUnsafeProjectionDeleteStep(args: UnsafeProjectionDeleteArgs): StepInstance;
+export {};

package/dist/engine/steps/unsafe-projection-delete.js

@@ -0,0 +1,35 @@
+// 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 { deleteMany } from "../../db/query.js";
+import { tenantDbRunner } from "../../db/tenant-db-runner.js";
+import { defineStep } from "../define-step.js";
+import { resolveRequired } from "./_resolver-utils.js";
+defineStep({
+    kind: "unsafeProjectionDelete",
+    defaultFailureStrategy: "throw",
+    run: async (args, ctx) => {
+        const where = resolveRequired(args.where, ctx);
+        // The `unsafe*`-step IS the sanctioned direct projection write — it exists
+        // to bypass the executor deliberately (boot-validated allowlist + reviewer
+        // gate). The brand-strip cast makes that explicit at the one blessed seam.
+        await deleteMany(tenantDbRunner(ctx.db), args.table, where);
+    },
+});
+export function buildUnsafeProjectionDeleteStep(args) {
+    return { kind: "unsafeProjectionDelete", args };
+}

package/dist/engine/steps/unsafe-projection-upsert.d.ts

@@ -0,0 +1,8 @@
+import type { StepInstance, StepResolver } from "../types/step.js";
+type UnsafeProjectionUpsertArgs = {
+    readonly table: unknown;
+    readonly on: readonly string[];
+    readonly row: StepResolver<Record<string, unknown>>;
+};
+export declare function buildUnsafeProjectionUpsertStep(args: UnsafeProjectionUpsertArgs): StepInstance;
+export {};

package/dist/engine/steps/unsafe-projection-upsert.js

@@ -0,0 +1,73 @@
+// 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 { KUMIKO_COLUMNS_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { extractTableName } from "../../db/index.js";
+import { executeRawQuery } from "../../db/queries/raw-sql.js";
+import { tenantDbRunner } from "../../db/tenant-db-runner.js";
+import { defineStep } from "../define-step.js";
+import { resolveRequired } from "./_resolver-utils.js";
+function resolveColumnName(table, field) {
+    if (typeof table !== "object" || table === null)
+        return field;
+    const cols = table[KUMIKO_COLUMNS_SYMBOL];
+    if (typeof cols !== "object" || cols === null)
+        return field;
+    const col = cols[field];
+    if (typeof col === "object" && col !== null) {
+        const nameVal = col["name"];
+        if (typeof nameVal === "string")
+            return nameVal;
+    }
+    return field;
+}
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+defineStep({
+    kind: "unsafeProjectionUpsert",
+    defaultFailureStrategy: "throw",
+    run: async (args, ctx) => {
+        const resolvedRow = resolveRequired(args.row, ctx);
+        // Validate conflict-key columns exist in the row.
+        for (const key of args.on) {
+            if (!(key in resolvedRow)) {
+                throw new Error(`unsafeProjectionUpsert: column "${key}" not found in row`);
+            }
+        }
+        const tableName = extractTableName(args.table, "unsafeProjectionUpsert");
+        const entries = Object.entries(resolvedRow);
+        const params = [];
+        const colNames = entries.map(([k]) => quoteIdent(resolveColumnName(args.table, k)));
+        const placeholders = entries.map((_, i) => `$${i + 1}`);
+        for (const [, v] of entries)
+            params.push(v);
+        const conflictCols = args.on
+            .map((k) => quoteIdent(resolveColumnName(args.table, k)))
+            .join(", ");
+        // SET clause excludes conflict-key columns.
+        const setClauses = [];
+        let paramIdx = entries.length + 1;
+        for (const [k, v] of entries) {
+            if (args.on.includes(k))
+                continue;
+            setClauses.push(`${quoteIdent(resolveColumnName(args.table, k))} = $${paramIdx++}`);
+            params.push(v);
+        }
+        const sqlText = `INSERT INTO ${quoteIdent(tableName)} (${colNames.join(", ")}) VALUES (${placeholders.join(", ")}) ` +
+            `ON CONFLICT (${conflictCols}) DO UPDATE SET ${setClauses.join(", ")}`;
+        await executeRawQuery(tenantDbRunner(ctx.db), sqlText, params);
+    },
+});
+export function buildUnsafeProjectionUpsertStep(args) {
+    return { kind: "unsafeProjectionUpsert", args };
+}

package/dist/engine/steps/wait-for-event.d.ts

@@ -0,0 +1,8 @@
+import type { AwaitedEventType, EventMatch, StepInstance, StepResolver } from "../types/step.js";
+type WaitForEventArgs = {
+    readonly event: AwaitedEventType;
+    readonly match?: StepResolver<EventMatch>;
+    readonly timeout: StepResolver<string>;
+};
+export declare function buildWaitForEventStep(args: WaitForEventArgs): StepInstance;
+export {};