Explain evidence-floor and final outcomes in the legacy reader

[samovers]

Delivery: #389 (parent #179). Current head: f993a1af172c715f302b643bff091bd5439dbf7a.

Problem, capability and boundary

The existing legacy API exposes a final commit result, a promotion trace and an optional sufficiency case, but interpreting any one status alone can confuse evidence sufficiency with acceptance. The guide documents the existing authorized result → trace → case path and its limits.

Primary boundary: documentation of evidence-decision reporting. Only docs/REVIEW_DISPUTE_SEMANTICS.md changes: 93 additions / 3 deletions overall. The current B2/F1/P1 correction is +24/-5 from f804beb. No runtime, test, fixture, inventory, contract, record, authority, endpoint or workflow changes. Routine descriptive documentation requires no new semantic approval; no prior PR approval is transferred. Every merge still requires the later exact-head task-user authorization.

Final behavior described and acceptance criteria

• Read the stored result from GET payload, its final outcome and all problems, then its matching trace and optional case. A missing case alone does not establish evidence failure; ALLOW alone does not authorize acceptance.
• Routing reasons can originate in validation, soft floor checks or promotion. On direct operation/compliance floor paths, SATISFIED means no hard check failed and durable evidence exists; an operation may still have an unmet soft check.
• Read retained per-rule arguments with final problems. Routing preserves those arguments but rewrites outcome and first bundle status to PARTIAL. Neither REQUIRE_REVIEW nor PARTIAL alone identifies an evidence gap; supported arguments do not exclude a separate validation problem.
• Read reused reason codes with title/detail/severity and final outcome. Distinguish attempt outcome, current claim disposition and historical replay. No case-only reverse lookup is invented.
• Describe the existing FIELD-only scope read limitation; its runtime repair stays separate. Production routes remain closed.

The five table examples are fictional and match captured existing behavior. No missing endpoint or implemented reader converting ALLOW to acceptance was demonstrated; documentation is the smallest complete outcome. Non-goals: changing evidence policy, grants, case records, promotion eligibility, replay, currentness, production posture or restarting the audit.

Review handling

Review 5207958022 found B1. Review 5209450131 then found B2 in the first correction, plus F1 and P1. The prior zero-Blocker reviews missed those points and remain historical.

B2 is corrected with all three routing sources, the qualified SATISFIED meaning, preserved per-rule conclusions, and a measured missing-crop example. One suggested remedy was wrong: bundle status is rewritten by routing; the corrected guide explicitly says so. P1's reason-code qualification is included. F1's existing limitation is documented, but its read-resolution repair is outside this PR. A separate Delivery draft is prepared; creation of that issue awaits explicit publication approval. No remote issue is claimed and no runtime repair is authorized.

Current-head bounded correction review: B2 closed; zero Blockers, one unresolved outside-boundary Follow-up (F1), zero unresolved Preferences. Report SHA256 633edd4b56ccb8c629e1a97dc2b17306d719c732e15c4b9df8a4b51cc90243c5. The review independently verified the corrected source path, exact one-file scope, whitespace and all sixteen capture digests; no second runtime test run or full audit. Earlier packets for 5fedcc1 and f804beb are superseded. No PR #393 merge authorization exists.

Verification

• Mandatory package/architecture/temporal check: PASS, zero failures, before the current commit. Whitespace: PASS.
• Six focused local probes on unchanged runtime f804beb: 6 passed, 1 expected Starlette warning in 4.72s. Real legacy HTTP and fictional demo records covered three route sources, advisor acceptance of the distinct-reviewer claim versus missing-crop refusal without new evidence, advisory-code reuse and FIELD-only versus FARM+FIELD reads.
• CPython 3.12.13, psycopg 3.3.4, pytest 9.1.1 and pinned PostgreSQL 17.10. Existing dependencies were not reinstalled or hash-reauthenticated. Every probe had an isolated database in a task-owned disposable container; all owned DBs/container/credentials were removed, unrelated services preserved. No concurrency or production claim; FIELD-only observation was not repeated. Direct case lookup after a denied trace used explicitly test-only DB enumeration and is not advertised as an API traversal.
• Original four reader scenarios remain evidenced on unchanged merged runtime: initial 3 passed / 1 failed, from a bad temporary final-gate assertion; corrected only that assertion and reran the affected control: 1 passed / 3 deselected, one expected warning per run. Those failures and sources are preserved. The new six probes are separate evidence, not a relabeling of that run.
• Current-head lightweight CI 34965723376: SUCCESS. PR is OPEN, non-draft, MERGEABLE/CLEAN at the current head and unchanged base. No newer formal review or close/reopen transition was observed. Full hosted baseline/admission/publication/receipt: not required under root AGENTS.md for this routine documentation-only slice. Unadmitted executor skips are not baseline evidence. No workflow rerun. Earlier automatic review logs hide model verdicts and are not counted as content-review clearance.

Excellence

EXC-001: existing record owners remain authoritative. EXC-002: no duplicate state, validation or reader. EXC-003: corrected statements trace to existing source and focused captures. EXC-004: remove misleading after-gate-only wording. EXC-005: no abstraction added. EXC-006: a guide and existing fields suffice; no new record, reverse endpoint or kernel machinery.

Technical review handling is complete. F1 issue creation and the prepared Delivery #389 status update both await explicit publication approval after automatic review rejected those issue writes. The existing Delivery description therefore still names the previous head; the corrected code and current verification are recorded here. No rejected issue body is republished here.

Next: resolve the two issue-publication approvals, complete their readbacks, then present the replacement packet unmerged for later exact-head authorization.

[samovers]

PR #393 — Request changes

Reviewed head: 5fedcc16776dd47f93e399cf5297d46e8711dbf4.

Scope: docs/REVIEW_DISPUTE_SEMANTICS.md only, 69 additions / 3 deletions.

One P2 documentation-correctness Blocker (B1), detailed inline at lines 925–927. The new general instruction labels the retained case outcome as the evidence-floor evaluation, but the existing runtime can amend that outcome after the evidence gate to incorporate non-evidence review-routing requirements. This undermines the guide's intended distinction between evidence sufficiency and acceptance decisions.

The smallest correction is documentation-only: label the fields as the retained sufficiency-case outcome, and explain that routed cases may incorporate later review-routing reasons. Read that outcome alongside the evidence-gate outcome and the final result's problems. No change to case semantics, stored records, links, endpoints, or runtime behavior is needed.

Remaining assessment

The forward traversal, GET payload unwrapping, separation of exact problem codes from trace gate entries, and replay warning match the implementation. In particular, replay creates a new trace without carrying forward the original case link. No additional Blocker was found in those instructions.

Sources inspected at the reviewed head include the legacy record reader, the gates, the record and replay writers, and the sufficiency-case builders.

Validation limits: Source review of the diff, relevant runtime paths, and existing test code. Tests were not executed and the author's local probe captures were not inspected.

Disposition: Fix B1 within this documentation-only PR. No separate Follow-up or runtime redesign is warranted. This review is not merge authorization.

Submitted as a COMMENT review because GitHub does not permit the authenticated PR author to submit a formal REQUEST_CHANGES review. The review verdict above remains Request changes.

[samovers]

B1 — [P2 / Blocker] The retained case outcome is not always the evidence-floor evaluation

This instruction applies generally to records returned from /commit, but the retained outcome.decision and outcome.rationale can incorporate non-evidence review-routing requirements, not just the earlier evidence-floor evaluation.

Concrete counterexample: Submit an otherwise-valid routine operation with complete evidence, confirmAccept: true, and a distinct reviewer named in reviewerPartyRef. The evidence gate can build an ALLOW case and log SATISFIED. ReviewPromotionGate.run() then adds HUMAN_APPROVAL_REQUIRED because naming another reviewer in the submitter's body is not that reviewer's own review act.

That path calls emit_pending_assertion(amend_case_for_routing=True). Before persistence, PromotionEmitter._store_case() calls amend_case_for_routing(), which changes the retained case outcome to REQUIRE_REVIEW, replaces its rationale with the routing explanation, and sets attestationAllowed to false. This is visible in the existing promotion gate, case-storage path, and case-routing amendment.

Violated invariant: Reader guidance must accurately distinguish evidence sufficiency from acceptance/review-routing decisions. Labeling this retained outcome as the evidence-floor evaluation presents a review-act requirement under an evidence-floor label.

Smallest acceptable fix: Rename the label to “retained sufficiency-case outcome” and add a qualification such as:

For routed submissions, the retained case may incorporate review-routing reasons added after the evidence gate. Its REQUIRE_REVIEW outcome does not, by itself, establish that evidence was missing. Read it alongside the evidence-gate outcome and the final result's problems.

This is an in-scope documentation correction only. Do not change runtime behavior, case semantics, stored records, links, or endpoints to resolve it.

[samovers]

PR #393 review — legacy reader guide for evidence sufficiency vs final outcome

Head reviewed: f804beb626c7026f6d25373caa9c427c1c5fc25c (tree 66cc839334a38b2986f0eb027bd5d5c1ddcdf557)
Base: 157e130dffb1f38ca4138e55075c5dde04778cc2 (tree 5c2e197e522a316513931315a26f05c1c03cb91d)
Scope: docs/REVIEW_DISPUTE_SEMANTICS.md only, +74/−3 (blob 2002c7c3, file sha256 42b54626…a82fa45). The B1 correction commit 5fedcc1..f804beb is +7/−2.
Delivery: #389. Classification: root AGENTS.md "Review classifications" (Blocker / Follow-up / Preference). The PR has no review-classification section of its own.

Verdict: 1 Blocker, 1 Follow-up, 1 Preference. Not ready to merge at this head.

Where this pass sits

This is an independent third pass on the PR. Earlier passes:

• The author's sealed review at 5fedcc1: zero findings. The author has since said it missed B1.
• Review 5207958022 / inline 4013941567 at 5fedcc1: one Blocker (B1). Source-only; no tests run.
• The author's "bounded B1 correction review" at f804beb: B1 closed, zero findings. It checked the source chain only, with no runtime run.

I extracted the head myself, ran my own probes over the real legacy HTTP reader, and read the earlier reviews only after measuring. The new Blocker is in the B1 fix itself. The fix copied B1's suggested wording word for word. That wording rests on a premise that holds for one of the three places routing reasons come from, not all three.

Method

• Fresh git clone of samovers/OFARM2, refs/pull/393/head fetched into its own worktree. Head, tree, base and +74/−3 match the PR body.
• PostgreSQL 16.13 (initdb, socket /tmp/pgman:54317), CPython 3.12.3 venv with requirements-review-baseline.lock. The kernel Store does not enforce the 17.10 pin; only tenant provisioning does.
• One throwaway probe module, kernel/tests/test_zz_probe393.py, which I wrote myself. It uses only conftest.fresh_env, create_test_app and demo fixtures, not the author's probe. Every read goes through GET /records/{id} with x-acting-party, exactly as the guide tells a reader to. The module was never committed.
• Result: 4 passed (3.0 s + 1.2 s). The JSON captures are cited below.

Blocker B2 — "Read it alongside the evidence-gate outcome" cannot tell a routing requirement from an unmet floor item

Text at head (lines 928–931):

For routed submissions, the retained case may incorporate review-routing reasons added after the evidence gate. Its REQUIRE_REVIEW outcome alone does not establish that evidence was missing. Read it alongside the evidence-gate outcome and the final result's problems.

The table (line 944) teaches the same heuristic: "ALLOW; evidence gate logs SATISFIED" means "The evidence floor passed."

Violated invariant: #389's outcome and its first acceptance criterion. The guide must name "the exact existing fields used to obtain the final outcome … alongside evidence sufficiency". B1 applied the same invariant: reader guidance must not present a routing requirement as an evidence judgement. This is that invariant in reverse. The guide now points the reader to a field that presents an unmet evidence-floor item as a pass.

Mechanism (unchanged runtime, read at head):

1. review_route_reasons has three producers, not one:
   • before the evidence gate, in ValidationGate: validators.py:434 (event time outside the plausibility window, code EVIDENCE_INSUFFICIENT), :943, :1099 (ACTOR_BINDING_UNRESOLVED), :1178 / :1187 (product/crop binding), :1446;
   • inside the evidence gate: stages.py:542 ctx.review_route_reasons.extend(floor_failures), the policy's softItems ["product-binding", "crop-binding"];
   • after it, in ReviewPromotionGate: stages.py:659/676/687. This is the only producer B1 considered.
2. Whatever the floor case decided, unless it was REFUSE, the floor path logs ctx.log("EVIDENCE_SUFFICIENCY", "SATISFIED") with no rationale (stages.py:551). A case whose soft floor item is missing (decision == "REQUIRE_REVIEW", bundleStatus: PARTIAL) is logged as SATISFIED.
3. amend_case_for_routing (sufficiency.py) then overwrites outcome the same way for all three producers.

So a routed operation always shows evidence gate SATISFIED plus case REQUIRE_REVIEW, whether or not an evidence-floor item was missing. The two fields the guide names cannot tell these apart.

Measured (captures routed.json, sources.json). All three are /commit with confirmAccept: true by party:demo.farmer.one, current event time:

Attempt	Where the route came from	Evidence gate	Retained case	Final result problems
(a) body names reviewerPartyRef: advisor	after the gate (B1's example)	SATISFIED, no rationale	REQUIRE_REVIEW, all 6 arguments SUPPORTED, codes [ATTESTATION_AUTHORITY_MISSING]	HUMAN_APPROVAL_REQUIRED "Distinct reviewer requires own act"
(c) binding_refs=[PRODUCT_BINDING] (no crop binding)	validation and the gate's own soft floor	SATISFIED, no rationale	REQUIRE_REVIEW, crop-binding: REVIEW_REQUIRED, codes [MISSING_REQUIRED_EVIDENCE]	IDENTITY_UNRESOLVED "Crop binding missing"; IDENTITY_UNRESOLVED "Floor item requires review"
(f) event time 2999-01-01T00:00:00Z	before the gate	SATISFIED, no rationale	REQUIRE_REVIEW, all 6 SUPPORTED, codes [TIMESTAMP_INCOMPLETE]	EVIDENCE_INSUFFICIENT "Event time outside plausibility window"

The consequence is real, not a matter of wording. An advisor then calls POST /review/accept on the queued assertion with no reviewer evidence:

a_accept {'decision': 'PROMOTE_ACCEPTED', 'problems': [],
          'evidenceGate': [['SATISFIED', 'all SI evidence-floor items satisfied']], 'new_cases': 1}
c_accept {'decision': 'RETAIN_DRAFT',
          'problems': [['EVIDENCE_INSUFFICIENT', 'Acceptance floor unmet', 'ERROR']],
          'evidenceGate': [['INSUFFICIENT', "evidence floor unmet: missing ['route-reasons-resolved']; ..."]],
          'new_cases': 0}

For (c), evidence was missing. The claim cannot be accepted until a reviewer attaches new durable evidence (IDENTITY_UNRESOLVED ∈ NEEDS_EVIDENCE_CODES). Yet at commit time it showed the same evidence gate SATISFIED and the same case REQUIRE_REVIEW as (a), which an advisor accepts outright. A reader who follows the guide sees "the evidence gate passed, so this routing came in after it and does not mean missing evidence". For (c) and (f) that conclusion is wrong, and the text never says routes can arise before or inside the gate.

Calibration. The probe does detect a change in the gate outcome. With one throwaway edit to stages.py:551 (log SATISFIED_WITH_EXCEPTIONS when the case is not ALLOW), only (c) changed: SATISFIED → SATISFIED_WITH_EXCEPTIONS; (a), (b), (d) and (e) stayed SATISFIED. The file was restored afterwards (git status: only the probe untracked). So the gap the finding rests on is line 551 at the unchanged runtime. It is not a probe artifact.

High-risk fields.

• Entry point: the legacy development/conformance POST /commit → GET /records/{id} (kernel/legacy_m1/api.py:143, 282). Production governed routes stay closed.
• Actor: any farm-read principal following §8 (measured as farmer and advisor).
• Path: ValidationGate / EvidenceSufficiencyGate:542,551 → ReviewPromotionGate:719-728 → PromotionEmitter._store_case → amend_case_for_routing.
• Precondition: an operation claim with a missing soft floor item (crop or product binding) or a validation-time route. Both are ordinary pilot inputs.
• Consequence: the guide leads the reader to report "evidence floor passed" for a claim whose evidence floor is not met and which cannot be accepted without new evidence. That is the exact confusion #389 exists to remove.
• Reproduction: the (c) row above.

Smallest acceptable fix (documentation only; no runtime change):

1. Replace "added after the evidence gate" with wording that covers all three producers. For example: "may incorporate review-routing reasons raised during validation, by the evidence gate's soft floor items, or by review routing."
2. Say that on the operation/compliance floor path, evidence gate SATISFIED means only "no hard floor item was missing". It does not mean every floor item was supported, and it carries no rationale.
3. Name the fields that do separate the cases: the retained case's arguments[].conclusion (REVIEW_REQUIRED / UNSUPPORTED per ruleRef) and evidenceBundles[].bundleStatus. These are not rewritten by the routing amendment. Also name the result problems[] titles and codes.
4. Optionally add (c) as a fifth table row: "REQUIRE_REVIEW case; evidence gate SATISFIED; floor argument REVIEW_REQUIRED → a soft floor item is unmet; acceptance needs new reviewer evidence."

Counter-argument, stated fairly. The sentence says "may incorporate", which is literally true. It also tells the reader to read problems[], and in (c) the problem title "Floor item requires review" does reveal the gap. #389's acceptance criterion itself uses the narrow "later routing reasons" phrasing, so the PR meets that criterion as written. I still call this a Blocker for three reasons:

• The one field the guide names for evidence sufficiency, the evidence-gate outcome, is identical in the passing and failing cases.
• The causal explanation ("after the gate") is false for two of three producers.
• The criterion's own "name the exact fields … alongside evidence sufficiency" is not met, because the only fields that separate them (arguments[], bundleStatus) go unmentioned.

This is the same standard B1 was held to.

Follow-up F1 — the traversal's first step returns 403 to the farm owner when targetScopes has no FARM entry

The guide says: "A later authorized GET of that ID returns the stored result" (line 915), and "these reads retain their existing farm-read authorization checks" (line 910).

_read_farm_scopes (legacy_m1/api.py:227-256) looks for a FARM scope on the record. If there is none, it follows semanticEventRef and then requestId. The event envelope's anchorScopes is the caller's targetScopes verbatim (stages.py:228). The ingress request carries the same targetScopes. The contract requires targetScopes (minItems: 1, ten-value enum including FIELD). The repo's own tests submit FIELD-only scopes (test_correction_authorization.py:351).

Measured (misc.json):

scopes_field_only_op_selfreview    {'decision': 'PROMOTE_ACCEPTED', 'result': 403, 'trace': 403, 'case_direct_status': 200}
scopes_field_only_obs              {'decision': 'RETAIN_DRAFT',     'result': 403, 'trace': 403}
scopes_farm_and_field_op_selfreview{'decision': 'PROMOTE_ACCEPTED', 'result': 200, 'trace': 200, 'case': 200}

The farm owner, who holds a full grant, gets PERMISSION_REDACTED on her own result and trace. The case is readable, because its anchorScopes is hard-coded to FARM, but it cannot be reached without the trace. This is a failure to resolve the farm, not an authorization decision, so "existing farm-read authorization checks" does not describe it.

Why Follow-up, not Blocker. The defect is in the unchanged reader. It fails closed, disclosing nothing, and fixing it is runtime work outside this documentation boundary. If B2's fix is being made anyway, one sentence in §8 would be cheap and accurate: "the reader resolves the farm from FARM-typed scopes only; a submission whose targetScopes omits the FARM entry returns 403 for its result and trace." The runtime repair belongs in a separate Delivery.

Preference P1 — say that EVIDENCE_INSUFFICIENT in problems[] is not itself an evidence decision

Row 3 pairs EVIDENCE_INSUFFICIENT with "the evidence gate refused before promotion". The same code also appears as:

• a WARNING on a PROMOTE_ACCEPTED result with case ALLOW: dose 9999.0 gives ['EVIDENCE_INSUFFICIENT', 'Dose-range advisory', 'WARNING'] (routed.json (b); ERRATA E-006);
• the routing warning in (f) above.

§8 already says to read severities and titles. One clause ("reason codes are reused across advisories, routes and refusals; read severity and title with the code") would stop the table row being read as a lookup rule. This is optional.

Checked and decided were not findings

• Table rows 1–4 reproduce exactly with my own fixtures (table.json):
  • direct observation: 0 new cases, NOT_REQUIRED with its rationale, RETAIN_DRAFT + HIGH_CONSEQUENCE_BLOCKED;
  • queued observation: 1 case ALLOW, SATISFIED, same refusal, no emitted refs;
  • Party-as-evidence: no case, INSUFFICIENT, EVIDENCE_INSUFFICIENT/ERROR, and it is the last gate;
  • queued operation: 1 case ALLOW, PROMOTE_ACCEPTED, one review and one consequence, then CURRENT_STATE_MATERIALIZATION UPDATED.
• For all 200 reads, the stored result equals the returned body (storedEqualsReturned: True). The trace's requestId and finalOutcome match the result.
• Gate entries carry gate / outcome / optional rationale / relatedArtifactRefs, never reasonCode (stages.py:163-172). This is correct. (The DB gate log does store reason_code, but it is not reachable over HTTP.)
• Rejection: RETAIN_DRAFT, problems: [], evidence gate NOT_REQUIRED, no new case, one ReviewDecision with decisionOutcomeState: REJECTED. Matches.
• Replay (identical /commit body): REPLAY_REUSED_RESULT, a single INGRESS_NORMALIZATION gate, no evidenceSufficiencyCaseRef, emitted refs carried forward, replayOfRequestId equal to the first requestId. GET on that ID returns an ofarm.commitingressrequest.v0.1, not a result. Every replay sentence is accurate.
• "A case alone has no result/trace backlink": correct. The case only has subject.subjectRef = assertion.
• An unconfirmed operation gives case ALLOW + RETAIN_DRAFT with no problems. This is a third ALLOW-without-acceptance shape not in the table, but it is covered by "Neither case ALLOW nor attestationAllowed substitutes for acceptance."
• Read authorization: advisor reads result, trace and case (200). Worker and inspector get 403. A delegated worker can /commit (200) but gets 403 reading his own result. That is a real grant decision (artifact_family="OTHER") and is covered by line 910.
• Links: the anchor slug computes to 8-reading-retained-evidence-existing-legacy-behavior and matches. All four ../kernel/... targets and the rfcs/ links exist. §§3.5–3.6 exist. git diff --check: clean.
• Gates: no conformance checker or test reads this file. grep -rn REVIEW_DISPUTE_SEMANTICS conformance/ has zero hits, while the same grep finds docs/rfcs/ paths in temporal_contract_candidate_check.py, so the search is known to work. So the package/architecture/temporal checks cannot be moved by this diff. I did not rebuild CPython 3.12.13 to rerun them, and I rely on the author's PASS and CI run 34951372642 for that.

What I could not check

• PostgreSQL 17.10: I used 16.13. None of the paths above touch tenant provisioning or anything version-specific. The author's captures on 17.10 agree with mine on all four shared rows.
• Compliance-assertion routing (stages.py:659, self-review of a compliance claim): not run. Its route is added after the gate, so it behaves like (a).

What my method made easier than production

• demo fixtures grant farmer and advisor everything, so every read that should succeed does. A narrower real grant set would add more 403s of the F1 kind, not fewer.
• My probe knew in advance which producer each route came from. A real reader does not, and that is the point of B2.
• Every probe ran in one fresh database with no concurrent writers and no prior replays under the same key.

Posting note

samovers is the PR author, so GitHub will accept this only as a COMMENT review. It is not a formal REQUEST_CHANGES. Neither this review nor 5207958022 is an independent approval.