cursedbelt-server 4.18.0 → 4.19.0

package/dist/server/engagement/summary.js

@@ -0,0 +1,127 @@
+/**
+ * One app's engagement, folded into the shape the console draws.
+ *
+ * ── Why the APP does the folding ────────────────────────────────────────────
+ * The same argument `metrics/inventory.ts` makes: the console runs on this Mac
+ * and most of the fleet runs on a checkout-less box reachable only over HTTPS,
+ * so the app that owns the data is the only thing that can read it. Shipping
+ * raw daily rows would also mean shipping the per-day timeline of a household's
+ * private apps across the wire on every poll, when the console draws totals.
+ *
+ * ── Everything here is pure over rows ───────────────────────────────────────
+ * `summarize` takes the three roll-ups and a clock, so `engagement.test.ts`
+ * drives it with hand-written rows and checks arithmetic a human can verify —
+ * which is the whole design constraint at n = 3. No I/O, no `Date.now()`.
+ */
+import { classifyInterest, dayKey, } from "./types.js";
+export function summarize(input) {
+    const { app, now } = input;
+    const users = input.users.map((u) => ({
+        userKey: u.userKey,
+        views: u.views,
+        sessions: u.sessions,
+        activeMs: u.activeMs,
+        firstTs: u.firstTs,
+        lastTs: u.lastTs,
+        places: u.places,
+        interest: classifyInterest({ lastSeenTs: u.lastTs, sessions: u.sessions }, now),
+        daysSinceSeen: Math.max(0, Math.floor((now - u.lastTs) / 86_400_000)),
+    }));
+    // Fold the (user, place) rows down the USER axis to get the per-feature view.
+    const byPlace = new Map();
+    for (const row of input.places) {
+        const existing = byPlace.get(row.place);
+        if (existing) {
+            existing.users += 1;
+            existing.views += row.views;
+            existing.sessions += row.sessions;
+            existing.activeMs += row.activeMs;
+            existing.lastTs = Math.max(existing.lastTs, row.lastTs);
+        }
+        else {
+            byPlace.set(row.place, {
+                place: row.place,
+                users: 1,
+                views: row.views,
+                sessions: row.sessions,
+                activeMs: row.activeMs,
+                lastTs: row.lastTs,
+                msPerView: 0,
+            });
+        }
+    }
+    const places = [...byPlace.values()].map((p) => ({
+        ...p,
+        // Integer ms: a mean over three people does not deserve decimals, and a
+        // whole number is one the owner can sanity-check against a stopwatch.
+        msPerView: p.views > 0 ? Math.round(p.activeMs / p.views) : 0,
+    }));
+    places.sort((a, b) => b.views - a.views || a.place.localeCompare(b.place));
+    // Distinct users per day needs the (user, place, day) grain, which is exactly
+    // why `days()` returns it rather than pre-summed days.
+    const dayAcc = new Map();
+    for (const row of input.days) {
+        let bucket = dayAcc.get(row.day);
+        if (!bucket) {
+            bucket = { views: 0, sessions: 0, users: new Set() };
+            dayAcc.set(row.day, bucket);
+        }
+        bucket.views += row.views;
+        bucket.sessions += row.sessions;
+        bucket.users.add(row.userKey);
+    }
+    const daily = [...dayAcc.entries()]
+        .map(([day, b]) => ({ day, views: b.views, sessions: b.sessions, users: b.users.size }))
+        .sort((a, b) => a.day.localeCompare(b.day));
+    const userPlaces = input.places
+        .map((p) => ({
+        userKey: p.userKey,
+        place: p.place,
+        views: p.views,
+        activeMs: p.activeMs,
+        lastTs: p.lastTs,
+    }))
+        .sort((a, b) => b.views - a.views);
+    return {
+        app,
+        generatedAt: now,
+        users,
+        places,
+        userPlaces,
+        daily,
+        totals: {
+            users: users.length,
+            views: users.reduce((n, u) => n + u.views, 0),
+            sessions: users.reduce((n, u) => n + u.sessions, 0),
+            activeMs: users.reduce((n, u) => n + u.activeMs, 0),
+            returning: users.filter((u) => u.sessions > 1).length,
+            oneTime: users.filter((u) => u.sessions <= 1).length,
+            activeUsers: users.filter((u) => u.interest === "active").length,
+        },
+    };
+}
+/**
+ * The return curve: of the accounts first seen on a given day, how many came
+ * back at least once afterwards.
+ *
+ * Stated as WHOLE ACCOUNTS on a named cohort day rather than as a percentage,
+ * because a percentage of one person is a number that lies confidently. The
+ * console renders "2 of 3 came back" for the same reason.
+ */
+export function returnCurve(users, now, windowDays = 30) {
+    const cutoff = now - windowDays * 86_400_000;
+    const acc = new Map();
+    for (const u of users) {
+        if (u.firstTs < cutoff)
+            continue;
+        const day = dayKey(u.firstTs);
+        const bucket = acc.get(day) ?? { joined: 0, returned: 0 };
+        bucket.joined += 1;
+        if (u.sessions > 1)
+            bucket.returned += 1;
+        acc.set(day, bucket);
+    }
+    return [...acc.entries()]
+        .map(([day, b]) => ({ day, ...b }))
+        .sort((a, b) => a.day.localeCompare(b.day));
+}

package/dist/server/engagement/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The row shapes the engagement store reads and writes, plus the pure policy
+ * re-exported through one door.
+ *
+ * Split out of `store.ts` so `summary.ts` — and the console's BROWSER code,
+ * which types the fetched payload — can import them without pulling in
+ * `bun:sqlite`. A type-only import would be erased, but the console also wants
+ * `classifyInterest` and `dayKey` at runtime to label a row it is rendering,
+ * and importing those from the store module would drag a native sqlite binding
+ * into a Vite build.
+ */
+export { classifyInterest, dayKey, daysSince, ENGAGEMENT_EXCLUDED_APPS, engagementAllowedForApp, foldView, INTEREST_ACTIVE_DAYS, INTEREST_FADING_DAYS, type InterestVerdict, MAX_DWELL_SLICE_MS, normalizePlaceId, OTHER_PLACE, resolvePlace, SESSION_GAP_MS, type ViewFold, } from "./policy.js";
+/** One (user, place, UTC day) bucket. */
+export interface EngagementDay {
+    userKey: string;
+    place: string;
+    day: string;
+    views: number;
+    activeMs: number;
+    sessions: number;
+}
+/** One (user, place) lifetime roll-up — what the retention answers read. */
+export interface EngagementUserPlace {
+    userKey: string;
+    place: string;
+    views: number;
+    sessions: number;
+    activeMs: number;
+    firstTs: number;
+    lastTs: number;
+}
+/** One account's relationship with the whole app. */
+export interface EngagementUser {
+    userKey: string;
+    views: number;
+    sessions: number;
+    activeMs: number;
+    firstTs: number;
+    lastTs: number;
+    /** Distinct places this account has ever opened in this app. */
+    places: number;
+}

package/dist/server/engagement/types.js

@@ -0,0 +1,12 @@
+/**
+ * The row shapes the engagement store reads and writes, plus the pure policy
+ * re-exported through one door.
+ *
+ * Split out of `store.ts` so `summary.ts` — and the console's BROWSER code,
+ * which types the fetched payload — can import them without pulling in
+ * `bun:sqlite`. A type-only import would be erased, but the console also wants
+ * `classifyInterest` and `dayKey` at runtime to label a row it is rendering,
+ * and importing those from the store module would drag a native sqlite binding
+ * into a Vite build.
+ */
+export { classifyInterest, dayKey, daysSince, ENGAGEMENT_EXCLUDED_APPS, engagementAllowedForApp, foldView, INTEREST_ACTIVE_DAYS, INTEREST_FADING_DAYS, MAX_DWELL_SLICE_MS, normalizePlaceId, OTHER_PLACE, resolvePlace, SESSION_GAP_MS, } from "./policy.js";

package/dist/server/maps-budget/mapsBudget.d.ts

@@ -0,0 +1,194 @@
+/**
+ * A HARD, persisted call ceiling for Google Maps Platform — monthly AND daily.
+ *
+ * ── Why this is a package and not a helper in one app ───────────────────────
+ * Two apps had their own copy of it — `apps/orch` (leave-by times) and
+ * `apps/family` (the atlas) — and two consumers is exactly the threshold the
+ * placement law names. The reason to promote rather than to leave them is
+ * sharper than tidiness: **the guarantee is that the ceiling and the network
+ * call cannot be separated**, and a rule living in two files that can drift is a
+ * guarantee with two chances to stop being one. A THIRD copy was the real risk.
+ *
+ * ── 🔴 `cursedbelt-server/maps-budget`, since 4.19.0 (task 345) ──────────────
+ * It was copied again in THIS generation, under two file names —
+ * `apps/family/src/kit/mapsBudget.ts` and `apps/station/src/kit/mapsPlatform.ts`,
+ * 13,408 identical bytes that no basename census could see. It lives here now,
+ * with its suite, as a leaf that imports nothing: an app injects its own
+ * {@link MapsBudgetStore}, so neither app can reach the other's ledger, and the
+ * generic `Api` parameter lets each name its own API set without a shared enum.
+ * It is in the SERVER tier rather than `cursedbelt-core` because a spend ceiling
+ * only means anything where the key is — never in a browser bundle.
+ *
+ * ── The owner's constraint, verbatim (2026-08-08) ───────────────────────────
+ * *"Note I don't want to allow spending with the apis so we have to enforce the
+ * limits for the free tiers if applicable."*
+ *
+ * Maps Platform is unlike the free Google APIs in three ways that together make
+ * a client-side ceiling the only real protection:
+ *
+ *   1. It REQUIRES a billing account. A runaway loop on Gmail or Calendar costs
+ *      nothing; here it bills.
+ *   2. The free allowance is 10,000 events/month per Essentials API. Past that,
+ *      calls cost money rather than failing.
+ *   3. 🔴 **A Cloud BUDGET DOES NOT CAP USAGE — it only alerts.** The only
+ *      server-side hard stop is a per-API QUOTA in Cloud Console, and that step
+ *      is the owner's. This is ours.
+ *
+ * ── 🔴 TWO periods, because a month is not a shape a runaway respects ───────
+ * A monthly cap can be burned inside a single day. A loop that starts on the
+ * 2nd spends the whole allowance by the 3rd and leaves the API dead for the
+ * other 29 — which is the outcome the ceiling exists to PREVENT, arriving by
+ * way of the ceiling itself. So every call is measured against both:
+ *
+ *   · the **month**, which protects the free tier and therefore the bill;
+ *   · the **day**, `dailyCeiling()` of the month's, which catches the loop in
+ *     hours rather than in a billing period.
+ *
+ * The daily number is DERIVED from the monthly one and never written down
+ * twice. Two tables drift, and this module exists because two copies of this
+ * rule already did.
+ *
+ * Both have to pass, and a refusal by either counts nothing. Expected real
+ * volume across ALL APIs is a few dozen calls a day — about 1% of the free
+ * allowance — so a tenth of the month still leaves roughly 10× headroom on the
+ * busiest single API. A ceiling being hit still means something is broken.
+ *
+ * ── Two properties that are not negotiable ─────────────────────────────────
+ * **PERSISTED, never in memory** — BOTH counters. An in-memory counter resets
+ * on every restart, and a crash-loop restarting hourly would reset it hourly —
+ * turning the one safeguard into a formality precisely when something is wrong.
+ * A daily counter is the one a restart-loop would defeat most cheaply, so it is
+ * persisted the same way. Each key embeds its own period, so a new month or a
+ * new day starts at zero with no scheduled reset to fail and no "the machine was
+ * off on the 1st" hole.
+ *
+ * **A corrupted counter fails SAFE**, treated as exhausted rather than as zero —
+ * the daily one exactly as the monthly one, deliberately. The wrong direction
+ * here spends the owner's money, and two fail-safes with different opinions in
+ * one module would be worse than either choice.
+ *
+ * ── What is deliberately NOT here ──────────────────────────────────────────
+ * The typed API callers. `apps/family` talks to eight Maps APIs plus Street
+ * View; `apps/orch` talks to Routes and Weather. They share no call site, only
+ * this rule — and hoisting nine wrappers into a package to give two apps one
+ * counter would be the shared-code version of the same mistake this package
+ * exists to fix. Each app keeps its own ONE DOOR (`maps.ts` in family, pinned by
+ * a test that scans for Google hosts outside it) and both doors consume this.
+ */
+/** Where the counter lives. A tiny KV, so an app can back it with whatever
+ *  durable store it already has — `apps/orch` uses its own settings store,
+ *  `apps/family` uses the `meta` table of the database it already opens. */
+export interface MapsBudgetStore {
+    read: (key: string) => string | null;
+    write: (key: string, value: string) => void;
+}
+/** The two periods a call is measured against. They answer different questions:
+ *  a month says whether the free tier is safe, a day says whether something is
+ *  looping right now — and they come back at different times, which is the
+ *  reason an app is told WHICH one refused. */
+export type BudgetPeriod = "month" | "day";
+export type BudgetVerdict = 
+/** Counted against BOTH periods. The caller may make exactly the request it
+ *  asked for. `used`/`ceiling` are the MONTH's — the figure a health surface
+ *  has always shown; `usage()` reports the day beside it. */
+{
+    allowed: true;
+    used: number;
+    ceiling: number;
+}
+/**
+ * 🔴 Refused. The caller must DEGRADE LOUDLY — never skip silently, and never
+ * make the call anyway. `reason` is viewer-facing; `fix` is for whoever has to
+ * do something about it, and is empty when the app has nothing to add.
+ *
+ * `used`, `ceiling`, `scope` and `period` all describe the ONE period that
+ * refused, so a caller can say when the API comes back without re-deriving it.
+ */
+ | {
+    allowed: false;
+    used: number;
+    ceiling: number;
+    scope: BudgetPeriod;
+    period: string;
+    reason: string;
+    fix: string;
+};
+/** What an app is told when it must explain a refusal. */
+export interface RefusalContext<Api extends string> {
+    api: Api;
+    /** Calls already spent in the period that refused, or that period's ceiling
+     *  when the counter is unreadable — never `Infinity`, so it is always
+     *  printable. */
+    used: number;
+    /** The ceiling of the period that refused — the MONTH's ceiling for a monthly
+     *  refusal, a tenth of it for a daily one. */
+    ceiling: number;
+    /** Which ceiling refused. 🔴 An app that words both cases the same is telling
+     *  a viewer the map is off for a month when it is off until midnight. */
+    scope: BudgetPeriod;
+    /** The period that refused: `YYYY-MM` for a month, `YYYY-MM-DD` for a day. */
+    period: string;
+    /** True when the counter could not be read and was failed safe. The wording
+     *  for that case is genuinely different: nothing was necessarily spent. */
+    corrupted: boolean;
+}
+export interface MapsBudget<Api extends string> {
+    /**
+     * Check AND count in one step, immediately before the request.
+     *
+     * 🔴 The order is the whole point: counting after the call would count
+     * correctly and protect nothing. `calls` is for a BATCH endpoint (family's
+     * elevation lookup sends 100 points in one request) and a batch that would
+     * cross EITHER line is refused whole rather than truncated — half an answer
+     * drawn as a complete one is worse than a labeled absence.
+     */
+    consume(api: Api, calls?: number): BudgetVerdict;
+    /** Read-only, for a health surface. Both periods, because the one that will
+     *  actually refuse the next call is usually the day, and a surface showing
+     *  only "12 of 3000" would read as healthy while the API is off until
+     *  midnight. */
+    usage(api: Api): {
+        api: Api;
+        used: number;
+        ceiling: number;
+        period: string;
+        day: {
+            used: number;
+            ceiling: number;
+            period: string;
+        };
+    };
+}
+/** `YYYY-MM` in local time — the period a monthly allowance is measured over. */
+export declare const monthKey: (at: number) => string;
+/** `YYYY-MM-DD` in local time — the period the daily sub-ceiling is measured
+ *  over. Local, like `monthKey`, so "today" means the owner's today. */
+export declare const dayKey: (at: number) => string;
+/** How much of a month's allowance one day may take. A tenth: expected use is a
+ *  few dozen calls a day against ceilings sized ~100× that, so a tenth still
+ *  leaves roughly 10× headroom on the busiest API while stopping a runaway in
+ *  hours instead of in a billing period. */
+export declare const DAILY_SHARE_OF_MONTH = 10;
+/**
+ * The daily sub-ceiling, DERIVED — never a second table.
+ *
+ * Rounded UP, so a ceiling of 1 stays reachable (a tenth of it rounded down
+ * would be zero, i.e. an API switched off by arithmetic) and every API keeps at
+ * least one call a day.
+ */
+export declare const dailyCeiling: (monthlyCeiling: number) => number;
+export interface MapsBudgetOptions<Api extends string> {
+    store: MapsBudgetStore;
+    /** The ceiling per API. Every API the app may call must appear, so adding one
+     *  is a deliberate act — a new line in the owner's bill and a new row here. */
+    ceilings: Record<Api, number>;
+    /** How this app words a refusal. Supplied by the app rather than templated
+     *  here because the audience differs: family's reaches a relative looking at a
+     *  map, orch's reaches the owner's notification bell. */
+    refusal: (context: RefusalContext<Api>) => {
+        reason: string;
+        fix?: string;
+    };
+    now?: () => number;
+}
+export declare function createMapsBudget<Api extends string>(options: MapsBudgetOptions<Api>): MapsBudget<Api>;

package/dist/server/maps-budget/mapsBudget.js

@@ -0,0 +1,193 @@
+/**
+ * A HARD, persisted call ceiling for Google Maps Platform — monthly AND daily.
+ *
+ * ── Why this is a package and not a helper in one app ───────────────────────
+ * Two apps had their own copy of it — `apps/orch` (leave-by times) and
+ * `apps/family` (the atlas) — and two consumers is exactly the threshold the
+ * placement law names. The reason to promote rather than to leave them is
+ * sharper than tidiness: **the guarantee is that the ceiling and the network
+ * call cannot be separated**, and a rule living in two files that can drift is a
+ * guarantee with two chances to stop being one. A THIRD copy was the real risk.
+ *
+ * ── 🔴 `cursedbelt-server/maps-budget`, since 4.19.0 (task 345) ──────────────
+ * It was copied again in THIS generation, under two file names —
+ * `apps/family/src/kit/mapsBudget.ts` and `apps/station/src/kit/mapsPlatform.ts`,
+ * 13,408 identical bytes that no basename census could see. It lives here now,
+ * with its suite, as a leaf that imports nothing: an app injects its own
+ * {@link MapsBudgetStore}, so neither app can reach the other's ledger, and the
+ * generic `Api` parameter lets each name its own API set without a shared enum.
+ * It is in the SERVER tier rather than `cursedbelt-core` because a spend ceiling
+ * only means anything where the key is — never in a browser bundle.
+ *
+ * ── The owner's constraint, verbatim (2026-08-08) ───────────────────────────
+ * *"Note I don't want to allow spending with the apis so we have to enforce the
+ * limits for the free tiers if applicable."*
+ *
+ * Maps Platform is unlike the free Google APIs in three ways that together make
+ * a client-side ceiling the only real protection:
+ *
+ *   1. It REQUIRES a billing account. A runaway loop on Gmail or Calendar costs
+ *      nothing; here it bills.
+ *   2. The free allowance is 10,000 events/month per Essentials API. Past that,
+ *      calls cost money rather than failing.
+ *   3. 🔴 **A Cloud BUDGET DOES NOT CAP USAGE — it only alerts.** The only
+ *      server-side hard stop is a per-API QUOTA in Cloud Console, and that step
+ *      is the owner's. This is ours.
+ *
+ * ── 🔴 TWO periods, because a month is not a shape a runaway respects ───────
+ * A monthly cap can be burned inside a single day. A loop that starts on the
+ * 2nd spends the whole allowance by the 3rd and leaves the API dead for the
+ * other 29 — which is the outcome the ceiling exists to PREVENT, arriving by
+ * way of the ceiling itself. So every call is measured against both:
+ *
+ *   · the **month**, which protects the free tier and therefore the bill;
+ *   · the **day**, `dailyCeiling()` of the month's, which catches the loop in
+ *     hours rather than in a billing period.
+ *
+ * The daily number is DERIVED from the monthly one and never written down
+ * twice. Two tables drift, and this module exists because two copies of this
+ * rule already did.
+ *
+ * Both have to pass, and a refusal by either counts nothing. Expected real
+ * volume across ALL APIs is a few dozen calls a day — about 1% of the free
+ * allowance — so a tenth of the month still leaves roughly 10× headroom on the
+ * busiest single API. A ceiling being hit still means something is broken.
+ *
+ * ── Two properties that are not negotiable ─────────────────────────────────
+ * **PERSISTED, never in memory** — BOTH counters. An in-memory counter resets
+ * on every restart, and a crash-loop restarting hourly would reset it hourly —
+ * turning the one safeguard into a formality precisely when something is wrong.
+ * A daily counter is the one a restart-loop would defeat most cheaply, so it is
+ * persisted the same way. Each key embeds its own period, so a new month or a
+ * new day starts at zero with no scheduled reset to fail and no "the machine was
+ * off on the 1st" hole.
+ *
+ * **A corrupted counter fails SAFE**, treated as exhausted rather than as zero —
+ * the daily one exactly as the monthly one, deliberately. The wrong direction
+ * here spends the owner's money, and two fail-safes with different opinions in
+ * one module would be worse than either choice.
+ *
+ * ── What is deliberately NOT here ──────────────────────────────────────────
+ * The typed API callers. `apps/family` talks to eight Maps APIs plus Street
+ * View; `apps/orch` talks to Routes and Weather. They share no call site, only
+ * this rule — and hoisting nine wrappers into a package to give two apps one
+ * counter would be the shared-code version of the same mistake this package
+ * exists to fix. Each app keeps its own ONE DOOR (`maps.ts` in family, pinned by
+ * a test that scans for Google hosts outside it) and both doors consume this.
+ */
+/** `YYYY-MM` in local time — the period a monthly allowance is measured over. */
+export const monthKey = (at) => {
+    const d = new Date(at);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+};
+/** `YYYY-MM-DD` in local time — the period the daily sub-ceiling is measured
+ *  over. Local, like `monthKey`, so "today" means the owner's today. */
+export const dayKey = (at) => {
+    const d = new Date(at);
+    return `${monthKey(at)}-${String(d.getDate()).padStart(2, "0")}`;
+};
+/** How much of a month's allowance one day may take. A tenth: expected use is a
+ *  few dozen calls a day against ceilings sized ~100× that, so a tenth still
+ *  leaves roughly 10× headroom on the busiest API while stopping a runaway in
+ *  hours instead of in a billing period. */
+export const DAILY_SHARE_OF_MONTH = 10;
+/**
+ * The daily sub-ceiling, DERIVED — never a second table.
+ *
+ * Rounded UP, so a ceiling of 1 stays reachable (a tenth of it rounded down
+ * would be zero, i.e. an API switched off by arithmetic) and every API keeps at
+ * least one call a day.
+ */
+export const dailyCeiling = (monthlyCeiling) => Math.ceil(monthlyCeiling / DAILY_SHARE_OF_MONTH);
+export function createMapsBudget(options) {
+    const now = options.now ?? Date.now;
+    /**
+     * 🔴 The monthly key is UNCHANGED (`maps-budget.<api>.2026-09`) — live stores
+     * hold counts under it. The daily one is the same shape with the day on the
+     * end (`…2026-09-11`), so the two can never collide and no migration is
+     * needed: the first call of a new day simply starts a new counter at zero.
+     *
+     * The store is read/write only — deliberately, so an app can back it with any
+     * KV it already has — which means nothing prunes yesterday's keys. That is
+     * a few hundred bytes per API per year, and cheaper than an interface that
+     * can delete rows in the owner's database.
+     */
+    const key = (api, period) => `maps-budget.${api}.${period}`;
+    const readCount = (api, period) => {
+        const raw = Number(options.store.read(key(api, period)) ?? 0);
+        // 🔴 Fails SAFE — see the header. Exhausted, never zero. The daily counter
+        // takes the same reading for the same reason; two fail-safes with different
+        // opinions would be worse than either.
+        return Number.isFinite(raw) && raw >= 0 ? raw : Number.POSITIVE_INFINITY;
+    };
+    /** Both lines for `api` at this instant — the month, then the day. */
+    const linesFor = (api, at) => {
+        const monthly = options.ceilings[api];
+        return [
+            { scope: "month", period: monthKey(at), ceiling: monthly },
+            { scope: "day", period: dayKey(at), ceiling: dailyCeiling(monthly) },
+        ];
+    };
+    return {
+        consume(api, calls = 1) {
+            const at = now();
+            const [month, day] = linesFor(api, at);
+            const monthUsed = readCount(api, month.period);
+            const dayUsed = readCount(api, day.period);
+            /**
+             * 🔴 The MONTH is tested first, and the order is not cosmetic: it decides
+             * what a viewer is told when both are spent, and only one answer is true
+             * then. "Off until midnight" is a promise the budget cannot keep once the
+             * month is gone; "off until the month ends" is right in both cases.
+             */
+            const refused = monthUsed + calls > month.ceiling
+                ? { line: month, used: monthUsed }
+                : dayUsed + calls > day.ceiling
+                    ? { line: day, used: dayUsed }
+                    : null;
+            if (refused) {
+                const corrupted = !Number.isFinite(refused.used);
+                const used = corrupted ? refused.line.ceiling : refused.used;
+                const spoken = options.refusal({
+                    api,
+                    used,
+                    ceiling: refused.line.ceiling,
+                    scope: refused.line.scope,
+                    period: refused.line.period,
+                    corrupted,
+                });
+                return {
+                    allowed: false,
+                    used,
+                    ceiling: refused.line.ceiling,
+                    scope: refused.line.scope,
+                    period: refused.line.period,
+                    reason: spoken.reason,
+                    fix: spoken.fix ?? "",
+                };
+            }
+            // Both fit, so both are counted. A refusal above wrote nothing at all —
+            // a call that did not happen must not be charged to either period.
+            options.store.write(key(api, month.period), String(monthUsed + calls));
+            options.store.write(key(api, day.period), String(dayUsed + calls));
+            return { allowed: true, used: monthUsed + calls, ceiling: month.ceiling };
+        },
+        usage(api) {
+            const [month, day] = linesFor(api, now());
+            // A corrupted counter reports its ceiling rather than `Infinity`, so a
+            // health surface prints a number and reads as exhausted — which is how
+            // `consume` is about to treat it.
+            const spent = (line) => {
+                const used = readCount(api, line.period);
+                return Number.isFinite(used) ? used : line.ceiling;
+            };
+            return {
+                api,
+                used: spent(month),
+                ceiling: month.ceiling,
+                period: month.period,
+                day: { used: spent(day), ceiling: day.ceiling, period: day.period },
+            };
+        },
+    };
+}