pg-boss 12.33.2 → 12.33.4

package/README.md

@@ -74,7 +74,7 @@ A HTTP proxy is available in the [`@pg-boss/proxy`](https://www.npmjs.com/packag
 See the [proxy documentation](https://pgboss.io/proxy) for details.
 
 ## Requirements
-* Node 22.12 or higher for CommonJS's require(esm)
+* Node 22.12 or higher, or Bun
 * PostgreSQL 13 or higher
 
 ## Sponsors

package/dist/attorney.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attorney.d.ts","sourceRoot":"","sources":["../src/attorney.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC,QAAA,MAAM,MAAM;;;;CAIX,CAAA;AAKD,QAAA,MAAM,mBAAmB,uQAaf,CAAA;AA2EV,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;AAgBD,iBAAS,mBAAmB,CAAE,KAAK,EAAE,MAAM,UAE1C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CAgDhD;AAOD,iBAAS,eAAe,CAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAc,EAAE;;CAAK,GAAG,KAAK,CAAC,OAAO,CA4D3E;AAED,iBAAS,mBAAmB,CAAE,MAAM,EAAE,GAAG,QAOxC;AAED,iBAAS,gBAAgB,CAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,QA2D/C;AA2GD,iBAAS,aAAa,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG;IAClD,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAA;IAClC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;CACjC,CAgCA;AAqBD,iBAAS,cAAc,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAQlD;AAED,iBAAS,SAAS,CAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,0BAA0B,CA0B9F;AA8GD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAiC9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AA+LD,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EAClB,CAAA"}
+{"version":3,"file":"attorney.d.ts","sourceRoot":"","sources":["../src/attorney.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC,QAAA,MAAM,MAAM;;;;CAIX,CAAA;AAKD,QAAA,MAAM,mBAAmB,uQAaf,CAAA;AA2EV,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;AAiBD,iBAAS,mBAAmB,CAAE,KAAK,EAAE,MAAM,UAE1C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CAgDhD;AAOD,iBAAS,eAAe,CAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAc,EAAE;;CAAK,GAAG,KAAK,CAAC,OAAO,CA4D3E;AAED,iBAAS,mBAAmB,CAAE,MAAM,EAAE,GAAG,QAOxC;AAED,iBAAS,gBAAgB,CAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,QA2D/C;AA2GD,iBAAS,aAAa,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG;IAClD,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAA;IAClC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;CACjC,CAgCA;AAqBD,iBAAS,cAAc,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAQlD;AAED,iBAAS,SAAS,CAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,0BAA0B,CA0B9F;AA8GD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAiC9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AA+LD,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EAClB,CAAA"}

package/dist/attorney.js

@@ -41,10 +41,10 @@ const BACKEND_PROFILES = {
             noAddColumnBackfill: true,
             noListenNotify: true,
             // Online DDL runs as a schema-change job, not the PG CONCURRENTLY path, and
-            // pg_stat_progress_create_index isn't available — so BAM can't use liveness-based reclaim.
+            // pg_stat_progress_create_index isn't available, so BAM can't use liveness-based reclaim.
             noIndexProgressView: true,
-            // REINDEX is rejected in either form — "CockroachDB does not require reindexing" with
-            // CONCURRENTLY, "unimplemented: this syntax" without — and the bloat check itself cannot run:
+            // REINDEX is rejected in either form, "CockroachDB does not require reindexing" with
+            // CONCURRENTLY, "unimplemented: this syntax" without, and the bloat check itself cannot run:
             // there is no pg_relation_size(), and reltuples / relpages is an "unsupported binary
             // operator: <float4> / <int4>".
             noReindex: true,
@@ -74,7 +74,7 @@ const BACKEND_PROFILES = {
     // No noIndexProgressView: pg-boss keeps its tables coordinator-local (it never calls
     // create_distributed_table), so CREATE INDEX CONCURRENTLY runs against ordinary local Postgres tables
     // on the coordinator, where pg_stat_progress_create_index is accurate and liveness-based reclaim is
-    // valid. This holds ONLY while the tables stay coordinator-local — if they are ever distributed, the
+    // valid. This holds ONLY while the tables stay coordinator-local. If they are ever distributed, the
     // coordinator's progress view would misread in-flight worker builds as dead and BAM could double-build.
     citus: { kind: 'distributed', flags: {} },
     pglite: { kind: 'embedded', flags: {} }
@@ -103,8 +103,9 @@ function validateQueueArgs(config = {}) {
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}/;
 // Matched against the remainder past YYYY-MM-DD, and deliberately a whitelist of the zone-less
 // spellings rather than a test for a missing zone: a trailing '-01' would read as an offset, and
-// forms Postgres resolves on its own — a named zone ('... UTC', '... America/New_York'), a
-// single-digit offset ('+5:30') — must be left exactly as they are rather than pinned to UTC.
+// forms Postgres resolves on its own must be left exactly as they are rather than pinned to UTC.
+// Those forms are a named zone ('... UTC', '... America/New_York') and a single-digit offset
+// ('+5:30').
 const ZONELESS_TIME = /^(?:[T ]\d{2}(?::\d{2}(?::\d{2}(?:[.,]\d+)?)?)?)?$/;
 function pinZonelessDateTime(value) {
     return ISO_DATE.test(value) && ZONELESS_TIME.test(value.slice(10)) ? value + 'Z' : value;
@@ -172,14 +173,14 @@ function checkUpdateArgs(args, { upsert = false } = {}) {
     assert(typeof options === 'object', 'options should be an object');
     const { id, singletonKey, match } = options;
     // Both update() and upsert() target by exactly one of id or singletonKey. (upsert() may also
-    // require a singletonKey at runtime on key_strict_fifo queues — enforced in the manager, which
-    // knows the policy — because an insert-on-miss there needs a key.)
+    // require a singletonKey at runtime on key_strict_fifo queues, enforced in the manager, which
+    // knows the policy, because an insert-on-miss there needs a key.)
     assert((!!id) !== (!!singletonKey), `${verb} requires exactly one of id or singletonKey`);
     assert(!(id && match !== undefined), 'match is only valid when targeting jobs by singletonKey');
     assert(match === undefined || JOB_MATCH_STRATEGIES.includes(match), `match must be one of: ${JOB_MATCH_STRATEGIES.join(', ')}`);
     assert(!('priority' in options) || (Number.isInteger(options.priority)), 'priority must be an integer');
     if ('startAfter' in options) {
-        // Unlike send(), update() must honor a numeric startAfter of 0 (or negative) — the caller is
+        // Unlike send(), update() must honor a numeric startAfter of 0 (or negative). The caller is
         // explicitly pulling a deferred job forward to now. The send-style `+startAfter > 0` guard
         // coerced 0 to undefined, which JSON.stringify then dropped, silently making the edit a no-op.
         // Any finite number is passed through as a seconds interval ('0' -> now()); a string is kept.
@@ -442,7 +443,7 @@ function validateWarningConfig(config) {
     assert(!('warningRetentionDays' in config) || config.warningRetentionDays <= POLICY.MAX_RETENTION_DAYS, `configuration assert: warningRetentionDays cannot exceed ${POLICY.MAX_RETENTION_DAYS} days`);
 }
 // Expands config.backend into the internal compatibility flags. The flags are derived
-// solely from the backend profile — they are not part of the public input, so a
+// solely from the backend profile. They are not part of the public input, so a
 // deployment can't end up with an inconsistent combination.
 function resolveBackend(config) {
     const backend = ('backend' in config) ? config.backend : 'postgres';
@@ -582,7 +583,7 @@ function applyPollingInterval(config) {
         : 2000;
     assert(!('notifyPollingIntervalSeconds' in config) || config.notifyPollingIntervalSeconds >= POLICY.MIN_POLLING_INTERVAL_MS / 1000, `configuration assert: notifyPollingIntervalSeconds must be at least every ${POLICY.MIN_POLLING_INTERVAL_MS}ms`);
     // Relaxed backstop poll used only while NOTIFY is active for the queue; falls back to
-    // pollingInterval when notify is unavailable. It must never be smaller than the base poll —
+    // pollingInterval when notify is unavailable. It must never be smaller than the base poll,
     // that would make a notify-active queue poll more aggressively than an idle one, the opposite
     // of the intent. When explicit, reject a value below the base; when defaulted, floor it at the
     // base so bumping pollingIntervalSeconds past 30s can't silently leave notify smaller.
@@ -629,7 +630,7 @@ function validateReindexConfig(config) {
         assert(maxIndexBytes === undefined || (Number.isInteger(maxIndexBytes) && maxIndexBytes > 0), 'configuration assert: reindex.maxIndexBytes must be an integer > 0');
         // force belongs to an explicit supervise() call, not to a background timer that would then
         // rebuild every job index on every interval.
-        assert(force === undefined || force === false, 'configuration assert: reindex.force cannot be set in constructor options — pass it to supervise()');
+        assert(force === undefined || force === false, 'configuration assert: reindex.force cannot be set in constructor options. Pass it to supervise()');
     }
     assert(!('reindexIntervalSeconds' in config) || config.reindexIntervalSeconds >= 1, 'configuration assert: reindexIntervalSeconds must be at least every second');
     config.reindexIntervalSeconds = config.reindexIntervalSeconds || POLICY.MAX_EXPIRATION_HOURS * 60 * 60;

package/dist/bam.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bam.d.ts","sourceRoot":"","sources":["../src/bam.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAItC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAOnC,cAAM,GAAI,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAOzD,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAU1C,IAAI,OAAO,IAAK,OAAO,CAEtB;IAEK,KAAK;IAcL,IAAI;CAkIX;AAED,eAAe,GAAG,CAAA"}
+{"version":3,"file":"bam.d.ts","sourceRoot":"","sources":["../src/bam.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAItC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAgBnC,cAAM,GAAI,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAOzD,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAU1C,IAAI,OAAO,IAAK,OAAO,CAEtB;IAEK,KAAK;IAcL,IAAI;CAwLX;AAED,eAAe,GAAG,CAAA"}

package/dist/bam.js

@@ -36,10 +36,8 @@ class Bam extends EventEmitter {
         if (this.#stopped)
             return;
         this.#stopped = true;
-        if (this.#pollTimer) {
-            this.#pollTimer.stop();
-            this.#pollTimer = undefined;
-        }
+        this.#pollTimer.stop();
+        this.#pollTimer = undefined;
         while (this.#working) {
             await delay(10);
         }
@@ -75,8 +73,25 @@ class Bam extends EventEmitter {
         if (this.#stopped)
             return;
         const entry = await this.#getNextCommand();
-        if (!entry || this.#stopped)
+        if (!entry)
+            return;
+        if (this.#config.__test__delay_bam_claim_ms) {
+            await delay(this.#config.__test__delay_bam_claim_ms);
+        }
+        if (this.#stopped) {
+            // The claim landed on the wrong side of a stop. The command has not run, so hand the row back
+            // exactly as it was found rather than leaving it in_progress - an in_progress row blocks the
+            // whole BAM queue until it goes stale, which is the grace window on native Postgres and 24
+            // hours on the timeout-only backends. If the release itself fails the row keeps that claim and
+            // recovers on the stale path, so surface it rather than throwing into #onPoll.
+            try {
+                await this.#releaseCommand(entry);
+            }
+            catch (err) {
+                this.emit(events.error, err);
+            }
             return;
+        }
         this.emit(events.bam, {
             id: entry.id,
             name: entry.name,
@@ -85,31 +100,50 @@ class Bam extends EventEmitter {
             table: entry.table
         });
         try {
-            // A re-attempted command (a stale in_progress reclaim, or a retry of a prior 'failed' — including
-            // failed rows left by older releases) may have an INVALID index behind it from an interrupted or
-            // failed CREATE INDEX CONCURRENTLY. Drop it first (best-effort, IF EXISTS) so the re-run rebuilds
-            // cleanly instead of the command's own IF NOT EXISTS skipping over a broken index forever. Only on
-            // the liveness path — CockroachDB/YugabyteDB roll interrupted builds back, so there's nothing to
-            // heal and DROP ... CONCURRENTLY isn't their model.
-            if (entry.reattempt && !this.#config.noIndexProgressView) {
-                const dropSql = plans.bamHealDrop(this.#config.schema, entry.command);
-                if (dropSql) {
-                    // Only heal an index the previous attempt left INVALID. A re-attempt can also fire for a
-                    // build that actually SUCCEEDED but whose row was never marked completed (a graceful stop
-                    // landed between the CREATE and markCompleted) — that index is VALID and in use, so dropping
-                    // it would tear down a live production index for the whole rebuild window. Probe indisvalid
-                    // first; skip the drop for a valid (or absent) index and let the command's IF NOT EXISTS re-run
-                    // no-op it and mark the row done.
-                    const probeSql = plans.bamHealProbe(this.#config.schema, entry.command);
+            let alreadyBuilt = false;
+            // A re-attempted command (a stale in_progress reclaim, or a retry of a prior 'failed', including
+            // failed rows left by older releases) needs the catalog consulted before the command is re-run,
+            // because the row keeps the text it was enqueued with and that text may not be idempotent.
+            // Probe indisvalid on every backend: pg_index is readable everywhere, and both outcomes matter.
+            if (entry.reattempt) {
+                const probeSql = plans.bamHealProbe(this.#config.schema, entry.command);
+                if (probeSql) {
                     const { rows } = await this.#db.executeSql(probeSql);
                     if (rows[0]?.invalid) {
-                        await this.#db.executeSql(dropSql);
+                        // An interrupted or failed CREATE INDEX CONCURRENTLY left an INVALID stub. Drop it
+                        // (best-effort, IF EXISTS) so the re-run rebuilds cleanly instead of the command's own
+                        // IF NOT EXISTS skipping over a broken index forever. Only on the liveness path,
+                        // CockroachDB/YugabyteDB roll interrupted builds back, so there is nothing to heal and
+                        // DROP ... CONCURRENTLY isn't their model.
+                        if (!this.#config.noIndexProgressView) {
+                            // Non-null wherever the probe was: both recognise the same CONCURRENTLY commands.
+                            await this.#db.executeSql(plans.bamHealDrop(this.#config.schema, entry.command));
+                        }
+                    }
+                    else if (rows[0]) {
+                        // The index is VALID, so the build already succeeded and only the row was never marked (a
+                        // stop landed between the CREATE and markCompleted). Dropping it would tear down a live
+                        // production index for the whole rebuild window, and re-running is not safe either: the two
+                        // oldest index commands (job_i7, job_i8) were queued without IF NOT EXISTS, so re-running
+                        // one against its own valid index fails with "already exists" and the failed row is retried
+                        // forever. Short-circuit to marking the row done instead. This half is deliberately NOT
+                        // gated on the liveness path. The timeout-only backends need it most, because their stale
+                        // window is BAM_STALE_SECONDS (24 hours) rather than the grace window.
+                        alreadyBuilt = true;
                     }
                 }
             }
-            await this.#db.executeSql(entry.command);
-            if (this.#stopped)
-                return;
+            if (!alreadyBuilt) {
+                await this.#db.executeSql(entry.command);
+            }
+            // Record the outcome even when a stop landed while the command was running. stop() waits out
+            // #working and index.ts closes the pool only after #bam.stop() resolves, so the UPDATE is safe
+            // here. Bailing out instead would strand a VALID index behind an unmarked row: on native
+            // Postgres the whole BAM queue then waits out BAM_LIVENESS_GRACE_SECONDS, and on the
+            // timeout-only backends (CockroachDB/YugabyteDB) every other command is blocked for
+            // BAM_STALE_SECONDS - 24 hours - before anything is retried. A failure here falls through to
+            // the catch, which marks the row failed - the next attempt's probe finds the VALID index and
+            // completes it.
             await this.#markCompleted(entry.id);
             this.emit(events.bam, {
                 id: entry.id,
@@ -120,9 +154,17 @@ class Bam extends EventEmitter {
             });
         }
         catch (err) {
-            if (this.#stopped)
-                return;
-            await this.#markFailed(entry.id, err);
+            // Same reasoning as the completed path: a stop must not leave the row in_progress. This write
+            // is guarded because it commonly runs on the connection that just failed - a terminated backend
+            // or dropped connection fails the command AND the UPDATE that would record it. Letting that
+            // throw would replace the real failure with the write's error and lose which command failed,
+            // so report both and let the stale path reclaim the row.
+            try {
+                await this.#markFailed(entry.id, err);
+            }
+            catch (markErr) {
+                this.emit(events.error, markErr);
+            }
             this.emit(events.error, err);
             this.emit(events.bam, {
                 id: entry.id,
@@ -139,6 +181,10 @@ class Bam extends EventEmitter {
         const { rows } = await this.#db.executeSql(sql);
         return rows[0] || null;
     }
+    async #releaseCommand(entry) {
+        const sql = plans.releaseBamCommand(this.#config.schema, entry.id, entry.priorStatus, entry.priorStartedOn ?? null, entry.claimedStartedOn);
+        await this.#db.executeSql(sql);
+    }
     async #markCompleted(id) {
         const sql = plans.setBamCompleted(this.#config.schema, id);
         await this.#db.executeSql(sql);

package/dist/boss.d.ts

@@ -15,7 +15,7 @@ declare class Boss extends EventEmitter implements types.EventsMixin {
     /**
      * The REINDEX statements this instance would run, for installations where it cannot run them
      * itself. Unlike the background pass this applies no ownership filter and no size cap unless one
-     * is passed — the commands are for an operator, who may run them as a different role.
+     * is passed. The commands are for an operator, who may run them as a different role.
      */
     getReindexCommands(options?: types.ReindexOptions): Promise<string[]>;
 }

package/dist/boss.js

@@ -68,7 +68,7 @@ function describeXminHolder(source, row) {
     return `${who} (${where}) has held a transaction open ${open}`;
 }
 // SQLSTATE 25001 (active_sql_transaction): "REINDEX CONCURRENTLY cannot run inside a transaction
-// block". Raised when a user-supplied adapter wraps executeSql in a transaction — a property of the
+// block". Raised when a user-supplied adapter wraps executeSql in a transaction. A property of the
 // adapter, not of this pass, so it disables rebuilds for the life of the instance rather than
 // retrying every interval.
 const IN_TRANSACTION_ERROR = '25001';
@@ -86,7 +86,7 @@ class Boss extends EventEmitter {
     // keeps running; only the DDL is abandoned.
     #reindexUnavailable = null;
     // Warn once per bloated index rather than on every pass. An index leaves the set as soon as it
-    // stops qualifying — rebuilt, dropped, or refilled — so a later episode warns again.
+    // stops qualifying (rebuilt, dropped, or refilled) so a later episode warns again.
     #warnedBloat = new Set();
     // Local rate limit for passes that only report bloat, which deliberately leave the shared interval
     // claim to whichever instance can act on it.
@@ -229,7 +229,7 @@ class Boss extends EventEmitter {
         // Ensure today's/tomorrow's partitions exist before any insertQueueStats below. Retention
         // (#maintainWarnings/#maintainQueueStats) runs at the tail. Both live here, in the public
         // supervise() path that also performs the writes, rather than in the timer-only #onSupervise
-        // wrapper — so manual supervise() callers (instances run with the built-in supervisor disabled)
+        // wrapper, so manual supervise() callers (instances run with the built-in supervisor disabled)
         // get partitions provisioned and old data pruned, not just job retention.
         if (this.#config.persistQueueStats && !this.#config.noTablePartitioning && !this.#stopping) {
             await this.#ensureQueueStatsPartitions();
@@ -574,7 +574,7 @@ class Boss extends EventEmitter {
             holder: describeXminHolder(holder.source, horizon.row),
             holderClass: XMIN_HOLDERS[holder.source],
             // Null unless the holder is a backend this role could read a row for. `self` says whether it
-            // shares this connection's application_name — pg-boss pinning its own horizon and an
+            // shares this connection's application_name. A pg-boss instance pinning its own horizon and an
             // external reporting tool pinning it have opposite fixes.
             holderPid: backend?.pid ?? null,
             holderApplicationName: backend?.applicationName ?? null,
@@ -598,10 +598,10 @@ class Boss extends EventEmitter {
         });
     }
     /**
-     * The widest holder in the row. Every source the query returns has already been qualified — the
+     * The widest holder in the row. Every source the query returns has already been qualified. The
      * backends column is filtered server-side to transactions that predate the failed vacuum, and a
      * slot, standby or prepared transaction advertises an xmin only while something is genuinely
-     * stuck — so this is a straight maximum. The horizon is pinned to the oldest of them, which makes
+     * stuck, so this is a straight maximum. The horizon is pinned to the oldest of them, which makes
      * the widest the one worth naming.
      */
     #attributeXminHorizon(row) {
@@ -665,7 +665,7 @@ class Boss extends EventEmitter {
         }
         return readable;
     }
-    // DDL runs outside the slow-query timer. A REINDEX is expected to take seconds — routing it
+    // DDL runs outside the slow-query timer. A REINDEX is expected to take seconds, routing it
     // through #executeQuery would emit a bogus slow_query warning on every rebuild.
     async #executeDdl(sql) {
         return unwrapSQLResult(await this.#db.executeSql(sql));
@@ -686,7 +686,7 @@ class Boss extends EventEmitter {
      * Detection still runs where the rebuild cannot: a role that does not own the indexes, an adapter
      * that wraps queries in a transaction, and `reindex: false` all still produce the `index_bloat`
      * warning and can act on getReindexCommands(). The one exception is a backend that stores data
-     * outside PostgreSQL's heap — see the noReindex gate below.
+     * outside PostgreSQL's heap. See the noReindex gate below.
      */
     async #reindex(tables, options) {
         if (this.#stopping)
@@ -696,7 +696,7 @@ class Boss extends EventEmitter {
         // rejects `reltuples / relpages` outright ("unsupported binary operator: <float4> / <int4>"),
         // so running the check would throw once per interval; YugabyteDB answers but reports relpages
         // and pg_relation_size as 0 for every relation, so nothing could ever match. Both store data in
-        // an LSM that compacts on its own, and both reject REINDEX in either form — CockroachDB with
+        // an LSM that compacts on its own, and both reject REINDEX in either form. CockroachDB with
         // the hint "CockroachDB does not require reindexing."
         if (this.#config.noReindex)
             return;
@@ -706,7 +706,7 @@ class Boss extends EventEmitter {
         // An explicit force is a request to run now; everything else waits for an interval.
         //
         // Which interval depends on whether this instance can do the work. The shared claim exists so
-        // exactly one instance in the cluster rebuilds per window — an instance that is only ever going
+        // exactly one instance in the cluster rebuilds per window. An instance that is only ever going
         // to report bloat has no business taking it, or a peer configured to rebuild would find the
         // window gone and skip the rebuild for a whole day. Detection-only passes throttle themselves
         // locally instead, on the same interval.
@@ -753,7 +753,7 @@ class Boss extends EventEmitter {
                 if (code === IN_TRANSACTION_ERROR) {
                     this.#reindexUnavailable = err.message;
                     failed.set(target.name, this.#reindexUnavailable);
-                    // Every remaining index would fail identically — the transaction wrapper is a property of
+                    // Every remaining index would fail identically. The transaction wrapper is a property of
                     // the adapter, not of this index.
                     break;
                 }
@@ -789,7 +789,7 @@ class Boss extends EventEmitter {
                 continue;
             // Ownership first: an index the role cannot touch was never a candidate, so it has no entry in
             // `failed` no matter why the pass stopped. #reindexUnavailable comes next and covers the
-            // indexes the 25001 giveup skipped without attempting — they are neither failed nor rebuilt,
+            // indexes the 25001 giveup skipped without attempting. They are neither failed nor rebuilt,
             // and reporting a size cap they are nowhere near would point at the wrong knob.
             const reason = failed.get(index.name) ??
                 (!index.owned
@@ -805,11 +805,11 @@ class Boss extends EventEmitter {
     /**
      * The REINDEX statements this instance would run, for installations where it cannot run them
      * itself. Unlike the background pass this applies no ownership filter and no size cap unless one
-     * is passed — the commands are for an operator, who may run them as a different role.
+     * is passed. The commands are for an operator, who may run them as a different role.
      */
     async getReindexCommands(options) {
         // The catalog query reads pg_class.relpages and pg_relation_size(), which the heap-less engines
-        // either reject outright or answer with zeroes — same gate as #reindex, and there is nothing to
+        // either reject outright or answer with zeroes, same gate as #reindex, and there is nothing to
         // rebuild on them anyway.
         if (this.#config.noReindex)
             return [];

package/dist/claimTimer.d.ts

@@ -25,7 +25,8 @@ import type { Clock } from './types.ts';
  * is nothing for a skew correction to correct, which is why the fix is in when the attempt is made
  * rather than in what it is measured against.
  *
- * `anchor()` is what a pass calls once its claim has been stamped. A pass that returns without ever
+ * `anchor()` is what a pass calls once its claim has been stamped, and it takes a wait of its own
+ * for the pass that knows when the row it was refused by comes due. A pass that returns without ever
  * reaching its claim - stopped, already working, an error on the way in - is re-armed from the end
  * of the callback instead, so the chain cannot die on a path that never anchored it.
  */
@@ -36,9 +37,15 @@ export declare class ClaimTimer {
     stop(): void;
     /**
      * Re-anchors the next attempt to now, because the claim this timer drives has just been stamped.
-     * Called whether the claim was won or lost: the winner needs its next attempt to fall after its
-     * own stamp, and a loser's phase is its own business either way.
+     *
+     * Called whether the claim was won or lost. A winner needs its next attempt to fall an interval
+     * after its own stamp. A loser has two phases it could take, and which one it takes is not a
+     * matter of taste: measured from its own failure it comes back an interval later, which is up to
+     * a whole interval after the row is next due, and that is the deployment's spacing the moment the
+     * instance holding the claim stops. A caller that knows when the row comes due passes that wait
+     * in `ms` instead. See Timekeeper.onCron(), which is the one claim where the difference costs
+     * work rather than latency.
      */
-    anchor(): void;
+    anchor(ms?: number): void;
 }
 //# sourceMappingURL=claimTimer.d.ts.map

package/dist/claimTimer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claimTimer.d.ts","sourceRoot":"","sources":["../src/claimTimer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAc,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,UAAU;;gBASR,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAMnE,KAAK,IAAK,IAAI;IAOd,IAAI,IAAK,IAAI;IAKb;;;;OAIG;IACH,MAAM,IAAK,IAAI;CAwChB"}
+{"version":3,"file":"claimTimer.d.ts","sourceRoot":"","sources":["../src/claimTimer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAc,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,UAAU;;gBASR,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAMnE,KAAK,IAAK,IAAI;IAOd,IAAI,IAAK,IAAI;IAKb;;;;;;;;;;OAUG;IACH,MAAM,CAAE,EAAE,GAAE,MAAiB,GAAG,IAAI;CAwCrC"}

package/dist/claimTimer.js

@@ -24,7 +24,8 @@
  * is nothing for a skew correction to correct, which is why the fix is in when the attempt is made
  * rather than in what it is measured against.
  *
- * `anchor()` is what a pass calls once its claim has been stamped. A pass that returns without ever
+ * `anchor()` is what a pass calls once its claim has been stamped, and it takes a wait of its own
+ * for the pass that knows when the row it was refused by comes due. A pass that returns without ever
  * reaching its claim - stopped, already working, an error on the way in - is re-armed from the end
  * of the callback instead, so the chain cannot die on a path that never anchored it.
  */
@@ -52,20 +53,26 @@ export class ClaimTimer {
     }
     /**
      * Re-anchors the next attempt to now, because the claim this timer drives has just been stamped.
-     * Called whether the claim was won or lost: the winner needs its next attempt to fall after its
-     * own stamp, and a loser's phase is its own business either way.
+     *
+     * Called whether the claim was won or lost. A winner needs its next attempt to fall an interval
+     * after its own stamp. A loser has two phases it could take, and which one it takes is not a
+     * matter of taste: measured from its own failure it comes back an interval later, which is up to
+     * a whole interval after the row is next due, and that is the deployment's spacing the moment the
+     * instance holding the claim stops. A caller that knows when the row comes due passes that wait
+     * in `ms` instead. See Timekeeper.onCron(), which is the one claim where the difference costs
+     * work rather than latency.
      */
-    anchor() {
+    anchor(ms = this.#ms) {
         if (this.#stopped)
             return;
         this.#anchored = true;
-        this.#arm();
+        this.#arm(ms);
     }
-    #arm() {
+    #arm(ms = this.#ms) {
         this.#disarm();
         if (this.#stopped)
             return;
-        this.#handle = this.#clock.setTimeout(() => { this.#run(); }, this.#ms);
+        this.#handle = this.#clock.setTimeout(() => { this.#run(); }, ms);
     }
     #disarm() {
         if (this.#handle !== undefined) {

package/dist/cli.js

@@ -193,7 +193,7 @@ async function createDb(config) {
     return db;
 }
 // Like getConnectionConfig, but returns null instead of exiting when no connection is
-// configured — used by commands (e.g. `plans`) where a connection is optional.
+// configured, used by commands (e.g. `plans`) where a connection is optional.
 function tryGetConnectionConfig(args) {
     const fileConfig = loadConfigFile(args.config);
     const hasConnection = args.connectionString || process.env.PGBOSS_DATABASE_URL || fileConfig.connectionString ||
@@ -303,7 +303,7 @@ async function cmdMigrate(args) {
         }
         // Render from the DB's actual version so the printed SQL is exactly what `migrate` would run.
         // Offline (or not yet installed) we can't know it, so fall back to the oldest supported starting
-        // version — the full chain — instead of a bogus "from 0" that fails on non-idempotent steps.
+        // version (the full chain) instead of a bogus "from 0" that fails on non-idempotent steps.
         const fromVersion = version ?? migrationStore.getMinVersion(schema);
         const sql = migrationStore.migrate(schema, fromVersion, migrationStore.getAllForConfig(config), config.noAdvisoryLocks, { inlineAsync: true, partitionTables });
         console.log(`-- SQL to migrate pg-boss from version ${fromVersion} to ${schemaVersion}:`);
@@ -382,7 +382,7 @@ async function cmdDoctor(args) {
         }
         console.log(`Schema "${schema}" version ${version} (latest: ${schemaVersion})`);
         if (version < schemaVersion) {
-            console.log(`⚠ Migrations pending: ${schemaVersion - version} — run "pg-boss migrate" before trusting drift results`);
+            console.log(`⚠ Migrations pending: ${schemaVersion - version}. Run "pg-boss migrate" before trusting drift results`);
         }
         // Reuse the same drift scan the boss.detectSchemaDrift() API runs, rather than duplicating the
         // catalog queries + computeSchemaDrift wiring here (the two copies had already drifted apart and
@@ -404,7 +404,7 @@ async function cmdDoctor(args) {
                 await contractor.detectClockOverride();
             if (override) {
                 console.log('\njob_now() carries a TestClock override, left behind by a test run that was');
-                console.log('killed before releasing its clock. Restoring it — make sure no instance is');
+                console.log('killed before releasing its clock. Restoring it, so make sure no instance is');
                 console.log('holding a live TestClock against this schema.');
                 await contractor.restoreClockFunction();
                 console.log('  restored.');
@@ -416,7 +416,7 @@ async function cmdDoctor(args) {
             }
         }
         if (report.building.length) {
-            console.log(`\nBuilding (async index build in progress — not yet drift) (${report.building.length}):`);
+            console.log(`\nBuilding (async index build in progress, not yet drift) (${report.building.length}):`);
             for (const i of report.building)
                 console.log(`  ${i.table}.${i.name}`);
         }
@@ -429,19 +429,19 @@ async function cmdDoctor(args) {
                 console.log(`\n⚠ INDEX BLOAT (rebuild with "pg-boss reindex") (${bloated.length}):`);
                 for (const i of bloated) {
                     const mb = Math.round(Number(i.bytes) / 1024 / 1024);
-                    console.log(`  ${i.table}.${i.name} — ${mb} MB across ${i.pages} pages, ~${i.entries} live entries`);
+                    console.log(`  ${i.table}.${i.name}: ${mb} MB across ${i.pages} pages, ~${i.entries} live entries`);
                     if (!i.owned)
                         console.log('    note: the connected role does not own this index and cannot reindex it');
                 }
             }
         }
         catch {
-            // Best effort — a role without catalog visibility should not fail the whole drift report.
+            // Best effort. A role without catalog visibility should not fail the whole drift report.
         }
-        // Extra indexes are informational (a stale pg-boss index or a user-added one) — a warning, not
+        // Extra indexes are informational (a stale pg-boss index or a user-added one). A warning, not
         // drift. Printed regardless of overall status; it never changes the exit code.
         if (report.extraIndexes.length) {
-            console.log(`\n⚠ EXTRA INDEXES (present on a managed table but not expected — harmless) (${report.extraIndexes.length}):`);
+            console.log(`\n⚠ EXTRA INDEXES (present on a managed table but not expected, harmless) (${report.extraIndexes.length}):`);
             for (const i of report.extraIndexes)
                 console.log(`  ${i.table}.${i.name}`);
         }
@@ -465,9 +465,10 @@ async function cmdDoctor(args) {
             }
         }
         if (report.invalid.length) {
-            // The definition is correct — the index is just invalid (interrupted build) — so show the DDL to
-            // drop and rebuild it, not an expected-vs-actual comparison (they would be identical).
-            console.log(`\nINVALID (present but marked invalid — drop and rebuild) (${report.invalid.length}):`);
+            // The definition is correct, since an invalid index is an interrupted build rather than a
+            // wrong shape. So show the DDL to drop and rebuild it, not an expected-vs-actual comparison,
+            // which would be identical.
+            console.log(`\nINVALID (present but marked invalid, drop and rebuild) (${report.invalid.length}):`);
             for (const i of report.invalid) {
                 console.log(`  ${i.table}.${i.name}`);
                 if (i.definition)
@@ -596,7 +597,7 @@ async function cmdReindex(args) {
             // The check reads pg_class.relpages and pg_relation_size(). CockroachDB has neither (it
             // rejects `reltuples / relpages` as an unsupported binary operator) and YugabyteDB reports
             // zeroes for every relation. --backend catches those up front (above); this stays for a target
-            // that was not declared — say what happened instead of surfacing a raw catalog error.
+            // that was not declared, say what happened instead of surfacing a raw catalog error.
             console.error(`Could not read index statistics from schema "${schema}": ${err.message}`);
             console.error('The bloat check reads pg_class.relpages and pg_relation_size(), which CockroachDB and YugabyteDB do not provide.');
             process.exitCode = 1;
@@ -625,7 +626,7 @@ async function cmdReindex(args) {
         }
         for (const index of rows) {
             const mb = Math.round(Number(index.bytes) / 1024 / 1024);
-            console.log(`  ${index.table}.${index.name} — ${mb} MB across ${index.pages} pages, ~${index.entries} live entries`);
+            console.log(`  ${index.table}.${index.name}: ${mb} MB across ${index.pages} pages, ~${index.entries} live entries`);
         }
         // Executing is different from printing: REINDEX needs ownership, so an index this role cannot
         // touch is reported up front rather than attempted for the sake of the server's error message.

package/dist/contractor.js

@@ -140,7 +140,7 @@ class Contractor {
         // Function-body and enum drift are best-effort: pg_get_functiondef is unsupported on some backends
         // (CockroachDB), so a failure here SKIPS the function check rather than aborting the whole scan.
         // `functionsSupported` must be tracked separately from an empty result: an empty `liveFunctions`
-        // means "query failed / unsupported", which is NOT the same as "no functions found" — feeding
+        // means "query failed / unsupported", which is NOT the same as "no functions found", feeding
         // `live: []` to the drift check would report every expected function as missing and flip `ok` to
         // false on every CockroachDB scan. So the check is gated (passed `undefined`) when the query throws.
         let liveFunctions = [];
@@ -162,7 +162,7 @@ class Contractor {
         }
         // Table presence is read from a catalog-only query independent of the column diff below. The column
         // query uses pg_get_expr (unsupported on some backends) and is best-effort; if it throws, the column
-        // check is skipped — but table presence must NOT collapse to "everything missing", so it comes from
+        // check is skipped, but table presence must NOT collapse to "everything missing", so it comes from
         // its own pg_class probe. pg_class is available everywhere, so this rarely throws; if it somehow
         // does, fall back to the columns-derived set rather than aborting the scan.
         let liveTables = null;

package/dist/db.js

@@ -114,7 +114,7 @@ class Db extends EventEmitter {
         const keepAliveInitialDelay = this.config.notifyKeepAliveInitialDelayMs ?? DEFAULT_LISTEN_KEEP_ALIVE_INITIAL_DELAY_MS;
         // Only self-heal once the listener has been established at least once. If the INITIAL connect
         // fails, the rejection propagates to the caller (Notifier.start), which falls back to
-        // polling-only and discards this subscription's close handle — so a reconnect scheduled from
+        // polling-only and discards this subscription's close handle, so a reconnect scheduled from
         // the client 'error' handler would be an untracked connection nothing can close, keeping the
         // event loop alive and delivering notifications into a stopped manager.
         let established = false;
@@ -198,7 +198,7 @@ class Db extends EventEmitter {
             });
             // Track the client before connecting so close() can tear down a connect still in flight
             // (e.g. shutdown during a reconnect). If connect or LISTEN then rejects, the catch ends
-            // it and rethrows — without that, a LISTEN that fails after connect() succeeded would
+            // it and rethrows. Without that, a LISTEN that fails after connect() succeeded would
             // leak an open connection. The reconnect .catch below reschedules on failure; an initial
             // failure propagates to the caller.
             client = next;