@cosmicdrift/kumiko-framework 0.118.0 → 0.120.0

package/src/engine/boot-validator/pii-retention.ts

@@ -64,6 +64,35 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         );
       }
 
+      // lookupable (#818): nur text + nur MIT Subject-Annotation. Ohne
+      // Subject bleibt der Wert eh Klartext — der Blind-Index wäre eine
+      // zweite (deterministische!) Kopie ohne Nutzen.
+      if (annot.lookupable === true) {
+        if (field.type !== "text") {
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { lookupable: true } but has type "${field.type}" — blind-index equality lookups only apply to text fields.`,
+          );
+        }
+        if (annotCount === 0) {
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { lookupable: true } without a subject annotation (pii / userOwned / tenantOwned). Plaintext fields don't need a blind index — add the subject annotation or drop lookupable.`,
+          );
+        }
+      }
+
+      // Substring-Suche/Sortierung auf Ciphertext ist prinzipbedingt
+      // unmöglich — searchable würde Plaintext-Kopien in den Suchindex
+      // schieben, sortable sortiert Base64-Blobs. Equality → lookupable.
+      if (annotCount > 0) {
+        const flags = field as { readonly searchable?: boolean; readonly sortable?: boolean }; // @cast-boundary schema-walk
+        if (flags.searchable === true || flags.sortable === true) {
+          const offending = flags.searchable === true ? "searchable" : "sortable";
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation with { ${offending}: true } — ${offending} on encrypted fields cannot work (ciphertext at rest). For equality lookups use { lookupable: true }; for search/sort the field must stay plaintext (allowPlaintext).`,
+          );
+        }
+      }
+
       if (annot.userOwned) {
         const ownerName = annot.userOwned.ownerField;
         if (!ownerName || typeof ownerName !== "string") {
@@ -78,21 +107,28 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
             `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" references userOwned.ownerField "${ownerName}" but no such field exists. Known fields: ${known}`,
           );
         }
-        if (ownerField.type !== "reference") {
+        // Text is accepted alongside reference: the ES-framework carries
+        // user ids as plain text columns throughout the bundled features
+        // (user-session.userId, invitation.invitedBy) — there is no
+        // relational FK to point a reference at. Self-referencing
+        // ownerField (the field's own value IS the owner id) rides on this.
+        if (ownerField.type !== "reference" && ownerField.type !== "text") {
           throw new Error(
-            `[Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" must be a reference field, got type "${ownerField.type}"`,
+            `[Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`,
           );
         }
         // Soft-Warning wenn das reference-target nicht offensichtlich user
         // ist — custom subject-entities (HR-Mitarbeiter, Patient) sind
         // erlaubt, müssen aber bewusste Wahl sein.
-        const refTarget = ownerField.entity;
-        const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
-        if (targetEntity !== "user") {
-          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-          console.warn(
-            `[kumiko:boot] [Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`,
-          );
+        if (ownerField.type === "reference") {
+          const refTarget = ownerField.entity;
+          const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
+          if (targetEntity !== "user") {
+            // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+            console.warn(
+              `[kumiko:boot] [Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`,
+            );
+          }
         }
       }
 

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,
@@ -66,6 +67,7 @@ import type {
   TreeChildrenSubscribe,
   UiHints,
   UnmanagedTableEntry,
+  UnmanagedTableOptions,
   ValidationHookFn,
   WriteHandlerDef,
   WriteHandlerFn,
@@ -510,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
@@ -529,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
@@ -537,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;
@@ -867,7 +891,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       };
     },
 
-    unmanagedTable(meta: EntityTableMeta, options: RawTableOptions): void {
+    unmanagedTable(meta: EntityTableMeta, options: UnmanagedTableOptions): void {
       // Name comes from the meta itself — apps already give the table a
       // name when calling defineUnmanagedTable, no need to repeat it.
       const tableName = meta.tableName;
@@ -896,6 +920,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
         name: tableName,
         meta,
         reason: options.reason,
+        ...(options.piiEncryptedOnWrite && { piiEncryptedOnWrite: true }),
       };
     },
 

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,
@@ -678,6 +680,15 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
             `Pick a different tableName — both would emit CREATE TABLE "${umName}".`,
         );
       }
+      const piiFields = umDef.meta.piiSubjectFields ?? [];
+      if (piiFields.length > 0 && !umDef.piiEncryptedOnWrite) {
+        throw new Error(
+          `Unmanaged-table "${umName}" (feature "${feature.name}") has PII-annotated fields ` +
+            `(${piiFields.join(", ")}) but direct writes bypass the executor's PII encryption. ` +
+            `Encrypt those fields before every insert/update (encryptPiiFieldValues) and declare ` +
+            `{ piiEncryptedOnWrite: true }, or drop the subject annotations.`,
+        );
+      }
       physicalTableOwners.set(umName, {
         kind: "unmanaged",
         owner: umName,
@@ -1354,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
@@ -1386,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,
@@ -168,6 +169,15 @@ export type UnmanagedTableEntry = {
   readonly name: string;
   readonly meta: EntityTableMeta;
   readonly reason: string;
+  readonly piiEncryptedOnWrite?: true;
+};
+
+/** Options for r.unmanagedTable(). Direct-write stores skip the executor,
+ *  so the executor's PII encryption never runs for them — a feature whose
+ *  meta carries piiSubjectFields must encrypt those fields itself before
+ *  every insert/update and declare that here, or boot fails (#820). */
+export type UnmanagedTableOptions = RawTableOptions & {
+  readonly piiEncryptedOnWrite?: true;
 };
 
 /** Registry-aggregated unmanaged-table — adds the owning feature name. */
@@ -520,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.
@@ -718,7 +732,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // `PgTable` (legacy), unmanagedTable carries the new `EntityTableMeta`
   // shape that `migrate-runner` consumes. After the full drizzle-cut they
   // will likely merge; for now they coexist.
-  unmanagedTable(meta: EntityTableMeta, options: RawTableOptions): void;
+  unmanagedTable(meta: EntityTableMeta, options: UnmanagedTableOptions): void;
 
   // Register the tree-actions schema for this feature — a map of
   // action-name → action-definition (with optional typed args). At-most-
@@ -780,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/fields.ts

@@ -62,6 +62,12 @@ export type PiiAnnotations = {
   readonly tenantOwned?: boolean;
   readonly anonymize?: () => unknown | Promise<unknown>;
   readonly allowPlaintext?: string;
+  /** Equality-Lookups (fetchOne/filter eq) bleiben trotz Verschluesselung
+   *  moeglich: generierte `<snake>_bidx`-Spalte traegt einen HMAC-Blind-
+   *  Index, Query-Compiler matchen `(col = $1 OR col_bidx = $2)`. Nur auf
+   *  text-Feldern MIT Subject-Annotation erlaubt (Boot-Validator).
+   *  Siehe docs/plans/datenschutz/blind-index.md (kumiko-framework#818). */
+  readonly lookupable?: true;
 };
 
 // --- Retention (DSGVO Art. 5(1)(e) + HGB/AO Aufbewahrungspflichten) ---

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

@@ -78,6 +78,7 @@ export type {
   UiHints,
   UnmanagedTableDef,
   UnmanagedTableEntry,
+  UnmanagedTableOptions,
 } from "./feature";
 export type {
   AnyFileFieldDef,
@@ -135,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,