humanish 0.107.0 → 0.108.0

package/dist/run/stats.js

@@ -5,12 +5,10 @@ import path from "node:path";
 import { readRunIndex } from "./run-index.js";
 import { addCostTotals, emptyCostTotals, readCostTotals, } from "./costs.js";
 import { round6 } from "./pricing.js";
-const STATS_SCHEMA = "humanish.stats.v1";
-const STATS_NOTE = "Every dollar figure is a retained rate-table estimate, never a provider charge. " +
-    "Known spend includes participant/desktop estimates and all distinct recorded analysis attempts; reuse is counted once. " +
-    "Unknown amounts are excluded, not $0. Missing historical attempts cannot be reconstructed. " +
-    "Analysis is attributed to its run's start date, including later reruns. " +
-    "JSON estimatedSpendUsd and medianCostUsd retain their participant/desktop-only meaning; costs includes analysis.";
+import { plural } from "./text.js";
+const STATS_SCHEMA = "humanish.stats.v2";
+// docs/contracts/study-costs.md holds the accounting rules this sentence summarizes.
+const STATS_NOTE = "Dollar figures are estimates from humanish's rate table, never provider charges, and a cost humanish does not know is left out of every total.";
 function median(values) {
     if (values.length === 0)
         return undefined;
@@ -28,15 +26,26 @@ function addParticipants(into, entry) {
     into.reachedGoal += entry.participants.reachedGoal;
     into.reportedFriction += entry.participants.reportedFriction ?? 0;
 }
+/**
+ * A run's participant and desktop estimate: its recorded figure, or $0 for a dry run that records
+ * none, since a dry run makes no model request and creates no desktop. Undefined when the cost is
+ * unknown, including a dry run that records an unknown (null) figure.
+ */
+function runEstimateUsd(entry) {
+    const usd = entry.estimatedCostUsd;
+    if (typeof usd === "number" && Number.isFinite(usd) && usd >= 0)
+        return usd;
+    return usd === undefined && entry.mode === "dry-run" ? 0 : undefined;
+}
 function entryTime(entry) {
     return entry.startedAt ?? entry.completedAt ?? entry.updatedAt;
 }
-function addToLabRow(labs, entry, priced, costs) {
-    const labId = entry.lab?.id ?? "(no lab)";
+function addToLabRow(labs, entry, runUsd, costs) {
+    const labId = entry.study?.id ?? "(no study)";
     let row = labs.get(labId);
     if (row === undefined) {
         row = {
-            lab: labId,
+            study: labId,
             runs: 0,
             live: 0,
             dryRun: 0,
@@ -64,14 +73,14 @@ function addToLabRow(labs, entry, priced, costs) {
     }
     if (entry.mode === "live" && entry.durationMs !== undefined)
         row.durations.push(entry.durationMs);
-    if (priced)
-        row.runCosts.push(entry.estimatedCostUsd);
-    else
+    if (runUsd === undefined)
         row.unpricedRuns += 1;
+    else
+        row.runCosts.push(runUsd);
     addParticipants(row.participants, entry);
     addCostTotals(row.costs, costs);
 }
-function addToDayRow(days, entry, priced, costs) {
+function addToDayRow(days, entry, runUsd, costs) {
     const at = entryTime(entry);
     const day = at === undefined ? "(undated)" : at.slice(0, 10);
     let dayRow = days.get(day);
@@ -89,10 +98,10 @@ function addToDayRow(days, entry, priced, costs) {
     dayRow.runs += 1;
     if (entry.mode === "live")
         dayRow.live += 1;
-    if (priced)
-        dayRow.estimatedSpendUsd += entry.estimatedCostUsd;
-    else
+    if (runUsd === undefined)
         dayRow.unpricedRuns += 1;
+    else
+        dayRow.estimatedSpendUsd += runUsd;
     addCostTotals(dayRow.costs, costs);
 }
 export async function computeStats(cwdInput, options = {}) {
@@ -127,7 +136,7 @@ export async function computeStats(cwdInput, options = {}) {
         })),
     ];
     const selected = entries.filter((entry) => {
-        if (options.lab !== undefined && entry.lab?.id !== options.lab)
+        if (options.lab !== undefined && entry.study?.id !== options.lab)
             return false;
         if (sinceMs !== undefined) {
             const at = entryTime(entry);
@@ -164,18 +173,16 @@ export async function computeStats(cwdInput, options = {}) {
             totals.dryRun += 1;
         if (entry.liveness === "running")
             totals.running += 1;
-        const priced = typeof entry.estimatedCostUsd === "number" &&
-            Number.isFinite(entry.estimatedCostUsd) &&
-            entry.estimatedCostUsd >= 0;
-        if (priced)
-            totals.estimatedSpendUsd += entry.estimatedCostUsd;
-        else
+        const runUsd = runEstimateUsd(entry);
+        if (runUsd === undefined)
             totals.unpricedRuns += 1;
+        else
+            totals.estimatedSpendUsd += runUsd;
         addParticipants(totals.participants, entry);
         if (entry.verdict !== undefined)
             totals.verdicts[entry.verdict] = (totals.verdicts[entry.verdict] ?? 0) + 1;
-        addToLabRow(labs, entry, priced, accounting.costs);
-        addToDayRow(days, entry, priced, accounting.costs);
+        addToLabRow(labs, entry, runUsd, accounting.costs);
+        addToDayRow(days, entry, runUsd, accounting.costs);
     }
     const labRows = [...labs.values()]
         .map(({ durations, runCosts, ...row }) => ({
@@ -186,15 +193,15 @@ export async function computeStats(cwdInput, options = {}) {
         ...(runCosts.length === 0 ? {} : { medianCostUsd: round6(median(runCosts)) }),
         costSamples: runCosts.length,
     }))
-        .sort((a, b) => b.runs - a.runs || a.lab.localeCompare(b.lab));
+        .sort((a, b) => b.runs - a.runs || a.study.localeCompare(b.study));
     return {
         schema: STATS_SCHEMA,
         ok: true,
         cwd,
         ...(options.since === undefined ? {} : { since: options.since }),
-        ...(options.lab === undefined ? {} : { lab: options.lab }),
+        ...(options.lab === undefined ? {} : { study: options.lab }),
         totals: { ...totals, estimatedSpendUsd: round6(totals.estimatedSpendUsd) },
-        labs: labRows,
+        studies: labRows,
         days: [...days.values()]
             .map((row) => ({ ...row, estimatedSpendUsd: round6(row.estimatedSpendUsd) }))
             .sort((a, b) => a.day.localeCompare(b.day)),
@@ -212,47 +219,98 @@ function knownMoney(value) {
 function minutes(ms) {
     return `${(ms / 60_000).toFixed(1)}m`;
 }
+/**
+ * Whether every selected run is a dry run whose accounting is a complete $0: no recorded figure,
+ * no incomplete estimate and no analysis attempt. Only then does the one-line report hold.
+ */
+function onlyFreeDryRuns(t) {
+    return (t.runs > 0 &&
+        t.runs === t.dryRun &&
+        t.costs.estimatedTotalUsd === 0 &&
+        t.costs.incompleteRunEstimates === 0 &&
+        t.costs.analysisAttempts === 0);
+}
+/** The run counts, with dry runs on their own line. */
+function runCountLines(t) {
+    if (t.runs === 0)
+        return ["no runs yet; start one with humanish run first-run"];
+    if (onlyFreeDryRuns(t))
+        return [`${plural(t.dryRun, "dry run")} ($0); no live runs yet`];
+    const running = t.running > 0 ? ` (${t.running} still running)` : "";
+    return [`live runs: ${t.live}${running}`, ...(t.dryRun > 0 ? [`dry runs: ${t.dryRun}`] : [])];
+}
+/** Spend, analysis, participants and verdicts across the selected live runs. */
+function totalsLines(t) {
+    const c = t.costs;
+    const incomplete = c.incompleteRunEstimates > 0
+        ? `; ${plural(c.incompleteRunEstimates, "run")} with incomplete accounting`
+        : "";
+    const unpriced = c.analysisUnpricedAttempts > 0 || c.analysisUnresolvedAttempts > 0
+        ? `; ${c.analysisUnpricedAttempts} unpriced, ${c.analysisUnresolvedAttempts} unresolved`
+        : "";
+    const verdicts = Object.entries(t.verdicts).map(([verdict, count]) => `${verdict} ${count}`);
+    return [
+        `known estimated spend: ${knownMoney(c.estimatedTotalUsd)}`,
+        `participants and desktops: ${knownMoney(c.runEstimatedUsd)}${incomplete}`,
+        c.analysisAttempts === 0
+            ? "analysis: none recorded"
+            : `analysis: ${knownMoney(c.analysisEstimatedUsd)} over ${plural(c.analysisAttempts, "recorded attempt")}${unpriced}`,
+        ...(c.analysisHistoryUncertainRuns > 0
+            ? [
+                `analysis history: ${plural(c.analysisHistoryUncertainRuns, "run")} missing or uncertain; --json lists each run`,
+            ]
+            : []),
+        ...(t.participants.total > 0
+            ? [
+                `participants: ${t.participants.reachedGoal} of ${t.participants.total} reached the goal, ${t.participants.reportedFriction} reported friction`,
+            ]
+            : []),
+        ...(verdicts.length > 0 ? [`verdicts: ${verdicts.join(", ")}`] : []),
+    ];
+}
+function dayLine(row) {
+    return `- ${row.day}: ${plural(row.runs, "run")}, ${row.live} live, known study spend ${knownMoney(row.costs.estimatedTotalUsd)}${unpricedTail(row.unpricedRuns, row.costs.analysisUnpricedAttempts)}`;
+}
+/** "; 2 unpriced runs, 1 unpriced analysis", or nothing when both are zero. */
+function unpricedTail(runs, analyses) {
+    if (runs === 0 && analyses === 0)
+        return "";
+    return `; ${plural(runs, "unpriced run")}, ${plural(analyses, "unpriced analysis", "unpriced analyses")}`;
+}
 export function formatStatsHuman(result) {
     if (!result.ok)
-        return `${result.error.code}: ${result.error.message}\n`;
+        return { error: result.error };
     const t = result.totals;
     const scope = [
-        result.lab === undefined ? undefined : `lab ${result.lab}`,
+        result.study === undefined ? undefined : `lab ${result.study}`,
         result.since === undefined ? undefined : `since ${result.since}`,
     ].filter((part) => part !== undefined);
     const lines = [
         `humanish stats${scope.length === 0 ? "" : ` (${scope.join(", ")})`}`,
-        `runs: ${t.runs} (${t.live} live, ${t.dryRun} dry-run${t.running > 0 ? `, ${t.running} running` : ""})`,
-        `known estimated spend: ${knownMoney(t.costs.estimatedTotalUsd)}`,
-        `participants + desktops: ${knownMoney(t.costs.runEstimatedUsd)}; ${t.costs.incompleteRunEstimates} run(s) with incomplete accounting`,
-        `analysis: ${knownMoney(t.costs.analysisEstimatedUsd)} over ${t.costs.analysisAttempts} recorded attempt(s); ${t.costs.analysisUnpricedAttempts} unpriced, ${t.costs.analysisUnresolvedAttempts} unresolved`,
-        `analysis history: ${t.costs.analysisHistoryUncertainRuns} run(s) missing or uncertain; use --json for per-run accounting`,
-        `participants: ${t.participants.reachedGoal}/${t.participants.total} recorded goal completions, ${t.participants.reportedFriction} reported friction`,
-        `verdicts: ${Object.entries(t.verdicts)
-            .map(([verdict, count]) => `${verdict} ${count}`)
-            .join(", ") || "none recorded"}`,
+        ...runCountLines(t),
     ];
-    if (result.labs.length > 0) {
-        lines.push("", "per lab:");
-        for (const row of result.labs) {
-            const rate = row.passRate === undefined ? "no verdicts" : `${row.passed}/${row.judged} pass`;
-            const duration = row.medianDurationMs === undefined
-                ? "no timed live runs"
-                : `median ${minutes(row.medianDurationMs)} over ${row.durationSamples}`;
-            const cost = row.medianCostUsd === undefined
-                ? "no priced participant/desktop runs"
-                : `participant/desktop median ${money(row.medianCostUsd)} over ${row.costSamples}`;
-            lines.push(`- ${row.lab}: ${row.runs} run(s), ${row.live} live; ${rate}; ${duration}; known study spend ${knownMoney(row.costs.estimatedTotalUsd)}; ${cost}; ${row.unpricedRuns} unpriced runs, ${row.costs.analysisUnpricedAttempts} unpriced analyses`);
-        }
-    }
-    if (result.days.length > 0) {
-        lines.push("", "by day:");
-        for (const row of result.days) {
-            lines.push(`- ${row.day}: ${row.runs} run(s), ${row.live} live, known study spend ${knownMoney(row.costs.estimatedTotalUsd)}, ${row.unpricedRuns} unpriced runs, ${row.costs.analysisUnpricedAttempts} unpriced analyses`);
-        }
+    // Free dry runs alone have no spend, outcome or duration to report. Anything else, an unreadable
+    // directory or a dry run that records a cost included, gets the full report.
+    const reportable = t.runs > 0 && !onlyFreeDryRuns(t);
+    if (reportable) {
+        lines.push(...totalsLines(t));
+        if (result.studies.length > 0)
+            lines.push("", "per lab:", ...result.studies.map((row) => {
+                const rate = row.passRate === undefined ? "no verdicts" : `${row.passed} of ${row.judged} passed`;
+                const duration = row.medianDurationMs === undefined
+                    ? "no timed live runs"
+                    : `median ${minutes(row.medianDurationMs)} over ${row.durationSamples}`;
+                const cost = row.medianCostUsd === undefined
+                    ? "no priced participant/desktop runs"
+                    : `participant/desktop median ${money(row.medianCostUsd)} over ${row.costSamples}`;
+                return `- ${row.study}: ${plural(row.runs, "run")}, ${row.live} live; ${rate}; ${duration}; known study spend ${knownMoney(row.costs.estimatedTotalUsd)}; ${cost}${unpricedTail(row.unpricedRuns, row.costs.analysisUnpricedAttempts)}`;
+            }));
+        if (result.days.length > 0)
+            lines.push("", "by day:", ...result.days.map(dayLine));
     }
     if (result.unreadable.length > 0)
         lines.push("", `unreadable run directories: ${result.unreadable.join(", ")}`);
-    lines.push("", result.note);
+    if (reportable)
+        lines.push("", result.note);
     return `${lines.join("\n")}\n`;
 }

package/dist/run/status.d.ts

@@ -1,4 +1,5 @@
 import type { RunBundle } from "./bundle.js";
+import { type RunStudyProvenance } from "./study-provenance.js";
 import { type PreparedOutputRoot } from "./contained-output.js";
 import type { ExecutionOutcome } from "./judge.js";
 export declare const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
@@ -12,15 +13,6 @@ export declare const RUN_STATUS_TOUCH_MS = 5000;
  * slack so an ordinary scheduling hiccup or a slow disk never mislabels a healthy run.
  */
 export declare const RUN_STATUS_STALE_MS: number;
-/** Which manifest a run came from, when it came from one. */
-export interface RunLabProvenance {
-    /** The lab id as declared in its manifest (`config.id`). */
-    id: string;
-    /** Repo-relative manifest path, when the run came from a file on disk. */
-    path?: string;
-    /** `committed` = humanish/labs, `ignored` = a local overlay, `explicit` = a path the operator passed. */
-    origin?: "committed" | "ignored" | "explicit";
-}
 type RunStatusState = "running" | "finished" | "interrupted";
 /** The signals the CLI's run handler records when it stops a run. */
 export type RunInterruptSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
@@ -49,8 +41,10 @@ export interface RunStatusRecord {
     runId: string;
     state: RunStatusState;
     mode: "dry-run" | "live";
-    /** Absent when the run did not come from a lab manifest (a library caller, a bare `run`). */
-    lab?: RunLabProvenance;
+    /** Absent when the run did not come from a study file (a library caller, a bare `run`). */
+    study?: RunStudyProvenance;
+    /** `study`'s value, written beside it until 0.109. Read either through studyProvenanceOf. */
+    lab?: RunStudyProvenance;
     /** The pid that owns the run, for local liveness checks. */
     pid: number;
     startedAt: string;
@@ -68,7 +62,7 @@ export interface RunStatusHandle {
      *  still has a record to classify. */
     readonly started: Promise<void>;
     /** Finalize: state `finished`, `completedAt`, and the derived outcome. Stops the cadence.
-     *  Idempotent — a second call is a no-op, so a backend with several exit paths is safe. */
+     *  Idempotent: a second call is a no-op, so a route with several exit paths is safe. */
     finish(outcome?: RunStatusOutcome): Promise<void>;
     /** After finish, add the result's ok and execution outcome to the finished record, so status.json
      *  and the result agree. Before finish it does nothing. */
@@ -85,12 +79,12 @@ export interface RunStatusHandle {
 export interface BeginRunStatusOptions {
     runId: string;
     mode: "dry-run" | "live";
-    lab?: RunLabProvenance | undefined;
+    lab?: RunStudyProvenance | undefined;
 }
 /**
  * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
  * fails must never fail the run it describes, so every write swallows its error. The interval is
- * `unref`'d — this file can never be the reason a process stays alive.
+ * `unref`'d, so this file can never be the reason a process stays alive.
  */
 export declare function beginRunStatus(runPaths: PreparedOutputRoot, options: BeginRunStatusOptions): RunStatusHandle;
 /** The three ways a run reads from disk. `interrupted` is a record its stopped process wrote, or a
@@ -103,19 +97,4 @@ export type RunLiveness = "running" | "interrupted" | "finished";
 export declare function classifyRunStatus(record: Pick<RunStatusRecord, "state" | "updatedAt">, nowMs: number, staleMs?: number): RunLiveness;
 /** Shape guard for a record read off disk. Unknown extra fields are tolerated (additive contract). */
 export declare function isRunStatusRecord(value: unknown): value is RunStatusRecord;
-/**
- * The legacy bridge: infer a lab id for a bundle written before this contract, where the only
- * attribution was the `lab:<id>` convention on persona/scenario source strings. Deliberately
- * conservative — it reads the convention and nothing else, and a `lab:` prefix with an empty
- * remainder is not an id. Ids may contain colons (the removed meta-lab wrote `oss:meta`), so
- * only the first segment is stripped. Returns undefined when the bundle carries no such marker.
- */
-export declare function inferLegacyLabId(bundle: {
-    persona?: {
-        source?: string;
-    };
-    scenario?: {
-        source?: string;
-    };
-}): string | undefined;
 export {};

package/dist/run/status.js

@@ -9,6 +9,7 @@
 // Public safety: it holds only the run id, the lab id/path/origin (the strings `humanish lab list`
 // prints), the mode, a local pid and timestamps. It holds no hostname or user/path identity: an
 // operator may share the run directory, so a share-safety gate must have nothing to strip here.
+import { isProvenanceField, studyFields } from "./study-provenance.js";
 import { writeContainedOutputFile } from "./contained-output.js";
 import { redactText } from "../evidence/redaction.js";
 export const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
@@ -46,7 +47,7 @@ export function runStatusOutcome(bundle) {
 /**
  * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
  * fails must never fail the run it describes, so every write swallows its error. The interval is
- * `unref`'d — this file can never be the reason a process stays alive.
+ * `unref`'d, so this file can never be the reason a process stays alive.
  */
 export function beginRunStatus(runPaths, options) {
     const iso = () => new Date().toISOString();
@@ -56,7 +57,7 @@ export function beginRunStatus(runPaths, options) {
         runId: options.runId,
         state: "running",
         mode: options.mode,
-        ...(options.lab === undefined ? {} : { lab: options.lab }),
+        ...studyFields(options.lab),
         pid: process.pid,
         startedAt,
         updatedAt: startedAt,
@@ -170,30 +171,7 @@ export function isRunStatusRecord(value) {
         return false;
     if (typeof record.startedAt !== "string" || typeof record.updatedAt !== "string")
         return false;
-    if (record.lab !== undefined) {
-        if (record.lab === null || typeof record.lab !== "object")
-            return false;
-        if (typeof record.lab.id !== "string")
-            return false;
-    }
+    if (!isProvenanceField(record.study) || !isProvenanceField(record.lab))
+        return false;
     return true;
 }
-/**
- * The legacy bridge: infer a lab id for a bundle written before this contract, where the only
- * attribution was the `lab:<id>` convention on persona/scenario source strings. Deliberately
- * conservative — it reads the convention and nothing else, and a `lab:` prefix with an empty
- * remainder is not an id. Ids may contain colons (the removed meta-lab wrote `oss:meta`), so
- * only the first segment is stripped. Returns undefined when the bundle carries no such marker.
- */
-export function inferLegacyLabId(bundle) {
-    for (const source of [bundle.persona?.source, bundle.scenario?.source]) {
-        if (typeof source !== "string")
-            continue;
-        if (!source.startsWith("lab:"))
-            continue;
-        const id = source.slice("lab:".length).trim();
-        if (id !== "")
-            return id;
-    }
-    return undefined;
-}

package/dist/run/stored-runs.js

@@ -1,4 +1,5 @@
 import { lstat, readdir } from "node:fs/promises";
+import { runNotFoundMessage } from "./run-not-found.js";
 import path from "node:path";
 import { redactText } from "../evidence/redaction.js";
 import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, resolveRunsRoot, validatePreparedRunArtifactPaths, } from "./paths.js";
@@ -66,7 +67,7 @@ export async function cleanupRun(cwdInput, runInput, hooks = {}) {
     if (!resolved) {
         return cleanupRefusal(cwd, runInput, checkedAt, {
             code: "HUMANISH_RUN_NOT_FOUND",
-            message: `Run not found: ${runInput}`,
+            message: await runNotFoundMessage(cwd, runInput),
         });
     }
     const runPaths = resolved;

package/dist/run/stream-shape.js

@@ -140,7 +140,7 @@ export function isRunSimulationStatus(value) {
         value === "running" ||
         value === "passed" ||
         // Participant outcomes (docs/principles/three-roles.md). This runtime allowlist is the actual
-        // gate — the TS union alone does not validate a bundle read back from disk.
+        // gate; the TS union alone does not validate a bundle read back from disk.
         value === "abandoned" ||
         value === "incomplete" ||
         value === "complete" ||

package/dist/run/streams.d.ts

@@ -70,8 +70,8 @@ export interface RunDesktopGeometry {
          * Without this, a floored run is indistinguishable from a faithful one: `verified` compares
          * the floored number with itself and reports a match, so a reader of the bundle sees
          * requested 500 / verified 500 and reasonably concludes a 500-wide preset was asked for. A
-         * `mobile` (414) and a `small-mobile` (360) seat both render at 500 and look identical here.
-         * When this field is set, the preset width did not render; see #221.
+         * `mobile` (414) and a `small-mobile` (360) participant both render at 500 and look identical
+         * here. When this field is set, the preset width did not render.
          */
         declared?: {
             width: number;
@@ -96,7 +96,7 @@ export interface RunDesktopGeometry {
         source: "cdp";
     };
     /**
-     * Mobile fidelity beyond viewport size (#221), present only when the lab asked for it. `requested`
+     * Mobile fidelity beyond viewport size, present only when the lab asked for it. `requested`
      * is what was applied through CDP; `resolved` is what the page reported about itself afterwards
      * and is the proof, never copied from the request. A run without this block is a
      * responsive-viewport study, whatever its preset is named.
@@ -122,7 +122,7 @@ export interface RunDesktopGeometry {
         };
         /**
          * Page targets the participant drove after the launch page (a link that opened in a new tab)
-         * whose own read-back reported the requested viewport width (#623). Absent when the
+         * whose own read-back reported the requested viewport width. Absent when the
          * participant never left the launch tab; a later tab that did not report the width is a
          * participant warning instead.
          */
@@ -234,9 +234,9 @@ export interface RunStream {
     };
     actor?: ActorTrace;
     /**
-     * Mid-run partial actor evidence (#441): the redacted trace items recorded so far,
+     * Mid-run partial actor evidence: the redacted trace items recorded so far,
      * flushed while a live participant is still running so the attached Observer's timeline can
-     * grow. It is deliberately not an ActorTrace: a running participant has no honest status,
+     * grow. It is deliberately not an ActorTrace: a running participant has no final status,
      * completionReason, or completedAt, and this shape cannot claim them. Present only on
      * `inProgress` bundles; the final write replaces it with the real `actor` and never
      * carries it.

package/dist/run/study-provenance.d.ts

@@ -0,0 +1,47 @@
+/** Which study a run came from, when it came from one. */
+export interface RunStudyProvenance {
+    /** The study id its file declares (`config.id`). */
+    id: string;
+    /** Project-relative path of the study file, when the run came from a file on disk. */
+    path?: string;
+    /**
+     * `committed` = humanish/studies or humanish/labs, `ignored` = a local overlay, `explicit` = a
+     * path the operator passed.
+     */
+    origin?: "committed" | "ignored" | "explicit";
+}
+/** Whether a saved record's `study` or `lab` field is absent or shaped like a provenance. */
+export declare function isProvenanceField(value: unknown): boolean;
+/**
+ * A saved record's study: a valid `study`, else a valid `lab`, else the id its persona or scenario
+ * source names by convention.
+ */
+export declare function studyProvenanceOf(record: {
+    study?: unknown;
+    lab?: unknown;
+    persona?: {
+        source?: unknown;
+    };
+    scenario?: {
+        source?: unknown;
+    };
+}): RunStudyProvenance | undefined;
+/** `study` and `lab` with the same value, as run.json and status.json write them until 0.109. */
+export declare function studyFields(study: RunStudyProvenance | undefined): {
+    study?: RunStudyProvenance;
+    lab?: RunStudyProvenance;
+};
+/**
+ * The study id a run names by the `study:<id>` or `lab:<id>` convention on its persona or scenario
+ * source, the only attribution a run written before `lab` and `study` has. A prefix with an empty
+ * remainder is not an id. Ids may contain colons (`lab:oss:meta`), so only the prefix is stripped.
+ * Readers keep both prefixes for good: saved runs say `lab:`.
+ */
+export declare function inferLegacyStudyId(bundle: {
+    persona?: {
+        source?: unknown;
+    };
+    scenario?: {
+        source?: unknown;
+    };
+}): string | undefined;

package/dist/run/study-provenance.js

@@ -0,0 +1,63 @@
+// Which study a saved run came from. run.json and status.json write it as `study`, and as `lab`
+// with the same value until 0.109 drops `lab`. Every reader goes through
+// studyProvenanceOf, which also reads a run older than both fields by the `study:<id>` or
+// `lab:<id>` convention on its persona and scenario sources.
+const ORIGINS = ["committed", "ignored", "explicit"];
+/** `value` as a provenance when it has an id, keeping only its fields that are valid. */
+function provenance(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const record = value;
+    if (typeof record.id !== "string" || record.id === "")
+        return undefined;
+    const origin = record.origin;
+    return {
+        id: record.id,
+        ...(typeof record.path === "string" ? { path: record.path } : {}),
+        ...(typeof origin === "string" && ORIGINS.includes(origin)
+            ? { origin: origin }
+            : {}),
+    };
+}
+/** Whether a saved record's `study` or `lab` field is absent or shaped like a provenance. */
+export function isProvenanceField(value) {
+    if (value === undefined)
+        return true;
+    if (value === null || typeof value !== "object")
+        return false;
+    return typeof value.id === "string";
+}
+/**
+ * A saved record's study: a valid `study`, else a valid `lab`, else the id its persona or scenario
+ * source names by convention.
+ */
+export function studyProvenanceOf(record) {
+    const declared = provenance(record.study) ?? provenance(record.lab);
+    if (declared !== undefined)
+        return declared;
+    const id = inferLegacyStudyId(record);
+    return id === undefined ? undefined : { id };
+}
+/** `study` and `lab` with the same value, as run.json and status.json write them until 0.109. */
+export function studyFields(study) {
+    return study === undefined ? {} : { study, lab: study };
+}
+/**
+ * The study id a run names by the `study:<id>` or `lab:<id>` convention on its persona or scenario
+ * source, the only attribution a run written before `lab` and `study` has. A prefix with an empty
+ * remainder is not an id. Ids may contain colons (`lab:oss:meta`), so only the prefix is stripped.
+ * Readers keep both prefixes for good: saved runs say `lab:`.
+ */
+export function inferLegacyStudyId(bundle) {
+    for (const source of [bundle.persona?.source, bundle.scenario?.source]) {
+        if (typeof source !== "string")
+            continue;
+        const prefix = ["study:", "lab:"].find((candidate) => source.startsWith(candidate));
+        if (prefix === undefined)
+            continue;
+        const id = source.slice(prefix.length).trim();
+        if (id !== "")
+            return id;
+    }
+    return undefined;
+}

package/dist/run/study-result.d.ts

@@ -0,0 +1,16 @@
+/** The schema of a study's result on every route. */
+export declare const STUDY_RESULT_SCHEMA = "humanish.study-result.v1";
+/** The fields every route's result carries to name its route and its study. */
+export interface StudyResultIdentity<R extends string> {
+    schema: typeof STUDY_RESULT_SCHEMA;
+    route: R;
+    /** The study's `id`. */
+    studyId: string;
+    /**
+     * The study's `id`, the same value as `studyId`.
+     * @deprecated Read `studyId`. The next minor removes it.
+     */
+    labId: string;
+}
+/** The identity fields for a result of route `route` from the study `studyId`. */
+export declare function studyResultIdentity<R extends string>(route: R, studyId: string): StudyResultIdentity<R>;

package/dist/run/study-result.js

@@ -0,0 +1,9 @@
+// The schema every route's result carries when a study runs: preview, computer use, scripted,
+// terminal and shared world. `route` says which, and route-specific fields stay on their route's
+// result type.
+/** The schema of a study's result on every route. */
+export const STUDY_RESULT_SCHEMA = "humanish.study-result.v1";
+/** The identity fields for a result of route `route` from the study `studyId`. */
+export function studyResultIdentity(route, studyId) {
+    return { schema: STUDY_RESULT_SCHEMA, route, studyId, labId: studyId };
+}

package/dist/run/text.d.ts

@@ -1,2 +1,4 @@
 /** Escape a literal string for use inside a RegExp source. */
 export declare function escapeRegExp(value: string): string;
+/** "1 run", "2 runs"; `plural` names the irregular form, as in plural(n, "analysis", "analyses"). */
+export declare function plural(count: number, singular: string, pluralForm?: string): string;

package/dist/run/text.js

@@ -2,3 +2,7 @@
 export function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/** "1 run", "2 runs"; `plural` names the irregular form, as in plural(n, "analysis", "analyses"). */
+export function plural(count, singular, pluralForm = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : pluralForm}`;
+}