compass(design): doc 11 D72/D74 - metrics clocks on virtual time, sim-time observer

[jgong5]

Part of #443. Design-doc only.

Moves D72 and D74 of 11 onto the PDES time model: the three metrics clocks run on virtual time, and a sim-time observer scrapes /metrics.

What changes

• Metrics clocks: the engine push gate (EngineCore.busy_loop, DPEngineCoreProc.busy_loop), the refresh loop's asyncio.sleep (_metrics_refresh_loop in api_server.py) and _last_refresh (AtomMetricsExporter.update) run on virtual time; none is allowlisted.
• New observer: a periodic timer in the traffic LP scrapes /metrics every scrape_interval of simulated time over the existing traffic->frontend:http / frontend->traffic:stream channels. No new LP or channel; samples carry virtual timestamps.
• New end of run: the traffic LP calls end_workload() (CA END) after its last scrape, so a periodic observer cannot keep a run alive.
• The section headed "This corrects 01 D5" is replaced by a note that the virtual push cadence there stands. Per-step sampling is unchanged and coexists with the scrape series.
• A follow-up commit (comment) renames the backfill table's category-A path to K1 of compass(design): doc 01 D4, D5, D9 and the decision log move to the PDES mechanisms #450.

Dev record

• Found: _last_refresh is also exported as the gauge atom:metrics_last_refresh_timestamp_seconds, mentioned by neither the old decision nor the design; it now carries virtual time.
• Decided: the decision states that the API server's asyncio loop runs on virtual time without citing a section, since CompassEventLoop has no section at the tip yet.
• Surprised: the design does not say where the scrape series is written or name the scrape_interval config key.
• Left undone: stale restatements of the old decision in README.md and 01, owned by compass(design): doc 01 D1-D3.5 protocol to HLA-style PDES grants #446 and compass(design): doc 01 D4, D5, D9 and the decision log move to the PDES mechanisms #450 (details).

Named result

none.

Gates

none: no code.

Details

How and why the clocks move (D72). The push gate is a virtual timer whose next push is a local next event folded into the engine's NER time. The refresh loop's asyncio.sleep becomes virtual with no code change because the API server's loop runs on virtual time. _last_refresh joins the clock-read substitution list (D9 item 2 of 01). The old reasons for real clocks do not hold: at 100x, a push every 5 virtual seconds is one small message per 50 ms of wall time, which affects simulator speed, not the prediction; a wall-clock staleness problem exists only for someone watching the simulator on the wall clock.

D74: the per-step series is the ground truth for analysis; the scrape series is comparable with a real run's Prometheus at the same interval. The transport wording and dataflow diagram no longer say "wall timer" or "wall scrape".

Alignment: the D77 class-T row says _last_refresh is virtual. The decision-log rows for D72 and D74 are rewritten and marked revised 2026-09-28. The doc-11 row of the design/README.md index no longer says "Both metrics clock reads stay real". The follow-up commit: the emission-cost row of the backfill table said a hook inside "a Category-A path" would be invisible; #450 maps old category A to K1 (event cost, advance_to), the only path along which virtual time advances by a modelled duration, and the row now names that path.

Left to other PRs:

• design/README.md, Scope table, "Wall-clock time" row: "Failure detectors and metrics-push cadence deliberately stay real. 01 D5, 11 D72". The metrics half is now false; the row is shared with D5 of 01, whose failure-detector half compass(design): doc 01 D4, D5, D9 and the decision log move to the PDES mechanisms #450 also changes, so it is left for compass(design): doc 01 D4, D5, D9 and the decision log move to the PDES mechanisms #450 or the lead.
• 01 restates the old D72 in D1.2 (the allowlist "is the set doc 11 D72 establishes as deliberately real") and in the D3.4 row "Deliberately-real clock reads ... 11 D72", both compass(design): doc 01 D1-D3.5 protocol to HLA-style PDES grants #446's sections and absent from its worklist (v0.20 design section 10.1); and in the D5 strikethrough "corrected by 11 D72", expected in compass(design): doc 01 D4, D5, D9 and the decision log move to the PDES mechanisms #450's worklist.
• D71's pipeline cites a line span of api_server.py for _metrics_refresh_loop that has drifted slightly at the tip; outside the worklist, left unchanged.
• The design places CompassEventLoop (section 4.12) in D1 of 01 and in 06; neither has it at the tip. The scrape-series gap is design section 4.14.
• Not in this PR: D5 of 01 (virtual metrics cadence, control-command refusals), the decision log and doc 01's README row (compass(design): doc 01 D4, D5, D9 and the decision log move to the PDES mechanisms #450); D3 (the end-of-workload invariant) and D1 (the asyncio deployment note) of 01 (compass(design): doc 01 D1-D3.5 protocol to HLA-style PDES grants #446); the observer's harness side, the aiperf adapter's periodic scrape (compass(design): doc 06 on the PDES time model: tokenizer stations, tracestate and SSE-comment carriers, simulated-time scrape #447).

Register: none opened or closed; T40-T46 unaffected; the 12_open_items.md line "the clock-read sites of 11 D72" stays true.

Generated with Claude Code

[jgong5]

Follow-up commit pushed, 11_metrics_support.md only. The backfill table's emission-cost row said a hook inside "a Category-A path" would be invisible. #450 rewrites D4 of 01 onto the PDES mechanisms K1-K9 and maps old category A to K1 (event cost, advance_to), the only path along which virtual time advances by a modelled duration. The row now names that path.