Skip to main content

exec_viz/
api_types.rs

1//! Wire shapes shared by the axum server (serializes) and the Dioxus web client (deserializes).
2//! `#[cfg]`-neutral — both features compile this module. The fat `/api/day` chart payload is
3//! deliberately absent from the client side: the web half holds it as an opaque JSON string and
4//! hands it straight to the chart shim.
5
6use serde::{Deserialize, Serialize};
7
8/// One node of the static graph, in step (= topo) order. Roots have empty `deps`. `dims` is the
9/// node's element shape (`[]` scalar); the client resolves dep dims by name from topology.
10/// `gates` are the node's control edges — the client's gate set is the union over all nodes.
11#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
12pub struct TopoNode {
13	pub node: String,
14	pub deps: Vec<String>,
15	pub gates: Vec<String>,
16	pub dims: Vec<usize>,
17	pub plots: Vec<PlotOut>,
18	/// Estimated nanoseconds this node spends per step — what ranks the graph by cost. `None` until
19	/// it has been stepped enough times for the estimate to be about the node rather than the
20	/// machine; see the recorder's `cost` module for what "estimated" means here.
21	pub cost_ns: Option<f64>,
22	pub fidelity: FidelityOut,
23	/// Simplified `∂out/∂dep`, one line per dep — `None` where the kernel has no algebra. Static:
24	/// the body is fixed, so only the values it is read against move tick to tick.
25	pub deriv: Option<String>,
26}
27
28/// Serde mirror of `trading_data_dag::Fidelity`: how much of what a node's body read its Jacobian
29/// covers. `omits`/`why` carry the kernel's own string, which is the whole point of the variant.
30#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
31#[serde(tag = "kind", rename_all = "lowercase")]
32pub enum FidelityOut {
33	Exact,
34	Partial { omits: String },
35	Opaque { why: String },
36}
37
38/// Serde mirror of `trading_data_dag::Ink`: l/c/a only — hue stays renderer-owned.
39#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
40pub struct InkOut {
41	pub l: f64,
42	pub c: f64,
43	pub a: f64,
44}
45
46#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
47pub struct GuideOut {
48	pub label: String,
49	pub value: f64,
50	pub ink: InkOut,
51}
52
53/// Serde mirror of `trading_data_dag::Plot`. `slots` indexes the node's flattened elements
54/// (empty = all of them), so a node whose out mixes units draws as several plots, each on its
55/// own scale, rather than as several nodes.
56#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
57pub struct PlotOut {
58	pub slots: Vec<usize>,
59	pub range: Option<(f64, f64)>,
60	pub guides: Vec<GuideOut>,
61	/// One name list per axis of the plot's shape, row-major — the cartesian product of them names
62	/// `slots` positionally. Empty = indices.
63	pub labels: Vec<Vec<String>>,
64	pub inks: Vec<InkOut>,
65	pub overlay: bool,
66	pub solo: bool,
67	pub bars: bool,
68	pub candles: bool,
69}
70
71/// One bucket's last fired flat out. What names its slots is the node's [`PlotOut::labels`] crossed
72/// out, which is where a field worth reading belongs — the chart's crosshair line and the DAG
73/// panel's hover both read it from there.
74#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
75pub struct PointOut {
76	pub ts_ms: i64,
77	pub vals: Vec<f64>,
78}
79
80/// One node's full-day output sampled once per 1m bucket (last fired value wins). `deps` lets
81/// the chart recompute topo depth without a second fetch; `gates` routes gate nodes to the
82/// chart's dedicated gates pane.
83#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
84pub struct SeriesOut {
85	pub node: String,
86	pub deps: Vec<String>,
87	pub gates: Vec<String>,
88	pub dims: Vec<usize>,
89	pub plots: Vec<PlotOut>,
90	pub points: Vec<PointOut>,
91	/// The node's declared clock in ms — the period one point *covers*, not the bucket it was sampled
92	/// into. `None` for a node that publishes whenever its inputs do. This is what lets the chart draw
93	/// a 1h candle a full hour wide on a 1m grid.
94	pub clock_ms: Option<i64>,
95}
96
97/// The `/api/day` chart payload, opaque to both the server and the wasm client (the chart shim is
98/// the only reader). Snapshotted per request — under a live feed it keeps growing.
99#[derive(Clone, Debug, Serialize)]
100pub struct DayOut {
101	pub series: Vec<SeriesOut>,
102	/// Node whose recorded series *is* the candle pane, read positionally as o·h·l·c·v — the chart
103	/// draws it there and skips it in the indicator panes. `None` when the graph has no price node,
104	/// and then nothing is skipped.
105	pub price_node: Option<String>,
106}
107
108/// One node's standing output as of the current tick: `fired` says whether it was *this* tick's
109/// work, while `out`/`vals` carry the last fired ones forward (`None` only before the node's first
110/// fire, or once that tick has left the ring). `out` is the node's own `Glance` (card face), `vals`
111/// the flattened elements — a slot is `None` where the node left it empty. `jac` is the tick's own
112/// row-major `vals.len() × sum(dep lens)` local Jacobian — never carried forward — with entries
113/// `None` where the engine saw no signal (NaN doesn't survive serde_json).
114///
115/// `ran` is the other half of `fired`, and the engine's own answer rather than a re-derivation: a
116/// clocked node between publications did not fire and *was* stepped; one the sweep skipped did
117/// neither.
118#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
119pub struct Activation {
120	pub node: String,
121	pub deps: Vec<String>,
122	pub gates: Vec<String>,
123	pub out: String,
124	pub ran: bool,
125	pub fired: bool,
126	pub dims: Vec<usize>,
127	pub vals: Option<Vec<Option<f64>>>,
128	pub jac: Option<Vec<Option<f64>>>,
129	/// The reading [`jac`](Self::jac) is silent about, where the kernel has one. `None` where it has
130	/// none, and then the column is the whole of what can be said.
131	pub exact_block: Option<ExactBlock>,
132	/// As [`TopoNode::cost_ns`] — carried here too so a card can show it without a second fetch.
133	pub cost_ns: Option<f64>,
134	/// Whether [`jac`](Self::jac) was differentiated or finite-differenced. Not a claim about how
135	/// much of the dep's reach the column covers — that is [`TopoNode::fidelity`].
136	pub exact: bool,
137}
138
139/// A tick's derivative over every element a body reached back over, not just the newest: per dep in
140/// `deps` order, `vals.len() × widths[d]` row-major and appended, oldest lag first — so a dep's last
141/// element-group is exactly its [`Activation::jac`] column. `None` entries for the same reason
142/// `jac`'s are: NaN does not survive serde_json.
143#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
144pub struct ExactBlock {
145	pub cols: Vec<Option<f64>>,
146	/// `lags(d) * slots(d)`, positional with `deps`; prefix sums recover `(dep, lag, slot)`.
147	pub widths: Vec<usize>,
148}
149
150/// Replay position + the last tick's activations. `tick` counts consumed events (0 = nothing
151/// replayed yet); `ts_ns` is the last consumed print's timestamp (0 at start).
152#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
153pub struct ActivationFrame {
154	pub tick: usize,
155	pub total: usize,
156	/// The recording is over: `total` will not grow again.
157	pub sealed: bool,
158	/// Ticks the graph stepped that the tape never got, because the recorder was running under
159	/// `Backpressure::Drop` and the handoff was full. Non-zero means the run outpaced its own viz —
160	/// the gap is in the tape, and this is what says so rather than it reading as a quiet market.
161	pub dropped: usize,
162	/// This op ran out of recorded ticks — re-issuing it later will get further.
163	pub pending: bool,
164	/// The scan this frame answers reached what it was looking for. `true` for every op that is not
165	/// a scan, so a `false` here is a search that walked to the end of a sealed recording and found
166	/// nothing — which without saying so reads as a dead key.
167	pub found: bool,
168	/// Absolute ticks this retained tick stands for: its distance from the previous retained one, so
169	/// `1` is a contiguous stretch and anything larger is the resolution thinning has left here.
170	pub gap: usize,
171	pub ts_ns: i64,
172	pub activations: Vec<Activation>,
173}
174
175#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
176pub struct StepReq {
177	pub n: usize,
178}
179
180#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
181pub struct SeekReq {
182	pub tick: usize,
183}
184
185#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
186pub struct SeekTsReq {
187	pub ts_ns: i64,
188}
189
190#[derive(Clone, Debug, Deserialize, Serialize)]
191pub struct StepUntilReq {
192	pub node: String,
193}
194
195#[derive(Clone, Debug, Deserialize, Serialize)]
196pub struct StepUntilChangeReq {
197	pub nodes: Vec<String>,
198}