SurfSense.deb declares no dependency on the Vulkan loader #1984

The gap

docs/architecture/local-models/runtime.md lists this under Known gaps:

The Linux .deb declares no dependency on the Vulkan loader (electron-builder.yml has no deb section), though libggml-vulkan.so needs libvulkan.so.1 from the host; without it the app runs on the CPU.

Why it matters

Vulkan is the only GPU backend off Apple Silicon, so the loader is not an optional extra — it is the whole graphics path. It ships with the GPU driver on an ordinary desktop, but it is a separate package on a minimal or server install, and when it is missing dlopen fails and ggml skips the backend without a word. Exit 0, no error, every model on the processor. That is the exact class of failure this runtime is shaped around, because it looks like success.

The user does not even get the app's own name for it. With the loader absent ggml lists no GPU while the operating system still sees the card, which is the broken_install status — a state the app has copy for and a deb could have prevented at install time. The AppImage cannot declare dependencies at all, but the deb can, and does not.

Where

• surfsense_local/electron/electron-builder.yml — the linux: block. It sets target: [AppImage, deb] and there is no deb: section anywhere in the file. Adding that section is the whole change.
• electron-builder (^26.16.1, in surfsense_local/electron/package.json) supplies its own default depends list when the key is absent, and setting the key replaces that list rather than adding to it. Check what your version defaults to and keep what is still needed, or the fix for one dependency drops several others.
• surfsense_local/electron/scripts/fetch-llamacpp.mjs — what is actually staged into llamacpp/, so you can confirm which file carries the link rather than taking the doc's word for it. .github/workflows/build-sdcpp.yml's Linux gate already encodes the rule that only libggml-vulkan.so may need the loader.

What done looks like

• The built .deb names the Vulkan loader in its control metadata, and the rest of electron-builder's dependency list is intact.
• Whether that is depends or recommends is the one real decision and it is yours. depends makes apt refuse the install without the loader, which is strong given the app does run without it, just on the processor; recommends is installed by default on Debian and Ubuntu and can be declined. Say which you chose and why in the PR.
• The AppImage is left alone. Its format carries no dependency metadata, so there is nothing to declare; if you think it should warn at runtime instead, that is a separate issue.
• If your change alters what a deb user actually experiences, update the Failure behavior entry for "No Vulkan loader" in the runtime doc, and delete the Known gaps line in the same PR.

What not to change

Nothing about Windows. vulkan-1.dll is in System32 on a stock install, which is why nothing is bundled or declared for it. And leave extraResources and linux.target as they are — this is a metadata addition, not a repackaging.

How to verify

Nothing reads electron-builder.yml in a test today, so the real check is the package itself:

cd surfsense_local/electron
pnpm exec electron-builder --linux deb
dpkg-deb -f release/SurfSense.deb Depends Recommends

pnpm test already collects scripts/**/*.test.mjs — see scripts/sdcpp/recipe.test.mjs — so if you want a guard that runs in CI rather than only on your machine, a check that the YAML still names the loader belongs there. Write it first and watch it fail. Then:

python scripts/check_docs.py          # from the repo root, for the doc edit
cd surfsense_local/electron && pnpm test && pnpm typecheck

Before you start

Read CONTRIBUTING.md, the runtime doc and ADR 0012, which is why Vulkan is the only backend to declare. Open your PR against dev, not main. Comment here to claim this.