velocious 1.0.618 → 1.0.620

package/README.md

@@ -259,7 +259,7 @@ npx velocious test:timing-manifest:merge --output tmp/test-timings.json \
 See [test profiling](docs/test-profiling.md) for lifecycle accounting, custom
 activity spans, schema, and privacy guarantees.
 
-Prefer waiting for a real signal or condition over sleeping a fixed duration. `waitForEvent(emitter, eventName, {timeoutMs, filter})` resolves the instant a matching event fires (a background job finishing, a model update, a websocket message) and rejects on timeout; for polling an arbitrary condition, use awaitery's `waitFor`.
+Prefer waiting for a real signal or condition over sleeping a fixed duration. `waitForEvent(emitter, eventName, {timeoutMs, filter})` resolves the instant a matching event fires (a background job finishing, a model update, a websocket message) and rejects on timeout; for polling an arbitrary condition, use awaitery's `waitFor`. The stable Velocious import remains `velocious/build/src/testing/test.js`; its generic `waitForEvent` primitive comes from `@velocious/testing`, while the keyed testing DSL and framework runner remain owned by Velocious.
 
 ```js
 import {waitForEvent} from "velocious/build/src/testing/test.js"
@@ -2162,7 +2162,9 @@ option; the default configuration keeps sequential `TRUNCATE TABLE` requests. Se
 
 Request tests share transaction-active, non-tenant database connections with their in-process HTTP handlers. Eligibility is evaluated when each request is dispatched, so a hook can start a transaction and issue a request in the same callback. This makes uncommitted setup visible to handlers while preserving rollback isolation. Without an active transaction, handlers use independent pooled connections, so concurrency and locking tests can opt out of transaction cleanup and exercise production-style connections. Shared connection state is scoped to the test lifecycle and cleared around each test. See [docs/testing-guidelines.md](docs/testing-guidelines.md#request-test-database-connections).
 
-Transactional tests also share active non-tenant connections with real forked, reusable pooled, and spawned background-job child runners through a per-attempt test-only loopback broker. Parent setup and child writes therefore occupy the same physical transaction and roll back together, including background-job persistence. Multiple configured databases route by identifier. Tenant-only databases remain excluded by default; a test can explicitly call `registerTransactionalTenant({databaseIdentifier, tenant})` from its attempt args to share one transaction with same-process paths resolving that exact physical tenant configuration. That registration remains active through `afterEach` and is revoked, rolled back, and released afterward. Emergency cleanup for a lifecycle hung beyond timeout grace revokes pending setup before it can publish stale state, bounds cleanup waits, and discards its physical tenant connection, so stale resumed work cannot use a driver recycled into a successor attempt. Tests using `{transaction: false, truncate: true}` retain ordinary independent physical connections for concurrency and locking coverage. See [docs/testing-guidelines.md](docs/testing-guidelines.md#in-process-test-database-connections).
+Transactional tests also share active non-tenant connections with real forked, reusable pooled, and spawned background-job child runners through a per-attempt test-only loopback broker. Parent setup and child writes therefore occupy the same physical transaction and roll back together, including background-job persistence. Backend harnesses can use [`TestTransactionSession`](docs/test-transaction-sessions.md) to propagate an ephemeral capability to already-running services and lazily enroll exact tenant physical identities. Tests using `{transaction: false, truncate: true}` retain ordinary independent connections for DDL, lock contention, independent commits, and genuine concurrency. See [docs/testing-guidelines.md](docs/testing-guidelines.md#request-test-database-connections).
+
+Multiple configured databases route by identifier. Tenant-only databases remain excluded by default; a test can explicitly call `registerTransactionalTenant({databaseIdentifier, tenant})` from its attempt args to share one transaction with same-process paths resolving that exact physical tenant configuration. That registration remains active through `afterEach` and is revoked, rolled back, and released afterward. Emergency cleanup for a lifecycle hung beyond timeout grace revokes pending setup before it can publish stale state, bounds cleanup waits, and discards its physical tenant connection, so stale resumed work cannot use a driver recycled into a successor attempt. See [docs/testing-guidelines.md](docs/testing-guidelines.md#in-process-test-database-connections).
 
 Warm pooled children receive the active broker capability per job, discard retained proxy state when the capability changes, and fail closed if a transactional dispatch lacks coordinates. Child transaction/savepoint work holds a FIFO lease on the parent physical connection until the matching root release or rollback.
 

package/build/configuration.js

@@ -3475,7 +3475,7 @@ export default class VelociousConfiguration {
    * @returns {T} - Callback result.
    */
   withoutCurrentConnectionContexts(callback) {
-    let runCallback = callback
+    let runCallback = () => this.getEnvironmentHandler().runWithoutSharedTransactionCoordinatorOwners(callback)
 
     for (const pool of Object.values(this.databasePools)) {
       if (!pool) continue

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

@@ -58,6 +58,12 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
   /** Attempt-owned shared connections keyed by resolved physical configuration. */
   _testSharedConnectionsByReuseKey = new Map()
 
+  /**
+   * Concurrent providers selected by live async join context.
+   * @type {Map<import("./base.js").TestSharedConnectionRegistration, {matches: () => boolean, provider: () => import("../drivers/base.js").default | undefined}>}
+   */
+  _testSharedConnectionProviders = new Map()
+
   /**
    * Connections.
    * @type {import("../drivers/base.js").default[]} */
@@ -176,15 +182,16 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
   /**
    * Spawns and times a physical connection without retaining its configuration.
    * @param {import("../../configuration-types.js").DatabaseConfigurationType} config - Resolved database configuration.
+   * @param {string} [reuseKey] - Exact resolved physical identity.
    * @returns {Promise<import("../drivers/base.js").default>} - Connected driver.
    */
-  async spawnConnectionWithConfiguration(config) {
+  async spawnConnectionWithConfiguration(config, reuseKey) {
     const startedAt = this.nowMs()
     const profileContext = currentTestProfileContext(this.configuration)
     let failed = true
 
     try {
-      const connection = await super.spawnConnectionWithConfiguration(config)
+      const connection = await super.spawnConnectionWithConfiguration(config, reuseKey)
 
       failed = false
       const liveConnectionCount = this.liveConnectionCount() - this.connectionsBeingSpawned + 1
@@ -544,7 +551,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     try {
       const environmentHandler = this.configuration.getEnvironmentHandler()
       const connection = await environmentHandler.runWithTestProfileContext(profileContext, async () => {
-        return await this.spawnConnectionWithConfiguration(databaseConfig)
+        return await this.spawnConnectionWithConfiguration(databaseConfig, this.getConfigurationReuseKey(databaseConfig))
       })
 
       this.stampConnectionForConfigurationReuseKey(connection, reuseKey)
@@ -1113,6 +1120,17 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     return registration
   }
 
+  /**
+   * Registers a provider selected by the current live async join context.
+   * @param {{matches: () => boolean, provider: () => import("../drivers/base.js").default | undefined}} args - Context selector and provider.
+   * @returns {import("./base.js").TestSharedConnectionRegistration} - Opaque scoped registration handle.
+   */
+  registerTestSharedConnectionProvider(args) {
+    const registration = {owner: Symbol("test-shared-connection-context-provider")}
+    this._testSharedConnectionProviders.set(registration, args)
+    return registration
+  }
+
   /**
    * Registers an attempt-owned connection for exactly one physical configuration.
    * @param {import("../drivers/base.js").default} connection - Attempt-owned connection.
@@ -1132,6 +1150,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @param {import("./base.js").TestSharedConnectionRegistration} [registration] - Opaque registration handle to clear conditionally.
    * @returns {void} */
   clearTestSharedConnection(registration) {
+    if (registration && this._testSharedConnectionProviders.delete(registration)) return
     if (registration) {
       for (const [reuseKey, entry] of this._testSharedConnectionsByReuseKey) {
         if (entry.registration !== registration) continue
@@ -1141,7 +1160,6 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     } else {
       this._testSharedConnectionsByReuseKey.clear()
     }
-
     if (registration && registration !== this._testSharedConnectionRegistration) return
 
     this._testSharedConnection = undefined
@@ -1187,11 +1205,13 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {import("../drivers/base.js").default | undefined} - Shared connection.
    */
   testSharedConnection() {
+    for (const {matches, provider} of this._testSharedConnectionProviders.values()) {
+      if (matches()) return provider()
+    }
     const reuseKey = this.getConfigurationReuseKey()
     const physicalRegistration = this._testSharedConnectionsByReuseKey.get(reuseKey)
 
     if (physicalRegistration) return physicalRegistration.connection
-
     return this._testSharedConnectionProvider
       ? this._testSharedConnectionProvider()
       : this._testSharedConnection

package/build/database/pool/base.js

@@ -185,6 +185,16 @@ class VelociousDatabasePoolBase {
     return undefined
   }
 
+  /**
+   * Registers a test shared connection selected by the caller's live async context.
+   * Base pools that do not track async context ignore it.
+   * @param {{matches: () => boolean, provider: () => import("../drivers/base.js").default | undefined}} _args - Context selector and connection provider.
+   * @returns {TestSharedConnectionRegistration | undefined} - Opaque scoped registration handle.
+   */
+  registerTestSharedConnectionProvider(_args) {
+    return undefined
+  }
+
   /**
    * Registers a test connection for one resolved physical database configuration.
    * @param {import("../drivers/base.js").default} _connection - Attempt-owned connection.
@@ -357,7 +367,7 @@ class VelociousDatabasePoolBase {
    */
   async spawnConnectionForConfiguration(databaseConfiguration) {
     const reuseKey = this.getConfigurationReuseKey(databaseConfiguration)
-    const connection = await this.spawnConnectionWithConfiguration(databaseConfiguration)
+    const connection = await this.spawnConnectionWithConfiguration(databaseConfiguration, reuseKey)
 
     this.stampConnectionForConfigurationReuseKey(connection, reuseKey)
 
@@ -388,21 +398,21 @@ class VelociousDatabasePoolBase {
   /**
    * Runs spawn connection with configuration.
    * @param {import("../../configuration-types.js").DatabaseConfigurationType} config - Configuration object.
+   * @param {string} [reuseKey] - Exact resolved physical identity.
    * @returns {Promise<import("../drivers/base.js").default>} - Resolves with the spawn connection with configuration.
    */
-  async spawnConnectionWithConfiguration(config) {
+  async spawnConnectionWithConfiguration(config, reuseKey) {
     const DriverClass = config.driver || this.driverClass
 
     if (!DriverClass) throw new Error("No driver class set in database pool or in given config")
 
-    const sharedConnection = config.tenantOnly
-      ? undefined
-      : await this.configuration.getEnvironmentHandler().createTestSharedTransactionConnection({
-        DriverClass,
-        config,
-        configuration: this.configuration,
-        databaseIdentifier: this.identifier
-      })
+    const sharedConnection = await this.configuration.getEnvironmentHandler().createTestSharedTransactionConnection({
+      DriverClass,
+      config,
+      configuration: this.configuration,
+      databaseIdentifier: this.identifier,
+      reuseKey
+    })
     const connection = sharedConnection || new DriverClass(config, this.configuration)
 
     try {

package/build/environment-handlers/base.js

@@ -31,7 +31,7 @@ export default class VelociousEnvironmentHandlerBase {
   /**
    * Node test runtimes may replace a physical child connection with a broker
    * proxy. Other environments never participate in this test-only protocol.
-   * @param {{DriverClass: typeof import("../database/drivers/base.js").default, config: import("../configuration-types.js").DatabaseConfigurationType, configuration: import("../configuration.js").default, databaseIdentifier: string}} _args - Connection details.
+   * @param {{DriverClass: typeof import("../database/drivers/base.js").default, config: import("../configuration-types.js").DatabaseConfigurationType, configuration: import("../configuration.js").default, databaseIdentifier: string, reuseKey?: string}} _args - Connection details.
    * @returns {Promise<import("../database/drivers/base.js").default | undefined>} - Optional proxy.
    */
   async createTestSharedTransactionConnection(_args) { return undefined }
@@ -54,6 +54,14 @@ export default class VelociousEnvironmentHandlerBase {
    */
   runWithSharedTransactionCoordinatorOwner(_connection, _owner, callback) { return callback() }
 
+  /**
+   * Runs work without inherited shared-transaction coordinator ownership.
+   * @template T
+   * @param {() => T} callback - Detached work.
+   * @returns {T} - Callback result.
+   */
+  runWithoutSharedTransactionCoordinatorOwners(callback) { return callback() }
+
   /**
    * Runs work with test-profile attribution. Runtimes without async-context
    * storage execute the callback without installing ambient attribution.

package/build/environment-handlers/node.js

@@ -40,7 +40,7 @@ import InitializerFromRequireContext from "../database/initializer-from-require-
 import toImportSpecifier from "../utils/to-import-specifier.js"
 import {validateTimeZone} from "../time-zone.js"
 import AttachmentPathSource from "./node/attachment-path-source.js"
-import { createSharedTransactionProxyDriver, sharedTransactionBrokerConfig } from "../testing/shared-transaction-proxy-driver.js"
+import { automaticSharedTransactionBrokerOmits, createSharedTransactionProxyDriver, sharedTransactionBrokerConfig } from "../testing/shared-transaction-proxy-driver.js"
 
 /**
  * Defines this typedef.
@@ -95,6 +95,8 @@ export default class VelociousEnvironmentHandlerNode extends Base{
    * @returns {typeof import("../database/pool/base.js").default} - Pool type for this context.
    */
   resolveTestSharedTransactionPoolType({configuredPoolType, databaseIdentifier}) {
+    const databaseConfiguration = this.getConfiguration().getDatabaseIdentifier(databaseIdentifier)
+    if (databaseConfiguration.tenantOnly && automaticSharedTransactionBrokerOmits(databaseIdentifier)) return configuredPoolType
     if (!sharedTransactionBrokerConfig(databaseIdentifier)) return configuredPoolType
 
     return AsyncTrackedMultiConnectionPool
@@ -102,13 +104,17 @@ export default class VelociousEnvironmentHandlerNode extends Base{
 
   /**
    * Creates a test-only child proxy when TestRunner supplied an active broker.
-   * @param {{DriverClass: typeof import("../database/drivers/base.js").default, config: import("../configuration-types.js").DatabaseConfigurationType, configuration: import("../configuration.js").default, databaseIdentifier: string}} args - Connection details.
+   * @param {{DriverClass: typeof import("../database/drivers/base.js").default, config: import("../configuration-types.js").DatabaseConfigurationType, configuration: import("../configuration.js").default, databaseIdentifier: string, reuseKey?: string}} args - Connection details.
    * @returns {Promise<import("../database/drivers/base.js").default | undefined>} - Optional proxy.
    */
-  async createTestSharedTransactionConnection({DriverClass, config, configuration, databaseIdentifier}) {
+  async createTestSharedTransactionConnection({DriverClass, config, configuration, databaseIdentifier, reuseKey}) {
+    if (config.tenantOnly && automaticSharedTransactionBrokerOmits(databaseIdentifier)) return undefined
     const brokerConfig = sharedTransactionBrokerConfig(databaseIdentifier)
     if (!brokerConfig) return undefined
-    return createSharedTransactionProxyDriver(DriverClass, config, configuration, databaseIdentifier, brokerConfig)
+    return createSharedTransactionProxyDriver(DriverClass, config, configuration, databaseIdentifier, {
+      ...brokerConfig,
+      reuseKey: brokerConfig.allowDynamicIdentities ? reuseKey : undefined
+    })
   }
 
   /**
@@ -148,6 +154,18 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     return this._sharedTransactionCoordinatorAsyncLocalStorage.run(owners, callback)
   }
 
+  /**
+   * Runs work without inherited shared-transaction coordinator ownership.
+   * @template T
+   * @param {() => T} callback - Detached work.
+   * @returns {T} - Callback result.
+   */
+  runWithoutSharedTransactionCoordinatorOwners(callback) {
+    if (!this._sharedTransactionCoordinatorAsyncLocalStorage) return callback()
+
+    return this._sharedTransactionCoordinatorAsyncLocalStorage.run(new Map(), callback)
+  }
+
   /**
    * Runs work with async-safe test profile attribution.
    * @template T