Skip to content

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

Description

@jeremi

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:bregBReg ownership.area:docsDocumentation site ownership.area:evidenceEvidence ownership.documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions