docs(book): explain the basic relations in an Akita fold - #340
Conversation
Adds the field-to-ring evaluation reduction chapter, rewrites the Stage-1 sumcheck-stages page (Stage 1 digit range check, Stage 2 fused relation, Stage 3 setup product), and links the new page from SUMMARY.md. Review fixes: hand terminal-fold anatomy to proving.md, repoint the opening- consistency link to field-ring-reduction.md, and pin all code references to a single snapshot. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
PR SummaryLow Risk Overview
Reviewed by Cursor Bugbot for commit f80c759. Bugbot is set up for automated code reviews on this repo. Configure here. |
|
Warning This PR has more than 500 changed lines and does not include a spec. Large features and architectural changes benefit from a short spec before implementation review. If this PR is a bug fix, small cleanup, or otherwise does not warrant a spec, feel free to ignore this message. |
Documentation blast radius (advisory)These regions may need doc/spec/book updates based on changed paths. Changed files in this PR: 4
|
Benchmark Report
Negative deltas are improvements for time, memory, and proof size. Terminal response component breakdown
The Detailed schedule and proof-size breakdowns by fold level are available in the uploaded |
CI test timing
Run summary
Wall time spans 2 parallel nextest slice shards. Slowest tests
Regressions vs mainNo per-test regressions above the threshold. New slow testsNo new tests ≥30s vs main baseline. |
f7ed
changed the title
…d' into freya/akita-book-relation-in-fold
…tion-in-fold # Conflicts: # book/src/SUMMARY.md # book/src/how/proving/field-ring-reduction.md # book/src/how/proving/sumcheck-stages.md
P1 — The documented four-row relation is no longer the production relation.The chapter says the current implementation has the four consistency | A | B | D families and presents B t̂ = u, D ê = v_D as direct public anchors (lines 11–19, lines 485–573). P1 — The canonical book contradicts an active security-sensitive spec.The chapter says EvaluationTrace is weighted by the shared τ₁ row challenge (lines 667–682), matching current code. P2 — Code references mix divergent, obsolete snapshots.field-ring-reduction.md and sumcheck-stages.md pin references to b104dae, while the new chapter pins eea8443. Both predate the current compressed implementation, and they are divergent snapshots—not one coherent protocol state. P3 — Documentation duplicates an existing canonical concept.The long balanced-digit/gadget derivation duplicates foundations/gadget-decomposition.md. This conflicts with the repository’s “one durable fact in one place” policy. Make the foundations page authoritative and keep only the fold-specific substitutions here. Additional gaps and cleanupThe extension-field evaluation section remains only a Status: stub, despite production support for extension-valued openings. |
quangvdao
left a comment
quangvdao
left a comment
There was a problem hiding this comment.
Freya, thank you for putting this together. This is a substantial and genuinely useful addition to the book. The four-equation derivation is clear, the distinction between the physical opening relation and EvaluationTrace is especially helpful, and the prose gives us a strong foundation to build on.
I am requesting changes because the chapter currently presents the raw B/D payload layout as the current physical protocol, while the shipped root and early recursive folds use commitment compression. The core derivation does not need to be discarded: I think the clean revision is to call the four equations the semantic source relations, then document the raw and compressed physical realizations separately.
Before merge, please:
- Add the production compressed layout: F/H row families, zero ordinary B/D right-hand sides, terminal p_F/p_H payloads, compression digits and quotients in WitnessLayout, and the planner-selected monotone compressed-to-raw cutover.
- Update the Stage 2 implementation map to distinguish ordinary relation weights from the separate compact compression and negative-binary evaluators. EvaluationTrace remains correct as the tau1-weighted virtual row after every physical row.
- Refresh the code map against the current implementation. In compressed mode the verifier reconstructs the RHS with assemble_compressed_relation_rhs, RingRelationInstance::v() is empty, and AkitaCommitmentHint stores semantic inner rows plus compression material rather than a stored t_hat.
- Bring the related documentation lifecycle into this foundational PR. Please fold the shipped content from commitment-compression-cutover.md and relation-range-image-sumcheck.md into the book and mark/archive those specs according to docs/documentation.md. y-ring-trace-internalization.md should be marked historical and archived, not treated as an implementation requirement: its gamma-squared design is stale, while the current tau1 EvaluationTrace implementation is authoritative.
- Update opening-points-layout.md so its witness-tail description includes compressed layers, alignment, and compression quotient rows.
A few precise locations to revise:
- akita-fold.md around the physical row table and equations 17–21: the stated count, RHS, and witness are the raw realization only.
- sumcheck-stages.md in the Stage 2 implementation map: compressed F/H rows precede EvaluationTrace and use the separate compression evaluator.
- akita-fold.md in the code-reference section: assemble_relation_rhs is the raw path; add assemble_compressed_relation_rhs and the terminal p_F/p_H flow.
This is a request to align a strong chapter with the shipped code, not a request to change the protocol. Once these points are addressed, I expect this to be a valuable and mergeable chapter.
|
Thank you for the detailed review. I'll revise this chapter accordingly. I want to confirm one organizational point about the commitment compression so that we are aligned. I have a follow-up PR 349 (#349) planned for the advanced relation layouts, covering multiple groups, multiple chunks, and mixed ring dimensions, and commitment compression, as extensions of the basic semantic relations introduced here. Given the commitment compression has been the production protocol rather than just a feature, I will reframe the four equations as semantic relations and document both of their physical realizations: raw and compressed. I'll then keep PR 349 focused on multiple groups, multiple chunks, and mixed ring dimensions extended these semantic relations. |
|
Sounds good, thanks! Where do you describe the evaluation trace relation btw? |
|
I finished it in PR 313 (#313), which had been merged. You can read it on page 2.5.1. sorry it's mixed with the sumcheck-stage page in the same PR. |
3 participants
Summary
Scope
This PR documents only the basic Akita-fold relation. Multi-group batching, multiple witness chunks, and mixed ring dimensions are intentionally deferred to a stacked follow-up PR for advanced relation layouts.
Testing
Dependency
This PR is stacked on #313 and therefore targets freya/akita-book. Once #313 merges, this PR can be retargeted to main.