Strata

Deterministic data language with canonical binary encoding.

This crate is the reference Rust implementation of Strata.

Same data → same bytes → same hash.
No ambiguity. No normalization. No silent coercions.

Golden vectors are law.

View the Documentation

What is Strata?

Strata is a strict, minimal data model with a fully deterministic binary encoding.

It is designed for systems where:

data integrity is non-negotiable
hashes must be stable forever
cross-language verification is required
ambiguity is unacceptable

Strata draws a hard line between representation and truth:

Value is an in-memory representation
canonical .scb bytes define truth
hashes are computed only from canonical bytes

What this crate provides

This crate defines canonical truth for Strata.

It provides:

Canonical encoder for Strata Core Binary (.scb)
Safe decoder with explicit, structured errors
Parser for Strata Text (.st)
Deterministic BLAKE3 hashing
Production-grade CLI
Golden vector enforcement
Reference semantics for all other implementations

If another language disagrees with this crate, the other language is wrong.

Installation

cargo add strata-rs

Or in Cargo.toml:

[dependencies]
strata-rs = "*"

Value model

Strata supports a fixed, closed value model:

Value =
    Null
  | Bool(bool)
  | Int
  | String
  | Bytes
  | List(Value*)
  | Map(string → Value)

Rules:

Integers are explicit (no floats, no implicit coercions)
Strings are UTF-8
Map keys are strings only
Bytes are raw bytes
Duplicate map keys are allowed
No floats
No NaN
No normalization

The model is intentionally small.
Power comes from determinism, not expressiveness.

Constructing values (Rust)

Values may be constructed manually or using DX macros.
Macros are pure sugar and do not affect canonical encoding or hashing.

use strata_rs::value::Value;

let value = map! {
    "id" => int!(42),
    "name" => string!("Gencho"),
    "active" => bool!(true),
    "skills" => list![
        string!("rust"),
        string!("systems"),
    ],
    "meta" => map! {
        "a" => int!(1),
        "a" => int!(2), // last-write-wins
    },
};

Available macros:

null!()
bool!(...)
int!(...)
string!(...)
bytes!(...)
list![ ... ]
map!{ "k" => v, ... }

Macros construct the exact same Value structures as manual code.

Canonical encoding

Encoding is fully deterministic.

Rules include:

Maps are sorted by UTF-8 byte order
Integers use canonical varint encoding
Strings are stored as raw UTF-8 bytes
Bytes are preserved verbatim
Duplicate keys resolve via last-write-wins

Identical values always produce identical .scb bytes.

use strata_rs::encode::encode_value;

let bytes = encode_value(&value)?;

Decoding guarantees

The decoder is strict and transparent.

It:

Never panics on input
Rejects malformed data explicitly
Preserves observable structure
Allows duplicate keys for inspection

Decoding reveals reality.
Encoding enforces truth.

use strata_rs::decode::decode_value;

let value = decode_value(&bytes)?;

Hashing

Hashes are computed as:

BLAKE3-256(canonical_scb_bytes)

Example:

use strata_rs::hash::hash_bytes;

let hash = hash_bytes(&bytes);

Hashes are stable across:

machines
operating systems
compiler versions
programming languages

Parsing Strata Text (`.st`)

Strata Text is a human-friendly authoring format.

Example:

user {
  id: 42
  name: "Gencho"
  active: true
  skills: ["rust", "systems"]
}

Parsing:

use strata_rs::parser::parse;

let value = parse(source)?;

Text is never canonical.
Only encoded .scb bytes are.

CLI

This crate ships with a CLI for inspection and tooling.

Compile

strata compile input.st output.scb

Decode

strata decode input.scb

Hash

strata hash input.st
strata hash input.scb

Format

strata fmt input.st

Error model

All failures are explicit and structured.

Decode errors include:

InvalidTag
UnexpectedEOF
InvalidVarint
InvalidUtf8
TrailingBytes

Parse errors include:

Unexpected token
Integer out of range
Malformed literals
Line and column information

CLI exit codes:

Code	Meaning
0	Success
1	Invalid input
2	I/O failure
100	Internal error

Golden vectors

Canonical truth lives in /vectors.

This implementation:

Must match vectors exactly
Must never change vectors to satisfy code
Must fail when vectors say so

If vectors disagree with code, code is wrong.

Documentation

Canonical integration documentation lives in the Integration Reference:

Value model
Encoding / decoding boundaries
Hashing contract
Rust and JavaScript examples
Strictness rules and footguns

The Integration Reference is the single source of truth for integrators.

Versioning & Northstar

Strata evolution is governed by Northstar documents.

Northstar v1 – Canonical encoding
Northstar v2 – Decode & inspection
Northstar v2.1 – Explicit error semantics
Northstar v3 – Cross-language parity
Northstar v4 – Developer ergonomics & documentation

Any canonical change requires a new Northstar.

License

MIT License

Final note

This crate is intentionally strict.

It is designed for:

integrity-critical systems
deterministic pipelines
cross-language verification
audit-friendly storage

If convenience matters more than correctness, use something else.
If correctness matters, this is the reference.

strata-rs 0.4.2