@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/bun-db/query.ts

@@ -19,6 +19,16 @@
 //     drizzle's getTableName + getTableColumns (drizzle weiterhin als type-
 //     reference, NICHT als runtime-API-call)
 
+import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import type {
+  SelectOptions,
+  WhereObject,
+  WhereOperator,
+} from "@cosmicdrift/kumiko-types/where-clause-types";
+// Static import, not the ambient global: Bun doesn't expose Temporal on
+// globalThis, so instantFromDriver crashed on timestamptz reads (#1480).
+import { Temporal } from "temporal-polyfill";
+import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index";
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";
 import { camelCase as envCamelCase } from "../env";
@@ -42,7 +52,6 @@ import type { BunDbRunner } from "./connection";
 // enumerable props, so an entity field named `source`/`columns`/`tableName`/…
 // would overwrite the matching meta key — reading the meta from the symbol is
 // the only collision-safe path.
-const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
 
 function isEntityTableMeta(v: unknown): v is EntityTableMeta {
   return (
@@ -109,6 +118,23 @@ export function asRawClient(db: unknown): RawClient {
   );
 }
 
+// postgres.js / Bun.SQL reject the WHOLE begin() when any statement inside
+// it errored — even if the JS error was caught (the driver tracks per-block
+// query failures). Error confinement therefore must go through the driver's
+// own savepoint(), not manual SAVEPOINT statements. The callback receives
+// the savepoint-scoped tx; run every confined statement on THAT handle.
+export async function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promise<T>): Promise<T> {
+  const raw = asRawClient(tx) as unknown as {
+    savepoint?: <TR>(cb: (sp: unknown) => Promise<TR>) => Promise<TR>;
+  };
+  if (typeof raw.savepoint !== "function") {
+    throw new Error(
+      "runInSavepoint: transaction handle has no savepoint() — pass the driver tx (postgres.js TransactionSql / Bun.SQL).",
+    );
+  }
+  return raw.savepoint(fn);
+}
+
 /**
  * When handlers call `selectMany(ctx.db, …)` instead of `ctx.db.selectMany(…)`,
  * unwrap via asRawClient would bypass TenantDb scoping. Duck-type TenantDb and
@@ -165,19 +191,23 @@ function assertNotTenantScoped(db: unknown, fnName: string): void {
 
 export type AnyDb = BunDbRunner | unknown;
 
-// WhereValue: primitive für eq, array für IN, null für IS NULL, oder
-// operator-object für range/comparisons.
-export type WhereOperator = {
-  readonly gt?: unknown;
-  readonly gte?: unknown;
-  readonly lt?: unknown;
-  readonly lte?: unknown;
-  readonly ne?: unknown;
-  readonly in?: readonly unknown[];
-  readonly like?: string;
-};
-export type WhereValue = unknown | WhereOperator;
-export type WhereObject = Record<string, WhereValue>;
+export type {
+  OrderByClause,
+  SelectOptions,
+  WhereObject,
+  WhereOperator,
+  WhereValue,
+} from "@cosmicdrift/kumiko-types/where-clause-types";
+
+const WHERE_OPERATOR_KEYS = ["gt", "gte", "lt", "lte", "ne", "in", "like"] as const;
+// Forces a tsc error here (not just a silent runtime miss) the moment
+// WhereOperator in @cosmicdrift/kumiko-types gains a key this array doesn't
+// know about — the two live in different packages and can't share a value
+// import without adding a runtime dependency edge.
+type _WhereOperatorKeysExhaustive =
+  Exclude<keyof WhereOperator, (typeof WHERE_OPERATOR_KEYS)[number]> extends never ? true : never;
+const _whereOperatorKeysExhaustive: _WhereOperatorKeysExhaustive = true;
+void _whereOperatorKeysExhaustive;
 
 function isWhereOperator(v: unknown): v is WhereOperator {
   if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
@@ -185,21 +215,8 @@ function isWhereOperator(v: unknown): v is WhereOperator {
   // WhereOperator is plain object literal with at most these keys.
   const keys = Object.keys(v);
   if (keys.length === 0) return false;
-  const opKeys = ["gt", "gte", "lt", "lte", "ne", "in", "like"];
-  return keys.every((k) => opKeys.includes(k));
+  return keys.every((k) => (WHERE_OPERATOR_KEYS as readonly string[]).includes(k));
 }
-export type OrderByClause = {
-  readonly col: string;
-  readonly direction?: "asc" | "desc";
-};
-
-export type SelectOptions = {
-  readonly limit?: number;
-  // Single column or array for multi-column tie-breaks (e.g.
-  // [{col: "createdAt"}, {col: "id"}] for chronological-with-stable-id).
-  readonly orderBy?: OrderByClause | readonly OrderByClause[];
-};
-
 // Akzeptiert EITHER. Beide haben einen tableName und field→column-mapping.
 // biome-ignore lint/suspicious/noExplicitAny: legacy drizzle pgTable surface
 type TableLike = EntityTableMeta | any;
@@ -338,6 +355,12 @@ export function coerceRow<T extends Record<string, unknown>>(row: T, info: Table
   const out: Record<string, unknown> = {};
   let changed = false;
   for (const key of Object.keys(row)) {
+    // Blind-Index-Spalten (#818) sind reine Lookup-Artefakte — der
+    // deterministische HMAC darf nie an Caller/API-Responses leaken.
+    if ((key.endsWith("_bidx") || key.endsWith("Bidx")) && info.hasColumn(key)) {
+      changed = true;
+      continue;
+    }
     const pgType = info.pgTypeOf(key);
     const value = row[key];
     let coerced: unknown = value;
@@ -512,14 +535,64 @@ function buildWhereClause(
       if (p.kind === "literal") {
         conditions.push(`${quoteIdent(col)} = ${p.literal}`);
       } else {
-        conditions.push(`${quoteIdent(col)} = $${idx++}${p.sql}`);
-        values.push(p.bound);
+        // Blind-Index-OR-Rewrite (#818): existiert zur Spalte ein bidx-
+        // Pendant (Suffix-Konvention `<col>_bidx`, framework-reserviert)
+        // und ist ein Key konfiguriert, matcht Equality beide Arme —
+        // Klartext-Alt-Rows über den Plaintext-Arm, verschlüsselte Rows
+        // über den HMAC. Der `kumiko-pii:`-Prefix der Ciphertexte macht
+        // einen Zufalls-Match des Plaintext-Arms praktisch unmöglich.
+        const bidxKey = configuredBlindIndexKey();
+        const bidxCol = `${col}_bidx`;
+        if (
+          bidxKey !== undefined &&
+          typeof value === "string" &&
+          !col.endsWith("_bidx") &&
+          info.hasColumn(bidxCol)
+        ) {
+          conditions.push(`(${quoteIdent(col)} = $${idx++} OR ${quoteIdent(bidxCol)} = $${idx++})`);
+          values.push(p.bound, computeBlindIndex(bidxKey, value));
+        } else {
+          conditions.push(`${quoteIdent(col)} = $${idx++}${p.sql}`);
+          values.push(p.bound);
+        }
       }
     }
   }
   return { sqlText: conditions.join(" AND "), values };
 }
 
+// #1163: under load the Bun.SQL pool can hand out a connection the server
+// already closed ("The connection was closed.", AbortError code 20) — no
+// validate-on-checkout exists. One retry re-checks out a fresh connection;
+// safe for pure reads. Tx handles are never retried: their transaction is
+// dead once the connection dropped, and a retry would run on the same dead
+// handle. Detection is name+message (not name alone) so a genuine user
+// abort (AbortSignal cancel) is NOT retried.
+function isClosedConnectionError(err: unknown): boolean {
+  if (err === null || typeof err !== "object") return false;
+  const e = err as { name?: unknown; message?: unknown };
+  return (
+    e.name === "AbortError" &&
+    typeof e.message === "string" &&
+    /connection was closed/i.test(e.message)
+  );
+}
+
+async function unsafeRead<TRow>(
+  db: AnyDb,
+  sqlText: string,
+  params: readonly unknown[],
+): Promise<readonly TRow[]> {
+  const raw = asRawClient(db);
+  try {
+    return (await raw.unsafe(sqlText, params)) as readonly TRow[];
+  } catch (err) {
+    // TransactionSql has savepoint(), only a top-level pool client has begin().
+    if (typeof raw.begin !== "function" || !isClosedConnectionError(err)) throw err;
+    return (await raw.unsafe(sqlText, params)) as readonly TRow[];
+  }
+}
+
 // biome-ignore lint/suspicious/noExplicitAny: opt-in default loosens row type for unannotated test fixtures
 export async function selectMany<TRow = any>(
   db: AnyDb,
@@ -556,7 +629,7 @@ export async function selectMany<TRow = any>(
     }
     sqlText += ` LIMIT ${options.limit}`;
   }
-  const raw = (await asRawClient(db).unsafe(sqlText, values)) as readonly Record<string, unknown>[];
+  const raw = (await unsafeRead(db, sqlText, values)) as readonly Record<string, unknown>[];
   return coerceRows(raw, info) as readonly TRow[];
 }
 
@@ -790,7 +863,7 @@ export async function countWhere(
     sqlText += ` WHERE ${w.sqlText}`;
     values = w.values;
   }
-  const rows = (await asRawClient(db).unsafe(sqlText, values)) as readonly { count: number }[];
+  const rows = (await unsafeRead(db, sqlText, values)) as readonly { count: number }[];
   return rows[0]?.count ?? 0;
 }
 

package/src/consumer-cli.ts

@@ -0,0 +1,134 @@
+// Shared core for the standalone consumer-ops CLI (status | restart).
+//
+// A dead event consumer (halt-on-poison after maxAttempts) previously had no
+// recovery surface in the standalone prod bundle — only raw SQL against
+// kumiko_event_consumers. Mirrors schema-cli.ts's shape (single runXCli(argv,
+// out) entry point, own DB connection) so `kumiko-consumer` ships the same
+// way `kumiko-schema` does.
+
+import { createConnection } from "./db/api";
+import { dbConnectionOptionsFromEnv } from "./db/connection";
+import { getConsumerState, restartConsumer } from "./pipeline";
+import { ensureTemporalPolyfill } from "./time";
+
+export type ConsumerCliOut = {
+  readonly log: (line: string) => void;
+  readonly err: (line: string) => void;
+};
+
+type ParsedConsumerCliArgs = {
+  readonly sub: string | undefined;
+  readonly name: string | undefined;
+  readonly instanceId: string | undefined;
+  readonly error: string | undefined;
+};
+
+// Single pass: pulls --instance-id (both "--instance-id <id>" and
+// "--instance-id=<id>") out of argv regardless of position, leaving the
+// remaining positionals for sub/name — instead of two independent
+// positional/flag reads that silently misparse "--instance-id" with no
+// value, the "=" form, or a flag placed before the positionals (#1412).
+function parseConsumerCliArgs(argv: readonly string[]): ParsedConsumerCliArgs {
+  const positionals: string[] = [];
+  let instanceId: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === undefined) continue;
+    if (arg === "--instance-id") {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        return {
+          sub: undefined,
+          name: undefined,
+          instanceId: undefined,
+          error: "--instance-id braucht einen Wert.",
+        };
+      }
+      instanceId = value;
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--instance-id=")) {
+      instanceId = arg.slice("--instance-id=".length);
+      continue;
+    }
+    positionals.push(arg);
+  }
+  return { sub: positionals[0], name: positionals[1], instanceId, error: undefined };
+}
+
+export async function runConsumerCli(
+  argv: readonly string[],
+  out: ConsumerCliOut,
+): Promise<number> {
+  // The standalone bundle never runs runProdApp/runDevApp's boot, which is
+  // where Temporal normally gets installed — ConsumerRecoveryState.updatedAt
+  // is a Temporal.Instant, so without this every subcommand throws "Temporal
+  // is not defined" (same failure mode as schema-cli, see its polyfill test).
+  await ensureTemporalPolyfill();
+  const parsed = parseConsumerCliArgs(argv);
+  if (parsed.error) {
+    out.err(`  ${parsed.error}`);
+    return 1;
+  }
+  const { sub, name, instanceId } = parsed;
+
+  if (sub !== "status" && sub !== "restart") {
+    // Unknown subcommand must be visible on stderr, not just a bare exit 1 —
+    // ops invocations piping `2>&1 >/dev/null` or log pipelines that only
+    // watch stderr would otherwise see a failure with zero explanation
+    // (#1412). A bare help call (no subcommand at all) is not an error, so
+    // it keeps exit 0 + stdout.
+    const write = sub === undefined ? out.log : out.err;
+    if (sub !== undefined) out.err(`  Unknown subcommand: ${sub}`);
+    write("");
+    write("  Subcommands:");
+    write("    status <name> [--instance-id <id>]   Zeigt Status + Cursor eines Consumers");
+    write("    restart <name> [--instance-id <id>]  Reaktiviert einen dead-Consumer (idle)");
+    write("");
+    return sub === undefined ? 0 : 1;
+  }
+
+  if (!name) {
+    out.err(`  Usage: consumer ${sub} <name> [--instance-id <id>]`);
+    return 1;
+  }
+
+  const dbUrl = process.env["DATABASE_URL"];
+  if (!dbUrl) {
+    out.err("  DATABASE_URL not set.");
+    return 1;
+  }
+  const { db, close } = await createConnection(dbUrl, dbConnectionOptionsFromEnv());
+  try {
+    if (sub === "status") {
+      const state = await getConsumerState(db, name, instanceId);
+      if (!state) {
+        out.err(`  Consumer "${name}" (instance_id="${instanceId ?? "__shared__"}") not found.`);
+        return 1;
+      }
+      out.log("");
+      out.log(`  ${state.name} (instance_id="${state.instanceId}")`);
+      out.log(`    status:      ${state.status}`);
+      out.log(`    cursor:      ${state.lastProcessedEventId}`);
+      out.log(`    attempts:    ${state.attempts}`);
+      out.log(`    rearmCount:  ${state.rearmCount}`);
+      out.log(`    lastError:   ${state.lastError ?? "-"}`);
+      out.log(`    updatedAt:   ${state.updatedAt.toString()}`);
+      out.log("");
+      return 0;
+    }
+
+    // restart
+    const result = await restartConsumer(db, name, instanceId);
+    out.log("");
+    out.log(`  ✓ ${result.name} (instance_id="${result.instanceId}") → ${result.status}`);
+    out.log("");
+    return 0;
+  } catch (e) {
+    out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+    return 1;
+  } finally {
+    await close();
+  }
+}

package/src/crypto/__tests__/blind-index.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine/factories";
+import {
+  blindIndexFieldName,
+  collectLookupableFields,
+  computeBlindIndex,
+  computeBlindIndexValues,
+  configureBlindIndexKey,
+  configuredBlindIndexKey,
+  decodeBlindIndexKey,
+  resetBlindIndexKeyForTests,
+} from "../blind-index";
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import {
+  configurePiiSubjectKms,
+  encryptPiiFieldValues,
+  PII_ERASED_SENTINEL,
+  resetPiiSubjectKmsForTests,
+} from "../pii-field-encryption";
+
+const UUID_A = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000a";
+const TEST_KEY_B64 = Buffer.alloc(32, 7).toString("base64");
+const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
+
+const userLikeEntity = createEntity({
+  fields: {
+    email: createTextField({ required: true, pii: true, lookupable: true }),
+    role: createTextField(),
+  },
+  table: "bidx_users",
+});
+
+afterEach(() => {
+  resetBlindIndexKeyForTests();
+  resetPiiSubjectKmsForTests();
+});
+
+describe("computeBlindIndex", () => {
+  test("deterministic, prefixed, byte-exact (no normalization)", () => {
+    const a = computeBlindIndex(TEST_KEY, "marc@example.com");
+    expect(a).toStartWith("kumiko-bidx:v1:");
+    expect(computeBlindIndex(TEST_KEY, "marc@example.com")).toBe(a);
+    expect(computeBlindIndex(TEST_KEY, "Marc@example.com")).not.toBe(a);
+  });
+
+  test("different keys produce different indexes", () => {
+    const otherKey = decodeBlindIndexKey(Buffer.alloc(32, 9).toString("base64"));
+    expect(computeBlindIndex(otherKey, "x")).not.toBe(computeBlindIndex(TEST_KEY, "x"));
+  });
+});
+
+describe("configureBlindIndexKey", () => {
+  test("rejects keys that are not 32 bytes", () => {
+    expect(() => configureBlindIndexKey(Buffer.alloc(16, 1).toString("base64"))).toThrow(
+      /32 bytes/,
+    );
+    expect(configuredBlindIndexKey()).toBeUndefined();
+  });
+
+  test("undefined clears the key", () => {
+    configureBlindIndexKey(TEST_KEY_B64);
+    expect(configuredBlindIndexKey()).toBeDefined();
+    configureBlindIndexKey(undefined);
+    expect(configuredBlindIndexKey()).toBeUndefined();
+  });
+});
+
+describe("collectLookupableFields", () => {
+  test("only text fields with lookupable: true", () => {
+    expect(collectLookupableFields(userLikeEntity)).toEqual(["email"]);
+  });
+});
+
+describe("computeBlindIndexValues", () => {
+  test("no key configured → empty (blind-indexing off)", async () => {
+    const out = await computeBlindIndexValues({ email: "a@b.c" }, ["email"]);
+    expect(out).toEqual({});
+  });
+
+  test("plaintext value → HMAC over the value itself", async () => {
+    configureBlindIndexKey(TEST_KEY_B64);
+    const out = await computeBlindIndexValues({ email: "a@b.c" }, ["email"]);
+    expect(out[blindIndexFieldName("email")]).toBe(computeBlindIndex(TEST_KEY, "a@b.c"));
+  });
+
+  test("absent field stays untouched, null value → NULL bidx", async () => {
+    configureBlindIndexKey(TEST_KEY_B64);
+    expect(await computeBlindIndexValues({ role: "admin" }, ["email"])).toEqual({});
+    expect(await computeBlindIndexValues({ email: null }, ["email"])).toEqual({
+      emailBidx: null,
+    });
+  });
+
+  test("ciphertext value → decrypt via configured KMS, HMAC over plaintext", async () => {
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+    configureBlindIndexKey(TEST_KEY_B64);
+    const stored = await encryptPiiFieldValues(
+      { id: UUID_A, email: "marc@example.com" },
+      userLikeEntity,
+      ["email"],
+      kms,
+      { requestId: "test" },
+    );
+    const out = await computeBlindIndexValues({ email: stored["email"] }, ["email"]);
+    expect(out["emailBidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
+  });
+
+  test("erased subject → NULL bidx (lookup stops matching)", async () => {
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+    configureBlindIndexKey(TEST_KEY_B64);
+    const stored = await encryptPiiFieldValues(
+      { id: UUID_A, email: "marc@example.com" },
+      userLikeEntity,
+      ["email"],
+      kms,
+      { requestId: "test" },
+    );
+    await kms.eraseKey({ kind: "user", userId: UUID_A });
+    const out = await computeBlindIndexValues({ email: stored["email"] }, ["email"]);
+    expect(out["emailBidx"]).toBeNull();
+  });
+
+  test("erased sentinel → NULL bidx", async () => {
+    configureBlindIndexKey(TEST_KEY_B64);
+    const out = await computeBlindIndexValues({ email: PII_ERASED_SENTINEL }, ["email"]);
+    expect(out["emailBidx"]).toBeNull();
+  });
+});

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