velocious 1.0.593 → 1.0.595

package/build/tenants/frontend-tenant-sqlite-lifecycle.js

@@ -8,6 +8,9 @@
  * @property {boolean} dirty - Whether delayed writes remain.
  * @property {number} lastUsed - Monotonic recency sequence.
  * @property {number} pinCount - Active scoped pins.
+ * @property {Promise<void> | undefined} readinessPromise - In-progress schema readiness.
+ * @property {boolean} ready - Whether migrations and model metadata are ready.
+ * @property {string | undefined} schemaGeneration - Ready or in-progress schema generation.
  * @property {LifecycleState} state - Current lifecycle state.
  */
 
@@ -55,7 +58,17 @@ export default class FrontendTenantSqliteLifecycle {
     const key = this.key(databaseIdentifier, databaseConfiguration)
     let entry = this.entries.get(key)
     if (!entry) {
-      entry = {databaseConfiguration, databaseIdentifier, dirty: false, lastUsed: 0, pinCount: 0, state: "closed"}
+      entry = {
+        databaseConfiguration,
+        databaseIdentifier,
+        dirty: false,
+        lastUsed: 0,
+        pinCount: 0,
+        readinessPromise: undefined,
+        ready: false,
+        schemaGeneration: undefined,
+        state: "closed"
+      }
       this.entries.set(key, entry)
     }
     return entry
@@ -67,6 +80,8 @@ export default class FrontendTenantSqliteLifecycle {
       dirty: entry.dirty,
       lastUsed: entry.lastUsed,
       pinCount: entry.pinCount,
+      ready: entry.ready,
+      schemaGeneration: entry.schemaGeneration,
       state: entry.state
     })
   }
@@ -94,6 +109,78 @@ export default class FrontendTenantSqliteLifecycle {
     })
   }
 
+  /**
+   * Opens and prepares one captured physical tenant database generation. The
+   * readiness callback runs outside the lifecycle bookkeeping lock, so distinct
+   * tenant databases can migrate concurrently while matching callers share one
+   * promise.
+   * @param {string} databaseIdentifier - Logical database identifier.
+   * @param {import("../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Captured physical configuration.
+   * @param {string} schemaGeneration - Application schema generation.
+   * @param {() => Promise<void>} callback - Migration and metadata initialization.
+   * @returns {Promise<Readonly<ReturnType<FrontendTenantSqliteLifecycle["snapshot"]>>>} - Ready lifecycle snapshot.
+   */
+  async initialize(databaseIdentifier, databaseConfiguration, schemaGeneration, callback) {
+    this.assertSqlite(databaseConfiguration)
+    if (!databaseConfiguration.tenantOnly) throw new Error("Frontend tenant database initialization requires a tenant-only SQLite database")
+    if (typeof schemaGeneration !== "string" || schemaGeneration.length === 0) {
+      throw new TypeError("Frontend tenant database initialization requires a non-empty schemaGeneration")
+    }
+
+    const readiness = await this.serialize(async () => {
+      const entry = this.entry(databaseIdentifier, databaseConfiguration)
+
+      if (entry.readinessPromise) {
+        if (entry.schemaGeneration !== schemaGeneration) {
+          throw new Error(`Frontend tenant database is already initializing schema generation ${JSON.stringify(entry.schemaGeneration)}; cannot initialize mismatched generation ${JSON.stringify(schemaGeneration)}`)
+        }
+
+        return {entry, promise: entry.readinessPromise}
+      }
+      if (entry.ready && entry.schemaGeneration === schemaGeneration) {
+        return {entry, promise: Promise.resolve()}
+      }
+      if (entry.schemaGeneration && entry.schemaGeneration !== schemaGeneration && (entry.pinCount > 0 || this.configuration.getDatabasePool(databaseIdentifier).capturedConnectionInUse(databaseConfiguration))) {
+        throw new Error(`Cannot replace frontend tenant schema generation ${JSON.stringify(entry.schemaGeneration)} while its physical database is in use`)
+      }
+      if (entry.state !== "open") await this.openUnlocked(entry)
+      if (entry.schemaGeneration && entry.schemaGeneration !== schemaGeneration) {
+        this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(databaseIdentifier, databaseConfiguration))
+      }
+
+      entry.ready = false
+      entry.schemaGeneration = schemaGeneration
+      entry.pinCount++
+      const promise = Promise.resolve().then(callback)
+
+      entry.readinessPromise = promise
+
+      return {entry, promise}
+    })
+
+    try {
+      await readiness.promise
+      await this.serialize(async () => {
+        if (readiness.entry.readinessPromise === readiness.promise) {
+          readiness.entry.readinessPromise = undefined
+          readiness.entry.ready = true
+          readiness.entry.pinCount--
+        }
+      })
+    } catch (error) {
+      await this.serialize(async () => {
+        if (readiness.entry.readinessPromise === readiness.promise) {
+          readiness.entry.readinessPromise = undefined
+          readiness.entry.ready = false
+          readiness.entry.pinCount--
+        }
+      })
+      throw error
+    }
+
+    return this.snapshot(readiness.entry)
+  }
+
   async flush(/** @type {string} */ databaseIdentifier, /** @type {import("../configuration-types.js").DatabaseConfigurationType} */ databaseConfiguration) {
     this.assertSqlite(databaseConfiguration)
     return await this.serialize(async () => {
@@ -117,7 +204,10 @@ export default class FrontendTenantSqliteLifecycle {
       try {
         if (flush) await this.configuration.getDatabasePool(databaseIdentifier).flushCapturedConnection(databaseConfiguration)
         await this.configuration.getDatabasePool(databaseIdentifier).closeCapturedConnection(databaseConfiguration)
+        this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(databaseIdentifier, databaseConfiguration))
         entry.dirty = false
+        entry.ready = false
+        entry.schemaGeneration = undefined
         entry.state = "closed"
         this.entries.delete(this.key(databaseIdentifier, databaseConfiguration))
         return this.snapshot(entry)
@@ -136,11 +226,16 @@ export default class FrontendTenantSqliteLifecycle {
       entry.state = "deleting"
       try {
         await this.configuration.getDatabasePool(databaseIdentifier).deleteCapturedDatabase(databaseConfiguration)
+        this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(databaseIdentifier, databaseConfiguration))
         entry.dirty = false
+        entry.ready = false
+        entry.schemaGeneration = undefined
         entry.state = "closed"
         this.entries.delete(this.key(databaseIdentifier, databaseConfiguration))
         return this.snapshot(entry)
       } catch (error) {
+        this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(databaseIdentifier, databaseConfiguration))
+        entry.ready = false
         entry.state = "closed"
         throw error
       }
@@ -150,7 +245,7 @@ export default class FrontendTenantSqliteLifecycle {
   inspect(/** @type {string} */ databaseIdentifier, /** @type {import("../configuration-types.js").DatabaseConfigurationType} */ databaseConfiguration) {
     this.assertSqlite(databaseConfiguration)
     const entry = this.entries.get(this.key(databaseIdentifier, databaseConfiguration))
-    return entry ? this.snapshot(entry) : Object.freeze({databaseIdentifier, dirty: false, lastUsed: 0, pinCount: 0, state: "closed"})
+    return entry ? this.snapshot(entry) : Object.freeze({databaseIdentifier, dirty: false, lastUsed: 0, pinCount: 0, ready: false, schemaGeneration: undefined, state: "closed"})
   }
 
   inspectAll() {
@@ -158,7 +253,13 @@ export default class FrontendTenantSqliteLifecycle {
     return Object.freeze({handles: Object.freeze(handles), maxOpenHandles: this.maxOpenHandles, openCount: handles.filter(({state}) => state === "open").length})
   }
 
-  reset() { this.entries.clear() }
+  reset() {
+    for (const entry of this.entries.values()) {
+      this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(entry.databaseIdentifier, entry.databaseConfiguration))
+    }
+
+    this.entries.clear()
+  }
 
   async withPin(/** @type {string} */ databaseIdentifier, /** @type {import("../configuration-types.js").DatabaseConfigurationType} */ databaseConfiguration, /** @type {() => Promise<ReturnType<typeof JSON.parse>>} */ callback) {
     this.assertSqlite(databaseConfiguration)
@@ -176,21 +277,52 @@ export default class FrontendTenantSqliteLifecycle {
     }
   }
 
-  async databaseOperation(/** @type {string} */ databaseIdentifier, /** @type {import("../configuration-types.js").DatabaseConfigurationType} */ databaseConfiguration, /** @type {() => Promise<ReturnType<typeof JSON.parse>>} */ callback) {
-    if (!this.entries.has(this.key(databaseIdentifier, databaseConfiguration))) return await callback()
+  /**
+   * Atomically validates readiness, captures the schema generation, and pins
+   * one lifecycle entry before starting database work.
+   * @param {string} databaseIdentifier - Logical database identifier.
+   * @param {import("../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Captured physical configuration.
+   * @param {{requireReady: boolean, schemaGeneration?: string}} options - Operation readiness requirements.
+   * @param {(schemaGeneration: string | undefined) => Promise<ReturnType<typeof JSON.parse>>} callback - Pinned operation callback.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Operation result.
+   */
+  async databaseOperation(databaseIdentifier, databaseConfiguration, {requireReady, schemaGeneration}, callback) {
+    if (databaseConfiguration.type !== "sqlite") return await callback(schemaGeneration)
 
-    return await this.withPin(databaseIdentifier, databaseConfiguration, async () => {
-      try {
-        return await callback()
-      } finally {
-        const dirty = this.configuration.getDatabasePool(databaseIdentifier).capturedConnectionHasPendingWrites(databaseConfiguration)
-        await this.serialize(async () => {
-          const entry = this.entry(databaseIdentifier, databaseConfiguration)
-          entry.dirty ||= dirty
-          entry.lastUsed = ++this.sequence
-        })
+    const entry = await this.serialize(async () => {
+      const operationEntry = this.entries.get(this.key(databaseIdentifier, databaseConfiguration))
+
+      if (requireReady && databaseConfiguration.tenantOnly && databaseConfiguration.migrations && !operationEntry?.ready) {
+        const generation = operationEntry?.schemaGeneration ? ` for schema generation ${JSON.stringify(operationEntry.schemaGeneration)}` : ""
+
+        throw new Error(`Frontend tenant database ${JSON.stringify(databaseIdentifier)} is not ready${generation}`)
+      }
+      if (!operationEntry) return undefined
+      if (schemaGeneration && operationEntry.schemaGeneration && schemaGeneration !== operationEntry.schemaGeneration) {
+        throw new Error(`Frontend tenant database ${JSON.stringify(databaseIdentifier)} is on schema generation ${JSON.stringify(operationEntry.schemaGeneration)}, not ${JSON.stringify(schemaGeneration)}`)
       }
+      if (operationEntry.state !== "open") await this.openUnlocked(operationEntry)
+
+      operationEntry.pinCount++
+      operationEntry.lastUsed = ++this.sequence
+
+      return operationEntry
     })
+    const operationSchemaGeneration = schemaGeneration || entry?.schemaGeneration
+
+    if (!entry) return await callback(operationSchemaGeneration)
+
+    try {
+      return await callback(operationSchemaGeneration)
+    } finally {
+      const dirty = this.configuration.getDatabasePool(databaseIdentifier).capturedConnectionHasPendingWrites(databaseConfiguration)
+
+      await this.serialize(async () => {
+        entry.dirty ||= dirty
+        entry.lastUsed = ++this.sequence
+        entry.pinCount--
+      })
+    }
   }
 
   async openUnlocked(/** @type {LifecycleEntry} */ entry) {
@@ -222,6 +354,9 @@ export default class FrontendTenantSqliteLifecycle {
     const victim = candidates[0]
     if (!victim) throw new Error(`Frontend tenant SQLite handle capacity ${this.maxOpenHandles} reached; every handle is dirty, pinned, or in use`)
     await this.configuration.getDatabasePool(victim.databaseIdentifier).closeCapturedConnection(victim.databaseConfiguration)
+    this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(victim.databaseIdentifier, victim.databaseConfiguration))
+    victim.ready = false
+    victim.schemaGeneration = undefined
     victim.state = "closed"
     this.entries.delete(this.key(victim.databaseIdentifier, victim.databaseConfiguration))
   }

package/build/tenants/tenant-handle.js

@@ -1,11 +1,13 @@
 // @ts-check
 
+import Migrator from "../database/migrator.js"
+
 /**
  * TenantDescriptorValue type.
  * @typedef {null | boolean | number | string | TenantDescriptorValue[] | {[key: string]: TenantDescriptorValue}} TenantDescriptorValue
  */
 /** @typedef {{[key: string]: TenantDescriptorValue}} TenantDescriptor */
-/** @typedef {{databaseIdentifier: string, dirty: boolean, lastUsed: number, pinCount: number, state: "closed" | "closing" | "deleting" | "open" | "opening"}} TenantSqliteLifecycleSnapshot */
+/** @typedef {{databaseIdentifier: string, dirty: boolean, lastUsed: number, pinCount: number, ready: boolean, schemaGeneration: string | undefined, state: "closed" | "closing" | "deleting" | "open" | "opening"}} TenantSqliteLifecycleSnapshot */
 
 /**
  * Returns a readable path for a captured descriptor/configuration value.
@@ -204,6 +206,17 @@ export default class TenantHandle {
     return this._tenant
   }
 
+  /**
+   * Rejects using this handle with a different Configuration instance.
+   * @param {import("../configuration.js").default} configuration - Expected owner.
+   * @returns {void}
+   */
+  assertConfiguration(configuration) {
+    if (configuration !== this._configuration) {
+      throw new Error("Tenant handle belongs to a different Velocious configuration")
+    }
+  }
+
   /**
    * Returns the captured physical configuration for an active identifier.
    * @param {string} databaseIdentifier - Logical database identifier.
@@ -229,6 +242,58 @@ export default class TenantHandle {
     return await this._configuration.getFrontendTenantSqliteLifecycle().open(databaseIdentifier, this.databaseConfiguration(databaseIdentifier))
   }
 
+  /**
+   * Opens, migrates, and initializes record metadata for one captured physical
+   * tenant SQLite database and application schema generation.
+   * @param {object} options - Initialization options.
+   * @param {string} options.databaseIdentifier - Tenant-only logical database identifier.
+   * @param {import("../database/migrator/types.js").RequireMigrationContextType} options.migrations - Frontend migration require context.
+   * @param {string} options.schemaGeneration - Stable application schema generation.
+   * @returns {Promise<Readonly<TenantSqliteLifecycleSnapshot>>} - Ready lifecycle snapshot.
+   */
+  async initialize({databaseIdentifier, migrations, schemaGeneration}) {
+    if (!migrations || typeof migrations !== "function" || typeof migrations.keys !== "function") {
+      throw new TypeError("TenantHandle.initialize requires a migrations require context")
+    }
+
+    const databaseConfiguration = this.databaseConfiguration(databaseIdentifier)
+    const lifecycle = this._configuration.getFrontendTenantSqliteLifecycle()
+
+    return await lifecycle.initialize(databaseIdentifier, databaseConfiguration, schemaGeneration, async () => {
+      await this._databaseOperation({
+        databaseIdentifier,
+        name: `Initialize frontend tenant database: ${databaseIdentifier}`,
+        requireReady: false,
+        schemaGeneration
+      }, async (operation) => {
+        const migrator = new Migrator({configuration: this._configuration, databaseIdentifiers: [databaseIdentifier]})
+
+        operation.connection().clearSchemaCache()
+        await migrator.migrateRequireContextForDatabase({
+          databaseConfiguration,
+          databaseIdentifier,
+          db: operation.connection(),
+          requireContext: migrations
+        })
+        await this._configuration.initializeModels({type: "frontend-tenant"})
+
+        for (const modelClass of Object.values(this._configuration.getModelClasses())) {
+          if (modelClass.getDatabaseIdentifier({tenant: this._tenant}) !== databaseIdentifier) continue
+          const table = await operation.connection().getTableByName(modelClass.tableName(), {throwError: false})
+
+          if (!table && !modelClass.getEagerLoadRecordMetadata()) continue
+          if (Object.keys(modelClass.getTranslationsMap()).length > 0) {
+            const translationsTable = await operation.connection().getTableByName(modelClass.getTranslationsTableName(), {throwError: false})
+
+            if (!translationsTable && !modelClass.getEagerLoadRecordMetadata()) continue
+          }
+
+          await operation.ensureModelInitialized(modelClass)
+        }
+      })
+    })
+  }
+
   /**
    * Flushes this captured SQLite identity.
    * @param {{databaseIdentifier: string}} options - Lifecycle options.
@@ -290,13 +355,32 @@ export default class TenantHandle {
    * @returns {Promise<T>} - Callback result.
    */
   async databaseOperation({databaseIdentifier, name = "TenantHandle.databaseOperation"}, callback) {
+    return await this._databaseOperation({databaseIdentifier, name, requireReady: true}, callback)
+  }
+
+  /**
+   * Runs a captured operation with explicit readiness policy. Initialization is
+   * the only caller allowed to enter an unready schema generation.
+   * @template T
+   * @param {{databaseIdentifier: string, name: string, requireReady: boolean, schemaGeneration?: string}} options - Internal operation options.
+   * @param {(operation: import("../database/operation.js").default) => Promise<T>} callback - Operation callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async _databaseOperation({databaseIdentifier, name, requireReady, schemaGeneration}, callback) {
     const databaseConfiguration = this.databaseConfiguration(databaseIdentifier)
-    return await this._configuration.getFrontendTenantSqliteLifecycle().databaseOperation(databaseIdentifier, databaseConfiguration, async () => await this._configuration.withDatabaseOperation({
-      databaseConfiguration,
+
+    return await this._configuration.getFrontendTenantSqliteLifecycle().databaseOperation(
       databaseIdentifier,
-      name,
-      tenant: this._tenant
-    }, callback))
+      databaseConfiguration,
+      {requireReady, schemaGeneration},
+      async (operationSchemaGeneration) => await this._configuration.withDatabaseOperation({
+        databaseConfiguration,
+        databaseIdentifier,
+        name,
+        schemaGeneration: operationSchemaGeneration,
+        tenant: this._tenant
+      }, callback)
+    )
   }
 
   /**

package/build/testing/browser-test-app.js

@@ -3,6 +3,7 @@
 import SystemTestBrowserHelper from "system-testing/build/system-test-browser-helper.js"
 import BrowserEnvironmentHandler from "../environment-handlers/browser.js"
 import runFrontendModelEventHookScenario from "./browser-frontend-model-event-hook-scenarios.js"
+import runUseDatabaseSelectionTransitionScenario from "./browser-use-database-hook-scenarios.js"
 
 const root = document.getElementById("root") || (() => {
   const element = document.createElement("div")
@@ -28,5 +29,6 @@ systemTestBrowserHelper.enableOnBrowser()
 Object.assign(globalThis, {velociousBrowserTest: {
   BrowserEnvironmentHandler,
   runFrontendModelEventHookScenario,
+  runUseDatabaseSelectionTransitionScenario,
   systemTestBrowserHelper
 }})

package/build/testing/browser-use-database-hook-scenarios.js

@@ -0,0 +1,204 @@
+// @ts-check
+
+import React, { act } from "react"
+import {createRoot} from "react-dom/client"
+
+import Configuration, {CurrentConfigurationNotSetError} from "../configuration.js"
+import BrowserEnvironmentHandler from "../environment-handlers/browser.js"
+import Migration from "../database/migration/index.js"
+import SingleMultiUsePool from "../database/pool/single-multi-use.js"
+import SqliteWebDriver from "../database/drivers/sqlite/index.web.js"
+import TenantHandle from "../tenants/tenant-handle.js"
+import useDatabase from "../database/use-database.js"
+
+/**
+ * Returns the current configuration without requiring one to exist.
+ * @returns {Configuration | undefined} - Current configuration when installed.
+ */
+function currentConfigurationOrUndefined() {
+  try {
+    return Configuration.current()
+  } catch (error) {
+    if (!(error instanceof CurrentConfigurationNotSetError)) throw error
+
+    return undefined
+  }
+}
+
+/**
+ * Builds the scoped browser configuration used by the real hook scenario.
+ * @returns {Configuration} - Browser test configuration.
+ */
+function buildHookConfiguration() {
+  return new Configuration({
+    database: {
+      test: {
+        projectTenant: {
+          driver: SqliteWebDriver,
+          getConnection: async () => { throw new Error("Hook scenario must not open a physical database") },
+          migrations: true,
+          name: "use-database-hook-template",
+          poolType: SingleMultiUsePool,
+          tenantOnly: true,
+          type: "sqlite"
+        }
+      }
+    },
+    directory: "/use-database-hook-scenario",
+    environment: "test",
+    environmentHandler: new BrowserEnvironmentHandler(),
+    initializeModels: async () => {},
+    locale: "en",
+    localeFallbacks: {en: ["en"]},
+    locales: ["en"],
+    tenantDatabaseResolver: ({identifier, tenant}) => {
+      if (identifier !== "projectTenant" || !tenant || typeof tenant !== "object") return
+
+      return {name: `use-database-hook-${String(/** @type {{slug?: string}} */ (tenant).slug)}`}
+    }
+  })
+}
+
+/**
+ * Flushes real React hook transitions and reports synchronous selection state,
+ * inline loader stability, and stale completion suppression.
+ * @returns {Promise<{firstChangedLoaded: boolean, initialLoaded: boolean, loaderCalls: string[], loadedAfterInlineLoaderRerender: boolean, thirdAfterStaleCompletion: {error: string | null, loaded: boolean}}>} - Render observations.
+ */
+export default async function runUseDatabaseSelectionTransitionScenario() {
+  const container = document.createElement("div")
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  /** @type {{error: string | null, loaded: boolean, selection: "first" | "second" | "third"}[]} */
+  const renders = []
+  /** @type {string[]} */
+  const loaderCalls = []
+  /**
+   * Releases the deliberately stale second initialization.
+   * @type {() => void}
+   */
+  let releaseSecondInitialization = () => {}
+  const secondInitializationRelease = new Promise((resolve) => { releaseSecondInitialization = () => resolve(undefined) })
+  /**
+   * Signals that the deliberately stale second initialization started.
+   * @type {() => void}
+   */
+  let signalSecondInitialization = () => {}
+  const secondInitializationStarted = new Promise((resolve) => { signalSecondInitialization = () => resolve(undefined) })
+
+  class HookTenantHandle extends TenantHandle {
+    /**
+     * Runs test initialization without touching a physical database.
+     * @param {{migrations: import("../database/migrator/types.js").RequireMigrationContextType}} args - Hook initialization arguments.
+     * @returns {Promise<Readonly<ReturnType<TenantHandle["inspect"]>>>} - Ready test snapshot.
+     */
+    async initialize({migrations}) {
+      loaderCalls.push(migrations.id)
+
+      if (this.tenant().slug === "second") {
+        signalSecondInitialization()
+        await secondInitializationRelease
+        throw new Error("SECOND_SELECTION_FAILED")
+      }
+
+      return Object.freeze({databaseIdentifier: "projectTenant", dirty: false, lastUsed: 0, pinCount: 0, ready: true, schemaGeneration: "generation-1", state: "open"})
+    }
+  }
+  const previousConfiguration = currentConfigurationOrUndefined()
+  const restorationConfiguration = previousConfiguration || buildHookConfiguration()
+  const configuration = buildHookConfiguration()
+
+  configuration.setCurrent()
+
+  const firstHandle = new HookTenantHandle({configuration, tenant: {slug: "first"}})
+  const secondHandle = new HookTenantHandle({configuration, tenant: {slug: "second"}})
+  const thirdHandle = new HookTenantHandle({configuration, tenant: {slug: "third"}})
+  const renderCounts = {first: 0, second: 0, third: 0}
+
+  /**
+   * Runs hook probe.
+   * @param {{selection: "first" | "second" | "third", tenantHandle: HookTenantHandle}} props - Probe props.
+   * @returns {React.ReactElement} - Empty host element.
+   */
+  function HookProbe({selection, tenantHandle}) {
+    const state = useDatabase({
+      databaseIdentifier: "projectTenant",
+      migrationsRequireContextCallback: async () => {
+        /**
+         * Looks up an empty migration context entry recreated by every probe render.
+         * @param {string} fileName - Requested migration file.
+         * @returns {{default: typeof Migration}} - Placeholder migration module.
+         * @type {import("../database/migrator/types.js").RequireMigrationContextType}
+         */
+        const emptyMigrations = (fileName) => {
+          if (!fileName) throw new Error("Migration context lookup requires a file name")
+
+          return {default: Migration}
+        }
+
+        emptyMigrations.keys = () => []
+        emptyMigrations.id = selection
+
+        return emptyMigrations
+      },
+      schemaGeneration: "generation-1",
+      tenantHandle
+    })
+
+    renderCounts[selection]++
+    if (renderCounts[selection] > 20) throw new Error(`useDatabase render loop for ${selection}`)
+    renders.push({error: state.error?.message || null, loaded: state.loaded, selection})
+
+    return React.createElement("div")
+  }
+
+  try {
+    await act(async () => {
+      root.render(React.createElement(HookProbe, {selection: "first", tenantHandle: firstHandle}))
+    })
+
+    const initialRender = renders.at(-1)
+
+    await act(async () => {
+      root.render(React.createElement(HookProbe, {selection: "first", tenantHandle: firstHandle}))
+    })
+
+    const loadedAfterInlineLoaderRerender = renders.at(-1)?.loaded
+
+    act(() => {
+      root.render(React.createElement(HookProbe, {selection: "second", tenantHandle: secondHandle}))
+    })
+
+    const firstChangedRender = renders.find((render) => render.selection === "second")
+    await secondInitializationStarted
+
+    await act(async () => {
+      root.render(React.createElement(HookProbe, {selection: "third", tenantHandle: thirdHandle}))
+    })
+
+    releaseSecondInitialization()
+    await act(async () => { await secondInitializationRelease })
+
+    const thirdAfterStaleCompletion = renders.at(-1)
+
+    if (!initialRender || !firstChangedRender || !thirdAfterStaleCompletion || loadedAfterInlineLoaderRerender === undefined) {
+      throw new Error("useDatabase hook scenario did not render every selection")
+    }
+
+    return {
+      firstChangedLoaded: firstChangedRender.loaded,
+      initialLoaded: initialRender.loaded,
+      loaderCalls,
+      loadedAfterInlineLoaderRerender,
+      thirdAfterStaleCompletion: {
+        error: thirdAfterStaleCompletion.error,
+        loaded: thirdAfterStaleCompletion.loaded
+      }
+    }
+  } finally {
+    releaseSecondInitialization()
+    await act(async () => { root.unmount() })
+    container.remove()
+    restorationConfiguration.setCurrent()
+    await configuration.closeDatabaseConnections()
+  }
+}

package/build/testing/test-runner.js

@@ -1456,14 +1456,15 @@ export default class TestRunner {
      * @type {Record<ConsoleMethodName, (...args: Array<ReturnType<typeof JSON.parse>>) => void>} */
     const consoleObject = /** @type {Record<ConsoleMethodName, (...args: Array<ReturnType<typeof JSON.parse>>) => void>} */ (console)
     /**
-     * Original console methods.
+     * Original console methods captured as direct references so stopping restores
+     * the exact method that was installed at capture start.
      * @type {Record<ConsoleMethodName, (...args: Array<ReturnType<typeof JSON.parse>>) => void>} */
     const originalConsoleMethods = {
-      debug: consoleObject.debug.bind(console),
-      error: consoleObject.error.bind(console),
-      info: consoleObject.info.bind(console),
-      log: consoleObject.log.bind(console),
-      warn: consoleObject.warn.bind(console)
+      debug: consoleObject.debug,
+      error: consoleObject.error,
+      info: consoleObject.info,
+      log: consoleObject.log,
+      warn: consoleObject.warn
     }
     let stopped = false
     let outputText = ""
@@ -1473,7 +1474,7 @@ export default class TestRunner {
         lines.push(`[${new Date().toISOString()}] [${methodName}] ${format(...args)}`)
 
         if (passthrough) {
-          originalConsoleMethods[methodName](...args)
+          originalConsoleMethods[methodName].apply(consoleObject, args)
         }
       }
     }