@dvai-bridge/ios-foundation-core 4.0.1

package/LICENSE

@@ -0,0 +1,358 @@
+DVAI BRIDGE COMMUNITY LICENCE
+Version 1.0 — "DVAI-BCL v1.0"
+Copyright (c) 2026 Deep Voice AI Limited (Company No. 16743132)
+
+================================================================================
+NOTICE TO USER
+================================================================================
+
+This is the legal text of the DVAI Bridge Community Licence ("DVAI-BCL v1.0",
+or "this Licence"). DVAI Bridge is source-available software developed by Deep
+Voice AI Limited, a company incorporated in England and Wales with registered
+number 16743132 ("Licensor", "we", "us"). Anyone may read, modify, build, and
+redistribute this software under the terms set out below.
+
+You may use DVAI Bridge free of charge for Permitted Uses (defined below).
+Commercial Use of DVAI Bridge requires a separate Commercial Licence from us.
+On the Change Date specified below, each Released Version of DVAI Bridge
+automatically converts to the Apache License, Version 2.0 ("Apache 2.0"). The
+conversion is irrevocable and is the structural commitment by which we
+guarantee the eventual full open-source availability of DVAI Bridge.
+
+This Licence is loosely modelled on the Business Source License 1.1 (BSL 1.1)
+published by MariaDB Corporation Ab, with significant customisations to
+support DVAI's dual-licensing commercial model, defined Permitted Uses, and
+patent grant. It is not a Business Source License and the Licensor License
+Grant in BSL 1.1 has been replaced.
+
+A plain-language summary of this Licence is published at
+https://deepvoiceai.co/licensing. The summary is informational only; this
+file is the legally binding instrument.
+
+================================================================================
+DEFINITIONS
+================================================================================
+
+In this Licence the following definitions apply:
+
+"Apache 2.0" means the Apache License, Version 2.0 published by the Apache
+Software Foundation and available at https://www.apache.org/licenses/LICENSE-2.0,
+together with the corresponding NOTICE-file conventions.
+
+"Change Date" means, in respect of a Released Version, the date that is three
+(3) years after the Public Release Date of that Released Version, as recorded
+in the Change Date Register published in the source repository (file
+CHANGE_DATE.md). On and after the Change Date for a Released Version, that
+Released Version automatically and irrevocably converts to Apache 2.0.
+
+"Commercial Licence" means a separate written commercial licence agreement
+issued by the Licensor authorising Commercial Use, on the commercial terms
+published from time to time at https://deepvoiceai.co/licensing or
+individually negotiated with the Licensor.
+
+"Commercial Use" means any use of DVAI Bridge in or in connection with a
+product, service, or activity that generates revenue, including without
+limitation:
+  (a) integration of DVAI Bridge into a product or service that you sell,
+      license, host, or otherwise make available to third parties for value;
+  (b) provision of inference services, AI services, or hosted offerings to
+      third parties using DVAI Bridge;
+  (c) use of DVAI Bridge by, or for the benefit of, any organisation that
+      generates revenue from any commercial offering in which DVAI Bridge is
+      a component (whether or not DVAI Bridge itself is monetised
+      separately).
+Commercial Use does not include any of the Permitted Uses defined below.
+
+"DVAI Bridge" means the software in the source repository at
+https://github.com/dvai-global/dvai-bridge ("the Repository"), including the
+source code, build outputs, language-binding packages, and any documentation
+distributed alongside it, in each case as published by the Licensor.
+
+"Licence" means this DVAI Bridge Community Licence v1.0 in its entirety,
+together with the NOTICE file in the Repository.
+
+"Permitted Use" means each of the following uses of DVAI Bridge, in each case
+free of charge and free of any obligation to enter into a Commercial Licence:
+  (a) Personal use — use of DVAI Bridge by an individual for personal,
+      non-commercial purposes, including hobby projects, personal-learning
+      builds, and experimentation outside the scope of any commercial
+      activity;
+  (b) Educational use — use of DVAI Bridge in teaching, coursework, training
+      materials, student projects, and other educational activities of an
+      educational institution or a teacher acting in that capacity;
+  (c) Academic research — use of DVAI Bridge in academic research the outputs
+      of which are intended for publication, dissemination, or peer review,
+      where DVAI Bridge is referenced or cited in the resulting outputs;
+  (d) Evaluation — use of DVAI Bridge by an organisation for a period not
+      exceeding ninety (90) consecutive days for the purpose of evaluating
+      whether to enter into a Commercial Licence;
+  (e) Internal-only use — use of DVAI Bridge by an organisation for purely
+      internal purposes, where the capability provided by DVAI Bridge is not
+      distributed to, used by, or made available to any third party outside
+      the organisation, and is not used to generate revenue from any
+      external party;
+  (f) Contribution — use of DVAI Bridge in connection with the preparation,
+      testing, and submission of contributions to the Repository, subject to
+      the Licensor's then-current Contributor Licence Agreement.
+
+"Public Release Date" means, in respect of a Released Version, the date on
+which the Licensor first made that Released Version generally available to the
+public through the Repository (typically the date of the corresponding Git
+tag), as recorded in the Change Date Register (file CHANGE_DATE.md).
+
+"Released Version" means a specific version of DVAI Bridge made publicly
+available by the Licensor through the Repository, identified by a Git tag
+matching the pattern "v<MAJOR>.<MINOR>.<PATCH>" or any successor versioning
+scheme published by the Licensor.
+
+"You" (or "Your") means the natural person or legal entity exercising the
+rights granted by this Licence. For legal entities, "You" includes each
+entity that controls, is controlled by, or is under common control with that
+entity.
+
+================================================================================
+1. GRANT OF LICENCE FOR PERMITTED USE
+================================================================================
+
+1.1 Subject to Your compliance with the terms of this Licence, the Licensor
+hereby grants You a worldwide, non-exclusive, royalty-free, non-transferable,
+non-sublicensable, revocable (only as expressly stated in Sections 7 and 8)
+copyright licence to reproduce, prepare derivative works of, publicly
+display, publicly perform, and distribute DVAI Bridge for Permitted Use.
+
+1.2 The Licence in Section 1.1 includes the right to modify DVAI Bridge and
+to redistribute DVAI Bridge (in original or modified form) provided that:
+  (a) every copy and every derivative work redistributed by You is distributed
+      under, and accompanied by, the unmodified text of this Licence;
+  (b) every copy and every derivative work retains all copyright, attribution,
+      and other proprietary notices appearing in the original;
+  (c) any redistribution is accompanied by the unmodified text of the NOTICE
+      file as published in the Repository at the time of redistribution; and
+  (d) the redistribution itself is for a Permitted Use, or is performed in a
+      manner that does not involve Commercial Use by You.
+
+1.3 The Licence in Section 1.1 does not authorise Commercial Use. If You wish
+to use DVAI Bridge for any Commercial Use, You must first obtain a Commercial
+Licence from the Licensor. Information about how to obtain a Commercial
+Licence is published at https://deepvoiceai.co/licensing and may be requested
+by email to info@deepvoiceai.co.
+
+================================================================================
+2. AUTOMATIC CONVERSION ON THE CHANGE DATE
+================================================================================
+
+2.1 On and after the Change Date for a Released Version, that Released
+Version (including all source code, build outputs, and documentation included
+in that Released Version) automatically and irrevocably converts to Apache 2.0.
+
+2.2 The conversion in Section 2.1 means that, on and after the Change Date,
+the Released Version may be used, copied, modified, distributed, and used for
+any Commercial Use without a Commercial Licence and without obligation to the
+Licensor, subject only to the terms of Apache 2.0.
+
+2.3 The conversion is per Released Version. Released Versions that have not
+yet reached their Change Date remain subject to this Licence. Each subsequent
+Released Version is subject to this Licence for its own three-year period
+before independently converting to Apache 2.0.
+
+2.4 The Change Date for each Released Version is recorded in the Change Date
+Register in the Repository (file CHANGE_DATE.md). The Licensor commits that
+once a Change Date has been recorded in the Change Date Register, the Change
+Date will not be moved backwards (made later) by any subsequent revision of
+this Licence or any other instrument.
+
+2.5 The Bridge Attribution requirements in Section 4 cease to apply to a
+Released Version on and after its Change Date. The standard NOTICE-file
+conventions of Apache 2.0 continue to apply.
+
+================================================================================
+3. GRANT OF PATENT LICENCE
+================================================================================
+
+3.1 Subject to the terms and conditions of this Licence, the Licensor hereby
+grants You a worldwide, non-exclusive, royalty-free, non-transferable,
+non-sublicensable patent licence under the Licensor's Patent Rights to make,
+have made, use, import, sell, offer to sell, and otherwise dispose of DVAI
+Bridge solely for Permitted Use.
+
+3.2 "Patent Rights" means the patent claims owned or controlled by the
+Licensor (including, without limitation, the claims of UK Patent Application
+GB2611312.6 once granted) that, but for this grant, would be infringed by use
+of DVAI Bridge as originally distributed by the Licensor.
+
+3.3 The patent licence in Section 3.1 does not extend to Commercial Use.
+Patent rights for Commercial Use are granted only under a separate Commercial
+Licence.
+
+3.4 If You institute patent litigation (including a cross-claim or
+counterclaim in a lawsuit) against any entity alleging that DVAI Bridge
+constitutes direct or contributory patent infringement, then any patent
+licences granted to You under this Section 3 shall terminate as of the date
+such litigation is filed, without prejudice to any other remedy the Licensor
+may have.
+
+================================================================================
+4. BRIDGE ATTRIBUTION MARK
+================================================================================
+
+4.1 When You exercise the licence in Section 1, You shall:
+  (a) retain in the source code of DVAI Bridge the copyright notice, this
+      Licence text, and the NOTICE file unmodified;
+  (b) where DVAI Bridge is incorporated into a build artefact (including a
+      published package, binary, container image, or installable application),
+      reproduce the substance of the copyright notice and a reference to this
+      Licence in a place reasonably accessible to recipients of that artefact
+      (for example, an About box, a credits file, a licensing page, or
+      documentation distributed with the artefact); and
+  (c) not remove or obscure the "Powered by DVAI Bridge" attribution mark, or
+      its equivalent in any localised form, in any user-visible or developer-
+      visible interface in which it is present in DVAI Bridge as distributed
+      by the Licensor.
+
+4.2 The Bridge Attribution Mark may be removed from a build artefact only by
+a Commercial Licensee under the terms of their Commercial Licence with the
+Licensor. Removal of the Bridge Attribution Mark in the absence of a
+Commercial Licence is a material breach of this Licence.
+
+4.3 The Bridge Attribution Mark requirements cease to apply to a Released
+Version on and after its Change Date.
+
+================================================================================
+5. TRADEMARKS
+================================================================================
+
+5.1 Nothing in this Licence grants You any right to use the trademarks of
+the Licensor or its affiliates, including without limitation "Deep Voice AI",
+"DVAI", "DVAI Bridge", or the corresponding logos and stylisations
+(collectively, "Licensor Marks"), other than:
+  (a) reproduction of the Licensor Marks as part of the unmodified copyright
+      notices, NOTICE file, and Bridge Attribution Mark as required by
+      Section 4;
+  (b) descriptive use of the Licensor Marks in factual references such as
+      "based on DVAI Bridge" or "compatible with DVAI Bridge", provided that
+      such use is accurate, does not suggest endorsement by the Licensor of
+      any third-party product, and does not use the Licensor Marks in a
+      stylised, dominant, or distinctive manner that would create a
+      likelihood of confusion as to source.
+
+5.2 Trademark rights of third parties referenced in DVAI Bridge or in the
+NOTICE file (including without limitation "Apple", "Android", "Google",
+"Microsoft", "Capacitor", "React Native", "Flutter", ".NET", "iOS",
+"macOS") are the property of their respective owners and are reserved.
+
+================================================================================
+6. NO WARRANTY
+================================================================================
+
+DVAI BRIDGE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY
+WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR
+FITNESS FOR A PARTICULAR PURPOSE. THE LICENSOR DOES NOT WARRANT THAT DVAI
+BRIDGE WILL BE ERROR-FREE, UNINTERRUPTED, SECURE, OR THAT IT WILL MEET YOUR
+REQUIREMENTS. ANY USE BY YOU OF DVAI BRIDGE IS AT YOUR OWN RISK.
+
+================================================================================
+7. LIMITATION OF LIABILITY
+================================================================================
+
+7.1 To the maximum extent permitted by applicable law, the Licensor shall
+not be liable for any indirect, incidental, special, consequential, or
+exemplary damages, including without limitation loss of profits, reputation, revenue,
+business, data, or goodwill, arising out of or in connection with this
+Licence or Your use of DVAI Bridge, even if the Licensor has been advised of
+the possibility of such damages.
+
+7.2 To the maximum extent permitted by applicable law, the aggregate
+liability of the Licensor arising out of or in connection with this Licence
+and Your use of DVAI Bridge shall not exceed one hundred pounds sterling
+(GBP 100). For Permitted Use, this Licence is provided to You free of
+charge; this limitation reflects the absence of any consideration paid by
+You to the Licensor for the licence granted here.
+
+7.3 Nothing in this Licence excludes or limits liability for death or
+personal injury caused by negligence, for fraud or fraudulent
+misrepresentation, or for any other liability that cannot be excluded or
+limited as a matter of applicable law.
+
+================================================================================
+8. TERMINATION
+================================================================================
+
+8.1 This Licence terminates automatically and without notice upon any
+material breach by You of its terms, including without limitation:
+  (a) Commercial Use of DVAI Bridge without a Commercial Licence;
+  (b) removal or modification of the copyright notice, this Licence text, the
+      NOTICE file, or the Bridge Attribution Mark contrary to Section 4;
+  (c) institution by You of patent litigation in the circumstances described
+      in Section 3.4.
+
+8.2 On termination under Section 8.1, You shall immediately cease all use of
+DVAI Bridge, delete all copies of DVAI Bridge in Your possession, and procure
+that any third party to whom You have redistributed DVAI Bridge does the
+same.
+
+8.3 If Your breach is curable and is in fact cured within thirty (30) days of
+written notice from the Licensor, the Licensor may at its discretion
+reinstate the Licence as if the breach had not occurred. Reinstatement is at
+the Licensor's sole discretion.
+
+8.4 Sections 3.4, 5, 6, 7, 9, and 10 survive termination of this Licence.
+
+================================================================================
+9. RELATIONSHIP WITH OTHER AGREEMENTS
+================================================================================
+
+9.1 This Licence applies only to Released Versions for the period from the
+Public Release Date to the Change Date. On and after the Change Date for a
+Released Version, that Released Version is governed exclusively by Apache 2.0
+and this Licence has no further application to that Released Version, save
+that the patent termination provisions of Section 3.4 continue to apply to
+the conduct of any party that institutes patent litigation as described in
+that Section.
+
+9.2 A Commercial Licence supersedes this Licence as between the Licensor and
+the Commercial Licensee in respect of the uses authorised by the Commercial
+Licence. This Licence continues to apply to all other uses of DVAI Bridge by
+the Commercial Licensee not authorised by the Commercial Licence.
+
+9.3 Contributors to DVAI Bridge are subject to the Licensor's Contributor
+Licence Agreement ("CLA") in addition to this Licence. The CLA is published
+at https://deepvoiceai.co/cla.
+
+================================================================================
+10. GOVERNING LAW
+================================================================================
+
+10.1 This Licence is governed by and construed in accordance with the law of
+England and Wales.
+
+10.2 The courts of England and Wales have non-exclusive jurisdiction to
+settle any dispute arising out of or in connection with this Licence.
+
+================================================================================
+11. CONTACT
+================================================================================
+
+For all enquiries about this Licence, including Commercial Licence enquiries,
+contact info@deepvoiceai.co.
+
+Deep Voice AI Limited
+71-75 Shelton Street
+Covent Garden
+London WC2H 9JQ
+United Kingdom
+
+Company No. 16743132
+
+================================================================================
+END OF DVAI BRIDGE COMMUNITY LICENCE v1.0
+================================================================================
+
+NOTE ON LEGAL REVIEW
+--------------------
+
+This Licence text has been prepared by the Licensor and is the legally
+binding instrument under which DVAI Bridge is distributed. The Licensor recommends 
+that counsel competent in the law of England and Wales be consulted prior to
+substantive variation of this text or before entering into any Commercial
+Licence based on this Licence's framework.

package/Package.swift

@@ -0,0 +1,45 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+// FoundationModels deployment-target rationale: link-time floor is iOS 18.1
+// (the SDK-emitted symbols are weak-linked and resolve at runtime); the
+// FoundationModels public API itself is `@available(iOS 26.0, *)` in the
+// Xcode 26.4 SDK, so calling it requires runtime guarding. SwiftPM 5.9's
+// `.iOS` enum maxes out at `.v17`, hence the string-based `.iOS(_:)`
+// initializer which accepts arbitrary version strings like "18.1".
+let package = Package(
+    name: "DVAIFoundationCore",
+    platforms: [.iOS("18.1"), .macOS(.v14)],
+    products: [
+        .library(name: "DVAIFoundationCore", targets: ["DVAIFoundationCore"]),
+    ],
+    dependencies: [
+        // Shared HTTP-server / handler-dispatch types (formerly duplicated
+        // inline; now extracted into dvai-bridge-ios-shared-core for reuse
+        // across all backend cores). Path-dep identity =
+        // "dvai-bridge-ios-shared-core". DVAISharedCore brings in
+        // Hummingbird transitively as of v3.2.0 — the iOS HTTP server
+        // backbone is no longer Telegraph.
+        .package(path: "../dvai-bridge-ios-shared-core"),
+    ],
+    targets: [
+        // Package.swift sits at the package ROOT (not under `ios/`) so SPM derives
+        // identity "dvai-bridge-ios-foundation-core" — unique among siblings.
+        // Target paths are relative to Package.swift, hence the `ios/` prefix.
+        .target(
+            name: "DVAIFoundationCore",
+            dependencies: [
+                .product(name: "DVAISharedCore", package: "dvai-bridge-ios-shared-core"),
+            ],
+            path: "ios/Sources/DVAIFoundationCore"
+        ),
+        .testTarget(
+            name: "DVAIFoundationCoreTests",
+            dependencies: [
+                "DVAIFoundationCore",
+                .product(name: "DVAISharedCore", package: "dvai-bridge-ios-shared-core"),
+            ],
+            path: "ios/Tests/DVAIFoundationCoreTests"
+        ),
+    ]
+)

package/ios/Sources/DVAIFoundationCore/AsyncSemaphore.swift

@@ -0,0 +1,62 @@
+// Internal/AsyncSemaphore.swift
+//
+// A simple counting semaphore that's safe to await across suspension points.
+// `value: 1` makes it a mutex; multiple `wait()`s queue up and resume in FIFO.
+//
+// Used by `FoundationHandlers` to serialize concurrent `LanguageModelSession`
+// inference calls (`respond(to:)` / `streamResponse(to:)`). An NSLock around
+// an `await` would deadlock because it isn't async-aware; we need a
+// continuation-based async semaphore instead.
+
+import Foundation
+
+final class AsyncSemaphore: @unchecked Sendable {
+    private let lock = NSLock()
+    private var value: Int
+    private var waiters: [CheckedContinuation<Void, Never>] = []
+
+    init(value: Int = 1) { self.value = value }
+
+    /// Try to take a permit synchronously without crossing a suspension
+    /// point. Returns `nil` if a permit was acquired and the caller can
+    /// proceed; returns a non-nil "register continuation" closure when the
+    /// caller must instead `await` to be resumed by a future `signal()`.
+    /// Splitting the NSLock manipulation into this sync helper keeps the
+    /// lock from being touched inside an `async` context — NSLock is not
+    /// async-safe (warning becomes an error in Swift 6).
+    private func tryAcquireOrRegister() -> ((CheckedContinuation<Void, Never>) -> Void)? {
+        lock.lock()
+        if value > 0 {
+            value -= 1
+            lock.unlock()
+            return nil
+        }
+        // Returning the locked-state register hook: caller stashes the
+        // continuation, then we drop the lock. This preserves FIFO ordering
+        // because a concurrent `signal()` blocks on the same NSLock until
+        // the continuation is appended.
+        return { [self] cont in
+            waiters.append(cont)
+            lock.unlock()
+        }
+    }
+
+    func wait() async {
+        guard let register = tryAcquireOrRegister() else { return }
+        await withCheckedContinuation { cont in
+            register(cont)
+        }
+    }
+
+    func signal() {
+        lock.lock()
+        if !waiters.isEmpty {
+            let cont = waiters.removeFirst()
+            lock.unlock()
+            cont.resume()
+        } else {
+            value += 1
+            lock.unlock()
+        }
+    }
+}

package/ios/Sources/DVAIFoundationCore/FoundationHandlers.swift

@@ -0,0 +1,391 @@
+// Internal/FoundationHandlers.swift
+//
+// OpenAI-compatible handler set backed by Apple's `FoundationModels`
+// framework (`LanguageModelSession`).
+//
+// Availability — DEVIATION FROM PLAN: the plan documented `iOS 18.1+`,
+// but on the current Xcode 26.4 / iPhoneSimulator26.4 SDK, every public
+// `LanguageModelSession` symbol carries `@available(iOS 26.0, *)`
+// (likewise macOS 26 / macCatalyst 26 / visionOS 26). The Apple
+// FoundationModels framework's runtime requirement was raised between
+// the early plan draft and Xcode 26's release. We therefore guard the
+// whole class with `@available(iOS 26.0, macOS 26.0, *)`. The package's
+// SwiftPM `iOS("18.1")` floor stays — the framework is a strict
+// availability annotation, not a hard link, so older iOS 18.1+ apps
+// still build; they just cannot call into FoundationHandlers without
+// their own `if #available(iOS 26, *)` check.
+//
+// Phase 1 scope (per spec §8.4 modality matrix): text only.
+// - Image content parts → 400 (spec §8.5 wording).
+// - Audio content parts → 400 (spec §8.5 wording).
+// - /v1/embeddings → 400 (Apple FM has no public embedding API).
+//
+// Streaming: 4-frame SSE envelope (role / content* / finish / [DONE]),
+// mirroring `LlamaHandlers`. Multiple content frames are emitted, one per
+// partial response yielded by `LanguageModelSession.streamResponse(to:)`.
+// Telegraph 0.40 buffers the SSE body server-side so per-frame flushing
+// is identical to single-frame to clients today.
+//
+// Concurrency: `LanguageModelSession` is a stateful conversation object;
+// concurrent requests would interleave turns and corrupt Apple FM state.
+// Concurrent inference calls are serialized via `inferenceLock` (an async
+// semaphore) — an NSLock around an `await` would deadlock because it isn't
+// async-aware. The pre-existing `sessionLock` (NSLock) keeps guarding lazy
+// session creation in `ensureSession()` only.
+//
+// Host-build guard: `#if canImport(FoundationModels)` keeps the file
+// compilable on macOS hosts whose Xcode SDK predates FoundationModels.
+// On those hosts the entire class compiles out and the test target
+// guards itself the same way.
+
+#if canImport(FoundationModels)
+import FoundationModels
+#endif
+import Foundation
+#if !COCOAPODS
+import DVAISharedCore
+#endif
+
+#if canImport(FoundationModels)
+@available(iOS 26.0, macOS 26.0, *)
+public final class FoundationHandlers: DVAIHandlers, @unchecked Sendable {
+    private let modelId: String
+    private var session: LanguageModelSession?
+    private let sessionLock = NSLock()
+    /// Serializes `session.respond(to:)` / `session.streamResponse(to:)`
+    /// calls so concurrent /v1/chat/completions requests can't interleave
+    /// turns on the same conversational `LanguageModelSession` and corrupt
+    /// Apple FM state. `sessionLock` only guards the lazy-creation path in
+    /// `ensureSession()`; it cannot be held across an `await`.
+    private let inferenceLock = AsyncSemaphore(value: 1)
+
+    public init(modelId: String = "apple-foundation-3b") {
+        self.modelId = modelId
+    }
+
+    private func ensureSession() -> LanguageModelSession {
+        sessionLock.lock()
+        defer { sessionLock.unlock() }
+        if let s = session { return s }
+        let s = LanguageModelSession()
+        session = s
+        return s
+    }
+
+    /// Null out the cached session under `sessionLock` so the next request
+    /// lazy-creates a fresh one. Called from inference error paths to avoid
+    /// reusing a (potentially poisoned) conversational session. This does
+    /// NOT touch `inferenceLock` — the in-flight semaphore acquisition is
+    /// independent of which session reference is cached.
+    private func resetSession() {
+        sessionLock.lock()
+        self.session = nil
+        sessionLock.unlock()
+    }
+
+    // MARK: - /v1/chat/completions
+
+    public func handleChatCompletion(body: [String: Any], ctx: HandlerContext) async throws -> HandlerResponse {
+        // Validate messages field shape up-front. Matches LlamaHandlers' pattern.
+        guard let messages = body["messages"] as? [[String: Any]] else {
+            return .error(400, "Missing 'messages' field")
+        }
+        if messages.isEmpty {
+            return .error(400, "Empty messages array")
+        }
+
+        // Reject image / audio content parts up-front (spec §8.5 wording).
+        for msg in messages {
+            if let parts = msg["content"] as? [[String: Any]] {
+                for part in parts {
+                    if let type = part["type"] as? String {
+                        if type == "image_url" {
+                            return .error(400, "Image input not supported by Apple Foundation Models in this version.")
+                        }
+                        if type == "input_audio" {
+                            return .error(400, "Audio input not supported by Apple Foundation Models in this version.")
+                        }
+                    }
+                }
+            }
+        }
+
+        let prompt = openAIMessagesToPrompt(messages)
+        let session = ensureSession()
+        let id = "chatcmpl-fm-\(UUID().uuidString.prefix(20).lowercased())"
+        let created = Int(Date().timeIntervalSince1970)
+
+        if (body["stream"] as? Bool) == true {
+            // Acquire the inference semaphore BEFORE building the stream so the
+            // entire `for try await partial in ...` loop holds it. The Task
+            // releases it in a defer, which is fine because `signal()` is sync.
+            await inferenceLock.wait()
+
+            let modelId = self.modelId
+            // `[modelId]` capture: explicit so the Sendable closure can refer
+            // to the immutable string without retaining `self`.
+            let stream = AsyncStream<String> { [inferenceLock] continuation in
+                let task = Task { [modelId, weak self] in
+                    defer { inferenceLock.signal() }
+                    do {
+                        // Frame 1: role delta
+                        let roleChunk: [String: Any] = [
+                            "id": id,
+                            "object": "chat.completion.chunk",
+                            "created": created,
+                            "model": modelId,
+                            "choices": [[
+                                "index": 0,
+                                "delta": ["role": "assistant"],
+                            ] as [String: Any]],
+                        ]
+                        if let s = Self.serialize(roleChunk) {
+                            continuation.yield("data: \(s)\n\n")
+                        }
+
+                        // Frames 2..N: content deltas, one per partial response.
+                        // DEVIATION FROM PLAN: plan used `responseStream(to:)` —
+                        // actual API is `streamResponse(to:)` (returns
+                        // `ResponseStream`, conforms to `AsyncSequence`,
+                        // partials expose `.content`).
+                        for try await partial in session.streamResponse(to: prompt) {
+                            let chunk: [String: Any] = [
+                                "id": id,
+                                "object": "chat.completion.chunk",
+                                "created": created,
+                                "model": modelId,
+                                "choices": [[
+                                    "index": 0,
+                                    "delta": ["content": partial.content],
+                                ] as [String: Any]],
+                            ]
+                            if let s = Self.serialize(chunk) {
+                                continuation.yield("data: \(s)\n\n")
+                            }
+                        }
+
+                        // Frame N+1: finish
+                        let finishChunk: [String: Any] = [
+                            "id": id,
+                            "object": "chat.completion.chunk",
+                            "created": created,
+                            "model": modelId,
+                            "choices": [[
+                                "index": 0,
+                                "delta": [:] as [String: Any],
+                                "finish_reason": "stop",
+                            ] as [String: Any]],
+                        ]
+                        if let s = Self.serialize(finishChunk) {
+                            continuation.yield("data: \(s)\n\n")
+                        }
+
+                        continuation.yield("data: [DONE]\n\n")
+                    } catch {
+                        // Stream errored mid-flight. Emit a finish chunk with
+                        // finish_reason: "error" plus an error message so the
+                        // client can distinguish truncation from completion,
+                        // then forward [DONE]. Reset the session afterwards so
+                        // a poisoned conversational instance isn't reused on
+                        // the next request.
+                        let errorChunk: [String: Any] = [
+                            "id": id,
+                            "object": "chat.completion.chunk",
+                            "created": created,
+                            "model": modelId,
+                            "choices": [[
+                                "index": 0,
+                                "delta": [:] as [String: Any],
+                                "finish_reason": "error",
+                            ] as [String: Any]],
+                            "error": ["message": error.localizedDescription],
+                        ]
+                        if let s = Self.serialize(errorChunk) {
+                            continuation.yield("data: \(s)\n\n")
+                        }
+                        continuation.yield("data: [DONE]\n\n")
+                        self?.resetSession()
+                    }
+                    continuation.finish()
+                }
+
+                // If the HTTP client disconnects (or the stream is otherwise
+                // released) cancel the upstream Task so Apple FM stops
+                // generating tokens nobody will read. `streamResponse(to:)`
+                // is an AsyncSequence and respects Swift Concurrency
+                // cancellation, propagating to Apple FM.
+                continuation.onTermination = { @Sendable _ in
+                    task.cancel()
+                }
+            }
+            return .sse(stream)
+        }
+
+        // Non-streaming
+        await inferenceLock.wait()
+        do {
+            let response = try await session.respond(to: prompt)
+            inferenceLock.signal()
+            let json: [String: Any] = [
+                "id": id,
+                "object": "chat.completion",
+                "created": created,
+                "model": modelId,
+                "choices": [[
+                    "index": 0,
+                    "message": ["role": "assistant", "content": response.content],
+                    "finish_reason": "stop",
+                ] as [String: Any]],
+                "usage": ["prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0],
+            ]
+            return .json(200, json)
+        } catch {
+            inferenceLock.signal()
+            resetSession()
+            return .error(500, error.localizedDescription)
+        }
+    }
+
+    // MARK: - /v1/completions (legacy)
+
+    public func handleCompletion(body: [String: Any], ctx: HandlerContext) async throws -> HandlerResponse {
+        let promptField = body["prompt"]
+        let prompt: String
+        if let s = promptField as? String {
+            prompt = s
+        } else if let arr = promptField as? [String] {
+            prompt = arr.joined(separator: "\n")
+        } else {
+            prompt = ""
+        }
+
+        var chatBody = body
+        chatBody["messages"] = [["role": "user", "content": prompt]]
+        chatBody.removeValue(forKey: "prompt")
+
+        let chatResp = try await handleChatCompletion(body: chatBody, ctx: ctx)
+        switch chatResp {
+        case .json(let status, let chatBodyAny):
+            guard status == 200, let chat = chatBodyAny as? [String: Any] else {
+                return chatResp
+            }
+            return .json(200, chatToLegacyCompletion(chat))
+        case .sse(let chatStream):
+            let legacyStream = AsyncStream<String> { continuation in
+                Task {
+                    for await chunk in chatStream {
+                        continuation.yield(self.adaptChunkToLegacy(chunk))
+                    }
+                    continuation.finish()
+                }
+            }
+            return .sse(legacyStream)
+        case .error:
+            return chatResp
+        }
+    }
+
+    // MARK: - /v1/embeddings
+
+    public func handleEmbeddings(body: [String: Any], ctx: HandlerContext) async throws -> HandlerResponse {
+        return .error(400, "Embeddings not supported on Apple Foundation Models in this version.")
+    }
+
+    // MARK: - /v1/models
+
+    public func handleModels(ctx: HandlerContext) async throws -> HandlerResponse {
+        return .json(200, [
+            "object": "list",
+            "data": [["id": modelId, "object": "model", "owned_by": "apple"] as [String: Any]],
+        ])
+    }
+
+    // MARK: - Helpers
+
+    private func openAIMessagesToPrompt(_ messages: [[String: Any]]) -> String {
+        var lines: [String] = []
+        for msg in messages {
+            let role = (msg["role"] as? String) ?? "user"
+            if let text = msg["content"] as? String {
+                lines.append("\(role): \(text)")
+            } else if let parts = msg["content"] as? [[String: Any]] {
+                for part in parts {
+                    if (part["type"] as? String) == "text" {
+                        lines.append("\(role): \(part["text"] as? String ?? "")")
+                    }
+                    // image_url / input_audio rejected before we get here
+                    // (handleChatCompletion early-returns 400).
+                }
+            }
+        }
+        return lines.joined(separator: "\n")
+    }
+
+    private static func serialize(_ obj: Any) -> String? {
+        guard let data = try? JSONSerialization.data(withJSONObject: obj, options: []),
+              let s = String(data: data, encoding: .utf8) else {
+            return nil
+        }
+        return s
+    }
+
+    /// Convert a chat.completion JSON body to the legacy text_completion shape.
+    /// Mirrors the same helper in `LlamaHandlers` and `packages/dvai-bridge-core`.
+    private func chatToLegacyCompletion(_ chat: [String: Any]) -> [String: Any] {
+        var legacy: [String: Any] = [:]
+        let chatId = chat["id"] as? String ?? ""
+        legacy["id"] = chatId.isEmpty
+            ? "cmpl-\(Int(Date().timeIntervalSince1970))"
+            : chatId.replacingOccurrences(of: "chatcmpl-", with: "cmpl-")
+        legacy["object"] = "text_completion"
+        legacy["created"] = chat["created"] ?? Int(Date().timeIntervalSince1970)
+        legacy["model"] = chat["model"] ?? modelId
+        let choices = (chat["choices"] as? [[String: Any]]) ?? []
+        legacy["choices"] = choices.map { c -> [String: Any] in
+            let msg = c["message"] as? [String: Any]
+            return [
+                "text": (msg?["content"] as? String) ?? "",
+                "index": c["index"] ?? 0,
+                "finish_reason": c["finish_reason"] ?? "stop",
+                "logprobs": NSNull(),
+            ] as [String: Any]
+        }
+        legacy["usage"] = chat["usage"] ?? ["prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0]
+        return legacy
+    }
+
+    /// Adapt one SSE frame from chat.completion.chunk → text_completion.chunk.
+    /// `[DONE]` is forwarded unchanged. Frames that don't parse fall through.
+    private func adaptChunkToLegacy(_ chunk: String) -> String {
+        let trimmed = chunk.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard trimmed.hasPrefix("data:") else { return chunk }
+        let payload = String(trimmed.dropFirst("data:".count)).trimmingCharacters(in: .whitespacesAndNewlines)
+        if payload == "[DONE]" { return "data: [DONE]\n\n" }
+        guard let data = payload.data(using: .utf8),
+              let parsed = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return chunk
+        }
+        let chatId = parsed["id"] as? String ?? ""
+        let id = chatId.replacingOccurrences(of: "chatcmpl-", with: "cmpl-")
+        var legacyChoices: [[String: Any]] = []
+        for c in (parsed["choices"] as? [[String: Any]]) ?? [] {
+            let delta = c["delta"] as? [String: Any]
+            legacyChoices.append([
+                "text": (delta?["content"] as? String) ?? "",
+                "index": c["index"] ?? 0,
+                "finish_reason": c["finish_reason"] ?? NSNull(),
+                "logprobs": NSNull(),
+            ] as [String: Any])
+        }
+        let legacy: [String: Any] = [
+            "id": id,
+            "object": "text_completion.chunk",
+            "created": parsed["created"] ?? Int(Date().timeIntervalSince1970),
+            "model": parsed["model"] ?? modelId,
+            "choices": legacyChoices,
+        ]
+        if let s = Self.serialize(legacy) { return "data: \(s)\n\n" }
+        return chunk
+    }
+}
+#endif

package/ios/Sources/DVAIFoundationCore/FoundationPluginState.swift

@@ -0,0 +1,136 @@
+// Internal/FoundationPluginState.swift
+//
+// Owns the running state of the capacitor-foundation plugin: the embedded
+// HTTP server and the FoundationHandlers instance. All access is serialised
+// through actor isolation.
+//
+// Differences from capacitor-llama's FoundationPluginState:
+//   - No model bridge: Apple FM owns the model inside `LanguageModelSession`,
+//     so there is no `LlamaCppBridge` analogue.
+//   - No `modelPath` opt: the system model is implicit.
+//   - iOS 26.0+ runtime gate: FoundationHandlers is `@available(iOS 26.0,
+//     macOS 26.0, *)`. We must check at runtime AND at the compiler level
+//     (the inner `#available` is required so the compiler permits us to
+//     instantiate FoundationHandlers).
+//   - No embeddingMode/mmprojPath/gpuLayers/contextSize/threads opts:
+//     Apple FM does not expose any of those knobs.
+
+import Foundation
+#if !COCOAPODS
+import DVAISharedCore
+#endif
+
+public actor FoundationPluginState {
+    private var server: HttpServer?
+    /// Type-erased reference to the live `FoundationHandlers` instance.
+    /// Stored as `AnyObject?` rather than `FoundationHandlers?` so we
+    /// don't have to mark the entire actor `@available(iOS 26.0, *)` —
+    /// the concrete type is only ever materialised inside an `#available`
+    /// block in `start()`. We never need to call methods on it from here
+    /// (Telegraph holds the only callable reference, via `installRoutes`),
+    /// so a strong-but-opaque retain is sufficient.
+    private var handlers: AnyObject?
+    private(set) var modelId: String = "apple-foundation-3b"
+    private(set) var isRunning: Bool = false
+    private(set) var baseUrl: String?
+    private(set) var port: Int?
+
+    public init() {}
+
+    /// Start the plugin: gate on iOS 26.0+, bind server, install routes.
+    /// - Returns dictionary suitable for Capacitor's `call.resolve(...)`.
+    public func start(opts: [String: Any]) async throws -> [String: Any] {
+        if isRunning { try await stopInternal() }
+
+        // Compile-time guard: on hosts where the FoundationModels framework
+        // isn't available at all (older Xcode), we can't run.
+        #if !canImport(FoundationModels)
+        throw NSError(
+            domain: "DVAIBridgeFoundation",
+            code: 500,
+            userInfo: [NSLocalizedDescriptionKey: "FoundationModels framework not available on this build."]
+        )
+        #else
+        // Runtime gate: even if the framework is linkable, the iOS device
+        // must be on iOS 26.0+ for the `LanguageModelSession` symbols to
+        // exist. This is the user-facing error path for older devices.
+        guard #available(iOS 26.0, macOS 26.0, *) else {
+            throw NSError(
+                domain: "DVAIBridgeFoundation",
+                code: 400,
+                userInfo: [NSLocalizedDescriptionKey: "Apple Foundation Models requires iOS 26.0 or later. The capacitor-foundation backend cannot start on this device."]
+            )
+        }
+
+        let httpBasePort = opts["httpBasePort"] as? Int ?? 38883
+        let httpMaxPortAttempts = opts["httpMaxPortAttempts"] as? Int ?? 16
+        let corsRaw = opts["corsOrigin"]
+        let corsConfig = parseCors(corsRaw)
+        let modelIdOverride = opts["modelId"] as? String
+        let modelId = modelIdOverride ?? "apple-foundation-3b"
+
+        // Build handlers first; Hummingbird requires routes to be
+        // installed at Application construction time, so installRoutes
+        // → tryBind is the mandatory order.
+        let handlers = FoundationHandlers(modelId: modelId)
+        let ctx = HandlerContext(modelId: modelId, backendName: "foundation")
+        let server = HttpServer()
+        await server.installRoutes(handlers: handlers, ctx: ctx, corsConfig: corsConfig)
+
+        // Bind server with port-fallback (mirrors capacitor-llama).
+        let port = try await server.tryBind(
+            basePort: httpBasePort,
+            maxAttempts: httpMaxPortAttempts,
+            host: "127.0.0.1"
+        )
+
+        self.handlers = handlers
+        self.modelId = modelId
+        self.server = server
+        self.port = port
+        self.baseUrl = "http://127.0.0.1:\(port)/v1"
+        self.isRunning = true
+
+        return [
+            "baseUrl": self.baseUrl!,
+            "port": port,
+            "backend": "foundation",
+            "modelId": modelId,
+        ]
+        #endif
+    }
+
+    /// Stop the plugin: drop handlers, stop server. Idempotent.
+    public func stop() async throws {
+        try await stopInternal()
+    }
+
+    private func stopInternal() async throws {
+        await server?.stop()
+        server = nil
+        handlers = nil
+        modelId = "apple-foundation-3b"
+        baseUrl = nil
+        port = nil
+        isRunning = false
+    }
+
+    /// Snapshot of the current running state, suitable for `call.resolve(...)`.
+    public func statusInfo() -> [String: Any] {
+        var dict: [String: Any] = ["running": isRunning]
+        if let baseUrl = baseUrl { dict["baseUrl"] = baseUrl }
+        if isRunning { dict["backend"] = "foundation" }
+        return dict
+    }
+
+    /// Parse the CORS option from the start opts dict.
+    private func parseCors(_ raw: Any?) -> CORSConfig {
+        if let s = raw as? String {
+            return s == "*" ? .wildcard : .exact(s)
+        }
+        if let arr = raw as? [String] {
+            return .allowlist(arr)
+        }
+        return .wildcard
+    }
+}

package/ios/Tests/DVAIFoundationCoreTests/FoundationHandlersTest.swift

@@ -0,0 +1,152 @@
+// Tests/DVAICapacitorFoundationTests/FoundationHandlersTest.swift
+//
+// Unit tests for the `FoundationHandlers` paths that don't require a real
+// `LanguageModelSession`:
+//   1. handleEmbeddings → 400 with spec §8.5 wording.
+//   2. handleModels → 200 with the canned single-entry list.
+//   3. handleChatCompletion (image content part) → 400 with spec §8.5 wording.
+//   4. handleChatCompletion (audio content part) → 400 with spec §8.5 wording.
+//   5. handleChatCompletion (missing 'messages') → 400 short-circuit.
+//   6. handleChatCompletion (empty 'messages' array) → 400 short-circuit.
+//
+// The chat happy path goes through `LanguageModelSession` and is verified
+// on a real iOS device via the instrumented / manual tier (per Task 40
+// plan note: "handleChatCompletion happy path requires real device — skip
+// in unit tests").
+//
+// The whole class is guarded by `#if canImport(FoundationModels)`. On a
+// macOS host without FoundationModels (older Xcode), the tests compile
+// out and the smoke test still runs.
+
+import XCTest
+@testable import DVAIFoundationCore
+import DVAISharedCore
+
+#if canImport(FoundationModels)
+import FoundationModels
+
+@available(iOS 26.0, macOS 26.0, *)
+final class FoundationHandlersTest: XCTestCase {
+
+    private func ctx() -> HandlerContext {
+        HandlerContext(modelId: "apple-foundation-3b", backendName: "foundation")
+    }
+
+    func testEmbeddingsReturnsSpecConformant400() async throws {
+        let handlers = FoundationHandlers()
+        let response = try await handlers.handleEmbeddings(
+            body: ["input": "hi"],
+            ctx: ctx()
+        )
+        if case .error(let status, let message) = response {
+            XCTAssertEqual(status, 400)
+            XCTAssertTrue(
+                message.contains("Embeddings not supported on Apple Foundation Models"),
+                "Expected spec §8.5 wording, got: \(message)"
+            )
+        } else {
+            XCTFail("Expected .error(400, ...), got \(response)")
+        }
+    }
+
+    func testModelsReturnsAppleFoundationEntry() async throws {
+        let handlers = FoundationHandlers()
+        let response = try await handlers.handleModels(ctx: ctx())
+        guard case .json(let status, let body) = response,
+              let dict = body as? [String: Any],
+              let data = dict["data"] as? [[String: Any]],
+              let first = data.first else {
+            XCTFail("Expected models list, got \(response)")
+            return
+        }
+        XCTAssertEqual(status, 200)
+        XCTAssertEqual(dict["object"] as? String, "list")
+        XCTAssertEqual(first["id"] as? String, "apple-foundation-3b")
+        XCTAssertEqual(first["object"] as? String, "model")
+        XCTAssertEqual(first["owned_by"] as? String, "apple")
+    }
+
+    func testChatCompletionImagePartReturns400() async throws {
+        let handlers = FoundationHandlers()
+        let body: [String: Any] = [
+            "messages": [[
+                "role": "user",
+                "content": [
+                    ["type": "text", "text": "describe this"],
+                    ["type": "image_url", "image_url": ["url": "data:image/png;base64,iVBORw0KGgo="]],
+                ],
+            ]],
+        ]
+        let response = try await handlers.handleChatCompletion(body: body, ctx: ctx())
+        if case .error(let status, let message) = response {
+            XCTAssertEqual(status, 400)
+            XCTAssertTrue(
+                message.contains("Image input not supported by Apple Foundation Models"),
+                "Expected spec §8.5 image-rejection wording, got: \(message)"
+            )
+        } else {
+            XCTFail("Expected .error(400, ...), got \(response)")
+        }
+    }
+
+    func testChatCompletionAudioPartReturns400() async throws {
+        let handlers = FoundationHandlers()
+        let body: [String: Any] = [
+            "messages": [[
+                "role": "user",
+                "content": [
+                    ["type": "input_audio", "input_audio": ["data": "AAAA", "format": "pcm16"]],
+                    ["type": "text", "text": "transcribe"],
+                ],
+            ]],
+        ]
+        let response = try await handlers.handleChatCompletion(body: body, ctx: ctx())
+        if case .error(let status, let message) = response {
+            XCTAssertEqual(status, 400)
+            XCTAssertTrue(
+                message.contains("Audio input not supported by Apple Foundation Models"),
+                "Expected spec §8.5 audio-rejection wording, got: \(message)"
+            )
+        } else {
+            XCTFail("Expected .error(400, ...), got \(response)")
+        }
+    }
+
+    func testChatCompletionMissingMessagesReturns400() async throws {
+        let handlers = FoundationHandlers()
+        // Body without a 'messages' key — must short-circuit to 400 before
+        // any session work, mirroring LlamaHandlers' behaviour.
+        let response = try await handlers.handleChatCompletion(body: [:], ctx: ctx())
+        if case .error(let status, let message) = response {
+            XCTAssertEqual(status, 400)
+            XCTAssertTrue(
+                message.contains("Missing 'messages'"),
+                "Expected missing-messages 400, got: \(message)"
+            )
+        } else {
+            XCTFail("Expected .error(400, ...), got \(response)")
+        }
+    }
+
+    func testChatCompletionEmptyMessagesReturns400() async throws {
+        let handlers = FoundationHandlers()
+        // Empty messages array — must short-circuit to 400 before any
+        // session work. Without this guard the prompt would be empty and
+        // Apple FM behaviour is undefined.
+        let body: [String: Any] = ["messages": [[String: Any]]()]
+        let response = try await handlers.handleChatCompletion(body: body, ctx: ctx())
+        if case .error(let status, let message) = response {
+            XCTAssertEqual(status, 400)
+            XCTAssertTrue(
+                message.contains("Empty messages"),
+                "Expected empty-messages 400, got: \(message)"
+            )
+        } else {
+            XCTFail("Expected .error(400, ...), got \(response)")
+        }
+    }
+}
+#else
+// macOS host without FoundationModels — tests compile out at this guard.
+// The smoke test (in SmokeTest.swift) still runs.
+#endif

package/ios/Tests/DVAIFoundationCoreTests/FoundationPluginStateTest.swift

@@ -0,0 +1,86 @@
+// Tests/DVAICapacitorFoundationTests/PluginStateTest.swift
+//
+// Unit tests for the `FoundationPluginState` actor — the lifecycle owner wired up
+// in Task 41. Tests focus on state-machine paths that don't require a
+// real Apple FM `LanguageModelSession`:
+//
+//   1. `statusInfo()` reports `running:false` initially.
+//   2. `stop()` is idempotent before any `start()`.
+//   3. Default-modelId behaviour (verified indirectly via runtime gate
+//      paths described below).
+//
+// We intentionally do NOT test the happy `start()` path here:
+//   - It requires Apple FM to actually be available on the test runner.
+//   - On the iOS Simulator destination on Xcode 26+, `#available(iOS
+//     26.0, *)` returns true and `start()` would then attempt to bind
+//     a real Telegraph server and instantiate `LanguageModelSession`.
+//     A real session call needs a device with the FM model installed.
+//   - That path is exercised by the device-tier tests when a real
+//     iOS 26+ device is wired up.
+//
+// The runtime-gate "iOS too old" error path is similarly hard to hit
+// reliably from XCTest: on Xcode 26 + iOS 26 Simulator the gate returns
+// true, on macOS host the build itself only sees the macOS availability,
+// and on older Xcodes the whole `FoundationHandlers` symbol compiles out
+// (so FoundationPluginState's `#if canImport(FoundationModels)` branch is dead).
+// We therefore skip a direct test of the gate's error message and rely
+// on the structural fact that `FoundationPluginState.start()` literally does
+// `guard #available(iOS 26.0, ...)` before any other work — verified by
+// code review.
+
+import XCTest
+@testable import DVAIFoundationCore
+
+final class PluginStateTest: XCTestCase {
+
+    func testStatusInfoReportsNotRunningInitially() async {
+        let state = FoundationPluginState()
+        let info = await state.statusInfo()
+        XCTAssertEqual(info["running"] as? Bool, false)
+        XCTAssertNil(info["baseUrl"], "baseUrl should be absent before start()")
+        XCTAssertNil(info["backend"], "backend should be absent before start()")
+    }
+
+    func testStopBeforeStartIsIdempotent() async throws {
+        let state = FoundationPluginState()
+        // Calling stop() on an idle state must not throw.
+        try await state.stop()
+        let info = await state.statusInfo()
+        XCTAssertEqual(info["running"] as? Bool, false)
+    }
+
+    func testStopAfterStopRemainsIdempotent() async throws {
+        let state = FoundationPluginState()
+        try await state.stop()
+        try await state.stop()
+        let info = await state.statusInfo()
+        XCTAssertEqual(info["running"] as? Bool, false)
+    }
+
+    /// On hosts where `FoundationModels` does not link at all (older Xcode),
+    /// `start()` rejects with a clear "framework not available" message.
+    /// On Xcode 26+ this branch is dead — the alternate `iOS 26.0+` runtime
+    /// gate kicks in instead, and on the iOS 26 Simulator that gate passes
+    /// and `start()` proceeds to bind a real server. We therefore only
+    /// assert that `start()` either succeeds or throws — never silently
+    /// resolves to an inconsistent state.
+    func testStartEitherSucceedsOrThrowsCleanly() async {
+        let state = FoundationPluginState()
+        do {
+            // Use a high port range to avoid conflicting with anything on
+            // CI. If start succeeds, immediately stop to free the socket.
+            _ = try await state.start(opts: [
+                "httpBasePort": 39300,
+                "httpMaxPortAttempts": 4,
+            ])
+            // Cleanup so subsequent tests aren't affected.
+            try? await state.stop()
+        } catch {
+            // Any error path is acceptable for this test — we just want
+            // to assert that the failure surfaces cleanly and the state
+            // stays "not running".
+            let info = await state.statusInfo()
+            XCTAssertEqual(info["running"] as? Bool, false)
+        }
+    }
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@dvai-bridge/ios-foundation-core",
+  "version": "4.0.1",
+  "description": "DVAI-Bridge iOS Foundation Models core — pure Swift embedded HTTP server + handlers wrapping Apple's LanguageModelSession. Capacitor-free. Requires iOS 26.0+ at runtime; iOS 18.1+ at link-time.",
+  "author": "Deep Chakraborty <https://github.com/dk013>",
+  "license": "Custom (See LICENSE)",
+  "main": "Package.swift",
+  "files": [
+    "ios/Sources",
+    "ios/Tests",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}