@open-everywhere/core 0.1.0

package/dist/agent/ops/census.js

@@ -0,0 +1,701 @@
+// THE DEPLOYED-STATE CENSUS (OPE-631, OPE-633) — the defect class no test tier can see.
+//
+// A unit test proves the code is right. An integration test proves the turn is right. Neither can
+// prove that the RUNNING DEPLOYMENT holds the rows and routes that code needs, because that state
+// is not in the repository. The motivating incident: the Notion webhook path was dead in production
+// because the db broker had no `db:notion:channel-key` row. Every delivery died AFTER a 200 ack,
+// with no audit trace, and nothing went red for weeks.
+//
+// So the census joins two halves that are normally never compared:
+//   • the REQUIRED state, derived from the shipped config — bundles, connector-credential
+//     catalogues, domains, webhook hooks, and the routes the mounted channels actually declare;
+//   • the ACTUAL state, read from the deployment — the credential refs its broker store holds, and
+//     the status each ingress route answers with.
+//
+// 🔴 DERIVED, NEVER DECLARED. There is no census manifest, because a manifest rots in one direction:
+// the state that matters is the state nobody remembered to write down. Every required item here is a
+// function of config the deployment already loads at boot. Adding a grant adds a required row;
+// deselecting a provider drops a required route.
+//
+// THE ONE DECLARATION, and why it is not a manifest (OPE-1674). A channel may ship DARK — mounted in
+// code, every route answering 404 until an arming condition holds — and a bare probe cannot tell a
+// dark route from a missing one, so the census demanded a route the deployment deliberately refuses
+// and red a correct ship (#191, #192: `POST /control/v1/oauth/token` → 404). {@link ROUTE_ARMING}
+// records, per channel, the condition the channel's OWN code already reads. It NARROWS what the
+// census requires and can never widen it: an unarmed route is SKIPPED with its reason, an armed one
+// is required exactly as before, and a channel with no entry is unaffected. It adds no env var —
+// every name it reads is one the channel already reads to decide the same thing.
+//
+// 🔴 PRESENCE, NEVER VALUE. The credential half asks the store which REFS exist and nothing else.
+// {@link proveKeyOpensRow} is the ONE place that touches ciphertext, and it returns a verdict — no
+// plaintext, prefix or length ever leaves it. Nothing here prints a secret.
+//
+// This module is pure: config in, a plan out; observations in, a verdict out. The IO (the store
+// connection, the HTTP probes) lives in scripts/deploy/census.ts.
+import { connectorGrantCredential, connectorGrantName } from "../access/bundle.js";
+import { CONTROL_OAUTH_ISSUER } from "../control/oauth-clients.js";
+import { controlOAuthIssuer } from "../control/oauth-resource.js";
+import { OAUTH_SIGNING_SECRET_ENV, oauthSigningSecret } from "../control/oauth-tokens.js";
+function catalogueCredential(catalogues, connector, credentialId) {
+    return catalogues.find((c) => c.connector === connector)?.credentials.find((c) => c.id === credentialId);
+}
+/** The db-brokered ref of one catalogue credential, or undefined when its home is not the db broker.
+ *  An env-brokered ref names an env var and an OAuth credential holds no ref at all — neither is a
+ *  row this census can look for. */
+function dbRefOf(credential) {
+    if (credential.broker !== "db")
+        return undefined;
+    const ref = credential.secretRef?.trim();
+    return ref && ref.length > 0 ? ref : undefined;
+}
+/**
+ * Derive every credential row this deployment must hold.
+ *
+ * Five config sites name one. Each is a LIVE resolution path — a missing row makes that exact path
+ * fail closed, silently, at the moment it is first used:
+ *   1. a bundle's egress `connections[]` entry stamped `broker: "db"` (the firewall injects it);
+ *   2. a bundle's `connectors[]` grant, through the named credential's catalogue entry;
+ *   3. a domain's `credentials[]` binding, through the credential it names in `use`;
+ *   4. a webhook hook stamped `broker: "db"` — every ref in its list, because a rotation window is
+ *      declared as live until the operator removes the old key;
+ *   5. a mounted provider's channel plumbing, supplied by the caller.
+ */
+export function planRequiredCredentials(input) {
+    const reasons = new Map();
+    const problems = [];
+    const add = (ref, reason) => {
+        const list = reasons.get(ref);
+        if (list) {
+            if (!list.includes(reason))
+                list.push(reason);
+            return;
+        }
+        reasons.set(ref, [reason]);
+    };
+    const viaCatalogue = (connector, credentialId, reason, where) => {
+        const credential = catalogueCredential(input.catalogues, connector, credentialId);
+        if (!credential) {
+            problems.push(`${where} names credential "${credentialId}", which connector "${connector}" does not configure`);
+            return;
+        }
+        const ref = dbRefOf(credential);
+        if (ref)
+            add(ref, reason);
+    };
+    for (const bundle of input.bundles) {
+        for (const connection of bundle.connections ?? []) {
+            if (connection.broker !== "db")
+                continue;
+            const ref = connection.secretRef?.trim();
+            if (ref)
+                add(ref, `bundle "${bundle.name}" egress connection "${connection.id}"`);
+        }
+        for (const grant of bundle.connectors ?? []) {
+            // Both grant shapes go through the canonical accessors — there is one reader of the
+            // string-vs-object split (access/bundle.ts) and this is not a second one.
+            const name = connectorGrantName(grant);
+            const credential = connectorGrantCredential(grant);
+            if (credential === undefined) {
+                problems.push(`bundle "${bundle.name}" grants connector "${name}" without naming a credential, so the resolver binds nothing`);
+                continue;
+            }
+            viaCatalogue(name, credential, `bundle "${bundle.name}" grants connector "${name}" as "${credential}"`, `bundle "${bundle.name}"`);
+        }
+    }
+    for (const domain of input.domains) {
+        for (const binding of domain.credentials ?? []) {
+            viaCatalogue(binding.connector, binding.use, `domain "${domain.name}" binds "${binding.connector}"/"${binding.credential}" to "${binding.use}"`, `domain "${domain.name}"`);
+        }
+    }
+    for (const hook of input.hooks) {
+        if (hook.broker !== "db")
+            continue;
+        const refs = Array.isArray(hook.secretRef) ? hook.secretRef : [hook.secretRef];
+        for (const raw of refs) {
+            const ref = typeof raw === "string" ? raw.trim() : "";
+            if (ref)
+                add(ref, `webhook hook "${hook.id}" signing secret`);
+        }
+    }
+    for (const entry of input.plumbing) {
+        viaCatalogue(entry.connector, entry.credentialId, entry.reason, `provider plumbing "${entry.connector}"`);
+    }
+    const required = [...reasons.entries()]
+        .map(([ref, list]) => ({ ref, reason: list.join("; ") }))
+        .sort((a, b) => a.ref.localeCompare(b.ref));
+    const declaredOnly = [];
+    for (const catalogue of input.catalogues) {
+        for (const credential of catalogue.credentials) {
+            const ref = dbRefOf(credential);
+            if (!ref || reasons.has(ref))
+                continue;
+            declaredOnly.push({
+                ref,
+                reason: `declared by connector "${catalogue.connector}" as "${credential.id}" — no grant, binding or plumbing names it`,
+            });
+        }
+    }
+    declaredOnly.sort((a, b) => a.ref.localeCompare(b.ref));
+    return { required, declaredOnly, problems };
+}
+/** The `/webhooks/:id` path parameter, as core's webhook channel declares it. */
+const WEBHOOK_ROUTE = "/webhooks/:id";
+/**
+ * Every channel that ships dark. ONE entry today: the control plane's OAuth authorization server and
+ * MCP mount (OPE-72), which answer 404 unless BOTH the signing secret is set (env — infrastructure)
+ * and the issuer is declared in tracked config. `channels/control-mcp.ts` states the same two
+ * conditions in its own header, and `control/oauth-route.ts`'s `armed()` is the code this mirrors.
+ *
+ * THE TRACKED HALF DECIDES IT TODAY. `CONTROL_OAUTH_ISSUER` is `""` on this repository, so the plane
+ * is dark by tracked config alone and the env half changes nothing until a deployer declares an
+ * issuer by pull request. That is why this entry needs no deployment round trip to be right here.
+ *
+ * ⚠️ WHAT THE ENV HALF WILL REST ON once an issuer IS declared, said plainly because the census
+ * probes a REMOTE deployment: it reads the OPERATOR's environment, not the deployment's, so it is
+ * right only while the two agree — the same `.env.local` convention every credential rung here
+ * already depends on. THE TWO DISAGREEMENTS ARE NOT SYMMETRIC, and only one of them is safe:
+ *   • operator ARMED, deployment DARK ⇒ the route is required and its 404 reds. That is the
+ *     census's original behaviour and the safe direction.
+ *   • operator DARK, deployment ARMED ⇒ the route is SKIPPED WHILE IT IS SERVING, and the census
+ *     passes without probing it. Nothing here can see that: the only trace is a NOT PROBED line
+ *     whose printed reason ("this route's 404 is the shipped design") is then FALSE. The census
+ *     exists because a route can be dead behind a green, and this is a way to buy exactly that.
+ * So set the signing secret in the environment you run the census from, on any deployment whose
+ * issuer is declared. A live arming probe would close this properly; it needs the census RUNNER,
+ * which this module does not hold.
+ */
+export const ROUTE_ARMING = [
+    {
+        channel: "control-mcp.ts",
+        armed: (env) => oauthSigningSecret(env) !== null && controlOAuthIssuer(CONTROL_OAUTH_ISSUER) !== null,
+        darkReason: `dark by declaration: the control OAuth plane answers 404 on every route until ${OAUTH_SIGNING_SECRET_ENV} is set ` +
+            `(at least 32 characters) AND a valid issuer is declared in agent/control/oauth-clients.ts. One of the two is absent ` +
+            `here, so this route's 404 is the shipped design, not a missing mount. Arm both and the census requires it again.`,
+    },
+];
+/**
+ * Derive the endpoints to probe from the routes the mounted channels declare.
+ *
+ * A route whose channel is DARK by declaration ({@link ROUTE_ARMING}) is skipped before anything
+ * else, because "this route is deliberately off" is the most specific thing the census can say
+ * about it, and every reason below would be wrong about a route that is not serving at all.
+ *
+ * Otherwise, ONLY POST ROUTES, and only ones a bare probe can interpret:
+ *   • `/webhooks/:id` expands to one endpoint per DECLARED hook — the incident family. A declared id
+ *     refuses an unsigned delivery; an undeclared one 404s. `controlHookId` rides along as the
+ *     negative control: if it does not 404, every id answers and the hook probes prove nothing.
+ *   • a POST route whose path ALSO has a GET route on the same channel is a token-gated page. It
+ *     answers 404 without its signed token, so a probe cannot tell "mounted" from "absent" — skipped
+ *     with that reason rather than asserted.
+ *   • any other parameterised path is skipped: the census cannot synthesise a valid parameter.
+ */
+export function planRequiredEndpoints(input) {
+    const endpoints = [];
+    const skipped = [];
+    const env = input.env ?? process.env;
+    const darkChannels = new Set((input.arming ?? ROUTE_ARMING).filter((entry) => !entry.armed(env)).map((entry) => entry.channel));
+    const darkReason = new Map((input.arming ?? ROUTE_ARMING).map((entry) => [entry.channel, entry.darkReason]));
+    // The control id must be one NO hook declares, or its probe would assert "must 404" against a real
+    // hook's "must refuse" and the census could never pass. A declared collision moves the control
+    // rather than breaking the family.
+    let controlHookId = input.controlHookId;
+    while (input.hooks.some((h) => h.id === controlHookId))
+        controlHookId = `${controlHookId}-x`;
+    const pageRoute = (route) => input.routes.some((r) => r.channel === route.channel && r.path === route.path && r.method.toUpperCase() === "GET");
+    for (const route of input.routes) {
+        if (route.method.toUpperCase() !== "POST")
+            continue;
+        if (darkChannels.has(route.channel)) {
+            skipped.push({
+                method: route.method,
+                path: route.path,
+                channel: route.channel,
+                reason: darkReason.get(route.channel) ?? "dark by declaration",
+            });
+            continue;
+        }
+        if (route.path === WEBHOOK_ROUTE) {
+            for (const hook of input.hooks) {
+                endpoints.push({
+                    method: "POST",
+                    path: `/webhooks/${hook.id}`,
+                    reason: `webhook hook "${hook.id}" is declared in agent/webhooks/hooks.ts`,
+                    meaning: "an unsigned delivery to a declared hook is refused; a 404 means this deployment does not carry the declaration",
+                    expect: "mounted",
+                });
+            }
+            endpoints.push({
+                method: "POST",
+                path: `/webhooks/${controlHookId}`,
+                reason: "negative control — this hook id is declared nowhere",
+                meaning: "an undeclared hook id must 404; any other answer means every id answers, and the hook probes above prove nothing",
+                expect: "absent",
+            });
+            continue;
+        }
+        if (pageRoute(route)) {
+            skipped.push({
+                method: route.method,
+                path: route.path,
+                channel: route.channel,
+                reason: "a token-gated page route — it answers 404 without its signed token, so a bare probe cannot tell mounted from absent",
+            });
+            continue;
+        }
+        if (route.path.includes(":")) {
+            skipped.push({
+                method: route.method,
+                path: route.path,
+                channel: route.channel,
+                reason: "a parameterised route — the census cannot synthesise a valid path parameter",
+            });
+            continue;
+        }
+        endpoints.push({
+            method: "POST",
+            path: route.path,
+            reason: `channel "${route.channel}" declares this route`,
+            meaning: "an unsigned POST is refused before any work; a 404 means the route is not mounted on this deployment",
+            expect: "mounted",
+        });
+    }
+    return { endpoints, skipped };
+}
+/**
+ * Classify one probe. A 4xx that is not 404 is the PASS: the route served the request and refused
+ * it. A 2xx is a failure of a different kind and is named as one — an ingress that accepts an
+ * unsigned body is worse than an ingress that is missing.
+ */
+export function classifyEndpoint(status) {
+    if (status === undefined)
+        return "unreachable";
+    if (status === 404)
+        return "absent";
+    if (status >= 200 && status < 400)
+        return "accepted-unsigned";
+    if (status >= 500)
+        return "server-error";
+    return "mounted";
+}
+/**
+ * Prove the AES key can open a stored row.
+ *
+ * 🔴 WHY THE CENSUS NEEDS THIS. `listStoredCredentialRefs` needs no key, so a census without this
+ * check reports "every row present" while `OE_CREDENTIAL_ENCRYPTION_KEY` is absent, wrong or
+ * rotated — and in that state EVERY `broker: "db"` credential fails closed at once, behind 200
+ * responses, with the Notion incident's exact symptom (silence). A presence-only census would be
+ * green through the largest failure in this plane.
+ *
+ * 🔴 WHAT IT DOES NOT PROVE. The key it uses is the one in THIS process. It proves the rows are
+ * openable, not that the deployment's own environment still carries the key — nothing observable
+ * from outside says that, and the census must not imply otherwise.
+ *
+ * NO PLAINTEXT ESCAPES. `decrypt` runs inside this function, its result is measured for emptiness
+ * and discarded, and the error path returns a fixed sentence rather than the thrown message.
+ */
+export function proveKeyOpensRow(input) {
+    try {
+        const opened = input.decrypt(input.ciphertext).length > 0;
+        return opened
+            ? { ref: input.ref, ok: true, detail: "the AES key opens the stored rows (GCM auth tag verified; no value was returned or printed)" }
+            : { ref: input.ref, ok: false, detail: "the envelope opened to an EMPTY value — the row exists and carries no secret" };
+    }
+    catch {
+        return {
+            ref: input.ref,
+            ok: false,
+            detail: "the AES key did NOT open this row — a wrong or rotated OE_CREDENTIAL_ENCRYPTION_KEY, or a corrupt envelope. " +
+                "In this state every broker:\"db\" credential fails closed at once.",
+        };
+    }
+}
+// --- what a MOUNTED CHANNEL contributes to the census (OPE-640) ----------------------------------
+//
+// Both tables below are keyed by the channel module `oe build` emits into `agent/channels/`, so a
+// deselected provider drops its entries with its routes. They live HERE, next to the finding logic,
+// for one reason: a limit and the heartbeat that softens it must never drift apart. A caveat saying
+// "nothing here can see the relay" beside a reported age that DOES partly see it would be worse than
+// either alone, and keeping the pair in one testable place is what stops that.
+/**
+ * What a PASS on a given mounted channel still does not establish. DOCUMENTATION, not required
+ * state: the census prints these beside its verdict so a green is never read as wider than it is.
+ */
+const CHANNEL_LIMITS = {
+    "discord-gateway.ts": "/eve/v1/discord-gateway answers, but it only RECEIVES traffic while the always-on relay (deploy/discord-relay/) holds " +
+        "the Discord WebSocket. Nothing here can see that process directly. `discord.dispatched` softens that a little: it dates " +
+        "the last message the relay actually delivered, but stays REPORTED, never gated, because a quiet guild writes no rows " +
+        "either — absence alone proves nothing. `discord.heartbeat` (OPE-775) is the stronger signal: the relay POSTs it on its OWN " +
+        "timer, independent of guild traffic, and the deployment appends the row once its relay gate accepts that POST. A missing row " +
+        "therefore reads most often as a dead relay or as a refused ingress — but the append is fire-and-forget, so the deployment " +
+        "also answers 200 and drops the row when the append itself fails. Since OPE-785 it GATES the census — its ceiling derives from " +
+        "OE_RELAY_HEARTBEAT_MS, the SAME env var the relay itself reads for its own interval (see docs/deploy/rollback.md).",
+};
+/**
+ * REPORTED (never gated) heartbeats a mounted channel contributes.
+ *
+ * OPE-640 — THE DISCORD RELAY LIVENESS SIGNAL, AND EXACTLY WHAT IT IS WORTH. The relay is the one
+ * non-serverless component (deploy/discord-relay/). It holds the Gateway WebSocket, and Discord
+ * delivers MESSAGE_CREATE over that socket ONLY, so when the relay dies the gateway ingress goes
+ * quiet while every route-level probe stays green. `discord.dispatched` is written ONLY by the
+ * gateway channel (discord-gateway.ts, its DM arm and its guild arm), so its age dates the last
+ * message the relay actually delivered.
+ *
+ * 🔴 REPORTED, NOT GATED, AND THAT IS THE TRUTH RATHER THAN A CONVENTION. Absence has two causes
+ * this signal cannot separate: a dead relay, and a guild where nobody spoke. Gating on the age would
+ * fail every deploy over a quiet weekend, which trains an operator to ignore the one check meant to
+ * catch a dead relay. So the census prints the age and states what it does not prove. Separating the
+ * two causes needs a heartbeat the RELAY ITSELF sends on a timer — a change to an always-on process
+ * this repository does not deploy, so it ran as its own arc rather than a line here. That arc landed:
+ * OPE-775 added the heartbeat and OPE-785 promoted it to GATED. See {@link channelGatedHeartbeats}
+ * below, which is where `discord.heartbeat` now lives.
+ */
+const CHANNEL_REPORTED_HEARTBEATS = {
+    "discord-gateway.ts": [
+        {
+            action: "discord.dispatched",
+            reason: "dates the last message the always-on Discord relay (deploy/discord-relay/) actually delivered. Reported, never gated: a quiet guild writes no rows either, so absence does NOT prove the relay is dead, and an age does not prove it is alive right now.",
+        },
+    ],
+};
+/**
+ * The relay heartbeat's own staleness ceiling, DERIVED from its configured interval — never
+ * hand-typed here — the same "derived, not declared" rule {@link cronCeilingHours} follows for the
+ * cron heartbeats.
+ *
+ * Headroom for TWO missed beats, not one: a single skipped tick under network jitter (a Railway
+ * restart, a brief network blip — see OPE-785) must not false-red the census, only a relay that has
+ * gone genuinely quiet. Three beats' worth of headroom (the one due, plus two missed) is what that
+ * buys.
+ *
+ * FAILS LOUD on a non-positive interval, on purpose: a silently-wrong bound is worse than a thrown
+ * error naming exactly what looks wrong. The caller is responsible for routing an explicitly
+ * DISABLED relay heartbeat (`OE_RELAY_HEARTBEAT_MS=0`, the same value that disables it at the relay
+ * itself) around this function entirely, back to the REPORTED half — see {@link channelGatedHeartbeats}.
+ */
+export function relayHeartbeatCeilingHours(intervalMs) {
+    if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+        throw new Error(`census: relay heartbeat interval "${intervalMs}" must be a positive number of milliseconds.`);
+    }
+    return (intervalMs * 3) / 3_600_000;
+}
+/**
+ * GATED heartbeats a mounted channel contributes (OPE-785), once the census can derive a ceiling
+ * for them — the channel-contributed counterpart to {@link CHANNEL_REPORTED_HEARTBEATS}, kept as a
+ * separate table because a GATED entry needs a `maxAgeHours` no REPORTED one carries.
+ *
+ * `discordRelayHeartbeatMs` is the operator's own mirror of `OE_RELAY_HEARTBEAT_MS` — the SAME env
+ * var name the always-on relay (deploy/discord-relay/index.js) reads for its own interval, so
+ * pointing the census at the relay's actual value is a one-name copy, not a second config surface.
+ * `0` means what it means to the relay: heartbeat disabled — the census then contributes nothing
+ * here (the channel still contributes its REPORTED `discord.dispatched` unaffected).
+ */
+export function channelGatedHeartbeats(files, discordRelayHeartbeatMs) {
+    if (!files.includes("discord-gateway.ts") || discordRelayHeartbeatMs <= 0)
+        return [];
+    return [
+        {
+            action: "discord.heartbeat",
+            reason: "the always-on Discord relay (deploy/discord-relay/) POSTs this heartbeat on a fixed timer, whether or not any guild is talking. The DEPLOYMENT appends the row, and only after its relay gate accepts the POST — so a stale or missing row has two COMMON causes, and they take different remedies. (1) The relay is not posting. Redeploy the Railway relay; a bot-token rotation always needs that redeploy — docs/deploy/surfaces/discord.md, section \"Rotating the bot token\". (2) The relay is live, and the deployment refuses its POST. Rule this one out FIRST, because redeploying the relay does not fix it: an OE_RELAY_SECRET that is unset or disagrees between relay and deployment answers 401, and a route the deployment does not carry refuses every delivery. Those two are the common causes, not the whole list: the append is fire-and-forget, so a deployment that accepted the POST and answered 200 still holds no row when the append itself fails. Unlike discord.dispatched, this signal does not depend on guild traffic, so it CAN separate a dead relay from a quiet one. GATED since OPE-785: the ticket's own rollout order (land, redeploy, confirm live, THEN promote) ran its confirmation window and promoted this from reported to gated.",
+            maxAgeHours: relayHeartbeatCeilingHours(discordRelayHeartbeatMs),
+        },
+    ];
+}
+/**
+ * What `files` — the channel modules the roster actually mounted — contribute to the census. Pure,
+ * so the census script stays a thin caller and the roster-conditional behaviour is testable offline.
+ * An unknown file contributes nothing; it is a channel with no caveat, not an error.
+ */
+export function channelCensusContributions(files) {
+    const limits = [];
+    const reportedHeartbeats = [];
+    for (const file of files) {
+        const limit = CHANNEL_LIMITS[file];
+        if (limit !== undefined)
+            limits.push(limit);
+        reportedHeartbeats.push(...(CHANNEL_REPORTED_HEARTBEATS[file] ?? []));
+    }
+    return { limits, reportedHeartbeats };
+}
+/**
+ * A daily (`"M H * * *"`) or weekly (`"M H * * D"`) cron's staleness ceiling, with headroom for
+ * scheduler jitter and one skipped tick. DERIVED from the schedule's own cron string (read at the
+ * call site off the compiled schedule module — never hand-typed here), so a cadence change updates
+ * the bound automatically instead of silently drifting out of step with it — the same "derived,
+ * never declared" rule {@link planRequiredCredentials} already follows.
+ *
+ * FAILS LOUD on any other shape, on purpose: a silently-wrong bound is worse than a thrown error
+ * naming exactly what to extend.
+ */
+export function cronCeilingHours(cron) {
+    const trimmed = cron.trim();
+    if (/^\d+\s+\d+\s+\*\s+\*\s+\*$/u.test(trimmed))
+        return 24 + 2; // daily + 2h scheduler-jitter slack
+    if (/^\d+\s+\d+\s+\*\s+\*\s+[0-6]$/u.test(trimmed))
+        return 24 * 7 + 4; // weekly + 4h slack
+    throw new Error(`census: cron "${cron}" is neither a daily nor a weekly pattern cronCeilingHours() understands — extend it rather than guessing a bound.`);
+}
+/** Join the gated + reported heartbeat plans against what the audit trail actually holds. */
+export function heartbeatFindings(input) {
+    const observed = (action) => input.observations.find((o) => o.action === action);
+    const ageHoursOf = (iso) => (input.now.getTime() - new Date(iso).getTime()) / 3_600_000;
+    const gated = input.gated.map((h) => {
+        const lastSeenIso = observed(h.action)?.lastSeenIso;
+        if (!lastSeenIso)
+            return { action: h.action, reason: h.reason, maxAgeHours: h.maxAgeHours, ok: false };
+        const ageHours = ageHoursOf(lastSeenIso);
+        return { action: h.action, reason: h.reason, lastSeenIso, ageHours, maxAgeHours: h.maxAgeHours, ok: ageHours <= h.maxAgeHours };
+    });
+    const reported = input.reported.map((h) => {
+        const lastSeenIso = observed(h.action)?.lastSeenIso;
+        if (!lastSeenIso)
+            return { action: h.action, reason: h.reason, ok: true }; // absence is legitimate — never gates
+        return { action: h.action, reason: h.reason, lastSeenIso, ageHours: ageHoursOf(lastSeenIso), ok: true };
+    });
+    return [...gated, ...reported];
+}
+/**
+ * Turn one `{ hasDeploymentId }` observation (or its absence) into a finding. `observed` undefined
+ * covers every reason the call did not complete — no token configured, the route unmounted
+ * (`OE_CONTROL_READ_TOKENS` unset), a network error — and reads as NOT PROVEN, never as a silent
+ * pass: a census that cannot reach the route says so instead of reporting green by omission.
+ */
+export function runtimeSignalFinding(observed) {
+    if (observed === undefined) {
+        return {
+            ok: false,
+            detail: "GET /control/v1/runtime-signal did not answer — no E2E_CONTROL_READ_TOKEN/OE_DEPLOY_CONTROL_TOKEN set, the route is unmounted " +
+                "(OE_CONTROL_READ_TOKENS unset on the deployment), or the call failed. This census cannot see whether the deployed function's env carries VERCEL_DEPLOYMENT_ID.",
+        };
+    }
+    return observed.hasDeploymentId
+        ? {
+            ok: true,
+            detail: "the deployed function's process env carries a non-empty VERCEL_DEPLOYMENT_ID — the fact eve's dynamic-tool-roster refresh keys off " +
+                "(window-gated-test.ts §6). This proves the SIGNAL only, not that any standing session has consumed it.",
+        }
+        : {
+            ok: false,
+            detail: "VERCEL_DEPLOYMENT_ID is EMPTY on the deployed function. Eve falls back to a compiled-artifacts cache key for the refresh revision — " +
+                "a standing seat's roster may not re-derive the way this deployment intends.",
+        };
+}
+/**
+ * Turn one `{ credentialBrokerArmed }` observation (or its absence) into a finding. `observed`
+ * undefined covers every reason the call did not complete or the field was absent from an older
+ * deployment's response — and reads as NOT PROVEN, never as a silent pass, the same posture
+ * {@link runtimeSignalFinding} takes for its own field.
+ */
+export function credentialBrokerArmedFinding(observed) {
+    if (observed === undefined) {
+        return {
+            ok: false,
+            detail: "GET /control/v1/runtime-signal did not answer (or its response carried no credentialBrokerArmed field) — no " +
+                "E2E_CONTROL_READ_TOKEN/OE_DEPLOY_CONTROL_TOKEN set, the route is unmounted (OE_CONTROL_READ_TOKENS unset on " +
+                "the deployment), the call failed, or the deployment predates OPE-641. This census cannot see whether the " +
+                "deployed function's env carries a valid OE_CREDENTIAL_ENCRYPTION_KEY.",
+        };
+    }
+    return observed.credentialBrokerArmed
+        ? {
+            ok: true,
+            detail: "the deployed function's process env carries a valid OE_CREDENTIAL_ENCRYPTION_KEY — the db credential " +
+                "broker registers and every broker:\"db\" credential is reachable.",
+        }
+        : {
+            ok: false,
+            detail: "OE_CREDENTIAL_ENCRYPTION_KEY is absent or malformed on the deployed function. The db credential broker " +
+                "never registers, and every broker:\"db\" credential fails closed at once, behind 200 responses, with no " +
+                "audit trace.",
+        };
+}
+/**
+ * Judges one declaration against what the log holds. Pure, so the whole matrix — exercised,
+ * unexercised-with-reason, unexercised-without — is driven offline without a deployment.
+ */
+export function judgeAuditRow(declaration, lastSeenIso) {
+    const exercised = lastSeenIso !== undefined;
+    // 🔴 AN EMPTY REASON IS NO REASON, AND IT FAILS CLOSED. `notExercised !== undefined` accepted
+    // `""` — so a declaration whose reason was deleted, or never written past the field name, would
+    // have silenced the census for that row while LOOKING declared. The whole point of the field is
+    // that somebody wrote down what is missing; a blank one says nothing and must read as absent.
+    const reason = (declaration.notExercised ?? "").trim();
+    const stated = reason.length > 0;
+    return {
+        action: declaration.action,
+        exercised,
+        ...(stated ? { notExercised: declaration.notExercised } : {}),
+        ...(lastSeenIso === undefined ? {} : { lastSeenIso }),
+        ok: exercised || stated,
+    };
+}
+/** The census's own summary of the audit-row half, for the report and the problem list. */
+export function auditRowProblems(findings) {
+    return findings
+        .filter((f) => !f.ok)
+        .map((f) => `audit row "${f.action}" is declared CONSEQUENTIAL but the pack emitted none — drive it from an e2e leg, or declare \`notExercised\` on it in packages/core/agent/audit/action-registry.ts with what is missing`);
+}
+/**
+ * Join the plan against what the deployment answered. `presentRefs` is the ref list the broker store
+ * holds — names only, never values.
+ *
+ * The census is clean only when EVERY required row exists, EVERY probed endpoint answers as its
+ * `expect` says, and no config problem was found. There is no partial pass: a census that reports
+ * "mostly complete" is the state the incident was already in.
+ */
+export function censusResult(input) {
+    const present = new Set(input.presentRefs);
+    const finding = (c) => ({ ref: c.ref, reason: c.reason, present: present.has(c.ref) });
+    const credentials = input.plan.required.map(finding);
+    const declared = input.plan.declaredOnly.map(finding);
+    const endpoints = input.endpoints.endpoints.map((e) => {
+        const status = input.observations.find((o) => o.path === e.path)?.status;
+        const state = classifyEndpoint(status);
+        return { ...e, ...(status === undefined ? {} : { status }), state, ok: state === e.expect };
+    });
+    const heartbeats = input.heartbeats ?? [];
+    const auditRows = input.auditRows ?? [];
+    const ok = input.plan.problems.length === 0 &&
+        credentials.every((c) => c.present) &&
+        endpoints.every((e) => e.ok) &&
+        (input.keyProof?.ok ?? true) &&
+        heartbeats.every((h) => h.ok) &&
+        (input.runtimeSignal?.ok ?? true) &&
+        (input.credentialBrokerArmed?.ok ?? true) &&
+        // OPE-1837: a consequential row the pack never emitted, with no stated reason, fails the
+        // census. A row with a reason is reported and does not gate — see judgeAuditRow.
+        auditRows.every((r) => r.ok);
+    return {
+        ok,
+        target: input.target,
+        storeLabel: input.storeLabel,
+        credentials,
+        declared,
+        endpoints,
+        skipped: input.endpoints.skipped,
+        problems: [...input.plan.problems, ...auditRowProblems(auditRows)],
+        ...(input.keyProof ? { keyProof: input.keyProof } : {}),
+        heartbeats,
+        auditRows,
+        ...(input.runtimeSignal ? { runtimeSignal: input.runtimeSignal } : {}),
+        ...(input.credentialBrokerArmed ? { credentialBrokerArmed: input.credentialBrokerArmed } : {}),
+        limits: input.limits ?? [],
+    };
+}
+/** The operator-facing report. Every line is a fact the census established; nothing is summarised
+ *  away, because a census that hides its inventory cannot be audited. */
+export function renderCensusReport(result) {
+    const lines = [];
+    lines.push("");
+    lines.push(`  deployment: ${result.target}`);
+    lines.push(`  store:      ${result.storeLabel}`);
+    lines.push("");
+    lines.push(`  CREDENTIAL ROWS (${result.credentials.filter((c) => c.present).length}/${result.credentials.length} present)`);
+    for (const c of result.credentials) {
+        lines.push(`    ${c.present ? "✓" : "✗"} ${c.ref}`);
+        lines.push(`        required by ${c.reason}`);
+    }
+    if (result.credentials.length === 0)
+        lines.push("    (none — no config names a db-brokered credential)");
+    if (result.keyProof) {
+        lines.push("");
+        lines.push("  ENCRYPTION KEY");
+        lines.push(`    ${result.keyProof.ok ? "✓" : "✗"} tested against ${result.keyProof.ref} — ${result.keyProof.detail}`);
+    }
+    if (result.declared.length > 0) {
+        lines.push("");
+        lines.push(`  DECLARED, NOT REQUIRED (${result.declared.length}) — inventory only, never a gate`);
+        for (const c of result.declared) {
+            lines.push(`    ${c.present ? "stored" : "absent"}  ${c.ref}`);
+            lines.push(`        ${c.reason}`);
+        }
+    }
+    lines.push("");
+    lines.push(`  INGRESS ROUTES (${result.endpoints.filter((e) => e.ok).length}/${result.endpoints.length} as expected)`);
+    for (const e of result.endpoints) {
+        const observed = e.status === undefined ? "no answer" : String(e.status);
+        lines.push(`    ${e.ok ? "✓" : "✗"} ${e.method} ${e.path} → ${observed} (${e.state}, expected ${e.expect})`);
+        if (!e.ok)
+            lines.push(`        ${e.meaning}`);
+    }
+    if (result.skipped.length > 0) {
+        lines.push("");
+        lines.push(`  NOT PROBED (${result.skipped.length})`);
+        for (const s of result.skipped)
+            lines.push(`    - ${s.method} ${s.path} [${s.channel}] — ${s.reason}`);
+    }
+    if (result.heartbeats.length > 0) {
+        lines.push("");
+        lines.push(`  CRON HEARTBEATS (${result.heartbeats.filter((h) => h.ok).length}/${result.heartbeats.length} as expected) — OPE-635`);
+        for (const h of result.heartbeats) {
+            const age = h.ageHours === undefined ? "never seen" : `${h.ageHours.toFixed(1)}h old`;
+            const bound = h.maxAgeHours === undefined ? "report-only, not gated" : `bound ${h.maxAgeHours}h`;
+            lines.push(`    ${h.ok ? "✓" : "✗"} ${h.action} — ${age} (${bound})`);
+            if (!h.ok)
+                lines.push(`        ${h.reason}`);
+        }
+    }
+    if (result.runtimeSignal) {
+        lines.push("");
+        lines.push("  RUNTIME-REVISION SIGNAL (OPE-658)");
+        lines.push(`    ${result.runtimeSignal.ok ? "✓" : "✗"} ${result.runtimeSignal.detail}`);
+    }
+    if (result.credentialBrokerArmed) {
+        lines.push("");
+        lines.push("  CREDENTIAL BROKER KEY, DEPLOYMENT'S OWN (OPE-641)");
+        lines.push(`    ${result.credentialBrokerArmed.ok ? "✓" : "✗"} ${result.credentialBrokerArmed.detail}`);
+    }
+    if (result.problems.length > 0) {
+        lines.push("");
+        lines.push(`  CONFIG PROBLEMS (${result.problems.length})`);
+        for (const p of result.problems)
+            lines.push(`    ✗ ${p}`);
+    }
+    if (result.auditRows.length > 0) {
+        const exercised = result.auditRows.filter((r) => r.exercised);
+        const stated = result.auditRows.filter((r) => !r.exercised && r.notExercised !== undefined);
+        const missing = result.auditRows.filter((r) => !r.ok);
+        lines.push("");
+        lines.push(`  AUDIT ROWS (${exercised.length}/${result.auditRows.length} exercised by the pack; ${stated.length} declared not-exercised)`);
+        // Only the two halves a reader acts on are listed. Printing all 76 exercised rows would bury
+        // the few that matter under a wall nobody reads to the end of.
+        for (const r of missing)
+            lines.push(`    ✗ ${r.action} — declared consequential, NO row in this window and no stated reason`);
+        for (const r of stated)
+            lines.push(`    – ${r.action} — not exercised: ${r.notExercised}`);
+        if (missing.length === 0 && stated.length === 0)
+            lines.push("    ✓ every declared consequential row was emitted at least once");
+    }
+    if (result.limits.length > 0) {
+        lines.push("");
+        lines.push(`  NOT PROVEN BY THIS CENSUS (${result.limits.length})`);
+        for (const l of result.limits)
+            lines.push(`    ! ${l}`);
+    }
+    lines.push("");
+    if (result.ok) {
+        lines.push("✓ deploy:census: the deployment holds every row and answers on every route the config requires.");
+    }
+    else {
+        const missing = result.credentials.filter((c) => !c.present).map((c) => c.ref);
+        const dead = result.endpoints.filter((e) => !e.ok).map((e) => `${e.method} ${e.path}`);
+        const stale = result.heartbeats.filter((h) => !h.ok).map((h) => h.action);
+        lines.push("✗ deploy:census: the deployment is MISSING required state.");
+        if (missing.length > 0)
+            lines.push(`  missing credential row(s): ${missing.join(", ")}`);
+        if (dead.length > 0)
+            lines.push(`  route(s) that did not answer as required: ${dead.join(", ")}`);
+        if (stale.length > 0)
+            lines.push(`  cron(s) with no fresh heartbeat: ${stale.join(", ")}`);
+        if (result.keyProof && !result.keyProof.ok)
+            lines.push(`  encryption key: ${result.keyProof.detail}`);
+        if (result.runtimeSignal && !result.runtimeSignal.ok)
+            lines.push(`  runtime-revision signal: ${result.runtimeSignal.detail}`);
+        if (result.credentialBrokerArmed && !result.credentialBrokerArmed.ok)
+            lines.push(`  credential broker key (deployment): ${result.credentialBrokerArmed.detail}`);
+        if (result.problems.length > 0)
+            lines.push(`  config problem(s): ${result.problems.length} — see above`);
+        lines.push("  A missing row fails CLOSED at first use, with no audit trace. Store it before trusting this deploy.");
+    }
+    return lines;
+}
+//# sourceMappingURL=census.js.map