@dvai-bridge/ios 4.0.0

package/DVAIBridge.podspec

@@ -0,0 +1,120 @@
+require 'json'
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+# CocoaPods doesn't allow per-subspec `module_name`, so the whole pod compiles
+# into a single Swift module called `DVAIBridge`. Cross-target imports inside
+# our SwiftPM module graph (e.g. `import DVAILlamaCore`, `import Tokenizers`)
+# are wrapped with `#if !COCOAPODS` (see scripts/wrap-cocoapods-imports.py)
+# so they remain real imports under SwiftPM and become no-ops here, where
+# everything is already same-module. SwiftPM consumers continue to resolve
+# the upstream swift-transformers / swift-jinja / swift-collections packages
+# through Package.swift; only CocoaPods consumers see the vendored copies
+# under Vendor/swift-transformers/.
+
+Pod::Spec.new do |s|
+  s.name             = 'DVAIBridge'
+  s.version          = package['version']
+  s.summary          = package['description']
+  s.license          = { :type => 'Custom', :file => '../../LICENSE' }
+  s.homepage         = 'https://github.com/dvai-global/dvai-bridge'
+  s.author           = package['author']
+  s.source           = { :git => 'https://github.com/dvai-global/dvai-bridge.git', :tag => "v#{s.version}" }
+  s.platform         = :ios, '18.1'
+  s.swift_version    = '5.9'
+
+  s.source_files = [
+    # DVAI core actor + reactive state
+    'ios/Sources/DVAIBridge/**/*.swift',
+    # CoreML backend (uses vendored Tokenizers + Hub + Jinja)
+    'ios/Sources/DVAICoreMLCore/**/*.swift',
+    # Shared HTTP-server / handler-dispatch types, plus llama.cpp backend
+    # — copied from sibling *-core packages into Sources/_external/ by
+    # prepare_command (CocoaPods' file globs do not follow `..` paths
+    # reliably across pod boundaries).
+    'Sources/_external/DVAISharedCore/**/*.swift',
+    'Sources/_external/DVAILlamaCore/**/*.swift',
+    'Sources/_external/DVAILlamaCoreObjC/**/*.{h,mm}',
+    # NOTE: DVAIFoundationCore is intentionally NOT in the pod. It uses
+    # Apple's FoundationModels framework whose import emits implicit
+    # autolink directives for private frameworks (SwiftUICore /
+    # UIUtilities / CoreAudioTypes) that non-Apple products cannot link.
+    # The Foundation Models backend is therefore SwiftPM-only. Calling
+    # `.start(BackendKind.foundation)` under a CocoaPods build throws
+    # DVAIBridgeError.backendUnavailable with a clear message.
+    # Vendored swift-transformers stack — see Vendor/swift-transformers/ for
+    # upstream attributions and the rationale for stripping HubApi.swift.
+    'Vendor/swift-transformers/Tokenizers/**/*.swift',
+    'Vendor/swift-transformers/Hub/**/*.swift',
+    'Vendor/swift-transformers/Jinja/**/*.swift',
+    'Vendor/swift-transformers/OrderedCollections/**/*.swift',
+    'Vendor/swift-transformers/InternalCollectionsUtilities/**/*.swift',
+  ]
+
+  # Tokenizer fallback configs (gpt2_tokenizer_config.json, t5_..) are looked
+  # up via Bundle.module by the vendored Hub.swift. Vendor/.../Hub/BundleModuleShim.swift
+  # provides Bundle.module under !SWIFT_PACKAGE so the lookup resolves to the
+  # framework's main bundle, where these resources land.
+  s.resources = ['Vendor/swift-transformers/Hub/Resources/*.json']
+
+  # CocoaPods' pod-validator treats the pod as a self-contained tree and
+  # refuses `..` paths in `vendored_frameworks`. The xcframeworks are
+  # produced by scripts/mac-side-prepare-xcframework.sh in the llama.cpp
+  # submodule's build-apple/ directory (so SwiftPM's binaryTarget paths
+  # resolve from Package.swift). For CocoaPods we copy them into a
+  # pod-local Frameworks/ folder via prepare_command, which runs in the
+  # source tree before validation.
+  s.prepare_command = <<-SH
+    set -e
+    XCF_SRC="../dvai-bridge-android-llama-core/android/src/main/cpp/native/llama.cpp/build-apple"
+    mkdir -p Frameworks
+    if [ -d "$XCF_SRC/llama.xcframework" ]; then
+      rm -rf Frameworks/llama.xcframework
+      cp -R "$XCF_SRC/llama.xcframework" Frameworks/llama.xcframework
+    fi
+    if [ -d "$XCF_SRC/mtmd.xcframework" ]; then
+      rm -rf Frameworks/mtmd.xcframework
+      cp -R "$XCF_SRC/mtmd.xcframework" Frameworks/mtmd.xcframework
+    fi
+    # Mirror sibling-package source dirs into Sources/_external/ so they're
+    # visible to CocoaPods' file glob (it doesn't follow `..` paths).
+    rm -rf Sources/_external
+    mkdir -p Sources/_external
+    cp -R ../dvai-bridge-ios-shared-core/ios/Sources/DVAISharedCore Sources/_external/
+    cp -R ../dvai-bridge-ios-llama-core/ios/Sources/DVAILlamaCore Sources/_external/
+    cp -R ../dvai-bridge-ios-llama-core/ios/Sources/DVAILlamaCoreObjC Sources/_external/
+    # FoundationCore + MLXCore are intentionally NOT mirrored — see
+    # source_files comment.
+  SH
+
+  s.vendored_frameworks = [
+    'Frameworks/llama.xcframework',
+    'Frameworks/mtmd.xcframework',
+  ]
+
+  s.frameworks = ['Foundation', 'CoreML', 'AVFoundation', 'CryptoKit']
+
+  # Vendored swift-collections 1.4.1 + swift-jinja 2.3.5 use:
+  #   - `package` access level (needs -package-name; SwiftPM auto-sets it)
+  #   - `@_lifetime(...)` (needs experimental Lifetimes feature)
+  # Set these explicitly for the CocoaPods build so the pod compiles
+  # with the same source SwiftPM consumes.
+  s.pod_target_xcconfig = {
+    'OTHER_SWIFT_FLAGS' => '$(inherited) -package-name DVAIBridgeVendored -enable-experimental-feature Lifetimes',
+    # Pin the test-app deployment target to our pod's iOS minimum.
+    'IPHONEOS_DEPLOYMENT_TARGET' => '18.1',
+    # CocoaPods auto-adds `-framework llama -framework mtmd` to the
+    # consumer's app target's OTHER_LDFLAGS but NOT to our pod's own
+    # framework target — so symbols from the xcframeworks (referenced
+    # by LlamaCppBridge.mm) are unresolved at pod-link time. Add them
+    # explicitly here. The xcframework integration script already places
+    # the right slice in PODS_XCFRAMEWORKS_BUILD_DIR/DVAIBridge before
+    # the link step.
+    'OTHER_LDFLAGS' => '$(inherited) -framework "llama" -framework "mtmd"',
+  }
+
+  # Telegraph stays at ~> 0.30 because Building42 publishes 0.40+ as GitHub
+  # tags only; CocoaPods trunk caps at 0.30.0. Our usage only touches stable
+  # core types (Server / HTTPRequest / HTTPResponse / HTTPStatus / HTTPHeaders),
+  # so consumers on either channel get a working build.
+  s.dependency 'Telegraph', '~> 0.30'
+end

package/LICENSE

@@ -0,0 +1,51 @@
+# Deep Voice Ai Limited - Software License Agreement
+
+**Version 1.0.0**
+
+This License Agreement governs the use of the DVAI-Bridge software (the "Software"). By downloading, installing, or using the Software, you agree to be bound by the terms of this License.
+
+---
+
+## 1. LICENSE GRANTS
+
+### 1.1 Development and Personal Use (Free Tier)
+Deep Voice Ai Limited ("Licensor") grants you a non-exclusive, non-transferable, royalty-free license to use the Software solely for:
+- Internal development and testing purposes.
+- Non-commercial personal projects.
+- Academic and non-profit research.
+
+### 1.2 Commercial Use (Paid Tier)
+Any use of the Software for **Commercial Purposes** requires a separate, paid Commercial License from Licensor. "Commercial Purposes" include:
+- Use in production environments.
+- Integration into revenue-generating products or services.
+- Distribution to third-party customers for a fee.
+- Use by an entity with more than $100,000 USD in annual revenue.
+
+To obtain a Commercial License, contact `info@deepvoiceai.co` or visit `https://deepvoiceai.co/licensing`.
+
+---
+
+## 2. RESTRICTIONS
+Except as expressly permitted, you may not:
+- Sublicense, rent, lease, or resell the Software without express permission.
+- Remove any proprietary notices or branding from the Software.
+- Use the Software for any illegal or malicious purposes.
+
+---
+
+## 3. INTELLECTUAL PROPERTY
+The Software is owned by **Deep Voice Ai Limited** and is protected by copyright and intellectual property laws. This agreement does not transfer ownership of the Software.
+
+---
+
+## 4. NO WARRANTY
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.
+
+---
+
+## 5. GOVERNING LAW
+This License shall be governed by and construed in accordance with the laws of the jurisdiction where Deep Voice Ai Limited is registered.
+
+---
+
+© 2026 Deep Voice Ai Limited. All rights reserved.

package/Package.swift

@@ -0,0 +1,104 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+let package = Package(
+    name: "DVAIBridge",
+    // iOS 18.1 link-time floor: DVAIFoundationCore requires it (the
+    // FoundationModels SDK is `@available(iOS 26, *)` at runtime; 18.1 is
+    // its link-time minimum). DVAILlamaCore allows 14.0, but the package
+    // as a whole takes the highest minimum. CoreML's MLState requires
+    // iOS 18 too, so 18.1 covers everything.
+    platforms: [.iOS("18.1"), .macOS(.v14)],
+    products: [
+        .library(name: "DVAIBridge", targets: ["DVAIBridge"]),
+        .library(name: "DVAICoreMLCore", targets: ["DVAICoreMLCore"]),
+    ],
+    dependencies: [
+        // Path-dep to the cores. Identity is derived from the path's last
+        // directory name; each core has its manifest at the package root,
+        // so identities are `dvai-bridge-ios-shared-core` /
+        // `dvai-bridge-ios-llama-core` / `dvai-bridge-ios-foundation-core` /
+        // `dvai-bridge-ios-mlx-core`.
+        .package(path: "../dvai-bridge-ios-shared-core"),
+        .package(path: "../dvai-bridge-ios-llama-core"),
+        .package(path: "../dvai-bridge-ios-foundation-core"),
+        .package(path: "../dvai-bridge-ios-mlx-core"),
+        // swift-transformers — provides Tokenizers product for HuggingFace
+        // tokenizer loading. Constraint relaxed to `from: 1.2.0` to keep
+        // our resolver compatible with mlx-swift-lm 2.x (which pins
+        // swift-transformers `<1.3.0`). Our usage of AutoTokenizer.from(modelFolder:)
+        // / applyChatTemplate / encode / decode is API-compatible across
+        // 1.2.x → 1.3.x.
+        .package(url: "https://github.com/huggingface/swift-transformers.git", from: "1.2.0"),
+        // v3.2.0 — Hummingbird is the iOS HTTP server backbone (replaces
+        // Telegraph). DVAISharedCore exports it transitively via its
+        // HttpServer actor, but we pull it here too so the OffloadProxy
+        // can use it directly without a `@_implementationOnly` import
+        // gymnastics step.
+        .package(url: "https://github.com/hummingbird-project/hummingbird.git", from: "2.0.0"),
+        // v3.2.2 — JWTKit drives the offline JWT license validator
+        // (ES256 ECDSA P-256). Refuses alg=none / HMAC to defend against
+        // algorithm-confusion attacks. Same .jwt format as the JS-side
+        // validator in @dvai-bridge/core.
+        .package(url: "https://github.com/vapor/jwt-kit.git", from: "5.5.0"),
+    ],
+    targets: [
+        .target(
+            name: "DVAICoreMLCore",
+            dependencies: [
+                .product(name: "Tokenizers", package: "swift-transformers"),
+                // CoreML backend uses shared HTTP types — DOES NOT depend on
+                // DVAILlamaCore (so CoreML-only consumers don't transitively
+                // pull llama.xcframework). DVAISharedCore brings Hummingbird
+                // transitively as of v3.2.0.
+                .product(name: "DVAISharedCore", package: "dvai-bridge-ios-shared-core"),
+            ],
+            path: "ios/Sources/DVAICoreMLCore",
+            // Keep Swift 5 language mode: the existing code in this
+            // package was written before Swift 6's strict-concurrency
+            // checks landed. Bumping `swift-tools-version` to 6.0 (to
+            // pull in JWTKit 5.x) doesn't require flipping the language
+            // mode; we opt out per-target to keep the source unchanged.
+            swiftSettings: [.swiftLanguageMode(.v5)]
+        ),
+        .target(
+            name: "DVAIBridge",
+            dependencies: [
+                // DVAIBridge depends on all four backends + shared types.
+                // The llama-core dep is what brings in ModelDownloader; if a
+                // future refactor extracts that too, DVAIBridge could drop
+                // the llama-core dep when the consumer is using only
+                // .mlx / .foundation / .coreml.
+                .product(name: "DVAISharedCore", package: "dvai-bridge-ios-shared-core"),
+                .product(name: "DVAILlamaCore", package: "dvai-bridge-ios-llama-core"),
+                .product(name: "DVAIFoundationCore", package: "dvai-bridge-ios-foundation-core"),
+                .product(name: "DVAIMLXCore", package: "dvai-bridge-ios-mlx-core"),
+                "DVAICoreMLCore",
+                // v3.2 Phase 5 — outgoing-offload pre-routing proxy.
+                // Hummingbird (built on swift-nio) gives us proper
+                // streaming SSE bodies through the proxy.
+                .product(name: "Hummingbird", package: "hummingbird"),
+                // v3.2.2 — offline JWT license validator.
+                .product(name: "JWTKit", package: "jwt-kit"),
+            ],
+            path: "ios/Sources/DVAIBridge",
+            swiftSettings: [.swiftLanguageMode(.v5)]
+        ),
+        .testTarget(
+            name: "DVAIBridgeTests",
+            dependencies: [
+                "DVAIBridge",
+                .product(name: "DVAISharedCore", package: "dvai-bridge-ios-shared-core"),
+                .product(name: "DVAILlamaCore", package: "dvai-bridge-ios-llama-core"),
+                .product(name: "DVAIFoundationCore", package: "dvai-bridge-ios-foundation-core"),
+                .product(name: "DVAIMLXCore", package: "dvai-bridge-ios-mlx-core"),
+                "DVAICoreMLCore",
+                // v3.2.2 — license validator tests sign their own test
+                // tokens with a freshly generated test ES256 keypair.
+                .product(name: "JWTKit", package: "jwt-kit"),
+            ],
+            path: "ios/Tests/DVAIBridgeTests",
+            swiftSettings: [.swiftLanguageMode(.v5)]
+        ),
+    ]
+)

package/README.md

@@ -0,0 +1,199 @@
+![DVAI-Bridge](/assets/banner.png)
+
+# DVAI-Bridge
+
+<!-- [![Smoke — real models](https://github.com/Westenets/dvai-bridge/actions/workflows/smoke-real-models.yml/badge.svg?branch=main)](https://github.com/Westenets/dvai-bridge/actions/workflows/smoke-real-models.yml) -->
+
+[![License](https://img.shields.io/badge/License-Commercial-blue.svg)](LICENSE) ![Node.js](https://img.shields.io/badge/Node.js-22+-green?logo=node.js) ![TypeScript](https://img.shields.io/badge/TypeScript-5.6+-blue?logo=typescript) ![Swift](https://img.shields.io/badge/Swift-5.9+-F05138?logo=swift) ![Kotlin](https://img.shields.io/badge/Kotlin-2.0+-7F52FF?logo=kotlin) ![Flutter](https://img.shields.io/badge/Flutter-3.39+-02569B?logo=flutter) ![.NET](https://img.shields.io/badge/.NET-10.0_LTS-512BD4?logo=dotnet)
+
+> **The local OpenAI server you embed inside your app.**
+> One library. One HTTP wire. Every platform. Zero install for your users.
+
+**Docs:** [dvai-bridge.deepvoiceai.co](https://dvai-bridge.deepvoiceai.co)
+
+```ts
+import { DVAI } from "@dvai-bridge/core";
+import OpenAI from "openai";
+
+const dvai = new DVAI({ backend: "transformers" });
+await dvai.initialize();
+
+const openai = new OpenAI({ baseURL: dvai.baseUrl, apiKey: "ignored" });
+await openai.chat.completions.create({
+  model: dvai.transformersModelId,
+  messages: [{ role: "user", content: "Hello!" }],
+});
+```
+
+That's it. A real OpenAI-compatible server is now running inside your app's
+own process. Point any OpenAI client — LangChain, the OpenAI SDK, the Vercel
+AI SDK, anything — at `dvai.baseUrl` and your agent code keeps working.
+
+Built by **[Deep Voice AI](https://deepvoiceai.co)**.
+
+---
+
+## Why it exists
+
+Local AI works beautifully on a laptop with **Ollama + LangChain**. Then you
+try to ship the app and your users don't have Ollama. Mobile can't run it.
+Corporate IT won't add another daemon. So you reinvent the same plumbing —
+spawn an inference engine, bind a port, translate to OpenAI HTTP, handle
+CORS, manage lifecycle, wrap the accelerator of the day per platform — and
+do it all over again for every target OS.
+
+DVAI-Bridge is that plumbing, packaged as a library, for every client
+platform.
+
+---
+
+## What you get
+
+- **One OpenAI HTTP surface.** Bound on `127.0.0.1` (or `0.0.0.0` for
+  device-to-device). Streaming, embeddings, models, recovery — all built in.
+- **Six SDKs.** `@dvai-bridge/core` + `react` + `vanilla` + `capacitor`,
+  `DVAIBridge` (Swift / iOS), `co.deepvoiceai:dvai-bridge` (Kotlin / Android),
+  `@dvai-bridge/react-native`, `dvai_bridge` (Flutter), `co.deepvoiceai.dvai-bridge` (.NET).
+- **Nine backends.** WebLLM, Transformers.js, llama.cpp, Apple Foundation
+  Models, MLX, CoreML / ANE, MediaPipe LLM, LiteRT, ONNX Runtime GenAI —
+  selected per-platform, invisible to your agent code.
+- **Native acceleration** wherever it runs: WebGPU in browsers, CUDA / Metal
+  / Vulkan / DirectML on desktop, ANE / Metal / MLX on iOS, NNAPI / QNN
+  Hexagon / GPU delegate on Android.
+- **Multimodal.** Text, image, audio, video — declarative loader for
+  cutting-edge models (Gemma 4, LLaVA, Idefics) without waiting for library
+  updates.
+- **Distributed inference (v3.0+).** Phone too slow? Offload to your laptop
+  on the same Wi-Fi via mDNS pairing — same OpenAI wire, transparent to
+  your code. Internet path via a self-hostable rendezvous server.
+- **DVAI Hub (v3.1+).** A first-party desktop utility that turns any device
+  into a strong-peer for the rest of your fleet. Brand-neutral install via
+  Homebrew / winget / GitHub Releases, OR fork it for your own branded
+  companion. Routes through Ollama / LM Studio / vLLM / llama-server /
+  llamafile if you've already got those running.
+- **Zero user install.** It's a library, not a daemon. `npm install`,
+  `cocoapods`, gradle — your CI already has the muscle for it.
+
+---
+
+## Supported platforms
+
+| Stack | Package | Backends |
+| --- | --- | --- |
+| Browser (React, Vue, Svelte, vanilla JS) | `@dvai-bridge/core` + `react` / `vanilla` | WebLLM (WebGPU), Transformers.js (WebGPU / WASM SIMD) |
+| Node / Bun / Electron | `@dvai-bridge/core` | Transformers.js, native llama.cpp |
+| Capacitor hybrid mobile | `@dvai-bridge/capacitor` + backend slice | Native llama.cpp (Metal iOS, Vulkan / CPU Android) |
+| iOS native (Swift) | `DVAIBridge` (SPM / CocoaPods) | llama.cpp (Metal), CoreML / ANE, Apple Foundation Models, MLX |
+| Android native (Kotlin / Java) | `co.deepvoiceai:dvai-bridge` (AAR) | llama.cpp, MediaPipe LLM, LiteRT, NNAPI / QNN |
+| React Native (≥0.77, TurboModule) | `@dvai-bridge/react-native` | All iOS + Android backends (delegates) |
+| Flutter (≥3.39) | `dvai_bridge` (pub.dev) | All iOS + Android backends (Pigeon channels) |
+| .NET 10 LTS (MAUI / Avalonia / WinUI / Catalyst / desktop) | `co.deepvoiceai.dvai-bridge*` (NuGet) | iOS / Android delegate to native; desktop = llama.cpp + ONNX Runtime GenAI + ML.NET |
+
+Full quickstart per platform: [dvai-bridge.deepvoiceai.co/guide/getting-started](https://dvai-bridge.deepvoiceai.co/guide/getting-started)
+
+---
+
+## Examples
+
+```ts
+// React
+import { DVAIProvider, useDVAI } from "@dvai-bridge/react";
+<DVAIProvider config={{ backend: "transformers" }}>
+  <Chat />
+</DVAIProvider>;
+function Chat() {
+  const { isReady, baseUrl } = useDVAI();
+  return isReady ? <div>Local AI live at {baseUrl}</div> : <Loading />;
+}
+```
+
+```swift
+// iOS
+let server = try await DVAIBridge.shared.start()
+// server.baseUrl = "http://127.0.0.1:38883/v1"
+```
+
+```kotlin
+// Android
+val server = DVAIBridge.start(context)
+// server.baseUrl = "http://127.0.0.1:38883/v1"
+```
+
+```dart
+// Flutter
+final state = await DVAIBridge.instance.start(
+  backend: BackendKind.auto,
+  modelPath: '/path/to/model.gguf',
+);
+// state.baseUrl = "http://127.0.0.1:38883/v1"
+```
+
+```csharp
+// .NET
+var server = await DVAIBridge.Shared.StartAsync(new StartOptions {
+    Backend = BackendKind.Auto,
+    ModelPath = "/path/to/model.gguf",
+});
+// server.BaseUrl = "http://127.0.0.1:38883/v1"
+```
+
+Multimodal, streaming, embeddings, distributed offload, the Hub —
+everything's at the [docs site](https://dvai-bridge.deepvoiceai.co).
+
+---
+
+## What's new in v3.1
+
+- **DVAI Hub** — Tauri desktop utility that's the strong-peer side of v3
+  distributed inference. `brew install deepvoiceai/dvai-hub/dvai-hub` (or
+  `winget install DeepVoiceAI.DVAIHub`) → mobile apps on the same Wi-Fi
+  pair with it and offload heavy inference. [Guide →](https://dvai-bridge.deepvoiceai.co/guide/dvai-hub)
+- **External-engine bridge.** Hub surfaces Ollama / LM Studio / vLLM /
+  llama-server / llamafile as additional backend pools so paired apps
+  serve from whatever's already cached. Opt-in per engine.
+- **Strict substitution policy.** Models with mismatched family / version /
+  size / type are refused by default; quant-only mismatches gated behind a
+  per-pairing `preferBetterQuant` flag. No silent mis-routing.
+- **HMAC-signed identity** on `/v1/chat/completions`. Per-app audit logs
+  surface who served what, with structured `(appId, peerDeviceId,
+  engine, requestedModel, servedModel, outcome)` rows.
+- **Library finalization.** `httpBindHost` (LAN bind), `chatCompletionInterceptor`
+  (extension point), HMAC primitives re-exported, `/v1/dvai/*` routes
+  actually dispatched, TransformersBackend Node-mode device fix.
+  [Migration v3.0 → v3.1 →](https://dvai-bridge.deepvoiceai.co/migration/v3.0-to-v3.1)
+
+---
+
+## Robustness
+
+Streaming-correct (SSE passthrough + blank-chunk detection), generation
+timeout, automatic engine-state recovery on fatal errors, port fallback,
+worker offloading, Private Network Access ready, CORS configured. The
+boring substrate so your agent code never has to think about it.
+
+---
+
+## Licensing
+
+Dual: **free for development & personal use** on `localhost` (verified at
+runtime). **Commercial use** requires a license key — `info@deepvoiceai.co`.
+
+---
+
+## Contributing
+
+PRs welcome.
+
+```bash
+pnpm install
+pnpm build
+bash scripts/build-all.sh   # full matrix (auto-skips per-host)
+```
+
+[`CONTRIBUTING.md`](./CONTRIBUTING.md) for the PR flow. Per-platform
+contributor docs (iOS / Android / RN / Flutter / .NET) under
+[`docs/development/`](./docs/development/).
+
+---
+
+© Deep Voice AI Limited. All rights reserved.

package/ios/Sources/DVAIBridge/BackendKind.swift

@@ -0,0 +1,23 @@
+import Foundation
+
+/// Inference backend used by `DVAIBridge.shared.start(...)`.
+public enum BackendKind: String, Sendable, Codable, CaseIterable {
+    /// Resolve the best available backend at runtime.
+    case auto
+    /// llama.cpp via Metal (iOS) — the broad-compatibility default.
+    case llama
+    /// Apple Foundation Models (LanguageModelSession). Requires iOS 26+ at runtime.
+    /// SwiftPM-only: omitted from CocoaPods builds (the `import FoundationModels`
+    /// auto-link directive references private frameworks CocoaPods consumers
+    /// cannot link). Selecting this under CocoaPods throws `backendUnavailable`.
+    case foundation
+    /// CoreML / Apple Neural Engine via `MLModel` + `MLState` (iOS 18+).
+    case coreml
+    /// MLX — Apple Silicon GPU/Neural Engine via `mlx-swift-lm`. Apple-Silicon
+    /// only at runtime; the iOS Simulator on Intel hosts has no MLX device.
+    /// Loads HuggingFace MLX-converted checkpoints (e.g.
+    /// "mlx-community/Llama-3.2-1B-Instruct-4bit"). SwiftPM-only for the
+    /// same reasons as `.foundation` — the mlx-swift-lm transitive deps
+    /// don't publish CocoaPods specs.
+    case mlx
+}

package/ios/Sources/DVAIBridge/BoundServer.swift

@@ -0,0 +1,46 @@
+import Foundation
+
+public struct BoundServer: Sendable, Equatable {
+    public let baseUrl: String
+    public let port: Int
+    public let backend: BackendKind
+    public let modelId: String
+    /// v3.2.2 — the license status the validator reported at startup.
+    /// `nil` when `DVAIBridge.start(_:)` was called without going through
+    /// the license gate (e.g. legacy test fixtures). `commercial` / `trial`
+    /// on the paid path; `freeDev` on debug / simulator. The two failure
+    /// cases (`freeProd` / `freeExpired`) never make it here because
+    /// `start(_:)` throws `LicenseRequiredError` before constructing
+    /// `BoundServer`.
+    public let licenseStatus: LicenseStatus?
+
+    public init(
+        baseUrl: String,
+        port: Int,
+        backend: BackendKind,
+        modelId: String,
+        licenseStatus: LicenseStatus? = nil
+    ) {
+        self.baseUrl = baseUrl
+        self.port = port
+        self.backend = backend
+        self.modelId = modelId
+        self.licenseStatus = licenseStatus
+    }
+
+    /// Construct from the underlying core PluginState's `[String: Any]` result.
+    internal init(coreResult: [String: Any], backend: BackendKind, licenseStatus: LicenseStatus? = nil) throws {
+        guard let baseUrl = coreResult["baseUrl"] as? String,
+              let port = (coreResult["port"] as? Int) ?? (coreResult["port"] as? NSNumber)?.intValue
+        else {
+            throw DVAIBridgeError.backendError(underlying: "core PluginState returned malformed start result")
+        }
+        let modelId = (coreResult["modelId"] as? String) ?? ""
+        self.init(baseUrl: baseUrl, port: port, backend: backend, modelId: modelId, licenseStatus: licenseStatus)
+    }
+
+    /// v3.2.2 — derive a copy with the license status attached.
+    internal func with(licenseStatus: LicenseStatus?) -> BoundServer {
+        BoundServer(baseUrl: baseUrl, port: port, backend: backend, modelId: modelId, licenseStatus: licenseStatus)
+    }
+}

package/ios/Sources/DVAIBridge/Capability/CapabilityCache.swift

@@ -0,0 +1,85 @@
+import Foundation
+
+/// JSON-file-backed capability cache living under
+/// `Application Support/dvai-bridge/capability.json`. Mirrors the TS-side
+/// `NodeFsCapabilityCache` in `packages/dvai-bridge-core/src/capability/cache.ts`
+/// so the same on-disk format round-trips between native and JS layers
+/// running on the same Mac (Mac Catalyst / Electron).
+public actor CapabilityCache {
+    private let fileURL: URL
+    private var cache: [String: CapabilityScore]?
+
+    public init(directory: URL) {
+        self.fileURL = directory.appendingPathComponent("capability.json", isDirectory: false)
+    }
+
+    public func get(_ key: CapabilityCacheKey) async -> CapabilityScore? {
+        let map = await load()
+        return map[Self.diskKey(key)]
+    }
+
+    public func set(_ score: CapabilityScore) async throws {
+        var map = await load()
+        let key = CapabilityCacheKey(modelId: score.modelId, libraryVersion: score.libraryVersion)
+        map[Self.diskKey(key)] = score
+        cache = map
+        try await save()
+    }
+
+    public func list() async -> [CapabilityScore] {
+        let map = await load()
+        return Array(map.values)
+    }
+
+    public func clear() async throws {
+        cache = [:]
+        try await save()
+    }
+
+    private func load() async -> [String: CapabilityScore] {
+        if let cache = cache { return cache }
+        if let data = try? Data(contentsOf: fileURL),
+           let decoded = try? JSONDecoder().decode([String: CapabilityScore].self, from: data) {
+            cache = decoded
+            return decoded
+        }
+        cache = [:]
+        return [:]
+    }
+
+    private func save() async throws {
+        guard let cache = cache else { return }
+        try FileManager.default.createDirectory(
+            at: fileURL.deletingLastPathComponent(),
+            withIntermediateDirectories: true
+        )
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        let data = try encoder.encode(cache)
+        try data.write(to: fileURL, options: .atomic)
+    }
+
+    /// Cache key on-disk: `${modelId}|${libraryVersion}`.
+    static func diskKey(_ key: CapabilityCacheKey) -> String {
+        "\(key.modelId)|\(key.libraryVersion)"
+    }
+}
+
+/// Resolves the canonical Application Support directory for dvai-bridge
+/// caches (capability + pairings + device-id). Matches the iOS / Mac
+/// Catalyst path documented in
+/// `docs/migration/v2.4-to-v3.0.md` (Operational notes).
+public enum DVAIBridgeSupportDirectory {
+    public static func resolve() throws -> URL {
+        let fm = FileManager.default
+        let base = try fm.url(
+            for: .applicationSupportDirectory,
+            in: .userDomainMask,
+            appropriateFor: nil,
+            create: true
+        )
+        let dir = base.appendingPathComponent("dvai-bridge", isDirectory: true)
+        try fm.createDirectory(at: dir, withIntermediateDirectories: true)
+        return dir
+    }
+}