@cosmicdrift/kumiko-testing 0.388.0 → 0.390.0

package/src/e2e/seeded-tenant-fixture.ts

@@ -3,7 +3,6 @@ import type {
   APIRequestContext,
   BrowserContext,
   Page,
-  Request as PlaywrightRequest,
   PlaywrightTestArgs,
   PlaywrightTestOptions,
   PlaywrightWorkerArgs,
@@ -19,6 +18,11 @@ import {
   type SeedTenantOptions,
   withSession,
 } from "../seed-types";
+import {
+  appBootBudgetViolation,
+  DEFAULT_MAX_APP_BOOTS_PER_TEST,
+  observeAppBoots,
+} from "./app-boot-budget";
 import {
   CLIENT_IP_HEADER,
   clearSession,
@@ -69,6 +73,7 @@ export type E2eSeededTenant = Omit<SeededTenant, "addUser"> & {
 export type SeedTenantFixture = (opts?: E2eSeedTenantOptions) => Promise<E2eSeededTenant>;
 
 type E2eFixtures = {
+  maxAppBootsPerTest: number;
   seedTenant: SeedTenantFixture;
 };
 
@@ -230,52 +235,35 @@ export function perTestClientIpKey(
   return `${runToken ?? ""}:${testInfo.testId}:${testInfo.repeatEachIndex}:${testInfo.retry}`;
 }
 
-// Same-origin only: on a cross-origin fetch the extra header would force a
-// CORS preflight the target never agreed to (why extraHTTPHeaders is no option
-// here). An explicit X-Forwarded-For set by the test wins.
-export function headersWithClientIp(
-  request: { readonly url: string; readonly frameUrl: string | undefined },
-  headers: Readonly<Record<string, string>>,
-  clientIp: string,
-): Record<string, string> | undefined {
-  if (request.frameUrl === undefined) return undefined;
-  let sameOrigin: boolean;
-  try {
-    sameOrigin = new URL(request.frameUrl).origin === new URL(request.url).origin;
-  } catch {
-    return undefined;
-  }
-  return sameOrigin ? { [CLIENT_IP_HEADER]: clientIp, ...headers } : undefined;
-}
-
-function frameUrlOf(request: PlaywrightRequest): string | undefined {
-  try {
-    return request.frame().url();
-  } catch {
-    // Service-worker requests have no frame.
-    return undefined;
-  }
-}
-
+// Chromium turns its HTTP cache off for a context as soon as it has a route,
+// so the header goes through setExtraHTTPHeaders and the cache stays on.
 export async function providePerTestClientIpContext(
-  { context }: Pick<PlaywrightTestArgs, "context">,
+  {
+    context,
+    maxAppBootsPerTest,
+  }: Pick<PlaywrightTestArgs, "context"> & Pick<E2eFixtures, "maxAppBootsPerTest">,
   use: (context: BrowserContext) => Promise<void>,
-  testInfo: Pick<TestInfo, "testId" | "repeatEachIndex" | "retry">,
+  testInfo: Pick<TestInfo, "testId" | "repeatEachIndex" | "retry" | "status" | "expectedStatus">,
 ): Promise<void> {
-  const clientIp = syntheticClientIpFor(perTestClientIpKey(testInfo));
-  await context.route("**/api/**", (route) => {
-    const request = route.request();
-    const headers = headersWithClientIp(
-      { url: request.url(), frameUrl: frameUrlOf(request) },
-      request.headers(),
-      clientIp,
-    );
-    return headers === undefined ? route.fallback() : route.fallback({ headers });
+  await context.setExtraHTTPHeaders({
+    [CLIENT_IP_HEADER]: syntheticClientIpFor(perTestClientIpKey(testInfo)),
   });
+  const appBoots = observeAppBoots(context);
   await use(context);
+
+  // A window.open tab left open stalls the context close by seconds.
+  await Promise.all(context.pages().map((page) => (page.isClosed() ? undefined : page.close())));
+
+  // Only after a passing body, so the budget never hides the original failure.
+  const violation =
+    testInfo.status === testInfo.expectedStatus
+      ? appBootBudgetViolation(appBoots.count(), maxAppBootsPerTest)
+      : undefined;
+  if (violation !== undefined) throw new Error(violation);
 }
 
 export const test = base.extend<E2eFixtures>({
+  maxAppBootsPerTest: [DEFAULT_MAX_APP_BOOTS_PER_TEST, { option: true }],
   context: providePerTestClientIpContext,
   seedTenant: provideSeedTenant,
 });

package/src/helpers/closed-connection-error.ts

@@ -2,7 +2,6 @@
 // the production matcher checks driver-specific codes a fake can't reproduce.
 
 import { isClosedConnectionError } from "@cosmicdrift/kumiko-framework/internal/stack-support";
-import postgres from "postgres";
 import { requireEnv } from "../stack/db.ts";
 
 export function testDatabaseUrl(): string {
@@ -14,8 +13,6 @@ const READS_PER_ROUND = 5;
 
 type AdminClient = { unsafe(sql: string, params?: readonly unknown[]): Promise<unknown> };
 
-// A per-round admin client hits a postgres-js reconnect timing bug (the first
-// retry after terminate hangs); a single long-lived admin client avoids it.
 export async function terminateBackendsByApplicationName(
   admin: AdminClient,
   applicationName: string,
@@ -31,11 +28,11 @@ export async function terminateBackendsByApplicationName(
 export async function captureClosedConnectionError(
   url: string = testDatabaseUrl(),
 ): Promise<unknown> {
-  const admin = postgres(url, { max: 1 });
+  const admin = new Bun.SQL(url, { max: 1 });
   try {
     for (let round = 0; round < MAX_WARMUP_ROUNDS; round++) {
       const applicationName = `kumiko-closed-conn-test-${crypto.randomUUID()}`;
-      const pool = postgres(url, { max: 1, connection: { application_name: applicationName } });
+      const pool = new Bun.SQL(url, { max: 1, connection: { application_name: applicationName } });
       try {
         await pool.unsafe("select 1");
         await terminateBackendsByApplicationName(admin, applicationName);
@@ -47,13 +44,13 @@ export async function captureClosedConnectionError(
           }
         }
       } finally {
-        await pool.end({ timeout: 0 });
+        await pool.close({ timeout: 0 });
       }
     }
     throw new Error(
       `captureClosedConnectionError: no closed-connection error observed after ${MAX_WARMUP_ROUNDS} rounds.`,
     );
   } finally {
-    await admin.end({ timeout: 0 });
+    await admin.close({ timeout: 0 });
   }
 }

package/src/helpers/console-calls.ts

@@ -10,3 +10,12 @@ export function consoleCallsMentioning(
 ): ReadonlyArray<ReadonlyArray<unknown>> {
   return spy.mock.calls.filter((args) => args.some((arg) => String(arg).includes(fragment)));
 }
+
+// For "stays silent" assertions: counts every call from the given logger namespace instead of one
+// message text, so a new or reworded warning from the module under test still fails the test.
+export function consoleCallsFromNamespace(
+  spy: ConsoleSpyLike,
+  namespace: string,
+): ReadonlyArray<ReadonlyArray<unknown>> {
+  return spy.mock.calls.filter((args) => String(args[0]).startsWith(`[${namespace}]`));
+}

package/src/helpers/event-store-writes.ts

@@ -0,0 +1,160 @@
+// Test-side writes on event-sourced tables that go through the event store, so
+// the event log and the projection stay consistent. Unlike seed.ts these survive
+// a projection rebuild and fire the same events a handler would.
+
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  fetchOne,
+  selectMany,
+  type WhereObject,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { executorManagedEntitySourceOf } from "@cosmicdrift/kumiko-framework/internal/testing";
+
+type ExecutorArgs = Parameters<typeof createEventStoreExecutor>;
+
+export type EventStoreWriteTarget = {
+  readonly table: ExecutorArgs[0];
+  readonly entity: ExecutorArgs[1];
+  readonly entityName: string;
+};
+
+export type EventStoreWriteScope = {
+  /** Tenant of the acting system user and of the tenant-bound db; defaults to the system tenant. */
+  readonly tenantId?: TenantId;
+  /** Address a stream that lives on another tenant than the actor's. */
+  readonly streamTenantId?: TenantId;
+};
+
+type EntityId = string | number;
+
+function isEntityId(value: unknown): value is EntityId {
+  return typeof value === "string" || typeof value === "number";
+}
+
+async function loadTarget(
+  db: DbConnection,
+  target: EventStoreWriteTarget,
+  where: WhereObject,
+  verb: string,
+): Promise<{ id: EntityId; version: number }> {
+  const row = await fetchOne<Record<string, unknown>>(db, target.table, where);
+  if (!row) {
+    throw new Error(`${verb} ${target.entityName}: no row matches ${JSON.stringify(where)}`);
+  }
+  const { id, version } = row;
+  if (!isEntityId(id)) throw new Error(`${verb} ${target.entityName}: row has no id`);
+  if (typeof version !== "number") {
+    throw new Error(`${verb} ${target.entityName}: row has no numeric version`);
+  }
+  return { id, version };
+}
+
+function writeContext(scope: EventStoreWriteScope | undefined, db: DbConnection) {
+  const tenantId = scope?.tenantId ?? SYSTEM_TENANT_ID;
+  return {
+    user: createSystemUser(tenantId),
+    tenantDb: createTenantDb({
+      db,
+      tenantId,
+      mode: "system",
+      reason: "test helper seeds event-store rows for any tenant",
+    }),
+    options: scope?.streamTenantId ? { streamTenantId: scope.streamTenantId } : undefined,
+  };
+}
+
+function failedWrite(
+  verb: string,
+  entityName: string,
+  error: { readonly code: string; readonly details?: unknown },
+): Error {
+  return new Error(
+    `${verb} ${entityName} failed: ${error.code} ${JSON.stringify(error.details ?? {})}`,
+  );
+}
+
+// Same arguments as seedRow, so a seed on an entity table switches over by rename. The row's
+// tenantId picks the acting tenant (and so the stream tenant); seed global entities without one,
+// the executor rejects a tenantId on them.
+export async function seedRowViaEventStore(
+  db: DbConnection,
+  table: EventStoreWriteTarget["table"],
+  values: Readonly<Record<string, unknown>>,
+): Promise<void> {
+  const source = executorManagedEntitySourceOf(table);
+  if (!source) {
+    throw new Error(
+      "seedRowViaEventStore: table is not an event-sourced entity table (buildEntityTable or r.entity); use seedRow",
+    );
+  }
+  const { entity, entityName } = source;
+  const { tenantId, ...payload } = values;
+  if (payload["id"] !== undefined && typeof payload["id"] !== "string") {
+    throw new Error(
+      `seed ${entityName}: id must be a string, the event store would mint a new one`,
+    );
+  }
+  if (tenantId !== undefined && typeof tenantId !== "string") {
+    throw new Error(`seed ${entityName}: tenantId must be a string`);
+  }
+  const { user, tenantDb } = writeContext({ tenantId }, db);
+  const executor = createEventStoreExecutor(table, entity, { entityName });
+  const result = await executor.create(payload, user, tenantDb);
+  if (!result.isSuccess) throw failedWrite("seed", entityName, result.error);
+}
+
+export async function updateRowViaEventStore(
+  db: DbConnection,
+  target: EventStoreWriteTarget,
+  where: WhereObject,
+  changes: Readonly<Record<string, unknown>>,
+  scope?: EventStoreWriteScope,
+): Promise<void> {
+  const { id, version } = await loadTarget(db, target, where, "update");
+  const { user, tenantDb, options } = writeContext(scope, db);
+  const executor = createEventStoreExecutor(target.table, target.entity, {
+    entityName: target.entityName,
+  });
+  const result = await executor.update(
+    { id, version, changes: { ...changes } },
+    user,
+    tenantDb,
+    options,
+  );
+  if (!result.isSuccess) throw failedWrite("update", target.entityName, result.error);
+}
+
+export async function deleteRowViaEventStore(
+  db: DbConnection,
+  target: EventStoreWriteTarget,
+  where: WhereObject,
+  scope?: EventStoreWriteScope,
+): Promise<void> {
+  const { id } = await loadTarget(db, target, where, "delete");
+  const { user, tenantDb, options } = writeContext(scope, db);
+  const executor = createEventStoreExecutor(target.table, target.entity, {
+    entityName: target.entityName,
+  });
+  const result = await executor.delete({ id }, user, tenantDb, options);
+  if (!result.isSuccess) throw failedWrite("delete", target.entityName, result.error);
+}
+
+/** Deletes every row matching `where`, each through its own event-store delete. */
+export async function deleteRowsViaEventStore(
+  db: DbConnection,
+  target: EventStoreWriteTarget,
+  where: WhereObject,
+  scope?: EventStoreWriteScope,
+): Promise<void> {
+  const rows = await selectMany<{ id: EntityId }>(db, target.table, where);
+  for (const { id } of rows) {
+    await deleteRowViaEventStore(db, target, { id }, scope);
+  }
+}

package/src/helpers/index.ts

@@ -2,6 +2,12 @@
 // must import nothing from this subpath — the stack builders live in
 // `@cosmicdrift/kumiko-testing/stack`.
 
+// Scope setters for tests that call cross-tenant or tenant functions directly, outside dispatch.
+export {
+  runInRowLevelSecurityScope,
+  runInSystemRowLevelSecurityScope,
+  tenantRowLevelSecurityScope,
+} from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 // The four cache/injection resets stay in their own modules (they close over
 // module-private state) and are only re-exported here — they are out of /crypto
 // and /db. A production call to resetPiiSubjectKmsForTests() silently switches
@@ -23,7 +29,11 @@ export {
   terminateBackendsByApplicationName,
   testDatabaseUrl,
 } from "./closed-connection-error.ts";
-export { type ConsoleSpyLike, consoleCallsMentioning } from "./console-calls.ts";
+export {
+  type ConsoleSpyLike,
+  consoleCallsFromNamespace,
+  consoleCallsMentioning,
+} from "./console-calls.ts";
 export { type ClearableTable, clearTables, resetTestTables } from "./db-cleanup.ts";
 export {
   type E2EGeneratorOptions,
@@ -32,6 +42,14 @@ export {
   generateE2ESpec,
   generateZodFixture,
 } from "./e2e-generator.ts";
+export {
+  deleteRowsViaEventStore,
+  deleteRowViaEventStore,
+  type EventStoreWriteScope,
+  type EventStoreWriteTarget,
+  seedRowViaEventStore,
+  updateRowViaEventStore,
+} from "./event-store-writes.ts";
 export { expectErrorIncludes } from "./expect-error.ts";
 export { describeFileProviderContract } from "./file-provider-contract.ts";
 export {

package/src/helpers/mock-module.ts

@@ -0,0 +1,24 @@
+import { afterAll, mock } from "bun:test";
+
+/**
+ * Mocks `specifier` with the real exports plus `overrides` and restores the real module in
+ * `afterAll`: bun's mock.module is process-global, so a leaked mock breaks later files of a
+ * shared DOM run. Pass the namespace imported before mocking; it is copied here because
+ * mock.module patches an already imported namespace in place. A relative specifier must be
+ * absolute (resolve it against the test file), since mock.module resolves it from this file.
+ *
+ * `restoreOverrides` fixes up modules that re-export a mocked binding: their copy was taken
+ * under the mock and holds the spy, so it must be pointed back at the real export.
+ */
+export function mockModuleForFile(
+  specifier: string,
+  realModule: object,
+  overrides: Readonly<Record<string, unknown>>,
+  options: { readonly restoreOverrides?: Readonly<Record<string, unknown>> } = {},
+): void {
+  const real = { ...realModule };
+  mock.module(specifier, () => ({ ...real, ...overrides }));
+  afterAll(() => {
+    mock.module(specifier, () => ({ ...real, ...options.restoreOverrides }));
+  });
+}

package/src/scaffold.ts

@@ -181,7 +181,7 @@ function renderIntegrationTest(): string {
     "});",
     "",
     "afterAll(async () => {",
-    "  await stack.cleanup();",
+    "  await stack?.cleanup();",
     "});",
     "",
     'describe("tasks", () => {',

package/src/stack/db.ts

@@ -4,12 +4,15 @@
 import { DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX } from "@cosmicdrift/kumiko-framework/db";
 import {
   acquireSessionAdvisoryLock,
+  createApplicationRole,
   createDatabase,
   createDbConnection,
   databaseExists,
   dropDatabaseIfExists,
   listDatabaseNamesWithPrefix,
   renameDatabase,
+  transferDatabaseOwnership,
+  transferPublicSchemaOwnership,
 } from "@cosmicdrift/kumiko-framework/internal/stack-support";
 import { ensureTemporalPolyfill } from "@cosmicdrift/kumiko-framework/time";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
@@ -27,6 +30,9 @@ function requireEnv(name: string): string {
 
 export const DEFAULT_TEST_DB_POOL_MAX = 10;
 
+// Non-superuser without BYPASSRLS: the only login that makes row-level-security policies bite in tests.
+export const TEST_APPLICATION_ROLE = "kumiko_app";
+
 export type TestDb = {
   db: DbConnection;
   poolMax: number;
@@ -44,6 +50,8 @@ export type CreateTestDbOptions = {
   readonly outsideTransactionPoolMax?: number;
   /** Clone this already-migrated database instead of starting empty. */
   readonly templateDbName?: string;
+  /** Own the database as the non-bypass application role and enforce row-level security on the pools. */
+  readonly applicationRole?: boolean;
 };
 
 // Set by the integration runner for one run; templates named after it are dropped when the run ends.
@@ -62,6 +70,67 @@ function databaseUrlOf(url: string, dbName: string): string {
   return url.replace(/\/[^/]+$/, `/${dbName}`);
 }
 
+/**
+ * URL of database `dbName` on the host of `url`, logged in as TEST_APPLICATION_ROLE with the password
+ * of `url` (the caller's TEST_DATABASE_URL). Pair it with `createTestDb({ applicationRole: true })` or
+ * a database owned by that role, so boots with row level security on connect without BYPASSRLS.
+ */
+// DDL takes no bind params, so the password is read from the configured URL instead of a literal.
+export function applicationRoleUrlOf(url: string, dbName: string): string {
+  const parsed = new URL(url);
+  parsed.pathname = `/${dbName}`;
+  parsed.username = TEST_APPLICATION_ROLE;
+  parsed.password = new URL(url).password;
+  return parsed.toString();
+}
+
+async function ensureApplicationRole(admin: DbConnection, url: string): Promise<void> {
+  await createApplicationRole(
+    admin,
+    TEST_APPLICATION_ROLE,
+    decodeURIComponent(new URL(url).password),
+  );
+}
+
+// Admin connections below run as superuser for CREATE/DROP DATABASE and never open a tenant scope: "off" is explicit.
+async function adoptPersistentDatabase(
+  admin: DbConnection,
+  url: string,
+  dbName: string,
+): Promise<void> {
+  await transferDatabaseOwnership(admin, dbName, TEST_APPLICATION_ROLE);
+  const owner = createDbConnection({
+    url: databaseUrlOf(url, dbName),
+    maxConnections: 1,
+    rowLevelSecurity: "off", // superuser ownership transfer, no tenant scope
+  });
+  try {
+    await transferPublicSchemaOwnership(owner.db, TEST_APPLICATION_ROLE);
+  } finally {
+    await owner.close();
+  }
+}
+
+type ProvisionArgs = {
+  readonly url: string;
+  readonly dbName: string;
+  readonly opts: CreateTestDbOptions;
+  readonly applicationRole: boolean;
+  readonly owner: string | undefined;
+};
+
+async function provisionDatabase(
+  admin: DbConnection,
+  { url, dbName, opts, applicationRole, owner }: ProvisionArgs,
+): Promise<void> {
+  const existing = opts.persistent === true && (await databaseExists(admin, dbName));
+  if (existing && applicationRole) await adoptPersistentDatabase(admin, url, dbName);
+  if (!existing) {
+    const template = opts.persistent === true ? undefined : opts.templateDbName;
+    await createDatabase(admin, dbName, template, owner);
+  }
+}
+
 export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<TestDb> {
   await ensureTemporalPolyfill();
   const opts: CreateTestDbOptions = typeof arg === "string" ? { baseUrl: arg } : (arg ?? {});
@@ -69,24 +138,23 @@ export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<
   const dbName = opts.dbName ?? `kumiko_test_${generateId().slice(-8)}`;
   const adminUrl = adminUrlOf(url);
 
-  const admin = createDbConnection({ url: adminUrl, maxConnections: 1 });
+  const applicationRole = opts.applicationRole === true;
+  const owner = applicationRole ? TEST_APPLICATION_ROLE : undefined;
+  const admin = createDbConnection({ url: adminUrl, maxConnections: 1, rowLevelSecurity: "off" });
   try {
-    if (opts.persistent) {
-      if (!(await databaseExists(admin.db, dbName))) {
-        await createDatabase(admin.db, dbName);
-      }
-    } else {
-      await createDatabase(admin.db, dbName, opts.templateDbName);
-    }
+    if (applicationRole) await ensureApplicationRole(admin.db, url);
+    await provisionDatabase(admin.db, { url, dbName, opts, applicationRole, owner });
   } finally {
     await admin.close();
   }
 
-  const testUrl = databaseUrlOf(url, dbName);
+  const testUrl = applicationRole ? applicationRoleUrlOf(url, dbName) : databaseUrlOf(url, dbName);
+  const rowLevelSecurity = applicationRole ? "on" : "off";
   const poolMax = opts.poolMax ?? DEFAULT_TEST_DB_POOL_MAX;
-  const conn = createDbConnection({ url: testUrl, maxConnections: poolMax });
+  const conn = createDbConnection({ url: testUrl, maxConnections: poolMax, rowLevelSecurity });
   const outsideConn = createDbConnection({
     url: testUrl,
+    rowLevelSecurity,
     maxConnections: opts.outsideTransactionPoolMax ?? DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX,
   });
 
@@ -99,13 +167,17 @@ export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<
     db: conn.db,
     poolMax,
     outsideTransactionDb: outsideConn.db,
-    client: conn.client,
+    client: conn.listenClient,
     dbName,
     cleanup: async () => {
       await conn.close();
       await outsideConn.close();
       if (!opts.persistent) {
-        const admin2 = createDbConnection({ url: adminUrl, maxConnections: 1 });
+        const admin2 = createDbConnection({
+          url: adminUrl,
+          maxConnections: 1,
+          rowLevelSecurity: "off",
+        });
         try {
           await dropDatabaseIfExists(admin2.db, dbName);
         } finally {
@@ -123,10 +195,11 @@ const testDbTemplates = new Map<string, Promise<void>>();
 export function ensureTestDbTemplate(
   templateDbName: string,
   buildSchema: (db: DbConnection) => Promise<void>,
+  options: { readonly applicationRole?: boolean } = {},
 ): Promise<void> {
   const known = testDbTemplates.get(templateDbName);
   if (known) return known;
-  const pending = buildTestDbTemplate(templateDbName, buildSchema);
+  const pending = buildTestDbTemplate(templateDbName, buildSchema, options);
   testDbTemplates.set(templateDbName, pending);
   pending.catch(() => testDbTemplates.delete(templateDbName));
   return pending;
@@ -135,10 +208,16 @@ export function ensureTestDbTemplate(
 export async function buildTestDbTemplate(
   templateDbName: string,
   buildSchema: (db: DbConnection) => Promise<void>,
+  options: { readonly applicationRole?: boolean } = {},
 ): Promise<void> {
+  const applicationRole = options.applicationRole === true;
   const url = requireEnv("TEST_DATABASE_URL");
   // One connection, so the session that takes the advisory lock is the one closed below.
-  const admin = createDbConnection({ url: adminUrlOf(url), maxConnections: 1 });
+  const admin = createDbConnection({
+    url: adminUrlOf(url),
+    maxConnections: 1,
+    rowLevelSecurity: "off",
+  });
   try {
     await acquireSessionAdvisoryLock(admin.db, templateDbName);
     // skip: another worker of this run already built it while we waited on the lock
@@ -146,8 +225,18 @@ export async function buildTestDbTemplate(
     // Built under a side name and renamed once complete, so a clone never sees a half-built schema.
     const buildDbName = `${templateDbName}_build`;
     await dropDatabaseIfExists(admin.db, buildDbName);
-    await createDatabase(admin.db, buildDbName);
-    const conn = createDbConnection({ url: databaseUrlOf(url, buildDbName), maxConnections: 1 });
+    if (applicationRole) await ensureApplicationRole(admin.db, url);
+    await createDatabase(
+      admin.db,
+      buildDbName,
+      undefined,
+      applicationRole ? TEST_APPLICATION_ROLE : undefined,
+    );
+    const conn = createDbConnection(
+      applicationRole
+        ? { url: applicationRoleUrlOf(url, buildDbName), maxConnections: 1, rowLevelSecurity: "on" }
+        : { url: databaseUrlOf(url, buildDbName), maxConnections: 1, rowLevelSecurity: "off" },
+    );
     try {
       await buildSchema(conn.db);
     } finally {
@@ -160,7 +249,11 @@ export async function buildTestDbTemplate(
 }
 
 export async function dropTestDbTemplates(baseUrl: string, runId: string): Promise<void> {
-  const admin = createDbConnection({ url: adminUrlOf(baseUrl), maxConnections: 1 });
+  const admin = createDbConnection({
+    url: adminUrlOf(baseUrl),
+    maxConnections: 1,
+    rowLevelSecurity: "off",
+  });
   try {
     for (const name of await listDatabaseNamesWithPrefix(admin.db, testDbTemplatePrefix(runId))) {
       await dropDatabaseIfExists(admin.db, name);

package/src/stack/index.ts

@@ -15,9 +15,11 @@ export {
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/internal/stack-support";
 export {
+  applicationRoleUrlOf,
   type CreateTestDbOptions,
   createTestDb,
   DEFAULT_TEST_DB_POOL_MAX,
+  TEST_APPLICATION_ROLE,
   type TestDb,
 } from "./db.ts";
 export { drainEventConsumers } from "./drain-event-consumers.ts";

package/src/stack/push-entity-projection-tables.ts

@@ -11,7 +11,12 @@ import {
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/internal/stack-support";
 
-type DbHolder = { readonly db: DbConnection };
+// DDL must not run through the system-scoped `db` of a stack: each scoped statement is its own transaction, which CREATE INDEX CONCURRENTLY rejects.
+type DbHolder = { readonly db: DbConnection; readonly unscopedDb?: DbConnection };
+
+function ddlDbOf(stack: DbHolder): DbConnection {
+  return stack.unscopedDb ?? stack.db;
+}
 
 // biome-ignore lint/suspicious/noConsole: stack-internal status logging
 const logInfo = (msg: string): void => console.log(msg);
@@ -45,7 +50,7 @@ export async function pushEntityProjectionTables(
     if (seen.has(proj.table)) continue;
     seen.add(proj.table);
     const physical = schemaTableName(proj.table) ?? tableToMeta(proj.table).tableName;
-    if (!(await tableExists(stack.db, `public.${physical}`))) {
+    if (!(await tableExists(ddlDbOf(stack), `public.${physical}`))) {
       missing[projName] = proj.table;
       continue;
     }
@@ -53,7 +58,7 @@ export async function pushEntityProjectionTables(
   }
 
   if (Object.keys(missing).length > 0) {
-    await unsafePushTables(stack.db, missing);
+    await unsafePushTables(ddlDbOf(stack), missing);
   }
 }
 
@@ -70,11 +75,11 @@ async function syncExistingProjectionTable(
   table: unknown,
 ): Promise<void> {
   const meta = tableToMeta(table);
-  const liveColumns = await columnNamesOf(stack.db, physical);
+  const liveColumns = await columnNamesOf(ddlDbOf(stack), physical);
   const missingColumns = meta.columns.filter((c) => !liveColumns.has(c.name));
   if (missingColumns.length === 0) {
     logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
-    await addMissingIndexes(stack.db, physical, meta.indexes);
+    await addMissingIndexes(ddlDbOf(stack), physical, meta.indexes);
     // skip: table is already in sync, only indexes needed backfilling
     return;
   }
@@ -97,6 +102,6 @@ async function syncExistingProjectionTable(
     `[kumiko-stack] table ${physical} is missing column(s) ` +
       `${missingColumns.map((c) => `"${c.name}"`).join(", ")} — adding`,
   );
-  await addMissingColumns(stack.db, physical, missingColumns);
-  await addMissingIndexes(stack.db, physical, meta.indexes);
+  await addMissingColumns(ddlDbOf(stack), physical, missingColumns);
+  await addMissingIndexes(ddlDbOf(stack), physical, meta.indexes);
 }