@cosmicdrift/kumiko-framework 0.116.1 → 0.119.0

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

@@ -1,4 +1,14 @@
 import { requestContext } from "../api/request-context";
+import {
+  collectPiiSubjectFields,
+  computeBlindIndex,
+  configuredBlindIndexKey,
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+  encryptPiiFieldValues,
+  type KmsContext,
+  type LocalKeyKmsAdapter,
+} from "../crypto";
 import { executeRawQuery } from "../db/queries/raw-sql";
 import type { WhereObject } from "../db/query";
 import { coerceRow, extractTableInfo, selectMany } from "../db/query";
@@ -121,6 +131,8 @@ export type EventStoreExecutorOptions = {
   entityCache?: EntityCache;
   /** Override the boot-injected cipher for fields marked `encrypted: true`. */
   encryption?: EnvelopeCipher;
+  /** Override the boot-injected subject KMS for pii-annotated fields. */
+  kms?: LocalKeyKmsAdapter;
 };
 
 // F8 helper: PG-23505 (unique-violation) catched aus applyEntityEvent
@@ -307,28 +319,64 @@ export function createEventStoreExecutor(
   const encryptedFields = collectEncryptedFieldNames(entity);
   const hasEncryptedFields = encryptedFields.size > 0;
 
+  const piiSubjectFields = collectPiiSubjectFields(entity);
+  const hasPiiFields = piiSubjectFields.length > 0;
+
   function fieldCipher(): EnvelopeCipher {
     if (options.encryption) return options.encryption;
     return resolveEntityFieldEncryption();
   }
 
+  // No adapter configured = crypto-shredding off; pii fields stay plaintext
+  // (pre-#724 behavior). The hard boot gate ships with the prod-grade
+  // PgKmsAdapter (phase E).
+  function piiKms(): LocalKeyKmsAdapter | undefined {
+    return options.kms ?? configuredPiiSubjectKms();
+  }
+
+  function kmsContextFor(user?: SessionUser): KmsContext {
+    return {
+      requestId: requestContext.get()?.requestId ?? "event-store-executor",
+      ...(user && { tenantId: user.tenantId, userId: String(user.id) }),
+    };
+  }
+
   // Async on purpose: the envelope cipher wraps/unwraps DEKs via the
   // MasterKeyProvider. Callers MUST await — a missed await here writes
   // "[object Promise]" into the projection, which the Promise return
   // types turn into a compile error at every call site.
   async function encryptForStorage(
     row: Record<string, unknown>,
-    onlyKeys?: Iterable<string>,
+    user: SessionUser,
+    opts?: { onlyKeys?: Iterable<string>; subjectSource?: Record<string, unknown> },
   ): Promise<Record<string, unknown>> {
-    if (!hasEncryptedFields) return row;
-    return encryptEntityFieldValues(row, encryptedFields, fieldCipher(), {
-      ...(onlyKeys !== undefined && { onlyKeys }),
-    });
+    let out = row;
+    if (hasEncryptedFields) {
+      out = await encryptEntityFieldValues(out, encryptedFields, fieldCipher(), {
+        ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
+      });
+    }
+    const kms = piiKms();
+    if (hasPiiFields && kms) {
+      out = await encryptPiiFieldValues(out, entity, piiSubjectFields, kms, kmsContextFor(user), {
+        tenantId: user.tenantId,
+        ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
+        ...(opts?.subjectSource !== undefined && { subjectSource: opts.subjectSource }),
+      });
+    }
+    return out;
   }
 
   async function decryptForRead(row: Record<string, unknown>): Promise<Record<string, unknown>> {
-    if (!hasEncryptedFields) return row;
-    return decryptEntityFieldValues(row, encryptedFields, fieldCipher());
+    let out = row;
+    if (hasEncryptedFields) {
+      out = await decryptEntityFieldValues(out, encryptedFields, fieldCipher());
+    }
+    const kms = piiKms();
+    if (hasPiiFields && kms) {
+      out = await decryptPiiFieldValues(out, piiSubjectFields, kms, kmsContextFor());
+    }
+    return out;
   }
 
   function applyDefaults(payload: Record<string, unknown>): Record<string, unknown> {
@@ -469,7 +517,12 @@ export function createEventStoreExecutor(
       // Alle Compound-Types (locatedTimestamp, money, ...) gehen durch
       // dieselbe Pipeline. Caller schickt combined API-Form, Framework
       // speichert flat DB-Form. Siehe db/compound-types.ts.
-      const flatData = await encryptForStorage(flattenCompoundTypes(data, entity));
+      // subjectSource carries the freshly minted aggregateId: the create
+      // payload has no id column, but a pii:true self-subject resolves from it.
+      const flatCreateData = flattenCompoundTypes(data, entity);
+      const flatData = await encryptForStorage(flatCreateData, user, {
+        subjectSource: { ...flatCreateData, id: aggregateId },
+      });
 
       // 1. Append event (same TX as the projection write — both must succeed
       //    or both roll back; the dispatcher wraps both in one transaction).
@@ -563,7 +616,9 @@ export function createEventStoreExecutor(
           previous: {},
           isNew: true,
           entityName,
-          event,
+          // Persisted event carries ciphertext by design — the caller-facing
+          // echo must be plaintext like every other response field (#820).
+          event: { ...event, payload: stripSensitive(flatCreateData) },
         },
       };
     },
@@ -650,10 +705,13 @@ export function createEventStoreExecutor(
 
       try {
         // Compound-Types Auto-Convert (alle in einem Pass).
-        const flatChanges = await encryptForStorage(
-          flattenCompoundTypes(payload.changes, entity),
-          Object.keys(payload.changes),
-        );
+        // subjectSource: partial changes may carry a pii field without its
+        // ownerField — the merged row still names the subject.
+        const flatChangesPlain = flattenCompoundTypes(payload.changes, entity);
+        const flatChanges = await encryptForStorage(flatChangesPlain, user, {
+          onlyKeys: Object.keys(payload.changes),
+          subjectSource: mergedNew,
+        });
 
         // The event payload carries BOTH `changes` (what the user asked for) AND
         // `previous` (the pre-update row). Cross-aggregate projections need the
@@ -673,7 +731,7 @@ export function createEventStoreExecutor(
           type: entityEventName(entityName, "updated"),
           payload: {
             changes: stripSensitive(flatChanges),
-            previous: stripSensitive(await encryptForStorage(previous)),
+            previous: stripSensitive(await encryptForStorage(previous, user)),
           },
           metadata: buildEventMetadata(user),
         });
@@ -717,7 +775,13 @@ export function createEventStoreExecutor(
             previous,
             isNew: false,
             entityName,
-            event,
+            event: {
+              ...event,
+              payload: {
+                changes: stripSensitive(flatChangesPlain),
+                previous: stripSensitive(previous),
+              },
+            },
           },
         };
       } catch (e) {
@@ -783,7 +847,7 @@ export function createEventStoreExecutor(
         tenantId: streamTenantFor(user),
         expectedVersion: currentVersion,
         type: entityEventName(entityName, "deleted"),
-        payload: { previous: stripSensitive(await encryptForStorage(existing)) },
+        payload: { previous: stripSensitive(await encryptForStorage(existing, user)) },
         metadata: buildEventMetadata(user),
       });
 
@@ -805,7 +869,13 @@ export function createEventStoreExecutor(
 
       return {
         isSuccess: true,
-        data: { kind: "delete", id: payload.id, data: existing, entityName, event },
+        data: {
+          kind: "delete",
+          id: payload.id,
+          data: existing,
+          entityName,
+          event: { ...event, payload: { previous: stripSensitive(existing) } },
+        },
       };
     },
 
@@ -846,7 +916,9 @@ export function createEventStoreExecutor(
         tenantId: streamTenantFor(user),
         expectedVersion: currentVersion,
         type: entityEventName(entityName, "forgotten"),
-        payload: { previous: stripSensitive(existing) },
+        // Re-encrypt like delete(): `existing` came decrypted from loadById —
+        // plaintext must not land in the immutable log, least of all on forget.
+        payload: { previous: stripSensitive(await encryptForStorage(existing, user)) },
         metadata: buildEventMetadata(user),
       });
 
@@ -863,7 +935,13 @@ export function createEventStoreExecutor(
 
       return {
         isSuccess: true,
-        data: { kind: "delete", id: payload.id, data: existing, entityName, event },
+        data: {
+          kind: "delete",
+          id: payload.id,
+          data: existing,
+          entityName,
+          event: { ...event, payload: { previous: stripSensitive(existing) } },
+        },
       };
     },
 
@@ -947,6 +1025,7 @@ export function createEventStoreExecutor(
         rehydrateCompoundTypes(restored as DbRow, entity) as DbRow,
       );
 
+      const previousPlain = await decryptForRead(data);
       return {
         isSuccess: true,
         data: {
@@ -954,10 +1033,10 @@ export function createEventStoreExecutor(
           id: payload.id,
           data: restoredHydrated,
           changes: { isDeleted: false },
-          previous: await decryptForRead(data),
+          previous: previousPlain,
           isNew: false,
           entityName,
-          event,
+          event: { ...event, payload: { previous: stripSensitive(previousPlain) } },
         },
       };
     },
@@ -1067,8 +1146,19 @@ export function createEventStoreExecutor(
               whereSql.push(`${colSql(field)} ${opSym} $${params.length}`);
             }
           } else {
-            params.push(value);
-            whereSql.push(`${colSql(field)} = $${params.length}`);
+            // Blind-Index-OR-Rewrite (#818), lock-step mit buildWhereClause
+            // in bun-db/query.ts — Equality auf lookupable-Feldern matcht
+            // Klartext-Arm ODER HMAC-Arm.
+            const bidxKey = configuredBlindIndexKey();
+            if (bidxKey !== undefined && typeof value === "string" && table[`${field}Bidx`]) {
+              params.push(value, computeBlindIndex(bidxKey, value));
+              whereSql.push(
+                `(${colSql(field)} = $${params.length - 1} OR ${colSql(`${field}Bidx`)} = $${params.length})`,
+              );
+            } else {
+              params.push(value);
+              whereSql.push(`${colSql(field)} = $${params.length}`);
+            }
           }
         }
       };
@@ -1086,21 +1176,26 @@ export function createEventStoreExecutor(
       const listSql = `SELECT * FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
 
       const rawRows = await executeRawQuery<Record<string, unknown>>(db.raw, listSql, params);
-      // Read-Side rehydrate pro Row + snake→camel coercion für driver-agnostic Feldnamen
+      // Read-Side rehydrate pro Row + snake→camel coercion für driver-agnostic Feldnamen.
+      // Coerce BEFORE decrypt: the raw SELECT * rows carry snake_case column
+      // names, while the encrypted/pii field lists are camelCase — decrypting
+      // first silently skipped every multi-word field (ciphertext leaked to
+      // the caller).
       const tableInfo = extractTableInfo(table);
-      const rows = await Promise.all(
-        rawRows.map(async (r) =>
-          coerceRow(await decryptForRead(rehydrateCompoundTypes(r, entity)), tableInfo),
-        ),
+      const encryptedRows = rawRows.map((r) =>
+        coerceRow(rehydrateCompoundTypes(r, entity), tableInfo),
       );
+      const rows = await Promise.all(encryptedRows.map((r) => decryptForRead(r)));
 
       // list rows carry the READ-ROW version (display-only), never an optimistic-lock
       // base — edit flows reload via detail(), which reconciles the stream version.
+      // Cache the still-encrypted form: same at-rest guarantee as detail()'s
+      // encryptForStorage round-trip, without paying a re-encrypt.
       if (entityCache && entityName && rows.length > 0) {
         await entityCache.mset(
           user.tenantId,
           entityName,
-          rows.map((r) => ({ id: r["id"] as EntityId, data: r })), // @cast-boundary engine-payload
+          encryptedRows.map((r) => ({ id: r["id"] as EntityId, data: r })), // @cast-boundary engine-payload
         );
       }
 
@@ -1180,7 +1275,7 @@ export function createEventStoreExecutor(
           user.tenantId,
           entityName,
           payload.id,
-          await encryptForStorage(coerced),
+          await encryptForStorage(coerced, user),
         );
       }
 

package/src/db/index.ts

@@ -1,4 +1,5 @@
 export { assertExistsIn } from "./assert-exists-in";
+export { nullBlindIndexesForSubject } from "./blind-index-cleanup";
 export { collectTableMetas } from "./collect-table-metas";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
 export { seedConfigValues } from "./config-seed";

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