[WS2][RFC] Add modular cross-config alignment roadmap

[CyberSecurityErial]

Summary

Part of #111. Builds on the merged RFC in #207 and reuses the #108 numerical contract.

This documentation-only PR turns the WS2 cross-config logprob contract into a modular implementation roadmap. The roadmap is centered on two design decisions:

1. Minimal, layered alignment: logical inputs must match exactly, but numerical paths should only be aligned at the smallest layer required to satisfy the selected-token logprob contract.
2. A composable ablation controller: batch/layout/dtype/cache/parallelism/kernel differences are modeled as typed knobs that can be explored through one-at-a-time, pairwise, or Cartesian grids.

What changed

• Add an L0-L5 alignment ladder that makes full/bitwise alignment a diagnostic fallback rather than the default production goal.
• Add a controller-centered design with typed experiment definitions, knob lifecycles, capability constraints, provenance validation, stable case ids, resumable execution, and a result cube.
• Map proposed knobs to the current repository surfaces:
  • VLLMSamplerConfig
  • StatelessForwardConfig
  • TorchRLTrainingConfig
  • resolve_logp_op_type()
  • TP linear_logp
  • build-time kernel flags
• Distinguish request-time, engine-construction, process-start, and build-time knobs so grid cases cannot silently reuse stale engines or cached kernel backends.
• Define a kernel backend descriptor/policy bridge so rewritten CUDA/Triton kernels can register without adding branches to the grid planner.
• Consolidate the previous fine-grained roadmap into:
  • 4 baseline infrastructure PRs
  • 4 ablation-controller PRs
  • 2 fixed core-scenario PRs plus one-root-cause fix PRs
  • 3 grid/CI closure PRs
• Define [WS2] Cross-config alignment (mismatched rollout/training parallelism) #111 completion around the smallest sufficient alignment set for the vLLM TP=2 versus FSDP scenario, not broad internal bitwise equality.

Proposed PR groups

Group	Scope
B1-B4	Shared contract/report, exact scorers, score-only FSDP controls, paired runner and rank aggregation
C1-C4	Typed grid planning, runtime materializers, kernel policy bridge, lifecycle-aware execution/result cube
M1/M-FIX/M2	First TP=2/FSDP diagnostic, one root cause per fix, minimal-alignment gate
G1-G3	Composable required grid, A0-A5 profiles/CLI, targeted GPU CI and downstream handoff

Validation

git diff --check
/tmp/rlkernel-docs-venv/bin/python -m mkdocs build --strict \
  -f mkdocs.yaml \
  --site-dir /tmp/rlkernel-ws2-roadmap-site

Results:

• git diff --check: pass
• mkdocs build --strict: pass

Non-goals

This PR does not add runtime code, tests, thresholds, distributed fixes, or kernel changes. It documents the implementation boundaries and review-sized roadmap for follow-up PRs.

Summary by CodeRabbit

• Documentation
  • Expanded the cross-configuration log-probability drift contract with a framework upgrade overview, modular execution plan, and clearer scope boundaries.
  • Added detailed guidance for controller-centered experiment design, typed core objects and knobs, deterministic case planning, filtering/resume, and isolation validation.
  • Documented alignment analysis framing, configuration-to-repo mapping, kernel integration requirements, ownership boundaries, and updated PR roadmap/completion criteria.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e01f7f20-f7e1-4c45-b6b3-9eaad41782e4

📥 Commits

Reviewing files that changed from the base of the PR and between 1def189 and 1d1acb1.

⛔ Files ignored due to path filters (1)

• docs/assets/ws2-cross-config-before-after.png is excluded by !**/*.png

📒 Files selected for processing (1)

• docs/design/ws2_cross_config_logprob_drift_contract.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/design/ws2_cross_config_logprob_drift_contract.md

---

📝 Walkthrough

Walkthrough

The WS2 RFC now defines layered alignment semantics, a controller-centered experiment framework, typed grid and provenance contracts, kernel integration boundaries, ownership boundaries, and a phased roadmap with updated completion criteria.

Changes

WS2 Cross-Config Alignment Contract

Layer / File(s)	Summary
Alignment model and controller architecture docs/design/ws2_cross_config_logprob_drift_contract.md	Adds the framework overview, alignment ladder, controller flow, typed core objects, grid planning, isolation validation, and minimal sufficient alignment analysis.
Kernel integration and repository boundaries docs/design/ws2_cross_config_logprob_drift_contract.md	Documents configuration-surface mapping, lifecycle constraints, backend descriptors, policy resolution, strict fallback rejection, repository gaps, and ownership boundaries.
Modular roadmap and completion criteria docs/design/ws2_cross_config_logprob_drift_contract.md	Replaces the follow-up test matrix with phased roadmap scopes, grid-coverage requirements, PR sizing rules, exclusions, and updated completion criteria for issue 111.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• RL-Align/RL-Kernel#207: Updates the same WS2 RFC’s cross-config drift contract and related roadmap scope.

Suggested reviewers: maxiaosong1124, inaniloquentee, KJLdefeated

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the documentation-only change adding a modular cross-config alignment roadmap.
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.

✨ 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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/design/ws2_cross_config_logprob_drift_contract.md`:
- Line 838: Update the heading text beginning with “#111 is complete when:” to
use valid Markdown, such as “Issue `#111` is complete when:”, preserving the
intended wording and meaning.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: efff75b2-a7b5-4848-892f-82df7e387771

📥 Commits

Reviewing files that changed from the base of the PR and between 77d50a3 and 1def189.

📒 Files selected for processing (1)

• docs/design/ws2_cross_config_logprob_drift_contract.md

[Flink-ddd]

Excellent work! Thank you, LGTM.