humanish 0.107.0 → 0.109.0

package/dist/{lab → study}/parse/actors.d.ts

@@ -1,14 +1,14 @@
-import type { LabActor, LabParticipantEntry, LabParticipantFocus, LabConfigParseFailure } from "../types.js";
+import type { StudyActor, StudyParticipantEntry, StudyParticipantFocus, StudyParseFailure } from "../types.js";
 export declare const PARTICIPANT_ID_PATTERN: RegExp;
 export declare const PARTICIPANT_ID_MAX_CHARS = 40;
 /** The participant entries an actor declares, after roster groups expand into them. The manifest
  *  spells them `actors[].lanes`. Undefined when the actor declares none. */
-export declare function rosterOf<Entry = LabParticipantEntry>(actor: {
+export declare function rosterOf<Entry = StudyParticipantEntry>(actor: {
     readonly lanes?: readonly Entry[];
 } | undefined): readonly Entry[] | undefined;
 /** An actor's per-participant focus on the app-url route. The manifest spells it `laneFocus`. */
-export declare function focusOf(actor: Pick<LabActor, "laneFocus"> | undefined): LabParticipantFocus | undefined;
+export declare function focusOf(actor: Pick<StudyActor, "laneFocus"> | undefined): StudyParticipantFocus | undefined;
 export declare function parseActors(raw: unknown): {
     ok: true;
-    value: LabActor[];
-} | LabConfigParseFailure;
+    value: StudyActor[];
+} | StudyParseFailure;

package/dist/{lab → study}/parse/actors.js

@@ -6,7 +6,7 @@ import { registeredComputerUseActors, registeredScriptedBrowserActors, registere
 import { invalid, posInt, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
 // A participant id interpolates into its evidence paths (screenshots/<id>/, actors/<id>.json), so
-// it must be a public-safe path token, same shape as a lab id.
+// it must be a public-safe path token, same shape as a study id.
 export const PARTICIPANT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 export const PARTICIPANT_ID_MAX_CHARS = 40;
 const METADATA_MAX_CHARS = 80;
@@ -19,11 +19,11 @@ export function rosterOf(actor) {
 export function focusOf(actor) {
     return actor?.laneFocus;
 }
-// Actor ids humanish no longer registers. Rejecting them at parse keeps a lab that names one
+// Actor ids humanish no longer registers. Rejecting them at parse keeps a study that names one
 // from running on a route that ignores actors[0].type, such as a this-repo dry run.
 const REMOVED_ACTOR_TYPES = new Set(["pi-agent-core", "claude-agent-sdk"]);
-// Only actors on a lane a route dispatches. codex-app-server is registered but declares only the
-// "code" lane, which no lab route runs, so naming it would lead to the same dead end.
+// Only actors of a run kind a route dispatches. codex-app-server is registered but declares only
+// the "code" run kind, which no study route runs, so naming it would lead to the same dead end.
 function routableActorTypes() {
     return [
         ...registeredComputerUseActors(),
@@ -33,7 +33,7 @@ function routableActorTypes() {
 }
 export function parseActors(raw) {
     if (!Array.isArray(raw) || raw.length === 0) {
-        return invalid("Lab `actors` must be a non-empty array.");
+        return invalid("`actors` must be a non-empty array.");
     }
     // Multi-actor fan-out is not wired yet (only actors[0] is consumed). Fail closed rather than
     // silently ignore actors[1..]; multi-actor support lands in a later slice.
@@ -50,17 +50,17 @@ export function parseActors(raw) {
             return invalid(`actors[${index}].type is required.`);
         }
         if (REMOVED_ACTOR_TYPES.has(type)) {
-            return invalid(`actors[${index}].type "${type}" is no longer a humanish actor. Use an actor a lab route runs (one of: ${routableActorTypes().join(", ")}). To drive a study with a signed-in Claude Code, use type: local-agent with localAgent: claude.`);
+            return invalid(`actors[${index}].type "${type}" is no longer a humanish actor. Use an actor a study route runs (one of: ${routableActorTypes().join(", ")}). To drive a study with a signed-in Claude Code, use type: local-agent with localAgent: claude.`);
         }
         const actor = { type };
         const count = posInt(entry.count);
         if (count !== undefined)
             actor.count = count;
         if (entry.lanes !== undefined && entry.roster !== undefined) {
-            return invalid(`actors[${index}].lanes and actors[${index}].roster are mutually exclusive: declare participants in \`lanes\` OR in compact \`roster\` groups, not both.`);
+            return invalid(`Set either actors[${index}].lanes or actors[${index}].roster, not both: list participants one by one in \`lanes\`, or in groups in \`roster\`.`);
         }
         if (entry.roster !== undefined && count !== undefined) {
-            return invalid(`actors[${index}].roster and actors[${index}].count are mutually exclusive — use compact differentiated groups OR a homogeneous count, not both.`);
+            return invalid(`Set either actors[${index}].roster or actors[${index}].count, not both: \`roster\` declares groups of distinct participants, and \`count\` declares identical ones.`);
         }
         if (entry.roster !== undefined && entry.laneFocus !== undefined) {
             return invalid(`actors[${index}].roster and actors[${index}].laneFocus are mutually exclusive: a roster group's instruction is each participant's steer.`);
@@ -160,7 +160,7 @@ function parseRosterGroups(raw, actorIndex) {
             return invalid(`actors[${actorIndex}].roster[${groupIndex}].id is required and must be a public-safe token matching ${PARTICIPANT_ID_PATTERN}.`);
         }
         if (!PARTICIPANT_ID_PATTERN.test(groupId) || groupId.length > PARTICIPANT_ID_MAX_CHARS - 3) {
-            return invalid(`actors[${actorIndex}].roster[${groupIndex}].id must be a public-safe token matching ${PARTICIPANT_ID_PATTERN} and at most ${PARTICIPANT_ID_MAX_CHARS - 3} chars (generated participant ids use <id>-NN); got "${groupId}".`);
+            return invalid(`actors[${actorIndex}].roster[${groupIndex}].id must match ${PARTICIPANT_ID_PATTERN} and be at most ${PARTICIPANT_ID_MAX_CHARS - 3} characters, because each generated participant id adds a suffix like "-01"; "${groupId}" is not.`);
         }
         if (seenGroupIds.has(groupId)) {
             return invalid(`actors[${actorIndex}].roster group ids must be unique (duplicate "${groupId}").`);
@@ -189,7 +189,7 @@ function parseRosterGroups(raw, actorIndex) {
  * Participant ids (when declared) must be public-safe path tokens and unique; grouping metadata
  * must be public-safe tokens; a device must be a known preset name. The
  * route-scoped cross-validation (`lanes` XOR `count`/`laneFocus`, device XOR raw resolution, cap 16)
- * runs in parseLabConfig where the route is known.
+ * runs in parseStudy where the route is known.
  */
 function parseParticipantEntries(raw, actorIndex) {
     if (raw === undefined) {
@@ -272,7 +272,7 @@ function parseParticipantEntries(raw, actorIndex) {
         const entryPath = str(entry.entry);
         if (entryPath !== undefined)
             parsedEntry.entry = entryPath;
-        // `host` marks the designated host seat on the external-public shared-world route; the
+        // `host` marks the designated host on the external-public shared-world route; the
         // exactly-one-host check runs in externalPublicSharedWorldValidationReason (route context).
         if (entry.host !== undefined) {
             if (typeof entry.host !== "boolean") {
@@ -287,7 +287,7 @@ function parseParticipantEntries(raw, actorIndex) {
 }
 /**
  * The researcher's protocol. Each task carries what the participant is asked to do and, optionally,
- * the observation that proves it happened — reusing `stopWhen`, so a criterion is exactly as
+ * the observation that proves it happened, reusing `stopWhen`, so a criterion is exactly as
  * expressive as a stop condition and an author who knows one knows the other.
  *
  * A task with no `success` is allowed on purpose: some things you ask a participant to do (think
@@ -314,7 +314,7 @@ function parseTasks(raw, field) {
         seen.add(id);
         const goal = str(entry.goal);
         if (goal === undefined) {
-            return invalid(`\`${field}[${index}].goal\` is required — what the PARTICIPANT is asked to do, in their language.`);
+            return invalid(`\`${field}[${index}].goal\` is required: what the participant is asked to do, in their own words.`);
         }
         const successResult = parseStopWhen(entry.success, `${field}[${index}].success`);
         if (!successResult.ok)
@@ -327,7 +327,7 @@ function parseTasks(raw, field) {
     }
     return { ok: true, value: tasks };
 }
-/** The bounds a dwell window (#510) must sit inside: at least one frame, at most an hour. */
+/** The bounds a dwell window must sit inside: at least one frame, at most an hour. */
 const DWELL_MIN_MS = 1_000;
 const DWELL_MAX_MS = 3_600_000;
 const DWELL_DEFAULT_EVERY_MS = 10_000;

package/dist/study/parse/comms.d.ts

@@ -0,0 +1,12 @@
+import type { StudyComms, StudyCommsEmail, StudyCommsRecipient, StudyParseFailure } from "../types.js";
+export declare function parseComms(raw: unknown): {
+    ok: true;
+    value: StudyComms | undefined;
+} | StudyParseFailure;
+/** The participant a declared inbox recipient belongs to. The manifest spells it `lane`. */
+export declare function recipientParticipantId(recipient: StudyCommsRecipient): string;
+/** The declared recipients that name an address, in declaration order, by participant id. */
+export declare function addressedRecipients(email: Pick<StudyCommsEmail, "recipients">): {
+    participantId: string;
+    address: string;
+}[];

package/dist/{lab → study}/parse/comms.js

@@ -30,8 +30,8 @@ function parseCommsEmail(raw) {
     if (raw.kind !== undefined && raw.kind !== "fake") {
         return invalid("`comms.email.kind` must be `fake`.");
     }
-    // external ingress (#328): the ADOPTER runs the catch, so there is no subject env for humanish to
-    // inject and `injectEnv` becomes meaningless rather than merely unused — the operator points their
+    // external ingress: the adopter runs the catch, so there is no subject env for humanish to
+    // inject and `injectEnv` has nothing to name: the operator points their
     // own app at their own catch. Parse it first so the injectEnv requirement can key off it.
     const external = parseExternalCatch(raw.external);
     if (!external.ok)
@@ -127,7 +127,7 @@ function parseExternalCatch(raw) {
         return invalid("`comms.email.external` must be a mapping.");
     const catchBaseUrl = str(raw.catchBaseUrl);
     if (catchBaseUrl === undefined) {
-        return invalid("`comms.email.external.catchBaseUrl` is required — the base URL of the catch YOU run (humanish reads its GET /deliveries and your app POSTs its sends to it).");
+        return invalid("`comms.email.external.catchBaseUrl` is required: the base URL of the catch you run. Your app sends its mail to it, and humanish reads GET /deliveries from it.");
     }
     for (const [field, value] of [
         ["catchBaseUrl", catchBaseUrl],
@@ -148,7 +148,7 @@ function parseExternalCatch(raw) {
     }
     const authTokenEnv = str(raw.authTokenEnv);
     if (authTokenEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(authTokenEnv)) {
-        return invalid(`\`comms.email.external.authTokenEnv\` must be a valid env var NAME (got "${authTokenEnv}"); the value is read at runtime and never persisted.`);
+        return invalid(`\`comms.email.external.authTokenEnv\` must be an environment variable name, and "${authTokenEnv}" is not one. Its value is read when the run starts and never stored.`);
     }
     const inboxBaseUrl = str(raw.inboxBaseUrl);
     return {
@@ -175,7 +175,7 @@ function parseSmtp(raw) {
     const hostEnv = envName(raw.hostEnv, "hostEnv");
     const portEnv = envName(raw.portEnv, "portEnv");
     if (hostEnv === undefined || portEnv === undefined) {
-        return invalid("`comms.email.smtp` needs both `hostEnv` and `portEnv` — the subject-env vars your app reads for its SMTP host and port. The harness sets them to its own loopback listener.");
+        return invalid("`comms.email.smtp` needs both `hostEnv` and `portEnv`: the environment variables your app reads for its SMTP host and port. humanish sets them to its own loopback listener.");
     }
     if (hostEnv.startsWith("__invalid__") || portEnv.startsWith("__invalid__")) {
         return invalid("`comms.email.smtp.hostEnv` and `portEnv` must be valid env var names.");

package/dist/study/parse/execution.d.ts

@@ -0,0 +1,19 @@
+import type { StudyParseFailure, StudyDefaults, StudyExecution, StudyPolicies, StudyReview, StudyScenario } from "../types.js";
+export declare function parseExecution(raw: unknown): {
+    ok: true;
+    value: StudyExecution | undefined;
+} | StudyParseFailure;
+export declare function parsePersonas(raw: unknown): Record<string, unknown>[] | undefined;
+export declare function parseScenario(raw: unknown): {
+    ok: true;
+    value: StudyScenario | undefined;
+} | StudyParseFailure;
+export declare function parsePolicies(raw: unknown): {
+    ok: true;
+    value: StudyPolicies | undefined;
+} | StudyParseFailure;
+export declare function parseReview(raw: unknown): {
+    ok: true;
+    value: StudyReview | undefined;
+} | StudyParseFailure;
+export declare function parseDefaults(raw: unknown): StudyDefaults | undefined;

package/dist/{lab → study}/parse/execution.js

@@ -33,7 +33,7 @@ export function parseExecution(raw) {
     }
     if (desktopResult.value)
         execution.desktop = desktopResult.value;
-    // Reuse the terminal route's caps parser (same shape, not a fork) — a malformed budget is a hard
+    // Reuse the terminal route's caps parser (same shape, not a fork); a malformed budget is a hard
     // error, never silently dropped (a cap that silently does nothing would be a safety lie).
     const capsResult = parseCaps(raw.caps);
     if (!capsResult.ok) {
@@ -90,9 +90,9 @@ function parseTerminal(raw) {
         const transport = str(raw.transport);
         if (transport !== "exec-stream") {
             // "pty" is deliberately rejected: stdin is disabled, so the capture is a non-interactive
-            // exec stream — an interactive-PTY label would overstate the mechanism (invariant 6 + the
-            // goal packet's PTY ruling). True duplex PTY does not ship.
-            return invalid("`execution.terminal.transport` must be exec-stream — captured non-interactive exec output (stdin disabled) is not an interactive PTY; true duplex PTY transport is not supported.");
+            // exec stream, and an interactive-PTY label would overstate the mechanism. True duplex PTY
+            // does not ship.
+            return invalid("`execution.terminal.transport` must be exec-stream: the route captures the agent's output with stdin closed, and an interactive terminal (pty) is not supported.");
         }
         terminal.transport = transport;
     }
@@ -103,9 +103,9 @@ function parseTerminal(raw) {
         }
         if (stdin === "sent") {
             // Assisted input is forbidden until the interventions ledger + comparability flag + verify
-            // check exist (safety contract item 7) — shipping it now would let an assisted run pose as
-            // autonomous green proof.
-            return invalid("`execution.terminal.stdin: sent` (assisted input) is not supported — the current route cannot capture assisted input with a non-comparable marker. stdin is disabled by default.");
+            // check exist (the terminal route's stdin rule); shipping it now would let an assisted run
+            // pose as autonomous green proof.
+            return invalid("`execution.terminal.stdin: sent` (assisted input) is not supported: the route cannot yet mark a run that received typed help as different from an unassisted one. Remove the setting; stdin stays closed.");
         }
         terminal.stdin = stdin;
     }
@@ -153,13 +153,13 @@ function parseDesktop(raw) {
         }
         desktop.browser = browser;
     }
-    // A custom E2B desktop template NAME or ID. Trimmed non-empty when present; deliberately NOT
-    // allowlisted (any string is a valid template name/id — over-restricting would reject real
+    // A custom E2B desktop template name or ID. Trimmed non-empty when present; deliberately not
+    // allowlisted (any string is a valid template name/id; over-restricting would reject real
     // adopter images). An explicitly-set but blank/whitespace value is a mistake, not a template.
     if (raw.template !== undefined) {
         const template = str(raw.template);
         if (template === undefined) {
-            return invalid("`execution.desktop.template` must be a non-empty E2B desktop template NAME or ID when set (any string is accepted; there is no allowlist).");
+            return invalid("`execution.desktop.template` must be a non-empty E2B desktop template name or ID when it is set. Any name is accepted.");
         }
         desktop.template = template;
     }
@@ -247,8 +247,8 @@ export function parseScenario(raw) {
 }
 /**
  * Parse `scenario.caps`. Returns a parse failure on a malformed value rather than silently
- * dropping a budget declaration (a cap that silently does nothing would be a safety lie —
- * invariant 6). Each cap must be a non-negative finite number.
+ * dropping a budget declaration (a cap that silently does nothing would claim protection it
+ * does not give). Each cap must be a non-negative finite number.
  */
 function parseCaps(raw) {
     if (raw === undefined) {
@@ -339,7 +339,7 @@ function parseReviewScorer(raw) {
         return invalid("`review.scorer` must be a mapping with a `ref` path (e.g. { ref: scorers/product.mjs }).");
     const unknownKeys = Object.keys(raw).filter((key) => key !== "ref");
     if (unknownKeys.length > 0) {
-        return invalid(`Unknown \`review.scorer\` field(s): ${unknownKeys.join(", ")}. review.scorer accepts only \`ref\` (a repo-relative scorer-module path).`);
+        return invalid(`\`review.scorer\` accepts only \`ref\` (a scorer module path relative to the project), and these fields are unknown: ${unknownKeys.join(", ")}.`);
     }
     const ref = str(raw.ref);
     if (!ref)

package/dist/study/parse/study-v3.d.ts

@@ -0,0 +1,21 @@
+import type { StudyRoute } from "../routing.js";
+import { type StudyParseFailure } from "../types.js";
+export interface StudyDocument {
+    readonly route: StudyRoute;
+    /** The same document in the humanish.lab.v2 spelling. */
+    readonly v2: Record<string, unknown>;
+    /** For each expanded participant, the index of the `participants` entry it came from. */
+    readonly participantSource: readonly number[];
+}
+type Parsed<T> = {
+    ok: true;
+    value: T;
+} | StudyParseFailure;
+/** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
+export declare function studyToV2(raw: Record<string, unknown>): Parsed<StudyDocument>;
+/**
+ * Spell a v2 parser message the way the study file is written: `actors[0].lanes[3]` becomes the
+ * `participants` entry it came from, `execution.caps` and `scenario.caps` become `caps`, and so on.
+ */
+export declare function studySpelling(message: string, route: StudyRoute, participantSource: readonly number[]): string;
+export {};

package/dist/study/parse/study-v3.js

@@ -0,0 +1,259 @@
+// humanish.study.v3, the study format. A study declares its route, one `actor`, its `participants`
+// and one `caps` block. studyToV2 rewrites a v3 document into the v2 spelling, so both formats run
+// through one parser and parse into the same StudyConfig. parseStudy then checks the declared
+// route against the one the config takes, and refuses any field that route does not read.
+import { isRecord } from "../../run/type-guards.js";
+import { findUnknownStudyKey } from "../keys.js";
+import { V2_SCHEMA } from "../types.js";
+import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./actors.js";
+import { invalid, posInt } from "./values.js";
+// The values `route:` takes: every route routeOf can return.
+const ROUTES = [
+    "preview",
+    "computer-use",
+    "shared-world",
+    "terminal",
+    "scripted",
+];
+// The caps keys each route reads. Computer use and shared world stop on estimated model spend;
+// the terminal route checks its spend ledger, product jobs and the command deadline.
+const CAPS_KEYS = {
+    preview: [],
+    "computer-use": ["maxUsd", "maxTotalUsd"],
+    "shared-world": ["maxUsd", "maxTotalUsd"],
+    terminal: ["maxUsd", "maxJobs", "maxMinutes"],
+    scripted: [],
+};
+/** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
+export function studyToV2(raw) {
+    const moved = movedKeyReason(raw);
+    if (moved)
+        return invalid(moved);
+    const unknownKey = findUnknownStudyKey(raw);
+    if (unknownKey)
+        return invalid(unknownKey);
+    const route = ROUTES.find((name) => name === raw.route);
+    if (route === undefined) {
+        return invalid(`A study needs \`route:\`, one of ${ROUTES.join(", ")}.`);
+    }
+    if (raw.mode !== undefined && raw.mode !== "dry-run" && raw.mode !== "live") {
+        return invalid("`mode` must be `dry-run` or `live`. Leave it out for a dry run.");
+    }
+    if (!isRecord(raw.actor)) {
+        return invalid("A study needs `actor:`, an object with at least `type`.");
+    }
+    if (raw.scenario !== undefined && typeof raw.scenario !== "string") {
+        return invalid("`scenario` is a scenario id or a path to one, as a string.");
+    }
+    const participants = participantsOf(route, raw.participants);
+    if (!participants.ok)
+        return participants;
+    const surfaces = surfaceCount(route, raw.surfaces);
+    if (!surfaces.ok)
+        return surfaces;
+    const capsReason = capsKeysReason(route, raw.caps);
+    if (capsReason)
+        return invalid(capsReason);
+    // The v2 inert-field table does not list this one, but the terminal planner never reads it.
+    if (route === "terminal" && isRecord(raw.execution) && raw.execution.timeoutMs !== undefined) {
+        return invalid("route: terminal does not read `execution.timeoutMs`: `caps.maxMinutes` is the command deadline. Remove it.");
+    }
+    const { count, instruction, entries, source } = participants.value;
+    // The v2 actor keys that hold participants.
+    const v2Participants = [
+        ["count", count ?? surfaces.value],
+        ["laneFocus", instruction === undefined ? undefined : { instruction }],
+        ["lanes", entries],
+    ];
+    const actor = { ...raw.actor };
+    for (const [key, value] of v2Participants)
+        if (value !== undefined)
+            actor[key] = value;
+    const caps = raw.caps;
+    const scenario = {};
+    if (raw.scenario !== undefined)
+        scenario.ref = raw.scenario;
+    if (raw.mode !== undefined)
+        scenario.mode = raw.mode;
+    if (caps !== undefined && route === "terminal")
+        scenario.caps = caps;
+    const execution = caps !== undefined && route !== "terminal"
+        ? withKey(raw.execution, "caps", caps)
+        : raw.execution;
+    const subject = route === "shared-world" ? withKey(raw.subject, "topology", "shared-world") : raw.subject;
+    const v2 = { schema: V2_SCHEMA };
+    const fields = [
+        ["id", raw.id],
+        ["title", raw.title],
+        ["description", raw.description],
+        ["subject", subject],
+        ["actors", [actor]],
+        ["execution", execution],
+        ["scenario", Object.keys(scenario).length > 0 ? scenario : undefined],
+        ["policies", raw.policies],
+        ["review", raw.review],
+        ["defaults", raw.defaults],
+        ["comms", raw.comms],
+    ];
+    for (const [key, value] of fields)
+        if (value !== undefined)
+            v2[key] = value;
+    return { ok: true, value: { route, v2, participantSource: source } };
+}
+/**
+ * Spell a v2 parser message the way the study file is written: `actors[0].lanes[3]` becomes the
+ * `participants` entry it came from, `execution.caps` and `scenario.caps` become `caps`, and so on.
+ */
+export function studySpelling(message, route, participantSource) {
+    return (message
+        .replaceAll(/actors\[0\]\.lanes\[(\d+)\]/g, (_match, index) => `participants[${participantSource[Number(index)] ?? index}]`)
+        // "an `actors[0].lanes` roster" reads "a `participants` list" in a v3 file.
+        .replaceAll(/\ban `actors\[0\]\.(lanes|roster)` roster\b/g, "a `participants` list")
+        .replaceAll(/actors\[0\]\.(lanes|roster)\b/g, "participants")
+        .replaceAll(/actors\[0\]\.laneFocus(\.instruction)?/g, "participants.instruction")
+        .replaceAll(/actors\[0\]\.count\b/g, route === "scripted" ? "surfaces" : "participants")
+        .replaceAll("actors[0]", "actor")
+        .replaceAll(/\b(execution|scenario)\.caps\b/g, "caps")
+        .replaceAll(/\bscenario\.mode\b/g, "mode")
+        .replaceAll(/\bscenario\.ref\b/g, "scenario")
+        .replaceAll("subject.topology: shared-world", "route: shared-world"));
+}
+// The v2 keys a hand-converted file is most likely to keep, each with where it went.
+function movedKeyReason(raw) {
+    if (raw.actors !== undefined) {
+        return "A study has one `actor:` object, and its participants go in `participants:`. `actors:` is the humanish.lab.v2 spelling.";
+    }
+    if (isRecord(raw.actor)) {
+        for (const key of ["count", "lanes", "roster", "laneFocus"]) {
+            if (raw.actor[key] !== undefined) {
+                return `\`actor.${key}\` moved to \`participants:\`: a count, \`{ count, instruction }\`, or a list of participants.`;
+            }
+        }
+    }
+    if (isRecord(raw.subject) && raw.subject.topology !== undefined) {
+        return "`subject.topology` moved to `route:`. A shared world is `route: shared-world`.";
+    }
+    if (isRecord(raw.execution) && raw.execution.caps !== undefined) {
+        return "`execution.caps` moved to a top-level `caps:` block.";
+    }
+    return undefined;
+}
+function participantsOf(route, raw) {
+    if (raw === undefined) {
+        if (route === "shared-world")
+            return invalid(listOnly(route));
+        return { ok: true, value: { source: [] } };
+    }
+    switch (route) {
+        case "scripted":
+            return invalid("route: scripted takes no `participants`. It replays committed steps on `surfaces`: [desktop] or [desktop, mobile].");
+        case "terminal":
+            return invalid("route: terminal takes no `participants`. It runs one agent.");
+        case "preview":
+            return typeof raw === "number"
+                ? countOf(raw)
+                : invalid("route: preview takes `participants` as a count, such as `participants: 4`.");
+        case "shared-world":
+            return Array.isArray(raw) ? entriesOf(raw) : invalid(listOnly(route));
+        case "computer-use":
+            if (typeof raw === "number")
+                return countOf(raw);
+            if (Array.isArray(raw))
+                return entriesOf(raw);
+            return homogeneousOf(raw);
+    }
+}
+function listOnly(route) {
+    return `route: ${route} takes \`participants\` as a list of at least two entries, one per participant in the shared world.`;
+}
+function countOf(raw) {
+    const count = posInt(raw);
+    if (count === undefined)
+        return invalid("`participants` must be a positive integer.");
+    return { ok: true, value: { count, source: [] } };
+}
+// `{ count, instruction }`: participants that share one instruction. The count stays a count, so
+// `--count` still overrides it.
+function homogeneousOf(raw) {
+    if (!isRecord(raw)) {
+        return invalid("`participants` is a count, an object `{ count, instruction }`, or a list of participants.");
+    }
+    const extra = Object.keys(raw).filter((key) => key !== "count" && key !== "instruction");
+    if (extra.length > 0) {
+        return invalid(`\`participants\` as an object takes only \`count\` and \`instruction\`, and every participant gets them. To set ${extra.map((key) => `\`${key}\``).join(", ")}, write participants as a list.`);
+    }
+    const participants = { source: [] };
+    if (raw.count !== undefined) {
+        const count = typeof raw.count === "number" ? posInt(raw.count) : undefined;
+        if (count === undefined)
+            return invalid("`participants.count` must be a positive integer.");
+        participants.count = count;
+    }
+    if (raw.instruction !== undefined)
+        participants.instruction = raw.instruction;
+    return { ok: true, value: participants };
+}
+// A list entry with `count: n` is a group: n participants `<id>-01` to `<id>-NN`, even when n is 1.
+// The v2 parser then checks every entry and the expanded ids for collisions.
+function entriesOf(raw) {
+    const entries = [];
+    const source = [];
+    for (const [index, entry] of raw.entries()) {
+        if (!isRecord(entry) || entry.count === undefined) {
+            entries.push(entry);
+            source.push(index);
+            continue;
+        }
+        const count = typeof entry.count === "number" ? posInt(entry.count) : undefined;
+        if (count === undefined) {
+            return invalid(`participants[${index}].count must be a positive integer.`);
+        }
+        const id = entry.id;
+        if (typeof id !== "string" ||
+            !PARTICIPANT_ID_PATTERN.test(id) ||
+            id.length > PARTICIPANT_ID_MAX_CHARS - 3) {
+            return invalid(`participants[${index}] has a count, so it needs an \`id\` matching ${PARTICIPANT_ID_PATTERN} of at most ${PARTICIPANT_ID_MAX_CHARS - 3} characters. Its participants are <id>-01 to <id>-${String(count).padStart(2, "0")}.`);
+        }
+        const shared = { ...entry };
+        delete shared.count;
+        for (let n = 1; n <= count; n += 1) {
+            entries.push({ ...shared, id: `${id}-${String(n).padStart(2, "0")}` });
+            source.push(index);
+        }
+    }
+    return { ok: true, value: { entries, source } };
+}
+// Scripted surfaces become the v2 count: 1 is desktop, 2 adds mobile.
+function surfaceCount(route, raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (route !== "scripted") {
+        return invalid(`\`surfaces\` belongs to route: scripted. This study's route is ${route}; remove it.`);
+    }
+    if (Array.isArray(raw) && raw.length === 1 && raw[0] === "desktop")
+        return { ok: true, value: 1 };
+    if (Array.isArray(raw) && raw.length === 2 && raw[0] === "desktop" && raw[1] === "mobile") {
+        return { ok: true, value: 2 };
+    }
+    return invalid("`surfaces` must be [desktop] or [desktop, mobile].");
+}
+function capsKeysReason(route, raw) {
+    if (raw === undefined)
+        return undefined;
+    const read = CAPS_KEYS[route];
+    if (read.length === 0)
+        return `route: ${route} reads no \`caps\`; remove the block.`;
+    if (!isRecord(raw))
+        return undefined;
+    const unread = Object.keys(raw).filter((key) => !read.includes(key));
+    if (unread.length === 0)
+        return undefined;
+    return `route: ${route} reads only ${read.map((key) => `caps.${key}`).join(", ")}. Remove ${unread.map((key) => `caps.${key}`).join(", ")}.`;
+}
+// Add one key to a section. A section that is not an object passes through unchanged, so the v2
+// parser refuses it with its own message.
+function withKey(section, key, value) {
+    if (section === undefined)
+        return { [key]: value };
+    return isRecord(section) ? { ...section, [key]: value } : section;
+}

package/dist/study/parse/subject-state.d.ts

@@ -0,0 +1,30 @@
+import type { StudyParseFailure, StudySubjectState } from "../types.js";
+/**
+ * Literal non-secret subject env. Real apps need configuration before they will boot: a public base
+ * URL, a transport selector, a feature flag, and none of that is secret. Routing it through
+ * `subject.env` would force an adopter to carry a private env file just to reproduce a public study.
+ *
+ * These values are recorded in evidence (they are part of how the subject was configured), so a
+ * value that looks like a credential is refused here rather than committed to a public repo.
+ */
+export declare function parseEnvValues(raw: unknown): {
+    ok: true;
+    value?: Record<string, string>;
+} | StudyParseFailure;
+/**
+ * Structural parse of `subject.state` into a candidate StudySubjectState. Deliberately keeps
+ * unrecognized `when`/`timeoutMs` values in the candidate (instead of silently dropping
+ * them) so subjectStateInvalidReason rejects them: a state declaration that silently does
+ * less than it says would claim more than its mechanism does.
+ */
+export declare function parseState(raw: unknown): {
+    ok: true;
+    value: StudySubjectState | undefined;
+} | StudyParseFailure;
+/**
+ * Semantic validation for `subject.state`, shared by parseStudy and the engine
+ * (the route re-enforces it on configs that arrive through runStudyWith). Returns
+ * the failure message, or null when the declaration is valid. Reads the candidate
+ * defensively: library callers can hand the engine arbitrarily-shaped objects.
+ */
+export declare function subjectStateInvalidReason(state: StudySubjectState, env: readonly string[] | undefined): string | null;