@greatwait/contracts 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/scheduling.js

@@ -1,7 +1,8 @@
-import { z } from "zod";
+import { FIXED_INTERVAL_MIN_SECONDS, FIXED_INTERVAL_MAX_SECONDS, MAX_INLINE_PAYLOAD_BYTES, } from "./configuration-bounds.js";
+import { z } from "./zod.js";
 import { attemptIdSchema, deliveryIdSchema, endpointIdSchema, occurrenceIdSchema, scheduleIdSchema, } from "./identifiers.js";
 import { CALLBACK_ATTEMPT_DIAGNOSTICS } from "./delivery.js";
-import { pageSchema, versionSchema } from "./protocol.js";
+import { pageRequestSchema, pageSchema, versionSchema, } from "./protocol.js";
 import { callbackTriggerSchema, } from "./signatures.js";
 import { durationSecondsSchema, timeZoneSchema, timestampSchema } from "./time.js";
 /**
@@ -46,6 +47,38 @@ export const SCHEDULE_STATUSES = [
     "completed",
 ];
 export const scheduleStatusSchema = z.enum(SCHEDULE_STATUSES);
+/**
+ * The statuses a schedule never leaves, and from which it never fires again on
+ * its own.
+ *
+ * **"Never fires again on its own" rather than "never delivers again", and the
+ * distinction is real.** A member can still press Redeliver on a completed
+ * occurrence, and the repository admits that for a `completed` schedule as well
+ * as an `active` one. What is terminal here is the schedule's own timetable, not
+ * every possible future delivery.
+ *
+ * Exported for the same reason as {@link TERMINAL_OCCURRENCE_STATES}: so a
+ * caller enumerates them rather than writing the list out and quietly missing
+ * one if another is ever added. Three places had already written it out — the
+ * `archivedAt` validator in `scheduling-records.ts`, the dashboard's schedule
+ * controls, and the dashboard's pending-action rules — and the third had missed
+ * it entirely, which is the defect this list was extracted for.
+ */
+export const TERMINAL_SCHEDULE_STATUSES = [
+    "cancelled",
+    "completed",
+];
+/**
+ * Whether this schedule has finished, either on its own or because somebody
+ * stopped it.
+ *
+ * `paused` is deliberately not terminal: it is reversible, so a paused schedule
+ * pointed at a broken destination is still a problem worth telling somebody
+ * about.
+ */
+export function isTerminalScheduleStatus(status) {
+    return TERMINAL_SCHEDULE_STATUSES.includes(status);
+}
 /**
  * How promptly an occurrence expects to be dispatched.
  *
@@ -55,29 +88,87 @@ export const scheduleStatusSchema = z.enum(SCHEDULE_STATUSES);
  */
 export const LATENCY_CLASSES = ["realtime", "bulk"];
 export const latencyClassSchema = z.enum(LATENCY_CLASSES);
+/**
+ * What happens when an occurrence reaches its first attempt after its planned
+ * instant.
+ *
+ * `skipAhead` never carries a recurring first arrival across its next planned
+ * instant (and a shorter custom window may retire it earlier). `catchUp`
+ * admits one first arrival while it is still inside the schedule's staleness
+ * window, even after later recurrence instants passed. A one-shot has no next
+ * recurrence, so either explicit policy uses its staleness window and its
+ * default is `catchUp`. Neither choice applies to an occurrence already on its
+ * retry ladder: that work arrived, failed, and keeps the retry/give-up policy
+ * it started under.
+ */
+export const LATENESS_POLICIES = ["skipAhead", "catchUp"];
+export const latenessPolicySchema = z.enum(LATENESS_POLICIES);
+/** The inherited one-shot staleness window: twenty-four hours. */
+export const DEFAULT_ONE_SHOT_MAX_STALENESS_SECONDS = 86_400;
+/**
+ * The per-schedule lateness choices a caller may state.
+ *
+ * Both members are optional so a caller can override only the part whose
+ * default does not fit. The policy defaults from recurrence kind. An omitted
+ * staleness bound uses the recurrence's own default: twenty-four hours for a
+ * one-shot, and one recurrence interval for a recurring schedule.
+ */
+export const scheduleLatenessRequestSchema = z
+    .object({
+    maxStalenessSeconds: durationSecondsSchema
+        .positive("must be at least 1 second")
+        .max(Number.MAX_SAFE_INTEGER, "must be a safely representable duration")
+        .optional(),
+    policy: latenessPolicySchema.optional(),
+})
+    .strict();
+/**
+ * Lateness settings as a schedule reads back.
+ *
+ * The policy is always effective and therefore required. The numeric member
+ * remains optional because it records a per-schedule override, not a duplicated
+ * copy of a default that can be derived from the recurrence.
+ */
+export const scheduleLatenessSchema = scheduleLatenessRequestSchema.extend({
+    policy: latenessPolicySchema,
+});
 /* -------------------------------------------------------------------------- */
 /* 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.
+ * The durations this product used to sell, one rung at a time.
+ *
+ * **Kept, and no longer the whole of what is accepted** (FXO-2258). The ladder
+ * was the argument that 47 seconds is a question with no answer — past the
+ * point where a delivery may occupy a partition slot, short of the point where
+ * it is worth carrying separately. The operator overruled it after the walk:
+ * "This can have a completely user definable timeout, they don't cost us hardly
+ * anything, but we should cap at something anyway, 24h is still fine."
+ *
+ * What the rungs were actually carrying survives without them. The line that
+ * matters commercially is {@link FREE_DELIVERY_DURATION_SECONDS} — above thirty
+ * seconds a delivery is carried outside the partition and needs a plan that
+ * allows it — and that line is a comparison, not a membership test. The line
+ * that matters technically is {@link RESPONSE_DELIVERY_MAX_DURATION_SECONDS},
+ * which is also a comparison. Neither ever needed eight fixed values to be
+ * expressible; the ladder was how they were *sold*, and per-rung pricing is
+ * what the operator withdrew.
+ *
+ * The list stays because a schedule saved on a rung must keep working, because
+ * the delivery-class rules are still exercised against exactly these values,
+ * and because the dashboard offers them as the shortcuts most people want.
  */
 export const DELIVERY_DURATION_TIERS = [
     5, 30, 300, 900, 1_800, 3_600, 43_200, 86_400,
 ];
+/**
+ * The longest duration any delivery may be given, in seconds.
+ *
+ * Twenty-four hours, which is the ladder's own top rung — so widening the field
+ * to a free-form integer admits nothing that was not already for sale. "24h is
+ * still fine."
+ */
+export const MAX_DELIVERY_DURATION_SECONDS = 86_400;
 /**
  * What a schedule gets without asking, in seconds.
  *
@@ -134,8 +225,26 @@ export const FREE_DELIVERY_DURATION_SECONDS = 30;
  * than thirty minutes has to do is answer immediately and call us back.
  */
 export const RESPONSE_DELIVERY_MAX_DURATION_SECONDS = 1_800;
+/**
+ * How long the receiver may take to answer, in whole seconds.
+ *
+ * **A bounded integer since FXO-2258, and every value the enum accepted is
+ * still accepted.** A widening is the one shape of contract change that cannot
+ * break a caller: a request that was valid before is valid now, and a stored
+ * schedule reads back and re-saves unchanged.
+ *
+ * The two bounds that are real are still enforced, and neither of them was ever
+ * the enum's doing: `maxDurationSeconds` above
+ * {@link RESPONSE_DELIVERY_MAX_DURATION_SECONDS} is refused unless `completion`
+ * is `callback` (checked in `scheduleRequestSchema`'s refinement, because it is
+ * a relation between two fields), and above
+ * {@link FREE_DELIVERY_DURATION_SECONDS} it needs a plan that allows it.
+ */
 export const deliveryDurationSecondsSchema = z
-    .literal(DELIVERY_DURATION_TIERS)
+    .number()
+    .int("must be a whole number of seconds")
+    .positive("must be at least 1 second")
+    .max(MAX_DELIVERY_DURATION_SECONDS, `must be at most ${String(MAX_DELIVERY_DURATION_SECONDS)} seconds`)
     .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) {
@@ -247,6 +356,89 @@ export const OCCURRENCE_STATES = [
     "skipped_stale",
 ];
 export const occurrenceStateSchema = z.enum(OCCURRENCE_STATES);
+/**
+ * One project-wide walk over retained occurrences, newest first.
+ *
+ * There is deliberately no order parameter: the Executions page answers what
+ * happened most recently, and making that fixed lets its index and cursor say
+ * the same thing. The date range is half-open, like every other time window in
+ * this contract, so adjacent requests neither overlap nor leave a gap.
+ */
+export const projectOccurrenceListRequestSchema = pageRequestSchema
+    .extend({
+    endpoint: endpointIdSchema.optional(),
+    from: timestampSchema.optional(),
+    outcome: occurrenceStateSchema.optional(),
+    schedule: scheduleIdSchema.optional(),
+    to: timestampSchema.optional(),
+})
+    .refine((request) => request.from === undefined ||
+    request.to === undefined ||
+    Date.parse(request.from) < Date.parse(request.to), {
+    message: "must be later than from",
+    path: ["to"],
+});
+const PROJECT_OCCURRENCE_LIST_PARAMETERS = [
+    "cursor",
+    "limit",
+    "endpoint",
+    "from",
+    "outcome",
+    "schedule",
+    "to",
+];
+/** Read the project occurrence filters exactly as REST and MCP send them. */
+export function parseProjectOccurrenceListRequest(query) {
+    const errors = [];
+    const raw = {};
+    for (const field of PROJECT_OCCURRENCE_LIST_PARAMETERS) {
+        const values = query.getAll(field);
+        if (values.length > 1) {
+            errors.push({
+                pointer: `/${field}`,
+                reason: "must be given at most once",
+            });
+            continue;
+        }
+        const value = values[0];
+        if (value === undefined)
+            continue;
+        raw[field] =
+            field === "limit" && /^-?\d+$/u.test(value) ? Number(value) : value;
+    }
+    if (errors.length > 0)
+        return { errors, ok: false };
+    const parsed = projectOccurrenceListRequestSchema.safeParse(raw);
+    if (parsed.success)
+        return { ok: true, page: parsed.data };
+    return {
+        errors: parsed.error.issues.map((issue) => ({
+            pointer: `/${issue.path.join("/")}`,
+            reason: issue.message,
+        })),
+        ok: false,
+    };
+}
+/**
+ * The exact operation and filters a project occurrence cursor belongs to.
+ *
+ * Cursor and limit do not affect which ordered collection is being walked, so
+ * neither belongs in the binding. Every actual filter does. Optional values
+ * stay absent rather than becoming empty strings, which are invalid inputs and
+ * must never collide with an unfiltered request.
+ */
+export function projectOccurrenceCursorBinding(request) {
+    return {
+        operation: "executions.list",
+        parameters: {
+            ...(request.endpoint === undefined ? {} : { endpoint: request.endpoint }),
+            ...(request.from === undefined ? {} : { from: request.from }),
+            ...(request.outcome === undefined ? {} : { outcome: request.outcome }),
+            ...(request.schedule === undefined ? {} : { schedule: request.schedule }),
+            ...(request.to === undefined ? {} : { to: request.to }),
+        },
+    };
+}
 /**
  * The states an occurrence never leaves.
  *
@@ -296,7 +488,7 @@ export const ATTEMPT_REMEDIATIONS = [
     "none",
     "review_retry_policy",
     "inspect_receiver",
-    "verify_endpoint",
+    "review_endpoint",
     "replace_payload",
     "contact_support",
     "review_before_redelivery",
@@ -320,7 +512,7 @@ export function remediationForAttempt(diagnostic) {
             return "none";
         case "endpoint_unavailable":
         case "endpoint_unsafe":
-            return "verify_endpoint";
+            return "review_endpoint";
         case "http_refused":
         case "http_terminal":
             // The same advice for two different futures, deliberately. Both mean the
@@ -409,17 +601,37 @@ 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.
+     *
+     * **Eight, and the number is load-bearing against a second limit rather than
+     * on its own.** `MAX_BUDGETED_DELIVERY_FAILURES` stops an occurrence after
+     * five failures the *receiver* caused; a rate limit and this product's own
+     * infrastructure faults are exempt from that count. The gap between the two
+     * is what the exemption spends — an occurrence throttled twice still has
+     * five receiver failures left. Lowering this to five was considered during
+     * the W4-10 walk and rejected once the pair was understood: it would make
+     * both limits fire on the same attempt and leave the exemption buying
+     * nothing.
      */
     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.
+     * One year. **The thirty days this replaces had no reason of its own** — it
+     * was the copied scheduler's `MAX_INTERVAL_SECONDS`, carried over on the
+     * belief that "a Durable Object alarm is not arbitrarily far in the future".
+     * Cloudflare documents no maximum distance for `setAlarm()`, and the belief
+     * predates the PostgreSQL authority besides: the durable fact is a row, and
+     * the alarm is only what wakes a bucket to read it.
+     *
+     * What makes a distant alarm safe is not the alarm. `TimerBucketRepairer`
+     * asks PostgreSQL for occurrences whose instant has passed and re-signals
+     * their bucket, on committed truth, never asking whether an alarm was armed
+     * — so an alarm that is somehow lost costs lateness rather than the run.
+     *
+     * Widening a bound is additive by `classifyChange` and narrowing it is
+     * breaking, so this direction is the safe one to move in.
      */
-    everySecondsMax: 30 * 24 * 60 * 60,
+    everySecondsMax: FIXED_INTERVAL_MAX_SECONDS,
     /**
      * The shortest fixed interval a recurring schedule may ask for, in seconds.
      *
@@ -431,7 +643,7 @@ export const SCHEDULING_BOUNDS = {
      * `classifyChange` and narrowing it is breaking, which is the direction to be
      * conservative in.
      */
-    everySecondsMin: 60,
+    everySecondsMin: FIXED_INTERVAL_MIN_SECONDS,
     /**
      * 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
@@ -483,7 +695,7 @@ export const SCHEDULING_BOUNDS = {
      * command-shaped payloads this product is for, and refuses the ones that are
      * really a file transfer.
      */
-    payloadBytes: 65_536,
+    payloadBytes: MAX_INLINE_PAYLOAD_BYTES,
     /**
      * How soon a one-shot has to be for `realtime` to be the class it gets by
      * default, in seconds.
@@ -573,6 +785,10 @@ export const recurrenceSchema = z.discriminatedUnion("kind", [
         timeZone: timeZoneSchema,
     }),
 ]);
+/** The customer-safe default for a schedule's recurrence kind. */
+export function defaultLatenessPolicyForRecurrence(kind) {
+    return kind === "at" ? "catchUp" : "skipAhead";
+}
 /* -------------------------------------------------------------------------- */
 /* Public resources                                                           */
 /* -------------------------------------------------------------------------- */
@@ -584,6 +800,23 @@ export const recurrenceSchema = z.discriminatedUnion("kind", [
  * endpoint id is useful definition metadata; the encrypted payload is content
  * and stays only in the authoritative partition.
  */
+/**
+ * A schedule's name: for people, never an identifier, and free to collide.
+ *
+ * Generated on save when nobody types one (W4-14, FXO-2255) — "Every 60s →
+ * flowxo.com" — and stored as any other name, so editing the recurrence
+ * later rewrites nothing. Two schedules may share a name: two on the same
+ * cadence against the same host both generate the same one, and the operator
+ * chose to let them collide, with the other columns and the identifier
+ * telling them apart. Endpoints get the opposite rule.
+ */
+/** The most a schedule's name may hold; the generated one is cut to fit it. */
+export const SCHEDULE_NAME_MAX_LENGTH = 120;
+export const scheduleNameSchema = z
+    .string()
+    .trim()
+    .min(1, "must not be blank")
+    .max(SCHEDULE_NAME_MAX_LENGTH, `must be at most ${String(SCHEDULE_NAME_MAX_LENGTH)} characters`);
 export const scheduleSchema = z.object({
     /**
      * When the schedule was filed away, and absent until it is.
@@ -596,6 +829,20 @@ export const scheduleSchema = z.object({
      * terminal status — archiving is filing, not stopping.
      */
     archivedAt: timestampSchema.optional(),
+    /**
+     * The payload the schedule carries, as it was given.
+     *
+     * Present on a read when the schedule has one; left off listings, which are
+     * served from a projection that holds a summary. **Readable by anyone who
+     * can read the schedule** — the dashboard, the API, the SDK and MCP alike —
+     * since FXO-2243, chosen with the cost stated: a payload somebody put a
+     * secret in is readable by anything holding a read key, and appears in an
+     * agent's tool history. The write-only custody this replaces answered that
+     * with a blanket rule over the whole body — "I've never used a platform
+     * where my configured payload was hidden from me" — and W4-13 answers it
+     * per field instead, with a header value that is a secret marked as one.
+     */
+    data: z.json().optional(),
     createdAt: timestampSchema,
     /**
      * The delivery settings in force, with the defaults filled in.
@@ -626,9 +873,33 @@ export const scheduleSchema = z.object({
         .optional(),
     /** The verified reusable callback endpoint this schedule delivers to. */
     endpoint: endpointIdSchema.optional(),
+    /**
+     * Where the schedule delivers, as an address (W4-14, FXO-2255).
+     *
+     * Beside the identifier rather than instead of it, on the listing and the
+     * read alike, so every caller — dashboard, SDK, agent — sees a readable
+     * destination without a second request. Present when the schedule has an
+     * endpoint the service could name; absent on a timer, and on a row whose
+     * endpoint is no longer readable.
+     */
+    endpointUrl: z.string().url().optional(),
     generation: generationSchema,
     id: scheduleIdSchema,
     latencyClass: latencyClassSchema,
+    /**
+     * What this schedule does with an occurrence that reaches its first attempt
+     * late. Present on every schedule so a caller never has to duplicate the
+     * recurrence-sensitive policy default. `maxStalenessSeconds` is present only
+     * when this schedule overrides its recurrence's window.
+     */
+    lateness: scheduleLatenessSchema,
+    /**
+     * The schedule's name. Every schedule the service has written since W4-14
+     * has one — generated on save when none was given — and it is optional on
+     * the wire only so a row from before the column, or a reader holding a
+     * projection the migration has not reached, parses rather than fails.
+     */
+    name: scheduleNameSchema.optional(),
     partitionKey: partitionKeySchema.optional(),
     /**
      * How this schedule recurs, in the vocabulary it will keep being read in.
@@ -643,6 +914,24 @@ export const scheduleSchema = z.object({
      * 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.
      */
+    /**
+     * When this schedule next fires, and absent when nothing is on the books.
+     *
+     * **The earliest unsettled occurrence, which is a fact rather than a
+     * projection** (FXO-2283). It is absent for a schedule that will not fire
+     * again — cancelled, archived, or a one-shot that has run — and absent is the
+     * truth about those rather than a value withheld: there is no instant to
+     * report, and reporting the last one would read as a plan.
+     *
+     * **This is the one field on a listing row that does not come from the
+     * projection.** The page comment below says a listing holds a route and a
+     * summary rather than every partition's live occurrence, and that is still
+     * true of the *detail* an occurrence carries — its state, its attempts, its
+     * identifier. This is one instant, taken by a lateral against a partial index
+     * built for it, and it is here because "when does this next run" is the
+     * question a list of schedules is read to answer.
+     */
+    nextDueAt: timestampSchema.optional(),
     recurrence: recurrenceSchema,
     status: scheduleStatusSchema,
     updatedAt: timestampSchema,
@@ -652,13 +941,39 @@ export const scheduleSchema = z.object({
  * 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
+ * served from the control-plane 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);
+function hasCompleteTimingEvidence(value) {
+    return ((value.firstAttemptStartedAt === undefined) ===
+        (value.firstAttemptLatenessMs === undefined) &&
+        (value.firstAttemptStartedAt === undefined) ===
+            (value.timingPolicyVersion === undefined));
+}
+function hasConsistentTimingEligibility(value) {
+    return value.timingEligibility === undefined
+        ? value.timingEligibilityReason === undefined
+        : value.timingEligibility === "eligible"
+            ? value.timingEligibilityReason === undefined
+            : value.timingEligibilityReason !== undefined;
+}
+const timingEvidenceShape = {
+    /** Signed difference from `plannedFor`; a negative value is an early send. */
+    firstAttemptLatenessMs: z.int().optional(),
+    /** Earliest trusted outbound start across this occurrence's attempts. */
+    firstAttemptStartedAt: timestampSchema.optional(),
+    /** Absent on records that predate timing evidence, which means unknown. */
+    timingEligibility: z
+        .enum(["eligible", "customer_blocked", "platform_blocked"])
+        .optional(),
+    timingEligibilityReason: z.string().min(1).max(128).optional(),
+    /** Policy pinned when trusted first-attempt timing evidence is recorded. */
+    timingPolicyVersion: z.string().min(1).max(64).optional(),
+};
 /**
  * One concrete occurrence of a schedule.
  *
@@ -670,6 +985,7 @@ export const schedulePageSchema = pageSchema(scheduleSchema);
 export const occurrenceSchema = z
     .object({
     attemptCount: z.number().int().nonnegative(),
+    ...timingEvidenceShape,
     generation: generationSchema,
     id: occurrenceIdSchema,
     /** When the occurrence was planned to fire. Never earlier than this. */
@@ -689,6 +1005,14 @@ export const occurrenceSchema = z
     (occurrence.settledAt !== undefined), {
     message: "settledAt must be present for a terminal state and absent otherwise",
     path: ["settledAt"],
+})
+    .refine(hasCompleteTimingEvidence, {
+    message: "firstAttemptStartedAt, firstAttemptLatenessMs and timingPolicyVersion must be present together",
+    path: ["firstAttemptStartedAt"],
+})
+    .refine(hasConsistentTimingEligibility, {
+    message: "timingEligibilityReason is required for a blocked population and absent otherwise",
+    path: ["timingEligibilityReason"],
 });
 /**
  * One delivery attempt against one occurrence.
@@ -746,6 +1070,12 @@ export const attemptSchema = z
     delivery: deliveryIdSchema,
     /** Safe classifier code; absent when durable evidence predates diagnostics. */
     diagnostic: attemptDiagnosticSchema.optional(),
+    /**
+     * Instrumented re-drives of the same dispatching occurrence under a new
+     * dispatch epoch. Includes deliberate admission deferrals; this is not a
+     * count of database failures or callback sends. Absent on older responses.
+     */
+    dispatchRecoveries: z.int().nonnegative().optional(),
     /** Executor-observed elapsed time; absent when no durable timing survived. */
     durationMs: z
         .number()
@@ -753,8 +1083,26 @@ export const attemptSchema = z
         .nonnegative()
         .max(ATTEMPT_DURATION_MAX_MS)
         .optional(),
+    ...timingEvidenceShape,
     id: attemptIdSchema,
+    /**
+     * Instrumented send authorizations granted after a later local alarm
+     * replayed the original wake receipt. Preserves the attempt and delivery
+     * identity; excludes synchronous receipt hedges and repeated authorization
+     * acknowledgements. A grant does not prove a callback left. Absent on
+     * older responses.
+     */
+    localReceiptRecoveries: z.int().nonnegative().optional(),
     occurrence: occurrenceIdSchema,
+    /**
+     * How many times the watchdog took this attempt's send back and sent it
+     * again: the send was authorized, and its outcome was never recorded
+     * before its lease expired. Each re-send uses this attempt's `delivery` id,
+     * so the receiver may have got the attempt more than once. `state` is the
+     * outcome that was recorded. The timing evidence is the earliest send
+     * known to have left. Absent when nothing was re-sent.
+     */
+    rescues: z.int().positive().optional(),
     /** Stable next-action code paired with a diagnostic when one is known. */
     remediation: attemptRemediationSchema.optional(),
     /**
@@ -802,11 +1150,24 @@ export const attemptSchema = z
         attempt.responseStatus === undefined), {
     message: "classification metadata must be absent while an attempt is in flight",
     path: ["state"],
+})
+    .refine(hasCompleteTimingEvidence, {
+    message: "firstAttemptStartedAt, firstAttemptLatenessMs and timingPolicyVersion must be present together",
+    path: ["firstAttemptStartedAt"],
+})
+    .refine(hasConsistentTimingEligibility, {
+    message: "timingEligibilityReason is required for a blocked population and absent otherwise",
+    path: ["timingEligibilityReason"],
 });
 /** An authoritative page over one schedule's retained occurrences. */
 export const occurrencePageSchema = pageSchema(occurrenceSchema).extend({
     freshness: z.object({ kind: z.literal("authoritative") }),
 });
+/** A project-wide occurrence page and its plan's normal history boundary. */
+export const projectOccurrencePageSchema = pageSchema(occurrenceSchema).extend({
+    freshness: z.object({ kind: z.literal("authoritative") }),
+    retention: z.object({ from: timestampSchema }),
+});
 /** An authoritative occurrence detail response. */
 export const occurrenceViewSchema = z.object({
     freshness: z.object({ kind: z.literal("authoritative") }),
@@ -877,8 +1238,8 @@ export const scheduleRequestSchema = z
     /**
      * 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
+     * Any JSON value is accepted, including `null`, arrays and scalars. A
+     * schedule read returns it; listings leave it off. The accepting adapter
      * serializes it once, enforces `SCHEDULING_BOUNDS.payloadBytes` against
      * those UTF-8 bytes, then encrypts those same bytes before persistence.
      */
@@ -904,16 +1265,15 @@ export const scheduleRequestSchema = z
      *
      * **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.
+     * run can ask; beside a five-second delivery it is stored and never
+     * consulted. Nesting makes the dependency visible in the shape.
      */
     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.
+         * has not finished. Consulted only on a recurring schedule whose runs
+         * can outlast their interval; accepted and ignored elsewhere.
          */
         onOverlap: deliveryOverlapPolicySchema.optional(),
         /**
@@ -922,8 +1282,11 @@ export const scheduleRequestSchema = z
          */
         completion: deliveryCompletionModeSchema.optional(),
         /**
-         * How long the receiver may take to answer, in seconds. One of
-         * `DELIVERY_DURATION_TIERS`.
+         * How long the receiver may take to answer, in whole seconds, up to
+         * `MAX_DELIVERY_DURATION_SECONDS`. Above
+         * `RESPONSE_DELIVERY_MAX_DURATION_SECONDS` the receiver has to answer
+         * immediately and call the completion URL instead, which is what
+         * `completion: "callback"` says.
          */
         maxDurationSeconds: deliveryDurationSecondsSchema.optional(),
     })
@@ -965,6 +1328,17 @@ export const scheduleRequestSchema = z
      * than obtained more of the service.
      */
     latencyClass: latencyClassSchema.optional(),
+    /**
+     * What to do when an occurrence reaches its first attempt late.
+     *
+     * Omitted policy defaults to `catchUp` for `at` and `delaySeconds`, and to
+     * `skipAhead` for `everySeconds` and `cron`. `maxStalenessSeconds` overrides
+     * the schedule-derived window with a positive whole number of seconds.
+     * Retries are exempt: once an occurrence has made an attempt, retry and
+     * give-up policy decide its outcome instead of measuring again from the
+     * original planned instant.
+     */
+    lateness: scheduleLatenessRequestSchema.optional(),
     /**
      * A fairness lane within the caller's own project and environment.
      *
@@ -983,6 +1357,15 @@ export const scheduleRequestSchema = z
      * somebody asks otherwise.
      */
     partitionKey: partitionKeySchema.optional(),
+    /**
+     * A name for people (W4-14, FXO-2255). On a create, omitted means the
+     * service generates one from the type, period and target domain —
+     * "Every 60s → flowxo.com" — and stores it. On a replace, omitted means
+     * the stored name stays as it is: a generated name is recomputed on
+     * nothing, so editing the recurrence does not silently rewrite a name
+     * the person kept or changed. Names may collide.
+     */
+    name: scheduleNameSchema.optional(),
     /**
      * The IANA timezone `cron` is read against. `UTC` when omitted.
      *
@@ -1024,30 +1407,15 @@ export const scheduleRequestSchema = z
             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"],
-            });
-        }
-    }
+    // **`onOverlap` is accepted wherever it is given, and ignored where it
+    // cannot apply** — a one-shot, or a run too short to outlast its own
+    // interval. It used to be refused in both cases, and the refusal became a
+    // trap: every stored schedule carries the default policy, the dashboard's
+    // editor sent it back on every save, and a five-second delivery was
+    // refused for a field nobody had touched, under a collapsed section. The
+    // operator's ruling on the W4-10 walk: "so what if it's not meaningful —
+    // then we ignore it." A policy that cannot fire is not a guarantee anyone
+    // can rely on, and the schedule's read reports what is stored.
     // 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
@@ -1067,6 +1435,20 @@ export const scheduleRequestSchema = z
         });
     }
 });
+/** Resolve the lateness settings a create or replacement request runs under. */
+export function deriveLatenessSettings(request) {
+    const recurrenceKind = request.cron !== undefined
+        ? "cron"
+        : request.everySeconds !== undefined
+            ? "every"
+            : "at";
+    const policy = request.lateness?.policy ??
+        defaultLatenessPolicyForRecurrence(recurrenceKind);
+    const maxStalenessSeconds = request.lateness?.maxStalenessSeconds;
+    return maxStalenessSeconds === undefined
+        ? { policy }
+        : { maxStalenessSeconds, policy };
+}
 /**
  * The delivery settings a request runs under: the caller's, or the defaults.
  *