fix(example-showcase): route external-datasource fixture through the sqlite fallback

[os-zhuang]

Symptom

pnpm dev in the showcase crashes at boot with the app plugin rolled back:

2026-… ERROR Plugin startup failed: plugin.app.com.example.showcase
The module '…/better-sqlite3/build/Release/better_sqlite3.node' was compiled against a
different Node.js version using NODE_MODULE_VERSION 127. This version of Node.js requires
NODE_MODULE_VERSION 141. … (ERR_DLOPEN_FAILED)
✗ Plugin plugin.app.com.example.showcase failed to start - rollback complete

…even though the default datasource had already logged the graceful step-down
(native better-sqlite3 unavailable … dev using wasm SQLite).

Root cause

setupShowcaseExternalDatasource (invoked from the showcase app's onEnable at boot, in
examples/app-showcase/src/system/datasources/external-fixture.ts) built its MANAGED
provisioning driver with a raw new SqlDriver({ client: 'better-sqlite3' }).

better-sqlite3 loads its native addon lazily at first query, so a NODE_MODULE_VERSION
ABI mismatch (e.g. after a Node upgrade) surfaces as ERR_DLOPEN_FAILED right here. The error
propagates through onEnable → AppPlugin.start() and bricks plugin.app.com.example.showcase.

Issue #2229 hoisted every SQLite construction site onto the shared resolveSqliteDriver
native → wasm → in-memory step-down. This fixture site was the one that got missed — so the
platform's own fallback machinery couldn't save it.

Fix

Route the fixture through the same resolveSqliteDriver helper (@objectstack/service-datasource):

• Dev: a native ABI/load failure steps down to wasm SQLite (real SQL + on-disk persistence)
  instead of throwing, so onEnable / app-plugin boot survives — consistent with the default
  datasource and the declared showcase_external datasource, which already use this helper.
• Production: returns the native driver unprobed (fail-closed) — historical behavior unchanged.

Adds @objectstack/service-datasource (which exports resolveSqliteDriver) to the example's
dependencies.

Verification

• tsc --noEmit on @objectstack/example-showcase: 0 errors (after building the workspace deps).
• objectstack compile on the showcase config: succeeds (import chain resolves at bundle time).
• End-to-end objectstack serve --dev: app plugin starts, the fixture provisions
  showcase_external.db, server listens — 0Plugin startup failed / ERR_DLOPEN /
  NODE_MODULE_VERSION occurrences (native happy path unbroken).
• @objectstack/service-datasource test suite: 93/93 pass, including the sqlite-driver
  fallback tests that back this step-down.

🤖 Generated with Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 14, 2026 1:46am