spec-047 Phase 4 — V1 migration close-out (V1 is the production path)

[codemonkeychris]

Spec-047 Phase 4 — V1 migration close-out

Closes out the spec-047 "Fully Extensible Control Model" migration. V1 is now the unconditional production path; the migration is closed. This PR is the full Phase 4 set (27 commits, §4.0.2 → §4.10) on top of main (#443, which still defaulted V1 OFF).

Net: 181 files, +4,825 / −12,371 (the large deletion is dead-code removal — legacy dispatch switch, A|B harness, flag plumbing).

Opened primarily to validate on other machines — in particular the ARM64 baseline box (LAPTOP-4MEP83VI) for the two deferred perf/byte-gate measurements (see "Outstanding" below).

What landed

• §4.0.2 / §4.0.5 — NavigationHost unmount ported to a V1 handler; XamlHost/XamlPage own their V1 registration.
• §4.1 — flipped UseV1Protocol ON by default (then removed entirely, below).
• §4.5 — deleted the legacy MountXxx/UpdateXxx dispatch switch + ~60 orphaned handler bodies; finalized the overlay/TabView genuine ports. Dispatch is now V1 registry → external _typeRegistry → composition-primitive switch (no legacy fallthrough).
• §4.6 — removed all A|B / UseV1Protocol dead code: the flag, AppContext switch, env var, dual-flag selftest harness, ReactorV2 perf-project duplicates, checkpoint runner. There is one public Reconciler(ILogger? logger = null) ctor; V1 is unconditional.
• §4.7 — graduated the public author surface out of [Experimental("REACTOR_V1_PREVIEW")] (157 attrs / 110 files) and locked it; closed KD-4 (external typed-event surface); retired the obsolete REACTOR1001/1003 analyzers (REACTOR1002 stays).
• §4.2 / §8 — echo handling settled as a documented HYBRID (spec §8.3): synchronous single-value round-trips use a value-diff arm (PendingEchoMatch + ArmExpectedEcho/ShouldSuppressEcho, opt-in valueDiffEcho); the suppress-counter (ChangeEchoSuppressor) is intentionally retained as the fallback for doubles/coercion/collection/deferred-strings/Expander/CheckBox-path-B/ApplySetters-scope/public WriteSuppressed. WriteSuppressed keeps its public signature.
• §4.3 — split the monolithic EventHandlerState: the WinUI routed-input family → ModifierEventHandlerState (lazy on ReactorState.Modifiers); control-intrinsic events → per-control ControlEventStateBox payloads. Migrated the last live holdouts (Button.Click, NumberBox immediate), deleted dead Image/ScrollViewer/ScrollView wiring + orphaned fields, added §9.2 pool-lifecycle hazard fixtures (no-double-subscribe across pool reuse, HandlerType-mismatch reset, dual-return idempotency, intrinsic-only alloc-shape, AddRawRoutedHandler survival). The monolith is gone.
• §4.4 — bucketed the 14 cross-cutting Element base fields into a value-equality ElementExtras record behind one Element.Extensions slot, via the proven ElementModifiers shim pattern (zero call-site edits — only Element.cs changed). Landed the §11.6 byte-gate target constants (PerformanceBudgets.cs: 407 / 1520 / 19200).
• §4.8 — promoted the author guide to stable; rewrote the stale AGENTS.md sections (new-control authoring → V1 descriptor model; echo → §8.3 hybrid; per-element-state → ModifierEventHandlerState + ControlEventStateBox).
• §4.10 — dead-code sweep (grep-clean for UseV1Protocol/REACTOR_USE_V1_PROTOCOL/ReactorV2/registerBuiltinHandlers/EventHandlerState-monolith); tracker + spec §14 status updated.

Validation (x64 dev machine)

• Full solution build (Reactor.slnx -p:Platform=x64): 0 errors.
• xunit (Reactor.Tests): 9128 passed / 0 failed.
• Full selftest: 0 failures modulo the known docking-family flakiness (DockHooks_* / SidePopup_*) — these fail intermittently under full-suite headless load (count varied 7→6 across runs) and pass deterministically green when filtered. Pre-existing, not a regression from this PR.

Outstanding — baseline-machine-only (the reason for cross-machine validation)

Both are code-complete; only the measurement/ratification is blocked on the ARM64 baseline machine LAPTOP-4MEP83VI:

1. §4.9 — ARM64 stable-AC perf ratification. Run §15.3 M1–M13 (randomized/interleaved ordering, cooldowns, CPU-clock telemetry) + L2/L3/L4/L6 macros + L13/L14 AOT, check §15.6 budgets vs the ReactorToday baseline, confirm/close KD-3 (apply the M1 binder-check fold only if M1 is over budget). Runbook is in the §4.9 section of the close-out task doc.
2. §4.4 — §11.6 hard byte-gate measurement/enforcement (M1 ≤407 / M2 ≤1520 / M3 ≤19200). The bucketed base ships and the target constants are landed; only the merge-blocking measurement remains.

Note for the spec author

The original exit-gate/§14 wording said "delete ChangeEchoSuppressor," but that was settled as the §8.3 hybrid (suppressor retained). The close-out docs are reconciled to the hybrid; the literal exit-gate wording should be formally ratified.

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[codemonkeychris]

CR feedback addressed (commit 3554617)

Thanks for the high-bar review. Resolutions below, with empirical results for #1.

🔴 #1 — GridView/ListBox deferred-echo → reverted to the causal counter (your preferred option (a))

Before reverting I built a probe fixture to settle the deferred-vs-synchronous question on this box. Findings:

• Post-realization SelectionChanged is synchronous for both GridView and ListBox (single programmatic write → single inline fire). The deferral called out in the fixture is mount-only (and mount writes are bare/unarmed), so the value-diff arm's precondition actually does hold in steady state.
• The counter and the value-diff arm behave identically in every production-reachable path. A contrived "two UpdateChilds with no render/dispatcher drain between them" leaks one spurious callback under both mechanisms — but the render loop never does that (one reconcile pass visits each element once), so it isn't reachable.
• For the guarded -1 no-op, I read the echo counter directly: it stays 0 through the dropped write (nothing is armed), so a later genuine deselect fires correctly — i.e. no strand under the counter.

Conclusion: the value-diff arm offered no real advantage here, so I moved both back to ShouldSuppress/WriteSuppressed, restoring main's mechanism for the default flip. ComboBox/toggles/pickers keep the value-diff arm (synchronous by construction). The probe was investigation-only and has been removed; descriptor + fixture narration updated to match.

🔴 #2 — empty ElementExtras bucket equality → fixed

Added ElementExtras.IsEmpty + Element.NormalizeExtras; all 14 bucketed init shims now (a) don't materialize a bucket for a null write and (b) collapse an all-null bucket back to null. New ElementExtrasBucketTests asserts (x with { Attached = null }) == x (and hash equality), the collapse case, and that a real value still differs.

🟡 #3 / #4 — resolved by #1

On the counter, ShouldSuppress gates the entire trampoline fire, so the multi-select snapshot OnSelectionChanged is governed too (#3). The guarded-no-op never arms suppression (counter stays 0), so the self-clear concern is moot for these controls (#4).

🟡 #5 — documented the per-extra ElementExtras construction-cost tradeoff in the §4.4 ElementExtras notes.

🟡 #6 — made Element.Extensions setter internal (no in-repo external writes; bucketed shim properties stay public), removing the initializer-ordering footgun from the locked-in public surface.

🟢 Nits

ComboBox stale ShouldSuppress doc corrected; PerformanceBudgets got a TODO(§4.9) dead-code guard; Reconciler ContinueDefaultTraversal cref namespace-qualified (clears the CS1574 warning); TabView "not byte-identical / pinnable tab appears immediately" callout added; ContentDialog OnClosed tag-routing follow-up noted in code.

Verification: core builds clean (ARM64 + x64), Reactor.Tests 9132 passed / 62 skip, and the selftest ValueDiff/Echo/ComboBox/GridView/ListBox/SelectionEvent/EventStateSplit fixtures are all green.

[codemonkeychris]

Rebased onto main (force-pushed 0f134d3c)

Synced the branch onto latest origin/main (was 5 behind / 28 ahead). Resolved conflicts:

• docs/guide/extensibility-preview.md (modify/delete ×2) — accepted main's deletion; docs: under-the-hood guide to the V1 Protocol + extension cookbook #444/docs: wire up nav + rename "V1 Protocol" page to "Control Reconciler Protocol" #448 replaced it with control-reconciler-protocol.md + extending-reactor-controls.md.
• Reconciler.Mount.cs / Reconciler.Update.cs — main's fix(navigationview): reconcile menu items in place to preserve expansion #454 (NavigationView in-place menu reconcile) modified the legacy MountNavigationView/UpdateNavigationView arms that this branch's §4.5 commit deletes. Took the deletion; main's fix lives in the V1 NavigationViewDescriptor (its own UpdateNavItemInPlace/CreateNavItem), which auto-merged cleanly, so the in-place-reconcile behavior is preserved on the production path.
• ChildrenStrategy.cs / IElementHandler.cs / MountContext.cs — kept main's new // <snippet:…> doc anchors; dropped the [Experimental("REACTOR_V1_PREVIEW")] attribute per this branch's §4.7 graduation.

Re-validation (post-rebase)

• Core builds clean on ARM64 + x64 (0 errors).
• Reactor.Tests: 9132 passed / 62 skip.
• Selftest host (--self-test): plan 1..982, 3734 ok / 0 failures.

CR fixes from 0f134d3c (the prior reply) are unchanged and re-verified green on top of main.

[codemonkeychris]

ARM64 baseline-machine capture landed — partially addresses the two "Outstanding" items

Ran the post-Phase-4 micro suite (M1–M13) on LAPTOP-4MEP83VI (the ARM64 baseline box this PR was opened to validate on) and compared against the 2026-05-25-arm64 baseline. Results + analysis are in #465 (docs/specs/047/phase4-results/LAPTOP-4MEP83VI/2026-05-29-arm64/), and I've updated the spec/§4.9/§4.4 trackers there with the measured numbers.

On Outstanding #1 (§4.9 ARM64 perf ratification) and #2 (§11.6 byte-gate measurement):

⚠️ This is an indicative capture, not the formal ratification. §15.5 isolation (AC / High-Perf / DRR-off / foreground) wasn't enforced, the §4.9-mandated randomized/interleaved ordering + CPU-clock telemetry isn't wired, and the macro suite (L1–L14) is unrunnable because this PR deleted its projects (StressPerf.ReactorV2, BlankReactorV2). So the timing axis is throttled and must be disregarded (Direct — zero Reactor code — is itself +60–140% vs baseline).

The allocation axis is valid (deterministic; Direct alloc matches the baseline byte-for-byte), and it surfaces two real findings worth acting on before the gate is claimed closed:

	result
§15.6 "M1–M3 alloc ≤ Today"	M2 −5.1% ✅, M3 −6.0% ✅, M1 +20.3% ❌
§11.6 absolute byte gate	M3 ≤19,200 ✅, M1 1,289 (3.2× over 407) ❌, M2 3,687 (2.4× over 1,520) ❌
vs baseline ReactorV2	mostly flat/better, M9 −41% 👍; but M1 +20% and M12 +17% regressed

The headline: the §4.4 bucketing made the leanest leaf (M1) ~+235 B/render heavier, not lighter — deterministic across all reps. This confirms the spec's own KD-3 trigger ("fold the M1 binder check if M1 is still over budget") and adds a new follow-up: investigate why bucketing regressed M1 (candidates: the added Element.Extensions slot, the §4.3 EHS split, the ReactorState.PendingEchoMatch slot) plus the M12 pool-reuse regression.

Net: the two outstanding items are measured but not closed — M1/M2 miss the byte gates, and a thermally-clean stable-AC re-capture (+ the macro suite rebuilt against the single Reactor variant) is still required. See #465 → RESULTS.md for the full breakdown and reproduction.