catalyst-core 1.0.0 → 1.0.1-canary.1

package/dist/native/iosnativeWebView/CoreLogic/Tests/CatalystCoreLogicTests/FrameworkServerUtilsLoopbackTests.swift

@@ -2,6 +2,13 @@ import XCTest
 import Foundation
 @testable import CatalystCoreLogic
 
+/// Thrown on CI when the loopback server never becomes reachable, so the test
+/// fails instead of silently skipping and dropping coverage.
+private struct LoopbackServerUnavailable: Error, CustomStringConvertible {
+    let message: String
+    var description: String { message }
+}
+
 /**
  * In-process loopback HTTP tests for FrameworkServerUtils.
  *
@@ -18,10 +25,10 @@ import Foundation
  * math showed 95% package-wide wasn't reachable while FrameworkServerUtils
  * stayed at ~35%.
  *
- * Same "server may not start in this sandbox" guard as the existing test
- * file — network restrictions in some CI/sandbox environments can prevent
- * NWListener from binding. Tests skip (not fail) in that case, consistent
- * with the established pattern.
+ * Each test waits for the listener to accept connections before sending a
+ * request (see requireRunningServer). Outside CI, a sandbox that cannot bind
+ * skips the test; on CI an unavailable server fails it, so loopback coverage
+ * can never silently drop and skew the coverage-regression baseline.
  */
 final class FrameworkServerUtilsLoopbackTests: XCTestCase {
 
@@ -39,22 +46,69 @@ final class FrameworkServerUtilsLoopbackTests: XCTestCase {
         }
         tempFileURL = nil
 
-        if frameworkServer.isRunning() {
-            frameworkServer.stopServer()
-        }
+        // Unconditional: a listener that failed asynchronously reports
+        // isRunning() == false but still holds its timer and listener, which
+        // must not leak into later tests.
+        frameworkServer.stopServer()
         frameworkServer = nil
         super.tearDown()
     }
 
-    /// Starts the server and waits for NWListener's async stateUpdateHandler
-    /// to settle, mirroring the pattern already established in
-    /// FrameworkServerUtilsTests.swift. Returns false (and the caller should
-    /// skip) if the server isn't actually running afterward.
-    private func startServerAndWaitReady() -> Bool {
-        let started = frameworkServer.startServer()
-        guard started else { return false }
-        Thread.sleep(forTimeInterval: 0.3)
-        return frameworkServer.isRunning()
+    /// Starts the server and blocks until it is actually accepting TCP
+    /// connections, so no test sends a request before NWListener is `.ready`.
+    ///
+    /// NWListener reports readiness asynchronously and `startServer()` returns
+    /// before it settles, so a fixed sleep is a race that loses on slow CI
+    /// runners. Instead this polls a raw loopback connect until it succeeds or
+    /// `readinessTimeout` elapses.
+    ///
+    /// If the server never comes up: on CI (`CI` env var set) the test fails,
+    /// because a silent skip would drop the loopback coverage and make the
+    /// coverage baseline non-deterministic. Outside CI (e.g. a restricted local
+    /// sandbox that cannot bind) it skips, as before.
+    private func requireRunningServer() throws {
+        let readinessTimeout: TimeInterval = 10
+
+        guard frameworkServer.startServer() else {
+            try serverUnavailable("startServer() returned false")
+            return
+        }
+
+        let deadline = Date().addingTimeInterval(readinessTimeout)
+        while Date() < deadline {
+            if frameworkServer.isRunning(),
+               Self.canConnect(toLoopbackPort: frameworkServer.getServerPort()) {
+                return
+            }
+            Thread.sleep(forTimeInterval: 0.02)
+        }
+        try serverUnavailable("not accepting connections within \(Int(readinessTimeout))s")
+    }
+
+    private func serverUnavailable(_ reason: String) throws {
+        let message = "Loopback server unavailable: \(reason)"
+        if ProcessInfo.processInfo.environment["CI"] != nil {
+            throw LoopbackServerUnavailable(message: message)
+        }
+        throw XCTSkip("\(message) — skipping loopback test outside CI")
+    }
+
+    private static func canConnect(toLoopbackPort port: UInt16) -> Bool {
+        let fd = socket(AF_INET, SOCK_STREAM, 0)
+        guard fd != -1 else { return false }
+        defer { close(fd) }
+
+        var addr = sockaddr_in()
+        addr.sin_family = sa_family_t(AF_INET)
+        addr.sin_port = port.bigEndian
+        addr.sin_addr.s_addr = inet_addr("127.0.0.1")
+
+        let result = withUnsafePointer(to: &addr) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                connect(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        }
+        return result == 0
     }
 
     private func serveTemporaryFile(content: String, fileName: String, mimeType: String) throws -> String? {
@@ -79,12 +133,89 @@ final class FrameworkServerUtilsLoopbackTests: XCTestCase {
         return (httpResponse, data)
     }
 
+    /// Opens a raw TCP client to the running server and returns its fd.
+    private func openRawClient() throws -> Int32 {
+        let fd = socket(AF_INET, SOCK_STREAM, 0)
+        try XCTSkipIf(fd == -1, "could not create client socket")
+
+        var addr = sockaddr_in()
+        addr.sin_family = sa_family_t(AF_INET)
+        addr.sin_port = frameworkServer.getServerPort().bigEndian
+        addr.sin_addr.s_addr = inet_addr("127.0.0.1")
+        let result = withUnsafePointer(to: &addr) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                connect(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        }
+        guard result == 0 else {
+            close(fd)
+            throw LoopbackServerUnavailable(message: "raw client could not connect (errno \(errno))")
+        }
+        return fd
+    }
+
+    /// Polls until `condition` holds or `timeout` elapses. Returns whether it held.
+    private func waitUntil(timeout: TimeInterval = 5, _ condition: () -> Bool) -> Bool {
+        let deadline = Date().addingTimeInterval(timeout)
+        while Date() < deadline {
+            if condition() { return true }
+            Thread.sleep(forTimeInterval: 0.01)
+        }
+        return condition()
+    }
+
+    // MARK: - Connection lifecycle
+
+    /// stopServer() must cancel and clear connections that are still open. A
+    /// request/response test only hits this when a keep-alive connection
+    /// happens to be alive at teardown, which is timing-dependent; holding a
+    /// client open here makes that path run every time.
+    func testStopServer_WithOpenConnection_ClearsActiveConnections() throws {
+        try requireRunningServer()
+
+        let client = try openRawClient()
+        defer { close(client) }
+
+        XCTAssertTrue(
+            waitUntil { frameworkServer.activeConnectionCount() >= 1 },
+            "server never registered the open client connection"
+        )
+
+        frameworkServer.stopServer()
+
+        XCTAssertEqual(frameworkServer.activeConnectionCount(), 0)
+        XCTAssertFalse(frameworkServer.isRunning())
+    }
+
+    /// A client that resets mid-request (RST via zero-linger close) must be
+    /// dropped from the tracking set, whichever of the server's failed or
+    /// cancelled connection handlers observes it.
+    func testClientResetMidRequest_RemovesConnection() throws {
+        try requireRunningServer()
+
+        let client = try openRawClient()
+        XCTAssertTrue(
+            waitUntil { frameworkServer.activeConnectionCount() >= 1 },
+            "server never registered the client connection"
+        )
+
+        let partialRequest = Array("GET /partial".utf8)
+        _ = partialRequest.withUnsafeBytes { send(client, $0.baseAddress, $0.count, 0) }
+
+        var linger = linger(l_onoff: 1, l_linger: 0)
+        setsockopt(client, SOL_SOCKET, SO_LINGER, &linger, socklen_t(MemoryLayout<linger>.size))
+        close(client)
+
+        XCTAssertTrue(
+            waitUntil { frameworkServer.activeConnectionCount() == 0 },
+            "connection was not removed after the client reset"
+        )
+    }
+
     // MARK: - Status endpoint
 
     func testStatusEndpoint_ReturnsRunningJSON() async throws {
-        guard startServerAndWaitReady() else {
-            throw XCTSkip("Server failed to start in this environment — skipping loopback test")
-        }
+        try requireRunningServer()
 
         let port = frameworkServer.getServerPort()
         let sessionId = frameworkServer.getSessionId()
@@ -104,9 +235,7 @@ final class FrameworkServerUtilsLoopbackTests: XCTestCase {
     // MARK: - File serving: success path
 
     func testFileRequest_ServesRealFileContent() async throws {
-        guard startServerAndWaitReady() else {
-            throw XCTSkip("Server failed to start in this environment — skipping loopback test")
-        }
+        try requireRunningServer()
 
         let content = "loopback test file content \(UUID().uuidString)"
         let servedURLString = try XCTUnwrap(
@@ -122,9 +251,7 @@ final class FrameworkServerUtilsLoopbackTests: XCTestCase {
     }
 
     func testFileRequest_ContentLengthHeaderMatchesActualBytes() async throws {
-        guard startServerAndWaitReady() else {
-            throw XCTSkip("Server failed to start in this environment — skipping loopback test")
-        }
+        try requireRunningServer()
 
         let content = String(repeating: "x", count: 5000)
         let servedURLString = try XCTUnwrap(
@@ -143,9 +270,7 @@ final class FrameworkServerUtilsLoopbackTests: XCTestCase {
     // MARK: - File serving: error paths
 
     func testFileRequest_UnknownFileId_Returns404() async throws {
-        guard startServerAndWaitReady() else {
-            throw XCTSkip("Server failed to start in this environment — skipping loopback test")
-        }
+        try requireRunningServer()
 
         let port = frameworkServer.getServerPort()
         let sessionId = frameworkServer.getSessionId()
@@ -157,9 +282,7 @@ final class FrameworkServerUtilsLoopbackTests: XCTestCase {
     }
 
     func testInvalidRoute_Returns404() async throws {
-        guard startServerAndWaitReady() else {
-            throw XCTSkip("Server failed to start in this environment — skipping loopback test")
-        }
+        try requireRunningServer()
 
         let port = frameworkServer.getServerPort()
         let url = try XCTUnwrap(URL(string: "http://localhost:\(port)/not-a-real-route"))
@@ -170,9 +293,7 @@ final class FrameworkServerUtilsLoopbackTests: XCTestCase {
     }
 
     func testNonGETMethod_Returns405() async throws {
-        guard startServerAndWaitReady() else {
-            throw XCTSkip("Server failed to start in this environment — skipping loopback test")
-        }
+        try requireRunningServer()
 
         let port = frameworkServer.getServerPort()
         let sessionId = frameworkServer.getSessionId()
@@ -186,9 +307,7 @@ final class FrameworkServerUtilsLoopbackTests: XCTestCase {
     // MARK: - Physical file missing after being registered (not just unknown id)
 
     func testFileRequest_PhysicalFileDeletedAfterRegistration_Returns404() async throws {
-        guard startServerAndWaitReady() else {
-            throw XCTSkip("Server failed to start in this environment — skipping loopback test")
-        }
+        try requireRunningServer()
 
         let servedURLString = try XCTUnwrap(
             try serveTemporaryFile(content: "will be deleted from cache", fileName: "loopback-vanish.txt", mimeType: "text/plain")
@@ -218,9 +337,7 @@ final class FrameworkServerUtilsLoopbackTests: XCTestCase {
     // MARK: - removeServedFile
 
     func testRemoveServedFile_SubsequentRequestReturns404() async throws {
-        guard startServerAndWaitReady() else {
-            throw XCTSkip("Server failed to start in this environment — skipping loopback test")
-        }
+        try requireRunningServer()
 
         let servedURLString = try XCTUnwrap(
             try serveTemporaryFile(content: "to be removed", fileName: "loopback-remove.txt", mimeType: "text/plain")

package/dist/native/iosnativeWebView/CoreLogic/Tests/CatalystCoreLogicTests/FrameworkServerUtilsNativeAITests.swift

@@ -0,0 +1,351 @@
+import XCTest
+import Foundation
+import Network
+@testable import CatalystCoreLogic
+
+/// Loopback tests for the native-AI routes (/ai/stream, /ai/generate) using a stub supplier,
+/// so the transport is covered without any inference library. Mirrors the pattern in
+/// FrameworkServerUtilsLoopbackTests (skip outside CI if the sandbox cannot bind, fail on CI).
+final class FrameworkServerUtilsNativeAITests: XCTestCase {
+
+    private var server: FrameworkServerUtils!
+
+    override func setUp() {
+        super.setUp()
+        server = FrameworkServerUtils.shared
+    }
+
+    override func tearDown() {
+        server.setNativeAiSupplier(nil)
+        server.setNativeSystemPrompt("")
+        server.stopServer()
+        server = nil
+        super.tearDown()
+    }
+
+    // MARK: - Helpers
+
+    private func requireRunningServer() throws {
+        guard server.startServer() else { return try unavailable("startServer() returned false") }
+        let deadline = Date().addingTimeInterval(10)
+        while Date() < deadline {
+            if server.isRunning(), Self.canConnect(port: server.getServerPort()) { return }
+            Thread.sleep(forTimeInterval: 0.02)
+        }
+        try unavailable("not accepting connections")
+    }
+
+    private func unavailable(_ reason: String) throws {
+        if ProcessInfo.processInfo.environment["CI"] != nil {
+            XCTFail("Loopback server unavailable: \(reason)")
+            throw XCTSkip("unavailable")
+        }
+        throw XCTSkip("Loopback server unavailable: \(reason)")
+    }
+
+    private static func canConnect(port: UInt16) -> Bool {
+        let fd = socket(AF_INET, SOCK_STREAM, 0)
+        guard fd != -1 else { return false }
+        defer { close(fd) }
+        var addr = sockaddr_in()
+        addr.sin_family = sa_family_t(AF_INET)
+        addr.sin_port = port.bigEndian
+        addr.sin_addr.s_addr = inet_addr("127.0.0.1")
+        return withUnsafePointer(to: &addr) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                connect(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        } == 0
+    }
+
+    private func url(_ path: String) throws -> URL {
+        try XCTUnwrap(URL(string: "http://localhost:\(server.getServerPort())/framework-\(server.getSessionId())/ai/\(path)"))
+    }
+
+    private func post(_ path: String, json: [String: Any]) async throws -> URLRequest {
+        var request = URLRequest(url: try url(path))
+        request.httpMethod = "POST"
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.httpBody = try JSONSerialization.data(withJSONObject: json)
+        return request
+    }
+
+    private func readFrames(_ request: URLRequest) async throws -> (HTTPURLResponse, [[String: Any]]) {
+        let (bytes, response) = try await URLSession.shared.bytes(for: request)
+        var frames: [[String: Any]] = []
+        for try await line in bytes.lines where line.hasPrefix("data: ") {
+            let payload = Data(line.dropFirst(6).utf8)
+            frames.append(try XCTUnwrap(JSONSerialization.jsonObject(with: payload) as? [String: Any]))
+        }
+        return (try XCTUnwrap(response as? HTTPURLResponse), frames)
+    }
+
+    private func stubSupplier(tokens: [String], conversationId: String = "conv-1") -> NativeAISupplier {
+        return { _, _, _ in
+            (conversationId, AsyncThrowingStream { continuation in
+                for token in tokens { continuation.yield(token) }
+                continuation.finish()
+            })
+        }
+    }
+
+    // MARK: - /ai/stream
+
+    func testStream_EmitsConversationIdTokensThenDone() async throws {
+        try requireRunningServer()
+        server.setNativeAiSupplier(stubSupplier(tokens: ["Hel", "lo \"quoted\" / ✓"]))
+
+        let (response, frames) = try await readFrames(try await post("stream", json: ["prompt": "hi"]))
+
+        XCTAssertEqual(response.statusCode, 200)
+        XCTAssertTrue(response.value(forHTTPHeaderField: "Content-Type")?.contains("text/event-stream") ?? false)
+        XCTAssertEqual(frames.count, 4)
+        XCTAssertEqual(frames[0]["conversationId"] as? String, "conv-1")
+        XCTAssertEqual(frames[1]["token"] as? String, "Hel")
+        XCTAssertEqual(frames[2]["token"] as? String, "lo \"quoted\" / ✓")
+        XCTAssertEqual(frames[3]["done"] as? Bool, true)
+    }
+
+    func testStream_PrependsSystemPromptAndForwardsGenConfigAndConversationId() async throws {
+        try requireRunningServer()
+        let seen = LockedBox<(String, [String: Any], String?)?>(nil)
+        server.setNativeSystemPrompt("SYSTEM")
+        server.setNativeAiSupplier { prompt, genConfig, convId in
+            seen.value = (prompt, genConfig, convId)
+            return ("c", AsyncThrowingStream { $0.finish() })
+        }
+
+        _ = try await readFrames(try await post("stream", json: [
+            "prompt": "hello", "genConfig": ["temperature": 0.5], "conversationId": "prev",
+        ]))
+
+        let value = try XCTUnwrap(seen.value)
+        XCTAssertEqual(value.0, "SYSTEM\n\nhello")
+        XCTAssertEqual(value.1["temperature"] as? Double, 0.5)
+        XCTAssertEqual(value.2, "prev")
+    }
+
+    func testStream_NoSupplier_EmitsNotReadyErrorFrame() async throws {
+        try requireRunningServer()
+        let (_, frames) = try await readFrames(try await post("stream", json: ["prompt": "hi"]))
+        XCTAssertEqual(frames.first?["code"] as? String, NativeAIErrorCode.streamNotReady)
+        XCTAssertNotNil(frames.first?["error"] as? String)
+    }
+
+    func testStream_EmptyPrompt_EmitsInvalidRequestFrame() async throws {
+        try requireRunningServer()
+        server.setNativeAiSupplier(stubSupplier(tokens: ["x"]))
+        let (_, frames) = try await readFrames(try await post("stream", json: ["prompt": ""]))
+        XCTAssertEqual(frames.first?["code"] as? String, NativeAIErrorCode.invalidRequestBody)
+    }
+
+    func testStream_SupplierThrows_EmitsErrorFrameWithEngineCode() async throws {
+        try requireRunningServer()
+        server.setNativeAiSupplier { _, _, _ in throw NativeAIError(message: "model exploded", code: "AI-006") }
+        let (_, frames) = try await readFrames(try await post("stream", json: ["prompt": "hi"]))
+        XCTAssertEqual(frames.first?["error"] as? String, "model exploded")
+        XCTAssertEqual(frames.first?["code"] as? String, "AI-006")
+    }
+
+    func testStream_MidStreamFailure_EmitsTokensThenError() async throws {
+        try requireRunningServer()
+        server.setNativeAiSupplier { _, _, _ in
+            ("c", AsyncThrowingStream { continuation in
+                continuation.yield("partial")
+                continuation.finish(throwing: NativeAIError(message: "context window exceeded"))
+            })
+        }
+        let (_, frames) = try await readFrames(try await post("stream", json: ["prompt": "hi"]))
+        XCTAssertEqual(frames.map { $0.keys.sorted().joined(separator: ",") }, ["conversationId", "token", "code,error"])
+    }
+
+    func testStream_TokenArrivingAfterGap_StillDelivered() async throws {
+        // Short gap only: the 30s connection-timeout exemption (cancelConnectionTimeout) is not exercised here.
+        try requireRunningServer()
+        server.setNativeAiSupplier { _, _, _ in
+            ("c", AsyncThrowingStream { continuation in
+                Task<Void, Never> {
+                    try? await Task.sleep(nanoseconds: 300_000_000)
+                    continuation.yield("late")
+                    continuation.finish()
+                }
+            })
+        }
+        let (_, frames) = try await readFrames(try await post("stream", json: ["prompt": "hi"]))
+        XCTAssertEqual(frames.last?["done"] as? Bool, true)
+    }
+
+    func testStream_ClientDisconnect_TerminatesUpstreamStream() async throws {
+        try requireRunningServer()
+        let terminated = expectation(description: "token stream terminated after client disconnect")
+        server.setNativeAiSupplier { _, _, _ in
+            ("c", AsyncThrowingStream { continuation in
+                continuation.onTermination = { _ in terminated.fulfill() }
+                Task<Void, Never> {
+                    while !Task.isCancelled {
+                        if case .terminated = continuation.yield("tick") { break }
+                        try? await Task.sleep(nanoseconds: 20_000_000)
+                    }
+                }
+            })
+        }
+
+        let (bytes, _) = try await URLSession.shared.bytes(for: try await post("stream", json: ["prompt": "hi"]))
+        var iterator = bytes.lines.makeAsyncIterator()
+        _ = try await iterator.next()
+        bytes.task.cancel()
+
+        await fulfillment(of: [terminated], timeout: 10)
+    }
+
+    // MARK: - Body framing
+
+    func testStream_BodyArrivingInSeparateWriteFromHeaders_IsAssembled() async throws {
+        try requireRunningServer()
+        server.setNativeAiSupplier(stubSupplier(tokens: ["ok"]))
+
+        let body = #"{"prompt":"split"}"#
+        let head = "POST /framework-\(server.getSessionId())/ai/stream HTTP/1.1\r\nHost: localhost\r\nContent-Type: application/json\r\nContent-Length: \(body.utf8.count)\r\n\r\n"
+        let reply = try Self.rawExchange(port: server.getServerPort(), writes: [head, body], pauseBetween: 0.2)
+
+        XCTAssertTrue(reply.contains("200 OK"))
+        XCTAssertTrue(reply.contains("\"token\":\"ok\""))
+        XCTAssertTrue(reply.contains("\"done\":true"))
+    }
+
+    func testPost_OversizedContentLength_Returns413() async throws {
+        try requireRunningServer()
+        let head = "POST /framework-\(server.getSessionId())/ai/stream HTTP/1.1\r\nContent-Length: 99999999\r\n\r\n"
+        let reply = try Self.rawExchange(port: server.getServerPort(), writes: [head], pauseBetween: 0)
+        XCTAssertTrue(reply.contains("413"))
+    }
+
+    func testPost_ClientClosesBeforeSendingDeclaredBody_Returns400() async throws {
+        try requireRunningServer()
+        server.setNativeAiSupplier(stubSupplier(tokens: ["must not run"]))
+        let head = "POST /framework-\(server.getSessionId())/ai/stream HTTP/1.1\r\nContent-Length: 50\r\n\r\n"
+        let reply = try Self.rawExchange(
+            port: server.getServerPort(), writes: [head, "{\"prompt\":\"x\"}"], pauseBetween: 0.1, halfCloseAfterWrites: true
+        )
+        XCTAssertTrue(reply.contains("400"))
+        XCTAssertFalse(reply.contains("must not run"))
+    }
+
+    /// Writes each chunk on a plain TCP socket (with a pause between), then reads until the server closes.
+    private static func rawExchange(
+        port: UInt16, writes: [String], pauseBetween: TimeInterval, halfCloseAfterWrites: Bool = false
+    ) throws -> String {
+        let fd = socket(AF_INET, SOCK_STREAM, 0)
+        guard fd != -1 else { throw XCTSkip("socket() failed") }
+        defer { close(fd) }
+        var tv = timeval(tv_sec: 5, tv_usec: 0)
+        setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &tv, socklen_t(MemoryLayout<timeval>.size))
+        var addr = sockaddr_in()
+        addr.sin_family = sa_family_t(AF_INET)
+        addr.sin_port = port.bigEndian
+        addr.sin_addr.s_addr = inet_addr("127.0.0.1")
+        let connected = withUnsafePointer(to: &addr) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                connect(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        }
+        guard connected == 0 else { throw XCTSkip("connect() failed") }
+
+        for chunk in writes {
+            _ = chunk.withCString { send(fd, $0, strlen($0), 0) }
+            if pauseBetween > 0 { Thread.sleep(forTimeInterval: pauseBetween) }
+        }
+
+        if halfCloseAfterWrites { shutdown(fd, SHUT_WR) }
+
+        var received = Data()
+        var buffer = [UInt8](repeating: 0, count: 4096)
+        while true {
+            let bytesRead = recv(fd, &buffer, buffer.count, 0)
+            if bytesRead <= 0 { break }
+            received.append(buffer, count: bytesRead)
+        }
+        return String(decoding: received, as: UTF8.self)
+    }
+
+    // MARK: - OPTIONS preflight / generate / URL
+
+    func testPreflight_ReturnsCORSForPost() async throws {
+        try requireRunningServer()
+        var request = URLRequest(url: try url("stream"))
+        request.httpMethod = "OPTIONS"
+        let (_, response) = try await URLSession.shared.data(for: request)
+        let http = try XCTUnwrap(response as? HTTPURLResponse)
+        XCTAssertEqual(http.statusCode, 200)
+        XCTAssertTrue(http.value(forHTTPHeaderField: "Access-Control-Allow-Methods")?.contains("POST") ?? false)
+        XCTAssertNotNil(http.value(forHTTPHeaderField: "Access-Control-Allow-Origin"))
+    }
+
+    func testGenerate_ReturnsAggregatedJSON() async throws {
+        try requireRunningServer()
+        server.setNativeAiSupplier(stubSupplier(tokens: ["a", "b", "c"], conversationId: "g1"))
+
+        let (data, response) = try await URLSession.shared.data(for: try await post("generate", json: ["prompt": "hi"]))
+
+        XCTAssertEqual((response as? HTTPURLResponse)?.statusCode, 200)
+        let json = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any])
+        XCTAssertEqual(json["output"] as? String, "abc")
+        XCTAssertEqual(json["conversationId"] as? String, "g1")
+        XCTAssertEqual(json["tokenCount"] as? Int, 3)
+    }
+
+    func testGenerate_NoSupplier_Returns503() async throws {
+        try requireRunningServer()
+        let (data, response) = try await URLSession.shared.data(for: try await post("generate", json: ["prompt": "hi"]))
+        XCTAssertEqual((response as? HTTPURLResponse)?.statusCode, 503)
+        let json = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any])
+        XCTAssertEqual(json["code"] as? String, NativeAIErrorCode.streamNotReady)
+    }
+
+    // MARK: - Loopback-only AI routes, Content-Length validation
+
+    func testIsLoopbackPeer_AcceptsLocalAddressesOnly() throws {
+        func endpoint(_ host: NWEndpoint.Host) -> NWEndpoint { .hostPort(host: host, port: 5000) }
+        XCTAssertTrue(FrameworkServerUtils.isLoopbackPeer(endpoint(.ipv4(try XCTUnwrap(IPv4Address("127.0.0.1"))))))
+        XCTAssertTrue(FrameworkServerUtils.isLoopbackPeer(endpoint(.ipv6(try XCTUnwrap(IPv6Address("::1"))))))
+        XCTAssertTrue(FrameworkServerUtils.isLoopbackPeer(endpoint(.ipv6(try XCTUnwrap(IPv6Address("::ffff:127.0.0.1"))))))
+        XCTAssertFalse(FrameworkServerUtils.isLoopbackPeer(endpoint(.ipv4(try XCTUnwrap(IPv4Address("192.168.1.20"))))))
+        XCTAssertFalse(FrameworkServerUtils.isLoopbackPeer(endpoint(.ipv6(try XCTUnwrap(IPv6Address("fe80::1"))))))
+        XCTAssertFalse(FrameworkServerUtils.isLoopbackPeer(.unix(path: "/tmp/x")))
+    }
+
+    func testContentLength_ParsesValidAbsentAndRejectsMalformed() {
+        func length(_ headers: String) -> Int?? { .some(FrameworkServerUtils.contentLength(inHeaders: Data(headers.utf8))) }
+        XCTAssertEqual(length("POST / HTTP/1.1\r\nContent-Length: 12"), .some(12))
+        XCTAssertEqual(length("POST / HTTP/1.1\r\ncontent-length:7"), .some(7))
+        XCTAssertEqual(length("GET / HTTP/1.1\r\nHost: x"), .some(0))
+        XCTAssertEqual(length("POST / HTTP/1.1\r\nContent-Length: abc"), .some(nil))
+        XCTAssertEqual(length("POST / HTTP/1.1\r\nContent-Length: -5"), .some(nil))
+    }
+
+    func testPost_MalformedContentLength_Returns400() async throws {
+        try requireRunningServer()
+        let head = "POST /framework-\(server.getSessionId())/ai/stream HTTP/1.1\r\nContent-Length: nope\r\n\r\n"
+        let reply = try Self.rawExchange(port: server.getServerPort(), writes: [head], pauseBetween: 0)
+        XCTAssertTrue(reply.contains("400"))
+    }
+
+    func testNativeAIStreamURL_NilWhenStopped_AndNamesSessionWhenRunning() throws {
+        server.stopServer()
+        XCTAssertNil(server.nativeAIStreamURL())
+        try requireRunningServer()
+        let url = try XCTUnwrap(server.nativeAIStreamURL())
+        XCTAssertTrue(url.hasSuffix("/framework-\(server.getSessionId())/ai/stream"))
+        XCTAssertTrue(url.contains("localhost:\(server.getServerPort())"))
+    }
+}
+
+private final class LockedBox<T>: @unchecked Sendable {
+    private let lock = NSLock()
+    private var stored: T
+    init(_ initial: T) { stored = initial }
+    var value: T {
+        get { lock.lock(); defer { lock.unlock() }; return stored }
+        set { lock.lock(); defer { lock.unlock() }; stored = newValue }
+    }
+}