From 2540d9a0a0f895bc3b1af57a163dead7df9716f4 Mon Sep 17 00:00:00 2001 From: Jiong Gong Date: Wed, 23 Sep 2026 10:56:14 +0000 Subject: [PATCH] compass(design): state the stack pin's default exactly: warns, refuses under strict, transfer or merge Doc 03 said software_pinned_to "refuses silently reusing a spec across a stack change". The code warns by default (check_stack, StackMismatch), refuses under validate(strict=True) with Rule.PINNED_STACK, and refuses unconditionally when constants move across stacks, by a transfer (validate._transfers) or a merge (merge._conflict). Doc 03, doc 05 rule 3 and doc 07 now say all three. Closes #277 Co-Authored-By: Claude Opus 5.5 (1M context) --- atom/compass/design/03_memory_and_kv_model.md | 7 ++++--- atom/compass/design/05_machine_spec_and_probes.md | 4 +++- atom/compass/design/07_calibration_toolchain.md | 5 +++-- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/atom/compass/design/03_memory_and_kv_model.md b/atom/compass/design/03_memory_and_kv_model.md index bc33c00d33..44d90a667b 100644 --- a/atom/compass/design/03_memory_and_kv_model.md +++ b/atom/compass/design/03_memory_and_kv_model.md @@ -355,9 +355,10 @@ KV gate, a spec that cannot be recovered from the artifact makes an error unattr depend on the ROCm/RCCL/AITER build more than on the die — the +5980 MiB at width > 1 is collective buffer sizing, and the 926 MiB at TP1 is HIP context plus libraries. Adopted as a working assumption rather than left open, and made *enforceable* by - `software_pinned_to` (doc `05` D25 rule 3), which refuses silently reusing a spec across - a stack change. Still untested across dies; recorded as **T50** and cheap to settle with - one startup on a second card type. + `software_pinned_to` (doc `05` D25 rule 3): reusing a spec across a stack change warns by + default (`check_stack`) and refuses under `validate(strict=True)`, and moving constants + across stacks, by a transfer or a merge, always refuses. Still untested across dies; + recorded as **T50** and cheap to settle with one startup on a second card type. - Three topologies of one model is interpolation, not a law. The prior work said so explicitly and could not get a third model because the box was offline. - **The graph-pool width scaling rests on one point above W=1.** Context, since the line diff --git a/atom/compass/design/05_machine_spec_and_probes.md b/atom/compass/design/05_machine_spec_and_probes.md index e807a9c8b2..d6d0084b7f 100644 --- a/atom/compass/design/05_machine_spec_and_probes.md +++ b/atom/compass/design/05_machine_spec_and_probes.md @@ -174,7 +174,9 @@ that reads like a neutral measurement would undercut that; `derate` reads like w 3. **`software_pinned_to` is checked, not decorative.** The plausible reading of the evidence is that these constants track the ROCm/RCCL/AITER build more than the die — the +5980 MiB at width > 1 is collective buffer sizing, the 926 MiB at TP1 is HIP - context plus libraries. A stack mismatch warns loudly. + context plus libraries. A stack mismatch warns loudly by default and refuses under + `validate(strict=True)`; constants moved across stacks, by a transfer or a merge, + always refuse. 4. **The whole resolved spec is echoed into every run artifact.** The KV gate is **≤5%**; a number whose spec cannot be recovered from the artifact is unattributable. diff --git a/atom/compass/design/07_calibration_toolchain.md b/atom/compass/design/07_calibration_toolchain.md index 8b872b2846..9db451f68c 100644 --- a/atom/compass/design/07_calibration_toolchain.md +++ b/atom/compass/design/07_calibration_toolchain.md @@ -686,8 +686,9 @@ Two consequences worth noting: what lets one campaign serve many shapes. - The device runtime constants depend on the **library build** as much as the silicon, which is why doc 05's schema carries `software_pinned_to` and why a mismatch warns - loudly. The +5980 MiB appearing the moment width exceeds one is collective buffer sizing; - the 926 MiB at TP1 is HIP context plus libraries. + loudly by default, refusing under `validate(strict=True)` or when a transfer or merge + moves constants across stacks. The +5980 MiB appearing the moment width exceeds one is + collective buffer sizing; the 926 MiB at TP1 is HIP context plus libraries. ### The gate must be verifiable from the artifact, not from the flag