registrystack / registrystack/registry-stack

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
area:breg area:docs area:evidence documentation
Dominant language
Rust
Stars
2
Forks
0
Avg merge
2h 57m
Merged PRs (30d)
128

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.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.

Contributor guide

Open the contributing guide

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.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
Half a day
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.