@open-everywhere/core 0.1.0

package/agent/ops/census.ts

@@ -0,0 +1,1076 @@
+// 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, type Bundle } from "../access/bundle.js";
+import type { ConnectorCredential, ConnectorCredentials } from "../access/connector-credentials.js";
+import type { CredentialBoundDomain } from "../access/domain-credentials.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";
+import type { WebhookHook } from "../webhooks/config.js";
+
+// --- the credential half -------------------------------------------------------------------------
+
+/** One credential row the deployment must hold, and the config that makes it required. */
+export interface CensusCredential {
+  /** The stored-credential ref, as the broker resolves it (`db:<connector>:<credentialId>`, or a
+   *  hook's own ref). */
+  readonly ref: string;
+  /** WHY it is required — one clause per config site that names it, joined by "; ". */
+  readonly reason: string;
+}
+
+/** A channel-plumbing credential a mounted provider resolves. The provider supplies it: the
+ *  credential is named by the code that resolves it, not by any grant, so no config join can find
+ *  it (this is exactly the `db:notion:channel-key` shape). */
+export interface PlumbingCredential {
+  readonly connector: string;
+  readonly credentialId: string;
+  readonly reason: string;
+}
+
+export interface CredentialPlanInput {
+  readonly bundles: readonly Bundle[];
+  readonly catalogues: readonly ConnectorCredentials[];
+  readonly domains: readonly (CredentialBoundDomain & { readonly name: string })[];
+  readonly hooks: readonly WebhookHook[];
+  readonly plumbing: readonly PlumbingCredential[];
+}
+
+export interface CredentialPlan {
+  /** Every required ref, deduplicated and sorted. */
+  readonly required: readonly CensusCredential[];
+  /**
+   * Every OTHER db-homed ref the catalogues declare — declared, but named by no live path.
+   * INVENTORY, never a gate. `db:notion:memory` is the standing example: it is declared so a domain
+   * binding can name it, and the org-default memory read resolves through its own broker arguments
+   * instead, so requiring a row for it would make the census permanently red and therefore ignored.
+   * Reported so the whole declared set is visible, with its store presence stated either way.
+   */
+  readonly declaredOnly: readonly CensusCredential[];
+  /** Config that names a credential its connector does not configure. The resolver contributes
+   *  nothing for such a grant, so the capability reads as live and is not. */
+  readonly problems: readonly string[];
+}
+
+function catalogueCredential(
+  catalogues: readonly ConnectorCredentials[],
+  connector: string,
+  credentialId: string,
+): ConnectorCredential | undefined {
+  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: ConnectorCredential): string | undefined {
+  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: CredentialPlanInput): CredentialPlan {
+  const reasons = new Map<string, string[]>();
+  const problems: string[] = [];
+  const add = (ref: string, reason: string): void => {
+    const list = reasons.get(ref);
+    if (list) {
+      if (!list.includes(reason)) list.push(reason);
+      return;
+    }
+    reasons.set(ref, [reason]);
+  };
+  const viaCatalogue = (connector: string, credentialId: string, reason: string, where: string): void => {
+    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: CensusCredential[] = [];
+  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 endpoint half ---------------------------------------------------------------------------
+
+/** One route of one mounted channel, as eve's own `defineChannel` declares it. */
+export interface MountedRoute {
+  /** The mounted channel module this route came from — reported so a red names the file to open. */
+  readonly channel: string;
+  readonly method: string;
+  readonly path: string;
+}
+
+/** One endpoint the census probes, and what an answer proves. */
+export interface CensusEndpoint {
+  readonly method: "POST";
+  readonly path: string;
+  readonly reason: string;
+  /** What "answering" means for THIS endpoint, in operator words. */
+  readonly meaning: string;
+  /** `mounted` — a refusal proves the route serves. `absent` — the negative control, which must 404
+   *  or every other probe on its family proves nothing. */
+  readonly expect: "mounted" | "absent";
+}
+
+export interface SkippedRoute {
+  readonly method: string;
+  readonly path: string;
+  readonly channel: string;
+  readonly reason: string;
+}
+
+export interface EndpointPlan {
+  readonly endpoints: readonly CensusEndpoint[];
+  readonly skipped: readonly SkippedRoute[];
+}
+
+/** The `/webhooks/:id` path parameter, as core's webhook channel declares it. */
+const WEBHOOK_ROUTE = "/webhooks/:id";
+
+/**
+ * A mounted channel whose routes only SERVE once an arming condition holds. Until then every route
+ * answers 404 by design, and a bare probe cannot tell that apart from a route that is not mounted.
+ *
+ * 🔴 THIS MIRRORS THE CHANNEL'S OWN CODE — it never re-decides the condition. `armed` must read the
+ * same names the channel reads, so a channel that changes what arms it and forgets this entry makes
+ * the census DEMAND a dark route again (a red on a correct deployment), never accept a missing one.
+ * That asymmetry is deliberate: the failure mode of a stale entry is a false red, not a false green.
+ */
+export interface ChannelArming {
+  /** The mounted channel file, exactly as {@link MountedRoute.channel} spells it. */
+  readonly channel: string;
+  /** Whether the plane is armed, from the environment the OPERATOR runs the census with. */
+  readonly armed: (env: NodeJS.ProcessEnv) => boolean;
+  /** The operator sentence a skip prints — it must name what to set to make the route required. */
+  readonly darkReason: string;
+}
+
+/**
+ * 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: readonly ChannelArming[] = [
+  {
+    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: {
+  readonly routes: readonly MountedRoute[];
+  readonly hooks: readonly WebhookHook[];
+  readonly controlHookId: string;
+  /** The environment the arming conditions are read from. Injectable so a suite can drive the dark
+   *  and the armed plan without touching the process. */
+  readonly env?: NodeJS.ProcessEnv;
+  /** The arming declarations to apply. Injectable for the same reason; defaults to the real table. */
+  readonly arming?: readonly ChannelArming[];
+}): EndpointPlan {
+  const endpoints: CensusEndpoint[] = [];
+  const skipped: SkippedRoute[] = [];
+  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: MountedRoute): boolean =>
+    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 };
+}
+
+/** What one observed status says about a route. */
+export type EndpointState = "mounted" | "absent" | "accepted-unsigned" | "server-error" | "unreachable";
+
+/**
+ * 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: number | undefined): EndpointState {
+  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";
+}
+
+// --- the encryption key -------------------------------------------------------------------------
+
+/** Whether the AES key opens the stored envelopes. NEVER carries a plaintext, a prefix or a length
+ *  that could narrow one — only the verdict and a fixed operator sentence. */
+export interface KeyProof {
+  /** The ref whose envelope was tested. */
+  readonly ref: string;
+  readonly ok: boolean;
+  readonly detail: string;
+}
+
+/**
+ * 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: { readonly ref: string; readonly ciphertext: string; readonly decrypt: (blob: string) => string }): KeyProof {
+  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.",
+    };
+  }
+}
+
+// --- the heartbeat half (OPE-635) -----------------------------------------------------------------
+//
+// Three schedules — directory-sync, tidy, dream-mode3 — had NO host-level proof they ever fire, and
+// one of them (directory-sync, unarmed on this deployment) was proven to be a genuine daily no-op:
+// nothing observable distinguished "ran and did nothing" from "never ran at all". The fix
+// (identity/directory-sync.ts, schedules/tidy.ts, schedules/dream-mode3.ts) makes every one of
+// those three write an audit row on EVERY tick, whatever happened — this half reads the AGE of the
+// most recent one and turns "is the cron still alive" into a number instead of folklore.
+//
+// GATED vs REPORTED. `directory.sync`/`tidy`/`mode3` heartbeats fire on a FIXED schedule regardless
+// of content, so a stale one is unambiguous evidence the cron stopped — these GATE the census.
+// `routine.fire` only writes a row when a routine is actually DUE; a deployment with no configured
+// routines never writes one at all, and that is a legitimate state, not a dead dispatcher. It is
+// REPORTED (the age, when present) but never gates — see ReportedHeartbeat.
+
+/** One scheduled action the census GATES on: a stale or missing row fails the census. */
+export interface RequiredHeartbeat {
+  readonly action: string;
+  readonly reason: string;
+  /** The bound to fail against, in hours — see {@link cronCeilingHours}. */
+  readonly maxAgeHours: number;
+}
+
+/** One scheduled action the census REPORTS the age of but never fails on — see the header above. */
+export interface ReportedHeartbeat {
+  readonly action: string;
+  readonly reason: string;
+}
+
+// --- 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: Readonly<Record<string, string>> = {
+  "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: Readonly<Record<string, readonly ReportedHeartbeat[]>> = {
+  "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: number): number {
+  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: readonly string[], discordRelayHeartbeatMs: number): readonly RequiredHeartbeat[] {
+  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: readonly string[]): {
+  readonly limits: readonly string[];
+  readonly reportedHeartbeats: readonly ReportedHeartbeat[];
+} {
+  const limits: string[] = [];
+  const reportedHeartbeats: ReportedHeartbeat[] = [];
+  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 };
+}
+
+/** One row's timestamp, as read off the audit trail. `lastSeenIso` absent = no row ever. */
+export interface HeartbeatObservation {
+  readonly action: string;
+  readonly lastSeenIso?: string;
+}
+
+export interface HeartbeatFinding {
+  readonly action: string;
+  readonly reason: string;
+  readonly lastSeenIso?: string;
+  readonly ageHours?: number;
+  /** Present only for a GATED heartbeat — a REPORTED one carries no bound to measure against. */
+  readonly maxAgeHours?: number;
+  readonly ok: boolean;
+}
+
+/**
+ * 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: string): number {
+  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: {
+  readonly gated: readonly RequiredHeartbeat[];
+  readonly reported: readonly ReportedHeartbeat[];
+  readonly observations: readonly HeartbeatObservation[];
+  readonly now: Date;
+}): readonly HeartbeatFinding[] {
+  const observed = (action: string): HeartbeatObservation | undefined => input.observations.find((o) => o.action === action);
+  const ageHoursOf = (iso: string): number => (input.now.getTime() - new Date(iso).getTime()) / 3_600_000;
+
+  const gated = input.gated.map((h): HeartbeatFinding => {
+    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): HeartbeatFinding => {
+    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];
+}
+
+// --- the runtime-revision signal half (OPE-658) ---------------------------------------------------
+//
+// Eve re-derives a live session's dynamic-tool roster on the first turn under a deployment revision
+// it has not seen, keyed off `VERCEL_DEPLOYMENT_ID` (packages/core/scripts/window-gated-test.ts §6
+// pins the mechanism against the installed eve dist). A STANDING seat does not reach that path on a
+// deploy: its workflow run is pinned to the deployment that minted it, so the revision its turns
+// stamp never changes and it keeps the minting deployment's roster until channels/runtime-rotation.ts
+// retires the generation — which it does when the running CODE fingerprint, or the seat's own domain
+// fingerprint, differs from the pair the seat was last served with (OPE-1821), never on a deployment
+// id alone. So this signal is about EVE's refresh path, not OE's rotation, and a deployment id that
+// moved without a code change correctly rotates nothing. That is tier 1 — it proves the CODE is
+// correct. It
+// cannot prove the env var is actually non-empty on THIS deployment's running function: that is a
+// Vercel platform fact, visible only from inside the process, and no offline tier can see it.
+//
+// So this half asks the deployment itself, over the same service-token control-read family the
+// credential and heartbeat checks already ride (`GET /control/v1/runtime-signal`, agent/control/
+// read-route.ts handleRuntimeSignalRead). PRESENCE, NEVER VALUE — the route answers a boolean,
+// never the id, matching the credential half's own posture.
+//
+// WHAT THIS DOES NOT PROVE. A non-empty env var is the SIGNAL the refresh mechanism reads. It is
+// not the CONSEQUENCE — proof that a STANDING session actually re-derived its roster under a new
+// deployment id. That read needs a durable session's internal tool-lifecycle context, which no
+// route exposes today; OPE-658 scoped that out rather than build it unreviewed (see the ticket for
+// the follow-up). A green here is deliberately read as "the signal exists", never as "every
+// standing seat is fresh".
+
+/** One `GET /control/v1/runtime-signal` observation, or absent when the call could not be made
+ *  (no token, the route 404s/401s, a network failure). */
+export interface RuntimeSignalFinding {
+  readonly ok: boolean;
+  readonly detail: string;
+}
+
+/**
+ * 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: { readonly hasDeploymentId: boolean } | undefined): RuntimeSignalFinding {
+  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.",
+      };
+}
+
+// --- the credential-broker-armed signal half (OPE-641) ---------------------------------------------
+//
+// `proveKeyOpensRow` above proves the key THIS census process holds opens a stored row. It says
+// nothing about the DEPLOYMENT's own key — `OE_CREDENTIAL_ENCRYPTION_KEY` is read per-process, and
+// if it is dropped from the deployment's environment `registerDbCredentialBroker()` never runs
+// (agent/lib/register-adapters.ts), so EVERY `broker: "db"` credential fails closed at once, behind
+// 200 responses, with no audit trace. Nothing observable from outside the deployment used to report
+// that state.
+//
+// So this half asks the deployment itself, over the same service-token control-read family the
+// runtime-revision signal already rides (`GET /control/v1/runtime-signal`, agent/control/
+// read-route.ts handleRuntimeSignalRead — one route answers both fields to avoid a second
+// token-parse/audit boilerplate block). PRESENCE, NEVER VALUE: the route answers a boolean, sourced
+// from `credentialKeyArmed()`, which never returns or logs the key.
+
+/** One `GET /control/v1/runtime-signal` `credentialBrokerArmed` observation, or absent when the
+ *  call could not be made (no token, the route 404s/401s, a network failure, or an older
+ *  deployment whose route does not yet carry the field). */
+export interface CredentialBrokerArmedFinding {
+  readonly ok: boolean;
+  readonly detail: string;
+}
+
+/**
+ * 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: { readonly credentialBrokerArmed: boolean } | undefined): CredentialBrokerArmedFinding {
+  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.",
+      };
+}
+
+// --- the verdict ---------------------------------------------------------------------------------
+
+export interface CredentialFinding {
+  readonly ref: string;
+  readonly reason: string;
+  readonly present: boolean;
+}
+
+export interface EndpointFinding {
+  readonly method: "POST";
+  readonly path: string;
+  readonly reason: string;
+  readonly meaning: string;
+  readonly expect: "mounted" | "absent";
+  readonly status?: number;
+  readonly state: EndpointState;
+  readonly ok: boolean;
+}
+
+/**
+ * THE AUDIT-ROW EXERCISE CHECK (OPE-1837) — one finding per CONSEQUENTIAL audit action the registry
+ * declares.
+ *
+ * WHY THE CENSUS AND NOT A TEST TIER. `npm test` proves the code that writes a row. It cannot prove
+ * the ship's own e2e pack ever DROVE the path that writes it, and an action no journey exercises is
+ * an action whose disappearance nothing reds: 22% of this tree's audit actions were named by no
+ * test, e2e or soak (coverage audit, 2026-09-14). The census reads the DEPLOYMENT's own audit log
+ * after a pack, which is the only place that question has an answer.
+ *
+ * 🔴 ABSENCE IS A FINDING, NOT A FAILURE, AND THE DIFFERENCE IS THE REGISTRY'S OWN `notExercised`.
+ * A declaration carrying a reason is reported as a stated gap and does not gate; a declaration
+ * WITHOUT one is a row the pack was supposed to produce and did not. That is what makes the reason
+ * field a debt with somebody's name on it rather than a way to silence the check.
+ */
+export interface AuditRowFinding {
+  readonly action: string;
+  /** True when at least one row with this action was found in the window. */
+  readonly exercised: boolean;
+  /** The registry's reason this row is not exercised, when it carries one. */
+  readonly notExercised?: string;
+  /** ISO timestamp of the most recent row, when there is one. */
+  readonly lastSeenIso?: string;
+  /** False only for a declaration with no row AND no stated reason. */
+  readonly ok: boolean;
+}
+
+/**
+ * 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: { readonly action: string; readonly notExercised?: string },
+  lastSeenIso: string | undefined,
+): AuditRowFinding {
+  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: readonly AuditRowFinding[]): readonly string[] {
+  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`,
+    );
+}
+
+export interface CensusResult {
+  readonly ok: boolean;
+  readonly target: string;
+  readonly storeLabel: string;
+  readonly credentials: readonly CredentialFinding[];
+  /** Declared-but-unrequired refs, with their presence — inventory only, never a gate. */
+  readonly declared: readonly CredentialFinding[];
+  readonly endpoints: readonly EndpointFinding[];
+  readonly skipped: readonly SkippedRoute[];
+  readonly problems: readonly string[];
+  /** Absent when the key check was not run (`--no-key-check`, or no row to test). */
+  readonly keyProof?: KeyProof;
+  /** OPE-635 — the scheduled-action liveness read (see the heartbeat half above). Empty when the
+   *  caller ran with `--no-heartbeat-check`. */
+  readonly heartbeats: readonly HeartbeatFinding[];
+  /** OPE-658 — the runtime-revision signal (see the section above). Absent when the caller ran
+   *  with `--no-runtime-signal-check`. */
+  readonly runtimeSignal?: RuntimeSignalFinding;
+  /** OPE-641 — the deployment's own credential-encryption-key-armed signal (see the section
+   *  above). Absent when the caller ran with `--no-credential-key-armed-check`. */
+  readonly credentialBrokerArmed?: CredentialBrokerArmedFinding;
+  /** OPE-1837 — one finding per consequential audit action the registry declares. Empty when the
+   *  caller ran with `--no-audit-row-check`. */
+  readonly auditRows: readonly AuditRowFinding[];
+  /** What the census did NOT establish, stated so a green is never read as wider than it is. */
+  readonly limits: readonly string[];
+}
+
+/** One observed probe result. `status` is absent when the request never completed. */
+export interface EndpointObservation {
+  readonly path: string;
+  readonly status?: number;
+}
+
+/**
+ * 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: {
+  readonly target: string;
+  readonly storeLabel: string;
+  readonly plan: CredentialPlan;
+  readonly endpoints: EndpointPlan;
+  readonly presentRefs: readonly string[];
+  readonly observations: readonly EndpointObservation[];
+  readonly keyProof?: KeyProof;
+  readonly heartbeats?: readonly HeartbeatFinding[];
+  readonly runtimeSignal?: RuntimeSignalFinding;
+  readonly credentialBrokerArmed?: CredentialBrokerArmedFinding;
+  readonly auditRows?: readonly AuditRowFinding[];
+  readonly limits?: readonly string[];
+}): CensusResult {
+  const present = new Set(input.presentRefs);
+  const finding = (c: CensusCredential): CredentialFinding => ({ 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: CensusResult): string[] {
+  const lines: string[] = [];
+  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;
+}