velocious 1.0.577 → 1.0.579

package/build/database/drivers/sqlite/query.web.js

@@ -4,7 +4,7 @@
  * Runs query.
  * @param {import("sql.js").Database} connection - Connection.
  * @param {string} sql - SQL string.
- * @returns {Promise<Record<string, ?>[]>} - Resolves with string value.
+ * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>[]>} - Resolves with string value.
  */
 export default async function query(connection, sql) {
   const rows = []
@@ -34,7 +34,7 @@ export default async function query(connection, sql) {
     for (const rowValues of result[0].values) {
       /**
        * Row.
-       * @type {Record<string, ?>} */
+       * @type {Record<string, ReturnType<typeof JSON.parse>>} */
       const row = {}
 
       for (const columnIndex in columns) {

package/build/database/drivers/sqlite/table-rebuilder.js

@@ -59,7 +59,7 @@ export default class VelociousDatabaseDriversSqliteTableRebuilder {
     // copy: index names are database-global and survive the rename, and a violation (e.g. a new
     // unique index over rows that all receive the same default) fails during INSERT...SELECT,
     // while the original table still exists - never after the swap.
-    /** @type {Array<{column: import("../../table-data/table-column.js").default, index: ?, indexArgs: ?}>} */
+    /** @type {Array<{column: import("../../table-data/table-column.js").default, index: ReturnType<typeof JSON.parse>, indexArgs: ReturnType<typeof JSON.parse>}>} */
     const strippedColumnIndexes = []
 
     for (const column of targetTableData.getColumns()) {

package/build/database/migration/index.js

@@ -3,7 +3,7 @@
 /**
  * AddColumnArgsType type.
  * @typedef {object} AddColumnArgsType
- * @property {?} [default] - Default value for the column.
+ * @property {ReturnType<typeof JSON.parse>} [default] - Default value for the column.
  * @property {object} [foreignKey] - Foreign key definition for the column.
  * @property {boolean | {unique: boolean}} [index] - Whether to add an index (optionally unique).
  * @property {number} [limit] - Alias for maxLength (varchar length limit) on string-like columns.
@@ -15,7 +15,7 @@
 /**
  * CreateTableIdArgsType type.
  * @typedef {object} CreateTableIdArgsType
- * @property {?} [default] - Default value for the ID column.
+ * @property {ReturnType<typeof JSON.parse>} [default] - Default value for the ID column.
  * @property {string} [type] - Column type for the ID column.
  */
 /**

package/build/database/migrator/types.js

@@ -9,11 +9,11 @@
  */
 
 /**
- * @typedef {function() : typeof import("../migration/index.js").default} ImportCallbackType
+ * @typedef {() => typeof import("../migration/index.js").default} ImportCallbackType
  */
 
 /**
- * @typedef {function(string) : Promise<typeof import("../migration/index.js").default>} ImportFullpathCallbackType
+ * @typedef {(arg: string) => Promise<typeof import("../migration/index.js").default>} ImportFullpathCallbackType
  */
 
 /**

package/build/database/operation.js

@@ -11,16 +11,23 @@ export default class VelociousDatabaseOperation {
    * Runs constructor.
    * @param {object} args - Operation ownership.
    * @param {import("../configuration.js").default} args.configuration - Owning configuration.
+   * @param {boolean} [args.enforceCurrentTenantReuseKey] - Whether ambient tenant changes invalidate this legacy operation.
+   * @param {import("../configuration-types.js").DatabaseConfigurationType} [args.databaseConfiguration] - Captured resolved physical database configuration.
    * @param {string} args.configurationReuseKey - Physical database configuration key captured at checkout.
    * @param {import("./drivers/base.js").default} args.connection - Pinned physical connection.
    * @param {string} args.databaseIdentifier - Singular database identifier.
    * @param {symbol} args.owner - Opaque pool lease owner.
+   * @param {object | undefined} args.tenant - Tenant descriptor captured by the owning handle.
    */
-  constructor({configuration, configurationReuseKey, connection, databaseIdentifier, owner}) {
+  constructor({configuration, databaseConfiguration, configurationReuseKey, connection, databaseIdentifier, enforceCurrentTenantReuseKey = true, owner, tenant}) {
     this._active = true
     this._configuration = configuration
+    this._databaseConfiguration = databaseConfiguration || configuration.resolveDatabaseConfiguration(databaseIdentifier, tenant)
     this._configurationReuseKey = configurationReuseKey
     this._databaseIdentifier = databaseIdentifier
+    this._enforceCurrentTenantReuseKey = enforceCurrentTenantReuseKey
+    this._physicalConnection = connection
+    this._tenant = tenant
     this._connection = new OperationConnection({
       connection,
       operation: this,
@@ -54,7 +61,7 @@ export default class VelociousDatabaseOperation {
       throw new Error(`${ModelClass.getModelName()} belongs to another Velocious configuration`)
     }
 
-    const modelDatabaseIdentifier = ModelClass.getDatabaseIdentifier()
+    const modelDatabaseIdentifier = ModelClass.getDatabaseIdentifier({tenant: this._tenant})
 
     if (modelDatabaseIdentifier !== this._databaseIdentifier) {
       throw new Error(`${ModelClass.getModelName()} uses database ${JSON.stringify(modelDatabaseIdentifier)}, not operation database ${JSON.stringify(this._databaseIdentifier)}`)
@@ -118,11 +125,52 @@ export default class VelociousDatabaseOperation {
      * Narrows the Proxy facade to the complete driver surface that it forwards.
      * @type {import("./drivers/base.js").default}
      */
-    const connectionFacade = /** @type {?} */ (this._connection)
+    const connectionFacade = /** @type {ReturnType<typeof JSON.parse>} */ (this._connection)
 
     return connectionFacade
   }
 
+  /**
+   * Returns the tenant descriptor captured by the immutable handle.
+   * @returns {Record<string, unknown> | undefined} - Captured tenant descriptor.
+   */
+  tenant() {
+    return /** @type {Record<string, unknown> | undefined} */ (this._tenant)
+  }
+
+  /**
+   * Returns the logical database identifier owned by this operation.
+   * @returns {string} - Database identifier.
+   */
+  databaseIdentifier() {
+    return this._databaseIdentifier
+  }
+
+  /**
+   * Returns a stable physical-database identity suitable for operation-aware caches.
+   * @returns {string} - Physical database identity.
+   */
+  databaseIdentity() {
+    return `${this._databaseIdentifier}:${this._configurationReuseKey}`
+  }
+
+  /**
+   * Initializes a model through this operation's captured connection.
+   * @param {typeof import("./record/index.js").default} ModelClass - Model class.
+   * @returns {Promise<void>} - Resolves when initialized.
+   */
+  async ensureModelInitialized(ModelClass) {
+    this.assertActive()
+
+    if (ModelClass.isInitialized()) this.assertModel(ModelClass)
+
+    await ModelClass.ensureInitialized({
+      configuration: this._configuration,
+      connection: this.connection()
+    })
+    this.assertModel(ModelClass)
+  }
+
   /**
    * Raises when an operation handle has left its callback.
    * @returns {void}
@@ -130,12 +178,17 @@ export default class VelociousDatabaseOperation {
   assertActive() {
     if (!this._active) throw new Error("Database operation has completed")
 
-    const currentReuseKey = this
+    const pool = this
       ._configuration
       .getDatabasePool(this._databaseIdentifier)
-      .getConfigurationReuseKey()
+    const capturedReuseKey = pool.getConfigurationReuseKey(this._databaseConfiguration)
+    const connectionReuseKey = pool.getConnectionConfigurationReuseKey(this._physicalConnection)
+
+    if (capturedReuseKey !== this._configurationReuseKey || connectionReuseKey !== this._configurationReuseKey) {
+      throw new Error(`Database operation for ${JSON.stringify(this._databaseIdentifier)} belongs to a different physical database than its captured tenant handle`)
+    }
 
-    if (currentReuseKey !== this._configurationReuseKey) {
+    if (this._enforceCurrentTenantReuseKey && pool.getConfigurationReuseKey() !== this._configurationReuseKey) {
       throw new Error(`Database operation for ${JSON.stringify(this._databaseIdentifier)} belongs to a different physical database than the current tenant context`)
     }
   }

package/build/database/pool/async-tracked-multi-connection.js

@@ -113,7 +113,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     super({configuration, identifier})
     /**
      * Runs a callback without the inherited current connection context.
-     * @type {(callback: () => ?) => ?}
+     * @type {(callback: () => ReturnType<typeof JSON.parse>) => ReturnType<typeof JSON.parse>}
      */
     const withoutCurrentConnectionContext = (callback) => this.asyncLocalStorage.run(SUPPRESSED_CONNECTION_CONTEXT, callback)
     this._withoutCurrentConnectionContext = withoutCurrentConnectionContext
@@ -155,7 +155,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * Runs close checked out connection after checkin failure.
    * @param {import("../drivers/base.js").default} connection - Connection that failed check-in cleanup.
    * @param {number | undefined} id - Connection checkout id.
-   * @param {?} originalError - Error that caused check-in cleanup to fail.
+   * @param {ReturnType<typeof JSON.parse>} originalError - Error that caused check-in cleanup to fail.
    * @returns {Promise<void>} - Resolves when cleanup has been attempted.
    */
   async closeCheckedOutConnectionAfterCheckinFailure(connection, id, originalError) {
@@ -232,6 +232,33 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     return await this.waitForCheckout(databaseConfig, reuseKey, options)
   }
 
+  /**
+   * Checks out a connection for an already-resolved physical configuration
+   * without consulting ambient tenant state.
+   * @param {import("../../configuration-types.js").DatabaseConfigurationType} databaseConfig - Captured database configuration.
+   * @param {import("./base.js").ConnectionCheckoutOptions} [options] - Checkout options.
+   * @returns {Promise<import("../drivers/base.js").default>} - Activated pooled connection.
+   */
+  async checkoutForConfiguration(databaseConfig, options = {}) {
+    const reuseKey = this.getConfigurationReuseKey(databaseConfig)
+    let connection = this.takeIdleConnectionForReuseKey(reuseKey)
+
+    if (connection) return await this.activateConnection(connection, options)
+
+    await this.reapIdleConnections()
+    connection = this.takeIdleConnectionForReuseKey(reuseKey)
+
+    if (connection) return await this.activateConnection(connection, options)
+
+    if (this.canSpawnConnection(databaseConfig)) {
+      connection = await this.spawnConnectionForCheckout(databaseConfig, reuseKey)
+
+      return await this.activateConnection(connection, options)
+    }
+
+    return await this.waitForCheckout(databaseConfig, reuseKey, options)
+  }
+
   /**
    * Runs take idle connection for reuse key.
    * @param {string} reuseKey - Database configuration reuse key.
@@ -295,10 +322,11 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs max connections.
+   * @param {import("../../configuration-types.js").DatabaseConfigurationType} [databaseConfig] - Configuration whose pool maximum applies.
    * @returns {number | null} - Configured max live connections.
    */
-  maxConnections() {
-    const value = this.getConfiguration().pool?.max
+  maxConnections(databaseConfig = this.getConfiguration()) {
+    const value = databaseConfig.pool?.max
 
     if (value === null) return null
     if (this.validMaxConnections(value)) return value
@@ -308,10 +336,11 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs checkout timeout millis.
+   * @param {import("../../configuration-types.js").DatabaseConfigurationType} [databaseConfig] - Configuration whose timeout applies.
    * @returns {number | null} - Pending checkout timeout in milliseconds, or null when disabled.
    */
-  checkoutTimeoutMillis() {
-    const value = this.getConfiguration().pool?.checkoutTimeoutMillis
+  checkoutTimeoutMillis(databaseConfig = this.getConfiguration()) {
+    const value = databaseConfig.pool?.checkoutTimeoutMillis
 
     if (value === null) return null
     if (this.validCheckoutTimeoutMillis(value)) return value
@@ -321,7 +350,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs valid checkout timeout millis.
-   * @param {?} value - Candidate checkout timeout.
+   * @param {ReturnType<typeof JSON.parse>} value - Candidate checkout timeout.
    * @returns {value is number} - Whether the value is a valid timeout.
    */
   validCheckoutTimeoutMillis(value) {
@@ -330,7 +359,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs valid max connections.
-   * @param {?} value - Candidate max connection count.
+   * @param {ReturnType<typeof JSON.parse>} value - Candidate max connection count.
    * @returns {value is number} - Whether the value is a valid max connection count.
    */
   validMaxConnections(value) {
@@ -353,10 +382,11 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs can spawn connection.
+   * @param {import("../../configuration-types.js").DatabaseConfigurationType} [databaseConfig] - Configuration whose pool maximum applies.
    * @returns {boolean} - Whether a new connection can be spawned.
    */
-  canSpawnConnection() {
-    const maxConnections = this.maxConnections()
+  canSpawnConnection(databaseConfig = this.getConfiguration()) {
+    const maxConnections = this.maxConnections(databaseConfig)
 
     return maxConnections === null || this.liveConnectionCount() < maxConnections
   }
@@ -396,7 +426,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
   async waitForCheckout(databaseConfig, reuseKey, options = {}) {
     return await new Promise((resolve, reject) => {
       const enqueuedAt = Date.now()
-      const timeoutMillis = this.checkoutTimeoutMillis()
+      const timeoutMillis = this.checkoutTimeoutMillis(databaseConfig)
       /** @type {PendingCheckout} */
       const checkout = {
         databaseConfig,
@@ -451,7 +481,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
       if (await this.closeIdleConnectionForPendingCheckoutCapacity(checkout)) continue
       if (!this.pendingCheckouts.includes(checkout)) continue
-      if (this.canSpawnConnection()) {
+      if (this.canSpawnConnection(checkout.databaseConfig)) {
         this.removePendingCheckoutAt(0)
         await this.spawnAndResolvePendingCheckout(checkout)
         continue
@@ -561,7 +591,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Builds a sanitized connection summary for checkout timeout diagnostics.
-   * @param {Record<string, ?>} connection - Connection debug snapshot.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} connection - Connection debug snapshot.
    * @returns {string} - Sanitized connection state.
    */
   pendingCheckoutTimeoutConnectionSummary(connection) {
@@ -575,7 +605,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     const activeQuery = connection.activeQuery
 
     if (activeQuery && typeof activeQuery === "object" && !Array.isArray(activeQuery)) {
-      const runningMs = (/** @type {Record<string, ?>} */ (activeQuery)).runningMs
+      const runningMs = (/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (activeQuery)).runningMs
 
       if (typeof runningMs === "number") parts.push(`activeQueryMs=${runningMs}`)
     }
@@ -623,7 +653,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
     if (this.findIdleConnectionForReuseKey(checkout.reuseKey)) return false
 
-    return this.canSpawnConnection() ? false : await this.closeOneIdleConnectionForCapacity()
+    return this.canSpawnConnection(checkout.databaseConfig) ? false : await this.closeOneIdleConnectionForCapacity()
   }
 
   /**
@@ -703,8 +733,8 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
   /**
    * Runs with connection.
    * @template T
-   * @param {import("./base.js").ConnectionCheckoutOptions | function(import("../drivers/base.js").default) : Promise<T>} optionsOrCallback - Checkout options or callback to invoke with the connection.
-   * @param {function(import("../drivers/base.js").default) : Promise<T>} [callback] - Callback to invoke with the connection.
+   * @param {import("./base.js").ConnectionCheckoutOptions | ((arg: import("../drivers/base.js").default) => Promise<T>)} optionsOrCallback - Checkout options or callback to invoke with the connection.
+   * @param {(arg: import("../drivers/base.js").default) => Promise<T>} [callback] - Callback to invoke with the connection.
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withConnection(optionsOrCallback, callback) {
@@ -725,6 +755,27 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     })
   }
 
+  /**
+   * Runs a captured operation through the normal bounded pool lifecycle.
+   * @template T
+   * @param {import("./base.js").CapturedConnectionOptions} options - Captured checkout options.
+   * @param {(connection: import("../drivers/base.js").default, owner: symbol) => Promise<T>} callback - Operation callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async withCapturedOperationConnection({databaseConfiguration, name}, callback) {
+    const connection = await this.checkoutForConfiguration(databaseConfiguration, {name})
+    const id = connection.getIdSeq()
+    const owner = Symbol("captured-database-operation-owner")
+
+    return await this.asyncLocalStorage.run(id, async () => {
+      try {
+        return await callback(connection, owner)
+      } finally {
+        await this.checkin(connection)
+      }
+    })
+  }
+
   /**
    * Runs get current connection.
    * @returns {import("../drivers/base.js").default} - The current connection.
@@ -923,12 +974,12 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
   /**
    * Runs debug connection snapshots.
    * @param {number} now - Current timestamp.
-   * @returns {{connections: Array<Record<string, ?>>, seenConnections: Set<import("../drivers/base.js").default>}} - Connection snapshots and seen set.
+   * @returns {{connections: Array<Record<string, ReturnType<typeof JSON.parse>>>, seenConnections: Set<import("../drivers/base.js").default>}} - Connection snapshots and seen set.
    */
   debugConnectionSnapshots(now) {
     /**
      * Connections.
-     * @type {Array<Record<string, ?>>} */
+     * @type {Array<Record<string, ReturnType<typeof JSON.parse>>>} */
     const connections = []
     const seenConnections = new Set()
 
@@ -941,7 +992,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs add in use debug connection snapshots.
-   * @param {{connections: Array<Record<string, ?>>, now: number, seenConnections: Set<import("../drivers/base.js").default>}} args - Snapshot collection state.
+   * @param {{connections: Array<Record<string, ReturnType<typeof JSON.parse>>>, now: number, seenConnections: Set<import("../drivers/base.js").default>}} args - Snapshot collection state.
    * @returns {void}
    */
   addInUseDebugConnectionSnapshots({connections, now, seenConnections}) {
@@ -957,7 +1008,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs add idle debug connection snapshots.
-   * @param {{connections: Array<Record<string, ?>>, now: number, seenConnections: Set<import("../drivers/base.js").default>}} args - Snapshot collection state.
+   * @param {{connections: Array<Record<string, ReturnType<typeof JSON.parse>>>, now: number, seenConnections: Set<import("../drivers/base.js").default>}} args - Snapshot collection state.
    * @returns {void}
    */
   addIdleDebugConnectionSnapshots({connections, now, seenConnections}) {
@@ -976,7 +1027,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs add fallback debug connection snapshots.
-   * @param {{connections: Array<Record<string, ?>>, seenConnections: Set<import("../drivers/base.js").default>}} args - Snapshot collection state.
+   * @param {{connections: Array<Record<string, ReturnType<typeof JSON.parse>>>, seenConnections: Set<import("../drivers/base.js").default>}} args - Snapshot collection state.
    * @returns {void}
    */
   addFallbackDebugConnectionSnapshots({connections, seenConnections}) {
@@ -986,7 +1037,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs add debug connection snapshot if unseen.
-   * @param {{connection: import("../drivers/base.js").default | undefined, connections: Array<Record<string, ?>>, reapable?: boolean, seenConnections: Set<import("../drivers/base.js").default>, state: string}} args - Snapshot collection state.
+   * @param {{connection: import("../drivers/base.js").default | undefined, connections: Array<Record<string, ReturnType<typeof JSON.parse>>>, reapable?: boolean, seenConnections: Set<import("../drivers/base.js").default>, state: string}} args - Snapshot collection state.
    * @returns {void}
    */
   addDebugConnectionSnapshotIfUnseen({connection, connections, reapable, seenConnections, state}) {
@@ -1083,7 +1134,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs valid idle timeout millis.
-   * @param {?} value - Candidate idle timeout value.
+   * @param {ReturnType<typeof JSON.parse>} value - Candidate idle timeout value.
    * @returns {value is number} - Whether the value is a valid idle timeout.
    */
   validIdleTimeoutMillis(value) {

package/build/database/pool/base-methods-forward.js

@@ -29,12 +29,12 @@ export default function baseMethodsForward(PoolBase) {
     "updateSql"
   ]
 
-  const prototype = /** @type {Record<string, (...args: Array<?>) => ?>} */ (/** @type {?} */ (PoolBase.prototype))
+  const prototype = /** @type {Record<string, (...args: Array<ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>>} */ (/** @type {ReturnType<typeof JSON.parse>} */ (PoolBase.prototype))
 
   for (const forwardMethod of forwardMethods) {
     prototype[forwardMethod] = function(...args) {
       const connection = this.getCurrentConnection()
-      const connectionRecord = /** @type {Record<string, (...args: Array<?>) => ?>} */ (/** @type {?} */ (connection))
+      const connectionRecord = /** @type {Record<string, (...args: Array<ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>>} */ (/** @type {ReturnType<typeof JSON.parse>} */ (connection))
       const connectionMethod = connectionRecord[forwardMethod]
 
       if (!connectionMethod) throw new Error(`${forwardMethod} isn't defined on driver`)

package/build/database/pool/base.js

@@ -14,6 +14,12 @@ import baseMethodsForward from "./base-methods-forward.js"
  * @typedef {object} ConnectionCheckoutOptions
  * @property {string} [name] - Human-readable name for the checked-out connection.
  */
+/**
+ * CapturedConnectionOptions type.
+ * @typedef {object} CapturedConnectionOptions
+ * @property {import("../../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Resolved physical database configuration captured by the caller.
+ * @property {string} [name] - Human-readable name for the checked-out connection.
+ */
 /**
  * DatabasePoolPendingCheckoutDebugSnapshot type.
  * @typedef {object} DatabasePoolPendingCheckoutDebugSnapshot
@@ -29,8 +35,8 @@ import baseMethodsForward from "./base-methods-forward.js"
 /**
  * DatabasePoolDebugSnapshot type.
  * @typedef {object} DatabasePoolDebugSnapshot
- * @property {Record<string, ?>} configuration - Sanitized resolved database configuration.
- * @property {Array<Record<string, ?>>} connections - Live connection snapshots.
+ * @property {Record<string, ReturnType<typeof JSON.parse>>} configuration - Sanitized resolved database configuration.
+ * @property {Array<Record<string, ReturnType<typeof JSON.parse>>>} connections - Live connection snapshots.
  * @property {number} connectionsBeingSpawned - Number of in-progress connection spawns.
  * @property {number} idleCount - Number of idle connections.
  * @property {string} identifier - Database identifier.
@@ -50,7 +56,7 @@ const shared = {
 
 /**
  * Runs stable stringify.
- * @param {?} value - Value to stringify.
+ * @param {ReturnType<typeof JSON.parse>} value - Value to stringify.
  * @returns {string} - Stable JSON string.
  */
 function stableStringify(value) {
@@ -60,9 +66,9 @@ function stableStringify(value) {
 
   if (value && typeof value === "object") {
     const entries = Object
-      .keys(/** @type {Record<string, ?>} */ (value))
+      .keys(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (value))
       .sort()
-      .map((key) => `${JSON.stringify(key)}:${stableStringify(/** @type {Record<string, ?>} */ (value)[key])}`)
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (value)[key])}`)
 
     return `{${entries.join(",")}}`
   }
@@ -73,7 +79,7 @@ function stableStringify(value) {
 class VelociousDatabasePoolBase {
   /**
    * Without current connection context.
-   * @type {undefined | ((callback: () => ?) => ?)} */
+   * @type {undefined | ((callback: () => ReturnType<typeof JSON.parse>) => ReturnType<typeof JSON.parse>)} */
   _withoutCurrentConnectionContext = undefined
 
   /**
@@ -216,11 +222,10 @@ class VelociousDatabasePoolBase {
 
   /**
    * Runs get configuration reuse key.
+   * @param {import("../../configuration-types.js").DatabaseConfigurationType} [databaseConfiguration] - Resolved configuration to identify.
    * @returns {string} - Reuse key for the currently resolved database configuration.
    */
-  getConfigurationReuseKey() {
-    const databaseConfiguration = this.getConfiguration()
-
+  getConfigurationReuseKey(databaseConfiguration = this.getConfiguration()) {
     return stableStringify({
       database: databaseConfiguration.database,
       host: databaseConfiguration.host,
@@ -310,13 +315,24 @@ class VelociousDatabasePoolBase {
 
     this.logger.debug("spawnConnection", {identifier: this.identifier, databaseConfig})
 
-    const connection = await this.spawnConnectionWithConfiguration(databaseConfig)
+    return await this.spawnConnectionForConfiguration(databaseConfig)
+  }
 
+  /**
+   * Spawns a connection for an already-resolved physical database configuration.
+   * The reuse identity is derived only from that captured configuration.
+   * @param {import("../../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Captured resolved configuration.
+   * @returns {Promise<import("../drivers/base.js").default>} - Connected and identity-stamped driver.
+   */
+  async spawnConnectionForConfiguration(databaseConfiguration) {
+    const reuseKey = this.getConfigurationReuseKey(databaseConfiguration)
+    const connection = await this.spawnConnectionWithConfiguration(databaseConfiguration)
     const connectionWithPoolKey = /** @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
-    connectionWithPoolKey[POOL_CONFIGURATION_KEY] = this.getConfigurationReuseKey()
+
+    connectionWithPoolKey[POOL_CONFIGURATION_KEY] = reuseKey
     connection.setSchemaCacheInvalidator(() => {
       this.clearSchemaCache()
-      this.configuration.clearSchemaCachesForReuseKey(this.getConfigurationReuseKey())
+      this.configuration.clearSchemaCachesForReuseKey(reuseKey)
     })
 
     return connection
@@ -361,8 +377,8 @@ class VelociousDatabasePoolBase {
    * Runs with connection.
    * @template T
    * @abstract
-   * @param {ConnectionCheckoutOptions | function(import("../drivers/base.js").default) : Promise<T>} _optionsOrCallback - Checkout options or callback function.
-   * @param {function(import("../drivers/base.js").default) : Promise<T>} [_callback] - Callback function.
+   * @param {ConnectionCheckoutOptions | ((arg: import("../drivers/base.js").default) => Promise<T>)} _optionsOrCallback - Checkout options or callback function.
+   * @param {(arg: import("../drivers/base.js").default) => Promise<T>} [_callback] - Callback function.
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   withConnection(_optionsOrCallback, _callback) {
@@ -382,6 +398,21 @@ class VelociousDatabasePoolBase {
     return await this.withConnection(options, async (connection) => await callback(connection, owner))
   }
 
+  /**
+   * Runs work through a pool-owned checkout for an immutable, already-resolved
+   * physical configuration. Concrete pools must preserve their capacity,
+   * timeout, queue, debug, and closeAll ownership on this path.
+   * @template T
+   * @param {CapturedConnectionOptions} options - Captured checkout options.
+   * @param {(connection: import("../drivers/base.js").default, owner: symbol) => Promise<T>} callback - Operation callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async withCapturedOperationConnection(options, callback) {
+    void options
+    void callback
+    throw new Error("'withCapturedOperationConnection' not implemented")
+  }
+
   /**
    * Ensures a reusable connection exists for contexts where AsyncLocalStorage isn't set.
    * Default implementation just checks out a connection.
@@ -410,7 +441,7 @@ class VelociousDatabasePoolBase {
 
   /**
    * Runs debug configuration snapshot.
-   * @returns {Record<string, ?>} - Sanitized resolved database configuration.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Sanitized resolved database configuration.
    */
   debugConfigurationSnapshot() {
     const databaseConfig = this.getConfiguration()
@@ -434,8 +465,8 @@ class VelociousDatabasePoolBase {
   /**
    * Runs debug connection snapshot.
    * @param {import("../drivers/base.js").default} connection - Database connection.
-   * @param {Record<string, ?>} details - Extra diagnostic fields.
-   * @returns {Record<string, ?>} - Connection diagnostic snapshot.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} details - Extra diagnostic fields.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Connection diagnostic snapshot.
    */
   debugConnectionSnapshot(connection, details = {}) {
     const connectionWithPoolKey = /** @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)