P0: add native-library preflight and negative startup tests for SBCL/CFFI #64

New issue

Open

opened 2026-08-27 05:34:13 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-27 05:34:13 +00:00

(Migrated from github.com)

Parent: #63

Problem

Quasar can currently start Vite and only later discover that the Common Lisp control plane cannot load a required native library. The observed failure was cl-sqlite/CFFI being unable to resolve libsqlite3.so.0 or libsqlite3.so.

That failure is too late and too opaque for both developers and CI.

Required behavior

Add an explicit native-runtime preflight for the Common Lisp control-plane startup path. It should validate the production FFI/native dependencies Quasar actually relies on before declaring the stack started.

At minimum cover:

SQLite / cl-sqlite;
OpenSSL;
RabbitMQ C client where required by the loaded production systems;
libffi/CFFI runtime assumptions;
LMDB where required by the loaded production systems.

Prefer testing through the actual Lisp/CFFI loading boundary rather than only checking filenames with test -e or ldconfig.

TDD / negative cases

Tests first must prove:

a clean valid environment passes the preflight;
SQLite intentionally absent/unresolvable produces a deterministic non-zero exit;
the error names the missing dependency and tells the developer to use/fix the canonical environment (nix develop) rather than dumping only a long SBCL backtrace;
a missing native dependency prevents the supervisor from reporting Quasar ready;
the failure propagates to the top-level dev command and CI;
success does not require starting external RabbitMQ/CouchDB services unless a specific smoke test actually needs them.

Startup UX

The goal is a short actionable message before/alongside the Lisp diagnostic, for example conceptually:

quasar: native runtime preflight failed: SQLite shared library is not loadable
hint: run inside `nix develop` or fix the declared runtime environment

Do not hide the underlying Lisp/CFFI failure from logs; make the primary failure understandable.

Acceptance

Preflight is part of the real supported control-plane/dev startup path, not a CI-only helper.
CI has a hermetic negative test for at least missing SQLite.
Required native dependencies are probed through their real loading boundary.
Failure is immediate, actionable, and non-zero.
No false-ready state is emitted when a dependency probe fails.
Exact-head tests pass.

Non-goal

Do not vendor system shared libraries into the repository or catch-and-ignore CFFI load errors.

Parent: #63 ## Problem Quasar can currently start Vite and only later discover that the Common Lisp control plane cannot load a required native library. The observed failure was `cl-sqlite`/CFFI being unable to resolve `libsqlite3.so.0` or `libsqlite3.so`. That failure is too late and too opaque for both developers and CI. ## Required behavior Add an explicit native-runtime preflight for the Common Lisp control-plane startup path. It should validate the production FFI/native dependencies Quasar actually relies on before declaring the stack started. At minimum cover: - SQLite / `cl-sqlite`; - OpenSSL; - RabbitMQ C client where required by the loaded production systems; - libffi/CFFI runtime assumptions; - LMDB where required by the loaded production systems. Prefer testing through the actual Lisp/CFFI loading boundary rather than only checking filenames with `test -e` or `ldconfig`. ## TDD / negative cases Tests first must prove: - a clean valid environment passes the preflight; - SQLite intentionally absent/unresolvable produces a deterministic non-zero exit; - the error names the missing dependency and tells the developer to use/fix the canonical environment (`nix develop`) rather than dumping only a long SBCL backtrace; - a missing native dependency prevents the supervisor from reporting Quasar ready; - the failure propagates to the top-level dev command and CI; - success does not require starting external RabbitMQ/CouchDB services unless a specific smoke test actually needs them. ## Startup UX The goal is a short actionable message before/alongside the Lisp diagnostic, for example conceptually: ```text quasar: native runtime preflight failed: SQLite shared library is not loadable hint: run inside `nix develop` or fix the declared runtime environment ``` Do not hide the underlying Lisp/CFFI failure from logs; make the primary failure understandable. ## Acceptance - [ ] Preflight is part of the real supported control-plane/dev startup path, not a CI-only helper. - [ ] CI has a hermetic negative test for at least missing SQLite. - [ ] Required native dependencies are probed through their real loading boundary. - [ ] Failure is immediate, actionable, and non-zero. - [ ] No false-ready state is emitted when a dependency probe fails. - [ ] Exact-head tests pass. ## Non-goal Do not vendor system shared libraries into the repository or catch-and-ignore CFFI load errors.