feat(proof): public per-repo proof summary, endpoint and README badge (#9569)

The shareable, unauthenticated twin of the in-app trust panel. One
composition serves both, so the public page and #9193's panel cannot
disagree about a figure -- which is the property the page exists to
demonstrate.

THE PRIVACY BOUNDARY IS STRUCTURAL. Every field is built by NAMING it,
never by filtering a wider object. A blocklist has to anticipate every
field a future upstream type might grow and silently leaks the one it did
not; an allowlisted shape cannot leak a field nobody wrote down. Tested by
feeding hostile records carrying hotkey/wallet/reward/trust-score/private-
rank and asserting none of it reaches the serialized page -- while the
named fields do, so the test proves allowlisting rather than an empty
object.

NEVER A BARE SCALAR. Any accuracy figure carries its coverage and a Wilson
interval; below a 20-decision floor there is no rate at all, only an
explicit insufficient_data state that still publishes the count. A perfect
record over 19 decisions must not render as 100%. Wilson rather than Wald
because a gate metric lives near p->1, exactly where Wald claims
impossible certainty.

HONEST BOUNDARY STATES. An empty ledger is `empty`, not `verified` --
different claims. A failed read is `unavailable`, not `broken`, which
would accuse the operator of tampering. A FAILED anchor attempt is not an
anchor: the public attempt log is where failures are legible, and
presenting one here would claim corroboration that does not exist. The
verification-contract boundary statement travels IN the payload, so a
screenshot or embed cannot shed it the way a footer caption can.

The badge reports the LEDGER's state rather than an accuracy percentage: a
badge is a one-glance claim, and an accuracy number without the interval
that makes it honest does not fit in one. Disabled and errored both render
a neutral SVG -- a broken image in a README is worse than an honest
"unavailable".

DECISION (requirement 6), recorded beside the code that implements it: the
page is opt-OUT per repo, default ON once the operator's fleet-wide flag
(default OFF) is on. Every figure is already publicly fetchable through
the ledger-verify / anchors / decision-record endpoints, so gating a page
over it would add friction without privacy. The per-repo switch still
exists because a page is a different artifact from an API -- discoverable,
linkable, and it markets a repo's numbers whether or not the maintainer
wants that. A repo can opt out but cannot opt IN when the operator has
not, which keeps the fleet switch a real switch.

Found and fixed while testing: `DB.prepare()` throws SYNCHRONOUSLY on a
driver-level failure, so the `.catch()` chain never ran and a D1 outage
would have 503'd the whole public page instead of degrading. Each section
is now a real try/catch, which is the difference between the
fail-safe-per-section contract being documented and being true.

Backend half of #9569; the /proof/:owner/:repo UI route renders this
payload and lands separately.

Author: JSONbored

apps/loopover-ui/public/openapi.json

@@ -26252,6 +26252,82 @@
           }
         }
       }
+    },
+    "/v1/public/repos/{owner}/{repo}/proof": {
+      "get": {
+        "operationId": "getPublicRepoProof",
+        "tags": [
+          "Public"
+        ],
+        "summary": "Public proof summary for one repo — ledger status, anchor, calibration with coverage and interval, sample records",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "owner",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "repo",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ProofSummary. Any accuracy figure carries its coverage AND a Wilson confidence interval; below the sample floor it is an explicit `insufficient_data` state, never a bare percentage. Carries the verification-boundary statement in the payload"
+          },
+          "404": {
+            "description": "The proof page is disabled fleet-wide, or this repo has opted out"
+          },
+          "503": {
+            "description": "Composition failed — no partial or fabricated summary is served"
+          }
+        }
+      }
+    },
+    "/v1/public/repos/{owner}/{repo}/proof-badge.svg": {
+      "get": {
+        "operationId": "getPublicRepoProofBadge",
+        "tags": [
+          "Public"
+        ],
+        "summary": "README badge for the proof page — reports the ledger's state, never a bare accuracy percentage",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "owner",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "repo",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "SVG badge"
+          },
+          "404": {
+            "description": "Disabled or opted out — still an SVG (a neutral 'unavailable' badge), so a README never shows a broken image"
+          },
+          "503": {
+            "description": "Same neutral SVG on an internal error"
+          }
+        }
+      }
     }
   },
   "servers": [

src/api/proof-badge.ts

@@ -0,0 +1,39 @@
+// README badge for the public proof page (#9569). Renders through the SAME flat-badge primitive and the
+// SAME XML escaping as the repo-quality badge (`./badge.ts`), so an unauthenticated, embeddable surface
+// cannot become an injection vector and the two badges cannot drift apart visually.
+import { escapeXml } from "./badge";
+import { buildProofBadgeColor, buildProofBadgeMessage, type ProofSummary } from "../review/proof-summary";
+
+export const PROOF_BADGE_LABEL = "loopover proof";
+const UNAVAILABLE_COLOR = "#9e9e9e";
+
+/** `null` renders the neutral unavailable badge — used for both the flag-off 404 and the error 503, since
+ *  from a README's point of view those are the same thing: no claim is being made right now. */
+export function renderProofBadgeSvg(summary: ProofSummary | null): string {
+  const message = summary ? buildProofBadgeMessage(summary) : "unavailable";
+  const color = summary ? buildProofBadgeColor(summary) : UNAVAILABLE_COLOR;
+  return renderFlatBadge(PROOF_BADGE_LABEL, message, color);
+}
+
+function renderFlatBadge(label: string, message: string, color: string): string {
+  const labelText = escapeXml(label);
+  const messageText = escapeXml(message);
+  const labelWidth = textWidth(label);
+  const messageWidth = textWidth(message);
+  const totalWidth = labelWidth + messageWidth;
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="20" role="img" aria-label="${labelText}: ${messageText}">`,
+    `<title>${labelText}: ${messageText}</title>`,
+    `<rect width="${totalWidth}" height="20" rx="3" fill="#fff"/>`,
+    `<rect width="${labelWidth}" height="20" rx="3" fill="#24292f"/>`,
+    `<rect x="${labelWidth}" width="${messageWidth}" height="20" rx="3" fill="${escapeXml(color)}"/>`,
+    `<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">`,
+    `<text x="${labelWidth / 2}" y="14">${labelText}</text>`,
+    `<text x="${labelWidth + messageWidth / 2}" y="14">${messageText}</text>`,
+    `</g></svg>`,
+  ].join("");
+}
+
+function textWidth(text: string): number {
+  return Math.max(40, Math.round(text.length * 6.5) + 10);
+}

src/api/routes.ts

@@ -308,6 +308,8 @@ import { isRagEnabled } from "../review/rag-wire";
 import { loadDecisionLedgerTip, loadPublicDecisionRecord, loadPublicLedgerRow, verifyDecisionLedger } from "../review/decision-record";
 import { buildEvalScoreRecordsFromRulePrecision, filterEvalScoreRecords } from "../review/eval-score-records";
 import { anchorSigningInput, buildLedgerAnchorPayload, currentAnchorKey, parseAnchorPublicKeys, signLedgerAnchorPayload } from "../review/ledger-anchor";
+import { isProofPageEnabledForRepo, loadProofSummary } from "../review/proof-summary";
+import { renderProofBadgeSvg } from "./proof-badge";
 import { ingestBittensorAnchorReport, parseBittensorAnchorReport } from "../review/ledger-anchor-bittensor";
 import { loadPublicLedgerAnchors } from "../review/ledger-anchor-persistence";
 import { getPublicStats, isPublicStatsEnabled, resolvePublicStatsManifestOverride } from "../review/public-stats";
@@ -1352,6 +1354,47 @@ export function createApp() {
     return c.json(result);
   });
 
+  // #9569: the public proof page's data, and its README badge. Read-only over the SAME public sources the
+  // standalone endpoints already serve -- no new verification mechanism and no new SQL surface. Two gates
+  // must allow (see isProofPageEnabledForRepo's recorded opt-out decision): the operator's fleet-wide flag,
+  // default OFF like every sibling public surface, and the repo's own opt-out.
+  app.get("/v1/public/repos/:owner/:repo/proof", async (c) => {
+    if (!isProofPageEnabledForRepo(c.env)) return c.json({ error: "not_found" }, 404);
+    const repoFullName = `${c.req.param("owner")}/${c.req.param("repo")}`;
+    try {
+      const summary = await loadProofSummary(c.env, repoFullName, {
+        verifyLedger: (env) => verifyDecisionLedger(env),
+        loadAnchors: (env) => loadPublicLedgerAnchors(env, { limit: 20 }),
+      });
+      c.header("Cache-Control", "public, max-age=60, stale-while-revalidate=300");
+      return c.json(summary);
+    } catch {
+      return c.json({ error: "unavailable" }, 503);
+    }
+  });
+
+  // The badge deliberately reports the LEDGER's state rather than an accuracy percentage: a badge is a
+  // one-glance claim, and an accuracy number without the interval that makes it honest (which does not fit
+  // in a badge) is exactly the bare scalar the proof summary refuses to publish.
+  app.get("/v1/public/repos/:owner/:repo/proof-badge.svg", async (c) => {
+    c.header("Content-Type", "image/svg+xml; charset=utf-8");
+    if (!isProofPageEnabledForRepo(c.env)) {
+      c.header("Cache-Control", "public, max-age=300");
+      return c.body(renderProofBadgeSvg(null), 404);
+    }
+    try {
+      const summary = await loadProofSummary(c.env, `${c.req.param("owner")}/${c.req.param("repo")}`, {
+        verifyLedger: (env) => verifyDecisionLedger(env),
+        loadAnchors: (env) => loadPublicLedgerAnchors(env, { limit: 20 }),
+      });
+      c.header("Cache-Control", "public, max-age=600, stale-while-revalidate=86400");
+      return c.body(renderProofBadgeSvg(summary));
+    } catch {
+      c.header("Cache-Control", "public, max-age=300");
+      return c.body(renderProofBadgeSvg(null), 503);
+    }
+  });
+
   // #9277 (epic #9267): the current tip's SIGNED checkpoint, for the operator's off-Worker Bittensor
   // commitment submitter to fetch and commit on-chain (sha256 of `signingInput` is the exact 32 bytes
   // `Data::Sha256` holds). Unauthenticated like every /v1/public/* sibling: it is the same payload the

src/auth/route-auth.ts

@@ -48,6 +48,11 @@ export function requiresApiToken(path: string): boolean {
   if (path === "/v1/public/decision-ledger/anchor-key") return false;
   // #9271: the public anchor-attempt listing, added in the SAME PR as its route.
   if (path === "/v1/public/decision-ledger/anchors") return false;
+  // #9569: the public proof page's data and its README badge. Unauthenticated by design -- every figure
+  // they render is already served unauthenticated by the ledger-verify / anchors / decision-record routes
+  // above; this is a composition, not a new disclosure. Added in the SAME PR as the routes, per #9120.
+  if (/^\/v1\/public\/repos\/[^/]+\/[^/]+\/proof$/.test(path)) return false;
+  if (/^\/v1\/public\/repos\/[^/]+\/[^/]+\/proof-badge\.svg$/.test(path)) return false;
   // #9277: the current tip's signed checkpoint, for the operator's off-Worker Bittensor submitter (and
   // anyone else — it is the same payload the Rekor/git backends already publish externally). Added in the
   // SAME PR as its route, per the #9120 lesson.

src/env.d.ts

@@ -601,6 +601,10 @@ declare global {
      *  worker is byte-identical to today. Exposes review-disposition counts + a reversal-grounded accuracy
      *  percentage + an estimated-time-saved figure ONLY — never PR content, authors, scores, or reward internals.
      *  See review/public-stats.ts. */
+    /** #9569: fleet-wide switch for the public proof page (`/proof/:owner/:repo`) and its badge. Default
+     *  OFF like every sibling public surface. A repo can opt OUT via its own manifest, but cannot opt IN
+     *  when this is off -- see isProofPageEnabledForRepo's recorded decision in review/proof-summary.ts. */
+    LOOPOVER_PUBLIC_PROOF?: string;
     LOOPOVER_PUBLIC_STATS?: string;
     /** Proof of Power (#1059): comma-separated allowlist of repo full-names ("owner/repo") whose OWN historical
      *  review ledger (audit_events "published a review surface" + pull_requests terminal state) counts toward

src/openapi/spec.ts

@@ -1906,6 +1906,32 @@ export function buildOpenApiSpec() {
       200: { description: "{ anchors: [{ id, seq, rowHash, keyId, backend, backendRef, status, error, createdAt }], nextBefore } — a failed attempt is returned identically to a successful one, never filtered out or reshaped" },
     },
   });
+  registry.registerPath({
+    method: "get",
+    path: "/v1/public/repos/{owner}/{repo}/proof",
+    operationId: "getPublicRepoProof",
+    tags: ["Public"],
+    summary: "Public proof summary for one repo — ledger status, anchor, calibration with coverage and interval, sample records",
+    request: { params: z.object({ owner: z.string(), repo: z.string() }) },
+    responses: {
+      200: { description: "ProofSummary. Any accuracy figure carries its coverage AND a Wilson confidence interval; below the sample floor it is an explicit `insufficient_data` state, never a bare percentage. Carries the verification-boundary statement in the payload" },
+      404: { description: "The proof page is disabled fleet-wide, or this repo has opted out" },
+      503: { description: "Composition failed — no partial or fabricated summary is served" },
+    },
+  });
+  registry.registerPath({
+    method: "get",
+    path: "/v1/public/repos/{owner}/{repo}/proof-badge.svg",
+    operationId: "getPublicRepoProofBadge",
+    tags: ["Public"],
+    summary: "README badge for the proof page — reports the ledger's state, never a bare accuracy percentage",
+    request: { params: z.object({ owner: z.string(), repo: z.string() }) },
+    responses: {
+      200: { description: "SVG badge" },
+      404: { description: "Disabled or opted out — still an SVG (a neutral 'unavailable' badge), so a README never shows a broken image" },
+      503: { description: "Same neutral SVG on an internal error" },
+    },
+  });
   registry.registerPath({
     method: "get",
     path: "/v1/public/decision-ledger/anchor-payload",