v1.1.0 live on npm + crates.io + PyPI

The 64 bytes your checkpoint is missing

A quantized tensor's exact meaning — its zero-point convention, its shared-exponent rule, its layout — lives in tool source code today, not in the file that carries the bytes. GRIT is a checkable interchange type: a 64-byte descriptor plus a normative decode law set, verifiable in O(1) at every producer–consumer boundary. One spec, 68 conformance vectors, five zero-dependency implementations that agree byte for byte.

▶ Open the workbench GitHub Install

# works on files you already have — no descriptors required
$ pip install grit-datatype
$ python3 -m grit.scan model.gguf
[disagreement] general.file_type = 15 (MOSTLY_Q4_K_M) declares this file
  is mostly Q4_K, but Q4_K holds 2.5% of tensor bytes
[warning] zero-point convention inferred as zpc=minus1 — byte-identical
  to zpc=asis at the container level; decoded values differ
# exit 2 — machine-readable, CI-gateable

The story

Why GRIT exists

It started with a simple question: when a quantized checkpoint moves between two tools, what, exactly, promises that both sides decode the same numbers?

The answer, we found, is nothing. The formats that carry today's quantized models — GGUF, safetensors — record shapes, dtypes, and byte offsets. They do not record the decode semantics: which shared-exponent rounding the producer used, whether a zero-point is stored as-is or minus one, how scale planes interleave with data. Those decisions live in the source code of whichever tool wrote the file. Change tools, and you are trusting that two codebases independently made the same undocumented choices.

So we downloaded four real, popular checkpoints and read them byte by byte. In a corpus of just four files we found a GGUF whose declared file type disagreed with what the tensor bytes actually were, and two quantization families whose serializations are byte-identical at the container level while their decoded values differ — the file itself cannot tell you which numbers it contains.

Four files were enough to find checkpoints that cannot prove what's inside them. That is not a corner case; that is the default state of the ecosystem.

The keystone. Two sides, one crossing — and the contract is the piece that holds it up. One block in the stream is caught mid-flight.

GRIT is the smallest fix we could specify completely: a grade — a canonical string that pins every decode decision — compressed into a 64-byte descriptor a producer writes once and a consumer checks in constant time. No new container, no re-encoding, no server. And because nobody emits descriptors yet, GRIT ships grit scan: a read-only auditor that applies the same discipline to the files you already have, today.

The claim is deliberately narrow and fully verified: one spec, five implementations in five languages, 68 conformance vectors, and a cross-language identity check that agrees 96/96 — all reproducible from a clean checkout.

How we decided to do what we do

A rule, before a line of code

GRIT did not start as a product idea. It started as a dare: find something genuinely missing — and only build it if the gap survives an adversarial attempt to prove it already exists.

So before writing anything, we swept the landscape and tried to kill our own idea: MLIR's sub-channel quantized types, StableHLO's DotAlgorithm, compressed-tensors, Avro's canonicalize-then-fingerprint discipline, the Khronos Data Format Specification, DLPack, torchao, TOSA's block-scaled types. Every claim of novelty had to survive a review panel whose explicit job was to refute it. What didn't survive was retracted before it was ever published — the spec's own claims table names the closest prior work for every component, because a contract type that oversold itself would be its own counterexample.

What survived the sweep was not a format — formats abound. It was the absence of a contract: nothing at any producer–consumer boundary checks that two tools mean the same thing by the same bytes. That decided the shape of everything: a checkable type, not another container.

The second decision was method. GRIT is built by a human–AI team working in the open: singhpratech sets direction, constraints, and the standard of evidence; Claude (Anthropic) does the orchestrated heavy lifting — five implementations written and cross-verified, an exact-arithmetic oracle sweeping tens of thousands of float values against every encoder, and a three-reviewer hostile panel that attacked the paper before anyone else could. The working rules never changed: every number must regenerate from a clean checkout, and every reviewer finding gets fixed or documented as a limitation — never softened.

Nothing here asks to be trusted. Everything here asks to be checked.

Four-panel wordless comic: two robots hold the same file but imagine different grids; the badger auditor's loupe reveals one amber byte; the badger stamps the file with the glowing descriptor seal; the robots cross a keystone bridge now imagining identical grids, badger giving a thumbs-up — The whole idea, wordlessly: same bytes, two meanings — until the contract is stamped on the file and both sides finally agree.

Design

One quadruple, four questions

GRIT models a quantized tensor as (Grade, Placement, Planes, Shape) — four orthogonal answers to four questions a consumer must ask before decoding a single byte.

Grade

What do the bytes mean?

The complete numeric contract as a canonical string — e.g. grit1(e=e2m1,k0=32,s0=e8m0,esr=exp2floormaxabs) — pinning element format, group sizes, scale formats, zero-point convention, and the rounding rules containers cannot express.

Placement

Where does each byte live?

The physical layout as a 64-bit value, not a type parameter: well-known layouts by ID, tool-local layouts by hash, opaque layouts declared honestly as opaque.

Planes

Which bytes are they?

Up to four byte buffers — data, scale0, scale1, aux — whose exact lengths the descriptor predicts, and the check verifies.

Shape

What geometry do they carry?

Rank and extents, carried in the view and hashed into the gid — the size equations tie all four together in constant time.

The grade canonicalizes to a 64-bit grade_id; grade + frame + shape fingerprint to a 128-bit gid (FNV-1a). Two tools holding the same gid hold the same contract — computed identically, bit for bit, by all five implementations.

The descriptor

64 bytes, no allocation, no parsing

The descriptor is a fixed-layout POD struct — every field at a fixed offset, little-endian, no variable-length anything. A consumer validates it against a shape and plane lengths in constant time: 296 ns in C on a laptop core, and +2.7 ms total to check every tensor while loading a 1 GB checkpoint.

Offset

Field

Meaning

[0, 8)

magic · ver · flags

Magic, header size, version, level count, flag bits (zero-point presence & convention, sparsity, bit order, interleave)

[8, 16)

elem · scales · zp

Element format, level-0/level-1 scale formats, zero-point format — from a closed format ladder (e2m1, e8m0, e4m3, u4, u6, s8, …)

[16, 22)

axis · k0 · k1

Group axis and group sizes for one- or two-level block scaling

[22, 28)

sparse · container

n:m sparsity, metadata format and ordering, container packing (dense / pad-to-8)

[28, 32)

note

The one mutable field — assumption provenance. Excluded from every fingerprint, so annotating a file never changes its identity.

[32, 56)

placement × 3

64-bit placement IDs for data, scale, and metadata planes — well-known, hashed, or opaque

[56, 64)

grade_id

FNV-1a-64 of the canonical grade string — the semantic anchor the structural fields cannot carry

Everything above is testable in your browser right now — the workbench runs the actual published npm implementation, byte for byte, so you can build a descriptor, corrupt any byte, and watch the check name the exact first failure.

Field findings

What four real checkpoints revealed

GRIT's evaluation is a field study, reported honestly: four popular quantized checkpoints (GGUF and safetensors), read byte by byte, first by hand and then by grit scan. Four files — existence, not prevalence — and they were enough.

Cartoon honey badger auditor with inspector spectacles, a loupe, and a clipboard showing a byte grid with one amber square flagged — Gritter — the GRIT critter. Auditor by trade, fearless against formats 100× its size.

Finding A · file_type_mismatch

The file's own label disagrees with its bytes

A GGUF declaring one MOSTLY_* file type while a different quantization dominates the actual tensor bytes. GGUF is self-describing per tensor, but nothing had ever cross-checked the summary against the contents. The scanner now does, automatically.

Finding B · zp_convention_ambiguous

Byte-identical files, different numbers

Two 4-bit zero-point conventions (zpc=asis vs zpc=minus1) whose serializations are indistinguishable at the container level. 168 modules in one real checkpoint carry bytes whose decoded values depend on a convention recorded nowhere in the file. A GRIT grade pins it in one field.

Finding C · gid_mismatch

One flag bit, isolated across files

Cross-file fingerprint comparison on real vendor bytes isolates a single flag-bit difference between checkpoints that claim the same format — the kind of drift a human diff of two multi-gigabyte files never surfaces.

After the study, the scanner's gaps were closed and it was re-run on bit-identical bytes: the corpus went from 12 hand-verified findings to 349 automatic ones, with a false-positive control (two known-clean files, zero findings, exit 0). The full experiment log ships in the repo under audit/.

Verification

Five implementations, one behaviour

Every claim below is checked in CI on every push, and reproducible from a clean checkout via REPRODUCING.md — prerequisites, exact commands, expected outputs.

conformance vectors, SHA-256-pinned (34 positive · 15 negative · 16 fingerprint · 3 supersedes)

zero-dependency implementations: C (C11), C++ (C++20), Rust, Python (stdlib), TypeScript

96/96

cross-language gid agreement — 96 descriptors fingerprinted identically by all five, in CI

1,963

checks across suites: C 910 · C++ 801 · Rust 37 · Python 124 · TypeScript 91

296 ns

level-1 boundary check in C (i9-13900HK); 9.8 µs in pure Python

runtime dependencies, in every language. The C header amalgamates to a single file.

Honesty

What GRIT does not claim

The spec and paper carry a threats-to-validity section; the short version lives here, because a contract type that oversold itself would be its own counterexample.

v1 cannot express everything. FNUZ float variants, NF4's codebook, and GPTQ act-order permutations are outside the v1 grade grammar — the scanner says so explicitly (inferred_inexpressible) rather than approximating.
The field study is n=4. It establishes that undeclared-contract mismatches exist in popular checkpoints, not how often. A prevalence sweep is future work.
Inference is not declaration. On descriptor-less files, grit scan infers a contract and labels it inferred; only a producer-written descriptor is a declaration.
The check bounds structure, not values. The size equations decide length agreement in O(1); catching corrupted contents requires the optional level-2 digest (0.46 GB/s in C).
Fingerprints are not adversarial. FNV-1a offers no collision resistance against a determined adversary; gids defend against drift and mislabeling, not attack.
Adoption is a chicken-and-egg problem. Nobody emits descriptors yet. That is exactly why the scanner works descriptor-free — the audit value arrives before the ecosystem does.

Install

Pick a language, get the same behaviour

All three registries publish the same version in lockstep with the repo tag. Every package passes the same 68 conformance vectors.

Python v1.1.0

pip install grit-datatype
python3 -m grit.scan model.gguf

Pure stdlib. Ships the scanner, the codec, and the reference vectors.

Rust v1.1.0

cargo add grit-datatype

no_std-friendly core, zero dependencies, 37 tests + conformance suite.

TypeScript v1.1.0

npm install grit-datatype

Node ≥18, zero dependencies. The same bytes power the workbench.

C / C++ in-tree

git clone https://github.com/\
singhpratech/grit-datatype

c/grit.h + c/grit.c (C11) and a single-header C++20 port — vendor them directly; there is nothing to link.

About the author

Built in the open by singhpratech

singhpratech is an independent engineer who builds verification-obsessed open source: small, sharply-scoped tools where every claim is backed by a test you can run yourself.

The through-line across the projects is the same conviction that produced GRIT: infrastructure should be able to prove what it does. Formats should carry their own contracts, engines should expose their own evidence, and a README number nobody can reproduce is a bug.

GRIT is the most complete expression of that so far — a spec, five agreeing implementations, and a paper whose every figure regenerates from a clean checkout. It is built in the open with Claude (Anthropic) as repository co-author: the human sets direction and the bar for evidence; the AI does the orchestrated implementation and adversarial review; nothing ships until the tests agree with both.

github.com/singhpratech

ferrovec — the in-browser vector store that remembers: Rust→WASM HNSW, persisted to OPFS, consistent across tabs.

crimson-crab — a Rust SDK for Claude that won't panic on you: unwrap/expect denied at compile time.

samkhya — engine-agnostic cardinality correction for embedded analytical engines, with a never-regress clamp.

mcp-turnstile — a token-cost and metadata-safety report card for any MCP server, deterministic by design.

diskhoji — a fast, beautiful disk space analyzer in one ~6 MB native Rust binary.

gpuviewer — the GPU flight recorder: always-on history with narrated throttle/OOM/hang causes.