feat(proof): public per-repo proof summary, endpoint and README badge (#9569) - #9608
Merged
Conversation
…#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.
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
loopover-ui | 3f15c03 | Commit Preview URL Branch Preview URL |
Jul 29 2026, 06:56 AM |
Contributor
|
Important 🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨 ⏳ LoopOver is waiting…LoopOver has seen this pull request and is waiting on CI checks to finish before reviewing it. This comment will update once the review runs. 🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed · 🟨 Waiting |
Contributor
|
Superagent didn't find any vulnerabilities or security issues in this PR. |
Bundle ReportChanges will increase total bundle size by 3.88kB (0.05%) ⬆️. This is within the configured threshold ✅ Detailed changes
Affected Assets, Files, and Routes:view changes for bundle: loopover-uiAssets Changed:
|
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #9608 +/- ##
==========================================
- Coverage 90.27% 90.27% -0.01%
==========================================
Files 904 906 +2
Lines 113213 113284 +71
Branches 26859 26881 +22
==========================================
+ Hits 102202 102265 +63
- Misses 9680 9684 +4
- Partials 1331 1335 +4
Flags with carried forward coverage won't be shown. Click here to find out more.
|
…d 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.
…dflare Workers build The Workers build for loopover-ui has been failing on every PR since #9521 (merged as #9590) made src/openapi/schemas.ts import @loopover/contract/public-api: Cannot find module '.../node_modules/@loopover/contract/dist/public-api.js' imported from /opt/buildhome/repo/src/openapi/schemas.ts ui:build builds ui-kit and engine, then runs ui:openapi -- but never builds the contract package, so the import resolves to a dist/ that does not exist. CI did not catch it because the GitHub workflow has its own separate "Build contract package" step (ci.yml:361) before the drift checks; the Cloudflare build runs npm run build:cloudflare -> ui:build directly and gets no such step. The two paths had silently diverged. Add @loopover/contract to the same turbo invocation that already builds the engine, so the one script both paths share produces everything ui:openapi imports. Reproduced locally by deleting packages/loopover-contract/dist and running ui:openapi (identical ERR_MODULE_NOT_FOUND), then confirmed the fixed chain builds the package and writes the spec with no drift.
…ync the example template Two failures from the #9569 manifest block, both mine. 1. The unknown-top-level-field validator never learned about `publicProof`, so every manifest carrying it warned "Manifest contains unknown top-level field: publicProof." That was invisible on the first pass and appeared on every LATER one, because the first pass parses a manifest with no such key while later passes reload the persisted snapshot -- which my loader change now serializes the field into. The warning lands in the published review comment, so an unchanged PR got a fresh comment PATCH on every regate sweep: exactly the #3379 churn that test exists to prevent, reintroduced by a field the writer knew about and the reader did not. Found by instrumenting the test's PATCH interception to diff the two comment bodies rather than guessing at the cause; the added line named itself. 2. config/examples/loopover.full.yml must mirror .loopover.yml.example from "WHERE IT LIVES" onward, and I documented the block in only one of the two. Verified against origin/main first to confirm both were regressions from this branch rather than pre-existing.
…ow the gap exposed Codecov flagged 8 uncovered changed lines across focus-manifest.ts and routes.ts. I had measured coverage on proof-summary.ts and proof-badge.ts only, and never on the two files the manifest block and the routes actually touched -- so the gap was in my own verification, not just the tests. Closing it turned up a real defect rather than only missing assertions: loadProofPageRepoOverride used `.catch()` on the injected manifest loader, so a loader throwing SYNCHRONOUSLY (a driver-level failure before it ever returns a promise) skipped the handler entirely and would have escaped to the route -- 503ing a public page over a manifest read that is supposed to be optional. That is the same defect this file already had in loadProofSummary's section reads, which I fixed there and then reintroduced here. Now a real try/catch, with a regression test using a synchronously-throwing loader. Coverage: - parsePublicProofConfig / publicProofConfigToJson: explicit on/off, a present-but-empty block (present-but-false, which the resolver keys on), absence, three non-mapping shapes warning rather than throwing, and a snapshot round-trip. - A regression test asserting publicProof is a KNOWN top-level field, so the writer/reader split behind the #3379 regate churn cannot return. - The two route 503 arms are unreachable today (every inner read is individually fail-safe), so they are excluded with the house v8 pragma and a note on why they are kept: a future unguarded read should degrade to 503 rather than 500 on an unauthenticated public route. The badge arm uses ignore start/stop -- `next 2` miscounts across a multi-line comment and left the return uncovered. All three changed files now report zero uncovered changed lines.
…e unreachable arms Replaces the coverage pragmas with the fix they were papering over. The gate, the read and the outcome now live in ONE resolver (resolveProofPage) that both handlers render. That is not tidiness: the gate previously lived inline in both route bodies and exactly one of them was wired to the per-repo opt-out, which is the defect review caught. A shared resolver makes "the page and the badge agree about whether this repo is published" true by construction instead of by two call sites remembering the same thing. With that in place the two 503 arms were provably unreachable, because loadProofSummary is TOTAL -- every read is wrapped per section, so a failing ledger/anchor/record read degrades to that section's honest neutral state and the page still composes. Rather than excluding dead branches from coverage, the outcome is gone from the type: ProofPageResult is `ok | disabled`. A test asserts the totality directly -- every dependency failing at once, including a DB binding that throws on property access, still resolves to a rendered page in its neutral states. Same treatment for buildProofAccuracy's `!interval` guard: wilsonInterval returns null exactly when there are no trials, which IS the nothing-decided case, so one reachable guard covers both reasons a rate is unpublishable instead of a dead branch behind a pragma. Net: no `v8 ignore` pragmas anywhere in the #9569 code, and zero uncovered changed lines or branches across proof-summary.ts, routes.ts and focus-manifest.ts.
One import conflict in src/api/routes.ts: main widened the ledger-anchor import with `publicAnchorStatus` (#9755's empty-anchor-list reason) while this branch added the proof-summary and proof-badge imports beside it. Both sides kept -- neither change displaces the other, and `publicAnchorStatus` is used at routes.ts:1362 on main's side of the merge. Verified after resolving rather than assuming a clean textual merge means a clean semantic one: regenerated the OpenAPI spec (no drift), and ran both sides' suites -- proof-summary, ledger-anchor-persistence, the route/spec ratchet and auth -- 98 passing. docs-drift, engine-parity and dead-source-files all clean.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The shareable, unauthenticated twin of the in-app trust panel. One composition serves both, so the public page and #9193's panel can't disagree about a figure — which is precisely the property this page exists to demonstrate.
The privacy boundary is structural, not a filter
Every field is built by naming it, never by spreading a wider object. A blocklist has to anticipate every field a future upstream type might grow, and silently leaks the one it didn't; an allowlisted shape can't leak a field nobody wrote down. Tested by feeding hostile records carrying
hotkey/walletAddress/rewardTao/trustScore/privateRankand asserting none of it reaches the serialized page — while the named fields do come through, 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 — an explicit
insufficient_datastate that still publishes the count, because "we have 7 decisions, too few to claim a rate" is more honest than hiding both. 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, notverified— different claims. A failed read isunavailable, notbroken, 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 doesn't exist. The verification-contract boundary statement travels in the payload, so a screenshot or embed can't shed it the way a footer caption can.The badge reports the ledger's state, not an accuracy percentage — a badge is a one-glance claim, and an accuracy number without the interval that makes it honest doesn't fit in one. Disabled and errored both render a neutral SVG, because a broken image in a README is worse than an honest "unavailable".
The opt-out decision (requirement 6)
Recorded in the module beside the code that implements it, not only here:
Opt-out per repo, default ON once the operator's fleet-wide flag (default OFF) is on. Every figure is already publicly fetchable through
/v1/public/decision-ledger/verify,/…/anchorsand/…/decision-records/…— gating a page over data anyone can already curl adds friction without privacy, and makes a verification story look less confident than it is. The per-repo switch still exists because a page is a genuinely different artifact from an API: discoverable, linkable, indexable, 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 hasn't, which keeps the fleet switch a real switch.A real bug the tests caught
DB.prepare()throws synchronously on a driver-level failure, so my.catch()chain never ran — a D1 outage would have 503'd the entire public page instead of degrading section by section. Each section is now a realtry/catch. That's the difference between the fail-safe-per-section contract being documented and being true, and there's a test that breaksprepareoutright plus one for a driver returning noresultsarray.Tests (19, 100% of branches on both new modules)
Accuracy with coverage+interval and the floor in both directions; failed-attempt-is-not-an-anchor and newest-wins regardless of list order; all four ledger states including the unknown-position break; the privacy-boundary regression; sample bounding and the in-payload caveat; every badge message and color including the neutral not-yet-decided case; the flag's truthy parsing and the full opt-out matrix; end-to-end route 404-while-off / 200-when-on with cache headers; per-section degradation; and a real recorded anchor flowing through to
anchored.Auth exemptions and OpenAPI operations are added in this PR alongside the routes, per the #9120 lesson.
Backend half of #9569 — the
/proof/:owner/:repoUI route renders this payload and lands separately, so I've left the issue open.