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

package/dist/forecast.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 import type { FieldError } from "./problems.js";
 import { type Freshness } from "./protocol.js";
 import type { ForecastPartitionBucket } from "./partition.js";
@@ -53,10 +53,11 @@ export declare const FORECAST_BOUNDS: {
      * argument for refusing rather than under-reporting collapses if staleness is
      * the one degradation that gets through as a number.
      */
-    readonly maxLagSeconds: 600;
+    readonly maxLagSeconds: number;
     /**
-     * Instants one partition may project into a single snapshot before it reports
-     * the answer as short.
+     * Actual recurrence work units (shared cron advances or interval-series
+     * calculations) before a partition reports the answer as short. Output-cell
+     * allocation is bounded independently by maxGroupsPerPartition.
      *
      * 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
@@ -83,7 +84,7 @@ export declare const FORECAST_BOUNDS: {
      * an incident. `freshness.lagSeconds` reports the actual age on every answer;
      * this is the bound it lives inside.
      */
-    readonly refreshCeilingSeconds: 300;
+    readonly refreshCeilingSeconds: number;
     /**
      * Shortest gap between refreshes once something *has* been written.
      *
@@ -92,7 +93,7 @@ export declare const FORECAST_BOUNDS: {
      * projection that rebuilt on every poll would be the cost this whole design
      * exists to avoid.
      */
-    readonly refreshFloorSeconds: 30;
+    readonly refreshFloorSeconds: number;
     /**
      * How far below `now` a window may begin.
      *
@@ -102,7 +103,7 @@ export declare const FORECAST_BOUNDS: {
      * 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;
+    readonly slackSeconds: number;
     /**
      * Customer keys named individually in one bucket before the rest are summed.
      *
@@ -120,20 +121,20 @@ export declare const FORECAST_BOUNDS: {
  * the total and the latency split, which every answer carries.
  */
 export declare const FORECAST_BREAKDOWNS: readonly ["none", "partitionKey"];
-export declare const forecastBreakdownSchema: z.ZodEnum<{
+export declare const forecastBreakdownSchema: import("zod").ZodEnum<{
     none: "none";
     partitionKey: "partitionKey";
 }>;
 export type ForecastBreakdown = z.infer<typeof forecastBreakdownSchema>;
-export declare const forecastRequestSchema: z.ZodObject<{
-    breakdown: z.ZodDefault<z.ZodEnum<{
+export declare const forecastRequestSchema: import("zod").ZodObject<{
+    breakdown: import("zod").ZodDefault<import("zod").ZodEnum<{
         none: "none";
         partitionKey: "partitionKey";
     }>>;
-    bucketSeconds: z.ZodDefault<z.ZodNumber>;
-    from: z.ZodOptional<z.ZodString>;
-    to: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+    bucketSeconds: import("zod").ZodDefault<import("zod").ZodNumber>;
+    from: import("zod").ZodOptional<import("zod").ZodString>;
+    to: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
 export type ForecastRequest = z.infer<typeof forecastRequestSchema>;
 export type ForecastRequestParse = {
     readonly errors: readonly FieldError[];
@@ -197,46 +198,145 @@ export declare function forecastBucketStartMs(instantMs: number, bucketSeconds:
  * 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 declare const forecastLatencyCountsSchema: import("zod").ZodObject<{
+    bulk: import("zod").ZodNumber;
+    realtime: import("zod").ZodNumber;
+}, import("zod/v4/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 declare const forecastBucketSchema: import("zod").ZodObject<{
+    byLatencyClass: import("zod").ZodObject<{
+        bulk: import("zod").ZodNumber;
+        realtime: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+    byPartitionKey: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>>;
+    count: import("zod").ZodNumber;
+    nextFireCount: import("zod").ZodNumber;
+    otherPartitionKeyCount: import("zod").ZodOptional<import("zod").ZodNumber>;
+    start: import("zod").ZodString;
+}, import("zod/v4/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>;
+/** Capability opt-in prevents old clients that read only counts from mistaking
+ * a lower bound for complete work. Older servers safely ignore this header. */
+export declare const FORECAST_PARTIAL_ACCEPT_HEADER = "X-Greatwait-Accept-Partial-Forecast";
+export declare const forecastRequestHeadersSchema: import("zod").ZodObject<{
+    "X-Greatwait-Accept-Partial-Forecast": import("zod").ZodOptional<import("zod").ZodLiteral<"true">>;
+}, import("zod/v4/core").$strip>;
+export declare const forecastCoverageSchema: import("zod").ZodObject<{
+    complete: import("zod").ZodBoolean;
+    countMeaning: import("zod").ZodEnum<{
+        "complete-total": "complete-total";
+        "lower-bound": "lower-bound";
+    }>;
+    projectedWindow: import("zod").ZodObject<{
+        from: import("zod").ZodString;
+        to: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>;
+    completeThrough: import("zod").ZodString;
+    heads: import("zod").ZodObject<{
+        groupsRead: import("zod").ZodNumber;
+        occurrencesCounted: import("zod").ZodNumber;
+        complete: import("zod").ZodBoolean;
+        selection: import("zod").ZodLiteral<"earliest bucket, latency class, partition key groups">;
+        lastGroup: import("zod").ZodOptional<import("zod").ZodObject<{
+            start: import("zod").ZodString;
+            latencyClass: import("zod").ZodEnum<{
+                realtime: "realtime";
+                bulk: "bulk";
+            }>;
+            partitionKey: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>;
+    recurring: import("zod").ZodObject<{
+        schedulesRead: import("zod").ZodNumber;
+        populationComplete: import("zod").ZodBoolean;
+        selection: import("zod").ZodLiteral<"oldest eligible active recurring schedules by createdAt and scheduleId">;
+        firstScheduleId: import("zod").ZodOptional<import("zod").ZodString>;
+        lastScheduleId: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>;
+    work: import("zod").ZodObject<{
+        usedUnits: import("zod").ZodNumber;
+        limitUnits: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+    boundsReached: import("zod").ZodArray<import("zod").ZodObject<{
+        kind: import("zod").ZodEnum<{
+            "head-cells": "head-cells";
+            "recurring-series": "recurring-series";
+            "projection-work": "projection-work";
+            "projection-cells": "projection-cells";
+        }>;
+        limit: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>;
+export type ForecastCoverage = z.infer<typeof forecastCoverageSchema>;
+export declare const forecastSchema: import("zod").ZodObject<{
+    coverage: import("zod").ZodOptional<import("zod").ZodObject<{
+        complete: import("zod").ZodBoolean;
+        countMeaning: import("zod").ZodEnum<{
+            "complete-total": "complete-total";
+            "lower-bound": "lower-bound";
+        }>;
+        projectedWindow: import("zod").ZodObject<{
+            from: import("zod").ZodString;
+            to: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>;
+        completeThrough: import("zod").ZodString;
+        heads: import("zod").ZodObject<{
+            groupsRead: import("zod").ZodNumber;
+            occurrencesCounted: import("zod").ZodNumber;
+            complete: import("zod").ZodBoolean;
+            selection: import("zod").ZodLiteral<"earliest bucket, latency class, partition key groups">;
+            lastGroup: import("zod").ZodOptional<import("zod").ZodObject<{
+                start: import("zod").ZodString;
+                latencyClass: import("zod").ZodEnum<{
+                    realtime: "realtime";
+                    bulk: "bulk";
+                }>;
+                partitionKey: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>;
+        recurring: import("zod").ZodObject<{
+            schedulesRead: import("zod").ZodNumber;
+            populationComplete: import("zod").ZodBoolean;
+            selection: import("zod").ZodLiteral<"oldest eligible active recurring schedules by createdAt and scheduleId">;
+            firstScheduleId: import("zod").ZodOptional<import("zod").ZodString>;
+            lastScheduleId: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>;
+        work: import("zod").ZodObject<{
+            usedUnits: import("zod").ZodNumber;
+            limitUnits: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strip>;
+        boundsReached: import("zod").ZodArray<import("zod").ZodObject<{
+            kind: import("zod").ZodEnum<{
+                "head-cells": "head-cells";
+                "recurring-series": "recurring-series";
+                "projection-work": "projection-work";
+                "projection-cells": "projection-cells";
+            }>;
+            limit: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>>;
+    buckets: import("zod").ZodArray<import("zod").ZodObject<{
+        byLatencyClass: import("zod").ZodObject<{
+            bulk: import("zod").ZodNumber;
+            realtime: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strip>;
+        byPartitionKey: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>>;
+        count: import("zod").ZodNumber;
+        nextFireCount: import("zod").ZodNumber;
+        otherPartitionKeyCount: import("zod").ZodOptional<import("zod").ZodNumber>;
+        start: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    freshness: import("zod").ZodObject<{
+        asOf: import("zod").ZodString;
+        kind: import("zod").ZodLiteral<"projected">;
+        lagSeconds: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+    window: import("zod").ZodObject<{
+        bucketSeconds: import("zod").ZodNumber;
+        from: import("zod").ZodString;
+        to: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>;
+}, import("zod/v4/core").$strip>;
 export type Forecast = z.infer<typeof forecastSchema>;
 /** One bucket, summed across every shard, before it is rendered. */
 export interface ForecastMergedBucket {
@@ -245,6 +345,7 @@ export interface ForecastMergedBucket {
     readonly byPartitionKey: Record<string, number>;
     count: number;
     nextFireCount: number;
+    omittedPartitionKeyCount?: number;
     unkeyedCount: number;
 }
 /**
@@ -301,26 +402,15 @@ export type ForecastAnswerDecision = {
 /**
  * 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.
+ * Unavailable and stale sources always refuse. Work-bound partial answers are
+ * permitted only for a reader that explicitly understands coverage; the
+ * default retains the count-only legacy consumer's safe failure behavior.
  *
  * `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;
+export declare function decideForecastAnswer(answers: readonly ForecastShardAnswer[], nowMs: number, acceptPartial?: boolean): ForecastAnswerDecision;
 /**
  * The version of the transitional window shape.
  *
@@ -329,32 +419,32 @@ export declare function decideForecastAnswer(answers: readonly ForecastShardAnsw
  * 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 declare const forecastWindowBucketSchema: import("zod").ZodObject<{
+    byTenant: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>;
+    count: import("zod").ZodNumber;
+    nextFireCount: import("zod").ZodNumber;
+    otherCount: import("zod").ZodNumber;
+    start: import("zod").ZodString;
+}, import("zod/v4/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 declare const forecastWindowsSchema: import("zod").ZodObject<{
+    bucketSeconds: import("zod").ZodNumber;
+    buckets: import("zod").ZodArray<import("zod").ZodObject<{
+        byTenant: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>;
+        count: import("zod").ZodNumber;
+        nextFireCount: import("zod").ZodNumber;
+        otherCount: import("zod").ZodNumber;
+        start: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    freshness: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"authoritative">;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        asOf: import("zod").ZodString;
+        kind: import("zod").ZodLiteral<"projected">;
+        lagSeconds: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>], "kind">;
+    version: import("zod").ZodLiteral<"2026-08-09">;
+}, import("zod/v4/core").$strip>;
 export type ForecastWindows = z.infer<typeof forecastWindowsSchema>;
 /**
  * What the migrating consumer may rely on, published as data.

package/dist/forecast.js

@@ -1,4 +1,6 @@
-import { z } from "zod";
+import { MAX_FORECAST_HORIZON_SECONDS } from "./configuration-bounds.js";
+import { OPERATIONAL_TIMING } from "./operational-config.js";
+import { z } from "./zod.js";
 import { freshnessSchema, projectedFreshnessSchema, } from "./protocol.js";
 import { timestampSchema } from "./time.js";
 /**
@@ -55,10 +57,11 @@ export const FORECAST_BOUNDS = {
      * argument for refusing rather than under-reporting collapses if staleness is
      * the one degradation that gets through as a number.
      */
-    maxLagSeconds: 600,
+    maxLagSeconds: (OPERATIONAL_TIMING.forecastRefreshMaximumMs * 2) / 1000,
     /**
-     * Instants one partition may project into a single snapshot before it reports
-     * the answer as short.
+     * Actual recurrence work units (shared cron advances or interval-series
+     * calculations) before a partition reports the answer as short. Output-cell
+     * allocation is bounded independently by maxGroupsPerPartition.
      *
      * 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
@@ -75,7 +78,7 @@ export const FORECAST_BOUNDS = {
      * legacy service's seven-day ceiling bounded the *query* with no snapshot
      * behind it at all.
      */
-    maxWindowSeconds: 25 * 60 * 60,
+    maxWindowSeconds: MAX_FORECAST_HORIZON_SECONDS,
     minBucketSeconds: 60,
     /**
      * Longest a partition lets its snapshot stand when nothing has been written.
@@ -85,7 +88,7 @@ export const FORECAST_BOUNDS = {
      * an incident. `freshness.lagSeconds` reports the actual age on every answer;
      * this is the bound it lives inside.
      */
-    refreshCeilingSeconds: 300,
+    refreshCeilingSeconds: OPERATIONAL_TIMING.forecastRefreshMaximumMs / 1000,
     /**
      * Shortest gap between refreshes once something *has* been written.
      *
@@ -94,7 +97,7 @@ export const FORECAST_BOUNDS = {
      * projection that rebuilt on every poll would be the cost this whole design
      * exists to avoid.
      */
-    refreshFloorSeconds: 30,
+    refreshFloorSeconds: OPERATIONAL_TIMING.forecastRefreshFloorMs / 1000,
     /**
      * How far below `now` a window may begin.
      *
@@ -104,7 +107,7 @@ export const FORECAST_BOUNDS = {
      * 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,
+    slackSeconds: OPERATIONAL_TIMING.forecastCoverageSlackMs / 1000,
     /**
      * Customer keys named individually in one bucket before the rest are summed.
      *
@@ -337,7 +340,73 @@ export const forecastBucketSchema = z.object({
     /** The bucket's epoch-aligned start. May precede the requested `from`. */
     start: timestampSchema,
 });
+/** Capability opt-in prevents old clients that read only counts from mistaking
+ * a lower bound for complete work. Older servers safely ignore this header. */
+export const FORECAST_PARTIAL_ACCEPT_HEADER = "X-Greatwait-Accept-Partial-Forecast";
+export const forecastRequestHeadersSchema = z.object({
+    [FORECAST_PARTIAL_ACCEPT_HEADER]: z.literal("true").optional(),
+});
+export const forecastCoverageSchema = z
+    .object({
+    complete: z.boolean(),
+    countMeaning: z.enum(["complete-total", "lower-bound"]),
+    projectedWindow: z.object({ from: timestampSchema, to: timestampSchema }),
+    /** No interval after this can be assumed quiet from absent buckets. */
+    completeThrough: timestampSchema,
+    heads: z.object({
+        groupsRead: z.number().int().nonnegative(),
+        occurrencesCounted: z.number().int().nonnegative(),
+        complete: z.boolean(),
+        selection: z.literal("earliest bucket, latency class, partition key groups"),
+        lastGroup: z
+            .object({
+            start: timestampSchema,
+            latencyClass: z.enum(["realtime", "bulk"]),
+            partitionKey: z.string(),
+        })
+            .optional(),
+    }),
+    recurring: z.object({
+        schedulesRead: z.number().int().nonnegative(),
+        /** The selected population is complete, not necessarily its expansion. */
+        populationComplete: z.boolean(),
+        selection: z.literal("oldest eligible active recurring schedules by createdAt and scheduleId"),
+        firstScheduleId: z.string().optional(),
+        lastScheduleId: z.string().optional(),
+    }),
+    work: z.object({
+        usedUnits: z.number().int().nonnegative(),
+        limitUnits: z.number().int().nonnegative(),
+    }),
+    boundsReached: z.array(z.object({
+        kind: z.enum([
+            "head-cells",
+            "recurring-series",
+            "projection-work",
+            "projection-cells",
+        ]),
+        limit: z.number().int().nonnegative(),
+    })),
+})
+    .superRefine((coverage, context) => {
+    if ((coverage.countMeaning === "complete-total") !== coverage.complete ||
+        (coverage.complete &&
+            (coverage.boundsReached.length !== 0 ||
+                !coverage.heads.complete ||
+                !coverage.recurring.populationComplete ||
+                coverage.completeThrough !== coverage.projectedWindow.to)) ||
+        (!coverage.complete &&
+            (coverage.boundsReached.length === 0 ||
+                coverage.completeThrough !== coverage.projectedWindow.from))) {
+        context.addIssue({
+            code: "custom",
+            message: "Coverage must distinguish complete totals from lower bounds without claiming an unproven time prefix",
+        });
+    }
+});
 export const forecastSchema = z.object({
+    /** Optional for older servers and callers without the coverage capability. */
+    coverage: forecastCoverageSchema.optional(),
     /** Ascending by `start`. A bucket with no occurrences is omitted. */
     buckets: z.array(forecastBucketSchema),
     /**
@@ -391,6 +460,10 @@ export function mergeForecastBuckets(buckets) {
         }
         into.count += bucket.count;
         into.nextFireCount += bucket.nextFireCount;
+        if (bucket.omittedPartitionKeyCount !== undefined) {
+            into.omittedPartitionKeyCount =
+                (into.omittedPartitionKeyCount ?? 0) + bucket.omittedPartitionKeyCount;
+        }
         into.unkeyedCount += bucket.unkeyedCount;
     }
     return [...merged.values()].sort((left, right) => left.bucketStartMs - right.bucketStartMs);
@@ -412,7 +485,7 @@ export function mergeForecastBuckets(buckets) {
 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;
+    let otherPartitionKeyCount = bucket.unkeyedCount + (bucket.omittedPartitionKeyCount ?? 0);
     ranked.forEach(([key, n], index) => {
         if (index < FORECAST_BOUNDS.topPartitionKeys) {
             byPartitionKey[key] = n;
@@ -426,30 +499,20 @@ export function topPartitionKeys(bucket) {
 /**
  * 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.
+ * Unavailable and stale sources always refuse. Work-bound partial answers are
+ * permitted only for a reader that explicitly understands coverage; the
+ * default retains the count-only legacy consumer's safe failure behavior.
  *
  * `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) {
+export function decideForecastAnswer(answers, nowMs, acceptPartial = false) {
     if (answers.some((answer) => "refused" in answer)) {
         return { ok: false, refusal: "partition-unavailable" };
     }
-    if (answers.some((answer) => "truncated" in answer && answer.truncated)) {
+    if (!acceptPartial &&
+        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

package/dist/identifiers.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * Public identifiers.
  *
@@ -37,25 +37,25 @@ export type IdResource = keyof typeof ID_PREFIXES;
 export declare function idPattern(resource: IdResource): RegExp;
 /** Any well-formed public identifier, whatever it names. */
 export declare const ANY_ID_PATTERN: RegExp;
-export declare function idSchema(resource: IdResource): z.ZodString;
-export declare const apiCredentialIdSchema: z.ZodString;
-export declare const apiCredentialEventIdSchema: z.ZodString;
-export declare const authorizationRequestIdSchema: z.ZodString;
-export declare const callbackSigningKeyIdSchema: z.ZodString;
-export declare const oauthClientIdSchema: z.ZodString;
-export declare const oauthGrantIdSchema: z.ZodString;
-export declare const oauthGrantEventIdSchema: z.ZodString;
-export declare const scheduleIdSchema: z.ZodString;
-export declare const occurrenceIdSchema: z.ZodString;
-export declare const attemptIdSchema: z.ZodString;
-export declare const deliveryIdSchema: z.ZodString;
-export declare const endpointIdSchema: z.ZodString;
-export declare const organizationIdSchema: z.ZodString;
-export declare const projectIdSchema: z.ZodString;
-export declare const environmentIdSchema: z.ZodString;
-export declare const eventIdSchema: z.ZodString;
-export declare const testSinkIdSchema: z.ZodString;
-export declare const testSinkDeliveryIdSchema: z.ZodString;
+export declare function idSchema(resource: IdResource): import("zod").ZodString;
+export declare const apiCredentialIdSchema: import("zod").ZodString;
+export declare const apiCredentialEventIdSchema: import("zod").ZodString;
+export declare const authorizationRequestIdSchema: import("zod").ZodString;
+export declare const callbackSigningKeyIdSchema: import("zod").ZodString;
+export declare const oauthClientIdSchema: import("zod").ZodString;
+export declare const oauthGrantIdSchema: import("zod").ZodString;
+export declare const oauthGrantEventIdSchema: import("zod").ZodString;
+export declare const scheduleIdSchema: import("zod").ZodString;
+export declare const occurrenceIdSchema: import("zod").ZodString;
+export declare const attemptIdSchema: import("zod").ZodString;
+export declare const deliveryIdSchema: import("zod").ZodString;
+export declare const endpointIdSchema: import("zod").ZodString;
+export declare const organizationIdSchema: import("zod").ZodString;
+export declare const projectIdSchema: import("zod").ZodString;
+export declare const environmentIdSchema: import("zod").ZodString;
+export declare const eventIdSchema: import("zod").ZodString;
+export declare const testSinkIdSchema: import("zod").ZodString;
+export declare const testSinkDeliveryIdSchema: import("zod").ZodString;
 export type ApiCredentialId = z.infer<typeof apiCredentialIdSchema>;
 export type ApiCredentialEventId = z.infer<typeof apiCredentialEventIdSchema>;
 export type AuthorizationRequestId = z.infer<typeof authorizationRequestIdSchema>;

package/dist/identifiers.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * Public identifiers.
  *