velocious 1.0.618 → 1.0.620

package/src/testing/shared-transaction-broker.js

@@ -80,15 +80,9 @@ export default class SharedTransactionBroker extends EventEmitter {
     /** @type {Map<object, symbol>} */
     this.connectionCoordinatorOwners = new Map()
     for (const connection of new Set(Object.values(connections))) {
-      /**
-       * Serializes parent operations with child broker traffic.
-       * @param {() => Promise<unknown>} callback - Parent operation.
-       * @returns {Promise<unknown>} - Operation result.
-       */
-      const coordinator = async (callback) => await this.serialize(this.connectionState(connection), callback)
-      this.connectionCoordinators.set(connection, coordinator)
-      this.connectionCoordinatorOwners.set(connection, setSharedTransactionCoordinator(connection, coordinator))
+      this.installConnectionCoordinator(connection)
     }
+    this.physicalConnections = new Map()
     this.httpServer = createServer()
     this.websocketServer = new WebSocketServer({server: this.httpServer, maxPayload: 16 * 1024 * 1024})
     this.websocketServer.on("connection", (socket) => {
@@ -101,6 +95,37 @@ export default class SharedTransactionBroker extends EventEmitter {
     })
   }
 
+  /**
+   * Installs serialization ownership for a newly enrolled physical connection.
+   * @param {object} connection - Parent-owned physical connection.
+   * @returns {void}
+   */
+  installConnectionCoordinator(connection) {
+    if (this.connectionCoordinators.has(connection)) return
+    /**
+     * Serializes parent operations with child broker traffic.
+     * @param {() => Promise<unknown>} callback - Parent operation.
+     * @returns {Promise<unknown>} - Operation result.
+     */
+    const coordinator = async (callback) => await this.serialize(this.connectionState(connection), callback)
+    this.connectionCoordinators.set(connection, coordinator)
+    this.connectionCoordinatorOwners.set(connection, setSharedTransactionCoordinator(connection, coordinator))
+  }
+
+  /**
+   * Enrolls one exact physical database identity in this capability's rollback set.
+   * @param {{connection: object, databaseIdentifier: string, reuseKey: string}} args - Physical connection identity.
+   * @returns {void}
+   */
+  enrollConnection({connection, databaseIdentifier, reuseKey}) {
+    if (!this.accepting) throw new Error("Shared transaction broker capability has been revoked")
+    const identity = `${databaseIdentifier}\0${reuseKey}`
+    const existing = this.physicalConnections.get(identity)
+    if (existing && existing !== connection) throw new Error(`Shared transaction physical connection identity is already enrolled: ${databaseIdentifier}`)
+    this.installConnectionCoordinator(connection)
+    this.physicalConnections.set(identity, connection)
+  }
+
   /**
    * Starts a broker on an ephemeral loopback port.
    * @param {{connections: Record<string, object>}} args - Parent-owned physical connections.
@@ -140,18 +165,22 @@ export default class SharedTransactionBroker extends EventEmitter {
   async handleRequest(socket, serialized) {
     let requestId = 0
     try {
-      const request = /** @type {{requestId: number, capability: string, databaseIdentifier: string, method: string, args: import("./shared-transaction-codec.js").EncodedBrokerValue}} */ (JSON.parse(serialized))
+      const request = /** @type {{requestId: number, capability: string, databaseIdentifier: string, reuseKey?: string, method: string, args: import("./shared-transaction-codec.js").EncodedBrokerValue}} */ (JSON.parse(serialized))
       requestId = request.requestId
       if (!this.accepting) throw new Error("Shared transaction broker capability has been revoked")
       if (!capabilityMatches(request.capability, this.secret)) throw new Error("Unknown shared transaction broker capability")
-      const connection = this.connections[request.databaseIdentifier]
-      if (!connection) throw new Error(`Unknown shared transaction database identifier: ${request.databaseIdentifier}`)
+      const connection = request.reuseKey
+        ? this.physicalConnections.get(`${request.databaseIdentifier}\0${request.reuseKey}`)
+        : this.connections[request.databaseIdentifier]
+      if (!connection) {
+        if (request.reuseKey) throw new Error(`Unenrolled physical connection identity: ${request.databaseIdentifier}`)
+        throw new Error(`Unknown shared transaction database identifier: ${request.databaseIdentifier}`)
+      }
       if (!ALLOWED_METHODS.has(request.method)) throw new Error(`Unsupported shared transaction broker method: ${request.method}`)
       const args = decodeBrokerValue(request.args)
       if (!Array.isArray(args)) throw new TypeError("Shared transaction broker arguments must be an array")
       this.emit("work-queued", {connection, databaseIdentifier: request.databaseIdentifier, method: request.method})
       const result = await this.runConnectionRequest({connection, method: request.method, savePointName: typeof args[0] === "string" ? args[0] : undefined, socket}, async () => {
-        if (!this.accepting) throw new Error("Shared transaction broker capability has been revoked")
         if (request.method === "rootTransactionRollback") {
           await this.rollbackRootSavePoint(connection, /** @type {string} */ (args[0]))
           return undefined
@@ -258,10 +287,11 @@ export default class SharedTransactionBroker extends EventEmitter {
 
     state.queue = previous.then(async () => {
       try {
-        if (!this.accepting || socket.readyState !== socket.OPEN) throw new Error("Shared transaction broker root transaction session closed before lease acquisition")
+        if (socket.readyState !== socket.OPEN) throw new Error("Shared transaction broker root transaction session closed before lease acquisition")
         const result = await callback()
         state.lease = {operations: Promise.resolve(), release, savePointName, socket}
         resolveStarted(result)
+        if (!this.accepting) await this.scheduleSessionCleanup(socket)
         await held
       } catch (error) {
         state.rootSessions.delete(socket)
@@ -418,17 +448,29 @@ export default class SharedTransactionBroker extends EventEmitter {
     return await this.closePromise
   }
 
+  /** Revokes admission without interrupting already accepted work. */
+  revoke() {
+    if (!this.accepting) return
+    this.accepting = false
+    this.secret = randomBytes(32).toString("base64url")
+  }
+
+  /** Drains all work accepted before capability revocation. */
+  async drain() {
+    if (this.accepting) throw new Error("Shared transaction broker must be revoked before drain")
+    await Promise.all(Array.from(this.connectionStates.values()).map((state) => state.queue))
+  }
+
   /**
    * Performs deterministic transport shutdown and reports cleanup failures last.
    * @returns {Promise<void>} - Resolves after shutdown or rejects with cleanup errors.
    */
   async closeTransport() {
-    this.accepting = false
-    this.secret = randomBytes(32).toString("base64url")
+    this.revoke()
     const closingSessions = Array.from(this.sessions)
     await Promise.all(closingSessions.map(async (socket) => await this.scheduleSessionCleanup(socket)))
+    await this.drain()
     for (const socket of closingSessions) socket.close(1001, "Shared transaction broker closed")
-    await Promise.allSettled(Array.from(this.connectionStates.values()).map((state) => state.queue))
     await new Promise((resolve) => this.websocketServer.close(() => resolve(undefined)))
     await new Promise((resolve) => this.httpServer.close(() => resolve(undefined)))
     await Promise.all(Array.from(this.sessionCleanup.values()))

package/src/testing/shared-transaction-connection-coordinator.js

@@ -1,18 +1,30 @@
 // @ts-check
 
-/** @typedef {{coordinator: (callback: () => Promise<unknown>) => Promise<unknown>, ownedQueue: Promise<void>, owner: symbol}} CoordinatorRegistration */
+/** @typedef {{coordinator: (callback: () => Promise<unknown>) => Promise<unknown>, ownedQueue: Promise<void>, owner: symbol, reentrantOwners: Set<symbol>, rootOwners: Set<symbol>}} CoordinatorRegistration */
 
 /** @type {WeakMap<object, CoordinatorRegistration>} */
 const coordinators = new WeakMap()
+/** @type {WeakMap<object, CoordinatorRegistration>} */
+const connectionRegistrations = new WeakMap()
+
+/**
+ * Runs work directly when only the connection-local queue remains registered.
+ * @param {() => Promise<unknown>} callback - Serialized operation.
+ * @returns {Promise<unknown>} - Operation result.
+ */
+async function inactiveCoordinator(callback) {
+  return await callback()
+}
 
 /**
  * Serializes sibling work that inherited one coordinator owner without re-entering the broker queue.
  * @template T
+ * @param {import("../database/drivers/base.js").default} connection - Parent physical connection.
  * @param {CoordinatorRegistration} registration - Physical connection registration.
  * @param {() => Promise<T>} callback - Owned operation.
  * @returns {Promise<T>} - Operation result.
  */
-async function coordinateOwnedSharedTransactionConnection(registration, callback) {
+async function coordinateOwnedSharedTransactionConnection(connection, registration, callback) {
   const previous = registration.ownedQueue
   /**
    * Releases the next owned sibling operation.
@@ -22,13 +34,54 @@ async function coordinateOwnedSharedTransactionConnection(registration, callback
 
   registration.ownedQueue = new Promise((resolve) => { release = resolve })
   await previous
+  const operationOwner = Symbol("shared-transaction-owned-operation")
+  const environmentHandler = connection.configuration.getEnvironmentHandler()
+
+  registration.reentrantOwners.add(operationOwner)
   try {
-    return await callback()
+    return await environmentHandler.runWithSharedTransactionCoordinatorOwner(connection, operationOwner, callback)
   } finally {
+    registration.reentrantOwners.delete(operationOwner)
     release()
   }
 }
 
+/**
+ * Drains all inherited operations admitted before the root owner is revoked.
+ * @param {CoordinatorRegistration} registration - Physical connection registration.
+ * @returns {Promise<void>} - Resolves when the owned queue stops advancing.
+ */
+async function drainOwnedSharedTransactionConnections(registration) {
+  let tail
+
+  do {
+    tail = registration.ownedQueue
+    await tail
+  } while (tail !== registration.ownedQueue)
+}
+
+/**
+ * Runs one broker-serialized root while tracking and draining its inherited work.
+ * @template T
+ * @param {import("../database/drivers/base.js").default} connection - Parent physical connection.
+ * @param {CoordinatorRegistration} registration - Physical connection registration.
+ * @param {() => Promise<T>} callback - Root operation.
+ * @returns {Promise<T>} - Operation result.
+ */
+async function coordinateRootSharedTransactionConnection(connection, registration, callback) {
+  await drainOwnedSharedTransactionConnections(registration)
+  const rootOwner = Symbol("shared-transaction-root-operation")
+  const environmentHandler = connection.configuration.getEnvironmentHandler()
+
+  registration.rootOwners.add(rootOwner)
+  try {
+    return await environmentHandler.runWithSharedTransactionCoordinatorOwner(connection, rootOwner, callback)
+  } finally {
+    await drainOwnedSharedTransactionConnections(registration)
+    registration.rootOwners.delete(rootOwner)
+  }
+}
+
 /**
  * Registers test-only serialization owned by the active broker.
  * @param {object} connection - Parent physical connection.
@@ -37,8 +90,17 @@ async function coordinateOwnedSharedTransactionConnection(registration, callback
  */
 export function setSharedTransactionCoordinator(connection, coordinator) {
   const owner = Symbol("shared-transaction-coordinator")
+  let registration = connectionRegistrations.get(connection)
+
+  if (registration) {
+    registration.coordinator = coordinator
+    registration.owner = owner
+  } else {
+    registration = {coordinator, ownedQueue: Promise.resolve(), owner, reentrantOwners: new Set(), rootOwners: new Set()}
+    connectionRegistrations.set(connection, registration)
+  }
 
-  coordinators.set(connection, {coordinator, ownedQueue: Promise.resolve(), owner})
+  coordinators.set(connection, registration)
   return owner
 }
 
@@ -49,7 +111,12 @@ export function setSharedTransactionCoordinator(connection, coordinator) {
  * @returns {void}
  */
 export function clearSharedTransactionCoordinator(connection, coordinator) {
-  if (coordinators.get(connection)?.coordinator === coordinator) coordinators.delete(connection)
+  const registration = coordinators.get(connection)
+
+  if (registration?.coordinator === coordinator) {
+    coordinators.delete(connection)
+    registration.coordinator = inactiveCoordinator
+  }
 }
 
 /**
@@ -61,18 +128,24 @@ export function clearSharedTransactionCoordinator(connection, coordinator) {
  * @returns {Promise<T>} - Operation result.
  */
 export async function coordinateSharedTransactionConnection(connection, callback, operationOwner) {
-  const registration = coordinators.get(connection)
+  const activeRegistration = coordinators.get(connection)
+  const registration = activeRegistration || connectionRegistrations.get(connection)
 
   if (!registration) return await callback()
-  if (operationOwner === registration.owner) return await callback()
 
   const environmentHandler = connection.configuration.getEnvironmentHandler()
+  const currentOwner = environmentHandler.getSharedTransactionCoordinatorOwner(connection)
 
-  if (environmentHandler.getSharedTransactionCoordinatorOwner(connection) === registration.owner) {
-    return await coordinateOwnedSharedTransactionConnection(registration, callback)
+  if (currentOwner && registration.reentrantOwners.has(currentOwner)) return await callback()
+  if (currentOwner && registration.rootOwners.has(currentOwner)) {
+    return await coordinateOwnedSharedTransactionConnection(connection, registration, callback)
+  }
+  if (!activeRegistration) return await coordinateOwnedSharedTransactionConnection(connection, registration, callback)
+  if (operationOwner === registration.owner) {
+    return await coordinateRootSharedTransactionConnection(connection, registration, callback)
   }
 
   return /** @type {T} */ (await registration.coordinator(async () => {
-    return await environmentHandler.runWithSharedTransactionCoordinatorOwner(connection, registration.owner, callback)
+    return await coordinateRootSharedTransactionConnection(connection, registration, callback)
   }))
 }

package/src/testing/shared-transaction-proxy-driver.js

@@ -1,4 +1,4 @@
-/** @typedef {{address?: string, capability?: string, databaseIdentifiers?: string[], expected: boolean}} SharedTransactionBrokerJobConfig */
+/** @typedef {{address?: string, allowDynamicIdentities?: boolean, capability?: string, databaseIdentifiers?: string[], expected: boolean}} SharedTransactionBrokerJobConfig */
 
 // @ts-check
 
@@ -11,6 +11,19 @@ export const BACKGROUND_JOB_CHILD_ENV = "VELOCIOUS_BACKGROUND_JOB_CHILD"
 /** @type {AsyncLocalStorage<SharedTransactionBrokerJobConfig>} */
 const pooledJobBrokerConfig = new AsyncLocalStorage()
 
+/**
+ * Returns the active live broker configuration without validating one database route.
+ * @returns {SharedTransactionBrokerJobConfig | undefined} - Active live or child configuration.
+ */
+function activeSharedTransactionBrokerConfig() {
+  const contextualConfig = pooledJobBrokerConfig.getStore()
+  if (contextualConfig) return contextualConfig
+  if (process.env[BACKGROUND_JOB_CHILD_ENV] !== "1") return undefined
+  const serialized = process.env[SHARED_TRANSACTION_BROKER_ENV]
+  if (!serialized) return undefined
+  return JSON.parse(Buffer.from(serialized, "base64url").toString("utf8"))
+}
+
 /**
  * Runs one pooled job with dispatch-time broker configuration.
  * @template T
@@ -22,6 +35,34 @@ export function runWithSharedTransactionBrokerConfig(config, callback) {
   return pooledJobBrokerConfig.run(config, callback)
 }
 
+/**
+ * Checks whether the current live join selects one exact session capability.
+ * @param {{address: string, capability: string}} identity - Session control-message identity.
+ * @returns {boolean} - Whether this async context belongs to that session.
+ */
+export function sharedTransactionBrokerContextMatches(identity) {
+  const config = pooledJobBrokerConfig.getStore()
+  return config?.expected === true && config.address === identity.address && config.capability === identity.capability
+}
+
+/**
+ * Preserves legacy real tenant connections omitted by automatic TestRunner mode.
+ * Explicit dynamic sessions never permit this fallback.
+ * @param {string} databaseIdentifier - Logical database identifier.
+ * @returns {boolean} - Whether an omitted automatic route stays independent.
+ */
+export function automaticSharedTransactionBrokerOmits(databaseIdentifier) {
+  const config = activeSharedTransactionBrokerConfig()
+  return Boolean(
+    config?.expected === true &&
+    !config.allowDynamicIdentities &&
+    typeof config.address === "string" &&
+    typeof config.capability === "string" &&
+    Array.isArray(config.databaseIdentifiers) &&
+    !config.databaseIdentifiers.includes(databaseIdentifier)
+  )
+}
+
 /**
  * Escapes a PostgreSQL literal without requiring a live child connection.
  * @param {ReturnType<typeof JSON.parse>} value - PostgreSQL literal value.
@@ -49,24 +90,19 @@ function pgEscapeLiteral(value) {
  * Parses the test-runner-owned child transport configuration when this logical
  * database is registered for the active attempt.
  * @param {string} databaseIdentifier - Logical database identifier.
- * @returns {{address: string, capability: string} | undefined} - Broker coordinates.
+ * @returns {{address: string, allowDynamicIdentities?: boolean, capability: string} | undefined} - Broker coordinates.
  */
 export function sharedTransactionBrokerConfig(databaseIdentifier) {
-  const contextualConfig = pooledJobBrokerConfig.getStore()
-  if (contextualConfig) return validatedBrokerConfig(contextualConfig, databaseIdentifier)
-  if (process.env[BACKGROUND_JOB_CHILD_ENV] !== "1") return undefined
-
-  const serialized = process.env[SHARED_TRANSACTION_BROKER_ENV]
-  if (!serialized) return undefined
-
-  return validatedBrokerConfig(JSON.parse(Buffer.from(serialized, "base64url").toString("utf8")), databaseIdentifier)
+  const config = activeSharedTransactionBrokerConfig()
+  if (!config) return undefined
+  return validatedBrokerConfig(config, databaseIdentifier)
 }
 
 /**
  * Validates dispatch-time broker configuration and fails closed when expected.
  * @param {SharedTransactionBrokerJobConfig} config - Candidate configuration.
  * @param {string} databaseIdentifier - Logical database identifier.
- * @returns {{address: string, capability: string} | undefined} - Broker coordinates.
+ * @returns {{address: string, allowDynamicIdentities?: boolean, capability: string} | undefined} - Broker coordinates.
  */
 function validatedBrokerConfig(config, databaseIdentifier) {
   if (config.expected && (!config.address || !config.capability || !config.databaseIdentifiers)) {
@@ -76,10 +112,13 @@ function validatedBrokerConfig(config, databaseIdentifier) {
   if (typeof config.address !== "string" || typeof config.capability !== "string" || !Array.isArray(config.databaseIdentifiers)) {
     throw new Error("Invalid shared transaction broker child configuration")
   }
-  if (!config.databaseIdentifiers.includes(databaseIdentifier)) {
+  if (!config.allowDynamicIdentities && !config.databaseIdentifiers.includes(databaseIdentifier)) {
     throw new Error(`Transactional pooled job expected broker database identifier: ${databaseIdentifier}`)
   }
 
+  if (config.allowDynamicIdentities) {
+    return {address: config.address, allowDynamicIdentities: true, capability: config.capability}
+  }
   return {address: config.address, capability: config.capability}
 }
 
@@ -90,7 +129,7 @@ function validatedBrokerConfig(config, databaseIdentifier) {
  * @param {import("../configuration-types.js").DatabaseConfigurationType} config - Database configuration.
  * @param {import("../configuration.js").default} configuration - Child configuration.
  * @param {string} databaseIdentifier - Logical identifier.
- * @param {{address: string, capability: string}} brokerConfig - Broker coordinates.
+ * @param {{address: string, capability: string, reuseKey?: string}} brokerConfig - Broker coordinates.
  * @returns {import("../database/drivers/base.js").default} - Unconnected physical proxy.
  */
 export function createSharedTransactionProxyDriver(DriverClass, config, configuration, databaseIdentifier, brokerConfig) {

package/src/testing/test-transaction-session.js

@@ -0,0 +1,240 @@
+// @ts-check
+
+import SharedTransactionBroker from "./shared-transaction-broker.js"
+import { runWithSharedTransactionBrokerConfig, sharedTransactionBrokerContextMatches } from "./shared-transaction-proxy-driver.js"
+
+/** @typedef {{connection: import("../database/drivers/base.js").default, databaseIdentifier: string, release: () => Promise<void>, reuseKey: string}} Enrollment */
+
+/**
+ * Backend-owned, capability-scoped transaction set for long-lived test services.
+ * Join coordinates are intentionally obtainable only as a live control message.
+ */
+export default class TestTransactionSession {
+  /**
+   * Creates an unstarted transaction session.
+   * @param {import("../configuration.js").default} [configuration] - Backend configuration owning enrolled pools.
+   */
+  constructor(configuration) {
+    this.configuration = configuration
+    /** @type {SharedTransactionBroker | undefined} */
+    this.broker = undefined
+    /** @type {Map<string, Enrollment>} */
+    this.enrollments = new Map()
+    /** @type {Map<string, {pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}>} */
+    this.sharedConnectionRegistrations = new Map()
+    /** @type {Promise<void> | undefined} */
+    this.cleanupPromise = undefined
+    /** @type {Promise<void> | undefined} */
+    this.rollbackPromise = undefined
+  }
+
+  /**
+   * Begins a test transaction session.
+   * @param {{configuration?: import("../configuration.js").default}} [args] - Backend owner.
+   * @returns {Promise<TestTransactionSession>} - Begun session.
+   */
+  static async begin({configuration} = {}) {
+    const session = new TestTransactionSession(configuration)
+    session.broker = await SharedTransactionBroker.start({connections: {}})
+    return session
+  }
+
+  /**
+   * Joins one request/job callback from a live backend control message.
+   * @template T
+   * @param {{address: string, capability: string}} message - Ephemeral coordinates received over live IPC.
+   * @param {() => T} callback - Backend request or worker work.
+   * @returns {T} - Callback result.
+   */
+  static join(message, callback) {
+    return runWithSharedTransactionBrokerConfig({...message, allowDynamicIdentities: true, databaseIdentifiers: [], expected: true}, callback)
+  }
+
+  /**
+   * Lazily adds an exact physical connection to the common rollback set.
+   * @param {Enrollment} enrollment - Checked-out physical connection and owner release hook.
+   */
+  async enroll(enrollment) {
+    const broker = this.requiredBroker()
+    const identity = `${enrollment.databaseIdentifier}\0${enrollment.reuseKey}`
+    const existing = this.enrollments.get(identity)
+    if (existing) {
+      if (existing.connection !== enrollment.connection) await enrollment.release()
+      return
+    }
+    try {
+      await enrollment.connection.startTransaction()
+    } catch (error) {
+      /** @type {Error | undefined} */
+      let releaseFailure
+      try {
+        await enrollment.release()
+      } catch (releaseError) {
+        releaseFailure = this.normalizeError(releaseError)
+      }
+      if (releaseFailure) {
+        throw new AggregateError(
+          [this.normalizeError(error), releaseFailure],
+          "Test transaction enrollment start and release failed",
+          {cause: error}
+        )
+      }
+      throw error
+    }
+    try {
+      broker.enrollConnection(enrollment)
+      this.enrollments.set(identity, enrollment)
+    } catch (error) {
+      await this.rollbackAndRelease(enrollment)
+      throw error
+    }
+  }
+
+  /**
+   * Lazily checks out and enrolls the physical database selected by a tenant descriptor.
+   * @param {{databaseIdentifier: string, tenant?: object}} args - Logical and tenant identity.
+   */
+  async enrollDatabase({databaseIdentifier, tenant}) {
+    if (!this.configuration) throw new Error("Test transaction session requires a configuration to enroll a database")
+    const pool = this.configuration.getDatabasePool(databaseIdentifier)
+    const databaseConfiguration = this.configuration.resolveDatabaseConfiguration(databaseIdentifier, tenant)
+    const reuseKey = pool.getConfigurationReuseKey(databaseConfiguration)
+    const identity = `${databaseIdentifier}\0${reuseKey}`
+    if (this.enrollments.has(identity)) return
+    const connection = await this.configuration.runWithTenant(tenant, async () => {
+      return await pool.checkout({name: "Test transaction session"})
+    })
+    await this.enroll({
+      connection,
+      databaseIdentifier,
+      release: async () => { await pool.checkin(connection) },
+      reuseKey
+    })
+    this.installSharedConnectionProvider(databaseIdentifier, pool)
+  }
+
+  /**
+   * Makes in-process request/Scoundrel checkouts resolve by current physical identity.
+   * @param {string} databaseIdentifier - Logical database identifier.
+   * @param {import("../database/pool/base.js").default} pool - Owning pool.
+   */
+  installSharedConnectionProvider(databaseIdentifier, pool) {
+    if (this.sharedConnectionRegistrations.has(databaseIdentifier)) return
+    const broker = this.requiredBroker()
+    const sessionIdentity = {address: broker.address(), capability: broker.capability()}
+    const registration = pool.registerTestSharedConnectionProvider({
+      matches: () => sharedTransactionBrokerContextMatches(sessionIdentity),
+      provider: () => {
+        if (!broker.accepting) throw new Error("Test transaction session capability has been revoked")
+        const reuseKey = pool.getConfigurationReuseKey()
+        const connection = this.enrollments.get(`${databaseIdentifier}\0${reuseKey}`)?.connection
+        if (!connection) throw new Error(`Test transaction physical identity is not enrolled: ${databaseIdentifier}`)
+        return connection
+      }
+    })
+    if (registration) this.sharedConnectionRegistrations.set(databaseIdentifier, {pool, registration})
+  }
+
+  /**
+   * Returns ephemeral coordinates for one live IPC/control message.
+   * @returns {{address: string, capability: string}} - Non-durable join coordinates.
+   */
+  joinMessage() {
+    const broker = this.requiredBroker()
+    if (!broker.accepting) throw new Error("Test transaction session capability has been revoked")
+    return {address: broker.address(), capability: broker.capability()}
+  }
+
+  /** Stops admission to the capability. */
+  revoke() { this.requiredBroker().revoke() }
+
+  /** Drains work accepted before revocation. */
+  async drain() { await this.requiredBroker().drain() }
+
+  /**
+   * Rolls back and releases the complete enrolled set after admission stops.
+   * @returns {Promise<void>} - Resolves after rollback and release.
+   */
+  async rollback() {
+    if (this.rollbackPromise) return await this.rollbackPromise
+    this.rollbackPromise = this.rollbackActual()
+    return await this.rollbackPromise
+  }
+
+  /**
+   * Performs rollback and release once.
+   * @returns {Promise<void>} - Resolves after actual rollback and release.
+   */
+  async rollbackActual() {
+    const broker = this.requiredBroker()
+    if (broker.accepting) throw new Error("Test transaction session must be revoked before rollback")
+    /** @type {Array<Error>} */
+    const errors = []
+    try { await broker.close() } catch (error) { errors.push(this.normalizeError(error)) }
+    for (const {pool, registration} of this.sharedConnectionRegistrations.values()) {
+      pool.clearTestSharedConnection(registration)
+    }
+    this.sharedConnectionRegistrations.clear()
+    for (const enrollment of this.enrollments.values()) {
+      try { await this.rollbackAndRelease(enrollment) } catch (error) { errors.push(this.normalizeError(error)) }
+    }
+    this.enrollments.clear()
+    if (errors.length > 0) throw new AggregateError(errors, "Test transaction session rollback failed")
+  }
+
+  /**
+   * Revokes, drains, rolls back, and releases every enrolled physical connection exactly once.
+   * @returns {Promise<void>} - Resolves after idempotent cleanup.
+   */
+  async cleanup() {
+    if (this.cleanupPromise) return await this.cleanupPromise
+    this.cleanupPromise = this.cleanupActual()
+    return await this.cleanupPromise
+  }
+
+  /**
+   * Performs idempotent cleanup once.
+   * @returns {Promise<void>} - Resolves after actual cleanup.
+   */
+  async cleanupActual() {
+    this.revoke()
+    await this.rollback()
+  }
+
+  /**
+   * Returns capability-free session diagnostics.
+   * @returns {{accepting: boolean, enrollmentCount: number}} - Capability-free diagnostics.
+   */
+  debugSnapshot() {
+    return {accepting: this.broker?.accepting === true, enrollmentCount: this.enrollments.size}
+  }
+
+  /**
+   * Returns the begun broker.
+   * @returns {SharedTransactionBroker} - Begun broker.
+   */
+  requiredBroker() {
+    if (!this.broker) throw new Error("Test transaction session has not begun")
+    return this.broker
+  }
+
+  /**
+   * Rolls back and releases one owned physical connection.
+   * @param {Enrollment} enrollment - Owned physical connection.
+   * @returns {Promise<void>} - Resolves after rollback and release.
+   */
+  async rollbackAndRelease(enrollment) {
+    /** @type {Array<Error>} */
+    const errors = []
+    try { await enrollment.connection.rollbackTransaction() } catch (error) { errors.push(this.normalizeError(error)) }
+    try { await enrollment.release() } catch (error) { errors.push(this.normalizeError(error)) }
+    if (errors.length > 0) throw new AggregateError(errors, "Test transaction enrollment cleanup failed")
+  }
+
+  /**
+   * Normalizes a thrown cleanup value.
+   * @param {unknown} error - Opaque thrown cleanup value narrowed at this boundary.
+   * @returns {Error} - Error instance.
+   */
+  normalizeError(error) { return error instanceof Error ? error : new Error(String(error)) }
+}

package/src/testing/test.js

@@ -2,9 +2,9 @@
 
 import path from "path"
 import {fileURLToPath} from "url"
+import { waitForEvent } from "@velocious/testing"
 import EventEmitter from "../utils/event-emitter.js"
 import Expect from "./expect.js"
-import waitForEvent from "./wait-for-event.js"
 import {arrayContaining, objectContaining} from "./expect-utils.js"
 
 /**