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

# OpenCascade backend

> Configure exact B-Rep evaluation, stock occt-wasm, custom binaries, and the owned facade.

`createOcctKernel()` adapts `occt-wasm@3.8.0` to InvariantCAD's exact geometry,
topology, and exchange protocols.

## Stock runtime

```ts theme={"system"}
import { createEvaluator } from "invariantcad";
import { createOcctKernel } from "invariantcad/kernels/occt";

const kernel = await createOcctKernel();
const evaluator = await createEvaluator({ kernel });
```

The stock module supports exact primitives, extrusion, revolution, bounded
loft/sweep contracts, Booleans, transforms, fillets, chamfers, shells, offsets,
topology snapshots, and STEP/BREP exchange. Draft and several complete-history
refinements are not advertised.

OCCT bounds, surface area, and center of mass are measured from the exact
native B-Rep. Volume and inertia normally come from the same native shape; the
documented validated analytic volume-override path for admitted sweep and
revolve cases replaces the volume and rescales density-one inertia. Genus is
currently `null`, not zero: the stock and owned facades do not expose the
degenerate-edge predicate needed to evaluate the B-Rep Euler formula correctly
for spheres, cones, seams, holes, and disconnected shells.

## Load a WASM source explicitly

`wasm` accepts a URL, string URL/path, `ArrayBuffer`, or `Uint8Array`:

```ts theme={"system"}
const kernel = await createOcctKernel({
  wasm: new URL("/assets/occt-wasm.wasm", location.href),
});
```

Bytes are copied where required so caller mutation cannot change an in-flight
module initialization.

## Tessellation and tolerance

```ts theme={"system"}
const kernel = await createOcctKernel({
  modelingTolerance: 1e-7,
  tessellation: {
    linearDeflection: 0.1,
    angularDeflection: 0.3,
    relative: false,
  },
});
```

Modeling tolerance is part of topology fingerprints and feature validation.
Tessellation options affect `mesh()` and mesh exports, not the underlying B-Rep.
Do not change tolerances merely to force an invalid model through a check.

## Native history limits

Owned facade operations can produce large indexed evolution reports. Bound
materialization explicitly:

```ts theme={"system"}
const kernel = await createOcctKernel({
  maxExactBooleanHistoryRecords: 250_000,
  maxExactEdgeTreatmentHistoryRecords: 250_000,
  maxExactSolidOffsetHistoryRecords: 250_000,
});
```

The defaults are 1,000,000 records per category. Limits apply across WASM and
JavaScript transfer. Raise them only after measuring a legitimate workload.

## Attested owned facade

For a reviewed bundle, prefer an environment-specific attested loader over
pairing the files manually:

```ts theme={"system"}
import { readFile } from "node:fs/promises";
import { createOcctKernel } from "invariantcad/kernels/occt";
import {
  INVARIANTCAD_OCCT_FACADE_0_9_0_RELEASE_MANIFEST_SHA256,
  loadAttestedOcctRuntime,
} from "invariantcad/kernels/occt/node";

const bundle = "/opt/invariantcad-occt-facade-0.9.0";
const [releaseManifest, javascript, webassembly] = await Promise.all([
  readFile(`${bundle}/metadata/release.json`),
  readFile(`${bundle}/runtime/occt-wasm.js`),
  readFile(`${bundle}/runtime/occt-wasm.wasm`),
]);

const attestedRuntime = await loadAttestedOcctRuntime({
  releaseManifest,
  expectedReleaseManifestSha256:
    INVARIANTCAD_OCCT_FACADE_0_9_0_RELEASE_MANIFEST_SHA256,
  javascript,
  webassembly,
});
const kernel = await createOcctKernel({ attestedRuntime });
```

The loader copies each caller-owned input, verifies the exact canonical release
manifest against an independently trusted SHA-256 pin, then verifies the
JavaScript and WASM sizes and digests before importing JavaScript. Kernel
creation supplies a fresh verified WASM copy and requires the initialized facade
marker to match the trusted manifest. `attestedRuntime` is mutually exclusive
with `wasm` and `moduleFactory`.

The opaque pair can be reused to create kernels only through the evaluated
InvariantCAD internal module instance that created it; cloning the visible
report does not reproduce executable authority. Its exact runtime-pair identity
strengthens only the repository-private artifact compatibility fingerprint; it
does not change persistent-topology fingerprints or advertise `shapeArtifacts`.
The separate declared-build identity records the manifest, but does not prove
that recipe ran or authenticate a publisher. See
[OCCT runtime attestation](/evaluation/occt-runtime-attestation) for the browser
loader, Node module-hook lifecycle, CSP, failure reasons, and complete
non-claims.

## Direct custom or rebuilt facade

```ts theme={"system"}
const kernel = await createOcctKernel({
  moduleFactory: createOwnedOcctModule,
  wasm: ownedWasmBytes,
  onOutput: (message) => logger.info(message),
  onError: (message) => logger.error(message),
});
```

The repository can build and verify a package-neutral facade bundle. The bundle
contains matched JavaScript/WASM, SHA-256 digests, source and relinking
instructions, ordered patches, notices, build provenance, and an SBOM.

Raw `moduleFactory` plus `wasm` overrides remain available for an intentionally
trusted custom or rebuilt pair. They do not perform release-manifest
attestation or acquire an attested runtime-pair identity.

<Warning>
  Never combine the owned JavaScript factory with stock WASM, or vice versa.
  Facade capability probing is not a license to mix binaries from different
  builds.
</Warning>

## Exact exchange

```ts theme={"system"}
const output = evaluated.output("body");

const step = output.export("step");
const textBrep = output.export("brep");
const binaryBrep = output.export("brep-binary");
```

<Note>
  The deterministic metadata and byte contract below is implemented for the
  unreleased 0.2 line, not the current 0.1.1 npm package.
</Note>

The bundled zero-override stock kernel's optional `capabilities.stepExport`
envelope advertises
`KERNEL_STEP_EXPORT_PROTOCOL_VERSION === 1`, schema `AP214IS`, byte scope
`same-shape-representation-and-metadata`, a 64 MiB output ceiling, and a
64 KiB metadata ceiling. This is a distinct, stronger declaration than
`nativeExports` containing `"step"`; the latter promises format availability,
not deterministic bytes. `inspectKernelStepExportCapabilities(...)` snapshots
and validates this optional envelope without invoking accessors.

Supplying `wasm`, `moduleFactory`, or `attestedRuntime` omits this envelope and
retains weak raw STEP export. Even an explicitly supplied stock-derived
artifact is unqualified until a separate exact-writer probe or attestation
contract exists.

At the evaluated-output boundary,
`output.export("step", { metadata?, signal?, maxOutputBytes? })` supplies a
complete resolved metadata request to a supporting kernel. The qualified
bundled stock runtime writes one AP214IS product, then a purpose-built
structural Part 21 transformer
replaces only the relevant `FILE_NAME` and `PRODUCT` string tokens. It validates
the exchange envelope, section structure, record arity, one-product
assumption, exact EOF, metadata, entity count, scan work, and resulting byte
size. It does not use a regular expression or reinterpret geometry.

Default metadata uses the document name for `FILE_NAME`, the fixed
`1970-01-01T00:00:00` timestamp, and the output alias for an ordinary solid's
product ID and name. Parts use the part number or part-node ID for product ID,
the part-node ID for product name, and the authored part description. A caller
timestamp is accepted only as a valid `YYYY-MM-DDTHH:MM:SS` calendar value and
is deterministic because it is explicit input. Protocol v1 accepts Unicode
scalar text in the four identity/description fields: apostrophes are doubled
for STEP, while literal backslashes and non-ASCII scalars use ISO-10303-21
`\X2\...\X0\` or `\X4\...\X0\` directives. Control characters and unpaired
UTF-16 surrogates are rejected.

Material identity, configuration selection, arbitrary document metadata, and
arbitrary part metadata are not representable through this current mapping.
Aggregate assembly and body-set exact STEP export remains unsupported.

<Warning>
  InvariantCAD validates and encodes metadata before starting the stock
  `occt-wasm` writer. That writer is synchronous and then materializes its
  original complete STEP string. JavaScript output limits and cancellation
  cannot interrupt the native call. Once it returns, InvariantCAD checks
  cancellation and applies bounded, cancellable scanning, entity/work limits,
  and the final output ceiling. `maxOutputBytes` bounds only the transformed
  bytes returned to JavaScript; it does not bound the native writer's peak
  allocation.
</Warning>

The 64 KiB metadata budget measures the five resolved strings as UTF-8.
Part 21 escaping can expand Unicode or backslash text, and that expanded form
counts toward the 64 MiB returned-output ceiling.

The byte guarantee is deliberately narrow: identical bytes require the same
backend shape representation, options, metadata, implementation, and exact
runtime artifact. It is not geometric canonicalization, cross-runtime cache
identity, or a canonicalizer for imported or third-party STEP files.

These methods return bytes or text synchronously from a live evaluated output.
Generic BREP exchange does not preserve InvariantCAD wrapper lineage, topology
annotations, cached evaluator state, or durable artifact identity.

## Licensing boundary

`occt-wasm` is MIT-licensed glue around OpenCascade Technology, which is LGPL
2.1 with the Open CASCADE exception. Distributors must preserve the applicable
notices, source/relinking path, and replacement rights. Read
[`THIRD_PARTY_NOTICES.md`](https://github.com/shlokjain42/invariantCAD/blob/main/THIRD_PARTY_NOTICES.md)
before redistributing a runtime bundle.