@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/db/__tests__/replay-migration-sql.test.ts

@@ -0,0 +1,384 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { EntityTableMeta } from "../entity-table-meta";
+import { snapshotFromMetas } from "../migrate-generator";
+import { diffReplayAgainstSnapshot, replayMigrationsDir } from "../replay-migration-sql";
+
+function tmpMigrationsDir(): string {
+  return mkdtempSync(join(tmpdir(), "replay-migration-sql-"));
+}
+
+function write(dir: string, filename: string, sql: string): void {
+  writeFileSync(join(dir, filename), sql);
+}
+
+function meta(tableName: string, columns: EntityTableMeta["columns"]): EntityTableMeta {
+  return { tableName, source: "managed", indexes: [], columns };
+}
+
+describe("replayMigrationsDir", () => {
+  test("reconstructs table+column shape from CREATE TABLE", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "read_accounts" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "tenant_id" uuid NOT NULL,
+  "stripe_customer_id" text
+);
+CREATE INDEX IF NOT EXISTS "read_accounts_tenant_id_idx" ON "read_accounts" ("tenant_id");`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...replayed.keys()]).toEqual(["read_accounts"]);
+      expect([...(replayed.get("read_accounts")?.columns ?? [])].sort()).toEqual([
+        "id",
+        "stripe_customer_id",
+        "tenant_id",
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("ADD COLUMN extends an already-created table across files", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      write(dir, "0002_add-col.sql", `ALTER TABLE "read_a" ADD COLUMN "title" text;`);
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  // Hand-edited migrations legitimately add "IF NOT EXISTS"/"IF EXISTS" to
+  // ADD/DROP COLUMN (the generator itself never emits it, but app authors
+  // are explicitly allowed to hand-edit before committing — see the header
+  // comment every generated migration carries).
+  test("ADD COLUMN IF NOT EXISTS (hand-edited) still extends the table", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      write(dir, "0002_add-col.sql", `ALTER TABLE "read_a" ADD COLUMN IF NOT EXISTS "title" text;`);
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  // Regression: publicstatus#0007_fix-secrets-table-columns adds three
+  // columns in ONE statement (comma-separated ADD COLUMN clauses) — the
+  // replay used to only pick up the first, reporting "metadata" and
+  // "last_rotated_at" as missing even though the migration creates them.
+  test("multiple ADD COLUMN clauses in a single ALTER TABLE statement all extend the table", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      write(
+        dir,
+        "0002_add-cols.sql",
+        `ALTER TABLE "read_a"
+  ADD COLUMN IF NOT EXISTS "envelope" jsonb NOT NULL,
+  ADD COLUMN IF NOT EXISTS "metadata" jsonb DEFAULT '{}'::jsonb NOT NULL,
+  ADD COLUMN IF NOT EXISTS "last_rotated_at" timestamp with time zone DEFAULT now() NOT NULL;`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])].sort()).toEqual([
+        "envelope",
+        "id",
+        "last_rotated_at",
+        "metadata",
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("mixed ADD + DROP COLUMN clauses in one statement apply in order", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY, "legacy" text);`,
+      );
+      write(
+        dir,
+        "0002_migrate-cols.sql",
+        `ALTER TABLE "read_a" DROP COLUMN IF EXISTS "legacy", ADD COLUMN IF NOT EXISTS "title" text;`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("DROP COLUMN IF EXISTS (hand-edited) still removes the column", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY, "title" text);`,
+      );
+      write(dir, "0002_drop-col.sql", `ALTER TABLE "read_a" DROP COLUMN IF EXISTS "title";`);
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])]).toEqual(["id"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  // The real migrate-runner never executes a DESTRUCTIVE marker (it's a
+  // commented-out suggestion an operator uncomments deliberately) — but the
+  // snapshot already reflects the post-drop state as the intended end state,
+  // so replay must count the marker as applied or "unexpected-table"/
+  // "unexpected columns" fires forever against a table the snapshot
+  // correctly omits.
+  // #1473/2: CREATE TABLE IF NOT EXISTS is a no-op in real Postgres when
+  // the table already exists — treating it as an overwrite here silently
+  // discards whatever an in-between ALTER TABLE added, exactly the
+  // copy-paste-migration class this replay exists to catch.
+  test("CREATE TABLE IF NOT EXISTS for an already-created table is a no-op, not an overwrite", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      write(dir, "0002_add-col.sql", `ALTER TABLE "read_a" ADD COLUMN "title" text;`);
+      // Accidental copy-paste of 0001 — same CREATE TABLE IF NOT EXISTS text.
+      write(
+        dir,
+        "0003_copy-paste.sql",
+        `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("commented-out destructive DROP TABLE is replayed as applied", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      write(
+        dir,
+        "0002_drop.sql",
+        `-- DESTRUCTIVE: DROP TABLE IF EXISTS "read_a";  -- uncomment + ensure backup`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...replayed.keys()]).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("commented-out destructive DROP COLUMN is replayed as applied", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY, "legacy" text);`,
+      );
+      write(
+        dir,
+        "0002_drop-col.sql",
+        `-- DESTRUCTIVE: ALTER TABLE "read_a" DROP COLUMN "legacy";  -- uncomment + ensure backup`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])]).toEqual(["id"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("diffReplayAgainstSnapshot", () => {
+  test("clean: replayed schema matches snapshot exactly", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY, "title" text);`,
+      );
+      const snapshot = snapshotFromMetas([
+        meta("read_a", [
+          { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+          { name: "title", pgType: "text", notNull: false },
+        ]),
+      ]);
+      const mismatches = diffReplayAgainstSnapshot(replayMigrationsDir(dir), snapshot);
+      expect(mismatches).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  // Reproduces the kumiko-studio 0016 incident: the snapshot correctly
+  // records store_api_tokens, but the migration file that's supposed to
+  // create it is an accidental copy of an earlier file (creates read_accounts
+  // again instead) — CI must fail loud instead of shipping a table that only
+  // ever exists on paper.
+  test("misgenerated migration: snapshot expects a table no file actually creates", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_account-entity.sql",
+        `CREATE TABLE IF NOT EXISTS "read_accounts" ("id" uuid PRIMARY KEY, "stripe_customer_id" text);`,
+      );
+      write(
+        dir,
+        "0002_add-personal-access-tokens.sql",
+        // bug: this should create store_api_tokens, but it's a copy of 0001
+        `CREATE TABLE IF NOT EXISTS "read_accounts" ("id" uuid PRIMARY KEY, "stripe_customer_id" text);`,
+      );
+      const snapshot = snapshotFromMetas([
+        meta("read_accounts", [
+          { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+          { name: "stripe_customer_id", pgType: "text", notNull: false },
+        ]),
+        meta("store_api_tokens", [
+          { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+          { name: "token_hash", pgType: "text", notNull: true },
+        ]),
+      ]);
+      const mismatches = diffReplayAgainstSnapshot(replayMigrationsDir(dir), snapshot);
+      expect(mismatches).toEqual([
+        {
+          tableName: "store_api_tokens",
+          kind: "missing-table",
+          detail: 'snapshot expects "store_api_tokens" but no migration file creates it',
+        },
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("column drift: migration creates a table with the wrong columns", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      const snapshot = snapshotFromMetas([
+        meta("read_a", [
+          { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+          { name: "title", pgType: "text", notNull: false },
+        ]),
+      ]);
+      const mismatches = diffReplayAgainstSnapshot(replayMigrationsDir(dir), snapshot);
+      expect(mismatches).toEqual([
+        { tableName: "read_a", kind: "column-drift", detail: "missing columns: title" },
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("kumiko-framework#1473: an unparsed ALTER TABLE RENAME statement fails loud instead of vanishing", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "widgets" ("id" uuid PRIMARY KEY);
+ALTER TABLE "widgets" RENAME TO "gadgets";`,
+      );
+      expect(() => replayMigrationsDir(dir)).toThrow(/unparsed table-DDL statement/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("kumiko-framework#1535: an unquoted CREATE TABLE identifier parses instead of failing loud", () => {
+    // Was "fails loud" pre-#1535 — but real committed migrations do this
+    // (publicstatus's 0014_marketing-waitlist.sql), and the old behavior
+    // turned an already-graceful missing-table report into a hard abort.
+    // Unquoted identifiers must parse like quoted ones.
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE widgets ("id" uuid PRIMARY KEY);`);
+      const replayed = replayMigrationsDir(dir);
+      expect([...replayed.keys()]).toEqual(["widgets"]);
+      expect([...(replayed.get("widgets")?.columns ?? [])]).toEqual(["id"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("schema-qualified CREATE TABLE (public.widgets) fails loud — IDENT rejects '.'", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", "CREATE TABLE public.widgets (id uuid PRIMARY KEY);\n");
+      expect(() => replayMigrationsDir(dir)).toThrow(/unparsed table-DDL statement/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("kumiko-framework#1535: a bare table-level PRIMARY KEY/UNIQUE clause isn't parsed as a column", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE widgets (id uuid, sku text, name text, UNIQUE (sku), PRIMARY KEY (id));`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("widgets")?.columns ?? [])].sort()).toEqual(["id", "name", "sku"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("kumiko-framework#1535: shape-neutral ALTER COLUMN/CONSTRAINT clauses don't fail loud", () => {
+    // Regression for the false-positive class: these are all real,
+    // committed, shape-neutral DDL shapes (kumiko-studio's
+    // 0002_file_refs_soft_delete.sql, publicstatus's
+    // 0020_add-monitor-checks.sql) that the #1535 fix must recognize
+    // instead of throwing "unparsed table-DDL statement".
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "widgets" ("id" uuid PRIMARY KEY, "title" text);
+ALTER TABLE "widgets" ALTER COLUMN "title" SET NOT NULL;
+ALTER TABLE "widgets" ALTER COLUMN "title" SET DEFAULT 'untitled';
+ALTER TABLE "widgets" ADD CONSTRAINT "widgets_title_check" CHECK (length("title") > 0);
+ALTER TABLE "widgets" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "widgets" OWNER TO app_user;`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("widgets")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("unexpected table: migrations create a table the snapshot doesn't know about", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "orphan" ("id" uuid PRIMARY KEY);`);
+      const mismatches = diffReplayAgainstSnapshot(replayMigrationsDir(dir), snapshotFromMetas([]));
+      expect(mismatches).toEqual([
+        {
+          tableName: "orphan",
+          kind: "unexpected-table",
+          detail: 'migrations create "orphan" but .snapshot.json has no entry for it',
+        },
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/db/__tests__/schema-inspection.test.ts

@@ -17,4 +17,11 @@ describe("schema-inspection — resolveUnsafeClient guard", () => {
   test("columnNamesOf throws the same named error", async () => {
     await expect(columnNamesOf(noUnsafe, "x")).rejects.toThrow(/resolveUnsafeClient: no `\.unsafe/);
   });
+
+  test("tableExists throws the same named error when .unsafe is a non-function value", async () => {
+    const notAFunction = { unsafe: "notafunction" } as unknown as DbConnection;
+    await expect(tableExists(notAFunction, "public.x")).rejects.toThrow(
+      /resolveUnsafeClient: no `\.unsafe/,
+    );
+  });
 });

package/src/db/__tests__/schema-migration.integration.test.ts

@@ -105,7 +105,7 @@ describe("schema migration workflows", () => {
     // Entity fields
     expect(columns.get("title")?.dataType).toBe("text");
     expect(columns.get("body")?.dataType).toBe("text");
-    expect(columns.get("view_count")?.dataType).toBe("integer");
+    expect(columns.get("view_count")?.dataType).toBe("double precision");
     expect(columns.get("published_at")?.dataType).toContain("timestamp");
     expect(columns.get("is_draft")?.dataType).toBe("boolean");
     expect(columns.get("is_draft")?.isNullable).toBe(false); // has default → NOT NULL

package/src/db/__tests__/table-builder-meta-lockstep.test.ts

@@ -109,3 +109,42 @@ describe("lock-step — softDelete + explizite Indexes", () => {
     expect((fromBuilder?.indexes ?? []).length).toBeGreaterThanOrEqual(3);
   });
 });
+
+// Dritte Probe: lookupable-Feld (#818) — bidx-Spalte, bidx-Index und das
+// partielle Unique-Pendant müssen auf beiden Pfaden identisch entstehen.
+const entityWithLookupable = createEntity({
+  table: "read_lockstep_probe_bidx",
+  fields: {
+    email: { type: "text", required: true, pii: true, lookupable: true },
+    tenantSlug: { type: "text", required: true },
+  },
+  indexes: [{ columns: ["tenantSlug", "email"], unique: true }],
+});
+
+describe("lock-step — lookupable / blind-index (#818)", () => {
+  const fromBuilder = asEntityTableMeta(
+    buildEntityTable("lockstepProbeBidx", entityWithLookupable),
+  );
+  const fromMeta = buildEntityTableMeta("lockstepProbeBidx", entityWithLookupable);
+
+  test("identical columns inkl. nullable bidx-Spalte", () => {
+    expect(byName<ColumnMeta>(fromBuilder?.columns ?? [])).toEqual(
+      byName<ColumnMeta>(fromMeta.columns),
+    );
+    const bidx = (fromMeta.columns ?? []).find((c) => c.name === "email_bidx");
+    expect(bidx).toEqual({ name: "email_bidx", pgType: "text", notNull: false });
+  });
+
+  test("identical indexes inkl. bidx-Index + partiellem Unique-Pendant", () => {
+    expect(byName<IndexMeta>(fromBuilder?.indexes ?? [])).toEqual(
+      byName<IndexMeta>(fromMeta.indexes),
+    );
+    const names = fromMeta.indexes.map((i) => i.name);
+    expect(names).toContain("read_lockstep_probe_bidx_email_bidx_idx");
+    const partial = fromMeta.indexes.find((i) => i.name.endsWith("_tenant_slug_email_unique_bidx"));
+    expect(partial).toBeDefined();
+    expect(partial?.unique).toBe(true);
+    expect(partial?.columns).toEqual(["tenant_slug", "email_bidx"]);
+    expect(partial?.whereSql).toBe('"email_bidx" IS NOT NULL');
+  });
+});

package/src/db/__tests__/tenant-db-where-merge.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine";
 import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import type { TableColumns } from "../dialect";
+import { buildEntityTableMeta } from "../entity-table-meta";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb } from "../tenant-db";
 
@@ -13,20 +16,25 @@ const entity = createEntity({
   table: "merge_items",
   fields: { name: createTextField({ required: true }) },
 });
-const table = buildEntityTable("mergeItem", entity);
+// Brand (#742) is compile-time-only; hold the handle at the unbranded TableColumns
+// view so the method-form scoping test still compiles (runtime shape is identical).
+const table: TableColumns = buildEntityTable("mergeItem", entity);
 
 const own = testTenantId(1);
 const foreign = testTenantId(2);
 
 type Captured = { sql: string; values: readonly unknown[] };
 
-function recordingDb(captured: Captured[]) {
+function recordingDb(captured: Captured[]): DbRunner {
   return {
     unsafe: async (sql: string, values: readonly unknown[]) => {
       captured.push({ sql, values });
       return [] as unknown[];
     },
-  };
+    begin: async () => {
+      throw new Error("begin not used in these tests");
+    },
+  } as DbRunner;
 }
 
 describe("tenant-db WHERE merge — caller cannot override tenant scope", () => {
@@ -113,3 +121,41 @@ describe("tenant-db WHERE merge — narrowing within the enforced scope", () =>
     expect(captured[0]?.values).not.toContain(foreign);
   });
 });
+
+// Root-cause regression for the cross-tenant leak fixed in hasTenantColumn:
+// unmanaged direct-write stores (buildEntityTableMeta, e.g. userSessionTable,
+// apiTokenTable) store tenantId as a snake_case column-meta entry, not a
+// direct `table.tenantId` property — a naive property check silently treated
+// them as tenant-less and skipped the WHERE-scope entirely.
+describe("tenant-db WHERE merge — unmanaged EntityTableMeta tables (buildEntityTableMeta)", () => {
+  const unmanagedEntity = createEntity({
+    table: "merge_meta_items",
+    fields: { tenantId: createTextField({ required: true }), name: createTextField() },
+  });
+  const unmanagedTable = buildEntityTableMeta("merge-meta-item", unmanagedEntity);
+
+  test("selectMany still applies the tenant scope (pre-fix: no WHERE at all)", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    // selectMany's Table param types the branded-EntityTable shape only;
+    // EntityTableMeta reads work identically at runtime (both normalize via
+    // asEntityTableMeta) — same unbranded-view cast as `table` above.
+    await tdb.selectMany(unmanagedTable as unknown as TableColumns, { name: "needle" });
+
+    expect(captured[0]?.sql).toMatch(/tenant_id" IN /i);
+    expect(captured[0]?.values).toContain(own);
+    expect(captured[0]?.values).not.toContain(foreign);
+  });
+
+  test("updateMany still forces own tenantId (pre-fix: no scope on writes either)", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.updateMany(unmanagedTable, { name: "x" }, { tenantId: foreign });
+
+    const update = captured.find((c) => /UPDATE/i.test(c.sql));
+    expect(update?.values).toContain(own);
+    expect(update?.values).not.toContain(foreign);
+  });
+});

package/src/db/__tests__/tenant-db.integration.test.ts

@@ -10,7 +10,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "../../stack";
-import { table as pgTable, serial, text, timestamp } from "../dialect";
+import { table as pgTable, serial, type TableColumns, text, timestamp } from "../dialect";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb } from "../tenant-db";
 
@@ -26,7 +26,11 @@ const entity = createEntity({
   softDelete: true,
 });
 
-const table = buildEntityTable("tenantDbItem", entity);
+// The ES-write brand (#742) is a compile-time phantom — no runtime property. This
+// suite exercises TenantDb method-form scoping on a real entity table, so the handle
+// is held at the unbranded TableColumns view: identical runtime shape, and both reads
+// and method-form writes accept it (a branded EntityTable is now rejected).
+const table: TableColumns = buildEntityTable("tenantDbItem", entity);
 
 // --- System table (no tenantId — like job_runs) ---
 

package/src/db/api.ts

@@ -15,7 +15,7 @@ export type DbConnectionOptions = {
 
 // Connection-Handle: db für Queries, client für Legacy-Zugriff (LISTEN/NOTIFY-Peer
 // bei Bun.SQL), close für Pool-Shutdown.
-export type DbConnection = {
+export type DbPoolHandle = {
   /** Provider Connection — Calls gehen über asRawClient() oder direkt. */
   // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection — postgres-js | Bun.SQL
   readonly db: any;
@@ -34,7 +34,7 @@ let _provider: undefined | (() => Promise<typeof import("./postgres-provider")>)
 export async function createConnection(
   url: string,
   options: DbConnectionOptions = {},
-): Promise<DbConnection> {
+): Promise<DbPoolHandle> {
   const p = process.env["DB_PROVIDER"];
   if (p === "bun" || p === "bun-sql") {
     const { createBunConnection } = await import("./bun-provider");

package/src/db/apply-entity-event.ts

@@ -1,22 +1,18 @@
 // applyEntityEvent — die EINZIGE Schreib-Logik für r.entity-Tabellen aus
 // Stored-Events. Beide Aufrufer benutzen sie:
 //
-//   - createEventStoreExecutor (live, im Write-TX) — übergibt ein
-//     "live event" mit unstripped flatData/flatChanges als payload damit
-//     sensitive Felder in der Read-Tabelle landen, das Event-Log selbst
-//     bleibt aber stripped (siehe append-Site im Executor).
+//   - createEventStoreExecutor (live, im Write-TX) — übergibt das gerade
+//     appendete StoredEvent direkt; sensitive Felder liegen als Tabellen-
+//     Ciphertext im Payload (boot-validiert pii/encrypted, #967).
 //   - rebuildProjection via ImplicitProjection (replay, im Rebuild-TX) —
-//     übergibt das StoredEvent direkt; payload ist dort ohne sensitive,
-//     was bei Rebuild akzeptiert wird (sensitive-Drift durch GDPR-Strip
-//     ist als load-bearing Backlog-Item gepinnt — siehe
-//     docs/plans/architecture/migrations.md Sektion "Backlog (Welle 3+)"
-//     → "Sensitive-Field-Persistenz im Rebuild" für Optionen a/b/c).
+//     übergibt dasselbe StoredEvent; apply kopiert Ciphertext byte-gleich
+//     zurück, bidx wird unten neu berechnet.
 //
-// Live==Rebuild-Equivalence ist damit by-construction für alle Felder
-// die NICHT als sensitive markiert sind — eine geänderte Schreib-Logik
-// muss nur an EINER Stelle gepflegt werden, kein Sync-Contract mehr.
-// Der load-bearing Test bleibt für non-sensitive-Drift in
-// db/__tests__/implicit-projection-equivalence.integration.ts.
+// Live==Rebuild-Equivalence ist damit by-construction für ALLE Felder —
+// eine geänderte Schreib-Logik muss nur an EINER Stelle gepflegt werden,
+// kein Sync-Contract mehr. Einzige legitime Divergenz: Crypto-Shredding
+// (DEK erased → Wert unlesbar, bidx NULL). Load-bearing Test:
+// db/__tests__/implicit-projection-equivalence.integration.test.ts.
 //
 // Tenant-Isolation: applyEntityEvent erwartet einen rohen DbRunner (TX
 // oder pool), KEINEN TenantDb-Wrapper. Schutz kommt aus zwei Quellen:
@@ -49,6 +45,7 @@
 //   - "skipped" → Event ist kein Auto-Verb (Domain-Event auf demselben
 //     Aggregate). Caller no-op.
 
+import { collectLookupableFields, computeBlindIndexValues } from "../crypto/blind-index";
 import { deleteMany, insertOne, updateMany } from "../db/query";
 import type { EntityDefinition } from "../engine/types";
 import { InternalError } from "../errors";
@@ -116,6 +113,11 @@ export async function applyEntityEvent(
       }
       const row = await insertOne<DbRow>(tx, table, {
         ...event.payload,
+        // Blind-Index-Spalten aus dem Payload-Wert (ciphertext → decrypt →
+        // HMAC, plaintext → HMAC, erased → NULL). Hier statt im Executor,
+        // damit Live-Write und Rebuild denselben Wert produzieren und der
+        // deterministische HMAC nie im Event-Log landet.
+        ...(await computeBlindIndexValues(event.payload, collectLookupableFields(entity))),
         tenantId,
         id: event.aggregateId,
         version: event.version,
@@ -142,6 +144,8 @@ export async function applyEntityEvent(
         table,
         {
           ...changes,
+          // bidx nur für die geänderten lookupable-Felder (siehe created).
+          ...(await computeBlindIndexValues(changes, collectLookupableFields(entity))),
           version: event.version,
           modifiedAt: event.createdAt,
           modifiedById: event.createdBy,