Crate kaiv 

kaiv — reference implementation of the kaiv format, Levels 0–2.

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 compiler::compile;

pub use compiler::compile_with;

pub use config::Config;

pub use denorm::denormalize;

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::compile_schema;

pub use schema::compile_schema_with;

pub use validator::parse_csaiv;

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]).

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 nothing else (SPEC.md § Architectural Impact). No forward references.

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.

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 with per-element-field optionality (a field missing from some elements infers ?=). Shapes outside the compiled subset (nested arrays, structure inside elements) are skipped with a comment — 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.

resolve

Type-library resolution, Layers 1–2 (SPEC.md § Type Registry Resolution): document-level .!registry overrides, then kaiv.kaiv build-time configuration. Filesystem bases only — the hosted Layers 3–4 (registry redirects, ktaiv.com default) are network services this seed does not implement, so a lookup that would need them 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). Backtracking over the AST; no backreferences, no lookaround.

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. 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.

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.