@cosmicdrift/kumiko-framework 0.253.0 → 0.255.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.253.0",
+  "version": "0.255.0",
   "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>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.253.0",
+    "@cosmicdrift/kumiko-types": "0.255.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.253.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.255.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/bun-db/__tests__/run-in-savepoint-if-supported.integration.test.ts

@@ -0,0 +1,47 @@
+// dead-tx-in-afterCommit-hooks: runInSavepointIfSupported must fail
+// loudly on a transaction handle that has already committed, instead of
+// silently re-running `fn` outside the savepoint's isolation. Uses a real
+// Postgres connection — a mock handle can't produce the driver's actual
+// PG 25P01 ("no active sql transaction") on a post-commit savepoint call.
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { InternalError } from "../../errors";
+import { asRawClient, runInSavepointIfSupported } from "../query";
+import { closeDb, getDb } from "./_helpers";
+
+afterAll(async () => {
+  await closeDb();
+});
+
+describe("runInSavepointIfSupported — already-committed transaction", () => {
+  test("throws InternalError naming afterCommit + dbOutsideTransaction, never runs fn", async () => {
+    const db = await getDb();
+    const raw = asRawClient(db);
+
+    let committedTx: unknown;
+    await raw.begin(async (tx) => {
+      committedTx = tx;
+    });
+    // `committedTx` is now a driver handle whose transaction has committed —
+    // it still exposes `.savepoint()`, calling it fails with PG 25P01.
+
+    let fnCalls = 0;
+    const fn = async () => {
+      fnCalls++;
+      return "should-not-run";
+    };
+
+    let caught: unknown;
+    try {
+      await runInSavepointIfSupported(committedTx, fn);
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeInstanceOf(InternalError);
+    const message = (caught as Error).message;
+    expect(message).toContain("afterCommit");
+    expect(message).toContain("dbOutsideTransaction");
+    expect(fnCalls).toBe(0);
+  });
+});

package/src/bun-db/query.ts

@@ -34,6 +34,7 @@ import type { EntityTableMeta } from "../db/entity-table-meta";
 import { extractPgError } from "../db/pg-error";
 import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";
 import { camelCase as envCamelCase } from "../env";
+import { InternalError } from "../errors";
 import { parseJsonSafe } from "../utils/safe-json";
 
 // Idempotent snake_case → camelCase. `env.camelCase` always lowercases first
@@ -145,15 +146,11 @@ export async function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promis
 // and doesn't need one, since each statement there is its own auto-committed
 // unit and a failed statement can't poison anything downstream.
 //
-// `.savepoint` being present isn't proof the transaction is still open: an
-// afterCommit hook closure captures the same handlerContext (and therefore
-// the same TransactionSql-shaped db) that was live during the write, but by
-// the time the hook fires the outer tx has already committed — the object
-// still exposes `.savepoint`, calling it now fails with PG 25P01 ("no
-// active sql transaction") because there's no BEGIN left to nest into. That
-// SAVEPOINT command is the first thing the driver sends, before `fn` runs,
-// so catching 25P01 and retrying directly is safe — nothing from `fn` has
-// executed yet.
+// `.savepoint` being present isn't proof the transaction is still open: a
+// committed TransactionSql-shaped db still exposes `.savepoint`, and calling
+// it fails with PG 25P01 ("no active sql transaction") since there's no
+// BEGIN left to nest into. That is now a programming error, not something
+// to paper over by re-running `fn` without the savepoint's isolation.
 export async function runInSavepointIfSupported<T>(
   db: unknown,
   fn: (sp: DbRunner) => Promise<T>,
@@ -167,7 +164,16 @@ export async function runInSavepointIfSupported<T>(
   try {
     return await raw.savepoint((sp) => fn(asRunner(sp)));
   } catch (e) {
-    if (extractPgError(e)?.code === "25P01") return fn(asRunner(db));
+    if (extractPgError(e)?.code === "25P01") {
+      throw new InternalError({
+        message:
+          "runInSavepointIfSupported: savepoint on a transaction that has already committed — " +
+          "this is almost always database work in an afterCommit hook. afterCommit is the default " +
+          "phase of r.hook/postSave/postDelete. Use HookPhases.inTransaction for writes that must " +
+          "roll back with the trigger, or ctx.dbOutsideTransaction for work that must survive a rollback.",
+        cause: e instanceof Error ? e : undefined,
+      });
+    }
     throw e;
   }
 }

package/src/crypto/__tests__/blind-index.test.ts

@@ -101,6 +101,7 @@ describe("computeBlindIndexValues", () => {
       ["email"],
       kms,
       { requestId: "test" },
+      { entityName: "bidx-user" },
     );
     const out = await computeBlindIndexValues({ email: stored["email"] }, ["email"]);
     expect(out["emailBidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
@@ -116,6 +117,7 @@ describe("computeBlindIndexValues", () => {
       ["email"],
       kms,
       { requestId: "test" },
+      { entityName: "bidx-user" },
     );
     await kms.eraseKey({ kind: "user", userId: UUID_A });
     const out = await computeBlindIndexValues({ email: stored["email"] }, ["email"]);

package/src/crypto/__tests__/event-pii.test.ts

@@ -4,8 +4,10 @@
 // are testable without a database.
 
 import { afterEach, describe, expect, test } from "bun:test";
+import { normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
 import { z } from "zod";
 import { createRegistry, defineFeature } from "../../engine";
+import type { TenantId } from "../../engine/types/identifiers";
 import {
   configuredEventPiiCatalog,
   configureEventPiiCatalog,
@@ -20,6 +22,7 @@ import {
   PII_ERASED_SENTINEL,
   resetPiiSubjectKmsForTests,
 } from "../pii-field-encryption";
+import type { EventSubjectEnvelope } from "../subject-resolver";
 
 const attemptSchema = z.object({
   recipientId: z.string().nullable(),
@@ -29,6 +32,12 @@ const attemptSchema = z.object({
 
 const EVENT_TYPE = "mailer:event:attempt";
 
+const ENVELOPE: EventSubjectEnvelope = {
+  tenantId: "6b2f4a0e-1c9d-4f3a-9d2e-0000000000e1" as TenantId,
+  aggregateType: "mailer-attempt",
+  aggregateId: "6b2f4a0e-1c9d-4f3a-9d2e-0000000000e2",
+};
+
 function catalogWithAttempt(): void {
   configureEventPiiCatalog(
     new Map([[EVENT_TYPE, { recipientAddress: { subjectField: "recipientId" } }]]),
@@ -40,6 +49,19 @@ afterEach(() => {
   resetPiiSubjectKmsForTests();
 });
 
+describe("normalizeEventPiiSubject", () => {
+  test("canonical personal.of and legacy subjectField normalize to the same form", () => {
+    expect(normalizeEventPiiSubject({ personal: { of: "recipientId" } })).toEqual({
+      kind: "user",
+      ownerField: "recipientId",
+    });
+    expect(normalizeEventPiiSubject({ subjectField: "recipientId" })).toEqual({
+      kind: "user",
+      ownerField: "recipientId",
+    });
+  });
+});
+
 describe("defineEvent piiFields validation", () => {
   test("valid piiFields land on the EventDef and in the registry catalog", () => {
     const feature = defineFeature("mailer", (r) => {
@@ -73,14 +95,46 @@ describe("defineEvent piiFields validation", () => {
     ).toThrow(/piiFields references "ownerId"/);
   });
 
-  test("field cannot be its own subjectField", () => {
+  test("field cannot be its own subjectField (legacy form)", () => {
     expect(() =>
       defineFeature("mailer", (r) => {
         r.defineEvent("attempt", attemptSchema, {
           piiFields: { recipientAddress: { subjectField: "recipientAddress" } },
         });
       }),
-    ).toThrow(/cannot use itself as subjectField/);
+    ).toThrow(/cannot use itself as the owner field/);
+  });
+
+  test("valid canonical personal.of piiFields land on the EventDef and in the registry catalog", () => {
+    const feature = defineFeature("mailer", (r) => {
+      r.defineEvent("attempt", attemptSchema, {
+        piiFields: { recipientAddress: { personal: { of: "recipientId" } } },
+      });
+    });
+    createRegistry([feature]);
+    expect(configuredEventPiiCatalog().get(EVENT_TYPE)).toEqual({
+      recipientAddress: { personal: { of: "recipientId" } },
+    });
+  });
+
+  test("unknown owner field throws at definition time (canonical form)", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, {
+          piiFields: { recipientAddress: { personal: { of: "ownerId" } } },
+        });
+      }),
+    ).toThrow(/piiFields references "ownerId"/);
+  });
+
+  test("field cannot be its own owner field (canonical form)", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, {
+          piiFields: { recipientAddress: { personal: { of: "recipientAddress" } } },
+        });
+      }),
+    ).toThrow(/cannot use itself as the owner field/);
   });
 
   test("omitting the options argument throws an explicit PII stance error (fw#2558)", () => {
@@ -112,6 +166,46 @@ describe("defineEvent piiFields validation", () => {
     createRegistry([feature]);
     expect(configuredEventPiiCatalog().has(EVENT_TYPE)).toBe(false);
   });
+
+  test('personal: "tenant" needs only the pii field itself on the schema, no owner field', () => {
+    const feature = defineFeature("mailer", (r) => {
+      r.defineEvent("attempt", attemptSchema, {
+        piiFields: { recipientAddress: { personal: "tenant" } },
+      });
+    });
+    createRegistry([feature]);
+    expect(configuredEventPiiCatalog().get(EVENT_TYPE)).toEqual({
+      recipientAddress: { personal: "tenant" },
+    });
+  });
+
+  test('personal: "self" needs only the pii field itself on the schema, no owner field', () => {
+    const feature = defineFeature("mailer", (r) => {
+      r.defineEvent("attempt", attemptSchema, {
+        piiFields: { recipientAddress: { personal: "self" } },
+      });
+    });
+    createRegistry([feature]);
+    expect(configuredEventPiiCatalog().get(EVENT_TYPE)).toEqual({
+      recipientAddress: { personal: "self" },
+    });
+  });
+
+  test('personal: "tenant" on a field not in the schema throws', () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, { piiFields: { nope: { personal: "tenant" } } });
+      }),
+    ).toThrow(/piiFields references "nope"/);
+  });
+
+  test('personal: "self" on a field not in the schema throws', () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, { piiFields: { nope: { personal: "self" } } });
+      }),
+    ).toThrow(/piiFields references "nope"/);
+  });
 });
 
 describe("encryptEventPayloadPii", () => {
@@ -119,12 +213,12 @@ describe("encryptEventPayloadPii", () => {
 
   test("uncatalogued event type returns the payload untouched (same reference)", async () => {
     configurePiiSubjectKms(new InMemoryKmsAdapter());
-    expect(await encryptEventPayloadPii("other:event:x", payload)).toBe(payload);
+    expect(await encryptEventPayloadPii("other:event:x", payload, ENVELOPE)).toBe(payload);
   });
 
   test("no KMS configured → plaintext passthrough (rollout mode)", async () => {
     catalogWithAttempt();
-    expect(await encryptEventPayloadPii(EVENT_TYPE, payload)).toBe(payload);
+    expect(await encryptEventPayloadPii(EVENT_TYPE, payload, ENVELOPE)).toBe(payload);
   });
 
   test("encrypts under the subject's DEK; subject fk stays plaintext", async () => {
@@ -132,7 +226,7 @@ describe("encryptEventPayloadPii", () => {
     const kms = new InMemoryKmsAdapter();
     configurePiiSubjectKms(kms);
 
-    const out = await encryptEventPayloadPii(EVENT_TYPE, payload);
+    const out = await encryptEventPayloadPii(EVENT_TYPE, payload, ENVELOPE);
     expect(isPiiCiphertext(out["recipientAddress"])).toBe(true);
     expect(String(out["recipientAddress"])).toContain("user:u-1");
     expect(out["recipientId"]).toBe("u-1");
@@ -144,6 +238,23 @@ describe("encryptEventPayloadPii", () => {
     expect(back["recipientAddress"]).toBe("u1@example.com");
   });
 
+  test("legacy subjectField and canonical personal.of encrypt under the same subject key", async () => {
+    const LEGACY_TYPE = "mailer:event:legacy-attempt";
+    const CANONICAL_TYPE = "mailer:event:canonical-attempt";
+    configureEventPiiCatalog(
+      new Map([
+        [LEGACY_TYPE, { recipientAddress: { subjectField: "recipientId" } }],
+        [CANONICAL_TYPE, { recipientAddress: { personal: { of: "recipientId" } } }],
+      ]),
+    );
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+
+    const legacy = await encryptEventPayloadPii(LEGACY_TYPE, payload, ENVELOPE);
+    const canonical = await encryptEventPayloadPii(CANONICAL_TYPE, payload, ENVELOPE);
+    expect(String(legacy["recipientAddress"])).toContain("user:u-1");
+    expect(String(canonical["recipientAddress"])).toContain("user:u-1");
+  });
+
   test("null subject field → value stays plaintext (no user key to shred)", async () => {
     catalogWithAttempt();
     configurePiiSubjectKms(new InMemoryKmsAdapter());
@@ -152,25 +263,25 @@ describe("encryptEventPayloadPii", () => {
       recipientAddress: "ops@example.com",
       status: "sent",
     };
-    expect(await encryptEventPayloadPii(EVENT_TYPE, systemPayload)).toBe(systemPayload);
+    expect(await encryptEventPayloadPii(EVENT_TYPE, systemPayload, ENVELOPE)).toBe(systemPayload);
   });
 
   test("null pii value passes through", async () => {
     catalogWithAttempt();
     configurePiiSubjectKms(new InMemoryKmsAdapter());
     const skipped = { recipientId: "u-1", recipientAddress: null, status: "skipped" };
-    expect(await encryptEventPayloadPii(EVENT_TYPE, skipped)).toBe(skipped);
+    expect(await encryptEventPayloadPii(EVENT_TYPE, skipped, ENVELOPE)).toBe(skipped);
   });
 
   test("idempotent: ciphertext and erased sentinel stay as-is", async () => {
     catalogWithAttempt();
     configurePiiSubjectKms(new InMemoryKmsAdapter());
-    const once = await encryptEventPayloadPii(EVENT_TYPE, payload);
-    const twice = await encryptEventPayloadPii(EVENT_TYPE, once);
+    const once = await encryptEventPayloadPii(EVENT_TYPE, payload, ENVELOPE);
+    const twice = await encryptEventPayloadPii(EVENT_TYPE, once, ENVELOPE);
     expect(twice["recipientAddress"]).toBe(once["recipientAddress"]);
 
     const erased = { ...payload, recipientAddress: PII_ERASED_SENTINEL };
-    const out = await encryptEventPayloadPii(EVENT_TYPE, erased);
+    const out = await encryptEventPayloadPii(EVENT_TYPE, erased, ENVELOPE);
     expect(out["recipientAddress"]).toBe(PII_ERASED_SENTINEL);
   });
 
@@ -178,6 +289,28 @@ describe("encryptEventPayloadPii", () => {
     catalogWithAttempt();
     configurePiiSubjectKms(new InMemoryKmsAdapter());
     const broken = { recipientId: "u-1", recipientAddress: 42, status: "sent" };
-    expect(encryptEventPayloadPii(EVENT_TYPE, broken)).rejects.toThrow(/must be a string/);
+    expect(encryptEventPayloadPii(EVENT_TYPE, broken, ENVELOPE)).rejects.toThrow(
+      /must be a string/,
+    );
+  });
+
+  test('personal: "tenant" encrypts under the envelope tenantId, not a payload field', async () => {
+    configureEventPiiCatalog(new Map([[EVENT_TYPE, { recipientAddress: { personal: "tenant" } }]]));
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+
+    const out = await encryptEventPayloadPii(EVENT_TYPE, payload, ENVELOPE);
+    expect(isPiiCiphertext(out["recipientAddress"])).toBe(true);
+    expect(String(out["recipientAddress"])).toContain(`tenant:${ENVELOPE.tenantId}`);
+  });
+
+  test('personal: "self" encrypts under the envelope aggregateType:aggregateId', async () => {
+    configureEventPiiCatalog(new Map([[EVENT_TYPE, { recipientAddress: { personal: "self" } }]]));
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+
+    const out = await encryptEventPayloadPii(EVENT_TYPE, payload, ENVELOPE);
+    expect(isPiiCiphertext(out["recipientAddress"])).toBe(true);
+    expect(String(out["recipientAddress"])).toContain(
+      `record:${ENVELOPE.aggregateType}:${ENVELOPE.aggregateId}`,
+    );
   });
 });

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

@@ -23,6 +23,7 @@ import { collectPiiSubjectFields } from "../subject-resolver";
 const UUID_A = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000a";
 const UUID_B = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000b";
 const KMS_CTX: KmsContext = { requestId: "test" };
+const ENTITY_NAME = "pii-entity";
 
 const userLikeEntity = createEntity({
   fields: {
@@ -67,7 +68,9 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
     const fields = collectPiiSubjectFields(userLikeEntity);
     const row = { id: UUID_A, email: "marc@example.com", role: "admin" };
 
-    const stored = await encryptPiiFieldValues(row, userLikeEntity, fields, kms, KMS_CTX);
+    const stored = await encryptPiiFieldValues(row, userLikeEntity, fields, kms, KMS_CTX, {
+      entityName: ENTITY_NAME,
+    });
     expect(isPiiCiphertext(stored["email"])).toBe(true);
     expect(String(stored["email"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${UUID_A}:`);
     expect(stored["role"]).toBe("admin");
@@ -88,6 +91,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       ["email"],
       kms,
       KMS_CTX,
+      { entityName: ENTITY_NAME },
     );
     const dek = await kms.getKey({ kind: "user", userId: UUID_A });
     expect(dek.length).toBe(32);
@@ -101,6 +105,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       ["body"],
       kms,
       KMS_CTX,
+      { entityName: ENTITY_NAME },
     );
     expect(String(stored["body"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${UUID_B}:`);
   });
@@ -113,7 +118,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       ["brandColor"],
       kms,
       KMS_CTX,
-      { tenantId: UUID_B },
+      { tenantId: UUID_B, entityName: ENTITY_NAME },
     );
     expect(String(stored["brandColor"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}tenant:${UUID_B}:`);
   });
@@ -124,6 +129,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
     const stored = await encryptPiiFieldValues(changes, commentEntity, ["body"], kms, KMS_CTX, {
       onlyKeys: ["body"],
       subjectSource: { id: UUID_A, body: "edited", authorId: UUID_B },
+      entityName: ENTITY_NAME,
     });
     expect(String(stored["body"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${UUID_B}:`);
   });
@@ -137,13 +143,16 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       fields,
       kms,
       KMS_CTX,
+      { entityName: ENTITY_NAME },
     );
     await kms.eraseKey({ kind: "user", userId: UUID_A });
 
     const read = await decryptPiiFieldValues(stored, fields, kms, KMS_CTX);
     expect(read["email"]).toBe(PII_ERASED_SENTINEL);
 
-    const reStored = await encryptPiiFieldValues(read, userLikeEntity, fields, kms, KMS_CTX);
+    const reStored = await encryptPiiFieldValues(read, userLikeEntity, fields, kms, KMS_CTX, {
+      entityName: ENTITY_NAME,
+    });
     expect(reStored["email"]).toBe(PII_ERASED_SENTINEL);
   });
 
@@ -158,6 +167,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
         ["email"],
         kms,
         KMS_CTX,
+        { entityName: ENTITY_NAME },
       ),
     ).rejects.toThrow(/erased/);
   });
@@ -181,8 +191,11 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       ["email"],
       kms,
       KMS_CTX,
+      { entityName: ENTITY_NAME },
     );
-    const twice = await encryptPiiFieldValues(once, userLikeEntity, ["email"], kms, KMS_CTX);
+    const twice = await encryptPiiFieldValues(once, userLikeEntity, ["email"], kms, KMS_CTX, {
+      entityName: ENTITY_NAME,
+    });
     expect(twice["email"]).toBe(once["email"]);
   });
 
@@ -194,6 +207,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       ["email"],
       kms,
       KMS_CTX,
+      { entityName: ENTITY_NAME },
     );
     expect(stored["email"]).toBeNull();
 
@@ -203,7 +217,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       ["email"],
       kms,
       KMS_CTX,
-      { onlyKeys: ["role"] },
+      { onlyKeys: ["role"], entityName: ENTITY_NAME },
     );
     expect(skipped["email"]).toBe("a@b.c");
   });
@@ -211,7 +225,9 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
   test("non-string pii value throws", async () => {
     const kms = new InMemoryKmsAdapter();
     await expect(
-      encryptPiiFieldValues({ id: UUID_A, email: 42 }, userLikeEntity, ["email"], kms, KMS_CTX),
+      encryptPiiFieldValues({ id: UUID_A, email: 42 }, userLikeEntity, ["email"], kms, KMS_CTX, {
+        entityName: ENTITY_NAME,
+      }),
     ).rejects.toThrow(/must be a string/);
   });
 
@@ -223,6 +239,7 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
       ["email"],
       kmsA,
       KMS_CTX,
+      { entityName: ENTITY_NAME },
     );
     const kmsB = new InMemoryKmsAdapter();
     await expect(decryptPiiFieldValues(stored, ["email"], kmsB, KMS_CTX)).rejects.toBeInstanceOf(
@@ -248,7 +265,9 @@ describe("tenant-owned field encryption (kumiko-platform#457)", () => {
     expect(fields).toEqual(["iban"]);
 
     const row = { id: UUID_A, tenantId: UUID_B, iban: "DE89370400440532013000" };
-    const stored = await encryptPiiFieldValues(row, brandingWithAccess, fields, kms, KMS_CTX);
+    const stored = await encryptPiiFieldValues(row, brandingWithAccess, fields, kms, KMS_CTX, {
+      entityName: ENTITY_NAME,
+    });
     expect(isPiiCiphertext(stored["iban"])).toBe(true);
     expect(String(stored["iban"])).toStartWith(`${PII_CIPHERTEXT_PREFIX}tenant:${UUID_B}:`);
 
@@ -266,7 +285,9 @@ describe("tenant-owned field encryption (kumiko-platform#457)", () => {
     });
     const fields = collectPiiSubjectFields(brandingWithAccess);
     const row = { id: UUID_A, tenantId: UUID_B, iban: "DE89370400440532013000" };
-    const stored = await encryptPiiFieldValues(row, brandingWithAccess, fields, kms, KMS_CTX);
+    const stored = await encryptPiiFieldValues(row, brandingWithAccess, fields, kms, KMS_CTX, {
+      entityName: ENTITY_NAME,
+    });
 
     // Erasure is subject-keyed, not field-flag-keyed — kms.eraseKey doesn't
     // know or care about the field's `personal` annotation, just the subject.

package/src/crypto/__tests__/subject-key-record.test.ts

@@ -56,6 +56,16 @@ describe("record subject key round-trip", () => {
     expect(() => subjectKeyForRecord("bad:name", UUID_A)).toThrow();
   });
 
+  test("subjectKeyForRecord rejects entity names that subjectIdSchema (forget-subject) could never shred (fw#2801)", () => {
+    expect(() => subjectKeyForRecord("v2.digest", UUID_A)).toThrow();
+    expect(() => subjectKeyForRecord("_internal", UUID_A)).toThrow();
+    expect(() => subjectKeyForRecord("3rd", UUID_A)).toThrow();
+  });
+
+  test("subjectKeyForRecord accepts a kebab-case registry entity name", () => {
+    expect(subjectKeyForRecord("mail-account", UUID_A)).toBe(`record:mail-account:${UUID_A}`);
+  });
+
   test("ciphertext round-trip for a record-owned field", async () => {
     const kms = new InMemoryKmsAdapter();
     const fields = collectPiiSubjectFields(recordEntity);
@@ -76,9 +86,9 @@ describe("record subject key round-trip", () => {
 
 describe("resolveSubjectForField: recordOwned fail-closed", () => {
   test("recordOwned field without opts.entityName throws", () => {
-    expect(() => resolveSubjectForField(recordEntity, "body", { id: UUID_A })).toThrow(
-      SubjectResolutionError,
-    );
+    expect(() =>
+      resolveSubjectForField(recordEntity, "body", { id: UUID_A }, { entityName: "" }),
+    ).toThrow(SubjectResolutionError);
   });
 
   test("recordOwned field with row missing id throws", () => {