@cronwatch/sdk 0.9.0 → 0.11.0

package/dist/index.js

@@ -78,13 +78,46 @@ function beyondDates(at) {
 function readEnv(name) {
   return typeof process === "undefined" || !process.env ? void 0 : process.env[name];
 }
+function readSecretEnv(name) {
+  const value = readEnv(name);
+  return value === void 0 || value.trim() === "" ? void 0 : value;
+}
+function secretOption(value, what) {
+  if (value === void 0 || value === null) return value;
+  if (typeof value !== "string") {
+    throw new TypeError(`${what} must be a string, or null to opt out, not ${Array.isArray(value) ? "an array" : typeof value}`);
+  }
+  return value.trim() === "" ? void 0 : value;
+}
+function environment() {
+  if (typeof process === "undefined" || !process.env) return "";
+  for (const value of [process.env.CRONWATCH_ENV, process.env.APP_ENV, process.env.NODE_ENV]) {
+    const name = typeof value === "string" ? value.trim().toLowerCase() : "";
+    if (name === "") continue;
+    if (name === "prod") return "production";
+    if (name === "dev" || name === "local" || name === "test" || name === "testing") return "development";
+    return name;
+  }
+  return "";
+}
 function isDevelopment() {
-  if (typeof process === "undefined" || !process.env) return false;
-  const mode = process.env.NODE_ENV;
-  return mode === "development" || mode === "test";
+  return environment() === "development";
+}
+function isProduction() {
+  return environment() === "production";
 }
 var cache = /* @__PURE__ */ new Map();
 var crons = /* @__PURE__ */ new WeakMap();
+var never = /* @__PURE__ */ new WeakSet();
+var PROBE_FROM_MS = Date.UTC(2e3, 0, 1);
+function neverFires(cron) {
+  try {
+    return cron.nextRuns(1, new Date(PROBE_FROM_MS)).length === 0;
+  } catch (error) {
+    return error instanceof RangeError && /call stack/i.test(error.message);
+  }
+}
+var ONE_TIME_DATE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/;
 var EARLY_SLACK_MS = 6e4;
 function parseSchedule(schedule, timezone) {
   const key = `${timezone ?? ""}|${schedule}`;
@@ -98,6 +131,10 @@ function parseSchedule(schedule, timezone) {
     if (everyMs < 1e3) throw new Error(`schedule "${schedule}" is shorter than one second`);
     parsed = { kind: "interval", source: text, everyMs };
   } else {
+    if (text.slice(1).includes(":")) {
+      const reason = ONE_TIME_DATE.test(text) ? "CronPattern: a one-time date is not supported" : "Invalid ISO8601 passed to timezone parser.";
+      throw new Error(`schedule "${schedule}" is not a cron expression or "every <duration>": ${reason}`);
+    }
     let cron;
     try {
       cron = new Cron(text, timezone ? { timezone } : {});
@@ -106,6 +143,7 @@ function parseSchedule(schedule, timezone) {
     }
     parsed = { kind: "cron", source: text, ...timezone ? { timezone } : {} };
     crons.set(parsed, cron);
+    if (neverFires(cron)) never.add(parsed);
   }
   cache.set(key, parsed);
   return parsed;
@@ -132,6 +170,7 @@ function countFrom(from) {
 function fireAfter(parsed, from) {
   const cron = crons.get(parsed);
   if (!cron) throw new Error(`schedule "${parsed.source}" was not made by parseSchedule`);
+  if (never.has(parsed)) return null;
   const start = countFrom(from);
   if (start === null) return null;
   let probe = start;
@@ -147,6 +186,7 @@ function fireAfter(parsed, from) {
 function firesBetween(parsed, from, to, limit) {
   const cron = crons.get(parsed);
   if (!cron) throw new Error(`schedule "${parsed.source}" was not made by parseSchedule`);
+  if (never.has(parsed)) return [];
   const out = [];
   const start = countFrom(from);
   if (start === null) return out;
@@ -266,6 +306,9 @@ function runDuration(startedAt, finishedAt) {
   const ms = finishedAt - startedAt;
   return ms > 0 ? Math.min(ms, MAX_DURATION_MS) : 0;
 }
+function silenceEnd(now, ms) {
+  return Math.min(now + Math.floor(Math.min(ms, MAX_DURATION_MS)), MAX_DURATION_MS);
+}
 function stateVersion(state) {
   const version = state?.version;
   return typeof version === "number" && Number.isSafeInteger(version) && version >= 0 ? version + 0 : 0;
@@ -278,17 +321,74 @@ function failureCount(state) {
 function emptyState(job) {
   return { job, open: {}, consecutiveFailures: 0, silencedUntil: null, lastAlertAt: null, pendingRecovery: [], undelivered: [] };
 }
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function normalizeState(state, job) {
-  if (!state) return emptyState(job);
+  if (!isObject(state)) return emptyState(job);
+  const { sending, ...rest } = state;
+  const open = isObject(state.open) ? Object.fromEntries(Object.entries(state.open).filter(([, at]) => typeof at === "number")) : {};
+  const number = (value) => typeof value === "number" ? value : null;
+  const list = (value) => Array.isArray(value) ? value : [];
   return {
     ...emptyState(job),
-    ...state,
-    open: { ...state.open },
+    ...rest,
+    open,
     consecutiveFailures: failureCount(state),
-    pendingRecovery: [...state.pendingRecovery ?? []],
-    undelivered: [...state.undelivered ?? []]
+    silencedUntil: number(state.silencedUntil),
+    lastAlertAt: number(state.lastAlertAt),
+    pendingRecovery: list(state.pendingRecovery).filter((c) => typeof c === "string"),
+    undelivered: list(state.undelivered).filter((alert) => isObject(alert)),
+    ...Array.isArray(sending) && sending.length > 0 ? { sending: [...sending] } : {}
   };
 }
+var MAX_UNDELIVERED = 20;
+var SEND_LEASE_MS = 5 * 6e4;
+function alertKey(alert) {
+  return `${alert.type}|${alert.at}|${alert.run?.id ?? ""}`;
+}
+function newest(list, max) {
+  return { kept: list.slice(-max), dropped: Math.max(0, list.length - max) };
+}
+function queueUndelivered(state, alerts) {
+  const next = cloneState(state);
+  const byKey = new Map(alerts.map((alert) => [alertKey(alert), alert]));
+  const queue = next.undelivered.map((alert) => byKey.get(alertKey(alert)) ?? alert);
+  const known = new Set(queue.map(alertKey));
+  queue.push(...alerts.filter((alert) => !known.has(alertKey(alert))));
+  const { kept, dropped } = newest(queue, MAX_UNDELIVERED);
+  next.undelivered = kept;
+  return { state: next, dropped };
+}
+function holdAlerts(state, alerts, until, deferred) {
+  if (alerts.length === 0) return { state, dropped: 0 };
+  if (deferred) return queueUndelivered(state, alerts);
+  const next = cloneState(state);
+  const { kept, dropped } = newest([...next.sending ?? [], ...alerts.map((alert) => ({ until, alert }))], MAX_UNDELIVERED);
+  next.sending = kept;
+  return { state: next, dropped };
+}
+function releaseSending(state, now) {
+  const sending = state.sending ?? [];
+  const lapsed = sending.filter((entry) => !(typeof entry?.until === "number" && entry.until > now));
+  if (lapsed.length === 0) return { state, dropped: 0 };
+  const held = sending.filter((entry) => !lapsed.includes(entry));
+  return queueUndelivered(
+    { ...state, sending: held },
+    lapsed.filter((entry) => typeof entry?.alert === "object" && entry.alert !== null).map((entry) => entry.alert)
+  );
+}
+function recordSent(state, delivered, failed, stale, now) {
+  const next = cloneState(state);
+  const done = new Set([...delivered, ...stale].map(alertKey));
+  next.undelivered = next.undelivered.filter((alert) => !done.has(alertKey(alert)));
+  const sent = new Set([...delivered, ...failed, ...stale].map(alertKey));
+  const held = (next.sending ?? []).filter((entry) => !(typeof entry?.alert === "object" && entry.alert !== null && sent.has(alertKey(entry.alert))));
+  if (held.length > 0) next.sending = held;
+  else delete next.sending;
+  if (delivered.length > 0) next.lastAlertAt = now;
+  return queueUndelivered(next, failed);
+}
 function cloneState(state) {
   return normalizeState(state, state.job);
 }
@@ -442,8 +542,12 @@ function applySilence(previous, evaluation, now) {
   return { state: muteOpens(previous, evaluation.state), alerts: [] };
 }
 function staleAlert(alert, state) {
-  if (alert.type === "recovered") return alert.details.after.some((condition) => state.open[condition] !== void 0);
-  return state.open[alert.type] !== alert.at;
+  if (alert.type === "recovered") {
+    const after2 = isObject(alert.details) ? alert.details.after : void 0;
+    if (!Array.isArray(after2)) return true;
+    return after2.some((condition) => typeof condition !== "string" || state.open[condition] !== void 0);
+  }
+  return typeof alert.at !== "number" || state.open[alert.type] !== alert.at;
 }
 function jobHealth(def, lastRun, state, now) {
   const open = openConditions(state);
@@ -592,7 +696,16 @@ var OUTPUT_CAP = 16 * 1024;
 function capOutput(text) {
   const clean = stripNul(text);
   if (clean.length <= OUTPUT_CAP) return clean;
-  return "[earlier output trimmed]\n" + clean.slice(clean.length - OUTPUT_CAP);
+  return TRIMMED + clean.slice(clean.length - OUTPUT_CAP);
+}
+var TRIMMED = "[earlier output trimmed]\n";
+var REDACT_EDGE = 3 * (OUTPUT_CAP + 1024);
+function redactAndCap(text, redact) {
+  const clean = stripNul(text);
+  const from = clean.length - (OUTPUT_CAP + REDACT_EDGE);
+  if (from <= 0) return capOutput(redact(clean));
+  const redacted = stripNul(redact(clean.slice(from)));
+  return TRIMMED + redacted.slice(Math.max(redacted.length - OUTPUT_CAP, REDACT_EDGE));
 }
 function stripNul(text) {
   return text.includes("\0") ? text.replace(/\u0000/g, "") : text;
@@ -600,9 +713,6 @@ function stripNul(text) {
 function stripJsonNul(json2) {
   return json2.includes("\\u0000") ? json2.replace(/\\(u0000|[\s\S])/g, (escape, next) => next === "u0000" ? "" : escape) : json2;
 }
-function errorMessage(error) {
-  return capOutput(describeError(error));
-}
 function describeError(error) {
   if (error instanceof Error) {
     const frames = (error.stack ?? "").split("\n").filter((line) => /^\s+at /.test(line)).slice(0, 5);
@@ -711,7 +821,7 @@ function createRecorder(run) {
   };
   return {
     context,
-    output: () => lines.length === 0 ? null : capOutput(lines.join("\n")),
+    output: () => lines.length === 0 ? null : lines.join("\n"),
     expectText: () => {
       if (lines.length === 0) return null;
       const all = lines.join("\n");
@@ -750,6 +860,15 @@ function checkExpectation(expect, output) {
   }
   return ok ? null : "Output did not pass the expect() check";
 }
+function readStoredJob(stored) {
+  const definition = stored.definition;
+  if (typeof definition !== "object" || definition === null || Array.isArray(definition)) {
+    return { job: { ...stored, definition: { name: stored.name } }, readable: false };
+  }
+  const read = { ...definition };
+  if ("tags" in read && !(Array.isArray(read.tags) && read.tags.every((tag) => typeof tag === "string"))) delete read.tags;
+  return { job: { ...stored, definition: read }, readable: true };
+}
 
 // src/routes/escape.ts
 function escapeHtml(value) {
@@ -1452,7 +1571,7 @@ function jobPage(job, runs, now, base, complete = true) {
       run.error ? `<details class="out error" open><summary>error</summary><pre>${h(run.error)}</pre></details>` : "",
       run.output ? `<details class="out"${run.status === "ok" ? "" : " open"}><summary>output</summary><pre>${h(run.output)}</pre></details>` : ""
     ].join("");
-    const metrics = Object.entries(run.metrics).map(([k, v]) => `<span><span class="k">${h(k)}</span> ${h(Number.isInteger(v) ? v : v.toFixed(4))}</span>`).join("");
+    const metrics = Object.entries(run.metrics ?? {}).filter(([, v]) => typeof v === "number" && Number.isFinite(v)).map(([k, v]) => `<span><span class="k">${h(k)}</span> ${h(Number.isInteger(v) ? v : v.toFixed(4))}</span>`).join("");
     return `<tr${detail ? ` class="has-detail"` : ""}>
 <td class="nowrap">${runState(run)}</td>
 <td class="nowrap">${h(when2(run.startedAt, now))} <span class="muted">UTC</span><span class="sub">${stamp(run.startedAt, now)}</span></td>
@@ -1521,12 +1640,18 @@ function jobPage(job, runs, now, base, complete = true) {
   return layout(`${job.name}: CronWatch`, body, base, { refresh: 60 });
 }
 function messagePage(title, message, base, signIn = false) {
-  const form = signIn ? `<form class="signin" method="get" action="${h(base)}/"><label for="token">Token</label><input id="token" name="token" type="password" autocomplete="current-password" autocapitalize="off" spellcheck="false" required><button class="primary" type="submit">Sign in</button></form>` : "";
+  const form = signIn ? `<form class="signin" method="post" action="${h(base)}/signin"><label for="token">Token</label><input id="token" name="token" type="password" autocomplete="current-password" autocapitalize="off" spellcheck="false" required><button class="primary" type="submit">Sign in</button></form>` : "";
   return layout(title, `<header class="top">${brand(base)}</header><main class="message"><h1>${h(title)}</h1><p>${h(message)}</p>${form}</main>`, base);
 }
 
+// src/version.ts
+var VERSION = "0.11.0";
+var API_VERSION = 1;
+
 // src/routes/index.ts
 var COOKIE = "cronwatch_token";
+var LIBRARY = "@cronwatch/sdk";
+var LANGUAGE = "typescript";
 async function cookieValue(token) {
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`cronwatch-cookie:${token}`));
   return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
@@ -1610,6 +1735,20 @@ function forwardedOrigin(request, url) {
     return url.origin;
   }
 }
+function bearerToken(header) {
+  const match = header === null ? null : /^Bearer\s+([\s\S]*)$/i.exec(header);
+  return match ? match[1] : null;
+}
+function signInReturn(referer, publicOrigin, base) {
+  if (referer === null || !referer.startsWith(publicOrigin + "/")) return `${base}/`;
+  let url;
+  try {
+    url = new URL(referer);
+  } catch {
+    return `${base}/`;
+  }
+  return url.searchParams.has("token") ? `${base}/` : referer;
+}
 function stripBase(pathname, base) {
   let path = pathname.startsWith(base) ? pathname.slice(base.length) : pathname;
   if (path === "") path = "/";
@@ -1652,8 +1791,12 @@ function runsLimit(value) {
   return Number.isFinite(n) ? Math.min(MAX_RUNS, Math.max(1, n)) : DEFAULT_RUNS;
 }
 function createRoutes(cw, options = {}) {
+  return cw.routes(options);
+}
+function buildRoutes(cw, options = {}) {
   const optedOut = options.token === null;
-  const configured = optedOut ? null : options.token || readEnv("CRONWATCH_TOKEN") || null;
+  const given = secretOption(options.token, "routes: token");
+  const configured = optedOut ? null : given || readSecretEnv("CRONWATCH_TOKEN") || null;
   const base = (options.basePath ?? "/cronwatch").replace(/\/+$/, "");
   const developing = isDevelopment();
   const fixedOrigin = configuredOrigin(options.origin);
@@ -1685,7 +1828,17 @@ function createRoutes(cw, options = {}) {
     if (method !== "GET" && method !== "HEAD" && crossSite(request, publicOrigin)) {
       return wantsHtml ? html(messagePage("Cross-site request refused", "Changes can only be made from the dashboard itself.", base), 403) : api({ ok: false, error: "Cross-site request refused" }, 403);
     }
-    const bearer = request.headers.get("authorization")?.replace(/^Bearer\s+/i, "") ?? null;
+    const bearer = bearerToken(request.headers.get("authorization"));
+    const signInCookie = async () => {
+      const secure = publicOrigin.startsWith("https:") ? "; Secure" : "";
+      return `${COOKIE}=${await expectedCookie(token)}; Path=${base || "/"}; HttpOnly; SameSite=Lax; Max-Age=${60 * 60 * 24 * 30}${secure}`;
+    };
+    const signInPage = () => generated ? html(messagePage("Sign in", "CRONWATCH_TOKEN is not set, so this development server made a token. The sign-in link is in the server log: open it once, or enter the token from it below, and this browser stays signed in.", base, true), 401) : html(messagePage("Sign in", "Enter your CRONWATCH_TOKEN and this browser stays signed in.", base, true), 401);
+    if (token && method === "POST" && path === "/signin") {
+      const sent = (await readBody(request)).token;
+      if (sent === void 0 || !constantTimeEqual(sent, token)) return signInPage();
+      return redirect(signInReturn(request.headers.get("referer"), publicOrigin, base), { "set-cookie": await signInCookie() });
+    }
     if (token) {
       const query = wantsHtml && method === "GET" ? url.searchParams.get("token") : null;
       const sent = readCookie(request, COOKIE);
@@ -1693,17 +1846,12 @@ function createRoutes(cw, options = {}) {
       const cronSecretOk = isCheck && bearer !== null && cw.cronSecret !== null && constantTimeEqual(bearer, cw.cronSecret);
       const tokenOk = bearer !== null ? constantTimeEqual(bearer, token) : query !== null ? constantTimeEqual(query, token) : sent !== null && constantTimeEqual(sent, await expectedCookie(token));
       if (!cronSecretOk && !tokenOk) {
-        if (generated) {
-          return wantsHtml ? html(messagePage("Sign in", "CRONWATCH_TOKEN is not set, so this development server made a token. The sign-in link is in the server log: open it once and this browser stays signed in.", base, true), 401) : api({ ok: false, error: "Unauthorized: CRONWATCH_TOKEN is not set, so this development server made a token; it is in the server log" }, 401);
-        }
-        return wantsHtml ? html(messagePage("Sign in", `Open this page with ?token=<your CRONWATCH_TOKEN> once and it will stay signed in.`, base, true), 401) : api({ ok: false, error: "Unauthorized" }, 401);
+        if (wantsHtml) return signInPage();
+        return generated ? api({ ok: false, error: "Unauthorized: CRONWATCH_TOKEN is not set, so this development server made a token; it is in the server log" }, 401) : api({ ok: false, error: "Unauthorized" }, 401);
       }
       if (query !== null) {
         url.searchParams.delete("token");
-        const secure = publicOrigin.startsWith("https:") ? "; Secure" : "";
-        return redirect(url.pathname + (url.search || ""), {
-          "set-cookie": `${COOKIE}=${await expectedCookie(token)}; Path=${base || "/"}; HttpOnly; SameSite=Lax; Max-Age=${60 * 60 * 24 * 30}${secure}`
-        });
+        return redirect(url.pathname + (url.search || ""), { "set-cookie": await signInCookie() });
       }
     }
     const redirectBack = () => {
@@ -1754,6 +1902,9 @@ function createRoutes(cw, options = {}) {
     }
     if (parts[0] === "api") {
       const rest = parts.slice(1);
+      if (method === "GET" && rest.length === 0) {
+        return api({ ok: true, library: LIBRARY, language: LANGUAGE, version: VERSION, api: API_VERSION });
+      }
       if (method === "GET" && rest[0] === "jobs" && rest.length === 1) {
         return api({ ok: true, jobs: await cw.jobs() });
       }
@@ -1781,9 +1932,13 @@ function createRoutes(cw, options = {}) {
           } catch (e) {
             return api({ ok: false, error: e.message }, 400);
           }
-          return api({ ok: true, state: await cw.silence(name, duration) });
+          await cw.silence(name, duration);
+          return api({ ok: true, job: await cw.jobSummary(name) });
+        }
+        if (rest[2] === "unsilence") {
+          await cw.unsilence(name);
+          return api({ ok: true, job: await cw.jobSummary(name) });
         }
-        if (rest[2] === "unsilence") return api({ ok: true, state: await cw.unsilence(name) });
       }
       if (rest[0] === "check" && rest.length === 1) {
         if (method === "GET" && bearer === null) {
@@ -1931,11 +2086,11 @@ function memory() {
       return true;
     },
     async prune(before) {
-      const newest = /* @__PURE__ */ new Map();
-      for (const run of runs.values()) newest.set(run.job, Math.max(newest.get(run.job) ?? -Infinity, run.startedAt));
+      const newest2 = /* @__PURE__ */ new Map();
+      for (const run of runs.values()) newest2.set(run.job, Math.max(newest2.get(run.job) ?? -Infinity, run.startedAt));
       let n = 0;
       for (const [id, run] of runs) {
-        if (run.status !== "running" && run.startedAt < before && run.startedAt < newest.get(run.job)) {
+        if (run.status !== "running" && run.startedAt < before && run.startedAt < newest2.get(run.job)) {
           runs.delete(id);
           order.delete(id);
           n++;
@@ -1951,7 +2106,6 @@ var NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/;
 var TRIAGE_TIMEOUT_MS = 25e3;
 var CHANNEL_TIMEOUT_MS = 15e3;
 var PRUNE_INTERVAL_MS = 60 * 6e4;
-var MAX_UNDELIVERED = 20;
 var RETRY_BUDGET_MS = 2e4;
 var STATE_ATTEMPTS = 10;
 var HISTORY_PAGE = BASELINE_WINDOW + 5;
@@ -1992,10 +2146,7 @@ function validateDefinition(def) {
 function sameState(a, b) {
   return JSON.stringify(a) === JSON.stringify(b);
 }
-function alertKey(alert) {
-  return `${alert.type}|${alert.at}|${alert.run?.id ?? ""}`;
-}
-var CronWatch = class {
+var Cronwatch = class {
   store;
   alerts;
   triage;
@@ -2008,7 +2159,7 @@ var CronWatch = class {
   /** cronSecret was passed as null: handlers may run without a secret. */
   secretOptOut;
   redact;
-  /** "check": queue alerts for another process's check instead of sending them. See CronWatchOptions.deliver. */
+  /** "check": queue alerts for another process's check instead of sending them. See CronwatchOptions.deliver. */
   deferDelivery;
   defaults;
   definitions = /* @__PURE__ */ new Map();
@@ -2027,12 +2178,15 @@ var CronWatch = class {
   usingDefaultStore = false;
   warnedNoSecret = false;
   warnedDeferredStart = false;
+  /** Stored jobs read with a definition that was not a JSON object (see readJob). */
+  unreadable = /* @__PURE__ */ new WeakSet();
   constructor(options = {}) {
     this.store = options.store ?? (this.usingDefaultStore = true, memory());
     this.alerts = options.alerts ?? [consoleChannel()];
     this.triage = options.triage;
     this.sources = options.sources ?? [];
-    const secret = options.cronSecret === void 0 ? readEnv("CRON_SECRET") : options.cronSecret;
+    const given = secretOption(options.cronSecret, "cronSecret");
+    const secret = options.cronSecret === void 0 ? readSecretEnv("CRON_SECRET") : given;
     this.cronSecret = secret ? secret : null;
     this.secretOptOut = options.cronSecret === null;
     this.retentionMs = parseDuration(options.retention ?? "30d", "retention");
@@ -2093,7 +2247,7 @@ var CronWatch = class {
         return outcome.result;
       },
       handler(fn, options) {
-        const own = options?.secret;
+        const own = secretOption(options?.secret, "handler: secret");
         const secret = own === null ? null : own ? own : self.cronSecret;
         const optedOut = own === null || !own && self.secretOptOut;
         return async (request) => {
@@ -2145,7 +2299,7 @@ var CronWatch = class {
     if (!this.ready) {
       this.ready = (async () => {
         if (this.store.init) await this.store.init();
-        if (this.usingDefaultStore && readEnv("NODE_ENV") === "production") {
+        if (this.usingDefaultStore && isProduction()) {
           console.warn("[cronwatch] using the in-memory store: runs and state are lost on restart. Pass a store from @cronwatch/sdk/sqlite or @cronwatch/sdk/postgres.");
         }
       })().catch((error) => {
@@ -2161,19 +2315,58 @@ var CronWatch = class {
    * that replaced it, never its own over it, and one forgotten since writes
    * its own. The writes of one name take turns, in the order they were asked
    * for, so one still under way cannot land after a later one; and a name
-   * declared again while its write was under way is still to be written.
+   * declared again while its write was under way is still to be written. A
+   * name is marked as written only while that same declaration stands, so a
+   * forget that lands during the write (deleting the row after it) leaves
+   * the name to be written again, as does one forgotten before it.
+   *
+   * With `confirm`, as a run starts, a name already written is read back:
+   * another process may have forgotten the job since, and a job still
+   * declared here comes back on its next run.
    */
-  async sync(definition) {
+  async sync(definition, confirm = false) {
     await this.ensureReady();
     const name = definition.name;
-    if (this.synced.has(name)) return;
+    if (this.synced.has(name)) {
+      if (!confirm || await this.store.getJob(name)) return;
+      this.synced.delete(name);
+    }
     await this.serial(name, async () => {
       if (this.synced.has(name)) return;
       const standing = this.definitions.get(name) ?? definition;
       await this.store.upsertJob(toStored(standing), this.now());
-      if ((this.definitions.get(name) ?? standing) === standing) this.synced.add(name);
+      if (this.definitions.get(name) === standing) this.synced.add(name);
     }, this.syncing);
   }
+  /**
+   * Every stored job, once each declaration has been written. A job declared
+   * here that the store no longer has was forgotten by another process after
+   * this one wrote it: it is written again, as its next run would, so it is
+   * checked and shown while any process still declares it.
+   */
+  async storedJobs() {
+    for (const definition of this.definitions.values()) await this.sync(definition);
+    const jobs = await this.store.listJobs();
+    const listed = new Set(jobs.map((job) => job.name));
+    const missing = [...this.definitions.values()].filter((definition) => !listed.has(definition.name));
+    if (missing.length === 0) return jobs.map((job) => this.readJob(job));
+    for (const definition of missing) {
+      if (this.definitions.get(definition.name) !== definition) continue;
+      this.synced.delete(definition.name);
+      await this.sync(definition);
+    }
+    return (await this.store.listJobs()).map((job) => this.readJob(job));
+  }
+  /** A stored job read leniently (readStoredJob); one whose definition is unreadable is remembered, so that evaluating it throws. */
+  readJob(stored) {
+    const { job, readable } = readStoredJob(stored);
+    if (!readable) this.unreadable.add(job);
+    return job;
+  }
+  /** Throws for a job whose stored definition was not a JSON object: reported, and shown as failing, while the others carry on. */
+  evaluable(stored) {
+    if (this.unreadable.has(stored)) throw new Error(`job "${stored.name}": its stored definition is not a JSON object`);
+  }
   /**
    * 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
@@ -2249,7 +2442,7 @@ var CronWatch = class {
     };
     let recorded = false;
     try {
-      await this.sync(definition);
+      await this.sync(definition, true);
       await this.store.insertRun({ ...run });
       recorded = true;
     } catch (e) {
@@ -2274,7 +2467,7 @@ var CronWatch = class {
     run.finishedAt = finishedAt;
     run.durationMs = runDuration(startedAt, finishedAt);
     run.metrics = recorder.metrics();
-    run.output = recorder.output() ?? (typeof result === "string" ? capOutput(result) : null);
+    run.output = recorder.output() ?? (typeof result === "string" ? result : null);
     this.conclude(definition, run, result, error, threw, recorder.expectText() ?? (typeof result === "string" ? result : null));
     await started;
     try {
@@ -2287,12 +2480,13 @@ var CronWatch = class {
   }
   /**
    * Sets a finished run's status and error from how it ended, then redacts
-   * its output and error. Shared by execute() and RunHandle.finish().
+   * its output and error and caps them, in that order. Shared by execute()
+   * and RunHandle.finish().
    */
   conclude(definition, run, result, error, threw, expectText) {
     if (threw) {
       run.status = "failed";
-      run.error = errorMessage(error);
+      run.error = describeError(error);
     } else if (result instanceof Response && result.status >= 400) {
       run.status = "failed";
       run.error = `HTTP ${result.status}${result.statusText ? ` ${result.statusText}` : ""}`;
@@ -2305,8 +2499,8 @@ var CronWatch = class {
         run.status = "ok";
       }
     }
-    if (run.output !== null) run.output = stripNul(this.redact(run.output));
-    if (run.error !== null) run.error = stripNul(this.redact(run.error));
+    if (run.output !== null) run.output = redactAndCap(run.output, this.redact);
+    if (run.error !== null) run.error = redactAndCap(run.error, this.redact);
   }
   /**
    * Writes a finished run and evaluates it. `recorded` says whether its
@@ -2401,7 +2595,7 @@ ${id}`;
     };
     let recorded = false;
     try {
-      await this.sync(definition);
+      await this.sync(definition, true);
       await this.store.insertRun({ ...run });
       recorded = true;
     } catch (e) {
@@ -2501,14 +2695,15 @@ ${id}`;
         const result = typeof outcome === "string" ? outcome : failed ? void 0 : outcome?.result;
         const error = failed ? outcome.error : void 0;
         const finishedAt = self.now();
-        const added = recorder.output() ?? (typeof result === "string" ? capOutput(result) : null);
+        const added = recorder.output() ?? (typeof result === "string" ? result : null);
         const run = {
           ...from,
           status: "running",
           finishedAt,
           durationMs: runDuration(from.startedAt, finishedAt),
           error: null,
-          output: joinOutput(from.output, added),
+          // Capped by conclude(), after it is redacted.
+          output: joinLines(from.output, added),
           metrics: { ...from.metrics, ...recorder.metrics() }
         };
         const expectText = joinLines(head, joinLines(from.output, recorder.expectText() ?? (typeof result === "string" ? result : null)));
@@ -2557,7 +2752,7 @@ ${id}`;
             self.report(new Error(`run ${id} of ${name} belongs to job "${stored.job}"; ignored`), `flushing ${name}`);
             return;
           }
-          const output = lines === null ? stored.output : joinOutput(stored.output, stripNul(self.redact(lines)));
+          const output = lines === null ? stored.output : joinOutput(stored.output, redactAndCap(lines, self.redact));
           if (!await self.writeRunIf({ ...stored, output, metrics: { ...stored.metrics, ...metrics } }, ["running"])) return putBack();
           const text = taken.expectText();
           if (text !== null && (head === null || head.length < OUTPUT_CAP)) head = (joinLines(head, text) ?? "").slice(0, OUTPUT_CAP);
@@ -2582,13 +2777,23 @@ ${id}`;
    * alone and reported. A finished run is judged as if it had been wrapped
    * here (expect, failures, duration, budgets) and its output and error are
    * redacted the same way; one finishing after a check marked it timeout is
-   * judged only when it succeeded, as RunHandle.finish() does. Returns the
-   * alerts it sent.
+   * judged only when it succeeded, as RunHandle.finish() does. A metric that
+   * is not a finite number throws before anything is written, as
+   * job.metric() does. Returns the alerts it sent.
    */
   async recordRun(input, options = {}) {
     const declared = this.definitions.get(input.job);
     if (!declared) throw new Error(`recordRun: job "${input.job}" is not declared; call job() first`);
+    if (typeof input.id !== "string" || input.id.length === 0 || input.id.length > MAX_RUN_ID) {
+      const got = typeof input.id === "string" ? `${input.id.length} characters` : typeof input.id;
+      throw new Error(`recordRun: run ids must be 1 to ${MAX_RUN_ID} characters (got ${got}; job "${input.job}")`);
+    }
     if (input.id.includes("\0")) throw new Error(`recordRun: run ids cannot contain a NUL character (job "${input.job}")`);
+    for (const [metric, value] of Object.entries(input.metrics ?? {})) {
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`recordRun: metric "${metric}" must be a finite number (job "${input.job}", run "${input.id}")`);
+      }
+    }
     await this.sync(declared);
     const run = { ...input, metrics: { ...input.metrics } };
     if (run.status === "ok") {
@@ -2598,8 +2803,8 @@ ${id}`;
         run.error = unmet;
       }
     }
-    if (run.output !== null) run.output = stripNul(this.redact(capOutput(run.output)));
-    if (run.error !== null) run.error = stripNul(this.redact(capOutput(run.error)));
+    if (run.output !== null) run.output = redactAndCap(run.output, this.redact);
+    if (run.error !== null) run.error = redactAndCap(run.error, this.redact);
     const evaluate = options.evaluate !== false;
     const definition = toStored(declared);
     const stored = await this.store.getRun(run.id);
@@ -2633,22 +2838,42 @@ ${id}`;
   }
   /**
    * Evaluate a finished run (ok, failed, or timed out by a check), already
-   * written, against the job's state and send what that produces. Never throws.
+   * written, against the job's state and send what that produces. The
+   * alerts are written with that state (see outbox()). Never throws.
    */
   async finishRun(definition, run, now) {
-    let drafts;
+    let held;
     try {
       let history = null;
-      ({ result: drafts } = await this.updateState(run.job, async (previous) => {
+      ({ result: held } = await this.updateState(run.job, async (previous) => {
         history ??= await this.history(run);
-        const settled = applySilence(previous, onRunFinish(definition, run, previous, history, now), now);
-        return { state: settled.state, result: settled.alerts };
+        return this.outbox(applySilence(previous, onRunFinish(definition, run, previous, history, now), now), definition, now);
       }));
     } catch (e) {
       this.onError(e, `evaluating ${run.job}`);
       return [];
     }
-    return this.dispatch(drafts, definition, now);
+    this.reportDropped(run.job, held.dropped);
+    return this.dispatch(run.job, held.alerts, now);
+  }
+  /**
+   * An evaluation as it is written: its drafts composed into alerts and held
+   * in the same state (holdAlerts), so the write that opens a condition also
+   * keeps its alerts, and a process that stops before sending them does not
+   * lose them. Called inside updateState(), so it only computes.
+   */
+  outbox(settled, definition, now) {
+    const alerts = settled.alerts.map((draft) => composeAlert(draft, definition, now));
+    const { state, dropped } = holdAlerts(settled.state, alerts, this.now() + SEND_LEASE_MS, this.deferDelivery);
+    return { state, result: { alerts, dropped } };
+  }
+  /** Reports alerts let go because a job's queue was full. */
+  reportDropped(name, dropped) {
+    if (dropped <= 0) return;
+    this.report(
+      new Error(`${dropped} undelivered alert${dropped === 1 ? "" : "s"} for ${name} dropped: only the newest ${MAX_UNDELIVERED} are kept for retry`),
+      `alert queue for ${name}`
+    );
   }
   /**
    * The runs before `run`, newest first, with up to BASELINE_WINDOW
@@ -2688,11 +2913,16 @@ ${id}`;
     }
     for (const definition of this.definitions.values()) await this.sync(definition);
     const now = this.now();
-    for (const run of await this.store.runningRuns()) {
+    for (const listed of await this.store.runningRuns()) {
       try {
-        const declared = this.definitions.get(run.job);
-        const definition = declared ? toStored(declared) : (await this.store.getJob(run.job))?.definition;
-        if (!definition || !isStuck(definition, run, now)) continue;
+        const declared = this.definitions.get(listed.job);
+        const found = declared ? null : await this.store.getJob(listed.job);
+        const stored = found ? this.readJob(found) : null;
+        if (stored) this.evaluable(stored);
+        const definition = declared ? toStored(declared) : stored?.definition;
+        if (!definition || !isStuck(definition, listed, now)) continue;
+        const run = await this.store.getRun(listed.id);
+        if (!run || run.status !== "running" || run.job !== listed.job) continue;
         const timeout = timeoutMs(definition);
         run.status = "timeout";
         run.finishedAt = now;
@@ -2701,23 +2931,27 @@ ${id}`;
         if (!await this.writeRunIf(run, ["running"])) continue;
         alerts.push(...await this.finishRun(definition, run, now));
       } catch (e) {
-        this.onError(e, `checking ${run.job}`);
+        this.onError(e, `checking ${listed.job}`);
       }
     }
     const jobs = [];
     const retries = { spentMs: 0 };
-    for (const stored of await this.store.listJobs()) {
+    for (const stored of await this.storedJobs()) {
       try {
+        this.evaluable(stored);
         const recent = await this.store.listRuns(stored.name, BASELINE_WINDOW);
         let nextExpectedAt = null;
-        const { state, result: drafts } = await this.updateState(stored.name, (previous) => {
+        const { state, result: held } = await this.updateState(stored.name, (previous) => {
           const evaluation = onCheck(stored.definition, stored, recent[0] ?? null, previous, now);
           nextExpectedAt = evaluation.nextExpectedAt;
           const settled = applySilence(previous, evaluation, now);
-          return { state: settled.state, result: settled.alerts };
+          const released = releaseSending(settled.state, this.now());
+          const out = this.outbox({ state: released.state, alerts: settled.alerts }, stored.definition, now);
+          return { state: out.state, result: { alerts: out.result.alerts, dropped: released.dropped + out.result.dropped } };
         });
+        this.reportDropped(stored.name, held.dropped);
         alerts.push(...await this.retryUndelivered(stored.name, state, now, retries));
-        alerts.push(...await this.dispatch(drafts, stored.definition, now));
+        alerts.push(...await this.dispatch(stored.name, held.alerts, now));
         jobs.push(summarize(stored, recent, state, nextExpectedAt, now));
       } catch (e) {
         this.onError(e, `checking ${stored.name}`);
@@ -2740,6 +2974,7 @@ ${id}`;
     let recent = [];
     try {
       recent = await this.store.listRuns(stored.name, Math.max(runs, BASELINE_WINDOW));
+      this.evaluable(stored);
       const state = await this.readState(stored.name);
       const { nextExpectedAt } = onCheck(stored.definition, stored, recent[0] ?? null, state, now);
       return { job: summarize(stored, recent, state, nextExpectedAt, now), runs: recent.slice(0, runs) };
@@ -2761,19 +2996,20 @@ ${id}`;
   /** Every job's summary with its newest `limit` runs, read together. What the dashboard shows. */
   async jobsWithRuns(limit = 20) {
     await this.ensureReady();
-    for (const definition of this.definitions.values()) await this.sync(definition);
+    const jobs = await this.storedJobs();
     const now = this.now();
     const out = [];
-    for (const stored of await this.store.listJobs()) out.push(await this.snapshot(stored, now, clampLimit(limit, 20, 0)));
+    for (const stored of jobs) out.push(await this.snapshot(stored, now, clampLimit(limit, 20, 0)));
     return out;
   }
+  /** A job's summary, or null for one the store does not have. One declared here and forgotten elsewhere is written again, as storedJobs() does. */
   async jobSummary(name) {
     await this.ensureReady();
     const definition = this.definitions.get(name);
-    if (definition) await this.sync(definition);
+    if (definition) await this.sync(definition, true);
     const stored = await this.store.getJob(name);
     if (!stored) return null;
-    return (await this.snapshot(stored, this.now(), 0)).job;
+    return (await this.snapshot(this.readJob(stored), this.now(), 0)).job;
   }
   /** A job's runs, newest first. `limit` is a whole number from 1 to 500. */
   async runs(name, limit = 50) {
@@ -2784,11 +3020,14 @@ ${id}`;
     await this.ensureReady();
     return this.store.getRun(id);
   }
-  /** Stop alerts for a job for a while. State keeps updating underneath. */
+  /**
+   * Stop alerts for a job for a while. State keeps updating underneath. The
+   * end is a whole millisecond, held at 2^53 - 1 (see silenceEnd).
+   */
   async silence(name, duration) {
     const ms = parseDuration(duration, "silence duration");
     return this.patchState(name, (state) => {
-      state.silencedUntil = this.now() + ms;
+      state.silencedUntil = silenceEnd(this.now(), ms);
     });
   }
   async unsilence(name) {
@@ -2806,28 +3045,38 @@ ${id}`;
     });
     return state;
   }
-  /** Remove a job and its runs from the store. A job still declared in code comes back on its next run. */
+  /**
+   * Remove a job and its runs from the store. A job still declared in code
+   * comes back: here on its next run, and in any other process that declares
+   * it on its next run there, or at that process's next check or dashboard read.
+   */
   async forget(name) {
     await this.ensureReady();
     this.definitions.delete(name);
     this.synced.delete(name);
     await this.store.deleteJob(name);
   }
-  /** The dashboard and JSON API as fetch-style handlers. See createRoutes(). */
+  /**
+   * The dashboard and JSON API as fetch-style handlers: the one way to mount
+   * them. A Next.js app exports them from app/cronwatch/[[...path]]/route.ts:
+   *
+   *   export const { GET, POST, DELETE } = cw.routes();
+   */
   routes(options) {
-    return createRoutes(this, options);
+    return buildRoutes(this, options);
   }
   /**
    * Check on an interval, for long-running servers. Default every minute.
    * Not for serverless functions or Cloudflare Workers, where nothing runs
-   * between requests: call check() from a cron there instead.
+   * between requests: call check() from a cron there instead. (A job's
+   * start() opens a run; this starts the checks.)
    */
-  start(every = "1m") {
+  startChecking(every = "1m") {
     if (this.timer) return;
     const ms = Math.min(TIMER_MAX_MS, Math.max(5e3, parseDuration(every, "check interval")));
     if (this.deferDelivery && !this.warnedDeferredStart) {
       this.warnedDeferredStart = true;
-      console.warn('[cronwatch] start() was called with deliver: "check", so these checks send no alerts. Another process must run checks with deliver: "now" (the default) to send them.');
+      console.warn('[cronwatch] startChecking() was called with deliver: "check", so these checks send no alerts. Another process must run checks with deliver: "now" (the default) to send them.');
     }
     const tick = () => this.check().catch((e) => this.onError(e, "check"));
     this.timer = setInterval(tick, ms);
@@ -2838,38 +3087,52 @@ ${id}`;
     }, 1e3);
     if (typeof this.firstTick === "object" && "unref" in this.firstTick) this.firstTick.unref();
   }
+  /**
+   * startChecking(), under its former name.
+   * @deprecated Renamed `startChecking`, since a job's `start()` opens a run.
+   * This name still works through 1.x and goes in 2.0.
+   */
+  start(every = "1m") {
+    this.startChecking(every);
+  }
+  /** Stop the checks startChecking() began. */
   stop() {
     if (this.timer) clearInterval(this.timer);
     if (this.firstTick) clearTimeout(this.firstTick);
     this.timer = null;
     this.firstTick = null;
   }
+  /**
+   * Stop the interval, wait for a check already under way (bounded by its
+   * own channel, triage and retry timeouts; what it throws was reported to
+   * whoever started it), then close the store, so that check neither writes
+   * after the store is closed nor loses the alerts it would queue.
+   */
   async close() {
     this.stop();
+    if (this.checking) await this.checking.catch(() => {
+    });
     if (this.store.close) await this.store.close();
   }
   /**
-   * 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.
+   * Triage and send each alert the outbox holds (see outbox()). The state,
+   * with the alerts in it, was saved before this, so a slow channel holds up
+   * nothing else; afterwards only the delivery fields are written back, onto
+   * a fresh read of the state, and the alerts leave `sending`. Triage is made
+   * here, never stored with the held alert: the write that opens a condition
+   * cannot wait for it, and a retry triages an alert that has none. With
+   * deliver: "check" the alerts were queued for a check elsewhere instead.
    */
-  async dispatch(drafts, definition, now) {
-    if (drafts.length === 0) return [];
-    const composed = [];
+  async dispatch(name, alerts, now) {
+    if (alerts.length === 0 || this.deferDelivery) return alerts;
     const delivered = [];
     const failed = [];
-    for (const draft of drafts) {
-      const alert = composeAlert(draft, definition, now);
-      if (this.deferDelivery) {
-        failed.push(alert);
-      } else {
-        if (this.triage && alert.type !== "recovered") await this.addTriage(alert, TRIAGE_TIMEOUT_MS);
-        (await this.deliver(alert) ? delivered : failed).push(alert);
-      }
-      composed.push(alert);
+    for (const alert of alerts) {
+      if (this.triage && alert.type !== "recovered") await this.addTriage(alert, TRIAGE_TIMEOUT_MS);
+      (await this.deliver(alert) ? delivered : failed).push(alert);
     }
-    await this.recordDelivery(definition.name, delivered, failed, [], now);
-    return composed;
+    await this.recordDelivery(name, delivered, failed, [], now);
+    return alerts;
   }
   /**
    * Send the alerts that no channel accepted last time, once each, oldest
@@ -2898,28 +3161,18 @@ ${id}`;
   }
   /**
    * 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.
+   * next check, taking them all out of `sending` (recordSent). A failed alert
+   * replaces its stored copy, so a triage made on this attempt is kept.
+   * lastAlertAt moves only on a delivery. When this write fails, alerts
+   * still in `sending` are retried once their lease runs out.
    */
   async recordDelivery(name, delivered, failed, dropped, now) {
     try {
       const { result: trimmed } = await this.updateState(name, (previous) => {
-        const state = normalizeState(previous, name);
-        const done = new Set([...delivered, ...dropped].map(alertKey));
-        const retried = new Map(failed.map((a) => [alertKey(a), a]));
-        const kept = state.undelivered.filter((a) => !done.has(alertKey(a))).map((a) => retried.get(alertKey(a)) ?? a);
-        const known = new Set(kept.map(alertKey));
-        kept.push(...failed.filter((a) => !known.has(alertKey(a))));
-        state.undelivered = kept.slice(-MAX_UNDELIVERED);
-        if (delivered.length > 0) state.lastAlertAt = now;
-        return { state, result: Math.max(0, kept.length - MAX_UNDELIVERED) };
+        const { state, dropped: letGo } = recordSent(normalizeState(previous, name), delivered, failed, dropped, now);
+        return { state, result: letGo };
       });
-      if (trimmed > 0) {
-        this.onError(
-          new Error(`${trimmed} undelivered alert${trimmed === 1 ? "" : "s"} for ${name} dropped: only the newest ${MAX_UNDELIVERED} are kept for retry`),
-          `alert queue for ${name}`
-        );
-      }
+      this.reportDropped(name, trimmed);
     } catch (e) {
       this.onError(e, `recording alert delivery for ${name}`);
     }
@@ -2955,9 +3208,10 @@ ${id}`;
   }
 };
 var RESERVED_RUN_ID_PREFIX = "pgcron:";
+var MAX_RUN_ID = 200;
 function checkRunId(job, id, method) {
-  if (typeof id !== "string" || id.length === 0 || id.length > 200) {
-    throw new Error(`job "${job}": ${method}() needs a run id of 1 to 200 characters (got ${typeof id === "string" ? `${id.length} characters` : typeof id})`);
+  if (typeof id !== "string" || id.length === 0 || id.length > MAX_RUN_ID) {
+    throw new Error(`job "${job}": ${method}() needs a run id of 1 to ${MAX_RUN_ID} characters (got ${typeof id === "string" ? `${id.length} characters` : typeof id})`);
   }
   if (id.includes("\0")) throw new Error(`job "${job}": ${method}() cannot take a run id containing a NUL character`);
   if (id.startsWith(RESERVED_RUN_ID_PREFIX)) {
@@ -3018,12 +3272,13 @@ function custom(name, send) {
     await send(alert);
   } };
 }
+var CronWatch = Cronwatch;
 
 // src/index.ts
 function cronwatch(options = {}) {
-  return new CronWatch(options);
+  return new Cronwatch(options);
 }
 
-export { CronWatch, composeAlert, consoleChannel, createRoutes, cronwatch, custom, formatDuration, memory, nextFire, parseDuration, parseSchedule };
+export { CronWatch, Cronwatch, VERSION, composeAlert, consoleChannel, createRoutes, cronwatch, custom, formatDuration, memory, nextFire, parseDuration, parseSchedule };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map