Skip to content

Mobile Bindings Overview

Status: ready for SDK consumers

Goals

  • Provide a minimal C ABI that exposes search and grep capabilities without leaking internal C++ types.
  • Enable embedders to build thin Swift/Kotlin wrappers on top of a shared library (libyams_mobile).
  • Maintain binary compatibility across minor releases via versioned structs and feature flags.

Target Platforms

  • iOS 15+/macOS 13+ (Swift Package Manager integration)
  • Android API 26+ (AAR with JNI bindings)
  • Additional consumers via C-compatible dynamic libraries (e.g., React Native, Flutter)

Architectural Shape

  1. Core ABI Layer — versioned header include/yams/api/mobile_bindings.h compiled into libyams_mobile.
  2. Platform Glue — Swift/Kotlin wrappers (future milestone) translate native types and may layer async semantics over the blocking C entrypoints.
  3. Service Facade — long-lived yams_mobile_context_t mapping to AppContext with configurable storage paths, caches, and worker executors.
  4. Lifecycle Hooks — initialization, shutdown, and JSON-based diagnostics helpers.
[Swift/Combine]      [Kotlin/Coroutines]
        \                 /
         \ yams_mobile C ABI /
          \             /
          Core services (grep/search + fixture-driven corpora)

Data Model Principles

  • All structs are POD with explicit sizes; optional fields are represented via nullable pointers or sentinel flags.
  • Strings use UTF-8 char* with caller-managed allocation; response containers return opaque handles with dispose functions.
  • Errors propagate through yams_mobile_status enums plus optional extended payloads.

Threading & Concurrency

  • Embedders may call APIs from any thread; the library owns a background boost::asio::thread_pool per context.
  • The current C ABI exposes synchronous entrypoints only (yams_mobile_*_execute). Async helpers will ship with platform wrappers.
  • Swift/Kotlin adapters should wrap the blocking calls using dispatch queues/coroutines to surface async behaviour.

Feature Skeleton

Area Available entrypoints Notes
Context lifecycle yams_mobile_context_create, yams_mobile_context_destroy Config accepts working/cache dirs and a telemetry_sink string (console, stderr, noop, or file:/path).
Grep/Search yams_mobile_grep_execute, yams_mobile_search_execute, destroy helpers, yams_mobile_{grep,search}_result_stats_json Blocking calls returning opaque handles plus JSON stats (latency, retry counters).
Document ingest yams_mobile_store_document, yams_mobile_remove_document Update/list flows are deferred; wrappers should enforce doc hygiene.
Metadata inspection yams_mobile_get_metadata, yams_mobile_metadata_result_json JSON payload mirrors DocumentService metadata map.
Vector status yams_mobile_get_vector_status, yams_mobile_vector_status_result_json Returns document counts/storage stats; warmup/model control APIs remain TODO.

Compatibility Strategy

  • ABI version encoded in yams_mobile_version_info (major/minor/patch) and mirrored in the header macros YAMS_MOBILE_API_VERSION_{MAJOR,MINOR,PATCH}.
  • Every request struct now embeds a struct_size/version header so older clients continue to function when fields are appended. Callers should initialize structs via the yams_mobile_context_config_default() / yams_mobile_request_header_default() helpers before setting additional fields.
  • Breaking changes must bump YAMS_MOBILE_API_VERSION_MAJOR and ship a parallel symbol surface (yams_mobile_v2_*) while preserving the previous version for at least one minor release.
  • CI enforces symbol compatibility with scripts/ci/check_mobile_abi.sh, comparing the exported surface against public/mobile/abi/yams_mobile_v1.symbols on every PR.

Fixtures & Test Corpora

  • tests/common/search_corpus_presets.h exposes mobileSearchCorpusSpec() which captures the curated mobile dataset (sync deltas, path sensitivity, semantic warm-up, case toggles). Use this in unit/integration tests to align with the demo apps and smoke suites.
  • tests/mobile/mobile_abi_smoke_test.cpp validates the round-trip ingest/list/search flow against the new corpus and guards the struct header defaults.

Swift Package Demo

  • The Swift reference package lives under examples/mobile/swift/YamsMobileDemo.
  • It provides a CYamsMobile system library target (via the generated yams_mobile.pc) and a minimal executable harness that calls yams_mobile_get_version() and dispatches grep/search flows.
  • To build locally: 1. Install YAMS (or build libyams_mobile) and expose it via PKG_CONFIG_PATH. 2. Run swift build inside the package; the manifest references CYamsMobile through pkg-config. 3. Run swift test to execute the smoke test that mirrors the C++ round-trip harness.

Android Demo

  • The Android reference lives under examples/mobile/android/YamsMobileDemo with a Gradle library module that wraps libyams_mobile via JNI.
  • src/main/cpp/yams_mobile_jni.cpp translates Kotlin calls to the C ABI; instrumentation tests in src/androidTest ensure yams_mobile_get_version() and a basic search flow succeed against the mobile corpus fixtures.
  • Build steps: 1. Place the compiled libyams_mobile.so for each ABI under app/src/main/jniLibs/<abi>/. 2. Run ./gradlew connectedAndroidTest to execute the smoke tests on a device/emulator.

Developer Workflow

  1. Initialize the fixtures using FixtureManager (see smoke test for a template) or reuse the packaged corpora in CI.
  2. Link against yams_mobile using pkg-config (Swift) or JNI (Android).
  3. Run the platform demo harnesses to validate bindings before shipping downstream SDK updates.