humanish 0.107.0 → 0.109.0

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

@@ -1,31 +1,33 @@
-import { type LabAnalysis } from "../analysis/automatic-config.js";
-import type { LabTask } from "./tasks.js";
+import { type StudyAnalysis } from "../analysis/automatic-config.js";
+import type { StudyTask } from "./tasks.js";
 import type { DwellWindow, StopWhen } from "../actors/stop-conditions.js";
 import { type ReasoningEffort } from "../actors/reasoning-effort.js";
-export declare const LAB_CONFIG_SCHEMA = "humanish.lab.v2";
+export declare const V2_SCHEMA = "humanish.lab.v2";
+/** The study format: it declares its route, one actor, its participants and one caps block. */
+export declare const STUDY_SCHEMA = "humanish.study.v3";
 export declare const ID_PATTERN: RegExp;
 /**
  * Where the run acts: the host repo, a fresh clone, a running app a browser actor drives
  * (`app-url`), an already-running local dev server driven in-process via a custom
  * CuaExecutor with no clone and no E2B desktop (`local-app`), or the operator's own local
  * working tree packed and provisioned in-sandbox in place of a clone (`local-tree`).
- * `local-app` routes to the cua backend and is library-assisted: a caller supplies
- * `RunLabOptions.inProcess` + `createProvider` (no built-in driver exists yet), and the engine
- * fails closed (HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR) when run without them: a structured
+ * `local-app` routes to the computer-use route and is library-assisted: a caller supplies
+ * `RunStudyOptions.inProcess` + `createProvider` (no built-in driver exists yet), and the engine
+ * fails closed (HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR) when run without them: a structured
  * error, never a desktop attempt. See docs/architecture/state-driven-executor.md.
  */
-type LabSubjectSource = "this-repo" | "clone" | "app-url" | "local-app" | "terminal-product" | "desktop-cli" | "local-tree";
+type StudySubjectSource = "this-repo" | "clone" | "app-url" | "local-app" | "terminal-product" | "desktop-cli" | "local-tree";
 /**
  * How a subject's world relates across participants. `per-lane-worlds` (the default; absent ==
- * this) is the only fan-out topology the computer-use route ships — N participants, N independent
- * worlds, isolation + per-participant attribution. `shared-world` (#164) is the declared override: one
+ * this) is the only fan-out topology the computer-use route ships: N participants, N independent
+ * worlds, isolation + per-participant attribution. `shared-world` is the declared override: one
  * mutable service plane that N participants use at the same time, so their actions interact through
  * shared state. Consumed only on the shared-world routes (a provisioned clone plane, or an
  * external-public app-url plane) with a computer-use actor; inert/warned everywhere else
- * (invariant 6).
+ * (claims match mechanism).
  */
-type LabSubjectTopology = "per-lane-worlds" | "shared-world";
-export interface LabSubjectClone {
+type StudySubjectTopology = "per-lane-worlds" | "shared-world";
+export interface StudySubjectClone {
     /** git clone depth; 1 (shallow) by default. Consumed on the computer-use clone route. */
     depth?: number;
     /** how many participants to fan out, each with its own clone (one sandbox/desktop each). */
@@ -35,9 +37,9 @@ export interface LabSubjectClone {
 }
 /**
  * `local-tree`: how the operator's own working tree is packed and provisioned in-sandbox in
- * place of a clone. Internal shape (not re-exported from src/index.ts, same as LabSubjectClone).
+ * place of a clone. Internal shape (not re-exported from src/index.ts, same as StudySubjectClone).
  */
-export interface LabSubjectLocalTree {
+export interface StudySubjectLocalTree {
     /** extra archive excludes (path prefixes/basenames) added on top of the always-on denylist. */
     exclude?: string[];
     /** keep the disposable sandbox on failure for debugging (mirrors subject.clone.keep). */
@@ -46,16 +48,16 @@ export interface LabSubjectLocalTree {
     maxArchiveBytes?: number;
 }
 /** How a cloned subject is installed/built/started inside the sandbox (computer-use route). */
-export interface LabSubjectServe {
+export interface StudySubjectServe {
     /** Optional bounded install step (e.g. "pnpm install --frozen-lockfile"). */
     install?: string;
     /** Optional bounded build step. */
     build?: string;
-    /** Required long-lived start command — launched detached; the sandbox lifecycle owns it. */
+    /** Required long-lived start command, launched detached; the sandbox lifecycle owns it. */
     start: string;
-    /** Loopback entry URL: the readiness-probe target and the URL the actor drives. The lab
+    /** Loopback entry URL: the readiness-probe target and the URL the actor drives. humanish
      *  serves the clone inside the sandbox, so this is always loopback (not subject to
-     *  allowPublicTargets — that governs app-url subjects, i.e. external deployments). */
+     *  allowPublicTargets, which governs app-url subjects, i.e. external deployments). */
     url: string;
     /** Budget for the served app to answer the readiness probe. Default 180000. */
     readyTimeoutMs?: number;
@@ -65,47 +67,47 @@ export interface LabSubjectServe {
     buildTimeoutMs?: number;
 }
 /** When a state step runs, relative to the serve sequence (clone subjects, computer-use route). */
-export type LabStateStepWhen = "before-build" | "before-start" | "after-ready";
-interface LabSubjectStateStep {
+export type StudyStateStepWhen = "before-build" | "before-start" | "after-ready";
+interface StudySubjectStateStep {
     /**
      * [a-z0-9-] step label (must start alphanumeric), <=40 chars, unique across steps; becomes
-     * the detached-step name `subject-state-<name>` (interpolates into in-sandbox file paths —
-     * the shape is load-bearing, validated at parse and re-enforced in the engine).
+     * the detached-step name `subject-state-<name>` (interpolates into in-sandbox file paths, so
+     * the shape is validated at parse and re-enforced in the engine).
      */
     name: string;
     /**
-     * Author-trusted shell command (same trust class as serve.install/build/start — the
+     * Author-trusted shell command (same trust class as serve.install/build/start: the
      * "serve commands are author-trusted" corollary). Runs detached in the subject directory
      * with an atomic status file, kill-on-timeout, and a capped log tail. Persisted in
      * evidence as a sha256-16 digest only, never as text.
      */
     command: string;
     /**
-     * Phase: before-build (after install — for builds that read the DB, e.g. SSG),
-     * before-start (after build, before the server launches — migrations, SQL/file fixtures,
-     * an in-sandbox `service postgresql start`), after-ready (after the readiness probe —
+     * Phase: before-build (after install, for builds that read the DB, e.g. SSG),
+     * before-start (after build, before the server launches: migrations, SQL/file fixtures,
+     * an in-sandbox `service postgresql start`), after-ready (after the readiness probe:
      * fixtures loaded through the running app's API). Default: before-start.
      */
-    when?: LabStateStepWhen;
+    when?: StudyStateStepWhen;
     /** Wall-clock budget per step. Default 300000. */
     timeoutMs?: number;
 }
 /**
  * A shared-world state checkpoint: an author-trusted, read-only, aggregate/digest probe command
  * (counts, max-timestamps, hashes) run at baseline and after each role's turn. Reuses the
- * seed-step validation shape (name [a-z0-9-] ≤40, unique; command required). Persisted DIGEST-ONLY
- * (only sha256-16(scrub+redact(stdout)) ever lands — never the raw value), same lockdown as the
- * seed surface. Consumed only on the shared-world route (#164); inert/warned elsewhere.
+ * seed-step validation shape (name [a-z0-9-] ≤40, unique; command required). Persisted digest-only
+ * (only sha256-16(scrub+redact(stdout)) ever lands, never the raw value), same lockdown as the
+ * seed surface. Consumed only on the shared-world route; inert/warned elsewhere.
  */
-export interface LabSubjectStateCheckpoint {
+export interface StudySubjectStateCheckpoint {
     /**
      * [a-z0-9-] probe label (must start alphanumeric), <=40 chars, unique across checkpoints;
-     * names the detached step (`checkpoint-<snapshot>-<name>`) — load-bearing shape, validated at
+     * names the detached step (`checkpoint-<snapshot>-<name>`), a shape validated at
      * parse and re-enforced in the engine.
      */
     name: string;
     /**
-     * Author-trusted READ-ONLY shell command (same trust class as serve/seed — the "serve commands
+     * Author-trusted read-only shell command (same trust class as serve/seed: the "serve commands
      * are author-trusted" corollary). Its stdout is scrubbed + pattern-redacted, then digested
      * (sha256-16); the raw value never persists.
      */
@@ -118,30 +120,30 @@ export interface LabSubjectStateCheckpoint {
     redact?: string[];
 }
 /** The subject's state story (clone subjects): seeded in-sandbox, or declared external. */
-export interface LabSubjectState {
+export interface StudySubjectState {
     /** Ordered seed/migration/fixture steps. Order within a phase is declaration order. */
-    seed?: LabSubjectStateStep[];
+    seed?: StudySubjectStateStep[];
     /**
-     * Env var names whose values point at state the lab does not control (e.g. a shared dev
+     * Env var names whose values point at state the study does not control (e.g. a shared dev
      * DB). Must be a subset of subject.env (so the declaration is mechanically backed by a
      * provisioned name, not a vibe). Flips state provenance to "unpinned".
      */
     external?: string[];
     /**
-     * Shared-world state checkpoints (#164): read-only digest probes run at baseline + after each
+     * Shared-world state checkpoints: read-only digest probes run at baseline + after each
      * role's turn to produce the harness-clocked interaction timeline. Consumed only on the
-     * shared-world route; inert/warned elsewhere (invariant 6). Shape-validated everywhere.
+     * shared-world route; inert/warned elsewhere. Shape-validated everywhere.
      */
-    checkpoint?: LabSubjectStateCheckpoint[];
+    checkpoint?: StudySubjectStateCheckpoint[];
 }
 /**
  * `terminal-product`: the product-under-study a terminal agent must discover and use from public
  * surfaces only (the terminal-product route's subject). The subject is not provisioned or cloned:
- * the agent drives the declared public surfaces, so provenance is unpinned (invariant 5). The
+ * the agent drives the declared public surfaces, so provenance is declared unpinned. The
  * concrete product name + surfaces are operator data; committed fixtures use a neutral mock name.
  */
-export interface LabSubjectProduct {
-    /** Public-safe product label (shape-validated like a lab id; interpolates into evidence). */
+export interface StudySubjectProduct {
+    /** Public-safe product label (shape-validated like a study id; interpolates into evidence). */
     name: string;
     /**
      * How the product gets onto the machine, run with no keys before the participant starts, in the
@@ -149,9 +151,9 @@ export interface LabSubjectProduct {
      * desktop) and `terminal-product` (an agent in a shell).
      *
      * Absent means the participant installs it themselves from the public surfaces, which is a
-     * different study — one about the install, not about the tool. Present means the study starts
+     * different study, one about the install. Present means the study starts
      * where you want it to start: asking a participant what studies a project contains, in an empty
-     * directory, measures the lab rather than the product.
+     * directory, measures the study rather than the product.
      * Both routes prepare Node/npm when install is absent; product installation remains the
      * participant's task. A missing template runtime must not become a product finding.
      */
@@ -162,7 +164,7 @@ export interface LabSubjectProduct {
      *
      * This exists because the first live study failed on it: the participant was asked what studies
      * the project contained, landed in an empty home directory, correctly reported that there was no
-     * project, and stopped. The finding was about the lab, not the product. A study of a
+     * project, and stopped. The finding was about the study, not the product. A study of a
      * project-scoped tool has to put the participant inside a project, the same way an app study opens
      * the app rather than a blank tab.
      */
@@ -179,23 +181,23 @@ export interface LabSubjectProduct {
      * autonomous agent is about to drive.
      *
      * It exists so a study can test a build that is not published yet. Installing `@latest` measures
-     * the last release, which is exactly the wrong artifact for a pre-release gate — the point is to
+     * the last release, which is exactly the wrong artifact for a pre-release gate. The point is to
      * meet the candidate before anyone else does. Any adopter shipping a CLI wants the same thing.
      */
     upload?: string;
 }
-export interface LabSubject {
-    source: LabSubjectSource;
+export interface StudySubject {
+    source: StudySubjectSource;
     /**
      * World topology across participants. Absent == `per-lane-worlds` (the isolation default; every
-     * existing lab is byte-stable). `shared-world` is the declared override (#164): one mutable
-     * service plane, N role seats at once. Consumed only on the shared-world routes (a provisioned
-     * clone or an external-public app-url plane, a computer-use actor, and a roster of ≥2 participants);
-     * inert/warned elsewhere.
+     * existing study is byte-stable). `shared-world` is the declared override: one mutable service
+     * plane, N participants at once, each in its role. Consumed only on the shared-world routes (a
+     * provisioned clone or an external-public app-url plane, a computer-use actor, and a roster of ≥2
+     * participants); inert/warned elsewhere.
      */
-    topology?: LabSubjectTopology;
+    topology?: StudySubjectTopology;
     /**
-     * Concurrent shared-world route only (#164 phase 2): the author's required attestation that the
+     * Concurrent shared-world route only: the author's required attestation that the
      * subject behind the internet-reachable `getHost` URL is synthetic seeded data. The concurrent
      * route exposes the subject on a tokenless public URL for the run's duration, so real/external
      * data must never sit behind it. This is author-trust + a provenance gate (verify also requires
@@ -204,16 +206,16 @@ export interface LabSubject {
      */
     exposure?: "synthetic";
     /**
-     * External-public shared-world route only (#164 phase 2): the author's required ownership
+     * External-public shared-world route only: the author's required ownership
      * attestation when a real public deployment (`source: app-url` + `topology: shared-world` +
      * `concurrency > 1` + `policies.allowPublicTargets: true`) is used directly as the shared plane.
      * The harness neither provisions nor exposes this target (no getHost, no clone, no seed), so it
      * cannot attest the data is synthetic; instead the operator must attest they own/operate it.
-     * `owner` is a public-safe operator/repo label; `authorized` must be true. This is author-trust —
-     * the harness cannot verify ownership — surfaced honestly in the evidence class. Required on the
+     * `owner` is a public-safe operator/repo label; `authorized` must be true. This is author-trust:
+     * the harness cannot verify ownership, and the evidence class says so. Required on the
      * external-public branch. On a non-`app-url` subject it is rejected (parse error); on any other
-     * `app-url` config that does not route to external-public shared-world it is IGNORED-WITH-A-WARNING
-     * (forwardDeclaredWarnings), never silently consumed — it is meaningless without that plane.
+     * `app-url` config that does not route to external-public shared-world it is ignored with a warning
+     * (forwardDeclaredWarnings), never silently consumed, because it is meaningless without that plane.
      */
     publicTarget?: {
         owner: string;
@@ -221,20 +223,20 @@ export interface LabSubject {
     };
     /** `clone`: one or more owner/repo slugs (public or authorized-private). */
     repos?: string[];
-    clone?: LabSubjectClone;
+    clone?: StudySubjectClone;
     /**
      * `app-url`: a loopback http(s) URL the computer-use actor drives (127.0.0.1/localhost
-     * only — driving arbitrary public sites is not allowed). The URL must be reachable from
+     * only; driving arbitrary public sites is not allowed). The URL must be reachable from
      * inside the desktop sandbox; library callers provision it via the prepareDesktop hook.
-     * For a config-only path use `clone` + `serve` — the lab serves the app itself.
+     * For a config-only path use `clone` + `serve`: humanish serves the app itself.
      *
      * `local-app`: the loopback http(s) URL of an already-running local dev server the caller's
-     * custom CuaExecutor drives in-process (no sandbox, no public-target option — always
+     * custom CuaExecutor drives in-process (no sandbox, no public-target option, always
      * loopback). Passed to `inProcess.executor` so the bridge knows where the app lives.
      */
     appUrl?: string;
     /** `clone` (computer-use route): how the cloned app is served in-sandbox. */
-    serve?: LabSubjectServe;
+    serve?: StudySubjectServe;
     /**
      * Env var names the subject app needs, provisioned into the sandbox from the caller's
      * environment (--env-file). Names are recorded in evidence; values never are. Consumed
@@ -242,10 +244,10 @@ export interface LabSubject {
      */
     env?: string[];
     /**
-     * Literal, non-secret env values committed alongside the lab: the configuration every real app
+     * Literal, non-secret env values committed alongside the study: the configuration every real app
      * needs before it will boot: a public base URL, a transport selector, a feature flag. None of that
      * is secret, and routing it through `subject.env` would force an adopter to carry a private env
-     * file just to reproduce a public study, which is the opposite of a reproducible lab.
+     * file just to reproduce a public study, which is the opposite of a reproducible study.
      *
      * These values are recorded in evidence, because they are part of how the subject was configured,
      * so a value that looks like a secret or a local path is refused at parse rather than committed to
@@ -253,27 +255,27 @@ export interface LabSubject {
      */
     envValues?: Record<string, string>;
     /**
-     * `clone` (computer-use route): the subject's state story — seed/migration/fixture steps
+     * `clone` (computer-use route): the subject's state story, as seed/migration/fixture steps
      * executed in-sandbox around the serve sequence, and/or declared external state. Recorded
-     * in the run bundle as structured provenance (invariant 5): seeded with command digests,
+     * in the run bundle as structured provenance: seeded with command digests,
      * unpinned for external state, declared-not-run for dry-run/failed provisioning.
      */
-    state?: LabSubjectState;
+    state?: StudySubjectState;
     /**
      * `terminal-product` (terminal route): the product the terminal agent discovers + uses from
      * public surfaces only. Consumed on the terminal route; rejected on every other source.
      */
-    product?: LabSubjectProduct;
+    product?: StudySubjectProduct;
     /**
-     * `local-tree` (computer-use route): local-tree packs the lab resolution cwd (the project
+     * `local-tree` (computer-use route): local-tree packs the study's working directory (the project
      * directory humanish runs from) instead of cloning a repo. `exclude` adds extra archive excludes
      * on top of the always-on denylist; `keep` preserves the sandbox on failure for debugging;
      * `maxArchiveBytes` caps the upload. Consumed on the local-tree route; rejected on every other
      * source.
      */
-    localTree?: LabSubjectLocalTree;
+    localTree?: StudySubjectLocalTree;
 }
-export interface LabParticipantFocus {
+export interface StudyParticipantFocus {
     id?: string;
     label?: string;
     /** Per-participant steer appended to the actor's mission. Consumed on the app-url route. */
@@ -286,8 +288,8 @@ export interface LabParticipantFocus {
  * defaults to `lane-01`..`lane-NN` and must be a public-safe token (it names per-participant evidence
  * paths). Consumed only on the computer-use E2B route (inert/warned elsewhere).
  */
-export interface LabParticipantEntry {
-    /** Public-safe participant id (interpolates into its evidence paths). Default lane-NN. */
+export interface StudyParticipantEntry {
+    /** Public-safe participant id (interpolates into its evidence paths). Default `lane-NN`. */
     id?: string;
     /**
      * App-defined actor type label for grouping simulated users ("operator", "viewer",
@@ -310,7 +312,7 @@ export interface LabParticipantEntry {
      * observation matches any declared rule; actor-level stopWhen is used as the default.
      */
     stopWhen?: StopWhen;
-    /** A declared observation window for this participant (#510); actor-level dwell is the default. */
+    /** A declared observation window for this participant; actor-level dwell is the default. */
     dwell?: DwellWindow;
     /**
      * How hard the model is asked to think for this participant; actor-level reasoningEffort is the default.
@@ -327,17 +329,17 @@ export interface LabParticipantEntry {
      */
     target?: string;
     /**
-     * Shared-world only (#164): this participant's loopback entry route, resolved against
+     * Shared-world only: this participant's loopback entry route, resolved against
      * `subject.serve.url`. It must be same-origin (loopback) with it, and the participant opens
      * `serve.url + entry`. Validated at parse and re-enforced in the engine. Inert/warned on every
      * non-shared-world route (the per-lane-worlds fan-out roster has no per-participant entry).
      */
     entry?: string;
     /**
-     * External-public shared-world only (#164 phase 2): marks this participant as the host. It
-     * creates the shared session (e.g. a multiplayer lobby) that the follower seats then join. Exactly
+     * External-public shared-world only: marks this participant as the host. It
+     * creates the shared session (e.g. a multiplayer lobby) that the followers then join. Exactly
      * one participant in the roster may carry `host: true` (validated in externalPublicSharedWorldValidationReason).
-     * The orchestrator watches the host seat's observed URL for the shared-session code and threads it
+     * The orchestrator watches the host's observed URL for the shared-session code and threads it
      * into the follower missions at a host-first barrier. Inert/warned on every other route.
      */
     host?: boolean;
@@ -347,13 +349,13 @@ export interface LabParticipantEntry {
  * `lanes[]` with deterministic ids (`<group.id>-01`, `<group.id>-02`, ...). The runtime never
  * consumes this shape directly; it always sees ordinary `LabActorLane` entries.
  */
-export interface LabActorRosterGroup extends Omit<LabParticipantEntry, "id"> {
+export interface StudyActorRosterGroup extends Omit<StudyParticipantEntry, "id"> {
     /** Public-safe group id; prefixes generated participant ids. */
     id: string;
     /** Number of participants to generate for this group. */
     count: number;
 }
-export interface LabActor {
+export interface StudyActor {
     /**
      * The actor label. On computer-use (including shared-world), scripted-browser, and
      * terminal-product routes this is a real dispatch key resolved against the closed first-party
@@ -369,24 +371,25 @@ export interface LabActor {
     /** Computer-use E2B route: a differentiated fan-out roster (`per-lane-worlds`). XOR `count`,
      *  `roster`, and `laneFocus`. Cap 16 participants. Consumed only on the cua E2B route
      *  (inert/warned elsewhere). */
-    lanes?: LabParticipantEntry[];
+    lanes?: StudyParticipantEntry[];
     /** Persona id/label threaded into the actor prompt. Consumed on the app-url route. */
     persona?: string;
     /** Consumed on the app-url route (laneFocus.instruction appended to the mission). XOR `lanes`. */
-    laneFocus?: LabParticipantFocus;
+    laneFocus?: StudyParticipantFocus;
     /** Free-form mission threaded into the actor prompt. Consumed on the app-url route. A mission on
-     *  its own is a complete, valid lab — `tasks` is additive, never required. */
+     *  its own is a complete, valid study; `tasks` is additive, never required. */
     mission?: string;
     /**
      * The researcher's protocol: discrete tasks, each with what the participant is asked to do and
      * (optionally) how the researcher measures it. Additive to `mission`, which stays the brief.
      *
      * The two halves belong to different people. `goal` reaches the participant's prompt; `success`
-     * never does — a moderator does not read the success criterion aloud, because telling someone how
-     * they will be judged changes what they do. See src/lab/tasks.ts.
-     * Supported only on the first actor of per-participant CUA routes; other routes fail preflight.
+     * never does. A moderator does not read the success criterion aloud, because telling someone how
+     * they will be judged changes what they do. See src/study/tasks.ts.
+     * Supported only on the first actor of per-participant computer-use routes; other routes fail
+     * preflight.
      */
-    tasks?: LabTask[];
+    tasks?: StudyTask[];
     /** Provider model override. Consumed on the app-url route. */
     model?: string;
     /** First-party OpenAI CUA only: per-response output limit including reasoning, not a dollar cap. */
@@ -420,7 +423,7 @@ export interface LabActor {
      */
     stopWhen?: StopWhen;
     /**
-     * A declared observation window (#510), the default for every participant; a `lanes[]` entry's dwell overrides
+     * A declared observation window, the default for every participant; a `lanes[]` entry's dwell overrides
      * it. `when` is a stopWhen-shaped condition (absent: the window opens after the first
      * observation); `ms` is the hold, `everyMs` the frame cadence (default 10 s), `then` whether
      * the participant continues afterwards (default) or the session ends. The harness takes no
@@ -428,21 +431,21 @@ export interface LabActor {
      */
     dwell?: DwellWindow;
 }
-type LabExecutionTarget = "local" | "e2b-desktop" | "e2b-terminal";
+type StudyExecutionTarget = "local" | "e2b-desktop" | "e2b-terminal";
 /** Terminal transport: the captured non-interactive exec stream (stdin disabled). It is not an
- *  interactive duplex PTY — labeling captured exec output "pty" would be a claim/mechanism
- *  mismatch (invariant 6 + the goal packet's PTY ruling), so this route uses "exec-stream". */
-type LabTerminalTransport = "exec-stream";
+ *  interactive duplex PTY; labeling captured exec output "pty" would be a claim/mechanism
+ *  mismatch, so this route uses "exec-stream". */
+type StudyTerminalTransport = "exec-stream";
 /** Whether operator stdin reaches the in-sandbox agent. Disabled by default (the run is
  *  autonomous + comparable to an unassisted baseline). "planned" records intent but sends no
  *  input; "sent" is rejected because assisted-input capture and a non-comparable marker do not
  *  ship (the safety contract forbids an assisted run masquerading as green). */
-type LabTerminalStdin = "disabled" | "planned" | "sent";
-export interface LabExecutionTerminal {
+type StudyTerminalStdin = "disabled" | "planned" | "sent";
+export interface StudyExecutionTerminal {
     /** Transport label. Default and only shipped value is "exec-stream". */
-    transport?: LabTerminalTransport;
+    transport?: StudyTerminalTransport;
     /** Operator stdin posture. Default "disabled". */
-    stdin?: LabTerminalStdin;
+    stdin?: StudyTerminalStdin;
 }
 /**
  * The terminal agent's runtime-auth channel. "openai-env" (the default) passes the raw runtime
@@ -450,24 +453,24 @@ export interface LabExecutionTerminal {
  * OpenAI endpoint and passes an inert placeholder to Codex. The latter still gives every sandbox
  * process a spendable OpenAI proxy capability; it is not a spend cap or an egress restriction.
  */
-export type LabRuntimeAuth = "openai-env" | "openai-egress";
-export type LabDesktopBrowser = "default" | "chrome" | "chromium" | "firefox";
-export interface LabExecutionDesktop {
+export type StudyRuntimeAuth = "openai-env" | "openai-egress";
+export type StudyDesktopBrowser = "default" | "chrome" | "chromium" | "firefox";
+export interface StudyExecutionDesktop {
     /**
      * Named device preset (mobile / small-mobile / narrow-mobile / tablet / desktop / wide) the
      * run renders at. Consumed on the computer-use route; default `desktop` (1440x950). On that
      * route only width/height physically render (the X screen is sized to the preset, so
-     * width-based responsive CSS fires) — touch/DPR/UA are sim-parity prompt signals, not rendered.
+     * width-based responsive CSS fires). Touch/DPR/UA are sim-parity prompt signals and do not render.
      */
     device?: string;
-    /** Raw hosted screen resolution [width, height] — an escape hatch that overrides `device`. */
+    /** Raw hosted screen resolution [width, height]: an escape hatch that overrides `device`. */
     resolution?: [number, number];
     /**
      * Browser family to launch for hosted desktop participants. Absent/default preserves the
      * historical desktop opener behavior. A concrete value means "launch this browser or fail"
      * instead of silently accepting the template's default URL opener.
      */
-    browser?: LabDesktopBrowser;
+    browser?: StudyDesktopBrowser;
     /** Sandbox server-side timeout. Consumed on the app-url route. */
     sandboxTimeoutMs?: number;
     /**
@@ -485,7 +488,7 @@ export interface LabExecutionDesktop {
     /** Use the Codex app-server client mode for headed desktop actor surfaces. Consumed (meta). */
     codexAppServer?: boolean;
     /**
-     * Mobile fidelity beyond viewport size (#221). With `mobileEmulation: true`, every hosted
+     * Mobile fidelity beyond viewport size. With `mobileEmulation: true`, every hosted
      * Chromium computer-use participant on a mobile preset (mobile / small-mobile / narrow-mobile) gets
      * CDP device emulation applied to its launch page before the participant arrives; desktop,
      * tablet and wide participants in the same run are untouched and carry no fidelity block. Applied: the participant's device preset width/height as the CSS viewport, the preset's
@@ -496,22 +499,22 @@ export interface LabExecutionDesktop {
      * A held CDP session also applies the overrides to later page targets. Their first observed
      * viewport and touch read-back is recorded separately; missing or different values warn.
      */
-    fidelity?: LabDesktopFidelity;
-    /** Synthetic media devices behind the browser's own permission prompt (#509). */
-    media?: LabDesktopMedia;
+    fidelity?: StudyDesktopFidelity;
+    /** Synthetic media devices behind the browser's own permission prompt. */
+    media?: StudyDesktopMedia;
     /** Optional retained screen video. Capture is independent of participant media input. */
     recording?: {
         audio: boolean;
     };
 }
 /**
- * A participant with a camera (#509): a property of the environment, like the screen preset and
+ * A participant with a camera: a property of the environment, like the screen preset and
  * the browser, never support for any conferencing product. `camera.source: synthetic` generates
  * a test pattern in the sandbox with the image's own ffmpeg; a `.y4m` path on the host is
  * uploaded instead on hosted desktops. `microphone.source: speech` enables the participant's
  * own spoken replies and listening through native audio devices. File microphones are unsupported.
  */
-export interface LabDesktopMedia {
+export interface StudyDesktopMedia {
     camera?: {
         source: string;
     };
@@ -519,7 +522,7 @@ export interface LabDesktopMedia {
         source: string;
     };
 }
-export interface LabDesktopFidelity {
+export interface StudyDesktopFidelity {
     mobileEmulation: boolean;
     /** Emulated devicePixelRatio; default: the device preset's. */
     deviceScaleFactor?: number;
@@ -528,36 +531,37 @@ export interface LabDesktopFidelity {
     /** Full user-agent string to present; default: a mobile Safari string. */
     userAgent?: string;
 }
-export interface LabExecution {
-    target?: LabExecutionTarget;
+export interface StudyExecution {
+    target?: StudyExecutionTarget;
     /** Actor session wall-clock budget. Consumed on the app-url route. */
     timeoutMs?: number;
-    /** FORWARD-DECLARED. */
+    /** Forward-declared: no route reads it yet, so a set value warns. */
     completionTimeoutMs?: number;
     /**
      * Bounds in-flight fan-out participants on the computer-use route. Shared-world needs at least 2 and
      * defaults to the participant count. Inert (warned) elsewhere.
      */
     concurrency?: number;
-    desktop?: LabExecutionDesktop;
-    /**
-     * Blast-radius budget for each computer-use participant. Consumed on the CUA route: `caps.maxUsd`, when
-     * set, is a fail-closed abort: the session stops the moment its running estimated spend crosses
-     * it (the runaway-retry guard), and a cap on a model src/run/pricing.ts cannot price is refused at
-     * preflight rather than run uncapped. It is a PER-PARTICIPANT cap: enforced inside each participant's loop,
-     * so an N-participant fan-out can spend up to N × maxUsd before any participant aborts (the run warns with the
-     * true ~N × cap ceiling). `caps.maxTotalUsd` is the shared study budget (#299): one ledger
-     * across every participant, the knob a researcher actually reasons with. Absent = uncapped (the
-     * historical CUA behavior); maxUsd: 0 still permits a request before reported usage trips it. Inert
-     * (warned) on non-CUA routes. Reuses the same LabScenarioCaps shape as the terminal route's
-     * `scenario.caps` (not a fork).
-     */
-    caps?: LabScenarioCaps;
+    desktop?: StudyExecutionDesktop;
+    /**
+     * Blast-radius budget for each computer-use participant. Consumed on the computer-use route:
+     * `caps.maxUsd`, when set, is a fail-closed abort: the session stops the moment its running
+     * estimated spend crosses it (the runaway-retry guard), and a cap on a model src/run/pricing.ts
+     * cannot price is refused at preflight rather than run uncapped. It is a per-participant cap:
+     * enforced inside each participant's loop, so an N-participant fan-out can spend up to N × maxUsd
+     * before any participant aborts (the run warns with the true ~N × cap ceiling).
+     * `caps.maxTotalUsd` is the shared study budget: one ledger across every participant, the knob a
+     * researcher actually reasons with. Absent = uncapped (the historical CUA behavior); maxUsd: 0
+     * still permits a request before reported usage trips it. Inert (warned) on non-computer-use
+     * routes. Reuses the same StudyScenarioCaps shape as the terminal route's `scenario.caps` (not a
+     * fork).
+     */
+    caps?: StudyScenarioCaps;
     /** `terminal-product` route: the terminal transport + stdin posture. Consumed on that route. */
-    terminal?: LabExecutionTerminal;
+    terminal?: StudyExecutionTerminal;
     /** `terminal-product` route: runtime key placement, defaulting to openai-env. openai-egress
      *  uses an external header transform; dry-runs record declarations only. Inert on other routes. */
-    runtimeAuth?: LabRuntimeAuth;
+    runtimeAuth?: StudyRuntimeAuth;
     /** Terminal Codex package pin. Omit to resolve latest once, observe it, then execute that version. */
     runtime?: {
         version: string;
@@ -565,11 +569,11 @@ export interface LabExecution {
     /**
      * `terminal-product` route: outbound routing allowlist passed to E2B with a deny-all fallback.
      * Domain filtering is a routing control, not strict destination isolation on shared hosting.
-     * It does not constrain spending through an allowed runtime provider (#538), including when
+     * It does not constrain spending through an allowed runtime provider, including when
      * openai-egress keeps the raw runtime key outside the sandbox.
      *
      * Absent means unrestricted, which is the historical behavior and stays the default, because a
-     * wrong host list fails studies in ways that look like product bugs. Opt in per lab.
+     * wrong host list fails studies in ways that look like product bugs. Opt in per study.
      *
      * Domain filtering covers HTTP on :80 (Host header) and TLS on :443 (SNI); anything else needs
      * an IP or CIDR. `*.example.com` matches subdomains at any depth and not the apex, which needs
@@ -577,28 +581,28 @@ export interface LabExecution {
      */
     egressAllow?: string[];
 }
-type LabScenarioMode = "dry-run" | "live";
+type StudyScenarioMode = "dry-run" | "live";
 /**
  * The blast-radius budget for a route that passes a live key to an in-sandbox command.
  * Per the safety contract, the live key is never exercised without a fail-closed cap in force.
  * All values are non-negative numbers (0 is the no-spend default). Live runs require maxUsd and a
  * positive maxMinutes; maxUsd/maxJobs are checked after the session against known ledger signals
  * and maxMinutes is enforced as the command wall clock. Codex tokens are unpriced, so a live run
- * refuses a positive maxUsd unless a costProbe measures spend (HUMANISH_TERMINAL_LAB_UNPRICED_CAP).
+ * refuses a positive maxUsd unless a costProbe measures spend (HUMANISH_TERMINAL_UNPRICED_CAP).
  */
-export interface LabScenarioCaps {
+export interface StudyScenarioCaps {
     /** Max USD the run may spend (provider + product). 0 = no-spend. */
     maxUsd?: number;
     /**
-     * STUDY-LEVEL model-spend budget (#299), the number a researcher actually reasons with: "this
-     * study is N participants, roughly $X" — decided once, up front, where recruiting decisions are
+     * study-level model-spend budget, the number a researcher actually reasons with: "this
+     * study is N participants, roughly $X", decided once, up front, where recruiting decisions are
      * made. The computer-use route reads it from `execution.caps.maxTotalUsd` only: every participant's
      * running estimated model spend feeds one shared ledger, and the moment the run total crosses
-     * this, each participant stops at its next turn with an honest `budget_reached` (status `incomplete` —
+     * this, each participant stops at its next turn with `budget_reached` (status `incomplete`:
      * the participant ran out of budget; never `gave_up`, because a study-level stop is not the
      * participant's doing). Estimated model spend only; desktop-minutes ride the cost summary but
      * not this ledger. Independent of the per-participant `maxUsd` backstop; either, both, or neither may
-     * be set. A positive `scenario.caps.maxTotalUsd` on a computer-use lab is a parse error; on the
+     * be set. A positive `scenario.caps.maxTotalUsd` on a computer-use study is a parse error; on the
      * terminal route it is inert (warned), since the single agent's maxUsd already caps the run.
      */
     maxTotalUsd?: number;
@@ -607,19 +611,19 @@ export interface LabScenarioCaps {
     /** Max wall-clock minutes for the agent session. */
     maxMinutes?: number;
 }
-export interface LabScenario {
+export interface StudyScenario {
     /** Reference a committed scenario by id (humanish/scenarios/<ref>.yaml) or path. Consumed
-     *  (and required) on the scripted-browser route; FORWARD-DECLARED elsewhere. */
+     *  (and required) on the scripted-browser route; forward-declared elsewhere. */
     ref?: string;
-    /** Or inline the scenario body. FORWARD-DECLARED (PR #2). */
+    /** Or inline the scenario body. Forward-declared: no route reads it yet, so a set value warns. */
     inline?: Record<string, unknown>;
-    /** dry-run = contract evidence (no provider spend); live = real run. Consumed. */
-    mode?: LabScenarioMode;
+    /** dry-run = a synthetic bundle with no provider spend; live = real run. Consumed. */
+    mode?: StudyScenarioMode;
     /** Spend/job/time caps. Consumed (recorded in the bundle) on the terminal-product route;
      *  inert (warned) elsewhere. */
-    caps?: LabScenarioCaps;
+    caps?: StudyScenarioCaps;
 }
-export interface LabPolicies {
+export interface StudyPolicies {
     /**
      * Redact target repo labels in durable artifacts. Consumed on the computer-use,
      * scripted-browser and shared-world clone routes (provenance), where it defaults to true when
@@ -636,13 +640,13 @@ export interface LabPolicies {
      */
     redactScreenshots?: boolean;
     /**
-     * Allow an app-url subject to point at a non-loopback (public/preview/staging) URL the lab
+     * Allow an app-url subject to point at a non-loopback (public/preview/staging) URL the study
      * owner declares. Default `false` (loopback-only). The invariant is "the actor drives a target
      * the owner declared"; setting this is that declaration (e.g. a Vercel preview of your app).
      */
     allowPublicTargets?: boolean;
     /**
-     * How the browser's camera/microphone permission is answered (#509). `prompt` (default): the
+     * How the browser's camera/microphone permission is answered. `prompt` (default): the
      * participant meets Chrome's real dialog and answers it, which is where a real person hesitates
      * or refuses. `granted`: the dialog is bypassed (`--use-fake-ui-for-media-stream`, which Chrome
      * marks with an "unsupported command-line flag" banner), for studies about what happens after
@@ -658,33 +662,33 @@ export interface LabPolicies {
     /** Recorded GitHub-mutation intent. No GitHub-token injection channel ships. */
     allowGitHubMutation?: boolean;
 }
-export interface LabReview {
+export interface StudyReview {
     /** Analysis defaults on for eligible live recordings; false disables the separate request. */
-    analysis?: LabAnalysis | false;
-    /** FORWARD-DECLARED (PR #2). */
+    analysis?: StudyAnalysis | false;
+    /** Forward-declared: no route reads it yet, so a set value warns. */
     scoring?: string;
-    /** FORWARD-DECLARED (PR #2). */
+    /** Forward-declared: no route reads it yet, so a set value warns. */
     milestones?: string;
-    /** FORWARD-DECLARED (PR #2). */
+    /** Forward-declared: no route reads it yet, so a set value warns. */
     vocabulary?: string;
     /**
-     * #316 code escape hatch: a repo-relative path to an adopter scorer module (.mjs recommended) that
+     * Code escape hatch: a repo-relative path to an adopter scorer module (.mjs recommended) that
      * exports any of `{score, deriveFeedback, deriveArtifacts}`. Consumed on the scorer-capable routes
      * (terminal / computer-use / shared-world); loaded fail-closed (typed error, pre-spend). The entry
-     * is executable code — review a PR that adds one as code, not config.
+     * is executable code: review a PR that adds one as code.
      */
     scorer?: {
         ref: string;
     };
 }
-export interface LabDefaults {
+export interface StudyDefaults {
     open?: boolean;
 }
-/** Off-app comms (email/SMS the persona lives in) the harness provides for the run (#297). */
-export interface LabComms {
-    email?: LabCommsEmail;
+/** Off-app comms (email/SMS the persona lives in) the harness provides for the run. */
+export interface StudyComms {
+    email?: StudyCommsEmail;
 }
-export interface LabCommsSmtp {
+export interface StudyCommsSmtp {
     /** Fixed in-sandbox loopback SMTP port (default 2525). Known before sandbox create, like `port`. */
     port?: number;
     /** The subject-env var carrying the SMTP host. The harness sets it to 127.0.0.1. */
@@ -699,8 +703,8 @@ export interface LabCommsSmtp {
     user?: string;
     password?: string;
 }
-export type LabCommsEmail = LabCommsCaptureEmail | LabCommsReceivingEmail;
-export interface LabCommsReceivingEmail {
+export type StudyCommsEmail = StudyCommsCaptureEmail | StudyCommsReceivingEmail;
+export interface StudyCommsReceivingEmail {
     kind: "real";
     connection: string;
     /** Additional exact first-hop destinations; automatic remote email assets remain blocked. */
@@ -712,16 +716,16 @@ export interface LabCommsReceivingEmail {
     recipients?: never;
     external?: never;
 }
-interface LabCommsCaptureEmail {
+interface StudyCommsCaptureEmail {
     connection?: never;
     allowedOrigins?: never;
     /** Which implementation backs the inbox (a backend discriminator, distinct from `scenario.mode`):
-     *  `fake` (default) is an in-harness in-memory inbox in the Fowler test-double sense — an in-sandbox
+     *  `fake` (default) is an in-harness in-memory inbox in the Fowler test-double sense: an in-sandbox
      *  catch captures the app's sends. Provider-backed receiving uses the separate
-     *  LabCommsReceivingEmail configuration selected by a saved connection. */
+     *  StudyCommsReceivingEmail configuration selected by a saved connection. */
     kind: "fake";
     /**
-     * The subject-env var the harness sets to the in-sandbox catch's base URL — ADOPTER-NAMED (an app
+     * The subject-env var the harness sets to the in-sandbox catch's base URL. The adopter names it (an app
      * calling Resend's API directly reads `RESEND_API_URL`; an app using the SDK reads `RESEND_BASE_URL`).
      * The value is computed by the harness (a loopback URL), so it is not declared in `subject.env`.
      * Required on the provisioned routes; absent (and meaningless) when `external` is declared,
@@ -736,10 +740,10 @@ interface LabCommsCaptureEmail {
      * into the same captured-send shape the HTTP path produces, so the inbox surface, the drain, and
      * the evidence artifact are identical either way.
      *
-     * `hostEnv` and `portEnv` are ADOPTER-NAMED, exactly like `injectEnv`: the harness sets them to
+     * `hostEnv` and `portEnv` are adopter-named, exactly like `injectEnv`: the harness sets them to
      * its own loopback and the chosen port. Declare the pair your app actually reads.
      */
-    smtp?: LabCommsSmtp;
+    smtp?: StudyCommsSmtp;
     /** Optional escape hatch: the exact absolute origin the app-under-test bakes into its email verify
      *  links, when that differs from the serve origin (e.g. an app configured with an absolute
      *  APP_URL/NEXT_PUBLIC_BASE_URL). The harness cannot infer it, so the operator declares it; it is
@@ -749,24 +753,25 @@ interface LabCommsCaptureEmail {
     /** Each participant's inbox address: the actor is told to sign up with it (the injected inbox
      *  instruction carries it) and the teardown drain matches captured mail against it. Omit the
      *  whole list and the parser fills one deterministic address per participant (`<laneId>@example.test`)
-     *  so every seat can do email out of the box (#351). When declared: a `lane` naming a participant that
-     *  does not exist is a hard parse error (a mismatch silently disables the funnel for that seat),
-     *  zero covered participants is a hard error, and partial coverage warns with the uncovered ones. An
-     *  entry without `address` is legal but inert for the funnel: the drain does not match it,
-     *  and its participant gets no inbox instruction; captured mail to an undeclared address is warned,
+     *  so every participant can do email out of the box. When declared: a `lane` naming a participant
+     * that  does not exist is a hard parse error (a mismatch silently disables the funnel for that
+     * participant),  zero covered participants is a hard error, and partial coverage warns with the
+     * uncovered ones. An  entry without `address` is legal but inert for the funnel: the drain does
+     * not match it,  and its participant gets no inbox instruction; captured mail to an undeclared
+     * address is warned,
      *  never silently dropped. */
-    recipients?: LabCommsRecipient[];
+    recipients?: StudyCommsRecipient[];
     /**
-     * ADOPTER-HOSTED ingress (#328). Declaring this says: the operator runs the catch and the inbox
-     * themselves, so humanish neither provisions the subject nor injects `injectEnv` — it points the
+     * adopter-hosted ingress. Declaring this says: the operator runs the catch and the inbox
+     * themselves, so humanish neither provisions the subject nor injects `injectEnv`. It points the
      * persona at the declared inbox, drains the declared catch over HTTP at teardown, and writes the
      * same digest-only evidence. This is what makes comms work on the app-url / operator-provisioned
      * plane, where humanish holds no sandbox handle to host a catch in and the block was previously
      * warned inert. Run the same implementation with `humanish comms catch`.
      */
-    external?: LabCommsExternal;
+    external?: StudyCommsExternal;
 }
-export interface LabCommsExternal {
+export interface StudyCommsExternal {
     /** Where the adopter's app POSTs its email sends, and where humanish reads GET /deliveries. */
     catchBaseUrl: string;
     /** Where the persona opens its inbox. Defaults to catchBaseUrl (one server serves both). */
@@ -775,39 +780,40 @@ export interface LabCommsExternal {
      *  the value is read at runtime and never persisted (the credential-boundary discipline). */
     authTokenEnv?: string;
 }
-export interface LabCommsRecipient {
+export interface StudyCommsRecipient {
     lane: string;
-    /** The literal address the app sends to — what the evidence drain matches. Omit to reserve the participant
+    /** The literal address the app sends to, which the evidence drain matches. Omit to reserve the participant
      *  for the persona surface's default address (not drain-matched). */
     address?: string;
 }
-export interface LabConfig {
-    schema: typeof LAB_CONFIG_SCHEMA;
+export interface StudyConfig {
+    /** The format the file was written in. Both parse into this one shape. */
+    schema: typeof V2_SCHEMA | typeof STUDY_SCHEMA;
     id: string;
     title?: string;
     description?: string;
-    subject: LabSubject;
-    actors: LabActor[];
-    execution?: LabExecution;
-    /** FORWARD-DECLARED (PR #2). */
+    subject: StudySubject;
+    actors: StudyActor[];
+    execution?: StudyExecution;
+    /** Forward-declared: no route reads it yet, so a set value warns. */
     personas?: Record<string, unknown>[];
-    scenario?: LabScenario;
-    policies?: LabPolicies;
-    review?: LabReview;
-    defaults?: LabDefaults;
-    comms?: LabComms;
+    scenario?: StudyScenario;
+    policies?: StudyPolicies;
+    review?: StudyReview;
+    defaults?: StudyDefaults;
+    comms?: StudyComms;
 }
-interface LabConfigParseSuccess {
+interface StudyParseSuccess {
     ok: true;
-    config: LabConfig;
+    config: StudyConfig;
     warnings: string[];
 }
-export interface LabConfigParseFailure {
+export interface StudyParseFailure {
     ok: false;
     error: {
-        code: "HUMANISH_LAB_INVALID";
+        code: "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_V2_UNSUPPORTED";
         message: string;
     };
 }
-export type LabConfigParseResult = LabConfigParseSuccess | LabConfigParseFailure;
+export type StudyParseResult = StudyParseSuccess | StudyParseFailure;
 export {};