humanish 0.108.0 → 0.109.0

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

@@ -1,8 +1,8 @@
-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;
@@ -12,11 +12,11 @@ export declare const ID_PATTERN: RegExp;
  * 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 computer-use route and is library-assisted: a caller supplies
- * `RunLabOptions.inProcess` + `createProvider` (no built-in driver exists yet), and the engine
+ * `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
@@ -26,8 +26,8 @@ type LabSubjectSource = "this-repo" | "clone" | "app-url" | "local-app" | "termi
  * external-public app-url plane) with a computer-use actor; inert/warned everywhere else
  * (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). */
@@ -37,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). */
@@ -48,14 +48,14 @@ 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. */
     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, which governs app-url subjects, i.e. external deployments). */
     url: string;
@@ -67,8 +67,8 @@ 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, so
@@ -88,7 +88,7 @@ interface LabSubjectStateStep {
      * 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;
 }
@@ -99,7 +99,7 @@ interface LabSubjectStateStep {
  * (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>`), a shape validated at
@@ -120,11 +120,11 @@ 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".
      */
@@ -134,7 +134,7 @@ export interface LabSubjectState {
      * role's turn to produce the harness-clocked interaction timeline. Consumed only on the
      * 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
@@ -142,8 +142,8 @@ export interface LabSubjectState {
  * 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
@@ -153,7 +153,7 @@ export interface LabSubjectProduct {
      * Absent means the participant installs it themselves from the public surfaces, which is a
      * 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.
      */
@@ -164,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.
      */
@@ -186,8 +186,8 @@ export interface LabSubjectProduct {
      */
     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 study is byte-stable). `shared-world` is the declared override: one mutable service
@@ -195,7 +195,7 @@ export interface LabSubject {
      * 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: the author's required attestation that the
      * subject behind the internet-reachable `getHost` URL is synthetic seeded data. The concurrent
@@ -223,12 +223,12 @@ 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
      * 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
@@ -236,7 +236,7 @@ export interface LabSubject {
      */
     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
@@ -244,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
@@ -260,22 +260,22 @@ export interface LabSubject {
      * 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. */
@@ -288,7 +288,7 @@ 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 {
+export interface StudyParticipantEntry {
     /** Public-safe participant id (interpolates into its evidence paths). Default `lane-NN`. */
     id?: string;
     /**
@@ -349,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
@@ -371,13 +371,13 @@ 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
@@ -385,11 +385,11 @@ export interface LabActor {
      *
      * 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.
+     * 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. */
@@ -431,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, so this route uses "exec-stream". */
-type LabTerminalTransport = "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
@@ -453,9 +453,9 @@ 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
@@ -470,7 +470,7 @@ export interface LabExecutionDesktop {
      * 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;
     /**
@@ -499,9 +499,9 @@ 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;
+    fidelity?: StudyDesktopFidelity;
     /** Synthetic media devices behind the browser's own permission prompt. */
-    media?: LabDesktopMedia;
+    media?: StudyDesktopMedia;
     /** Optional retained screen video. Capture is independent of participant media input. */
     recording?: {
         audio: boolean;
@@ -514,7 +514,7 @@ export interface LabExecutionDesktop {
  * 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;
     };
@@ -522,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;
@@ -531,8 +531,8 @@ 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: no route reads it yet, so a set value warns. */
@@ -542,7 +542,7 @@ export interface LabExecution {
      * defaults to the participant count. Inert (warned) elsewhere.
      */
     concurrency?: number;
-    desktop?: LabExecutionDesktop;
+    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
@@ -553,15 +553,15 @@ export interface LabExecution {
      * `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 LabScenarioCaps shape as the terminal route's `scenario.caps` (not a
+     * routes. Reuses the same StudyScenarioCaps shape as the terminal route's `scenario.caps` (not a
      * fork).
      */
-    caps?: LabScenarioCaps;
+    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;
@@ -573,7 +573,7 @@ export interface LabExecution {
      * 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
@@ -581,7 +581,7 @@ 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.
@@ -590,7 +590,7 @@ type LabScenarioMode = "dry-run" | "live";
  * 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_UNPRICED_CAP).
  */
-export interface LabScenarioCaps {
+export interface StudyScenarioCaps {
     /** Max USD the run may spend (provider + product). 0 = no-spend. */
     maxUsd?: number;
     /**
@@ -602,7 +602,7 @@ export interface LabScenarioCaps {
      * 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;
@@ -611,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. */
     ref?: string;
     /** Or inline the scenario body. Forward-declared: no route reads it yet, so a set value warns. */
     inline?: Record<string, unknown>;
     /** dry-run = a synthetic bundle with no provider spend; live = real run. Consumed. */
-    mode?: LabScenarioMode;
+    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
@@ -640,7 +640,7 @@ 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).
      */
@@ -662,9 +662,9 @@ 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;
+    analysis?: StudyAnalysis | false;
     /** Forward-declared: no route reads it yet, so a set value warns. */
     scoring?: string;
     /** Forward-declared: no route reads it yet, so a set value warns. */
@@ -681,14 +681,14 @@ export interface LabReview {
         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. */
-export interface LabComms {
-    email?: LabCommsEmail;
+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. */
@@ -703,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. */
@@ -716,13 +716,13 @@ 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
      *  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. The adopter names it (an app
@@ -743,7 +743,7 @@ interface LabCommsCaptureEmail {
      * `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
@@ -760,7 +760,7 @@ interface LabCommsCaptureEmail {
      * 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. Declaring this says: the operator runs the catch and the inbox
      * themselves, so humanish neither provisions the subject nor injects `injectEnv`. It points the
@@ -769,9 +769,9 @@ interface LabCommsCaptureEmail {
      * 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). */
@@ -780,40 +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, 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 {
+export interface StudyConfig {
     /** The format the file was written in. Both parse into this one shape. */
-    schema: typeof LAB_CONFIG_SCHEMA | typeof STUDY_SCHEMA;
+    schema: typeof V2_SCHEMA | typeof STUDY_SCHEMA;
     id: string;
     title?: string;
     description?: string;
-    subject: LabSubject;
-    actors: LabActor[];
-    execution?: LabExecution;
+    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_STUDY_INVALID";
+        code: "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_V2_UNSUPPORTED";
         message: string;
     };
 }
-export type LabConfigParseResult = LabConfigParseSuccess | LabConfigParseFailure;
+export type StudyParseResult = StudyParseSuccess | StudyParseFailure;
 export {};

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

@@ -1,6 +1,6 @@
 import {} from "../analysis/automatic-config.js";
 import {} from "../actors/reasoning-effort.js";
-export const LAB_CONFIG_SCHEMA = "humanish.lab.v2";
+export const V2_SCHEMA = "humanish.lab.v2";
 /** The study format: it declares its route, one actor, its participants and one caps block. */
 export const STUDY_SCHEMA = "humanish.study.v3";
 // Must start alphanumeric so an id never collides with the path-vs-id resolver heuristic