node-ABI breakage class: better-sqlite3 built under one node, invoked under another — detect legibly, decide install strategy, revisit native-store choice

[amrmelsayed]

Owner-requested look at the class (not just the two symptom bugs)

Filed at the owner's ask. codev depends on better-sqlite3, a NATIVE module built against whatever node ran the install (field case: a version manager's v22, MODULE_VERSION 127). When the user's shell later resolves node to a different major (field case: a package manager's v25, MODULE_VERSION 141 — installed as an ordinary transitive dependency of unrelated developer tools), EVERY sqlite-backed afx path throws a raw NODE_MODULE_VERSION stack trace that reads like a codev bug. The mixed-node-manager setup that triggers this is completely normal; any user with two node sources is one shell-restart away. The same event produced the #1712 half-registration and exposed the #1713 message honesty gap, which made the breakage near-silent rather than loud.

(For fairness to the CLI: afx status under the mismatch exits 1 with the error on stderr — the exit-code behavior is correct. The problem is the error's LEGIBILITY and the class's preventability.)

Three questions for this issue to resolve (decisions are the owner's; builder prepares the analysis)

1. Detection: should codev catch the ABI-mismatch error at the DB-open boundary and fail with an actionable message — naming the node that built the module, the node currently running, and the remedy (rebuild command / switch node) — instead of the raw stack trace? (Cheap, unambiguous, worth doing under any answer to 2/3.)
2. Install strategy: postinstall rebuild? prebuilt binaries for supported ABIs (better-sqlite3 ships prebuilds — verify coverage)? a documented supported-node range with a refusal outside it? Each has failure modes (postinstall needs a toolchain; prebuilds lag new node majors; refusals frustrate).
3. Dependency choice: is a native sqlite the right store for a CLI invoked under whatever node a shell resolves? Alternatives to weigh honestly: node:sqlite (built-in, removes the ABI class entirely but pins a minimum node), a pure-JS store (perf/durability trade-offs vs the mailbox-first write patterns), or status quo + detection. NOTE: this connects to the standing native-dep decision already reserved to the owner on tower owner-lock robustness: surface refusal in the CLI, graceful-shutdown same-address overlap, clear-owner escape hatch (follow-up to #1629) #1690 (flock) — the two should be decided with one policy on native dependencies, not piecemeal.

Suggested shape

Builder produces a short analysis (options, costs, what breaks) as the issue's first deliverable; owner rules; implementation follows the ruling. Item 1 (legible error) can proceed immediately regardless.