@cosmicdrift/kumiko-framework 0.118.0 → 0.120.0

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/db/table-builder.ts

@@ -69,7 +69,13 @@ function fieldToColumns(
       const base = text(snakeName);
       const withDefault =
         "default" in field && field.default !== undefined ? base.default(field.default) : base;
-      return { [name]: field.required ? withDefault.notNull() : withDefault };
+      const mainCol = { [name]: field.required ? withDefault.notNull() : withDefault };
+      // lookupable → nullable HMAC-Blind-Index-Spalte (lock-step mit
+      // fieldToColumnMeta in entity-table-meta.ts).
+      if (field.type === "text" && field.lookupable === true) {
+        return { ...mainCol, [`${name}Bidx`]: text(`${snakeName}_bidx`) };
+      }
+      return mainCol;
     }
     case "boolean":
       return {
@@ -272,63 +278,72 @@ type NullCol<_T> = ColumnHandle & { readonly __notNull: false };
 // columns (resolved via FileRef table). `notNull` propagiert von
 // `field.required` (literal preserved by createXField generics).
 type ColumnsForField<K extends string, F extends FieldDefinition> = F extends {
-  type: "text" | "select" | "tz";
+  type: "text";
+  lookupable: true;
 }
-  ? F extends { required: true }
-    ? { readonly [P in K]: Col<string> }
-    : { readonly [P in K]: NullCol<string> }
-  : F extends { type: "boolean" }
-    ? // boolean default OR required → notNull (DB has DEFAULT, structurally never-null)
-      F extends { default: boolean } | { required: true }
-      ? { readonly [P in K]: Col<boolean> }
-      : { readonly [P in K]: NullCol<boolean> }
-    : F extends { type: "multiSelect" }
-      ? // jsonb default `[]`, immer notNull
-        { readonly [P in K]: Col<readonly string[]> }
-      : F extends { type: "number" }
-        ? F extends { required: true }
-          ? { readonly [P in K]: Col<number> }
-          : { readonly [P in K]: NullCol<number> }
-        : F extends { type: "decimal" }
+  ? (F extends { required: true }
+      ? { readonly [P in K]: Col<string> }
+      : { readonly [P in K]: NullCol<string> }) & {
+      readonly [P in `${K}Bidx`]: NullCol<string>;
+    }
+  : F extends {
+        type: "text" | "select" | "tz";
+      }
+    ? F extends { required: true }
+      ? { readonly [P in K]: Col<string> }
+      : { readonly [P in K]: NullCol<string> }
+    : F extends { type: "boolean" }
+      ? // boolean default OR required → notNull (DB has DEFAULT, structurally never-null)
+        F extends { default: boolean } | { required: true }
+        ? { readonly [P in K]: Col<boolean> }
+        : { readonly [P in K]: NullCol<boolean> }
+      : F extends { type: "multiSelect" }
+        ? // jsonb default `[]`, immer notNull
+          { readonly [P in K]: Col<readonly string[]> }
+        : F extends { type: "number" }
           ? F extends { required: true }
             ? { readonly [P in K]: Col<number> }
             : { readonly [P in K]: NullCol<number> }
-          : F extends { type: "money" }
+          : F extends { type: "decimal" }
             ? F extends { required: true }
-              ? { readonly [P in K]: Col<number> } & {
-                  readonly [P in `${K}Currency`]: Col<string>;
-                }
-              : { readonly [P in K]: NullCol<number> } & {
-                  readonly [P in `${K}Currency`]: Col<string>;
-                }
-            : F extends { type: "reference"; multiple: true }
-              ? { readonly [P in K]: Col<readonly string[]> }
-              : F extends { type: "reference" }
-                ? F extends { required: true }
-                  ? { readonly [P in K]: Col<string> }
-                  : { readonly [P in K]: NullCol<string> }
-                : F extends { type: "embedded" }
-                  ? // jsonb default `{}`, immer notNull
-                    { readonly [P in K]: Col<Readonly<Record<string, unknown>>> }
-                  : F extends { type: "date" | "timestamp" }
-                    ? F extends { required: true }
-                      ? { readonly [P in K]: Col<Temporal.Instant> }
-                      : { readonly [P in K]: NullCol<Temporal.Instant> }
-                    : F extends { type: "locatedTimestamp" }
+              ? { readonly [P in K]: Col<number> }
+              : { readonly [P in K]: NullCol<number> }
+            : F extends { type: "money" }
+              ? F extends { required: true }
+                ? { readonly [P in K]: Col<number> } & {
+                    readonly [P in `${K}Currency`]: Col<string>;
+                  }
+                : { readonly [P in K]: NullCol<number> } & {
+                    readonly [P in `${K}Currency`]: Col<string>;
+                  }
+              : F extends { type: "reference"; multiple: true }
+                ? { readonly [P in K]: Col<readonly string[]> }
+                : F extends { type: "reference" }
+                  ? F extends { required: true }
+                    ? { readonly [P in K]: Col<string> }
+                    : { readonly [P in K]: NullCol<string> }
+                  : F extends { type: "embedded" }
+                    ? // jsonb default `{}`, immer notNull
+                      { readonly [P in K]: Col<Readonly<Record<string, unknown>>> }
+                    : F extends { type: "date" | "timestamp" }
                       ? F extends { required: true }
-                        ? { readonly [P in `${K}Utc`]: Col<Temporal.Instant> } & {
-                            readonly [P in `${K}Tz`]: Col<string>;
-                          }
-                        : { readonly [P in `${K}Utc`]: NullCol<Temporal.Instant> } & {
-                            readonly [P in `${K}Tz`]: NullCol<string>;
-                          }
-                      : F extends { type: "file" | "image" }
+                        ? { readonly [P in K]: Col<Temporal.Instant> }
+                        : { readonly [P in K]: NullCol<Temporal.Instant> }
+                      : F extends { type: "locatedTimestamp" }
                         ? F extends { required: true }
-                          ? { readonly [P in K]: Col<string> }
-                          : { readonly [P in K]: NullCol<string> }
-                        : F extends { type: "files" | "images" }
-                          ? Record<never, never>
-                          : never;
+                          ? { readonly [P in `${K}Utc`]: Col<Temporal.Instant> } & {
+                              readonly [P in `${K}Tz`]: Col<string>;
+                            }
+                          : { readonly [P in `${K}Utc`]: NullCol<Temporal.Instant> } & {
+                              readonly [P in `${K}Tz`]: NullCol<string>;
+                            }
+                        : F extends { type: "file" | "image" }
+                          ? F extends { required: true }
+                            ? { readonly [P in K]: Col<string> }
+                            : { readonly [P in K]: NullCol<string> }
+                          : F extends { type: "files" | "images" }
+                            ? Record<never, never>
+                            : never;
 
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
   k: infer I,
@@ -526,6 +541,18 @@ export function buildEntityTable<E extends EntityDefinition>(
           ).on(column);
         }
       }
+      // lookupable-Felder: Index auf der bidx-Spalte (lock-step mit
+      // buildEntityTableMeta).
+      const bidxFieldByField = new Map<string, string>();
+      for (const [name, field] of Object.entries(entity.fields)) {
+        if (field.type !== "text" || field.lookupable !== true) continue;
+        bidxFieldByField.set(name, `${name}Bidx`);
+        const column = tHandle[`${name}Bidx`];
+        if (column) {
+          const idxName = `${tableName}_${toSnakeCase(name)}_bidx_idx`;
+          indexes[idxName] = index(idxName).on(column);
+        }
+      }
       // entity.indexes = composite/unique-Indices die der Author explizit
       // deklariert hat. Spalten werden via field-name (camelCase) angesprochen,
       // der Index-Name folgt der Convention <table>_<col1>_<col2>_<unique|idx>
@@ -546,6 +573,26 @@ export function buildEntityTable<E extends EntityDefinition>(
           chain = chain.where(def.where as SqlExpression);
         }
         indexes[indexName] = chain;
+        // Partielles bidx-Pendant für unique-Indices über lookupable-Spalten
+        // (lock-step mit buildEntityTableMeta).
+        if (def.unique === true && def.where === undefined) {
+          const bidxFieldNames = def.columns.map((c) => bidxFieldByField.get(c) ?? c);
+          if (bidxFieldNames.some((c, i) => c !== def.columns[i])) {
+            const bidxCols = bidxFieldNames
+              .map((c) => tHandle[c])
+              .filter((col): col is ColumnHandle => col !== undefined);
+            if (bidxCols.length === bidxFieldNames.length) {
+              const whereText = bidxFieldNames
+                .filter((c, i) => c !== def.columns[i])
+                .map((c) => `"${toSnakeCase(c)}" IS NOT NULL`)
+                .join(" AND ");
+              const partialWhere: SqlExpression = { kind: "sql-expr", text: whereText, params: [] };
+              indexes[`${indexName}_bidx`] = uniqueIndex(`${indexName}_bidx`)
+                .on(...bidxCols)
+                .where(partialWhere);
+            }
+          }
+        }
       }
       return indexes;
     },

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

@@ -133,19 +133,36 @@ describe("validateBoot — PII annotations", () => {
     );
   });
 
-  test("userOwned.ownerField pointing to non-reference field throws", () => {
+  test("userOwned.ownerField on a text field passes (ES userId-by-convention)", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(
         "comment",
         createEntity({
           fields: {
-            body: createLongTextField({ userOwned: { ownerField: "authorName" } }),
-            authorName: createTextField(),
+            body: createLongTextField({ userOwned: { ownerField: "authorId" } }),
+            authorId: createTextField(),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("userOwned.ownerField pointing to a non-id-capable field throws", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "comment",
+        createEntity({
+          fields: {
+            body: createLongTextField({ userOwned: { ownerField: "isPublic" } }),
+            isPublic: { type: "boolean" },
           },
         }),
       );
     });
-    expect(() => validateBoot([feature])).toThrow(/must be a reference field, got type "text"/);
+    expect(() => validateBoot([feature])).toThrow(
+      /must be a reference or text \(userId\) field, got type "boolean"/,
+    );
   });
 
   test("userOwned.ownerField referencing non-user entity warns", () => {
@@ -568,3 +585,77 @@ describe("validateBoot — retention", () => {
     expect(matchingWarn).toBeUndefined();
   });
 });
+
+describe("validateBoot — lookupable / blind-index (#818)", () => {
+  test("lookupable on subject-annotated text field passes", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            email: createTextField({ pii: true, lookupable: true }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("lookupable without subject annotation throws", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "doc",
+        createEntity({
+          fields: {
+            slug: createTextField({ lookupable: true }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(/lookupable.*without a subject annotation/);
+  });
+
+  test("lookupable on non-text field throws", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "person",
+        createEntity({
+          fields: {
+            // longText carries PiiAnnotations too — lookupable must still be rejected.
+            bio: createLongTextField({ userOwned: { ownerField: "ownerId" }, lookupable: true }),
+            ownerId: createTextField({ required: true }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(/only apply to text fields/);
+  });
+
+  test("searchable combined with a subject annotation throws", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            displayName: createTextField({ pii: true, searchable: true }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(/searchable.*cannot work/);
+  });
+
+  test("sortable combined with a subject annotation throws", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            email: createTextField({ pii: true, sortable: true }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(/sortable.*cannot work/);
+  });
+});

package/src/engine/__tests__/unmanaged-table.test.ts

@@ -3,7 +3,11 @@
 // drizzle migrate-runner). See define-feature.ts / DX-4.
 
 import { describe, expect, test } from "bun:test";
-import { defineUnmanagedTable, resolveTableName } from "../../db/entity-table-meta";
+import {
+  buildEntityTableMeta,
+  defineUnmanagedTable,
+  resolveTableName,
+} from "../../db/entity-table-meta";
 import { defineFeature } from "../define-feature";
 import { createEntity, createTextField } from "../index";
 import { createRegistry } from "../registry";
@@ -125,3 +129,44 @@ describe("createRegistry — unmanagedTable aggregation", () => {
     );
   });
 });
+
+describe("createRegistry — unmanaged tables with PII-annotated fields (#820)", () => {
+  const piiEntity = createEntity({
+    table: "ut_pii_probe",
+    fields: {
+      userId: createTextField({ required: true }),
+      ip: createTextField({ userOwned: { ownerField: "userId" } }),
+    },
+  });
+  const piiMeta = buildEntityTableMeta("ut-pii-probe", piiEntity);
+
+  test("buildEntityTableMeta records the subject-annotated field names", () => {
+    expect(piiMeta.piiSubjectFields).toEqual(["ip"]);
+  });
+
+  test("rejects a PII-carrying unmanaged table without piiEncryptedOnWrite", () => {
+    const feat = defineFeature("probe", (r) => {
+      r.unmanagedTable(piiMeta, { reason: "direct-write store" });
+    });
+    expect(() => createRegistry([feat])).toThrow(
+      /has PII-annotated fields \(ip\) but direct writes bypass the executor's PII encryption/,
+    );
+  });
+
+  test("accepts it once the feature declares piiEncryptedOnWrite", () => {
+    const feat = defineFeature("probe", (r) => {
+      r.unmanagedTable(piiMeta, {
+        reason: "direct-write store",
+        piiEncryptedOnWrite: true,
+      });
+    });
+    expect(() => createRegistry([feat])).not.toThrow();
+  });
+
+  test("a PII-free unmanaged table needs no declaration", () => {
+    const feat = defineFeature("probe", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "plain store" });
+    });
+    expect(() => createRegistry([feat])).not.toThrow();
+  });
+});