@cosmicdrift/kumiko-testing 0.388.0 → 0.389.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.388.0",
+  "version": "0.389.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -34,6 +34,10 @@
       "types": "./src/helpers/index.ts",
       "default": "./src/helpers/index.ts"
     },
+    "./helpers/mock-module": {
+      "types": "./src/helpers/mock-module.ts",
+      "default": "./src/helpers/mock-module.ts"
+    },
     "./helpers/real-providers": {
       "types": "./src/helpers/real-providers.ts",
       "default": "./src/helpers/real-providers.ts"
@@ -99,9 +103,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.388.0",
-    "@cosmicdrift/kumiko-guards": "0.388.0",
-    "@cosmicdrift/kumiko-types": "0.388.0",
+    "@cosmicdrift/kumiko-framework": "0.389.0",
+    "@cosmicdrift/kumiko-guards": "0.389.0",
+    "@cosmicdrift/kumiko-types": "0.389.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -125,8 +129,8 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.388.0",
-    "@cosmicdrift/kumiko-dev-server": "0.388.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.389.0",
+    "@cosmicdrift/kumiko-dev-server": "0.389.0",
     "@happy-dom/global-registrator": "^20.11.2",
     "@playwright/test": "^1.62.1",
     "@testing-library/dom": "^10.4.1",

package/src/changes.json

@@ -1,4 +1,42 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "captureClosedConnectionError returns a Bun.SQL error",
+    "detail": "The helper opens Bun.SQL pools, so the captured error has the code ERR_POSTGRES_CONNECTION_CLOSED instead of the postgres-js CONNECTION_CLOSED. The client of createTestDb is the connection handle's listenClient, the same Bun.SQL pool as before.",
+    "migration": "Tests that compared the captured error's code with CONNECTION_CLOSED compare with ERR_POSTGRES_CONNECTION_CLOSED or call isClosedConnectionError. Manual migration, there is no codemod."
+  },
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "e2e tests fail after more than 8 app boots; the per-test client IP no longer disables the HTTP cache",
+    "detail": "The test fixture sent the per-test X-Forwarded-For through context.route, which turns Chromium's HTTP cache off for the whole context, so every page.goto re-downloaded all assets and GET /api/schema. It now uses setExtraHTTPHeaders and the cache stays on. The fixture also counts GET /api/schema per test and fails a passing test that boots the app more than 8 times (default of the new maxAppBootsPerTest fixture option), and closes pages left open (window.open tabs) before the context closes.",
+    "migration": "Seed through tenant.api, tenant.seed and tenant.addUser instead of calling page.goto(APP_BASE_PATH) before every seed; each page.goto reloads the app. runMatrix and runScreenshots boot the app once per test themselves, so they need no change; only your own scenario flows or specs that navigate on purpose raise the budget with test.use({ maxAppBootsPerTest: <n> }). Manual migration, there is no codemod. The X-Forwarded-For header is now sent on every request of the context, including cross-origin ones."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "loginViaUi no longer races the MFA auto-submit",
+    "detail": "The MFA code field submits itself on the sixth digit since 0.388. loginViaUi now fills the code while waiting for the verify response and no longer presses Enter on a field that may already be disabled."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "consoleCallsFromNamespace test helper for silent-log assertions",
+    "detail": "Filters a console spy by logger namespace prefix, so a new or reworded warning from the module under test fails a silent test. The boot-validator, client-ip and settings-hub silent tests use it."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "mockModuleForFile restores module mocks automatically",
+    "detail": "bun's mock.module is process-global, so tests had to copy the real module and restore it by hand in afterAll. The helper does both and can point re-exporting modules back at the real export."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "E2E specs can present stable identities around their own screenshots",
+    "detail": "withPresentedIdentities replaces generated identities in page text and form values, runs the callback and restores the originals in a finally block. The lower-level present and restore functions are exported too."
+  },
   {
     "version": "0.388.0",
     "type": "improvement",

package/src/e2e/app-boot-budget.ts

@@ -0,0 +1,22 @@
+import type { BrowserContext } from "@playwright/test";
+
+// Duplicated from kumiko-renderer (APP_SCHEMA_API_PATH): kumiko-testing does not depend on the renderer.
+export const APP_SCHEMA_API_PATH = "/api/schema";
+
+export const DEFAULT_MAX_APP_BOOTS_PER_TEST = 8;
+
+// Every app boot fetches the schema once, so the request count is the number of page loads.
+export function observeAppBoots(context: Pick<BrowserContext, "on">): {
+  readonly count: () => number;
+} {
+  let bootCount = 0;
+  context.on("request", (request) => {
+    if (new URL(request.url()).pathname === APP_SCHEMA_API_PATH) bootCount += 1;
+  });
+  return { count: () => bootCount };
+}
+
+export function appBootBudgetViolation(bootCount: number, maxBoots: number): string | undefined {
+  if (bootCount <= maxBoots) return undefined;
+  return `This test booted the app ${bootCount} times (GET ${APP_SCHEMA_API_PATH}), budget is ${maxBoots}. Seed through tenant.api instead of page.goto per seed; each page.goto reloads the app. Specs that navigate on purpose (screenshot scenarios) raise the budget with test.use({ maxAppBootsPerTest }).`;
+}

package/src/e2e/auth-kit.ts

@@ -273,8 +273,14 @@ export async function loginViaUi(page: Page, credentials: LoginCredentials): Pro
   // avoids racing the transition from the password form.
   const codeField = page.locator("#mfa-verify-code");
   await expect(codeField).toBeVisible();
-  await codeField.fill(await unburnedTotpCode(credentials.mfaTotpSecret));
-  await codeField.press("Enter");
+  const code = await unburnedTotpCode(credentials.mfaTotpSecret);
+  // The sixth digit submits on its own and disables the field; an Enter press would race that.
+  await Promise.all([
+    page.waitForResponse(
+      (response) => response.url().includes("/api/auth/mfa/verify") && response.ok(),
+    ),
+    codeField.fill(code),
+  ]);
   await expect(codeField).toHaveCount(0);
 }
 

package/src/e2e/index.ts

@@ -51,6 +51,12 @@ export {
 } from "./mail-links";
 export { pinEnglishLocale } from "./pin-english-locale";
 export { pollForRow, waitForProjection } from "./poll";
+export {
+  type PresentIdentity,
+  presentIdentitiesOnPage,
+  restoreIdentitiesOnPage,
+  withPresentedIdentities,
+} from "./present-identities";
 export {
   requireScreenshotDir,
   SCREENSHOT_DIR_ENV,
@@ -66,7 +72,6 @@ export {
   type FlatOptions,
   findIdenticalThemeScreenshots,
   type MatrixOptions,
-  type PresentIdentity,
   runMatrix,
   runScreenshots,
   type Scenario,

package/src/e2e/present-identities.ts

@@ -0,0 +1,90 @@
+import type { Page } from "@playwright/test";
+
+// Seeded identities are unique per run (admin-<tenantId>@…), so a screenshot
+// would show a different address every time. Replaced in the page's text and
+// form values right before each capture; the seeded data stays untouched.
+export interface PresentIdentity {
+  readonly from: string;
+  readonly to: string;
+}
+
+export function assertPresentableMappings(mappings: readonly PresentIdentity[]): void {
+  for (const { from } of mappings) {
+    if (from === "") throw new Error("presentIdentities: `from` must not be empty");
+  }
+}
+
+declare global {
+  interface Window {
+    __kumikoPresentRestore?: Array<() => void>;
+  }
+}
+
+// Runs in the browser, so it may not reference module scope. Originals are kept
+// on window so a later evaluate can put them back (captureScreenshot runs
+// mid-flow, where the spec keeps asserting and submitting forms).
+function replaceIdentitiesInDocument(mappings: readonly PresentIdentity[]): void {
+  window.__kumikoPresentRestore ??= [];
+  const restorers = window.__kumikoPresentRestore;
+  const present = (text: string): string =>
+    mappings.reduce((current, { from, to }) => current.replaceAll(from, to), text);
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+    const text = node.nodeValue ?? "";
+    const presented = present(text);
+    if (presented !== text) {
+      const textNode = node;
+      textNode.nodeValue = presented;
+      restorers.push(() => {
+        textNode.nodeValue = text;
+      });
+    }
+  }
+  for (const field of document.querySelectorAll("input, textarea")) {
+    if (field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement) {
+      const original = field.value;
+      const presented = present(original);
+      if (presented !== original) {
+        field.value = presented;
+        restorers.push(() => {
+          field.value = original;
+        });
+      }
+    }
+  }
+}
+
+// Reverse order: a second presentation pass records already-presented values.
+function restoreIdentitiesInDocument(): void {
+  const restorers = window.__kumikoPresentRestore ?? [];
+  for (const restore of restorers.reverse()) restore();
+  window.__kumikoPresentRestore = [];
+}
+
+export async function presentIdentitiesOnPage(
+  page: Page,
+  mappings: readonly PresentIdentity[],
+): Promise<void> {
+  if (mappings.length > 0) await page.evaluate(replaceIdentitiesInDocument, mappings);
+}
+
+export async function restoreIdentitiesOnPage(
+  page: Page,
+  mappings: readonly PresentIdentity[],
+): Promise<void> {
+  if (mappings.length > 0) await page.evaluate(restoreIdentitiesInDocument);
+}
+
+export async function withPresentedIdentities<T>(
+  page: Page,
+  mappings: readonly PresentIdentity[],
+  fn: () => Promise<T>,
+): Promise<T> {
+  assertPresentableMappings(mappings);
+  await presentIdentitiesOnPage(page, mappings);
+  try {
+    return await fn();
+  } finally {
+    await restoreIdentitiesOnPage(page, mappings);
+  }
+}

package/src/e2e/screenshots.ts

@@ -6,6 +6,12 @@ import { E2E_TIMEOUT_MS } from "../e2e-timeouts";
 import { isRealProviderRun } from "../helpers/real-providers.ts";
 import { DESKTOP_VIEWPORT } from "./constants";
 import { pinEnglishLocale } from "./pin-english-locale";
+import {
+  assertPresentableMappings,
+  type PresentIdentity,
+  presentIdentitiesOnPage,
+  restoreIdentitiesOnPage,
+} from "./present-identities";
 import { requireScreenshotDir, SCREENSHOT_DIR_ENV } from "./screenshot-dir";
 import { type SeedTenantFixture, test } from "./seeded-tenant-fixture";
 
@@ -33,14 +39,6 @@ export async function applyDefaultTheme(page: Page, theme: DefaultThemeId): Prom
   }, theme);
 }
 
-// Seeded identities are unique per run (admin-<tenantId>@…), so a screenshot
-// would show a different address every time. Replaced in the page's text and
-// form values right before each capture; the seeded data stays untouched.
-export interface PresentIdentity {
-  readonly from: string;
-  readonly to: string;
-}
-
 export interface ScenarioFixtures {
   readonly seedTenant: SeedTenantFixture;
   // runMatrix's current locale, for apps whose routes carry the locale in the
@@ -165,73 +163,6 @@ async function waitForSettledPage(page: Page, inFlightDataRequests: () => number
     .toBeGreaterThanOrEqual(STABLE_POLLS);
 }
 
-function assertPresentableMappings(mappings: readonly PresentIdentity[]): void {
-  for (const { from } of mappings) {
-    if (from === "") throw new Error("presentIdentities: `from` must not be empty");
-  }
-}
-
-declare global {
-  interface Window {
-    __kumikoPresentRestore?: Array<() => void>;
-  }
-}
-
-// Runs in the browser, so it may not reference module scope. Originals are kept
-// on window so a later evaluate can put them back (captureScreenshot runs
-// mid-flow, where the spec keeps asserting and submitting forms).
-function replaceIdentitiesInDocument(mappings: readonly PresentIdentity[]): void {
-  window.__kumikoPresentRestore ??= [];
-  const restorers = window.__kumikoPresentRestore;
-  const present = (text: string): string =>
-    mappings.reduce((current, { from, to }) => current.replaceAll(from, to), text);
-  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
-  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
-    const text = node.nodeValue ?? "";
-    const presented = present(text);
-    if (presented !== text) {
-      const textNode = node;
-      textNode.nodeValue = presented;
-      restorers.push(() => {
-        textNode.nodeValue = text;
-      });
-    }
-  }
-  for (const field of document.querySelectorAll("input, textarea")) {
-    if (field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement) {
-      const original = field.value;
-      const presented = present(original);
-      if (presented !== original) {
-        field.value = presented;
-        restorers.push(() => {
-          field.value = original;
-        });
-      }
-    }
-  }
-}
-
-// Reverse order: a second presentation pass records already-presented values.
-function restoreIdentitiesInDocument(): void {
-  const restorers = window.__kumikoPresentRestore ?? [];
-  for (const restore of restorers.reverse()) restore();
-  window.__kumikoPresentRestore = [];
-}
-
-async function presentIdentitiesOnPage(
-  page: Page,
-  mappings: readonly PresentIdentity[],
-): Promise<void> {
-  if (mappings.length > 0) await page.evaluate(replaceIdentitiesInDocument, mappings);
-}
-
-async function restoreIdentitiesOnPage(
-  page: Page,
-  mappings: readonly PresentIdentity[],
-): Promise<void> {
-  if (mappings.length > 0) await page.evaluate(restoreIdentitiesInDocument);
-}
-
 // Order matters: beforeCapture first (it may hide/mask), identities after, so
 // the replaced text is what the screenshot sees. Exported for unit tests.
 export async function captureScenario(

package/src/e2e/seed-route.ts

@@ -107,6 +107,12 @@ function assertSeededTenant(tenantId: string, seededTenantIds: ReadonlySet<strin
 export type E2eSeederContext = {
   readonly write: (handlerQn: string, payload: unknown) => Promise<unknown>;
   readonly query: (handlerQn: string, payload: unknown) => Promise<unknown>;
+  // System user with "system" plus exactly these roles, no SystemAdmin.
+  readonly writeAs: (
+    roles: readonly string[],
+    handlerQn: string,
+    payload: unknown,
+  ) => Promise<unknown>;
 };
 
 // `body` is whatever the client sent; validate it with a zod schema's parse(),
@@ -311,6 +317,11 @@ export function createE2eSeedRoutesWith(
             handlerQn,
             await deps.dispatchSystemWrite({ handlerQn, payload, tenantId }),
           ),
+        writeAs: async (roles, handlerQn, payload) =>
+          unwrapWriteData(
+            handlerQn,
+            await deps.dispatchWriteAs({ handlerQn, payload, tenantId, roles }),
+          ),
         query: (handlerQn, payload) => deps.dispatchSystemQuery({ handlerQn, payload, tenantId }),
       };
       try {

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/index.ts

@@ -23,7 +23,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,

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/stack/db.ts

@@ -99,7 +99,7 @@ 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();

package/src/stack/test-stack-setup.ts

@@ -31,6 +31,7 @@ import {
 import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { createInMemorySearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import type { Clock } from "@cosmicdrift/kumiko-types/tz-context";
 import {
   createTestDb,
   ensureTestDbTemplate,
@@ -248,14 +249,26 @@ export function createStackCacheSync(
 // A static `files.storageProvider` is wired as the per-tenant resolver — the
 // framework test seam that doesn't require mounting config + file-foundation.
 // (Bundled GDPR tests mount the real provider features instead.)
+function isClock(value: unknown): value is Clock {
+  return (
+    typeof value === "object" && value !== null && "now" in value && typeof value.now === "function"
+  );
+}
+
 async function resolveStackFileProvider(
   options: TestStackOptions,
   testDb: StackStorage["testDb"],
+  readClock: () => unknown,
 ): Promise<import("@cosmicdrift/kumiko-framework/files").FileProviderResolver | undefined> {
   if (!options.files) return undefined;
   const provider = options.files.storageProvider;
   const { withUploadLedger } = await import("@cosmicdrift/kumiko-framework/files");
-  return withUploadLedger(() => Promise.resolve(provider), testDb.db);
+  // Read per call: the clock arrives via extraContext, which is merged after this resolver is built.
+  const now = (): Temporal.Instant => {
+    const clock = readClock();
+    return isClock(clock) ? clock.now() : Temporal.Now.instant();
+  };
+  return withUploadLedger(() => Promise.resolve(provider), testDb.db, now);
 }
 
 export async function buildStackServices(
@@ -277,7 +290,12 @@ export async function buildStackServices(
   );
 
   const entityCache = createEntityCache(testRedis.redis, { ttlSeconds: 60 });
-  const fileProviderResolver = await resolveStackFileProvider(options, testDb);
+  const extraContextClock: { current: unknown } = { current: undefined };
+  const fileProviderResolver = await resolveStackFileProvider(
+    options,
+    testDb,
+    () => extraContextClock.current,
+  );
   const observability = options.observability ?? createNoopProvider();
 
   // Same AppContext buildServer() gets below (db/redis/searchAdapter/
@@ -292,6 +310,10 @@ export async function buildStackServices(
   // index.ts). Putting it here would reintroduce the exact test-vs-prod
   // drift fixed: a job/handler reading `ctx.effectiveFeatures` would pass in
   // tests and break in prod.
+  const extraContext =
+    typeof options.extraContext === "function"
+      ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
+      : options.extraContext;
   const appContext = {
     db: testDb.db,
     redis: testRedis.redis,
@@ -301,10 +323,9 @@ export async function buildStackServices(
     ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
     ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
     ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
-    ...(typeof options.extraContext === "function"
-      ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
-      : options.extraContext),
+    ...extraContext,
   };
+  extraContextClock.current = extraContext?.["clock"];
   return { searchAdapter, events, registry, sseBroker, entityCache, observability, appContext };
 }