humanish 0.128.0 → 0.130.0

package/dist/analysis/source.d.ts

@@ -0,0 +1,28 @@
+import { type StoredRunBundle } from "../run/bundle.js";
+import { type PreparedRunArtifactPaths } from "../run/paths.js";
+import type { RunStream } from "../run/streams.js";
+/**
+ * A refusal of the run's recorded source. Its message is the code, as every analysis error's is,
+ * and `reason` says which file analysis did not read and why, for the person who asked.
+ */
+export declare class AnalysisSourceRefusedError extends Error {
+    readonly reason: string;
+    constructor(code: "ANALYSIS_SOURCE_TOO_LARGE" | "ANALYSIS_SOURCE_INVALID", reason: string);
+}
+/** The refusal of a run.json of `size` bytes, more than the `max` analysis reads of it. */
+export declare function runFileTooLarge(size: number | bigint, max: number): AnalysisSourceRefusedError;
+/**
+ * run.json's bundle, when it is a run bundle of the prepared run that analysis reads: at most
+ * EVIDENCE_LIMITS.sourceBytes, at most EVIDENCE_LIMITS.participants participants, and each
+ * participant and event with the fields analysis reads.
+ */
+export declare function parseAnalysisSource(prepared: PreparedRunArtifactPaths, bytes: Buffer): StoredRunBundle;
+/**
+ * What `keep` takes from each stream of run.json's bundle with the stream's trace loaded, in stream
+ * order. Each trace file is read up to RUN_ARTIFACT_MAX_BYTES, as the loader, verify and the
+ * Observer read it, and is dropped once `keep` returns, so analysis holds one trace at a time
+ * whatever the number of participants. run.json's digest, which the analysis record binds, binds
+ * each trace's sha256. A trace whose index records more than the limit is refused as
+ * ANALYSIS_SOURCE_TOO_LARGE, and any other trace the loader refuses as ANALYSIS_SOURCE_INVALID.
+ */
+export declare function readParticipantTraces<T>(prepared: PreparedRunArtifactPaths, bundle: StoredRunBundle, keep: (stream: RunStream, index: number) => T): Promise<T[]>;

package/dist/analysis/source.js

@@ -0,0 +1,118 @@
+// How analysis reads a run's recorded source: run.json, then each participant's trace one at a time,
+// and the refusals it gives for either.
+import { isCommsReceivingEvidence } from "../comms/receiving-evidence.js";
+import { isReadRunBundleSchema } from "../run/bundle.js";
+import { runIdOf } from "../run/paths.js";
+import { reduceRunTraces, StreamTraceRefusedError, StreamTraceTooLargeError, } from "../run/stream-trace.js";
+import { isRecord } from "../run/type-guards.js";
+import { EVIDENCE_LIMITS } from "./analysis-limits.js";
+/**
+ * A refusal of the run's recorded source. Its message is the code, as every analysis error's is,
+ * and `reason` says which file analysis did not read and why, for the person who asked.
+ */
+export class AnalysisSourceRefusedError extends Error {
+    reason;
+    constructor(code, reason) {
+        super(code);
+        this.reason = reason;
+        this.name = "AnalysisSourceRefusedError";
+    }
+}
+const bytes = (count) => `${count.toLocaleString("en-US")} bytes`;
+const limit = (max) => `${bytes(max)} (${(max / (1024 * 1024)).toLocaleString("en-US", { maximumFractionDigits: 1 })} MiB)`;
+const runFileInvalid = (reason) => new AnalysisSourceRefusedError("ANALYSIS_SOURCE_INVALID", `Analysis did not read run.json: ${reason}`);
+const traceInvalid = (streamId, reason) => new AnalysisSourceRefusedError("ANALYSIS_SOURCE_INVALID", `Analysis did not read participant ${streamId}'s trace: ${reason}`);
+/** The refusal of a run.json of `size` bytes, more than the `max` analysis reads of it. */
+export function runFileTooLarge(size, max) {
+    return new AnalysisSourceRefusedError("ANALYSIS_SOURCE_TOO_LARGE", `Analysis did not read run.json: it holds ${bytes(size)}, more than the ${limit(max)} analysis reads of it. run.json grows with each participant and the study's mission; split the participants across studies to keep it under the limit.`);
+}
+/**
+ * run.json's bundle, when it is a run bundle of the prepared run that analysis reads: at most
+ * EVIDENCE_LIMITS.sourceBytes, at most EVIDENCE_LIMITS.participants participants, and each
+ * participant and event with the fields analysis reads.
+ */
+export function parseAnalysisSource(prepared, bytes) {
+    if (bytes.length > EVIDENCE_LIMITS.sourceBytes)
+        throw runFileTooLarge(bytes.length, EVIDENCE_LIMITS.sourceBytes);
+    const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    if (!isRecord(value) || !isReadRunBundleSchema(value.schema))
+        throw runFileInvalid("it is not a run bundle of a schema this version of humanish reads.");
+    if (value.runId !== runIdOf(prepared))
+        throw runFileInvalid(`it records another run than ${runIdOf(prepared)}, the run in its folder.`);
+    if (!Array.isArray(value.streams) || !Array.isArray(value.events))
+        throw runFileInvalid("it has no participants or events list.");
+    if (value.streams.length > EVIDENCE_LIMITS.participants)
+        throw runFileInvalid(`it lists ${value.streams.length} participants, more than the ${EVIDENCE_LIMITS.participants} analysis reads; split the participants across studies.`);
+    if (value.commsReceiving !== undefined && !isCommsReceivingEvidence(value.commsReceiving))
+        throw runFileInvalid("its email receiving evidence holds a field or value analysis does not read.");
+    const ids = new Set();
+    for (const [index, stream] of value.streams.entries()) {
+        if (!isRecord(stream) ||
+            typeof stream.id !== "string" ||
+            stream.id.length === 0 ||
+            stream.id.length > 256 ||
+            ids.has(stream.id) ||
+            typeof stream.label !== "string" ||
+            typeof stream.status !== "string") {
+            throw runFileInvalid(`participant ${index + 1} needs an id of 1 to 256 characters no other participant has, a label and a status.`);
+        }
+        ids.add(stream.id);
+        if (stream.actor !== undefined && !isRecord(stream.actor))
+            throw runFileInvalid(`participant ${stream.id}'s actor is not an object.`);
+    }
+    for (const [index, event] of value.events.entries()) {
+        if (!isRecord(event) ||
+            typeof event.id !== "string" ||
+            typeof event.message !== "string" ||
+            typeof event.type !== "string")
+            throw runFileInvalid(`event ${index + 1} needs an id, a type and a message.`);
+    }
+    return value;
+}
+/**
+ * What `keep` takes from each stream of run.json's bundle with the stream's trace loaded, in stream
+ * order. Each trace file is read up to RUN_ARTIFACT_MAX_BYTES, as the loader, verify and the
+ * Observer read it, and is dropped once `keep` returns, so analysis holds one trace at a time
+ * whatever the number of participants. run.json's digest, which the analysis record binds, binds
+ * each trace's sha256. A trace whose index records more than the limit is refused as
+ * ANALYSIS_SOURCE_TOO_LARGE, and any other trace the loader refuses as ANALYSIS_SOURCE_INVALID.
+ */
+export async function readParticipantTraces(prepared, bundle, keep) {
+    try {
+        return await reduceRunTraces(prepared, bundle, (stream, index) => {
+            validateTraceItems(stream);
+            return keep(stream, index);
+        });
+    }
+    catch (error) {
+        // The loader's refusal names the participant, the file, why, and what to do.
+        if (error instanceof StreamTraceRefusedError)
+            throw new AnalysisSourceRefusedError(error instanceof StreamTraceTooLargeError
+                ? "ANALYSIS_SOURCE_TOO_LARGE"
+                : "ANALYSIS_SOURCE_INVALID", error.message);
+        throw error;
+    }
+}
+function validateTraceItems(stream) {
+    const actor = stream.actor;
+    if (actor === undefined)
+        return;
+    if (!isRecord(actor) || !Array.isArray(actor.items))
+        throw traceInvalid(stream.id, "it has no items list.");
+    // The place each id was first seen. A refusal names places, since an id is trace text.
+    const firstPlace = new Map();
+    for (const [index, item] of actor.items.entries()) {
+        if (!isRecord(item) ||
+            typeof item.id !== "string" ||
+            item.id.length === 0 ||
+            item.id.length > 256 ||
+            typeof item.kind !== "string" ||
+            typeof item.title !== "string" ||
+            (item.text !== undefined && typeof item.text !== "string"))
+            throw traceInvalid(stream.id, `item ${index + 1} needs an id of 1 to 256 characters, a kind and a title, and a text that is a string if it has one.`);
+        const first = firstPlace.get(item.id);
+        if (first !== undefined)
+            throw traceInvalid(stream.id, `items ${first + 1} and ${index + 1} share an id, and analysis cites each item by its id.`);
+        firstPlace.set(item.id, index);
+    }
+}

package/dist/analysis/validation.js

@@ -150,7 +150,7 @@ const analysisEvidenceSchema = z
     quoteEligible: z.boolean(),
     at: timestamp.nullable(),
     elapsedMs: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).nullable(),
-    frame: z.number().int().min(0).max(100000).nullable(),
+    frame: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).nullable(),
     capture: z
         .object({
         eventId: sourceId,

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

@@ -138,7 +138,8 @@ export function formatConcurrentSharedWorldStudyHuman(result) {
                     ? "Participants used the app at the same time (observed in this run only)."
                     : "Participants were not observed using the app at the same time.",
             ]),
-        ...result.roles.map((participant) => `${participantCaption({ id: participant.id, personaId: participant.persona })}: ${participantStatus(participant.status)}${participant.ok ? "" : ", not ok"}`),
+        // A skipped participant's line ends on the reason the run recorded, as on computer use.
+        ...result.roles.map((participant) => `${participantCaption({ id: participant.id, personaId: participant.persona })}: ${participantStatus(participant.status)}${participant.ok ? "" : ", not ok"}${participant.skippedReason === undefined ? "" : ` · ${participant.skippedReason}`}`),
         ...(result.subjectSandbox
             ? [
                 `subject sandbox: ${sandboxName(result.subjectSandbox)} killed=${result.subjectSandbox.killed ? "yes" : "no"}`,

package/dist/feedback/export.js

@@ -17,7 +17,6 @@ import { buildObserverData, OBSERVER_DATA_SCHEMA, observerDataFromSaved, } from
 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";
 import { loadAnalysis } from "../analysis/load.js";
 import { readNotesForSharing } from "../run/note-files.js";

package/dist/observer/data.d.ts

@@ -1,7 +1,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";
+import type { RunStream, RunStreamKind, StoredRunStream } from "../run/streams.js";
 /**
  * The Observer's data. From v2 observer-data.json leaves out each participant's items, and from v3
  * each participant's per-request lists (REQUEST_LISTS in src/run/stream-trace.ts), which no part
@@ -96,7 +96,7 @@ export interface ObserverData {
         artifactRoot: string;
     };
 }
-export interface ObserverStream extends RunStream {
+export interface ObserverStream extends StoredRunStream {
     /** Only the attached server may grant provider-origin access for a live desktop iframe. */
     embed?: NonNullable<RunStream["embed"]> & {
         runtimeDesktop?: true;

package/dist/observer/feed-cursors.d.ts

@@ -9,6 +9,8 @@ import type { ObserverItems } from "./participant-items.js";
 export declare function parseFeedCursors(after: string | null): ReadonlyMap<string, LiveItemsCursor>;
 /**
  * `items` with each live file's cursor on the entry of the stream it was joined into, and
- * `liveAfter`, the page's cursor, where the entry's `liveActor` holds only the items past it.
+ * `liveAfter`, the page's cursor, where the entry's `liveActor` holds only the items past it. A
+ * live file the loader stopped reading (LiveItemsRead's `stopped`) keeps the page's cursor as its
+ * own, so the page holds its items and sends that cursor again.
  */
 export declare function withFeedCursors(items: ObserverItems, live: readonly LiveItemsRead[]): ObserverItems;

package/dist/observer/feed-cursors.js

@@ -43,7 +43,9 @@ function cursorText(path, position) {
 }
 /**
  * `items` with each live file's cursor on the entry of the stream it was joined into, and
- * `liveAfter`, the page's cursor, where the entry's `liveActor` holds only the items past it.
+ * `liveAfter`, the page's cursor, where the entry's `liveActor` holds only the items past it. A
+ * live file the loader stopped reading (LiveItemsRead's `stopped`) keeps the page's cursor as its
+ * own, so the page holds its items and sends that cursor again.
  */
 export function withFeedCursors(items, live) {
     const streams = Object.assign(Object.create(null), items.streams);
@@ -51,9 +53,10 @@ export function withFeedCursors(items, live) {
         const entry = Object.hasOwn(streams, read.streamId) ? streams[read.streamId] : undefined;
         if (entry === undefined || !Array.isArray(entry.liveActor))
             continue;
+        const end = read.stopped === undefined ? read.index : read.after;
         streams[read.streamId] = {
             ...entry,
-            live: cursorText(read.index.path, read.index),
+            live: cursorText(read.index.path, end),
             ...(read.after === undefined ? {} : { liveAfter: cursorText(read.index.path, read.after) }),
         };
     }

package/dist/observer/run-routes.js

@@ -10,6 +10,7 @@ import { listRuns } from "../run/stored-runs.js";
 import { readAnalysisAccounting } from "../run/costs.js";
 import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, } from "../run/paths.js";
 import { isRunOutcome } from "../run/bundle-shape.js";
+import { RUN_ARTIFACT_MAX_BYTES } from "../run/contained-output.js";
 import { displayedTraces, loadStreamTraces, } from "../run/stream-trace.js";
 import { isNodeError, isRecord } from "../run/type-guards.js";
 import { MAX_NOTE_FILE_BYTES, readRunNotes, RUN_NOTES_DIR, } from "../run/note-files.js";
@@ -150,10 +151,17 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
         return;
     }
+    // run.json is read under the limit every other reader of it uses, by name as through the feed.
+    const runJson = cleanedRelativePath === "run.json";
     try {
-        const body = await readContainedFile(runRoot, filePath, notePath ? { maxBytes: MAX_NOTE_FILE_BYTES } : {});
+        const body = await readContainedFile(runRoot, filePath, notePath
+            ? { maxBytes: MAX_NOTE_FILE_BYTES }
+            : runJson
+                ? { maxBytes: RUN_ARTIFACT_MAX_BYTES }
+                : {});
         if (!body) {
-            writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
+            const tooLarge = runJson ? await pastReadLimit(runRoot, "run.json") : undefined;
+            writeResponse(response, 404, tooLarge === undefined ? "Not found" : `Not found: ${tooLarge}`, "text/plain; charset=utf-8");
             return;
         }
         response.writeHead(200, {
@@ -198,12 +206,15 @@ async function readObserverData(runRoot, runtimeStreamUrls = []) {
  * fallback. The saved observer-data.json is read only while the run has no run.json at all, or in
  * safe serving, where only its admitted bytes can be read. Otherwise a run.json that is there and
  * cannot be read, parsed or used as a bundle (which a browser poll can meet mid-write) gives the
- * reason, a 404 the poller retries, never the saved projection.
+ * reason, a 404 the poller retries, never the saved projection. Both files are read under
+ * RUN_ARTIFACT_MAX_BYTES, as every other reader of a run file reads them.
  */
 async function observerDataOrReason(runRoot, runtimeStreamUrls, cursors) {
     const record = await readLocalRunStatus(runRoot);
     const runJson = path.join(runRoot.physicalPath, "run.json");
-    const bundleBytes = await readContainedFile(runRoot, runJson).catch(() => null);
+    const bundleBytes = await readContainedFile(runRoot, runJson, {
+        maxBytes: RUN_ARTIFACT_MAX_BYTES,
+    }).catch(() => null);
     const absent = bundleBytes === null &&
         (await lstat(runJson).then(() => false, (error) => isNodeError(error) && error.code === "ENOENT"));
     // A root admitted for safe serving checks every read against the identity and digest admitted
@@ -214,7 +225,10 @@ async function observerDataOrReason(runRoot, runtimeStreamUrls, cursors) {
         return "unavailable" in saved ? saved : { data: saved, live: [] };
     }
     if (bundleBytes === null)
-        return { unavailable: "run.json is there but could not be read: it is a link or changed." };
+        return {
+            unavailable: (await pastReadLimit(runRoot, "run.json")) ??
+                "run.json is there but could not be read: it is a link or changed.",
+        };
     let stored;
     try {
         const parsed = JSON.parse(bundleBytes.toString("utf8"));
@@ -237,12 +251,31 @@ async function observerDataOrReason(runRoot, runtimeStreamUrls, cursors) {
         return { unavailable: "run.json could not be shown as a run." };
     }
 }
+/**
+ * Why run.json or a saved observer-data.json was not read, when the file at `relativePath` passes
+ * the root's checks and is larger than RUN_ARTIFACT_MAX_BYTES, the most the server reads of either;
+ * otherwise undefined. The size comes from the opened file, so no link or file outside the run
+ * folder is measured.
+ */
+async function pastReadLimit(runRoot, relativePath) {
+    const opened = await openContainedFile(runRoot, path.join(runRoot.physicalPath, relativePath));
+    if (opened === null)
+        return undefined;
+    await opened.handle.close().catch(() => undefined);
+    return opened.size > RUN_ARTIFACT_MAX_BYTES
+        ? `${relativePath} is larger than ${RUN_ARTIFACT_MAX_BYTES} bytes, the most humanish reads of it.`
+        : undefined;
+}
 /** The saved observer-data.json of a run that has written no run.json yet. */
 async function savedObserverData(runRoot, record, runtimeStreamUrls) {
     try {
-        const observerBytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, "observer", "observer-data.json"));
-        if (!observerBytes)
+        const observerBytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, "observer", "observer-data.json"), { maxBytes: RUN_ARTIFACT_MAX_BYTES });
+        if (!observerBytes) {
+            const tooLarge = await pastReadLimit(runRoot, "observer/observer-data.json");
+            if (tooLarge !== undefined)
+                return { unavailable: tooLarge };
             throw new Error("observer-data.json unavailable");
+        }
         const saved = observerDataFromSaved(JSON.parse(observerBytes.toString("utf8")));
         if (saved === null)
             throw new Error("observer-data.json holds no participant's items");