Distinguish evidence sufficiency from final acceptance in retained review evidence

[samovers]

Implementation: PR #393, head f804beb626c7026f6d25373caa9c427c1c5fc25c. One documentation file, +74/-3. B1 documentation correction committed and pushed; mandatory package/architecture/temporal and whitespace checks passed. Bounded exact-head review closes B1 with zero remaining findings; current-head lightweight CI passed; no merge authorization.

Parent: #179. Discovered during PR #388 review 5192087845 (F1), separate from merged Delivery #387 / PR #388's observation acceptance eligibility change.

Delivery outcome and boundary

Document how an authorized caller of the existing legacy API reads the final commit result alongside evidence sufficiency. The concrete reader retains the result returned by /commit or /review/accept, then follows the existing authorized /records/{record_id} route.

Primary boundary: documentation of evidence-decision reporting across evidence sufficiency and the final commit outcome. Bounded discovery found that CommitIngressResult.problems/decisionOutcome, its promotionTraceRef, the trace's ordered gates and optional evidenceSufficiencyCaseRef already supply the needed information. No existing runtime reader was found converting case ALLOW into acceptance. The gap is the exact reading guidance and examples.

This Delivery is narrowed to one documentation file, docs/REVIEW_DISPUTE_SEMANTICS.md, plus local verification of existing behavior. It adds no runtime reader, state, record, backlink, endpoint, contract, permission or evidence rule. The former tracking text and original requirements are preserved in the local issue capture. This scope does not need or claim transfer of PR #388's semantic approval; any future new record/link/contract behavior still needs its own explicit scoped decision. Final exact-head merge authorization remains required.

Acceptance criteria

• Name the actual result/record reader and exact existing fields used to obtain the final outcome and full refusal reasons alongside evidence sufficiency.
• Demonstrate direct observation capture without a case, queued observation acceptance with an ALLOW case but later eligibility refusal, earlier evidence refusal, and a successful other-family control using fictional records and disposable databases.
• Explain that missing case does not imply evidence failure, case ALLOW does not imply acceptance, retained REQUIRE_REVIEW may include later routing reasons and does not alone imply missing evidence, RETAIN_DRAFT is not a complete claim disposition, and matching replay is not a fresh evidence evaluation.
• Preserve all runtime, contracts, immutable records, evidence-floor meaning, final decisions, replay, actor grants, O01–O07 and production closure. No runtime files change.

Completed bounded discovery and verification

All four examples were verified using existing fixtures, real legacy HTTP result/record reads and isolated PostgreSQL 17.10 databases on unmodified merged runtime 157e130dffb1f38ca4138e55075c5dde04778cc2. Initial run: 3 passed / 1 failed in3.31s. The temporary probe incorrectly expected REVIEW_PROMOTION to be the successful operation's final gate; the implementation correctly continues to materialization. Correcting that expectation and rerunning only the affected control gave 1 passed /3 deselected in1.23s. Each invocation reported the existing Starlette warning. Original failed evidence is preserved; no runtime changes or full-baseline claims.

The cases showed: direct observation has no case and final RETAIN_DRAFT/HIGH_CONSEQUENCE_BLOCKED; queued observation has ALLOW plus the same final refusal; wrong-kind evidence has no case and earlier EVIDENCE_INSUFFICIENT; queued operation has ALLOW plus PROMOTE_ACCEPTED and one review/consequence. Owned databases/container/tmpfs/credential were removed; unrelated services preserved. No audit restart.

Non-goals: new observation semantics, acceptance reopening, case rewriting, broader promotion matrix, new reporting API, reverse lookup without a concrete consumer, deployment or production activation.

Review B1 correctly identified that retained sufficiency-case outcomes may include later non-evidence review-routing reasons. The documentation now states that distinction and links the existing amendment source. The previous zero-Blocker review missed B1 and remains historical; the prior final packet is superseded. No runtime behavior changed and no new runtime tests were run for this prose correction. Bounded exact-head review closes B1 with zero Blockers, Follow-ups or Preferences; current-head lightweight CI 34951372642 succeeded. PR remains OPEN, non-draft, MERGEABLE/CLEAN at the corrected head and unchanged base. No close/reopen transition or newer formal review was observed.

Next: present the complete replacement PR #393 packet unmerged for later exact-head task-user authorization. Routine descriptive documentation needs no new semantic decision or full-baseline/publication cycle; no earlier implementation approval or evidence is transferred.