Module observer 

Run observer: callback trait for phase lifecycle events.

The executor notifies observers when phases start, complete, or fail. The TUI implements this to update its display state. The default stderr observer prints phase progress lines.

Re-exports

pub use crate::scene_tree::NodeKind as PreMapKind;

Structs

EventTag

Provenance tag carried alongside a log message so display sinks can route by kind, not by sniffing message text.

PhaseProgressUpdate

Live metrics snapshot for progress updates.

PhaseRenderHandle

SRD-100 P2 — the per-phase live render handle, attached to the display fold’s ActivePhase exactly once (after the Activity and its metrics exist — executor.rs creates the activity well after phase_starting, so this cannot ride that callback). It carries everything a display surface needs to re-derive this phase’s status line at the consumer by folding the snapshot, replacing the retired per-phase inline-status producer threads (SRD-100 §6).

StderrObserver

Default observer: prints to stderr.

Enums

CompletedPhaseDisplay

SRD-92 R5 — how much of a completed node’s block is retained in scrollback. Completion is never a full collapse: the header line always lands; this selects whether the detail rows and op leaves land with it. Selected once per run via the completed_phases= param; session.log keeps every line unconditionally.

EventCategory

The semantic domain of a structured event — orthogonal to the lifecycle moment it attaches to. Extend as producers appear; a category earns a variant when some consumer (sink filter, counter, panel) needs to dispatch on it without string-matching rendered prefixes.

LogLevel

Log level for diagnostic messages.

SkippedPhaseDisplay

SRD-? — how a FULLY-SKIPPED phase (every cycle if:-gated off, or pre-entry pruned) is represented across the plan, traversal, and readout surfaces. Selected once per run via the skipped_phases param; read by the runtime’s completion fire, the executor’s pre-entry gate, and the TUI’s tree fold.

Traits

RunObserver

Lifecycle events from the executor.

Functions

colorize_log_line

ANSI-colorize a log line by severity for console output. Always applied at the producer side — every console emission of a log entry runs through this so DBG/INF/WRN/ERR are visually distinct without the operator having to squint at message bodies. Falls through to the bare message when stderr isn’t a TTY or NO_COLOR is set (per use_color); pipeline captures stay readable.

completed_phase_display

The run’s completed-phase display mode. Default CompletedPhaseDisplay::Full.

display_level

Effective console display threshold. Defaults to Info — same default the live observers use.

global_observer

The observer the current code should route through. Used by code that needs the observer without threading it through every call site (e.g. the activity’s inline-status refresh thread publishing into [RunObserver::set_status_line]).

is_explain_held

True iff the explainer overlay is currently on (toggled on within the last EXPLAIN_AUTO_REVERT_MS and not yet toggled off). Read by the readout binder on each fire() to decide whether to dispatch with ContentMode::Explanation instead of Value.

log

log_tagged

log with an explicit EventTag. The session-log write (unconditional, all tags) and the fallback stderr path are identical to log; the tag only changes how a tag-aware display sink files the message — e.g. the readout engine attaches phase-start renders to PhaseStart so the terminal sink keeps them out of its scrollback (they show in its managed phase-history region instead).

op_output

Emit a line of adapter op output (SRD-41 / “console belongs to the adapter”). Delegates to the installed crate::output_channel::OutputChannel (SRD-87): the op-output bucket’s impl decides where the bytes land — raw to the owned stdout (a console-owning adapter or a pipe, via [op_output_raw]) or routed through the live display (an interactive dashboard, avoiding the raw-mode staircase). Before any channel is installed (bootstrap / unit tests with no run), falls back to the raw path so early output is never lost.

readouts_paused

True while the readout pause is on (see toggle_readout_pause).

retain_level

Effective retention threshold. Defaults to Debug so pre-runner-init log calls (very early startup) still reach the file sink.

set_completed_phase_display

Set the run’s completed-phase display mode (runner, at param parse).

set_display_level

Install the console display threshold. Called by the runner alongside set_retain_level at startup.

set_global_observer

Set the global observer. Called once by the runner at startup.

set_log_file

Direct the log sink to a file. Opens for append-writes, installs the crate::log_sink async writer thread. Producers thereafter try_send and never block — see SRD-02 §“Display and Diagnostic Decoupling”. Silently no-ops on a second call — the first session wins (one run per process).

set_retain_level

Install the file-sink retention threshold. Called once by the runner; subsequent calls are silent no-ops (matching the “first wins” pattern of the rest of the global observer surface).

set_skipped_phase_display

Set the run’s skipped-phase display mode (runner, at param parse).

skipped_phase_display

The run’s skipped-phase display mode. Default SkippedPhaseDisplay::Mark.

toggle_explain

Toggle the explainer overlay. First press → on (with a 10 s auto-revert deadline). Second press while on → off immediately. Auto-repeat-safe via a 250 ms debounce.

toggle_readout_pause

Toggle the readout pause; returns the NEW state (true = now paused).

trace

Emit a LogLevel::Trace event carrying the component’s labels through the [crate::trace_router]. Returns immediately when no --trace=<spec> was configured (the router is empty), so the hot-path cost of an unused trace site is one atomic load + branch.

trace_enabled

True iff the trace router has at least one configured sink. Hot-path guard so callers can skip expensive message formatting when tracing is off.

use_color

Log a diagnostic message through the global observer and append to the async log sink (if initialized). Safe to call from anywhere — falls back to stderr if no observer is set.