fix(qhexrt): restore example catalog architecture eligibility

SH
10h ago
+2413-2398

Description

Ineligible QHexRT example rows currently reach registration because most architecture restrictions from the deleted native catalog were not copied into the app catalogs. Restore those restrictions for all existing rows: 47 restricted Flutter entries and 36 restricted React Native entries. For example, qwen3_5_4b now skips v75 before registration instead of requesting an unavailable variant.

Preserve both curated model selections and their URLs and metadata. Document the deliberate v81-only Kitten nano manifest selection and continued omission of the private varlen variant; introducing that variant requires an explicit HF-auth preflight. The other native-only entries remain outside these curated catalogs.

Add independent expected eligibility matrices for every current row on v75/v79/v81, pinned match/mismatch, exclusions, unsupported devices, and URL-folder/filename pin consistency. Flutter tests also verify that ineligible rows never reach the registrar. Run the focused Flutter example suite explicitly in PR CI, since it is outside the Melos package workspace.

Depends on #685, which is still open. This PR branches from its head 6380738, so the full diff includes that prerequisite. It is ready for automated review; do not merge before #685 is integrated. Review the catalog eligibility implementation in commit 0f4b441 and the SDK review corrections in commit e503cc9. Incorporate shared SDK corrections into the prerequisite as appropriate, then rebase onto main after #685 merges.

SDK review corrections

Preserve Kotlin tool-result serialization failures instead of reporting a successful empty result, forward React Native multi-file and explicit-layout archive metadata, and retain native error details through React Native and Flutter. Keep Kotlin's original registration parameter positions and hidden JVM/default-argument forwarding overloads. Preserve the JNI fallback exception type.

The prerequisite removes the native curated catalog and rac_qhexrt_catalog_* C ABI, including Flutter's modelSupportsArchitecture, modelRequiresHfAuth, and registerModelForDevice APIs. This is a breaking removal: curated eligibility and HF-auth preflight are application-owned, while commons/engine layers retain URL resolution, registry, download, and inference behavior. Explicit architecture pins are preserved without device validation at registration; callers must filter incompatible pins. See migration guidance and the QHexRT changelog.

Closes #1035.
Closes #1036.

Type of Change

  • Bug fix
  • Documentation update
  • Breaking API removal inherited from #685; migration documented

Testing

  • Focused lint, analysis, and formatting pass locally
  • Added/updated tests for changes

Validation of the follow-up commit:

  • Flutter 3.44.6 / Dart 3.12.2: 19 catalog tests pass; analysis of both changed Dart files reports no issues; formatting passes.
  • React Native: 12 catalog tests pass; ESLint and Prettier pass; focused strict TypeScript check passes against the actual public SDK type definitions and generated proto declarations.
  • Regression checks: original catalogs fail the new architecture matrix tests (six Flutter failures, three RN failures); removing the Kitten nano pin fails both URL consistency tests. Restoring the changes passes again.
  • Workflow YAML, whitespace, AGENTS/CLAUDE symlink sync, PII logging, and generated default-pool gates pass.

The complete RN workspace typecheck was not run locally: the minimal dependency install cannot resolve the workspace package @runanywhere/core. The normal PR CI workspace checks remain enabled. No physical-device inference testing was performed.

Review follow-up validation (e503cc9)

  • 29 focused React Native registration/error tests pass; six fail against the original implementations and pass with the fixes.
  • Focused strict TypeScript check passes using actual generated protobuf, React Native, and Nitro declarations.
  • ktlint 1.5.0 passes for changed Kotlin production and test files. New Kotlin tests cover tool-result serialization failures and the legacy JVM/default registration signatures; their execution awaits platform CI.
  • Whitespace, AGENTS/CLAUDE symlink synchronization, centralized-default, and PII-logging gates pass.
  • Repository-wide C++ formatting reports the same 76 files before and after this follow-up. No unrelated formatting sweep was applied.
  • Flutter/native builds and physical-device inference were not run locally for this follow-up; CI remains required.

Platform-Specific Testing

  • Flutter tested on iOS
  • Flutter tested on Android
  • React Native tested on iOS
  • React Native tested on Android

Labels

  • Flutter Sample
  • React Native Sample

Checklist

  • Code follows project style guidelines
  • Self-review completed
  • Documentation updated where needed

Screenshots

Not applicable; no UI layout changes.

Summary by cubic

Restores the architecture eligibility rules lost when the native QHexRT catalog was removed, so ineligible example models no longer reach registration. The Flutter and React Native app catalogs now apply per-architecture restrictions to all existing rows (47 Flutter, 36 React Native): qwen3_5_4b skips v75 instead of requesting an unavailable variant, while curated model selections, URLs, and metadata are unchanged.

Catalog eligibility

  • Adds pinned eligibility expectations for every catalog row on v75/v79/v81, covering match/mismatch, exclusions, unsupported devices, and URL folder/filename consistency; Flutter tests also verify ineligible rows never reach the registrar.
  • Kitten nano stays pinned to its v81-only manifest, and the private varlen variant remains omitted until an explicit HF-auth preflight exists; both decisions are documented.
  • Runs the focused Flutter example catalog suite in PR CI, since the example sits outside the Melos package workspace.

Registration now flows through the core SDK's URL registration instead of the removed native catalog facade; the facade, its wire adapters, and engine-side catalog tests were deleted. downloadSize, contextLength, source, and description are preserved through registration across Flutter, Kotlin, Swift, and React Native, including archive and multi-file registration. Native registration failures propagate as canonical SDK exceptions with their original error codes intact, Kotlin retains its legacy registration JVM entry points, and failed tool-result serialization reports an error instead of retrying native serialization. Docs note that private QHexRT native payloads must come from a compatible authorized build and that example dependency pins match the source package manifests.

Summary by CodeRabbit

  • New Features
    • Model registration across Flutter, Kotlin, Swift, and React Native supports additional metadata, including download size, context length, source, and description.
    • Example apps filter QHexRT models by device capability and architecture before registering eligible models through the core model API.
  • Changes
    • QHexRT no longer provides a built-in model catalog or catalog-based registration. Apps manage model eligibility and registration.
    • Swift now provides a model-registration builder for URL, archive, and multi-file models.
  • Bug Fixes
    • Native registration and bridge errors now retain more specific details.
  • Tests
    • Added coverage for model eligibility, registration metadata, and serialization failures, plus a Flutter build check for catalog eligibility.