@buoy-gg/storage 7.0.17 → 7.0.18

package/lib/module/storage/hooks/useAsyncStorageKeys.js

@@ -3,6 +3,7 @@
 import { useState, useEffect, useCallback, useRef } from 'react';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import { readMany } from '../utils/asyncStorageCompat';
+import { requiredKeyAppliesTo } from '../utils/requiredStorageKeyScope';
 export function useAsyncStorageKeys(requiredStorageKeys = []) {
   // State management
   const [storageKeys, setStorageKeys] = useState([]);
@@ -48,8 +49,9 @@ export function useAsyncStorageKeys(requiredStorageKeys = []) {
           }
         }
 
-        // Check if this is a required key
+        // Check if this is a required key scoped to AsyncStorage
         const requiredConfig = requiredStorageKeys.find(req => {
+          if (!requiredKeyAppliesTo(req, 'async')) return false;
           if (typeof req === 'string') return req === key;
           return req.key === key;
         });
@@ -59,9 +61,9 @@ export function useAsyncStorageKeys(requiredStorageKeys = []) {
         if (requiredConfig) {
           if (parsedValue === undefined || parsedValue === null) {
             status = 'required_missing';
-          } else if (typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig) {
+          } else if (typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined) {
             status = parsedValue === requiredConfig.expectedValue ? 'required_present' : 'required_wrong_value';
-          } else if (typeof requiredConfig === 'object' && 'expectedType' in requiredConfig) {
+          } else if (typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined) {
             const actualType = parsedValue === null ? 'null' : typeof parsedValue;
             status = actualType.toLowerCase() === requiredConfig.expectedType.toLowerCase() ? 'required_present' : 'required_wrong_type';
           } else {
@@ -74,21 +76,22 @@ export function useAsyncStorageKeys(requiredStorageKeys = []) {
           storageType: 'async',
           status,
           category: requiredConfig ? 'required' : 'optional',
-          ...(typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined && {
             expectedValue: requiredConfig.expectedValue
           }),
-          ...(typeof requiredConfig === 'object' && 'expectedType' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined && {
             expectedType: requiredConfig.expectedType
           }),
-          ...(typeof requiredConfig === 'object' && 'description' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.description !== undefined && {
             description: requiredConfig.description
           })
         };
         allStorageKeys.push(keyInfo);
       });
 
-      // 4. Add missing required keys
+      // 4. Add missing required keys (Async-scoped only)
       requiredStorageKeys.forEach(req => {
+        if (!requiredKeyAppliesTo(req, 'async')) return;
         const key = typeof req === 'string' ? req : req.key;
         const exists = allStorageKeys.some(k => k.key === key);
         if (!exists) {
@@ -98,13 +101,13 @@ export function useAsyncStorageKeys(requiredStorageKeys = []) {
             storageType: 'async',
             status: 'required_missing',
             category: 'required',
-            ...(typeof req === 'object' && 'expectedValue' in req && {
+            ...(typeof req === 'object' && req.expectedValue !== undefined && {
               expectedValue: req.expectedValue
             }),
-            ...(typeof req === 'object' && 'expectedType' in req && {
+            ...(typeof req === 'object' && req.expectedType !== undefined && {
               expectedType: req.expectedType
             }),
-            ...(typeof req === 'object' && 'description' in req && {
+            ...(typeof req === 'object' && req.description !== undefined && {
               description: req.description
             })
           });

package/lib/module/storage/hooks/useMMKVKeys.js

@@ -14,6 +14,7 @@
  */
 
 import { useState, useEffect, useCallback, useRef } from 'react';
+import { requiredKeyAppliesTo } from '../utils/requiredStorageKeyScope';
 // Pure-JS utilities (no react-native-mmkv dependency) — safe to import
 // unconditionally. They operate on whatever instance objects are registered,
 // including remote-backed wrappers on the desktop dashboard.
@@ -92,12 +93,12 @@ export function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
       // 1. Get all keys from MMKV (synchronous)
       const allKeys = instance.getAllKeys();
       if (!allKeys || allKeys.length === 0) {
-        // Still need to check for missing required keys
-        const missingRequiredKeys = requiredStorageKeys.map(req => {
+        // Still need to check for missing required keys scoped to MMKV
+        const missingRequiredKeys = requiredStorageKeys.filter(req => requiredKeyAppliesTo(req, 'mmkv')).map(req => {
           const key = typeof req === 'string' ? req : req.key;
-          const description = typeof req === 'object' && 'description' in req ? req.description : undefined;
-          const expectedValue = typeof req === 'object' && 'expectedValue' in req ? req.expectedValue : undefined;
-          const expectedType = typeof req === 'object' && 'expectedType' in req ? req.expectedType : undefined;
+          const description = typeof req === 'object' ? req.description : undefined;
+          const expectedValue = typeof req === 'object' ? req.expectedValue : undefined;
+          const expectedType = typeof req === 'object' ? req.expectedType : undefined;
           return {
             key,
             value: undefined,
@@ -125,8 +126,9 @@ export function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
           type
         } = detectMMKVType(instance, key);
 
-        // Check if this is a required key
+        // Check if this is a required key scoped to MMKV
         const requiredConfig = requiredStorageKeys.find(req => {
+          if (!requiredKeyAppliesTo(req, 'mmkv')) return false;
           if (typeof req === 'string') return req === key;
           return req.key === key;
         });
@@ -136,10 +138,10 @@ export function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
         if (requiredConfig) {
           if (value === undefined) {
             status = 'required_missing';
-          } else if (typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig) {
+          } else if (typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined) {
             // Value validation
             status = String(value) === String(requiredConfig.expectedValue) ? 'required_present' : 'required_wrong_value';
-          } else if (typeof requiredConfig === 'object' && 'expectedType' in requiredConfig) {
+          } else if (typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined) {
             // Type validation
             status = isTypeMatch(type, requiredConfig.expectedType) ? 'required_present' : 'required_wrong_type';
           } else {
@@ -158,13 +160,13 @@ export function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
           status,
           category: requiredConfig ? 'required' : 'optional',
           lastUpdated: new Date(),
-          ...(typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined && {
             expectedValue: requiredConfig.expectedValue
           }),
-          ...(typeof requiredConfig === 'object' && 'expectedType' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined && {
             expectedType: requiredConfig.expectedType
           }),
-          ...(typeof requiredConfig === 'object' && 'description' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.description !== undefined && {
             description: requiredConfig.description
           })
         };
@@ -173,6 +175,7 @@ export function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
 
       // 3. Add missing required keys that weren't found in storage
       requiredStorageKeys.forEach(req => {
+        if (!requiredKeyAppliesTo(req, 'mmkv')) return;
         const key = typeof req === 'string' ? req : req.key;
         const exists = allStorageKeys.some(k => k.key === key);
         if (!exists) {
@@ -184,13 +187,13 @@ export function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
             instanceId,
             status: 'required_missing',
             category: 'required',
-            ...(typeof req === 'object' && 'expectedValue' in req && {
+            ...(typeof req === 'object' && req.expectedValue !== undefined && {
               expectedValue: req.expectedValue
             }),
-            ...(typeof req === 'object' && 'expectedType' in req && {
+            ...(typeof req === 'object' && req.expectedType !== undefined && {
               expectedType: req.expectedType
             }),
-            ...(typeof req === 'object' && 'description' in req && {
+            ...(typeof req === 'object' && req.description !== undefined && {
               description: req.description
             })
           });
@@ -279,6 +282,7 @@ export function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
             type
           } = detectMMKVType(instance, key);
           const requiredConfig = requiredStorageKeys.find(req => {
+            if (!requiredKeyAppliesTo(req, 'mmkv')) return false;
             if (typeof req === 'string') return req === key;
             return req.key === key;
           });
@@ -286,9 +290,9 @@ export function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
           if (requiredConfig) {
             if (value === undefined) {
               status = 'required_missing';
-            } else if (typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig) {
+            } else if (typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined) {
               status = String(value) === String(requiredConfig.expectedValue) ? 'required_present' : 'required_wrong_value';
-            } else if (typeof requiredConfig === 'object' && 'expectedType' in requiredConfig) {
+            } else if (typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined) {
               status = isTypeMatch(type, requiredConfig.expectedType) ? 'required_present' : 'required_wrong_type';
             } else {
               status = 'required_present';
@@ -303,13 +307,13 @@ export function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
             status,
             category: requiredConfig ? 'required' : 'optional',
             lastUpdated: new Date(),
-            ...(typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig && {
+            ...(typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined && {
               expectedValue: requiredConfig.expectedValue
             }),
-            ...(typeof requiredConfig === 'object' && 'expectedType' in requiredConfig && {
+            ...(typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined && {
               expectedType: requiredConfig.expectedType
             }),
-            ...(typeof requiredConfig === 'object' && 'description' in requiredConfig && {
+            ...(typeof requiredConfig === 'object' && requiredConfig.description !== undefined && {
               description: requiredConfig.description
             })
           };
@@ -317,8 +321,9 @@ export function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
         });
       });
 
-      // Add missing required keys
+      // Add missing required keys scoped to MMKV
       requiredStorageKeys.forEach(req => {
+        if (!requiredKeyAppliesTo(req, 'mmkv')) return;
         const key = typeof req === 'string' ? req : req.key;
         const exists = allStorageKeys.some(k => k.key === key);
         if (!exists) {
@@ -333,13 +338,13 @@ export function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
             instanceId: firstInstanceId,
             status: 'required_missing',
             category: 'required',
-            ...(typeof req === 'object' && 'expectedValue' in req && {
+            ...(typeof req === 'object' && req.expectedValue !== undefined && {
               expectedValue: req.expectedValue
             }),
-            ...(typeof req === 'object' && 'expectedType' in req && {
+            ...(typeof req === 'object' && req.expectedType !== undefined && {
               expectedType: req.expectedType
             }),
-            ...(typeof req === 'object' && 'description' in req && {
+            ...(typeof req === 'object' && req.description !== undefined && {
               description: req.description
             })
           });

package/lib/module/storage/stores/storageEventStore.js

@@ -35,6 +35,35 @@ import { detectMMKVType } from "../utils/mmkvTypeDetection";
  * millisecond timestamp), and React keys must be unique per render.
  */
 
+/** True when a field is the wire-form VALUE_ON_DEVICE marker. */
+export function isValueOnDevice(value) {
+  return !!value && typeof value === "object" && value.__buoyValueOnDevice === true;
+}
+
+/**
+ * `pairs` / `prevPairs` are AsyncStorage-only — they carry the batch
+ * operations (multiSet / multiRemove / multiMerge / clear), and MMKV has no
+ * batch API, so its `data` has no such fields. Reading them off the
+ * `StorageEvent` union needs narrowing, and this is the one place that does
+ * it; writing them unconditionally would also graft meaningless keys onto
+ * every MMKV event on the wire.
+ */
+export function batchPairsOf(event) {
+  if (event.storageType !== "async" || !event.data) return {};
+  return {
+    pairs: event.data.pairs,
+    prevPairs: event.data.prevPairs
+  };
+}
+function eventHasOnDeviceValues(event) {
+  const data = event.data;
+  if (!data) return false;
+  const {
+    pairs,
+    prevPairs
+  } = batchPairsOf(event);
+  return isValueOnDevice(data.value) || isValueOnDevice(data.prevValue) || isValueOnDevice(pairs) || isValueOnDevice(prevPairs);
+}
 let storageEventIdCounter = 0;
 function nextStorageEventId() {
   return `se-${Date.now()}-${++storageEventIdCounter}`;
@@ -207,6 +236,58 @@ class StorageEventStore extends BaseEventStore {
   getEventsByType(storageType) {
     return this.events.filter(event => event.storageType === storageType);
   }
+
+  /**
+   * Replace the event list, keeping values a remote mirror already hydrated.
+   * Wire-form snapshots always carry VALUE_ON_DEVICE markers for oversized
+   * payloads; a later snapshot must not blank the detail pane (or wipe
+   * `prevValue` that time-travel undo needs).
+   */
+  replaceEvents(events) {
+    const hydrated = new Map();
+    for (const existing of this.events) {
+      if (!eventHasOnDeviceValues(existing)) {
+        hydrated.set(existing.id, existing);
+      }
+    }
+    const merged = events.map(incoming => {
+      const kept = hydrated.get(incoming.id);
+      if (!kept || !eventHasOnDeviceValues(incoming)) return incoming;
+      // Restore only the fields this event's storage type actually has, so an
+      // MMKV event never grows `pairs`/`prevPairs` it has no meaning for.
+      return {
+        ...incoming,
+        data: {
+          ...incoming.data,
+          value: kept.data?.value,
+          prevValue: kept.data?.prevValue,
+          ...batchPairsOf(kept)
+        }
+      };
+    });
+    super.replaceEvents(merged);
+  }
+
+  /**
+   * Hydrate one mirrored event with real values fetched on demand from the
+   * device via the adapter's `getEventDetail`. Remote-mirror (desktop) only.
+   */
+  hydrateEvent(event) {
+    const index = this.events.findIndex(e => e.id === event.id);
+    if (index === -1) return;
+    const current = this.events[index];
+    const next = this.events.slice();
+    next[index] = {
+      ...current,
+      ...event,
+      timestamp: current.timestamp,
+      data: {
+        ...current.data,
+        ...event.data
+      }
+    };
+    super.replaceEvents(next);
+  }
 }
 
 // Singleton instance

package/lib/module/storage/sync/storageSyncAdapter.js

@@ -1,15 +1,157 @@
 "use strict";
 
 import AsyncStorage from "@react-native-async-storage/async-storage";
-import { isDevToolsStorageKey } from "@buoy-gg/shared-ui";
+import { approxJsonSize, isDevToolsStorageKey, isOverWireBudget, isJsonSerializable } from "@buoy-gg/shared-ui";
 import { readMany, writeMany, removeMany } from "../utils/asyncStorageCompat";
-import { storageEventStore } from "../stores/storageEventStore";
+import { batchPairsOf, storageEventStore } from "../stores/storageEventStore";
 import { clearAllAppStorage } from "../utils/clearAllStorage";
 import { undoOperation, jumpToState, canUndo } from "../utils/storageTimeTravelUtils";
 import { mmkvInstanceRegistry } from "../utils/MMKVInstanceRegistry";
 import { detectMMKVType } from "../utils/mmkvTypeDetection";
 import { secureStoreRegistry } from "../utils/SecureStoreRegistry";
 
+/**
+ * Sentinel used in WIRE-FORM snapshots in place of oversized values.
+ * Storage events, MMKV browse dumps, and SecureStore dumps all reuse this
+ * marker. Dashboards fetch the real payload via `getEventDetail` / `mmkv.get`
+ * / `secure.get`.
+ */
+export const VALUE_ON_DEVICE = Object.freeze({
+  __buoyValueOnDevice: true,
+  note: "Value stays on the device — fetched on demand via getEventDetail / mmkv.get / secure.get."
+});
+
+/** Max serialized bytes of one storage value on the list snapshot. */
+export const SNAPSHOT_VALUE_INLINE_LIMIT = 16 * 1024;
+
+/**
+ * Total inline budget for one snapshot's event list, held under the emit
+ * layer's 2MB so a snapshot is never DROPPED (a drop leaves the whole panel
+ * stale). Per-value caps alone don't get there: the store keeps 500 events, so
+ * 500 writes of an individually-legal 9KB value still total ~4.7MB. Newest
+ * events keep their values inline; once the budget is spent, older ones
+ * degrade to metadata + fetch-on-demand.
+ */
+export const SNAPSHOT_EVENTS_BUDGET = 1.25 * 1024 * 1024;
+const MAX_EVENT_DETAIL_BYTES = 8 * 1024 * 1024;
+function toWireValue(value) {
+  if (value === undefined) return value;
+  return isOverWireBudget(value, SNAPSHOT_VALUE_INLINE_LIMIT) ? VALUE_ON_DEVICE : value;
+}
+
+/**
+ * Apply `map` to every payload field an event carries, preserving object
+ * identity when nothing changed (the desktop mirror feeds these into effect
+ * dependencies, so a fresh object per snapshot would re-run them).
+ *
+ * The cast is deliberate and load-bearing: the wire form intentionally puts a
+ * marker OBJECT where the domain type declares a string, because the real
+ * value stayed on the device. `StorageEvent` describes on-device truth; this
+ * is its wire projection.
+ */
+function mapEventValues(event, map) {
+  const data = event.data;
+  if (!data) return event;
+  const value = map(data.value);
+  const prevValue = map(data.prevValue);
+  const batch = batchPairsOf(event);
+  const pairs = map(batch.pairs);
+  const prevPairs = map(batch.prevPairs);
+  if (value === data.value && prevValue === data.prevValue && pairs === batch.pairs && prevPairs === batch.prevPairs) {
+    return event;
+  }
+  return {
+    ...event,
+    data: {
+      ...data,
+      value,
+      prevValue,
+      // Only AsyncStorage events have these; see batchPairsOf.
+      ...(event.storageType === "async" ? {
+        pairs,
+        prevPairs
+      } : {})
+    }
+  };
+}
+function capDetailValue(value) {
+  if (value === undefined) return value;
+  if (!isOverWireBudget(value, MAX_EVENT_DETAIL_BYTES)) return value;
+  return isJsonSerializable(value) ? {
+    __buoyTruncated: true,
+    note: `Exceeds the ${MAX_EVENT_DETAIL_BYTES / (1024 * 1024)}MB detail limit — inspect it on-device.`
+  } : VALUE_ON_DEVICE;
+}
+
+/** One event's wire form plus its measured cost, so the budget pass is free. */
+
+/**
+ * Per-event wire cache. The store never mutates an event in place — `addEvent`
+ * prepends and `hydrateEvent` replaces — so keying on identity is correct and
+ * self-invalidating. Without it every value is re-measured on all ~5 snapshots
+ * per second for as long as it stays in the list, which for storage means
+ * re-walking megabytes of strings per tick.
+ */
+const wireCache = new WeakMap();
+const strippedCache = new WeakMap();
+function wireFor(event) {
+  const cached = wireCache.get(event);
+  if (cached) return cached;
+  let entry;
+  try {
+    const wire = mapEventValues(event, toWireValue);
+    entry = {
+      event: wire,
+      bytes: approxJsonSize(wire, SNAPSHOT_EVENTS_BUDGET).bytes
+    };
+  } catch {
+    // A hostile getter can blow up the walk itself. Degrading this ONE event
+    // beats letting getSnapshot throw and taking the whole panel with it.
+    const wire = mapEventValues(event, () => VALUE_ON_DEVICE);
+    entry = {
+      event: wire,
+      bytes: 1024
+    };
+  }
+  wireCache.set(event, entry);
+  return entry;
+}
+
+/** Metadata-only form for the tail of the list once the budget is spent. */
+function strippedFor(event) {
+  const cached = strippedCache.get(event);
+  if (cached) return cached;
+  const wire = mapEventValues(event, v => v === undefined ? undefined : VALUE_ON_DEVICE);
+  const entry = {
+    event: wire,
+    bytes: approxJsonSize(wire, SNAPSHOT_EVENTS_BUDGET).bytes
+  };
+  strippedCache.set(event, entry);
+  return entry;
+}
+
+/**
+ * Spend the snapshot budget newest-first. The store keeps events newest-first,
+ * so the developer keeps full detail on what they are actually looking at and
+ * the tail degrades rather than the whole panel being dropped.
+ */
+function fitEventsToBudget(events) {
+  const out = new Array(events.length);
+  let spent = 0;
+  for (let i = 0; i < events.length; i++) {
+    const full = wireFor(events[i]);
+    if (spent + full.bytes <= SNAPSHOT_EVENTS_BUDGET) {
+      out[i] = full.event;
+      spent += full.bytes;
+    } else {
+      const lean = strippedFor(events[i]);
+      out[i] = lean.event;
+      spent += lean.bytes;
+    }
+  }
+  return out;
+}
+
 /** One MMKV entry in a `mmkv.snapshot` result. */
 
 /** One MMKV instance in a `mmkv.snapshot` result. */
@@ -47,22 +189,53 @@ function assertMMKVWritable(instanceId) {
  *
  * The `async.*` actions mirror the AsyncStorage API so the desktop dashboard
  * can proxy its browse/edit mode against the device's real storage.
+ *
+ * v2: oversized / unserializable event values are replaced with
+ * VALUE_ON_DEVICE. Dashboards fetch them via `getEventDetail`.
  */
 export const storageSyncAdapter = {
-  version: 1,
+  // v3: a total snapshot budget, so a burst of individually-legal values
+  // degrades the oldest events instead of the emit layer dropping the panel.
+  version: 3,
   // Strip Buoy's OWN devtool keys (@react_buoy*, @buoy*, buoy-*, legacy) at the
   // source so no sync client (desktop, MCP, raw socket) ever sees them as if
   // they were app data — matching the tools' default key filters, but
   // authoritative instead of UI-only.
-  getSnapshot: () => storageEventStore.getEvents().filter(e => {
+  getSnapshot: () => fitEventsToBudget(storageEventStore.getEvents().filter(e => {
     const key = e.data?.key;
     return !(typeof key === "string" && isDevToolsStorageKey(key));
-  }),
+  })),
   subscribe: onChange => storageEventStore.subscribeToEvents(onChange),
   actions: {
     clearEvents: () => {
       storageEventStore.clearEvents();
     },
+    /**
+     * On-demand detail: one event's real value/prevValue/pairs.
+     * The per-snapshot stream stays payload-light; this is the explicit,
+     * size-guarded channel for the detail pane (and for time-travel undo,
+     * which needs `prevValue`).
+     */
+    getEventDetail: params => {
+      const {
+        id
+      } = params ?? {};
+      if (!id) return {
+        found: false,
+        reason: "missing id"
+      };
+      const event = storageEventStore.getEvents().find(e => e.id === id);
+      if (!event) return {
+        found: false,
+        reason: "unknown id"
+      };
+      const detailed = mapEventValues(event, capDetailValue);
+      return {
+        found: true,
+        id,
+        event: detailed
+      };
+    },
     /** Clears all app storage keys, preserving dev tools settings. */
     clearAppStorage: () => clearAllAppStorage(),
     // ── Time travel (same code path as the modal's UNDO / JUMP buttons) ──
@@ -159,7 +332,7 @@ export const storageSyncAdapter = {
           } = detectMMKVType(instance, key);
           return {
             key,
-            value,
+            value: toWireValue(value),
             valueType
           };
         });
@@ -173,6 +346,41 @@ export const storageSyncAdapter = {
         entries
       };
     }),
+    /**
+     * On-demand MMKV value. `mmkv.snapshot` omits oversized strings so a
+     * browse poll cannot blow the action-result budget; this is the
+     * size-guarded channel for one key.
+     */
+    "mmkv.get": params => {
+      const {
+        instanceId,
+        key
+      } = params ?? {};
+      if (!instanceId || !key) {
+        return {
+          found: false,
+          reason: "missing instanceId/key"
+        };
+      }
+      const registered = mmkvInstanceRegistry.get(instanceId);
+      if (!registered) {
+        return {
+          found: false,
+          reason: "unknown instance"
+        };
+      }
+      const {
+        value,
+        type: valueType
+      } = detectMMKVType(registered.instance, key);
+      return {
+        found: true,
+        instanceId,
+        key,
+        value: capDetailValue(value),
+        valueType
+      };
+    },
     "mmkv.set": params => {
       const {
         instanceId,
@@ -232,7 +440,7 @@ export const storageSyncAdapter = {
           description,
           keychainService: options.keychainService,
           requireAuthentication: options.requireAuthentication ?? false,
-          value
+          value: value == null ? value : toWireValue(value)
         });
       }
       return result;

package/lib/module/storage/utils/requiredStorageKeyScope.js

@@ -0,0 +1,13 @@
+"use strict";
+
+/**
+ * Whether a required-key declaration should be enforced by a given backend
+ * hook. Explicit `storageType` wins; bare string keys default to AsyncStorage
+ * (the historical zero-config backend). Objects without `storageType` still
+ * apply to every backend — matching prior behavior for apps that never set it.
+ */
+export function requiredKeyAppliesTo(req, backend) {
+  if (typeof req === "string") return backend === "async";
+  if (req.storageType) return req.storageType === backend;
+  return true;
+}