humanish 0.110.4 → 0.111.0

package/dist/study/composition-rules.js

@@ -4,13 +4,22 @@
 // a library caller's config itself, under its route's error codes. The planners call the shared
 // checks in study/validation.ts and desktopCliProductReason below. The other subject rules here have
 // planner counterparts whose conditions and wording differ (clone serve and repo, local-tree
-// target, in-process fan-out, loopback targets, scripted scenario.ref).
+// target, in-process fan-out, loopback targets, scripted `scenario`).
 import { isLoopbackUrl } from "./parse/subject.js";
 import { REPO_SLUG_PATTERN } from "./parse/values.js";
 import { declaredTargets } from "./plan-participants.js";
 import { actorResolvesToComputerUse, actorResolvesToScriptedBrowser, actorResolvesToTerminal, computerUseParticipantCount, registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, isComputerUseComposition, } from "./routing.js";
 import { cloneTargetValidationReason, computerUseValidationReason, sharedWorldValidationReason, } from "./validation.js";
 import { actorOf, participantList, declaredParticipantCount, surfaceCount, modeOf, scenarioRefOf, declaresSharedWorld, } from "./study-fields.js";
+/**
+ * The count a scripted or terminal composition reads: its surfaces, or a participant count.
+ * parse/front.ts refuses `participants` on route: scripted and route: terminal, and `surfaces` off
+ * route: scripted, but a study can declare a route its composition does not take, and these rules
+ * run before parseStudy compares the two. migrate's view of a v2 file reaches them the same way.
+ */
+function participantOrSurfaceCount(config) {
+    return declaredParticipantCount(config) ?? surfaceCount(config);
+}
 /** The first composition rule a config breaks, in the parser's order, or null. */
 export function compositionReason(config) {
     return (thisRepoValidationReason(config) ??
@@ -62,7 +71,7 @@ function localAppValidationReason(config) {
             return `actor.type must be a registered computer-use actor for local-app subjects (one of: ${registeredComputerUseActors().join(", ")}); the caller's custom executor runs the computer-use loop. Got "${type}".`;
         }
         if (computerUseParticipantCount(config) > 1) {
-            return "Fan-out to more than one participant is not supported on the in-process/local-app route: fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Set participants to 1 and drop participants (use an app-url or clone subject on execution.target: e2b-desktop for fan-out).";
+            return "Fan-out to more than one participant is not supported on the in-process/local-app route: fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Remove `participants`, or set `participants: 1`. For fan-out, use an app-url or clone subject on execution.target: e2b-desktop.";
         }
         if (participantList(config) !== undefined) {
             return "`participants` (fan-out roster) is not supported on the in-process/local-app route: it provisions one E2B desktop per participant, which this route skips. Use an app-url or clone subject with execution.target: e2b-desktop.";
@@ -88,7 +97,7 @@ function appUrlValidationReason(config) {
             if (!scenarioRefOf(config)) {
                 return "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.";
             }
-            if ((surfaceCount(config) ?? 1) > 2) {
+            if ((participantOrSurfaceCount(config) ?? 1) > 2) {
                 return "A scripted-browser study takes `surfaces` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
             }
             if (config.policies?.redactScreenshots === true) {
@@ -109,9 +118,8 @@ function appUrlValidationReason(config) {
                 return `actor.type must be a registered computer-use actor for app-url × e2b-desktop studies (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
             }
             // Multi-participant fan-out is consumed on this route (`per-lane-worlds`; the shared cua
-            // cross-validation below enforces `lanes`/`count` XOR rules, the 16 cap, and the
-            // per-participant target gates, and the allowPublicTargets+N>1 rejection for ambiguous one-target
-            // fan-out).
+            // cross-validation below enforces the 16 cap, the per-participant target gates, and the
+            // allowPublicTargets+N>1 rejection for ambiguous one-target fan-out).
             // Loopback by default; an owner may declare a public/preview target via policies.
             const targets = [config.subject.appUrl ?? "", ...declaredTargets(config)];
             const unsafeTarget = targets.find((target) => !config.policies?.allowPublicTargets && !isLoopbackUrl(target));
@@ -142,7 +150,9 @@ function scriptedBrowserValidationReason(config) {
         if (!REPO_SLUG_PATTERN.test(repo)) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
-        if (config.subject.topology !== undefined) {
+        // migrate converts a v2 file's `subject.topology: shared-world` to `route: shared-world`, and
+        // refuses it here with the v2 parser's message.
+        if (declaresSharedWorld(config)) {
             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 (config.subject.clone?.fanout !== undefined || config.subject.clone?.keep === true) {
@@ -151,7 +161,7 @@ function scriptedBrowserValidationReason(config) {
         if (!scenarioRefOf(config)) {
             return "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.";
         }
-        if ((surfaceCount(config) ?? 1) > 2) {
+        if ((participantOrSurfaceCount(config) ?? 1) > 2) {
             return "A scripted-browser study takes `surfaces` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
         }
         if (participantList(config) !== undefined) {
@@ -195,8 +205,8 @@ function cloneComputerUseValidationReason(config) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
         // Fan-out is consumed here: N participants each clone the same single repo into their own
-        // E2B desktop (`per-lane-worlds`). The shared cua cross-validation below enforces the
-        // `lanes`/`count` rules and the 16 cap; the single-repo rule above is unchanged.
+        // E2B desktop (`per-lane-worlds`). The shared cua cross-validation below enforces the 16 cap;
+        // the single-repo rule above is unchanged.
     }
     return null;
 }
@@ -262,7 +272,7 @@ function terminalValidationReason(config) {
         if (!actorResolvesToTerminal(type)) {
             return `actor.type must be a registered terminal actor for terminal-product subjects (one of: ${registeredTerminalActors().join(", ")}). Got "${type}".`;
         }
-        if ((declaredParticipantCount(config) ?? 1) > 1) {
+        if ((participantOrSurfaceCount(config) ?? 1) > 1) {
             return "Terminal fan-out to more than one participant is not supported yet; set participants to 1.";
         }
     }

package/dist/study/config.d.ts

@@ -1,22 +1,38 @@
-import { type StudyConfig, type StudyParseResult } from "./types.js";
-/** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
-export declare const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study, which humanish no longer reads. Convert its file with humanish migrate <path>.";
+import { type StudyConfig, type StudyParseFailure, type StudyParseResult } from "./types.js";
 /**
  * The package's study parser (src/index.ts) and the one discovery uses: a humanish.study.v3
  * document. It refuses a humanish.lab.v2 one with HUMANISH_STUDY_V2_UNSUPPORTED.
  */
 export declare function parseStudy(raw: unknown): StudyParseResult;
+interface StudyV3Options {
+    /**
+     * `report`, for `humanish migrate`: list the fields the route does not read in `inert`, in place
+     * of refusing the study for them. A shared world may then give `participants` as a count or
+     * leave it out, as a v2 file could (readStudyFront).
+     */
+    readonly inert?: "refuse" | "report";
+}
+type StudyV3ParseResult = {
+    ok: true;
+    config: StudyConfig;
+    warnings: string[];
+    inert?: string[];
+} | StudyParseFailure;
 /**
- * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
- * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
- * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
- * nothing. The v2 parser's tests call it directly; migrate reads v2 files through migrate/v2.ts.
+ * Validate a humanish.study.v3 document into a StudyConfig. Pure: the caller owns file IO. Fields the
+ * route does not read refuse the study; migrate's report mode lists them in `inert` instead.
  */
-export declare function parseStudyDocument(raw: unknown): StudyParseResult;
+export declare function parseStudyV3(raw: Record<string, unknown>, options?: StudyV3Options): StudyV3ParseResult;
+/** Why runStudy refuses a config before anything runs. */
+interface ConfigRefusal {
+    readonly code: "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID";
+    readonly message: string;
+}
 /**
- * The checks that read more than one section of a parsed config, and the defaults they fill:
- * shared-world `execution.concurrency`, `comms.email.recipients` and the local browser's defaults.
- * parseV2 runs them once every section has parsed. parse/study.ts runs them on its v2 view of a v3
- * study.
+ * Why runStudy refuses a config a library caller passes, or undefined: a humanish.lab.v2 config,
+ * one that still sets a StudyConfig field of humanish 0.110, one with no `actor` object, and one
+ * whose `route` is not the route its subject and actor take, with parseStudy's message. A planner
+ * reads only the v3 fields, so a budget left in `execution.caps` would otherwise run uncapped.
  */
-export declare function checkStudyConfig(config: StudyConfig): StudyParseResult;
+export declare function libraryConfigRefusal(config: StudyConfig): ConfigRefusal | undefined;
+export {};

package/dist/study/config.js

@@ -1,204 +1,224 @@
-// The normalized config, in the humanish.lab.v2 spelling: a study composes code primitives, with no
-// hardcoded study kind.
-// A humanish.study.v3 file is rewritten into this spelling first (parse/study-v3.ts), and then must
-// take the route it declares and set no field that route does not read.
+// The study parser: a humanish.study.v3 document into a StudyConfig with the file's own keys.
+// parse/front.ts checks what the document declares before its sections parse (the route, the
+// actor object, the participants or surfaces form the route takes, and the caps keys it reads). The
+// sections parse here, checkStudyConfig runs the checks that read more than one section, and the
+// study must then take the route it declares and set no field that route does not read
+// (warnings.ts). A humanish.lab.v2 document is refused; `humanish migrate` reads it
+// (migrate/v2.ts).
 //
-// Scope (read before trusting field names): the engine routes by
-// subject.source × execution.target (disambiguated by the actor's run kind where both axes
-// collide) and consumes a deliberately small set of fields:
-//   subject.source/repos/appUrl/serve/env/state/clone.{depth,fanout,keep}, actors[0].count,
-//   execution.target + execution.desktop.codexAppServer, scenario.mode,
-//   policies.redactRepos, defaults.open.
-// On the computer-use routes (app-url × e2b-desktop, and clone × e2b-desktop with a
-// computer-use actor), `actors[0].type` selects the actor: it must resolve to a registered
-// computer-use actor, and that descriptor runs the session. Those routes also consume
-// actors[0].{mission,persona,laneFocus.instruction,model,reasoningEffort}, execution.timeoutMs,
-// execution.desktop.{browser,resolution,sandboxTimeoutMs}, and (clone)
-// subject.{serve,env,state,clone.depth}.
-// On the scripted-browser route (app-url × local-or-absent, or clone × e2b-desktop, with a
-// registered scripted-browser actor), `actors[0].type` selects the actor too, and the route
-// consumes scenario.ref (required there, because the committed scenario's browser steps are what the
-// actor executes), actors[0].{persona,count}, and execution.timeoutMs. On the provisioned
-// clone slice it also consumes subject.{repos,serve,env,state,exposure,clone.depth} and
-// execution.desktop.template. actors[0].{mission,laneFocus,model} are inert on that route
-// because no model runs, and most execution.desktop.* fields remain forward-declared (device
-// presets belong to the computer-use route; scripted surfaces are the driver's own desktop/mobile
-// viewports where isMobile/DSF genuinely render via playwright emulation).
-// On the other routes those fields remain forward-declared and are not yet consumed:
-// parseStudy emits a warning listing any such field that is set, so `study show` shows
-// the truth.
+// Scope (read before trusting field names): routeOf derives the route from
+// subject.source × execution.target × the actor's run kind, with `route: shared-world` as the
+// declaration that turns a computer-use composition into a shared world. On the computer-use
+// routes (app-url × e2b-desktop or local, and clone, local-tree or desktop-cli on e2b-desktop with a
+// computer-use actor), `actor.type` must resolve to a registered computer-use actor, and that
+// descriptor runs the session. Those routes consume actor.{mission,persona,model,reasoningEffort},
+// `participants`, `caps`, execution.timeoutMs and execution.desktop.*. The scripted route
+// (app-url × local, or clone × e2b-desktop, with a registered scripted-browser actor) consumes
+// `scenario` (required: its browser steps are what the actor runs), actor.persona and `surfaces`.
+// The terminal route consumes subject.product, `caps` and execution.{terminal,runtimeAuth}.
 //
-// NOTE on actors[0].count: it carries route-specific meanings. Preview route: simCount;
-// scripted-browser route: surface roster {1 = desktop, 2 = desktop + mobile}, default 1 (the
-// defaults-table single-participant row governs; count: 2 is the declared override); computer-use
-// E2B route: the homogeneous fan-out participant count (N identical participants, each its own E2B
-// desktop), capped at 16; the in-process/local-app computer-use route stays single-participant (no
-// E2B to fan out).
-//
-// NOTE on actors[0].lanes / actors[0].roster (computer-use E2B route): a
-// differentiated fan-out roster: each `{ id?, persona?, device?, instruction?, target? }` becomes one
-// independent E2B desktop (`per-lane-worlds`, the default topology). `roster[]` is parser sugar for
-// repeated groups and is normalized into `lanes[]` before the engine sees it. `lanes|roster` XOR
-// `count` (declare a differentiated roster or a homogeneous count, never both); `lanes|roster`
-// XOR `actors[0].laneFocus` (each entry's `instruction` is the roster's steer); `lanes[].device` XOR
-// raw `execution.desktop.resolution`. `execution.concurrency` bounds in-flight participants (default:
-// the participant count, all at once; env HUMANISH_CUA_MAX_CONCURRENCY may only lower it, per invariant
-// 3). On every non-computer-use route normalized `lanes` are inert (warned). subject.clone.fanout
-// is rejected on the computer-use route. `lanes[].target` is app-url × computer-use only: an
-// absolute browser URL this participant opens instead of `subject.appUrl`; it is the generic
-// setup-produced-target handoff, not a service topology primitive.
-//
-// There is deliberately no v1 compatibility: v1 had zero real users. Breaking schema changes
-// bump the version.
+// NOTE on `participants`: a count (preview: the simulated count; computer use: N identical
+// participants, each its own desktop, capped at 16), `{ count, instruction }` (identical
+// participants with one steer), or a list of `{ id?, persona?, device?, instruction?, target? ... }`
+// entries, each its own desktop. A list entry with a `count` is a group that expands into
+// `<id>-01` to `<id>-NN`. A shared world takes a list of at least two. `participants[].device`
+// excludes a raw `execution.desktop.resolution`, and `participants[].target` is app-url computer
+// use only: an absolute browser URL this participant opens in place of `subject.appUrl`.
+// `execution.concurrency` bounds in-flight participants (default: all at once; env
+// HUMANISH_CUA_MAX_CONCURRENCY may only lower it).
 import { isLocalBrowserStudy, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
 import { isRecord } from "../run/type-guards.js";
 import { compositionReason } from "./composition-rules.js";
-import { findUnknownV2Key } from "./keys.js";
-import { parseActors, rosterOf } from "./parse/actors.js";
+import { V2_SCHEMA, V2_UNSUPPORTED_MESSAGE, v2FieldMoves } from "./migrate/v2.js";
+import { parseActorFields, parseActorType, parseParticipantEntries } from "./parse/actors.js";
 import { parseComms, recipientParticipantId } from "./parse/comms.js";
-import { parseDefaults, parseExecution, parsePersonas, parsePolicies, parseReview, parseScenario, } from "./parse/execution.js";
-import { studySpelling, studyToV2 } from "./parse/study-v3.js";
+import { parseCaps, parseDefaults, parseExecution, parsePolicies, parseReview, } from "./parse/execution.js";
+import { ACTOR_REQUIRED, readStudyFront, routeNameReason, } from "./parse/front.js";
 import { parseSubject } from "./parse/subject.js";
 import { invalid, optionalStr, str } from "./parse/values.js";
 import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
-import { ID_PATTERN, V2_SCHEMA, STUDY_SCHEMA, } from "./types.js";
-import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, smtpValidationReason, taskProtocolValidationReason, } from "./validation.js";
-import { forwardDeclaredWarnings, inertFieldLabels } from "./warnings.js";
+import { declaredParticipantCount, participantList } from "./study-fields.js";
+import { ID_PATTERN, STUDY_SCHEMA, } from "./types.js";
+import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, smtpValidationReason, taskProtocolValidationReason, } from "./validation.js";
+import { forwardDeclaredWarnings, inertFieldLabels, inertFieldPaths } from "./warnings.js";
 import { plural } from "../run/text.js";
-/** 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 package's study parser (src/index.ts) and the one discovery uses: a humanish.study.v3
  * document. It refuses a humanish.lab.v2 one with HUMANISH_STUDY_V2_UNSUPPORTED.
  */
 export function parseStudy(raw) {
-    if (isRecord(raw) && raw.schema === V2_SCHEMA)
+    if (!isRecord(raw))
+        return invalid("A study file must be a YAML object.");
+    if (raw.schema === V2_SCHEMA)
         return {
             ok: false,
             error: { code: "HUMANISH_STUDY_V2_UNSUPPORTED", message: V2_UNSUPPORTED_MESSAGE },
         };
-    return parseStudyDocument(raw);
-}
-/**
- * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
- * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
- * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
- * nothing. The v2 parser's tests call it directly; migrate reads v2 files through migrate/v2.ts.
- */
-export function parseStudyDocument(raw) {
-    if (!isRecord(raw)) {
-        return invalid("A study file must be a YAML object.");
-    }
-    if (raw.schema === STUDY_SCHEMA)
-        return parseV3(raw);
-    if (raw.schema !== V2_SCHEMA) {
+    if (raw.schema !== STUDY_SCHEMA) {
         return invalid(`The study schema must be ${STUDY_SCHEMA} or ${V2_SCHEMA}.`);
     }
-    return parseV2(raw);
+    return parseStudyV3(raw);
 }
 /**
- * A v3 study parses through the v2 parser, then must take the route it declares and set no field
- * that route does not read. A v2 file gets those fields as a warning instead.
+ * Validate a humanish.study.v3 document into a StudyConfig. Pure: the caller owns file IO. Fields the
+ * route does not read refuse the study; migrate's report mode lists them in `inert` instead.
  */
-function parseV3(raw) {
-    const document = studyToV2(raw);
-    if (!document.ok)
-        return document;
-    const { route, v2, participantSource } = document.value;
-    const spell = (message) => studySpelling(message, route, participantSource);
-    const parsed = parseV2(v2);
-    if (!parsed.ok)
-        return invalid(spell(parsed.error.message));
-    const taken = routeOf(parsed.config);
-    if (taken !== route) {
-        return invalid(`This study declares route: ${route}, but its subject (source: ${parsed.config.subject.source}) and actor (type: ${parsed.config.actors[0]?.type}) take the ${taken} route. Change \`route\`, or change the subject or actor.`);
+export function parseStudyV3(raw, options = {}) {
+    const front = readStudyFront(raw, options.inert === "report");
+    if (!front.ok)
+        return front;
+    const study = parseSections(raw, front.value);
+    if (!study.ok)
+        return study;
+    const checked = checkStudyConfig(study.value);
+    if (!checked.ok)
+        return checked;
+    const { config, warnings } = checked;
+    const { route } = config;
+    const mismatch = routeMismatchReason(config);
+    if (mismatch)
+        return invalid(mismatch);
+    if (options.inert === "report") {
+        return { ok: true, config, warnings, inert: inertFieldPaths(config) };
     }
-    const inert = inertFieldLabels(parsed.config);
+    const inert = inertFieldLabels(config);
     if (inert.length > 0) {
-        return invalid(spell(`route: ${route} does not read ${inert.join(", ")}. Remove ${inert.length === 1 ? "it" : "them"}.`));
+        return invalid(`route: ${route} does not read ${inert.join(", ")}. Remove ${inert.length === 1 ? "it" : "them"}.`);
     }
-    return {
-        ok: true,
-        config: { ...parsed.config, schema: STUDY_SCHEMA },
-        warnings: parsed.warnings.map(spell),
-    };
+    return { ok: true, config, warnings };
+}
+/** Why a config's declared route is not the one its subject and actor take, or undefined. */
+function routeMismatchReason(config) {
+    const taken = routeOf(config);
+    if (taken === config.route)
+        return undefined;
+    return `This study declares route: ${config.route}, but its subject (source: ${config.subject.source}) and actor (type: ${config.actor.type}) take the ${taken} route. Change \`route\`, or change the subject or actor.`;
+}
+/**
+ * Why runStudy refuses a config a library caller passes, or undefined: a humanish.lab.v2 config,
+ * one that still sets a StudyConfig field of humanish 0.110, one with no `actor` object, and one
+ * whose `route` is not the route its subject and actor take, with parseStudy's message. A planner
+ * reads only the v3 fields, so a budget left in `execution.caps` would otherwise run uncapped.
+ */
+export function libraryConfigRefusal(config) {
+    const raw = config;
+    if (!isRecord(raw))
+        return undefined;
+    if (raw.schema === V2_SCHEMA)
+        return { code: "HUMANISH_STUDY_V2_UNSUPPORTED", message: V2_UNSUPPORTED_MESSAGE };
+    const moves = v2FieldMoves(raw);
+    if (moves.length > 0)
+        return {
+            code: "HUMANISH_STUDY_V2_UNSUPPORTED",
+            message: `This StudyConfig sets fields that humanish 0.111.0 renamed: ${moves.join("; ")}. Set the humanish.study.v3 fields, or parse the study file with parseStudy. The 0.111.0 release notes list each renamed field.`,
+        };
+    if (!isRecord(raw.actor))
+        return { code: "HUMANISH_STUDY_INVALID", message: ACTOR_REQUIRED };
+    const message = routeNameReason(raw.route) ?? routeMismatchReason(config);
+    return message === undefined ? undefined : { code: "HUMANISH_STUDY_INVALID", message };
 }
-function parseV2(raw) {
-    const unknownKey = findUnknownV2Key(raw);
-    if (unknownKey)
-        return invalid(unknownKey);
+// Each section in a fixed order, so a file with more than one error always reports the same one
+// first. migrate's checkV2 reads a v2 file's sections in this order too.
+function parseSections(raw, front) {
     const id = str(raw.id);
     if (!id || !ID_PATTERN.test(id)) {
         return invalid("The study id must be a public-safe token starting with a letter or digit (/^[A-Za-z0-9][A-Za-z0-9_.-]*$/).");
     }
-    const subjectResult = parseSubject(raw.subject);
-    if (!subjectResult.ok) {
-        return subjectResult;
-    }
-    const actorsResult = parseActors(raw.actors);
-    if (!actorsResult.ok) {
-        return actorsResult;
-    }
-    const executionResult = parseExecution(raw.execution);
-    if (!executionResult.ok) {
-        return executionResult;
-    }
-    const config = {
-        schema: V2_SCHEMA,
-        id,
-        ...optionalStr("title", raw.title),
-        ...optionalStr("description", raw.description),
-        subject: subjectResult.value,
-        actors: actorsResult.value,
-        ...(executionResult.value ? { execution: executionResult.value } : {}),
-    };
-    const personas = parsePersonas(raw.personas);
-    if (personas)
-        config.personas = personas;
-    const scenarioResult = parseScenario(raw.scenario);
-    if (!scenarioResult.ok) {
-        return scenarioResult;
-    }
-    if (scenarioResult.value)
-        config.scenario = scenarioResult.value;
+    const subject = parseSubject(raw.subject);
+    if (!subject.ok)
+        return subject;
+    const type = parseActorType(front.actor, "actor");
+    if (!type.ok)
+        return type;
+    const participants = parseParticipants(raw.participants, front.participants);
+    if (!participants.ok)
+        return participants;
+    const fields = parseActorFields(front.actor, "actor");
+    if (!fields.ok)
+        return fields;
+    const execution = parseExecution(raw.execution);
+    if (!execution.ok)
+        return execution;
+    const caps = parseCaps(raw.caps);
+    if (!caps.ok)
+        return caps;
     if (isRecord(raw.policies) &&
         raw.policies.mediaPermission !== undefined &&
         raw.policies.mediaPermission !== "prompt" &&
         raw.policies.mediaPermission !== "granted") {
         return invalid("`policies.mediaPermission` must be `prompt` (the participant answers the browser's own dialog) or `granted`.");
     }
-    const policiesResult = parsePolicies(raw.policies);
-    if (!policiesResult.ok)
-        return policiesResult;
-    if (policiesResult.value)
-        config.policies = policiesResult.value;
-    const reviewResult = parseReview(raw.review);
-    if (!reviewResult.ok)
-        return reviewResult;
-    if (reviewResult.value)
-        config.review = reviewResult.value;
-    if (raw.defaults !== undefined && isRecord(raw.defaults) && raw.defaults.open !== undefined) {
+    const policies = parsePolicies(raw.policies);
+    if (!policies.ok)
+        return policies;
+    const review = parseReview(raw.review);
+    if (!review.ok)
+        return review;
+    if (isRecord(raw.defaults) && raw.defaults.open !== undefined) {
         if (typeof raw.defaults.open !== "boolean")
             return invalid("`defaults.open` must be true or false.");
     }
     const defaults = parseDefaults(raw.defaults);
-    if (defaults)
-        config.defaults = defaults;
-    const commsResult = parseComms(raw.comms);
-    if (!commsResult.ok)
-        return commsResult;
-    if (commsResult.value)
-        config.comms = commsResult.value;
-    return checkStudyConfig(config);
+    const comms = parseComms(raw.comms);
+    if (!comms.ok)
+        return comms;
+    const mode = raw.mode === "dry-run" || raw.mode === "live" ? raw.mode : undefined;
+    const { surfaces } = front;
+    const scenario = str(raw.scenario);
+    return {
+        ok: true,
+        value: {
+            schema: STUDY_SCHEMA,
+            id,
+            ...optionalStr("title", raw.title),
+            ...optionalStr("description", raw.description),
+            route: front.route,
+            ...(mode === undefined ? {} : { mode }),
+            subject: subject.value,
+            actor: { type: type.value, ...fields.value },
+            ...(participants.value === undefined ? {} : { participants: participants.value }),
+            ...(surfaces === undefined ? {} : { surfaces }),
+            ...(caps.value === undefined ? {} : { caps: caps.value }),
+            ...(execution.value === undefined ? {} : { execution: execution.value }),
+            ...(scenario === undefined ? {} : { scenario }),
+            ...(policies.value === undefined ? {} : { policies: policies.value }),
+            ...(review.value === undefined ? {} : { review: review.value }),
+            ...(defaults === undefined ? {} : { defaults }),
+            ...(comms.value === undefined ? {} : { comms: comms.value }),
+        },
+    };
+}
+// `participants` in the form the file wrote it. readStudyFront has checked the form against the
+// route and expanded each list entry that has a count; the entries parse here, each named by the
+// `participants` entry it came from. An instruction that is not a non-empty string is dropped, as
+// the v2 parser drops it.
+function parseParticipants(raw, read) {
+    if (read.entries !== undefined) {
+        const { source } = read;
+        return parseParticipantEntries(read.entries, {
+            list: "participants",
+            entry: (index) => `participants[${source[index] ?? index}]`,
+        });
+    }
+    if (typeof raw === "number")
+        return { ok: true, value: read.count };
+    if (!isRecord(raw))
+        return { ok: true, value: undefined };
+    const instruction = str(read.instruction);
+    return {
+        ok: true,
+        value: {
+            ...(read.count === undefined ? {} : { count: read.count }),
+            ...(instruction === undefined ? {} : { instruction }),
+        },
+    };
 }
 /**
  * The checks that read more than one section of a parsed config, and the defaults they fill:
  * shared-world `execution.concurrency`, `comms.email.recipients` and the local browser's defaults.
- * parseV2 runs them once every section has parsed. parse/study.ts runs them on its v2 view of a v3
- * study.
  */
-export function checkStudyConfig(config) {
+function checkStudyConfig(config) {
     const smtpReason = smtpValidationReason(config);
     if (smtpReason)
         return invalid(smtpReason);
@@ -208,9 +228,6 @@ export function checkStudyConfig(config) {
     const outputLimitReason = outputTokenLimitValidationReason(config);
     if (outputLimitReason)
         return invalid(outputLimitReason);
-    const scenarioCapsReason = scenarioCapsValidationReason(config);
-    if (scenarioCapsReason)
-        return invalid(scenarioCapsReason);
     // All-parallel default: a multi-participant study that does not declare execution.concurrency
     // runs every participant at once; the declared field is a cap the author chose, never a mode.
     // Independent computer-use participants resolve that default from the final participant count
@@ -218,7 +235,7 @@ export function checkStudyConfig(config) {
     // world's roster is fixed, so its default is filled here for the envelopes and warnings that read
     // the parsed config.
     {
-        const participantCount = rosterOf(config.actors[0])?.length ?? config.actors[0]?.count ?? 1;
+        const participantCount = participantList(config)?.length ?? declaredParticipantCount(config) ?? 1;
         if (participantCount > 1 &&
             config.execution?.concurrency === undefined &&
             isSharedWorldComposition(config)) {

package/dist/study/discover.d.ts

@@ -1,5 +1,5 @@
 import type { ActorPersonaRef } from "../actors/contract.js";
-import { type StudyConfig } from "./types.js";
+import type { StudyConfig } from "./types.js";
 declare const STUDY_LIST_SCHEMA = "humanish.study-list.v1";
 declare const STUDY_SHOW_SCHEMA = "humanish.study-show.v1";
 type StudyOrigin = "committed" | "ignored" | "explicit";

package/dist/study/discover.js

@@ -5,7 +5,7 @@ import { lstat, open, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { parse } from "yaml";
 import { parseStudy } from "./config.js";
-import { V2_SCHEMA } from "./types.js";
+import { V2_SCHEMA } from "./migrate/v2.js";
 import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
 import { isNodeError } from "../run/type-guards.js";
 import { studyFileCandidates, STUDY_DIRECTORIES } from "./files.js";