pg-boss 12.33.3 → 12.33.5

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.js

@@ -101,7 +101,7 @@ class Bam extends EventEmitter {
         });
         try {
             let alreadyBuilt = false;
-            // A re-attempted command (a stale in_progress reclaim, or a retry of a prior 'failed' — including
+            // 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.
@@ -112,7 +112,7 @@ class Bam extends EventEmitter {
                     if (rows[0]?.invalid) {
                         // 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 —
+                        // 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) {
@@ -127,7 +127,7 @@ class Bam extends EventEmitter {
                         // 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
+                        // 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;
                     }

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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boss.d.ts","sourceRoot":"","sources":["../src/boss.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAEtC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAgHnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAsC1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAa1C,IAAI,WAAW,IAAK,OAAO,CAE1B;IAEK,KAAK;IAaL,IAAI;IAmGJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,gBAAgB;IAorBvF;;;;OAIG;IACG,kBAAkB,CAAE,OAAO,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAwB7E;AAED,eAAe,IAAI,CAAA"}
+{"version":3,"file":"boss.d.ts","sourceRoot":"","sources":["../src/boss.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAEtC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAgHnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAsC1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAa1C,IAAI,WAAW,IAAK,OAAO,CAE1B;IAEK,KAAK;IAaL,IAAI;IAmGJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,gBAAgB;IAurBvF;;;;OAIG;IACG,kBAAkB,CAAE,OAAO,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAwB7E;AAED,eAAe,IAAI,CAAA"}

package/dist/boss.js

@@ -11,7 +11,7 @@ const events = {
 // Default thresholds and warning messages
 const WARNINGS = {
     SLOW_QUERY: { seconds: 30, message: 'Warning: slow query. Your queues and/or database server should be reviewed' },
-    LARGE_QUEUE: { size: 10_000, message: 'Warning: large queue backlog. Your queue should be reviewed' },
+    LARGE_QUEUE: { size: 10_000, message: 'Warning: large queue backlog' },
     // No threshold constant: the trigger is measured, not configured. See #checkVacuum.
     XMIN_HORIZON: { message: 'Warning: the database transaction horizon is pinned, so completed jobs cannot be cleaned up' },
     AUTOVACUUM_DISABLED: { message: 'Warning: autovacuum is disabled, so nothing is reclaiming completed jobs' },
@@ -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();
@@ -312,9 +312,12 @@ class Boss extends EventEmitter {
                 // Coerce with Number(): CockroachDB returns these integer columns as strings, so a bare `>`
                 // would compare lexicographically ("100" > "9" === false) and silently miss the backlog. On
                 // standard Postgres these are already numbers, so Number() is a no-op.
-                const warnings = rowsCacheStats.filter(i => Number(i.queuedCount) > (Number(i.warningQueueSize) || this.#largeQueueSize));
-                for (const warning of warnings) {
-                    await emitAndPersistWarning(this.#warningContext, WARNING_TYPES.QUEUE_BACKLOG, WARNINGS.LARGE_QUEUE.message, warning);
+                const warnings = rowsCacheStats
+                    .map(i => ({ row: i, threshold: Number(i.warningQueueSize) || this.#largeQueueSize }))
+                    .filter(({ row, threshold }) => Number(row.queuedCount) > threshold);
+                for (const { row, threshold } of warnings) {
+                    await emitAndPersistWarning(this.#warningContext, WARNING_TYPES.QUEUE_BACKLOG, `${WARNINGS.LARGE_QUEUE.message}: queue "${row.name}" has ${Number(row.queuedCount)} jobs in the ` +
+                        `created or retry state, over its warning threshold of ${threshold}. Your queue should be reviewed`, row);
                 }
             }
             if (this.#stopping)
@@ -574,7 +577,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 +601,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 +668,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 +689,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 +699,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 +709,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 +756,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 +792,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 +808,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;