@buoy-gg/react-query 7.0.35 → 7.0.36

package/lib/commonjs/react-query/sync/reactQuerySyncAdapter.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.createReactQuerySyncAdapter = createReactQuerySyncAdapter;
+var _sharedUi = require("@buoy-gg/shared-ui");
 var _reactQuery = require("@tanstack/react-query");
 var _dehydrate = require("./dehydrate");
 var _getQueryStatusLabel = require("../utils/getQueryStatusLabel");
@@ -21,12 +22,123 @@ var _getQueryStatusLabel = require("../utils/getQueryStatusLabel");
  * on-device markers. Dashboards fetch real data via `getQueryData`.
  */
 
+/**
+ * Does this patch write into the list at `path`? Only then is an
+ * unchecked-shape warning about that list worth saying — a patch that changes
+ * `promoCode` should not be told about an empty `results`. Mirrors the same
+ * helper in the zustand adapter, which has warned about this since it shipped.
+ */
+function touchesList(patch, path) {
+  let cur = patch;
+  for (const seg of path.split(".")) {
+    if (!cur || typeof cur !== "object" || Array.isArray(cur)) return false;
+    if (!(seg in cur)) return false;
+    cur = cur[seg];
+  }
+  // An empty list stays empty; there is no new item to be unsure about.
+  return Array.isArray(cur) ? cur.length > 0 : !!cur && typeof cur === "object";
+}
+const isPlainObject = v => !!v && typeof v === "object" && !Array.isArray(v);
+/** The shape category the screen depends on: array vs object vs the rest. */
+function shapeKind(v) {
+  if (Array.isArray(v)) return "array";
+  if (v === null) return "null";
+  if (typeof v === "object") return "object";
+  return typeof v;
+}
+
+/**
+ * Objects merge key by key; arrays and primitives are replaced. Two dangers a
+ * remote caller (an LLM most of all) hits are collected instead of silently
+ * written:
+ *
+ * - `shrunk`: a non-empty array shorter than the one it replaces — "change
+ *   item 0" sent as only item 0, dropping the rest.
+ * - `breaks`: a field whose SHAPE changes — an array or object overwritten by
+ *   null or a primitive. This is the crash we actually shipped: a model set
+ *   the siblings it wasn't changing (`sizes:null, store:null`) thinking it had
+ *   to name them, and the screen's `sizes.map(s => s.multiplier)` threw. Merge
+ *   KEEPS untouched fields, so nulling them is never necessary and never safe.
+ *
+ * The handler refuses either unless forced. An empty array (explicit clear)
+ * and null→value / value→value-of-same-kind are fine.
+ */
+function deepMerge(base, patch, path = "", issues = {
+  shrunk: [],
+  breaks: []
+}) {
+  if (Array.isArray(base) && Array.isArray(patch)) {
+    if (patch.length > 0 && patch.length < base.length) {
+      issues.shrunk.push({
+        path: path || "(root)",
+        have: base.length,
+        sent: patch.length
+      });
+    }
+    return patch;
+  }
+  if (!isPlainObject(base) || !isPlainObject(patch)) return patch;
+  const out = {
+    ...base
+  };
+  for (const [k, v] of Object.entries(patch)) {
+    const p = path ? `${path}.${k}` : k;
+    if (k in base) {
+      const from = shapeKind(base[k]);
+      const to = shapeKind(v);
+      // A populated array/object being replaced by null or a primitive breaks
+      // the shape the screen renders. (object→object and array→array recurse
+      // or replace normally; null/primitive→anything is a real value change.)
+      if ((from === "array" || from === "object") && from !== to) {
+        issues.breaks.push({
+          path: p,
+          from,
+          to
+        });
+      }
+      out[k] = deepMerge(base[k], v, p, issues);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+/** Parse a loose, non-hash key spelling into comparable string parts, or null. */
+function looseKeyParts(raw) {
+  const trimmed = raw.trim();
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) {
+      return parsed.map(k => typeof k === "object" && k !== null ? JSON.stringify(k) : String(k));
+    }
+  } catch {
+    /* not JSON — fall through to comma splitting */
+  }
+  if (trimmed.includes(",") && !trimmed.startsWith("[")) {
+    return trimmed.split(",").map(s => s.trim().replace(/^["']|["']$/g, ""));
+  }
+  return null;
+}
 function createReactQuerySyncAdapter(queryClient) {
   const getQuery = params => {
     const {
       queryHash
     } = params;
-    const query = queryClient.getQueryCache().get(queryHash);
+    const cache = queryClient.getQueryCache();
+    let query = queryHash ? cache.get(queryHash) : undefined;
+    // Tolerate a key that is not an exact hash. Models routinely send a
+    // comma-joined key ("pokemon-detail,mewtwo,fetch") or a JSON array where a
+    // hash is wanted; resolve it against the live cache by comparing each
+    // query's key parts, so one malformed hash does not cost a turn.
+    if (!query && typeof queryHash === "string") {
+      const wanted = looseKeyParts(queryHash);
+      if (wanted) {
+        query = cache.getAll().find(q => {
+          const parts = q.queryKey.map(k => typeof k === "object" ? JSON.stringify(k) : String(k));
+          return parts.length === wanted.length && parts.every((p, i) => p === wanted[i]);
+        });
+      }
+    }
     if (!query) {
       throw new Error(`Query with hash "${queryHash}" not found`);
     }
@@ -56,7 +168,8 @@ function createReactQuerySyncAdapter(queryClient) {
        */
       getQueryData: params => {
         const {
-          queryHash
+          queryHash,
+          path
         } = params ?? {};
         if (!queryHash) return {
           found: false,
@@ -67,9 +180,55 @@ function createReactQuerySyncAdapter(queryClient) {
           found: false,
           reason: "unknown queryHash"
         };
+        if (path) {
+          const at = (0, _sharedUi.readPath)(query.state.data, path);
+          if (!at.ok) return {
+            found: false,
+            reason: at.error
+          };
+          return {
+            found: true,
+            queryHash,
+            path,
+            shape: (0, _sharedUi.shapeSummary)(at.value),
+            data: at.value
+          };
+        }
+        // Before the data, not after: a long payload is sliced at the engine's
+        // 24,000-character cap, and the shape is what a caller needs in order to
+        // send a correctly NESTED edit back. Ten of eleven measured `query`
+        // write failures were one level too shallow — `{name}` for a payload
+        // that is `{item: {name}}` — and the sketch is where that is visible in
+        // one line even when the data is not.
+        // A query with no data is not the same as a query holding nothing, and
+        // the two used to be indistinguishable: an errored query, a disabled
+        // one and an empty one all came back as a bare `{found:true}`. A reader
+        // — an LLM most of all — then reports "the query is empty" when the
+        // truth is "it failed with X". `listQueries` has always known; this is
+        // the call where anyone actually asks.
+        if (query.state.data === undefined) {
+          const status = query.state.status;
+          const err = query.state.error;
+          return {
+            found: true,
+            queryHash,
+            hasData: false,
+            status,
+            fetchStatus: query.state.fetchStatus,
+            ...(err ? {
+              error: err instanceof Error ? err.message : String(err)
+            } : {}),
+            reason: status === "error" ? "This query has no data because it FAILED. Report the error, not an empty result." : query.state.fetchStatus === "fetching" ? "No data yet — this query is still fetching." : "This query has never resolved (it may be disabled, or never enabled). It is not empty — it has nothing."
+          };
+        }
+        const shape = (0, _sharedUi.shapeSummary)(query.state.data);
         return {
           found: true,
           queryHash,
+          hasData: true,
+          ...(shape ? {
+            shape
+          } : {}),
           data: (0, _dehydrate.capQueryDetail)(query.state.data)
         };
       },
@@ -88,7 +247,17 @@ function createReactQuerySyncAdapter(queryClient) {
         } = params ?? {};
         const all = queryClient.getQueryCache().getAll();
         const filtered = staleOnly ? all.filter(q => q.isStale()) : all;
-        const sorted = [...filtered].sort((a, b) => (b.state.dataUpdatedAt ?? 0) - (a.state.dataUpdatedAt ?? 0));
+        // MOUNTED FIRST, then most-recently-updated. `limit` exists to keep
+        // this cheap for a remote reader, and sorting by recency alone made it
+        // lossy in the one way that matters: a detail screen's query settles
+        // once and is then older than every background refetch, so on a cache
+        // with more live queries than the limit the query the user is actually
+        // LOOKING AT was the first thing dropped. Nothing downstream can undo
+        // that — a caller re-sorting the response can only reorder survivors.
+        const sorted = [...filtered].sort((a, b) => {
+          const mounted = Number(b.getObserversCount() > 0) - Number(a.getObserversCount() > 0);
+          return mounted !== 0 ? mounted : (b.state.dataUpdatedAt ?? 0) - (a.state.dataUpdatedAt ?? 0);
+        });
         const capped = typeof limit === "number" && limit > 0 ? sorted.slice(0, limit) : sorted;
         const queries = capped.map(q => {
           const err = q.state.error;
@@ -103,6 +272,12 @@ function createReactQuerySyncAdapter(queryClient) {
             error: err ? err.message ?? String(err) : undefined,
             ...(includeData ? {
               data: q.state.data
+            } : {}),
+            // The compact view exists so a caller can survey the cache without
+            // pulling payloads; the shape is the part of a payload it actually
+            // needs to write a correct edit, and it costs one line.
+            ...((0, _sharedUi.shapeSummary)(q.state.data) ? {
+              shape: (0, _sharedUi.shapeSummary)(q.state.data)
             } : {})
           };
         });
@@ -120,17 +295,226 @@ function createReactQuerySyncAdapter(queryClient) {
       },
       invalidate: params => queryClient.invalidateQueries(getQuery(params)),
       reset: params => queryClient.resetQueries(getQuery(params)),
+      /**
+       * Dropping a query does NOT re-drive the screen watching it.
+       *
+       * React Query removes the cache entry; a mounted observer keeps its last
+       * result in local state until something makes it fetch again. So the app
+       * carries on rendering a value that now exists nowhere — including one
+       * the agent itself wrote a moment earlier. Measured on device: `remove`
+       * on the live menu query left the storefront showing a single fabricated
+       * item, with no skeleton, no refetch and no error, while the cache held
+       * no menu at all. Returning a bare null let that be reported as "done".
+       *
+       * `reset` is the action that actually re-drives an observed query, so
+       * the note names it rather than leaving the caller to find out from a
+       * screen that looks fine.
+       */
       remove: params => {
-        queryClient.removeQueries(getQuery(params));
+        const target = getQuery(params);
+        const watched = queryClient.getQueryCache().findAll(target).some(q => q.getObserversCount() > 0);
+        queryClient.removeQueries(target);
+        return {
+          ok: true,
+          ...(watched ? {
+            note: "Removed — but a screen is still watching this query, and React Query leaves that screen rendering its LAST value (including anything written into the cache before this) until something refetches. Nothing on screen will change on its own. Use `reset` instead when you want the screen to go back to loading and fetch again."
+          } : {})
+        };
       },
       setQueryData: params => {
         const {
-          queryKey,
-          data
+          data,
+          merge,
+          force,
+          path,
+          value
         } = params;
+        /**
+         * Address the query the way EVERY OTHER action here does.
+         *
+         * This action took `queryKey` and silently ignored `queryHash` — while
+         * `listQueries` hands out `queryHash` and getQueryData / invalidate /
+         * refetch / reset / remove / triggerError / triggerLoading all take it.
+         * A caller that used the hash got `getQueryData(undefined)` →
+         * `undefined`, and so a refusal about "(root): undefined → object"
+         * that named the wrong problem. With `force:true` — which that refusal
+         * literally suggests — it wrote under an undefined key and still
+         * returned `{ok:true, changedKeys:[…]}`: a success report for a write
+         * that touched nothing, which is the one outcome this codebase refuses
+         * to ship. Ask Buoy itself was covered because the ENGINE aliases hash
+         * → key before dispatch; the MCP server, the desktop dashboard and
+         * Scenarios all call straight in here and were not.
+         */
+        const {
+          queryKey: rawKey,
+          queryHash
+        } = params;
+        let queryKey = rawKey;
+        if (queryKey === undefined && typeof queryHash === "string") {
+          const found = queryClient.getQueryCache().get(queryHash);
+          if (!found) {
+            return {
+              ok: false,
+              error: `Refused: no query with hash ${queryHash} is in the cache. Read listQueries for the current hashes — a query that has been removed or whose key includes changing params (a search term, a cart payload) will not match an older hash.`
+            };
+          }
+          queryKey = found.queryKey;
+        }
+        if (queryKey === undefined) {
+          return {
+            ok: false,
+            error: `Refused: no query was named. Send \`queryKey\` (the array from listQueries) or \`queryHash\` (its string form).`
+          };
+        }
+        const current = queryClient.getQueryData(queryKey);
+        /**
+         * There is nothing to merge INTO.
+         *
+         * The typed-edit guard answers this with "`(root)`: undefined →
+         * object", which describes the symptom and not the cause — and it is
+         * the same sentence a caller used to get when the query simply could
+         * not be found, so it taught nothing. A query with no data is usually
+         * one that FAILED or was never enabled, and that is what the caller
+         * needs to hear.
+         */
+        const existing = queryClient.getQueryCache().find({
+          queryKey,
+          exact: true
+        });
+        // Only when the query is THERE and holds nothing. A key that is not in
+        // the cache at all is a deliberate seed — `setQueryData(["new"], …)`
+        // creates the entry, and that has always worked.
+        if (current === undefined && existing && (data !== undefined || path !== undefined)) {
+          const q = existing;
+          const status = q?.state.status;
+          const why = status === "error" ? `it FAILED${q?.state.error ? ` (${q.state.error instanceof Error ? q.state.error.message : String(q.state.error)})` : ""}` : status === "pending" ? "it has never resolved (it may be disabled, or still loading)" : "it holds no data";
+          return {
+            ok: false,
+            error: `Refused: this query has no data to edit — ${why}. There is nothing to merge into. Fix the cause first (restoreError, or let it fetch), or send force:true with the COMPLETE value if you mean to seed the cache from nothing.`,
+            status
+          };
+        }
+        // `path` is sugar over a merge, resolved against the data as it is now.
+        // It only ever produces a patch; everything below — the keyed expansion,
+        // the typed-edit guard, the receipt — then runs unchanged, so the guard
+        // stays the single place that decides what a write may do.
+        // `data` stopped being schema-required when `path` became an
+        // alternative, so the handler has to reject NEITHER — the same hole that
+        // let a bare `setState` fall through to a whole-store replace. Here it
+        // would write `undefined` over a cached value.
+        if (data === undefined && path === undefined) {
+          return {
+            ok: false,
+            error: `Refused: no change was described. Send \`data\` (with merge:true for a partial edit), or \`path\` and \`value\` to set one value.`
+          };
+        }
+        let patch = data;
+        if (path !== undefined) {
+          if (value === undefined) {
+            return {
+              ok: false,
+              error: `Refused: sent \`path\` without \`value\`. Say what to set "${path}" to; if you mean to clear it, send value:null and the field must already be nullable.`
+            };
+          }
+          const built = (0, _sharedUi.patchFromPath)(current, path, value);
+          if (!built.ok) return {
+            ok: false,
+            error: `Refused: ${built.error}`
+          };
+          patch = built.patch;
+        }
+        if (merge || path !== undefined) {
+          // Address list items by their own id instead of resending the list:
+          //   {"results": {"pikachu": {"name": "test123"}}}
+          // Expanded BEFORE the guard below, so the typed-edit rule still holds
+          // over the result. This is the only form that works when the read was
+          // truncated — and a capped read is the normal case here, not the edge
+          // one. See packages/shared/src/sync/keyedArrays.ts for the measurement.
+          const expandedKeyed = force ? {
+            patch,
+            notes: [],
+            error: undefined
+          } : (0, _sharedUi.expandKeyedArrays)(current, patch);
+          // An id that contradicts its own address is refused HERE, where we
+          // still know both halves; the typed-edit guard downstream would only
+          // see the item we picked and could not name the ambiguity.
+          if (expandedKeyed.error) {
+            return {
+              ok: false,
+              error: `Refused: ${expandedKeyed.error}`
+            };
+          }
+          const effective = expandedKeyed.patch;
+          // Edit like the devtools value editor: only same-type changes to
+          // fields that already exist. One rule replaces every ad-hoc guard —
+          // no new keys, no type changes, no null-ing a rendered array/object,
+          // no resizing a list. This is what makes a crash structurally
+          // impossible. `force` drops to a raw write for the rare real case.
+          if (!force) {
+            const violations = (0, _sharedUi.typedEditViolations)(current, effective, {
+              noun: "data"
+            });
+            if (violations.length > 0) {
+              const suggestion = (0, _sharedUi.suggestedPatch)(effective, violations);
+              return {
+                ok: false,
+                error: (0, _sharedUi.refusalText)(violations, "data", suggestion),
+                violations,
+                ...(suggestion ? {
+                  suggestedData: suggestion
+                } : {})
+              };
+            }
+          }
+          const next = deepMerge(current, effective);
+          // A list that was EMPTY had no item shape for anything to check the
+          // new item against — not the guard above, not the reader, not the
+          // app. The zustand tool has always said so; this one stayed silent
+          // while the system prompt told the model the note always arrives, so
+          // a write of an invented shape into an empty list came back a clean
+          // success and got reported as one.
+          const unchecked = (0, _sharedUi.unshapedLists)(current).filter(p => touchesList(effective, p));
+          queryClient.setQueryData(queryKey, next, {
+            updatedAt: Date.now()
+          });
+          return {
+            ok: true,
+            mode: "merge",
+            ...(path !== undefined ? {
+              path
+            } : {}),
+            changedKeys: isPlainObject(effective) ? Object.keys(effective) : undefined,
+            ...(expandedKeyed.notes.length ? {
+              keyed: expandedKeyed.notes
+            } : {}),
+            ...(unchecked.length ? {
+              unchecked: unchecked.map(p => `\`${p}\` was empty, so nothing in the app knows what its items look like and the shape of what you added was NOT checked. If the screen renders a field you left out, it will render undefined — read the query back and compare against how the screen uses it.`)
+            } : {})
+          };
+        }
+        // THE GUARD. A remote caller — an LLM most of all — reads the cached
+        // value through a wire that truncates big payloads, edits one field,
+        // and writes the torn object back. The screen then renders
+        // `data.stats.map` over a field that no longer exists and the app
+        // dies. If the replacement silently drops top-level keys the cache
+        // has, that is almost never intended, so refuse and name the fix.
+        if (!force && isPlainObject(current) && isPlainObject(data)) {
+          const missing = Object.keys(current).filter(k => !(k in data));
+          if (missing.length > 0) {
+            return {
+              ok: false,
+              error: `Refused: the new value drops ${missing.length} top-level field(s) the cached value has (${missing.slice(0, 8).join(", ")}${missing.length > 8 ? ", …" : ""}). A screen rendering those fields would crash. To change some fields, send merge:true with ONLY the fields that change. To really replace the whole value, send force:true.`,
+              missingKeys: missing
+            };
+          }
+        }
         queryClient.setQueryData(queryKey, data, {
           updatedAt: Date.now()
         });
+        return {
+          ok: true,
+          mode: "replace"
+        };
       },
       triggerError: params => {
         const query = getQuery(params);
@@ -184,7 +568,16 @@ function createReactQuerySyncAdapter(queryClient) {
         }
       },
       clearQueryCache: () => {
+        // Same trap as `remove`, across every screen at once. See its note.
+        const watched = queryClient.getQueryCache().getAll().filter(q => q.getObserversCount() > 0).length;
         queryClient.getQueryCache().clear();
+        return {
+          ok: true,
+          cleared: true,
+          ...(watched ? {
+            note: `Cleared — but ${watched} quer${watched === 1 ? "y is" : "ies are"} still being watched by a screen, and React Query leaves those screens rendering their LAST value until something refetches. The cache is empty; the app on screen is not. Use \`reset\` on a query when you want its screen to reload.`
+          } : {})
+        };
       },
       clearMutationCache: () => {
         queryClient.getMutationCache().clear();

package/lib/module/react-query/sync/reactQuerySyncAdapter.js

@@ -13,15 +13,128 @@
  * v2: oversized / unserializable query (and mutation) data is replaced with
  * on-device markers. Dashboards fetch real data via `getQueryData`.
  */
+import { expandKeyedArrays, patchFromPath, readPath, refusalText, shapeSummary, suggestedPatch, typedEditViolations, unshapedLists } from "@buoy-gg/shared-ui";
 import { onlineManager } from "@tanstack/react-query";
 import { capQueryDetail, dehydrateQueryClient } from "./dehydrate";
 import { getQueryStatusLabel } from "../utils/getQueryStatusLabel";
+
+/**
+ * Does this patch write into the list at `path`? Only then is an
+ * unchecked-shape warning about that list worth saying — a patch that changes
+ * `promoCode` should not be told about an empty `results`. Mirrors the same
+ * helper in the zustand adapter, which has warned about this since it shipped.
+ */
+function touchesList(patch, path) {
+  let cur = patch;
+  for (const seg of path.split(".")) {
+    if (!cur || typeof cur !== "object" || Array.isArray(cur)) return false;
+    if (!(seg in cur)) return false;
+    cur = cur[seg];
+  }
+  // An empty list stays empty; there is no new item to be unsure about.
+  return Array.isArray(cur) ? cur.length > 0 : !!cur && typeof cur === "object";
+}
+const isPlainObject = v => !!v && typeof v === "object" && !Array.isArray(v);
+/** The shape category the screen depends on: array vs object vs the rest. */
+function shapeKind(v) {
+  if (Array.isArray(v)) return "array";
+  if (v === null) return "null";
+  if (typeof v === "object") return "object";
+  return typeof v;
+}
+
+/**
+ * Objects merge key by key; arrays and primitives are replaced. Two dangers a
+ * remote caller (an LLM most of all) hits are collected instead of silently
+ * written:
+ *
+ * - `shrunk`: a non-empty array shorter than the one it replaces — "change
+ *   item 0" sent as only item 0, dropping the rest.
+ * - `breaks`: a field whose SHAPE changes — an array or object overwritten by
+ *   null or a primitive. This is the crash we actually shipped: a model set
+ *   the siblings it wasn't changing (`sizes:null, store:null`) thinking it had
+ *   to name them, and the screen's `sizes.map(s => s.multiplier)` threw. Merge
+ *   KEEPS untouched fields, so nulling them is never necessary and never safe.
+ *
+ * The handler refuses either unless forced. An empty array (explicit clear)
+ * and null→value / value→value-of-same-kind are fine.
+ */
+function deepMerge(base, patch, path = "", issues = {
+  shrunk: [],
+  breaks: []
+}) {
+  if (Array.isArray(base) && Array.isArray(patch)) {
+    if (patch.length > 0 && patch.length < base.length) {
+      issues.shrunk.push({
+        path: path || "(root)",
+        have: base.length,
+        sent: patch.length
+      });
+    }
+    return patch;
+  }
+  if (!isPlainObject(base) || !isPlainObject(patch)) return patch;
+  const out = {
+    ...base
+  };
+  for (const [k, v] of Object.entries(patch)) {
+    const p = path ? `${path}.${k}` : k;
+    if (k in base) {
+      const from = shapeKind(base[k]);
+      const to = shapeKind(v);
+      // A populated array/object being replaced by null or a primitive breaks
+      // the shape the screen renders. (object→object and array→array recurse
+      // or replace normally; null/primitive→anything is a real value change.)
+      if ((from === "array" || from === "object") && from !== to) {
+        issues.breaks.push({
+          path: p,
+          from,
+          to
+        });
+      }
+      out[k] = deepMerge(base[k], v, p, issues);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+/** Parse a loose, non-hash key spelling into comparable string parts, or null. */
+function looseKeyParts(raw) {
+  const trimmed = raw.trim();
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) {
+      return parsed.map(k => typeof k === "object" && k !== null ? JSON.stringify(k) : String(k));
+    }
+  } catch {
+    /* not JSON — fall through to comma splitting */
+  }
+  if (trimmed.includes(",") && !trimmed.startsWith("[")) {
+    return trimmed.split(",").map(s => s.trim().replace(/^["']|["']$/g, ""));
+  }
+  return null;
+}
 export function createReactQuerySyncAdapter(queryClient) {
   const getQuery = params => {
     const {
       queryHash
     } = params;
-    const query = queryClient.getQueryCache().get(queryHash);
+    const cache = queryClient.getQueryCache();
+    let query = queryHash ? cache.get(queryHash) : undefined;
+    // Tolerate a key that is not an exact hash. Models routinely send a
+    // comma-joined key ("pokemon-detail,mewtwo,fetch") or a JSON array where a
+    // hash is wanted; resolve it against the live cache by comparing each
+    // query's key parts, so one malformed hash does not cost a turn.
+    if (!query && typeof queryHash === "string") {
+      const wanted = looseKeyParts(queryHash);
+      if (wanted) {
+        query = cache.getAll().find(q => {
+          const parts = q.queryKey.map(k => typeof k === "object" ? JSON.stringify(k) : String(k));
+          return parts.length === wanted.length && parts.every((p, i) => p === wanted[i]);
+        });
+      }
+    }
     if (!query) {
       throw new Error(`Query with hash "${queryHash}" not found`);
     }
@@ -51,7 +164,8 @@ export function createReactQuerySyncAdapter(queryClient) {
        */
       getQueryData: params => {
         const {
-          queryHash
+          queryHash,
+          path
         } = params ?? {};
         if (!queryHash) return {
           found: false,
@@ -62,9 +176,55 @@ export function createReactQuerySyncAdapter(queryClient) {
           found: false,
           reason: "unknown queryHash"
         };
+        if (path) {
+          const at = readPath(query.state.data, path);
+          if (!at.ok) return {
+            found: false,
+            reason: at.error
+          };
+          return {
+            found: true,
+            queryHash,
+            path,
+            shape: shapeSummary(at.value),
+            data: at.value
+          };
+        }
+        // Before the data, not after: a long payload is sliced at the engine's
+        // 24,000-character cap, and the shape is what a caller needs in order to
+        // send a correctly NESTED edit back. Ten of eleven measured `query`
+        // write failures were one level too shallow — `{name}` for a payload
+        // that is `{item: {name}}` — and the sketch is where that is visible in
+        // one line even when the data is not.
+        // A query with no data is not the same as a query holding nothing, and
+        // the two used to be indistinguishable: an errored query, a disabled
+        // one and an empty one all came back as a bare `{found:true}`. A reader
+        // — an LLM most of all — then reports "the query is empty" when the
+        // truth is "it failed with X". `listQueries` has always known; this is
+        // the call where anyone actually asks.
+        if (query.state.data === undefined) {
+          const status = query.state.status;
+          const err = query.state.error;
+          return {
+            found: true,
+            queryHash,
+            hasData: false,
+            status,
+            fetchStatus: query.state.fetchStatus,
+            ...(err ? {
+              error: err instanceof Error ? err.message : String(err)
+            } : {}),
+            reason: status === "error" ? "This query has no data because it FAILED. Report the error, not an empty result." : query.state.fetchStatus === "fetching" ? "No data yet — this query is still fetching." : "This query has never resolved (it may be disabled, or never enabled). It is not empty — it has nothing."
+          };
+        }
+        const shape = shapeSummary(query.state.data);
         return {
           found: true,
           queryHash,
+          hasData: true,
+          ...(shape ? {
+            shape
+          } : {}),
           data: capQueryDetail(query.state.data)
         };
       },
@@ -83,7 +243,17 @@ export function createReactQuerySyncAdapter(queryClient) {
         } = params ?? {};
         const all = queryClient.getQueryCache().getAll();
         const filtered = staleOnly ? all.filter(q => q.isStale()) : all;
-        const sorted = [...filtered].sort((a, b) => (b.state.dataUpdatedAt ?? 0) - (a.state.dataUpdatedAt ?? 0));
+        // MOUNTED FIRST, then most-recently-updated. `limit` exists to keep
+        // this cheap for a remote reader, and sorting by recency alone made it
+        // lossy in the one way that matters: a detail screen's query settles
+        // once and is then older than every background refetch, so on a cache
+        // with more live queries than the limit the query the user is actually
+        // LOOKING AT was the first thing dropped. Nothing downstream can undo
+        // that — a caller re-sorting the response can only reorder survivors.
+        const sorted = [...filtered].sort((a, b) => {
+          const mounted = Number(b.getObserversCount() > 0) - Number(a.getObserversCount() > 0);
+          return mounted !== 0 ? mounted : (b.state.dataUpdatedAt ?? 0) - (a.state.dataUpdatedAt ?? 0);
+        });
         const capped = typeof limit === "number" && limit > 0 ? sorted.slice(0, limit) : sorted;
         const queries = capped.map(q => {
           const err = q.state.error;
@@ -98,6 +268,12 @@ export function createReactQuerySyncAdapter(queryClient) {
             error: err ? err.message ?? String(err) : undefined,
             ...(includeData ? {
               data: q.state.data
+            } : {}),
+            // The compact view exists so a caller can survey the cache without
+            // pulling payloads; the shape is the part of a payload it actually
+            // needs to write a correct edit, and it costs one line.
+            ...(shapeSummary(q.state.data) ? {
+              shape: shapeSummary(q.state.data)
             } : {})
           };
         });
@@ -115,17 +291,226 @@ export function createReactQuerySyncAdapter(queryClient) {
       },
       invalidate: params => queryClient.invalidateQueries(getQuery(params)),
       reset: params => queryClient.resetQueries(getQuery(params)),
+      /**
+       * Dropping a query does NOT re-drive the screen watching it.
+       *
+       * React Query removes the cache entry; a mounted observer keeps its last
+       * result in local state until something makes it fetch again. So the app
+       * carries on rendering a value that now exists nowhere — including one
+       * the agent itself wrote a moment earlier. Measured on device: `remove`
+       * on the live menu query left the storefront showing a single fabricated
+       * item, with no skeleton, no refetch and no error, while the cache held
+       * no menu at all. Returning a bare null let that be reported as "done".
+       *
+       * `reset` is the action that actually re-drives an observed query, so
+       * the note names it rather than leaving the caller to find out from a
+       * screen that looks fine.
+       */
       remove: params => {
-        queryClient.removeQueries(getQuery(params));
+        const target = getQuery(params);
+        const watched = queryClient.getQueryCache().findAll(target).some(q => q.getObserversCount() > 0);
+        queryClient.removeQueries(target);
+        return {
+          ok: true,
+          ...(watched ? {
+            note: "Removed — but a screen is still watching this query, and React Query leaves that screen rendering its LAST value (including anything written into the cache before this) until something refetches. Nothing on screen will change on its own. Use `reset` instead when you want the screen to go back to loading and fetch again."
+          } : {})
+        };
       },
       setQueryData: params => {
         const {
-          queryKey,
-          data
+          data,
+          merge,
+          force,
+          path,
+          value
         } = params;
+        /**
+         * Address the query the way EVERY OTHER action here does.
+         *
+         * This action took `queryKey` and silently ignored `queryHash` — while
+         * `listQueries` hands out `queryHash` and getQueryData / invalidate /
+         * refetch / reset / remove / triggerError / triggerLoading all take it.
+         * A caller that used the hash got `getQueryData(undefined)` →
+         * `undefined`, and so a refusal about "(root): undefined → object"
+         * that named the wrong problem. With `force:true` — which that refusal
+         * literally suggests — it wrote under an undefined key and still
+         * returned `{ok:true, changedKeys:[…]}`: a success report for a write
+         * that touched nothing, which is the one outcome this codebase refuses
+         * to ship. Ask Buoy itself was covered because the ENGINE aliases hash
+         * → key before dispatch; the MCP server, the desktop dashboard and
+         * Scenarios all call straight in here and were not.
+         */
+        const {
+          queryKey: rawKey,
+          queryHash
+        } = params;
+        let queryKey = rawKey;
+        if (queryKey === undefined && typeof queryHash === "string") {
+          const found = queryClient.getQueryCache().get(queryHash);
+          if (!found) {
+            return {
+              ok: false,
+              error: `Refused: no query with hash ${queryHash} is in the cache. Read listQueries for the current hashes — a query that has been removed or whose key includes changing params (a search term, a cart payload) will not match an older hash.`
+            };
+          }
+          queryKey = found.queryKey;
+        }
+        if (queryKey === undefined) {
+          return {
+            ok: false,
+            error: `Refused: no query was named. Send \`queryKey\` (the array from listQueries) or \`queryHash\` (its string form).`
+          };
+        }
+        const current = queryClient.getQueryData(queryKey);
+        /**
+         * There is nothing to merge INTO.
+         *
+         * The typed-edit guard answers this with "`(root)`: undefined →
+         * object", which describes the symptom and not the cause — and it is
+         * the same sentence a caller used to get when the query simply could
+         * not be found, so it taught nothing. A query with no data is usually
+         * one that FAILED or was never enabled, and that is what the caller
+         * needs to hear.
+         */
+        const existing = queryClient.getQueryCache().find({
+          queryKey,
+          exact: true
+        });
+        // Only when the query is THERE and holds nothing. A key that is not in
+        // the cache at all is a deliberate seed — `setQueryData(["new"], …)`
+        // creates the entry, and that has always worked.
+        if (current === undefined && existing && (data !== undefined || path !== undefined)) {
+          const q = existing;
+          const status = q?.state.status;
+          const why = status === "error" ? `it FAILED${q?.state.error ? ` (${q.state.error instanceof Error ? q.state.error.message : String(q.state.error)})` : ""}` : status === "pending" ? "it has never resolved (it may be disabled, or still loading)" : "it holds no data";
+          return {
+            ok: false,
+            error: `Refused: this query has no data to edit — ${why}. There is nothing to merge into. Fix the cause first (restoreError, or let it fetch), or send force:true with the COMPLETE value if you mean to seed the cache from nothing.`,
+            status
+          };
+        }
+        // `path` is sugar over a merge, resolved against the data as it is now.
+        // It only ever produces a patch; everything below — the keyed expansion,
+        // the typed-edit guard, the receipt — then runs unchanged, so the guard
+        // stays the single place that decides what a write may do.
+        // `data` stopped being schema-required when `path` became an
+        // alternative, so the handler has to reject NEITHER — the same hole that
+        // let a bare `setState` fall through to a whole-store replace. Here it
+        // would write `undefined` over a cached value.
+        if (data === undefined && path === undefined) {
+          return {
+            ok: false,
+            error: `Refused: no change was described. Send \`data\` (with merge:true for a partial edit), or \`path\` and \`value\` to set one value.`
+          };
+        }
+        let patch = data;
+        if (path !== undefined) {
+          if (value === undefined) {
+            return {
+              ok: false,
+              error: `Refused: sent \`path\` without \`value\`. Say what to set "${path}" to; if you mean to clear it, send value:null and the field must already be nullable.`
+            };
+          }
+          const built = patchFromPath(current, path, value);
+          if (!built.ok) return {
+            ok: false,
+            error: `Refused: ${built.error}`
+          };
+          patch = built.patch;
+        }
+        if (merge || path !== undefined) {
+          // Address list items by their own id instead of resending the list:
+          //   {"results": {"pikachu": {"name": "test123"}}}
+          // Expanded BEFORE the guard below, so the typed-edit rule still holds
+          // over the result. This is the only form that works when the read was
+          // truncated — and a capped read is the normal case here, not the edge
+          // one. See packages/shared/src/sync/keyedArrays.ts for the measurement.
+          const expandedKeyed = force ? {
+            patch,
+            notes: [],
+            error: undefined
+          } : expandKeyedArrays(current, patch);
+          // An id that contradicts its own address is refused HERE, where we
+          // still know both halves; the typed-edit guard downstream would only
+          // see the item we picked and could not name the ambiguity.
+          if (expandedKeyed.error) {
+            return {
+              ok: false,
+              error: `Refused: ${expandedKeyed.error}`
+            };
+          }
+          const effective = expandedKeyed.patch;
+          // Edit like the devtools value editor: only same-type changes to
+          // fields that already exist. One rule replaces every ad-hoc guard —
+          // no new keys, no type changes, no null-ing a rendered array/object,
+          // no resizing a list. This is what makes a crash structurally
+          // impossible. `force` drops to a raw write for the rare real case.
+          if (!force) {
+            const violations = typedEditViolations(current, effective, {
+              noun: "data"
+            });
+            if (violations.length > 0) {
+              const suggestion = suggestedPatch(effective, violations);
+              return {
+                ok: false,
+                error: refusalText(violations, "data", suggestion),
+                violations,
+                ...(suggestion ? {
+                  suggestedData: suggestion
+                } : {})
+              };
+            }
+          }
+          const next = deepMerge(current, effective);
+          // A list that was EMPTY had no item shape for anything to check the
+          // new item against — not the guard above, not the reader, not the
+          // app. The zustand tool has always said so; this one stayed silent
+          // while the system prompt told the model the note always arrives, so
+          // a write of an invented shape into an empty list came back a clean
+          // success and got reported as one.
+          const unchecked = unshapedLists(current).filter(p => touchesList(effective, p));
+          queryClient.setQueryData(queryKey, next, {
+            updatedAt: Date.now()
+          });
+          return {
+            ok: true,
+            mode: "merge",
+            ...(path !== undefined ? {
+              path
+            } : {}),
+            changedKeys: isPlainObject(effective) ? Object.keys(effective) : undefined,
+            ...(expandedKeyed.notes.length ? {
+              keyed: expandedKeyed.notes
+            } : {}),
+            ...(unchecked.length ? {
+              unchecked: unchecked.map(p => `\`${p}\` was empty, so nothing in the app knows what its items look like and the shape of what you added was NOT checked. If the screen renders a field you left out, it will render undefined — read the query back and compare against how the screen uses it.`)
+            } : {})
+          };
+        }
+        // THE GUARD. A remote caller — an LLM most of all — reads the cached
+        // value through a wire that truncates big payloads, edits one field,
+        // and writes the torn object back. The screen then renders
+        // `data.stats.map` over a field that no longer exists and the app
+        // dies. If the replacement silently drops top-level keys the cache
+        // has, that is almost never intended, so refuse and name the fix.
+        if (!force && isPlainObject(current) && isPlainObject(data)) {
+          const missing = Object.keys(current).filter(k => !(k in data));
+          if (missing.length > 0) {
+            return {
+              ok: false,
+              error: `Refused: the new value drops ${missing.length} top-level field(s) the cached value has (${missing.slice(0, 8).join(", ")}${missing.length > 8 ? ", …" : ""}). A screen rendering those fields would crash. To change some fields, send merge:true with ONLY the fields that change. To really replace the whole value, send force:true.`,
+              missingKeys: missing
+            };
+          }
+        }
         queryClient.setQueryData(queryKey, data, {
           updatedAt: Date.now()
         });
+        return {
+          ok: true,
+          mode: "replace"
+        };
       },
       triggerError: params => {
         const query = getQuery(params);
@@ -179,7 +564,16 @@ export function createReactQuerySyncAdapter(queryClient) {
         }
       },
       clearQueryCache: () => {
+        // Same trap as `remove`, across every screen at once. See its note.
+        const watched = queryClient.getQueryCache().getAll().filter(q => q.getObserversCount() > 0).length;
         queryClient.getQueryCache().clear();
+        return {
+          ok: true,
+          cleared: true,
+          ...(watched ? {
+            note: `Cleared — but ${watched} quer${watched === 1 ? "y is" : "ies are"} still being watched by a screen, and React Query leaves those screens rendering their LAST value until something refetches. The cache is empty; the app on screen is not. Use \`reset\` on a query when you want its screen to reload.`
+          } : {})
+        };
       },
       clearMutationCache: () => {
         queryClient.getMutationCache().clear();

package/lib/typescript/react-query/sync/reactQuerySyncAdapter.d.ts

@@ -1,16 +1,3 @@
-/**
- * Sync adapter for the React Query tool, consumed by @buoy-gg/external-sync's
- * `useExternalSync` (structurally matches its ToolSyncAdapter interface so
- * this package doesn't need a dependency on it).
- *
- * Action handlers are ported from buoy-desktop's react-query-external-sync
- * (useSyncQueries.ts) so the dashboard keeps identical behavior, including
- * the trigger/restore loading and error simulations used by the TanStack
- * devtools UI.
- *
- * v2: oversized / unserializable query (and mutation) data is replaced with
- * on-device markers. Dashboards fetch real data via `getQueryData`.
- */
 import { type QueryClient } from "@tanstack/react-query";
 export declare function createReactQuerySyncAdapter(queryClient: QueryClient): {
     version: number;
@@ -29,12 +16,41 @@ export declare function createReactQuerySyncAdapter(queryClient: QueryClient): {
             found: false;
             reason: string;
             queryHash?: undefined;
+            path?: undefined;
+            shape?: undefined;
             data?: undefined;
         } | {
             found: true;
             queryHash: string;
+            path: string;
+            shape: {
+                shape: string;
+                lists?: import("@buoy-gg/shared-ui").ListShape[];
+            } | undefined;
             data: unknown;
             reason?: undefined;
+        } | {
+            reason: string;
+            error?: string | undefined;
+            found: true;
+            queryHash: string;
+            hasData: false;
+            status: import("@tanstack/query-core").QueryStatus;
+            fetchStatus: import("@tanstack/query-core").FetchStatus;
+            path?: undefined;
+            shape?: undefined;
+            data?: undefined;
+        } | {
+            data: unknown;
+            shape?: {
+                shape: string;
+                lists?: import("@buoy-gg/shared-ui").ListShape[];
+            } | undefined;
+            found: true;
+            queryHash: string;
+            hasData: true;
+            reason?: undefined;
+            path?: undefined;
         };
         /**
          * Compact, token-bounded cache reader for a remote driver (MCP/LLM):
@@ -45,6 +61,10 @@ export declare function createReactQuerySyncAdapter(queryClient: QueryClient): {
          */
         listQueries: (params?: unknown) => {
             queries: {
+                shape?: {
+                    shape: string;
+                    lists?: import("@buoy-gg/shared-ui").ListShape[];
+                } | undefined;
                 data?: unknown;
                 queryHash: string;
                 queryKey: readonly unknown[];
@@ -62,13 +82,77 @@ export declare function createReactQuerySyncAdapter(queryClient: QueryClient): {
         refetch: (params: unknown) => Promise<unknown>;
         invalidate: (params: unknown) => Promise<void>;
         reset: (params: unknown) => Promise<void>;
-        remove: (params: unknown) => void;
-        setQueryData: (params: unknown) => void;
+        /**
+         * Dropping a query does NOT re-drive the screen watching it.
+         *
+         * React Query removes the cache entry; a mounted observer keeps its last
+         * result in local state until something makes it fetch again. So the app
+         * carries on rendering a value that now exists nowhere — including one
+         * the agent itself wrote a moment earlier. Measured on device: `remove`
+         * on the live menu query left the storefront showing a single fabricated
+         * item, with no skeleton, no refetch and no error, while the cache held
+         * no menu at all. Returning a bare null let that be reported as "done".
+         *
+         * `reset` is the action that actually re-drives an observed query, so
+         * the note names it rather than leaving the caller to find out from a
+         * screen that looks fine.
+         */
+        remove: (params: unknown) => {
+            note?: string | undefined;
+            ok: true;
+        };
+        setQueryData: (params: unknown) => {
+            ok: boolean;
+            error: string;
+            status?: undefined;
+            missingKeys?: undefined;
+            mode?: undefined;
+        } | {
+            ok: boolean;
+            error: string;
+            status: import("@tanstack/query-core").QueryStatus;
+            missingKeys?: undefined;
+            mode?: undefined;
+        } | {
+            suggestedData?: Record<string, unknown> | undefined;
+            ok: boolean;
+            error: string;
+            violations: import("@buoy-gg/shared-ui").EditViolation[];
+            status?: undefined;
+            missingKeys?: undefined;
+            mode?: undefined;
+        } | {
+            unchecked?: string[] | undefined;
+            keyed?: string[] | undefined;
+            changedKeys: string[] | undefined;
+            path?: string | undefined;
+            ok: boolean;
+            mode: string;
+            error?: undefined;
+            status?: undefined;
+            missingKeys?: undefined;
+        } | {
+            ok: boolean;
+            error: string;
+            missingKeys: string[];
+            status?: undefined;
+            mode?: undefined;
+        } | {
+            ok: boolean;
+            mode: string;
+            error?: undefined;
+            status?: undefined;
+            missingKeys?: undefined;
+        };
         triggerError: (params: unknown) => void;
         restoreError: (params: unknown) => Promise<void>;
         triggerLoading: (params: unknown) => void;
         restoreLoading: (params: unknown) => void;
-        clearQueryCache: () => void;
+        clearQueryCache: () => {
+            note?: string | undefined;
+            ok: true;
+            cleared: true;
+        };
         clearMutationCache: () => void;
         setOnline: (params: unknown) => void;
     };

package/lib/typescript/react-query/sync/reactQuerySyncAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reactQuerySyncAdapter.d.ts","sourceRoot":"","sources":["../../../../src/react-query/sync/reactQuerySyncAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAiB,KAAK,WAAW,EAAiB,MAAM,uBAAuB,CAAC;AA0BvF,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,WAAW;;;;;;0BAgB1C,MAAM,IAAI;;QAa9B;;;;WAIG;+BACoB,OAAO;;;;;;;;;;;QAY9B;;;;;;WAMG;+BACoB,OAAO;;;;;;;;;;;;;;;;0BAkCZ,OAAO;6BAKJ,OAAO;wBAEZ,OAAO;yBACN,OAAO;+BAGD,OAAO;+BAIP,OAAO;+BAaP,OAAO;iCAEL,OAAO;iCAwBP,OAAO;;;4BA4BZ,OAAO;;EAMhC"}
+{"version":3,"file":"reactQuerySyncAdapter.d.ts","sourceRoot":"","sources":["../../../../src/react-query/sync/reactQuerySyncAdapter.ts"],"names":[],"mappings":"AAcA,OAAO,EAAiB,KAAK,WAAW,EAAiB,MAAM,uBAAuB,CAAC;AAsKvF,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,WAAW;;;;;;0BA8B1C,MAAM,IAAI;;QAa9B;;;;WAIG;+BACoB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAkD9B;;;;;;WAMG;+BACoB,OAAO;;;;;;;;;;;;;;;;;;;;0BAiDZ,OAAO;6BAKJ,OAAO;wBAEZ,OAAO;QACvB;;;;;;;;;;;;;;WAcG;yBACc,OAAO;;;;+BAgBD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAsKP,OAAO;+BAaP,OAAO;iCAEL,OAAO;iCAwBP,OAAO;;;;;;;4BA0CZ,OAAO;;EAMhC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buoy-gg/react-query",
-  "version": "7.0.35",
+  "version": "7.0.36",
   "description": "TanStack Query devtools inside your React Native app — cache inspection, refetch & invalidate, offline toggle. Part of Buoy devtools.",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -29,8 +29,8 @@
     "**/snapshotProvider.ts"
   ],
   "dependencies": {
-    "@buoy-gg/shared-ui": "^7.0.35",
-    "@buoy-gg/floating-tools-core": "^7.0.35"
+    "@buoy-gg/shared-ui": "^7.0.36",
+    "@buoy-gg/floating-tools-core": "^7.0.36"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",