pi-supernova 0.8.2 → 0.9.1

package/src/fs/vfs.js

@@ -1,248 +1,14 @@
+import {textSignature,sameFileVersion,fileSignature,tooLargeRead,overlayOrThrow,assertReadableFile,readLimitedBytes,remapReadError} from './file-io.js';
+import {resolveCommitTarget,assertExpectedSignature,collectMissingAncestors,makeStageEntry,stageReplacement,installStaged,failCommit,cleanupStaged} from './commit.js';
+export {resolveCommitTarget} from './commit.js';
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isString } from "../shared/decode.js";
 import { decodeUtf8Strict } from "../shared/utf8.js";
-import { createHash, randomUUID } from "node:crypto";
 
 // Serialize validation + replacement across Supernova transactions in this host.
 let commitTail = Promise.resolve();
 
-function textSignature(text) {
-  return { size: Buffer.byteLength(text, "utf8"), sha256: createHash("sha256").update(text, "utf8").digest("hex") };
-}
-
-function sameFileVersion(a, b) {
-  return ["dev", "ino", "size", "mtimeMs", "ctimeMs"].every(key => a[key] === b[key]);
-}
-
-async function fileSignature(target, signal, observed) {
-  const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
-
-  try {
-    const actual = await file.stat();
-
-    if (!actual.isFile()) throw new Error("read requires a regular file: " + target);
-    if (observed && !sameFileVersion(observed, actual)) throw new Error("file changed while reading: " + target);
-    const hash = createHash("sha256");
-
-    for await (const chunk of file.createReadStream({ autoClose: false, signal })) hash.update(chunk);
-    const after = await file.stat();
-
-    if (!after.isFile() || !sameFileVersion(actual, after)) throw new Error("file changed while signing: " + target);
-
-    return { size: actual.size, sha256: hash.digest("hex") };
-  } finally {
-    await file.close();
-  }
-}
-
-// realpath() cannot resolve a missing leaf. Canonicalize its nearest existing
-// ancestor so two symlink spellings still share one commit destination.
-async function canonicalNewPath(target) {
-  let ancestor = path.dirname(target);
-
-  for (;;) {
-    try { return path.join(await fs.realpath(ancestor), path.relative(ancestor, target)); }
-    catch (error) {
-      if (error.code !== "ENOENT") throw error;
-      const parent = path.dirname(ancestor);
-
-      if (parent === ancestor) throw error;
-      ancestor = parent;
-    }
-  }
-}
-
-function sameSignature(a, b) {
-  return a === b || (a !== null && b !== null && a.size === b.size && a.sha256 === b.sha256);
-}
-
-function tooLargeRead(label, maxBytes) {
-  return new Error(label + " exceeds " + maxBytes + " bytes; use a streaming parser through bash");
-}
-
-function overlayOrThrow(overlay, maxBytes, label) {
-  if (maxBytes !== undefined && Buffer.byteLength(overlay, "utf8") > maxBytes) throw tooLargeRead(label, maxBytes);
-
-  return overlay;
-}
-
-function assertReadableFile(stat, target) {
-  // Callers are reads, writes, edits and patch application: name the path, not the caller.
-  if (stat.isDirectory()) throw new Error("path is a directory, not a file: " + target);
-
-  if (!stat.isFile()) throw new Error("path is not a regular file: " + target);
-}
-
-async function readLimitedBytes(file, stat, maxBytes, label, signal) {
-  if (stat.size > maxBytes) throw tooLargeRead(label, maxBytes);
-  const chunks = [];
-  let size = 0;
-
-  for await (const chunk of file.createReadStream({ end: maxBytes, autoClose: false, signal })) {
-    size += chunk.length;
-
-    if (size > maxBytes) throw tooLargeRead(label, maxBytes);
-    chunks.push(chunk);
-  }
-
-  return Buffer.concat(chunks);
-}
-
-function remapReadError(err, target) {
-  if (err.code === "EISDIR") throw new Error("path is a directory, not a file: " + target);
-
-  if (err.code === "ENOTDIR") throw new Error("cannot use path: a parent component of " + target + " is a file, not a directory");
-  if (err.code === "EACCES" || err.code === "EPERM") throw new Error("permission denied reading " + target + ": check the file mode (for example bash chmod)");
-
-  if (err.code === "ENOENT") {
-    const missing = new Error("no such file: " + target + ' (locate it with read using a directory path or source question; use Promise.allSettled for optional reads to retain successful siblings)');
-    missing.code = "ENOENT";
-    throw missing;
-  }
-
-  throw err;
-}
-
-async function resolveExistingFile(logicalPath) {
-  const target = await fs.realpath(logicalPath);
-  const stat = await fs.stat(target);
-
-  if (!stat.isFile()) throw new Error("cannot write to a non-file: " + logicalPath);
-
-  return { target, stat };
-}
-
-async function resolveCommitTarget(logicalPath) {
-  try {
-    return await resolveExistingFile(logicalPath);
-  } catch (err) {
-    if (err.code !== "ENOENT") throw err;
-
-    return { target: await canonicalNewPath(logicalPath), stat: undefined };
-  }
-}
-
-async function collectMissingAncestors(parent) {
-  const missing = [];
-  let probe = parent;
-
-  for (;;) {
-    try { await fs.stat(probe); break; } catch (err) {
-      if (err.code !== "ENOENT") throw err;
-      missing.push(probe);
-      probe = path.dirname(probe);
-    }
-  }
-
-  return missing;
-}
-
-async function writeTemporary(entry, content, stat) {
-  try {
-    await fs.writeFile(entry.temporary, content, { encoding: "utf8", flag: "wx", mode: stat ? stat.mode & 0o7777 : 0o666 });
-  } catch (error) {
-    // Never leak the temporary name: name the destination and the real cause.
-    if (error?.code === "EACCES" || error?.code === "EPERM") throw new Error("permission denied writing " + entry.target + ": the directory or file is not writable");
-    if (error?.code === "EROFS") throw new Error("cannot write " + entry.target + ": the file system is read-only");
-    if (error?.code === "ENOSPC") throw new Error("cannot write " + entry.target + ": no space left on device");
-
-    throw error;
-  }
-
-  if (stat) await fs.chmod(entry.temporary, stat.mode & 0o7777);
-}
-
-async function stageReplacement(entry, content, stat, target) {
-  const replacement = writeTemporary(entry, content, stat);
-  // These touch separate staging files. Settle both before cleanup, even
-  // on failure: Promise.all could leave a late backup after rollback.
-  const staging = [replacement];
-
-  if (stat) staging.push(fs.copyFile(target, entry.backup, fs.constants.COPYFILE_EXCL));
-  const outcomes = await Promise.allSettled(staging);
-  const failure = outcomes.find(outcome => outcome.status === "rejected");
-
-  if (failure) throw failure.reason;
-}
-
-function makeStageEntry(logicalPath, target, content, parent, stat) {
-  const token = ".supernova-" + randomUUID();
-
-  return { logicalPath, target, content, temporary: path.join(parent, token + ".new"), backup: path.join(parent, token + ".bak"), existed: !!stat, replaced: false };
-}
-
-async function recoverReplaced(staged) {
-  const recoveryErrors = [];
-
-  for (const entry of staged.toReversed()) {
-    if (!entry.replaced) continue;
-
-    try {
-      if (entry.existed) await fs.rename(entry.backup, entry.target);
-      else await fs.unlink(entry.target);
-    } catch (err) {
-      // Keep the backup if recovery fails; never delete the remaining original.
-      entry.keepBackup = true;
-      recoveryErrors.push(entry.target + ": " + err.message + " (backup: " + entry.backup + ")");
-    }
-  }
-
-  return recoveryErrors;
-}
-
-async function cleanupStaged(staged, failed, createdDirs) {
-  for (const entry of staged) {
-    // A successful rename consumed the temporary path. These are known
-    // files, so unlink avoids rm's extra type probe; missing files stay benign.
-    if (!entry.replaced) await fs.unlink(entry.temporary).catch(() => {});
-
-    if (entry.existed && !entry.keepBackup) await fs.unlink(entry.backup).catch(() => {});
-  }
-
-  if (failed) for (const dir of createdDirs.toReversed()) await fs.rmdir(dir).catch(() => {});
-}
-
-async function assertExpectedSignature(vfs, logicalPath, target, stat) {
-  if (!vfs.expected.has(logicalPath)) return;
-  const current = stat ? await fileSignature(target, vfs.signal) : null;
-
-  if (!sameSignature(current, vfs.expected.get(logicalPath))) {
-    throw new Error("write conflict: file changed since it was read: " + logicalPath + "; read it again before retrying");
-  }
-}
-
-async function installStaged(vfs, staged) {
-  for (const entry of staged) {
-    vfs.signal?.throwIfAborted();
-    await fs.rename(entry.temporary, entry.target);
-    entry.replaced = true;
-  }
-
-  for (const entry of staged) {
-    vfs.expected.set(entry.logicalPath, textSignature(entry.content));
-  }
-
-  // Canonical commit destinations must not rewrite established event paths
-  // for newly created files, whose callers supplied a logical cwd spelling.
-  if (staged.length) vfs.onNewFile?.(staged.map(entry => entry.existed ? entry.target : entry.logicalPath));
-}
-
-async function failCommit(vfs, staged, error) {
-  const recoveryErrors = await recoverReplaced(staged);
-  // Keep CAS baselines: a failed commit must not forgive conflicts on files it
-  // never touched. If recovery left disk diverging from a baseline, the next
-  // write to that path fails loudly and forces a re-read instead of silently
-  // re-capturing unknown bytes as the new truth.
-
-  if (recoveryErrors.length) vfs.mutations.recoveryFailed = true;
-
-  if (recoveryErrors.length) vfs.onNewFile?.(null);
-
-  if (recoveryErrors.length) throw new AggregateError([error, ...recoveryErrors.map(message => new Error(message))], "commit failed: " + error.message + "; recovery failed: " + recoveryErrors.join("; "));
-  throw error;
-}
-
 export class CausalVfs {
   constructor(onNewFile, validateWrite) {
     this.validateWrite = validateWrite;
@@ -275,7 +41,7 @@ export class CausalVfs {
   async read(target, { preserveRead = false, maxBytes, label = "read input", strict = true } = {}) {
     const overlay = this.getOverlay(target);
 
-    if (overlay !== undefined) return overlayOrThrow(overlay, maxBytes, label);
+    if (overlay !== undefined) return overlayOrThrow(overlay, maxBytes, label, target);
 
     // External editors and captured tools can change a file between any two reads.
     // Open once with O_NONBLOCK so a FIFO or device cannot park a host I/O worker.
@@ -288,7 +54,7 @@ export class CausalVfs {
         assertReadableFile(stat, target);
         bytes = maxBytes === undefined
           ? await file.readFile({ signal: this.signal })
-          : await readLimitedBytes(file, stat, maxBytes, label, this.signal);
+          : await readLimitedBytes(file, stat, maxBytes, label, this.signal, () => tooLargeRead(label,maxBytes,target));
         if (!sameFileVersion(stat, await file.stat())) throw new Error("file changed while reading: " + target);
       } finally { await file.close(); }
 

package/src/fs/workspace.js

@@ -1,3 +1,4 @@
+import {remapReadError} from "./file-io.js";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { spawn } from "node:child_process";
@@ -44,7 +45,7 @@ async function realpathNearest(target) {
     try {
       return await fs.realpath(probe);
     } catch (err) {
-      if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") throw err;
+      if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") remapReadError(err, target);
       const parent = path.dirname(probe);
 
       if (parent === probe) throw err;

package/src/output/bottleneck.js

@@ -1,8 +1,9 @@
+import {READ_VALUE} from "../shared/result.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
-import { isString, isObject, mapChangedChildren, assertModelImageMime } from "../shared/decode.js";
-import { truncateChars, formatReturn, formatBoundedStringArray } from "./format.js";
+import { isString, isObject } from "../shared/decode.js";
+import { truncateChars } from "./format.js";
 
 function json(value) {
   try { return JSON.stringify(value) ?? "null"; } catch { return JSON.stringify(String(value)); }
@@ -221,8 +222,16 @@ function attachTruncation(result, truncated, batch, text, config, maxChars, capp
 }
 
 export function packageHostResult(raw, config) {
-  const maxChars = config.maxCallResultChars ?? 65536;
   const details = detailsOf(raw);
+  if (raw && Object.hasOwn(raw, READ_VALUE)) {
+    const batch = batchFromDetails(details);
+    const result = {ok: !hostResultFailed(raw), value: raw[READ_VALUE], typed: true, cloneItems: details?.jsonMany === true, truncated: details?.outputTruncated === true};
+    attachDetails(result, details, batch);
+    if (batch) { result.items = batch; result.itemErrors = details.itemErrors ?? []; }
+    if (details?.streamed) result.streamed = true;
+    return result;
+  }
+  const maxChars = config.maxCallResultChars ?? 65536;
   const batch = batchFromDetails(details);
   const text = batch ? "" : extractRawString(raw);
   const capped = truncateChars(text, maxChars, "host-result");
@@ -237,67 +246,4 @@ export function packageHostResult(raw, config) {
   return result;
 }
 
-function collectImage(input, acc) {
-  if (!(input?.type === "image" && isString(input.data) && isString(input.mimeType) && input.mimeType.startsWith("image/"))) return null;
-  assertModelImageMime(input.mimeType);
-  const size = Buffer.byteLength(input.data, "base64");
-
-  acc.imageCount += 1;
-  acc.imageBytes += size;
-  if (acc.imageCount > 16 || acc.imageBytes > 20 * 1024 * 1024) {
-    acc.imageOverflow = true;
-    return "[image over budget]";
-  }
-  acc.images.push({ type: "image", data: input.data, mimeType: input.mimeType });
-
-  return `[image ${acc.images.length}: ${input.mimeType}]`;
-}
-
-function collectImages(input, acc) {
-  const replaced = collectImage(input, acc);
-
-  if (replaced !== null) return replaced;
-
-  return mapChangedChildren(input, collectImages, acc);
-}
-
-function serializeReturn(value, formatted, maxReturn, imageOverflow) {
-  if (formatted.length <= maxReturn) return { text: formatted, truncated: imageOverflow };
-
-  if (Array.isArray(value) && value.length && value.every(isString)) return { text: formatBoundedStringArray(value, maxReturn), truncated: true };
-
-  return { ...truncateChars(formatted, maxReturn, "return"), truncated: true };
-}
-
-function clipLogLine(line, maxLogLineChars) {
-  const result = truncateChars(line, maxLogLineChars, "log");
-
-  return { text: result.text, truncated: result.truncated };
-}
-
-function clipLogs(logs, config) {
-  const maxLines = config.maxLogLines ?? 100;
-  let logTruncated = logs.length > maxLines;
-  const clipped = logs.slice(0, maxLines).map(line => {
-    const result = clipLogLine(line, config.maxLogLineChars ?? 4096);
-    logTruncated ||= result.truncated;
-
-    return result.text;
-  });
-
-  return { logs: clipped, logTruncated };
-}
-
-export function packageFinalReturn(value, logs, config) {
-  const acc = { images: [], imageCount: 0, imageBytes: 0, imageOverflow: false };
-  value = collectImages(value, acc);
-  if (acc.imageOverflow) {
-    throw new Error(`image attachment budget exceeded: ${acc.imageCount} images / ${acc.imageBytes} bytes; limit is 16 images / 20971520 bytes (20 MiB). No images returned; return fewer or smaller images per program`);
-  }
-  const maxReturn = config.maxReturnChars ?? 32000;
-  const serialized = serializeReturn(value, formatReturn(value), maxReturn, acc.imageOverflow);
-  const clipped = clipLogs(logs, config);
-
-  return { returnValue: serialized.truncated ? serialized.text : value, returnText: serialized.text,
-    returnTruncated: serialized.truncated, logs: clipped.logs, logTruncated: clipped.logTruncated, images: acc.images };
-}
+export {packageFinalReturn} from "./final.js";

package/src/output/final.js

@@ -0,0 +1,114 @@
+import {isString,mapChangedChildren,assertModelImageMime,decodeImageData} from "../shared/decode.js";
+import {assertPng} from "../shared/png.js";
+import {truncateChars,formatReturn,formatBoundedStringArray,formatBoundedValue,isStringArray} from "./format.js";
+
+function collectImage(input, acc) {
+  if (!(input?.type === "image" && isString(input.data) && isString(input.mimeType) && input.mimeType.startsWith("image/"))) return null;
+  assertModelImageMime(input.mimeType);
+  const size = Buffer.byteLength(input.data, "base64");
+
+  acc.imageCount += 1;
+  acc.imageBytes += size;
+  if (acc.imageCount > 16 || acc.imageBytes > 20 * 1024 * 1024) {
+    acc.imageOverflow = true;
+    return "[image over budget]";
+  }
+  const bytes = decodeImageData(input.data);
+  if (input.mimeType === "image/png") assertPng(bytes);
+  acc.images.push({ type: "image", data: input.data, mimeType: input.mimeType });
+
+  return `[image ${acc.images.length}: ${input.mimeType}]`;
+}
+
+function displayWeight(value,key) {
+  // Count even omitted undefined fields: typed result metadata crosses RPC too.
+  const field = isString(key) ? key.length+1 : 0;
+  return field + (isString(value) ? value.length : 1) + (Array.isArray(value) ? value.length : 0);
+}
+
+function collectImages(input, acc, key) {
+  const replaced = collectImage(input, acc);
+  acc.displayUnits += displayWeight(replaced ?? input,key);
+  if (replaced !== null) return replaced;
+
+  return mapChangedChildren(input, collectImages, acc);
+}
+
+function serializeReturn(value, formatted, maxReturn, imageOverflow) {
+  if (formatted.length <= maxReturn) return { text: formatted, truncated: imageOverflow };
+
+  if (isStringArray(value)) return { text: formatBoundedStringArray(value, maxReturn), truncated: true };
+
+  return { ...truncateChars(formatted, maxReturn, "return"), truncated: true };
+}
+
+function clipLogLine(line, maxLogLineChars) {
+  const result = truncateChars(line, maxLogLineChars, "log");
+
+  return { text: result.text, truncated: result.truncated };
+}
+
+function clipLogs(logs, config) {
+  const maxLines = config.maxLogLines ?? 100;
+  let logTruncated = logs.length > maxLines;
+  const clipped = logs.slice(0, maxLines).map(line => {
+    const result = clipLogLine(line, config.maxLogLineChars ?? 4096);
+    logTruncated ||= result.truncated;
+
+    return result.text;
+  });
+
+  return { logs: clipped, logTruncated };
+}
+
+function isSourceView(value) {
+  return value?.status === "found" && isString(value.path) && isString(value.text) && Array.isArray(value.lines);
+}
+
+function sourcePreview(value, maxReturn) {
+  if (!isSourceView(value)) return null;
+  if (value.text.length < maxReturn / 2) return null;
+  if (value.text.length <= maxReturn && formatReturn(value).length <= maxReturn-256) return null;
+  const base = {...value,text:"",complete:false,nextOffset:value.lines[0]+1};
+  let room = maxReturn - formatReturn(base).length - 512;
+  while (room > 0) {
+    const end = value.text.lastIndexOf("\n",room-1) + 1;
+    if (!end || end >= value.text.length) return null;
+    const text = value.text.slice(0,end);
+    const lines = [value.lines[0],value.lines[0]+text.match(/\n/g).length-1];
+    const preview = {...base,text,lines,nextOffset:lines[1]+1};
+    if (formatReturn(preview).length <= maxReturn-256) return preview;
+    room = Math.floor(room / 2);
+  }
+  return null;
+}
+
+function presentValue(value, maxReturn, oversized) {
+  if (isString(value)) {
+    const bounded = truncateChars(value,maxReturn,"return");
+    const result = serializeReturn(value,formatReturn(bounded.text),maxReturn,false);
+    result.truncated ||= bounded.truncated;
+    return result;
+  }
+  if (isStringArray(value) && oversized) {
+    return {text:formatBoundedStringArray(value,maxReturn),truncated:true};
+  }
+  if (oversized) return {text:formatBoundedValue(value,maxReturn),truncated:true};
+  return serializeReturn(value,formatReturn(value),maxReturn,false);
+}
+
+export function packageFinalReturn(value, logs, config) {
+  const acc = { images: [], imageCount: 0, imageBytes: 0, imageOverflow: false, displayUnits:0 };
+  value = collectImages(value, acc);
+  if (acc.imageOverflow) {
+    throw new Error(`image attachment budget exceeded: ${acc.imageCount} images / ${acc.imageBytes} bytes; limit is 16 images / 20971520 bytes (20 MiB). No images returned; return fewer or smaller images per program`);
+  }
+  const maxReturn = config.maxReturnChars ?? 32000;
+  const preview = sourcePreview(value,maxReturn);
+  if (preview) value = preview;
+  const serialized = presentValue(value,maxReturn,!preview && acc.displayUnits>maxReturn);
+  const clipped = clipLogs(logs, config);
+
+  return { returnValue: serialized.truncated ? serialized.text : value, returnText: serialized.text,
+    returnTruncated: serialized.truncated || Boolean(preview), logs: clipped.logs, logTruncated: clipped.logTruncated, images: acc.images };
+}

package/src/output/format.js

@@ -1,4 +1,5 @@
 import { isString, isObject, mapChangedChildren } from "../shared/decode.js";
+import {maxJsonStringPrefix} from "../fs/json-size.js";
 
 function normalizeText(text) {
   return isString(text) ? text : String(text ?? "");
@@ -76,24 +77,40 @@ function hasUnpairedSurrogate(text) {
   return SURROGATE_CODE_UNIT.test(text) && UNPAIRED_SURROGATE.test(text);
 }
 
+export function isStringArray(value) {
+  if (!Array.isArray(value) || !value.length) return false;
+  for (const item of value) if (!isString(item)) return false;
+  return true;
+}
+
 function hasWellFormedStrings(values) {
   for (const value of values) if (!isString(value) || hasUnpairedSurrogate(value)) return false;
 
   return true;
 }
 
-/** Keep every array item in an oversized return by giving each a fair truncated share. */
+function boundedStringText(value, limit) {
+  const text = truncateChars(value,limit,"return").text;
+  return hasUnpairedSurrogate(text) ? truncateChars(JSON.stringify(text),limit,"return").text : text;
+}
+
+/** Give displayed array items a fair share; disclose any omitted items. */
 export function formatBoundedStringArray(values, budget) {
   const n = values.length;
   const header = "strings[" + n + "]\n";
   let remaining = Math.max(0, budget - header.length);
   let out = header;
+  if (header.length >= budget) return truncateChars(header,budget,"return").text;
+  const omitted = count => "…[return truncated; " + count + " string items omitted]…\n";
 
   for (let i = 0; i < n; i++) {
     const itemHeader = "[" + i + "] " + values[i].length + " UTF-16 units\n";
-    const per = Math.max(32, Math.floor(remaining / (n - i)) - itemHeader.length - 1);
-    const bounded = truncateChars(values[i], per, "return");
-    const chunk = itemHeader + bounded.text + "\n";
+    const footer = i + 1 < n ? omitted(n - i - 1) : "";
+    if (remaining < itemHeader.length + Math.min(32,values[i].length) + 1 + footer.length) {
+      return out + truncateChars(omitted(n - i),remaining,"return").text;
+    }
+    const per = Math.min(remaining - itemHeader.length - 1 - footer.length, Math.max(32, Math.floor(remaining / (n - i)) - itemHeader.length - 1));
+    const chunk = itemHeader + boundedStringText(values[i],per) + "\n";
     remaining = Math.max(0, remaining - chunk.length);
     out += chunk;
   }
@@ -149,7 +166,7 @@ function framedReturn(value) {
 
 /** Lossless framing for source arrays, not string escaping or source compression. */
 export function formatReturn(value) {
-  if (isString(value)) return value;
+  if (isString(value)) return hasUnpairedSurrogate(value) ? JSON.stringify(value) : value;
   const rawArray = formatRawStringArray(value);
 
   if (rawArray !== null) return rawArray;
@@ -287,3 +304,75 @@ export function formatValue(value, indent = "", width = FORMAT_WIDTH, seen = new
     seen.delete(value);
   }
 }
+
+
+function displayKeys(value) {
+  return Array.isArray(value) ? value.keys() : Object.keys(value);
+}
+
+/** A cheap lower bound stops before expanding large/shared result subtrees. */
+export function displayExceeds(value, budget) {
+  const seen = new Set();
+  const spend = units => (budget -= units) < 0;
+  function container(item) {
+    if (seen.has(item)) return false;
+    seen.add(item);
+    const array = Array.isArray(item);
+    if (array && spend(item.length)) return true;
+    for (const key of displayKeys(item)) {
+      if (!array && spend(key.length+1)) return true;
+      if (visit(item[key])) return true;
+    }
+    seen.delete(item);
+    return false;
+  }
+  function visit(item) {
+    if (spend(isString(item) ? item.length : 1)) return true;
+    return isObject(item) || Array.isArray(item) ? container(item) : false;
+  }
+  return visit(value);
+}
+
+/** Display-only prefix; never constructs an oversized JSON/string rendering. */
+export function formatBoundedValue(value, budget, label = "return") {
+  const footer = "\n…["+label+" truncated]…";
+  const parts = [];
+  const seen = new Set();
+  let remaining = Math.max(0,budget-footer.length), stopped = false;
+  const push = text => {
+    if (text.length > remaining) { stopped = true; return false; }
+    remaining -= text.length; parts.push(text); return true;
+  };
+  function quoted(text) {
+    const end = maxJsonStringPrefix(text,remaining);
+    push(JSON.stringify(text.slice(0,end)));
+    if (end < text.length) stopped = true;
+  }
+  function visitChild(item,key,array) {
+    if (!array) { quoted(key); push(":"); }
+    visit(array && item[key] === undefined ? null : item[key]);
+  }
+  function container(item) {
+    if (seen.has(item)) { push('"[Circular]"'); return; }
+    seen.add(item);
+    const array = Array.isArray(item);
+    push(array ? "[" : "{");
+    let first = true;
+    for (const key of displayKeys(item)) {
+      if (stopped) break;
+      if (!first) push(",");
+      first = false;
+      visitChild(item,key,array);
+    }
+    if (!stopped) push(array ? "]" : "}");
+    seen.delete(item);
+  }
+  function visit(item) {
+    if (stopped) return;
+    if (isString(item)) quoted(item);
+    else if (isObject(item) || Array.isArray(item)) container(item);
+    else push(formatPrimitive(item));
+  }
+  visit(value);
+  return truncateChars(parts.join("")+footer,budget,"return").text;
+}