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.examples/docs/document-canonicalization-and-migration.ts.
Serialize deterministically
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
Clone
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
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
Theschema 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 throughparseDocumentValue before persistence or
evaluation.