fix: harden Rust FFI boundary

[tuannx]

Closes #25.

What changed

• recover poisoned singleton-engine mutexes instead of panicking in exported FFI calls
• remove unchecked enum transmute calls from the engine
• use checked primitive-to-enum conversion with safe fallback values
• add regression coverage for poisoned-lock recovery, enum sentinels, and out-of-range values

Why

The singleton setup/cleanup paths used Mutex::lock().unwrap(), so a poisoned lock could panic at a C ABI boundary. The engine also relied on several unsafe primitive-to-enum transmutes. Both paths now fail safely without changing the public ABI.

Validation

• cargo test in vnkey-engine — 41 passed
• git diff --check — passed
• rg 'std::mem::transmute|ENGINE\\.lock\\(\\)\\.unwrap' vnkey-engine/src — no matches

cargo clippy --all-targets -- -D warnings remains blocked by 23 pre-existing lints (for example byte_char_slices, manual_range_contains, and existing public raw-pointer FFI warnings); this PR does not expand scope to rewrite those APIs.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9fda753c-0b1f-49bb-b3a0-73ee50ceb61b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[tuannx]

Overall validation and Arcade baseline

The focused engine suite is green: 41 tests passed (3 unit regressions + 38 integration tests). The updated source has no remaining std::mem::transmute or ENGINE.lock().unwrap() matches.

I also ran Arcade Agent against a fresh cache on vnkey-engine/ using the PKG recovery algorithm:

• 9 Rust files
• 193 entities / 335 dependency edges
• 8 recovered components
• BalancedArchitectureScore: 0.6898
• strongest signals: Responsibility Focus 1.0, Interface Segregation 1.0, Boundary Clarity 0.8750
• follow-up signals: Hub Balance 0.2857, Dependency Distribution 0.5341, one reported dependency-cycle smell

These figures are an architecture baseline rather than a correctness verdict. The reported Engine / Ffi / Input / Vnlexi cycle should be manually validated because package-based static recovery can include parser/ownership noise.

Proposal: add Arcade after Rust support is released

Arcade's public v0.1.1 does not include the Rust parser yet; Rust support is currently in arcade-agent#18. Once it ships in a tagged release, I suggest a separate workflow pinned to an immutable release/SHA:

1. analyze vnkey-engine/ as Rust with the PKG algorithm;
2. upload JSON + HTML artifacts first, without gating merges;
3. post a short PR summary after maintainers opt in;
4. establish the first reviewed report as the baseline.

I can send that follow-up workflow PR as soon as a released Rust-capable action is available.