docs(rfc): amend context-selector-tearing with Option D (Relay pattern)

[layershifter]

docs: amend context-selector-tearing RFC with Option D (Relay pattern)

Summary

Amends docs/react-v9/contributing/rfcs/react-components/context-selector-tearing.md with a new "Addendum" section documenting Option D: a hook rewrite modeled on Relay's useFragmentInternal.

The original RFC considered Options A, B, C and selected A ("do nothing"). Option D was not considered at the time — it emerged from a conversation with the React team after the decision was made. Option D strictly improves on Option A for the "Glitchy Behavior" case without regressing anything else.

Why amend rather than replace

The original decision record is load-bearing context: it documents the reasoning for rejecting Options B and C, the test harness, and the "Level 1 tearing is acceptable" framing. Keeping it intact and appending an addendum preserves that history. The addendum section is clearly dated and labeled as revisiting the decision in light of new evidence and a new option.

What's in the addendum

1. New root-cause analysis of the "Glitchy Behavior" note the original RFC flagged but didn't bottom out. The bug is a fiber.lanes pollution issue in React's dispatchSetStateInternal eager-bailout check — the bound-at-mount fiber becomes the stale alternate after the first listener-driven commit and its lanes never get cleared, permanently failing the NoLanes precondition.
2. Empirical confirmation via patched react-dom.development.js that logs fiber.lanes / alternate.lanes at the check site. First dispatch: fiber=0 alt=0 eager=TRUE. All subsequent dispatches on that fiber: fiber=1 alt=0 eager=FALSE.
3. Option D specification: read valueRef.current during render (like useSyncExternalStore.getSnapshot), no [value, selected] state tuple, no setState(prev => prev) bailout trick. Listener compares selector(newValue) against a layout-effect-latched lastReturnedRef.current and force-updates only when the slice actually differs. Matches Relay's useFragmentInternal_CURRENT.js pattern.
4. Comparison table vs Option A: fixes the glitch, preserves everything else (tearing behavior, concurrent safety, public API).
5. Why not B or C (unchanged): B still doesn't fix the glitch per the original RFC's test, C has a newly-empirically-verified concurrent-mode hazard where uncommitted transition values leak into sibling urgent renders.
6. Measurements from the investigation repo's probe suite.

Accompanying PR

microsoft/fluentui#<TBD> — implementation of Option D in @fluentui/react-context-selector. The two PRs can merge in either order; the doc PR stands on its own as the architectural record.

Test plan

• Prose-review the addendum section (peer reviewer).
• Verify the diff against main is additive — no existing sections modified.

Out of scope

• Level 1 tearing. Unchanged from original RFC.
• Any API changes. Option D is API-compatible.

[github-actions]

📊 Bundle size report

✅ No changes found

[github-actions]

Pull request demo site: URL