compass(design): metrics push and refresh are daemon timers on simulated time; fix two stale doc-01 statements

[jgong5]

Closes #535. Closes #577. Ready for review. No blocking issues.

The execution and time model, the metrics doc, the design README and the sync inventory now agree that the metrics push, refresh and scrape are daemon timers on simulated time (owner ruling 2026-10-02), and the time model no longer describes two Atomesh timeouts as constants or names a deleted test.

Dev record

• Found: compass(design): doc 01 D1-D3.5 protocol to HLA-style PDES grants #446 had already done the time-model rows of compass(design): metrics cadence on simulated time, and the all-waiting state is the finish #535 except uvicorn's tick. The K7 mechanism on the three inventory rows was already right.
• Decided: the three inventory rows keep category: ignore and their first why (owner review); K7 already carried the ruling, and mechanism_why now names the daemon timer on simulated time.
• Decided: the metrics decision keeps its first version's reasons in a table, each with why it no longer holds.
• Surprised: the design README still summarised the metrics doc as "both metrics clock reads stay real"; fixed here (outside the issue's file set).
• Left undone: in code, only the refresh is a daemon timer today (DAEMON_TIMERS in atom/utils/compass_loop.py); the engine push joins t_daemon with compass(engine): TAR and NER in the step loops, engine timers on the virtual clock, and the I2 lock guard #460 and the traffic-LP scrape with compass: the vertical slice on the PDES runtime — one request end to end at TP1, three LPs, co-hosted CA #472, both open. The docs state the decision.

Named result

None: documentation and a data file (#535, #577).

Gates

branch @ 9ac55a06c (tree 5c7ead12c), scripts/compass/gate_cpu.sh on node 18: 5811 passed, 155 skipped, 3 xfailed, 0 failed, GATE_CPU_RC=0. No Python file changed, so ruff has nothing to check.

Evidence

• Inventory test at 9ac55a06c: tests/compass/test_sync_inventory.py 31 passed.
• Revert-red: the engine_core.py push anchor's mechanism_why emptied: test_sync_inventory.py::test_every_mechanism_agrees_with_the_rest_of_its_row fails with atom/model_engine/engine_core.py:320: the mechanism is not the one its category named; say why. That keeps the row consistent; it is not a behaviour pin (data and prose only).
• Cost: zero AST statements; +60/-50 physical lines against the tip, against an estimate of about 46 (compass(design): metrics cadence on simulated time, and the all-waiting state is the finish #535 about 40, design: doc 01 describes two Atomesh timeouts as constants and names a deleted test (found in #575) #577 about 6).

Generated with Claude Code

[jgong5]

Finding 3. The ruling changes what a simulated run does at these sites, which mechanism (K7) already said before this PR; moving category to C2 adds the file's only exception to its own history rule and overwrites the first classification's why. Keep category: ignore and the original why on the three rows, put the daemon wording in mechanism_why, and drop this clause. That form passes tests/compass/test_sync_inventory.py (31 passed at this head).

[jgong5]

Round 2 pushed 9ac55a06c: the three rows keep category: ignore and their original why; mechanism_why now says the cadence is a daemon timer on simulated time, and the history exception is gone. tests/compass/test_sync_inventory.py: 31 passed.

[jgong5]

Finding 3: the same exception as the history field in sync_sites.json. Drop it with that change.

[jgong5]

Round 2 pushed 9ac55a06c: the exception is dropped; atom/compass/audit/README.md is byte-identical to the tip again.

[jgong5]

Review round 1. Verdict: CHANGES NEEDED at head cb6cf3225dba358462031a8ff601cb2ab7bfb459. REQUEST CHANGES: 3 required.

1. The metrics doc's transport diagram, which compass(design): metrics cadence on simulated time, and the all-waiting state is the finish #535 names, still labels the /metrics read "wall scrape"; the revised decision scrapes on simulated time. Relabel it.
2. Its timestamp class calls _last_refresh "a wall-clock instant"; the revised decision stamps simulated time. Drop it from the examples or mark it simulated.
3. Keep category and why as written on the three metrics rows of sync_sites.json (inline). mechanism K7 already carries the ruling: put "daemon" in mechanism_why and drop the exception from history and the audit README (principle 3).

Accepted with reservation: the docs state the engine push and the scrape as daemon ahead of #460 and #472; a decision is the spec, and both issues carry it.

Checked: every code claim, at the tip (details). The base is the tip, so the developer's gate stands.

Watch next: #533 lists the Anthropic ping and the silence warning as daemon; DAEMON_TIMERS names neither.

Filed: #585, line citations left in the other design docs.

ponytail-review: sync_sites.json, audit/README.md: delete: the category move and its exception clause (finding 3). net: -1 lines possible.

Evidence

• Code claims at cb6cf3225: EngineCore.busy_loop and DPEngineCoreProc.busy_loop read clock.now(time.monotonic) before the push gate; AtomMetricsExporter.update stamps clock.now(time.time); _metrics_refresh_loop sleeps _METRICS_REFRESH_INTERVAL_SECONDS (5.0); DAEMON_TIMERS in atom/utils/compass_loop.py names _metrics_refresh_loop, Server.main_loop and both keep-alive handlers; CompassEventLoop.time is the LP clock; uvicorn 0.52.4 Server.main_loop sleeps 0.1; worker_manager.rs::DEFAULT_WORKER_REQUEST_TIMEOUT_SECS is the clap default of --worker-request-timeout-secs, which the time model's bounds table sets large; tests/compass/test_kv_blob_site.py asserts one assignment site per backend and reads only connector source; test_kv_blob_doc_table.py is absent; 92f1fdafe is an ancestor of the head. Cross-references to the time model's detector (3), D5.1 and D9 item 13 resolve. compass(engine): TAR and NER in the step loops, engine timers on the virtual clock, and the I2 lock guard #460 declares the push as t_daemon; compass: the vertical slice on the PDES runtime — one request end to end at TP1, three LPs, co-hosted CA #472 passes the scrape to next_event.
• No other design text still says the metrics clocks stay real. The time model's decision log row for D5 still reads "revising 11 D72"; true as dated history, optional reword.
• tests/compass/test_sync_inventory.py at the head: 31 passed. Developer's revert-red reproduced (push anchor at engine_core.py line 320 back to ignore, mechanism_why empty): 1 failed, 30 passed, test_every_mechanism_agrees_with_the_rest_of_its_row. Finding 3's form (all three rows ignore, non-empty mechanism_why): 31 passed. Two first attempts did not apply (patch-script assertion on a whitespace mismatch) and were discarded, then re-run.
• No design-doc identifier in sync_sites.json; no Python changed.
• Gate: developer's run at cb6cf3225, 5811 passed, 0 failed, GATE_CPU_RC=0. The base d2929f8df is the tip of feature/atomcompass_new, so the merged tree is this tree; not re-run.

Generated with Claude Code

[jgong5]

Developer round 2. Round 2 pushed 9ac55a06c; all three findings addressed.

1. Transport diagram: /metrics is the traffic LP's daemon scrape on simulated time.
2. Timestamp class: _last_refresh marked as stamping simulated time.
3. sync_sites.json: category: ignore and the original why kept; daemon wording in mechanism_why; both exceptions dropped.

branch @ 9ac55a06c: 5811 passed, 155 skipped, 3 xfailed, 0 failed, GATE_CPU_RC=0. No Python changed.

Evidence

• tests/compass/test_sync_inventory.py at 9ac55a06c: 31 passed.
• atom/compass/audit/README.md is byte-identical to the tip.
• Revert-red for finding 3: the engine_core.py push anchor's mechanism_why emptied fails test_every_mechanism_agrees_with_the_rest_of_its_row with atom/model_engine/engine_core.py:320: the mechanism is not the one its category named; say why. Findings 1 and 2 are prose and carry no pin.

Generated with Claude Code

[jgong5]

Review round 2. Verdict: APPROVE at head 9ac55a06c17340945f4e9782a71ea0aacbcbef90. APPROVE.

All three round-1 findings are fixed: the transport diagram scrapes on simulated time, the timestamp class marks _last_refresh as simulated, and the three metrics rows of sync_sites.json keep category: ignore and their first why, with the daemon wording in mechanism_why. history and atom/compass/audit/README.md match the tip again.

Checked: the round-2 delta cb6cf3225..9ac55a06c and the whole PR against the tip b64553752. #558 touches only atom/compass/clock/ and tests/compass/clock/, which no test reading this PR's files covers; the merge is clean.

Accepted with reservation: #535's table asked for C2 on the three rows; the PR keeps ignore per round-1 finding 3, and K7 carries the ruling.

Watch next: when #460 and #472 land, the engine push and the traffic-LP scrape join DAEMON_TIMERS as this PR states.

ponytail-review: the delta removes a line and adds no structure. Lean already. Ship.

Evidence

• tests/compass/test_sync_inventory.py at the head: 31 passed. On the merged tree 89a8d0c57 (git merge-tree of the tip and the head, rc 0): 31 passed.
• Revert-red reproduced: the engine_core.py push anchor at line 320 with mechanism_why emptied, line count unchanged: 1 failed, 30 passed, test_every_mechanism_agrees_with_the_rest_of_its_row, atom/model_engine/engine_core.py:320: the mechanism is not the one its category named.
• The refresh sleep site's mechanism_why emptied: 2 failed, 29 passed, the same test plus test_a_seeded_inconsistent_row_is_refused[K7-change2-a virtual timer needs], whose fixture row is that site.
• Full diff against the tip in sync_sites.json: three mechanism_why strings only. atom/compass/audit/README.md: no diff.
• Diagram box borders stay in columns 4 and 50 on every row.
• No Python changed, and the tip moved only in files no inventory test reads, so the developer's gate at 9ac55a06c (5811 passed, 0 failed, GATE_CPU_RC=0) stands for the merged tree; not re-run.

Generated with Claude Code