RIFF — Console, Corridor & Simulation Tooling (how to run + review)

Status: live tooling guide — reflects what's built and runnable today Date: 2026-07-01 See also: call-plan-artifact-schema-v0.md (the artifact + §6 trace contracts), console-flow-map-design-v0.md (the corridor design), companion-channel-design-v0.md (the texted-link channel).

This is the operator/engineer guide to the design-review surfaces and the simulations that feed them. Everything here is offline (no phone, no live Gemini) unless noted — it renders the compiled artifact + recorded/simulated §6 traces.

1. Serve the review pages

The web pages fetch data files (/data/...), so they must be served over HTTP (not file://):

cd /Users/davidmar/src/riff/web
python3 -m http.server 8799        # or any port

Then open (the pages read the live files, so a reload picks up new commits):

The live phone/web call is separate from these: http://127.0.0.1:8765/voice.html?flow=space_channel_network_ops (browser mic) or the Telnyx number (needs the cloudflared tunnel up).

2. riffc — the pre-flow compiler (validation-only, no runtime effect)

riffc compiles a flow YAML into the node/edge/finding data the console + corridor render, and runs the L0 compile-time checks.

python -m riff.riffc flows/space_channel_network_ops.yaml            # prints the L0 report
python -m riff.riffc flows/austin_plumbing.yaml --json out.json      # + writes the artifact JSON

What it emits: classify_node (say/choose/collect/do/end), flow_shape (hub|chain), classify_edges (advance/failure/reloop, DFS back-edges), traversal_order, and L0 findings (missing degraded assets, no reject path, unpinned collect, orphaned states, template leaks …). It never touches the runtime.

Rigor: tests/test_riffc_all_flows.py classifies every state of all ~60 flows (0 unknowns); tests/test_riffc_edges_adversarial.py proves every reloop forms a real cycle corpus-wide.

3. The simulations (the transcript / data evidence)

3a. Full audio sim — what the caller HEARS

Drives all Space Channel options through the real transport audio path, Whisper-transcribes what plays, and LLM-judges each:

set -a && . ./.env && set +a
python scripts/space_channel_all_options_sim.py
# → docs/flow-eval/space-channel-all-options.md   (per-option transcript + judge + verdict)

3b. §6 trace sim — the step-by-step data the corridor replays

Drives the real FSM per permutation and emits a §6 trace (JSONL) per option:

python scripts/space_channel_trace_sim.py
# → web/data/traces/space_channel/<route>.jsonl  + index.json

Then regenerate the corridor artifact (nodes + exits, derived from riffc + the sim index):

python scripts/gen_corridor_artifact.py space_channel_network_ops
# → web/data/corridor/space_channel_network_ops.json

Reload the corridor and pick a permutation — you're now stepping through that option's real trace.

4. The §6 trace format

One JSON object per line, keyed by call_id, dense monotonic seq, t_ms since call_start. Types: call_start, state_enter, audio_pushed, audio_done{source}, barge_in, route_decision{via,token,goto,heard_*,confidence}, collect_turn, tool_start, tool_result, degraded, stall_detected, call_end. Emitted by riff/trace.py::TraceEmitter (one per call, engine-owned). Canonical fixture: tests/fixtures/trace_plumbing_sample.jsonl.

5. Test it's all solid

python -m pytest tests/test_riffc*.py tests/test_trace.py \
  tests/test_space_channel_trace_sim.py tests/test_web_static_push.py -q

Covers: node classification across the corpus, edge/reloop correctness, the trace emitter + fixture schema, every permutation emitting a valid trace, and the web static-audio push (the regression for the pump-crash that caused the 'huge delay' on the web path).

6. Where things live