@cosmicdrift/kumiko-framework 0.155.1 → 0.156.1

package/README.md

@@ -28,9 +28,10 @@ Bun is the intended runtime and test runner.
 ## At-a-glance
 
 ```typescript
-import { defineFeature, createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 
 export const taskEntity = createEntity({
+  table: "read_tasks",
   fields: {
     title: createTextField({ required: true, searchable: true }),
     done: createTextField(),
@@ -38,44 +39,14 @@ export const taskEntity = createEntity({
   softDelete: true,
 });
 
-const taskTable = buildDrizzleTable("task", taskEntity);
-const taskExecutor = createEventStoreExecutor(taskTable, taskEntity, { entityName: "task" });
-
 export const taskFeature = defineFeature("tasks", (r) => {
-  r.entity("task", taskEntity);
-
-  // Write handlers go through createEventStoreExecutor — events + projection in one TX,
-  // optimistic locking, access control, all explicit.
-  r.writeHandler(
-    "task:create",
-    z.object({ title: z.string() }),
-    async (event, ctx) => taskExecutor.create(event.payload, event.user, ctx.db),
-    { access: { roles: ["User"] } },
-  );
-  r.writeHandler(
-    "task:update",
-    z.object({ id: z.uuid(), version: z.number(), changes: z.object({ title: z.string().optional() }) }),
-    async (event, ctx) => taskExecutor.update(event.payload, event.user, ctx.db),
-    { access: { roles: ["User"] } },
-  );
-  r.writeHandler(
-    "task:delete",
-    z.object({ id: z.uuid() }),
-    async (event, ctx) => taskExecutor.delete(event.payload, event.user, ctx.db),
-    { access: { roles: ["Admin"] } },
-  );
-  r.queryHandler(
-    "task:list",
-    z.object({}),
-    async (query, ctx) => taskExecutor.list(query.payload, query.user, ctx.db),
-    { access: { openToAll: true } },
-  );
-  r.queryHandler(
-    "task:detail",
-    z.object({ id: z.uuid() }),
-    async (query, ctx) => taskExecutor.detail(query.payload, query.user, ctx.db),
-    { access: { openToAll: true } },
-  );
+  // r.crud wires create/update/delete/restore + list/detail queries in one
+  // call — events + projection in the same TX, optimistic locking, access
+  // control, all explicit via the options below.
+  r.crud("task", taskEntity, {
+    write: { access: { roles: ["User"] } },
+    read: { access: { openToAll: true } },
+  });
 
   // Read-model fed from task events, rebuildable via the CLI
   r.projection({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.155.1",
+  "version": "0.156.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -193,7 +193,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.155.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.156.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/entity-permalink-open.integration.test.ts

@@ -0,0 +1,94 @@
+// Issue #912 — Teilbare Entity-Permalinks. Der Copy-Link-Button selbst ist
+// UI-Zucker (baut eine URL, kopiert sie); die eigentliche Anforderung des
+// Issues ist "ein Permalink darf nie Auth/Tenant-Isolation umgehen". Ein
+// entityEdit-Permalink öffnet beim Klick exactly denselben
+// `<feature>:query:<entity>:detail`-Call, den jede Entity schon für ihr
+// Update-Formular nutzt — es gibt keinen separaten Permalink-Resolve-Pfad.
+// Dieser Test beweist den Deny für beide Achsen, die einen Leak verhindern
+// müssten: Rollen-Gate (dispatcher-seitig, default-deny) und Tenant-Scoping
+// (strukturell über ctx.db).
+
+import { describe, expect, test } from "bun:test";
+import { setupTestStackFromFeatures } from "@cosmicdrift/kumiko-dev-server/setup-test-stack-from-features";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDetailHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  pushEntityProjectionTables,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+
+const noteEntity = createEntity({
+  table: "read_permalink_notes",
+  fields: {
+    title: createTextField({ required: true, maxLength: 160, allowPlaintext: "is-business-data" }),
+  },
+});
+
+const permalinkFeature = defineFeature("permalink-fixture", (r) => {
+  r.entity("note", noteEntity);
+  const access = { roles: ["TenantAdmin"] } as const;
+  r.writeHandler(defineEntityCreateHandler("note", noteEntity, { access }));
+  r.queryHandler(defineEntityDetailHandler("note", noteEntity, { access }));
+});
+
+describe("entityEdit permalink open-path denies cleanly", () => {
+  test("unauthorized role → AccessDeniedError, not the record", async () => {
+    const stack = await setupTestStackFromFeatures([permalinkFeature]);
+    try {
+      const tenantId = testTenantId(701);
+      const owner = createTestUser({ id: 701, tenantId, roles: ["TenantAdmin"] });
+      const outsider = createTestUser({ id: 702, tenantId, roles: ["TeamMember"] });
+      await pushEntityProjectionTables(stack, stack.registry);
+
+      const created = await stack.http.writeOk<{ id: string }>(
+        "permalink-fixture:write:note:create",
+        { title: "Q3 Forecast" },
+        owner,
+      );
+
+      const res = await stack.http.query(
+        "permalink-fixture:query:note:detail",
+        { id: created.id },
+        outsider,
+      );
+      expect(res.ok).toBe(false);
+      const body = (await res.json()) as { isSuccess?: boolean; error?: { code?: string } };
+      expect(body.isSuccess).not.toBe(true);
+      expect(body.error?.code).toBe("access_denied");
+    } finally {
+      await stack.cleanup();
+    }
+  });
+
+  test("cross-tenant open → not-found, not the other tenant's record", async () => {
+    const stack = await setupTestStackFromFeatures([permalinkFeature]);
+    try {
+      const tenantA = testTenantId(703);
+      const tenantB = testTenantId(704);
+      const ownerA = createTestUser({ id: 703, tenantId: tenantA, roles: ["TenantAdmin"] });
+      const adminB = createTestUser({ id: 704, tenantId: tenantB, roles: ["TenantAdmin"] });
+      await pushEntityProjectionTables(stack, stack.registry);
+
+      const created = await stack.http.writeOk<{ id: string }>(
+        "permalink-fixture:write:note:create",
+        { title: "Tenant A Secret" },
+        ownerA,
+      );
+
+      const row = await stack.http.queryOk<Record<string, unknown> | null>(
+        "permalink-fixture:query:note:detail",
+        { id: created.id },
+        adminB,
+      );
+      expect(row).toBeNull();
+    } finally {
+      await stack.cleanup();
+    }
+  });
+});

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

@@ -4,7 +4,7 @@
 // kumiko-platform/docs/plans/architecture/table-ddl-guard.md (Stufe 3).
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { table, text, timestamp } from "../db/dialect";
+import { defineUnmanagedTable } from "../db/entity-table-meta";
 import { asRawClient, insertOne, selectMany } from "../db/query";
 import { defineFeature } from "../engine";
 import { setupTestStack, type TestStack, unsafePushTables } from "../stack";
@@ -13,30 +13,19 @@ import { setupTestStack, type TestStack, unsafePushTables } from "../stack";
 // write-only by an integration handler, read-only by a query, never
 // event-sourced (the data isn't a domain fact, it's a side-effect
 // snapshot).
-const stripeWebhookCache = table("rt_int_stripe_webhook_cache", {
-  eventId: text("event_id").primaryKey(),
-  payload: text("payload").notNull(),
-  receivedAt: timestamp("received_at", { withTimezone: true }).notNull().defaultNow(),
-});
-
-// A second physical table reachable through two distinct r.rawTable
-// registrations — pins the seenTables-by-reference dedupe at push time.
-// Two logical names, one CREATE.
-const sharedSyncCache = table("rt_int_shared_sync_cache", {
-  syncId: text("sync_id").primaryKey(),
-  payload: text("payload").notNull(),
+const stripeWebhookCacheMeta = defineUnmanagedTable({
+  tableName: "rt_int_stripe_webhook_cache",
+  columns: [
+    { name: "event_id", pgType: "text", notNull: true, primaryKey: true },
+    { name: "payload", pgType: "text", notNull: true },
+    { name: "received_at", pgType: "timestamptz", notNull: true, defaultSql: "now()" },
+  ],
 });
 
 const webhookCacheFeature = defineFeature("webhook-cache", (r) => {
-  r.rawTable("stripe", stripeWebhookCache, {
+  r.rawTable(stripeWebhookCacheMeta, {
     reason: "external Stripe webhook payload cache — write-only by webhook handler",
   });
-  r.rawTable("primary-sync", sharedSyncCache, {
-    reason: "shared sync-state cache, primary writer",
-  });
-  r.rawTable("secondary-sync", sharedSyncCache, {
-    reason: "same physical table, different logical role for read consumers",
-  });
 });
 
 let stack: TestStack;
@@ -54,9 +43,9 @@ describe("r.rawTable — DB roundtrip via setupTestStack", () => {
     const eventId = "evt_test_123";
     const payload = JSON.stringify({ type: "invoice.paid", amount: 4200 });
 
-    await insertOne(stack.db, stripeWebhookCache, { eventId, payload });
+    await insertOne(stack.db, stripeWebhookCacheMeta, { eventId, payload });
 
-    const rows = await selectMany(stack.db, stripeWebhookCache, { eventId: eventId });
+    const rows = await selectMany(stack.db, stripeWebhookCacheMeta, { eventId: eventId });
 
     expect(rows).toHaveLength(1);
     expect(rows[0]?.payload).toBe(payload);
@@ -65,11 +54,11 @@ describe("r.rawTable — DB roundtrip via setupTestStack", () => {
 
   test("registry exposes the raw table with its reason and featureName", () => {
     const all = stack.registry.getAllRawTables();
-    const entry = all.get("stripe");
+    const entry = all.get("rt_int_stripe_webhook_cache");
     expect(entry).toBeDefined();
     expect(entry?.featureName).toBe("webhook-cache");
     expect(entry?.reason).toContain("Stripe webhook payload cache");
-    expect(entry?.table).toBe(stripeWebhookCache);
+    expect(entry?.meta).toBe(stripeWebhookCacheMeta);
   });
 
   test("INSERT bypasses the event store — no kumiko_events row produced", async () => {
@@ -82,7 +71,7 @@ describe("r.rawTable — DB roundtrip via setupTestStack", () => {
     );
     const beforeCount = Number(before[0]?.count ?? 0);
 
-    await insertOne(stack.db, stripeWebhookCache, {
+    await insertOne(stack.db, stripeWebhookCacheMeta, {
       eventId: "evt_no_event_emitted",
       payload: "{}",
     });
@@ -95,22 +84,10 @@ describe("r.rawTable — DB roundtrip via setupTestStack", () => {
     expect(afterCount).toBe(beforeCount);
   });
 
-  test("two registrations sharing one PgTable result in one CREATE (dedupe by reference)", async () => {
-    // primary-sync + secondary-sync both target sharedSyncCache. If the
-    // setupTestStack dedupe (seenTables-by-table-reference) had silently
-    // broken, beforeAll's setupTestStack would have raised a 42P07 on
-    // the second push and never reached this test.
-    await insertOne(stack.db, sharedSyncCache, { syncId: "sync_1", payload: "{}" });
-    const rows = await selectMany(stack.db, sharedSyncCache, { syncId: "sync_1" });
-    expect(rows).toHaveLength(1);
-    // Both registrations are visible in the registry — same physical
-    // target, different logical handles.
-    expect(stack.registry.getAllRawTables().get("primary-sync")?.table).toBe(sharedSyncCache);
-    expect(stack.registry.getAllRawTables().get("secondary-sync")?.table).toBe(sharedSyncCache);
-  });
-
   test("a second push on the same rawTable is idempotent — CREATE IF NOT EXISTS", async () => {
     // unsafePushTables uses CREATE TABLE IF NOT EXISTS — idempotent by design.
-    await expect(unsafePushTables(stack.db, { idem: stripeWebhookCache })).resolves.toBeUndefined();
+    await expect(
+      unsafePushTables(stack.db, { idem: stripeWebhookCacheMeta }),
+    ).resolves.toBeUndefined();
   });
 });

package/src/crypto/__tests__/pii-field-encryption.test.ts

@@ -1,11 +1,20 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine/factories";
 import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
-import { KeyNotFoundError, type KmsContext, subjectIdFromKey } from "../kms-adapter";
+import {
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsContext,
+  subjectIdFromKey,
+  subjectIdToKey,
+} from "../kms-adapter";
 import {
   decryptPiiFieldValues,
+  decryptPiiValueForSubject,
   encryptPiiFieldValues,
+  encryptPiiValueForSubject,
   isPiiCiphertext,
+  PII_CIPHERTEXT_PREFIX,
   PII_ERASED_SENTINEL,
 } from "../pii-field-encryption";
 import { collectPiiSubjectFields } from "../subject-resolver";
@@ -214,3 +223,98 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
     );
   });
 });
+
+describe("piiEncrypted alias (kumiko-platform#457)", () => {
+  test("piiEncrypted + tenantOwned round-trips through the same subject-KMS pipeline", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const brandingWithAccess = createEntity({
+      fields: {
+        iban: createTextField({
+          piiEncrypted: true,
+          tenantOwned: true,
+          access: { read: ["TenantAdmin"] },
+        }),
+      },
+      table: "pii_branding_iban",
+    });
+    const fields = collectPiiSubjectFields(brandingWithAccess);
+    expect(fields).toEqual(["iban"]);
+
+    const row = { id: UUID_A, tenantId: UUID_B, iban: "DE89370400440532013000" };
+    const stored = await encryptPiiFieldValues(row, brandingWithAccess, fields, kms, KMS_CTX);
+    expect(isPiiCiphertext(stored["iban"])).toBe(true);
+    expect(String(stored["iban"])).toStartWith(`kumiko-pii:v1:tenant:${UUID_B}:`);
+
+    const read = await decryptPiiFieldValues(stored, fields, kms, KMS_CTX);
+    expect(read["iban"]).toBe("DE89370400440532013000");
+  });
+
+  test("piiEncrypted field is covered by subject erasure (Art. 17, kumiko-platform#461)", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const brandingWithAccess = createEntity({
+      fields: {
+        iban: createTextField({ piiEncrypted: true, tenantOwned: true }),
+      },
+      table: "pii_branding_iban_erasure",
+    });
+    const fields = collectPiiSubjectFields(brandingWithAccess);
+    const row = { id: UUID_A, tenantId: UUID_B, iban: "DE89370400440532013000" };
+    const stored = await encryptPiiFieldValues(row, brandingWithAccess, fields, kms, KMS_CTX);
+
+    // Erasure is subject-keyed, not field-flag-keyed — kms.eraseKey doesn't
+    // know or care that this field is piiEncrypted vs. plain tenantOwned.
+    await kms.eraseKey({ kind: "tenant", tenantId: UUID_B });
+
+    const read = await decryptPiiFieldValues(stored, fields, kms, KMS_CTX);
+    expect(read["iban"]).toBe(PII_ERASED_SENTINEL);
+  });
+});
+
+describe("encryptPiiValueForSubject / decryptPiiValueForSubject (kumiko-platform#459)", () => {
+  test("round-trips a single value for a tenant subject", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const subject = { kind: "tenant" as const, tenantId: UUID_B };
+    const stored = await encryptPiiValueForSubject(kms, subject, "DE89370400440532013000", KMS_CTX);
+    expect(isPiiCiphertext(stored)).toBe(true);
+    expect(stored).toStartWith(`kumiko-pii:v1:tenant:${UUID_B}:`);
+
+    const read = await decryptPiiValueForSubject(kms, stored, KMS_CTX);
+    expect(read).toBe("DE89370400440532013000");
+  });
+
+  test("erased subject: decrypt yields the sentinel", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const subject = { kind: "user" as const, userId: UUID_A };
+    const stored = await encryptPiiValueForSubject(kms, subject, "+49 151 00000000", KMS_CTX);
+    await kms.eraseKey(subject);
+
+    const read = await decryptPiiValueForSubject(kms, stored, KMS_CTX);
+    expect(read).toBe(PII_ERASED_SENTINEL);
+  });
+
+  test("plaintext passes through decrypt unchanged (pre-engine rows)", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const read = await decryptPiiValueForSubject(kms, "plain-value", KMS_CTX);
+    expect(read).toBe("plain-value");
+  });
+});
+
+describe("cross-subject decrypt leak (kumiko-framework#1190)", () => {
+  test("ciphertext forged to a different-but-valid subject's DEK fails GCM auth, not just KeyNotFound", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const subjectA = { kind: "tenant" as const, tenantId: UUID_A };
+    const subjectB = { kind: "tenant" as const, tenantId: UUID_B };
+    // Both subjects must have a real key — otherwise this only re-proves the
+    // existing "ciphertext without a key row fails loud" (KeyNotFoundError) case.
+    await kms.createKey(subjectA);
+
+    const storedForB = await encryptPiiValueForSubject(kms, subjectB, "tenant-b-secret", KMS_CTX);
+    const blob = storedForB.slice(storedForB.lastIndexOf(":") + 1);
+    const forgedForA = `${PII_CIPHERTEXT_PREFIX}${subjectIdToKey(subjectA)}:${blob}`;
+
+    const attempt = decryptPiiValueForSubject(kms, forgedForA, KMS_CTX);
+    await expect(attempt).rejects.not.toBeInstanceOf(KeyNotFoundError);
+    await expect(attempt).rejects.not.toBeInstanceOf(KeyErasedError);
+    await expect(attempt).rejects.toThrow();
+  });
+});

package/src/crypto/index.ts

@@ -46,6 +46,7 @@ export {
   configuredPiiSubjectKms,
   configurePiiSubjectKms,
   decryptPiiFieldValues,
+  decryptPiiValueForSubject,
   type EncryptPiiOptions,
   encryptPiiFieldValues,
   encryptPiiValueForSubject,

package/src/crypto/pii-field-encryption.ts

@@ -99,6 +99,25 @@ export async function encryptPiiValueForSubject(
   return encryptValue(subject, dek, value);
 }
 
+// Single-value decrypt for callers that don't have an entity/field-map to
+// pass through decryptPiiFieldValues (config values). The subject lives
+// inside the ciphertext itself, so no subject/scope resolution is needed
+// on this side — only the encrypt direction has to pick one.
+export async function decryptPiiValueForSubject(
+  kms: LocalKeyKmsAdapter,
+  value: string,
+  kmsCtx: KmsContext,
+): Promise<string> {
+  if (!isPiiCiphertext(value)) return value;
+  const { subject, blob } = parseCiphertext(value);
+  try {
+    return decryptValue(await kms.getKey(subject, kmsCtx), blob);
+  } catch (e) {
+    if (!(e instanceof KeyErasedError)) throw e;
+    return PII_ERASED_SENTINEL;
+  }
+}
+
 export interface EncryptPiiOptions {
   readonly onlyKeys?: Iterable<string>;
   // Write-time tenant for tenantOwned fields on rows without a tenantId column.

package/src/db/__tests__/assert-no-unreachable-live-rows.integration.test.ts

@@ -85,6 +85,7 @@ describe("assert-no-unreachable-live-rows / #722 ghost-row guard", () => {
     const result = await rebuildProjection(projectionName, { db: testDb.db, registry });
 
     expect(result.eventsProcessed).toBe(2);
+    expect(result.columnDriftCount).toBe(0);
     expect(await snapshotTable()).toEqual(before);
   });
 
@@ -131,7 +132,10 @@ describe("assert-no-unreachable-live-rows / #722 ghost-row guard", () => {
     );
 
     // No throw — the row is event-backed. Rebuild replays the create event.
-    await rebuildProjection(projectionName, { db: testDb.db, registry });
+    // #916: the direct write IS reported as column drift (non-blocking) —
+    // this is the exact #494 healing case the guard leaves to replay.
+    const result = await rebuildProjection(projectionName, { db: testDb.db, registry });
+    expect(result.columnDriftCount).toBe(1);
 
     const [rebuilt] = await selectMany(testDb.db, userTable, { id: a.data.id as string });
     expect(rebuilt?.["email"]).toBe("a@test.de");
@@ -139,6 +143,28 @@ describe("assert-no-unreachable-live-rows / #722 ghost-row guard", () => {
     expect(rebuilt?.["firstName"]).toBe("Alice");
   });
 
+  test("columnDriftCount reports the TRUE total, not capped at the 20-row sample limit", async () => {
+    const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+    const created = await Promise.all(
+      Array.from({ length: 21 }, (_, i) =>
+        crud.create({ email: `u${i}@test.de`, firstName: `Name${i}` }, adminUser, tdb),
+      ),
+    );
+    for (const c of created) {
+      if (!c.isSuccess) throw new Error("setup failed");
+      await asRawClient(testDb.db).unsafe(
+        `UPDATE read_unreachable_users SET first_name = 'DirectWrite' WHERE id = $1`,
+        [c.data.id],
+      );
+    }
+
+    const result = await rebuildProjection(projectionName, { db: testDb.db, registry });
+
+    // #916: the sample query is LIMITed to 20 rows, but the count must reflect
+    // all 21 — a min(actual, 20) would silently understate severity to ops.
+    expect(result.columnDriftCount).toBe(21);
+  });
+
   test("archived stream (fw#832 tombstone) does NOT trip the guard", async () => {
     // archiveStream never deletes the .created event — projection rebuild
     // deliberately excludes archived streams from replay (fw#832, see

package/src/db/__tests__/blind-index.integration.test.ts

@@ -213,6 +213,22 @@ describe("blind-index rebuild + forget", () => {
     expect(await fetchOne(tdb, personTable, { email: "marc@example.com" })).toBeUndefined();
   });
 
+  test("erased subject → column drift excludes bidx (#916, not counted)", async () => {
+    // Pre-swap, live still holds the OLD bidx hash while the shadow already
+    // computed NULL for the erased subject — a real live-vs-shadow divergence,
+    // but the exact legitimate class countColumnDrift is designed to ignore.
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    await kms.eraseKey({ kind: "user", userId: String(created.data.id) });
+
+    const registry = createRegistry([personFeature]);
+    const result = await rebuildProjection(implicitName, { db: testDb.db, registry });
+
+    expect(result.columnDriftCount).toBe(0);
+    expect((await rawRow(String(created.data.id)))["email_bidx"]).toBeNull();
+  });
+
   test("nullBlindIndexesForSubject nulls bidx immediately (no rebuild needed)", async () => {
     const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
     if (!created.isSuccess) throw new Error("create failed");

package/src/db/__tests__/collect-table-metas.test.ts

@@ -40,13 +40,13 @@ describe("collectTableMetas (#255)", () => {
       // side-effect-only MSP — no table, must be skipped without throwing
       r.multiStreamProjection({ name: "unit-notify", apply: { "unit.created": async () => {} } });
       r.rawTable(
-        "cache",
-        table("unit_cache", {
-          id: uuid("id").primaryKey(),
-        }) as unknown as SchemaTable,
+        defineUnmanagedTable({
+          tableName: "unit_cache",
+          columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true }],
+        }),
         { reason: "test fixture" },
       );
-      r.unmanagedTable(
+      r.rawTable(
         defineUnmanagedTable({
           tableName: "read_unit_log",
           columns: [{ name: "id", pgType: "serial", notNull: true, primaryKey: true }],
@@ -60,7 +60,7 @@ describe("collectTableMetas (#255)", () => {
     expect(names).toContain("read_unit_counters"); // r.projection
     expect(names).toContain("read_unit_audit"); // r.multiStreamProjection
     expect(names).toContain("unit_cache"); // r.rawTable
-    expect(names).toContain("read_unit_log"); // r.unmanagedTable
+    expect(names).toContain("read_unit_log"); // r.rawTable (second registration)
     expect(names).toHaveLength(5);
   });
 

package/src/db/__tests__/event-store-executor.integration.test.ts

@@ -419,6 +419,81 @@ describe("event-store-executor — encrypted fields", () => {
     expect(updated.data.data["secretNote"]).toBe("new-note");
   });
 
+  test("update WITHOUT skipUnchanged still re-encrypts a resubmitted-but-unchanged encrypted field (KEK-rotation/backfill contract)", async () => {
+    // Regression guard: direct executor.update() callers that don't opt into
+    // skipUnchanged rely on today's always-re-encrypt behavior to force a
+    // fresh ciphertext for an unchanged plaintext — e.g. auth-mfa's
+    // KEK-rotation job (reencrypt.job.ts) and the user-data-rights #494
+    // backfill both resubmit the CURRENT value on purpose to land a real
+    // event. A blanket value-diff here would silently break both.
+    const created = await crud.create(
+      { email: "force-enc@test.de", secretNote: "same-note" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const before = (await asRawClient(testDb.db).unsafe(
+      `SELECT secret_note FROM read_es_exec_encrypted WHERE email = 'force-enc@test.de' LIMIT 1`,
+    )) as Array<{ secret_note: string }>;
+
+    const updated = await crud.update(
+      { id: created.data.id, version: 1, changes: { secretNote: "same-note" } },
+      adminUser,
+      tdb,
+    );
+    if (!updated.isSuccess) throw new Error("update failed");
+
+    const after = (await asRawClient(testDb.db).unsafe(
+      `SELECT secret_note FROM read_es_exec_encrypted WHERE email = 'force-enc@test.de' LIMIT 1`,
+    )) as Array<{ secret_note: string }>;
+
+    // Fresh AEAD nonce per encrypt call → different ciphertext even though
+    // the plaintext is identical. Byte-identical would mean the write was
+    // skipped, which is exactly what would break KEK rotation.
+    expect(after[0]?.secret_note).toBeDefined();
+    expect(after[0]?.secret_note).not.toBe(before[0]?.secret_note);
+  });
+
+  test("update with skipUnchanged: true omits a resubmitted-but-unchanged encrypted field — no phantom re-encrypt (#464)", async () => {
+    const created = await crud.create(
+      { email: "noop-enc@test.de", secretNote: "same-note" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const before = (await asRawClient(testDb.db).unsafe(
+      `SELECT secret_note FROM read_es_exec_encrypted WHERE email = 'noop-enc@test.de' LIMIT 1`,
+    )) as Array<{ secret_note: string }>;
+
+    const updated = await crud.update(
+      {
+        id: created.data.id,
+        version: 1,
+        changes: { secretNote: "same-note", email: "noop-enc-2@test.de" },
+      },
+      adminUser,
+      tdb,
+      { skipUnchanged: true },
+    );
+    if (!updated.isSuccess) throw new Error("update failed");
+
+    const after = (await asRawClient(testDb.db).unsafe(
+      `SELECT secret_note FROM read_es_exec_encrypted WHERE email = 'noop-enc-2@test.de' LIMIT 1`,
+    )) as Array<{ secret_note: string }>;
+
+    // Re-encrypting the same plaintext produces a fresh AEAD nonce → a
+    // different ciphertext even for an unchanged value. Byte-identical
+    // ciphertext proves the column was never touched by this update.
+    expect(after[0]?.secret_note).toBe(before[0]?.secret_note);
+
+    const rows = (await asRawClient(testDb.db).unsafe(
+      `SELECT payload FROM kumiko_events WHERE type = 'esExecEncrypted.updated' ORDER BY id DESC LIMIT 1`,
+    )) as Array<{ payload: { changes?: Record<string, unknown> } }>;
+    expect(rows[0]?.payload.changes).not.toHaveProperty("secretNote");
+  });
+
   test("update's persisted event carries ciphertext (not plaintext) for an encrypted field in `previous`", async () => {
     // Regression: `previous` in the STORED event came from loadById(), which
     // decrypts — appending it unchanged would put the plaintext of an

package/src/db/__tests__/feature-table-sources.test.ts

@@ -1,9 +1,9 @@
-// Regression test for #255-class drift: unmanagedTables must appear in
+// Regression test for #255-class drift: rawTables must appear in
 // enumerateFeatureTableSources so setupTestStack's auto-push and
 // collectTableMetas see the exact same table set. Before this fix,
-// unmanagedTables were only handled by collectTableMetas directly, so any
+// unmanaged tables were only handled by collectTableMetas directly, so any
 // app relying on setupTestStack's ephemeral DB (Playwright/e2e) never got
-// its unmanaged tables created — e.g. the bundled "sessions" feature's
+// its raw tables created — e.g. the bundled "sessions" feature's
 // read_user_sessions, breaking every login in an ephemeral test stack.
 
 import { describe, expect, test } from "bun:test";
@@ -16,10 +16,10 @@ const probeMeta = defineUnmanagedTable({
   columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
 });
 
-describe("enumerateFeatureTableSources — unmanagedTables", () => {
-  test("includes a feature's unmanagedTable as a table source", () => {
+describe("enumerateFeatureTableSources — rawTables", () => {
+  test("includes a feature's rawTable as a table source", () => {
     const feature = defineFeature("probe", (r) => {
-      r.unmanagedTable(probeMeta, { reason: "direct-write store" });
+      r.rawTable(probeMeta, { reason: "direct-write store" });
     });
     const sources = enumerateFeatureTableSources(feature);
     const entry = sources.find((s) => s.origin.includes("ftst_probe"));
@@ -27,7 +27,7 @@ describe("enumerateFeatureTableSources — unmanagedTables", () => {
     expect(entry?.table).toBe(probeMeta);
   });
 
-  test("a feature with no unmanagedTable contributes nothing extra", () => {
+  test("a feature with no rawTable contributes nothing extra", () => {
     const feature = defineFeature("plain", () => {});
     expect(enumerateFeatureTableSources(feature)).toEqual([]);
   });