Skip to main content

Complete executable lifecycle

This canonical module migrates a frozen v1 document, serializes it canonically, reparses the bytes through validation, proves the round trip is stable, and computes its semantic SHA-256.
The release gate compiles and executes the source module from examples/docs/document-canonicalization-and-migration.ts.

Serialize deterministically

Serialization canonicalizes topology query ordering and persistent-reference variants. Equivalent commutative topology expressions therefore produce the same document representation.

Parse untrusted text

parseDocument checks UTF-8 byte size before JSON.parse, captures a bounded plain snapshot, validates the matching frozen version schema, validates graph semantics, and deep-freezes the result. Use parseDocumentValue(value) when another parser already produced an unknown JavaScript value. It still performs the bounded snapshot and schema checks.

Do not cast

Type assertions provide no runtime safety and can feed cycles, wrong versions, invalid expressions, missing references, or resource bombs into code that expects a validated document.

Clone

Cloning serializes and reparses through the public protocol. It is appropriate when a detached frozen copy is needed; it is not a mutable editing API.

Migrate

Migration preserves admitted authored data from versions 1 through 6 and moves it to the current schema. It does not:
  • invent information a prior version could not express
  • recapture topology evidence
  • upgrade a stored persistent-reference protocol
  • rewrite kernel fingerprints
  • execute geometry
Keep the original input when auditability requires proving exactly what was received before migration.

Hash a document

By default, root metadata is excluded so descriptive root changes do not alter the semantic document hash. Node metadata and every modeled field follow the protocol’s canonical representation. Pass { includeMetadata: true } when the root metadata is intentionally part of the hash.

Schema identifiers

The schema URI and integer version are protocol identifiers. Parsers do not dereference the URI over the network. Treat both as exact values, not as a URL from which runtime code should be downloaded.

Editing strategy

InvariantCAD 0.1 exposes a builder for authoring and parsers for validated documents. It does not expose an in-place mutable document editor. To revise a stored document programmatically, use a reviewed transformation that produces a new value, then pass it through parseDocumentValue before persistence or evaluation.