[WS2][RFC] Clarify cross-config logprob drift contract

[CyberSecurityErial]

Summary

Part of #111. Builds on #108.

This PR clarifies the WS2 RFC tolerance model: the #108 per-dtype threshold is a numerical infrastructure contract for pre-update selected-token logprob alignment, not a universal proof of algorithmic harmlessness.

Changes

• Define WS2 acceptable drift as max_abs_dlogp satisfying the [WS1] Ground-truth harness + numerical contract for batch-invariant ops #108 per-dtype threshold.
• Add tolerance interpretation language separating infrastructure alignment from downstream model-effect validation.
• Add drift source taxonomy for arithmetic schedule, reduction/collective, quantization/dequantization, and logical input/metadata mismatch.
• Add a layered ablation strategy and interpretation rules.
• Extend the follow-up test matrix with source-isolation ablations and downstream model-effect recording.

Validation

git diff --check
python3 -m mkdocs build --strict -f mkdocs.yaml --site-dir /tmp/rlkernel-ws2-rfc-site

Results:

• git diff --check: pass
• mkdocs build --strict: not run; local Python environment does not have mkdocs installed (/usr/bin/python3: No module named mkdocs)

Notes

Documentation-only RFC update. This does not add a second tolerance table, runtime gates, tests, or implementation changes.

Summary by CodeRabbit

• Documentation
  • Added a new design RFC describing the WS2 cross-config alignment contract.
  • Documented how drift is measured, including token selection, masking rules, and training/rollout comparability requirements.
  • Defined expected failure signals, diagnostic metrics, tolerance handling, and a taxonomy of drift sources.
  • Included guidance for classification, ablation analysis, and future test coverage.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a single new RFC documentation file defining the WS2 cross-config logprob drift contract, covering the dlogp measurement definition, comparability requirements, primary failure signal, diagnostics, tolerance sourcing/interpretation, drift source taxonomy, decision rules, a layered ablation strategy, and a follow-up test matrix scope.

Changes

WS2 Drift Contract Documentation

Layer / File(s)	Summary
RFC intro and measurement contract docs/design/ws2_cross_config_logprob_drift_contract.md	Introduces motivation for using selected-token logprob drift as the primary signal and defines the dlogp formula, token masking rules, teacher-forcing requirement, and comparability contract.
Failure signal, diagnostics, and tolerance docs/design/ws2_cross_config_logprob_drift_contract.md	Specifies zero-update failure expectations, the diagnostics metric set, tolerance sourced from the WS1 per-dtype threshold table (#108), and effect-based validation guidance.
Drift taxonomy and ablation strategy docs/design/ws2_cross_config_logprob_drift_contract.md	Documents drift source taxonomy, a stepwise decision rule, a layered ablation strategy (A0–A5), interpretation rules, and a follow-up test matrix scope.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related issues

• [WS2] Tolerance contract alignment & WS2 drift report format #116: Defines the same WS2 cross-config tolerance/drift-report standard and metrics this RFC documents.
• [WS2] Cross-config alignment (mismatched rollout/training parallelism) #111: Directly related to the WS2 cross-config alignment contract and tolerance standard documented in this RFC.

Poem

A rabbit sat with quill in paw,
Drafting rules of drift and law,
Dlogp measured, tokens masked with care,
Tolerance sourced from thresholds fair,
A0 to A5, hop by hop we go,
Documenting drift for all to know. 🐇📜

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the doc-only RFC and summarizes the main change: clarifying the WS2 cross-config logprob drift contract.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Flink-ddd]

Excellent work! LGTM, Here's a small suggestion: could you add a design sketch to this document?