@cosmicdrift/kumiko-framework 0.2.3 → 0.3.0

package/src/engine/types/step.ts

@@ -0,0 +1,334 @@
+// Step-Vocabulary Types — see docs/plans/architecture/intern/step-vocabulary.md
+//
+// M.1 minimal scope:
+//   - Steps execute against the existing HandlerContext (no per-step subset).
+//   - steps-accumulator is Record<string, unknown> (no tuple-reduce typing).
+//   - Resolvers receive the full PipelineCtx as one argument.
+//
+// Strict typing on appendEvent inside steps is deferred to a later pass
+// (see TS-typing notes in the design doc). M.1 uses unsafeAppendEvent
+// semantics under the hood for r.step.aggregate.appendEvent.
+
+import type { SQL, Table } from "drizzle-orm";
+import type { EventStoreExecutor } from "../../db/event-store-executor";
+import type { KumikoEventTypeMap } from "./event-type-map";
+import type { HandlerContext, WriteEvent, WriteResult } from "./handlers";
+import type { SaveContext } from "./hooks";
+import type { EntityId } from "./identifiers";
+
+/**
+ * The kind discriminator for a step instance — matches the step's
+ * registration name in the step-registry (e.g. "return", "compute",
+ * "aggregate.create"). Steps register themselves at module-load time
+ * via defineStep().
+ */
+export type StepKind = string;
+
+/**
+ * Pipeline-side context handed to step argument resolvers.
+ *
+ * Contains the full HandlerContext (no per-step subset in M.1) plus
+ * the accumulated `steps` map of prior step results, and a `scope`
+ * record for forEach/branch-local bindings.
+ *
+ * `scope` is `Record<string, unknown>` — sub-step builders (forEach,
+ * branch) populate it once they land in later M.1 slices. M.1.1 ships
+ * with `r.step.return` only, which reads `event` and ignores both
+ * `steps` and `scope`.
+ */
+export type PipelineCtx<
+  TPayload = unknown,
+  TMap extends object = KumikoEventTypeMap,
+> = HandlerContext<TMap> & {
+  readonly event: WriteEvent<TPayload>;
+  readonly steps: Readonly<Record<string, unknown>>;
+  readonly scope: Readonly<Record<string, unknown>>;
+  // Workflow-run context — present only when running inside defineWorkflow.
+  // Tier-3 steps use this to write suspension events onto the correct
+  // aggregate stream and for the Resume-Loop to re-hydrate state.
+  readonly workflow?: {
+    readonly runId: string;
+    readonly workflowName: string;
+    /** Current step index in the pipeline — set by the executor before each step. */
+    readonly stepIndex: number;
+    /**
+     * Retry attempt counter for the current workflow.retry step.
+     * Set by the workflow-engine resume-loop on re-entry; starts at 1.
+     * Absent (undefined) means first attempt.
+     */
+    readonly retryAttempt?: number;
+    /**
+     * Q7 Snapshot-at-Start fingerprint of the workflow definition that
+     * started this run. Propagated into every suspension event payload so
+     * the resume-loop can detect library-upgrades that changed the closure
+     * source and surface them as a typed failure instead of running a
+     * stale-vs-new mix of steps. Optional only for legacy callers; the
+     * workflow-runner sets it on every newly-started run.
+     */
+    readonly definitionFingerprint?: string;
+  };
+};
+
+/**
+ * A resolver is either a static value or a function that derives the
+ * value from the pipeline-context. M.1 keeps the resolver signature
+ * uniform — every step accepts both forms via a normalise helper.
+ */
+export type StepResolver<T, TPayload = unknown> = T | ((ctx: PipelineCtx<TPayload>) => T);
+
+/**
+ * Per-step error strategy. M.1.1 only supports "throw" — the type is
+ * deliberately narrowed so callers cannot pass an unsupported strategy
+ * past the type-checker. The doc lists "return" / "skip" / fallback as
+ * future strategies; each lands together with its own runtime support
+ * + integration test in a later slice (no untested type expansion).
+ */
+export type StepFailureStrategy = "throw";
+
+export type StepDef<TArgs = unknown, TResult = unknown> = {
+  readonly kind: StepKind;
+  readonly defaultFailureStrategy: StepFailureStrategy;
+  // Returns the result-key for this step instance, or undefined when the
+  // step doesn't surface a result. The first-position name on the call
+  // (e.g. r.step.compute("startedAt", fn) → "startedAt") becomes the key.
+  readonly resultKey?: (args: TArgs) => string | undefined;
+  // Sub-pipeline arg-paths — names of `args.<path>` entries that hold a
+  // readonly StepInstance[] (e.g. branch's `["onTrue", "onFalse"]`, forEach's
+  // `["do"]`). The boot-validator reads these at registration time so it
+  // can recurse into nested pipelines without a hardcoded kind-list. Steps
+  // that don't carry sub-pipelines omit the field. Followup #15 self-
+  // registration: prevents future sub-step-builders from silently bypassing
+  // the unsafeProjection allowlist by forgetting to update a central map.
+  readonly subPaths?: readonly string[];
+  // Step-vocabulary tier (Q9). Tier-1 implicit, Tier-2+ requires
+  // r.requires.step("<kind>") in the owning feature. Default 1 (implicit).
+  // Tier-3 is only available inside defineWorkflow.
+  readonly tier?: 1 | 2 | 3;
+  // Runtime: resolve the args against the ctx, perform the work, return
+  // the value to land in steps.{resultKey}. Thrown errors propagate to
+  // the dispatcher's catch (M.1.1 supports "throw"-strategy only).
+  readonly run: (args: TArgs, ctx: PipelineCtx) => Promise<TResult> | TResult;
+};
+
+/**
+ * An instance of a step in a pipeline — what users build via the
+ * step-builder (`r.step.compute(...)`). Carries the kind + resolved-or-
+ * resolver args + the user-chosen onFailure override.
+ *
+ * `args` is `unknown` at this layer — the registered StepDef knows the
+ * concrete shape and casts at run() time. Cross-step type-safety lives
+ * in the per-step builder factories, not in this central type.
+ */
+export type StepInstance = {
+  readonly kind: StepKind;
+  readonly args: unknown;
+  readonly onFailure?: StepFailureStrategy;
+};
+
+/**
+ * What `pipeline(closure)` returns. Carries the closure (instead of an
+ * eagerly-built array) so each handler-call sees a fresh event ref and
+ * the `r` step-builder is resolved at runtime, not at module-load time.
+ *
+ * `__kind: "pipeline"` lets defineWriteHandler distinguish a pipeline-
+ * form `perform` from accidental other shapes.
+ *
+ * `_TData` is a phantom type-parameter — held in constraint position
+ * only, never referenced in the type body. defineWriteHandler binds it
+ * via `def.perform: PipelineDef<…, TData>` (the call-site uses TData
+ * without underscore — phantom-prefix is purely a Biome
+ * `noUnusedVariables` marker, not user-facing). _TData is NOT inferred
+ * from the closure body (r.step.return has its own per-call TData), so
+ * callers must spell it explicitly:
+ *   `pipeline<{ greeting: string }, { echoed: string }>(...)`
+ * Better DX is a known follow-up — see step-vocabulary.md M.1-Followups.
+ */
+export type PipelineDef<TPayload = unknown, _TData = unknown> = {
+  readonly __kind: "pipeline";
+  readonly build: (ctx: PipelineBuildCtx<TPayload>) => readonly StepInstance[];
+};
+
+/**
+ * Argument bundle passed to the closure inside `pipeline(closure)`.
+ * Build-time only — no `steps`, no `scope`, no `db`: at build time no
+ * step has run yet.
+ *
+ * The closure is invoked ONCE per handler-call and returns the immutable
+ * list of step instances. Values inside the closure that depend on prior
+ * step results MUST go through resolvers (functions) — those receive the
+ * resolver-side PipelineCtx which carries `steps` + `scope`.
+ *
+ * **Closure-body contract:** the closure must produce a deterministic
+ * step-list that doesn't depend on `event.payload` — branching on payload
+ * fields belongs inside resolvers (where they fire per-call), not in the
+ * outer closure body. Boot-validation runs the closure once with a dummy
+ * empty payload to scan unsafeProjection-* step targets; a closure that
+ * conditionally builds different step-lists per payload would silently
+ * skip validation. See validate-projection-allowlist.ts for the
+ * boot-side mechanics.
+ */
+export type PipelineBuildCtx<TPayload = unknown> = {
+  readonly event: WriteEvent<TPayload>;
+  readonly r: StepBuilder;
+};
+
+/**
+ * Step-builder namespace handed to the pipeline closure. The fields
+ * grow as M.1 adds more steps. Each is a thin factory that returns a
+ * StepInstance — the runtime resolution happens later in run().
+ *
+ * Why nested under `step`: matches the doc-API surface and leaves room
+ * for future sibling namespaces (`r.trigger`, `r.transform`) without
+ * crowding the top-level r.
+ */
+export type StepBuilder = {
+  readonly step: StepNamespace;
+};
+
+/**
+ * The collection of step factory functions. Grown incrementally —
+ * landed: return (M.1.1), compute (M.1.2), unsafeProjectionUpsert
+ * (M.1.3), aggregate.create (M.1.4). Pending: branch, forEach,
+ * read.*, aggregate.update, aggregate.appendEvent,
+ * unsafeProjectionDelete.
+ */
+export type StepNamespace = {
+  readonly return: <TData>(resolver: StepResolver<WriteResult<TData>>) => StepInstance;
+  readonly compute: <TResult>(name: string, fn: (ctx: PipelineCtx) => TResult) => StepInstance;
+  // Inline read-side projection write. Boot-validation enforces the
+  // table is in the owning feature's r.requires.projection allowlist
+  // and NOT registered as an aggregate-table via r.entity. See
+  // step-vocabulary.md "Was unsafeProjection.* überspringt".
+  readonly unsafeProjectionUpsert: (args: {
+    readonly table: Table;
+    readonly on: readonly string[];
+    readonly row: StepResolver<Record<string, unknown>>;
+  }) => StepInstance;
+  // Sibling: delete row(s) from a read-side projection table. Same
+  // boot-validation contract as unsafeProjectionUpsert.
+  readonly unsafeProjectionDelete: (args: {
+    readonly table: Table;
+    readonly where: StepResolver<SQL>;
+  }) => StepInstance;
+  // Read sub-namespace — thin wrapper on ctx.db.select(). Caller-owned
+  // tenant-filter (does NOT auto-inject like ctx.queryProjection does).
+  readonly read: {
+    readonly findOne: (
+      name: string,
+      opts: {
+        readonly table: Table;
+        readonly where: StepResolver<SQL | undefined>;
+      },
+    ) => StepInstance;
+    readonly findMany: (
+      name: string,
+      opts: {
+        readonly table: Table;
+        readonly where?: StepResolver<SQL | undefined>;
+        readonly limit?: number;
+      },
+    ) => StepInstance;
+  };
+  // Aggregate-mutation sub-namespace — wraps the existing event-store-
+  // executor surface. Every method goes through the full ES pipeline
+  // (events + projections + lifecycle hooks + audit). The default and
+  // intended path for domain mutation; contrast with unsafeProjection.*.
+  readonly aggregate: {
+    readonly create: (
+      name: string,
+      opts: {
+        readonly executor: EventStoreExecutor;
+        readonly data: StepResolver<Record<string, unknown>>;
+      },
+    ) => StepInstance;
+    readonly update: (
+      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;
+    readonly appendEvent: (args: {
+      readonly aggregateId: StepResolver<string>;
+      readonly aggregateType: string;
+      readonly type: string;
+      readonly payload: StepResolver<unknown>;
+      readonly headers?: StepResolver<Readonly<Record<string, string | number | boolean>>>;
+    }) => StepInstance;
+  };
+  // Conditional sub-pipeline. `onTrue` (required) and `onFalse`
+  // (optional) are static StepInstance arrays; `r` for sub-step builders
+  // is captured from the outer pipeline closure. Naming-Q14: `onTrue`/
+  // `onFalse` over `then`/`else` because Biome's noThenProperty lint
+  // flags `then` as a thenable-trap. Q12: r.step.return inside
+  // onTrue/onFalse is rejected at build time (would trigger
+  // discriminated-union TData trap). Q13: no resultKey — branch is
+  // side-effect-only.
+  readonly branch: (args: {
+    readonly if: StepResolver<boolean>;
+    readonly onTrue: readonly StepInstance[];
+    readonly onFalse?: readonly StepInstance[];
+  }) => StepInstance;
+  // Iterate a sub-pipeline over an array. `as` is required (Q15);
+  // current item lands under `scope[as]` for resolvers in `do`.
+  // Sequential only in M.1.6; concurrency is Followup #12.
+  readonly forEach: <TItem = unknown>(args: {
+    readonly over: StepResolver<readonly TItem[]>;
+    readonly as: string;
+    readonly do: readonly StepInstance[];
+    readonly concurrency?: 1;
+  }) => StepInstance;
+  // Tier-2 namespace. Each builder requires r.requires.step("<kind>")
+  // in the owning feature; boot-validation enforces.
+  readonly webhook: {
+    readonly send: (args: {
+      readonly url: StepResolver<string>;
+      readonly method?: "POST" | "PUT" | "PATCH";
+      readonly headers?: StepResolver<Readonly<Record<string, string>>>;
+      readonly body?: StepResolver<unknown>;
+      readonly auth?:
+        | { readonly kind: "bearer"; readonly secretRef: string }
+        | { readonly kind: "header"; readonly name: string; readonly secretRef: string };
+      readonly mode: "deferred";
+      readonly retry?: { readonly times: number; readonly backoff: "exponential" | "linear" };
+    }) => StepInstance;
+  };
+  readonly mail: {
+    readonly send: (args: {
+      readonly to: StepResolver<string | readonly string[]>;
+      readonly subject: StepResolver<string>;
+      readonly body: StepResolver<string>;
+      readonly from?: StepResolver<string>;
+      readonly mode: "deferred";
+    }) => StepInstance;
+  };
+  readonly callFeature: (
+    name: string,
+    opts: {
+      readonly handler: string;
+      readonly payload: StepResolver<unknown>;
+      readonly as?: import("./handlers").SessionUser;
+    },
+  ) => StepInstance;
+  // --- Tier-3 / Workflow-only steps ---
+  // Only available inside defineWorkflow ({ steps: pipeline(...) }).
+  // Runtime guard: throws when used inside sync defineWriteHandler.
+  readonly wait: (args: { readonly for: StepResolver<string> }) => StepInstance;
+  readonly waitForEvent: (args: {
+    readonly event: string;
+    readonly match?: StepResolver<(payload: unknown) => boolean>;
+    readonly timeout: StepResolver<string>;
+  }) => StepInstance;
+  readonly retry: (args: {
+    readonly times: number;
+    readonly backoff: "exponential" | "linear";
+    readonly do: readonly StepInstance[];
+  }) => StepInstance;
+};
+
+// SaveContext is the result-type of aggregate.create / aggregate.update;
+// re-exported for step authors who want to type their resolver bindings.
+export type AggregateStepResult = SaveContext;

package/src/engine/types/target-ref.ts

@@ -0,0 +1,21 @@
+// TargetRef — runtime-Repräsentation eines typed buildTarget-Outputs.
+// Wird vom Visual-Tree-Component (renderer-web) an einen Target-Resolver
+// dispatcht; der Resolver findet die Editor-Maske via featureId.
+//
+// **Compile-time-Safety:** TargetRef wird niemals hand-getippt. Stattdessen
+// erzeugt der typed buildTarget-Builder (engine/build-target.ts) einen
+// TargetRef, dessen action + args gegen die treeActions-Map des Ziel-
+// Features validiert sind.
+//
+// **Runtime:** args sind hier untyped (Record<string, unknown>), weil
+// TargetRef die erased-runtime-Version ist. Der Resolver kennt das
+// Ziel-Feature und kann args entsprechend casten — ähnlich wie Event-
+// Payloads im Event-Store.
+//
+// Siehe docs/plans/architecture/visual-tree.md A5.
+
+export type TargetRef = {
+  readonly featureId: string;
+  readonly action: string;
+  readonly args?: Readonly<Record<string, unknown>>;
+};

package/src/engine/types/tree-node.ts

@@ -0,0 +1,130 @@
+// TreeNode — single Knoten im Visual-Tree (opt-in Workspace mit
+// `navigation: "tree"`). Provider liefern entweder statische
+// readonly TreeNode[] oder dynamische TreeChildrenSubscribe.
+//
+// **Mental-Modell** (VS-Code-Explorer):
+//   [icon] [label] [...hover-actions]
+// optional ein target zum Klicken (öffnet Editor-Maske via
+// Target-Resolver) und optional children als nested tree.
+//
+// **State** markiert Visual-Modus für Skeleton-Pattern:
+//   - "filled" (default) — schwarz, Knoten hat Inhalt
+//   - "stub" — hellgrau, existing aber leer (Designer-Stub-File)
+//   - "empty" — Platzhalter für "+ create"-Affordance
+//   - "loading" — Children werden gerade aufgelöst
+//   - "error" — Provider hat Fehler emittiert
+// Provider die kein Skeleton-Pattern brauchen müssen state nicht setzen.
+//
+// **Subscribe-Form** für dynamic Children: Provider erhält emit(),
+// gibt unsubscribe() zurück. Initial-Emit synchron oder async, weitere
+// Emits beliebig oft (z.B. wenn Entity-Row neu erscheint via SSE).
+// Spielt natürlich mit existing SSE-Frame: ein Provider kann intern
+// auf Entity-Update-Events abonnieren und bei Änderung emit() aufrufen.
+//
+// Siehe docs/plans/architecture/visual-tree.md A4.
+
+import type { TenantId } from "./identifiers";
+import type { TargetRef } from "./target-ref";
+
+export type TreeNodeState = "filled" | "stub" | "empty" | "loading" | "error";
+
+export type TreeAction = {
+  // Icon-Key — vom Renderer-Icon-Registry interpretiert. Konvention
+  // matched NavDefinition.icon: unbekannte Icons surface als missing-icon
+  // im UI, nicht als Boot-Failure.
+  readonly icon: string;
+  // i18n-Translation-Key oder roher String. Vom Renderer aufgelöst, Engine
+  // behandelt opak (mirrors NavDefinition.label, WorkspaceDefinition.label).
+  readonly label: string;
+  // Klick-Ziel der Action. Pflicht — Action ohne target ist semantisch
+  // sinnlos (Hover-Icon das nichts tut).
+  readonly target: TargetRef;
+};
+
+export type TreeNode = {
+  // i18n-Translation-Key oder roher String. Vom Renderer beim Rendern
+  // aufgelöst (siehe TreeAction.label).
+  readonly label: string;
+  // Optional. Icon links neben dem Label. Selbe Konvention wie
+  // TreeAction.icon — Renderer-Icon-Registry-Lookup.
+  readonly icon?: string;
+  // Visueller State für Skeleton-Pattern. Default "filled" (kein Eintrag
+  // ⇒ schwarz/normal). Wert-Semantik im Header-Comment dieser Datei.
+  readonly state?: TreeNodeState;
+  // Optional Klick-Ziel. Fehlt → reiner Container-Knoten (nur ausklappbar,
+  // nicht klickbar). Vorhanden → Klick öffnet die Editor-Maske via
+  // Target-Resolver in renderer-web.
+  readonly target?: TargetRef;
+  // Hover-Actions rechts (Add/Refresh/Delete/etc.). Werden in der
+  // Sidebar-Row erst bei Hover sichtbar — VS-Code-Pattern. Engine
+  // ordnet die Actions in der Reihenfolge an, in der sie hier stehen.
+  readonly actions?: readonly TreeAction[];
+  // Statische Children oder dynamic Subscribe-Function. Subscribe wird
+  // erst beim Ausklappen aufgerufen (lazy); die Function-Form erlaubt
+  // SSE-gefütterte Live-Updates wenn neue Entity-Rows reinkommen.
+  readonly children?: readonly TreeNode[] | TreeChildrenSubscribe;
+  // Provider-deklarierte „+ create"-Action für Knoten mit `state: "empty"`.
+  // Tree-Component zeigt automatisch ein „+"-Icon und dispatcht
+  // `createAction.target` bei Klick — Provider weiß was „leer befüllen"
+  // für ihn bedeutet (z.B. „neuer Page-Slug" vs „neue Entity-Row"),
+  // Convention könnte das nicht raten. Konsistent zu `state` (auch
+  // Provider-explizit). Siehe visual-tree.md V.1.1-Decision D3.
+  readonly createAction?: TreeAction;
+};
+
+// Subscribe<T> — Provider implementiert: emit(initial); ...emit(updated);
+// und gibt unsubscribe-Function zurück. Caller (Tree-Component) ruft
+// unsubscribe auf wenn Knoten unmounted/eingeklappt wird.
+export type Subscribe<T> = (emit: (value: T) => void) => () => void;
+
+// TreeChildrenSubscribe — Lazy-Variante für dynamic Children. Wird
+// erst aufgerufen wenn der Knoten im UI ausgeklappt wird. ctx ist
+// für Phase 0 ein opaque empty Type; V.1.1 erweitert ihn um Query-/
+// Subscribe-Helpers (entity-list, slug-list etc.).
+export type TreeChildrenSubscribe = (ctx: TreeContext) => Subscribe<readonly TreeNode[]>;
+
+// TreeContext — Provider erhält context-Objekt mit den minimal-nötigen
+// React-Tree-State-Bridges. V.1.1 startet mit `tenantId` only (Provider
+// braucht tenant-awareness sonst stale-tenant-Bug bei Tenant-Switch);
+// `query` und `subscribe` werden additiv ergänzt wenn ein konkreter
+// Konsument sie braucht (V.1.2: text-content slug-list-query, später
+// SSE-driven re-emit). Memory `[Keine Optionen ohne Bedarf]` — surface
+// wächst mit Bedarfen, nicht mit Spekulation. Siehe visual-tree.md
+// V.1.1-Decision D1.
+export type TreeContext = Readonly<{
+  readonly tenantId: TenantId;
+}>;
+
+// TreeActionDef — Schema-Eintrag pro Action in der treeActions-Map
+// eines Features. Phase 0: Args sind ein optionales Type-Sample
+// (kein Validator zur Laufzeit — Validation passiert compile-time
+// via buildTarget-Generic, runtime via Editor-Panel-Schema).
+//
+// Lebt hier (nicht in build-target.ts) weil es konzeptuell zur
+// Visual-Tree-Domäne gehört, nicht zum Builder. build-target.ts
+// importiert den Type von hier.
+export type TreeActionDef<TArgs = Record<string, unknown>> = {
+  readonly args?: TArgs;
+};
+
+// TreeActionsHandle<T> — Return-Type von r.treeActions(...). Trägt
+// den literal-typed Action-Map durch das Feature-Export-System
+// (siehe FeatureDefinition.exports + Memory `[EventDef-Exports-
+// Pattern]`). Das ist die compile-time Bridge zu buildTarget:
+//
+//   const handle = r.treeActions({ edit: { args: { slug: "" as string } } });
+//   // handle.id        → TFeature (literal feature name)
+//   // handle.treeActions → { edit: { args: { slug: string } } } (literal-typed)
+//   buildTarget({ target: handle, action: "edit", args: { slug: "x" } });
+//   //                                ^^^^^^^^^^^^^^         ^^^^^^^^
+//   //                                literal-validated      typed-validated
+//
+// Runtime-Lookup geht über FeatureDefinition.treeActions (erased Map),
+// Compile-Time-Validation über diesen Handle.
+export type TreeActionsHandle<
+  TFeature extends string,
+  TActions extends Record<string, TreeActionDef>,
+> = {
+  readonly id: TFeature;
+  readonly treeActions: TActions;
+};

package/src/engine/types/workspace.ts

@@ -39,4 +39,11 @@ export type WorkspaceDefinition = {
   // Default workspace at login when the user has access to multiple. Boot
   // validator rejects more than one default per app.
   readonly default?: boolean;
+  // Render mode of the workspace's sidebar. "nav" (default, missing-ok)
+  // mounts the existing NavTree component as before. "tree" mounts the
+  // Visual-Tree component which collects r.tree() providers across all
+  // active features. Default-on-undefined preserves backwards-compat —
+  // every existing workspace stays nav-mode without code touch.
+  // See visual-tree.md A1.
+  readonly navigation?: "nav" | "tree";
 };

package/src/engine/validate-projection-allowlist.ts

@@ -0,0 +1,161 @@
+// Boot-validation for r.step.unsafeProjection* allowlist.
+//
+// Q10 declared the allowlist a hard requirement: every unsafeProjection*
+// step must target a table that the owning feature explicitly declared
+// via r.requires.projection("table_name"), and that table must NOT be
+// one of the registered aggregate-tables (those are managed via
+// r.entity / r.step.aggregate.*). Boot-error otherwise.
+//
+// Mechanism: each writeHandler that uses the perform-pipeline form ships
+// a closure. We invoke it once at boot with a minimal dummy event to
+// extract the immutable step-list, then walk the list looking for the
+// known unsafeProjection-* kinds. Resolvers (the per-step arg-callbacks)
+// don't run at build time, so dummy event-payloads are fine.
+//
+// CLOSURE-BODY CONTRACT: the pipeline-closure body (the function passed
+// to `pipeline(...)`) must produce its step-list deterministically based
+// on the step-builder `r` alone. Reading `event.payload` outside of
+// resolvers (i.e. at the top of the closure, not inside a step's `row:`
+// or `data:` callback) is forbidden — at boot the dummy payload is `{}`
+// and a closure that branches on payload-fields would pass validation
+// while production calls produce a different step-list. A throw at
+// boot-time is surfaced cleanly; a quietly-different step-list is not
+// caught by this validator. A future lint-rule will enforce the contract
+// statically; today it lives in this comment + the StepBuilder doc.
+
+import { getTableName, type Table } from "drizzle-orm";
+import { getStep } from "./define-step";
+import { buildPipelineSteps } from "./pipeline";
+import type { FeatureDefinition, SessionUser, TenantId, WriteEvent } from "./types";
+import type { PipelineDef, StepInstance } from "./types/step";
+
+// Listed step-kinds whose `args.table` must be in the owning feature's
+// r.requires.projection allowlist. Extend as further unsafeProjection.*
+// steps land — don't pre-list hypothetical kinds (CLAUDE.md: don't design
+// for scenarios that can't happen).
+const UNSAFE_PROJECTION_KINDS = new Set(["unsafeProjectionUpsert", "unsafeProjectionDelete"]);
+
+// Sub-pipeline arg-paths come from `defineStep({ subPaths: [...] })` —
+// each builder declares its own (e.g. branch's onTrue/onFalse, forEach's
+// do). Walking via the registry means nested unsafeProjection-* in NEW
+// sub-step-builders is automatically caught the moment the builder
+// registers itself; no central map to keep in sync. Followup #15.
+function* walkAllSteps(steps: readonly StepInstance[]): Generator<StepInstance, void, void> {
+  for (const step of steps) {
+    yield step;
+    const def = getStep(step.kind);
+    const subPaths = def?.subPaths;
+    if (!subPaths || subPaths.length === 0) continue;
+    const args = step.args as Record<string, unknown>;
+    for (const path of subPaths) {
+      const subSteps = args[path];
+      if (Array.isArray(subSteps)) {
+        yield* walkAllSteps(subSteps as readonly StepInstance[]);
+      }
+    }
+  }
+}
+
+type UnsafeProjectionStepArgs = { readonly table: Table };
+
+const DUMMY_USER: SessionUser = {
+  id: "00000000-0000-0000-0000-000000000000",
+  tenantId: "00000000-0000-0000-0000-000000000000" as TenantId,
+  roles: [],
+};
+
+/**
+ * Validate every feature's pipeline-form writeHandlers against:
+ *   1. the owning feature's r.requires.projection allowlist
+ *   2. the cross-feature aggregate-table set (registered via r.entity)
+ *
+ * Throws on the first violation (fail-fast, consistent with other
+ * boot-validations).
+ */
+export function validateProjectionAllowlist(features: readonly FeatureDefinition[]): void {
+  // Aggregate-tables across all features. Map table-name → owning feature.
+  // Two features registering r.entity on the same table is always a bug —
+  // physical PG-collision aside, the second feature's writes would replay
+  // the first feature's projections (and vice-versa). Detect and surface
+  // here so the error names BOTH owners; without this, the silent-set
+  // would point any later unsafeProjection-error at the wrong feature.
+  // Followup #8.
+  const aggregateTables = new Map<string, string>();
+  for (const f of features) {
+    for (const [entityName, entity] of Object.entries(f.entities)) {
+      const tableName = entity.table ?? entityName;
+      const existing = aggregateTables.get(tableName);
+      if (existing && existing !== f.name) {
+        throw new Error(
+          `Aggregate-table "${tableName}" is registered by both feature "${existing}" and feature "${f.name}" via r.entity. ` +
+            `Each aggregate-table must have a single owning feature — pick distinct table names ` +
+            `(via createEntity({ table: "..." })) or remove the duplicate r.entity registration.`,
+        );
+      }
+      aggregateTables.set(tableName, f.name);
+    }
+  }
+
+  for (const f of features) {
+    for (const [handlerName, handler] of Object.entries(f.writeHandlers)) {
+      const perform = (handler as { readonly perform?: PipelineDef }).perform;
+      if (!perform || perform.__kind !== "pipeline") continue;
+
+      let steps: readonly StepInstance[];
+      try {
+        const dummyEvent: WriteEvent<unknown> = {
+          type: handlerName,
+          payload: {},
+          user: DUMMY_USER,
+        };
+        steps = buildPipelineSteps(perform, dummyEvent);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `[Feature ${f.name}] writeHandler "${handlerName}" pipeline-closure threw at boot: ${message}. ` +
+            `Closure body must produce the step list without reading event-payload fields ` +
+            `(those belong inside step resolvers).`,
+        );
+      }
+
+      for (const step of walkAllSteps(steps)) {
+        // Tier-2 step-discovery (Q9): require explicit opt-in via
+        // r.requires.step("<kind>") for any tier-2+ step. Tier-1 is implicit.
+        const def = getStep(step.kind);
+        if (def?.tier === 2 && !f.requiredSteps.has(step.kind)) {
+          throw new Error(
+            `[Feature ${f.name}] writeHandler "${handlerName}" uses tier-2 step "${step.kind}" ` +
+              `but did not declare it via r.requires.step("${step.kind}"). ` +
+              `Add the declaration in defineFeature("${f.name}", r => { r.requires.step("${step.kind}"); ... }).`,
+          );
+        }
+        if (!UNSAFE_PROJECTION_KINDS.has(step.kind)) continue;
+        const stepArgs = step.args as UnsafeProjectionStepArgs;
+        if (!stepArgs.table) {
+          throw new Error(
+            `[Feature ${f.name}] writeHandler "${handlerName}" has a ${step.kind} step ` +
+              `without a \`table\` argument.`,
+          );
+        }
+        const tableName = getTableName(stepArgs.table);
+
+        const aggregateOwner = aggregateTables.get(tableName);
+        if (aggregateOwner) {
+          throw new Error(
+            `[Feature ${f.name}] writeHandler "${handlerName}" uses ${step.kind} on table "${tableName}", ` +
+              `but that table is the aggregate-projection of feature "${aggregateOwner}" (registered via r.entity). ` +
+              `Aggregate-tables MUST be mutated through r.step.aggregate.* — see step-vocabulary.md Q10.`,
+          );
+        }
+
+        if (!f.requiredProjections.has(tableName)) {
+          throw new Error(
+            `[Feature ${f.name}] writeHandler "${handlerName}" uses ${step.kind} on table "${tableName}", ` +
+              `but the feature did not declare it via r.requires.projection("${tableName}"). ` +
+              `Add the declaration in defineFeature("${f.name}", r => { r.requires.projection("${tableName}"); ... }).`,
+          );
+        }
+      }
+    }
+  }
+}

package/src/event-store/snapshot.ts

@@ -136,7 +136,7 @@ export async function loadLatestSnapshot<
     tenantId: row.tenantId,
     aggregateType: row.aggregateType,
     version: row.version,
-    state: row.state as TState,
+    state: row.state as TState, // @cast-boundary engine-payload
     createdAt: row.createdAt,
   };
 }