[Code Health] Rename span families to pod/host/chip/core — coordinated across simpler, pypto-lib, pypto-serving

[ChaoWao]

Category

Naming / Consistency

Component

Other (please specify in description)

Affects the [STRACE] span vocabulary, which spans src/common/,
simpler_setup/tools/, the docs, and two external repositories.

Description

Span names currently come in two unrelated families with no shared scheme, and one
of them is a de-facto contract with repositories outside this one.

Today:

Family	Emitted by	Occurrences
simpler_run*, simpler_prewarm.*	the chip runtime in the forked child	~185 in 37 files
l3.*	the L3 parent (added by #1730, unreleased)	~59 in 17 files

The scheme. One word per level of the hierarchy — the same levels, named
instead of numbered:

Prefix	Level	What it describes	Replaces
pod.	L4	a Worker whose children are L3 Workers	nothing emits it yet
host.	L3	one host driving chips: graph build, submit, dispatch, worker threads	l3.*
chip.	L2	the chip runtime in the forked child	simpler_run*, simpler_prewarm.*
core.	L0	the in-core AIC/AIV pipeline	the core-swimlane tool's own output

Numeric levels stay out of the names, consistent with codestyle rule 13's mapping
of L2 → Chip and L0 → Core. Rule 13 lumps L3+ together as unprefixed because
it governs type and identifier names, where one Worker serves every level above
the chip; a trace does need L3 distinguished from L4, hence two words where the rule
has none.

The prefix is per process, not per call site. Orchestrator::submit_impl and
WorkerThread::submit_dispatch are level-agnostic — the same code runs at L3 and
L4. It does not need to be per site: a Worker forks its next-level children into
separate processes, so one process hosts exactly one Worker level, and the prefix
resolves once at Worker init.

Reserve a namespace for external producers. pod./host./chip./core. are our
levels and a caller is not one of them; without a reserved prefix a caller's span
named host.foo parses as ours. Settle it here rather than when a public tracing
API lands, because this is the one moment every name and every parser is already
being touched.

Location

Inside this repo:

• simpler_setup/tools/strace_timing.py — legacy_spans(), _ROUNDS_TABLE_NAMES,
  _host_thread_name, the swimlane process-role test, the flow-key pairing
• Hardcoded assertions that will fail loudly (good):
  tests/st/a2a3/host_build_graph/native_run_lifecycle/test_native_run_lifecycle.py
  (an expected-depth table), tests/st/a5/tensormap_and_ringbuffer/bench_prewarm_timing.py
  (a compiled regex on name=simpler_run.bind.prebuilt),
  examples/workers/l2/vector_add/test_run_timing.py, tests/ut/py/test_strace_timing.py
• Docs: docs/dfx/host-trace.md, docs/dfx/l2-timing.md, docs/dfx/device-phases.md,
  simpler_setup/tools/README.md, and the dfx-analyze / benchmark skills

Outside this repo — the reason this needs coordination rather than a rename commit:

• pypto-lib pypto/runtime/bench.py carries its own copy of the span-name
  table (_ROUNDS_TABLE_NAMES), and its comments still reference the
  run_prepared → simpler_run root rename from simpler Refactor: rename prepare/run vocabulary to register, layered by ABI tier #1210 — with the table
  still keyed off the pre-Refactor: rename prepare/run vocabulary to register, layered by ABI tier #1210 spelling. golden/runner.py reuses that parser.
• pypto-serving .agents/skills/qwen3-14b-offline-perf-test/SKILL.md hardcodes
  simpler_run, runner_run, device_wall and the formula
  simpler_run.runner_run.device_wall.graph_build as Effective. Being a runbook,
  it fails silently — the agent simply stops finding the field.

docs/dfx/host-trace.md frames this as a feature: "A consumer (e.g. pypto-serving)
reads the per-stage breakdown from the log, with no code change on its side and no
API contract." "No API contract" is precisely the problem — the names are the
contract. #1210 already renamed a span root once, the downstream repo had to adapt,
and the scar is still in its code.

Proposed Fix

Coordinated rename across simpler, pypto-lib and pypto-serving together — no
dual-spelling window and no alias table, so the retired spellings actually go away
rather than lingering the way #1210's did.

1. Settle the merge order. simpler emits the new names, so it lands last or behind
   something the other two can pin against; otherwise their parsers see unknown
   names for the window between merges.
2. Rename in simpler, and replace legacy_spans()'s allow-list with an explicit
   family split so per-task host.* spans stay out of the invocation-grouping path.
3. Downstream edits in the two files located above.
4. A grep gate per repo: zero occurrences of the retired spellings, in prose as
   well as code, since the pypto-serving consumer is a runbook.

Blocked on #1792's "one span entry point" item — renaming one emit site is far
easier than renaming three — and on the by_name() fix requested in #1730, because
removing the allow-list is what makes that latent bug live.

Priority

Medium

[ChaoWao]

Surveyed the downstream consumers against current main on every repo (2026-08-18): simpler 1220d622 · hw-native-sys/pypto 488ba5d · hw-native-sys/pypto-lib 8bf8860 · hw-native-sys/pypto-serving f55785d. The located-edits section of this issue is substantially wrong, and the correction makes the rename much cheaper than this issue claims. Corrections first, then the verified edit list.

Four corrections to this issue

1. bench.py is in the wrong repo and the wrong path

This issue says "pypto-lib pypto/runtime/bench.py carries its own copy of the span-name table (_ROUNDS_TABLE_NAMES) at 269–271, plus docstrings at 78/121/146/184 and the run_prepared comments at 263/280".

That file does not exist in pypto-lib and never has — git log --all -- '*bench.py' there is empty, and git ls-tree main pypto/runtime/ returns nothing. It lives in a different repository: hw-native-sys/pypto, at python/pypto/runtime/bench.py. The line numbers were recorded against the wrong tree and should be treated as unverified.

2. It does not carry its own copy — it reads simpler's at call time

This is the correction that matters, because "carries a duplicate table" was the main argument for "cannot rename in one repo". What bench.py actually does (python/pypto/runtime/bench.py:284-313):

# `run_prepared` -> `simpler_run` in simpler #1210, so the names are sourced
# at call time from the installed runtime's `strace_timing._ROUNDS_TABLE_NAMES`
_LEGACY_SPAN_NAMES = {
    "host":   "run_prepared",
    "device": "run_prepared.runner_run.device_wall",
    "orch":   "run_prepared.runner_run.device_wall.orch",
    "sched":  "run_prepared.runner_run.device_wall.sched",
}

def _resolve_span_names():
    """Resolve the four [STRACE] span names from the installed runtime."""
    try:
        from simpler_setup.tools.strace_timing import _ROUNDS_TABLE_NAMES
        return {key: _ROUNDS_TABLE_NAMES[key] for key in _LEGACY_SPAN_NAMES}
    except ...:
        return _LEGACY_SPAN_NAMES

The hardcoded names are a fallback for runtimes older than #1210, not a duplicate to keep in sync. It keys off host / device / orch / sched, and our side already exports exactly those four (simpler_setup/tools/strace_timing.py:451-456).

Consequence: if the rename keeps _ROUNDS_TABLE_NAMES with the same four keys, pypto needs no code change at all. The table is already the compatibility seam this issue proposed inventing.

3. The pypto-serving hardcoding is in a different skill, and it is code, not a runbook

This issue names .agents/skills/qwen3-14b-offline-perf-test/SKILL.md and says a runbook "fails silently". Both halves need adjusting:

• That file is a consumer — 9 hits — but it is prose only.
• The hardcoded span literals are in a second skill this issue does not mention: .agents/skills/profile-dsv4-serving-strace/, which ships executable Python. scripts/render_8lane.py imports nothing from simpler (stdlib only) and looks up literals by name, so it fails loudly — one_event(events, "simpler_run.bind") on a renamed trace finds nothing.

4. It is four repos, not three, and the dependency is chained

pypto-lib does not read span names at all. golden/runner.py:869-873 imports the parsing helpers from pypto:

from pypto.runtime.bench import _STRACE_LOG_LEVEL, _capture_fd_stderr, _parse_stats_from_strace

So the chain is simpler → pypto → pypto-lib, with pypto-serving hanging off simpler in parallel. This issue's "coordinate simpler, pypto-lib and pypto-serving" has the middle repo wrong and misses pypto entirely.

Verified edit list

Repo	File	Shape	Rename cost
simpler	simpler_setup/tools/strace_timing.py:451-456	_ROUNDS_TABLE_NAMES — the contract, 4 stable keys → dotted names	the change itself
pypto	python/pypto/runtime/bench.py:284-313	imports the table; hardcodes only the pre-#1210 fallback	no code change if the 4 keys survive
pypto	same file, lines 15/23/25/35-36/61/81/89/120/132/149/169-170/208	prose naming simpler_run, runner_run, device_wall in docstrings/comments	prose (Tier A), no breakage
pypto	python/pypto/ir/compiled_program.py:680,1391 · python/pypto/jit/decorator.py:2145	prose referencing [STRACE] (simpler #1177)	prose
pypto-lib	golden/runner.py:869-873	imports helpers from pypto.runtime.bench — no span names	no change
pypto-lib	golden/runner.py:334,375-376,398,417,587,609,751,916 · .github/workflows/daily_ci.yml:67,186 · docs/debug-and-tune/performance-tuning.md · tests/golden/test_runner.py	prose / log-level plumbing; device_wall_us is a stats field, not a span name	prose
pypto-serving	.agents/skills/profile-dsv4-serving-strace/scripts/render_8lane.py:118,196,200,201,202,220,221,231	❗ hardcoded literals — simpler_run, simpler_run.bind, simpler_run.runner_run, simpler_run.validate, plus removeprefix("simpler_run") twice	real code edits, 8 sites
pypto-serving	.agents/skills/profile-dsv4-serving-strace/scripts/analyze_profile.py:33,59	imports from simpler_setup.tools.strace_timing	follows automatically
pypto-serving	.agents/skills/profile-dsv4-serving-strace/SKILL.md:77-84	prose naming the spans, and the clk=dev / device_wall / Effective contract	prose
pypto-serving	.agents/skills/qwen3-14b-offline-perf-test/SKILL.md:127,128,130,134,139,140,153,156,157	prose: metric table plus both TPOT ~= … formulas	prose

What this does to the plan

The proposed fix in this issue — "coordinated rename across three repos together, no dual-spelling window and no alias table" — was sized against a duplicate table that turns out not to exist. With the real shape:

• _ROUNDS_TABLE_NAMES is already the alias table, and keeping its four keys stable is what makes the rename land without a lockstep window. That is a decision to preserve something, not to build it.
• Exactly one downstream file needs code edits: render_8lane.py. The better fix there is to teach it to read the table rather than to update eight literals, which also stops it breaking on the next rename.
• Everything else is prose, and prose can lag safely — it does not fail a build or silently mis-parse.

So the merge-order constraint in step 1 ("simpler emits the new names, so it lands last or behind something the other two can pin against") is only binding for render_8lane.py. Suggested revision: land the simpler rename with the table keys unchanged, and fix render_8lane.py in the same window; treat pypto / pypto-lib prose as follow-ups rather than blockers.

The grep gate in step 4 is still right, and it should now cover four repos plus the two pypto-serving skills.

Note on the numbers in this issue

The ~185 occurrences / 37 files and ~59 / 17 figures date from 2026-08-12 and no longer reproduce. Against simpler 1220d622, with the pattern stated so it can be rechecked:

git grep -c 'simpler_run'   → 212 occurrences / 37 files
git grep -c '"l3\.'         →  44 / 8    (span-name string literals)
git grep -c 'l3\.'          →  91 / 21   (loose — also matches l3.json, _l3.py)

The 59 / 17 pair does not come out of either pattern, so it should be replaced by whichever one is meant, with the pattern recorded next to it.