@dvai-bridge/android 4.0.0 → 4.0.2

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

@@ -1,146 +1,146 @@
-package co.deepvoiceai.bridge.license
-
-import android.content.Context
-import java.io.File
-
-/**
- * License-file discovery for the Android SDK.
- *
- * Kotlin port of `packages/dvai-bridge-core/src/license/discovery.ts`.
- * The discovery priority order mirrors the JS side but the platform-
- * default locations are Android-specific:
- *
- *   1. An explicit string literal passed via [LicenseDiscoveryOptions.token]
- *      — useful for CI / test contexts where reading a file isn't practical.
- *   2. A path passed via [LicenseDiscoveryOptions.path] — the developer
- *      points the SDK at a file they've placed somewhere non-default.
- *   3. The `DVAI_LICENSE_PATH` env var — same as (2) but driven by
- *      process environment, helpful for emulator-based testing.
- *   4. The `DVAI_LICENSE_TOKEN` env var — inline JWT as an alternative
- *      to a file path.
- *   5. The bundled asset `assets/dvai-license.jwt` — the conventional
- *      ship-with-the-APK location. Auto-discovered.
- *   6. The bundled raw resource `R.raw.dvai_license` — alternative
- *      asset location for apps that already use the res/raw/ folder.
- *      Looked up reflectively against the host app's R.raw class.
- *   7. Internal storage `context.filesDir/dvai-license.jwt` — for
- *      apps that drop the license at runtime (e.g. fetched from
- *      a self-hosted endpoint after first launch).
- *
- * Returning `null` means "no license file found"; the validator treats
- * that as the free-prod case, which on Android escalates to a throw via
- * [LicenseValidator.validateAndAssert].
- */
-
-/** Default filename the SDK looks for at every file location. */
-const val DEFAULT_LICENSE_FILENAME: String = "dvai-license.jwt"
-
-/** Default raw-resource name (without the `R.raw.` prefix). */
-const val DEFAULT_LICENSE_RAW_RESOURCE_NAME: String = "dvai_license"
-
-data class LicenseDiscoveryOptions(
-    /** Pre-loaded JWT string (skips all filesystem / asset lookups). */
-    val token: String? = null,
-    /** Explicit path to load from. Overrides auto-discovery. */
-    val path: String? = null,
-)
-
-/** Result of a successful discovery; identifies the source for audit logging. */
-data class DiscoveredToken(val token: String, val source: String)
-
-/**
- * Best-effort load of a license JWT. Returns the raw token string on
- * success or null on miss. Errors during loading (file not found, asset
- * not present) collapse to null — the validator's responsibility is to
- * handle the no-license case gracefully, not the discovery layer's.
- *
- * Side-effect-free in the sense of "no network calls"; reads from the
- * filesystem and the APK's assets directory only.
- */
-fun discoverLicenseToken(
-    context: Context,
-    opts: LicenseDiscoveryOptions = LicenseDiscoveryOptions(),
-): DiscoveredToken? {
-    // 1. Explicit token wins.
-    if (!opts.token.isNullOrEmpty()) {
-        return DiscoveredToken(opts.token.trim(), "config.licenseToken")
-    }
-
-    // 2. Explicit path (config option). An explicit path that doesn't load
-    //    is a real miss, not a silent fallthrough — matches JS behaviour.
-    if (!opts.path.isNullOrEmpty()) {
-        val loaded = tryLoadFromPath(opts.path)
-        return loaded?.let { DiscoveredToken(it, opts.path) }
-    }
-
-    // 3. Env-var path.
-    val envPath = System.getenv("DVAI_LICENSE_PATH")
-    if (!envPath.isNullOrEmpty()) {
-        val loaded = tryLoadFromPath(envPath)
-        if (loaded != null) return DiscoveredToken(loaded, "DVAI_LICENSE_PATH=$envPath")
-    }
-
-    // 4. Env-var inline token (alternative to file).
-    val envToken = System.getenv("DVAI_LICENSE_TOKEN")
-    if (!envToken.isNullOrEmpty()) {
-        return DiscoveredToken(envToken.trim(), "DVAI_LICENSE_TOKEN env var")
-    }
-
-    // 5. Bundled asset: assets/dvai-license.jwt.
-    val asset = tryLoadFromAsset(context, DEFAULT_LICENSE_FILENAME)
-    if (asset != null) return DiscoveredToken(asset, "assets/$DEFAULT_LICENSE_FILENAME")
-
-    // 6. Bundled raw resource: R.raw.dvai_license (looked up reflectively
-    //    against the host app's R class because we can't reference its
-    //    R from a library module).
-    val raw = tryLoadFromRawResource(context, DEFAULT_LICENSE_RAW_RESOURCE_NAME)
-    if (raw != null) return DiscoveredToken(raw, "res/raw/$DEFAULT_LICENSE_RAW_RESOURCE_NAME")
-
-    // 7. Internal storage: filesDir/dvai-license.jwt.
-    val internalFile = File(context.filesDir, DEFAULT_LICENSE_FILENAME)
-    val internal = tryLoadFromFile(internalFile)
-    if (internal != null) return DiscoveredToken(internal, internalFile.absolutePath)
-
-    return null
-}
-
-private fun tryLoadFromPath(path: String): String? = tryLoadFromFile(File(path))
-
-private fun tryLoadFromFile(file: File): String? {
-    return try {
-        if (!file.exists() || !file.isFile) return null
-        val text = file.readText(Charsets.UTF_8).trim()
-        text.ifEmpty { null }
-    } catch (_: Throwable) {
-        null
-    }
-}
-
-private fun tryLoadFromAsset(context: Context, name: String): String? {
-    return try {
-        context.assets.open(name).use { input ->
-            val text = input.readBytes().toString(Charsets.UTF_8).trim()
-            text.ifEmpty { null }
-        }
-    } catch (_: Throwable) {
-        null
-    }
-}
-
-private fun tryLoadFromRawResource(context: Context, name: String): String? {
-    return try {
-        // Resource ids are dynamic — the library module has no compile-time
-        // reference to the host app's R.raw, so look it up by name via
-        // Resources.getIdentifier(). Returns 0 if the host app doesn't
-        // ship a `res/raw/dvai_license.*` resource, which we treat as a
-        // clean miss.
-        val resId = context.resources.getIdentifier(name, "raw", context.packageName)
-        if (resId == 0) return null
-        context.resources.openRawResource(resId).use { input ->
-            val text = input.readBytes().toString(Charsets.UTF_8).trim()
-            text.ifEmpty { null }
-        }
-    } catch (_: Throwable) {
-        null
-    }
-}
+package co.deepvoiceai.bridge.license
+
+import android.content.Context
+import java.io.File
+
+/**
+ * License-file discovery for the Android SDK.
+ *
+ * Kotlin port of `packages/dvai-bridge-core/src/license/discovery.ts`.
+ * The discovery priority order mirrors the JS side but the platform-
+ * default locations are Android-specific:
+ *
+ *   1. An explicit string literal passed via [LicenseDiscoveryOptions.token]
+ *      — useful for CI / test contexts where reading a file isn't practical.
+ *   2. A path passed via [LicenseDiscoveryOptions.path] — the developer
+ *      points the SDK at a file they've placed somewhere non-default.
+ *   3. The `DVAI_LICENSE_PATH` env var — same as (2) but driven by
+ *      process environment, helpful for emulator-based testing.
+ *   4. The `DVAI_LICENSE_TOKEN` env var — inline JWT as an alternative
+ *      to a file path.
+ *   5. The bundled asset `assets/dvai-license.jwt` — the conventional
+ *      ship-with-the-APK location. Auto-discovered.
+ *   6. The bundled raw resource `R.raw.dvai_license` — alternative
+ *      asset location for apps that already use the res/raw/ folder.
+ *      Looked up reflectively against the host app's R.raw class.
+ *   7. Internal storage `context.filesDir/dvai-license.jwt` — for
+ *      apps that drop the license at runtime (e.g. fetched from
+ *      a self-hosted endpoint after first launch).
+ *
+ * Returning `null` means "no license file found"; the validator treats
+ * that as the free-prod case, which on Android escalates to a throw via
+ * [LicenseValidator.validateAndAssert].
+ */
+
+/** Default filename the SDK looks for at every file location. */
+const val DEFAULT_LICENSE_FILENAME: String = "dvai-license.jwt"
+
+/** Default raw-resource name (without the `R.raw.` prefix). */
+const val DEFAULT_LICENSE_RAW_RESOURCE_NAME: String = "dvai_license"
+
+data class LicenseDiscoveryOptions(
+    /** Pre-loaded JWT string (skips all filesystem / asset lookups). */
+    val token: String? = null,
+    /** Explicit path to load from. Overrides auto-discovery. */
+    val path: String? = null,
+)
+
+/** Result of a successful discovery; identifies the source for audit logging. */
+data class DiscoveredToken(val token: String, val source: String)
+
+/**
+ * Best-effort load of a license JWT. Returns the raw token string on
+ * success or null on miss. Errors during loading (file not found, asset
+ * not present) collapse to null — the validator's responsibility is to
+ * handle the no-license case gracefully, not the discovery layer's.
+ *
+ * Side-effect-free in the sense of "no network calls"; reads from the
+ * filesystem and the APK's assets directory only.
+ */
+fun discoverLicenseToken(
+    context: Context,
+    opts: LicenseDiscoveryOptions = LicenseDiscoveryOptions(),
+): DiscoveredToken? {
+    // 1. Explicit token wins.
+    if (!opts.token.isNullOrEmpty()) {
+        return DiscoveredToken(opts.token.trim(), "config.licenseToken")
+    }
+
+    // 2. Explicit path (config option). An explicit path that doesn't load
+    //    is a real miss, not a silent fallthrough — matches JS behaviour.
+    if (!opts.path.isNullOrEmpty()) {
+        val loaded = tryLoadFromPath(opts.path)
+        return loaded?.let { DiscoveredToken(it, opts.path) }
+    }
+
+    // 3. Env-var path.
+    val envPath = System.getenv("DVAI_LICENSE_PATH")
+    if (!envPath.isNullOrEmpty()) {
+        val loaded = tryLoadFromPath(envPath)
+        if (loaded != null) return DiscoveredToken(loaded, "DVAI_LICENSE_PATH=$envPath")
+    }
+
+    // 4. Env-var inline token (alternative to file).
+    val envToken = System.getenv("DVAI_LICENSE_TOKEN")
+    if (!envToken.isNullOrEmpty()) {
+        return DiscoveredToken(envToken.trim(), "DVAI_LICENSE_TOKEN env var")
+    }
+
+    // 5. Bundled asset: assets/dvai-license.jwt.
+    val asset = tryLoadFromAsset(context, DEFAULT_LICENSE_FILENAME)
+    if (asset != null) return DiscoveredToken(asset, "assets/$DEFAULT_LICENSE_FILENAME")
+
+    // 6. Bundled raw resource: R.raw.dvai_license (looked up reflectively
+    //    against the host app's R class because we can't reference its
+    //    R from a library module).
+    val raw = tryLoadFromRawResource(context, DEFAULT_LICENSE_RAW_RESOURCE_NAME)
+    if (raw != null) return DiscoveredToken(raw, "res/raw/$DEFAULT_LICENSE_RAW_RESOURCE_NAME")
+
+    // 7. Internal storage: filesDir/dvai-license.jwt.
+    val internalFile = File(context.filesDir, DEFAULT_LICENSE_FILENAME)
+    val internal = tryLoadFromFile(internalFile)
+    if (internal != null) return DiscoveredToken(internal, internalFile.absolutePath)
+
+    return null
+}
+
+private fun tryLoadFromPath(path: String): String? = tryLoadFromFile(File(path))
+
+private fun tryLoadFromFile(file: File): String? {
+    return try {
+        if (!file.exists() || !file.isFile) return null
+        val text = file.readText(Charsets.UTF_8).trim()
+        text.ifEmpty { null }
+    } catch (_: Throwable) {
+        null
+    }
+}
+
+private fun tryLoadFromAsset(context: Context, name: String): String? {
+    return try {
+        context.assets.open(name).use { input ->
+            val text = input.readBytes().toString(Charsets.UTF_8).trim()
+            text.ifEmpty { null }
+        }
+    } catch (_: Throwable) {
+        null
+    }
+}
+
+private fun tryLoadFromRawResource(context: Context, name: String): String? {
+    return try {
+        // Resource ids are dynamic — the library module has no compile-time
+        // reference to the host app's R.raw, so look it up by name via
+        // Resources.getIdentifier(). Returns 0 if the host app doesn't
+        // ship a `res/raw/dvai_license.*` resource, which we treat as a
+        // clean miss.
+        val resId = context.resources.getIdentifier(name, "raw", context.packageName)
+        if (resId == 0) return null
+        context.resources.openRawResource(resId).use { input ->
+            val text = input.readBytes().toString(Charsets.UTF_8).trim()
+            text.ifEmpty { null }
+        }
+    } catch (_: Throwable) {
+        null
+    }
+}

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

@@ -1,158 +1,158 @@
-package co.deepvoiceai.bridge.license
-
-/**
- * Type surface for the DVAI-Bridge offline JWT license system.
- *
- * Kotlin port of `packages/dvai-bridge-core/src/license/types.ts`. The
- * sealed [LicenseStatus] hierarchy mirrors the JS discriminated-union;
- * each case carries the same fields. Android-native consumers dispatch
- * on `when (status)` exhaustively, matching the JS `switch(status.kind)`.
- *
- * The whole license flow is deliberately small:
- *   1. A signed JWT (produced server-side by your license generator) is
- *      either dropped at a platform-default path, pointed at via the
- *      [co.deepvoiceai.bridge.StartOptions.licenseKeyPath] config option,
- *      or pasted directly into [co.deepvoiceai.bridge.StartOptions.licenseToken].
- *   2. The SDK reads it, verifies the ECDSA P-256 signature against the
- *      key registry in [DvaiPublicKeys], and checks four runtime claims:
- *      - signature must verify against a known kid
- *      - `exp` must be in the future
- *      - `aud` must include the current audience (package name)
- *      - `platforms` must include "android"
- *   3. The outcome is summarised in a [LicenseStatus] value that the
- *      rest of the SDK can dispatch on.
- *
- * Nothing in this file makes network calls. The entire flow is offline.
- */
-
-/** Platform identifiers the SDK recognises in license `platforms` claims. */
-enum class DvaiPlatform(val wire: String) {
-    WEB("web"),
-    NODE("node"),
-    IOS("ios"),
-    ANDROID("android"),
-    DOTNET("dotnet"),
-    FLUTTER("flutter"),
-    REACT_NATIVE("react-native"),
-    CAPACITOR("capacitor");
-
-    companion object {
-        fun fromWire(s: String): DvaiPlatform? = values().firstOrNull { it.wire == s }
-    }
-}
-
-/**
- * Payload shape we issue (subset; extra claims tolerated). Mirrors the
- * JS-side `DvaiLicensePayload`.
- *
- * @property iss        Standard JWT issuer claim. Must be `"DVAI-Bridge"`.
- * @property sub        Standard subject — internal license id. Surfaced in audit logs.
- * @property aud        Audience binding — list of domains and/or bundle ids permitted
- *                      to activate this license. Each entry is either an exact string
- *                      match (e.g. `"com.acme.app"`) or a wildcard subdomain
- *                      pattern (e.g. `"*.acme.com"` matches both `acme.com` and
- *                      `app.acme.com`), or `"*"` for any-audience licenses.
- * @property tier       Tier the license grants. `"commercial"` and `"trial"` are
- *                      the live tiers; the validator never produces `"free-*"` here
- *                      (those are computed at validation time).
- * @property platforms  Which DVAI-Bridge SDK platforms this license activates.
- *                      The current runtime platform must appear here for the
- *                      license to apply.
- * @property licensee   Display name of the licensee, for audit logs + user-facing messaging.
- * @property iat        Standard JWT issued-at (seconds since Unix epoch).
- * @property exp        Standard JWT expiry (seconds since Unix epoch).
- */
-data class DvaiLicensePayload(
-    val iss: String,
-    val sub: String,
-    val aud: List<String>,
-    val tier: String, // "commercial" | "trial"
-    val platforms: List<String>,
-    val licensee: String,
-    val iat: Long,
-    val exp: Long,
-)
-
-/**
- * Result of license validation. Sealed class so the consumer's decision
- * tree is exhaustive (`Commercial` or `Trial` → premium; everything else
- * → free).
- *
- * Note: on Android the validator NEVER produces a [FreeProd] status that
- * the SDK then runs in free tier — production Android without a license
- * throws via [LicenseRequiredError]. The status case exists so that
- * `validate()` (the non-throwing variant) can describe the failure for
- * host-app dashboards / logging, but [LicenseValidator.validateAndAssert]
- * (called from `DVAIBridge.start`) converts it to a throw.
- */
-sealed class LicenseStatus {
-    /** Paid commercial license — premium tier. */
-    data class Commercial(
-        val licensee: String,
-        val expiresAt: Long,
-        val platform: DvaiPlatform,
-        val audienceMatched: String,
-    ) : LicenseStatus()
-
-    /** Paid trial license — premium tier, time-limited. */
-    data class Trial(
-        val licensee: String,
-        val expiresAt: Long,
-        val platform: DvaiPlatform,
-        val audienceMatched: String,
-    ) : LicenseStatus()
-
-    /**
-     * Debug build / dev-mode bypass. License enforcement skipped.
-     * @property reason Why dev mode was detected (for logging / dashboard surfacing).
-     */
-    data class FreeDev(val reason: String) : LicenseStatus()
-
-    /**
-     * Production deploy with no valid license. On Android,
-     * `validateAndAssert()` throws [LicenseRequiredError] for this case
-     * rather than allowing free-tier operation — unlike the JS SDK which
-     * runs with a watermark in free-prod.
-     *
-     * @property reason Specific failure mode (no token, signature failed,
-     *                  audience mismatch, etc.) — verbose by design so the
-     *                  developer can self-debug without a support ticket.
-     */
-    data class FreeProd(val reason: String) : LicenseStatus()
-
-    /**
-     * Had a valid license but `exp` is in the past. On Android,
-     * `validateAndAssert()` throws [LicenseRequiredError] for this case.
-     */
-    data class FreeExpired(
-        val licensee: String,
-        val expiredAt: Long,
-    ) : LicenseStatus()
-}
-
-/** Returns true iff `status` represents a paid / unwatermarked tier. */
-fun isPaidTier(status: LicenseStatus): Boolean =
-    status is LicenseStatus.Commercial || status is LicenseStatus.Trial
-
-/**
- * Thrown by [LicenseValidator.validateAndAssert] (and propagated from
- * `DVAIBridge.start(...)`) when an SDK consumer attempts to run the
- * library in a production / release context without a valid commercial
- * or trial license.
- *
- * The error message is intentionally verbose: it tells the developer
- * exactly which check failed (missing file, expired, audience mismatch,
- * etc.), how to resolve it, and where to put the license file once
- * they have one. This is the front line of the BSL 1.1 commercial
- * enforcement story — surface it clearly enough that a developer can
- * unblock themselves without a support ticket.
- *
- * The `status` field carries the underlying [LicenseStatus] so
- * programmatic callers can dispatch on `err.status` if they want to
- * handle "expired" differently from "missing".
- */
-class LicenseRequiredError(
-    message: String,
-    /** The underlying validator status that triggered the throw. */
-    val status: LicenseStatus,
-) : Exception(message)
+package co.deepvoiceai.bridge.license
+
+/**
+ * Type surface for the DVAI-Bridge offline JWT license system.
+ *
+ * Kotlin port of `packages/dvai-bridge-core/src/license/types.ts`. The
+ * sealed [LicenseStatus] hierarchy mirrors the JS discriminated-union;
+ * each case carries the same fields. Android-native consumers dispatch
+ * on `when (status)` exhaustively, matching the JS `switch(status.kind)`.
+ *
+ * The whole license flow is deliberately small:
+ *   1. A signed JWT (produced server-side by your license generator) is
+ *      either dropped at a platform-default path, pointed at via the
+ *      [co.deepvoiceai.bridge.StartOptions.licenseKeyPath] config option,
+ *      or pasted directly into [co.deepvoiceai.bridge.StartOptions.licenseToken].
+ *   2. The SDK reads it, verifies the ECDSA P-256 signature against the
+ *      key registry in [DvaiPublicKeys], and checks four runtime claims:
+ *      - signature must verify against a known kid
+ *      - `exp` must be in the future
+ *      - `aud` must include the current audience (package name)
+ *      - `platforms` must include "android"
+ *   3. The outcome is summarised in a [LicenseStatus] value that the
+ *      rest of the SDK can dispatch on.
+ *
+ * Nothing in this file makes network calls. The entire flow is offline.
+ */
+
+/** Platform identifiers the SDK recognises in license `platforms` claims. */
+enum class DvaiPlatform(val wire: String) {
+    WEB("web"),
+    NODE("node"),
+    IOS("ios"),
+    ANDROID("android"),
+    DOTNET("dotnet"),
+    FLUTTER("flutter"),
+    REACT_NATIVE("react-native"),
+    CAPACITOR("capacitor");
+
+    companion object {
+        fun fromWire(s: String): DvaiPlatform? = values().firstOrNull { it.wire == s }
+    }
+}
+
+/**
+ * Payload shape we issue (subset; extra claims tolerated). Mirrors the
+ * JS-side `DvaiLicensePayload`.
+ *
+ * @property iss        Standard JWT issuer claim. Must be `"DVAI-Bridge"`.
+ * @property sub        Standard subject — internal license id. Surfaced in audit logs.
+ * @property aud        Audience binding — list of domains and/or bundle ids permitted
+ *                      to activate this license. Each entry is either an exact string
+ *                      match (e.g. `"com.acme.app"`) or a wildcard subdomain
+ *                      pattern (e.g. `"*.acme.com"` matches both `acme.com` and
+ *                      `app.acme.com`), or `"*"` for any-audience licenses.
+ * @property tier       Tier the license grants. `"commercial"` and `"trial"` are
+ *                      the live tiers; the validator never produces `"free-*"` here
+ *                      (those are computed at validation time).
+ * @property platforms  Which DVAI-Bridge SDK platforms this license activates.
+ *                      The current runtime platform must appear here for the
+ *                      license to apply.
+ * @property licensee   Display name of the licensee, for audit logs + user-facing messaging.
+ * @property iat        Standard JWT issued-at (seconds since Unix epoch).
+ * @property exp        Standard JWT expiry (seconds since Unix epoch).
+ */
+data class DvaiLicensePayload(
+    val iss: String,
+    val sub: String,
+    val aud: List<String>,
+    val tier: String, // "commercial" | "trial"
+    val platforms: List<String>,
+    val licensee: String,
+    val iat: Long,
+    val exp: Long,
+)
+
+/**
+ * Result of license validation. Sealed class so the consumer's decision
+ * tree is exhaustive (`Commercial` or `Trial` → premium; everything else
+ * → free).
+ *
+ * Note: on Android the validator NEVER produces a [FreeProd] status that
+ * the SDK then runs in free tier — production Android without a license
+ * throws via [LicenseRequiredError]. The status case exists so that
+ * `validate()` (the non-throwing variant) can describe the failure for
+ * host-app dashboards / logging, but [LicenseValidator.validateAndAssert]
+ * (called from `DVAIBridge.start`) converts it to a throw.
+ */
+sealed class LicenseStatus {
+    /** Paid commercial license — premium tier. */
+    data class Commercial(
+        val licensee: String,
+        val expiresAt: Long,
+        val platform: DvaiPlatform,
+        val audienceMatched: String,
+    ) : LicenseStatus()
+
+    /** Paid trial license — premium tier, time-limited. */
+    data class Trial(
+        val licensee: String,
+        val expiresAt: Long,
+        val platform: DvaiPlatform,
+        val audienceMatched: String,
+    ) : LicenseStatus()
+
+    /**
+     * Debug build / dev-mode bypass. License enforcement skipped.
+     * @property reason Why dev mode was detected (for logging / dashboard surfacing).
+     */
+    data class FreeDev(val reason: String) : LicenseStatus()
+
+    /**
+     * Production deploy with no valid license. On Android,
+     * `validateAndAssert()` throws [LicenseRequiredError] for this case
+     * rather than allowing free-tier operation — unlike the JS SDK which
+     * runs with a watermark in free-prod.
+     *
+     * @property reason Specific failure mode (no token, signature failed,
+     *                  audience mismatch, etc.) — verbose by design so the
+     *                  developer can self-debug without a support ticket.
+     */
+    data class FreeProd(val reason: String) : LicenseStatus()
+
+    /**
+     * Had a valid license but `exp` is in the past. On Android,
+     * `validateAndAssert()` throws [LicenseRequiredError] for this case.
+     */
+    data class FreeExpired(
+        val licensee: String,
+        val expiredAt: Long,
+    ) : LicenseStatus()
+}
+
+/** Returns true iff `status` represents a paid / unwatermarked tier. */
+fun isPaidTier(status: LicenseStatus): Boolean =
+    status is LicenseStatus.Commercial || status is LicenseStatus.Trial
+
+/**
+ * Thrown by [LicenseValidator.validateAndAssert] (and propagated from
+ * `DVAIBridge.start(...)`) when an SDK consumer attempts to run the
+ * library in a production / release context without a valid commercial
+ * or trial license.
+ *
+ * The error message is intentionally verbose: it tells the developer
+ * exactly which check failed (missing file, expired, audience mismatch,
+ * etc.), how to resolve it, and where to put the license file once
+ * they have one. This is the front line of the BSL 1.1 commercial
+ * enforcement story — surface it clearly enough that a developer can
+ * unblock themselves without a support ticket.
+ *
+ * The `status` field carries the underlying [LicenseStatus] so
+ * programmatic callers can dispatch on `err.status` if they want to
+ * handle "expired" differently from "missing".
+ */
+class LicenseRequiredError(
+    message: String,
+    /** The underlying validator status that triggered the throw. */
+    val status: LicenseStatus,
+) : Exception(message)