@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/health-report.d.ts

@@ -0,0 +1,1766 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Shared shape for the `/api/health` endpoints (AGL-1102).
+ *
+ * Both the console and the tenant runtime answer this, and they must answer it
+ * IDENTICALLY — an uptime series is only comparable across services if the
+ * status codes and the field names agree. Two near-identical route files would
+ * have drifted the first time one of them was touched.
+ *
+ * The rules encoded here, each of which is a way health checks routinely lie:
+ *
+ * **The status code is the contract.** Most uptime monitors read nothing else,
+ * so a degraded dependency has to be a 503. A 200 whose body says "degraded"
+ * is a signal nobody receives.
+ *
+ * **Never cacheable.** A cached health check returns 200 from the edge while
+ * the origin is on fire, and the graph stays green straight through the
+ * outage. Three separate caches have faked a green check in this repo already,
+ * so this sets `no-store` on every response including the failures — an error
+ * response is the one you least want served from a cache.
+ *
+ * **No internals in the body.** It is public and unauthenticated, so a failing
+ * check reports a CODE and never the underlying message, which can carry
+ * project ids, paths or credentials fragments.
+ */
+export interface HealthCheck {
+    ok: boolean;
+    /** How long the dependency took. The number that turns into a latency graph. */
+    ms: number;
+    /** A stable code on failure — never a raw error message. */
+    code?: string;
+}
+export interface HealthReport {
+    service: string;
+    checks: Record<string, HealthCheck>;
+    commit?: string | null;
+    /**
+     * Which VERSION of the platform answered (AGL-2091).
+     *
+     * `commit` alone could only ever be answered on Aglyn's own cloud, so a
+     * self-host operator had nothing to quote in a bug report and no way to ask
+     * whether a fix had reached them. This is the field that answers it, and
+     * unlike the commit it needs no operator configuration —
+     * `platformVersion()` reads the number the build inlined from package.json.
+     */
+    version?: string | null;
+    environment?: string | null;
+    region?: string | null;
+    /** Injected so the body is deterministic in tests. */
+    at?: string;
+}
+export declare const HEALTH_NO_STORE = "no-store, no-cache, must-revalidate, max-age=0";
+/** Degraded if ANY check failed. There is no partial credit for uptime. */
+export declare function healthStatus(checks: Record<string, HealthCheck>): 'ok' | 'degraded';
+export declare function healthBody(report: HealthReport): Record<string, unknown>;
+export declare function healthHeaders(status: 'ok' | 'degraded'): Record<string, string>;
+export declare function healthHttpStatus(status: 'ok' | 'degraded'): number;
+/**
+ * A HEAD response for a health endpoint: the SAME status and headers its GET
+ * would return, with no body (AGL-1148).
+ *
+ * ## Why this exists
+ *
+ * Every health route used to answer HEAD with a hardcoded `200` and the
+ * comment "cheap liveness for monitors that only issue HEAD. Touches
+ * nothing." Touching nothing is precisely the problem: **a HEAD that knows
+ * nothing is a health check that cannot go red.** A monitor configured with
+ * HEAD — which several uptime providers use by default — would have reported
+ * green through any outage that left the function able to boot, which is most
+ * of them. `/api/health/crons` sat at 503 for fifty-one hours; a HEAD monitor
+ * pointed at it would have agreed with the green board the whole time.
+ *
+ * It also violated the contract this file opens with. "The status code is the
+ * contract" cannot hold for one method and not another, and HTTP requires a
+ * HEAD response to carry the same status and headers its GET would.
+ *
+ * ## The cost argument, which is why this is safe
+ *
+ * Delegating to GET means HEAD runs the dependency probe. Every route
+ * memoizes that probe (`memoizeWithTtl`, 15s on the root and 5 minutes on the
+ * subsystems) explicitly so a public unauthenticated endpoint cannot be made
+ * to read in a loop — the same bound that already lets a fifteen-minute probe
+ * hit seven endpoints for nearly nothing. HEAD now costs exactly what GET
+ * costs, which is a memo lookup between refreshes, and it serializes no body.
+ *
+ * Headers are carried over rather than rebuilt so `Cache-Control: no-store`,
+ * the open CORS origin and `Retry-After` reach a HEAD client identically — a
+ * HEAD response that was cacheable while its GET was not would be the same
+ * lie one layer down.
+ */
+export declare function healthHeadOf(get: () => Promise<Response>): Promise<Response>;
+/**
+ * Firestore backup state, reduced to a health verdict (AGL-1490, AGL-1502).
+ *
+ * The 2026-08-02 backup sat at `NOT_AVAILABLE` for eleven days and nothing
+ * noticed — the schedule ran, the API reported the failure, and no one was
+ * listening. This turns "is the newest backup real and recent" into the same
+ * 200/503 contract the other health checks speak, so the existing uptime
+ * probe + alert path is the listener.
+ *
+ * Pure on purpose: the route fetches, this decides, the spec exercises every
+ * branch without a network.
+ */
+export interface BackupSnapshot {
+    /** `READY` | `CREATING` | `NOT_AVAILABLE` (or whatever the API adds next). */
+    state?: string;
+    /** ISO timestamp of the data the backup captured. */
+    snapshotTime?: string;
+}
+export interface BackupsCheck extends HealthCheck {
+    /**
+     * Histogram by state — `{ READY: 1, NOT_AVAILABLE: 1 }`. Counts only: the
+     * endpoint is public, and backup ids or resource paths have no business in
+     * it. Counts are enough to know WHAT is wrong before opening gcloud.
+     */
+    states: Record<string, number>;
+    /** Age of the newest READY backup, in days. Null when there is none. */
+    newestReadyAgeDays: number | null;
+    /**
+     * Present, and always `false`, ONLY in the third state (AGL-1843): the
+     * check could not determine whether backups are healthy. Omitted entirely
+     * from a real verdict, exactly as `code` is omitted from a healthy one, so
+     * `ok: true` with no `determinate` key means "measured, and fine".
+     *
+     * An indeterminate check reports `ok: true` and therefore does not page.
+     * That is deliberate and it is bounded — see the escalation note in
+     * `backupsHealth`.
+     */
+    determinate?: false;
+}
+/**
+ * Weekly Sunday schedule + one day of slack. A healthy cadence never exceeds
+ * 7; day 8 means the last run produced nothing usable.
+ */
+export declare const MAX_BACKUP_AGE_DAYS = 8;
+/**
+ * `backups` is the listing, or `null` when it could not be read at all.
+ *
+ * `options.unreachable` is `ListBackupsResponse.unreachable` — the locations
+ * the API could not reach. Non-empty means the listing is a PARTIAL result
+ * set. `options.code` is the code to report when `backups` is `null`.
+ */
+export declare function backupsHealth(backups: BackupSnapshot[] | null, ms: number, now?: number, options?: {
+    unreachable?: string[];
+    code?: string;
+}): BackupsCheck;
+/**
+ * GCS export freshness, reduced to a health verdict (AGL-1843).
+ *
+ * Exports are NOT managed backups — they are the independent copy that exists
+ * BECAUSE the managed backups proved unreliable (every backup this project
+ * took flipped `READY` → `NOT_AVAILABLE` at roughly one week old, AGL-1843).
+ * A weekly `exportDocuments` run writes portable snapshot files to a GCS
+ * bucket, and this check watches that the newest one is real and recent, so
+ * a managed-backup flip no longer means "one copy only". The two are kept as
+ * SEPARATE checks in the same endpoint precisely so the body says which layer
+ * is degraded rather than blending them into one dishonest verdict.
+ *
+ * The input is the list of `*.overall_export_metadata` completion markers —
+ * Firestore writes exactly one per FINISHED export, so the marker's creation
+ * time is the moment the export completed, not the moment it started. An
+ * export that hangs forever never produces a marker and fails the age rule,
+ * the same trick `backupsHealth` plays with `CREATING`.
+ *
+ * Pure on purpose, like its siblings: the route lists, this decides, the
+ * spec exercises every branch without a network.
+ */
+export interface ExportMarker {
+    /** ISO timestamp the completion marker was written — when the export FINISHED. */
+    timeCreated?: string;
+}
+export interface ExportsCheck extends HealthCheck {
+    /**
+     * Completed exports currently retained. A COUNT only — the endpoint is
+     * public, and bucket names or object paths have no business in it. Null
+     * when the listing itself failed.
+     */
+    exportCount: number | null;
+    /** Age of the newest completed export, in days. Null when there is none. */
+    newestExportAgeDays: number | null;
+}
+/**
+ * Weekly cadence (Mondays, `scheduled-crons.yml`) + one day of slack — the
+ * same budget as `MAX_BACKUP_AGE_DAYS`, for the same reason: a schedule that
+ * stops producing is as broken as one that fails.
+ */
+export declare const MAX_EXPORT_AGE_DAYS = 8;
+export declare function exportsHealth(markers: ExportMarker[] | null, ms: number, now?: number): ExportsCheck;
+/**
+ * Org-creation volume, reduced to a health verdict (AGL-1536).
+ *
+ * The detection layer over the AGL-1534 rate limit: the limiter bounds each
+ * uid (3/h) and each IP (10/h), so a distributed farm holding every actor
+ * under both caps is invisible to it — but visible in aggregate. This turns
+ * "how many orgs appeared in the trailing hour" into the same 200/503
+ * contract the other health checks speak, so the existing uptime check +
+ * alert + email path is the listener, and a wave becomes an email instead of
+ * a surprise. The manual response lever is the AGL-1510 signups feature-lock.
+ *
+ * Pure on purpose, like `backupsHealth`: the route counts, this decides, the
+ * spec exercises every branch without a network.
+ */
+export interface SignupsCheck extends HealthCheck {
+    /**
+     * Orgs created inside the trailing window. A COUNT only — the endpoint is
+     * public, and org names, slugs or owners have no business in it. Null when
+     * the count query itself failed.
+     */
+    recentOrgCreations: number | null;
+    /** The trailing window the count covers, so the body is self-describing. */
+    windowMinutes: number;
+    /** The count above which this reports degraded. */
+    threshold: number;
+}
+/** Trailing window the org-creation count covers. */
+export declare const ORG_CREATION_WINDOW_MINUTES = 60;
+/**
+ * Degraded above 10 creations/hour. Calibrated against two facts: production
+ * holds 4 orgs TOTAL (2026-08), so the organic baseline is ~zero per hour;
+ * and the AGL-1534 per-IP cap is 10/h, so a single maxed-out address can
+ * never trip this — 11+/h necessarily means multiple addresses, which is
+ * exactly the distributed signature the rate limiter cannot see. If a launch
+ * day legitimately beats this, the alert asks a human to glance at the orgs
+ * list and enjoy the view; that is the correct outcome, not a false positive.
+ */
+export declare const MAX_ORG_CREATIONS_PER_WINDOW = 10;
+export declare function signupsHealth(recentOrgCreations: number | null, ms: number, threshold?: number): SignupsCheck;
+/**
+ * Refused org creations, reduced to a health verdict (AGL-1907).
+ *
+ * `signupsHealth` above counts the signups that SUCCEEDED. That is the right
+ * alarm for a wave that gets through, and the wrong one for a wave that is
+ * being contained: when the AGL-1534 limiter starts refusing, org-creation
+ * volume goes *down*, so the check that watches volume reads calmer at exactly
+ * the moment scripted pressure arrives. The 429s are the signature. Before the
+ * doors open on Sep 1 this is also the only thing that can answer "has the
+ * limiter ever actually fired in production" — a control nobody has seen
+ * refuse is a control nobody has tested.
+ *
+ * Counted from `rateLimits/signupRefused_{minuteBucket}` markers, which carry
+ * per-reason counts and no identifiers. This is a separate check rather than
+ * more fields on `SignupsCheck` so the AGL-1536 verdict keeps its meaning
+ * exactly: a creation wave and a refusal wave are different events with
+ * different responses (feature-lock the signups door vs. leave the limiter to
+ * do its job and go read the refusal reasons).
+ *
+ * Pure on purpose, like its siblings: the route queries, this decides.
+ */
+export interface SignupRefusalMarker {
+    /** Refused attempts merged into this minute bucket. */
+    refusals?: number;
+    /**
+     * Split by what refused: `{ uid?: n, ip?: n, locked?: n, held?: n }`.
+     *
+     * `uid` and `ip` are the AGL-1534 rate limiter's two caps. `locked` and
+     * `held` come from the `beforeUserCreated` blocking function (AGL-2583) — a
+     * door the limiter never sees, because it decides account creation on the
+     * Identity Platform path before any Aglyn route runs.
+     */
+    byReason?: Record<string, number>;
+    /**
+     * Account creations the blocking function admitted BLIND: the signups lock
+     * could not be read and nothing this instance remembered said it was pulled
+     * (AGL-2583).
+     *
+     * Deliberately its own field rather than another `byReason` entry. Nobody
+     * was refused, so folding it into the refusal split would make both counts
+     * lie — and it is graded on its own terms below.
+     */
+    unreadable?: number;
+    /** When the most recent refusal in this bucket happened. */
+    refusedAtMs?: number;
+}
+export interface SignupRefusalsCheck extends HealthCheck {
+    /**
+     * Refused org creations inside the trailing window. A COUNT only — the
+     * endpoint is public, and the limiter's keys are a uid and a hashed client
+     * IP. Null when the query itself failed.
+     */
+    refusedSignups: number | null;
+    /**
+     * Which cap did the refusing. A run that is almost all `ip` is one address
+     * hammering; a run that is almost all `uid` is many accounts each pushing
+     * past three, which is the distributed shape. Null when the query failed.
+     */
+    refusedByReason: Record<string, number> | null;
+    /**
+     * Account creations decided WITHOUT the signups lock being readable
+     * (AGL-2583). Graded on its own, at zero tolerance, because it is
+     * categorically different from every entry in `refusedByReason`: those are
+     * controls working as designed, this is the platform answering the signups
+     * question without being able to consult it, and one of those is one too
+     * many. Null when the query itself failed.
+     */
+    lockUnreadable: number | null;
+    /** Minutes since the most recent refusal, so the body dates itself. */
+    minutesSinceLast: number | null;
+    /** The trailing window the count covers, so the body is self-describing. */
+    windowMinutes: number;
+    /** The count above which this reports degraded. */
+    threshold: number;
+}
+/**
+ * Trailing window the refusal count covers. One hour, matching the limiter's
+ * own window (`org-create` is 3/h and 10/h) so the number is readable against
+ * the caps that produced it.
+ */
+export declare const SIGNUP_REFUSAL_WINDOW_MINUTES = 60;
+/**
+ * Degraded above 50 refusals/hour.
+ *
+ * Not zero, unlike the limiter-degradation alarm: a refusal is the system
+ * working, and a real person who fumbles a workspace slug four times in an
+ * hour produces one. The number that means something is *sustained* refusal.
+ * Calibrated the same way AGL-1536's was: production holds single-digit orgs
+ * (2026-08), so organic refusals are ~zero per hour, and 50 is far above any
+ * plausible human while being reached in under a minute by a script. One
+ * determined address can generate this alone — that is intended, because "one
+ * address is hammering the signup door" is worth an email even though the
+ * limiter is containing it.
+ */
+export declare const MAX_SIGNUP_REFUSALS_PER_WINDOW = 50;
+/**
+ * The marker field the blocking function counts blind decisions under
+ * (AGL-2583).
+ *
+ * `signupsCreationVerdict` answers `locked` when a completed read found the
+ * lever pulled, `held` when a failed read fell back on an earlier one that
+ * had, and — the case this names — admits the account when the read failed
+ * and nothing remembered said the lever was pulled. That last one refuses
+ * nobody, so it is not a `byReason` entry; it is the platform deciding the
+ * signups question without being able to consult it, which is the visible
+ * edge of a Firestore read outage on the account-creation path. AGL-2581 was
+ * three days of that same read failing, and its only trace was a
+ * `logger.warn` nothing alerts on.
+ */
+export declare const SIGNUP_LOCK_UNREADABLE_FIELD = "unreadable";
+/**
+ * Blind signups-lock decisions tolerated per window: NONE.
+ *
+ * Deliberately not calibrated like `MAX_SIGNUP_REFUSALS_PER_WINDOW` above,
+ * which is a volume threshold over refusals that mean the system is working.
+ * A blind decision is never routine — a single one says the signups lock was
+ * unreadable at least once, and the lock is unenforceable for as long as that
+ * lasts. False positives here cost a glance at one endpoint.
+ */
+export declare const MAX_UNREADABLE_SIGNUP_DECISIONS_PER_WINDOW = 0;
+export declare function signupRefusalsHealth(markers: SignupRefusalMarker[] | null, ms: number, now?: number, threshold?: number, windowMinutes?: number, unreadableThreshold?: number): SignupRefusalsCheck;
+/**
+ * NOBODY GOT AN ACCOUNT WHILE PEOPLE WERE TRYING (AGL-2583).
+ *
+ * `signupsHealth` watches for a FLOOD. Its healthiest possible reading —
+ * zero orgs created in the trailing hour — is also what total failure looks
+ * like, so the monitor named "signups" reports green precisely when nobody
+ * can sign up. That is not a hypothetical: account creation was refused for
+ * every visitor from Sep 1 to Sep 4 (AGL-2581) and the signup check was
+ * green through all of it, because zero is comfortably under ten.
+ *
+ * ## Zero is only a signal next to a denominator
+ *
+ * Alone, "no accounts this hour" describes a quiet Tuesday night as loudly as
+ * an outage, and an alarm that fires on quiet nights is an alarm everyone
+ * mutes. What makes zero mean something is TRAFFIC: people arrived at the
+ * signup page and none of them ended up with an account.
+ *
+ * ## The denominator is ATTEMPTS, and was once SERVES (AGL-2714)
+ *
+ * It began as signup-page serves — `signupServed_` markers written when the
+ * page asks `/api/lockdown-status?feature=signups`, the one server request
+ * every rendering makes. That counts LOOKERS: crawlers, link previews, a
+ * person reading the plan names and closing the tab. On 2026-09-09 it paged
+ * "Signups is down" on an hour with six such hits and no account, while the
+ * signup page rendered clean, the lockdown was off, all seven auth doors were
+ * green and not one signup had been refused. One of the six was the
+ * diagnostic load made while investigating the alert.
+ *
+ * At this platform's conversion rate a quiet hour and a broken door produce
+ * the same reading, so no threshold on serves could separate them. The
+ * quantity was wrong, not the number.
+ *
+ * `signupAttempted_` markers are the right one: written at the top of
+ * `/api/orgs/create` before any outcome is known, so an attempt means
+ * somebody authenticated, filled the form and asked for an org. Arrivals with
+ * no account is then a statement about the door rather than about demand.
+ *
+ * Writing the marker BEFORE the outcome is what makes this stronger than the
+ * refusal check beside it: `signupRefusals` counts what the route chose to
+ * turn away, so a request that 500s, hangs, or dies between the limiter and
+ * the write leaves no refusal at all — and leaves an attempt with no org,
+ * which is exactly this verdict.
+ *
+ * Not GA4, for the reason it was never GA4: its API needs a service account
+ * and an OAuth round trip from a public health route, its data lands with
+ * hours of latency, and a monitor that depends on an analytics vendor is a
+ * monitor that reports an outage every time that vendor has one.
+ *
+ * The denominator UNDER-counts on purpose and that is the safe direction: a
+ * marker write is fire-and-forget and a lost one is simply not counted.
+ * Under-counting can only make this check quieter, never louder — it cannot
+ * invent attempts that did not happen, so it cannot invent an outage.
+ *
+ * Serves are still read and still reported, as CONTEXT. They cost nothing
+ * extra and they answer the second question an on-call person asks: was
+ * anybody even looking.
+ *
+ * Pure on purpose, like its siblings: the route counts, this decides.
+ */
+export interface SignupServedMarker {
+    /** Signup-page serves merged into this minute bucket. */
+    serves?: number;
+    /** When the most recent serve in this bucket happened. */
+    servedAtMs?: number;
+}
+export interface SignupAttemptMarker {
+    /** Org-creation attempts merged into this minute bucket. */
+    attempts?: number;
+    /** When the most recent attempt in this bucket happened. */
+    attemptedAtMs?: number;
+}
+export interface SignupDroughtCheck extends HealthCheck {
+    /**
+     * Signup pages served inside the trailing window — the denominator. A
+     * COUNT only; the markers carry no visitor, no IP and no referrer. Null
+     * when the query itself failed.
+     */
+    signupPagesServed: number | null;
+    /**
+     * Org-creation attempts inside the same window — the denominator the
+     * verdict is actually taken on (AGL-2714). Null when that query failed.
+     */
+    signupAttempts: number | null;
+    /** Accounts (orgs) actually created in the same window. The numerator. */
+    orgCreations: number | null;
+    /** The trailing window all three numbers cover, so the body is self-describing. */
+    windowMinutes: number;
+    /**
+     * Attempts below which zero creations is treated as a quiet hour rather
+     * than an outage. Named `minimumTraffic` still, because it is the same
+     * question — how much has to have happened before zero means something —
+     * and renaming it would break every monitor body that reads it.
+     */
+    minimumTraffic: number;
+}
+/**
+ * Trailing window the drought verdict covers. One hour, matching the sibling
+ * checks so the three numbers on this endpoint are all read against the same
+ * clock — and long enough that a single slow afternoon does not page anyone.
+ */
+export declare const SIGNUP_DROUGHT_WINDOW_MINUTES = 60;
+/**
+ * Attempts in the window below which zero accounts means nothing.
+ *
+ * Three, against attempts rather than the five it once meant against serves
+ * (AGL-2714). The unit changed, so the number had to be re-argued rather than
+ * carried over.
+ *
+ * Not one: a browser can lose a request, and a person can start the form and
+ * abandon it between authenticating and the org write. Not ten either — at a
+ * handful of signups a week, waiting for ten attempts to fail would mean
+ * waiting days to notice a door that stopped opening, which is the failure
+ * this check exists to catch inside an hour.
+ *
+ * Three distinct requests to create an org, none of which produced one and
+ * none of which was refused, is a door that does not open. That reading has
+ * no quiet-hour interpretation: nobody attempts three times by browsing.
+ */
+export declare const MIN_SIGNUP_TRAFFIC_FOR_DROUGHT = 3;
+export declare function signupDroughtHealth(markers: SignupServedMarker[] | null, attemptMarkers: SignupAttemptMarker[] | null, orgCreations: number | null, ms: number, minimumTraffic?: number, windowMinutes?: number): SignupDroughtCheck;
+/**
+ * Rate-limiter degradation, reduced to a health verdict (AGL-1693).
+ *
+ * `consumeRateLimit` fails SOFT: when the Firestore counter is unreachable it
+ * answers from a per-instance `Map` and flags `degraded`. AGL-1679 made that
+ * findable after the fact — on recovery the instance writes one summary
+ * document `rateLimits/degraded_{minuteBucket}` — but nothing reads it, so a
+ * degraded window during the beta still passes unnoticed in real time. This
+ * turns "did any limiter fall back recently" into the same 200/503 contract
+ * the sibling checks speak, so the AGL-1502 uptime check + alert + email path
+ * is the listener.
+ *
+ * **The window is the whole design.** Markers carry a 30-day `expiresAt`, so
+ * "does a marker exist" would leave the endpoint red for a month after a
+ * thirty-second blip — a recovered incident permanently paging is how a check
+ * gets muted, and muted is worse than absent. That is the opposite of the
+ * backups check, which stays red BY DESIGN because a missing restore point is
+ * a condition that persists until someone fixes it (DISASTER_RECOVERY.md gap
+ * 2). A degraded limiter window is an EVENT: it is over, and what is owed is
+ * a notification, not a standing alarm. So the verdict covers a trailing
+ * window and clears itself.
+ *
+ * Filtering on `lastAtMs` rather than the marker's id: the id is bucketed on
+ * `firstAtMs`, so a long episode's document is stamped with the minute the
+ * outage STARTED. An id-range window would miss exactly the longest episodes,
+ * which are the ones worth waking up for.
+ *
+ * Pure on purpose, like `backupsHealth` and `signupsHealth`: the route
+ * queries, this decides, the spec exercises every branch without a network.
+ */
+export interface RateLimitDegradationMarker {
+    /** Calls that fell back to the per-instance cap. */
+    calls?: number;
+    /** Instance-episodes merged into this minute bucket. */
+    episodes?: number;
+    /** When the episode's last fallback happened. */
+    lastAtMs?: number;
+    /** The failure code the episode ended on. */
+    code?: string;
+}
+export interface RateLimitsCheck extends HealthCheck {
+    /**
+     * Fallback calls inside the trailing window. A COUNT only — the endpoint is
+     * public, and limiter keys are hashed client IPs. Null when the query
+     * itself failed.
+     */
+    degradedCalls: number | null;
+    /** Instance-episodes inside the window. 2+ means several instances saw it. */
+    degradedEpisodes: number | null;
+    /** Minutes since the most recent fallback, so the body dates itself. */
+    minutesSinceLast: number | null;
+    /** The trailing window the counts cover, so the body is self-describing. */
+    windowMinutes: number;
+    /** The count above which this reports degraded. */
+    threshold: number;
+}
+/**
+ * Trailing window the degradation counts cover.
+ *
+ * Bounded from below by the alert path, not by taste. The probe memoizes for
+ * `HEALTH_PROBE_TTL_MS` (2 minutes), the slowest check on this door runs
+ * every 15, and the alert policy wants a minute of sustained failure — so a
+ * window shorter than ~18 minutes can go red and green again before that
+ * check tells anyone, which is a check that reports nothing while looking
+ * like it works. 30 leaves margin and still clears itself inside half an hour.
+ */
+export declare const RATE_LIMIT_DEGRADED_WINDOW_MINUTES = 30;
+/**
+ * Any fallback at all is worth an email. Unlike the signup alarm there is no
+ * organic baseline to clear: a healthy deployment produces exactly zero of
+ * these, and one is already the statement "for some requests, the global cap
+ * was not the cap". Firestore retries transactions internally, so a failure
+ * that reaches this code is not a single unlucky contention.
+ */
+export declare const MAX_DEGRADED_CALLS_PER_WINDOW = 0;
+export declare function rateLimitsHealth(markers: RateLimitDegradationMarker[] | null, ms: number, now?: number, threshold?: number, windowMinutes?: number): RateLimitsCheck;
+/**
+ * Uncaught server-side errors, reduced to a health verdict (AGL-1921).
+ *
+ * ## The gap this closes
+ *
+ * Of the eleven alert policies in `aglyn-main`, not one could see a server
+ * error rate. Every check is a LIVENESS probe on one URL: `/api/health` can be
+ * green while `/api/billing/checkout` 500s for every paying customer, which is
+ * the single most likely shape of a launch-day incident and the one nothing
+ * could page on. Server errors lived only in the Vercel runtime log, which
+ * retains ~60 minutes and drains nowhere (AGL-1799).
+ *
+ * The first pass gave both apps an `onRequestError` hook that forwards each
+ * error to a `server-errors` log in `aglyn-main`. That closed the CAPTURE gap
+ * and left the reading gap wide open, and the reading gap is the one this repo
+ * keeps losing to — `/api/health/crons` was correct about a broken job for
+ * fifty-one hours because nothing asked it. Measured 2026-08-24: the
+ * production credential is refused `entries:list` on that log
+ * (`403 Permission denied for all log views`), so no probe here can read what
+ * the hook writes. The only reader that log can have is a GCP alert policy
+ * created by hand.
+ *
+ * So the hook ALSO counts into a `rateLimits/serverError_{minute}` marker,
+ * and this grades those counts into the same 200/503 contract the sibling
+ * checks speak — which hands the signal to readers that already exist and
+ * already run: the 15-minute GitHub uptime probe, the external keyword
+ * monitors, and `docs.aglyn.com/status`.
+ *
+ * ## What it can and cannot see, exactly
+ *
+ * It counts what `onRequestError` counts: an uncaught throw in a render or a
+ * route handler, in the nodejs runtime. It does NOT count an error that kills
+ * the process before the hook runs, a platform-level 5xx that never reaches
+ * our code (function timeout, OOM, cold-start 502), or anything thrown in the
+ * edge runtime. A Vercel log drain sees all of those and remains the real fix.
+ * This is the arm that ships without a purchase, and its blind spots are
+ * written down rather than glossed — `docs/UPTIME_AND_SLA.md`.
+ *
+ * ## The third state is the one that matters here
+ *
+ * A monitoring path that cannot measure MUST NOT report a zero. `null` markers
+ * — the query failed — is `errors-unavailable` and degraded, never "0 errors".
+ * That is the same rule `rateLimitsHealth` and `billingWebhookHealth` follow,
+ * and on this check it is the difference between "nothing is wrong" and "we
+ * have no idea", which during a 5xx spike are the two readings furthest apart.
+ *
+ * ## It must be able to go GREEN
+ *
+ * A spike is an EVENT, not a condition (the AGL-1843 rule). Markers live seven
+ * days, so "does a marker exist" would hold this red for a week after a
+ * one-minute blip, and a check that stays red after recovery is a check that
+ * gets muted. The verdict covers a trailing window and clears itself.
+ *
+ * Pure on purpose, like its siblings: the route queries, this decides, the
+ * spec exercises every branch without a network.
+ */
+export interface ServerErrorMarker {
+    /** Uncaught server errors merged into this minute bucket. */
+    errors?: number;
+    /** Split by deployment — `{ 'console-web': n, 'tenant-web': n }`. */
+    byService?: Record<string, number>;
+    /** When the most recent error in this bucket happened. */
+    erroredAtMs?: number;
+}
+export interface ServerErrorsCheck extends HealthCheck {
+    /**
+     * Uncaught server errors inside the trailing window. A COUNT only — the
+     * endpoint is public, and messages, stacks and route patterns have no
+     * business in it (they are in the Logging entry, which is not public). Null
+     * when the query itself failed, and null is NEVER zero.
+     */
+    serverErrors: number | null;
+    /**
+     * Which deployment produced them. The first thing an incident needs, and it
+     * is a deployment name rather than anything about a request. Null when the
+     * query failed.
+     */
+    byService: Record<string, number> | null;
+    /** Minutes since the most recent error, so the body dates itself. */
+    minutesSinceLast: number | null;
+    /** The trailing window the count covers, so the body is self-describing. */
+    windowMinutes: number;
+    /** The count above which this reports degraded. */
+    threshold: number;
+}
+/**
+ * Trailing window the error count covers.
+ *
+ * Bounded from below by the alert path, not by taste — the same arithmetic as
+ * `RATE_LIMIT_DEGRADED_WINDOW_MINUTES`: the probe memoizes for 2 minutes, the
+ * slowest external check runs every 15, and an alert policy wants a minute of
+ * sustained failure, so a window under ~18 minutes can go red and green again
+ * before that check tells anyone. 30 leaves margin and still clears itself
+ * inside half an hour of the last error.
+ */
+export declare const SERVER_ERROR_WINDOW_MINUTES = 30;
+/**
+ * Errors tolerated in the window.
+ *
+ * NOT zero, unlike the rate-limiter and billing alarms, and the difference is
+ * real rather than a matter of nerve. Those two watch controls that a healthy
+ * deployment exercises exactly never. This one watches a count that a single
+ * cold-start Firestore deadline, or one visitor's malformed request reaching a
+ * route that throws instead of 400ing, can make non-zero on a perfectly good
+ * day — and an alarm that pages on the first of those gets muted before the
+ * one that matters arrives.
+ *
+ * Five over thirty minutes is chosen against the only two facts available.
+ * Production serves single-digit orgs (2026-08), so the organic rate of
+ * UNCAUGHT server errors is ~zero — the codebase answers its expected failures
+ * with 4xx, and reaching this hook means nothing handled it. And the shape
+ * being caught is "a route is failing for real users", which does not produce
+ * six errors an hour; it produces six in a minute. There is deliberately no
+ * pretence of calibration: the beta window exists to produce a baseline, and
+ * `SERVER_ERROR_ALARM_MAX_ERRORS` moves this without a deploy when it does.
+ */
+export declare const MAX_SERVER_ERRORS_PER_WINDOW = 5;
+export declare function serverErrorsHealth(markers: ServerErrorMarker[] | null, ms: number, now?: number, threshold?: number, windowMinutes?: number): ServerErrorsCheck;
+/**
+ * How long a health door may reuse its verdict (AGL-2947).
+ *
+ * Cut from one budget: an outage must reach a person within ten minutes. A
+ * green verdict computed just before the onset keeps being served for this
+ * long, and only then can a prober see red. The fastest prober on most doors
+ * is UptimeRobot, every five minutes, which then confirms before it notifies.
+ * So the worst case is this + 5 + that confirmation: at two minutes the budget
+ * holds for any confirmation delay up to three. The five minutes every door
+ * used before spent the whole ten minutes before a notification could leave.
+ *
+ * It still bounds what a public door can be made to cost: at most one
+ * computation per instance per two minutes, and {@link memoizeWithTtl} shares
+ * a computation among the callers that arrive while it runs.
+ */
+export declare const HEALTH_PROBE_TTL_MS: number;
+/**
+ * Reuse a probe result for `ttlMs`, per instance.
+ *
+ * The endpoint is public and unauthenticated, so an unthrottled dependency
+ * check is a free amplifier: anyone could turn a loop into database reads on
+ * our account. This bounds the cost to one probe per instance per interval
+ * however hard it is hit.
+ *
+ * Callers that arrive while a probe is running share it rather than starting
+ * their own. The uptime check's regions, UptimeRobot and a HEAD twin routinely
+ * land within the same second of an expired entry, and each used to pay for a
+ * full probe.
+ *
+ * FAILURES ARE CACHED TOO, deliberately. A dependency that is down will be
+ * down for the next caller as well, and re-probing per request turns an
+ * outage into a stampede against the thing that is already failing. A probe
+ * that THROWS is not cached: its callers all see the throw, and the next
+ * caller probes again.
+ */
+export declare function memoizeWithTtl<T>(ttlMs: number, probe: () => Promise<T>, now?: () => number): () => Promise<T>;
+/**
+ * The error beacon's own liveness, reduced to a health verdict (AGL-1923).
+ *
+ * ## The failure this exists for
+ *
+ * The `Client error beacon` alert policy is a log-match: it fires when an
+ * entry APPEARS in `client-errors`. A policy of that shape can only report
+ * presence, so if the thing writing the entries stops writing, the policy
+ * goes quiet — and quiet is the reading it also gives when everything is
+ * healthy. **A dead beacon is indistinguishable from zero errors**, and
+ * `reportClientErrors` has three fail-soft paths that each end in a
+ * `console.warn` to a log that retains an hour and drains nowhere
+ * (AGL-1799). Error Reporting would show zero errors; the policy would stay
+ * silent; both readings look exactly like a clean launch.
+ *
+ * ## Why this shape and not a metric-absence policy
+ *
+ * AGL-1923 proposed a log-based metric plus `conditionAbsent`. This is the
+ * same guarantee with two properties that one lacks. It is PROVABLE — the
+ * verdict is graded synchronously against the write's own status, so the
+ * degraded branch can be induced and observed rather than waited out over an
+ * absence window. And it needs nothing new to run it: the uptime probe is
+ * what winds the dead-man's switch, so there is no cron that can itself stop
+ * without anyone noticing (which would only move the problem one layer out).
+ *
+ * ## It must be able to go GREEN
+ *
+ * The condition is an EVENT, not a state. A failed write degrades; the next
+ * successful write clears it, within one probe TTL — nothing latches and
+ * there is no retention window to age out of. That is the AGL-1843 rule
+ * applied before the fact: the clearing event is named, and it is "the next
+ * heartbeat that reaches Cloud Logging". The durable marker AGL-2713 added is
+ * evidence of a LANDING, never of a failure, so it can only ever shorten the
+ * red — a stale one forgives nothing.
+ *
+ * Pure on purpose, like its siblings: the route writes, this decides, the
+ * spec exercises every branch without a network.
+ */
+export interface BeaconCheck extends HealthCheck {
+    /**
+     * The log id the heartbeat targets, so the body names what to query during
+     * an incident rather than making someone go and find it.
+     */
+    logId: string;
+    /** Which deployment's credential was exercised — console and tenant differ. */
+    service: string;
+    /**
+     * How many heartbeat writes this probe attempted. Two means the first one
+     * missed, which is a fact a green row must still carry: a credential that
+     * needs a second attempt every time is on its way to failing outright.
+     */
+    attempts: number;
+    /**
+     * Minutes since a heartbeat last durably landed, or null when the answer
+     * could not be established — which includes "none ever has". Null is what
+     * makes a missed heartbeat unforgivable, so the two cases fold safely.
+     */
+    minutesSinceHeartbeat: number | null;
+    /** How long a missed heartbeat is tolerated before this door reds. */
+    graceMinutes: number;
+}
+/**
+ * Codes that mean the heartbeat got no ANSWER, as opposed to a refusal
+ * (AGL-2713).
+ *
+ * The distinction is the whole of the tolerance below, so it is named once
+ * and asserted directly rather than being spelled inline at the branch.
+ *
+ * - `credential-unavailable` — the admin app is configured and its credential
+ *   simply did not mint a token on this attempt. On a cold lambda that is the
+ *   first outbound TLS of the instance's life, and it is the measured shape of
+ *   both 2026-09-09 blips.
+ * - `transport-*` — the Logging write never came back inside its 4s deadline,
+ *   or the fetch layer failed. Same class: nothing was decided.
+ *
+ * Everything else is a DECISION and must never be tolerated. `http-401` and
+ * `http-403` are a lost `logging.logEntries.create` grant, `http-429` is
+ * quota, and `no-credential` is a deployment whose `FIREBASE_*` env is absent
+ * — every one of them permanent until a person fixes it, and every one of
+ * them a state in which browser errors are being collected by nothing. So is
+ * `heartbeat-unavailable`, which means a writer documented never to throw
+ * threw.
+ */
+export declare function isTransientBeaconCode(code: string | undefined): boolean;
+/**
+ * How a missed heartbeat is graded (AGL-2713).
+ *
+ * `landedAtMs` is the durable, cross-instance fact — the last time ANY
+ * instance of this deployment put an entry in the log. It has to be durable:
+ * the probe memo dies with the lambda, so an in-process counter is at one on
+ * every cold start and would forgive nothing at all on the one shape this
+ * exists for.
+ */
+export interface BeaconTolerance {
+    /** Heartbeat writes this probe made. Defaults to the single-attempt shape. */
+    attempts?: number;
+    /** When a heartbeat last durably landed; null when that cannot be shown. */
+    landedAtMs?: number | null;
+    /** How long a miss is forgiven after the last landing. Zero forgives none. */
+    graceMs?: number;
+    now?: number;
+}
+/**
+ * ## Tolerating ONE miss without becoming a door that cannot red (AGL-2713)
+ *
+ * `/api/health/error-beacon` on the console answered `503 no-credential` twice
+ * on 2026-09-09 — 15:12 and 17:22 UTC, each shortly after new capacity from
+ * the 15:08 deploy, each self-clearing within minutes, with the beacon code
+ * path changed by one comment line since the previous release. Between them
+ * they took the 15-minute uptime workflow red and opened four GCP alert
+ * events, on a monitor whose entire value is that somebody believes it.
+ *
+ * The tolerance is deliberately NOT "forgive a failure". It is three
+ * conditions that must all hold, and each one is what keeps the door able to
+ * go red:
+ *
+ *  1. the code says nothing was decided ({@link isTransientBeaconCode});
+ *  2. a heartbeat is PROVEN to have landed within `graceMs` — proof being a
+ *     durable marker a successful write left behind, so a deployment whose
+ *     credential never worked has nothing to forgive with and reds on its
+ *     first probe;
+ *  3. that proof is not from the future, because a clock that ran backwards
+ *     must not mint an unbounded grace.
+ *
+ * Absence of proof reds. A marker store that cannot be read reds. That is the
+ * same rule the `*-unavailable` arms of every sibling grader apply, pointed at
+ * the evidence for calm rather than at the evidence for alarm.
+ */
+export declare function beaconHealth(write: {
+    ok: boolean;
+    code?: string;
+} | null, logId: string, service: string, ms: number, tolerance?: BeaconTolerance): BeaconCheck;
+/**
+ * A tenant page render, reduced to a health verdict (AGL-2486).
+ *
+ * ## The gap this closes
+ *
+ * `marketing-home` (`aglyn.com/`) and `customer-site` (`demo.aglyn.app/`) are
+ * the only two external checks that watched a REAL PAGE rather than a health
+ * endpoint. Both sat at 0% from 2026-08-21, because bot protection answered
+ * Google's checkers with a 429 checkpoint. The health-path firewall bypass
+ * that recovered `tenant-health` and `beacon-heartbeat tenant` cannot reach
+ * them: they fetch `/`, not `/api/health/*`.
+ *
+ * The alternative was allowlisting Google's 54 checker IPs — rejected because
+ * an IP-valued bypass rule is one the drift checker cannot meaningfully
+ * assert, and Google rotates the list. So the render moves to where the
+ * bypass already is: an endpoint under `/api/health` that renders the page
+ * server-side and grades the result.
+ *
+ * ## Why this is not "200 because the route exists"
+ *
+ * The caller runs the SAME loader the catch-all page route runs, against the
+ * SAME host, and this grades what came back. A page that resolves no host,
+ * 404s, redirects away, or composes an EMPTY node tree is a failure — and
+ * those are the shapes an outage actually takes. A canary that cannot go red
+ * for a broken page is worse than the dark check it replaces, because it
+ * reports a confidence it has not earned.
+ *
+ * ## What is deliberately NOT asserted
+ *
+ * Never a string from the page. The marker is STRUCTURAL — a host resolved
+ * and a non-empty composed node tree. Asserting copy would page whoever is
+ * on call for an ordinary content edit, and this endpoint is public, so
+ * customer content must not appear in its body either. `nodeCount` is a
+ * count, which is enough to tell "rendered nothing" from "rendered" without
+ * disclosing what was rendered.
+ */
+export type RenderOutcome = 
+/** The loader returned props. `nodeCount` is the composed node total. */
+{
+    kind: 'rendered';
+    hostResolved: boolean;
+    nodeCount: number;
+}
+/** The loader chose the not-found branch. */
+ | {
+    kind: 'not-found';
+}
+/** The loader chose to redirect — a home page should never do this. */
+ | {
+    kind: 'redirect';
+}
+/** The loader threw, or could not be reached at all. */
+ | {
+    kind: 'unavailable';
+}
+/**
+ * No target host is configured. A failure on purpose: "we are watching
+ * nothing" must never read the same as "the page is fine".
+ */
+ | {
+    kind: 'not-configured';
+};
+export interface RenderCheck extends HealthCheck {
+    /**
+     * Composed nodes the page produced. A COUNT, never the nodes: this endpoint
+     * is public and the nodes are the customer's page. Zero is the failure.
+     */
+    nodeCount: number;
+    /**
+     * Which tenant host was rendered — a CONFIGURED host, never one derived
+     * from the request, so no caller can choose what we render. Empty string
+     * when nothing is configured.
+     */
+    host: string;
+}
+export declare function renderHealth(outcome: RenderOutcome, host: string, ms: number): RenderCheck;
+/**
+ * Billing webhook delivery, reduced to a health verdict (AGL-1924).
+ *
+ * ## The gap this closes
+ *
+ * Of the alert policies in `aglyn-main`, none watched billing. Sept 1 opens to
+ * PAYING customers, and the billing path is the one place where a failure
+ * nobody notices converts directly into lost revenue and a support incident
+ * per affected customer. The webhook has a documented history of failing
+ * exactly that way: AGL-1551 (every delivery rejected `400 Invalid signature`
+ * for a week, behind a green "Active" badge), AGL-1560 (a secret roll 400ing
+ * roughly half of deliveries), AGL-1552 (the replay window making every retry
+ * unreceivable), AGL-1798 (`charge.refunded` never subscribed). Each is a
+ * total or near-total failure of the billing event path, and not one of them
+ * would have paged anyone.
+ *
+ * ## Why the denominator has to come from Stripe
+ *
+ * `stripeEvents` alone cannot answer this. `route.ts` returns 400 BEFORE
+ * claiming the idempotency document, so a rejected delivery writes nothing —
+ * an empty collection reads identically whether nothing happened or
+ * everything was refused. That is precisely how the 2026-08-14 checklist tick
+ * came out green while AGL-1551 was live. Stripe supplies what it TRIED to
+ * deliver; we supply what we processed; the gap is the failure.
+ *
+ * ## Why this cannot false-page on a quiet night
+ *
+ * The verdict never keys on the ABSENCE of events. At beta volume a night
+ * with zero deliveries is legitimate, and a naive freshness rule would page
+ * on it — the AGL-1843 mistake in a new costume. `undelivered` is a count of
+ * deliveries Stripe attempted AND failed, so a quiet window scores zero and
+ * reads healthy for the right reason. `emitted` and `processed` are carried
+ * for the human reading the incident and are DELIBERATELY not inputs to the
+ * verdict: no floor for them exists yet, and inventing one before the beta
+ * produces a baseline would be a threshold nobody could defend.
+ *
+ * ## Division of labour with the AGL-1906 audit
+ *
+ * `tools/scripts/lib/stripe-webhook-health.mjs` asserts the endpoint's full
+ * subscribed-event list against `WEBHOOK_EVENTS`. That list is deliberately
+ * NOT duplicated here — a second copy is the exact failure its own comment
+ * warns about, and a subscription set is config that changes on deploys, not
+ * a thing that changes minute to minute. This watches the two facts that DO
+ * move continuously: whether the destination is still enabled, and whether
+ * deliveries are landing.
+ *
+ * ## It must be able to go GREEN
+ *
+ * Everything here is a trailing window over live Stripe state. A destination
+ * re-enabled, or a fixed handler whose retries then succeed, reads healthy on
+ * the next probe. There is no marker to age out and nothing to latch
+ * (AGL-1843): the clearing event is "a window with no failed deliveries and
+ * an enabled endpoint".
+ *
+ * Pure on purpose, like its siblings: the route fetches, this decides, the
+ * spec exercises every branch without a network.
+ */
+export interface BillingWebhookFacts {
+    /** Our production destination, as Stripe currently holds it. */
+    endpointStatus: 'enabled' | 'disabled' | 'missing';
+    /** Events Stripe attempted and failed to deliver inside the window. */
+    undelivered: number;
+    /** Events Stripe emitted inside the window. Reported, never a verdict input. */
+    emitted: number;
+    /**
+     * Events our handler claimed inside the window. Reported, never a verdict
+     * input — and null when the Firestore arm could not run, which does NOT on
+     * its own make the check red: Stripe already answered the question that
+     * matters.
+     */
+    processed: number | null;
+    /**
+     * Deliveries that answered 200 and moved NOTHING inside the window
+     * (AGL-1954) — a required event type that produced neither a committed
+     * effect nor a named deliberate skip. See `webhook-delivery.ts` for why
+     * that is a defect by construction and a legitimate no-op is not one.
+     *
+     * Null when the Firestore arm could not run, and null is NOT red on its
+     * own: Stripe already answered the question that matters, and a health
+     * check that reds on its own read failure trains people to ignore it.
+     */
+    inert: number | null;
+    /**
+     * Deliveries that only landed on a RETRY inside the window (AGL-2039).
+     *
+     * The arm every other count here is structurally blind to.
+     * `undelivered` comes from `delivery_success=false`, which is a TERMINAL
+     * filter over EVENTS: an event that 400s three times and then succeeds
+     * reads back clean and is indistinguishable from one that succeeded
+     * immediately. The Stripe Dashboard scores delivery ATTEMPTS and counted
+     * all three — which is why AGL-1906 read 0% against the Dashboard's 30% and
+     * both figures were correct. The three attempts it could not see were
+     * AGL-1551.
+     *
+     * The webhook stamps `retriedAtMs` when the distance from `event.created`
+     * to its own claim exceeds `RETRY_LAG_SECONDS`, so this is an aggregation
+     * over a marker field rather than a scan of every claim in the window.
+     *
+     * Null when the Firestore arm could not run, and null is NOT red on its
+     * own — same rule as `processed` and `inert`.
+     */
+    retried: number | null;
+    /**
+     * Required event types the destination is NOT subscribed to (AGL-1948 /
+     * AGL-1798). Empty is the healthy answer; null means the endpoint did not
+     * report its subscriptions and the coverage question is unanswered.
+     */
+    unsubscribedEvents: readonly string[] | null;
+    /**
+     * The CONNECT destination, as Stripe currently holds it (AGL-1948).
+     *
+     * A SECOND destination, and the platform one being perfectly healthy says
+     * nothing about it: connected-account events are delivered only to a
+     * destination created with `connect: true`, so its absence is invisible to
+     * every count above. AGL-2122 found exactly that — `account.updated`
+     * handled in two plugins, and no destination that could ever deliver it,
+     * so every merchant's `stripeChargesEnabled` rotted silently.
+     *
+     * Null when the endpoint census itself could not be taken.
+     */
+    connectEndpoint: 'enabled' | 'disabled' | 'missing' | null;
+    /**
+     * Required Connect events the Connect destination is NOT subscribed to.
+     * Empty is healthy; null means there was no destination to ask, or it did
+     * not state its subscriptions.
+     */
+    unsubscribedConnectEvents: readonly string[] | null;
+}
+export interface BillingWebhookCheck extends HealthCheck {
+    endpointStatus: BillingWebhookFacts['endpointStatus'] | null;
+    undelivered: number | null;
+    emitted: number | null;
+    processed: number | null;
+    inert: number | null;
+    retried: number | null;
+    unsubscribedEvents: readonly string[] | null;
+    connectEndpoint: BillingWebhookFacts['connectEndpoint'] | null;
+    unsubscribedConnectEvents: readonly string[] | null;
+    /** The trailing window the counts cover, so the body is self-describing. */
+    windowMinutes: number;
+}
+/**
+ * Trailing window the delivery counts cover.
+ *
+ * Bounded from below by the alert path, not by taste, exactly like
+ * `RATE_LIMIT_DEGRADED_WINDOW_MINUTES`: the probe memoizes for 5 minutes, the
+ * uptime check runs every 5, and the policy wants ~10 minutes of sustained
+ * failure before it emails — so a window under ~20 minutes can go red and
+ * green again before anyone is told. Bounded from ABOVE by Stripe's retry
+ * schedule: an event that fails and then succeeds on retry stops counting, so
+ * a window much longer than an hour would hold transient blips red past their
+ * own recovery.
+ */
+export declare const WEBHOOK_FAILURE_WINDOW_MINUTES = 60;
+/**
+ * Failed deliveries tolerated in the window.
+ *
+ * Zero, and unlike the signup alarm there is no organic baseline to clear: a
+ * healthy account produces exactly zero, and one is already the statement
+ * "Stripe tried to tell us something about money and could not". Stripe
+ * retries on its own, so a failure visible here is not one unlucky packet.
+ */
+export declare const MAX_FAILED_DELIVERIES_PER_WINDOW = 0;
+/**
+ * Inert deliveries tolerated in the window (AGL-1954).
+ *
+ * Zero — and unlike `processed`, the count this check reports but refuses to
+ * gate on because no defensible floor exists before the beta produces a
+ * baseline, this one's floor follows from the definition. A delivery is
+ * counted inert only when a required event type produced neither a committed
+ * effect nor a NAMED deliberate skip (`classifyWebhookDelivery`). No
+ * legitimate traffic pattern generates one: a tenant shopper's subscription,
+ * a marketplace refund, a `won` dispute nobody claimed all name their reason
+ * and classify as `ignored`. So any at all is the statement "Stripe told us
+ * about money and nothing here moved" — the same "any at all" rule the
+ * rate-limiter degradation markers use (AGL-1679).
+ */
+export declare const MAX_INERT_DELIVERIES_PER_WINDOW = 0;
+/**
+ * Retried deliveries tolerated in the window (AGL-2039).
+ *
+ * Zero, and the reasoning is `MAX_FAILED_DELIVERIES_PER_WINDOW`'s: a delivery
+ * counted here is one whose FIRST attempt did not get through, which is a
+ * failed attempt that happened, not a statistical wobble. The healthy band
+ * measured against the live account is 1.0–3.7 seconds against a 120-second
+ * bar, so nothing organic sits anywhere near it.
+ *
+ * Cheap to be wrong in the safe direction, because this cannot latch: the
+ * window is trailing and the marker is on the event's own claim, so a single
+ * blip reds for at most one window and then clears itself — an event, not a
+ * condition (the AGL-1843 rule). It is a parameter rather than a literal so
+ * that if beta traffic turns out to produce organic retries, the knob is one
+ * argument and not a rewrite.
+ */
+export declare const MAX_RETRIED_DELIVERIES_PER_WINDOW = 0;
+export declare function billingWebhookHealth(facts: BillingWebhookFacts | null, ms: number, windowMinutes?: number, threshold?: number, inertThreshold?: number, retriedThreshold?: number): BillingWebhookCheck;
+/**
+ * Is every interval we can SELL also an interval we can BILL? (AGL-1931)
+ *
+ * The metered item is what turns reported usage into money. It is attached
+ * from an env-configured price id that is keyed by billing interval —
+ * `STRIPE_PRICE_METERED` for monthly, `STRIPE_PRICE_METERED_YEARLY` for
+ * annual — because Stripe forbids one subscription mixing
+ * `recurring.interval`.
+ *
+ * When one of those ids is missing, `meteredPriceId(interval)` returns null
+ * and every subscription-mutating path does the only safe thing: it attaches
+ * nothing and carries on. Failing a checkout over it would be worse. But the
+ * result is a subscription that accrues usage against a meter and carries no
+ * item to bill it, and NOTHING about that is visible — the plan is right, the
+ * entitlements are right, the invoice looks right, and the only trace is
+ * revenue that never arrives.
+ *
+ * That is the defect shape this check exists to end. The absence of a price
+ * was indistinguishable from "correctly no overage", so it hid behind a
+ * `console.warn` on a server log nobody reads. Here it is a 503 on the same
+ * probe the uptime check and alert email already watch.
+ *
+ * ## Why ASYMMETRY is the loudest code
+ *
+ * One interval configured and the other not means one cohort of customers is
+ * billed for overage and the other silently is not — off the same meter, on
+ * the same plans, with no screen anywhere showing the difference. It cannot
+ * be a deliberate state: there is no product reason to meter monthly
+ * subscribers and exempt annual ones.
+ *
+ * ## Why BOTH missing is still red, but only with Stripe configured
+ *
+ * Both unset with no `STRIPE_SECRET_KEY` is simply an unprovisioned
+ * deployment — local dev, a fresh preview — where no money is at stake and
+ * going red would train everyone to ignore this check. That is the exact
+ * reasoning the checkout and subscription routes already apply to their
+ * warning, and it is preserved here.
+ *
+ * But both unset while Stripe IS configured is a deployment that can take
+ * money and cannot bill a single unit of overage on ANY interval. That is
+ * the same revenue loss, merely total instead of partial, and the earlier
+ * code treated it as calm because it only ever compared the two ids to each
+ * other. Comparing them to Stripe's presence instead is what closes it.
+ */
+export interface MeteredPricingFacts {
+    /** Whether this deployment holds a Stripe secret key at all. */
+    stripeConfigured: boolean;
+    /** `STRIPE_PRICE_METERED` — the monthly metered price — is set. */
+    monthly: boolean;
+    /** `STRIPE_PRICE_METERED_YEARLY` — the annual metered price — is set. */
+    yearly: boolean;
+}
+export interface MeteredPricingCheck extends HealthCheck {
+    stripeConfigured: boolean;
+    monthly: boolean;
+    yearly: boolean;
+    /**
+     * The interval that would accrue unbilled usage, named so the body says
+     * which cohort is affected without anyone re-deriving it from two booleans.
+     */
+    unbilledInterval: 'month' | 'year' | 'both' | null;
+}
+export declare function meteredPricingHealth(facts: MeteredPricingFacts, ms: number): MeteredPricingCheck;
+/** Where the marks live. One document per job id, written by the job. */
+export declare const CRON_BEAT_COLLECTION = "platformCronBeats";
+/**
+ * The document that records when this deployment STARTED watching.
+ *
+ * Without it a job that has never reported cannot be told apart from a job
+ * that has stopped reporting, and every board would come up red on the day
+ * the feature deploys — for `usage-email`, red until the 1st of the next
+ * month. The rule this enables is stated once, in `cronJobsHealth`: a job
+ * with no mark is only silent once a scheduled fire time has passed SINCE
+ * we started watching.
+ *
+ * Not a reserved id: Firestore reserves `__.*__`, and this is a plain slug
+ * that no job id can collide with (job ids never contain the word `watch`,
+ * and the wiring spec asserts the inventory's ids against the workflow).
+ */
+export declare const CRON_BEAT_WATCH_DOC = "watch-window";
+/**
+ * Where a degraded verdict is recorded, so a red window survives it.
+ *
+ * The response body names the late job, but only to whoever is holding it,
+ * and the uptime probe reads the status and discards the body. Vercel's
+ * runtime log keeps a `console.error` for about an hour, and the Cloud
+ * Logging drain deliberately does not forward one — `isServerErrorEntry`
+ * drops `level: 'error'`, because that is every fail-soft line the beacons
+ * write and forwarding it is what a self-feeding bill is made of. So the
+ * only sink that outlives the window is the one the endpoint already holds
+ * a handle to.
+ *
+ * Written by the READER, like the verdict itself. One document, replaced on
+ * each degraded probe, holding the failing rows and when the window opened.
+ * Same collision argument as the watch document: a plain slug, and no job id
+ * contains `degraded`.
+ */
+export declare const CRON_BEAT_DEGRADED_DOC = "last-degraded";
+/**
+ * Every job's latest mark in one document, `{ beats: { [jobId]: atMs } }`.
+ *
+ * The reader's fast path (AGL-2946). Listing the collection costs one read per
+ * job on every uncached probe — ~23 reads, several hundred times a day, on a
+ * project that pays for reads past the free tier — to answer a question this
+ * one document answers.
+ *
+ * A COPY, never the authority. `writeCronBeat` writes it second, so a job
+ * whose own mark landed can still be missing or stale here, and the reader
+ * confirms any job this document calls late against that job's own mark
+ * before reporting it. Stale costs a read; it never costs a false red.
+ *
+ * Same collision argument as the other two: a plain slug no job id equals.
+ */
+export declare const CRON_BEAT_SUMMARY_DOC = "summary";
+/** The reserved documents in `CRON_BEAT_COLLECTION` that are not job marks. */
+export declare const CRON_BEAT_RESERVED_DOCS: ReadonlySet<string>;
+/**
+ * How long a gap may be before the next degraded probe counts as a NEW
+ * window rather than a continuation of the one on file.
+ *
+ * Three probe TTLs. Long enough that an instance answering intermittently
+ * does not split one outage into a dozen, short enough that yesterday's
+ * window is never mistaken for today's. The comparison is against the
+ * failing set as well, so a different set always opens a new window.
+ */
+export declare const CRON_DEGRADED_WINDOW_CONTINUITY_MS: number;
+/** Who fires the job. The two are operated, and fail, differently. */
+export type CronRunner = 'github-actions' | 'cloud-scheduler';
+export interface ScheduledJob {
+    /** Stable id. The Firestore document id, and the health check's name. */
+    id: string;
+    label: string;
+    /**
+     * Five-field cron, UTC. The SAME string the scheduler holds — the wiring
+     * spec asserts each one against its runner's source of truth
+     * (`.github/workflows/scheduled-crons.yml` for `github-actions`,
+     * `cloud/functions/src/index.ts` for `cloud-scheduler`), so an edit there
+     * that is not made here fails the build rather than quietly changing what
+     * "on time" means.
+     */
+    cron: string;
+    runner: CronRunner;
+    /** What the scheduler actually invokes, for the operator reading a red row. */
+    target: string;
+    /**
+     * How late a run may be before the row goes red.
+     *
+     * Generous on purpose, and the generosity is not padding. GitHub only runs
+     * scheduled workflows from the default branch and delays them under load —
+     * routinely by minutes, occasionally by an hour. The question this check
+     * answers is "is this job still scheduled at all", not "did it start on the
+     * second"; a grace that reds on ordinary lateness is alert fatigue, and an
+     * alert people learn to ignore is the failure this issue is about wearing
+     * a different hat.
+     *
+     * SO THE GRACE IS A PROPERTY OF THE RUNNER, not of the job (AGL-1617). The
+     * ninety minutes the two frequent sweeps used to carry was GitHub's drift
+     * budget, and it was bought with detection: on a fifteen-minute schedule it
+     * takes SIX consecutive missed fires before anything is said. Moving those
+     * two onto Cloud Scheduler — which is punctual, as `plugin-jobs-beat` has
+     * been demonstrating at `every 1 minutes` in the same payload the whole
+     * time — is what let the bar go back UP, to forty-five minutes and three
+     * missed fires. That direction is the point: widening a grace to make a
+     * monitor agree with a runner that drops 60% of its triggers is not a fix,
+     * it is deciding not to look.
+     *
+     * IT IS A FLOOR, NOT THE EXACT BAR. `cronJobsHealth` compares the mark
+     * against the last fire that is ALREADY this old, so where the threshold
+     * lands depends on the clock's phase against the schedule: forty-five
+     * minutes on a fifteen-minute cron reds somewhere between 45 and 60 minutes
+     * of silence, six hours on a daily one between 6h and 30h. Quote the range,
+     * not the number, when reasoning about how fast a dead job is found — and
+     * never write a test that only holds at one phase.
+     */
+    graceMinutes: number;
+    /** What stops happening when this job stops. Rendered on the board. */
+    drives: string;
+}
+/**
+ * THE INVENTORY.
+ *
+ * Seven GitHub Actions schedules (`.github/workflows/scheduled-crons.yml`) —
+ * the weekly jobs, the month-boundary usage-email sweep and the hourly CRM
+ * task reminders, for which an hour of drift is nothing — and the rows
+ * driven by Cloud Scheduler out of
+ * `cloud/functions/src/index.ts`: `pluginJobsBeat` and `consoleAiJobsBeat`
+ * (every minute), the routes the `consoleFastCrons` job carries every
+ * fifteen (AGL-1617), and one `consoleDailyCron` export per daily job.
+ *
+ * `scheduled-crons-wiring.spec.ts` holds BOTH runners against their source —
+ * the workflow for the `github-actions` rows, the functions file for the
+ * `cloud-scheduler` ones — in both directions. An inventory row for a job
+ * nobody schedules and a scheduled job nobody watches are the same bug seen
+ * from opposite ends, and both fail the build.
+ *
+ * `report-usage` appears TWICE and is two jobs, not one. The 02:00 run
+ * rolls up the closed month and is the only run that ever reaches Stripe;
+ * the 07:00 `?month=current` run writes the in-progress figure every usage
+ * budget reads (AGL-2219). Either can stop without the other, and folding
+ * them into one row would hide exactly that.
+ */
+export declare const SCHEDULED_JOBS: readonly ScheduledJob[];
+/** One job's most recent mark, as read from `CRON_BEAT_COLLECTION`. */
+export interface CronBeat {
+    jobId: string;
+    /** Epoch ms of the invocation that left the mark. */
+    atMs: number;
+}
+export interface CronJobCheck extends HealthCheck {
+    /** The schedule this row was judged against, so the body is self-describing. */
+    schedule: string;
+    runner: CronRunner;
+    /** Minutes since the job last reported. Null when it never has. */
+    lastBeatAgeMinutes: number | null;
+    /**
+     * The most recent fire time the job should already have reported for, ISO.
+     * Null when no such time has passed since we started watching — which is
+     * the healthy reading for a job that is legitimately idle.
+     */
+    dueAt: string | null;
+    graceMinutes: number;
+}
+/**
+ * The latest time at or before `atMs` that `expression` fires, UTC.
+ *
+ * Null when the expression is unparsable, or when it does not fire inside
+ * the lookback — 45 days, which comfortably clears the longest gap any
+ * inventory entry has (`usage-email`'s twenty-nine idle days).
+ *
+ * Whole non-matching DAYS are skipped rather than walked minute by minute,
+ * so the worst case is ~45 day checks plus 1,440 minute checks rather than
+ * 64,800 of them.
+ */
+export declare function previousCronFire(expression: string, atMs: number, lookbackDays?: number): number | null;
+/**
+ * The scheduled jobs, reduced to one health check per job (AGL-1955).
+ *
+ * `beats` null means the marks could not be read at all — degraded for every
+ * row, the same rule `signupsHealth`, `rateLimitsHealth` and `beaconHealth`
+ * follow. An alarm that cannot see the thing it watches must say so rather
+ * than report calm; here it is the literal condition the issue is about.
+ *
+ * `watchStartedAtMs` is when this deployment first read the marks. A job with
+ * no mark is silent only once a fire time has passed SINCE then — otherwise
+ * every row would be red on the day this deploys, and `usage-email` would
+ * stay red until the 1st.
+ *
+ * Pure on purpose, like its siblings: the route reads, this decides, the
+ * spec exercises every branch without a network.
+ */
+export declare function cronJobsHealth(beats: readonly CronBeat[] | null, watchStartedAtMs: number, ms: number, now?: number, jobs?: readonly ScheduledJob[]): Record<string, CronJobCheck>;
+/**
+ * The mark a run leaves — the only writes on the beat path.
+ *
+ * Structurally typed against firebase-admin's Firestore rather than importing
+ * it: this module is pure and is imported by tenant Server Components, and a
+ * health verdict library that drags in the admin SDK would be a new reason
+ * for a page to fail. The console routes, the marketing plugin's scheduled
+ * campaign processor and the tenant job runner all pass their own handle.
+ *
+ * Two writes, in order: the job's own document, which is the authority, then
+ * its entry in {@link CRON_BEAT_SUMMARY_DOC}, which is what the reader reads
+ * first. The summary merges one map key, so jobs beating at the same moment
+ * do not overwrite each other's entries.
+ *
+ * NEVER THROWS. A beat that cannot be written must not take down the job it
+ * is describing — the monitor becoming the outage is its own failure mode.
+ * It returns false when the job's own mark could not be written, and a write
+ * that keeps failing shows up where it should: as a silent job on the board.
+ * A failed summary write still returns true, because the mark that decides
+ * the verdict landed.
+ */
+export interface CronBeatStore {
+    collection(name: string): {
+        doc(id: string): {
+            set(data: Record<string, unknown>, options?: unknown): Promise<unknown>;
+        };
+    };
+}
+export declare function writeCronBeat(store: CronBeatStore, jobId: string, now?: number): Promise<boolean>;
+/**
+ * The beats a summary document holds, ignoring anything malformed.
+ *
+ * `raw` is the document's `beats` field as Firestore returns it — a plain map,
+ * or undefined when the document does not exist yet.
+ */
+export declare function cronBeatsFromSummary(raw: unknown): CronBeat[];
+/**
+ * DID A STRANGER ACTUALLY SIGN UP? (AGL-2715)
+ *
+ * Every other signup check on this platform is an inference. The auth doors
+ * assert that Identity Platform is reachable and refuses an account that
+ * cannot exist — configuration, not a signup. `probeCreate` reads that the
+ * platform is unlocked and the probe's name is free — preconditions, not a
+ * signup. `signupVolume`, `signupRefusals` and `signupDrought` count what
+ * happened afterwards — a consequence, observed late.
+ *
+ * The strongest thing any of them could say, on the day AGL-2714 paged, was
+ * "somebody got an account recently", and recently was 24 hours ago. AGL-2581
+ * is what that costs: signup refused every visitor for three days while the
+ * monitor named for signups stayed green.
+ *
+ * So something has to WALK it. A canary creates an account, verifies it,
+ * mints a session, provisions an org, and deletes all of it — against
+ * production, on a schedule — then stamps what happened into one marker. This
+ * verdict reads that marker.
+ *
+ * ## Why the walk is not done here
+ *
+ * Health probes on this platform are read-only and cost-bounded by contract,
+ * and this one is served from a PUBLIC unauthenticated endpoint. A probe that
+ * created an account would hand anyone with `curl` an org factory. The write
+ * lives in a scheduled job; the door only reports. Same split as the beacon
+ * heartbeat (AGL-2713), for the same reason.
+ *
+ * ## The four ways this reds, and why residue is one of them
+ *
+ * A canary that walks perfectly and fails to clean up is not a success. It
+ * leaves a real org, with a real slug reservation and a real host, on the
+ * production estate — every hour, forever. `canary-left-residue` is red even
+ * though the signup itself worked, because the alternative is a monitor that
+ * quietly fills the database it is monitoring.
+ */
+export interface SignupCanaryMarker {
+    /** When the walk finished. The freshness clock. */
+    walkedAtMs?: number;
+    /** Whether every step of the walk succeeded. */
+    ok?: boolean;
+    /** Which step broke, for the body. Never an error message, never a uid. */
+    failedStep?: string | null;
+    /** Wall clock for the whole walk. */
+    elapsedMs?: number;
+    /** Whether the walk deleted everything it created. */
+    reapedCleanly?: boolean;
+}
+export interface SignupCanaryCheck extends HealthCheck {
+    /** Age of the last recorded walk, or null when there is no marker. */
+    ageMs: number | null;
+    /** Which step broke on that walk, when one did. */
+    failedStep: string | null;
+    /** How long the walk took, for the latency graph. */
+    walkMs: number | null;
+    /** Whether it cleaned up after itself. */
+    reapedCleanly: boolean | null;
+    /** The age past which a walk stops counting as evidence. */
+    staleAfterMs: number;
+}
+/**
+ * How old the last successful walk may be before this reds.
+ *
+ * Two hours against an hourly schedule — one missed run is tolerated, two are
+ * not. A canary that runs hourly and reds at 61 minutes would page on every
+ * GitHub Actions queue delay, and an alarm that cries wolf on infrastructure
+ * latency is one nobody reads by the time signup actually breaks. Two misses
+ * is a pattern rather than a hiccup.
+ *
+ * This is deliberately NOT generous enough to sleep through AGL-2581: three
+ * days of refused signups would red this inside two hours.
+ */
+/**
+ * Workspace-slug prefix the signup canary owns, and the one piece of the
+ * product that has to know the canary exists (AGL-2715).
+ *
+ * ## Why an exclusion is not optional
+ *
+ * The canary creates a real org and then deletes it. `signupDrought` compares
+ * durable ATTEMPT markers against a live COUNT of orgs — and a deleted org
+ * leaves the count while its attempt marker stays. So every canary walk adds
+ * 1 to the denominator and 0 to the numerator, and after three walks the
+ * platform reports `signup-drought` with nothing wrong.
+ *
+ * That is not theoretical. It fired on 2026-09-09 at six attempts against
+ * zero creations — six walks that had each just proved, end to end, that a
+ * stranger could sign up. A monitor that manufactures the outage it watches
+ * for is worse than no monitor, and it is the same alarm fatigue AGL-2714
+ * removed, arriving from inside the house.
+ *
+ * ## Why the slug, and what that costs
+ *
+ * `/api/orgs/create` receives the requested slug before it does anything, so
+ * this needs no secret, no header and no second code path — the canary is
+ * excluded by being what it says it is.
+ *
+ * The cost is that the prefix is caller-supplied: someone naming their
+ * workspace `signup-canary-…` would not be counted in the drought's
+ * denominator. That is bounded to one uncounted attempt per such workspace,
+ * and it cannot hide an outage, because an outage is many attempts by many
+ * people and only the oddly-named ones would go missing.
+ *
+ * The canary declares the same prefix in `tools/e2e/signup-canary.mjs`, which
+ * cannot import this file — it runs outside the workspace. They are held
+ * together by `apps/console/specs/signup-canary-marker-wiring.spec.ts`.
+ */
+export declare const SIGNUP_CANARY_ORG_SLUG_PREFIX = "signup-canary-";
+/**
+ * Is this org creation the canary's own?
+ *
+ * Exported as a function rather than leaving callers to compare strings, so
+ * the one place that decides is the one place to read when asking why a
+ * number looks wrong.
+ */
+export declare function isSignupCanaryOrgSlug(slug: string | null | undefined): boolean;
+/**
+ * How old the last walk may be before the check goes red.
+ *
+ * Six hours, far wider than the schedule that writes it, and deliberately so.
+ * GitHub Actions serves `schedule` from a best-effort queue that drops most
+ * requests under load: measured 2026-09-10, `uptime-probe.yml` asks for every
+ * fifteen minutes and actually fired at gaps of 1h55m to 4h38m across the
+ * preceding day and a half. A window sized to the cron expression rather than
+ * to that behavior reds on ordinary queue depth.
+ *
+ * Widening it costs no detection speed, because staleness is not how a broken
+ * signup surfaces. A walk that cannot sign up FAILS and still writes its
+ * marker, which reads `signup-walk-failed` on the next poll. Staleness can
+ * only mean the walker never reported — a CI condition, not a product one —
+ * so this window's whole job is to notice a canary that has genuinely stopped,
+ * and it must not fire before then: this check grades the monitor that must
+ * never be muted.
+ */
+export declare const SIGNUP_CANARY_STALE_AFTER_MS: number;
+/**
+ * Grade the last recorded signup walk.
+ *
+ * Pure, like every sibling: the route reads the marker, this decides. Ordered
+ * by which mistake costs most — a missing marker is treated as failure, never
+ * as calm, because "no evidence" and "evidence of success" are the two
+ * readings this whole issue exists to stop anyone from confusing.
+ */
+export declare function signupCanaryHealth(marker: SignupCanaryMarker | null, ms: number, nowMs?: number, staleAfterMs?: number): SignupCanaryCheck;
+/**
+ * IS ATTESTATION WORKING FOR REAL PEOPLE? (AGL-2715)
+ *
+ * The signup canary walks the real journey, but it attests with an App Check
+ * DEBUG TOKEN — because this project's provider is reCAPTCHA Enterprise, which
+ * is built to score headless automation as a bot and always will. Everything
+ * else in that walk is real; the attestation step is not. So the canary is
+ * structurally blind to the one failure it sits closest to: App Check refusing
+ * the people it is supposed to admit.
+ *
+ * That blindness is not acceptable on its own, and it is not fixed by
+ * argument. It is fixed by measuring the thing directly.
+ *
+ * ## What this reads, and why a token cannot fool it
+ *
+ * Firebase publishes `firebaseappcheck.googleapis.com/services/verification_count`
+ * to Cloud Monitoring, labelled by `result` (ALLOW / DENY) and `security`
+ * (VALID / INVALID / MISSING_UNKNOWN_ORIGIN), per service. Those counts are
+ * every request from every visitor.
+ *
+ * The canary contributes at most one verification an hour against roughly a
+ * thousand a day, and its debug-token attestation lands in the same ALLOW
+ * bucket as everyone else's. So it cannot hold this green: if attestation
+ * collapses for real people the rate collapses with it, one canary request
+ * notwithstanding.
+ *
+ * ## Why only Identity Platform is graded
+ *
+ * `identitytoolkit.googleapis.com` is the service signup depends on, and it
+ * runs clean — 939 ALLOW against 3 DENY over the 24 hours to 2026-09-09.
+ * `firestore.googleapis.com` in the same window was 5493 ALLOW against 1046
+ * DENY, because client Firestore reads are reached by crawlers and stale tabs
+ * that legitimately fail attestation. Grading that number would either mute
+ * this check with a floor low enough to admit the noise, or page on the noise.
+ * The other services are reported for diagnosis and decide nothing.
+ */
+export interface AppCheckVerificationSample {
+    /** `ALLOW` or `DENY`. */
+    result?: string;
+    /** `VALID`, `INVALID`, `MISSING_UNKNOWN_ORIGIN`, … — for the body only. */
+    security?: string;
+    /** The service the verdict was rendered for. */
+    service?: string;
+    /** Requests in this bucket over the window. */
+    count?: number;
+}
+/**
+ * IS THE EDGE STILL LETTING REAL VISITORS IN? (AGL-2720)
+ *
+ * Every synthetic on this platform carries the `x-aglyn-probe` firewall
+ * bypass, because bot protection refuses a datacenter IP outright. So if the
+ * edge started challenging real people, every check would ride past the thing
+ * that was broken and stay green.
+ *
+ * Measured 2026-09-10 while looking for something to close that: Vercel
+ * publishes no challenged-versus-allowed metric — seven endpoints probed, the
+ * only one that answers returns rule actions rather than traffic. And a probe
+ * cannot substitute, because the discriminator is not "was this request
+ * challenged" but "can a REAL BROWSER get in": `curl` from a residential
+ * address is challenged too, and that is the healthy state, since the
+ * challenge is answerable and a non-JS client cannot answer it.
+ *
+ * What is left is the outcome, and it was already being counted for money.
+ * Metered page views are written by real browsers on real customer sites
+ * after the edge admitted them — 57 to 563 a day across hosts over the
+ * preceding week. Nothing synthetic touches that number: the probes ride the
+ * bypass and the signup canary walks the console, neither of which is a
+ * metered tenant page view.
+ *
+ * So the question this asks is simply whether that number is still moving. A
+ * platform serving tens of views an hour that serves none for hours has
+ * either lost its edge or lost every customer site, and both are worth waking
+ * somebody for.
+ *
+ * ⛔ What it is NOT. It watches the TENANT edge, because that is where the
+ * volume is. The console's own front door serves a handful of signup views a
+ * day — too few to floor, and now partly synthetic — so a firewall change
+ * scoped only to `aglyn-console` would not show up here. It is also not a
+ * latency or correctness check: it says traffic arrives, nothing more.
+ *
+ * ⚠️ And the volume is CONCENTRATED. On the day this was built, one host of
+ * thirteen produced every view. So this reds if that one site goes quiet for
+ * half a day, which is why the window is what it is — see
+ * {@link EDGE_ADMISSION_QUIET_AFTER_MS}.
+ */
+/**
+ * What the metered-traffic sampler leaves behind.
+ *
+ * `advancedAtMs` is the whole point and it is the WRITER's judgement, not the
+ * reader's: the sampler compares this reading against the last one and stamps
+ * the moment the total actually grew. A day rollover sets the counter back to
+ * zero, so a grader handed a single sample could not tell midnight from an
+ * outage.
+ */
+export interface EdgeAdmissionMarker {
+    /** When the sampler last ran. Context; the verdict does not use it. */
+    sampledAtMs?: number;
+    /** The last moment the metered total was seen to GROW. The clock. */
+    advancedAtMs?: number;
+    /** Which UTC day the total belongs to. */
+    day?: string;
+    /** The running total for that day at the last sample. */
+    total?: number;
+}
+export interface EdgeAdmissionCheck extends HealthCheck {
+    /** How long since the metered total last moved, or null with no marker. */
+    quietMs: number | null;
+    /** The day the sampled total belongs to, so a rollover is readable. */
+    day: string | null;
+    /** The running total for that day at the last sample. */
+    total: number | null;
+    /** How long the total may sit still before this reds. */
+    quietAfterMs: number;
+    /** How long since the sampler last reported, or null with no marker. */
+    sampleAgeMs: number | null;
+}
+/**
+ * How long metered page views may sit still before the edge is presumed shut.
+ *
+ * Twelve hours, and the width is deliberate rather than lazy.
+ *
+ * The quietest full day in the sampled week carried 57 views — about 2.4 an
+ * hour on average, which would make six hours of zero look damning. But the
+ * average is the wrong statistic here: measured 2026-09-10, the day's 62 views
+ * came from ONE host of thirteen. Traffic that concentrated arrives in bursts,
+ * and a burst distribution produces long empty stretches with nothing wrong.
+ * A window sized to the average would page on one of them, which is how the
+ * monitor that must never be ignored gets ignored.
+ *
+ * Twelve hours of exactly zero, on a platform serving 57 to 563 views a day,
+ * is not a quiet stretch. It is slower to fire than anyone would like, and it
+ * is the only thing that catches a fully blocked edge at all — nothing else
+ * would ever fire, because every other check rides the bypass.
+ *
+ * ⚑ Tighten it once the real quiet-period distribution is known: the sampler
+ * stamps `advancedAtMs` on every run, so a week of markers says what the true
+ * maximum gap is. Do not tighten it from the daily average.
+ */
+export declare const EDGE_ADMISSION_QUIET_AFTER_MS: number;
+/**
+ * How old the sampler's own reading may be before it stops being evidence.
+ *
+ * Six hours, sized like `SIGNUP_CANARY_STALE_AFTER_MS` to a scheduler that
+ * drops most of what it is asked for (AGL-2723) rather than to the cron
+ * expression. Shorter than the quiet window on purpose: a stalled sampler
+ * should be named as one BEFORE its frozen reading has had time to look like
+ * an edge outage.
+ */
+export declare const EDGE_ADMISSION_SAMPLE_STALE_AFTER_MS: number;
+/**
+ * Grade the last recorded metered-traffic sample.
+ *
+ * Pure, like every sibling. The sampler decides when the total last MOVED and
+ * stamps it; this only asks how long ago that was. Keeping the movement
+ * detection in the writer is what lets the door stay a read: a day rollover
+ * resets the counter to zero, and a grader looking at one sample could not
+ * tell that from traffic stopping.
+ */
+export declare function edgeAdmissionHealth(marker: EdgeAdmissionMarker | null, ms: number, nowMs?: number, quietAfterMs?: number, sampleStaleAfterMs?: number): EdgeAdmissionCheck;
+export interface AppCheckAttestationCheck extends HealthCheck {
+    /** Allowed over total for the graded service, or null with no traffic. */
+    allowRate: number | null;
+    /** Requests the rate is taken over. */
+    allowed: number;
+    denied: number;
+    /** Below this many requests the rate says nothing and is not graded. */
+    minimumRequests: number;
+    /** The floor the rate must clear. */
+    minimumAllowRate: number;
+    /** The service graded. Everything else is context. */
+    service: string;
+    /** Denials by `security`, so a red says which way it broke. */
+    deniedBy: Record<string, number>;
+    /** The window the counts cover. */
+    windowMinutes: number;
+}
+/** The service signup depends on. See the docblock for why it is the only one. */
+export declare const APP_CHECK_GRADED_SERVICE = "identitytoolkit.googleapis.com";
+/**
+ * Window the attestation rate is taken over.
+ *
+ * Six hours, not one. This metric is aggregated by Google on its own schedule
+ * and arrives late, so a one-hour window reads empty for reasons that have
+ * nothing to do with attestation. Six hours is long enough to always carry
+ * traffic on this platform and short enough that a real collapse is caught the
+ * same working day.
+ */
+export declare const APP_CHECK_WINDOW_MINUTES: number;
+/**
+ * Requests below which the rate is not graded.
+ *
+ * A ratio over three requests is noise wearing a percentage. Twenty is a
+ * fraction of the ~940 a day Identity Platform sees, so a healthy platform
+ * always clears it, and a platform quiet enough not to is a platform where
+ * this check has nothing to say.
+ */
+export declare const APP_CHECK_MIN_REQUESTS = 20;
+/**
+ * The floor the allow rate must clear.
+ *
+ * 0.90, against a measured 0.997. The gap is deliberate: a handful of genuine
+ * denials is ordinary — a stale tab, a bot, a browser that failed its
+ * reCAPTCHA — and a floor set near the observed rate would page on those.
+ *
+ * What this is built to catch is not a drift of a few percent; it is the
+ * documented failure mode of `recaptcha-allowlist.ts`, where an origin that is
+ * attached and routed but not allowlisted renders a console that can never
+ * sign anyone in. That reads as ~0%, not 85%.
+ */
+export declare const APP_CHECK_MIN_ALLOW_RATE = 0.9;
+/**
+ * Grade attestation for real visitors.
+ *
+ * Pure, like every sibling: something else reads Cloud Monitoring, this
+ * decides. Null samples are degraded rather than calm — an unreadable metric
+ * is not evidence that attestation works, and this check exists precisely
+ * because "we did not look" was being reported as "it is fine".
+ */
+export declare function appCheckAttestationHealth(samples: AppCheckVerificationSample[] | null, ms: number, service?: string, minimumRequests?: number, minimumAllowRate?: number, windowMinutes?: number): AppCheckAttestationCheck;