compass(spec): hold the probe tables, the reimport helper and the transfer stanzas against their defects

[jgong5]

This PR is agent-authored.

Closes #231. It also closes CA2/CA2m, which #346's cycle-2 review found and #231's last comment added to this issue.

Tests only. 0 production lines. tests/compass/test_spec_verbs.py is +12 / −3. No refusal text changes.

What changed

item	before (tip 872edea12)	now
pin B: test_a_width_table_no_probe_is_named_for_is_refused_and_not_an_import_error	added.path not in under_test.PROBE_TABLES, which an empty tuple satisfies	under_test.PROBE_TABLES == (THE_HOLE,). The added table is not a probe table, and the one table that has a hole still is.
pin C: test_a_probe_given_the_width_that_has_none_empties_the_probe_tables	under_test.PROBE_TABLES == (), which is the value a total failure produces	(PROBE_TABLES, under_test.PROBE_TABLES) == ((THE_HOLE,), ()). The table is emptied by the probe, and it was not empty before the probe.
reimported_validate: "does not register it…"	held by nothing	assert importlib.import_module("atom.compass.spec.validate") is not module, in the helper, so both callers hold it
CA2: saved-transfer arm	nothing held which fragment is named	refused.what.startswith("'t.yaml' (machine ")
CA2m: stack-mismatch arm	nothing held which fragment is named	checked.refusals[0].what.startswith("'tier2' (machine ")

THE_HOLE is "device.runtime_constants.allocator_retained_after_load_bytes": the one width table that FILLED_BY leaves a probe hole in, at width 1.

Re-measured: all four items still reproduced at the tip

I measured on node 18 (xiaobizh_n18_cpu), over the whole of tests/compass, with 10 jobs.

• Each job is a fresh copy of a git archive tree, and atom.__file__ was under that job's own copy in all 10.
• Each mutant is one exact substring that occurs once, with the line count kept. The harness asserts both.
• CA2 and CA2m are the compass(spec): hold each refusal clause that names a machine, fragment, version or term #346 reviewer's mutants, copied byte for byte from pr346-review2/tools/mutate.py.

mutant	edit	tip 872edea12	head 064ac89bd	failing ids at the head that the tip does not have (all tests/compass/test_spec_verbs.py::)
none (null control)	none	1307 passed, green	1307 passed, green	none
PE: PROBE_TABLES forced empty	validate.py: PROBE_TABLES = tuple( → PROBE_TABLES = () and tuple(	6 F. Pin B and pin C both pass.	8 F	pin B, …refused_and_not_an_import_error: assert () == ('device.runt..._load_bytes',) pin C, …empties_the_probe_tables: assert ((), ()) == (('device.run..._bytes',), ())
REG: the helper registers under the canonical name	test file: exec_module(module) → exec_module(module); __import__('sys').modules['atom.compass.spec.validate'] = module	1307 passed, green	2 F	…refused_and_not_an_import_error and …empties_the_probe_tables, both on the helper's new is not module
CA2: saved arm blames listed[0] ('tier2')	reviewer's CA2	1307 passed, green	1 F	test_a_saved_transfer_merged_again_names_the_merge_that_dropped_its_pin, at the new startswith
CA2m: mismatch arm blames 'tier1'	reviewer's CA2m	1307 passed, green	1 F	test_a_transfer_keeps_the_source_stack_out_of_this_machines_pin, at the new startswith

The PE red is the same at both trees, apart from pin B and pin C. Six other ids catch PE at both trees:

• test_each_condition_in_the_check_set_is_earned_by_a_spec[whether a probe fills …]
• test_a_missing_entry_no_probe_fills_is_two_refusals_and_not_one
• test_the_check_does_not_agree_a_probe_exists_for_a_width_below_one
• test_the_probe_question_is_asked_of_the_tables_it_says_it_reads
• test_the_probe_question_reads_only_the_tables_a_probe_can_fall_short_on
• test_the_probe_question_says_it_could_not_be_asked_when_its_table_is_gone

The brief counted four of these at 80a508dff; the tree has grown since. As the brief said, the tree was covered, and the hole was in these two pins.

Gate 1: ATOM's CPU tier, unmodified, against a measured control

• Merged tree: git merge-tree --write-tree 872edea12 064ac89bd gives f1ce8b3d47a69906b1c3ffcf1a51944dbe98821d, rc 0. That equals the head's tree, because the head's parent is the tip.
• Stamp: git commit-tree gives 0c2a2efa8, with parents the tip and the head. .compass-changed lists the one test file. scripts/compass is tree bc0d1dc99 on both sides.
• How it ran:
  • staged with git archive, then shipped over docker exec -i into /tmp/i231 and extracted with tar -x. The tar md5 matched on both ends;
  • the tree's own gate_cpu.sh, under timeout -k 10 2400, unpiped;
  • one gate at a time.

tree	printed commit:	printed atom:	passed	skipped	xfailed	GATE_CPU_RC
merged	0c2a2efa8 (stamp)	/tmp/i231/stage/merged/ATOM/atom/__init__.py	5263	155	3	0
control, tip	872edea12 (stamp)	/tmp/i231/stage/tip/ATOM/atom/__init__.py	5263	155	3	0

• junit: 5421 cases on each side. No id is only on one side, and no outcome changed. That is expected, because the PR adds no test ids.
• Timing classes (TestTheRegionIsNotCopiedPerChunk, …[minimax], test_freezing_twice…): 17 cases on each run, all passed, so none needed a re-run.
• Lint: ruff 0.16.7 check and format --check pass on the file, as does black 26.5.1 --check. The file has no design-doc references and no #NNN.

Dev record

• Pin B's old assertion was dropped rather than kept beside the new one. == (THE_HOLE,) implies added.path not in …, because the added path is not THE_HOLE.
• The docstring sentence is held, not rewritten. The helper asserts its own claim after exec_module, so both callers go red by their own ids when it breaks. The sentence's consequence is that "the instance the rest of the suite is holding is the one it started with". The assertion checks exactly that, through the canonical import_module.
• Nothing surprised me, and nothing was left undone. Effort was 15 changed lines against an estimate of 15–30.

🤖 Generated with Claude Code

[jgong5]

Non-blocking, R1-1: the needle stops just before the part of the stanza that differs between fragments.

Principle 6: "A declined answer with a named reason is a result. A guessed one is a defect." The rule: "A check counts only once someone has seen it fire."

't.yaml' (machine holds the source name. (machine …) is the same for every fragment, because _one_machine enforces that. After it, the stanza renders the method, author and date, and in these fixtures the method is the field that tells fragments apart.

Mutant CA2L. The saved arm keeps fragment.source, but the rest of its stanza comes from merged.fragments[-1] ('links'). It is one line, the line count is kept, and the file is atom/compass/spec/validate.py. Here is the text it produces, probed on node 18:

't.yaml' (machine 'mi355x-8gpu-2node', probed, by a person on 2026-09-18) carried constants over from 'mi300x-8gpu', and its provenance names ...

It says a probed fragment carried constants over. That contradicts itself: the real stanza reads transferred-from:mi300x-8gpu.

Result: tests/compass, head 064ac89bd, 1307 passed, 0 failed. The null control is also 1307 passed. At the tip it is 1307 passed as well.

A fix of the same shape as your first_hand control a few lines below:

    assert refused.what.startswith(
        "'t.yaml' (machine 'mi355x-8gpu-2node', transferred-from:mi300x-8gpu, "
        "by a person on 2026-09-18) carried constants over from "
    )

The needle you have does what the brief asked, and it reddens the #346 reviewer's CA2 (0 F at the tip, 1 F at the head). So this finding is non-blocking. If it is not taken here, it needs a follow-up issue. The same gap is in the mismatch arm (R1-2).

[jgong5]

Non-blocking, R1-2: same as R1-1, in the stack-mismatch arm.

Principle 6, and the rule "A check counts only once someone has seen it fire."

Mutant CA2mL. The mismatch arm keeps fragment.source, and renders the rest of the stanza from merged.fragments[-1]. The text it produces, probed on node 18:

'tier2' (machine 'mi355x-8gpu-2node', probed, by a person on 2026-09-18) carried constants over from 'mi300x-8gpu', measured against rocm '7.0.2', into a spec pinned to rocm '7.2.4'

Result: head 064ac89bd, 1307 passed, 0 failed. The endswith below pins everything after the stanza, and this startswith pins everything up to (machine . That leaves exactly the method, author and date free.

The fix: extend the needle through the method, "'tier2' (machine 'mi355x-8gpu-2node', transferred-from:mi300x-8gpu, by a person on 2026-09-18) carried ". With that, startswith plus endswith together cover the whole string.

This is non-blocking for the same reason as R1-1: the #346 reviewer's CA2m is red at the head (1 F) and green at the tip.

[jgong5]

Non-blocking, R1-3: the new assertion holds half of the docstring's sentence.

Principle 8: "Every claim carries its measurement."

The docstring (L2002) says the helper "does not register it". The assertion holds a narrower claim: that the helper does not register the module under the canonical name.

Mutant REGown. It changes exec_module(module) to exec_module(module); __import__('sys').modules[loaded.name] = module, which registers the module under its own name. The line count is kept.

Result: head 064ac89bd, 1307 passed, 0 failed. For comparison, your REG mutant, which registers under the canonical name, gives 2 F by both callers' ids, and it is green at the tip. I reproduced that too.

The consequence clause is held. "the instance the rest of the suite is holding is the one it started with" is exactly what import_module(...) is not module checks.

It cannot pass for the wrong reason in this file. The canonical module is imported at collection, by L57–68. I probed that "atom.compass.spec.validate" in sys.modules is True at the call, so import_module returns the suite's instance and never imports a fresh one.

Two one-line fixes: narrow the sentence to "does not register it under the package's name", or add assert loaded.name not in sys.modules. The first costs no import.

[jgong5]

Review cycle 1, PR #357 (issue #231): APPROVE at head 064ac89bd2a9b14cfb1475fffcbda1bd6ba3cb11

This review is agent-authored.

No blocking issues. There are three non-blocking findings, posted inline: R1-1 (L601), R1-2 (L568) and R1-3 (L2011/L2002).

Every pin this PR claims fires. I reinstated each defect at the head and at the tip, and they redden by their own ids. That satisfies the rule "A reviewer credits a test with holding a defect only after reinstating it … An inert pin on a required finding blocks APPROVE." The three findings are narrower mutants that the required findings did not name.

1. Mutation table, reproduced on node 18

Setup:

• Where: xiaobizh_n18_cpu.
• Suite: tests/compass.
• Staging: each job is a fresh copy of a git archive tree, and atom.__file__ was under that copy in all 17 jobs.
• Mutants: each is one exact substring, and the line count is kept. The developer's harness is copied, and extra mutants are added.
• CA2 and CA2m are byte-identical to pr346-review2/tools/mutate.py. I checked that with diff.

mutant	tip 872edea12	head 064ac89bd	ids at the head beyond the tip (tests/compass/test_spec_verbs.py::)
none	1307 passed	1307 passed	none
PE: PROBE_TABLES forced empty	6 F. Pin B and pin C both pass.	8 F	test_a_width_table_no_probe_is_named_for_is_refused_and_not_an_import_error: assert () == ('device.runt..._load_bytes',) test_a_probe_given_the_width_that_has_none_empties_the_probe_tables: assert ((), ()) == (('device.run..._bytes',), ())
REG: the helper registers under the canonical name	1307 passed	2 F	both of the tests above, at the helper's is not module
CA2: #346's mutant	1307 passed	1 F	test_a_saved_transfer_merged_again_names_the_merge_that_dropped_its_pin
CA2m: #346's mutant	1307 passed	1 F	test_a_transfer_keeps_the_source_stack_out_of_this_machines_pin
HARD: PROBE_TABLES hard-coded to (THE_HOLE,)	not run	1 F	…empties_the_probe_tables. Pin C still holds the other direction.
CA2L: see R1-1	1307 passed	1307 passed	none. It survives.
CA2mL: see R1-2	not run	1307 passed	none. It survives.
REGown: see R1-3	not run	1307 passed	none. It survives.
LEG: a second probe hole	5 F	6 F	…refused_and_not_an_import_error. See 2a.

The PE red is the same set at both trees, apart from pins B and C. Six older ids catch PE at both trees:

• test_each_condition_in_the_check_set_is_earned_by_a_spec[whether a probe fills …]
• …two_refusals_and_not_one
• …asked_of_the_tables_it_says_it_reads
• …width_below_one
• …reads_only_the_tables_a_probe_can_fall_short_on
• …could_not_be_asked_when_its_table_is_gone

These match the PR body's table in every cell.

2. Inertness checks

(a) Pin B's == (THE_HOLE,). It does break when a second hole is legitimately added. I tested that with mutant LEG, which sets driver_and_collective_reserve_bytes to (None, MULTI_RANK).

• Pin C was already brittle to this at the tip. Its setup fills only the allocator term, so the tip gives 5 F, including pin C.
• Pin B is the one extra id at the head. It fails with assert ('…allocator_retained…', '…driver_and_collective_reserve…') == ('…allocator_retained…',), and pytest's diff says the left side has one more item.
• The literal is the price of catching PE. A derived expectation such as == PROBE_TABLES is () == () under PE, which is inert. THE_HOLE's comment names it as "the one width table a probe falls short on", so the reader of a red knows what changed.
• Verdict: intended and clear. Not a finding.

(b) The helper's import_module(...) is not module. It cannot pass for the wrong reason in this file.

• The canonical module is imported at collection, by L57–68.
• I probed at the helper's call: "atom.compass.spec.validate" in sys.modules is True. So import_module returns the suite's instance and never imports a fresh one.
• REG reddens it.
• Residual: REGown, which registers the module under its own name, survives. See R1-3.

(c) The startswith needles. Both aim at the source name that the refusal gives the fragment, and both redden #346's mutants.

• The gap: a mutant that keeps the prefix but renders the rest of the stanza from another fragment ('links', method probed) survives both arms. That is R1-1 and R1-2.
• Why only these fields: the machine is shared by construction, so the method, author and date are the fields left unpinned.

3. Truth checks (principle 8)

sentence	true?	held by
L1992: "The one width table a probe falls short on, the retained bytes at width 1."	yes. FILLED_BY has one None, allocator_retained_after_load_bytes at width 1.	PE, HARD and LEG each redden a pin
L2029–30: "A table with no entry has no hole to report, so it is not a probe table, and the table that has one still is."	yes. FILLED_BY.get(…, ()) has no None.	PE, LEG
L2056: "Emptied by the probe, and not empty before it."	yes. PROBE_TABLES is the suite's instance, derived before monkeypatch.setitem.	PE, HARD
L2002: "does not register it"	only the canonical-name half is held	R1-3

PR-body claims:

• The mutation counts all reproduce.
• The merged tree equalled the head tree at 872edea12. That is still so there, but the tip has moved (see 5).
• ruff 0.16.7 check and format --check pass on the file at the head.
• The file has no #NNN, D<n> or "principle N" references.

4. ponytail-review

L1992–1993 THE_HOLE: two uses. The literal is required, because a derived value is inert under PE (2a). It stays.
L2011: a single assert self-check, the minimum, so it is not flagged.
L2029–2031 and L2056–2057: each replaces the assertion it widens, and neither adds a line of logic.

Lean already. Ship.

5. Gate 1: the merged tree at the current tip

The tip moved during the review, from 872edea12 to 6987b0716 (#356, docs only: atom/compass/design/08_validation_protocol.md and scripts/compass/README.md). So the tree that would land is no longer the head's tree.

tip	git merge-tree --write-tree <tip> 064ac89bd	stamp (commit-tree, parents tip and head)	printed commit: / atom:	passed	skipped	xfailed	GATE_CPU_RC
6987b0716 (current)	56eed69318448e0a5117533420f74f70eb203ed1, rc 0. It is not the head tree f1ce8b3d4.	f86a69c35	f86a69c35 (stamp) / /tmp/p357r1/stage/merged/ATOM/atom/__init__.py	5263	155	3	0
872edea12 (read first)	f1ce8b3d4…, which is the head tree	d6eac713d	d6eac713d (stamp) / same path	5263	155	3	0

How it ran:

• the tree's own scripts/compass/gate_cpu.sh, where scripts/compass is tree bf85ab6e4 at the new tip;
• under timeout -k 10 2400, unpiped, one gate at a time;
• .compass-changed lists only tests/compass/test_spec_verbs.py.

What the junit shows: 5421 cases, and nothing outside passed or skipped. The 17 timing-class cases (TestTheRegionIsNotCopiedPerChunk, …[minimax], test_freezing_twice…) all passed, so none needed a re-run.

The control count: 5263 equals the developer's measured tip control at 872edea12. The only change between the two tips is two documentation files, and the gate at 6987b0716 was green at the same count. Land against tree 56eed6931.

Non-blocking findings (inline)

• R1-1 (L601) and R1-2 (L568): extend each needle through the stanza's method, the way first_hand already does. Each fix is one line.
• R1-3 (L2002/L2011): narrow the sentence to "under the package's name", or assert loaded.name not in sys.modules.

If these are not taken in this PR, they need one follow-up issue.

Next action: land at 064ac89bd against merged tree 56eed6931.