doc: Document the physical optimizer contract

[2010YOUY01]

Which issue does this PR close?

• Closes #.

Rationale for this change

This PR tries to captures the current state and explains it. Please let me know if I’ve missed anything.

What changes are included in this PR?

docs only

What is the testing strategy for this PR?

Are there any user-facing changes?

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.72%. Comparing base (7b1e55d) to head (833aebd).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #26107      +/-   ##
==========================================
- Coverage   82.72%   82.72%   -0.01%     
==========================================
  Files        1147     1147              
  Lines      449175   449213      +38     
  Branches   449175   449213      +38     
==========================================
+ Hits       371598   371627      +29     
- Misses      54929    54931       +2     
- Partials    22648    22655       +7     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.