@cosmicdrift/kumiko-framework 0.119.0 → 0.120.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.119.0",
+  "version": "0.120.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>",
@@ -185,7 +185,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.119.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.120.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/crypto/__tests__/event-pii.test.ts

@@ -0,0 +1,161 @@
+// Event-PII catalog (#799): defineEvent({ piiFields }) → createRegistry
+// publishes the catalog → encryptEventPayloadPii encrypts under the owning
+// user's DEK. append() applies this on every write path; the pure pieces
+// are testable without a database.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { createRegistry, defineFeature } from "../../engine";
+import {
+  configuredEventPiiCatalog,
+  configureEventPiiCatalog,
+  encryptEventPayloadPii,
+  resetEventPiiCatalogForTests,
+} from "../event-pii";
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import {
+  configurePiiSubjectKms,
+  decryptPiiFieldValues,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+  resetPiiSubjectKmsForTests,
+} from "../pii-field-encryption";
+
+const attemptSchema = z.object({
+  recipientId: z.string().nullable(),
+  recipientAddress: z.string().nullable(),
+  status: z.string(),
+});
+
+const EVENT_TYPE = "mailer:event:attempt";
+
+function catalogWithAttempt(): void {
+  configureEventPiiCatalog(
+    new Map([[EVENT_TYPE, { recipientAddress: { subjectField: "recipientId" } }]]),
+  );
+}
+
+afterEach(() => {
+  resetEventPiiCatalogForTests();
+  resetPiiSubjectKmsForTests();
+});
+
+describe("defineEvent piiFields validation", () => {
+  test("valid piiFields land on the EventDef and in the registry catalog", () => {
+    const feature = defineFeature("mailer", (r) => {
+      r.defineEvent("attempt", attemptSchema, {
+        piiFields: { recipientAddress: { subjectField: "recipientId" } },
+      });
+    });
+    createRegistry([feature]);
+    expect(configuredEventPiiCatalog().get(EVENT_TYPE)).toEqual({
+      recipientAddress: { subjectField: "recipientId" },
+    });
+  });
+
+  test("pii field not on the payload schema throws at definition time", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, {
+          piiFields: { nope: { subjectField: "recipientId" } },
+        });
+      }),
+    ).toThrow(/piiFields references "nope"/);
+  });
+
+  test("unknown subjectField throws at definition time", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, {
+          piiFields: { recipientAddress: { subjectField: "ownerId" } },
+        });
+      }),
+    ).toThrow(/piiFields references "ownerId"/);
+  });
+
+  test("field cannot be its own subjectField", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, {
+          piiFields: { recipientAddress: { subjectField: "recipientAddress" } },
+        });
+      }),
+    ).toThrow(/cannot use itself as subjectField/);
+  });
+
+  test("events without piiFields do not enter the catalog", () => {
+    const feature = defineFeature("mailer", (r) => {
+      r.defineEvent("attempt", attemptSchema);
+    });
+    createRegistry([feature]);
+    expect(configuredEventPiiCatalog().size).toBe(0);
+  });
+});
+
+describe("encryptEventPayloadPii", () => {
+  const payload = { recipientId: "u-1", recipientAddress: "u1@example.com", status: "sent" };
+
+  test("uncatalogued event type returns the payload untouched (same reference)", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    expect(await encryptEventPayloadPii("other:event:x", payload)).toBe(payload);
+  });
+
+  test("no KMS configured → plaintext passthrough (rollout mode)", async () => {
+    catalogWithAttempt();
+    expect(await encryptEventPayloadPii(EVENT_TYPE, payload)).toBe(payload);
+  });
+
+  test("encrypts under the subject's DEK; subject fk stays plaintext", async () => {
+    catalogWithAttempt();
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+
+    const out = await encryptEventPayloadPii(EVENT_TYPE, payload);
+    expect(isPiiCiphertext(out["recipientAddress"])).toBe(true);
+    expect(String(out["recipientAddress"])).toContain("user:u-1");
+    expect(out["recipientId"]).toBe("u-1");
+    expect(out["status"]).toBe("sent");
+
+    const back = await decryptPiiFieldValues(out, ["recipientAddress"], kms, {
+      requestId: "test",
+    });
+    expect(back["recipientAddress"]).toBe("u1@example.com");
+  });
+
+  test("null subject field → value stays plaintext (no user key to shred)", async () => {
+    catalogWithAttempt();
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const systemPayload = {
+      recipientId: null,
+      recipientAddress: "ops@example.com",
+      status: "sent",
+    };
+    expect(await encryptEventPayloadPii(EVENT_TYPE, systemPayload)).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);
+  });
+
+  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);
+    expect(twice["recipientAddress"]).toBe(once["recipientAddress"]);
+
+    const erased = { ...payload, recipientAddress: PII_ERASED_SENTINEL };
+    const out = await encryptEventPayloadPii(EVENT_TYPE, erased);
+    expect(out["recipientAddress"]).toBe(PII_ERASED_SENTINEL);
+  });
+
+  test("non-string pii value is a loud error, not a silent skip", async () => {
+    catalogWithAttempt();
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const broken = { recipientId: "u-1", recipientAddress: 42, status: "sent" };
+    expect(encryptEventPayloadPii(EVENT_TYPE, broken)).rejects.toThrow(/must be a string/);
+  });
+});

package/src/crypto/event-pii.ts

@@ -0,0 +1,69 @@
+// PII on custom-event payloads (#799). Entity CRUD events get their PII
+// encrypted by the executor; events written via ctx.appendEvent / MSP-apply /
+// low-level append() (delivery attempt-log, jobs run-logger) had no encrypt
+// path at all. `r.defineEvent(name, schema, { piiFields })` declares which
+// payload fields are PII and which payload field names the owning user;
+// createRegistry publishes the catalog and append() — the single write funnel
+// into kumiko_events — encrypts every catalogued field. No caller can forget.
+
+import { requestContext } from "../api/request-context";
+import type { EventPiiFields } from "../engine/types/handlers";
+import { configuredPiiSubjectKms, encryptPiiValueForSubject } from "./pii-field-encryption";
+
+export type EventPiiCatalog = ReadonlyMap<string, EventPiiFields>;
+
+// Boot-injected like configurePiiSubjectKms — createRegistry calls this with
+// the catalog collected from all defineEvent registrations.
+let catalog: EventPiiCatalog = new Map();
+
+export function configureEventPiiCatalog(next: EventPiiCatalog): void {
+  catalog = next;
+}
+
+export function configuredEventPiiCatalog(): EventPiiCatalog {
+  return catalog;
+}
+
+/** @internal test-only */
+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.
+export async function encryptEventPayloadPii(
+  eventType: string,
+  payload: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const piiFields = catalog.get(eventType);
+  if (!piiFields) return payload;
+  const kms = configuredPiiSubjectKms();
+  if (!kms) return payload;
+
+  let out: Record<string, unknown> | undefined;
+  for (const [field, spec] of Object.entries(piiFields)) {
+    const value = payload[field];
+    if (value === null || value === undefined) continue;
+    if (typeof value !== "string") {
+      throw new Error(
+        `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 encrypted = await encryptPiiValueForSubject(
+      kms,
+      { kind: "user", userId: subjectId },
+      value,
+      { requestId: requestContext.get()?.requestId ?? "append-event" },
+    );
+    if (encrypted !== value) {
+      out ??= { ...payload };
+      out[field] = encrypted;
+    }
+  }
+  return out ?? payload;
+}

package/src/crypto/index.ts

@@ -8,6 +8,13 @@ export {
   decodeBlindIndexKey,
   resetBlindIndexKeyForTests,
 } from "./blind-index";
+export {
+  configuredEventPiiCatalog,
+  configureEventPiiCatalog,
+  type EventPiiCatalog,
+  encryptEventPayloadPii,
+  resetEventPiiCatalogForTests,
+} from "./event-pii";
 export { InMemoryKmsAdapter } from "./in-memory-kms-adapter";
 export {
   isLocalKeyKmsAdapter,
@@ -38,6 +45,7 @@ export {
   decryptPiiFieldValues,
   type EncryptPiiOptions,
   encryptPiiFieldValues,
+  encryptPiiValueForSubject,
   isPiiCiphertext,
   PII_CIPHERTEXT_PREFIX,
   PII_ERASED_SENTINEL,

package/src/crypto/pii-field-encryption.ts

@@ -85,6 +85,20 @@ async function getOrCreateDek(
   return kms.getKey(subject, ctx);
 }
 
+// Single-value encrypt for callers that resolve the subject themselves
+// (event-pii catalog, backfill). Ciphertext/sentinel inputs pass through —
+// idempotent like the field-map variant.
+export async function encryptPiiValueForSubject(
+  kms: LocalKeyKmsAdapter,
+  subject: SubjectId,
+  value: string,
+  kmsCtx: KmsContext,
+): Promise<string> {
+  if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL) return value;
+  const dek = await getOrCreateDek(kms, subject, kmsCtx);
+  return encryptValue(subject, dek, value);
+}
+
 export interface EncryptPiiOptions {
   readonly onlyKeys?: Iterable<string>;
   // Write-time tenant for tenantOwned fields on rows without a tenantId column.

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

@@ -0,0 +1,276 @@
+// One-time backfill for pre-KMS plaintext PII in kumiko_events (#799).
+//
+// Crypto-shredding (#724/#818) only covers NEW writes — events appended
+// before a KMS was configured still carry plaintext (user.created email,
+// delivery attempt recipientAddress, job payloads). This tool re-encrypts
+// them in place, per field, under the owning subject's DEK:
+//
+//   - entity lifecycle events (<entity>.created/updated/deleted/forgotten/
+//     restored) for every entity with PII subject annotations
+//   - custom events from the event-PII catalog (r.defineEvent piiFields)
+//
+// Already-forgotten subjects must NOT get a fresh key minted for their old
+// plaintext — three erased-detection layers write [[erased]] instead:
+//   1. KeyErasedError from the KMS (subject forgotten in the KMS era)
+//   2. the event's own aggregate has a *.forgotten event (pre-KMS forget)
+//   3. the resolved user subject's id has a *.forgotten event (custom
+//      events referencing a pre-KMS-forgotten user)
+//
+// Idempotent: ciphertext and sentinel values pass through untouched — a
+// second run reports 0 updates. One failing event does not abort the run;
+// failures are collected and reported (fail-loud at the caller).
+//
+// Snapshots of touched aggregates are dropped (they may cache plaintext);
+// the next snapshotting load recreates them. AFTER a run, rebuild the
+// affected projections — applyEntityEvent materializes ciphertext AND the
+// blind-index columns, which keeps equality lookups (login by email) alive.
+
+import { asRawClient } from "../../bun-db";
+import { configuredEventPiiCatalog } from "../../crypto/event-pii";
+import type { KmsContext, LocalKeyKmsAdapter, SubjectId } from "../../crypto/kms-adapter";
+import { KeyErasedError } from "../../crypto/kms-adapter";
+import {
+  configuredPiiSubjectKms,
+  encryptPiiValueForSubject,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+} from "../../crypto/pii-field-encryption";
+import { collectPiiSubjectFields, resolveSubjectForField } from "../../crypto/subject-resolver";
+import type { EntityDefinition, Registry, TenantId } from "../../engine/types";
+import type { DbRunner } from "../connection";
+
+const LIFECYCLE_VERBS = ["created", "updated", "deleted", "restored", "forgotten"] as const;
+
+export type PiiBackfillFailure = {
+  readonly eventId: string;
+  readonly reason: string;
+};
+
+export type PiiBackfillResult = {
+  readonly scannedEvents: number;
+  readonly updatedEvents: number;
+  readonly encryptedFields: number;
+  readonly erasedFields: number;
+  readonly deletedSnapshots: number;
+  readonly failures: readonly PiiBackfillFailure[];
+};
+
+export type PiiBackfillOptions = {
+  readonly batchSize?: number;
+  // Scan + count only, write nothing.
+  readonly dryRun?: boolean;
+};
+
+type EventRow = {
+  readonly id: bigint | string;
+  readonly aggregate_id: string;
+  readonly aggregate_type: string;
+  readonly tenant_id: string;
+  readonly type: string;
+  readonly payload: Record<string, unknown>;
+};
+
+type FieldOutcome = "unchanged" | "encrypted" | "erased";
+
+export async function backfillEventPiiEncryption(
+  db: DbRunner,
+  registry: Registry,
+  options: PiiBackfillOptions = {},
+): Promise<PiiBackfillResult> {
+  const kms = configuredPiiSubjectKms();
+  if (!kms) {
+    throw new Error(
+      "backfillEventPiiEncryption requires a configured subject KMS — boot with " +
+        "runProdApp({ kms }) / configurePiiSubjectKms(adapter) before running the backfill.",
+    );
+  }
+  const batchSize = options.batchSize ?? 500;
+  const raw = asRawClient(db);
+  const kmsCtx: KmsContext = { requestId: "pii-backfill" };
+
+  const entityTargets = new Map<
+    string,
+    { readonly entity: EntityDefinition; readonly piiFields: readonly string[] }
+  >();
+  for (const [name, entity] of registry.getAllEntities()) {
+    const piiFields = collectPiiSubjectFields(entity);
+    if (piiFields.length > 0) entityTargets.set(name, { entity, piiFields });
+  }
+  const eventCatalog = configuredEventPiiCatalog();
+
+  const aggregateTypes = [...entityTargets.keys()];
+  const catalogTypes = [...eventCatalog.keys()];
+  const result = {
+    scannedEvents: 0,
+    updatedEvents: 0,
+    encryptedFields: 0,
+    erasedFields: 0,
+    deletedSnapshots: 0,
+    failures: [] as PiiBackfillFailure[],
+  };
+  if (aggregateTypes.length === 0 && catalogTypes.length === 0) return result;
+
+  // Pre-KMS forgets left no key tombstone — the *.forgotten event on the
+  // stream is the only durable marker. Collect once; aggregate_id doubles
+  // as the user id for user-subject lookups.
+  const forgottenRows = (await raw.unsafe(
+    `SELECT DISTINCT "aggregate_id" FROM "kumiko_events" WHERE "type" LIKE '%.forgotten'`,
+  )) as ReadonlyArray<{ aggregate_id: string }>;
+  const forgottenAggregates = new Set(forgottenRows.map((r) => r.aggregate_id));
+
+  const touchedAggregates = new Set<string>();
+  let cursor = "0";
+
+  for (;;) {
+    const rows = (await raw.unsafe(
+      `SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
+         FROM "kumiko_events"
+        WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" > $3::bigint
+        ORDER BY "id" ASC
+        LIMIT $4`,
+      [aggregateTypes, catalogTypes, cursor, batchSize],
+    )) as ReadonlyArray<EventRow>;
+    if (rows.length === 0) break;
+
+    for (const row of rows) {
+      result.scannedEvents++;
+      try {
+        const outcome = await transformEvent(row);
+        if (outcome === null) continue;
+        result.encryptedFields += outcome.encrypted;
+        result.erasedFields += outcome.erased;
+        if (!options.dryRun) {
+          await raw.unsafe(`UPDATE "kumiko_events" SET "payload" = $1::jsonb WHERE "id" = $2`, [
+            JSON.stringify(outcome.payload),
+            row.id,
+          ]);
+        }
+        result.updatedEvents++;
+        touchedAggregates.add(row.aggregate_id);
+      } catch (e) {
+        result.failures.push({
+          eventId: String(row.id),
+          reason: e instanceof Error ? e.message : String(e),
+        });
+      }
+    }
+    const last = rows[rows.length - 1];
+    if (last === undefined) break;
+    cursor = String(last.id);
+  }
+
+  // Snapshots may cache the plaintext state of touched aggregates.
+  if (!options.dryRun && touchedAggregates.size > 0) {
+    const deleted = (await raw.unsafe(
+      `DELETE FROM "kumiko_snapshots" WHERE "aggregate_id" = ANY($1::uuid[]) RETURNING "aggregate_id"`,
+      [[...touchedAggregates]],
+    )) as ReadonlyArray<unknown>;
+    result.deletedSnapshots = deleted.length;
+  }
+
+  return result;
+
+  async function transformEvent(
+    row: EventRow,
+  ): Promise<{ payload: Record<string, unknown>; encrypted: number; erased: number } | null> {
+    const counters = { encrypted: 0, erased: 0 };
+    const payload = structuredClone(row.payload);
+
+    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;
+        const outcome = await encryptField(payload, field, { kind: "user", userId: subjectId });
+        bump(outcome);
+      }
+    } else {
+      const target = entityTargets.get(row.aggregate_type);
+      if (!target || !isLifecycleEventOf(row.type, row.aggregate_type)) return null;
+      const sections = lifecycleSections(payload);
+      for (const section of sections) {
+        // Update-changes may carry a pii field without its owner field —
+        // resolve subjects from the merged view; aggregate_id backs the
+        // self-subject when a section lacks the id column.
+        const subjectSource: Record<string, unknown> = {
+          id: row.aggregate_id,
+          ...Object.assign({}, ...sections),
+          ...section,
+        };
+        for (const field of target.piiFields) {
+          const subject = resolveSubjectForField(target.entity, field, subjectSource, {
+            // @cast-boundary db-read — tenant_id column is the branded TenantId
+            tenantId: row.tenant_id as TenantId,
+          });
+          if (subject === null) continue;
+          const outcome = await encryptField(section, field, subject);
+          bump(outcome);
+        }
+      }
+    }
+
+    if (counters.encrypted === 0 && counters.erased === 0) return null;
+    return { payload, ...counters };
+
+    function bump(outcome: FieldOutcome): void {
+      if (outcome === "encrypted") counters.encrypted++;
+      if (outcome === "erased") counters.erased++;
+    }
+
+    async function encryptField(
+      section: Record<string, unknown>,
+      field: string,
+      subject: SubjectId,
+    ): Promise<FieldOutcome> {
+      const value = section[field];
+      if (value === null || value === undefined) return "unchanged";
+      if (typeof value !== "string") return "unchanged";
+      if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL) return "unchanged";
+      if (isForgottenSubject(subject, row.aggregate_id)) {
+        section[field] = PII_ERASED_SENTINEL;
+        return "erased";
+      }
+      try {
+        section[field] = await encryptPiiValueForSubject(
+          kms as LocalKeyKmsAdapter,
+          subject,
+          value,
+          kmsCtx,
+        );
+        return "encrypted";
+      } catch (e) {
+        if (e instanceof KeyErasedError) {
+          section[field] = PII_ERASED_SENTINEL;
+          return "erased";
+        }
+        throw e;
+      }
+    }
+  }
+
+  function isForgottenSubject(subject: SubjectId, aggregateId: string): boolean {
+    if (forgottenAggregates.has(aggregateId)) return true;
+    return subject.kind === "user" && forgottenAggregates.has(subject.userId);
+  }
+}
+
+function isLifecycleEventOf(eventType: string, aggregateType: string): boolean {
+  if (!eventType.startsWith(`${aggregateType}.`)) return false;
+  const verb = eventType.slice(aggregateType.length + 1);
+  return (LIFECYCLE_VERBS as readonly string[]).includes(verb);
+}
+
+// created events carry the fields flat; updated carries { changes, previous };
+// deleted/forgotten/restored carry { previous }. Returned sections are the
+// mutable objects INSIDE the payload clone — encryptField writes in place.
+function lifecycleSections(payload: Record<string, unknown>): Record<string, unknown>[] {
+  const sections: Record<string, unknown>[] = [];
+  if (isRecord(payload["changes"])) sections.push(payload["changes"]);
+  if (isRecord(payload["previous"])) sections.push(payload["previous"]);
+  if (sections.length === 0) sections.push(payload);
+  return sections;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/engine/define-feature.ts

@@ -1,4 +1,4 @@
-import type { ZodType, z } from "zod";
+import { ZodObject, type ZodType, type z } from "zod";
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { toTableName } from "../db/table-builder";
 import { LifecycleHookTypes } from "./constants";
@@ -19,6 +19,7 @@ import type {
   EntityRef,
   EventDef,
   EventMigrationDef,
+  EventPiiFields,
   EventUpcastFn,
   ExtensionSelectorDef,
   FeatureDefinition,
@@ -511,7 +512,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     defineEvent: <const TInner extends string, TPayload>(
       eventName: TInner,
       schema: ZodType<TPayload>,
-      options?: { readonly version?: number },
+      options?: { readonly version?: number; readonly piiFields?: EventPiiFields },
     ): EventDef<TPayload, QualifiedEventName<TName, TInner>> => {
       // Return the fully-qualified event name so callers can pass it
       // straight to ctx.appendEvent without hand-building the
@@ -530,6 +531,27 @@ export function defineFeature<const TName extends string, TExports = undefined>(
           `[Feature ${name}] defineEvent("${eventName}"): version must be a positive integer, got ${String(version)}`,
         );
       }
+      // piiFields misconfiguration is a boot-time error, not a silent
+      // plaintext leak: both the pii field and its subjectField must exist
+      // on the payload schema (checkable when the schema is a ZodObject).
+      const piiFields = options?.piiFields;
+      if (piiFields) {
+        const shape = schema instanceof ZodObject ? schema.shape : undefined;
+        for (const [field, spec] of Object.entries(piiFields)) {
+          if (field === spec.subjectField) {
+            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.`,
+            );
+          }
+          for (const required of [field, spec.subjectField]) {
+            if (shape && !(required in shape)) {
+              throw new Error(
+                `[Feature ${name}] defineEvent("${eventName}"): piiFields references "${required}" which is not a field of the payload schema.`,
+              );
+            }
+          }
+        }
+      }
       // @cast-boundary engine-bridge — runtime-string mirrors the
       // template-literal-type via QualifiedEventName + toKebab. Both
       // sides are tested (CamelToKebab type-tests + scan-events kebab
@@ -538,6 +560,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
         name: qualified as QualifiedEventName<TName, TInner>,
         schema,
         version,
+        ...(piiFields !== undefined && { piiFields }),
       };
       events[eventName] = def;
       return def;

package/src/engine/registry.ts

@@ -1,3 +1,4 @@
+import { configureEventPiiCatalog } from "../crypto/event-pii";
 import { applyEntityEvent } from "../db/apply-entity-event";
 import {
   assertBackingTableSuperset,
@@ -26,6 +27,7 @@ import type {
   EntityProjectionExtension,
   EntityRelations,
   EventDef,
+  EventPiiFields,
   EventUpcastFn,
   FeatureDefinition,
   FeatureMetricDef,
@@ -1363,6 +1365,16 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     return false;
   })();
 
+  // Publish the event-PII catalog (#799): append() — the single write funnel
+  // into kumiko_events — encrypts catalogued payload fields regardless of
+  // which path produced the event (ctx.appendEvent, MSP-apply, low-level
+  // append in delivery/jobs loggers).
+  const eventPiiCatalog = new Map<string, EventPiiFields>();
+  for (const [qualified, def] of eventMap) {
+    if (def.piiFields) eventPiiCatalog.set(qualified, def.piiFields);
+  }
+  configureEventPiiCatalog(eventPiiCatalog);
+
   // Auto-wire the soft-delete cleanup cron + its grace-days config key when ANY
   // entity opts into softDelete — the framework owns this machinery, no feature
   // declares it (mirrors the auto restore-handler). Job-runner reads getAllJobs
@@ -1395,6 +1407,10 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       return entityMap.get(name);
     },
 
+    getAllEntities(): ReadonlyMap<string, EntityDefinition> {
+      return entityMap;
+    },
+
     getWriteHandler(name: string): WriteHandlerDef | undefined {
       return writeHandlerMap.get(name);
     },

package/src/engine/types/feature.ts

@@ -36,6 +36,7 @@ import type {
   EntityRef,
   EventDef,
   EventMigrationDef,
+  EventPiiFields,
   EventUpcastFn,
   HandlerRef,
   NameOrRef,
@@ -529,10 +530,14 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // on first registration. When you bump the payload shape, raise version
   // AND register r.eventMigration(shortName, N, N+1, transform) — the
   // framework refuses to boot if the chain from 1 → version has gaps.
+  //
+  // `options.piiFields` declares PII payload fields encrypted under the DEK
+  // of the user named by `subjectField` (crypto-shredding, #799). append()
+  // enforces the catalog on every write path.
   defineEvent<const TInner extends string, TPayload>(
     name: TInner,
     schema: ZodType<TPayload>,
-    options?: { readonly version?: number },
+    options?: { readonly version?: number; readonly piiFields?: EventPiiFields },
   ): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
 
   // Register a step-wise payload transform for event-schema evolution.
@@ -789,6 +794,7 @@ export type Registry = {
 
   getFeature(name: string): FeatureDefinition | undefined;
   getEntity(name: string): EntityDefinition | undefined;
+  getAllEntities(): ReadonlyMap<string, EntityDefinition>;
   getWriteHandler(name: string): WriteHandlerDef | undefined;
   getQueryHandler(name: string): QueryHandlerDef | undefined;
   getSearchableFields(entityName: string): readonly string[];

package/src/engine/types/handlers.ts

@@ -584,6 +584,12 @@ export type QualifiedEventName<
   TInner extends string,
 > = `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`;
 
+// PII payload fields on a custom event (#799): `field` is encrypted under
+// the DEK of the user named by the payload's `subjectField` (crypto-
+// shredding). A null subject field leaves the value plaintext — there is
+// no user key to shred for system-triggered events.
+export type EventPiiFields = Readonly<Record<string, { readonly subjectField: string }>>;
+
 export type EventDef<TPayload = unknown, TName extends string = string> = {
   readonly name: TName;
   readonly schema: ZodType<TPayload>;
@@ -592,6 +598,7 @@ export type EventDef<TPayload = unknown, TName extends string = string> = {
   // upcasts older stored events. Reads consult this to decide if upcasters
   // need to run before the payload hits consumer code.
   readonly version: number;
+  readonly piiFields?: EventPiiFields;
 };
 
 // Args for ctx.appendEvent — explicit aggregate target, Marten-style.

package/src/engine/types/index.ts

@@ -136,6 +136,7 @@ export type {
   EntityRef,
   EventDef,
   EventMigrationDef,
+  EventPiiFields,
   EventUpcastCtx,
   EventUpcastFn,
   FetchForWritingArgs,

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

@@ -0,0 +1,279 @@
+// backfillEventPiiEncryption (#799): pre-KMS plaintext events get re-
+// encrypted in place — entity lifecycle payloads (created / updated
+// changes+previous / forgotten previous) AND catalogued custom events.
+// Pre-KMS-forgotten subjects (detectable only via their *.forgotten event)
+// get [[erased]] instead of a freshly minted key. After the backfill,
+// applyEntityEvent (the rebuild primitive) materializes ciphertext AND the
+// blind-index column, so equality lookups keep working.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "../../crypto";
+import { applyEntityEvent } from "../../db/apply-entity-event";
+import { backfillEventPiiEncryption } from "../../db/queries/backfill-pii";
+import { asRawClient, fetchOne } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { defineFeature } from "../../engine/define-feature";
+import { createEntity, createTextField } from "../../engine/factories";
+import { createRegistry } from "../../engine/registry";
+import type { Registry, TenantId } from "../../engine/types";
+import { createTestDb, type TestDb, unsafeCreateEntityTable } from "../../stack";
+import { generateId } from "../../utils";
+import { append, loadAggregate } from "../event-store";
+import { createEventsTable } from "../events-schema";
+
+const TENANT = "00000000-0000-4000-8000-000000000001" as TenantId;
+const BIDX_KEY = Buffer.alloc(32, 5).toString("base64");
+
+const contactEntity = createEntity({
+  fields: {
+    email: createTextField({ required: true, pii: true, lookupable: true }),
+    displayName: createTextField(),
+  },
+});
+const contactTable = buildEntityTable("contact", contactEntity);
+
+const crmFeature = defineFeature("crm", (r) => {
+  r.entity("contact", contactEntity);
+});
+
+const mailerFeature = defineFeature("mailer", (r) => {
+  r.defineEvent(
+    "ping",
+    z.object({ targetId: z.string().nullable(), address: z.string().nullable() }),
+    { piiFields: { address: { subjectField: "targetId" } } },
+  );
+});
+
+let testDb: TestDb;
+let registry: Registry;
+let kms: InMemoryKmsAdapter;
+
+async function appendPlain(
+  aggregateId: string,
+  aggregateType: string,
+  type: string,
+  payload: Record<string, unknown>,
+  expectedVersion = 0,
+): Promise<void> {
+  await append(testDb.db, {
+    aggregateId,
+    aggregateType,
+    tenantId: TENANT,
+    expectedVersion,
+    type,
+    payload,
+    metadata: { userId: "system" },
+  });
+}
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  registry = createRegistry([crmFeature, mailerFeature]);
+  await createEventsTable(testDb.db);
+  await unsafeCreateEntityTable(testDb.db, contactEntity, "contact");
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  const raw = asRawClient(testDb.db);
+  await raw.unsafe(`TRUNCATE "kumiko_events" RESTART IDENTITY`);
+  await raw.unsafe(`TRUNCATE "${contactTable.tableName}"`);
+  // Plaintext era: NO KMS while the legacy events are appended.
+  resetPiiSubjectKmsForTests();
+  resetBlindIndexKeyForTests();
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+  resetBlindIndexKeyForTests();
+});
+
+function armKms(): void {
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+}
+
+describe("backfillEventPiiEncryption", () => {
+  test("encrypts entity lifecycle payloads: created flat, updated changes+previous", async () => {
+    const c1 = generateId();
+    await appendPlain(c1, "contact", "contact.created", {
+      id: c1,
+      email: "old@x.com",
+      displayName: "Alice",
+    });
+    await appendPlain(
+      c1,
+      "contact",
+      "contact.updated",
+      { changes: { email: "new@x.com" }, previous: { id: c1, email: "old@x.com" } },
+      1,
+    );
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry);
+
+    expect(result.failures).toEqual([]);
+    expect(result.updatedEvents).toBe(2);
+    expect(result.encryptedFields).toBe(3);
+
+    const events = await loadAggregate(testDb.db, c1, TENANT);
+    const created = events[0]?.payload as Record<string, unknown>;
+    expect(isPiiCiphertext(created["email"])).toBe(true);
+    expect(String(created["email"])).toContain(`user:${c1}`);
+    expect(created["displayName"]).toBe("Alice");
+
+    const updated = events[1]?.payload as {
+      changes: Record<string, unknown>;
+      previous: Record<string, unknown>;
+    };
+    expect(isPiiCiphertext(updated.changes["email"])).toBe(true);
+    expect(isPiiCiphertext(updated.previous["email"])).toBe(true);
+  });
+
+  test("pre-KMS-forgotten aggregate gets [[erased]], not a fresh key", async () => {
+    const c2 = generateId();
+    await appendPlain(c2, "contact", "contact.created", { id: c2, email: "gone@x.com" });
+    await appendPlain(
+      c2,
+      "contact",
+      "contact.forgotten",
+      { previous: { id: c2, email: "gone@x.com" } },
+      1,
+    );
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry);
+
+    expect(result.failures).toEqual([]);
+    expect(result.erasedFields).toBe(2);
+    const events = await loadAggregate(testDb.db, c2, TENANT);
+    const created = events[0]?.payload as Record<string, unknown>;
+    expect(created["email"]).toBe(PII_ERASED_SENTINEL);
+    const forgotten = events[1]?.payload as { previous: Record<string, unknown> };
+    expect(forgotten.previous["email"]).toBe(PII_ERASED_SENTINEL);
+  });
+
+  test("catalogued custom events: encrypt under target's DEK; forgotten target → [[erased]]", async () => {
+    const forgottenUser = generateId();
+    await appendPlain(forgottenUser, "contact", "contact.created", {
+      id: forgottenUser,
+      email: "f@x.com",
+    });
+    await appendPlain(
+      forgottenUser,
+      "contact",
+      "contact.forgotten",
+      { previous: { id: forgottenUser, email: "f@x.com" } },
+      1,
+    );
+
+    const p1 = generateId();
+    const p2 = generateId();
+    const p3 = generateId();
+    await appendPlain(p1, "ping", "mailer:event:ping", {
+      targetId: "u-7",
+      address: "u7@x.com",
+    });
+    await appendPlain(p2, "ping", "mailer:event:ping", {
+      targetId: forgottenUser,
+      address: "f@x.com",
+    });
+    await appendPlain(p3, "ping", "mailer:event:ping", { targetId: null, address: "ops@x.com" });
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry);
+
+    expect(result.failures).toEqual([]);
+    const alive = (await loadAggregate(testDb.db, p1, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(isPiiCiphertext(alive["address"])).toBe(true);
+    expect(String(alive["address"])).toContain("user:u-7");
+
+    const erased = (await loadAggregate(testDb.db, p2, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(erased["address"]).toBe(PII_ERASED_SENTINEL);
+
+    // No subject → no key to shred; stays plaintext (documented rollout gap).
+    const system = (await loadAggregate(testDb.db, p3, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(system["address"]).toBe("ops@x.com");
+  });
+
+  test("idempotent: second run updates nothing; dryRun writes nothing", async () => {
+    const c1 = generateId();
+    await appendPlain(c1, "contact", "contact.created", { id: c1, email: "a@x.com" });
+
+    armKms();
+    const dry = await backfillEventPiiEncryption(testDb.db, registry, { dryRun: true });
+    expect(dry.updatedEvents).toBe(1);
+    const untouched = (await loadAggregate(testDb.db, c1, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(untouched["email"]).toBe("a@x.com");
+
+    const first = await backfillEventPiiEncryption(testDb.db, registry);
+    expect(first.updatedEvents).toBe(1);
+    const second = await backfillEventPiiEncryption(testDb.db, registry);
+    expect(second.updatedEvents).toBe(0);
+    expect(second.failures).toEqual([]);
+  });
+
+  test("small batchSize pages through the estate completely", async () => {
+    const ids = [generateId(), generateId(), generateId(), generateId(), generateId()];
+    for (const id of ids) {
+      await appendPlain(id, "contact", "contact.created", { id, email: `${id}@x.com` });
+    }
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry, { batchSize: 2 });
+    expect(result.scannedEvents).toBe(5);
+    expect(result.updatedEvents).toBe(5);
+  });
+
+  test("after backfill, applyEntityEvent (rebuild) materializes ciphertext + blind index", async () => {
+    const c1 = generateId();
+    await appendPlain(c1, "contact", "contact.created", { id: c1, email: "login@x.com" });
+
+    armKms();
+    configureBlindIndexKey(BIDX_KEY);
+    await backfillEventPiiEncryption(testDb.db, registry);
+
+    const events = await loadAggregate(testDb.db, c1, TENANT);
+    const created = events[0];
+    if (!created) throw new Error("missing created event");
+    await applyEntityEvent(created, contactTable, contactEntity, testDb.db);
+
+    const row = await fetchOne(testDb.db, contactTable, { id: c1 });
+    expect(isPiiCiphertext(row?.["email"])).toBe(true);
+    const rawRows = (await asRawClient(testDb.db).unsafe(
+      `SELECT "email_bidx" FROM "${contactTable.tableName}" WHERE "id" = $1`,
+      [c1],
+    )) as ReadonlyArray<Record<string, unknown>>;
+    expect(String(rawRows[0]?.["email_bidx"])).toStartWith("kumiko-bidx:v1:");
+  });
+
+  test("throws without a configured KMS", async () => {
+    expect(backfillEventPiiEncryption(testDb.db, registry)).rejects.toThrow(
+      /requires a configured subject KMS/,
+    );
+  });
+});

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

@@ -1,3 +1,4 @@
+import { encryptEventPayloadPii } from "../crypto/event-pii";
 import type { DbRunner } from "../db";
 import { isUniqueViolation } from "../db/pg-error";
 import {
@@ -108,21 +109,25 @@ type SelectedEvent = {
 export const EVENTS_PUBSUB_CHANNEL = "kumiko_events_new";
 
 export async function append(db: DbRunner, event: EventToAppend): Promise<StoredEvent> {
-  const newVersion = event.expectedVersion + 1;
-  const eventVersion = event.eventVersion ?? 1;
+  // 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 toStore = payload === event.payload ? event : { ...event, payload };
+  const newVersion = toStore.expectedVersion + 1;
+  const eventVersion = toStore.eventVersion ?? 1;
 
   try {
     const row =
-      event.expectedVersion === 0
-        ? await insertFirstEvent(db, event, newVersion, eventVersion)
-        : await insertSubsequentEvent(db, event, newVersion, eventVersion);
+      toStore.expectedVersion === 0
+        ? await insertFirstEvent(db, toStore, newVersion, eventVersion)
+        : await insertSubsequentEvent(db, toStore, newVersion, eventVersion);
 
     // NOTIFY fires on commit (PG buffers NOTIFY per TX), so subscribers never
     // see a wake-up for an event that later rolled back. Harmless no-op when
     // no LISTENer is attached.
     await notifyPgChannel(db, EVENTS_PUBSUB_CHANNEL);
 
-    return buildStoredEvent(event, newVersion, eventVersion, row);
+    return buildStoredEvent(toStore, newVersion, eventVersion, row);
   } catch (e) {
     if (isUniqueViolation(e)) {
       // Only constraint left on the events table: events_aggregate_version_uq

package/src/event-store/index.ts

@@ -1,3 +1,9 @@
+export {
+  backfillEventPiiEncryption,
+  type PiiBackfillFailure,
+  type PiiBackfillOptions,
+  type PiiBackfillResult,
+} from "../db/queries/backfill-pii";
 export {
   type ArchiveStreamArgs,
   archivedStreamsTable,