@worca/app 1.3.0 → 1.4.0-rc.1

package/src/shared/graph/validate.mjs

@@ -1,13 +1,13 @@
 // src/shared/graph/validate.mjs
-// THE authority on v2 graph legality (base spec §2, V1-V21; V22 is RETIRED —
-// subsumed by the restored V7 — and its number stays reserved so V-rule
-// references remain stable). Server save (422), plugin import, the composer's
+// THE authority on v2 graph legality (base spec §2, V1-V22; V22 (script config)
+// reuses the number the retired single-wire rule freed). Server save (422), plugin import, the composer's
 // live report, the run-time check and the seed drift guard all come through
 // here, so it is pure, never throws on a malformed template, and every lookup
 // guards: a dangling endpoint or an unknown key is an issue to COLLECT.
-import { KINDS, NODE_ID_RE, LIMITS } from './constants.mjs';
+import { KINDS, KEYED_KINDS, NODE_ID_RE, LIMITS, PARAMS_PORT } from './constants.mjs';
 import { portsOf, findPort, resolveOrOutType } from './ports.mjs';
 import { classifyLoops } from './loops.mjs';
+import { paramValueError, mockErrors, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, pythonMissingSentence, wirableParams, WIRABLE_PARAM_TYPES } from './script-meta.mjs';
 
 const ARITY_SET = new Set(['and', 'or', 'combine']);
 const IN_PORT_RE = /^in\d+$/;
@@ -19,6 +19,7 @@ const AWAIT_PORT_ID = 'await';
  *  on a flow card. Unknown keys are PRESERVED and ignored, never stripped. */
 const KNOWN_CONFIG = {
   agent: new Set(['model', 'effort', 'fanOut', 'askQuestions', 'awaitAll', 'subagentModel']),
+  script: new Set(['params', 'ports', 'timeoutMs', 'awaitAll', 'mock', 'paramsPort']),
   task: new Set(['planStoreSeed']),
   and: new Set(['arity']),
   or: new Set(['arity']),
@@ -32,6 +33,8 @@ const KNOWN_WIRE_CONFIG = new Set(['maxCycles']);
  *  (workflows.mjs#setWorkflowNodeDefaults, ui/server.mjs template save). A
  *  strict subset of KNOWN_CONFIG.agent: awaitAll is TOPOLOGY, not a tunable. */
 export const AGENT_TUNABLES = ['model', 'effort', 'fanOut', 'askQuestions', 'subagentModel'];
+/** The per-node SCRIPT tunables (P2's per-project overlays); unused by v1 writers. */
+export const SCRIPT_TUNABLES = ['params', 'timeoutMs'];
 
 const isObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
 
@@ -184,8 +187,8 @@ export const RULES = [
     for (const n of nodes) {
       if (!KINDS.includes(n.kind)) {           // KINDS is a frozen ARRAY (P1 constants)
         add(`node '${n.id}' has unknown kind ${JSON.stringify(n.kind)} — expected one of ${[...KINDS].join(', ')}`, { nodeId: n.id });
-      } else if (n.kind === 'agent' && !n.key) add(`agent node '${n.id}' must declare a key`, { nodeId: n.id });
-      else if (n.kind !== 'agent' && n.key !== undefined) {
+      } else if (KEYED_KINDS.includes(n.kind) && !n.key) add(`${n.kind} node '${n.id}' must declare a key`, { nodeId: n.id });
+      else if (!KEYED_KINDS.includes(n.kind) && n.key !== undefined) {
         add(`node '${n.id}' of kind '${n.kind}' must not declare a key`, { nodeId: n.id });
       }
     }
@@ -193,12 +196,25 @@ export const RULES = [
 
   { code: 'V4', level: 'E', check({ nodes, portsFor }, add) {
     for (const n of nodes) {
-      if (n.kind !== 'agent' || !n.key) continue;                       // a missing key is V3's
+      if (!KEYED_KINDS.includes(n.kind) || !n.key) continue;             // a missing key is V3's
       const p = portsFor(n.id);
-      if (!p.known) add(`unknown agent "${n.key}" — no such key in the registry`, { nodeId: n.id });
-      else if (!p.ported) add(`agent "${n.key}" has no v2 ports — port its sidecar to metaVersion 2`, { nodeId: n.id });
+      const what = n.kind;
+      if (!p.known) add(`unknown ${what} "${n.key}" — no such key in the registry`, { nodeId: n.id });
+      else if (!p.ported && p.meta?.configPortsMissing) {
+        add(`script "${n.key}" takes its ports per card — add them in the inspector`, { nodeId: n.id, incomplete: true });
+      } else if (!p.ported && p.meta?.configPortsInvalid) {
+        add(`script "${n.key}" has invalid ports in its config — fix them in the inspector`, { nodeId: n.id });
+      } else if (!p.ported) add(`agent "${n.key}" has no v2 ports — port its sidecar to metaVersion 2`, { nodeId: n.id });
       else if (p.meta?.placeable === false) {
-        add(`agent "${n.key}" declares placeable: false and cannot be a graph node`, { nodeId: n.id });
+        add(`${what} "${n.key}" declares placeable: false and cannot be a graph node`, { nodeId: n.id });
+      } else if (p.meta?.runtime === 'python' && p.meta?.runtimeMissing) {
+        // Workbench §7 / W17: GET /api/scripts stamps `runtimeMissing` on a python
+        // meta when THIS host's probe failed, so the composer paints the card red
+        // the moment it is placed. The registry itself never carries the flag (the
+        // loader is synchronous, the probe is not), so a saved graph and a run are
+        // gated by the run preflight, which says the same sentence at the right
+        // moment. Listed always, unplaceable with a reason.
+        add(pythonMissingSentence(n.key), { nodeId: n.id });
       }
     }
   } },
@@ -263,10 +279,10 @@ export const RULES = [
 
   { code: 'V9', level: 'E', check({ nodes, metaOf, inputsOf, isWired, isLoopInput }, add) {
     for (const n of nodes) {
-      // AGENT inputs only. P1 marks the gate `inK` ports and End's `result`
+      // KEYED inputs only. P1 marks the gate `inK` ports and End's `result`
       // `required: true`, and V12/V21 already own them with a card-specific
       // sentence — without this guard one unwired `n_and.in2` reports TWICE.
-      if (n.kind !== 'agent' || !metaOf(n.id)) continue;               // V3/V4 own an unresolved node
+      if (!KEYED_KINDS.includes(n.kind) || !metaOf(n.id)) continue;   // V3/V4 own an unresolved node
       for (const inp of inputsOf(n.id)) {
         if (!inp?.required || inp.loop || isLoopInput(n.id, inp.id)) continue;
         // `incomplete`: the graph is UNFINISHED here, not wrong — the composer shows
@@ -403,7 +419,7 @@ export const RULES = [
 
   { code: 'V16', level: 'W', check({ nodes, metaOf, inputsOf, isWired, isLoopInput }, add) {
     for (const n of nodes) {
-      if (n.kind !== 'agent' || !n.config?.awaitAll || !metaOf(n.id)) continue;
+      if (!KEYED_KINDS.includes(n.kind) || !n.config?.awaitAll || !metaOf(n.id)) continue;
       const wired = inputsOf(n.id).filter((inp) => !isLoopInput(n.id, inp.id) && isWired(n.id, inp.id));
       if (wired.length < 2) {
         add(`node '${n.id}' sets awaitAll but has ${wired.length} wired non-loop input(s) — the barrier is a no-op`,
@@ -434,7 +450,7 @@ export const RULES = [
   // always source, so without it every double-loop seed would warn permanently.
   { code: 'V18', level: 'W', check({ nodes, nodeById, metaOf, inputsOf, inboundOf, outputPort, isLoopInput }, add) {
     for (const n of nodes) {
-      if (n.kind !== 'agent' || n.config?.awaitAll || !metaOf(n.id)) continue;
+      if (!KEYED_KINDS.includes(n.kind) || n.config?.awaitAll || !metaOf(n.id)) continue;
       let paired = 0;
       for (const inp of inputsOf(n.id)) {
         if (inp.id === AWAIT_PORT_ID || inp.synthetic) continue;                    // (c)
@@ -447,7 +463,7 @@ export const RULES = [
         paired += 1;
       }
       if (paired >= 2) {
-        add(`agent node '${n.id}' has ${paired} always-sourced payload inputs without awaitAll — `
+        add(`${n.kind} node '${n.id}' has ${paired} always-sourced payload inputs without awaitAll — `
           + 'it may double-fire on re-runs (enable Await-all or insert an AND card)', { nodeId: n.id });
       }
     }
@@ -463,7 +479,7 @@ export const RULES = [
       const target = nodeById.get(w.to.node);
       if ((target.kind === 'and' || target.kind === 'or') && IN_PORT_RE.test(w.to.port)) continue;
       if (target.kind === 'end' && w.to.port === 'result') continue;
-      if (target.kind === 'agent' && w.to.port === AWAIT_PORT_ID) continue;
+      if (KEYED_KINDS.includes(target.kind) && w.to.port === AWAIT_PORT_ID) continue;
       add(`blocking output '${w.from.node}.${w.from.port}' is wired into '${w.to.node}.${w.to.port}', `
         + 'which is not a loop input', { wireId: w.id });
     }
@@ -490,4 +506,61 @@ export const RULES = [
       if (!isWired(e.id, 'result')) add(`end node '${e.id}' input 'result' must be wired`, { nodeId: e.id, incomplete: true });
     }
   } },
+
+  // Script config (spec §9.1 V22): params against the sidecar's declarations,
+  // `ports` only where the sidecar says "config" (a MISSING or unreadable config
+  // is V4's), `mock` against the declared non-void outputs, `timeoutMs` an integer
+  // within [1 s, 24 h]. `incomplete` marks work-to-do (a required param nobody set yet).
+  // `paramsPort` only where it takes effect; a WIRED params port defers a required wirable param to the runner.
+  { code: 'V22', level: 'E', check({ nodes, portsFor, isWired }, add) {
+    for (const n of nodes) {
+      if (n.kind !== 'script' || !n.key) continue;
+      const p = portsFor(n.id);
+      if (!p.known) continue;                                            // V4 owns it
+      const meta = p.meta || {};
+      const cfg = isObject(n.config) ? n.config : {};
+      const declared = Array.isArray(meta.params) ? meta.params : [];
+      const byId = new Map(declared.map((d) => [d.id, d]));
+      if (cfg.params !== undefined && !isObject(cfg.params)) add(`script node '${n.id}' config.params must be an object`, { nodeId: n.id });
+      const values = isObject(cfg.params) ? cfg.params : {};
+      for (const [id, value] of Object.entries(values)) {
+        const d = byId.get(id);
+        if (!d) {
+          add(`script node '${n.id}' sets unknown param '${id}' — script "${n.key}" declares ${declared.length ? declared.map((x) => x.id).join(', ') : 'no params'}`, { nodeId: n.id });
+          continue;
+        }
+        const bad = paramValueError(d, value);
+        if (bad) add(`script node '${n.id}' param '${id}': ${bad}`, { nodeId: n.id });
+      }
+      // `p.meta.inputs` are the RESOLVED inputs — the engine port is already among them, so it is
+      // looked up there instead of re-asking hasParamsPort (which would read it as a collision).
+      const enginePort = p.ported && p.inputs.some((x) => x && x.id === PARAMS_PORT.id && x.engine === 'params');
+      if (cfg.paramsPort !== undefined && typeof cfg.paramsPort !== 'boolean') {
+        add(`script node '${n.id}' config.paramsPort must be true or false`, { nodeId: n.id });
+      } else if (cfg.paramsPort === true && p.ported && !enginePort) {
+        add(wirableParams(meta).length
+          ? `script node '${n.id}' enables paramsPort but script "${n.key}" already declares an input named '${PARAMS_PORT.id}'`
+          : `script node '${n.id}' enables paramsPort but script "${n.key}" declares no param a wire can set`, { nodeId: n.id });
+      }
+      const wireDelivers = enginePort && isWired(n.id, PARAMS_PORT.id);
+      for (const d of declared) {
+        if (wireDelivers && WIRABLE_PARAM_TYPES.includes(d.type)) continue;   // the wire may deliver it; the runner refuses the execution if it does not
+        if (d.required && values[d.id] === undefined && d.default === undefined) {
+          add(`script node '${n.id}' is missing required param '${d.id}'`, { nodeId: n.id, incomplete: true });
+        }
+      }
+      if (meta.ports !== 'config' && cfg.ports !== undefined) {
+        add(`script node '${n.id}' carries config.ports but script "${n.key}" declares its ports in its sidecar`, { nodeId: n.id });
+      }
+      if (cfg.mock !== undefined) {
+        for (const e of mockErrors(cfg.mock, p.ported ? p.outputs : [])) add(`script node '${n.id}' config.mock: ${e}`, { nodeId: n.id });
+      }
+      if (cfg.timeoutMs !== undefined && (!Number.isInteger(cfg.timeoutMs) || cfg.timeoutMs < MIN_TIMEOUT_MS)) {
+        add(`script node '${n.id}' timeoutMs must be an integer >= ${MIN_TIMEOUT_MS} ms (got ${JSON.stringify(cfg.timeoutMs)})`, { nodeId: n.id });
+      } else if (cfg.timeoutMs > MAX_TIMEOUT_MS) {
+        // v4 T3: a timer delay past 2^31-1 ms fires after ONE millisecond — the card would be killed at once.
+        add(`script node '${n.id}' timeoutMs must be at most ${MAX_TIMEOUT_MS} ms (24 h) (got ${cfg.timeoutMs})`, { nodeId: n.id });
+      }
+    }
+  } },
 ];

package/src/shared/human-estimate.mjs

@@ -0,0 +1,100 @@
+// Human-hours estimator (money-saved design §4). PURE: no I/O, no builtin imports — shared by
+// the orchestrator (per step), the backfill (per run) and, later, the browser. Every rule
+// reads EVIDENCE of what a step produced; no agent key is ever consulted.
+
+export const HUMAN_ESTIMATE_DEFAULTS = Object.freeze({
+  codeBase: 0.5, codeFileH: 0.1, codeExp: 0.85, codeDiv: 25,        // 0.5 + 0.1·files + lines^0.85/25
+  writeBase: 0.25, writeWph: 500, writeCapWords: 6000,              // 0.25 + min(words,6000)/500
+  reviseFactor: 0.35, reviseDecay: 0.5,                             // write · 0.35 · 0.5^(cycle−1)
+  jsonBase: 0.25, jsonItemH: 0.05,                                  // 0.25 + 0.05·items
+  readLph: 300, readWph: 3000, rereadFactor: 0.3,                   // (lines/300 + words/3000) · (cycle>1 ? 0.3 : 1)
+});
+
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+
+/** Round hours to 2 dp (the unit the rate multiplies). */
+export const roundHours = (h) => Math.round(((finite(h) ? h : 0) + Number.EPSILON) * 100) / 100;
+
+/** Merge user overrides over the defaults: only finite, non-negative numbers for KNOWN keys apply. */
+export function resolveConstants(overrides) {
+  if (!overrides || typeof overrides !== 'object') return HUMAN_ESTIMATE_DEFAULTS;
+  const out = { ...HUMAN_ESTIMATE_DEFAULTS };
+  for (const key of Object.keys(HUMAN_ESTIMATE_DEFAULTS)) {
+    const v = overrides[key];
+    if (finite(v) && v >= 0) out[key] = v;
+  }
+  return out;
+}
+
+const FENCE_RE = /```[\s\S]*?```/g;
+
+/** Words outside fenced code blocks. Plans embed whole files; a human would not have typed those. */
+export function proseWords(text) {
+  if (text == null) return 0;
+  return String(text).replace(FENCE_RE, ' ').split(/\s+/).filter(Boolean).length;
+}
+
+/** Array length, else the first array-valued member's length, else the key count; 0 for scalars. */
+export function jsonItems(value) {
+  if (Array.isArray(value)) return value.length;
+  if (!value || typeof value !== 'object') return 0;
+  const arr = Object.values(value).find(Array.isArray);
+  return arr ? arr.length : Object.keys(value).length;
+}
+
+/**
+ * @param {object} evidence  see the module header in human-evidence.mjs for the collector
+ * @param {object} [k]       resolved constants
+ * @returns {{hours:number, signals:{code:number,write:number,revise:number,json:number,read:number}, method:'heuristic'|'override'|'none'}}
+ */
+export function estimateStepHours(evidence, k = HUMAN_ESTIMATE_DEFAULTS) {
+  const signals = { code: 0, write: 0, revise: 0, json: 0, read: 0 };
+  const e = evidence || {};
+  const effort = e.agent?.humanEffort;
+  if (effort && finite(effort.hours) && effort.hours >= 0) {
+    return { hours: roundHours(effort.hours), signals, method: 'override' };
+  }
+  if (e.nodeKind !== 'agent' || !e.agent) return { hours: 0, signals, method: 'none' };
+  const cycle = Number.isInteger(e.cycle) && e.cycle > 0 ? e.cycle : 1;
+
+  // 3. code delta
+  if (e.code) {
+    const lines = (e.code.insertions | 0) + (e.code.deletions | 0);
+    if (lines > 0) signals.code = k.codeBase + k.codeFileH * (e.code.files | 0) + Math.pow(lines, k.codeExp) / k.codeDiv;
+  }
+  // 4. prose: the LARGEST md output only (a plan plus its review note is one activity)
+  const mds = (e.outputs || []).filter((o) => o && o.type === 'md');
+  if (mds.length) {
+    const top = mds.reduce((a, b) => ((b.words | 0) > (a.words | 0) ? b : a));
+    const w = k.writeBase + Math.min(top.words | 0, k.writeCapWords) / k.writeWph;
+    if (top.revision) signals.revise = w * k.reviseFactor * Math.pow(k.reviseDecay, cycle - 1);
+    else signals.write = w;
+  }
+  // 5. structured outputs
+  for (const o of e.outputs || []) {
+    if (o && o.type === 'json') signals.json += k.jsonBase + k.jsonItemH * (o.items | 0);
+  }
+  // 6. reading (verifiers only)
+  if (e.agent.runnerType === 'verifier' && e.reads) {
+    const base = (e.reads.diffLines | 0) / k.readLph + (e.reads.words | 0) / k.readWph;
+    signals.read = base * (cycle > 1 ? k.rereadFactor : 1);
+  }
+  // 7. total, scaled
+  const factor = effort && finite(effort.factor) && effort.factor >= 0 ? effort.factor : 1;
+  for (const s of Object.keys(signals)) signals[s] = roundHours(signals[s] * factor);
+  const hours = roundHours(Object.values(signals).reduce((a, b) => a + b, 0));
+  return { hours, signals, method: 'heuristic' };
+}
+
+/** Σ finite step.humanHours, 2 dp. Mirrors run-harness sumStepCosts. */
+export function sumStepHours(steps) {
+  let sum = 0;
+  for (const s of Array.isArray(steps) ? steps : []) if (finite(s?.humanHours)) sum += s.humanHours;
+  return roundHours(sum);
+}
+
+/** hours × rate − spent, 2 dp; negative is a real (honest) outcome. */
+export function savedUsd(hours, rateUsd, spentUsd) {
+  const v = (finite(hours) ? hours : 0) * (finite(rateUsd) ? rateUsd : 0) - (finite(spentUsd) ? spentUsd : 0);
+  return Math.round((v + Number.EPSILON) * 100) / 100;
+}

package/src/shared/schedule/recurrence.mjs

@@ -0,0 +1,353 @@
+// src/shared/schedule/recurrence.mjs
+// Recurrence rules for scheduled runs — ONE source for the server, the CLI and the
+// browser (served under /src/shared, like the graph model). Pure: no node: imports,
+// no Date.now() — every function takes its instant.
+//
+// A rule is wall-clock time in an IANA timezone, never a UTC instant: "02:00 every
+// night" must stay 02:00 across daylight-saving changes.
+//
+//   { freq: 'daily'|'weekly'|'monthly', interval: 1..,
+//     weekdays: ['mo',..]            (weekly)
+//     monthDay: 1..31 | 'last'       (monthly)
+//     time: 'HH:MM', tz: 'Europe/Berlin',
+//     anchor: 'YYYY-MM-DD'           (local date the interval counts from)
+//     end: { type:'never' } | { type:'until', until:'YYYY-MM-DD' } | { type:'count', count:n } }
+
+export const WEEKDAYS = ['mo', 'tu', 'we', 'th', 'fr', 'sa', 'su'];
+const WD_LONG = { mo: 'Monday', tu: 'Tuesday', we: 'Wednesday', th: 'Thursday', fr: 'Friday', sa: 'Saturday', su: 'Sunday' };
+const WD_SHORT = { mo: 'Mon', tu: 'Tue', we: 'Wed', th: 'Thu', fr: 'Fri', sa: 'Sat', su: 'Sun' };
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+export const OVERLAP_POLICIES = ['skip', 'start', 'queue'];
+export const MISSED_POLICIES = ['run', 'skip'];
+const TIME_RE = /^([01]?\d|2[0-3]):([0-5]\d)$/;
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const MAX_SCAN_DAYS = 366 * 12;
+
+/** True when `tz` is a timezone Intl accepts. */
+export function isValidTimeZone(tz) {
+  if (typeof tz !== 'string' || !tz) return false;
+  try { new Intl.DateTimeFormat('en-US', { timeZone: tz }); return true; } catch { return false; }
+}
+
+const _fmtCache = new Map();
+function partsFormatter(tz) {
+  let f = _fmtCache.get(tz);
+  if (!f) {
+    f = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit',
+      hour: '2-digit', minute: '2-digit', second: '2-digit',
+    });
+    _fmtCache.set(tz, f);
+  }
+  return f;
+}
+
+/** Wall-clock parts of instant `ms` in `tz`: { y, m (1-12), d, hh, mm, ss }. */
+export function zonedParts(ms, tz) {
+  const out = {};
+  for (const p of partsFormatter(tz).formatToParts(new Date(ms))) {
+    if (p.type !== 'literal') out[p.type] = Number(p.value);
+  }
+  return { y: out.year, m: out.month, d: out.day, hh: out.hour % 24, mm: out.minute, ss: out.second };
+}
+
+/** Offset (ms) of `tz` from UTC at instant `ms` (positive east of Greenwich). */
+function tzOffsetMs(ms, tz) {
+  const p = zonedParts(ms, tz);
+  return Date.UTC(p.y, p.m - 1, p.d, p.hh, p.mm, p.ss) - Math.floor(ms / 1000) * 1000;
+}
+
+/**
+ * The UTC instant of a wall-clock time in `tz`. A time that does not exist (spring
+ * forward) moves FORWARD past the gap; a time that occurs twice (autumn) resolves to
+ * the FIRST occurrence, so a rule fires once.
+ */
+export function zonedToUtc({ y, m, d, hh, mm }, tz) {
+  const wall = Date.UTC(y, m - 1, d, hh, mm, 0);
+  // The offsets a day either side of the wall time cover every transition.
+  const offs = [...new Set([tzOffsetMs(wall - 86400000, tz), tzOffsetMs(wall + 86400000, tz), tzOffsetMs(wall, tz)])];
+  const hits = [];
+  for (const off of offs) {
+    const t = wall - off;
+    const p = zonedParts(t, tz);
+    if (p.y === y && p.m === m && p.d === d && p.hh === hh && p.mm === mm) hits.push(t);
+  }
+  if (hits.length) return Math.min(...hits);
+  // Non-existent local time: read it with the offset in force BEFORE the jump, which
+  // lands the same distance past the gap.
+  return wall - Math.min(...offs);
+}
+
+function daysInMonth(y, m) { return new Date(Date.UTC(y, m, 0)).getUTCDate(); }
+function dowIndex(y, m, d) { return (new Date(Date.UTC(y, m - 1, d)).getUTCDay() + 6) % 7; } // Monday = 0
+function weekdayKey(y, m, d) { return WEEKDAYS[dowIndex(y, m, d)]; }
+function civilDayNumber(y, m, d) { return Math.floor(Date.UTC(y, m - 1, d) / 86400000); }
+function parseDate(s) { const r = DATE_RE.exec(String(s || '')); return r ? { y: +r[1], m: +r[2], d: +r[3] } : null; }
+function pad(n) { return String(n).padStart(2, '0'); }
+/** 'YYYY-MM-DD' of civil parts. */
+export function civilDate({ y, m, d }) { return `${y}-${pad(m)}-${pad(d)}`; }
+/** Today's local date ('YYYY-MM-DD') in `tz` at instant `ms`. */
+export function localDate(ms, tz) { return civilDate(zonedParts(ms, tz)); }
+
+/**
+ * Validate + normalise a rule. Returns { ok:true, rule } or { ok:false, error }.
+ * `todayLocal` ('YYYY-MM-DD') seeds a missing anchor.
+ */
+export function normalizeRule(input, { todayLocal = null } = {}) {
+  const r = input && typeof input === 'object' && !Array.isArray(input) ? input : null;
+  if (!r) return { ok: false, error: 'repeat.rule must be an object' };
+  const freq = String(r.freq || '').toLowerCase();
+  if (!['daily', 'weekly', 'monthly'].includes(freq)) return { ok: false, error: 'rule.freq must be daily, weekly or monthly' };
+  const interval = r.interval == null ? 1 : Number(r.interval);
+  if (!Number.isInteger(interval) || interval < 1 || interval > 365) return { ok: false, error: 'rule.interval must be a whole number from 1 to 365' };
+  const tm = TIME_RE.exec(String(r.time || ''));
+  if (!tm) return { ok: false, error: 'rule.time must be HH:MM (24-hour)' };
+  const time = `${pad(+tm[1])}:${tm[2]}`;
+  if (!isValidTimeZone(r.tz)) return { ok: false, error: `rule.tz is not a known timezone: ${r.tz ?? '(missing)'}` };
+  const out = { freq, interval, time, tz: r.tz };
+  if (freq === 'weekly') {
+    const days = Array.isArray(r.weekdays) ? [...new Set(r.weekdays.map((x) => String(x).toLowerCase().slice(0, 2)))] : [];
+    if (days.some((x) => !WEEKDAYS.includes(x))) return { ok: false, error: 'rule.weekdays must use mo tu we th fr sa su' };
+    if (!days.length) return { ok: false, error: 'rule.weekdays needs at least one day' };
+    out.weekdays = WEEKDAYS.filter((x) => days.includes(x));
+  }
+  if (freq === 'monthly') {
+    const md = r.monthDay === 'last' ? 'last' : Number(r.monthDay);
+    if (md !== 'last' && (!Number.isInteger(md) || md < 1 || md > 31)) return { ok: false, error: 'rule.monthDay must be 1-31 or "last"' };
+    out.monthDay = md;
+  }
+  const anchor = parseDate(r.anchor) ? r.anchor : todayLocal;
+  if (!parseDate(anchor)) return { ok: false, error: 'rule.anchor must be YYYY-MM-DD' };
+  out.anchor = anchor;
+  const end = r.end && typeof r.end === 'object' ? r.end : { type: 'never' };
+  const et = String(end.type || 'never');
+  if (et === 'never') out.end = { type: 'never' };
+  else if (et === 'until') {
+    if (!parseDate(end.until)) return { ok: false, error: 'rule.end.until must be YYYY-MM-DD' };
+    out.end = { type: 'until', until: end.until };
+  } else if (et === 'count') {
+    const c = Number(end.count);
+    if (!Number.isInteger(c) || c < 1 || c > 100000) return { ok: false, error: 'rule.end.count must be a whole number of 1 or more' };
+    out.end = { type: 'count', count: c };
+  } else return { ok: false, error: 'rule.end.type must be never, until or count' };
+  return { ok: true, rule: out };
+}
+
+function matchesDate(rule, y, m, d, anchor) {
+  if (rule.freq === 'daily') {
+    const diff = civilDayNumber(y, m, d) - civilDayNumber(anchor.y, anchor.m, anchor.d);
+    return diff >= 0 && diff % rule.interval === 0;
+  }
+  if (rule.freq === 'weekly') {
+    if (!rule.weekdays.includes(weekdayKey(y, m, d))) return false;
+    if (civilDayNumber(y, m, d) < civilDayNumber(anchor.y, anchor.m, anchor.d)) return false;
+    // Week index counted from the Monday of the anchor's week.
+    const monday = (yy, mm2, dd) => civilDayNumber(yy, mm2, dd) - dowIndex(yy, mm2, dd);
+    const diff = (monday(y, m, d) - monday(anchor.y, anchor.m, anchor.d)) / 7;
+    return diff % rule.interval === 0;
+  }
+  // monthly — a day past the month's end clamps to its last day.
+  const months = (y - anchor.y) * 12 + (m - anchor.m);
+  if (months < 0 || months % rule.interval !== 0) return false;
+  const dim = daysInMonth(y, m);
+  const want = rule.monthDay === 'last' ? dim : Math.min(rule.monthDay, dim);
+  return d === want;
+}
+
+/**
+ * The first occurrence strictly after `afterMs`, as a UTC ms instant, or null when
+ * the rule has ended (`firedCount` feeds end.type 'count').
+ */
+export function nextOccurrence(rule, afterMs, { firedCount = 0 } = {}) {
+  if (rule.end?.type === 'count' && firedCount >= rule.end.count) return null;
+  const anchor = parseDate(rule.anchor);
+  const [hh, mm] = rule.time.split(':').map(Number);
+  const until = rule.end?.type === 'until' ? parseDate(rule.end.until) : null;
+  const start = zonedParts(afterMs, rule.tz);
+  let dayNo = civilDayNumber(start.y, start.m, start.d);
+  for (let i = 0; i < MAX_SCAN_DAYS; i++, dayNo++) {
+    const dt = new Date(dayNo * 86400000);
+    const y = dt.getUTCFullYear(), m = dt.getUTCMonth() + 1, d = dt.getUTCDate();
+    if (until && dayNo > civilDayNumber(until.y, until.m, until.d)) return null;
+    if (!matchesDate(rule, y, m, d, anchor)) continue;
+    const t = zonedToUtc({ y, m, d, hh, mm }, rule.tz);
+    if (t > afterMs) return t;
+  }
+  return null;
+}
+
+/** The next `n` occurrences after `afterMs` (for the editor preview). */
+export function previewOccurrences(rule, afterMs, n = 3, { firedCount = 0 } = {}) {
+  const out = [];
+  let t = afterMs, fired = firedCount;
+  while (out.length < n) {
+    const next = nextOccurrence(rule, t, { firedCount: fired });
+    if (next == null) break;
+    out.push(next); t = next; fired++;
+  }
+  return out;
+}
+
+function listJoin(xs) { return xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs[xs.length - 1]}`; }
+function ordinal(n) { const s = ['th', 'st', 'nd', 'rd'], v = n % 100; return n + (s[(v - 20) % 10] || s[v] || s[0]); }
+
+/** The plain-language sentence of a rule: "Every weekday at 02:00". */
+export function describeRule(rule, { withTz = false } = {}) {
+  if (!rule) return '';
+  const n = rule.interval || 1;
+  let head;
+  if (rule.freq === 'daily') head = n === 1 ? 'Every day' : `Every ${n} days`;
+  else if (rule.freq === 'weekly') {
+    const days = rule.weekdays || [];
+    const key = days.join(',');
+    if (key === 'mo,tu,we,th,fr') head = n === 1 ? 'Every weekday' : `Every ${n} weeks on weekdays`;
+    else if (days.length === 7) head = n === 1 ? 'Every day' : `Every ${n} weeks, every day`;
+    else head = `${n === 1 ? 'Every' : `Every ${n} weeks on`} ${listJoin(days.map((d) => WD_LONG[d]))}`;
+  } else {
+    const day = rule.monthDay === 'last' ? 'the last day' : `the ${ordinal(rule.monthDay)}`;
+    head = n === 1 ? `Every month on ${day}` : `Every ${n} months on ${day}`;
+  }
+  let s = `${head} at ${rule.time}`;
+  if (rule.end?.type === 'until') s += `, until ${rule.end.until}`;
+  if (rule.end?.type === 'count') s += `, ${rule.end.count} time${rule.end.count === 1 ? '' : 's'}`;
+  if (withTz) s += ` (${rule.tz})`;
+  return s;
+}
+
+/** "Sat Sep 19, 02:00" in `tz` — the app's hand-rolled local format (app.js fmtResetAtLocal). */
+export function formatInstant(ms, tz, { withYear = false } = {}) {
+  const p = zonedParts(ms, tz);
+  const wd = WD_SHORT[weekdayKey(p.y, p.m, p.d)];
+  return `${wd} ${MONTHS[p.m - 1]} ${p.d}${withYear ? ` ${p.y}` : ''}, ${pad(p.hh)}:${pad(p.mm)}`;
+}
+
+/** "7h 12m" / "3d 4h" / "45s" — the distance to a future instant ('' when past). */
+export function formatCountdown(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return '';
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 48) return `${h}h ${m % 60}m`;
+  return `${Math.floor(h / 24)}d ${h % 24}h`;
+}
+
+/**
+ * Parse the CLI's `--every` shorthand into a rule (tz/anchor filled by the caller):
+ *   "day 03:30" · "3 days 02:00" · "weekdays 02:00" · "weekends 09:00"
+ *   "mon,wed,fri 02:00" · "2 weeks mon 02:00" · "month 1 02:00" · "3 months last 02:00"
+ */
+export function parseEvery(text) {
+  const toks = String(text || '').trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (toks.length < 2) return { ok: false, error: '--every needs a pattern and a time, e.g. "weekdays 02:00"' };
+  const time = toks.pop();
+  if (!TIME_RE.test(time)) return { ok: false, error: `--every: "${time}" is not a HH:MM time` };
+  let interval = 1;
+  if (/^\d+$/.test(toks[0])) interval = Number(toks.shift());
+  if (!toks.length) return { ok: false, error: '--every: missing unit (day, week, month, weekdays, or day names)' };
+  const unit = toks.shift();
+  const days = (s) => s.split(',').map((x) => x.trim().slice(0, 2)).filter(Boolean);
+  if (['day', 'days', 'daily', 'night', 'nightly'].includes(unit) && !toks.length) return { ok: true, rule: { freq: 'daily', interval, time } };
+  if (unit === 'weekdays' && !toks.length) return { ok: true, rule: { freq: 'weekly', interval, weekdays: ['mo', 'tu', 'we', 'th', 'fr'], time } };
+  if (unit === 'weekends' && !toks.length) return { ok: true, rule: { freq: 'weekly', interval, weekdays: ['sa', 'su'], time } };
+  if (['week', 'weeks', 'weekly'].includes(unit)) {
+    if (toks.length !== 1) return { ok: false, error: '--every: name the day(s), e.g. "week mon 02:00" or "2 weeks mon,thu 02:00"' };
+    const d = days(toks[0]);
+    if (!d.length || d.some((x) => !WEEKDAYS.includes(x))) return { ok: false, error: `--every: unknown day in "${toks[0]}"` };
+    return { ok: true, rule: { freq: 'weekly', interval, weekdays: d, time } };
+  }
+  if (['month', 'months', 'monthly'].includes(unit)) {
+    if (toks.length !== 1) return { ok: false, error: '--every: name the day of the month, e.g. "month 1 02:00" or "month last 02:00"' };
+    const md = toks[0] === 'last' ? 'last' : Number(toks[0]);
+    if (md !== 'last' && (!Number.isInteger(md) || md < 1 || md > 31)) return { ok: false, error: `--every: "${toks[0]}" is not a day of the month` };
+    return { ok: true, rule: { freq: 'monthly', interval, monthDay: md, time } };
+  }
+  if (!toks.length) {
+    const d = days(unit);
+    if (d.length && d.every((x) => WEEKDAYS.includes(x))) return { ok: true, rule: { freq: 'weekly', interval, weekdays: d, time } };
+  }
+  return { ok: false, error: `--every: cannot read "${text}" — try "day 03:30", "weekdays 02:00", "mon,thu 02:00" or "month 1 02:00"` };
+}
+
+/**
+ * Translate a 5-field cron line when a rule can express it (fixed minute + hour, and
+ * either a day-of-week set or one day-of-month). Anything else is refused with a hint.
+ */
+export function parseCron(text) {
+  const f = String(text || '').trim().split(/\s+/);
+  if (f.length !== 5) return { ok: false, error: '--cron needs five fields: minute hour day-of-month month day-of-week' };
+  const [min, hour, dom, mon, dow] = f;
+  const hint = ' — only a fixed time with day-of-week or one day-of-month is supported; use --every for the rest';
+  if (!/^\d{1,2}$/.test(min) || !/^\d{1,2}$/.test(hour) || +min > 59 || +hour > 23) return { ok: false, error: `--cron: minute and hour must be single numbers${hint}` };
+  if (mon !== '*') return { ok: false, error: `--cron: a month field is not supported${hint}` };
+  const time = `${pad(+hour)}:${pad(+min)}`;
+  if (dom === '*' && dow === '*') return { ok: true, rule: { freq: 'daily', interval: 1, time } };
+  if (dom === '*') {
+    const set = new Set();
+    for (const part of dow.split(',')) {
+      const r = /^(\d)(?:-(\d))?$/.exec(part);
+      if (!r) return { ok: false, error: `--cron: cannot read day-of-week "${dow}"${hint}` };
+      const a = +r[1], b = r[2] == null ? a : +r[2];
+      if (a > 7 || b > 7 || b < a) return { ok: false, error: `--cron: cannot read day-of-week "${dow}"${hint}` };
+      for (let i = a; i <= b; i++) set.add(WEEKDAYS[((i % 7) + 6) % 7]); // cron 0/7 = Sunday
+    }
+    return { ok: true, rule: { freq: 'weekly', interval: 1, weekdays: WEEKDAYS.filter((d) => set.has(d)), time } };
+  }
+  if (dow === '*' && /^\d{1,2}$/.test(dom) && +dom >= 1 && +dom <= 31) return { ok: true, rule: { freq: 'monthly', interval: 1, monthDay: +dom, time } };
+  return { ok: false, error: `--cron: this pattern cannot be expressed${hint}` };
+}
+
+/**
+ * Parse a one-shot `--at` value into a UTC ms instant. Local forms are read in `tz`:
+ *   "02:00" (next occurrence) · "today 22:00" · "tomorrow 02:00" · "+90m" "+2h" "+1d"
+ *   "2026-09-19 02:00" · "2026-09-19T02:00" · ISO 8601 with an offset or Z
+ */
+export function parseAt(text, { nowMs, tz }) {
+  const s = String(text || '').trim();
+  if (!s) return { ok: false, error: '--at needs a time' };
+  const rel = /^\+(\d+)\s*(s|sec|secs|m|min|mins|h|hr|hrs|d|day|days)$/i.exec(s);
+  if (rel) {
+    const n = Number(rel[1]); const u = rel[2][0].toLowerCase();
+    return { ok: true, ms: nowMs + n * (u === 's' ? 1000 : u === 'm' ? 60000 : u === 'h' ? 3600000 : 86400000) };
+  }
+  if (/\d{4}-\d{2}-\d{2}T/.test(s) && /([zZ]|[+-]\d{2}:?\d{2})$/.test(s)) {
+    const ms = Date.parse(s);
+    return Number.isFinite(ms) ? { ok: true, ms } : { ok: false, error: `--at: cannot read "${s}"` };
+  }
+  const now = zonedParts(nowMs, tz);
+  let r = /^(?:(today|tomorrow)\s+)?(\d{1,2}:\d{2})$/i.exec(s);
+  if (r) {
+    const tm = TIME_RE.exec(r[2]);
+    if (!tm) return { ok: false, error: `--at: "${r[2]}" is not a HH:MM time` };
+    const base = civilDayNumber(now.y, now.m, now.d) + (String(r[1] || '').toLowerCase() === 'tomorrow' ? 1 : 0);
+    const mk = (dayNo) => {
+      const dt = new Date(dayNo * 86400000);
+      return zonedToUtc({ y: dt.getUTCFullYear(), m: dt.getUTCMonth() + 1, d: dt.getUTCDate(), hh: +tm[1], mm: +tm[2] }, tz);
+    };
+    let ms = mk(base);
+    if (!r[1] && ms <= nowMs) ms = mk(base + 1); // a bare time means its NEXT occurrence
+    return { ok: true, ms };
+  }
+  r = /^(\d{4})-(\d{2})-(\d{2})[T\s](\d{1,2}):(\d{2})(?::\d{2})?$/.exec(s);
+  if (r) {
+    if (+r[4] > 23 || +r[5] > 59) return { ok: false, error: `--at: "${s}" is not a valid time` };
+    return { ok: true, ms: zonedToUtc({ y: +r[1], m: +r[2], d: +r[3], hh: +r[4], mm: +r[5] }, tz) };
+  }
+  return { ok: false, error: `--at: cannot read "${s}" — try "02:00", "tomorrow 02:00", "+90m" or "2026-09-19 02:00"` };
+}
+
+/**
+ * Parse an API `scheduledFor`: ISO 8601 WITH an offset or Z only — the server cannot
+ * know the caller's zone. Returns { ok, ms } or { ok:false, error }.
+ */
+export function parseScheduledFor(value) {
+  if (typeof value !== 'string' || !value.trim()) return { ok: false, error: 'scheduledFor must be an ISO 8601 string' };
+  const s = value.trim();
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?([zZ]|[+-]\d{2}:?\d{2})$/.test(s)) {
+    return { ok: false, error: 'scheduledFor must be ISO 8601 with a UTC offset or Z, e.g. 2026-09-19T02:00:00+02:00' };
+  }
+  const ms = Date.parse(s);
+  if (!Number.isFinite(ms)) return { ok: false, error: 'scheduledFor is not a valid date' };
+  return { ok: true, ms };
+}