humanish 0.107.0 → 0.108.0

package/dist/lab/keys.js

@@ -93,7 +93,10 @@ const ACTOR = {
     count: true,
     lanes: PARTICIPANT_ENTRY,
     // Roster groups are participants with a count; the parser expands them into `lanes[]`.
-    roster: { ...PARTICIPANT_ENTRY, count: true },
+    roster: {
+        ...PARTICIPANT_ENTRY,
+        count: true,
+    },
     persona: true,
     mission: true,
     model: true,
@@ -200,14 +203,45 @@ const LAB_KEYS = {
     defaults: { open: true },
     comms: { email: EMAIL },
 };
+function without(shape, ...keys) {
+    return Object.fromEntries(Object.entries(shape).filter(([key]) => !keys.includes(key)));
+}
+// humanish.study.v3. The route is declared, so `subject.topology` goes. The participant keys leave
+// the actor for `participants`, and `caps` is one top-level block. Top-level `personas` and
+// `scenario.inline` are read by no route, and `scenario` is a string.
+const STUDY_KEYS = {
+    schema: true,
+    id: true,
+    title: true,
+    description: true,
+    route: true,
+    mode: true,
+    subject: without(SUBJECT, "topology"),
+    actor: without(ACTOR, "count", "lanes", "roster", "laneFocus"),
+    // A count, `{ count, instruction }` or a list of entries. studyToV2 checks which form the route
+    // takes; an entry with a count is a group.
+    participants: { ...PARTICIPANT_ENTRY, count: true },
+    surfaces: true,
+    caps: CAPS,
+    execution: without(EXECUTION, "caps"),
+    scenario: true,
+    policies: LAB_KEYS.policies,
+    review: LAB_KEYS.review,
+    defaults: LAB_KEYS.defaults,
+    comms: LAB_KEYS.comms,
+};
 /** The first key in `raw` that LAB_KEYS does not list, as an error message; undefined if none. */
 export function findUnknownLabKey(raw) {
-    return walk(raw, LAB_KEYS, "");
+    return walk(raw, LAB_KEYS, "", "lab");
+}
+/** The first key in a humanish.study.v3 document that the format does not have; undefined if none. */
+export function findUnknownStudyKey(raw) {
+    return walk(raw, STUDY_KEYS, "", "study");
 }
-function walk(value, shape, path) {
+function walk(value, shape, path, noun) {
     if (Array.isArray(value)) {
         for (const [index, item] of value.entries()) {
-            const found = walk(item, shape, `${path}[${index}]`);
+            const found = walk(item, shape, `${path}[${index}]`, noun);
             if (found)
                 return found;
         }
@@ -220,23 +254,23 @@ function walk(value, shape, path) {
     // Object.hasOwn: a key like `constructor` must not match Object.prototype.
     const unknown = Object.keys(record).filter((key) => !Object.hasOwn(shape, key));
     if (unknown.length > 0)
-        return unknownKeysMessage(path, unknown, known);
+        return unknownKeysMessage(path, unknown, known, noun);
     for (const [key, child] of Object.entries(record)) {
         const expected = shape[key];
         if (expected !== true && expected !== undefined) {
-            const found = walk(child, expected, path ? `${path}.${key}` : key);
+            const found = walk(child, expected, path ? `${path}.${key}` : key, noun);
             if (found)
                 return found;
         }
     }
     return undefined;
 }
-function unknownKeysMessage(path, unknown, known) {
+function unknownKeysMessage(path, unknown, known, noun) {
     const named = unknown.map((key) => {
         const suggestion = closest(key, known);
         return suggestion ? `${key} (did you mean \`${suggestion}\`?)` : key;
     });
-    return `Unknown lab field(s)${path ? ` in \`${path}\`` : ""}: ${named.join(", ")}. Known fields: ${known.join(", ")}.`;
+    return `Unknown ${noun} field(s)${path ? ` in \`${path}\`` : ""}: ${named.join(", ")}. Known fields: ${known.join(", ")}.`;
 }
 // The known key within edit distance 2, or one that differs only in case.
 function closest(key, known) {

package/dist/lab/lab-deps.d.ts

@@ -9,12 +9,7 @@ import type { DetachedTimers } from "../substrates/detached.js";
 import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
 import type { LocalTreeArchive } from "../subject/local-tree-archive.js";
 import type { SubjectPhaseEvent } from "../subject/steps.js";
-/** The participant a computer-use subject phase belongs to, with the route's field names. */
-export interface PhaseParticipant {
-    readonly laneId: string;
-    readonly laneIndex: number;
-    readonly laneCount: number;
-}
+import type { ParticipantRef } from "./run-lab-events.js";
 export interface LabDeps {
     /** Loads the E2B SDK. Defaults to loadE2BDesktopModule. */
     readonly desktopModule?: () => Promise<E2BDesktopModule>;
@@ -29,10 +24,10 @@ export interface LabDeps {
      * computer-use phase names its participant; a shared-world plane's names none. onEvent still
      * receives every phase.
      */
-    readonly subjectPhaseSink?: (event: SubjectPhaseEvent, participant?: PhaseParticipant) => void;
+    readonly subjectPhaseSink?: (event: SubjectPhaseEvent, participant?: ParticipantRef) => void;
     /**
-     * Shared world: runs each seat's computer-use session in place of the actor's own. The planner
-     * reads whether it is set: a custom runner cannot enforce actors[0].maxOutputTokens.
+     * Shared world: runs each participant's computer-use session in place of the actor's own. The
+     * planner reads whether it is set: a custom runner cannot enforce actors[0].maxOutputTokens.
      */
     readonly runSession?: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
     /**
@@ -50,13 +45,13 @@ export interface LabDeps {
     /** Shared world: the background stateSeries prober's cadence in milliseconds. Defaults to 1000. */
     readonly proberCadenceMs?: number;
     /**
-     * Shared world, external-public plane: how long the host seat has to surface a /lobby/CODE URL
+     * Shared world, external-public plane: how long the host has to surface a /lobby/CODE URL
      * before the run fails closed. Defaults to 120000, capped by execution.timeoutMs.
      */
     readonly handoffDeadlineMs?: number;
     /**
-     * Shared world, external-public plane: reads a /lobby/CODE off a seat's screenshot. Defaults to
-     * the single-frame OpenAI read.
+     * Shared world, external-public plane: reads a /lobby/CODE off a participant's screenshot.
+     * Defaults to the single-frame OpenAI read.
      */
     readonly readLobbyCodeFromFrame?: (frame: Buffer, apiKey: string) => Promise<string | undefined>;
     /**

package/dist/lab/parse/actors.js

@@ -22,8 +22,8 @@ export function focusOf(actor) {
 // Actor ids humanish no longer registers. Rejecting them at parse keeps a lab 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(),
@@ -57,10 +57,10 @@ export function parseActors(raw) {
         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}").`);
@@ -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/lab/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/lab/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/lab/parse/study-v3.d.ts

@@ -0,0 +1,23 @@
+import { type LabConfigParseFailure } from "../types.js";
+declare const ROUTES: readonly ["preview", "computer-use", "shared-world", "terminal", "scripted"];
+/** A route a study declares. */
+export type StudyRoute = (typeof ROUTES)[number];
+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;
+} | LabConfigParseFailure;
+/** 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/lab/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 LabConfig. parseLabConfig 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 { LAB_CONFIG_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: LAB_CONFIG_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/lab/parse/subject-state.d.ts

@@ -1,10 +1,10 @@
 import type { LabConfigParseFailure, LabSubjectState } 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
+ * 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
+ * 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): {
@@ -14,8 +14,8 @@ export declare function parseEnvValues(raw: unknown): {
 /**
  * Structural parse of `subject.state` into a candidate LabSubjectState. 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 violate invariant 6.
+ * 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;
@@ -23,8 +23,8 @@ export declare function parseState(raw: unknown): {
 } | LabConfigParseFailure;
 /**
  * Semantic validation for `subject.state`, shared by parseLabConfig and the engine
- * (runCuaActorLab re-enforces it on configs that arrive through the library API). Returns
+ * (the route re-enforces it on configs that arrive through runLab). Returns
  * the failure message, or null when the declaration is valid. Reads the candidate
- * defensively — library callers can hand the engine arbitrarily-shaped objects.
+ * defensively: library callers can hand the engine arbitrarily-shaped objects.
  */
 export declare function subjectStateInvalidReason(state: LabSubjectState, env: readonly string[] | undefined): string | null;