@stonyx/cron 0.2.1-beta.13 → 0.2.1-beta.131

package/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/abofs/stonyx-cron/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx-cron/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@stonyx/cron.svg)](https://www.npmjs.com/package/@stonyx/cron)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # stonyx-cron
 
 A small, lightweight cron/job scheduling utility for asynchronous jobs. Designed to schedule, run, and automatically re-schedule jobs at precise intervals with optional debug logging.
@@ -31,20 +35,118 @@ 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. `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, even though the scheduler stays healthy and the job stays visible in `jobs` and in the heap. Other jobs are unaffected.
+>
+> One warning is emitted per stuck run (not per tick), including how long the invocation has been running. That warning goes to `log.warn` and is **not** gated by `config.cron.log` — a dropped execution reported on a channel a config flag can silence would be indistinguishable from a healthy scheduler.
+>
+> The same-job guarantee holds for the lifetime of a **registration**, not of a key: `unregister` followed by `register` on a key whose invocation is still in flight builds a fresh job object with a fresh guard, so the replacement can run alongside the abandoned invocation. That is also the only way to recover a permanently stuck job.
+>
+> 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. Note that a rejection which previously escaped `register()` as an unhandled rejection — process-fatal under Node's default — is now swallowed into `log.error`.
+
 > `MinHeap` is also exported as a public subpath (`@stonyx/cron/min-heap`) and can be imported directly for advanced usage.
 
+## CronService
+
+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 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';
+
+const service = new CronService();
+service.onJobDue = async (job) => ({ status: 'ok', summary: 'done' });
+
+await service.start();
+const job = await service.add({ name: 'Nightly', schedule: { kind: 'every', everyMs: 86_400_000 }, payload: { kind: 'agentTurn', message: 'go' } });
+
+const result = await service.run(job.id, 'force');
+```
+
+### The `run()` contract
+
+`run(id, mode)` resolves with an `ExecuteResult`. It **never** invokes the callback twice for one job, and it will refuse rather than queue:
+
+| `status`    | `reason`            | Meaning                                                                        |
+| :---------- | :------------------ | :----------------------------------------------------------------------------- |
+| `'ok'`      | —                   | The callback resolved. `summary` and `durationMs` are set.                     |
+| `'error'`   | —                   | The callback threw or rejected. `error` carries the message; backoff is applied. |
+| `'skipped'` | `'not due'`         | `mode` was `'due'` and the job's next run time has not arrived. Use `'force'` to run anyway. |
+| `'skipped'` | `'already running'`  | A previous invocation of **this** job has not settled. The call is refused, not queued, and nothing is logged. |
+| `'skipped'` | `'removed'`         | The job was removed between the lookup and the claim. The callback did not fire. |
+
+`run()` throws (rather than returning a result) when `id` is not a registered job: `Error: Job not found: <id>`.
+
+**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
+
+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 four things:
+the class gained `#private;`, `reason` narrowed, five type declarations gained
+`export` (`JobDueResult`, `ExecuteResult`, `ServiceStatus`, `ListOptions` and
+`OnJobDueCallback`), and `SkipReason` was added as a new exported type — it did
+not exist in the previous release, so it gained nothing. `HeapEntry` remains
+unexported. `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.** 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.
+
 ## Configuration
 
-Optionally, logging and debugging can be enabled through `config.cron`:
+Optionally, informational logging and debugging can be controlled through `config.cron`:
 
 ```js
 config.cron = {
-  log: true // enable cron job logs
+  log: true // informational cron job logs; defaults to true
 };
 
 config.debug = true; // optional: debug logs for job registration and execution
 ```
 
+`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
 
 Apache — do what you want, just keep attribution.

package/dist/cron-parser.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 5-field cron expression parser with next-occurrence computation.
+ * No external dependencies - built for stonyx-cron.
+ *
+ * Fields: minute(0-59) hour(0-23) day-of-month(1-31) month(1-12) day-of-week(0-6)
+ * Supports: wildcards(*), ranges(1-5), steps(* /5), lists(1,3,5), names(jan-dec, sun-sat)
+ */
+export interface ParsedCronExpression {
+    minutes: number[];
+    hours: number[];
+    daysOfMonth: number[];
+    months: number[];
+    daysOfWeek: number[];
+}
+/**
+ * Parse a single cron field into a sorted array of allowed values.
+ */
+export declare function parseField(field: string, fieldIndex: number): number[];
+/**
+ * Parse a 5-field cron expression into field arrays.
+ */
+export declare function parseCronExpression(expr: string): ParsedCronExpression;
+/**
+ * Compute the next occurrence of a cron expression after a given timestamp.
+ */
+export declare function nextOccurrence(expr: string, afterMs: number, tz?: string): number | undefined;
+/**
+ * Validate a cron expression without computing next occurrence.
+ */
+export declare function validateCronExpression(expr: string): void;

package/dist/cron-parser.js

@@ -0,0 +1,200 @@
+/**
+ * 5-field cron expression parser with next-occurrence computation.
+ * No external dependencies - built for stonyx-cron.
+ *
+ * Fields: minute(0-59) hour(0-23) day-of-month(1-31) month(1-12) day-of-week(0-6)
+ * Supports: wildcards(*), ranges(1-5), steps(* /5), lists(1,3,5), names(jan-dec, sun-sat)
+ */
+const MONTH_NAMES = { jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6, jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12 };
+const DAY_NAMES = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+const FIELD_RANGES = [
+    { min: 0, max: 59 }, // minute
+    { min: 0, max: 23 }, // hour
+    { min: 1, max: 31 }, // day of month
+    { min: 1, max: 12 }, // month
+    { min: 0, max: 6 }, // day of week
+];
+/**
+ * Parse a single cron field into a sorted array of allowed values.
+ */
+export function parseField(field, fieldIndex) {
+    const { min, max } = FIELD_RANGES[fieldIndex];
+    const names = fieldIndex === 3 ? MONTH_NAMES : fieldIndex === 4 ? DAY_NAMES : null;
+    const resolveToken = (token) => {
+        if (names) {
+            const lower = token.toLowerCase();
+            if (lower in names)
+                return names[lower];
+        }
+        const n = Number(token);
+        if (!Number.isInteger(n))
+            throw new Error(`Invalid cron value: "${token}" in field ${fieldIndex}`);
+        // Normalize day-of-week 7 -> 0 (both mean Sunday)
+        if (fieldIndex === 4 && n === 7)
+            return 0;
+        return n;
+    };
+    const results = new Set();
+    for (const part of field.split(',')) {
+        const trimmed = part.trim();
+        const [rangeStr, stepStr] = trimmed.split('/');
+        const step = stepStr !== undefined ? Number(stepStr) : 1;
+        if (!Number.isInteger(step) || step < 1) {
+            throw new Error(`Invalid step "${stepStr}" in cron field ${fieldIndex}`);
+        }
+        let start, end;
+        if (rangeStr === '*') {
+            start = min;
+            end = max;
+        }
+        else if (rangeStr.includes('-')) {
+            const [lo, hi] = rangeStr.split('-');
+            start = resolveToken(lo);
+            end = resolveToken(hi);
+        }
+        else {
+            start = resolveToken(rangeStr);
+            end = stepStr !== undefined ? max : start;
+        }
+        if (start < min || start > max || end < min || end > max) {
+            throw new Error(`Value out of range [${min}-${max}] in cron field ${fieldIndex}: "${trimmed}"`);
+        }
+        for (let v = start; v <= end; v += step) {
+            results.add(v);
+        }
+    }
+    return [...results].sort((a, b) => a - b);
+}
+/**
+ * Parse a 5-field cron expression into field arrays.
+ */
+export function parseCronExpression(expr) {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error(`Cron expression must have exactly 5 fields, got ${fields.length}: "${expr}"`);
+    }
+    return {
+        minutes: parseField(fields[0], 0),
+        hours: parseField(fields[1], 1),
+        daysOfMonth: parseField(fields[2], 2),
+        months: parseField(fields[3], 3),
+        daysOfWeek: parseField(fields[4], 4),
+    };
+}
+/**
+ * Get the number of days in a given month/year.
+ */
+function daysInMonth(_year, month) {
+    return new Date(_year, month, 0).getDate();
+}
+/**
+ * Check if a day-of-month + day-of-week pair matches the parsed expression.
+ */
+function dayMatches(parsed, domWild, dowWild, dayOfMonth, dayOfWeek) {
+    const domMatch = parsed.daysOfMonth.includes(dayOfMonth);
+    const dowMatch = parsed.daysOfWeek.includes(dayOfWeek);
+    if (domWild && dowWild)
+        return true;
+    if (domWild)
+        return dowMatch;
+    if (dowWild)
+        return domMatch;
+    return domMatch || dowMatch; // Both restricted -> OR
+}
+/**
+ * Compute the next occurrence of a cron expression after a given timestamp.
+ */
+export function nextOccurrence(expr, afterMs, tz) {
+    const parsed = parseCronExpression(expr);
+    const exprFields = expr.trim().split(/\s+/);
+    const domWild = exprFields[2] === '*';
+    const dowWild = exprFields[4] === '*';
+    // Start from the next whole minute after afterMs
+    const startDate = new Date(afterMs);
+    startDate.setSeconds(0, 0);
+    startDate.setMinutes(startDate.getMinutes() + 1);
+    // Convert to target timezone for field matching
+    const formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz || undefined,
+        year: 'numeric', month: 'numeric', day: 'numeric',
+        hour: 'numeric', minute: 'numeric', hour12: false,
+        weekday: 'short',
+    });
+    const dayMap = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+    // Parse formatted date parts in the target timezone
+    function getLocalParts(date) {
+        const parts = {};
+        for (const { type, value } of formatter.formatToParts(date)) {
+            parts[type] = value;
+        }
+        const hourStr = parts.hour ?? '0';
+        return {
+            year: Number(parts.year ?? '0'),
+            month: Number(parts.month ?? '0'),
+            day: Number(parts.day ?? '0'),
+            hour: Number(hourStr === '24' ? '0' : hourStr),
+            minute: Number(parts.minute ?? '0'),
+            weekday: dayMap[parts.weekday] ?? 0,
+        };
+    }
+    // Search limit: 4 years of minutes
+    const maxMs = afterMs + 4 * 365.25 * 24 * 60 * 60 * 1000;
+    const candidate = new Date(startDate);
+    while (candidate.getTime() <= maxMs) {
+        const p = getLocalParts(candidate);
+        // Check month
+        if (!parsed.months.includes(p.month)) {
+            const nextMonth = parsed.months.find(m => m > p.month);
+            if (nextMonth) {
+                advanceToMonth(candidate, p.year, nextMonth);
+            }
+            else {
+                advanceToMonth(candidate, p.year + 1, parsed.months[0]);
+            }
+            continue;
+        }
+        // Check day (dom + dow)
+        if (!dayMatches(parsed, domWild, dowWild, p.day, p.weekday)) {
+            candidate.setMinutes(candidate.getMinutes() + (24 * 60 - p.hour * 60 - p.minute));
+            continue;
+        }
+        // Check hour
+        if (!parsed.hours.includes(p.hour)) {
+            const nextHour = parsed.hours.find(h => h > p.hour);
+            if (nextHour) {
+                candidate.setMinutes(candidate.getMinutes() + ((nextHour - p.hour) * 60 - p.minute));
+            }
+            else {
+                candidate.setMinutes(candidate.getMinutes() + ((24 - p.hour) * 60 - p.minute));
+            }
+            continue;
+        }
+        // Check minute
+        if (!parsed.minutes.includes(p.minute)) {
+            const nextMin = parsed.minutes.find(m => m > p.minute);
+            if (nextMin) {
+                candidate.setMinutes(candidate.getMinutes() + (nextMin - p.minute));
+            }
+            else {
+                candidate.setMinutes(candidate.getMinutes() + (60 - p.minute));
+            }
+            continue;
+        }
+        // All fields match
+        return candidate.getTime();
+    }
+    return undefined;
+}
+/**
+ * Advance a Date to the start of a specific month in a specific year.
+ */
+function advanceToMonth(current, year, month) {
+    current.setFullYear(year, month - 1, 1);
+    current.setHours(0, 0, 0, 0);
+}
+/**
+ * Validate a cron expression without computing next occurrence.
+ */
+export function validateCronExpression(expr) {
+    parseCronExpression(expr);
+}

package/dist/job.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Job data model and state machine for the advanced scheduling system.
+ */
+import { type Schedule } from './schedule.js';
+export interface JobState {
+    nextRunAtMs: number | undefined;
+    runningAtMs: number | undefined;
+    lastRunAtMs: number | undefined;
+    lastStatus: 'ok' | 'error' | 'skipped' | undefined;
+    lastError: string | undefined;
+    lastDurationMs: number | undefined;
+    consecutiveErrors: number;
+    scheduleErrorCount: number;
+}
+export interface Job {
+    id: string;
+    name: string;
+    description: string | undefined;
+    enabled: boolean;
+    deleteAfterRun: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    schedule: Schedule;
+    sessionTarget: string;
+    wakeMode: string;
+    payload: Record<string, unknown>;
+    delivery: Record<string, unknown> | undefined;
+    state: JobState;
+}
+export interface JobInput {
+    name: string;
+    schedule: Schedule;
+    payload: Record<string, unknown>;
+    description?: string;
+    enabled?: boolean;
+    deleteAfterRun?: boolean;
+    sessionTarget?: string;
+    wakeMode?: string;
+    delivery?: Record<string, unknown>;
+}
+export interface JobPatch {
+    name?: string;
+    description?: string;
+    schedule?: Schedule;
+    payload?: Record<string, unknown>;
+    delivery?: Record<string, unknown> | null;
+    enabled?: boolean;
+    deleteAfterRun?: boolean;
+    sessionTarget?: string;
+    wakeMode?: string;
+}
+export declare function errorBackoffMs(consecutiveErrors: number): number;
+/**
+ * Create a new job object from input.
+ */
+export declare function createJob(input: JobInput): Job;
+/**
+ * Apply an update patch to a job.
+ */
+export declare function updateJob(job: Job, patch: JobPatch): Job;
+/**
+ * Mark a job as started (running).
+ */
+export declare function markRunning(job: Job): void;
+/**
+ * Apply the result of a job execution.
+ */
+export declare function applyResult(job: Job, status: 'ok' | 'error' | 'skipped', error?: string, durationMs?: number): void;
+/**
+ * Check if a job is due to run.
+ */
+export declare function isDue(job: Job, nowMs: number): boolean;

package/dist/job.js

@@ -0,0 +1,172 @@
+/**
+ * Job data model and state machine for the advanced scheduling system.
+ */
+import { computeNextRunAtMs, validateSchedule } from './schedule.js';
+/**
+ * Error backoff table (milliseconds).
+ * Applied after consecutive errors to prevent hammering.
+ */
+const ERROR_BACKOFF_MS = [30_000, 60_000, 300_000, 900_000, 3_600_000];
+export function errorBackoffMs(consecutiveErrors) {
+    if (consecutiveErrors < 1)
+        return 0;
+    return ERROR_BACKOFF_MS[Math.min(consecutiveErrors - 1, ERROR_BACKOFF_MS.length - 1)];
+}
+/**
+ * Create a new job object from input.
+ */
+export function createJob(input) {
+    validateSchedule(input.schedule);
+    const nowMs = Date.now();
+    const enabled = input.enabled !== false;
+    const deleteAfterRun = input.deleteAfterRun ?? (input.schedule.kind === 'at');
+    const job = {
+        id: crypto.randomUUID(),
+        name: input.name,
+        description: input.description || undefined,
+        enabled,
+        deleteAfterRun,
+        createdAtMs: nowMs,
+        updatedAtMs: nowMs,
+        schedule: { ...input.schedule },
+        sessionTarget: input.sessionTarget || 'isolated',
+        wakeMode: input.wakeMode || 'now',
+        payload: { ...input.payload },
+        delivery: input.delivery ? { ...input.delivery } : undefined,
+        state: {
+            nextRunAtMs: undefined,
+            runningAtMs: undefined,
+            lastRunAtMs: undefined,
+            lastStatus: undefined,
+            lastError: undefined,
+            lastDurationMs: undefined,
+            consecutiveErrors: 0,
+            scheduleErrorCount: 0,
+        },
+    };
+    // Compute initial next run
+    if (enabled) {
+        try {
+            job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+        }
+        catch {
+            job.state.scheduleErrorCount = 1;
+        }
+    }
+    return job;
+}
+/**
+ * Apply an update patch to a job.
+ */
+export function updateJob(job, patch) {
+    const nowMs = Date.now();
+    if (patch.name !== undefined)
+        job.name = patch.name;
+    if (patch.description !== undefined)
+        job.description = patch.description || undefined;
+    if (patch.deleteAfterRun !== undefined)
+        job.deleteAfterRun = patch.deleteAfterRun;
+    if (patch.sessionTarget !== undefined)
+        job.sessionTarget = patch.sessionTarget;
+    if (patch.wakeMode !== undefined)
+        job.wakeMode = patch.wakeMode;
+    if (patch.payload !== undefined)
+        job.payload = { ...patch.payload };
+    if (patch.delivery !== undefined)
+        job.delivery = patch.delivery ? { ...patch.delivery } : undefined;
+    if (patch.schedule !== undefined) {
+        validateSchedule(patch.schedule);
+        job.schedule = { ...patch.schedule };
+        job.state.scheduleErrorCount = 0;
+        // Recompute next run
+        if (job.enabled) {
+            try {
+                job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+            }
+            catch {
+                job.state.scheduleErrorCount = 1;
+            }
+        }
+    }
+    if (patch.enabled !== undefined) {
+        job.enabled = patch.enabled;
+        if (job.enabled && !job.state.nextRunAtMs) {
+            try {
+                job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+            }
+            catch {
+                job.state.scheduleErrorCount++;
+            }
+        }
+        if (!job.enabled) {
+            job.state.nextRunAtMs = undefined;
+        }
+    }
+    job.updatedAtMs = nowMs;
+    return job;
+}
+/**
+ * Mark a job as started (running).
+ */
+export function markRunning(job) {
+    job.state.runningAtMs = Date.now();
+}
+/**
+ * Apply the result of a job execution.
+ */
+export function applyResult(job, status, error, durationMs) {
+    const nowMs = Date.now();
+    job.state.lastRunAtMs = job.state.runningAtMs || nowMs;
+    job.state.runningAtMs = undefined;
+    job.state.lastStatus = status;
+    job.state.lastError = status === 'error' ? error : undefined;
+    job.state.lastDurationMs = durationMs;
+    if (status === 'error') {
+        job.state.consecutiveErrors = (job.state.consecutiveErrors || 0) + 1;
+    }
+    else {
+        job.state.consecutiveErrors = 0;
+    }
+    // One-shot jobs: disable after any terminal status
+    if (job.schedule.kind === 'at') {
+        job.enabled = false;
+        job.state.nextRunAtMs = undefined;
+        return;
+    }
+    // Recurring jobs: compute next run with backoff
+    if (job.enabled) {
+        try {
+            const normalNext = computeNextRunAtMs(job.schedule, nowMs);
+            if (normalNext === undefined) {
+                job.enabled = false;
+                job.state.nextRunAtMs = undefined;
+                return;
+            }
+            if (status === 'error' && job.state.consecutiveErrors > 0) {
+                const backoff = errorBackoffMs(job.state.consecutiveErrors);
+                job.state.nextRunAtMs = Math.max(normalNext, nowMs + backoff);
+            }
+            else {
+                job.state.nextRunAtMs = normalNext;
+            }
+            job.state.scheduleErrorCount = 0;
+        }
+        catch {
+            job.state.scheduleErrorCount = (job.state.scheduleErrorCount || 0) + 1;
+            // Auto-disable after 3 consecutive schedule computation errors
+            if (job.state.scheduleErrorCount >= 3) {
+                job.enabled = false;
+                job.state.nextRunAtMs = undefined;
+            }
+        }
+    }
+}
+/**
+ * Check if a job is due to run.
+ */
+export function isDue(job, nowMs) {
+    return job.enabled
+        && !job.state.runningAtMs
+        && job.state.nextRunAtMs !== undefined
+        && job.state.nextRunAtMs <= nowMs;
+}

package/dist/locked.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Async locking mechanism to serialize state mutations.
+ * Prevents concurrent operations from corrupting job state.
+ */
+/**
+ * Execute a function with exclusive access to cron state.
+ * Operations queue behind each other - no concurrent mutations.
+ */
+export declare function locked<T>(fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Reset the lock chain. Only for testing.
+ */
+export declare function resetLock(): void;

package/dist/locked.js

@@ -0,0 +1,27 @@
+/**
+ * Async locking mechanism to serialize state mutations.
+ * Prevents concurrent operations from corrupting job state.
+ */
+let chain = Promise.resolve();
+/**
+ * Execute a function with exclusive access to cron state.
+ * Operations queue behind each other - no concurrent mutations.
+ */
+export async function locked(fn) {
+    let resolve;
+    const prev = chain;
+    chain = new Promise(r => { resolve = r; });
+    await prev;
+    try {
+        return await fn();
+    }
+    finally {
+        resolve();
+    }
+}
+/**
+ * Reset the lock chain. Only for testing.
+ */
+export function resetLock() {
+    chain = Promise.resolve();
+}