Development

Toolchain

Development uses Node 24.19.0, pnpm 12.4.2 and Rust 1.96.0.

Scripts and benchmarks use TypeScript, run through tsx, and are included in pnpm typecheck. Use the package scripts below, or pnpm exec tsx scripts/<name>.ts for a direct invocation. The MPFR oracle generator remains Python because it uses ctypes to call the system MPFR library for independent, directed-rounding checks.

rustup toolchain install 1.96.0 --component rustfmt --component clippy --target wasm32-unknown-unknown
pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm test:rust
pnpm typecheck
pnpm lint
pnpm format:check
pnpm check:package

build:ts cleans dist. Run it before native/Wasm builds and before aggregating native assets from multiple platforms. The Rust wrapper resolves rustc, rustfmt and clippy through rustup; LANEOPS_RUST_TOOLCHAIN can select another installed toolchain.

Repository layout

Directory	Responsibility
src	Public API, validation, arenas, pipelines, Workers and backend adapters
crates/core	Shared numerical semantics and explicit SIMD kernels
crates/bindings-napi	Synchronous Node-API adapter
crates/bindings-wasm	Private linear-memory ABI
spec	Operation registry and executable numerical contracts
scripts	Generation, builds, numerical evidence and candidate/package verification
tests	API, numerical, memory, ABI, registry, package and browser regression suites
benchmarks	End-to-end, resident, typed, mathematical, pipeline and Worker measurements
experiments/async-task	Opt-in, unpublished alternative Node binding experiment
examples/vite	Real browser consumer with explicit Worker/Wasm asset URLs
docs	English VitePress documentation and historical verification records

Tests and benchmarks are named by capability. P0–P8 names in the registry and historical reports identify implementation milestones. Current documentation is organized by topic: guide/ for usage, reference/ for contracts and generated signatures, contributing/ for maintenance, and archive/ for dated evidence.

Generated files

spec/operations.json generates operation IDs, TS interfaces/adapters, Rust decoding, test lists and the expanded matrix.

pnpm generate
pnpm check:generated
pnpm test:registry
pnpm test:extension

Commit generated outputs with registry changes. Drift checks are read-only. Numerical kernels, independent references and boundary datasets remain handwritten. The extension rehearsal creates and builds a temporary probeNeg operation, checks scalar fallback and Wasm SIMD, then removes the temporary package. Consumers never run generation or compilation during installation.

Verification entries reference repository-relative Markdown reports and current test suites. The support audit checks report paths, nonempty files and scope metadata without requiring a particular documentation directory. It does not re-run or authenticate the historical results. Update registry references when moving reports or tests. The executable fingerprint includes semantics/accuracy fields, including some documentation references; moving those paths requires regenerated matching assets. Do not weaken the fingerprint to make a documentation move pass.

Tests and package consumers

pnpm test runs TS suites through Vitest. pnpm test:registry separately runs the *.node.test.ts registry, evidence-audit, candidate-policy and command-runner tests through tsx --test. Neither replaces the other. pnpm check:math checks the committed MPFR oracle without requiring MPFR locally. Regenerate it only intentionally with pnpm generate:math.

pnpm check:package packs and installs the real archive offline in an isolated consumer, with install scripts disabled. It checks exported assets, Node/browser conditions, NodeNext/Bundler types, native/dual Wasm, Workers and missing-addon fallback. Worker lifecycle and package-consumer fixtures are authored in TypeScript and compiled into temporary JavaScript files before execution, so these checks still exercise plain Node without a TypeScript loader in the worker or consumer.

pnpm exec playwright install chromium firefox webkit
pnpm test:browser
pnpm example:vite

Browser checks require a build and consume the packed package. They cover static ESM, Vite production output, scalar/required SIMD, unsupported-SIMD fallback, missing assets and Worker lifecycle. Reports/traces go under artifacts/browser. A Firefox launch failure is a failed browser check, not a skipped success.

Documentation

pnpm docs:dev
pnpm docs:build
pnpm docs:preview

The build validates internal page links; keep that validation enabled. Local search, responsive navigation and light/dark themes are bundled by VitePress. The generated site is in docs/.vitepress/dist, served at laneops.ntnyq.dev. The default base is /. For a subpath deployment, build with:

pnpm --filter docs build --base /laneops/

Serve the generated directory with a static host. No deployment or publishing step is run automatically. Historical reports are linked from their index and excluded from search so current usage and contracts remain discoverable. VitePress configuration follows the official site configuration reference.

Full verification

pnpm release:check performs the local build and library checks. pnpm verify:baseline also collects all performance suites and the Rust core benchmark in a fresh evidence directory. pnpm verify:candidate validates an existing build and one immutable tarball with source/asset consistency checks. See candidate verification for their distinct responsibilities.