@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/src/engine/soft-delete-cleanup.ts

@@ -1,126 +0,0 @@
-// 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, type WhereObject } from "../db/query";
-import { SYSTEM_USER_ID } from "./system-user";
-import type { ConfigKeyDefinition, JobDefinition, JobHandlerFn } from "./types/config";
-
-// 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: ConfigKeyDefinition = {
-  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: JobHandlerFn = 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 as Record<string, unknown>)["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: WhereObject = { 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: JobHandlerFn = 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 as Record<string, unknown>)["tenantId"] !== undefined) continue;
-    await deleteMany(db, proj.table, { isDeleted: true, deletedAt: { lt: cutoff } });
-  }
-};
-
-export function buildSoftDeleteCleanupJob(): JobDefinition {
-  return {
-    name: SOFT_DELETE_CLEANUP_JOB,
-    handler: softDeleteCleanupJob,
-    trigger: { cron: "0 3 * * *" },
-    perTenant: true,
-    concurrency: "skip",
-    runIn: "worker",
-  };
-}
-
-export function buildSoftDeleteCleanupSystemJob(): JobDefinition {
-  return {
-    name: SOFT_DELETE_CLEANUP_SYSTEM_JOB,
-    handler: softDeleteCleanupSystemJob,
-    trigger: { cron: "15 3 * * *" },
-    concurrency: "skip",
-    runIn: "worker",
-  };
-}

package/src/engine/state-machine.ts

@@ -1,71 +0,0 @@
-import { buildInvalidTransitionDetails, FrameworkReasons, UnprocessableError } from "../errors";
-
-/**
- * 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 function defineTransitions<const TMap extends Record<string, readonly string[]>>(
-  map: TMap,
-): TransitionGraph<keyof TMap & string> {
-  type TStates = keyof TMap & string;
-  const internal = new Map<string, ReadonlySet<string>>();
-  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] as TStates[]) : []; // @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<TStates extends string>(
-  transitions: TransitionGraph<TStates>,
-  from: TStates,
-  to: TStates,
-): void {
-  transitions.assertTransition(from, to);
-}

package/src/engine/steps/__tests__/duration-utils.test.ts

@@ -1,20 +0,0 @@
-// kumiko-framework#1525: addDuration must not rely on globalThis.Temporal —
-// it's a pure free function called from step handlers before boot may have
-// run ensureTemporalPolyfill() on every code path.
-
-import { describe, expect, test } from "bun:test";
-import { addDuration } from "../_duration-utils";
-
-describe("addDuration — kumiko-framework#1525: no ambient Temporal global", () => {
-  test("adds a duration without relying on globalThis.Temporal", () => {
-    const savedGlobal = (globalThis as { Temporal?: unknown }).Temporal;
-    delete (globalThis as { Temporal?: unknown }).Temporal;
-    try {
-      const result = addDuration("2026-01-01T00:00:00Z", "P1DT1H");
-      expect(result).toBe("2026-01-02T01:00:00Z");
-    } finally {
-      if (savedGlobal === undefined) delete (globalThis as { Temporal?: unknown }).Temporal;
-      else (globalThis as { Temporal?: unknown }).Temporal = savedGlobal;
-    }
-  });
-});

package/src/engine/steps/_duration-utils.ts

@@ -1,35 +0,0 @@
-// 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: string, duration: string): string {
-  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/src/engine/steps/_event-match.ts

@@ -1,98 +0,0 @@
-// 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.
-
-import type { EventMatch, EventMatchExpr, EventMatchOp } from "../types/step";
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function resolvePath(payload: unknown, path: readonly string[]): unknown {
-  let current: unknown = payload;
-  for (const segment of path) {
-    if (!isRecord(current)) return undefined;
-    current = current[segment];
-  }
-  return current;
-}
-
-function compareOrdered(
-  actual: number | string,
-  expected: number | string,
-  kind: "gt" | "gte" | "lt" | "lte",
-): boolean {
-  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: EventMatchOp, actual: unknown): boolean {
-  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: { readonly kind: string } = op;
-      throw new Error(`Unknown EventMatchOp kind "${unrecognized.kind}"`);
-    }
-  }
-}
-
-function evaluateExpr(expr: EventMatchExpr, payload: unknown): boolean {
-  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: { readonly kind: string } = expr;
-      throw new Error(`Unknown EventMatchExpr kind "${unrecognized.kind}"`);
-    }
-  }
-}
-
-export function evaluateEventMatch(match: EventMatch, payload: unknown): boolean {
-  if (match.version !== 1) {
-    throw new Error(`Unsupported EventMatch version ${JSON.stringify(match.version)} — expected 1`);
-  }
-  return evaluateExpr(match.expr, payload);
-}

package/src/engine/steps/_no-return-guard.ts

@@ -1,21 +0,0 @@
-// 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.
-
-import type { StepInstance } from "../types/step";
-
-export function validateNoReturnSteps(steps: readonly StepInstance[], where: string): void {
-  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/src/engine/steps/_read-source.ts

@@ -1,12 +0,0 @@
-import type { DbRunner } from "../../db/connection";
-import { type TenantDb, unsafeRawForDeclaredStep } from "../../db/tenant-db";
-import type { PipelineCtx } from "../types/step";
-
-// unsafeRaw fails closed without the handler's escapeHatch (or systemScope) and reports the use.
-export function readSourceFor(
-  ctx: PipelineCtx,
-  unsafeAllTenants: { readonly reason: string } | undefined,
-): TenantDb | DbRunner {
-  if (!unsafeAllTenants) return ctx.db;
-  return unsafeRawForDeclaredStep(ctx.systemDb ?? ctx.db, unsafeAllTenants.reason);
-}

package/src/engine/steps/_resolver-utils.ts

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

package/src/engine/steps/_step-dispatch-constants.ts

@@ -1,38 +0,0 @@
-// 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/src/engine/steps/aggregate-append-event.ts

@@ -1,56 +0,0 @@
-// 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";
-import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
-import { resolveOptional, resolveRequired } from "./_resolver-utils";
-
-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>>>;
-};
-
-defineStep<AggregateAppendEventArgs, void>({
-  kind: "aggregate.appendEvent",
-  defaultFailureStrategy: "throw",
-  run: async (args, ctx: PipelineCtx) => {
-    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: AggregateAppendEventArgs): StepInstance {
-  return { kind: "aggregate.appendEvent", args };
-}

package/src/engine/steps/aggregate-create.ts

@@ -1,56 +0,0 @@
-// 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 type { EventStoreExecutor } from "../../db/event-store-executor";
-import { reraiseAsKumikoError } from "../../errors/write-error-info";
-import { defineStep } from "../define-step";
-import type { SaveContext } from "../types/hooks";
-import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
-import { resolveRequired } from "./_resolver-utils";
-
-type AggregateCreateArgs = {
-  readonly name: string;
-  readonly executor: EventStoreExecutor;
-  readonly data: StepResolver<Record<string, unknown>>;
-};
-
-defineStep<AggregateCreateArgs, SaveContext>({
-  kind: "aggregate.create",
-  defaultFailureStrategy: "throw",
-  resultKey: (args) => args.name,
-  run: async (args, ctx: PipelineCtx) => {
-    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: string,
-  opts: {
-    readonly executor: EventStoreExecutor;
-    readonly data: StepResolver<Record<string, unknown>>;
-  },
-): StepInstance {
-  return {
-    kind: "aggregate.create",
-    args: { name, executor: opts.executor, data: opts.data } satisfies AggregateCreateArgs,
-  };
-}

package/src/engine/steps/aggregate-update.ts

@@ -1,68 +0,0 @@
-// 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 type { EventStoreExecutor } from "../../db/event-store-executor";
-import { reraiseAsKumikoError } from "../../errors/write-error-info";
-import { defineStep } from "../define-step";
-import type { SaveContext } from "../types/hooks";
-import type { EntityId } from "../types/identifiers";
-import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
-import { resolveOptional, resolveRequired } from "./_resolver-utils";
-
-type AggregateUpdateArgs = {
-  readonly name: string;
-  readonly executor: EventStoreExecutor;
-  readonly id: StepResolver<EntityId>;
-  readonly changes: StepResolver<Record<string, unknown>>;
-  readonly version?: StepResolver<number | undefined>;
-  readonly skipOptimisticLock?: boolean;
-};
-
-defineStep<AggregateUpdateArgs, SaveContext>({
-  kind: "aggregate.update",
-  defaultFailureStrategy: "throw",
-  resultKey: (args) => args.name,
-  run: async (args, ctx: PipelineCtx) => {
-    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: string,
-  opts: {
-    readonly executor: EventStoreExecutor;
-    readonly id: StepResolver<EntityId>;
-    readonly changes: StepResolver<Record<string, unknown>>;
-    readonly version?: StepResolver<number | undefined>;
-    readonly skipOptimisticLock?: boolean;
-  },
-): StepInstance {
-  return {
-    kind: "aggregate.update",
-    args: { name, ...opts } satisfies AggregateUpdateArgs,
-  };
-}