grit/lib.rs
1//! # GRIT — Grouped Reduced-precision Interchange Type
2//!
3//! A conformant Rust implementation of the normative specification,
4//! version 1 (`spec/SPEC.md`). No external dependencies, by design: GRIT
5//! hashes with FNV-1a, which is nine lines of arithmetic, so a bootloader,
6//! a WebGPU shim and a `ggml` build can all carry it.
7//!
8//! A **GRIT array** is a quadruple `(Grade, Placement, Planes, Shape)`
9//! denoting a logical array of binary32 values.
10//!
11//! - **Grade** — the complete numeric contract, with one canonical string
12//! form and a derived 64-bit id ([`grade`]).
13//! - **Placement** — the physical layout, carried as a **64-bit value**,
14//! never as a type parameter ([`placement`]). New silicon means a new
15//! constant, not a new type.
16//! - **Planes** — up to four byte buffers: `data`, `scale0`, `scale1`, `aux`.
17//! - **Shape** — rank and extents, carried in the view, not the descriptor.
18//!
19//! [`codec::decode`] is the normative semantics; everything else exists to
20//! make "do these two tools agree about what these bytes mean?" checkable at
21//! an O(1) boundary crossing ([`check::grit_check`]).
22//!
23//! ## The three claims, and the one GRIT refuses to make
24//!
25//! 1. Equal [`gid::Gid`] **and** equal plane bytes ⇒ bit-identical decode on
26//! every conformant implementation. This is testable, and
27//! `tests/conformance.rs` is the test.
28//! 2. A `grit_check` failure is always a diagnostic, never undefined
29//! behaviour, for *any* 64-byte input including adversarial ones.
30//! 3. `gid` certifies **decode agreement and nothing else** — not
31//! calibration quality, not provenance, not trustworthiness.
32//!
33//! ## Example
34//!
35//! ```
36//! use grit::typed::{GritTensor, Mxfp4};
37//! use grit::check::GritCheck;
38//!
39//! let vals: Vec<f32> = (0..32).map(|i| i as f32 * 0.125).collect();
40//! let t = GritTensor::<Mxfp4>::encode(vec![32], &vals);
41//!
42//! // The boundary result is #[must_use]: a check you can drop is not a check.
43//! assert_eq!(t.check(2).status, GritCheck::Ok);
44//!
45//! // The printable fingerprint is 26 Crockford base32 symbols, no hyphens.
46//! assert_eq!(t.gid().to_string().len(), 26);
47//! ```
48
49#![forbid(unsafe_code)]
50#![warn(missing_debug_implementations)]
51// The spec is written in terms of a *logical element index* `i` that also
52// drives the group arithmetic (`g0 = i / k0`); rewriting those loops as
53// iterator chains would obscure the correspondence with SPEC 8.
54#![allow(clippy::needless_range_loop)]
55
56pub mod audit;
57pub mod check;
58pub mod codec;
59pub mod desc;
60pub mod fmt;
61pub mod fnv;
62pub mod gid;
63pub mod grade;
64pub mod num;
65pub mod placement;
66pub mod typed;
67pub mod view;
68
69pub use check::{grit_check, GritCheck, GritDetail, GritError};
70pub use codec::{decode, encode};
71pub use desc::{desc_for, digest_of, grit_explain, GritDesc};
72pub use gid::Gid;
73pub use grade::{canonicalize, grade_id_of, grade_parse, Grade, GradeError, Scope};
74pub use view::{GritView, PlaneRole};
75
76/// The descriptor version this crate implements.
77pub const GRIT_SPEC_VERSION: u32 = 1;