engine-plugin-authoring

# Engine plugin authoring (`engines/`) Two related runbooks: adding a brand-new engine plugin, and adding a modality to one that already exists. Read `engines/AGENTS.md` first for the concepts these steps assume (op-table vtable, manifest, the valid-engine checklist, the 4-file skeleton, the engine↔runtime rule). This skill is the "how", that file is the "what/why". **Invariant that applies to both procedures:** never invent a new modality just to ship an engine — fill an existing `rac_engine_vtable_t` slot. Adding a brand-new *primitive* (a new `RAC_PRIMITIVE_*` + vtable slot) is a commons ABI change, covered by `core/AGENTS.md` → "Adding a new capability interface", not an engine change. --- ## Procedure A — add a new engine Mirror **sherpa** (multi-modality, standalone `.so`) or **cloud** (single modality, no runtime) as your template; both are the cleanest references for the 4-file skeleton described in `engines/AGENTS.md`. 1. **Create `engines/<name>/`** with the 4-file skeleton: `rac_plugin_entry_<name>.cpp`, `rac_backend_<name>_register.cpp` (skip it if there's no extra bring-up, like `neurt`), `rac_static_register_<name>.cpp`, plus your impl files. 2. **Write the manifest** in `rac_plugin_entry_<name>.cpp`: - `name` = snake_case identity (the library/framework you wrap, or your own codebase unit — NEVER a modality name; see the naming rule in `engines/AGENTS.md`). - `primitives[]` = what you serve; fill the matching vtable slots; leave every other slot explicit NULL (the all-NULL tripwire depends on this). - `runtimes[]` — only devices your compute actually depends on (NULL for cloud/HTTP engines) — see THE RULE in `engines/AGENTS.md`. - `formats[]` = the `RAC_MODEL_FORMAT_ID_*` values you accept (NULL if there's no local model file). - `priority`, `availability` (PUBLIC/PRIVATE), `package_owner`/`package_name`. 3. **Implement the op-table(s)** honoring the MODEL LIFECYCLE: `create → initialize → use → cleanup → destroy` (see `engines/AGENTS.md` for the exact signatures). Use `RAC_DEFINE_CREATE_ADAPTER(primitive, name)` (`core/include/rac/plugin/rac_plugin_entry.h`) when `create` is a plain forward onto `rac_<primitive>_<name>_create` — sherpa uses it for STT/TTS/VAD. Engines with richer create flows (llamacpp, onnx, neurt, qhexrt) hand-write it. 4. **`capability_check`** when the engine is platform- or binary-gated: use the shared 3-way helper `rac_engine_unavailable_capability(platform_supported, backend_present)` from `engines/common/rac_engine_unavailable.h`. When the backend can be entirely absent at build time (a private prebuilt archive, a sibling private repo), emit the stub with `RAC_ENGINE_UNAVAILABLE_PLUGIN(name, display, cap_fn)` from the same header — see qhexrt and neurt for the two-mode (ROUTABLE vs STUB) pattern this produces. 5. **Registration carriers:** `RAC_PLUGIN_ENTRY_DEF(<name>)` returning the vtable; a `rac_backend_<name>_register()`/`_unregister()` pair if you have extra bring-up (called directly by SDK bridges on dynamic-link hosts); a `rac_static_register_<name>.cpp` shim using `RAC_STATIC_REGISTER_BACKEND(<name>)` (routes through the register fn) or `RAC_STATIC_PLUGIN_REGISTER(<name>)` (calls the entry directly) for iOS/WASM static hosts. 6. **CMake:** call `rac_add_engine_plugin(<name> SOURCES … LINK_LIBRARIES … AVAILABILITY … PACKAGE_OWNER … PACKAGE_NAME …)` (`cmake/plugins.cmake`) from `engines/<name>/CMakeLists.txt`, fronted by your own `option(RAC_BACKEND_<NAME> "…" <default>)` + `if(NOT RAC_BACKEND_<NAME>) return() endif()` self-gate (each engine owns its own option — `engines/CMakeLists.txt` just unconditionally `add_subdirectory()`s and lets the child decide). Add `add_subdirectory(<name>)` there. Declare `primitives`/`runtimes`/`formats` ONLY in the C manifest, never in CMake, so the build graph can't drift from what the router routes. 7. **Android:** if the SDK loads the engine via `System.loadLibrary` + `nativeRegister`, add a JNI bridge with `RAC_DEFINE_ENGINE_JNI_BRIDGE(...)` (standalone per-engine `.so` — onnx, llamacpp) or `RAC_DEFINE_ENGINE_JNI_BRIDGE_NO_ONLOAD(...)` (folded into a host lib that already owns `JNI_OnLoad`, e.g. cloud → `librunanywhere_jni.so`) from `engines/common/rac_engine_jni_bridge.h`. The JVM class-path token in the macro call must match the Kotlin `*Bridge` class byte-for-byte. 8. **iOS/WASM static hosts:** make sure the host force-loads the plugin — `rac_force_load(<app> PLUGINS <name>)` in the host's CMakeLists — so the static-init Registrar TU survives linker stripping. 9. **If this engine ships an Electron/npm carrier package**, register it in `scripts/validation/gates/check_plugin_natives.py`'s `REQUIRED_OPS` dict (the ops-table symbol name(s) your entry TU references only on the routable branch) — `package-sdk.sh` calls this automatically, so an unregistered engine's stub/shell builds ship undetected. **Check which FILE actually compiles `rac_plugin_entry_<name>.cpp`** before assuming the carrier (`runanywhere_<name>`) is what to gate: sherpa/onnx/llamacpp compile it into the carrier itself (an undefined symbol reference there is the evidence), but neurt's `rac_add_engine_plugin()` call puts it on the ENGINE target (`rac_backend_neurt`) instead — the carrier there is empty boilerplate with zero symbols. Add the engine id to `EVIDENCE_IN_BACKEND_FILE` if it follows neurt's shape; discovered by actually building neurt for real and running `nm -a` on both files, not by reading the CMakeLists and assuming. ## Procedure B — add a modality to an existing engine Multi-modality is the whole point of an identity-named engine. `cloud` and `neurt` are explicitly built for this and carry the recipe inline as a comment next to their vtable. 1. Implement the new modality's op-table (e.g. a cloud TTS `g_cloud_tts_ops`, typically backed by a per-modality provider adapter under `providers/`). 2. **Fill the corresponding slot** in the engine's `rac_engine_vtable_t` (`tts_ops` / `llm_ops` / `embedding_ops` / …) — every other slot must stay explicit NULL. 3. **Add the primitive** to the manifest's `primitives[]`. 4. Update `formats[]`/`runtimes[]` only if the new modality actually needs them (per THE RULE — don't declare a runtime your new op-table doesn't depend on). No new plugin, no rename, no ABI bump — the engine already owns one `rac_engine_vtable_t` with all ten primitive slots; you're just filling another one. Grep the target engine's `rac_plugin_entry_<name>.cpp` for the phrase "To add a" — cloud and neurt both leave a comment naming exactly which slots are still free and what to add to `primitives[]`.