compass(kv): state whole_number union case in two lines under Limits

[jgong5]

Closes #403

Change

atom/compass/kv/handoff.py, whole_number's docstring only: the Limits paragraph's first sentence goes from three lines to two, in the form the #391 cycle-2 reviewer proposed in N1.

-    Limits: the dtype text test also refuses a whole number whose dtype text
-    has "bool", such as a 0-d array of a numpy union dtype with a field
-    "is_bool", and the message then says it is not a whole number. An
+    Limits: a whole number whose dtype text has "bool", such as a 0-d array
+    of a numpy union dtype with a field "is_bool", is refused as not one. An

Net -1 line (119 -> 118). Line widths 75 and 76. ruff check and black --check on the file: both pass.

Dev record

Every clause of the whole docstring was probed on node 18, on the merged tree d46e0c0de (tip 37fba4df0 + head 0a152711f; merge-tree equals the head's tree 8f54c94b4), with atom.__file__ under the staged root. numpy 2.4.6, torch 2.10.0+rocm7.2.4, Python 3.12.3. The probe is the #391 cycle-2 reviewer's, extended; it is at agent_scratch/compass_dev/issue-403/probe.py. "Branch fired" is from an instrumented copy of the function. The last column is a copy of the function with the dtype-text test removed.

The three things the brief asked about:

1. "is refused as not one" matches the message. For every union-case row the message is tp_size is <repr>, which is not a whole number; a parallel width or rank is a count, so it is refused rather than converted. The probe compares it character for character. For example: tp_size is array(8, dtype=(numpy.int64, [('is_bool', '<i8')])), which is not a whole number; ....
2. The dropped words carry no fact the rest does not.
   • "the dtype text test also": in every union-case row the only branch that fires is the dtype-text test. The kept condition, "whose dtype text has "bool"", is the same condition the Refused paragraph gives that test ("anything whose dtype has "bool" in its text").
   • "the message then says it is not a whole number": "as not one" carries it (point 1).
3. The first two paragraphs, the Refused paragraph and Limits sentence 2 are identical to the tip (the probe compares the paragraphs parsed from the docstring), and each clause in them still measures true (tables below), including the second paragraph's three claims about ATOM's launch path (probe2.py).

Not a finding, recorded for the reviewer. An int subclass whose dtype.__str__ returns a str subclass that holds the text "bool", but whose in answers False, is accepted. That contradicts "a whole number whose dtype text has "bool" ... is refused" if "text" is read as the characters. The tip's sentence makes the same claim ("the dtype text test also refuses a whole number whose dtype text has "bool"") and gets the same result, so this PR does not introduce it. A dunder that lies can falsify any clause here, the tip's "No value that is accepted changes on the way" included; Limits sentence 2 covers dunders that raise, not dunders that lie.

Correction to the commit message. It says the kept condition is the Refused paragraph's "word for word". It is the same condition, but not the same words: the Refused paragraph says "anything whose dtype has "bool" in its text". The branch only gains commits, so this is corrected here rather than amended.

AST with docstrings masked: identical to the tip (masked AST head == tip: True). Unmasked it differs, as expected. To show the masking is not vacuous, three code mutants make the masked AST differ from the tip: dropping OverflowError, "bool" -> "Bool", and changing the message text. A docstring-only mutant does not.

Probe table (node 18, merged tree d46e0c0de)

Columns: clause | input | whole_number | branch fired | copy without the dtype-text test.

Limits sentence 1 (the changed sentence)

clause	input	whole_number	branch fired	copy without the dtype-text test
L1 'a whole number whose dtype text has bool ... is refused as not one'	0-d is_bool/i8 holding 8	refused: 'not a whole number'	text	accepted int 8
L1 'a whole number whose dtype text has bool ... is refused as not one'	0-d is_bool/i8 holding 3	refused: 'not a whole number'	text	accepted int 3
L1 'a whole number whose dtype text has bool ... is refused as not one'	0-d is_bool/i8 holding 1	refused: 'not a whole number'	text	accepted int 1
L1 'a whole number whose dtype text has bool ... is refused as not one'	0-d is_bool/i8 holding 0	refused: 'not a whole number'	text	accepted int 0
L1 'a whole number whose dtype text has bool ... is refused as not one'	0-d is_bool/i8 holding -2	refused: 'not a whole number'	text	accepted int -2
L1 'a whole number whose dtype text has bool ... is refused as not one'	0-d is_bool/i8 holding 4611686018427387904	refused: 'not a whole number'	text	accepted int 4611686018427387904
L1 'a whole number'	0-d is_bool/i8 holding 8: str(dtype), kind, int(), int()==a	("(numpy.int64, [('is_bool', '<i8')])", 'i', 8, True)
L1 every such: f8 union	0-d is_bool/f8 holding 8.0	refused: 'not a whole number'	text	accepted int 8
L1 every such: c16 union	0-d is_bool/c16 holding 8+0j	refused: 'not a whole number'	text	refused: 'not a whole number'
L1 every such: i8 base, i4 fields	0-d ('i8',[is_bool i4, y i4]) holding 8	refused: 'not a whole number'	text	accepted int 8
L1 every such: field name	0-d union field 'boolean'/i8 holding 8	refused: 'not a whole number'	text	accepted int 8
L1 every such: not numpy	int subclass 8, dtype 'boolean'	refused: 'not a whole number'	text	accepted int 8
L1 'whole number' scope	0-d is_bool/f8 holding 8.5 (not whole)	refused: 'not a whole number'	text	refused: 'not a whole number'
L1 control	0-d union field 'x'/i8 holding 8	accepted int 8	-	accepted int 8
L1 control	plain np.array(8)	accepted int 8	-	accepted int 8
L1 control	structured 0-d [('is_bool','i8')] holding (8,)	refused: 'not a whole number'	text	refused: 'not a whole number'
L1 'dtype text' is str(dtype)	str(int64 dtype with metadata {'is_bool':1})	'int64'
L1 'dtype text' is str(dtype)	0-d int64 with metadata {'is_bool':1} holding 8	accepted int 8	-	accepted int 8
L1 adversarial (same claim at tip)	int sub 8, dtype str() is a str sub whose in answers False, text 'bool'	accepted int 8	-	accepted int 8

The message ("is refused as not one")

0-d is_bool/i8 holding 8: ValueError: tp_size is array(8, dtype=(numpy.int64, [('is_bool', '<i8')])), which is not a whole number; a parallel width or rank is a count, so it is refused rather than converted
0-d is_bool/i8 holding 0: ValueError: tp_size is array(0, dtype=(numpy.int64, [('is_bool', '<i8')])), which is not a whole number; a parallel width or rank is a count, so it is refused rather than converted
0-d is_bool/f8 holding 8.0: ValueError: tp_size is array(8., dtype=(numpy.float64, [('is_bool', '<f8')])), which is not a whole number; a parallel width or rank is a count, so it is refused rather than converted
np.bool_(True): ValueError: tp_size is np.True_, which is not a whole number; a parallel width or rank is a count, so it is refused rather than converted
8.5: ValueError: tp_size is 8.5, which is not a whole number; a parallel width or rank is a count, so it is refused rather than converted

Unchanged paragraphs: first paragraph, Refused, Limits sentence 2

clause	input	whole_number	branch fired	copy without the dtype-text test
Refused	np.bool_(True)	refused: 'not a whole number'	text	accepted int 1
Refused	np.array(True)	refused: 'not a whole number'	text	accepted int 1
Refused	torch.tensor(True)	refused: 'not a whole number'	text	accepted int 1
Refused	torch.tensor(False)	refused: 'not a whole number'	text	accepted int 0
Refused	True	refused: 'not a whole number'	isinstance	refused: 'not a whole number'
Refused	False	refused: 'not a whole number'	isinstance	refused: 'not a whole number'
Refused	8.5	refused: 'not a whole number'	-	refused: 'not a whole number'
Refused	'8'	refused: 'not a whole number'	-	refused: 'not a whole number'
Refused	None	refused: 'not a whole number'	-	refused: 'not a whole number'
Refused	float('inf')	refused: 'not a whole number'	-	refused: 'not a whole number'
Refused	float('nan')	refused: 'not a whole number'	-	refused: 'not a whole number'
Refused 'neither being a bool subclass'	issubclass(np.bool_, bool), issubclass(torch.Tensor, bool)	(False, False)
Refused 'dtype has bool in its text'	str(dtype): np.bool_, torch bool	('bool', 'torch.bool')
Refused 'int truncates'	int(8.5)	8
Refused 'int("8") is 8, not equal to "8"'	(int('8'), int('8') != '8')	(8, True)
first para 'an int as it is, a float with no fraction'	8	accepted int 8	-	accepted int 8
first para 'an int as it is, a float with no fraction'	8.0	accepted int 8	-	accepted int 8
first para 'an int as it is, a float with no fraction'	np.int64(8)	accepted int 8	-	accepted int 8
first para 'an int as it is, a float with no fraction'	np.float64(8.0)	accepted int 8	-	accepted int 8
first para 'an int as it is, a float with no fraction'	torch.tensor(8)	accepted int 8	-	accepted int 8
L2 'from the value'	__int__ raises RuntimeError	escapes RuntimeError: boom; same object: True	-	escapes RuntimeError: boom
L2 'from the value'	dtype property raises RuntimeError (int sub 8)	escapes RuntimeError: boom; same object: True	-	accepted int 8
L2 'from the value'	__ne__ raises (int sub 8)	escapes RuntimeError: boom; same object: True	-	escapes RuntimeError: boom
L2 'from its dtype'	dtype's __str__ raises	escapes RuntimeError: boom; same object: True	-	accepted int 8
L2 'object either returns, such as ne's result'	__ne__ returns obj whose __bool__ raises	escapes RuntimeError: boom; same object: True	-	escapes RuntimeError: boom
L2 'object either returns'	dtype __str__ returns str sub whose __contains__ raises	escapes RuntimeError: boom; same object: True	-	accepted int 8
L2 'AttributeError counts as no dtype'	dtype raises AttributeError (int sub 8)	accepted int 8	-	accepted int 8
L2 'AttributeError counts as no dtype'	dtype raises AttributeError('bool') (int sub 8)	accepted int 8	-	accepted int 8
L2 'can escape', -W error	1-d int64 [8]	refused: 'not a whole number'	-	refused: 'not a whole number'

Docstring and AST

paragraph count head/tip: 4 4
para 0 (*value*): head == tip: True
para 1 (An): head == tip: True
para 2 (Refused:): head == tip: True
para 3 (Limits:): head == tip: False
Limits sentence 2 head == tip: True
HEAD Limits s1: Limits: a whole number whose dtype text has "bool", such as a 0-d array of a numpy union dtype with a field "is_bool", is refused as not one.
TIP  Limits s1: Limits: the dtype text test also refuses a whole number whose dtype text has "bool", such as a 0-d array of a numpy union dtype with a field "is_bool", and the message then says it is not a whole number.
docstring lines head/tip: 21 22
__doc__ == get_docstring source (head): True

raw text differs from tip: True
masked AST head == tip: True
unmasked AST head == tip (expect False): False
mutant drop OverflowError: masked AST differs from tip: True
mutant 'bool' -> 'Bool': masked AST differs from tip: True
mutant message text: masked AST differs from tip: True
mutant docstring-only edit (control): masked AST differs from tip: False
line count of handoff.py head/tip: 118 119
PROBE DONE

Second paragraph: the launch-path clauses (probe2.py, same tree)

clause 'its CLI flags ... are parsed with int'	result
--tensor-parallel-size action type	returns <class 'int'>
--data-parallel-size action type	returns <class 'int'>
--pipeline-parallel-size action type	returns <class 'int'>
--data-parallel-size-local action type	returns <class 'int'>
parse -tp 8 -dp 2: types	returns ('int', 8, 'int', 2)
parse -tp 8.0	raises ArgumentError: argument --tensor-parallel-size/-tp: invalid int value: '8.0' (argparse)

clause 'ATOM_DP_RANK [is] parsed with int'	result
ATOM_DP_RANK='3': envs.ATOM_DP_RANK	returns 3
ATOM_DP_RANK='x': envs.ATOM_DP_RANK	raises ValueError: invalid literal for int() with base 10: 'x' at atom/utils/envs.py:27 "ATOM_DP_RANK": lambda: int(os.getenv("ATOM_DP_RANK", "0")),

clause 'its Config raises on a string width'	result
Config(model=M, tensor_parallel_size='8')	raises TypeError: '<=' not supported between instances of 'int' and 'str' at atom/config.py:1747 assert 1 <= self.tensor_parallel_size <= 8
Config(model=M, tensor_parallel_size=8) (control: fails later, elsewhere)	raises OSError: Repo id must use alphanumeric chars, '-', '_' or '.'. The name cannot (transformers hub lookup)
ParallelConfig(data_parallel_size='2')	raises TypeError: '<' not supported between instances of 'str' and 'int' at atom/config.py:934 if self.data_parallel_size < 1:
ParallelConfig(data_parallel_size=2) (control)	returns 2

Gate 1 (node 18, xiaobizh_n18_cpu)

The merged tree d46e0c0de (git merge-tree --write-tree 37fba4df0 0a152711f = 8f54c94b4, the head's own tree), staged by git archive into the container's /tmp, with stamps written. The gate's commit: line reads d46e0c0de (stamp), .compass-changed is atom/compass/kv/handoff.py, and atom.__file__ is under the staged root. The tree's own scripts/compass/gate_cpu.sh ran once, unpiped, under timeout -k 10 3000.

tree	passed	skipped	xfailed	GATE_CPU_RC
tip 37fba4df0 (from the brief)	5276	155	3	0
merged d46e0c0de	5276	155	3	0
delta	0	0	0

Wall time 188 s. No timing flake fired.

🤖 Generated with Claude Code

[jgong5]

Review cycle 1: APPROVE at head 0a152711fe9890d4e44b1ff1c4155e534361ae6a

No blocking findings. No non-blocking findings either. There are two rulings and one note for whoever next works on this docstring, all below.

I read the eight Design principles in atom/compass/design/README.md and atom/compass/AI_DEV_RULES.md at tip 37fba4df0 in full before reviewing. The tip has since moved to 3eb94cfa7, and the gate below was run against the new tip.

1. Every clause, measured on node 18

Setup. Container xiaobizh_n18_cpu. I staged the head by git archive into my own path in the container. atom.__file__ resolved under the staged root. Versions: numpy 2.4.6, torch 2.10.0+rocm7.2.4, Python 3.12.3.

Probe. I wrote my own probe at agent_scratch/compass_dev/pr408-review1/probe.py; it is not the developer's.

• "message exact" means str(e) == f"tp_size is {v!r}, which is not a whole number; a parallel width or rank is a count, so it is refused rather than converted".
• The last column is the function with only the dtype-text test replaced by False.

Changed sentence: "a whole number whose dtype text has "bool", such as a 0-d array of a numpy union dtype with a field "is_bool", is refused as not one."

input	str(dtype); int(v); int(v) == v	whole_number	without the dtype-text test
0-d union i8 is_bool, holding 8 / 1 / 0 / -3 / 2**62	(numpy.int64, [('is_bool', '<i8')]); itself; True	ValueError, message exact (all 5)	accepted as itself (all 5)
0-d union u1 is_bool, holding 8	(numpy.uint8, [('is_bool', 'u1')]); 8; True	ValueError, exact	accepted 8
0-d union f4 is_bool, holding 8.0	(numpy.float32, [('is_bool', '<f4')]); 8; True	ValueError, exact	accepted 8
0-d union i8, fields is_bool:i4 + pad:i4	shows both fields; 8; True	ValueError, exact	accepted 8
0-d union i8, field titled is_bool (name x)	(numpy.int64, [(('is_bool', 'x'), '<i8')]); 8; True	ValueError, exact	accepted 8
0-d union O (object) is_bool, holding 8	(numpy.object_, [('is_bool', 'O')]); 8; True	ValueError, exact	accepted 8
control: 0-d union i8, field x	no "bool"; 8; True	accepted 8	accepted 8
control: np.array(8)	int64; 8; True	accepted 8	accepted 8
a[()] of the 0-d union (an np.int64; the fields are dropped)	int64	accepted 8	n/a

Full message, for whole_number("tp_size", np.array(8, dtype=("i8", [("is_bool", "i8")]))):

tp_size is array(8, dtype=(numpy.int64, [('is_bool', '<i8')])), which is not a whole number; a parallel width or rank is a count, so it is refused rather than converted

"is refused as not one" matches it: "not one" = "not a whole number". The same holds for dp_rank holding 0. The raised error is ValueError with __context__ None: the internal TypeError does not leak into the chain.

The rest of the docstring. Paragraphs 1–3 and Limits sentence 2 are byte-identical to the tip (compared as parsed paragraphs). Every clause in them still measures true on this tree:

• 8, 8.0, np.int64(8) and torch.tensor(8) are accepted as 8.
• "8", 8.5, True, np.bool_(True), torch.tensor(True), None, inf and nan are all refused with the exact message.
• issubclass(np.bool_, bool) is False. The dtype texts are bool and torch.bool.
• A dtype property raising RuntimeError escapes as raised.
• AttributeError("bool") from dtype counts as no dtype, so the value is accepted.
• A __ne__ result whose __bool__ raises escapes as raised.
• The launch-path clauses I re-ran on the same staged tree:
  • the four parallel-size flags have type=int, and -tp 8.0 is refused by argparse;
  • ATOM_DP_RANK goes through int(...) at atom/utils/envs.py:27;
  • Config(tensor_parallel_size="8") raises TypeError at atom/config.py:1747;
  • ParallelConfig(data_parallel_size="2") raises at atom/config.py:934.

Format. The new lines are 75 and 76 columns wide. ruff check and black --check on the file both pass. The file goes from 119 to 118 lines.

2. AST identical with docstrings masked

I masked the first-statement string constant of every module, class and function, then compared ast.dump:

• masked head vs tip: True;
• unmasked: False, as it should be.

To show the masking is not vacuous, three code mutants make the masked AST differ from the tip, and a docstring-only mutant does not:

• OverflowError) -> ArithmeticError);
• "bool" in str -> "boo" in str;
• whole is None or -> whole is None and.

3. Rulings on the two flagged points

(a) The lying __contains__ case: not a finding for this PR.

The case is an int subclass holding 8 whose dtype.__str__ returns a str subclass with the characters bool and a __contains__ that answers False.

• It is accepted at the head, and it is accepted by the tip's code too. I measured both.

Neither "can escape" nor "such as" covers it.

• Limits sentence 2 is about exceptions, and this case raises nothing.
• "such as" introduces an example; it does not narrow the class.

So, read with "has" meaning the characters, sentence 1 is literally false for this object. But three things make it not a finding:

• The tip's sentence made the same claim ("the dtype text test also refuses a whole number whose dtype text has "bool"").
• The unchanged Refused paragraph makes it too ("anything whose dtype has "bool" in its text").
• The whole docstring, "No value that is accepted changes on the way" included, assumes dunders that answer honestly. x in s is Python's definition of "s has x" for a str. A __contains__ that contradicts the characters breaks the str protocol, not this sentence.

Guarding it would take a caveat about lying dunders across every paragraph. That is the opposite of principle 3, "Add only what is necessary, and nothing more", and nothing in ATOM produces such a dtype. No issue is needed.

(b) "word for word" in the commit message: nothing is needed on the branch.

The claim is loose. The Refused paragraph says "anything whose dtype has "bool" in its text", and Limits says "whose dtype text has "bool"". The condition is the same, but the words are not. The PR body already records the correction.

The branch must not be amended: AI_DEV_RULES says "PR branches only gain commits: no force-push, no rebase, no amend". A fix-up commit would only add a second message that is squashed away. The rule "PRs land squashed ... one commit per task with a written message" means the lander writes the squash message from scratch. The lander should not carry the "word for word" sentence into it. "the same condition as the Refused paragraph" is accurate.

4. ponytail-review (diff: handoff.py L101–102, -3/+2 docstring lines)

No over-engineering in the diff:

• It deletes words and adds no code, abstraction, config or dependency.
• Dropping the sentence entirely would make the Refused paragraph read as though the dtype-text test hits only booleans. The sentence records that the test overreaches, which is a real limit, so it is not a delete:.
• The such as example is the measured case behind the claim (principle 8: "Every claim carries its measurement"), so it is not a shrink:.

Lean already. Ship.

5. Gate

The tip moved from 37fba4df0 to 3eb94cfa7 (#404: two design docs and atom/compass/runner/overrides.py, -1 line). git merge-tree --write-tree 3eb94cfa7 0a152711f = 901ef6de8, which is not 8f54c94b4, so the developer's gate does not carry over.

I gated the new merged tree once:

• stamped as 3652b3ec3 via git commit-tree, with no ref;
• diff tip..stamp touches only atom/compass/kv/handoff.py;
• staged by git archive, tar md5 matched on both ends, atom.__file__ resolved under the staged root;
• run with the tree's own scripts/compass/gate_cpu.sh, unpiped, under timeout -k 10 3000.

The gate's own line reads commit: 3652b3ec3 (stamp). It ran for 206 s, and no timing flake fired.

tree	passed	skipped	xfailed	GATE_CPU_RC
developer: merged d46e0c0de (tree 8f54c94b4, tip 37fba4df0)	5276	155	3	0
reviewer: merged 3652b3ec3 (tree 901ef6de8, tip 3eb94cfa7)	5276	155	3	0
delta	0	0	0

Gate 1 holds on the tree that will land.

Note for the next task in this area (not a finding)

An int subclass holding 8 whose dtype.__str__ returns a non-str is refused with the exact message. The TypeError from str() is caught, so it becomes this refusal instead of escaping.

This makes no sentence false: Limits sentence 2 says such an exception "can escape", not that it must. It is unchanged from the tip. Like (a), it needs a dunder that breaks its protocol.

---

Reviewed head: 0a152711fe9890d4e44b1ff1c4155e534361ae6a. Verdict: APPROVE. The gate above covers the tree that lands on tip 3eb94cfa7.