Skip to main content
The current authoring grammar is Document v6. Versions 1 through 6 remain exported as types and Zod schemas for exact parsing and migration.

Top-level shape

Use the exported TypeScript definition for exact field types; this sketch shows the stable top-level organization.

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
For example, Document v6 can contain a stored persistent-reference protocol-v1 variant whose kernel descriptor fingerprint is @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.