humanish 0.122.0 → 0.124.0

package/dist/observer/run-routes.js

@@ -1,6 +1,7 @@
 // HTTP handlers for one run's Observer: the page, its data with live status and runtime stream
 // URLs, its analysis, and its media with byte ranges. serveObserver (render.ts) and the library
 // server (serve.ts) both route requests through them.
+import { lstat } from "node:fs/promises";
 import path from "node:path";
 import { isAnalysisRecordPath, projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadAnalysis } from "../analysis/load.js";
@@ -9,11 +10,14 @@ 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 { 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";
 import { analysisCostOf, runCost, runCostLabel } from "../run/run-cost.js";
 import { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, isRunStatusRecord, } from "../run/status.js";
 import { renderObserverHtml } from "./artifact.js";
-import { buildObserverData, recordedStreamEmbed, withObserverEndings, } from "./data.js";
+import { splitObserverData } from "./participant-items.js";
+import { buildObserverData, observerDataFromSaved, recordedStreamEmbed, withObserverEndings, } from "./data.js";
 import { buildArtifactSecurityHeaders } from "./http.js";
 import { assertPinnedDirectory, openContainedFile, pinDirectChildDirectory, readContainedFile, relativeToRoot, sha256OfOpenedFile, } from "./pinned-files.js";
 /** The run's artifact paths, only when they are still the pinned directory being served. */
@@ -99,9 +103,9 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         return;
     }
     if (cleanedRelativePath === "observer/index.html") {
-        const observerData = await readObserverData(runRoot, runtimeStreamUrls);
-        if (!observerData) {
-            writeResponse(response, 404, "Observer data not found", "text/plain; charset=utf-8");
+        const observerData = await observerDataOrReason(runRoot, runtimeStreamUrls);
+        if ("unavailable" in observerData) {
+            writeResponse(response, 404, `Observer data not found: ${observerData.unavailable}`, "text/plain; charset=utf-8");
             return;
         }
         const analysis = await readObserverAnalysis(runRoot);
@@ -113,13 +117,19 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         }), "text/html; charset=utf-8");
         return;
     }
-    if (cleanedRelativePath === "observer/observer-data.json") {
-        const observerData = await readObserverData(runRoot, runtimeStreamUrls);
-        if (!observerData) {
-            writeResponse(response, 404, "Observer data not found", "text/plain; charset=utf-8");
+    // observer-data.json is the run without its participants' items, as the run saves it. The page
+    // polls observer-feed.json, the same data with the items, so one projection serves each poll.
+    if (cleanedRelativePath === "observer/observer-data.json" ||
+        cleanedRelativePath === "observer/observer-feed.json") {
+        const observerData = await observerDataOrReason(runRoot, runtimeStreamUrls);
+        if ("unavailable" in observerData) {
+            writeResponse(response, 404, `Observer data not found: ${observerData.unavailable}`, "text/plain; charset=utf-8");
             return;
         }
-        writeResponse(response, 200, JSON.stringify(observerData, null, 2), "application/json; charset=utf-8");
+        const { shell, items } = splitObserverData(observerData);
+        writeResponse(response, 200, cleanedRelativePath === "observer/observer-data.json"
+            ? JSON.stringify(shell, null, 2)
+            : JSON.stringify({ data: shell, items }), "application/json; charset=utf-8");
         return;
     }
     if (cleanedRelativePath === "observer/study-analysis.json") {
@@ -153,29 +163,72 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
     }
 }
+/** The run's trace files, read through its pinned folder. */
+function pinnedTraceReader(runRoot) {
+    return async (relativePath, maxBytes) => {
+        const bytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, relativePath), {
+            maxBytes,
+        }).catch(() => null);
+        return bytes === null ? { refused: `${relativePath} could not be read` } : { bytes };
+    };
+}
 async function readObserverData(runRoot, runtimeStreamUrls = []) {
+    const read = await observerDataOrReason(runRoot, runtimeStreamUrls);
+    return "unavailable" in read ? null : read;
+}
+/**
+ * The run's Observer data, or why there is none. run.json is the source: each trace is loaded
+ * through the loader, and a participant whose trace it refuses shows as unavailable, with no
+ * 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.
+ */
+async function observerDataOrReason(runRoot, runtimeStreamUrls) {
     const record = await readLocalRunStatus(runRoot);
-    // Best-effort load from either source. Both reads swallow all errors on
-    // purpose: this runs on every browser poll of a live run, where run.json may
-    // be absent, still being written (a partial-JSON parse error), or superseded
-    // by observer-data.json. A transient failure just falls through to the next
-    // source, or to null -> a 404 the poller retries; it must not surface a 500.
+    const runJson = path.join(runRoot.physicalPath, "run.json");
+    const bundleBytes = await readContainedFile(runRoot, runJson).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
+    // with the run's share_ready verification, so a run.json changed since then is refused, and the
+    // saved projection it may serve is the one admitted with the verified run.
+    if (absent || (bundleBytes === null && runRoot.admitsContent !== undefined))
+        return savedObserverData(runRoot, record, runtimeStreamUrls);
+    if (bundleBytes === null)
+        return { unavailable: "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"));
+        if (!isRecord(parsed) || !Array.isArray(parsed.streams))
+            throw new Error("not a run bundle");
+        stored = parsed;
+    }
+    catch {
+        return { unavailable: "run.json is not a run bundle; it may be mid-write, so try again." };
+    }
     try {
-        const bundleBytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, "run.json"));
-        if (!bundleBytes)
-            throw new Error("run.json unavailable");
-        const bundle = JSON.parse(bundleBytes.toString("utf8"));
+        const bundle = displayedTraces(await loadStreamTraces(pinnedTraceReader(runRoot), stored));
         return withRuntimeStreamUrls(withLocalRunStatus(record, buildObserverData(bundle, undefined, record), bundle.outcome), runtimeStreamUrls);
     }
-    catch { }
+    catch {
+        return { unavailable: "run.json could not be shown as a run." };
+    }
+}
+/** 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)
             throw new Error("observer-data.json unavailable");
-        return withRuntimeStreamUrls(withLocalRunStatus(record, withObserverEndings(JSON.parse(observerBytes.toString("utf8")))), runtimeStreamUrls);
+        const saved = observerDataFromSaved(JSON.parse(observerBytes.toString("utf8")));
+        if (saved === null)
+            throw new Error("observer-data.json holds no participant's items");
+        return withRuntimeStreamUrls(withLocalRunStatus(record, withObserverEndings(saved)), runtimeStreamUrls);
+    }
+    catch {
+        return { unavailable: "The run has written no run.json or Observer data yet." };
     }
-    catch { }
-    return null;
 }
 /** The run directory's own status record, when it is well formed and names that directory. */
 async function readLocalRunStatus(runRoot) {