@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/engine/types/step.ts

@@ -1,334 +1,2 @@
-// 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 { EventStoreExecutor } from "../../db/event-store-executor";
-import type { WhereObject } from "../../db/query";
-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: unknown;
-    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: unknown;
-    readonly where: StepResolver<WhereObject>;
-  }) => StepInstance;
-  // Read sub-namespace — thin wrapper on selectMany/fetchOne (bun-db).
-  // Caller-owned tenant-filter (does NOT auto-inject like ctx.queryProjection does).
-  readonly read: {
-    readonly findOne: (
-      name: string,
-      opts: {
-        readonly table: unknown;
-        readonly where: StepResolver<WhereObject | undefined>;
-      },
-    ) => StepInstance;
-    readonly findMany: (
-      name: string,
-      opts: {
-        readonly table: unknown;
-        readonly where?: StepResolver<WhereObject | 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;
+// Legacy path — re-exported for callers still importing this module directly.
+export type * from "@cosmicdrift/kumiko-types/step";

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

@@ -1,21 +1 @@
-// 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>>;
-};
+export type * from "@cosmicdrift/kumiko-types/target-ref";

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

@@ -1,132 +1 @@
-// 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 { 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.
-//
-// **V.1.4 emitError**: optional callback für async-error-Pfade (fetch-
-// fail, SSE-disconnect). Provider die explizit Errors signalisieren
-// wollen rufen `emitError(e)` statt empty-emit; VisualTree zeigt
-// Error-Banner mit Retry-Button. Sync-Throws im Provider-Body werden
-// vom useEffect-try/catch abgefangen — emitError ist nur für async.
-export type Subscribe<T> = (
-  emit: (value: T) => void,
-  emitError?: (error: Error) => void,
-) => () => void;
-
-// TreeChildrenSubscribe — Lazy-Variante für dynamic Children. Wird
-// erst aufgerufen wenn der Knoten im UI ausgeklappt wird. Kein ctx-
-// Argument: Provider sind session-bound; Backend liest tenantId aus
-// session bei jedem fetch/dispatch. V.1.1 hatte ein ctx mit tenantId,
-// das aber im Browser nie echten Tenant trug (war auf SYSTEM_TENANT_ID
-// gepinnt) und vom einzigen V.1.2-Consumer (text-content) ignoriert
-// wurde. SR2-Rip 2026-05-18: Dead-API entfernt; wenn später ein
-// Provider tenant-aware-rendern muss (z.B. cross-tenant-Dashboards
-// für SystemAdmin), wird ctx mit echtem Tenant-Source aus dem Auth-
-// Layer re-introduziert. YAGNI bis dahin.
-export type TreeChildrenSubscribe = () => Subscribe<readonly TreeNode[]>;
-
-// 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;
-};
+export type * from "@cosmicdrift/kumiko-types/tree-node";

package/src/engine/types/workspace.ts

@@ -1,49 +1,2 @@
-import type { AccessRule } from "./handlers";
-
-// Workspace declaration. A workspace is a persona-/role-scoped UI surface:
-// pure UI composition with no backend, DB or auth impact. The engine stores
-// these verbatim and the active web shell (shellWorkspaces) renders the
-// switcher and filters the nav tree by membership + access.
-//
-// Membership is computed from two sources, merged at boot:
-//   1. r.workspace({ nav: [...] }) — explicit list of nav QNs
-//   2. r.nav({ workspaces: [...] }) — nav entry self-assigns to workspaces
-// A nav entry that appears in neither source belongs to no workspace and
-// only shows up when no workspace is active (legacy / non-workspace apps).
-//
-// Cross-feature references are allowed: `nav` may point at any registered
-// nav QN. The boot validator checks references exist and that workspace
-// IDs referenced from r.nav are real.
-export type WorkspaceDefinition = {
-  // Feature author writes the short id ("disposition"); the registry
-  // overwrites `id` with the qualified name ("bmc:workspace:disposition")
-  // in its stored copy. Same pattern as NavDefinition / ScreenDefinition.
-  readonly id: string;
-  // i18n translation key. Resolved at render time by the renderer's
-  // useTranslation hook; engine keeps it opaque.
-  readonly label: string;
-  // Icon key — whatever the icon registry of the active renderer understands.
-  // Engine doesn't validate; unknown icons surface as a missing icon on
-  // screen, not a boot failure (mirrors NavDefinition.icon).
-  readonly icon?: string;
-  // Sort weight in the workspace switcher (lower = earlier). Ties broken
-  // by registration order — features registered later appear lower.
-  readonly order?: number;
-  // Role / openToAll gate. Only users matching this rule see the workspace
-  // in their switcher. Mirrors NavDefinition.access — same semantics across
-  // the UI surface, so a default-deny app can do `{ roles: [] }`.
-  readonly access?: AccessRule;
-  // Explicit nav QNs that belong to this workspace. Merged with any nav
-  // entries that self-assign via r.nav({ workspaces: [...] }).
-  readonly nav?: readonly string[];
-  // 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";
-};
+// Legacy path — re-exported for callers still importing this module directly.
+export type * from "@cosmicdrift/kumiko-types/workspace";

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

@@ -13,7 +13,7 @@
 // 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
+// to `stepsPipeline(...)`) 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 `{}`
@@ -23,6 +23,10 @@
 // caught by this validator. A future lint-rule will enforce the contract
 // statically; today it lives in this comment + the StepBuilder doc.
 
+import {
+  KUMIKO_META_SYMBOL,
+  KUMIKO_NAME_SYMBOL,
+} from "@cosmicdrift/kumiko-types/schema-table-types";
 import { getStep } from "./define-step";
 import { buildPipelineSteps } from "./pipeline";
 import type { FeatureDefinition, SessionUser, TenantId, WriteEvent } from "./types";
@@ -55,13 +59,9 @@ function* walkAllSteps(steps: readonly StepInstance[]): Generator<StepInstance,
   }
 }
 
-// @cast-boundary drizzle-bridge — reads table name from a Symbol without
-// importing drizzle-orm (bun-db pattern, see bun-db/query.ts).
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
 // table()/buildEntityTable spread column handles as enumerable props, so an
 // entity field named `tableName`/`source` would shadow the matching meta key —
-// the canonical meta under this symbol is the only collision-safe source.
-const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
+// the canonical meta under KUMIKO_META_SYMBOL is the only collision-safe source.
 
 function resolveTableNameFromStep(table: unknown): string {
   if (typeof table === "object" && table !== null) {