Crate verit 

verit — Exavian Veritate

The public umbrella crate. One serialization format that is all three things at once — zero-copy, self-describing, and schema-evolvable — with no unsafe, an opt-in amplification-DoS budget, and one wire spec implemented byte-for-byte across six independent implementations (Rust, Python, C++, Go, TypeScript, and a GnuCOBOL port).

Consumers depend only on verit. Everything real lives in the internal verit_core engine; this crate is the single public seam that re-exports it, so the engine can be split or rewritten from one edit point. The internal crates (verit-core, verit-cli) must never be imported directly.

use verit::prelude::*;

let schema = SchemaBuilder::new()
    .add_struct("Point", vec![(1, "x", Dt::F64), (2, "y", Dt::F64)])
    .build("Point")?;
let bytes = encode(&schema, &Value::Struct(vec![
    (1, Value::F64(1.5)), (2, Value::F64(-0.5)),
]), SchemaMode::Inline)?;
assert_eq!(dump_json(&bytes)?, r#"{"x":1.5,"y":-0.5}"#);

The wire format is specified in docs/Architecture/VERIT - Wire Specification.md; the crate map is in VERIT - System Architecture.md.

Modules

codegen

Rust code generation: compile a Schema into typed readers and writers.

container

.vertc — the Veritate container: an at-rest file holding many messages for zero-copy random access, designed to be mmap-ped and read in place.

derive

Runtime support for #[derive(Verit)] — the Rust peer of Python’s @verit decorator.

dump

The self-description proof: given message bytes and nothing else, recover the writer schema from the inline region and render every present field — with its human-readable name — as JSON.

encode

Encoder: Schema + Value tree → message bytes.

error

file

.verit — the Veritate file: many messages in one self-contained, mmap-able, appendable file.

hash

Content hashing for schema ids.

idl

The .vsc schema IDL — a small text front-end that compiles to a Schema. It invents no wire semantics: it drives SchemaBuilder, so the result is exactly the same canonical VSC1 bytes (and 128-bit id) any other definition of the same schema produces. The IDL therefore cannot drift from the wire format — the id is the contract, and it is computed the same way regardless of how the schema was written.

layout

Deterministic struct layout. Because the layout is a pure function of the schema, a schema id fully determines every byte offset — the schema acts as one shared “vtable” for every message that uses it, which is what makes per-message zero-copy access possible without per-object tables.

message

Zero-copy message access. Message::parse only reads the 24-byte header; nothing else is touched until a field is asked for, and every field read is a bounds-checked load straight out of the buffer through a precompiled Resolver plan. Strings and byte fields are returned as &str / &[u8] borrowing the message buffer — no allocation, no copy.

prelude

The common import surface for Exavian Veritate.

registry

Schema registry + distribution bundle for multi-service deployments.

resolve

Schema resolution: the piece that buys evolution without giving up zero-copy. A Resolver is built once per (writer schema, reader schema) pair and compiles, for every corresponding struct type, an access plan mapping each reader field ID to either a concrete byte slot in the writer’s layout (with an optional lossless widening) or Absent. After that, reading any number of messages costs no per-message resolution work.

schema

Schema model, builder, canonical binary encoding (“VSC1”), and content hashing. The canonical form sorts types by name, fields by ID, and enum variants by value, so one logical schema has exactly one byte encoding and therefore exactly one id.

value

Dynamic values for the write path. The prototype has no codegen; you build a Value tree against a runtime crate::Schema and encode it. A struct value lists (field id, value) pairs — omitted fields are absent (their presence bit stays 0 and readers see None).

wire

Public low-level wire primitives for generated code (see crate::codegen). Everything here is bounds-checked and unsafe-free; generated readers/writers compose these with offsets computed at generation time from the deterministic layout algorithm.

Structs

Budget

A per-read traversal budget — an opt-in guard against amplification-DoS on untrusted messages (the wire spec §5.2). Veritate’s offsets are absolute and may alias, so a small hostile message can point many fields at the same large sub-object and make a naive full read do work super-linear in the message’s own size. Memory safety (bounds, depth, allocation) always holds; a Budget additionally caps total work.

ContainerDeprecated

A read-only view over a .vertc container’s bytes (e.g. an mmap). Parsing validates the header and the whole index up front, so every later get is a bounds-free slice.

ContainerWriterDeprecated

Build a .vertc container from a sequence of Veritate messages. The output is a self-contained Vec<u8> you write to a file (and later mmap).

EnumDef

FieldDef

FileBuilder

Build a complete generation-1 .verit file in memory.

FileReader

A .verit file read into memory, owning its bytes.

FileView

A read-only, zero-copy view over a .verit file’s bytes (typically an mmap). open validates the header, footer, schema section, and every index entry up front, so each later get is a bounds-free slice.

FileWriter

A .verit file open for reading and writing, mutated by crash-safe append-only commits.

Footer

A parsed footer — the authoritative statement of a file’s committed state.

ListReader

Message

Record

One index entry: a record’s identity, where it lives, and which schema interprets it.

Resolver

Resolvers

One Resolver per distinct schema in a file, built once by FileView::resolvers.

Schema

A validated schema: canonical type table, cached canonical bytes, content id, and precomputed struct layouts.

SchemaBuilder

Declaration order never matters: build sorts types by name and fields by ID before encoding, so equivalent declarations produce identical schema ids.

SchemaRegistry

A content-addressed store of schemas, keyed by their 128-bit id.

StructDef

StructReader

Enums

Default

A scalar custom default for a field: the value a reader synthesizes when the field is absent (see StructReader::get_or_default). v1 supports scalar defaults only; floats are stored as their bit patterns so the schema types stay Eq.

Dt

Draft type used in SchemaBuilder: like Type but names other types by string instead of index (indices only exist after canonical sorting).

Error

Ref

A field value read from the buffer. Scalars are by value; strings, bytes, structs, and lists borrow the message buffer ('b).

Scalars

A run of scalars held in its native Rust form.

SchemaMode

StructMode

How a struct’s fields are stored.

Type

A field or element type. Struct/Enum reference other types in the same schema by index into the canonically (name-)sorted type table.

TypeDef

Value

Constants

FIRST_RECORD_ID

Record ids start at 1, so 0 is available as “no record”.

OPT_RECORD_CRC

optional_features bit 0 — the file carries a CRC-32 per record.

VERSION

The crate version string, from Cargo.toml.

Traits

VeritType

Implemented by every #[derive(Verit)] type. All of it is generated; you never write an impl by hand. The provided methods (to_verit, from_verit, verit_schema_id) are the surface you actually call.

Functions

dump_json

Decode a message using only its own bytes. Requires the message to have been encoded with crate::SchemaMode::Inline.

dump_json_with

Render a hash-only message using a writer schema supplied from outside the message — a registry, or a .verit file’s schema section. Same output as dump_json; the difference is only where the schema came from.

encode

Type Aliases

Result

Derive Macros

Verit

#[derive(Verit)] — generate a schema, encoder, and decoder from a plain Rust struct (the peer of Python’s @verit). Available with the derive feature: verit = { version = "…", features = ["derive"] }. See VeritType for what it generates. Derive VeritType for a named-field struct.