docs: plan for porting XoRL features from main onto dev

[qywu]

Scaffolding and the written plan for #26. No feature code yet — this is the shape the ports land in.

Three placements, one rule

Placement	Use when	Cost at upstream sync
python/sglang/xorl/	new capability upstream has no version of	none
python/sglang/overrides/	changed behaviour of a module upstream does have	none textually; the twin can silently drift
in-tree edit	neither of the above can work	a conflict on every sync

Two constraints found while sizing the work

Both are recorded in the code and docs where someone will actually hit them.

Additive code cannot use the overlay. The finder fires when sglang.srt.X is imported and a twin sglang.overrides.X exists. A twin whose upstream counterpart doesn't exist is never imported and never fires — it sits there looking installed and doing nothing. Hence sglang/xorl/.

server_args.py cannot use the overlay at all. 458 NS() field annotations and nine guard tests, including two-way namespace coverage (test_server_args_namespaces.py) and a mutation ratchet. Dataclass fields are fixed at class creation, so no post-hoc patch adds a field and still satisfies those guards. CLI surface is an in-tree edit — the one place we knowingly take a conflict on every upstream sync, so it stays minimal and the behaviour behind it goes in xorl/ or overrides/.

__apply_patch__ suits replacement, not interleaving. Replacing a whole function or method is clean. Interleaved edits inside a long method force the twin to copy that method, and the copy then stops tracking upstream fixes with nothing to warn you. That's the trap that makes an overlay look maintainable while it quietly rots, so it's called out rather than discovered later.

Why the port is cheap right now

Git actively misleads here. main's reported merge-base is 2026-03-18, but 38dc5c2b0 squashed its upstream import instead of merging, leaving no ancestry. By tree distance, main's real base is 48f1b14fc (2026-08-06) — one day before v0.5.17 — with only 137 files between it and main's post-sync tree.

So the XoRL code was written against an upstream contemporaneous with dev's base: this is a port, not a re-implementation. That decays with every upstream release, which is the argument for starting with the high-value items now.

Contents

• python/sglang/xorl/__init__.py — namespace for additive modules. Deliberately inert; verified it adds zero sglang.srt imports of its own, since anything pulling srt in earlier than sglang/__init__.py's bootstrap would permanently un-override whatever it touched.
• docs/xorl-porting-plan.md — placement rules, port order, per-feature definition of done.
• python/sglang/overrides/README.md — documents the boundary, so the next person reaching for a twin learns the two limits before writing one.

Draft, because two questions in #26 change the order

• Is sgl-model-gateway in scope?
• Is the near-term need P2P weight update + exact serving + routed-expert capture, or do multi-LoRA MoE and canonical MoE come too?

[broly-code-security-scanner]

Broly Security Scan

Warning

Latest baseline snapshot is stale. Broly is running in PR-only fallback mode until the next scheduled baseline refreshes. This does not block the PR.

Note

✅ Clean scan
No vulnerabilities detected in this PR.

Note

Re-scan this PR anytime with /broly scan — useful after /broly undismiss, or to refresh findings without a new push.

Broly — SAST (zai-org/GLM-5.2) · Secrets · SCA · IaC · GH Actions · Base Images · Supply Chain Threats · Exploit Chains · Adversarial Verification

We're continuously improving Broly's accuracy and finding quality — your feedback is valuable. False positives, missed findings, bugs, and feature requests all welcome.