/**
 * Wall-clock cron schedule helper.
 *
 * Pure helpers for parsing/validating `cron_at` schedules and computing
 * the next deterministic fire time for a given anchor (`afterUtcMs`).
 *
 * The orchestration MUST call `computeCronAtNextFire` through a recorded
 * activity so that replay reuses the original next-fire result even if
 * tzdata or the helper implementation changes later.
 *
 * This module intentionally avoids any I/O and any non-deterministic state
 * (clock reads, randomness) so it is safe to call from activity code.
 *
 * Recurrence inference:
 *   - minute                                 → hourly
 *   - minute + hour                          → daily
 *   - minute + hour + dayOfWeek (0-6, Sun=0) → weekly
 *   - minute + hour + dayOfMonth (1-31)      → monthly
 *
 * Timezone handling uses `Intl.DateTimeFormat` with the `ianaName` timezone
 * to determine the local wall-clock parts for a candidate UTC instant. This
 * works for any IANA zone supported by the running Node.js runtime.
 *
 * @module
 */
/**
 * Serialized `cron_at` schedule. Mirrors the proposed orchestration state shape.
 *
 * Optional fields (`hour`, `dayOfWeek`, `dayOfMonth`, `maxFires`,
 * `lastOccurrenceKey`, `nextFireAtMs`, `nextOccurrenceKey`) are absent unless set.
 */
export interface CronAtSchedule {
    minute: number;
    hour?: number;
    dayOfWeek?: number;
    dayOfMonth?: number;
    tz: string;
    reason: string;
    maxFires?: number;
    firesCompleted: number;
    lastOccurrenceKey?: string;
    nextFireAtMs?: number;
    nextOccurrenceKey?: string;
}
/** User-supplied input fields accepted by the `cron_at` tool. */
export interface CronAtInput {
    minute?: number | string;
    hour?: number | string;
    day_of_week?: number | string;
    day_of_month?: number | string;
    tz?: string;
    max_fires?: number | string;
    reason?: string;
}
/** Successful next-fire computation, returned by `computeCronAtNextFire`. */
export interface CronAtNextFire {
    nextFireAtMs: number;
    occurrenceKey: string;
    localTime: string;
    skippedOccurrences: number;
}
/** Validation/normalization result returned by `normalizeCronAtInput`. */
export type CronAtNormalizeResult = {
    ok: true;
    schedule: Omit<CronAtSchedule, "firesCompleted"> & {
        firesCompleted: 0;
    };
} | {
    ok: false;
    error: string;
};
declare const VALID_RECURRENCES: readonly ["hourly", "daily", "weekly", "monthly"];
export type CronAtRecurrence = (typeof VALID_RECURRENCES)[number];
/** Classify a normalized schedule into its inferred recurrence kind. */
export declare function classifyRecurrence(s: Pick<CronAtSchedule, "hour" | "dayOfWeek" | "dayOfMonth">): CronAtRecurrence;
/** True if `tz` is a valid IANA timezone according to the host runtime. */
export declare function isValidTimezone(tz: string): boolean;
/**
 * Validate and normalize raw `cron_at` tool input.
 *
 * On success, returns `{ ok: true, schedule }` with `firesCompleted = 0`.
 * On failure, returns `{ ok: false, error }` with a human-readable explanation
 * suitable for surfacing back to the LLM.
 */
export declare function normalizeCronAtInput(input: CronAtInput): CronAtNormalizeResult;
/**
 * Compute the next deterministic fire time for `schedule` strictly after `afterUtcMs`.
 *
 * This is a pure function. Call it from inside an activity to record the result
 * in durable history (the proposal contract).
 *
 * If `lastOccurrenceKey` matches the candidate occurrence key (DST fall-back
 * duplicate wall-time), the next candidate is selected so the same local
 * label does not fire twice.
 */
export declare function computeCronAtNextFire(schedule: Pick<CronAtSchedule, "minute" | "hour" | "dayOfWeek" | "dayOfMonth" | "tz">, afterUtcMs: number, lastOccurrenceKey?: string): CronAtNextFire;
/** Build a human-readable description for status surfaces and prompts. */
export declare function describeCronAt(schedule: Pick<CronAtSchedule, "minute" | "hour" | "dayOfWeek" | "dayOfMonth" | "tz">): string;
export {};
//# sourceMappingURL=cron-at.d.ts.map