@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/core/tui/host.js

@@ -0,0 +1,379 @@
+// host.ts — the alt-screen loop that hosts a ViewModule.
+//
+// Models browse/app.ts's loop, generalized: the host owns the screen, input,
+// chrome, and the single-flight async lane; the view paints into the `Draw` it's
+// handed and returns a `ViewAction` per keystroke.
+//
+//   • TTY gate: !process.stdin.isTTY → view.dump(state) to stdout, exit 0.
+//   • setup/restore terminal (alt-screen, raw); restore exactly once, however we
+//     leave (quit / Ctrl-C / crash / process exit).
+//   • single-flight async lane: at most ONE async hook (refresh or an async
+//     onKey) in flight; a busy indicator shows in the chrome; keystrokes that
+//     arrive mid-flight are DROPPED (this paces fetches/sends).
+//   • chrome: title row + separator on top; an error banner + a footer (status
+//     left, keymap hints right) on the bottom; the view gets the content Rect.
+//   • loop: parseKeypress → view.onKey → ViewAction → render; refreshMs polling;
+//     resize → render (NOT refresh) so a resize mid-fetch repaints from current
+//     state without re-entering the in-flight hook.
+import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from './terminal.js';
+import { createDraw, detectColorCaps } from './draw.js';
+// Numeric SGR codes only (a color NAME emits a broken CSI — see draw.ts guard).
+const FG = { cyan: '36', green: '32', yellow: '33', red: '31', grey: '90' };
+/** The persistent state signal: word + glyph + hue, derived from host signals so
+ *  every view gets it for free. Each pairs hue with a glyph/word — mono-safe. */
+const CHIP = {
+    working: { word: 'working', glyph: '⟳', fg: FG.cyan },
+    blocked: { word: 'blocked', glyph: '⚠', fg: FG.red },
+    attention: { word: 'attention', glyph: '⚠', fg: FG.yellow },
+    ready: { word: 'ready', glyph: '●', fg: FG.green },
+    idle: { word: 'idle', glyph: '◌', fg: FG.grey },
+};
+/** Spinner frames for the working chip (animated only while busy). */
+const SPINNER = ['⟳', '⟲'];
+/** Explicit interaction modes flip the chip to the compose accent (yellow `33`)
+ *  so entering an input mode is unmistakable. Known modes get a tailored glyph;
+ *  any other mode word falls back to `✎`. Color is yellow; the glyph + bold are
+ *  the mono carrier (survive NO_COLOR). */
+const MODE_GLYPH = { compose: '✎', react: '☺' };
+const MODE_GLYPH_FALLBACK = '✎';
+/** Banner glyph + hue by severity (color never carries meaning alone: the glyph
+ *  + bold survive NO_COLOR). */
+const BANNER = {
+    info: { glyph: 'ℹ', fg: FG.cyan },
+    action: { glyph: '▸', fg: FG.yellow },
+    error: { glyph: '✗', fg: FG.red },
+};
+/** Derive the one state chip from host signals (resume guidance): busy→working,
+ *  error banner→blocked, action banner→attention, else ready (once loaded) / idle.
+ *  An info banner does not block — the chip stays ready/idle and the cyan banner
+ *  carries the notice. */
+function deriveState(c) {
+    if (c.busy)
+        return 'working';
+    if (c.banner?.level === 'error')
+        return 'blocked';
+    if (c.banner?.level === 'action')
+        return 'attention';
+    return c.loaded ? 'ready' : 'idle';
+}
+/** Color-code the transient footer status by kind (not dim, so it leads): a
+ *  trailing … or an in-progress verb → cyan; a completed verb → green; else plain.
+ *  The words carry meaning; the hue is decorative (mono-safe). */
+function statusStyle(s) {
+    if (/…$/.test(s) || /^(loading|sending|reacting|opening|working|refreshing)\b/i.test(s))
+        return { fg: FG.cyan };
+    if (/^(sent|reacted|done|saved|caught up)\b/i.test(s) || /\bsent\b/i.test(s))
+        return { fg: FG.green };
+    return {};
+}
+/** Visible width of a span group. */
+function spanWidth(spans) {
+    let n = 0;
+    for (const s of spans)
+        n += Array.from(s.text).length;
+    return n;
+}
+/** Compact relative-time cue for "updated <rel>": now/Ns/Nm/Nh/Nd. */
+function relTime(deltaMs) {
+    const s = Math.max(0, Math.floor(deltaMs / 1000));
+    if (s < 5)
+        return 'just now';
+    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 < 24)
+        return `${h}h`;
+    return `${Math.floor(h / 24)}d`;
+}
+/** Build the right-flushed keymap span group, applying the overflow ladder: full
+ *  (key bold + label dim) → keys only → drop trailing hints (keep the last, q quit)
+ *  → the last hint alone. Returns spans ≤ `avail` where possible. */
+function keymapSpans(hints, avail) {
+    if (hints.length === 0 || avail <= 0)
+        return [];
+    const sep = () => ({ text: ' · ', style: { dim: true } });
+    const build = (hs, labels) => {
+        const out = [];
+        hs.forEach((h, i) => {
+            if (i > 0)
+                out.push(sep());
+            out.push({ text: h.keys, style: { bold: true } });
+            if (labels)
+                out.push({ text: ` ${h.label}`, style: { dim: true } });
+        });
+        return out;
+    };
+    let spans = build(hints, true);
+    if (spanWidth(spans) <= avail)
+        return spans;
+    spans = build(hints, false);
+    if (spanWidth(spans) <= avail)
+        return spans;
+    const last = hints[hints.length - 1];
+    for (let keep = hints.length - 1; keep > 0; keep--) {
+        spans = build([...hints.slice(0, keep), last], false);
+        if (spanWidth(spans) <= avail)
+            return spans;
+    }
+    return build([last], false); // may still overflow — spansRight left-clips with …
+}
+/** Draw the host chrome into `draw` and return the content Rect for the view.
+ *  Three zones: title row (state rail + title/subtitle + state chip + liveness),
+ *  a hairline, and a footer (status left, keymap right) with a severity banner
+ *  on the row above it when set. */
+function drawChrome(draw, size, manifest, c, now = Date.now()) {
+    const { cols, rows } = size;
+    const st = deriveState(c);
+    // Chip selection. An explicit interaction mode (compose/react) WINS the chip
+    // over the derived state — even while busy — so entering input is unmistakable
+    // (precedence: setMode > derived). The mode chip is the yellow compose accent;
+    // only the derived `working` chip animates its spinner.
+    let chipWord;
+    let chipGlyph;
+    let chipFg;
+    let animate = false;
+    if (c.mode) {
+        chipWord = c.mode;
+        chipGlyph = MODE_GLYPH[c.mode] ?? MODE_GLYPH_FALLBACK;
+        chipFg = FG.yellow;
+    }
+    else {
+        const chip = CHIP[st];
+        chipWord = chip.word;
+        chipGlyph = chip.glyph;
+        chipFg = chip.fg;
+        animate = st === 'working';
+    }
+    const chipStyle = { fg: chipFg, bold: true };
+    // ── Title row: right cluster first (measure), then title clipped to fit. ──
+    const glyph = animate ? (SPINNER[c.tick % SPINNER.length] ?? chipGlyph) : chipGlyph;
+    const rightCluster = [{ text: `${glyph} ${chipWord}`, style: chipStyle }];
+    if (c.loaded && c.lastRefresh > 0) {
+        rightCluster.push({ text: ` · updated ${relTime(now - c.lastRefresh)}`, style: { dim: true } });
+    }
+    const rightW = spanWidth(rightCluster);
+    draw.text(0, 0, '▎', chipStyle); // state rail (always drawn; word carries meaning in mono)
+    // Dynamic subtitle overrides the static manifest default; null ⇒ manifest.
+    const subtitle = c.subtitle ?? manifest.subtitle;
+    const titleSpans = [{ text: manifest.title, style: { bold: true } }];
+    if (subtitle)
+        titleSpans.push({ text: ` · ${subtitle}`, style: { dim: true } });
+    draw.spans(0, 2, titleSpans, Math.max(0, cols - 2 - rightW - 1));
+    draw.spansRight(0, cols, rightCluster, rightW);
+    draw.hline(1, 0, cols); // hairline separator (dim)
+    // ── Footer: status left (color-coded, not dim), keymap right. ──
+    const footerRow = rows - 1;
+    const status = c.status ?? '';
+    const statusW = Math.min(spanWidth([{ text: status }]), Math.max(0, Math.floor(cols / 2)));
+    if (status)
+        draw.spans(footerRow, 0, [{ text: status, style: statusStyle(status) }], statusW);
+    const avail = Math.max(0, cols - statusW - 1);
+    draw.spansRight(footerRow, cols, keymapSpans(manifest.keymap ?? [], avail), avail);
+    // ── Banner (bottom-1, only when set): severity-coded, full-width. ──
+    let bottomRows = 1;
+    if (c.banner) {
+        const b = BANNER[c.banner.level];
+        draw.spans(footerRow - 1, 0, [
+            { text: `${b.glyph} `, style: { fg: b.fg, bold: true } },
+            { text: c.banner.msg, style: { bold: true } },
+        ], cols);
+        bottomRows = 2;
+    }
+    const top = 2; // title + separator
+    const height = Math.max(1, rows - top - bottomRows);
+    return { row: top, col: 0, width: cols, height };
+}
+export { drawChrome };
+/** Host a view in the alt screen until it quits (or Ctrl-C). */
+export async function runView(view, opts = {}) {
+    const options = Object.freeze({ ...(opts.options ?? {}) });
+    const chrome = { status: null, banner: null, busy: false, loaded: false, lastRefresh: 0, tick: 0, subtitle: null, mode: null };
+    const host = {
+        options,
+        setStatus(msg) { chrome.status = msg; },
+        setBanner(msg, level) { chrome.banner = msg == null ? null : { msg, level }; },
+        setError(msg) { chrome.banner = msg == null ? null : { msg, level: 'error' }; },
+        setSubtitle(s) { chrome.subtitle = s; },
+        setMode(mode) { chrome.mode = mode; },
+    };
+    // ── Non-TTY / piped path: build state, best-effort load, dump, exit 0. ──
+    if (!process.stdin.isTTY) {
+        const state = await view.init(host);
+        if (view.refresh) {
+            try {
+                await view.refresh(state, host);
+            }
+            catch { /* dump current state regardless */ }
+        }
+        // Thread the host's current banner so a view can surface guidance without
+        // mirroring it into state (older views ignore the arg).
+        let text = view.dump(state, { banner: chrome.banner });
+        if (!text.endsWith('\n'))
+            text += '\n';
+        process.stdout.write(text);
+        return;
+    }
+    const caps = detectColorCaps();
+    const state = await view.init(host);
+    // Restore the terminal exactly once, however we leave.
+    let restored = false;
+    const cleanup = () => {
+        if (restored)
+            return;
+        restored = true;
+        try {
+            restoreTerminal();
+        }
+        catch { /* best-effort */ }
+    };
+    process.once('exit', cleanup);
+    const render = () => {
+        const size = getTerminalSize();
+        const { draw, frame } = createDraw(size, caps);
+        const content = drawChrome(draw, size, view.manifest, chrome);
+        try {
+            view.render(state, draw, content);
+        }
+        catch (e) {
+            chrome.banner = { msg: `render error: ${errText(e)}`, level: 'error' };
+        }
+        process.stdout.write(frame());
+    };
+    // Busy-tick repaint: while an async op is in flight, a ~120ms timer advances
+    // the spinner + re-renders so live setStatus narration shows. Render-only — it
+    // NEVER re-enters a hook, and Ctrl-C still escapes (handled before the drop).
+    let tickTimer;
+    const startBusyTick = () => {
+        if (tickTimer)
+            return;
+        tickTimer = setInterval(() => { chrome.tick++; render(); }, 120);
+    };
+    const stopBusyTick = () => {
+        if (tickTimer) {
+            clearInterval(tickTimer);
+            tickTimer = undefined;
+        }
+    };
+    // The single-flight lane. Returns true if the op ran (false if one was already
+    // in flight). Always repaints around the op so the busy indicator shows.
+    let busy = false;
+    const runRefresh = async () => {
+        if (!view.refresh || busy)
+            return;
+        busy = true;
+        chrome.busy = true;
+        render();
+        startBusyTick();
+        try {
+            await view.refresh(state, host);
+        }
+        catch (e) {
+            chrome.banner = { msg: errText(e), level: 'error' };
+        }
+        finally {
+            busy = false;
+            chrome.busy = false;
+            chrome.loaded = true;
+            chrome.lastRefresh = Date.now();
+            stopBusyTick();
+            render();
+        }
+    };
+    setupTerminal();
+    render(); // initial loading paint (before any fetch)
+    await runRefresh(); // first data load
+    await new Promise((resolveLoop) => {
+        let done = false;
+        let timer;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            if (timer)
+                clearInterval(timer);
+            stopBusyTick();
+            cleanup();
+            resolveLoop();
+        };
+        if (typeof view.manifest.refreshMs === 'number' && view.manifest.refreshMs > 0) {
+            timer = setInterval(() => { void runRefresh(); }, view.manifest.refreshMs);
+        }
+        const apply = async (action) => {
+            switch (action.type) {
+                case 'render':
+                    render();
+                    break;
+                case 'refresh':
+                    await runRefresh();
+                    break;
+                case 'quit':
+                    finish();
+                    break;
+                case 'none': break;
+            }
+        };
+        const onData = async (data) => {
+            if (done)
+                return;
+            let parsed;
+            try {
+                parsed = parseKeypress(data);
+            }
+            catch {
+                return;
+            }
+            const { input, key } = parsed;
+            // Ctrl-C is the universal escape hatch — works even mid-flight.
+            if (key.ctrl && input === 'c') {
+                finish();
+                return;
+            }
+            // Drop keystrokes while an async op is in flight (paces fetch/send).
+            if (busy)
+                return;
+            if (!view.onKey) {
+                if (input === 'q')
+                    finish(); // minimal default so a no-onKey view escapes
+                return;
+            }
+            try {
+                const r = view.onKey({ input, key }, state, host);
+                let action;
+                if (r instanceof Promise) {
+                    busy = true;
+                    chrome.busy = true;
+                    render();
+                    startBusyTick();
+                    try {
+                        action = await r;
+                    }
+                    finally {
+                        busy = false;
+                        chrome.busy = false;
+                        stopBusyTick();
+                    }
+                }
+                else {
+                    action = r;
+                }
+                await apply(action);
+            }
+            catch (e) {
+                chrome.banner = { msg: errText(e), level: 'error' };
+                render();
+            }
+        };
+        process.stdin.on('data', (d) => { void onData(d); });
+        // Resize → repaint from current state (never re-enter the in-flight hook).
+        process.stdout.on('resize', () => { if (!done)
+            render(); });
+    });
+}
+function errText(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}

package/dist/core/tui/loader.d.ts

@@ -0,0 +1,16 @@
+import type { ViewModule } from './contract.js';
+export interface ResolvedView {
+    id: string;
+    dir: string;
+    entry: string;
+    scope: 'project' | 'user' | 'builtin';
+}
+/** Scope search project→user→builtin; first hit wins. null if no view dir holds
+ *  a `<name>/view.mjs`. */
+export declare function resolveView(name: string): ResolvedView | null;
+/** Enumerate every resolvable view across scopes (first scope wins per id) —
+ *  backs `view list` / `view pick`. */
+export declare function listViews(): ResolvedView[];
+/** Dynamic-import a resolved view and validate it's a usable ViewModule. Throws
+ *  a guided error (with the entry path) if the module is malformed. */
+export declare function loadView(r: ResolvedView): Promise<ViewModule>;

package/dist/core/tui/loader.js

@@ -0,0 +1,94 @@
+// loader.ts — resolve + dynamically import view modules across scopes.
+//
+// A view = a directory containing `view.mjs` (the entry). Resolution order in
+// resolveView, first hit wins: project → user → builtin (see scope.ts viewsDir).
+// loadView does a plain `import(pathToFileURL(entry).href)` — no transpile, no
+// bundle (the published binary is `node dist/cli.js` with no esbuild/tsx) — then
+// validates the module is a usable ViewModule, throwing a guided error if not.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { viewsDir } from '../scope.js';
+const SCOPE_ORDER = ['project', 'user', 'builtin'];
+/** Scope search project→user→builtin; first hit wins. null if no view dir holds
+ *  a `<name>/view.mjs`. */
+export function resolveView(name) {
+    for (const scope of SCOPE_ORDER) {
+        const root = viewsDir(scope);
+        if (!root)
+            continue;
+        const dir = join(root, name);
+        const entry = join(dir, 'view.mjs');
+        if (existsSync(entry))
+            return { id: name, dir, entry, scope };
+    }
+    return null;
+}
+/** Enumerate every resolvable view across scopes (first scope wins per id) —
+ *  backs `view list` / `view pick`. */
+export function listViews() {
+    const seen = new Set();
+    const out = [];
+    for (const scope of SCOPE_ORDER) {
+        const root = viewsDir(scope);
+        if (!root || !existsSync(root))
+            continue;
+        let names;
+        try {
+            names = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names.sort()) {
+            if (seen.has(name))
+                continue; // first scope wins
+            const dir = join(root, name);
+            let isDir = false;
+            try {
+                isDir = statSync(dir).isDirectory();
+            }
+            catch {
+                isDir = false;
+            }
+            if (!isDir)
+                continue;
+            const entry = join(dir, 'view.mjs');
+            if (!existsSync(entry))
+                continue;
+            seen.add(name);
+            out.push({ id: name, dir, entry, scope });
+        }
+    }
+    return out;
+}
+/** Dynamic-import a resolved view and validate it's a usable ViewModule. Throws
+ *  a guided error (with the entry path) if the module is malformed. */
+export async function loadView(r) {
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(r.entry).href));
+    }
+    catch (e) {
+        throw guided(r, `failed to import the module: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const candidate = (mod['default'] ?? mod['view']);
+    if (!candidate || typeof candidate !== 'object') {
+        throw guided(r, 'no default export (or named `view`) that is a ViewModule object');
+    }
+    const m = candidate.manifest;
+    if (!m || typeof m.id !== 'string' || typeof m.title !== 'string') {
+        throw guided(r, 'manifest.id and manifest.title must be strings');
+    }
+    if (typeof candidate.init !== 'function')
+        throw guided(r, 'init() is required');
+    if (typeof candidate.render !== 'function')
+        throw guided(r, 'render() is required');
+    if (typeof candidate.dump !== 'function')
+        throw guided(r, 'dump() is required');
+    return candidate;
+}
+function guided(r, problem) {
+    return new Error(`invalid view "${r.id}" (${r.scope}) at ${r.entry}: ${problem}.\n` +
+        'A view.mjs must `export default` a ViewModule with { manifest: { id, title }, init(), render(), dump() }.');
+}

package/dist/core/{canvas/browse → tui}/terminal.js

@@ -1,9 +1,10 @@
-// terminal.ts — raw-mode helpers for the `crtr canvas browse` TUI.
+// terminal.ts — raw-mode helpers shared by every crtr raw-ANSI TUI.
 //
-// Hand-rolled (no deps), mirroring humanloop's src/tui/terminal.ts. Extends its
-// key parsing beyond up/down/return/escape/tab/backspace/ctrl + printable input:
-// adds leftArrow/rightArrow (cursor keys) and shiftTab (`\x1b[Z`) so the browser
-// can drive tree expand/collapse and tab cycling.
+// Moved verbatim from src/core/canvas/browse/terminal.ts (it was already
+// generic). Hand-rolled (no deps), mirroring humanloop's src/tui/terminal.ts.
+// Extends its key parsing beyond up/down/return/escape/tab/backspace/ctrl +
+// printable input: adds leftArrow/rightArrow (cursor keys) and shiftTab
+// (`\x1b[Z`) so callers can drive tree expand/collapse and tab cycling.
 function emptyKey() {
     return {
         upArrow: false,
@@ -77,7 +78,7 @@ export function parseKeypress(data) {
 }
 export function setupTerminal() {
     if (!process.stdin.isTTY) {
-        throw new Error('crtr canvas browse requires an interactive terminal (TTY)');
+        throw new Error('this TUI requires an interactive terminal (TTY)');
     }
     process.stdin.setRawMode(true);
     process.stdin.resume();

package/dist/core/wake.d.ts

@@ -0,0 +1,86 @@
+/** Error codes this module owns (a subset of surface-design §4.3). */
+export type WakeErrorCode = 'wake_in_past' | 'bad_when' | 'bad_cadence' | 'unknown_zone' | 'cadence_too_fast';
+export interface WakeError {
+    code: WakeErrorCode;
+    message: string;
+    /** The offending input, echoed back for the rendered error block. */
+    received: string;
+}
+export type WhenResult = {
+    fireAt: string;
+} | {
+    error: WakeError;
+};
+export type CadenceResult = {
+    recur: string;
+    firstFireAt: string;
+} | {
+    error: WakeError;
+};
+export interface ParseOpts {
+    /** IANA zone for bare wall-clock / calendar cadence; defaults to host-local. */
+    tz?: string;
+    /** Resolution anchor (frozen "now"). */
+    now: Date;
+}
+/**
+ * The two `recur` JSON shapes (pinned in the plan's Shared contracts). Stored
+ * as a JSON string in the `wakeups.recur` column; consumed by `nextSlotAfter`.
+ */
+export type Recur = {
+    every: string;
+} | {
+    cron: string;
+    tz: string;
+};
+/** Cadence floor: reject any interval / cron min-spacing below this (AC-N4). */
+export declare const CADENCE_FLOOR_MS = 60000;
+/**
+ * Resolve a `<when>` to a single UTC `fireAt`:
+ *   - relative duration (`90s`, `1h30m`)        -> now + Σ
+ *   - absolute zoned ISO (`…Z` / `±HH:MM`)       -> that exact instant
+ *   - absolute bare ISO (`2026-06-07T09:00`)     -> wall clock in `tz`
+ *                                                   (default host-local) -> UTC
+ *
+ * A bare wall-clock time is interpreted in `opts.tz` when given, else the host
+ * zone, and frozen to a UTC instant (DST never re-enters a one-shot). A
+ * resolved instant not strictly in the future is rejected (`wake_in_past`).
+ */
+export declare function parseWhen(when: string, opts: ParseOpts): WhenResult;
+/**
+ * Resolve a `<cadence>` (the `--every` value) to a stored `recur` JSON string
+ * plus the first `fireAt`:
+ *   - fixed interval (a duration)  -> {"every":"<dur>"},   first = now + interval
+ *   - calendar cron / @alias       -> {"cron":"<5-field>","tz":"<iana>"},
+ *                                     first = next match strictly after now
+ *
+ * Aliases (`@daily`) are expanded to a 5-field cron before baking, and the
+ * IANA zone (from `opts.tz`, else host-local) is baked in so the engine stays a
+ * pure UTC evaluator (design D7). Rejects sub-floor spacing (`cadence_too_fast`,
+ * < 60s — for both intervals and seconds-granular crons), ungrammatical input
+ * (`bad_cadence`), and unknown zones (`unknown_zone`).
+ */
+export declare function parseCadence(every: string, opts: ParseOpts): CadenceResult;
+/**
+ * Render a stored `recur` JSON as a compact, human-readable cadence:
+ *   - {"every":"6h"}                         -> `every 6h`
+ *   - {"cron":"0 9 * * *","tz":"America/…"}  -> ``cron `0 9 * * *` (America/…)``
+ *   - null / undefined / unparseable         -> `none`
+ *
+ * The ONE cadence-display helper, shared by the `node wake` CLI surface
+ * (list/guidance) and the <crtr-wake> wake-provenance block (bearings.ts), so
+ * the cadence an agent reads in its wake block matches `crtr node wake list`
+ * exactly. Cadence only — never an instance count.
+ */
+export declare function cadenceDisplay(recur: string | null | undefined): string;
+/**
+ * Earliest occurrence of `recur` strictly greater than `now`, as a UTC ISO
+ * string. Anchors on `now` (not the stored `fire_at`), so it structurally
+ * coalesces every slot missed while the daemon was down (design §5.3, AC-E2).
+ * DST-correct because the IANA zone is baked into a calendar `recur`.
+ *
+ * parseCadence validates the cadence at arm time, so a throw here is a rare
+ * backstop (a corrupted/foreign row) — T4 must quarantine such a row, never
+ * re-query it each tick.
+ */
+export declare function nextSlotAfter(recur: string, now: Date): string;