echelongraph-mcp 2.7.2 → 3.0.2

package/dist/textBudget.js

@@ -1,9 +1,13 @@
-// The text budget (#2783): what a success's first text block may cost, and how an answer larger
-// than that is cut. index.ts's `succeeded` builds every success's first text block with dataText;
-// a tool that returns a list of rows names it with a TextCut. structuredContent.data is never cut.
-// A module of its own, so a tool module can import its types and TEXT_BUDGET_DESCRIPTION without
-// importing index.ts, which starts the stdio server when loaded.
-//
+// The text budget (#2783), and the structured result's (#3013): what a success may cost in each
+// channel a client hands a model, and how an answer larger than that is cut. index.ts's
+// `succeeded` builds every success's first text block with dataText (a tool that returns a list of
+// rows names it with a TextCut), and its structured result with cutData (each tool names its lists
+// in the order they are cut with a DataCut, and answering() hands the call's `full` and DataCut to
+// `succeeded`). A module of its own, so a tool module can import its types,
+// TEXT_BUDGET_DESCRIPTION and FULL_ARG without importing index.ts, which starts the stdio server
+// when loaded.
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as z from "zod";
 // What a success costs in the channel a model reads is mostly its first text block, and through
 // 2.6.2 that block was the API's JSON pretty-printed, whatever its size. Measured on production
 // through https://mcp.echelongraph.io/mcp (2.6.2, 2026-10-04): search_cves {search: "openssl"} at
@@ -18,8 +22,8 @@
 // serialized in a text block too, as a SHOULD, for backwards compatibility, and SEP-1624 proposes
 // content as the model-facing, token-efficient form and structuredContent as the machine-facing one.
 //
-// So structuredContent.data is always the API's JSON whole, and the first text block is that JSON
-// when it fits DATA_TEXT_BUDGET, half the ceiling, and cut when it does not:
+// So the first text block is the API's JSON when it fits DATA_TEXT_BUDGET, half the ceiling, and
+// cut when it does not (structuredContent.data, below, is cut on its own terms, never from this):
 //   1. pretty-printed, as since 1.x, when that fits;
 //   2. else the same JSON with each element of a list on a line of its own, which parses to the
 //      same value, when that fits;
@@ -33,19 +37,73 @@
 //      level keeps, and before any row leaves the text;
 //   4. else every list keeps its first n entries, n halving, and then strings are cut too.
 // Whenever the text is not the JSON whole, the note ends with one sentence, starting TEXT CUT,
-// that says what the first text block leaves out, that structuredContent.data carries all of it,
+// that says what the first text block leaves out, where structuredContent.data carries all of it,
 // and how to read the rest in the text: the tool that returns one row, and what of it, and the page
 // size or offset at which a page fits. The cut is deterministic: the same answer is cut the same way.
+//
+// The structured result, per client (#3013). Through 2.7.x structuredContent.data was the API's
+// JSON whole, on the reading above that structuredContent is the machine-facing form. It is not, in
+// the client the README gives first-class install steps: Claude Code hands the model
+// structuredContent, not the text blocks (reproduced 2026-10-11 over raw JSON-RPC: get_cve
+// CVE-2021-44228 was 65,540 characters of structuredContent beside a first text block of 23,759,
+// and Claude Code refused it, "exceeds maximum allowed tokens", against its default
+// MAX_MCP_OUTPUT_TOKENS of 25,000, and saved it to a file, so the model got a path, not an answer).
+// The spec (MCP 2025-06-18, Tools, Structured Content) does not say which of the two a client gives
+// the model. So the text cut above reached every client but that one. Since 3.0.0 the structured
+// result is held to the same budget, STRUCTURED_BUDGET: the whole of it, envelope and notes with
+// data, as compact JSON, since that is what such a client sizes. Past it, data is cut (cutData):
+//   1. the lists the tool's DataCut names, step by step in its order. Where a step names thinning
+//      levels (a list whose single entries are large: check_sbom's and scan_manifest's results,
+//      check_affected's matches, cve_remediation's vendor_remediations, search_cves' and the
+//      vendor-advisory tools' rows), every entry is first cut to the fields each level keeps, level
+//      by level, all entries kept, so that no row leaves while thinning its detail would do; then
+//      each step keeps the most entries that fit, every list in the step at most the same number,
+//      its first ones, or for a list named with leaveOutFirst (check_sbom's results) those entries
+//      the tool names leave first (the clean rows, counted in data.summary), then the last of the
+//      rest, or for a step of series named keepNewest (exposure_radar's daily and weekly counts,
+//      which the API sends oldest first) its last ones, the newest, the oldest leaving first; a
+//      step that cannot fit even empty is emptied, and the next one is cut. A level can cut inside
+//      each entry on its own terms (an EntryLevel, #3132: check_sbom's rows keep at most the same
+//      number of matches, the most that fit, so only the rows with more lose any), and a step named
+//      keepAll (#3139: cve_remediation's vendor_remediations) keeps every entry at its leanest level
+//      while the later steps are cut, its entries leaving only once they all are;
+//   2. then every other list at the top level of data, the same way. A list inside an object of
+//      data (get_cve's remediation summary, with fix_status, #2841) is cut only where a DataCut
+//      names it, and none names get_cve's. Once a step fits, the room it leaves goes back to the
+//      steps emptied before it, the last first, each the same way (scan_manifest's not_checked,
+//      emptied while its rows were whole, keeps its entries once the thinned rows fit);
+//   3. no string is shortened and no value changes: a thinned entry keeps some of its fields as
+//      they are (every field a thinning level drops is optional in the outputSchema, so data still
+//      validates against it), and no field outside the lists cut changes (the one field a cut
+//      adds is an EntryLevel's mark, check_sbom's matches_truncated, which says what the row's own
+//      cut left out, and which its outputSchema names); the envelope says
+//      data_truncated true, truncated gives each list cut by its path in data with its total, the
+//      number returned and, where its entries are thinned, thinned true, and the note ends with
+//      sentences starting DATA CUT that say what was cut and to which fields, how to read the rest
+//      (the offset or page size, where the tool pages: a page size the note says fits data whole
+//      is counted on the entries whole, never on the thinned ones, #3013's review) and that the
+//      same call with full: true returns data whole.
+// The first text block is cut from the whole answer as before, not from the cut data: what it
+// holds is unchanged for the clients that read it. full: true is for programs, which read data
+// whole whatever its size; a client that sizes structured results, Claude Code among them, may
+// still refuse such an answer past its own cap (MAX_MCP_OUTPUT_TOKENS raises Claude Code's).
+// Rejected (#3013's decision of 2026-10-11): saying only that Claude Code gets files; cutting only
+// for a client whose clientInfo.name is Claude Code (the same call would answer differently by
+// client, and the next client to pass structuredContent on would get the 65,540 again); and dropping
+// structuredContent (it loses the outputSchema check the spec recommends and the suite relies on).
 export const DATA_TEXT_BUDGET = 30_000;
 // What a note may say of reading one CVE's record through get_cve (#2802): get_cve's own first text
-// block is cut too past the budget (each list to its first entries, every other field kept), so
-// only its structuredContent.data is the record whole. A row tool's `whole` sentence starts with it.
-export const GET_CVE_WHOLE = "get_cve returns any one of these CVEs' records, whole in its structuredContent.data, and in its first text block with every field (past 30,000 characters, each list cut to its first entries)";
+// block is cut too past the budget (each list to its first entries, every other field kept), and
+// since #3013 so is its structured result's data, unless the call says full: true. A row tool's
+// `whole` sentence starts with it.
+export const GET_CVE_WHOLE = "get_cve returns any one of these CVEs' records, whole in its structuredContent.data with full: true, and in its first text block with every field (past 30,000 characters, each list cut to its first entries)";
 // What every tool description says about it, one constant string (marketing-site
 // lib/mcpToolClaims.test.ts folds only constant strings); the suite holds its number to
 // DATA_TEXT_BUDGET's. It uses none of the words that check reviews as the page's own prose (how,
-// when, does, have, on and the rest of its PROSE list), so no reviewed entry goes stale.
-export const TEXT_BUDGET_DESCRIPTION = "Past 30,000 characters of JSON, the first text block holds data cut to fit, and the note says what the cut leaves out and where to read it (TEXT CUT); data in the structured result always holds it whole.";
+// when, does, have, on and the rest of its PROSE list), so no reviewed entry goes stale. #3013: the
+// same length as 2.7.x's (203 characters), since several descriptions sit within ten characters of
+// the floor the suite keeps under the client cut (#2924); FULL_ARG says the rest.
+export const TEXT_BUDGET_DESCRIPTION = "Past 30,000 characters of JSON, the first text block holds data cut to fit, and the note says what the cut leaves out and where to read it (TEXT CUT); so is structured data (DATA CUT), unless full: true.";
 const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const field = (o, k) => (isPlainObject(o) ? o[k] : undefined);
 const listed = (xs) => (xs.length < 2 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`);
@@ -66,11 +124,12 @@ function cutValue(v, clip, cap, s) {
     if (typeof v === "string") {
         if (v.length <= clip)
             return v;
-        s.clipped++;
+        if (s)
+            s.clipped++;
         return clipString(v, clip);
     }
     if (Array.isArray(v)) {
-        if (v.length > cap)
+        if (s && v.length > cap)
             s.capped++;
         return v.slice(0, cap).map((x) => cutValue(x, clip, cap, s));
     }
@@ -78,18 +137,31 @@ function cutValue(v, clip, cap, s) {
         return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, cutValue(x, clip, cap, s)]));
     return v;
 }
+// A RowKeep as the fields it names, each with its subfields (null: kept whole), built once per
+// RowKeep (3.0.2: through 3.0.1, once per row cut; a 2,000-row answer's structured cut built it
+// some 12,000 times). A RowKeep is never changed once built.
+const wantedOf = (() => {
+    const built = new WeakMap();
+    return (keep) => {
+        let wanted = built.get(keep);
+        if (!wanted)
+            built.set(keep, (wanted = new Map(keep.map((k) => (typeof k === "string" ? [k, null] : [k[0], k[1]])))));
+        return wanted;
+    };
+})();
 function cutRow(row, keep, level, s, prefix = "") {
-    const wanted = new Map(keep.map((k) => (typeof k === "string" ? [k, null] : [k[0], k[1]])));
+    const wanted = wantedOf(keep);
     const cap = level.cap ?? Number.POSITIVE_INFINITY;
     const out = {};
-    for (const [k, v] of Object.entries(row)) {
+    for (const k of Object.keys(row)) {
+        const v = row[k];
         if (!wanted.has(k)) {
-            s.left.add(`${prefix}${k}`);
+            s?.left.add(`${prefix}${k}`);
             continue;
         }
         const sub = wanted.get(k);
         if (sub && Array.isArray(v)) {
-            if (v.length > cap)
+            if (s && v.length > cap)
                 s.capped++;
             out[k] = v.slice(0, cap).map((e) => (isPlainObject(e) ? cutRow(e, sub, level, s, `${prefix}${k}[].`) : cutValue(e, level.clip, cap, s)));
         }
@@ -165,6 +237,12 @@ function cutSides(data, sides) {
 export const FIRST_TEXT_BLOCK = {
     opens: (chars) => `TEXT CUT: the API's answer is ${chars} characters of JSON, more than the ${DATA_TEXT_BUDGET} the first text block holds, so that block is cut, and structuredContent.data carries the answer whole.`,
 };
+// #3013: the first text block beside a structuredContent.data that is cut too (DATA CUT): the same
+// text, cut the same way, and sentences that say data is whole only with full: true.
+export const FIRST_TEXT_BLOCK_BESIDE_A_CUT = {
+    opens: (chars) => `TEXT CUT: the API's answer is ${chars} characters of JSON, more than the ${DATA_TEXT_BUDGET} the first text block holds, so that block is cut, and structuredContent.data carries the answer whole with full: true (DATA CUT, below).`,
+    leftOut: (n, which) => `the other ${n} are left out of it${which}, and structuredContent.data holds them with full: true`,
+};
 /** The first text block for `data` within DATA_TEXT_BUDGET, and the TEXT CUT sentence when it is cut. */
 export function dataText(data, cut, place = FIRST_TEXT_BLOCK) {
     const pretty = JSON.stringify(data, null, 2);
@@ -232,7 +310,8 @@ export function dataText(data, cut, place = FIRST_TEXT_BLOCK) {
             const which = outFirst > 0
                 ? `: the ${outFirst} whose ${firstOut?.field} is ${(firstOut?.values ?? []).join(" or ")} (${firstOut?.why})${out.size > outFirst ? `, and the last ${out.size - outFirst} of the rest` : ""}`
                 : `, the last ${out.size} in order`;
-            const left = `Only ${kept.length} of the ${n} rows of ${cut.rows} are in it; the other ${out.size} are in structuredContent.data only${which}.`;
+            const elsewhere = place.leftOut ? place.leftOut(out.size, which) : `the other ${out.size} are in structuredContent.data only${which}`;
+            const left = `Only ${kept.length} of the ${n} rows of ${cut.rows} are in it; ${elsewhere}.`;
             return { text: shown, said: say(rowsSaid, ...sidesSaid, left, cut.whole, cut.page?.(kept.length, n, data)) };
         }
         base = { ...beside, [cut.rows]: cutRows };
@@ -250,5 +329,492 @@ export function dataText(data, cut, place = FIRST_TEXT_BLOCK) {
     const more = last.caps.size > 8 ? `, and ${last.caps.size - 8} more` : "";
     const lists = last.caps.size ? `Every list in it keeps at most its first ${last.n} ${last.n === 1 ? "entry" : "entries"}: ${listed(named)}${more}, each named with its full length.` : "";
     const strings = last.s.clipped ? `Every string in it longer than ${last.clip} characters keeps its first ${last.clip}, ending in "…".` : "";
-    return { text: last.text, said: say(rowsSaid, ...sidesSaid, lists, strings, cut?.whole) };
+    const said = say(rowsSaid, ...sidesSaid, lists, strings, cut?.whole);
+    if (last.caps.size === 0)
+        return { text: last.text, said };
+    return { text: last.text, said, capped: Object.fromEntries([...last.caps].map(([p, len]) => [p || "the answer", { total: len, returned: Math.min(last.n, len) }])) };
+}
+// ── The structured result's budget (#3013) ──
+//
+// What a success's structured result may cost, all of it (the envelope, its notes and data), as
+// compact JSON, which is how a client that hands structuredContent to a model reads it: the same
+// number as the first text block's. See "The structured result, per client" above.
+export const STRUCTURED_BUDGET = DATA_TEXT_BUDGET;
+// The clause of a paging tool's DATA CUT sentence that names the page size whose rows fit data
+// whole, given PageAt.wholeFit for its rows (search_cves, search_vendor_advisories).
+export const wholePage = (n) => n > 0
+    ? `a page of ${n} ${n === 1 ? "row" : "rows"} or fewer like these fits data whole.`
+    : `even a page of one row like these is past ${STRUCTURED_BUDGET} characters with that row whole, so its data is cut too.`;
+// A tool that names no list: only step 2 (every list at the top level of data) cuts its data.
+export const NO_DATA_CUT = { steps: [] };
+const calls = new AsyncLocalStorage();
+export function answering(full, cut, fn) {
+    return calls.run({ full: full === true, cut }, fn);
+}
+export const answeringNow = () => calls.getStore();
+// The argument every tool takes (#3013), and what it says, one constant string. It names no other
+// tool and directs no model (test/description-policy.test.mjs reads inputSchema descriptions too).
+export const FULL_ARG_DESCRIPTION = "true: data in the structured result is the answer whole, however long. Without it, a structured result past 30,000 characters of JSON has its data cut (DATA CUT): in an order the note states, the entries of its longest lists keep only some of their fields, and then the lists only some of their entries; data_truncated is true, and truncated gives each list cut with its total, the number returned and whether its entries are thinned. Whole data is for a program; a client that sizes structured results, as Claude Code does against MAX_MCP_OUTPUT_TOKENS, can refuse an answer past its cap.";
+export const FULL_ARG = z.boolean().optional().describe(FULL_ARG_DESCRIPTION);
+// A level as its fields, and what it does inside each entry (#3132).
+const levelOf = (l) => (Array.isArray(l) ? { keep: l } : l);
+const thinned = (e, level, cap = Number.POSITIVE_INFINITY) => {
+    if (!isPlainObject(e))
+        return e;
+    const { keep, capped, mark } = levelOf(level);
+    const t = cutRow(e, keep, { keep, clip: Number.POSITIVE_INFINITY });
+    const inner = capped ? t[capped] : undefined;
+    if (capped && Array.isArray(inner) && inner.length > cap)
+        t[capped] = inner.slice(0, cap);
+    return mark ? { ...t, ...mark(e, cap) } : t;
+};
+// The longest list named `capped` inside any entry of a list (#3132): the cap a level starts below.
+const longestInside = (v, capped) => Array.isArray(v) ? v.reduce((m, e) => Math.max(m, Array.isArray(field(e, capped)) ? field(e, capped).length : 0), 0) : 0;
+// An entry JSON cannot write (undefined) is written null in a list.
+const entryChars = (e) => JSON.stringify(e)?.length ?? 4;
+const listOf = (data, at) => at.reduce((o, k) => field(o, k), data);
+// 3.0.2: a list's entries are measured, thinned, only when the cut first asks how many characters
+// some of them take (chars), each thinned, measured and let go; and thinned to be kept only when
+// the cut asks for them (keep), only those it keeps, each once. Through 3.0.1 every list the cut
+// tried held every entry thinned for as long as the cut ran, and a level that caps a list inside
+// each entry thinned every entry at no cap before it tried any: on a 2,000-row check_sbom answer
+// (test/http-memory.test.mjs's) the structured cut allocated 108 MB, against 18 MB on 3.0.0 and 24
+// MB now (V8's sampling heap profiler, collected objects included). What is measured and kept is
+// the same: each entry thinned as before, its characters summed as before.
+function listAt(data, path, firstOut, level, newest, cap = Number.POSITIVE_INFINITY, levelAt) {
+    const at = path.split(".");
+    const v = listOf(data, at);
+    if (!Array.isArray(v) || v.length === 0)
+        return undefined;
+    const n = v.length;
+    const made = [];
+    const entry = (i) => {
+        if (!level)
+            return v[i];
+        if (!(i in made))
+            made[i] = thinned(v[i], level, cap);
+        return made[i];
+    };
+    const thin = level ? levelOf(level).keep : undefined;
+    // A capped level's clause only where its cap cuts an entry's list (#3139's review: a package
+    // with one range is not "at most its first 1").
+    const lv = level ? levelOf(level) : undefined;
+    const bites = lv?.capped === undefined || v.some((e) => (Array.isArray(field(e, lv.capped)) ? field(e, lv.capped).length : 0) > cap);
+    const thinSaid = lv && bites ? lv.said?.(cap) : undefined;
+    // The indices in the order they leave: from the end, or, for a series kept newest, from the start.
+    const leavingOrder = (i) => (newest ? i : n - 1 - i);
+    const order = [];
+    for (const value of firstOut?.values ?? [])
+        for (let j = 0; j < n; j++)
+            if (field(v[leavingOrder(j)], firstOut?.field ?? "") === value)
+                order.push(leavingOrder(j));
+    const named = order.length;
+    const queued = new Set(order);
+    for (let j = 0; j < n; j++)
+        if (!queued.has(leavingOrder(j)))
+            order.push(leavingOrder(j));
+    // The characters of the entries in the order they leave, summed: leaving[j] is the first j's.
+    let leaving;
+    const sums = () => {
+        if (leaving)
+            return leaving;
+        const lens = [];
+        for (let i = 0; i < n; i++)
+            lens.push(entryChars(!level || i in made ? entry(i) : thinned(v[i], level, cap)));
+        leaving = [0];
+        for (const i of order)
+            leaving.push(leaving[leaving.length - 1] + lens[i]);
+        return leaving;
+    };
+    const kept = (k) => Math.max(0, Math.min(n, k));
+    const over = new Map();
+    const keptAt = (k) => {
+        const out = new Set(order.slice(0, n - kept(k)));
+        return Array.from({ length: n }, (_, i) => i).filter((i) => !out.has(i));
+    };
+    return {
+        path,
+        at,
+        n,
+        firstOut,
+        thin,
+        ...(thinSaid ? { thinSaid } : {}),
+        ...(newest ? { newest } : {}),
+        named,
+        ...(levelAt !== undefined ? { level: levelAt } : {}),
+        cap,
+        over,
+        chars: (k) => {
+            const l = sums();
+            return l[n] - l[n - kept(k)] + Math.max(0, kept(k) - 1);
+        },
+        kept: keptAt,
+        keep: (k) => keptAt(k).map((i) => (over.has(i) ? over.get(i)?.entry : entry(i))),
+    };
+}
+// `o` with the list at `at` replaced by `v`, each object on the way copied, its keys in their order.
+function withList(o, at, v) {
+    const [k, ...rest] = at;
+    return { ...o, [k]: rest.length ? withList(o[k], rest, v) : v };
+}
+const orListed = (xs) => (xs.length < 2 ? xs.join("") : `${xs.slice(0, -1).join(", ")} or ${xs[xs.length - 1]}`);
+// The fields a thinning level keeps, as a sentence says them.
+const keepSaid = (keep) => listed(keep.map((x) => (typeof x === "string" ? x : `${x[0]} (each with ${listed([...x[1]])})`)));
+// The clause on the entries that took back detail (#3132's review): their positions among those
+// kept, in their order in data, grouped where one level and cap holds a run of them (#3132's second
+// review: not always the first kept, since give-back passes an entry that cannot take any back).
+function givenBackSaid(list, k) {
+    if (list.over.size === 0)
+        return "";
+    const kept = list.kept(k);
+    const runs = [];
+    kept.forEach((i, pos) => {
+        const g = list.over.get(i);
+        if (!g)
+            return;
+        const last = runs[runs.length - 1];
+        if (last && last.to === pos && last.g.level === g.level && last.g.cap === g.cap)
+            last.to = pos + 1;
+        else
+            runs.push({ from: pos + 1, to: pos + 1, g });
+    });
+    if (runs.length === 0)
+        return "";
+    const n = runs.reduce((t, r) => t + r.to - r.from + 1, 0);
+    const one = (r) => `${r.from === r.to ? `entry ${r.from}` : `entries ${r.from} to ${r.to}`} cut to ${keepSaid(r.g.keep)}${r.g.said ? `, ${r.g.said}` : ""}`;
+    return `; with the room left, ${n} of the entries kept take back detail (by position among those kept, in their order in data): ${runs.map(one).join("; ")}`;
+}
+// What a cut keeps of each list it has cut so far, as truncated and as the DATA CUT sentences.
+function cutSaid(cut, kept, wholeChars, data, over, wholeFit) {
+    const isThinned = ({ list, k }) => list.thin !== undefined && k > 0;
+    const cutOnes = kept.filter((x) => x.k < x.list.n || isThinned(x));
+    if (cutOnes.length === 0)
+        return { said: "" };
+    const truncated = Object.fromEntries(cutOnes.map((x) => [x.list.path, { total: x.list.n, returned: x.k, ...(isThinned(x) ? { thinned: true } : {}) }]));
+    const parts = [];
+    const byKept = new Map();
+    for (const x of cutOnes) {
+        const { list, k } = x;
+        const out = list.n - k;
+        const first = Math.min(out, list.named);
+        const end = list.newest ? "oldest" : "last";
+        const which = list.firstOut ? `whose ${list.firstOut.field} is ${orListed(list.firstOut.values)} (${list.firstOut.why})` : "";
+        const leftOut = out === 0 ? "" : first === 0 ? `, the ${end} ${out} left out` : first === out ? `, the ${out} left out being entries ${which}` : `, the ${out} left out being the ${first} ${which} and the ${end} ${out - first} of the rest`;
+        if (isThinned(x)) {
+            parts.push(`${list.path} keeps ${k === list.n ? `all ${k}` : `${k} of its ${list.n}`} entries, each cut to ${keepSaid(list.thin)}${list.thinSaid ? `, ${list.thinSaid}` : ""}${leftOut}${givenBackSaid(list, k)}`);
+            continue;
+        }
+        if (!list.firstOut || first === 0 || k === 0) {
+            const newest = list.newest === true && k > 0;
+            const key = `${k}:${newest}`;
+            const group = byKept.get(key);
+            if (group)
+                group.lists.push(list);
+            else {
+                const g = { k, newest, lists: [list] };
+                byKept.set(key, g);
+                parts.push(g);
+            }
+            continue;
+        }
+        parts.push(`${list.path} keeps ${k} of its ${list.n} entries${leftOut}`);
+    }
+    const cuts = parts.map((p) => {
+        if (typeof p === "string")
+            return p;
+        const paths = listed(p.lists.map((l) => l.path));
+        const which = p.newest ? "newest" : "first";
+        if (p.lists.length === 1)
+            return p.k === 0 ? `${paths} keeps none of its ${p.lists[0].n} entries` : `${paths} keeps its ${which} ${p.k} of ${p.lists[0].n} entries`;
+        return p.k === 0 ? `${paths} keep none of their entries` : `${paths} keep their ${which} ${p.k} entries each`;
+    });
+    const keeps = Object.fromEntries(cutOnes.filter(isThinned).map((x) => [x.list.path, x.list.thin]));
+    const page = cut.page?.(truncated, data, { keeps, wholeFit }) ?? "";
+    const said = [
+        `DATA CUT: with data whole, this structured result is ${wholeChars} characters of JSON, more than the ${STRUCTURED_BUDGET} it holds unless the call says full: true, so its data is cut: ${cuts.join("; ")}.`,
+        "truncated gives the total and the number returned of each list cut, and thinned where its entries are cut to some of their fields.",
+        page,
+        over ? `Cut so, the structured result is still past ${STRUCTURED_BUDGET} characters: data holds no other list to cut.` : "",
+        "The same call with full: true returns data whole.",
+    ];
+    return { truncated, said: said.filter(Boolean).join(" ") };
+}
+/**
+ * The structured result for `data` cut to STRUCTURED_BUDGET, as `cut` says (see "The structured
+ * result, per client" above): `structured` builds the result for a data, its truncated and the DATA
+ * CUT sentences, and is called with data null to size the rest of it. `wholeChars` is the result's
+ * size with data whole. undefined when data holds no list to cut.
+ */
+export function cutData(data, cut, wholeChars, structured) {
+    if (!isPlainObject(data))
+        return undefined;
+    const named = new Set(cut.steps.flatMap((s) => s.lists));
+    const steps = [...cut.steps, { lists: Object.keys(data).filter((k) => !named.has(k)) }];
+    // Each list cut so far, in the order cut, at the level it was thinned to, how many entries it
+    // keeps, and the step that cut it.
+    const kept = new Map();
+    const apply = (also = []) => [...kept.values(), ...also].reduce((d, { list, k }) => withList(d, list.at, list.keep(k)), data);
+    // PageAt.wholeFit: of the list at `path`, the most first entries, each whole, that the result
+    // holds within the budget with the rest of data whole and no DATA CUT sentence (structured with
+    // truncated undefined): the shape of the same call at that page size. Counted once per path.
+    const wholeFits = new Map();
+    const wholeFit = (path) => {
+        const known = wholeFits.get(path);
+        if (known !== undefined)
+            return known;
+        const at = path.split(".");
+        const v = listOf(data, at);
+        let k = 0;
+        if (Array.isArray(v)) {
+            let chars = JSON.stringify(structured(withList(data, at, []), undefined, "")).length;
+            for (const e of v) {
+                chars += entryChars(e) + (k > 0 ? 1 : 0);
+                if (chars > STRUCTURED_BUDGET)
+                    break;
+                k++;
+            }
+        }
+        wholeFits.set(path, k);
+        return k;
+    };
+    // The result's size with this step's lists at k entries each: the rest of the result (data
+    // null), data with this step's lists empty (`base`), and their entries.
+    const size = (lists, k, base) => {
+        const all = [...kept.values(), ...lists.map((list) => ({ list, k: Math.min(k, list.n) }))];
+        const { truncated, said } = cutSaid(cut, all, wholeChars, data, false, wholeFit);
+        return JSON.stringify(structured(null, truncated, said)).length - "null".length + base + lists.reduce((t, l) => t + l.chars(k), 0);
+    };
+    let fits = false;
+    for (const [s, step] of steps.entries()) {
+        // Every entry whole, then each thinning level in turn, every entry kept; at the leanest level
+        // the entries leave until the result fits (with keepAll, #3139, not in this step: see below).
+        const levels = [undefined, ...(step.thin ?? [])];
+        let lists = [];
+        let k = 0;
+        const at = (level, cap, levelAt) => step.lists.map((p) => listAt(data, p, step.leaveOutFirst, level, step.keepNewest, cap, levelAt)).filter((l) => l !== undefined && !kept.has(l.path));
+        for (const [i, thin] of levels.entries()) {
+            lists = at(thin, undefined, i - 1);
+            if (lists.length === 0)
+                break;
+            const base = JSON.stringify(apply(lists.map((list) => ({ list, k: 0 })))).length;
+            const top = Math.max(...lists.map((l) => l.n));
+            // #3132: a level that caps a list inside each entry, every entry kept: the most entries of
+            // that inner list, the same number in each, that fit; a level where even none fits is passed.
+            // #3132's review: a level with `least` is taken at that cap or more, or passed.
+            const capped = thin === undefined ? undefined : levelOf(thin).capped;
+            if (capped !== undefined) {
+                const longest = Math.max(0, ...step.lists.map((p) => longestInside(listOf(data, p.split(".")), capped)));
+                const least = (thin === undefined ? undefined : levelOf(thin).least) ?? 0;
+                if (longest > least && size(at(thin, least, i - 1), top, base) <= STRUCTURED_BUDGET) {
+                    let m = least;
+                    let hi = longest - 1;
+                    while (m < hi) {
+                        const mid = Math.ceil((m + hi) / 2);
+                        if (size(at(thin, mid, i - 1), top, base) <= STRUCTURED_BUDGET)
+                            m = mid;
+                        else
+                            hi = mid - 1;
+                    }
+                    lists = at(thin, m, i - 1);
+                    k = top;
+                    fits = true;
+                    break;
+                }
+                if (i < levels.length - 1)
+                    continue;
+                // The last level, and even its least cap does not fit: the entries go on at that cap.
+                lists = at(thin, least, i - 1);
+            }
+            if (i < levels.length - 1) {
+                if (size(lists, top, base) <= STRUCTURED_BUDGET) {
+                    k = top;
+                    fits = true;
+                    break;
+                }
+                continue;
+            }
+            if (step.keepAll) {
+                // #3139: every entry stays, at this level; the later steps are cut first.
+                k = top;
+                fits = size(lists, top, base) <= STRUCTURED_BUDGET;
+                break;
+            }
+            // #3132's review: entries leave at the step's leaveAt level, where it names one.
+            if (step.leaveAt && step.thin) {
+                const { level, cap } = step.leaveAt;
+                lists = at(step.thin[level], cap, level);
+            }
+            if (step.whole) {
+                // Every entry or none (#3132's review: data.not_sent_purls).
+                if (size(lists, 0, base) <= STRUCTURED_BUDGET) {
+                    k = size(lists, top, base) <= STRUCTURED_BUDGET ? top : 0;
+                    fits = true;
+                }
+                break;
+            }
+            if (size(lists, 0, base) <= STRUCTURED_BUDGET) {
+                // The most entries each list of the step keeps with the result inside the budget.
+                let hi = top;
+                while (k < hi) {
+                    const mid = Math.ceil((k + hi) / 2);
+                    if (size(lists, mid, base) <= STRUCTURED_BUDGET)
+                        k = mid;
+                    else
+                        hi = mid - 1;
+                }
+                fits = true;
+            }
+        }
+        for (const list of lists)
+            kept.set(list.path, { list, k: Math.min(k, list.n), step: s });
+        if (fits)
+            break;
+    }
+    const exact = () => {
+        const { truncated, said } = cutSaid(cut, [...kept.values()], wholeChars, data, false, wholeFit);
+        return JSON.stringify(structured(apply(), truncated, said)).length;
+    };
+    // #3139: every step cut and the result still past the budget: a keepAll step's entries leave now,
+    // the step's first, as many as must, the rest of data as the steps after it left it. The steps
+    // after it then take back what room is left (below), as though it were the step that fits.
+    // #3139's review: with more than one keepAll step, the last one's entries leave first
+    // (cve_remediation's fixed_branches before any vendor advisory).
+    if (!fits) {
+        for (const [s, step] of [...steps.entries()].reverse()) {
+            if (!step.keepAll || fits)
+                continue;
+            const entries = [...kept.values()].filter((e) => e.step === s);
+            if (entries.length === 0)
+                continue;
+            const set = (k) => {
+                for (const e of entries)
+                    e.k = Math.min(k, e.list.n);
+            };
+            set(0);
+            if (exact() > STRUCTURED_BUDGET)
+                continue;
+            let k = 0;
+            let hi = Math.max(...entries.map((e) => e.list.n));
+            while (k < hi) {
+                const mid = Math.ceil((k + hi) / 2);
+                set(mid);
+                if (exact() <= STRUCTURED_BUDGET)
+                    k = mid;
+                else
+                    hi = mid - 1;
+            }
+            set(k);
+            for (const e of entries)
+                e.step = steps.length;
+            fits = true;
+        }
+    }
+    // The room the step that fits leaves goes back to the steps emptied before it, the last first,
+    // each step's lists keeping at most the same number of their entries, as many as fit, at the
+    // level they were thinned to (scan_manifest's not_checked, emptied while its rows were whole,
+    // keeps its entries once the thinned rows fit).
+    if (fits) {
+        const last = Math.max(...[...kept.values()].map((e) => e.step));
+        for (let s = last - 1; s >= 0; s--) {
+            const entries = [...kept.values()].filter((e) => e.step === s);
+            if (entries.length === 0)
+                continue;
+            const at = (k) => {
+                for (const e of entries)
+                    e.k = Math.min(k, e.list.n);
+            };
+            let k = Math.min(...entries.map((e) => e.k));
+            let hi = Math.max(...entries.map((e) => e.list.n));
+            if (steps[s].whole) {
+                // Every entry or none (#3132's review).
+                at(hi);
+                if (exact() > STRUCTURED_BUDGET)
+                    at(k);
+                continue;
+            }
+            while (k < hi) {
+                const mid = Math.ceil((k + hi) / 2);
+                at(mid);
+                if (exact() <= STRUCTURED_BUDGET)
+                    k = mid;
+                else
+                    hi = mid - 1;
+            }
+            at(k);
+        }
+    }
+    // #3132's review: then a giveBack step's entries, in their order in data, take back detail (see
+    // DataCutStep): each the richest level above its own that fits. A RowKeep level is tried whole;
+    // of the capped levels, only the leanest at or above the entry's own (check_sbom's compact one,
+    // or the entry's own), uncapped and then at the most inner entries that fit, so a row takes back
+    // more of its matches compact before fewer of them thinned. #3132's second review: an entry that
+    // takes back nothing is passed, not an end (through round 2 it ended give-back, so a row at the
+    // compact level holding every match, too large to move up, kept every later capped row at its
+    // cap while room was left); the entries that took some are named by position (givenBackSaid).
+    if (fits) {
+        for (const [s, step] of steps.entries()) {
+            if (!step.giveBack || !step.thin)
+                continue;
+            const thin = step.thin;
+            for (const e of [...kept.values()].filter((x) => x.step === s)) {
+                const { list } = e;
+                const own = list.level;
+                if (own === undefined || list.thin === undefined)
+                    continue;
+                const whole = listOf(data, list.at);
+                if (!Array.isArray(whole))
+                    continue;
+                let leanestCapped = -1;
+                for (let j = 0; j <= own; j++)
+                    if (levelOf(thin[j]).capped !== undefined)
+                        leanestCapped = j;
+                const tryAt = (i, j, c) => {
+                    const l = levelOf(thin[j]);
+                    list.over.set(i, { entry: thinned(whole[i], thin[j], c), level: j, cap: c, keep: l.keep, ...(l.said && l.capped && c < Number.POSITIVE_INFINITY ? { said: l.said(c) } : {}) });
+                    if (exact() <= STRUCTURED_BUDGET)
+                        return true;
+                    list.over.delete(i);
+                    return false;
+                };
+                for (const i of list.kept(e.k)) {
+                    // An entry its own level already keeps as the richest would is passed, not an end.
+                    if (JSON.stringify(thinned(whole[i], thin[0])) === JSON.stringify(thinned(whole[i], thin[own], list.cap)))
+                        continue;
+                    let took = false;
+                    for (let j = 0; j <= own && !took; j++) {
+                        const l = levelOf(thin[j]);
+                        const inner = l.capped !== undefined && Array.isArray(field(whole[i], l.capped)) ? field(whole[i], l.capped).length : 0;
+                        if (l.capped === undefined) {
+                            if (j < own)
+                                took = tryAt(i, j, Number.POSITIVE_INFINITY);
+                            continue;
+                        }
+                        if (j !== leanestCapped)
+                            continue;
+                        if (j < own || list.cap < inner)
+                            took = tryAt(i, j, Number.POSITIVE_INFINITY);
+                        if (took)
+                            break;
+                        let c = j === own ? list.cap + 1 : (l.least ?? 0);
+                        let hi = inner - 1;
+                        if (c > hi || !tryAt(i, j, c))
+                            continue;
+                        while (c < hi) {
+                            const mid = Math.ceil((c + hi) / 2);
+                            if (tryAt(i, j, mid))
+                                c = mid;
+                            else
+                                hi = mid - 1;
+                        }
+                        took = tryAt(i, j, c);
+                    }
+                }
+            }
+        }
+    }
+    const { truncated, said } = cutSaid(cut, [...kept.values()], wholeChars, data, !fits, wholeFit);
+    if (truncated === undefined)
+        return undefined;
+    const d = apply();
+    return { data: d, truncated, said, structured: structured(d, truncated, said) };
 }