@dvai-bridge/android 4.0.0

package/android/src/main/java/co/deepvoiceai/bridge/license/LicenseValidator.kt

@@ -0,0 +1,400 @@
+package co.deepvoiceai.bridge.license
+
+import android.content.Context
+import android.util.Base64
+import com.nimbusds.jose.JOSEException
+import com.nimbusds.jose.JWSAlgorithm
+import com.nimbusds.jose.crypto.ECDSAVerifier
+import com.nimbusds.jose.jwk.Curve
+import com.nimbusds.jose.jwk.ECKey
+import com.nimbusds.jose.util.Base64URL
+import com.nimbusds.jwt.SignedJWT
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import org.json.JSONObject
+import java.text.ParseException
+import java.util.Date
+
+/**
+ * DVAI-Bridge license validator — offline JWT verification.
+ *
+ * Kotlin port of `packages/dvai-bridge-core/src/license/LicenseValidator.ts`.
+ * Verifies a JWT (header + payload + ECDSA P-256 signature) using
+ * `nimbus-jose-jwt`. The SDK ships only with public keys (see
+ * [DvaiPublicKeys]) and cannot itself produce valid licenses — so
+ * reverse-engineering the bundled APK gains nothing.
+ *
+ * Network calls: zero. The whole flow is offline by design — there's
+ * no "phone home" step, no license server polling, no DRM beacon.
+ *
+ * Android divergence from the JS validator: in production (non-DEBUG)
+ * Android builds, both [validateAndAssert] and the SDK's `start(...)`
+ * THROW [LicenseRequiredError] rather than falling back to a watermarked
+ * free-tier. This matches the iOS validator and the BSL 1.1 commercial
+ * enforcement story for native mobile distributions.
+ *
+ * @param context              Application context (typically
+ *                             `applicationContext`). Required for audience
+ *                             detection (package name) and discovery
+ *                             (assets, raw resources, internal storage).
+ * @param token                Pre-loaded JWT string. If non-null, skips all
+ *                             auto-discovery.
+ * @param path                 Explicit license file path. Overrides
+ *                             auto-discovery if non-null.
+ * @param hostBuildConfigDebug The host app's `BuildConfig.DEBUG` value. Pass
+ *                             this from `Application.onCreate()` so the
+ *                             validator can bypass enforcement on debug builds.
+ *                             Falls back to `ApplicationInfo.FLAG_DEBUGGABLE`
+ *                             if null.
+ * @param publicKeys           Override for the public-key registry. Defaults
+ *                             to [DvaiPublicKeys.REGISTRY]. Tests inject
+ *                             their own keypair so they can sign + verify
+ *                             against a deterministic key without polluting
+ *                             the production registry.
+ * @param allowPlaceholderKey  If true, accept tokens signed under
+ *                             [PLACEHOLDER_KID]. Off by default — a real
+ *                             production build must replace the placeholder
+ *                             with a generated key. Tests set this to true.
+ */
+class LicenseValidator(
+    private val context: Context,
+    private val token: String? = null,
+    private val path: String? = null,
+    private val hostBuildConfigDebug: Boolean? = null,
+    private val publicKeys: Map<String, DvaiPublicKeyJwk> = DvaiPublicKeys.REGISTRY,
+    private val allowPlaceholderKey: Boolean = false,
+) {
+    /**
+     * Validate WITHOUT throwing. Returns a [LicenseStatus] describing what
+     * the validator determined; never throws on missing / invalid /
+     * expired licenses. Useful for host-app dashboards that want to
+     * display the licensee / expiry / fallback reason without halting
+     * SDK startup, and for tests.
+     *
+     * Idempotent; safe to call multiple times.
+     */
+    suspend fun validate(): LicenseStatus = withContext(Dispatchers.IO) {
+        // 1. Dev-mode bypass — license required only in production.
+        val dev = detectDevMode(context, hostBuildConfigDebug)
+        if (dev.isDev) {
+            return@withContext LicenseStatus.FreeDev(dev.reason)
+        }
+
+        // 2. Discover the token. Returns null when no license source is
+        //    configured AND auto-discovery fails.
+        val discovered = discoverLicenseToken(
+            context,
+            LicenseDiscoveryOptions(token = token, path = path),
+        )
+        if (discovered == null) {
+            return@withContext LicenseStatus.FreeProd(
+                "no license token found; checked config.licenseToken, " +
+                    "config.licenseKeyPath, DVAI_LICENSE_PATH env, " +
+                    "DVAI_LICENSE_TOKEN env, assets/$DEFAULT_LICENSE_FILENAME, " +
+                    "res/raw/$DEFAULT_LICENSE_RAW_RESOURCE_NAME, " +
+                    "and filesDir/$DEFAULT_LICENSE_FILENAME",
+            )
+        }
+
+        // 3. Verify signature + claims with nimbus-jose-jwt.
+        verifyToken(discovered.token, detectPlatform(), detectAudience(context))
+    }
+
+    /**
+     * Strict validation entry point used by the SDK at startup. Returns
+     * [LicenseStatus] on success ([LicenseStatus.Commercial],
+     * [LicenseStatus.Trial], [LicenseStatus.FreeDev]) and THROWS
+     * [LicenseRequiredError] on [LicenseStatus.FreeProd] /
+     * [LicenseStatus.FreeExpired].
+     *
+     * This is the BSL 1.1 enforcement point: in production / release
+     * builds (any non-dev-mode environment), the SDK refuses to operate
+     * without a valid commercial or trial license. Developers running on
+     * debug builds / `BuildConfig.DEBUG=true` / explicit DVAI_FORCE_DEV
+     * are unaffected — those return a [LicenseStatus.FreeDev] status and
+     * the SDK proceeds normally.
+     *
+     * Use [validate] instead when you want to inspect the status without
+     * halting startup (host-app dashboards, test fixtures).
+     */
+    suspend fun validateAndAssert(): LicenseStatus {
+        val status = validate()
+        when (status) {
+            is LicenseStatus.FreeProd ->
+                throw LicenseRequiredError(buildRequiredErrorMessage(status), status)
+            is LicenseStatus.FreeExpired ->
+                throw LicenseRequiredError(buildRequiredErrorMessage(status), status)
+            else -> return status
+        }
+    }
+
+    private fun verifyToken(
+        token: String,
+        platform: DvaiPlatform,
+        runtimeAudience: String?,
+    ): LicenseStatus {
+        // Parse the JWT structure first so we can read the header to pick
+        // the right public key. We could let nimbus iterate but specifying
+        // the key up-front gives clearer error messages on misses.
+        val parts = token.split(".")
+        if (parts.size != 3 || parts[0].isEmpty()) {
+            return LicenseStatus.FreeProd(
+                "license token is not a well-formed JWT (need 3 segments)",
+            )
+        }
+
+        val headerJson: JSONObject = try {
+            JSONObject(base64UrlDecodeUtf8(parts[0]))
+        } catch (e: Throwable) {
+            return LicenseStatus.FreeProd(
+                "license token header is not parseable JSON: ${e.message ?: e.javaClass.simpleName}",
+            )
+        }
+
+        val alg = headerJson.optString("alg", "")
+        if (alg != "ES256") {
+            // Refuse `alg: none` and any non-ES256 algorithm. Critical
+            // defense against the classic JWT algorithm-confusion vulnerability.
+            return LicenseStatus.FreeProd(
+                "license token uses unsupported alg \"${alg.ifEmpty { "(missing)" }}\", expected ES256",
+            )
+        }
+
+        val kid = headerJson.optString("kid", "")
+        if (kid.isEmpty()) {
+            return LicenseStatus.FreeProd(
+                "license token header missing kid; cannot select verification key",
+            )
+        }
+
+        val jwk = publicKeys[kid]
+            ?: return LicenseStatus.FreeProd(
+                "license token kid \"$kid\" is not in the SDK's public-key " +
+                    "registry; either the key was rotated and you're on an old SDK, " +
+                    "or the token was signed with a key we don't recognise",
+            )
+
+        if (kid == PLACEHOLDER_KID && !allowPlaceholderKey) {
+            return LicenseStatus.FreeProd(
+                "license token signed with the placeholder key (kid \"$PLACEHOLDER_KID\"); " +
+                    "replace the placeholder in PublicKeys.kt with a real key generated " +
+                    "via scripts/license/generate-keypair.mjs before issuing real licenses",
+            )
+        }
+
+        // Parse the JWT structure (header / payload / signature) with nimbus.
+        val signed: SignedJWT = try {
+            SignedJWT.parse(token)
+        } catch (e: ParseException) {
+            return LicenseStatus.FreeProd(
+                "license token verification failed: ${e.message ?: "parse error"}",
+            )
+        }
+
+        // Verify signature. Build the public ECKey from the JWK coordinate
+        // strings (x / y). nimbus expects `Base64URL`-wrapped strings — they're
+        // already base64url-encoded in the JWK, so we just rehydrate.
+        val ecKey: ECKey = try {
+            ECKey.Builder(Curve.P_256, Base64URL(jwk.x), Base64URL(jwk.y))
+                .keyID(jwk.kid ?: kid)
+                .build()
+        } catch (e: Throwable) {
+            return LicenseStatus.FreeProd(
+                "license public-key entry is malformed: ${e.message ?: e.javaClass.simpleName}",
+            )
+        }
+
+        try {
+            if (signed.header.algorithm != JWSAlgorithm.ES256) {
+                // Defense-in-depth — we already checked the header above,
+                // but nimbus might surface its own opinion about the alg.
+                return LicenseStatus.FreeProd(
+                    "license token uses unsupported alg \"${signed.header.algorithm}\", expected ES256",
+                )
+            }
+            val verifier = ECDSAVerifier(ecKey)
+            if (!signed.verify(verifier)) {
+                return LicenseStatus.FreeProd(
+                    "license token signature did not verify against kid \"$kid\"; " +
+                        "the token may have been tampered with or was signed by a different key",
+                )
+            }
+        } catch (e: JOSEException) {
+            return LicenseStatus.FreeProd(
+                "license token verification failed: ${e.message ?: e.javaClass.simpleName}",
+            )
+        } catch (e: Throwable) {
+            return LicenseStatus.FreeProd(
+                "license token verification failed: ${e.message ?: e.javaClass.simpleName}",
+            )
+        }
+
+        // Coerce + validate the payload shape ourselves. nimbus' claim
+        // set is loose-typed JSON; we want strict checks with specific
+        // free-prod reasons.
+        val claims = signed.jwtClaimsSet
+        val payload = parsePayload(claims.toJSONObject())
+            ?: return LicenseStatus.FreeProd(
+                "license token payload missing required DVAI fields (tier/platforms/aud/licensee)",
+            )
+
+        // Issuer check.
+        if (payload.iss != "DVAI-Bridge") {
+            return LicenseStatus.FreeProd(
+                "license token claim \"iss\" failed: expected \"DVAI-Bridge\", got \"${payload.iss}\"",
+            )
+        }
+
+        // Expiry check. Surface "free-expired" specifically so the developer
+        // knows whose renewal to chase.
+        val nowSec = System.currentTimeMillis() / 1000
+        if (payload.exp <= nowSec) {
+            return LicenseStatus.FreeExpired(
+                licensee = payload.licensee,
+                expiredAt = payload.exp,
+            )
+        }
+
+        // Platform check.
+        if (!payload.platforms.contains(platform.wire)) {
+            return LicenseStatus.FreeProd(
+                "license token does not authorise platform \"${platform.wire}\"; " +
+                    "the token covers [${payload.platforms.joinToString(", ")}]",
+            )
+        }
+
+        // Audience check.
+        val matched = matchAudience(runtimeAudience, payload.aud)
+            ?: return LicenseStatus.FreeProd(
+                "license token's audience entries [${payload.aud.joinToString(", ")}] " +
+                    "do not match the current runtime audience \"${runtimeAudience ?: "(none)"}\"" +
+                    if (runtimeAudience == null) {
+                        " — set DVAI_AUDIENCE in your environment, or use a \"*\" aud entry for any-domain licenses"
+                    } else {
+                        ""
+                    },
+            )
+
+        return when (payload.tier) {
+            "commercial" -> LicenseStatus.Commercial(
+                licensee = payload.licensee,
+                expiresAt = payload.exp,
+                platform = platform,
+                audienceMatched = matched,
+            )
+            "trial" -> LicenseStatus.Trial(
+                licensee = payload.licensee,
+                expiresAt = payload.exp,
+                platform = platform,
+                audienceMatched = matched,
+            )
+            else -> LicenseStatus.FreeProd(
+                "license token payload missing required DVAI fields (tier/platforms/aud/licensee)",
+            )
+        }
+    }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Helpers                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Parse the JWT payload into a [DvaiLicensePayload], or return null if any
+ * required field is missing/malformed. Mirrors `isLicensePayload` on the JS side.
+ */
+private fun parsePayload(claims: Map<String, Any?>): DvaiLicensePayload? {
+    val iss = claims["iss"] as? String ?: return null
+    val sub = claims["sub"] as? String ?: return null
+    val tier = claims["tier"] as? String ?: return null
+    if (tier != "commercial" && tier != "trial") return null
+    val licensee = claims["licensee"] as? String ?: return null
+
+    // `aud` can be either a JSON array (the canonical form) or a single
+    // string (nimbus sometimes single-unwraps single-element audiences).
+    // We coerce both into a List<String>.
+    val audRaw = claims["aud"]
+    val aud: List<String> = when (audRaw) {
+        is List<*> -> audRaw.filterIsInstance<String>().also {
+            if (it.size != audRaw.size) return null
+        }
+        is String -> listOf(audRaw)
+        else -> return null
+    }
+
+    val platformsRaw = claims["platforms"] as? List<*> ?: return null
+    val platforms = platformsRaw.filterIsInstance<String>()
+    if (platforms.size != platformsRaw.size) return null
+
+    // `iat` / `exp` are seconds-since-epoch integers in our JWTs, but
+    // nimbus' parser may surface them as Date or Number. Coerce both.
+    val iat = coerceEpochSeconds(claims["iat"]) ?: return null
+    val exp = coerceEpochSeconds(claims["exp"]) ?: return null
+
+    return DvaiLicensePayload(
+        iss = iss,
+        sub = sub,
+        aud = aud,
+        tier = tier,
+        platforms = platforms,
+        licensee = licensee,
+        iat = iat,
+        exp = exp,
+    )
+}
+
+private fun coerceEpochSeconds(v: Any?): Long? = when (v) {
+    is Number -> v.toLong()
+    is Date -> v.time / 1000
+    else -> null
+}
+
+/** Decode base64url-encoded JSON header to a UTF-8 string. */
+private fun base64UrlDecodeUtf8(s: String): String {
+    val bytes = Base64.decode(s, Base64.URL_SAFE or Base64.NO_WRAP)
+    return String(bytes, Charsets.UTF_8)
+}
+
+/**
+ * Build the developer-facing error message for [LicenseRequiredError].
+ * Intentionally verbose — mirrors the JS side's multi-line format with
+ * Android-specific resolution paths.
+ */
+internal fun buildRequiredErrorMessage(status: LicenseStatus): String {
+    val header =
+        "\n" +
+            "DVAI-Bridge Commercial License Required\n" +
+            "=======================================\n"
+
+    val reason = when (status) {
+        is LicenseStatus.FreeExpired ->
+            "License for \"${status.licensee}\" expired at ${Date(status.expiredAt * 1000)}."
+        is LicenseStatus.FreeProd -> status.reason
+        else -> "(unknown status)"
+    }
+
+    val remediation =
+        "\n" +
+            "This SDK is licensed under BSL 1.1 and requires a valid commercial\n" +
+            "or trial license to run in production / release builds.\n" +
+            "\n" +
+            "To resolve:\n" +
+            "  1. Obtain a license at https://deepvoiceai.com/dvai-bridge/license\n" +
+            "  2. Place the file at one of these locations (any will work):\n" +
+            "       - assets/dvai-license.jwt           (bundled in the APK; auto-discovered)\n" +
+            "       - res/raw/dvai_license              (bundled raw resource; auto-discovered)\n" +
+            "       - filesDir/dvai-license.jwt         (internal storage; auto-discovered)\n" +
+            "       - the path you pass as StartOptions.licenseKeyPath\n" +
+            "       - the path in \$DVAI_LICENSE_PATH\n" +
+            "       - inline JWT in StartOptions.licenseToken or \$DVAI_LICENSE_TOKEN\n" +
+            "  3. Re-run.\n" +
+            "\n" +
+            "Developing locally? The SDK auto-detects dev mode on:\n" +
+            "  - BuildConfig.DEBUG=true (pass hostBuildConfigDebug through StartOptions)\n" +
+            "  - apps installed with ApplicationInfo.FLAG_DEBUGGABLE\n" +
+            "  - DVAI_FORCE_DEV=1 environment variable (explicit override)\n" +
+            "Any of these silences this error and lets the SDK run without a\n" +
+            "license.\n"
+
+    return header + "\n" + reason + "\n" + remediation
+}

package/android/src/main/java/co/deepvoiceai/bridge/license/PublicKeys.kt

@@ -0,0 +1,91 @@
+package co.deepvoiceai.bridge.license
+
+/**
+ * Public-key registry for DVAI-Bridge license JWT verification.
+ *
+ * Kotlin port of `packages/dvai-bridge-core/src/license/publicKeys.ts` — semantics
+ * and registry contents are 1:1 with the JS side. The same JWT format and the
+ * same kids work across the JS, iOS, and Android validators.
+ *
+ * Each entry is keyed by `kid` (key id, written by the license generator
+ * into the JWT header). The SDK looks up the matching entry by kid when
+ * verifying a license token. Multiple entries can coexist so that key
+ * rotation is non-disruptive: ship the new key in a release alongside
+ * the old, leave the old in place for ~12 months while previously-
+ * issued licenses naturally expire or get re-issued, then prune.
+ *
+ * THE PRIVATE KEY DOES NOT LIVE HERE. It belongs in your secrets
+ * manager (1Password / AWS Secrets Manager / Vault), accessible only
+ * to the license-generator service that produces signed JWTs. The
+ * mathematics of ECDSA P-256 guarantee that a holder of the public
+ * key alone cannot forge a signature.
+ */
+
+/** ES256 (P-256 ECDSA) public key in JWK form. */
+data class DvaiPublicKeyJwk(
+    val kty: String = "EC",
+    val crv: String = "P-256",
+    val x: String,
+    val y: String,
+    val alg: String? = "ES256",
+    val use: String? = "sig",
+    val kid: String? = null,
+)
+
+/**
+ * `kid` reserved for the placeholder key. The validator refuses to
+ * accept tokens signed with this kid unless the caller explicitly opts
+ * in (`allowPlaceholderKey = true` passed to the validator constructor,
+ * used by tests and by the sample license printed by the keypair-
+ * generator script).
+ */
+const val PLACEHOLDER_KID: String = "placeholder-do-not-ship"
+
+/**
+ * Registry mapping `kid` → public key JWK.
+ *
+ * The entry below is a **placeholder** — it is a published, well-known
+ * test keypair and DOES NOT verify any real production license. Before
+ * shipping licenses to customers, replace it with the output of
+ * `scripts/license/generate-keypair.mjs`. The SDK refuses to validate
+ * licenses against the placeholder kid unless `allowPlaceholderKey` is
+ * set (test-only escape hatch).
+ *
+ * To add a new key for rotation, add a second entry keyed by the new
+ * `kid`; old licenses keep verifying against the old key, new licenses
+ * (issued by the generator that knows the new private key) verify
+ * against the new entry.
+ */
+object DvaiPublicKeys {
+    /** Production registry. Mirrors `DVAI_PUBLIC_KEYS` on the JS side. */
+    val REGISTRY: Map<String, DvaiPublicKeyJwk> = mapOf(
+        // Production key, kid `2026-05`. Generated 2026-05-15 by
+        // scripts/license/generate-keypair.mjs. The matching private
+        // key lives in the operator's secrets manager.
+        "2026-05" to DvaiPublicKeyJwk(
+            kty = "EC",
+            crv = "P-256",
+            x = "2Y8TuhnlE4tiVDtliozYTgc1TAqi4_TBTI6FHe1p_Vw",
+            y = "pyxMJHj10HPe2hnpJvMpnZ4AzpYZRfqGEMhpBr1-Oto",
+            alg = "ES256",
+            use = "sig",
+            kid = "2026-05",
+        ),
+        // PLACEHOLDER — used by the SDK's own unit tests and by the
+        // sample license printed by `generate-keypair.mjs`. The
+        // validator REFUSES to accept tokens signed under this kid
+        // unless `allowPlaceholderKey = true` is passed to the
+        // validator constructor (test-only escape hatch). Safe to keep
+        // in production builds; remove only if you want test fixtures
+        // to stop working.
+        PLACEHOLDER_KID to DvaiPublicKeyJwk(
+            kty = "EC",
+            crv = "P-256",
+            x = "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
+            y = "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
+            alg = "ES256",
+            use = "sig",
+            kid = PLACEHOLDER_KID,
+        ),
+    )
+}

package/android/src/test/java/co/deepvoiceai/bridge/BackendSelectorTest.kt

@@ -0,0 +1,76 @@
+package co.deepvoiceai.bridge
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import java.io.File
+import java.nio.file.Files
+
+class BackendSelectorTest {
+    @Test
+    fun `explicit backend bypasses resolution`() {
+        for (kind in listOf(BackendKind.Llama, BackendKind.MediaPipe, BackendKind.LiteRT)) {
+            val opts = StartOptions(backend = kind, modelPath = "/tmp/x.gguf")
+            assertEquals(kind, BackendSelector.resolve(opts))
+        }
+    }
+
+    @Test
+    fun `auto with task suffix and existing file resolves to MediaPipe`() {
+        val tmp = Files.createTempFile("dvai-test", ".task").toFile()
+        try {
+            val opts = StartOptions(backend = BackendKind.Auto, modelPath = tmp.absolutePath)
+            assertEquals(BackendKind.MediaPipe, BackendSelector.resolve(opts))
+        } finally {
+            tmp.delete()
+        }
+    }
+
+    @Test
+    fun `auto with task suffix but missing file falls through to llama`() {
+        val opts = StartOptions(
+            backend = BackendKind.Auto,
+            modelPath = "/tmp/does-not-exist-${System.nanoTime()}.task",
+        )
+        assertEquals(BackendKind.Llama, BackendSelector.resolve(opts))
+    }
+
+    @Test
+    fun `auto with tflite suffix resolves to LiteRT`() {
+        val opts = StartOptions(backend = BackendKind.Auto, modelPath = "/tmp/x.tflite")
+        assertEquals(BackendKind.LiteRT, BackendSelector.resolve(opts))
+    }
+
+    @Test
+    fun `auto with litertlm suffix resolves to LiteRT`() {
+        val opts = StartOptions(backend = BackendKind.Auto, modelPath = "/tmp/x.litertlm")
+        assertEquals(BackendKind.LiteRT, BackendSelector.resolve(opts))
+    }
+
+    @Test
+    fun `auto with gguf suffix resolves to Llama`() {
+        val opts = StartOptions(backend = BackendKind.Auto, modelPath = "/tmp/x.gguf")
+        assertEquals(BackendKind.Llama, BackendSelector.resolve(opts))
+    }
+
+    @Test
+    fun `auto with no modelPath defaults to Llama`() {
+        val opts = StartOptions(backend = BackendKind.Auto, modelPath = null)
+        assertEquals(BackendKind.Llama, BackendSelector.resolve(opts))
+    }
+
+    @Test
+    fun `auto with unknown extension defaults to Llama`() {
+        val opts = StartOptions(backend = BackendKind.Auto, modelPath = "/tmp/something.bin")
+        assertEquals(BackendKind.Llama, BackendSelector.resolve(opts))
+    }
+
+    @Test
+    fun `BackendKind enum order matches iOS counterpart`() {
+        // Cross-platform spec compliance — the iOS DVAIBridge.BackendKind
+        // declares cases in the same order: Auto, Llama, MediaPipe, LiteRT.
+        // (Foundation / CoreML / MLX are iOS-only and don't appear here.)
+        val expected = listOf("Auto", "Llama", "MediaPipe", "LiteRT")
+        val actual = BackendKind.values().map { it.name }
+        assertEquals(expected, actual)
+    }
+}

package/android/src/test/java/co/deepvoiceai/bridge/CapabilityPrecheckTest.kt

@@ -0,0 +1,117 @@
+package co.deepvoiceai.bridge
+
+import co.deepvoiceai.bridge.shared.core.capability.CapabilityPrecheck
+import co.deepvoiceai.bridge.shared.core.capability.CpuClass
+import co.deepvoiceai.bridge.shared.core.capability.DeviceCapabilityHints
+import co.deepvoiceai.bridge.shared.core.capability.GpuClass
+import co.deepvoiceai.bridge.shared.core.capability.PrecheckMode
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+import org.robolectric.annotation.Config
+
+/**
+ * v3.2 — pre-init capability gate (Kotlin).
+ *
+ * Mirrors `packages/dvai-bridge-core/src/__tests__/precheck.test.ts`
+ * one-to-one. Same hints, same expected modes — guarantees that the
+ * Android SDK and the TS core agree on what's a "too-weak" or
+ * "offload-only" device for a given hardware shape.
+ *
+ * Heuristic-only: no real device call. Pass [DeviceCapabilityHints]
+ * directly to [CapabilityPrecheck.assess] via the `hints` override.
+ * Robolectric provides the ApplicationContext (the assess() function
+ * needs one even when hints are pre-supplied — for consistency with
+ * the auto-detect path).
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class CapabilityPrecheckTest {
+
+    private val ctx: android.content.Context get() = RuntimeEnvironment.getApplication()
+
+    private val highEndDesktop = DeviceCapabilityHints(
+        hasNpu = false, ramGb = 32, gpuClass = GpuClass.DISCRETE, cpuClass = CpuClass.HIGH,
+    )
+    private val appleSiliconLaptop = DeviceCapabilityHints(
+        hasNpu = true, ramGb = 16, gpuClass = GpuClass.APPLE_SILICON, cpuClass = CpuClass.HIGH,
+    )
+    private val midRangeLaptop = DeviceCapabilityHints(
+        hasNpu = false, ramGb = 8, gpuClass = GpuClass.INTEGRATED, cpuClass = CpuClass.MID,
+    )
+    private val lowEndLaptop = DeviceCapabilityHints(
+        hasNpu = false, ramGb = 4, gpuClass = GpuClass.INTEGRATED, cpuClass = CpuClass.LOW,
+    )
+    private val veryWeakDevice = DeviceCapabilityHints(
+        hasNpu = false, ramGb = 2, gpuClass = GpuClass.NONE, cpuClass = CpuClass.LOW,
+    )
+
+    @Test
+    fun `high-end desktop classifies as OK`() {
+        val result = CapabilityPrecheck.assess(ctx, hints = highEndDesktop)
+        assertEquals(PrecheckMode.OK, result.mode)
+        assertTrue("expected > 10 tok/s, got ${result.tokPerSec}", result.tokPerSec > 10.0)
+    }
+
+    @Test
+    fun `Apple Silicon classifies as OK`() {
+        val result = CapabilityPrecheck.assess(ctx, hints = appleSiliconLaptop)
+        assertEquals(PrecheckMode.OK, result.mode)
+    }
+
+    @Test
+    fun `mid-range laptop classifies as OFFLOAD_ONLY at default thresholds`() {
+        // 8 (integrated) * 1.0 (mid CPU) * 1.0 (8 GB RAM) * 1.0 (no NPU) = 8 tok/s
+        // Above hardwareMinimum (3), below minLocalCapability (10) ⇒ offload-only.
+        val result = CapabilityPrecheck.assess(ctx, hints = midRangeLaptop)
+        assertEquals(PrecheckMode.OFFLOAD_ONLY, result.mode)
+        assertEquals(8.0, result.tokPerSec, 0.01)
+    }
+
+    @Test
+    fun `low-end laptop classifies as OFFLOAD_ONLY`() {
+        // 8 * 0.6 * 0.7 = 3.4 tok/s ⇒ above floor (3), below comfort (10).
+        val result = CapabilityPrecheck.assess(ctx, hints = lowEndLaptop)
+        assertEquals(PrecheckMode.OFFLOAD_ONLY, result.mode)
+    }
+
+    @Test
+    fun `very-weak device classifies as TOO_WEAK`() {
+        // 3 (no GPU) * 0.6 (low CPU) * 0.3 (RAM < 4) = 0.5 tok/s ⇒ too-weak.
+        val result = CapabilityPrecheck.assess(ctx, hints = veryWeakDevice)
+        assertEquals(PrecheckMode.TOO_WEAK, result.mode)
+        assertTrue(result.tokPerSec < 3.0)
+    }
+
+    @Test
+    fun `custom hardwareMinimum is honored`() {
+        val result = CapabilityPrecheck.assess(
+            ctx,
+            thresholds = CapabilityPrecheck.Thresholds(hardwareMinimum = 12.0),
+            hints = midRangeLaptop,
+        )
+        assertEquals(PrecheckMode.TOO_WEAK, result.mode)
+    }
+
+    @Test
+    fun `custom minLocalCapability is honored`() {
+        val result = CapabilityPrecheck.assess(
+            ctx,
+            thresholds = CapabilityPrecheck.Thresholds(minLocalCapability = 5.0),
+            hints = midRangeLaptop,
+        )
+        assertEquals(PrecheckMode.OK, result.mode)
+    }
+
+    @Test
+    fun `result reason mentions tok-per-second`() {
+        val result = CapabilityPrecheck.assess(ctx, hints = veryWeakDevice)
+        assertTrue(
+            "reason should mention tok/s — got: ${result.reason}",
+            result.reason.contains("tok/s"),
+        )
+    }
+}