Trace Glossary

Trace Glossary: Decoding Certificate Fields for Auditable Routes

Quick-Scan Infobox

Aspect	Details
Target User	Educators dissecting traces, developers scripting audits; JSON parsing basics assumed.
Core Goal	Break down --trace JSON fields—from utilities to drifts—for mechanistic insights into bounded decisions.
Time to First Decode	3 mins: jq '.constraints' trace.json → Unpack feas/shadows.
Key Analogy	Like a hike logbook: Each field a waypoint note—utilities the elevation gain, boundaries the fork warnings, drifts the pace checks.
Emit Flag	--trace for verbose; minimal defaults to model + U.

Core Principles Layer (Technical Backbone)

Traces are Compitum's audit envelopes: JSON schemas capturing the observer loop from embed to select, with fields tying to core math—U as free-energy min ( U = \alpha q - \beta_t l - \beta_c c - \beta_d d + \beta_s e - \beta_u \sigma ), components as decomps, constraints via feas ( A x \leq b ) and shadows ( \lambda_i = \partial U^* / \partial b_i ), boundaries on gap ( g = U_1 - U_2 < \delta ) or entropy ( H = -\sum p_i \log p_i > \log 2 ), drifts via SRMF (r_t from EMA ( \bar{d} = \alpha d + (1-\alpha) \bar{d} ), I_t leaky integral). PGD sig hashes projected x_B for tamper-proof; timestamp/version for repro. Example in repo examples/trace.example.json: Full cert post-route, flat for ARIA/screen readers.

• Utility Flow: Components predict via calibrated models (Platt/isotonic); unc σ_U = √(∑ w_i^2 σ_i^2) modulates flags.
• Constraint Audit: Feas boolean gates select; violations list (e.g., ["cost>1"]); shadows approx via ε-perturb (finite diff O(ε)).
• Boundary Heuristic: Flag if g<0.05 AND (H>1.0 OR σ_winner>0.1)—triggers Thompson reroute.
• Drift Control: r_t = clip(r exp(-β \bar{d} - κ I)), with I = ρ I + γ e_t (anti-windup ρ=0.99).

Why these fields? Mechanistic certificates: Each a bounded query signal, emergent audit from local logs—no judges, just quadratic proofs.

Code Dive: Field Extraction Script (Collapsible for Tinkerers)

Open on GitHub | Open in nbviewer | Launch in Binder

Snippet from Trace-Glossary.md

# Audit Trace: Parse Key Fields
import json
from typing import Dict

def decode_trace(trace_path: str) -> Dict:
    with open(trace_path, 'r') as f:
        cert = json.load(f)
    
    # Extractors
    model = cert['model']
    U = cert['utility']
    components = cert['utility_components']
    feas = cert['constraints']['feasible']
    shadows = cert['constraints']['shadow_prices']
    gap = cert['boundary']['utility_gap']
    entropy = cert['boundary']['entropy']
    r_t = cert['drift']['trust_radius']
    
    # Insights
    insights = []
    if not feas:
        insights.append("Infeas: Loosen b via shadows.")
    if gap < 0.05 or entropy > 1.0:
        insights.append(f"Boundary: g={gap:.3f}, H={entropy:.2f}—explore.")
    if r_t < 0.5:
        insights.append("Tight r_t—check EMA drift.")
    
    return {
        "summary": {"model": model, "U": U},
        "components": components,
        "insights": insights,
        "sig": cert['pgd_signature'][:8]  # Prefix for quick ID
    }

# Example: Load Verbose
print(decode_trace('examples/trace.example.json'))

Pro Tip: Validate schema: pydantic model on cert—flags missing 'timestamp'.

Approachable Layer (Relatable Hooks for Educators)

Traces are the "debrief diary" for your routes: Model as the chosen speaker, U the session vibe score, components the feedback facets ("quality high, but latency dragged"). Constraints as the room rules (feas check: "All in bounds?"), shadows the "what if flex?" queries, boundaries the "tiebreaker alerts" for group polls. Drifts? Pace monitors—EMA smooths the jitters, integral the cumulative "off-course" tugs. For classrooms, they're reflection prompts: Parse a student's query trace, discuss "high entropy? Reroute with peers"—turns math fields into teachable "error controls," like Montessori self-checks.

• Classroom Tie-In: Batch traces for class sims—spot patterns in shadows ("Tight ethics? Brainstorm relaxes"), use unc for "confidence circles."
• Analogy Echo: PGD sig as the trail marker: Hash ensures "this path's untampered"—hike without getting lost.
• Common Hurdle: Field overload? Start with jq one-offs: .utility_components.quality for quick quality scans.

Quick-Reference Toolkit (Field Breakdown)

Section	Field	Type	Description	Math Tie	Threshold Example
Core	model	str	Selected candidate.	Argmin E.	N/A
Core	utility	float	Scalar U.	( \alpha q - \sum \beta c ).	< -0.1 good
Components	quality	float	+ Quality pred.	Calib μ_q.	>0.7 strong
Components	latency	float	- Latency cost.	-β_t l.	<0.2 low drag
Components	cost	float	- Base/model cost.	-β_c c.	<0.1 budget ok
Components	distance	float	- SPD dist to prior.	-β_d d_M.	<0.15 aligned
Components	evidence	float	+ Coh log p.	β_s log \hat{p}.	> -1 coherent
Components	uncertainty	float	σ_U spread.	√(∑ w σ^2).	<0.1 confident
Constraints	feasible	bool	A x ≤ b ok.	QP feas.	True
Constraints	violations	list[str]	Reasons if false.	e.g., ["cost>1"].	Empty ideal
Constraints	shadow_prices	list[float]	∂U/∂b_i.	Finite diff approx.	<0.5 loose
Boundary	winner / runner_up	str	Top two.	Argmin1/2 E.	N/A
Boundary	utility_gap	float	U1 - U2.	g < δ flag.	>0.05 clear
Boundary	entropy	float	Softmax H.	-∑ p log p.	<1.0 peaked
Boundary	uncertainty	float	Winner σ.	Calib spread.	<0.1 low doubt
Boundary	is_boundary	bool	Heuristic flag.	g<0.05 AND (H>1 OR σ>0.1).	False
Drift	trust_radius	float	Current r_t.	Clip(exp(-β \bar{d} - κ I)).	0.5-2.0 stable
Drift	drift_ema	float	EMA of dist.	α d + (1-α) \bar{d}.	<0.05 smooth
Drift	drift_integral	float	Leaky I_t.	ρ I + γ e.	> -0.2 no windup
Audit	pgd_signature	str	Prompt hash prefix.	sha256(x_B).	Traceable
Audit	timestamp	str	ISO time.	UTC route.	Repro
Audit	router_version	str	Tag.	SemVer.	v0.1.0 lock

Gotchas Table (Collapsible: Trace Traps)

Issue	Symptom	Fix	Analogy
NaN Fields	Inf U or σ.	Clip preds [-1,1]; check calib.	Overflow ink—cap the pen.
Empty Violations	Feas true but shadows high.	Perturb b for sens; log all.	Silent alarm—test the bell.
High Entropy Always	H>2 per trace.	Temp τ=0.8; more candidates.	Foggy map—sharpen the lens.
Drift Stale	r_t fixed.	Tune α=0.3; force refit stride=4.	Stuck odometer—wind the gear.

Next Steps: Your Loop

• Audit a Trace: Load example.json, extract insights—boundary flag?
• Script a Decoder: Extend the snippet; batch on routes for patterns.
• Tune a Field: Weight β_u=0.05 in config, re-trace—unc impact?

See also: Output-Format for schema; Glossary for term cross-refs; Cookbook for jq/parse recipes; Verification for trace tests.