pg-boss 12.32.0 → 12.33.0

package/dist/adapters/pglite.d.ts

@@ -7,6 +7,7 @@ export interface PGliteLike {
         rows: any[];
     }>>;
     listen?(channel: string, callback: (payload: string) => void): Promise<() => Promise<void>>;
+    onLeaderChange?(callback: () => void): () => void;
 }
 export declare function fromPglite(pglite: PGliteLike): IDatabase;
 //# sourceMappingURL=pglite.d.ts.map

package/dist/adapters/pglite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pglite.d.ts","sourceRoot":"","sources":["../../src/adapters/pglite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAM5C,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAA;IACzE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC,CAAA;IACpD,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;CAC5F;AAUD,wBAAgB,UAAU,CAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CA6CzD"}
+{"version":3,"file":"pglite.d.ts","sourceRoot":"","sources":["../../src/adapters/pglite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAM5C,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAA;IACzE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC,CAAA;IACpD,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;IAC3F,cAAc,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAClD;AAmBD,wBAAgB,UAAU,CAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAwJzD"}

package/dist/adapters/pglite.js

@@ -1,3 +1,10 @@
+// PGliteWorker's error when leadership moves while a call is in flight. Matched on the message
+// rather than the constructor name: the class is anonymous after bundling, so `name` is just
+// 'Error', while the message is fixed in the worker source.
+const LEADER_CHANGED_MESSAGE = 'Leader changed, pending operation in indeterminate state';
+function isLeaderChange(err) {
+    return err instanceof Error && err.message === LEADER_CHANGED_MESSAGE;
+}
 // Adapts a PGlite instance (embedded single-connection WASM PostgreSQL) to pg-boss's IDatabase.
 // PGlite is full PostgreSQL, so it needs none of the distributed compatibility flags — pair it
 // with `backend: 'pglite'`. The user owns the PGlite instance lifecycle (construction and close).
@@ -23,17 +30,114 @@ export function fromPglite(pglite) {
         const results = await pglite.exec(text);
         return { rows: results.flatMap(r => r.rows ?? []) };
     };
+    // The statements every session must carry, kept so they can be reapplied. A plain PGlite has one
+    // session for the life of the instance and never needs that; PGliteWorker does — see below.
+    let sessionStatements = [];
+    let unsubscribeLeaderChange = null;
+    // While a reapply is in flight, every statement waits for it. Without this a query issued between
+    // the leader change and the reapply lands on a session that has not been set up yet.
+    let reapplying = null;
+    // Statements currently in flight, so a leader change can fail them itself — see executeSql.
+    const inFlight = new Set();
+    // Note what this cannot fix: because one leader instance serves every tab, session state is shared
+    // by all of them. A SET issued through one tab's adapter applies to every other tab's queries
+    // against that database, and there is no way to scope it to the instance that asked for it.
+    //
+    // Only the PGliteWorker leader holds an actual PGlite instance; the other tabs proxy into it. When
+    // the leader tab goes away, the next tab's worker constructs a *new* PGlite over the same data
+    // directory — a new backend, and so a new session. Anything set with SET is gone, and nothing in
+    // the worker replays it, so without this the session would silently revert to defaults: for the
+    // clock override specifically, back to real time with no error anywhere.
+    const watchLeaderChange = () => {
+        if (unsubscribeLeaderChange || typeof pglite.onLeaderChange !== 'function') {
+            return;
+        }
+        unsubscribeLeaderChange = pglite.onLeaderChange(() => {
+            // Fail the in-flight statements first: they were issued against a backend that no longer
+            // exists, and one of them may be holding a reapply behind it.
+            for (const fail of [...inFlight])
+                fail(new Error(LEADER_CHANGED_MESSAGE));
+            if (!sessionStatements.length)
+                return;
+            // Cleared only by the chain that set it: a second leader change during a reapply assigns a
+            // new one, and the first must not open the gate on a session the new chain has not set up.
+            const chain = applySessionStatements().catch(() => { }).then(() => {
+                if (reapplying === chain)
+                    reapplying = null;
+            });
+            reapplying = chain;
+        });
+    };
+    // PGliteWorker settles a statement that was in flight across a leader change only when it was
+    // still queued on the transaction lock: that rejection is raised before _runExclusiveTransaction
+    // enters its try/finally, so it reaches us. A statement that had already *taken* the lock never
+    // settles at all — its own rpc rejects, but the `finally` then posts _releaseTransactionLock to a
+    // tab channel the new leader has not attached to yet, and nothing will ever reply or reject it.
+    // That await swallows the original rejection and hangs forever, which for pg-boss means a
+    // locked() block stalling a maintenance cycle silently and permanently.
+    //
+    // So the leader change fails its own in-flight statements, giving a lock holder the same
+    // indeterminate-state error a queued statement already gets. The abandoned promise is left to
+    // settle or not on its own; only its late rejection has to be swallowed.
+    const raceLeaderChange = async (text, values) => {
+        if (typeof pglite.onLeaderChange !== 'function') {
+            return await run(text, values);
+        }
+        let fail;
+        const lost = new Promise((_resolve, reject) => { fail = reject; });
+        inFlight.add(fail);
+        const statement = run(text, values);
+        statement.catch(() => { });
+        try {
+            return await Promise.race([statement, lost]);
+        }
+        finally {
+            inFlight.delete(fail);
+        }
+    };
+    // Through raceLeaderChange, not run(): a reapply orphaned by a *second* leader change is the
+    // same upstream hang as any other statement, and worse here, because executeSql waits on
+    // `reapplying` - a reapply that never settles stalls the adapter permanently and silently.
+    // Failing it instead leaves the next leader change to reapply from scratch.
+    const applySessionStatements = async () => {
+        for (const statement of sessionStatements) {
+            await raceLeaderChange(statement);
+        }
+    };
     const db = {
+        // A plain PGlite is one session for the life of the instance, so these are applied once and
+        // every later statement sees them. A pooled driver re-runs them per connection; here the only
+        // thing that can take the session away is a PGliteWorker leader change.
+        async setSessionStatements(statements) {
+            sessionStatements = statements;
+            await applySessionStatements();
+        },
         async executeSql(text, values) {
+            // Re-checked, not awaited once: a second leader change during a reapply fails the first
+            // chain's in-flight statement, so that chain settles early and hands the gate back while the
+            // chain that replaced it has not reissued anything yet. Waiting again on whatever is there
+            // now is what keeps a query from reaching a session the current chain has not set up.
+            for (let pending = reapplying; pending; pending = reapplying) {
+                await pending;
+            }
             try {
-                return await run(text, values);
+                return await raceLeaderChange(text, values);
             }
             catch (err) {
-                await pglite.query('ROLLBACK').catch(() => { });
+                // A leader change leaves nothing to roll back on this side: the transaction died with the
+                // old leader's instance, and a ROLLBACK now would go to a different session that was never
+                // in it. The statement's own outcome is genuinely unknown, which is what the error says.
+                if (!isLeaderChange(err)) {
+                    await pglite.query('ROLLBACK').catch(() => { });
+                }
                 throw err;
             }
         }
     };
+    // Taken out once and kept for the adapter's life. It used to be tied to having session statements
+    // to reapply; it now also fails in-flight statements, which every adapter needs whether or not a
+    // TestClock is involved. A plain PGlite has no onLeaderChange and subscribes to nothing.
+    watchLeaderChange();
     // PGlite is embedded single-connection PostgreSQL, so LISTEN/NOTIFY works entirely in-process:
     // the same instance both NOTIFYs (via pg-boss's inlined pg_notify) and delivers to listeners.
     // Only expose `listen` when the instance actually supports it (older builds/mocks may not), so

package/dist/attorney.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attorney.d.ts","sourceRoot":"","sources":["../src/attorney.ts"],"names":[],"mappings":"AAEA,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,CAyB9F;AAiGD,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;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"}

package/dist/attorney.js

@@ -1,4 +1,5 @@
 import assert from 'node:assert';
+import { systemClock } from "./clock.js";
 import { DEFAULT_SCHEMA } from "./plans.js";
 const POLICY = {
     MAX_EXPIRATION_HOURS: 24,
@@ -409,6 +410,7 @@ function getConfig(value) {
     config.useListenNotify = ('useListenNotify' in config) ? config.useListenNotify : false;
     config.reindex = ('reindex' in config) ? config.reindex : true;
     resolveBackend(config);
+    applyClockConfig(config);
     applySchemaConfig(config);
     applyOpsConfig(config);
     applyScheduleConfig(config);
@@ -417,6 +419,16 @@ function getConfig(value) {
     validateWarningConfig(config);
     return config;
 }
+const CLOCK_METHODS = ['now', 'setTimeout', 'clearTimeout', 'setInterval', 'clearInterval'];
+function applyClockConfig(config) {
+    if (config.clock) {
+        const clock = config.clock;
+        for (const method of CLOCK_METHODS) {
+            assert(typeof clock[method] === 'function', `configuration assert: clock must implement ${method}()`);
+        }
+    }
+    config.clock = config.clock || systemClock;
+}
 function applySchemaConfig(config) {
     if (config.schema) {
         assertPostgresObjectName(config.schema);

package/dist/bam.js

@@ -28,14 +28,14 @@ class Bam extends EventEmitter {
             return;
         this.#stopped = false;
         setImmediate(() => this.#onPoll());
-        this.#pollInterval = setInterval(() => this.#onPoll(), this.#config.bamIntervalSeconds * 1000);
+        this.#pollInterval = this.#config.clock.setInterval(() => this.#onPoll(), this.#config.bamIntervalSeconds * 1000);
     }
     async stop() {
         if (this.#stopped)
             return;
         this.#stopped = true;
         if (this.#pollInterval) {
-            clearInterval(this.#pollInterval);
+            this.#config.clock.clearInterval(this.#pollInterval);
             this.#pollInterval = undefined;
         }
         while (this.#working) {

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;AACtC,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;IAWL,IAAI;IA8FJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,gBAAgB;IAwqBvF;;;;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;AACtC,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;IAWL,IAAI;IA+FJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,gBAAgB;IAwqBvF;;;;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

@@ -125,7 +125,7 @@ class Boss extends EventEmitter {
     async start() {
         if (this.#stopped) {
             this.#stopping = false;
-            this.#superviseInterval = setInterval(() => this.#onSupervise(), this.#config.superviseIntervalSeconds * 1000);
+            this.#superviseInterval = this.#config.clock.setInterval(() => this.#onSupervise(), this.#config.superviseIntervalSeconds * 1000);
             this.#stopped = false;
         }
     }
@@ -133,7 +133,7 @@ class Boss extends EventEmitter {
         if (!this.#stopped) {
             this.#stopping = true;
             if (this.#superviseInterval)
-                clearInterval(this.#superviseInterval);
+                this.#config.clock.clearInterval(this.#superviseInterval);
             this.#stopped = true;
             while (this.#maintaining) {
                 await delay(10);
@@ -154,6 +154,7 @@ class Boss extends EventEmitter {
         if (typeof (query) === 'string') {
             query = { text: query, values: [] };
         }
+        // Real time: a stopwatch around I/O reads zero on a frozen clock.
         const started = Date.now();
         const result = unwrapSQLResult(await this.#db.executeSql(query.text, query.values));
         const elapsed = (Date.now() - started) / 1000;
@@ -701,9 +702,9 @@ class Boss extends EventEmitter {
                     return;
             }
             else {
-                if (Date.now() < this.#detectOnly)
+                if (this.#config.clock.now() < this.#detectOnly)
                     return;
-                this.#detectOnly = Date.now() + this.#config.reindexIntervalSeconds * 1000;
+                this.#detectOnly = this.#config.clock.now() + this.#config.reindexIntervalSeconds * 1000;
             }
         }
         if (this.#stopping)

package/dist/cli.js

@@ -39,6 +39,8 @@ Options:
                           Non-postgres backends need this to emit schema they accept.
   --dry-run               Output SQL without executing (for plans and reindex commands)
   --force                 Rebuild every job index, not just the bloated ones (reindex)
+  --fix                   Restore a job_now() left overridden by a killed TestClock run
+                          (doctor). Only run this when no instance holds a live TestClock.
 
 Environment Variables:
   PGBOSS_DATABASE_URL     Full connection string
@@ -161,7 +163,8 @@ function parseCliArgs() {
             ssl: { type: 'boolean' },
             backend: { type: 'string' },
             'dry-run': { type: 'boolean' },
-            force: { type: 'boolean' }
+            force: { type: 'boolean' },
+            fix: { type: 'boolean' }
         },
         allowPositionals: true
     });
@@ -179,6 +182,7 @@ function parseCliArgs() {
         backend: values.backend,
         dryRun: values['dry-run'],
         force: values.force,
+        fix: values.fix,
         command: positionals[0],
         subCommand: positionals[1]
     };
@@ -385,7 +389,32 @@ async function cmdDoctor(args) {
         // carried divergent best-effort/backend-gating bugs). Contractor.detectDrift handles the
         // partitioned probe, best-effort catalog fallbacks, and backend-specific gating in one place.
         const contractor = new Contractor(db, { ...config, schema });
-        const report = await contractor.detectDrift();
+        let report = await contractor.detectDrift();
+        // --fix repairs exactly one cause of drift, and only when asked. A TestClock restores job_now()
+        // when its handle is disposed, so a run killed first leaves the override installed; but a
+        // leftover override is indistinguishable from one a peer instance is holding right now, which is
+        // why this cannot be done automatically at startup. An operator knows which it is. Everything
+        // else doctor finds is reported and never repaired.
+        if (args.fix) {
+            // The drift report is the first source, but not the only one: mismatchedFunctions comes from
+            // pg_get_functiondef, and the whole function check is skipped when that query is unsupported
+            // (CockroachDB). detectClockOverride() reads prosrc instead, so a leftover override is still
+            // found - and repaired - on a backend whose functions never reach the report at all.
+            const override = report.mismatchedFunctions.some(f => f.name === 'job_now' && plans.clockFunctionIsOverridden(f.actualDefinition)) ||
+                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('holding a live TestClock against this schema.');
+                await contractor.restoreClockFunction();
+                console.log('  restored.');
+                // Report on the repaired schema, so the summary and the exit code describe what is there now.
+                report = await contractor.detectDrift();
+            }
+            else {
+                console.log('\nNothing for --fix to repair: job_now() carries no TestClock override.');
+            }
+        }
         if (report.building.length) {
             console.log(`\nBuilding (async index build in progress — not yet drift) (${report.building.length}):`);
             for (const i of report.building)
@@ -461,6 +490,14 @@ async function cmdDoctor(args) {
                 console.log(`    expected: ${f.definition}`);
             }
         }
+        let clockOverrideNamed = false;
+        const printClockOverrideHint = (marker) => {
+            console.log(`\n${marker}job_now() carries a TestClock override, left behind by a test run that was`);
+            console.log('  killed before releasing its clock. Time is still correct, but the function no');
+            console.log('  longer inlines, so every statement that reads the clock is slower. Restore it');
+            console.log('  with "pg-boss doctor --fix", or by hand:');
+            console.log(plans.restoreClockFunction(schema).split('\n').filter(l => l.trim()).map(l => `    ${l.trim()}`).join('\n'));
+        };
         if (report.mismatchedFunctions.length) {
             console.log(`\nMISMATCHED FUNCTIONS (body differs) (${report.mismatchedFunctions.length}):`);
             for (const f of report.mismatchedFunctions) {
@@ -468,6 +505,23 @@ async function cmdDoctor(args) {
                 console.log(`    expected: ${f.definition}`);
                 console.log(`    actual:   ${f.actualDefinition}`);
             }
+            // One cause of a job_now() mismatch is common and self-inflicted: a TestClock only restores
+            // the function when its handle is disposed, so a killed run leaves the override installed.
+            // The body still returns real time for a session that never opted in, which is why nothing
+            // surfaces it at runtime - but it no longer inlines, so every statement that reads the clock
+            // pays a per-row call. Name it rather than leave an operator to read two bodies and guess.
+            const clockOverride = report.mismatchedFunctions.find(f => f.name === 'job_now' && plans.clockFunctionIsOverridden(f.actualDefinition));
+            if (clockOverride) {
+                clockOverrideNamed = true;
+                printClockOverrideHint('  ');
+            }
+        }
+        // Same hint for a backend that never produced function rows to mismatch: the check above is
+        // gated on pg_get_functiondef, which CockroachDB does not support, so the override is invisible
+        // to drift there. This probe reads prosrc and finds it anyway. It is not drift the report can
+        // show a body for, so it names the condition and stops short of printing an "actual:".
+        if (!clockOverrideNamed && await contractor.detectClockOverride()) {
+            printClockOverrideHint('⚠ ');
         }
         if (report.columnDrift.length) {
             console.log(`\nCOLUMN DRIFT (missing/unexpected columns, or default/type/nullability drift) (${report.columnDrift.length}):`);

package/dist/clock.d.ts

@@ -0,0 +1,31 @@
+import type { AttachableClock, Clock, ClockTimer, IDatabase } from './types.ts';
+export declare const systemClock: Clock;
+export declare function isAttachable(clock: Clock): clock is AttachableClock;
+interface Target {
+    db: IDatabase;
+    schema: string;
+}
+/**
+ * A clock a test drives by hand. Time only moves through setTime() and tick(); timers only fire
+ * from tick(). When attached to a schema, every pg-boss statement there reads the same time
+ * through ${schema}.job_now(), so JavaScript and Postgres agree on what "now" is.
+ */
+export declare class TestClock implements AttachableClock {
+    #private;
+    constructor(start?: Date | number | string);
+    now(): number;
+    setTimeout(fn: () => void, ms: number): ClockTimer;
+    setInterval(fn: () => void, ms: number): ClockTimer;
+    clearTimeout(handle: ClockTimer): void;
+    clearInterval(handle: ClockTimer): void;
+    /** Jumps to a time, forwards or backwards, firing nothing. */
+    setTime(t: Date | number | string): Promise<void>;
+    /**
+     * Advances by ms, firing each due timer in order at its own due time. Does not wait for I/O the
+     * callbacks start; observe effects with spies or by querying.
+     */
+    tick(ms: number): Promise<void>;
+    attach(target: Target): Promise<AsyncDisposable>;
+}
+export {};
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE/E,eAAO,MAAM,WAAW,EAAE,KAMzB,CAAA;AAED,wBAAgB,YAAY,CAAE,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,eAAe,CAEpE;AASD,UAAU,MAAM;IACd,EAAE,EAAE,SAAS,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAUD;;;;GAIG;AACH,qBAAa,SAAU,YAAW,eAAe;;gBAWlC,KAAK,GAAE,IAAI,GAAG,MAAM,GAAG,MAAmB;IAIvD,GAAG,IAAK,MAAM;IAId,UAAU,CAAE,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAInD,WAAW,CAAE,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAIpD,YAAY,CAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAKvC,aAAa,CAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAIxC,8DAA8D;IACxD,OAAO,CAAE,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD;;;OAGG;IACG,IAAI,CAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsChC,MAAM,CAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CA4ExD"}

package/dist/clock.js

@@ -0,0 +1,156 @@
+import { setImmediate } from 'node:timers/promises';
+import * as plans from "./plans.js";
+export const systemClock = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+    setInterval: (fn, ms) => setInterval(fn, ms),
+    clearInterval: (handle) => clearInterval(handle)
+};
+export function isAttachable(clock) {
+    return typeof clock.attach === 'function';
+}
+function toMillis(t) {
+    const ms = t instanceof Date ? t.getTime() : typeof t === 'number' ? t : new Date(t).getTime();
+    if (!Number.isFinite(ms)) {
+        throw new Error(`TestClock: invalid time ${String(t)}`);
+    }
+    return ms;
+}
+/**
+ * A clock a test drives by hand. Time only moves through setTime() and tick(); timers only fire
+ * from tick(). When attached to a schema, every pg-boss statement there reads the same time
+ * through ${schema}.job_now(), so JavaScript and Postgres agree on what "now" is.
+ */
+export class TestClock {
+    #now;
+    #timers = [];
+    #seq = 0;
+    #ticking = false;
+    // Every (db, schema) this clock currently pushes time to. More than one because a multi-instance
+    // test shares one clock across several PgBoss instances, each of which attaches on start(). The
+    // schema is shared, so the last handle to be disposed is the one that restores job_now() and
+    // drops the clock table; the session opt-in is separate, and each instance drops its own.
+    #targets = [];
+    constructor(start = Date.now()) {
+        this.#now = toMillis(start);
+    }
+    now() {
+        return this.#now;
+    }
+    setTimeout(fn, ms) {
+        return this.#schedule(fn, ms, null);
+    }
+    setInterval(fn, ms) {
+        return this.#schedule(fn, ms, Math.max(ms, 1));
+    }
+    clearTimeout(handle) {
+        const i = this.#timers.indexOf(handle);
+        if (i !== -1)
+            this.#timers.splice(i, 1);
+    }
+    clearInterval(handle) {
+        this.clearTimeout(handle);
+    }
+    /** Jumps to a time, forwards or backwards, firing nothing. */
+    async setTime(t) {
+        this.#now = toMillis(t);
+        await this.#push();
+    }
+    /**
+     * Advances by ms, firing each due timer in order at its own due time. Does not wait for I/O the
+     * callbacks start; observe effects with spies or by querying.
+     */
+    async tick(ms) {
+        if (this.#ticking) {
+            throw new Error('TestClock: tick() called while a tick is in progress');
+        }
+        this.#ticking = true;
+        try {
+            const target = this.#now + ms;
+            while (this.#timers.length && this.#timers[0].due <= target) {
+                const timer = this.#timers.shift();
+                if (timer.due > this.#now) {
+                    this.#now = timer.due;
+                    await this.#push();
+                }
+                // Reinsert the same object so the handle handed out by setInterval still clears it.
+                if (timer.interval !== null) {
+                    timer.due += timer.interval;
+                    timer.seq = this.#seq++;
+                    this.#insert(timer);
+                }
+                timer.fn();
+                await setImmediate();
+            }
+            this.#now = target;
+            await this.#push();
+            await setImmediate();
+        }
+        finally {
+            this.#ticking = false;
+        }
+    }
+    async attach(target) {
+        const { db, schema } = target;
+        // One batch, so the override function is never visible over an empty table: the body reads the
+        // single row and COALESCEs to pg_catalog.now() when it finds none, so a seed in a second round
+        // trip would serve real time to anything calling job_now() in between. The timestamp is a
+        // literal because a parameterised statement cannot carry more than one command; it is derived
+        // from this.#now, a number, so there is nothing here to inject.
+        //
+        // Dropped and recreated rather than IF NOT EXISTS: adopting a table that is already there would
+        // mean wiping rows this clock did not write, and dropping it on release. The name is one nobody
+        // else would pick, so a table under it is always a leftover from a killed run and safe to take.
+        await db.executeSql(`
+      DROP TABLE IF EXISTS ${plans.clockTable(schema)};
+      CREATE TABLE ${plans.clockTable(schema)} (now timestamp with time zone NOT NULL);
+      ${plans.createClockFunction(schema, { replace: true, body: plans.clockOverrideBody(schema) })}
+      INSERT INTO ${plans.clockTable(schema)} (now) VALUES (to_timestamp(${this.#now / 1000}));
+    `);
+        // The session opt-in is not issued here. attach() runs after the contractor has already opened
+        // connections and migrated, so a SET on this one session would miss every other one. PgBoss
+        // declares it through db.setSessionStatements() before anything opens; see #doStart.
+        const entry = { db, schema };
+        this.#targets.push(entry);
+        let disposed = false;
+        return {
+            [Symbol.asyncDispose]: async () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                this.#targets.splice(this.#targets.indexOf(entry), 1);
+                if (!this.#targets.some(t => t.schema === schema)) {
+                    await db.executeSql(`
+            ${plans.createClockFunction(schema, { replace: true })}
+            DROP TABLE IF EXISTS ${plans.clockTable(schema)};
+            ${plans.disableClockOverride()};
+          `);
+                }
+            }
+        };
+    }
+    #schedule(fn, ms, interval) {
+        const timer = { fn, due: this.#now + Math.max(ms, 0), seq: this.#seq++, interval };
+        this.#insert(timer);
+        return timer;
+    }
+    // Keeps #timers sorted by due time, then by scheduling order for equal due times, so tick() can
+    // always take the next timer from the front.
+    #insert(timer) {
+        let i = this.#timers.length;
+        while (i > 0) {
+            const previous = this.#timers[i - 1];
+            const laterDue = previous.due > timer.due;
+            const sameDueScheduledLater = previous.due === timer.due && previous.seq > timer.seq;
+            if (!laterDue && !sameDueScheduledLater)
+                break;
+            i--;
+        }
+        this.#timers.splice(i, 0, timer);
+    }
+    async #push() {
+        const seconds = this.#now / 1000;
+        await Promise.all(this.#targets.map(({ db, schema }) => db.executeSql(`UPDATE ${plans.clockTable(schema)} SET now = to_timestamp($1)`, [seconds])));
+    }
+}

package/dist/contractor.d.ts

@@ -11,7 +11,11 @@ declare class Contractor {
     isInstalled(): Promise<boolean>;
     start(): Promise<void>;
     private assertNoSchemaCaseVariant;
-    detectDrift(): Promise<types.SchemaDriftReport>;
+    detectDrift(options?: {
+        clockOverride?: boolean;
+    }): Promise<types.SchemaDriftReport>;
+    detectClockOverride(): Promise<boolean>;
+    restoreClockFunction(): Promise<void>;
     check(): Promise<void>;
     create(): Promise<void>;
     migrate(version: number): Promise<void>;

package/dist/contractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contractor.d.ts","sourceRoot":"","sources":["../src/contractor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAkBxC,cAAM,UAAU;IACd,MAAM,CAAC,iBAAiB,CAAE,MAAM,SAAuB,EAAE,OAAO,GAAE,KAAK,CAAC,uBAA4B;IAapG,MAAM,CAAC,cAAc,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAoB,EAAE,OAAO,GAAE,KAAK,CAAC,oBAAyB;IAS3H,MAAM,CAAC,aAAa,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAgB,EAAE,OAAO,GAAE,KAAK,CAAC,WAAgB;IAM7G,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,UAAU,CAAmB;gBAExB,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAgBpE,aAAa;IAKb,WAAW;IAKX,KAAK;YAsBG,yBAAyB;IAkCjC,WAAW,IAAK,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IA4GhD,KAAK;IAcL,MAAM;IASN,OAAO,CAAE,OAAO,EAAE,MAAM;IASxB,IAAI,CAAE,OAAO,EAAE,MAAM;IAKrB,QAAQ,CAAE,OAAO,EAAE,MAAM;CAIhC;AAED,eAAe,UAAU,CAAA"}
+{"version":3,"file":"contractor.d.ts","sourceRoot":"","sources":["../src/contractor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAkBxC,cAAM,UAAU;IACd,MAAM,CAAC,iBAAiB,CAAE,MAAM,SAAuB,EAAE,OAAO,GAAE,KAAK,CAAC,uBAA4B;IAapG,MAAM,CAAC,cAAc,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAoB,EAAE,OAAO,GAAE,KAAK,CAAC,oBAAyB;IAS3H,MAAM,CAAC,aAAa,CAAE,MAAM,SAAuB,EAAE,OAAO,SAAgB,EAAE,OAAO,GAAE,KAAK,CAAC,WAAgB;IAM7G,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,UAAU,CAAmB;gBAExB,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAgBpE,aAAa;IAKb,WAAW;IAKX,KAAK;YAsBG,yBAAyB;IAkCjC,WAAW,CAAE,OAAO,GAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IAsHzF,mBAAmB,IAAK,OAAO,CAAC,OAAO,CAAC;IASxC,oBAAoB,IAAK,OAAO,CAAC,IAAI,CAAC;IAItC,KAAK;IAcL,MAAM;IASN,OAAO,CAAE,OAAO,EAAE,MAAM;IASxB,IAAI,CAAE,OAAO,EAAE,MAAM;IAKrB,QAAQ,CAAE,OAAO,EAAE,MAAM;CAIhC;AAED,eAAe,UAAU,CAAA"}

package/dist/contractor.js

@@ -113,7 +113,7 @@ class Contractor {
     // Presence-level schema drift scan: compares the managed indexes the code expects against the live
     // catalog. Partitioned vs. non-partitioned is read from the database (job_common presence), and the
     // per-queue policy indexes are computed from the queue table, so conditional indexes are handled.
-    async detectDrift() {
+    async detectDrift(options = {}) {
         const schema = this.config.schema;
         const probe = await this.db.executeSql(plans.jobCommonExists(schema));
         const partitioned = !!probe.rows[0].name;
@@ -206,12 +206,34 @@ class Contractor {
         return drifter.computeSchemaDrift({
             indexes: { expected: expectedIndexes, live, building },
             tables: { expected: plans.expectedManagedTables(schema, partitioned, partitions), live: liveTables ?? [...new Set(liveColumns.map(c => c.table))] },
-            functions: functionsSupported ? { expected: plans.expectedManagedFunctions(schema, partitioned), live: liveFunctions } : undefined,
+            functions: functionsSupported ? { expected: plans.expectedManagedFunctions(schema, partitioned, options), live: liveFunctions } : undefined,
             columns: { expected: expectedColumns, live: liveColumns },
             constraints: canonicalPg ? { expected: plans.expectedManagedConstraints(schema, partitioned), live: liveConstraints } : undefined,
             enum: { name: 'job_state', expected: plans.EXPECTED_JOB_STATES, actual: enumLabels }
         });
     }
+    // A TestClock swaps the body of job_now() and only puts it back when its handle is disposed, so a
+    // run killed mid-test (Ctrl-C, a crashed suite, a bailed runner) leaves the override installed.
+    // Correctness survives - the body falls through to pg_catalog.now() for any session that has not
+    // opted in - but the override's subquery defeats inlining, so every statement that reads the clock
+    // pays a per-row function call instead of a constant-folded timestamp, permanently and silently.
+    // The leftover travels with the database, which matters most for an embedded one whose data
+    // directory gets committed or shipped.
+    //
+    // Best-effort in both directions: a backend or a role that cannot read pg_proc is not evidence of
+    // a problem, and must never block a start that would otherwise succeed.
+    async detectClockOverride() {
+        try {
+            const result = await this.db.executeSql(plans.getClockFunctionSource(this.config.schema));
+            return plans.clockFunctionIsOverridden(result.rows[0]?.source);
+        }
+        catch {
+            return false;
+        }
+    }
+    async restoreClockFunction() {
+        await this.db.executeSql(plans.restoreClockFunction(this.config.schema));
+    }
     async check() {
         const installed = await this.isInstalled();
         if (!installed) {

package/dist/db.d.ts

@@ -4,13 +4,18 @@ export declare const TRANSACTION_ROLLBACK_TIMEOUT_MS = 5000;
 declare class Db extends EventEmitter implements types.IDatabase, types.EventsMixin {
     private pool;
     private config;
+    private clock;
+    private sessionStatements;
     opened: boolean;
-    constructor(config: types.DatabaseOptions);
+    constructor(config: types.DatabaseOptions & {
+        clock?: types.Clock;
+    });
     events: {
         error: string;
     };
     open(): Promise<void>;
     close(): Promise<void>;
+    setSessionStatements(statements: string[]): Promise<void>;
     executeSql(text: string, values?: unknown[]): Promise<import("pg").QueryResult<any>>;
     listen(channel: string, onNotification: (payload: string) => void, onReconnect: () => void): Promise<types.ListenHandle>;
     beginTransaction(): Promise<types.TransactionHandle>;

package/dist/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAItC,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAYxC,eAAO,MAAM,+BAA+B,OAAO,CAAA;AAEnD,cAAM,EAAG,SAAQ,YAAa,YAAW,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW;IACzE,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAuB;IAGrC,MAAM,EAAE,OAAO,CAAA;gBAEF,MAAM,EAAE,KAAK,CAAC,eAAe;IAY1C,MAAM;;MAEL;IAEK,IAAI;IAMJ,KAAK;IAOL,UAAU,CAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;IAqB5C,MAAM,CACV,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EACzC,WAAW,EAAE,MAAM,IAAI,GACtB,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC;IA2JxB,gBAAgB,IAAK,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IAsFrD,eAAe,CAAC,CAAC,EAAG,EAAE,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAY/E;AAED,eAAe,EAAE,CAAA"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAItC,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAaxC,eAAO,MAAM,+BAA+B,OAAO,CAAA;AAEnD,cAAM,EAAG,SAAQ,YAAa,YAAW,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW;IACzE,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,KAAK,CAAa;IAG1B,OAAO,CAAC,iBAAiB,CAAe;IAGxC,MAAM,EAAE,OAAO,CAAA;gBAEF,MAAM,EAAE,KAAK,CAAC,eAAe,GAAG;QAAE,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAA;KAAE;IAcpE,MAAM;;MAEL;IAEK,IAAI;IAgBJ,KAAK;IAOL,oBAAoB,CAAE,UAAU,EAAE,MAAM,EAAE;IAoC1C,UAAU,CAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;IAqB5C,MAAM,CACV,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EACzC,WAAW,EAAE,MAAM,IAAI,GACtB,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC;IA2JxB,gBAAgB,IAAK,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IAsFrD,eAAe,CAAC,CAAC,EAAG,EAAE,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAY/E;AAED,eAAe,EAAE,CAAA"}