exec_viz 0.3.0

Tick-by-tick replay of a trading_data computation DAG: a recording Observer, a scrubbable tape, and an axum server the browser front-end drives
Documentation
//! Wire shapes shared by the axum server (serializes) and the Dioxus web client (deserializes).
//! `#[cfg]`-neutral — both features compile this module. The fat `/api/day` chart payload is
//! deliberately absent from the client side: the web half holds it as an opaque JSON string and
//! hands it straight to the chart shim.

use serde::{Deserialize, Serialize};

/// One node of the static graph, in step (= topo) order. Roots have empty `deps`. `dims` is the
/// node's element shape (`[]` scalar); the client resolves dep dims by name from topology.
/// `gates` are the node's control edges — the client's gate set is the union over all nodes.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct TopoNode {
	pub node: String,
	pub deps: Vec<String>,
	pub gates: Vec<String>,
	pub dims: Vec<usize>,
	pub plots: Vec<PlotOut>,
	/// Estimated nanoseconds this node spends per step — what ranks the graph by cost. `None` until
	/// it has been stepped enough times for the estimate to be about the node rather than the
	/// machine; see the recorder's `cost` module for what "estimated" means here.
	pub cost_ns: Option<f64>,
	pub fidelity: FidelityOut,
	/// Simplified `∂out/∂dep`, one line per dep — `None` where the kernel has no algebra. Static:
	/// the body is fixed, so only the values it is read against move tick to tick.
	pub deriv: Option<String>,
}

/// Serde mirror of `trading_data_dag::Fidelity`: how much of what a node's body read its Jacobian
/// covers. `omits`/`why` carry the kernel's own string, which is the whole point of the variant.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(tag = "kind", rename_all = "lowercase")]
pub enum FidelityOut {
	Exact,
	Partial { omits: String },
	Opaque { why: String },
}

/// Serde mirror of `trading_data_dag::Ink`: l/c/a only — hue stays renderer-owned.
#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
pub struct InkOut {
	pub l: f64,
	pub c: f64,
	pub a: f64,
}

#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct GuideOut {
	pub label: String,
	pub value: f64,
	pub ink: InkOut,
}

/// Serde mirror of `trading_data_dag::Plot`. `slots` indexes the node's flattened elements
/// (empty = all of them), so a node whose out mixes units draws as several plots, each on its
/// own scale, rather than as several nodes.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct PlotOut {
	pub slots: Vec<usize>,
	pub range: Option<(f64, f64)>,
	pub guides: Vec<GuideOut>,
	/// One name list per axis of the plot's shape, row-major — the cartesian product of them names
	/// `slots` positionally. Empty = indices.
	pub labels: Vec<Vec<String>>,
	pub inks: Vec<InkOut>,
	pub overlay: bool,
	pub solo: bool,
	pub bars: bool,
	pub candles: bool,
}

/// One bucket's last fired flat out. What names its slots is the node's [`PlotOut::labels`] crossed
/// out, which is where a field worth reading belongs — the chart's crosshair line and the DAG
/// panel's hover both read it from there.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct PointOut {
	pub ts_ms: i64,
	pub vals: Vec<f64>,
}

/// One node's full-day output sampled once per 1m bucket (last fired value wins). `deps` lets
/// the chart recompute topo depth without a second fetch; `gates` routes gate nodes to the
/// chart's dedicated gates pane.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct SeriesOut {
	pub node: String,
	pub deps: Vec<String>,
	pub gates: Vec<String>,
	pub dims: Vec<usize>,
	pub plots: Vec<PlotOut>,
	pub points: Vec<PointOut>,
	/// The node's declared clock in ms — the period one point *covers*, not the bucket it was sampled
	/// into. `None` for a node that publishes whenever its inputs do. This is what lets the chart draw
	/// a 1h candle a full hour wide on a 1m grid.
	pub clock_ms: Option<i64>,
}

/// The `/api/day` chart payload, opaque to both the server and the wasm client (the chart shim is
/// the only reader). Snapshotted per request — under a live feed it keeps growing.
#[derive(Clone, Debug, Serialize)]
pub struct DayOut {
	pub series: Vec<SeriesOut>,
	/// Node whose recorded series *is* the candle pane, read positionally as o·h·l·c·v — the chart
	/// draws it there and skips it in the indicator panes. `None` when the graph has no price node,
	/// and then nothing is skipped.
	pub price_node: Option<String>,
}

/// One node's standing output as of the current tick: `fired` says whether it was *this* tick's
/// work, while `out`/`vals` carry the last fired ones forward (`None` only before the node's first
/// fire, or once that tick has left the ring). `out` is the node's own `Glance` (card face), `vals`
/// the flattened elements — a slot is `None` where the node left it empty. `jac` is the tick's own
/// row-major `vals.len() × sum(dep lens)` local Jacobian — never carried forward — with entries
/// `None` where the engine saw no signal (NaN doesn't survive serde_json).
///
/// `ran` is the other half of `fired`, and the engine's own answer rather than a re-derivation: a
/// clocked node between publications did not fire and *was* stepped; one the sweep skipped did
/// neither.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct Activation {
	pub node: String,
	pub deps: Vec<String>,
	pub gates: Vec<String>,
	pub out: String,
	pub ran: bool,
	pub fired: bool,
	pub dims: Vec<usize>,
	pub vals: Option<Vec<Option<f64>>>,
	pub jac: Option<Vec<Option<f64>>>,
	/// The reading [`jac`](Self::jac) is silent about, where the kernel has one. `None` where it has
	/// none, and then the column is the whole of what can be said.
	pub exact_block: Option<ExactBlock>,
	/// As [`TopoNode::cost_ns`] — carried here too so a card can show it without a second fetch.
	pub cost_ns: Option<f64>,
	/// Whether [`jac`](Self::jac) was differentiated or finite-differenced. Not a claim about how
	/// much of the dep's reach the column covers — that is [`TopoNode::fidelity`].
	pub exact: bool,
}

/// A tick's derivative over every element a body reached back over, not just the newest: per dep in
/// `deps` order, `vals.len() × widths[d]` row-major and appended, oldest lag first — so a dep's last
/// element-group is exactly its [`Activation::jac`] column. `None` entries for the same reason
/// `jac`'s are: NaN does not survive serde_json.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct ExactBlock {
	pub cols: Vec<Option<f64>>,
	/// `lags(d) * slots(d)`, positional with `deps`; prefix sums recover `(dep, lag, slot)`.
	pub widths: Vec<usize>,
}

/// Replay position + the last tick's activations. `tick` counts consumed events (0 = nothing
/// replayed yet); `ts_ns` is the last consumed print's timestamp (0 at start).
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct ActivationFrame {
	pub tick: usize,
	pub total: usize,
	/// The recording is over: `total` will not grow again.
	pub sealed: bool,
	/// Ticks the graph stepped that the tape never got, because the recorder was running under
	/// `Backpressure::Drop` and the handoff was full. Non-zero means the run outpaced its own viz —
	/// the gap is in the tape, and this is what says so rather than it reading as a quiet market.
	pub dropped: usize,
	/// This op ran out of recorded ticks — re-issuing it later will get further.
	pub pending: bool,
	/// The scan this frame answers reached what it was looking for. `true` for every op that is not
	/// a scan, so a `false` here is a search that walked to the end of a sealed recording and found
	/// nothing — which without saying so reads as a dead key.
	pub found: bool,
	/// Absolute ticks this retained tick stands for: its distance from the previous retained one, so
	/// `1` is a contiguous stretch and anything larger is the resolution thinning has left here.
	pub gap: usize,
	pub ts_ns: i64,
	pub activations: Vec<Activation>,
}

#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
pub struct StepReq {
	pub n: usize,
}

#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
pub struct SeekReq {
	pub tick: usize,
}

#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
pub struct SeekTsReq {
	pub ts_ns: i64,
}

#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct StepUntilReq {
	pub node: String,
}

#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct StepUntilChangeReq {
	pub nodes: Vec<String>,
}