@cosmicdrift/kumiko-framework 0.4.1 → 0.5.1

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

@@ -0,0 +1,363 @@
+// Integration-Test gegen echtes Postgres. Verifiziert:
+// - Marker landet in kumiko_es_operations nach Erfolg
+// - Idempotency: zweiter Boot skipped applied seeds
+// - Tx-Rollback bei Failure (kein Marker geschrieben)
+// - systemWriteAs leitet zum Dispatcher durch
+// - End-to-End mit echten findUserByEmail / findMembershipsOfUser
+//
+// Heavy lifting (mock-dispatcher, in-memory-applied-set) liegt in
+// runner.test.ts. Hier nur DB-Round-Trip-Wahrheit.
+
+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 { createSeedMigrationContext } from "../context";
+import { createEsOperationsTable, esOperationsTable } from "../operations-schema";
+import { runPendingSeedMigrations } from "../runner";
+
+let testDb: TestDb;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEsOperationsTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(sql`TRUNCATE kumiko_es_operations RESTART IDENTITY`);
+});
+
+function makeTempSeedsDir(files: readonly { name: string; content: string }[]): string {
+  const dir = mkdtempSync(join(tmpdir(), "es-ops-integration-"));
+  for (const f of files) writeFileSync(join(dir, f.name), f.content);
+  return dir;
+}
+
+function makeMockDispatcher() {
+  const calls: Array<{ qn: string; payload: unknown }> = [];
+  return {
+    write: vi.fn(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(),
+    calls,
+  };
+}
+
+describe("runPendingSeedMigrations (integration)", () => {
+  test("first run: applies pending + writes marker, second run: skips applied", async () => {
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-noop.ts",
+        content: `
+          export default {
+            description: "no-op seed for integration test",
+            run: async () => {},
+          };
+        `,
+      },
+    ]);
+    try {
+      const dispatcher = makeMockDispatcher();
+
+      // First run: pending → applied
+      const r1 = await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: (dbRunner) =>
+          createSeedMigrationContext({ dispatcher: dispatcher as never, dbRunner }),
+        logger: () => {},
+      });
+      expect(r1.appliedIds).toEqual(["2026-05-20-noop"]);
+
+      // Marker landed
+      const markers1 = await testDb.db.select().from(esOperationsTable);
+      expect(markers1).toHaveLength(1);
+      expect(markers1[0]?.id).toBe("2026-05-20-noop");
+      expect(markers1[0]?.operationType).toBe("seed-migration");
+      expect(markers1[0]?.appliedBy).toBe("boot");
+
+      // Second run: already applied → skipped, no new markers
+      const r2 = await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: (dbRunner) =>
+          createSeedMigrationContext({ dispatcher: dispatcher as never, dbRunner }),
+        logger: () => {},
+      });
+      expect(r2.appliedIds).toEqual([]);
+      const markers2 = await testDb.db.select().from(esOperationsTable);
+      expect(markers2).toHaveLength(1);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("seed throws → Tx rollback, kein Marker geschrieben", async () => {
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-fails.ts",
+        content: `
+          export default {
+            description: "intentional fail",
+            run: async () => { throw new Error("boom"); },
+          };
+        `,
+      },
+    ]);
+    try {
+      const dispatcher = makeMockDispatcher();
+      await expect(
+        runPendingSeedMigrations({
+          db: testDb.db,
+          seedsDir: dir,
+          appliedBy: "boot",
+          createContext: (dbRunner) =>
+            createSeedMigrationContext({ dispatcher: dispatcher as never, dbRunner }),
+          logger: () => {},
+        }),
+      ).rejects.toThrow(/boom/);
+
+      const markers = await testDb.db.select().from(esOperationsTable);
+      expect(markers).toHaveLength(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("systemWriteAs leitet zum Dispatcher mit SYSTEM_TENANT-User durch", async () => {
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-uses-dispatcher.ts",
+        content: `
+          export default {
+            description: "calls a write-handler",
+            run: async (ctx) => {
+              await ctx.systemWriteAs("some:write:handler", { foo: "bar" });
+            },
+          };
+        `,
+      },
+    ]);
+    try {
+      const dispatcher = makeMockDispatcher();
+      await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: (dbRunner) =>
+          createSeedMigrationContext({ dispatcher: dispatcher as never, dbRunner }),
+        logger: () => {},
+      });
+
+      expect(dispatcher.write).toHaveBeenCalledTimes(1);
+      expect(dispatcher.write).toHaveBeenCalledWith(
+        "some:write:handler",
+        { foo: "bar" },
+        expect.objectContaining({ tenantId: expect.any(String) }),
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("WriteResult{isSuccess:false} → throw + Marker NICHT geschrieben", async () => {
+    // Critical: ohne diese Garantie würde ein silent-failed Write den Seed
+    // als "applied" markieren → beim nächsten Boot kein retry → DB-Drift
+    // bleibt unbemerkt.
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-write-fails.ts",
+        content: `
+          export default {
+            description: "tries a handler that returns isSuccess:false",
+            run: async (ctx) => {
+              await ctx.systemWriteAs("some:write:handler", { foo: "bar" });
+            },
+          };
+        `,
+      },
+    ]);
+    try {
+      const dispatcher = {
+        write: vi.fn(async () => ({
+          isSuccess: false as const,
+          error: { code: "version_conflict", message: "stream changed" },
+        })),
+        query: vi.fn(),
+        command: vi.fn(),
+        batch: vi.fn(),
+        resolveAuthClaims: vi.fn(),
+      };
+
+      await expect(
+        runPendingSeedMigrations({
+          db: testDb.db,
+          seedsDir: dir,
+          appliedBy: "boot",
+          createContext: (dbRunner) =>
+            createSeedMigrationContext({ dispatcher: dispatcher as never, dbRunner }),
+          logger: () => {},
+        }),
+      ).rejects.toThrow(/version_conflict/);
+
+      // Kein Marker — bei nächstem Boot würde der Seed retried
+      const markers = await testDb.db.select().from(esOperationsTable);
+      expect(markers).toHaveLength(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("documented limitation: dispatcher-writes vor throw bleiben committed (idempotency-Pflicht für seeds)", async () => {
+    // Documents NICHT-Garantie aus dem README: systemWriteAs läuft durch
+    // den App-Dispatcher mit eigener tx-Verwaltung — die Runner-Tx
+    // schützt NUR den Marker-Insert + direct dbRunner-reads, NICHT die
+    // dispatcher-Writes. Daher müssen Seeds idempotent sein.
+    //
+    // Test: dispatcher.write wird 1× erfolgreich aufgerufen, dann throws.
+    // Expectation:
+    //   - dispatcher.write was called 1x (confirms write went through)
+    //   - kein Marker (run was rolled back)
+    //   - bei "echtem" Setup wäre die Event-Row schon committed → retry
+    //     müsste idempotent sein, sonst Duplikat.
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-write-then-throw.ts",
+        content: `
+          export default {
+            description: "writes successfully then throws (idempotency test)",
+            run: async (ctx) => {
+              await ctx.systemWriteAs("some:write:handler", { step: 1 });
+              throw new Error("post-write failure");
+            },
+          };
+        `,
+      },
+    ]);
+    try {
+      const dispatcher = makeMockDispatcher();
+      await expect(
+        runPendingSeedMigrations({
+          db: testDb.db,
+          seedsDir: dir,
+          appliedBy: "boot",
+          createContext: (dbRunner) =>
+            createSeedMigrationContext({ dispatcher: dispatcher as never, dbRunner }),
+          logger: () => {},
+        }),
+      ).rejects.toThrow(/post-write failure/);
+
+      // Write-handler WURDE aufgerufen — dispatcher-tx isoliert vom runner-tx
+      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);
+      expect(markers).toHaveLength(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("applied-set filter: entries already in kumiko_es_operations werden geskipped", async () => {
+    // Test deckt den loadAppliedIds-Filter ab (pending = files \ applied).
+    // Der pg_advisory_xact_lock + inner-tx re-check ist eine zweite Defense-
+    // Linie für echte parallel-Pod-Races zwischen loadAppliedIds und der
+    // pro-Migration Tx — diese Race ist empirisch nicht reproduzierbar in
+    // einem Single-Process-Test ohne extra Lock-Coordination. Wir verifizieren
+    // hier nur die obere Filter-Schicht (häufigster Pfad).
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-race.ts",
+        content: `
+          export default {
+            description: "race-test",
+            run: async () => {
+              throw new Error("MUST NOT BE CALLED — re-check should skip");
+            },
+          };
+        `,
+      },
+    ]);
+    try {
+      // Pre-seed marker als wäre ein parallel-Pod schon durch
+      await testDb.db.insert(esOperationsTable).values({
+        id: "2026-05-20-race",
+        operationType: "seed-migration",
+        durationMs: 42,
+        appliedBy: "boot",
+        notes: "applied by simulated parallel-pod",
+      });
+
+      const dispatcher = makeMockDispatcher();
+      // Würde normalerweise als pending klassifiziert (loadAppliedIds liest
+      // BEFORE the tx) — der re-check inside tx muss das catchen.
+      // Achtung: das obere applied-set-load sieht den Marker auch schon —
+      // dieses Test ist daher eher eine Wahrscheinlichkeits-Aussage über
+      // den Race-Pfad, nicht ein deterministischer Race-Repro. Aber:
+      // wenn der re-check funktioniert, läuft `run()` nicht.
+      await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: (dbRunner) =>
+          createSeedMigrationContext({ dispatcher: dispatcher as never, dbRunner }),
+        logger: () => {},
+      });
+
+      expect(dispatcher.write).not.toHaveBeenCalled();
+      const markers = await testDb.db.select().from(esOperationsTable);
+      expect(markers).toHaveLength(1); // nur der pre-seeded
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("multiple seeds: apply in chronological order, halt on first failure", async () => {
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-19-first.ts",
+        content: `export default { description: "first", run: async () => {} };`,
+      },
+      {
+        name: "2026-05-20-fails.ts",
+        content: `export default { description: "fails", run: async () => { throw new Error("stop here"); } };`,
+      },
+      {
+        name: "2026-05-21-never.ts",
+        content: `export default { description: "never reached", run: async () => {} };`,
+      },
+    ]);
+    try {
+      const dispatcher = makeMockDispatcher();
+      await expect(
+        runPendingSeedMigrations({
+          db: testDb.db,
+          seedsDir: dir,
+          appliedBy: "boot",
+          createContext: (dbRunner) =>
+            createSeedMigrationContext({ dispatcher: dispatcher as never, dbRunner }),
+          logger: () => {},
+        }),
+      ).rejects.toThrow(/stop here/);
+
+      // Nur first hat marker — fails warf, never wurde nie attempted
+      const markers = await testDb.db.select().from(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

@@ -0,0 +1,192 @@
+// Unit-Tests für den runner. Heavy lifting (Tx, applied-set-diff,
+// dispatcher-call) testen wir gegen Postgres in der integration-test.
+// Hier nur die pure-logic-Pfade die kein echtes DB brauchen.
+
+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 {
+  const dir = mkdtempSync(join(tmpdir(), "es-ops-test-"));
+  for (const f of files) writeFileSync(join(dir, f.name), f.content);
+  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").
+function makeStubDb(initialApplied: readonly string[] = []) {
+  const inserts: Array<Record<string, unknown>> = [];
+  const applied = new Set(initialApplied);
+  const 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 };
+}
+
+describe("runPendingSeedMigrations", () => {
+  test("no seeds dir → no-op", async () => {
+    const { db } = makeStubDb();
+    const result = await runPendingSeedMigrations({
+      db: db as never,
+      seedsDir: "/path/does/not/exist",
+      appliedBy: "boot",
+      createContext: () => ({}) as never,
+      logger: () => {},
+    });
+    expect(result.appliedIds).toEqual([]);
+    expect(result.skippedIds).toEqual([]);
+  });
+
+  test("listSeedFiles: filtert non-seed Files raus, sortiert chronologisch", async () => {
+    const dir = makeTempSeedsDir([
+      { name: "2026-05-20-fix-roles.ts", content: makeSeedFile("fix-roles") },
+      { name: "2026-05-19-init.ts", content: makeSeedFile("init") },
+      { name: "_helper.ts", content: makeSeedFile("helper") }, // _-prefix → skip
+      { name: "README.md", content: "" }, // .md → skip
+      { name: ".hidden.ts", content: "" }, // dot-prefix → skip
+    ]);
+    try {
+      const { db } = makeStubDb();
+      const result = await runPendingSeedMigrations({
+        db: db as never,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: () => ({}) as never,
+        logger: () => {},
+      });
+      // Beide gültige seeds laufen, in chronologischer Reihenfolge
+      expect(result.appliedIds).toEqual(["2026-05-19-init", "2026-05-20-fix-roles"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("skippable + env-flag → skip ohne run", async () => {
+    const dir = makeTempSeedsDir([
+      { name: "2026-05-20-skip-me.ts", content: makeSeedFile("skip-me", { skippable: true }) },
+    ]);
+    const envKey = "KUMIKO_SKIP_ES_OPS_2026_05_20_SKIP_ME";
+    process.env[envKey] = "1";
+    try {
+      const { db, inserts } = makeStubDb();
+      const result = await runPendingSeedMigrations({
+        db: db as never,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: () => ({}) as never,
+        logger: () => {},
+      });
+      expect(result.appliedIds).toEqual([]);
+      expect(result.skippedIds).toEqual(["2026-05-20-skip-me"]);
+      // Kein marker geschrieben — beim nächsten Boot ohne Flag würde es laufen
+      expect(inserts).toHaveLength(0);
+    } finally {
+      delete process.env[envKey];
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("already-applied seed wird übersprungen", async () => {
+    const dir = makeTempSeedsDir([
+      { name: "2026-05-19-init.ts", content: makeSeedFile("init") },
+      { name: "2026-05-20-new.ts", content: makeSeedFile("new") },
+    ]);
+    try {
+      const { db, inserts } = makeStubDb(["2026-05-19-init"]);
+      const result = await runPendingSeedMigrations({
+        db: db as never,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: () => ({}) as never,
+        logger: () => {},
+      });
+      // Nur new lief
+      expect(result.appliedIds).toEqual(["2026-05-20-new"]);
+      expect(inserts).toHaveLength(1);
+      expect(inserts[0]?.["id"]).toBe("2026-05-20-new");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("seed-file ohne default-export → klarer Error", async () => {
+    const dir = makeTempSeedsDir([
+      { name: "2026-05-20-broken.ts", content: "export const notDefault = {};" },
+    ]);
+    try {
+      const { db } = makeStubDb();
+      await expect(
+        runPendingSeedMigrations({
+          db: db as never,
+          seedsDir: dir,
+          appliedBy: "boot",
+          createContext: () => ({}) as never,
+          logger: () => {},
+        }),
+      ).rejects.toThrow(/must export a SeedMigration as default/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("seed.run throws → abort + no marker", async () => {
+    const dir = makeTempSeedsDir([
+      { name: "2026-05-20-good.ts", content: makeSeedFile("good") },
+      { name: "2026-05-21-fails.ts", content: makeSeedFile("fails", { fail: true }) },
+      { name: "2026-05-22-never.ts", content: makeSeedFile("never") },
+    ]);
+    try {
+      const { db, inserts } = makeStubDb();
+      await expect(
+        runPendingSeedMigrations({
+          db: db as never,
+          seedsDir: dir,
+          appliedBy: "boot",
+          createContext: () => ({}) as never,
+          logger: () => {},
+        }),
+      ).rejects.toThrow();
+      // good lief, fails warf, never wurde NIE attempted
+      expect(inserts.map((r) => r["id"])).toEqual(["2026-05-20-good"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// --- Test-Helpers -----------------------------------------------------------
+
+function makeSeedFile(
+  description: string,
+  options: { skippable?: boolean; fail?: boolean } = {},
+): string {
+  return `
+export default {
+  description: ${JSON.stringify(description)},
+  ${options.skippable ? "skippable: true," : ""}
+  run: async () => {
+    ${options.fail ? "throw new Error('intentional fail');" : ""}
+  },
+};
+`;
+}

package/src/es-ops/context.ts

@@ -0,0 +1,113 @@
+// SeedMigrationContext-Builder. Caller (runProdApp/CLI) übergibt einen
+// schon-konfigurierten Dispatcher; der Builder produziert pro-Migration
+// einen tx-scoped Context der via dispatcher.write den existierenden
+// Handler-Pfad nutzt — gleiches Pattern wie ein User-UI-Click.
+//
+// SystemUser bypassed Access-Checks (Standard-Seed-Pattern, siehe
+// 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 { createSystemUser, SYSTEM_TENANT_ID } from "../engine";
+import type { Dispatcher } from "../pipeline/dispatcher";
+import type { SeedMembershipRow, SeedMigrationContext, SeedTenantRow } from "./types";
+
+export type CreateSeedMigrationContextArgs = {
+  readonly dispatcher: Dispatcher;
+  readonly dbRunner: DbRunner;
+};
+
+/** Builder: gibt eine factory-function zurück die der Runner pro-Migration
+ *  aufruft. Der dbRunner kann eine Top-Connection oder eine Tx sein —
+ *  Read-Helpers nutzen ihn direkt, systemWriteAs delegiert an dispatcher.
+ *
+ *  Hinweis: dispatcher.write hat eigene tx-Logik. Wenn der Runner um die
+ *  Migration eine outer-tx legt, läuft dispatcher.write als nested via
+ *  postgres-savepoint. Beim Failure rollt der outer-tx auch das
+ *  dispatcher-write zurück → kein partial-Apply möglich. */
+export function createSeedMigrationContext(
+  args: CreateSeedMigrationContextArgs,
+): SeedMigrationContext {
+  const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+
+  return {
+    systemWriteAs: async (handlerQualifiedName, payload) => {
+      const result = await args.dispatcher.write(handlerQualifiedName, payload, systemUser);
+      // Critical: WriteResult{isSuccess: false} würde sonst silent durchlaufen
+      // → Marker landet trotz failed-Write → Migration falsch als "applied"
+      // markiert. Hier throw damit der Runner's outer-tx rollback macht und
+      // Marker NICHT geschrieben wird. Seed-Author kann via try/catch eigene
+      // Fehler-Behandlung machen wenn ein soft-failure erwartet ist.
+      if (!result.isSuccess) {
+        const code = result.error?.code ?? "unknown";
+        const message = result.error?.message ?? "(no message)";
+        throw new Error(
+          `[es-ops/seed-migration] systemWriteAs("${handlerQualifiedName}") failed: ${code} — ${message}`,
+        );
+      }
+      return result;
+    },
+
+    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];
+      if (!row) return null;
+      return { id: row.id, email: row.email, tenantId: row.tenant_id };
+    },
+
+    findMembershipsOfUser: async (userId) => {
+      // @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 user_id::text AS user_id, tenant_id::text AS tenant_id, roles
+            FROM read_tenant_memberships
+            WHERE user_id = ${userId}`,
+      )) as unknown as readonly { user_id: string; tenant_id: string; roles: string }[];
+      return rows.map(
+        (r): SeedMembershipRow => ({
+          userId: r.user_id,
+          tenantId: r.tenant_id,
+          roles: safeParseRolesJson(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 }[];
+      return rows.map((r): SeedTenantRow => ({ id: r.id, name: r.name, tenantKey: r.tenant_key }));
+    },
+
+    db: args.dbRunner,
+  };
+}
+
+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";