Enterprise Enterprise: the wasm engine and causl-wasm-ts

Causl ships a pure-TypeScript engine (causl-ts) as the open-source floor and reference implementation. As an Enterprise feature I also ship a Rust→WebAssembly engine, causl-core-rs, consumed through a thin TypeScript client, causl-wasm-ts. Both engines expose the same public Graph surface: the canonical primitives of SPEC §12.1 plus the §12.2 second-tier structural surface, the full contract the Rust core satisfies over FFI (§18A.4). Inside causl-wasm-ts the Rust engine is the whole engine. There is no TypeScript fallback in that package, and createCausl() either constructs the wasm graph or throws. The promotion gate documented in SPEC §18A.7 has been met. The engine and client repositories are private, so I cite them here by name and issue number without linking; reaching the source needs a Gitea account on git.opsite.ca.

Enterprise

Construction is synchronous behind one preload. The one unavoidable async is the WebAssembly compile, and §18A.12 splits it away from construction: await preloadCauslWasm() compiles and caches the module once at app init, then createCausl() and createCauslWasmSync() build a wasm Graph with zero await at the call site, so synchronous consumers (a React render body, an xldatagrid cell) can use them directly. createCauslWasm() is retained as preload ∘ createCauslWasmSync. The --target nodejs server glue is already synchronous end to end and needs no preload; only the browser bundler target does.

The TypeScript capability fallback is withdrawn. §18A.13.1 once described an implicit createCausl() that degraded to a retained internal TypeScript engine on a host that could not instantiate the wasm engine. That section was withdrawn at 0.5.0 and now reads, in its own words, as a dated record rather than a live obligation. createCauslTs is deleted from source, so nothing on this site should be read as promising a runtime degrade. Branch on error.code, never on instanceof: CAUSL_WASM_ENGINE_UNAVAILABLE (the wasm subpath was never imported, or the host cannot instantiate the engine) and CAUSL_WASM_NOT_PRELOADED (imported, but preloadCauslWasm() never resolved).

Two things killed the fallback, and both are worth stating. First, the fallback engine and the primary disagreed on a surface §18A.1.1 requires to be identical: in-place mutation of a committed value (causl-wasm-ts#272). A fallback that is not byte-identical is not a fallback, it is a second set of semantics reached by accident. Second, the implicit path was the accident path: 0.4.0 warned on it, 0.5.0 throws.

causl-wasm-ts

Integrating causl-wasm-ts

Adopt the Rust engine from a TypeScript or Node application: the Gitea-registry install, await preloadCauslWasm() once at boot, synchronous createCausl() afterwards, the placed artefact and its loader, and the two structured failure codes.

Read the guide

SPEC §18A

Two-engine architecture

Two conformant engines, now in two different repositories: causl-core-rs ships the Rust engine that causl-wasm-ts binds, and causl-core-ts stays dual-engine as the differential oracle. The §18A contract and the shared public Graph surface.

Read the contract

causl-bench

Wasm performance, measured

What the wasm path actually costs. The marshal tax is not the ceiling: a raw boundary crossing is 1.6 ns. The real costs are a per-commit clone that scales with graph size, a per-recompute constant, and a per-commit constant.

Read the numbers

TypeDoc

Generated API reference

The TypeDoc-generated reference for the package surface. It is built from an older package layout and still names @causl/core, so it lags the 2026-07-27 rename. Where it disagrees with these prose pages, the prose pages are current.

View API

Distribution

The Enterprise @causl/* packages are distributed through a self-hosted, private npm registry: the Gitea package registry at https://git.opsite.ca/api/packages/causl/npm/. It is fully private. Every package requires authentication to read, nothing is listed publicly, and anonymous requests are rejected. The old Verdaccio host iasbuilt-npm.opsite.ca is gone; any .npmrc or lockfile still naming it is stale.

Read this before you edit an .npmrc. @causl/core is not the client, and it has zero versions on this registry. It does resolve on the public npm registry, at 0.3.0 through 0.3.3, to a different package (the retired TypeScript engine). So an .npmrc missing the @causl:registry= line, or a lockfile still pinning @causl/core, installs successfully and gets the wrong package rather than failing. The failure mode is a silent wrong install, not an error. Install @causl/causl-wasm-ts, and check the scope line is present before you do.

The packages, the repositories that publish them, and where each one lives:

Layer	Repository	Package	Registry
Rust engine	`causl-core-rs`	`@causl/core-rs`	Gitea (private)
TypeScript engine	`causl-core-ts`	`@causl/core-ts` (never published)	Gitea (private)
TypeScript client	`causl-wasm-ts`	`@causl/causl-wasm-ts`	Gitea (private)
OSS TypeScript engine	`causl-ts`	`@causlts/core`	public npmjs

@causl/causl-wasm-ts is the package you install. Its satellite packages (@causl/persistence, @causl/devtools, @causl/devtools-bridge, @causl/migration-check, @causl/formula, @causl/hypothesis, @causl/sync, @causl/react) publish from the same repository to the same registry. Two names that used to appear here do not exist on it: @causl/wasm was never published, and @causl/core is the hazard above. The naming scheme is deliberate, engines by substrate and clients by consumer language, and it is recorded in causl-wasm-ts docs/repo-naming-decision.md.

Point the @causl scope at the registry and attach the token issued during Enterprise onboarding. Both lines go in .npmrc before the first install:

@causl:registry=https://git.opsite.ca/api/packages/causl/npm/
//git.opsite.ca/api/packages/causl/npm/:_authToken=${CAUSL_NPM_TOKEN}

Then install with your usual package manager:

pnpm add @causl/causl-wasm-ts
# npm install @causl/causl-wasm-ts
# yarn add @causl/causl-wasm-ts

These Enterprise features require a production Rust build and a Node target (SPEC §18A.2). The §18A.7 GO/NO-GO gate was met on 2026-06-21, all five criteria GO, so in causl-wasm-ts the Rust engine is the unconditional production engine. The host floor is Safari 18.2, Chromium 119, Firefox 120 and Node 22, governed by typed function references rather than by WasmGC heap types; the host-tier matrix has the detail. The pure-TypeScript engine is still the §12 conformance reference and the §18A.7 Criterion-5 floor, but it lives in causl-core-ts, not in causl-wasm-ts. That is the repository that stays dual-engine and runs the differential oracle.