@greatwait/contracts 0.1.0-alpha.1

package/dist/scheduling.js

@@ -0,0 +1,1116 @@
+import { z } from "zod";
+import { attemptIdSchema, deliveryIdSchema, endpointIdSchema, occurrenceIdSchema, scheduleIdSchema, } from "./identifiers.js";
+import { CALLBACK_ATTEMPT_DIAGNOSTICS } from "./delivery.js";
+import { pageSchema, versionSchema } from "./protocol.js";
+import { callbackTriggerSchema, } from "./signatures.js";
+import { durationSecondsSchema, timeZoneSchema, timestampSchema } from "./time.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.
+ */
+/* -------------------------------------------------------------------------- */
+/* Schedule state                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const SCHEDULE_STATUSES = [
+    "active",
+    "paused",
+    "cancelled",
+    "completed",
+];
+export const scheduleStatusSchema = z.enum(SCHEDULE_STATUSES);
+/**
+ * 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 const LATENCY_CLASSES = ["realtime", "bulk"];
+export const latencyClassSchema = z.enum(LATENCY_CLASSES);
+/* -------------------------------------------------------------------------- */
+/* Delivery duration                                                          */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const DELIVERY_DURATION_TIERS = [
+    5, 30, 300, 900, 1_800, 3_600, 43_200, 86_400,
+];
+/**
+ * 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 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 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 const RESPONSE_DELIVERY_MAX_DURATION_SECONDS = 1_800;
+export const deliveryDurationSecondsSchema = z
+    .literal(DELIVERY_DURATION_TIERS)
+    .describe("How long the receiver may take to answer, in seconds");
+/** Whether a duration is past the point where it needs a plan that allows it. */
+export function isLongRunningDuration(seconds) {
+    return seconds > FREE_DELIVERY_DURATION_SECONDS;
+}
+/**
+ * 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 const DELIVERY_COMPLETION_MODES = ["response", "callback"];
+export const deliveryCompletionModeSchema = z.enum(DELIVERY_COMPLETION_MODES);
+/**
+ * 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 const DELIVERY_OVERLAP_POLICIES = ["skip", "queue"];
+export const deliveryOverlapPolicySchema = z.enum(DELIVERY_OVERLAP_POLICIES);
+export const DEFAULT_DELIVERY_OVERLAP_POLICY = "skip";
+/**
+ * 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 const generationSchema = z
+    .number()
+    .int("must be a whole number")
+    .positive("must be at least 1");
+/**
+ * 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 const PARTITION_KEY_MAX_LENGTH = 64;
+export const partitionKeySchema = z
+    .string()
+    .min(1, "must not be empty")
+    .max(PARTITION_KEY_MAX_LENGTH, `must be at most ${String(PARTITION_KEY_MAX_LENGTH)} characters`)
+    .regex(/^[A-Za-z0-9._:-]+$/u, "must use only letters, digits, dot, underscore, colon, or hyphen");
+/* -------------------------------------------------------------------------- */
+/* Occurrence state                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const OCCURRENCE_STATES = [
+    "planned",
+    "due",
+    "dispatching",
+    "retry_wait",
+    "ambiguous",
+    "succeeded",
+    "terminal_failed",
+    "cancelled",
+    "skipped_stale",
+];
+export const occurrenceStateSchema = z.enum(OCCURRENCE_STATES);
+/**
+ * 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 const TERMINAL_OCCURRENCE_STATES = [
+    "succeeded",
+    "terminal_failed",
+    "cancelled",
+    "skipped_stale",
+];
+export function isTerminalOccurrenceState(state) {
+    return TERMINAL_OCCURRENCE_STATES.includes(state);
+}
+/* -------------------------------------------------------------------------- */
+/* Attempt state                                                              */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const ATTEMPT_STATES = [
+    "succeeded",
+    "retryable_failure",
+    "terminal_failure",
+    "ambiguous",
+];
+export const attemptStateSchema = z.enum(ATTEMPT_STATES);
+/** Safe diagnostic codes produced by the W3-03 delivery classifier. */
+export const attemptDiagnosticSchema = z.enum(CALLBACK_ATTEMPT_DIAGNOSTICS);
+/**
+ * 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 const ATTEMPT_REMEDIATIONS = [
+    "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 const ATTEMPT_RESPONSE_HEADER_MAX_LENGTH = 256;
+/** How much of a failed receiver's body is published, in characters. */
+export const ATTEMPT_FAILURE_SNIPPET_MAX_LENGTH = 4_096;
+export const attemptRemediationSchema = z.enum(ATTEMPT_REMEDIATIONS);
+/** Derive the one safe next-action code a public attempt may expose. */
+export function remediationForAttempt(diagnostic) {
+    switch (diagnostic) {
+        case "delivered":
+            return "none";
+        case "endpoint_unavailable":
+        case "endpoint_unsafe":
+            return "verify_endpoint";
+        case "http_refused":
+        case "http_terminal":
+            // The same advice for two different futures, deliberately. Both mean the
+            // receiver answered and declined, so the receiver is what to look at;
+            // what differs is whether the occurrence still has attempts left, which
+            // this immutable row must not claim to know — see `http_retryable` below.
+            return "inspect_receiver";
+        case "identity_conflict":
+            return "contact_support";
+        case "payload_unavailable":
+            return "replace_payload";
+        case "completion_timed_out":
+        case "duplicate_inflight":
+        case "network_ambiguous":
+            // A receiver that acknowledged the work and then said nothing is exactly
+            // the ambiguous case, and the advice is the same one: it may have run.
+            // Anything more decisive would be this row claiming to know something no
+            // part of this system observed.
+            return "review_before_redelivery";
+        case "http_retryable":
+        case "rate_limited":
+            // This describes what the immutable diagnostic asks an operator to
+            // review, not what the occurrence will do next. The latter can change
+            // later through retry, give-up, cancellation, or redelivery; deriving
+            // from it would make this earlier attempt's representation mutable.
+            return "review_retry_policy";
+    }
+}
+/**
+ * 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 const attemptTriggerSchema = callbackTriggerSchema;
+/**
+ * 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 const ATTEMPT_DURATION_MAX_MS = Number.MAX_SAFE_INTEGER;
+/** The attempt state a classified response produces. */
+export function attemptStateForResponse(responseClass) {
+    switch (responseClass) {
+        case "success":
+            return "succeeded";
+        case "retryable":
+            return "retryable_failure";
+        case "terminal":
+            return "terminal_failure";
+        case "ambiguous":
+            return "ambiguous";
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Bounds                                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 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.
+     */
+    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.
+     */
+    everySecondsMax: 30 * 24 * 60 * 60,
+    /**
+     * 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.
+     */
+    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.
+     */
+    idempotencyReceiptSeconds: 24 * 60 * 60,
+    /**
+     * 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.
+     */
+    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.
+     */
+    occurrenceHistorySeconds: 30 * 24 * 60 * 60,
+    /**
+     * 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.
+     */
+    oneShotDelaySeconds: 158_000_000,
+    /**
+     * 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.
+     */
+    payloadBytes: 65_536,
+    /**
+     * 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.
+     */
+    realtimeOneShotSeconds: 120,
+};
+/* -------------------------------------------------------------------------- */
+/* Recurrence                                                                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 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 const cronExpressionSchema = z
+    .string()
+    .min(1, "must not be empty")
+    .max(CRON_EXPRESSION_MAX_LENGTH, `must be at most ${String(CRON_EXPRESSION_MAX_LENGTH)} characters`)
+    .refine((expression) => expression.startsWith("@") ||
+    [5, 6].includes(expression.trim().split(/\s+/u).length), { message: "must be five cron fields, six fields, or an @-nickname" });
+/**
+ * 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 const recurrenceSchema = z.discriminatedUnion("kind", [
+    /**
+     * A one-shot, which carries no instant of its own.
+     *
+     * The instant is the occurrence's `plannedFor` and is stated once, there —
+     * repeating it here would invite the two to disagree after a replace, and the
+     * question this field answers is "does this fire again", not "when". A
+     * listing, which carries no occurrence, is a summary by design; detail is one
+     * call away and is where the occurrence is authoritative.
+     */
+    z.object({ kind: z.literal("at") }),
+    z.object({
+        everySeconds: durationSecondsSchema
+            .min(SCHEDULING_BOUNDS.everySecondsMin, `must be at least ${String(SCHEDULING_BOUNDS.everySecondsMin)} seconds`)
+            .max(SCHEDULING_BOUNDS.everySecondsMax, `must be at most ${String(SCHEDULING_BOUNDS.everySecondsMax)} seconds`),
+        kind: z.literal("every"),
+    }),
+    z.object({
+        cron: cronExpressionSchema,
+        kind: z.literal("cron"),
+        timeZone: timeZoneSchema,
+    }),
+]);
+/* -------------------------------------------------------------------------- */
+/* Public resources                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const scheduleSchema = z.object({
+    /**
+     * When the schedule was filed away, and absent until it is.
+     *
+     * A timestamp rather than a `status` member, for two independent reasons.
+     * Adding an enum member a client must *receive* is breaking by
+     * `classifyChange`, and archiving is orthogonal to the lifecycle anyway: a
+     * schedule is archived *because* it is `cancelled` or `completed`, and
+     * folding the two would lose which of those it was. It is set only from a
+     * terminal status — archiving is filing, not stopping.
+     */
+    archivedAt: timestampSchema.optional(),
+    createdAt: timestampSchema,
+    /**
+     * The delivery settings in force, with the defaults filled in.
+     *
+     * **Present on every callback schedule rather than only on one that asked**,
+     * which is a deliberate departure from how `partitionKey` and `endpoint` read
+     * back. Those are absent when unset because absent is the truth about them.
+     * These three always have a value — five seconds, answer the request, skip an
+     * overlapping run — and a schedule that reported nothing would leave a caller
+     * to hardcode the defaults in order to display them, which is the shape of
+     * duplication that goes stale the first time a default moves.
+     *
+     * Absent on a timer-only schedule, which delivers to nothing.
+     *
+     * **`maxDurationSeconds` reads back as a plain duration, not as the ladder the
+     * request accepts**, and the asymmetry is the point. Narrowing a request field
+     * is breaking and widening it is additive, so the request takes the closed
+     * ladder; a *response* field is the other way round — adding a value a client
+     * must receive is what breaks it — so the response promises only "a number of
+     * seconds" and a rung added later costs no contract break.
+     */
+    delivery: z
+        .object({
+        completion: deliveryCompletionModeSchema,
+        maxDurationSeconds: durationSecondsSchema,
+        onOverlap: deliveryOverlapPolicySchema,
+    })
+        .optional(),
+    /** The verified reusable callback endpoint this schedule delivers to. */
+    endpoint: endpointIdSchema.optional(),
+    generation: generationSchema,
+    id: scheduleIdSchema,
+    latencyClass: latencyClassSchema,
+    partitionKey: partitionKeySchema.optional(),
+    /**
+     * How this schedule recurs, in the vocabulary it will keep being read in.
+     *
+     * Required rather than optional, which is additive by `classifyChange`
+     * (`required` on a *response* field is what a client may now rely on
+     * receiving, not a new obligation on it). A schedule that could omit it would
+     * make "does this fire again?" unanswerable from a read, and that is the
+     * question a caller has immediately after creating one.
+     *
+     * A schedule created as `delaySeconds` reports `{ kind: "at" }`: the delay
+     * was converted to an instant once, at acceptance, and reporting the delay
+     * back would describe a schedule whose next fire moves every time it is read.
+     */
+    recurrence: recurrenceSchema,
+    status: scheduleStatusSchema,
+    updatedAt: timestampSchema,
+    version: versionSchema,
+});
+/**
+ * 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 const schedulePageSchema = pageSchema(scheduleSchema);
+/**
+ * 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 const occurrenceSchema = z
+    .object({
+    attemptCount: z.number().int().nonnegative(),
+    generation: generationSchema,
+    id: occurrenceIdSchema,
+    /** When the occurrence was planned to fire. Never earlier than this. */
+    plannedFor: timestampSchema,
+    schedule: scheduleIdSchema,
+    sequence: z.number().int().positive(),
+    /** Present exactly when the occurrence is in a terminal state. */
+    settledAt: timestampSchema.optional(),
+    state: occurrenceStateSchema,
+})
+    // Settlement and terminality are one fact, so the wire must not be able to
+    // express them separately. The partition enforces the same pairing, and a
+    // document the storage layer could never hold is a document no client should
+    // ever be handed: "succeeded, settled at — unknown" is not a state anything
+    // can explain.
+    .refine((occurrence) => isTerminalOccurrenceState(occurrence.state) ===
+    (occurrence.settledAt !== undefined), {
+    message: "settledAt must be present for a terminal state and absent otherwise",
+    path: ["settledAt"],
+});
+/**
+ * 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 const attemptResponseHeaderSchema = z.object({
+    /** Lowercase, from the published allowlist. */
+    name: z.string().min(1).max(64),
+    value: z.string().max(ATTEMPT_RESPONSE_HEADER_MAX_LENGTH),
+});
+/**
+ * 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 const attemptFailureSnippetSchema = z.object({
+    /** The media type it was captured from. Not customer content. */
+    contentType: z.string().min(1).max(128),
+    text: z.string().max(ATTEMPT_FAILURE_SNIPPET_MAX_LENGTH),
+    truncated: z.boolean(),
+});
+export const attemptSchema = z
+    .object({
+    attemptNumber: z.number().int().positive(),
+    /** Present exactly when the attempt has been classified. */
+    classifiedAt: timestampSchema.optional(),
+    delivery: deliveryIdSchema,
+    /** Safe classifier code; absent when durable evidence predates diagnostics. */
+    diagnostic: attemptDiagnosticSchema.optional(),
+    /** Executor-observed elapsed time; absent when no durable timing survived. */
+    durationMs: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(ATTEMPT_DURATION_MAX_MS)
+        .optional(),
+    id: attemptIdSchema,
+    occurrence: occurrenceIdSchema,
+    /** Stable next-action code paired with a diagnostic when one is known. */
+    remediation: attemptRemediationSchema.optional(),
+    /**
+     * What a failing receiver said, where the plan retains it.
+     *
+     * Absent on a success, on an in-flight attempt, on a response whose media
+     * type is not text or JSON, and on a plan whose retention does not include
+     * one. Its absence is never evidence about the delivery.
+     */
+    failureSnippet: attemptFailureSnippetSchema.optional(),
+    /** The fixed diagnostic-header allowlist, when a response carried any. */
+    responseHeaders: z.array(attemptResponseHeaderSchema).max(8).optional(),
+    /** Absent when no response was received at all. */
+    responseStatus: z.number().int().min(100).max(599).optional(),
+    startedAt: timestampSchema,
+    state: attemptStateSchema.optional(),
+    trigger: attemptTriggerSchema,
+})
+    // Classification and its timestamp arrive together or not at all — the same
+    // pairing the partition's CHECK constraint enforces. Independently optional
+    // fields would let an adapter publish a classified attempt with no
+    // classification time, which validates here and is unstorable there.
+    .refine((attempt) => (attempt.state === undefined) === (attempt.classifiedAt === undefined), {
+    message: "state and classifiedAt must both be present or both absent",
+    path: ["classifiedAt"],
+})
+    // A diagnostic and the safe action derived from it are one public fact. Old
+    // retained attempts may have neither; publishing only one would make the
+    // other look accidentally lost and tempt a client to infer it.
+    .refine((attempt) => (attempt.diagnostic === undefined) ===
+    (attempt.remediation === undefined), {
+    message: "diagnostic and remediation must both be present or both absent",
+    path: ["remediation"],
+})
+    // An in-flight attempt has no classified delivery evidence. In particular,
+    // a response status may not be presented early and then contradicted by the
+    // immutable outcome that lands later — and neither may the response headers
+    // or a failure snippet, which is the same rule one field wider since W8-11.
+    .refine((attempt) => attempt.state !== undefined ||
+    (attempt.diagnostic === undefined &&
+        attempt.durationMs === undefined &&
+        attempt.failureSnippet === undefined &&
+        attempt.remediation === undefined &&
+        attempt.responseHeaders === undefined &&
+        attempt.responseStatus === undefined), {
+    message: "classification metadata must be absent while an attempt is in flight",
+    path: ["state"],
+});
+/** An authoritative page over one schedule's retained occurrences. */
+export const occurrencePageSchema = pageSchema(occurrenceSchema).extend({
+    freshness: z.object({ kind: z.literal("authoritative") }),
+});
+/** An authoritative occurrence detail response. */
+export const occurrenceViewSchema = z.object({
+    freshness: z.object({ kind: z.literal("authoritative") }),
+    occurrence: occurrenceSchema,
+});
+/** An authoritative page over one retained occurrence's immutable attempts. */
+export const attemptPageSchema = pageSchema(attemptSchema).extend({
+    freshness: z.object({ kind: z.literal("authoritative") }),
+});
+/** An authoritative attempt detail or redelivery response. */
+export const attemptViewSchema = z.object({
+    attempt: attemptSchema,
+    freshness: z.object({ kind: z.literal("authoritative") }),
+});
+/**
+ * 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 const scheduleViewSchema = z.object({
+    occurrence: occurrenceSchema,
+    schedule: scheduleSchema,
+});
+/**
+ * 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 const RECURRENCE_REQUEST_FIELDS = [
+    "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 const scheduleRequestSchema = z
+    .object({
+    /** The instant the first occurrence is planned for. */
+    at: timestampSchema.optional(),
+    /**
+     * A cron expression the schedule recurs on, read against `timeZone`.
+     *
+     * The first occurrence is the first instant the expression names after the
+     * request is accepted, so a caller does not give both an expression and a
+     * starting point — the expression already is one.
+     */
+    cron: cronExpressionSchema.optional(),
+    /**
+     * Customer data placed in the signed callback envelope.
+     *
+     * Any JSON value is accepted, including `null`, arrays and scalars. It is
+     * never returned by schedule reads or listings. The accepting adapter
+     * serializes it once, enforces `SCHEDULING_BOUNDS.payloadBytes` against
+     * those UTF-8 bytes, then encrypts those same bytes before persistence.
+     */
+    data: z.json().optional(),
+    /**
+     * How long from acceptance the first occurrence is planned for. Converted
+     * to an absolute instant once, **in the adapter that accepts the request**,
+     * against the clock that request arrived on — never in the partition, which
+     * is reached again by every retry and every replay and would convert a
+     * second time. A schedule created as a delay and one created as an instant
+     * are the same schedule afterwards, and neither drifts when it is read
+     * again.
+     */
+    delaySeconds: durationSecondsSchema
+        .positive("must be at least 1 second")
+        .max(SCHEDULING_BOUNDS.oneShotDelaySeconds, `must be at most ${String(SCHEDULING_BOUNDS.oneShotDelaySeconds)} seconds`)
+        .optional(),
+    /**
+     * How long the receiver may take, and what happens while it is taking it.
+     *
+     * Omitted is the ordinary case and the one this product is designed around:
+     * a reminder webhook answers in well under a second and needs none of this.
+     *
+     * **Grouped rather than three sibling fields**, because two of the three are
+     * meaningless without the first. `onOverlap` only answers a question a long
+     * run can ask, and a caller who set it beside a five-second delivery would
+     * be configuring something that cannot happen. Nesting makes the dependency
+     * visible in the shape instead of only in a refusal message.
+     */
+    delivery: z
+        .object({
+        /**
+         * What to do when this schedule comes due and its previous occurrence
+         * has not finished. Only meaningful on a recurring, long-running
+         * schedule; refused elsewhere rather than ignored.
+         */
+        onOverlap: deliveryOverlapPolicySchema.optional(),
+        /**
+         * How the receiver signals it is finished — by answering the request,
+         * or by calling the completion URL in the envelope.
+         */
+        completion: deliveryCompletionModeSchema.optional(),
+        /**
+         * How long the receiver may take to answer, in seconds. One of
+         * `DELIVERY_DURATION_TIERS`.
+         */
+        maxDurationSeconds: deliveryDurationSecondsSchema.optional(),
+    })
+        .strict()
+        .optional(),
+    /**
+     * A fixed interval the schedule recurs on, in seconds. The first occurrence
+     * falls one interval after acceptance.
+     *
+     * A duration and not a wall clock: `86400` is twenty-four hours and stays
+     * twenty-four hours across a daylight-saving transition, which is why it
+     * takes no `timeZone`. A caller who means "every day at nine" is naming a
+     * wall clock and wants `cron`.
+     */
+    everySeconds: durationSecondsSchema
+        .min(SCHEDULING_BOUNDS.everySecondsMin, `must be at least ${String(SCHEDULING_BOUNDS.everySecondsMin)} seconds`)
+        .max(SCHEDULING_BOUNDS.everySecondsMax, `must be at most ${String(SCHEDULING_BOUNDS.everySecondsMax)} seconds`)
+        .optional(),
+    /**
+     * A verified reusable callback endpoint owned by this request's authority.
+     *
+     * Optional so timer-only schedules remain valid. On replace, omission
+     * preserves the existing endpoint; sending `data` without this field is
+     * valid only when the stored schedule already has an endpoint.
+     */
+    endpoint: endpointIdSchema.optional(),
+    /**
+     * How promptly this schedule's occurrences expect to be served.
+     *
+     * Optional, and omitting it is the ordinary case: the default is derived
+     * from how the schedule recurs (`deriveLatencyClass`). Stating it is for
+     * the caller whose nightly cron really is a human waiting, or whose
+     * thirty-second one-shot really is a campaign — the derivation is a good
+     * guess about intent and cannot be a correct one.
+     *
+     * It buys preference, not a promise. `realtime` is served ahead of `bulk`
+     * within the same partition; it does not raise the partition's rate, so a
+     * caller who marks everything `realtime` has re-labelled their work rather
+     * than obtained more of the service.
+     */
+    latencyClass: latencyClassSchema.optional(),
+    /**
+     * A fairness lane within the caller's own project and environment.
+     *
+     * Two schedules with different keys are paced independently, so one key's
+     * herd does not delay another's work. It is a label and a lane and nothing
+     * more: it cannot widen the authority tuple, cannot select a different
+     * database shard or timer actor, and cannot raise anybody's rate — the
+     * lanes share the project's ceiling, so minting more keys divides the same
+     * budget rather than multiplying it.
+     *
+     * **Fixed once the schedule exists.** A replace may carry the key it read
+     * back or omit it to preserve the stored value. Adding, changing, or
+     * clearing it is refused as `invalid_request` with `/partitionKey` named in
+     * the field errors. Widening this later is additive and narrowing it later
+     * is breaking, so a lane that cannot move is the direction to ship in until
+     * somebody asks otherwise.
+     */
+    partitionKey: partitionKeySchema.optional(),
+    /**
+     * The IANA timezone `cron` is read against. `UTC` when omitted.
+     *
+     * Accepted only alongside `cron`. Sent with an instant or an interval it
+     * would be a caller believing something had been reinterpreted that had
+     * not, so it is refused rather than ignored — an ignored field is a
+     * misunderstanding a customer cannot see.
+     */
+    timeZone: timeZoneSchema.optional(),
+})
+    // Ordinary creation and replacement mint every authority and record
+    // identity on the service side. Stripping an unknown `id` or `authority`
+    // would make a caller believe it selected something it did not, so the body
+    // is closed rather than permissive.
+    .strict()
+    // `superRefine` rather than two `refine`s, because a pointer is the whole
+    // value of this refusal to a caller and a fixed one stopped being honest when
+    // a third and fourth way of saying "when" arrived. A body naming two of them
+    // now points at **both**, so a dashboard highlights the pair that conflict
+    // rather than one field chosen alphabetically; a body naming none points at
+    // `at`, because a pointer has to name something a document could contain and
+    // the message names the rest. The published `pointer` must start with `/`, so
+    // "the document as a whole" is not a value this surface can express.
+    .superRefine((request, context) => {
+    const supplied = RECURRENCE_REQUEST_FIELDS.filter((field) => request[field] !== undefined);
+    if (supplied.length !== 1) {
+        for (const path of supplied.length === 0 ? ["at"] : supplied) {
+            context.addIssue({
+                code: "custom",
+                message: "give exactly one of `at`, `delaySeconds`, `everySeconds` and `cron`",
+                path: [path],
+            });
+        }
+    }
+    if (request.timeZone !== undefined && request.cron === undefined) {
+        context.addIssue({
+            code: "custom",
+            message: "`timeZone` is only meaningful with `cron`",
+            path: ["timeZone"],
+        });
+    }
+    if (request.delivery?.onOverlap !== undefined) {
+        // A one-shot has nothing to overlap with. Refused rather than ignored, for
+        // the reason `timeZone` is: an ignored field is a misunderstanding the
+        // customer cannot see, and this one would look like a guarantee.
+        if (request.cron === undefined && request.everySeconds === undefined) {
+            context.addIssue({
+                code: "custom",
+                message: "`onOverlap` is only meaningful with `cron` or `everySeconds`",
+                path: ["delivery", "onOverlap"],
+            });
+        }
+        // Only checked when the duration is in *this* request. A replace may carry
+        // `onOverlap` while the stored schedule holds the duration, exactly as it
+        // may carry `data` while the stored schedule holds the endpoint, and the
+        // partition is where a request is resolved against what is stored.
+        const duration = request.delivery.maxDurationSeconds;
+        if (duration !== undefined && !isLongRunningDuration(duration)) {
+            context.addIssue({
+                code: "custom",
+                message: `\`onOverlap\` is only meaningful above ${String(FREE_DELIVERY_DURATION_SECONDS)} seconds, where a run can still be going when the next one is due`,
+                path: ["delivery", "onOverlap"],
+            });
+        }
+    }
+    // Held open past the point a held-open request survives. Checked against the
+    // *derived* pair rather than against what the body names, because
+    // `completion` defaults to `response`: a caller who asks for twelve hours and
+    // says nothing about the mechanism has asked for a twelve-hour held socket
+    // whether or not the word appears in their document. Pointing at
+    // `delivery.completion` therefore names a field the body may not contain,
+    // which is the same choice the recurrence refusal above makes and for the
+    // same reason — a pointer has to name what the caller must change.
+    if (request.delivery?.maxDurationSeconds !== undefined &&
+        request.delivery.maxDurationSeconds >
+            RESPONSE_DELIVERY_MAX_DURATION_SECONDS &&
+        (request.delivery.completion ?? "response") === "response") {
+        context.addIssue({
+            code: "custom",
+            message: `a receiver may hold the request open for at most ${String(RESPONSE_DELIVERY_MAX_DURATION_SECONDS)} seconds; above that set \`completion\` to \`callback\` and call the completion URL in the envelope when the work is done`,
+            path: ["delivery", "completion"],
+        });
+    }
+});
+/**
+ * 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 function deriveDeliverySettings(request) {
+    return {
+        completion: request.delivery?.completion ?? "response",
+        maxDurationSeconds: request.delivery?.maxDurationSeconds ?? DEFAULT_DELIVERY_DURATION_SECONDS,
+        onOverlap: request.delivery?.onOverlap ?? DEFAULT_DELIVERY_OVERLAP_POLICY,
+    };
+}
+export function deriveLatencyClass(request, nowMs) {
+    if (request.latencyClass !== undefined) {
+        return request.latencyClass;
+    }
+    if (request.cron !== undefined || request.everySeconds !== undefined) {
+        return "bulk";
+    }
+    const threshold = SCHEDULING_BOUNDS.realtimeOneShotSeconds * 1000;
+    if (request.delaySeconds !== undefined) {
+        return request.delaySeconds * 1000 <= threshold ? "realtime" : "bulk";
+    }
+    if (request.at === undefined) {
+        // No recurrence at all, which the schema refuses before this is reached.
+        // Answered rather than thrown so a caller of this function on an unvalidated
+        // body gets the conservative class instead of an exception.
+        return "bulk";
+    }
+    const atMs = Date.parse(request.at);
+    if (Number.isNaN(atMs)) {
+        return "bulk";
+    }
+    // An instant already in the past is as immediate as an instant gets, so the
+    // comparison is against the delay from now and not against its absolute
+    // value: `at` one second ago is realtime, and `at` a year out is not.
+    return atMs - nowMs <= threshold ? "realtime" : "bulk";
+}