version	1.0.0
evaluation	programmatic
evals_version	2
agent	claude-code
model	anthropic/claude-haiku-5.5
model_provider	openrouter
snapshot	python312-uv
primary_outputs	result_card.html

TRACE Simulator: Stop Early, Edit Only What Is Harmful (SMASH 2026 · Paper #10)

Objective

This runbook is an interactive companion to the SMASH 2026 paper "TRACE: Temporal Risk Assessment and Concept Editing for Safer Language Generation" (Ankur Garg, Xuemin Yu, Hassan Sajjad, Samira Ebrahimi Kahou). Read the paper: https://github.com/agarg-dev/TRACE/blob/0d45d7e5a5e30399eeafd0e2a41c55ae8ae8288d/TRACE.pdf

The paper's claim: a safeguard should (1) detect harmful content while it is being generated and (2) intervene only when necessary, leaving safe responses unchanged. TRACE learns a codebook of discrete activation concepts. It scores each concept's harmfulness from response labels, and a causal detector accumulates a token-by-token streaming risk that can stop generation. During generation it edits a token's activation only if that token is assigned to a harmful concept, shifting it toward the nearest benign concept. On Qwen3-8B it improves streaming detection over Kelp and cuts HarmBench ASR with almost no extra refusal on safe responses. A single global refusal direction, by contrast, reaches ASR 0 but makes many safe responses refuse.

What this runbook is. It is a transparent mechanism simulator. It implements every TRACE equation on simulated token activations, with no language model and no text. Why not a real model?

• Qwen3-8B cannot run on a CPU sandbox in the time budget.
• A CPU-sized model (e.g. a 135M-parameter one) would need about 450 MB of downloads (CPU PyTorch plus weights).
• It would also need a labelled corpus of harmful responses. This runbook deliberately does not ship one.

Simulation also gives what a tiny real model could not: the ground truth of every token. Concept purity, detection latency and the effect of each activation edit can then be measured exactly.

The simulated world contains three abstract concept families, built from orthogonal topic, compliance and refusal features:

• benign: ordinary content.
• caution: safe content on a sensitive topic, such as refusals and safety education. These are the hard negatives.
• harmful: compliance on a sensitive topic.

Harmful responses start benign and turn harmful at an onset point. The participant tunes the codebook and the steering, makes the safe data harder, and composes their own response trajectory (e.g. benign:20, caution:8, harmful:14) to see when TRACE would stop it and which tokens it would edit. Output: a shareable result card.

Target wall-clock: under 3 minutes. The experiment takes about 5 s. No LLM calls, no downloads.

The equations, as implemented

• Eq. 1 encoder z_t = (1 − ρ) x_t + ρ LN(W x_t + b), concept c_t = argmin_j ‖z_t − e_j‖².
• Eq. 2 (stand-in) W, b come from ridge regression of layer ℓ onto a simulated later layer u (reconstruction). The codebook is k-means. The region term appends the response label (× region_weight) as an extra coordinate during codebook learning only. Utilization is handled by re-seeding unused codes. The paper trains all of this jointly with β = 0.1, η = 0.01, γ = 5.
• Eq. 3 p_c = (H_c + a·r)/(N_c + a); s_c = (p_c − r)/(1 − r) if p_c ≥ r, else (p_c − r)/r; each concept is counted at most once per response; harmful iff s_c > 0; concept mean μ_c over layer-ℓ activations.
• Eq. 4 token hazard q_t, cumulative risk R_t = 1 − ∏_{i≤t}(1 − q_i); stop when R_t crosses a threshold chosen on validation.
• Eq. 5 response head trained with cross-entropy, streaming head trained with BCE on R_T. Stand-in for the GRU: a causal logistic hazard on [s_ct, max(s_ct,0), support, running max s, running mean s⁺, 4 PCA components of x_t].
• Eq. 6 b(h) = argmin_{b: s_b ≤ 0, well supported} ‖μ_h − μ_b‖, Δ_h = μ_b(h) − μ_h.
• Eq. 7 x'_t = x_t + λ g_h Δ_h with g_h = max(s_h,0)/max_j max(s_j,0), applied only when c_t is harmful.
• Baselines: DiffMean (mean-difference direction, running-mean score) for detection. Global refusal direction (mean token of refusal/caution responses minus mean token of harmful responses) added to every token.
• Steering readouts (simulated downstream behaviour from the semantic features): ASR analog is the share of harmful test responses still harmful after editing. ΔRef analog is the share of originally non-refusing safe responses that now read as refusals.

Paper headline numbers (quote exactly)

• Harmful-class F1 (Table 1), Resp. / Stream: TRACE 0.835 / 0.837 (WildGuard), 0.933 / 0.935 (S-Eval); Kelp 0.839 / 0.803, 0.900 / 0.896; DiffMean 0.491 / 0.491, 0.820 / 0.820; WildGuard classifier 0.571, 0.093.
• Steering (Table 2), ASR / ΔRef: Unsteered 0.873 / 0.000 and 0.634 / 0.000; TRACE 0.306 / +0.006 and 0.062 / −0.002; Refusal direction 0.000 / +0.717 and 0.000 / +0.439; CAST 0.278 / +0.241, 0.167 / +0.263; Self-Reminder 0.289 / +0.078, 0.182 / +0.103.
• Setup: Qwen3-8B, layer 20 read/steer, layer 24 reconstruction target; example stop threshold = 0.605 (Figure 1).

REQUIRED OUTPUT FILES (MANDATORY)

All in {{results_dir}}:

File	Description
result_card.html	Primary output. Self-contained, shareable one-page result card
results.json	All computed numbers (written by experiment.py)
card_data.json	Numbers/figures for the card (written by experiment.py)
narrative.json	Your interpretation of this run (Step 4)
fig_*.png	Figures (written by experiment.py)
summary.md	5–10 line plain-text summary
validation_report.json	Evals v2 report: steps, code checks, checklist (see Write Validation Report)

Parameters

Parameter	Template Variable	Default	Description
Your sequence	{{your_sequence}}	benign:20, caution:8, benign:6, harmful:14, benign:6	Your response trajectory as family:count segments (benign, caution, harmful; ≤ 300 tokens). Activations are sampled for it; TRACE scores it token by token
Codebook size	{{codebook_size}}	48	Number of discrete concepts K (try 16 for a coarse codebook)
Prior strength	{{prior_strength}}	5	Virtual responses a in Eq. 3 (higher = rare concepts pulled harder toward the base rate)
Encoder mix ρ	{{rho}}	0.5	How much the learned projection changes the activation in Eq. 1 (0–1)
Region weight	{{region_weight}}	0.5	Strength of the region term pushing harmful- and safe-response tokens to different codes (0 = off)
Steering strength λ	{{steer_strength}}	1.0	λ in Eq. 7 (and the global direction's scale)
Hard negatives	{{hard_negative_share}}	0.3	Share of safe responses that are refusals / safety education on sensitive topics (0–0.9)
Harm onset	{{harm_onset}}	0.4	Mean position (fraction of the response) where harmful responses turn harmful
Seed	{{seed}}	3	Random seed

Dependencies

numpy, scikit-learn and matplotlib (preinstalled in python312-uv). No downloads, no LLM calls.

Step 1: Set up

Write /app/work/params.json. If a value is blank or still looks like an unsubstituted {{…}} placeholder, use the table default. Clamp codebook_size to [8, 128] (integer), prior_strength to [0, 50], rho to [0, 1], region_weight to [0, 5], steer_strength to [0, 4], hard_negative_share to [0, 0.9], and harm_onset to [0.05, 0.9]. your_sequence is a string; segments that do not match family:count are ignored by the code. Record any clamp as a caveat.

Step 2: Get the code (extract it, don't retype it)

The tested implementation of the method is embedded in the Appendix at the end of this runbook. Do not rewrite, "improve", or re-derive it. Always run the command below first, exactly as written. It copies the files out of this runbook's text (which the sandbox exposes to running processes) in about a second, and it is far faster and more reliable than retyping several hundred lines. Do not skip it on the assumption that it won't work: run it and read its output:

If it exits non-zero or prints MISSING, write each missing file from the Appendix exactly as given, one heredoc per file (quoted delimiter, e.g. cat > experiment.py <<'PYEOF'). If a later step fails, fix only environment problems (missing package, network retry), never the methodology.

Step 3: Run the experiment

Expected: about 5 s. Ends with a done: line giving streaming F1, ASR and ΔRef analogs, and where your sequence stops.

The sandbox has 4 CPUs even though nproc may report more; the exports keep numpy/BLAS and process pools from oversubscribing them.

Step 4: Interpret: write narrative.json

Read {{results_dir}}/results.json and card_data.json, and look at every fig_*.png. Write {{results_dir}}/narrative.json with keys headline, idea (exactly 3), findings (2–4), try_next (2–3), caveats (2–4):

• headline (≤ 30 words): the most striking result of this run with 1–2 numbers from results.json. Usually the selective-vs-global steering contrast (asr_trace and dref_trace vs asr_global and dref_global), or, if detection broke down, the false-positive rate on safe sensitive-topic responses.
• idea: (1) detect harm while it is generated via a cumulative risk that can only rise; (2) discrete activation concepts with a smoothed harmfulness score (Eq. 3) make both detection and editing interpretable; (3) edit only tokens assigned to harmful concepts, toward nearby benign ones, instead of one global direction.
• findings: (1) detection: TRACE vs DiffMean streaming F1 and FPR (detection, including fpr_hardneg) vs the paper's Table 1, plus trace_median_position; (2) steering: ASR and ΔRef analogs for TRACE vs the global direction vs Table 2. Mention safe_tokens_edited_trace: TRACE may still edit a share of safe tokens (impure concepts) without changing their behaviour. (3) The codebook: n_harmful_concepts of codebook_size and their harmful_concept_purity, read off fig_concepts.png. (4) Your sequence: your_stop_token vs your_harm_onset_token, and whether a caution-only stretch triggered a stop.
• try_next: 2–3 runs with exact values using only your_sequence, codebook_size, prior_strength, rho, region_weight, steer_strength, hard_negative_share, harm_onset, seed. Good contrasts: a coarse codebook (codebook_size 16, region_weight 0, hard_negative_share 0.8), which usually breaks detection; a safe-only sequence (caution:15, benign:10, caution:10); a weaker edit (steer_strength 0.5); region_weight 0.
• caveats: simulated activations and a simulated downstream readout, not Qwen3-8B, WildGuard, S-Eval or HarmBench, so the ASR/ΔRef analogs are not comparable in level with the paper; the codebook and the hazard model are simplified stand-ins for the paper's jointly trained cross-layer VQ and GRU; the simulated world was designed with separable semantic features, which favours concept methods.

Step 5: Render the card and summary

Write {{results_dir}}/summary.md (5–10 lines: settings, detection F1/FPR, steering ASR/ΔRef, your sequence, headline).

Writing style for narrative.json

These rules apply to every field and override any longer limits stated earlier in this runbook. Let the paper and the numbers speak; the card is not the place for commentary.

• Length: headline one sentence; idea 1–3 bullets of at most 30 words; findings 1–2 paragraphs of at most 60 words each; caveats 1–2 bullets of at most 20 words. Cut anything the tiles, figures or tables already show.
• Plain statements of what was measured. Write "Sensitivity gap −0.284 [−0.354, −0.218]; the paper reports +0.088", not an interpretation of what it means for the field.
• Avoid: em-dash asides; "not X, but Y" framings; colon-then-reveal sentences; rhetorical questions; words such as crucially, notably, strikingly, remarkably, collapses, illustrating, underscores, highlights, delve, powerful, key insight, worth noting; exclamation marks; restating the method before the result.
• Use the paper's own terms for its concepts. Quote the paper's numbers exactly.

Code Checks

Jetty runs these checks itself in the sandbox after the agent finishes, so they cannot be skipped or misreported. validate.py (see Write Validation Report) runs the same checks first so you can fix problems before you stop.

outputs-exist — Result card, numbers, narrative and summary were written

results-valid — Experiment numbers are valid JSON and the experiment stayed within its time budget

narrative-complete — The narrative is complete and within the length limits

try-next-valid — Every try-next suggestion uses only this runbook's parameters

headline-grounded — Every number in the headline appears in the run's results

card-integrity — The card embeds its figures, shows the headline, and contains no NaN

Checklist

• The headline states this run's finding with its numbers, not a description of the method
• Paper numbers are quoted exactly and any disagreement with the paper is stated plainly
• Caveats say what is synthetic, reconstructed or an extension of the paper
• Each try-next suggestion would plausibly give a contrasting result

Write Validation Report

Judge the four Checklist items honestly against your outputs and write them to /app/work/checklist.json as a list, using the checklist ids Jetty gives you (one entry per item):

Then write the report and self-check in one command:

validate.py writes {{results_dir}}/validation_report.json in the v2 shape Jetty reads (version: 2, one step entry per runbook step, one code_check entry per check above, one checklist entry per item). Jetty replaces the code_check entries with its own independent run of the same checks. Do not write the report by hand.

Iteration (up to 2 rounds)

If validate.py prints any FAIL, fix the named problem (usually a headline number that does not match results.json, or an unknown try_next key), re-render the card (Step 5) and rerun the command above. Never rerun the experiment just to change the narrative.

Appendix: code

These files are extracted verbatim in Step 2.

/app/work/experiment.py

/app/work/render_card.py

/app/work/validate.py