velocious 1.0.596 → 1.0.598

package/README.md

@@ -9,6 +9,7 @@
 * Declarative state machines for models, with typed event methods generated into the base model (see [docs/state-machine.md](docs/state-machine.md))
 * Migrations for schema changes and UTC datetime storage (see [docs/database-migrations.md](docs/database-migrations.md))
 * Tenant-selected base-model and structure generation with one immutable, fail-closed physical database context; tenant-only model metadata initializes only after that context is active (see [docs/tenant-selected-database-generation.md](docs/tenant-selected-database-generation.md))
+* Read-only tenant migration deploy preflight with stable JSON output and fail-closed ledger reads (see [docs/tenant-migration-deploy-preflight.md](docs/tenant-migration-deploy-preflight.md))
 * External packages (engines) that contribute data models, frontend-model resources and migrations to a consuming app (see [docs/packages.md](docs/packages.md))
 * Optional Rampway-owned durable deployment control plane mounted through the standard routes DSL on Velocious 1.0.577 or newer (see [docs/rampway-integration.md](docs/rampway-integration.md))
 * Controllers and views for HTTP endpoints
@@ -24,7 +25,7 @@
 * Expo / Metro compatibility guidance and a real Expo export check (see [docs/expo-metro-compatibility.md](docs/expo-metro-compatibility.md))
 * Gap-less positional lists with automatic reordering via `actsAsList`, including models with numeric, string, or UUID primary keys (see [docs/acts-as-list.md](docs/acts-as-list.md))
 * Rails-style nested-attribute writes on frontend-model `save()` (see [docs/nested-attributes.md](docs/nested-attributes.md))
-* Async-aware test-data factories with inherited traits, graph-first native association autosave, metadata-aware override precedence, callbacks, sequences, and linting (see [docs/factories.md](docs/factories.md))
+* Async-aware test-data factories with inherited traits, graph-first native association autosave, metadata-aware override precedence, callbacks, sequences, linting, and a process-global reload-retention budget that bounds cache-busted re-import memory (see [docs/factories.md](docs/factories.md))
 * Per-row association counts via `.withCount(...)`, including cohort-safe intersected filters, safe batching of structurally identical aggregates, and automatic IN-list chunking for large parent sets, on frontend and backend queries (see [docs/with-count.md](docs/with-count.md))
 * Consumer-defined per-row SQL aggregates/computations via `.queryData(...)`, with compatible projections sharing a roundtrip while preserving declared alias-overwrite order and automatic IN-list chunking for large parent sets, on frontend and backend queries (see [docs/query-data.md](docs/query-data.md))
 * Per-record ability checks via `.abilities(...)` on frontend queries + `record.can(action)` (see [docs/abilities.md](docs/abilities.md))
@@ -389,6 +390,19 @@ await new TasksMailer().newNotification(task, user).deliverNow()
 await new TasksMailer().newNotification(task, user).deliverLater()
 ```
 
+For a provider that advertises duplicate suppression, a producer can require one stable mail operation across outbox replay and native-job retries:
+
+```js
+await new TasksMailer().newNotification(task, user).deliverLater({
+  deliveryOperation: {
+    id: `project-command:${command.id()}`,
+    idempotency: "required"
+  }
+})
+```
+
+Required delivery fails before enqueue on unsupported backends, rejects the same id with changed rendered content, and fails closed after the provider retention window. Direct required `deliverPayload()` calls also fail before provider I/O when the background-jobs database connection is already inside a caller-owned transaction, because an outer rollback could erase the first-attempt marker. Generic SMTP remains at-least-once. Velocious includes a dedicated `ResendSmtpMailerBackend` for Resend's 24-hour `Resend-Idempotency-Key` contract; see [Mailers](docs/mailers.md#provider-backed-idempotent-background-delivery) for setup, expiry, reconciliation, and non-exactly-once guarantees.
+
 Build the rendered payload without sending when the app needs to store an audit copy or hand delivery to its own transport:
 
 ```js
@@ -2395,10 +2409,12 @@ const result = await MyJob.replaceScheduled({
 await MyJob.cancelScheduled(`event:${eventId}:reminder:24h`)
 ```
 
-A queued owner is atomically cancelled during replacement/cancellation. A `previousStatus` or cancellation `outcome` of `"handed_off"` means the worker may already be running; Velocious removes or replaces key ownership but does not claim that JavaScript stopped. Store a generation/revision in application state, pass it to the job, and re-check it immediately before irreversible effects. Stable keys and full result shapes are documented in [Scheduling One-Off Background Jobs](docs/scheduled-background-job-enqueue.md#replacing-or-cancelling-a-logical-schedule).
+A queued owner is atomically cancelled during replacement/cancellation. Its acknowledgement waits for the corresponding dispatch drain lifecycle; if another drain is already active, the request coalesces and waits for its re-drain and future-job timer re-arm instead of acknowledging early. A `previousStatus` or cancellation `outcome` of `"handed_off"` means the worker may already be running; Velocious removes or replaces key ownership but does not claim that JavaScript stopped. Store a generation/revision in application state, pass it to the job, and re-check it immediately before irreversible effects. Stable keys and full result shapes are documented in [Scheduling One-Off Background Jobs](docs/scheduled-background-job-enqueue.md#replacing-or-cancelling-a-logical-schedule).
 
 Set `deduplicateWhileQueued: true` to coalesce an enqueue onto the earliest identical queued job with the same job name, arguments, and queue when that existing job is scheduled no later than the new request. A retry backed off into the future does not suppress a new immediate enqueue, while repeated immediate triggers and equal or later schedules still coalesce.
 
+Use `options: {idempotencyKey}` when producer replay must converge on the original durable job across every state and even after terminal-job pruning. Ownership is scoped to the resolved job class name, resolved queue, and key; reusing that scope with changed canonical arguments or behavior-affecting options fails. This is distinct from queued-only deduplication, and ownership rows are intentionally retained until a future explicit reconciliation/deletion policy. See [durable idempotent enqueue](docs/background-jobs.md#durable-idempotent-enqueue).
+
 Select a non-default runtime explicitly with `options: {executionMode: "inline" | "forked" | "spawned"}`.
 
 Inline jobs share the worker process and run concurrently up to `maxConcurrentInlineJobs`, so a single slow inline job no longer blocks the queue. A single worker can also override the configured cap explicitly:

package/build/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/build/background-jobs/pooled-runner-broker-identity.js

@@ -23,16 +23,18 @@ export default class PooledRunnerBrokerIdentity {
   /**
    * Prepares one identity, sharing an in-flight same-identity rotation.
    * @param {import("../testing/shared-transaction-proxy-driver.js").SharedTransactionBrokerJobConfig} config - Dispatch configuration.
+   * @param {boolean} [admissionReserved] - Whether the caller already reserved its active-user slot.
    * @returns {Promise<void>} - Resolves after stale connections close.
    */
-  async prepare(config) {
+  async prepare(config, admissionReserved = false) {
     const identity = JSON.stringify(config)
     if (this.pending) {
       if (this.pending.identity !== identity) throw new Error("Pooled runner cannot mix shared transaction broker capabilities concurrently")
       return await this.pending.promise
     }
     if (this.activeIdentity === identity) return
-    if (this.activeUsers > 0) throw new Error("Pooled runner cannot mix shared transaction broker capabilities concurrently")
+    const otherActiveUsers = this.activeUsers - (admissionReserved ? 1 : 0)
+    if (otherActiveUsers > 0) throw new Error("Pooled runner cannot mix shared transaction broker capabilities concurrently")
     if (this.activeIdentity === undefined) {
       this.activeIdentity = identity
       return
@@ -55,8 +57,7 @@ export default class PooledRunnerBrokerIdentity {
    * @returns {Promise<T>} - Job result.
    */
   async run(config, callback) {
-    await this.prepare(config)
-    this.activeUsers++
+    await this.admit(config)
     try {
       return await callback()
     } finally {
@@ -64,6 +65,23 @@ export default class PooledRunnerBrokerIdentity {
     }
   }
 
+  /**
+   * Atomically prepares an attempt identity and reserves its active user. Without
+   * this admission turn, another capability can rotate connections after `prepare`
+   * resolves but before `run` increments `activeUsers`.
+   * @param {import("../testing/shared-transaction-proxy-driver.js").SharedTransactionBrokerJobConfig} config - Dispatch configuration.
+   * @returns {Promise<void>} - Resolves after admission is reserved.
+   */
+  async admit(config) {
+    this.activeUsers++
+    try {
+      await this.prepare(config, true)
+    } catch (error) {
+      this.activeUsers--
+      throw error
+    }
+  }
+
   /**
    * Rotates retained connection state to an identity.
    * @param {string} identity - Target identity.