@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/dist/engine/soft-delete-cleanup.js

@@ -0,0 +1,114 @@
+// Auto-generated soft-delete maintenance. Hard-deletes entity rows that have
+// been soft-deleted longer than the per-tenant grace period. Injected into the
+// registry (the job + its config key) whenever ANY entity opts into softDelete
+// — see createRegistry. Runtime twin to the auto restore-handler: softDelete:
+// true buys an entity restore + trash (ctx.includeDeleted) + this cleanup, with
+// no feature to wire.
+//
+// Hard-deleting the projection row leaves the event stream intact (source of
+// truth) — a full projection rebuild would replay created+deleted and
+// resurrect the row as isDeleted=true. That's acceptable: cleanup bounds LIVE
+// table growth; irreversible event-log purging is data-retention's job
+// (pruneEvents), a separate, consumer-lag-guarded path.
+import { deleteMany } from "../db/query.js";
+import { SYSTEM_USER_ID } from "./system-user.js";
+// qualifyEntityName convention (feature:type:kebab-name) with a reserved
+// "soft-delete" owner — no real feature owns these; the framework synthesizes
+// them. The job-runner keys cron scheduling off the name, the config-resolver
+// off the key.
+export const SOFT_DELETE_CLEANUP_JOB = "soft-delete:job:cleanup";
+export const SOFT_DELETE_CLEANUP_SYSTEM_JOB = "soft-delete:job:cleanup-system";
+export const SOFT_DELETE_GRACE_DAYS_KEY = "soft-delete:config:grace-days";
+export const DEFAULT_GRACE_DAYS = 30;
+export const softDeleteGraceDaysConfig = {
+    type: "number",
+    default: DEFAULT_GRACE_DAYS,
+    scope: "tenant",
+    access: { read: ["TenantAdmin", "SystemAdmin"], write: ["SystemAdmin"] },
+    // min: 1, not 0 (565/2) — graceDays: 0 doesn't mean "no cleanup", it means
+    // "hard-delete every currently soft-deleted row on the next cron run".
+    // Clamping (not rejecting) keeps the resolve-config-or-param clamp path's
+    // existing silent-below-bound / audited-crossing behavior.
+    bounds: { min: 1 },
+};
+export const softDeleteCleanupJob = async (_payload, ctx) => {
+    const { db, registry } = ctx;
+    if (!db || !registry) {
+        throw new Error("soft-delete cleanup: ctx.db + ctx.registry required (JobContext incomplete)");
+    }
+    // perTenant fan-out → one run per active tenant, systemUser scoped to it.
+    // The job's db is a tenant-filtered TenantDb, but every delete is still
+    // explicitly tenant-filtered below as defense-in-depth — otherwise a
+    // tenant with a short grace would purge another tenant's still-within-grace
+    // rows.
+    const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+    if (tenantId === undefined) {
+        // skip: cron fired without a perTenant fan-out tenant — nothing scoped to purge
+        return;
+    }
+    const resolved = ctx.configResolver
+        ? await ctx.configResolver.get(SOFT_DELETE_GRACE_DAYS_KEY, softDeleteGraceDaysConfig, tenantId, SYSTEM_USER_ID, db)
+        : undefined;
+    const graceDays = typeof resolved === "number" && resolved >= 1 ? resolved : DEFAULT_GRACE_DAYS;
+    const cutoff = Temporal.Now.instant().subtract({ hours: graceDays * 24 });
+    for (const proj of registry.getAllProjections().values()) {
+        if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
+            continue;
+        const entity = registry.getEntity(proj.source);
+        if (!entity?.softDelete)
+            continue;
+        // @cast-boundary column-presence probe — identical access the executor's
+        // list() does on table["tenantId"] to decide tenant-scoping.
+        const hasTenantColumn = proj.table["tenantId"] !== undefined;
+        // System-global entities (no tenantId column, e.g. `user`) are NOT swept
+        // here: this handler runs once PER TENANT, so a tenant-scoped grace value
+        // would purge every OTHER tenant's still-within-grace rows too (effective
+        // grace = min() across all tenants). softDeleteCleanupSystemJob handles
+        // these separately, once, with a fixed grace period.
+        if (!hasTenantColumn)
+            continue;
+        const where = { isDeleted: true, deletedAt: { lt: cutoff }, tenantId };
+        await deleteMany(db, proj.table, where);
+    }
+};
+// System-global soft-deleted entities (no tenantId column) can't take a
+// per-tenant grace period — there's no "this tenant's view" of a row that
+// isn't scoped to any tenant. Runs once (not perTenant) with a fixed grace
+// period; a future system-scope config key could make this configurable
+// without reintroducing the per-tenant-fanout bug.
+export const softDeleteCleanupSystemJob = async (_payload, ctx) => {
+    const { db, registry } = ctx;
+    if (!db || !registry) {
+        throw new Error("soft-delete system cleanup: ctx.db + ctx.registry required (JobContext incomplete)");
+    }
+    const cutoff = Temporal.Now.instant().subtract({ hours: DEFAULT_GRACE_DAYS * 24 });
+    for (const proj of registry.getAllProjections().values()) {
+        if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
+            continue;
+        const entity = registry.getEntity(proj.source);
+        if (!entity?.softDelete)
+            continue;
+        if (proj.table["tenantId"] !== undefined)
+            continue;
+        await deleteMany(db, proj.table, { isDeleted: true, deletedAt: { lt: cutoff } });
+    }
+};
+export function buildSoftDeleteCleanupJob() {
+    return {
+        name: SOFT_DELETE_CLEANUP_JOB,
+        handler: softDeleteCleanupJob,
+        trigger: { cron: "0 3 * * *" },
+        perTenant: true,
+        concurrency: "skip",
+        runIn: "worker",
+    };
+}
+export function buildSoftDeleteCleanupSystemJob() {
+    return {
+        name: SOFT_DELETE_CLEANUP_SYSTEM_JOB,
+        handler: softDeleteCleanupSystemJob,
+        trigger: { cron: "15 3 * * *" },
+        concurrency: "skip",
+        runIn: "worker",
+    };
+}

package/dist/engine/state-machine.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Type-safe transition graph. Wraps the underlying Map so callers don't
+ * accidentally fall into the `transitions[from]?.includes(to)` footgun
+ * (Object-Index-Access auf einer Map returnt undefined und der ganze
+ * Check kollabiert silently). Stattdessen forciert die API explizite
+ * Methoden — kein Map-shape mehr extern sichtbar.
+ *
+ * - `canTransition(from, to)` → boolean
+ * - `allowedFrom(from)` → readonly string[] (leer wenn `from` unbekannt
+ *   oder terminaler Zustand)
+ * - `assertTransition(from, to)` → wirft UnprocessableError(invalid_transition)
+ */
+export type TransitionGraph<TStates extends string = string> = {
+    readonly canTransition: (from: TStates, to: TStates) => boolean;
+    readonly allowedFrom: (from: TStates) => readonly TStates[];
+    readonly assertTransition: (from: TStates, to: TStates) => void;
+};
+/**
+ * Defines allowed state transitions. Returns a typed graph (see
+ * TransitionGraph) — nicht eine Map. Damit ist `transitions[x]`-Zugriff
+ * type-error statt silent undefined.
+ */
+export declare function defineTransitions<const TMap extends Record<string, readonly string[]>>(map: TMap): TransitionGraph<keyof TMap & string>;
+/**
+ * Asserts a state transition is allowed. Throws UnprocessableError with
+ * reason="invalid_transition" if not — the 422 status lets the client
+ * distinguish a logical rejection from a validation or auth failure.
+ *
+ * Convenience-Wrapper um `transitions.assertTransition(from, to)` —
+ * existiert weil bestehende Aufrufer `guardTransition(graph, ...)`-Form
+ * nutzen. Beides ist erlaubt; die Method-Form auf dem Graph ist die
+ * idiomatische API für neuen Code.
+ */
+export declare function guardTransition<TStates extends string>(transitions: TransitionGraph<TStates>, from: TStates, to: TStates): void;

package/dist/engine/state-machine.js

@@ -0,0 +1,44 @@
+import { buildInvalidTransitionDetails, FrameworkReasons, UnprocessableError, } from "../errors/index.js";
+/**
+ * Defines allowed state transitions. Returns a typed graph (see
+ * TransitionGraph) — nicht eine Map. Damit ist `transitions[x]`-Zugriff
+ * type-error statt silent undefined.
+ */
+export function defineTransitions(map) {
+    const internal = new Map();
+    for (const [from, targets] of Object.entries(map)) {
+        internal.set(from, new Set(targets));
+    }
+    return {
+        canTransition: (from, to) => internal.get(from)?.has(to) === true,
+        allowedFrom: (from) => {
+            const set = internal.get(from);
+            return set ? [...set] : []; // @cast-boundary schema-walk
+        },
+        assertTransition: (from, to) => {
+            const set = internal.get(from);
+            // skip: erlaubter Übergang — kein Throw, fall through.
+            if (set?.has(to) === true)
+                return;
+            const allowed = set ? [...set] : [];
+            throw new UnprocessableError(FrameworkReasons.invalidTransition, {
+                i18nKey: "errors.invalidTransition",
+                details: buildInvalidTransitionDetails(from, to, allowed),
+            });
+        },
+    };
+}
+/**
+ * Asserts a state transition is allowed. Throws UnprocessableError with
+ * reason="invalid_transition" if not — the 422 status lets the client
+ * distinguish a logical rejection from a validation or auth failure.
+ *
+ * Convenience-Wrapper um `transitions.assertTransition(from, to)` —
+ * existiert weil bestehende Aufrufer `guardTransition(graph, ...)`-Form
+ * nutzen. Beides ist erlaubt; die Method-Form auf dem Graph ist die
+ * idiomatische API für neuen Code.
+ */
+// @wrapper-known semantic-alias
+export function guardTransition(transitions, from, to) {
+    transitions.assertTransition(from, to);
+}

package/dist/engine/steps/_duration-utils.d.ts

@@ -0,0 +1 @@
+export declare function addDuration(baseIso: string, duration: string): string;

package/dist/engine/steps/_duration-utils.js

@@ -0,0 +1,28 @@
+// ISO-8601 duration arithmetic — shared by wait and waitForEvent steps.
+// Accepts "P1D", "PT1H", "P1Y2M3DT4H5M6S" etc.
+// Uses approximate calendar math (365d/year, 30d/month). See #23.
+import { Temporal } from "temporal-polyfill";
+export function addDuration(baseIso, duration) {
+    const pattern = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/;
+    const match = duration.match(pattern);
+    if (!match) {
+        throw new Error(`Invalid ISO-8601 duration "${duration}" — expected format like "PT1H", "P1D", "P7D"`);
+    }
+    const parts = match.slice(1).map((n) => Number(n) || 0);
+    const years = parts[0] ?? 0;
+    const months = parts[1] ?? 0;
+    const days = parts[2] ?? 0;
+    const hours = parts[3] ?? 0;
+    const minutes = parts[4] ?? 0;
+    const seconds = parts[5] ?? 0;
+    // Compute in ms (Temporal.Instant.add accepts only smaller units below
+    // hours for calendar-agnostic shifts; we approximate years/months as
+    // fixed-length days, see file header).
+    let ms = years * 365 * 24 * 60 * 60 * 1000;
+    ms += months * 30 * 24 * 60 * 60 * 1000;
+    ms += days * 24 * 60 * 60 * 1000;
+    ms += hours * 60 * 60 * 1000;
+    ms += minutes * 60 * 1000;
+    ms += seconds * 1000;
+    return Temporal.Instant.from(baseIso).add({ milliseconds: ms }).toString();
+}

package/dist/engine/steps/_event-match.d.ts

@@ -0,0 +1,2 @@
+import type { EventMatch } from "../types/step.js";
+export declare function evaluateEventMatch(match: EventMatch, payload: unknown): boolean;

package/dist/engine/steps/_event-match.js

@@ -0,0 +1,88 @@
+// Evaluator for the persisted r.step.waitForEvent `match` AST (EventMatch).
+// Runtime-only: kept in the framework package (not packages/types) so it
+// stays out of the type graph, same steps/-vs-packages/types split as
+// _duration-utils.ts.
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function resolvePath(payload, path) {
+    let current = payload;
+    for (const segment of path) {
+        if (!isRecord(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function compareOrdered(actual, expected, kind) {
+    if (typeof actual === "number" && typeof expected === "number") {
+        switch (kind) {
+            case "gt":
+                return actual > expected;
+            case "gte":
+                return actual >= expected;
+            case "lt":
+                return actual < expected;
+            case "lte":
+                return actual <= expected;
+        }
+    }
+    if (typeof actual === "string" && typeof expected === "string") {
+        switch (kind) {
+            case "gt":
+                return actual > expected;
+            case "gte":
+                return actual >= expected;
+            case "lt":
+                return actual < expected;
+            case "lte":
+                return actual <= expected;
+        }
+    }
+    return false;
+}
+function evaluateOp(op, actual) {
+    switch (op.kind) {
+        case "eq":
+            return actual === op.value;
+        case "ne":
+            return actual !== op.value;
+        case "in":
+            return op.values.some((value) => value === actual);
+        case "gt":
+        case "gte":
+        case "lt":
+        case "lte":
+            // A payload value of a different primitive kind than the operand
+            // doesn't match — bad input, not a malformed AST.
+            if (typeof actual !== "number" && typeof actual !== "string")
+                return false;
+            return compareOrdered(actual, op.value, op.kind);
+        default: {
+            // op.kind comes from a persisted event, not from this call's static
+            // type — an unrecognized kind means a format we don't understand.
+            const unrecognized = op;
+            throw new Error(`Unknown EventMatchOp kind "${unrecognized.kind}"`);
+        }
+    }
+}
+function evaluateExpr(expr, payload) {
+    switch (expr.kind) {
+        case "and":
+            return expr.nodes.every((node) => evaluateExpr(node, payload));
+        case "or":
+            return expr.nodes.some((node) => evaluateExpr(node, payload));
+        case "atom":
+            return evaluateOp(expr.op, resolvePath(payload, expr.path));
+        default: {
+            const unrecognized = expr;
+            throw new Error(`Unknown EventMatchExpr kind "${unrecognized.kind}"`);
+        }
+    }
+}
+export function evaluateEventMatch(match, payload) {
+    if (match.version !== 1) {
+        throw new Error(`Unsupported EventMatch version ${JSON.stringify(match.version)} — expected 1`);
+    }
+    return evaluateExpr(match.expr, payload);
+}

package/dist/engine/steps/_no-return-guard.d.ts

@@ -0,0 +1,2 @@
+import type { StepInstance } from "../types/step.js";
+export declare function validateNoReturnSteps(steps: readonly StepInstance[], where: string): void;

package/dist/engine/steps/_no-return-guard.js

@@ -0,0 +1,16 @@
+// Build-time guard for Q12 — sub-pipelines (branch.onTrue/onFalse,
+// forEach.do) may not contain r.step.return. Centralised here so the
+// error message is wordlaut-identical across both sub-step-builders;
+// inline duplication would drift the moment someone edits one site.
+//
+// Extracted at the second sub-step-builder rather than the third because
+// the drift-risk on the Q12 wording is real (advisor M.1.6 cleanup), not
+// because the line-count alone justifies it.
+export function validateNoReturnSteps(steps, where) {
+    for (const step of steps) {
+        if (step.kind === "return") {
+            throw new Error(`r.step.return is not allowed inside ${where} — branch/forEach are side-effect containers (Q12). ` +
+                `Restructure the pipeline so the return happens at the top level.`);
+        }
+    }
+}

package/dist/engine/steps/_read-source.d.ts

@@ -0,0 +1,6 @@
+import type { DbRunner } from "../../db/connection.js";
+import { type TenantDb } from "../../db/tenant-db.js";
+import type { PipelineCtx } from "../types/step.js";
+export declare function readSourceFor(ctx: PipelineCtx, unsafeAllTenants: {
+    readonly reason: string;
+} | undefined): TenantDb | DbRunner;

package/dist/engine/steps/_read-source.js

@@ -0,0 +1,7 @@
+import { unsafeRawForDeclaredStep } from "../../db/tenant-db.js";
+// unsafeRaw fails closed without the handler's escapeHatch (or systemScope) and reports the use.
+export function readSourceFor(ctx, unsafeAllTenants) {
+    if (!unsafeAllTenants)
+        return ctx.db;
+    return unsafeRawForDeclaredStep(ctx.systemDb ?? ctx.db, unsafeAllTenants.reason);
+}

package/dist/engine/steps/_resolver-utils.d.ts

@@ -0,0 +1,11 @@
+import type { PipelineCtx, StepResolver } from "../types/step.js";
+/**
+ * Resolve a required StepResolver — either a static value or a function.
+ * Throws if `arg` is undefined; caller must guarantee presence.
+ */
+export declare function resolveRequired<T>(arg: StepResolver<T>, ctx: PipelineCtx): T;
+/**
+ * Resolve an optional StepResolver — returns undefined when arg is
+ * undefined, otherwise the resolved value.
+ */
+export declare function resolveOptional<T>(arg: StepResolver<T> | undefined, ctx: PipelineCtx): T | undefined;

package/dist/engine/steps/_resolver-utils.js

@@ -0,0 +1,36 @@
+// Resolver-call helpers — eliminate the typeof-narrow boilerplate that
+// was repeated across 11 step files (return, compute, branch, forEach,
+// read.findOne/findMany, aggregate.create/update/appendEvent,
+// unsafeProjectionUpsert/Delete).
+//
+// Pattern before:
+//   const value = typeof args.x === "function" ? args.x(ctx) : args.x;
+//
+// Pattern after:
+//   const value = resolveRequired(args.x, ctx);
+//
+// The local-alias version (`const r = args.x; typeof r === "function" ? ...`)
+// was needed to satisfy TS narrowing on a property-access; passing the
+// arg through a function-call achieves the same narrowing trivially via
+// the function-parameter binding.
+//
+// Followup #10 (closed at the M.1.6 cleanup-pass).
+/**
+ * Resolve a required StepResolver — either a static value or a function.
+ * Throws if `arg` is undefined; caller must guarantee presence.
+ */
+export function resolveRequired(arg, ctx) {
+    if (typeof arg === "function") {
+        return arg(ctx);
+    }
+    return arg;
+}
+/**
+ * Resolve an optional StepResolver — returns undefined when arg is
+ * undefined, otherwise the resolved value.
+ */
+export function resolveOptional(arg, ctx) {
+    if (arg === undefined)
+        return undefined;
+    return resolveRequired(arg, ctx);
+}

package/dist/engine/steps/_step-dispatch-constants.d.ts

@@ -0,0 +1,13 @@
+export declare const STEP_DISPATCH_AGGREGATE_TYPE = "step-dispatch";
+export declare const STEP_DISPATCH_REQUESTED_TYPE = "kumiko:system:step.dispatch-requested";
+export declare const STEP_DISPATCHED_TYPE = "kumiko:system:step.dispatched";
+export declare const STEP_DISPATCH_FAILED_TYPE = "kumiko:system:step.dispatch-failed";
+export declare const WORKFLOW_WAITING_TYPE = "kumiko:system:workflow.step.waiting";
+export declare const WORKFLOW_WAITING_FOR_EVENT_TYPE = "kumiko:system:workflow.step.waiting-for-event";
+export declare const WORKFLOW_RESUMED_TYPE = "kumiko:system:workflow.step.resumed";
+export declare const WORKFLOW_AGGREGATE_TYPE = "workflow-run";
+export declare const WORKFLOW_RUN_STARTED_TYPE = "kumiko:system:workflow.run-started";
+export declare const WORKFLOW_RUN_COMPLETED_TYPE = "kumiko:system:workflow.run-completed";
+export declare const WORKFLOW_RUN_FAILED_TYPE = "kumiko:system:workflow.run-failed";
+export declare const SUSPEND_SENTINEL: unique symbol;
+export declare const WORKFLOW_RETRY_SCHEDULED_TYPE = "kumiko:system:workflow.retry.scheduled";

package/dist/engine/steps/_step-dispatch-constants.js

@@ -0,0 +1,32 @@
+// Shared constants for the deferred-step dispatcher pipeline. Extracted
+// so individual step-builders (webhook.send, mail.send, ...) don't
+// import from each other and silently break on a future split.
+export const STEP_DISPATCH_AGGREGATE_TYPE = "step-dispatch";
+// System-event namespace (kumiko:system:*) — bypasses registry +
+// ownership checks in append-event-core. Reserved for framework-internal
+// step-engine coordination. The bundled step-dispatcher MSP listens
+// for the literal type-string.
+export const STEP_DISPATCH_REQUESTED_TYPE = "kumiko:system:step.dispatch-requested";
+export const STEP_DISPATCHED_TYPE = "kumiko:system:step.dispatched";
+export const STEP_DISPATCH_FAILED_TYPE = "kumiko:system:step.dispatch-failed";
+// --- Tier-3 / Workflow async step constants ---
+// Written by wait / waitForEvent / retry steps onto the workflow-run stream.
+// The Resume-Loop reads these to decide when to resume a suspended run.
+export const WORKFLOW_WAITING_TYPE = "kumiko:system:workflow.step.waiting";
+export const WORKFLOW_WAITING_FOR_EVENT_TYPE = "kumiko:system:workflow.step.waiting-for-event";
+export const WORKFLOW_RESUMED_TYPE = "kumiko:system:workflow.step.resumed";
+// Workflow-run aggregate type — each workflow run is an event-sourced
+// aggregate stream.
+export const WORKFLOW_AGGREGATE_TYPE = "workflow-run";
+// Workflow-run lifecycle events — written by the event-trigger subscriber
+// and the resume-loop onto a workflow-run aggregate stream.
+export const WORKFLOW_RUN_STARTED_TYPE = "kumiko:system:workflow.run-started";
+export const WORKFLOW_RUN_COMPLETED_TYPE = "kumiko:system:workflow.run-completed";
+export const WORKFLOW_RUN_FAILED_TYPE = "kumiko:system:workflow.run-failed";
+// Step return sentinel — when a step's run() returns this value,
+// runStepList stops and yields a "suspended" outcome. The caller
+// (defineWorkflow / workflow-engine) persists the suspension state.
+export const SUSPEND_SENTINEL = Symbol("kumiko:step:suspend");
+// Workflow retry scheduled — written by the retry step when a sub-pipeline
+// fails and a retry attempt is scheduled with backoff.
+export const WORKFLOW_RETRY_SCHEDULED_TYPE = "kumiko:system:workflow.retry.scheduled";

package/dist/engine/steps/aggregate-append-event.d.ts

@@ -0,0 +1,10 @@
+import type { StepInstance, StepResolver } from "../types/step.js";
+type AggregateAppendEventArgs = {
+    readonly aggregateId: StepResolver<string>;
+    readonly aggregateType: string;
+    readonly type: string;
+    readonly payload: StepResolver<unknown>;
+    readonly headers?: StepResolver<Readonly<Record<string, string | number | boolean>>>;
+};
+export declare function buildAggregateAppendEventStep(args: AggregateAppendEventArgs): StepInstance;
+export {};

package/dist/engine/steps/aggregate-append-event.js

@@ -0,0 +1,43 @@
+// r.step.aggregate.appendEvent — write an additional domain-event onto
+// an existing aggregate stream.
+//
+// Wraps ctx.unsafeAppendEvent: the event lands on the named aggregate
+// stream in the active TX, downstream projections (multiStreamProjection)
+// fire, audit-trail captures it. Used when a write-handler needs to
+// record a domain event that's NOT one of the auto-generated CRUD
+// events (e.g. "incident.update-posted" on the same incident stream
+// that already carries "incident.created").
+//
+// Why `unsafeAppendEvent` (not the strict `appendEvent`): step.run sees
+// `ctx` as PipelineCtx<unknown, KumikoEventTypeMap> after the variance-
+// bridge cast in run-pipeline.ts. The strict TMap-typed appendEvent
+// would collapse `keyof TMap` to `never` from the framework-side. Strict
+// typing of appendEvent inside steps is a deferred pass (post-M.1.5).
+// At the call-site users still spell `type` as a string-literal — TS
+// catches typos against the QualifiedEventName union when the literal
+// matches a registered EventDef.
+//
+// No result-key — appendEvent doesn't surface a value to subsequent
+// steps (the event-store assigns the position, but consumers don't
+// need it during the same handler call).
+import { defineStep } from "../define-step.js";
+import { resolveOptional, resolveRequired } from "./_resolver-utils.js";
+defineStep({
+    kind: "aggregate.appendEvent",
+    defaultFailureStrategy: "throw",
+    run: async (args, ctx) => {
+        const aggregateId = resolveRequired(args.aggregateId, ctx);
+        const payload = resolveRequired(args.payload, ctx);
+        const headers = resolveOptional(args.headers, ctx);
+        await ctx.unsafeAppendEvent({
+            aggregateId,
+            aggregateType: args.aggregateType,
+            type: args.type,
+            payload,
+            ...(headers !== undefined && { headers }),
+        });
+    },
+});
+export function buildAggregateAppendEventStep(args) {
+    return { kind: "aggregate.appendEvent", args };
+}

package/dist/engine/steps/aggregate-create.d.ts

@@ -0,0 +1,6 @@
+import type { EventStoreExecutor } from "../../db/event-store-executor.js";
+import type { StepInstance, StepResolver } from "../types/step.js";
+export declare function buildAggregateCreateStep(name: string, opts: {
+    readonly executor: EventStoreExecutor;
+    readonly data: StepResolver<Record<string, unknown>>;
+}): StepInstance;

package/dist/engine/steps/aggregate-create.js

@@ -0,0 +1,38 @@
+// r.step.aggregate.create — open a new event-sourced aggregate stream.
+//
+// Wraps the existing createEventStoreExecutor.create(): writes the
+// `<entity>.created` event to the aggregate stream + applies the inline
+// projection, both in the active TX. Lifecycle hooks (postSave),
+// field-access write rules, crypto-shredding, audit-trail and the rest
+// of the framework-protections all run because we go through the
+// executor (the canonical aggregate-mutation path).
+//
+// Returns the SaveContext { id, data, changes, previous, isNew, event }
+// — landed under steps.<name> so subsequent steps can read steps.<name>.id.
+//
+// Failure-handling: M.1.1's "throw"-only strategy applies. If the
+// executor returns a WriteFailure, we re-raise as a KumikoError so the
+// dispatcher's catch maps it to the standard write-failure shape on the
+// HTTP response.
+import { reraiseAsKumikoError } from "../../errors/write-error-info.js";
+import { defineStep } from "../define-step.js";
+import { resolveRequired } from "./_resolver-utils.js";
+defineStep({
+    kind: "aggregate.create",
+    defaultFailureStrategy: "throw",
+    resultKey: (args) => args.name,
+    run: async (args, ctx) => {
+        const data = resolveRequired(args.data, ctx);
+        const result = await args.executor.create(data, ctx.event.user, ctx.db);
+        if (!result.isSuccess) {
+            throw reraiseAsKumikoError(result.error);
+        }
+        return result.data;
+    },
+});
+export function buildAggregateCreateStep(name, opts) {
+    return {
+        kind: "aggregate.create",
+        args: { name, executor: opts.executor, data: opts.data },
+    };
+}

package/dist/engine/steps/aggregate-update.d.ts

@@ -0,0 +1,10 @@
+import type { EventStoreExecutor } from "../../db/event-store-executor.js";
+import type { EntityId } from "../types/identifiers.js";
+import type { StepInstance, StepResolver } from "../types/step.js";
+export declare function buildAggregateUpdateStep(name: string, opts: {
+    readonly executor: EventStoreExecutor;
+    readonly id: StepResolver<EntityId>;
+    readonly changes: StepResolver<Record<string, unknown>>;
+    readonly version?: StepResolver<number | undefined>;
+    readonly skipOptimisticLock?: boolean;
+}): StepInstance;

package/dist/engine/steps/aggregate-update.js

@@ -0,0 +1,38 @@
+// r.step.aggregate.update — apply a delta to an existing aggregate stream.
+//
+// Wraps the existing createEventStoreExecutor.update(): writes the
+// `<entity>.updated` event + applies the inline projection in the
+// active TX. Optimistic-locking via the optional `version` field —
+// pipeline-author can supply the loaded version (often via a prior
+// r.step.read.findOne) or skip with skipOptimisticLock.
+//
+// Returns the SaveContext { id, data, changes, previous, isNew, event }
+// — landed under steps.<name>. `changes` and `previous` are useful for
+// hooks/audit consumers; the `id` matches the input id.
+//
+// Failure-handling mirrors aggregate.create: WriteFailure → re-raised
+// as KumikoError → dispatcher catches and maps.
+import { reraiseAsKumikoError } from "../../errors/write-error-info.js";
+import { defineStep } from "../define-step.js";
+import { resolveOptional, resolveRequired } from "./_resolver-utils.js";
+defineStep({
+    kind: "aggregate.update",
+    defaultFailureStrategy: "throw",
+    resultKey: (args) => args.name,
+    run: async (args, ctx) => {
+        const id = resolveRequired(args.id, ctx);
+        const changes = resolveRequired(args.changes, ctx);
+        const version = resolveOptional(args.version, ctx);
+        const result = await args.executor.update({ id, version, changes }, ctx.event.user, ctx.db, args.skipOptimisticLock ? { skipOptimisticLock: true } : undefined);
+        if (!result.isSuccess) {
+            throw reraiseAsKumikoError(result.error);
+        }
+        return result.data;
+    },
+});
+export function buildAggregateUpdateStep(name, opts) {
+    return {
+        kind: "aggregate.update",
+        args: { name, ...opts },
+    };
+}

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

@@ -0,0 +1,8 @@
+import type { StepInstance, StepResolver } from "../types/step.js";
+type BranchArgs = {
+    readonly if: StepResolver<boolean>;
+    readonly onTrue: readonly StepInstance[];
+    readonly onFalse?: readonly StepInstance[];
+};
+export declare function buildBranchStep(args: BranchArgs): StepInstance;
+export {};