humanish 0.107.0 → 0.109.0

package/dist/{lab/run-lab-options.js → study/run-study-options.js}

@@ -1,22 +1,19 @@
-// The typed homes on RunLabOptions. runLab calls normalizeRunLabOptions first: it refuses an option
+// The typed homes on RunStudyOptions. runStudyWith calls normalizeRunStudyOptions first: it refuses an option
 // the route cannot honor and otherwise passes the typed options to the route, with env copied and
-// onEvent turned into the emitter. The package's runLab refuses the removed bags
+// onEvent turned into the emitter. The package's runStudy refuses the removed bags
 // (removedOptionRefusal).
 import path from "node:path";
-import { CUA_ACTOR_LAB_SCHEMA } from "../routes/computer-use/types.js";
-import { SCRIPTED_BROWSER_LAB_SCHEMA } from "../routes/scripted/types.js";
-import { CONCURRENT_SHARED_WORLD_LAB_SCHEMA } from "../routes/shared-world/types.js";
-import { TERMINAL_PRODUCT_LAB_SCHEMA } from "../routes/terminal/types.js";
-import { isLocalBrowserLab } from "../substrates/local/runtime-config.js";
-import { resolveLabDryRun } from "./plan.js";
-import { knownSecretValues, labEventEmitter } from "./run-lab-events.js";
+import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
+import { resolveStudyDryRun } from "./plan.js";
+import { knownSecretValues, studyEventEmitter } from "./run-study-events.js";
 import { rosterOf } from "./parse/actors.js";
+import { studyResultIdentity } from "../run/study-result.js";
 const unsupported = (option, route, reason) => ({
     ok: false,
-    code: "HUMANISH_LAB_OPTION_UNSUPPORTED",
+    code: "HUMANISH_STUDY_OPTION_UNSUPPORTED",
     message: `RunLabOptions.${option} is not supported on the ${route} route: ${reason}`,
 });
-// Fields RunLabOptions no longer has, and where each one's job went.
+// Fields RunStudyOptions no longer has, and where each one's job went.
 const REMOVED_OPTIONS = {
     cuaHooks: "Use scorer, createProvider, inProcess, prepareDesktop, env, onEvent and onStream.",
     scriptedHooks: "Use prepareDesktop and env.",
@@ -24,16 +21,17 @@ const REMOVED_OPTIONS = {
     sharedWorldHooks: "Use scorer, prepareDesktop, env, onEvent and onStream.",
     automaticAnalysis: "Use onEvent (analysis-started, analysis-finished) and analysisSignal.",
     lab: "The humanish CLI sets it.",
+    study: "The humanish CLI sets it.",
     scorerProvenance: "The humanish CLI sets it.",
 };
-/** The refusal for a field a JavaScript caller passed that RunLabOptions no longer has. */
+/** The refusal for a field a JavaScript caller passed that RunStudyOptions no longer has. */
 export function removedOptionRefusal(options) {
     // rerun.laneIds, the older name of rerun.participantIds, would otherwise be ignored, so the rerun
     // would select every failed participant instead of the ones the caller named.
     if (options.rerun !== undefined && Reflect.get(options.rerun, "laneIds") !== undefined)
         return {
             ok: false,
-            code: "HUMANISH_LAB_OPTION_UNSUPPORTED",
+            code: "HUMANISH_STUDY_OPTION_UNSUPPORTED",
             message: 'RunLabOptions.rerun.laneIds was removed. Use rerun.participantIds. See docs/contracts/schemas.md, "Library options".',
         };
     const field = Object.keys(REMOVED_OPTIONS).find((key) => Reflect.get(options, key) !== undefined);
@@ -41,7 +39,7 @@ export function removedOptionRefusal(options) {
         return undefined;
     return {
         ok: false,
-        code: "HUMANISH_LAB_OPTION_UNSUPPORTED",
+        code: "HUMANISH_STUDY_OPTION_UNSUPPORTED",
         message: `RunLabOptions.${field} was removed. ${REMOVED_OPTIONS[field]} See docs/contracts/schemas.md, "Library options".`,
     };
 }
@@ -55,7 +53,7 @@ function unsupportedOption(config, route, options) {
         return unsupported("scorer", route, "only computer use, shared world and terminal score runs.");
     if (createProvider !== undefined && route !== "computer-use")
         return unsupported("createProvider", route, route === "shared-world"
-            ? "shared-world participants run the lab's own brain."
+            ? "shared-world participants run the study's own brain."
             : "only computer use takes a caller brain.");
     if (route === "computer-use") {
         const source = config.subject.source;
@@ -64,7 +62,7 @@ function unsupportedOption(config, route, options) {
                 return unsupported("inProcess", route, "it drives an app-url or local-app subject.");
         }
         if (prepareDesktop !== undefined) {
-            if (isLocalBrowserLab(config))
+            if (isLocalBrowserStudy(config))
                 return unsupported("prepareDesktop", route, "a local VM study has no E2B desktop.");
             // An in-process run has no desktop to prepare.
             if (inProcess !== undefined || source === "local-app")
@@ -86,7 +84,7 @@ function unsupportedOption(config, route, options) {
  * Refuse what the route cannot honor, copy env, and build the emitter onEvent receives through.
  * Nothing here touches the filesystem, so a refusal leaves no run directory, receipt or sandbox.
  */
-export function normalizeRunLabOptions(config, route, options) {
+export function normalizeRunStudyOptions(config, route, options) {
     const refused = unsupportedOption(config, route, options);
     if (refused)
         return refused;
@@ -95,7 +93,7 @@ export function normalizeRunLabOptions(config, route, options) {
     // The route gets this copy, so it is the env a warning is scrubbed against, whatever the caller
     // does to its own object afterwards.
     const forwardedEnv = env === undefined ? undefined : { ...env };
-    const emit = labEventEmitter(onEvent, warnings, () => knownSecretValues(config, options, forwardedEnv));
+    const emit = studyEventEmitter(onEvent, warnings, () => knownSecretValues(config, options, forwardedEnv));
     // Every route reads its typed options directly, and onEvent reaches it as `emit`. unsupportedOption
     // already refused an option no route reads; the preview route reads no env.
     const normalized = { ...forwarded };
@@ -108,20 +106,26 @@ export function optionRefusalOutcome(config, route, options, refusal) {
     const cwd = path.resolve(options.cwd);
     const error = { code: refusal.code, message: refusal.message };
     const actor = config.actors[0]?.type ?? "";
-    const dryRun = resolveLabDryRun(config, options.dryRun, true) ?? true;
+    const dryRun = resolveStudyDryRun(config, options.dryRun, true) ?? true;
     const runId = options.runId ?? "not-created";
-    const common = { ok: false, cwd, labId: config.id, actor, dryRun, runId, warnings: [], error };
+    const common = { ok: false, cwd, actor, dryRun, runId, warnings: [], error };
     switch (route) {
         case "preview":
             return {
                 route: "preview",
-                result: { schema: "humanish.run-result.v1", ok: false, cwd, warnings: [], error },
+                result: {
+                    ...studyResultIdentity("preview", config.id),
+                    ok: false,
+                    cwd,
+                    warnings: [],
+                    error,
+                },
             };
         case "computer-use":
             return {
                 route: "computer-use",
                 result: {
-                    schema: CUA_ACTOR_LAB_SCHEMA,
+                    ...studyResultIdentity("computer-use", config.id),
                     ...common,
                     ok: false,
                     appUrl: config.subject.appUrl ?? config.subject.serve?.url ?? "",
@@ -132,7 +136,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
             return {
                 route: "scripted",
                 result: {
-                    schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+                    ...studyResultIdentity("scripted", config.id),
                     ...common,
                     ok: false,
                     appUrl: config.subject.appUrl ?? "",
@@ -143,7 +147,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
             return {
                 route: "terminal",
                 result: {
-                    schema: TERMINAL_PRODUCT_LAB_SCHEMA,
+                    ...studyResultIdentity("terminal", config.id),
                     ...common,
                     ok: false,
                     product: config.subject.product?.name ?? "",
@@ -154,7 +158,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
             return {
                 route: "shared-world",
                 result: {
-                    schema: CONCURRENT_SHARED_WORLD_LAB_SCHEMA,
+                    ...studyResultIdentity("shared-world", config.id),
                     ...common,
                     ok: false,
                     topology: "shared-world",

package/dist/{lab/lab-deps.d.ts → study/study-deps.d.ts}

@@ -9,13 +9,8 @@ import type { DetachedTimers } from "../substrates/detached.js";
 import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
 import type { LocalTreeArchive } from "../subject/local-tree-archive.js";
 import type { SubjectPhaseEvent } from "../subject/steps.js";
-/** The participant a computer-use subject phase belongs to, with the route's field names. */
-export interface PhaseParticipant {
-    readonly laneId: string;
-    readonly laneIndex: number;
-    readonly laneCount: number;
-}
-export interface LabDeps {
+import type { ParticipantRef } from "./run-study-events.js";
+export interface StudyDeps {
     /** Loads the E2B SDK. Defaults to loadE2BDesktopModule. */
     readonly desktopModule?: () => Promise<E2BDesktopModule>;
     /** Renders the Observer. Defaults to renderObserver. */
@@ -29,10 +24,10 @@ export interface LabDeps {
      * computer-use phase names its participant; a shared-world plane's names none. onEvent still
      * receives every phase.
      */
-    readonly subjectPhaseSink?: (event: SubjectPhaseEvent, participant?: PhaseParticipant) => void;
+    readonly subjectPhaseSink?: (event: SubjectPhaseEvent, participant?: ParticipantRef) => void;
     /**
-     * Shared world: runs each seat's computer-use session in place of the actor's own. The planner
-     * reads whether it is set: a custom runner cannot enforce actors[0].maxOutputTokens.
+     * Shared world: runs each participant's computer-use session in place of the actor's own. The
+     * planner reads whether it is set: a custom runner cannot enforce actors[0].maxOutputTokens.
      */
     readonly runSession?: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
     /**
@@ -50,13 +45,13 @@ export interface LabDeps {
     /** Shared world: the background stateSeries prober's cadence in milliseconds. Defaults to 1000. */
     readonly proberCadenceMs?: number;
     /**
-     * Shared world, external-public plane: how long the host seat has to surface a /lobby/CODE URL
+     * Shared world, external-public plane: how long the host has to surface a /lobby/CODE URL
      * before the run fails closed. Defaults to 120000, capped by execution.timeoutMs.
      */
     readonly handoffDeadlineMs?: number;
     /**
-     * Shared world, external-public plane: reads a /lobby/CODE off a seat's screenshot. Defaults to
-     * the single-frame OpenAI read.
+     * Shared world, external-public plane: reads a /lobby/CODE off a participant's screenshot.
+     * Defaults to the single-frame OpenAI read.
      */
     readonly readLobbyCodeFromFrame?: (frame: Buffer, apiKey: string) => Promise<string | undefined>;
     /**

package/dist/{lab/lab-deps.js → study/study-deps.js}

@@ -1,4 +1,4 @@
-// Test seams: the implementations a test puts in place of the real ones. The internal runLab takes
-// them as its third argument and each route runner as `deps`; the package's runLab takes none.
+// Test seams: the implementations a test puts in place of the real ones. The internal runStudyWith takes
+// them as its third argument and each route runner as `deps`; the package's runStudy takes none.
 // Each field defaults to the real implementation.
 export {};

package/dist/{lab → study}/summary.d.ts

@@ -1,13 +1,13 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
 import { type KeyResolutionDeps } from "../keys/key-resolution.js";
-export declare const LAB_SUMMARY_SCHEMA = "humanish.lab-summary.v1";
-export interface LabCaps {
+export declare const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
+export interface StudyCaps {
     /** Per-participant blast-radius budget. */
     laneUsd?: number;
     /** Shared study budget across every participant. */
     studyUsd?: number;
 }
-export interface LabSummary {
+export interface StudySummary {
     runtime?: Pick<LocalRuntimeStatus, "ok" | "installed" | "message">;
     participantReadiness?: {
         ok: boolean;
@@ -20,8 +20,9 @@ export interface LabSummary {
         model: string;
         maxCostUsd: number | null;
     };
-    schema: typeof LAB_SUMMARY_SCHEMA;
-    labId: string;
+    schema: typeof STUDY_SUMMARY_SCHEMA;
+    /** The study's `id`. */
+    studyId: string;
     title?: string;
     description?: string;
     /** "clone drawdb-io/drawdb", "app-url http://127.0.0.1:3000/", "this-repo". */
@@ -31,14 +32,14 @@ export interface LabSummary {
     /** The model that will actually run, override or default. */
     model?: string;
     /**
-     * The reasoning effort that will actually run, override or default — and `"per-lane"` when the
+     * The reasoning effort that will actually run, override or default, and `"per-lane"` when the
      * roster declares more than one, because a single value would be a lie about half the participants.
      *
-     * Shown because it was a silent constant: unreachable from a lab, so every run took the provider
-     * default. A study variable you cannot see is one nobody chose (#497).
+     * Shown because it was a silent constant: unreachable from a study, so every run took the provider
+     * default. A study variable you cannot see is one nobody chose.
      */
     reasoningEffort?: string;
-    caps: LabCaps;
+    caps: StudyCaps;
     /**
      * Whether the configured route's required keys resolve. Dry runs require none. This checks key
      * presence, not local CLI authentication or provider validity. Undefined when not checked.
@@ -46,12 +47,12 @@ export interface LabSummary {
     keysReady?: boolean;
     missingKeys?: string[];
     /**
-     * The planner's refusal message when a live key check finds the lab will not plan, as
-     * `humanish lab run` would report it. `keysReady` is then unset: a refused plan lists no keys.
+     * The planner's refusal message when a live key check finds the study will not plan, as
+     * `humanish run` would report it. `keysReady` is then unset: a refused plan lists no keys.
      */
     planRefusal?: string;
 }
-export interface ReadLabSummaryOptions {
+export interface ReadStudySummaryOptions {
     /** Skip the key probe (it touches vendor stores); the screen then shows no keys line. */
     checkKeys?: boolean;
     env?: NodeJS.ProcessEnv;
@@ -59,7 +60,7 @@ export interface ReadLabSummaryOptions {
     keyDeps?: KeyResolutionDeps;
 }
 /**
- * Describe one lab. Returns null when the manifest cannot be resolved — the caller already knows
- * the lab exists from the listing, so this failing means the file changed underneath them.
+ * Describe one study. Returns null when the manifest cannot be resolved: the caller already knows
+ * the study exists from the listing, so this failing means the file changed underneath them.
  */
-export declare function readLabSummary(cwd: string, lab: string, options?: ReadLabSummaryOptions): Promise<LabSummary | null>;
+export declare function readStudySummary(cwd: string, study: string, options?: ReadStudySummaryOptions): Promise<StudySummary | null>;

package/dist/{lab → study}/summary.js

@@ -1,28 +1,28 @@
-import { isLocalBrowserLab } from "../substrates/local/runtime-config.js";
+import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
-// What a lab IS, for the surface that has to describe it before you spend money (#455).
+// What a study is, for the surface that has to describe it before you spend money.
 //
-// The run index and run detail answer questions about runs. This answers a question about the LAB
-// itself — what it drives, who is in it, which model, and what it is allowed to spend — which is
+// The run index and run detail answer questions about runs. This answers a question about the study
+// itself (what it drives, who is in it, which model, and what it is allowed to spend), which is
 // what a stakeholder reads on the screen where they decide whether to press Start.
 //
 // Resolved analysis defaults are shown independently of declared participant caps. A cap that is not
 // declared is not "unlimited" and not "$0"; it is a line the screen does not draw.
-import { resolveLabDryRun } from "./plan.js";
+import { resolveStudyDryRun } from "./plan.js";
 import { routeOf } from "./plan.js";
 import { localCodexParticipantCheck, planCliRun } from "./doctor.js";
 import { requiredKeys, requiredSubjectEnv } from "./requirements.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { DEFAULT_OPENAI_CU_MODEL, DEFAULT_OPENAI_CU_REASONING_EFFORT, } from "../actors/computer-use/openai-provider.js";
-import { inspectLabManifest } from "./discover.js";
+import { inspectStudyManifest } from "./discover.js";
 import { isComputerUseComposition } from "./routing.js";
 import { probeKeySources } from "../keys/key-resolution.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { rosterOf } from "./parse/actors.js";
-export const LAB_SUMMARY_SCHEMA = "humanish.lab-summary.v1";
+export const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
 /**
  * The effort every participant will run at, or `"per-lane"` when they differ. A participant that declares nothing
- * inherits the actor's, and an actor that declares nothing gets the provider default — which is
+ * inherits the actor's, and an actor that declares nothing gets the provider default, which is
  * reported as the resolved value, exactly as `model` reports its default rather than hiding it.
  */
 function reasoningEffortOf(config) {
@@ -35,7 +35,7 @@ function reasoningEffortOf(config) {
         return "per-lane";
     return resolved.size === 1 ? [...resolved][0] : fallback;
 }
-/** One short phrase for what the lab drives. */
+/** One short phrase for what the study drives. */
 function subjectOf(config) {
     const subject = config.subject;
     if (subject?.source === undefined)
@@ -47,7 +47,7 @@ function subjectOf(config) {
         return `${subject.source} ${subject.appUrl}`;
     return subject.source;
 }
-/** How many participants, and who — collapsed when they are all the same persona. */
+/** How many participants, and who; collapsed when they are all the same persona. */
 function participantsOf(config) {
     const actors = config.actors;
     const actor = actors?.[0];
@@ -61,7 +61,7 @@ function participantsOf(config) {
     const unique = [...new Set(personas)];
     if (unique.length === 0)
         return `${count} participant${count === 1 ? "" : "s"}`;
-    // Several participants of ONE persona reads as "3 × skeptical-power-user"; genuinely different people
+    // Several participants of one persona reads as "3 × skeptical-power-user"; genuinely different people
     // are named, because which personas are in a study is the study's design.
     return unique.length === 1 ? `${count} × ${unique[0]}` : unique.join(" · ");
 }
@@ -76,11 +76,11 @@ function capsOf(config) {
     };
 }
 /**
- * Describe one lab. Returns null when the manifest cannot be resolved — the caller already knows
- * the lab exists from the listing, so this failing means the file changed underneath them.
+ * Describe one study. Returns null when the manifest cannot be resolved: the caller already knows
+ * the study exists from the listing, so this failing means the file changed underneath them.
  */
-export async function readLabSummary(cwd, lab, options = {}) {
-    const inspected = await inspectLabManifest(cwd, lab).catch(() => null);
+export async function readStudySummary(cwd, study, options = {}) {
+    const inspected = await inspectStudyManifest(cwd, study).catch(() => null);
     if (inspected === null || !inspected.ok || inspected.config === undefined)
         return null;
     const config = inspected.config;
@@ -88,8 +88,8 @@ export async function readLabSummary(cwd, lab, options = {}) {
     const route = routeOf(inspected.config);
     let keysReady;
     let missingKeys;
-    const dryRun = resolveLabDryRun(inspected.config, undefined, true) === true;
-    // A live key check reads the plan's requirements. A lab the planner refuses has none to check,
+    const dryRun = resolveStudyDryRun(inspected.config, undefined, true) === true;
+    // A live key check reads the plan's requirements. A study the planner refuses has none to check,
     // so the summary reports the refusal in place of its keys.
     const planned = options.checkKeys === true && !dryRun ? await planCliRun(inspected.config, cwd) : undefined;
     const planRefusal = planned?.ok === false ? planned.refusal.message : undefined;
@@ -129,7 +129,7 @@ export async function readLabSummary(cwd, lab, options = {}) {
     const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route);
     const subject = subjectOf(config);
     const participants = participantsOf(config);
-    const runtime = options.checkKeys === true && isLocalBrowserLab(inspected.config)
+    const runtime = options.checkKeys === true && isLocalBrowserStudy(inspected.config)
         ? await localRuntimeStatus({
             ...(options.env ? { env: options.env } : {}),
             media: inspected.config.execution?.desktop?.media !== undefined ||
@@ -137,7 +137,7 @@ export async function readLabSummary(cwd, lab, options = {}) {
         })
         : undefined;
     const participantReadiness = options.checkKeys === true &&
-        isLocalBrowserLab(inspected.config) &&
+        isLocalBrowserStudy(inspected.config) &&
         inspected.config.actors[0]?.type === "local-agent"
         ? await localCodexParticipantCheck({ env: options.env ?? process.env })
         : undefined;
@@ -154,13 +154,13 @@ export async function readLabSummary(cwd, lab, options = {}) {
                 },
             }
             : {}),
-        schema: LAB_SUMMARY_SCHEMA,
+        schema: STUDY_SUMMARY_SCHEMA,
         ...(inspected.config.comms?.email?.kind === "real"
             ? {
                 communications: `Real email · ${inspected.config.comms.email.connection} · fresh inbox per participant · hosted processing · local review only`,
             }
             : {}),
-        labId: String(config.id ?? lab),
+        studyId: String(config.id ?? study),
         ...(typeof config.title === "string" ? { title: config.title } : {}),
         ...(typeof config.description === "string" ? { description: config.description.trim() } : {}),
         ...(subject === undefined ? {} : { subject }),

package/dist/{lab → study}/tasks.d.ts

@@ -4,20 +4,20 @@ declare const TASK_FUNNEL_SCHEMA: "humanish.task-funnel.v1";
  * One task in a protocol. It has two halves that belong to two different people, and keeping them
  * apart is the point of the type.
  *
- * `goal` belongs to the PARTICIPANT. It is what they are asked to do, in their language, and it is
+ * `goal` belongs to the participant. It is what they are asked to do, in their language, and it is
  * the only half that reaches the prompt.
  *
- * `success` belongs to the RESEARCHER. It is how the task will be measured, and the participant
- * never sees it — a moderator does not read the success criterion aloud, because telling someone
+ * `success` belongs to the researcher. It is how the task will be measured, and the participant
+ * never sees it. A moderator does not read the success criterion aloud, because telling someone
  * how they will be judged changes what they do. A persona told "you succeed when the URL contains
  * /dashboard" will go find that URL, which measures the instruction rather than the product.
  */
-export interface LabTask {
+export interface StudyTask {
     /** Stable id, used in evidence and in the funnel. Researcher-facing. */
     id: string;
-    /** PARTICIPANT-FACING. What they are asked to do. The only half that reaches the prompt. */
+    /** Participant-facing. What they are asked to do. The only half that reaches the prompt. */
     goal: string;
-    /** RESEARCHER-FACING. Observation-shaped proof the task happened. Never rendered to the
+    /** Researcher-facing. Observation-shaped proof the task happened. Never rendered to the
      *  participant. Absent means the task is narrative-only: it is asked for but cannot be measured,
      *  and the funnel says so rather than quietly counting it as failed. */
     success?: StopWhen;
@@ -38,12 +38,12 @@ export interface TaskFunnel {
     total: number;
     /** Tasks observed complete. */
     completed: number;
-    /** Declared tasks with no `done` criterion — shown to the participant, never observable. */
+    /** Declared tasks with no `done` criterion: shown to the participant, never observable. */
     unobservable: number;
-    /** The first task that was NOT observed complete: where this participant stopped. */
+    /** The first task that was not observed complete: where this participant stopped. */
     stoppedAt?: string;
     /** Per-task, in declaration order. `inputsObserved` is false when the task declares criteria
-     *  whose inputs (url, text, appState) NEVER arrived in any observation this session, so the
+     *  whose inputs (url, text, appState) never arrived in any observation this session, so the
      *  task was never actually measured. Absent when the task completed or is unobservable. */
     tasks: Array<{
         id: string;
@@ -53,22 +53,22 @@ export interface TaskFunnel {
         inputsObserved?: boolean;
     }>;
     /** Observable tasks that were never measured, because the inputs their criteria need never
-     *  arrived. Reported SEPARATELY from failures: a task nobody could observe is a gap in our
-     *  instrument, and reporting it as 0-completed blames the participant for it (#514). */
+     *  arrived. Reported separately from failures: a task nobody could observe is a gap in our
+     *  instrument, and reporting it as 0-completed blames the participant for it. */
     unmeasured: number;
 }
 /**
- * Tracks task completion across a session. Stateful on purpose: a task completes ONCE, on the first
- * observation that satisfies it, and stays complete even if the participant navigates away — you do
+ * Tracks task completion across a session. Stateful on purpose: a task completes once, on the first
+ * observation that satisfies it, and stays complete even if the participant navigates away; you do
  * not un-sign-up by going back to the home page.
  */
 export declare class TaskTracker {
     private readonly tasks;
     private readonly completions;
     /** Which observation fields were ever populated this session. A criterion whose field never
-     *  arrived was never evaluated against anything, however many turns ran (#514). */
+     *  arrived was never evaluated against anything, however many turns ran. */
     private readonly fieldsSeen;
-    constructor(tasks: readonly LabTask[]);
+    constructor(tasks: readonly StudyTask[]);
     /** Evaluate every still-incomplete task against one observation. Returns newly completed tasks. */
     observe(observation: StopConditionObservation, turn: number): TaskCompletion[];
     /** Which observation fields a task's criteria actually read. A task whose rules need `url` was
@@ -78,14 +78,14 @@ export declare class TaskTracker {
     funnel(): TaskFunnel;
 }
 /**
- * The task list as the PARTICIPANT reads it: numbered, in order, in their own language.
+ * The task list as the participant reads it: numbered, in order, in their own language.
  *
  * Reads `goal` and nothing else. The success criteria are the researcher's instrument and never
- * appear here — a participant who is told how they will be measured optimizes for the measurement,
+ * appear here: a participant who is told how they will be measured optimizes for the measurement,
  * and the study stops being about the product. A test pins this, because it is the kind of leak a
  * later convenience change makes without noticing.
  */
-export declare function renderTaskPrompt(tasks: readonly LabTask[]): string | undefined;
+export declare function renderTaskPrompt(tasks: readonly StudyTask[]): string | undefined;
 /** One line a stakeholder can read, with the denominator attached. */
 export declare function formatTaskFunnel(funnel: TaskFunnel): string;
 export {};

package/dist/{lab → study}/tasks.js

@@ -1,32 +1,32 @@
 // Tasks: the researcher's protocol, expressed as config (docs/principles/three-roles.md).
 //
-// A lab could declare a prose `mission` and nothing else. That is a brief, not a protocol — and it
+// A study could declare a prose `mission` and nothing else. That is a brief, not a protocol, and it
 // left "where did people get stuck" answerable only from an actor's own narration, which is the one
 // source a study should not have to take on faith.
 //
-// Real usability studies are built from discrete TASKS, each with a written success criterion, and
+// Real usability studies are built from discrete tasks, each with a written success criterion, and
 // the result is a funnel: how far each participant got before they stopped. That funnel is the
 // finding. A single pass/fail per participant throws it away.
 //
-// The criterion language is `stopWhen`, unchanged and already load-bearing elsewhere: a task is
+// The criterion language is `stopWhen`, unchanged and already used by stop conditions: a task is
 // done when an observation satisfies it. Reusing it means a task criterion is exactly as expressive
 // as a stop condition, and an author who knows one knows the other.
 //
-// A task's completion is CORROBORATED, not self-reported. The actor saying "I signed up" does not
+// A task's completion is corroborated, not self-reported. The actor saying "I signed up" does not
 // complete a task; the observed URL, page text, or app state does. That distinction is the whole
 // reason to declare tasks at all.
 import { evaluateStopWhen, } from "../actors/stop-conditions.js";
 const TASK_FUNNEL_SCHEMA = "humanish.task-funnel.v1";
 /**
- * Tracks task completion across a session. Stateful on purpose: a task completes ONCE, on the first
- * observation that satisfies it, and stays complete even if the participant navigates away — you do
+ * Tracks task completion across a session. Stateful on purpose: a task completes once, on the first
+ * observation that satisfies it, and stays complete even if the participant navigates away; you do
  * not un-sign-up by going back to the home page.
  */
 export class TaskTracker {
     tasks;
     completions = new Map();
     /** Which observation fields were ever populated this session. A criterion whose field never
-     *  arrived was never evaluated against anything, however many turns ran (#514). */
+     *  arrived was never evaluated against anything, however many turns ran. */
     fieldsSeen = new Set();
     constructor(tasks) {
         this.tasks = tasks;
@@ -77,7 +77,7 @@ export class TaskTracker {
         const tasks = this.tasks.map((task) => {
             const completion = this.completions.get(task.id);
             const observable = task.success !== undefined;
-            // A task counts as measured when at least ONE field its criteria read was populated by some
+            // A task counts as measured when at least one field its criteria read was populated by some
             // observation. `any` semantics: any satisfiable rule needed a field we actually saw.
             const required = observable ? this.fieldsRequiredBy(task) : [];
             const inputsObserved = required.length === 0 ? true : required.some((field) => this.fieldsSeen.has(field));
@@ -91,12 +91,12 @@ export class TaskTracker {
                 ...(observable && completion === undefined ? { inputsObserved } : {}),
             };
         });
-        // Where they stopped is the first task not observed complete — the thing a researcher reads
+        // Where they stopped is the first task not observed complete, the thing a researcher reads
         // first. An unobservable task cannot be "where they stopped", because nothing could have
         // proven otherwise; skipping it avoids blaming a participant for a gap in the protocol.
         // A task we never measured cannot be "where they stopped" either, for the same reason an
         // unobservable one cannot: nothing could have proven otherwise, so naming it blames the
-        // participant for our gap (#514).
+        // participant for our gap.
         const stoppedAt = tasks.find((task) => task.observable && !task.completed && task.inputsObserved !== false)?.id;
         return {
             schema: TASK_FUNNEL_SCHEMA,
@@ -110,10 +110,10 @@ export class TaskTracker {
     }
 }
 /**
- * The task list as the PARTICIPANT reads it: numbered, in order, in their own language.
+ * The task list as the participant reads it: numbered, in order, in their own language.
  *
  * Reads `goal` and nothing else. The success criteria are the researcher's instrument and never
- * appear here — a participant who is told how they will be measured optimizes for the measurement,
+ * appear here: a participant who is told how they will be measured optimizes for the measurement,
  * and the study stops being about the product. A test pins this, because it is the kind of leak a
  * later convenience change makes without noticing.
  */
@@ -131,9 +131,9 @@ export function formatTaskFunnel(funnel) {
     const stopped = funnel.stoppedAt === undefined ? "" : `, stopped at "${funnel.stoppedAt}"`;
     const unobservable = funnel.unobservable === 0 ? "" : `, ${funnel.unobservable} with no completion criterion`;
     // Named separately from failures. "0/3 completed" alone reads as "no participant managed it",
-    // which is the wrong story when the criterion was never evaluated against anything (#514).
+    // which is the wrong story when the criterion was never evaluated against anything.
     const unmeasured = funnel.unmeasured === 0
         ? ""
-        : `, ${funnel.unmeasured} NEVER MEASURED (the observations their criteria read never arrived)`;
+        : `, ${funnel.unmeasured} never measured (the observations their criteria read never arrived)`;
     return `${base}${stopped}${unobservable}${unmeasured}`;
 }