docs: per-instance query limits book chapter - #846
Merged
QuantumExplorer merged 3 commits intoAug 31, 2026
Merged
Conversation
Adds the Per-Instance Query Limits chapter (semantics, min composition, budget-vs-traversal charges, the merge lift, proof behavior, the fail-closed table, and the version-3 wire encoding), links it from the Query System chapter, and refreshes the stale Query struct listings in the book and the grovedb crate doc (both predated read_mode). The add_parent_tree_on_subquery known-limitation note now points at the remaining prover/verifier charging work instead of promising the per-level redesign that has since shipped. Part 3 of 3. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
…nstance-limit-book
…nstance-limit-book
QuantumExplorer
merged commit Aug 31, 2026
8456217
into
claude/query-instance-limit-proofs
3 checks passed
QuantumExplorer
added a commit
that referenced
this pull request
Aug 31, 2026
Adds the Per-Instance Query Limits chapter (semantics, min composition, budget-vs-traversal charges, the merge lift, proof behavior, the fail-closed table, and the version-3 wire encoding), links it from the Query System chapter, and refreshes the stale Query struct listings in the book and the grovedb crate doc (both predated read_mode). The add_parent_tree_on_subquery known-limitation note now points at the remaining prover/verifier charging work instead of promising the per-level redesign that has since shipped. Part 3 of 3. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
QuantumExplorer
added a commit
that referenced
this pull request
Aug 31, 2026
…ugh merges (#845) * feat: serve per-instance query limits in V1 proofs and lift them through merges Teaches the V1 prover and verifier the per-instance limit accounting (Query::limit, introduced in #844), and makes PathQuery::merge lift merged inputs' global limits into per-instance caps. Proofs: the bare overall_limit/limit_left counters become a shared V1LimitState { global, consumed_rows, consumed_total } threaded through both walks, plus a frame-local instance budget per layer (min(inherited, the layer query's Query::limit), resolved through SinglePathSubquery::instance_limit). Each layer's merk walk runs under min(global, instance); rows charge every budget, descents settle the enclosing frame from the consumed_rows delta, and the empty-layer charge stays global-only. The consumed_total counter also replaces the old detect-consumption-by-diffing-the-Option trick, which went blind when the global limit was None. Non-Merk layers (MMR / BulkAppend / Dense / CommitmentTree) and the count-offset dispatch keep their helper signatures and are bounded through an effective-limit temp whose delta is absorbed back. Behavior for every query without per-instance limits is byte-for-byte unchanged; the V0 prover/verifier stay frozen and reject limit-carrying queries at dispatch, as do absence-proof assembly and pre-GROVE_V4 versions. The public verification wrappers run the version-aware gate before decoding the proof envelope, with the absence-mode blanket kept pre-decode as well. Merging (path_query_methods.merge = 2, GROVE_V4): an input's global SizedQuery::limit is lifted onto its merged branch's Query::limit — exact, because the branch instance executes exactly once — and authored per-instance limits ride along on their branches. Limits merge only as exclusive grafts: a limited input landing at the merged root, or two branches colliding on a key, are refused with typed errors; limit-free inputs keep the v1 merge behavior identically. prove_query_many therefore now serves limited path queries, and the verifier re-derives the same merged query at the same grove version. Deliberately NOT included: counting add_parent_tree_on_subquery rows against the limit (the M6 known limitation). Making the prover charge exactly where the verifier pushes needs a per-descent-arm audit (including the aggregate arms) that deserves its own change; the documented limitation stands. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: per-instance query limits book chapter (#846) Adds the Per-Instance Query Limits chapter (semantics, min composition, budget-vs-traversal charges, the merge lift, proof behavior, the fail-closed table, and the version-3 wire encoding), links it from the Query System chapter, and refreshes the stale Query struct listings in the book and the grovedb crate doc (both predated read_mode). The add_parent_tree_on_subquery known-limitation note now points at the remaining prover/verifier charging work instead of promising the per-level redesign that has since shipped. Part 3 of 3. Co-authored-by: Claude Fable 5 <noreply@anthropic.com> * refactor: move PathQuery::merge onto the versioned sub-file dispatch pattern The merge slot's behavior was branched inline throughout one function body (if merge_version >= 1 / < 2 / match merge_version), against the repo convention that version gates live in <op>/{mod.rs,v0.rs,...} sub-files with a match dispatcher. PathQuery::merge now keeps only the version-independent prelude (unknown-slot fail-closed validation, empty-input rejection, the read-mode refusal, the single-input shortcut) and dispatches to query/merge/{v0,v1,v2}.rs: - v0: frozen GROVE_V1..V3 behavior — directions silently dropped, all limits and offsets refused; - v1: direction agreement + propagation, limits still refused (kept as its own arm — unlike the folded path_query_push intermediate, the 0/1/2 numbering is spelled out in the version-table docs); - v2 (GROVE_V4): v1's direction rules plus the per-instance limit lift with its exclusive-graft refusals. Pure restructure — every version's behavior is byte-for-byte what the inline branches produced, pinned by the untouched merge test suite. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * refactor: fold the never-shipped merge intermediate into v1 Same reasoning as the path_query_push fold: the direction-agreement merge landed gated to GROVE_V4 as slot 1, V4 has not been released, and the per-instance lift took the V4 slot as 2 — leaving slot 1 a dead dispatch arm no version table selects. Since the slot values are internal until V4 ships, collapse: the direction rules + limit lift ARE merge v1 now, GROVE_V4 maps path_query_methods.merge back to 1, and the dispatcher (and its fail-closed validator) know [0, 1]. Table docs, tests, and the book chapter renumbered to match. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.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
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.
Part 3 of 3, stacked on #845 (which stacks on #844).
Query::limitmeans (per execution instance, "top k per parent"),mincomposition with ancestors and the globalSizedQuery::limit, root ≡ global, rows-vs-traversal-charge budget rules, offset interplay, the merge lift with its exclusive-graft refusals, proof behavior (out-of-band input, per-layermin(global, instance)enforcement), the fail-closed table, and the version-3 wire encoding.Querystruct listings inquery-system.mdanddocs/crates/grovedb.md— both predatedread_mode, let alonelimit.add_parent_tree_on_subqueryknown-limitation doc comment: the per-level redesign it promised has shipped; what remains is the symmetric prover/verifier charging for parent rows, now described as tracked follow-up work.🤖 Generated with Claude Code