BReg docs: the apply-time Evidence and target precondition guard has no configure coverage

Open Beginner friendly
#1,098 0 comments 0 reactions 0 assignees View on GitHub

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

area:breg area:docs area:evidence criticality:p3 documentation triage:needs-implementation

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.rs lines 320 to 442 walks plan.application.preconditions.request, .targets and .evidence and freezes them as FrozenApplicationPreconditions. crates/registry-breg/src/change_request.rs line 747 validates the block, line 96 emits change_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 (serialized atMost) is declared twice in crates/registry-breg/src/contract.rs, lines 599 and 659, and consumed in crates/registry-breg/src/action_evidence_contracts.rs lines 150 to 166 and crates/registry-breg/src/change_request.rs lines 986, 1106 and 1159.
  • Docs coverage: rg -i precondition docs/site/src/content/docs/configure/breg-change-control.mdx matches only lines 281, 515 and 534, all about target ETags on actions and on request target admission. rg -i atmost docs/site/src/content returns 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from registrystack/registry-stack

All issues in registrystack/registry-stack

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.