@greatwait/contracts 0.1.0-alpha.1

package/dist/forecast.js

@@ -0,0 +1,729 @@
+import { z } from "zod";
+import { freshnessSchema, projectedFreshnessSchema, } from "./protocol.js";
+import { timestampSchema } from "./time.js";
+/**
+ * What is about to happen, in bounded time buckets.
+ *
+ * A capacity planner asks one question — how much work is coming, and when —
+ * and the answer has to be bounded in three directions at once: the horizon it
+ * covers, the number of buckets it returns, and the work the service does to
+ * compute it. Architecture section 13 lists the forecast horizon among the cost
+ * controls for exactly that reason.
+ *
+ * **`owner` appears nowhere.** The copied service answered
+ * `/v1/analytics/:owner/forecast` and trusted the segment; here the authority
+ * tuple comes from the verified principal as it does everywhere else, and a
+ * legacy `owner` is a W6 migration input rather than authorization.
+ */
+/* -------------------------------------------------------------------------- */
+/* Bounds                                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * The bounds a forecast is served under.
+ *
+ * The horizon, the finest bucket and the slack below `now` are **the copied
+ * `ForecastCache`'s numbers, kept rather than re-derived**: 25 hours, 60-second
+ * buckets, 120 seconds of slack. That file says why — the horizon must exceed
+ * the largest served window plus the maximum staleness so a sliding window
+ * stays covered between refreshes, and 25 hours comfortably covers a 24-hour
+ * poll. Re-choosing them here would have discarded a tuning that arrived
+ * proven.
+ *
+ * `maxBuckets` is the one bound that is ours, and it is arithmetic rather than
+ * taste: the longest window over the finest bucket is 1,500 buckets, so stating
+ * it makes the response size bounded by a calculation instead of by hope.
+ */
+export const FORECAST_BOUNDS = {
+    defaultBucketSeconds: 30 * 60,
+    /** Window served when a caller names neither `from` nor `to`. */
+    defaultWindowSeconds: 24 * 60 * 60,
+    maxBucketSeconds: 24 * 60 * 60,
+    /** `maxWindowSeconds / minBucketSeconds`, so the size is arithmetic. */
+    maxBuckets: 1_500,
+    /**
+     * Distinct `(minute, latencyClass, partitionKey)` groups one partition may
+     * aggregate before it reports the answer as short.
+     */
+    maxGroupsPerPartition: 100_000,
+    /**
+     * How stale an answer may be before it is refused rather than served.
+     *
+     * Twice the partition's own refresh ceiling, so a healthy answer never trips
+     * it and a broken one always does. It exists because the consumer this shape
+     * was measured against reads `count` and not `freshness`: a live-but-badly-
+     * stale 200 is indistinguishable, to it, from a fresh one, and the whole
+     * argument for refusing rather than under-reporting collapses if staleness is
+     * the one degradation that gets through as a number.
+     */
+    maxLagSeconds: 600,
+    /**
+     * Instants one partition may project into a single snapshot before it reports
+     * the answer as short.
+     *
+     * Published rather than kept internal so a refusal is classifiable: a shadow
+     * comparison that sees a refusal needs to be able to tell "we are near a
+     * stated bound" from "something is broken".
+     */
+    maxProjectedOccurrencesPerPartition: 20_000,
+    /** Recurring series one partition may project from in a single snapshot. */
+    maxRecurringSeriesPerPartition: 20_000,
+    /**
+     * How far ahead of `now` a forecast may look.
+     *
+     * The copied cache's `DEFAULT_FORECAST_CACHE_HORIZON_SECONDS`. A window
+     * reaching past it cannot be served from a snapshot taken at `now`, and the
+     * legacy service's seven-day ceiling bounded the *query* with no snapshot
+     * behind it at all.
+     */
+    maxWindowSeconds: 25 * 60 * 60,
+    minBucketSeconds: 60,
+    /**
+     * Longest a partition lets its snapshot stand when nothing has been written.
+     *
+     * Published because it is the honest answer to "how out of date can this be",
+     * and a caller who has to discover that by experiment will discover it during
+     * an incident. `freshness.lagSeconds` reports the actual age on every answer;
+     * this is the bound it lives inside.
+     */
+    refreshCeilingSeconds: 300,
+    /**
+     * Shortest gap between refreshes once something *has* been written.
+     *
+     * So a caller who has just created or cancelled a schedule knows when it will
+     * appear: within this, not instantly. A forecast is a projection, and a
+     * projection that rebuilt on every poll would be the cost this whole design
+     * exists to avoid.
+     */
+    refreshFloorSeconds: 30,
+    /**
+     * How far below `now` a window may begin.
+     *
+     * The copied cache's `DEFAULT_FORECAST_CACHE_SLACK_SECONDS`, kept for its
+     * reason: it absorbs the skew between a caller's clock and ours, so the
+     * ordinary request — "from now, for six hours" — does not fail intermittently
+     * because the caller's `now` is a second behind. Further back than that is a
+     * question about the past, which a forecast does not answer.
+     */
+    slackSeconds: 120,
+    /**
+     * Customer keys named individually in one bucket before the rest are summed.
+     *
+     * The copied route's `FORECAST_TOP_TENANTS`. A customer's key space is
+     * unbounded by design, so a breakdown naming every key would let one caller
+     * decide the size of our response.
+     */
+    topPartitionKeys: 10,
+};
+/* -------------------------------------------------------------------------- */
+/* Request                                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * Whether the answer carries a per-customer-key breakdown.
+ *
+ * Off by default. The breakdown is the axis whose size a caller controls — a
+ * bucket's payload grows with how many keys fired in it — and most callers want
+ * the total and the latency split, which every answer carries.
+ */
+export const FORECAST_BREAKDOWNS = ["none", "partitionKey"];
+export const forecastBreakdownSchema = z.enum(FORECAST_BREAKDOWNS);
+export const forecastRequestSchema = z.object({
+    breakdown: forecastBreakdownSchema.default("none"),
+    /**
+     * Bucket width in whole seconds, aligned to the epoch.
+     *
+     * Seconds as a number rather than the legacy `bucket=30m` duration string:
+     * "durations are whole seconds as numbers" is the convention this product
+     * publishes, and a second spelling of a duration is a second thing to get
+     * wrong.
+     */
+    bucketSeconds: z
+        .number()
+        .int()
+        .min(FORECAST_BOUNDS.minBucketSeconds)
+        .max(FORECAST_BOUNDS.maxBucketSeconds)
+        // A whole number of the finest bucket, so re-aggregating the internal
+        // minute-granular snapshot into the requested width is exact rather than
+        // best-effort. The copied cache says of itself that it is exact only when
+        // the width is a multiple of sixty and best-effort otherwise; that was
+        // forced on it by callers who could ask for a width that straddled, and
+        // refusing such a width is cheaper than publishing an approximate capacity
+        // number nobody can reconcile against a bill.
+        .multipleOf(FORECAST_BOUNDS.minBucketSeconds)
+        .default(FORECAST_BOUNDS.defaultBucketSeconds),
+    /** Inclusive lower bound. Defaults to the instant the request is served. */
+    from: timestampSchema.optional(),
+    /** Exclusive upper bound. Defaults to `from` plus the default window. */
+    to: timestampSchema.optional(),
+});
+/** `[name, numeric]` — the coercion each parameter needs off a URL. */
+const FORECAST_PARAMETERS = [
+    ["breakdown", false],
+    ["bucketSeconds", true],
+    ["from", false],
+    ["to", false],
+];
+function asNumberIfInteger(value) {
+    return /^-?\d+$/u.test(value) ? Number(value) : value;
+}
+/**
+ * Reads a forecast request off a URL.
+ *
+ * Values arrive as strings, so the coercion lives here rather than in every
+ * adapter — the reason `parsePageRequest` exists. A repeated parameter is a
+ * refusal rather than a last-one-wins guess: two different windows in one
+ * request is a caller bug, and answering one of them silently is how it stays a
+ * bug.
+ */
+export function parseForecastRequest(query) {
+    const errors = [];
+    const raw = {};
+    for (const [field, numeric] of FORECAST_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] = numeric ? asNumberIfInteger(value) : value;
+    }
+    if (errors.length > 0) {
+        return { errors, ok: false };
+    }
+    const parsed = forecastRequestSchema.safeParse(raw);
+    if (parsed.success) {
+        return { ok: true, request: parsed.data };
+    }
+    return {
+        errors: parsed.error.issues.map((issue) => ({
+            pointer: `/${issue.path.join("/")}`,
+            reason: issue.message,
+        })),
+        ok: false,
+    };
+}
+/**
+ * Turns a parsed request into the window that will be served, or says why not.
+ *
+ * Separate from the schema because every refusal here is a relation between two
+ * fields rather than a property of one, and a refinement that fails on the
+ * object cannot say which field to point at.
+ *
+ * **The horizon is measured from `now`, not from `from`.** A caller asking for
+ * a window that starts tomorrow and ends the day after is asking for something
+ * no snapshot taken now can cover; answering it from a snapshot that stops at
+ * 25 hours would be a confident wrong answer rather than a refusal.
+ */
+export function resolveForecastWindow(request, nowMs) {
+    const fromMs = request.from === undefined ? nowMs : Date.parse(request.from);
+    const toMs = request.to === undefined
+        ? fromMs + FORECAST_BOUNDS.defaultWindowSeconds * 1000
+        : Date.parse(request.to);
+    if (toMs <= fromMs) {
+        return { ok: false, refusal: "range-empty" };
+    }
+    if (toMs - fromMs > FORECAST_BOUNDS.maxWindowSeconds * 1000) {
+        return { ok: false, refusal: "range-too-long" };
+    }
+    if (fromMs < nowMs - FORECAST_BOUNDS.slackSeconds * 1000) {
+        return { ok: false, refusal: "window-in-the-past" };
+    }
+    if (toMs > nowMs + FORECAST_BOUNDS.maxWindowSeconds * 1000) {
+        return { ok: false, refusal: "window-past-horizon" };
+    }
+    // **There is deliberately no bucket-count refusal here.** `maxBuckets` is the
+    // longest window over the finest bucket *exactly*, so a request the checks
+    // above admit can never produce more buckets than it — a guard for it would
+    // be a branch nothing could reach, which reads as though it covers something
+    // and does not. `forecast.test.ts` holds the two bounds in that relation, so
+    // widening the window without widening the bound fails a test rather than
+    // quietly removing the ceiling on a response's size.
+    // **Snapped to the finest bucket, and the snapped window is what the answer
+    // reports.** A forecast is served from a snapshot held at minute
+    // granularity — the copied cache's design and its reason — so a window whose
+    // edges fall inside a minute cannot be answered exactly. The copy resolved
+    // that by filtering on bucket starts and calling the edges best-effort; here
+    // the window is snapped instead and echoed back, so what a caller is told was
+    // counted is exactly what was counted. Both ends floor, so the counted range
+    // can never reach past the horizon the checks above just cleared.
+    const grainMs = FORECAST_BOUNDS.minBucketSeconds * 1000;
+    const snappedFromMs = Math.floor(fromMs / grainMs) * grainMs;
+    const snappedToMs = Math.floor(toMs / grainMs) * grainMs;
+    if (snappedToMs <= snappedFromMs) {
+        return { ok: false, refusal: "range-empty" };
+    }
+    return {
+        ok: true,
+        window: {
+            bucketSeconds: request.bucketSeconds,
+            fromMs: snappedFromMs,
+            toMs: snappedToMs,
+        },
+    };
+}
+/**
+ * The epoch-aligned bucket an instant belongs to, in milliseconds.
+ *
+ * Aligned to the epoch rather than to `from`, so two callers asking for
+ * different windows at different moments agree about where a bucket begins —
+ * which is what makes a shadow comparison between two services a comparison of
+ * counts rather than of alignment. The consequence is that the first bucket of
+ * a window usually begins before the window does, and that is published.
+ */
+export function forecastBucketStartMs(instantMs, bucketSeconds) {
+    const bucketMs = bucketSeconds * 1000;
+    return Math.floor(instantMs / bucketMs) * bucketMs;
+}
+/* -------------------------------------------------------------------------- */
+/* Response                                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * One count per latency class, with every class present.
+ *
+ * Written out rather than derived from `LATENCY_CLASSES`, so the published JSON
+ * Schema names both keys. `forecast.test.ts` holds the two lists equal, so a
+ * third latency class fails a test here rather than silently vanishing from
+ * every forecast.
+ */
+export const forecastLatencyCountsSchema = z.object({
+    bulk: z.number().int().nonnegative(),
+    realtime: z.number().int().nonnegative(),
+});
+export const forecastBucketSchema = z.object({
+    byLatencyClass: forecastLatencyCountsSchema,
+    /**
+     * The busiest customer keys in this bucket, present exactly when the caller
+     * asked for the breakdown — and then always paired with
+     * `otherPartitionKeyCount`, so the arithmetic below can be relied on rather
+     * than guessed at.
+     *
+     * Real keys only, ordered by count and then by key so the tenth and eleventh
+     * of a tie resolve the same way on every read. The remainder is
+     * `otherPartitionKeyCount`, a sibling field rather than a reserved key,
+     * because `partitionKeySchema` admits the literal string `other` — and admits
+     * `__proto__`, which is why every producer of this map builds it with a null
+     * prototype.
+     */
+    byPartitionKey: z.record(z.string(), z.number().int().positive()).optional(),
+    /**
+     * Occurrences expected in this bucket, across every latency class and every
+     * customer key. Never a top-N subtotal.
+     */
+    count: z.number().int().positive(),
+    /**
+     * Occurrences that are the *next* firing of their schedule.
+     *
+     * A recurring series contributes to this in exactly one bucket however many
+     * times it fires, so summing it across a window gives the number of schedules
+     * that fire in that window — which is precisely what the legacy service
+     * reported as its total. It is published rather than derived so a shadow
+     * comparison against that service is a subtraction rather than an inference,
+     * and it answers a question of its own: one herd of a thousand schedules and
+     * one schedule firing a thousand times are the same `count` and very
+     * different work.
+     */
+    nextFireCount: z.number().int().nonnegative(),
+    /**
+     * Occurrences not attributed to a named key: those from schedules that chose
+     * no `partitionKey`, plus the keys beyond the top ten. Present with the
+     * breakdown.
+     */
+    otherPartitionKeyCount: z.number().int().nonnegative().optional(),
+    /** The bucket's epoch-aligned start. May precede the requested `from`. */
+    start: timestampSchema,
+});
+export const forecastSchema = z.object({
+    /** Ascending by `start`. A bucket with no occurrences is omitted. */
+    buckets: z.array(forecastBucketSchema),
+    /**
+     * How old the answer is.
+     *
+     * Always `projected`, and now the schema says so rather than the comment. A
+     * partition serves this from a snapshot it refreshes on a floor rather than
+     * on every read — which is what makes a ten-second poll affordable — so
+     * `authoritative` would be true only by accident, on the call that happened
+     * to trigger a refresh. Admitting an arm the service never sends made every
+     * reader handle it, and put the age and the snapshot instant behind a narrow
+     * nothing could justify.
+     */
+    freshness: projectedFreshnessSchema,
+    window: z.object({
+        bucketSeconds: z.number().int().positive(),
+        from: timestampSchema,
+        to: timestampSchema,
+    }),
+});
+/**
+ * Sum one bucket across every shard, ascending by start.
+ *
+ * Both maps are null-prototype, and that is not defensive style: a customer's
+ * `partitionKey` may contain underscores, so `__proto__` is a legal key, and
+ * assigning it on an ordinary object runs the prototype setter and silently
+ * drops the count. The copied route took the same care for the same reason, and
+ * this product's charset makes the key easier to reach rather than harder.
+ */
+export function mergeForecastBuckets(buckets) {
+    const merged = new Map();
+    for (const bucket of buckets) {
+        let into = merged.get(bucket.bucketStartMs);
+        if (into === undefined) {
+            into = {
+                bucketStartMs: bucket.bucketStartMs,
+                byLatencyClass: Object.create(null),
+                byPartitionKey: Object.create(null),
+                count: 0,
+                nextFireCount: 0,
+                unkeyedCount: 0,
+            };
+            merged.set(bucket.bucketStartMs, into);
+        }
+        for (const [latencyClass, n] of Object.entries(bucket.byLatencyClass)) {
+            into.byLatencyClass[latencyClass] =
+                (into.byLatencyClass[latencyClass] ?? 0) + n;
+        }
+        for (const { key, n } of bucket.partitionKeys) {
+            into.byPartitionKey[key] = (into.byPartitionKey[key] ?? 0) + n;
+        }
+        into.count += bucket.count;
+        into.nextFireCount += bucket.nextFireCount;
+        into.unkeyedCount += bucket.unkeyedCount;
+    }
+    return [...merged.values()].sort((left, right) => left.bucketStartMs - right.bucketStartMs);
+}
+/**
+ * The busiest customer keys in one bucket, and everything else as one number.
+ *
+ * Ordered by count and then by key, so the tenth and eleventh of a tie resolve
+ * the same way on every read rather than by whatever order the shards answered
+ * in — a breakdown that reshuffles between polls looks like a change to
+ * anything comparing two readings.
+ *
+ * Occurrences from schedules that chose **no** key are counted in the
+ * remainder rather than published under a reserved name, because `default` and
+ * `other` are both legal keys and a reserved one would absorb a real
+ * customer's count. The published invariant is what survives:
+ * `count = sum(named) + other`.
+ */
+export function topPartitionKeys(bucket) {
+    const ranked = Object.entries(bucket.byPartitionKey).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+    const byPartitionKey = Object.create(null);
+    let otherPartitionKeyCount = bucket.unkeyedCount;
+    ranked.forEach(([key, n], index) => {
+        if (index < FORECAST_BOUNDS.topPartitionKeys) {
+            byPartitionKey[key] = n;
+        }
+        else {
+            otherPartitionKeyCount += n;
+        }
+    });
+    return { byPartitionKey, otherPartitionKeyCount };
+}
+/**
+ * Whether a gathered forecast may be published, and how old it is.
+ *
+ * **Every degradation this operation can suffer ends here, and every one of
+ * them is a refusal.** That is the whole safety argument of the shape, and it
+ * follows from a measured fact about the consumer it exists for: it reads the
+ * bucket total and nothing else — not a degraded flag, not `freshness` — so a
+ * degraded answer reads to it as a quiet book, and a quiet book makes it
+ * release capacity. Its own failure path is fail-safe: a request that errors
+ * makes it hold its last good reading. So the honest degradation is the one
+ * that errors.
+ *
+ * The three are distinct because they mean different things to whoever is
+ * looking: a partition that did not answer is an availability problem, a book
+ * past the projection bound is a capacity problem with a published number
+ * beside it, and an answer older than the bound is a partition that has stopped
+ * refreshing.
+ *
+ * `asOfMs` is the **oldest** across the shards, for the reason
+ * `projectionCoverage` takes the oldest checkpoint: one busy shard must not be
+ * allowed to vouch for three quiet ones.
+ */
+export function decideForecastAnswer(answers, nowMs) {
+    if (answers.some((answer) => "refused" in answer)) {
+        return { ok: false, refusal: "partition-unavailable" };
+    }
+    if (answers.some((answer) => "truncated" in answer && answer.truncated)) {
+        return { ok: false, refusal: "book-too-large" };
+    }
+    // **Only a partition that built a snapshot vouches for freshness.** One that
+    // holds nothing has nothing to be stale about, and letting it contribute the
+    // instant of the read made `asOf` move between two reads of an unchanged
+    // book — a project spans several shards and most of them are usually empty.
+    // With none of them holding a snapshot the answer really is current.
+    const instants = answers.flatMap((answer) => "asOfMs" in answer && answer.asOfMs !== undefined ? [answer.asOfMs] : []);
+    const asOfMs = instants.length === 0 ? nowMs : Math.min(...instants);
+    const lagSeconds = Math.max(0, Math.ceil((nowMs - asOfMs) / 1000));
+    if (lagSeconds > FORECAST_BOUNDS.maxLagSeconds) {
+        return { ok: false, refusal: "too-stale" };
+    }
+    return {
+        freshness: {
+            asOf: new Date(asOfMs).toISOString(),
+            kind: "projected",
+            lagSeconds,
+        },
+        ok: true,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* The migration adapter                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * The version of the transitional window shape.
+ *
+ * Dated like the callback envelope, for the same reason: a consumer pins a
+ * literal, and a literal that moves is a change the consumer can be told about
+ * rather than one it discovers.
+ */
+export const FORECAST_WINDOW_VERSION = "2026-08-09";
+export const forecastWindowBucketSchema = z.object({
+    /**
+     * The legacy spelling of the customer-key breakdown.
+     *
+     * Upstream a partition *was* a tenant, so its breakdown was `byTenant`; here
+     * the equivalent division is the customer's own `partitionKey`. The name is
+     * kept because the migrating consumer carries this map through untouched, and
+     * renaming it would be a change with no benefit on either side.
+     */
+    byTenant: z.record(z.string(), z.number().int().positive()),
+    count: z.number().int().positive(),
+    /** `forecastBucketSchema.nextFireCount`, under the same name. */
+    nextFireCount: z.number().int().nonnegative(),
+    otherCount: z.number().int().nonnegative(),
+    start: timestampSchema,
+});
+export const forecastWindowsSchema = z.object({
+    /**
+     * The width of every bucket, in seconds.
+     *
+     * Not in the legacy shape, and the one addition worth its bytes: without it a
+     * consumer cannot tell whether a bucket is still ahead of it. The measured
+     * consumer drops any bucket whose `start` is not strictly after its own
+     * `now`, and buckets are aligned to the epoch, so the bucket carrying the next
+     * few minutes of work is the one it throws away on almost every poll. With the
+     * width published, `start + bucketSeconds > now` is the filter that keeps it.
+     */
+    bucketSeconds: z.number().int().positive(),
+    buckets: z.array(forecastWindowBucketSchema),
+    /** Stated here too, so a shadow comparison can compare staleness. */
+    freshness: freshnessSchema,
+    version: z.literal(FORECAST_WINDOW_VERSION),
+});
+/**
+ * What the migrating consumer may rely on, published as data.
+ *
+ * Prose describing a wire contract drifts from the code that produces it —
+ * three times during W3-08, and the third published a rule that would have had
+ * a customer take a payment twice. So the rules live here, beside the schema,
+ * and `scripts/contract-projection.test.ts` holds `docs/contracts/forecast.md`
+ * against them.
+ *
+ * Every entry was read out of the consumer rather than assumed. It parses
+ * `start` with `Date.parse` and drops any bucket that does not parse; it reads
+ * `count` raw and sums it across buckets to size capacity; it carries
+ * `byTenant` through untouched; and it reads no other field — not `otherCount`,
+ * not the legacy `partial`, not `unavailablePartitions`. That last fact is what
+ * makes "a refusal, never a short answer" a rule rather than an implementation
+ * note: a degraded answer this consumer cannot see reads as a quiet book, and a
+ * quiet book makes it scale *down*.
+ */
+export const FORECAST_COMPATIBILITY = {
+    /**
+     * What a consumer must tolerate or do for itself. Not checkable in a
+     * response: each is a permission this producer has, or an obligation the
+     * consumer owes, rather than something the producer owes.
+     */
+    consumerNotes: [
+        "a bucket's start may precede the requested from, because buckets are aligned to the epoch rather than to the window; filter on start + bucketSeconds > now rather than on start > now, or the bucket carrying the next few minutes of work is discarded on almost every poll",
+        "a window this service cannot answer completely is a refusal rather than a short list of buckets, so a non-2xx is no reading rather than an empty book",
+        "the legacy partial and unavailablePartitions fields are gone, because there is no partial answer left for them to describe",
+        "freshness is published on every answer and an answer staler than FORECAST_BOUNDS.maxLagSeconds is refused rather than served, so a 200 is always inside that bound",
+    ],
+    /** The only fields the migrating consumer reads today. */
+    consumedFields: ["byTenant", "count", "start"],
+    /** What a caller must change, beyond the base URL. */
+    migrationDelta: [
+        "authenticate with a scoped Greatwait credential holding forecast:read, not the legacy shared bearer token",
+        "drop the :owner path segment, because authority comes from the credential and a request can no longer name a project",
+        "send bucketSeconds=600 rather than bucket=10m, because durations on this surface are whole seconds as numbers",
+        "expect a recurring series to contribute every instant it fires in the window, where the legacy answer counted each schedule once at its next fire time — sum nextFireCount to reproduce the legacy total, and retune any threshold calibrated against it before cutting over",
+        "assert version equals the published constant and treat a mismatch as staleness, because nothing else tells a consumer the shape moved",
+    ],
+    /**
+     * What this check cannot see, stated so nobody mistakes a pass for a proof.
+     *
+     * A response body carries counts, not the reasoning that produced them, so an
+     * implementation that quietly stopped expanding recurring series would
+     * satisfy every rule below: its counts would simply be smaller. That property
+     * is pinned by running the un-expanded implementation through
+     * `partition-forecast.test.ts` and the worker acceptance tests and watching
+     * them fail, which is the only place it can be pinned.
+     */
+    notCheckedHere: [
+        "that recurring series were expanded at all, because a smaller count is still an arithmetically consistent one",
+        "that the counts match the partition's own state, because this check never sees it",
+    ],
+    /**
+     * What this producer owes, in the order `forecastWindowViolations` checks
+     * them. Every rule has a case that trips it, which `forecast.test.ts` asserts
+     * by construction rather than by inspection.
+     */
+    rules: [
+        "start is an RFC 3339 UTC timestamp with millisecond precision and a literal Z, because a consumer parsing it with Date.parse reads a bucket it cannot parse as no work at all",
+        "count is the total across every customer key and latency class in the bucket, never the top-ten subtotal",
+        "count equals the sum of byTenant plus otherCount",
+        "nextFireCount is at most count, because a bucket cannot hold more first firings than firings",
+        "buckets ascend strictly by start",
+        "a bucket with no occurrences is omitted rather than published with a count of zero",
+    ],
+    version: FORECAST_WINDOW_VERSION,
+};
+/**
+ * What the canonical forecast owes, checked by `forecastViolations`.
+ *
+ * Published separately from `FORECAST_COMPATIBILITY` because the adapter is
+ * dated and scheduled for deletion once W6-02 has cut over, and the shape that
+ * outlives it must not be the one with no gate. Two of these are the same
+ * obligations in the canonical spelling; the latency-class arithmetic has no
+ * counterpart in the adapter, which carries no class breakdown.
+ */
+export const FORECAST_RULES = [
+    "start is an RFC 3339 UTC timestamp with millisecond precision and a literal Z",
+    "count equals byLatencyClass.bulk plus byLatencyClass.realtime",
+    "byPartitionKey and otherPartitionKeyCount are present together or not at all, so a caller never has to guess whether a breakdown was requested",
+    "when the breakdown is present, count equals the sum of byPartitionKey plus otherPartitionKeyCount",
+    "nextFireCount is at most count",
+    "buckets ascend strictly by start",
+    "a bucket with no occurrences is omitted rather than published with a count of zero",
+];
+function looseBuckets(body) {
+    if (typeof body !== "object" || body === null) {
+        return undefined;
+    }
+    const buckets = body.buckets;
+    if (!Array.isArray(buckets)) {
+        return undefined;
+    }
+    return buckets.filter((bucket) => typeof bucket === "object" && bucket !== null);
+}
+function sumOf(map) {
+    if (typeof map !== "object" || map === null) {
+        return Number.NaN;
+    }
+    return Object.values(map).reduce((total, value) => total + (typeof value === "number" ? value : Number.NaN), 0);
+}
+function numberOr(value, fallback) {
+    return typeof value === "number" ? value : fallback;
+}
+function ascendingViolated(buckets) {
+    return buckets.some((bucket, index) => {
+        const previous = buckets[index - 1];
+        return (previous !== undefined &&
+            typeof bucket.start === "string" &&
+            typeof previous.start === "string" &&
+            bucket.start <= previous.start);
+    });
+}
+/**
+ * Which published rules a canonical forecast breaks.
+ *
+ * The same shape of check as `forecastWindowViolations`, over `FORECAST_RULES`,
+ * so the shape that outlives the migration adapter is gated too. See that
+ * function for why both read the body loosely rather than through their schema.
+ */
+export function forecastViolations(body) {
+    const buckets = looseBuckets(body);
+    if (buckets === undefined) {
+        return [...FORECAST_RULES];
+    }
+    const [spelling, classes, pairing, breakdown, heads, ascending, empties] = FORECAST_RULES;
+    const violations = [];
+    if (buckets.some((bucket) => !timestampSchema.safeParse(bucket.start).success)) {
+        violations.push(spelling);
+    }
+    if (buckets.some((bucket) => bucket.count !== sumOf(bucket.byLatencyClass))) {
+        violations.push(classes);
+    }
+    if (buckets.some((bucket) => (bucket.byPartitionKey === undefined) !==
+        (bucket.otherPartitionKeyCount === undefined))) {
+        violations.push(pairing);
+    }
+    if (buckets.some((bucket) => bucket.byPartitionKey !== undefined &&
+        bucket.count !==
+            sumOf(bucket.byPartitionKey) +
+                numberOr(bucket.otherPartitionKeyCount, Number.NaN))) {
+        violations.push(breakdown);
+    }
+    if (buckets.some((bucket) => numberOr(bucket.nextFireCount, Number.NaN) >
+        numberOr(bucket.count, Number.NaN) ||
+        Number.isNaN(numberOr(bucket.nextFireCount, Number.NaN)))) {
+        violations.push(heads);
+    }
+    if (ascendingViolated(buckets)) {
+        violations.push(ascending);
+    }
+    if (buckets.some((bucket) => bucket.count === 0)) {
+        violations.push(empties);
+    }
+    return violations;
+}
+/**
+ * Which published rules a window response breaks.
+ *
+ * Deliberately a predicate over a **response body** rather than over the code
+ * that produced it, so it can be pointed at a knowingly wrong implementation
+ * and watched failing. W3-08 shipped a conformance suite that compared HTTP
+ * status codes, and a receiver carrying the exact defect the story existed to
+ * fix passed twenty of twenty published cases; reading a suite cannot show what
+ * it fails to distinguish.
+ *
+ * It reads the body loosely rather than through `forecastWindowsSchema`,
+ * because the schema refuses several of these outright and a check that could
+ * only say "did not parse" would name no rule — which is the same defect in a
+ * different coat.
+ *
+ * Returns the broken rules in `FORECAST_COMPATIBILITY.rules` order. An empty
+ * array is the only pass.
+ */
+export function forecastWindowViolations(body) {
+    const buckets = looseBuckets(body);
+    if (buckets === undefined) {
+        return [...FORECAST_COMPATIBILITY.rules];
+    }
+    const violations = [];
+    const [spelling, total, arithmetic, heads, ascending, empties] = FORECAST_COMPATIBILITY.rules;
+    if (buckets.some((bucket) => !timestampSchema.safeParse(bucket.start).success)) {
+        violations.push(spelling);
+    }
+    // The discriminating case for "count is the total, never the subtotal": an
+    // implementation that published the top ten's sum as the count while a
+    // remainder existed. Arithmetic below catches it too, and both firing is the
+    // honest report — one names the defect, the other names the symptom.
+    if (buckets.some((bucket) => bucket.count === sumOf(bucket.byTenant) &&
+        numberOr(bucket.otherCount, 0) > 0)) {
+        violations.push(total);
+    }
+    if (buckets.some((bucket) => bucket.count !==
+        sumOf(bucket.byTenant) + numberOr(bucket.otherCount, Number.NaN))) {
+        violations.push(arithmetic);
+    }
+    if (buckets.some((bucket) => numberOr(bucket.nextFireCount, Number.NaN) >
+        numberOr(bucket.count, Number.NaN) ||
+        Number.isNaN(numberOr(bucket.nextFireCount, Number.NaN)))) {
+        violations.push(heads);
+    }
+    if (ascendingViolated(buckets)) {
+        violations.push(ascending);
+    }
+    if (buckets.some((bucket) => bucket.count === 0)) {
+        violations.push(empties);
+    }
+    return violations;
+}