@cosmicdrift/kumiko-framework 0.155.1 → 0.156.1

package/src/engine/__tests__/raw-table.test.ts

@@ -1,35 +1,47 @@
 // Unit tests for r.rawTable() — declaration-time validation + registry
-// aggregation. Full DB roundtrip (setupTestStack pushes the table → INSERT
-// / SELECT) lives in src/__tests__/raw-table.integration.ts.
+// aggregation. Post-drizzle-cut merge of the former r.rawTable() (legacy
+// Drizzle PgTable) and r.unmanagedTable() (EntityTableMeta) — this file
+// absorbs the former unmanaged-table.test.ts coverage under the new name.
+// Full DB roundtrip (setupTestStack pushes the table → INSERT / SELECT)
+// lives in src/__tests__/raw-table.integration.test.ts.
 
 import { describe, expect, test } from "bun:test";
-import type { SchemaTable } from "../../db/dialect";
-import { table, text } from "../../db/dialect";
+import {
+  buildEntityTableMeta,
+  defineUnmanagedTable,
+  resolveTableName,
+} from "../../db/entity-table-meta";
 import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../index";
 import { createRegistry } from "../registry";
-import type { ProjectionDefinition } from "../types";
 
-const probeTable = table("rt_probe_table", {
-  id: text("id").primaryKey(),
+const probeMeta = defineUnmanagedTable({
+  tableName: "rt_probe",
+  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
 });
-const probeTableTwo = table("rt_probe_table_two", {
-  id: text("id").primaryKey(),
+const probeMetaTwo = defineUnmanagedTable({
+  tableName: "rt_probe_two",
+  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
 });
 
 describe("r.rawTable — declaration", () => {
-  test("rejects non-kebab-case names", () => {
+  test("rejects an invalid table name", () => {
+    const badMeta = defineUnmanagedTable({
+      tableName: "BadName",
+      columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+    });
     expect(() =>
       defineFeature("probe", (r) => {
-        r.rawTable("BadName", probeTable, { reason: "test" });
+        r.rawTable(badMeta, { reason: "test" });
       }),
-    ).toThrow(/must be kebab-case/);
+    ).toThrow(/must be a valid identifier/);
   });
 
-  test("rejects duplicate names within one feature", () => {
+  test("rejects duplicate registrations within one feature", () => {
     expect(() =>
       defineFeature("probe", (r) => {
-        r.rawTable("cache", probeTable, { reason: "test" });
-        r.rawTable("cache", probeTableTwo, { reason: "test" });
+        r.rawTable(probeMeta, { reason: "test" });
+        r.rawTable(probeMeta, { reason: "test" });
       }),
     ).toThrow(/already registered/);
   });
@@ -37,7 +49,7 @@ describe("r.rawTable — declaration", () => {
   test("rejects empty reason", () => {
     expect(() =>
       defineFeature("probe", (r) => {
-        r.rawTable("cache", probeTable, { reason: "" });
+        r.rawTable(probeMeta, { reason: "" });
       }),
     ).toThrow(/options\.reason must be a non-empty string/);
   });
@@ -45,106 +57,144 @@ describe("r.rawTable — declaration", () => {
   test("rejects whitespace-only reason", () => {
     expect(() =>
       defineFeature("probe", (r) => {
-        r.rawTable("cache", probeTable, { reason: "   " });
+        r.rawTable(probeMeta, { reason: "   " });
       }),
     ).toThrow(/options\.reason must be a non-empty string/);
   });
 
-  test("accepts valid registration and stores reason verbatim", () => {
+  test("accepts valid registration and stores meta + reason", () => {
     const feature = defineFeature("probe", (r) => {
-      r.rawTable("cache", probeTable, {
-        reason: "external Stripe webhook cache, write-only by webhook handler",
+      r.rawTable(probeMeta, {
+        reason: "read-side projection of an event-stream",
       });
     });
-    expect(feature.rawTables).toHaveProperty("cache");
-    expect(feature.rawTables["cache"]?.reason).toBe(
-      "external Stripe webhook cache, write-only by webhook handler",
-    );
-    expect(feature.rawTables["cache"]?.table).toBe(probeTable);
+    expect(feature.rawTables).toHaveProperty("rt_probe");
+    expect(feature.rawTables["rt_probe"]?.reason).toBe("read-side projection of an event-stream");
+    expect(feature.rawTables["rt_probe"]?.meta).toBe(probeMeta);
+  });
+
+  test("two raw tables on one feature register under their tableName", () => {
+    const feature = defineFeature("dual", (r) => {
+      r.rawTable(probeMeta, { reason: "one" });
+      r.rawTable(probeMetaTwo, { reason: "two" });
+    });
+    expect(Object.keys(feature.rawTables).sort()).toEqual(["rt_probe", "rt_probe_two"]);
+  });
+
+  test("absent rawTables on a feature is ok", () => {
+    const feat = defineFeature("plain", () => {
+      // no r.rawTable calls
+    });
+    expect(feat.rawTables).toEqual({});
   });
 });
 
 describe("createRegistry — rawTable aggregation", () => {
   test("aggregates raw tables across features and tags featureName", () => {
     const featA = defineFeature("billing", (r) => {
-      r.rawTable("stripe-cache", probeTable, { reason: "external API cache" });
+      r.rawTable(probeMeta, { reason: "external API cache" });
     });
     const featB = defineFeature("inventory", (r) => {
-      r.rawTable("legacy-import", probeTableTwo, { reason: "imported pre-ES" });
+      r.rawTable(probeMetaTwo, { reason: "imported pre-ES" });
     });
 
     const registry = createRegistry([featA, featB]);
     const all = registry.getAllRawTables();
 
     expect(all.size).toBe(2);
-    expect(all.get("stripe-cache")?.featureName).toBe("billing");
-    expect(all.get("stripe-cache")?.reason).toBe("external API cache");
-    expect(all.get("legacy-import")?.featureName).toBe("inventory");
+    expect(all.get("rt_probe")?.featureName).toBe("billing");
+    expect(all.get("rt_probe")?.reason).toBe("external API cache");
+    expect(all.get("rt_probe_two")?.featureName).toBe("inventory");
   });
 
-  test("rejects cross-feature name collisions at boot", () => {
+  test("rejects cross-feature tableName collisions at boot", () => {
+    // Two features can't share the same physical tableName — migrate-runner
+    // would race two CREATE TABLE statements. Boot-validator catches it.
     const featA = defineFeature("a", (r) => {
-      r.rawTable("shared", probeTable, { reason: "first" });
+      r.rawTable(probeMeta, { reason: "first" });
     });
     const featB = defineFeature("b", (r) => {
-      r.rawTable("shared", probeTableTwo, { reason: "second" });
+      r.rawTable(probeMeta, { reason: "second" });
     });
-
     expect(() => createRegistry([featA, featB])).toThrow(
-      /Raw-table "shared" registered by both feature "a" and "b"/,
+      /Raw-table "rt_probe" registered by both feature "a" and "b"/,
     );
   });
 
-  test("absent rawTables block on a feature is ok (legacy / hand-built features)", () => {
-    const featNoRaw = defineFeature("no-raw", () => {
-      // no r.rawTable calls
+  test("two features with distinct tableNames register cleanly", () => {
+    const featA = defineFeature("a", (r) => {
+      r.rawTable(probeMeta, { reason: "first" });
+    });
+    const featB = defineFeature("b", (r) => {
+      r.rawTable(probeMetaTwo, { reason: "second" });
+    });
+    expect(() => createRegistry([featA, featB])).not.toThrow();
+  });
+
+  test("rejects a raw-table that collides with an entity's physical name", () => {
+    const widget = createEntity({ fields: { name: createTextField() } });
+    // resolveTableName mirrors the migrate-runner — pin the exact physical name.
+    const physical = resolveTableName("widget", widget, "shop");
+    const clashing = defineUnmanagedTable({
+      tableName: physical,
+      columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+    });
+    const entityFeature = defineFeature("shop", (r) => {
+      r.entity("widget", widget);
+    });
+    const tableFeature = defineFeature("other", (r) => {
+      r.rawTable(clashing, { reason: "clash" });
     });
-    const registry = createRegistry([featNoRaw]);
-    expect(registry.getAllRawTables().size).toBe(0);
-  });
-
-  test("two raw tables on the same PgTable register under both names", () => {
-    // Different logical names, identical physical target — legitimate
-    // when one role writes (primary cache) and a second role reads
-    // (alias view). Push-time dedupe keeps the boot to a single CREATE;
-    // the registry keeps both entries so callers can resolve either name.
-    const sharedT = table("rt_shared_dedupe", {
-      id: text("id").primaryKey(),
-    }) as unknown as SchemaTable;
-    const feat = defineFeature("dedupe", (r) => {
-      r.rawTable("primary", sharedT, { reason: "main writer" });
-      r.rawTable("alias", sharedT, { reason: "alias for read consumers" });
-    });
-    const registry = createRegistry([feat]);
-
-    expect(registry.getAllRawTables().size).toBe(2);
-    expect(registry.getAllRawTables().get("primary")?.table).toBe(sharedT);
-    expect(registry.getAllRawTables().get("alias")?.table).toBe(sharedT);
-  });
-
-  test("rejects rawTable that shares a PgTable with an explicit projection", () => {
-    // A r.rawTable() declaring the same physical table as a registered
-    // r.projection() is almost always an authoring bug — two owners on
-    // the same physical table, one event-sourced, one bypass. Boot
-    // throws so the failure points at the misconfiguration site.
-    const sharedT = table("rt_collision_phys", {
-      id: text("id").primaryKey(),
-    }) as unknown as SchemaTable;
-    const projection: ProjectionDefinition = {
-      name: "shared-summary",
-      source: "shared",
-      table: sharedT,
-      apply: {},
-    };
-    const featProj = defineFeature("proj-owner", (r) => {
-      r.projection(projection);
-    });
-    const featRaw = defineFeature("raw-owner", (r) => {
-      r.rawTable("collision", sharedT, { reason: "intentionally bad" });
-    });
-
-    expect(() => createRegistry([featProj, featRaw])).toThrow(
-      /shares a Drizzle PgTable with a registered projection/,
+
+    // Entity registered first, then the colliding raw table.
+    expect(() => createRegistry([entityFeature, tableFeature])).toThrow(
+      new RegExp(`Raw-table "${physical}".*collides with the physical table of entity "widget"`),
+    );
+
+    // Order-independent: raw table registered first, then the entity.
+    expect(() => createRegistry([tableFeature, entityFeature])).toThrow(
+      new RegExp(`Entity "widget".*collides with r.rawTable\\("${physical}"\\)`),
     );
   });
 });
+
+describe("createRegistry — raw tables with PII-annotated fields (#820)", () => {
+  const piiEntity = createEntity({
+    table: "rt_pii_probe",
+    fields: {
+      userId: createTextField({ required: true }),
+      ip: createTextField({ userOwned: { ownerField: "userId" } }),
+    },
+  });
+  const piiMeta = buildEntityTableMeta("rt-pii-probe", piiEntity);
+
+  test("buildEntityTableMeta records the subject-annotated field names", () => {
+    expect(piiMeta.piiSubjectFields).toEqual(["ip"]);
+  });
+
+  test("rejects a PII-carrying raw table without piiEncryptedOnWrite", () => {
+    const feat = defineFeature("probe", (r) => {
+      r.rawTable(piiMeta, { reason: "direct-write store" });
+    });
+    expect(() => createRegistry([feat])).toThrow(
+      /has PII-annotated fields \(ip\) but direct writes bypass the executor's PII encryption/,
+    );
+  });
+
+  test("accepts it once the feature declares piiEncryptedOnWrite", () => {
+    const feat = defineFeature("probe", (r) => {
+      r.rawTable(piiMeta, {
+        reason: "direct-write store",
+        piiEncryptedOnWrite: true,
+      });
+    });
+    expect(() => createRegistry([feat])).not.toThrow();
+  });
+
+  test("a PII-free raw table needs no declaration", () => {
+    const feat = defineFeature("probe", (r) => {
+      r.rawTable(probeMeta, { reason: "plain store" });
+    });
+    expect(() => createRegistry([feat])).not.toThrow();
+  });
+});

package/src/engine/__tests__/registry.test.ts

@@ -61,6 +61,46 @@ describe("createRegistry slot robustness", () => {
   });
 });
 
+describe("getAllQueryHandlers", () => {
+  test("returns every registered query handler, qualified, across multiple features", () => {
+    const taskEntity = createEntity({
+      table: "registry_test_tasks",
+      fields: { title: createTextField({ required: true }) },
+    });
+    const noteEntity = createEntity({
+      table: "registry_test_notes",
+      fields: { body: createTextField({ required: true }) },
+    });
+    const taskFeature = defineFeature("registry-test-task", (r) => {
+      r.crud("task", taskEntity, {
+        write: { access: { roles: ["Admin"] } },
+        read: { access: { openToAll: true } },
+      });
+    });
+    const noteFeature = defineFeature("registry-test-note", (r) => {
+      r.crud("note", noteEntity, {
+        write: { access: { roles: ["Admin"] } },
+        read: { access: { openToAll: true } },
+      });
+    });
+
+    const registry = createRegistry([taskFeature, noteFeature]);
+    const handlers = registry.getAllQueryHandlers();
+
+    expect(handlers.get("registry-test-task:query:task:list")).toBeDefined();
+    expect(handlers.get("registry-test-note:query:note:list")).toBeDefined();
+    // Same Map instance getQueryHandler reads from, not a copy that can drift.
+    expect(handlers.get("registry-test-task:query:task:list")).toBe(
+      registry.getQueryHandler("registry-test-task:query:task:list"),
+    );
+  });
+
+  test("empty registry returns an empty map, not undefined", () => {
+    const registry = createRegistry([]);
+    expect(registry.getAllQueryHandlers().size).toBe(0);
+  });
+});
+
 describe("extensionSelector boot-validation", () => {
   function foundationFeature() {
     return defineFeature("probe-foundation", (r) => {

package/src/engine/boot-validator/__tests__/config-deps.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import { createSystemConfig } from "../../config-helpers";
+import { createSystemConfig, createTenantConfig, createUserConfig } from "../../config-helpers";
 import type { FeatureDefinition } from "../../types";
-import { validateConfigKeyAllowPerRequest, validateConfigKeyComputed } from "../config-deps";
+import {
+  validateConfigKeyAllowPerRequest,
+  validateConfigKeyComputed,
+  validateConfigKeyPiiEncrypted,
+} from "../config-deps";
 
 function fakeFeature(configKeys: FeatureDefinition["configKeys"]): FeatureDefinition {
   return { name: "test-feature", configKeys } as unknown as FeatureDefinition;
@@ -40,3 +44,49 @@ describe("validateConfigKeyAllowPerRequest", () => {
     );
   });
 });
+
+describe("validateConfigKeyPiiEncrypted (kumiko-platform#231/#459)", () => {
+  test("allows piiEncrypted on a tenant-scoped text key", () => {
+    const feature = fakeFeature({
+      billingAddress: createTenantConfig("text", { piiEncrypted: true }),
+    });
+    expect(() => validateConfigKeyPiiEncrypted(feature)).not.toThrow();
+  });
+
+  test("allows piiEncrypted on a user-scoped text key", () => {
+    const feature = fakeFeature({
+      phoneNumber: createUserConfig("text", { piiEncrypted: true }),
+    });
+    expect(() => validateConfigKeyPiiEncrypted(feature)).not.toThrow();
+  });
+
+  test("rejects piiEncrypted on a non-text key", () => {
+    const feature = fakeFeature({
+      rateLimit: { ...createTenantConfig("number"), piiEncrypted: true },
+    });
+    expect(() => validateConfigKeyPiiEncrypted(feature)).toThrow(
+      /piiEncrypted.*only applies to text keys/,
+    );
+  });
+
+  test("rejects piiEncrypted + scope:system", () => {
+    const feature = fakeFeature({
+      apiKey: createSystemConfig("text", { piiEncrypted: true }),
+    });
+    expect(() => validateConfigKeyPiiEncrypted(feature)).toThrow(/piiEncrypted.*scope="system"/);
+  });
+
+  test("rejects piiEncrypted + encrypted", () => {
+    const feature = fakeFeature({
+      iban: createTenantConfig("text", { piiEncrypted: true, encrypted: true }),
+    });
+    expect(() => validateConfigKeyPiiEncrypted(feature)).toThrow(/piiEncrypted=true and encrypted/);
+  });
+
+  test("rejects piiEncrypted + backing:secrets", () => {
+    const feature = fakeFeature({
+      iban: { ...createTenantConfig("text", { piiEncrypted: true }), backing: "secrets" as const },
+    });
+    expect(() => validateConfigKeyPiiEncrypted(feature)).toThrow(/piiEncrypted=true and encrypted/);
+  });
+});

package/src/engine/boot-validator/action-wiring.ts

@@ -15,8 +15,8 @@ function throwIfFunction(value: unknown, message: string): void {
 // static visibility conditions and navigate entityId — all declarative-DSL-
 // only fields (RowFieldExtractor's `{ pick }`/`{ map }`, FieldCondition's
 // `{ field, eq }`/`{ field, ne }`, plain strings). A function literal here
-// compiles fine (the DSL types are structural, not branded) but is silently
-// dropped once the feature config is serialized for the client.
+// does not type-check against these structural DSL types — it only reaches
+// here via a leaked `any`/`as any`, which this runtime check backstops.
 const ACTION_FUNCTION_FIELDS = ["payload", "params", "entityId", "visible"] as const;
 
 function validateActionNoFunctions(

package/src/engine/boot-validator/config-deps.ts

@@ -161,6 +161,41 @@ export function validateConfigKeyBacking(feature: FeatureDefinition): void {
   }
 }
 
+// --- Config key piiEncrypted compatibility (kumiko-platform#231/#459) ---
+
+export function validateConfigKeyPiiEncrypted(feature: FeatureDefinition): void {
+  for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
+    if (!keyDef.piiEncrypted) continue;
+
+    if (keyDef.type !== "text") {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but type="${keyDef.type}" — piiEncrypted only applies to text keys`,
+      );
+    }
+
+    // system scope has no subject (no tenant, no user) for the subject-KMS
+    // to encrypt under.
+    if (keyDef.scope === "system") {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but scope="system" — system-scope has no subject (tenant/user) for the subject-KMS to encrypt under`,
+      );
+    }
+
+    // Mutually exclusive with the shared-cipher path: a config value is
+    // either subject-keyed (piiEncrypted) or master-key-keyed (encrypted/
+    // backing="secrets"), never both — unlike entity fields, which allow
+    // both markers together (double-wrap, e.g. auth-mfa.totpSecret) because
+    // entity rows decrypt through a fixed executor pipeline that peels both
+    // layers. Config values have no such pipeline; picking one keeps the
+    // resolver simple.
+    if (isEncryptedAtRest(keyDef)) {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has both piiEncrypted=true and encrypted/backing="secrets" — pick one: piiEncrypted (subject-KMS, user-visible) or encrypted (shared cipher, server-only values)`,
+      );
+    }
+  }
+}
+
 // --- Config key cross-feature reference validation ---
 
 export function validateConfigReads(

package/src/engine/boot-validator/index.ts

@@ -9,6 +9,7 @@ import {
   validateConfigKeyBacking,
   validateConfigKeyBounds,
   validateConfigKeyComputed,
+  validateConfigKeyPiiEncrypted,
   validateConfigKeyRequired,
   validateConfigReads,
   warnOnToggleableDependencies,
@@ -170,6 +171,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
     validateConfigKeyComputed(feature);
     validateConfigKeyAllowPerRequest(feature);
     validateConfigKeyBacking(feature);
+    validateConfigKeyPiiEncrypted(feature);
     validateOwnershipRules(feature, allClaimKeys, knownRoles);
     validateMultiStreamProjections(feature);
     // Vor validateScreens: dessen visible/entityId-Feldref-Checks werfen für

package/src/engine/boot-validator/pii-retention.ts

@@ -1,5 +1,5 @@
 import type { FeatureDefinition } from "../types";
-import type { PiiAnnotations } from "../types/fields";
+import type { FieldAccess, PiiAnnotations } from "../types/fields";
 import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS } from "./entity-handler";
 
 // Framework-managed Timestamp-Spalten — dürfen als retention.reference
@@ -80,6 +80,38 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         }
       }
 
+      // piiEncrypted (kumiko-platform#231/#456): a declarative alias over
+      // the subject-KMS — text only (storage stays the plaintext column
+      // with subject ciphertext, no separate envelope path).
+      const piiEncryptedFlag = field as { readonly piiEncrypted?: boolean }; // @cast-boundary schema-walk
+      if (piiEncryptedFlag.piiEncrypted === true && field.type !== "text") {
+        throw new Error(
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { piiEncrypted: true } but has type "${field.type}" — piiEncrypted only applies to text fields.`,
+        );
+      }
+      // piiEncrypted wiring (kumiko-platform#457): resolveSubjectForField/
+      // collectPiiSubjectFields only ever look at pii/userOwned/tenantOwned
+      // — piiEncrypted alone doesn't pick a subject. Without one of the
+      // three, the field would silently stay plaintext (no encrypt-on-
+      // write happens). Fail at boot like lookupable does, not at first read.
+      if (piiEncryptedFlag.piiEncrypted === true && annotCount === 0) {
+        throw new Error(
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { piiEncrypted: true } without a subject annotation (pii / userOwned / tenantOwned) — piiEncrypted alone doesn't encrypt anything, it only adds the access/masking layer on top of the subject-key encryption.`,
+        );
+      }
+      // piiEncrypted access model (kumiko-platform#460): field-level
+      // access.read already exists + is enforced (filterReadFields), but
+      // its default without an access config is "visible to everyone" —
+      // the wrong default for a field whose entire point is "only the
+      // legitimate owner may see the plaintext". Force an explicit choice
+      // instead of silently decrypting for every row-reader.
+      const accessFlag = field as { readonly access?: FieldAccess }; // @cast-boundary schema-walk
+      if (piiEncryptedFlag.piiEncrypted === true && !accessFlag.access?.read) {
+        throw new Error(
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { piiEncrypted: true } without { access: { read: [...] } } — without it the decrypted value is visible to anyone who can read the row. Set the roles allowed to see the plaintext.`,
+        );
+      }
+
       // sensitive-Felder liegen seit #967 als Tabellen-Ciphertext im Event-
       // Log — ohne ciphertext-at-rest würde der Append Klartext in die
       // immutable History schreiben.
@@ -100,12 +132,12 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
       // Substring-Suche/Sortierung auf Ciphertext ist prinzipbedingt
       // unmöglich — searchable würde Plaintext-Kopien in den Suchindex
       // schieben, sortable sortiert Base64-Blobs. Equality → lookupable.
-      if (annotCount > 0) {
+      if (annotCount > 0 || piiEncryptedFlag.piiEncrypted === true) {
         const flags = field as { readonly searchable?: boolean; readonly sortable?: boolean }; // @cast-boundary schema-walk
         if (flags.searchable === true || flags.sortable === true) {
           const offending = flags.searchable === true ? "searchable" : "sortable";
           throw new Error(
-            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation with { ${offending}: true } — ${offending} on encrypted fields cannot work (ciphertext at rest). For equality lookups use { lookupable: true }; for search/sort the field must stay plaintext (allowPlaintext).`,
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation or { piiEncrypted: true } with { ${offending}: true } — ${offending} on encrypted fields cannot work (ciphertext at rest). For equality lookups use { lookupable: true }; for search/sort the field must stay plaintext (allowPlaintext).`,
           );
         }
       }

package/src/engine/build-config-feature-schema.ts

@@ -260,9 +260,6 @@ function deriveField(def: ConfigKeyDefinition): FieldDefinition {
 function collectMaskedKeys(registry: Registry): MaskedKey[] {
   const out: MaskedKey[] = [];
   for (const [qn, def] of registry.getAllConfigKeys()) {
-    // computed keys derive their value — there is no row to set, so a
-    // configEdit screen could not write them. Skip even when masked.
-    if (def.mask === undefined || def.computed !== undefined) continue;
     const sep = qn.indexOf(":config:");
     if (sep === -1) continue;
     const ownerFeature = qn.slice(0, sep);
@@ -271,6 +268,9 @@ function collectMaskedKeys(registry: Registry): MaskedKey[] {
         `[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" has invalid group "${def.group}" — must be kebab-case.`,
       );
     }
+    // computed keys derive their value — there is no row to set, so a
+    // configEdit screen could not write them. Skip even when masked.
+    if (def.mask === undefined || def.computed !== undefined) continue;
     out.push({
       qn,
       feature: def.group ?? ownerFeature,

package/src/engine/config-helpers.ts

@@ -81,6 +81,7 @@ type ConfigKeyOptions<T extends ConfigKeyType> = {
   read?: readonly string[];
   default?: ConfigValue<T>;
   encrypted?: boolean;
+  piiEncrypted?: T extends "text" ? boolean : never;
   options?: readonly string[]; // for select type
   bounds?: T extends "number" ? ConfigBounds : never;
   // Regex enforced at write (set.write) — only meaningful for text keys
@@ -123,6 +124,7 @@ function createConfigKey<T extends ConfigKeyType>(
     },
     default: opts.default,
     ...(opts.encrypted ? { encrypted: true } : {}),
+    ...(opts.piiEncrypted ? { piiEncrypted: true } : {}),
     ...(opts.options ? { options: opts.options } : {}),
     bounds: opts.bounds as ConfigBounds | undefined, // @cast-boundary schema-walk
     ...(opts.pattern ? { pattern: opts.pattern } : {}),

package/src/engine/define-feature.ts

@@ -2,6 +2,7 @@ import { createInitialFeatureBuilderState } from "./feature-builder-state";
 import { buildConfigEventsJobsMethods } from "./feature-config-events-jobs";
 import { buildEntityHandlerMethods } from "./feature-entity-handlers";
 import { buildUiExtensionsMethods } from "./feature-ui-extensions";
+import { unwrapArrayForm } from "./object-form";
 import type { FeatureDefinition, FeatureRegistrar, HookMap, UiHints } from "./types";
 import type { RequiresApi } from "./types/feature";
 
@@ -25,11 +26,7 @@ import type { RequiresApi } from "./types/feature";
 function resolveFeatureNamesArgs(
   args: readonly [{ readonly features: readonly string[] }] | readonly string[],
 ): readonly string[] {
-  const [first] = args;
-  if (typeof first === "object" && first !== null && "features" in first) {
-    return first.features;
-  }
-  return args as readonly string[];
+  return unwrapArrayForm(args, "features");
 }
 
 export function defineFeature<const TName extends string, TExports = undefined>(
@@ -156,7 +153,6 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     workspaces: state.workspaces,
     httpRoutes: state.httpRoutes,
     rawTables: state.rawTables,
-    unmanagedTables: state.unmanagedTables,
     ...(state.treeActions !== undefined && { treeActions: state.treeActions }),
     ...(state.envSchema !== undefined && { envSchema: state.envSchema }),
   };

package/src/engine/entity-handlers.ts

@@ -28,7 +28,7 @@ import type {
 // Two API shapes — pick one per project, don't mix:
 //
 //   PREFERRED — full standard CRUD set in one call:
-//     registerEntityCrud(r, "note", noteEntity, { write: { access }, read: { access } })
+//     r.crud("note", noteEntity, { write: { access }, read: { access } })
 //
 //   PREFERRED — one function per verb, type-safe, no magic strings:
 //     r.writeHandler(defineEntityCreateHandler("note", noteEntity, { access }))
@@ -176,7 +176,15 @@ export function defineEntityWriteHandler(
         changes: buildUpdateSchema(entity),
       });
       handler = async (event, ctx) =>
-        executor.update(event.payload as UpdatePayload, event.user, ctx.db); // @cast-boundary engine-payload
+        // skipUnchanged (#464): API-driven updates diff against the stored
+        // row so a resubmitted-but-identical field doesn't force a fresh
+        // pii/encrypted ciphertext. Direct executor.update() callers (e.g.
+        // KEK-rotation, the user-data-rights #494 backfill) don't go through
+        // this handler and keep today's always-re-encrypt behavior, which
+        // they rely on to intentionally force a fresh event/ciphertext.
+        executor.update(event.payload as UpdatePayload, event.user, ctx.db, {
+          skipUnchanged: true,
+        }); // @cast-boundary engine-payload
       break;
     case "delete":
       schema = idSchema;
@@ -475,9 +483,7 @@ export function registerEntityCrud(
 ): void {
   const verbs = { ...defaultCrudVerbs(entity), ...options?.verbs };
   if (verbs.restore && entity.softDelete !== true) {
-    throw new Error(
-      `registerEntityCrud("${entityName}"): restore requested but entity has no softDelete: true`,
-    );
+    throw new Error(`restore requested but entity "${entityName}" has no softDelete: true`);
   }
 
   if (options?.registerEntity !== false) {

package/src/engine/feature-ast/__tests__/parse-real-features.test.ts

@@ -69,7 +69,7 @@ const FEATURES: readonly RealFeature[] = [
     path: "packages/bundled-features/src/sessions/feature.ts",
     expectedFeatureName: "sessions",
     recognisedKinds: ["hook", "writeHandler", "queryHandler"],
-    errorMethodNames: ["unmanagedTable", "job"],
+    errorMethodNames: ["rawTable", "job"],
   },
   {
     path: "packages/bundled-features/src/auth-email-password/feature.ts",