humanish 0.107.0 → 0.109.0

package/dist/{lab → study}/composition-rules.js

@@ -1,15 +1,15 @@
-// Which subject, target and actor compositions a lab may declare. Each rule returns the refusal
+// Which subject, target and actor compositions a study may declare. Each rule returns the refusal
 // message for the first thing its composition gets wrong, or null. compositionReason runs them in
-// the parser's order, and only parseLabConfig calls it. planLab does not: each route planner checks
+// the parser's order, and only parseStudy calls it. planStudy does not: each route planner checks
 // a library caller's config itself, under its route's error codes. The planners call the shared
-// checks in lab/validation.ts and desktopCliProductReason below. The other subject rules here have
+// checks in study/validation.ts and desktopCliProductReason below. The other subject rules here have
 // planner counterparts whose conditions and wording differ (clone serve and repo, local-tree
 // target, in-process fan-out, loopback targets, scripted scenario.ref).
 import { isLoopbackUrl } from "./parse/subject.js";
 import { REPO_SLUG_PATTERN } from "./parse/values.js";
 import { declaredTargets } from "./plan-participants.js";
-import { actorResolvesToComputerUse, actorResolvesToScriptedBrowser, actorResolvesToTerminal, cuaLaneCount, registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, isComputerUseComposition, } from "./routing.js";
-import { cloneTargetValidationReason, cuaLaneValidationReason, sharedWorldValidationReason, } from "./validation.js";
+import { actorResolvesToComputerUse, actorResolvesToScriptedBrowser, actorResolvesToTerminal, computerUseParticipantCount, registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, isComputerUseComposition, } from "./routing.js";
+import { cloneTargetValidationReason, computerUseValidationReason, sharedWorldValidationReason, } from "./validation.js";
 import { rosterOf } from "./parse/actors.js";
 /** The first composition rule a config breaks, in the parser's order, or null. */
 export function compositionReason(config) {
@@ -22,7 +22,7 @@ export function compositionReason(config) {
         cloneComputerUseValidationReason(config) ??
         localTreeValidationReason(config) ??
         // Independent computer-use participants: the roster contract on every route that resolves to cua.
-        (isComputerUseComposition(config) ? cuaLaneValidationReason(config) : null) ??
+        (isComputerUseComposition(config) ? computerUseValidationReason(config) : null) ??
         // Whenever shared world is declared, not only when it routes, so a half-declared shared world
         // fails with a precise reason instead of running as independent participants.
         (config.subject.topology === "shared-world" ? sharedWorldValidationReason(config) : null) ??
@@ -30,14 +30,14 @@ export function compositionReason(config) {
         terminalValidationReason(config) ??
         cloneActorValidationReason(config));
 }
-/** Why a this-repo lab cannot run live. The parser and the preview planner both refuse with it. */
-export const THIS_REPO_DRY_RUN_ONLY = "this-repo labs are dry-run only; use a clone or app-url subject for a live run.";
-// this-repo subjects run locally and dry-run only — there is no live execution target for the
+/** Why a this-repo study cannot run live. The parser and the preview planner both refuse with it. */
+export const THIS_REPO_DRY_RUN_ONLY = "this-repo studies are dry-run only; use a clone or app-url subject for a live run.";
+// this-repo subjects run locally and dry-run only: there is no live execution target for the
 // host repo (clone/app-url provide that). Reject the mis-configs rather than silently mishandle.
 function thisRepoValidationReason(config) {
     if (config.subject.source === "this-repo") {
         if (config.execution?.target) {
-            return "`execution.target` applies only to clone/app-url/local-app subjects; this-repo labs run locally.";
+            return "`execution.target` applies only to clone/app-url/local-app subjects; this-repo studies run locally.";
         }
         if (config.scenario?.mode === "live") {
             return THIS_REPO_DRY_RUN_ONLY;
@@ -51,51 +51,51 @@ function thisRepoValidationReason(config) {
 // desktop), and no public-target policy (it is always loopback; the loopback shape was already
 // enforced in parseSubject). The actual "no inProcess executor supplied" case is inherently an
 // engine-time decision (the parser cannot know whether a library caller will pass one), so
-// it fails closed in runCuaActorLab with HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR.
+// it fails closed in runCuaActorStudy with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
         const type = config.actors[0]?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "local") {
-            return "local-app subjects drive an in-process LOCAL dev server with NO E2B desktop — set `execution.target: local` or omit it (absent means local); `e2b-desktop` is rejected (use an app-url subject for the hosted-desktop route).";
+            return "A local-app subject drives a local dev server in this process, with no E2B desktop. Set `execution.target: local` or omit it. To run on a hosted desktop, use an app-url subject with `execution.target: e2b-desktop`.";
         }
         if (!actorResolvesToComputerUse(type)) {
             return `actors[0].type must be a registered computer-use actor for local-app subjects (one of: ${registeredComputerUseActors().join(", ")}); the caller's custom executor runs the computer-use loop. Got "${type}".`;
         }
-        if (cuaLaneCount(config) > 1) {
+        if (computerUseParticipantCount(config) > 1) {
             return "Fan-out to more than one participant is not supported on the in-process/local-app route: fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Set actors[0].count to 1 and drop actors[0].lanes (use an app-url or clone subject on execution.target: e2b-desktop for fan-out).";
         }
         if (rosterOf(config.actors[0]) !== undefined) {
             return "`actors[0].lanes` (fan-out roster) is not supported on the in-process/local-app route: it provisions one E2B desktop per participant, which this route skips. Use an app-url or clone subject with execution.target: e2b-desktop.";
         }
         if (config.policies?.allowPublicTargets === true) {
-            return "`policies.allowPublicTargets` is not supported on the local-app route — a local-app subject is always a loopback dev server; there is no public target to allow.";
+            return "`policies.allowPublicTargets` does not apply to a local-app subject: it is always a loopback dev server, so there is no public target to allow. Remove the setting.";
         }
     }
     return null;
 }
-// app-url routes: the actor type is a real dispatch key (registry-resolved). The actor lane
+// app-url routes: the actor type is a real dispatch key (registry-resolved). The actor's run kind
 // picks the substrate: a scripted-browser actor runs locally against the declared loopback
 // app; a computer-use actor drives a hosted desktop browser. Fail closed on mis-configs.
 function appUrlValidationReason(config) {
     if (config.subject.source === "app-url") {
         const type = config.actors[0]?.type ?? "";
         if (actorResolvesToScriptedBrowser(type)) {
-            // Scripted-browser route (all fail-closed: invariant 6 — a field that cannot act on
+            // Scripted-browser route (all fail-closed, so claims match mechanism: a field that cannot act on
             // this route is rejected, never silently ignored).
             if (config.execution?.target !== undefined && config.execution.target !== "local") {
-                return "scripted-browser actors run on the operator's machine — set `execution.target: local` or omit it (absent means local); in-sandbox scripted execution is a later slice.";
+                return "A scripted-browser actor on an app-url subject runs on this machine. Set `execution.target: local` or omit it. To run scripted steps on a hosted desktop, use a clone subject.";
             }
             if (!config.scenario?.ref) {
-                return "scripted-browser labs require `scenario.ref` — the committed scenario's browser steps are what this actor executes.";
+                return "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.";
             }
             if ((config.actors[0]?.count ?? 1) > 2) {
-                return "scripted-browser labs support actors[0].count of 1 (desktop surface) or 2 (desktop + mobile); larger fan-out is a later slice.";
+                return "A scripted-browser study takes `actors[0].count` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
             }
             if (config.policies?.redactScreenshots === true) {
-                return "`policies.redactScreenshots: true` is not implemented on the scripted-browser route yet — screenshots persist raw in gitignored .humanish; a silently ignored redaction policy would be a safety lie, so it is rejected.";
+                return "`policies.redactScreenshots: true` is not supported on the scripted-browser route yet, so its screenshots would be stored unredacted in .humanish/. Remove the setting, or use a computer-use actor, which blurs screenshots as it takes them.";
             }
             if (config.policies?.allowPublicTargets === true) {
-                return "`policies.allowPublicTargets` is not supported on the scripted-browser route — the scripted step driver enforces loopback at every navigation; public targets on this route are a later slice.";
+                return "`policies.allowPublicTargets` is not supported on the scripted-browser route: the step driver allows only loopback URLs at every navigation. Remove the setting, or drive the public URL with a computer-use actor.";
             }
             if (!isLoopbackUrl(config.subject.appUrl ?? "")) {
                 return "`subject.appUrl` must be a loopback URL (127.0.0.1/localhost) on the scripted-browser route.";
@@ -106,7 +106,7 @@ function appUrlValidationReason(config) {
                 return "app-url computer-use subjects require `execution.target: local` or `e2b-desktop`.";
             }
             if (!actorResolvesToComputerUse(type)) {
-                return `actors[0].type must be a registered computer-use actor for app-url × e2b-desktop labs (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
+                return `actors[0].type must be a registered computer-use actor for app-url × e2b-desktop studies (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
             }
             // Multi-participant fan-out is consumed on this route (`per-lane-worlds`; the shared cua
             // cross-validation below enforces `lanes`/`count` XOR rules, the 16 cap, and the
@@ -116,7 +116,7 @@ function appUrlValidationReason(config) {
             const targets = [config.subject.appUrl ?? "", ...declaredTargets(config)];
             const unsafeTarget = targets.find((target) => !config.policies?.allowPublicTargets && !isLoopbackUrl(target));
             if (unsafeTarget !== undefined) {
-                return "`subject.appUrl` and `actors[0].lanes[].target` must be loopback URLs (127.0.0.1/localhost) unless `policies.allowPublicTargets: true` is set — set it to drive deployed/preview URLs you own.";
+                return "`subject.appUrl` and `actors[0].lanes[].target` must be loopback URLs (127.0.0.1 or localhost). To drive a deployed or preview URL you own, set `policies.allowPublicTargets: true`.";
             }
         }
     }
@@ -130,54 +130,54 @@ function scriptedBrowserValidationReason(config) {
             return "scripted-browser actors require `subject.source: app-url` (a running app at a loopback URL) or `subject.source: clone` with `execution.target: e2b-desktop` (a provisioned synthetic subject).";
         }
         if (config.execution?.target !== "e2b-desktop") {
-            return "clone subjects with scripted-browser actors require `execution.target: e2b-desktop` — the lab provisions the clone in E2B, exposes it with getHost, then drives deterministic browser steps.";
+            return "A clone subject with a scripted-browser actor needs `execution.target: e2b-desktop`: humanish builds the clone in an E2B sandbox, opens it at a public sandbox URL and runs the scenario's browser steps against it.";
         }
         if (!config.subject.serve) {
-            return "clone subjects with scripted-browser actors require `subject.serve` (start + url) — the lab serves the app in-sandbox before the scripted browser drives it.";
+            return "A clone subject with a scripted-browser actor needs `subject.serve` (start and url): humanish starts the app in the sandbox before the browser steps run.";
         }
         if ((config.subject.repos?.length ?? 0) !== 1) {
-            return "clone scripted-browser labs require exactly one repo in subject.repos.";
+            return "clone scripted-browser studies require exactly one repo in subject.repos.";
         }
         const repo = config.subject.repos?.[0] ?? "";
         if (!REPO_SLUG_PATTERN.test(repo)) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
         if (config.subject.topology !== undefined) {
-            return "clone scripted-browser labs do not support `subject.topology` yet — this slice provisions one synthetic subject and one deterministic scripted actor roster, not a shared-world run.";
+            return "A clone scripted-browser study does not support `subject.topology` yet: it runs one synthetic subject for its scripted actor. Remove `subject.topology`.";
         }
         if (config.subject.clone?.fanout !== undefined || config.subject.clone?.keep === true) {
-            return "clone scripted-browser labs do not support `subject.clone.fanout` or `subject.clone.keep` yet — the provisioned subject is always a single disposable E2B sandbox.";
+            return "A clone scripted-browser study does not support `subject.clone.fanout` or `subject.clone.keep` yet: its subject is always one sandbox, removed after the run.";
         }
         if (!config.scenario?.ref) {
-            return "scripted-browser labs require `scenario.ref` — the committed scenario's browser steps are what this actor executes.";
+            return "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.";
         }
         if ((config.actors[0]?.count ?? 1) > 2) {
-            return "scripted-browser labs support actors[0].count of 1 (desktop surface) or 2 (desktop + mobile); larger fan-out is a later slice.";
+            return "A scripted-browser study takes `actors[0].count` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
         }
         if (rosterOf(config.actors[0]) !== undefined) {
-            return "`actors[0].lanes` is not supported on the scripted-browser route yet — use actors[0].count for the deterministic surface roster.";
+            return "`actors[0].lanes` is not supported on the scripted-browser route yet. Use `actors[0].count` to choose the desktop and mobile surfaces.";
         }
         if (config.policies?.redactScreenshots === true) {
-            return "`policies.redactScreenshots: true` is not implemented on the scripted-browser route yet — screenshots persist raw in gitignored .humanish; a silently ignored redaction policy would be a safety lie, so it is rejected.";
+            return "`policies.redactScreenshots: true` is not supported on the scripted-browser route yet, so its screenshots would be stored unredacted in .humanish/. Remove the setting, or use a computer-use actor, which blurs screenshots as it takes them.";
         }
         if (config.policies?.allowPublicTargets === true) {
-            return "`policies.allowPublicTargets` is not supported on the clone scripted-browser route — the only external host is the harness-minted getHost URL for a provisioned synthetic subject.";
+            return "`policies.allowPublicTargets` does not apply to a clone scripted-browser study: its only public URL is the sandbox URL humanish opens for its synthetic subject. Remove the setting.";
         }
         if (config.subject.exposure !== "synthetic") {
-            return "clone scripted-browser labs require `subject.exposure: synthetic` — the subject is exposed on an internet-reachable getHost URL for the run, so the author must attest it is synthetic seeded data.";
+            return "A clone scripted-browser study needs `subject.exposure: synthetic`. The subject is reachable from the internet at a public sandbox URL during the run, so the study must declare that its data is synthetic.";
         }
         if (!config.subject.state?.seed ||
             config.subject.state.seed.length === 0 ||
             (config.subject.state.external?.length ?? 0) > 0) {
-            return "clone scripted-browser labs require `subject.state.seed` and do not allow `subject.state.external` — getHost-exposed subjects must be synthetic seeded data, not external/unpinned state.";
+            return "A clone scripted-browser study needs `subject.state.seed` and cannot use `subject.state.external`: a subject at a public sandbox URL may hold only seeded synthetic data.";
         }
         if (!config.subject.serve.start.includes("0.0.0.0")) {
-            return "clone scripted-browser labs require `subject.serve.start` to bind all interfaces (e.g. `-H 0.0.0.0` / `--host 0.0.0.0` / `HOST=0.0.0.0`) — getHost only routes to a 0.0.0.0-bound port; the readiness probe stays loopback.";
+            return "A clone scripted-browser study needs `subject.serve.start` to listen on all interfaces (for example `-H 0.0.0.0`, `--host 0.0.0.0` or `HOST=0.0.0.0`): the public sandbox URL reaches only a port bound to 0.0.0.0. The readiness probe still uses loopback.";
         }
     }
     return null;
 }
-// clone × e2b-desktop disambiguates on the actor lane: a computer-use actor means the lab
+// clone × e2b-desktop disambiguates on the actor's run kind: a computer-use actor means the study
 // clones and serves the subject in-sandbox, then drives it. Scripted-browser actors were checked
 // above.
 function cloneComputerUseValidationReason(config) {
@@ -185,10 +185,10 @@ function cloneComputerUseValidationReason(config) {
         config.execution?.target === "e2b-desktop" &&
         actorResolvesToComputerUse(config.actors[0]?.type)) {
         if (!config.subject.serve) {
-            return "clone subjects on the computer-use route require `subject.serve` (start + url) — the lab serves the app in-sandbox before the actor drives it.";
+            return "A clone subject on the computer-use route needs `subject.serve` (start and url): humanish starts the app in the sandbox before the participant opens it.";
         }
         if ((config.subject.repos?.length ?? 0) !== 1) {
-            return "computer-use clone labs serve one repo; declare exactly one repo in subject.repos.";
+            return "computer-use clone studies serve one repo; declare exactly one repo in subject.repos.";
         }
         const repo = config.subject.repos?.[0] ?? "";
         if (!REPO_SLUG_PATTERN.test(repo)) {
@@ -216,18 +216,18 @@ function localTreeValidationReason(config) {
     }
     return null;
 }
-// desktop-cli route: a computer-use participant studies a CLI/TUI the way a person does — at a
+// desktop-cli route: a computer-use participant studies a CLI/TUI the way a person does: at a
 // desktop, in a terminal window, by looking at it. The sibling of terminal-product, and the
 // distinction is the population: terminal-product sends an autonomous agent
-// through a pipe with stdin disabled, which is the honest way to study what an agent meets and
+// through a pipe with stdin disabled, which matches what an agent meets and
 // structurally cannot study an interactive surface. This route sends someone who can see it.
 //
-// Fail-closed on the pairing (invariant 6): a hosted desktop and a computer-use actor, because
+// Fail-closed on the pairing: a hosted desktop and a computer-use actor, because
 // "watch a person use a terminal" is not something the other substrates can do.
 /** A desktop-cli subject with no product to study. The computer-use planner checks this too. */
 export function desktopCliProductReason(config) {
     return config.subject.source === "desktop-cli" && config.subject.product?.name === undefined
-        ? "desktop-cli subjects need `subject.product.name` — the CLI the participant is being asked to use."
+        ? "A desktop-cli subject needs `subject.product.name`: the CLI the participant is asked to use."
         : null;
 }
 function desktopCliValidationReason(config) {
@@ -236,7 +236,7 @@ function desktopCliValidationReason(config) {
         return productReason;
     if (config.subject.source === "desktop-cli" && config.subject.product !== undefined) {
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-desktop") {
-            return "desktop-cli subjects are studied at a hosted desktop — set `execution.target: e2b-desktop` or omit it.";
+            return "A desktop-cli subject runs on a hosted desktop. Set `execution.target: e2b-desktop` or omit it.";
         }
         if (!actorResolvesToComputerUse(config.actors[0]?.type ?? "")) {
             return "desktop-cli subjects need a registered computer-use actor: the participant reads the screen and types, which is what makes an interactive surface studiable at all.";
@@ -248,16 +248,16 @@ function desktopCliValidationReason(config) {
     }
     return null;
 }
-// terminal-product route: a real autonomous agent studies a CLI/product from public surfaces
-// inside an E2B shell. Fail-closed (invariant 6 — a field that cannot act on this route is an
-// honest parse error): a registered terminal actor only, execution.target e2b-terminal or absent
-// (absent defaults to e2b-terminal — the only honest target for an in-sandbox agent), one
-// participant until fan-out lands.
+// terminal-product route: a real autonomous agent studies a CLI/product from public surfaces inside
+// an E2B shell. Fail-closed (claims match mechanism: a field that cannot act on this route is a
+// parse error): a registered terminal actor only, execution.target e2b-terminal or absent (absent
+// defaults to e2b-terminal, the only target where an in-sandbox agent runs), one participant until
+// fan-out lands.
 function terminalValidationReason(config) {
     if (config.subject.source === "terminal-product") {
         const type = config.actors[0]?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-terminal") {
-            return "terminal-product subjects run the agent inside an E2B shell — set `execution.target: e2b-terminal` or omit it (absent means e2b-terminal); `local`/`e2b-desktop` are rejected.";
+            return "A terminal-product subject runs its agent in an E2B shell. Set `execution.target: e2b-terminal` or omit it; `local` and `e2b-desktop` are not supported.";
         }
         if (!actorResolvesToTerminal(type)) {
             return `actors[0].type must be a registered terminal actor for terminal-product subjects (one of: ${registeredTerminalActors().join(", ")}). Got "${type}".`;
@@ -268,7 +268,7 @@ function terminalValidationReason(config) {
     }
     else if (config.execution?.target === "e2b-terminal") {
         // e2b-terminal is the terminal-product substrate only. Any other source declaring it is a
-        // mis-config — reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
+        // mis-config: reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
         return "`execution.target: e2b-terminal` requires `subject.source: terminal-product` with a registered terminal actor.";
     }
     else if (actorResolvesToTerminal(config.actors[0]?.type)) {
@@ -278,14 +278,14 @@ function terminalValidationReason(config) {
     }
     return null;
 }
-// A clone lab is served in-sandbox for a participant to drive, so only a computer-use or a
+// A clone study is served in-sandbox for a participant to drive, so only a computer-use or a
 // scripted-browser actor can run it. Any other actor would parse and then fail at run start.
 // Terminal actors were already refused above with their own message.
 function cloneActorValidationReason(config) {
     if (config.subject.source === "clone") {
         const type = config.actors[0]?.type ?? "";
         if (!actorResolvesToComputerUse(type) && !actorResolvesToScriptedBrowser(type)) {
-            return `clone subjects need a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}) or scripted-browser actor (one of: ${registeredScriptedBrowserActors().join(", ")}); the lab clones and serves the app for that participant to drive. Got "${type}".`;
+            return `clone subjects need a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}) or scripted-browser actor (one of: ${registeredScriptedBrowserActors().join(", ")}); humanish clones and serves the app for that participant to drive. Got "${type}".`;
         }
     }
     return null;

package/dist/study/config.d.ts

@@ -0,0 +1,15 @@
+import { type StudyParseResult } from "./types.js";
+/** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
+export declare const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study, which humanish no longer reads. Convert its file with humanish migrate <path>.";
+/**
+ * The package's study parser (src/index.ts) and the one discovery uses: a humanish.study.v3
+ * document. It refuses a humanish.lab.v2 one with HUMANISH_STUDY_V2_UNSUPPORTED.
+ */
+export declare function parseStudy(raw: unknown): StudyParseResult;
+/**
+ * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
+ * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
+ * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
+ * nothing. migrate's conversion (convert.ts) calls it directly, since it reads v2 files.
+ */
+export declare function parseStudyDocument(raw: unknown): StudyParseResult;

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

@@ -1,38 +1,41 @@
-// humanish.lab.v2: a lab is a composition over code primitives. There is no hardcoded lab kind.
+// The normalized config, in the humanish.lab.v2 spelling: a study composes code primitives, with no
+// hardcoded study kind.
+// A humanish.study.v3 file is rewritten into this spelling first (parse/study-v3.ts), and then must
+// take the route it declares and set no field that route does not read.
 //
 // Scope (read before trusting field names): the engine routes by
-// subject.source × execution.target (disambiguated by the actor lane where both axes
+// subject.source × execution.target (disambiguated by the actor's run kind where both axes
 // collide) and consumes a deliberately small set of fields:
 //   subject.source/repos/appUrl/serve/env/state/clone.{depth,fanout,keep}, actors[0].count,
 //   execution.target + execution.desktop.codexAppServer, scenario.mode,
 //   policies.redactRepos, defaults.open.
 // On the computer-use routes (app-url × e2b-desktop, and clone × e2b-desktop with a
-// computer-use actor), `actors[0].type` is load-bearing: it must resolve to a registered
+// computer-use actor), `actors[0].type` selects the actor: it must resolve to a registered
 // computer-use actor, and that descriptor runs the session. Those routes also consume
 // actors[0].{mission,persona,laneFocus.instruction,model,reasoningEffort}, execution.timeoutMs,
 // execution.desktop.{browser,resolution,sandboxTimeoutMs}, and (clone)
 // subject.{serve,env,state,clone.depth}.
 // On the scripted-browser route (app-url × local-or-absent, or clone × e2b-desktop, with a
-// registered scripted-browser actor), `actors[0].type` is equally load-bearing, and the route
+// registered scripted-browser actor), `actors[0].type` selects the actor too, and the route
 // consumes scenario.ref (required there, because the committed scenario's browser steps are what the
 // actor executes), actors[0].{persona,count}, and execution.timeoutMs. On the provisioned
 // clone slice it also consumes subject.{repos,serve,env,state,exposure,clone.depth} and
 // execution.desktop.template. actors[0].{mission,laneFocus,model} are inert on that route
 // because no model runs, and most execution.desktop.* fields remain forward-declared (device
-// presets belong to the cua route — scripted surfaces are the driver's own desktop/mobile
+// presets belong to the computer-use route; scripted surfaces are the driver's own desktop/mobile
 // viewports where isMobile/DSF genuinely render via playwright emulation).
 // On the other routes those fields remain forward-declared and are not yet consumed:
-// parseLabConfig emits a warning listing any such field that is set, so `lab inspect` shows
+// parseStudy emits a warning listing any such field that is set, so `study show` shows
 // the truth.
 //
-// NOTE on actors[0].count: it now carries ROUTE-SPECIFIC meanings — synthetic route: simCount;
+// NOTE on actors[0].count: it carries route-specific meanings. Preview route: simCount;
 // scripted-browser route: surface roster {1 = desktop, 2 = desktop + mobile}, default 1 (the
 // defaults-table single-participant row governs; count: 2 is the declared override); computer-use
 // E2B route: the homogeneous fan-out participant count (N identical participants, each its own E2B
-// desktop), capped at 16; the in-process/local-app cua route stays single-participant (no E2B to
-// fan out).
+// desktop), capped at 16; the in-process/local-app computer-use route stays single-participant (no
+// E2B to fan out).
 //
-// NOTE on actors[0].lanes / actors[0].roster (computer-use E2B route, this slice): a
+// NOTE on actors[0].lanes / actors[0].roster (computer-use E2B route): a
 // differentiated fan-out roster: each `{ id?, persona?, device?, instruction?, target? }` becomes one
 // independent E2B desktop (`per-lane-worlds`, the default topology). `roster[]` is parser sugar for
 // repeated groups and is normalized into `lanes[]` before the engine sees it. `lanes|roster` XOR
@@ -40,45 +43,94 @@
 // XOR `actors[0].laneFocus` (each entry's `instruction` is the roster's steer); `lanes[].device` XOR
 // raw `execution.desktop.resolution`. `execution.concurrency` bounds in-flight participants (default:
 // the participant count, all at once; env HUMANISH_CUA_MAX_CONCURRENCY may only lower it, per invariant
-// 3). On every non-cua route normalized `lanes` are inert (warned). subject.clone.fanout is
-// rejected on the cua route. `lanes[].target` is app-url × computer-use only: an absolute browser
-// URL this participant opens instead of `subject.appUrl`; it is the generic setup-produced-target
-// handoff, not a service topology primitive.
+// 3). On every non-computer-use route normalized `lanes` are inert (warned). subject.clone.fanout
+// is rejected on the computer-use route. `lanes[].target` is app-url × computer-use only: an
+// absolute browser URL this participant opens instead of `subject.appUrl`; it is the generic
+// setup-produced-target handoff, not a service topology primitive.
 //
 // There is deliberately no v1 compatibility: v1 had zero real users. Breaking schema changes
-// bump the version honestly.
-import { isLocalBrowserLab, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
+// bump the version.
+import { isLocalBrowserStudy, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
 import { isRecord } from "../run/type-guards.js";
 import { compositionReason } from "./composition-rules.js";
-import { findUnknownLabKey } from "./keys.js";
+import { findUnknownV2Key } from "./keys.js";
 import { parseActors, rosterOf } from "./parse/actors.js";
 import { parseComms, recipientParticipantId } from "./parse/comms.js";
 import { parseDefaults, parseExecution, parsePersonas, parsePolicies, parseReview, parseScenario, } from "./parse/execution.js";
+import { studySpelling, studyToV2 } from "./parse/study-v3.js";
 import { parseSubject } from "./parse/subject.js";
 import { invalid, optionalStr, str } from "./parse/values.js";
-import { isComputerUseComposition, isSharedWorldComposition } from "./routing.js";
+import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
-import { ID_PATTERN, LAB_CONFIG_SCHEMA, } from "./types.js";
+import { ID_PATTERN, V2_SCHEMA, STUDY_SCHEMA, } from "./types.js";
 import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "./validation.js";
-import { forwardDeclaredWarnings } from "./warnings.js";
+import { forwardDeclaredWarnings, inertFieldLabels } from "./warnings.js";
+import { plural } from "../run/text.js";
+/** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
+export const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study, which humanish no longer reads. Convert its file with humanish migrate <path>.";
 /**
- * Validate a parsed YAML object into a LabConfig. Pure: the caller owns file IO. Structural
- * validation only. Fields the engine does not yet consume are accepted but reported in
- * `warnings` so `lab inspect` never silently swallows a setting that does nothing.
+ * The package's study parser (src/index.ts) and the one discovery uses: a humanish.study.v3
+ * document. It refuses a humanish.lab.v2 one with HUMANISH_STUDY_V2_UNSUPPORTED.
  */
-export function parseLabConfig(raw) {
+export function parseStudy(raw) {
+    if (isRecord(raw) && raw.schema === V2_SCHEMA)
+        return {
+            ok: false,
+            error: { code: "HUMANISH_STUDY_V2_UNSUPPORTED", message: V2_UNSUPPORTED_MESSAGE },
+        };
+    return parseStudyDocument(raw);
+}
+/**
+ * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
+ * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
+ * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
+ * nothing. migrate's conversion (convert.ts) calls it directly, since it reads v2 files.
+ */
+export function parseStudyDocument(raw) {
     if (!isRecord(raw)) {
-        return invalid("Lab manifest must be a YAML object.");
+        return invalid("A study file must be a YAML object.");
     }
-    if (raw.schema !== LAB_CONFIG_SCHEMA) {
-        return invalid(`Lab schema must be ${LAB_CONFIG_SCHEMA}.`);
+    if (raw.schema === STUDY_SCHEMA)
+        return parseV3(raw);
+    if (raw.schema !== V2_SCHEMA) {
+        return invalid(`The study schema must be ${STUDY_SCHEMA} or ${V2_SCHEMA}.`);
     }
-    const unknownKey = findUnknownLabKey(raw);
+    return parseV2(raw);
+}
+/**
+ * A v3 study parses through the v2 parser, then must take the route it declares and set no field
+ * that route does not read. A v2 file gets those fields as a warning instead.
+ */
+function parseV3(raw) {
+    const document = studyToV2(raw);
+    if (!document.ok)
+        return document;
+    const { route, v2, participantSource } = document.value;
+    const spell = (message) => studySpelling(message, route, participantSource);
+    const parsed = parseV2(v2);
+    if (!parsed.ok)
+        return invalid(spell(parsed.error.message));
+    const taken = routeOf(parsed.config);
+    if (taken !== route) {
+        return invalid(`This study declares route: ${route}, but its subject (source: ${parsed.config.subject.source}) and actor (type: ${parsed.config.actors[0]?.type}) take the ${taken} route. Change \`route\`, or change the subject or actor.`);
+    }
+    const inert = inertFieldLabels(parsed.config);
+    if (inert.length > 0) {
+        return invalid(spell(`route: ${route} does not read ${inert.join(", ")}. Remove ${inert.length === 1 ? "it" : "them"}.`));
+    }
+    return {
+        ok: true,
+        config: { ...parsed.config, schema: STUDY_SCHEMA },
+        warnings: parsed.warnings.map(spell),
+    };
+}
+function parseV2(raw) {
+    const unknownKey = findUnknownV2Key(raw);
     if (unknownKey)
         return invalid(unknownKey);
     const id = str(raw.id);
     if (!id || !ID_PATTERN.test(id)) {
-        return invalid("Lab id must be a public-safe token starting with a letter or digit (/^[A-Za-z0-9][A-Za-z0-9_.-]*$/).");
+        return invalid("The study id must be a public-safe token starting with a letter or digit (/^[A-Za-z0-9][A-Za-z0-9_.-]*$/).");
     }
     const subjectResult = parseSubject(raw.subject);
     if (!subjectResult.ok) {
@@ -93,7 +145,7 @@ export function parseLabConfig(raw) {
         return executionResult;
     }
     const config = {
-        schema: LAB_CONFIG_SCHEMA,
+        schema: V2_SCHEMA,
         id,
         ...optionalStr("title", raw.title),
         ...optionalStr("description", raw.description),
@@ -139,7 +191,7 @@ export function parseLabConfig(raw) {
     if (commsResult.value)
         config.comms = commsResult.value;
     if (config.comms?.email?.smtp && config.subject.topology === "shared-world") {
-        return invalid("SMTP capture is not yet wired for shared-world labs. Use the default per-lane-worlds topology for SMTP, or configure supported HTTP email capture for concurrent shared-world labs.");
+        return invalid("SMTP capture is not supported yet for shared-world studies. Use the default per-lane-worlds topology for SMTP, or configure supported HTTP email capture for concurrent shared-world studies.");
     }
     const mediaReason = desktopMediaValidationReason(config);
     if (mediaReason)
@@ -150,11 +202,12 @@ export function parseLabConfig(raw) {
     const scenarioCapsReason = scenarioCapsValidationReason(config);
     if (scenarioCapsReason)
         return invalid(scenarioCapsReason);
-    // All-parallel default (#350): a multi-seat lab that does not declare execution.concurrency runs
-    // every seat at once; the declared field is a cap the author chose, never a mode. Independent
-    // computer-use participants resolve that default from the final participant count when they plan, after any
-    // --count override, so the parser leaves it unset for them. A shared world's roster is fixed, so
-    // its default is filled here for the envelopes and warnings that read the parsed config.
+    // All-parallel default: a multi-participant study that does not declare execution.concurrency
+    // runs every participant at once; the declared field is a cap the author chose, never a mode.
+    // Independent computer-use participants resolve that default from the final participant count
+    // when they plan, after any --count override, so the parser leaves it unset for them. A shared
+    // world's roster is fixed, so its default is filled here for the envelopes and warnings that read
+    // the parsed config.
     {
         const participantCount = rosterOf(config.actors[0])?.length ?? config.actors[0]?.count ?? 1;
         if (participantCount > 1 &&
@@ -163,8 +216,8 @@ export function parseLabConfig(raw) {
             config.execution = { ...config.execution, concurrency: participantCount };
         }
     }
-    // Email that just works (#351): the funnel's only handoff to an actor is the per-participant
-    // inbox instruction, gated on recipients[]. Guessed participant ids broke a field run —
+    // Email that just works: the funnel's only handoff to an actor is the per-participant
+    // inbox instruction, gated on recipients[]. Guessed participant ids broke a field run:
     // recipients copied from a single-participant example matched nothing, so every actor was left inbox-blind with zero
     // signal. Omitted recipients are therefore filled (one deterministic address per participant);
     // a recipient naming an unknown participant is a hard error listing the real ids; declared
@@ -184,7 +237,7 @@ export function parseLabConfig(raw) {
         else {
             const unknown = email.recipients.filter((recipient) => !participantIds.includes(recipientParticipantId(recipient)));
             if (unknown.length > 0) {
-                return invalid(`comms.email.recipients name participant(s) that do not exist: ${unknown.map((r) => `"${recipientParticipantId(r)}"`).join(", ")}. This lab's participant ids are: ${participantIds.join(", ")}. A recipient's \`lane\` must match one of them exactly: the inbox instruction is injected per participant, and a mismatch disables the email funnel for that participant.`);
+                return invalid(`comms.email.recipients name ${plural(unknown.length, "participant")} that ${unknown.length === 1 ? "does" : "do"} not exist: ${unknown.map((r) => `"${recipientParticipantId(r)}"`).join(", ")}. This study's participant ids are: ${participantIds.join(", ")}. A recipient's \`lane\` must match one of them exactly: the inbox instruction is injected per participant, and a mismatch disables the email funnel for that participant.`);
             }
             if (!email.recipients.some((recipient) => recipient.address !== undefined)) {
                 return invalid("comms.email.recipients cover no participant with an address, so no actor would be told an inbox exists and no captured mail could match. Give at least one recipient an address, or omit `recipients` entirely (every participant then gets a deterministic address automatically).");
@@ -201,10 +254,14 @@ export function parseLabConfig(raw) {
     if (analysisReason)
         return invalid(analysisReason);
     const normalized = localBrowserDefaults(config);
-    if (isLocalBrowserLab(normalized)) {
+    if (isLocalBrowserStudy(normalized)) {
         const reason = localBrowserUnsupportedReason(normalized);
         if (reason)
             return invalid(reason);
     }
-    return { ok: true, config: normalized, warnings: forwardDeclaredWarnings(normalized) };
+    return {
+        ok: true,
+        config: normalized,
+        warnings: forwardDeclaredWarnings(normalized),
+    };
 }

package/dist/study/convert.d.ts

@@ -0,0 +1,33 @@
+import { type StudyRoute } from "./routing.js";
+/** A key the conversion moved, by its v2 path and its v3 path. */
+export interface MovedKey {
+    readonly from: string;
+    readonly to: string;
+}
+/** A key the conversion dropped because the study's route never reads it. */
+export interface DroppedKey {
+    readonly path: string;
+    readonly value: unknown;
+    /** The comments that sat on the dropped key, which the v3 file no longer has. */
+    readonly comments?: string;
+}
+/** A v2 file converted to v3. */
+interface StudyConversion {
+    readonly text: string;
+    readonly route: StudyRoute;
+    readonly moved: readonly MovedKey[];
+    readonly dropped: readonly DroppedKey[];
+}
+/** The conversion, or why the file cannot be converted as it stands. */
+export type StudyConversionResult = {
+    readonly ok: true;
+    readonly conversion: StudyConversion;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Whether a parsed YAML value is a v3 study file. */
+export declare function isStudyV3(raw: unknown): boolean;
+/** Convert one v2 file's text. `cwd` is the project the plan check plans in. */
+export declare function convertStudyText(text: string, cwd: string): StudyConversionResult;
+export {};