Add proof source visualization atlas - #67
Open
Amaury Chamayou (achamayou) wants to merge 22 commits into
Open
Conversation
Add HashSourceT (abstract subtree-root resolver), TileHashSourceT (resolves from full tiles, with an LRU tile cache), ProofEngineT (inclusion/consistency proofs and their verifiers, built on mth_range), MemoryHashSourceT (resolves from a resident in-memory tree), and CombinedHashSourceT (memory first, falling back to tiles). Add the sole essential core change: TreeT::subtree_root(), a read-only, non-hashing accessor that lets proofs be served from the resident tree, plus the <limits> include it needs. No other merklecpp.h changes. Add tiles_proofs tests, cross-checking tile-derived inclusion and consistency proofs against merkle::TreeT as the oracle across a range of sizes, including tile-boundary crossings. Move the memory-only subtree_root proof coverage and the ProofEngineProbe hostile-arithmetic edge cases here from tree coverage, since they exercise the proof engine and core accessor rather than TiledTree lifecycle. Add tiles_level2 for end-to-end coverage of the level-2 tile path. Introduce the LONG_TESTS CMake option, gate tiles_level2 behind it, and enable it in CI (and CodeQL) so long-running tile coverage runs on pull requests. Document the compatibility statement, the optional core accessor, and the HashSource/ProofEngineT API and algorithms in the design doc. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Use the current default tree hash function for public proof aliases, reject index conversions that cannot be represented safely, and align the design and level-2 coverage notes with the rebased implementation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c504572c-322f-4950-8682-edf4a7fd2c5b
Co-authored-by: eddyashton <6000239+eddyashton@users.noreply.github.com>
Amaury Chamayou (achamayou)
marked this pull request as ready for review
August 6, 2026 20:52
Amaury Chamayou (achamayou)
changed the base branch from
achamayou/tiles-proofs
to
main
August 7, 2026 14:50
Copilot started reviewing on behalf of
Amaury Chamayou (achamayou)
August 7, 2026 15:23
View session
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a self-contained “proof visualization atlas” under tools/proof-viz/ that generates a strict data.json trace from real tile/memory proof resolution, and ships a static HTML/CSS/JS viewer as part of the documentation build artifact.
Changes:
- Introduces a C++ harness (
proof_viz.cpp) + scenario files to generate and validate traced inclusion/consistency proof resolution attempts. - Adds a static frontend (
index.html,styles.css,app.js) that renders the atlas (tile/frontier/computed nodes, routes, and resolver attempts) fromdata.json. - Extends the docs workflow to build and package the atlas into the Pages artifact, and links to it from the Sphinx docs landing page.
Reviewed changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/proof-viz/styles.css | Theme + layout styling for the atlas (light/dark, responsive, print). |
| tools/proof-viz/scenarios/tile-to-frontier.scenario | Defines an inclusion scenario crossing from tile-backed history to frontier. |
| tools/proof-viz/scenarios/next-frontier.scenario | Defines an inclusion scenario starting at the first post-tile frontier leaf. |
| tools/proof-viz/scenarios/near-boundary.scenario | Defines an inclusion scenario just before a tile completion boundary. |
| tools/proof-viz/scenarios/frontier-to-tile.scenario | Defines an inclusion scenario that needs a tile lookup late in the proof. |
| tools/proof-viz/scenarios/frontier-only.scenario | Defines an inclusion scenario entirely within the resident frontier. |
| tools/proof-viz/scenarios/consistency-tiled-history.scenario | Defines a consistency scenario fully satisfiable from tiled history. |
| tools/proof-viz/scenarios/consistency-frontier-pair.scenario | Defines a consistency scenario with both checkpoints beyond the first tile. |
| tools/proof-viz/scenarios/consistency-frontier-only.scenario | Defines a consistency scenario entirely before tiling begins. |
| tools/proof-viz/scenarios/consistency-boundary.scenario | Defines a consistency scenario spanning the flush boundary. |
| tools/proof-viz/scenarios/consistency-arbitrary-crossing.scenario | Defines a consistency scenario with an arbitrary A/B pair crossing tile/frontier. |
| tools/proof-viz/scenarios/boundary-overlap.scenario | Defines an inclusion scenario at the exact two-tile boundary (overlap case). |
| tools/proof-viz/proof_viz.cpp | Generates scenarios, traces HashSource::subtree_root attempts, verifies proofs, and writes the data.json contract. |
| tools/proof-viz/make_viz.sh | Builds the generator, produces data.json, validates JS + JSON shape, and copies site assets to output. |
| tools/proof-viz/index.html | Static page structure and controls for the atlas UI. |
| tools/proof-viz/app.js | Frontend renderer: loads data.json, builds node maps, draws canvases, and wires UI toggles/filters. |
| tools/proof-viz/.gitignore | Ignores generated data.json in the source directory. |
| doc/index.rst | Adds a docs entry linking to the generated proof-viz/ site. |
| .github/workflows/build-docs.yml | Runs on PRs and builds the proof visualization into doc/build/proof-viz before uploading the Pages artifact. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
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
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.
Summary
HashSource::subtree_root(level, index)attempts through transparent wrappers around the memory and tile sources;Tree::path(), verify arbitrary leaf-pair consistency proofs, and compare every traced proof with an unwrapped control;name: valuefiles loaded fromtools/proof-viz/scenarios/;data.jsoncontract and load it without executable globals;make_viz.sh.Base
This PR targets
maindirectly. The tile-backed proof APIs exercised by the atlas landed in #54; #55 remains separate.Build and view
Open http://localhost:4173/. CI calls the same script with
doc/build/proof-vizas its output directory.The generated site contains
index.html,styles.css,app.js, anddata.json. The JSON document hasschemaVersion,tileWidth, and a list of scenarios; each resolver attempt recordssource,level,index, andsuccess.Validation
tiles_proofstest passes;make_viz.shvalidates shell/JavaScript syntax, strict JSON structure, safe integer bounds, scenario fields, and resolver attempts;Documentation / Buildcheck passes and uploads agithub-pagesartifact containing all four atlas files; deployment is intentionally skipped for pull requests;data.jsonand build outputs remain ignored.