feat(breg): accept an optional reason on approve_request and apply_request

[jeremi]

Closes #1109.

What changes

A favourable decision had nowhere to put remarks: approve_request and apply_request refused a reason, so remarks could only be captured on rejection or return. Both actions now accept the same optional, bounded reason (≤ 4096 Unicode characters, NUL refused, empty string allowed) that reject_request and request_revision already accept. A body without reason stays valid, so nothing changes for callers that send none.

• Server (registry-breg): RequestActionBody::Approve/Apply carry reason: Option<String>, parsed by parse_reasoned_proposal_action. The approve reason is recorded on the decision entry exactly as a rejection's is. The apply reason is recorded on the application receipt (ApplicationReceipt gains reason/reason_present, registry_request_applications gains the columns) — apply is an execution step with no decision entry, and an application only ever exists for the current proposal version, so data.request.application is the complete read surface for it.
• Disclosure and retention parity: data.request.application carries reasonPresent always and reason under the same readableRequestFields: [reason] rule; anonymous profiles never see text. Request-detail erasure removes apply-reason text while keeping presence, and the retention report gains applicationReasons beside decisionReasons.
• Idempotency (issue point 3, unchanged rule): the reason joins the canonical action binding, so replaying under one key must repeat the same text; a changed reason is a conflict. Lifecycle webhook events carry reasonPresent/reason on approve and apply transitions — including an approve whose proposal applies in the same transaction (emitted on the terminal applied state).
• Client (registry-breg-client + Node/Python bindings): with_reason accepts approve and apply; recovery (recovery_action_body) replays a reasoned body verbatim; the retained/erased application decoders expose reason_present/reason. The byte-exact metadata gate now expects the reason property on all four action schemas the server publishes — same-release clients and servers stay in lockstep, and an older client refuses newer metadata (fail closed) rather than guessing.
• Casework: the BReg adapter forwards reasons on every promoted decision and apply instead of answering SourceAdapterError::ReasonUnsupported. The problem code stays registered for source adapters that do refuse reasons; its published row and products/casework/README.md no longer claim BReg refuses it.
• Generated artifacts: the four change-request OpenAPI baselines regenerated with their documented generators; check-generated.sh matches all nine baselines.
• Docs: breg-api.mdx action section, the Casework decision explanation, the review-breg-changes-in-casework tutorial (records a remark on the favourable decision), and the client READMEs.

Decisions on the issue's open questions

1. Apply in scope? Yes — implemented as proposed (title and numbered proposal both include it). It is recorded on the application receipt rather than a decision entry, since apply creates no decision; that is the smallest mechanism with the same disclosure and erasure semantics.
2. review.stages[].requireReason? Not added — optional covers the stated institutional need; required can follow a concrete ask.
3. Field name? Kept reason on the wire; the docs describe it as the approver's/applier's recorded remark, not only a refusal explanation.

Security-sensitive notes

This touches disclosure and data minimization: reason text on favourable decisions is guarded by the existing readableRequestFields profile rule (presence always, text only when permitted, never for anonymous profiles) and erased by operator_erase retention with presence retained — verified by new assertions for the hidden-profile and erasure paths. The DB CHECK constraints enforce the bounds and the reason/presence pairing in both tables. No new audit surface: the reason was already covered for reject/return; approve/apply reuse it.

Verification

• cargo fmt --check; cargo clippy --all-targets -D warnings for the changed crates; full-workspace cargo check --all-targets.
• cargo test for registry-breg, registry-breg-client, registry-casework-breg, plus registry-casework*, registry-bregctl — all pass.
• Real PostgreSQL (PostGIS, CI-pinned image): postgres_change_requests (including reworked reviewer-reason journeys: reasoned approve decision read-back, reasoned apply with disclosure/hidden/erasure checks and idempotent replay, event payloads), postgres_request_events, postgres_request_read_retention, postgres_request_upgrade_retention, postgres_request_receipts, postgres_mutation, postgres_webhook_outbox — all pass. The DB CHECK-constraint change is exercised by these suites (an in-place upgrade re-adds the constraint at startup).
• Node binding: npm ci && npm run build:debug && npm test && npm run check:types (33 pass). Python binding: extension-module build + 27 unittests pass.
• Product checks: products/breg/scripts/check-contracts.sh, check-client-contract.sh, check-generated.sh (9/9 baselines match), products/casework/scripts/check-checkpoint.sh.
• Docs site: npm run generate, npm test (601 pass), npm run check.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.