refactor: make ADR32 M2 evidence/receipt parity opt-in

The M2 fold commit (2763a1c) ran the legacy-vs-typed parity comparison on the
default production path: build_run_evidence_bundle_from_events assembled both the
folded and legacy bundles plus two to_dict() serializations every call, and
build_run_receipt rendered the receipt twice for a shadow gate. That doubled
evidence work on the hot path and let a mismatch silently revert the M6 typed
source-of-truth cutover.

Make parity diagnostics opt-in without weakening the guarantee:
- build_run_evidence_bundle_from_events(..., verify_parity=False) folds once by
  default; parity/gap comparison only when verify_parity=True;
- build_run_receipt(..., shadow_parity=False) renders once by default; the
  receipt_event_derived_mismatch shadow warning only when shadow_parity=True;
- ADR32-M2 parity tests now pass the flags explicitly so the guarantee still
  holds where it belongs (tests, not runtime);
- add a regression guard asserting the default fold assembles once and
  verify_parity adds exactly one more assembly.

Action: G-P2-8
Roadmap-Status: unchanged
Constraint: behavior-preserving refactor of ADR32-M2 fold; default evidence/receipt output unchanged; parity still proven in tests; no fixture retirement; no roadmap holds touched
Tested: ruff format/check; mypy teaagent/run_evidence.py teaagent/run_receipt.py teaagent/runner/ --explicit-package-bases; pytest across evidence/receipt/model-route/goal-record/skill-activation/event-stream/conversation-ux/five-minute-proof/adversarial/evidence-completeness (150 passed); scripts/validate_wiring.py; scripts/validate_docs_consistency.py (29/29 risk, 21/21 ticket); docs-inventory --check
Not-tested: full acceptance/nightly suite, live/paid providers
Confidence: high

Author: johnteee

.omo/plans/adr-0032-m2-t003-work-order.md

@@ -11,10 +11,12 @@ Switch `build_run_receipt()` to consume event-derived evidence (via `build_run_e
 Synthetic fixtures that construct receipt test data from hardcoded audit event dicts mask real-path gaps. Once the event stream can produce byte-equivalent evidence, those fixtures become liabilities — they test a path that no longer matches production. M2-T003 eliminates this gap.
 
 **2026-07-22 execution note:** the safe local implementation added
-`build_run_receipt(..., use_event_stream=True|False)`, receipt parity coverage,
-and a best-effort `receipt_event_derived_mismatch` audit warning when the
-event-derived receipt diverges from the legacy receipt. The synthetic-fixture
-retirement remains Human Review work; no fixture was deleted by the agent.
+`build_run_receipt(..., use_event_stream=True|False, shadow_parity=False)` and
+receipt parity coverage. The `receipt_event_derived_mismatch` audit warning and
+the legacy shadow rendering are gated behind the opt-in `shadow_parity` flag so
+the default receipt path renders once (FR-02 called the shallow gate temporary;
+it is off by default rather than always-on). The synthetic-fixture retirement
+remains Human Review work; no fixture was deleted by the agent.
 
 ## 3. Scope
 

teaagent/run_evidence.py

@@ -946,16 +946,22 @@ def build_run_evidence_bundle_from_events(
     raw_audit_events: list[JsonMapping],
     *,
     goal_id: str = '',
+    verify_parity: bool = False,
 ) -> EventDerivedEvidenceResult:
-    """Build evidence from typed RunEvents, preserving raw-audit parity.
-
-    If typed folding ever diverges from the legacy raw-audit assembly, return
-    the legacy bundle and record the missing/raw categories. This preserves
-    receipt correctness while making the gap explicit for ADR32-M2 review.
+    """Build evidence from typed RunEvents.
+
+    By default this folds the typed stream once (the production path). When
+    ``verify_parity`` is True it additionally assembles the legacy raw-audit
+    bundle and, if the two diverge, returns the legacy bundle plus the gap
+    categories. The parity path is opt-in because the default runtime must not
+    pay for a second full assembly and two ``to_dict`` serializations on every
+    call; parity is asserted by the ADR32-M2 tests, not the hot path.
     """
     folded = build_evidence_from_events(
         events, root=root, run_id=run_id, goal_id=goal_id
     )
+    if not verify_parity:
+        return EventDerivedEvidenceResult(bundle=folded)
     legacy = _assemble_evidence_bundle(
         raw_audit_events, root=root, run_id=run_id, goal_id=goal_id
     )

teaagent/run_receipt.py

@@ -374,8 +374,15 @@ def build_run_receipt(
     *,
     budget_cap_cents: int | None = None,
     use_event_stream: bool = True,
+    shadow_parity: bool = False,
 ) -> str:
-    """Build a formatted run receipt for *run_id*."""
+    """Build a formatted run receipt for *run_id*.
+
+    ``shadow_parity`` is an opt-in ADR32-M2 diagnostic: when enabled alongside
+    ``use_event_stream`` it also renders the legacy receipt and records a
+    ``receipt_event_derived_mismatch`` audit warning on divergence. It is off by
+    default so the production receipt path renders once instead of twice.
+    """
     try:
         events = store.show_run(run_id)
     except FileNotFoundError:
@@ -396,7 +403,7 @@ def build_run_receipt(
         raw_audit_events=events,
     )
     receipt = format_run_receipt(summary, context, bundle=bundle, events=events)
-    if use_event_stream:
+    if use_event_stream and shadow_parity:
         legacy_bundle = build_run_evidence_bundle(
             root,
             run_id,

tests/test_run_evidence.py

@@ -343,12 +343,70 @@ def _assert_fold_matches_legacy(events: list[dict], run_id: str) -> RunEvidenceB
             run_id,
             typed,
             events,
+            verify_parity=True,
         )
         assert result.gap_categories == []
         assert result.bundle.to_dict() == legacy.to_dict()
     return legacy
 
 
+def test_from_events_parity_adds_exactly_one_assembly() -> None:
+    """The default fold does one assembly; verify_parity adds exactly one more.
+
+    Regression guard for the ADR32-M2 receipt/evidence fold. The typed fold
+    (``build_evidence_from_events``) legitimately calls ``_assemble_evidence_bundle``
+    once as its shared projection step. The parity comparison must be opt-in: the
+    default hot path must NOT assemble the legacy bundle a second time (the earlier
+    implementation did, doubling evidence work on every production call).
+    """
+    import teaagent.run_evidence as run_evidence
+
+    events = [
+        {
+            'event_type': 'run_started',
+            'run_id': 'r-once',
+            'payload': {},
+            'created_at': '2026-06-13T10:00:00+00:00',
+        },
+        {
+            'event_type': 'run_completed',
+            'run_id': 'r-once',
+            'payload': {'status': 'completed'},
+            'created_at': '2026-06-13T10:00:01+00:00',
+        },
+    ]
+    from teaagent.runner._events import read_run_events_from_audit
+
+    typed = read_run_events_from_audit(events)
+    calls = {'legacy': 0}
+    original = run_evidence._assemble_evidence_bundle
+
+    def _counting_assemble(*args: object, **kwargs: object):
+        calls['legacy'] += 1
+        return original(*args, **kwargs)
+
+    run_evidence._assemble_evidence_bundle = _counting_assemble
+    try:
+        calls['legacy'] = 0
+        default_result = build_run_evidence_bundle_from_events(
+            '.', 'r-once', typed, events
+        )
+        default_calls = calls['legacy']
+
+        calls['legacy'] = 0
+        parity_result = build_run_evidence_bundle_from_events(
+            '.', 'r-once', typed, events, verify_parity=True
+        )
+        parity_calls = calls['legacy']
+    finally:
+        run_evidence._assemble_evidence_bundle = original
+
+    assert default_calls == 1, 'default fold should assemble exactly once'
+    assert parity_calls == default_calls + 1, 'parity must add exactly one assembly'
+    assert default_result.gap_categories == []
+    assert default_result.bundle.to_dict() == parity_result.bundle.to_dict()
+
+
 def test_m6_fold_equals_legacy_on_success_run():
     """Success run with commands, tests, and an approval folds losslessly."""
     events = [

tests/test_run_receipt.py

@@ -189,7 +189,9 @@ def test_build_run_receipt_event_stream_matches_legacy_path() -> None:
         run_id = 'receipt-parity'
         _write_run(tmpdir, run_id, events)
         store = RunStore(tmpdir)
-        event_receipt = build_run_receipt(store, run_id, tmpdir, use_event_stream=True)
+        event_receipt = build_run_receipt(
+            store, run_id, tmpdir, use_event_stream=True, shadow_parity=True
+        )
         legacy_receipt = build_run_receipt(
             store, run_id, tmpdir, use_event_stream=False
         )