@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/db/blind-index-cleanup.ts

@@ -0,0 +1,55 @@
+// Sofortiges Blind-Index-Nulling nach einem Subject-Erase (#818).
+//
+// Nach kms.eraseKey ist der Ciphertext unlesbar, aber die deterministische
+// bidx-Spalte bliebe bis zum nächsten Write/Rebuild matchbar — ein
+// Linkage-Fenster ("hat irgendeine Row den Wert X"). Dieser Sweep schließt
+// es sofort: der Ciphertext nennt sein Subject inline
+// (kumiko-pii:v1:<subjectKey>:...), also findet ein LIKE-Prefix-Match exakt
+// die Rows des erased Subjects — pro lookupable-Feld ein UPDATE.
+//
+// Rows, die der Forget-Lauf ohnehin via Executor löscht/anonymisiert,
+// bekommen ihren bidx dort automatisch neu berechnet; dieser Sweep deckt
+// die liegen bleibenden Rows ab (fremde Entities mit userOwned-Feldern).
+
+import { collectLookupableFields } from "../crypto/blind-index";
+import type { FeatureDefinition } from "../engine/types";
+import { toSnakeCase } from "../utils/case";
+import type { DbRunner } from "./connection";
+import { resolveTableName } from "./entity-table-meta";
+import { executeRawQuery } from "./queries/raw-sql";
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+function escapeLikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, (m) => `\\${m}`);
+}
+
+export async function nullBlindIndexesForSubject(
+  db: DbRunner,
+  features: ReadonlyMap<string, FeatureDefinition>,
+  subjectKey: string,
+): Promise<void> {
+  // "v%" matches any format version (v1 no-AAD, v2 AAD-bound, #1263) — the
+  // subject key placement is stable across versions.
+  const likePattern = `kumiko-pii:v%:${escapeLikePattern(subjectKey)}:%`;
+  for (const feature of features.values()) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+      const lookupable = collectLookupableFields(entity);
+      if (lookupable.length === 0) continue;
+      // Kein featureName-Prefix — der Dispatcher baut Entity-Tables ohne
+      // (buildEntityTable ohne featureName-Option), der Sweep muss dieselben
+      // Namen treffen.
+      const tableName = resolveTableName(entityName, entity, undefined);
+      for (const fieldName of lookupable) {
+        const snake = toSnakeCase(fieldName);
+        await executeRawQuery(
+          db,
+          `UPDATE ${quoteIdent(tableName)} SET ${quoteIdent(`${snake}_bidx`)} = NULL WHERE ${quoteIdent(snake)} LIKE $1`,
+          [likePattern],
+        );
+      }
+    }
+  }
+}

package/src/db/bun-provider.ts

@@ -8,9 +8,9 @@
 // Bun.SQL hat kein LISTEN — postgres-js-Peer für event-dispatcher.
 
 import postgres from "postgres";
-import type { DbConnection, DbConnectionOptions } from "./api";
+import type { DbConnectionOptions, DbPoolHandle } from "./api";
 
-export function createBunConnection(url: string, options: DbConnectionOptions = {}): DbConnection {
+export function createBunConnection(url: string, options: DbConnectionOptions = {}): DbPoolHandle {
   const bunOpts: { max?: number; idleTimeout?: number; connectionTimeout?: number } = {};
   if (options.maxConnections !== undefined) bunOpts.max = options.maxConnections;
   if (options.idleTimeoutSeconds !== undefined) bunOpts.idleTimeout = options.idleTimeoutSeconds;

package/src/db/collect-table-metas.ts

@@ -1,10 +1,9 @@
 // collectTableMetas — kanonische ENTITY_METAS-Quelle für `kumiko schema
 // generate`. Erfasst dieselben Tabellen-Quellen wie der setupTestStack-
-// auto-push (entities, unmanagedTables, projections, multiStreamProjections,
-// rawTables) — die frühere Template-Variante sammelte nur entities +
-// unmanagedTables, wodurch projection-only-Tabellen (z.B. billing-foundation
-// read_subscriptions) nie in Migrations landeten und der erste Prod-Write
-// crashte (#255).
+// auto-push (entities, storeTables, projections, multiStreamProjections) —
+// die frühere Template-Variante sammelte nur entities + storeTables, wodurch
+// projection-only-Tabellen (z.B. billing-foundation read_subscriptions) nie
+// in Migrations landeten und der erste Prod-Write crashte (#255).
 
 import type { FeatureDefinition } from "../engine/types";
 import { compareByCodepoint } from "../utils";
@@ -60,11 +59,11 @@ export function collectTableMetas(
       metas.push(meta);
       byName.set(meta.tableName, { meta, origin: `entity "${name}" (${feature.name})` });
     }
-    for (const entry of Object.values(feature.unmanagedTables)) {
+    for (const entry of Object.values(feature.storeTables)) {
       metas.push(entry.meta);
       byName.set(entry.meta.tableName, {
         meta: entry.meta,
-        origin: `unmanagedTable "${entry.name}" (${feature.name})`,
+        origin: `storeTable "${entry.name}" (${feature.name})`,
       });
     }
   }

package/src/db/config-seed.ts

@@ -2,8 +2,8 @@ import { v5 as uuidv5 } from "uuid";
 import type { EntityDefinition } from "../engine";
 import { createSystemUser, SYSTEM_TENANT_ID } from "../engine";
 import type { ConfigSeedDef, Registry } from "../engine/types";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher";
 import type { DbConnection } from "./connection";
-import type { EncryptionProvider } from "./encryption";
 import { createEventStoreExecutor } from "./event-store-executor";
 import type { EntityTable } from "./table-builder";
 import { createTenantDb } from "./tenant-db";
@@ -30,7 +30,7 @@ export async function seedConfigValues<E extends EntityDefinition>(
   entity: E,
   registry: Registry,
   db: DbConnection,
-  encryption?: EncryptionProvider,
+  cipher?: EnvelopeCipher,
 ): Promise<{ created: number; skipped: number }> {
   let created = 0;
   let skipped = 0;
@@ -48,12 +48,12 @@ export async function seedConfigValues<E extends EntityDefinition>(
       continue;
     }
 
-    // Encrypted keys without an encryption provider would silently write
-    // plaintext to a column the resolver later tries to decrypt — fail
-    // loud at boot, not on first read in prod.
-    if (keyDef.encrypted && !encryption) {
+    // Encrypted keys without a cipher would silently write plaintext to a
+    // column the resolver later tries to decrypt — fail loud at boot, not
+    // on first read in prod.
+    if (keyDef.encrypted && !cipher) {
       throw new Error(
-        `seedConfigValues: key "${seed.key}" is encrypted but no EncryptionProvider was supplied.`,
+        `seedConfigValues: key "${seed.key}" is encrypted but no EnvelopeCipher was supplied.`,
       );
     }
 
@@ -77,8 +77,8 @@ export async function seedConfigValues<E extends EntityDefinition>(
     const aggregateId = uuidv5(idSource, CONFIG_SEED_NS);
 
     let value = JSON.stringify(seed.value);
-    if (keyDef.encrypted && encryption) {
-      value = encryption.encrypt(value);
+    if (keyDef.encrypted && cipher) {
+      value = await cipher.encrypt(value, { tenantId });
     }
 
     const payload: Record<string, unknown> = {

package/src/db/connection.ts

@@ -1,20 +1,15 @@
 // DB-Connection-Types: provider-agnostic via db/api.ts.
 // createConnection delegiert an postgres-provider (default) oder bun-provider (DB_PROVIDER=bun).
+import type { DbConnection, PgClient } from "@cosmicdrift/kumiko-types/db-connection";
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse";
 
-export { createConnection, type DbConnectionOptions } from "./api";
-
-// Legacy Types — für Aufrufer die direkt diese Module importieren
-// biome-ignore lint/suspicious/noExplicitAny: Bun.SQL global type
-export type DbConnection = ReturnType<typeof postgres> | any;
-// biome-ignore lint/suspicious/noExplicitAny: postgres-js namespace lookup
-export type DbTx = postgres.TransactionSql<any> | any;
-export type DbRunner = DbConnection | DbTx;
-export type DbRow = Record<string, unknown>;
-export type PgClient = ReturnType<typeof postgres>;
-
-export type PgListenClient = ReturnType<typeof postgres>;
+// Raw client types (postgres-js | Bun.SQL) — the name used across query/
+// event-store/pipeline call sites. The structural pool handle from ./api is
+// `DbPoolHandle` (createConnection's return type) to avoid colliding with this.
+export type * from "@cosmicdrift/kumiko-types/db-connection";
+export type { DbConnectionOptions, DbPoolHandle } from "./api";
+export { createConnection } from "./api";
 
 // Legacy: postgres-js only. Neue Aufrufer: createConnection() aus api.ts.
 // guard:dup-ok — andere Layer als createPgConnection (gibt DbConnection zurück, nicht postgres-Instanz)

package/src/db/cursor.ts

@@ -1,21 +1,4 @@
-import type { EntityId, TenantId } from "../engine/types/identifiers";
-
-export type CursorQueryOptions = {
-  tenantId: TenantId;
-  cursor?: string;
-  limit?: number;
-  filterIds?: readonly EntityId[];
-  sort?: string;
-  sortDirection?: "asc" | "desc";
-};
-
-export type CursorResult<T> = {
-  rows: T[];
-  nextCursor: string | null;
-  /** Optional total row count — nur present wenn der Caller `totalCount: true`
-   *  in der Query setzt. */
-  total?: number;
-};
+export type { CursorQueryOptions, CursorResult } from "@cosmicdrift/kumiko-types/cursor-types";
 
 // String-basiert damit UUIDs (Default seit Sprint F) + Integer-Auto-Increment
 // durch denselben Cursor-Pfad laufen. UUIDv7 erfüllt die lex-Monotonie

package/src/db/dialect.ts

@@ -12,7 +12,18 @@
 //
 // The framework no longer imports drizzle-orm at runtime — schema-files
 // use only this module.
-
+//
+// Static import, not the ambient global: Bun doesn't expose Temporal on
+// globalThis, so instantToDriver crashed on timestamptz writes (#1480).
+
+import {
+  type ColumnHandle,
+  KUMIKO_COLUMNS_SYMBOL,
+  KUMIKO_META_SYMBOL,
+  KUMIKO_NAME_SYMBOL,
+  type SchemaTable,
+} from "@cosmicdrift/kumiko-types/schema-table-types";
+import { Temporal } from "temporal-polyfill";
 import type {
   ColumnMeta,
   CompositePrimaryKeyMeta,
@@ -21,6 +32,8 @@ import type {
   PgType,
 } from "./entity-table-meta";
 
+export type { ColumnHandle, SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+
 // Public type aliases — historical compat for callers that used to import
 // these from drizzle-orm/pg-core. SelectQuery is no longer a meaningful
 // shape (no chain builder); TableColumns is the new SchemaTable union.
@@ -29,31 +42,6 @@ export type TableColumns<_T = any> = SchemaTable;
 // biome-ignore lint/suspicious/noExplicitAny: legacy type — chain API is gone
 export type SelectQuery = any;
 
-// Column handle exposed on the SchemaTable. The `name` is the SQL column
-// name (snake_case); legacy code accesses `table.fieldName.name` to
-// produce raw SQL.
-export type ColumnHandle = {
-  readonly name: string;
-  readonly pgType: PgType;
-  readonly getSQLType: () => string;
-};
-
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
-// Shadow-proof handle on the EntityTableMeta. The column handles below are
-// spread as enumerable props, so an entity field named `source`/`columns`/
-// `tableName`/… would overwrite the matching meta key. extractTableInfo reads
-// the canonical meta from this symbol instead of the (shadowable) props.
-const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
-
-// SchemaTable — opaque shape with both EntityTableMeta + Symbol-based
-// introspection. Returned by `table(...)`.
-export type SchemaTable = EntityTableMeta & {
-  readonly [KUMIKO_NAME_SYMBOL]: string;
-  readonly [KUMIKO_COLUMNS_SYMBOL]: Record<string, ColumnHandle>;
-  readonly [field: string]: unknown;
-};
-
 function isNumericPgType(t: PgType): t is `numeric(${number},${number})` {
   return t.startsWith("numeric(");
 }
@@ -72,6 +60,8 @@ export function pgTypeToSqlType(pgType: PgType): string {
       return "boolean";
     case "integer":
       return "integer";
+    case "double precision":
+      return "double precision";
     case "bigint":
       return "bigint";
     case "serial":
@@ -234,6 +224,10 @@ export function integer(name: string): ColumnBuilder<number> {
   return buildColumn(name, "integer") as ColumnBuilder<number>;
 }
 
+export function doublePrecision(name: string): ColumnBuilder<number> {
+  return buildColumn(name, "double precision") as ColumnBuilder<number>;
+}
+
 export function serial(name: string): ColumnBuilder<number> {
   return buildColumn(name, "serial") as ColumnBuilder<number>;
 }

package/src/db/entity-field-encryption.ts

@@ -1,6 +1,13 @@
-import type { EntityDefinition } from "../engine/types";
-import type { EncryptionProvider } from "./encryption";
-import { createEncryptionProvider } from "./encryption";
+// Entity-field encryption (`encrypted: true` on text/longText fields),
+// backed by the same envelope cipher as encrypted config values: JSON
+// StoredEnvelope in the TEXT column, kekVersion per value, legacy
+// single-key ciphertexts (pre-envelope ENCRYPTION_KEY era) readable via
+// the cipher's legacy fallback until re-encrypted.
+
+import type { EntityDefinition, TenantId } from "../engine/types";
+import { createEnvMasterKeyProvider } from "../secrets/env-master-key-provider";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher";
+import type { KeyScope } from "../secrets/types";
 
 export function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string> {
   const names = new Set<string>();
@@ -12,70 +19,120 @@ export function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySe
   return names;
 }
 
-function encryptFieldValue(
+// BYOK hook: thread the row's tenant to the cipher when the row carries one
+// (system-scope rows may not).
+function scopeOf(row: Record<string, unknown>): KeyScope | undefined {
+  const tenantId = row["tenantId"];
+  return typeof tenantId === "string" ? { tenantId: tenantId as TenantId } : undefined; // @cast-boundary db-row
+}
+
+async function encryptFieldValue(
   fieldName: string,
   value: unknown,
-  encryption: EncryptionProvider,
-): string {
+  cipher: EnvelopeCipher,
+  scope: KeyScope | undefined,
+): Promise<string> {
   if (value === null || value === undefined) {
     throw new Error(`encrypted field "${fieldName}" cannot be null or undefined`);
   }
   if (typeof value !== "string") {
     throw new Error(`encrypted field "${fieldName}" must be a string, got ${typeof value}`);
   }
-  return encryption.encrypt(value);
+  return cipher.encrypt(value, scope);
 }
 
-export function encryptEntityFieldValues(
+export async function encryptEntityFieldValues(
   row: Record<string, unknown>,
   encryptedFields: ReadonlySet<string>,
-  encryption: EncryptionProvider,
+  cipher: EnvelopeCipher,
   opts?: { onlyKeys?: Iterable<string> },
-): Record<string, unknown> {
+): Promise<Record<string, unknown>> {
   if (encryptedFields.size === 0) return row;
   const only = opts?.onlyKeys ? new Set(opts.onlyKeys) : null;
   const out = { ...row };
+  const scope = scopeOf(row);
   for (const name of encryptedFields) {
     if (only && !only.has(name)) continue;
     if (!(name in out)) continue;
     const value = out[name];
     if (value === null || value === undefined) continue;
-    out[name] = encryptFieldValue(name, value, encryption);
+    out[name] = await encryptFieldValue(name, value, cipher, scope);
   }
   return out;
 }
 
-export function decryptEntityFieldValues(
+export async function decryptEntityFieldValues(
   row: Record<string, unknown>,
   encryptedFields: ReadonlySet<string>,
-  encryption: EncryptionProvider,
-): Record<string, unknown> {
+  cipher: EnvelopeCipher,
+): Promise<Record<string, unknown>> {
   if (encryptedFields.size === 0) return row;
   const out = { ...row };
+  const scope = scopeOf(row);
   for (const name of encryptedFields) {
     const value = out[name];
     if (value === null || value === undefined) continue;
     if (typeof value !== "string") continue;
-    out[name] = encryption.decrypt(value);
+    out[name] = await cipher.decrypt(value, scope);
   }
   return out;
 }
 
-let cachedProvider: EncryptionProvider | undefined;
+// Boot-injected app-wide cipher. run{Prod,Dev}App (and test setups that
+// exercise encrypted fields) call configureEntityFieldEncryption once with
+// the same cipher instance the config feature uses; executors resolve it
+// lazily so entities without encrypted fields never touch it.
+let injectedCipher: EnvelopeCipher | undefined;
 
-export function resolveEntityFieldEncryption(): EncryptionProvider {
-  if (cachedProvider) return cachedProvider;
-  const key = process.env["ENCRYPTION_KEY"];
-  if (!key) {
+export function configureEntityFieldEncryption(cipher: EnvelopeCipher | undefined): void {
+  injectedCipher = cipher;
+}
+
+export function resolveEntityFieldEncryption(): EnvelopeCipher {
+  if (!injectedCipher) {
     throw new Error(
-      "ENCRYPTION_KEY environment variable is required (encrypted entity fields in use)",
+      "entity-field encryption is not configured — encrypted entity fields need a master key " +
+        "(KUMIKO_SECRETS_MASTER_KEY_V<n>); run{Prod,Dev}App wire the cipher automatically, " +
+        "custom boots call configureEntityFieldEncryption(cipher).",
     );
   }
-  cachedProvider = createEncryptionProvider(key);
-  return cachedProvider;
+  return injectedCipher;
+}
+
+// Non-throwing probe for callers that degrade gracefully (DSGVO export
+// replaces encrypted fields with an explicit marker instead of failing
+// the whole export when no cipher is wired).
+export function configuredEntityFieldEncryption(): EnvelopeCipher | undefined {
+  return injectedCipher;
 }
 
 /** @internal test-only */
 export function resetEntityFieldEncryptionCacheForTests(): void {
-  cachedProvider = undefined;
+  injectedCipher = undefined;
+}
+
+// Boot-time availability probe for validateBoot: either a cipher was
+// injected, or the env keyring must be constructible — eager construction
+// surfaces missing AND malformed keys (wrong length, bad base64) at boot
+// instead of on the first encrypted read in prod. validateBoot runs before
+// configureEntityFieldEncryption, so the env probe is the common path.
+export function validateEntityFieldEncryptionAvailable(): void {
+  // skip: an injected cipher (test seam / custom KMS) satisfies availability
+  if (injectedCipher) return;
+  try {
+    createEnvMasterKeyProvider({
+      env: {
+        ...process.env,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION:
+          process.env["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
+      },
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `encrypted entity fields in use but no usable master key (${reason}) — set ` +
+        "KUMIKO_SECRETS_MASTER_KEY_V1 (32 bytes, base64) or inject a cipher via " +
+        "configureEntityFieldEncryption().",
+    );
+  }
 }

package/src/db/entity-table-meta-types.ts

@@ -0,0 +1,2 @@
+// Legacy path — re-exported for callers still importing this module directly.
+export type * from "@cosmicdrift/kumiko-types/entity-table-meta-types";

package/src/db/entity-table-meta.ts

@@ -18,81 +18,26 @@
 //      auf Sondercases beschränken (child-projection-tables ohne tenant,
 //      append-only-logs mit serial PK, aggregate-ID ohne DEFAULT, …).
 
+import { collectPiiSubjectFields } from "../crypto";
+import type { EntityDefinition, EntityIndexDef, FieldDefinition } from "../engine/types";
 import type {
-  EntityDefinition,
-  EntityIndexDef,
-  EntityRelations,
-  FieldDefinition,
-} from "../engine/types";
+  BuildEntityTableMetaOptions,
+  ColumnMeta,
+  EntityTableMeta,
+  IndexMeta,
+  UnmanagedTableInput,
+} from "./entity-table-meta-types";
 import { READ_MODEL_PREFIX, toSnakeCase, toTableName } from "./table-builder";
 
-// PG-Type-Repertoire das die Read-Model-Tabellen brauchen. Bewusst
-// schmal — keine Vendor-spezifischen Typen (TSVECTOR, HSTORE, etc.).
-// App-Author die solche braucht greift in der reviewten SQL-Migration
-// hand-edit ein, nicht im Generator.
-export type PgType =
-  | "uuid"
-  | "text"
-  | "boolean"
-  | "integer"
-  | "bigint"
-  | "serial"
-  | "bigserial"
-  | "jsonb"
-  | "timestamptz"
-  | "timestamptz(3)"
-  // Exact decimal — precision/scale are encoded in the type string so the
-  // DDL renderer and read-coercion need no side-channel metadata.
-  | `numeric(${number},${number})`;
-
-export type ColumnMeta = {
-  readonly name: string; // snake_case PG column name
-  readonly pgType: PgType;
-  readonly notNull: boolean;
-  // Raw SQL-default-expression (e.g. `now()`, `gen_random_uuid()`,
-  // `'[]'::jsonb`). undefined = no DEFAULT clause.
-  readonly defaultSql?: string;
-  readonly primaryKey?: boolean;
-  readonly identity?: boolean;
-  // bigint/bigserial only: JS round-trip mode. `number` = createBigIntField /
-  // drizzle mode:"number" (safe ≤2^53). `bigint` = money cents, raw unmanaged.
-  readonly bigintJsMode?: "number" | "bigint";
-};
-
-export type IndexMeta = {
-  readonly name: string;
-  readonly columns: readonly string[]; // snake_case PG column names
-  readonly unique?: boolean;
-  // Raw SQL-where-expression for partial indexes. Caller is responsible
-  // for safety — emitted verbatim.
-  readonly whereSql?: string;
-  // Set wenn die EntityDefinition ein partial-Index hat (def.where als
-  // drizzle SQL-AST), der vom Generator nicht zuverlässig renderbar ist.
-  // Renderer emittiert das Statement dann AUSKOMMENTIERT mit Warn-Hint —
-  // App-Author muss das WHERE manuell im generierten SQL hinzufügen.
-  readonly needsManualWhere?: boolean;
-};
-
-export type CompositePrimaryKeyMeta = {
-  readonly name: string;
-  readonly columns: readonly string[];
-};
-
-export type EntityTableMeta = {
-  readonly tableName: string;
-  readonly columns: readonly ColumnMeta[];
-  readonly indexes: readonly IndexMeta[];
-  // For tables with composite PK (no single id column, e.g. snapshots
-  // keyed by aggregate_id+version). When set, no column should have
-  // primaryKey:true; the constraint is emitted at table-level.
-  readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
-  // Source-hint für Diagnose/Tests — nicht funktional verwendet.
-  // "managed" = aus EntityDefinition (mit base-columns + audit-trail).
-  // "unmanaged" = via defineUnmanagedTable — kein Standard-Audit, App
-  // trägt Verantwortung. Migration-Generator + Tooling können den
-  // discriminator nutzen um Warnungen zu rendern ("X tables are unmanaged").
-  readonly source: "managed" | "unmanaged";
-};
+export type {
+  BuildEntityTableMetaOptions,
+  ColumnMeta,
+  CompositePrimaryKeyMeta,
+  EntityTableMeta,
+  IndexMeta,
+  PgType,
+  UnmanagedTableInput,
+} from "./entity-table-meta-types";
 
 // Standard base-columns für event-sourced Read-Model-Tabellen. Spiegelt
 // `buildBaseColumns()` aus table-builder.ts (drizzle-Variante).
@@ -153,7 +98,7 @@ function fieldToColumnMeta(
     case "text":
     case "longText": {
       const def = fieldDefaultLiteral(field);
-      return [
+      const cols: ColumnMeta[] = [
         {
           name: snake,
           pgType: "text",
@@ -161,6 +106,13 @@ function fieldToColumnMeta(
           ...(def !== undefined && { defaultSql: def }),
         },
       ];
+      // lookupable → HMAC-Blind-Index-Pendant. Nullable ist Pflicht:
+      // managedChangeRequiresRecreate würde eine NOT-NULL-Spalte ohne
+      // Default auf Bestandstabellen als DROP+Rebuild diffen.
+      if (field.type === "text" && field.lookupable === true) {
+        cols.push({ name: `${snake}_bidx`, pgType: "text", notNull: false });
+      }
+      return cols;
     }
     case "boolean": {
       const def = fieldDefaultLiteral(field);
@@ -192,7 +144,7 @@ function fieldToColumnMeta(
       return [
         {
           name: snake,
-          pgType: "integer",
+          pgType: field.integer === true ? "integer" : "double precision",
           notNull: field.required === true,
           ...(def !== undefined && { defaultSql: def }),
         },
@@ -280,11 +232,6 @@ export function resolveTableName(
   return `${featureName}_${baseName}`;
 }
 
-export type BuildEntityTableMetaOptions = {
-  readonly featureName?: string;
-  readonly relations?: EntityRelations;
-};
-
 export function buildEntityTableMeta(
   entityName: string,
   entity: EntityDefinition,
@@ -305,10 +252,17 @@ export function buildEntityTableMeta(
   for (const c of baseCols) colByName.set(c.name, c);
 
   const fieldNameToSnake = new Map<string, string>();
+  const bidxSnakeByFieldSnake = new Map<string, string>();
   for (const [name, field] of Object.entries(entity.fields)) {
     const fieldCols = fieldToColumnMeta(name, field, entity);
     for (const c of fieldCols) colByName.set(c.name, c);
-    if (fieldCols.length === 1 && fieldCols[0]) fieldNameToSnake.set(name, fieldCols[0].name);
+    // Multi-column fields map to their primary column when its name IS the
+    // field's snake (text+bidx, money+currency) — matches the toSnakeCase
+    // fallback below, so explicit indexes keep resolving.
+    const primary = fieldCols[0];
+    if (primary && primary.name === toSnakeCase(name)) fieldNameToSnake.set(name, primary.name);
+    const bidxCol = fieldCols.find((c) => c.name.endsWith("_bidx"));
+    if (primary && bidxCol) bidxSnakeByFieldSnake.set(primary.name, bidxCol.name);
   }
 
   // Preserve base-col order, then any new user-col-names in fields-order.
@@ -347,6 +301,12 @@ export function buildEntityTableMeta(
     indexes.push({ name: `${tableName}_${snake}_idx`, columns: [snake] });
   }
 
+  // lookupable-Felder: Index auf der bidx-Spalte — der OR-Rewrite der
+  // Query-Compiler trifft sie bei jedem Equality-Lookup.
+  for (const bidxSnake of bidxSnakeByFieldSnake.values()) {
+    indexes.push({ name: `${tableName}_${bidxSnake}_idx`, columns: [bidxSnake] });
+  }
+
   // Explizit deklarierte indexes (EntityIndexDef). `def.where` ist ein
   // SqlExpression (`sql\`…\`` aus @cosmicdrift/kumiko-framework/db) —
   // renderbar via `.text`. Unbekannte where-Shapes bleiben needsManualWhere.
@@ -364,13 +324,33 @@ export function buildEntityTableMeta(
       ...(whereSql !== undefined && { whereSql }),
       ...(def.where !== undefined && whereSql === undefined && { needsManualWhere: true }),
     });
+    // Unique-Index über lookupable-Spalten: partielles bidx-Pendant, damit
+    // Uniqueness auch für verschlüsselte Rows greift. Das Original bleibt
+    // für Klartext-Alt-Rows; partial (IS NOT NULL) weil bidx bei erased/
+    // key-losen Rows NULL ist.
+    if (def.unique === true && def.where === undefined) {
+      const bidxCols = cols.map((c) => bidxSnakeByFieldSnake.get(c) ?? c);
+      if (bidxCols.some((c, i) => c !== cols[i])) {
+        const notNullParts = bidxCols
+          .filter((c, i) => c !== cols[i])
+          .map((c) => `"${c}" IS NOT NULL`);
+        indexes.push({
+          name: `${indexName}_bidx`,
+          columns: bidxCols,
+          unique: true,
+          whereSql: notNullParts.join(" AND "),
+        });
+      }
+    }
   }
 
+  const piiSubjectFields = collectPiiSubjectFields(entity);
   return {
     tableName,
     columns,
     indexes,
-    source: "managed",
+    source: options?.source ?? "managed",
+    ...(piiSubjectFields.length > 0 && { piiSubjectFields }),
   };
 }
 
@@ -385,15 +365,8 @@ export function buildEntityTableMeta(
 // jede neue defineUnmanagedTable-Stelle prüfen.
 //
 // Heutige use-cases im framework:
-//   - `read_delivery_attempts` — id kommt aus dem Aggregate-Stream
-//   - `read_job_run_logs` — child-table, serial PK, kein tenant-scope
-export type UnmanagedTableInput = {
-  readonly tableName: string;
-  readonly columns: readonly ColumnMeta[];
-  readonly indexes?: readonly IndexMeta[];
-  readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
-};
-
+//   - `store_delivery_attempts` — id kommt aus dem Aggregate-Stream
+//   - `store_job_run_logs` — child-table, serial PK, kein tenant-scope
 function sqlExpressionText(where: unknown): string | undefined {
   if (
     typeof where === "object" &&