humanish 0.106.1 → 0.108.0

package/dist/lab/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";
+/** 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/validation.d.ts

@@ -1,16 +1,16 @@
 import type { LabConfig } 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 lane shape (id/device validity, id uniqueness) is
- * already checked in parseLanes; this is the route-scoped XOR/cap/policy layer.
+ * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
+ * message, or null when valid. The parser enforces it, and runLab 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: LabConfig): 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.
+ * runLab takes a config that skipped the parser.
  */
 export declare function sharedWorldValidationReason(config: LabConfig): string | null;
 /**
@@ -21,7 +21,7 @@ export declare function sharedWorldValidationReason(config: LabConfig): string |
 export declare function desktopMediaValidationReason(config: LabConfig, 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).
+/** 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;
 /**
@@ -43,24 +43,24 @@ export declare function scenarioCapsValidationReason(config: LabConfig): string
 /** Refuse a claimed output bound when the route cannot pass it to the first-party provider. */
 export declare function outputTokenLimitValidationReason(config: LabConfig): string | null;
 /**
- * Cross-validate a CONCURRENT shared-world declaration (#164 phase 2). Returns the failure message,
- * or null when valid. Includes the base shared-world checks PLUS the concurrent extras: a synthetic
- * subject attestation (FIX-3), a 0.0.0.0 serve bind (FIX-4 — getHost only routes to a port bound on
- * all interfaces), and no `subject.clone.keep`/`subject.localTree.keep` (FIX-9 - either would
- * orphan actor sandboxes). Enforced at parse AND re-enforced in the engine (runConcurrentSharedWorld
- * is exported npm surface).
+ * 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 (runLab
+ * takes a config that skipped the parser).
  */
 export declare function concurrentSharedWorldValidationReason(config: LabConfig): string | null;
 /**
- * Cross-validate the EXTERNAL-PUBLIC shared-world declaration (#164 phase 2): a real PUBLIC
- * deployment used DIRECTLY as the shared plane (no getHost, no clone, no subject sandbox, no seed).
- * The honest analog of concurrentSharedWorldValidationReason for a plane the harness does NOT own:
- * it FORBIDS every provisioned-subject field (serve/state.seed/state.checkpoint/exposure/clone/repos
- * are inert with no sandbox — fail closed, never silently ignored, per invariant 6), and REQUIRES a
+ * 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), 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 lane. The getHost synthetic
+ * 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 (runLab takes a config that skipped the parser).
  */
 export declare function externalPublicSharedWorldValidationReason(config: LabConfig): string | null;
 /** Analysis requires a live recording producer, including supported dry-run previews. */

package/dist/lab/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 lane shape (id/device validity, id uniqueness) is
- * already checked in parseLanes; this is the route-scoped XOR/cap/policy layer.
+ * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
+ * message, or null when valid. The parser enforces it, and runLab 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/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,21 +46,21 @@ 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 — that is an
-    // ambiguous shared-world-ish shape, not a per-lane target swarm. Permit N>1 public runs only when
-    // every roster lane declares its own target, making the adapter-owned topology explicit. But when
-    // `subject.topology: shared-world` is ALSO declared, N lanes against one public target is the
-    // EXTERNAL-PUBLIC shared-world topology (#164 phase 2) — ROUTE it there (a real public deployment
+    // 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, 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;
 }
@@ -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.
+ * runLab takes a config that skipped the parser.
  */
 export function sharedWorldValidationReason(config) {
     return config.subject.source === "app-url"
@@ -107,9 +108,9 @@ export function sharedWorldValidationReason(config) {
         : concurrentSharedWorldValidationReason(config);
 }
 /**
- * The structural checks every provisioned shared world shares. It REQUIRES: a clone or local-tree source + e2b-desktop
+ * The structural checks every provisioned shared world shares. It requires: a clone or local-tree source + e2b-desktop
  * target + a computer-use actor + a `subject.serve` block + an `actors[0].lanes` roster of ≥2 roles (the
- * roster IS the role roster — no parallel roles[] field), and every role `entry` must resolve
+ * roster is the role roster; there is no separate roles[] field), and every role `entry` must resolve
  * same-origin (loopback) with serve.url. Fail-closed: a half-declared shared-world is rejected,
  * never silently downgraded.
  */
@@ -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}".`;
         }
     }
@@ -198,7 +199,7 @@ export function receivingEmailValidationReason(config) {
     }
     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()) {
@@ -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-lane 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
@@ -275,12 +277,12 @@ function sharedWorldConcurrencyReason(config) {
     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.`;
 }
 /**
- * Cross-validate a CONCURRENT shared-world declaration (#164 phase 2). Returns the failure message,
- * or null when valid. Includes the base shared-world checks PLUS the concurrent extras: a synthetic
- * subject attestation (FIX-3), a 0.0.0.0 serve bind (FIX-4 — getHost only routes to a port bound on
- * all interfaces), and no `subject.clone.keep`/`subject.localTree.keep` (FIX-9 - either would
- * orphan actor sandboxes). Enforced at parse AND re-enforced in the engine (runConcurrentSharedWorld
- * is exported npm surface).
+ * 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 (runLab
+ * 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
- * deployment used DIRECTLY as the shared plane (no getHost, no clone, no subject sandbox, no seed).
- * The honest analog of concurrentSharedWorldValidationReason for a plane the harness does NOT own:
- * it FORBIDS every provisioned-subject field (serve/state.seed/state.checkpoint/exposure/clone/repos
- * are inert with no sandbox — fail closed, never silently ignored, per invariant 6), and REQUIRES a
+ * 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), 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 lane. The getHost synthetic
+ * 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 (runLab 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
-    // synthetic on a real site, but you MUST attest you own/operate it). Author-trust; unverifiable.
+    // 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.";
     }
-    // FORBID every provisioned-subject field: with no sandbox they cannot act, so they are rejected
-    // with a precise reason, never silently ignored (invariant 6). exposure: synthetic in particular
-    // would be a LIE on a real site (the harness neither provisioned nor exposed it).
+    // No provisioned-subject field is allowed: with no sandbox they cannot act, so they are rejected
+    // 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;
 }

package/dist/lab/warnings.d.ts

@@ -1,2 +1,12 @@
 import type { LabConfig } 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: LabConfig): 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: LabConfig): string[];
 export declare function forwardDeclaredWarnings(config: LabConfig): string[];