Memory And Disposal

WASM memory management and disposal

Mental model

WASM objects are not visible to the JS garbage collector — a leaked shape grows WASM linear memory silently. Every branded shape (Vertex, Edge, Wire, Face, Shell, Solid, CompSolid, Compound) IS a disposable handle: src/core/shapeTypes.ts wraps each via createHandle() (src/core/disposal.ts). Cleanup has one primary rule and one safety net:

• Primary: dispose deterministically with using / Symbol.dispose / DisposalScope. This is the plan.
• Safety net: a FinalizationRegistry (disposal.ts) frees handles that were never disposed — non-deterministic, GC-timed, never something to rely on. Environments lacking it get a no-op stub plus a console.warn (disposal.ts).

User-facing prose lives in docs/memory-management.md (the four mechanisms, using examples, LIFO, heap-monitoring snippets, three common leak patterns) and the maintainer deep-dive in src/core/README.md. This skill adds what those lack: the tool-selection table, the pattern-checker rule, the kernel-dependent free semantics, and the leak-hunting workflow. Do not re-read those two docs for basics — point users to them.

using requires "target": "ES2022" + "lib": ["ES2022", "ESNext.Disposable"]; the repo tsconfig.json:3,6 already sets this.

The three tools — when to use each

using for a single handle

using box = box(1, 1, 1);

Any branded shape works directly this way, since every shape is a ShapeHandle. Accessing .wrapped after disposal throws 'Shape handle has been disposed' (disposal.ts); the KernelHandle variant throws 'kernel handle has been disposed' (disposal.ts). Double-dispose is safe — dispose is idempotent and inner delete() failures are swallowed.

DisposalScope — register vs track, and LIFO

Two registration methods, both return their argument for inline use:

• scope.register(resource) — for anything Deletable ({ delete() }); calls .delete() on dispose (disposal.ts).
• scope.track(disposable) — for anything with [Symbol.dispose] (branded shapes, Curve2DHandle); calls [Symbol.dispose]() (disposal.ts).

DisposalScope disposes in LIFO (reverse-registration) order (disposal.ts). The ordering rule (also a CLAUDE.md gotcha): register a dependency AFTER its dependee, so the dependent is disposed first. If B is built from A, register A first and B second.

Real code overwhelmingly uses the scope directly — using scope = new DisposalScope() then scope.register(...) (e.g. src/sketching/draw3d.ts, src/operations/threadFns.ts, src/gear/gearFns.ts). Prefer this idiom.

Scope helpers for Result-returning ops

kernelCallScoped(fn, code, message) (src/core/kernelCall.ts) creates a scope, runs fn, and disposes deterministically after return or throw — the canonical wrapper for a *Fns.ts op that needs intermediate kernel allocations and returns Result<AnyShape>:

return kernelCallScoped(
  (scope) => {
    const axis = scope.register(makeKernelAx1(origin, dir));
    return getKernel().revolveVec(shape.wrapped, axis);
  },
  BrepErrorCode.REVOLUTION_NOT_3D,
  'Revolution failed'
);

withScopeResult(fn) (disposal.ts) is the same scope discipline for any Result-returning function. withScopeResultAsync(fn) (disposal.ts) is the async variant — its body is return await fn(scope). The await is load-bearing: using disposes synchronously at end of block, so without await the scope would dispose before the promise settles. Keep the await.

These helpers are exported and documented but rarely called directly in src/; present them as available conveniences, not the dominant convention.

The gate: require-using-for-handles

The pattern checker (scripts/check-patterns.ts, severity error) flags any createHandle() / createKernelHandle() call not bound with using. Message: "createHandle() without \using` keyword risks WASM memory leak.`"

Excused positions (check-patterns.ts):

• using x = createHandle(...)
• return createHandle(...) — caller owns lifetime
• direct argument to another call, e.g. scope.register(createHandle(...))
• property assignment { k: createHandle(...) } or array literal [createHandle(...)]

It does not catch handles nested in ternaries/sub-expressions — those slip through. Scan scope is src/**/*.ts only (tests and scripts exempt, check-patterns.ts).

Inline disable (line above or inline):

// brepjs-patterns-disable: require-using-for-handles

Real use: createCurve2DHandle in src/core/curve2dHandle.ts, which returns the handle for the caller to own.

Where it runs: npm run check:patterns, pre-commit via lint-staged on staged src/**/*.ts, and CI's quality job. The baseline .pattern-baseline.json contains zero require-using-for-handles entries (see the quality-gates skill for the current baseline composition) — so ANY new violation of this rule fails the gate immediately; there is no baseline slack to absorb it. For baseline mechanics and the general pattern-checker workflow, see the quality-gates skill.