@cosmicdrift/kumiko-framework 0.157.2 → 0.159.1

package/src/db/__tests__/event-store-executor-write-verbs.integration.test.ts

@@ -0,0 +1,305 @@
+// The five write-verbs (create/update/delete/forget/restore) have several
+// error paths the existing suites (event-store-executor.integration.test.ts,
+// unique-violation-mapping.integration.test.ts) don't touch: entity- and
+// field-level ownership denials, explicit version conflicts, the forget()
+// verb entirely, and restore()'s two precondition failures.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "../../db/query";
+import { createEntity, createTextField } from "../../engine";
+import { from } from "../../engine/ownership";
+import { createEventsTable } from "../../event-store";
+import { createTestDb, type TestDb, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+let testDb: TestDb;
+let tdb: TenantDb;
+const admin = TestUsers.admin;
+const nonAdmin = TestUsers.user;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEventsTable(testDb.db);
+  tdb = createTenantDb(testDb.db, admin.tenantId);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+// =============================================================================
+// entity-level ownership_denied — create/update/delete/forget/restore
+// =============================================================================
+
+const restrictedEntity = createEntity({
+  table: "read_es_write_restricted",
+  fields: {
+    email: createTextField({ required: true }),
+  },
+  softDelete: true,
+  access: { write: { Admin: "all" } },
+});
+const restrictedTable = buildEntityTable("esWriteRestricted", restrictedEntity);
+
+describe("event-store-executor write-verbs — entity-level ownership_denied", () => {
+  const crud = createEventStoreExecutor(restrictedTable, restrictedEntity, {
+    entityName: "esWriteRestricted",
+  });
+
+  beforeAll(async () => {
+    await unsafeCreateEntityTableFor(restrictedEntity, "esWriteRestricted");
+  });
+
+  beforeEach(async () => {
+    await asRawClient(testDb.db).unsafe(
+      `TRUNCATE kumiko_events, read_es_write_restricted RESTART IDENTITY CASCADE`,
+    );
+  });
+
+  test("create: role without a write-rule → ownership_denied", async () => {
+    const result = await crud.create({ email: "denied@test.de" }, nonAdmin, tdb);
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect((result.error.details as { reason?: string }).reason).toBe("ownership_denied");
+  });
+
+  test("update: role without a write-rule → ownership_denied", async () => {
+    const created = await crud.create({ email: "owner@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.update(
+      { id: created.data.id, version: 1, changes: { email: "changed@test.de" } },
+      nonAdmin,
+      tdb,
+    );
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect((result.error.details as { reason?: string }).reason).toBe("ownership_denied");
+  });
+
+  test("delete: role without a write-rule → ownership_denied", async () => {
+    const created = await crud.create({ email: "todelete@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.delete({ id: created.data.id }, nonAdmin, tdb);
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect((result.error.details as { reason?: string }).reason).toBe("ownership_denied");
+  });
+
+  test("forget: role without a write-rule → ownership_denied", async () => {
+    const created = await crud.create({ email: "toforget@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.forget({ id: created.data.id }, nonAdmin, tdb);
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect((result.error.details as { reason?: string }).reason).toBe("ownership_denied");
+  });
+
+  test("forget: happy path hard-deletes the row and appends a forgotten event", async () => {
+    const created = await crud.create({ email: "gone@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.forget({ id: created.data.id }, admin, tdb);
+    expect(result.isSuccess).toBe(true);
+
+    const rows = (await asRawClient(testDb.db).unsafe(
+      `SELECT id FROM read_es_write_restricted WHERE email = 'gone@test.de'`,
+    )) as unknown[];
+    expect(rows).toHaveLength(0);
+
+    const events = (await asRawClient(testDb.db).unsafe(
+      `SELECT type FROM kumiko_events WHERE type = 'esWriteRestricted.forgotten'`,
+    )) as unknown[];
+    expect(events).toHaveLength(1);
+  });
+
+  test("restore: role without a write-rule → ownership_denied", async () => {
+    const created = await crud.create({ email: "torestore@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+    await crud.delete({ id: created.data.id }, admin, tdb);
+
+    const result = await crud.restore({ id: created.data.id }, nonAdmin, tdb);
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect((result.error.details as { reason?: string }).reason).toBe("ownership_denied");
+  });
+
+  test("restore: not yet deleted row → not_deleted", async () => {
+    const created = await crud.create({ email: "notdeleted@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.restore({ id: created.data.id }, admin, tdb);
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect((result.error.details as { reason?: string }).reason).toBe("not_deleted");
+  });
+});
+
+// =============================================================================
+// restore() on a non-soft-delete entity → soft_delete_not_enabled
+// =============================================================================
+
+const hardDeleteEntity = createEntity({
+  table: "read_es_write_hard",
+  fields: {
+    email: createTextField({ required: true }),
+  },
+});
+const hardDeleteTable = buildEntityTable("esWriteHard", hardDeleteEntity);
+
+describe("event-store-executor write-verbs — restore without softDelete", () => {
+  const crud = createEventStoreExecutor(hardDeleteTable, hardDeleteEntity, {
+    entityName: "esWriteHard",
+  });
+
+  beforeAll(async () => {
+    await unsafeCreateEntityTableFor(hardDeleteEntity, "esWriteHard");
+  });
+
+  beforeEach(async () => {
+    await asRawClient(testDb.db).unsafe(
+      `TRUNCATE kumiko_events, read_es_write_hard RESTART IDENTITY CASCADE`,
+    );
+  });
+
+  test("restore on an entity without softDelete → soft_delete_not_enabled", async () => {
+    const created = await crud.create({ email: "hard@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.restore({ id: created.data.id }, admin, tdb);
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect((result.error.details as { reason?: string }).reason).toBe("soft_delete_not_enabled");
+  });
+});
+
+// =============================================================================
+// field-level ownership_denied — checkWriteFieldOwnership via a row-scoped rule
+// =============================================================================
+
+const ownedFieldEntity = createEntity({
+  table: "read_es_write_owned_field",
+  fields: {
+    authorId: createTextField({ required: true }),
+    note: createTextField({
+      access: { write: { Admin: "all", User: from("user:id", "authorId") } },
+    }),
+  },
+});
+const ownedFieldTable = buildEntityTable("esWriteOwnedField", ownedFieldEntity);
+
+describe("event-store-executor write-verbs — field-level ownership_denied", () => {
+  const crud = createEventStoreExecutor(ownedFieldTable, ownedFieldEntity, {
+    entityName: "esWriteOwnedField",
+  });
+
+  beforeAll(async () => {
+    await unsafeCreateEntityTableFor(ownedFieldEntity, "esWriteOwnedField");
+  });
+
+  beforeEach(async () => {
+    await asRawClient(testDb.db).unsafe(
+      `TRUNCATE kumiko_events, read_es_write_owned_field RESTART IDENTITY CASCADE`,
+    );
+  });
+
+  test("create: writing `note` while authorId names someone else → ownership_denied (field scope)", async () => {
+    const result = await crud.create(
+      { authorId: TestUsers.driver.id, note: "not mine" },
+      nonAdmin,
+      tdb,
+    );
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    const details = result.error.details as { reason?: string; scope?: string; field?: string };
+    expect(details.reason).toBe("ownership_denied");
+    expect(details.scope).toBe("field");
+    expect(details.field).toBe("note");
+  });
+
+  test("create: writing `note` as the named author succeeds", async () => {
+    const result = await crud.create({ authorId: nonAdmin.id, note: "mine" }, nonAdmin, tdb);
+    expect(result.isSuccess).toBe(true);
+  });
+
+  test("update: changing `note` on someone else's row → ownership_denied (field scope)", async () => {
+    const created = await crud.create(
+      { authorId: TestUsers.driver.id, note: "original" },
+      admin,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.update(
+      { id: created.data.id, version: 1, changes: { note: "hijacked" } },
+      nonAdmin,
+      tdb,
+    );
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect((result.error.details as { reason?: string }).reason).toBe("ownership_denied");
+  });
+});
+
+// =============================================================================
+// version_conflict — explicit-id create collision, missing version on update
+// =============================================================================
+
+const versionEntity = createEntity({
+  table: "read_es_write_version",
+  fields: {
+    email: createTextField({ required: true }),
+  },
+});
+const versionTable = buildEntityTable("esWriteVersion", versionEntity);
+
+describe("event-store-executor write-verbs — version_conflict edge cases", () => {
+  const crud = createEventStoreExecutor(versionTable, versionEntity, {
+    entityName: "esWriteVersion",
+  });
+
+  beforeAll(async () => {
+    await unsafeCreateEntityTableFor(versionEntity, "esWriteVersion");
+  });
+
+  beforeEach(async () => {
+    await asRawClient(testDb.db).unsafe(
+      `TRUNCATE kumiko_events, read_es_write_version RESTART IDENTITY CASCADE`,
+    );
+  });
+
+  test("create with an explicit id that already has a stream → version_conflict", async () => {
+    const first = await crud.create({ email: "first@test.de" }, admin, tdb);
+    if (!first.isSuccess) throw new Error("setup failed");
+
+    const collision = await crud.create({ id: first.data.id, email: "second@test.de" }, admin, tdb);
+    expect(collision.isSuccess).toBe(false);
+    if (collision.isSuccess) return;
+    expect(collision.error.code).toBe("version_conflict");
+  });
+
+  test("update without a version field (and no skipOptimisticLock) → version_conflict", async () => {
+    const created = await crud.create({ email: "noversion@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.update(
+      { id: created.data.id, changes: { email: "changed@test.de" } },
+      admin,
+      tdb,
+    );
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect(result.error.code).toBe("version_conflict");
+  });
+});
+
+async function unsafeCreateEntityTableFor(
+  entity: Parameters<typeof buildEntityTable>[1],
+  name: string,
+): Promise<void> {
+  await unsafeCreateEntityTable(testDb.db, entity, name);
+}

package/src/db/__tests__/event-store-executor.integration.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { InMemoryKmsAdapter, PII_ERASED_SENTINEL } from "../../crypto";
+import { InMemoryKmsAdapter, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL } from "../../crypto";
 import { asRawClient } from "../../db/query";
 import { createBooleanField, createEntity, createTextField } from "../../engine";
 import { append, createEventsTable, loadEventsAfterVersion } from "../../event-store";
@@ -726,13 +726,13 @@ describe("event-store-executor — pii subject encryption", () => {
     const rawRows = (await asRawClient(testDb.db).unsafe(
       `SELECT email, plain FROM read_es_exec_pii LIMIT 1`,
     )) as Array<{ email: string; plain: string }>;
-    expect(rawRows[0]!.email).toStartWith(`kumiko-pii:v1:user:${result.data.id}:`);
+    expect(rawRows[0]!.email).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${result.data.id}:`);
     expect(rawRows[0]!.plain).toBe("visible");
 
     const events = (await asRawClient(testDb.db).unsafe(
       `SELECT payload FROM kumiko_events WHERE type = 'esExecPii.created' LIMIT 1`,
     )) as Array<{ payload: { email?: string } }>;
-    expect(events[0]?.payload.email).toStartWith("kumiko-pii:v1:");
+    expect(events[0]?.payload.email).toStartWith(PII_CIPHERTEXT_PREFIX);
 
     const detail = await crud.detail({ id: result.data.id }, adminUser, tdb);
     expect(detail?.["email"]).toBe("pii@test.de");
@@ -759,7 +759,7 @@ describe("event-store-executor — pii subject encryption", () => {
     const rawRows = (await asRawClient(testDb.db).unsafe(
       `SELECT note FROM read_es_exec_pii LIMIT 1`,
     )) as Array<{ note: string }>;
-    expect(rawRows[0]!.note).toStartWith(`kumiko-pii:v1:user:${TestUsers.admin.id}:`);
+    expect(rawRows[0]!.note).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${TestUsers.admin.id}:`);
   });
 
   test("eraseKey: detail renders the sentinel, stored events stay byte-identical", async () => {
@@ -805,7 +805,7 @@ describe("event-store-executor — pii subject encryption", () => {
     const rawRows = (await asRawClient(testDb.db).unsafe(
       `SELECT email FROM read_es_exec_pii LIMIT 1`,
     )) as Array<{ email: string }>;
-    expect(rawRows[0]!.email).toStartWith("kumiko-pii:v1:");
+    expect(rawRows[0]!.email).toStartWith(PII_CIPHERTEXT_PREFIX);
     expect(rawRows[0]!.email).not.toContain("rebuild@test.de");
 
     const detail = await crud.detail({ id: created.data.id }, adminUser, tdb);

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

@@ -31,7 +31,9 @@ export async function nullBlindIndexesForSubject(
   features: ReadonlyMap<string, FeatureDefinition>,
   subjectKey: string,
 ): Promise<void> {
-  const likePattern = `kumiko-pii:v1:${escapeLikePattern(subjectKey)}:%`;
+  // "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);

package/src/db/connection.ts

@@ -1,20 +1,12 @@
 // 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>;
+export * from "@cosmicdrift/kumiko-types/db-connection";
+export { createConnection, type DbConnectionOptions } 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/encryption.ts

@@ -12,9 +12,8 @@ export type EncryptionProvider = {
 /**
  * @deprecated Legacy single-key format: base64(iv+tag+ct) with NO key id —
  * a key change makes existing ciphertexts permanently undecryptable. Use
- * `createEnvelopeCipher` (@cosmicdrift/kumiko-framework/secrets) for new code; this
- * provider remains only as the decrypt-fallback for pre-envelope values
- * (EnvelopeCipherOptions.legacy) until a re-encrypt job migrated them.
+ * `createEnvelopeCipher` (@cosmicdrift/kumiko-framework/secrets) for new code;
+ * this provider has no consumers left in the framework.
  */
 export function createEncryptionProvider(key: string): EncryptionProvider {
   // Key must be 32 bytes for AES-256

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

@@ -0,0 +1,92 @@
+// Plain-data types for EntityTableMeta — split from the runtime
+// (buildEntityTableMeta, resolveTableName, defineUnmanagedTable) in
+// entity-table-meta.ts. Prep step for the types-only package extraction
+// (#1283) — this file must have ONLY `import type`, no value imports
+// (crypto/DB deps).
+
+import type { EntityRelations } from "../engine/types";
+
+// PG type repertoire the read-model tables need. Deliberately narrow — no
+// vendor-specific types (TSVECTOR, HSTORE, etc.). An app-author who needs
+// those reaches into the reviewed SQL migration by hand, not the generator.
+export type PgType =
+  | "uuid"
+  | "text"
+  | "boolean"
+  | "integer"
+  | "double precision"
+  | "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 when the EntityDefinition has a partial index (def.where as a
+  // drizzle SQL AST) the generator can't reliably render. The renderer
+  // emits the statement COMMENTED OUT with a warning hint — the app-author
+  // has to add the WHERE manually in the generated SQL.
+  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 for diagnostics/tests — not used functionally.
+  // "managed" = from EntityDefinition (with base-columns + audit trail).
+  // "unmanaged" = via defineUnmanagedTable — no standard audit, the app
+  // carries the responsibility. Migration-generator + tooling can use the
+  // discriminator to render warnings ("X tables are unmanaged").
+  readonly source: "managed" | "unmanaged";
+  // PII-subject-annotated field names (pii/userOwned/tenantOwned). Set by
+  // buildEntityTableMeta so the registry can reject r.storeTable stores
+  // whose direct writes would skip the executor's encryption (#820).
+  readonly piiSubjectFields?: readonly string[];
+};
+
+export type BuildEntityTableMetaOptions = {
+  readonly featureName?: string;
+  readonly relations?: EntityRelations;
+  readonly source?: "managed" | "unmanaged";
+};
+
+export type UnmanagedTableInput = {
+  readonly tableName: string;
+  readonly columns: readonly ColumnMeta[];
+  readonly indexes?: readonly IndexMeta[];
+  readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
+};

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

@@ -19,86 +19,25 @@
 //      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"
-  | "double precision"
-  | "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";
-  // PII-Subject-annotated field names (pii/userOwned/tenantOwned). Set by
-  // buildEntityTableMeta so the registry can reject r.storeTable stores
-  // whose direct writes would skip the executor's encryption (#820).
-  readonly piiSubjectFields?: readonly string[];
-};
+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).
@@ -293,12 +232,6 @@ export function resolveTableName(
   return `${featureName}_${baseName}`;
 }
 
-export type BuildEntityTableMetaOptions = {
-  readonly featureName?: string;
-  readonly relations?: EntityRelations;
-  readonly source?: "managed" | "unmanaged";
-};
-
 export function buildEntityTableMeta(
   entityName: string,
   entity: EntityDefinition,
@@ -434,13 +367,6 @@ export function buildEntityTableMeta(
 // Heutige use-cases im framework:
 //   - `store_delivery_attempts` — id kommt aus dem Aggregate-Stream
 //   - `store_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;
-};
-
 function sqlExpressionText(where: unknown): string | undefined {
   if (
     typeof where === "object" &&

package/src/db/queries/backfill-pii.ts

@@ -236,6 +236,7 @@ export async function backfillEventPiiEncryption(
           subject,
           value,
           kmsCtx,
+          field,
         );
         return "encrypted";
       } catch (e) {