@cosmicdrift/kumiko-framework 0.254.0 → 0.255.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.254.0",
+  "version": "0.255.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>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.254.0",
+    "@cosmicdrift/kumiko-types": "0.255.1",
     "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.254.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.255.1",
     "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__/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__/subject-id-schema.test.ts

@@ -0,0 +1,60 @@
+// subjectIdSchema is `satisfies z.ZodType<SubjectId>` at the definition site
+// (kms-adapter.ts) — a future 4th SubjectId variant or a renamed field fails
+// to compile there. This file pins the runtime side of that binding: exactly
+// the three SubjectId shapes parse, everything else is refused.
+
+import { describe, expect, test } from "bun:test";
+import { subjectIdSchema } from "../kms-adapter";
+
+const UUID_A = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000a";
+
+describe("subjectIdSchema", () => {
+  test("accepts a user subject", () => {
+    expect(subjectIdSchema.safeParse({ kind: "user", userId: UUID_A }).success).toBe(true);
+  });
+
+  test("accepts a tenant subject", () => {
+    expect(subjectIdSchema.safeParse({ kind: "tenant", tenantId: UUID_A }).success).toBe(true);
+  });
+
+  test("accepts a record subject", () => {
+    expect(
+      subjectIdSchema.safeParse({ kind: "record", entity: "mail-account", id: UUID_A }).success,
+    ).toBe(true);
+  });
+
+  test("mints tenantId as a branded TenantId, not a plain string type", () => {
+    const result = subjectIdSchema.parse({ kind: "tenant", tenantId: UUID_A });
+    expect(result).toEqual({ kind: "tenant", tenantId: UUID_A });
+  });
+
+  test("rejects a non-UUID userId", () => {
+    expect(subjectIdSchema.safeParse({ kind: "user", userId: "not-a-uuid" }).success).toBe(false);
+  });
+
+  test("rejects a non-UUID tenantId", () => {
+    expect(subjectIdSchema.safeParse({ kind: "tenant", tenantId: "not-a-uuid" }).success).toBe(
+      false,
+    );
+  });
+
+  test("rejects a non-UUID record id", () => {
+    expect(
+      subjectIdSchema.safeParse({ kind: "record", entity: "mail-account", id: "not-a-uuid" })
+        .success,
+    ).toBe(false);
+  });
+
+  test("rejects a record entity that violates RECORD_ENTITY_PATTERN", () => {
+    expect(
+      subjectIdSchema.safeParse({ kind: "record", entity: "_internal", id: UUID_A }).success,
+    ).toBe(false);
+    expect(
+      subjectIdSchema.safeParse({ kind: "record", entity: "v2.digest", id: UUID_A }).success,
+    ).toBe(false);
+  });
+
+  test("rejects an unknown subject kind", () => {
+    expect(subjectIdSchema.safeParse({ kind: "bogus", id: UUID_A }).success).toBe(false);
+  });
+});

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);

package/src/crypto/__tests__/subject-resolver.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine/factories";
+import type { TenantId } from "../../engine/types/identifiers";
 import {
   collectPiiSubjectFields,
+  resolveEventSubject,
   resolveSubjectForField,
   SubjectResolutionError,
 } from "../subject-resolver";
@@ -138,3 +140,90 @@ describe("collectPiiSubjectFields", () => {
     expect(collectPiiSubjectFields(brandingEntity)).toEqual(["brandColor"]);
   });
 });
+
+const EVENT_TENANT = "6b2f4a0e-1c9d-4f3a-9d2e-0000000000e1" as TenantId;
+
+describe("resolveEventSubject (fw#2801)", () => {
+  test("personal: { of } → user subject from the named payload field", () => {
+    const subject = resolveEventSubject(
+      "note",
+      { personal: { of: "authorId" } },
+      { authorId: UUID_A },
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "user", userId: UUID_A });
+  });
+
+  test("personal: { of } with a missing owner value → null, no throw (system-triggered event)", () => {
+    const subject = resolveEventSubject(
+      "note",
+      { personal: { of: "authorId" } },
+      { authorId: null },
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toBeNull();
+  });
+
+  test('personal: "tenant" → subject from the envelope tenantId', () => {
+    const subject = resolveEventSubject(
+      "note",
+      { personal: "tenant" },
+      {},
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "tenant", tenantId: EVENT_TENANT });
+  });
+
+  test('personal: "self" → record subject from the envelope aggregateType/aggregateId', () => {
+    const subject = resolveEventSubject(
+      "note",
+      { personal: "self" },
+      {},
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "record", entity: "note", id: UUID_B });
+  });
+
+  test('personal: "tenant" with an empty envelope tenantId throws and names the pii field, not "tenant"', () => {
+    expect(() =>
+      resolveEventSubject(
+        "note",
+        { personal: "tenant" },
+        {},
+        { tenantId: "" as TenantId, aggregateType: "note", aggregateId: UUID_B },
+      ),
+    ).toThrow(/field "note"/);
+  });
+
+  test('personal: "self" with an empty envelope aggregateId throws and names the pii field, not "self"', () => {
+    expect(() =>
+      resolveEventSubject(
+        "note",
+        { personal: "self" },
+        {},
+        { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: "" },
+      ),
+    ).toThrow(/field "note"/);
+  });
+
+  test('personal: "self" with an aggregateType that violates the record-entity pattern throws — mint must never outrun shred (fw#2801)', () => {
+    expect(() =>
+      resolveEventSubject(
+        "note",
+        { personal: "self" },
+        {},
+        { tenantId: EVENT_TENANT, aggregateType: "v2.digest", aggregateId: UUID_B },
+      ),
+    ).toThrow(/field "note".*v2\.digest/s);
+  });
+
+  test("legacy subjectField normalizes to the same user subject as personal: { of }", () => {
+    const subject = resolveEventSubject(
+      "note",
+      { subjectField: "authorId" },
+      { authorId: UUID_A },
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "user", userId: UUID_A });
+  });
+});

package/src/crypto/event-pii.ts

@@ -12,9 +12,10 @@
 // silent no-op (forgetting the option) is now either an explicit "none" or a
 // missing subject KMS at encrypt-time, both visible states, not a gap.
 
+import type { EventPiiFields } from "@cosmicdrift/kumiko-types/handlers";
 import { requestContext } from "../api/request-context";
-import type { EventPiiFields } from "../engine/types/handlers";
 import { configuredPiiSubjectKms, encryptPiiValueForSubject } from "./pii-field-encryption";
+import { type EventSubjectEnvelope, resolveEventSubject } from "./subject-resolver";
 
 export type EventPiiCatalog = ReadonlyMap<string, EventPiiFields>;
 
@@ -35,14 +36,20 @@ export function resetEventPiiCatalogForTests(): void {
   catalog = new Map();
 }
 
-// Encrypts catalogued payload fields under the owning user's DEK. No-op when
-// the event type is uncatalogued or no subject KMS is configured (plaintext
-// rollout mode — the hard boot gate governs whether that is acceptable).
-// A null/absent subject field (system cron runs, recipient-less skip
-// attempts) leaves the value plaintext: there is no user key to shred.
+// Encrypts catalogued payload fields under the declared subject's DEK
+// (user/tenant/self — resolveEventSubject, fw#2801). No-op when the event
+// type is uncatalogued or no subject KMS is configured (plaintext rollout
+// mode — the hard boot gate governs whether that is acceptable). A
+// user-subject field with no resolvable owner (system cron runs,
+// recipient-less skip attempts) leaves the value plaintext: there is no
+// user key to shred. This is the ONLY live-write encrypt path — the backfill
+// catalog branch (`backfill-pii.ts`) resolves through the same
+// resolveEventSubject so a field never ends up encrypted under different
+// subjects depending on which path wrote it.
 export async function encryptEventPayloadPii(
   eventType: string,
   payload: Record<string, unknown>,
+  envelope: EventSubjectEnvelope,
 ): Promise<Record<string, unknown>> {
   const piiFields = catalog.get(eventType);
   if (!piiFields) return payload;
@@ -58,11 +65,11 @@ export async function encryptEventPayloadPii(
         `Event "${eventType}" piiFields."${field}" must be a string payload field, got ${typeof value}`,
       );
     }
-    const subjectId = payload[spec.subjectField];
-    if (typeof subjectId !== "string" || subjectId.length === 0) continue;
+    const subject = resolveEventSubject(field, spec, payload, envelope);
+    if (subject === null) continue;
     const encrypted = await encryptPiiValueForSubject(
       kms,
-      { kind: "user", userId: subjectId },
+      subject,
       value,
       { requestId: requestContext.get()?.requestId ?? "append-event" },
       field,

package/src/crypto/index.ts

@@ -24,12 +24,15 @@ export {
   type KmsContext,
   type KmsHealth,
   type LocalKeyKmsAdapter,
+  RECORD_ENTITY_PATTERN,
   type RemoteCryptoKmsAdapter,
   type SubjectDek,
   type SubjectId,
   type SubjectKey,
   subjectIdFromKey,
+  subjectIdSchema,
   subjectIdToKey,
+  subjectKeyForRecord,
   subjectKeyForTenant,
   subjectKeyForUser,
 } from "./kms-adapter";

package/src/crypto/kms-adapter.ts

@@ -1,10 +1,34 @@
-import { type SubjectId, subjectIdToKey } from "@cosmicdrift/kumiko-types/kms-adapter-types";
+import {
+  RECORD_ENTITY_PATTERN,
+  type SubjectId,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-types/kms-adapter-types";
+import { z } from "zod";
+import type { TenantId } from "../engine/types/identifiers";
 
 export * from "@cosmicdrift/kumiko-types/kms-adapter-types";
 
 // The KMS error classes live here and not in kumiko-types (#1629): callers
 // branch on them with `instanceof`, which needs a single copy of the class.
 
+// `satisfies z.ZodType<SubjectId>` binds this to the TS type at compile time
+// (fw#2801) — mint (subjectKeyForRecord) and shred (forget-subject) can no
+// longer drift apart on which subjects are valid, the way #2809 happened.
+export const subjectIdSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("user"), userId: z.uuid() }),
+  z.object({
+    kind: z.literal("tenant"),
+    // z.uuid() only proves string shape; TenantId is a nominal brand on top
+    // of that, minted here right after validation (@cast-boundary).
+    tenantId: z.uuid().transform((value) => value as TenantId),
+  }),
+  z.object({
+    kind: z.literal("record"),
+    entity: z.string().regex(RECORD_ENTITY_PATTERN),
+    id: z.uuid(),
+  }),
+]) satisfies z.ZodType<SubjectId>;
+
 export class KeyErasedError extends Error {
   constructor(public readonly subject: SubjectId) {
     super(`Subject key erased: ${subjectIdToKey(subject)}`);