BReg docs: the apply-time Evidence and target precondition guard has no configure coverage
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- Half a day
- Newbie friendliness
- 78/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- rust
- Domain
- documentation
Research direction
Start with docs/site/src/content/docs/configure/breg-change-control.mdx and compare its existing precondition coverage with the runtime references in crates/registry-breg/src/request_prepare.rs, change_request.rs, contract.rs, and action_evidence_contracts.rs. Use the issue's rg searches to verify the current gaps; done means the page documents application preconditions, manual-only behavior, ceilings, atLeast/atMost bounds, and the distinct failure contracts.
Written by the indexing model from the issue text.
Description
What
A change request can declare apply-time preconditions: changeRequest.application.preconditions with request[] predicates, targets[] guards and evidence[] requirements, evaluated at manual application rather than at submit or approval. None of it has a page on the documentation site. The configure/breg-change-control.mdx page documents action preconditions (target ETags on an invoke) and says nothing about the application block, so a reader who searches for "preconditions" finds the wrong feature and concludes the apply-time guard does not exist.
The atMost bound on an Evidence or predicate requirement is undocumented anywhere on the site, in either the change-request or the action-evidence form.
Evidence
- Runtime surface:
crates/registry-breg/src/request_prepare.rslines 320 to 442 walksplan.application.preconditions.request,.targetsand.evidenceand freezes them asFrozenApplicationPreconditions.crates/registry-breg/src/change_request.rsline 747 validates the block, line 96 emitschange_request.application.preconditions_manual_only, and line 773 emits the ceiling refusal "application preconditions exceed the finite target, Evidence, predicate, or byte ceiling". at_most(serializedatMost) is declared twice incrates/registry-breg/src/contract.rs, lines 599 and 659, and consumed incrates/registry-breg/src/action_evidence_contracts.rslines 150 to 166 andcrates/registry-breg/src/change_request.rslines 986, 1106 and 1159.- Docs coverage:
rg -i precondition docs/site/src/content/docs/configure/breg-change-control.mdxmatches only lines 281, 515 and 534, all about target ETags on actions and on request target admission.rg -i atmost docs/site/src/contentreturns nothing.
Proposed fix
Add a section to the change-control configure page for the application precondition block: the three kinds, the manual-application-only rule and its diagnostic, the finite ceilings, and the atLeast and atMost bounds on a requirement. Include the failure contract in the same place, distinguishing 412 precondition.failed (a guard no longer holds) from 503 action.evidence_failed (the Evidence check could not be completed), since the caller's recovery differs.
Found while
Extracting reusable App Kit skills against Registry Stack v0.32.0.
- Dominant language
- Rust
- Stars
- 2
- Forks
- 0
- Avg merge
- 3h 45m
- Merged PRs (30d)
- 134
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from registrystack/registry-stack
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
registrystack/registry-stack#1239 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
registrystack/registry-stack#1235 ·
-
area:breg bug good first issue rust
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
registrystack/registry-stack#1227 ·
-
area:casework documentation
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
registrystack/registry-stack#1217 ·
-
area:breg documentation
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
registrystack/registry-stack#1213 ·
All issues in registrystack/registry-stack
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Eynzof/Hermes-CN-Desktop#610 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
gitbutlerapp/gitbutler#15998 · 1 comment ·
-
bug triage:deciding
Difficulty 1/5 Under an hour Newbie friendliness 88/100
open-telemetry/otel-arrow#4132 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100