> ## 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.

# Reference model corpus

> Build, test, and measure InvariantCAD against a small set of real mechanical models.

The repository reference corpus is a deliberately small outcome harness. Each
model is authored with the same public APIs available to a library consumer,
has one named part output, and records analytical default-volume and bounds
expectations. It does not stand in for features that InvariantCAD does not yet
support.

| Model                 | Construction                                                      | Default output |
| --------------------- | ----------------------------------------------------------------- | -------------- |
| Electronics enclosure | Box subtraction plus four cylindrical mounting bosses             | `enclosure`    |
| Six-bolt flange       | Overlapping cylinders, a through bore, and a six-hole bolt circle | `flange`       |
| Hollow stepped shaft  | Three overlapping shaft stages and a continuous axial bore        | `shaft`        |

All three models are parameterized, material-backed parts and use only the
common Manifold and stock OCCT modeling subset: boxes, cylinders, transforms,
Booleans, parts, and materials. The corpus therefore exercises mesh-first and
exact evaluation without pretending that unsupported sketch, surfacing, or
assembly workflows exist.

## Deterministic outcome tests

`tests/reference-models.test.ts` rebuilds every document twice, checks canonical
serialization, validates the document, and evaluates compatible cases on both
shipped kernels. The assertions cover analytical volume, world bounds,
non-empty mesh structure, and density-derived mass. Manifold receives a small
relative tolerance for segmented circles; stock OCCT is checked against the
analytic values.

Run the focused test directly:

```bash theme={"system"}
pnpm exec vitest run tests/reference-models.test.ts
```

## Measurement-only benchmark

Benchmark schema v2 emits JSON and intentionally has no pass/fail performance
thresholds. It launches one fresh child process for every model/kernel pair.
Each case has a 120-second process timeout; a timed-out worker is killed and
reaped with its kernel/model context included in the failure.
The first run in that process is labeled `fresh-runtime-first-run`: it creates
a new kernel and evaluator, builds a fresh document, and performs the first
evaluation. It is not a claim that the machine, filesystem cache, WebAssembly
compiler cache, CPU frequency, or surrounding host is cold.

Every `same-runtime-repeat` builds a new document with byte-identical canonical
serialization, reuses that case's kernel and evaluator, and starts only after
the previous result is disposed. No evaluator artifact cache is enabled, so a
repeat is not described as a cache hit.

```bash theme={"system"}
pnpm exec tsx scripts/benchmark-reference-models.ts \
  --kernel manifold \
  --repeat-runs 3

mkdir -p .artifacts
pnpm exec tsx scripts/benchmark-reference-models.ts \
  --kernel all \
  --repeat-runs 1 > .artifacts/reference-models-v2.json
```

Use one or more `--model <id>` options to measure a subset. The complete
one-repeat corpus also executes in Node 26 CI as a protocol and correctness
check, without comparing performance values.

Each run records canonical document bytes and SHA-256, node and parameter
counts, measured geometry and mass, tessellation counts and buffer sizes,
binary STL size, and STEP size when the kernel advertises STEP export. OCCT
uses the explicit `0.1` linear deflection, `0.3` angular deflection, absolute
tessellation profile recorded in the report. Manifold records that its mesh is
controlled by authored primitive segmentation and its kernel default; the
report does not imply triangle-count parity between backends.

Timings remain separated into document construction, canonical serialization,
evaluation, measurement, physical mass properties, tessellation, STL
serialization, optional STEP serialization, result disposal, and total
workflow time. Repeat samples also receive minimum, median, and maximum
summaries.

Memory evidence is Node's `process.resourceUsage().maxRSS` high-water value in
KiB at named lifecycle boundaries inside the dedicated case process. It
includes Node.js, loaded modules, JavaScript, WebAssembly, and native kernel
state. It is process-wide, cannot attribute allocations to the model, and is
not instantaneous RSS. The public kernel protocol does not expose native
allocation counters, so current reports explicitly record native-handle
telemetry as `unsupported`; private adapter bookkeeping is not mislabeled as a
native-handle count.

Compare reports produced from the same source revision on equivalent hardware,
operating system, and runtime versions. Do not use this script as a
cross-machine leaderboard.