Module trace 

Structured event trace — the machine-readable sibling of harness::trail.

harness::trail is a human free-form line (facett ACTION … [RENDER] tiny size=800x600 → 412 verts). This is its typed counterpart: every instrumented operation emits its INPUT parameters and its OUTPUT data as real JSON payloads, so an external agent (or a test matrix) can read back exactly the data a facet rendered — its state_json, the vertex proof, the inputs it was handed — not a summary and not a screenshot.

Mirrors nornir viz’s $NORNIR_VIZ_TRACE: one JSON object per line (JSONL) at $FACETT_TRACE (default /tmp/facett_trace.jsonl), truncated on launch:

{"seq":3,"ts_ms":1733961825678,"stamp":"01:23:45.678",
 "span":"facet.render","phase":"in","data":{"title":"graph","size":[800.0,600.0]}}
{"seq":4,...,"span":"facet.render","phase":"out","data":{"title":"graph","vertices":412,"drew":true,"state":{…}}}

The contract

• span — the operation name (facet.render, and whatever a live facet emits for its own interactions).
• phase — in (params accepted), out (result produced), end (a unit of work finished), or event (a point-in-time fact). Pair an in with its later out/end of the same span by adjacency.
• data — the real, structured payload (a serde_json::Value, the same currency as Facet::state_json), so the consumer parses fields rather than scraping a formatted string.

Dependency-free, like the rest of harness: the stamp comes from SystemTime (no chrono) and the payload is a serde_json::Value (no serde-derive). Cheap: a Mutex<File> writeln! + a global atomic seq. Call sites emit on edge-triggered events only, never per-frame.

Enums

Phase

Phase of an instrumented operation — lets a consumer correlate the inputs a call accepted with the data it produced.

Functions

emit

Emit one structured event: span is the operation, phase its stage, and data the real payload (a serde_json::Value — typically a facet’s state_json or a small json!({…}) of its inputs). Writes a single JSONL line to $FACETT_TRACE; never panics (best-effort I/O).

emit_end

Convenience: a unit of work finished (no separate in/out).

emit_event

Convenience: a point-in-time fact (a selection, a mode switch).

emit_in

Convenience: the inputs a call accepted.

emit_out

Convenience: the data a call produced.