test(service-job): schedule exact-count cases on an inert cron fixture (#8748) (#8774)

Seven cases in this package asserted an exact call/execution count while
`CronJobAdapter.schedule()` had registered a REAL croner job on a firing
expression. Croner fired that registration on its own schedule alongside the
explicit `trigger()`, so every one of those assertions was a claim about the
wall clock rather than about the adapter.

Reproduced by faking ONLY `Date` — real timers, croner's real scheduling path —
with the registration placed 2/5/10/15 ms before the expression's own instant.
Under the firing spellings each case gained exactly one extra handler run:
`records executions` 1 -> 2 execution rows, `retries a failing handler` 3 -> 4
calls (the self-fire re-enters a handler whose retry counter is already spent,
so it succeeds on the first attempt), and the daily kernel-rebuild case gained
an unasked-for `fired` entry at 08:00 UTC. At a 2 ms lead two of the three
stopped reproducing — croner had already passed the instant by the time it
computed `nextRun()` — which is what makes this a positional flake rather than
a deterministic failure. Under the fixture all three hold at every lead.

Four cases used '* * * * *' (hazard window once per minute) and three used a
daily expression (same defect, ~1440x rarer). All seven now schedule on the
inert `NEVER_FIRES` fixture ('0 0 30 2 *' — February 30th never occurs, so
`nextRun()` is null and the registration owns no schedule of its own).

The counts themselves are unchanged: they are the only thing here that can
catch a genuine double-scheduling regression.

`NEVER_FIRES` moves out of db-job-adapter.timeout.test.ts into a shared
test-support module so a later tidy-up cannot revive the hazard in one file
only, and both halves of the pin (the fixture cannot fire; the registration the
case actually made cannot fire) are shared assertions rather than a shape each
file re-spells by hand.


Claude-Session: https://claude.ai/code/session_01NaS1PAHJcPfAA2acnV53Tn

Co-authored-by: Claude <noreply@anthropic.com>

Author: Jack Q

packages/services/service-job/src/cron-job-adapter.test.ts

@@ -3,16 +3,32 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import { Cron, scheduledJobs } from 'croner';
 import { CronJobAdapter } from './cron-job-adapter.js';
-
+import {
+  NEVER_FIRES_SCHEDULE as CRON,
+  expectFixtureCannotFire,
+  expectInertRegistration,
+} from './never-fires.fixture.js';
+
+/**
+ * Every case below that asserts an EXACT call/execution count schedules on the
+ * inert `NEVER_FIRES` fixture, and pins that its own registration cannot fire.
+ * The rationale, and what the firing spellings cost, is in
+ * `never-fires.fixture.ts`.
+ */
 describe('CronJobAdapter', () => {
   let adapter: CronJobAdapter;
   afterEach(async () => { await adapter?.destroy(); });
 
+  it('the shared cron fixture cannot fire on its own', () => {
+    expectFixtureCannotFire();
+  });
+
   it('schedules and triggers a cron job', async () => {
     adapter = new CronJobAdapter();
     let calls = 0;
-    await adapter.schedule('daily', { type: 'cron', expression: '0 0 * * *' }, async () => { calls++; });
+    await adapter.schedule('daily', CRON, async () => { calls++; });
     expect(await adapter.listJobs()).toEqual(['daily']);
+    expectInertRegistration(adapter, 'daily');
 
     await adapter.trigger('daily');
     expect(calls).toBe(1);
@@ -35,7 +51,8 @@ describe('CronJobAdapter', () => {
 
   it('records executions', async () => {
     adapter = new CronJobAdapter();
-    await adapter.schedule('tracked', { type: 'cron', expression: '* * * * *' }, async () => {});
+    await adapter.schedule('tracked', CRON, async () => {});
+    expectInertRegistration(adapter, 'tracked');
     await adapter.trigger('tracked');
     const execs = await adapter.getExecutions('tracked');
     expect(execs).toHaveLength(1);
@@ -76,13 +93,14 @@ describe('CronJobAdapter retryPolicy / timeout (#3494)', () => {
     let calls = 0;
     await adapter.schedule(
       'flaky',
-      { type: 'cron', expression: '* * * * *' },
+      CRON,
       async () => {
         calls++;
         if (calls < 3) throw new Error(`attempt ${calls} boom`);
       },
       { retryPolicy: { maxRetries: 3, backoffMs: 1, backoffMultiplier: 1 } },
     );
+    expectInertRegistration(adapter, 'flaky');
     await adapter.trigger('flaky');
     expect(calls).toBe(3);
     const execs = await adapter.getExecutions('flaky');
@@ -95,10 +113,11 @@ describe('CronJobAdapter retryPolicy / timeout (#3494)', () => {
     let calls = 0;
     await adapter.schedule(
       'doomed',
-      { type: 'cron', expression: '* * * * *' },
+      CRON,
       async () => { calls++; throw new Error('always boom'); },
       { retryPolicy: { maxRetries: 2, backoffMs: 1 } },
     );
+    expectInertRegistration(adapter, 'doomed');
     await adapter.trigger('doomed');
     expect(calls).toBe(3); // initial + 2 retries
     const execs = await adapter.getExecutions('doomed');
@@ -109,10 +128,11 @@ describe('CronJobAdapter retryPolicy / timeout (#3494)', () => {
   it('does not retry when no retryPolicy is given (legacy behavior)', async () => {
     adapter = new CronJobAdapter();
     let calls = 0;
-    await adapter.schedule('legacy', { type: 'cron', expression: '* * * * *' }, async () => {
+    await adapter.schedule('legacy', CRON, async () => {
       calls++;
       throw new Error('boom');
     });
+    expectInertRegistration(adapter, 'legacy');
     await adapter.trigger('legacy');
     expect(calls).toBe(1);
     const execs = await adapter.getExecutions('legacy');
@@ -168,20 +188,27 @@ describe('CronJobAdapter — process-global croner name registry (#8362)', () =>
   const registeredFor = (jobName: string) =>
     scheduledJobs.filter((j) => (j.name ?? '').endsWith(jobName));
 
-  const DAILY = { type: 'cron', expression: '0 8 * * *' } as const;
+  // These cases scheduled on a CRON expression, hazardous for the same reason
+  // on a window one instant wide per day rather than per minute: `fired` and
+  // `calls` below are exact counts, and a self-fire at 08:00 UTC adds to them.
+  it('the shared cron fixture cannot fire on its own', () => {
+    expectFixtureCannotFire(CRON.expression);
+  });
 
   it('lets two live adapters hold the SAME job name — two environments, one container', async () => {
     const NAME = 'flow-time-relative:contract_expiry_reminder_flow';
     const fired: string[] = [];
 
     const envA = make();
-    await envA.schedule(NAME, DAILY, async () => { fired.push('A'); });
+    await envA.schedule(NAME, CRON, async () => { fired.push('A'); });
     // The FIRST bind must really have entered the named registry: a rebind pin
     // whose first bind registered nothing passes for the wrong reason.
     expect(registeredFor(NAME)).toHaveLength(1);
 
     const envB = make();
-    await envB.schedule(NAME, DAILY, async () => { fired.push('B'); });
+    await envB.schedule(NAME, CRON, async () => { fired.push('B'); });
+    expectInertRegistration(envA, NAME);
+    expectInertRegistration(envB, NAME);
 
     expect(registeredFor(NAME)).toHaveLength(2);
 
@@ -193,7 +220,7 @@ describe('CronJobAdapter — process-global croner name registry (#8362)', () =>
   it('frees the process-global name on destroy() — the job is STOPPED, not renamed around', async () => {
     const NAME = 'flow-schedule:nightly_rollup';
     const adapterA = make();
-    await adapterA.schedule(NAME, DAILY, async () => {});
+    await adapterA.schedule(NAME, CRON, async () => {});
 
     const [job] = registeredFor(NAME);
     expect(job).toBeDefined();
@@ -213,10 +240,11 @@ describe('CronJobAdapter — process-global croner name registry (#8362)', () =>
     // Somebody else already holds the exact name this adapter will register
     // under — the residual shape once per-instance namespacing rules out our
     // own collisions. Replace semantics: the holder is stopped, not tolerated.
-    const squatter = new Cron(DAILY.expression, { name: adapterA.cronRegistryName(NAME) }, () => {});
+    const squatter = new Cron(CRON.expression, { name: adapterA.cronRegistryName(NAME) }, () => {});
     expect(registeredFor(NAME)).toHaveLength(1);
 
-    await adapterA.schedule(NAME, DAILY, async () => { calls++; });
+    await adapterA.schedule(NAME, CRON, async () => { calls++; });
+    expectInertRegistration(adapterA, NAME);
 
     expect(squatter.isStopped()).toBe(true);
     const held = registeredFor(NAME);

packages/services/service-job/src/db-job-adapter.test.ts

@@ -4,6 +4,11 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { scheduledJobs } from 'croner';
 import { DbJobAdapter } from './db-job-adapter.js';
 import { CronJobAdapter } from './cron-job-adapter.js';
+import {
+  NEVER_FIRES_SCHEDULE as CRON,
+  expectFixtureCannotFire,
+  expectInertRegistration,
+} from './never-fires.fixture.js';
 
 function makeFakeEngine() {
   const tables = new Map<string, any[]>();
@@ -167,7 +172,16 @@ describe('DbJobAdapter — kernel rebuild (#8362)', () => {
   const registeredFor = (jobName: string) =>
     scheduledJobs.filter((j) => (j.name ?? '').endsWith(jobName));
 
-  const DAILY = { type: 'cron', expression: '0 8 * * *' } as const;
+  /**
+   * These cases inject a REAL CronJobAdapter, so `schedule()` builds a REAL
+   * croner job. They scheduled on a daily expression, whose one instant a day
+   * is a window the exact-count assertion below (`fired`) straddles just as an
+   * every-minute expression's is — 1440x rarer, same defect. The inert fixture
+   * removes the schedule entirely; see `never-fires.fixture.ts`.
+   */
+  it('the shared cron fixture cannot fire on its own', () => {
+    expectFixtureCannotFire(CRON.expression);
+  });
 
   /** One kernel's job-service wiring: the pair JobServicePlugin builds. */
   function kernel() {
@@ -178,7 +192,8 @@ describe('DbJobAdapter — kernel rebuild (#8362)', () => {
   it('destroy() destroys the CRON adapter too, freeing the process-global name', async () => {
     const NAME = 'flow-time-relative:xqao_contract_expiry_reminder_flow';
     const k = kernel();
-    await k.db.schedule(NAME, DAILY, async () => {});
+    await k.db.schedule(NAME, CRON, async () => {});
+    expectInertRegistration(k.cron, NAME);
 
     const [job] = registeredFor(NAME);
     expect(job, 'the first bind must register a REAL croner named job').toBeDefined();
@@ -197,15 +212,17 @@ describe('DbJobAdapter — kernel rebuild (#8362)', () => {
     const fired: string[] = [];
 
     const old = kernel();
-    await old.db.schedule(NAME, DAILY, async () => { fired.push('old-kernel'); });
+    await old.db.schedule(NAME, CRON, async () => { fired.push('old-kernel'); });
+    expectInertRegistration(old.cron, NAME);
     // Assert the FIRST bind landed before asserting anything about the second.
     expect(registeredFor(NAME)).toHaveLength(1);
     const oldJob = registeredFor(NAME)[0];
 
     await old.db.destroy(); // kernel evicted by the freshness probe
 
     const rebuilt = kernel();
-    await rebuilt.db.schedule(NAME, DAILY, async () => { fired.push('new-kernel'); });
+    await rebuilt.db.schedule(NAME, CRON, async () => { fired.push('new-kernel'); });
+    expectInertRegistration(rebuilt.cron, NAME);
 
     const held = registeredFor(NAME);
     expect(held).toHaveLength(1); // exactly once — not one live + one zombie

packages/services/service-job/src/db-job-adapter.timeout.test.ts

@@ -1,10 +1,14 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { Cron, scheduledJobs } from 'croner';
 import { assertEngineUpdateDispatch } from '@objectstack/metadata-core';
 import { DbJobAdapter } from './db-job-adapter.js';
 import { CronJobAdapter } from './cron-job-adapter.js';
+import {
+  NEVER_FIRES_SCHEDULE,
+  expectFixtureCannotFire,
+  expectInertRegistration,
+} from './never-fires.fixture.js';
 
 /**
  * #7734 — a job that blows its `timeout` must say so in the DURABLE record.
@@ -47,26 +51,14 @@ function makeFakeEngine() {
 }
 
 /**
- * A cron expression croner PARSES but can never fire: February 30th does not
- * exist, so `nextRun()` is `null` and the registration carries no schedule of
- * its own. The explicit `trigger()` in each case below is therefore the ONLY
- * writer of `sys_job_run`, which is what entitles these cases to assert an
- * EXACT row count.
- *
- * This was `'* * * * *'`, and under that spelling the exact-count assertions
- * were a claim about the wall clock rather than about the adapter: when a run
- * straddled a minute boundary croner fired the registration on its own, a
- * second `sys_job_run` row landed, and CI reddened on a package the offending
- * PR had usually not touched (#8628).
- *
- * `'0 0 29 2 *'` is NOT a substitute — croner resolves Feb 29 to the next leap
- * year and it would fire there. Only a date that never occurs is inert.
+ * The inert cron fixture, now shared with the sibling job suites rather than
+ * spelled a second time here (#8628, #8748): why February 30th, and why
+ * `'0 0 29 2 *'` is NOT a substitute, live in `never-fires.fixture.ts`.
  *
  * Nothing here depends on the registration being schedulable: `trigger()`
  * executes the stored record directly and never consults the schedule.
  */
-const NEVER_FIRES = '0 0 30 2 *';
-const CRON = { type: 'cron', expression: NEVER_FIRES } as const;
+const CRON = NEVER_FIRES_SCHEDULE;
 const TIMEOUT_MS = 20;
 const HANDLER_MS = 300;
 
@@ -233,7 +225,7 @@ describe('the timeout policy still applies through an injected cron adapter (#77
    * machine and reds CI only when a run happens to straddle `:00`.
    */
   it('the shared CRON fixture cannot fire on its own', () => {
-    expect(new Cron(CRON.expression, { timezone: 'UTC' }).nextRun()).toBeNull();
+    expectFixtureCannotFire(CRON.expression);
   });
 
   it('a cron-scheduled run lands a timeout row even though the adapter no longer sees the policy', async () => {
@@ -251,9 +243,7 @@ describe('the timeout policy still applies through an injected cron adapter (#77
     // holds only while that registration owns no schedule of its own. Pin both
     // halves: the job is genuinely registered (the case still exercises the
     // real adapter) and it will never fire itself (#8628).
-    const registered = scheduledJobs.find((j) => j.name === cron.cronRegistryName('cronic'));
-    expect(registered, 'the case must register a REAL croner job').toBeDefined();
-    expect(registered!.nextRun()).toBeNull();
+    expectInertRegistration(cron, 'cronic');
 
     await cron.trigger('cronic'); // fire the copy the cron adapter holds
 

packages/services/service-job/src/never-fires.fixture.ts

@@ -0,0 +1,85 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The inert cron fixture every exact-count job test in this package schedules
+ * on, and the two assertions that keep it inert.
+ *
+ * Test-only support module. Nothing in `src/index.ts` re-exports it and the
+ * package's tsup entry is `src/index.ts` alone, so it is type-checked with the
+ * rest of `src` and shipped in nothing.
+ */
+
+import { expect } from 'vitest';
+import { Cron, scheduledJobs } from 'croner';
+import type { CronJobAdapter } from './cron-job-adapter.js';
+
+/**
+ * A cron expression croner PARSES but can never fire: February 30th does not
+ * exist, so `nextRun()` is `null` and a registration on it carries no schedule
+ * of its own. An explicit `trigger()` is then the ONLY thing that can run the
+ * handler, which is what entitles a case to assert an EXACT execution count.
+ *
+ * These fixtures were spelled `'* * * * *'` (and, in the rarer cases, a real
+ * daily expression). Under those spellings every exact-count assertion in the
+ * package was a claim about the wall clock rather than about the adapter:
+ * `CronJobAdapter.schedule()` builds a REAL croner job, so when a run straddled
+ * the expression's own instant croner fired the registration alongside the
+ * explicit `trigger()`, a second execution landed, and CI reddened on a package
+ * the offending PR had usually not touched.
+ *
+ * Measured (#8748) by faking ONLY `Date` — real timers, croner's real
+ * scheduling path — with the registration placed 2/5/10/15 ms before the
+ * expression's own instant. Under the firing spellings each case gained
+ * exactly one extra handler run: `records executions` went 1 → 2 execution
+ * rows, `retries a failing handler` went 3 → 4 calls (the self-fire re-enters
+ * a handler whose retry counter is already spent, so it succeeds first try),
+ * and the daily kernel-rebuild case gained an unasked-for `fired` entry at
+ * 08:00 UTC. At a 2 ms lead two of the three no longer reproduced — croner had
+ * already passed the instant by the time it computed `nextRun()` — which is
+ * exactly why this is a positional flake rather than a deterministic failure.
+ * Under this fixture all three stay put at every lead.
+ *
+ * ⛔ `'0 0 29 2 *'` is NOT a substitute — croner resolves Feb 29 forward to the
+ * next leap year (measured: `2028-02-29T00:00:00.000Z`) and it would fire
+ * there. Only a date that never occurs at all is inert.
+ *
+ * ⛔ And the remedy is never to loosen the counts. An exact count is the only
+ * thing in this package that can catch a genuine double-scheduling regression,
+ * which is precisely what these suites exist to catch.
+ */
+export const NEVER_FIRES = '0 0 30 2 *';
+
+/** The inert fixture as a `JobSchedule`, ready to hand to `schedule()`. */
+export const NEVER_FIRES_SCHEDULE = { type: 'cron', expression: NEVER_FIRES } as const;
+
+/**
+ * Pin that the FIXTURE itself is inert.
+ *
+ * Stated as an assertion and not a comment because the failure it prevents is
+ * invisible locally: restoring a firing spelling passes on a developer machine
+ * and reds CI only when a run happens to straddle the expression's instant.
+ */
+export function expectFixtureCannotFire(expression: string = NEVER_FIRES, timezone = 'UTC'): void {
+  expect(
+    new Cron(expression, { timezone }).nextRun(),
+    `cron fixture "${expression}" must have no next run — otherwise every exact-count assertion in this file is a claim about the wall clock`,
+  ).toBeNull();
+}
+
+/**
+ * Pin that the registration a case ACTUALLY made is inert — both halves.
+ *
+ * The fixture pin above is not sufficient on its own: a case can only assert an
+ * exact count if the job it really registered owns no schedule, and a case that
+ * registered nothing at all would pass a one-sided check for the wrong reason
+ * (it would no longer be exercising the real adapter). So: registered, and
+ * unable to fire.
+ */
+export function expectInertRegistration(adapter: CronJobAdapter, jobName: string): void {
+  const registered = scheduledJobs.find((job) => job.name === adapter.cronRegistryName(jobName));
+  expect(registered, `"${jobName}": the case must register a REAL croner job`).toBeDefined();
+  expect(
+    registered!.nextRun(),
+    `"${jobName}": the registration must own no schedule of its own, or it can fire alongside trigger()`,
+  ).toBeNull();
+}