Fail model load early when free RAM is below the catalog estimate (#251)

* Fail model load early when free RAM is below the catalog estimate

Before WhisperKit starts, refuse loads that cannot fit in installed
or available memory so the spinner does not hang (vocamac#250).

* Cast os_proc_available_memory to UInt64 for App CI

Swift imports the probe as Int; coerce non-positive readings to zero
so availableMemoryBytes matches its UInt64 return type.

* Replace iOS-only memory probe with host_statistics64

os_proc_available_memory is unavailable on macOS and broke App CI.
Use free+inactive pages from HOST_VM_INFO64 instead; return 0 on probe failure.

* Stub low-RAM model gate in AppState tests

CI free+inactive pages often sit under Medium's 5 GB estimate, so the new pre-load check rejected mock medium loads and broke serialization/restore tests.

* Address Greptile notes on the low-RAM model gate

Refuse the load without restoring or clearing an already loaded
model. Count speculative, purgeable, and compressor pages in the
host probe, and release the mach_host_self send right.

* Retrigger Greptile review on e47f66a

Empty commit so Greptile re-scores the low-RAM gate fixes after the
prior review on 8108205. No code changes.

* Fix low-RAM probe overcounting available pages

Do not add speculative pages on top of free_count (Darwin already
includes them), and drop compressor pages which still occupy RAM.

* Use free+inactive only for the low-RAM probe

Purgeable often overlaps the inactive queue on Darwin, so summing both
overstates reclaimable memory. Keep the gate conservative.

Author: jatinkrmalik

Sources/VocaMac/Models/AppState.swift

@@ -324,6 +324,10 @@ final class AppState: ObservableObject {
     /// Set to `true` in tests to avoid side effects.
     let skipSystemIntegration: Bool
 
+    /// Pre-load memory gate. Production defaults to SystemInfo; tests stub this
+    /// so CI free+inactive pages cannot flake medium/large mock loads.
+    var modelFitsInMemory: (ModelSize) -> Bool = { SystemInfo.canFitModelInMemory($0) }
+
     // MARK: - Initialization
 
     init(
@@ -1258,6 +1262,20 @@ final class AppState: ObservableObject {
         // we don't know yet — we'll detect it after loading completes.
         let targetSize = size
 
+        // Refuse known-too-large loads before WhisperKit/CoreML can hang the
+        // UI spinner under memory pressure (vocamac#250). Leave any already
+        // loaded model alone — we never started a load, so do not restore/clear.
+        if let targetSize,
+           !modelFitsInMemory(targetSize) {
+            let needed = String(format: "%.1f", targetSize.ramRequiredGB)
+            let failureMessage =
+                "Not enough free memory to load \(targetSize.displayName) "
+                + "(~\(needed) GB needed). Free RAM or choose a smaller model."
+            showTemporaryError(failureMessage)
+            VocaLogger.error(.appState, failureMessage)
+            return
+        }
+
         // Mark the model as loading in the UI
         if let targetSize = targetSize, let idx = availableModels.firstIndex(where: { $0.size == targetSize }) {
             availableModels[idx].isLoading = true

Sources/VocaMac/Services/SystemInfo.swift

@@ -3,6 +3,7 @@
 //
 // Detects system hardware capabilities and recommends optimal whisper model size.
 
+import Darwin
 import Foundation
 
 // MARK: - SystemCapabilities
@@ -147,4 +148,49 @@ enum SystemInfo {
         // Use at most half the cores, minimum 2, maximum 8
         return max(2, min(cores / 2, 8))
     }
+
+    /// Approximate reclaimable memory in bytes. Zero means the probe failed.
+    ///
+    /// Uses free + inactive only. On Darwin, `free_count` already includes
+    /// speculative pages, purgeable pages often overlap the inactive queue,
+    /// and compressor-resident pages still occupy RAM — so those counters
+    /// must not be added on top or the gate can over-approve loads.
+    static var availableMemoryBytes: UInt64 {
+        var stats = vm_statistics64()
+        var count = mach_msg_type_number_t(
+            MemoryLayout<vm_statistics64_data_t>.stride / MemoryLayout<integer_t>.stride
+        )
+        let host = mach_host_self()
+        defer { mach_port_deallocate(mach_task_self_, host) }
+        let kr = withUnsafeMutablePointer(to: &stats) {
+            $0.withMemoryRebound(to: integer_t.self, capacity: Int(count)) {
+                host_statistics64(host, HOST_VM_INFO64, $0, &count)
+            }
+        }
+        guard kr == KERN_SUCCESS else { return 0 }
+        var pageSize: vm_size_t = 0
+        guard host_page_size(host, &pageSize) == KERN_SUCCESS, pageSize > 0 else { return 0 }
+        let pages = UInt64(stats.free_count)
+            + UInt64(stats.inactive_count)
+        return pages * UInt64(pageSize)
+    }
+
+    /// Whether loading `size` is likely to fit without thrashing.
+    ///
+    /// Uses the catalog RAM estimate against installed memory and against
+    /// reclaimable free memory from host_statistics64. A zero available
+    /// reading is treated as unknown so we do not block loads on a failed probe.
+    static func canFitModelInMemory(
+        _ size: ModelSize,
+        physicalMemoryGB: Int = physicalMemoryGB,
+        availableBytes: UInt64 = availableMemoryBytes
+    ) -> Bool {
+        let requiredGB = size.ramRequiredGB
+        guard Double(physicalMemoryGB) + 0.001 >= requiredGB else {
+            return false
+        }
+        guard availableBytes > 0 else { return true }
+        let requiredBytes = UInt64((requiredGB * 1024 * 1024 * 1024).rounded(.up))
+        return availableBytes >= requiredBytes
+    }
 }

Tests/VocaMacTests/AppStateTests.swift

@@ -347,6 +347,45 @@ final class AppStateModelLoadingTests: XCTestCase {
         )
     }
 
+    @MainActor
+    func testLowMemoryGateRefusesMediumBeforeWhisperWithoutTouchingLoadedModel() async {
+        UserDefaults.standard.set(ModelSize.small.rawValue, forKey: "vocamac.selectedModelSize")
+
+        let modelManager = MockModelManager()
+        modelManager.downloadedModels = [.small, .medium]
+
+        let whisperService = MockWhisperService()
+        whisperService.loadResponses = [
+            .success("openai_whisper-small"),
+        ]
+
+        let (appState, mocks) = AppState.makeTestState(
+            modelManager: modelManager,
+            whisperService: whisperService
+        )
+
+        await appState.loadModel(.small)
+        let loadsAfterSmall = mocks.whisperService.loadRequests.count
+        XCTAssertEqual(appState.currentModel?.size, .small)
+        XCTAssertTrue(mocks.whisperService.isModelLoaded)
+
+        appState.modelFitsInMemory = { $0 != .medium }
+        await appState.loadModel(.medium)
+
+        XCTAssertTrue(
+            appState.errorMessage?.contains("Not enough") == true
+                || appState.errorMessage?.localizedCaseInsensitiveContains("free memory") == true
+        )
+        XCTAssertEqual(mocks.whisperService.loadRequests.count, loadsAfterSmall)
+        XCTAssertFalse(
+            mocks.whisperService.loadRequests.map { $0.name }.contains("openai_whisper-medium")
+        )
+        XCTAssertEqual(appState.currentModel?.size, .small)
+        XCTAssertEqual(appState.selectedModelSize, ModelSize.small.rawValue)
+        XCTAssertTrue(mocks.whisperService.isModelLoaded)
+        XCTAssertEqual(mocks.whisperService.loadedModelName, "openai_whisper-small")
+    }
+
     @MainActor
     func testDeleteModelRemovesDownloadedModel() async {
         let modelManager = MockModelManager()

Tests/VocaMacTests/Mocks/MockServices.swift

@@ -572,6 +572,8 @@ extension AppState {
             permissionManager: permissionManager,
             skipSystemIntegration: true
         )
+        // Bypass host free-RAM probe so mock loads are not refused on CI.
+        appState.modelFitsInMemory = { _ in true }
         return (appState, mocks)
     }
 }

Tests/VocaMacTests/ModelTests.swift

@@ -53,6 +53,47 @@ final class SystemInfoTests: XCTestCase {
         XCTAssertTrue(summary.contains("Metal:"))
         XCTAssertTrue(summary.contains("Recommended Model:"))
     }
+
+    func testCanFitModelRejectsWhenPhysicalMemoryIsTooLow() {
+        XCTAssertFalse(
+            SystemInfo.canFitModelInMemory(
+                .largeV3Latest,
+                physicalMemoryGB: 4,
+                availableBytes: UInt64(64) * 1024 * 1024 * 1024
+            )
+        )
+    }
+
+    func testCanFitModelRejectsWhenAvailableMemoryIsTooLow() {
+        XCTAssertFalse(
+            SystemInfo.canFitModelInMemory(
+                .base,
+                physicalMemoryGB: 16,
+                availableBytes: 64 * 1024 * 1024
+            )
+        )
+    }
+
+    func testCanFitModelAllowsWhenAvailableIsUnknown() {
+        XCTAssertTrue(
+            SystemInfo.canFitModelInMemory(
+                .tiny,
+                physicalMemoryGB: 8,
+                availableBytes: 0
+            )
+        )
+    }
+
+    func testCanFitModelAllowsWhenPhysicalAndAvailableAreEnough() {
+        let required = UInt64((ModelSize.base.ramRequiredGB * 1024 * 1024 * 1024).rounded(.up))
+        XCTAssertTrue(
+            SystemInfo.canFitModelInMemory(
+                .base,
+                physicalMemoryGB: 16,
+                availableBytes: required
+            )
+        )
+    }
 }
 
 // MARK: - ModelSize Tests