@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

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
@@ -164,6 +173,21 @@ export type FeatureDefinition = {
   readonly jobs: Readonly<Record<string, JobDefinition>>;
   readonly registrarExtensions: Readonly<Record<string, RegistrarExtensionDef>>;
   readonly extensionUsages: readonly RegistrarExtensionRegistration[];
+  /**
+   * Cross-feature API names this feature exposes via `r.exposesApi(name)`.
+   * Pure Marker-Deklaration — die echte Implementation wird als
+   * Query-/Write-Handler unter dem QN-Pattern registriert (z.B.
+   * `compliance-profiles:query:effective-profile`). Boot-Validator prüft
+   * dass jedes `r.usesApi(name)` einen passenden Exposer hier findet —
+   * Tippfehler oder Drop-Refactorings werden zu Boot-Fail statt Runtime-Crash.
+   */
+  readonly exposedApis: ReadonlySet<string>;
+  /**
+   * Cross-feature API names this feature calls. Pflicht-Boot-Check:
+   * jeder Eintrag muss in `exposedApis` irgendeines Features auftauchen
+   * UND das Provider-Feature muss in requires/optionalRequires sein.
+   */
+  readonly usedApis: ReadonlySet<string>;
   readonly referenceData: readonly ReferenceDataDef[];
   readonly notifications: Readonly<Record<string, NotificationDefinition>>;
   readonly events: Readonly<Record<string, EventDef>>;
@@ -209,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
@@ -235,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
@@ -360,6 +412,42 @@ export type FeatureRegistrar<TFeature extends string = string> = {
 
   useExtension(extensionName: string, entity: NameOrRef, options?: Record<string, unknown>): void;
 
+  /**
+   * Marker-Deklaration: dieses Feature stellt eine Cross-Feature-API
+   * unter dem genannten Namen bereit. Die eigentliche Implementation
+   * wird separat als Query- oder Write-Handler unter dem QN-Pattern
+   * registriert; `r.exposesApi` ist reine Boot-Check-Surface.
+   *
+   * Boot-Validator prüft, dass jedes `r.usesApi(name)` einen passenden
+   * Exposer findet, dass das Exposer-Feature in requires/optionalRequires
+   * gelisted ist und dass kein API-Name doppelt exposed wird.
+   *
+   * ```ts
+   * defineFeature("compliance-profiles", (r) => {
+   *   r.exposesApi("compliance.forTenant");
+   *   r.queryHandler({
+   *     name: "compliance:query:for-tenant",
+   *     // ... echte Implementation
+   *   });
+   * });
+   * ```
+   */
+  exposesApi(apiName: string): void;
+
+  /**
+   * Declares that this feature calls a cross-feature API. Boot-Validator
+   * checkt dass irgendein anderes Feature `r.exposesApi(apiName)` macht
+   * und dass dieses Feature `r.requires/optionalRequires` darauf hat.
+   *
+   * ```ts
+   * defineFeature("user-data-rights", (r) => {
+   *   r.requires("compliance-profiles");
+   *   r.usesApi("compliance.forTenant");
+   * });
+   * ```
+   */
+  usesApi(apiName: string): void;
+
   // Declare a metric. Short name (without kumiko_<feature>_ prefix) — Framework
   // qualifies it on boot. Validation (snake_case + typ-suffix) runs at boot.
   // Usage at runtime: ctx.metrics.inc("created_total", { status: "new" }).
@@ -455,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) ---
@@ -626,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/fields.ts

@@ -5,6 +5,7 @@
 // accepted at the type layer during migration: features that pass an
 // array are auto-normalized to { [role]: "all" } at registry build.
 // Long-term: string[] disappears.
+import type { SQL } from "drizzle-orm";
 import type { OwnershipMap } from "../ownership";
 
 export type FieldAccess = {
@@ -20,6 +21,76 @@ export type FieldAccess = {
 // custom projections cannot read sensitive field values. See
 // docs/plans/architecture/projections.md.
 
+// --- PII / Subject-Key Annotations (DSGVO Art. 17 — Crypto-Shredding) ---
+//
+// Felder die PII enthalten werden in Sprint 3 (crypto-shredding) mit einem
+// Subject-Schluessel encrypted gespeichert. Subject = die natuerliche Person
+// oder der Tenant der die Daten "besitzt". Loeschung erfolgt durch Vernichten
+// des Subject-Keys ("Crypto-Shredding") — der Datensatz bleibt physisch
+// (Audit-Trail bewahrt), ist aber nicht mehr entschluesselbar. Sprint 0
+// fuegt nur die Schema-Marker + Boot-Validation ein; Encrypt/Decrypt-Mechanik
+// kommt in Sprint 3.
+//
+// Drei orthogonale Markierungen:
+//   - `pii: true`              — Subject = die Entity selbst.
+//                                Beispiel: user.email gehoert User Marc.
+//   - `userOwned: { ownerField }` — Subject = der User der im genannten
+//                                Field referenziert ist.
+//                                Beispiel: comment.body gehoert
+//                                comment.authorId.
+//   - `tenantOwned: true`      — Subject = der aktuelle Tenant
+//                                (ctx.tenantId zur Schreibzeit).
+//                                Beispiel: tenantBranding.brandColor.
+//
+// `anonymize` ist die Pro-Feld-Funktion die der retention-Cleanup-Job
+// (Sprint 2) aufruft wenn die Entity-Strategy "anonymize" lautet oder die
+// `blockDelete`-Frist abgelaufen ist. Beispiel: `() => "[ANONYMIZED]"` oder
+// `() => null`.
+//
+// `allowPlaintext` unterdrueckt PII-Heuristik-Boot-Warnings fuer Felder die
+// zwar PII-Naming haben (email, name, body) aber bewusst Klartext bleiben
+// sollen — z.B. ticket.title als Geschaeftsdaten. Wert ist eine Begruendung
+// wie "is-business-data".
+//
+// `anonymize` darf sync oder async sein — der Cleanup-Job (Sprint 2)
+// awaited den Return. Async-Funktionen sind sinnvoll wenn die Anonymisierung
+// einen Lookup braucht (z.B. konsistente Pseudonyme aus separater Tabelle).
+//
+// Siehe docs/plans/datenschutz/crypto-shredding.md und docs/plans/datenschutz/roadmap.md.
+export type PiiAnnotations = {
+  readonly pii?: boolean;
+  readonly userOwned?: { readonly ownerField: string };
+  readonly tenantOwned?: boolean;
+  readonly anonymize?: () => unknown | Promise<unknown>;
+  readonly allowPlaintext?: string;
+};
+
+// --- Retention (DSGVO Art. 5(1)(e) + HGB/AO Aufbewahrungspflichten) ---
+//
+// Pro Entity definiert der Author eine Default-Retention-Policy. Tenant-
+// Admin uebersteuert sie via Compliance-Profile + Tenant-Override (Sprint 2).
+// Vier Strategien:
+//
+//   - "hardDelete"  — Row physisch weg nach `keepFor`. Logs, Sessions.
+//   - "softDelete"  — `deletedAt = now()`. Erlaubt spaetere Restore.
+//   - "anonymize"   — Felder mit `anonymize`-Funktion ueberschrieben,
+//                     Row bleibt. Order/Invoice mit gemischter PII +
+//                     Geschaeftsdaten.
+//   - "blockDelete" — Cleanup-Job ignoriert; User-Forget loest stattdessen
+//                     `anonymize` aus. Buchhaltung, Mandate, Patientenakten.
+//
+// `keepFor` ist eine Duration-String wie "30d", "10y", "6m". Parser
+// kommt im Cleanup-Job (Sprint 2). `reference` ist das Field das den
+// Lebenszeit-Anker liefert (Default: `createdAt`). Sessions z.B. nutzen
+// `lastSeenAt` damit aktive Sessions nicht weggemueht werden.
+//
+// Siehe docs/plans/features/core-data-retention.md und Sprint 2 in roadmap.md.
+export type RetentionDef = {
+  readonly keepFor: string;
+  readonly strategy: "hardDelete" | "softDelete" | "anonymize" | "blockDelete";
+  readonly reference?: string;
+};
+
 export type TextFieldDef = {
   readonly type: "text";
   readonly maxLength?: number;
@@ -40,7 +111,7 @@ export type TextFieldDef = {
    *  explizite Höhe. Search/sort/encrypt verhalten sich unverändert
    *  identisch zu single-line — nur die Render-Surface wechselt. */
   readonly multiline?: boolean | { readonly rows?: number };
-};
+} & PiiAnnotations;
 
 /**
  * Long-form text content — source-code, markdown, blog-posts, email-
@@ -74,7 +145,7 @@ export type LongTextFieldDef = {
   readonly default?: string;
   readonly access?: FieldAccess;
   readonly multiline?: boolean | { readonly rows?: number };
-};
+} & PiiAnnotations;
 
 export type BooleanFieldDef = {
   readonly type: "boolean";
@@ -95,7 +166,7 @@ export type SelectFieldDef<TOptions extends readonly string[] = readonly string[
   readonly sensitive?: boolean;
   readonly default?: TOptions[number];
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 // Mehrere Werte aus einer festen Options-Liste — UI rendert als
 // Checkbox-/Multi-Select-Kontrolle. Storage: jsonb-Array<string>;
@@ -119,7 +190,7 @@ export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly st
   /** Default-Auswahl. Jeder Eintrag muss in `options` sein (Boot-Validator). */
   readonly default?: readonly TOptions[number][];
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 export type NumberFieldDef = {
   readonly type: "number";
@@ -129,7 +200,29 @@ export type NumberFieldDef = {
   readonly sensitive?: boolean;
   readonly default?: number;
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
+
+/**
+ * 64-bit-Integer-Spalte fuer Audit-Counter, Byte-Sizes, Event-IDs und
+ * andere Werte die >2^31 (~2.1 Mrd) wandern koennen. Storage als
+ * Postgres `bigint`, JS-Round-trip als `number` (mode:"number" — sicher
+ * bis 2^53 ≈ 9 PB, JSON-serialisierbar). Wer >2^53 braucht (rare),
+ * nutzt einen `text`-Field mit eigenem Codec.
+ *
+ * Vorrang vor `NumberFieldDef`-(integer 32-bit-Cap, ~2.1 GB) immer dann
+ * wenn der Wert physisch ueber dieses Limit klettern kann: Bytes,
+ * Events, Counters in High-Throughput-Apps, Cumulative-Sums. Money
+ * hat dafuer den eigenen `MoneyFieldDef` (mit Currency-Spalte).
+ */
+export type BigIntFieldDef = {
+  readonly type: "bigInt";
+  readonly required?: boolean;
+  readonly sortable?: boolean;
+  readonly filterable?: boolean;
+  readonly sensitive?: boolean;
+  readonly default?: number;
+  readonly access?: FieldAccess;
+} & PiiAnnotations;
 
 export type MoneyFieldDef = {
   readonly type: "money";
@@ -207,7 +300,7 @@ export type EmbeddedFieldDef = {
   readonly sensitive?: boolean;
   readonly schema: Readonly<Record<string, EmbeddedSubFieldDef>>;
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 // Legacy "date" — JS-Date-Object, semantisch unklar (Wall-Clock vs Instant).
 // Für neue Felder bevorzuge:
@@ -223,7 +316,7 @@ export type DateFieldDef = {
   readonly filterable?: boolean;
   readonly sensitive?: boolean;
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 // UTC-Instant (Temporal.Instant). Für Ereignisse die zu einem bestimmten
 // Augenblick passieren, ohne Location-Bezug: createdAt, loginAt, actualPickupAt.
@@ -251,7 +344,7 @@ export type TimestampFieldDef = {
    *   { pickupAt: { type: "timestamp", locatedBy: "pickupTz" }, pickupTz: { type: "tz" } }
    */
   readonly locatedBy?: string;
-};
+} & PiiAnnotations;
 
 // IANA-Zonenname (z.B. "Europe/Berlin", "America/Los_Angeles").
 // Wird via `Intl.supportedValuesOf("timeZone")` validiert (kommt im
@@ -262,7 +355,7 @@ export type TzFieldDef = {
   readonly required?: boolean;
   readonly sensitive?: boolean;
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 // Wall-Clock-Termin an einem Ort als ATOMARES Konzept.
 // EIN Feld in der Schema-Definition, ZWEI Spalten in der DB
@@ -289,7 +382,7 @@ export type LocatedTimestampFieldDef = {
   readonly filterable?: boolean;
   readonly sensitive?: boolean;
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 export type FileFieldDef = {
   readonly type: "file";
@@ -332,6 +425,7 @@ export type FieldDefinition =
   | SelectFieldDef
   | MultiSelectFieldDef
   | NumberFieldDef
+  | BigIntFieldDef
   | MoneyFieldDef
   | ReferenceFieldDef
   | EmbeddedFieldDef
@@ -380,6 +474,20 @@ export type EntityIndexDef = {
   readonly columns: readonly [string, ...string[]];
   readonly unique?: boolean;
   readonly name?: string;
+  /**
+   * Optional SQL-Fragment fuer Partial-Index — `CREATE [UNIQUE] INDEX
+   * ... WHERE <condition>`. Postgres-Pattern fuer "Index nur unter
+   * bestimmten Bedingungen", typisches Beispiel: ExportJob-Idempotency
+   * `UNIQUE(userId) WHERE status IN ('pending', 'running')`.
+   *
+   * Caller baut das Fragment via drizzle-orm `sql\`...\``-Tagged-
+   * Template. table-builder.ts emittiert `.where(def.where)` auf den
+   * Drizzle-IndexBuilder — wirkt sowohl fuer unique- als auch fuer
+   * non-unique-Indexes (PG erlaubt beides; non-unique partial nutzt
+   * man z.B. fuer scharfe BTREE-Indexes nur auf einer Status-Teilmenge
+   * statt voller Tabelle).
+   */
+  readonly where?: SQL;
 };
 
 export type FieldsMap = Readonly<Record<string, FieldDefinition>>;
@@ -419,4 +527,20 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap> = {
     readonly read?: OwnershipMap;
     readonly write?: OwnershipMap;
   };
+  /**
+   * Default-Retention-Policy fuer diese Entity. Tenant-Admin kann via
+   * Compliance-Profile + Tenant-Override (Sprint 2) uebersteuern.
+   * Cleanup-Job (Sprint 2) verarbeitet die Strategy:
+   *
+   *   - "hardDelete" → Row physisch weg nach keepFor
+   *   - "softDelete" → deletedAt = now() (mit core-soft-delete-Feature)
+   *   - "anonymize"  → Felder mit `anonymize`-Funktion ueberschrieben,
+   *                    Row bleibt
+   *   - "blockDelete" → Cleanup-Job ignoriert; User-Forget loest
+   *                     stattdessen anonymize aus. Buchhaltung, Mandate,
+   *                     Patientenakten.
+   *
+   * Siehe docs/plans/features/core-data-retention.md.
+   */
+  readonly retention?: RetentionDef;
 };

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

@@ -66,6 +66,7 @@ export type {
 } from "./feature";
 export type {
   AnyFileFieldDef,
+  BigIntFieldDef,
   BooleanFieldDef,
   DateFieldDef,
   DefaultCurrency,
@@ -85,7 +86,9 @@ export type {
   MoneyFieldDef,
   MultiSelectFieldDef,
   NumberFieldDef,
+  PiiAnnotations,
   ReferenceFieldDef,
+  RetentionDef,
   SelectFieldDef,
   TextFieldDef,
   TimestampFieldDef,
@@ -99,7 +102,6 @@ export type {
   AppContext,
   AppendEventArgs,
   AppendEventFn,
-  AppendEventUnsafeFn,
   AuthClaimsContext,
   AuthClaimsFn,
   AuthClaimsHookDef,
@@ -130,6 +132,7 @@ export type {
   RateLimitOption,
   RateLimitPer,
   SessionUser,
+  UnsafeAppendEventFn,
   WriteEvent,
   WriteHandlerDef,
   WriteHandlerFn,
@@ -208,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";