compass(docs): drop the redundant RapidServe ordering clause and agree the substitution citations

[jgong5]

Closes #400

Drops the ordering clause and two line citations that #397 added, and makes the design docs cite the RapidServe runner substitution one way. Comment and doc only: 3 files, +11/-13.

Changes

• atom/compass/runner/overrides.py (comment only), design 01 near L944.
  • Dropped the ordering clause: "LLMEngine builds that Config (llm_engine.py:43) before either class" and "before LLMEngine.__init__ constructs any engine core".
  • Dropped the config.py:1737-1745 citation. Each passage now ends at "RAPIDSERVE_RUNNERS, this one included." / "is in RAPIDSERVE_RUNNERS."
• The substitution is now cited as config.py:1730-1736 everywhere. It had been cited three ways: 1727-1736, 1729-1736 and 1730-1736.
  • 01:51 and 02:39 cited a bare line range with no symbol. They now also name Config.__post_init__, following the Config.runner_qualname (atom/config.py:1595) style used in the same sentences.
  • 01:944's sentence already names RapidServeModelRunner, runner_qualname and Config, so it only gets the corrected range.
• The runner_qualname read is now cited as engine_core.py:128, not :129, at 01:49 and 01:1417 (the Sources list repeats the same citation).

Citation table (every citation touched, resolved at tip b80ee8ac4)

atom/config.py, atom/model_engine/engine_core.py and atom/model_engine/llm_engine.py are identical at the tip and the head.

Where (head)	Citation	Code at the tip
01:49, 01:1417	engine_core.py:128 (was :129)	:128 is config.runner_qualname,, the third argument of self.runner_mgr = AsyncIOProcManager( (:125-130). :129 is config,.
01:51	Config.__post_init__, config.py:1730-1736 (was 1729-1736)	:1730 if ( · :1731 self.enable_rapidserve · :1732 and self.runner_qualname == "atom.model_engine.model_runner.ModelRunner" · :1733 ): · :1734 self.runner_qualname = ( · :1735 "atom.model_engine.model_runner.RapidServeModelRunner" · :1736 ). The enclosing def is def __post_init__(self): at :1670. :1727-1729 is the comment above the statement, which is why neither start line was exact.
01:944	config.py:1730-1736 (was 1727-1736)	same as above
02:39-40	Config.__post_init__ (config.py:1730-1736) (was config.py:1729-1736)	same as above
overrides.py:117	config.py:1730-1736 (unchanged, re-checked)	same as above
01:945, overrides.py:120	config.py:1737-1745 removed	:1737 if self.enable_rapidserve and self.runner_qualname not in RAPIDSERVE_RUNNERS:. The sentence names RAPIDSERVE_RUNNERS, and config.py:2102 defines it.
overrides.py:121	llm_engine.py:43 removed with its clause	:43 config = Config(model, **config_kwargs)

The remaining sentences are still true.

• Config raises ValueError under enable_rapidserve=True for a runner not in RAPIDSERVE_RUNNERS (config.py:1737-1738).
• RAPIDSERVE_RUNNERS is frozenset({"atom.model_engine.model_runner.RapidServeModelRunner"}), so the Compass runner is included.
• The dropped ordering clause was true when it was removed. compass(docs): say that Config refuses enable_rapidserve with a non-RapidServe runner #397's review probe (engine-core-level recorder, seen firing on a mutant) confirmed it, so dropping it loses no truth.

No test or script pins any string that changed. I grepped tests/ and scripts/ for 1729-1736, 1727-1736, 1737-1745, engine_core.py:129 and llm_engine.py:43, and none of them match.

Named result

• Every citation touched resolves to the named code at the tip. See the table above.
• The overrides.py AST is identical once comments and docstrings are masked.
  • Method: ast.dump of b80ee8ac4:atom/compass/runner/overrides.py compared with the head, after stripping the leading string Expr from every module, class and function body.
  • Base sha256 prefix: 701ad09fe38cf2ae. Head: 701ad09fe38cf2ae. identical: True.
  • Positive control: changing RPC_SURFACE: dict[str, bool] to dict[str, int] gives identical: False.
• Suite delta 0. See Gate 1.

Gate 1 (node 18, xiaobizh_n18_cpu)

• Tip. b80ee8ac4 (compass(tests): pin RAPIDSERVE_RPCS to the RapidServe cores waited broadcasts #396), re-read from fork/feature/atomcompass_new before gating.
• Merged tree. git merge-tree --write-tree b80ee8ac4 1d0811038 gives facede62a, which equals 1d0811038^{tree}. The stamp is therefore the head itself: .compass-commit = 1d0811038, .compass-changed = the 3 PR files.
• Staging. git archive into a tarball, docker exec -i … cat into /tmp/i400gate/ in xiaobizh_n18_cpu, md5 cc74986f… matching on both ends, then tar -x. The shared mount was not touched.
• Run. The tree's own scripts/compass/gate_cpu.sh, run with timeout -k 10 3000, unpiped, and started only after pgrep -fc "[g]ate_cpu.sh" returned 0.

tree	commit:	atom:	passed	skipped	xfailed	failed	GATE_CPU_RC
tip b80ee8ac4 (given baseline)			5276	155	3	0	0
merged = head 1d0811038	1d0811038 (stamp)	/tmp/i400gate/ATOM/atom/__init__.py	5276	155	3	0	0 PASSED

The delta is 0 on every count. The run took 187.3 s. None of the three known flakes fired, so no re-run was needed.

Dev record

• Decided. I named Config.__post_init__ only where a citation stood alone as a bare range (01:51, 02:39). At 01:944 and in overrides.py the sentence already names the symbols, so they keep only the range. The compass(docs): say that Config refuses enable_rapidserve with a non-RapidServe runner #397 reviewer judged the range to be overrides.py's house style, since every RPC_SURFACE entry cites engine_core.py:NNN.
• Left alone. Two citations sit in the file set and were checked, but not changed:
  • 02:37's engine_core.py:125-130 is the whole AsyncIOProcManager(...) call, and it contains :128.
  • 01:120's engine_core.py:125 cites the AsyncIOProcManager construction, not the read.
• Gate 2 does not apply. The change is comments and docs and adds no behaviour.

🤖 Generated with Claude Code

[jgong5]

Review cycle 1: PR #404 (issue #400), head 1d08110389c62c4a2d2773dd508fcedb7dd448a8

Agent-authored review. I read the eight design principles in atom/compass/design/README.md and atom/compass/AI_DEV_RULES.md at tip 37fba4df0 first.

Verdict: APPROVE at 1d08110389c62c4a2d2773dd508fcedb7dd448a8. No findings block this PR. There is one non-blocking note, and it is about the issue thread, not the diff.

1. Citation checks, resolved at tip 37fba4df0

atom/config.py and atom/model_engine/ are identical at b80ee8ac4 and 37fba4df0. #391 touched only atom/compass/kv/handoff.py.

Where (head)	Citation	Code at the tip	Result
01:49, 01:1417	engine_core.py:128	:128 is config.runner_qualname,, the third argument of self.runner_mgr = AsyncIOProcManager( (:125). :129 is config,.	exact
01:51, 01:944, 02:40, overrides.py:117	config.py:1730-1736	:1730 is if (, :1731 is self.enable_rapidserve, :1732 is and self.runner_qualname == "atom.model_engine.model_runner.ModelRunner", :1733 is ):, :1734 is self.runner_qualname = (, :1735 is "atom.model_engine.model_runner.RapidServeModelRunner", and :1736 is ). :1727-1729 is the comment above, and :1737 starts the RAPIDSERVE_RUNNERS refusal.	spans exactly the substitution
01:51, 02:39	Config.__post_init__	@dataclass at :1504, then class Config: at :1505 and def __post_init__(self): at :1670. No other def sits between :1670 and :1730.	correct enclosing method

I found four sites that cite the substitution, not five. The PR body's table also lists four, while the issue comment says "all five places". Every site reads 1730-1736.

Missed-citation search over the whole head tree (git grep at 1d0811038):

• 1729-1736|1727-1736|1737-1745|engine_core\.py:129|llm_engine\.py:43\b has zero hits anywhere, including tests/ and scripts/.
• config\.py:1[67]NN has the four sites above, plus 15:437 config.py:1677-1681, which is a different refusal (mega without EP).
• A search for the ordering phrase (before (any|either) (engine core|class), constructs any engine core, builds that Config) has zero hits.
• Other engine_core.py:12x citations: 01:120 engine_core.py:125 names the AsyncIOProcManager construction, and 02:37 engine_core.py:125-130 spans the whole call, which contains :128. Both are correct and outside the brief.

Rule: "Do not write 'checked' unless the check you ran is the one that answers the claim." Principle 8: "Every claim carries its measurement." Each claim is matched to the quote above it.

2. Paragraph re-reads (every edited paragraph, in full)

• 01:48-51 ("The seam needs no ATOM change."): grammatical. The two precedents now read file:range for RLHF and symbol plus range for RapidServe. Both parentheticals resolve.
• 01:934-947 (the struck time.sleep(2) item). The paragraph ends: "Config keeps a simulated runner from it: --enable-rapidserve selects RapidServeModelRunner only when runner_qualname is still the default (config.py:1730-1736), and otherwise Config raises ValueError unless runner_qualname is in RAPIDSERVE_RUNNERS. The cost, for a runner that list names, is two real seconds…" It is true as written:
  • With the default runner, the substitution installs a runner that is in the set (config.py:2102 RAPIDSERVE_RUNNERS = frozenset({"…RapidServeModelRunner"})).
  • With any other runner, :1737-1738 raises unless the runner is listed.
  • "Keeps … from it" still needs the ordering, and "Config raises" carries it: Config is built at llm_engine.py:43 before any core. So the removed clause took no truth with it, and nothing dangles.
• 01:1416-1418 (Sources, "The seam"): single-token change, grammatical.
• 02:37-41: "Config.__post_init__ (config.py:1730-1736) swaps in RapidServeModelRunner automatically" is grammatical and true ("automatically" means under enable_rapidserve with the default qualname, and the range shows the condition).
• overrides.py:109-120 (Scope comment): now ends "Config therefore raises ValueError for enable_rapidserve=True with any runner not in RAPIDSERVE_RUNNERS, this one included." It is grammatical and true, since the Compass runner is not in the frozenset. git diff -U0 b80ee8ac4 1d0811038 -- atom/compass/runner/overrides.py has 0 changed lines that do not start with #, which is consistent with the developer's masked-AST identity. The comment carries no design-doc references. Rule: "No design-doc references in code or runtime output."

3. ponytail-review

Comment and doc only, 3 files, +11/-13. The diff is itself the ponytail cut #397's review asked for (net: -2). It adds one symbol name at two bare ranges, which the brief requested ("Prefer naming the symbol where the doc's style allows it"). There is nothing further to delete, inline or shrink. Principle 3: "Add only what is necessary, and nothing more."

Lean already. Ship.

4. Gate 1 (node 18, xiaobizh_n18_cpu)

• Tip: 37fba4df0 (compass(kv): whole_number Limits name the value, its dtype, or a returned object as where an escape comes from (#390) #391), re-read with git ls-remote before gating and again before posting.
• Merged tree: git merge-tree --write-tree 37fba4df0 1d0811038 gives 2f3c56c55. That is not the head tree facede62a, because the tip moved. So I gated the merged tree.
• Stamp: git commit-tree 2f3c56c55 -p 37fba4df0 -p 1d0811038 gives 9d793a957, which is not pushed and has no ref. .compass-changed holds the 3 PR files.
• Staging: git archive of the stamp, a tarball, then docker exec -i … cat into /tmp/r404gate/. The md5 eeb563ad… matched on both ends. The shared mount was untouched.
• Run: the tree's own scripts/compass/gate_cpu.sh with timeout -k 10 3000, unpiped. It started only after pgrep -fc "[g]ate_cpu.sh" returned 0 (after compass(tests): SITES filters broadcast sites on the bare name engine_core.py, which a diffusion file shares #401's gates cleared).

tree	commit:	atom:	passed	skipped	xfailed	failed	GATE_CPU_RC
developer, merged = head at b80ee8ac4	1d0811038	/tmp/i400gate/ATOM/atom/__init__.py	5276	155	3	0	0
reviewer, merged at 37fba4df0	9d793a957 (stamp)	/tmp/r404gate/ATOM/atom/__init__.py	5276	155	3	0	0 PASSED

The run took 187.85 s. None of the three known flakes fired. The gate stands for tip 37fba4df0. If the tip moves again before landing, the lander's tree check applies.

Findings

• N1 (non-blocking, issue thread only). The compass: drop the redundant ordering clause and line citations #397 added, and make design-doc citations of the RapidServe substitution agree #400 delivery comment says the substitution "is cited as config.py:1730-1736 in all five places". There are four sites: 01:51, 01:944, 02:40 and overrides.py:117. The PR body's table correctly lists four. A one-word correction in the handoff comment is enough, and the diff needs no change. Principle 8: "A number without a source is a defect."

Gates 1-3 as they apply: gate 1 is green, as above. Gate 2 does not apply, because the change is comment and doc only and adds no behaviour. Gate 3's named result is met: every touched citation resolves, the masked AST is identical, and the delta is 0. This review is gate 4.