humanish 0.124.0 → 0.125.0

package/dist/run/live-items.d.ts

@@ -0,0 +1,48 @@
+import type { ActorTraceItem } from "../actors/contract.js";
+import type { RunEvent } from "./bundle.js";
+import { type PreparedOutputRoot } from "./contained-output.js";
+import type { LiveItemsIndex, RunStream } from "./streams.js";
+/** The live actor of a v3 run.json, whose items are in the file `itemsFile` names. */
+export declare const LIVE_ACTOR_SCHEMA = "humanish.live-actor.v2";
+/** The live actor of v1 and v2 run.json, with its items inline. */
+export declare const LIVE_ACTOR_V1_SCHEMA = "humanish.live-actor.v1";
+/** Whether `value` is a live items index naming a live file name and its own generation. */
+export declare function isLiveItemsIndex(value: unknown): value is LiveItemsIndex;
+/**
+ * The items the indexed prefix of a live file holds, or why the bytes do not match the index:
+ * `bytes` must be exactly the indexed byte count, hash to the indexed sha256, and hold the indexed
+ * number of lines, each a JSON object.
+ */
+export declare function liveItemsFromBytes(bytes: Buffer, index: LiveItemsIndex): {
+    items: ActorTraceItem[];
+} | {
+    refused: string;
+};
+/** One run's live files: what each stream position's current generation holds. */
+export interface LiveItemsWriter {
+    /**
+     * `streams` with each running participant's items in its live file: every `liveActor` that
+     * carries `items` becomes humanish.live-actor.v2 with `itemsFile` in their place. A `liveActor`
+     * that already carries `itemsFile` (a bundle built from a run.json this writer wrote) stands for
+     * the list this writer last wrote for its position, and gets the same checks; any other index
+     * (another position's file, an earlier generation, a file this writer did not write) rejects the
+     * write, since the writer can vouch for and scan only its own files. Items past what the participant's current
+     * generation holds are appended, each through publicSandboxView with `sandboxIds`; a new
+     * generation holding the full list starts when appending cannot keep the file equal to the list.
+     * Every byte is on disk when this resolves, so a run.json written after it indexes nothing
+     * missing. Call `published` once run.json naming the returned streams is written: it removes
+     * every superseded generation those streams do not name, including the file of a stream that no
+     * longer carries live items. A generation whose removal fails, or whose write's run.json failed
+     * so `published` never ran, is removed by the next `published`. `events` is the one warn event
+     * the run records once a participant's generation was replaced on two writes in a row, from that
+     * write on; empty until then.
+     */
+    write(streams: readonly RunStream[], sandboxIds: readonly string[]): Promise<{
+        streams: RunStream[];
+        events: RunEvent[];
+        published: () => Promise<void>;
+    }>;
+    /** Remove every live file this writer created, and live/ once empty: after the final run.json. */
+    remove(): Promise<void>;
+}
+export declare function liveItemsWriter(root: PreparedOutputRoot): LiveItemsWriter;

package/dist/run/live-items.js

@@ -0,0 +1,242 @@
+// A running participant's items so far live in an append-only file, so a flush writes only the
+// items recorded since the last one. The file is live/<position>.<generation>.ndjson, one item per
+// line; run.json's liveActor indexes the prefix written so far by line count, byte count and a
+// running sha256. A file only grows. When appending cannot keep what the file holds equal to the
+// participant's list (the list shrank, an earlier item changed, an append failed, a sandbox id
+// the run learned occurs in it), the writer starts the next generation with the full list, and
+// removes the earlier one once run.json names the new one. This module owns that format: the
+// trace loader reads through liveItemsFromBytes, the run writer through liveItemsWriter.
+import { createHash } from "node:crypto";
+import { appendContainedOutputFile, createContainedOutputFile, readContainedPrefix, removeContainedOutputFile, } from "./contained-output.js";
+import { publicSandboxView } from "./sandbox-ids.js";
+import { isNonNegativeSafeInteger, isPositiveSafeInteger, isRecord } from "./type-guards.js";
+/** The live actor of a v3 run.json, whose items are in the file `itemsFile` names. */
+export const LIVE_ACTOR_SCHEMA = "humanish.live-actor.v2";
+/** The live actor of v1 and v2 run.json, with its items inline. */
+export const LIVE_ACTOR_V1_SCHEMA = "humanish.live-actor.v1";
+/** live/<position>.<generation>.ndjson: names the writer gives, by stream position, from 1. */
+const LIVE_FILE = /^live\/([1-9]\d{0,5})\.([1-9]\d{0,8})\.ndjson$/;
+/** Whether `value` is a live items index naming a live file name and its own generation. */
+export function isLiveItemsIndex(value) {
+    if (!isRecord(value) || typeof value.path !== "string")
+        return false;
+    const name = LIVE_FILE.exec(value.path);
+    return (name !== null &&
+        isPositiveSafeInteger(value.generation) &&
+        Number(name[2]) === value.generation &&
+        isNonNegativeSafeInteger(value.items) &&
+        isNonNegativeSafeInteger(value.bytes) &&
+        typeof value.sha256 === "string" &&
+        /^[0-9a-f]{64}$/.test(value.sha256));
+}
+/**
+ * The items the indexed prefix of a live file holds, or why the bytes do not match the index:
+ * `bytes` must be exactly the indexed byte count, hash to the indexed sha256, and hold the indexed
+ * number of lines, each a JSON object.
+ */
+export function liveItemsFromBytes(bytes, index) {
+    if (bytes.length !== index.bytes)
+        return {
+            refused: `${index.path} holds ${bytes.length} bytes and run.json records ${index.bytes}`,
+        };
+    if (createHash("sha256").update(bytes).digest("hex") !== index.sha256)
+        return { refused: `${index.path} does not match the sha256 run.json records for it` };
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return { refused: `${index.path} is not UTF-8 text` };
+    }
+    const lines = text === "" ? [] : text.split("\n");
+    if (lines.length > 0 && lines.pop() !== "")
+        return { refused: `${index.path} does not end its indexed bytes at a line end` };
+    if (lines.length !== index.items)
+        return {
+            refused: `${index.path} holds ${lines.length} items and run.json records ${index.items}`,
+        };
+    const items = [];
+    for (const line of lines) {
+        let item;
+        try {
+            item = JSON.parse(line);
+        }
+        catch {
+            return { refused: `${index.path} holds a line that is not JSON` };
+        }
+        if (!isRecord(item))
+            return { refused: `${index.path} holds a line that is not an item` };
+        items.push(item);
+    }
+    return { items };
+}
+/** The warning for a participant whose live items were written in full on two writes in a row. */
+function rewrittenEvent(stream, position) {
+    return {
+        id: "event-live-items-rewritten",
+        at: stream.liveActor?.updatedAt ?? stream.updatedAt,
+        level: "warn",
+        type: "live-items.rewritten",
+        streamId: stream.id,
+        message: `The live items of ${stream.id} were written again in full on two flushes in a row (live/${position}.<generation>.ndjson). A full write copies every item recorded so far, so as long as this goes on, each flush takes longer and writes more to disk than the one before. It happens when an item already written was replaced or removed, or an append to the live file failed. Check that the disk holding the run has free space and no write errors. If the disk is fine, report this run: the participant's recorder is replacing items it already recorded.`,
+    };
+}
+/** Each item as its line in a live file, scrubbed of the run's raw sandbox ids. */
+function itemLines(items, sandboxIds) {
+    return Buffer.from(items.map((item) => `${JSON.stringify(publicSandboxView(item, sandboxIds))}\n`).join(""), "utf8");
+}
+/**
+ * The list behind `index` when it is the index of `held`, the generation the writer last wrote for
+ * stream `position`; any other index throws.
+ */
+function heldItems(held, position, index) {
+    if (held === undefined ||
+        index.path !== held.path ||
+        index.items !== held.items ||
+        index.bytes !== held.bytes ||
+        index.sha256 !== held.hash.copy().digest("hex"))
+        throw new Error(`The live actor of stream ${position} indexes ${index.path}, which is not the file this run last wrote for that stream. Pass the participant's items instead of an index.`);
+    return held.written;
+}
+export function liveItemsWriter(root) {
+    const current = new Map();
+    /** The highest generation started at each position, so a failed start never reuses a name. */
+    const started = new Map();
+    /** Positions whose last append failed: their next write starts a new generation. */
+    const appendFailed = new Set();
+    const created = new Set();
+    /** Generations no current index names: removed once a published run.json names none of them. */
+    const superseded = new Set();
+    let knownIds = new Set();
+    /** Positions whose generation the previous write replaced, and the current write. */
+    let replacedBefore = new Set();
+    let replaced = new Set();
+    let rewritten;
+    const startGeneration = async (position, items, sandboxIds) => {
+        const generation = (started.get(position) ?? 0) + 1;
+        started.set(position, generation);
+        const path = `live/${position}.${generation}.ndjson`;
+        const bytes = itemLines(items, sandboxIds);
+        created.add(path);
+        await createContainedOutputFile(root, path, bytes.toString("utf8"));
+        const previous = current.get(position);
+        if (previous !== undefined) {
+            superseded.add(previous.path);
+            replaced.add(position);
+        }
+        appendFailed.delete(position);
+        const next = {
+            path,
+            generation,
+            written: items,
+            items: items.length,
+            bytes: bytes.length,
+            hash: createHash("sha256").update(bytes),
+        };
+        current.set(position, next);
+        return next;
+    };
+    /**
+     * Whether the generation can take an append: the list did not shrink, every item it holds is the
+     * object it wrote, its last append did not fail, and no id the run learned since occurs in it.
+     */
+    const appendable = async (position, held, items, learned) => {
+        if (appendFailed.has(position) || items.length < held.items)
+            return false;
+        for (let index = 0; index < held.items; index += 1)
+            if (items[index] !== held.written[index])
+                return false;
+        if (learned.length === 0)
+            return true;
+        const read = await readContainedPrefix(root, held.path, held.bytes);
+        return (read.status === "read" &&
+            read.bytes.length === held.bytes &&
+            !learned.some((id) => id.length > 0 && read.bytes.includes(id)));
+    };
+    const writeItems = async (position, items, sandboxIds, learned) => {
+        const held = current.get(position);
+        if (held === undefined || !(await appendable(position, held, items, learned)))
+            return startGeneration(position, items, sandboxIds);
+        if (items.length > held.items) {
+            const bytes = itemLines(items.slice(held.items), sandboxIds);
+            try {
+                await appendContainedOutputFile(root, held.path, bytes, held.bytes);
+            }
+            catch {
+                // What the file holds past its index is unknown now; the full list starts over.
+                appendFailed.add(position);
+                return startGeneration(position, items, sandboxIds);
+            }
+            held.hash.update(bytes);
+            held.bytes += bytes.length;
+            held.items = items.length;
+        }
+        held.written = items;
+        return held;
+    };
+    return {
+        async write(streams, sandboxIds) {
+            const learned = sandboxIds.filter((id) => !knownIds.has(id));
+            replaced = new Set();
+            const live = new Set();
+            const written = [];
+            for (const [index, stream] of streams.entries()) {
+                const position = index + 1;
+                const liveActor = stream.liveActor;
+                // A live actor written as its index stands for what its generation holds, so an id learned
+                // now is looked for in that generation too before the ids count as known.
+                const items = Array.isArray(liveActor?.items)
+                    ? liveActor.items
+                    : liveActor?.itemsFile === undefined
+                        ? undefined
+                        : heldItems(current.get(position), position, liveActor.itemsFile);
+                if (liveActor === undefined || items === undefined) {
+                    written.push(stream);
+                    continue;
+                }
+                live.add(position);
+                const held = await writeItems(position, items, sandboxIds, learned);
+                const { items: _items, ...summary } = liveActor;
+                const itemsFile = {
+                    path: held.path,
+                    generation: held.generation,
+                    items: held.items,
+                    bytes: held.bytes,
+                    sha256: held.hash.copy().digest("hex"),
+                };
+                written.push({
+                    ...stream,
+                    liveActor: { ...summary, schema: LIVE_ACTOR_SCHEMA, itemsFile },
+                });
+            }
+            // Known once every current generation was checked for them; a write that threw rechecks.
+            knownIds = new Set([...knownIds, ...sandboxIds]);
+            for (const [position, held] of current)
+                if (!live.has(position)) {
+                    superseded.add(held.path);
+                    current.delete(position);
+                }
+            // Replaced on two writes in a row: each flush rewrites the whole list, as before live files.
+            const churning = [...replaced].find((position) => replacedBefore.has(position));
+            if (rewritten === undefined && churning !== undefined)
+                rewritten = rewrittenEvent(streams[churning - 1], churning);
+            replacedBefore = replaced;
+            const named = new Set(written.map((stream) => stream.liveActor?.itemsFile?.path));
+            return {
+                streams: written,
+                events: rewritten === undefined ? [] : [rewritten],
+                published: async () => {
+                    // A removal that fails stays pending for the next published run.json.
+                    for (const path of superseded)
+                        if (!named.has(path))
+                            await removeContainedOutputFile(root, path).then(() => superseded.delete(path), () => undefined);
+                },
+            };
+        },
+        async remove() {
+            for (const path of created)
+                await removeContainedOutputFile(root, path).catch(() => { });
+            await removeContainedOutputFile(root, "live").catch(() => { });
+        },
+    };
+}

package/dist/run/locate.d.ts

@@ -40,6 +40,16 @@ export declare function readSafeRunArtifact(runPaths: PreparedRunArtifactPaths,
 /** readSafeRunArtifact's bytes, or null for any file it does not read. */
 export declare function readSafeRunArtifactBytes(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<Buffer | null>;
 export declare function readSafeRunArtifactJson(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<unknown>;
+/**
+ * A run's bundle as `humanish verify` reads it, for a reader outside humanish: run.json of run
+ * `runInput` (a run id, or `latest`) under `cwdInput`'s `.humanish/runs/`, with every participant's
+ * trace file and, while the run is in progress, live file joined, so each stream has its
+ * `actor.items`, its screenshot entries and its `liveActor.items` as a v1 run.json held them. It
+ * reads run bundles v1, v2 and v3. Each file must match the index run.json records for it (path,
+ * size, sha256, item count); one that does not throws an Error named `StreamTraceRefusedError`
+ * that names the participant. Resolves to null when there is no such run, or its run.json is not
+ * a run bundle. `bundlePath` is run.json relative to `cwdInput`, `runDir` the run folder.
+ */
 export declare function loadRunBundle(cwdInput: string, runInput: string): Promise<{
     bundle: RunBundle;
     bundlePath: string;

package/dist/run/locate.js

@@ -101,6 +101,16 @@ export async function readSafeRunArtifactJson(runPaths, relativePath) {
         return null;
     }
 }
+/**
+ * A run's bundle as `humanish verify` reads it, for a reader outside humanish: run.json of run
+ * `runInput` (a run id, or `latest`) under `cwdInput`'s `.humanish/runs/`, with every participant's
+ * trace file and, while the run is in progress, live file joined, so each stream has its
+ * `actor.items`, its screenshot entries and its `liveActor.items` as a v1 run.json held them. It
+ * reads run bundles v1, v2 and v3. Each file must match the index run.json records for it (path,
+ * size, sha256, item count); one that does not throws an Error named `StreamTraceRefusedError`
+ * that names the participant. Resolves to null when there is no such run, or its run.json is not
+ * a run bundle. `bundlePath` is run.json relative to `cwdInput`, `runDir` the run folder.
+ */
 export async function loadRunBundle(cwdInput, runInput) {
     const cwd = path.resolve(cwdInput);
     const runPaths = await resolveRunPath(cwd, runInput).catch(() => null);

package/dist/run/run.d.ts

@@ -92,7 +92,8 @@ interface Run {
     /** The literal values the route scrubs from this run's evidence; a value found later is added here. */
     readonly secrets: RunSecrets;
     /**
-     * Publish an in-progress bundle: run.json, review.json, review.md, events.ndjson and
+     * Publish an in-progress bundle: each running participant's new items appended to its live file
+     * (src/run/live-items.ts), then run.json, review.json, review.md, events.ndjson and
      * observer/observer-data.json, plus the latest pointer until one pointer write has succeeded,
      * so a live run is `latest` from its first snapshot and a later flush never takes the pointer
      * back from a newer run. status.json stays running. Writes are serialized with each other and
@@ -116,7 +117,7 @@ interface Run {
     /**
      * The one final publication: run.json with `outcome` set from `outcome`, then the status
      * outcome copied from it, then review.json, review.md, events.ndjson,
-     * observer/observer-data.json, and last the latest pointer. The status goes after run.json so
+     * observer/observer-data.json, then the removal of the live files, and last the latest pointer. The status goes after run.json so
      * the index never gets ahead of the evidence, and the pointer goes last so `latest` never
      * selects a run whose projections are incomplete. Every projection reads the outcome, so none
      * shows a pass for a run whose ok is false. Rejects before writing on a second call, after the

package/dist/run/run.js

@@ -13,7 +13,8 @@ import {} from "./results.js";
 import { createRunArtifactPaths, validatePreparedRunArtifactPaths, } from "./paths.js";
 import { registerActiveRun } from "./active-runs.js";
 import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./contained-output.js";
-import { scrubRunSandboxIds, withPublicSandboxIds } from "./sandbox-ids.js";
+import { liveItemsWriter } from "./live-items.js";
+import { publicSandboxView, readRunSandboxIds, scrubRunSandboxIds } from "./sandbox-ids.js";
 import { RunSecrets } from "./secrets.js";
 import { RUN_STATUS_FILE, beginRunStatus, runStatusOutcome, } from "./status.js";
 import { readRunJsonIfExists, runJsonValue } from "./locate.js";
@@ -117,6 +118,28 @@ function observerTarget(options) {
             render: options.observer.render ?? renderObserver,
         };
 }
+/**
+ * run.json for `bundle`, written after every live file and trace file it indexes, then the removal
+ * of the live files it no longer names. Returns the bundle the review and the projections read:
+ * raw sandbox ids scrubbed, each finished trace inline, each running participant's items as the
+ * index of its live file, and the live files' warning among the events. Live items are scrubbed
+ * as they are appended, so the scrub of the bundle no longer walks them.
+ */
+async function writeRunJson(paths, liveItems, bundle) {
+    const sandboxIds = await readRunSandboxIds(paths);
+    const live = await liveItems.write(bundle.streams, sandboxIds);
+    const events = [
+        ...bundle.events.filter((event) => !live.events.some((mine) => mine.id === event.id)),
+        ...live.events,
+    ];
+    const publicBundle = publicSandboxView({ ...bundle, streams: live.streams, events }, sandboxIds);
+    const split = splitStreamTraces(publicBundle);
+    for (const file of split.files)
+        await writeContainedOutputFile(paths, file.path, file.bytes);
+    await writeContainedOutputFile(paths, RUN_BUNDLE_FILE, json(split.bundle), "utf8");
+    await live.published();
+    return publicBundle;
+}
 function runPublisher(args) {
     const { options, runId, createdAt, paths, runStatus, now, admit, participantsRan } = args;
     const observer = observerTarget(options);
@@ -161,24 +184,20 @@ function runPublisher(args) {
         await writePreparedRunLatestPointer(paths, json(pointer), "utf8");
         pointerWritten = true;
     };
+    // Each running participant's items so far, appended to its live file as the flushes arrive.
+    const liveItems = liveItemsWriter(paths);
     /** run.json with its outcome, then `afterBundle`, then the review and projections. */
     const writeBundleFiles = async (bundle, outcome, afterBundle) => {
         await validatePreparedRunArtifactPaths(paths);
         // The run owns `outcome`: a bundle read back from disk keeps none of its own.
         const { outcome: _previous, ...evidence } = bundle;
         const recorded = interrupted ?? outcome;
-        const publicBundle = await withPublicSandboxIds(paths, {
+        const publicBundle = await writeRunJson(paths, liveItems, {
             ...evidence,
             events: withRunEvents(evidence.events),
             cwd: PUBLIC_TARGET_CWD,
             ...(recorded === undefined ? {} : { outcome: recorded }),
         });
-        // Each trace file first, so run.json never indexes a file that is not yet written. The review
-        // and the Observer data below read the whole in-memory bundle.
-        const split = splitStreamTraces(publicBundle);
-        for (const file of split.files)
-            await writeContainedOutputFile(paths, file.path, file.bytes);
-        await writeContainedOutputFile(paths, RUN_BUNDLE_FILE, json(split.bundle), "utf8");
         await afterBundle(publicBundle);
         // The run writes its own status.json; one it refuses renders as a missing one does.
         const status = recorded === undefined
@@ -202,6 +221,8 @@ function runPublisher(args) {
     });
     const publish = async (bundle, outcome) => {
         await writeBundleFiles(bundle, finishedOutcome(outcome), (publicBundle) => runStatus.finish(runStatusOutcome(publicBundle)));
+        // The final run.json indexes each finished trace, so the live files are journal no reader needs.
+        await liveItems.remove();
         await scrubRunSandboxIds(paths);
         await writePointer();
         let current = { ok: outcome.ok, execution: outcome.execution };

package/dist/run/sandbox-ids.d.ts

@@ -30,11 +30,6 @@ export declare function holdsKeyedSandboxId(file: string, text: string): boolean
  * caller would otherwise write or grade a run's files without the ids it may hold.
  */
 export declare function readRunSandboxIds(root: PreparedOutputRoot): Promise<string[]>;
-/**
- * `value` as a run writes it: raw sandbox ids stay in the run's sandbox-receipts.ndjson, and the
- * file names each by marker and digest.
- */
-export declare function withPublicSandboxIds<T>(root: PreparedOutputRoot, value: T): Promise<T>;
 /**
  * The bytes of `file` with each raw id replaced by its label: the same buffer when none occurs, or
  * when the bytes are not the plain text verify and export read as text.

package/dist/run/sandbox-ids.js

@@ -115,13 +115,6 @@ export async function readRunSandboxIds(root) {
     }
     return [...new Set([...journaled, ...appendedSandboxIds(root)])];
 }
-/**
- * `value` as a run writes it: raw sandbox ids stay in the run's sandbox-receipts.ndjson, and the
- * file names each by marker and digest.
- */
-export async function withPublicSandboxIds(root, value) {
-    return publicSandboxView(value, await readRunSandboxIds(root));
-}
 /**
  * The bytes of `file` with each raw id replaced by its label: the same buffer when none occurs, or
  * when the bytes are not the plain text verify and export read as text.

package/dist/run/stream-trace.d.ts

@@ -22,10 +22,12 @@ export declare function splitStreamTraces(bundle: RunBundle): {
 };
 /**
  * Where a loader reads trace files from: the bytes at a run-relative path, at most `maxBytes`, or
- * why it could not. Prepared run paths read through the contained reader; the Observer server
- * passes a reader over its pinned run folder.
+ * why it could not. With `length`, the first `length` bytes, or all of a shorter file: a live file
+ * grows past what run.json indexes, and the loader reads only the indexed prefix. Prepared run
+ * paths read through the contained reader; the Observer server passes a reader over its pinned run
+ * folder.
  */
-export type TraceFileReader = (relativePath: string, maxBytes: number) => Promise<{
+export type TraceFileReader = (relativePath: string, maxBytes: number, length?: number) => Promise<{
     bytes: Buffer;
 } | {
     refused: string;
@@ -39,21 +41,27 @@ export type TraceFileReader = (relativePath: string, maxBytes: number) => Promis
  * actor, two participants indexing one file) are loadStreamTraces'.
  */
 export declare function loadStreamTrace(runPaths: PreparedOutputRoot, stream: RunStream, maxBytes?: number): Promise<RunStream>;
+interface LoadedTraces {
+    bundle: RunBundle;
+    refused: StreamTraceRefusedError[];
+}
 /**
  * Every stream of the bundle loaded through loadStreamTrace, one file at a time, and the refusal
  * of each stream that could not be (see bundleRefusal for the rules that need the whole bundle).
  * Each refused stream is kept as run.json holds it; a reader that shows the run passes the result
  * to displayedTraces. `source` is the run's prepared paths, or a TraceFileReader. `onTrace`
- * receives each trace file's path and the bytes the stream was joined from, after they matched
- * the index, so a caller scans exactly what it reads.
+ * receives each trace and live file's path and the bytes the stream was joined from, after they
+ * matched the index, so a caller scans exactly what it reads.
+ *
+ * A live file that cannot be read may have been removed by the writer after `bundle` was read: it
+ * removes a superseded generation once run.json names the next one, and every live file once the
+ * run finished. The loader then reads run.json again, once, through the same reader, and loads
+ * that bundle instead when it is a run bundle of the same run.
  */
 export declare function loadStreamTraces(source: PreparedOutputRoot | TraceFileReader, bundle: RunBundle, options?: {
     maxBytes?: number;
     onTrace?: (path: string, bytes: Buffer) => void;
-}): Promise<{
-    bundle: RunBundle;
-    refused: StreamTraceRefusedError[];
-}>;
+}): Promise<LoadedTraces>;
 /**
  * A loaded bundle as a reader that shows a run presents it. A refused stream keeps run.json's
  * summary, shows none of the items run.json or a file supplied for it (its actor's items, its
@@ -66,3 +74,4 @@ export declare function displayedTraces(loaded: {
 }): RunBundle;
 /** The bundle with every stream loaded; the first refusal throws. */
 export declare function loadRunTraces(source: PreparedOutputRoot | TraceFileReader, bundle: RunBundle, maxBytes?: number): Promise<RunBundle>;
+export {};