> ## Documentation Index
> Fetch the complete documentation index at: https://invariant-cad.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# InvariantCAD 0.2.0

> Verified imported bodies, strict author-time checks, hardened untrusted-input handling, honest kernel measurements, and a GitHub-driven release flow.

# InvariantCAD 0.2.0

InvariantCAD 0.2.0 adds one public exact-import workflow and makes the 0.1
foundation strict and predictable. Builders now check their inputs when each
method is called. Parsing, the CLI, and signal-bearing evaluation bound
untrusted documents, options, and files before using them. Kernels report only
measurements they can stand behind. Public
document authoring remains Document v6. Imported-body documents use a fixed
Document v7 subset, read and evaluated only by the imported-body functions.

This release contains breaking changes for some 0.1.1 callers. Read the
[upgrade notes](#upgrade-notes) before upgrading.

## Highlights

* **Verified single-body import.**
  * `createImportedBodyDocument`, `stringifyImportedBodyDocument`,
    `parseImportedBodyDocument`, and `Evaluator.evaluateImportedBody` persist
    and evaluate one exact solid backed by a SHA-256 byte commitment.
  * Bytes come from a caller callback and are verified before use. The workflow
    never falls back to weak native import or to a mesh conversion.
* **Author-time checks.**
  * Builder methods validate option values, ownership, and ceilings when they
    are called, and read caller records once through their own data
    properties.
  * `build()` returns a detached, deeply frozen document that satisfies the
    strict document grammar.
  * `SketchBuilder.regularPolygon(...)` now works.
* **Hardened untrusted input.**
  * `parseDocument` rejects duplicate JSON member names.
  * Serialization and the CLI are bounded.
  * Diagnostic paths are RFC 6901 JSON Pointers that escape every document key.
  * The CLI fails closed on bad arguments and escapes document text.
  * An evaluation with a `signal` snapshots its request, then yields to the
    host so aborts from timers, UI handlers, and workers take effect.
* **Correct, bounded evaluation.**
  * Assemblies have fixed occurrence, path, and depth ceilings.
  * Mirror normals, revolve axes, sweep miters, and loft phases are checked
    before kernel work.
  * Custom sketch solvers are held to their declared protocol.
  * Expression evaluation and validation are linear in distinct nodes.
* **Honest kernel results.**
  * `ShapeMeasurements.genus` is `number | null`, and `null` means unsupported.
  * Stock OCCT transforms spheres and cones.
  * OCCT `mesh()` no longer depends on earlier tessellations.
  * STEP export on stock OCCT is bounded, and single-product export is
    byte-deterministic.
  * Manifold rejects foreign shapes and profiles beyond ±1e10 mm with readable
    diagnostics.
* **A GitHub-driven release flow.**
  * Every change reaches npm through a reviewed release pull request.
  * Publication uses OIDC trusted publishing with npm provenance.
  * The tagged GitHub release and the live documentation follow the published
    package.

## Verified single-body import

`createImportedBodyDocument(...)` records a caller-owned SHA-256 digest, exact
byte length, format and media type, and unit policy without performing I/O.
`Evaluator.evaluateImportedBody(...)` resolves the bytes through a callback. It
checks the committed length against the resource ceiling and verifies the digest
before the strong exact B-Rep single-solid import runs. STEP uses the file's
units; text and binary BREP use caller-declared units.

The saved JSON is a fixed, minimal Document v7 subset: one resource, one
`importedBody` node, and one solid output. Tests pin its canonical bytes and
digest, so imported-body documents saved by 0.2.0 stay readable. The general
Document v1–v6 APIs reject Document v7. `validateDocument`, `parseDocument`,
`parseDocumentValue`, `migrateDocument`, `hashDesignFeatures`,
`analyzeDesignImpact`, and `Evaluator.evaluate` return one `IR_INVALID`
diagnostic that names the imported-body functions. `stringifyDocument` and
`cloneDocument` throw a `TypeError`, and `hashDocument` rejects with one. See
[verified single-body import](https://invariant-cad.mintlify.site/interchange/import-export.md#verified-single-body-import).

## Strict authoring

* **Plain records and lists.** Option records must be plain objects, and the
  lists and records a document stores must be plain dense arrays and plain
  objects. Own fields are read once, whether enumerable or not. Accessors never
  run, and fields inherited from `Object.prototype` are never read.
* **Ownership.** A `Parameter` from another builder, a handle created with an
  exported constructor, or a builder used after its callback returned now
  throws.
* **Ceilings.** Metadata, topology selections, option records, and raw
  expression IR have fixed size and depth ceilings. They are refused before
  their contents are copied.

See [programmer errors](https://invariant-cad.mintlify.site/reference/design-builder.md#programmer-errors) for the
complete list.

## Untrusted input and diagnostics

Parsing, serialization, the CLI, and evaluation with a `signal` now apply
their documented ceilings before they allocate the data those ceilings
protect. An evaluation without a `signal` reads the supplied document
directly, so pass untrusted values through `parseDocument` or
`parseDocumentValue` before evaluating them. Every
diagnostic path escapes `/` and `~` in document keys, so a node named `a/b` is
reported at `/nodes/a~1b`. A non-string `outputs` entry or `configuration`
option fails with `IR_INVALID`. See
[diagnostics and limits](https://invariant-cad.mintlify.site/evaluation/diagnostics-and-limits.md).

## Kernels and exchange

* **Genus.** Manifold reports exact per-component genus. Stock and owned OCCT
  report `null` (unsupported) instead of the 0.1.1 Euler-characteristic
  heuristic.
* **STEP export.** On stock OCCT it has output, input, scan, and entity
  ceilings. Single-product zero-override export is byte-deterministic.
* **Binary STL.** Headers fit long multi-byte names on a character boundary,
  and a name starting with `solid` is prefixed so readers do not mistake the
  file for ASCII STL.
* **OCCT runtime.** Kernel `capabilities` are frozen, `dispose()` releases every
  remaining native handle, and OCCT `measure()` counts each occurrence of a
  solid that a compound repeats.

## Public entry points

The five public entry points are unchanged:

* `invariantcad`
* `invariantcad/conformance`
* `invariantcad/kernels/occt`
* `invariantcad/kernels/occt/browser`
* `invariantcad/kernels/occt/node`

## Important boundaries

* Public document authoring, schemas, migration targets, and aliases remain
  Document v6. Documents v1–v6 remain frozen and directly supported.
* The imported-body subset is the only public Document v7 JSON. Resources
  beyond it, datums, body sets, products, external occurrences, and feature-hash
  protocol v2 remain staged, repository-only work.
* The InvariantCAD-owned OCCT facade is not distributed in the npm package.
  Draft geometry and some exact topology-history guarantees still require it.
* Mesh and exact behavior remain distinct. Unsupported exact work is never
  silently converted to an approximate operation.

## Upgrade notes

Node.js 22.13 or newer is still required, and existing v1–v6 documents need no
migration. Review these changes:

* **Document v7 JSON.** Code that passed Document v7 JSON to `validateDocument`,
  `parseDocument`, `stringifyDocument`, `hashDocument`, or `Evaluator.evaluate`
  must use the imported-body functions instead.
* **Option records and lists.** They must be plain object literals and plain
  arrays. Class instances, getter-backed objects, array subclasses, and sparse
  arrays now throw `TypeError`.
* **Genus.** `ShapeMeasurements.genus` can be `null`; handle it explicitly.
* **Manifold shape ownership.** Each `ManifoldKernel` accepts only the shapes it
  created.
* **Revolve.** A revolve profile that crosses its axis now fails with
  `FEATURE_INVALID` instead of being clipped on Manifold.
* **Sweep.** It now accounts for the corner miter, so some tight 0.1.1 sweeps
  need longer segments, gentler corners, or a smaller profile.
* **Custom sketch solvers.** They must advertise every entity and constraint
  kind they accept, and their `status` is authoritative.
* **Assemblies.** Those beyond 100,000 occurrence records, 1,000,000 instance
  path segments, or depth 64 now fail with `RESOURCE_LIMIT_EXCEEDED`.
* **CLI export.** `invariantcad export` requires `--output` for documents with
  more than one output.
* **Declaration maps.** The package no longer ships TypeScript declaration maps;
  declarations keep their JSDoc.

For the exhaustive change record, see the
[0.2.0 changelog](https://github.com/shlokjain42/invariantCAD/blob/v0.2.0/CHANGELOG.md).
For exact current capabilities and planned work, see the
[support matrix](https://invariant-cad.mintlify.site/reference/support-matrix.md) and [roadmap](https://invariant-cad.mintlify.site/roadmap.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.