From f51d54a1c191bc668c764ff4e815ea7c88747c55 Mon Sep 17 00:00:00 2001 From: Brummel Date: Mon, 22 Jun 2026 11:24:08 +0200 Subject: [PATCH] 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 --- crates/aura-core/src/cell.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/crates/aura-core/src/cell.rs b/crates/aura-core/src/cell.rs index 3d89e8b..f0814af 100644 --- a/crates/aura-core/src/cell.rs +++ b/crates/aura-core/src/cell.rs @@ -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);