Document schema and versioning

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

interface DesignDocumentV6 {
  schema: string;
  version: 6;
  name: string;
  units: { length: "mm"; angle: "rad"; mass?: "kg" };
  parameters: Record<string, ParameterIR>;
  materials?: Record<string, MaterialDefinitionIR>;
  configurations?: Record<string, DesignConfigurationIR>;
  topologyReferences?: Record<string, TopologyReferenceEntryIR>;
  nodes: Record<string, NodeIR>;
  outputs: Record<string, RefIR>;
  metadata?: Record<string, JsonValue>;
}

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

Frozen versions

Version	Principal addition
1	Initial executable document grammar
2	Document-owned persistent face/edge topology references
3	Ruled-loft topology roles, and lofts as sketch-entity topology sources
4	Bounded-sweep topology roles, and sweeps as sketch-entity topology sources
5	Exact fillet/chamfer generated-face roles
6	Persistent vertices, vertex position queries, and edge↔vertex adjacency

The node-kind vocabulary is the same in every frozen version: Documents v1 through v6 all admit the same 20 node kinds, including loft, sweep, polylinePath, circularArcPath, and compositePath. Versions 3 and 4 added topology vocabulary for those nodes, not the nodes themselves, so a v1 or v2 document that contains a loft, sweep, or path node is valid. 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. Frozen v1–v6 schemas and parse paths strip an own __proto__ key from plain records and arrays before validation, as they always have. That keeps the same legacy bytes admitted on every supported Zod release, including Zod 4.6, which would otherwise report the key as unrecognized on strict objects. Staged Document v7 does not strip it.

Staged Document v7 product outputs

Document v7 remains repository-staged: the public alias, builder, and migration target stay on v6. Its strict grammar admits exactly four named product output kinds, solid, bodySet, part, and assembly. One frozen vocabulary derives the TypeScript union, the strict schema, and semantic validation. Curves, wires, faces, shells, backend compounds, and unknown kinds fail as IR_INVALID at /outputs/<name>/kind; they are not reserved placeholders and return only with real nodes, evaluators, ownership rules, and conformance evidence. A solid output is exactly one body. A bodySet is the only multibody output: an ordered authored collection with stable member IDs that is never fused or turned into a kernel compound. Frozen v1–v6 output grammars are unchanged.

Identity when migrating to v7

Documents v1–v6 accept any string as a parameter, node, output, sketch-entity, sketch-constraint, or assembly-occurrence ID, and accept repeated occurrence IDs within one assembly. Document v7 requires ^[A-Za-z][A-Za-z0-9._:-]*$ and unique occurrence IDs. Staged migration fails closed and never renames anything on its own. It reports every blocking location rather than one diagnostic per identity: a non-conforming ID gets an IR_INVALID diagnostic (reason document-v7-id-grammar-incompatible) at its definition and again at each stored topology-lineage entry, variant or adjacency, that names it. Each repeat of an occurrence ID within one assembly adds a DUPLICATE_ID diagnostic (reason document-v7-duplicate-assembly-occurrence-id) that points back to the first occurrence. Diagnostics are ordered by JSON Pointer path. A separate staged operation accepts an explicit caller-authored rename map. Flat maps cover parameters, nodes, and outputs. Sketch maps are keyed by legacy sketch ID. Occurrence maps are keyed by legacy assembly ID and then by instance index, because a repeated ID cannot address one occurrence.

Only identities that block v7 may be renamed; renaming an ID that already conforms is rejected.
Node and sketch-entity renames also cover historical identities that exist only in stored topology lineage.
Every entry must name an existing source identity, every target must be a unique v7 ID, and no target may collide with a retained ID.
Renaming a repeated occurrence ID that a configuration references is rejected, because which occurrence the configuration meant is ambiguous.

Each rename rewrites its definition and every structural reference, including expressions, topology queries, and stored lineage. Metadata and other free-form text are never rewritten. The result must pass strict v7 validation, and the operation returns a deterministic audit record of every applied rename. Output renames are marked consumer-visible because callers and external documents select outputs by name.

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
body-result classification 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. These schemas are structural. Every node reference accepts any of the five reference kinds (profile, path, solid, part, assembly), and every topology selection accepts any topology kind its version admits. The node schemas therefore accept, for example, a fillet whose input.kind is assembly or whose edges.topology is vertex, even though NodeV6Schema is typed as returning NodeIRV6, whose fillet input is a solid reference and whose edges are an edge selection. Agreement between a reference’s declared kind, its target, and its consumer, and between a selection’s topology kind and its feature, is enforced only by semantic validation. parseDocument, parseDocumentValue, and validateDocument apply it and report REFERENCE_KIND_MISMATCH or TOPOLOGY_SELECTOR_INVALID. Validate a whole document with those functions before relying on the static types of a node parsed on its own.

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.

Library reference

Tools and formats

Exhaustive guide