@capacms/mcp 0.2.0

package/lib/bound.mjs

@@ -0,0 +1,546 @@
+/**
+ * bound.mjs — keep a tool's answer inside a character budget, say what was
+ * cut, and never hand back a cursor that skips what was cut.
+ *
+ * An agent's context is the resource these tools spend. A query that returns
+ * 200 entries with long bodies would otherwise fill it with one call, and a
+ * reply cut mid-string is JSON nobody can read. So the answer is shortened
+ * structurally, in this order, and each step only as far as it has to go:
+ *
+ *   1. The REST twin (`rest`) loses rows from its end while it takes more
+ *      than half the budget and more than 2,000 characters. A twin URL is
+ *      never clipped, and a `nodes(ids:)` read's lists every id, so without
+ *      this it would crowd the data out.
+ *   2. A content string longer than half the budget is clipped, longest
+ *      first, to the room the answer has, so one long value does not cut
+ *      away the entries beside it: a list loses an entry only when the
+ *      answer does not fit with every such string at 200 characters.
+ *   3. Content lists lose items from their end, the largest list first,
+ *      measured item by item, down to one item each. A string clipped
+ *      before then takes back the room the cut leaves, longest first.
+ *   4. Long content strings are clipped, longest first, each to the room
+ *      actually left, and never below 200 characters.
+ *   5. Metadata lists (`rest`, `deprecations`, and `errors` beside `data`)
+ *      lose items from their end: the REST twin of a root field whose data
+ *      is shown is worth more than one more entry, so it goes last. A tool
+ *      that names `rest` in `spare` (capa_graphql_query) has it left out
+ *      whole before the last entry of the data goes.
+ *
+ * Never clipped: an id, a cursor, a url, or anything in `pageInfo`, `rest`,
+ * `deprecations` or a response's `errors`. A clipped cursor is a cursor the
+ * API refuses, and a clipped error loses the fix it carries.
+ *
+ * A CUT CONNECTION STAYS PAGEABLE. Its `nodes` and `edges` are cut together,
+ * and its `pageInfo` is made true of what is kept. A page read forward
+ * (`first`, `after`) loses entries from its end: `hasNextPage` is true (the
+ * cut entries come next), and `endCursor` is the cursor of the last entry
+ * kept. A page read backward (`last`, `before`) loses them from its start,
+ * farthest from `before`: `hasPreviousPage` is true, and `startCursor` is the
+ * cursor of the first entry kept. The cursor is read from the entry's edge, or
+ * from `cursors` when the caller holds them. With no cursor to give, it is
+ * null and the cut says how to page on: the uncut page's cursor would skip
+ * every entry that was cut.
+ *
+ * Which lists are a connection's entries, which object is its pageInfo, and
+ * which way it pages is read from the document when the caller passes
+ * `connections` (lib/graphql/document.mjs), so `items: nodes` and `info:
+ * pageInfo` are repaired under the keys they answer with. Without them, a
+ * list under `nodes` or `edges` beside a `pageInfo` is a connection read
+ * forward. A connection with its own `resume` says how to page on in its own
+ * words: a REST page's is `limit`, not `first` (lib/rest-tools.mjs).
+ *
+ * Every cut list is recorded as `{ path, kept, total }`, a connection's edges
+ * and nodes each, and every clipped string as `{ path, kept, total }` in
+ * characters, so the agent knows the answer is partial and where, and a
+ * clipped string's `kept` is where to read on from. `maxChars` bounds the
+ * whole answer, notes included.
+ */
+
+export const DEFAULT_MAX_CHARS = 20_000;
+export const TRUNCATION_HINT = "Ask for fewer fields or a smaller first.";
+/** The shortest a string is clipped to, and the shortest that is ever clipped. */
+const MIN_STRING = 200;
+/** What a clipped string ends with. */
+const ELLIPSIS = "...";
+/** The REST twin keeps whole until it takes more than half the budget and more than this. */
+const REST_FLOOR = 2_000;
+const MAX_NOTES_LISTED = 10;
+/** Strings under these keys are never clipped: `next` and `prev` are REST's cursors. */
+const WHOLE_STRING_KEYS = new Set(["id", "cursor", "startCursor", "endCursor", "url", "next", "prev"]);
+/**
+ * Outside `data`, the parts of an answer that describe the request rather
+ * than hold content: `rest`, `deprecations`, and `errors` beside `data` (a
+ * GraphQL response's errors; an answer that is about errors, such as
+ * capa_explain_error's, holds them as its content).
+ */
+const isMetadata = (holder, name) => name === "rest" || name === "deprecations" || (name === "errors" && "data" in holder);
+const CONTENT = 0;
+const METADATA = 1;
+
+function size(value) {
+  return JSON.stringify(value)?.length ?? 0;
+}
+
+function join(path, key) {
+  if (typeof key === "number") return `${path || "$"}[${key}]`;
+  return path ? `${path}.${key}` : key;
+}
+
+/**
+ * Every list that may be shortened and every string that may be clipped in
+ * `value`, with where it is, what holds it, and its tier. `keep` names
+ * top-level keys left untouched; `whole` names lists that keep every item.
+ */
+function inventory(value, { keep, whole }) {
+  const lists = [];
+  const strings = [];
+  const visit = (node, path, holder, key, at) => {
+    if (Array.isArray(node)) {
+      if (!at.frozen && !whole.has(path || "$")) lists.push({ path: path || "$", array: node, holder, key, tier: at.tier });
+      node.forEach((item, i) => visit(item, join(path, i), node, i, at));
+    } else if (node && typeof node === "object") {
+      for (const [name, inner] of Object.entries(node)) {
+        const inData = at.inData || name === "data";
+        visit(inner, join(path, name), node, name, {
+          frozen: at.frozen || (path === "" && keep.has(name)),
+          inData,
+          tier: at.tier === METADATA || (!at.inData && isMetadata(node, name)) ? METADATA : CONTENT,
+          wholeStrings: at.wholeStrings || name === "pageInfo" || (!at.inData && isMetadata(node, name)),
+        });
+      }
+    } else if (typeof node === "string" && node.length > MIN_STRING && !at.frozen && !at.wholeStrings && !WHOLE_STRING_KEYS.has(key)) {
+      strings.push({ path, holder, key, tier: at.tier });
+    }
+  };
+  visit(value, "", null, null, { frozen: false, inData: false, tier: CONTENT, wholeStrings: false });
+  return { lists, strings };
+}
+
+/** A connection read by its literal field names, forward: what an answer with no document is read as. */
+const LITERAL_CONNECTION = {
+  nodes: ["nodes"],
+  edges: [{ key: "edges", cursor: ["cursor"] }],
+  pageInfo: [{ key: "pageInfo", fields: { hasNextPage: ["hasNextPage"], hasPreviousPage: [], startCursor: [], endCursor: ["endCursor"] } }],
+  backward: false,
+};
+
+/** Where the object holding `list` sits: `data.articles` for `data.articles.nodes`. */
+const holderPathOf = (list) => list.path.slice(0, list.path.length - String(list.key).length).replace(/\.$/, "");
+
+/** `data.articles.nodes[3].coauthors` as the document names it: `data.articles.nodes.coauthors`. */
+const shapeOf = (path) => path.replace(/\[\d+\]/g, "");
+
+/**
+ * The connection whose entries `list` is, `{ ...shape, holderPath }`, or null.
+ * With `connections` from the document, only a list the document reads as
+ * `nodes` or `edges` (under whatever key) is one.
+ */
+function connectionOf(list, connections) {
+  if (!list.holder || Array.isArray(list.holder)) return null;
+  const holderPath = holderPathOf(list);
+  const shape = connections ? connections[shapeOf(holderPath)] : LITERAL_CONNECTION;
+  if (!shape) return null;
+  const isEntries = shape.nodes.includes(list.key) || shape.edges.some((edge) => edge.key === list.key);
+  return isEntries ? { ...shape, holderPath } : null;
+}
+
+/** A connection's nodes and edges, which are cut together, each with its path; any other list alone. */
+function parallelOf(list, connection) {
+  if (!connection) return [{ path: list.path, array: list.array }];
+  return [...connection.nodes, ...connection.edges.map((edge) => edge.key)]
+    .filter((key) => Array.isArray(list.holder[key]))
+    .map((key) => ({ path: join(connection.holderPath, key), array: list.holder[key] }));
+}
+
+/**
+ * Drop items from `list`, and from the lists cut with it, until `excess`
+ * characters are freed or one item is left: from the end, or from the start
+ * when `fromStart` (a page read backward keeps the entries nearest `before`).
+ */
+function trim(list, parallel, excess, fromStart) {
+  let dropped = 0;
+  let freed = 0;
+  while (list.array.length - dropped > 1 && freed < excess) {
+    for (const items of parallel) {
+      const index = fromStart ? dropped : items.length - 1 - dropped;
+      if (index >= 0 && index < items.length) freed += size(items[index]) + 1;
+    }
+    dropped++;
+  }
+  for (const items of parallel) {
+    if (fromStart) items.splice(0, Math.min(dropped, items.length));
+    else items.length = Math.max(0, items.length - dropped);
+  }
+}
+
+/** The first string under any of `keys` in `holder`. */
+const readAny = (holder, keys) => keys.map((key) => holder?.[key]).find((value) => typeof value === "string");
+
+/**
+ * Make a cut connection's pageInfo true of what it kept: `total` entries were
+ * served and some were dropped. Returns how to page on when there is no cursor
+ * to give, else null.
+ */
+function repairPage(holder, connection, cursors, total) {
+  const entries = [...connection.nodes, ...connection.edges.map((edge) => edge.key)].map((key) => holder[key]).find(Array.isArray);
+  const kept = entries?.length ?? 0;
+  const backward = connection.backward;
+  const [moreKey, cursorKey] = backward ? ["hasPreviousPage", "startCursor"] : ["hasNextPage", "endCursor"];
+  // The cursor of the entry at the cut: the first kept going back, the last kept going on.
+  const edgeCursor = connection.edges
+    .map((edge) => {
+      const items = holder[edge.key];
+      if (!Array.isArray(items) || !items.length) return undefined;
+      return readAny(items[backward ? 0 : items.length - 1], edge.cursor);
+    })
+    .find((value) => typeof value === "string");
+  const held = cursors?.[backward ? total - kept : kept - 1];
+  const cursor = edgeCursor ?? (typeof held === "string" ? held : null);
+  let asked = false;
+  for (const { key, fields } of connection.pageInfo) {
+    const info = holder[key];
+    if (!info || typeof info !== "object" || Array.isArray(info)) continue;
+    for (const alias of fields[moreKey]) if (alias in info) info[alias] = true;
+    for (const alias of fields[cursorKey]) {
+      if (!(alias in info)) continue;
+      info[alias] = cursor;
+      asked = true;
+    }
+  }
+  if (!asked || cursor !== null) return null;
+  if (connection.resume) return connection.resume(kept);
+  return backward
+    ? `startCursor is null because entries were cut; the uncut page's would skip them. Run the query again with last: ${kept} and the same before for a cursor before the first entry shown, or select edges { cursor }.`
+    : `endCursor is null because entries were cut; the uncut page's would skip them. Run the query again with first: ${kept} for a cursor after the last entry shown, or select edges { cursor }.`;
+}
+
+const fits = (value, maxChars) => size(value) <= maxChars;
+
+/** The first `length` UTF-16 units of `text`, never ending inside a surrogate pair. */
+function prefix(text, length) {
+  const end = length > 0 && /[\uD800-\uDBFF]/.test(text[length - 1] ?? "") ? length - 1 : length;
+  return text.slice(0, end);
+}
+
+/** Where every object and array in `value` sits: each clipped string is named by where its holder ended up. */
+function pathsOf(value) {
+  const paths = new Map();
+  const visit = (node, path) => {
+    if (!node || typeof node !== "object") return;
+    paths.set(node, path);
+    if (Array.isArray(node)) node.forEach((item, i) => visit(item, join(path, i)));
+    else for (const [name, inner] of Object.entries(node)) visit(inner, join(path, name));
+  };
+  visit(value, "");
+  return paths;
+}
+
+/**
+ * `value` cut to fit `maxChars` when serialized (see the file comment for the
+ * order), the lists cut and the strings clipped. The input is not modified.
+ * Options: `keep` (top-level keys never touched), `whole` (lists that keep
+ * every item), `cursors` (a connection's cursors by its path, for a
+ * connection whose answer does not carry them), `connections` (the
+ * document's connections by path, from `connectionsOf`).
+ */
+export function boundValue(value, maxChars = DEFAULT_MAX_CHARS, { keep = new Set(), whole = new Set(), cursors = {}, connections = null } = {}) {
+  if (fits(value, maxChars)) return { value, truncated: [], clipped: [] };
+  const copy = structuredClone(value);
+  const scope = { keep, whole };
+  const cuts = new Map();
+  const cutConnections = new Map();
+  /** Each clipped string by its holder and key: the text it had, and how much of it is kept. */
+  const clips = new Map();
+  const half = Math.floor(maxChars / 2);
+
+  /** Leave out the REST twin's last rows while it takes more than half the budget and more than REST_FLOOR. */
+  const capRest = () => {
+    const rest = copy.rest;
+    const share = Math.max(REST_FLOOR, half);
+    if (!Array.isArray(rest) || keep.has("rest") || whole.has("rest") || size(rest) <= share) return;
+    const total = rest.length;
+    while (rest.length && size(rest) > share) rest.pop();
+    cuts.set("rest", { path: "rest", kept: rest.length, total });
+  };
+
+  const cutLists = (tier) => {
+    while (!fits(copy, maxChars)) {
+      const candidates = inventory(copy, scope).lists.filter((l) => l.tier === tier && l.array.length > 1);
+      if (!candidates.length) return;
+      const sized = candidates.map((list) => ({ list, chars: size(list.array) }));
+      const biggest = sized.reduce((a, b) => (b.chars > a.chars ? b : a)).list;
+      // A connection's edges and nodes are both shortened, so both are noted.
+      const connection = connectionOf(biggest, connections);
+      const parallel = parallelOf(biggest, connection);
+      const lengths = parallel.map(({ array }) => array.length);
+      const fromStart = connection?.backward === true;
+      trim(biggest, parallel.map((p) => p.array), size(copy) - maxChars, fromStart);
+      parallel.forEach(({ path, array }, i) => {
+        if (array.length >= lengths[i]) return;
+        const note = { path, kept: array.length, total: cuts.get(path)?.total ?? lengths[i] };
+        cuts.set(path, fromStart ? { ...note, cutFrom: "start" } : note);
+      });
+      if (connection) {
+        const known = cutConnections.get(connection.holderPath);
+        cutConnections.set(connection.holderPath, {
+          holder: biggest.holder,
+          connection,
+          paths: parallel.map((p) => p.path),
+          total: known?.total ?? Math.max(...lengths),
+        });
+      }
+    }
+  };
+  /** The text a string held before any clip, and the clip record for it. */
+  const clipOf = ({ holder, key }) => clips.get(holder)?.get(key);
+  /**
+   * Clip one string to the most of the text it first held that lets the
+   * answer fit, and never below `floor` characters. Measured as JSON, since
+   * escapes make a string longer than its characters.
+   */
+  const clip = (string, floor) => {
+    const current = string.holder[string.key];
+    const record = clipOf(string);
+    const text = record?.text ?? current;
+    const room = maxChars - (size(copy) - size(current));
+    const clipped = (length) => `${prefix(text, length)}${ELLIPSIS}`;
+    // The longest prefix that fits the room, found by bisection between the floor and what is kept now.
+    let low = floor;
+    let high = (record?.kept ?? text.length) - 1;
+    if (high < low) return;
+    while (low < high) {
+      const middle = Math.ceil((low + high) / 2);
+      if (size(clipped(middle)) <= room) low = middle;
+      else high = middle - 1;
+    }
+    const kept = prefix(text, low);
+    string.holder[string.key] = `${kept}${ELLIPSIS}`;
+    if (!clips.has(string.holder)) clips.set(string.holder, new Map());
+    clips.get(string.holder).set(string.key, { text, kept: kept.length });
+  };
+  /**
+   * Give each clipped string still in the answer back as much of its text as
+   * the room left holds, longest first: a list cut item by item can free
+   * more than the clip before it needed. A string that fits whole is no
+   * longer clipped.
+   */
+  const regrow = () => {
+    const where = pathsOf(copy);
+    const held = [...clips]
+      .filter(([holder]) => where.has(holder))
+      .flatMap(([holder, keys]) => [...keys].map(([key, record]) => ({ holder, key, record })))
+      .sort((a, b) => b.record.text.length - a.record.text.length);
+    for (const { holder, key, record } of held) {
+      const current = holder[key];
+      const room = maxChars - (size(copy) - size(current));
+      if (size(record.text) <= room) {
+        holder[key] = record.text;
+        clips.get(holder).delete(key);
+        continue;
+      }
+      const clipped = (length) => `${prefix(record.text, length)}${ELLIPSIS}`;
+      let low = record.kept;
+      let high = record.text.length - 1;
+      while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (size(clipped(middle)) <= room) low = middle;
+        else high = middle - 1;
+      }
+      if (low <= record.kept) continue;
+      const kept = prefix(record.text, low);
+      holder[key] = `${kept}${ELLIPSIS}`;
+      record.kept = kept.length;
+    }
+  };
+  /** Clip the strings of `tier` longer than `over`, longest first, none below `floor`, while the answer overruns. */
+  const clipStrings = (tier, over, floor) => {
+    if (fits(copy, maxChars)) return;
+    const long = inventory(copy, scope).strings.filter((s) => s.tier === tier && s.holder[s.key].length > over);
+    long.sort((a, b) => b.holder[b.key].length - a.holder[a.key].length);
+    for (const string of long) {
+      if (fits(copy, maxChars)) return;
+      clip(string, floor);
+    }
+  };
+
+  capRest();
+  clipStrings(CONTENT, Math.max(MIN_STRING, half), MIN_STRING);
+  cutLists(CONTENT);
+  regrow();
+  clipStrings(CONTENT, MIN_STRING, MIN_STRING);
+  cutLists(METADATA);
+  regrow();
+  clipStrings(METADATA, MIN_STRING, MIN_STRING);
+
+  // Cuts inside a list that was itself cut away are not worth reporting, and
+  // neither is a string clipped in an entry that was cut away after it.
+  const present = new Set(inventory(copy, { keep: new Set(), whole: new Set() }).lists.map((l) => l.path));
+  const truncated = [...cuts.values()].filter((c) => present.has(c.path));
+  const where = pathsOf(copy);
+  const clipped = [...clips]
+    .filter(([holder]) => where.has(holder))
+    .flatMap(([holder, keys]) => [...keys].map(([key, { text, kept }]) => ({ path: join(where.get(holder), key), kept, total: text.length })))
+    .sort((a, b) => b.total - a.total);
+  // One note per connection says how to page on: its nodes', else its edges'.
+  for (const [holderPath, { holder, connection, paths, total }] of cutConnections) {
+    const cut = truncated.find((c) => paths.includes(c.path));
+    const resume = cut && repairPage(holder, connection, cursors[holderPath], total);
+    if (resume) cut.resume = resume;
+  }
+  return { value: copy, truncated, clipped };
+}
+
+/** A count as the API writes one: 102,400. */
+const grouped = (n) => n.toLocaleString("en-US");
+
+/**
+ * The hint for a cut answer. For a tool that says how to read on (`readOn`)
+ * and a string clipped, it names the longest one, its size and what is
+ * shown, then how to read the rest: asking for fewer fields cannot help a
+ * value that is long. Otherwise `hint`.
+ */
+function hintFor(clipped, hint, readOn) {
+  const longest = clipped[0];
+  if (!longest || !readOn) return hint;
+  return `${longest.path} is ${grouped(longest.total)} characters, and the first ${grouped(longest.kept)} are shown. ${readOn(longest)}`;
+}
+
+/** `value` with the notes that say what was cut, and how to ask for less. */
+function withNotes(value, truncated, clipped, hint, readOn) {
+  if (!truncated.length && !clipped.length) return value;
+  const out = { ...value };
+  if (truncated.length) out.truncated = truncated.slice(0, MAX_NOTES_LISTED);
+  if (truncated.length > MAX_NOTES_LISTED) out.truncatedMore = truncated.length - MAX_NOTES_LISTED;
+  if (clipped.length) out.clipped = clipped.slice(0, MAX_NOTES_LISTED);
+  if (clipped.length > MAX_NOTES_LISTED) out.clippedMore = clipped.length - MAX_NOTES_LISTED;
+  out.hint = hintFor(clipped, hint, readOn);
+  return out;
+}
+
+/** Names in a note, at most `limit` of them, then how many more. */
+export function someNames(names, limit = 40) {
+  return names.length > limit ? `${names.slice(0, limit).join(", ")} and ${names.length - limit} more` : names.join(", ");
+}
+
+/** "a", "a and b", "a, b and c". */
+function listed(names) {
+  return names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}` : names.join("");
+}
+
+function without(value, key) {
+  const { [key]: _dropped, ...rest } = value;
+  return rest;
+}
+
+/**
+ * `fallback` when its kept parts overrun `maxChars` beside `truncated`. The
+ * budget holds and a kept part is never cut, so the largest kept parts are
+ * left out whole, each named in `truncated`, until the answer fits. The hint
+ * names the least budget that returns them: `fallback` with neither note nor
+ * hint, which `boundAnswer` answers at its own size.
+ */
+function withoutKeptParts(fallback, keptKeys, maxChars) {
+  const least = without(without(fallback, "note"), "hint");
+  const leftOut = [];
+  let out = least;
+  for (const key of [...keptKeys].sort((a, b) => size(fallback[b]) - size(fallback[a]))) {
+    if (fits(out, maxChars)) break;
+    out = { ...without(out, key), truncated: [...out.truncated, { path: key, kept: 0, total: 1 }] };
+    leftOut.push(key);
+  }
+  if (!fits(out, maxChars)) return { note: `The answer does not fit in ${maxChars} characters.`, truncated: [{ path: "$", kept: 0, total: 1 }] };
+  const one = leftOut.length === 1;
+  const hint =
+    `${listed(leftOut)} ${one ? "does" : "do"} not fit in ${maxChars} characters, so ${one ? "it is" : "they are"} left out rather than cut. ` +
+    `Call again with maxChars ${size(least)} or more for ${one ? "it" : "them"}.`;
+  return fits({ ...out, hint }, maxChars) ? { ...out, hint } : out;
+}
+
+/**
+ * A tool answer (an object) that serializes to at most `maxChars`, with
+ * `truncated`, `clipped` and `hint` saying what was cut and how to ask for
+ * less. Options, beside `boundValue`'s: `hint` (the advice for a cut answer,
+ * a query's by default), `readOn` (given the longest clipped string's note,
+ * how to read the rest of it, which the hint then says), `drop` (top-level keys left out whole, in order,
+ * before anything else is cut; each is noted as kept 0 of 1), `spare`
+ * (top-level keys left out whole, in order, only when one entry per list
+ * does not fit beside them, so they give way before the data does; noted the
+ * same way) and `fallbackHint` (the advice when even one entry per list does
+ * not fit).
+ *
+ * The budget the value is cut to is searched by bisection, so the notes are
+ * paid for exactly: data survives whenever one entry per list and the notes
+ * fit, the hint left out when only it does not. Only when they do not is the
+ * answer replaced by a note saying so. The note keeps the `keep` keys whole
+ * and names each part it left out, and a `keep` key that does not fit either
+ * is left out whole, never cut.
+ */
+export function boundAnswer(answer, maxChars = DEFAULT_MAX_CHARS, options = {}) {
+  const { hint = TRUNCATION_HINT, readOn = null, keep = [], drop = [], spare = [], whole = [], cursors = {}, connections = null, fallbackHint = hint } = options;
+  if (fits(answer, maxChars)) return answer;
+  let base = answer;
+  const dropped = [];
+  for (const key of drop) {
+    if (!(key in base)) continue;
+    base = without(base, key);
+    dropped.push({ path: key, kept: 0, total: 1 });
+    const out = withNotes(base, dropped, [], hint);
+    if (fits(out, maxChars)) return out;
+  }
+  const scope = { keep: new Set(keep), whole: new Set(whole), cursors, connections };
+  /** The answer cut to `budget` with the spare parts `left` left out, the hint kept when `hinted`; null when it overruns. */
+  const cutWith = (left, hinted) => (budget) => {
+    const from = left.reduce(without, base);
+    const { value, truncated, clipped } = boundValue(from, budget, scope);
+    const out = withNotes(value, [...dropped, ...left.map((path) => ({ path, kept: 0, total: 1 })), ...truncated], clipped, hint, readOn);
+    const answer = hinted ? out : without(out, "hint");
+    return fits(answer, maxChars) ? answer : null;
+  };
+  // Before one entry per list gives way, the hint does, then each spare part in turn; what was cut is always named.
+  const spares = spare.filter((key) => key in base);
+  let cutTo = null;
+  let best = null;
+  for (let count = 0; count <= spares.length && !best; count++) {
+    for (const hinted of [true, false]) {
+      cutTo = cutWith(spares.slice(0, count), hinted);
+      best = cutTo(0);
+      if (best) break;
+    }
+  }
+  if (!best) {
+    base = spares.reduce(without, base);
+    dropped.push(...spares.map((path) => ({ path, kept: 0, total: 1 })));
+    const keptKeys = keep.filter((key) => key in base);
+    if (!keptKeys.length) {
+      return {
+        note: `The answer does not fit in ${maxChars} characters, even cut to one entry per list.`,
+        truncated: [{ path: "$", kept: 0, total: 1 }],
+        hint: fallbackHint,
+      };
+    }
+    const omitted = Object.keys(base).filter((key) => !keep.includes(key));
+    const fallback = {
+      ...Object.fromEntries(keptKeys.map((key) => [key, base[key]])),
+      note: `${listed(omitted)} does not fit in ${maxChars} characters beside ${listed(keptKeys)}, even cut to one entry per list.`,
+      truncated: [...dropped, ...omitted.map((path) => ({ path, kept: 0, total: 1 }))],
+      hint: fallbackHint,
+    };
+    // The note goes first, since truncated names every part the note names,
+    // then the hint. Kept parts that overrun the budget even so are left out.
+    const noNote = without(fallback, "note");
+    return [fallback, noNote, without(noNote, "hint")].find((out) => fits(out, maxChars)) ?? withoutKeptParts(fallback, keptKeys, maxChars);
+  }
+  let low = 0;
+  let high = maxChars;
+  while (high - low > 1) {
+    const middle = (low + high) >> 1;
+    const out = cutTo(middle);
+    if (out) {
+      low = middle;
+      best = out;
+    } else {
+      high = middle;
+    }
+  }
+  return best;
+}