Top-level shape
Frozen versions
Each version freezes its admitted node kinds, role vocabulary, query grammar,
wire representation, and schema URI. New parser code may validate an older
version more defensively, but it must not reinterpret valid frozen bytes as a
newer grammar.
Independent version axes
Do not infer one version from another:- npm package semver
- document version
- geometry kernel protocol version
- topology signature protocol version
- topology descriptor fingerprint version
- exact indexed-evolution protocol version
- artifact-cache and semantic-observation versions
- owned OCCT facade ABI
@4 or @5. Migrating the
document does not recapture it as protocol v2.
Schemas
The root entry exports current and version-specific Zod schemas for documents, nodes, topology queries/selections, persistent references, and registry entries. Use version-specific schemas when implementing a protocol tool that must reject newer vocabulary rather than accepting the current union.Migration contract
migrateDocument validates the source version and emits v6. It preserves
stored persistent evidence, fingerprints, IDs, metadata, nodes, and outputs
admitted by the source. It cannot synthesize later feature roles or vertex
evidence that did not exist.
Canonicalization
stringifyDocument canonicalizes JSON object ordering and the commutative parts
of topology query algebra. Persistent variants are normalized and sorted by
protocol/fingerprint. This provides deterministic bytes for the same admitted
document semantics; it does not canonicalize native geometry output.