humanish 0.104.3 → 0.106.0

package/dist/run/judge.js

@@ -0,0 +1,240 @@
+// How humanish judges a run. A route reduces what happened to plain facts and judges them here
+// once. Two facts come out: what the participants experienced (the verdict, which the bundle and
+// status.json show) and whether the run worked as an execution. The result's ok reads both under
+// the route's policy. The file reads in the order a run is judged:
+//   1. session and participant predicates (hollowCompletion, selfReportedBlocker, judgedStatus,
+//      participantPassed, participantHarnessFailed);
+//   2. the judgment shapes (Judgment and judgmentOf, SharedWorldJudgment, ExecutionOutcome,
+//      OutcomePolicy);
+//   3. one judge per route: computer-use calls judgeOneParticipant (one lane, no rerun) or
+//      judgeParticipants, shared-world calls judgeSharedWorld, terminal calls judgeTerminal,
+//      scripted calls judgeScripted and preview calls judgePreview;
+//   4. foldScorerFailures, which every route with a scorer applies before the run finishes;
+//   5. the outcome: judgeExecution applies the route's policy to its execution failures, and
+//      resultOk gives the result's ok.
+/**
+ * The participant said it reached the goal having taken no action and said nothing, and no stop
+ * condition ended the session. It most likely saw a blank or loading screen, so it is not a pass.
+ */
+export function hollowCompletion(ending) {
+    return (ending.completionReason === "goal_satisfied" &&
+        ending.actions === 0 &&
+        ending.messages === 0 &&
+        !ending.stopConditionMatched);
+}
+/**
+ * The participant said it reached the goal but reported a blocker. A declared outcome is its own
+ * word and wins (#570). Without one, the closing report is read, unless a stop condition ended the
+ * session: a matched stopWhen is structured completion evidence and overrides the text.
+ */
+export function selfReportedBlocker(ending) {
+    if (ending.declaredOutcome !== undefined)
+        return ending.declaredOutcome === "blocked" && ending.completionReason === "goal_satisfied";
+    return (ending.completionReason === "goal_satisfied" &&
+        ending.closingReportReadsBlocked &&
+        !ending.stopConditionMatched);
+}
+/**
+ * The status a participant is judged under. A harness failure is failed, and a skipped participant
+ * is blocked, as the fan-out bundle and the result write it. Otherwise it is the tallied
+ * participantStatus of its session, or undefined when no session reached a terminal status.
+ * participantPassed and judgeOneParticipant's verdict both read it, so the two cannot disagree.
+ */
+export function judgedStatus(participant) {
+    if (participantHarnessFailed(participant))
+        return "failed";
+    if (participant.skipped)
+        return "blocked";
+    return participant.status === undefined
+        ? undefined
+        : participantStatus(participant.status, participant);
+}
+/** A participant passed: its session passed without a harness error, engaged, and reported no blocker. */
+export function participantPassed(participant) {
+    return judgedStatus(participant) === "passed";
+}
+/**
+ * The participant's session failed in the harness: it threw before a terminal status, or it ended
+ * in a harness error. That is an execution failure, apart from what the participant experienced.
+ */
+export function participantHarnessFailed(participant) {
+    return participant.sessionError !== undefined || participant.completionReason === "harness_error";
+}
+/**
+ * The status a participant is tallied under, given what the route made of the session. A
+ * goal_satisfied claim with zero engagement is a session that ran out before anything happened;
+ * one whose final message describes a blocker is a participant who could not proceed and said so.
+ * Both keep their trace status (the claim is evidence); neither is a participant who reached the
+ * goal. One rule for the single lane and the fan-out roll-up (#476).
+ */
+export function participantStatus(status, judgments) {
+    if (status !== "passed" || judgments === undefined)
+        return status;
+    if (judgments.noEngagement)
+        return "incomplete";
+    if (judgments.selfReportedBlocker)
+        return "blocked";
+    return status;
+}
+/** The review verdict for one participant's status. */
+export function verdictForStatus(status) {
+    switch (status) {
+        case "passed":
+            return "pass";
+        case "failed":
+            return "fail";
+        case "blocked":
+            return "blocked";
+        case "timed_out":
+            return "timed_out";
+        // A participant who abandoned, or a session that ran out before the goal, did not pass, but the
+        // harness did not fail either. The run reports what happened rather than a verdict on the tool.
+        case "abandoned":
+        case "incomplete":
+            return "fail";
+    }
+}
+/** The judgment for a verdict: a run passes when its verdict is pass, and a dry run passes. */
+export function judgmentOf(verdict, dryRun) {
+    return { verdict, passed: dryRun || verdict === "pass" };
+}
+/** Each route's outcome policy, in one place. */
+export const OUTCOME_POLICIES = {
+    "computer-use": { participants: "gate", sandboxCleanup: "warns", evidence: "fails" },
+    "shared-world": { participants: "gate", sandboxCleanup: "warns", evidence: "fails" },
+    terminal: { participants: "evidence", sandboxCleanup: "fails", evidence: "fails" },
+    scripted: { participants: "evidence", sandboxCleanup: "warns", evidence: "fails" },
+    // The preview's bundle is evidence even when its Observer does not render; export renders it.
+    preview: { participants: "evidence", sandboxCleanup: "warns", evidence: "warns" },
+};
+/**
+ * A run with one participant: its tallied status is the verdict, so a hollow pass fails and a
+ * self-reported blocker reads as blocked. Without a session, a harness failure fails the run and
+ * a dry run is a contract. A run still in progress is a contract until it finishes. Computer-use
+ * calls it for one lane with no rerun, and terminal calls it through judgeTerminal.
+ */
+export function judgeOneParticipant(args) {
+    const status = args.participant === undefined ? undefined : judgedStatus(args.participant);
+    const verdict = args.inProgress || status === undefined ? "contract_proof_only" : verdictForStatus(status);
+    return judgmentOf(verdict, args.dryRun);
+}
+/**
+ * A run with several participants: it passes only when every expected participant passed. When
+ * one did not, a timeout among them makes the run timed_out; otherwise it fails. A dry run and a
+ * run still in progress are contracts. Computer-use calls it for a fan-out or a rerun.
+ */
+export function judgeParticipants(args) {
+    const { participants } = args;
+    const complete = participants.length === args.expected;
+    const passed = complete && participants.every(participantPassed);
+    const verdict = args.inProgress || args.dryRun
+        ? "contract_proof_only"
+        : passed
+            ? "pass"
+            : complete && participants.some((participant) => participant.status === "timed_out")
+                ? "timed_out"
+                : "fail";
+    return judgmentOf(verdict, args.dryRun);
+}
+/**
+ * Why a shared-world run whose seats all passed still fails, or undefined when its world facts
+ * meet what verify's shared-world check requires of a pass: two seats live at the same time and,
+ * on the provisioned plane, a shared-state change at or after the first overlap started.
+ */
+export function sharedWorldShortfall(world) {
+    if (!world.overlap) {
+        return "No two participants were live at the same time, so the run shows no concurrency.";
+    }
+    if (world.stateChangedUnderOverlap === false) {
+        return "The shared state did not change after the participants started overlapping.";
+    }
+    return undefined;
+}
+/**
+ * A shared-world run: it passes only when every expected seat passed and the world facts have no
+ * shortfall, and otherwise fails (this route has no timed_out verdict). A dry run and a run still
+ * in progress are contracts. Lobby convergence is recorded but not read.
+ */
+export function judgeSharedWorld(args) {
+    const passed = args.participants.length === args.expected &&
+        args.participants.every(participantPassed) &&
+        sharedWorldShortfall(args.world) === undefined;
+    const verdict = args.dryRun || args.inProgress ? "contract_proof_only" : passed ? "pass" : "fail";
+    return { ...judgmentOf(verdict, args.dryRun), world: args.world };
+}
+/**
+ * A terminal run: one agent session judged as a one-participant run. It has no engagement or
+ * blocker rule; the agent's nonce-verified marker is its declared outcome.
+ */
+export function judgeTerminal(args) {
+    return judgeOneParticipant({
+        dryRun: args.dryRun,
+        inProgress: false,
+        participant: args.participant,
+    });
+}
+/**
+ * A scripted run: the worst surface decides the verdict. A harness error or a failed step fails
+ * the run, then a timeout makes it timed_out. Otherwise it passes when every expected surface
+ * passed, and fails when one did not. A session error fails it and a run with no surface results
+ * is a contract.
+ */
+export function judgeScripted(args) {
+    const { surfaces } = args;
+    const reasons = surfaces.map((surface) => surface.completionReason);
+    const passed = args.sessionError === undefined &&
+        surfaces.length === args.expected &&
+        surfaces.every(participantPassed);
+    const verdict = args.sessionError !== undefined
+        ? "fail"
+        : surfaces.length === 0
+            ? "contract_proof_only"
+            : reasons.some((reason) => reason === "harness_error" || reason === "step_failed")
+                ? "fail"
+                : reasons.some((reason) => reason === "timed_out")
+                    ? "timed_out"
+                    : passed
+                        ? "pass"
+                        : "fail";
+    return judgmentOf(verdict, args.dryRun);
+}
+/** The preview: a synthetic contract with no participants. */
+export function judgePreview() {
+    return judgmentOf("contract_proof_only", true);
+}
+/**
+ * The run's final review after scoring. Each scorer failure is recorded as a gap, and the first
+ * turns a pass or a contract into a fail with that failure as the summary. Every other verdict
+ * stays as it was, so scoring can never improve a verdict. No failures returns the review as is.
+ */
+export function foldScorerFailures(review, failures) {
+    let folded = review;
+    for (const failure of failures) {
+        folded = {
+            ...folded,
+            ...(folded.verdict === "pass" || folded.verdict === "contract_proof_only"
+                ? { verdict: "fail", summary: failure }
+                : {}),
+            gaps: folded.gaps.includes(failure) ? folded.gaps : [...folded.gaps, failure],
+        };
+    }
+    return folded;
+}
+/** The run's execution outcome under its route's policy. A failure of a kind the policy lets warn is dropped. */
+export function judgeExecution(failures, policy) {
+    const counted = failures.filter((failure) => failure.kind === "sandbox-cleanup"
+        ? policy.sandboxCleanup === "fails"
+        : failure.kind === "evidence"
+            ? policy.evidence === "fails"
+            : true);
+    return { succeeded: counted.length === 0, failures: counted };
+}
+/**
+ * The result's ok: the run worked as an execution, no scorer failed it, and on a gate route every
+ * participant passed. An evidence route ignores how its participants did.
+ */
+export function resultOk(args) {
+    return (args.execution.succeeded &&
+        args.scorerFailures.length === 0 &&
+        (args.policy.participants === "evidence" || args.judgment.passed));
+}

package/dist/run/locate.d.ts

@@ -0,0 +1,22 @@
+import { type PreparedRunArtifactPaths } from "./paths.js";
+import { type PreparedSelectedOutputDirectory } from "./contained-output.js";
+import type { RunPointer } from "./results.js";
+import { type RunBundle } from "./bundle.js";
+/** Resolve "latest" or an explicit run id to its prepared artifact paths. */
+export declare function resolveRunPath(cwd: string, runInput: string): Promise<PreparedRunArtifactPaths | null>;
+export declare function readLatest(runsRoot: PreparedSelectedOutputDirectory): Promise<RunPointer | null>;
+export declare function readRunJsonIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<unknown>;
+export declare function readRunTextIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<string | null>;
+export declare function readSafeRunArtifactBytes(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<Buffer | null>;
+export declare function readSafeRunArtifactJson(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<unknown>;
+export declare function loadRunBundle(cwdInput: string, runInput: string): Promise<{
+    bundle: RunBundle;
+    bundlePath: string;
+    runDir: string;
+} | null>;
+/** loadRunBundle for a caller that already holds prepared paths. Revalidates them first. */
+export declare function loadRunBundlePrepared(cwdInput: string, runPaths: PreparedRunArtifactPaths): Promise<{
+    bundle: RunBundle;
+    bundlePath: string;
+    runDir: string;
+} | null>;

package/dist/run/locate.js

@@ -0,0 +1,122 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveExistingRunDirectory, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "./paths.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, readContainedRegularFile, } from "./contained-output.js";
+import { RUN_BUNDLE_FILE } from "./bundle.js";
+import { isRunBundle, isRunPointer } from "./bundle-shape.js";
+import { isNodeError } from "./type-guards.js";
+/** Resolve "latest" or an explicit run id to its prepared artifact paths. */
+export async function resolveRunPath(cwd, runInput) {
+    if (runInput === "latest") {
+        const runsRoot = await bindExistingManagedHumanishOutputDirectory(cwd, "runs");
+        if (!runsRoot) {
+            return null;
+        }
+        const latest = await readLatest(runsRoot);
+        const expected = latest ? resolveLatestRunDirectory(cwd, latest) : null;
+        if (!latest || !expected) {
+            return null;
+        }
+        const runPaths = await bindExistingRunArtifactPaths(cwd, latest.runId);
+        if (runPaths.absoluteRunRoot !== expected ||
+            runPaths.physicalRunsRoot !== runsRoot.physicalPath) {
+            throw new Error("Latest run pointer changed physical runs root.");
+        }
+        await assertPreparedSelectedOutputDirectory(runsRoot);
+        return runPaths;
+    }
+    if (!isSafeRunIdSegment(runInput) || !(await resolveExistingRunDirectory(cwd, runInput))) {
+        return null;
+    }
+    return bindExistingRunArtifactPaths(cwd, runInput);
+}
+export async function readLatest(runsRoot) {
+    const latestPath = path.join(runsRoot.physicalPath, "latest.json");
+    let latestStats;
+    try {
+        latestStats = await lstat(latestPath, { bigint: true });
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+    if (latestStats.isSymbolicLink() || !latestStats.isFile() || latestStats.nlink !== 1n) {
+        throw new Error("Latest run pointer must be a single-link regular file.");
+    }
+    const bytes = await readContainedRegularFile(runsRoot, "latest.json");
+    if (!bytes) {
+        throw new Error("Latest run pointer changed while it was being read.");
+    }
+    let latest;
+    try {
+        latest = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    return isRunPointer(latest) ? latest : null;
+}
+export async function readRunJsonIfExists(runPaths, ...segments) {
+    const text = await readRunTextIfExists(runPaths, ...segments);
+    if (text === null) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readRunTextIfExists(runPaths, ...segments) {
+    const bytes = await readContainedRegularFile(runPaths, segments.join("/"));
+    return bytes?.toString("utf8") ?? null;
+}
+export async function readSafeRunArtifactBytes(runPaths, relativePath) {
+    const normalized = relativePath.replace(/\\/g, "/");
+    const segments = normalized.split("/");
+    if (path.isAbsolute(relativePath) ||
+        path.win32.isAbsolute(relativePath) ||
+        segments.length === 0 ||
+        segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+        return null;
+    }
+    return readContainedRegularFile(runPaths, normalized);
+}
+export async function readSafeRunArtifactJson(runPaths, relativePath) {
+    const bytes = await readSafeRunArtifactBytes(runPaths, relativePath);
+    if (!bytes) {
+        return null;
+    }
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function loadRunBundle(cwdInput, runInput) {
+    const cwd = path.resolve(cwdInput);
+    const runPaths = await resolveRunPath(cwd, runInput).catch(() => null);
+    if (!runPaths) {
+        return null;
+    }
+    return loadRunBundlePrepared(cwd, runPaths);
+}
+/** loadRunBundle for a caller that already holds prepared paths. Revalidates them first. */
+export async function loadRunBundlePrepared(cwdInput, runPaths) {
+    const cwd = path.resolve(cwdInput);
+    await validatePreparedRunArtifactPaths(runPaths);
+    const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
+    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    if (!isRunBundle(bundle)) {
+        return null;
+    }
+    return {
+        bundle,
+        bundlePath: path.relative(cwd, bundlePath),
+        runDir: runPaths.absoluteRunRoot,
+    };
+}

package/dist/run/outcomes.d.ts

@@ -0,0 +1,31 @@
+import { type ActorStatus } from "../actors/contract.js";
+import { type CuaGoalSource } from "../actors/goal-source.js";
+import type { TaskFunnel } from "../lab/tasks.js";
+import type { ParticipantOutcomes, ReviewSummary, StudyTaskFunnel } from "./bundle.js";
+/** Tally participant outcomes from actor statuses. Statuses this does not recognise are counted in
+ *  `total` but nowhere else, so the parts can never exceed the whole. */
+export declare function tallyParticipantOutcomes(statuses: readonly ActorStatus[], 
+/** Per-participant: did this one report friction or a defect? Same order as `statuses`. */
+reportedFriction?: readonly boolean[]): ParticipantOutcomes;
+/** Roll per-participant funnels up into the study funnel. Undefined when nothing measured one. */
+export declare function aggregateTaskFunnels(funnels: readonly TaskFunnel[]): StudyTaskFunnel | undefined;
+/** The funnel as one line, denominator on every number: `signup 2/2 · verify-email 1/2`. */
+export declare function formatStudyTaskFunnel(funnel: StudyTaskFunnel): string;
+type ParticipantOutcomeDetail = {
+    status: ActorStatus;
+    label?: string;
+    goalSource?: CuaGoalSource;
+};
+/** One line a stakeholder can read, with the denominator attached to every number. */
+export declare function formatParticipantOutcomes(outcomes: ParticipantOutcomes, terminalCauses?: readonly ParticipantOutcomeDetail[]): string;
+/** Presentation details tolerate optional legacy actor payloads without changing their tallies. */
+export declare function participantOutcomeDetails(streams: readonly {
+    actor?: unknown;
+    status?: unknown;
+}[]): ParticipantOutcomeDetail[];
+/** Refresh a CUA completion claim from recorded traces, leaving original evidence and enums intact. */
+export declare function withCuaReviewProvenance(review: ReviewSummary, streams: readonly {
+    actor?: unknown;
+    status?: unknown;
+}[]): ReviewSummary;
+export {};

package/dist/run/outcomes.js

@@ -0,0 +1,210 @@
+import { ACTOR_STATUSES } from "../actors/contract.js";
+import { cuaGoalSource, isCuaTrace, CUA_COMPLETION_NOTE, } from "../actors/goal-source.js";
+import { actorEnding } from "../actors/stop-cause.js";
+import { isNonNegativeSafeInteger, isRecord } from "./type-guards.js";
+/** Tally participant outcomes from actor statuses. Statuses this does not recognise are counted in
+ *  `total` but nowhere else, so the parts can never exceed the whole. */
+export function tallyParticipantOutcomes(statuses, 
+/** Per-participant: did this one report friction or a defect? Same order as `statuses`. */
+reportedFriction = []) {
+    const tally = {
+        total: statuses.length,
+        reachedGoal: 0,
+        abandoned: 0,
+        ranOut: 0,
+        blocked: 0,
+        harnessFailed: 0,
+        reportedFriction: reportedFriction.filter(Boolean).length,
+    };
+    for (const status of statuses) {
+        if (status === "passed")
+            tally.reachedGoal += 1;
+        else if (status === "abandoned")
+            tally.abandoned += 1;
+        else if (status === "incomplete" || status === "timed_out")
+            tally.ranOut += 1;
+        else if (status === "blocked")
+            tally.blocked += 1;
+        else if (status === "failed")
+            tally.harnessFailed += 1;
+    }
+    return tally;
+}
+/** Roll per-participant funnels up into the study funnel. Undefined when nothing measured one. */
+export function aggregateTaskFunnels(funnels) {
+    if (funnels.length === 0)
+        return undefined;
+    const order = [];
+    const byId = new Map();
+    for (const funnel of funnels) {
+        for (const task of funnel.tasks) {
+            let entry = byId.get(task.id);
+            if (entry === undefined) {
+                entry = { completed: 0, sessions: 0, observable: false, unmeasured: 0 };
+                byId.set(task.id, entry);
+                order.push(task.id);
+            }
+            entry.sessions += 1;
+            if (task.completed)
+                entry.completed += 1;
+            if (task.observable)
+                entry.observable = true;
+            if (task.inputsObserved === false)
+                entry.unmeasured += 1;
+        }
+    }
+    return {
+        sessions: funnels.length,
+        tasks: order.map((id) => {
+            const entry = byId.get(id);
+            return {
+                id,
+                completed: entry.completed,
+                sessions: entry.sessions,
+                observable: entry.observable,
+                unmeasured: entry.unmeasured,
+            };
+        }),
+    };
+}
+/** The funnel as one line, denominator on every number: `signup 2/2 · verify-email 1/2`. */
+export function formatStudyTaskFunnel(funnel) {
+    if (funnel.tasks.length === 0)
+        return "no tasks declared";
+    return funnel.tasks
+        .map((task) => {
+        if (!task.observable)
+            return `${task.id} (no completion criterion)`;
+        // A count that is entirely unmeasured must not render as a bare "0/3": that reads as a
+        // participant failure when it is our observer that produced nothing.
+        if (task.unmeasured === task.sessions) {
+            return `${task.id} (never measured in ${task.sessions})`;
+        }
+        const caveat = task.unmeasured > 0 ? ` (${task.unmeasured} never measured)` : "";
+        return `${task.id} ${task.completed}/${task.sessions}${caveat}`;
+    })
+        .join(" · ");
+}
+function participantCompletionLine(outcomes, terminalCauses) {
+    const completions = terminalCauses.filter((entry) => entry.status === "passed");
+    const reported = completions.filter((entry) => entry.goalSource === "participant_report").length;
+    const matched = completions.filter((entry) => entry.goalSource === "condition_matched").length;
+    let goalLine = outcomes.reachedGoal === 0
+        ? `0/${outcomes.total} recorded completions`
+        : `${outcomes.reachedGoal}/${outcomes.total} reached the goal`;
+    if (outcomes.reachedGoal > 0 && terminalCauses.some((entry) => entry.goalSource !== undefined)) {
+        const count = `${outcomes.reachedGoal}/${outcomes.total}`;
+        goalLine =
+            completions.length !== outcomes.reachedGoal
+                ? `${count} recorded completions (completion source unavailable)`
+                : reported === outcomes.reachedGoal
+                    ? `${count} reported reaching the goal`
+                    : matched === outcomes.reachedGoal
+                        ? `${count} met a recorded completion condition`
+                        : `${count} recorded completions (${[
+                            reported > 0 ? `${reported} participant-reported` : undefined,
+                            matched > 0 ? `${matched} condition-matched` : undefined,
+                            outcomes.reachedGoal - reported - matched > 0
+                                ? `${outcomes.reachedGoal - reported - matched} other or unavailable source`
+                                : undefined,
+                        ]
+                            .filter(Boolean)
+                            .join(", ")})`;
+    }
+    return goalLine;
+}
+/** One line a stakeholder can read, with the denominator attached to every number. */
+export function formatParticipantOutcomes(outcomes, terminalCauses = []) {
+    if (outcomes.total === 0)
+        return "no participants reached a terminal state";
+    const parts = [participantCompletionLine(outcomes, terminalCauses)];
+    // Detail may explain a recorded outcome, but must never change its count or invent a match
+    // between a tally and an incomplete set of traces.
+    const append = (count, statuses, fallback) => {
+        if (count === 0)
+            return;
+        const matching = terminalCauses.filter((entry) => statuses.includes(entry.status));
+        if (matching.length !== count) {
+            parts.push(`${count} ${fallback}`);
+            return;
+        }
+        const counts = new Map();
+        for (const entry of matching) {
+            const description = entry.label === undefined ? fallback : `interrupted (${entry.label})`;
+            counts.set(description, (counts.get(description) ?? 0) + 1);
+        }
+        for (const [description, n] of counts)
+            parts.push(`${n} ${description}`);
+    };
+    append(outcomes.abandoned, ["abandoned"], "gave up");
+    append(outcomes.ranOut, ["incomplete", "timed_out"], "interrupted (stop details unavailable)");
+    // "blocked" covers an approval the run could not give AND a blocker the participant reported in
+    // its own words, so the label names no cause.
+    if (outcomes.blocked > 0)
+        parts.push(`${outcomes.blocked} blocked`);
+    append(outcomes.harnessFailed, ["failed"], "lost to a harness failure");
+    // Last, and separate, because it cuts across the outcomes rather than partitioning them: someone
+    // can reach the goal and still have found the road there broken.
+    if (outcomes.reportedFriction > 0)
+        parts.push(`${outcomes.reportedFriction} reported friction`);
+    return parts.join(", ");
+}
+/** Presentation details tolerate optional legacy actor payloads without changing their tallies. */
+export function participantOutcomeDetails(streams) {
+    return streams.flatMap((stream) => {
+        if (!isRecord(stream.actor))
+            return [];
+        const actor = stream.actor;
+        const goalSource = cuaGoalSource(actor, stream.status);
+        if (!ACTOR_STATUSES.includes(String(actor.status))) {
+            return goalSource === "unavailable" ? [{ status: "passed", goalSource }] : [];
+        }
+        const ending = Array.isArray(actor.items) && actor.items.every(isRecord)
+            ? actorEnding(actor)
+            : undefined;
+        return [
+            {
+                status: actor.status,
+                ...(ending === undefined ? {} : { label: ending.label }),
+                ...(goalSource === undefined ? {} : { goalSource }),
+            },
+        ];
+    });
+}
+/** Refresh a CUA completion claim from recorded traces, leaving original evidence and enums intact. */
+export function withCuaReviewProvenance(review, streams) {
+    const details = participantOutcomeDetails(streams);
+    if (!isRecord(review.participants) ||
+        ![
+            "total",
+            "reachedGoal",
+            "abandoned",
+            "ranOut",
+            "blocked",
+            "harnessFailed",
+            "reportedFriction",
+        ].every((key) => isNonNegativeSafeInteger(review.participants[key])) ||
+        (review.participants.reachedGoal === 0
+            ? !streams.some((stream) => isCuaTrace(stream.actor))
+            : !details.some((entry) => entry.goalSource !== undefined)))
+        return review;
+    const outcomes = formatParticipantOutcomes(review.participants, details);
+    // Preserve rerun context, participant narration and adapter-specific findings. Refreshing a
+    // historical summary qualifies its old tally instead of silently discarding that context.
+    const header = `Run gate: ${review.verdict}. Participants: ${outcomes}.${review.tasks ? ` Tasks: ${formatStudyTaskFunnel(review.tasks)}.` : ""}`;
+    const prefix = `${header} Recorded summary: `;
+    const recorded = review.summary.startsWith(prefix)
+        ? review.summary.slice(prefix.length)
+        : review.summary;
+    const oldGoal = `${review.participants.reachedGoal}/${review.participants.total} reached the goal`;
+    const qualified = recorded
+        .split(oldGoal)
+        .join(participantCompletionLine(review.participants, details));
+    return {
+        ...review,
+        summary: `${prefix}${qualified}`,
+        gaps: review.participants.reachedGoal === 0
+            ? review.gaps
+            : [...review.gaps.filter((gap) => gap !== CUA_COMPLETION_NOTE), CUA_COMPLETION_NOTE],
+    };
+}

package/dist/run/participant-records.d.ts

@@ -0,0 +1,28 @@
+import type { RunEvent, RunProviderResource, RunSimulation } from "./bundle.js";
+import type { RunStream } from "./streams.js";
+/** The ids a participant's saved records carry: its record id and its stream id. */
+export interface ParticipantIds {
+    readonly recordId: string;
+    readonly streamId: string;
+}
+/** Ids a route chose itself, for routes whose ids are not the `sim-NNN` default. */
+export declare function participantIdsOf(recordId: string, streamId: string): ParticipantIds;
+/** The default ids of the participant at a 0-based position: `sim-001` and `stream-001` first. */
+export declare function participantIds(position: number): ParticipantIds;
+/** A participant's record, at its 1-based place in the bundle, with its one stream. */
+export declare function participantRecord(ids: ParticipantIds, place: number, fields: Omit<RunSimulation, "id" | "index" | "streamIds">): RunSimulation;
+/**
+ * A participant's stream. `participantId` is the route's own participant id (a fan-out lane's id),
+ * saved right after the record id when the route has one.
+ */
+export declare function participantStream(ids: ParticipantIds, fields: Omit<RunStream, "id" | "simId" | "laneId">, participantId?: string): RunStream;
+/** An event about one participant. */
+export declare function participantEvent(ids: ParticipantIds, event: Omit<RunEvent, "simId" | "streamId">): RunEvent;
+/** The ids a provider resource saves for the participant whose sandbox it is. */
+export declare function participantResourceIds(ids: ParticipantIds, participantId: string): Required<Pick<RunProviderResource, "simId" | "streamId" | "laneId">>;
+/** The record id a saved stream belongs to. */
+export declare function recordIdOf(stream: RunStream): string;
+/** The record id a saved event names, when it names one. */
+export declare function eventRecordIdOf(event: RunEvent): string | undefined;
+/** The participant id an adapter recorded on a saved stream (a fan-out lane id), when it has one. */
+export declare function streamParticipantIdOf(stream: RunStream): string | undefined;