@cosmicdrift/kumiko-framework 0.2.3 → 0.3.0

package/src/engine/steps/return.ts

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

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

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

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

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

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

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

package/src/engine/steps/wait.ts

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

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

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

package/src/engine/system-user.ts

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

package/src/engine/types/feature.ts

@@ -54,6 +54,7 @@ import type { NavDefinition } from "./nav";
 import type { MultiStreamProjectionDefinition, ProjectionDefinition } from "./projection";
 import type { EntityRelations, RelationDefinition } from "./relations";
 import type { ScreenDefinition } from "./screen";
+import type { TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe } from "./tree-node";
 import type { WorkspaceDefinition } from "./workspace";
 
 // --- Metrics (declared by features via r.metric()) ---
@@ -148,6 +149,14 @@ export type FeatureDefinition = {
   readonly exports?: unknown;
   readonly requires: readonly string[];
   readonly optionalRequires: readonly string[];
+  // Read-side projection-tables this feature is allowed to write via
+  // r.step.unsafeProjectionUpsert / unsafeProjectionDelete. Declared via
+  // r.requires.projection("table_name"). Hard requirement — boot-error
+  // if a step targets a non-listed table or one that's already an
+  // r.entity-registered aggregate-table. See step-vocabulary.md Q10.
+  readonly requiredProjections: ReadonlySet<string>;
+  // Tier-2 step kinds opted-in via r.requires.step("webhook.send"). Q9.
+  readonly requiredSteps: ReadonlySet<string>;
   // Declared via r.toggleable({ default }). Presence makes the feature
   // operator-switchable via the feature-toggles bundled feature; absence
   // means the feature is always-on (e.g. auth, tenant, user — core infra
@@ -224,6 +233,21 @@ export type FeatureDefinition = {
   // shellWorkspaces consumes the resolved per-workspace nav list at mount
   // time; engine validates roles + nav refs at boot.
   readonly workspaces: Readonly<Record<string, WorkspaceDefinition>>;
+  // Tree-Actions-Map declared via r.treeActions(). At-most-one per feature
+  // (only-once-guard at registration). Erased to `Record<string,
+  // TreeActionDef>` for runtime registry-lookup (Visual-Tree-Component
+  // dispatching, Pattern-AST consumers). The compile-time-typed surface
+  // is the registrar's return value (TreeActionsHandle) which the
+  // feature exports via setup-return — buildTarget consumes the handle,
+  // not this slot. See visual-tree.md A5 + A7.
+  readonly treeActions?: Readonly<Record<string, TreeActionDef>>;
+  // Tree-Provider declared via r.tree(). At-most-one per feature.
+  // Provider liefert die Top-Level-Knoten dieses Features im Visual-
+  // Workspace (navigation: "tree"). Subscribe-Form mit lazy-Eval: erst
+  // beim Mount des Workspaces aufgerufen, kann Updates emittieren.
+  // Feature ohne treeProvider ist im Visual-Workspace unsichtbar
+  // (Zero-Whitelist-Filter aus visual-tree.md A2).
+  readonly treeProvider?: TreeChildrenSubscribe;
   // HTTP-Routes declared via r.httpRoute(). Index is "METHOD path"
   // (z.B. "GET /feed.xml") — eindeutig pro Feature. Die App-Server-
   // Boot-Stage iteriert getAllHttpRoutes() und mountet jede Route auf
@@ -250,9 +274,22 @@ type RefOrRefs = NameOrRef | readonly NameOrRef[];
  * keeping strict-mode alive even when handlers route via `eventDef.name`
  * instead of hand-typed string literals.
  */
+/**
+ * `r.requires` is a callable+namespace: existing call form takes feature
+ * names (`r.requires("auth", "tenant")`), the `.projection` extension
+ * declares read-side projection tables that this feature's pipeline
+ * steps are allowed to write via `r.step.unsafeProjectionUpsert`.
+ * Hard-required for any unsafeProjection-* step usage (see Q10).
+ */
+export type RequiresApi = ((...featureNames: string[]) => void) & {
+  readonly projection: (tableName: string) => void;
+  // Tier-2 step opt-in (Q9). Tier-1 implicit, Tier-2 must be declared.
+  readonly step: (stepKind: string) => void;
+};
+
 export type FeatureRegistrar<TFeature extends string = string> = {
   systemScope(): void;
-  requires(...featureNames: string[]): void;
+  requires: RequiresApi;
   optionalRequires(...featureNames: string[]): void;
   // Declare the feature as operator-togglable. `default` is the effective
   // state when no global-toggle row exists. Must be called at most once per
@@ -506,6 +543,44 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // a non-empty string is the contract. If you can't write a reason,
   // declare data via `r.entity()` instead.
   rawTable(name: string, table: PgTable, options: RawTableOptions): void;
+
+  // Register the tree-actions schema for this feature — a map of
+  // action-name → action-definition (with optional typed args). At-most-
+  // one call per feature.
+  //
+  // Returns a TreeActionsHandle that the feature exports via setup-return
+  // (Memory `[EventDef-Exports-Pattern]`). The handle carries the
+  // literal-typed action-map that `buildTarget` consumes for compile-
+  // time validation:
+  //
+  //   const handle = r.treeActions({
+  //     edit: { args: { slug: "" as string } },
+  //     list: {},
+  //   });
+  //   return { handle };
+  //
+  // Without this typed return, the action-map collapses to
+  // `Record<string, TreeActionDef>` at the buildTarget call-site and
+  // every action becomes accept-anything-string. See visual-tree.md A5.
+  //
+  // The runtime FeatureDefinition.treeActions slot stores the same map
+  // as erased Record (registry lookup, Pattern-AST consumers).
+  treeActions<const TActions extends Record<string, TreeActionDef>>(
+    actions: TActions,
+  ): TreeActionsHandle<TFeature, TActions>;
+
+  // Register the tree-provider for this feature — the Subscribe-Function
+  // that emits the top-level Tree-Knoten when the Visual-Workspace
+  // (navigation: "tree") mounts. At-most-one call per feature.
+  //
+  // Provider receives a TreeContext (Phase-0-stub, opaque) and an
+  // emit-function; returns an unsubscribe-function. Initial-emit synchron
+  // oder async, weitere Emits beliebig oft (e.g. on entity-update SSE).
+  //
+  // A feature without r.tree() is invisible in `navigation: "tree"`-
+  // workspaces — that's the Zero-Whitelist-Filter from visual-tree.md A2:
+  // provider-Vorhandensein ist der Filter, kein Workspace-Mapping.
+  tree(provider: TreeChildrenSubscribe): void;
 };
 
 // --- Registry (created from features) ---
@@ -677,4 +752,20 @@ export type Registry = {
   // validator rejects more than one. Apps without a default fall back to
   // the first workspace the user has access to.
   getDefaultWorkspace(): WorkspaceDefinition | undefined;
+
+  // Tree-Providers declared via r.tree() across all features. Keyed by
+  // declaring feature name (NOT qualified — Provider sind feature-bound,
+  // ein Feature liefert genau eine Provider-Function). The Visual-Tree
+  // component (renderer-web) iteriert getTreeProviders() beim Mount des
+  // navigation: "tree"-Workspaces, ruft jeden Provider mit ctx auf,
+  // sammelt die emitted TreeNode[] und merged sie zur Top-Level-Liste.
+  // See visual-tree.md A2 (Zero-Whitelist) + A4 (Subscribe-Form).
+  getTreeProviders(): ReadonlyMap<string, TreeChildrenSubscribe>;
+
+  // Tree-Actions-Map des Features. Returns the erased Record (compile-
+  // time-typed handle wandert über setup-export, nicht hier). Visual-
+  // Tree-Component nutzt das für Runtime-Action-Lookup beim Klick auf
+  // einen TreeNode.target — der Resolver findet das Feature via
+  // TargetRef.featureId und holt sich die zugehörige Action-Definition.
+  getTreeActions(featureName: string): Readonly<Record<string, TreeActionDef>> | undefined;
 };

package/src/engine/types/handlers.ts

@@ -175,9 +175,9 @@ export function withResponseData<T>(result: WriteResult<unknown>, data: T): Writ
 
 // --- Context Types ---
 
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 // Forward import: Registry is in feature.ts (circular type import — fine in TS)
 import type { Registry } from "./feature";
+import type { TenantId } from "./identifiers";
 
 // Minimal interface for job event triggers (framework-owned, concrete type in jobs/)
 export type JobRunnerRef = {
@@ -312,7 +312,7 @@ export type AppContext = SharedContextFields & {
 // TMap propagates the strict event-type-map through `appendEvent`. Defaults
 // to the global KumikoEventTypeMap (augmented per app via
 // `declare module "@cosmicdrift/kumiko-framework/engine"`). Code that bypasses the
-// type-map (runtime-pluggable events) uses `appendEventUnsafe`.
+// type-map (runtime-pluggable events) uses `unsafeAppendEvent`.
 export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedContextFields & {
   readonly db: TenantDb;
   readonly registry: Registry;
@@ -353,11 +353,11 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   readonly appendEvent: AppendEventFn<TMap>;
 
   // Escape-hatch for runtime-pluggable features without a compile-time
-  // augmentation. See AppendEventUnsafeFn — same runtime as appendEvent,
+  // augmentation. See UnsafeAppendEventFn — same runtime as appendEvent,
   // but the type-surface is `payload: unknown`. Use only when the event-
   // type is not knowable at compile-time; otherwise the strict path
   // (appendEvent) is the contract Designer/AI rely on.
-  readonly appendEventUnsafe: AppendEventUnsafeFn;
+  readonly unsafeAppendEvent: UnsafeAppendEventFn;
 
   // Marten FetchForWriting equivalent: load the current stream, optionally
   // enforce expectedVersion, and get a handle that appends further events
@@ -428,11 +428,11 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   // name without the feature having to import the drizzle-table directly.
   //
   // Auto-applies tenant_id filter when the projection table has a tenant_id
-  // column (or opt out with { allTenants: true } for system-scoped reads
+  // column (or opt out with { unsafeAllTenants: true } for system-scoped reads
   // like cross-tenant analytics). Unknown projection name throws.
   readonly queryProjection: <T = Record<string, unknown>>(
     qualifiedName: string,
-    options?: { readonly allTenants?: boolean },
+    options?: { readonly unsafeAllTenants?: boolean },
   ) => Promise<readonly T[]>;
 
   // Always populated — Noop when no observability provider is configured.
@@ -601,7 +601,7 @@ export type TypedAppendEventArgs<TMap extends object, K extends keyof TMap> = {
 // Strict-only form. Single overload — `<K extends keyof TMap>` against the
 // app's pre-bound TMap. No fallback overload: apps that need runtime-pluggable
 // events (where the type-string isn't known at compile-time) reach for
-// `appendEventUnsafe`.
+// `unsafeAppendEvent`.
 //
 // Why no fallback overload:
 //   A two-overload form (`(args: AppendEventArgs)` as the second sig)
@@ -619,13 +619,13 @@ export type TypedAppendEventArgs<TMap extends object, K extends keyof TMap> = {
 //     KumikoEventTypeMap>(...)` wrappers. Handlers inside those wrappers
 //     get a strict ctx.appendEvent.
 //   - Cross-package callers (e.g. bundled-features's set.write.ts) that
-//     can't afford a local wrapper reach for `ctx.appendEventUnsafe`
+//     can't afford a local wrapper reach for `ctx.unsafeAppendEvent`
 //     instead — same runtime, looser type-surface.
 export type AppendEventFn<TMap extends object = KumikoEventTypeMap> = <K extends keyof TMap>(
   args: TypedAppendEventArgs<TMap, K>,
 ) => Promise<void>;
 
-export type AppendEventUnsafeFn = (args: AppendEventArgs) => Promise<void>;
+export type UnsafeAppendEventFn = (args: AppendEventArgs) => Promise<void>;
 
 // Args for ctx.fetchForWriting — Marten FetchForWriting equivalent. Returns
 // the current stream state + a handle that appends without re-specifying
@@ -737,8 +737,16 @@ export type WriteHandlerDef = {
   readonly schema: ZodType;
   readonly handler: WriteHandlerFn;
   readonly access?: AccessRule;
-  readonly skipTransitionGuard?: boolean;
+  readonly unsafeSkipTransitionGuard?: boolean;
   readonly rateLimit?: RateLimitOption;
+  // Set when the author wrote a `perform: pipeline(...)` block. Boot-
+  // validators (projection-allowlist) and Designer/AI tooling read this
+  // to inspect the step list. Absent on free-form handlers.
+  // Inline-import is intentional: step.ts imports HandlerContext from
+  // this file, a top-level `import type { PipelineDef } from "./step"`
+  // would form a type-only circular import that TS resolves but tooling
+  // (incremental compile, IDEs) sometimes mis-handles.
+  readonly perform?: import("./step").PipelineDef;
 };
 
 export type QueryHandlerDef = {

package/src/engine/types/identifiers.ts

@@ -1,3 +1,4 @@
+// @runtime client
 // Domain-identifier type aliases. Used everywhere a tenantId/userId/aggregateId
 // travels through the framework. One declaration per concept so future
 // representation changes (branded types, UUID validation, opaque wrappers)

package/src/engine/types/index.ts

@@ -102,7 +102,6 @@ export type {
   AppContext,
   AppendEventArgs,
   AppendEventFn,
-  AppendEventUnsafeFn,
   AuthClaimsContext,
   AuthClaimsFn,
   AuthClaimsHookDef,
@@ -133,6 +132,7 @@ export type {
   RateLimitOption,
   RateLimitPer,
   SessionUser,
+  UnsafeAppendEventFn,
   WriteEvent,
   WriteHandlerDef,
   WriteHandlerFn,
@@ -211,4 +211,15 @@ export type {
   ToolbarAction,
 } from "./screen";
 export { normalizeEditField, normalizeListColumn } from "./screen";
+export type { TargetRef } from "./target-ref";
+export type {
+  Subscribe,
+  TreeAction,
+  TreeActionDef,
+  TreeActionsHandle,
+  TreeChildrenSubscribe,
+  TreeContext,
+  TreeNode,
+  TreeNodeState,
+} from "./tree-node";
 export type { WorkspaceDefinition } from "./workspace";