[wOvAN]

What

A .rknn sidecar names its compiled engine through exec_plan, as a path the operator types. Until now that string was used verbatim, so a relative name resolved against the process working directory: to use an engine that sits in the model directory you had to type a board-absolute path. Every other model-adjacent file in the runtime is nameable relative to the model — a ResourceBundle reference, the miotts codec and ASR model defaults, the chatterbox conditional tensors, the yue2 VAE sidecars — so the five RKNN artifact options were the odd ones out.

engine::rknn::resolve_engine_path(artifact, model_root) joins a relative name onto the model root when that file exists, and returns the artifact unchanged in every other case: absolute path, unset artifact, empty root, and a relative name with nothing under the root — which keeps today's working-directory-relative behaviour, the spelling docs/models/cosyvoice3.md already documents. CosyVoice3's engine ladder resolves per element.

Why the root is a new accessor

ResourceBundle::model_root() is where a package's resources live, and for a GGUF source that is assets::prepare_model_directory(model_path).model_root — for a GGUF with embedded sidecars, a directory materialized from the file rather than the directory on disk. Joining an installed file name onto that never hits, which is exactly how this branch first failed on the board (cannot open model flow_estimator_seq200.rknn, engine loads 0).

So load_resource_bundle() now records resolve_model_root(model_path) — the canonical directory --model names, the same root a GGUF sidecar is found under — as ResourceBundle::model_directory(), and the five sidecars resolve against it. model_directory() falls back to model_root() for a bundle that was never given one, so nothing outside load_resource_bundle() changes behaviour.

Validation

Host:

g++ -std=c++20 -Iinclude -Itests/unittests tests/unittests/test_rknn_engine.cpp src/framework/rknn/engine.cpp -o /tmp/rknn_engine_test && /tmp/rknn_engine_test   ->  TEST PASS
g++ -std=c++20 -fsyntax-only -Iinclude -Iexternal/ggml/include <the five session .cpp>    ->  clean
python3 tools/check_loader_catalog_sync.py --self-test && python3 tools/check_loader_catalog_sync.py   ->  ok

rknn_engine_test (existing target, extended) covers: name under root resolves, absolute path unchanged, name with no engine under the root unchanged, unset artifact unchanged, empty root resolves nothing. src/framework/rknn/engine.cpp compiles in the non-RKNN configuration — the resolver lives outside ENGINE_HAVE_RKNN, so a CPU build links it.

Board — Orange Pi 5 Plus (RK3588), native build with -DENGINE_ENABLE_RKNN=ON, whole tree rebuilt, 0 errors. One cosyvoice3 model on models/CosyVoice3-GGUF/cosyvoice3-q8_0.gguf, flow ladder spelled twice:

abs:  "main": "/root/audio.cpp/models/CosyVoice3-RKNN/flow_estimator_seq110.rknn,...seq200.rknn,...seq250.rknn"
bare: "main": "flow_estimator_seq110.rknn,flow_estimator_seq200.rknn,flow_estimator_seq250.rknn"

(the three names are symlinks in the GGUF directory; audiocpp_server is started from an unrelated working directory). Six requests per run, 4/10/14/20/26/34 input chars, seed=1234, same reference audio, one cold server per run:

chars	abs	bare	identical
4	200	200	md5 f2864dfeb0f56734cfe56278be87d49c
10	200	200	a6f082274762d516b4b8b4ce3c34a7a1
14	200	200	e789b8aa7101a7dac84201f1c2cfc43a
20	200	200	def00c2af34c12f92b84609499f7626f
26	200	200	2032a5752b59b4ceec99ec38c79e7fe1
34	200	200	e77335e0bf953223b9fbd13cc94d5b5e

Engine loads 4 in both runs (flow.dit.rknn.loaded_frames 200/250). On a binary without the model_directory() fix the bare run fails all six requests with CosyVoice3 flow estimator RKNN: cannot open model flow_estimator_seq200.rknn and loads 0 — the resolution, not the working directory, is what carries it.

Docs: docs/build/rockchip-npu.md states the resolution rule.

Limits

• Resolution is existence-gated by design: a typo'd name that exists nowhere keeps the old behaviour (the engine loader reports it), so the change never silently redirects an artifact that the operator meant to be CWD-relative.
• Only the five RKNN artifact consumers were wired; no other option goes through the resolver.

[0xShug0]

@wOvAN Merged 🎉