humanish 0.122.0 → 0.123.0

package/CHANGELOG.md

@@ -8,6 +8,22 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.123.0: Run bundle v2 writes each trace once, bundle size estimate (2026-10-12)
+
+humanish 0.123.0 writes each participant's trace once, outside run.json, so long studies stay
+within the bundle's size limits, and estimates a study's bundle before it runs. Run bundles are now
+`humanish.run-bundle.v2`: a participant's trace items live only in its trace file
+(`actor.json`, `actors/<stream>.json` or `actor-<surface>.json`), and run.json indexes each one by
+path, size and sha256. On a synthetic 8-participant, 1,000-turn run, run.json fell from 17 MB to
+74 KB. Every reader loads traces through one loader that checks the index and refuses a missing,
+altered or shared trace; a refused trace shows as evidence unavailable, and an unfinished run
+grades `local_only`. Bundles from earlier versions still load unchanged; npm 0.122.0 and earlier
+refuse a v2 bundle by name. `study check` and `run` estimate the bundle's size and file count and
+warn before any sandbox is created when it may pass the analysis or verify limit, and the
+public-safety scan's file limit grows with the number of participants.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.123.0)
+
 ## 0.122.0: Participants end on the clock, a harness error ends only its participant (2026-10-12)
 
 humanish 0.122.0 lets a participant end at a scheduled time and keeps one participant's harness

package/CONTEXT.md

@@ -12,7 +12,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | Term                | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Where it lives in the code                                                                                                                                                                                                                                                                                                                                                                                  |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | study               | What a user designs and runs: one YAML file that declares the subject, the actor, the participants and the caps. The file lives at `humanish/studies/<id>.yaml` with schema `humanish.study.v3`, read by `humanish study` and `--study`. humanish refuses a 0.107 `humanish.lab.v2` file, and `humanish migrate` converts it (second table).                                                                                                                                                                                          | `src/study/`; `StudyConfig` in `src/study/types.ts`, parsed by `parseStudy` in `src/study/config.ts`                                                                                                                                                                                                                                                                                                        |
-| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v1`) as the source of truth.                                                                                                                                                                                                                                                                                                                                                                                                      | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                              |
+| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v2`) as the source of truth and each participant's trace in its own file.                                                                                                                                                                                                                                                                                                                                                         | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                              |
 | dry run             | A run with no live participant, from `--dry-run` or `mode: dry-run`. humanish writes a synthetic run bundle, review and Observer with no browser, model, keys or provider spend, and tests no product behavior. The `preview` route only dry-runs; "preview" names that route and nothing else.                                                                                                                                                                                                                                       | `runDryRun` in `src/run/dry-run.ts`; `resolveStudyDryRun` in `src/study/plan.ts`                                                                                                                                                                                                                                                                                                                            |
 | participant         | One simulated person, or agent, taking part in a study. The planner builds each one's record (id, persona id, assignment, labels and the route's own fields). Shared-world participants resolve the plan's records; computer-use participants rebuild the same records from the study config with `computerUseParticipants` (`src/study/plan-participants.ts`) and resolve those. `ResolvedParticipant` adds the bundle ids, persona and prompt. `run.json` records each one as a `simulations[]` entry with one or more `streams[]`. | `ResolvedParticipant` in `src/run/participant.ts`; the planned records in `src/study/plan-participants.ts`. Computer-use and shared-world participants run a `DesktopParticipantRun` (`src/routes/computer-use/types.ts`). The terminal session (`src/routes/terminal/session.ts`), scripted surfaces (`src/routes/scripted/plan.ts`) and fixture simulations (`src/run/dry-run.ts`) still build their own. |
 | persona             | Who a participant is: traits, background, device. `humanish/personas/<id>.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `src/study/persona.ts`, `src/study/persona-resolve.ts`                                                                                                                                                                                                                                                                                                                                                      |

package/README.md

@@ -1,12 +1,23 @@
 # humanish
 
-Synthetic user research for apps, CLIs, and agent-facing product flows. AI participants with a persona and a task use your app on real desktops, and each run leaves evidence you can verify: what they did, where they got stuck, and what it cost.
+[![npm version](https://img.shields.io/npm/v/humanish)](https://www.npmjs.com/package/humanish) [![npm downloads per month](https://img.shields.io/npm/dm/humanish)](https://www.npmjs.com/package/humanish) [![CI status on main](https://img.shields.io/github/actions/workflow/status/danielgwilson/humanish/ci.yml?branch=main&label=CI)](https://github.com/danielgwilson/humanish/actions/workflows/ci.yml?query=branch%3Amain) [![License: MIT](https://img.shields.io/npm/l/humanish)](LICENSE) [![Node.js version](https://img.shields.io/node/v/humanish)](https://nodejs.org/)
 
-[![The Observer grid of a saved eight-participant study: eight desktops in one multiplayer lobby, each tile a participant's live screen](https://humanish.dev/runs/lobby-0927/poster.jpg)](https://humanish.dev/demo)
+Synthetic user research for apps, CLIs, and agent-facing product flows. AI participants with a persona and a task use your app on real desktops, and each run leaves evidence you can verify: what they did, where they got stuck, and what it cost.
 
-**[Watch a saved run](https://humanish.dev/demo).** Eight synthetic participants joined one
-lobby of a multiplayer game on its live deployment, each on its own hosted desktop. The page
-replays the real Observer; nothing runs from it.
+<a href="https://humanish.dev/demo">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://humanish.dev/runs/lobby-0927/observer-grid-dark.webp">
+    <img alt="The humanish Observer replaying a saved study five minutes into its 13-minute recording: a grid of eight participants' desktops in a multiplayer movie-guessing game, seven in the same round and one held at the join page, under tabs for 8 participants and 7 findings" src="https://humanish.dev/runs/lobby-0927/observer-grid-light.webp">
+  </picture>
+</a>
+
+**[Watch the replay](https://humanish.dev/demo).** The image is the Observer partway through a
+saved study. Eight synthetic participants joined one lobby of a multiplayer movie-guessing game
+on its live deployment, each on its own hosted desktop, and each tile shows one participant's
+screen at the same moment of the recording. Six reached the final standings. Two were blocked,
+among them Player six, who arrived after the game started and is still on the join page. The
+Findings tab holds the seven findings the analysis wrote. The demo page replays this run in the
+Observer, and nothing runs from it.
 
 ## Learn how a study works
 
@@ -19,6 +30,14 @@ disposable browser VM on your machine. On the computer-use route a model drives
 participant: every turn it reads a screenshot and answers with mouse and keyboard actions, until
 the participant finishes, gets stuck or reaches a limit.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://humanish.dev/runs/lobby-0927/observer-player-dark.webp">
+  <img alt="The Observer with one participant open: its desktop during a round of a movie-guessing game, replay controls and a filmstrip of captures below, and on the right its trace, with the participant's reasoning and each TAB and ENTER keypress" src="https://humanish.dev/runs/lobby-0927/observer-player-light.webp">
+</picture>
+
+Player four from the run above, a keyboard-only participant: its screen, and beside it each
+keypress and the reasoning it wrote before acting.
+
 The run writes its evidence to gitignored `.humanish/runs/<run id>/`: screenshots, every
 action, each participant's report and the estimated cost. The Observer replays it,
 `humanish review` prints the findings of the analysis that follows a live run, and
@@ -26,6 +45,14 @@ action, each participant's report and the estimated cost. The Observer replays i
 [How a study works](https://humanish.dev/docs/concepts) walks through one annotated study file,
 and the [study file reference](https://humanish.dev/docs/study-files) lists every field.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://humanish.dev/runs/lobby-0927/observer-findings-dark.webp">
+  <img alt="The Observer's Findings tab: the first of seven findings, that three participants found keyboard guessing hard to track and one stopped mid-game, with the analysis's summary, what to check next, a cited capture and the timeline of evidence moments behind it" src="https://humanish.dev/runs/lobby-0927/observer-findings-light.webp">
+</picture>
+
+The first of the seven findings the analysis wrote for the same run, with the evidence moments
+it cites.
+
 ## Try it without keys
 
 In a project directory, with Node.js 22.19 or newer:
@@ -308,7 +335,7 @@ and the library exports.
 - Breaking changes ship together in one minor release. Its release notes carry a migration
   table: each old form, its new form, and the change to make.
 - The study file and the run bundle carry versioned schemas, `humanish.study.v3` and
-  `humanish.run-bundle.v1`. A breaking change to either one bumps its version.
+  `humanish.run-bundle.v2`. A breaking change to either one bumps its version.
 
 Pin the exact version in `package.json` and read [CHANGELOG.md](CHANGELOG.md) before upgrading.
 

package/dist/analysis/automatic.js

@@ -4,6 +4,7 @@ import {} from "../run/bundle.js";
 import { refreshObserver, analyzeRun, readCompletedAnalysisSource, resolveAnalysisRun, } from "./service.js";
 import { preferLargerAnalysisOutput, ANALYSIS_PROMPT_VERSION } from "./execute.js";
 import { captureEvidence } from "./evidence.js";
+import { loadRunTraces } from "../run/stream-trace.js";
 import { hashAnalysisValue } from "./validation.js";
 import { refusedCost } from "./admission.js";
 import { claimAutomaticAnalysis, readAutomaticAnalysisPrepared, requestAutomaticAnalysisCancellationPrepared, } from "./job.js";
@@ -88,7 +89,7 @@ async function readAutomaticSource(cwd, prepared, configInput, deps, hasKey) {
     let config = configInput;
     try {
         const bytes = await readCompletedAnalysisSource(cwd, prepared);
-        const bundle = JSON.parse(bytes.toString("utf8"));
+        const bundle = await loadRunTraces(prepared, JSON.parse(bytes.toString("utf8")));
         if (bundle.streams.some((stream) => stream.actor?.stopCause === "harness_aborted"))
             return skipped("AUTOMATIC_ANALYSIS_ACTOR_CANCELLED");
         const participantEvidence = hasParticipantEvidence(bundle);

package/dist/analysis/evidence.js

@@ -3,7 +3,8 @@ import { createHash } from "node:crypto";
 import { screenshotEvidenceError } from "../evidence/image.js";
 import { runIdOf } from "../run/paths.js";
 import { isRecord } from "../run/type-guards.js";
-import { RUN_BUNDLE_FILE } from "../run/bundle.js";
+import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, } from "../run/bundle.js";
+import { loadStreamTraces } from "../run/stream-trace.js";
 import { ACTION_CAPTURE_VERSION, } from "./types.js";
 import { digestAnalysisInput, hashAnalysisValue, validateAnalysisInputMetadata, } from "./validation.js";
 import { boundedText, fairShares, hasUnmappedCaptures, participantAssignment, participantSource, sourceEntries, sourceOrder, impressionEventIds, } from "./evidence-sources.js";
@@ -29,7 +30,7 @@ function parseSource(prepared, bytes) {
         throw new Error("ANALYSIS_SOURCE_TOO_LARGE");
     const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
     if (!isRecord(value) ||
-        value.schema !== "humanish.run-bundle.v1" ||
+        (value.schema !== RUN_BUNDLE_SCHEMA && value.schema !== RUN_BUNDLE_V1_SCHEMA) ||
         value.runId !== runIdOf(prepared) ||
         !Array.isArray(value.streams) ||
         value.streams.length > EVIDENCE_LIMITS.participants ||
@@ -49,24 +50,8 @@ function parseSource(prepared, bytes) {
             throw new Error("ANALYSIS_SOURCE_INVALID");
         }
         ids.add(stream.id);
-        const actor = stream.actor;
-        if (actor !== undefined &&
-            (!isRecord(actor) || !Array.isArray(actor.items) || actor.items.length > 100000)) {
+        if (stream.actor !== undefined && !isRecord(stream.actor))
             throw new Error("ANALYSIS_SOURCE_INVALID");
-        }
-        const eventIds = new Set();
-        for (const item of isRecord(actor) ? actor.items : []) {
-            if (!isRecord(item) ||
-                typeof item.id !== "string" ||
-                item.id.length === 0 ||
-                item.id.length > 256 ||
-                eventIds.has(item.id) ||
-                typeof item.kind !== "string" ||
-                typeof item.title !== "string" ||
-                (item.text !== undefined && typeof item.text !== "string"))
-                throw new Error("ANALYSIS_SOURCE_INVALID");
-            eventIds.add(item.id);
-        }
     }
     for (const event of value.events) {
         if (!isRecord(event) ||
@@ -77,6 +62,41 @@ function parseSource(prepared, bytes) {
     }
     return value;
 }
+/**
+ * run.json's bundle with each stream's trace loaded. The source limit applies to each trace file
+ * as it does to run.json; run.json's digest, which the analysis record binds, binds each trace's
+ * sha256.
+ */
+async function readSource(prepared, bytes, traceBytes) {
+    const stored = parseSource(prepared, bytes);
+    if (stored.streams.some((stream) => (stream.trace?.bytes ?? 0) > traceBytes))
+        throw new Error("ANALYSIS_SOURCE_TOO_LARGE");
+    const loaded = await loadStreamTraces(prepared, stored, { maxBytes: traceBytes });
+    if (loaded.refused.length > 0)
+        throw new Error("ANALYSIS_SOURCE_INVALID");
+    for (const stream of loaded.bundle.streams)
+        validateTraceItems(stream.actor);
+    return loaded.bundle;
+}
+function validateTraceItems(actor) {
+    if (actor !== undefined &&
+        (!isRecord(actor) || !Array.isArray(actor.items) || actor.items.length > 100000)) {
+        throw new Error("ANALYSIS_SOURCE_INVALID");
+    }
+    const eventIds = new Set();
+    for (const item of isRecord(actor) ? actor.items : []) {
+        if (!isRecord(item) ||
+            typeof item.id !== "string" ||
+            item.id.length === 0 ||
+            item.id.length > 256 ||
+            eventIds.has(item.id) ||
+            typeof item.kind !== "string" ||
+            typeof item.title !== "string" ||
+            (item.text !== undefined && typeof item.text !== "string"))
+            throw new Error("ANALYSIS_SOURCE_INVALID");
+        eventIds.add(item.id);
+    }
+}
 /** Select once from retained source. Models receive no filesystem or network resolver. */
 export async function captureEvidence(prepared, bundleBytes, requested = {}) {
     const limits = { ...EVIDENCE_LIMITS, ...requested };
@@ -92,7 +112,7 @@ export async function captureEvidence(prepared, bundleBytes, requested = {}) {
     const current = await readBoundedFile(prepared, RUN_BUNDLE_FILE, limits.sourceBytes);
     if (!current || !current.equals(bundleBytes))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
-    const bundle = parseSource(prepared, bundleBytes);
+    const bundle = await readSource(prepared, bundleBytes, limits.sourceBytes);
     const captureVersion = ACTION_CAPTURE_VERSION;
     if (bundle.streams.some((stream) => stream.liveActor !== undefined || UNFINISHED_STREAM_STATUSES.has(stream.status))) {
         throw new Error("ANALYSIS_RUN_UNFINISHED");
@@ -393,7 +413,7 @@ function packEvidence(selected, packings, textByEntry, evidence, images) {
 export async function validateAnalysisEvidence(prepared, artifact, bundleBytes) {
     if (artifact.captureVersion !== undefined && artifact.captureVersion !== ACTION_CAPTURE_VERSION)
         throw new Error("ANALYSIS_CAPTURE_VERSION_INVALID");
-    const bundle = parseSource(prepared, bundleBytes);
+    const bundle = await readSource(prepared, bundleBytes, EVIDENCE_LIMITS.sourceBytes);
     if (artifact.runId !== bundle.runId || artifact.sourceRunSha256 !== sha256(bundleBytes))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
     const included = new Set(artifact.coverage.includedStreamIds);

package/dist/cli/commands/study-run.js

@@ -84,7 +84,14 @@ export async function runStudyCommand(args) {
     // the keys its plan reads. This comes after the option refusals above, which read no key, and
     // before the route's CLI setup and prepareStudy, which do.
     if (resolveStudyDryRun(config, args.options.dryRun, true) === false) {
-        const announced = announcedKeyNames(config, args.options);
+        const planned = planStudy(config, { cwd: args.options.cwd, dryRun: false });
+        // The plan's warnings, such as a bundle estimated past a limit, before anything is created.
+        // The study file's own were printed above.
+        if (planned.ok)
+            for (const warning of planned.planned.plan.warnings ?? [])
+                if (!resolved.warnings.includes(warning))
+                    warnAndQueue(args.command, args.io, warning);
+        const announced = announcedKeyNames(config, args.options, planned);
         await discoverCliKeys({
             io: args.io,
             cwd: args.options.cwd,
@@ -150,10 +157,9 @@ export async function runStudyCommand(args) {
  * change who runs, not which keys. Undefined, so every fill is printed, when a scorer is declared,
  * since its host code may read any key, and when the study does not plan.
  */
-function announcedKeyNames(config, options) {
+function announcedKeyNames(config, options, planned) {
     if (options.scorer !== undefined || config.review?.scorer !== undefined)
         return undefined;
-    const planned = planStudy(config, { cwd: options.cwd, dryRun: false });
     return planned.ok ? keyNamesOf(planned.planned.plan) : undefined;
 }
 /** Each route's CLI setup. It returns undefined when it has already written its own result. */

package/dist/feedback/derivative-text.d.ts

@@ -0,0 +1,12 @@
+import type { RunBundle } from "../run/bundle.js";
+/** A source file's path and bytes. */
+interface TextFile {
+    path: string;
+    bytes: Buffer;
+}
+export declare function jsonBytes(value: unknown): Buffer;
+export declare function transformText(file: TextFile, imagePaths: ReadonlySet<string>): Buffer;
+export declare function assertRewritableNumbers(json: string): void;
+/** The loaded source bundle as the copy records it: screenshots declared and labelled blurred. */
+export declare function derivedBundle(bundle: RunBundle, imagePaths: ReadonlySet<string>): RunBundle;
+export {};

package/dist/feedback/derivative-text.js

@@ -0,0 +1,130 @@
+// How a redacted copy rewrites a run's text: screenshots declared blurred, sandbox ids redacted,
+// inline images and secret-shaped text refused. src/feedback/export-bundle.ts copies the files.
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { ACTOR_TRACE_SCHEMA } from "../actors/contract.js";
+import { containsSensitive, redactSandboxIds } from "../evidence/redaction.js";
+import { decodeEscapes, readingsOf } from "../evidence/encoded-text.js";
+import { readPlainText } from "../evidence/plain-text.js";
+export function jsonBytes(value) {
+    return Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+}
+function assertNoInlineRaster(text) {
+    // Decode the escapes verify decodes (decodeEscapes) before checking. Unknown embedded bytes are
+    // refused: copying a text extension must not smuggle untransformed pixels.
+    if (readingsOf(text).some(containsSensitive))
+        throw new Error("Decoded text contains a secret-shaped value or private path; export refused.");
+    const decoded = decodeEscapes(text);
+    if (/data\s*:\s*(?:image\/|application\/|text\/|[^,\s]*;base64,|,)/i.test(decoded) ||
+        /iVBORw0KGgo|\/9j\/[A-Za-z0-9+/]|R0lGOD|UklGR[A-Za-z0-9+/]{4}|<svg\b/i.test(decoded)) {
+        throw new Error("Text contains an inline image/data payload; embedded raster redaction is unsupported.");
+    }
+}
+function decodeText(file) {
+    const decoded = readPlainText(file.bytes);
+    if (!decoded.ok)
+        throw new Error(decoded.reason === "invalid-utf8"
+            ? "Source text contains invalid UTF-8 or binary bytes."
+            : "Source text contains binary control bytes.");
+    assertNoInlineRaster(decoded.text);
+    return decoded.text;
+}
+function updateScreenshotDeclarations(value, imagePaths) {
+    if (Array.isArray(value))
+        return value.map((entry) => updateScreenshotDeclarations(entry, imagePaths));
+    if (value === null || typeof value !== "object")
+        return value;
+    const object = value;
+    const result = Object.create(null);
+    for (const [key, entry] of Object.entries(object))
+        result[key] = updateScreenshotDeclarations(entry, imagePaths);
+    if (object.schema === ACTOR_TRACE_SCHEMA &&
+        object.redaction !== null &&
+        typeof object.redaction === "object") {
+        const original = object.redaction;
+        if (original.screenshots === "raw" || original.screenshots === "blurred") {
+            result.redaction = {
+                ...original,
+                screenshots: "blurred",
+                notes: `${typeof original.notes === "string" ? original.notes : ""} Exported copy: screenshots blurred during export; original capture posture: ${original.screenshots}. See derivation.json.`,
+            };
+        }
+        if (Array.isArray(result.items)) {
+            result.items = result.items.map((item) => {
+                if (item === null || typeof item !== "object")
+                    return item;
+                const entry = item;
+                if (entry.screenshotRef === undefined)
+                    return item;
+                if (entry.screenshotRef === null || typeof entry.screenshotRef !== "object")
+                    throw new Error("Actor screenshot reference is malformed.");
+                const ref = entry.screenshotRef;
+                if (typeof ref.path !== "string" || !imagePaths.has(ref.path)) {
+                    throw new Error("Actor screenshot reference must resolve to a PNG transformed from this run's inventory.");
+                }
+                return { ...entry, screenshotRef: { ...ref, redaction: "blurred" } };
+            });
+        }
+    }
+    return result;
+}
+export function transformText(file, imagePaths) {
+    const text = decodeText(file);
+    const extension = path.extname(file.path).toLowerCase();
+    if (extension === ".json") {
+        const parsed = JSON.parse(text);
+        // Parsing also resolves escape sequences in string values before inspection.
+        assertNoInlineRaster(JSON.stringify(parsed));
+        // The copy names no sandbox: an id is local operational evidence, and the copy is shared.
+        const transformed = redactSandboxIds(updateScreenshotDeclarations(parsed, imagePaths));
+        if (JSON.stringify(transformed) === JSON.stringify(parsed))
+            return file.bytes;
+        assertRewritableNumbers(text);
+        return jsonBytes(transformed);
+    }
+    if (extension === ".ndjson" || extension === ".jsonl") {
+        const lines = text.split("\n");
+        const transformed = lines.map((line) => {
+            if (line.trim().length === 0)
+                return line;
+            const parsed = JSON.parse(line);
+            assertNoInlineRaster(JSON.stringify(parsed));
+            const updated = JSON.stringify(redactSandboxIds(updateScreenshotDeclarations(parsed, imagePaths)));
+            if (updated === JSON.stringify(parsed))
+                return line;
+            assertRewritableNumbers(line);
+            return updated;
+        });
+        return Buffer.from(transformed.join("\n"));
+    }
+    if (extension === ".yaml" || extension === ".yml") {
+        assertNoInlineRaster(JSON.stringify(parseYaml(text, { maxAliasCount: 100, logLevel: "silent" })) ?? "");
+    }
+    return file.bytes;
+}
+export function assertRewritableNumbers(json) {
+    // Opaque adapter JSON stays byte-identical. A known trace that actually needs
+    // rewriting must not silently round an identifier outside JS's integer range.
+    const unquoted = json.replace(/"(?:\\.|[^"\\])*"/g, '""');
+    for (const match of unquoted.matchAll(/-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/g)) {
+        const number = Number(match[0]);
+        if (!Number.isFinite(number) || (Number.isInteger(number) && !Number.isSafeInteger(number))) {
+            throw new Error("A trace requiring redaction contains an unsafe numeric value; represent large identifiers as strings before capture.");
+        }
+    }
+}
+/** The loaded source bundle as the copy records it: screenshots declared and labelled blurred. */
+export function derivedBundle(bundle, imagePaths) {
+    const transformed = redactSandboxIds(updateScreenshotDeclarations(bundle, imagePaths));
+    transformed.redaction = {
+        status: "passed",
+        notes: `${bundle.redaction.notes} Exported copy: screenshots were blurred during export; the original capture is retained separately. See derivation.json.`,
+    };
+    for (const stream of transformed.streams) {
+        for (const artifact of stream.artifacts) {
+            if (artifact.kind === "screenshot")
+                artifact.label = artifact.label.replace(/\((raw|blurred)\)/g, "(blurred at export)");
+        }
+    }
+    return transformed;
+}

package/dist/feedback/export-bundle.js

@@ -4,18 +4,18 @@ import { createHash } from "node:crypto";
 import { lstat, mkdir, mkdtemp, readdir, realpath, rename, rm, rmdir } from "node:fs/promises";
 import path from "node:path";
 import { tmpdir } from "node:os";
-import { parse as parseYaml } from "yaml";
-import { ACTOR_TRACE_SCHEMA } from "../actors/contract.js";
 import { renderObserver } from "../observer/render.js";
 import { buildObserverData } from "../observer/data.js";
-import { inventorySandboxIds, scrubSandboxIdBytes } from "../run/sandbox-ids.js";
-import { containsSensitive, redactSandboxIds, redactScreenshot, redactText, } from "../evidence/redaction.js";
-import { decodeEscapes, readingsOf } from "../evidence/encoded-text.js";
-import { readPlainText } from "../evidence/plain-text.js";
-import { MAX_RUN_ENTRIES, streamScreenshotPaths } from "../verify/artifacts.js";
+import { inventorySandboxIds, publicSandboxView, scrubSandboxIdBytes } from "../run/sandbox-ids.js";
+import { splitStreamTraces } from "../run/stream-trace.js";
+import { redactScreenshot, redactText } from "../evidence/redaction.js";
+import { assertRewritableNumbers, derivedBundle, jsonBytes, transformText, } from "./derivative-text.js";
+import { streamScreenshotPaths } from "../verify/artifacts.js";
+import { runEntryLimit } from "../verify/scan-limit.js";
 import { verifyRunPrepared } from "../verify/verify.js";
-import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
-import {} from "../run/bundle.js";
+import { loadRunBundlePrepared, readRunJsonIfExists, resolveRunPath, runJsonValue, } from "../run/locate.js";
+import { RUN_BUNDLE_FILE } from "../run/bundle.js";
+import { isRecord } from "../run/type-guards.js";
 import { runIdOf, isPathInside, prepareRunArtifactPaths, validatePreparedRunArtifactPaths, } from "../run/paths.js";
 import { isAnalysisRecordPath } from "../analysis/sharing.js";
 import { LOCAL_ONLY_RUN_FILES } from "../run/local-only-files.js";
@@ -43,9 +43,6 @@ const PNG_MAGIC = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 function hash(bytes) {
     return createHash("sha256").update(bytes).digest("hex");
 }
-function jsonBytes(value) {
-    return Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
-}
 function omittedReason(relative) {
     if (relative.startsWith("analysis-automatic/") && isAnalysisRecordPath(relative))
         return "automatic execution intent and liveness do not transfer to a derivative";
@@ -63,14 +60,17 @@ async function inventory(root, maxBytes) {
     const files = [];
     let total = 0;
     let entriesSeen = 0;
+    // The scan's limit for the participants run.json records, so a run verify reads in full exports.
+    const stored = runJsonValue(await readRunJsonIfExists(root, RUN_BUNDLE_FILE));
+    const entryLimit = runEntryLimit(isRecord(stored) && Array.isArray(stored.simulations) ? stored.simulations.length : 0);
     const walk = async (relative) => {
         const directory = path.join(root.physicalRunRoot, relative);
         const before = await lstat(directory, { bigint: true });
         if (!before.isDirectory() || before.isSymbolicLink())
             throw new Error("Source contains an unsafe directory.");
         for (const name of (await readdir(directory)).sort()) {
-            if (++entriesSeen > MAX_RUN_ENTRIES)
-                throw new Error(`Source exceeds ${MAX_RUN_ENTRIES} inventory entries.`);
+            if (++entriesSeen > entryLimit)
+                throw new Error(`Source exceeds ${entryLimit} inventory entries.`);
             if (name.includes("\\") || name.includes("\0"))
                 throw new Error("Source contains an unsafe path segment.");
             const rel = relative ? `${relative}/${name}` : name;
@@ -147,65 +147,6 @@ async function prospectivePhysicalPath(requested) {
         return path.join(await prospectivePhysicalPath(parent), path.basename(requested));
     }
 }
-function assertNoInlineRaster(text) {
-    // Decode the escapes verify decodes (decodeEscapes) before checking. Unknown embedded bytes are
-    // refused: copying a text extension must not smuggle untransformed pixels.
-    if (readingsOf(text).some(containsSensitive))
-        throw new Error("Decoded text contains a secret-shaped value or private path; export refused.");
-    const decoded = decodeEscapes(text);
-    if (/data\s*:\s*(?:image\/|application\/|text\/|[^,\s]*;base64,|,)/i.test(decoded) ||
-        /iVBORw0KGgo|\/9j\/[A-Za-z0-9+/]|R0lGOD|UklGR[A-Za-z0-9+/]{4}|<svg\b/i.test(decoded)) {
-        throw new Error("Text contains an inline image/data payload; embedded raster redaction is unsupported.");
-    }
-}
-function decodeText(file) {
-    const decoded = readPlainText(file.bytes);
-    if (!decoded.ok)
-        throw new Error(decoded.reason === "invalid-utf8"
-            ? "Source text contains invalid UTF-8 or binary bytes."
-            : "Source text contains binary control bytes.");
-    assertNoInlineRaster(decoded.text);
-    return decoded.text;
-}
-function updateScreenshotDeclarations(value, imagePaths) {
-    if (Array.isArray(value))
-        return value.map((entry) => updateScreenshotDeclarations(entry, imagePaths));
-    if (value === null || typeof value !== "object")
-        return value;
-    const object = value;
-    const result = Object.create(null);
-    for (const [key, entry] of Object.entries(object))
-        result[key] = updateScreenshotDeclarations(entry, imagePaths);
-    if (object.schema === ACTOR_TRACE_SCHEMA &&
-        object.redaction !== null &&
-        typeof object.redaction === "object") {
-        const original = object.redaction;
-        if (original.screenshots === "raw" || original.screenshots === "blurred") {
-            result.redaction = {
-                ...original,
-                screenshots: "blurred",
-                notes: `${typeof original.notes === "string" ? original.notes : ""} Exported copy: screenshots blurred during export; original capture posture: ${original.screenshots}. See derivation.json.`,
-            };
-        }
-        if (Array.isArray(result.items)) {
-            result.items = result.items.map((item) => {
-                if (item === null || typeof item !== "object")
-                    return item;
-                const entry = item;
-                if (entry.screenshotRef === undefined)
-                    return item;
-                if (entry.screenshotRef === null || typeof entry.screenshotRef !== "object")
-                    throw new Error("Actor screenshot reference is malformed.");
-                const ref = entry.screenshotRef;
-                if (typeof ref.path !== "string" || !imagePaths.has(ref.path)) {
-                    throw new Error("Actor screenshot reference must resolve to a PNG transformed from this run's inventory.");
-                }
-                return { ...entry, screenshotRef: { ...ref, redaction: "blurred" } };
-            });
-        }
-    }
-    return result;
-}
 function assertFeedbackReferences(bundle, source) {
     const retained = new Set(source.files.filter((file) => omittedReason(file.path) === undefined).map((file) => file.path));
     retained.add("observer/index.html");
@@ -220,51 +161,6 @@ function assertFeedbackReferences(bundle, source) {
         }
     }
 }
-function transformText(file, imagePaths) {
-    const text = decodeText(file);
-    const extension = path.extname(file.path).toLowerCase();
-    if (extension === ".json") {
-        const parsed = JSON.parse(text);
-        // Parsing also resolves escape sequences in string values before inspection.
-        assertNoInlineRaster(JSON.stringify(parsed));
-        // The copy names no sandbox: an id is local operational evidence, and the copy is shared.
-        const transformed = redactSandboxIds(updateScreenshotDeclarations(parsed, imagePaths));
-        if (JSON.stringify(transformed) === JSON.stringify(parsed))
-            return file.bytes;
-        assertRewritableNumbers(text);
-        return jsonBytes(transformed);
-    }
-    if (extension === ".ndjson" || extension === ".jsonl") {
-        const lines = text.split("\n");
-        const transformed = lines.map((line) => {
-            if (line.trim().length === 0)
-                return line;
-            const parsed = JSON.parse(line);
-            assertNoInlineRaster(JSON.stringify(parsed));
-            const updated = JSON.stringify(redactSandboxIds(updateScreenshotDeclarations(parsed, imagePaths)));
-            if (updated === JSON.stringify(parsed))
-                return line;
-            assertRewritableNumbers(line);
-            return updated;
-        });
-        return Buffer.from(transformed.join("\n"));
-    }
-    if (extension === ".yaml" || extension === ".yml") {
-        assertNoInlineRaster(JSON.stringify(parseYaml(text, { maxAliasCount: 100, logLevel: "silent" })) ?? "");
-    }
-    return file.bytes;
-}
-function assertRewritableNumbers(json) {
-    // Opaque adapter JSON stays byte-identical. A known trace that actually needs
-    // rewriting must not silently round an identifier outside JS's integer range.
-    const unquoted = json.replace(/"(?:\\.|[^"\\])*"/g, '""');
-    for (const match of unquoted.matchAll(/-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/g)) {
-        const number = Number(match[0]);
-        if (!Number.isFinite(number) || (Number.isInteger(number) && !Number.isSafeInteger(number))) {
-            throw new Error("A trace requiring redaction contains an unsafe numeric value; represent large identifiers as strings before capture.");
-        }
-    }
-}
 /** PNG paths that run.json cites outside actor traces: feedback, adapter and stream artifacts. */
 function citedPngPaths(bundle) {
     const cited = [
@@ -304,6 +200,13 @@ async function writeDerivative(source, stagePaths, bundle) {
     const entries = [];
     const imagePaths = keptPngPaths(source, bundle);
     const sandboxIds = inventorySandboxIds(source.files);
+    // run.json and each trace file come from one rewritten bundle, so each trace's index binds the
+    // bytes written here. A v1 source is written as v2.
+    const derived = splitStreamTraces(publicSandboxView(derivedBundle(bundle, imagePaths), sandboxIds));
+    const derivedFiles = new Map([
+        ["run.json", jsonBytes(derived.bundle)],
+        ...derived.files.map((file) => [file.path, file.bytes]),
+    ]);
     let images = 0;
     for (const file of source.files) {
         const isPng = path.extname(file.path).toLowerCase() === ".png";
@@ -332,20 +235,11 @@ async function writeDerivative(source, stagePaths, bundle) {
             if (!TEXT_EXTENSIONS.has(extension))
                 throw new Error(`Unsupported artifact format ${extension || "(no extension)"}; bundle export supports PNG and UTF-8 text only.`);
             bytes = transformText(file, imagePaths);
-            if (file.path === "run.json") {
+            const rewritten = derivedFiles.get(file.path);
+            if (rewritten !== undefined) {
                 assertRewritableNumbers(file.bytes.toString("utf8"));
-                const transformed = redactSandboxIds(updateScreenshotDeclarations(bundle, imagePaths));
-                transformed.redaction = {
-                    status: "passed",
-                    notes: `${bundle.redaction.notes} Exported copy: screenshots were blurred during export; the original capture is retained separately. See derivation.json.`,
-                };
-                for (const stream of transformed.streams) {
-                    for (const artifact of stream.artifacts) {
-                        if (artifact.kind === "screenshot")
-                            artifact.label = artifact.label.replace(/\((raw|blurred)\)/g, "(blurred at export)");
-                    }
-                }
-                bytes = jsonBytes(transformed);
+                bytes = rewritten;
+                derivedFiles.delete(file.path);
             }
             bytes = scrubSandboxIdBytes(file.path, bytes, sandboxIds);
             action = bytes.equals(file.bytes) ? "copied" : "updated";
@@ -353,6 +247,19 @@ async function writeDerivative(source, stagePaths, bundle) {
         await writeContainedOutputFile(stagePaths, file.path, bytes);
         entries.push({ path: file.path, sourceSha256: file.sha256, outputSha256: hash(bytes), action });
     }
+    // A v1 source stream with no actor trace file gets one; its content came from run.json.
+    const runJson = source.files.find((file) => file.path === "run.json");
+    for (const [relative, bytes] of derivedFiles) {
+        if (relative === "run.json" || runJson === undefined)
+            continue;
+        await writeContainedOutputFile(stagePaths, relative, bytes);
+        entries.push({
+            path: relative,
+            sourceSha256: runJson.sha256,
+            outputSha256: hash(bytes),
+            action: "updated",
+        });
+    }
     return { images, entries };
 }
 async function removeOwnedDirectory(root, strict = false) {