Skip to main content

Crate grit

Crate grit 

Source
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

  1. Equal gid::Gid and equal plane bytes ⇒ bit-identical decode on every conformant implementation. This is testable, and tests/conformance.rs is the test.
  2. A grit_check failure is always a diagnostic, never undefined behaviour, for any 64-byte input including adversarial ones.
  3. gid certifies 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_placement and the audit ledger (SPEC 12).
check
grit_check and the boundary result (SPEC 7).
codec
Normative decode() and encode() 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 in crate::typed are a thin layer on top and are optional.

Constants§

GRIT_SPEC_VERSION
The descriptor version this crate implements.