@cosmicdrift/kumiko-framework 0.254.0 → 0.255.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.254.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.254.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.254.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__/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-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,14 @@ export {
   type KmsContext,
   type KmsHealth,
   type LocalKeyKmsAdapter,
+  RECORD_ENTITY_PATTERN,
   type RemoteCryptoKmsAdapter,
   type SubjectDek,
   type SubjectId,
   type SubjectKey,
   subjectIdFromKey,
   subjectIdToKey,
+  subjectKeyForRecord,
   subjectKeyForTenant,
   subjectKeyForUser,
 } from "./kms-adapter";

package/src/crypto/subject-resolver.ts

@@ -1,7 +1,8 @@
+import { type EventPiiSubject, normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
 import type { EntityDefinition } from "../engine/types/fields";
 import type { TenantId } from "../engine/types/identifiers";
 import { isSelfPiiField } from "./is-self-pii-field";
-import type { SubjectId } from "./kms-adapter";
+import { RECORD_ENTITY_PATTERN, type SubjectId } from "./kms-adapter";
 
 // Thrown when a field IS pii-annotated but the row can't name its subject —
 // that must surface as an error, not fall back to plaintext.
@@ -125,6 +126,66 @@ export function resolveSubjectForField(
   return null;
 }
 
+// Envelope facts an event's own aggregate stream always carries — unlike a
+// row's tenantId/id columns, these are structural, so a missing/empty value
+// here is a caller bug, not a normal "no subject to shred" case.
+export interface EventSubjectEnvelope {
+  readonly tenantId: TenantId;
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+}
+
+// Same resolver for the live-append path (encryptEventPayloadPii) and the
+// backfill catalog path (backfillEventPiiEncryption) — the reason the two
+// can never encrypt the same field under different subjects. "user" returns
+// null on a missing owner (no key to shred for system-triggered events);
+// "tenant"/"self" throw instead, since their envelope facts are structural.
+export function resolveEventSubject(
+  fieldName: string,
+  spec: EventPiiSubject,
+  payload: Record<string, unknown>,
+  envelope: EventSubjectEnvelope,
+): SubjectId | null {
+  const normalized = normalizeEventPiiSubject(spec);
+
+  if (normalized.kind === "user") {
+    const userId = nonEmptyString(payload[normalized.ownerField]);
+    return userId === null ? null : { kind: "user", userId };
+  }
+
+  if (normalized.kind === "tenant") {
+    if (nonEmptyString(envelope.tenantId) === null) {
+      throw new SubjectResolutionError(fieldName, "event envelope tenantId is empty");
+    }
+    return { kind: "tenant", tenantId: envelope.tenantId };
+  }
+
+  if (normalized.kind === "self") {
+    if (
+      nonEmptyString(envelope.aggregateType) === null ||
+      nonEmptyString(envelope.aggregateId) === null
+    ) {
+      throw new SubjectResolutionError(
+        fieldName,
+        "event envelope aggregateType/aggregateId is empty",
+      );
+    }
+    // aggregate_type is a free-form text column (events-schema.ts) — reject
+    // here rather than mint a record key that subjectIdSchema (forget-
+    // subject.write.ts) would later refuse to shred.
+    if (!RECORD_ENTITY_PATTERN.test(envelope.aggregateType)) {
+      throw new SubjectResolutionError(
+        fieldName,
+        `event aggregateType "${envelope.aggregateType}" does not match ${RECORD_ENTITY_PATTERN} — not a shreddable record subject`,
+      );
+    }
+    return { kind: "record", entity: envelope.aggregateType, id: envelope.aggregateId };
+  }
+
+  const exhaustiveCheck: never = normalized;
+  throw new Error(`Unhandled normalized event PII subject: ${JSON.stringify(exhaustiveCheck)}`);
+}
+
 function hasSubjectAnnotation(field: EntityDefinition["fields"][string]): boolean {
   return (
     ("userOwned" in field && field.userOwned !== undefined) ||

package/src/db/queries/backfill-pii.ts

@@ -11,7 +11,8 @@
 //     same collectPiiSubjectFields/resolveSubjectForField the live write
 //     path uses
 //   - custom events from the event-PII catalog (r.defineEvent piiFields) —
-//     user-subject only, see the note at its call site (fw#2801)
+//     user/tenant/self subjects, via the same resolveEventSubject the live
+//     append path uses (fw#2801)
 //
 // Already-forgotten subjects must NOT get a fresh key minted for their old
 // plaintext — three erased-detection layers write [[erased]] instead:
@@ -59,6 +60,7 @@ import {
 } from "../../crypto/pii-field-encryption";
 import {
   collectPiiSubjectFields,
+  resolveEventSubject,
   resolveSubjectForField,
   SubjectResolutionError,
 } from "../../crypto/subject-resolver";
@@ -284,11 +286,13 @@ export async function backfillEventPiiEncryption(
     const catalogFields = eventCatalog.get(row.type);
     if (catalogFields) {
       for (const [field, spec] of Object.entries(catalogFields)) {
-        const subjectId = payload[spec.subjectField];
-        if (typeof subjectId !== "string" || subjectId.length === 0) continue;
-        // Catalog entries only ever resolve a user subject — a tenant/record
-        // subject in a custom event is not backfillable today (fw#2801).
-        const outcome = await encryptField(payload, field, { kind: "user", userId: subjectId });
+        const subject = resolveEventSubject(field, spec, payload, {
+          tenantId: row.tenant_id as TenantId, // @cast-boundary db-read — tenant_id column is the branded TenantId
+          aggregateType: row.aggregate_type,
+          aggregateId: row.aggregate_id,
+        });
+        if (subject === null) continue;
+        const outcome = await encryptField(payload, field, subject);
         bump(outcome);
       }
     } else {

package/src/engine/__tests__/projection-detail-tabs.test.ts

@@ -132,6 +132,37 @@ describe("validateBoot — projectionDetail tabs (fw record-layout)", () => {
     expect(() => validateBoot([feature])).toThrow(/metric "balance" has no entry in fieldLabels/);
   });
 
+  test("object-form metric with its own label needs no fieldLabels entry", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("rent:detail", z.object({}), async () => ({ description: "x" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        metrics: [{ field: "balance", label: "rent.balance" }],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("object-form metric with neither its own label nor a fieldLabels entry throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        metrics: [{ field: "balance" }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /metric "balance" has no entry in fieldLabels and no own "label"/,
+    );
+  });
+
   test("valid tabs + header + metrics declaration boots cleanly", () => {
     const feature = defineFeature("app", (r) => {
       r.queryHandler("rent:detail", z.object({}), async () => ({ description: "x" }), {
@@ -142,8 +173,8 @@ describe("validateBoot — projectionDetail tabs (fw record-layout)", () => {
         type: "projectionDetail",
         query: "app:query:rent:detail",
         header: { title: "name", subtitle: "address", status: "state" },
-        metrics: ["balance", "overdueDays"],
-        fieldLabels: { balance: "rent.balance", overdueDays: "rent.overdueDays" },
+        metrics: ["balance", { field: "overdueDays", label: "rent.overdueDays" }],
+        fieldLabels: { balance: "rent.balance" },
         layout: {
           mode: "tabs",
           sections: [

package/src/engine/boot-validator/query-output-columns.ts

@@ -12,6 +12,7 @@ import type {
   QueryHandlerDef,
   ScreenDefinition,
 } from "../types";
+import { metricField } from "../types";
 import { buildQueryHandlerMap } from "./projection-list-screens";
 import { getZodObjectShape, getZodRowShape } from "./zod-shape";
 
@@ -130,11 +131,12 @@ function checkProjectionDetailOutputFields(
     if (screen.header.status !== undefined) checkHeaderField("status", screen.header.status);
   }
   for (const metric of screen.metrics ?? []) {
+    const field = metricField(metric);
     checkFieldExists(
       recordShape,
-      metric,
+      field,
       () =>
-        `${prefix} metrics references field "${metric}" which is not present in query "${screen.query}"'s outputSchema.`,
+        `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`,
     );
   }
 }

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

@@ -16,6 +16,7 @@ import {
   normalizeListColumn,
 } from "../screen-helpers";
 import type { EntityDefinition, FeatureDefinition } from "../types";
+import { metricField } from "../types";
 import type {
   DashboardCustomPanel,
   DashboardFilterDefinition,
@@ -697,11 +698,13 @@ export function validateScreens(
       }
       if (screen.metrics !== undefined) {
         for (const metric of screen.metrics) {
-          if (screen.fieldLabels?.[metric] === undefined) {
+          const field = metricField(metric);
+          const hasOwnLabel = typeof metric !== "string" && metric.label !== undefined;
+          if (!hasOwnLabel && screen.fieldLabels?.[field] === undefined) {
             throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) metric "${metric}" has ` +
-                `no entry in fieldLabels — every metrics field needs a label, there is no fallback to ` +
-                `the raw column name.`,
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) metric "${field}" has ` +
+                `no entry in fieldLabels and no own "label" — every metrics field needs one of the two, ` +
+                `there is no fallback to the raw column name.`,
             );
           }
         }

package/src/engine/feature-config-events-jobs.ts

@@ -1,3 +1,4 @@
+import { normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
 import { ZodObject, type ZodType, type z } from "zod";
 import type { FeatureBuilderState } from "./feature-builder-state";
 import { resolveName } from "./handler-helpers";
@@ -96,7 +97,7 @@ export function buildConfigEventsJobsMethods<TName extends string>(
   }
 
   // piiFields misconfiguration is a boot-time error, not a silent
-  // plaintext leak: both the pii field and its subjectField must exist
+  // plaintext leak: both the pii field and its owner field must exist
   // on the payload schema (checkable when the schema is a ZodObject).
   function validateEventPiiFields(
     eventName: string,
@@ -105,12 +106,24 @@ export function buildConfigEventsJobsMethods<TName extends string>(
   ): void {
     const shape = schema instanceof ZodObject ? schema.shape : undefined;
     for (const [field, spec] of Object.entries(piiFields)) {
-      if (field === spec.subjectField) {
+      const normalized = normalizeEventPiiSubject(spec);
+      // Only the user form names an owner field — tenant/self subjects come
+      // from the write-time envelope (tenantId / aggregateType+aggregateId),
+      // so there is no owner-field existence or self-reference check for them.
+      if (normalized.kind !== "user") {
+        if (shape && !(field in shape)) {
+          throw new Error(
+            `[Feature ${name}] defineEvent("${eventName}"): piiFields references "${field}" which is not a field of the payload schema.`,
+          );
+        }
+        continue;
+      }
+      if (field === normalized.ownerField) {
         throw new Error(
-          `[Feature ${name}] defineEvent("${eventName}"): piiFields."${field}" cannot use itself as subjectField — the subject id is a plaintext pseudonymous fk, the pii field is the value it owns.`,
+          `[Feature ${name}] defineEvent("${eventName}"): piiFields."${field}" cannot use itself as the owner field — the subject id is a plaintext pseudonymous fk, the pii field is the value it owns.`,
         );
       }
-      for (const required of [field, spec.subjectField]) {
+      for (const required of [field, normalized.ownerField]) {
         if (shape && !(required in shape)) {
           throw new Error(
             `[Feature ${name}] defineEvent("${eventName}"): piiFields references "${required}" which is not a field of the payload schema.`,
@@ -238,7 +251,7 @@ export function buildConfigEventsJobsMethods<TName extends string>(
       // an event without declaring whether its payload carries personal data.
       const missingStanceError = () =>
         new Error(
-          `[Feature ${name}] defineEvent("${eventName}") must declare an explicit PII stance. Pass { piiFields: { <payloadField>: { subjectField: "<userIdField>" } } } for payload fields holding personal data, or { piiFields: "none" } when the payload holds none.`,
+          `[Feature ${name}] defineEvent("${eventName}") must declare an explicit PII stance. Pass { piiFields: { <payloadField>: { personal: { of: "<userIdField>" } } } } for payload fields owned by a user (or { personal: "tenant" } / { personal: "self" } for tenant- or record-scoped subjects), or { piiFields: "none" } when the payload holds none.`,
         );
       if (options === undefined || options.piiFields === undefined) {
         throw missingStanceError();

package/src/engine/index.ts

@@ -390,6 +390,8 @@ export type {
   ListSortSpec,
   LongTextFindability,
   ManyToManyRelation,
+  MetricNavigate,
+  MetricSpec,
   MspErrorMode,
   MspErrorPolicy,
   MultiSelectFieldDef,

package/src/engine/types/index.ts

@@ -292,6 +292,8 @@ export type {
   ListPaginationMode,
   ListSortDir,
   ListSortSpec,
+  MetricNavigate,
+  MetricSpec,
   PlatformComponent,
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
@@ -311,6 +313,7 @@ export type {
   ToolbarAction,
   UnitKey,
 } from "@cosmicdrift/kumiko-types/screen";
+export { metricField } from "@cosmicdrift/kumiko-types/screen";
 export type { TargetRef } from "@cosmicdrift/kumiko-types/target-ref";
 export type {
   Subscribe,

package/src/engine/types/screen.ts

@@ -1,2 +1,3 @@
 // Legacy path — re-exported for callers still importing this module directly.
 export type * from "@cosmicdrift/kumiko-types/screen";
+export { metricField } from "@cosmicdrift/kumiko-types/screen";

package/src/event-store/__tests__/backfill-pii.integration.test.ts

@@ -51,12 +51,31 @@ const crmFeature = defineFeature("crm", (r) => {
   r.entity("contact", contactEntity);
 });
 
+// Qualified event-type strings are kebab-case (qn/toKebab, feature-config-
+// events-jobs.ts) — captured from defineEvent's own return value instead of
+// hand-written, so a camelCase event name (tenantNote → tenant-note) can
+// never drift from what the catalog is actually keyed by (fw#2801).
+let PING_EVENT_TYPE: string;
 const mailerFeature = defineFeature("mailer", (r) => {
-  r.defineEvent(
+  PING_EVENT_TYPE = r.defineEvent(
     "ping",
     z.object({ targetId: z.string().nullable(), address: z.string().nullable() }),
     { piiFields: { address: { subjectField: "targetId" } } },
-  );
+  ).name;
+});
+
+// fw#2801 step 2: custom events declaring a tenant/self subject — no entity,
+// pure catalog events — proving the catalog branch resolves through the
+// same resolveEventSubject the live append path uses.
+let TENANT_NOTE_EVENT_TYPE: string;
+let SELF_NOTE_EVENT_TYPE: string;
+const signalsFeature = defineFeature("signals", (r) => {
+  TENANT_NOTE_EVENT_TYPE = r.defineEvent("tenantNote", z.object({ note: z.string().nullable() }), {
+    piiFields: { note: { personal: "tenant" } },
+  }).name;
+  SELF_NOTE_EVENT_TYPE = r.defineEvent("selfNote", z.object({ note: z.string().nullable() }), {
+    piiFields: { note: { personal: "self" } },
+  }).name;
 });
 
 // personal: { of } (not "self") — the named owner field can legitimately be
@@ -111,7 +130,13 @@ async function appendPlain(
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  registry = createRegistry([crmFeature, mailerFeature, notesFeature, surveyFeature]);
+  registry = createRegistry([
+    crmFeature,
+    mailerFeature,
+    notesFeature,
+    surveyFeature,
+    signalsFeature,
+  ]);
   await createEventsTable(testDb.db);
   await unsafeCreateEntityTable(testDb.db, contactEntity, "contact");
   await unsafeCreateEntityTable(testDb.db, noteEntity, "note");
@@ -220,15 +245,15 @@ describe("backfillEventPiiEncryption", () => {
     const p1 = generateId();
     const p2 = generateId();
     const p3 = generateId();
-    await appendPlain(p1, "ping", "mailer:event:ping", {
+    await appendPlain(p1, "ping", PING_EVENT_TYPE, {
       targetId: "u-7",
       address: "u7@x.com",
     });
-    await appendPlain(p2, "ping", "mailer:event:ping", {
+    await appendPlain(p2, "ping", PING_EVENT_TYPE, {
       targetId: forgottenUser,
       address: "f@x.com",
     });
-    await appendPlain(p3, "ping", "mailer:event:ping", { targetId: null, address: "ops@x.com" });
+    await appendPlain(p3, "ping", PING_EVENT_TYPE, { targetId: null, address: "ops@x.com" });
 
     armKms();
     const result = await backfillEventPiiEncryption(testDb.db, registry);
@@ -386,7 +411,7 @@ describe("backfillEventPiiEncryption", () => {
 
   test("dryRun over a catalogued custom event mints no key for its payload-resolved subject", async () => {
     const p1 = generateId();
-    await appendPlain(p1, "ping", "mailer:event:ping", {
+    await appendPlain(p1, "ping", PING_EVENT_TYPE, {
       targetId: "u-7",
       address: "u7@x.com",
     });
@@ -730,3 +755,104 @@ describe("backfillEventPiiEncryption: raw jsonb column type (fw#2253)", () => {
     expect(rows[0]?.t).toBe("object");
   });
 });
+
+// The security-critical invariant this PR exists for: a catalogued field
+// must resolve to the IDENTICAL subject key whether it was encrypted at
+// live-append time or re-encrypted by the backfill — both paths now go
+// through the same resolveEventSubject (subject-resolver.ts). If they ever
+// diverged, an Art. 17 erase of one subject key would leave the same field's
+// other-path ciphertext readable under a different key.
+describe("backfillEventPiiEncryption: catalog subject kinds match live append (fw#2801)", () => {
+  test("user subject: backfill and live append encrypt under the same subject key", async () => {
+    const preKmsId = generateId();
+    await appendPlain(preKmsId, "ping", PING_EVENT_TYPE, {
+      targetId: "u-42",
+      address: "pre-kms@x.com",
+    });
+
+    armKms();
+    const liveId = generateId();
+    await append(testDb.db, {
+      aggregateId: liveId,
+      aggregateType: "ping",
+      tenantId: TENANT,
+      expectedVersion: 0,
+      type: PING_EVENT_TYPE,
+      payload: { targetId: "u-42", address: "live@x.com" },
+      metadata: { userId: "system" },
+    });
+
+    await backfillEventPiiEncryption(testDb.db, registry);
+
+    const backfilled = (await loadAggregate(testDb.db, preKmsId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    const live = (await loadAggregate(testDb.db, liveId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(String(backfilled["address"])).toContain("user:u-42");
+    expect(String(live["address"])).toContain("user:u-42");
+  });
+
+  test("tenant subject: backfill and live append encrypt under the same subject key", async () => {
+    const preKmsId = generateId();
+    await appendPlain(preKmsId, "signal", TENANT_NOTE_EVENT_TYPE, { note: "pre-kms" });
+
+    armKms();
+    const liveId = generateId();
+    await append(testDb.db, {
+      aggregateId: liveId,
+      aggregateType: "signal",
+      tenantId: TENANT,
+      expectedVersion: 0,
+      type: TENANT_NOTE_EVENT_TYPE,
+      payload: { note: "live" },
+      metadata: { userId: "system" },
+    });
+
+    await backfillEventPiiEncryption(testDb.db, registry);
+
+    const backfilled = (await loadAggregate(testDb.db, preKmsId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    const live = (await loadAggregate(testDb.db, liveId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(String(backfilled["note"])).toContain(`tenant:${TENANT}`);
+    expect(String(live["note"])).toContain(`tenant:${TENANT}`);
+  });
+
+  test("self (record) subject: backfill and live append encrypt each under its own aggregate's key", async () => {
+    const preKmsId = generateId();
+    await appendPlain(preKmsId, "signal", SELF_NOTE_EVENT_TYPE, { note: "pre-kms" });
+
+    armKms();
+    const liveId = generateId();
+    await append(testDb.db, {
+      aggregateId: liveId,
+      aggregateType: "signal",
+      tenantId: TENANT,
+      expectedVersion: 0,
+      type: SELF_NOTE_EVENT_TYPE,
+      payload: { note: "live" },
+      metadata: { userId: "system" },
+    });
+
+    await backfillEventPiiEncryption(testDb.db, registry);
+
+    const backfilled = (await loadAggregate(testDb.db, preKmsId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    const live = (await loadAggregate(testDb.db, liveId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(String(backfilled["note"])).toContain(`record:signal:${preKmsId}`);
+    expect(String(live["note"])).toContain(`record:signal:${liveId}`);
+  });
+});

package/src/event-store/event-store.ts

@@ -78,7 +78,11 @@ export const EVENTS_PUBSUB_CHANNEL = "kumiko_events_new";
 export async function append(db: DbRunner, event: EventToAppend): Promise<StoredEvent> {
   // Event-PII (#799): stored payload AND returned echo carry ciphertext, so
   // inline projections and rebuilds materialize identical rows.
-  const payload = await encryptEventPayloadPii(event.type, event.payload);
+  const payload = await encryptEventPayloadPii(event.type, event.payload, {
+    tenantId: event.tenantId,
+    aggregateType: event.aggregateType,
+    aggregateId: event.aggregateId,
+  });
   const toStore = payload === event.payload ? event : { ...event, payload };
   const newVersion = toStore.expectedVersion + 1;
   const eventVersion = toStore.eventVersion ?? 1;

package/src/pipeline/__tests__/ctx-bridge.integration.test.ts

@@ -10,7 +10,9 @@ import {
   createSystemUser,
   createTextField,
   defineFeature,
+  HookPhases,
 } from "../../engine";
+import type { HandlerContext } from "../../engine/types";
 import { UnprocessableError, writeFailure } from "../../errors";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 
@@ -44,14 +46,32 @@ const secretEntity = createEntity({
 });
 const secretTable = buildEntityTable("secret", secretEntity);
 
+// Target entity for the afterCommit-hook-writes-a-second-entity test below
+// (dead-tx-in-afterCommit-hooks). Plain Admin access — kept separate
+// from `secret` so that test doesn't entangle with the privileged-access
+// assertions the other describe blocks make about it.
+const echoEntity = createEntity({
+  table: "ctx_echoes",
+  fields: {
+    bagId: createTextField({ required: true }),
+  },
+});
+const echoTable = buildEntityTable("echo", echoEntity);
+
 let stack: TestStack;
 const admin = TestUsers.admin;
 
 const afterCommitLog: string[] = [];
 
+// Toggled per-test so the afterCommit hook only writes echo rows for
+// the test that exercises it — reset in beforeEach.
+let afterCommitHookShouldEchoBag = false;
+const echoedBagIds: string[] = [];
+
 const bridgeFeature = defineFeature("ctxbridge", (r) => {
   const bag = r.entity("bag", bagEntity);
   const secret = r.entity("secret", secretEntity);
+  r.entity("echo", echoEntity);
 
   r.writeHandler(
     "bag:create",
@@ -182,11 +202,45 @@ const bridgeFeature = defineFeature("ctxbridge", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
+  r.writeHandler(
+    "echo:create",
+    z.object({ bagId: z.string() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(echoTable, echoEntity, {
+        entityName: "echo",
+      });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   // afterCommit hook on bag — fires once per outer commit.
   r.hook("postSave", { allOf: bag }, async (result) => {
     afterCommitLog.push(`bag:${result.data["label"]}`);
   });
 
+  // afterCommit hook on bag that writes a SECOND entity via ctx.write,
+  // going through the real event-store append path (crud.create ->
+  // runInSavepointIfSupported). Proves the afterCommit context's ctx.db
+  // is a live, usable handle rather than the already-committed tx
+  // (dead-tx-in-afterCommit-hooks). Explicit phase so the test says
+  // what it means, even though afterCommit is already the default.
+  r.hook(
+    "postSave",
+    { allOf: bag },
+    async (result, ctx) => {
+      if (!afterCommitHookShouldEchoBag) return;
+      const bagId = String(result.id);
+      // Hooks are typed against AppContext (no bridge), but the runtime
+      // object is always the full HandlerContext — see the comment on
+      // AppContext in @cosmicdrift/kumiko-types/handlers. @cast-boundary
+      const handlerCtx = ctx as unknown as HandlerContext;
+      const echoRes = await handlerCtx.write("ctxbridge:write:echo:create", { bagId });
+      if (echoRes.isSuccess) echoedBagIds.push(bagId);
+    },
+    { phase: HookPhases.afterCommit },
+  );
+
   // afterCommit hook on secret — the entity targeted by the nested writeAs.
   // Proves: (a) hook fires exactly once per successful writeAs, (b) hook
   // does NOT fire when the outer transaction rolls back.
@@ -199,6 +253,7 @@ beforeAll(async () => {
   stack = await setupTestStack({ features: [bridgeFeature] });
   await unsafeCreateEntityTable(stack.db, bagEntity);
   await unsafeCreateEntityTable(stack.db, secretEntity);
+  await unsafeCreateEntityTable(stack.db, echoEntity);
 });
 
 afterAll(async () => {
@@ -207,8 +262,11 @@ afterAll(async () => {
 
 beforeEach(async () => {
   afterCommitLog.length = 0;
+  afterCommitHookShouldEchoBag = false;
+  echoedBagIds.length = 0;
   await asRawClient(stack.db).unsafe(`DELETE FROM "${bagTable.tableName}"`);
   await asRawClient(stack.db).unsafe(`DELETE FROM "${secretTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${echoTable.tableName}"`);
   // Clear the event-dedup cache — tests re-use entity ids (Postgres sequences
   // reset, each test sees id=1). Without flushing Redis the second test hits
   // a dedup hit on the same handler:id:version:phase key and the hook is
@@ -331,3 +389,24 @@ describe("ctx.dbOutsideTransaction", () => {
     expect(labels).toEqual(["signal-probe-outside-tx"]);
   });
 });
+
+describe("afterCommit hook context is usable for real DB work", () => {
+  test("a postSave afterCommit hook can write a second entity via ctx.write", async () => {
+    afterCommitHookShouldEchoBag = true;
+
+    const res = await stack.http.write("ctxbridge:write:bag:create", { label: "echo-me" }, admin);
+    expect((await res.json()).isSuccess).toBe(true);
+
+    // The effect, not just "no throw": afterCommit hook errors are caught
+    // and logged by the framework (dispatch-batch.ts flushAfterCommit), so
+    // a broken hook still returns a 200 here. What proves the fix is that
+    // the hook's ctx.write actually landed a row through the event-store
+    // append path.
+    expect(echoedBagIds).toHaveLength(1);
+    const [expectedBagId] = echoedBagIds;
+    if (!expectedBagId) throw new Error("echoedBagIds[0] missing");
+    const echoes = await selectMany(stack.db, echoTable);
+    expect(echoes).toHaveLength(1);
+    expect((echoes[0] as { bagId: string }).bagId).toBe(expectedBagId);
+  });
+});

package/src/pipeline/dispatch-write.ts

@@ -116,12 +116,15 @@ function invalidateTenantTimezoneCache(
 // Runs lifecycle hooks for a handler result. inTransaction hooks fire NOW
 // (they see the tx via ctx.db when batch/write opens a transaction).
 // afterCommit hooks are queued into `afterCommitHooks` for the caller to
-// flush after commit.
+// flush after commit. Their context is built lazily, without `tx`: by the
+// time they fire the transaction has already committed, so `handlerContext`
+// (built around it) would hand them a dead handle.
 async function runLifecycle(
   ctx: DispatchContext,
   type: string,
   data: unknown,
   handlerContext: HandlerContext,
+  user: SessionUser,
   afterCommitHooks: AfterCommitHook[],
 ): Promise<void> {
   const { lifecycle } = ctx;
@@ -143,15 +146,29 @@ async function runLifecycle(
 
   if (result.kind === "save") {
     await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
-    afterCommitHooks.push(() =>
-      lifecycle.runPostSave(type, result, handlerContext, HookPhases.afterCommit),
-    );
+    afterCommitHooks.push(async () => {
+      const afterCommitContext = await buildHandlerContext(
+        ctx,
+        type,
+        user,
+        undefined,
+        afterCommitHooks,
+      );
+      await lifecycle.runPostSave(type, result, afterCommitContext, HookPhases.afterCommit);
+    });
   } else if (result.kind === "delete") {
     await lifecycle.runPreDelete(type, result, handlerContext);
     await lifecycle.runPostDelete(type, result, handlerContext, HookPhases.inTransaction);
-    afterCommitHooks.push(() =>
-      lifecycle.runPostDelete(type, result, handlerContext, HookPhases.afterCommit),
-    );
+    afterCommitHooks.push(async () => {
+      const afterCommitContext = await buildHandlerContext(
+        ctx,
+        type,
+        user,
+        undefined,
+        afterCommitHooks,
+      );
+      await lifecycle.runPostDelete(type, result, afterCommitContext, HookPhases.afterCommit);
+    });
   }
 }
 
@@ -159,8 +176,9 @@ async function runLifecycle(
 // Used by runBatch (which opens a transaction and flushes afterCommitHooks on commit).
 //
 // Contract:
-//   - `tx` is the active Drizzle transaction handle (or undefined for the no-DB
-//     fallback path used by tests without a Postgres connection).
+//   - `tx` is the active Drizzle transaction handle, or undefined for "no
+//     surrounding transaction" — either no Postgres is configured, or the
+//     transaction already committed (afterCommit phase).
 //   - `afterCommitHooks` collects deferred side-effects that must only fire
 //     after the transaction commits. The caller flushes them on commit, drops
 //     them on rollback. executeWrite never fires them directly.
@@ -479,7 +497,7 @@ async function executeWriteInner(
 
   if (result.isSuccess) {
     try {
-      await runLifecycle(ctx, type, result.data, handlerContext, afterCommitHooks);
+      await runLifecycle(ctx, type, result.data, handlerContext, user, afterCommitHooks);
     } catch (e) {
       return writeFailure(wrapToKumiko(e));
     }

package/src/ui-types/index.ts

@@ -86,6 +86,8 @@ export type {
   ListColumnSpec,
   ListFacetSpec,
   ListSortSpec,
+  MetricNavigate,
+  MetricSpec,
   PlatformComponent,
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
@@ -102,6 +104,7 @@ export type {
   SecretsEditSection,
   ToolbarAction,
 } from "../engine/types/screen";
+export { metricField } from "../engine/types/screen";
 export type { TargetRef } from "../engine/types/target-ref";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node";
 export type { WorkspaceDefinition } from "../engine/types/workspace";