Skip to content

compass(design): the stack pin warns by default, refuses under strict=True or on a transfer or merge #278

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jgong5 merged 1 commit into from
Sep 23, 2026
Merged

compass(design): the stack pin warns by default, refuses under strict=True or on a transfer or merge #278

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions atom/compass/design/03_memory_and_kv_model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

@jgong5 jgong5 Sep 23, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent-authored review comment (Claude), reviewer for #277.

Non-blocking, principle 8 (every claim carries its measurement): "always refuses" is true about strict but not about every way a transfer gets validated.

I ran it on node 18 against the merged tree 17d6577da (tip e9d31f4bc + this head). The setup is the test_spec_verbs fixtures, with a transfer fragment pinned to rocm 7.0.2 merged into a spec pinned to 7.2.4:

  • validate(<the Merge>) returns ok=False with PINNED_STACK for all four combinations of strict in {False, True} and observed_stack in {None, matching}. So the refusal does not depend on strict, which is the contrast this sentence draws.
  • validate(<that Merge>.document, strict=True, observed_stack=<matching>) returns ok=True with 0 refusals. The "whether a transferred constant came from a spec pinned to this stack" check is listed in not_asked. That is by design: merge keeps the source pin out of the document (merge.py, the transferred_from skip in merge()), and test_the_transfer_condition_names_itself_as_unaskable_of_a_document pins it.

So a reader of doc 03 alone would expect a saved cross-stack spec to be refused wherever it is checked, and it is not. This is milder than the wording #277 fixes, because the document path names the question as unasked instead of clearing silently. Suggested wording: "...moving constants across stacks, by a transfer or a merge, refuses whatever strict says". Doc 05 can carry the Merge-versus-document detail. The same "always" appears at 05_machine_spec_and_probes.md:179. 07:689-690 avoids the word and is fine as written.

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
Expand Down
4 changes: 3 additions & 1 deletion atom/compass/design/05_machine_spec_and_probes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@jgong5 jgong5 Sep 23, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent-authored review comment (Claude).

Non-blocking, principle 8. This is the same "always" as the comment on 03_memory_and_kv_model.md:360. The transfer refusal comes from validate._transfers and is reached only when the Merge itself is validated. On the saved document, validate returns ok=True and lists the transfer check under not_asked (measured on node 18). "Regardless of strict" is exact. "Always" is not quite exact.

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.

Expand Down
5 changes: 3 additions & 2 deletions atom/compass/design/07_calibration_toolchain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down