kaiv 0.2.0

Reference implementation of the kaiv format (Levels 0-2): lexer, compiler, denormalizer, schema compiler, validator
Documentation

kaiv-rs

Reference implementation of the kaiv format (Levels 0–2) in Rust. A cargo workspace with two crates:

  • kaiv — the library. Zero dependencies; the certifiable reference pipeline.
  • kaiv-cli — the kaiv command-line binary, a thin shell over the library. Kept out of the library crate so its (future) dependencies never reach library consumers.

kaiv is an immutable structural type system for data at rest; the specification and design documents live in the sibling spec repository. The library implements the build pipeline:

.kaiv --[Compiler]--> .raiv --[Denormalizer]--> .daiv
.saiv --[schema compiler]--> .csaiv
.daiv + .csaiv --[Validator]--> pass / fail

CLI

kaiv compile  <file.kaiv>       authored -> relational canonical (.raiv)
kaiv denorm   <file.raiv>       relational -> denormalized (.daiv)
kaiv build    <file.kaiv>       authored -> .daiv (compile + denorm)
kaiv schema   <file.saiv>       authored schema -> compiled (.csaiv)
kaiv validate <data> <schema>   .daiv/.kaiv against .csaiv/.saiv -> pass/error
kaiv unit     <expr>            canonicalize a unit expression
kaiv infer    [--name ID] [f]   infer an authored .saiv from an example
                                document (kaiv or any import format); the
                                example validates against the result
kaiv import-schema [--name] [f] JSON Schema -> authored .saiv, as a sound
                                weakening: inexpressible constraints are
                                dropped with // comments, never invented
kaiv import   [--FMT] [file]    JSON/YAML/TOML -> authored .kaiv: structures
                                import natively (inline ;= := +:= forms where
                                homogeneous and short); only empty containers,
                                anonymous nested arrays, and non-flat strings
                                embed as std/enc/json. Format from the
                                extension (.json .yaml .yml .toml) or the
                                option (required for stdin); --flat embeds
                                all containers (json only)
kaiv export   --FMT [file]      kaiv -> JSON/YAML/TOML (.kaiv built first;
                                .daiv as is)

The nearest kaiv.kaiv up from the working directory configures registry resolution (SPEC.md § Layer 2) — the toolchain's own configuration is a kaiv document — with KAIV_REGISTRY_* environment variables overriding. Exit 0 on success/pass, 1 otherwise; output on stdout, diagnostics on stderr.

Library modules

Module Role
lexer Six-rule line classifier + document checks (SPEC.md § Parsing Requirements). Eager model: whole text validated before any token is emitted.
anno Constraint grammar, both surface forms (annotation position and constraint-line position), including the alternative-delimiter pattern form re{sep}…{sep} (lowered to canonical /…/).
rex Backtracking matcher for the pinned finite-state regex dialect.
unit Compound-unit canonicalization (base-name-sorted factors) and built-in-set membership.
taiv / faiv Type-library (.taiv) and unit-definition (.faiv) parsing; std/core and std/enc ship embedded as real .taiv files.
config / resolve kaiv.kaiv Layer 2 configuration (the format bootstrap) and Layer 1/2 registry resolution over filesystem bases.
compiler .kaiv → .raiv: variables, sugar (+=, ;=, :=, +:=, blocks, maps), &name resolution via .!types, unit membership via .!units.
denorm .raiv → .daiv: $field reference resolution, nothing else.
schema .saiv → .csaiv: transitive named-type lowering, constrained-union groups, map entry lines, ;= vector declarations and [/@name …] element blocks with Level 2 table headers (unique/ref/min/max collection constraint lines), .!schema inheritance (flat, /ns-encapsulated, /@arr element-wise; redeclaration narrows in place), =/?= operators, strict-modifier passthrough.
infer Canonical kaiv → an authored .saiv the example validates against: types from annotations, {int,float} widening, null unions, ;= vectors, [/@name] blocks with per-element-field optionality.
jsonschema (feature json) JSON Schema → authored .saiv as a sound weakening: types/unions, pattern (dialect-checked, / escaped), length/range (exclusiveMin/Max exact for integers), enum/const, required/defaults, format date-time→std/time, nested objects, typed maps, scalar vectors and struct-array blocks (minItems/maxItems graduate to table-header cardinality), local $ref inlining; everything else drops with a comment.
validator Parallel scan of .daiv against .csaiv, plus the Level 2 post-scan pass (uniqueness, referential integrity, cardinality).
json (feature json) JSON import/export with a hand-rolled parser: number tokens and nested containers stay raw source slices, so a compact import/export roundtrip is byte-identical. The library's default build stays zero-dependency; format features are additive.
yaml / toml (features) Thin adapters over the JSON hub: each converts its parse tree to compact JSON text and reuses the JSON importer/exporter, so every emission rule is shared by construction. Fidelity is semantic (formatting and comments do not survive); TOML datetimes import as strings, and TOML cannot represent null. Deps (yaml-rust2, toml) gated behind their features.

Conformance

The executable definition of "correct" is the conformance tree in the spec repo (spec/kaiv/conformance/). cargo test runs it from ../../spec/kaiv/conformance (relative to the kaiv crate) by default; override with KAIV_CONFORMANCE_DIR.

Scope and known limits (seed)

Levels 0–2. Type, schema, and unit resolution is offline (Layers 1–2: .!registry + kaiv.kaiv over filesystem bases); an http(s) base is a SchemaResolutionError — the hosted Layers 3–4 are not implemented. Also not yet implemented, by design at this stage: Level 3 locale collation (..lex[locale] values), Level 4 entirely, map key-pattern clauses, quoted names as interior path segments, and ..time/..ver span semantics beyond canonical-form string comparison. Each unimplemented path fails loudly rather than guessing.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.