[Config] Round 6.5: a namespace declares what it derives, next to what it derives it from (#38113)

Fifth of five; stacked on #38049. The split gave every namespace a file, but
only for the half an operator types. This is the other half.

## The parallel quotients are declared, not written out

`attn_tp_size` and its five siblings were sixty lines of near-identical
properties in the runtime context, a file away from the leaves they are
quotients of, so reading `parallel.py` told you what you could set and nothing
about what that decides.

They are declared in `Parallel` now, in the same class as those leaves. They
carry no annotation, so they are not dataclass fields and
`collect_input_fields` never puts them on the record -- the same mechanism that
already keeps `_NS_PATH` off it. That is the right exclusion: a quotient has no
operator input to preserve, and the record is what crosses a process boundary,
where a stamped width is one an elastic scale-up will not refresh.

## A quotient is a value in the bag, like every other derived one

`_derived_width` answered from a stamp or, failing that, a live process group.
The group read could never disagree with the stamp:

- `initialize_model_parallel` stamps all six as its last statement,
  unconditionally;
- an elastic scale-up restamps `attn_dp_size` through
  `update_dp_attention_post_scale` -- the comment claiming it does *not* was
  wrong;
- no hardware backend builds groups of its own;
- `multimodal_gen`, which has its own `initialize_model_parallel` and does not
  stamp, never reads a quotient.

So a built group was always already stamped, and the group read goes -- and with
it the last reason for a quotient to be resolved on every read.

Every input to `derive_parallel_widths` is a record field. `dcp_enabled` is
`decode_context_parallel_size > 1`, not a fact about a built group; it was
spelled `_DCP is not None`, which is a longer way to say the same thing. So the
six are fixed once the configuration is fixed -- the same test every other
`Derived(fn=...)` in this PR passes. They are declared the same way and computed
the same way: once, at publish, into ordinary bag leaves.

What remains is override -> stamp -> published leaf. The stamp stays above the
leaf because an elastic scale-up restamps `attn_dp_size`; the override stays on
top because that is how a test names a width.

## One answer for the config-derived predicates

`enable_mamba_extra_buffer` and its lazy variant, `is_ep_joiner`,
`is_ep_scale_joiner`, `is_startup_weight_load_overlap`: each existed as a
`ServerArgs` member for the resolution pipeline and, for most of them, again as
a `runtime_context` function for readers after publish. Three places to keep
saying the same thing.

A `Derived(fn=...)` is a pure function of the published configuration, so
`publish` computes it once and stores it as an ordinary bag leaf -- a plain
attribute load, which is what a read inside compiled model code needs. The
function is handed the whole resolved config rather than the bag it lands in,
because a derivation is free to span namespaces and the mamba one does: it
reads `memory.disable_radix_cache` alongside its own `exec.mamba` strategy,
which is why it could never have been a method on either bag.

The pre-publish helpers stay -- resolution needs the predicate before there is
a bag to read -- and three readers keep them, because they run before their own
process publishes: `initialize_dp_attention`, which the weight-cache daemon
calls while building its groups thirty lines before its `publish`, and
`PortArgs.init_new`, a factory handed the record that already reads eighteen
other fields off it.

## Notes for a reviewer

**Overriding a leaf does not move its quotient.** `override(tp_size=2)` leaves
`attn_tp_size` where the published config put it, because nothing is recomputed
on read. A test states a topology by publishing a config -- which is what a
real process does -- or by naming the width it wants, `override(attn_tp_size=2)`.
Six tests say it that way now. This is the price of having one answer computed
once, and it is the same price every other derived value in the config already
carries.

A caller that reads a quotient without publishing or overriding now gets an
explicit error naming the field, instead of a default that an uninitialised
group happened to supply. One fixture was in that state --
`TestMlaWriteDoorsUnderDcp` built a bare pool and asked whether DCP was on --
and it publishes a config now, which is what the process it stands in for
does.

Eighteen sites read these predicates without calling them. That is correct --
they are properties -- but it is worth saying they were checked, because a
census that assumes otherwise reports eighteen always-true conditions.

## The skill that documents this subsystem is updated with it

`.claude/rules/modify-component-must-read.md` points at
`.claude/skills/sglang-runtime-context/SKILL.md` before anyone touches these
files, so a stale sentence there is a wrong instruction rather than a stale
note. Four of its load-bearing statements stopped being true across this series
and are corrected here: `NS(...)` is no longer how a field states its namespace
(the declaring class is); the DCP degrade rule is gone, because the quotients
are not live reads; `mamba_extra_buffer_enabled()` and the other predicate
functions it named as the shape to copy no longer exist; and the
namespace-coverage ratchet is described in terms of the marker. The docstring of
`test_server_args_namespaces.py` said the same thing and is fixed too.

The consequence a test author actually trips over is stated there as well:
overriding a leaf no longer moves its quotient, so a topology is stated by
publishing a config or by naming the width.

## Verification

A full registered-unit sweep (648 files) against this stack's merge-base:
19 failures on both sides, the same 19 -- AMD `gfx950`, `modelopt`,
`cuda_vmm`, `weight_checker` and friends, none of them config. The narrower 139-file config sweep used earlier in this series
does not contain the files this change reaches -- `test_kv_index_translator`
never names `get_parallel()`, it constructs an object that does -- which is why
the baseline differential over everything is what is quoted here.
This commit is contained in:
Cheng Wan
2026-09-06 21:44:24 -07:00
committed by GitHub
parent b99175dc7d
commit aaf9a95763
56 changed files with 1118 additions and 379 deletions
+35 -15
View File
@@ -47,8 +47,11 @@ with what the operator typed, not with what resolution decided.**
compilation disabled before restricting a role), and
`=enforce` fails closed on bag reads outside the role's `ROLE_NAMESPACE_SETS` entry
(`None` = full tree; only audited roles are restricted).
- Bag membership is metadata on the dataclass: every `ServerArgs` field carries
`NS("path")` (e.g. `NS("exec.moe")`); coverage is linted two-way
- Bag membership is **where the field is declared**: one class per namespace under
`arg_groups/fields/`, each carrying the `_NS_PATH` it stands for, and `ServerArgs`
is assembled from them (`collect_input_fields`). The per-field `NS("path")` marker
survives only for a class that cannot express this — an ad-hoc dataclass spanning
namespaces, which is what the config-bag tests build. Coverage is linted two-way
(`test_server_args_namespaces.py`, `test_runtime_context_config_bags.py`).
- **Reading config**: `get_<ns>()[.sub].field` — e.g.
`get_exec().moe.moe_a2a_backend`, `get_schedule().max_running_requests`. Bag leaves
@@ -253,10 +256,18 @@ A process-global seed field-read of one of these sizes
(`get_server_args().tp_size`, or an alias of it) is a read-ratchet failure. A
`server_args` the object was *handed* is a different thing and not a ratchet
matter — see "Reads that legitimately stay on a ServerArgs instance".
Fail-loud is narrower: before dist init, a live size/group read raises — except
the DCP pair, which degrades instead (`dcp_enabled` → `False`,
`attn_dcp_size` → `1` when no group is installed;
`test_attn_dcp_defaults_when_group_is_uninitialized` pins this). After init,
Fail-loud is narrower: before dist init, a live *rank/group* read raises. The six
parallel quotients are not live reads at all — `attn_tp_size`, `attn_dp_size`,
`attn_dcp_size`, `moe_ep_size`, `moe_tp_size`, `dcp_enabled` are a function of the
configured leaves, computed once at publish into bag leaves, and answered
override → stamp → published leaf. So `dcp_enabled` means "the launch configured
DCP" (`dcp_size > 1`), not "a DCP group is installed here"; in a scheduler the
stamp makes the two identical, in a process that publishes without dist init they
differ. `test_a_topology_is_stated_by_naming_the_width` and its neighbours in
`test_runtime_context.py` pin this; they replaced
`test_attn_dcp_defaults_when_group_is_uninitialized`. One consequence for tests:
overriding a leaf no longer moves its quotient — state a topology by publishing a
config, or by naming the width. After init,
only the DCP group is optional (`_DCP` exists only when `dcp_size > 1`; attn-CP and
moe-DP always install, as size-1 aliases if unused). The `config` hop is
deliberately dynamo-traceable (a plain property over a slot, no
@@ -283,13 +294,21 @@ where an object was handed one; it is not a global accessor.
raises on a non-leaf. A call site that knows its field reads the bag leaf.
- **the live topology** → `get_parallel()` (bare names).
- **a value derived from published leaves** → an accessor in `runtime_context` that
derives it *from the bags*: `mamba_extra_buffer_enabled()` /
`mamba_extra_buffer_lazy_enabled()` read `get_memory()` and `get_exec()`, so
they see post-publish overrides. Prefer this shape whenever the inputs are
leaves; the same-named `ServerArgs` members are the pre-publish equivalents the
resolution pipeline uses, and wrapping one of those instead would quietly cost
you override visibility. `is_ep_joiner()` / `is_ep_scale_joiner()` are the same
shape over `exec.moe.ep_join_mode`, `attention_backends()` derives the
derives it *from the bags*. The strongest form of this is a `Derived(fn=...)`
declared beside the leaves it is computed from, in the namespace's own
`arg_groups/fields/` class: `publish` computes it once and stores it as an
ordinary bag leaf, so the read is a plain attribute load and it sees
post-publish overrides. `enable_mamba_extra_buffer`, `is_ep_joiner`,
`is_ep_scale_joiner` and `is_startup_weight_load_overlap` are declared that way
now — read them where they are declared:
`get_exec().mamba.enable_mamba_extra_buffer`, `get_exec().moe.is_ep_joiner`,
`get_model().is_startup_weight_load_overlap`. (The namespace is the class that
declares the field, not the namespaces its `fn` happens to read: the mamba one
spans `exec.mamba` and `memory`, which is exactly why it could not be a method
on either bag.) The
old `mamba_extra_buffer_enabled()` / `is_ep_joiner()` functions and the
same-named `ServerArgs` members are gone. The pre-publish helpers that remain
exist for resolution, which has no bag to read yet. `attention_backends()` derives the
`(prefill, decode)` pair from the three `exec.kernel` leaves, and
`max_speculative_num_draft_tokens()` / `cutedsl_moe_max_num_tokens()` derive
theirs from `spec` / `schedule` / `exec.graph`.
@@ -548,8 +567,9 @@ ONE thread — do not design for TBO threads that don't exist.
flag-owning layers are pinned by name. A new module-level runtime global belongs on a
flags group / resources slot instead; migrating a pinned survivor must shrink the pin.
7. **Namespace coverage** (`test_server_args_namespaces.py`,
`test_runtime_context_config_bags.py`): every `ServerArgs` field carries `NS(...)`
metadata and the projected bags must cover the fields exactly (two-way).
`test_runtime_context_config_bags.py`): every `ServerArgs` field resolves to a
namespace — from the `arg_groups/fields/` class that declares it — and the
projected bags must cover the fields exactly (two-way).
Never module-skip a test "until the migration settles" — seed the context instead
(the deferral ratchet that once pinned this is retired; the rule stands).