docs(cell): name Scalar as the param-authoring surface; no tagged Cell ctors by design

Cell is the kind-erased hot-path carrier (C7): the value carries no tag, so
there are deliberately no tuple-style/tagged constructors (`Cell::I64(..)`).
Document on the struct that Scalar is the value to reach for when authoring a
param / bind / sweep point / RunManifest field, and that the from_* ctors are the
carrier-side entry. Resolves the discoverability papercut without softening the
carrier split.

closes #100
This commit is contained in:
2026-06-22 11:24:08 +02:00
parent 5a01179fd5
commit f51d54a1c1
+10
View File
@@ -19,6 +19,16 @@ use crate::scalar::Timestamp;
/// same integer word, `f64` via its IEEE-754 bit pattern. `Eq`/`Hash` are
/// bit-exact (so `+0.0`/`-0.0` differ and a `NaN` bit pattern equals itself) —
/// the semantics of a raw word, not of a number.
///
/// **Authoring vs. carrier — reach for [`Scalar`](crate::scalar::Scalar) to
/// build a value.** `Cell` is the hot-path *carrier*, so it deliberately has no
/// tuple-style or tagged constructors (`Cell::I64(3)` does not exist, by design,
/// not omission). When *authoring* a value — a node param, a `bind`/sweep point,
/// a `RunManifest` field — use `Scalar`, the kind-tagged, self-describing carrier
/// of the param plane. The `from_i64`/`from_f64`/`from_bool`/`from_ts` ctors here
/// are the carrier-side entry used once a value crosses into the kind-erased hot
/// path; a self-describing `Cell::I64` would re-introduce the very tag the
/// carrier split strips (C7).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct Cell(u64);