@cosmicdrift/kumiko-framework 0.155.1 → 0.156.1

package/src/engine/feature-ui-extensions.ts

@@ -19,7 +19,6 @@ import type {
   SearchPayloadContributorFn,
   TreeActionDef,
   TreeActionsHandle,
-  UnmanagedTableOptions,
   ValidationHookFn,
 } from "./types";
 import { HookPhases } from "./types";
@@ -417,39 +416,7 @@ export function buildUiExtensionsMethods<TName extends string>(
       }
       state.httpRoutes[key] = definition;
     },
-    rawTable(rawTableName: string, table: unknown, options: RawTableOptions): void {
-      // Same kebab guard as r.projection / r.screen / r.nav so authoring-time
-      // mistakes surface at the feature file, not deep in registry boot.
-      if (!isKebabSegment(rawTableName)) {
-        throw new Error(
-          `[Feature ${name}] Raw-table name "${rawTableName}" must be kebab-case ` +
-            `(lowercase letters, digits, dashes; start with a letter). ` +
-            `Got "${rawTableName}" — try "${toKebab(rawTableName).replace(/_/g, "-")}".`,
-        );
-      }
-      if (state.rawTables[rawTableName]) {
-        throw new Error(
-          `[Feature ${name}] r.rawTable("${rawTableName}") already registered. ` +
-            `Raw-table names must be unique per feature.`,
-        );
-      }
-      // The `reason` is the marker that justifies the bypass — empty
-      // strings would defeat the audit trail. Reject early so the
-      // failure points at the feature file.
-      if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
-        throw new Error(
-          `[Feature ${name}] r.rawTable("${rawTableName}"): options.reason must be a ` +
-            `non-empty string. The reason is the marker that justifies the bypass — ` +
-            `if you can't write one, declare data via r.entity() instead.`,
-        );
-      }
-      state.rawTables[rawTableName] = {
-        name: rawTableName,
-        table,
-        reason: options.reason,
-      };
-    },
-    unmanagedTable(meta: EntityTableMeta, options: UnmanagedTableOptions): void {
+    rawTable(meta: EntityTableMeta, options: RawTableOptions): void {
       // Name comes from the meta itself — apps already give the table a
       // name when calling defineUnmanagedTable, no need to repeat it.
       const tableName = meta.tableName;
@@ -457,24 +424,27 @@ export function buildUiExtensionsMethods<TName extends string>(
         // EntityTableMeta uses snake_case for tableName (matches Postgres
         // convention); we just guard against truly broken input.
         throw new Error(
-          `[Feature ${name}] Unmanaged-table name "${tableName}" must be a ` +
+          `[Feature ${name}] Raw-table name "${tableName}" must be a ` +
             `valid identifier (lowercase letters, digits, underscores; start with a letter).`,
         );
       }
-      if (state.unmanagedTables[tableName]) {
+      if (state.rawTables[tableName]) {
         throw new Error(
-          `[Feature ${name}] r.unmanagedTable("${tableName}") already registered. ` +
-            `Unmanaged-table names must be unique per feature.`,
+          `[Feature ${name}] r.rawTable("${tableName}") already registered. ` +
+            `Raw-table names must be unique per feature.`,
         );
       }
+      // The `reason` is the marker that justifies the bypass — empty
+      // strings would defeat the audit trail. Reject early so the
+      // failure points at the feature file.
       if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
         throw new Error(
-          `[Feature ${name}] r.unmanagedTable("${tableName}"): options.reason must be a ` +
+          `[Feature ${name}] r.rawTable("${tableName}"): options.reason must be a ` +
             `non-empty string. The reason justifies the audit-trail bypass — ` +
             `if you can't write one, declare data via r.entity() instead.`,
         );
       }
-      state.unmanagedTables[tableName] = {
+      state.rawTables[tableName] = {
         name: tableName,
         meta,
         reason: options.reason,

package/src/engine/field-access.ts

@@ -2,6 +2,13 @@ import type { DbRow } from "../db/connection";
 import { normalizeAccessEntry, userCanReadFieldRow, userCanWriteFieldRow } from "./ownership";
 import type { EntityDefinition, SessionUser } from "./types";
 
+// piiEncrypted fields deliberately break that silence (kumiko-platform#463):
+// the field's whole point is "a legitimate reader may see the plaintext",
+// so an unauthorized reader seeing the field exist-but-masked is the
+// intended signal, not a leak — unlike a secret whose existence itself
+// should stay hidden.
+export const PII_MASKED_VALUE = "••••••";
+
 // Field-level read filtering. Returns a copy of `data` with fields stripped
 // if the user's roles don't grant read access OR the ownership-rule for the
 // matching role doesn't accept this concrete row. Fields without access
@@ -11,7 +18,8 @@ import type { EntityDefinition, SessionUser } from "./types";
 // one place in the ownership system where silence is the right default:
 // reporting "you tried to read X but can't" leaks the field's existence.
 // Writes do the opposite (loud error) because a silent drop there masks
-// save-bugs.
+// save-bugs. piiEncrypted fields are the one exception — see
+// PII_MASKED_VALUE above.
 export function filterReadFields(
   entity: EntityDefinition,
   data: Readonly<Record<string, unknown>>,
@@ -29,7 +37,10 @@ export function filterReadFields(
 
     const accessMap = normalizeAccessEntry(field.access?.read);
     if (!userCanReadFieldRow(user, accessMap, data)) {
-      continue; // entire field stripped
+      if ("piiEncrypted" in field && field.piiEncrypted === true) {
+        result[key] = PII_MASKED_VALUE;
+      }
+      continue; // entire field stripped (masked instead, for piiEncrypted)
     }
 
     // For embedded fields: filter sub-fields with access restrictions

package/src/engine/object-form.ts

@@ -10,3 +10,18 @@ export function splitNamedDefinition<T extends { readonly name: string }>(
   const { name, ...rest } = definition;
   return [name, rest];
 }
+
+// Shared helper for registrar methods that accept either variadic strings
+// (hand-written call sites) or a single Object-Form object wrapping the
+// same string array under `key` (the feature-ast renderer's canonical
+// shape for Designer/AI-generated code).
+export function unwrapArrayForm<K extends string>(
+  args: readonly [Record<K, readonly string[]>] | readonly string[],
+  key: K,
+): readonly string[] {
+  const [first] = args;
+  if (typeof first === "object" && first !== null && key in first) {
+    return (first as Record<K, readonly string[]>)[key];
+  }
+  return args as readonly string[];
+}

package/src/engine/registry-facade.ts

@@ -68,6 +68,10 @@ export function buildRegistryFacade(state: RegistryState): Registry {
       return state.queryHandlerMap.get(name);
     },
 
+    getAllQueryHandlers(): ReadonlyMap<string, QueryHandlerDef> {
+      return state.queryHandlerMap;
+    },
+
     getSearchableFields(entityName: string): readonly string[] {
       return state.searchableFieldsCache.get(entityName) ?? [];
     },

package/src/engine/registry-ingest.ts

@@ -20,10 +20,10 @@ export function populateFeatureCore(state: RegistryState, feature: FeatureDefini
     state.entityMap.set(name, entity);
     const physical = resolveTableName(name, entity, feature.name);
     const clash = state.physicalTableOwners.get(physical);
-    if (clash?.kind === "unmanaged") {
+    if (clash?.kind === "raw") {
       throw new Error(
         `Entity "${name}" (feature "${feature.name}") has physical table "${physical}" which ` +
-          `collides with r.unmanagedTable("${physical}") (feature "${clash.featureName}"). ` +
+          `collides with r.rawTable("${physical}") (feature "${clash.featureName}"). ` +
           `Pick a different tableName — both would emit CREATE TABLE "${physical}".`,
       );
     }
@@ -145,12 +145,14 @@ export function populateEvents(state: RegistryState, feature: FeatureDefinition)
   }
 }
 
-// Translations prefixed with featureName: (i18next namespace convention).
 export function populateTranslations(state: RegistryState, feature: FeatureDefinition): void {
   // Translations prefixed with featureName: (i18next namespace convention).
   // Keys that already carry the feature's own namespace prefix (e.g. a nav
   // label referencing "cap-counter:nav.cap-list" verbatim) must NOT be
-  // re-prefixed, else server-side t() can never resolve them (#1105).
+  // re-prefixed, else server-side t() can never resolve them (#1105). Both
+  // bare and qualified spellings for the same key are accepted; if a
+  // feature defines both, whichever is declared last wins (Object.entries
+  // = insertion order, not "qualified always wins").
   const prefix = `${feature.name}:`;
   for (const [key, value] of Object.entries(feature.translations ?? {})) {
     const qualifiedKey = key.startsWith(prefix) ? key : `${prefix}${key}`;
@@ -302,7 +304,9 @@ export function populateProjectionsAndTables(
   // these bypass the qualified-name namespace because they have no
   // event-stream binding to disambiguate). Reject cross-feature
   // duplicates at boot so the dev-server doesn't race two CREATE TABLE
-  // statements that target the same physical table name.
+  // statements that target the same physical table name. Two features
+  // registering the same physical tableName would also race two CREATE
+  // TABLE statements via migrate-runner.
   for (const [rawName, rawDef] of Object.entries(feature.rawTables ?? {})) {
     const existing = state.rawTableMap.get(rawName);
     if (existing) {
@@ -311,43 +315,29 @@ export function populateProjectionsAndTables(
           `"${feature.name}". Pick a feature-prefixed name to disambiguate.`,
       );
     }
-    state.rawTableMap.set(rawName, { ...rawDef, featureName: feature.name });
-  }
-
-  // Unmanaged tables — same cross-feature uniqueness invariant as rawTables.
-  // Two features registering the same physical tableName would race two
-  // CREATE TABLE statements via migrate-runner.
-  for (const [umName, umDef] of Object.entries(feature.unmanagedTables ?? {})) {
-    const existing = state.unmanagedTableMap.get(umName);
-    if (existing) {
-      throw new Error(
-        `Unmanaged-table "${umName}" registered by both feature "${existing.featureName}" and ` +
-          `"${feature.name}". Pick a feature-prefixed tableName to disambiguate.`,
-      );
-    }
-    const physicalClash = state.physicalTableOwners.get(umName);
+    const physicalClash = state.physicalTableOwners.get(rawName);
     if (physicalClash?.kind === "entity") {
       throw new Error(
-        `Unmanaged-table "${umName}" (feature "${feature.name}") collides with the physical ` +
+        `Raw-table "${rawName}" (feature "${feature.name}") collides with the physical ` +
           `table of entity "${physicalClash.owner}" (feature "${physicalClash.featureName}"). ` +
-          `Pick a different tableName — both would emit CREATE TABLE "${umName}".`,
+          `Pick a different tableName — both would emit CREATE TABLE "${rawName}".`,
       );
     }
-    const piiFields = umDef.meta.piiSubjectFields ?? [];
-    if (piiFields.length > 0 && !umDef.piiEncryptedOnWrite) {
+    const piiFields = rawDef.meta.piiSubjectFields ?? [];
+    if (piiFields.length > 0 && !rawDef.piiEncryptedOnWrite) {
       throw new Error(
-        `Unmanaged-table "${umName}" (feature "${feature.name}") has PII-annotated fields ` +
+        `Raw-table "${rawName}" (feature "${feature.name}") has PII-annotated fields ` +
           `(${piiFields.join(", ")}) but direct writes bypass the executor's PII encryption. ` +
           `Encrypt those fields before every insert/update (encryptPiiFieldValues) and declare ` +
           `{ piiEncryptedOnWrite: true }, or drop the subject annotations.`,
       );
     }
-    state.physicalTableOwners.set(umName, {
-      kind: "unmanaged",
-      owner: umName,
+    state.physicalTableOwners.set(rawName, {
+      kind: "raw",
+      owner: rawName,
       featureName: feature.name,
     });
-    state.unmanagedTableMap.set(umName, { ...umDef, featureName: feature.name });
+    state.rawTableMap.set(rawName, { ...rawDef, featureName: feature.name });
   }
 }
 

package/src/engine/registry-state.ts

@@ -38,7 +38,6 @@ import type {
   SearchPayloadContributorFn,
   SecretKeyDefinition,
   TreeActionDef,
-  UnmanagedTableDef,
   WorkspaceDefinition,
   WriteHandlerDef,
 } from "./types";
@@ -201,11 +200,7 @@ export type RegistryState = {
   multiStreamProjectionMap: Map<string, MultiStreamProjectionDefinition>;
   multiStreamProjectionFeatureMap: Map<string, string>;
   rawTableMap: Map<string, RawTableDef>;
-  unmanagedTableMap: Map<string, UnmanagedTableDef>;
-  physicalTableOwners: Map<
-    string,
-    { kind: "entity" | "unmanaged"; owner: string; featureName: string }
-  >;
+  physicalTableOwners: Map<string, { kind: "entity" | "raw"; owner: string; featureName: string }>;
   authClaimsHooks: AuthClaimsHookDef[];
   claimKeyMap: Map<string, ClaimKeyDefinition>;
   screenMap: Map<string, ScreenDefinition>;
@@ -266,7 +261,6 @@ export function createInitialState(): RegistryState {
     multiStreamProjectionMap: new Map(),
     multiStreamProjectionFeatureMap: new Map(),
     rawTableMap: new Map(),
-    unmanagedTableMap: new Map(),
     physicalTableOwners: new Map(),
     authClaimsHooks: [],
     claimKeyMap: new Map(),

package/src/engine/registry-validate.ts

@@ -223,27 +223,6 @@ export function buildImplicitProjections(
   }
 }
 
-export function validateNoRawTableProjectionClash(state: RegistryState): void {
-  // Cross-cut: a r.rawTable() PgTable must not coincide with any
-  // registered projection's table. Silent dedupe via Set would mask a
-  // real authoring bug (two owners writing to the same physical table).
-  // Run after both passes so implicit projections are visible too.
-  const projectionTables = new Set<unknown>();
-  for (const proj of state.projectionMap.values()) projectionTables.add(proj.table);
-  for (const msp of state.multiStreamProjectionMap.values()) {
-    if (msp.table) projectionTables.add(msp.table);
-  }
-  for (const raw of state.rawTableMap.values()) {
-    if (projectionTables.has(raw.table)) {
-      throw new Error(
-        `r.rawTable "${raw.name}" (feature "${raw.featureName}") shares a Drizzle ` +
-          `PgTable with a registered projection. Pick one owner: r.entity() / ` +
-          `r.projection() for event-sourced reads, r.rawTable() for the bypass.`,
-      );
-    }
-  }
-}
-
 export function buildSearchIncludesAndIncomingRelations(state: RegistryState): void {
   for (const [entityName, rels] of state.relationMap) {
     const includes = new Map<string, readonly string[]>();
@@ -320,13 +299,11 @@ export function validateEventMigrationVersions(
   for (const feature of features) {
     for (const [shortName, migrations] of Object.entries(feature.eventMigrations ?? {})) {
       const qualified = qualify(feature.name, "event", shortName);
-      const eventDef = state.eventMap.get(qualified);
-      if (!eventDef) {
-        throw new Error(
-          `Feature "${feature.name}" has migrations declared for event "${shortName}" ` +
-            `but no r.defineEvent exists for that name. Register the event first.`,
-        );
-      }
+      // registerEventMigration only ever runs alongside state.events[name]=def
+      // in the same defineEvent call (feature-config-events-jobs.ts:260-269),
+      // so a migrations entry here guarantees a matching eventMap entry.
+      // biome-ignore lint/style/noNonNullAssertion: invariant proven above
+      const eventDef = state.eventMap.get(qualified)!;
       for (const m of migrations) {
         if (m.toVersion > eventDef.version) {
           throw new Error(

package/src/engine/registry.ts

@@ -34,7 +34,6 @@ import {
   validateFieldAccessHandlersAreEntityMapped,
   validateJobTriggers,
   validateLifecycleHookTargets,
-  validateNoRawTableProjectionClash,
   validateProjectionApplyKeys,
   validateRelationTargetsExist,
   validateRequiredFeatures,
@@ -68,7 +67,6 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   applyExtensionUsages(state);
   buildSearchableSortableCaches(state);
   buildImplicitProjections(state, features);
-  validateNoRawTableProjectionClash(state);
   buildSearchIncludesAndIncomingRelations(state);
   validateFieldAccessHandlersAreEntityMapped(state, features);
   validateExtensionPreSaveWiring(features);

package/src/engine/types/config.ts

@@ -89,6 +89,13 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
   readonly scope: ConfigScope;
   readonly access: ConfigKeyAccess;
   readonly encrypted?: boolean;
+  /** User/admin may legitimately see the value — unlike `encrypted`
+   *  (shared master-key cipher), this is the subject-KMS: the value is
+   *  encrypted under the DEK of the scope actually written to (tenant-row
+   *  → tenant subject, user-row → user subject). Only on `type: "text"`,
+   *  `scope !== "system"` (no subject there), and mutually exclusive with
+   *  `encrypted` (kumiko-platform#231/#459). */
+  readonly piiEncrypted?: boolean;
   readonly options?: readonly string[];
   readonly bounds?: ConfigBounds;
   // Per-key string-pattern validation for type="text". The value must match

package/src/engine/types/feature.ts

@@ -1,12 +1,7 @@
 import type { ZodType, z } from "zod";
 import type { EntityTableMeta } from "../../db/entity-table-meta";
-
-// PgTable historically came from drizzle-orm/pg-core; the native dialect
-// no longer carries drizzle internal class types. Every caller really
-// needs "an opaque table-object with Symbol-based introspection".
-type PgTable = unknown;
-
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "../define-handler";
+import type { RegisterEntityCrudOptions } from "../entity-handlers";
 import type {
   ConfigKeyDefinition,
   ConfigKeyHandle,
@@ -131,6 +126,11 @@ export type SecretKeyHandle = {
 };
 
 // --- Raw tables (declared by features via r.rawTable()) ---
+// Post-drizzle-cut: unified with the former r.unmanagedTable() — both
+// carried the same reason/audit contract, differing only in whether the
+// table value was a legacy Drizzle PgTable (rawTable) or the framework-
+// native EntityTableMeta (unmanagedTable, consumed by migrate-runner).
+// EntityTableMeta was the forward-compatible shape, so rawTable adopted it.
 
 /** Options accepted by `r.rawTable()`. The `reason` is required so the
  *  bypass leaves an audit trail at the registration site — reviewers can
@@ -142,15 +142,23 @@ export type RawTableOptions = {
    *  payload cache, write-only by webhook handler", "denormalised
    *  projection of a non-Kumiko data source". */
   readonly reason: string;
+  /** Direct-write stores skip the executor, so the executor's PII
+   *  encryption never runs for them — a feature whose meta carries
+   *  piiSubjectFields must encrypt those fields itself before every
+   *  insert/update and declare that here, or boot fails (#820). */
+  readonly piiEncryptedOnWrite?: true;
 };
 
-/** Per-feature raw-table registration. Carries the bypass-justification
- *  reason but knows nothing about the owning feature — that's added when
- *  the registry aggregates entries cross-feature into `RawTableDef`. */
+/** Per-feature raw-table registration. `meta` is the `EntityTableMeta`
+ *  (framework-native shape used by `migrate-runner`). Carries the
+ *  bypass-justification reason but knows nothing about the owning
+ *  feature — that's added when the registry aggregates entries
+ *  cross-feature into `RawTableDef`. */
 export type RawTableEntry = {
   readonly name: string;
-  readonly table: PgTable;
+  readonly meta: EntityTableMeta;
   readonly reason: string;
+  readonly piiEncryptedOnWrite?: true;
 };
 
 /** Registry-aggregated raw-table — the per-feature `RawTableEntry` plus
@@ -160,32 +168,6 @@ export type RawTableDef = RawTableEntry & {
   readonly featureName: string;
 };
 
-// --- Unmanaged tables (declared by features via r.unmanagedTable()) ---
-
-/** Per-feature unmanaged-table registration. `meta` is the
- *  `EntityTableMeta` (framework-native shape used by `migrate-runner`).
- *  The `reason` justifies the bypass at the registration site — same
- *  contract as `r.rawTable`. */
-export type UnmanagedTableEntry = {
-  readonly name: string;
-  readonly meta: EntityTableMeta;
-  readonly reason: string;
-  readonly piiEncryptedOnWrite?: true;
-};
-
-/** Options for r.unmanagedTable(). Direct-write stores skip the executor,
- *  so the executor's PII encryption never runs for them — a feature whose
- *  meta carries piiSubjectFields must encrypt those fields itself before
- *  every insert/update and declare that here, or boot fails (#820). */
-export type UnmanagedTableOptions = RawTableOptions & {
-  readonly piiEncryptedOnWrite?: true;
-};
-
-/** Registry-aggregated unmanaged-table — adds the owning feature name. */
-export type UnmanagedTableDef = UnmanagedTableEntry & {
-  readonly featureName: string;
-};
-
 // --- UI-Hints (manifest-only, picker/scaffolder metadata) ---
 
 // Optional, declarative UI metadata declared via `r.uiHints({...})`. Surfaces
@@ -360,15 +342,12 @@ export type FeatureDefinition = {
   // writeHandlers — Routes leben mit dem Feature, nicht im Bootstrap.
   readonly httpRoutes: Readonly<Record<string, HttpRouteDefinition>>;
   // Raw tables declared via r.rawTable() — bypass the event-sourcing
-  // system. Keyed by feature-local short name. The registry attaches
-  // featureName on aggregation, lifting RawTableEntry → RawTableDef.
+  // system. Keyed by feature-local short name (derived from
+  // meta.tableName). The registry attaches featureName on aggregation,
+  // lifting RawTableEntry → RawTableDef. `kumiko schema generate`
+  // aggregates these alongside r.entity()-derived metas to build the
+  // full schema.
   readonly rawTables: Readonly<Record<string, RawTableEntry>>;
-  // Unmanaged tables declared via r.unmanagedTable() — `EntityTableMeta`
-  // shape (post-drizzle), keyed by feature-local table-name. Cousin of
-  // rawTables: same bypass-justification contract, different storage
-  // shape. `kumiko schema generate` aggregates these alongside
-  // r.entity()-derived metas to build the full schema.
-  readonly unmanagedTables: Readonly<Record<string, UnmanagedTableEntry>>;
   // Optional Zod-schema for env-vars this feature reads at runtime.
   // Declared via `r.envSchema(z.object({...}))`. `composeEnvSchema` reads
   // this to build one app-wide schema for boot-validation + dry-run
@@ -438,6 +417,9 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   ): EntityRef;
   entity(definition: { readonly name: string } & EntityDefinition): EntityRef;
 
+  // Shorthand for registerEntityCrud(r, ...), scoped to this registrar.
+  crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
+
   writeHandler<TName extends string, TSchema extends ZodType>(
     def: WriteHandlerDefinition<TName, TSchema>,
   ): HandlerRef;
@@ -737,34 +719,23 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // bleibt runProdApp.extraRoutes.
   httpRoute(definition: HttpRouteDefinition): void;
 
-  // Declare a raw Drizzle table that bypasses the event-sourcing system.
-  // Reserved for legacy-import, read-only caches, write-only webhook
-  // payload buffers, or any other case where the event-sourced flow
-  // doesn't fit. The dev-server iterates these alongside r.entity()
-  // projections at boot so the table exists before the first query.
-  // Apps still declare the table in `drizzle/schema.ts` so drizzle-kit
-  // tracks migrations and schema-drift detection works automatically.
+  // Declare an "unmanaged" framework-native table that bypasses the
+  // event-sourcing system. Reserved for legacy-import, read-only caches,
+  // write-only webhook payload buffers, or read-side projections of
+  // event-streams (delivery-attempts, job-run-logs) where r.entity()'s
+  // aggregate-lifecycle assumptions don't fit. The dev-server iterates
+  // these alongside r.entity() projections at boot so the table exists
+  // before the first query.
+  //
+  // EntityTableMeta carries the same column-shape that r.entity() builds,
+  // minus the audit-trail + base-columns scaffolding. The `meta` argument
+  // is the result of `defineUnmanagedTable(...)` / `buildEntityTableMeta(...)`
+  // from `@cosmicdrift/kumiko-framework/db`.
   //
   // The required `reason` string is the marker that justifies the bypass —
   // 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;
-
-  // Declare an "unmanaged" framework-native table (post-drizzle).
-  // EntityTableMeta carries the same column-shape that r.entity() builds,
-  // minus the audit-trail + base-columns scaffolding — used for read-side
-  // projections of event-streams (delivery-attempts, job-run-logs) where
-  // r.entity()'s aggregate-lifecycle assumptions don't fit.
-  //
-  // The `meta` argument is the result of `defineUnmanagedTable(...)` from
-  // `@cosmicdrift/kumiko-framework/db`. Reason-justification + audit-trail
-  // contract identical to `r.rawTable`.
-  //
-  // Why this exists separate from `r.rawTable`: rawTable carries a Drizzle
-  // `PgTable` (legacy), unmanagedTable carries the new `EntityTableMeta`
-  // shape that `migrate-runner` consumes. After the full drizzle-cut they
-  // will likely merge; for now they coexist.
-  unmanagedTable(meta: EntityTableMeta, options: UnmanagedTableOptions): void;
+  rawTable(meta: EntityTableMeta, options: RawTableOptions): void;
 
   // Register the tree-actions schema for this feature — a map of
   // action-name → action-definition (with optional typed args). At-most-
@@ -815,6 +786,7 @@ export type Registry = {
   getAllEntities(): ReadonlyMap<string, EntityDefinition>;
   getWriteHandler(name: string): WriteHandlerDef | undefined;
   getQueryHandler(name: string): QueryHandlerDef | undefined;
+  getAllQueryHandlers(): ReadonlyMap<string, QueryHandlerDef>;
   getSearchableFields(entityName: string): readonly string[];
   getSortableFields(entityName: string): readonly string[];
   getRelations(entityName: string): EntityRelations;

package/src/engine/types/fields.ts

@@ -107,6 +107,12 @@ export type TextFieldDef = {
    *  Default: false — analog zu `sortable`, opt-in. */
   readonly filterable?: boolean;
   readonly encrypted?: boolean;
+  /** User/admin may legitimately see the value (their own IBAN, passport
+   *  number) — unlike `r.secret()`, which only server code reads. A
+   *  declarative alias over the subject-KMS (pii/userOwned/tenantOwned):
+   *  only allowed on `type: "text"`, can't combine with `searchable`/
+   *  `sortable` (boot validator, kumiko-platform#231/#456). */
+  readonly piiEncrypted?: boolean;
   readonly sensitive?: boolean;
   readonly format?: "email" | "url" | "phone";
   readonly default?: string;

package/src/engine/types/index.ts

@@ -76,9 +76,6 @@ export type {
   SecretOptions,
   UiHintOption,
   UiHints,
-  UnmanagedTableDef,
-  UnmanagedTableEntry,
-  UnmanagedTableOptions,
 } from "./feature";
 export type {
   AnyFileFieldDef,

package/src/es-ops/README.md

@@ -7,7 +7,7 @@ ES-Operations für Kumiko-Apps. Phase 1+1.5 liefert `seed-migrations` als file-b
 ## Quick API
 
 ```ts
-import { runProdApp } from "@cosmicdrift/kumiko-dev-server";
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
 
 await runProdApp({
   features: [...],

package/src/es-ops/__tests__/runner.integration.test.ts

@@ -72,6 +72,14 @@ const seedTestFeature = defineFeature("esopstest", (r) => {
     },
     { access: { openToAll: true } },
   );
+  // Role-gated handler (no openToAll): the bare system actor has no bypass
+  // for explicit role gates — only systemWriteAs' extraRoles reaches it.
+  r.writeHandler(
+    "probe:admin-only",
+    z.object({ label: z.string().min(1) }),
+    async (event, ctx) => probeExecutor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["SystemAdmin"] } },
+  );
 });
 
 let testDb: TestDb;
@@ -233,6 +241,72 @@ describe("runPendingSeedMigrations (integration)", () => {
     }
   });
 
+  test("systemWriteAs ohne extraRoles → access_denied gegen rollen-gated Handler, mit extraRoles → durch", async () => {
+    const denyDir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-denied.ts",
+        content: `
+          export default {
+            description: "no extraRoles against a role-gated handler",
+            run: async (ctx) => {
+              await ctx.systemWriteAs("esopstest:write:probe:admin-only", { label: "denied" });
+            },
+          };
+        `,
+      },
+    ]);
+    try {
+      await expect(
+        runPendingSeedMigrations({
+          db: testDb.db,
+          seedsDir: denyDir,
+          appliedBy: "boot",
+          registry,
+          createContext: (dbRunner) => createSeedMigrationContext({ dispatcher, dbRunner }),
+          logger: () => {},
+        }),
+      ).rejects.toThrow(/access_denied/);
+      expect(await selectEvents()).toHaveLength(0);
+    } finally {
+      rmSync(denyDir, { recursive: true, force: true });
+    }
+
+    const allowDir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-allowed.ts",
+        content: `
+          export default {
+            description: "extraRoles reaches a role-gated handler",
+            run: async (ctx) => {
+              await ctx.systemWriteAs(
+                "esopstest:write:probe:admin-only",
+                { label: "allowed" },
+                undefined,
+                ["SystemAdmin"],
+              );
+            },
+          };
+        `,
+      },
+    ]);
+    try {
+      await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: allowDir,
+        appliedBy: "boot",
+        registry,
+        createContext: (dbRunner) => createSeedMigrationContext({ dispatcher, dbRunner }),
+        logger: () => {},
+      });
+      const events = await selectEvents();
+      expect(events).toHaveLength(1);
+      expect(events[0]?.type).toBe("esops-probe.created");
+      expect(events[0]?.tenant_id).toBe(SYSTEM_TENANT_ID);
+    } finally {
+      rmSync(allowDir, { recursive: true, force: true });
+    }
+  });
+
   test("WriteResult{isSuccess:false} → throw + Marker NICHT geschrieben", async () => {
     // Critical: ohne diese Garantie würde ein silent-failed Write den Seed
     // als "applied" markieren → beim nächsten Boot kein retry → DB-Drift