Wasm performance Enterprise

This page reports what the wasm path costs, measured rather than modelled. For a long time it led with the JS↔WASM marshal tax as the engine's ceiling, and I retract that in full in §3: a raw boundary crossing costs 1.6 ns on the benchmark host, which works out to 0.13% of the cell it was supposed to dominate. The boundary was never the constraint.

Three costs are. In order of how much they hurt: a residual per-commit clone proportional to the number of live cells (not touched cells), a per-recompute constant of roughly 2.5 µs, and a per-commit constant of roughly 3.1 to 4.4 µs. None of the three is the crossing itself. Two of them are known to be constants I can attack; the first is a bug with an open issue and a located line of source.

1. The architecture, as it actually ships

Two packages matter to an adopter, and a third exists only to keep them honest.

Three older names appear in prose that predates the 2026-07-27 rename and all three are retired: causl-client is now causl-wasm-ts, causl-wasm as a repository is now causl-core-rs, and causl-ts-wasm-engine is now causl-core-ts. Each survives only as a redirect. The package @causl/core deserves its own warning: it has zero versions on the Gitea registry, but the name resolves on public npmjs to a different package, so a stale pin installs successfully and gets the wrong thing rather than failing loudly. Do not import @causl/core.

There is no TypeScript fallback

§18A.13.1, the implicit capability fallback that let createCausl() degrade to the TypeScript engine on a host that could not instantiate the wasm one, was withdrawn at 0.5.0. The SPEC heading now says so verbatim and adds that the section should be read as a dated record, not as a live obligation. I withdrew it for two reasons. The fallback engine and the primary disagreed (causl-wasm-ts#272, in-place mutation of a committed value, on a surface §18A.1.1 requires to be identical), and the implicit path was the accident path rather than a chosen one: 0.4.0 warned on it, 0.5.0 throws.

createCausl() is now construct-or-throw, two statements at packages/core/src/graph.ts:1500. createCauslTs is deleted from source: git grep createCauslTs over packages/*/src/** returns zero hits, and it survives only in tests that assert its absence and in dated records. Any documentation claiming it is "retained internally" is out of date, including earlier revisions of this page.

createCauslWasmSync() is the explicit synchronous constructor and createCauslWasm() is retained as preloadCauslWasm ∘ createCauslWasmSync, one codepath rather than a second implementation.

Host floor, and what actually governs it

The governing requirement is typed function references, established by feature-bisecting the shipped artefact in causl-wasm-ts#426. It is not WasmGC heap types: the artefact declares zero WasmGC struct, array or rec-group types, so a host that lacks GC heap types but has typed function references runs it fine. The floor lives in source at packages/core/src/wasm-registry.ts:94.

Treat the floor as a release-note claim, not as our measurement. Nobody has run the artefact on a real boundary host. The retired floor (Safari 18, a macOS-15 pairing, and a Node ceiling of 20) was wrong on three counts, which is exactly why I am labelling the confidence on the replacement.

Two more corrections that touch this page directly. There are two exported functions named detectBridge(), and they behave oppositely, so an unqualified claim about "the probe" is wrong whichever way it points. The one on the /wasm subpath is a real probe: #426 wired it to a 56-byte floor module and it throws WasmEngineUnavailableError on a host that fails. The one re-exported from the main barrel (packages/core/src/bridge.ts) is still a placeholder whose marshalling primitives all throw "pending #692", and it advertises gc: false on hosts where the engine instantiates perfectly well. So if you call detectBridge() from the default import you get the stub. An earlier revision of this page said flatly that the probe is real, which was true only of the subpath, and I got that wrong. And only one bridge ships, gc-classic. gc-builtins was deleted in causl-core-rs#355 and no longer exists as a build target. The ids are gc-classic and gc-builtins, never wasmgc-classic or wasmgc-builtins; earlier revisions of this page used the wrong spelling.

Multi-instance isolation is solved by engine_id multiplexing over a single WebAssembly.Instance per process, verified isolated at N=16. One behavioural caveat that matters to the cost analysis below: read() reference identity is not guaranteed across commits (§15.1), and the engine is not uniformly fresh either. A ValueHandleCache retains the original adopter reference, so identity is stable on a cache hit and fresh only on decode paths. The break is intermittent, which is harder to catch than a uniform one. That same cache is a measurable slice of §2.2.

2. Where the time actually goes

2.1 A residual per-commit clone of every live cell

This is the largest single cost and the only one of the three that scales with graph size rather than with work done. It is tracked as causl-core-rs#392, which is open and untouched by the engine.

The mux-ballast scenario exists to isolate exactly this, and it is the strongest result in the dataset because it removes every competing explanation by construction. Its stepOps are byte-identical at all three scales: 100 writes, 100 commits, 20,100 edge reads, 10,200 recomputes. The only thing that changes between rows is how many derived nodes exist and are never touched.

Four libraries stay flat between 1.02× and 1.10×, which is what identical work on a larger idle graph should cost. One pays 5.09× for nodes nothing ever reads or writes. Fitting T = α + β·Dn over the three rows gives β = 115 ns per untouched derived node per commit, and that fit predicts the middle row to within 0.6%.

The mechanism is located in engine source, not inferred:

• tools/engine-rs-bridge/src/lib.rs:1355-1372: ReentrantSnapshot::from_state() performs state.inputs.clone() plus state.deriveds.clone().
• engine_registry.rs:1017 routes any derived-carrying commit into that path, and :1069 stages the snapshot unconditionally.
• compute_bridge.rs:1097 stages it a second time at the drain's first crossing. So a derived-carrying commit whose drain enters JS pays the clone twice.

The sharpest corroboration is equality-cutoff-noop, because it strips away everything the clone could be confused with. That cell performs zero recomputes and zero edge reads and issues one no-op commit. No recompute means no compute callback and no value marshalling. Its cost still quadruples with graph size, 0.0249 ms to 0.0883 ms (high confidence at the 10k scale), while causl-ts stays flat at 0.0020 to 0.0022. Nothing scaled in that cell except the number of cells to clone.

2.2 About 2.5 µs per recompute, and it is the payload, not the crossing

Four independent estimates converge on the same constant, which is why I trust it more than any single cell:

That is 6.2× to 7.4× causl-ts per recompute. On mux-ballast at 1000 the clone term of §2.1 accounts for 8.3% of the cell and this constant accounts for 91.7%, so on any graph that is not enormous, this is the cost that dominates.

The important part is where the 2.5 µs sits. It is the callback's payload, not its crossing. Rust already crosses once per affected derived and no more (compute_bridge.rs:952-1063, the minimum-crossings floor), with no per-derived allocation on the Rust side. The JS side is where the allocation happens. dist/wasm.js:3188-3246 (#onCompute) allocates a Map, an Array, a Set and a closure per recompute, plus a depsBufView.slice() on cache miss. Every ValueHandleCache touch is four Map operations (has, get, delete, set) and there are at least two touches per recompute.

So the fix here is a shape change on the JS side, reusing scratch structures across recomputes rather than allocating fresh ones, and not a reduction in crossings. There are already as few crossings as the design allows.

2.3 About 3.1 to 4.4 µs per commit, before any derived work

A commit that touches no derived node at all still costs microseconds:

That is 13× to 19× causl-ts on the same cells. Creating a derived node is worse in isolation: 11.67 µs against causl-ts's 0.573 µs, a factor of 20.4. If your workload builds and tears down graphs frequently rather than committing into a long-lived one, this is the number that will bite you first.

3. What I published here before, and what I retract

This page has been serving wrong performance claims, so I am correcting them by name rather than deleting them quietly. Anyone who cited a figure from an earlier revision can see exactly which one moved and why.

The structural error worth naming on its own is the ceiling framing. Earlier revisions organised the whole page around a 250 µs/commit bound on isolated marshal overhead and treated clearing it as evidence of health. Isolated marshal overhead turns out to be 0.13% of the cell. A bound on a quantity that small was always going to be cleared, and clearing it never implied the engine was fast. That is why this revision leads with the costs themselves instead.

One more thing that was never shipped. The JSON value-marshalling change (BTreeMap to IndexMap) is a recommendation, not a landed change. The follow-up PR has not merged and the two cells built to measure it report inapplicable. Do not plan around it.

4. Where the engine stands today

Against causl-ts across 75 comparable cells: min 0.023×, p25 4.15×, median 6.90×, p75 13.33×, max 51.95×. The median is the honest headline. On a typical cell the wasm path takes about seven times as long as the TypeScript engine it replaced.

It wins 3 of 75 cells, and I want to be precise about what those wins are, because all three are places where causl-ts is quadratic rather than places where the wasm engine is fast:

causl-ts fits N^2.09 and N^1.88 on the first two. The wasm engine wins there by not being quadratic, which is a real property worth having, but it is a different claim from being fast.

Against the best of the other four libraries in each group, it wins 0 of 75 cells. In the harness ranking it appears in 8 comparable groups and places last in every one.

What it is currently good for

• Graph shapes where the alternative degrades super-linearly. Large equality-cutoff fanouts and large batch commits are the demonstrated cases, and the margin there is one to two orders of magnitude.
• Workloads where per-commit microseconds are not the binding constraint. If a user interaction issues tens of commits rather than tens of thousands, a 4 µs commit constant is invisible.
• Anything that needs one engine rather than two. A single Rust engine, kept honest by 5,000 differential trials per PR against causl-core-ts, is the reason there is no second implementation to disagree with (and disagreement is precisely what killed the fallback, causl-wasm-ts#272).

What it is not currently good for

• Median throughput. 6.90× causl-ts is not a rounding error, and against mobx, jotai and redux-rtk it loses every comparable group.
• Large idle graphs. Until causl-core-rs#392 lands, every commit pays roughly 115 ns for each derived node that exists, whether or not anything touched it.
• Recompute-dense hot loops. 2.5 µs per recompute is a hard floor today.
• Memory-constrained environments. Peak RSS is above causl-ts in every comparable cell, median 1.70×.
• Graph churn. 11.67 µs to create a derived node punishes build-and-discard patterns.

5. What genuinely improved

causl-core-rs#331 is fixed, and it was the big one. On linear-chain from 1000 to 10000, the scaling exponent went from N^1.932 on the quarantined 0.3.6 build to N^1.041 on the build the current run measures. The quadratic coefficient fell 14.6×, with 6.9% surviving.

That is the difference between an engine that cannot be used on a large graph at all and one that is linear but carries constants I can still attack. Everything in §2 is the linear remainder of that fix, which is why I am reporting constants rather than exponents this time.

Related open work worth tracking: causl-wasm-ts#500 is a red-by-design test pinning commit cost against graph size. Its bisection is informative on its own: the command buffer stays at 40 bytes and the diff buffer at 120 bytes at both the 1000 and 10000 scales, the JS half stays effectively flat at 4.6 µs to 5.1 µs, and the time spent inside the wasm call goes from 25.1 µs to 147.4 µs. Buffer sizes did not move, so it is not a marshalling volume problem.

6. How these numbers were measured, and what they cannot tell you

Source: causl-bench/combined.json, combined at 2026-08-11T04:13:45Z, schema version 2, commit e73620e.

The engine under test is attested rather than asserted. The runner measures @causl/causl-wasm-ts@0.3.7 against the gc-classic binary causl_engine_bridge_bg.wasm, sha256 ab4b62c1…, 714,194 bytes. That hash is what distinguishes it from the quarantined 0.3.6 build (e6883840…), whose numbers were withdrawn. The engine floor is cleared and the runner is now ranked rather than held out.

These numbers measure 0.3.7, and 0.5.0 is what ships

I want this stated before any figure on this page is quoted elsewhere. The harness pins its engine floor at @causl/causl-wasm-ts@0.3.7 because that is the release which cleared causl-core-rs#331 (causl-wasm-ts#294), and it measures exactly that version. The Gitea registry currently serves three versions of the client, 0.3.6, 0.3.7 and 0.5.0, and 0.5.0 is latest. So every measurement on this page is two minor releases behind the client an adopter installs today.

What I can say about the gap is narrow. 0.5.0 is the release that withdrew the §18A.13.1 capability fallback and turned createCausl() into construct-or-throw, which is a change to the engine-selection surface rather than to the commit or recompute path. What I cannot say is that the hot path is unchanged between the two, because nothing in this run measures 0.5.0. Read every figure here as describing 0.3.7, and treat a re-measurement against 0.5.0 as outstanding work rather than as a formality.

The confidence caveat, stated rather than buried

45% of ok cells are low confidence: 171 of 380. The drivers are dispersion (100 cells), drift (79), truncated warmup (13) and machine load (8). Low-confidence cells are excluded from ranking, but they are not excluded from the per-cell figures quoted on this page, so where a number carries a confidence label I have given it, and where two cells are both low confidence I have rounded the ratio rather than quoting three digits. Treat single-cell numbers as indicative and the converging four-estimate figure in §2.2 as the solid one.

The gap I have not closed

There is no profile of the 0.3.7 binary this run measures. All 24 captures in causl-bench/profiles/ are of the quarantined 0.3.6 build. The consequence is specific and it matters: the 2.5 µs per recompute is not yet split between JS-side #onCompute machinery and Rust-side per-node work. That split decides whether the next fix is a client PR or an engine PR, so until someone captures a profile of the shipping binary, the attribution in §2.2 rests on source reading plus the #500 bisection, not on a profile.

Why the historical wasm series disappeared

An earlier harness published a causl-wasm series whose engine label was asserted rather than observed: the column labelled "wasm" was in fact the TypeScript engine. Those samples are being deleted from the public feed rather than relabelled, because relabelling them would attach a Rust-engine claim to TypeScript-engine measurements. The attested causl-wasm-ts series takes over the causl-wasm name, so from now on one series carries that label and it is backed only by rust-ssot measurements. Losing the historical records is accepted and intended.

7. What I would fix next, and what is tracking it

Everything above diagnoses. This section says what follows from it, so a reader can tell which findings are being worked and which are only recorded. Each row names an issue in a private repository, so I give the identifier as text rather than a link.

On the ordering. Steps 2 and 3 are both larger than step 1 in raw microseconds, and I still put step 1 first. Step 1 is the only one where I can point at the code that causes it, so it is the only one I can promise a fix for. Steps 2 and 3 are constants I can describe but not yet attribute, and shipping a patch against a cost I have not located is how an optimisation turns into a rewrite.

Related reading

• Two-engine architecture: the §18A contract, the shared adopter surface, and how causl-core-ts works as the differential oracle now that the client itself is single-engine.
• Integrating causl-wasm-ts: registry configuration, the preloadCauslWasm() boot seam and the error-code contract in adopter context.
• Performance (usage guide): the cost model for graph shape and the canonical bench harness.
• Benchmarks: the live feed, the per-cell confidence labels and the withdrawal notices behind §6.