Develop the native layer

Port code to Rust only for measured performance, platform integration, or resource-control needs. Keep orchestration and product policy in TypeScript.

How do I add or change a native export?

Define the Rust implementation and Node-application programming interface (API) signature, expose it from the Rust package, update TypeScript declarations and wrappers, then extend validation and contract tests. Preserve the JavaScript fallback when the public contract requires one; otherwise fail explicitly when the addon is unavailable.

How do I build target variants?

The build pipeline selects target triples and optional hardware variants, compiles release artifacts, and packages names the loader can resolve. Environment flags affect the build target or diagnostics, not the public API. Test the ordinary target plus any variant whose resolution order changed.

How do I diagnose loading and cancellation?

Start with the resolved candidate list, platform identity, file permissions, and validateNative mismatch. For asynchronous work, test cancellation before start, during execution, and after completion; a cancellation token must never resolve the same task twice.

Change crates/pi-natives/src and packages/natives together; a signature that exists on only one side fails at load rather than at build.

Build from the repository root with bun scripts/ensure-dev-native.ts, then run the focused TypeScript contract test in a fresh process so the loader cannot reuse an already loaded addon. Inspect git status --short afterward: generated binaries and target directories are build products, not source changes. If the test fails, compare the exported Rust symbol, generated binding, wrapper name, and packaged filename before changing loader fallback behavior.