docs(color): ADR-021 encoding-state invariant + DP-declared handoff [#409]

[dfattal]

What

Establishes a vendor-neutral color contract for the runtime (ADR-021) and fixes the documentation + code that the #407/#408 sRGB investigation showed to be inconsistent. Docs + one-line guard only — no behavior change.

Resolves the design question in #409.

Why

The three compositor paths each grew a different colorspace strategy, and the reactive fixes were tuned to one vendor's display processor — inverting DisplayXR's dependency direction (the DP adapts to the runtime, not the reverse). One path (service/workspace sRGB-client branch) carries the same unmatched-decode half-conversion #407/#408 fixed in-process; it's latent only because every shipping app stores encoded-into-UNORM.

Changes

• docs/adr/ADR-021 (new) — the encoding-state contract:
  • Matched-pair invariant: conversions come in pairs (decode…encode) or passthrough, never half.
  • Compose space is DisplayXR-internal/vendor-neutral; DP-handoff encoding is declared — the DP states which encoding(s) it accepts (LINEAR/ENCODED/EITHER) and the runtime declares per-frame what it sends. Production DPs typically accept EITHER, so the runtime never converts at the boundary.
  • Canonical transfer function is standard sRGB; no vendor curves in runtime shaders (the dead linear_to_srgb() is to be removed).
  • Model A (passthrough) baseline; Model B (linear compose) sanctioned future, scoped to the workspace compose path (where blending/transparency lives), gated on that feature. B degenerates to A wherever nothing blends.
• compositor-pipeline.md — corrects the wrong "DP expects linear input" assertion to the declared-handoff model; documents the latent sRGB-SRV half-conversion.
• vendors/leia/weaver.md — maps the vendor SDK's sRGB-conversion knob to the ADR contract + records the plug-in wiring gaps. (Vendor specifics live here, not in the ADR.)
• comp_d3d11_service.cpp — one-shot guard + corrected comment on the per-client sRGB-SRV branch.
• Fixed 4 inbound anchor links to the renamed color-space section.

Not in this PR (specified in the ADR as next steps)

• The process_atlas() per-frame atlas-encoding argument + the DP-vtable capability field (ABI work per ADR-020).
• Vendor plug-in wiring (separate repos).
• The true-linear test app + regression matrix.

Test

Docs + a one-shot U_LOG_W behind a static bool; no runtime behavior change. The guarded branch is dead in practice today.

🤖 Generated with Claude Code