@cronwatch/sdk 0.1.0 → 0.3.1

package/dist/index.d.cts

@@ -1,6 +1,5 @@
-import { S as Store, a as AlertChannel, T as TriageFn, D as Duration, J as JobOptions, b as JobDefinition, R as Run, C as CheckResult, c as JobSummary, d as JobState, A as Alert, e as Condition, f as StoredJobDefinition } from './types-BQ1P8z55.cjs';
-export { g as AlertType, E as ExpectRule, h as JobHealth, i as RunStatus, j as StoredJob, k as TriageContext } from './types-BQ1P8z55.cjs';
-import { Cron } from 'croner';
+import { S as Store, a as AlertChannel, T as TriageFn, D as Duration, J as JobOptions, b as JobDefinition, C as CheckResult, c as JobSummary, R as Run, d as JobState, A as Alert, e as AlertDraft, f as StoredJobDefinition } from './types-DUt2apl0.cjs';
+export { g as AlertDetails, h as AlertType, B as BudgetBreach, i as Condition, E as ExpectRule, j as JobHealth, k as RunStatus, l as StoredJob, m as TriageContext } from './types-DUt2apl0.cjs';
 
 /** What a job function receives. */
 interface JobContext {
@@ -20,8 +19,11 @@ interface RoutesOptions {
     /**
      * Required to reach anything. Send it as `Authorization: Bearer <token>`,
      * or open the dashboard once with `?token=<token>` and a cookie is set.
-     * Defaults to process.env.CRONWATCH_TOKEN. With no token at all, the routes
-     * are open in development and refuse to serve in production.
+     * Defaults to process.env.CRONWATCH_TOKEN; an empty string counts as unset.
+     * With no token while NODE_ENV is "development" or "test", the routes make
+     * a random one and print a sign-in link to the server log on their first
+     * request; with no token otherwise they answer 503. Pass `null` to opt out
+     * and serve them open everywhere, for example behind your own auth.
      *
      * The check endpoint (/api/check) also accepts the client's cronSecret, so
      * a platform cron that sends `Authorization: Bearer <CRON_SECRET>` can
@@ -52,7 +54,9 @@ interface HandlerOptions {
     /**
      * Callers must send `Authorization: Bearer <secret>`. Defaults to the
      * client's cronSecret, which defaults to process.env.CRON_SECRET (what
-     * Vercel sends its cron requests with). Pass null to allow anyone.
+     * Vercel sends its cron requests with). An empty string counts as unset.
+     * With no secret at all the handler answers 503 unless NODE_ENV is
+     * "development" or "test". Pass null to allow anyone.
      */
     secret?: string | null;
 }
@@ -71,41 +75,68 @@ interface CronWatchOptions {
     store?: Store;
     /** Where alerts go. Defaults to the console. */
     alerts?: AlertChannel[];
-    /** Adds a short diagnosis to failure alerts. See @cronwatch/sdk/anthropic. */
+    /** Adds a short diagnosis to every alert except recoveries. See @cronwatch/sdk/anthropic. */
     triage?: TriageFn;
-    /** Shared secret that handler() requests must carry. Defaults to process.env.CRON_SECRET. */
+    /**
+     * Shared secret that handler() requests must carry. Defaults to
+     * process.env.CRON_SECRET; an empty string counts as unset. Pass null to
+     * let handlers run without one.
+     */
     cronSecret?: string | null;
     /** How long finished runs are kept. Default "30d". */
     retention?: Duration;
     /** Applied to every job unless the job sets its own. */
     defaults?: Pick<JobOptions, "grace" | "timeout" | "timezone" | "failuresBeforeAlert">;
-    /** Called with anything that goes wrong outside a job: an alert channel failing, a triage timeout. */
+    /**
+     * Applied to every run's output and error before it is stored, shown or
+     * sent to an alert channel or triage. The default blanks values that look
+     * like secrets (password=..., Authorization headers, URL credentials, bearer
+     * tokens, JWTs, PEM private keys, webhook URLs, AWS, GitHub, Slack, Stripe,
+     * Google and API key formats). Pass your own function, or false to keep
+     * output exactly as logged. A function that throws or returns something
+     * other than a string is reported to onError and the default is used.
+     */
+    redact?: ((text: string) => string) | false;
+    /**
+     * "now" (the default) sends alerts from this process. "check" sends nothing
+     * from here: each alert is queued in the store and the next check, in a
+     * process that delivers now, sends it (with triage). For a process that
+     * records runs but cannot reach the network, such as a sandboxed backup job.
+     * Its `alerts` and `triage` are not used.
+     */
+    deliver?: "now" | "check";
+    /** Called with anything that goes wrong outside a job: the store failing, an alert channel failing, a triage timeout. */
     onError?: (error: unknown, where: string) => void;
     /** The clock. Tests use this. */
     now?: () => number;
 }
-interface ExecuteResult<T> {
-    run: Run;
-    result: T | undefined;
-    error: unknown;
-    threw: boolean;
-}
 declare class CronWatch {
     readonly store: Store;
     readonly alerts: AlertChannel[];
     readonly triage: TriageFn | undefined;
+    /** The secret handler() requests must carry, or null when none is set. */
     readonly cronSecret: string | null;
     readonly retentionMs: number;
     readonly now: () => number;
     readonly onError: (error: unknown, where: string) => void;
+    /** cronSecret was passed as null: handlers may run without a secret. */
+    private readonly secretOptOut;
+    private readonly redact;
+    /** "check": queue alerts for another process's check instead of sending them. See CronWatchOptions.deliver. */
+    private readonly deferDelivery;
     private readonly defaults;
     private readonly definitions;
     private readonly synced;
+    /** The tail of each job's queue of state updates. See serial(). */
+    private readonly queues;
     private ready;
     private checking;
     private lastPruneAt;
     private timer;
+    private firstTick;
     private usingDefaultStore;
+    private warnedNoSecret;
+    private warnedDeferredStart;
     constructor(options?: CronWatchOptions);
     /** Declare a job. Call it once, at module level, and keep the handle. */
     job(name: string, options?: JobOptions): JobHandle;
@@ -115,25 +146,80 @@ declare class CronWatch {
     /** The definitions declared in this process. */
     definedJobs(): JobDefinition[];
     private handle;
+    private warnNoSecret;
+    /** onError, for places that must carry on even when onError itself throws. */
+    private report;
     private ensureReady;
     private sync;
-    /** Runs a function as a recorded run. Never throws for the job's own error; see `threw`. */
-    execute<T>(definition: JobDefinition, fn: JobFn<T>, trigger: string): Promise<ExecuteResult<T>>;
     /**
-     * Look for missed and stuck runs across every job, send alerts, and prune
-     * old runs. Call it from an interval (start()), a cron hitting the mounted
-     * routes, or by hand. Concurrent calls share one check.
+     * Runs `fn` after every earlier state update for the same job has settled,
+     * so two runs (or a run and a check) in this process never read and write
+     * the job's state over each other. Other processes are coordinated by
+     * updateState() instead.
+     */
+    private serial;
+    private readState;
+    /**
+     * Every read-modify-write of a job's state goes through here. In turn with
+     * this process's other updates to the job (serial()), it reads the state,
+     * asks `change` for the next one, and writes it with the version one
+     * higher, only if the stored version is still the one read. When another
+     * process wrote in between, the write is refused and it starts again from
+     * a fresh read, up to STATE_ATTEMPTS times. So `change` may run more than
+     * once and must only compute: whatever it returns from the attempt that
+     * was written is the result. Nothing is written when the state is
+     * unchanged. Returns the state as stored.
+     */
+    private updateState;
+    /** A conditional write, or for a store without compareAndSetState, a plain one that always succeeds. */
+    private writeState;
+    /**
+     * Runs a function as a recorded run. The function always runs, whatever
+     * the store is doing: store errors go to onError, and the result is the
+     * function's own outcome. Never throws for the job's own error; see `threw`.
+     */
+    private execute;
+    /** Whether a check already marked this run as timed out, for a failure that finished late. */
+    private markedTimedOut;
+    /**
+     * Record a finished run (ok, failed, or timed out by a check), evaluate it
+     * against the job's state and send what that produces. Never throws.
+     */
+    private finishRun;
+    /**
+     * The runs before `run`, newest first, with up to BASELINE_WINDOW
+     * successful ones when the store has them. One small read normally; a
+     * larger one only when failures crowd the successes out of it.
+     */
+    private history;
+    /**
+     * Look for missed and stuck runs across every job, send alerts, retry
+     * alerts no channel accepted, and prune old runs. Call it from an interval
+     * (start()), a cron hitting the mounted routes, or by hand. Concurrent
+     * calls share one check.
      */
     check(): Promise<CheckResult>;
     private runCheck;
+    /** A job's summary and its newest runs, without alerting. A job that cannot be evaluated is reported and shown as failing. */
+    private snapshot;
+    /** The summary of a job whose evaluation failed, from whatever can still be read. */
+    private unevaluable;
     /** Every job the store knows about, with its health. Does not send alerts. */
     jobs(): Promise<JobSummary[]>;
+    /** Every job's summary with its newest `limit` runs, read together. What the dashboard shows. */
+    jobsWithRuns(limit?: number): Promise<{
+        job: JobSummary;
+        runs: Run[];
+    }[]>;
     jobSummary(name: string): Promise<JobSummary | null>;
+    /** A job's runs, newest first. `limit` is a whole number from 1 to 500. */
     runs(name: string, limit?: number): Promise<Run[]>;
     getRun(id: string): Promise<Run | null>;
     /** Stop alerts for a job for a while. State keeps updating underneath. */
     silence(name: string, duration: Duration): Promise<JobState>;
     unsilence(name: string): Promise<JobState>;
+    /** Read, change and write one job's state, in turn with every other update to it. */
+    private patchState;
     /** Remove a job and its runs from the store. A job still declared in code comes back on its next run. */
     forget(name: string): Promise<void>;
     /** The dashboard and JSON API as fetch-style handlers. See createRoutes(). */
@@ -142,18 +228,36 @@ declare class CronWatch {
     start(every?: Duration): void;
     stop(): void;
     close(): Promise<void>;
-    private summarize;
-    /** Save an evaluation's state, honouring silence, and send its alerts. */
-    private settle;
+    /**
+     * Compose, triage and send each draft. The state was saved before this
+     * (updateState), so a slow channel holds up nothing else; afterwards only
+     * the delivery fields are written back, onto a fresh read of the state.
+     */
     private dispatch;
+    /**
+     * Send the alerts that no channel accepted last time, once each, oldest
+     * first. `state` is the job's state as this check left it: an alert that
+     * no longer describes it (staleAlert) is dropped instead. Retries across a
+     * check share RETRY_BUDGET_MS of wall-clock time; once it is spent the rest
+     * stay queued for the next check.
+     */
+    private retryUndelivered;
+    /**
+     * Mark delivered alerts done, drop stale ones, and keep failed ones for the
+     * next check. A failed alert replaces its stored copy, so a triage made on
+     * this attempt is kept. lastAlertAt moves only on a delivery.
+     */
+    private recordDelivery;
+    /** Send to every channel at once. True when at least one accepted it, or there are none. */
+    private deliver;
+    /** Sets alert.triage to the diagnosis, or to null when there is none, so it is tried once per alert. */
+    private addTriage;
 }
 /** Writes alerts to the console. The default channel. */
 declare function consoleChannel(): AlertChannel;
 /** Wrap any function as an alert channel. */
 declare function custom(name: string, send: (alert: Alert) => Promise<void> | void): AlertChannel;
 
-declare function json(body: unknown, status?: number, headers?: Record<string, string>): Response;
-
 /**
  * Keeps everything in process memory. The default when no store is given,
  * good for tests and for trying the library out. State is gone on restart,
@@ -168,15 +272,14 @@ declare function memory(): Store;
 declare function parseDuration(value: Duration, label?: string): number;
 /** 90000 -> "1m 30s". For messages, not for parsing back. */
 declare function formatDuration(ms: number): string;
-/** "5 minutes ago", "in 2h". Relative to `now`. */
-declare function formatRelative(at: number, now: number): string;
 
 interface ParsedSchedule {
     kind: "cron" | "interval";
     source: string;
+    /** The IANA timezone a cron is read in, when one was given. */
+    timezone?: string;
     /** For intervals, the period in milliseconds. */
     everyMs?: number;
-    cron?: Cron;
 }
 /**
  * "0 2 * * *" (cron, five or six fields), "@hourly", or "every 5m".
@@ -187,23 +290,8 @@ interface ParsedSchedule {
  * timezone: "UTC" for those.
  */
 declare function parseSchedule(schedule: string, timezone?: string): ParsedSchedule;
-/** The next time the cron fires strictly after `from`. */
+/** The next time the schedule fires strictly after `from`. For an interval, counted from the last run when there is one. */
 declare function nextFire(parsed: ParsedSchedule, from: number, lastRunAt: number | null): number | null;
-/**
- * The most recent time the cron fired at or before `now`, or null when the
- * expression never fires in the year before `now`.
- *
- * croner only looks forward, so this searches: widen a window behind `now`
- * until a fire time falls inside it, then bisect on the window's start for
- * the latest start whose next fire is still at or before `now`.
- */
-declare function previousFire(parsed: ParsedSchedule, now: number): number | null;
-
-interface AlertDraft {
-    type: Condition | "recovered";
-    run: Run | null;
-    details: Record<string, unknown>;
-}
 
 /** Turns a draft into the title and message every channel shows. */
 declare function composeAlert(draft: AlertDraft, def: StoredJobDefinition, now: number): Alert;
@@ -216,4 +304,4 @@ declare function composeAlert(draft: AlertDraft, def: StoredJobDefinition, now:
  */
 declare function cronwatch(options?: CronWatchOptions): CronWatch;
 
-export { Alert, AlertChannel, CheckResult, Condition, CronWatch, type CronWatchOptions, Duration, type HandlerFn, type HandlerOptions, type JobContext, JobDefinition, type JobFn, type JobHandle, JobOptions, JobState, JobSummary, type Routes, type RoutesOptions, Run, Store, StoredJobDefinition, TriageFn, composeAlert, consoleChannel, createRoutes, cronwatch, custom, formatDuration, formatRelative, json, memory, nextFire, parseDuration, parseSchedule, previousFire };
+export { Alert, AlertChannel, AlertDraft, CheckResult, CronWatch, type CronWatchOptions, Duration, type FetchHandler, type HandlerFn, type HandlerOptions, type JobContext, JobDefinition, type JobFn, type JobHandle, JobOptions, JobState, JobSummary, type ParsedSchedule, type Routes, type RoutesOptions, Run, Store, StoredJobDefinition, TriageFn, composeAlert, consoleChannel, createRoutes, cronwatch, custom, formatDuration, memory, nextFire, parseDuration, parseSchedule };

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-import { S as Store, a as AlertChannel, T as TriageFn, D as Duration, J as JobOptions, b as JobDefinition, R as Run, C as CheckResult, c as JobSummary, d as JobState, A as Alert, e as Condition, f as StoredJobDefinition } from './types-BQ1P8z55.js';
-export { g as AlertType, E as ExpectRule, h as JobHealth, i as RunStatus, j as StoredJob, k as TriageContext } from './types-BQ1P8z55.js';
-import { Cron } from 'croner';
+import { S as Store, a as AlertChannel, T as TriageFn, D as Duration, J as JobOptions, b as JobDefinition, C as CheckResult, c as JobSummary, R as Run, d as JobState, A as Alert, e as AlertDraft, f as StoredJobDefinition } from './types-DUt2apl0.js';
+export { g as AlertDetails, h as AlertType, B as BudgetBreach, i as Condition, E as ExpectRule, j as JobHealth, k as RunStatus, l as StoredJob, m as TriageContext } from './types-DUt2apl0.js';
 
 /** What a job function receives. */
 interface JobContext {
@@ -20,8 +19,11 @@ interface RoutesOptions {
     /**
      * Required to reach anything. Send it as `Authorization: Bearer <token>`,
      * or open the dashboard once with `?token=<token>` and a cookie is set.
-     * Defaults to process.env.CRONWATCH_TOKEN. With no token at all, the routes
-     * are open in development and refuse to serve in production.
+     * Defaults to process.env.CRONWATCH_TOKEN; an empty string counts as unset.
+     * With no token while NODE_ENV is "development" or "test", the routes make
+     * a random one and print a sign-in link to the server log on their first
+     * request; with no token otherwise they answer 503. Pass `null` to opt out
+     * and serve them open everywhere, for example behind your own auth.
      *
      * The check endpoint (/api/check) also accepts the client's cronSecret, so
      * a platform cron that sends `Authorization: Bearer <CRON_SECRET>` can
@@ -52,7 +54,9 @@ interface HandlerOptions {
     /**
      * Callers must send `Authorization: Bearer <secret>`. Defaults to the
      * client's cronSecret, which defaults to process.env.CRON_SECRET (what
-     * Vercel sends its cron requests with). Pass null to allow anyone.
+     * Vercel sends its cron requests with). An empty string counts as unset.
+     * With no secret at all the handler answers 503 unless NODE_ENV is
+     * "development" or "test". Pass null to allow anyone.
      */
     secret?: string | null;
 }
@@ -71,41 +75,68 @@ interface CronWatchOptions {
     store?: Store;
     /** Where alerts go. Defaults to the console. */
     alerts?: AlertChannel[];
-    /** Adds a short diagnosis to failure alerts. See @cronwatch/sdk/anthropic. */
+    /** Adds a short diagnosis to every alert except recoveries. See @cronwatch/sdk/anthropic. */
     triage?: TriageFn;
-    /** Shared secret that handler() requests must carry. Defaults to process.env.CRON_SECRET. */
+    /**
+     * Shared secret that handler() requests must carry. Defaults to
+     * process.env.CRON_SECRET; an empty string counts as unset. Pass null to
+     * let handlers run without one.
+     */
     cronSecret?: string | null;
     /** How long finished runs are kept. Default "30d". */
     retention?: Duration;
     /** Applied to every job unless the job sets its own. */
     defaults?: Pick<JobOptions, "grace" | "timeout" | "timezone" | "failuresBeforeAlert">;
-    /** Called with anything that goes wrong outside a job: an alert channel failing, a triage timeout. */
+    /**
+     * Applied to every run's output and error before it is stored, shown or
+     * sent to an alert channel or triage. The default blanks values that look
+     * like secrets (password=..., Authorization headers, URL credentials, bearer
+     * tokens, JWTs, PEM private keys, webhook URLs, AWS, GitHub, Slack, Stripe,
+     * Google and API key formats). Pass your own function, or false to keep
+     * output exactly as logged. A function that throws or returns something
+     * other than a string is reported to onError and the default is used.
+     */
+    redact?: ((text: string) => string) | false;
+    /**
+     * "now" (the default) sends alerts from this process. "check" sends nothing
+     * from here: each alert is queued in the store and the next check, in a
+     * process that delivers now, sends it (with triage). For a process that
+     * records runs but cannot reach the network, such as a sandboxed backup job.
+     * Its `alerts` and `triage` are not used.
+     */
+    deliver?: "now" | "check";
+    /** Called with anything that goes wrong outside a job: the store failing, an alert channel failing, a triage timeout. */
     onError?: (error: unknown, where: string) => void;
     /** The clock. Tests use this. */
     now?: () => number;
 }
-interface ExecuteResult<T> {
-    run: Run;
-    result: T | undefined;
-    error: unknown;
-    threw: boolean;
-}
 declare class CronWatch {
     readonly store: Store;
     readonly alerts: AlertChannel[];
     readonly triage: TriageFn | undefined;
+    /** The secret handler() requests must carry, or null when none is set. */
     readonly cronSecret: string | null;
     readonly retentionMs: number;
     readonly now: () => number;
     readonly onError: (error: unknown, where: string) => void;
+    /** cronSecret was passed as null: handlers may run without a secret. */
+    private readonly secretOptOut;
+    private readonly redact;
+    /** "check": queue alerts for another process's check instead of sending them. See CronWatchOptions.deliver. */
+    private readonly deferDelivery;
     private readonly defaults;
     private readonly definitions;
     private readonly synced;
+    /** The tail of each job's queue of state updates. See serial(). */
+    private readonly queues;
     private ready;
     private checking;
     private lastPruneAt;
     private timer;
+    private firstTick;
     private usingDefaultStore;
+    private warnedNoSecret;
+    private warnedDeferredStart;
     constructor(options?: CronWatchOptions);
     /** Declare a job. Call it once, at module level, and keep the handle. */
     job(name: string, options?: JobOptions): JobHandle;
@@ -115,25 +146,80 @@ declare class CronWatch {
     /** The definitions declared in this process. */
     definedJobs(): JobDefinition[];
     private handle;
+    private warnNoSecret;
+    /** onError, for places that must carry on even when onError itself throws. */
+    private report;
     private ensureReady;
     private sync;
-    /** Runs a function as a recorded run. Never throws for the job's own error; see `threw`. */
-    execute<T>(definition: JobDefinition, fn: JobFn<T>, trigger: string): Promise<ExecuteResult<T>>;
     /**
-     * Look for missed and stuck runs across every job, send alerts, and prune
-     * old runs. Call it from an interval (start()), a cron hitting the mounted
-     * routes, or by hand. Concurrent calls share one check.
+     * Runs `fn` after every earlier state update for the same job has settled,
+     * so two runs (or a run and a check) in this process never read and write
+     * the job's state over each other. Other processes are coordinated by
+     * updateState() instead.
+     */
+    private serial;
+    private readState;
+    /**
+     * Every read-modify-write of a job's state goes through here. In turn with
+     * this process's other updates to the job (serial()), it reads the state,
+     * asks `change` for the next one, and writes it with the version one
+     * higher, only if the stored version is still the one read. When another
+     * process wrote in between, the write is refused and it starts again from
+     * a fresh read, up to STATE_ATTEMPTS times. So `change` may run more than
+     * once and must only compute: whatever it returns from the attempt that
+     * was written is the result. Nothing is written when the state is
+     * unchanged. Returns the state as stored.
+     */
+    private updateState;
+    /** A conditional write, or for a store without compareAndSetState, a plain one that always succeeds. */
+    private writeState;
+    /**
+     * Runs a function as a recorded run. The function always runs, whatever
+     * the store is doing: store errors go to onError, and the result is the
+     * function's own outcome. Never throws for the job's own error; see `threw`.
+     */
+    private execute;
+    /** Whether a check already marked this run as timed out, for a failure that finished late. */
+    private markedTimedOut;
+    /**
+     * Record a finished run (ok, failed, or timed out by a check), evaluate it
+     * against the job's state and send what that produces. Never throws.
+     */
+    private finishRun;
+    /**
+     * The runs before `run`, newest first, with up to BASELINE_WINDOW
+     * successful ones when the store has them. One small read normally; a
+     * larger one only when failures crowd the successes out of it.
+     */
+    private history;
+    /**
+     * Look for missed and stuck runs across every job, send alerts, retry
+     * alerts no channel accepted, and prune old runs. Call it from an interval
+     * (start()), a cron hitting the mounted routes, or by hand. Concurrent
+     * calls share one check.
      */
     check(): Promise<CheckResult>;
     private runCheck;
+    /** A job's summary and its newest runs, without alerting. A job that cannot be evaluated is reported and shown as failing. */
+    private snapshot;
+    /** The summary of a job whose evaluation failed, from whatever can still be read. */
+    private unevaluable;
     /** Every job the store knows about, with its health. Does not send alerts. */
     jobs(): Promise<JobSummary[]>;
+    /** Every job's summary with its newest `limit` runs, read together. What the dashboard shows. */
+    jobsWithRuns(limit?: number): Promise<{
+        job: JobSummary;
+        runs: Run[];
+    }[]>;
     jobSummary(name: string): Promise<JobSummary | null>;
+    /** A job's runs, newest first. `limit` is a whole number from 1 to 500. */
     runs(name: string, limit?: number): Promise<Run[]>;
     getRun(id: string): Promise<Run | null>;
     /** Stop alerts for a job for a while. State keeps updating underneath. */
     silence(name: string, duration: Duration): Promise<JobState>;
     unsilence(name: string): Promise<JobState>;
+    /** Read, change and write one job's state, in turn with every other update to it. */
+    private patchState;
     /** Remove a job and its runs from the store. A job still declared in code comes back on its next run. */
     forget(name: string): Promise<void>;
     /** The dashboard and JSON API as fetch-style handlers. See createRoutes(). */
@@ -142,18 +228,36 @@ declare class CronWatch {
     start(every?: Duration): void;
     stop(): void;
     close(): Promise<void>;
-    private summarize;
-    /** Save an evaluation's state, honouring silence, and send its alerts. */
-    private settle;
+    /**
+     * Compose, triage and send each draft. The state was saved before this
+     * (updateState), so a slow channel holds up nothing else; afterwards only
+     * the delivery fields are written back, onto a fresh read of the state.
+     */
     private dispatch;
+    /**
+     * Send the alerts that no channel accepted last time, once each, oldest
+     * first. `state` is the job's state as this check left it: an alert that
+     * no longer describes it (staleAlert) is dropped instead. Retries across a
+     * check share RETRY_BUDGET_MS of wall-clock time; once it is spent the rest
+     * stay queued for the next check.
+     */
+    private retryUndelivered;
+    /**
+     * Mark delivered alerts done, drop stale ones, and keep failed ones for the
+     * next check. A failed alert replaces its stored copy, so a triage made on
+     * this attempt is kept. lastAlertAt moves only on a delivery.
+     */
+    private recordDelivery;
+    /** Send to every channel at once. True when at least one accepted it, or there are none. */
+    private deliver;
+    /** Sets alert.triage to the diagnosis, or to null when there is none, so it is tried once per alert. */
+    private addTriage;
 }
 /** Writes alerts to the console. The default channel. */
 declare function consoleChannel(): AlertChannel;
 /** Wrap any function as an alert channel. */
 declare function custom(name: string, send: (alert: Alert) => Promise<void> | void): AlertChannel;
 
-declare function json(body: unknown, status?: number, headers?: Record<string, string>): Response;
-
 /**
  * Keeps everything in process memory. The default when no store is given,
  * good for tests and for trying the library out. State is gone on restart,
@@ -168,15 +272,14 @@ declare function memory(): Store;
 declare function parseDuration(value: Duration, label?: string): number;
 /** 90000 -> "1m 30s". For messages, not for parsing back. */
 declare function formatDuration(ms: number): string;
-/** "5 minutes ago", "in 2h". Relative to `now`. */
-declare function formatRelative(at: number, now: number): string;
 
 interface ParsedSchedule {
     kind: "cron" | "interval";
     source: string;
+    /** The IANA timezone a cron is read in, when one was given. */
+    timezone?: string;
     /** For intervals, the period in milliseconds. */
     everyMs?: number;
-    cron?: Cron;
 }
 /**
  * "0 2 * * *" (cron, five or six fields), "@hourly", or "every 5m".
@@ -187,23 +290,8 @@ interface ParsedSchedule {
  * timezone: "UTC" for those.
  */
 declare function parseSchedule(schedule: string, timezone?: string): ParsedSchedule;
-/** The next time the cron fires strictly after `from`. */
+/** The next time the schedule fires strictly after `from`. For an interval, counted from the last run when there is one. */
 declare function nextFire(parsed: ParsedSchedule, from: number, lastRunAt: number | null): number | null;
-/**
- * The most recent time the cron fired at or before `now`, or null when the
- * expression never fires in the year before `now`.
- *
- * croner only looks forward, so this searches: widen a window behind `now`
- * until a fire time falls inside it, then bisect on the window's start for
- * the latest start whose next fire is still at or before `now`.
- */
-declare function previousFire(parsed: ParsedSchedule, now: number): number | null;
-
-interface AlertDraft {
-    type: Condition | "recovered";
-    run: Run | null;
-    details: Record<string, unknown>;
-}
 
 /** Turns a draft into the title and message every channel shows. */
 declare function composeAlert(draft: AlertDraft, def: StoredJobDefinition, now: number): Alert;
@@ -216,4 +304,4 @@ declare function composeAlert(draft: AlertDraft, def: StoredJobDefinition, now:
  */
 declare function cronwatch(options?: CronWatchOptions): CronWatch;
 
-export { Alert, AlertChannel, CheckResult, Condition, CronWatch, type CronWatchOptions, Duration, type HandlerFn, type HandlerOptions, type JobContext, JobDefinition, type JobFn, type JobHandle, JobOptions, JobState, JobSummary, type Routes, type RoutesOptions, Run, Store, StoredJobDefinition, TriageFn, composeAlert, consoleChannel, createRoutes, cronwatch, custom, formatDuration, formatRelative, json, memory, nextFire, parseDuration, parseSchedule, previousFire };
+export { Alert, AlertChannel, AlertDraft, CheckResult, CronWatch, type CronWatchOptions, Duration, type FetchHandler, type HandlerFn, type HandlerOptions, type JobContext, JobDefinition, type JobFn, type JobHandle, JobOptions, JobState, JobSummary, type ParsedSchedule, type Routes, type RoutesOptions, Run, Store, StoredJobDefinition, TriageFn, composeAlert, consoleChannel, createRoutes, cronwatch, custom, formatDuration, memory, nextFire, parseDuration, parseSchedule };