fix(memory): platform-aware override floor so mid-size models load on high-RAM Android

The user's original bug: a ~3.7GB model refused on a 12GB phone. Root cause: the override
survival floor (1200MB) is calibrated for iOS jetsam, but a 12GB Android phone exposes only
~4.5GB physical availMem, so 4500-3700=800 < 1200 → refused.

Fix (the SAFE version, not the reverted swap-credit): a platform-aware floor. Android backs
the OS and other apps with zram/LMK (foreground app killed last), so the override reserves a
smaller physical margin (KV growth, 700MB) instead of iOS's full jetsam buffer. Crucially this
stays PHYSICAL-based — the dirty model's full footprint is still subtracted from real availMem,
so an oversized dirty model (e.g. 5.2GB LiteRT on ~4.5GB physical → negative) is still REFUSED.
That's the OOM guard my earlier swap-credit fix lacked (it credited swap toward a dirty model
that can't be swapped → loaded → OOM; reverted).

Result: ~3.7GB models load on high-RAM Android (800>700); 5.2GB still refused; iOS unchanged
(800<1200 jetsam floor holds). Tests cover all three. NEEDS on-device verification — [MEM-SM]
logs the real numbers; the 700MB margin may need device tuning.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: alichherawalla

__tests__/unit/services/modelResidency.test.ts

@@ -783,6 +783,56 @@ describe('ModelResidencyManager', () => {
       expect(unloadSmall).toHaveBeenCalledTimes(1); // we tried (freed everything first)
       expect(fits).toBe(false); // but real physics still refuses
     });
+
+    // Platform-aware floor: Android backs the OS/other apps with zram, so the override reserves a
+    // smaller physical margin (KV growth) than iOS's full jetsam floor. This is what lets a
+    // ~3.7GB model load on a 12GB phone (physical availMem ~4.5GB) instead of the iOS-calibrated
+    // 1200 floor refusing it — WITHOUT the swap-credit mistake (the dirty footprint is still
+    // subtracted from real physical, so an oversized dirty model still goes negative → refused).
+    describe('platform-aware override floor', () => {
+      const RN = require('react-native');
+      const originalOS = RN.Platform.OS;
+      afterEach(() => { RN.Platform.OS = originalOS; });
+
+      it('ANDROID: a ~3.7GB dirty model that leaves ~800MB physical LOADS (was refused by the iOS 1200 floor)', async () => {
+        RN.Platform.OS = 'android';
+        modelResidencyManager.setBudgetOverrideMB(null);
+        jest.spyOn(hardwareService, 'refreshMemoryInfo').mockResolvedValue(undefined as never);
+        jest.spyOn(hardwareService, 'getTotalMemoryGB').mockReturnValue(12);
+        jest.spyOn(hardwareService, 'getAvailableMemoryGB').mockReturnValue(4.5); // ~4500MB physical
+        const { fits } = await modelResidencyManager.makeRoomFor(
+          { key: 'text', type: 'text', sizeMB: 3700, dirtyMemory: true }, // 4500-3700=800 > 700 android floor
+          { override: true },
+        );
+        expect(fits).toBe(true); // loads on Android (800 > 700) — the user's 12GB-phone case
+      });
+
+      it('ANDROID: an oversized dirty model that exceeds PHYSICAL is still refused (the OOM guard, no swap credit)', async () => {
+        RN.Platform.OS = 'android';
+        modelResidencyManager.setBudgetOverrideMB(null);
+        jest.spyOn(hardwareService, 'refreshMemoryInfo').mockResolvedValue(undefined as never);
+        jest.spyOn(hardwareService, 'getTotalMemoryGB').mockReturnValue(12);
+        jest.spyOn(hardwareService, 'getAvailableMemoryGB').mockReturnValue(4.5);
+        const { fits } = await modelResidencyManager.makeRoomFor(
+          { key: 'text', type: 'text', sizeMB: 5235, dirtyMemory: true }, // 4500-5235 = negative → refuse (the E4B OOM case)
+          { override: true },
+        );
+        expect(fits).toBe(false); // refused — a 5.2GB dirty model can't fit ~4.5GB physical (would OOM)
+      });
+
+      it('iOS: the same ~3.7GB dirty model is REFUSED (full jetsam floor stands — no user swap)', async () => {
+        RN.Platform.OS = 'ios';
+        modelResidencyManager.setBudgetOverrideMB(null);
+        jest.spyOn(hardwareService, 'refreshMemoryInfo').mockResolvedValue(undefined as never);
+        jest.spyOn(hardwareService, 'getTotalMemoryGB').mockReturnValue(12);
+        jest.spyOn(hardwareService, 'getAvailableMemoryGB').mockReturnValue(4.5);
+        const { fits } = await modelResidencyManager.makeRoomFor(
+          { key: 'text', type: 'text', sizeMB: 3700, dirtyMemory: true }, // 4500-3700=800 < 1200 iOS floor
+          { override: true },
+        );
+        expect(fits).toBe(false); // iOS unchanged — 800 < 1200 jetsam floor
+      });
+    });
   });
 
   describe('session override memory (approve Load Anyway once per model)', () => {

src/services/memoryBudget.ts

@@ -57,6 +57,27 @@ export const AGGRESSIVE_RESERVE_MB = 800;
  * (e.g. many background apps have eaten the baseline).
  */
 export const OVERRIDE_SURVIVAL_FLOOR_MB = 1200;
+/**
+ * Android's override floor is LOWER than iOS's because the physics differ:
+ *  - iOS: no user swap; exceeding os_proc_available_memory is an uncatchable jetsam SIGKILL, so
+ *    we hold the full 1200MB physical reserve.
+ *  - Android: zram/swap + the low-memory killer back the OS and OTHER apps (their pages compress
+ *    to zram / background is killed) — the foreground app is killed LAST. The model's own dirty
+ *    (GPU) pages still need PHYSICAL RAM (this check subtracts the full dirty footprint from real
+ *    physical availMem, so an oversized dirty model — e.g. a 5.2GB LiteRT on ~4.5GB physical —
+ *    still goes negative and is refused), but the SYSTEM survives on swap, so we only reserve a
+ *    physical margin for the model's KV-cache growth, not a full jetsam buffer. This is what lets
+ *    a ~3.7GB model load on a 12GB phone (physical availMem ~4.5GB) instead of being refused by
+ *    the iOS-calibrated 1200 floor, WITHOUT the swap-credit mistake that let an oversized dirty
+ *    model load and OOM. NEEDS on-device tuning/verification ([MEM-SM] logs the real numbers).
+ */
+export const ANDROID_OVERRIDE_SURVIVAL_FLOOR_MB = 700;
+/** The override survival floor for the current platform (data-driven, not a scattered branch). */
+export function overrideSurvivalFloorMB(platform: Plat = Platform.OS): number {
+  return platform === 'android'
+    ? ANDROID_OVERRIDE_SURVIVAL_FLOOR_MB
+    : OVERRIDE_SURVIVAL_FLOOR_MB;
+}
 
 type Plat = 'ios' | 'android' | string;
 

src/services/modelResidency/index.ts

@@ -18,7 +18,7 @@ import {
   Resident,
   ResidentType,
 } from './policy';
-import { LoadPolicy, OVERRIDE_SURVIVAL_FLOOR_MB } from '../memoryBudget';
+import { LoadPolicy, overrideSurvivalFloorMB } from '../memoryBudget';
 
 type UnloadFn = () => Promise<void>;
 
@@ -395,9 +395,14 @@ class ModelResidencyManager {
       );
       const incomingDirtyMB = spec.dirtyMemory ? spec.sizeMB : 0;
       const postLoadFreeMB = realAvailMB - incomingDirtyMB;
-      if (postLoadFreeMB < OVERRIDE_SURVIVAL_FLOOR_MB) {
+      // Physical-based (NO swap credit): the dirty model's own footprint is subtracted from real
+      // physical availMem, so an oversized dirty model still goes negative and is refused (the
+      // OOM guard). The FLOOR is platform-aware: Android backs the OS/other apps with zram so it
+      // reserves only a KV-growth margin; iOS holds the full jetsam reserve.
+      const floorMB = overrideSurvivalFloorMB();
+      if (postLoadFreeMB < floorMB) {
         logger.log(
-          `[MEM-SM] makeRoomFor ${spec.key} REFUSED even under override - real post-evict free ~${postLoadFreeMB}MB < survival floor ${OVERRIDE_SURVIVAL_FLOOR_MB}MB`,
+          `[MEM-SM] makeRoomFor ${spec.key} REFUSED even under override - real post-evict free ~${postLoadFreeMB}MB < survival floor ${floorMB}MB`,
         );
         return { evicted: plan.evict.map(e => e.key), fits: false };
       }