@independo/capacitor-inderun 1.1.0-dev.3 → 2.0.0-dev.1

package/Package.swift

@@ -16,15 +16,28 @@ let package = Package(
         .library(
             name: "IndeRunCapacitor",
             targets: ["IndeRunCapacitorPlugin"]
+        ),
+        // The Capacitor CLI derives a product name from the npm package name
+        // (`@independo/capacitor-inderun` -> `IndependoCapacitorInderun`) and writes exactly
+        // that into the app's generated CapApp-SPM manifest. Without a product under this
+        // name, `cap add ios` produces a project that cannot resolve its dependencies at all.
+        // Kept alongside the original name rather than replacing it, so anything already
+        // depending on `IndeRunCapacitor` by URL keeps resolving.
+        .library(
+            name: "IndependoCapacitorInderun",
+            targets: ["IndeRunCapacitorPlugin"]
         )
     ],
     dependencies: [
         .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
-        // `exact:` rather than `from:` while tracking a prerelease: SwiftPM's range
-        // operators exclude prerelease versions, so `from: "0.3.0-dev.14"` would
-        // silently keep resolving 0.2.2 and fail on the missing stream(). Move back
-        // to `from: "0.3.0"` once the stable release is out.
-        .package(url: "https://github.com/independo-gmbh/inderun.git", exact: "0.3.0-dev.14")
+        // Ranged rather than `exact:` so a consumer that also depends on `inderun`
+        // directly can unify the graph. `.upToNextMinor` rather than `from:` because
+        // `from:` on a 0.x means `<1.0.0` — it would let SwiftPM float across a minor
+        // (where an 0.x SDK's breaking changes live) while package.json and
+        // android/build.gradle.kts stay pinned, which is exactly the three-platform
+        // drift the versioning policy forbids. Both operators exclude prereleases:
+        // tracking a `-dev.N` again requires going back to `exact:`.
+        .package(url: "https://github.com/independo-gmbh/inderun.git", .upToNextMinor(from: "0.3.0"))
     ],
     targets: [
         .target(

package/README.md

@@ -52,6 +52,63 @@ itself. On-device execution needs more than the floor: Apple Foundation Models r
 Intelligence–capable device on iOS 26+, and ML Kit GenAI requires AICore / Gemini Nano support.
 Availability is checked at runtime and the cloud provider serves the request when it is missing.
 
+## Host Project Requirements
+
+The IndeRun SDKs this bridge wraps are newer than a freshly generated Capacitor app's
+defaults, so `cap add` alone is not enough. Each of these is a hard requirement — the
+corresponding build failure is named so it is searchable:
+
+**Android** (`android/variables.gradle` and `android/build.gradle` in your app):
+
+| Setting | Value | Failure if unset |
+|---|---|---|
+| `compileSdkVersion` | `37` | *"requires libraries and applications that depend on it to compile against version 37 or later"* |
+| `minSdkVersion` | `26` | manifest merger conflict |
+| Android Gradle Plugin | `9.1.0`+ (Gradle 9.x) | *"requires Android Gradle plugin 9.1.0 or higher"* |
+| `org.jetbrains.kotlin:kotlin-gradle-plugin:2.4.10` on the app's `buildscript` classpath | — | *"Module was compiled with an incompatible version of Kotlin … metadata is 2.4.0, expected version is 2.2.0"* |
+
+The Kotlin one is the surprising entry: the `inderun-*` artifacts carry Kotlin 2.4.x
+metadata, which the Kotlin plugin AGP brings by default cannot read. The plugin's own build
+hoists a newer KGP for its standalone build, but a consuming app resolves KGP from its own
+buildscript classpath, so the app has to add it too:
+
+```groovy
+// android/build.gradle
+buildscript {
+    dependencies {
+        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.4.10'
+    }
+}
+```
+
+AGP 9 also rejects `getDefaultProguardFile('proguard-android.txt')`; switch to
+`proguard-android-optimize.txt`.
+
+**iOS**: set `IPHONEOS_DEPLOYMENT_TARGET` to `16.0` in your Xcode project **before**
+`npx cap sync ios`. The Capacitor CLI reads that value to generate `CapApp-SPM/Package.swift`,
+so syncing with the default leaves a manifest pinned below this package's floor and the build
+fails with *"requires minimum platform version 16.0 for the iOS platform, but this target
+supports 15.0"*.
+
+## Supported IndeRun Version
+
+This release tracks **IndeRun 0.3.0** on all three platforms:
+
+| Platform | Artifact | Constraint |
+|----------|----------|------------|
+| Web      | `@independo/inderun-web`, `@independo/inderun-contracts` | `0.3.0` (exact) |
+| iOS      | `inderun` SwiftPM package | `>=0.3.0 <0.4.0` |
+| Android  | `app.independo.inderun:inderun-*` | `0.3.0` (exact) |
+
+The npm and Gradle pins are exact and all three are bumped together — a partial bump is how the
+platforms drift apart. The SwiftPM constraint is ranged rather than exact so an app that also depends
+on `inderun` directly can still unify its package graph; it stops at the next minor because that is
+where an 0.x SDK's breaking changes live.
+
+This package versions **independently** of the IndeRun monorepo under plain semver — the numbers are
+unrelated, and this bridge's own version says nothing about which IndeRun release it wraps. Read that
+off the table above.
+
 ## Usage
 
 ```ts
@@ -122,23 +179,55 @@ things are specific to reaching them through a bridge:
 - `createIndeRunCapacitor(options)` — returns a handle that lazily `configure()`s on the first `run()` or `stream()` and memoizes it. Safe to call once at app startup.
 - `run(request)` — Mode 1. Resolves with the canonical IndeRun `TaskResult`.
 - `stream(request)` — Mode 2. Resolves with a `StreamRun` (`handle`, `events`, `cancel`). `events` is single-use.
+- `checkCapabilities()` — every registered provider's static declaration and live availability, without executing a task. Resolves with `ProviderCapabilitySnapshot[]`. Use it for a provider or settings screen; availability changes between calls, so do not cache it across a `run()` or `stream()`.
 - The low-level plugin methods `configure(options)`, `startStream(options)` and `cancelStream(options)` are also exported, along with the listener event names `STREAM_EVENT_NAME` (`"indeRunStreamEvent"`) and `STREAM_ERROR_NAME` (`"indeRunStreamError"`).
 
 > The two listener event names are **public contract**. Native emits exactly these, and an
 > app may attach its own listener to them; renaming one is a breaking change.
 
-The `IndeRunCapacitorPlugin`, `ConfigureOptions`, and `OpenAIProviderBootstrapOptions`
-contracts — including the `openAI` bootstrap config and the web-only
-`allowDirectOpenAIEndpoint` flag — are defined and documented in
-`src/definitions.ts`.
-
-Note one asymmetry in the low-level surface: `run(request)` passes the request at the
-options root, while `startStream({ streamId, request })` nests it, because that envelope
-also carries the bridge-local correlation id. `stream()` hides this.
+The `IndeRunCapacitorPlugin` and `ConfigureOptions` contracts — including the `openAI`,
+`systemModel` and `onnx` bootstrap configs and the `allowDirectOpenAIEndpoint` flag — are
+defined and documented in `src/definitions.ts`.
+
+`systemModel`, `onnx` and `allowDirectOpenAIEndpoint` are **web-only** and ignored on iOS
+and Android, which register their own on-device provider from `configure()` regardless.
+`systemModel` registers the browser-managed on-device provider (Chrome's Prompt API) and is
+what makes `constraints.privacy = "local_required"` routable in a browser. Both on-device
+web providers are Mode 1 only.
+
+`onnx` carries two caveats. It needs the consumer to install the optional
+`@huggingface/transformers` peer dependency — this bridge does not declare it — and to
+supply real model weights, because the web SDK's `runtime` injection seam is a function and
+so cannot cross a JSON bridge hop: only the default Transformers.js runtime is reachable
+through `configure()`, never the fixture runtime the upstream demos use offline. Register it
+only when the weights are there; a provider that cannot load turns a clean routing refusal
+into a provider error.
+
+Two asymmetries in the low-level surface, both hidden by the ergonomic API:
+
+- `run(request)` passes the request at the options root, while
+  `startStream({ streamId, request })` nests it, because that envelope also carries the
+  bridge-local correlation id. `stream()` hides this.
+- The plugin method `checkCapabilities()` resolves `{ providers: [...] }` rather than the
+  array itself, because a Capacitor plugin method cannot resolve a top-level array on
+  either native platform. `IndeRunCapacitor.checkCapabilities()` unwraps it, so app code
+  sees the same array the three platform SDKs return.
+
+`ProviderCapabilitySnapshot` and the `ProviderDescriptor` /
+`ProviderDynamicCapabilities` it contains are declared in `src/definitions.ts` rather than
+imported, because — unlike `TaskRequest` or `StreamEvent` — they are not generated
+contracts: each platform SDK declares its own copy and there is no schema or validator for
+them upstream. `src/web.ts` returns the web SDK's snapshots into the bridge's type uncast,
+so the shapes staying identical is a compile error rather than a convention. Note
+`capabilities.streamingAvailable` and `cancellationAvailable` are **absent**, not `null`,
+when the runtime has nothing to add: absence means *inherit the static declaration*.
 
 ## Platform Notes
 
-- Web requires `openAI` registration because the current web SDK only has the OpenAI-compatible provider.
+- Web requires at least one provider to be registered from `configure()`. The web SDK ships an
+  OpenAI-compatible provider, a Web ONNX Runtime provider and a browser system-model provider, but
+  only the OpenAI-compatible one declares streaming support — so a `local_required` **stream** in a
+  browser is refused at routing time, while a `local_required` **run** can be served on-device.
 - iOS always registers the Apple on-device provider and optionally registers OpenAI when configured.
 - Android always registers the ML Kit on-device provider and optionally registers OpenAI when configured.
 - Keep credentials behind `authContextRef`. That keeps a secret out of the request payload and out

package/android/build.gradle.kts

@@ -10,7 +10,13 @@ buildscript {
 }
 
 plugins {
-    id("com.android.library") version "9.3.1"
+    // No version here on purpose. When a Capacitor app includes this module, AGP is already
+    // on the app's classpath and a versioned request fails with "the plugin is already on the
+    // classpath with an unknown version, so compatibility cannot be checked" — i.e. the plugin
+    // could not be consumed at all. The version for a standalone build of this directory is
+    // declared in settings.gradle's pluginManagement instead, which a consuming app's own
+    // settings file replaces.
+    id("com.android.library")
 }
 
 android {
@@ -37,11 +43,11 @@ dependencies {
     testImplementation("com.capacitorjs:core:8.0.0")
     implementation("androidx.appcompat:appcompat:1.7.1")
     implementation("androidx.core:core-ktx:1.17.0")
-    implementation("app.independo.inderun:inderun-contracts:0.3.0-dev.14")
-    implementation("app.independo.inderun:inderun-core:0.3.0-dev.14")
-    implementation("app.independo.inderun:inderun-kotlin:0.3.0-dev.14")
-    implementation("app.independo.inderun:inderun-mlkit-providers:0.3.0-dev.14")
-    implementation("app.independo.inderun:inderun-openai-providers:0.3.0-dev.14")
+    implementation("app.independo.inderun:inderun-contracts:0.3.0")
+    implementation("app.independo.inderun:inderun-core:0.3.0")
+    implementation("app.independo.inderun:inderun-kotlin:0.3.0")
+    implementation("app.independo.inderun:inderun-mlkit-providers:0.3.0")
+    implementation("app.independo.inderun:inderun-openai-providers:0.3.0")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2")
 
     testImplementation("junit:junit:4.13.2")

package/android/settings.gradle

@@ -4,6 +4,13 @@ pluginManagement {
         mavenCentral()
         gradlePluginPortal()
     }
+
+    // Supplies the version build.gradle.kts deliberately omits, for a standalone build of
+    // this directory (pnpm test:android / verify:android). A Capacitor app that includes the
+    // module uses its own settings file, so AGP comes from the app's classpath there.
+    plugins {
+        id("com.android.library") version "9.3.1"
+    }
 }
 
 dependencyResolutionManagement {

package/android/src/main/kotlin/app/independo/inderun/capacitor/IndeRunCapacitorPlugin.kt

@@ -87,6 +87,41 @@ class IndeRunCapacitorPlugin : Plugin() {
         }
     }
 
+    /**
+     * Reports every registered provider's static declaration and live availability without
+     * executing a task. Availability changes between calls — a local model can unload,
+     * cloud credentials can expire — so callers must not cache it across a run.
+     */
+    @PluginMethod
+    fun checkCapabilities(call: PluginCall) {
+        scope.launch {
+            try {
+                val registry = configuredRegistry
+                    ?: throw toIndeRunException(IllegalStateException("Capacitor IndeRun has not been configured. Configure providers before calling checkCapabilities()."))
+                // IndeRun is stateless; new per call is intentional — registry is cached after configure().
+                val snapshots = IndeRun.initialize(context.applicationContext, registry).checkCapabilities()
+                call.resolve(IndeRunSerializer.encodeCapabilitySnapshots(snapshots))
+            } catch (error: IndeRunException) {
+                val contractError = error.toContractError()
+                call.reject(
+                    contractError.message,
+                    contractError.errorClass.rawValue,
+                    null,
+                    runCatching { IndeRunSerializer.encodeError(contractError) }.getOrNull()
+                )
+            } catch (error: Throwable) {
+                val normalized = toIndeRunException(error)
+                val contractError = normalized.toContractError()
+                call.reject(
+                    contractError.message,
+                    contractError.errorClass.rawValue,
+                    null,
+                    runCatching { IndeRunSerializer.encodeError(contractError) }.getOrNull()
+                )
+            }
+        }
+    }
+
     /**
      * Resolves with the run handle. Only validation and route-selection failures reject;
      * a provider failure, a cancellation, or completion all arrive as the single terminal

package/android/src/main/kotlin/app/independo/inderun/capacitor/IndeRunSerializer.kt

@@ -28,6 +28,9 @@ import app.independo.inderun.contracts.TaskRequestTelemetry
 import app.independo.inderun.contracts.TaskResult
 import app.independo.inderun.contracts.TaskResultTelemetry
 import app.independo.inderun.contracts.TelemetryLevel
+import app.independo.inderun.core.ProviderCapabilitySnapshot
+import app.independo.inderun.core.ProviderDescriptor
+import app.independo.inderun.core.ProviderDynamicCapabilities
 import com.getcapacitor.JSArray
 import com.getcapacitor.JSObject
 import org.json.JSONArray
@@ -113,6 +116,100 @@ object IndeRunSerializer {
         }
     }
 
+    /**
+     * Wire encoding for `checkCapabilities()`.
+     *
+     * Note the enums are written with `.name`, which is the opposite of what
+     * [encodeOutcome] and [encodePhase] below have to do. Those contract enums are
+     * generated without raw values, so their Kotlin constant names are camelCase and the
+     * snake_case wire spelling has to be written by hand. `ProviderDescriptor`'s enums are
+     * declared with the wire spelling *as* the constant name (`in_process`,
+     * `system_service`), so `.name` already is the wire value — and writing them by hand
+     * here would be the thing that eventually drifts.
+     *
+     * The array is wrapped in a `providers` object because a Capacitor `PluginCall` cannot
+     * resolve a top-level array. `IndeRunCapacitor` unwraps it on the JS side.
+     */
+    fun encodeCapabilitySnapshots(snapshots: List<ProviderCapabilitySnapshot>): JSObject {
+        return JSObject().apply {
+            put(
+                "providers",
+                JSArray().apply {
+                    snapshots.forEach { snapshot ->
+                        put(
+                            JSObject().apply {
+                                put("providerId", snapshot.providerId)
+                                put("descriptor", encodeProviderDescriptor(snapshot.descriptor))
+                                put("capabilities", encodeProviderDynamicCapabilities(snapshot.capabilities))
+                            }
+                        )
+                    }
+                }
+            )
+        }
+    }
+
+    private fun encodeProviderDescriptor(descriptor: ProviderDescriptor): JSObject {
+        return JSObject().apply {
+            put("id", descriptor.id)
+            put("type", descriptor.type.name)
+            put("transport", descriptor.transport.name)
+            descriptor.streamingStyle?.let { put("streamingStyle", it.name) }
+            put(
+                "supports",
+                JSObject().apply {
+                    put("run", descriptor.supports.run)
+                    put("streaming", descriptor.supports.streaming)
+                    put("realtime", descriptor.supports.realtime)
+                    put("tools", descriptor.supports.tools)
+                    put("reasoningEvents", descriptor.supports.reasoningEvents)
+                    put("structuredOutput", descriptor.supports.structuredOutput)
+                    put("multimodal", descriptor.supports.multimodal)
+                }
+            )
+            put("cancel", descriptor.cancel.name)
+            put("tasks", JSArray().apply { descriptor.tasks.forEach { put(it) } })
+            descriptor.limits?.let { limits ->
+                put(
+                    "limits",
+                    JSObject().apply {
+                        limits.maxInputTokens?.let { put("maxInputTokens", it) }
+                        limits.maxOutputTokens?.let { put("maxOutputTokens", it) }
+                        limits.maxImageBytes?.let { put("maxImageBytes", it) }
+                        limits.maxAudioSeconds?.let { put("maxAudioSeconds", it) }
+                    }
+                )
+            }
+            descriptor.privacy?.let { privacy ->
+                put(
+                    "privacy",
+                    JSObject().apply {
+                        put("dataLeavesDevice", privacy.dataLeavesDevice)
+                        privacy.regions?.let { regions ->
+                            put("regions", JSArray().apply { regions.forEach { put(it) } })
+                        }
+                    }
+                )
+            }
+        }
+    }
+
+    /**
+     * The three nullable flags are **omitted** rather than written as null. Absence is the
+     * contract's "inherit the static declaration" state — `descriptor.supports.streaming`
+     * for streaming, `descriptor.cancel != none` for cancellation — and a null would be a
+     * third state no consumer has.
+     */
+    private fun encodeProviderDynamicCapabilities(capabilities: ProviderDynamicCapabilities): JSObject {
+        return JSObject().apply {
+            put("available", capabilities.available)
+            capabilities.reason?.let { put("reason", it) }
+            capabilities.streamingAvailable?.let { put("streamingAvailable", it) }
+            capabilities.streamingUnavailableReason?.let { put("streamingUnavailableReason", it) }
+            capabilities.cancellationAvailable?.let { put("cancellationAvailable", it) }
+        }
+    }
+
     fun encodeStreamRunHandle(handle: StreamRunHandle): JSObject {
         return JSObject().apply {
             put("schemaVersion", handle.schemaVersion.rawValue)

package/android/src/test/kotlin/app/independo/inderun/capacitor/IndeRunSerializerCapabilitiesTest.kt

@@ -0,0 +1,253 @@
+package app.independo.inderun.capacitor
+
+import app.independo.inderun.core.ProviderCapabilitySnapshot
+import app.independo.inderun.core.ProviderDescriptor
+import app.independo.inderun.core.ProviderDynamicCapabilities
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class IndeRunSerializerCapabilitiesTest {
+
+    private fun snapshot(
+        providerId: String,
+        type: ProviderDescriptor.ProviderType,
+        transport: ProviderDescriptor.TransportType,
+        streamingStyle: ProviderDescriptor.StreamingStyle? = null,
+        streaming: Boolean,
+        cancel: ProviderDescriptor.CancelSemantics,
+        limits: ProviderDescriptor.ResourceLimits? = null,
+        privacy: ProviderDescriptor.PrivacyDescriptor? = null,
+        capabilities: ProviderDynamicCapabilities
+    ): ProviderCapabilitySnapshot = ProviderCapabilitySnapshot(
+        providerId = providerId,
+        descriptor = ProviderDescriptor(
+            id = providerId,
+            type = type,
+            transport = transport,
+            streamingStyle = streamingStyle,
+            supports = ProviderDescriptor.SupportsCapabilities(
+                run = true,
+                streaming = streaming,
+                realtime = false,
+                tools = false,
+                reasoningEvents = false,
+                structuredOutput = false,
+                multimodal = false
+            ),
+            cancel = cancel,
+            tasks = listOf("text_to_text"),
+            limits = limits,
+            privacy = privacy
+        ),
+        capabilities = capabilities
+    )
+
+    @Test
+    fun `encodeCapabilitySnapshots wraps the snapshots in a providers array`() {
+        val encoded = IndeRunSerializer.encodeCapabilitySnapshots(
+            listOf(
+                snapshot(
+                    providerId = "openai",
+                    type = ProviderDescriptor.ProviderType.cloud,
+                    transport = ProviderDescriptor.TransportType.http,
+                    streamingStyle = ProviderDescriptor.StreamingStyle.tokens,
+                    streaming = true,
+                    cancel = ProviderDescriptor.CancelSemantics.hard,
+                    limits = ProviderDescriptor.ResourceLimits(
+                        maxInputTokens = 128_000,
+                        maxOutputTokens = 4_096
+                    ),
+                    privacy = ProviderDescriptor.PrivacyDescriptor(
+                        dataLeavesDevice = true,
+                        regions = listOf("us")
+                    ),
+                    capabilities = ProviderDynamicCapabilities(available = true)
+                )
+            )
+        )
+
+        val providers = encoded.getJSONArray("providers")
+        assertEquals(1, providers.length())
+
+        val provider = providers.getJSONObject(0)
+        assertEquals("openai", provider.getString("providerId"))
+
+        val descriptor = provider.getJSONObject("descriptor")
+        assertEquals("openai", descriptor.getString("id"))
+        assertEquals("cloud", descriptor.getString("type"))
+        assertEquals("http", descriptor.getString("transport"))
+        assertEquals("tokens", descriptor.getString("streamingStyle"))
+        assertEquals("hard", descriptor.getString("cancel"))
+        assertEquals(1, descriptor.getJSONArray("tasks").length())
+        assertEquals("text_to_text", descriptor.getJSONArray("tasks").getString(0))
+
+        val supports = descriptor.getJSONObject("supports")
+        assertTrue(supports.getBoolean("run"))
+        assertTrue(supports.getBoolean("streaming"))
+        assertFalse(supports.getBoolean("realtime"))
+        assertFalse(supports.getBoolean("tools"))
+        assertFalse(supports.getBoolean("reasoningEvents"))
+        assertFalse(supports.getBoolean("structuredOutput"))
+        assertFalse(supports.getBoolean("multimodal"))
+
+        val limits = descriptor.getJSONObject("limits")
+        assertEquals(128_000, limits.getInt("maxInputTokens"))
+        assertEquals(4_096, limits.getInt("maxOutputTokens"))
+        assertFalse(limits.has("maxImageBytes"))
+        assertFalse(limits.has("maxAudioSeconds"))
+
+        val privacy = descriptor.getJSONObject("privacy")
+        assertTrue(privacy.getBoolean("dataLeavesDevice"))
+        assertEquals("us", privacy.getJSONArray("regions").getString(0))
+
+        assertTrue(provider.getJSONObject("capabilities").getBoolean("available"))
+    }
+
+    /**
+     * `in_process` and `system_service` are the two descriptor constants a future upstream
+     * rename to camelCase would silently corrupt on the wire, because the TypeScript union
+     * in src/definitions.ts spells them out. Asserting the literals is the guard.
+     */
+    @Test
+    fun `encodeCapabilitySnapshots writes snake case transport constants verbatim`() {
+        val encoded = IndeRunSerializer.encodeCapabilitySnapshots(
+            listOf(
+                snapshot(
+                    providerId = "local.onnx.genai.android",
+                    type = ProviderDescriptor.ProviderType.local,
+                    transport = ProviderDescriptor.TransportType.in_process,
+                    streaming = false,
+                    cancel = ProviderDescriptor.CancelSemantics.soft,
+                    capabilities = ProviderDynamicCapabilities(
+                        available = false,
+                        reason = "No model package configured."
+                    )
+                ),
+                snapshot(
+                    providerId = "android.mlkit.genai",
+                    type = ProviderDescriptor.ProviderType.local,
+                    transport = ProviderDescriptor.TransportType.system_service,
+                    streamingStyle = ProviderDescriptor.StreamingStyle.chunks,
+                    streaming = true,
+                    cancel = ProviderDescriptor.CancelSemantics.soft,
+                    capabilities = ProviderDynamicCapabilities(available = true)
+                )
+            )
+        )
+
+        val providers = encoded.getJSONArray("providers")
+        assertEquals(
+            "in_process",
+            providers.getJSONObject(0).getJSONObject("descriptor").getString("transport")
+        )
+        assertEquals(
+            "system_service",
+            providers.getJSONObject(1).getJSONObject("descriptor").getString("transport")
+        )
+        assertEquals(
+            "chunks",
+            providers.getJSONObject(1).getJSONObject("descriptor").getString("streamingStyle")
+        )
+    }
+
+    /**
+     * Absence is the contract's "inherit the static declaration" state, so the nullable
+     * flags must not reach the wire as nulls — a null would be a third state no consumer
+     * has. Same for the optional descriptor sub-objects.
+     */
+    @Test
+    fun `encodeCapabilitySnapshots omits unset optional fields instead of writing null`() {
+        val encoded = IndeRunSerializer.encodeCapabilitySnapshots(
+            listOf(
+                snapshot(
+                    providerId = "android.mlkit.genai",
+                    type = ProviderDescriptor.ProviderType.local,
+                    transport = ProviderDescriptor.TransportType.system_service,
+                    streaming = true,
+                    cancel = ProviderDescriptor.CancelSemantics.soft,
+                    capabilities = ProviderDynamicCapabilities(available = true)
+                )
+            )
+        )
+
+        val provider = encoded.getJSONArray("providers").getJSONObject(0)
+        val descriptor = provider.getJSONObject("descriptor")
+        assertFalse(descriptor.has("streamingStyle"))
+        assertFalse(descriptor.has("limits"))
+        assertFalse(descriptor.has("privacy"))
+
+        val capabilities = provider.getJSONObject("capabilities")
+        assertFalse(capabilities.has("reason"))
+        assertFalse(capabilities.has("streamingAvailable"))
+        assertFalse(capabilities.has("streamingUnavailableReason"))
+        assertFalse(capabilities.has("cancellationAvailable"))
+    }
+
+    @Test
+    fun `encodeCapabilitySnapshots encodes streaming taken away at runtime`() {
+        val encoded = IndeRunSerializer.encodeCapabilitySnapshots(
+            listOf(
+                snapshot(
+                    providerId = "openai",
+                    type = ProviderDescriptor.ProviderType.cloud,
+                    transport = ProviderDescriptor.TransportType.http,
+                    streamingStyle = ProviderDescriptor.StreamingStyle.tokens,
+                    streaming = true,
+                    cancel = ProviderDescriptor.CancelSemantics.hard,
+                    capabilities = ProviderDynamicCapabilities(
+                        available = true,
+                        streamingAvailable = false,
+                        streamingUnavailableReason = "Host has no streaming HTTP client.",
+                        cancellationAvailable = true
+                    )
+                )
+            )
+        )
+
+        val capabilities = encoded.getJSONArray("providers")
+            .getJSONObject(0)
+            .getJSONObject("capabilities")
+        assertTrue(capabilities.getBoolean("available"))
+        assertFalse(capabilities.getBoolean("streamingAvailable"))
+        assertEquals(
+            "Host has no streaming HTTP client.",
+            capabilities.getString("streamingUnavailableReason")
+        )
+        assertTrue(capabilities.getBoolean("cancellationAvailable"))
+    }
+
+    @Test
+    fun `encodeCapabilitySnapshots encodes an empty registry as an empty array`() {
+        val encoded = IndeRunSerializer.encodeCapabilitySnapshots(emptyList())
+
+        assertTrue(encoded.has("providers"))
+        assertEquals(0, encoded.getJSONArray("providers").length())
+    }
+
+    /**
+     * Every enum constant of every descriptor enum maps to the wire spelling the
+     * TypeScript unions declare. Exhaustive by construction: `values()` grows when
+     * upstream adds a constant, and a renamed one fails here rather than in a demo.
+     */
+    @Test
+    fun `every descriptor enum constant maps to its declared wire value`() {
+        assertEquals(
+            listOf("local", "edge", "cloud"),
+            ProviderDescriptor.ProviderType.values().map { it.name }
+        )
+        assertEquals(
+            listOf("in_process", "system_service", "http", "sse", "realtime"),
+            ProviderDescriptor.TransportType.values().map { it.name }
+        )
+        assertEquals(
+            listOf("tokens", "chunks", "snapshots"),
+            ProviderDescriptor.StreamingStyle.values().map { it.name }
+        )
+        assertEquals(
+            listOf("hard", "soft", "none"),
+            ProviderDescriptor.CancelSemantics.values().map { it.name }
+        )
+    }
+}