pg-boss 12.33.3 → 12.33.4

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

package/dist/drifter.js

@@ -1,10 +1,10 @@
 import { resolveSchemaName } from "./tools.js";
 const SINGLE_QUOTE_REGEX = /'/g;
-// Extracts the first balanced parenthesised group from a CREATE INDEX statement — the key-column
+// Extracts the first balanced parenthesised group from a CREATE INDEX statement. The key-column
 // list. Stops at the matching close paren, so a trailing INCLUDE(...) or WHERE(...) is excluded and
 // an inner COALESCE(...) is kept. Works on both hand-written DDL and pg_get_indexdef output (whose
 // leading `USING btree (` opens the same first group). The INCLUDE payload is not ignored, just
-// compared separately — see extractIndexIncludeList.
+// compared separately. See extractIndexIncludeList.
 function extractIndexKeyList(ddl) {
     const open = ddl.indexOf('(');
     if (open === -1)
@@ -20,11 +20,11 @@ function extractIndexKeyList(ddl) {
 }
 // Strips SQL type casts, including schema-qualified enum casts (Postgres renders a job_state literal
 // as `'active'::pgboss.job_state` and a text literal as `''::text`). Run before whitespace removal is
-// fine — casts never contain spaces.
+// fine, casts never contain spaces.
 const CAST_REGEX = /::(?:[a-z_][a-z0-9_$]*\.)?[a-z_][a-z0-9_$]*(?:\[\])?/g;
 // Normalises a key-column list so an expected list and a pg_get_indexdef list compare equal when they
 // mean the same thing: lower-cased, quotes and whitespace stripped, and type casts removed. Column
-// ORDER is preserved — an index on (a, b) must not normalise equal to (b, a), which is exactly the
+// ORDER is preserved. An index on (a, b) must not normalise equal to (b, a), which is exactly the
 // index-ordinal significance the drift check needs. Parens are kept so COALESCE(...) survives.
 function normalizeKeyList(keyList) {
     return keyList
@@ -76,13 +76,13 @@ export function indexIncludeRaw(ddl) {
     const list = extractIndexIncludeList(ddl);
     return list === null ? '' : list.replace(CAST_REGEX, '').replace(/\s+/g, ' ').trim();
 }
-// Everything after the top-level WHERE — the partial-index predicate — or '' for a non-partial index.
+// Everything after the top-level WHERE (the partial-index predicate) or '' for a non-partial index.
 function extractPredicate(ddl) {
     const m = ddl.match(/\bWHERE\b/i);
     return m ? ddl.slice(m.index + m[0].length) : '';
 }
-// Normalises a predicate for comparison. Both sides originate from pg_get_indexdef — expected from the
-// manifest, live from the catalog — so both carry pg's canonical form; this only undoes the cosmetic
+// Normalises a predicate for comparison. Both sides originate from pg_get_indexdef, expected from the
+// manifest, live from the catalog, so both carry pg's canonical form; this only undoes the cosmetic
 // differences pg can vary between two equal predicates:
 //   - casts added to every literal (`'active'::pgboss.job_state`, `'x'::text`) → stripped
 //   - `IN (a, b)` rendered as `= ANY (ARRAY[a, b])` → folded back to `IN (a, b)`
@@ -130,7 +130,7 @@ function outerParensWrapWhole(s) {
     return false;
 }
 // Removes the redundant outer parentheses pg_get_indexdef wraps a whole predicate in. Only the
-// outermost pair is stripped — inner grouping (which may be meaningful) is left intact.
+// outermost pair is stripped, inner grouping (which may be meaningful) is left intact.
 function stripOuterParens(s) {
     let out = s.trim();
     while (outerParensWrapWhole(out)) {
@@ -151,12 +151,12 @@ export function displayIndexDefinition(def) {
     const predicate = stripOuterParens(cleaned.slice(m.index + m[0].length).trim());
     return `${head} ${predicate}`;
 }
-// Extracts the body of a function definition — the text between the outer dollar-quote tags. Works on
+// Extracts the body of a function definition. The text between the outer dollar-quote tags. Works on
 // both pg-boss's own `CREATE FUNCTION ... AS $$ … $$` and Postgres's `pg_get_functiondef` output
 // (which wraps the body in `$function$ … $function$`). Postgres stores prosrc verbatim, so the two
 // bodies are byte-identical for an un-drifted function, modulo the dollar-quote tag name. Nested
 // dollar quotes with a different tag (pg-boss uses `$cmd$`) live inside the body and are preserved.
-// Returns '' when no dollar-quoted body is found — an un-diffable definition is skipped, not flagged.
+// Returns '' when no dollar-quoted body is found. An un-diffable definition is skipped, not flagged.
 export function extractFunctionBody(def) {
     const open = def.match(/\$[A-Za-z0-9_]*\$/);
     if (!open)
@@ -168,7 +168,7 @@ export function extractFunctionBody(def) {
 }
 // Normalises a function body so a hand-written definition and pg_get_functiondef's stored copy compare
 // equal despite cosmetic reindentation: runs of whitespace collapse to a single space and the ends are
-// trimmed. Case is preserved — a changed string literal or identifier is real drift.
+// trimmed. Case is preserved. A changed string literal or identifier is real drift.
 export function normalizeFunctionBody(body) {
     return body.replace(/\s+/g, ' ').trim();
 }
@@ -211,7 +211,7 @@ export function getSchemaFunctions(schema) {
   `;
 }
 // The ordered value list of an enum type, for the enum-definition diff. ORDER BY enumsortorder
-// preserves declaration order — reordering the enum is itself drift (the numeric base type makes
+// preserves declaration order, reordering the enum is itself drift (the numeric base type makes
 // created < retry < … < failed load-bearing for state comparisons).
 export function getEnumDefinition(schema, typeName = 'job_state') {
     return `
@@ -244,7 +244,7 @@ export function getSchemaColumns(schema) {
 }
 // Every ordinary ('r') or partitioned ('p') table in the schema, catalog-only (pg_class), for the
 // table-presence check. Deliberately independent of getSchemaColumns: that query uses pg_get_expr,
-// which is unsupported on some backends and is wrapped in a best-effort try/catch — deriving table
+// which is unsupported on some backends and is wrapped in a best-effort try/catch, deriving table
 // presence from its (possibly empty-on-failure) result would false-report every managed table as
 // missing whenever the column query throws. pg_class is available everywhere, so table presence stays
 // reliable even when the column diff is skipped.
@@ -296,7 +296,7 @@ function computeFunctionDrift(expected, live) {
     return { missingFunctions, mismatchedFunctions };
 }
 // Column presence / default / type / nullability diff per managed table. A table with no live columns
-// is skipped (it does not exist — table presence is reported separately), so a missing table never
+// is skipped (it does not exist, table presence is reported separately), so a missing table never
 // floods the report with every column. Default, type, and nullability drift are only checked for
 // expected tables that carry the corresponding `defaults`/`types` maps (the fixed managed tables); the
 // job/partition tables omit them and are name-only.
@@ -331,7 +331,7 @@ export function computeColumnDrift(expected, live) {
             }
             if (types && types[col]) {
                 // Both sides are the canonical format_type() form (expected from the manifest, actual from the
-                // live catalog), so a direct comparison suffices — no alias folding needed.
+                // live catalog), so a direct comparison suffices. No alias folding needed.
                 const actualType = liveCol.type ?? '';
                 if (types[col].type !== actualType) {
                     typeMismatches.push({ column: col, expected: types[col].type, actual: actualType });
@@ -374,7 +374,7 @@ export function computeConstraintDrift(expected, live) {
     }
     return drift;
 }
-// Enum diff: ordered value-set comparison. An absent enum (empty actual — pre-enum schema or a backend
+// Enum diff: ordered value-set comparison. An absent enum (empty actual, pre-enum schema or a backend
 // without enums) is not treated as drift. Order is significant; the numeric base type relies on it.
 function computeEnumDrift(name, expected, actual) {
     if (actual.length === 0)
@@ -384,13 +384,13 @@ function computeEnumDrift(name, expected, actual) {
 }
 // Presence + index definition diff: which managed indexes exist, plus (for present, valid ones) a
 // key-column-order and partial-predicate comparison. Ordinals are treated asymmetrically, the same
-// convention test/pgSchemaHelper.ts encodes — index column ORDER is significant here (an index on
+// convention test/pgSchemaHelper.ts encodes, index column ORDER is significant here (an index on
 // (a, b) differs from (b, a)); the table-column diff instead normalises ordinal position away.
 //
 // Generic engine: it carries no pg-boss knowledge. Every dimension is one optional `{ expected, live }`
-// entry — none is privileged. `indexes.building` names async builds still in progress (pulled out of
+// entry, none is privileged. `indexes.building` names async builds still in progress (pulled out of
 // "missing"); `tables.expected` is the managed table set that scopes the extra-index warning. Each
-// dimension is best-effort — callers omit the ones a backend can't support.
+// dimension is best-effort, callers omit the ones a backend can't support.
 export function computeSchemaDrift(opts = {}) {
     const expectedIndexes = opts.indexes?.expected ?? [];
     const liveIndexes = opts.indexes?.live ?? [];
@@ -412,7 +412,7 @@ export function computeSchemaDrift(opts = {}) {
         else if (idx.keys && found.def) {
             // Definition-diff: a present, valid index whose key columns/order or predicate differ from the
             // expected shape. Comparison is on the normalised forms (order-significant, format-insensitive),
-            // but the report carries the readable raw text. Only when the key list parses — an unparseable
+            // but the report carries the readable raw text. Only when the key list parses. An unparseable
             // def is skipped, not falsely flagged. (An empty normalised key list means we could not parse the
             // def; '' is never a real key list, whereas an empty predicate is legitimate for a non-partial
             // index.)
@@ -436,7 +436,7 @@ export function computeSchemaDrift(opts = {}) {
         }
     }
     // Extra indexes: standalone (non-constraint-backing) indexes on a managed table that the expected set
-    // does not account for — a stale pg-boss index or one a user added. These are informational (an extra
+    // does not account for. A stale pg-boss index or one a user added. These are informational (an extra
     // index is harmless), so they are surfaced as a warning and do NOT flip `ok`. Scoped to managed tables
     // so a user's indexes on their own tables in the schema are never reported.
     const managedTables = new Set(opts.tables?.expected ?? expectedIndexes.map(i => i.table));