humanish 0.107.0 → 0.109.0

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

@@ -1,6 +1,8 @@
 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
 // (a leading "." or "/" is read as a file path; a leading "-" collides with CLI flags).
 export const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;

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

@@ -1,67 +1,67 @@
-import type { LabConfig } from "./types.js";
+import type { StudyConfig } from "./types.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
- * message, or null when valid. Enforced at parse and re-enforced in the engine (runCuaActorLab
- * is itself exported npm surface). Structural roster shape (id/device validity, id uniqueness) is
- * already checked in parseLanes; this is the route-scoped XOR/cap/policy layer.
+ * message, or null when valid. The parser enforces it, and runStudyWith checks it again for a config
+ * that skipped the parser. It runs rosterStructuralValidationReason (id and device
+ * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
  */
-export declare function cuaLaneValidationReason(config: LabConfig): string | null;
+export declare function computerUseValidationReason(config: StudyConfig): string | null;
 /**
- * Cross-validate a `topology: shared-world` declaration (#164). Returns the failure message, or
+ * Cross-validate a `topology: shared-world` declaration. Returns the failure message, or
  * null when the one shared-world route can run it: the external-public checks for an app-url
  * subject, the provisioned checks otherwise. Enforced at parse and again by the route, since
- * runConcurrentSharedWorld is exported.
+ * runStudyWith takes a config that skipped the parser.
  */
-export declare function sharedWorldValidationReason(config: LabConfig): string | null;
+export declare function sharedWorldValidationReason(config: StudyConfig): string | null;
 /**
  * Declared capture devices must be implemented by the selected execution route.
  * Unsupported backends pass false when called directly, where the declared
  * topology may not identify the backend that is actually executing.
  */
-export declare function desktopMediaValidationReason(config: LabConfig, supportsMedia?: boolean): string | undefined;
+export declare function desktopMediaValidationReason(config: StudyConfig, supportsMedia?: boolean): string | undefined;
 /** Reused by direct library runners so unsupported receiving never becomes inert configuration. */
-export declare function receivingEmailValidationReason(config: LabConfig): string | undefined;
-/** Refuse task declarations that the selected execution path would discard (#737).
+export declare function receivingEmailValidationReason(config: StudyConfig): string | undefined;
+/** Refuse task declarations that the selected execution path would discard.
  * Direct runners pass their actual support rather than trusting the config's dispatch shape. */
-export declare function taskProtocolValidationReason(config: LabConfig, supportsTasks?: boolean): string | null;
+export declare function taskProtocolValidationReason(config: StudyConfig, supportsTasks?: boolean): string | null;
 /**
  * Refuse a clone subject whose target is not an explicit e2b-desktop. Every clone route clones and
- * serves the repo inside a hosted desktop sandbox, and routeOf sends every clone lab to
+ * serves the repo inside a hosted desktop sandbox, and routeOf sends every clone study to
  * one, so any other target, or none, would still run on an E2B desktop. Requiring it explicitly
  * also means the parser's clone checks, which run only on e2b-desktop, cannot be skipped. Enforced
  * at parse and again on the computer-use and scripted-browser routes for library callers.
  */
-export declare function cloneTargetValidationReason(config: LabConfig): string | null;
+export declare function cloneTargetValidationReason(config: StudyConfig): string | null;
 /**
- * Refuse a positive `scenario.caps.maxUsd` or `maxTotalUsd` on a computer-use lab.
+ * Refuse a positive `scenario.caps.maxUsd` or `maxTotalUsd` on a computer-use study.
  * `scenario.caps` belongs to the terminal route; the computer-use route stops on `execution.caps`,
- * so a dollar figure here would read as a cap while the lab ran uncapped. Zero spends nothing
+ * so a dollar figure here would read as a cap while the study ran uncapped. Zero spends nothing
  * either way and stays a warning. Enforced at parse and again on the computer-use routes for
  * library callers.
  */
-export declare function scenarioCapsValidationReason(config: LabConfig): string | null;
+export declare function scenarioCapsValidationReason(config: StudyConfig): string | null;
 /** Refuse a claimed output bound when the route cannot pass it to the first-party provider. */
-export declare function outputTokenLimitValidationReason(config: LabConfig): string | null;
+export declare function outputTokenLimitValidationReason(config: StudyConfig): string | null;
 /**
- * Cross-validate a concurrent shared-world declaration (#164 phase 2). Returns the failure message,
+ * Cross-validate a concurrent shared-world declaration. Returns the failure message,
  * or null when valid. Includes the base shared-world checks plus the concurrent extras: a synthetic
  * subject attestation, a 0.0.0.0 serve bind (getHost only routes to a port bound on
  * all interfaces), and no `subject.clone.keep`/`subject.localTree.keep` (either would
- * orphan actor sandboxes). Enforced at parse and re-enforced in the engine (runConcurrentSharedWorld
- * is exported npm surface).
+ * orphan actor sandboxes). Enforced at parse and re-enforced in the engine (runStudyWith
+ * takes a config that skipped the parser).
  */
-export declare function concurrentSharedWorldValidationReason(config: LabConfig): string | null;
+export declare function concurrentSharedWorldValidationReason(config: StudyConfig): string | null;
 /**
- * Cross-validate the external-public shared-world declaration (#164 phase 2): a real public
+ * Cross-validate the external-public shared-world declaration: a real public
  * deployment used directly as the shared plane (no getHost, no clone, no subject sandbox, no seed).
  * The counterpart of concurrentSharedWorldValidationReason for a plane the harness does not own:
  * it rejects every provisioned-subject field (serve/state.seed/state.checkpoint/exposure/clone/repos
- * are inert with no sandbox, so they fail closed per invariant 6), and requires a
+ * are inert with no sandbox, so they fail closed), and requires a
  * non-loopback appUrl + allowPublicTargets + the operator-ownership attestation subject.publicTarget +
  * concurrency >= 2 + an actors[0].lanes roster of ≥2 with exactly one host participant. The getHost synthetic
  * gate is deliberately unreachable here (there is no internet-reachable harness-owned URL to attest).
- * Enforced at parse and re-enforced in the engine (runConcurrentSharedWorld is exported npm surface).
+ * Enforced at parse and re-enforced in the engine (runStudyWith takes a config that skipped the parser).
  */
-export declare function externalPublicSharedWorldValidationReason(config: LabConfig): string | null;
+export declare function externalPublicSharedWorldValidationReason(config: StudyConfig): string | null;
 /** Analysis requires a live recording producer, including supported dry-run previews. */
-export declare function automaticAnalysisRouteReason(config: LabConfig): string | undefined;
+export declare function automaticAnalysisRouteReason(config: StudyConfig): string | undefined;

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

@@ -2,28 +2,29 @@ import { isMaxOutputTokens } from "../actors/output-token-limit.js";
 import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN, focusOf, rosterOf, } from "./parse/actors.js";
 import { isHttpUrl, isLoopbackUrl } from "./parse/subject.js";
 import { declaredTargets } from "./plan-participants.js";
-import { actorResolvesToComputerUse, cuaLaneCount, MAX_CUA_LANES, registeredComputerUseActors, resolveSeatUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
+import { actorResolvesToComputerUse, computerUseParticipantCount, MAX_COMPUTER_USE_PARTICIPANTS, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
- * message, or null when valid. Enforced at parse and re-enforced in the engine (runCuaActorLab
- * is itself exported npm surface). Structural roster shape (id/device validity, id uniqueness) is
- * already checked in parseLanes; this is the route-scoped XOR/cap/policy layer.
+ * message, or null when valid. The parser enforces it, and runStudyWith checks it again for a config
+ * that skipped the parser. It runs rosterStructuralValidationReason (id and device
+ * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
  */
-export function cuaLaneValidationReason(config) {
+export function computerUseValidationReason(config) {
     const actor = config.actors[0];
     const roster = rosterOf(actor);
     const structuralReason = rosterStructuralValidationReason(config);
     if (structuralReason) {
         return structuralReason;
     }
-    // clone.fanout is a declared behavior change: rejected on the cua route (was inert-warned).
-    // Fan-out is declared via `actors[0].count` or `actors[0].lanes`; subject.clone.fanout never applied here.
+    // clone.fanout is a declared behavior change: rejected on the computer-use route (was
+    // inert-warned). Fan-out is declared via `actors[0].count` or `actors[0].lanes`;
+    // subject.clone.fanout never applied here.
     if (config.subject.clone?.fanout !== undefined) {
         return "`subject.clone.fanout` is not used on the computer-use route: declare fan-out with actors[0].count (homogeneous) or actors[0].lanes (a roster of participants). (No current route reads clone.fanout.)";
     }
     if (roster !== undefined) {
         if (actor?.count !== undefined) {
-            return "Declare EITHER actors[0].count (a homogeneous participant count) OR actors[0].lanes (a differentiated roster), not both.";
+            return "Set either `actors[0].count` (identical participants) or `actors[0].lanes` (a roster of distinct participants), not both.";
         }
         if (focusOf(actor) !== undefined) {
             return "actors[0].laneFocus and actors[0].lanes are mutually exclusive: each roster entry's `instruction` is the fan-out steer; laneFocus is the steer for a single participant.";
@@ -35,7 +36,7 @@ export function cuaLaneValidationReason(config) {
         const targeted = roster.filter((entry) => entry.target !== undefined);
         if (targeted.length > 0) {
             if (config.subject.source !== "app-url") {
-                return "actors[0].lanes[].target is supported only on app-url computer-use labs — clone/shared-world/local-app routes provision or own their entry URL by mechanism.";
+                return "`actors[0].lanes[].target` works only on app-url computer-use studies. Clone, shared-world and local-app studies set each participant's entry URL themselves; remove `target`.";
             }
             if (roster.some((entry) => entry.entry !== undefined)) {
                 return "actors[0].lanes[].target and actors[0].lanes[].entry are mutually exclusive: target is an app-url fan-out browser URL; entry is a shared-world same-origin participant path.";
@@ -45,27 +46,27 @@ export function cuaLaneValidationReason(config) {
             }
         }
     }
-    const participantCount = cuaLaneCount(config);
-    if (participantCount > MAX_CUA_LANES) {
-        return `Computer-use fan-out is capped at ${MAX_CUA_LANES} participants (declared ${participantCount}); N concurrent paid desktops is real spend, and there is no override above the cap this slice.`;
+    const participantCount = computerUseParticipantCount(config);
+    if (participantCount > MAX_COMPUTER_USE_PARTICIPANTS) {
+        return `A computer-use study runs at most ${MAX_COMPUTER_USE_PARTICIPANTS} participants, and this one declares ${participantCount}. Each participant is a paid desktop and they all run at once, so no setting raises the cap; split the roster across studies.`;
     }
     // Public targets fan out into N independent worlds driving the same public app, which is an
     // ambiguous shared-world-ish shape, not a per-participant target swarm. Permit N>1 public runs only
     // when every roster entry declares its own target, making the adapter-owned topology explicit. But when
     // `subject.topology: shared-world` is also declared, N participants against one public target is the
-    // external-public shared-world topology (#164 phase 2), so route it there (a real public deployment
+    // external-public shared-world topology, so route it there (a real public deployment
     // as the shared plane) instead of refusing; externalPublicSharedWorldValidationReason then applies.
     if (participantCount > 1 &&
         config.policies?.allowPublicTargets === true &&
         declaredTargets(config).length === 0 &&
         config.subject.topology !== "shared-world") {
-        return "policies.allowPublicTargets cannot be combined with fan-out to more than one participant (N>1): N participants against one declared public target is the SHARED-WORLD topology (layer 7, #164), not `per-lane-worlds`. Declare `subject.topology: shared-world` to run the external-public shared-world route, fan out against a loopback/provisioned subject, or run a single public-target participant.";
+        return "`policies.allowPublicTargets` with more than one participant sends them all to one public app, which is a shared world. Set `subject.topology: shared-world` to run them together there, give each `actors[0].lanes[]` entry its own `target`, or run one participant.";
     }
     return null;
 }
 /**
  * Engine-level path-token validation for configs supplied directly through the
- * public TypeScript/JavaScript API instead of parseLabConfig.
+ * public TypeScript/JavaScript API instead of parseStudy.
  */
 function rosterStructuralValidationReason(config) {
     const roster = rosterOf(config.actors[0]);
@@ -96,10 +97,10 @@ function rosterStructuralValidationReason(config) {
     return null;
 }
 /**
- * Cross-validate a `topology: shared-world` declaration (#164). Returns the failure message, or
+ * Cross-validate a `topology: shared-world` declaration. Returns the failure message, or
  * null when the one shared-world route can run it: the external-public checks for an app-url
  * subject, the provisioned checks otherwise. Enforced at parse and again by the route, since
- * runConcurrentSharedWorld is exported.
+ * runStudyWith takes a config that skipped the parser.
  */
 export function sharedWorldValidationReason(config) {
     return config.subject.source === "app-url"
@@ -119,7 +120,7 @@ function provisionedSharedWorldStructureReason(config) {
         return structuralReason;
     }
     if (config.subject.source !== "clone" && config.subject.source !== "local-tree") {
-        return "`subject.topology: shared-world` requires `subject.source: clone` or `subject.source: local-tree` - the shared world is ONE provisioned, served, seeded plane (#164).";
+        return "`subject.topology: shared-world` needs `subject.source: clone` or `local-tree`, which humanish serves as one seeded app every participant uses, or `app-url` for a public deployment you own.";
     }
     if (config.execution?.target !== "e2b-desktop") {
         return "`subject.topology: shared-world` requires `execution.target: e2b-desktop`: the role participants drive hosted desktop browsers against one in-sandbox app.";
@@ -129,17 +130,17 @@ function provisionedSharedWorldStructureReason(config) {
     }
     const serve = config.subject.serve;
     if (!serve) {
-        return "`subject.topology: shared-world` requires `subject.serve` (start + url) — the lab serves ONE shared app in-sandbox that every role drives.";
+        return "`subject.topology: shared-world` needs `subject.serve` (start and url): humanish starts one copy of the app in the sandbox, and every participant uses it.";
     }
     const roster = rosterOf(config.actors[0]);
     if (!roster || roster.length < 2) {
-        return "`subject.topology: shared-world` requires an `actors[0].lanes` roster of at least 2 roles (the roster IS the role roster: declare ≥2 participants; a single-role shared world proves no interaction).";
+        return "`subject.topology: shared-world` needs an `actors[0].lanes` roster of at least 2 participants: with one participant there is nobody to interact with.";
     }
     if (!config.subject.state?.checkpoint || config.subject.state.checkpoint.length === 0) {
-        return "`subject.topology: shared-world` requires `subject.state.checkpoint` (≥1 read-only digest probe) — the checkpoint series is how the run shows the shared state changing; without it the run cannot show that participants changed the shared app.";
+        return "`subject.topology: shared-world` needs at least one read-only `subject.state.checkpoint` probe: the checkpoints are how the run shows that participants changed the shared app.";
     }
     for (const entry of roster) {
-        if (entry.entry !== undefined && resolveSeatUrl(serve.url, entry.entry) === null) {
+        if (entry.entry !== undefined && resolveEntryUrl(serve.url, entry.entry) === null) {
             return `actors[0].lanes role "${entry.id ?? "(unnamed)"}".entry must resolve same-origin (loopback) with subject.serve.url (${serve.url}); got "${entry.entry}".`;
         }
     }
@@ -191,14 +192,14 @@ export function receivingEmailValidationReason(config) {
         return undefined;
     if (!isComputerUseComposition(config) ||
         !["app-url", "clone", "local-tree"].includes(config.subject.source)) {
-        return "Real email receiving requires a hosted computer-use browser lab with an app-url, clone, or local-tree subject. Scripted, terminal, desktop-cli and local-app routes are unsupported.";
+        return "Real email receiving requires a hosted computer-use browser study with an app-url, clone, or local-tree subject. Scripted, terminal, desktop-cli and local-app routes are unsupported.";
     }
     if (config.actors.some((actor) => actor.type === "local-agent")) {
         return "Real email receiving is unavailable for local-agent: its host process does not isolate the inbox management credential. Use a hosted first-party computer-use actor.";
     }
     return undefined;
 }
-/** Refuse task declarations that the selected execution path would discard (#737).
+/** Refuse task declarations that the selected execution path would discard.
  * Direct runners pass their actual support rather than trusting the config's dispatch shape. */
 export function taskProtocolValidationReason(config, supportsTasks = isComputerUseComposition(config) && !isSharedWorldComposition(config)) {
     for (const [index, actor] of config.actors.entries()) {
@@ -215,7 +216,7 @@ export function taskProtocolValidationReason(config, supportsTasks = isComputerU
 }
 /**
  * Refuse a clone subject whose target is not an explicit e2b-desktop. Every clone route clones and
- * serves the repo inside a hosted desktop sandbox, and routeOf sends every clone lab to
+ * serves the repo inside a hosted desktop sandbox, and routeOf sends every clone study to
  * one, so any other target, or none, would still run on an E2B desktop. Requiring it explicitly
  * also means the parser's clone checks, which run only on e2b-desktop, cannot be skipped. Enforced
  * at parse and again on the computer-use and scripted-browser routes for library callers.
@@ -225,12 +226,12 @@ export function cloneTargetValidationReason(config) {
     if (config.subject.source !== "clone" || target === "e2b-desktop")
         return null;
     const got = target === undefined ? "it is absent" : `got "${target}"`;
-    return `clone subjects require \`execution.target: e2b-desktop\` (${got}): the lab clones and serves the repo inside a hosted desktop sandbox. \`execution.target: local\` applies to app-url and local-app subjects.`;
+    return `clone subjects require \`execution.target: e2b-desktop\` (${got}): humanish clones and serves the repo inside a hosted desktop sandbox. \`execution.target: local\` applies to app-url and local-app subjects.`;
 }
 /**
- * Refuse a positive `scenario.caps.maxUsd` or `maxTotalUsd` on a computer-use lab.
+ * Refuse a positive `scenario.caps.maxUsd` or `maxTotalUsd` on a computer-use study.
  * `scenario.caps` belongs to the terminal route; the computer-use route stops on `execution.caps`,
- * so a dollar figure here would read as a cap while the lab ran uncapped. Zero spends nothing
+ * so a dollar figure here would read as a cap while the study ran uncapped. Zero spends nothing
  * either way and stays a warning. Enforced at parse and again on the computer-use routes for
  * library callers.
  */
@@ -241,7 +242,7 @@ export function scenarioCapsValidationReason(config) {
         const value = config.scenario?.caps?.[key];
         if (value === undefined || value <= 0)
             continue;
-        return `scenario.caps.${key} (${value}) does not cap a computer-use lab: this route stops on execution.caps.${key}. Move the value to execution.caps.${key}; scenario.caps applies only to terminal-product labs.`;
+        return `scenario.caps.${key} (${value}) does not cap a computer-use study: this route stops on execution.caps.${key}. Move the value to execution.caps.${key}; scenario.caps applies only to terminal-product studies.`;
     }
     return null;
 }
@@ -263,7 +264,8 @@ export function outputTokenLimitValidationReason(config) {
  * Shared-world participants share one live app, so at least two must be live at once. The
  * sequential shared-world route (`execution.concurrency: 1`) was removed in 0.106.0; the parser
  * fills an omitted concurrency with the participant count. Both callers check it after their
- * two-participant roster floor, so a one-seat roster gets the roster refusal, never this one.
+ * two-participant roster floor, so a one-participant roster gets the roster refusal, never this
+ * one.
  */
 function sharedWorldConcurrencyReason(config) {
     // Direct library callers skip the parser, so an omitted value defaults here exactly as the
@@ -272,15 +274,15 @@ function sharedWorldConcurrencyReason(config) {
     const concurrency = config.execution?.concurrency ?? participants;
     if (concurrency >= 2)
         return null;
-    return `shared-world labs need \`execution.concurrency\` of at least 2 (got ${concurrency}). Sequential shared-world turns (concurrency 1) were removed in 0.106.0: omit execution.concurrency to run every participant at once, or set it to 2 or more. A provisioned subject also needs \`subject.exposure: synthetic\` and a \`serve.start\` that binds 0.0.0.0.`;
+    return `shared-world studies need \`execution.concurrency\` of at least 2 (got ${concurrency}). Sequential shared-world turns (concurrency 1) were removed in 0.106.0: omit execution.concurrency to run every participant at once, or set it to 2 or more. A provisioned subject also needs \`subject.exposure: synthetic\` and a \`serve.start\` that binds 0.0.0.0.`;
 }
 /**
- * Cross-validate a concurrent shared-world declaration (#164 phase 2). Returns the failure message,
+ * Cross-validate a concurrent shared-world declaration. Returns the failure message,
  * or null when valid. Includes the base shared-world checks plus the concurrent extras: a synthetic
  * subject attestation, a 0.0.0.0 serve bind (getHost only routes to a port bound on
  * all interfaces), and no `subject.clone.keep`/`subject.localTree.keep` (either would
- * orphan actor sandboxes). Enforced at parse and re-enforced in the engine (runConcurrentSharedWorld
- * is exported npm surface).
+ * orphan actor sandboxes). Enforced at parse and re-enforced in the engine (runStudyWith
+ * takes a config that skipped the parser).
  */
 export function concurrentSharedWorldValidationReason(config) {
     const base = provisionedSharedWorldStructureReason(config);
@@ -291,11 +293,11 @@ export function concurrentSharedWorldValidationReason(config) {
     if (sharedWorldConcurrency)
         return sharedWorldConcurrency;
     if (config.subject.exposure !== "synthetic") {
-        return "the concurrent shared-world route requires `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 (no real/external data behind a getHost URL).";
+        return "A shared-world 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 and seeded.";
     }
     const serve = config.subject.serve;
     if (!serve || !serve.start.includes("0.0.0.0")) {
-        return "the concurrent shared-world route requires `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; a loopback-only bind 502s. (The readiness probe stays loopback.)";
+        return "A shared-world 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, and a loopback-only server answers 502. The readiness probe still uses loopback.";
     }
     if (config.subject.clone?.keep === true || config.subject.localTree?.keep === true) {
         const keepField = config.subject.clone?.keep === true ? "subject.clone.keep" : "subject.localTree.keep";
@@ -304,15 +306,15 @@ export function concurrentSharedWorldValidationReason(config) {
     return null;
 }
 /**
- * Cross-validate the external-public shared-world declaration (#164 phase 2): a real public
+ * Cross-validate the external-public shared-world declaration: a real public
  * deployment used directly as the shared plane (no getHost, no clone, no subject sandbox, no seed).
  * The counterpart of concurrentSharedWorldValidationReason for a plane the harness does not own:
  * it rejects every provisioned-subject field (serve/state.seed/state.checkpoint/exposure/clone/repos
- * are inert with no sandbox, so they fail closed per invariant 6), and requires a
+ * are inert with no sandbox, so they fail closed), and requires a
  * non-loopback appUrl + allowPublicTargets + the operator-ownership attestation subject.publicTarget +
  * concurrency >= 2 + an actors[0].lanes roster of ≥2 with exactly one host participant. The getHost synthetic
  * gate is deliberately unreachable here (there is no internet-reachable harness-owned URL to attest).
- * Enforced at parse and re-enforced in the engine (runConcurrentSharedWorld is exported npm surface).
+ * Enforced at parse and re-enforced in the engine (runStudyWith takes a config that skipped the parser).
  */
 export function externalPublicSharedWorldValidationReason(config) {
     const structuralReason = rosterStructuralValidationReason(config);
@@ -320,7 +322,7 @@ export function externalPublicSharedWorldValidationReason(config) {
         return structuralReason;
     }
     if (config.subject.source !== "app-url") {
-        return "the external-public shared-world route requires `subject.source: app-url` — a real public deployment is used directly as the shared plane (no clone, no provisioned subject).";
+        return "An external-public shared-world study needs `subject.source: app-url`: the participants share a public deployment you already run, so there is nothing to clone or serve.";
     }
     if (config.execution?.target !== "e2b-desktop") {
         return "the external-public shared-world route requires `execution.target: e2b-desktop`: the role participants drive hosted desktop browsers against the one public deployment.";
@@ -336,40 +338,40 @@ export function externalPublicSharedWorldValidationReason(config) {
     if (sharedWorldConcurrency)
         return sharedWorldConcurrency;
     if (config.policies?.allowPublicTargets !== true) {
-        return "the external-public shared-world route requires `policies.allowPublicTargets: true` — the shared plane is a real non-loopback public deployment.";
+        return "An external-public shared-world study needs `policies.allowPublicTargets: true`, because the participants drive a public deployment.";
     }
     const appUrl = config.subject.appUrl ?? "";
     if (!isHttpUrl(appUrl) || isLoopbackUrl(appUrl)) {
-        return "the external-public shared-world route requires a non-loopback http(s) `subject.appUrl` — a loopback URL is not a shared public plane (use the getHost provisioned route for a local subject).";
+        return "An external-public shared-world study needs a public http(s) `subject.appUrl`, not a loopback URL. For an app you run locally, use a clone or local-tree subject, which humanish serves itself.";
     }
-    // The operator-ownership attestation (the honest analog of exposure: synthetic — you cannot claim
+    // The operator-ownership attestation (the counterpart of exposure: synthetic; you cannot claim
     // synthetic on a real site, but you must attest you own/operate it). Author-trust; unverifiable.
     if (config.subject.publicTarget?.authorized !== true) {
-        return "the external-public shared-world route requires `subject.publicTarget: { owner, authorized: true }` — you must attest you own/operate the public deployment used as the shared plane (author-trust; the harness cannot verify ownership).";
+        return "An external-public shared-world study needs `subject.publicTarget: { owner, authorized: true }` to declare that you own or operate the public deployment. humanish cannot check ownership, so the study states it.";
     }
     // No provisioned-subject field is allowed: with no sandbox they cannot act, so they are rejected
-    // with a precise reason, never silently ignored (invariant 6). exposure: synthetic in particular
+    // with a precise reason, never silently ignored. exposure: synthetic in particular
     // would be a false claim on a real site (the harness neither provisioned nor exposed it).
     if (config.subject.exposure !== undefined) {
-        return "`subject.exposure: synthetic` is forbidden on the external-public shared-world route — you cannot attest a real public deployment is synthetic seeded data; use `subject.publicTarget` to attest ownership instead.";
+        return "`subject.exposure: synthetic` does not apply to an external-public shared-world study: a real public deployment is not seeded synthetic data. Declare ownership with `subject.publicTarget` instead.";
     }
     if (config.subject.serve !== undefined) {
-        return "`subject.serve` is forbidden on the external-public shared-world route — the harness does not serve the plane (it is an already-deployed public app); there is no in-sandbox serve to run.";
+        return "`subject.serve` does not apply to an external-public shared-world study: the app is already deployed, so humanish serves nothing. Remove `subject.serve`.";
     }
     if (config.subject.state?.seed !== undefined ||
         config.subject.state?.checkpoint !== undefined ||
         config.subject.state !== undefined) {
-        return "`subject.state` (seed/checkpoint/external) is forbidden on the external-public shared-world route — the harness neither seeds nor snapshots the plane (no in-sandbox filesystem to digest); no authoritative shared-state proof is possible on this class.";
+        return "`subject.state` (seed, checkpoint or external) does not apply to an external-public shared-world study: humanish cannot seed or read a deployment it does not run. Remove `subject.state`.";
     }
     if (config.subject.clone !== undefined || config.subject.repos !== undefined) {
-        return "`subject.clone`/`subject.repos` are forbidden on the external-public shared-world route — nothing is cloned; the public deployment IS the plane.";
+        return "`subject.clone` and `subject.repos` do not apply to an external-public shared-world study: the participants use the public deployment, so nothing is cloned. Remove them.";
     }
     if (roster.some((entry) => entry.entry !== undefined)) {
         return "`actors[0].lanes[].entry` (the loopback same-origin participant path) is forbidden on the external-public shared-world route: there is no harness-served serve.url to resolve it against; participants open the public appUrl and reach the shared session through the real UI.";
     }
     const hostEntries = roster.filter((entry) => entry.host === true);
     if (hostEntries.length !== 1) {
-        return `the external-public shared-world route requires EXACTLY ONE \`host: true\` participant (the designated host that creates the shared session; got ${hostEntries.length}). The other ≥1 participants are followers that join it.`;
+        return `An external-public shared-world study needs exactly one \`host: true\` participant, the one who creates the shared session, and this study has ${hostEntries.length}. Every other participant joins that session.`;
     }
     return null;
 }
@@ -383,5 +385,5 @@ export function automaticAnalysisRouteReason(config) {
         isSharedWorldComposition(config) ||
         ["app-url", "local-app", "local-tree", "desktop-cli", "terminal-product"].includes(config.subject.source))
         return undefined;
-    return "review.analysis requires a computer-use, scripted-browser, terminal-product or shared-world lab; this lab's route does not produce an eligible live recording.";
+    return "review.analysis requires a computer-use, scripted-browser, terminal-product or shared-world study; this study's route does not produce an eligible live recording.";
 }

package/dist/study/warnings.d.ts

@@ -0,0 +1,12 @@
+import type { StudyConfig } from "./types.js";
+/**
+ * The fields a config sets that its route does not read, each as `field` or `field (reason)`. A v2
+ * file gets them as one warning; a v3 study is refused for any of them.
+ */
+export declare function inertFieldLabels(config: StudyConfig): string[];
+/**
+ * The same fields as `inertFieldLabels`, as paths without their reasons, such as
+ * `actors[0].lanes[].entry` or `execution.timeoutMs`. `humanish migrate` drops each one.
+ */
+export declare function inertFieldPaths(config: StudyConfig): string[];
+export declare function forwardDeclaredWarnings(config: StudyConfig): string[];