@greatwait/contracts 0.3.1 → 0.3.2

package/dist/scheduling.js

@@ -3,11 +3,13 @@ import { executionSelectionSchema, normalizeExecutionSelection, } from "./execut
 import { httpRequestSchema, publicHttpRequestSchema } from "./http-request.js";
 import { FIXED_INTERVAL_MIN_SECONDS, FIXED_INTERVAL_MAX_SECONDS, MAX_INLINE_PAYLOAD_BYTES, } from "./configuration-bounds.js";
 import { z } from "./zod.js";
+import { SERVICE_MODE_POLICY } from "./operational-config.js";
+import { REQUESTED_LATENCY_CLASSES, oneOffSpacingMs, resolveService, } from "./service-mode.js";
 import { externalIdentifierSchema, scheduleTagsSchema, } from "./host-correlation.js";
 import { attemptIdSchema, deliveryIdSchema, endpointIdSchema, occurrenceIdSchema, scheduleIdSchema, } from "./identifiers.js";
 import { CALLBACK_ATTEMPT_DIAGNOSTICS } from "./delivery.js";
 import { callbackUrlSchema, signingSecretNoticeSchema } from "./endpoints.js";
-import { pageRequestSchema, pageSchema, versionSchema, } from "./protocol.js";
+import { pageRequestSchema, pageSchema, projectedFreshnessSchema, versionSchema, } from "./protocol.js";
 import { callbackTriggerSchema, } from "./signatures.js";
 import { durationSecondsSchema, timeZoneSchema, timestampSchema } from "./time.js";
 /**
@@ -104,6 +106,13 @@ export function isTerminalScheduleStatus(status) {
  */
 export const LATENCY_CLASSES = ["realtime", "bulk"];
 export const latencyClassSchema = /* @__PURE__ */ (() => z.enum(LATENCY_CLASSES))();
+/**
+ * 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 const requestedLatencyClassSchema = /* @__PURE__ */ (() => z.enum(REQUESTED_LATENCY_CLASSES))();
 /**
  * What happens when an occurrence reaches its first attempt after its planned
  * instant.
@@ -612,13 +621,11 @@ export 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.
@@ -689,17 +696,15 @@ export const SCHEDULING_BOUNDS = {
      */
     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.
-     *
-     * 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.
      */
-    realtimeOneShotSeconds: 120,
+    realtimeOneShotSeconds: SERVICE_MODE_POLICY.autoRealtimeBelowMs / 1000,
 };
 /* -------------------------------------------------------------------------- */
 /* Recurrence                                                                 */
@@ -881,7 +886,18 @@ export const scheduleSchema = /* @__PURE__ */ (() => z.object({
     endpointUrl: z.string().url().optional(),
     generation: generationSchema,
     id: scheduleIdSchema,
+    /**
+     * The concrete class this schedule's occurrences are served and charged
+     * as: what `auto` resolved to, or the class the caller named.
+     */
     latencyClass: latencyClassSchema,
+    /**
+     * The mode the caller asked for (W12-02): `auto` when the request named
+     * none. Absent on a schedule accepted before the mode was recorded; its
+     * `latencyClass` is what it was accepted as, and a replacement that leaves
+     * its timing alone keeps it.
+     */
+    requestedLatencyClass: requestedLatencyClassSchema.optional(),
     /**
      * 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
@@ -946,6 +962,76 @@ export const scheduleSchema = /* @__PURE__ */ (() => z.object({
  * is authoritative, and detail is one call away.
  */
 export const schedulePageSchema = /* @__PURE__ */ (() => pageSchema(scheduleSchema))();
+/** Local days a schedule summary covers, today included (W9-80, FXO-3446). */
+export const SCHEDULE_SUMMARY_DAYS = 30;
+/** Auto-paused schedules a summary names beside their count. */
+export const SCHEDULE_SUMMARY_PAUSED_SAMPLE = 5;
+/** The oldest a served schedule summary may be, in seconds. */
+export const SCHEDULE_SUMMARY_MAX_AGE_SECONDS = 300;
+const localDateSchema = /* @__PURE__ */ (() => z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/u, "must be a calendar date, YYYY-MM-DD"))();
+/** A schedule summary request: the reader's time zone for the day buckets. */
+export const scheduleSummaryRequestSchema = /* @__PURE__ */ (() => z.object({
+    timeZone: timeZoneSchema
+        .default("UTC")
+        .describe("IANA time zone the per-day buckets are counted in; defaults to UTC."),
+}))();
+/**
+ * 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 const scheduleSummarySchema = /* @__PURE__ */ (() => z.object({
+    counts: z.object({
+        active: z.number().int().nonnegative(),
+        paused: z.number().int().nonnegative(),
+        completed: z.number().int().nonnegative(),
+        cancelled: z.number().int().nonnegative(),
+    }),
+    /**
+     * Paused schedules whose newest run paused them after repeated failures,
+     * and up to five of them (id, name and why), most recently paused first.
+     * Read a schedule, or list `status=paused`, for the rest.
+     */
+    pausedAfterFailures: z.object({
+        count: z.number().int().nonnegative(),
+        schedules: z
+            .array(z.object({
+            id: scheduleIdSchema,
+            name: z.string().optional(),
+            autoPauseReason: autoPauseReasonSchema,
+        }))
+            .max(SCHEDULE_SUMMARY_PAUSED_SAMPLE),
+    }),
+    /**
+     * One entry per local day of the window, oldest first, zero days
+     * included: schedules created that day, and schedules that finished that
+     * day (completed by their final run, or cancelled).
+     */
+    days: z
+        .array(z.object({
+        date: localDateSchema,
+        created: z.number().int().nonnegative(),
+        finished: z.number().int().nonnegative(),
+    }))
+        .length(SCHEDULE_SUMMARY_DAYS),
+    window: z.object({
+        from: localDateSchema,
+        to: localDateSchema,
+        timeZone: timeZoneSchema,
+    }),
+    freshness: projectedFreshnessSchema,
+}))();
 function hasCompleteTimingEvidence(value) {
     return ((value.firstAttemptStartedAt === undefined) ===
         (value.firstAttemptLatenessMs === undefined) &&
@@ -970,7 +1056,12 @@ const timingEvidenceShape = {
         .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(),
+    timingPolicyVersion: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("Timing policy pinned with trusted first-outbound evidence. Banded occurrences use timing-v2-service-bands (realtime 1000ms, short bulk 10000ms, bulk 60000ms from plannedFor); legacy occurrences without a band retain their recorded policy, including payg-v1, and 5000ms/15000ms thresholds. Absent timing evidence means unknown."),
 };
 /**
  * One concrete occurrence of a schedule.
@@ -989,6 +1080,13 @@ export const occurrenceSchema = /* @__PURE__ */ (() => z
     /** When the occurrence was planned to fire. Never earlier than this. */
     plannedFor: timestampSchema,
     schedule: scheduleIdSchema,
+    /**
+     * The schedule's name, on the project executions listing
+     * (`executions.list`) only, read from the same schedule rows that page
+     * already joins — so a list of runs can say whose they are without a
+     * schedule read per row (W9-80). Absent elsewhere.
+     */
+    scheduleName: z.string().optional(),
     sequence: z.number().int().positive(),
     /** Present exactly when the occurrence is in a terminal state. */
     settledAt: timestampSchema.optional(),
@@ -1151,6 +1249,22 @@ export const attemptSchema = /* @__PURE__ */ (() => z
     response: attemptResponseSchema.optional(),
     request: attemptRequestSchema.optional(),
     requestState: z.enum(["captured", "expired", "not_captured"]).optional(),
+    /**
+     * Why a successful attempt's request cannot be shown, when
+     * `requestState` is `not_captured` for that reason. A successful
+     * attempt's request is rebuilt from the schedule's payload and its
+     * endpoint, so it is shown only while neither has changed since the run
+     * and the payload still exists; it is never shown from a later version.
+     * Absent otherwise.
+     */
+    requestUnavailable: z
+        .enum([
+        "schedule_changed",
+        "endpoint_changed",
+        "endpoint_deleted",
+        "payload_deleted",
+    ])
+        .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. */
@@ -1372,20 +1486,27 @@ export const scheduleRequestSchema = /* @__PURE__ */ (() => z
      */
     url: callbackUrlSchema().optional(),
     /**
-     * How promptly this schedule's occurrences expect to be served.
+     * How promptly this schedule's occurrences expect to be served: `auto`,
+     * `bulk` or `realtime` (W12-02, FXO-3171).
      *
-     * Optional, and omitting it is the ordinary case: the default is derived
-     * from how the schedule recurs (`deriveLatencyClass`). Stating it is for
+     * Omitting it means `auto`, the ordinary case. `auto` makes a one-shot
+     * planned less than a minute after acceptance `realtime` and everything
+     * else `bulk`; a recurrence is classified by the gap between its runs, so
+     * it is `bulk`. Naming `realtime` or `bulk` always gets that class — 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.
+     * thirty-second one-shot really is a campaign.
      *
-     * 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.
+     * Bulk work becomes eligible on a 5-second boundary when its runs are
+     * under five minutes apart (or it is due within five minutes) and on a
+     * 50-second boundary otherwise; realtime on a 250-millisecond boundary.
+     * The occurrence's `plannedFor` is unchanged. Each occurrence is charged
+     * as the class it resolved to.
+     *
+     * On a replacement, omission keeps the schedule's mode. Changing the
+     * timing resolves again under that mode; changing anything else keeps
+     * the class and price the schedule was accepted under.
      */
-    latencyClass: latencyClassSchema.optional(),
+    latencyClass: requestedLatencyClassSchema.optional(),
     /**
      * What to do when an occurrence reaches its first attempt late.
      *
@@ -1540,29 +1661,46 @@ export function deriveDeliverySettings(request) {
         onOverlap: request.delivery?.onOverlap ?? DEFAULT_DELIVERY_OVERLAP_POLICY,
     };
 }
+/**
+ * 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 function fingerprintedScheduleRequest(request) {
+    if (request.latencyClass !== "auto")
+        return request;
+    const { latencyClass: _auto, ...rest } = request;
+    void _auto;
+    return rest;
+}
+/**
+ * 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 function deriveLatencyClass(request, nowMs) {
-    if (request.latencyClass !== undefined) {
-        return request.latencyClass;
-    }
+    const requested = request.latencyClass ?? "auto";
     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";
+        return resolveService(requested, request.everySeconds === undefined
+            ? SCHEDULING_BOUNDS.everySecondsMin * 1000
+            : request.everySeconds * 1000).latencyClass;
     }
-    // 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";
+    const atMs = request.delaySeconds !== undefined
+        ? nowMs + request.delaySeconds * 1000
+        : request.at === undefined
+            ? Number.NaN
+            : Date.parse(request.at);
+    // No instant at all, which the schema refuses before this is reached, is
+    // answered conservatively rather than thrown.
+    return Number.isNaN(atMs)
+        ? resolveService(requested, Infinity).latencyClass
+        : resolveService(requested, oneOffSpacingMs(nowMs, atMs)).latencyClass;
 }

package/dist/service-mode.d.ts

@@ -0,0 +1,88 @@
+/** The modes a request may name. `auto` is what omission means. */
+export declare const REQUESTED_LATENCY_CLASSES: readonly ["auto", "bulk", "realtime"];
+export type RequestedLatencyClass = (typeof REQUESTED_LATENCY_CLASSES)[number];
+/** The concrete services an occurrence resolves to. */
+export type ResolvedLatencyClass = "bulk" | "realtime";
+/** The internal bands. Not on the wire: only the concrete service is. */
+export declare const SERVICE_BANDS: readonly ["realtime", "short_bulk", "bulk"];
+export type ServiceBand = (typeof SERVICE_BANDS)[number];
+export interface ServiceResolution {
+    readonly band: ServiceBand;
+    readonly latencyClass: ResolvedLatencyClass;
+    readonly quantumMs: number;
+}
+/** The concrete service a band is charged and reported as. */
+export declare function bandLatencyClass(band: ServiceBand): ResolvedLatencyClass;
+/**
+ * The service, band and quantum for one occurrence.
+ *
+ * `spacingMs` is the one-off lead or the recurrence's shorter adjacent gap
+ * (see the module comment). A non-finite spacing — a recurrence with no
+ * adjacent instant — is treated as long.
+ */
+export declare function resolveService(requested: RequestedLatencyClass, spacingMs: number): ServiceResolution;
+/** A one-off's lead: planned instant minus the captured acceptance time. */
+export declare function oneOffSpacingMs(acceptedAtMs: number, plannedForMs: number): number;
+/**
+ * A recurrence occurrence's shorter adjacent planned gap. Either neighbour may
+ * be unknown — a series' first occurrence has no predecessor — and the gap to
+ * a known neighbour decides alone.
+ */
+export declare function recurrenceSpacingMs(previousMs: number | undefined, plannedForMs: number, nextMs: number | undefined): number;
+/**
+ * An instant's first eligibility in its band: `ceil(instant / quantum) *
+ * quantum`, so a boundary stays where it is.
+ *
+ * Applied once, to the planned instant or to a retry's backed-off instant.
+ * Work that becomes claimable late is claimable now, never at another
+ * boundary: nothing rounds a rounded instant, and nothing rounds `now`. The
+ * last quantum of year 9999 has no boundary the contract can name, so it is
+ * eligible at the end of that year instead.
+ */
+export declare function roundEligibilityMs(instantMs: number, band: ServiceBand): number;
+export interface OccurrenceResolution extends ServiceResolution {
+    /** `plannedForMs` rounded up to the band's quantum. */
+    readonly eligibleAtMs: number;
+}
+/**
+ * One occurrence's service, band and rounded first eligibility: the entry
+ * point create, replacement and a recurrence's successor all use.
+ *
+ * A one-off is measured from its captured acceptance time; a recurrence by its
+ * neighbours, which the caller took from the existing recurrence evaluator.
+ */
+export declare function resolveOccurrence(input: {
+    readonly kind: "one-off";
+    readonly requested: RequestedLatencyClass;
+    readonly acceptedAtMs: number;
+    readonly plannedForMs: number;
+} | {
+    readonly kind: "recurring";
+    readonly requested: RequestedLatencyClass;
+    readonly plannedForMs: number;
+    readonly previousMs?: number;
+    readonly nextMs?: number;
+}): OccurrenceResolution;
+/** Stored requested intent; `legacy` predates recording it (W12-02). */
+export type StoredRequestedLatencyClass = RequestedLatencyClass | "legacy";
+/**
+ * What a replacement runs under (implementation-guide § W02, step 4).
+ *
+ * - A request naming a mode other than the stored one is a mode edit.
+ * - A timing or cadence edit resolves again. An explicit stored mode survives
+ *   it; a legacy schedule's enters `auto`.
+ * - Anything else — payload, headers, name, tags, a mode named as it already
+ *   was — preserves the stored service and tariff, and a legacy schedule stays
+ *   legacy.
+ */
+export declare function replacementMode(input: {
+    readonly stored: StoredRequestedLatencyClass;
+    readonly requested: RequestedLatencyClass | undefined;
+    readonly timingChanged: boolean;
+}): {
+    readonly kind: "preserve";
+    readonly requested: StoredRequestedLatencyClass;
+} | {
+    readonly kind: "resolve";
+    readonly requested: RequestedLatencyClass;
+};

package/dist/service-mode.js

@@ -0,0 +1,130 @@
+/**
+ * W12-02 (FXO-3171): the one resolver for service modes.
+ *
+ * Design: docs/archive/warm-worker-scheduling/project-spec.md § Customer
+ * contract, and implementation-guide.md § W02. A request names a mode —
+ * `auto`, `bulk` or `realtime` — and every occurrence resolves to a concrete
+ * service (`bulk` or `realtime`, what is charged and what a read reports), an
+ * internal band (`realtime`, `short_bulk` or `bulk`) and that band's quantum.
+ *
+ * Pure: every input is a parameter, nothing here reads a clock, and the
+ * spacing it classifies by is measured by the caller from instants the
+ * existing recurrence evaluator produced. There is deliberately no cron
+ * arithmetic in this module: a second evaluator is a second opinion about when
+ * a schedule fires, and two opinions eventually disagree.
+ *
+ * The spacing is:
+ *
+ * - for a one-off, the lead from the captured acceptance time to the original
+ *   planned instant (an instant already past has no lead), measured once at
+ *   acceptance — a replayed request reads the stored answer and never measures
+ *   again; and
+ * - for a recurrence, the shorter adjacent planned gap. A one-minute heartbeat
+ *   is short bulk however soon its next run happens to be due.
+ *
+ * Every recurrence the product accepts is at least a minute apart — `every`
+ * starts at sixty seconds and cron names whole minutes — so `auto` never
+ * resolves a recurrence to `realtime`, and an occurrence's service is the
+ * schedule's for its whole series. Only the band moves with irregular gaps.
+ */
+import { SERVICE_MODE_POLICY } from "./operational-config.js";
+/** The modes a request may name. `auto` is what omission means. */
+export const REQUESTED_LATENCY_CLASSES = ["auto", "bulk", "realtime"];
+/** The internal bands. Not on the wire: only the concrete service is. */
+export const SERVICE_BANDS = ["realtime", "short_bulk", "bulk"];
+/** The concrete service a band is charged and reported as. */
+export function bandLatencyClass(band) {
+    return band === "realtime" ? "realtime" : "bulk";
+}
+/**
+ * The service, band and quantum for one occurrence.
+ *
+ * `spacingMs` is the one-off lead or the recurrence's shorter adjacent gap
+ * (see the module comment). A non-finite spacing — a recurrence with no
+ * adjacent instant — is treated as long.
+ */
+export function resolveService(requested, spacingMs) {
+    const spacing = Number.isNaN(spacingMs) ? Infinity : Math.max(0, spacingMs);
+    const band = requested === "realtime" ||
+        (requested === "auto" && spacing < SERVICE_MODE_POLICY.autoRealtimeBelowMs)
+        ? "realtime"
+        : spacing < SERVICE_MODE_POLICY.shortBulkBelowMs
+            ? "short_bulk"
+            : "bulk";
+    return {
+        band,
+        latencyClass: bandLatencyClass(band),
+        quantumMs: SERVICE_MODE_POLICY.quantumMs[band],
+    };
+}
+/** A one-off's lead: planned instant minus the captured acceptance time. */
+export function oneOffSpacingMs(acceptedAtMs, plannedForMs) {
+    return plannedForMs - acceptedAtMs;
+}
+/**
+ * A recurrence occurrence's shorter adjacent planned gap. Either neighbour may
+ * be unknown — a series' first occurrence has no predecessor — and the gap to
+ * a known neighbour decides alone.
+ */
+export function recurrenceSpacingMs(previousMs, plannedForMs, nextMs) {
+    const gaps = [
+        previousMs === undefined ? Infinity : plannedForMs - previousMs,
+        nextMs === undefined ? Infinity : nextMs - plannedForMs,
+    ].filter((gap) => gap > 0);
+    return gaps.length === 0 ? Infinity : Math.min(...gaps);
+}
+/** The last instant the contract's four-digit-year timestamps express. */
+const LATEST_EXPRESSIBLE_MS = Date.parse("9999-12-31T23:59:59.999Z");
+/**
+ * An instant's first eligibility in its band: `ceil(instant / quantum) *
+ * quantum`, so a boundary stays where it is.
+ *
+ * Applied once, to the planned instant or to a retry's backed-off instant.
+ * Work that becomes claimable late is claimable now, never at another
+ * boundary: nothing rounds a rounded instant, and nothing rounds `now`. The
+ * last quantum of year 9999 has no boundary the contract can name, so it is
+ * eligible at the end of that year instead.
+ */
+export function roundEligibilityMs(instantMs, band) {
+    const quantum = SERVICE_MODE_POLICY.quantumMs[band];
+    return Math.min(Math.ceil(instantMs / quantum) * quantum, Math.max(instantMs, LATEST_EXPRESSIBLE_MS));
+}
+/**
+ * One occurrence's service, band and rounded first eligibility: the entry
+ * point create, replacement and a recurrence's successor all use.
+ *
+ * A one-off is measured from its captured acceptance time; a recurrence by its
+ * neighbours, which the caller took from the existing recurrence evaluator.
+ */
+export function resolveOccurrence(input) {
+    const spacing = input.kind === "one-off"
+        ? oneOffSpacingMs(input.acceptedAtMs, input.plannedForMs)
+        : recurrenceSpacingMs(input.previousMs, input.plannedForMs, input.nextMs);
+    const resolution = resolveService(input.requested, spacing);
+    return {
+        ...resolution,
+        eligibleAtMs: roundEligibilityMs(input.plannedForMs, resolution.band),
+    };
+}
+/**
+ * What a replacement runs under (implementation-guide § W02, step 4).
+ *
+ * - A request naming a mode other than the stored one is a mode edit.
+ * - A timing or cadence edit resolves again. An explicit stored mode survives
+ *   it; a legacy schedule's enters `auto`.
+ * - Anything else — payload, headers, name, tags, a mode named as it already
+ *   was — preserves the stored service and tariff, and a legacy schedule stays
+ *   legacy.
+ */
+export function replacementMode(input) {
+    if (input.requested !== undefined && input.requested !== input.stored) {
+        return { kind: "resolve", requested: input.requested };
+    }
+    if (input.timingChanged) {
+        return {
+            kind: "resolve",
+            requested: input.stored === "legacy" ? "auto" : input.stored,
+        };
+    }
+    return { kind: "preserve", requested: input.stored };
+}

package/dist/tenancy.d.ts

@@ -133,20 +133,19 @@ export declare const provisionedProjectSchema: import("zod").ZodObject<{
     }, import("zod/v4/core").$strip>;
 }, import("zod/v4/core").$strip>;
 export type ProvisionedProject = z.infer<typeof provisionedProjectSchema>;
+/** Exactly what a permanent deletion of the project would destroy now. */
+export declare const projectDeletionCountsSchema: import("zod").ZodObject<{
+    endpoints: import("zod").ZodNumber;
+    keys: import("zod").ZodNumber;
+    runs: import("zod").ZodNumber;
+    schedules: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>;
 /**
- * What a signed-in member is told about a project they may act in.
+ * One project, with the exact counts a permanent deletion would destroy now.
  *
- * **Not `provisionedProjectSchema`, deliberately.** That shape carries
- * `organization`, `status`, `version` and both environment *identifiers*, and
- * publishing environment ids would make them public names — while nothing on
- * `/v1` takes one: every operation that names an environment names its
- * `kind`. Publishing an identifier no operation accepts invites a client to
- * build on it and then constrains us to keep it.
- *
- * This remains a display aid rather than an authorization control. Whatever the
- * list shows, the authority for a request is re-resolved from the member's
- * organization when the request arrives. Lifecycle state and version make an
- * archived row manageable without making it a valid work target.
+ * Returned by the single-project read (`projects.read`) and by the writes that
+ * answer with the project they changed. Never by the list: see
+ * `projectListItemSchema`.
  */
 export declare const projectSummarySchema: import("zod").ZodObject<{
     createdAt: import("zod").ZodNullable<import("zod").ZodString>;
@@ -169,12 +168,43 @@ export declare const projectSummarySchema: import("zod").ZodObject<{
     version: import("zod").ZodNumber;
 }, import("zod/v4/core").$strip>;
 export type ProjectSummary = z.infer<typeof projectSummarySchema>;
-export declare const projectDeletionCountsSchema: import("zod").ZodObject<{
-    endpoints: import("zod").ZodNumber;
-    keys: import("zod").ZodNumber;
-    runs: import("zod").ZodNumber;
-    schedules: import("zod").ZodNumber;
+/**
+ * What a signed-in member is told about a project they may act in.
+ *
+ * **Not `provisionedProjectSchema`, deliberately.** That shape carries
+ * `organization`, `status`, `version` and both environment *identifiers*, and
+ * publishing environment ids would make them public names — while nothing on
+ * `/v1` takes one: every operation that names an environment names its
+ * `kind`. Publishing an identifier no operation accepts invites a client to
+ * build on it and then constrains us to keep it.
+ *
+ * This remains a display aid rather than an authorization control. Whatever the
+ * list shows, the authority for a request is re-resolved from the member's
+ * organization when the request arrives. Lifecycle state and version make an
+ * archived row manageable without making it a valid work target.
+ *
+ * **No deletion counts (W9-88).** Counting a project's schedules and runs
+ * reads every one of them, so a list that counted every project cost the sum
+ * of the organization's whole history — 2.2 s for an organization with
+ * 290,000 schedules, longer than the API's pool would wait, and the landing
+ * page failed every time. Exact counts are a deletion preview; they belong to
+ * the one project somebody is about to delete: `projectSummarySchema`.
+ */
+export declare const projectListItemSchema: import("zod").ZodObject<{
+    status: import("zod").ZodEnum<{
+        active: "active";
+        archived: "archived";
+    }>;
+    name: import("zod").ZodString;
+    version: import("zod").ZodNumber;
+    id: import("zod").ZodString;
+    createdAt: import("zod").ZodNullable<import("zod").ZodString>;
+    environmentKinds: import("zod").ZodArray<import("zod").ZodEnum<{
+        test: "test";
+        live: "live";
+    }>>;
 }, import("zod/v4/core").$strip>;
+export type ProjectListItem = z.infer<typeof projectListItemSchema>;
 export type ProjectDeletionCounts = z.infer<typeof projectDeletionCountsSchema>;
 /**
  * Every active or archived project the member can access. Administrators see all.
@@ -190,24 +220,18 @@ export type ProjectDeletionCounts = z.infer<typeof projectDeletionCountsSchema>;
 export declare const PROJECT_LIST_LIMIT = 200;
 export declare const projectListSchema: import("zod").ZodObject<{
     data: import("zod").ZodArray<import("zod").ZodObject<{
-        createdAt: import("zod").ZodNullable<import("zod").ZodString>;
-        deletionCounts: import("zod").ZodObject<{
-            endpoints: import("zod").ZodNumber;
-            keys: import("zod").ZodNumber;
-            runs: import("zod").ZodNumber;
-            schedules: import("zod").ZodNumber;
-        }, import("zod/v4/core").$strip>;
-        environmentKinds: import("zod").ZodArray<import("zod").ZodEnum<{
-            test: "test";
-            live: "live";
-        }>>;
-        id: import("zod").ZodString;
-        name: import("zod").ZodString;
         status: import("zod").ZodEnum<{
             active: "active";
             archived: "archived";
         }>;
+        name: import("zod").ZodString;
         version: import("zod").ZodNumber;
+        id: import("zod").ZodString;
+        createdAt: import("zod").ZodNullable<import("zod").ZodString>;
+        environmentKinds: import("zod").ZodArray<import("zod").ZodEnum<{
+            test: "test";
+            live: "live";
+        }>>;
     }, import("zod/v4/core").$strip>>;
     total: import("zod").ZodNumber;
 }, import("zod/v4/core").$strip>;