@qvac/fabric

Shared bare addon that hosts the qvac-fabric runtime (Tether's fork of llama.cpp + ggml) as a single prebuilt shared library. Consumer addons (@qvac/llm-llamacpp, @qvac/embed-llamacpp, …) declare @qvac/fabric as an npm dependency and dynamically link against it, so the multi-hundred-megabyte llama/ggml runtime is built once and loaded once per process instead of being statically embedded into every addon.

It follows the npm + prebuilds/ + include_bare_module(... PREBUILD) + companion-.bare pattern. See INTEGRATION.md for the consumer guide.

What it ships

• Prebuilt .bare shared library (prebuilds/<platform>/qvac__fabric.bare) — contains libllama, libcommon, libmtmd, and libggml-base. It exports the full llama_* / LLAMA_* / ggml_* / gguf_* / mtmd_* C API plus the common_* and json_schema_to_grammar C++ symbols.
• C++ headers (prebuilds/include/) — ggml*.h, gguf.h at the root and llama.h, llama-cpp.h, common/*.h, mtmd/*.h under include/llama/.
• CMake config (prebuilds/share/qvac-fabric/) — find_package(qvac-fabric) exposes qvac-fabric::headers for compile-time includes
• ggml compute backends — on Linux, Android, and Windows, separate shared libraries ship under prebuilds/<platform>/qvac__fabric/ and are loaded at runtime via ggml_backend_load_all_from_path(). On macOS and iOS the backends are linked statically inside qvac__fabric.bare and self-register on load. On linux-x64 this includes the ROCm/HIP backend (libqvac-ggml-hip.so, gfx1151) alongside Vulkan; the DL loader skips it on non-AMD hosts. Linux packages also include an RPC backend with RDMA auto-negotiation and TCP fallback.

Platform packages

Since 0.18, @qvac/fabric is a meta package that ships the loader, headers and CMake config. The runtime and backends for each desktop host live in a version-locked platform package selected at install time through os/cpu filtered optionalDependencies:

| Host | Package | | --- | --- | | linux-x64 (glibc) | @qvac/fabric-linux-x64 | | linux-arm64 (glibc) | @qvac/fabric-linux-arm64 | | darwin-arm64 | @qvac/fabric-darwin-arm64 | | darwin-x64 | @qvac/fabric-darwin-x64 | | win32-x64 | @qvac/fabric-win32-x64 |

Do not depend on desktop platform packages directly. Supported installers are npm 7+, pnpm, bun, and Yarn Berry. Yarn v1 and --omit=optional installs skip the platform package and fail at require time with an error naming the missing package; a runtime in the package's own prebuilds/<host> (source builds, fabric 0.17 and earlier) always takes precedence. Consumer addons locate the runtime with the CMake template and the ggml backends with require('@qvac/fabric/backends').resolveBackendsDir(); see INTEGRATION.md.

Mobile targets are cross-built, so no install host ever matches their os, and optionalDependencies filtering can never select them. Mobile applications must declare @qvac/fabric and the target's platform package as direct dependencies at the same exact version, one that satisfies the @qvac/fabric range their addons declare:

| Target | Package | | --- | --- | | android-arm64 | @qvac/fabric-android-arm64 | | ios (device + simulators) | @qvac/fabric-ios |

Architecture

┌──────────────────────────────────────────────────────────┐
│  Consumer addons (.bare)                                   │
│  @qvac/llm-llamacpp   @qvac/embed-llamacpp   …             │
│  link qvac-fabric::headers + DT_NEEDED [email protected] │
└───────────────────────────┬────────────────────────────────┘
                            │ (ELF SONAME dedup → one load)
┌───────────────────────────▼────────────────────────────────┐
│  [email protected]  (this package)                        │
│  libllama · libcommon · libmtmd · libggml-base              │
│  + ggml backend modules (.so/.dll; static on Apple)         │
│  exports llama_* / LLAMA_* / ggml_* / gguf_* / mtmd_* /     │
│          common_* / json_schema_to_grammar                  │
└───────────────────────────┬────────────────────────────────┘
                            │
┌───────────────────────────▼────────────────────────────────┐
│  qvac-fabric vcpkg port (forked llama.cpp + ggml)           │
└──────────────────────────────────────────────────────────┘

Key design points:

• Single runtime load — Every consumer addon's .bare has DT_NEEDED: [email protected]. The dynamic linker deduplicates by SONAME, so the llama/ggml runtime is loaded exactly once per process, no matter how many fabric-based addons are present.
• No JS API — @qvac/fabric is a carrier module. Consumers require() it only to register the .bare with the bare runtime before resolving their own addon (see INTEGRATION.md Step 5). All inference happens through the consumer's own C++ code against the shipped headers.
• One C++ runtime (Linux) — the module embeds libc++ and exports the Itanium C++ ABI under the ELF version node QVAC_FABRIC_ABI_1. Consumer addons link with -nostdlib++ and record a DT_VERNEED on that node, which is what keeps their __cxa_* / typeinfo references from binding to the GNU libstdc++.so.6 that the bare executable brings into the process' global lookup scope. The node name is part of the ABI: renaming it requires rebuilding every consumer. See symbols.map and arch/qips/linux-fabric-libcxx-ownership.md.
• Backends — ggml compute backends are self-contained: each links its own ggml statically and imports no ggml_* from the module that dlopens it.

Build

npm install
npm run build   # bare-make generate && bare-make build && bare-make install

Linux builds require the libibverbs development package (libibverbs-dev on Debian/Ubuntu). On linux-x64 a ROCm/TheRock SDK is also required, discovered via ROCM_PATH or /opt/rocm. The hip port is deterministic — it hard-fails rather than installing empty, so that the vcpkg binary cache cannot conflate a no-HIP build with a real one under the same ABI hash. The hip dependency is gated on linux & x64.

Linux hosts that use the RPC backend must provide libibverbs.so.1 (libibverbs1 on Debian/Ubuntu). RDMA use also requires the provider package for the host's hardware. The library is required even when the connection falls back to TCP because the dynamic loader resolves it before loading the RPC backend. Other Fabric backends remain available when the RPC backend cannot be loaded.

Supported platforms

| Platform | Triplet | Backends | |----------|---------|----------| | Linux | x64-linux, arm64-linux | shared .so under prebuilds/<platform>/qvac__fabric/ (RPC with RDMA auto-negotiation; x64 also ships ROCm/HIP) | | macOS | arm64-osx | static (CPU, Metal) inside .bare | | Windows | (default MSVC) | dynamic .dll under prebuilds/<platform>/qvac__fabric/ | | Android | arm64-android | shared .so under prebuilds/<platform>/qvac__fabric/ | | iOS | arm64-ios | static inside .bare |