@cosmicdrift/kumiko-framework 0.14.0 → 0.16.0

package/src/es-ops/__tests__/{context.integration.ts → context.integration.test.ts}

@@ -10,25 +10,27 @@
 // Feature in den Tests zu schwer wäre — wir testen nur den Read-Helper-
 // Layer, nicht die volle Event-Store-Pipeline.
 
+import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { sql } from "drizzle-orm";
-import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
-import { createTestDb, type TestDb } from "../../stack";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient, selectMany } from "../../db/query";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { createSeedMigrationContext } from "../context";
 import { createEsOperationsTable, esOperationsTable } from "../operations-schema";
 import { runPendingSeedMigrations } from "../runner";
 
-let testDb: TestDb;
+let testDb: BunTestDb;
 
 beforeAll(async () => {
+  await ensureTemporalPolyfill();
   testDb = await createTestDb();
   await createEsOperationsTable(testDb.db);
 
   // Minimal-Schema-Stubs für die 3 Read-Tabellen die context.ts liest.
   // Spalten matchen production (siehe Sysadmin-Stream-Tenant-Bug Memory).
-  await testDb.db.execute(sql`
+  await asRawClient(testDb.db).unsafe(`
     CREATE TABLE IF NOT EXISTS read_users (
       id          uuid PRIMARY KEY,
       email       text NOT NULL,
@@ -54,7 +56,7 @@ afterAll(async () => {
 });
 
 beforeEach(async () => {
-  await testDb.db.execute(sql`
+  await asRawClient(testDb.db).unsafe(`
     TRUNCATE kumiko_es_operations, kumiko_events, read_users, read_tenant_memberships, read_tenants
     RESTART IDENTITY CASCADE
   `);
@@ -70,26 +72,32 @@ async function insertMembershipWithEvent(args: {
   readonly streamTenantId: string;
   readonly roles: string;
 }): Promise<void> {
-  await testDb.db.execute(sql`
+  await asRawClient(testDb.db).unsafe(
+    `
     INSERT INTO read_tenant_memberships (id, user_id, tenant_id, roles)
-    VALUES (${args.id}::uuid, ${args.userId}, ${args.payloadTenantId}::uuid, ${args.roles})
-  `);
-  await testDb.db.execute(sql`
+    VALUES ($1::uuid, $2, $3::uuid, $4)
+  `,
+    [args.id, args.userId, args.payloadTenantId, args.roles],
+  );
+  await asRawClient(testDb.db).unsafe(
+    `
     INSERT INTO kumiko_events
       (aggregate_id, aggregate_type, tenant_id, version, type, payload, metadata, created_by)
     VALUES
-      (${args.id}::uuid, 'tenant-membership', ${args.streamTenantId}::uuid, 1,
+      ($1::uuid, 'tenant-membership', $2::uuid, 1,
        'tenant-membership.created', '{}'::jsonb, '{"userId":"system"}'::jsonb, 'system')
-  `);
+  `,
+    [args.id, args.streamTenantId],
+  );
 }
 
 function makeMockDispatcher() {
   return {
-    write: vi.fn(async () => ({ isSuccess: true as const, data: {} })),
-    query: vi.fn(),
-    command: vi.fn(),
-    batch: vi.fn(),
-    resolveAuthClaims: vi.fn(),
+    write: mock(async () => ({ isSuccess: true as const, data: {} })),
+    query: mock(),
+    command: mock(),
+    batch: mock(),
+    resolveAuthClaims: mock(),
   };
 }
 
@@ -105,10 +113,13 @@ describe("SeedMigrationContext.findUserByEmail (integration)", () => {
   test("liest existing user-row korrekt + maps tenant_id → tenantId", async () => {
     const userId = "01900000-0000-7000-8000-000000000001";
     const tenantId = "00000000-0000-4000-8000-000000000099";
-    await testDb.db.execute(sql`
+    await asRawClient(testDb.db).unsafe(
+      `
       INSERT INTO read_users (id, email, tenant_id)
-      VALUES (${userId}::uuid, 'admin@example.com', ${tenantId}::uuid)
-    `);
+      VALUES ($1::uuid, 'admin@example.com', $2::uuid)
+    `,
+      [userId, tenantId],
+    );
 
     const ctx = createSeedMigrationContext({
       dispatcher: makeMockDispatcher() as never,
@@ -231,11 +242,14 @@ describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
     // statt einer mit fehlendem stream-tenant zu arbeiten und schwer
     // diagnostizierbare version_conflict-Errors zu produzieren.
     const userId = "01900000-0000-7000-8000-000000000003";
-    await testDb.db.execute(sql`
+    await asRawClient(testDb.db).unsafe(
+      `
       INSERT INTO read_tenant_memberships (id, user_id, tenant_id, roles) VALUES
-        ('00000000-0000-4000-8000-0000000000d1'::uuid, ${userId},
+        ('00000000-0000-4000-8000-0000000000d1'::uuid, $1,
          '00000000-0000-4000-8000-000000000005'::uuid, '["Admin"]')
-    `);
+    `,
+      [userId],
+    );
     const ctx = createSeedMigrationContext({
       dispatcher: makeMockDispatcher() as never,
       dbRunner: testDb.db,
@@ -247,7 +261,7 @@ describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
 
 describe("SeedMigrationContext.findTenants (integration)", () => {
   test("returnt alle Tenants sortiert nach inserted_at", async () => {
-    await testDb.db.execute(sql`
+    await asRawClient(testDb.db).unsafe(`
       INSERT INTO read_tenants (id, name, tenant_key, inserted_at) VALUES
         ('00000000-0000-4000-8000-000000000002'::uuid, 'Beta',  'beta',  '2026-01-02'),
         ('00000000-0000-4000-8000-000000000001'::uuid, 'Alpha', 'alpha', '2026-01-01')
@@ -296,7 +310,7 @@ describe("runPendingSeedMigrations: skippable + env-flag (integration)", () => {
 
       // Kritisch: KEIN Marker — beim nächsten Boot ohne env-flag würde
       // der Seed dann tatsächlich laufen.
-      const markers = await testDb.db.select().from(esOperationsTable);
+      const markers = await selectMany(testDb.db, esOperationsTable);
       expect(markers).toHaveLength(0);
     } finally {
       delete process.env[envKey];
@@ -329,7 +343,7 @@ describe("runPendingSeedMigrations: skippable + env-flag (integration)", () => {
       expect(r.appliedIds).toEqual(["2026-05-20-skippable-but-no-flag"]);
       expect(r.skippedIds).toEqual([]);
 
-      const markers = await testDb.db.select().from(esOperationsTable);
+      const markers = await selectMany(testDb.db, esOperationsTable);
       expect(markers).toHaveLength(1);
     } finally {
       rmSync(dir, { recursive: true, force: true });
@@ -341,7 +355,7 @@ describe("runPendingSeedMigrations: skippable + env-flag (integration)", () => {
 
 describe("SeedMigrationContext.db (escape-hatch, integration)", () => {
   test("ctx.db kann für eigene Lookups genutzt werden (read-only)", async () => {
-    await testDb.db.execute(sql`
+    await asRawClient(testDb.db).unsafe(`
       INSERT INTO read_tenants (id, name, tenant_key) VALUES
         ('00000000-0000-4000-8000-000000000007'::uuid, 'Lucky', 'lucky')
     `);
@@ -349,8 +363,8 @@ describe("SeedMigrationContext.db (escape-hatch, integration)", () => {
       dispatcher: makeMockDispatcher() as never,
       dbRunner: testDb.db,
     });
-    const rows = (await ctx.db.execute(
-      sql`SELECT name FROM read_tenants WHERE tenant_key = 'lucky'`,
+    const rows = (await asRawClient(ctx.db).unsafe(
+      `SELECT name FROM read_tenants WHERE tenant_key = 'lucky'`,
     )) as unknown as readonly { name: string }[];
     expect(rows[0]?.name).toBe("Lucky");
   });

package/src/es-ops/__tests__/{runner.integration.ts → runner.integration.test.ts}

@@ -8,19 +8,21 @@
 // Heavy lifting (mock-dispatcher, in-memory-applied-set) liegt in
 // runner.test.ts. Hier nur DB-Round-Trip-Wahrheit.
 
+import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { sql } from "drizzle-orm";
-import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
-import { createTestDb, type TestDb } from "../../stack";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient, insertOne, selectMany } from "../../db/query";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { createSeedMigrationContext } from "../context";
 import { createEsOperationsTable, esOperationsTable } from "../operations-schema";
 import { runPendingSeedMigrations } from "../runner";
 
-let testDb: TestDb;
+let testDb: BunTestDb;
 
 beforeAll(async () => {
+  await ensureTemporalPolyfill();
   testDb = await createTestDb();
   await createEsOperationsTable(testDb.db);
 });
@@ -30,7 +32,7 @@ afterAll(async () => {
 });
 
 beforeEach(async () => {
-  await testDb.db.execute(sql`TRUNCATE kumiko_es_operations RESTART IDENTITY`);
+  await asRawClient(testDb.db).unsafe(`TRUNCATE kumiko_es_operations RESTART IDENTITY`);
 });
 
 function makeTempSeedsDir(files: readonly { name: string; content: string }[]): string {
@@ -42,14 +44,14 @@ function makeTempSeedsDir(files: readonly { name: string; content: string }[]):
 function makeMockDispatcher() {
   const calls: Array<{ qn: string; payload: unknown }> = [];
   return {
-    write: vi.fn(async (qn: string, payload: unknown) => {
+    write: mock(async (qn: string, payload: unknown) => {
       calls.push({ qn, payload });
       return { isSuccess: true as const, data: {} };
     }),
-    query: vi.fn(),
-    command: vi.fn(),
-    batch: vi.fn(),
-    resolveAuthClaims: vi.fn(),
+    query: mock(),
+    command: mock(),
+    batch: mock(),
+    resolveAuthClaims: mock(),
     calls,
   };
 }
@@ -82,7 +84,7 @@ describe("runPendingSeedMigrations (integration)", () => {
       expect(r1.appliedIds).toEqual(["2026-05-20-noop"]);
 
       // Marker landed
-      const markers1 = await testDb.db.select().from(esOperationsTable);
+      const markers1 = await selectMany(testDb.db, esOperationsTable);
       expect(markers1).toHaveLength(1);
       expect(markers1[0]?.id).toBe("2026-05-20-noop");
       expect(markers1[0]?.operationType).toBe("seed-migration");
@@ -98,7 +100,7 @@ describe("runPendingSeedMigrations (integration)", () => {
         logger: () => {},
       });
       expect(r2.appliedIds).toEqual([]);
-      const markers2 = await testDb.db.select().from(esOperationsTable);
+      const markers2 = await selectMany(testDb.db, esOperationsTable);
       expect(markers2).toHaveLength(1);
     } finally {
       rmSync(dir, { recursive: true, force: true });
@@ -130,7 +132,7 @@ describe("runPendingSeedMigrations (integration)", () => {
         }),
       ).rejects.toThrow(/boom/);
 
-      const markers = await testDb.db.select().from(esOperationsTable);
+      const markers = await selectMany(testDb.db, esOperationsTable);
       expect(markers).toHaveLength(0);
     } finally {
       rmSync(dir, { recursive: true, force: true });
@@ -192,14 +194,14 @@ describe("runPendingSeedMigrations (integration)", () => {
     ]);
     try {
       const dispatcher = {
-        write: vi.fn(async () => ({
+        write: mock(async () => ({
           isSuccess: false as const,
           error: { code: "version_conflict", message: "stream changed" },
         })),
-        query: vi.fn(),
-        command: vi.fn(),
-        batch: vi.fn(),
-        resolveAuthClaims: vi.fn(),
+        query: mock(),
+        command: mock(),
+        batch: mock(),
+        resolveAuthClaims: mock(),
       };
 
       await expect(
@@ -214,7 +216,7 @@ describe("runPendingSeedMigrations (integration)", () => {
       ).rejects.toThrow(/version_conflict/);
 
       // Kein Marker — bei nächstem Boot würde der Seed retried
-      const markers = await testDb.db.select().from(esOperationsTable);
+      const markers = await selectMany(testDb.db, esOperationsTable);
       expect(markers).toHaveLength(0);
     } finally {
       rmSync(dir, { recursive: true, force: true });
@@ -264,7 +266,7 @@ describe("runPendingSeedMigrations (integration)", () => {
       expect(dispatcher.write).toHaveBeenCalledTimes(1);
       // Marker NICHT gesetzt — retry beim nächsten Boot wird die Migration
       // nochmal ausführen. Wenn der Write nicht idempotent ist → Duplikat.
-      const markers = await testDb.db.select().from(esOperationsTable);
+      const markers = await selectMany(testDb.db, esOperationsTable);
       expect(markers).toHaveLength(0);
     } finally {
       rmSync(dir, { recursive: true, force: true });
@@ -293,7 +295,7 @@ describe("runPendingSeedMigrations (integration)", () => {
     ]);
     try {
       // Pre-seed marker als wäre ein parallel-Pod schon durch
-      await testDb.db.insert(esOperationsTable).values({
+      await insertOne(testDb.db, esOperationsTable, {
         id: "2026-05-20-race",
         operationType: "seed-migration",
         durationMs: 42,
@@ -318,7 +320,7 @@ describe("runPendingSeedMigrations (integration)", () => {
       });
 
       expect(dispatcher.write).not.toHaveBeenCalled();
-      const markers = await testDb.db.select().from(esOperationsTable);
+      const markers = await selectMany(testDb.db, esOperationsTable);
       expect(markers).toHaveLength(1); // nur der pre-seeded
     } finally {
       rmSync(dir, { recursive: true, force: true });
@@ -354,7 +356,7 @@ describe("runPendingSeedMigrations (integration)", () => {
       ).rejects.toThrow(/stop here/);
 
       // Nur first hat marker — fails warf, never wurde nie attempted
-      const markers = await testDb.db.select().from(esOperationsTable);
+      const markers = await selectMany(testDb.db, esOperationsTable);
       expect(markers.map((m) => m.id)).toEqual(["2026-05-19-first"]);
     } finally {
       rmSync(dir, { recursive: true, force: true });

package/src/es-ops/__tests__/runner.test.ts

@@ -2,10 +2,10 @@
 // dispatcher-call) testen wir gegen Postgres in der integration-test.
 // Hier nur die pure-logic-Pfade die kein echtes DB brauchen.
 
+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 { describe, expect, test } from "vitest";
 import { runPendingSeedMigrations } from "../runner";
 
 function makeTempSeedsDir(files: readonly { name: string; content: string }[]): string {
@@ -14,31 +14,41 @@ function makeTempSeedsDir(files: readonly { name: string; content: string }[]):
   return dir;
 }
 
-// Minimal DB-Stub — Runner ruft transaction() + select() + insert() +
-// execute() auf. execute() liefert ein leeres array für den
-// re-check-inside-lock (= "nicht applied, weiter mit Run").
+// Minimal DB-Stub — Runner uses bun-db helpers (selectMany, insertOne) +
+// asRawClient(tx).unsafe(...) for the advisory lock + re-check + insert.
+// Returns parsed rows based on the SQL text shape:
+//   SELECT * FROM "kumiko_es_operations" ...  → applied-set rows
+//   SELECT pg_advisory_xact_lock(...)         → ignored
+//   SELECT 1 FROM "kumiko_es_operations" ...  → empty (= not applied)
+//   INSERT INTO "kumiko_es_operations" ...    → record + add to applied
 function makeStubDb(initialApplied: readonly string[] = []) {
   const inserts: Array<Record<string, unknown>> = [];
   const applied = new Set(initialApplied);
+  const unsafe = async (
+    sqlText: string,
+    params?: readonly unknown[],
+  ): Promise<readonly unknown[]> => {
+    if (/SELECT \* FROM "kumiko_es_operations"/.test(sqlText)) {
+      return Array.from(applied).map((id) => ({
+        id,
+        operationType: "seed-migration",
+      }));
+    }
+    if (/INSERT INTO "kumiko_es_operations"/.test(sqlText)) {
+      const id = String(params?.[0]);
+      inserts.push({ id });
+      applied.add(id);
+      return [{ id }];
+    }
+    // pg_advisory_xact_lock + re-check both yield empty → "not applied, run".
+    return [];
+  };
   const db = {
+    unsafe,
+    begin: async (cb: (tx: unknown) => Promise<unknown>) => cb(db),
     transaction: async (cb: (tx: unknown) => Promise<void>) => {
       await cb(db);
     },
-    select: () => ({
-      from: () => ({
-        where: async () => Array.from(applied).map((id) => ({ id })),
-      }),
-    }),
-    insert: () => ({
-      values: async (row: Record<string, unknown>) => {
-        inserts.push(row);
-        if (typeof row["id"] === "string") applied.add(row["id"]);
-      },
-    }),
-    // execute: für pg_advisory_xact_lock + re-check. Leere Liste = "nicht
-    // applied im Inner-Lock-Scope, weiter mit Run". applied-set check via
-    // select() oben wird sowieso schon angewendet.
-    execute: async (_q: unknown) => [],
   };
   return { db, inserts, applied };
 }

package/src/es-ops/context.ts

@@ -7,10 +7,15 @@
 // config-seed.ts:40). Events haben createdBy = SYSTEM_TENANT_ID-User
 // → audit-fähig.
 
-import { sql } from "drizzle-orm";
 import type { DbRunner } from "../db";
+import {
+  selectAllTenants,
+  selectMembershipsOfUser,
+  selectUserByEmail,
+} from "../db/queries/seed-context";
 import { createSystemUser, SYSTEM_TENANT_ID } from "../engine";
 import type { Dispatcher } from "../pipeline/dispatcher";
+import { parseStringArrayJson } from "../utils/parse-string-array-json";
 import type { SeedMembershipRow, SeedMigrationContext, SeedTenantRow } from "./types";
 
 export type CreateSeedMigrationContextArgs = {
@@ -59,63 +64,25 @@ export function createSeedMigrationContext(
     },
 
     findUserByEmail: async (email) => {
-      // Direct DB-Read via read_users-Projection (gleicher Pfad wie
-      // UserQueries.findForAuth aber ohne Dispatcher-Roundtrip; Seeds
-      // greifen oft 1-N Lookups → direkt schneller).
-      // @cast-boundary db-row — drizzle execute(sql) returns row-array
-      // direkt (kein { rows }-Wrapper); column-types vom SQL-Cast oben
-      const rows = (await args.dbRunner.execute(
-        sql`SELECT id::text AS id, email, tenant_id::text AS tenant_id
-            FROM read_users
-            WHERE email = ${email}
-            LIMIT 1`,
-      )) as unknown as readonly { id: string; email: string; tenant_id: string }[];
-      const row = rows[0];
+      const row = await selectUserByEmail(args.dbRunner, email);
       if (!row) return null;
-      return { id: row.id, email: row.email, tenantId: row.tenant_id };
+      return { id: row.id, email: row.email, tenantId: row.tenantId };
     },
 
     findMembershipsOfUser: async (userId) => {
-      // INNER JOIN auf kumiko_events um den stream-tenant (events.tenant_id
-      // der v1-Row) neben dem payload-tenant (memberships.tenant_id) zu
-      // liefern. Die beiden divergieren wenn das Aggregate von einem
-      // Executor mit fremder tenantId angelegt wurde (seedTenantMembership
-      // by=systemAdmin) — typischer publicstatus-Driver-Use-Case.
-      // INNER (nicht LEFT): kein v1-Event bei vorhandener Read-Row wäre
-      // Data-Drift, kein legitimer Zustand für Seed-Migrations.
-      // @cast-boundary db-row — roles ist JSON-string in der text-Spalte
-      // (Memory: tenant-membership.created payload "[\"User\"]"), wird unten geparst
-      const rows = (await args.dbRunner.execute(
-        sql`SELECT m.user_id::text AS user_id,
-                   m.tenant_id::text AS tenant_id,
-                   e.tenant_id::text AS stream_tenant_id,
-                   m.roles
-            FROM read_tenant_memberships m
-            JOIN kumiko_events e ON e.aggregate_id = m.id AND e.version = 1
-            WHERE m.user_id = ${userId}`,
-      )) as unknown as readonly {
-        user_id: string;
-        tenant_id: string;
-        stream_tenant_id: string;
-        roles: string;
-      }[];
+      const rows = await selectMembershipsOfUser(args.dbRunner, userId);
       return rows.map(
         (r): SeedMembershipRow => ({
           userId: r.user_id,
           tenantId: r.tenant_id,
           streamTenantId: r.stream_tenant_id,
-          roles: safeParseRolesJson(r.roles),
+          roles: parseStringArrayJson(r.roles),
         }),
       );
     },
 
     findTenants: async () => {
-      // @cast-boundary db-row
-      const rows = (await args.dbRunner.execute(
-        sql`SELECT id::text AS id, name, tenant_key
-            FROM read_tenants
-            ORDER BY inserted_at`,
-      )) as unknown as readonly { id: string; name: string; tenant_key: string }[];
+      const rows = await selectAllTenants(args.dbRunner);
       return rows.map((r): SeedTenantRow => ({ id: r.id, name: r.name, tenantKey: r.tenant_key }));
     },
 
@@ -123,17 +90,5 @@ export function createSeedMigrationContext(
   };
 }
 
-function safeParseRolesJson(raw: string): readonly string[] {
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    if (Array.isArray(parsed) && parsed.every((x) => typeof x === "string")) {
-      return parsed;
-    }
-  } catch {
-    // Fallthrough — return empty rather than throwing in a seed context.
-  }
-  return [];
-}
-
 // Re-export für Caller-Convenience.
 export type { SeedMigrationContext } from "./types";

package/src/es-ops/operations-schema.ts

@@ -10,9 +10,9 @@
 //   bunx kumiko ops seed:status      → operation_type = "seed-migration"
 //   bunx kumiko ops projection:status → operation_type = "projection-rebuild"
 
-import { sql } from "drizzle-orm";
+// sql now comes from native dialect
 import { type DbConnection, tableExists } from "../db";
-import { index, integer, table as pgTable, text, timestamp } from "../db/dialect";
+import { index, integer, table as pgTable, sql, text, timestamp } from "../db/dialect";
 import { unsafePushTables } from "../stack";
 
 export type EsOperationType = "seed-migration";

package/src/es-ops/runner.ts

@@ -22,20 +22,13 @@
 
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { eq, sql } from "drizzle-orm";
 import type { DbConnection, DbRunner } from "../db";
+import { acquireEsOpsAdvisoryLock, esOperationExists } from "../db/queries/es-ops";
+import { insertOne, selectMany } from "../db/query";
 import type { Registry } from "../engine";
 import { esOperationsTable } from "./operations-schema";
 import type { EsOperationAppliedBy, SeedMigration, SeedMigrationContext } from "./types";
 
-// Stabiler 32-bit-Integer-Lock-Key für pg_advisory_xact_lock. Multi-Replica-
-// Boots gegen den selben Stack greifen denselben Lock — sequentialisiert
-// die Migration ohne dass jedes Pod alle pending Files parallel anwendet.
-// Ohne Lock: Pod A + Pod B sehen beide dieselbe pending-Liste → beide
-// laufen migration.run() → events DOUBLED, marker-unique-constraint
-// catched zu spät (nur den Marker, nicht die schon-committed Events).
-const ES_OPS_LOCK_KEY = 0x65_73_6f_70; // 'esop' als hex
-
 export type RunPendingSeedMigrationsArgs = {
   readonly db: DbConnection;
   /** Absoluter Pfad zum seeds-Directory (typically <appRoot>/seeds). */
@@ -130,30 +123,24 @@ export async function runPendingSeedMigrations(
 
     const start = Date.now();
     try {
-      await args.db.transaction(async (tx) => {
+      await args.db.begin(async (tx: DbRunner) => {
         // Advisory-Lock: sequentialisiert Multi-Replica-Boots. Zweiter
         // Pod blockt bis erster fertig ist, dann re-checked sein
         // applied-set (außerhalb dieser Funktion in nächster Iteration)
         // und findet den Marker → skip. Lock wird beim Tx-Commit
         // automatisch released (xact-scope).
-        await tx.execute(sql`SELECT pg_advisory_xact_lock(${ES_OPS_LOCK_KEY})`);
+        await acquireEsOpsAdvisoryLock(tx);
 
-        // Re-check applied-set INSIDE Tx + Lock — verhindert Race
-        // wo Pod-A schon committed hat während Pod-B vor dem Lock
-        // war. Sonst würde Pod-B die Migration nochmal ausführen.
-        const reCheck = (await tx.execute(
-          sql`SELECT 1 FROM kumiko_es_operations WHERE id = ${entry.id} LIMIT 1`,
-        )) as unknown as readonly unknown[];
-        if (reCheck.length > 0) {
+        if (await esOperationExists(tx, entry.id)) {
           log(`${LOG_PREFIX} race-skip "${entry.id}" — applied by parallel boot`);
-          // skip: race-detected — other replica committed marker between
-          // loadAppliedIds() and this tx; their run already covered the work.
+          // skip: parallel boot won the advisory-lock and already applied
+          // this migration. Nothing more to do in this tx.
           return;
         }
 
         const ctx = args.createContext(tx);
         await migration.run(ctx);
-        await tx.insert(esOperationsTable).values({
+        await insertOne(tx, esOperationsTable, {
           id: entry.id,
           operationType: "seed-migration",
           durationMs: Date.now() - start,
@@ -204,11 +191,10 @@ async function listSeedFiles(seedsDir: string): Promise<readonly SeedFileEntry[]
 }
 
 async function loadAppliedIds(db: DbConnection): Promise<Set<string>> {
-  const rows = await db
-    .select({ id: esOperationsTable.id })
-    .from(esOperationsTable)
-    .where(eq(esOperationsTable.operationType, "seed-migration"));
-  return new Set(rows.map((r: { id: string }) => r.id));
+  const rows = await selectMany<{ id: string }>(db, esOperationsTable, {
+    operationType: "seed-migration",
+  });
+  return new Set(rows.map((r) => r.id));
 }
 
 async function loadSeedModule(filePath: string): Promise<SeedMigration> {