Expand description
§GRIT — Grouped Reduced-precision Interchange Type
A conformant Rust implementation of the normative specification,
version 1 (spec/SPEC.md). No external dependencies, by design: GRIT
hashes with FNV-1a, which is nine lines of arithmetic, so a bootloader,
a WebGPU shim and a ggml build can all carry it.
A GRIT array is a quadruple (Grade, Placement, Planes, Shape)
denoting a logical array of binary32 values.
- Grade — the complete numeric contract, with one canonical string
form and a derived 64-bit id (
grade). - Placement — the physical layout, carried as a 64-bit value,
never as a type parameter (
placement). New silicon means a new constant, not a new type. - Planes — up to four byte buffers:
data,scale0,scale1,aux. - Shape — rank and extents, carried in the view, not the descriptor.
codec::decode is the normative semantics; everything else exists to
make “do these two tools agree about what these bytes mean?” checkable at
an O(1) boundary crossing (check::grit_check).
§The three claims, and the one GRIT refuses to make
- Equal
gid::Gidand equal plane bytes ⇒ bit-identical decode on every conformant implementation. This is testable, andtests/conformance.rsis the test. - A
grit_checkfailure is always a diagnostic, never undefined behaviour, for any 64-byte input including adversarial ones. gidcertifies decode agreement and nothing else — not calibration quality, not provenance, not trustworthiness.
§Example
use grit::typed::{GritTensor, Mxfp4};
use grit::check::GritCheck;
let vals: Vec<f32> = (0..32).map(|i| i as f32 * 0.125).collect();
let t = GritTensor::<Mxfp4>::encode(vec![32], &vals);
// The boundary result is #[must_use]: a check you can drop is not a check.
assert_eq!(t.check(2).status, GritCheck::Ok);
// The printable fingerprint is 26 Crockford base32 symbols, no hyphens.
assert_eq!(t.gid().to_string().len(), 26);Re-exports§
pub use check::grit_check;pub use check::GritCheck;pub use check::GritDetail;pub use check::GritError;pub use codec::decode;pub use codec::encode;pub use desc::desc_for;pub use desc::digest_of;pub use desc::grit_explain;pub use desc::GritDesc;pub use gid::Gid;pub use grade::canonicalize;pub use grade::grade_id_of;pub use grade::grade_parse;pub use grade::Grade;pub use grade::GradeError;pub use grade::Scope;pub use view::GritView;pub use view::PlaneRole;
Modules§
- audit
assume_placementand the audit ledger (SPEC 12).- check
grit_checkand the boundary result (SPEC 7).- codec
- Normative
decode()andencode()for the four reference grades (SPEC 8, 9, 10). - desc
grit_desc— the 64-byte descriptor (SPEC 3), plus the fingerprints derived from it (SPEC 6).- fmt
grit_fmt_t— the 16-bit format word (SPEC 2).- fnv
- FNV-1a, 64 and 128 bit (SPEC 6.1).
- gid
Gid— the 128-bit contract fingerprint, and its Crockford base32 printable form (SPEC 6.3, 6.4).- grade
- The Grade — the complete numeric contract, its canonical string form, its aliases and its 64-bit id (SPEC 4, 6.2).
- num
- Numeric preliminaries (SPEC 1).
- placement
- The placement word (SPEC 5).
- typed
- Optional typed wrappers.
- view
grit_view— a descriptor plus a shape plus four plane buffers (SPEC 3.1). The runtime, descriptor-driven face of GRIT; the typed wrappers incrate::typedare a thin layer on top and are optional.
Constants§
- GRIT_
SPEC_ VERSION - The descriptor version this crate implements.