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

package/dist/usage.d.ts

@@ -1,28 +1,65 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 import type { FieldError } from "./problems.js";
 /**
- * What a customer is charged for, and nothing about what it cost to deliver.
+ * A legacy operational aggregate of terminal occurrences.
  *
- * **One terminal occurrence is one billable unit, however many attempts it
- * took.** That is the commercial rule the whole runtime is built around — a
- * retry is our cost, not the customer's — and this surface exists so it is
- * something a customer can see rather than something they are told. A schedule
- * that failed four times and succeeded on the fifth appears here once; the
- * five attempts are on the occurrence's own attempt history, which is the page
- * that answers "what did it cost us".
+ * The published field names predate PAYG and remain for client compatibility.
+ * They are no longer the invoice meter: PAYG charges each logical delivery
+ * attempt, including retries and redeliveries, through the exact billing ledger.
+ * A schedule that failed four times and succeeded on the fifth appears here as
+ * one terminal occurrence and in `billing.ledger` as five distinct attempts.
  *
  * Days are UTC and half-open, aligned to midnight at both ends. A tenant-local
  * boundary would make every bucket a different width for a different customer
  * and could not be one index range; the capacity decision states the budget in
  * UTC days for the same reason.
  *
- * A day with no billable occurrence is **absent** rather than zero. The window
+ * A day with no terminal occurrence is **absent** rather than zero. The window
  * says which days the answer covers, so an absent day is unambiguous, and a
  * quiet month is a short document rather than thirty-one zeroes.
  */
 export declare const USAGE_BOUNDS: {
+    /**
+     * The bucket a caller gets without asking: one UTC day.
+     *
+     * Unchanged from the only width this surface had, so a caller that never
+     * heard of `bucketSeconds` sees exactly what it saw before.
+     */
+    readonly defaultBucketSeconds: 86400;
     /** Days a window covers when the caller names neither end. */
     readonly defaultWindowDays: 31;
+    /**
+     * Buckets one answer may carry.
+     *
+     * A year of hours is 8,784, which is not a chart and not a document anybody
+     * reads — it is a client asking for the widest window at the finest width and
+     * getting a megabyte back. The ceiling is a refusal rather than a truncation,
+     * for the reason the forecast gives: an answer that is quietly short is one a
+     * caller will act on.
+     *
+     * Matched to `FORECAST_BOUNDS.maxBuckets`, because past and future now answer
+     * the same question in the same shape and a client charting both should not
+     * discover that one of them stops earlier.
+     */
+    readonly maxBuckets: 1500;
+    /**
+     * The widest bucket, which is also the default: a day.
+     *
+     * Wider than a day is a question about months, and months are not a whole
+     * number of days — a "monthly" bucket would have to pick a calendar and this
+     * surface is deliberately in UTC days for every tenant.
+     */
+    readonly maxBucketSeconds: 86400;
+    /**
+     * The finest bucket, which is an hour.
+     *
+     * Finer than an hour is not refused for cost — the read is the same indexed
+     * range scan at any width, and the row count depends on the window rather
+     * than the bucket — but because nothing asks for it. The dashboard's finest
+     * chart is hourly, and a width nothing consumes is a width nobody has
+     * checked the arithmetic of.
+     */
+    readonly minBucketSeconds: 3600;
     /**
      * The widest window this contract will describe.
      *
@@ -32,19 +69,20 @@ export declare const USAGE_BOUNDS: {
      */
     readonly maxWindowDays: 366;
 };
-/** How a billable occurrence ended. The four terminal occurrence states. */
+/** How a terminal occurrence ended. The four retained terminal states. */
 export declare const BILLABLE_TERMINAL_STATES: readonly ["cancelled", "skipped_stale", "succeeded", "terminal_failed"];
-export declare const billableTerminalStateSchema: z.ZodEnum<{
+export declare const billableTerminalStateSchema: import("zod").ZodEnum<{
     succeeded: "succeeded";
     cancelled: "cancelled";
     terminal_failed: "terminal_failed";
     skipped_stale: "skipped_stale";
 }>;
 export type BillableTerminalStateName = z.infer<typeof billableTerminalStateSchema>;
-export declare const usageRequestSchema: z.ZodObject<{
-    from: z.ZodOptional<z.ZodString>;
-    to: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
+export declare const usageRequestSchema: import("zod").ZodObject<{
+    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").$strict>;
 export type UsageRequest = z.infer<typeof usageRequestSchema>;
 export type UsageRequestParse = {
     readonly errors: readonly FieldError[];
@@ -65,43 +103,51 @@ export type UsageRequestParse = {
 export declare function parseUsageRequest(query: URLSearchParams): UsageRequestParse;
 /** What a caller is told when a usage window is refused rather than served. */
 export declare const USAGE_WINDOW_REASONS: Readonly<Record<UsageWindowRefusal, string>>;
-export declare const usageDaySchema: z.ZodObject<{
-    billableOccurrences: z.ZodNumber;
-    byTerminalState: z.ZodRecord<z.ZodEnum<{
+export declare const usageDaySchema: import("zod").ZodObject<{
+    billableOccurrences: import("zod").ZodNumber;
+    byTerminalState: import("zod").ZodRecord<import("zod").ZodEnum<{
         succeeded: "succeeded";
         cancelled: "cancelled";
         terminal_failed: "terminal_failed";
         skipped_stale: "skipped_stale";
-    }> & z.core.$partial, z.ZodNumber>;
-    start: z.ZodString;
-}, z.core.$strip>;
+    }> & import("zod/v4/core").$partial, import("zod").ZodNumber>;
+    start: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 export type UsageDayView = z.infer<typeof usageDaySchema>;
-export declare const usageSchema: z.ZodObject<{
-    days: z.ZodArray<z.ZodObject<{
-        billableOccurrences: z.ZodNumber;
-        byTerminalState: z.ZodRecord<z.ZodEnum<{
+export declare const usageSchema: import("zod").ZodObject<{
+    bucketSeconds: import("zod").ZodNumber;
+    days: import("zod").ZodArray<import("zod").ZodObject<{
+        billableOccurrences: import("zod").ZodNumber;
+        byTerminalState: import("zod").ZodRecord<import("zod").ZodEnum<{
             succeeded: "succeeded";
             cancelled: "cancelled";
             terminal_failed: "terminal_failed";
             skipped_stale: "skipped_stale";
-        }> & z.core.$partial, z.ZodNumber>;
-        start: z.ZodString;
-    }, z.core.$strip>>;
-    freshness: z.ZodObject<{
-        kind: z.ZodLiteral<"authoritative">;
-    }, z.core.$strip>;
-    totalBillableOccurrences: z.ZodNumber;
-    window: z.ZodObject<{
-        from: z.ZodString;
-        to: z.ZodString;
-    }, z.core.$strip>;
-}, z.core.$strip>;
+        }> & import("zod/v4/core").$partial, import("zod").ZodNumber>;
+        start: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    freshness: import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"authoritative">;
+    }, import("zod/v4/core").$strip>;
+    plan: import("zod").ZodOptional<import("zod").ZodObject<{
+        attemptsToday: import("zod").ZodNumber;
+        dailyAttemptCeiling: import("zod").ZodNumber;
+        resetsAt: import("zod").ZodString;
+        since: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    totalBillableOccurrences: import("zod").ZodNumber;
+    window: import("zod").ZodObject<{
+        from: import("zod").ZodString;
+        to: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>;
+}, import("zod/v4/core").$strip>;
 export type UsageView = z.infer<typeof usageSchema>;
-export type UsageWindowRefusal = "window-inverted" | "window-too-wide" | "window-unreadable";
+export type UsageWindowRefusal = "too-many-buckets" | "window-inverted" | "window-too-wide" | "window-unreadable";
 export type ResolvedUsageWindow = {
     readonly ok: false;
     readonly refusal: UsageWindowRefusal;
 } | {
+    readonly bucketSeconds: number;
     readonly fromMs: number;
     readonly ok: true;
     readonly toMs: number;
@@ -109,13 +155,23 @@ export type ResolvedUsageWindow = {
 /** UTC midnight of the day an instant falls in. */
 export declare function utcMidnightMs(instantMs: number): number;
 /**
- * Resolve the window a usage request names, aligned to UTC days.
+ * Resolve the window a usage request names, aligned to whole buckets.
+ *
+ * **Both ends are snapped outward, and that is not tidiness.** A window
+ * beginning at nine in the morning would put a partial bucket at the front of
+ * the list with no way for a reader to tell it from a quiet one — a bar that is
+ * short because it is twenty-three minutes long rather than because nothing
+ * happened. Snapping outward means the answer always covers whole buckets and
+ * never covers less than what was asked for.
  *
- * **Both ends are snapped to midnight, and that is not tidiness.** The answer
- * is bucketed by UTC day; a window beginning at nine in the morning would put a
- * partial day at the front of the list with no way for a reader to tell it from
- * a quiet one. Snapping outward — the start of `from`'s day, the start of the
- * day after `to`'s — means the window always covers whole days and never covers
- * less than what was asked for.
+ * **To the bucket rather than to the day, since FXO-2281**, which is the same
+ * argument one width down. It is the same behaviour at the default width: a
+ * day-wide bucket aligned to the epoch starts at UTC midnight, so a caller who
+ * names no width gets exactly the window this always served. An hourly caller
+ * asking for "the last twenty-four hours" would otherwise have both ends pushed
+ * to midnight and be handed up to forty-eight buckets, half of them for a day
+ * they did not ask about.
  */
-export declare function resolveUsageWindow(request: UsageRequest, nowMs: number): ResolvedUsageWindow;
+export declare function resolveUsageWindow(request: Omit<UsageRequest, "bucketSeconds"> & {
+    readonly bucketSeconds?: number;
+}, nowMs: number): ResolvedUsageWindow;

package/dist/usage.js

@@ -1,28 +1,65 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 import { timestampSchema } from "./time.js";
 /**
- * What a customer is charged for, and nothing about what it cost to deliver.
+ * A legacy operational aggregate of terminal occurrences.
  *
- * **One terminal occurrence is one billable unit, however many attempts it
- * took.** That is the commercial rule the whole runtime is built around — a
- * retry is our cost, not the customer's — and this surface exists so it is
- * something a customer can see rather than something they are told. A schedule
- * that failed four times and succeeded on the fifth appears here once; the
- * five attempts are on the occurrence's own attempt history, which is the page
- * that answers "what did it cost us".
+ * The published field names predate PAYG and remain for client compatibility.
+ * They are no longer the invoice meter: PAYG charges each logical delivery
+ * attempt, including retries and redeliveries, through the exact billing ledger.
+ * A schedule that failed four times and succeeded on the fifth appears here as
+ * one terminal occurrence and in `billing.ledger` as five distinct attempts.
  *
  * Days are UTC and half-open, aligned to midnight at both ends. A tenant-local
  * boundary would make every bucket a different width for a different customer
  * and could not be one index range; the capacity decision states the budget in
  * UTC days for the same reason.
  *
- * A day with no billable occurrence is **absent** rather than zero. The window
+ * A day with no terminal occurrence is **absent** rather than zero. The window
  * says which days the answer covers, so an absent day is unambiguous, and a
  * quiet month is a short document rather than thirty-one zeroes.
  */
 export const USAGE_BOUNDS = {
+    /**
+     * The bucket a caller gets without asking: one UTC day.
+     *
+     * Unchanged from the only width this surface had, so a caller that never
+     * heard of `bucketSeconds` sees exactly what it saw before.
+     */
+    defaultBucketSeconds: 86_400,
     /** Days a window covers when the caller names neither end. */
     defaultWindowDays: 31,
+    /**
+     * Buckets one answer may carry.
+     *
+     * A year of hours is 8,784, which is not a chart and not a document anybody
+     * reads — it is a client asking for the widest window at the finest width and
+     * getting a megabyte back. The ceiling is a refusal rather than a truncation,
+     * for the reason the forecast gives: an answer that is quietly short is one a
+     * caller will act on.
+     *
+     * Matched to `FORECAST_BOUNDS.maxBuckets`, because past and future now answer
+     * the same question in the same shape and a client charting both should not
+     * discover that one of them stops earlier.
+     */
+    maxBuckets: 1_500,
+    /**
+     * The widest bucket, which is also the default: a day.
+     *
+     * Wider than a day is a question about months, and months are not a whole
+     * number of days — a "monthly" bucket would have to pick a calendar and this
+     * surface is deliberately in UTC days for every tenant.
+     */
+    maxBucketSeconds: 86_400,
+    /**
+     * The finest bucket, which is an hour.
+     *
+     * Finer than an hour is not refused for cost — the read is the same indexed
+     * range scan at any width, and the row count depends on the window rather
+     * than the bucket — but because nothing asks for it. The dashboard's finest
+     * chart is hourly, and a width nothing consumes is a width nobody has
+     * checked the arithmetic of.
+     */
+    minBucketSeconds: 3_600,
     /**
      * The widest window this contract will describe.
      *
@@ -32,7 +69,7 @@ export const USAGE_BOUNDS = {
      */
     maxWindowDays: 366,
 };
-/** How a billable occurrence ended. The four terminal occurrence states. */
+/** How a terminal occurrence ended. The four retained terminal states. */
 export const BILLABLE_TERMINAL_STATES = [
     "cancelled",
     "skipped_stale",
@@ -42,13 +79,42 @@ export const BILLABLE_TERMINAL_STATES = [
 export const billableTerminalStateSchema = z.enum(BILLABLE_TERMINAL_STATES);
 export const usageRequestSchema = z
     .object({
+    /**
+     * Bucket width in whole seconds, aligned to the epoch.
+     *
+     * **Mirrors `/v1/forecast`'s parameter, deliberately** — past and future
+     * answer the same question about the same book, and a client charting both
+     * should not have to learn two spellings of "by the hour". Seconds as a
+     * number rather than a duration string, which is this product's published
+     * convention.
+     *
+     * A whole number of the finest bucket, so re-aggregating is exact: an
+     * answer whose buckets straddled would be a number nobody can reconcile
+     * against a bill.
+     */
+    bucketSeconds: z
+        .number()
+        .int()
+        .min(USAGE_BOUNDS.minBucketSeconds)
+        .max(USAGE_BOUNDS.maxBucketSeconds)
+        .multipleOf(USAGE_BOUNDS.minBucketSeconds)
+        .default(USAGE_BOUNDS.defaultBucketSeconds),
     /** Inclusive start. Defaults to `defaultWindowDays` before the end. */
     from: timestampSchema.optional(),
     /** Exclusive end. Defaults to the start of tomorrow, UTC. */
     to: timestampSchema.optional(),
 })
     .strict();
-const USAGE_PARAMETERS = ["from", "to"];
+/** `[name, numeric]` — the coercion each parameter needs off a URL. */
+const USAGE_PARAMETERS = [
+    ["bucketSeconds", true],
+    ["from", false],
+    ["to", false],
+];
+/** Query values arrive as strings; only a whole number may become one. */
+function asNumberIfInteger(value) {
+    return /^-?\d+$/u.test(value) ? Number(value) : value;
+}
 /**
  * Read a usage request off a URL.
  *
@@ -61,7 +127,7 @@ const USAGE_PARAMETERS = ["from", "to"];
 export function parseUsageRequest(query) {
     const errors = [];
     const raw = {};
-    for (const field of USAGE_PARAMETERS) {
+    for (const [field, numeric] of USAGE_PARAMETERS) {
         const values = query.getAll(field);
         if (values.length > 1) {
             errors.push({
@@ -73,7 +139,7 @@ export function parseUsageRequest(query) {
         const value = values[0];
         if (value === undefined)
             continue;
-        raw[field] = value;
+        raw[field] = numeric ? asNumberIfInteger(value) : value;
     }
     if (errors.length > 0)
         return { errors, ok: false };
@@ -90,6 +156,7 @@ export function parseUsageRequest(query) {
 }
 /** What a caller is told when a usage window is refused rather than served. */
 export const USAGE_WINDOW_REASONS = {
+    "too-many-buckets": `must not ask for more than ${String(USAGE_BOUNDS.maxBuckets)} buckets; widen bucketSeconds or narrow the window`,
     "window-inverted": "must end after it begins",
     "window-too-wide": `must cover at most ${String(USAGE_BOUNDS.maxWindowDays)} days`,
     "window-unreadable": "must be an RFC 3339 instant",
@@ -97,7 +164,7 @@ export const USAGE_WINDOW_REASONS = {
 export const usageDaySchema = z.object({
     billableOccurrences: z.number().int().positive(),
     /**
-     * How the day's billable occurrences ended.
+     * How the day's terminal occurrences ended.
      *
      * Sums to `billableOccurrences`, and a state with no occurrences is absent
      * rather than zero — the same rule the day list follows, one level down.
@@ -108,7 +175,22 @@ export const usageDaySchema = z.object({
 });
 export const usageSchema = z
     .object({
-    /** Ascending by `start`. Days with no billable occurrence are absent. */
+    /**
+     * The width each entry in `days` covers, in seconds.
+     *
+     * Echoed so a client knows what it got rather than what it asked for, the
+     * way the forecast echoes its own. It is `86400` for every caller that does
+     * not ask, which is what this surface always served.
+     */
+    bucketSeconds: z.number().int().positive(),
+    /**
+     * Ascending by `start`. Buckets with no terminal occurrence are absent.
+     *
+     * **Still named `days`, at a width that may not be one.** Renaming it would
+     * break every caller reading the field to serve callers who asked for an
+     * hourly width — which is nobody until they opt in. `bucketSeconds` above
+     * says what a row spans.
+     */
     days: z.array(usageDaySchema),
     /**
      * Authoritative, because this is the committed model the settlement wrote.
@@ -119,6 +201,44 @@ export const usageSchema = z
      * summary.
      */
     freshness: z.object({ kind: z.literal("authoritative") }),
+    /**
+     * How much of this deployment's daily attempt allowance has been spent.
+     *
+     * **Because nothing else could say it, and something had to.** The runtime
+     * refuses admission once an organization has made
+     * `dailyAttemptCeiling` attempts in a UTC day, and defers every schedule to
+     * the next day boundary rather than failing them. Nothing lost, nothing
+     * failed — and nothing running either, for up to a day, on a product whose
+     * whole job is to run things. The operator found his own account in that
+     * state during the W4-10 walk and no screen anywhere named it: the runs
+     * read "Delivering", the dashboard had no action waiting, and the only
+     * visible trace was an unremarkable number on the billing panel.
+     *
+     * The disposition, the ceiling and the count all lived inside
+     * `DialerWorker` and `EntitlementPolicy`; neither ever left
+     * `packages/application`, and `days` above counts settled *occurrences*
+     * rather than attempts, so it could not be derived either.
+     *
+     * Absent when this deployment sets no ceiling, which is the honest shape
+     * for "there is no allowance to be near the end of" — a surface must not
+     * render a limit nobody has.
+     */
+    plan: z
+        .object({
+        /** Attempts this organization has made since `since`, capped at one past the ceiling. */
+        attemptsToday: z.number().int().nonnegative(),
+        dailyAttemptCeiling: z.number().int().positive(),
+        /**
+         * When the allowance refills — the next UTC day boundary.
+         *
+         * The same instant the runtime defers to, so a page saying "runs
+         * resume at" and a row's own wake cannot disagree.
+         */
+        resetsAt: timestampSchema,
+        /** The start of the day being counted, so a reader can check the window. */
+        since: timestampSchema,
+    })
+        .optional(),
     totalBillableOccurrences: z.number().int().nonnegative(),
     window: z.object({ from: timestampSchema, to: timestampSchema }),
 })
@@ -138,7 +258,7 @@ export const usageSchema = z
     path: ["totalBillableOccurrences"],
 })
     .refine((usage) => usage.days.every((day) => Object.values(day.byTerminalState).reduce((sum, count) => sum + count, 0) === day.billableOccurrences), {
-    message: "byTerminalState must account for every billable occurrence",
+    message: "byTerminalState must account for every terminal occurrence",
     path: ["days"],
 })
     .refine((usage) => usage.days.every((day) => {
@@ -166,35 +286,81 @@ export function utcMidnightMs(instantMs) {
     return Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), at.getUTCDate());
 }
 /**
- * Resolve the window a usage request names, aligned to UTC days.
+ * Resolve the window a usage request names, aligned to whole buckets.
+ *
+ * **Both ends are snapped outward, and that is not tidiness.** A window
+ * beginning at nine in the morning would put a partial bucket at the front of
+ * the list with no way for a reader to tell it from a quiet one — a bar that is
+ * short because it is twenty-three minutes long rather than because nothing
+ * happened. Snapping outward means the answer always covers whole buckets and
+ * never covers less than what was asked for.
  *
- * **Both ends are snapped to midnight, and that is not tidiness.** The answer
- * is bucketed by UTC day; a window beginning at nine in the morning would put a
- * partial day at the front of the list with no way for a reader to tell it from
- * a quiet one. Snapping outward — the start of `from`'s day, the start of the
- * day after `to`'s — means the window always covers whole days and never covers
- * less than what was asked for.
+ * **To the bucket rather than to the day, since FXO-2281**, which is the same
+ * argument one width down. It is the same behaviour at the default width: a
+ * day-wide bucket aligned to the epoch starts at UTC midnight, so a caller who
+ * names no width gets exactly the window this always served. An hourly caller
+ * asking for "the last twenty-four hours" would otherwise have both ends pushed
+ * to midnight and be handed up to forty-eight buckets, half of them for a day
+ * they did not ask about.
  */
-export function resolveUsageWindow(request, nowMs) {
-    const defaultToMs = utcMidnightMs(nowMs) + DAY_MS;
+export function resolveUsageWindow(
+// **The request as a caller may hand it over, not only as the schema hands
+// it back.** `bucketSeconds` carries a `.default()`, which makes it required
+// on the parsed type; a caller resolving a window from a literal `{ from, to }`
+// — which every case here and the contract mock do — is asking the same
+// question and gets the same default from the `??` below.
+request, nowMs) {
+    const bucketSeconds = request.bucketSeconds ?? USAGE_BOUNDS.defaultBucketSeconds;
+    const bucketMs = bucketSeconds * 1_000;
+    /** The start of the bucket an instant falls in, aligned to the epoch. */
+    const floorToBucket = (instantMs) => Math.floor(instantMs / bucketMs) * bucketMs;
+    /**
+     * The end of the bucket an instant falls in — and the instant itself when it
+     * is already a boundary.
+     *
+     * **The `+ bucketMs` here used to be unconditional**, which handed every
+     * caller asking a tidy question one bucket more than it asked for. A
+     * dashboard requesting seven whole days ending at midnight was served eight,
+     * and printed the served window under a heading that said seven. Windows
+     * here are half-open, so an aligned `to` is already exact; only an instant
+     * *inside* a bucket has anything to round up to.
+     *
+     * `defaultToMs` reads the same way and wants to: with `to` omitted the
+     * answer should reach the bucket in progress, and when `now` happens to land
+     * exactly on a boundary the bucket in progress is empty and belongs outside
+     * the window rather than on the end of it as a zero.
+     */
+    const ceilToBucket = (instantMs) => {
+        const floored = floorToBucket(instantMs);
+        return floored === instantMs ? instantMs : floored + bucketMs;
+    };
+    const defaultToMs = ceilToBucket(nowMs);
     const requestedToMs = request.to === undefined ? defaultToMs : Date.parse(request.to);
     if (!Number.isFinite(requestedToMs)) {
         return { ok: false, refusal: "window-unreadable" };
     }
-    const toMs = request.to === undefined
-        ? defaultToMs
-        : utcMidnightMs(requestedToMs) + DAY_MS;
+    const toMs = request.to === undefined ? defaultToMs : ceilToBucket(requestedToMs);
     const requestedFromMs = request.from === undefined
         ? toMs - USAGE_BOUNDS.defaultWindowDays * DAY_MS
         : Date.parse(request.from);
     if (!Number.isFinite(requestedFromMs)) {
         return { ok: false, refusal: "window-unreadable" };
     }
-    const fromMs = utcMidnightMs(requestedFromMs);
+    const fromMs = floorToBucket(requestedFromMs);
     if (fromMs >= toMs)
         return { ok: false, refusal: "window-inverted" };
     if (toMs - fromMs > USAGE_BOUNDS.maxWindowDays * DAY_MS) {
         return { ok: false, refusal: "window-too-wide" };
     }
-    return { fromMs, ok: true, toMs };
+    // **The bucket count, not the read.** The read is one indexed range scan over
+    // `occurrence_usage` at any width — `terminal_state` is an INCLUDE column on
+    // the index it uses, so the whole answer comes from the index and the rows it
+    // touches depend on the window rather than on how they are grouped. What
+    // grows with a finer bucket is the *answer*, and a year of hours is 8,784
+    // rows nobody charts. Refused rather than truncated: a quietly short answer
+    // is one a caller acts on.
+    if ((toMs - fromMs) / bucketMs > USAGE_BOUNDS.maxBuckets) {
+        return { ok: false, refusal: "too-many-buckets" };
+    }
+    return { bucketSeconds, fromMs, ok: true, toMs };
 }