/** 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 `crons.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 cron CLI surface and the
 * <crtr-wake> wake-provenance block (bearings.ts), so the cadence an agent
 * reads in its wake block matches `crtr cron` 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;