velocious 1.0.597 → 1.0.598

package/src/background-jobs/main.js

@@ -127,6 +127,8 @@ export default class BackgroundJobsMain {
     this.scheduler = undefined
     this._draining = false
     this._redrainQueued = false
+    /** @type {Promise<void> | undefined} */
+    this._drainPromise = undefined
     this._stopped = false
     /** @type {Promise<void> | undefined} */
     this.stopPromise = undefined
@@ -645,9 +647,11 @@ export default class BackgroundJobsMain {
   /**
    * Removes a lost worker socket and releases only leases dispatched through it.
    * @param {JsonSocket} worker - Disconnected worker socket.
+   * @param {object} [args] - Coordination options.
+   * @param {boolean} [args.queueRedrain] - Queue another pass instead of awaiting the active drain.
    * @returns {Promise<void>} - Resolves after its active leases are released.
    */
-  async _handleWorkerSocketClosed(worker) {
+  async _handleWorkerSocketClosed(worker, {queueRedrain = false} = {}) {
     this.workers.delete(worker)
     this.readyWorkers.delete(worker)
 
@@ -657,7 +661,7 @@ export default class BackgroundJobsMain {
     }
 
     try {
-      await this._releaseWorkerHandoffs(worker)
+      await this._releaseWorkerHandoffs(worker, {queueRedrain})
     } catch (error) {
       this._reportHandoffReleaseError(error)
       this._scheduleErrorRetry()
@@ -667,9 +671,11 @@ export default class BackgroundJobsMain {
   /**
    * Releases all leases still owned by one exact worker socket.
    * @param {JsonSocket} worker - Worker socket.
+   * @param {object} [args] - Coordination options.
+   * @param {boolean} [args.queueRedrain] - Queue another pass instead of awaiting the active drain.
    * @returns {Promise<void>} - Resolves after fenced releases and dispatch wake-up.
    */
-  async _releaseWorkerHandoffs(worker) {
+  async _releaseWorkerHandoffs(worker, {queueRedrain = false} = {}) {
     const handoffs = this.workerHandoffs.get(worker)
 
     if (!handoffs || handoffs.size === 0) {
@@ -683,7 +689,11 @@ export default class BackgroundJobsMain {
 
     this.workerHandoffs.delete(worker)
     this._notifyEnqueued()
-    await this._drain()
+    if (queueRedrain) {
+      this._redrainQueued = true
+    } else {
+      await this._drain()
+    }
   }
 
   /**
@@ -1100,23 +1110,38 @@ export default class BackgroundJobsMain {
    * @returns {Promise<void>}
    */
   async _drain() {
-    if (!this._startDrain()) return
+    if (this._stopped) return
 
-    const errored = await this._drainUntilIdle()
+    if (this._drainPromise) {
+      this._redrainQueued = true
+      await this._drainPromise
+      return
+    }
+
+    const drainPromise = this._drainToCompletion()
 
-    await this._finishDrain({errored})
+    this._drainPromise = drainPromise
+    await drainPromise
   }
 
   /**
-   * Runs start drain.
-   * @returns {boolean} - Whether the drain should continue.
+   * Runs one serialized drain lifecycle, including timer re-arming.
+   * @returns {Promise<void>} - Resolves after every coalesced request is handled.
    */
-  _startDrain() {
-    if (this._stopped) return false
-    if (this._queueDrainIfAlreadyRunning()) return false
-
+  async _drainToCompletion() {
     this._draining = true
-    return true
+
+    try {
+      let errored
+
+      do {
+        errored = await this._drainUntilIdle()
+        await this._finishDrain({errored})
+      } while (!errored && this._redrainQueued && !this._stopped)
+    } finally {
+      this._draining = false
+      this._drainPromise = undefined
+    }
   }
 
   /**
@@ -1162,27 +1187,12 @@ export default class BackgroundJobsMain {
     }
   }
 
-  /**
-   * Runs queue drain if already running.
-   * @returns {boolean} - Whether another drain is already in progress.
-   */
-  _queueDrainIfAlreadyRunning() {
-    if (!this._draining) return false
-
-    this._redrainQueued = true
-    return true
-  }
-
   /**
    * Runs drain until idle.
    * @returns {Promise<boolean>} - Whether the drain hit an error.
    */
   async _drainUntilIdle() {
-    try {
-      return await this._runDrainLoop()
-    } finally {
-      this._draining = false
-    }
+    return await this._runDrainLoop()
   }
 
   /**
@@ -1279,7 +1289,7 @@ export default class BackgroundJobsMain {
       if (!handoffs || !this.workers.has(worker)) {
         await this.store.markReturnedToQueue({handoffId: handoff.handoffId, jobId: job.id})
         this._notifyEnqueued()
-        await this._drain()
+        this._redrainQueued = true
         continue
       }
 
@@ -1307,7 +1317,7 @@ export default class BackgroundJobsMain {
         } catch (closeError) {
           this.logger.warn(() => ["Failed to close worker after job send failure:", closeError])
         }
-        await this._handleWorkerSocketClosed(worker)
+        await this._handleWorkerSocketClosed(worker, {queueRedrain: true})
       }
     }
   }

package/src/testing/factory/node/definition-reload-policy.js

@@ -0,0 +1,149 @@
+// @ts-check
+
+/**
+ * Default maximum number of cache-busted factory definition import attempts a
+ * single Node process may perform. Chosen conservatively from the
+ * `factory-esm-reload-retention` benchmark evidence: each cache-busted import
+ * retains roughly 6 KB of heap in Node's ESM module map, so the default bounds
+ * retained definition modules to a few tens of MB before the owning process
+ * must be recycled. This module is intentionally Node-only; browser-safe factory
+ * code must never import it.
+ */
+export const DEFAULT_DEFINITION_RELOAD_BUDGET = 4096
+
+/**
+ * Rejected when code tries to configure the process-global reload budget more
+ * than once or after any valid cache-busted import reservation was attempted.
+ * Retained ESM modules and their accounting live for the process lifetime, so
+ * changing the budget can never begin a new in-process policy epoch.
+ */
+export class DefinitionReloadConfigurationError extends Error {
+  /**
+   * Creates the error.
+   * @param {object} args - Details.
+   * @param {number} args.current - Cache-busted imports already reserved.
+   * @param {number} args.budget - Active process-global import budget.
+   * @param {number} args.requestedBudget - Rejected replacement budget.
+   * @param {boolean} args.configured - Whether an explicit budget was already configured.
+   */
+  constructor({budget, configured, current, requestedBudget}) {
+    const reason = configured
+      ? "the process-global definition reload budget was already configured"
+      : "a definition reload reservation was already attempted"
+
+    super(`Cannot configure definition reload budget to ${requestedBudget}: ${reason} (current=${current}, budget=${budget}). Configuration is allowed exactly once before the first reservation; only process exit resets retained-module accounting.`)
+    this.name = "DefinitionReloadConfigurationError"
+    this.budget = budget
+    this.configured = configured
+    this.current = current
+    this.requestedBudget = requestedBudget
+  }
+}
+
+/**
+ * Rejected when a reload would push the process over its cache-busted import
+ * budget. The rejection happens synchronously before any registry reset or
+ * import, so the currently loaded registry stays usable. Node never evicts
+ * retained ESM module instances, so only recycling/restarting the owning Node
+ * process reclaims the memory and refreshes edited dependency modules.
+ */
+export class DefinitionRecycleRequiredError extends Error {
+  /**
+   * Creates the error.
+   * @param {object} args - Details.
+   * @param {number} args.current - Cache-busted import attempts already reserved in this process.
+   * @param {number} args.budget - Process-global import budget.
+   * @param {number} args.requested - Import attempts the rejected reload needed.
+   */
+  constructor({current, budget, requested}) {
+    super(`Factory definition reload import budget exhausted (current=${current}, budget=${budget}, requested=${requested}). Recycle or restart the owning Node process: every reload imports a fresh cache-busted module instance and Node never evicts them, so process recycling is the only reclamation boundary.`)
+    this.name = "DefinitionRecycleRequiredError"
+    this.current = current
+    this.budget = budget
+    this.requested = requested
+  }
+}
+
+/** @type {number} - The single process-global import budget. */
+let importBudget = DEFAULT_DEFINITION_RELOAD_BUDGET
+
+/** @type {number} - Cache-busted import attempts reserved so far across every registry and target. */
+let reservedImports = 0
+
+/** @type {boolean} - Whether the process-global budget was explicitly configured. */
+let budgetConfigured = false
+
+/** @type {boolean} - Whether any valid complete reload batch reservation was attempted. */
+let reservationStarted = false
+
+/**
+ * Returns the process-global cache-busted import budget.
+ * @returns {number} - The budget.
+ */
+export function getDefinitionReloadBudget() {
+  return importBudget
+}
+
+/**
+ * Reads the cache-busted import attempts reserved so far in this process,
+ * across every registry and target. Combined with {@link getDefinitionReloadBudget}
+ * this is the deterministic process-global census for the recycle policy.
+ * @returns {number} - Reserved count.
+ */
+export function peekDefinitionReloadBudget() {
+  return reservedImports
+}
+
+/**
+ * Configures the one process-global import budget exactly once and only before
+ * the first valid reservation attempt. There is exactly one budget for the whole
+ * process, so no combination of registries or targets can create independent
+ * budgets that defeat the global limit. Retained-import accounting is never
+ * reset in-process.
+ * @param {number} budget - New budget.
+ * @returns {void}
+ */
+export function setDefinitionReloadBudget(budget) {
+  if (!Number.isInteger(budget) || budget < 1) {
+    throw new TypeError(`Definition reload budget must be a positive integer, got ${JSON.stringify(budget)}`)
+  }
+
+  if (budgetConfigured || reservationStarted) {
+    throw new DefinitionReloadConfigurationError({
+      budget: importBudget,
+      configured: budgetConfigured,
+      current: reservedImports,
+      requestedBudget: budget
+    })
+  }
+
+  importBudget = budget
+  budgetConfigured = true
+}
+
+/**
+ * Preflights and reserves a whole reload batch synchronously. Malformed counts
+ * are rejected before configuration is sealed or accounting changes. Every valid
+ * request, including zero and a rejected over-budget request, seals configuration
+ * before capacity is evaluated. Throws {@link DefinitionRecycleRequiredError}
+ * when the requested batch would push the process over its budget. The check and
+ * reservation run in one synchronous step, so concurrent reloads cannot race past
+ * the budget. The reservation is deliberately conservative: it covers every
+ * import attempt in the batch, so a mid-batch import failure still counts its
+ * attempts as retained modules.
+ * @param {number} requested - Cache-busted import attempts the reload will perform.
+ * @returns {void}
+ */
+export function reserveDefinitionReloadBudget(requested) {
+  if (!Number.isInteger(requested) || requested < 0) {
+    throw new TypeError(`Definition reload reservation must be a non-negative integer, got ${typeof requested} ${String(requested)}`)
+  }
+
+  reservationStarted = true
+
+  if (reservedImports + requested > importBudget) {
+    throw new DefinitionRecycleRequiredError({current: reservedImports, budget: importBudget, requested})
+  }
+
+  reservedImports += requested
+}

package/src/testing/factory/node/load-definitions.js

@@ -1,8 +1,9 @@
 // @ts-check
 
-import {pathToFileURL} from "node:url"
-import {readdir, stat} from "node:fs/promises"
+import { pathToFileURL } from "node:url"
+import { readdir, stat } from "node:fs/promises"
 import path from "node:path"
+import { reserveDefinitionReloadBudget } from "./definition-reload-policy.js"
 
 /**
  * Monotonic cache-busting counter shared by reloads. Kept module-local so a reload
@@ -68,6 +69,26 @@ async function resolveFiles(target) {
 export async function loadDefinitions(registry, target, {reload = false} = {}) {
   const files = await resolveFiles(target)
 
+  return await loadResolvedDefinitionFiles({files, registry, reload})
+}
+
+/**
+ * Loads definition files that have already been resolved into a deterministic
+ * sorted list. When `reload` is set, the whole batch is preflighted and reserved
+ * against the process-global import budget before any registry reset or import
+ * attempt, so a rejected reload never mutates the registry.
+ * @param {object} args - Options object.
+ * @param {string[]} args.files - Resolved, sorted definition file paths.
+ * @param {import("../factory-registry.js").default} args.registry - Registry to define into.
+ * @param {boolean} args.reload - Whether to cache-bust the imports.
+ * @param {boolean} [args.reset] - Whether to reset the registry first.
+ * @returns {Promise<string[]>} - The loaded file paths, in load order.
+ */
+async function loadResolvedDefinitionFiles({files, registry, reload, reset = false}) {
+  if (reload) reserveDefinitionReloadBudget(files.length)
+
+  if (reset) registry.reset()
+
   for (const file of files) {
     let href = pathToFileURL(file).href
 
@@ -91,13 +112,16 @@ export async function loadDefinitions(registry, target, {reload = false} = {}) {
 /**
  * Fully reloads definitions: resets the registry (dropping every factory, trait,
  * sequence, callback and default) and re-imports the target files with cache
- * busting so edited definitions take effect.
+ * busting so edited definitions take effect. The resolved batch is preflighted
+ * against the process-global import budget before the reset, and a
+ * `DefinitionRecycleRequiredError` is raised before any mutation when the batch
+ * would exceed the budget.
  * @param {import("../factory-registry.js").default} registry - Registry to reload.
  * @param {string | string[]} target - File path, directory, or list of paths.
  * @returns {Promise<string[]>} - The reloaded file paths, in load order.
  */
 export async function reloadDefinitions(registry, target) {
-  registry.reset()
+  const files = await resolveFiles(target)
 
-  return await loadDefinitions(registry, target, {reload: true})
+  return await loadResolvedDefinitionFiles({files, registry, reload: true, reset: true})
 }

package/src/testing/test-runner.js

@@ -1058,12 +1058,12 @@ export default class TestRunner {
               // back). Releasing the lease after each lifecycle also runs the pool's
               // session cleanup before another test can reuse the connection.
               await this.getConfiguration().ensureConnections({name: `Test: ${testDescription}`}, async () => {
-                // Register dynamic candidates before application hooks so transaction
-                // state changes made during a hook are visible to a request dispatched
-                // by that same callback.
-                if (testArgs.type == "request") {
-                  testSharedConnectionRegistrations = this.activateTestSharedConnections()
-                }
+                // Register dynamic candidates before hooks so transaction state changes
+                // made during a hook are immediately visible to any in-process work.
+                // Long-lived services such as a background-jobs main can dispatch DB
+                // work between a transaction-starting hook and broker activation just
+                // as an HTTP request can dispatch work from inside the hook itself.
+                testSharedConnectionRegistrations = this.activateTestSharedConnections()
 
                 try {
                   try {