pi-supernova 0.10.2 → 0.11.0

package/src/fs/vfs.js

@@ -1,25 +1,66 @@
-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';
+import {textSignature,sameSignature,sameFileVersion,fileSignature,tooLargeRead,overlayOrThrow,assertReadableFile,readLimitedBytes,remapReadError} from './file-io.js';
+import {resolveFileIdentity,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 { AsyncLocalStorage } from "node:async_hooks";
 import { isString } from "../shared/decode.js";
 import { decodeUtf8Strict } from "../shared/utf8.js";
 
 // Serialize validation + replacement across Supernova transactions in this host.
 let commitTail = Promise.resolve();
 
+const readScopes = new Set();
+
+let installingPaths = null;
+
+function scopeContains(scope, target) {
+  const relative = path.relative(scope, target);
+
+  return relative === "" || (relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative));
+}
+
+function noteCommitPath(target) {
+  installingPaths.add(target);
+
+  for (const read of readScopes) {
+    if (scopeContains(read.scope, target)) read.changed = true;
+  }
+}
+
+// Readers validate after every in-process commit they could have observed.
+// An aborted reader must not retain its buffers until another writer finishes.
+async function waitForCommits(signal) {
+  signal?.throwIfAborted();
+
+  if (!signal) return commitTail;
+  let abort;
+
+  const cancelled = new Promise((_, reject) => {
+    abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+  });
+
+  try { await Promise.race([commitTail, cancelled]); }
+  finally { signal.removeEventListener("abort", abort); }
+}
+
+
 export class CausalVfs {
   constructor(onNewFile, validateWrite, assertCurrent) {
     this.validateWrite = validateWrite;
     this.assertCurrent = assertCurrent;
     // No body cache: every read hits disk (or its overlay) so observed bytes
-    // are never stale. CAS baselines in `expected` are the only retained
-    // per-file state, cleared only at external-mutation boundaries.
+    // are never stale. CAS signatures and observed logical-to-physical bindings
+    // survive between operations, but clear at external-mutation boundaries.
     this.overlays = [];
     this.expected = new Map();
+    this.observedPaths = new Map();
+    this.pathScope = new AsyncLocalStorage();
+    this.bestEffort = false;
+    this.pendingSignatures = new Map();
     this.onNewFile = onNewFile;
     this.closed = false;
     this.signal = undefined;
@@ -33,25 +74,118 @@ export class CausalVfs {
     this.signal?.throwIfAborted();
   }
 
-  getOverlay(target) {
+  // Reuse identity only within one native operation. Commit resolution is
+  // always fresh, and no path/body cache survives into the next operation.
+  withPathScope(fn) { return this.pathScope.run({paths:new Map()}, fn); }
+
+  bindMutationRecord(record) {
+    const scope = this.pathScope.getStore();
+
+    if (scope) scope.record = record;
+  }
+
+  async resolvePath(target, allowMissing = true) {
+    const scope = this.pathScope.getStore()?.paths;
+    let pending = scope?.get(target);
+
+    if (!pending) {
+      pending = resolveFileIdentity(target);
+      scope?.set(target, pending);
+    }
+
+    const identity = await pending;
+
+    if (!allowMissing && identity.missing) throw identity.missing;
+
+    return identity.path;
+  }
+
+  #assertWriteAlias(logicalPath, entry) {
+    if (entry && entry.logicalPath !== logicalPath) throw new Error("conflicting write aliases: " + logicalPath);
+  }
+
+  #overlay(target) {
     for (let i = this.overlays.length - 1; i >= 0; i--) {
-      if (this.overlays[i].has(target)) return this.overlays[i].get(target);
+      const entry = this.overlays[i].get(target);
+
+      if (entry) return entry;
     }
   }
 
-  getOverlayPaths() {
-    return [...new Set(this.overlays.flatMap(overlay => [...overlay.keys()]))];
+  async getOverlay(target) {
+    this.signal?.throwIfAborted();
+
+    if (!this.overlays.some(layer => layer.size)) return undefined;
+
+    return this.#overlay(await this.resolvePath(target))?.content;
+  }
+
+  async getOverlayPaths(scope) {
+    const entries = new Map(this.overlays.flatMap(overlay => [...overlay]));
+
+    if (!scope || !entries.size) return [...entries.values()].map(entry => entry.logicalPath);
+    const canonical = await this.resolvePath(scope);
+
+    // Expose the caller's scope spelling, including directories not yet on disk.
+    const paths = [];
+
+    for (const target of entries.keys()) {
+      if (scopeContains(canonical, target)) paths.push(path.resolve(scope, path.relative(canonical, target)));
+    }
+
+    return paths;
   }
 
-  async read(target, { preserveRead = false, maxBytes, label = "read input", strict = true } = {}) {
-    const overlay = this.getOverlay(target);
+  #assertIdentity(logicalPath, target) {
+    const observed = this.observedPaths.get(logicalPath);
+
+    if (observed !== undefined && observed !== target) throw new Error("write conflict: path target changed since it was read: " + logicalPath + "; read it again before retrying");
+  }
+
+  #observe(logicalPath, target, signature, preserveRead = false) {
+    if (preserveRead) this.#assertIdentity(logicalPath, target);
+
+    if (!preserveRead || !this.expected.has(target)) this.expected.set(target, signature);
+    this.observedPaths.set(logicalPath, target);
+  }
+
+  async readRevision(scope) {
+    let canonical;
+
+    try { canonical = await this.resolvePath(scope); }
+    catch (error) { await remapReadError(error, scope); }
+
+    const read = { scope: canonical, changed: [...(installingPaths ?? [])].some(target => scopeContains(canonical, target)) };
+    readScopes.add(read);
+
+    return read;
+  }
+
+  releaseRead(read) { readScopes.delete(read); }
+
+  async assertReadCommitted(read) {
+    try {
+      if (read.changed) await waitForCommits(this.signal);
+      this.signal?.throwIfAborted();
+
+      if (read.changed) throw new Error("workspace may have changed while reading; retry the read");
+    } finally { this.releaseRead(read); }
+  }
 
-    if (overlay !== undefined) return overlayOrThrow(overlay, maxBytes, label, target);
+  async read(target, { preserveRead = false, forWrite = false, maxBytes, label = "read input", strict = true } = {}) {
+    this.signal?.throwIfAborted();
+    let revision;
 
     // 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.
     try {
-      const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+      revision = await this.readRevision(target);
+      const overlay = this.#overlay(revision.scope);
+
+      if (forWrite) this.#assertWriteAlias(target, overlay);
+
+      if (overlay) return overlayOrThrow(overlay.content, maxBytes, label, target);
+      const file = await fs.open(revision.scope, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
       let bytes;
 
       try {
@@ -64,13 +198,15 @@ export class CausalVfs {
         if (!sameFileVersion(stat, await file.stat())) throw new Error("file changed while reading: " + target);
       } finally { await file.close(); }
 
+      await this.assertReadCommitted(revision);
+
       // Hash the actual bytes, not a lossy UTF-8 decode/re-encode.
-      if (!preserveRead || !this.expected.has(target)) this.expected.set(target, textSignature(bytes));
+      this.#observe(target, revision.scope, textSignature(bytes), preserveRead || forWrite);
 
       return strict ? decodeUtf8Strict(bytes, target) : bytes.toString("utf8");
     } catch (err) {
       await remapReadError(err, target);
-    }
+    } finally { this.releaseRead(revision); }
   }
 
   async #diskSignature(target) {
@@ -83,15 +219,56 @@ export class CausalVfs {
   }
 
   async captureExpected(target) {
-    if (this.getOverlay(target) !== undefined || this.expected.has(target)) return;
+    const canonical = await this.resolvePath(target);
+    await this.#captureExpected(target, canonical);
+  }
+
+  async #captureExpected(logicalPath, target) {
+    this.#assertIdentity(logicalPath, target);
 
-    this.expected.set(target, await this.#diskSignature(target));
+    if (!this.#overlay(target) && !this.expected.has(target)) this.expected.set(target, await this.#diskSignature(target));
+    this.observedPaths.set(logicalPath, target);
   }
 
-  async recordExpected(target, observed) {
-    if (this.getOverlay(target) !== undefined) return;
-    const signature = observed ? await fileSignature(target, this.signal, observed) : await this.#diskSignature(target);
-    this.expected.set(target, signature);
+  async recordExpected(target, observed, bytes) {
+    this.signal?.throwIfAborted();
+    const revision = await this.readRevision(target), canonical = revision.scope;
+    let job;
+
+    try {
+      if (this.#overlay(canonical)) return;
+
+      if (!observed) {
+        this.#observe(target, canonical, await this.#diskSignature(canonical));
+
+        return;
+      }
+
+      // Windows timestamps can alias same-size rewrites; loaded bytes must
+      // still agree with disk. Other hosts can reuse a complete byte snapshot.
+      if (bytes !== undefined && (!Buffer.isBuffer(bytes) || bytes.length !== observed.size)) throw new Error("file changed while reading: " + target + "; expected complete bytes");
+      job = this.pendingSignatures.get(canonical);
+
+      if (!job || !sameFileVersion(job.observed, observed)) {
+        job = { observed, promise: bytes === undefined || process.platform === "win32"
+          ? fileSignature(canonical, this.signal, observed)
+          : Promise.resolve(textSignature(bytes)) };
+        this.pendingSignatures.set(canonical, job);
+      }
+
+      const signature = await job.promise;
+
+      if (bytes !== undefined && process.platform === "win32" && !sameSignature(signature, textSignature(bytes))) throw new Error("file changed while reading: " + target);
+      await this.assertReadCommitted(revision);
+
+      // Each window retains its own post-read check even when hashing overlaps.
+      if (!sameFileVersion(observed, await fs.stat(canonical))) throw new Error("file changed while reading: " + target);
+      this.#observe(target, canonical, signature);
+    } finally {
+      this.releaseRead(revision);
+
+      if (job && this.pendingSignatures.get(canonical) === job) this.pendingSignatures.delete(canonical);
+    }
   }
 
   async write(target, content) {
@@ -99,25 +276,51 @@ export class CausalVfs {
 
     if (!isString(content)) throw new Error("write requires string content");
 
-    try {
-      if ((await fs.stat(target)).isDirectory()) throw new Error("cannot write to a directory: " + target);
-    } catch (err) {
-      if (err.code !== "ENOENT") throw err;
+    if (!content.isWellFormed()) throw new Error("write requires well-formed Unicode text: unpaired UTF-16 surrogate in " + target + "; avoid splitting a Unicode character");
+
+    const canonical = await this.resolvePath(target);
+    const previous = this.#overlay(canonical);
+
+    this.#assertWriteAlias(target, previous);
+
+    if (!previous) {
+      try {
+        if ((await fs.stat(canonical)).isDirectory()) throw new Error("cannot write to a directory: " + target);
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+      }
     }
 
     this.assertWritable();
 
-    await this.captureExpected(target);
+    await this.#captureExpected(target, canonical);
 
     this.assertWritable();
+    const latest = this.#overlay(canonical);
+
+    // Concurrent aliases may have staged while signature capture awaited I/O.
+    this.#assertWriteAlias(target, latest);
 
-    if (this.overlays.length) {
-      this.overlays.at(-1).set(target, content);
+    const record = this.pathScope.getStore()?.record;
+
+    // The host retains an empty outer layer for program lifecycle bookkeeping.
+    // Best-effort mode stages only inside an explicit inner checkpoint.
+    if (this.overlays.length && (!this.bestEffort || this.overlays.length > 1)) {
+      this.overlays.at(-1).set(canonical, { logicalPath: target, content });
+
+      if (record) { record.mutationState = "pending"; record.mutationDepth = this.overlays.length; }
 
       return { speculative: true };
     }
 
-    await this.flush(new Map([[target, content]]));
+    try {
+      await this.flush(new Map([[target, content]]), new Map([[target, canonical]]));
+
+      if (record) record.mutationState = "saved";
+    } catch (error) {
+      if (record && this.mutations.recoveryFailed) record.mutationState = "uncertain";
+      throw error;
+    }
 
     return { speculative: false };
   }
@@ -130,15 +333,61 @@ export class CausalVfs {
   }
 
   /** Stage every file and its backup before replacing any destination. */
-  async flush(writes) {
-    this.mutations.pendingCommits++;
-    const work = commitTail.then(() => this.flushWrites(writes)).finally(() => { this.mutations.pendingCommits--; });
-    commitTail = work.catch(() => {});
+  async #flushOverlay(overlay) {
+    const writes = new Map(), targets = new Map();
+
+    for (const [target, entry] of overlay) {
+      writes.set(entry.logicalPath, entry.content);
+      targets.set(entry.logicalPath, target);
+    }
+
+    return this.flush(writes, targets);
+  }
+
+  async flush(writes, pinnedTargets = new Map()) {
+    this.assertCurrent?.();
+    this.signal?.throwIfAborted();
 
-    return work;
+    if (!writes.size) return;
+    this.mutations.pendingCommits++;
+    const signal = this.signal;
+    let started = false, cancelled = false, pendingWrites = writes, pendingTargets = pinnedTargets;
+
+    return new Promise((resolve, reject) => {
+      const abort = () => {
+        if (started || cancelled) return;
+        cancelled = true;
+        pendingWrites = null;
+        pendingTargets = null;
+        this.mutations.pendingCommits--;
+        signal.removeEventListener("abort", abort);
+        reject(signal.reason);
+      };
+
+      // Withdrawal does not release the predecessor's lock. A later live
+      // transaction still waits for it; only this caller can settle early.
+      const work = commitTail.then(async () => {
+        if (cancelled) return;
+        started = true;
+        signal?.removeEventListener("abort", abort);
+
+        installingPaths = new Set();
+
+        for (const target of pendingWrites.keys()) noteCommitPath(target);
+
+        try { resolve(await this.flushWrites(pendingWrites, pendingTargets)); }
+        catch (error) { reject(error); }
+        finally { installingPaths = null; pendingWrites = null; pendingTargets = null; this.mutations.pendingCommits--; }
+      });
+
+      commitTail = work.catch(() => {});
+      signal?.addEventListener("abort", abort, {once:true});
+
+      if (signal?.aborted) abort();
+    });
   }
 
-  async flushWrites(writes) {
+  async flushWrites(writes, pinnedTargets = new Map()) {
     const staged = [];
     const targets = new Set();
     const createdDirs = [];
@@ -151,7 +400,12 @@ export class CausalVfs {
       for (const [logicalPath, content] of writes) {
         this.signal?.throwIfAborted();
         const { target, stat } = await resolveCommitTarget(logicalPath);
+        // Validation may wait or cancel; publish the physical read hazard first.
+        noteCommitPath(target);
         await this.validateWrite?.(logicalPath);
+        this.#assertIdentity(logicalPath, target);
+
+        if (pinnedTargets.has(logicalPath) && pinnedTargets.get(logicalPath) !== target) throw new Error("write conflict: path target changed while staged: " + logicalPath);
 
         if (targets.has(target)) throw new Error("conflicting write aliases: " + logicalPath);
         targets.add(target);
@@ -179,12 +433,12 @@ export class CausalVfs {
     if (!this.overlays.length) return { committed: 0, depth: 0 };
     const top = this.overlays.at(-1);
 
-    if (this.overlays.length > 1) {
+    if (this.overlays.length > 1 && !(this.bestEffort && this.overlays.length === 2)) {
       const parent = this.overlays[this.overlays.length - 2];
 
       for (const [key, value] of top) parent.set(key, value);
     } else {
-      await this.flush(top);
+      await this.#flushOverlay(top);
     }
 
     this.overlays.pop();
@@ -216,24 +470,25 @@ export class CausalVfs {
  return false; }
 
     const pending = this.overlays[0];
-    await this.flush(pending);
-    this.assertWritable();
+    await this.#flushOverlay(pending);
+    // Committed writes no longer belong to the speculative rollback set.
     this.overlays[0] = new Map();
+    this.assertWritable();
     this.mutations.external++;
 
     return pending.size > 0;
   }
 
   /** External-mutation boundary: drop CAS baselines so the next access re-observes disk. */
-  invalidateObserved() { this.expected.clear(); }
+  invalidateObserved() { this.expected.clear(); this.observedPaths.clear(); this.pathScope.getStore()?.paths.clear(); }
   getOverlayDepth() { return this.overlays.length; }
   describeOverlays() {
     let files = 0, bytes = 0;
 
     for (const layer of this.overlays) {
-      for (const content of layer.values()) {
+      for (const entry of layer.values()) {
         files++;
-        bytes += Buffer.byteLength(content, "utf8");
+        bytes += Buffer.byteLength(entry.content, "utf8");
       }
     }
 

package/src/fs/workspace.js

@@ -4,6 +4,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { spawn } from "node:child_process";
 import { constants } from "node:os";
+import { StringDecoder } from "node:string_decoder";
 import { isString } from "../shared/decode.js";
 import { truncateChars } from "../output/format.js";
 
@@ -92,11 +93,13 @@ function rejectUriPath(trimmed, opName, allowSessionRead) {
 
 /** Reject scheme:// and scheme:/ paths. A single-letter drive (C:/) stays a filesystem path. */
 export function assertFilesystemPath(inputPath, opName, allowSessionRead = false) {
-  if (inputPath == null || !isString(inputPath) || !inputPath.trim()) {
+  if (inputPath == null || !isString(inputPath) || inputPath.length === 0) {
     throw new Error(`${opName} requires path`);
   }
 
-  return rejectUriPath(inputPath.trim(), opName, allowSessionRead);
+  if (!inputPath.isWellFormed()) throw new Error(`${opName} requires a well-formed Unicode path: unpaired UTF-16 surrogate`);
+
+  return rejectUriPath(String(inputPath), opName, allowSessionRead);
 }
 
 export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false, fresh = false) {
@@ -206,6 +209,23 @@ function appendCommandOutput(state, current, chunk) {
   return remaining ? current + chunk.slice(0, remaining) : current;
 }
 
+function captureCommandStream(state, name) {
+  const stream = state.child[name], decoder = new StringDecoder("utf8");
+
+  stream.on("data", chunk => {
+    // Keep draining after the shared cap fills, without decoding discarded text
+    // or backpressuring a child that still needs to finish its work.
+    if (state.stdout.length + state.stderr.length >= state.maxOutputChars) {
+      if (chunk.length) state.outputTruncated = true;
+
+      return;
+    }
+
+    state[name] = appendCommandOutput(state, state[name], decoder.write(chunk));
+  });
+  stream.once("end", () => { state[name] = appendCommandOutput(state, state[name], decoder.end()); });
+}
+
 function attachCommandIO(state, options, argv, timeoutMs) {
   const { child } = state;
   const onAbort = () => terminateCommand(state, new Error("aborted"));
@@ -218,10 +238,8 @@ function attachCommandIO(state, options, argv, timeoutMs) {
     "command timed out after " + timeoutMs + "ms: " + truncateChars(options.commandLabel ?? argv.join(" "), 240, "command").text
     + "\nhint: Increase this bash timeoutMs and the outer supernova timeoutMs, or split the work. Sleeps and every command in a shell chain share the same limit."
   )), timeoutMs);
-  child.stdout.setEncoding("utf8");
-  child.stderr.setEncoding("utf8");
-  child.stdout.on("data", chunk => { state.stdout = appendCommandOutput(state, state.stdout, chunk); });
-  child.stderr.on("data", chunk => { state.stderr = appendCommandOutput(state, state.stderr, chunk); });
+  captureCommandStream(state, "stdout");
+  captureCommandStream(state, "stderr");
   child.on("error", error => failCommand(state,commandSpawnError(error,argv[0])));
   child.once("exit", (code, signal) => {
     state.processExited = true;

package/src/output/bottleneck.js

@@ -65,7 +65,9 @@ function fitContainer(input, limit) {
   const out = Array.isArray(input) ? [] : { truncated: true };
   const entries = Object.entries(input);
 
-  if (!Array.isArray(input)) entries.sort((a, b) => json(a[1]).length - json(b[1]).length);
+  const lengths = Array.isArray(input) ? null : new Map(entries.map(([key, child]) => [key, json(child).length]));
+
+  if (lengths) entries.sort((a, b) => lengths.get(a[0]) - lengths.get(b[0]));
 
   for (const [key, child] of entries) {
     const used = json(out).length;
@@ -73,7 +75,7 @@ function fitContainer(input, limit) {
     const available = limit - used - overhead;
 
     if (available < 4) break;
-    assignBounded(out, key, fit(child, available));
+    assignBounded(out, key, fit(child, available, lengths?.get(key)));
 
     if (json(out).length > limit) rollbackBounded(out, key);
   }
@@ -81,10 +83,8 @@ function fitContainer(input, limit) {
   return out;
 }
 
-function fit(input, limit) {
-  const serialized = json(input);
-
-  if (serialized.length <= limit) return input;
+function fit(input, limit, encodedLength = json(input).length) {
+  if (encodedLength <= limit) return input;
 
   if (isString(input)) return fitString(input, limit);
 
@@ -99,7 +99,7 @@ function summarizeDetails(value, budget = 2000) {
 
   if (encoded.length <= budget) return encoded;
 
-  return json(fit(JSON.parse(encoded), budget));
+  return json(fit(JSON.parse(encoded), budget, encoded.length));
 }
 
 function spill(fullText, config) {
@@ -222,36 +222,53 @@ function attachTruncation(result, truncated, batch, text, config, maxChars, capp
   attachSpill(result, batch, text, config, maxChars, capped);
 }
 
-export function packageHostResult(raw, config) {
-  const details = detailsOf(raw);
+/** Already materialized batches retain items; never budget them a second time. */
+function attachTypedBatch(result, batch, details) {
+  result.items = batch;
+  result.itemErrors = details.itemErrors ?? [];
 
-  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 (details.sourcePaths) result.sourcePaths = details.sourcePaths;
+}
 
-    if (isString(details?.sourcePath)) result.sourcePath = details.sourcePath;
+function typedHostResult(raw, details) {
+  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 (isString(details?.sourcePath)) result.sourcePath = details.sourcePath;
 
-      if (details.sourcePaths) result.sourcePaths = details.sourcePaths;
-    }
+  if (batch) attachTypedBatch(result, batch, details);
 
-    if (details?.streamed) result.streamed = true;
+  if (details?.streamed) result.streamed = true;
 
-    return result;
-  }
+  return result;
+}
+
+function hasStructuredResult(raw, acceptsStructured) {
+  return acceptsStructured && !hostResultFailed(raw) && raw?.structuredContent !== undefined;
+}
 
+function displayedHostText(raw, batch, structured) {
+  return batch ? "" : structured ? json(raw.structuredContent) : extractRawString(raw);
+}
+
+function boundedStructuredValue(raw, capped) {
+  return capped.truncated ? capped.text : raw.structuredContent;
+}
+
+function boundedHostResult(raw, details, config, acceptsStructured) {
   const maxChars = config.maxCallResultChars ?? 65536;
-  const batch = batchFromDetails(details);
-  const text = batch ? "" : extractRawString(raw);
+  const structured = hasStructuredResult(raw, acceptsStructured);
+  const batch = structured ? undefined : batchFromDetails(details);
+  const text = displayedHostText(raw, batch, structured);
   const capped = truncateChars(text, maxChars, "host-result");
   let truncated = hostTruncated(capped, details);
   const image = hostImage(raw);
   const directoryEntries = directoryEntriesIfFit(image, details, maxChars);
-  const result = { ok: !hostResultFailed(raw), value: hostResultValue(image, directoryEntries, capped), truncated };
+  const result = { ok: !hostResultFailed(raw), value: structured ? boundedStructuredValue(raw, capped) : hostResultValue(image, directoryEntries, capped), truncated };
+
+  // Even a clipped JSON display is already materialized; read must not parse it.
+  if (structured) result.typed = true;
   attachDetails(result, details, batch);
   truncated ||= attachBatch(result, batch, details, maxChars);
   attachTruncation(result, truncated, batch, text, config, maxChars, capped);
@@ -259,4 +276,12 @@ export function packageHostResult(raw, config) {
   return result;
 }
 
+export function packageHostResult(raw, config, acceptsStructured = false) {
+  const details = detailsOf(raw);
+
+  return raw && Object.hasOwn(raw, READ_VALUE)
+    ? typedHostResult(raw, details)
+    : boundedHostResult(raw, details, config, acceptsStructured);
+}
+
 export {packageFinalReturn} from "./final.js";