Reorganize xorl.ops: vendored quarantine, objectives split, ops/exact, ops/families (#78 phases 1-5)

[qywu]

Phases 1–5 of #78, one commit per phase, stacked on the phase-0 PR #80 (base branch reorg/phase0-vendored-markers; retarget to main after #80 lands). Every move leaves a compat stub or lazy re-export at the old import path for one deprecation cycle, and every in-repo import was codemodded to the new canonical path in the same commit.

Phase 1 — vendored quarantine

ops/quack → ops/_vendored/quack, ops/linear_attention/flashqla → ops/_vendored/flashqla (~30k lines out of the first-party namespace). Old paths are sys.modules alias stubs (deep submodule imports through them create a duplicate module instance — noted in the stub docstrings). Lint/format/codespell excludes collapse to the single _vendored/ prefix.

Phase 2 — objectives out of ops/loss

New xorl.objectives package: policy_loss, grpo_loss, cispo_loss, importance_sampling_loss, opd_loss, opd_streaming_kl, causallm_loss, reducers, loss_output, and the loss registry. ops/loss keeps only the CE/selected-logprob kernel stack. The old package paths re-export the objective API lazily (PEP 562) — eager re-export is an import cycle, since the objectives import the kernels.

Phase 3 — the exact-contract family under ops/exact (+ ops/sglang, per review)

Physically moved: rope_class_b, canonical_moe_leaf, canonical_moe_cast, kernel_config_pin, bi_gemm_configs, block_fp8_native, fused_silu_and_mul, and (after review feedback, commit cc8f635) exact_sampling_transforms.py → ops/exact/sampling_transforms.py.

Per @kiddyboots216's suggestion on #78, the literal serving-engine twins get their own ops/sglang/ package: bi_families_v2.py (moved byte-identical — same git blob as main; the sha256 gate hashes content, not paths) and batch_invariant_ops.py (vendored-adapted from sglang/srt/batch_invariant_ops). One deviation from the issue sketch stands: batch_invariant_ops.py is not split — it must remain a single file diffable against the serving twin. The taxonomy is three-way: _vendored/ (untouchable snapshots), sglang/ (parity twins, paired-edit policy), first-party everything else.

Phase 4 — one home per family; layers out of ops

ops/glm5_kernels → ops/families/glm5, ops/dsv4 → ops/families/dsv4. Deviation from the issue sketch: they stay under ops/ rather than moving into models/transformers/<family>/ because those packages have import side effects (DSV4 mutates the HF Auto registries on import) and kernels must be importable without them. The GatedDeltaNet and Mamba2Mixer layer classes move to xorl.models.layers; the kernel-adjacent contract modules (linear_attention/modules, ssm/modules) stay in ops by design.

Phase 5 — dead code

ops/ep_kernels had zero importers for any of its seven exports — deleted rather than merged into moe/ as sketched.

Verification

• pre-commit run --all-files (the lint CI command) green after every phase.
• Full CPU matrix run locally: tests/ops (90 passed), catch-all tests minus server/distributed/ops (501 passed), tests/server -m cpu (green), tests/distributed -m cpu (153 passed; 1 failure — test_native_fp8_meta_materialization_preserves_fsdp2_dtensors — fails identically on unmodified main).
• GPU spot checks on moved paths: MoE backends, BI golden gates, fused linear-logprob (quack), gated-delta-rule.
• Pre-existing failures on this box, identical on unmodified main, unrelated to this PR: 14 tilelang-compile failures (dsv4 indexer/sparse-MLA + flashqla contract pins; nvcc/CUDA-13 header mismatch), 2 model-snapshot tests, 1 native-FP8 FSDP2 materialization test, and 2 pytest_asyncio-missing collection errors in tests/server/orchestrator.
• One real codemod bug was caught by the sweep and fixed in the last commit: the vendored-path rewrite matched …flashqla as a prefix of the first-party flashqla_cp module.

Closes nothing by itself; tracks #78 (phases 1–5). The deprecation-stub deletion sweep is the future final phase.

[broly-code-security-scanner]

Broly Security Scan

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.

 

[kiddyboots216]

Three members are aliased in place rather than moved, deviating deliberately from the issue sketch:

don't think this is good

[qywu]

Done in cc8f635 — no aliases left. You were right that the constraint was narrower than I stated: the sha256 gate hashes content, not paths, so moving the file is safe (the moved bi_families_v2.py is the same git blob as on main — byte-identical).

Per your #78 suggestion there's now an ops/sglang/ package for the literal serving-engine twins: bi_families_v2.py (byte-gated, format carve-out follows the new path) and batch_invariant_ops.py (vendored-adapted from sglang/srt/batch_invariant_ops; kept a single file so it stays diffable against the serving copy — the originally-sketched 4-way split is the one thing I'd still push back on, for that reason). exact_sampling_transforms.py is now physically ops/exact/sampling_transforms.py. Old paths are full-fidelity alias stubs for one deprecation cycle; all in-repo imports rewritten. #74 will need a rebase over the rename — I'll handle it.

[kiddyboots216]

a lot of the file names etc. are kind of artifact-y, like the "rope class b" is just nomenclature from the blog post, i think we should feel free to take a high-level look at the kernels / ops breakdown and see how we can name things to not be so inscrutable / opaque. there's too much scar tissue in the names.

[qywu]

Agreed on the scar tissue. Two-part response:

Done now (abed122): a name glossary in ops/README.md decoding bi_, K3, Class-A/B RoPE, canonical MoE reduce, one-round SwiGLU, families v1/v2, GKN, "exact" — so nothing is inscrutable while we rename.

Needs your sign-off before executing — most of these names are load-bearing beyond file names, so renames have blast radii:

current	proposed	blast radius
rope_class_b (module + fns)	rope_fp32_single_round	also a YAML config field rope_class_b: — needs a deprecated alias
bi_ prefix (fns, bi_gemm_configs, tests)	spell out batch_invariant_	ce_mode: bi_fused is user config; bi_families_v2 is the serving twin — renaming it means renaming in SGLang too
canonical_moe_*	moe_fixed_order_reduce_*	CANONICAL_MOE_REDUCE_VERSION is a cross-engine contract key (string can stay; module/fn names can change)
exact_ fn prefix	drop it — the ops/exact/ package now carries the meaning	pure churn, best done in the stub-deletion sweep
fused_silu_and_mul's exact_fp32_silu_and_mul	one_round_swiglu	config stamp _exact_one_round_swiglu already uses this vocabulary
K3 (docs/k3, "zero-K3")	keep — it's the k3 KL estimator, a real term	—
families_v2 / head_v2	keep — version names are genuine	—

Say which rows you want and I'll execute them as one rename commit here (module renames with alias stubs) plus a follow-up for the config-field deprecations.

[qywu]

All table rows executed (4 commits, abed122..c28f8cb):

• rope_class_b → rope_fp32_single_round — module, functions, internal stamps, and the YAML field. rope_class_b: and XORL_ROPE_CLASS_B remain deprecated aliases (DeprecationWarning). Test files renamed incl. the distributed shard claim.
• bi_ spelled out — canonical ce_mode value is now batch_invariant (bi_fused accepted + warned in both entry points); bi_fused_lm_head.py → batch_invariant_lm_head.py with its functions; bi_gemm_configs → batch_invariant_gemm_configs; prose/messages/examples/docs updated. The bi_ prefix survives only inside the serving twins (bi_families_v2, the bi_* kernels in batch_invariant_ops, bi_fused_gdn_gating) whose symbols must match the engine.
• canonical_moe_* → moe_fixed_order_reduce_* — modules + Python names; the cross-engine contract key CANONICAL_MOE_REDUCE_VERSION and the registered xorl_k3::_canonical_moe_* torch.library op names keep their strings (pinned identifiers).
• exact_fp32_silu_and_mul → one_round_swiglu with a deprecated alias.
• Rows marked keep/defer stayed as proposed (K3, families_v2/head_v2; the exact_ fn-prefix drop lands with the stub-deletion sweep).

Glossary updated to lead with the new names (old terms noted as "formerly"). Alias regression tests added for both config deprecations. Verified: full pre-commit, arguments suites, the batch-invariant head + golden-gate + rmsnorm-family + exact-head + trainers surfaces all green locally.