@stonyx/cron 0.2.1-alpha.60 → 0.2.1-alpha.62

package/README.md

@@ -51,7 +51,7 @@ When a job is executed, its next trigger time is updated, and it is re-inserted
 
 The default export above is `Cron`: a fire-and-forget interval registry. `@stonyx/cron/service` is a separate, heavier class for jobs that need CRUD, persistence, a run log and error backoff. It is not a drop-in replacement and the two do not share a scheduler.
 
-The two classes agree on the guarantee — the same job is never run concurrently with itself, and different jobs may overlap — but not on the mechanism or on what you can observe. `Cron` invokes callbacks fire-and-forget and reports a skipped run only through the `config.cron`-gated log. `CronService` **awaits** `onJobDue`, its return value shapes `status`/`error`/`summary`, and a refused run comes back to the caller as a value that no log setting can suppress — it is not logged.
+The two classes agree on the guarantee — the same job is never run concurrently with itself, and different jobs may overlap — but not on the mechanism or on what you can observe. `Cron` invokes callbacks fire-and-forget and reports a skipped run only as an ungated `log.warn` line, one per stuck run, never as a value. `CronService` **awaits** `onJobDue`, its return value shapes `status`/`error`/`summary`, and a refused run comes back to the caller as a value that no log setting can suppress — it is not logged. The two therefore agree on one more thing than the contrast suggests: neither can have a *refused* run made silent by `config.cron.log` — `Cron`'s skip warning is ungated, and `CronService`'s refusal is a return value rather than a log line. A job *failure* is the opposite case, and there the two classes genuinely diverge; see [Configuration](#configuration).
 
 ```js
 import CronService from '@stonyx/cron/service';
@@ -81,14 +81,31 @@ const result = await service.run(job.id, 'force');
 
 **Concurrency.** A job is bounded to one in-flight invocation on every path — manual `run()` and the timer both claim it first. **Different** jobs are not bounded: the callback is deliberately invoked outside the internal lock, so N concurrent `run()` calls on N distinct jobs produce N concurrent callbacks. The scheduler itself never generates that fan-out (its timer path invokes a due batch sequentially); only a caller can. If you drive `run()` from a request handler, bound it on your side. Taking the callback out of the lock is what stops a callback that never settles from blocking `add`/`update`/`remove`; restoring the bound by putting it back would restore that deadlock.
 
+**The residual, stated plainly.** Taking the callback out of the lock fixes
+`add`/`update`/`remove`; it does **not** bound the callback. A callback that
+never settles still holds its job's claim forever, and because the timer's
+re-entrancy latch is only released when the batch settles, it also **stops the
+timer loop for every other job** — silently, with `status()` still reporting
+`started: true`. There is no execution timeout by design, so bounding your own
+callback is your responsibility, exactly as it is for `Cron`. Only a real
+process restart recovers it: `start()` releases a claim whose owner is provably
+gone, but an object still held in this process is deliberately left alone.
+Tracked as #35.
+
 ### Breaking changes in this line
 
-Four consumer-visible changes landed with the phase split (#34). All are measured against the emitted `dist/service.d.ts`:
+Five consumer-visible changes landed with the phase split (#34). Only the first
+two are visible in the emitted `dist/service.d.ts`; the rest are runtime
+behaviour and a type-checker will not find them for you. The measured
+`dist/service.d.ts` delta against the previous release is exactly three things:
+the class gained `#private;`, `reason` narrowed, and six type declarations
+gained `export`. `dist/main.d.ts` is unchanged.
 
 1. **`ExecuteResult.reason` narrowed** from `string` to `'not due' | 'already running' | 'removed'`, and gained the `'removed'` member. Comparing it against a literal outside the union, or `switch`ing on one, is now a compile error (`TS2367` / `TS2678`). Assigning it into `string | undefined` and spreading it are unaffected. The type is exported as `SkipReason`.
 2. **`CronService` is nominally typed.** It carries ECMAScript hard-private members, so the declarations emit `#private;` and a structurally hand-built test double no longer assigns to `CronService` (`TS2741: Property '#private' is missing`). The break is one-directional: `class X extends CronService` still compiles, and assigning a real `CronService` to your own hand-written interface still compiles. **Migration:** declare your own interface and depend on that instead of a `CronService`-typed mock.
-3. **`claimJob`, `settleJob` and `executeClaimed` are not published.** They were never a supported API; a claim taken without its matching settle strands the job permanently.
-4. **`run()` no longer serializes across jobs** — see the concurrency note above.
+3. **`claimJob`, `settleJob` and `executeClaimed` are not published.** Not a change against the previous release — these members did not exist there at all. Listed because they are new internals that look like API and are deliberately unreachable: a claim taken without its matching settle strands the job permanently in-process. Guarded by `test/unit/publish-surface-test.ts`.
+4. **`run()` no longer serializes across jobs** — a runtime change, not a d.ts one. See the concurrency note above.
+5. **`start()` now throws on a row it cannot use.** A `Job` whose `state` is missing or frozen — `structuredClone` + `Object.freeze` is an ordinary defensive rehydration — makes `start()` reject where the previous release resolved and carried on. Measured: previous release resolves and leaves the stale claim in place; this line throws `TypeError: Cannot assign to read only property 'runningAtMs'`. The timer is still armed for the rows loaded before the throw, so this surfaces at your `await` instead of as an unhandled rejection from inside a timer callback later. **Migration:** if your store hands back frozen rows, thaw `state` before passing them, or catch at the `start()` call site.
 
 `SkipReason`, `ExecuteResult`, `JobDueResult`, `ServiceStatus`, `ListOptions` and `OnJobDueCallback` are all exported from `@stonyx/cron/service`, so an exhaustive handler over `reason` is expressible.
 
@@ -104,9 +121,28 @@ config.cron = {
 config.debug = true; // optional: debug logs for job registration and execution
 ```
 
-`config.cron.log` gates **informational** messages only. Error reports and the
-stuck-job warning described above are never gated by it, so setting it to `false`
-cannot make a dropped execution silent.
+`config.cron.log` gates the `log.cron` channel only. **The two classes route job
+failures differently, so what `log: false` costs you depends on which one you are
+running.** Measured on this build, with a callback that throws:
+
+| | Failure channel | Records with `log: false` |
+| :--- | :--- | :--- |
+| `Cron` (default export) | ungated `log.error` | emitted — unchanged |
+| `CronService` | **gated** `log.cron` | **none** |
+
+- **`Cron`** reports a callback's throw or rejection through `log.error`, and the
+  stuck-job warning described above through `log.warn`. Neither is gated, so
+  setting `log` to `false` cannot make a dropped or failed execution silent.
+- **`CronService`** reports a job whose `onJobDue` callback throws through the
+  **gated** channel, so `log: false` yields **zero** log records for that
+  failure. It stays observable as `ExecuteResult.error` and as a run-log row —
+  but a job driven off the timer rather than `run()` has no caller to read that
+  return value, so the failure is visible only in the run log. Only the timer
+  path's *unexpected* internal throw (a fault in the scheduler itself, not in
+  your callback) is reported on the ungated `log.error` channel.
+
+If you set `log: false` in production and rely on `CronService`, read failures
+from the run log or from `ExecuteResult`, not from the log file.
 
 ## License
 

package/dist/main.js

@@ -29,12 +29,28 @@ const MAX_LOGGED_ERROR_LENGTH = 512;
  * become the literal two characters so the content survives for a reader, and
  * the length cap keeps one pathological value from swamping the file.
  *
- * Kept byte-identical to the `forLog` landing in `src/service.ts` on #34: the
- * two tiers render the same untrusted values into the same log file, and a
- * reader diagnosing a forged record should not have to know which tier wrote
- * it. Duplicated rather than shared because the two land on separate branches;
- * folding them into one helper is a follow-up once both are on `dev`, not a
- * cross-PR dependency that would make either unmergeable alone.
+ * DIVERGED from the `forLog` in `src/service.ts`, deliberately — this copy is
+ * NOT byte-identical to it and must not be folded into it by assuming it is.
+ * (An earlier version of this docblock claimed byte-identity; #34's `fac09cb`
+ * falsified that, and the two bodies now measure unequal.) `service.ts`'s is
+ * TOTAL: it wraps the coercion in `String(value)` and a `try`, returning
+ * `'<unrenderable value>'` rather than throwing. This one is not.
+ *
+ * The divergence is correct on the merits, and the reason is the call site, not
+ * the helper. Both of this copy's callers are the two `forLog(...)` calls in
+ * `describeError` directly below (`:82`, `:85`), and both are INSIDE that
+ * function's own `try`, so a `TypeError` from `value.replace` on a
+ * non-string degrades to `'<thrown value could not be rendered>'` and the log
+ * record is still produced. `service.ts`'s callers are not so contained: `:692`
+ * sits in a bare `catch` with nothing above it, and `:571`'s enclosing `catch`
+ * has nothing left to report to — so a throw there destroyed the failure
+ * record outright (measured: 0 records for a job that failed). That is why
+ * totality was a live defect there and is not one here.
+ *
+ * Duplicated rather than shared because the two landed on separate branches.
+ * The fold is still wanted, but whoever performs it MUST adopt `service.ts`'s
+ * total version as the survivor: folding to this one would silently revert
+ * `fac09cb`. See #66, which carries the consolidation.
  */
 function forLog(value, maxLength) {
     const flattened = value.replace(/\r\n|[\r\n\u2028\u2029]/g, '\\n');

package/dist/service.d.ts

@@ -44,7 +44,46 @@ export default class CronService {
     onJobDue: OnJobDueCallback | null;
     constructor();
     /**
-     * Start the service. Loads jobs from store (if any), arms timer.
+     * Start the service. Loads jobs from store (if any), arms timer. A no-op if
+     * already started.
+     *
+     * `initialJobs` crosses a serialization boundary — it is whatever the
+     * consumer's store handed back — so `Job[]` is a compile-time claim about
+     * runtime data. Three behaviours follow from that and are worth knowing
+     * before you call this, because all three are deliberate and two of them
+     * differ from a plain "load and arm":
+     *
+     * 1. WRITES TO `row.state`. A STALE claim (`state.runningAtMs` set by a
+     *    process that is gone) is released, because nothing else ever will —
+     *    there is no lease on the field (#35) — and left in place it is a job
+     *    that is dead forever while `status()` reports it healthy. A LIVE claim,
+     *    held by an invocation still running in this process, is left alone:
+     *    releasing it would let the timer start a second concurrent invocation of
+     *    a job that is already running.
+     *
+     * 2. THROWS on a row this class cannot use, rather than accepting it. A row
+     *    whose `state` is missing, or frozen (`structuredClone` + `Object.freeze`
+     *    is an ordinary defensive rehydration), throws out of `start()` where the
+     *    caller's own `await` can catch it. The alternative is a `TypeError` from
+     *    inside a bare timer callback later — an unhandled rejection, and
+     *    process-fatal under Node's default.
+     *
+     * 3. ARMS THE TIMER EVEN IF IT THROWS. The rows loaded before the throw are
+     *    registered and scheduled. Without this, a throw leaves `started: true`
+     *    (so a retry is a no-op) with jobs in the heap and no timer: nothing ever
+     *    fires and `status()` still reports healthy.
+     *
+     * Which of the three you can observe depends on the CONTENT of the rows, not
+     * on whether they were deserialized — 1 fires only on a row that already
+     * carries a claim, and 2/3 only on a row this class cannot use. Hand it
+     * well-formed deserialized rows with no claim set and none of the three is
+     * observable. Hand it a deserialized row that DOES carry one and 1 and 2 are
+     * exactly what you get: measured, a stale `state.runningAtMs` of 1 comes back
+     * `undefined`, and a `structuredClone` + `Object.freeze` row makes `start()`
+     * throw `TypeError: Cannot assign to read only property 'runningAtMs'` with
+     * the timer still armed behind it. Hand it live `Job` objects this service is
+     * currently executing and only 1 is in play, by design — and on those it
+     * deliberately does nothing.
      */
     start(initialJobs?: Job[]): Promise<void>;
     /**

package/dist/service.js

@@ -43,9 +43,39 @@ const MAX_LOGGED_NAME_LENGTH = 120;
  * text. Newlines become the literal two characters so the content survives for
  * a reader, and the length cap keeps one pathological value from swamping the
  * file.
+ *
+ * TOTAL, for the same reason `describeError` below is total, and the parameter
+ * is coerced even though it is typed `string`. `job.name` is typed `string` but
+ * that is a compile-time claim about runtime data: `normalize.ts` only
+ * GENERATES a name when the field is falsy, so `add({ name: 12345 })` stores a
+ * number through the public API, and `start(initialJobs)` takes names verbatim
+ * from the consumer's store — the same untrusted boundary `start()` already
+ * hardens `state` against.
+ *
+ * Fixed HERE rather than by coercing in `normalize`, deliberately. Coercing at
+ * `normalize` closes the `add()` path only; the rehydration path bypasses both
+ * `normalize` and `createJob` entirely, and that is the path this class already
+ * treats as hostile. And this helper is on the ERROR path — a helper that
+ * throws while building an error report destroys the report it exists to
+ * produce. Measured pre-fix: `run()` rejected with `TypeError: value.replace is
+ * not a function` instead of returning an `ExecuteResult`, and on the timer
+ * path the failure record was swallowed entirely (0 records for a job that
+ * failed) because the throw happened inside the reporter's own `try`.
+ *
+ * `String(value)` alone is NOT enough: a value whose `toString` or
+ * `Symbol.toPrimitive` throws raises out of the coercion itself, so the `try`
+ * is load-bearing and not belt-and-braces. Kept typed `string` rather than
+ * widened to `unknown` so call sites still get compile-time pressure; the
+ * runtime coercion is the defence, not the signature.
  */
 function forLog(value, maxLength) {
-    const flattened = value.replace(/\r\n|[\r\n\u2028\u2029]/g, '\\n');
+    let flattened;
+    try {
+        flattened = String(value).replace(/\r\n|[\r\n\u2028\u2029]/g, '\\n');
+    }
+    catch {
+        return '<unrenderable value>';
+    }
     return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}...` : flattened;
 }
 /**
@@ -70,8 +100,11 @@ function forLog(value, maxLength) {
  * differ: it renders for a log line only, so it prefers `err.stack`; this one
  * is also returned to the caller as `ExecuteResult.error` and persisted in a
  * per-job run log, where a stack would be an unbounded blob in every stored
- * failure. Recorded in `docs/architecture.md` under Error Handling — do not
- * merge them into a shared helper without reading that first.
+ * failure. Recorded in `docs/architecture.md` under Code Patterns &
+ * Conventions -> Private Members -> "Two `describeError` helpers, deliberately
+ * not shared (#34 / #36)" — do not merge them into a shared helper without
+ * reading that first. NOT the `### Error Handling` section further down, which
+ * is about the legacy `Cron` and does not carry this decision.
  */
 function describeError(err) {
     try {
@@ -81,6 +114,33 @@ function describeError(err) {
         return 'unknown error';
     }
 }
+/**
+ * Job objects whose claim is held by an invocation still running IN THIS
+ * PROCESS. Added by phase 1, removed by phase 3 (or by the one hand-release in
+ * `#executeClaimed`), so membership is exactly "a settle is still coming".
+ *
+ * This exists so `start()` can tell a STALE claim from a LIVE one. Both look
+ * identical in `job.state.runningAtMs` — a number — but they need opposite
+ * treatment: a stale claim must be released (it is #34's permanently-dead job,
+ * and nothing reaps it) while a live one must be left alone (releasing it lets
+ * the timer launch a second concurrent invocation of a job that is already
+ * running, breaking the one invariant this class advertises).
+ *
+ * Keyed on the Job OBJECT, not the id, and module-level rather than per
+ * instance, for the two reasons that make those the only workable choices:
+ *
+ *   - Object identity is what makes it correct across `CronService` instances.
+ *     A second service handed live rows sees the same objects, so it inherits
+ *     the answer rather than guessing; a per-instance set would report "not in
+ *     flight" for a claim a sibling instance is holding. `locked()`'s chain is
+ *     already module-global for the same reason.
+ *   - Identity is also what makes it correct after a real crash. A restart
+ *     deserializes its rows, so those are new objects and are never members —
+ *     the #34 release still fires, which is the whole point of it.
+ *
+ * `WeakSet`, so a job that is removed and dropped mid-flight is not retained.
+ */
+const inFlight = new WeakSet();
 export default class CronService {
     jobs;
     heap;
@@ -101,7 +161,46 @@ export default class CronService {
     }
     // -- Lifecycle -------------------------------------------------------
     /**
-     * Start the service. Loads jobs from store (if any), arms timer.
+     * Start the service. Loads jobs from store (if any), arms timer. A no-op if
+     * already started.
+     *
+     * `initialJobs` crosses a serialization boundary — it is whatever the
+     * consumer's store handed back — so `Job[]` is a compile-time claim about
+     * runtime data. Three behaviours follow from that and are worth knowing
+     * before you call this, because all three are deliberate and two of them
+     * differ from a plain "load and arm":
+     *
+     * 1. WRITES TO `row.state`. A STALE claim (`state.runningAtMs` set by a
+     *    process that is gone) is released, because nothing else ever will —
+     *    there is no lease on the field (#35) — and left in place it is a job
+     *    that is dead forever while `status()` reports it healthy. A LIVE claim,
+     *    held by an invocation still running in this process, is left alone:
+     *    releasing it would let the timer start a second concurrent invocation of
+     *    a job that is already running.
+     *
+     * 2. THROWS on a row this class cannot use, rather than accepting it. A row
+     *    whose `state` is missing, or frozen (`structuredClone` + `Object.freeze`
+     *    is an ordinary defensive rehydration), throws out of `start()` where the
+     *    caller's own `await` can catch it. The alternative is a `TypeError` from
+     *    inside a bare timer callback later — an unhandled rejection, and
+     *    process-fatal under Node's default.
+     *
+     * 3. ARMS THE TIMER EVEN IF IT THROWS. The rows loaded before the throw are
+     *    registered and scheduled. Without this, a throw leaves `started: true`
+     *    (so a retry is a no-op) with jobs in the heap and no timer: nothing ever
+     *    fires and `status()` still reports healthy.
+     *
+     * Which of the three you can observe depends on the CONTENT of the rows, not
+     * on whether they were deserialized — 1 fires only on a row that already
+     * carries a claim, and 2/3 only on a row this class cannot use. Hand it
+     * well-formed deserialized rows with no claim set and none of the three is
+     * observable. Hand it a deserialized row that DOES carry one and 1 and 2 are
+     * exactly what you get: measured, a stale `state.runningAtMs` of 1 comes back
+     * `undefined`, and a `structuredClone` + `Object.freeze` row makes `start()`
+     * throw `TypeError: Cannot assign to read only property 'runningAtMs'` with
+     * the timer still armed behind it. Hand it live `Job` objects this service is
+     * currently executing and only 1 is in play, by design — and on those it
+     * deliberately does nothing.
      */
     async start(initialJobs) {
         if (this.started)
@@ -121,15 +220,15 @@ export default class CronService {
         try {
             if (initialJobs) {
                 for (const job of initialJobs) {
-                    // A `runningAtMs` on a rehydrated job is always stale. The claim it
-                    // records was taken by a process that is gone, so nothing will ever
-                    // settle it, and nothing reaps it — there is no lease on the field
-                    // (tracked on #35). Left in place it is a permanently dead job that
-                    // still reports healthy: `isDue` returns false forever because of the
-                    // flag, `run()` answers `'already running'` forever, `update()` never
-                    // touches `state.runningAtMs`, and `status()` counts it like any other.
-                    // The consumer's only recovery would be remove() + add(), losing the
-                    // job id and its run history.
+                    // A STALE `runningAtMs` records a claim taken by a process that is
+                    // gone. Nothing will ever settle it, and nothing reaps it — there is
+                    // no lease on the field (tracked on #35). Left in place it is a
+                    // permanently dead job that still reports healthy: `isDue` returns
+                    // false forever because of the flag, `run()` answers
+                    // `'already running'` forever, `update()` never touches
+                    // `state.runningAtMs`, and `status()` counts it like any other. The
+                    // consumer's only recovery would be remove() + add(), losing the job
+                    // id and its run history.
                     //
                     // Same hazard, same treatment as the hand-release on the `'removed'`
                     // path in `#executeClaimed`: a claim with no reachable settle must be
@@ -138,19 +237,36 @@ export default class CronService {
                     // run, so it gets no run-log row, no `lastStatus`, and no recomputed
                     // `nextRunAtMs`; it is rescheduled from the store's own value below.
                     //
-                    // Written unconditionally, and deliberately NOT guarded on a
-                    // `job.state.runningAtMs` read. Guarding it makes `start()` accept a
-                    // row whose `state` is frozen — `structuredClone` + `Object.freeze`
-                    // is an ordinary defensive rehydration — and that row is not usable
-                    // by this class at all: `markRunning` writes the same field on every
-                    // execution. Measured, the guard moves the failure from a throw out
-                    // of `start()`, which the consumer's own `await` can catch, to a
+                    // But NOT every `runningAtMs` here is stale, and the field cannot
+                    // tell you which — it is a number either way. `start()` early-returns
+                    // when `started`, so reaching this with a LIVE claim needs `stop()`
+                    // then `start(sameObjects)` (an in-process restart against a store
+                    // that hands back references rather than fresh rows) or a second
+                    // `CronService` handed live rows. Measured on the unconditional
+                    // version: the release cleared a live claim, the timer then found the
+                    // job due, and one job got TWO concurrent in-flight callbacks. That
+                    // is the single invariant this class advertises and that #34/#35
+                    // exist to protect, so the release is guarded on `inFlight` —
+                    // authoritative object identity, not a heuristic on the timestamp.
+                    // See `inFlight`'s docblock for why identity is also what keeps the
+                    // stale case working after a real crash.
+                    //
+                    // The guard is deliberately NOT a `job.state.runningAtMs` read.
+                    // Guarding on THAT makes `start()` accept a row whose `state` is
+                    // frozen — `structuredClone` + `Object.freeze` is an ordinary
+                    // defensive rehydration — and that row is not usable by this class at
+                    // all: `markRunning` writes the same field on every execution.
+                    // Measured, that guard moves the failure from a throw out of
+                    // `start()`, which the consumer's own `await` can catch, to a
                     // TypeError raised inside `onTimer`'s batch claim — a bare timer
                     // callback, so it surfaces as an unhandled rejection and is
-                    // process-fatal under Node's default. Failing loudly at the store
-                    // boundary is the better of the two, and the `finally` above keeps
-                    // the rows that loaded before it scheduled.
-                    job.state.runningAtMs = undefined;
+                    // process-fatal under Node's default. `inFlight` does not have that
+                    // problem: a deserialized row is never a member, so the write still
+                    // happens and the frozen row still fails loudly at the boundary. Both
+                    // properties are tested; do not collapse the two guards into one.
+                    if (!inFlight.has(job)) {
+                        job.state.runningAtMs = undefined;
+                    }
                     this.jobs.set(job.id, job);
                     if (job.enabled && job.state.nextRunAtMs) {
                         this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
@@ -343,6 +459,7 @@ export default class CronService {
                 const due = this.findDueJobs(nowMs);
                 for (const job of due) {
                     markRunning(job);
+                    inFlight.add(job);
                 }
                 return due;
             });
@@ -470,6 +587,7 @@ export default class CronService {
         // recomputed `nextRunAtMs` — the job did not run.
         if (this.jobs.get(job.id) !== job) {
             job.state.runningAtMs = undefined;
+            inFlight.delete(job);
             return { status: 'skipped', reason: 'removed' };
         }
         const startMs = Date.now();
@@ -533,6 +651,7 @@ export default class CronService {
         if (job.state.runningAtMs)
             return 'already running';
         markRunning(job);
+        inFlight.add(job);
         this.removeFromHeap(job.id);
         return null;
     }
@@ -589,6 +708,12 @@ export default class CronService {
             return { status, error, summary, durationMs };
         }
         finally {
+            // The invocation is over, so this job is no longer in flight in this
+            // process — whatever `applyResult` did or did not manage to write. In the
+            // `finally` so it covers a throw out of `applyResult` or `runLog.record`
+            // too: past this point no settle is coming, which is precisely the state
+            // `start()`'s release is for.
+            inFlight.delete(job);
             // One re-arm covering every exit, rather than one per branch. The claim
             // detached this job from the heap, so a timer that fired during the
             // unlocked invoke would have found nothing to arm — and `run()` has no

package/package.json

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