Crate kaiv 

kaiv — reference implementation of the kaiv format, Levels 0–3 (Level 3 collation behind the default collation feature).

Pipeline (SPEC.md, ARCHITECTURE.md §7):

.kaiv --[compiler]--> .raiv --[denorm]--> .daiv --[validator + .csaiv]--> pass/fail
.saiv --[schema]----> .csaiv

The executable definition of “correct” is the conformance tree in the spec repo (spec/kaiv/conformance/); tests/conformance.rs runs it. The Lexer implements the eager parsing model: the whole text is validated before any token is emitted, and no tokens are emitted on error.

Re-exports

pub use builder::DaivBuilder;

pub use builder::Provenance;

pub use compiler::compile;

pub use compiler::compile_with;

pub use config::Config;

pub use denorm::denormalize;

pub use denorm::denormalize_with;

pub use error::AppError;

pub use error::LexError;

pub use error::LexErrorAt;

pub use error::PipelineError;

pub use lexer::lex;

pub use lexer::FileKind;

pub use resolve::Resolver;

pub use schema::check_type_lib;

pub use schema::compile_schema;

pub use schema::compile_schema_with;

pub use validator::parse_csaiv;

pub use validator::schema_for_daiv;

pub use validator::validate;

pub use validator::CompiledSchema;

pub use validator::ProvenanceLevel;

Modules

anno

Parsing of type annotations and constraint expressions — the two surface forms of the constraint grammar (SPEC.md § Formal Grammar): the whitespace-free annotation position (!int[1,65535]:s?prov) and the space-separated constraint-line position (/re/ ..num [1,65535]).

asn1

ASN.1 BER/DER import and DER export (--features asn1) — hand-rolled, zero dependencies, schema-less: BER/DER is structurally self-describing (every element carries a tag and length), so universal tags drive the mapping and no ASN.1 module is needed. PEM armor is stripped automatically on import; export writes raw DER.

avro

Avro import/export (--features avro) — Object Container Files (self-describing: the schema rides in the header as JSON, read with the crate’s own JSON parser), hand-rolled, zero dependencies.

builder

Programmatic construction of canonical .daiv documents.

cbor

CBOR import/export (--features cbor, RFC 8949) — a thin adapter over the value hub and the family’s first binary format; the decoder/encoder pair is hand-rolled, zero dependencies.

collate

Level 3 collation: locale-aware comparison for ..lex[locale] spans (SPEC.md § Level 3: Collation), built on ICU4X. The locale is a BCP 47 tag; comparisons run at the spec’s pinned defaults — tertiary strength, non-ignorable variables, no case level — unless the tag carries one of the recognized -u- collation extension overrides: ks (strength), ka (variable handling), kc (case level), co (named collation).

compiler

The Compiler: authored .kaiv → relational canonical .raiv. Resolves variables and syntactic sugar (+=, ;=, :=, +:=, blocks, maps, & core shorthands, unit canonicalization); preserves $field references for the Denormalizer.

config

Layer 2 build-time configuration: kaiv.kaiv (SPEC.md § Layer 2). The config file is the format’s own bootstrap — a kaiv document restricted to the Level 0 scalar subset, parsed by the core pipeline before any type resolution exists, so the configuration that drives resolution never needs resolution itself.

denorm

The Denormalizer: .raiv → .daiv. Resolves $field / $path::field references left-to-right against the field table and collapses $$ to a literal $ (SPEC.md § The “Almost Verbatim” Principle). References may appear mid-value; no forward references. When the data declares a schema, the Denormalizer is additionally schema-aware: it reads the compiled .csaiv and materializes absent optional fields — the resolved default, or !null — so every schema-declared field appears in .daiv, in schema-declared order (SPEC.md § Default Values, § Null Semantics “Materialization of Absent Fields”). A required field absent from the authored data is a build-time RequiredFieldSchemaError.

error

Error catalog per SPEC.md § Errors. Names match the spec strings exactly; the conformance runner compares against them.

faiv

Unit-definition (.faiv, Factor AIV) parsing — SPEC.md § Unit Definition Files. A library is a sequence of definition lines, each a dimension (expressed by unit reference, avoiding non-ASCII dimension symbols) plus a conversion factor to the dimension’s base unit, above a &name= line. Currencies use the dimension $, deliberately carry no factor, and may declare a rate-source URL template instead. &alias=name defines an alias.

graphql

GraphQL SDL → authored .saiv (--features graphql) — a sound weakening like the other schema converters: every emitted constraint is implied by the source, and what kaiv cannot express drops with a // comment.

infer

Schema inference: canonical kaiv text → an authored .saiv that the example document validates against. Types come from the canonical annotations (str/int/float/bool, std library types via &name + .!types); {int,float} widens to float and null joins as a union alternative; scalar arrays become ;= vector declarations, namespace arrays become [/@name]…[] blocks. A field missing from some elements is skipped with a comment (the strict-lockstep parallel scan would fail the source document on a declared-but-absent field), like every other shape outside the compiled subset — inferred schemas are relaxed, so skipped fields still validate.

json

JSON import/export (--features json). Import produces a flat authored .kaiv: top-level scalars become typed lines; anything not representable as a flat scalar line — nested containers, strings containing EOL/NUL, strings starting with $ — embeds as std/enc/json (base64url of its JSON text). Export inverts: canonical lines become a JSON object tree, std/enc/json payloads decode and splice verbatim.

jsonschema

JSON Schema → authored .saiv (--features json). The conversion contract is a sound weakening: every kaiv constraint emitted is implied by the source schema, and source constraints with no kaiv equivalent are dropped with a // comment — so any document valid under the source schema validates under the imported one, never the reverse. Local $refs (#/$defs/…, #/definitions/…) inline; title/description become doc comments; default rides the field’s right side; format date-time/date/time map to std/time.

lexer

The Lexer: the six-rule line classifier plus the document-level checks from SPEC.md § Parsing Requirements. Eager model: the whole text is validated before any line is handed to later stages.

proto

Protocol Buffers import/export (--features proto) — hand-rolled, zero dependencies. Unlike every other converter, the wire format is not self-describing: both directions are driven by a .proto schema (proto3; proto2 labels are tolerated), passed alongside the data, plus a message name when the file has more than one top-level message.

resolve

Type-library resolution, Layers 1–4 (SPEC.md § Type Registry Resolution): document-level .!registry overrides, then kaiv.kaiv build-time configuration, then — behind the default-on net feature — the hosted registries (redirect aliasing + the Layer 4 default hosts). Without net, a lookup that would need the network is a SchemaResolutionError. std/core is embedded and never resolved.

rex

Minimal regex engine for the pinned kaiv pattern dialect (SPEC.md § Formal Grammar, “Regex dialect”): literals, classes, ., anchors, grouping, alternation, greedy bounded quantifiers, and the escapes \d \. \/ \\ (any escaped punctuation is a literal).

schema

The schema compiler: authored .saiv → compiled .csaiv (SPEC.md § The Schema Compiler). Lowers named types — core and registry-resolved — to their constraint forms; carries requiredness in the =/?= operator; propagates the .!kaivschema header (including the strict modifier) verbatim.

table

Level 2 table machinery: authored table headers on section-open lines ([/@servers host=!,port=! min=1]) and the compiled .csaiv collection constraint lines they lower to (/@servers [unique::host,port] [min=1]) — SPEC.md § Table Declaration Syntax, § Table Declarations in the Compiled Schema.

taiv

Type-library (.taiv) parsing and the embedded std/core (SPEC.md § Type Library Files, § The std/core Standard Library). A library is a sequence of constraint lines accumulating above each &name= definition; std/core ships embedded (SPEC.md: bundled, never fetched) and is parsed by the same path as any other library.

toml

TOML import/export (--features toml) — a thin adapter over the value hub, exactly like the YAML pair. TOML’s four datetime flavors ride the hub’s typed-scalar channel as std/time named types (&datetime, &localdatetime, &date, &time) and emit back as bare TOML datetimes; in datetime-less targets they degrade to strings. TOML cannot represent null — exporting a !null field is an error, as is an integer beyond i64 (it would silently round through f64). Fidelity is semantic: hex/octal/binary/underscored integer literals normalize to decimal (value exact via i64). Non-finite floats ride the typed channel as std/num marker types (&inf, &nan) — kaiv floats are deliberately finite, and extended reals are the union idiom !float|std/num/inf.

unit

Compound-unit canonicalization (SPEC.md § Canonical form: ASCII-sorted factors) and built-in unit membership (§ Built-in units). * places a factor in the numerator, / in the denominator; negative authored exponents flip sides; repeated factors collapse; shared factors cancel; factors sort by base name; 1 is the dimensionless identity. Every factor must be a built-in unit or a well-formed currency — kfaiv.com resolution is not implemented in this seed, so unknown means invalid.

validator

The Validator: parallel scan of .daiv against .csaiv (SPEC.md § Parallel Scan Validation, § Validator Pseudocode). Constant-memory in spirit: one pass, one schema pointer, plus the duplicate-detection set.

xml

XML import/export (--features xml) — a thin adapter over the value hub, zero dependencies: the well-formed-subset parser is hand-rolled like the JSON one, keeping raw source slices so mixed-content elements can embed verbatim as std/enc/xml.

xsd

XSD (XML Schema) → authored .saiv (--features xsd) — parsed with the crate’s own XML parser, converted under the same sound-weakening contract as the other schema converters: every emitted constraint is implied by the source, and what kaiv cannot express drops with a // comment.

yaml

YAML import/export (--features yaml) — a thin adapter over the value hub: import converts the YAML tree to Val and feeds the shared emission engine, so every rule (inline forms, the explicit- index mode, the 80-character budget, std/enc/json embedding) is format-agnostic by construction; export walks the shared export tree. Fidelity is semantic — YAML formatting, comments, and quoting styles do not survive any parse. Merge keys (<<) are resolved and materialized. Known edges: !!binary tags are not visible through the parser (the payload arrives as its base64 string); unquoted timestamp-shaped scalars stay strings — the parser cannot distinguish them from quoted strings, so no datetime sniffing (import from TOML for typed datetimes); and non-finite reals (.inf, .nan) ride the typed channel as std/num markers, kaiv floats being deliberately finite.