@cosmicdrift/kumiko-framework 0.4.0 → 0.5.0

package/src/engine/types/config.ts

@@ -123,6 +123,12 @@ export type ConfigStoredRow = {
   readonly userId: string | null;
 };
 
+// Extended row returned by ConfigResolver.getAllWithSource — includes the
+// resolution source so the UI can display where each value came from.
+export type ConfigStoredRowWithSource = ConfigStoredRow & {
+  readonly source: ConfigValueSource;
+};
+
 // Which layer of the cascade actually produced a value. Emitted only by
 // `getWithSource` — regular `get` hides this to keep the hot-path simple.
 // Use-case: Ops-debugging ("warum ist mein Wert 50 und nicht 100?") without
@@ -141,6 +147,22 @@ export type ConfigValueWithSource = {
   readonly source: ConfigValueSource;
 };
 
+/// Full cascade for a single config key — every level the resolver
+/// walks through, with the winning level marked.
+export type ConfigCascadeLevel = {
+  readonly label: string;
+  readonly value: string | number | boolean | undefined;
+  readonly source: ConfigValueSource;
+  readonly isActive: boolean;
+  readonly hasValue: boolean;
+};
+
+export type ConfigCascade = {
+  readonly value: string | number | boolean | undefined;
+  readonly source: ConfigValueSource;
+  readonly levels: readonly ConfigCascadeLevel[];
+};
+
 // Minimal contract handlers (set/reset/values.query) call against the
 // resolver. Lives in the framework so SharedContextFields.configResolver
 // can drop the `unknown` cast — the concrete implementation in
@@ -176,6 +198,39 @@ export type ConfigResolver = {
     userId: string,
     db: DbConnection | TenantDb,
   ): Promise<ReadonlyMap<string, ConfigStoredRow>>;
+
+  // Like getAll() but also reports the resolution source for each key.
+  // Use when the caller needs to display the cascade origin (e.g. the
+  // values.query handler serves the UI's hierarchy badge). Hot-path
+  // callers should prefer getAll() for the narrower return type.
+  getAllWithSource(
+    tenantId: TenantId,
+    userId: string,
+    db: DbConnection | TenantDb,
+  ): Promise<ReadonlyMap<string, ConfigStoredRowWithSource>>;
+
+  // Returns ALL cascade levels for a single key — not just the winner.
+  // Each level shows its value (or undefined if not set) and whether it
+  // is the active/winning level. Levels are ordered by specificity
+  // descending (most specific first).
+  getCascade(
+    qualifiedKey: string,
+    keyDef: ConfigKeyDefinition,
+    tenantId: TenantId,
+    userId: string,
+    db: DbConnection | TenantDb,
+  ): Promise<ConfigCascade>;
+
+  // Batch variant: resolves cascades for N keys in one DB round-trip.
+  // keyDefs must contain definitions for every key in the keys array.
+  // Returns a map of qualifiedKey → ConfigCascade.
+  getCascadeBatch(
+    keys: readonly string[],
+    keyDefs: ReadonlyMap<string, ConfigKeyDefinition>,
+    tenantId: TenantId,
+    userId: string,
+    db: DbConnection | TenantDb,
+  ): Promise<ReadonlyMap<string, ConfigCascade>>;
 };
 
 // --- Process-Placement (runIn) ---
@@ -304,3 +359,44 @@ export type ReferenceDataDef = {
   readonly data: readonly Record<string, unknown>[];
   readonly upsertKey?: string | undefined;
 };
+
+// --- Config Seeding ---
+
+// A deploy-time default for a config key, written via the event-store
+// executor at boot. Idempotent — if the stream already exists the executor
+// returns version_conflict and seedConfigValues counts it as skipped.
+// See config-seeding.md.
+//
+// `scope` is optional on the factory-output: createSeed leaves it unset
+// (define-feature derives it from keyDef.scope). createSystemSeed /
+// createTenantSeed / createUserSeed always set it explicitly.
+//
+// `tenantId` / `userId` semantics:
+//   - system scope: both stay undefined (row stored under SYSTEM_TENANT_ID).
+//   - tenant scope: tenantId optional (undefined → fallback row under
+//     SYSTEM_TENANT_ID, visible to all tenants via resolver cascade).
+//   - user scope: BOTH tenantId AND userId required, otherwise the resolver
+//     can never match the row (user-scope cascade looks up the user's actual
+//     tenantId, not SYSTEM_TENANT_ID).
+export type ConfigSeedDef = {
+  readonly key: string; // fully-qualified config key name (set by define-feature)
+  readonly value: string | number | boolean;
+  readonly scope?: ConfigScope;
+  readonly tenantId?: string;
+  readonly userId?: string;
+};
+
+// Factory types for ergonomic seed creation in r.config({ seeds }).
+
+export type CreateSeedOptions = {
+  readonly value: string | number | boolean;
+};
+
+export type CreateTenantSeedOptions = {
+  readonly tenantId?: string;
+};
+
+export type CreateUserSeedOptions = {
+  readonly tenantId: string;
+  readonly userId: string;
+};

package/src/engine/types/feature.ts

@@ -5,6 +5,7 @@ import type {
   ConfigKeyDefinition,
   ConfigKeyHandle,
   ConfigKeyType,
+  ConfigSeedDef,
   JobDefinition,
   JobHandlerFn,
   NotificationDataFn,
@@ -170,6 +171,7 @@ export type FeatureDefinition = {
   readonly hooks: HookMap;
   readonly entityHooks: EntityHookMap;
   readonly configKeys: Readonly<Record<string, ConfigKeyDefinition>>;
+  readonly configSeeds: readonly ConfigSeedDef[];
   readonly jobs: Readonly<Record<string, JobDefinition>>;
   readonly registrarExtensions: Readonly<Record<string, RegistrarExtensionDef>>;
   readonly extensionUsages: readonly RegistrarExtensionRegistration[];
@@ -356,8 +358,11 @@ export type FeatureRegistrar<TFeature extends string = string> = {
 
   // Returns a handle map keyed exactly like the input. Pass any handle to
   // `ctx.config(handle)` to get the value type narrowed by the key's `type`.
+  // Optional `seeds` declare boot-time system-rows that are written via the
+  // event-store executor — idempotent, skipped when the stream already exists.
   config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
     readonly keys: TKeys;
+    readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
   }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> };
 
   job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
@@ -656,6 +661,7 @@ export type Registry = {
   getAllTranslations(): TranslationKeys;
   getConfigKey(qualifiedKey: string): ConfigKeyDefinition | undefined;
   getAllConfigKeys(): ReadonlyMap<string, ConfigKeyDefinition>;
+  getAllConfigSeeds(): readonly ConfigSeedDef[];
   // Feature-declared secrets, aggregated across all registered features.
   // Keyed by qualified name ("<feature>:<shortName>"). Used by the rotation
   // job (to iterate "known" secrets) and admin-UIs to list available keys.

package/src/engine/types/index.ts

@@ -13,6 +13,8 @@ export type {
   ConfigAccessor,
   ConfigAccessorFactory,
   ConfigBounds,
+  ConfigCascade,
+  ConfigCascadeLevel,
   ConfigComputedContext,
   ConfigComputedFn,
   ConfigDefinition,
@@ -21,10 +23,15 @@ export type {
   ConfigKeyHandle,
   ConfigKeyType,
   ConfigResolver,
+  ConfigSeedDef,
   ConfigStoredRow,
+  ConfigStoredRowWithSource,
   ConfigValue,
   ConfigValueSource,
   ConfigValueWithSource,
+  CreateSeedOptions,
+  CreateTenantSeedOptions,
+  CreateUserSeedOptions,
   JobDefinition,
   JobHandlerFn,
   JobRunIn,

package/src/es-ops/README.md

@@ -0,0 +1,119 @@
+# es-ops
+
+ES-Operations für Kumiko-Apps. Phase 1 liefert `seed-migrations` als file-basiertes Diff-and-Apply für Aggregate-State-Updates, die idempotent-Seeder nicht erfassen können.
+
+## Quick API
+
+```ts
+import { runProdApp } from "@cosmicdrift/kumiko-dev-server";
+
+await runProdApp({
+  features: [...],
+  seedsDir: "./seeds",   // ← einzige Setup-Pflicht
+  // ...
+});
+```
+
+> **Phase 1 Scope:** `runProdApp`-only. `runDevApp`-Integration folgt in Phase 1.5 (braucht separaten Dispatcher-Bootstrap, der stack-typed ist). Für lokale Tests: laufe `bunx kumiko ops seed:status` gegen die Dev-DB um pending seeds zu sehen, dann `runProdApp` lokal mit DEV-Connection für Apply.
+
+```ts
+// seeds/2026-05-20-fix-admin-roles.ts
+import type { SeedMigration } from "@cosmicdrift/kumiko-framework/es-ops";
+
+export default {
+  description: "ergänze TenantAdmin-Rolle für admin@example.com",
+  run: async (ctx) => {
+    const admin = await ctx.findUserByEmail("admin@example.com");
+    if (!admin) return;
+    for (const m of await ctx.findMembershipsOfUser(admin.id)) {
+      if (m.roles.includes("TenantAdmin")) continue;
+      await ctx.systemWriteAs("tenant:write:updateMemberRoles", {
+        userId: admin.id,
+        tenantId: m.tenantId,
+        roles: [...m.roles, "TenantAdmin"],
+      });
+    }
+  },
+} satisfies SeedMigration;
+```
+
+## CLI
+
+```bash
+bunx kumiko ops seed:new <slug>    # scaffold seeds/<date>-<slug>.ts
+bunx kumiko ops seed:status        # was applied, was pending
+bunx kumiko ops seed:apply [--dry-run]  # pending applien (CLI-Pfad in Phase 1.5)
+```
+
+## Garantien
+
+| Garantie | Wie |
+|---|---|
+| **Single-Run** | Marker in `kumiko_es_operations` + `pg_advisory_xact_lock` sequentialisiert Multi-Replica-Boots |
+| **Marker-Atomicity** | Runner-Tx + Re-Check inside lock → Marker reflektiert "Run wurde wirklich attempted" |
+| **Order** | File-name = chronologische ID; Failure stoppt alle pending |
+| **ES-konform** | `systemWriteAs` ruft existing Handler → Events landen im Store |
+| **Recovery** | `skippable: true` + `KUMIKO_SKIP_ES_OPS_<ID>=1` env-flag für Notfall-Skip |
+| **Boot-skip** | `KUMIKO_SKIP_ES_OPS=1` env-var skipped alle pending (Debug-Boots) |
+
+### Was NICHT garantiert ist
+
+**Seed-Body ist NICHT atomic vs. den Marker.** `systemWriteAs` läuft durch den App-Dispatcher mit dessen eigener Tx-Verwaltung (separat von der Runner-Tx). Wenn ein Seed `systemWriteAs` 5× erfolgreich aufruft und dann throws, sind die 5 Events **committed**, der Marker aber **nicht** geschrieben. Beim nächsten Boot retried der Runner — Seeds müssen daher **idempotent** sein:
+
+```ts
+// Gut: skip wenn schon korrigiert
+for (const m of memberships) {
+  if (m.roles.includes("TenantAdmin")) continue;
+  await ctx.systemWriteAs(...);
+}
+
+// Schlecht: jeder Re-Run dupliziert
+for (const m of memberships) {
+  await ctx.systemWriteAs("create-something-new", ...); // double on retry!
+}
+```
+
+Die meisten realen Seeds sind natürlich idempotent (existing-Lookup → conditional-write). Volle End-to-End-Atomicity (write + marker im gleichen Tx) ist als Phase 1.5 vorgesehen — braucht Refactor wie der Dispatcher die outer-Tx übernimmt.
+
+## Architektur
+
+`packages/framework/src/es-ops/` enthält:
+
+| File | Zweck |
+|---|---|
+| `operations-schema.ts` | `kumiko_es_operations` table-definition + `createEsOperationsTable` helper |
+| `types.ts` | `SeedMigration` + `SeedMigrationContext` Public-API |
+| `runner.ts` | `runPendingSeedMigrations` — Diff + Tx + Marker |
+| `context.ts` | `createSeedMigrationContext` — Read-Helpers + `systemWriteAs` |
+| `index.ts` | barrel-export |
+
+Tabellen-Schema:
+
+```sql
+CREATE TABLE kumiko_es_operations (
+  id              TEXT PRIMARY KEY,
+  operation_type  TEXT NOT NULL,                -- "seed-migration" | (Phase 2+)
+  applied_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+  duration_ms     INTEGER NOT NULL,
+  applied_by      TEXT NOT NULL,                -- "boot" | "cli" | "ci-pipeline"
+  notes           TEXT
+);
+```
+
+## Phase 2+
+
+`operation_type`-Discriminator lässt zukünftige Operations dieselbe Tabelle + dasselbe CLI-Pattern nutzen:
+
+- `projection-rebuild` — TRUNCATE read_* + Replay aus Events
+- `event-replay` — Notification re-send ohne DB-Write
+- `event-backfill` — Missing-Events für Pre-ES-Daten
+- `stream-migration` — Aggregate-Stream-Tenant-Move (Sysadmin-Bug)
+- `aggregate-rebuild` — Snapshot-Refresh
+
+Implementation: **on demand** (siehe `kumiko-platform/docs/plans/features/es-ops.md`).
+
+## Driver-Use-Case
+
+publicstatus' admin-Member hatte initial `roles: ["Admin"]`. Sprint Role-Naming-Drift ergänzte „TenantAdmin", aber der idempotent-Seeder skipped existing Memberships → DB-Drift. Phase 1 löst genau diese Klasse von Bugs.
+
+Siehe Sample: `samples/recipes/seed-migration/`.

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

@@ -0,0 +1,267 @@
+// Integration-Tests für SeedMigrationContext-Read-Helpers + skippable-
+// integration. Verifizieren dass:
+// - findUserByEmail liest read_users korrekt (typed result-cast)
+// - findMembershipsOfUser parst JSON-encoded roles korrekt
+// - findTenants returnt sorted-by-inserted_at
+// - skippable + env-flag: kein marker geschrieben (gegen real-DB)
+// - ctx.db ist DbRunner (Escape-Hatch für direct-reads)
+//
+// Schema-stubs sind raw CREATE TABLE, weil das vollständige user/tenant-
+// Feature in den Tests zu schwer wäre — wir testen nur den Read-Helper-
+// Layer, nicht die volle Event-Store-Pipeline.
+
+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);
+
+  // 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`
+    CREATE TABLE IF NOT EXISTS read_users (
+      id          uuid PRIMARY KEY,
+      email       text NOT NULL,
+      tenant_id   uuid NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
+      id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+      user_id     text NOT NULL,
+      tenant_id   uuid NOT NULL,
+      roles       text NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS read_tenants (
+      id            uuid PRIMARY KEY,
+      name          text NOT NULL,
+      tenant_key    text NOT NULL,
+      inserted_at   timestamptz NOT NULL DEFAULT now()
+    );
+  `);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(sql`
+    TRUNCATE kumiko_es_operations, read_users, read_tenant_memberships, read_tenants
+  `);
+});
+
+function makeMockDispatcher() {
+  return {
+    write: vi.fn(async () => ({ isSuccess: true as const, data: {} })),
+    query: vi.fn(),
+    command: vi.fn(),
+    batch: vi.fn(),
+    resolveAuthClaims: vi.fn(),
+  };
+}
+
+function makeTempSeedsDir(files: readonly { name: string; content: string }[]): string {
+  const dir = mkdtempSync(join(tmpdir(), "es-ops-ctx-integ-"));
+  for (const f of files) writeFileSync(join(dir, f.name), f.content);
+  return dir;
+}
+
+// --- Read-Helpers --------------------------------------------------------
+
+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`
+      INSERT INTO read_users (id, email, tenant_id)
+      VALUES (${userId}::uuid, 'admin@example.com', ${tenantId}::uuid)
+    `);
+
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const found = await ctx.findUserByEmail("admin@example.com");
+    expect(found).toEqual({ id: userId, email: "admin@example.com", tenantId });
+  });
+
+  test("liefert null bei unknown email (kein throw)", async () => {
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const found = await ctx.findUserByEmail("does-not-exist@example.com");
+    expect(found).toBeNull();
+  });
+});
+
+describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
+  test("parst JSON-encoded roles-Spalte zu string[]", async () => {
+    const userId = "01900000-0000-7000-8000-000000000001";
+    const tenantId1 = "00000000-0000-4000-8000-000000000001";
+    const tenantId2 = "00000000-0000-4000-8000-000000000002";
+    await testDb.db.execute(sql`
+      INSERT INTO read_tenant_memberships (user_id, tenant_id, roles) VALUES
+        (${userId}, ${tenantId1}::uuid, '["Admin", "TenantAdmin"]'),
+        (${userId}, ${tenantId2}::uuid, '["User"]')
+    `);
+
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const memberships = await ctx.findMembershipsOfUser(userId);
+    expect(memberships).toHaveLength(2);
+
+    const m1 = memberships.find((m) => m.tenantId === tenantId1);
+    expect(m1?.roles).toEqual(["Admin", "TenantAdmin"]);
+
+    const m2 = memberships.find((m) => m.tenantId === tenantId2);
+    expect(m2?.roles).toEqual(["User"]);
+  });
+
+  test("malformed roles-JSON → leeres Array (defensive, no throw)", async () => {
+    // Defensive: wenn ein corrupted row kommt, soll der Seed nicht
+    // explodieren — kann selbst entscheiden was zu tun ist.
+    const userId = "01900000-0000-7000-8000-000000000002";
+    await testDb.db.execute(sql`
+      INSERT INTO read_tenant_memberships (user_id, tenant_id, roles) VALUES
+        (${userId}, '00000000-0000-4000-8000-000000000003'::uuid, 'not-json')
+    `);
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const memberships = await ctx.findMembershipsOfUser(userId);
+    expect(memberships[0]?.roles).toEqual([]);
+  });
+
+  test("liefert leere Liste bei userId ohne memberships", async () => {
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const memberships = await ctx.findMembershipsOfUser("01900000-0000-7000-8000-000000000099");
+    expect(memberships).toEqual([]);
+  });
+});
+
+describe("SeedMigrationContext.findTenants (integration)", () => {
+  test("returnt alle Tenants sortiert nach inserted_at", async () => {
+    await testDb.db.execute(sql`
+      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')
+    `);
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const tenants = await ctx.findTenants();
+    expect(tenants.map((t) => t.tenantKey)).toEqual(["alpha", "beta"]); // ORDER BY inserted_at ASC
+    expect(tenants[0]).toMatchObject({ name: "Alpha", tenantKey: "alpha" });
+  });
+});
+
+// --- skippable + env-flag (Integration) ---------------------------------
+
+describe("runPendingSeedMigrations: skippable + env-flag (integration)", () => {
+  test("skippable=true + env-flag='1' → kein Marker in DB", async () => {
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-skip-via-env.ts",
+        content: `
+          export default {
+            description: "skippable seed",
+            skippable: true,
+            run: async () => {
+              throw new Error("MUST NOT BE CALLED — env-flag should skip me");
+            },
+          };
+        `,
+      },
+    ]);
+    const envKey = "KUMIKO_SKIP_ES_OPS_2026_05_20_SKIP_VIA_ENV";
+    process.env[envKey] = "1";
+    try {
+      const r = await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: (dbRunner) =>
+          createSeedMigrationContext({ dispatcher: makeMockDispatcher() as never, dbRunner }),
+        logger: () => {},
+      });
+      expect(r.appliedIds).toEqual([]);
+      expect(r.skippedIds).toEqual(["2026-05-20-skip-via-env"]);
+
+      // 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);
+      expect(markers).toHaveLength(0);
+    } finally {
+      delete process.env[envKey];
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("skippable=true OHNE env-flag → läuft normal", async () => {
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-skippable-but-no-flag.ts",
+        content: `
+          export default {
+            description: "skippable seed, kein env-flag gesetzt",
+            skippable: true,
+            run: async () => {},
+          };
+        `,
+      },
+    ]);
+    try {
+      const r = await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: (dbRunner) =>
+          createSeedMigrationContext({ dispatcher: makeMockDispatcher() as never, dbRunner }),
+        logger: () => {},
+      });
+      expect(r.appliedIds).toEqual(["2026-05-20-skippable-but-no-flag"]);
+      expect(r.skippedIds).toEqual([]);
+
+      const markers = await testDb.db.select().from(esOperationsTable);
+      expect(markers).toHaveLength(1);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// --- ctx.db Escape-Hatch (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`
+      INSERT INTO read_tenants (id, name, tenant_key) VALUES
+        ('00000000-0000-4000-8000-000000000007'::uuid, 'Lucky', 'lucky')
+    `);
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const rows = (await ctx.db.execute(
+      sql`SELECT name FROM read_tenants WHERE tenant_key = 'lucky'`,
+    )) as unknown as readonly { name: string }[];
+    expect(rows[0]?.name).toBe("Lucky");
+  });
+});