test(runtime): map API-404 clauses to each control-plane profile's evidence

[doublewhy]

Summary

#1435, part of #8, asks for a map from API-404-C1 to C4 onto the P0, P1 and P2 implementation, conformance cases and operator guidance. It also asks that each property #8 lists be checked on every profile that guarantees it. The evidence already existed, but it was ordered by CP-9 obligation, not by clause. One binding was also not exercised on every profile: no case sent a request for another run through each composition, and no case rebound a selected P0 store to another run.

This PR adds an "API-404 clause verification" section to the runtime control-plane conformance page. It also adds a conformance module that covers the run binding and checks the map against profile_declaration(). The shared conformance witness now records evaluator starts as well as provisioning effects, so the run cases can see a backend effect. No runtime code changes, so no research evidence is republished.

The branch is based on dev 3512210 and holds two commits. 7713df5 adds the map, the cases and the witness change. 35daf6c adds the modules behind C3's revision-bearing reads to the map and tightens its citation and link checks. An earlier revision was stacked on #1431 only so that the C3 row could cite test_issue_1091_request_limit_boundary.py. That citation is gone, so this PR no longer depends on #1431. The two PRs touch different lines of docs/requirements/API-404/requirement.md.

Requirement UIDs

• API-404

Related Issues

Closes #1435

ADR Impact

• ADR-104: verification evidence for its P0/P1/P2 profile guarantees only. No ADR text changes.

Changes

• docs/research/runtime-control-plane/conformance.md: new "API-404 clause verification" section. Each clause row gives its profiles, landed implementation modules, conformance modules and operator guidance.
  • For C3's revision-bearing reads, the row cites control_plane_api/_operation_routes.py and control_plane_api_participant_retrieval.py. The first serves /snapshot and /apparatus/operational-summary with X-RAES-Snapshot-Revision (lines 327-366); the second sets the same header on participant retrieval views (line 112). API-404 traces them for "Revision-identifying snapshot and operational-summary reads" and "Revision-identifying participant view reads". The row also cites control_plane_api/_responses.py, which defines that header and maps a core conflict to the redacted 409 detail that the P2 run case observes.
  • The C1 row includes control_plane_execution.py, which API-404 traces for write-ahead claims and terminal commit routing. The C1 and C4 guidance links open the "Control-plane operating profiles" section of runtime-architecture.md.
  • A list follows that names the exact test behind each property Verify API-404 completion against control-plane profiles #8 lists on each profile that guarantees it: actor binding, target and run binding, atomic state and audit, retained idempotency, ownership, revision checks, and startup classification. It also says why a request for another run records no audit. Under the CP-9 preflight, an admission denial creates audit only. This refusal is not one: the CP-5 preflight requires it to fail before claim or disclosure, and operation_admission_context() refuses it before building the operation context that an admission-denial audit records.
• implementations/python/tests/control_plane_conformance_fixtures.py: witness_target now also installs WitnessEvaluator. It is a StubEvaluator that appends an evaluate event for the operation to the backend-effect witness on each start. Before this, an accepted evaluation left the witness empty. No other user of the fixture submits an evaluation, so their witness logs are unchanged.
• implementations/python/tests/test_issue_1435_profile_clause_verification.py (new, 7 cases, marked control_plane_conformance):
  • test_request_for_another_run_changes_nothing[P0, P1, P2]: through each reference composition (profile_harness), an evaluation plan for another run is refused. The P0 and P1 cores raise ValueError, and P2 returns 409 {"detail":"operation conflict"}. No operation record, audit, evaluator start or snapshot revision follows. The same plan for the admitted run is then accepted. The same reads then see one record, one terminal audit, one evaluate witness event for that operation, and revision 1.
  • test_selected_p0_store_cannot_be_rebound_to_another_run: a selected P0 store bound to one run refuses another run and still reopens for its own.
  • test_clause_map_binds_each_clause_to_its_declared_profiles: for each clause, it derives the available profiles whose declared guarantees include all of the clause's identifiers. The identifier sets are the docs(runtime): align API-404 with control-plane profiles #1185 module's COMMON_GUARANTEES, DURABLE_GUARANTEES and TRANSPORT_GUARANTEES. C4 names no identifier, so it binds every available profile, which leaves out P3. The derived sets must equal both the table rows and an expectation written independently of the requirement.
  • test_clause_map_cites_existing_code_and_tests: every entry of each row's Implementation and Conformance cells must be a citation the check's pattern reads, and every cited code path, test module and module::test function must exist.
  • test_clause_map_links_resolve: every link in the section must open an existing page, and a heading fragment must match a heading on that page under GitHub's anchor rule (without duplicate-heading suffixes).
• docs/requirements/API-404/requirement.md: DOCUMENTS and TESTS lines for test(runtime): map API-404 clauses to each control-plane profile's evidence #1435 and the new module. The conformance-page line now names the clause map.

Test Plan

• Unit tests pass
• Integration tests pass if applicable
• Full completion suite required in CI before merge
• No coverage regression

All runs below are on head 35daf6c.

pytest implementations/python/tests/test_issue_1435_profile_clause_verification.py passed (7 passed). With -m integration it selects nothing (7 deselected, exit 5).

The fixture change reaches every module that imports control_plane_conformance_fixtures or control_plane_crash_fixtures: the four test_issue_1187_control_plane_* modules for durable carriers, lifecycle properties, process loss and profiles. I ran them with this module, test_issue_1185_api_404_profile_alignment.py and test_issue_1189_control_plane_profile_declarations.py. The default lane gave 144 passed. With -m integration, the process-loss crash cases gave 37 passed. With -m "fuzz or docker", the two Hypothesis lifecycle cases gave 2 passed. No case needs Docker.

The effect leg fails without the fixture change. With control_plane_conformance_fixtures.py reset to its dev version, test_request_for_another_run_changes_nothing fails on P0, P1 and P2 with assert [] == [{'event': 'evaluate', ...}], because the old witness never sees the accepted evaluation. With the fixture restored, it passes.

The run and rebinding behavior already holds on dev 3512210, so there is no runtime fix to revert. Mutation runs show that each case group fails when its code path breaks. Each mutation ran on its own and was reverted:

• With the run-scope comparison in control_plane_operation_context.py disabled, the three run cases fail. A probe under the same mutation read 1 record, an evaluation_terminal audit, an evaluate witness event and revision 1 after the request for another run, on each profile. Without the mutation, the same probe read no record, audit or witness event, and revision 0. So every leg of the case can see the change, the effect leg included.
• With the scope comparison in InMemoryControlPlaneStore.bind_scope disabled, the P0 rebind case fails.
• Removing atomic-audit from P0's declared guarantees fails the declared-profile check, and so does marking P3 available. Binding C2 to P0 in the table fails it too, and so does adding P3 to the C1 row.
• Renaming a cited test fails the citation check. So does narrowing the citation pattern until it no longer reads control_plane_api/ paths, and so does emptying the C4 Implementation cell. The count-only assertion in 7713df5 passed both of those.
• Breaking a link's page fails the link check. So do a misspelled heading fragment, a fragment link whose page is missing, and a same-page link to a missing heading. A same-page link to the section's own heading passes. The link pattern in 7713df5 skipped every link with a fragment, so the misspelled fragment and the fragment link to a missing page both passed there.

The CP-9 selection the conformance page documents, pytest implementations/python/tests -m control_plane_conformance, passed: 889 passed, 2 skipped, 12170 deselected. It covers 22 modules, including the integration-marked process-loss cases and the fuzz-marked lifecycle cases. The two skips are macOS platform skips in test_issue_1092_control_plane_crash_consistency.py: "hard links are unavailable" and "symlink creation is unavailable". The two modules the clause table cites outside that selection, test_issue_1185_api_404_profile_alignment.py and test_issue_1189_control_plane_profile_declarations.py, gave 20 passed; with -m integration they select nothing.

nox -s verify-fast-feedback -- --base-rev origin/dev passed. Its changed-module stage ran this module (7 passed). nox -s lint passed. make policy passed; requirement governance is skipped there because the branch selects no UID. tools/check_requirement_governance.py --base-rev origin/dev --requirement-uid API-404 also exits 0. nox -s docs-local was not run: Vale reads docs/public and the root entry-point files, Sphinx builds docs/public, and this PR changes neither. The Docs workflow runs in CI. No package source changes, so package coverage cannot drop.

Ground Control Checks

• Repository policy command passes
• Each case group fails when the code path it covers is broken (mutation runs above), and the effect leg fails without the witness change
• Pre-push review completed; all findings fixed or dispositioned

Traceability

• IMPLEMENTS: (none); no package source change
• TESTS: API-404 ← implementations/python/tests/test_issue_1435_profile_clause_verification.py, implementations/python/tests/control_plane_conformance_fixtures.py (existing trace line)
• DOCUMENTS: API-404 ← docs/research/runtime-control-plane/conformance.md

Checklist

• Code follows the project coding standards
• FM: not applicable. There is no semantic change (documentation and characterization tests), and no executable or runtime adoption is claimed.
• No published contract schema or model changed, so nothing is regenerated
• PR title is a Conventional Commit; test(runtime) because nothing user-visible changes
• Architectural docs updated if applicable: the conformance page gains the clause map; ADR-104 is unchanged

Documentation

Updated: docs/research/runtime-control-plane/conformance.md ("API-404 clause verification").