humanish 0.122.0 → 0.124.0

package/dist/feedback/export-bundle.js

@@ -4,18 +4,17 @@ 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 +42,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 +59,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 +146,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 +160,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 +199,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 +234,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 +246,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) {
@@ -534,10 +440,7 @@ async function buildDerivative(stage, source, runId, bundle, maxBytes) {
         note: "A redacted copy of the same study, not a new attempt. Original pixels are not present. Text and findings still require human review before sharing.",
         files: transformed.entries,
     };
-    const transformedBundle = await loadRunBundlePrepared(stage.physicalPath, stagePaths);
-    if (!transformedBundle)
-        throw new Error("Derivative bundle could not be loaded.");
-    await writeContainedOutputFile(stagePaths, "observer/observer-data.json", jsonBytes(buildObserverData(transformedBundle.bundle)));
+    // Rendering writes observer-data.json and index.html from the derivative's run.json.
     const rendered = await renderObserver(stage.physicalPath, runId, { open: false });
     if (!rendered.ok)
         throw new Error("Derivative Observer could not be rebuilt.");

package/dist/feedback/export.js

@@ -13,8 +13,9 @@ import { createHash } from "node:crypto";
 import path from "node:path";
 import { renderObserver } from "../observer/render.js";
 import { renderObserverHtml } from "../observer/artifact.js";
-import { buildObserverData } from "../observer/data.js";
+import { buildObserverData, OBSERVER_DATA_SCHEMA, observerDataFromSaved, } from "../observer/data.js";
 import { resolveRunPath } from "../run/locate.js";
+import { loadRunTraces, StreamTraceRefusedError } from "../run/stream-trace.js";
 import { verifyRun } from "../verify/verify.js";
 import {} from "../run/bundle.js";
 import { exportRedactedBundle } from "./export-bundle.js";
@@ -24,6 +25,7 @@ import { cli } from "../cli/invocation.js";
 import { analysisSharingProblems } from "../analysis/sharing.js";
 import { EVIDENCE_LIMITS, validateAnalysisEvidence } from "../analysis/evidence.js";
 import { readBoundedFile } from "../run/evidence-files.js";
+import { isRecord } from "../run/type-guards.js";
 import { shellQuote } from "../substrates/shell.js";
 import { plural } from "../run/text.js";
 const EXPORT_SCHEMA = "humanish.export-result.v1";
@@ -79,7 +81,7 @@ export async function exportRun(cwdInput, runInput, options = {}, deps = {}) {
     const analysis = await loadAnalysis(runPaths);
     const data = await currentObserverData(runPaths, analysis, slot);
     if (data === undefined)
-        return exportFailure(cwd, runInput, "HUMANISH_EXPORT_VERIFY_FAILED", "Source evidence changed while preparing the analysis export.");
+        return exportFailure(cwd, runInput, "HUMANISH_EXPORT_VERIFY_FAILED", "The run's evidence changed, or a participant's trace could not be read, while preparing the export.");
     const omittedRecording = omitRecordings(data.value);
     if (omittedRecording)
         warnings.push(MEDIA_OMISSION);
@@ -176,17 +178,42 @@ async function readObserverSlot(cwd, runInput, runRoot, runId, verified, deps, w
 /**
  * The Observer data to export. A current report must travel with the current source projection,
  * even if an older saved HTML was never refreshed; old recording-only exports keep the saved slot.
- * Undefined when run.json no longer matches the analysis.
+ * A page saved since observer-data v2 holds no participant's items in its slot, and verify does not
+ * read the page's compressed copy, so its export is the current projection of the run and its
+ * traces. Undefined when run.json no longer matches the analysis, or a v2 page's run cannot be read.
  */
 async function currentObserverData(runPaths, analysis, slot) {
     const saved = JSON.parse(slot);
-    if (analysis.state !== "ready" || !analysis.analysis)
-        return { value: saved };
-    const source = await readBoundedFile(runPaths, "run.json", EVIDENCE_LIMITS.sourceBytes);
-    if (!source ||
-        createHash("sha256").update(source).digest("hex") !== analysis.analysis.sourceRunSha256)
+    const source = async () => readBoundedFile(runPaths, "run.json", EVIDENCE_LIMITS.sourceBytes);
+    if (analysis.state !== "ready" || !analysis.analysis) {
+        const schema = saved?.schema;
+        if (schema === "humanish.observer-data.v1")
+            return { value: observerDataFromSaved(saved) };
+        if (schema !== OBSERVER_DATA_SCHEMA)
+            return { value: saved };
+        const bundle = await sourceTraces(runPaths, await source());
+        return bundle === undefined ? undefined : { value: buildObserverData(bundle) };
+    }
+    const bytes = await source();
+    if (!bytes ||
+        createHash("sha256").update(bytes).digest("hex") !== analysis.analysis.sourceRunSha256)
+        return undefined;
+    const bundle = await sourceTraces(runPaths, bytes);
+    return bundle === undefined ? undefined : { value: buildObserverData(bundle) };
+}
+/** The run with its traces read, or undefined when run.json is missing or a trace is refused. */
+async function sourceTraces(runPaths, bytes) {
+    if (!bytes)
         return undefined;
-    return { value: buildObserverData(JSON.parse(source.toString("utf8"))) };
+    const stored = JSON.parse(bytes.toString("utf8"));
+    if (!isRecord(stored) || !Array.isArray(stored.streams))
+        return undefined;
+    // A trace that no longer matches run.json's index is a source that no longer matches.
+    return loadRunTraces(runPaths, stored).catch((error) => {
+        if (error instanceof StreamTraceRefusedError)
+            return undefined;
+        throw error;
+    });
 }
 /** Portable HTML keeps the lightweight evidence; media remains in the source run. */
 function omitRecordings(data) {

package/dist/observer/artifact.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { projectShareCheckedAnalysis, analysisSharingProblems } from "../analysis/sharing.js";
 import { withObserverEndings } from "./data.js";
+import { escapeJsonScript, observerDataElements } from "./page-data.js";
 const OBSERVER_DATA_PLACEHOLDER = "__HUMANISH_OBSERVER_DATA__";
 const OBSERVER_DATA_SLOT = `<script id="observer-data" type="application/json">${OBSERVER_DATA_PLACEHOLDER}</script>`;
 let cachedObserverArtifact = null;
@@ -166,7 +167,7 @@ function renderObserverAppHtml(data, snapshot, analysis, notes, assets) {
     return (snapshot
         ? artifact.replace("</head>", '<meta name="humanish-observer-mode" content="snapshot"></head>')
         : artifact)
-        .replace(OBSERVER_DATA_SLOT, () => `<script id="observer-data" type="application/json">${escapeJsonScript(data)}</script>`)
+        .replace(OBSERVER_DATA_SLOT, () => observerDataElements(data))
         .replace(/<script id="study-analysis" type="application\/json">[\s\S]*?<\/script>/, () => `<script id="study-analysis" type="application/json">${escapeJsonScript(analysis)}</script>`)
         .replace(/<script id="run-notes" type="application\/json">[\s\S]*?<\/script>/, () => `<script id="run-notes" type="application/json">${escapeJsonScript(notes)}</script>`)
         .replace("</body>", () => `${renderExportAssets(assets)}</body>`)
@@ -241,11 +242,3 @@ function escapeHtml(value) {
         }
     });
 }
-function escapeJsonScript(value) {
-    return JSON.stringify(value)
-        .replace(/</g, "\\u003c")
-        .replace(/>/g, "\\u003e")
-        .replace(/&/g, "\\u0026")
-        .replace(/\u2028/g, "\\u2028")
-        .replace(/\u2029/g, "\\u2029");
-}

package/dist/observer/data.d.ts

@@ -2,7 +2,7 @@ import { type ActorEnding } from "../actors/stop-cause.js";
 import type { RunBundle, RunCostSummary, RunEvent, RunSimulation } from "../run/bundle.js";
 import { type RunDisplay } from "../run/display.js";
 import type { RunStream, RunStreamKind } from "../run/streams.js";
-export declare const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v1";
+export declare const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v2";
 interface ObserverArtifactLink {
     label: string;
     href: string;
@@ -10,7 +10,7 @@ interface ObserverArtifactLink {
 }
 export interface ObserverData {
     schema: typeof OBSERVER_DATA_SCHEMA;
-    schemaVersion: 1;
+    schemaVersion: 2;
     generatedAt: string;
     /** Served-only liveness observation. Never a replacement for the recorded evidence verdict. */
     runtime?: {
@@ -123,6 +123,13 @@ interface ObserverLaneGroup {
  * carried its outcome.
  */
 export declare function buildObserverData(bundle: RunBundle, generatedAt?: string, statusRecord?: unknown): ObserverData;
+/**
+ * A saved Observer projection as this version reads it, unchecked as before: an observer-data.json
+ * written before v2 holds every participant's items. A v2 one holds none, so it is read only when
+ * no participant has any: showing participants with no steps would say they did nothing, and the
+ * items are in the run's traces. Null for a v2 projection that leaves items out.
+ */
+export declare function observerDataFromSaved(value: unknown): ObserverData | null;
 /** Refresh presentation from recorded actor evidence, including older exported snapshots. */
 export declare function withObserverEndings(data: ObserverData): ObserverData;
 export {};

package/dist/observer/data.js

@@ -3,7 +3,8 @@ import { isCommsReceivingEvidence, receivingAnalysisContext } from "../comms/rec
 import { formatParticipantOutcomes, formatRunTaskFunnel, participantOutcomeDetails, withCuaReviewProvenance, } from "../run/outcomes.js";
 import { cuaGoalSource, CUA_COMPLETION_NOTE } from "../actors/goal-source.js";
 import { bundleDisplayFacts, runDisplay } from "../run/display.js";
-export const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v1";
+import { joinObserverData, shellNeedsItems } from "./participant-items.js";
+export const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v2";
 /** Discard a forged or stale runtime grant before projecting persisted evidence. */
 export function recordedStreamEmbed(embed) {
     if (!embed)
@@ -80,7 +81,7 @@ export function buildObserverData(bundle, generatedAt = new Date().toISOString()
     const active = streams.filter((stream) => stream.status === "running" || stream.status === "preparing").length;
     return withObserverEndings({
         schema: OBSERVER_DATA_SCHEMA,
-        schemaVersion: 1,
+        schemaVersion: 2,
         generatedAt,
         run: {
             runId: bundle.runId,
@@ -141,6 +142,20 @@ export function buildObserverData(bundle, generatedAt = new Date().toISOString()
         },
     });
 }
+/**
+ * A saved Observer projection as this version reads it, unchecked as before: an observer-data.json
+ * written before v2 holds every participant's items. A v2 one holds none, so it is read only when
+ * no participant has any: showing participants with no steps would say they did nothing, and the
+ * items are in the run's traces. Null for a v2 projection that leaves items out.
+ */
+export function observerDataFromSaved(value) {
+    const saved = value;
+    if (saved.schema === "humanish.observer-data.v1")
+        return { ...saved, schema: OBSERVER_DATA_SCHEMA, schemaVersion: 2 };
+    return shellNeedsItems(saved)
+        ? null
+        : joinObserverData(saved, null);
+}
 /** Refresh presentation from recorded actor evidence, including older exported snapshots. */
 export function withObserverEndings(data) {
     const streams = (data.streams ?? []).map(({ ending: _previousEnding, ...stream }) => {

package/dist/observer/page-data.d.ts

@@ -0,0 +1,5 @@
+import type { ObserverData } from "./data.js";
+/** The page's data elements for `data`, in place of the built page's data slot. */
+export declare function observerDataElements(data: ObserverData): string;
+/** JSON that stays inert inside a script element: no `</script>` breakout, no HTML entities. */
+export declare function escapeJsonScript(value: unknown): string;

package/dist/observer/page-data.js

@@ -0,0 +1,21 @@
+// How an Observer page carries a run's data: observer-data.json's content as JSON, and every
+// participant's trace items gzip-compressed in base64, which a file:// page decodes without a
+// fetch. The items are most of a long run's bytes and compress about eight times.
+import { gzipSync } from "node:zlib";
+import { splitObserverData } from "./participant-items.js";
+/** The page's data elements for `data`, in place of the built page's data slot. */
+export function observerDataElements(data) {
+    const { shell, items } = splitObserverData(data);
+    const packed = gzipSync(JSON.stringify(items)).toString("base64");
+    return (`<script id="observer-data" type="application/json">${escapeJsonScript(shell)}</script>` +
+        `<script id="observer-items" type="application/octet-stream" data-encoding="gzip">${packed}</script>`);
+}
+/** JSON that stays inert inside a script element: no `</script>` breakout, no HTML entities. */
+export function escapeJsonScript(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}

package/dist/observer/participant-items.d.ts

@@ -0,0 +1,45 @@
+import type { ActorTraceItem } from "../actors/contract.js";
+import type { ObserverData, ObserverStream } from "./data.js";
+export declare const OBSERVER_ITEMS_SCHEMA = "humanish.observer-items.v1";
+/** A stream's actor and live actor, each without its items. */
+type ObserverShellStream = Omit<ObserverStream, "actor" | "liveActor"> & {
+    actor?: Omit<NonNullable<ObserverStream["actor"]>, "items">;
+    liveActor?: Omit<NonNullable<ObserverStream["liveActor"]>, "items">;
+    /** How many screenshot entries of `artifacts` travel with the items, when any do. */
+    screenshotArtifacts?: number;
+};
+/** observer-data.json: the Observer's data with no participant's trace items. */
+export type ObserverShell = Omit<ObserverData, "streams"> & {
+    streams: ObserverShellStream[];
+};
+/**
+ * Each participant's trace items by stream id, with the stream's artifact list when it names
+ * screenshots: one per turn, so it grows with the items.
+ */
+export interface ObserverItems {
+    schema: typeof OBSERVER_ITEMS_SCHEMA;
+    runId: string;
+    streams: Record<string, {
+        actor?: ActorTraceItem[];
+        liveActor?: ActorTraceItem[];
+        artifacts?: ObserverStream["artifacts"];
+    }>;
+}
+/** The data as observer-data.json and the page's items carry it. */
+export declare function splitObserverData(data: ObserverData): {
+    shell: ObserverShell;
+    items: ObserverItems;
+};
+/**
+ * Whether `items` are this run's and hold every participant's items that the data leaves out. The
+ * page reads nothing short of that: participants shown with no steps would say they did nothing.
+ */
+export declare function itemsCoverShell(shell: ObserverShell, items: ObserverItems): boolean;
+/** Whether the data leaves out items or screenshot entries that only an items document holds. */
+export declare function shellNeedsItems(shell: ObserverShell): boolean;
+/**
+ * The data with each participant's items back in place. A stream the items do not cover keeps an
+ * empty list, so the page shows the participant with no recorded steps.
+ */
+export declare function joinObserverData(shell: ObserverShell, items: ObserverItems | null): ObserverData;
+export {};

package/dist/observer/participant-items.js

@@ -0,0 +1,85 @@
+// The Observer's data in two parts: observer-data.json, the run and every participant without
+// their trace items, and the items themselves. A participant working for hours records thousands
+// of items, so the items are most of the bytes; apart, the saved observer-data.json stays small
+// enough to verify, and the page carries the items compressed. The Observer bundles this module,
+// so it imports types only (docs/decisions/0002-observer-is-one-self-contained-file.md).
+export const OBSERVER_ITEMS_SCHEMA = "humanish.observer-items.v1";
+/** The data as observer-data.json and the page's items carry it. */
+export function splitObserverData(data) {
+    // No prototype, so a stream id such as `__proto__` is an entry like any other.
+    const items = Object.create(null);
+    const streams = data.streams.map((stream) => {
+        const { actor, liveActor, ...rest } = stream;
+        const entry = {};
+        const shell = rest;
+        // Saved projections are read unchecked, and one written by an older version may have no list.
+        if (Array.isArray(stream.artifacts) &&
+            stream.artifacts.some((artifact) => artifact.kind === "screenshot")) {
+            entry.artifacts = stream.artifacts;
+            shell.artifacts = stream.artifacts.filter((artifact) => artifact.kind !== "screenshot");
+            shell.screenshotArtifacts = stream.artifacts.length - shell.artifacts.length;
+        }
+        if (actor !== undefined) {
+            const { items: actorItems, ...summary } = actor;
+            entry.actor = actorItems;
+            shell.actor = summary;
+        }
+        if (liveActor !== undefined) {
+            const { items: liveItems, ...summary } = liveActor;
+            entry.liveActor = liveItems;
+            shell.liveActor = summary;
+        }
+        if (Object.keys(entry).length > 0)
+            items[stream.id] = entry;
+        return shell;
+    });
+    return {
+        shell: { ...data, streams },
+        items: { schema: OBSERVER_ITEMS_SCHEMA, runId: data.run.runId, streams: items },
+    };
+}
+/**
+ * Whether `items` are this run's and hold every participant's items that the data leaves out. The
+ * page reads nothing short of that: participants shown with no steps would say they did nothing.
+ */
+export function itemsCoverShell(shell, items) {
+    if (items.runId !== shell.run.runId)
+        return false;
+    return shell.streams.every((stream) => {
+        const entry = Object.hasOwn(items.streams, stream.id) ? items.streams[stream.id] : undefined;
+        return ((stream.actor === undefined || Array.isArray(entry?.actor)) &&
+            (stream.liveActor === undefined || Array.isArray(entry?.liveActor)) &&
+            (stream.screenshotArtifacts === undefined ||
+                (Array.isArray(entry?.artifacts) &&
+                    entry.artifacts.filter((artifact) => artifact.kind === "screenshot").length ===
+                        stream.screenshotArtifacts)));
+    });
+}
+/** Whether the data leaves out items or screenshot entries that only an items document holds. */
+export function shellNeedsItems(shell) {
+    return shell.streams.some((stream) => stream.actor !== undefined ||
+        stream.liveActor !== undefined ||
+        stream.screenshotArtifacts !== undefined);
+}
+/**
+ * The data with each participant's items back in place. A stream the items do not cover keeps an
+ * empty list, so the page shows the participant with no recorded steps.
+ */
+export function joinObserverData(shell, items) {
+    const byStream = items !== null && items.runId === shell.run.runId ? items.streams : {};
+    return {
+        ...shell,
+        streams: shell.streams.map((stream) => {
+            const entry = Object.hasOwn(byStream, stream.id) ? byStream[stream.id] : undefined;
+            const { actor, liveActor, screenshotArtifacts: _moved, ...rest } = stream;
+            return {
+                ...rest,
+                artifacts: entry?.artifacts ?? stream.artifacts,
+                ...(actor === undefined ? {} : { actor: { ...actor, items: entry?.actor ?? [] } }),
+                ...(liveActor === undefined
+                    ? {}
+                    : { liveActor: { ...liveActor, items: entry?.liveActor ?? [] } }),
+            };
+        }),
+    };
+}

package/dist/observer/render.js

@@ -17,6 +17,7 @@ import { RUN_STATUS_FILE } from "../run/status.js";
 import { verifyRunPrepared } from "../verify/verify.js";
 import { renderObserverHtml } from "./artifact.js";
 import { buildObserverData } from "./data.js";
+import { splitObserverData } from "./participant-items.js";
 import { buildServeSecurityHeaders, hostAllowed, parsePublicOrigin } from "./http.js";
 import { listenOnLoopback } from "./listen.js";
 import { NOTES_PATH } from "../run/note-shape.js";
@@ -116,7 +117,7 @@ export async function renderObserver(cwdInput, runInput, options = {}) {
         verifiedAt: new Date().toISOString(),
         reasons: verified.shareSafety.reasons.map((reason) => reason.code),
     };
-    await writeContainedOutputFile(preparedRunPaths, path.join("observer", "observer-data.json"), `${JSON.stringify(observerData, null, 2)}\n`, "utf8");
+    await writeContainedOutputFile(preparedRunPaths, path.join("observer", "observer-data.json"), `${JSON.stringify(splitObserverData(observerData).shell, null, 2)}\n`, "utf8");
     await writeContainedOutputFile(preparedRunPaths, path.join("observer", "study-analysis.json"), `${JSON.stringify(analysis, null, 2)}\n`, "utf8");
     await writeContainedOutputFile(preparedRunPaths, path.join("observer", "index.html"), renderObserverHtml(observerData, { analysis, notes: await readRunNotes(preparedRunPaths) }), "utf8");
     await validatePreparedRunArtifactPaths(preparedRunPaths);