Escript build doesn't bundle NIF priv/ — Stats.start_run crashes at boot

[corylanou]

PR #34 added exqlite (SQLite NIF) as a dependency for token-stats persistence. The orchestrator calls Exqlite.Sqlite3NIF.open/3 in init/1 via Stats.start_run/2.

Problem: mix escript.build bundles BEAM modules but does NOT bundle priv/ directories of dependencies, where NIF shared libraries (.so / .dylib) live. At runtime the escript loads Exqlite.Sqlite3NIF (the BEAM stub) but fails to dlopen the underlying SQLite library, raising :undef on the very first call. Symphony refuses to boot.

Failed to start Symphony ... {:undef, [{Exqlite.Sqlite3NIF, :open, ["/Users/.../.local/share/symphony/stats.db", 6], []}, ...]}

This regression is masked when developing via mix run or iex -S mix because Mix sets up the full project context including NIF priv/ paths. The escript-built binary that operators actually run is broken.

Fix options

1. Switch from escript to mix release (recommended). Releases bundle dependency priv/ directories and erts. Update make build / docs / install path.
2. Configure escript_opts to embed exqlite/priv/sqlite3_nif.so (escript doesn't natively support this; would need a custom :embed_extra_applications workaround or a post-build copy step).
3. Make stats persistence soft-fail when the NIF is unavailable: wrap Stats.start_run/2 in try/rescue, log a warning, set stats_run_id: nil, and degrade gracefully. Token totals would not persist across restarts on broken builds but Symphony would still boot.

Recommend a combination: (1) for the proper packaging path going forward, plus (3) for defense-in-depth so future NIF deps don't repeat this failure mode.

Reproduction

cd elixir && mix deps.get && mix escript.build
./bin/symphony --i-understand-that-this-will-be-running-without-the-usual-guardrails
# Failed to start: :undef on Exqlite.Sqlite3NIF.open

Workaround (operators)

Run via mix instead of the prebuilt escript:

cd elixir && mix run --no-halt -e 'SymphonyElixir.CLI.main(["--i-understand-that-this-will-be-running-without-the-usual-guardrails", "/path/to/WORKFLOW.md"])'

Why now

Surfaced today after PR #34 landed and operators rebuilt the escript to pick up the new feature set. Several other NIF-using libs (e.g. lazy_html) are already in deps; PR #34 was the first to call one at boot.

[corylanou]

Codex Workpad

Status: Done

PR: #54
Merge commit: bd58f84

Plan:

• Verify the escript NIF failure in the worktree-local Elixir build.
• Add defense-in-depth so stats persistence can soft-fail when the exqlite NIF is unavailable.
• Move packaging from escript toward release output where dependency priv directories are bundled.
• Add or update focused tests for changed Elixir behavior.
• Address Codex review feedback about onboarding release-root restart instructions.
• Rebase on current origin/main and run the merge gate.
• Push, watch CI, resolve review thread, and merge.

Acceptance criteria:

• Broken escript-style NIF availability does not prevent Symphony from booting.
• Build/install docs and Make targets point operators at release packaging instead of escript packaging.
• Onboarding restart instructions use a release-root runnable command.
• Validation evidence is recorded here before Done.

Validation:

• Reproduced the original escript crash after mix escript.build: {:undef, [{Exqlite.Sqlite3NIF, :open, ...}]}.
• mix test test/symphony_elixir/stats_test.exs passed: 9 tests, 0 failures.
• mix test test/symphony_elixir/cli_test.exs test/symphony_elixir/stats_test.exs test/symphony_elixir_web/onboarding_live_test.exs passed: 26 tests, 0 failures.
• mix build assembled _build/dev/rel/symphony, including lib/exqlite-0.36.0/priv/sqlite3_nif.so.
• _build/dev/rel/symphony/bin/symphony-cli --i-understand-that-this-will-be-running-without-the-usual-guardrails --port 0 --logs-root .tmp/release-log ./WORKFLOW.md stayed up and rendered the dashboard on an OS-assigned port.
• mix test test/symphony_elixir_web/onboarding_live_test.exs passed after the review fix: 7 tests, 0 failures.
• make all from elixir/ passed after the final code change: format, lint, 493 tests with 100% coverage, dialyzer.
• PR checks passed after the final push: elixir-ci, make-all, and validate-pr-description.

Review/merge evidence:

• Responded to and resolved the Codex review thread on elixir/lib/symphony_elixir_web/onboarding_live.ex.
• PR Fix release packaging for NIF-backed stats #54 squash-merged at 2026-05-21T19:23:17Z.
• Issue Escript build doesn't bundle NIF priv/ — Stats.start_run crashes at boot #46 auto-closed at 2026-05-21T19:23:18Z.

Blockers: none.