fix(web): restore surviving capability owners after backend teardown

[shubhamsinnh]

Description

unregisterWasmModule() in EmscriptenModule.ts removed every _recordByCapability slot owned by a torn-down backend. Because registration is last-writer-wins, unregistering a later module deleted the mapping even when an earlier sibling still claimed the same capability ? getModuleForCapability('llm') returned null and facade verbs reported no backend, contradicting the function's own contract that teardown lets siblings keep their slots.

The fix re-elects the most recently registered surviving sibling (highest registration generation for that capability) for each released capability, restores it in the capability registry, and re-registers it with ModalityProtoAdapter so per-modality dispatch slots and the aggregate defaultModule keep pointing at a live module. reelectLifecycleAndRegistryPrimary() then correctly re-pins the lifecycle/model-registry adapters to the survivor instead of falling back to commons.

Type of Change

• Bug fix
• New feature
• Documentation update
• Refactoring

Testing

• Lint passes locally
• Added/updated tests for changes (existing suite re-run; no new tests per repo guidance)

Local (from bindings/web/packages/core): npm run typecheck (exit 0, 0 errors), npm run lint (exit 0, 0 findings), npx vitest run tests/unit/runtime/EmscriptenModule.test.ts (9/9 passed), npm run test:unit (56 files / 244 tests passed). git diff --check clean.

Platform-Specific Testing (check all that apply)

Swift SDK / iOS Sample:

• Tested on iPhone (Simulator or Device)
• Tested on iPad / Tablet
• Tested on Mac (macOS target)

Kotlin SDK / Android Sample:

• Tested on Android Phone (Emulator or Device)
• Tested on Android Tablet

Flutter SDK / Flutter Sample:

• Tested on iOS
• Tested on Android

React Native SDK / React Native Sample:

• Tested on iOS
• Tested on Android

Web SDK / Web Sample:

• Tested in Chrome (Desktop) ? not run on this host (requires Emscripten WASM + browser; CI covers)
• Tested in Firefox ? not run on this host
• Tested in Safari ? not run on this host
• WASM backends load (LlamaCpp + ONNX) ? not run on this host; CI covers
• OPFS storage persistence verified (survives page refresh) ? not run on this host
• Settings persistence verified (localStorage) ? not run on this host

Labels

Please add the appropriate label(s):

SDKs:

• Swift SDK - Changes to Swift SDK (bindings/swift)
• Kotlin SDK - Changes to Kotlin SDK (bindings/kotlin)
• Flutter SDK - Changes to Flutter SDK (bindings/flutter)
• React Native SDK - Changes to React Native SDK (bindings/react-native)
• Web SDK - Changes to Web SDK (bindings/web)
• Commons - Changes to shared native code (core)

Sample Apps:

• Flutter Sample - Changes to Flutter example app (bindings/flutter/example)
• React Native Sample - Changes to React Native example app (bindings/react-native/example)
• Minimal Examples - Changes to an in-repo SDK harness (bindings/{swift,kotlin,web}/example)

The iOS, Android, Web, and Electron consumer apps live in their own
repositories (RunanywhereAI/runanywhere-{ios,android,web,electron}) ? open
those PRs there.

Checklist

• Code follows project style guidelines
• Self-review completed
• Documentation updated (if needed) ? behavior restored to the documented contract; no doc change required

Screenshots

Attach relevant UI screenshots for changes (if applicable):

• Mobile (Phone)
• Tablet / iPad
• Desktop / Mac

Summary by CodeRabbit

• Bug Fixes
  • Improved WebAssembly module capability management for more predictable ownership when modules are registered or removed.
  • Restored surviving capability handlers automatically when the current provider is unregistered.
  • Ensured capability dispatch consistently follows the most recently registered provider.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b8aaae8c-38cf-48d1-9b51-ad178101e7e0

📥 Commits

Reviewing files that changed from the base of the PR and between 996fe0a and 9860e65.

📒 Files selected for processing (1)

• bindings/web/packages/core/src/runtime/EmscriptenModule.ts

Included review availability: Your plan includes up to 10 reviews per rolling hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

WasmModuleRecord now tracks per-capability registration generations. Module unregistration restores released capabilities to surviving highest-generation owners and re-registers their modality dispatch routes.

Changes

Capability ownership restoration

Layer / File(s)	Summary
Record capability registration generations bindings/web/packages/core/src/runtime/EmscriptenModule.ts	WasmModuleRecord stores per-capability generations. Registration assigns generation values to newly claimed capabilities.
Restore surviving capability owners bindings/web/packages/core/src/runtime/EmscriptenModule.ts	Unregistration selects surviving highest-generation owners and restores their capability and modality dispatch mappings.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 9860e

The change restores surviving Web SDK capability owners after backend teardown, with reported checks passing; no actionable merge-blocking risk remains beyond normal review.

Suggested reviewers: sanchitmonga22

Sequence Diagram(s)

sequenceDiagram
  participant ModuleRegistry
  participant WasmModuleRecord
  participant ModalityProtoAdapter
  ModuleRegistry->>WasmModuleRecord: record capability generations
  ModuleRegistry->>WasmModuleRecord: remove unregistered module
  WasmModuleRecord-->>ModuleRegistry: select highest-generation survivors
  ModuleRegistry->>ModalityProtoAdapter: restore surviving dispatch routes

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the Web SDK bug fix that restores surviving capability owners after backend teardown.
Description check	✅ Passed	The description follows the template, explains the fix, records testing and limitations, and identifies the Web SDK change.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

bindings/web/packages/core/src/runtime/EmscriptenModule.ts

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}