fix(proof): actually wire the per-repo opt-out the routes only claimed to honor (#9569)

Review caught the real defect: both handlers called
isProofPageEnabledForRepo(c.env) with no second argument, so the
ProofPageRepoOverride documented at length in proof-summary.ts and in the
PR body was never loaded or passed. Every repo was effectively
opt-out-less once the fleet flag was on -- a gate that is described,
typed, and unit-tested as a pure function, but never reachable from the
surface it governs. That is the registered-but-unreachable class, and the
long comment made it worse rather than better by making it look done.

- Adds a real `publicProof:` focus-manifest block (engine parser + toJson
  + loader snapshot), mirroring `publicStats:`/`ops:`. Precedence is
  deliberately the opposite of those two: read from the TARGET repo's
  manifest rather than the operator's self-repo, because the thing being
  opted out of is that repo's own page.
- loadProofPageRepoOverride resolves it, degrading a failed manifest load
  to "no override" -- a broken manifest never takes a page DOWN, which is
  the failure direction worth accepting here and is now stated in the
  doc comment rather than left implicit.
- Both routes load the override BEFORE anything else, so a repo that
  turned its page off does not have its decision records queried to build
  a summary that will be discarded.
- Documents the block in .loopover.yml.example, including the precedence
  and the opt-out default.

Tests that would have caught it: a repo opting out in its manifest now
gets 404 from BOTH routes with the fleet flag on, while a different repo
in the same fleet still serves 200 (the opt-out is per repo, not a kill
switch); explicit opt-in and no-block-at-all both serve; and the resolver
is covered across absent/explicit/failing loads.

Author: JSONbored

.loopover.yml.example

@@ -1493,3 +1493,17 @@ settings:
 #   # To stop trusting a peer, remove its key -- that is the whole revocation story, by design.
 #   peerKeys:
 #     - 0000000000000000000000000000000000000000000000000000000000000000
+
+# Public proof page (#9569) — the shareable, unauthenticated per-repo verification page
+# (`/proof/<owner>/<repo>`) and its README badge.
+#
+# OPT-OUT, not opt-in. Every figure the page renders is ALREADY publicly fetchable through the
+# ledger-verify, anchors and decision-record endpoints, so gating a page over data anyone can already
+# curl would add friction without adding privacy. This block exists because a page is nonetheless a
+# different artifact from an API: it is discoverable, linkable, and it markets this repo's numbers.
+#
+# Precedence: the operator's fleet-wide LOOPOVER_PUBLIC_PROOF flag must be on first. This block can turn
+# THIS repo's page OFF; it cannot turn one ON that the operator has not enabled. Omit the block entirely
+# to keep the page on once the operator enables it.
+# publicProof:
+#   enabled: false   # Bool. Default when the block is absent: true (opt-out).

packages/loopover-engine/src/focus-manifest.ts

@@ -440,6 +440,21 @@ export type FocusManifestPublicStatsConfig = {
   enabled: boolean;
 };
 
+/**
+ * Per-repo opt-OUT for the public proof page and its badge (#9569), declared under `publicProof:`.
+ *
+ * Shape matches `publicStats:`/`ops:`, but the PRECEDENCE is deliberately different: those are fleet-wide
+ * and read from the operator's self-repo manifest, whereas this is read from the TARGET repo's own manifest,
+ * because the thing being opted out of is that repo's own page. Not present ⇒ enabled, once the operator's
+ * LOOPOVER_PUBLIC_PROOF flag is on — opt-OUT, since every figure the page renders is already publicly
+ * fetchable through the ledger-verify / anchors / decision-record endpoints. A repo can turn its page off;
+ * it cannot turn one on that the operator has not enabled.
+ */
+export type FocusManifestPublicProofConfig = {
+  present: boolean;
+  enabled: boolean;
+};
+
 /**
  * Config-as-code override for the internal, bearer-gated contributor-trust-profile / fairness-analytics
  * surface (LOOPOVER_FAIRNESS_ANALYTICS, #fairness-analytics), declared under `fairnessAnalytics:`. Same
@@ -1249,6 +1264,7 @@ export type FocusManifest = {
   maintainerRecap: FocusManifestMaintainerRecapConfig;
   ops: FocusManifestOpsConfig;
   publicStats: FocusManifestPublicStatsConfig;
+  publicProof: FocusManifestPublicProofConfig;
   fairnessAnalytics: FocusManifestFairnessAnalyticsConfig;
   draftFlow: FocusManifestDraftFlowConfig;
   upstreamDriftIssues: FocusManifestUpstreamDriftIssuesConfig;
@@ -1413,6 +1429,13 @@ const EMPTY_PUBLIC_STATS_CONFIG: FocusManifestPublicStatsConfig = {
   enabled: false,
 };
 
+/** #9569: absent means ENABLED at the resolver (opt-out), so `enabled:false` here is only the shape's
+ *  default — `present:false` is what the resolver actually keys on. */
+const EMPTY_PUBLIC_PROOF_CONFIG: FocusManifestPublicProofConfig = {
+  present: false,
+  enabled: false,
+};
+
 const EMPTY_FAIRNESS_ANALYTICS_CONFIG: FocusManifestFairnessAnalyticsConfig = {
   present: false,
   enabled: false,
@@ -1478,6 +1501,7 @@ const EMPTY_MANIFEST: FocusManifest = {
   maintainerRecap: { ...EMPTY_MAINTAINER_RECAP_CONFIG },
   ops: { ...EMPTY_OPS_CONFIG },
   publicStats: { ...EMPTY_PUBLIC_STATS_CONFIG },
+  publicProof: { ...EMPTY_PUBLIC_PROOF_CONFIG },
   fairnessAnalytics: { ...EMPTY_FAIRNESS_ANALYTICS_CONFIG },
   draftFlow: { ...EMPTY_DRAFT_FLOW_CONFIG },
   upstreamDriftIssues: { ...EMPTY_UPSTREAM_DRIFT_ISSUES_CONFIG },
@@ -1520,6 +1544,7 @@ function emptyManifest(source: FocusManifestSource, warnings: string[] = []): Fo
     maintainerRecap: { ...EMPTY_MAINTAINER_RECAP_CONFIG },
     ops: { ...EMPTY_OPS_CONFIG },
     publicStats: { ...EMPTY_PUBLIC_STATS_CONFIG },
+    publicProof: { ...EMPTY_PUBLIC_PROOF_CONFIG },
     fairnessAnalytics: { ...EMPTY_FAIRNESS_ANALYTICS_CONFIG },
     draftFlow: { ...EMPTY_DRAFT_FLOW_CONFIG },
     upstreamDriftIssues: { ...EMPTY_UPSTREAM_DRIFT_ISSUES_CONFIG },
@@ -2356,6 +2381,24 @@ export function publicStatsConfigToJson(config: FocusManifestPublicStatsConfig):
   return { enabled: config.enabled };
 }
 
+/** Parse the optional `publicProof:` mapping (#9569). Mirrors {@link parsePublicStatsConfig} exactly. */
+function parsePublicProofConfig(value: JsonValue | undefined, warnings: string[]): FocusManifestPublicProofConfig {
+  if (value === undefined || value === null) return { ...EMPTY_PUBLIC_PROOF_CONFIG };
+  if (typeof value !== "object" || Array.isArray(value)) {
+    warnings.push('Manifest field "publicProof" must be a mapping; ignoring it.');
+    return { ...EMPTY_PUBLIC_PROOF_CONFIG };
+  }
+  const record = value as Record<string, JsonValue>;
+  const enabled = normalizeOptionalBoolean(record.enabled, "publicProof.enabled", warnings) ?? false;
+  return { present: true, enabled };
+}
+
+/** Serialize a publicProof config so a cached snapshot round-trips through {@link parsePublicProofConfig}. */
+export function publicProofConfigToJson(config: FocusManifestPublicProofConfig): JsonValue {
+  if (!config.present) return null;
+  return { enabled: config.enabled };
+}
+
 /** Parse the optional `fairnessAnalytics:` mapping (#fairness-analytics). Mirrors {@link parsePublicStatsConfig}
  *  exactly -- the only field is `enabled`, no DB layer to overlay onto. */
 function parseFairnessAnalyticsConfig(value: JsonValue | undefined, warnings: string[]): FocusManifestFairnessAnalyticsConfig {
@@ -4326,6 +4369,7 @@ export function parseFocusManifest(raw: unknown, source?: FocusManifestSource):
     maintainerRecap: parseMaintainerRecapConfig(record.maintainerRecap, warnings),
     ops: parseOpsConfig(record.ops, warnings),
     publicStats: parsePublicStatsConfig(record.publicStats, warnings),
+    publicProof: parsePublicProofConfig(record.publicProof, warnings),
     fairnessAnalytics: parseFairnessAnalyticsConfig(record.fairnessAnalytics, warnings),
     draftFlow: parseDraftFlowConfig(record.draftFlow, warnings),
     upstreamDriftIssues: parseUpstreamDriftIssuesConfig(record.upstreamDriftIssues, warnings),

src/api/routes.ts

@@ -306,7 +306,7 @@ 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 { isProofPageEnabledForRepo, loadProofPageRepoOverride, 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";
@@ -1357,8 +1357,11 @@ export function createApp() {
   // 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")}`;
+    // The repo's OWN opt-out, loaded before anything else is read: a repo that turned its page off must not
+    // have its decision records queried to build a summary that will be discarded.
+    const override = await loadProofPageRepoOverride(c.env, repoFullName, loadRepoFocusManifest);
+    if (!isProofPageEnabledForRepo(c.env, override)) return c.json({ error: "not_found" }, 404);
     try {
       const summary = await loadProofSummary(c.env, repoFullName, {
         verifyLedger: (env) => verifyDecisionLedger(env),
@@ -1376,12 +1379,14 @@ export function createApp() {
   // 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)) {
+    const badgeRepoFullName = `${c.req.param("owner")}/${c.req.param("repo")}`;
+    const badgeOverride = await loadProofPageRepoOverride(c.env, badgeRepoFullName, loadRepoFocusManifest);
+    if (!isProofPageEnabledForRepo(c.env, badgeOverride)) {
       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")}`, {
+      const summary = await loadProofSummary(c.env, badgeRepoFullName, {
         verifyLedger: (env) => verifyDecisionLedger(env),
         loadAnchors: (env) => loadPublicLedgerAnchors(env, { limit: 20 }),
       });

src/review/proof-summary.ts

@@ -217,6 +217,29 @@ export function buildProofBadgeColor(summary: ProofSummary): string {
 
 export type ProofPageRepoOverride = { present: boolean; enabled: boolean };
 
+/**
+ * Load ONE repo's `publicProof:` opt-out from its own focus manifest.
+ *
+ * Read from the TARGET repo's manifest, not the operator's self-repo, because the thing being opted out of
+ * is that repo's own page -- the opposite precedence from `publicStats:`/`ops:`, which are fleet-wide.
+ *
+ * A manifest load failure degrades to `{ present: false }`, i.e. exactly as if no override existed, so a
+ * network blip or malformed YAML can never accidentally EXPOSE a page the maintainer turned off... which is
+ * the wrong direction, and is why the caller must treat a failed load as the operator default rather than
+ * this function pretending to know. Documented here because the failure direction is the interesting part:
+ * we accept "a broken manifest leaves the page on" in exchange for "a broken manifest never takes a page
+ * down", matching how every other resolveX accessor in this codebase degrades.
+ */
+export async function loadProofPageRepoOverride(
+  env: Env,
+  repoFullName: string,
+  loadManifest: (env: Env, repoFullName: string) => Promise<{ publicProof: { present: boolean; enabled: boolean } } | null>,
+): Promise<ProofPageRepoOverride> {
+  const manifest = await loadManifest(env, repoFullName).catch(() => null);
+  if (!manifest?.publicProof?.present) return { present: false, enabled: false };
+  return { present: true, enabled: manifest.publicProof.enabled };
+}
+
 /** Fleet-wide operator flag -- truthy-string, default OFF, matching isPublicStatsEnabled's convention. */
 export function isPublicProofPageEnabled(env: { LOOPOVER_PUBLIC_PROOF?: string | undefined }): boolean {
   return /^(1|true|yes|on)$/i.test(env.LOOPOVER_PUBLIC_PROOF ?? "");

src/signals/focus-manifest-loader.ts

@@ -2,7 +2,7 @@ import { listSignalSnapshots, persistSignalSnapshot } from "../db/repositories";
 import { mapWithConcurrency } from "../queue/map-with-concurrency";
 import type { JsonValue } from "../types";
 import { nowIso } from "../utils/json";
-import { contentLaneConfigToJson, experimentalConfigToJson, featuresConfigToJson, gateConfigToJson, MAX_FOCUS_MANIFEST_BYTES, parseFocusManifest, parseFocusManifestContent, repoDocGenerationConfigToJson, reviewConfigToJson, reviewRecapConfigToJson, maintainerRecapConfigToJson, opsConfigToJson, publicStatsConfigToJson, fairnessAnalyticsConfigToJson, draftFlowConfigToJson, upstreamDriftIssuesConfigToJson, sweepWatchdogConfigToJson, prReconciliationConfigToJson, activeReviewReconciliationConfigToJson, loopEscalationConfigToJson, federatedIntelligenceConfigToJson, settingsOverrideToJson, type FocusManifest, type FocusManifestSource, type RepoReviewContext } from "./focus-manifest";
+import { contentLaneConfigToJson, experimentalConfigToJson, featuresConfigToJson, gateConfigToJson, MAX_FOCUS_MANIFEST_BYTES, parseFocusManifest, parseFocusManifestContent, repoDocGenerationConfigToJson, reviewConfigToJson, reviewRecapConfigToJson, maintainerRecapConfigToJson, opsConfigToJson, publicStatsConfigToJson, publicProofConfigToJson, fairnessAnalyticsConfigToJson, draftFlowConfigToJson, upstreamDriftIssuesConfigToJson, sweepWatchdogConfigToJson, prReconciliationConfigToJson, activeReviewReconciliationConfigToJson, loopEscalationConfigToJson, federatedIntelligenceConfigToJson, settingsOverrideToJson, type FocusManifest, type FocusManifestSource, type RepoReviewContext } from "./focus-manifest";
 import { LOOPOVER_REPO_FOCUS_MANIFEST_YAML, resolveLoopOverSelfRepoFullName } from "../config/loopover-repo-focus-manifest";
 import type { LocalManifestLoadResult } from "../selfhost/private-config";
 
@@ -337,6 +337,7 @@ function manifestToJson(manifest: FocusManifest): Record<string, JsonValue> {
     maintainerRecap: maintainerRecapConfigToJson(manifest.maintainerRecap),
     ops: opsConfigToJson(manifest.ops),
     publicStats: publicStatsConfigToJson(manifest.publicStats),
+    publicProof: publicProofConfigToJson(manifest.publicProof),
     fairnessAnalytics: fairnessAnalyticsConfigToJson(manifest.fairnessAnalytics),
     draftFlow: draftFlowConfigToJson(manifest.draftFlow),
     upstreamDriftIssues: upstreamDriftIssuesConfigToJson(manifest.upstreamDriftIssues),

src/signals/focus-manifest.ts

@@ -37,6 +37,7 @@ export {
   maintainerRecapConfigToJson,
   opsConfigToJson,
   publicStatsConfigToJson,
+  publicProofConfigToJson,
   fairnessAnalyticsConfigToJson,
   draftFlowConfigToJson,
   upstreamDriftIssuesConfigToJson,

test/unit/focus-manifest.test.ts

@@ -971,6 +971,7 @@ describe("compileFocusManifestPolicy", () => {
       maintainerRecap: { present: false, enabled: false, cadence: "weekly", channel: "discord" },
       ops: { present: false, enabled: false },
       publicStats: { present: false, enabled: false },
+    publicProof: { present: false, enabled: false },
       fairnessAnalytics: { present: false, enabled: false },
       draftFlow: { present: false, enabled: false },
       upstreamDriftIssues: { present: false, enabled: false },

test/unit/proof-summary.test.ts

@@ -18,6 +18,8 @@ import { createApp } from "../../src/api/routes";
 import { appendDecisionLedger, persistDecisionRecord } from "../../src/review/decision-record";
 import { loadPublicLedgerAnchors, recordLedgerAnchorAttempt } from "../../src/review/ledger-anchor-persistence";
 import { createTestEnv } from "../helpers/d1";
+import { loadProofPageRepoOverride } from "../../src/review/proof-summary";
+import { upsertRepoFocusManifest } from "../../src/signals/focus-manifest-loader";
 import type { PublicLedgerAnchor } from "../../src/review/ledger-anchor-persistence";
 
 // #9569: the public, shareable twin of the in-app trust panel. The properties that matter here are the ones
@@ -326,4 +328,41 @@ describe("loadProofSummary + routes (#9569)", () => {
     });
     expect(summary.anchor).toMatchObject({ state: "anchored", backend: "rekor", seq: 3 });
   });
-});
+
+  it("REGRESSION: a repo that opts OUT in its manifest gets 404 from BOTH routes, even with the fleet flag on", async () => {
+    // The defect this test exists for: both handlers called isProofPageEnabledForRepo(c.env) with no
+    // override, so the documented per-repo opt-out was never loaded and every repo was effectively
+    // opt-out-less once the operator flag was on.
+    const app = createApp();
+    const env = await seeded();
+    await upsertRepoFocusManifest(env, "o/r", { publicProof: { enabled: false } } as never);
+
+    expect((await app.request("/v1/public/repos/o/r/proof", {}, env)).status).toBe(404);
+    const badge = await app.request("/v1/public/repos/o/r/proof-badge.svg", {}, env);
+    expect(badge.status).toBe(404);
+    expect(await badge.text()).toContain("unavailable");
+
+    // A DIFFERENT repo in the same fleet is unaffected — the opt-out is per repo, not a kill switch.
+    expect((await app.request("/v1/public/repos/other/repo/proof", {}, env)).status).toBe(200);
+  });
+
+  it("an explicit manifest opt-IN serves, and so does a repo with no manifest block at all (opt-out default)", async () => {
+    const app = createApp();
+    const env = await seeded();
+    await upsertRepoFocusManifest(env, "o/r", { publicProof: { enabled: true } } as never);
+    expect((await app.request("/v1/public/repos/o/r/proof", {}, env)).status).toBe(200);
+    // No block at all: the page is on, because the data is already public and this is opt-OUT.
+    const bare = await seeded();
+    expect((await app.request("/v1/public/repos/o/r/proof", {}, bare)).status).toBe(200);
+  });
+
+  it("loadProofPageRepoOverride: absent block, explicit values, and a failing load all resolve honestly", async () => {
+    const env = createTestEnv();
+    expect(await loadProofPageRepoOverride(env, "o/r", async () => null)).toEqual({ present: false, enabled: false });
+    expect(await loadProofPageRepoOverride(env, "o/r", async () => ({ publicProof: { present: false, enabled: false } }))).toEqual({ present: false, enabled: false });
+    expect(await loadProofPageRepoOverride(env, "o/r", async () => ({ publicProof: { present: true, enabled: false } }))).toEqual({ present: true, enabled: false });
+    expect(await loadProofPageRepoOverride(env, "o/r", async () => ({ publicProof: { present: true, enabled: true } }))).toEqual({ present: true, enabled: true });
+    // A failing manifest load degrades to "no override" -- a broken manifest never takes a page DOWN.
+    expect(await loadProofPageRepoOverride(env, "o/r", async () => { throw new Error("network down"); })).toEqual({ present: false, enabled: false });
+  });
+});