@open-everywhere/core 0.1.0

package/agent/review/facts-artifact.ts

@@ -0,0 +1,377 @@
+// THE ATTRIBUTABLE FACTS SOURCE — fetches OPE-255's resolved-config diff for a pull request from
+// the WORKFLOW ARTIFACT that produced it, and from nowhere else.
+//
+// 🔴 THE ACTIONS LANE IS DORMANT ON OPEN EVERYWHERE'S OWN REPOSITORY (OPE-1173). PR #408 deleted
+// `.github/workflows/`, so no run of {@link CONFIG_DIFF_WORKFLOW_PATH} exists and the artifact half
+// of this module can only ever answer `not-triggered` or `unavailable` there. The module is NOT
+// dead: it reads the repository under review, and a deployer repo that runs the workflow still feeds
+// it.
+//
+// SO THERE ARE TWO PROVENANCES SINCE OPE-1683, tried in this order by {@link fetchConfigFacts}:
+//   ① the Actions artifact below — for any repository that runs the workflow;
+//   ② a commit status vouching for a document by sha256 (`./facts-cloud-status.ts`) — for a
+//      repository like this one that runs no Actions at all, where a cloud run computes the same
+//      `scripts/config-diff.ts` output and the orchestrator posts `oe/config-diff` on the head sha.
+// ① is consulted FIRST because its attribution rests on a CODEOWNED workflow file. ② is consulted
+// whenever ① produced no document — and that includes the cases where ① found a run and REFUSED what
+// it carried: an expired artifact, a zip that yields no `config-diff.json`, an unparseable document,
+// a failed download. Say that plainly, because it means a deployer repository whose artifact expires
+// falls to the weaker provenance rather than to an UNKNOWN. What keeps that honest is that the
+// render always NAMES which provenance supplied the document, and §5 states that lane's own bound.
+// When both come back empty the answer is `unavailable` naming BOTH reasons — an UNKNOWN, rendered
+// as an unknown.
+//
+// ⭐⭐ THE WHOLE POINT OF THIS MODULE IS WHAT IT REFUSES TO READ. OPE-255's CI job posts its report
+// as a PR comment AND uploads it as an artifact, and it says why in its own header: *anyone who can
+// comment on a PR can post something that merely LOOKS like that report.* A walkthrough built on
+// comment text would inherit that forgery — and the walkthrough exists to be the thing a merging
+// human trusts. So:
+//
+//   🔴 THERE IS NO CODE PATH IN THIS MODULE THAT READS A PR COMMENT. Not a preferred path with a
+//   comment fallback; not a comment path behind a flag. The GitHub comment API is never called,
+//   which is why "the facts came from a forged comment" is not a failure mode that has to be
+//   argued about — it is unreachable. The cost of that choice is that a PR whose CI has not
+//   finished, or whose artifact has expired, yields `unavailable` with a reason. That is the
+//   correct outcome: an UNKNOWN, rendered as an unknown.
+//
+// ⭐ WHAT MAKES THE ARTIFACT ATTRIBUTABLE, precisely — three checks, all of them cheap:
+//   ① the run's `path` must be exactly {@link CONFIG_DIFF_WORKFLOW_PATH}. An artifact called
+//      `config-diff` uploaded by some OTHER workflow (which a PR author can add, since a PR can
+//      edit `.github/workflows/`) is rejected. The workflow FILE is CODEOWNED; a workflow's
+//      identity is therefore a reviewed fact, and its artifact inherits that.
+//   ② the run's `head_sha` must equal the head sha we asked about, so a stale run against an
+//      earlier push cannot be presented as describing the current diff.
+//   ③ the run must have been triggered by `pull_request` — the only event the gate declares, and
+//      the only one whose token cannot write to the repo.
+//   The run id and its URL travel with the facts (`FactsProvenance`) so a reviewer can open the
+//   exact run that produced them. A walkthrough that cannot name its run is not a walkthrough.
+//
+// ⚠️ WHAT THIS DOES **NOT** ESTABLISH, stated here because the renderer quotes it: a GitHub Actions
+// artifact is not signed. Anyone with `actions: write` on the repository (or a maintainer re-running
+// a job from a modified branch) can produce a run whose artifact says whatever they like. The
+// property bought here is *"these facts came from a named run of a CODEOWNED workflow at this exact
+// head sha"* — which is strictly stronger than a comment, and strictly weaker than a signature.
+// Closing the remaining gap needs artifact attestations, which are out of this module's scope.
+//
+// Every network edge is injectable (`fetchFn`) so the whole path is offline-testable, with the live
+// default used byte-for-byte in production — the same discipline approvals/access-request.ts uses.
+
+import { prApiHeaders } from "../scm/pr.js";
+import { parseConfigFacts, type ConfigFacts } from "./config-facts.js";
+import { fetchCloudStatusFacts, type CloudStatusFacts } from "./facts-cloud-status.js";
+import { readZipTextEntry, ZipReadError } from "./zip.js";
+
+/**
+ * Minimal fetch shape for this module — `scm/pr.ts`'s `PrFetchFn` plus `arrayBuffer()`, because the
+ * artifact download is BINARY (a zip) and that is the one GitHub read in the tree that isn't text.
+ * Declared here rather than widened on `PrFetchFn`: every other caller of that type GETs JSON, and
+ * adding a binary method to the shared shape would oblige each of their test doubles to grow one.
+ */
+export type ArtifactFetchFn = (
+  url: string,
+  init: { method: string; headers: Record<string, string> },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string>; json(): Promise<unknown>; arrayBuffer(): Promise<ArrayBuffer> }>;
+
+/** The workflow file whose runs are the ONLY accepted source of config facts. CODEOWNED. */
+export const CONFIG_DIFF_WORKFLOW_PATH = ".github/workflows/config-diff.yml";
+
+/** The artifact name the workflow's upload step uses. */
+export const CONFIG_DIFF_ARTIFACT_NAME = "config-diff";
+
+/** The machine-readable entry inside that artifact — OPE-255's `--json` output. */
+const CONFIG_DIFF_JSON_ENTRY = "config-diff.json";
+
+/** The overlay single-scope gate's report, also in the artifact. The HARD gate's own words. */
+const OVERLAY_GATE_ENTRY = "access-diff.md";
+
+/** Char cap on the overlay-gate report carried into a render. */
+const MAX_OVERLAY_REPORT_CHARS = 8000;
+
+/** Cap on the artifact zip we will download. An Actions artifact this big is not our facts document. */
+const MAX_ARTIFACT_BYTES = 16 * 1024 * 1024;
+
+/**
+ * Which changed paths make a config diff meaningful. A walkthrough uses it to distinguish "the gate
+ * did not run because this PR touches no config" (a COMPUTED absence) from "the gate should have run
+ * and we cannot find its output" (an UNKNOWN). Those two must never render the same way, and only
+ * this list can tell them apart.
+ *
+ * 🔴 KEPT HONEST BY A TEST, NOT BY DISCIPLINE: `scripts/pr-walkthrough-facts-test.ts` joins every
+ * glob below to the repo's own tracked files and refuses one that matches nothing. Core cannot read
+ * the repo (there is none at runtime), so the app tier binds them — the same split
+ * `packages/core/scripts/codeowners-coverage-test.ts` uses for CODEOWNERS. A glob naming a path the
+ * tree no longer has is the failure this catches: it can never match, so it silently narrows the
+ * trigger set and turns an UNKNOWN into a computed absence.
+ *
+ * ⚠️ WHAT THE JOIN DOES NOT CATCH: a MISSING entry. It reads each glob and asks whether the tree has
+ * a file for it; it has no second list to compare against, so a config path nobody added here stays
+ * invisible. The mirror that did catch that read the config-diff workflow's own `paths:` filter, and
+ * OPE-1113 deleted the workflow. A deployment that restores one owes this list a fresh comparison.
+ */
+export const CONFIG_DIFF_TRIGGER_PATHS: readonly string[] = [
+  "agent/**",
+  "scripts/config-snapshot*.ts",
+  "scripts/config-diff.ts",
+  "scripts/access-diff.ts",
+];
+
+/**
+ * Does `path` match one of GitHub's `paths:` globs? Supports the two forms the filter actually
+ * uses — a trailing `**` (any depth) and a single `*` inside one segment — and nothing else, so a
+ * glob form nobody wrote cannot be silently mis-matched. Pure.
+ */
+export function pathMatchesGlob(path: string, glob: string): boolean {
+  const rx = glob
+    .split("**")
+    .map((part) =>
+      part
+        .split("*")
+        .map((lit) => lit.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join("[^/]*"),
+    )
+    .join(".*");
+  return new RegExp(`^${rx}$`).test(path);
+}
+
+/** True iff a PR touching `paths` would trigger the config-diff workflow at all. */
+export function triggersConfigDiff(paths: readonly string[]): boolean {
+  return paths.some((p) => CONFIG_DIFF_TRIGGER_PATHS.some((g) => pathMatchesGlob(p, g)));
+}
+
+/** Where a facts document came from — carried into the render so a reviewer can go and check it. */
+export interface FactsProvenance {
+  readonly repo: string;
+  readonly headSha: string;
+  readonly workflowPath: string;
+  readonly runId: number;
+  readonly runUrl: string;
+  readonly runAttempt: number;
+  readonly runConclusion: string | null;
+  readonly artifactId: number;
+  readonly artifactName: string;
+}
+
+/**
+ * The facts, or a stated reason there are none. FOUR outcomes, never two — `artifact` and
+ * `cloud-status` are the two provenances the header names, `not-triggered` is a computed absence and
+ * `unavailable` is an unknown, and the renderer shows all four differently.
+ */
+export type FactsSource =
+  | Extract<CloudStatusFacts, { kind: "cloud-status" }>
+  | {
+      readonly kind: "artifact";
+      readonly facts: ConfigFacts;
+      readonly provenance: FactsProvenance;
+      /** The overlay single-scope gate's own report, verbatim and bounded, when the artifact carried it. */
+      readonly overlayGateReport: string | undefined;
+    }
+  | {
+      readonly kind: "not-triggered";
+      /** Which of the trigger globs went unmatched is not interesting; WHY there are no facts is. */
+      readonly reason: string;
+    }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+interface WorkflowRun {
+  readonly id: number;
+  readonly path?: string;
+  readonly event?: string;
+  readonly head_sha?: string;
+  readonly html_url?: string;
+  readonly run_attempt?: number;
+  readonly conclusion?: string | null;
+  readonly created_at?: string;
+}
+
+export interface FetchConfigFactsOpts {
+  readonly repo: string;
+  readonly headSha: string;
+  readonly token: string;
+  /** The files this PR touches, when known — lets a non-config PR report `not-triggered`. */
+  readonly changedPaths?: readonly string[];
+  readonly fetchFn?: ArtifactFetchFn;
+  readonly apiBase?: string;
+}
+
+/**
+ * Fetch the config-diff facts for one PR head, from whichever provenance can produce them.
+ *
+ * The order and what it means is in the header. In short: a PR that touches no config answers
+ * `not-triggered` without a single request; otherwise the CODEOWNED Actions artifact is tried first
+ * and the vouching commit status second, and an answer from either is returned as it stands.
+ *
+ * NEVER THROWS — every failure of either lane is an outcome with a reason, because a throw here
+ * would surface to the caller as a tool error and a tool error reads, to a model and then to a
+ * human, as "the check didn't apply". Even a transport failure becomes `unavailable`.
+ *
+ * 🔴 WHEN BOTH LANES COME BACK EMPTY THE REASON NAMES BOTH. A single reason would read as "the
+ * workflow has not finished" on a repository that has no workflow at all, and an operator would go
+ * looking for a run rather than for the status that was actually missing.
+ */
+export async function fetchConfigFacts(opts: FetchConfigFactsOpts): Promise<FactsSource> {
+  if (opts.changedPaths !== undefined && !triggersConfigDiff(opts.changedPaths)) {
+    return {
+      kind: "not-triggered",
+      reason:
+        `this PR touches none of the deployer-config paths a resolved-config diff covers (${CONFIG_DIFF_TRIGGER_PATHS.join(", ")}), ` +
+        `so no resolved-config facts exist for it. That is a COMPUTED absence, not a blind spot: the deployer config is unchanged by ` +
+        `this PR. It says nothing about the CODE the PR changes — code is reviewed as code (CODEOWNERS), and no config diff can see it.`,
+    };
+  }
+
+  const viaArtifact = await fetchWorkflowArtifactFacts(opts);
+  if (viaArtifact.kind === "artifact") return viaArtifact;
+
+  const viaStatus = await fetchCloudStatusFacts({
+    repo: opts.repo,
+    headSha: opts.headSha,
+    token: opts.token,
+    ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}),
+    ...(opts.apiBase ? { apiBase: opts.apiBase } : {}),
+  });
+  if (viaStatus.kind === "cloud-status") return viaStatus;
+
+  return {
+    kind: "unavailable",
+    reason: `NEITHER facts provenance produced a document. Actions artifact: ${viaArtifact.reason} — Commit status: ${viaStatus.reason}`,
+  };
+}
+
+/**
+ * The Actions half — the CODEOWNED-workflow artifact and nothing else. Split out of
+ * {@link fetchConfigFacts} by OPE-1683 so the two provenances are separately readable and separately
+ * testable; the three attribution checks below are unchanged.
+ */
+async function fetchWorkflowArtifactFacts(
+  opts: FetchConfigFactsOpts,
+): Promise<Extract<FactsSource, { kind: "artifact" }> | { kind: "unavailable"; reason: string }> {
+  const fetchFn = opts.fetchFn ?? (globalThis.fetch as unknown as ArtifactFetchFn);
+  const apiBase = opts.apiBase ?? "https://api.github.com";
+  const headers = prApiHeaders(opts.token);
+
+  let runs: readonly WorkflowRun[];
+  try {
+    const res = await fetchFn(`${apiBase}/repos/${opts.repo}/actions/runs?head_sha=${encodeURIComponent(opts.headSha)}&per_page=100`, {
+      method: "GET",
+      headers,
+    });
+    if (!res.ok) {
+      return { kind: "unavailable", reason: `the workflow-run listing for ${opts.repo}@${opts.headSha.slice(0, 12)} failed: ${res.status} ${await safeText(res)}` };
+    }
+    const body = (await res.json()) as { workflow_runs?: WorkflowRun[] };
+    runs = body.workflow_runs ?? [];
+  } catch (err) {
+    return { kind: "unavailable", reason: `the workflow-run listing could not be read: ${errText(err)}` };
+  }
+
+  // ── the three attribution checks (see the header) ─────────────────────────────────────────
+  const candidates = runs
+    .filter((r) => r.path === CONFIG_DIFF_WORKFLOW_PATH)
+    .filter((r) => r.head_sha === opts.headSha)
+    .filter((r) => r.event === "pull_request")
+    .sort((a, b) => (b.run_attempt ?? 1) - (a.run_attempt ?? 1) || (b.created_at ?? "").localeCompare(a.created_at ?? "") || b.id - a.id);
+
+  if (candidates.length === 0) {
+    const others = runs.filter((r) => r.path === CONFIG_DIFF_WORKFLOW_PATH).length;
+    return {
+      kind: "unavailable",
+      reason:
+        `no \`pull_request\` run of ${CONFIG_DIFF_WORKFLOW_PATH} exists for head sha ${opts.headSha.slice(0, 12)} ` +
+        `(${runs.length} run(s) at this sha, ${others} of them from that workflow). Either CI has not finished, or the run was ` +
+        `re-triggered by a different event. This is an UNKNOWN — the config facts for this PR are NOT established.`,
+    };
+  }
+  const run = candidates[0];
+
+  let artifact: { id: number; name: string } | undefined;
+  try {
+    const res = await fetchFn(`${apiBase}/repos/${opts.repo}/actions/runs/${run.id}/artifacts?per_page=100`, { method: "GET", headers });
+    if (!res.ok) {
+      return { kind: "unavailable", reason: `the artifact listing for run ${run.id} failed: ${res.status} ${await safeText(res)}` };
+    }
+    const body = (await res.json()) as { artifacts?: { id?: number; name?: string; expired?: boolean }[] };
+    const hit = (body.artifacts ?? []).find((a) => a.name === CONFIG_DIFF_ARTIFACT_NAME && a.expired !== true && typeof a.id === "number");
+    if (!hit) {
+      const expired = (body.artifacts ?? []).some((a) => a.name === CONFIG_DIFF_ARTIFACT_NAME && a.expired === true);
+      return {
+        kind: "unavailable",
+        reason: expired
+          ? `run ${run.id}'s "${CONFIG_DIFF_ARTIFACT_NAME}" artifact has EXPIRED (Actions retention), so the facts it computed are gone. Re-run the workflow to recompute them. This is an UNKNOWN, not a pass.`
+          : `run ${run.id} uploaded no "${CONFIG_DIFF_ARTIFACT_NAME}" artifact — the config-diff step may have failed before writing one. Read the run log: ${run.html_url ?? "(no url)"}. This is an UNKNOWN, not a pass.`,
+      };
+    }
+    artifact = { id: hit.id!, name: hit.name! };
+  } catch (err) {
+    return { kind: "unavailable", reason: `the artifact listing could not be read: ${errText(err)}` };
+  }
+
+  let zip: Buffer;
+  try {
+    const res = await fetchFn(`${apiBase}/repos/${opts.repo}/actions/artifacts/${artifact.id}/zip`, { method: "GET", headers });
+    if (!res.ok) {
+      return { kind: "unavailable", reason: `downloading artifact ${artifact.id} failed: ${res.status} ${await safeText(res)}` };
+    }
+    const bytes = Buffer.from(await res.arrayBuffer());
+    if (bytes.length > MAX_ARTIFACT_BYTES) {
+      return { kind: "unavailable", reason: `artifact ${artifact.id} is ${bytes.length} bytes, over the ${MAX_ARTIFACT_BYTES}-byte cap — refusing to read it` };
+    }
+    zip = bytes;
+  } catch (err) {
+    return { kind: "unavailable", reason: `artifact ${artifact.id} could not be downloaded: ${errText(err)}` };
+  }
+
+  let json: string;
+  try {
+    json = readZipTextEntry(zip, CONFIG_DIFF_JSON_ENTRY);
+  } catch (err) {
+    return {
+      kind: "unavailable",
+      reason: `artifact ${artifact.id} does not yield ${CONFIG_DIFF_JSON_ENTRY}: ${err instanceof ZipReadError ? err.message : errText(err)}`,
+    };
+  }
+
+  const parsed = parseConfigFacts(json);
+  if (!parsed.ok) {
+    return { kind: "unavailable", reason: `artifact ${artifact.id}'s ${CONFIG_DIFF_JSON_ENTRY} could not be read: ${parsed.reason}` };
+  }
+
+  // Best-effort, and its absence is stated rather than assumed: the overlay gate's report is the
+  // HARD gate's own words, and a walkthrough that quietly omitted it would be hiding the one
+  // assertion in this system that can fail a job.
+  let overlayGateReport: string | undefined;
+  try {
+    const text = readZipTextEntry(zip, OVERLAY_GATE_ENTRY);
+    overlayGateReport = text.length > MAX_OVERLAY_REPORT_CHARS ? `${text.slice(0, MAX_OVERLAY_REPORT_CHARS)}\n…[clipped at ${MAX_OVERLAY_REPORT_CHARS} chars]` : text;
+  } catch {
+    overlayGateReport = undefined;
+  }
+
+  return {
+    kind: "artifact",
+    facts: parsed.facts,
+    overlayGateReport,
+    provenance: {
+      repo: opts.repo,
+      headSha: opts.headSha,
+      workflowPath: CONFIG_DIFF_WORKFLOW_PATH,
+      runId: run.id,
+      runUrl: run.html_url ?? `https://github.com/${opts.repo}/actions/runs/${run.id}`,
+      runAttempt: run.run_attempt ?? 1,
+      runConclusion: run.conclusion ?? null,
+      artifactId: artifact.id,
+      artifactName: artifact.name,
+    },
+  };
+}
+
+async function safeText(res: { text(): Promise<string> }): Promise<string> {
+  try {
+    return (await res.text()).slice(0, 300);
+  } catch {
+    return "(no body)";
+  }
+}
+
+function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/agent/review/facts-cloud-status.ts

@@ -0,0 +1,288 @@
+// THE SECOND FACTS PROVENANCE — a config-diff document vouched for by a COMMIT STATUS, for a
+// repository that runs no GitHub Actions (OPE-1683).
+//
+// 🔴 WHY THIS EXISTS. `./facts-artifact.ts` reads the resolved-config facts from a run of
+// `.github/workflows/config-diff.yml` and from nowhere else. PR #408 deleted every workflow on this
+// repository and CLAUDE.md forbids adding one back, so on Open Everywhere's OWN pull requests that
+// module can only ever answer `unavailable`, and `walk_pr`'s two-toned document — 🧮 facts against
+// 🗣️ narration — never shows its facts tone on the repository that built it. The facts half was
+// dark exactly where it is read most.
+//
+// ⭐ THE TRUST SHAPE, and it is deliberately the SAME ONE `oe/cloud-proof` already uses. A cloud run
+// executes `scripts/config-diff.ts --json`, which prints the document's sha256. The orchestrator —
+// a principal holding real `gh` auth — posts a commit status on the pull request's HEAD SHA:
+//   context     `oe/config-diff`
+//   description `sha256:<64 hex> session=<the run that produced it>`
+//   target_url  where the document can be fetched
+// The identity of the facts is therefore THE STATUS CONTEXT PLUS THE POSTING PRINCIPAL, not a
+// workflow file. Posting a commit status needs `statuses: write` on the repository, so a status is
+// attributable in the same way and to the same degree a workflow run is.
+//
+// 🔴 THE HOSTING LOCATION IS NOT TRUSTED, AND DOES NOT NEED TO BE. The document is accepted only
+// when its sha256 equals the digest the STATUS named. So a `target_url` that serves different bytes
+// — a swapped release asset, a redirect to somewhere else, a cache — is REFUSED rather than
+// believed. That is what lets this module follow a redirect at all, and it is why the URL fence
+// below is defence in depth rather than the property that carries the trust.
+//
+//   ① the status must sit on the exact head sha asked about, so a status posted for an earlier push
+//      cannot be presented as describing the current diff;
+//   ② its context must be exactly {@link CONFIG_DIFF_STATUS_CONTEXT};
+//   ③ its description must parse to a sha256 digest — a status whose description says anything else
+//      vouches for nothing and is refused, never "trusted because it exists";
+//   ④ the fetched bytes must hash to that digest;
+//   ⑤ only the LATEST status for that context counts, which is what GitHub's own combined-status
+//      view shows a human — so this module and a reviewer's browser can never disagree about which
+//      status is in force.
+//
+// ⚠️ WHAT THIS DOES NOT ESTABLISH, stated here because the renderer quotes it: a commit status is not
+// a signature. ANYONE with `statuses: write` on the repository can post one saying whatever they
+// like, and this module cannot tell an orchestrator's status from any other writer's. The property
+// bought is *"a principal who can write statuses on this repository vouched for exactly these bytes
+// at this exact head sha"* — strictly stronger than a pull-request comment, strictly weaker than a
+// signature, and exactly the property `oe/cloud-proof` rests on.
+//
+// 🔴 NO COMMENT PATH HERE EITHER. `./facts-artifact.ts` refuses to read a pull-request comment
+// because anyone who can comment can forge one. Nothing below calls the comment API. A commit
+// status is not a comment: it needs write access, GitHub attributes it, and it cannot be posted by
+// an outside contributor whose fork-based pull request is under review.
+
+import { createHash } from "node:crypto";
+import { prApiHeaders } from "../scm/pr.js";
+import { parseConfigFacts, type ConfigFacts } from "./config-facts.js";
+
+/** The commit-status `context:` this lane posts under and this module reads. */
+export const CONFIG_DIFF_STATUS_CONTEXT = "oe/config-diff";
+
+/** Cap on the facts document. A config-diff JSON this big is not our facts document. */
+const MAX_FACTS_DOCUMENT_BYTES = 8 * 1024 * 1024;
+
+/** The response shape this module needs — narrower than `Response`, so a suite hands it a literal. */
+export interface StatusFetchResponse {
+  readonly ok: boolean;
+  readonly status: number;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+}
+
+export type StatusFetchFn = (url: string, init: { method: string; headers: Record<string, string> }) => Promise<StatusFetchResponse>;
+
+/** Where a status-vouched facts document came from — carried into the render so a reviewer can check it. */
+export interface CloudStatusProvenance {
+  readonly repo: string;
+  readonly headSha: string;
+  readonly statusContext: string;
+  /** The sha256 the STATUS named, and which the fetched bytes were verified against. */
+  readonly digest: string;
+  /** Where the bytes were fetched from. Untrusted by design — the digest is what vouches for them. */
+  readonly documentUrl: string;
+  /** The cloud run named in the status description, so the transcript that produced the facts is
+   *  findable. Absent when the description named none. */
+  readonly sessionId: string | undefined;
+  /** When GitHub recorded the status. */
+  readonly postedAtIso: string | undefined;
+  /** The GitHub login the status is attributed to, when the API reported one. */
+  readonly postedBy: string | undefined;
+}
+
+/** The facts, or a stated reason there are none. Never a throw — see {@link fetchCloudStatusFacts}. */
+export type CloudStatusFacts =
+  | { readonly kind: "cloud-status"; readonly facts: ConfigFacts; readonly provenance: CloudStatusProvenance }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+/** The sha256 of a facts document, lowercase hex — the one definition both halves of this lane use. */
+export function configFactsDigest(document: string): string {
+  return createHash("sha256").update(document, "utf8").digest("hex");
+}
+
+/**
+ * The status `description` a publisher must post. GitHub truncates a description at 140 bytes, and a
+ * 64-character digest plus its prefix is 71, so the SESSION id is what a long value would cost —
+ * which is why the digest comes first. Pure.
+ */
+export function buildConfigDiffStatusDescription(input: { digest: string; sessionId?: string }): string {
+  const head = `sha256:${input.digest}`;
+  const full = input.sessionId ? `${head} session=${input.sessionId}` : head;
+  return full.length <= 140 ? full : `${full.slice(0, 139)}…`;
+}
+
+/**
+ * Read a digest (and the session id, when present) back out of a status description.
+ *
+ * 🔴 ANSWERS undefined FOR ANYTHING IT CANNOT PARSE, and the caller then refuses the status. A
+ * description that does not name a full 64-hex sha256 vouches for no particular bytes, so accepting
+ * it would turn "a status exists" into "the facts are established" — which is the one inference this
+ * module is built to prevent. Pure.
+ */
+export function parseConfigDiffStatusDescription(description: string | null | undefined): { digest: string; sessionId: string | undefined } | undefined {
+  if (typeof description !== "string") return undefined;
+  const digest = /(?:^|\s)sha256:([0-9a-f]{64})(?:\s|$)/u.exec(description);
+  if (!digest) return undefined;
+  const session = /(?:^|\s)session=([^\s]+)/u.exec(description);
+  return { digest: digest[1], sessionId: session ? session[1] : undefined };
+}
+
+/**
+ * Is `url` a place this module will fetch a facts document from?
+ *
+ * Defence in depth, NOT the trust property — the digest check is what makes the bytes safe. This
+ * exists so a status pointing at an arbitrary host cannot make a host-side tool dial it at all, and
+ * so the read token below is never offered to anything but GitHub's API host.
+ *
+ * Three shapes, all of them serving THIS repository: the API host, the raw-content host, and the
+ * release-download path on github.com. Anything else is refused. Pure.
+ */
+export function isAllowedFactsDocumentUrl(url: string, repo: string): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "https:") return false;
+  if (parsed.host === "api.github.com") return parsed.pathname.startsWith(`/repos/${repo}/`);
+  if (parsed.host === "raw.githubusercontent.com") return parsed.pathname.startsWith(`/${repo}/`);
+  if (parsed.host === "github.com") return parsed.pathname.startsWith(`/${repo}/releases/download/`);
+  return false;
+}
+
+interface CommitStatus {
+  readonly context?: string;
+  readonly description?: string | null;
+  readonly target_url?: string | null;
+  readonly created_at?: string;
+  readonly updated_at?: string;
+  readonly creator?: { login?: string } | null;
+}
+
+export interface FetchCloudStatusFactsOpts {
+  readonly repo: string;
+  readonly headSha: string;
+  readonly token: string;
+  readonly fetchFn?: StatusFetchFn;
+  readonly apiBase?: string;
+}
+
+/**
+ * Fetch the config-diff facts a commit status vouches for, for one pull-request head.
+ *
+ * NEVER THROWS — every failure is an `unavailable` with a reason, for the same reason
+ * `./facts-artifact.ts` states: a throw reaches a model, and then a human, as "the check did not
+ * apply", which is not what a missing document means.
+ */
+export async function fetchCloudStatusFacts(opts: FetchCloudStatusFactsOpts): Promise<CloudStatusFacts> {
+  const fetchFn = opts.fetchFn ?? (globalThis.fetch as unknown as StatusFetchFn);
+  const apiBase = opts.apiBase ?? "https://api.github.com";
+  const headers = prApiHeaders(opts.token);
+  const shortSha = opts.headSha.slice(0, 12);
+
+  let statuses: readonly CommitStatus[];
+  try {
+    // NEWEST FIRST is GitHub's own order for this endpoint, and check ⑤ above depends on it: the
+    // first entry for a context is the one in force, which is what a reviewer's browser also shows.
+    const res = await fetchFn(`${apiBase}/repos/${opts.repo}/commits/${encodeURIComponent(opts.headSha)}/statuses?per_page=100`, {
+      method: "GET",
+      headers,
+    });
+    if (!res.ok) {
+      return { kind: "unavailable", reason: `the commit-status listing for ${opts.repo}@${shortSha} failed: ${res.status} ${await safeText(res)}` };
+    }
+    const body = (await res.json()) as unknown;
+    statuses = Array.isArray(body) ? (body as CommitStatus[]) : [];
+  } catch (err) {
+    return { kind: "unavailable", reason: `the commit-status listing could not be read: ${errText(err)}` };
+  }
+
+  const status = statuses.find((s) => s.context === CONFIG_DIFF_STATUS_CONTEXT);
+  if (!status) {
+    return {
+      kind: "unavailable",
+      reason:
+        `no \`${CONFIG_DIFF_STATUS_CONTEXT}\` commit status exists on head sha ${shortSha} (${statuses.length} status(es) there). ` +
+        `Either the cloud run that computes the resolved-config diff has not posted yet, or this deployment does not run one. ` +
+        `This is an UNKNOWN — the config facts for this pull request are NOT established.`,
+    };
+  }
+
+  const named = parseConfigDiffStatusDescription(status.description);
+  if (!named) {
+    return {
+      kind: "unavailable",
+      reason:
+        `the \`${CONFIG_DIFF_STATUS_CONTEXT}\` status on ${shortSha} names no sha256 digest in its description, so it vouches for no ` +
+        `particular document. Refusing to treat its existence as facts. This is an UNKNOWN, not a pass.`,
+    };
+  }
+
+  const documentUrl = typeof status.target_url === "string" ? status.target_url : "";
+  if (!isAllowedFactsDocumentUrl(documentUrl, opts.repo)) {
+    return {
+      kind: "unavailable",
+      reason:
+        `the \`${CONFIG_DIFF_STATUS_CONTEXT}\` status on ${shortSha} points its target_url at a location this tool will not fetch ` +
+        `(only api.github.com, raw.githubusercontent.com and github.com release downloads serving ${opts.repo} are read). This is an UNKNOWN.`,
+    };
+  }
+
+  let document: string;
+  try {
+    // THE TOKEN GOES TO THE API HOST ONLY. The other two allowed hosts serve public content and get
+    // an unauthenticated read, so a read credential is never offered to a host that does not need
+    // it. The digest check below is what makes an unauthenticated fetch safe.
+    const res = await fetchFn(documentUrl, {
+      method: "GET",
+      headers: documentUrl.startsWith(`${apiBase}/`) ? headers : { accept: "application/octet-stream" },
+    });
+    if (!res.ok) {
+      return { kind: "unavailable", reason: `the facts document at ${documentUrl} could not be fetched: ${res.status} ${await safeText(res)}` };
+    }
+    document = await res.text();
+  } catch (err) {
+    return { kind: "unavailable", reason: `the facts document at ${documentUrl} could not be fetched: ${errText(err)}` };
+  }
+
+  if (Buffer.byteLength(document, "utf8") > MAX_FACTS_DOCUMENT_BYTES) {
+    return { kind: "unavailable", reason: `the facts document at ${documentUrl} is over the ${MAX_FACTS_DOCUMENT_BYTES}-byte cap — refusing to read it` };
+  }
+
+  const actual = configFactsDigest(document);
+  if (actual !== named.digest) {
+    return {
+      kind: "unavailable",
+      reason:
+        `the document at ${documentUrl} hashes to sha256:${actual}, but the \`${CONFIG_DIFF_STATUS_CONTEXT}\` status on ${shortSha} ` +
+        `vouches for sha256:${named.digest}. The bytes are NOT the ones a principal vouched for, so they are refused. This is an UNKNOWN.`,
+    };
+  }
+
+  const parsed = parseConfigFacts(document);
+  if (!parsed.ok) {
+    return { kind: "unavailable", reason: `the vouched document at ${documentUrl} could not be read as a config-diff report: ${parsed.reason}` };
+  }
+
+  return {
+    kind: "cloud-status",
+    facts: parsed.facts,
+    provenance: {
+      repo: opts.repo,
+      headSha: opts.headSha,
+      statusContext: CONFIG_DIFF_STATUS_CONTEXT,
+      digest: named.digest,
+      documentUrl,
+      sessionId: named.sessionId,
+      postedAtIso: status.updated_at ?? status.created_at,
+      postedBy: status.creator?.login,
+    },
+  };
+}
+
+async function safeText(res: { text(): Promise<string> }): Promise<string> {
+  try {
+    return (await res.text()).slice(0, 300);
+  } catch {
+    return "(no body)";
+  }
+}
+
+function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}