@buoy-gg/shared-ui 7.0.35 → 7.0.36

package/lib/module/sync/keyedArrays.js

@@ -0,0 +1,204 @@
+"use strict";
+
+/**
+ * Id-addressed list edits — one implementation, shared by every adapter that
+ * takes a merge patch.
+ *
+ * WHY. Resending a whole array is correct only when the caller has SEEN the
+ * whole array, and reads are capped. Measured with a 20-item list truncated to
+ * 5 (`pnpm ai:array --truncate=5`): the whole-array form scored 0/9 across three
+ * models — two refused outright, and one silently sent back only the 5 items it
+ * had been shown, destroying the other 15. Addressed edits scored 9/9.
+ *
+ * It also makes mass deletion impossible BY OMISSION: an addressed edit can only
+ * remove ids it names. Sending a real array still replaces the list, which is
+ * how a caller deliberately empties one.
+ *
+ * This lives here rather than in one adapter because react-query, zustand and
+ * network all take merge patches, and a second copy of a data-destroying safety
+ * rule is a copy that drifts.
+ */
+const isPlainObject = v => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Fields we will treat as an item's stable identity, best first. */
+const ID_FIELDS = ["id", "lineId", "key", "uuid", "_id", "slug", "name"];
+
+/**
+ * The field that identifies items in this list, or undefined if there isn't one.
+ *
+ * Every item must carry it, and every value must be a distinct string/number —
+ * a duplicated id would make an addressed edit ambiguous, and silently picking
+ * the first match is exactly the kind of "helpful" guess that loses data.
+ */
+export function identityField(items) {
+  if (!items.length || !items.every(isPlainObject)) return undefined;
+  const first = items[0];
+  for (const f of ID_FIELDS) {
+    if (!(f in first)) continue;
+    const values = items.map(it => it[f]);
+    const usable = values.every(v => typeof v === "string" || typeof v === "number");
+    if (!usable) continue;
+    if (new Set(values.map(String)).size !== values.length) continue;
+    return f;
+  }
+  return undefined;
+}
+
+/**
+ * The identity an ADDED item should carry.
+ *
+ * `Object.entries` hands back STRING keys, so `{"9901": {id: 9901, …}}` was
+ * written as `{id: "9901"}` — the caller's own numeric id replaced by text, and
+ * then refused by the typed-edit guard as `[2].id: number → string`. The caller
+ * recovers by resending the WHOLE array, which is exactly the truncation-unsafe
+ * move this module exists to prevent. Measured on a live QA run: one added
+ * offer cost a refusal, a full-list retransmission and 35 seconds.
+ *
+ * So the id the caller WROTE wins. With no id in the body, the key is coerced
+ * to the type the existing items use, and only when the text round-trips
+ * exactly: "007" is not 7, and inventing that identity is worse than a refusal
+ * the caller can read.
+ */
+function identityForAdd(current, idField, key, edit) {
+  const supplied = edit[idField];
+  if (typeof supplied === "string" || typeof supplied === "number") {
+    // An item whose id disagrees with the address it was sent under is
+    // ambiguous — either could be the one the caller meant. Say so rather than
+    // silently picking one and writing an item nobody asked for.
+    if (String(supplied) !== key) {
+      return {
+        ok: false,
+        error: `The new item is addressed as \`${key}\` but carries \`${idField}\`: ${JSON.stringify(supplied)}. Use the same value for both — address it by the id it carries.`
+      };
+    }
+    return {
+      ok: true,
+      value: supplied
+    };
+  }
+  const numericList = current.every(it => typeof it[idField] === "number");
+  if (numericList && key.trim() !== "" && String(Number(key)) === key) {
+    return {
+      ok: true,
+      value: Number(key)
+    };
+  }
+  return {
+    ok: true,
+    value: key
+  };
+}
+
+/**
+ * Let a caller address list items by their own id instead of resending the list.
+ *
+ *   { lines: { "seed-1": { qty: 5 } } }   change one field of one item
+ *   { lines: { "seed-2": null } }         remove that item
+ *   { lines: { "new-1": { …all fields… } } }  append (id not already present)
+ *
+ * WHY THIS EXISTS. Resending the whole array is correct only when the caller has
+ * SEEN the whole array, and reads are capped — so on a long list the honest
+ * agents refuse and the careless ones send back only the items they were shown,
+ * silently destroying the rest. Measured: with a 20-item bag truncated to 5, the
+ * whole-array form scored 0/9 across three models and one of them deleted 15
+ * lines without a word. Addressed edits scored 9/9. (`pnpm ai:array`.)
+ *
+ * It also makes mass deletion impossible BY OMISSION: `lines: []` empties a bag,
+ * but a keyed edit can only remove ids it names.
+ *
+ * Returns the patch with keyed objects expanded into real arrays, so everything
+ * downstream — the typed-edit guard, the receipt, the store write — is unchanged
+ * and keeps all of its protections.
+ */
+export function expandKeyedArrays(current, patch, path = "", notes = []) {
+  if (Array.isArray(current) && isPlainObject(patch)) {
+    const idField = identityField(current);
+    if (!idField) {
+      // No stable identity: leave it alone and let the normal guard report the
+      // object-vs-array type change, which says something truer than we could.
+      return {
+        patch,
+        notes
+      };
+    }
+    const byId = new Map(current.map(it => [String(it[idField]), it]));
+    const next = current.slice();
+    let removed = 0;
+    let changed = 0;
+    let added = 0;
+    for (const [id, edit] of Object.entries(patch)) {
+      const i = next.findIndex(it => String(it[idField]) === id);
+      if (edit === null) {
+        if (i === -1) return {
+          patch,
+          notes
+        };
+        next.splice(i, 1);
+        removed++;
+      } else if (i === -1) {
+        if (!isPlainObject(edit)) return {
+          patch,
+          notes
+        };
+        const identity = identityForAdd(current, idField, id, edit);
+        if (!identity.ok) {
+          return {
+            patch,
+            notes,
+            error: identity.error
+          };
+        }
+        next.push({
+          ...edit,
+          [idField]: identity.value
+        });
+        added++;
+      } else {
+        const merged = expandKeyedArrays(byId.get(id), edit, `${path}[${id}]`, notes);
+        if (merged.error) return {
+          patch,
+          notes,
+          error: merged.error
+        };
+        const base = next[i];
+        next[i] = isPlainObject(base) && isPlainObject(merged.patch) ? {
+          ...base,
+          ...merged.patch
+        } : merged.patch;
+        changed++;
+      }
+    }
+    notes.push(`${path || "(root)"}: addressed by \`${idField}\` — ${changed} changed, ${added} added, ${removed} removed, ${next.length} item(s) remain`);
+    return {
+      patch: next,
+      notes
+    };
+  }
+  if (isPlainObject(current) && isPlainObject(patch)) {
+    const outPatch = {};
+    for (const [k, v] of Object.entries(patch)) {
+      const p = path ? `${path}.${k}` : k;
+      if (!(k in current)) {
+        outPatch[k] = v;
+        continue;
+      }
+      const inner = expandKeyedArrays(current[k], v, p, notes);
+      // A refusal deep in the tree is the whole patch's refusal: writing the
+      // rest of it would apply half of what the caller asked for.
+      if (inner.error) return {
+        patch,
+        notes,
+        error: inner.error
+      };
+      outPatch[k] = inner.patch;
+    }
+    return {
+      patch: outPatch,
+      notes
+    };
+  }
+  return {
+    patch,
+    notes
+  };
+}

package/lib/module/sync/toolAttention.test.js

@@ -0,0 +1,50 @@
+"use strict";
+
+/**
+ * The attention badge seam: a tool says "I need you" and the rail hears it.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { getToolAttention, setToolAttention, subscribeToolAttention } from "./toolUiBridge.js";
+describe("toolAttention", () => {
+  it("stores, replaces and clears a badge, notifying once per change", () => {
+    const fn = vi.fn();
+    const off = subscribeToolAttention(fn);
+    setToolAttention("ask-buoy", {
+      kind: "needsInput",
+      label: "Needs your approval"
+    });
+    expect(getToolAttention("ask-buoy")).toEqual({
+      kind: "needsInput",
+      label: "Needs your approval"
+    });
+    expect(fn).toHaveBeenCalledTimes(1);
+    // Same value again is not a change.
+    setToolAttention("ask-buoy", {
+      kind: "needsInput",
+      label: "Needs your approval"
+    });
+    expect(fn).toHaveBeenCalledTimes(1);
+    setToolAttention("ask-buoy", {
+      kind: "done",
+      label: "Finished"
+    });
+    expect(fn).toHaveBeenCalledTimes(2);
+    setToolAttention("ask-buoy", null);
+    expect(getToolAttention("ask-buoy")).toBeNull();
+    expect(fn).toHaveBeenCalledTimes(3);
+    // Clearing what is already clear is silent.
+    setToolAttention("ask-buoy", null);
+    expect(fn).toHaveBeenCalledTimes(3);
+    off();
+  });
+  it("keeps tools apart", () => {
+    setToolAttention("a", {
+      kind: "failed",
+      label: "x"
+    });
+    setToolAttention("b", null);
+    expect(getToolAttention("a")?.kind).toBe("failed");
+    expect(getToolAttention("b")).toBeNull();
+    setToolAttention("a", null);
+  });
+});

package/lib/module/sync/toolUiBridge.js

@@ -65,4 +65,59 @@ export function openBuoyTool(toolId) {
 /** True when some host is listening — for deciding whether to offer the button. */
 export function canOpenBuoyTools() {
   return openers().size > 0;
+}
+
+// ─── Attention ───────────────────────────────────────────────────────────────
+
+/**
+ * "This tool needs you" — shown as a badge on its chip in the minimized rail.
+ *
+ * The case: Ask Buoy is minimized so a tester can watch the app, and the
+ * agent hits a step that needs a tap. Nobody can see the card. The sheet used
+ * to fail safe by DECLINING the change and ending the turn — which made
+ * minimize mean "stop", the opposite of what it is for. Now the approval
+ * holds, the chip gets a badge, and tapping the chip (the existing restore
+ * path) brings the card back. Same seam shape as the opener above: the rail
+ * lives inside the host, the tool cannot import the host, so it publishes
+ * through a global.
+ *
+ * `done` and `failed` cover the other thing a hidden tool cannot say — that
+ * the work you minimized it to wait for has finished.
+ */
+
+const ATTENTION_KEY = "__buoyToolAttention";
+function attention() {
+  const g = globalThis;
+  if (!g[ATTENTION_KEY]) g[ATTENTION_KEY] = {
+    byTool: new Map(),
+    listeners: new Set()
+  };
+  return g[ATTENTION_KEY];
+}
+
+/** Set, replace or (with null) clear a tool's badge. No-op when nothing changed. */
+export function setToolAttention(toolId, next) {
+  const store = attention();
+  const prev = store.byTool.get(toolId) ?? null;
+  if (prev === next || prev && next && prev.kind === next.kind && prev.label === next.label) return;
+  if (next) store.byTool.set(toolId, next);else store.byTool.delete(toolId);
+  for (const fn of store.listeners) {
+    try {
+      fn();
+    } catch {
+      // A throwing subscriber must not stop the others from hearing.
+    }
+  }
+}
+export function getToolAttention(toolId) {
+  return attention().byTool.get(toolId) ?? null;
+}
+
+/** For `useSyncExternalStore` in the rail. */
+export function subscribeToolAttention(fn) {
+  const store = attention();
+  store.listeners.add(fn);
+  return () => {
+    store.listeners.delete(fn);
+  };
 }

package/lib/module/sync/typedEdit.js

@@ -0,0 +1,220 @@
+"use strict";
+
+/**
+ * The typed-edit guard — ONE implementation, for every surface that takes a
+ * merge patch from a remote caller.
+ *
+ * The rule, which is the React Query devtools value-editor rule: you may change
+ * the VALUE of a field that already exists, to the same kind of thing. You may
+ * not add a field, change a field's type, or null a list or object the screen
+ * renders. A list may grow or shrink — carts are lists you add to — but every
+ * item in it must have the same fields as the items already there, because an
+ * item missing a field the others have is what crashes the list on render.
+ *
+ * WHY IT LIVES HERE. This existed twice, once in the zustand adapter and once in
+ * react-query, drifting slightly (one said "the ones already in the list", the
+ * other "the items"; only one had the did-you-mean hint). Jotai had NO copy at
+ * all, so `setAtom` accepted a string over a number or a one-item array over a
+ * fifty-item one with nothing to stop it. Three copies of a data-destroying
+ * safety rule is two more than anyone can keep in step — the same argument
+ * `keyedArrays.ts` makes about the expansion it owns.
+ *
+ * The one behavioural knob is `noun`: what to call the thing being edited in a
+ * refusal ("this store", "this data", "this atom"). Everything else is shared,
+ * deliberately — a rule that differs per surface is a rule nobody can state.
+ */
+
+const isPlainObject = v => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** The shape category the screen depends on: array vs object vs the rest. */
+export function shapeKind(v) {
+  if (Array.isArray(v)) return "array";
+  if (v === null) return "null";
+  if (typeof v === "object") return "object";
+  return typeof v;
+}
+const SCALARS = ["string", "number", "boolean"];
+
+/**
+ * Where a key actually lives in a nested value, as a dotted path — first match,
+ * breadth-first, capped so a huge payload cannot stall the walk.
+ *
+ * This is what turns "you put `name` at the top" into "`name` lives at
+ * `item.name`", which is the difference between a caller that gives up and one
+ * that fixes it. Ten of eleven measured `query` write failures were this exact
+ * mistake.
+ */
+export function findKeyPath(obj, key, maxNodes = 2000) {
+  const queue = [{
+    node: obj,
+    path: ""
+  }];
+  let seen = 0;
+  while (queue.length && seen < maxNodes) {
+    const {
+      node,
+      path
+    } = queue.shift();
+    seen++;
+    if (Array.isArray(node)) {
+      node.slice(0, 20).forEach((v, i) => queue.push({
+        node: v,
+        path: `${path}[${i}]`
+      }));
+    } else if (isPlainObject(node)) {
+      for (const [k, v] of Object.entries(node)) {
+        const p = path ? `${path}.${k}` : k;
+        if (k === key && path) return p; // path set => nested, not the top level
+        if (isPlainObject(v) || Array.isArray(v)) queue.push({
+          node: v,
+          path: p
+        });
+      }
+    }
+  }
+  return undefined;
+}
+/**
+ * Every way this patch would break the value it is merged into. Empty means the
+ * edit is safe to apply.
+ */
+export function typedEditViolations(current, patch, opts = {}, root = current, path = "", out = []) {
+  const noun = opts.noun ?? "data";
+  const here = path || "(root)";
+  if (Array.isArray(patch)) {
+    if (!Array.isArray(current)) {
+      out.push({
+        path: here,
+        kind: "type-change",
+        detail: `${shapeKind(current)} → array`
+      });
+      return out;
+    }
+    // Length may change — a cart is a list you add to and remove from — but each
+    // item must match the shape of the ones already there. The first item is the
+    // template; an added item missing a field the others have is what makes the
+    // list throw when it renders that field.
+    const template = current.length ? current[0] : undefined;
+    if (template !== undefined && (isPlainObject(template) || Array.isArray(template))) {
+      patch.forEach((el, i) => {
+        const ep = `${path}[${i}]`;
+        if (isPlainObject(template) && isPlainObject(el)) {
+          for (const k of Object.keys(template)) {
+            if (!(k in el)) {
+              out.push({
+                path: `${ep}.${k}`,
+                kind: "missing-key",
+                detail: `list items need \`${k}\` — the items already in the list have it`
+              });
+            }
+          }
+        }
+        typedEditViolations(template, el, opts, root, ep, out);
+      });
+    }
+    return out;
+  }
+  if (isPlainObject(patch)) {
+    if (!isPlainObject(current)) {
+      out.push({
+        path: here,
+        kind: "type-change",
+        detail: `${shapeKind(current)} → object`
+      });
+      return out;
+    }
+    for (const [k, v] of Object.entries(patch)) {
+      const p = path ? `${path}.${k}` : k;
+      if (!(k in current)) {
+        const elsewhere = findKeyPath(root, k);
+        out.push({
+          path: p,
+          kind: "add-key",
+          detail: elsewhere ? `no such field here — did you mean \`${elsewhere}\`?` : `no field named \`${k}\` exists in this ${noun}`,
+          ...(elsewhere ? {
+            movedTo: elsewhere
+          } : {})
+        });
+      } else {
+        typedEditViolations(current[k], v, opts, root, p, out);
+      }
+    }
+    return out;
+  }
+
+  // A leaf: the edit itself.
+  const ck = shapeKind(current);
+  const pk = shapeKind(patch);
+  // Filling an empty field and CLEARING one are the same kind of edit, and this
+  // guard used to allow only the first. That asymmetry had a cost: "take the
+  // promo off my bag" is `string → null`, the refusal named `force: true` as the
+  // only way through, and a model that anticipated it wrote the forced call
+  // pre-emptively — reaching for the one parameter that bypasses EVERY
+  // protection in order to do something completely ordinary. Measured on
+  // `cart/take-promo-off`: an S1 on an otherwise correct flow.
+  //
+  // Nulling a LIST or OBJECT the screen renders stays refused. That is the crash
+  // this guard exists for (`sizes.map` on null); a null scalar renders as empty.
+  const fillingNull = ck === "null" && SCALARS.includes(pk);
+  const clearingScalar = pk === "null" && SCALARS.includes(ck);
+  if (ck !== pk && !fillingNull && !clearingScalar) {
+    out.push({
+      path: here,
+      kind: "type-change",
+      detail: `${ck} → ${pk}`
+    });
+  }
+  return out;
+}
+
+/**
+ * The patch the caller should have sent, when every problem was a field written
+ * at the wrong DEPTH.
+ *
+ * The guard already worked out where each field really lives in order to say
+ * "did you mean `item.name`?", so it can rebuild the patch instead of leaving
+ * the caller to re-derive it from prose. Returns undefined unless EVERY
+ * violation is a relocatable add-key: a partial suggestion that silently drops
+ * the parts we could not fix would be worse than none, because the caller would
+ * send it, be refused again, and learn nothing.
+ */
+export function suggestedPatch(patch, violations) {
+  if (!violations.length || !violations.every(v => v.kind === "add-key" && v.movedTo)) return undefined;
+  const out = {};
+  for (const v of violations) {
+    const value = getAtDotted(patch, v.path);
+    if (value === undefined) return undefined;
+    // `movedTo` can name a list element (`results[0].name`); a merge patch
+    // cannot address one by index, and rewriting it to the id-addressed form
+    // needs the list itself. Leave those to the prose rather than suggest
+    // something that will not apply.
+    if (v.movedTo.includes("[")) return undefined;
+    let node = out;
+    const segs = v.movedTo.split(".");
+    segs.slice(0, -1).forEach(seg => {
+      node[seg] ??= {};
+      node = node[seg];
+    });
+    node[segs[segs.length - 1]] = value;
+  }
+  return out;
+}
+function getAtDotted(obj, path) {
+  let cur = obj;
+  for (const seg of path.split(".")) {
+    if (!isPlainObject(cur)) return undefined;
+    cur = cur[seg];
+  }
+  return cur;
+}
+
+/**
+ * The sentence a refusal ends with. Shared so every surface refuses in the same
+ * words — a caller that learns the rule on one tool should recognise it on the
+ * next.
+ */
+export function refusalText(violations, noun, suggestion) {
+  const listed = violations.slice(0, 6).map(v => `\`${v.path}\`: ${v.detail}`).join("; ");
+  const more = violations.length > 6 ? `; +${violations.length - 6} more` : "";
+  return `Refused: this isn't a same-type edit of existing fields (the rule the React Query devtools enforces). ${listed}${more}. ` + `You can only change the VALUE of a field that already exists, to the same type — you can't add fields, change a field's type, ` + `or null a list/object the screen renders. Clearing a scalar to null is fine. Send just the field(s) you're changing, nested to ` + `match the current shape of this ${noun}. Use force:true only to deliberately break that.` + (suggestion ? ` This is the same edit at the right depth — send it as the patch: ${JSON.stringify(suggestion)}` : "");
+}