@greatwait/contracts 0.3.1 → 0.3.3

package/dist/scheduling.d.ts

@@ -90,10 +90,21 @@ export declare function isTerminalScheduleStatus(status: ScheduleStatus): boolea
  */
 export declare const LATENCY_CLASSES: readonly ["realtime", "bulk"];
 export declare const latencyClassSchema: import("zod").ZodEnum<{
-    realtime: "realtime";
     bulk: "bulk";
+    realtime: "realtime";
 }>;
 export type LatencyClass = z.infer<typeof latencyClassSchema>;
+/**
+ * The service mode a request asks for (W12-02, FXO-3171): `auto`, or one of
+ * the concrete classes. Omission means `auto`. A read reports the concrete
+ * class an occurrence resolved to as `latencyClass`, and what was asked for as
+ * `requestedLatencyClass`; see `service-mode.ts` for the resolution.
+ */
+export declare const requestedLatencyClassSchema: import("zod").ZodEnum<{
+    bulk: "bulk";
+    realtime: "realtime";
+    auto: "auto";
+}>;
 /**
  * What happens when an occurrence reaches its first attempt after its planned
  * instant.
@@ -553,13 +564,11 @@ export declare const SCHEDULING_BOUNDS: {
      * 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.
+     * predates the PostgreSQL authority besides: the durable fact is a row.
      *
-     * 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.
+     * Since W13-03 there is no alarm at all. The Node runtime polls
+     * `core.occurrence` for rows whose `due_at` has passed, so a year-distant
+     * occurrence is the same row read on the same poll as a minute-distant one.
      *
      * Widening a bound is additive by `classifyChange` and narrowing it is
      * breaking, so this direction is the safe one to move in.
@@ -630,17 +639,15 @@ export declare const SCHEDULING_BOUNDS: {
      */
     readonly payloadBytes: 65536;
     /**
-     * How soon a one-shot has to be for `realtime` to be the class it gets by
-     * default, in seconds.
-     *
-     * Two minutes, which is the copied `validate.ts`'s own threshold kept rather
-     * than a number invented beside it: upstream classifies an `at` or a `delay`
-     * inside 120 seconds as realtime and everything else as bulk, on the
-     * reasoning that a wait that short is a human waiting on a screen. A caller
-     * who disagrees says so — `latencyClass` on the request is what makes this a
-     * default rather than a rule.
+     * How soon a one-shot has to be for `auto` to resolve it to `realtime`, in
+     * seconds, exclusive: a one-shot planned less than a minute after it was
+     * accepted is realtime, and one planned exactly a minute out is bulk
+     * (W12-02, FXO-3171; owner decision 2026-10-14). The single owner is
+     * `SERVICE_MODE_POLICY.autoRealtimeBelowMs`. A caller who disagrees says so
+     * — `latencyClass` on the request is what makes this a default rather than a
+     * rule.
      */
-    readonly realtimeOneShotSeconds: 120;
+    readonly realtimeOneShotSeconds: number;
 };
 /**
  * The longest cron expression this surface accepts, in characters.
@@ -778,9 +785,14 @@ export declare const scheduleSchema: import("zod").ZodObject<{
     generation: import("zod").ZodNumber;
     id: import("zod").ZodString;
     latencyClass: import("zod").ZodEnum<{
-        realtime: "realtime";
         bulk: "bulk";
+        realtime: "realtime";
     }>;
+    requestedLatencyClass: import("zod").ZodOptional<import("zod").ZodEnum<{
+        bulk: "bulk";
+        realtime: "realtime";
+        auto: "auto";
+    }>>;
     lateness: import("zod").ZodObject<{
         maxStalenessSeconds: import("zod").ZodOptional<import("zod").ZodNumber>;
         policy: import("zod").ZodEnum<{
@@ -880,9 +892,14 @@ export declare const schedulePageSchema: import("zod").ZodObject<{
         generation: import("zod").ZodNumber;
         id: import("zod").ZodString;
         latencyClass: import("zod").ZodEnum<{
-            realtime: "realtime";
             bulk: "bulk";
+            realtime: "realtime";
         }>;
+        requestedLatencyClass: import("zod").ZodOptional<import("zod").ZodEnum<{
+            bulk: "bulk";
+            realtime: "realtime";
+            auto: "auto";
+        }>>;
         lateness: import("zod").ZodObject<{
             maxStalenessSeconds: import("zod").ZodOptional<import("zod").ZodNumber>;
             policy: import("zod").ZodEnum<{
@@ -924,6 +941,68 @@ export declare const schedulePageSchema: import("zod").ZodObject<{
     nextCursor: import("zod").ZodOptional<import("zod").ZodString>;
 }, import("zod/v4/core").$strip>;
 export type SchedulePage = z.infer<typeof schedulePageSchema>;
+/** Local days a schedule summary covers, today included (W9-80, FXO-3446). */
+export declare const SCHEDULE_SUMMARY_DAYS = 30;
+/** Auto-paused schedules a summary names beside their count. */
+export declare const SCHEDULE_SUMMARY_PAUSED_SAMPLE = 5;
+/** The oldest a served schedule summary may be, in seconds. */
+export declare const SCHEDULE_SUMMARY_MAX_AGE_SECONDS = 300;
+/** A schedule summary request: the reader's time zone for the day buckets. */
+export declare const scheduleSummaryRequestSchema: import("zod").ZodObject<{
+    timeZone: import("zod").ZodDefault<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<string, string>>>;
+}, import("zod/v4/core").$strip>;
+export type ScheduleSummaryRequest = z.infer<typeof scheduleSummaryRequestSchema>;
+/**
+ * Whole-project schedule counts for the caller's project and environment
+ * (W9-80, FXO-3446).
+ *
+ * **Exact as of `freshness.asOf`, and at most five minutes old.** The counts
+ * read every retained, unarchived schedule in one statement, which is too
+ * costly to repeat on every view of a large project, so an answer is computed
+ * on read and reused for up to {@link SCHEDULE_SUMMARY_MAX_AGE_SECONDS}
+ * seconds per project, environment and time zone. `freshness` is always
+ * `projected`: `asOf` is when the counts were taken and `lagSeconds` how long
+ * ago that was, so a client can say "as of 2 minutes ago" rather than present
+ * the numbers as live. Counts cover retained schedules only: retention removes
+ * cancelled schedules and one-offs that ran once their history horizon passes.
+ */
+export declare const scheduleSummarySchema: import("zod").ZodObject<{
+    counts: import("zod").ZodObject<{
+        active: import("zod").ZodNumber;
+        paused: import("zod").ZodNumber;
+        completed: import("zod").ZodNumber;
+        cancelled: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+    pausedAfterFailures: import("zod").ZodObject<{
+        count: import("zod").ZodNumber;
+        schedules: import("zod").ZodArray<import("zod").ZodObject<{
+            id: import("zod").ZodString;
+            name: import("zod").ZodOptional<import("zod").ZodString>;
+            autoPauseReason: import("zod").ZodObject<{
+                failedRuns: import("zod").ZodNumber;
+                status: import("zod").ZodOptional<import("zod").ZodNumber>;
+                diagnostic: import("zod").ZodString;
+                pausedAt: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>;
+    days: import("zod").ZodArray<import("zod").ZodObject<{
+        date: import("zod").ZodString;
+        created: import("zod").ZodNumber;
+        finished: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>>;
+    window: import("zod").ZodObject<{
+        from: import("zod").ZodString;
+        to: import("zod").ZodString;
+        timeZone: import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<string, string>>;
+    }, import("zod/v4/core").$strip>;
+    freshness: import("zod").ZodObject<{
+        asOf: import("zod").ZodString;
+        kind: import("zod").ZodLiteral<"projected">;
+        lagSeconds: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+}, import("zod/v4/core").$strip>;
+export type ScheduleSummary = z.infer<typeof scheduleSummarySchema>;
 /**
  * One concrete occurrence of a schedule.
  *
@@ -937,6 +1016,7 @@ export declare const occurrenceSchema: import("zod").ZodObject<{
     id: import("zod").ZodString;
     plannedFor: import("zod").ZodString;
     schedule: import("zod").ZodString;
+    scheduleName: import("zod").ZodOptional<import("zod").ZodString>;
     sequence: import("zod").ZodNumber;
     settledAt: import("zod").ZodOptional<import("zod").ZodString>;
     state: import("zod").ZodEnum<{
@@ -1173,6 +1253,12 @@ export declare const attemptSchema: import("zod").ZodObject<{
         expired: "expired";
         not_captured: "not_captured";
     }>>;
+    requestUnavailable: import("zod").ZodOptional<import("zod").ZodEnum<{
+        schedule_changed: "schedule_changed";
+        endpoint_changed: "endpoint_changed";
+        endpoint_deleted: "endpoint_deleted";
+        payload_deleted: "payload_deleted";
+    }>>;
     responseHeaders: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
         name: import("zod").ZodString;
         value: import("zod").ZodString;
@@ -1228,6 +1314,7 @@ export declare const occurrencePageSchema: import("zod").ZodObject<{
         id: import("zod").ZodString;
         plannedFor: import("zod").ZodString;
         schedule: import("zod").ZodString;
+        scheduleName: import("zod").ZodOptional<import("zod").ZodString>;
         sequence: import("zod").ZodNumber;
         settledAt: import("zod").ZodOptional<import("zod").ZodString>;
         state: import("zod").ZodEnum<{
@@ -1265,6 +1352,7 @@ export declare const projectOccurrencePageSchema: import("zod").ZodObject<{
         id: import("zod").ZodString;
         plannedFor: import("zod").ZodString;
         schedule: import("zod").ZodString;
+        scheduleName: import("zod").ZodOptional<import("zod").ZodString>;
         sequence: import("zod").ZodNumber;
         settledAt: import("zod").ZodOptional<import("zod").ZodString>;
         state: import("zod").ZodEnum<{
@@ -1308,6 +1396,7 @@ export declare const occurrenceViewSchema: import("zod").ZodObject<{
         id: import("zod").ZodString;
         plannedFor: import("zod").ZodString;
         schedule: import("zod").ZodString;
+        scheduleName: import("zod").ZodOptional<import("zod").ZodString>;
         sequence: import("zod").ZodNumber;
         settledAt: import("zod").ZodOptional<import("zod").ZodString>;
         state: import("zod").ZodEnum<{
@@ -1399,6 +1488,12 @@ export declare const attemptPageSchema: import("zod").ZodObject<{
             expired: "expired";
             not_captured: "not_captured";
         }>>;
+        requestUnavailable: import("zod").ZodOptional<import("zod").ZodEnum<{
+            schedule_changed: "schedule_changed";
+            endpoint_changed: "endpoint_changed";
+            endpoint_deleted: "endpoint_deleted";
+            payload_deleted: "payload_deleted";
+        }>>;
         responseHeaders: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
             name: import("zod").ZodString;
             value: import("zod").ZodString;
@@ -1517,6 +1612,12 @@ export declare const attemptViewSchema: import("zod").ZodObject<{
             expired: "expired";
             not_captured: "not_captured";
         }>>;
+        requestUnavailable: import("zod").ZodOptional<import("zod").ZodEnum<{
+            schedule_changed: "schedule_changed";
+            endpoint_changed: "endpoint_changed";
+            endpoint_deleted: "endpoint_deleted";
+            payload_deleted: "payload_deleted";
+        }>>;
         responseHeaders: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
             name: import("zod").ZodString;
             value: import("zod").ZodString;
@@ -1583,6 +1684,7 @@ export declare const scheduleViewSchema: import("zod").ZodObject<{
         id: import("zod").ZodString;
         plannedFor: import("zod").ZodString;
         schedule: import("zod").ZodString;
+        scheduleName: import("zod").ZodOptional<import("zod").ZodString>;
         sequence: import("zod").ZodNumber;
         settledAt: import("zod").ZodOptional<import("zod").ZodString>;
         state: import("zod").ZodEnum<{
@@ -1663,9 +1765,14 @@ export declare const scheduleViewSchema: import("zod").ZodObject<{
         generation: import("zod").ZodNumber;
         id: import("zod").ZodString;
         latencyClass: import("zod").ZodEnum<{
-            realtime: "realtime";
             bulk: "bulk";
+            realtime: "realtime";
         }>;
+        requestedLatencyClass: import("zod").ZodOptional<import("zod").ZodEnum<{
+            bulk: "bulk";
+            realtime: "realtime";
+            auto: "auto";
+        }>>;
         lateness: import("zod").ZodObject<{
             maxStalenessSeconds: import("zod").ZodOptional<import("zod").ZodNumber>;
             policy: import("zod").ZodEnum<{
@@ -1711,6 +1818,7 @@ export declare const scheduleWrittenViewSchema: import("zod").ZodObject<{
         id: import("zod").ZodString;
         plannedFor: import("zod").ZodString;
         schedule: import("zod").ZodString;
+        scheduleName: import("zod").ZodOptional<import("zod").ZodString>;
         sequence: import("zod").ZodNumber;
         settledAt: import("zod").ZodOptional<import("zod").ZodString>;
         state: import("zod").ZodEnum<{
@@ -1791,9 +1899,14 @@ export declare const scheduleWrittenViewSchema: import("zod").ZodObject<{
         generation: import("zod").ZodNumber;
         id: import("zod").ZodString;
         latencyClass: import("zod").ZodEnum<{
-            realtime: "realtime";
             bulk: "bulk";
+            realtime: "realtime";
         }>;
+        requestedLatencyClass: import("zod").ZodOptional<import("zod").ZodEnum<{
+            bulk: "bulk";
+            realtime: "realtime";
+            auto: "auto";
+        }>>;
         lateness: import("zod").ZodObject<{
             maxStalenessSeconds: import("zod").ZodOptional<import("zod").ZodNumber>;
             policy: import("zod").ZodEnum<{
@@ -1905,8 +2018,9 @@ export declare const scheduleRequestSchema: import("zod").ZodObject<{
     endpoint: import("zod").ZodOptional<import("zod").ZodString>;
     url: import("zod").ZodOptional<import("zod").ZodString>;
     latencyClass: import("zod").ZodOptional<import("zod").ZodEnum<{
-        realtime: "realtime";
         bulk: "bulk";
+        realtime: "realtime";
+        auto: "auto";
     }>>;
     lateness: import("zod").ZodOptional<import("zod").ZodObject<{
         maxStalenessSeconds: import("zod").ZodOptional<import("zod").ZodNumber>;
@@ -1924,27 +2038,6 @@ export declare const scheduleRequestSchema: import("zod").ZodObject<{
 export type ScheduleRequest = z.infer<typeof scheduleRequestSchema>;
 /** Resolve the lateness settings a create or replacement request runs under. */
 export declare function deriveLatenessSettings(request: ScheduleRequest): LatenessSettings;
-/**
- * The class a request runs under: the caller's, or the one its recurrence
- * implies.
- *
- * **Retenanted from the copied `validate.ts` §9 defaulting**, which is the same
- * three rules in the same order — an explicit class wins; a `cron` or an
- * `every` is `bulk`; a one-shot is `realtime` when it is close and `bulk`
- * otherwise. What changes is only where the threshold is written down and that
- * a `delay` is measured against the clock the request arrived on rather than
- * read off a separate field, because this surface has already converted one
- * into the other by the time anything else looks at it.
- *
- * It lives here rather than in either adapter because REST and MCP must reach
- * the same class for the same body — the same reason `classifyIdempotency` is
- * here — and because a default that two surfaces derive separately is a default
- * they will eventually disagree about.
- *
- * `nowMs` is a parameter for the reason every clock in this package is: a rule
- * about "within two minutes" that reads its own clock cannot be asked what it
- * says one millisecond either side of the boundary.
- */
 /** Every delivery setting resolved, with nothing left optional. */
 export interface DeliverySettings {
     readonly completion: DeliveryCompletionMode;
@@ -1966,4 +2059,23 @@ export interface DeliverySettings {
  * is never still going — rather than something wrong.
  */
 export declare function deriveDeliverySettings(request: ScheduleRequest): DeliverySettings;
+/**
+ * The create request as its idempotency fingerprint reads it (W12-02).
+ *
+ * An omitted `latencyClass` means `auto`, so the two spellings are one request
+ * and must fingerprint alike. They are made alike by writing the default the
+ * way the request has always been able to write it — by omission — so a
+ * receipt issued before `auto` existed still recognizes its own retry.
+ */
+export declare function fingerprintedScheduleRequest(request: ScheduleRequest): ScheduleRequest;
+/**
+ * The concrete class a create request resolves to at `nowMs`, its acceptance
+ * time. Here so REST, MCP and the dashboard's preview reach the same answer
+ * for the same body; `service-mode.ts` owns the rule.
+ *
+ * A recurrence is classified by the gap between runs, at least a minute for
+ * anything this surface accepts, so `auto` makes it `bulk` without evaluating
+ * a cron expression here. `nowMs` is a parameter so the boundary can be asked
+ * about one millisecond either side of it.
+ */
 export declare function deriveLatencyClass(request: ScheduleRequest, nowMs: number): LatencyClass;