@greatwait/contracts 0.1.0-alpha.1

package/dist/scheduling.d.ts

@@ -0,0 +1,1098 @@
+import { z } from "zod";
+import { type CallbackTrigger, type ResponseClass } from "./signatures.js";
+/**
+ * The scheduling resource family: schedules, the occurrences they produce, and
+ * the attempts made to deliver each occurrence.
+ *
+ * Three ideas make the difference between this and the legacy scheduler, where
+ * one row was the schedule, the occurrence and the delivery all at once.
+ *
+ * 1. **A schedule is a definition; an occurrence is a concrete instant.** A
+ *    recurring series never advances by rewriting its row, because that loses
+ *    the outcome of the occurrence it just overwrote. Each occurrence carries
+ *    its own state, retries and terminal outcome.
+ * 2. **A generation makes a stale event harmless.** Replacing a definition
+ *    increments it, so work already in flight against the old definition can be
+ *    recorded but can never fire, retire, or advance the replacement.
+ * 3. **An attempt is immutable once classified.** A redelivery is a new
+ *    attempt against the same occurrence; it never rewrites history.
+ *
+ * Nothing here carries an authority tuple. A scheduling resource belongs to the
+ * partition that stores it, and that partition is bound to exactly one
+ * `(organization, project, environment)` for its whole life — see
+ * `docs/architecture/system-architecture.md` section 3. Repeating the tuple on
+ * every row would invite two answers to the same question.
+ */
+/**
+ * Every state a schedule can be in, in lifecycle order.
+ *
+ * `paused` is reversible and `cancelled` is terminal. `completed` is what a
+ * finite schedule reaches on its own — a one-shot that fired, or a series that
+ * ran out of occurrences — and is distinct from `cancelled` because "it
+ * finished" and "someone stopped it" are different answers to a support
+ * question.
+ */
+export declare const SCHEDULE_STATUSES: readonly ["active", "paused", "cancelled", "completed"];
+export declare const scheduleStatusSchema: z.ZodEnum<{
+    paused: "paused";
+    active: "active";
+    cancelled: "cancelled";
+    completed: "completed";
+}>;
+export type ScheduleStatus = z.infer<typeof scheduleStatusSchema>;
+/**
+ * How promptly an occurrence expects to be dispatched.
+ *
+ * Two classes, not a numeric priority: a number invites callers to bid against
+ * each other, and a scheduler that honours arbitrary priorities cannot promise
+ * anything to anybody. `realtime` gets preference without starving `bulk`.
+ */
+export declare const LATENCY_CLASSES: readonly ["realtime", "bulk"];
+export declare const latencyClassSchema: z.ZodEnum<{
+    realtime: "realtime";
+    bulk: "bulk";
+}>;
+export type LatencyClass = z.infer<typeof latencyClassSchema>;
+/**
+ * How long a receiver may take to answer, as a ladder rather than a number.
+ *
+ * **A ladder because every rung is a different product.** The first two are the
+ * ordinary path: a delivery is carried inside the partition's own dispatch and
+ * holds one of six in-flight slots for its whole duration, so the cost of a slow
+ * receiver is paid by every other schedule in that
+ * `(organization, project, environment)`. The rungs above are carried elsewhere
+ * and priced, because that is the only honest way to sell them.
+ *
+ * **Deliberately not a free-form integer.** A caller that could ask for 47
+ * seconds would be asking a question this product has no answer to: 47 is past
+ * the point where a delivery may occupy a partition slot and short of the point
+ * where it is worth carrying separately. The ladder is what makes "which side of
+ * the line is this" a decision somebody took rather than a comparison somebody
+ * wrote.
+ */
+export declare const DELIVERY_DURATION_TIERS: readonly [5, 30, 300, 900, 1800, 3600, 43200, 86400];
+/**
+ * What a schedule gets without asking, in seconds.
+ *
+ * Five, and it is a **six-fold tightening of the 30 seconds that shipped**. The
+ * reason is `DEFAULT_MAX_OUTSTANDING`: a partition dispatches six deliveries at
+ * once because Cloudflare permits six connections per invocation to be waiting
+ * for response headers, so a partition's throughput is six divided by how long a
+ * delivery takes. At 30 seconds that is twelve deliveries a minute for
+ * everything a customer has scheduled in one project and environment; at five it
+ * is seventy-two. The everyday reminder webhook this product is designed around
+ * answers in well under a second, and the schedules that do not now have
+ * somewhere to say so.
+ */
+export declare const DEFAULT_DELIVERY_DURATION_SECONDS = 5;
+/**
+ * The longest duration that is not a long-running schedule, in seconds.
+ *
+ * Thirty. A receiver that writes a row and calls one API can exceed five seconds
+ * without being a long-running job, and making that customer buy a plan to fix
+ * an occasional timeout would price the most ordinary failure there is. Above
+ * this the delivery is carried outside the partition and is a plan feature.
+ *
+ * EasyCron, which sells this ladder, allows **five seconds** on its free tier
+ * and nothing between that and twelve hours. The thirty-second rung is a
+ * deliberate difference from them rather than an oversight.
+ */
+export declare const FREE_DELIVERY_DURATION_SECONDS = 30;
+/**
+ * The longest a receiver may hold the request itself open, in seconds.
+ *
+ * Thirty minutes, and it is a platform fact rather than a commercial one. A
+ * `response` delivery is carried by a Workflow step holding a live socket, and
+ * Cloudflare restarts the Workers runtime a few times a week, giving in-flight
+ * requests a thirty-second grace period and terminating whatever is left. Their
+ * own limits page calls that "very unlikely" — which is true of a five-second
+ * delivery and inverts as the hold grows: at roughly three restarts a week a
+ * twelve-hour hold overlaps one about one time in five, and a twenty-four-hour
+ * hold about two in five.
+ *
+ * A terminated hold is not a lost occurrence — the watchdog settles it
+ * `network_ambiguous` and the ladder retries it — but `network_ambiguous` on a
+ * twelve-hour job means "your receiver may have run this, and we are about to
+ * ask it to run again". Selling that as a duration would be selling a coin flip.
+ *
+ * So the rungs above this are `callback` only. A `callback` receiver answers
+ * immediately and reports afterwards, so there is no hold for a restart to
+ * terminate — the attempt waits in one indexed row, which is not running when
+ * the runtime restarts. Cloudflare's own "limit timeouts to 30 minutes or less"
+ * advice lands on the same number from the same direction, which is the reason
+ * this constant is 1,800 rather than a round guess.
+ *
+ * **This is a ceiling on the mechanism, not on the ladder.** Every rung is still
+ * for sale and the duration is still what is priced; what a customer buying more
+ * than thirty minutes has to do is answer immediately and call us back.
+ */
+export declare const RESPONSE_DELIVERY_MAX_DURATION_SECONDS = 1800;
+export declare const deliveryDurationSecondsSchema: z.ZodLiteral<5 | 300 | 86400 | 30 | 900 | 1800 | 3600 | 43200>;
+export type DeliveryDurationSeconds = z.infer<typeof deliveryDurationSecondsSchema>;
+/** Whether a duration is past the point where it needs a plan that allows it. */
+export declare function isLongRunningDuration(seconds: number): boolean;
+/**
+ * How the receiver tells us the work finished.
+ *
+ * - `response` — it answers the POST when it is done, and we hold the request
+ *   open for up to `maxDurationSeconds`. Nothing to build on the receiver's
+ *   side; its own stack has to tolerate a request open that long, which is the
+ *   customer's constraint rather than ours and is the one they will meet first.
+ *   Available up to {@link RESPONSE_DELIVERY_MAX_DURATION_SECONDS}.
+ * - `callback` — it answers immediately to say it has the work, does the work,
+ *   and calls the completion URL in the envelope when it is done. More to build
+ *   on the receiver's side and no upper bound worth naming.
+ *
+ * **What is sold is the duration rather than the mechanism.** The operator
+ * settled that on 2026-08-12: `callback` costs this product almost nothing to
+ * run — an instance waiting for an event hibernates, one holding a socket does
+ * not — so pricing it separately would charge for the option we would rather
+ * every customer took.
+ *
+ * **Both were available at every rung until 2026-08-13**, and what changed is
+ * not the pricing but a measured platform limit: see
+ * {@link RESPONSE_DELIVERY_MAX_DURATION_SECONDS} for why a held-open request
+ * stops being a promise somebody can keep at the top three rungs. The ladder is
+ * untouched, and so is what a rung costs.
+ */
+export declare const DELIVERY_COMPLETION_MODES: readonly ["response", "callback"];
+export declare const deliveryCompletionModeSchema: z.ZodEnum<{
+    response: "response";
+    callback: "callback";
+}>;
+export type DeliveryCompletionMode = z.infer<typeof deliveryCompletionModeSchema>;
+/**
+ * What to do when a recurring schedule comes due and its previous run has not
+ * finished.
+ *
+ * **There was no answer to this before long-running deliveries**, and the
+ * absence was deliberate rather than an oversight: `PartitionKernel.advanceSeries`
+ * never reads the head occurrence's state, because a series whose advance
+ * depended on delivery succeeding would stop a customer's daily schedule the
+ * first time their receiver had a bad afternoon. That reasoning is untouched for
+ * every schedule on the default duration, where a run lasts five seconds and an
+ * overlap is not a thing anyone can construct.
+ *
+ * It stops being true at twelve hours. An hourly schedule whose runs take twelve
+ * hours has twelve of them alive at once under the old rule, and no customer
+ * means that. So this setting exists **only on a long-running schedule**, which
+ * is the narrowest place it can live and still answer the question.
+ *
+ * - `skip` — do not run; record the occurrence as skipped. The default.
+ * - `queue` — run it when the previous one finishes.
+ */
+export declare const DELIVERY_OVERLAP_POLICIES: readonly ["skip", "queue"];
+export declare const deliveryOverlapPolicySchema: z.ZodEnum<{
+    skip: "skip";
+    queue: "queue";
+}>;
+export type DeliveryOverlapPolicy = z.infer<typeof deliveryOverlapPolicySchema>;
+export declare const DEFAULT_DELIVERY_OVERLAP_POLICY: DeliveryOverlapPolicy;
+/**
+ * A definition generation. Starts at 1 and increases on every replacement.
+ *
+ * Deliberately separate from `version`. `version` moves for any write at all,
+ * including a pause, and drives ETags; `generation` moves only when the *work*
+ * changes, and is what a due event is checked against. Folding them together
+ * would make pausing and resuming a schedule invalidate occurrences that are
+ * still perfectly valid.
+ */
+export declare const generationSchema: z.ZodNumber;
+export type Generation = z.infer<typeof generationSchema>;
+/**
+ * A customer-supplied fairness key.
+ *
+ * Bounded in length and charset because it is used as a telemetry label and as
+ * a pacing lane: an unbounded key would let one caller mint unbounded
+ * cardinality in our metrics, and a key carrying arbitrary bytes would end up
+ * in a log line that nothing downstream can parse. It selects a lane within the
+ * caller's own partition and can never change the authority tuple or reach
+ * another Durable Object namespace.
+ */
+export declare const PARTITION_KEY_MAX_LENGTH = 64;
+export declare const partitionKeySchema: z.ZodString;
+export type PartitionKey = z.infer<typeof partitionKeySchema>;
+/**
+ * Every state one occurrence can be in.
+ *
+ * `ambiguous` is a first-class state rather than a kind of failure. When a
+ * request times out the receiver may or may not have acted, and calling that
+ * either "succeeded" or "failed" is how an occurrence is silently dropped or
+ * silently duplicated.
+ *
+ * `skipped_stale` records an occurrence that became due too late to be worth
+ * firing, or whose definition was replaced underneath it. It is deliberately
+ * not `cancelled`: a customer who cancelled something and a customer whose
+ * occurrence went stale need different explanations.
+ */
+export declare const OCCURRENCE_STATES: readonly ["planned", "due", "dispatching", "retry_wait", "ambiguous", "succeeded", "terminal_failed", "cancelled", "skipped_stale"];
+export declare const occurrenceStateSchema: z.ZodEnum<{
+    succeeded: "succeeded";
+    ambiguous: "ambiguous";
+    cancelled: "cancelled";
+    planned: "planned";
+    due: "due";
+    dispatching: "dispatching";
+    retry_wait: "retry_wait";
+    terminal_failed: "terminal_failed";
+    skipped_stale: "skipped_stale";
+}>;
+export type OccurrenceState = z.infer<typeof occurrenceStateSchema>;
+/**
+ * The states an occurrence never leaves.
+ *
+ * Exported so a caller enumerates them rather than writing the list out and
+ * quietly missing one if another is ever added.
+ */
+export declare const TERMINAL_OCCURRENCE_STATES: readonly ["succeeded", "terminal_failed", "cancelled", "skipped_stale"];
+export declare function isTerminalOccurrenceState(state: OccurrenceState): boolean;
+/**
+ * How one delivery attempt was classified. Immutable once set.
+ *
+ * These four are the attempt-level counterpart of `ResponseClass` in
+ * `signatures.ts`, which classifies a *response*. They are kept as separate
+ * vocabularies on purpose: a response class is a fact about what came back, and
+ * an attempt state is a fact about the attempt as a whole, including an attempt
+ * that never received a response at all. `attemptStateForResponse` is the only
+ * sanctioned mapping between them.
+ */
+export declare const ATTEMPT_STATES: readonly ["succeeded", "retryable_failure", "terminal_failure", "ambiguous"];
+export declare const attemptStateSchema: z.ZodEnum<{
+    succeeded: "succeeded";
+    ambiguous: "ambiguous";
+    retryable_failure: "retryable_failure";
+    terminal_failure: "terminal_failure";
+}>;
+export type AttemptState = z.infer<typeof attemptStateSchema>;
+/** Safe diagnostic codes produced by the W3-03 delivery classifier. */
+export declare const attemptDiagnosticSchema: z.ZodEnum<{
+    rate_limited: "rate_limited";
+    completion_timed_out: "completion_timed_out";
+    delivered: "delivered";
+    duplicate_inflight: "duplicate_inflight";
+    endpoint_unavailable: "endpoint_unavailable";
+    endpoint_unsafe: "endpoint_unsafe";
+    http_refused: "http_refused";
+    http_retryable: "http_retryable";
+    http_terminal: "http_terminal";
+    identity_conflict: "identity_conflict";
+    network_ambiguous: "network_ambiguous";
+    payload_unavailable: "payload_unavailable";
+}>;
+export type AttemptDiagnostic = z.infer<typeof attemptDiagnosticSchema>;
+/**
+ * Bounded next-action hints for an attempt timeline.
+ *
+ * These are codes rather than prose so a client can render its own guidance
+ * without ever receiving an executor exception, destination, response body,
+ * payload, or secret. `review_retry_policy` names the historical category
+ * without promising that the occurrence still has automatic work to do.
+ */
+export declare const ATTEMPT_REMEDIATIONS: readonly ["none", "review_retry_policy", "inspect_receiver", "verify_endpoint", "replace_payload", "contact_support", "review_before_redelivery"];
+/**
+ * How much of one retained response header is published, in characters.
+ *
+ * The sender caps it at 256 **bytes**, and this is the schema's own bound on
+ * what may be presented — deliberately the looser of the two, because a schema
+ * that refused what the sender legitimately stored would make a delivery
+ * unreadable rather than a header untidy.
+ */
+export declare const ATTEMPT_RESPONSE_HEADER_MAX_LENGTH = 256;
+/** How much of a failed receiver's body is published, in characters. */
+export declare const ATTEMPT_FAILURE_SNIPPET_MAX_LENGTH = 4096;
+export declare const attemptRemediationSchema: z.ZodEnum<{
+    none: "none";
+    review_retry_policy: "review_retry_policy";
+    inspect_receiver: "inspect_receiver";
+    verify_endpoint: "verify_endpoint";
+    replace_payload: "replace_payload";
+    contact_support: "contact_support";
+    review_before_redelivery: "review_before_redelivery";
+}>;
+export type AttemptRemediation = z.infer<typeof attemptRemediationSchema>;
+/** Derive the one safe next-action code a public attempt may expose. */
+export declare function remediationForAttempt(diagnostic: AttemptDiagnostic): AttemptRemediation;
+/**
+ * Why this immutable attempt exists.
+ *
+ * Automatic work has no causal attempt. A manual redelivery names the
+ * retained attempt the caller chose to follow, which preserves both identities
+ * and makes the new row an honest link instead of a rewrite of the old one.
+ *
+ * **Deliberately the same schema the signed callback envelope carries**, rather
+ * than a second declaration of the same shape. From W3-08 the attempt's trigger
+ * is what reaches the receiver, so a reader of the timeline and a receiver
+ * branching on the wire are looking at one fact. Two definitions would drift,
+ * and the failure mode of that drift is a receiver that re-runs work for a
+ * cause the history says never happened.
+ */
+export declare const attemptTriggerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"automatic">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"redelivery">;
+    sourceAttemptId: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type AttemptTrigger = CallbackTrigger;
+/**
+ * The largest elapsed time JSON can carry without losing integer precision.
+ *
+ * Runtime timeout policies are ordinarily much smaller, but their configured
+ * ceiling is not a public invariant. Bounding the wire at the safe-integer
+ * edge keeps corrupt or non-finite timing out without clamping honest durable
+ * evidence into a value the executor did not report.
+ */
+export declare const ATTEMPT_DURATION_MAX_MS: number;
+/** The attempt state a classified response produces. */
+export declare function attemptStateForResponse(responseClass: ResponseClass): AttemptState;
+/**
+ * The runtime's default bounds, in one place.
+ *
+ * **These are engineering defaults, not plan limits.** They exist because a
+ * partition has to bound its own growth to stay affordable and predictable, and
+ * every one of them is enforced by the storage layer today. What they are *not*
+ * is a commercial decision: `docs/product/vision-and-strategy.md` section 11
+ * names retained history, payload size, active schedules, realtime rate,
+ * endpoints and forecast horizon as **plan limits**, and puts limits and
+ * retention behind the W7 commercial gate. W7 sets the per-plan numbers; these
+ * are what a partition enforces until it does, and the partition store takes
+ * them as an argument precisely so a plan can supply its own.
+ *
+ * Durations are whole seconds, per `docs/contracts/v1-conventions.md`.
+ */
+export declare const SCHEDULING_BOUNDS: {
+    /**
+     * Attempts made against one occurrence before it is terminal, including the
+     * first. Bounded so a permanently broken receiver cannot make one occurrence
+     * cost an unbounded amount of work.
+     */
+    readonly attemptsPerOccurrence: 8;
+    /**
+     * The longest fixed interval a recurring schedule may ask for, in seconds.
+     *
+     * Thirty days, which is the copied scheduler's `MAX_INTERVAL_SECONDS` kept
+     * rather than a new number invented beside it, and its reason is the
+     * platform's rather than the product's: a Durable Object alarm is not
+     * arbitrarily far in the future.
+     */
+    readonly everySecondsMax: number;
+    /**
+     * The shortest fixed interval a recurring schedule may ask for, in seconds.
+     *
+     * One minute, and this one is **not** inherited: the copy admits a one-second
+     * interval, which is 86,400 alarm wakes a day for a single schedule. A minute
+     * is also the finest instant a five-field cron expression can name, so both
+     * ways of expressing a recurrence promise the same granularity rather than
+     * one of them quietly promising more. Widening this later is additive by
+     * `classifyChange` and narrowing it is breaking, which is the direction to be
+     * conservative in.
+     */
+    readonly everySecondsMin: 60;
+    /**
+     * How long an idempotency receipt is honoured. A client retrying a create for
+     * longer than a day is not retrying, it is making a new request; keeping
+     * receipts beyond that turns the partition into an unbounded key/value store.
+     */
+    readonly idempotencyReceiptSeconds: number;
+    /**
+     * Concrete occurrences materialized **ahead of time** for one schedule.
+     *
+     * One, which is architecture section 15's default: a series is written one
+     * occurrence at a time rather than as a horizon, because a horizon multiplies
+     * row count by its own length and makes a replace rewrite all of it.
+     *
+     * **What it bounds is lead time, not live rows, and W2-04 settled that.**
+     * Read as "one non-terminal occurrence" it would forbid architecture section
+     * 6's own fire flow, which marks the current occurrence `due` and plans its
+     * successor in one transaction and therefore holds two. Read as this wording
+     * already says — materialized *ahead of time* — it means a schedule holds at
+     * most one `planned` occurrence whose instant has not yet arrived, which
+     * permits that transaction, permits an advance and a serve to land in either
+     * order within one wake, and still forbids the horizon it exists to forbid.
+     *
+     * Enforced by `PartitionStore.insertOccurrence`, where occurrences are
+     * planned, rather than by a unique index — an index cannot reference the
+     * present, and the present is what "ahead of time" is measured against.
+     */
+    readonly materializedOccurrencesPerSchedule: 1;
+    /**
+     * How long occurrence and attempt history is retained before it is swept.
+     * Long enough to explain last month's invoice, short enough that a busy
+     * partition's history does not outgrow its schedules.
+     */
+    readonly occurrenceHistorySeconds: number;
+    /**
+     * How far ahead a one-shot may be asked for as a *delay*, in seconds — about
+     * five years, which is the copied scheduler's `MAX_ONESHOT_SECONDS` kept
+     * rather than a new number invented beside it.
+     *
+     * It bounds `delaySeconds` and deliberately does not bound `at`. Narrowing a
+     * request field that is already published is breaking by `classifyChange`,
+     * and `at` shipped with W1-08; a horizon on both belongs with the plan limits
+     * W7 owns, which is where a customer-visible ceiling can be set once for
+     * every way of expressing the same instant.
+     */
+    readonly oneShotDelaySeconds: 158000000;
+    /**
+     * The customer payload carried to the callback, in bytes, measured on the
+     * UTF-8 encoding of the JSON the caller sent. 64 KiB comfortably fits the
+     * command-shaped payloads this product is for, and refuses the ones that are
+     * really a file transfer.
+     */
+    readonly payloadBytes: 65536;
+    /**
+     * How soon a one-shot has to be for `realtime` to be the class it gets by
+     * default, in seconds.
+     *
+     * Two minutes, which is the copied `validate.ts`'s own threshold kept rather
+     * than a number invented beside it: upstream classifies an `at` or a `delay`
+     * inside 120 seconds as realtime and everything else as bulk, on the
+     * reasoning that a wait that short is a human waiting on a screen. A caller
+     * who disagrees says so — `latencyClass` on the request is what makes this a
+     * default rather than a rule.
+     */
+    readonly realtimeOneShotSeconds: 120;
+};
+/**
+ * The longest cron expression this surface accepts, in characters.
+ *
+ * A five-field expression naming every value it could name is well under a
+ * hundred characters, so this refuses a field list built to make a parser work
+ * hard without refusing anything a human would write.
+ */
+export declare const CRON_EXPRESSION_MAX_LENGTH = 120;
+/**
+ * A cron expression, checked for shape and deliberately not for meaning.
+ *
+ * **What a schema can honestly promise here is the interesting part.** Whether
+ * an expression parses, whether its fields are in range, and whether it names
+ * an instant that ever arrives are all decisions belonging to the engine that
+ * resolves it — the partition, which owns timer authority and is the one place
+ * `cron-schedule` is a dependency. Encoding them here would mean either a
+ * second parser in this package or a JSON Schema pretending to a precision it
+ * does not have, and a published schema that lies about what it validates is
+ * worse than one that says less. So this bounds the length and the field count
+ * and stops; a request that passes it and cannot be resolved is refused by the
+ * partition as `invalid_request`, naming which part it could not resolve.
+ *
+ * Five fields, or the `@`-prefixed nicknames every cron understands. Six-field
+ * forms are not refused here — a six-field expression whose seconds field is
+ * zero says the same thing as its five-field spelling — but one that asks to
+ * fire on a second boundary is refused by the partition, because a minute is
+ * the granularity both arms of recurrence promise.
+ */
+export declare const cronExpressionSchema: z.ZodString;
+export type CronExpression = z.infer<typeof cronExpressionSchema>;
+/**
+ * How a schedule recurs, as a caller reads it back.
+ *
+ * A discriminated union rather than three optional fields, because "which of
+ * these is set" is a question a client should not have to answer by
+ * elimination — and because a one-shot is a recurrence of one rather than an
+ * absence of recurrence, which is what lets every consumer `switch`
+ * exhaustively and be told by its compiler when a fourth kind arrives.
+ *
+ * `timeZone` is present on the `cron` arm and nowhere else, which is the
+ * conventions' rule made structural: a timezone means something alongside a
+ * wall-clock recurrence and nothing alongside an instant, where it would only
+ * invite a caller to believe an instant had been reinterpreted. It is required
+ * on that arm rather than optional, so a read always says which wall clock a
+ * cron schedule is on instead of leaving the caller to assume UTC.
+ */
+export declare const recurrenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"at">;
+}, z.core.$strip>, z.ZodObject<{
+    everySeconds: z.ZodNumber;
+    kind: z.ZodLiteral<"every">;
+}, z.core.$strip>, z.ZodObject<{
+    cron: z.ZodString;
+    kind: z.ZodLiteral<"cron">;
+    timeZone: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strip>], "kind">;
+export type Recurrence = z.infer<typeof recurrenceSchema>;
+/**
+ * A schedule, as a client sees it.
+ *
+ * A callback schedule exposes the reusable endpoint it references, but never
+ * the payload stored for that endpoint and never its signing secret. The
+ * endpoint id is useful definition metadata; the encrypted payload is content
+ * and stays only in the authoritative partition.
+ */
+export declare const scheduleSchema: z.ZodObject<{
+    archivedAt: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    delivery: z.ZodOptional<z.ZodObject<{
+        completion: z.ZodEnum<{
+            response: "response";
+            callback: "callback";
+        }>;
+        maxDurationSeconds: z.ZodNumber;
+        onOverlap: z.ZodEnum<{
+            skip: "skip";
+            queue: "queue";
+        }>;
+    }, z.core.$strip>>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    generation: z.ZodNumber;
+    id: z.ZodString;
+    latencyClass: z.ZodEnum<{
+        realtime: "realtime";
+        bulk: "bulk";
+    }>;
+    partitionKey: z.ZodOptional<z.ZodString>;
+    recurrence: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"at">;
+    }, z.core.$strip>, z.ZodObject<{
+        everySeconds: z.ZodNumber;
+        kind: z.ZodLiteral<"every">;
+    }, z.core.$strip>, z.ZodObject<{
+        cron: z.ZodString;
+        kind: z.ZodLiteral<"cron">;
+        timeZone: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    }, z.core.$strip>], "kind">;
+    status: z.ZodEnum<{
+        paused: "paused";
+        active: "active";
+        cancelled: "cancelled";
+        completed: "completed";
+    }>;
+    updatedAt: z.ZodString;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type Schedule = z.infer<typeof scheduleSchema>;
+/**
+ * A page of schedules.
+ *
+ * Items are schedules rather than schedule *views*. A cross-partition listing is
+ * served from the D1 projection W2-06 built, and that projection holds a route
+ * and a summary rather than every partition's live occurrence — so a page that
+ * promised an occurrence would either lie about its freshness or force the
+ * listing back through every partition it spans. Detail is where the occurrence
+ * is authoritative, and detail is one call away.
+ */
+export declare const schedulePageSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        archivedAt: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodString;
+        delivery: z.ZodOptional<z.ZodObject<{
+            completion: z.ZodEnum<{
+                response: "response";
+                callback: "callback";
+            }>;
+            maxDurationSeconds: z.ZodNumber;
+            onOverlap: z.ZodEnum<{
+                skip: "skip";
+                queue: "queue";
+            }>;
+        }, z.core.$strip>>;
+        endpoint: z.ZodOptional<z.ZodString>;
+        generation: z.ZodNumber;
+        id: z.ZodString;
+        latencyClass: z.ZodEnum<{
+            realtime: "realtime";
+            bulk: "bulk";
+        }>;
+        partitionKey: z.ZodOptional<z.ZodString>;
+        recurrence: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"at">;
+        }, z.core.$strip>, z.ZodObject<{
+            everySeconds: z.ZodNumber;
+            kind: z.ZodLiteral<"every">;
+        }, z.core.$strip>, z.ZodObject<{
+            cron: z.ZodString;
+            kind: z.ZodLiteral<"cron">;
+            timeZone: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        }, z.core.$strip>], "kind">;
+        status: z.ZodEnum<{
+            paused: "paused";
+            active: "active";
+            cancelled: "cancelled";
+            completed: "completed";
+        }>;
+        updatedAt: z.ZodString;
+        version: z.ZodNumber;
+    }, z.core.$strip>>;
+    freshness: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>, z.ZodObject<{
+        asOf: z.ZodString;
+        kind: z.ZodLiteral<"projected">;
+        lagSeconds: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SchedulePage = z.infer<typeof schedulePageSchema>;
+/**
+ * One concrete occurrence of a schedule.
+ *
+ * `sequence` is the occurrence's position in its series, starting at 1, and is
+ * scoped to a generation: replacing a definition starts a new generation whose
+ * numbering starts again. Together `(schedule, generation, sequence)` is what
+ * makes an occurrence identifiable without depending on when it was written.
+ */
+export declare const occurrenceSchema: z.ZodObject<{
+    attemptCount: z.ZodNumber;
+    generation: z.ZodNumber;
+    id: z.ZodString;
+    plannedFor: z.ZodString;
+    schedule: z.ZodString;
+    sequence: z.ZodNumber;
+    settledAt: z.ZodOptional<z.ZodString>;
+    state: z.ZodEnum<{
+        succeeded: "succeeded";
+        ambiguous: "ambiguous";
+        cancelled: "cancelled";
+        planned: "planned";
+        due: "due";
+        dispatching: "dispatching";
+        retry_wait: "retry_wait";
+        terminal_failed: "terminal_failed";
+        skipped_stale: "skipped_stale";
+    }>;
+}, z.core.$strip>;
+export type Occurrence = z.infer<typeof occurrenceSchema>;
+/**
+ * One delivery attempt against one occurrence.
+ *
+ * `delivery` is the identifier the callback signature covers and the receiver
+ * dedupes on, so it is per-attempt rather than per-occurrence: a retry is a new
+ * delivery, and a receiver that saw the first one must be able to tell.
+ *
+ * `state` is absent while the attempt is in flight. That is the ambiguity the
+ * watchdog resolves, and modelling it as absent rather than defaulting it to a
+ * failure is what stops an in-flight attempt from being counted as one that
+ * came back.
+ */
+/**
+ * Bounded, non-secret evidence about the response a receiver sent.
+ *
+ * **A closed allowlist rather than "the headers".** A response header is
+ * receiver-controlled text that lands in durable history and on a support
+ * screen, so the question is not "is this one dangerous" but "does this one
+ * earn its place": the media type explains what the snippet is, `Retry-After`
+ * explains a pacing decision the customer can see, and one receiver-side
+ * identifier turns "your receiver refused this" into something an integrator
+ * can look up in their own logs. Cookies, `Authorization` and
+ * `WWW-Authenticate` have no representation here at all.
+ */
+export declare const attemptResponseHeaderSchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
+export type AttemptResponseHeader = z.infer<typeof attemptResponseHeaderSchema>;
+/**
+ * What a failing receiver said, bounded and access-controlled.
+ *
+ * Present only on a **failed** attempt whose response carried a text or JSON
+ * media type, and only where the plan retains one. A successful response body
+ * is never retained, and neither is a pending acknowledgement's: the customer
+ * content this product keeps is the content that helps somebody fix a broken
+ * receiver, and nothing else.
+ *
+ * `truncated` is carried rather than inferred from the length, because a body
+ * that is exactly the bound and a body that was cut at the bound are different
+ * facts and only one of them should show a customer an ellipsis.
+ */
+export declare const attemptFailureSnippetSchema: z.ZodObject<{
+    contentType: z.ZodString;
+    text: z.ZodString;
+    truncated: z.ZodBoolean;
+}, z.core.$strip>;
+export type AttemptFailureSnippet = z.infer<typeof attemptFailureSnippetSchema>;
+export declare const attemptSchema: z.ZodObject<{
+    attemptNumber: z.ZodNumber;
+    classifiedAt: z.ZodOptional<z.ZodString>;
+    delivery: z.ZodString;
+    diagnostic: z.ZodOptional<z.ZodEnum<{
+        rate_limited: "rate_limited";
+        completion_timed_out: "completion_timed_out";
+        delivered: "delivered";
+        duplicate_inflight: "duplicate_inflight";
+        endpoint_unavailable: "endpoint_unavailable";
+        endpoint_unsafe: "endpoint_unsafe";
+        http_refused: "http_refused";
+        http_retryable: "http_retryable";
+        http_terminal: "http_terminal";
+        identity_conflict: "identity_conflict";
+        network_ambiguous: "network_ambiguous";
+        payload_unavailable: "payload_unavailable";
+    }>>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodString;
+    occurrence: z.ZodString;
+    remediation: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        review_retry_policy: "review_retry_policy";
+        inspect_receiver: "inspect_receiver";
+        verify_endpoint: "verify_endpoint";
+        replace_payload: "replace_payload";
+        contact_support: "contact_support";
+        review_before_redelivery: "review_before_redelivery";
+    }>>;
+    failureSnippet: z.ZodOptional<z.ZodObject<{
+        contentType: z.ZodString;
+        text: z.ZodString;
+        truncated: z.ZodBoolean;
+    }, z.core.$strip>>;
+    responseHeaders: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>>;
+    responseStatus: z.ZodOptional<z.ZodNumber>;
+    startedAt: z.ZodString;
+    state: z.ZodOptional<z.ZodEnum<{
+        succeeded: "succeeded";
+        ambiguous: "ambiguous";
+        retryable_failure: "retryable_failure";
+        terminal_failure: "terminal_failure";
+    }>>;
+    trigger: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"automatic">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"redelivery">;
+        sourceAttemptId: z.ZodString;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+export type Attempt = z.infer<typeof attemptSchema>;
+/** An authoritative page over one schedule's retained occurrences. */
+export declare const occurrencePageSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        attemptCount: z.ZodNumber;
+        generation: z.ZodNumber;
+        id: z.ZodString;
+        plannedFor: z.ZodString;
+        schedule: z.ZodString;
+        sequence: z.ZodNumber;
+        settledAt: z.ZodOptional<z.ZodString>;
+        state: z.ZodEnum<{
+            succeeded: "succeeded";
+            ambiguous: "ambiguous";
+            cancelled: "cancelled";
+            planned: "planned";
+            due: "due";
+            dispatching: "dispatching";
+            retry_wait: "retry_wait";
+            terminal_failed: "terminal_failed";
+            skipped_stale: "skipped_stale";
+        }>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+    freshness: z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type OccurrencePage = z.infer<typeof occurrencePageSchema>;
+/** An authoritative occurrence detail response. */
+export declare const occurrenceViewSchema: z.ZodObject<{
+    freshness: z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>;
+    occurrence: z.ZodObject<{
+        attemptCount: z.ZodNumber;
+        generation: z.ZodNumber;
+        id: z.ZodString;
+        plannedFor: z.ZodString;
+        schedule: z.ZodString;
+        sequence: z.ZodNumber;
+        settledAt: z.ZodOptional<z.ZodString>;
+        state: z.ZodEnum<{
+            succeeded: "succeeded";
+            ambiguous: "ambiguous";
+            cancelled: "cancelled";
+            planned: "planned";
+            due: "due";
+            dispatching: "dispatching";
+            retry_wait: "retry_wait";
+            terminal_failed: "terminal_failed";
+            skipped_stale: "skipped_stale";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type OccurrenceView = z.infer<typeof occurrenceViewSchema>;
+/** An authoritative page over one retained occurrence's immutable attempts. */
+export declare const attemptPageSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        attemptNumber: z.ZodNumber;
+        classifiedAt: z.ZodOptional<z.ZodString>;
+        delivery: z.ZodString;
+        diagnostic: z.ZodOptional<z.ZodEnum<{
+            rate_limited: "rate_limited";
+            completion_timed_out: "completion_timed_out";
+            delivered: "delivered";
+            duplicate_inflight: "duplicate_inflight";
+            endpoint_unavailable: "endpoint_unavailable";
+            endpoint_unsafe: "endpoint_unsafe";
+            http_refused: "http_refused";
+            http_retryable: "http_retryable";
+            http_terminal: "http_terminal";
+            identity_conflict: "identity_conflict";
+            network_ambiguous: "network_ambiguous";
+            payload_unavailable: "payload_unavailable";
+        }>>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        id: z.ZodString;
+        occurrence: z.ZodString;
+        remediation: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            review_retry_policy: "review_retry_policy";
+            inspect_receiver: "inspect_receiver";
+            verify_endpoint: "verify_endpoint";
+            replace_payload: "replace_payload";
+            contact_support: "contact_support";
+            review_before_redelivery: "review_before_redelivery";
+        }>>;
+        failureSnippet: z.ZodOptional<z.ZodObject<{
+            contentType: z.ZodString;
+            text: z.ZodString;
+            truncated: z.ZodBoolean;
+        }, z.core.$strip>>;
+        responseHeaders: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>>>;
+        responseStatus: z.ZodOptional<z.ZodNumber>;
+        startedAt: z.ZodString;
+        state: z.ZodOptional<z.ZodEnum<{
+            succeeded: "succeeded";
+            ambiguous: "ambiguous";
+            retryable_failure: "retryable_failure";
+            terminal_failure: "terminal_failure";
+        }>>;
+        trigger: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"automatic">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"redelivery">;
+            sourceAttemptId: z.ZodString;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+    freshness: z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AttemptPage = z.infer<typeof attemptPageSchema>;
+/** An authoritative attempt detail or redelivery response. */
+export declare const attemptViewSchema: z.ZodObject<{
+    attempt: z.ZodObject<{
+        attemptNumber: z.ZodNumber;
+        classifiedAt: z.ZodOptional<z.ZodString>;
+        delivery: z.ZodString;
+        diagnostic: z.ZodOptional<z.ZodEnum<{
+            rate_limited: "rate_limited";
+            completion_timed_out: "completion_timed_out";
+            delivered: "delivered";
+            duplicate_inflight: "duplicate_inflight";
+            endpoint_unavailable: "endpoint_unavailable";
+            endpoint_unsafe: "endpoint_unsafe";
+            http_refused: "http_refused";
+            http_retryable: "http_retryable";
+            http_terminal: "http_terminal";
+            identity_conflict: "identity_conflict";
+            network_ambiguous: "network_ambiguous";
+            payload_unavailable: "payload_unavailable";
+        }>>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        id: z.ZodString;
+        occurrence: z.ZodString;
+        remediation: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            review_retry_policy: "review_retry_policy";
+            inspect_receiver: "inspect_receiver";
+            verify_endpoint: "verify_endpoint";
+            replace_payload: "replace_payload";
+            contact_support: "contact_support";
+            review_before_redelivery: "review_before_redelivery";
+        }>>;
+        failureSnippet: z.ZodOptional<z.ZodObject<{
+            contentType: z.ZodString;
+            text: z.ZodString;
+            truncated: z.ZodBoolean;
+        }, z.core.$strip>>;
+        responseHeaders: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>>>;
+        responseStatus: z.ZodOptional<z.ZodNumber>;
+        startedAt: z.ZodString;
+        state: z.ZodOptional<z.ZodEnum<{
+            succeeded: "succeeded";
+            ambiguous: "ambiguous";
+            retryable_failure: "retryable_failure";
+            terminal_failure: "terminal_failure";
+        }>>;
+        trigger: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"automatic">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"redelivery">;
+            sourceAttemptId: z.ZodString;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>;
+    freshness: z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AttemptView = z.infer<typeof attemptViewSchema>;
+/**
+ * A schedule together with the occurrence that is next to happen.
+ *
+ * One document rather than two calls, because "when does this next fire" is the
+ * question every caller has immediately after creating a schedule, and a client
+ * that has to make a second request to answer it will cache the first answer and
+ * be wrong.
+ */
+export declare const scheduleViewSchema: z.ZodObject<{
+    occurrence: z.ZodObject<{
+        attemptCount: z.ZodNumber;
+        generation: z.ZodNumber;
+        id: z.ZodString;
+        plannedFor: z.ZodString;
+        schedule: z.ZodString;
+        sequence: z.ZodNumber;
+        settledAt: z.ZodOptional<z.ZodString>;
+        state: z.ZodEnum<{
+            succeeded: "succeeded";
+            ambiguous: "ambiguous";
+            cancelled: "cancelled";
+            planned: "planned";
+            due: "due";
+            dispatching: "dispatching";
+            retry_wait: "retry_wait";
+            terminal_failed: "terminal_failed";
+            skipped_stale: "skipped_stale";
+        }>;
+    }, z.core.$strip>;
+    schedule: z.ZodObject<{
+        archivedAt: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodString;
+        delivery: z.ZodOptional<z.ZodObject<{
+            completion: z.ZodEnum<{
+                response: "response";
+                callback: "callback";
+            }>;
+            maxDurationSeconds: z.ZodNumber;
+            onOverlap: z.ZodEnum<{
+                skip: "skip";
+                queue: "queue";
+            }>;
+        }, z.core.$strip>>;
+        endpoint: z.ZodOptional<z.ZodString>;
+        generation: z.ZodNumber;
+        id: z.ZodString;
+        latencyClass: z.ZodEnum<{
+            realtime: "realtime";
+            bulk: "bulk";
+        }>;
+        partitionKey: z.ZodOptional<z.ZodString>;
+        recurrence: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"at">;
+        }, z.core.$strip>, z.ZodObject<{
+            everySeconds: z.ZodNumber;
+            kind: z.ZodLiteral<"every">;
+        }, z.core.$strip>, z.ZodObject<{
+            cron: z.ZodString;
+            kind: z.ZodLiteral<"cron">;
+            timeZone: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        }, z.core.$strip>], "kind">;
+        status: z.ZodEnum<{
+            paused: "paused";
+            active: "active";
+            cancelled: "cancelled";
+            completed: "completed";
+        }>;
+        updatedAt: z.ZodString;
+        version: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ScheduleView = z.infer<typeof scheduleViewSchema>;
+/**
+ * The four ways a caller may say when a schedule happens.
+ *
+ * Exported so a caller enumerates them rather than writing the list out and
+ * quietly missing one when a fifth arrives.
+ */
+export declare const RECURRENCE_REQUEST_FIELDS: readonly ["at", "cron", "delaySeconds", "everySeconds"];
+/**
+ * What a caller sends to create or replace a schedule.
+ *
+ * Exactly one of `at`, `delaySeconds`, `everySeconds` and `cron`. A callback
+ * schedule references a reusable endpoint and may carry any JSON value as its
+ * data. Nothing here names an organization, project or environment: those come
+ * from the verified principal, and the endpoint lookup is bound to that same
+ * tuple. The idempotency key is not here either — it is a header, because a
+ * retry of the *same* request must be byte-identical, and a key inside the body
+ * would make every retry a different request from the one it is retrying.
+ *
+ * **All fields optional, with refinements, rather than a union.** A union of
+ * object schemas accepts a body carrying two arms' fields, since each arm
+ * strips what it does not know; the copied validator refuses that as
+ * `ambiguous_schedule`, and a scheduler that silently picks one of two instants
+ * a customer named is the worst kind of helpful.
+ */
+export declare const scheduleRequestSchema: z.ZodObject<{
+    at: z.ZodOptional<z.ZodString>;
+    cron: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodJSONSchema>;
+    delaySeconds: z.ZodOptional<z.ZodNumber>;
+    delivery: z.ZodOptional<z.ZodObject<{
+        onOverlap: z.ZodOptional<z.ZodEnum<{
+            skip: "skip";
+            queue: "queue";
+        }>>;
+        completion: z.ZodOptional<z.ZodEnum<{
+            response: "response";
+            callback: "callback";
+        }>>;
+        maxDurationSeconds: z.ZodOptional<z.ZodLiteral<5 | 300 | 86400 | 30 | 900 | 1800 | 3600 | 43200>>;
+    }, z.core.$strict>>;
+    everySeconds: z.ZodOptional<z.ZodNumber>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    latencyClass: z.ZodOptional<z.ZodEnum<{
+        realtime: "realtime";
+        bulk: "bulk";
+    }>>;
+    partitionKey: z.ZodOptional<z.ZodString>;
+    timeZone: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strict>;
+export type ScheduleRequest = z.infer<typeof scheduleRequestSchema>;
+/**
+ * The class a request runs under: the caller's, or the one its recurrence
+ * implies.
+ *
+ * **Retenanted from the copied `validate.ts` §9 defaulting**, which is the same
+ * three rules in the same order — an explicit class wins; a `cron` or an
+ * `every` is `bulk`; a one-shot is `realtime` when it is close and `bulk`
+ * otherwise. What changes is only where the threshold is written down and that
+ * a `delay` is measured against the clock the request arrived on rather than
+ * read off a separate field, because this surface has already converted one
+ * into the other by the time anything else looks at it.
+ *
+ * It lives here rather than in either adapter because REST and MCP must reach
+ * the same class for the same body — the same reason `classifyIdempotency` is
+ * here — and because a default that two surfaces derive separately is a default
+ * they will eventually disagree about.
+ *
+ * `nowMs` is a parameter for the reason every clock in this package is: a rule
+ * about "within two minutes" that reads its own clock cannot be asked what it
+ * says one millisecond either side of the boundary.
+ */
+/** Every delivery setting resolved, with nothing left optional. */
+export interface DeliverySettings {
+    readonly completion: DeliveryCompletionMode;
+    readonly maxDurationSeconds: number;
+    readonly onOverlap: DeliveryOverlapPolicy;
+}
+/**
+ * The delivery settings a request runs under: the caller's, or the defaults.
+ *
+ * Here rather than in either adapter for the same reason `deriveLatencyClass`
+ * is: REST and MCP have to reach the same answer for the same body, and a
+ * default two surfaces derive separately is a default they will eventually
+ * disagree about.
+ *
+ * **`onOverlap` resolves to its default even for a schedule that cannot
+ * overlap**, and that is deliberate rather than sloppy. The alternative is an
+ * optional field the storage layer has to keep re-deciding about, and a stored
+ * `skip` on a five-second one-shot describes something true — the previous run
+ * is never still going — rather than something wrong.
+ */
+export declare function deriveDeliverySettings(request: ScheduleRequest): DeliverySettings;
+export declare function deriveLatencyClass(request: ScheduleRequest, nowMs: number): LatencyClass;