@mentra/bluetooth-sdk 3.4.0-dev.978 → 3.4.0-dev.979

package/ios/Source/sgcs/NimoCanvasCoordinator.swift

@@ -7,40 +7,49 @@ final class NimoCanvasCoordinator {
     private final class Flight {
         let key: Int
         var finalStarted = false
+        var finalStartedElapsedMs: UInt64?
         var complete = false
-        var earlyAck: Data?
+        var earlyAck: (Data, UInt64?)?
         init(key: Int) {
             self.key = key
         }
     }
 
+    private let continuousNow: (() -> UInt64)?
     private let schedule: NimoScheduler
     private let writeCapacity: () -> Int
     private let enqueue: ([Data], @escaping () -> Void, @escaping () -> Void) -> Bool
     private let reconnect: (String) -> Void
     private let rejected: (Int) -> Void
+    private let result: (Int, Int) -> Void
+    private let observedResult: (Int, Int, UInt64?) -> Void
     private let session = NimoCanvasSession()
     private var flight: Flight?
+    private var releaseDraining = false
     private var cancelRetry: (() -> Void)?
     private var cancelDeadline: (() -> Void)?
 
     init(schedule: @escaping NimoScheduler, writeCapacity: @escaping () -> Int,
          enqueue: @escaping ([Data], @escaping () -> Void, @escaping () -> Void) -> Bool,
-         reconnect: @escaping (String) -> Void, rejected: @escaping (Int) -> Void)
+         reconnect: @escaping (String) -> Void, rejected: @escaping (Int) -> Void, result: @escaping (Int, Int) -> Void = { _, _ in }, observedResult: @escaping (Int, Int, UInt64?) -> Void = { _, _, _ in }, continuousNow: (() -> UInt64)? = nil)
     {
+        self.continuousNow = continuousNow
         self.schedule = schedule; self.writeCapacity = writeCapacity; self.enqueue = enqueue
-        self.reconnect = reconnect; self.rejected = rejected
+        self.reconnect = reconnect; self.rejected = rejected; self.result = result; self.observedResult = observedResult
     }
 
     func offer(_ bytes: Data, scope: String, force: Bool = false) {
+        guard !releaseDraining else { return }
         run(session.offer(bytes, scope: scope, force: force))
     }
 
     func activate() {
+        guard !releaseDraining else { return }
         run(session.activate())
     }
 
     func readiness(_ value: Bool, confirmed: Bool = false) {
+        guard !releaseDraining else { return }
         if !value { cancelRetry?(); cancelRetry = nil }
         run(session.readiness(value, confirmed: confirmed))
     }
@@ -50,7 +59,20 @@ final class NimoCanvasCoordinator {
         run(session.exit())
     }
 
+    /// Fence new scenes/retries while retaining only the already-issued command
+    /// and its exact ACK, followed by the final Exit through the same queue.
+    func drainForRelease() {
+        releaseDraining = true
+        cancelRetry?(); cancelRetry = nil
+        run(session.exit())
+    }
+
+    func acceptsReleaseResponse(key: Int, payload: Data) -> Bool {
+        releaseDraining && flight?.key == key && session.acceptsResponse(key: key, payload: payload)
+    }
+
     func nativeApp(_ appId: Int, entered: Bool) {
+        guard !releaseDraining else { return }
         run(session.nativeApp(appId, entered: entered))
     }
 
@@ -61,17 +83,24 @@ final class NimoCanvasCoordinator {
         session.disconnected()
     }
 
-    func response(key: Int, payload: Data) {
+    func response(key: Int, payload: Data, receivedElapsedMs: UInt64? = nil) {
         guard let current = flight, session.acceptsResponse(key: key, payload: payload) else { return }
+        if let receivedElapsedMs, let started = current.finalStartedElapsedMs, receivedElapsedMs < started { return }
         if !current.complete {
-            if current.finalStarted, current.earlyAck == nil { current.earlyAck = payload }
+            if current.finalStarted, current.earlyAck == nil { current.earlyAck = (payload, receivedElapsedMs) }
             return
         }
         cancelDeadline?(); cancelDeadline = nil
         flight = nil
-        run(session.response(key: key, payload: payload))
+        let actions = session.response(key: key, payload: payload)
+        result(key, Int(payload.first ?? 255))
+        observedResult(key, Int(payload.first ?? 255), receivedElapsedMs)
+        run(actions)
     }
 
+    var pendingCount: Int { (flight == nil ? 0 : 1) + (cancelRetry == nil ? 0 : 1) }
+    var mayHaveEntered: Bool { session.mayHaveEntered }
+
     private func run(_ actions: [NimoCanvasSession.Action]) {
         for action in actions {
             switch action {
@@ -87,11 +116,11 @@ final class NimoCanvasCoordinator {
                 do {
                     let frames = try NimoCanvasCodec.frames(key: key, content: frame, writeCapacity: writeCapacity())
                     let queued = enqueue(frames, { [weak self] in
-                        if self?.flight === current { current.finalStarted = true }
+                        if let self, self.flight === current { current.finalStarted = true; current.finalStartedElapsedMs = self.continuousNow?() }
                     }, { [weak self] in
                         guard let self, self.flight === current else { return }
                         current.complete = true
-                        if let ack = current.earlyAck { self.response(key: key, payload: ack) }
+                        if let ack = current.earlyAck { self.response(key: key, payload: ack.0, receivedElapsedMs: ack.1) }
                     })
                     if !queued, flight === current { disconnected(); reconnect("Canvas transport unavailable") }
                 } catch {
@@ -100,7 +129,7 @@ final class NimoCanvasCoordinator {
             case let .reconnect(reason): disconnected(); reconnect(reason)
             case let .rejected(status):
                 rejected(status)
-                if status == 7 {
+                if status == 7 && !releaseDraining {
                     cancelRetry?()
                     cancelRetry = schedule(1) { [weak self] in
                         guard let self else { return }
@@ -134,6 +163,11 @@ final class NimoWriteQueue<Characteristic: AnyObject> {
     private var generation: UInt64 = 0
     private var queue: [Write] = []
     private var current: Write?
+    private var outstanding: [(AnyObject, Characteristic)] = []
+    private var scheduledCompletions = 0
+    var activeCount: Int { outstanding.count + scheduledCompletions }
+    var queuedCount: Int { queue.count }
+    func connectionClosed(_ closed: AnyObject) { outstanding.removeAll { $0.0 === closed } }
     private var cancelDeadline: (() -> Void)?
 
     init(schedule: @escaping NimoScheduler, write: @escaping (Characteristic, Data) -> Bool, failure: @escaping (String) -> Void) {
@@ -165,14 +199,18 @@ final class NimoWriteQueue<Characteristic: AnyObject> {
     }
 
     func written(_ connection: AnyObject, characteristic: Characteristic, success: Bool) {
+        if let index = outstanding.firstIndex(where: { $0.0 === connection && $0.1 === characteristic }) { outstanding.remove(at: index) }
         guard connection === self.connection, let item = current,
               characteristic === item.characteristic, !item.callbackReceived else { return }
         item.callbackReceived = true
         cancelDeadline?(); cancelDeadline = nil
         guard success else { fail("GATT write failed"); return }
         let expected = generation
+        scheduledCompletions += 1
         _ = schedule(0.005) { [weak self] in
-            guard let self, self.generation == expected, self.current === item else { return }
+            guard let self else { return }
+            self.scheduledCompletions -= 1
+            guard self.generation == expected, self.current === item else { return }
             self.current = nil
             item.completed()
             self.drain()
@@ -185,6 +223,7 @@ final class NimoWriteQueue<Characteristic: AnyObject> {
         current = item
         let expected = generation
         guard write(item.characteristic, item.bytes) else { fail("GATT transport unavailable"); return }
+        outstanding.append((connection!, item.characteristic))
         item.started()
         cancelDeadline = schedule(3) { [weak self] in
             guard let self, self.generation == expected, self.current === item, !item.callbackReceived else { return }
@@ -199,26 +238,41 @@ final class NimoWriteQueue<Characteristic: AnyObject> {
 
 /// Coalesces pending encodes and fences running results on scene change, Exit and disconnect.
 final class NimoCanvasEncoder {
+    private final class Work {
+        enum Stage { case queued, worker, delivery, settled }
+        var stage = Stage.queued
+        var cancelled = false
+    }
     private let worker: NimoScheduler
     private let main: NimoScheduler
     private let failure: (Error) -> Void
+    private let lock = NSLock()
     private var generation: UInt64 = 0
-    private var cancelPending: (() -> Void)?
+    private var jobs: [Work] = []
+    var workerCount: Int { lock.lock(); defer { lock.unlock() }; return jobs.filter { $0.stage == .queued || $0.stage == .worker }.count }
+    var deliveryCount: Int { lock.lock(); defer { lock.unlock() }; return jobs.filter { $0.stage == .delivery }.count }
 
     init(main: @escaping NimoScheduler, worker: @escaping NimoScheduler, failure: @escaping (Error) -> Void) {
         self.main = main; self.worker = worker; self.failure = failure
     }
 
-    /// submit/invalidate and delivery run on Main; the worker only reads its captured request.
     func submit(encode: @escaping () throws -> Data, deliver: @escaping (Data) -> Void) {
         invalidate()
-        let expected = generation
-        cancelPending = worker(0) { [weak self] in
-            let result = Result { try encode() }
+        let expected = generation, job = Work()
+        lock.lock(); jobs.append(job); lock.unlock()
+        _ = worker(0) { [weak self] in
             guard let self else { return }
+            self.lock.lock()
+            guard job.stage == .queued else { self.lock.unlock(); return }
+            let shouldEncode = !job.cancelled
+            job.stage = .worker; self.lock.unlock()
+            let result: Result<Data, Error>? = shouldEncode ? Result { try encode() } : nil
+            self.lock.lock(); job.stage = .delivery; self.lock.unlock()
             _ = self.main(0) { [weak self] in
-                guard let self, self.generation == expected else { return }
-                self.cancelPending = nil
+                guard let self else { return }
+                self.lock.lock(); job.stage = .settled; self.jobs.removeAll { $0 === job }; self.lock.unlock()
+                guard self.generation == expected else { return }
+                guard let result else { return }
                 switch result {
                 case let .success(bytes): deliver(bytes)
                 case let .failure(error): self.failure(error)
@@ -228,6 +282,11 @@ final class NimoCanvasEncoder {
     }
 
     func invalidate() {
-        generation &+= 1; cancelPending?(); cancelPending = nil
+        generation &+= 1
+        lock.lock()
+        for job in jobs where job.stage == .queued { job.cancelled = true }
+        lock.unlock()
+        // Do not erase queued producers: their no-op worker and Main delivery
+        // fences must actually execute before teardown can report settlement.
     }
 }

package/ios/Source/sgcs/NimoCanvasSession.swift

@@ -32,6 +32,7 @@ final class NimoCanvasSession {
     private var sentRevision: UInt64 = 0
     private var ticket: UInt64 = 0
     private var flight: Flight?
+    var mayHaveEntered: Bool { active || flight != nil }
 
     func offer(_ frame: Data, scope: String, force: Bool = false) -> [Action] {
         if self.scope != scope || force { forceRevision &+= 1 }

package/ios/Source/sgcs/NimoMacResourceTransport.swift

@@ -0,0 +1,217 @@
+import Foundation
+#if os(macOS) || os(iOS)
+import CryptoKit
+import Darwin
+
+struct NimoMacProcessBirth: Codable, Equatable {
+    let seconds: UInt64
+    let microseconds: UInt64
+
+}
+struct NimoMacFixtureConfiguration: Codable {
+    let version: Int
+    let ownerPid: Int32
+    let ownerAuditToken: String
+    let ownerBirth: NimoMacProcessBirth
+    let planSha256: String
+    let grantSha256: String
+    let bootstrapNonce: String
+    let appExecutableSha256: String
+    let appBundleId: String
+}
+
+/// Private, one-owner fixture IPC. Only typed lifecycle operations reach Main.
+/// No socket path, packet, host address or connection command is caller supplied.
+final class NimoMacResourceTransport {
+    let configuration: NimoMacFixtureConfiguration
+    private let process: NimoResourceProcess
+    private let directory: String
+    private let directoryFd: Int32
+    private let directoryDevice: UInt64
+    private let directoryInode: UInt64
+    private let socketFd: Int32
+    private let socketPath: String
+    private let processAuditToken: String
+    private let executableSha256: String
+    private let queue = DispatchQueue(label: "NimoResourceFixtureSocket")
+
+    init(process: NimoResourceProcess) throws {
+        #if os(iOS)
+        guard ProcessInfo.processInfo.isiOSAppOnMac else { throw transportError("fixture-requires-ios-on-mac") }
+        #endif
+        guard let text = ProcessInfo.processInfo.environment["MENTRA_NIMO_RESOURCE_BOOTSTRAP"], text.utf8.count <= 4096,
+              let bytes = text.data(using: .utf8), let object = try JSONSerialization.jsonObject(with: bytes) as? [String: Any],
+              Set(object.keys) == Set(["version","ownerPid","ownerAuditToken","ownerBirth","planSha256","grantSha256","bootstrapNonce","appExecutableSha256","appBundleId"]),
+              let birth = object["ownerBirth"] as? [String: Any], Set(birth.keys) == Set(["seconds","microseconds"]) else { throw transportError("invalid-bootstrap") }
+        configuration = try JSONDecoder().decode(NimoMacFixtureConfiguration.self, from: bytes)
+        guard configuration.version == 1, configuration.ownerPid > 1,
+              configuration.ownerPid != process.pid,
+              UUID(uuidString: configuration.bootstrapNonce)?.uuidString.lowercased() == configuration.bootstrapNonce,
+              [configuration.planSha256, configuration.grantSha256, configuration.appExecutableSha256, configuration.ownerAuditToken].allSatisfy({ $0.range(of: "^[0-9a-f]{64}$", options: .regularExpression) != nil }),
+              Bundle.main.bundleIdentifier == configuration.appBundleId,
+              let executable = Bundle.main.executableURL else { throw transportError("bootstrap-identity-mismatch") }
+        let executableBytes = try Data(contentsOf: executable, options: [.mappedIfSafe])
+        guard executableBytes.count <= 256 * 1024 * 1024 else { throw transportError("executable-budget") }
+        executableSha256 = SHA256.hash(data: executableBytes).map { String(format: "%02x", $0) }.joined()
+        guard executableSha256 == configuration.appExecutableSha256 else { throw transportError("executable-mismatch") }
+        self.process = process; processAuditToken = try nimoOwnAuditToken()
+        directory = NSHomeDirectory() + "/tmp/nr-" + configuration.bootstrapNonce.replacingOccurrences(of: "-", with: "").prefix(16)
+        // Never reuse another process's directory, socket or receipts.
+        guard mkdir(directory, 0o700) == 0 else { throw transportError("fixture-directory-exists-or-unavailable") }
+        directoryFd = open(directory, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC)
+        guard directoryFd >= 0 else { throw transportError("fixture-directory-open") }
+        var info = stat()
+        guard fstat(directoryFd, &info) == 0, info.st_uid == geteuid(), info.st_mode & 0o777 == 0o700 else { throw transportError("fixture-directory-permissions") }
+        directoryDevice = UInt64(info.st_dev); directoryInode = UInt64(info.st_ino)
+        socketPath = directory + "/s"
+        socketFd = socket(AF_UNIX, SOCK_STREAM, 0)
+        guard socketFd >= 0 else { throw transportError("fixture-socket-open") }
+        var address = sockaddr_un(); address.sun_family = sa_family_t(AF_UNIX)
+        let pathBytes = Array(socketPath.utf8) + [0]
+        guard pathBytes.count <= MemoryLayout.size(ofValue: address.sun_path) else { throw transportError("fixture-socket-path-budget") }
+        withUnsafeMutableBytes(of: &address.sun_path) { $0.copyBytes(from: pathBytes) }
+        let length = socklen_t(MemoryLayout<sockaddr_un>.size)
+        address.sun_len = UInt8(length)
+        let result = withUnsafePointer(to: &address) { ptr in ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { Darwin.bind(socketFd, $0, length) } }
+        guard result == 0, chmod(socketPath, 0o600) == 0, listen(socketFd, 4) == 0 else { throw transportError("fixture-socket-bind") }
+        let flags = fcntl(socketFd, F_GETFD); _ = fcntl(socketFd, F_SETFD, flags | FD_CLOEXEC)
+        let schedulerQoS: DispatchQoS = .unspecified
+        let schedulerFlags = DispatchWorkItemFlags(rawValue: 0)
+        enqueueServe(qos: schedulerQoS, flags: schedulerFlags)
+    }
+
+    // A narrow scheduling boundary for this transport's original accept loop.
+    @inline(never)
+    private func enqueueServe(qos: DispatchQoS, flags: DispatchWorkItemFlags) {
+        queue.async(group: nil, qos: qos, flags: flags) { [weak self] in self?.serve() }
+    }
+
+    private func sameDirectory() -> Bool {
+        var byPath = stat(), byFd = stat()
+        return lstat(directory, &byPath) == 0 && fstat(directoryFd, &byFd) == 0 &&
+            byPath.st_mode & S_IFMT == S_IFDIR && byPath.st_dev == byFd.st_dev && byPath.st_ino == byFd.st_ino &&
+            UInt64(byFd.st_dev) == directoryDevice && UInt64(byFd.st_ino) == directoryInode && byFd.st_uid == geteuid() && byFd.st_mode & 0o777 == 0o700
+    }
+
+    func persist(_ bytes: Data, nonce: String, kind: String) throws {
+        guard sameDirectory(), UUID(uuidString: nonce)?.uuidString.lowercased() == nonce,
+              ["intent","receipt","admission","transport"].contains(kind), bytes.count <= 32_768 else { throw transportError("journal-identity-mismatch") }
+        let final = "\(nonce).\(kind).json", temp = "\(nonce).\(kind).pending"
+        let fd = openat(directoryFd, temp, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW | O_CLOEXEC, 0o600)
+        guard fd >= 0 else { throw transportError("journal-intent-exists-or-unavailable") }
+        defer { close(fd); unlinkat(directoryFd, temp, 0) }
+        try bytes.withUnsafeBytes { raw in
+            var offset = 0
+            while offset < raw.count {
+                let count = Darwin.write(fd, raw.baseAddress!.advanced(by: offset), raw.count - offset)
+                guard count > 0 else { throw transportError("journal-write-failed") }; offset += count
+            }
+        }
+        guard fsync(fd) == 0, sameDirectory(), linkat(directoryFd, temp, directoryFd, final, 0) == 0,
+              fsync(directoryFd) == 0 else { throw transportError("journal-atomic-publish-failed") }
+    }
+
+    private func peerAllowed(_ fd: Int32) -> Bool {
+        var peerPid: Int32 = 0, length = socklen_t(MemoryLayout<Int32>.size)
+        var uid: uid_t = 0, gid: gid_t = 0
+        var token = audit_token_t(), tokenLength = socklen_t(MemoryLayout<audit_token_t>.size)
+        return getsockopt(fd, SOL_LOCAL, LOCAL_PEERPID, &peerPid, &length) == 0 &&
+            length == MemoryLayout<Int32>.size && peerPid == configuration.ownerPid && getpeereid(fd, &uid, &gid) == 0 && uid == geteuid() &&
+            getsockopt(fd, SOL_LOCAL, LOCAL_PEERTOKEN, &token, &tokenLength) == 0 &&
+            tokenLength == MemoryLayout<audit_token_t>.size && nimoAuditTokenHex(token) == configuration.ownerAuditToken && sameDirectory()
+    }
+
+    private func serve() {
+        while true {
+            let fd = accept(socketFd, nil, nil)
+            if fd < 0 { if errno == EINTR { continue }; return }
+            defer { close(fd) }
+            guard peerAllowed(fd) else { continue }
+            var timeout = timeval(tv_sec: 5, tv_usec: 0)
+            _ = setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &timeout, socklen_t(MemoryLayout<timeval>.size))
+            _ = setsockopt(fd, SOL_SOCKET, SO_SNDTIMEO, &timeout, socklen_t(MemoryLayout<timeval>.size))
+            var noSignal: Int32 = 1
+            _ = setsockopt(fd, SOL_SOCKET, SO_NOSIGPIPE, &noSignal, socklen_t(MemoryLayout<Int32>.size))
+            var request = Data(), complete = false
+            let readDeadline = NimoResourceClock.now() + 5_000
+            while request.count <= 16_384, NimoResourceClock.now() < readDeadline {
+                var buffer = [UInt8](repeating: 0, count: 1024)
+                let count = read(fd, &buffer, buffer.count)
+                if count <= 0 { break }
+                request.append(contentsOf: buffer.prefix(count))
+                if request.contains(10) { complete = true; break }
+            }
+            guard complete, request.count <= 16_384, request.last == 10, request.dropLast().contains(10) == false,
+                  peerAllowed(fd) else { continue }
+            do {
+                guard let envelope = try JSONSerialization.jsonObject(with: request) as? [String: Any],
+                      envelope["bootstrapNonce"] as? String == configuration.bootstrapNonce else { throw transportError("bootstrap-capability-mismatch") }
+                let response: Data
+                if Set(envelope.keys) == Set(["bootstrapNonce","hello"]), envelope["hello"] as? Bool == true {
+                    response = try JSONSerialization.data(withJSONObject: hello(), options: [.sortedKeys])
+                } else {
+                    guard Set(envelope.keys) == Set(["bootstrapNonce","request"]), let value = envelope["request"] as? [String: Any] else { throw transportError("invalid-envelope") }
+                    let canonical = try JSONSerialization.data(withJSONObject: value, options: [.sortedKeys])
+                    let semaphore = DispatchSemaphore(value: 0)
+                    // Connection execution is serial; parent timeout does not cancel
+                    // native cleanup or renew its original operation authority.
+                    final class Box: @unchecked Sendable { var result: Result<Data, Error>? }
+                    let box = Box()
+                    Task { @MainActor in
+                        do { box.result = .success(try await NimoResourceFixture.shared.execute(canonical)) }
+                        catch { box.result = .failure(error) }
+                        semaphore.signal()
+                    }
+                    semaphore.wait()
+                    guard peerAllowed(fd), let result = box.result else { continue }
+                    let receipt = try result.get()
+                    response = try JSONSerialization.data(withJSONObject: ["receipt": try JSONSerialization.jsonObject(with: receipt)], options: [.sortedKeys])
+                }
+                send(response + Data([10]), fd)
+            } catch {
+                let code = String(error.localizedDescription.prefix(160))
+                if let bytes = try? JSONSerialization.data(withJSONObject: ["error": code], options: [.sortedKeys]) { send(bytes + Data([10]), fd) }
+            }
+        }
+    }
+    private func send(_ data: Data, _ fd: Int32) {
+        data.withUnsafeBytes { bytes in
+            var offset = 0
+            while offset < bytes.count {
+                let count = Darwin.write(fd, bytes.baseAddress!.advanced(by: offset), bytes.count - offset)
+                if count <= 0 { return }; offset += count
+            }
+        }
+    }
+    private func hello() -> [String: Any] {
+        ["protocol": "nimo-macos-resource-v1", "process": ["pid": process.pid, "instanceId": process.instanceId],
+         "processAuditToken": processAuditToken, "ownerAuditToken": configuration.ownerAuditToken,
+         "ownerPid": configuration.ownerPid, "ownerBirth": ["seconds": configuration.ownerBirth.seconds, "microseconds": configuration.ownerBirth.microseconds],
+         "executableSha256": executableSha256, "bundleIdentifier": configuration.appBundleId,
+         "directory": ["device": directoryDevice, "inode": directoryInode], "socketPath": socketPath]
+    }
+}
+// Audit tokens are opaque kernel identities: never interpret their word layout.
+private func nimoAuditTokenHex(_ token: audit_token_t) -> String {
+    withUnsafeBytes(of: token) { $0.map { String(format: "%02x", $0) }.joined() }
+}
+private func nimoOwnAuditToken() throws -> String {
+    var token = audit_token_t()
+    var count = mach_msg_type_number_t(MemoryLayout<audit_token_t>.size / MemoryLayout<integer_t>.size)
+    let result = withUnsafeMutablePointer(to: &token) { pointer in
+        pointer.withMemoryRebound(to: integer_t.self, capacity: Int(count)) {
+            task_info(mach_task_self_, task_flavor_t(TASK_AUDIT_TOKEN), $0, &count)
+        }
+    }
+    guard result == KERN_SUCCESS, count == MemoryLayout<audit_token_t>.size / MemoryLayout<integer_t>.size else { throw transportError("process-audit-token-unavailable") }
+    return nimoAuditTokenHex(token)
+}
+private func transportError(_ code: String) -> Error { NSError(domain: "NimoResourceTransport", code: 1, userInfo: [NSLocalizedDescriptionKey: code]) }
+#else
+struct NimoMacFixtureConfiguration { let planSha256 = "", grantSha256 = "" }
+final class NimoMacResourceTransport {
+    let configuration = NimoMacFixtureConfiguration()
+    init(process: NimoResourceProcess) throws { throw NSError(domain: "NimoResourceFixture", code: 1) }
+    func persist(_ bytes: Data, nonce: String, kind: String) throws { throw NSError(domain: "NimoResourceFixture", code: 1) }
+}
+#endif

package/ios/Source/sgcs/NimoResourceFixture.swift

@@ -0,0 +1,187 @@
+import Foundation
+
+/// One process-local authority shared by the typed Expo bridge and the Mac
+/// fixture socket. Neither accepts packets, connection addresses or file paths.
+@MainActor
+public enum NimoResourceFixtureBridge {
+    public static func execute(_ json: String) async throws -> String {
+        let bytes = Data(json.utf8)
+        return String(decoding: try await NimoResourceFixture.shared.execute(bytes), as: UTF8.self)
+    }
+}
+
+@MainActor
+final class NimoResourceFixture {
+    static let shared = NimoResourceFixture()
+    let process = NimoResourceProcess(pid: ProcessInfo.processInfo.processIdentifier, instanceId: UUID().uuidString.lowercased())
+    private(set) var session: NimoResourceSession?
+    private(set) var owner: Nimo?
+    private var completed: [String: (Data, Data)] = [:]
+    private var pending: [String: (Data, Task<Data, Error>)] = [:]
+    private var transport: NimoMacResourceTransport?
+    private var startupError: Error?
+    private var originalClosed = false
+    private let managerEntries = NimoResourceManagerEntries()
+    var pendingManagerEntries: Int { managerEntries.all }
+    var pendingOriginalManagerEntries: Int { managerEntries.originalNimo }
+    func beginManagerEntry(_ wearable: String) -> NimoResourceManagerEntries.Ticket { managerEntries.begin(wearable) }
+    func endManagerEntry(_ ticket: NimoResourceManagerEntries.Ticket) { managerEntries.end(ticket) }
+    #if os(macOS)
+    private let requested = ProcessInfo.processInfo.environment["MENTRA_NIMO_RESOURCE_BOOTSTRAP"] != nil
+    #elseif os(iOS)
+    private let requested = ProcessInfo.processInfo.isiOSAppOnMac && ProcessInfo.processInfo.environment["MENTRA_NIMO_RESOURCE_BOOTSTRAP"] != nil
+    #else
+    private let requested = false
+    #endif
+    var enabled: Bool { requested }
+
+    func start() {
+        guard enabled, transport == nil, startupError == nil else { return }
+        do { transport = try NimoMacResourceTransport(process: process) }
+        catch { startupError = error }
+    }
+    func allowsManager(_ wearable: String, name: String? = nil) -> Bool {
+        guard enabled else { return true }
+        // A different manager can clean up the captured Nimo object. Permit it
+        // only after the original resource has actually completed teardown.
+        guard wearable.contains("NIMO") else { return NimoResourceManagerState.allowsReplacement(fixtureEnabled: enabled, originalClosed: originalClosed && session?.errors.isEmpty == true && session?.connected == false) }
+        guard let session, !session.cancelled, session.releaseNonce == nil, session.original == nil,
+              name == nil || name == session.pair.name else { return false }
+        return true
+    }
+    func hasVerifiedOriginalClosure(_ candidate: Nimo) -> Bool {
+        originalClosed && owner === candidate && session?.isOwner(candidate) == true
+            && session?.errors.isEmpty == true && session?.connected == false
+    }
+    func admit(_ candidate: Nimo, name: String?) -> Bool {
+        guard enabled else { return true }
+        guard (DeviceManager.shared.sgc as AnyObject?) === candidate, let session, let transport else { return false }
+        let admitted = session.admit(candidate, instanceId: candidate.resourceInstanceId, name: name) { proposed in
+            self.persistAdmission(session, instanceId: candidate.resourceInstanceId, elapsed: proposed, transportStart: false, transport: transport)
+        }
+        if session.isOwner(candidate), owner == nil { owner = candidate }
+        return admitted && owner === candidate
+    }
+    private func persistAdmission(_ session: NimoResourceSession, instanceId: String, elapsed: UInt64, transportStart: Bool, transport: NimoMacResourceTransport) -> Bool {
+        let value: [String: Any] = ["protocol": "nimo-macos-resource-v1", "captureNonce": session.captureNonce,
+            "process": ["pid": process.pid, "instanceId": process.instanceId],
+            "planSha256": transport.configuration.planSha256, "grantSha256": transport.configuration.grantSha256,
+            "instanceId": instanceId, "peripheralUuid": session.pair.peripheralUuid, "sessionGeneration": transportStart ? 1 : 0,
+            "armedElapsedMs": session.armedElapsedMs, "admittedElapsedMs": transportStart ? nullable(session.admittedElapsedMs) : elapsed,
+            "startedElapsedMs": transportStart ? elapsed : NSNull() as Any]
+        do {
+            let bytes = try JSONSerialization.data(withJSONObject: value, options: [.sortedKeys])
+            try transport.persist(bytes, nonce: session.captureNonce, kind: transportStart ? "transport" : "admission")
+            return true
+        } catch { return false }
+    }
+    func preserveScan(_ name: String) -> Bool {
+        guard enabled, let owner, let session, session.isOwner(owner),
+              session.original == nil, !session.cancelled, name == session.pair.name else { return false }
+        return (DeviceManager.shared.sgc as AnyObject?) === owner
+    }
+    func beginTransport(_ candidate: Nimo, peripheral: AnyObject, uuid: String) -> Bool {
+        guard enabled else { return true }
+        guard (DeviceManager.shared.sgc as AnyObject?) === candidate, let session, let transport else { return false }
+        return session.beginTransport(candidate, peripheral: peripheral, uuid: uuid) { proposed in
+            self.persistAdmission(session, instanceId: candidate.resourceInstanceId, elapsed: proposed, transportStart: true, transport: transport)
+        }
+    }
+    func allowsProducer(_ candidate: Nimo) -> Bool {
+        guard enabled else { return true }
+        return session?.isOwner(candidate) == true && session?.releaseNonce == nil && session?.cancelled == false && (DeviceManager.shared.sgc as AnyObject?) === candidate
+    }
+    func captured(_ candidate: Nimo) -> NimoResourceSession? {
+        guard enabled, session?.isOwner(candidate) == true else { return nil }; return session
+    }
+
+    func execute(_ bytes: Data) async throws -> Data {
+        start()
+        guard bytes.count <= 16_384, enabled, let transport, startupError == nil else { throw failure("fixture-unavailable") }
+        let request = try decode(bytes)
+        guard request.version == 1, request.expectedProcess == process,
+              request.planSha256 == transport.configuration.planSha256,
+              request.grantSha256 == transport.configuration.grantSha256 else { throw failure("fixture-authority-mismatch") }
+        if let (original, receipt) = completed[request.requestNonce] {
+            guard original == bytes else { throw failure("request-nonce-reused") }; return receipt
+        }
+        if let (original, task) = pending[request.requestNonce] {
+            guard original == bytes else { throw failure("request-nonce-reused") }; return try await task.value
+        }
+        if request.operation != .arm {
+            guard let session, session.captureNonce == request.captureNonce, session.pair == request.expectedPair else { throw failure("capture-mismatch") }
+            let observed = session.original ?? session.instanceId.map { NimoResourceOriginal(instanceId: $0, peripheralUuid: session.pair.peripheralUuid, sessionGeneration: 0) }
+            if let expected = request.original { guard expected == observed else { throw failure("original-session-mismatch") } }
+            if request.operation == .release, session.hasOwner, request.original == nil { throw failure("release-requires-original") }
+            if request.operation == .release, let release = session.releaseNonce, release != request.requestNonce { throw failure("original-release-nonce-required") }
+        }
+        let recovery = request.operation == .release || request.operation == .cancel || session?.releaseNonce != nil
+        guard completed.count + pending.count < (recovery ? 256 : 192) else { throw failure("request-budget-exhausted") }
+        // Intent is persisted before ANY capture or release mutation. No caller
+        // path is used; replay compares the exact original request bytes.
+        try transport.persist(bytes, nonce: request.requestNonce, kind: "intent")
+        let received = NimoResourceClock.now()
+        let task = Task { @MainActor in
+            let result = try await self.perform(request, received: received)
+            let encoded = try JSONSerialization.data(withJSONObject: result, options: [.sortedKeys])
+            guard encoded.count <= 32_768 else { throw self.failure("receipt-budget-exhausted") }
+            try transport.persist(encoded, nonce: request.requestNonce, kind: "receipt")
+            return encoded
+        }
+        pending[request.requestNonce] = (bytes, task)
+        do {
+            let receipt = try await task.value
+            completed[request.requestNonce] = (bytes, receipt); pending.removeValue(forKey: request.requestNonce)
+            return receipt
+        } catch {
+            // Keep the original failed intent fenced; do not reexecute effects.
+            throw error
+        }
+    }
+
+    private func perform(_ request: NimoResourceRequest, received: UInt64) async throws -> [String: Any] {
+        if request.operation == .arm {
+            guard session == nil, request.original == nil, DeviceManager.shared.sgc == nil, pendingManagerEntries == 0 else { throw failure("arm-requires-unowned-manager") }
+            session = NimoResourceSession(captureNonce: request.captureNonce, pair: request.expectedPair)
+        }
+        guard let session, session.captureNonce == request.captureNonce, session.pair == request.expectedPair else { throw failure("capture-mismatch") }
+        if let expected = request.original {
+            let observed = session.original ?? session.instanceId.map { NimoResourceOriginal(instanceId: $0, peripheralUuid: session.pair.peripheralUuid, sessionGeneration: 0) }
+            guard expected == observed else { throw failure("original-session-mismatch") }
+        } else if request.operation == .release, session.hasOwner { throw failure("release-requires-original") }
+        if request.operation == .release || request.operation == .cancel {
+            if session.releaseNonce == nil {
+                let mic = owner?.resourceMicStopRequired ?? false, canvas = owner?.resourceCanvasRequired ?? false
+                guard session.beginRelease(nonce: request.requestNonce, cancel: request.operation == .cancel, mic: mic, canvas: canvas) else { throw failure("release-mismatch") }
+                if let owner { await owner.releaseResource(session) }
+                else {
+                    let deadline = NimoResourceClock.now() + 1_000
+                    while pendingOriginalManagerEntries != 0, NimoResourceClock.now() < deadline { try? await Task.sleep(nanoseconds: 10_000_000) }
+                    if pendingOriginalManagerEntries != 0 { session.recordError("pending-manager-entry-not-settled") }
+                    session.proveNoTransport()
+                }
+            } else if request.operation == .release, session.releaseNonce != request.requestNonce {
+                throw failure("original-release-nonce-required")
+            }
+        }
+        var producers = NimoResourceProducers()
+        producers.postedCallbacks = pendingOriginalManagerEntries
+        if let owner { producers = await owner.resourceProducers() }
+        originalClosed = session.settled(producers: producers)
+        let manager = DeviceManager.shared.sgc
+        let managerId = (manager as? Nimo)?.resourceInstanceId
+        let current: [String: Any] = ["type": nullable(manager?.type), "instanceId": nullable(managerId)]
+        return ["version": 1, "protocol": "nimo-macos-resource-v1", "operation": request.operation.rawValue,
+                "requestNonce": request.requestNonce, "captureNonce": request.captureNonce,
+                "planSha256": request.planSha256, "grantSha256": request.grantSha256,
+                "process": ["pid": process.pid, "instanceId": process.instanceId],
+                "clock": ["kind": "darwin-continuous-time-v1", "receivedElapsedMs": received, "observedElapsedMs": NimoResourceClock.now()],
+                "capture": ["armedElapsedMs": session.armedElapsedMs, "admittedElapsedMs": nullable(session.admittedElapsedMs), "cancelled": session.cancelled,
+                            "expectedPair": ["name": session.pair.name, "peripheralUuid": session.pair.peripheralUuid]],
+                "currentManager": current, "session": nullable(session.sessionDictionary()),
+                "release": session.releaseDictionary(producers: producers), "producers": producers.dictionary, "errors": session.errors]
+    }
+
+    private func decode(_ bytes: Data) throws -> NimoResourceRequest { try NimoResourceRequest.decode(bytes) }
+    private func failure(_ code: String) -> Error { NSError(domain: "NimoResourceFixture", code: 1, userInfo: [NSLocalizedDescriptionKey: code]) }
+}