@cosmicdrift/kumiko-testing 0.385.0 → 0.387.0

package/LICENSE

@@ -1,57 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Marc Frost
-
-Licensed Work:        @cosmicdrift/kumiko-testing
-                      The Licensed Work is © 2026 Marc Frost.
-
-Additional Use Grant: 
-You may use the Licensed Work in production for any purpose, including 
-commercially, EXCEPT for the Restricted Use. 
-
-"Restricted Use" is defined as using the Licensed Work to provide a platform 
-or service to third parties that allows them to host, deploy, or run their 
-own applications built with the Licensed Work. This includes, but is not 
-limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
-platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
-managed offering of the Licensed Work.
-
-This restriction does not apply to the Licensor, any entity controlled by, 
-controlling, or under common control with the Licensor ("Affiliates"), or 
-contractors acting on their behalf. The Licensor remains free to use the 
-Licensed Work for any purpose, including for the operation of kumiko.rocks.
-
-Change Date:          2030-05-05
-Change License:       Apache License, Version 2.0
-
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative works, 
-redistribute, and make non-production use of the Licensed Work. The Licensor may 
-make an Additional Use Grant, above, permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly 
-available distribution of the Licensed Work under this License, whichever comes 
-first, this License will convert to the Change License.
-
-This Business Source License governs use of the Licensed Work in all cases, except 
-as to any use that is explicitly granted in the Additional Use Grant above or 
-under the Change License after the Change Date.
-
-If your use of the Licensed Work does not comply with the requirements of this 
-License, you must cease use of the Licensed Work immediately.
-
-All copies of the Licensed Work, and all derivative works thereof, must include 
-this License.
-
-This License does not grant you any right, title, or interest in any trademark, 
-logo, or branding of the Licensor, except as required to comply with this License.
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
-“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
-WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
-TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
-ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.
+MIT License
+
+Copyright (c) 2026 Marc Frost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/kumiko-testing.ts

@@ -8,6 +8,7 @@ import {
   buildIntegrationTestArgs,
   listIntegrationTestFiles,
   resolveRequestedIntegrationFiles,
+  runWithTestDbTemplates,
   selectIntegrationFiles,
 } from "../src/integration-runner";
 
@@ -99,8 +100,15 @@ async function runIntegration(args: readonly string[]): Promise<number> {
     ...(values.timings !== undefined && { timings: values.timings }),
     ...(values["update-timings"] === true && { updateTimings: true }),
   });
-  const proc = Bun.spawn(["bun", ...testArgs], { stdio: ["inherit", "inherit", "inherit"] });
-  return proc.exited;
+  return runWithTestDbTemplates(
+    // Bun.spawn defaults to the env from process start; pass the live one so the
+    // template run id set by runWithTestDbTemplates reaches the test process.
+    () =>
+      Bun.spawn(["bun", ...testArgs], {
+        stdio: ["inherit", "inherit", "inherit"],
+        env: process.env,
+      }).exited,
+  );
 }
 
 const [command, ...rest] = process.argv.slice(2);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.385.0",
+  "version": "0.387.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
-  "license": "BUSL-1.1",
+  "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
     "type": "git",
@@ -99,9 +99,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.385.0",
-    "@cosmicdrift/kumiko-guards": "0.385.0",
-    "@cosmicdrift/kumiko-types": "0.385.0",
+    "@cosmicdrift/kumiko-framework": "0.387.0",
+    "@cosmicdrift/kumiko-guards": "0.387.0",
+    "@cosmicdrift/kumiko-types": "0.387.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -125,8 +125,8 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.385.0",
-    "@cosmicdrift/kumiko-dev-server": "0.385.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.387.0",
+    "@cosmicdrift/kumiko-dev-server": "0.387.0",
     "@happy-dom/global-registrator": "^20.11.2",
     "@playwright/test": "^1.62.1",
     "@testing-library/dom": "^10.4.1",

package/src/bunfig.ts

@@ -102,7 +102,7 @@ type BunfigBlock = { readonly header: string; readonly lines: readonly string[]
 // contain "[" are never alone on their own line. Anything before the first
 // header (top-level keys like `preload`/`telemetry`/`smol`/`logLevel`, plus
 // the header comments) is its own block under the synthetic header "" —
-// dropping it silently lost those keys (kumiko-framework#3120).
+// dropping it silently lost those keys.
 function splitBunfigBlocks(content: string): readonly BunfigBlock[] {
   const blocks: { header: string; lines: string[] }[] = [];
   let current: { header: string; lines: string[] } = { header: "", lines: [] };
@@ -224,7 +224,7 @@ function appendArrayExtras(
  * verbatim, appended after the generated content — so a section the
  * template doesn't own this run is never silently dropped. A key inside a
  * section the template DOES emit that isn't in this run's own version of
- * that section (e.g. `concurrency`, `timeout`, kumiko-framework#3120) fails
+ * that section (e.g. `concurrency`, `timeout`) fails
  * the merge instead of silently disappearing. Within an array key the
  * template does emit on both sides (`preload`, `pathIgnorePatterns`,
  * `coveragePathIgnorePatterns`), entries the app appended on top of the

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.386.0",
+    "type": "fix",
+    "title": "Integration test stacks clone a migrated template database",
+    "detail": "kumiko-testing integration and the framework integration runner set a run id; setupTestStack then builds one template per schema fingerprint under an advisory lock and clones it, and the runner drops the templates at the end. Plain bun test runs keep the in-place DDL path. setupAppTestStack skips pushEntityProjectionTables on fresh databases."
+  },
+  {
+    "version": "0.386.0",
+    "type": "fix",
+    "title": "createTestRedis waits for a ready connection",
+    "detail": "The test Redis client connected in the background, so the first rate-limit check in a test file could see status \"connect\" and fail with \"rate-limit redis connection not ready\". createTestRedis now connects explicitly and returns after the connection is ready."
+  },
   {
     "version": "0.385.0",
     "type": "fix",

package/src/e2e/screenshots.ts

@@ -324,7 +324,7 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
     // Browser-context locale for JS-side Intl/navigator.language (e.g. money-input's
     // resolvedLocale) — pinEnglishLocale() only seeds the app's own kumiko:locale.
     // ponytail: native <input type="number"> still formats per the host OS region,
-    // unreachable from Playwright (context.locale and --lang both no-op there). #1851
+    // unreachable from Playwright (context.locale and --lang both no-op there).
     if (opts.pinLocale) test.use({ locale: "en-US" });
     for (const s of scenarios) {
       test(
@@ -556,7 +556,7 @@ export function runMatrix<T extends string>(
     test.describe(locale, () => {
       // Browser-context locale for JS-side Intl/navigator.language — the
       // kumiko:locale seed below only drives the app's own i18n strings.
-      // ponytail: see the runScreenshots() locale comment above / #1851
+      // ponytail: see the runScreenshots() locale comment above.
       const tag = resolveLocaleTag(locale, opts.localeTags);
       test.use({ locale: tag });
 

package/src/e2e/seed-route.ts

@@ -51,7 +51,7 @@ function parseJsonBody<S extends z.ZodType>(schema: S, raw: string): ParsedBody<
 }
 
 // Shared by every verify() below — a failed parse becomes a 400 the same way
-// the pre-#3050 handler-level parseJsonBody/parseWith checks did.
+// the handler-level parseJsonBody/parseWith checks did.
 function parseOrReject<T>(value: ParsedBody<T>): T {
   if (value.success) return value.data;
   throw new ExtraRouteRejection(400, { error: value.error });
@@ -153,9 +153,9 @@ function toCapturedMail(message: InboxMessage): CapturedMail {
 // still throw in every environment) — the *mounting* decision is the
 // caller's: use isE2eSeedingEnabled() to keep prod from ever registering
 // these route objects at all, e.g. `...(isE2eSeedingEnabled() ?
-// createE2eSeedRoutes() : [])` in a server entry that also runs in prod
-// (kumiko-framework#3120). Each route's own assertGateOpen() 404s outside
-// the seed condition regardless — this is belt-and-suspenders, not the only gate.
+// createE2eSeedRoutes() : [])` in a server entry that also runs in prod.
+// Each route's own assertGateOpen() 404s outside the seed condition regardless
+// — this is belt-and-suspenders, not the only gate.
 export function createE2eSeedRoutes(
   options: E2eSeedRoutesOptions,
   bundled: SeedRouteBundledApi,

package/src/helpers/boot-validator-fixture.ts

@@ -68,7 +68,7 @@ function ensureEntityListRowNavigation(
       // No `params` here: this same-entity target always resolves to
       // UPDATE mode (the renderer auto-fills entityId from row["id"]),
       // and entityEdit-update never reads search-params as initial
-      // values — the boot-validator now rejects that combination (#1680).
+      // values — the boot-validator now rejects that combination.
       {
         kind: "navigate",
         id: "edit",

package/src/helpers/e2e-generator.ts

@@ -309,7 +309,7 @@ function buildEditFillOps(
           ops.push({ kind: "fill", field, value: String(v) });
           break;
         // embedded/money/timestamp/locatedTimestamp/file/image/files/images:
-        // no generic interaction. Since #369 timestamp renders two inputs
+        // no generic interaction. Since timestamp renders two inputs
         // (date + time) that a single .fill() cannot drive; the test author
         // supplies a hand override or skips it.
         default:
@@ -489,7 +489,7 @@ function fieldToFixture(name: string, field: FieldDefinition): unknown {
     case "images":
       // File-upload fixtures are not generic yet: Playwright would have to supply
       // file contents, and the write API already expects uploaded fileRef UUIDs.
-      // Can be added once a sample settles the paths (M4).
+      // Can be added once a sample settles the paths.
       return undefined;
     default:
       return undefined;

package/src/helpers/index.ts

@@ -4,9 +4,9 @@
 
 // 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 as of #1631. A production call to resetPiiSubjectKmsForTests() silently
-// switches the PII layer off, and subject-annotated fields are written in
-// plaintext from then on: no error, no log.
+// and /db. A production call to resetPiiSubjectKmsForTests() silently switches
+// the PII layer off, and subject-annotated fields are written in plaintext from
+// then on: no error, no log.
 export {
   resetBlindIndexKeyForTests,
   resetEntityFieldEncryptionCacheForTests,

package/src/helpers/without-ambient-temporal.ts

@@ -1,6 +1,6 @@
 /**
  * Run `fn` with `globalThis.Temporal` deleted, then restore.
- * Used by ambient-independence regression tests (kumiko-framework#1525/#1550).
+ * Used by ambient-independence regression tests.
  */
 export async function withoutAmbientTemporal<T>(fn: () => T | Promise<T>): Promise<T> {
   const savedGlobal: unknown = Reflect.get(globalThis, "Temporal");

package/src/integration-runner.ts

@@ -1,6 +1,9 @@
+import { randomBytes } from "node:crypto";
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { BUNFIG_FILES, TEST_TIMEOUT_MS } from "./bunfig";
+import { withEnv } from "./helpers/with-env";
+import { SERVICE_ENV_DEFAULTS } from "./preload/service-env-defaults-values";
 
 export type IntegrationRunOptions = {
   readonly files: readonly string[];
@@ -85,3 +88,21 @@ export function buildIntegrationTestArgs(opts: IntegrationRunOptions): string[]
     ...opts.files,
   ];
 }
+
+// Test stacks of this run clone migrated template databases instead of repeating
+// the DDL per stack; the templates live exactly as long as the run.
+export async function runWithTestDbTemplates(run: () => Promise<number>): Promise<number> {
+  const { TEST_DB_TEMPLATE_RUN_ENV, dropTestDbTemplates } = await import("./stack/db.ts");
+  const runId = randomBytes(4).toString("hex");
+  try {
+    return await withEnv({ [TEST_DB_TEMPLATE_RUN_ENV]: runId }, run);
+  } finally {
+    const baseUrl = process.env["TEST_DATABASE_URL"] ?? SERVICE_ENV_DEFAULTS.TEST_DATABASE_URL;
+    try {
+      await dropTestDbTemplates(baseUrl, runId);
+    } catch (error) {
+      // biome-ignore lint/suspicious/noConsole: runner output is the interface
+      console.warn(`kumiko-testing: could not drop the test DB templates of run ${runId}:`, error);
+    }
+  }
+}

package/src/seed-types.ts

@@ -28,7 +28,7 @@ export type SeededUser = SeededCredentials & {
 export type SeedPart = (ctx: { readonly tenant: SeededTenant }) => Promise<void>;
 
 // email may contain the literal "{tenantId}" placeholder, substituted with the
-// seeded tenant's id — user:create's email uniqueness is global (fw#2134/#2593),
+// seeded tenant's id — user:create's email uniqueness is global,
 // so a fixed literal email collides across per-scenario tenants.
 export type SeedAdminIdentity = {
   readonly displayName?: string;

package/src/stack/db.ts

@@ -3,10 +3,13 @@
 
 import { DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX } from "@cosmicdrift/kumiko-framework/db";
 import {
+  acquireSessionAdvisoryLock,
   createDatabase,
   createDbConnection,
   databaseExists,
   dropDatabaseIfExists,
+  listDatabaseNamesWithPrefix,
+  renameDatabase,
 } from "@cosmicdrift/kumiko-framework/internal/stack-support";
 import { ensureTemporalPolyfill } from "@cosmicdrift/kumiko-framework/time";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
@@ -39,14 +42,32 @@ export type CreateTestDbOptions = {
   readonly persistent?: boolean;
   readonly poolMax?: number;
   readonly outsideTransactionPoolMax?: number;
+  /** Clone this already-migrated database instead of starting empty. */
+  readonly templateDbName?: string;
 };
 
+// Set by the integration runner for one run; templates named after it are dropped when the run ends.
+export const TEST_DB_TEMPLATE_RUN_ENV = "KUMIKO_TEST_DB_TEMPLATE_RUN";
+
+// Inside the kumiko_test_ namespace, so clean-test-dbs also sweeps templates of killed runs.
+export function testDbTemplatePrefix(runId: string): string {
+  return `kumiko_test_tpl_${runId}_`;
+}
+
+function adminUrlOf(url: string): string {
+  return url.replace(/\/[^/]+$/, "/postgres");
+}
+
+function databaseUrlOf(url: string, dbName: string): string {
+  return url.replace(/\/[^/]+$/, `/${dbName}`);
+}
+
 export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<TestDb> {
   await ensureTemporalPolyfill();
   const opts: CreateTestDbOptions = typeof arg === "string" ? { baseUrl: arg } : (arg ?? {});
   const url = opts.baseUrl ?? requireEnv("TEST_DATABASE_URL");
   const dbName = opts.dbName ?? `kumiko_test_${generateId().slice(-8)}`;
-  const adminUrl = url.replace(/\/[^/]+$/, "/postgres");
+  const adminUrl = adminUrlOf(url);
 
   const admin = createDbConnection({ url: adminUrl, maxConnections: 1 });
   try {
@@ -55,13 +76,13 @@ export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<
         await createDatabase(admin.db, dbName);
       }
     } else {
-      await createDatabase(admin.db, dbName);
+      await createDatabase(admin.db, dbName, opts.templateDbName);
     }
   } finally {
     await admin.close();
   }
 
-  const testUrl = url.replace(/\/[^/]+$/, `/${dbName}`);
+  const testUrl = databaseUrlOf(url, dbName);
   const poolMax = opts.poolMax ?? DEFAULT_TEST_DB_POOL_MAX;
   const conn = createDbConnection({ url: testUrl, maxConnections: poolMax });
   const outsideConn = createDbConnection({
@@ -69,8 +90,10 @@ export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<
     maxConnections: opts.outsideTransactionPoolMax ?? DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX,
   });
 
-  const { createEventsTable } = await import("@cosmicdrift/kumiko-framework/event-store");
-  await createEventsTable(conn.db);
+  if (opts.templateDbName === undefined) {
+    const { createEventsTable } = await import("@cosmicdrift/kumiko-framework/event-store");
+    await createEventsTable(conn.db);
+  }
 
   return {
     db: conn.db,
@@ -93,4 +116,58 @@ export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<
   };
 }
 
+const testDbTemplates = new Map<string, Promise<void>>();
+
+// One build per template and process; other workers of the run wait on the
+// advisory lock and reuse the finished database.
+export function ensureTestDbTemplate(
+  templateDbName: string,
+  buildSchema: (db: DbConnection) => Promise<void>,
+): Promise<void> {
+  const known = testDbTemplates.get(templateDbName);
+  if (known) return known;
+  const pending = buildTestDbTemplate(templateDbName, buildSchema);
+  testDbTemplates.set(templateDbName, pending);
+  pending.catch(() => testDbTemplates.delete(templateDbName));
+  return pending;
+}
+
+async function buildTestDbTemplate(
+  templateDbName: string,
+  buildSchema: (db: DbConnection) => Promise<void>,
+): Promise<void> {
+  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 });
+  try {
+    await acquireSessionAdvisoryLock(admin.db, templateDbName);
+    // skip: another worker of this run already built it while we waited on the lock
+    if (await databaseExists(admin.db, templateDbName)) return;
+    // 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 });
+    try {
+      await buildSchema(conn.db);
+    } finally {
+      await conn.close();
+    }
+    await renameDatabase(admin.db, buildDbName, templateDbName);
+  } finally {
+    await admin.close();
+  }
+}
+
+export async function dropTestDbTemplates(baseUrl: string, runId: string): Promise<void> {
+  const admin = createDbConnection({ url: adminUrlOf(baseUrl), maxConnections: 1 });
+  try {
+    for (const name of await listDatabaseNamesWithPrefix(admin.db, testDbTemplatePrefix(runId))) {
+      await dropDatabaseIfExists(admin.db, name);
+    }
+  } finally {
+    await admin.close();
+  }
+}
+
 export { requireEnv };

package/src/stack/redis.ts

@@ -7,9 +7,8 @@ export type TestRedis = {
   // The exact REDIS_URL used to build `redis` above — for a second, unrelated
   // connection (e.g. the test-stack's JobRunner) that needs its own client
   // rather than sharing this one's keyPrefix. Reconstructing a URL from
-  // `redis.options` loses password/username/tls/path (pr-review
-  // kumiko-framework #1036/2) — callers needing a fresh connection should use
-  // this raw string, not rebuild one from parsed options.
+  // `redis.options` loses password/username/tls/path — callers needing a fresh
+  // connection should use this raw string, not rebuild one from parsed options.
   redisUrl: string;
   /** The per-test `keyPrefix` on `redis`, e.g. `kt:1a2b3c4d:`. */
   keyPrefix: string;
@@ -39,7 +38,9 @@ export async function createTestRedis(opts: CreateTestRedisOptions = {}): Promis
   // round-robin). Collisions at birthday-paradox rates are gone — the
   // prefix space is unbounded. See Track B.3 in docs/plans/tests-refactor.
   const prefix = opts.borrowKeyPrefix ?? `kt:${generateId().slice(-8)}:`;
-  const redis = new Redis(redisUrl, { keyPrefix: prefix });
+  // Callers that check redis.status (rate-limit resolver) must not see "connect" on their first call.
+  const redis = new Redis(redisUrl, { keyPrefix: prefix, lazyConnect: true });
+  await redis.connect();
 
   async function deleteKeysMatching(pattern: string): Promise<void> {
     // Open a prefix-less client for the scan — ioredis' keyPrefix is applied

package/src/stack/request-helper.ts

@@ -109,7 +109,7 @@ export type RequestHelper = {
 export type RequestHelperOptions = {
   // When sessionChecker is wired (sessions feature), JWTs without jti are
   // rejected as no_sid. Seed/test helpers that only jwt.sign(user) need a
-  // live sid — create one via the same sessionCreator login uses (#1372).
+  // live sid — create one via the same sessionCreator login uses.
   readonly sessionCreator?: SessionCreator;
 };
 

package/src/stack/test-stack.ts

@@ -1,6 +1,8 @@
 // @runtime dev
+import { createHash } from "node:crypto";
 import type { AuthRoutesConfig, JwtHelper } from "@cosmicdrift/kumiko-framework/api";
 import { buildServer, createSseBroker, type SseBroker } from "@cosmicdrift/kumiko-framework/api";
+import type { DbConnection, EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { createRegistry, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
 import type {
   AppContext,
@@ -50,7 +52,12 @@ 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 { Hono } from "hono";
-import { createTestDb } from "./db.ts";
+import {
+  createTestDb,
+  ensureTestDbTemplate,
+  TEST_DB_TEMPLATE_RUN_ENV,
+  testDbTemplatePrefix,
+} from "./db.ts";
 import { createJobFailureTracker, drainJobs } from "./drain-jobs.ts";
 import { createEventCollector, type EventCollector } from "./event-collector.ts";
 import { createTestRedis, queueNamePrefixForTestRedis, type TestRedis } from "./redis.ts";
@@ -83,7 +90,7 @@ export type TestStack = {
   // The AppContext buildServer handed the request path, incl. the fields it
   // wires itself (_fileProviderResolver). A dev-server that starts its own
   // lane job-runners beside this stack must hand them THIS, not a
-  // `{ db, registry }` literal — that's the #1232 drift, and it makes an
+  // `{ db, registry }` literal — that's the drift, and it makes an
   // event-triggered job reaching for ctx.files die where the request path works.
   context: AppContext;
   // Present whenever a system consumer (SSE, Search) or
@@ -246,11 +253,11 @@ export type TestStackOptions = {
   /** Override the event dispatcher's polling-timer interval. Default 50ms.
    *  Tests that assert LISTEN/NOTIFY wake-up latency need this pushed far
    *  out (e.g. 60_000) so the polling timer can't land inside the
-   *  assertion window and mask a dead subscription — see E.4 (#2042). */
+   *  assertion window and mask a dead subscription. */
   eventDispatcherPollIntervalMs?: number;
   /** Opt out of auto-created r.entity() tables for callers that create/migrate
    *  them themselves. Default true — false pushes only projection/MSP/
-   *  storeTable sources, same as before fw#3102. */
+   *  storeTable sources, same as before. */
   entityTables?: boolean;
   /** Time source of the stack's rate-limit resolver, so tests can freeze the
    *  clock instead of racing the window. Default: system time. */
@@ -304,6 +311,87 @@ function bindMfaTokenSecrets(features: readonly FeatureDefinition[], jwtSecret:
   }
 }
 
+// Same table list as `kumiko schema generate` (collectTableMetas) — divergence
+// caused a production crash and left r.entity() tables missing.
+async function collectStackTableMetas(
+  options: TestStackOptions,
+): Promise<readonly EntityTableMeta[]> {
+  const { collectTableMetas, enumerateFeatureTableSources, extractTableInfo } = await import(
+    "@cosmicdrift/kumiko-framework/db"
+  );
+  const metas = collectTableMetas(options.features);
+  if (options.entityTables !== false) return metas;
+  const nonEntityNames = new Set(
+    options.features.flatMap((f) =>
+      enumerateFeatureTableSources(f).map((s) => extractTableInfo(s.table).name),
+    ),
+  );
+  return metas.filter((m) => nonEntityNames.has(m.tableName));
+}
+
+async function pushStackSchema(
+  db: DbConnection,
+  metas: readonly EntityTableMeta[],
+  withFileTables: boolean,
+): Promise<void> {
+  // Every ES-entity writes events via createEventStoreExecutor in the
+  // feature's write handlers. Auto-create the events table so every
+  // setupTestStack call is ready for writes without needing a manual
+  // createEventsTable().
+  await createEventsTable(db);
+  // Archive-stream metadata — needed by ctx.appendEvent's archive guard and
+  // loadAggregate's default-skip. Idempotent, so production boot running
+  // the same call is fine.
+  await createArchivedStreamsTable(db);
+
+  // Framework state for projection rebuild/status + event-consumer cursors.
+  // Idempotent — production boot flows run the same calls.
+  const { createProjectionStateTable, createEventConsumerStateTable } = await import(
+    "@cosmicdrift/kumiko-framework/pipeline"
+  );
+  await createProjectionStateTable(db);
+  await createEventConsumerStateTable(db);
+
+  // Files support: when a provider is registered, the fileRefs table must
+  // exist before the first upload. Skipped when no provider — the table
+  // stays off tenant test DBs that never touch files.
+  if (withFileTables) {
+    const { fileRefsTable, fileUploadLedgerTable } = await import(
+      "@cosmicdrift/kumiko-framework/files"
+    );
+    await unsafePushTables(db, { fileRefsTable, fileUploadLedgerTable });
+  }
+
+  const { tableExists } = await import("@cosmicdrift/kumiko-framework/db");
+  const missing: Record<string, unknown> = {};
+  for (const meta of metas) {
+    if (await tableExists(db, `public.${meta.tableName}`)) continue;
+    missing[meta.tableName] = meta;
+  }
+  if (Object.keys(missing).length > 0) {
+    await unsafePushTables(db, missing);
+  }
+}
+
+// Only inside an integration-runner run: the framework tables above are not part
+// of the fingerprint, which holds because one run never sees two framework versions.
+async function resolveTestDbTemplateName(
+  options: TestStackOptions,
+  metas: readonly EntityTableMeta[],
+  withFileTables: boolean,
+): Promise<string | undefined> {
+  const runId = process.env[TEST_DB_TEMPLATE_RUN_ENV];
+  if (runId === undefined || options.persistentDb === true || options.dbName !== undefined) {
+    return undefined;
+  }
+  const { renderTablesDdl } = await import("@cosmicdrift/kumiko-framework/db");
+  const fingerprint = createHash("sha256")
+    .update(JSON.stringify({ withFileTables, ddl: renderTablesDdl(metas) }))
+    .digest("hex")
+    .slice(0, 16);
+  return `${testDbTemplatePrefix(runId)}${fingerprint}`;
+}
+
 export async function setupTestStack(options: TestStackOptions): Promise<TestStack> {
   const jwtSecret = options.jwtSecret ?? DEFAULT_JWT_SECRET;
   const enabledHooks = options.systemHooks ?? ["sse", "search"];
@@ -313,9 +401,9 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
   await ensureTemporalPolyfill();
 
-  // Ownership boot-guards (fw#2639 unqualified where-fragments, fw#2626
-  // where-rules on the write path) otherwise run only in the prod boot via
-  // validateBoot, leaving every test stack blind to a broken access map.
+  // Ownership boot-guards (unqualified where-fragments, where-rules on the
+  // write path) otherwise run only in the prod boot via validateBoot, leaving
+  // every test stack blind to a broken access map.
   // Runs after the polyfill (buildEntityTable needs it to derive the probe
   // columns) and before the ephemeral DB/Redis exist, so a throw can't leak
   // a database that nothing will clean up.
@@ -325,6 +413,13 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   if (options.validateBoot === "full") validateBoot(options.features);
   bindMfaTokenSecrets(options.features, jwtSecret);
 
+  const stackTableMetas = await collectStackTableMetas(options);
+  const withFileTables = options.files !== undefined;
+  const buildStackSchema = (db: DbConnection): Promise<void> =>
+    pushStackSchema(db, stackTableMetas, withFileTables);
+  const templateDbName = await resolveTestDbTemplateName(options, stackTableMetas, withFileTables);
+  if (templateDbName !== undefined) await ensureTestDbTemplate(templateDbName, buildStackSchema);
+
   // Forward db-name/persistent-flag through to createTestDb. The
   // defaults (undefined dbName, persistent:false) keep the legacy
   // test contract: fresh kumiko_test_<random> DB per setup, dropped
@@ -337,6 +432,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       ...(options.outsideTransactionPoolMax !== undefined && {
         outsideTransactionPoolMax: options.outsideTransactionPoolMax,
       }),
+      ...(templateDbName !== undefined && { templateDbName }),
     }),
     createTestRedis(
       options.sharedRedisWith && { borrowKeyPrefix: options.sharedRedisWith.redis.keyPrefix },
@@ -347,70 +443,22 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   // DB/Redis — the caller never gets the stack object back to call
   // cleanup() itself (same "leaked ephemeral DB" failure class as the later
   // try/catch below, but for setup that runs before that try starts).
-  try {
-    // Every ES-entity writes events via createEventStoreExecutor in the
-    // feature's write handlers. Auto-create the events table so every
-    // setupTestStack call is ready for writes without needing a manual
-    // createEventsTable().
-    await createEventsTable(testDb.db);
-    // Archive-stream metadata — needed by ctx.appendEvent's archive guard and
-    // loadAggregate's default-skip. Idempotent, so production boot running
-    // the same call is fine.
-    await createArchivedStreamsTable(testDb.db);
-
-    // Framework state for projection rebuild/status + event-consumer cursors.
-    // Idempotent — production boot flows run the same calls.
-    const { createProjectionStateTable, createEventConsumerStateTable } = await import(
-      "@cosmicdrift/kumiko-framework/pipeline"
-    );
-    await createProjectionStateTable(testDb.db);
-    await createEventConsumerStateTable(testDb.db);
-
-    // Files support: when a provider is registered, the fileRefs table must
-    // exist before the first upload. Skipped when no provider — the table
-    // stays off tenant test DBs that never touch files.
-    if (options.files) {
-      const { fileRefsTable, fileUploadLedgerTable } = await import(
-        "@cosmicdrift/kumiko-framework/files"
-      );
-      await unsafePushTables(testDb.db, { fileRefsTable, fileUploadLedgerTable });
-    }
-
-    // Same table list as `kumiko schema generate` (collectTableMetas) — divergence
-    // was the #255 prod-crash and the #3102 missing r.entity() tables.
-    const { collectTableMetas } = await import("@cosmicdrift/kumiko-framework/db");
-    const { tableExists } = await import("@cosmicdrift/kumiko-framework/db");
-    let metas = collectTableMetas(options.features);
-    if (options.entityTables === false) {
-      const { enumerateFeatureTableSources } = await import("@cosmicdrift/kumiko-framework/db");
-      const { extractTableInfo } = await import("@cosmicdrift/kumiko-framework/db");
-      const nonEntityNames = new Set(
-        options.features.flatMap((f) =>
-          enumerateFeatureTableSources(f).map((s) => extractTableInfo(s.table).name),
-        ),
-      );
-      metas = metas.filter((m) => nonEntityNames.has(m.tableName));
-    }
-    const missing: Record<string, unknown> = {};
-    for (const meta of metas) {
-      if (await tableExists(testDb.db, `public.${meta.tableName}`)) continue;
-      missing[meta.tableName] = meta;
-    }
-    if (Object.keys(missing).length > 0) {
-      await unsafePushTables(testDb.db, missing);
-    }
-  } catch (error) {
+  if (templateDbName === undefined) {
     try {
-      await testDb.cleanup();
-    } catch {
-      // ignore — `error` is the one that matters
-    }
-    try {
-      await testRedis.cleanup();
-    } catch {
-      // ignore — `error` is the one that matters
+      await buildStackSchema(testDb.db);
+    } catch (error) {
+      try {
+        await testDb.cleanup();
+      } catch {
+        // ignore — `error` is the one that matters
+      }
+      try {
+        await testRedis.cleanup();
+      } catch {
+        // ignore — `error` is the one that matters
+      }
+      throw error;
     }
-    throw error;
   }
 
   // Redis only where two stacks can actually disagree (avoids two extra
@@ -456,16 +504,16 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
 
   // Same AppContext buildServer() gets below (db/redis/searchAdapter/
   // entityCache/masterKeyProvider/fileProviderResolver/extraContext) —
-  // shared so the job context can't drift from the request-path context
-  // (kumiko-framework#1232: a reduced `{ db, registry }` literal let jobs
-  // pass in tests while reaching for fields only prod's context has).
+  // shared so the job context can't drift from the request-path context:
+  // a reduced `{ db, registry }` literal let jobs pass in tests while
+  // reaching for fields only prod's context has.
   //
   // effectiveFeatures deliberately stays OUT of appContext — prod never puts
   // it there either (only dispatcherOptions.effectiveFeatures, consumed by
   // the command-dispatcher — see buildJobRunnerWithHook in entrypoint/
   // index.ts). Putting it here would reintroduce the exact test-vs-prod
-  // drift #1232 fixed: a job/handler reading `ctx.effectiveFeatures` would
-  // pass in tests and break in prod (kumiko-framework#1255).
+  // drift fixed: a job/handler reading `ctx.effectiveFeatures` would pass in
+  // tests and break in prod.
   const appContext = {
     db: testDb.db,
     redis: testRedis.redis,
@@ -499,8 +547,8 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     jobRunner = createJobRunner({
       registry,
       context: { ...appContext, tracer: observability.tracer, meter: observability.meter },
-      // The real REDIS_URL, not one rebuilt from `.options` — that lost
-      // password/username/tls/path (pr-review kumiko-framework #1036/2).
+      // The real REDIS_URL, not one rebuilt from `.options` — rebuilding it lost
+      // password/username/tls/path.
       redisUrl: testRedis.redisUrl,
       ...(options.jobs.consumerLane !== undefined && { consumerLane: options.jobs.consumerLane }),
       queueNamePrefix:
@@ -534,7 +582,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   // above (createJobRunner() itself opens live BullMQ Queue/lock Redis
   // connections, .start() adds a live worker) — otherwise a failing
   // buildServer()/search-config/etc. leaks that connection and the test
-  // process hangs on exit (pr-review kumiko-framework #1036/1).
+  // process hangs on exit.
   try {
     if (jobRunner) await jobRunner.start();