humanish 0.107.0 → 0.108.0

package/dist/lab/run-lab-options.js

@@ -3,17 +3,14 @@
 // onEvent turned into the emitter. The package's runLab 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 { 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.
@@ -33,7 +30,7 @@ export function removedOptionRefusal(options) {
     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 +38,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".`,
     };
 }
@@ -110,18 +107,24 @@ export function optionRefusalOutcome(config, route, options, refusal) {
     const actor = config.actors[0]?.type ?? "";
     const dryRun = resolveLabDryRun(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 +135,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 +146,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 +157,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/summary.d.ts

@@ -1,6 +1,6 @@
 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 declare const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
 export interface LabCaps {
     /** Per-participant blast-radius budget. */
     laneUsd?: number;
@@ -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,11 +32,11 @@ 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).
+     * default. A study variable you cannot see is one nobody chose.
      */
     reasoningEffort?: string;
     caps: LabCaps;
@@ -59,7 +60,7 @@ export interface ReadLabSummaryOptions {
     keyDeps?: KeyResolutionDeps;
 }
 /**
- * Describe one lab. Returns null when the manifest cannot be resolved — the caller already knows
+ * 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.
  */
 export declare function readLabSummary(cwd: string, lab: string, options?: ReadLabSummaryOptions): Promise<LabSummary | null>;

package/dist/lab/summary.js

@@ -1,9 +1,9 @@
 import { isLocalBrowserLab } 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 lab 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 lab
+// 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
@@ -19,10 +19,10 @@ 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) {
@@ -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,7 +76,7 @@ function capsOf(config) {
     };
 }
 /**
- * Describe one lab. Returns null when the manifest cannot be resolved — the caller already knows
+ * 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.
  */
 export async function readLabSummary(cwd, lab, options = {}) {
@@ -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 ?? lab),
         ...(typeof config.title === "string" ? { title: config.title } : {}),
         ...(typeof config.description === "string" ? { description: config.description.trim() } : {}),
         ...(subject === undefined ? {} : { subject }),

package/dist/lab/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 {
     /** 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,20 +53,20 @@ 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[]);
     /** Evaluate every still-incomplete task against one observation. Returns newly completed tasks. */
@@ -78,10 +78,10 @@ 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.
  */

package/dist/lab/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 lab 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}`;
 }