feat(tests): add cross-stack parity gate vs jsartoolkitNFT-Node (jsartoolkitNFT#584 Track 2, refs #170, #166 Track B)

[kalwalt]

Refs jsartoolkitNFT#584 Track 2, #170, #166 Track B.

Summary

Closes Track 2 of webarkit/jsartoolkitNFT#584 by adding a cross-stack parity gate that compares Rust + C++ FFI matcher outputs against jsartoolkitNFT-Node on the same fixtures.

Three new pieces, all under WebARKitLib-rs (per the brainstorming decision earlier this session — the Rust + C++ FFI implementations live here, so the comparison code does too):

1. tools/jsartoolkitnft-bridge/ — Node.js bridge tool

A small Node script that drives @webarkit/jsartoolkit-nft@^1.9.0 (the Node entry point) over the same NFT fixtures the Rust corner-error gate consumes, and writes a expected-js.json sidecar with the JS-stack loaded_marker_id and first_match.{id, pose}.

Run with:

cd tools/jsartoolkitnft-bridge
npm install
npm run regen

Bridge chdirs to crates/core/examples/Data/ so jsartoolkitNFT's Emscripten NODEFS sees camera_para.dat, pinball.fset, pinball.fset3, pinball.iset at the relative paths it expects — no duplication of ~890 KB of marker assets.

2. crates/core/tests/cross_stack_parity.rs — Linux-only integration test

Reads the JSON sidecar, drives CppFreakMatcher + RustFreakMatcher through KpmHandle on each listed fixture, asserts:

• Tier-1: matched_id agrees across all three stacks (JS, C++ FFI, Rust).
• Pose element-wise: max rotation diff < 0.05 (dimensionless), max translation diff < 10 mm. Generous tolerances absorb the current pre-feat(ar2): implement .fset write support #39 cross-stack envelope.

Linux-only #[cfg] gate matches the existing kpm_regression convention: C++ FFI matched_id + pose are platform-sensitive until #170 fully closes, but the JS sidecar's WASM is hermetic across host platforms (the WASM bytes encode the compile-time libc++ behavior), so the sidecar itself is portable; what's not portable is the C++ FFI side of the comparison.

3. CI wiring

cross_stack_parity added to the Run ffi-backend integration tests step on kpm-build (ubuntu-latest). Runs alongside kpm_regression, nft_pipeline, ar2_pinball_io. No Node toolchain needed in CI (sidecar is pre-generated and committed).

Day-1 sidecar findings

On pinball-demo.jpg, jsartoolkitNFT-Node@1.9.0 produces:

	loaded_marker_id	pose row 0
JS	0	[0.98670, 0.16253, 0.00159, -182.52]
Linux pre-#39 C++ FFI	0 (page 0)	[0.98658, 0.16427, 0.00272, -181.92]
Windows / post-#39 C++ FFI	0 (page 0)	[0.98615, 0.16710, 0.06406, -182.16]

The JS values sit on the Linux pre-#39 side of the cross-platform divide (pose[0][2] ≈ 0.0016, vs Linux pre-#39's 0.0027, vs canonical 0.0641). That's because npm-published @webarkit/jsartoolkit-nft@1.9.0 was compiled against the pre-#39 C++ matcher and the libc++ iteration order is baked into the WASM bytes. Once WebARKitLib#39 lands and jsartoolkitNFT republishes, the sidecar's regen here picks up the canonical numbers and all three stacks should converge.

So the gate today is checking: "the pre-#39 JS, our pre-#171 Rust, and our Linux pre-#39 C++ FFI are all in the same ballpark." All three sit on the same side of the cross-platform divide, so this gate should pass today on Linux CI. Post-#39 + post-#171 + post-jsartoolkitNFT-rebuild, all three converge on the canonical baseline and tolerances can tighten.

Why this is its own PR (not folded into #172)

PR #172 is the WebARKitLib submodule bump. This PR predates that landing — it tests against pre-#39 jsartoolkitNFT npm + pre-#39 C++ FFI to establish the parity infrastructure now. When the chain catches up (#39 → jsartoolkitNFT submodule bump → jsartoolkitNFT republish → bump @webarkit/jsartoolkit-nft dep here → regen sidecar), the gate keeps gating; only the reference values move.

Test plan

• cargo build --tests --features ffi-backend builds clean (compiled cross_stack_parity.rs via temporarily relaxed cfg gate to verify; restored to target_os = "linux" for the commit).
• cargo fmt --all -- --check clean.
• cargo clippy --all-targets --features ffi-backend -- --deny warnings exit 0.
• npm install && npm run regen locally — produces expected-js.json with the values above.
• CI on kpm-build (ubuntu-latest) runs cargo test --test cross_stack_parity --features ffi-backend — pending CI on this PR.

Open follow-ups

• Add pinball-seq* fixtures to the bridge's FIXTURES array once they reliably match in jsartoolkitNFT (seq1 + seq4 should now that fix(kpm): use BTreeMap for Hough vote tally and VisualDatabase keyframes to remove Rust-side matcher nondeterminism (refs #170) #171 lands deterministic Rust).
• Bump @webarkit/jsartoolkit-nft here once jsartoolkitNFT republishes post-feat(ar2): implement .fset write support #39 → regen → tighten pose tolerances.
• Consider whether to publish a similar bridge tool inside jsartoolkitNFT (for symmetric "WebARKitLib-rs vs JS" gates from that side) — that's part of jsartoolkitNFT#584 Track 1, separate work.

Refs

• Closes jsartoolkitNFT#584 Track 2.
• Refs investigate: Rust backend matched_id is non-deterministic across runs (HashMap random hasher likely affecting BHC tree topology) #170 (matcher determinism, both halves).
• Refs feat(tests): replace symmetric tier-2 gate with absolute corner-error against external references (hand-annotated GT + jsartoolkitNFT-node parity) #166 Track B (cross-stack parity check, originally scoped as the long-term complement to Track A's annotated GT).
• Independent of fix(kpm): use BTreeMap for Hough vote tally and VisualDatabase keyframes to remove Rust-side matcher nondeterminism (refs #170) #171 (Rust BTreeMap fix) and chore(submodule): bump WebARKitLib for std::map matcher-determinism fix (refs #170) #172 (submodule bump) — both still open; this PR predates them.

🤖 Generated with Claude Code

[kalwalt]

Hold for jsartoolkitNFT npm republish

Marking this informally on hold (still CI-green, still mergeable) until jsartoolkitNFT publishes a new npm release picking up jsartoolkitNFT#586's post-#39 WASM artifacts.

Why wait

The committed expected-js.json here was generated against @webarkit/jsartoolkit-nft@1.9.0, which was built before WebARKitLib#39. After jsartoolkitNFT republishes, the JS reference values will shift to match the canonical post-fix C++ / Rust baselines that PR #172 lands. Merging #173 now would mean immediately filing a follow-up "regen sidecar" PR — cleaner to do both in one merge.

Pre-merge checklist (do these in order, then merge)

1. Wait for jsartoolkitNFT npm release containing the rebuilt WASM (post-#586 master).
2. Bump the dependency in tools/jsartoolkitnft-bridge/package.json:

   - "@webarkit/jsartoolkit-nft": "^1.9.0",
   + "@webarkit/jsartoolkit-nft": "^<new-version>",

3. Regen the sidecar:

   cd tools/jsartoolkitnft-bridge
   rm -rf node_modules package-lock.json
   npm install
   npm run regen

4. Inspect expected-js.json — the first_match.pose[0][2] value should shift from ~0.0016 (pre-fix Linux quirk) to ~0.064 (canonical, matching our C++ FFI and Rust). If it does, the fix took.
5. Optional: tighten POSE_ROT_TOL (currently 0.05) and POSE_TRANS_TOL (currently 10.0) in crates/core/tests/cross_stack_parity.rs. With JS converged, the cross-stack envelope is much smaller — POSE_ROT_TOL = 0.01 and POSE_TRANS_TOL = 2.0 (mm) are probably defensible. Skip this step if you'd rather keep the generous bounds for headroom.
6. Commit and push — CI re-runs against the new sidecar.
7. Merge if green.

Not blocked

This PR is structurally complete — the bridge tooling, the Rust integration test, and the CI wiring all work. We're just holding the merge for stronger reference numbers in the day-1 baseline. If the jsartoolkitNFT release stalls for any reason, this can land as-is with pre-fix JS numbers and a regen PR can follow later.

Tracked alongside WebARKitLib-rs#170 (the umbrella) and jsartoolkitNFT#584 Track 2 (which this PR closes).