Brummel
cd3d1ca9ed
Motivation
----------
`Scalar` was a tagged enum (I64/F64/Bool/Ts), so every scalar value
physically carried its own kind tag. But the kind is already known from
the schema/port/column the value flows through (C7: the type is a
property of the column, not of the value — the hot path is already
columnar `Column<T>`, and `AnyColumn::get` *reconstructs* the tag from
the column on the way out). The per-value tag was therefore redundant
with the kind the surrounding context already holds.
That redundancy had three costs:
* It baked an implicit `match` (a branch) into every function that read
a Scalar payload — even where the caller statically knew the type.
The tag could never be exploited away.
* Size: a tagged enum is tag + payload = 16 bytes (f64/i64 alignment),
twice the 8 bytes the value needs. A `Column<Scalar>` would be double
the memory and half the cache utilisation.
* It is the shared root of several downstream papercuts we keep hitting
— the lossy f64 manifest field, the `unreachable!` panic on a
non-numeric param, the serde-tag question — all symptoms of "the type
is baked into the value".
Change
------
Introduce `Cell`: a type-erased 64-bit word (`struct Cell(u64)`) that is
not readable without external type context. It is constructed per base
type (`from_i64/from_f64/from_bool/from_ts`) and read only by naming the
type at the call site (`i64()/f64()/bool()/ts()`) — each a branch-free
bit-cast. The hot path resolves the kind once at the boundary (from the
schema) and then reads natively, with no per-value branch. `Cell` knows
nothing of `Scalar` or `ScalarKind`; the dependency is strictly one-way,
and it lives in its own `cell.rs` (more is planned on top of it).
`Scalar` becomes `struct { kind: ScalarKind, cell: Cell }` — the
self-describing form for the dynamic boundaries (builder binding,
serialization, rendering), built on top of `Cell`. Its `as_*` accessors
now `debug_assert` the kind and return the native value (free in
release); calling the wrong accessor is a caller bug, not a checked
`Option`. The variant constructors `Scalar::I64(..)` become associated
fns `Scalar::i64(..)`.
`PartialEq` is hand-written (not derived) to preserve the former enum's
value semantics: kinds must match, then native payloads compare, so f64
keeps IEEE-754 behaviour (`NaN != NaN`, `+0.0 == -0.0`) and a kind
mismatch is never equal even when the raw words coincide. A fixture
(`scalar_eq_is_value_not_bitwise`) pins exactly the cases where bit- and
value-equality diverge, so it can't silently regress. `Cell`'s own
`Eq`/`Hash` stay bitwise — correct for a raw word.
The change is behaviour-preserving: Scalar's observable behaviour is
identical to the pre-Cell enum (the value-equality fixture proves it);
only the internal representation changed. The ~440 call sites across the
workspace are a mechanical constructor rename plus ~12 destructuring
sites (match-arms / `let`-patterns) rewritten to `kind()` + `as_*`.
Verified: cargo build --workspace --all-targets, cargo clippy --workspace
--all-targets -- -D warnings, cargo test --workspace — all green.
93 lines
4.2 KiB
Rust
93 lines
4.2 KiB
Rust
//! `aura-engine` — the headless, UI-agnostic reactive SoA engine.
|
|
//!
|
|
//! Delivered across cycles 0003-0004 — the harness and its deterministic run
|
|
//! loop:
|
|
//!
|
|
//! - [`Harness`] — the closed root graph that runs (a flat node array + an index
|
|
//! edge table, topologically ordered) and its deterministic `run` loop: a
|
|
//! k-way merge of timestamped sources (C3/C4) driven through a wired DAG of
|
|
//! nodes, cycle by cycle, with freshness-gated recompute and the two firing
|
|
//! policies (C5/C6) deciding when each node re-evaluates and what it holds.
|
|
//! - [`Edge`] / [`Target`] / [`SourceSpec`] — producer->consumer wiring,
|
|
//! source->consumer wiring, and a declared source (its kind + target slots).
|
|
//! - [`BootstrapError`] — wiring faults caught once, at bootstrap (kind
|
|
//! mismatch, bad index, directed cycle).
|
|
//!
|
|
//! Delivered in cycle 0009 — the run report surface:
|
|
//!
|
|
//! - [`RunMetrics`] / [`RunManifest`] / [`RunReport`] — the `(manifest, metrics)`
|
|
//! pair C18 mandates per run, with [`RunReport::to_json`] for the structured
|
|
//! C14 face;
|
|
//! - [`summarize`] — the post-run pure reduction over a run's recorded
|
|
//! pip-equity + exposure streams into [`RunMetrics`]; [`f64_field`] bridges a
|
|
//! recording sink's `Vec<Scalar>` rows to it.
|
|
//!
|
|
//! Orchestration families of the atomic sim unit
|
|
//! (`(topology + params + data-window + seed)`) ship along three of C12's axes: the
|
|
//! **grid** axis via [`sweep`] over a [`GridSpace`] into a [`SweepFamily`], the
|
|
//! **window** axis via [`walk_forward`] over a [`WindowRoller`] into a
|
|
//! [`WalkForwardResult`] (C12 axis 3: rolling in-sample/out-of-sample splits, the
|
|
//! in-sample optimize closure-supplied), and
|
|
//! the **seed** axis via [`monte_carlo`] over a seed set into an [`McFamily`]
|
|
//! (C12 axis 4: Monte-Carlo *is* a sweep over seeds; both drive one shared
|
|
//! disjoint-parallel executor). The **seed** input itself ships too:
|
|
//! [`SyntheticSpec`] is a seeded `Source` producer (`Fn(u64) -> impl Source`,
|
|
//! C12 seed-as-input) whose stream is fully seed-determined, making
|
|
//! [`RunManifest`]'s seed a live captured input; the atomic unit's `-> metrics`
|
|
//! reduction ships via [`summarize`].
|
|
//!
|
|
//! Still to come (subsequent cycles): the broker-independent position-event
|
|
//! output and downstream broker nodes (C10), the random param-sweep
|
|
//! orchestration axis, and registry lineage across a family.
|
|
//!
|
|
//! Visualization is never here: it is a downstream consumer node on the streams.
|
|
|
|
mod blueprint;
|
|
mod builder;
|
|
mod graph_model;
|
|
mod harness;
|
|
mod mc;
|
|
mod report;
|
|
mod sweep;
|
|
mod walkforward;
|
|
|
|
pub use blueprint::{
|
|
BindError, Binder, BlueprintNode, CompileError, Composite, OutField, Role,
|
|
SweepBinder,
|
|
};
|
|
pub use builder::{BuildError, GraphBuilder, InPort, NodeHandle, OutPort, RoleHandle};
|
|
pub use graph_model::model_to_json;
|
|
pub use harness::{
|
|
window_of, BootstrapError, Edge, FlatGraph, Harness, Source, SourceSpec, SyntheticSpec, Target,
|
|
VecSource,
|
|
};
|
|
pub use report::{f64_field, summarize, RunManifest, RunMetrics, RunReport};
|
|
pub use sweep::{sweep, GridSpace, SweepError, SweepFamily, SweepPoint};
|
|
pub use mc::{monte_carlo, McAggregate, McDraw, McFamily, MetricStats};
|
|
pub use walkforward::{
|
|
param_stability, walk_forward, RollMode, WalkForwardError, WalkForwardResult,
|
|
WindowBounds, WindowOutcome, WindowRoller, WindowRun,
|
|
};
|
|
// #29: re-export the core scalar vocabulary a Blueprint builder needs
|
|
// (SourceSpec.kind is a ScalarKind; sources/Recorder columns are Scalar /
|
|
// Firing / Timestamp) so a graph builder has one import surface, not two.
|
|
pub use aura_core::{Firing, NodeSchema, ParamSpec, PortSpec, Scalar, ScalarKind, Timestamp};
|
|
|
|
#[cfg(test)]
|
|
mod test_fixtures;
|
|
|
|
#[cfg(test)]
|
|
mod reexport_tests {
|
|
// #29: the core scalar vocabulary a Blueprint builder needs is reachable
|
|
// from aura-engine alone (crate::X == external aura_engine::X), so a
|
|
// downstream author does not add a second aura-core import for ScalarKind.
|
|
#[test]
|
|
fn core_scalar_vocabulary_is_reexported_from_crate_root() {
|
|
use crate::{Firing, Scalar, ScalarKind, Timestamp};
|
|
let _k: ScalarKind = ScalarKind::F64;
|
|
let _f: Firing = Firing::Any;
|
|
let _s: Scalar = Scalar::f64(0.0);
|
|
let _t: Timestamp = Timestamp(0);
|
|
}
|
|
}
|