@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/data-retention/run-retention-cleanup.ts

@@ -9,13 +9,17 @@
 //   - hardDelete  → executor.forget pro Row (Event → rebuild-safe hard purge)
 //   - softDelete  → executor.delete pro Row (Event → rebuild-safe soft-delete),
 //                   nur auf noch-nicht-geloeschte (isDeleted:false-Filter)
-//   - anonymize   → DEFERRED (siehe unten)
+//   - anonymize   → executor.update pro Row mit den Werten der per-Feld
+//                   anonymize-Funktionen; Row bleibt (fields.ts-Contract)
+//   - blockDelete → waehrend keepFor unangetastet (Aufbewahrungs-Pflicht;
+//                   user-forget loest anonymize aus). NACH Ablauf laufen die
+//                   anonymize-Funktionen — Geschaeftsdaten bleiben, Personen-
+//                   Bezug raus (fields.ts:44-47).
 //
 // Über den Executor statt Batch-deleteMany/updateMany: ein eventloser Batch-Write
 // auf die (erased) Projektions-Tabelle wird beim Projection-Rebuild
 // gewischt/resurrektiert — das #648-Loch. Kosten: N Events pro Cleanup statt ein
 // Batch-Statement (per-Row-Ceiling, Batch-Event-Variante als Follow-up).
-//   - blockDelete → ignoriert (Aufbewahrungs-Pflicht; user-forget loest anonymize)
 //
 // **Schaerfer als soft-delete-cleanup:** dieser Cron hardDeleted LIVE Rows
 // (keyed auf reference, Default createdAt), nicht bereits-soft-geloeschte.
@@ -23,12 +27,12 @@
 // reference-Spalte wuerde sonst ein malformed/all-matching WHERE ergeben und
 // pauschal loeschen.
 //
-// **anonymize deferred:** anonymize behaelt die Row. Ohne Idempotenz-Marker
-// wuerde der taegliche UPDATE jede past-cutoff Row endlos neu treffen — genau
-// der Full-Table-Scan den die Strategie vermeiden soll (hardDelete begrenzt
-// sich selbst, softDelete via isDeleted:false). Kein bundled-Entity nutzt
-// zeitgesteuertes anonymize; der user-forget-Flow (run-forget-cleanup) deckt
-// anonymize keyed auf userId ab. Follow-up fuer den Marker.
+// **anonymize-Idempotenz ohne Marker-Spalte:** die anonymize-Funktionen sind
+// row-unabhaengig (`() => unknown`) — einmal pro Entity ausgewertet ergeben
+// sie die Ziel-Werte. Eine Row die sie schon traegt wird uebersprungen, der
+// taegliche Re-Lauf appended also null Events. Der WHERE matcht anonymisierte
+// Rows weiter (reference bleibt alt), deshalb id-Cursor-Paging statt einer
+// einzelnen Page — sonst verstopfen erledigte Rows das batchLimit-Fenster.
 
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
@@ -76,15 +80,18 @@ export interface RunRetentionCleanupArgs {
 
 export interface RetentionCleanupSkip {
   readonly entityName: string;
-  readonly reason: "missing_reference_column" | "missing_softdelete_columns";
+  readonly reason:
+    | "missing_reference_column"
+    | "missing_softdelete_columns"
+    | "missing_anonymize_fields";
 }
 
 export interface RunRetentionCleanupResult {
   readonly hardDeleted: number;
   readonly softDeleted: number;
-  /** Entities mit anonymize-Strategy — deferred (Header). Cron logt sie. */
-  readonly anonymizeDeferred: readonly string[];
-  /** Anomalien: Policy referenziert eine Spalte die die Tabelle nicht hat. */
+  /** Rows deren anonymize-Feld-Funktionen angewendet wurden (anonymize + abgelaufene blockDelete). */
+  readonly anonymized: number;
+  /** Anomalien: Policy referenziert eine Spalte die die Tabelle nicht hat, oder anonymize ohne anonymize-Felder. */
   readonly skipped: readonly RetentionCleanupSkip[];
 }
 
@@ -106,6 +113,65 @@ async function purgeMatchingRows(
   return count;
 }
 
+// PiiAnnotations.anonymize — structural view, avoids reaching into the
+// engine's field-type internals from here.
+type AnonymizeCapableField = { readonly anonymize?: () => unknown | Promise<unknown> };
+
+// Evaluate the entity's per-field anonymize functions ONCE — they are
+// row-independent by signature, so the result doubles as the idempotency
+// probe: a row already carrying these values needs no event.
+async function resolveAnonymizeTargets(
+  fields: Readonly<Record<string, unknown>>,
+): Promise<Record<string, unknown> | null> {
+  const targets: Record<string, unknown> = {};
+  for (const [name, field] of Object.entries(fields)) {
+    const annot = field as AnonymizeCapableField; // @cast-boundary schema-walk
+    if (typeof annot.anonymize === "function") targets[name] = await annot.anonymize();
+  }
+  return Object.keys(targets).length > 0 ? targets : null;
+}
+
+function rowNeedsAnonymize(
+  row: Record<string, unknown>,
+  targets: Record<string, unknown>,
+): boolean {
+  return Object.entries(targets).some(([field, value]) => row[field] !== value);
+}
+
+// Anonymize every matching row via the executor (event → rebuild-safe).
+// id-Cursor-paged because the where keeps matching already-anonymized rows;
+// the diff-check keeps the daily re-run event-free. batchLimit bounds the
+// UPDATES per run, not the scan.
+// ponytail: scans all past-cutoff rows per run — add an anonymized-marker
+// column if a hot entity accumulates millions of held rows.
+async function anonymizeMatchingRows(
+  db: DbRunner,
+  table: Parameters<typeof selectMany>[1],
+  where: WhereObject,
+  batchLimit: number,
+  targets: Record<string, unknown>,
+  op: (id: EntityId, changes: Record<string, unknown>) => Promise<{ readonly isSuccess: boolean }>,
+): Promise<number> {
+  let count = 0;
+  let cursor: EntityId | null = null;
+  while (count < batchLimit) {
+    const pageWhere: WhereObject = cursor === null ? where : { ...where, id: { gt: cursor } };
+    const rows = await selectMany<Record<string, unknown>>(db, table, pageWhere, {
+      limit: batchLimit,
+      orderBy: { col: "id" },
+    });
+    if (rows.length === 0) break;
+    for (const row of rows) {
+      cursor = row["id"] as EntityId; // @cast-boundary db-row
+      if (!rowNeedsAnonymize(row, targets)) continue;
+      const res = await op(cursor, targets);
+      if (res.isSuccess) count++;
+      if (count >= batchLimit) break;
+    }
+  }
+  return count;
+}
+
 export async function runRetentionCleanup(
   args: RunRetentionCleanupArgs,
 ): Promise<RunRetentionCleanupResult> {
@@ -114,7 +180,7 @@ export async function runRetentionCleanup(
 
   let hardDeleted = 0;
   let softDeleted = 0;
-  const anonymizeDeferred: string[] = [];
+  let anonymized = 0;
   const skipped: RetentionCleanupSkip[] = [];
 
   // Retention writes go through the executor (events) so a projection rebuild
@@ -198,16 +264,33 @@ export async function runRetentionCleanup(
         );
         break;
       }
-      case "anonymize": {
-        anonymizeDeferred.push(entityName);
-        break;
-      }
+      // blockDelete = Legal-Hold: rows stay untouched during keepFor (the
+      // cutoff-WHERE guarantees that), user-forget anonymizes instead of
+      // deleting (run-forget-cleanup maps blockDelete → anonymize). AFTER the
+      // hold expires the anonymize-field functions run — business data stays,
+      // the person link goes (fields.ts contract). Same executor path as the
+      // anonymize strategy, so both cases share it.
+      case "anonymize":
       case "blockDelete": {
-        // skip: Aufbewahrungs-Pflicht — Cleanup ignoriert, user-forget anonymisiert
+        const targets = await resolveAnonymizeTargets(entity.fields);
+        if (!targets) {
+          skipped.push({ entityName, reason: "missing_anonymize_fields" });
+          break;
+        }
+        const executor = createEventStoreExecutor(proj.table, entity, { entityName });
+        anonymized += await anonymizeMatchingRows(
+          db,
+          proj.table,
+          where,
+          batchLimit,
+          targets,
+          (id, changes) =>
+            executor.update({ id, changes }, systemUser, tdb, { skipOptimisticLock: true }),
+        );
         break;
       }
     }
   }
 
-  return { hardDeleted, softDeleted, anonymizeDeferred, skipped };
+  return { hardDeleted, softDeleted, anonymized, skipped };
 }

package/src/delivery/__tests__/delivery-pii-kms.integration.test.ts

@@ -0,0 +1,171 @@
+// Delivery-attempt log under KMS (#799): recipientAddress is written via
+// LOW-LEVEL append() in attempt-log.ts — the event-PII catalog must cover
+// it. Stored event + projected row carry ciphertext under the recipient's
+// DEK, the outgoing mail still reaches the PLAINTEXT address, the admin
+// log.query decrypts for display, and erasing the recipient's key flips
+// the log entry to [[erased]] without touching the append-only stream.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  defineFeature,
+  defineWriteHandler,
+  type NotifyFn,
+  qn,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import { createChannelEmailFeature } from "../../channel-email/feature";
+import { createInMemoryTransport } from "../../channel-email/types";
+import { createConfigFeature } from "../../config/feature";
+import { configValuesTable } from "../../config/table";
+import { createRendererFoundationFeature } from "../../renderer-foundation/feature";
+import { createRendererSimpleFeature } from "../../renderer-simple/feature";
+import { simpleRenderer } from "../../renderer-simple/simple-renderer";
+import { createTemplateResolverFeature } from "../../template-resolver/feature";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { DELIVERY_ATTEMPT_EVENT } from "../constants";
+import { createDeliveryFeature } from "../feature";
+import { deliveryAttemptsTable, notificationPreferencesTable } from "../tables";
+import { createDeliveryTestContext } from "../testing";
+
+const emailTransport = createInMemoryTransport();
+const testEmail = (userId: string | number) => `user-${userId}@test.com`;
+
+const admin = TestUsers.admin;
+const recipient = createTestUser({ id: 7, roles: ["User"] });
+
+const appFeature = defineFeature("app", (r) => {
+  r.requires("delivery");
+
+  r.writeHandler(
+    defineWriteHandler({
+      name: "ping",
+      schema: z.object({ toUserId: z.string() }),
+      handler: async (event, ctx) => {
+        const notify = ctx.notify as NotifyFn;
+        await notify(qn("app", "notify", "pinged"), {
+          to: event.payload.toUserId,
+          data: { title: "Ping", body: "Du wurdest angepingt" },
+        });
+        return { isSuccess: true, data: { sent: true } };
+      },
+      access: { openToAll: true },
+    }),
+  );
+});
+
+let stack: TestStack;
+let kms: InMemoryKmsAdapter;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createTemplateResolverFeature(),
+      createRendererFoundationFeature(),
+      createDeliveryFeature(),
+      createRendererSimpleFeature(),
+      createChannelEmailFeature({
+        transport: emailTransport,
+        renderer: simpleRenderer,
+        resolveEmail: async (userId) => testEmail(userId),
+      }),
+      appFeature,
+    ],
+    extraContext: (deps) => createDeliveryTestContext(deps),
+  });
+
+  await unsafePushTables(stack.db, {
+    configValuesTable,
+    tenantMembershipsTable,
+    notificationPreferencesTable,
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+// ONE kms for the whole file: rows persist across tests, so a fresh adapter
+// per test would orphan earlier ciphertext (decrypt fails loud on KeyNotFound).
+beforeEach(() => {
+  kms ??= new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+  emailTransport.sent.length = 0;
+});
+
+afterAll(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+async function pingRecipient(): Promise<void> {
+  await stack.http.writeOk(qn("app", "write", "ping"), { toUserId: recipient.id }, admin);
+}
+
+describe("delivery attempt log under KMS", () => {
+  test("mail goes to the plaintext address; event + row store ciphertext", async () => {
+    await pingRecipient();
+
+    expect(emailTransport.sent.length).toBe(1);
+    expect(emailTransport.sent[0]?.to).toBe(testEmail(recipient.id));
+
+    const events = await selectMany(stack.db, eventsTable, { type: DELIVERY_ATTEMPT_EVENT });
+    const sent = events
+      .map((e) => e.payload as Record<string, unknown>)
+      .find((p) => p["channel"] === "email" && p["status"] === "sent");
+    expect(sent).toBeDefined();
+    expect(isPiiCiphertext(sent?.["recipientAddress"])).toBe(true);
+    expect(String(sent?.["recipientAddress"])).toContain(`user:${recipient.id}`);
+    expect(sent?.["recipientId"]).toBe(recipient.id);
+
+    const rows = await selectMany(stack.db, deliveryAttemptsTable, {
+      recipientId: recipient.id,
+      channel: "email",
+    });
+    expect(rows.length).toBeGreaterThan(0);
+    expect(isPiiCiphertext(rows[0]?.["recipientAddress"])).toBe(true);
+  });
+
+  test("admin log.query decrypts for display; after key-erase it shows [[erased]]", async () => {
+    await pingRecipient();
+
+    const before = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "delivery:query:log",
+      { limit: 100 },
+      admin,
+    );
+    const entry = before.rows.find(
+      (r) => r["recipientId"] === recipient.id && r["channel"] === "email",
+    );
+    expect(entry?.["recipientAddress"]).toBe(testEmail(recipient.id));
+
+    await kms.eraseKey({ kind: "user", userId: recipient.id });
+
+    const after = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "delivery:query:log",
+      { limit: 100 },
+      admin,
+    );
+    const erased = after.rows.find(
+      (r) => r["recipientId"] === recipient.id && r["channel"] === "email",
+    );
+    expect(erased?.["recipientAddress"]).toBe(PII_ERASED_SENTINEL);
+  });
+});

package/src/delivery/__tests__/delivery-screens.boot.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { access, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
+import { DELIVERY_LOG_SCREEN_ID } from "../constants";
+import { createDeliveryFeature } from "../feature";
+
+describe("delivery screens + handler access alignment", () => {
+  const features = [createDeliveryFeature()];
+
+  test("boot-validates with delivery-log screen registered", () => {
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("delivery-log screen is custom, access.admin-gated", () => {
+    const delivery = createDeliveryFeature();
+    const screen = delivery.screens[DELIVERY_LOG_SCREEN_ID];
+    expect(screen?.type).toBe("custom");
+    if (screen && "access" in screen && screen.access && "roles" in screen.access) {
+      expect(screen.access.roles).toEqual(access.admin);
+    }
+  });
+
+  test("delivery log handler shares access.admin", () => {
+    const delivery = createDeliveryFeature();
+    expect(rolesOf(delivery.queryHandlers["log"]?.access)).toEqual([...access.admin]);
+  });
+});

package/src/delivery/__tests__/delivery-security.integration.test.ts

@@ -0,0 +1,106 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { insertMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { access, createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
+import { DELIVERY_LOG_SCREEN_ID, DeliveryQueries } from "../constants";
+import { createDeliveryFeature } from "../feature";
+import { deliveryAttemptsTable, notificationPreferencesTable } from "../tables";
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createDeliveryFeature()],
+  });
+  await unsafePushTables(stack.db, { deliveryAttemptsTable, notificationPreferencesTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("delivery access matrix", () => {
+  test("delivery log handler and screen share access.admin", () => {
+    const registry = createRegistry([createDeliveryFeature()]);
+    expect(rolesOf(registry.getQueryHandler(DeliveryQueries.log)?.access)).toEqual([
+      ...access.admin,
+    ]);
+    const delivery = createDeliveryFeature();
+    const screen = delivery.screens[DELIVERY_LOG_SCREEN_ID];
+    if (screen && "access" in screen && screen.access && "roles" in screen.access) {
+      expect(screen.access.roles).toEqual(access.admin);
+    }
+  });
+});
+
+describe("delivery log HTTP access", () => {
+  test("TenantAdmin can query delivery log", async () => {
+    const user = createTestUser({ id: 11, roles: ["TenantAdmin"] });
+    const res = await stack.http.queryOk<{ rows: readonly unknown[] }>(
+      DeliveryQueries.log,
+      {},
+      user,
+    );
+    expect(Array.isArray(res.rows)).toBe(true);
+  });
+
+  test("historic Admin can query delivery log", async () => {
+    const user = createTestUser({ id: 12, roles: ["Admin"] });
+    const res = await stack.http.queryOk<{ rows: readonly unknown[] }>(
+      DeliveryQueries.log,
+      {},
+      user,
+    );
+    expect(Array.isArray(res.rows)).toBe(true);
+  });
+
+  test("regular User gets 403", async () => {
+    const user = createTestUser({ id: 13, roles: ["User"] });
+    expect((await stack.http.query(DeliveryQueries.log, {}, user)).status).toBe(403);
+  });
+});
+
+describe("delivery log tenant isolation", () => {
+  // delivery runs in system-scope, so the handler must filter by tenantId —
+  // otherwise a TenantAdmin reads every tenant's attempts (with decrypted PII).
+  test("TenantAdmin only sees their own tenant's delivery attempts", async () => {
+    const tenantA = testTenantId(1); // createTestUser default tenant
+    const tenantB = testTenantId(2);
+    await insertMany(stack.db, deliveryAttemptsTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: tenantA,
+        notificationType: "welcome",
+        channel: "email",
+        recipientAddress: null,
+        status: "sent",
+      },
+      {
+        id: crypto.randomUUID(),
+        tenantId: tenantB,
+        notificationType: "welcome",
+        channel: "email",
+        recipientAddress: null,
+        status: "sent",
+      },
+    ]);
+
+    const adminA = createTestUser({ id: 21, roles: ["TenantAdmin"], tenantId: tenantA });
+    const res = await stack.http.queryOk<{ rows: readonly { tenantId: string }[] }>(
+      DeliveryQueries.log,
+      {},
+      adminA,
+    );
+
+    expect(res.rows.length).toBeGreaterThan(0);
+    expect(res.rows.every((r) => r.tenantId === tenantA)).toBe(true);
+    expect(res.rows.some((r) => r.tenantId === tenantB)).toBe(false);
+  });
+});

package/src/delivery/constants.ts

@@ -1,8 +1,18 @@
 import type { NotifyPriority } from "@cosmicdrift/kumiko-framework/engine";
 import { QnTypes, qn } from "@cosmicdrift/kumiko-framework/engine";
-
-// Feature name
-export const DELIVERY_FEATURE = "delivery" as const;
+import { DELIVERY_FEATURE, DeliveryJobNames } from "./public-names";
+
+export {
+  DELIVERY_ATTEMPT_EVENT,
+  DELIVERY_FEATURE,
+  DELIVERY_LOG_SCREEN_ID,
+  DeliveryErrors,
+  DeliveryHandlers,
+  DeliveryJobNames,
+  DeliveryQueries,
+  DeliveryStatus,
+  type DeliveryStatusValue,
+} from "./public-names";
 
 // notify() priority → BullMQ job priority. Lower number = processed first; all
 // > 0 so prioritised delivery jobs never mix with BullMQ's "0 = unprioritised
@@ -13,54 +23,6 @@ export const deliveryPriorityRank: Record<NotifyPriority, number> = {
   low: 3,
 };
 
-// Qualified write handler names (QN format: scope:type:name)
-export const DeliveryHandlers = {
-  setPreference: "delivery:write:set-preference",
-} as const;
-
-// Qualified query handler names (QN format: scope:type:name)
-export const DeliveryQueries = {
-  log: "delivery:query:log",
-  preferences: "delivery:query:preferences",
-} as const;
-
-// Error codes
-export const DeliveryErrors = {
-  noRecipient: "delivery_no_recipient",
-  channelFailed: "delivery_channel_failed",
-} as const;
-
-// Delivery status values. `queued` is the initial state of an async attempt
-// (email/push) between dispatch and the worker running — it transitions to
-// sent/failed once the delivery.send job finishes. Synchronous attempts
-// (inApp, skips) never observe `queued`.
-export const DeliveryStatus = {
-  queued: "queued",
-  sent: "sent",
-  failed: "failed",
-  skipped: "skipped",
-} as const;
-
-export type DeliveryStatusValue = (typeof DeliveryStatus)[keyof typeof DeliveryStatus];
-
-// Qualified domain-event name. Emitted by the delivery-service on every
-// attempt (sent / failed / skipped). A multi-stream-projection materialises
-// each event into a row in deliveryAttemptsTable for the log-query handler.
-export const DELIVERY_ATTEMPT_EVENT = "delivery:event:attempt" as const;
-
-// Background jobs that carry async (queued-mode) channels. render decouples the
-// expensive template step from the send so each retries independently; render
-// dispatches send on success. Channels without a render() (push) skip straight
-// to send.
-//
-// Short names are what r.job() registers; the registry qualifies them to
-// `scope:job:name`. Dispatch (notify + render→send chaining) must use the
-// QUALIFIED name, so DeliveryJobs holds the qualified form via qn().
-export const DeliveryJobNames = {
-  render: "render",
-  send: "send",
-} as const;
-
 export const DeliveryJobs = {
   render: qn(DELIVERY_FEATURE, QnTypes.job, DeliveryJobNames.render),
   send: qn(DELIVERY_FEATURE, QnTypes.job, DeliveryJobNames.send),

package/src/delivery/feature.ts

@@ -1,11 +1,16 @@
 import { upsertByPk } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  access,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
 import type { z } from "zod";
-import { DELIVERY_ATTEMPT_EVENT, DeliveryJobNames } from "./constants";
+import { DELIVERY_ATTEMPT_EVENT, DELIVERY_LOG_SCREEN_ID, DeliveryJobNames } from "./constants";
 import { deliveryAttemptSchema } from "./events";
 import { logQuery } from "./handlers/log.query";
 import { preferencesQuery } from "./handlers/preferences.query";
 import { setPreferenceWrite } from "./handlers/set-preference.write";
+import { DELIVERY_I18N } from "./i18n";
 import { deliveryRenderJob, deliverySendJob } from "./jobs";
 import {
   deliveryAttemptsTable,
@@ -17,7 +22,7 @@ import {
 export function createDeliveryFeature(): FeatureDefinition {
   return defineFeature("delivery", (r) => {
     r.describe(
-      "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, logs every attempt to `read_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything.",
+      "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything.",
     );
     r.uiHints({
       displayLabel: "Notifications \u00b7 Dispatch Core",
@@ -31,7 +36,7 @@ export function createDeliveryFeature(): FeatureDefinition {
     r.entity("notification-preference", notificationPreferenceEntity, {
       table: notificationPreferencesTable,
     });
-    r.unmanagedTable(deliveryAttemptsTableMeta, {
+    r.storeTable(deliveryAttemptsTableMeta, {
       reason: "read_side.delivery_attempt_log",
     });
 
@@ -40,7 +45,11 @@ export function createDeliveryFeature(): FeatureDefinition {
     // attempt is a fresh stream, no CRUD lifecycle. Framework's
     // boot-validator accepts the projection below because at least one
     // apply-key is a registered domain-event (DELIVERY_ATTEMPT_EVENT).
-    r.defineEvent("attempt", deliveryAttemptSchema);
+    // recipientAddress is the real PII (email address); recipientId stays
+    // plaintext — pseudonymous fk, same line as config.userId (#821).
+    r.defineEvent("attempt", deliveryAttemptSchema, {
+      piiFields: { recipientAddress: { subjectField: "recipientId" } },
+    });
 
     // Inline projection that materialises every delivery attempt into
     // deliveryAttemptsTable. Runs in the SAME transaction as the low-level
@@ -113,6 +122,21 @@ export function createDeliveryFeature(): FeatureDefinition {
       preferences: r.queryHandler(preferencesQuery),
     };
 
+    r.screen({
+      id: DELIVERY_LOG_SCREEN_ID,
+      type: "custom",
+      renderer: { react: { __component: "DeliveryLogScreen" } },
+      access: { roles: access.admin },
+    });
+    r.nav({
+      id: "delivery-log",
+      label: "delivery:nav.deliveryLog",
+      screen: "delivery:screen:delivery-log",
+      order: 40,
+    });
+
+    r.translations({ keys: DELIVERY_I18N });
+
     return { handlers, queries };
   });
 }

package/src/delivery/handlers/log.query.ts

@@ -1,6 +1,7 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { decryptStoredPii } from "../../shared";
 import { deliveryAttemptsTable } from "../tables";
 
 export const logQuery = defineQueryHandler({
@@ -8,12 +9,32 @@ export const logQuery = defineQueryHandler({
   schema: z.object({
     limit: z.number().min(1).max(100).default(50),
   }),
-  access: { roles: ["Admin", "SystemAdmin"] },
+  access: { roles: access.admin },
   handler: async (query, ctx) => {
-    const rows = await selectMany(ctx.db, deliveryAttemptsTable, undefined, {
-      orderBy: { col: "createdAt", direction: "desc" },
-      limit: query.payload.limit,
-    });
-    return { rows };
+    // delivery runs in system-scope (feature.ts r.systemScope()), so ctx.db is
+    // NOT auto-tenant-filtered — filter explicitly or a tenant admin reads every
+    // tenant's attempts (with decrypted recipient PII below).
+    const rows = await selectMany(
+      ctx.db,
+      deliveryAttemptsTable,
+      { tenantId: query.user.tenantId },
+      {
+        orderBy: { col: "createdAt", direction: "desc" },
+        limit: query.payload.limit,
+      },
+    );
+    // recipientAddress is stored encrypted under the recipient's DEK (#799)
+    // — decrypt for the admin log view; forgotten subjects show [[erased]].
+    return {
+      rows: await Promise.all(
+        rows.map(async (row) => ({
+          ...row,
+          recipientAddress:
+            typeof row["recipientAddress"] === "string"
+              ? await decryptStoredPii(row["recipientAddress"], "recipientAddress", "delivery-log")
+              : row["recipientAddress"],
+        })),
+      ),
+    };
   },
 });