Module run_trace 

The history-replay TRACE: a native instrument that counts and times every execute_history this crate performs, tagged with the SITE that asked for it and the thread it ran on.

The engine executes a history on the RUNNER (a background thread natively, a worker in the browser). Anything the main thread re-derives by running the SAME history again is a second full execution of the document — the kernel’s incremental cache is per thread, and the wire-harness / assembly / PMI tails are not cached at all, so a tail sweeps once per thread that replays. Whether that is happening cannot be read off a frame time, so this module makes it observable in two ways.

A running TALLY, always on, one entry per site: how many executions that site performed, how long they took, and what came back. It is what perf_stats’s runs block reports and perf_reset clears, so a test can bracket one edit and assert that it cost ONE execution — the property the frame time cannot state, because a duplicate replay and a slow machine look alike in milliseconds. The cost is one mutex lock per execute_history, which is a millisecond-scale operation.

Two things to know before reading a tally. It is PROCESS-global, not per-session — several headless sessions in one process share it — so the only meaningful read is one bracketed by reset; an unbracketed runs is every execution since the process started. And a CANCELLED run contributes nothing: the runner thread is terminated rather than joined, so its span is never dropped and never folded in. A tally of zero after a cancel is the expected reading, not a lost measurement.

A per-execution LINE on stderr, when the environment asks for it:

BREP_RUN_TRACE=1 ./brep-app --mcp 2>trace.log

[run-trace] site=runner thread=ThreadId(2) ms=412.6 features=21 reused=20 errors=0

site=runner is the one execution a run is supposed to cost; every other site on a different thread in the same edit is a duplicate replay. Both halves are a no-op on wasm, where there is no second thread to trace.

Structs

SiteTally

One site’s running total. features, reused and errors are summed over the executions that reported a result — a replay that is “free” because every feature errored out reads the same as a warm cache hit without them.

Tally

A set of per-site totals. A BTreeMap keyed by the site’s &'static str so the report comes out in a stable order and a new site needs no registration.

Functions

reset

Drop every site’s totals — the counterpart of clearing the frame-timing window, so a caller can bracket ONE interaction.

span

Open a trace span around an execute_history call. Always Some natively — the tally is not gated on the environment variable; the Option is the shape wasm needs.

tally

Every site that has executed a history since the last reset, in name order.

tally_json

The tally as JSON: one object per site plus a total, the shape perf_stats embeds under runs.