humanish 0.110.4 → 0.111.1

package/dist/study/migrate/v2.js

@@ -4,20 +4,113 @@
 // rules the two formats share. The converter (convert.ts) rewrites the YAML document separately and
 // compares what the two rewrites parse to.
 //
-// The v2-only rules are copies of the parser's and the planners' (the actor list and roster in
-// parse/actors.ts, the scenario object in parse/execution.ts, and checks in validation.ts and
-// composition-rules.ts), which stay there while a library config can still take the v2 shape.
+// The v2 parser itself is gone. The rules here on keys v3 does not have (the actor list and roster,
+// `laneFocus`, the `scenario` object, `subject.topology`, `execution.caps`, and the checks on their
+// combinations) are kept with that parser's messages, so migrate refuses what it refused.
 import { isRecord } from "../../run/type-guards.js";
-import { findUnknownV2Key } from "../keys.js";
+import { ACTOR, CAPS, EXECUTION, findUnknownKey, PARTICIPANT_ENTRY, SHARED_SECTIONS, SUBJECT, } from "../keys.js";
 import { parseActorFields, parseActorType, parseParticipantEntries, PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN, } from "../parse/actors.js";
 import { parseComms } from "../parse/comms.js";
-import { parseExecution, parsePolicies, parseReview } from "../parse/execution.js";
-import { parseCaps } from "../parse/study.js";
-import { parseSubject } from "../parse/subject.js";
+import { parseCaps, parseExecution, parsePolicies, parseReview } from "../parse/execution.js";
+import { hasSubjectSource, parseSubject } from "../parse/subject.js";
 import { posInt, str } from "../parse/values.js";
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, routeOf, } from "../routing.js";
 import { desktopMediaValidationReason, outputTokenLimitValidationReason, smtpValidationReason, } from "../validation.js";
-import { ID_PATTERN, STUDY_SCHEMA, V2_SCHEMA, } from "../types.js";
+import { ID_PATTERN, STUDY_SCHEMA, } from "../types.js";
+/** The schema of the study format before humanish.study.v3. */
+export const V2_SCHEMA = "humanish.lab.v2";
+/** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
+export const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study, which humanish no longer reads. Convert its file with humanish migrate <path>.";
+// The StudyConfig fields of humanish 0.110 and earlier, which a humanish.study.v3 config does not
+// have, each with where its value goes now. A library caller may still build a config with them.
+const V2_FIELDS = [
+    {
+        present: (config) => config.actors !== undefined,
+        move: "`actors[0]` is `actor`, and its `count`, `lanes`, `roster` and `laneFocus` are `participants` (`surfaces` on the scripted route)",
+    },
+    // A caller that moved `actors[0]` to `actor` as it was.
+    {
+        present: (config) => isRecord(config.actor) &&
+            ["count", "lanes", "roster", "laneFocus"].some((key) => config.actor[key] !== undefined),
+        move: "`actor.count`, `actor.lanes`, `actor.roster` and `actor.laneFocus` are `participants` (`surfaces` on the scripted route)",
+    },
+    {
+        present: (config) => isRecord(config.scenario),
+        move: "`scenario.ref` is `scenario`, a string, `scenario.mode` is `mode` and `scenario.caps` is `caps`",
+    },
+    {
+        present: (config) => isRecord(config.execution) && config.execution.caps !== undefined,
+        move: "`execution.caps` is `caps`",
+    },
+    {
+        present: (config) => isRecord(config.subject) && config.subject.topology !== undefined,
+        move: "`subject.topology: shared-world` is `route: shared-world`",
+    },
+    {
+        present: (config) => config.personas !== undefined,
+        move: "`personas` has no field now; remove it",
+    },
+];
+/** Where each humanish 0.110 StudyConfig field a config still sets went; empty when it sets none. */
+export function v2FieldMoves(config) {
+    if (!isRecord(config))
+        return [];
+    return V2_FIELDS.filter((field) => field.present(config)).map((field) => field.move);
+}
+/**
+ * The v2 key a hand-converted humanish.study.v3 file is most likely to keep, with where it went;
+ * undefined when the file keeps none. parse/front.ts refuses the file with it.
+ */
+export function movedV2KeyReason(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;
+}
+// The keys of a humanish.lab.v2 file, in the order its parser listed them: the v3 sections with
+// `subject.topology`, the actor list with its participant keys, `execution.caps`, `personas` and
+// the `scenario` object.
+const V2_KEYS = {
+    schema: true,
+    id: true,
+    title: true,
+    description: true,
+    subject: { source: true, topology: true, ...without(SUBJECT, "source") },
+    actors: {
+        type: true,
+        count: true,
+        lanes: PARTICIPANT_ENTRY,
+        // Roster groups are participants with a count; the parser expanded them into `lanes[]`.
+        roster: { ...PARTICIPANT_ENTRY, count: true },
+        ...without(ACTOR, "type"),
+        laneFocus: { id: true, label: true, instruction: true },
+    },
+    execution: withAfter(EXECUTION, "egressAllow", { caps: CAPS }),
+    // Inline personas were validated by the persona resolver.
+    personas: true,
+    scenario: { ref: true, mode: true, inline: true, caps: CAPS },
+    ...SHARED_SECTIONS,
+};
+function without(shape, ...keys) {
+    return Object.fromEntries(Object.entries(shape).filter(([key]) => !keys.includes(key)));
+}
+// `shape` with `added` inserted after the key `after`.
+function withAfter(shape, after, added) {
+    return Object.fromEntries(Object.entries(shape).flatMap((entry) => entry[0] === after ? [entry, ...Object.entries(added)] : [entry]));
+}
 function refused(message) {
     return { ok: false, message };
 }
@@ -32,22 +125,26 @@ const ENTRY_PATHS = {
  * message.
  */
 export function checkV2(raw) {
-    const unknownKey = findUnknownV2Key(raw);
+    const unknownKey = findUnknownKey(raw, V2_KEYS);
     if (unknownKey)
         return refused(unknownKey);
     const id = str(raw.id);
     if (!id || !ID_PATTERN.test(id)) {
         return refused("The study id must be a public-safe token starting with a letter or digit (/^[A-Za-z0-9][A-Za-z0-9_.-]*$/).");
     }
+    // The v2 parser checked `subject.topology` right after `subject.source`.
+    const topology = hasSubjectSource(raw.subject) ? readTopology(raw.subject) : undefined;
+    if (topology?.ok === false)
+        return topology;
     const subject = parseSubject(raw.subject);
     if (!subject.ok)
         return refused(subject.error.message);
     const actor = readActor(raw.actors);
     if (!actor.ok)
         return actor;
-    const execution = parseExecution(raw.execution);
+    const execution = readExecution(raw.execution);
     if (!execution.ok)
-        return refused(execution.error.message);
+        return execution;
     const scenario = readScenario(raw.scenario);
     if (!scenario.ok)
         return scenario;
@@ -71,22 +168,26 @@ export function checkV2(raw) {
     if (!comms.ok)
         return refused(comms.error.message);
     const composition = {
-        schema: V2_SCHEMA,
+        schema: STUDY_SCHEMA,
         id,
+        // A shared world is declared; any other route is derived below.
+        route: topology?.value === "shared-world" ? "shared-world" : "computer-use",
         subject: subject.value,
-        actors: [{ type: actor.value.type, ...actor.value.fields }],
-        ...(execution.value === undefined ? {} : { execution: execution.value }),
+        actor: { type: actor.value.type, ...actor.value.fields },
+        ...(execution.value.execution === undefined ? {} : { execution: execution.value.execution }),
         ...(policies.value === undefined ? {} : { policies: policies.value }),
         ...(comms.value === undefined ? {} : { comms: comms.value }),
     };
     const route = v2RouteOf(composition);
+    composition.route = route;
     const study = {
         route,
         composition,
+        topology: topology?.value,
         count: actor.value.count,
         entries: actor.value.entries,
         focus: actor.value.focus,
-        executionCaps: execution.value?.caps,
+        executionCaps: execution.value.caps,
         scenario: scenario.value,
         personas: Array.isArray(raw.personas) && raw.personas.some(isRecord),
         terminalTimeout: route === "terminal" && isRecord(raw.execution) && raw.execution.timeoutMs !== undefined,
@@ -107,7 +208,37 @@ export function checkV2(raw) {
  * the shared-world checks' refusal, as it does from the v2 parser.
  */
 function v2RouteOf(composition) {
-    return composition.subject.topology === "shared-world" ? "shared-world" : routeOf(composition);
+    return composition.route === "shared-world" ? "shared-world" : routeOf(composition);
+}
+// parse/subject.ts read `subject.topology` as one of two values.
+function readTopology(subject) {
+    if (!isRecord(subject) || subject.topology === undefined)
+        return { ok: true, value: undefined };
+    const topology = str(subject.topology);
+    if (topology !== "per-lane-worlds" && topology !== "shared-world") {
+        return refused("`subject.topology` must be per-lane-worlds (the default) or shared-world.");
+    }
+    return { ok: true, value: topology };
+}
+// parse/execution.ts parseExecution, which read `execution.caps` after `execution.desktop` and
+// before `execution.terminal`.
+function readExecution(raw) {
+    let caps;
+    if (isRecord(raw)) {
+        const { target, timeoutMs, completionTimeoutMs, concurrency, desktop } = raw;
+        const head = parseExecution({ target, timeoutMs, completionTimeoutMs, concurrency, desktop });
+        if (!head.ok)
+            return refused(head.error.message);
+        const parsed = parseCaps(raw.caps);
+        if (!parsed.ok)
+            return refused(parsed.error.message);
+        caps = parsed.value;
+    }
+    // parseExecution reads every key but `caps`.
+    const execution = parseExecution(raw);
+    if (!execution.ok)
+        return refused(execution.error.message);
+    return { ok: true, value: { execution: execution.value, caps } };
 }
 // parse/actors.ts parseActors, for the one actor it accepts.
 function readActor(raw) {
@@ -252,7 +383,7 @@ export function v2ShapeReason(study) {
     const { route, composition, count, entries, focus } = study;
     if (route === "scripted") {
         // composition-rules.ts scriptedBrowserValidationReason, in its order.
-        if (composition.subject.source === "clone" && composition.subject.topology !== undefined) {
+        if (composition.subject.source === "clone" && study.topology !== undefined) {
             return "A clone scripted-browser study does not support `subject.topology` yet: it runs one synthetic subject for its scripted actor. Remove `subject.topology`.";
         }
         if ((count ?? 1) > 2) {
@@ -280,13 +411,13 @@ export function v2ShapeReason(study) {
     const caps = study.scenario?.caps;
     if (composition.subject.source === "app-url" &&
         composition.execution?.target === "local" &&
-        composition.actors[0]?.type === "local-agent" &&
+        composition.actor.type === "local-agent" &&
         (caps?.maxUsd !== undefined || caps?.maxTotalUsd !== undefined)) {
         return "Local Codex participants currently use gpt-6-astra at low effort. Account dollar/output-token caps are unavailable; use API participants for those controls.";
     }
     return undefined;
 }
-// The caps keys each route reads, as study-v3.ts CAPS_KEYS has them.
+// The caps keys each route reads, as parse/front.ts CAPS_KEYS has them.
 const CAPS_READ = {
     preview: [],
     "computer-use": ["maxUsd", "maxTotalUsd"],
@@ -394,7 +525,7 @@ const V2_DROP_ROWS = [
     },
     {
         path: "subject.topology",
-        applies: (study, routes) => !routes.shared && study.composition.subject.topology !== undefined,
+        applies: (study, routes) => !routes.shared && study.topology !== undefined,
     },
     {
         path: "execution.caps",
@@ -458,15 +589,34 @@ const DROP_ORDER = [
     "review.scorer",
     "personas",
 ];
+/**
+ * The v2 path of a field parseStudyV3 reports in report mode. Each of these keys exists in both
+ * formats: `actor.<key>` is `actors[0].<key>`, a `participants` entry's key is
+ * `actors[0].lanes[].<key>` (field-paths.ts finds it under `roster` when the file has one), `mode`
+ * is `scenario.mode` and `scenario` is `scenario.ref`. Every other path is the same.
+ */
+function v2PathOf(path) {
+    if (path.startsWith("actor."))
+        return `actors[0].${path.slice("actor.".length)}`;
+    if (path.startsWith("participants[]")) {
+        return `actors[0].lanes[]${path.slice("participants[]".length)}`;
+    }
+    if (path === "mode")
+        return "scenario.mode";
+    if (path === "scenario")
+        return "scenario.ref";
+    return path;
+}
 /**
  * The keys migrate drops: the v2-only rows above and `inert`, the fields parseStudyV3 reports the
- * route does not read, then terminal `execution.timeoutMs`, which no terminal code reads. Parents
- * come before their children, so a child under a dropped parent is reported with the parent.
+ * route does not read (v3 paths, mapped back to the file's), then terminal `execution.timeoutMs`,
+ * which no terminal code reads. Parents come before their children, so a child under a dropped
+ * parent is reported with the parent.
  */
 export function droppedPaths(study, inert) {
     const routes = routesOf(study);
     const found = new Set([
-        ...inert,
+        ...inert.map(v2PathOf),
         ...V2_DROP_ROWS.filter((row) => row.applies(study, routes)).map((row) => row.path),
     ]);
     const paths = [

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

@@ -1,56 +1,35 @@
-import type { StudyActor, StudyParticipantEntry, StudyParticipantFocus, StudyParseFailure, StudyV3 } from "../types.js";
+import type { StudyActor, StudyParticipantEntry, 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 = 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<StudyActor, "laneFocus"> | undefined): StudyParticipantFocus | undefined;
-export declare function parseActors(raw: unknown): {
-    ok: true;
-    value: StudyActor[];
-} | StudyParseFailure;
 /** An actor's `type`, which a study route must run. `path` names the actor in messages. */
 export declare function parseActorType(entry: Record<string, unknown>, path: string): {
     ok: true;
     value: string;
 } | StudyParseFailure;
-/** An actor's keys other than `type` and the keys that declare its participants. */
-type ActorFields = Omit<StudyV3["actor"], "type">;
+/** An actor's keys other than `type`. */
+type ActorFields = Omit<StudyActor, "type">;
 /**
- * Every actor key other than `type` and the participant keys. The v2 parser reads them after the
- * participant entries, so a file with errors in both reports the entry first.
+ * Every actor key other than `type`. The parser reads them after the participant entries, so a file
+ * with errors in both reports the entry first.
  */
 export declare function parseActorFields(entry: Record<string, unknown>, path: string): {
     ok: true;
     value: ActorFields;
 } | StudyParseFailure;
-/** The participants a v2 actor declares, which a v3 study declares outside its actor. */
-interface ActorParticipants {
-    readonly count?: number | undefined;
-    readonly entries?: StudyParticipantEntry[] | undefined;
-    readonly instruction?: string | undefined;
-}
-/** A v3 study's actor in the v2 spelling: the actor holds its participants. */
-export declare function withParticipants(actor: StudyV3["actor"], { count, entries, instruction }: ActorParticipants): StudyActor;
-/** A v2 actor without the keys that declare its participants: the actor of a v3 study. */
-export declare function withoutParticipants(actor: StudyActor): StudyV3["actor"];
 /** How a participant list's messages name the list and each entry in it. */
 export interface ParticipantPaths {
     readonly list: string;
     readonly entry: (index: number) => string;
 }
 /**
- * Parse a participant list into a fan-out roster (computer-use E2B route): `actors[index].lanes` in
- * a v2 file, `participants` in a v3 one, each named in messages by `paths`. Structural only:
- * each entry is `{ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?,
- * entry?, host?, reasoningEffort?, stopWhen?, dwell? }`.
+ * Parse a participant list into a fan-out roster (computer-use E2B route): `participants` in a
+ * study, `actors[0].lanes` in the v2 file migrate reads, each named in messages by `paths`.
+ * Structural only: each entry is `{ id?, actorType?, surface?, caseGroup?, persona?, device?,
+ * instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }`.
  * 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 parseStudy where the route is known.
+ * route-scoped cross-validation (device XOR raw resolution, targets, cap 16) runs in parseStudy
+ * where the route is known.
  */
 export declare function parseParticipantEntries(raw: unknown, paths: ParticipantPaths): {
     ok: true;

package/dist/study/parse/actors.js

@@ -4,24 +4,15 @@ import { isMaxOutputTokens } from "../../actors/output-token-limit.js";
 import { isHttpUrl } from "./subject.js";
 import { entryCredentialReason, urlCredentialReason } from "./url-credentials.js";
 import { registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, } from "../routing.js";
-import { invalid, posInt, str } from "./values.js";
+import { invalid, 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 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;
-/** 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 function rosterOf(actor) {
-    return actor?.lanes;
-}
-/** An actor's per-participant focus on the app-url route. The manifest spells it `laneFocus`. */
-export function focusOf(actor) {
-    return actor?.laneFocus;
-}
 // 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.
+// from running on a route that ignores actor.type, such as a this-repo dry run.
 const REMOVED_ACTOR_TYPES = new Set(["pi-agent-core", "claude-agent-sdk"]);
 // 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.
@@ -32,56 +23,6 @@ function routableActorTypes() {
         ...registeredTerminalActors(),
     ];
 }
-export function parseActors(raw) {
-    if (!Array.isArray(raw) || raw.length === 0) {
-        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.
-    if (raw.length > 1) {
-        return invalid("Multiple actors are not supported yet (only the first actor runs); declare a single actor.");
-    }
-    const actors = [];
-    for (const [index, entry] of raw.entries()) {
-        if (!isRecord(entry)) {
-            return invalid(`actors[${index}] must be an object.`);
-        }
-        const path = `actors[${index}]`;
-        const type = parseActorType(entry, path);
-        if (!type.ok)
-            return type;
-        const actor = { type: type.value };
-        const count = posInt(entry.count);
-        if (count !== undefined)
-            actor.count = count;
-        if (entry.lanes !== undefined && entry.roster !== undefined) {
-            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(`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.`);
-        }
-        const rosterResult = entry.roster !== undefined
-            ? parseRosterGroups(entry.roster, index)
-            : parseParticipantEntries(entry.lanes, lanePaths(index));
-        if (!rosterResult.ok) {
-            return rosterResult;
-        }
-        if (rosterResult.value)
-            actor.lanes = rosterResult.value;
-        const fields = parseActorFields(entry, path);
-        if (!fields.ok)
-            return fields;
-        Object.assign(actor, fields.value);
-        const focus = parseFocus(entry.laneFocus);
-        if (focus)
-            actor.laneFocus = focus;
-        actors.push(actor);
-    }
-    return { ok: true, value: actors };
-}
 /** An actor's `type`, which a study route must run. `path` names the actor in messages. */
 export function parseActorType(entry, path) {
     const type = str(entry.type);
@@ -94,8 +35,8 @@ export function parseActorType(entry, path) {
     return { ok: true, value: type };
 }
 /**
- * Every actor key other than `type` and the participant keys. The v2 parser reads them after the
- * participant entries, so a file with errors in both reports the entry first.
+ * Every actor key other than `type`. The parser reads them after the participant entries, so a file
+ * with errors in both reports the entry first.
  */
 export function parseActorFields(entry, path) {
     const actor = {};
@@ -143,101 +84,15 @@ export function parseActorFields(entry, path) {
         actor.tasks = tasksResult.value;
     return { ok: true, value: actor };
 }
-/** A v3 study's actor in the v2 spelling: the actor holds its participants. */
-export function withParticipants(actor, { count, entries, instruction }) {
-    const { type, ...fields } = actor;
-    return {
-        type,
-        ...(count === undefined ? {} : { count }),
-        ...(entries === undefined ? {} : { lanes: entries }),
-        ...fields,
-        ...(instruction === undefined ? {} : { laneFocus: { instruction } }),
-    };
-}
-/** A v2 actor without the keys that declare its participants: the actor of a v3 study. */
-export function withoutParticipants(actor) {
-    const fields = { ...actor };
-    delete fields.count;
-    delete fields.lanes;
-    delete fields.laneFocus;
-    return fields;
-}
-function parseFocus(raw) {
-    if (!isRecord(raw)) {
-        return undefined;
-    }
-    const focus = {};
-    const id = str(raw.id);
-    if (id)
-        focus.id = id;
-    const label = str(raw.label);
-    if (label)
-        focus.label = label;
-    const instruction = str(raw.instruction);
-    if (instruction)
-        focus.instruction = instruction;
-    return Object.keys(focus).length > 0 ? focus : undefined;
-}
-/**
- * Parse `actors[index].roster` compact groups into concrete `lanes[]` entries. This is authoring sugar for
- * "N users of M adapter-owned types across S surfaces"; the runtime receives only `lanes[]`.
- */
-function parseRosterGroups(raw, actorIndex) {
-    if (raw === undefined) {
-        return { ok: true, value: undefined };
-    }
-    if (!Array.isArray(raw) || raw.length === 0) {
-        return invalid(`actors[${actorIndex}].roster must be a non-empty array of group objects ({ id, count, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }) when set.`);
-    }
-    const expanded = [];
-    const seenGroupIds = new Set();
-    for (const [groupIndex, entry] of raw.entries()) {
-        if (!isRecord(entry)) {
-            return invalid(`actors[${actorIndex}].roster[${groupIndex}] must be an object ({ id, count, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }).`);
-        }
-        const groupId = str(entry.id);
-        if (groupId === undefined) {
-            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 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}").`);
-        }
-        seenGroupIds.add(groupId);
-        const count = posInt(entry.count);
-        if (count === undefined) {
-            return invalid(`actors[${actorIndex}].roster[${groupIndex}].count is required and must be a positive integer.`);
-        }
-        const groupEntryInput = { ...entry };
-        delete groupEntryInput.id;
-        delete groupEntryInput.count;
-        for (let i = 1; i <= count; i += 1) {
-            expanded.push({
-                ...groupEntryInput,
-                id: `${groupId}-${String(i).padStart(2, "0")}`,
-            });
-        }
-    }
-    return parseParticipantEntries(expanded, lanePaths(actorIndex));
-}
-// The v2 spelling, `actors[0].lanes[3]`. A roster group's participants are named the same way.
-function lanePaths(actorIndex) {
-    return {
-        list: `actors[${actorIndex}].lanes`,
-        entry: (index) => `actors[${actorIndex}].lanes[${index}]`,
-    };
-}
 /**
- * Parse a participant list into a fan-out roster (computer-use E2B route): `actors[index].lanes` in
- * a v2 file, `participants` in a v3 one, each named in messages by `paths`. Structural only:
- * each entry is `{ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?,
- * entry?, host?, reasoningEffort?, stopWhen?, dwell? }`.
+ * Parse a participant list into a fan-out roster (computer-use E2B route): `participants` in a
+ * study, `actors[0].lanes` in the v2 file migrate reads, each named in messages by `paths`.
+ * Structural only: each entry is `{ id?, actorType?, surface?, caseGroup?, persona?, device?,
+ * instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }`.
  * 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 parseStudy where the route is known.
+ * route-scoped cross-validation (device XOR raw resolution, targets, cap 16) runs in parseStudy
+ * where the route is known.
  */
 export function parseParticipantEntries(raw, paths) {
     if (raw === undefined) {
@@ -415,7 +270,7 @@ function parseDwell(raw, field) {
             ...(whenResult.value === undefined ? {} : { when: whenResult.value }),
             ms,
             everyMs,
-            // oxlint-disable-next-line unicorn/no-thenable -- `then` is the documented dwell field of humanish.lab.v2
+            // oxlint-disable-next-line unicorn/no-thenable -- `then` is the documented dwell field of a study
             then,
         },
     };

package/dist/study/parse/comms.js

@@ -76,9 +76,13 @@ function parseCommsEmail(raw) {
     }
     return { ok: true, value: email };
 }
-/** A real inbox: a saved connection, with optional link and allowed origins and nothing else. */
+/**
+ * A real inbox: a saved connection, with optional link and allowed origins and nothing else. The
+ * parsed config adds `kind: real`, so a config parseStudy returned parses again with it.
+ */
 function parseEmailConnection(raw) {
-    const unsupported = Object.keys(raw).filter((key) => !["connection", "linkOrigin", "allowedOrigins"].includes(key));
+    const unsupported = Object.keys(raw).filter((key) => !["connection", "linkOrigin", "allowedOrigins"].includes(key) &&
+        !(key === "kind" && raw.kind === "real"));
     if (unsupported.length)
         return invalid("An email connection cannot be mixed with capture settings, kind, recipients, or provider options. Use only connection, optional linkOrigin and allowedOrigins.");
     if (typeof raw.connection !== "string" || !/^[a-z][a-z0-9-]{0,47}$/.test(raw.connection))

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

@@ -1,12 +1,17 @@
-import type { StudyParseFailure, StudyDefaults, StudyExecution, StudyPolicies, StudyReview, StudyScenario } from "../types.js";
+import type { StudyCaps, StudyParseFailure, StudyDefaults, StudyExecution, StudyPolicies, StudyReview } 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): {
+/**
+ * Parse a `caps` block's values. Returns a parse failure on a malformed value rather than silently
+ * 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. readStudyFront has checked the
+ * keys against the route; migrate checks a v2 file's two caps blocks with it.
+ */
+export declare function parseCaps(raw: unknown): {
     ok: true;
-    value: StudyScenario | undefined;
+    value: StudyCaps | undefined;
 } | StudyParseFailure;
 export declare function parsePolicies(raw: unknown): {
     ok: true;