C++ layer full cleanup: correctness, ABI, backend abstraction, JNI safety

[sanchitmonga22]

Summary

Full refactor of sdk/runanywhere-commons/ plus coordinated updates to all 5 SDK consumers (Swift, Kotlin, React Native, Flutter, Web). 14 commits, ~3,000 lines changed.

Driven by the 7-agent audit in CPP_LAYER_AUDIT.md at repo root. Every verified finding from that audit is either fixed here or listed as documented follow-up in sdk/runanywhere-commons/CPP_LAYER_CLEANUP_STATUS.md.

What this PR delivers

Correctness fixes

• sherpa-onnx runtime ABI version check (was SIGSEGV on mismatch, now clean error)
• JniScope RAII helper applied to all 17 native→Java callback sites in the JNI bridge (was 11/149 exception-check coverage, now 100%)
• Completed the wakeword service wire-up to its existing ONNX backend (7 TODOs closed)
• std::atomic on download manager health flags (was TSan data-race candidate)
• macOS-host-JDK / Android-NDK AttachCurrentThread portability cast

Architectural foundations

• RAC_NODISCARD on 479 public functions via new rac_attrs.h
• rac_hardware_query_capabilities() public C API + rac_hardware_report_t versioned struct
• Abstract rac::backends::IInferenceBackend class (incremental retrofit of 5 backends is documented follow-up)
• New rac_wakeword_provider_ops_t vtable decouples the wakeword service from any specific backend

ABI evolution (breaking)

• rac_platform_adapter_t.version field, enforced by rac_init
• RAC_PLATFORM_ADAPTER_VERSION = 1 — any adapter with .version == 0 is rejected with RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION (no grace period)
• New error codes: RAC_ERROR_BACKEND_UNAVAILABLE, RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION, RAC_ERROR_JNI_EXCEPTION

SDK consumer coordination

• Swift: CppBridge+PlatformAdapter.swift sets version; CRACommons header fork synced
• Kotlin/JNI: racSetPlatformAdapter sets g_c_adapter.version
• React Native: InitBridge.cpp sets adapter_.version
• Flutter: RacPlatformAdapterStruct has leading uint32 version; dart_bridge_platform.dart populates it
• Web: PlatformAdapter.ts writes 4-byte version as first struct field

Tooling / hygiene

• cmake/Sanitizers.cmake with ASan/UBSan/TSan/MSan options + mutual-exclusion guards
• CMakePresets.json: dev-asan, dev-ubsan, dev-tsan presets
• .clang-tidy tightened (nodiscard, owning-memory, slicing checks active)
• rac_platform_compat.h moved from include/ to src/internal/ (resolves PR feat: support to build on windows #383 deferred TODO; stops leaking dirent/DIR/opendir/... into Windows consumers' global namespace)

Tests

• 4 new test_core tests cover adapter-version rejection paths + hardware capability query
• All existing tests updated to set .version on their adapter
• ctest result: 68/70 passing (the 2 failures are pre-existing rac_rag_backend_thread_safety_test compile errors unrelated to this branch)
• test_core --run-all: 17/17 passing with ASan+UBSan

What's intentionally deferred

• Phase 7 (per-feature JNI file split): scaffold header jni_shared.h is in place; the actual shard extraction is mechanical and best done in per-feature follow-up commits (each reviewable in isolation).
• Phase 8 backend retrofit: IInferenceBackend interface exists; the 5 concrete backends inheriting from it is touch-every-backend boilerplate best bundled with the JNI split.
• CRACommons header fork: Swift maintains its own copy of commons headers; needs a proper sync or an include/ symlink. Tracked.
• Prebuilt xcframeworks (sdk/runanywhere-swift/Binaries/): need rebuild against the new adapter layout before downstream apps can consume.

Full detail in sdk/runanywhere-commons/CPP_LAYER_CLEANUP_STATUS.md.

Test plan

• macOS: cmake --preset dev-asan && cmake --build build/dev-asan — clean ASan+UBSan build
• macOS: runanywhere_commons_jni target builds clean (dev-core preset)
• macOS: ctest in build/dev-asan — 68/70 pass (2 pre-existing failures unrelated)
• Swift: swift build — clean
• Kotlin: JNI target builds on macOS via dev-core
• React Native: npm run typecheck — clean
• Flutter: flutter analyze — 0 errors (pre-existing warnings unrelated)
• Web: my PlatformAdapter.ts changes compile clean
• CI: iOS XCFramework build (needs CI)
• CI: Android AAR full build (needs NDK-enabled CI)
• CI: Linux build (needs CI)
• CI: WebAssembly build (needs emscripten-enabled CI)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Hardware capability detection API (CPU SIMD, GPU/NPU availability, memory) with human-readable report.
  • Platform adapter ABI versioning to prevent incompatible adapter/runtime mismatches.
  • Wake-word provider plugin system for pluggable wake-word backends.

• Improvements

  • Marked many public APIs to require checking return status.
  • New backend/integration error codes including ABI incompatibility and JNI-exception.
  • Added development sanitizer presets and test tooling support.

[greptile-apps]

Too many files changed for review. (104 files found, 100 file limit)

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds sanitizer tooling, a portable attribute header, RAC_NODISCARD annotations across many public APIs, platform-adapter ABI/versioning with runtime validation, a hardware-capabilities API, JNI RAII/exception-safety utilities, a wakeword provider vtable, backend ABI checks, internal header relocation, and related consumer SDK updates and tests.

Changes

Cohort / File(s)	Summary
Build/tooling sdk/runanywhere-commons/.clang-tidy, sdk/runanywhere-commons/CMakeLists.txt, sdk/runanywhere-commons/CMakePresets.json, sdk/runanywhere-commons/cmake/Sanitizers.cmake	Add Sanitizers.cmake and ENABLE_* options, new dev-asan/ubsan/tsan presets, sanitizer enable helper, and tighten clang-tidy checks.
Portable attributes sdk/.../include/rac/core/rac_attrs.h, sdk/.../include/rac/core/rac_types.h, sdk/runanywhere-swift/.../include/rac_attrs.h, sdk/runanywhere-swift/.../include/rac_types.h	Introduce RAC_NODISCARD, RAC_NONNULL, RAC_DEPRECATED, RAC_NORETURN, RAC_ATTR_PRINTF, RAC_PURE, etc., and include them widely.
RAC_NODISCARD sweep (public headers) sdk/runanywhere-commons/include/rac/... (many files across core, features, backends, infrastructure, platform, utils)	Applied RAC_NODISCARD to ~180+ public rac_result_t-returning APIs across lifecycle, services, components, analytics, events, backends, infrastructure, and platform headers.
Hardware capabilities API sdk/runanywhere-commons/include/rac/core/rac_hardware.h, sdk/runanywhere-commons/src/core/rac_hardware.cpp	Add rac_hardware_report_t, RAC_HARDWARE_REPORT_V1, rac_hardware_query_capabilities() and rac_hardware_format_report().
Platform-adapter ABI/versioning sdk/runanywhere-commons/include/rac/core/rac_platform_adapter.h, sdk/runanywhere-commons/src/core/rac_core.cpp, consumer SDK files...	Add uint32_t version as first field, RAC_PLATFORM_ADAPTER_VERSION, runtime validation in rac_init() rejecting version==0 or > supported.
Error codes sdk/runanywhere-commons/include/rac/core/rac_error.h, Swift variant	Add RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION and RAC_ERROR_JNI_EXCEPTION (and Swift also adds BACKEND_UNAVAILABLE).
JNI RAII & refactor sdk/runanywhere-commons/src/jni/jni_scope.h, .../jni/jni_shared.h, .../jni/runanywhere_commons_jni.cpp	New rac::jni::JniScope and Local<T> RAII wrappers; refactor native→Java callbacks to use JniScope, adjust AttachCurrentThread usage, and handle JNI exceptions centrally.
Wakeword provider vtable sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h, .../src/features/wakeword/wakeword_service.cpp, .../src/backends/onnx/wakeword_onnx.cpp	Add rac_wakeword_provider_ops_t, rac_wakeword_provider_set/rac_wakeword_has_provider, make service dispatch to provider, implement ONNX provider adapter.
Backend ABI validation & interface sdk/runanywhere-commons/src/backends/onnx/rac_backend_onnx_register.cpp, sdk/runanywhere-commons/src/backends/backend_interface.h	Parse/check Sherpa-ONNX version at runtime (require major/minor match), add IInferenceBackend abstract interface for backend lifecycle/health.
Internal header relocation sdk/runanywhere-commons/src/internal/rac_platform_compat.h, many source includes	Move platform-compat header into src/internal/ and update includes across sources/tests to internal/rac_platform_compat.h.
Download manager concurrency sdk/runanywhere-commons/src/infrastructure/download/download_manager.cpp	Switch health/pause flags to std::atomic<bool> for concurrent access.
Tests & CMake test helpers sdk/runanywhere-commons/tests/CMakeLists.txt, sdk/runanywhere-commons/tests/test_core.cpp, other tests	Enable sanitizer flags for test targets, include src/ in test includes, add tests for adapter version validation and hardware query.
Consumer SDK changes Flutter, React Native, Swift, Web files (e.g., dart_bridge_platform.dart, ffi_types.dart, InitBridge.cpp, Swift/TS adapters)	Initialize adapter.version in multiple platform bridges and update FFI/types to include the version field.
Docs sdk/runanywhere-commons/CPP_LAYER_CLEANUP_STATUS.md	Add documentation summarizing C++ cleanup, ABI/versioning, JNI sweep, wakeword provider, and sanitizer/tooling steps.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Flutter rearch #251 — overlaps platform-adapter ABI/version and Flutter bridge changes (must coordinate adapter version field and FFI layout).
• fix: clear KV cache and reset batch state between sequential decode c #393 — JNI/refactor changes affecting native→Java callback handling; related to jni_scope RAII work.
• feat(commons): Windows build support + review fixes (rebased from #383) #470 — changes to rac_platform_compat.h and include-paths; related to relocation to src/internal/.

Suggested reviewers

• Siddhesh2377

"🐰
I hop and patch with gentle paws,
Version set and tidy laws,
JNI scopes hold tight,
Sanitizers take flight,
API petals gleam in audit's draws."

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch smonga/cpp-layer-full-cleanup

[coderabbitai]

Actionable comments posted: 14

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

sdk/runanywhere-commons/tests/CMakeLists.txt (1)

275-287: ⚠️ Potential issue | 🟡 Minor

Duplicate FetchContent_Declare for GoogleTest with conflicting versions.

FetchContent_Declare(googletest ...) is called twice:

• Line 193-198: release-1.12.1 for RAG pipeline tests
• Line 277-281: v1.14.0 for benchmark tests

CMake's FetchContent uses the first declaration for a given name and ignores subsequent ones. The benchmark tests will actually use GoogleTest 1.12.1, not 1.14.0 as intended.

Consider consolidating to a single version or using distinct content names if different versions are truly required.

Option 1: Consolidate to single version (recommended)

Move GoogleTest fetch to the top of the file before any test definitions, and use one consistent version (e.g., v1.14.0):

+# =============================================================================
+# GoogleTest (shared by all test suites)
+# =============================================================================
+include(FetchContent)
+FetchContent_Declare(
+    googletest
+    GIT_REPOSITORY https://github.com/google/googletest.git
+    GIT_TAG v1.14.0
+    GIT_SHALLOW TRUE
+)
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+set(INSTALL_GTEST OFF CACHE BOOL "" FORCE)
+FetchContent_MakeAvailable(googletest)
+include(GoogleTest)
+
 # =============================================================================
 # Integration Test Suite for runanywhere-commons
 # =============================================================================

Then remove the duplicate FetchContent_Declare blocks from lines 189-201 and 275-287.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/tests/CMakeLists.txt` around lines 275 - 287, There
are two FetchContent_Declare blocks for the same content name "googletest" with
different GIT_TAGs (release-1.12.1 and v1.14.0), so CMake will honor the first
and ignore the second; to fix, consolidate to a single FetchContent_Declare for
googletest with the desired version (pick one GIT_TAG, e.g., v1.14.0), move that
single declaration (and FetchContent_MakeAvailable) to a common preamble before
test definitions, and remove the duplicate declarations (or if you truly need
two versions, rename the second content identifier to a different name like
"googletest_bench" and update usages accordingly so both can be fetched
separately).

sdk/runanywhere-commons/src/features/wakeword/wakeword_service.cpp (1)

375-384: ⚠️ Potential issue | 🟠 Major

rac_wakeword_unload_all() skips provider-side teardown.

Single-model unload forwards to provider->unload_model(), but this path only clears service->models. That leaves the backend holding live model state while the service thinks everything is gone.

Suggested fix

 RAC_API rac_result_t rac_wakeword_unload_all(rac_handle_t handle) {
     if (!is_valid_handle(handle)) {
         return RAC_ERROR_INVALID_HANDLE;
     }

     auto* service = get_service(handle);
     std::lock_guard<std::mutex> lock(service->mutex);

+    const auto* provider = service->provider;
+    if (provider && provider->unload_model && service->backend_handle) {
+        for (const auto& model : service->models) {
+            (void)provider->unload_model(service->backend_handle,
+                                         model.model_id.c_str(),
+                                         provider->user_data);
+        }
+    }
+
     service->models.clear();
     RAC_LOG_INFO("WakeWord", "Unloaded all models");

     return RAC_SUCCESS;
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/features/wakeword/wakeword_service.cpp` around
lines 375 - 384, rac_wakeword_unload_all currently only clears service->models
and does not call the provider teardown, leaving backend models loaded; update
rac_wakeword_unload_all to iterate the existing entries in service->models (use
the same model representation used by single-model unload), call the provider's
unload_model(...) for each model (as done by the single-model path),
handle/provider-return errors or exceptions appropriately (log per-model
failures with RAC_LOG_*), and only after successful/unattempted unloads clear
service->models and log "Unloaded all models"; use get_service(handle) and
service->mutex for thread-safety as currently implemented.

🧹 Nitpick comments (9)

sdk/runanywhere-commons/src/infrastructure/download/download_manager.cpp (1)

64-68: Update the concurrency comment to reference the correct API name.

The comment cites rac_download_manager_start_download, but this file exposes rac_download_manager_start, which makes the rationale look stale.

✏️ Suggested comment-only cleanup

-    // path (e.g. rac_download_manager_start_download consults is_paused
+    // path (e.g. rac_download_manager_start consults is_paused

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/infrastructure/download/download_manager.cpp`
around lines 64 - 68, The concurrency comment references a stale API name;
update the comment to mention the actual public entry point
rac_download_manager_start (instead of rac_download_manager_start_download) and
keep the rest of the rationale intact: explain that flags like is_paused are
read without holding the mutex on the hot path, may be written by
pause/resume/set-healthy entry points on any thread, and therefore MUST be
std::atomic to avoid torn reads and TSan data races.

sdk/runanywhere-commons/src/features/rag/CMakeLists.txt (1)

88-92: Minor documentation inconsistency in comment.

The comment mentions onnx_embedding_provider.cpp as a user of internal/rac_platform_compat.h, but per lines 68-71, that file is compiled into rac_backend_onnx, not this rac_backend_rag target. Consider updating the comment to reference the actual RAG sources that need the internal include path, or simply state it's for general internal header access.

The CMake change itself is correct — PRIVATE visibility ensures internal headers don't leak to consumers.

📝 Suggested comment fix

-# Internal headers (e.g. internal/rac_platform_compat.h used by
-# onnx_embedding_provider.cpp). PRIVATE - never leaks to consumers.
+# Internal headers (e.g. internal/rac_platform_compat.h).
+# PRIVATE - never leaks to consumers.
 target_include_directories(rac_backend_rag PRIVATE
     ${CMAKE_SOURCE_DIR}/src
 )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/features/rag/CMakeLists.txt` around lines 88 -
92, The comment above the target_include_directories(rac_backend_rag PRIVATE
...) incorrectly cites onnx_embedding_provider.cpp as a consumer of
internal/rac_platform_compat.h (that file is compiled into rac_backend_onnx);
update the comment to either reference the actual RAG sources that require the
internal headers for rac_backend_rag or make it a generic note such as "Internal
headers (e.g. internal/*.h) used by RAG sources; PRIVATE - never leaks to
consumers" so the comment matches the target_include_directories and the
rac_backend_rag target.

sdk/runanywhere-commons/src/backends/onnx/rac_backend_onnx_register.cpp (2)

582-583: Consider extracting expected version as named constants at file scope.

The expected major/minor are constexpr within the block scope, which is fine. However, for easier maintenance when Sherpa-ONNX is upgraded, consider defining these at namespace scope (alongside LOG_CAT) with a comment referencing the VERSIONS file:

📝 Suggested refactor

 namespace {
 
 const char* LOG_CAT = "ONNX";
+
+// Sherpa-ONNX ABI version this code was compiled against.
+// Update when upgrading sherpa-onnx in VERSIONS file.
+constexpr int SHERPA_ONNX_EXPECTED_MAJOR = 1;
+constexpr int SHERPA_ONNX_EXPECTED_MINOR = 12;

Then reference these in the version check block.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/backends/onnx/rac_backend_onnx_register.cpp`
around lines 582 - 583, The expected_major and expected_minor constants are
defined inside a local scope; move them to file/namespace scope (near LOG_CAT)
as named constexpr constants (e.g., kExpectedSherpaOnnxMajor,
kExpectedSherpaOnnxMinor) with a comment referencing the VERSIONS file so
upgrades are obvious, then update the version check in
rac_backend_onnx_register.cpp to use these file-scope constants instead of the
local expected_major/expected_minor variables.

---

684-684: Consider checking return value of rac_backend_onnx_embeddings_register().

The call to rac_backend_onnx_embeddings_register() ignores its return value. Given this PR adds RAC_NODISCARD to that function, the ONNX backend should either check the result or explicitly cast to void if embeddings registration failure is acceptable.

📝 Suggested fix

     // Register ONNX embeddings provider (for RAG pipeline).
-    rac_backend_onnx_embeddings_register();
+    // Embeddings registration failure is non-fatal; RAG pipeline may still
+    // work with alternative embedding providers.
+    (void)rac_backend_onnx_embeddings_register();

Or if embeddings are required:

-    rac_backend_onnx_embeddings_register();
+    result = rac_backend_onnx_embeddings_register();
+    if (result != RAC_SUCCESS && result != RAC_ERROR_MODULE_ALREADY_REGISTERED) {
+        RAC_LOG_WARNING(LOG_CAT, "ONNX embeddings registration failed: %d", result);
+        // Continue - embeddings are optional for core STT/TTS/VAD
+    }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/backends/onnx/rac_backend_onnx_register.cpp` at
line 684, The call to rac_backend_onnx_embeddings_register() currently ignores
its return value and must respect its RAC_NODISCARD contract; update the caller
(where rac_backend_onnx_embeddings_register() is invoked) to either check its
return value and handle failure (e.g., log the error and propagate/return a
non-success status from rac_backend_onnx_register() or the surrounding init
function) or, if embedding registration failures are acceptable, explicitly cast
the call to void ((void)rac_backend_onnx_embeddings_register()) to document
intentional ignoring; reference rac_backend_onnx_embeddings_register() and the
surrounding registration/init function when applying the change.

sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_model_assignment.h (1)

76-77: Consider adding RAC_NODISCARD to rac_model_assignment_set_callbacks for consistency.

This function returns rac_result_t but lacks RAC_NODISCARD, unlike the other functions in this header. If the PR goal is comprehensive RAC_NODISCARD coverage for all rac_result_t-returning public APIs, this appears to be an oversight.

Proposed fix

-RAC_API rac_result_t
+RAC_API RAC_NODISCARD rac_result_t
 rac_model_assignment_set_callbacks(const rac_assignment_callbacks_t* callbacks);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_model_assignment.h`
around lines 76 - 77, Add the RAC_NODISCARD attribute to the
rac_model_assignment_set_callbacks declaration so its rac_result_t return is
annotated consistently with the other public APIs; edit the declaration of
rac_model_assignment_set_callbacks to match the pattern used elsewhere (place
RAC_NODISCARD in the same position relative to RAC_API/rac_result_t as other
functions) and run a quick build to ensure the macro placement compiles cleanly.

sdk/runanywhere-commons/include/rac/features/llm/rac_llm_structured_output.h (1)

126-128: Consider adding RAC_NODISCARD to rac_structured_output_validate for consistency.

This function returns rac_result_t but lacks RAC_NODISCARD, unlike the other rac_result_t-returning functions in this header. If the PR goal is comprehensive RAC_NODISCARD coverage, this appears to be an oversight.

Proposed fix

-RAC_API rac_result_t
+RAC_API RAC_NODISCARD rac_result_t
 rac_structured_output_validate(const char* text, const rac_structured_output_config_t* config,
                                rac_structured_output_validation_t* out_validation);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/include/rac/features/llm/rac_llm_structured_output.h`
around lines 126 - 128, The declaration for rac_structured_output_validate is
missing the RAC_NODISCARD attribute like other rac_result_t-returning functions;
update its declaration to prepend RAC_NODISCARD so callers are warned if the
return value is ignored (modify the function prototype for
rac_structured_output_validate in rac_llm_structured_output.h to include
RAC_NODISCARD and keep the existing signature and parameter names).

sdk/runanywhere-commons/src/jni/jni_shared.h (1)

55-69: Consider using the RAC logger API for the non-Android fallback.

The non-Android fallback macros (lines 65-68) use raw fprintf. Per coding guidelines, logging should use the RAC logger API (RAC_LOG_INFO, etc.). While the Android path uses __android_log_print for logcat integration, the desktop fallback could route through the RAC logger for consistency.

That said, since this is internal JNI scaffolding and the macros already exist in runanywhere_commons_jni.cpp, maintaining consistency with the existing codebase is reasonable.

Optional: Route non-Android logging through RAC logger

 `#else`
 `#include` <cstdio>
-#define LOGi(...) do { std::fprintf(stdout, "[INFO]  " __VA_ARGS__); std::fputc('\n', stdout); } while (0)
-#define LOGd(...) do { std::fprintf(stdout, "[DEBUG] " __VA_ARGS__); std::fputc('\n', stdout); } while (0)
-#define LOGw(...) do { std::fprintf(stderr, "[WARN]  " __VA_ARGS__); std::fputc('\n', stderr); } while (0)
-#define LOGe(...) do { std::fprintf(stderr, "[ERROR] " __VA_ARGS__); std::fputc('\n', stderr); } while (0)
+#define LOGi(...) RAC_LOG_INFO(__VA_ARGS__)
+#define LOGd(...) RAC_LOG_DEBUG(__VA_ARGS__)
+#define LOGw(...) RAC_LOG_WARNING(__VA_ARGS__)
+#define LOGe(...) RAC_LOG_ERROR(__VA_ARGS__)
 `#endif`

As per coding guidelines: "Logging must use the RAC logger API (RAC_LOG_INFO, RAC_LOG_ERROR, RAC_LOG_WARNING, RAC_LOG_DEBUG) via rac/core/rac_logger.h"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/jni/jni_shared.h` around lines 55 - 69, Replace
the non-Android logging macros in jni_shared.h (LOGi, LOGd, LOGw, LOGe) to call
the RAC logger API (RAC_LOG_INFO, RAC_LOG_DEBUG, RAC_LOG_WARNING, RAC_LOG_ERROR)
instead of using fprintf; add an `#include` for rac/core/rac_logger.h inside the
non-Android branch, keep the Android __android_log_print path unchanged, and
preserve the variadic macro usage so existing calls to LOGi/LOGd/LOGw/LOGe
continue to work with the RAC logger.

sdk/runanywhere-commons/tests/test_core.cpp (1)

131-147: Add the same post-failure init-state assertion here for symmetry.

test_adapter_version_future_rejected should also assert rac_is_initialized() == RAC_FALSE, matching the zero-version test and guarding against partial-init regressions.

💡 Suggested test hardening

 static TestResult test_adapter_version_future_rejected() {
@@
     rac_result_t rc = rac_init(&config);
     ASSERT_EQ(rc, RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION,
               "rac_init with future version should return "
               "RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION");
+    ASSERT_EQ(rac_is_initialized(), RAC_FALSE,
+              "init failure must not leave SDK in initialized state");
     return TEST_PASS();
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/tests/test_core.cpp` around lines 131 - 147, Add a
post-failure initialization-state assertion to
test_adapter_version_future_rejected: after the rac_init(&config) ASSERT_EQ(...)
check, add an assertion that rac_is_initialized() == RAC_FALSE to mirror the
zero-version test and ensure no partial init occurred; locate this in the
test_adapter_version_future_rejected function alongside the existing
rac_init/rac_result_t rc check and use the same ASSERT_EQ style and messaging as
the other test for consistency.

sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h (1)

423-423: Missing RAC_NODISCARD for consistency.

rac_wakeword_provider_set returns rac_result_t but lacks RAC_NODISCARD, unlike all other rac_result_t-returning functions in this file. Even though the doc says it "always returns RAC_SUCCESS", future versions might add validation that could fail.

♻️ Suggested fix

-RAC_API rac_result_t rac_wakeword_provider_set(const rac_wakeword_provider_ops_t* ops);
+RAC_API RAC_NODISCARD rac_result_t rac_wakeword_provider_set(const rac_wakeword_provider_ops_t* ops);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h`
at line 423, Add the missing RAC_NODISCARD attribute to the declaration of
rac_wakeword_provider_set to match other rac_result_t-returning functions and
ensure callers don't ignore the return value; locate the function declaration
for rac_wakeword_provider_set (the prototype returning rac_result_t) in
rac_wakeword_service.h and prepend or insert RAC_NODISCARD so the signature
mirrors the other annotated functions in the file.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@sdk/runanywhere-commons/cmake/Sanitizers.cmake`:
- Around line 130-140: The ENABLE_MSAN block in Sanitizers.cmake currently only
checks CMAKE_CXX_COMPILER_ID for Clang but must also verify the target platform;
update the ENABLE_MSAN handling to reject non-supported OSes by checking
CMAKE_SYSTEM_NAME (or equivalent) and erroring out unless it matches Linux (or
allowed BSDs like FreeBSD/NetBSD), so you fail at configure time instead of
applying MSan flags on macOS; keep the existing Clang check and the list(APPEND
_san_cflags/_san_lflags) behavior but add a platform guard that calls
message(FATAL_ERROR "MemorySanitizer requires Linux (or FreeBSD/NetBSD).") when
the OS is unsupported.

In `@sdk/runanywhere-commons/CMakePresets.json`:
- Around line 84-87: Add explicit CC/CXX compiler environment variables to the
dev presets so builds are pinned to gcc/g++; for the existing presets dev-asan,
dev-ubsan, and dev-tsan, update their "environment" objects to include "CC":
"gcc" and "CXX": "g++"; for dev-no-backends, create an "environment" section and
add the same "CC" and "CXX" entries so all four dev presets consistently use
gcc/g++.

In `@sdk/runanywhere-commons/CPP_LAYER_CLEANUP_STATUS.md`:
- Line 3: Update the hard-coded commit count in the document header: replace the
exact line containing "Branch: `smonga/cpp-layer-full-cleanup` (12 commits,
branched from `main @ bc7db9bd0`)" so it no longer hard-codes "12 commits" —
either remove the numeric count entirely or change it to a non-stale form like
"N+ commits" (or "multiple commits") so the header stays accurate as the table
below changes.

In `@sdk/runanywhere-commons/include/rac/core/rac_error.h`:
- Around line 370-380: Add mappings for the two new error macros inside the
rac_error_message() switch so callers get descriptive messages: locate
rac_error_message (in sdk/runanywhere-commons/src/core/rac_error.cpp) and add
case RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION to return a string describing the
backend runtime ABI/version mismatch and case RAC_ERROR_JNI_EXCEPTION to return
a string describing a pending Java exception from a JNI callback; ensure the
returned messages match the comments in rac_error.h and follow the existing
formatting/style of other case branches.

In `@sdk/runanywhere-commons/include/rac/core/rac_platform_adapter.h`:
- Around line 95-98: The comment references a nonexistent macro
`RAC_PLATFORM_ADAPTER_VERSION_LATEST`; update the comment to match the actual
symbol names used in this header by either changing the text to only mention
`RAC_PLATFORM_ADAPTER_VERSION` (and explain bumping that macro when callbacks
are appended) or add/introduce a proper `RAC_PLATFORM_ADAPTER_VERSION_LATEST`
definition if intended; locate the comment near `RAC_PLATFORM_ADAPTER_VERSION`
and make the wording consistent with the defined macro so consumers can rely on
the documented symbol.

In `@sdk/runanywhere-commons/src/backends/onnx/wakeword_onnx.cpp`:
- Around line 1038-1057: The provider creation path in
onnx_wakeword_provider_create currently only populates
rac_wakeword_onnx_config_t and calls rac_wakeword_onnx_create, but never
initializes the shared melspec/embedding sessions so detection can silently be
disabled; update onnx_wakeword_provider_create to call
rac_wakeword_onnx_init_shared_models (or the appropriate shared-model init
function) before rac_wakeword_onnx_create and propagate any error (return
non-success) if shared-model initialization fails so the provider fails fast
when sessions are unavailable, or alternatively check post-create that the
shared sessions exist and return an error instead of silently succeeding.
- Around line 1127-1134: The code currently ignores the return value of
rac_wakeword_provider_set(&g_onnx_wakeword_provider_ops) then unconditionally
sets g_wakeword_onnx_registered = true and logs success; change this so you
check the provider_set return (and similarly the provider_clear return in the
corresponding clear block), only set g_wakeword_onnx_registered = true after a
successful rac_wakeword_provider_set, and on failure log a descriptive error via
RAC_LOG_ERROR(LOG_TAG, ...) including the return code and return an error status
(do not flip the registered flag). Also mirror this behavior for the
provider_clear path: call rac_wakeword_provider_clear, check its return, only
clear g_wakeword_onnx_registered on success, and log/return on failure.

In `@sdk/runanywhere-commons/src/core/rac_core.cpp`:
- Around line 113-117: The error detail string passed to rac_error_set_details
contains an unexpanded template token "{0}-init"; update the message in
rac_error_set_details (in rac_core.cpp) to remove the placeholder and use a
concrete reference such as "the adapter initializer (e.g., rac_init)" or "your
adapter initialization function" so callers are not confused; keep the rest of
the text intact and ensure the message references rac_init and/or the platform
adapter .version assignment explicitly.

In `@sdk/runanywhere-commons/src/core/rac_hardware.cpp`:
- Around line 116-125: kHasANE is currently set to true for all Apple targets;
restrict it to real Apple Silicon devices only and exclude simulator builds by
changing the preprocessor condition around kHasANE (and including
TargetConditionals.h if needed). Replace the current defined(__APPLE__) branch
with a condition like defined(__APPLE__) && (defined(__aarch64__) ||
defined(__arm64__)) && !TARGET_OS_SIMULATOR (or
!defined(__ENVIRONMENT_IPHONE_SIMULATOR__) / using TARGET_OS_SIMULATOR from
TargetConditionals.h) so kHasANE is RAC_TRUE only on actual Apple Silicon
devices and RAC_FALSE elsewhere.

In `@sdk/runanywhere-commons/src/features/wakeword/wakeword_service.cpp`:
- Around line 39-41: The service currently uses the global g_provider at init
but re-reads it for later ops, which can misroute old backend_handle through a
new vtable; modify WakewordService to capture and store the provider pointer
(const rac_wakeword_provider_ops_t*) used when creating backend_handle and use
that stored ops table for all lifecycle calls (destroy, process, unload,
set_threshold) instead of reading g_provider each time; alternatively, implement
a guard in rac_wakeword_provider_set() to reject provider changes while
WakewordService instances exist—update methods referencing g_provider to use the
instance field (and ensure constructor stores the provider) so cleanup always
uses the correct ops.

In `@sdk/runanywhere-commons/src/jni/jni_scope.h`:
- Line 56: The backend JNI targets rac_backend_onnx_jni,
rac_backend_whispercpp_jni, rac_backend_llamacpp_jni, and rac_backend_rag_jni
are missing ${JNI_INCLUDE_DIRS} in their target_include_directories calls;
update each CMakeLists.txt for these targets to add ${JNI_INCLUDE_DIRS} (as
SYSTEM or PUBLIC/PRIVATE as appropriate) to the target_include_directories()
invocation so that <jni.h> is available for Android builds (ensure you reference
the exact target names above when making the change).

In `@sdk/runanywhere-commons/src/jni/runanywhere_commons_jni.cpp`:
- Around line 2859-2864: In jni_device_get_info handling, guard against
GetStringUTFChars returning null: after obtaining jstring jResult from
cb_result.get() and before calling env->GetStringUTFChars (or using json_str),
check that jResult is non-null and that the returned const char* from
GetStringUTFChars is not null; if either is null, call RAC_JNI_TRY_VOID(s) or
return early (releasing resources appropriately) instead of proceeding to log or
json::parse; update the code paths around rac::jni::JniScope s(...), cb_result,
g_device_jni_state.get_device_info_method, and any subsequent json::parse and
env->ReleaseStringUTFChars calls to only run when the UTF chars pointer is valid
so we avoid UB on OOM/JNI failures.
- Around line 807-830: The code currently ignores Java exceptions cleared by
rac::jni::JniScope (js.failed() / hadException) and continues generation
returning RAC_TRUE; update the token-callback handling in
racLlmComponentGenerateStreamWithCallback's loop so that if js.failed() (i.e.,
hadException is true) after calling ctx->onTokenMethod on ctx->callback (both
byte and string paths) you mark the context as failed and return RAC_FALSE
immediately; ensure you reference JniScope js, ctx->onTokenExpectsBytes,
ctx->callback and ctx->onTokenMethod and replace the current unconditional
RAC_TRUE return with a failure path that stops the stream.

In `@sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_error.h`:
- Around line 368-377: The switch in rac_error_message() is missing case
mappings for RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION and RAC_ERROR_JNI_EXCEPTION,
so callers get "Unknown error code"; add two cases in the BACKEND ERRORS section
of rac_error.cpp within rac_error_message(): one for
RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION that returns "Backend ABI incompatible
with SDK version" and one for RAC_ERROR_JNI_EXCEPTION that returns "JNI
exception occurred".

---

Outside diff comments:
In `@sdk/runanywhere-commons/src/features/wakeword/wakeword_service.cpp`:
- Around line 375-384: rac_wakeword_unload_all currently only clears
service->models and does not call the provider teardown, leaving backend models
loaded; update rac_wakeword_unload_all to iterate the existing entries in
service->models (use the same model representation used by single-model unload),
call the provider's unload_model(...) for each model (as done by the
single-model path), handle/provider-return errors or exceptions appropriately
(log per-model failures with RAC_LOG_*), and only after successful/unattempted
unloads clear service->models and log "Unloaded all models"; use
get_service(handle) and service->mutex for thread-safety as currently
implemented.

In `@sdk/runanywhere-commons/tests/CMakeLists.txt`:
- Around line 275-287: There are two FetchContent_Declare blocks for the same
content name "googletest" with different GIT_TAGs (release-1.12.1 and v1.14.0),
so CMake will honor the first and ignore the second; to fix, consolidate to a
single FetchContent_Declare for googletest with the desired version (pick one
GIT_TAG, e.g., v1.14.0), move that single declaration (and
FetchContent_MakeAvailable) to a common preamble before test definitions, and
remove the duplicate declarations (or if you truly need two versions, rename the
second content identifier to a different name like "googletest_bench" and update
usages accordingly so both can be fetched separately).

---

Nitpick comments:
In
`@sdk/runanywhere-commons/include/rac/features/llm/rac_llm_structured_output.h`:
- Around line 126-128: The declaration for rac_structured_output_validate is
missing the RAC_NODISCARD attribute like other rac_result_t-returning functions;
update its declaration to prepend RAC_NODISCARD so callers are warned if the
return value is ignored (modify the function prototype for
rac_structured_output_validate in rac_llm_structured_output.h to include
RAC_NODISCARD and keep the existing signature and parameter names).

In
`@sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h`:
- Line 423: Add the missing RAC_NODISCARD attribute to the declaration of
rac_wakeword_provider_set to match other rac_result_t-returning functions and
ensure callers don't ignore the return value; locate the function declaration
for rac_wakeword_provider_set (the prototype returning rac_result_t) in
rac_wakeword_service.h and prepend or insert RAC_NODISCARD so the signature
mirrors the other annotated functions in the file.

In
`@sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_model_assignment.h`:
- Around line 76-77: Add the RAC_NODISCARD attribute to the
rac_model_assignment_set_callbacks declaration so its rac_result_t return is
annotated consistently with the other public APIs; edit the declaration of
rac_model_assignment_set_callbacks to match the pattern used elsewhere (place
RAC_NODISCARD in the same position relative to RAC_API/rac_result_t as other
functions) and run a quick build to ensure the macro placement compiles cleanly.

In `@sdk/runanywhere-commons/src/backends/onnx/rac_backend_onnx_register.cpp`:
- Around line 582-583: The expected_major and expected_minor constants are
defined inside a local scope; move them to file/namespace scope (near LOG_CAT)
as named constexpr constants (e.g., kExpectedSherpaOnnxMajor,
kExpectedSherpaOnnxMinor) with a comment referencing the VERSIONS file so
upgrades are obvious, then update the version check in
rac_backend_onnx_register.cpp to use these file-scope constants instead of the
local expected_major/expected_minor variables.
- Line 684: The call to rac_backend_onnx_embeddings_register() currently ignores
its return value and must respect its RAC_NODISCARD contract; update the caller
(where rac_backend_onnx_embeddings_register() is invoked) to either check its
return value and handle failure (e.g., log the error and propagate/return a
non-success status from rac_backend_onnx_register() or the surrounding init
function) or, if embedding registration failures are acceptable, explicitly cast
the call to void ((void)rac_backend_onnx_embeddings_register()) to document
intentional ignoring; reference rac_backend_onnx_embeddings_register() and the
surrounding registration/init function when applying the change.

In `@sdk/runanywhere-commons/src/features/rag/CMakeLists.txt`:
- Around line 88-92: The comment above the
target_include_directories(rac_backend_rag PRIVATE ...) incorrectly cites
onnx_embedding_provider.cpp as a consumer of internal/rac_platform_compat.h
(that file is compiled into rac_backend_onnx); update the comment to either
reference the actual RAG sources that require the internal headers for
rac_backend_rag or make it a generic note such as "Internal headers (e.g.
internal/*.h) used by RAG sources; PRIVATE - never leaks to consumers" so the
comment matches the target_include_directories and the rac_backend_rag target.

In `@sdk/runanywhere-commons/src/infrastructure/download/download_manager.cpp`:
- Around line 64-68: The concurrency comment references a stale API name; update
the comment to mention the actual public entry point rac_download_manager_start
(instead of rac_download_manager_start_download) and keep the rest of the
rationale intact: explain that flags like is_paused are read without holding the
mutex on the hot path, may be written by pause/resume/set-healthy entry points
on any thread, and therefore MUST be std::atomic to avoid torn reads and TSan
data races.

In `@sdk/runanywhere-commons/src/jni/jni_shared.h`:
- Around line 55-69: Replace the non-Android logging macros in jni_shared.h
(LOGi, LOGd, LOGw, LOGe) to call the RAC logger API (RAC_LOG_INFO,
RAC_LOG_DEBUG, RAC_LOG_WARNING, RAC_LOG_ERROR) instead of using fprintf; add an
`#include` for rac/core/rac_logger.h inside the non-Android branch, keep the
Android __android_log_print path unchanged, and preserve the variadic macro
usage so existing calls to LOGi/LOGd/LOGw/LOGe continue to work with the RAC
logger.

In `@sdk/runanywhere-commons/tests/test_core.cpp`:
- Around line 131-147: Add a post-failure initialization-state assertion to
test_adapter_version_future_rejected: after the rac_init(&config) ASSERT_EQ(...)
check, add an assertion that rac_is_initialized() == RAC_FALSE to mirror the
zero-version test and ensure no partial init occurred; locate this in the
test_adapter_version_future_rejected function alongside the existing
rac_init/rac_result_t rc check and use the same ASSERT_EQ style and messaging as
the other test for consistency.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e04b9299-f308-4c83-af16-d156753bdeaf

📥 Commits

Reviewing files that changed from the base of the PR and between bc7db9b and 459c324.

📒 Files selected for processing (104)

• sdk/runanywhere-commons/.clang-tidy
• sdk/runanywhere-commons/CMakeLists.txt
• sdk/runanywhere-commons/CMakePresets.json
• sdk/runanywhere-commons/CPP_LAYER_CLEANUP_STATUS.md
• sdk/runanywhere-commons/cmake/Sanitizers.cmake
• sdk/runanywhere-commons/include/rac/backends/rac_embeddings_onnx.h
• sdk/runanywhere-commons/include/rac/backends/rac_stt_whisperkit_coreml.h
• sdk/runanywhere-commons/include/rac/core/capabilities/rac_lifecycle.h
• sdk/runanywhere-commons/include/rac/core/rac_analytics_events.h
• sdk/runanywhere-commons/include/rac/core/rac_attrs.h
• sdk/runanywhere-commons/include/rac/core/rac_audio_utils.h
• sdk/runanywhere-commons/include/rac/core/rac_benchmark_log.h
• sdk/runanywhere-commons/include/rac/core/rac_benchmark_stats.h
• sdk/runanywhere-commons/include/rac/core/rac_core.h
• sdk/runanywhere-commons/include/rac/core/rac_error.h
• sdk/runanywhere-commons/include/rac/core/rac_events.h
• sdk/runanywhere-commons/include/rac/core/rac_hardware.h
• sdk/runanywhere-commons/include/rac/core/rac_logger.h
• sdk/runanywhere-commons/include/rac/core/rac_platform_adapter.h
• sdk/runanywhere-commons/include/rac/core/rac_sdk_state.h
• sdk/runanywhere-commons/include/rac/core/rac_structured_error.h
• sdk/runanywhere-commons/include/rac/core/rac_types.h
• sdk/runanywhere-commons/include/rac/features/diffusion/rac_diffusion_component.h
• sdk/runanywhere-commons/include/rac/features/diffusion/rac_diffusion_model_registry.h
• sdk/runanywhere-commons/include/rac/features/diffusion/rac_diffusion_service.h
• sdk/runanywhere-commons/include/rac/features/diffusion/rac_diffusion_tokenizer.h
• sdk/runanywhere-commons/include/rac/features/embeddings/rac_embeddings_component.h
• sdk/runanywhere-commons/include/rac/features/embeddings/rac_embeddings_service.h
• sdk/runanywhere-commons/include/rac/features/llm/rac_llm_analytics.h
• sdk/runanywhere-commons/include/rac/features/llm/rac_llm_component.h
• sdk/runanywhere-commons/include/rac/features/llm/rac_llm_events.h
• sdk/runanywhere-commons/include/rac/features/llm/rac_llm_metrics.h
• sdk/runanywhere-commons/include/rac/features/llm/rac_llm_service.h
• sdk/runanywhere-commons/include/rac/features/llm/rac_llm_structured_output.h
• sdk/runanywhere-commons/include/rac/features/llm/rac_tool_calling.h
• sdk/runanywhere-commons/include/rac/features/platform/rac_diffusion_platform.h
• sdk/runanywhere-commons/include/rac/features/platform/rac_llm_platform.h
• sdk/runanywhere-commons/include/rac/features/platform/rac_tts_platform.h
• sdk/runanywhere-commons/include/rac/features/rag/rac_rag.h
• sdk/runanywhere-commons/include/rac/features/rag/rac_rag_pipeline.h
• sdk/runanywhere-commons/include/rac/features/stt/rac_stt_analytics.h
• sdk/runanywhere-commons/include/rac/features/stt/rac_stt_component.h
• sdk/runanywhere-commons/include/rac/features/stt/rac_stt_events.h
• sdk/runanywhere-commons/include/rac/features/stt/rac_stt_service.h
• sdk/runanywhere-commons/include/rac/features/tts/rac_tts_analytics.h
• sdk/runanywhere-commons/include/rac/features/tts/rac_tts_component.h
• sdk/runanywhere-commons/include/rac/features/tts/rac_tts_events.h
• sdk/runanywhere-commons/include/rac/features/tts/rac_tts_service.h
• sdk/runanywhere-commons/include/rac/features/vad/rac_vad_analytics.h
• sdk/runanywhere-commons/include/rac/features/vad/rac_vad_component.h
• sdk/runanywhere-commons/include/rac/features/vad/rac_vad_energy.h
• sdk/runanywhere-commons/include/rac/features/vad/rac_vad_events.h
• sdk/runanywhere-commons/include/rac/features/vad/rac_vad_service.h
• sdk/runanywhere-commons/include/rac/features/vlm/rac_vlm_component.h
• sdk/runanywhere-commons/include/rac/features/vlm/rac_vlm_service.h
• sdk/runanywhere-commons/include/rac/features/voice_agent/rac_voice_agent.h
• sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h
• sdk/runanywhere-commons/include/rac/infrastructure/device/rac_device_manager.h
• sdk/runanywhere-commons/include/rac/infrastructure/download/rac_download.h
• sdk/runanywhere-commons/include/rac/infrastructure/download/rac_download_orchestrator.h
• sdk/runanywhere-commons/include/rac/infrastructure/events/rac_events.h
• sdk/runanywhere-commons/include/rac/infrastructure/extraction/rac_extraction.h
• sdk/runanywhere-commons/include/rac/infrastructure/file_management/rac_file_manager.h
• sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_lora_registry.h
• sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_model_assignment.h
• sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_model_compatibility.h
• sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_model_paths.h
• sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_model_registry.h
• sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_model_strategy.h
• sdk/runanywhere-commons/include/rac/infrastructure/model_management/rac_model_types.h
• sdk/runanywhere-commons/include/rac/infrastructure/storage/rac_storage_analyzer.h
• sdk/runanywhere-commons/include/rac/infrastructure/telemetry/rac_telemetry_manager.h
• sdk/runanywhere-commons/include/rac/server/rac_server.h
• sdk/runanywhere-commons/include/rac/utils/rac_image_utils.h
• sdk/runanywhere-commons/src/backends/backend_interface.h
• sdk/runanywhere-commons/src/backends/onnx/CMakeLists.txt
• sdk/runanywhere-commons/src/backends/onnx/onnx_backend.cpp
• sdk/runanywhere-commons/src/backends/onnx/rac_backend_onnx_register.cpp
• sdk/runanywhere-commons/src/backends/onnx/wakeword_onnx.cpp
• sdk/runanywhere-commons/src/core/rac_core.cpp
• sdk/runanywhere-commons/src/core/rac_hardware.cpp
• sdk/runanywhere-commons/src/features/rag/CMakeLists.txt
• sdk/runanywhere-commons/src/features/rag/onnx_embedding_provider.cpp
• sdk/runanywhere-commons/src/features/vlm/vlm_component.cpp
• sdk/runanywhere-commons/src/features/wakeword/wakeword_service.cpp
• sdk/runanywhere-commons/src/infrastructure/download/download_manager.cpp
• sdk/runanywhere-commons/src/infrastructure/download/download_orchestrator.cpp
• sdk/runanywhere-commons/src/infrastructure/extraction/rac_extraction.cpp
• sdk/runanywhere-commons/src/internal/rac_platform_compat.h
• sdk/runanywhere-commons/src/jni/jni_scope.h
• sdk/runanywhere-commons/src/jni/jni_shared.h
• sdk/runanywhere-commons/src/jni/runanywhere_commons_jni.cpp
• sdk/runanywhere-commons/tests/CMakeLists.txt
• sdk/runanywhere-commons/tests/test_config.h
• sdk/runanywhere-commons/tests/test_core.cpp
• sdk/runanywhere-commons/tests/test_download_orchestrator.cpp
• sdk/runanywhere-commons/tests/test_extraction.cpp
• sdk/runanywhere-flutter/packages/runanywhere/lib/native/dart_bridge_platform.dart
• sdk/runanywhere-flutter/packages/runanywhere/lib/native/ffi_types.dart
• sdk/runanywhere-react-native/packages/core/cpp/bridges/InitBridge.cpp
• sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_error.h
• sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_platform_adapter.h
• sdk/runanywhere-swift/Sources/RunAnywhere/Foundation/Bridge/Extensions/CppBridge+PlatformAdapter.swift
• sdk/runanywhere-web/packages/llamacpp/src/Foundation/PlatformAdapter.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

Does LLVM/Clang MemorySanitizer support macOS, or is it limited to Linux targets?

💡 Result:

LLVM/Clang MemorySanitizer does not support macOS. It is limited to Linux, FreeBSD, and NetBSD targets.

Citations:

• 1: https://clang.llvm.org/docs/MemorySanitizer.html
• 2: https://prereleases.llvm.org/10.0.0/rc4/tools/clang/docs/MemorySanitizer.html
• 3: https://stackoverflow.com/questions/72565582/installing-memory-sanitizer-and-leak-sanitizer-into-clang-compiler
• 4: https://releases.llvm.org/20.1.0/tools/clang/docs/MemorySanitizer.html

---

Add platform check to reject ENABLE_MSAN on non-Linux systems.

The implementation checks only for Clang but the documented constraint is "MSan requires Clang + Linux". On macOS with AppleClang, the MSan flags will be applied and fail during the build instead of at configure time. LLVM/Clang MemorySanitizer is limited to Linux (and FreeBSD/NetBSD), not supported on macOS.

Suggested fix

     if(ENABLE_MSAN)
         # MSan requires Clang + Linux and all linked libs to be MSan-built.
+        if(NOT CMAKE_SYSTEM_NAME STREQUAL "Linux")
+            message(FATAL_ERROR "MemorySanitizer is supported only on Linux.")
+        endif()
         if(NOT CMAKE_CXX_COMPILER_ID MATCHES "Clang")
             message(FATAL_ERROR "MemorySanitizer requires Clang.")
         endif()

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if(ENABLE_MSAN)
	# MSan requires Clang + Linux and all linked libs to be MSan-built.
	if(NOT CMAKE_CXX_COMPILER_ID MATCHES "Clang")
	message(FATAL_ERROR "MemorySanitizer requires Clang.")
	endif()
	list(APPEND _san_cflags
	-fsanitize=memory
	-fsanitize-memory-track-origins=2
	-fno-omit-frame-pointer -g)
	list(APPEND _san_lflags -fsanitize=memory)
	message(STATUS "[${target}] MemorySanitizer: ENABLED")
	if(ENABLE_MSAN)
	# MSan requires Clang + Linux and all linked libs to be MSan-built.
	if(NOT CMAKE_SYSTEM_NAME STREQUAL "Linux")
	message(FATAL_ERROR "MemorySanitizer is supported only on Linux.")
	endif()
	if(NOT CMAKE_CXX_COMPILER_ID MATCHES "Clang")
	message(FATAL_ERROR "MemorySanitizer requires Clang.")
	endif()
	list(APPEND _san_cflags
	-fsanitize=memory
	-fsanitize-memory-track-origins=2
	-fno-omit-frame-pointer -g)
	list(APPEND _san_lflags -fsanitize=memory)
	message(STATUS "[${target}] MemorySanitizer: ENABLED")

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/cmake/Sanitizers.cmake` around lines 130 - 140, The
ENABLE_MSAN block in Sanitizers.cmake currently only checks
CMAKE_CXX_COMPILER_ID for Clang but must also verify the target platform; update
the ENABLE_MSAN handling to reject non-supported OSes by checking
CMAKE_SYSTEM_NAME (or equivalent) and erroring out unless it matches Linux (or
allowed BSDs like FreeBSD/NetBSD), so you fail at configure time instead of
applying MSan flags on macOS; keep the existing Clang check and the list(APPEND
_san_cflags/_san_lflags) behavior but add a platform guard that calls
message(FATAL_ERROR "MemorySanitizer requires Linux (or FreeBSD/NetBSD).") when
the OS is unsupported.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify whether sanitizer presets pin compilers
python - <<'PY'
import json
with open("sdk/runanywhere-commons/CMakePresets.json") as f:
    data = json.load(f)
for p in data.get("configurePresets", []):
    if p.get("name", "").startswith("dev-"):
        env = p.get("environment", {})
        print(p["name"], "CC=", env.get("CC"), "CXX=", env.get("CXX"))
PY

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 193

---

🏁 Script executed:

#!/bin/bash
# Extract and verify the CMakePresets.json structure around the specified lines
cat -n sdk/runanywhere-commons/CMakePresets.json | sed -n '80,120p'

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1882

---

🏁 Script executed:

#!/bin/bash
# Find dev-no-backends preset and its environment section
cat -n sdk/runanywhere-commons/CMakePresets.json | sed -n '50,88p'

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1928

---

🏁 Script executed:

#!/bin/bash
# Find dev-no-backends preset
grep -n "dev-no-backends" sdk/runanywhere-commons/CMakePresets.json

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 109

---

🏁 Script executed:

#!/bin/bash
# View the dev-no-backends preset and its structure
cat -n sdk/runanywhere-commons/CMakePresets.json | sed -n '18,50p'

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1345

---

Add CC/CXX compiler env vars to all dev presets.

All four dev presets lack explicit compiler configuration. Per C++ Commons guidelines, gcc/g++ must be pinned to avoid clang toolchain drift, which breaks builds on this platform due to missing C++ stdlib headers.

Update three presets with existing environment sections (dev-asan at 84-87, dev-ubsan at 100-102, dev-tsan at 115-117) by adding:

"CC": "gcc",
"CXX": "g++",

Also add an "environment" section to dev-no-backends (currently missing) with the same compiler variables.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/CMakePresets.json` around lines 84 - 87, Add explicit
CC/CXX compiler environment variables to the dev presets so builds are pinned to
gcc/g++; for the existing presets dev-asan, dev-ubsan, and dev-tsan, update
their "environment" objects to include "CC": "gcc" and "CXX": "g++"; for
dev-no-backends, create an "environment" section and add the same "CC" and "CXX"
entries so all four dev presets consistently use gcc/g++.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Commit-count metadata is already stale.

Line [3] says “12 commits,” but the same document’s table has more entries. Prefer removing the hard-coded count or making it “N+ commits” to avoid immediate drift.

📝 Suggested doc tweak

-> **Branch**: `smonga/cpp-layer-full-cleanup` (12 commits, branched from `main @ bc7db9bd0`).
+> **Branch**: `smonga/cpp-layer-full-cleanup` (branched from `main @ bc7db9bd0`).

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	> **Branch**: `smonga/cpp-layer-full-cleanup` (12 commits, branched from `main @ bc7db9bd0`).
	> **Branch**: `smonga/cpp-layer-full-cleanup` (branched from `main @ bc7db9bd0`).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/CPP_LAYER_CLEANUP_STATUS.md` at line 3, Update the
hard-coded commit count in the document header: replace the exact line
containing "Branch: `smonga/cpp-layer-full-cleanup` (12 commits, branched from
`main @ bc7db9bd0`)" so it no longer hard-codes "12 commits" — either remove the
numeric count entirely or change it to a non-stale form like "N+ commits" (or
"multiple commits") so the header stays accurate as the table below changes.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

fd -i "rac_error.cpp" sdk/runanywhere-commons | while read -r f; do
  echo "== Inspecting: $f =="
  rg -n -C3 "rac_error_message|RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION|RAC_ERROR_JNI_EXCEPTION|-605|-606" "$f"
done

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 309

---

🏁 Script executed:

#!/bin/bash
# Get the full rac_error_message() implementation from rac_error.cpp
rg -n "^const char\* rac_error_message|RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION|RAC_ERROR_JNI_EXCEPTION|-605|-606" sdk/runanywhere-commons/src/core/rac_error.cpp -A 200 | head -250

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 9678

---

🏁 Script executed:

#!/bin/bash
# Search for -600 range error codes and their case statements
rg -n "case RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION|case RAC_ERROR_JNI_EXCEPTION|-605|-606|// =.*-6[0-9][0-9]" sdk/runanywhere-commons/src/core/rac_error.cpp

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 56

---

🏁 Script executed:

#!/bin/bash
# Get the entire rac_error_message() function
sed -n '22,/^}/p' sdk/runanywhere-commons/src/core/rac_error.cpp | tail -100

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 4500

---

Add case statements for RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION and RAC_ERROR_JNI_EXCEPTION in rac_error_message().

Both new error codes (-605 and -606) are missing from the switch statement in rac_error_message() implementation (sdk/runanywhere-commons/src/core/rac_error.cpp). Without mappings, callers will receive the generic "Unknown error code" message instead of descriptive text.

Add to BACKEND ERRORS section in rac_error_message():

case RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION:
    return "Backend runtime ABI is incompatible with the version the SDK was compiled against";
case RAC_ERROR_JNI_EXCEPTION:
    return "JNI call from a Kotlin/Java callback left a pending Java exception";

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/include/rac/core/rac_error.h` around lines 370 - 380,
Add mappings for the two new error macros inside the rac_error_message() switch
so callers get descriptive messages: locate rac_error_message (in
sdk/runanywhere-commons/src/core/rac_error.cpp) and add case
RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION to return a string describing the backend
runtime ABI/version mismatch and case RAC_ERROR_JNI_EXCEPTION to return a string
describing a pending Java exception from a JNI callback; ensure the returned
messages match the comments in rac_error.h and follow the existing
formatting/style of other case branches.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Reference to an undefined version macro in docs.

Line [96] mentions RAC_PLATFORM_ADAPTER_VERSION_LATEST, but this header only defines RAC_PLATFORM_ADAPTER_VERSION. Please align the comment with actual symbols.

📝 Suggested doc correction

- *   When new callbacks are appended here, bump RAC_PLATFORM_ADAPTER_VERSION
- *   and bump RAC_PLATFORM_ADAPTER_VERSION_LATEST. Older consumers continue
+ *   When new callbacks are appended here, bump RAC_PLATFORM_ADAPTER_VERSION.
+ *   Older consumers continue

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	* When new callbacks are appended here, bump RAC_PLATFORM_ADAPTER_VERSION
	* and bump RAC_PLATFORM_ADAPTER_VERSION_LATEST. Older consumers continue
	* to work by setting their `version` to the version they were compiled
	* against; the runtime only reads callbacks through that version.
	* When new callbacks are appended here, bump RAC_PLATFORM_ADAPTER_VERSION.
	* Older consumers continue
	* to work by setting their `version` to the version they were compiled
	* against; the runtime only reads callbacks through that version.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/include/rac/core/rac_platform_adapter.h` around lines
95 - 98, The comment references a nonexistent macro
`RAC_PLATFORM_ADAPTER_VERSION_LATEST`; update the comment to match the actual
symbol names used in this header by either changing the text to only mention
`RAC_PLATFORM_ADAPTER_VERSION` (and explain bumping that macro when callbacks
are appended) or add/introduce a proper `RAC_PLATFORM_ADAPTER_VERSION_LATEST`
definition if intended; locate the comment near `RAC_PLATFORM_ADAPTER_VERSION`
and make the wording consistent with the defined macro so consumers can rely on
the documented symbol.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

Bind each service to the provider that created its backend handle.

The service creates backend_handle with whatever g_provider points to at init time, but every later operation reloads the global provider again. If rac_wakeword_provider_set() clears or replaces the provider while services are alive, destroy/process/unload/set_threshold can route an old handle through the wrong vtable or skip cleanup entirely. Store the provider pointer on WakewordService (or reject provider changes while services exist) and use that captured ops table for the lifetime of the handle.

Suggested fix

 struct WakewordService {
   ...
+  const rac_wakeword_provider_ops_t* provider = nullptr;
   rac_handle_t backend_handle = nullptr;
 };

-    const auto* provider = g_provider.load(std::memory_order_acquire);
-    if (provider && provider->create) {
+    service->provider = g_provider.load(std::memory_order_acquire);
+    if (service->provider && service->provider->create) {
         rac_handle_t backend_handle = nullptr;
-        rac_result_t rc =
-            provider->create(&service->config, &backend_handle, provider->user_data);
+        rac_result_t rc = service->provider->create(
+            &service->config, &backend_handle, service->provider->user_data);
         ...
     }

-    const auto* provider = g_provider.load(std::memory_order_acquire);
+    const auto* provider = service->provider;

Also applies to: 161-188, 211-219, 256-277, 309-321, 530-540, 607-633, 757-767, 852-865

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/features/wakeword/wakeword_service.cpp` around
lines 39 - 41, The service currently uses the global g_provider at init but
re-reads it for later ops, which can misroute old backend_handle through a new
vtable; modify WakewordService to capture and store the provider pointer (const
rac_wakeword_provider_ops_t*) used when creating backend_handle and use that
stored ops table for all lifecycle calls (destroy, process, unload,
set_threshold) instead of reading g_provider each time; alternatively, implement
a guard in rac_wakeword_provider_set() to reject provider changes while
WakewordService instances exist—update methods referencing g_provider to use the
instance field (and ensure constructor stores the provider) so cleanup always
uses the correct ops.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== Where jni_scope.h is included =="
rg -n -C2 '#include ".*jni_scope\.h"|#include <jni\.h>' sdk/runanywhere-commons

echo
echo "== JNI-related build wiring =="
fd -i "CMakeLists.txt" sdk/runanywhere-commons | while read -r f; do
  echo "--- $f ---"
  rg -n -C2 "JNI|find_package\\(JNI|runanywhere_commons_jni\\.cpp|target_include_directories|ANDROID" "$f" || true
done

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 23247

---

🏁 Script executed:

# Check if backend JNI targets explicitly configure JNI_INCLUDE_DIRS
rg -A 5 "add_library.*_jni.*SHARED" sdk/runanywhere-commons/src/backends/*/CMakeLists.txt

# Also check for any conditional include wiring in backend CMakeLists
echo "=== Checking for JNI_INCLUDE_DIRS in backend CMakeLists ==="
fd -i "CMakeLists.txt" sdk/runanywhere-commons/src/backends | xargs rg "JNI_INCLUDE_DIRS" || echo "No JNI_INCLUDE_DIRS found in backend CMakeLists"

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 1948

---

Add explicit JNI_INCLUDE_DIRS to all backend JNI targets.

Backend JNI targets (rac_backend_onnx_jni, rac_backend_whispercpp_jni, rac_backend_llamacpp_jni, rac_backend_rag_jni) in sdk/runanywhere-commons/src/backends/*/CMakeLists.txt and sdk/runanywhere-commons/src/features/rag/CMakeLists.txt omit JNI_INCLUDE_DIRS from their target_include_directories() calls. The project-wide include_directories(SYSTEM ${JNI_INCLUDE_DIRS}) in the main CMakeLists.txt applies only on non-Android (for IDE support), leaving these targets unable to find <jni.h> during actual Android builds. Each backend JNI target must explicitly include ${JNI_INCLUDE_DIRS} in its target-level configuration.

🧰 Tools

🪛 Clang (14.0.6)

[error] 56-56: 'jni.h' file not found

(clang-diagnostic-error)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/jni/jni_scope.h` at line 56, The backend JNI
targets rac_backend_onnx_jni, rac_backend_whispercpp_jni,
rac_backend_llamacpp_jni, and rac_backend_rag_jni are missing
${JNI_INCLUDE_DIRS} in their target_include_directories calls; update each
CMakeLists.txt for these targets to add ${JNI_INCLUDE_DIRS} (as SYSTEM or
PUBLIC/PRIVATE as appropriate) to the target_include_directories() invocation so
that <jni.h> is available for Android builds (ensure you reference the exact
target names above when making the change).

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Stop the LLM stream when onToken() throws.

After JniScope clears a Java exception, this path returns RAC_TRUE, so native generation keeps running and racLlmComponentGenerateStreamWithCallback() can still complete successfully even though Kotlin stopped receiving tokens. Mark the context as failed and return RAC_FALSE so the waiter observes a real stream failure.

Suggested fix

-            if (hadException) {
-                // Ignore callback return value when JNI exception was thrown.
-                return RAC_TRUE;
-            }
+            if (hadException) {
+                {
+                    std::lock_guard<std::mutex> lock(ctx->mtx);
+                    ctx->has_error = true;
+                    ctx->error_code = RAC_ERROR_JNI_EXCEPTION;
+                    ctx->error_message = "onToken callback threw";
+                    ctx->is_complete = true;
+                }
+                ctx->cv.notify_one();
+                return RAC_FALSE;
+            }

Also applies to: 836-839

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/jni/runanywhere_commons_jni.cpp` around lines 807
- 830, The code currently ignores Java exceptions cleared by rac::jni::JniScope
(js.failed() / hadException) and continues generation returning RAC_TRUE; update
the token-callback handling in racLlmComponentGenerateStreamWithCallback's loop
so that if js.failed() (i.e., hadException is true) after calling
ctx->onTokenMethod on ctx->callback (both byte and string paths) you mark the
context as failed and return RAC_FALSE immediately; ensure you reference
JniScope js, ctx->onTokenExpectsBytes, ctx->callback and ctx->onTokenMethod and
replace the current unconditional RAC_TRUE return with a failure path that stops
the stream.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Check GetStringUTFChars() before logging and parsing jResult.

GetStringUTFChars() can return nullptr, but this callback immediately logs json_str, passes it to json::parse, and releases it unconditionally. That turns an OOM/JNI failure into undefined behavior instead of a clean early return.

Suggested fix

-        const char* json_str = env->GetStringUTFChars(jResult, nullptr);
-        LOGd("jni_device_get_info: parsing JSON: %.200s...", json_str);
+        const char* json_str = env->GetStringUTFChars(jResult, nullptr);
+        s.check("GetStringUTFChars");
+        if (json_str == nullptr || s.failed()) {
+            return;
+        }
+        LOGd("jni_device_get_info: parsing JSON: %.200s...", json_str);
...
-        env->ReleaseStringUTFChars(jResult, json_str);
+        env->ReleaseStringUTFChars(jResult, json_str);

Also applies to: 2866-2949

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/jni/runanywhere_commons_jni.cpp` around lines
2859 - 2864, In jni_device_get_info handling, guard against GetStringUTFChars
returning null: after obtaining jstring jResult from cb_result.get() and before
calling env->GetStringUTFChars (or using json_str), check that jResult is
non-null and that the returned const char* from GetStringUTFChars is not null;
if either is null, call RAC_JNI_TRY_VOID(s) or return early (releasing resources
appropriately) instead of proceeding to log or json::parse; update the code
paths around rac::jni::JniScope s(...), cb_result,
g_device_jni_state.get_device_info_method, and any subsequent json::parse and
env->ReleaseStringUTFChars calls to only run when the UTF chars pointer is valid
so we avoid UB on OOM/JNI failures.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Locate rac_error.cpp and verify new code coverage"
fd -i '^rac_error\.cpp$' | while read -r f; do
  echo "== $f =="

  echo "-- New constants referenced --"
  rg -n -C2 'RAC_ERROR_BACKEND_UNAVAILABLE|RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION|RAC_ERROR_JNI_EXCEPTION' "$f"

  echo "-- switch-case mappings in rac_error_message() --"
  rg -n -C2 'case\s+RAC_ERROR_BACKEND_UNAVAILABLE|case\s+RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION|case\s+RAC_ERROR_JNI_EXCEPTION' "$f"
done

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 747

---

🏁 Script executed:

#!/bin/bash
# Extract the rac_error_message() function to see all switch cases
fd -i '^rac_error\.cpp$' | head -1 | xargs cat | \
  awk '/^[a-zA-Z_].*rac_error_message\(/{flag=1} flag{print NR": "$0} /^}$/{if(flag && prev_brace++) exit}' | head -100

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 4882

---

🏁 Script executed:

#!/bin/bash
# Extract rac_error_message() function and show lines around 310
fd -i '^rac_error\.cpp$' | head -1 | xargs sed -n '250,350p'

Repository: RunanywhereAI/runanywhere-sdks

Length of output: 4364

---

Add message mappings for RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION and RAC_ERROR_JNI_EXCEPTION in rac_error_message().

Two of the three new error codes (-605 and -606) are missing case statements in rac_error.cpp. Only RAC_ERROR_BACKEND_UNAVAILABLE (-604) has a mapping. Without entries in the switch statement, callers will receive "Unknown error code" instead of meaningful error messages.

Add the following cases to the BACKEND ERRORS section in sdk/runanywhere-commons/src/core/rac_error.cpp:

case RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION:
    return "Backend ABI incompatible with SDK version";
case RAC_ERROR_JNI_EXCEPTION:
    return "JNI exception occurred";

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_error.h`
around lines 368 - 377, The switch in rac_error_message() is missing case
mappings for RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION and RAC_ERROR_JNI_EXCEPTION,
so callers get "Unknown error code"; add two cases in the BACKEND ERRORS section
of rac_error.cpp within rac_error_message(): one for
RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION that returns "Backend ABI incompatible
with SDK version" and one for RAC_ERROR_JNI_EXCEPTION that returns "JNI
exception occurred".

[coderabbitai]

Actionable comments posted: 3

♻️ Duplicate comments (1)

sdk/runanywhere-commons/src/core/rac_core.cpp (1)

127-131: ⚠️ Potential issue | 🟡 Minor

Remove the {0}-init placeholder from the error detail.

Line 130 still contains an unexpanded template token, so callers will see {0}-init verbatim in diagnostics.

🛠️ Suggested wording

         rac_error_set_details(
             "Platform adapter .version is 0. Every caller must set "
             "`.version = RAC_PLATFORM_ADAPTER_VERSION` before passing the "
-            "adapter to rac_init(). If you are using {0}-init, add the "
-            "assignment explicitly.");
+            "adapter to rac_init(). Set the field explicitly during adapter "
+            "initialization.");

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/core/rac_core.cpp` around lines 127 - 131, Update
the error text passed to rac_error_set_details to remove the unexpanded
`{0}-init` placeholder: change the message in the rac_error_set_details call
that mentions ".version is 0" so it no longer contains `{0}-init` and instead
uses a plain instruction (e.g., "If you are using a platform-specific init, set
`.version = RAC_PLATFORM_ADAPTER_VERSION` before calling rac_init()."); keep
references to `.version`, RAC_PLATFORM_ADAPTER_VERSION and rac_init() so callers
know what to change.

🧹 Nitpick comments (3)

sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_hardware.h (1)

98-98: Add RAC_NODISCARD to the formatted-report allocator.

Line 98 returns newly allocated memory; if the return value is accidentally ignored, that leaks memory silently. Marking it RAC_NODISCARD helps catch misuse at compile time.

Proposed diff

-RAC_API char* rac_hardware_format_report(const rac_hardware_report_t* report);
+RAC_API RAC_NODISCARD char* rac_hardware_format_report(const rac_hardware_report_t* report);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_hardware.h`
at line 98, The declaration for rac_hardware_format_report should be annotated
with RAC_NODISCARD to prevent callers from silently ignoring the newly allocated
return; update the prototype for rac_hardware_format_report in rac_hardware.h
(the declaration "rac_hardware_format_report(const rac_hardware_report_t*
report)") to include the RAC_NODISCARD attribute before the return type so
compilers can warn when the returned char* is discarded.

sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h (1)

419-431: Prefer enforced runtime checks over “undefined behaviour” for re-registration.

Given this is exported API, reject unsafe provider swaps/clears while services are alive (e.g., RAC_ERROR_INVALID_STATE) instead of relying only on contract text.

Also applies to: 437-437

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h`
around lines 419 - 431, The public provider registration function (the one that
sets/clears the backend ops used by rac_wakeword_create) must enforce the
contract at runtime: add a check in rac_wakeword_register_provider (or the
provider-setter function) to refuse swapping or clearing the ops while any
wake-word service instances exist by returning an error code such as
RAC_ERROR_INVALID_STATE; only allow setting NULL when the active-service count
is zero. Track active services (increment in rac_wakeword_create, decrement in
rac_wakeword_destroy) and protect both the count and the provider pointer with
the same mutex to avoid races, returning the error immediately instead of
leaving the behaviour undefined.

sdk/runanywhere-commons/src/core/rac_core.cpp (1)

134-138: Make the runtime check match the documented ABI contract.

rac_platform_adapter_t.version is documented as “must equal RAC_PLATFORM_ADAPTER_VERSION”, but this branch only rejects 0 and newer versions. After the next version bump, stale adapters will still pass init unless equality is enforced or backward compatibility is documented explicitly.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/core/rac_core.cpp` around lines 134 - 138, The
platform adapter version check currently only rejects adapters newer than
RAC_PLATFORM_ADAPTER_VERSION; change the comparison in the initialization path
that reads rac_platform_adapter_t.version to enforce equality with
RAC_PLATFORM_ADAPTER_VERSION (i.e., fail when version !=
RAC_PLATFORM_ADAPTER_VERSION) so stale or future adapter versions are rejected
per the documented ABI contract; update the rac_error_set_details message to
state that the adapter version must equal RAC_PLATFORM_ADAPTER_VERSION and
return RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION from the same branch (refer to
rac_platform_adapter_t.version and RAC_PLATFORM_ADAPTER_VERSION in
rac_core.cpp).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In
`@sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h`:
- Line 445: The function rac_wakeword_has_provider currently returns rac_bool_t
and must be converted to the rac_result_t convention: change the public
declaration to rac_result_t rac_wakeword_has_provider(rac_bool_t*
out_has_provider) and update the implementation to validate out_has_provider
(return appropriate rac_result_t on null), set *out_has_provider to the boolean
result, and return RAC_RESULT_OK or an error code on failure; update any
internal helper functions, callers, and unit tests to use the new pointer output
pattern and handle rac_result_t checks accordingly, keeping the RAC_API export
macro and function name unchanged except for the new signature.
- Around line 362-411: The public vtable rac_wakeword_provider_ops_t can break
ABI when fields change; add explicit ABI fields (e.g. uint32_t abi_version and
size_t struct_size) as the first members of rac_wakeword_provider_ops_t and
document the current ABI_VERSION constant; then update
rac_wakeword_provider_set() to validate the incoming ops by checking
ops->abi_version equals the expected ABI_VERSION and ops->struct_size is at
least the minimum expected size (or equals sizeof the known struct) and return a
rac_result_t error if validation fails, ensuring all subsequent code uses only
fields within the validated struct_size.

In `@sdk/runanywhere-commons/src/core/rac_core.cpp`:
- Around line 120-139: The ABI-version check added to rac_init() must be
duplicated in rac_set_platform_adapter(): in rac_set_platform_adapter(),
validate platform_adapter->version (reject 0 and versions >
RAC_PLATFORM_ADAPTER_VERSION) and call rac_error_set_details with a matching
explanatory message and return RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION on
failure; ensure you reference the same error texts and constants
(RAC_PLATFORM_ADAPTER_VERSION, rac_error_set_details,
RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION, and platform_adapter->version) so the
adapter cannot be installed with an unversioned or too-new layout.

---

Duplicate comments:
In `@sdk/runanywhere-commons/src/core/rac_core.cpp`:
- Around line 127-131: Update the error text passed to rac_error_set_details to
remove the unexpanded `{0}-init` placeholder: change the message in the
rac_error_set_details call that mentions ".version is 0" so it no longer
contains `{0}-init` and instead uses a plain instruction (e.g., "If you are
using a platform-specific init, set `.version = RAC_PLATFORM_ADAPTER_VERSION`
before calling rac_init()."); keep references to `.version`,
RAC_PLATFORM_ADAPTER_VERSION and rac_init() so callers know what to change.

---

Nitpick comments:
In
`@sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h`:
- Around line 419-431: The public provider registration function (the one that
sets/clears the backend ops used by rac_wakeword_create) must enforce the
contract at runtime: add a check in rac_wakeword_register_provider (or the
provider-setter function) to refuse swapping or clearing the ops while any
wake-word service instances exist by returning an error code such as
RAC_ERROR_INVALID_STATE; only allow setting NULL when the active-service count
is zero. Track active services (increment in rac_wakeword_create, decrement in
rac_wakeword_destroy) and protect both the count and the provider pointer with
the same mutex to avoid races, returning the error immediately instead of
leaving the behaviour undefined.

In `@sdk/runanywhere-commons/src/core/rac_core.cpp`:
- Around line 134-138: The platform adapter version check currently only rejects
adapters newer than RAC_PLATFORM_ADAPTER_VERSION; change the comparison in the
initialization path that reads rac_platform_adapter_t.version to enforce
equality with RAC_PLATFORM_ADAPTER_VERSION (i.e., fail when version !=
RAC_PLATFORM_ADAPTER_VERSION) so stale or future adapter versions are rejected
per the documented ABI contract; update the rac_error_set_details message to
state that the adapter version must equal RAC_PLATFORM_ADAPTER_VERSION and
return RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION from the same branch (refer to
rac_platform_adapter_t.version and RAC_PLATFORM_ADAPTER_VERSION in
rac_core.cpp).

In `@sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_hardware.h`:
- Line 98: The declaration for rac_hardware_format_report should be annotated
with RAC_NODISCARD to prevent callers from silently ignoring the newly allocated
return; update the prototype for rac_hardware_format_report in rac_hardware.h
(the declaration "rac_hardware_format_report(const rac_hardware_report_t*
report)") to include the RAC_NODISCARD attribute before the return type so
compilers can warn when the returned char* is discarded.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 57eb33c0-4705-44ee-9f86-ee1d12613a6f

📥 Commits

Reviewing files that changed from the base of the PR and between 459c324 and 2ed7fb2.

📒 Files selected for processing (14)

• sdk/runanywhere-commons/include/rac/backends/rac_backend_metalrt.h
• sdk/runanywhere-commons/include/rac/backends/rac_llm_llamacpp.h
• sdk/runanywhere-commons/include/rac/backends/rac_stt_onnx.h
• sdk/runanywhere-commons/include/rac/backends/rac_stt_whispercpp.h
• sdk/runanywhere-commons/include/rac/backends/rac_tts_onnx.h
• sdk/runanywhere-commons/include/rac/backends/rac_vad_onnx.h
• sdk/runanywhere-commons/include/rac/backends/rac_vlm_llamacpp.h
• sdk/runanywhere-commons/include/rac/backends/rac_wakeword_onnx.h
• sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h
• sdk/runanywhere-commons/src/core/rac_core.cpp
• sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/CRACommons.h
• sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_attrs.h
• sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_hardware.h
• sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_types.h

✅ Files skipped from review due to trivial changes (4)

• sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_types.h
• sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/CRACommons.h
• sdk/runanywhere-swift/Sources/RunAnywhere/CRACommons/include/rac_attrs.h
• sdk/runanywhere-commons/include/rac/backends/rac_wakeword_onnx.h

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Add ABI version/size fields to rac_wakeword_provider_ops_t before this interface hardens.

This public vtable can silently break binary compatibility when fields are added/reordered. Add an explicit version/size contract and validate it in rac_wakeword_provider_set().

Proposed header-side ABI hardening

+// Increment when `rac_wakeword_provider_ops_t` layout changes incompatibly.
+#define RAC_WAKEWORD_PROVIDER_OPS_VERSION 1u
+
 typedef struct rac_wakeword_provider_ops {
+    /** ABI version for this vtable layout. */
+    uint32_t version;
+    /** sizeof(rac_wakeword_provider_ops_t) from provider compile unit. */
+    uint32_t struct_size;
+
     /** Create a backend-specific handle. Called once per wake-word service
      *  during rac_wakeword_initialize(). Must return a handle suitable for
      *  passing to every other vtable method (and to `destroy`). */
     rac_result_t (*create)(const rac_wakeword_config_t* config,
                            rac_handle_t* out_backend_handle,
                            void* user_data);

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	typedef struct rac_wakeword_provider_ops {
	/** Create a backend-specific handle. Called once per wake-word service
	* during rac_wakeword_initialize(). Must return a handle suitable for
	* passing to every other vtable method (and to `destroy`). */
	rac_result_t (*create)(const rac_wakeword_config_t* config,
	rac_handle_t* out_backend_handle,
	void* user_data);
	/** Load a wake-word classification model (ONNX, etc.). */
	rac_result_t (*load_model)(rac_handle_t backend_handle,
	const char* model_path,
	const char* model_id,
	const char* wake_word,
	void* user_data);
	/** Unload a wake-word model previously loaded with load_model. */
	rac_result_t (*unload_model)(rac_handle_t backend_handle,
	const char* model_id,
	void* user_data);
	/** Load a VAD pre-filter model (Silero). Optional. */
	rac_result_t (*load_vad)(rac_handle_t backend_handle,
	const char* vad_model_path,
	void* user_data);
	/** Run one frame of audio through inference + optional VAD.
	* out_detected_index is set to >= 0 if a wake word fires (index into
	* the provider's loaded-models list) or -1 otherwise. */
	rac_result_t (*process)(rac_handle_t backend_handle,
	const float* samples, size_t num_samples,
	int32_t* out_detected_index,
	float* out_confidence,
	rac_bool_t* out_vad_speech,
	float* out_vad_confidence,
	void* user_data);
	/** Reset internal state (KV cache, sliding window, etc.). */
	rac_result_t (*reset)(rac_handle_t backend_handle, void* user_data);
	/** Adjust detection threshold at runtime. */
	rac_result_t (*set_threshold)(rac_handle_t backend_handle,
	float threshold,
	void* user_data);
	/** Tear down the backend handle. */
	void (*destroy)(rac_handle_t backend_handle, void* user_data);
	/** Opaque user-data passed through to every callback. */
	void* user_data;
	} rac_wakeword_provider_ops_t;
	// Increment when `rac_wakeword_provider_ops_t` layout changes incompatibly.
	`#define` RAC_WAKEWORD_PROVIDER_OPS_VERSION 1u
	typedef struct rac_wakeword_provider_ops {
	/** ABI version for this vtable layout. */
	uint32_t version;
	/** sizeof(rac_wakeword_provider_ops_t) from provider compile unit. */
	uint32_t struct_size;
	/** Create a backend-specific handle. Called once per wake-word service
	* during rac_wakeword_initialize(). Must return a handle suitable for
	* passing to every other vtable method (and to `destroy`). */
	rac_result_t (*create)(const rac_wakeword_config_t* config,
	rac_handle_t* out_backend_handle,
	void* user_data);
	/** Load a wake-word classification model (ONNX, etc.). */
	rac_result_t (*load_model)(rac_handle_t backend_handle,
	const char* model_path,
	const char* model_id,
	const char* wake_word,
	void* user_data);
	/** Unload a wake-word model previously loaded with load_model. */
	rac_result_t (*unload_model)(rac_handle_t backend_handle,
	const char* model_id,
	void* user_data);
	/** Load a VAD pre-filter model (Silero). Optional. */
	rac_result_t (*load_vad)(rac_handle_t backend_handle,
	const char* vad_model_path,
	void* user_data);
	/** Run one frame of audio through inference + optional VAD.
	* out_detected_index is set to >= 0 if a wake word fires (index into
	* the provider's loaded-models list) or -1 otherwise. */
	rac_result_t (*process)(rac_handle_t backend_handle,
	const float* samples, size_t num_samples,
	int32_t* out_detected_index,
	float* out_confidence,
	rac_bool_t* out_vad_speech,
	float* out_vad_confidence,
	void* user_data);
	/** Reset internal state (KV cache, sliding window, etc.). */
	rac_result_t (*reset)(rac_handle_t backend_handle, void* user_data);
	/** Adjust detection threshold at runtime. */
	rac_result_t (*set_threshold)(rac_handle_t backend_handle,
	float threshold,
	void* user_data);
	/** Tear down the backend handle. */
	void (*destroy)(rac_handle_t backend_handle, void* user_data);
	/** Opaque user-data passed through to every callback. */
	void* user_data;
	} rac_wakeword_provider_ops_t;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h`
around lines 362 - 411, The public vtable rac_wakeword_provider_ops_t can break
ABI when fields change; add explicit ABI fields (e.g. uint32_t abi_version and
size_t struct_size) as the first members of rac_wakeword_provider_ops_t and
document the current ABI_VERSION constant; then update
rac_wakeword_provider_set() to validate the incoming ops by checking
ops->abi_version equals the expected ABI_VERSION and ops->struct_size is at
least the minimum expected size (or equals sizeof the known struct) and return a
rac_result_t error if validation fails, ensuring all subsequent code uses only
fields within the validated struct_size.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

rac_wakeword_has_provider should follow rac_result_t error-handling convention.

Returning rac_bool_t directly introduces a new inconsistency in the public C API surface. Consider rac_result_t rac_wakeword_has_provider(rac_bool_t* out_has_provider).

As per coding guidelines, “All public API functions must be declared in include/rac/ header files and implement consistent error handling via rac_result_t.”

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/include/rac/features/wakeword/rac_wakeword_service.h`
at line 445, The function rac_wakeword_has_provider currently returns rac_bool_t
and must be converted to the rac_result_t convention: change the public
declaration to rac_result_t rac_wakeword_has_provider(rac_bool_t*
out_has_provider) and update the implementation to validate out_has_provider
(return appropriate rac_result_t on null), set *out_has_provider to the boolean
result, and return RAC_RESULT_OK or an error code on failure; update any
internal helper functions, callers, and unit tests to use the new pointer output
pattern and handle rac_result_t checks accordingly, keeping the RAC_API export
macro and function name unchanged except for the new signature.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Validate adapters in rac_set_platform_adapter() too.

This ABI gate only protects rac_init(). rac_set_platform_adapter() at Lines 68-74 can still install an unversioned or future-layout adapter, which reintroduces the callback-offset risk this change is meant to prevent.

🛠️ Suggested extraction

+static rac_result_t validate_platform_adapter_version(
+    const rac_platform_adapter_t* adapter) {
+    if (adapter == nullptr) {
+        return RAC_ERROR_NULL_POINTER;
+    }
+
+    const uint32_t adapter_version = adapter->version;
+    if (adapter_version == 0) {
+        rac_error_set_details(
+            "Platform adapter .version is 0. Set "
+            "`.version = RAC_PLATFORM_ADAPTER_VERSION` before passing the "
+            "adapter to rac_init().");
+        return RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION;
+    }
+    if (adapter_version != RAC_PLATFORM_ADAPTER_VERSION) {
+        rac_error_set_details(
+            "Platform adapter version is incompatible with this runtime.");
+        return RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION;
+    }
+    return RAC_SUCCESS;
+}
+
 rac_result_t rac_set_platform_adapter(const rac_platform_adapter_t* adapter) {
-    if (adapter == nullptr) {
-        return RAC_ERROR_NULL_POINTER;
+    rac_result_t result = validate_platform_adapter_version(adapter);
+    if (result != RAC_SUCCESS) {
+        return result;
     }
     s_platform_adapter = adapter;
     return RAC_SUCCESS;
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/runanywhere-commons/src/core/rac_core.cpp` around lines 120 - 139, The
ABI-version check added to rac_init() must be duplicated in
rac_set_platform_adapter(): in rac_set_platform_adapter(), validate
platform_adapter->version (reject 0 and versions > RAC_PLATFORM_ADAPTER_VERSION)
and call rac_error_set_details with a matching explanatory message and return
RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION on failure; ensure you reference the same
error texts and constants (RAC_PLATFORM_ADAPTER_VERSION, rac_error_set_details,
RAC_ERROR_BACKEND_INCOMPATIBLE_VERSION, and platform_adapter->version) so the
adapter cannot be installed with an unversioned or too-new layout.