Per-surface parity harness for the Step 2-4 migrations

[Firehed]

Slice SP.1 — Per-surface parity harness + branch-coverage gate

• Plan step: Execution Plan 0002, Step P (gates Steps 2–4)
• RFC sections: RFC 1 §4.2 (SymbolSource authority), §4.3 (read/write segregation), §5.1/§5.2 (read/write contracts), §8.1 (enforcement)

Adds the corpus-wide golden harness that lets the Step 2–4 strangler migrations be
proven behavior-preserving. TypeGraphParityTest covers member resolution only;
this covers the four surfaces those steps move consumers onto.

What's here

• Golden infrastructure — GoldenCodec (deterministic, portable JSON encoding +
  path relativization) and the AssertsGolden trait (UPDATE_GOLDENS=1 to
  recapture, diff otherwise), each with self-tests proving a diverged surface goes
  red and update-mode recaptures.
• Four per-surface goldens, each capturing observable output over a curated,
  deterministic corpus (in-repo fixtures + the locked psr/http-message; reflection
  built-ins covered by stable-subset assertions, not frozen):
  • class-like lookup — ClassRepository::get()
  • namespace enumeration — NamespaceCatalog::childrenOf()
  • prefix search — SymbolIndex::findByPrefix()
  • document write path — open/update/close symbol state
• Scoped surface-coverage measurement — composer parity-coverage runs only the
  four surface tests with coverage restricted to the migrated surface classes, so an
  unexecuted line is a corpus gap. The corpus drives every surface class to 100%
  except a handful of provably-unreachable defensive guards, enumerated in
  tests/Parity/README.md.

Acceptance criteria (Step P)

• Goldens recorded per surface (class-like lookup, childrenOf, prefix-search, write-path), so a later step can rewrite one surface's golden while the others stay frozen
• Harness fails on any diff and runs in CI (the golden tests run in the default suite)
• Branch/line coverage of the migrated production code is measured while the harness runs (composer parity-coverage, scoped to the surface classes)
• Goldens spot-audited on first capture (e.g. Fixtures\tests confirmed a real dir; ClassModifiers multi-class file; anon-class members correctly skipped)

Notes for the reviewer

• Branch-coverage rigor is delegated to /review-slice (per the maintainer's
  decision): pcov measures line coverage; the adversarial pass verifies the corpus
  actually catches a regression (name a mutation, confirm a golden goes red).
• The measurement is a diagnostic, not a bespoke hard-fail gate. The 6 residual
  uncovered lines are pre-existing defensive/dead guards in existing production
  (parser ast === null under a collecting handler, file_get_contents after
  is_readable, synthetic-autoload-map-only branches, a Constant nameKind arm the
  extractor never emits) — documented in the README, not new code.
• Goldens were deliberately de-brittled: line/column offsets are dropped (they
  churn on any edit above a symbol), and the enumeration corpus is narrowed to stable
  namespaces (locked vendor, single PSR-0/classmap fixtures, the Fixtures\Model
  subtree) so unrelated fixture growth cannot churn it. This is a permanent
  regression net (Step Z requires it green; it is not on the Teardown ledger).

Candidate closes

None — SP.1's manifest Closes column is empty.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.12%. Comparing base (46cacbc) to head (fa16608).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #372      +/-   ##
============================================
+ Coverage     97.61%   98.12%   +0.51%     
  Complexity     1696     1696              
============================================
  Files           105      105              
  Lines          4271     4271              
============================================
+ Hits           4169     4191      +22     
+ Misses          102       80      -22     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.