@stonyx/cron 0.2.1-alpha.35 → 0.2.1-alpha.36

package/README.md

@@ -35,6 +35,14 @@ When a job is executed, its next trigger time is updated, and it is re-inserted
 |  `register`  | `key: string, callback: Function, interval: number, runOnInit?: boolean` | Register a new job with a given interval in seconds. If `runOnInit` is true, the job runs immediately upon registration. |
 | `unregister` |                               `key: string`                              | Remove a previously registered job.                                                                                      |
 
+> **Callback semantics.** Callbacks are invoked fire-and-forget: `Cron` never waits for one to settle, and reschedules a job *before* invoking it. Two *different* jobs that fall due on the same tick may therefore overlap.
+>
+> A job that is still running when it next falls due is skipped — and **keeps** being skipped until that invocation settles. One warning is logged per stuck run (not per tick), including how long the invocation has been running. `Cron` provides no timeout by design, so **bounding your own callback is your responsibility**: a promise that never settles means that job never runs again for the lifetime of the process. Other jobs are unaffected.
+>
+> Synchronous throws and asynchronous rejections are both caught and reported through `log.error`, with the error's stack interpolated into the message. Neither can stop the scheduler.
+>
+> `interval` is **whole seconds, as a string**, and the value must be *wholly* numeric. `register` throws a `TypeError` on anything else — including **partially** numeric values: `'1h'`, `'30s'` and `'5m'` are rejected outright, **not** read as 1, 30 and 5 seconds. Cron expressions are rejected for the same reason; use `CronService` (`@stonyx/cron/service`) for those, and an empty string is rejected too. The interval is read with `Number()`, so exponent notation and surrounding whitespace resolve at full value (`'1e3'` is 1000 seconds, `' 60 '` is 60). A value that *is* wholly numeric but below `1` (`'0'`, `'-5'`) is interpretable as “as often as possible” and is clamped to `1` second with a warning rather than rejected. Intervals longer than `setTimeout`'s range (~24.9 days) are scheduled in hops rather than overflowing the timer, so they run on schedule.
+
 > `MinHeap` is also exported as a public subpath (`@stonyx/cron/min-heap`) and can be imported directly for advanced usage.
 
 ## Configuration

package/dist/main.d.ts

@@ -3,6 +3,17 @@ interface CronJob extends HeapItem {
     callback: () => void | Promise<void>;
     interval: string;
     key: string;
+    /**
+     * Timestamp (ms) at which the current invocation started; `undefined` when the
+     * job is idle. Mirrors `job.state.runningAtMs` in the service tier
+     * (`src/job.ts` `markRunning`/`applyResult`/`isDue`).
+     */
+    runningAtMs?: number;
+    /**
+     * True once a skip has been reported for the *current* invocation. Bounds the
+     * still-running warning to one line per stuck run instead of one per tick.
+     */
+    skipReported?: boolean;
 }
 export default class Cron {
     static instance: Cron | null;
@@ -13,8 +24,55 @@ export default class Cron {
     init(): Promise<void>;
     scheduleNextRun(): void;
     runDueJobs(): Promise<void>;
+    /**
+     * The one safe way this class invokes a consumer callback.
+     *
+     * Never blocks the caller, catches synchronous throws and asynchronous
+     * rejections alike, and skips the invocation entirely when the job's previous
+     * invocation has not settled yet (fire-and-forget would otherwise let a slow
+     * job stack invocations on itself).
+     */
+    safeInvoke(job: CronJob, runOnInit?: boolean): void;
+    /**
+     * Report a scheduler-level message without ever letting the logger's own
+     * failure reach the caller.
+     *
+     * `@stonyx/logs` convenience methods return a promise and write to disk
+     * through an unguarded `mkdirSync` + `fsp.appendFile`. On a read-only or full
+     * log volume that promise rejects; an unobserved rejection raised from inside
+     * the handler that exists to prevent unhandled rejections would re-create
+     * exactly the defect this class was fixed for (measured: exit code 1).
+     */
+    report(level: 'error' | 'warn', message: string): void;
+    /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
+    release(job: CronJob): void;
     register(key: string, callback: () => void | Promise<void>, interval: string, runOnInit?: boolean): void;
     unregister(key: string): void;
+    /**
+     * Read a job interval (whole seconds, as a string) as a number, WITHOUT
+     * applying the floor. Returns `null` when the value is not wholly numeric.
+     *
+     * `Number()` rather than `parseInt`, deliberately. `parseInt` stops at the
+     * first non-numeric character and so fails in the dangerous direction: it
+     * reads `'1h'` as 1, `'30s'` as 30 and `'5m'` as 5 — intervals 3600x, 120x and
+     * 60x faster than written, scheduled with no error attached to them. A `NaN`
+     * check catches a cron expression but not those, and those are the likelier
+     * typo: `stonyx-orm` hands `DB_SAVE_INTERVAL` straight through from the
+     * environment as a string. `Number()` reads the whole value or none of it, and
+     * also gets `'1e3'` (1000, not 1) and `' 60 '` (60) right.
+     *
+     * An empty or whitespace-only string is rejected rather than read as
+     * `Number('')` === 0, so a missing value is a loud error and not a job silently
+     * clamped to the floor.
+     */
+    toSeconds(interval: string): number | null;
+    /**
+     * Parse a job interval into a positive integer at or above the floor.
+     *
+     * Returns `null` when the value cannot be parsed at all, so callers can choose
+     * between failing fast (`register`) and falling back (`setNextTrigger`).
+     */
+    parseInterval(interval: string): number | null;
     setNextTrigger(job: CronJob): void;
     log(text: string, key?: string | null): void;
 }

package/dist/main.js

@@ -17,6 +17,42 @@ import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { getTimestamp } from '@stonyx/utils/date';
 import MinHeap from './min-heap.js';
+/**
+ * Floor for a job interval, in whole seconds.
+ *
+ * `runDueJobs` no longer awaits the callback, so `next.nextTrigger > now` is the
+ * drain loop's only exit condition *and* the loop has no suspension point left.
+ * An interval that fails to advance `nextTrigger` therefore spins the loop
+ * forever and blocks the event loop, rather than merely scheduling too often.
+ */
+const MIN_INTERVAL_SECONDS = 1;
+/**
+ * Ceiling for a single `setTimeout` delay, in milliseconds (2^31 - 1, ~24.9
+ * days).
+ *
+ * Node stores a timer's delay in a 32-bit signed int. A larger value overflows,
+ * is truncated to 1 ms and emits a `TimeoutOverflowWarning`, so `scheduleNextRun`
+ * would re-arm every millisecond while the job never came due — measured at
+ * `'86400000'` (a day expressed in *milliseconds*, the plausible typo): ~790
+ * wakeups a second and ~8 GB of stderr a day from a job that never runs.
+ *
+ * Long intervals are clamped and re-armed rather than rejected, so they work
+ * instead of merely failing loudly.
+ */
+const TIMEOUT_MAX_MS = 2_147_483_647;
+/**
+ * Render an unknown thrown value as log text.
+ *
+ * `@stonyx/logs` reads a second argument as `logToFile`, not as a format
+ * argument, so `log.error(message, err)` discards the error entirely *and*
+ * forces a disk write on every failure. The error has to be interpolated into
+ * the message instead — the shape `CronService.executeJob` already uses.
+ */
+function describeError(err) {
+    if (err instanceof Error)
+        return err.stack ?? `${err.name}: ${err.message}`;
+    return String(err);
+}
 export default class Cron {
     static instance;
     jobs = {};
@@ -42,7 +78,11 @@ export default class Cron {
         const nextJob = heap.peek();
         if (!nextJob)
             return;
-        const delay = Math.max(0, nextJob.nextTrigger - getTimestamp()) * 1000;
+        // Clamped to `setTimeout`'s range. `runDueJobs` finds nothing due when the
+        // clamp fires, breaks out of the drain loop, and re-arms the remainder — so
+        // an interval past the ceiling costs one extra wakeup every ~24.9 days
+        // instead of one every millisecond, forever.
+        const delay = Math.min(Math.max(0, nextJob.nextTrigger - getTimestamp()) * 1000, TIMEOUT_MAX_MS);
         this.timer = setTimeout(() => this.runDueJobs(), delay);
     }
     async runDueJobs() {
@@ -55,18 +95,118 @@ export default class Cron {
             const job = heap.pop();
             if (config.debug)
                 this.log('job has been triggered', job.key);
-            try {
-                await job.callback();
-            }
-            catch (err) {
-                log.error(`Cron job "${job.key}" failed:`, err);
-            }
+            // Reschedule *before* invoking. The callback's result is not used by this
+            // class (`runDueJobs` returns void), so awaiting it bought nothing and
+            // cost the scheduler: a callback that never settled left the job absent
+            // from the heap and stopped the timer from ever re-arming.
             this.setNextTrigger(job);
             heap.push(job);
+            this.safeInvoke(job);
         }
         this.scheduleNextRun();
     }
+    /**
+     * The one safe way this class invokes a consumer callback.
+     *
+     * Never blocks the caller, catches synchronous throws and asynchronous
+     * rejections alike, and skips the invocation entirely when the job's previous
+     * invocation has not settled yet (fire-and-forget would otherwise let a slow
+     * job stack invocations on itself).
+     */
+    safeInvoke(job, runOnInit = false) {
+        const { key } = job;
+        const context = runOnInit ? 'failed on init:' : 'failed:';
+        // The in-flight guard lives on the job object, not in a module-level set
+        // keyed by string. That is what gives each invocation an identity: the only
+        // thing that ever clears the flag is the settle handler of the invocation
+        // that set it, and that handler closes over this exact job object. A stale
+        // handler therefore cannot release a *later* invocation's guard. It also
+        // matches the in-repo idiom one tier up (`job.state.runningAtMs`).
+        //
+        // `unregister` needs no explicit clear as a result: the flag is dropped with
+        // the job object, so a re-registered key gets a fresh object and runs
+        // immediately, while the abandoned invocation can only ever release itself.
+        if (job.runningAtMs !== undefined) {
+            // Bounded: one line per stuck run, not one per tick. A permanently hung
+            // job is re-pushed and re-skipped every interval forever, which at the
+            // 1s interval this class's own tests use is ~86k log lines a day, per job
+            // — a disk-fill and ingest-cost vector on any deployment capturing stdout.
+            if (!job.skipReported) {
+                job.skipReported = true;
+                const runningForSeconds = Math.max(0, Math.round((Date.now() - job.runningAtMs) / 1000));
+                this.report('warn', `Cron job ${JSON.stringify(key)} is still running after ${runningForSeconds}s; skipping this `
+                    + 'tick and any further ticks until it settles (this warning is not repeated for this run)');
+            }
+            return;
+        }
+        job.runningAtMs = Date.now();
+        job.skipReported = false;
+        try {
+            const result = job.callback();
+            if (result && typeof result.then === 'function') {
+                Promise.resolve(result)
+                    .catch((err) => {
+                    // Braces matter: returning `report`'s value would put it back into
+                    // the chain, and `.finally` passes a rejection straight through.
+                    this.report('error', `Cron job ${JSON.stringify(key)} ${context} ${describeError(err)}`);
+                })
+                    .finally(() => { this.release(job); })
+                    // Backstop: a throw inside the error handler or the release must not
+                    // re-create the unhandled rejection this helper exists to prevent.
+                    .catch(() => { });
+                return;
+            }
+            this.release(job);
+        }
+        catch (err) {
+            this.release(job);
+            this.report('error', `Cron job ${JSON.stringify(key)} ${context} ${describeError(err)}`);
+        }
+    }
+    /**
+     * Report a scheduler-level message without ever letting the logger's own
+     * failure reach the caller.
+     *
+     * `@stonyx/logs` convenience methods return a promise and write to disk
+     * through an unguarded `mkdirSync` + `fsp.appendFile`. On a read-only or full
+     * log volume that promise rejects; an unobserved rejection raised from inside
+     * the handler that exists to prevent unhandled rejections would re-create
+     * exactly the defect this class was fixed for (measured: exit code 1).
+     */
+    report(level, message) {
+        try {
+            const result = level === 'error' ? log.error(message) : log.warn(message);
+            void Promise.resolve(result).catch(() => { });
+        }
+        catch {
+            // Nowhere left to report to; the logger must never stop the scheduler.
+        }
+    }
+    /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
+    release(job) {
+        job.runningAtMs = undefined;
+        job.skipReported = false;
+    }
     register(key, callback, interval, runOnInit = false) {
+        const seconds = this.toSeconds(interval);
+        // Fail fast rather than clamp. An interval that is not wholly a number is a
+        // programming error — a cron expression handed to the legacy class, or a
+        // duration with a unit on it (`'1h'`, `'30s'`) — and clamping or truncating
+        // it would silently run a job intended for every hour once per second,
+        // hammering whatever the callback talks to. Throwing surfaces it at the call
+        // site, at boot, before anything is scheduled. A degenerate-but-numeric
+        // interval (`'0'`, `'-5'`) is a different case: it is interpretable as "as
+        // often as possible" and is clamped to the floor with one warning.
+        if (seconds === null) {
+            throw new TypeError(`Cron job ${JSON.stringify(key)} has an invalid interval ${JSON.stringify(interval)}: `
+                + 'expected a value that is wholly a whole-second count (e.g. \'30\'). Units are not '
+                + 'accepted — \'1h\' is rejected, not read as 1. The legacy Cron class does not accept '
+                + 'cron expressions — use CronService for those.');
+        }
+        if (seconds < MIN_INTERVAL_SECONDS) {
+            this.report('warn', `Cron job ${JSON.stringify(key)} interval ${JSON.stringify(interval)} is below the `
+                + `${MIN_INTERVAL_SECONDS}s floor; clamping to ${MIN_INTERVAL_SECONDS}s`);
+        }
         const job = { callback, interval, key, nextTrigger: 0 };
         this.jobs[key] = job;
         this.setNextTrigger(job);
@@ -74,14 +214,8 @@ export default class Cron {
         if (config.debug) {
             this.log(`job has been registered with interval: ${interval}`, key);
         }
-        if (runOnInit) {
-            try {
-                callback();
-            }
-            catch (err) {
-                log.error(`Cron job "${key}" failed on init:`, err);
-            }
-        }
+        if (runOnInit)
+            this.safeInvoke(job, true);
         this.scheduleNextRun();
     }
     unregister(key) {
@@ -95,8 +229,51 @@ export default class Cron {
             this.log('job has been unregistered', key);
         this.scheduleNextRun();
     }
+    /**
+     * Read a job interval (whole seconds, as a string) as a number, WITHOUT
+     * applying the floor. Returns `null` when the value is not wholly numeric.
+     *
+     * `Number()` rather than `parseInt`, deliberately. `parseInt` stops at the
+     * first non-numeric character and so fails in the dangerous direction: it
+     * reads `'1h'` as 1, `'30s'` as 30 and `'5m'` as 5 — intervals 3600x, 120x and
+     * 60x faster than written, scheduled with no error attached to them. A `NaN`
+     * check catches a cron expression but not those, and those are the likelier
+     * typo: `stonyx-orm` hands `DB_SAVE_INTERVAL` straight through from the
+     * environment as a string. `Number()` reads the whole value or none of it, and
+     * also gets `'1e3'` (1000, not 1) and `' 60 '` (60) right.
+     *
+     * An empty or whitespace-only string is rejected rather than read as
+     * `Number('')` === 0, so a missing value is a loud error and not a job silently
+     * clamped to the floor.
+     */
+    toSeconds(interval) {
+        const trimmed = String(interval ?? '').trim();
+        if (!trimmed)
+            return null;
+        const seconds = Number(trimmed);
+        if (!Number.isFinite(seconds))
+            return null;
+        // Whole seconds; a fractional value truncates as it always has.
+        return Math.trunc(seconds);
+    }
+    /**
+     * Parse a job interval into a positive integer at or above the floor.
+     *
+     * Returns `null` when the value cannot be parsed at all, so callers can choose
+     * between failing fast (`register`) and falling back (`setNextTrigger`).
+     */
+    parseInterval(interval) {
+        const seconds = this.toSeconds(interval);
+        if (seconds === null)
+            return null;
+        return Math.max(MIN_INTERVAL_SECONDS, seconds);
+    }
     setNextTrigger(job) {
-        job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
+        // `register` rejects an unparseable interval up front; this floor is the
+        // backstop for a job object mutated after registration (`cron.jobs` is
+        // public, mutable state) and is what actually guarantees the drain loop
+        // terminates. Never let `nextTrigger` land on `NaN` or on `now`.
+        job.nextTrigger = getTimestamp() + (this.parseInterval(job.interval) ?? MIN_INTERVAL_SECONDS);
     }
     log(text, key = null) {
         if (!config.cron?.log)

package/dist/service.d.ts

@@ -15,8 +15,7 @@ interface ExecuteResult {
     summary?: string;
     durationMs?: number;
     deleted?: boolean;
-    /** Only set when `status` is `'skipped'`. */
-    reason?: 'not due' | 'already running' | 'removed';
+    reason?: string;
 }
 interface ServiceStatus {
     started: boolean;
@@ -28,7 +27,6 @@ interface ListOptions {
 }
 type OnJobDueCallback = (job: Job) => Promise<JobDueResult | void> | JobDueResult | void;
 export default class CronService {
-    #private;
     jobs: Map<string, Job>;
     heap: MinHeap<HeapEntry>;
     timer: ReturnType<typeof setTimeout> | null;
@@ -71,25 +69,6 @@ export default class CronService {
     remove(id: string): Promise<void>;
     /**
      * Manually trigger a job.
-     *
-     * Returns `{ status: 'skipped', reason }` without invoking the callback when
-     * the job is not due (`mode: 'due'`), is already in flight
-     * (`'already running'`), or was removed before the claim landed
-     * (`'removed'`). Before the phase split a forced run against an in-flight job
-     * launched a second concurrent invocation; refusing it is AC4 of #34.
-     *
-     * CONCURRENCY: the same job is bounded to one in-flight invocation on every
-     * path, and the timer path invokes due jobs one at a time. `run()` fan-out
-     * across DIFFERENT jobs is deliberately unbounded - N concurrent `run()`
-     * calls produce N concurrent consumer callbacks. Before the phase split
-     * these serialized behind the module-global lock; that serialization was the
-     * bug, not the feature (one hung callback wedged every other caller), so it
-     * is not being restored here. The fan-out is caller-driven: it is bounded by
-     * how many times the consumer chooses to call `run()`, exactly like any other
-     * async API, and the scheduler never produces it on its own. A consumer that
-     * exposes `run()` over HTTP or a CLI owns that bound the same way it owns
-     * request concurrency for every other handler. A per-invoke bound inside the
-     * service is tracked separately (#35).
      */
     run(id: string, mode?: 'due' | 'force'): Promise<ExecuteResult>;
     /**
@@ -99,25 +78,6 @@ export default class CronService {
     armTimer(): void;
     onTimer(): Promise<void>;
     findDueJobs(nowMs: number): Job[];
-    /**
-     * Execute a job in three phases:
-     *
-     *   1. claim  (locked)   - take ownership of the job, detach it from the heap
-     *   2. invoke (UNLOCKED) - await the consumer callback
-     *   3. settle (locked)   - apply the result, log it, re-insert into the heap
-     *
-     * The critical section deliberately excludes phase 2. `onJobDue` is
-     * arbitrary, unbounded consumer code; awaiting it under the module-global
-     * lock is what wedged every subsequent `locked()` call (add/update/remove)
-     * when a callback never settled.
-     *
-     * `onTimer` performs the batch claim (findDueJobs + markRunning) for all due
-     * jobs under a single lock, then enters at phase 2 via `#executeClaimed`.
-     * That entry point is a `#private` method rather than a parameter on this
-     * one: as a published `alreadyClaimed` boolean it was a supported way for a
-     * consumer to skip phase 1 entirely, which defeats the claim guard AC4 asks
-     * for and allows concurrent `onJobDue` invocations for the same job.
-     */
     executeJob(job: Job): Promise<ExecuteResult>;
     removeFromHeap(id: string): void;
     log(message: string): void;

package/dist/service.js

@@ -12,24 +12,6 @@ import { locked } from './locked.js';
 import { normalizeJobInput, recoverFlatParams } from './normalize.js';
 import RunLog from './run-log.js';
 const MAX_TIMER_DELAY_MS = 60_000;
-/**
- * Describe a thrown value without ever throwing.
- *
- * `String(err)` is not total: a null-prototype object, or any object whose
- * `toString`/`Symbol.toPrimitive` throws, raises "Cannot convert object to
- * primitive value". Consumer callbacks throw arbitrary values, so the error
- * handler itself must not be a second failure source.
- */
-function describeError(err) {
-    if (err instanceof Error)
-        return err.message;
-    try {
-        return String(err);
-    }
-    catch {
-        return 'unknown error';
-    }
-}
 export default class CronService {
     jobs;
     heap;
@@ -154,25 +136,6 @@ export default class CronService {
     }
     /**
      * Manually trigger a job.
-     *
-     * Returns `{ status: 'skipped', reason }` without invoking the callback when
-     * the job is not due (`mode: 'due'`), is already in flight
-     * (`'already running'`), or was removed before the claim landed
-     * (`'removed'`). Before the phase split a forced run against an in-flight job
-     * launched a second concurrent invocation; refusing it is AC4 of #34.
-     *
-     * CONCURRENCY: the same job is bounded to one in-flight invocation on every
-     * path, and the timer path invokes due jobs one at a time. `run()` fan-out
-     * across DIFFERENT jobs is deliberately unbounded - N concurrent `run()`
-     * calls produce N concurrent consumer callbacks. Before the phase split
-     * these serialized behind the module-global lock; that serialization was the
-     * bug, not the feature (one hung callback wedged every other caller), so it
-     * is not being restored here. The fan-out is caller-driven: it is bounded by
-     * how many times the consumer chooses to call `run()`, exactly like any other
-     * async API, and the scheduler never produces it on its own. A consumer that
-     * exposes `run()` over HTTP or a CLI owns that bound the same way it owns
-     * request concurrency for every other handler. A per-invoke bound inside the
-     * service is tracked separately (#35).
      */
     async run(id, mode = 'force') {
         const job = this.jobs.get(id);
@@ -181,10 +144,6 @@ export default class CronService {
         if (mode === 'due' && !isDue(job, Date.now())) {
             return { status: 'skipped', reason: 'not due' };
         }
-        // Deliberately NOT wrapped in locked(): executeJob takes the lock itself
-        // for its claim and settle phases only. Wrapping here would re-create the
-        // wedge through a second door, since the callback would again be awaited
-        // while a lock is held.
         return this.executeJob(job);
     }
     /**
@@ -213,51 +172,16 @@ export default class CronService {
         }
         this.running = true;
         try {
-            // Phase 1 - claim (locked). Collecting due jobs pops them off the heap
-            // and marking them running makes them un-collectable by anyone else, so
-            // both must happen under the same lock.
-            const dueJobs = await locked(() => {
+            await locked(async () => {
                 const nowMs = Date.now();
-                const due = this.findDueJobs(nowMs);
-                for (const job of due) {
+                const dueJobs = this.findDueJobs(nowMs);
+                for (const job of dueJobs) {
                     markRunning(job);
                 }
-                return due;
-            });
-            // Phases 2 and 3 run outside the claim lock. The consumer callback is
-            // awaited here holding no lock at all, so a callback that never settles
-            // cannot poison the lock chain.
-            for (const job of dueJobs) {
-                try {
-                    await this.#executeClaimed(job);
-                }
-                catch (err) {
-                    // One job's unexpected throw must not abort the batch. Every job in
-                    // `dueJobs` is already claimed - marked running and detached from the
-                    // heap - and only its own settle releases it, so aborting here would
-                    // strand every sibling permanently un-due.
-                    //
-                    // Reported on an UNGATED channel. `this.log()` returns early when
-                    // `config.cron.log` is false - a supported production setting - and a
-                    // failure here permanently unschedules the job while `status()` keeps
-                    // reporting the service healthy. Silent-and-healthy is the failure
-                    // class the phase split exists to remove, so the one handler that
-                    // survives it must not depend on a log flag. `log.error` is a Stonyx
-                    // system log type, created in the Log constructor rather than by
-                    // `defineType`, so it is always callable and never gated.
-                    //
-                    // This is the outermost handler on the timer path, so it is the one
-                    // that must not be able to throw. `log` is a shared singleton whose
-                    // transports can reach the filesystem, so its own failure is
-                    // swallowed here rather than being allowed to take the batch down.
-                    try {
-                        log.error(`Cron — Job "${job.name}" (${job.id}) execution failed unexpectedly: ${describeError(err)}`);
-                    }
-                    catch {
-                        // Nothing left to report to.
-                    }
+                for (const job of dueJobs) {
+                    await this.executeJob(job);
                 }
-            }
+            });
         }
         finally {
             this.running = false;
@@ -278,203 +202,50 @@ export default class CronService {
         }
         return due;
     }
-    /**
-     * Execute a job in three phases:
-     *
-     *   1. claim  (locked)   - take ownership of the job, detach it from the heap
-     *   2. invoke (UNLOCKED) - await the consumer callback
-     *   3. settle (locked)   - apply the result, log it, re-insert into the heap
-     *
-     * The critical section deliberately excludes phase 2. `onJobDue` is
-     * arbitrary, unbounded consumer code; awaiting it under the module-global
-     * lock is what wedged every subsequent `locked()` call (add/update/remove)
-     * when a callback never settled.
-     *
-     * `onTimer` performs the batch claim (findDueJobs + markRunning) for all due
-     * jobs under a single lock, then enters at phase 2 via `#executeClaimed`.
-     * That entry point is a `#private` method rather than a parameter on this
-     * one: as a published `alreadyClaimed` boolean it was a supported way for a
-     * consumer to skip phase 1 entirely, which defeats the claim guard AC4 asks
-     * for and allows concurrent `onJobDue` invocations for the same job.
-     */
     async executeJob(job) {
-        // -- Phase 1: claim (locked) --
-        const refusal = await locked(() => this.#claimJob(job));
-        if (refusal)
-            return { status: 'skipped', reason: refusal };
-        return this.#executeClaimed(job);
-    }
-    /**
-     * Phases 2 and 3 for a job that has already been claimed - either by
-     * `executeJob` above or by `onTimer`'s batch claim.
-     *
-     * Private: reaching this without a claim would run the consumer callback for
-     * a job nobody owns.
-     */
-    async #executeClaimed(job) {
-        // Membership re-check. The claim and the invoke are no longer in the same
-        // critical section, and sibling callbacks run unlocked, so a `remove()` can
-        // land in between AND RESOLVE - it used to deadlock. A resolved `remove()`
-        // must keep meaning "this callback will not fire": #settleJob's identity
-        // guard only cleans up afterwards, by which point the side effect has
-        // already happened. Identity, not id, so a removed-then-replaced key is
-        // caught too. Deliberately synchronous with the `onJobDue` call below -
-        // nothing can interleave between this check and the invocation.
-        //
-        // This is the ONE early return in the phase-2/3 control flow that happens
-        // after a claim, so it is the one that has to release the claim by hand.
-        // (`executeJob`'s refusal return at the call site is pre-claim; `onTimer`'s
-        // re-entrancy return never claims; every return inside `#settleJob` is
-        // already past phase 3.)
-        //
-        // Skipping settle entirely here is right - re-inserting or run-logging a
-        // removed job is exactly the resurrection `#settleJob`'s identity guard
-        // refuses, and its heap entry is already gone. But the claim itself must
-        // still come off, because the detached object is NOT unreachable: it is the
-        // object `add()` returned and `get()`/`list()` hand out, and
-        // `start(initialJobs)` re-registers those objects verbatim, `state`
-        // included. Leaving `runningAtMs` set means a consumer that persists jobs
-        // rehydrates a permanently dead one - `isDue` false forever, `run()`
-        // refused forever, `status()` reporting it healthy. That is the
-        // claim-without-settle hazard the try/finally below exists for, reached
-        // through a different door.
-        //
-        // Assigned directly rather than via `applyResult`: this must release the
-        // claim and nothing else. No run-log row, no heap entry, no lastStatus, no
-        // recomputed nextRunAtMs - the job did not run.
-        if (this.jobs.get(job.id) !== job) {
-            job.state.runningAtMs = undefined;
-            return { status: 'skipped', reason: 'removed' };
-        }
         const startMs = Date.now();
         let status = 'ok';
         let error;
         let summary;
-        let settled;
-        // The claim above marked the job running and detached it from the heap.
-        // Phase 3 is the ONLY thing that undoes either, so it must survive every
-        // non-local exit from phase 2 - including a throw from the catch handler
-        // itself. A claim with no matching settle is not a degraded state, it is a
-        // permanently dead job: `runningAtMs` set, no heap entry, `isDue` false
-        // forever and `run()` refused forever.
         try {
-            // -- Phase 2: invoke (NOT locked) --
-            try {
-                if (this.onJobDue) {
-                    const result = await this.onJobDue(job);
-                    if (result) {
-                        status = result.status || 'ok';
-                        error = result.error;
-                        summary = result.summary;
-                    }
+            if (this.onJobDue) {
+                const result = await this.onJobDue(job);
+                if (result) {
+                    status = result.status || 'ok';
+                    error = result.error;
+                    summary = result.summary;
                 }
             }
-            catch (err) {
-                status = 'error';
-                error = describeError(err);
-                this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
-            }
         }
-        finally {
-            // -- Phase 3: settle (locked) --
-            settled = await locked(() => this.#settleJob(job, status, error, summary, startMs, Date.now() - startMs));
+        catch (err) {
+            status = 'error';
+            error = err instanceof Error ? err.message : String(err);
+            this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
         }
-        return settled;
-    }
-    /**
-     * Phase 1 - claim. Must be called while holding the lock (`locked()`, whose
-     * chain is module-global and therefore shared across CronService instances).
-     *
-     * `#private`, like `#executeClaimed` and for the same reason. Published, this
-     * was a supported call performing `markRunning` + `removeFromHeap` with no
-     * guaranteed settle - the claim-without-settle shape the try/finally in
-     * `#executeClaimed` exists to prevent, and with no lease on `runningAtMs` a
-     * single such call permanently strands the job: off the heap, marked running,
-     * with nothing that will ever release it. The precondition below cannot be
-     * expressed in the type system, so the method must not be reachable from
-     * outside the class body.
-     *
-     * Returns `null` on a successful claim, or the reason the claim was refused.
-     * "already running" is what makes a second `run()` report a skip instead of
-     * launching a concurrent invocation. "removed" covers the job being deleted
-     * between `run()`'s unlocked lookup and this lock turn - claiming then would
-     * `markRunning` an orphan and, worse, `removeFromHeap` an id that may now
-     * belong to a replacement.
-     *
-     * Detaching from the heap here (rather than relying on phase 3 to push a
-     * fresh entry) is what keeps manual runs from permanently duplicating heap
-     * entries.
-     */
-    #claimJob(job) {
-        if (this.jobs.get(job.id) !== job)
-            return 'removed';
-        if (job.state.runningAtMs)
-            return 'already running';
-        markRunning(job);
-        this.removeFromHeap(job.id);
-        return null;
-    }
-    /**
-     * Phase 3 - settle. Must be called while holding the lock.
-     *
-     * `#private` for the same reason as `#claimJob`: unlocked it would run
-     * `applyResult`, a `runLog.record`, a full `removeFromHeap` rebuild, a
-     * `heap.push` and an `armTimer` with no mutual exclusion - exactly the
-     * corruption `locked()` exists to prevent.
-     */
-    #settleJob(job, status, error, summary, startMs, durationMs) {
-        try {
-            const validStatus = (status === 'ok' || status === 'error' || status === 'skipped') ? status : 'error';
-            applyResult(job, validStatus, error, durationMs);
-            // The callback ran unlocked, so this job may have been removed - or
-            // removed and re-registered under the same id (the shape
-            // `start(initialJobs)` uses) - while it was in flight. Identity, not id.
-            //
-            // Deliberately touch NOTHING here. The claim phase already detached this
-            // job's own heap entry and nothing re-added it, so there is nothing to
-            // clean up; any entry now filed under this id belongs to the
-            // replacement, and removing it by id would silently unschedule a live
-            // job. Do not resurrect a removed job's heap entry or run log either.
-            if (this.jobs.get(job.id) !== job) {
-                return { status, error, summary, durationMs };
-            }
-            // Log the run
-            this.runLog.record({
-                jobId: job.id,
-                status,
-                error,
-                summary,
-                runAtMs: startMs,
-                durationMs,
-                nextRunAtMs: job.state.nextRunAtMs,
-            });
-            // Handle one-shot auto-delete. The callback ran unlocked and may have
-            // pushed a heap entry for this job via update(), so drop it - the job is
-            // about to stop existing.
-            if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
-                this.jobs.delete(job.id);
-                this.removeFromHeap(job.id);
-                this.runLog.removeJob(job.id);
-                return { status, summary, deleted: true };
-            }
-            // Re-insert into heap if still active. The callback ran unlocked, so it
-            // may itself have added a heap entry for this job (via add/update); drop
-            // any such entry first to preserve one-entry-per-key.
-            this.removeFromHeap(job.id);
-            if (job.enabled && job.state.nextRunAtMs) {
-                this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
-            }
-            return { status, error, summary, durationMs };
+        const durationMs = Date.now() - startMs;
+        const validStatus = (status === 'ok' || status === 'error' || status === 'skipped') ? status : 'error';
+        applyResult(job, validStatus, error, durationMs);
+        // Log the run
+        this.runLog.record({
+            jobId: job.id,
+            status,
+            error,
+            summary,
+            runAtMs: startMs,
+            durationMs,
+            nextRunAtMs: job.state.nextRunAtMs,
+        });
+        // Handle one-shot auto-delete
+        if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
+            this.jobs.delete(job.id);
+            this.runLog.removeJob(job.id);
+            return { status, summary, deleted: true };
         }
-        finally {
-            // One re-arm covering every exit, rather than one per branch. The claim
-            // phase detached this job from the heap, so a timer that fired during the
-            // unlocked invoke would have found an empty heap and armed nothing -
-            // and `run()` has no `finally { armTimer() }` of its own the way
-            // `onTimer` does. Without this a manual run() can leave the scheduler
-            // with no pending wake at all.
-            this.armTimer();
+        // Re-insert into heap if still active
+        if (job.enabled && job.state.nextRunAtMs) {
+            this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
         }
+        return { status, error, summary, durationMs };
     }
     // -- Helpers ---------------------------------------------------------
     removeFromHeap(id) {
@@ -495,19 +266,6 @@ export default class CronService {
     log(message) {
         if (!config.cron?.log)
             return;
-        // `log.cron` is created by `log.defineType`, which runs in `Cron.init()`
-        // (src/main.ts) - a DIFFERENT class. A consumer wiring CronService directly
-        // never runs it, while `config/environment.js` defaults `cron.log` to true,
-        // so an unguarded call throws `log.cron is not a function`. That throw
-        // escapes executeJob's catch, and the error-reporting path must never be
-        // the thing that kills the scheduler. `src/types/stonyx.d.ts:19` declares
-        // `cron()` unconditionally, so the type system will not catch this.
-        const { logColor = '#888', logMethod = 'cron' } = config.cron ?? {};
-        if (typeof log[logMethod] !== 'function')
-            log.defineType(logMethod, logColor);
-        const method = log[logMethod];
-        if (typeof method !== 'function')
-            return;
-        method.call(log, `Cron — ${message}`);
+        log.cron(`Cron — ${message}`);
     }
 }

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.35",
+  "version": "0.2.1-alpha.36",
   "description": "Cron/job scheduler for Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",