@cosmicdrift/kumiko-framework 0.253.0 → 0.255.0

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