@cosmicdrift/kumiko-framework 0.254.0 → 0.255.1

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 (kms-adapter.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/__tests__/record-owned.test.ts

@@ -1,9 +1,8 @@
 // fw#2809 — a recordOwned field is encrypted under `record:<entity>:<id>`
-// (kms-adapter-types.ts) and forgetSubject's subjectIdSchema validates that
-// id as a UUID (crypto-shredding/handlers/forget-subject.write.ts). An
-// idType: "serial" entity would encrypt such a field but could never satisfy
-// a forget-subject request for it — the boot guard catches that combination
-// before it ships.
+// (kms-adapter-types.ts) and forgetSubject's subjectIdSchema (crypto/kms-adapter.ts)
+// validates that id as a UUID. An idType: "serial" entity would encrypt such
+// a field but could never satisfy a forget-subject request for it — the boot
+// guard catches that combination before it ships.
 
 import { describe, expect, test } from "bun:test";
 import { defineFeature } from "../../define-feature";

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/record-owned.ts

@@ -2,10 +2,9 @@ import type { FeatureDefinition } from "../types";
 import type { ResolvedPiiFlags } from "../types/fields";
 
 // A recordOwned field is encrypted under `record:<entity>:<id>` (kms-adapter-types.ts)
-// and forgetSubject's subjectIdSchema requires that id to be a UUID
-// (crypto-shredding/handlers/forget-subject.write.ts) — an entity with
-// idType: "serial" would encrypt the field but could never satisfy a
-// forget-subject request for it.
+// and forgetSubject's subjectIdSchema (crypto/kms-adapter.ts) requires that id
+// to be a UUID — an entity with idType: "serial" would encrypt the field but
+// could never satisfy a forget-subject request for it.
 export function validateRecordOwnedSubjects(feature: FeatureDefinition): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     if (entity.idType !== "serial") continue;

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: 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);
+  });
+});