Module schema_registry 

Events track, slice 3c (#980): the cross-build schema registry’s document shape and (de)serialisation.

P4.0 (#1113, [DECISION A]): this module used to also hold reconcile — the bynk_check-coupled half that diffs a project’s live event shapes against this document (it reads UnitTable, which stays in bynk-emit pending P4.1’s bynk-check entry point). Only the pure, disk-free document shape and its parse/serialize moved here; reconcile and its helpers (snapshot, canon_type, Reconciled, …) stay in bynk-emit’s own project/schema_registry.rs, and reach SchemaRegistry’s otherwise- private version/events only through SchemaRegistry::new, SchemaRegistry::get, and SchemaRegistry::insert — never raw field access across the crate boundary.

#1078: this module touches no disk. parse/serialize are pure — bynk.schema.lock’s content comes in through CompileOptions::schema_registry’s SchemaLock::On { existing } and goes out through ProjectOutput::schema_lock; bynk-driver’s schema_lock module owns the actual read/atomic-write. parse takes a project_root: &Path (#1085 review) purely to name the file in a corruption message — never for I/O.

State-migrations S0 (#2204): the lock is version = 2 and also records each agent class’s stored state shape under [agents] (the retired track’s summary in design/archive/retired-tracks.md, §3.1). A v1 lock reads as v2 with no agents; the version bump exists so an older toolchain refuses a v2 lock instead of parsing it, dropping the unknown [agents] table (there is no deny_unknown_fields) and writing the lock back without it.

Structs

AgentEntry

One agent class’s recorded state history (track §3.1).

AgentShape

The stored shape of one agent class at one version.

EventEntry

FieldShape

A shallow, per-field snapshot of an event’s current shape — deliberately not bynk-check/src/contract.rs’s canon_named_in: that renders a field as name: type with no signal for default-presence, so an additive change (new field, has a default) and a breaking one (new field, no default) perturb it identically. This snapshot exists to tell those two apart, one field at a time.

SchemaRegistry

StoreShape

One store field’s stored shape. ty is the structural rendering of the field’s type with every refinement predicate stripped; refinement is the same walk with predicates kept (an opaque type’s included). A change to ty is non-additive; a change to refinement alone is not.

Functions

lock_version

parse

Parse bynk.schema.lock’s content. existing: None means the project has no lock file yet — a fresh project’s first reconciliation, baselined rather than compared, exactly as a missing file always meant back when this function read the file itself. It must mean verified absent, never “content unavailable” for some other reason — see SchemaLock::On’s doc comment, which states that invariant on the type the caller constructs.

serialize

Serialize a reconciled registry to bynk.schema.lock’s TOML form — what bynk-driver writes to disk, atomically, only on a fully clean build (compile_project’s own gate). No disk access here; see this module’s doc comment for why. Cannot fail for this data shape (string keys, no floats) — toml::to_string_pretty only errors on inputs this struct never produces.