@greatwait/contracts 0.1.0-alpha.1

package/dist/forecast.d.ts

@@ -0,0 +1,443 @@
+import { z } from "zod";
+import type { FieldError } from "./problems.js";
+import { type Freshness } from "./protocol.js";
+import type { ForecastPartitionBucket } from "./partition.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.
+ */
+/**
+ * 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 declare const FORECAST_BOUNDS: {
+    readonly defaultBucketSeconds: number;
+    /** Window served when a caller names neither `from` nor `to`. */
+    readonly defaultWindowSeconds: number;
+    readonly maxBucketSeconds: number;
+    /** `maxWindowSeconds / minBucketSeconds`, so the size is arithmetic. */
+    readonly maxBuckets: 1500;
+    /**
+     * Distinct `(minute, latencyClass, partitionKey)` groups one partition may
+     * aggregate before it reports the answer as short.
+     */
+    readonly maxGroupsPerPartition: 100000;
+    /**
+     * 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.
+     */
+    readonly 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".
+     */
+    readonly maxProjectedOccurrencesPerPartition: 20000;
+    /** Recurring series one partition may project from in a single snapshot. */
+    readonly maxRecurringSeriesPerPartition: 20000;
+    /**
+     * 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.
+     */
+    readonly maxWindowSeconds: number;
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly topPartitionKeys: 10;
+};
+/**
+ * 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 declare const FORECAST_BREAKDOWNS: readonly ["none", "partitionKey"];
+export declare const forecastBreakdownSchema: z.ZodEnum<{
+    none: "none";
+    partitionKey: "partitionKey";
+}>;
+export type ForecastBreakdown = z.infer<typeof forecastBreakdownSchema>;
+export declare const forecastRequestSchema: z.ZodObject<{
+    breakdown: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        partitionKey: "partitionKey";
+    }>>;
+    bucketSeconds: z.ZodDefault<z.ZodNumber>;
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ForecastRequest = z.infer<typeof forecastRequestSchema>;
+export type ForecastRequestParse = {
+    readonly errors: readonly FieldError[];
+    readonly ok: false;
+} | {
+    readonly ok: true;
+    readonly request: ForecastRequest;
+};
+/**
+ * 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 declare function parseForecastRequest(query: URLSearchParams): ForecastRequestParse;
+/** The window a forecast actually covers, once defaults have been applied. */
+export interface ForecastWindow {
+    readonly bucketSeconds: number;
+    readonly fromMs: number;
+    readonly toMs: number;
+}
+export type ForecastWindowRefusal = "range-empty" | "range-too-long" | "window-in-the-past" | "window-past-horizon";
+export type ForecastWindowResolution = {
+    readonly ok: false;
+    readonly refusal: ForecastWindowRefusal;
+} | {
+    readonly ok: true;
+    readonly window: ForecastWindow;
+};
+/**
+ * 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 declare function resolveForecastWindow(request: ForecastRequest, nowMs: number): ForecastWindowResolution;
+/**
+ * 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 declare function forecastBucketStartMs(instantMs: number, bucketSeconds: number): number;
+/**
+ * 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 declare const forecastLatencyCountsSchema: z.ZodObject<{
+    bulk: z.ZodNumber;
+    realtime: z.ZodNumber;
+}, z.core.$strip>;
+export type ForecastLatencyCounts = z.infer<typeof forecastLatencyCountsSchema>;
+export declare const forecastBucketSchema: z.ZodObject<{
+    byLatencyClass: z.ZodObject<{
+        bulk: z.ZodNumber;
+        realtime: z.ZodNumber;
+    }, z.core.$strip>;
+    byPartitionKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    count: z.ZodNumber;
+    nextFireCount: z.ZodNumber;
+    otherPartitionKeyCount: z.ZodOptional<z.ZodNumber>;
+    start: z.ZodString;
+}, z.core.$strip>;
+export type ForecastBucket = z.infer<typeof forecastBucketSchema>;
+export declare const forecastSchema: z.ZodObject<{
+    buckets: z.ZodArray<z.ZodObject<{
+        byLatencyClass: z.ZodObject<{
+            bulk: z.ZodNumber;
+            realtime: z.ZodNumber;
+        }, z.core.$strip>;
+        byPartitionKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        count: z.ZodNumber;
+        nextFireCount: z.ZodNumber;
+        otherPartitionKeyCount: z.ZodOptional<z.ZodNumber>;
+        start: z.ZodString;
+    }, z.core.$strip>>;
+    freshness: z.ZodObject<{
+        asOf: z.ZodString;
+        kind: z.ZodLiteral<"projected">;
+        lagSeconds: z.ZodNumber;
+    }, z.core.$strip>;
+    window: z.ZodObject<{
+        bucketSeconds: z.ZodNumber;
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type Forecast = z.infer<typeof forecastSchema>;
+/** One bucket, summed across every shard, before it is rendered. */
+export interface ForecastMergedBucket {
+    readonly bucketStartMs: number;
+    readonly byLatencyClass: Record<string, number>;
+    readonly byPartitionKey: Record<string, number>;
+    count: number;
+    nextFireCount: number;
+    unkeyedCount: number;
+}
+/**
+ * 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 declare function mergeForecastBuckets(buckets: readonly ForecastPartitionBucket[]): readonly ForecastMergedBucket[];
+/**
+ * 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 declare function topPartitionKeys(bucket: ForecastMergedBucket): {
+    readonly byPartitionKey: Record<string, number>;
+    readonly otherPartitionKeyCount: number;
+};
+/** Why a gathered forecast is refused rather than served. */
+export type ForecastAnswerRefusal = "book-too-large" | "partition-unavailable" | "too-stale";
+/**
+ * One partition's contribution, reduced to what the decision depends on.
+ *
+ * `asOfMs` is absent when the partition has no snapshot at all, which is the
+ * ordinary case for a shard a project has never written to.
+ */
+export type ForecastShardAnswer = {
+    readonly refused: true;
+} | {
+    readonly asOfMs?: number;
+    readonly truncated: boolean;
+};
+export type ForecastAnswerDecision = {
+    readonly ok: false;
+    readonly refusal: ForecastAnswerRefusal;
+} | {
+    readonly freshness: Extract<Freshness, {
+        kind: "projected";
+    }>;
+    readonly ok: true;
+};
+/**
+ * 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 declare function decideForecastAnswer(answers: readonly ForecastShardAnswer[], nowMs: number): ForecastAnswerDecision;
+/**
+ * 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 declare const FORECAST_WINDOW_VERSION = "2026-08-09";
+export declare const forecastWindowBucketSchema: z.ZodObject<{
+    byTenant: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    count: z.ZodNumber;
+    nextFireCount: z.ZodNumber;
+    otherCount: z.ZodNumber;
+    start: z.ZodString;
+}, z.core.$strip>;
+export type ForecastWindowBucket = z.infer<typeof forecastWindowBucketSchema>;
+export declare const forecastWindowsSchema: z.ZodObject<{
+    bucketSeconds: z.ZodNumber;
+    buckets: z.ZodArray<z.ZodObject<{
+        byTenant: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        count: z.ZodNumber;
+        nextFireCount: z.ZodNumber;
+        otherCount: z.ZodNumber;
+        start: z.ZodString;
+    }, z.core.$strip>>;
+    freshness: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>, z.ZodObject<{
+        asOf: z.ZodString;
+        kind: z.ZodLiteral<"projected">;
+        lagSeconds: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    version: z.ZodLiteral<"2026-08-09">;
+}, z.core.$strip>;
+export type ForecastWindows = z.infer<typeof forecastWindowsSchema>;
+/**
+ * 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 declare 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.
+     */
+    readonly consumerNotes: readonly ["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. */
+    readonly consumedFields: readonly ["byTenant", "count", "start"];
+    /** What a caller must change, beyond the base URL. */
+    readonly migrationDelta: readonly ["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.
+     */
+    readonly notCheckedHere: readonly ["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.
+     */
+    readonly rules: readonly ["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"];
+    readonly version: "2026-08-09";
+};
+/**
+ * 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 declare const FORECAST_RULES: readonly ["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"];
+/**
+ * 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 declare function forecastViolations(body: unknown): readonly string[];
+/**
+ * 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 declare function forecastWindowViolations(body: unknown): readonly string[];