humanish 0.110.3 → 0.111.0

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,187 +23,98 @@ 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 type = str(entry.type);
-        if (!type) {
-            return invalid(`actors[${index}].type is required.`);
-        }
-        if (REMOVED_ACTOR_TYPES.has(type)) {
-            return invalid(`actors[${index}].type "${type}" is no longer a humanish actor. Use an actor a study route runs (one of: ${routableActorTypes().join(", ")}). To drive a study with a signed-in Claude Code, use type: local-agent with localAgent: claude.`);
-        }
-        const actor = { type };
-        const count = posInt(entry.count);
-        if (count !== undefined)
-            actor.count = count;
-        if (entry.lanes !== undefined && entry.roster !== undefined) {
-            return invalid(`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, index);
-        if (!rosterResult.ok) {
-            return rosterResult;
-        }
-        if (rosterResult.value)
-            actor.lanes = rosterResult.value;
-        const persona = str(entry.persona);
-        if (persona)
-            actor.persona = persona;
-        const mission = str(entry.mission);
-        if (mission)
-            actor.mission = mission;
-        const model = str(entry.model);
-        if (model)
-            actor.model = model;
-        if (entry.maxOutputTokens !== undefined) {
-            if (!isMaxOutputTokens(entry.maxOutputTokens))
-                return invalid(`actors[${index}].maxOutputTokens must be a positive safe integer.`);
-            actor.maxOutputTokens = entry.maxOutputTokens;
-        }
-        const localAgent = str(entry.localAgent);
-        if (entry.localAgent !== undefined) {
-            if (localAgent !== "codex" && localAgent !== "claude") {
-                return invalid(`actors[${index}].localAgent must be "codex" or "claude" (the locally signed-in CLI that drives the study).`);
-            }
-            actor.localAgent = localAgent;
-        }
-        if (entry.reasoningEffort !== undefined) {
-            if (!isReasoningEffort(entry.reasoningEffort)) {
-                return invalid(`actors[${index}].reasoningEffort must be one of: ${reasoningEffortNames()}. Support is model-dependent, so a level this model does not accept fails on the first turn rather than being silently downgraded.`);
-            }
-            actor.reasoningEffort = entry.reasoningEffort;
-        }
-        const stopWhenResult = parseStopWhen(entry.stopWhen, `actors[${index}].stopWhen`);
-        if (!stopWhenResult.ok)
-            return stopWhenResult;
-        if (stopWhenResult.value !== undefined)
-            actor.stopWhen = stopWhenResult.value;
-        const dwellResult = parseDwell(entry.dwell, `actors[${index}].dwell`);
-        if (!dwellResult.ok)
-            return dwellResult;
-        if (dwellResult.value !== undefined)
-            actor.dwell = dwellResult.value;
-        const tasksResult = parseTasks(entry.tasks, `actors[${index}].tasks`);
-        if (!tasksResult.ok)
-            return tasksResult;
-        if (tasksResult.value !== undefined)
-            actor.tasks = tasksResult.value;
-        const focus = parseFocus(entry.laneFocus);
-        if (focus)
-            actor.laneFocus = focus;
-        actors.push(actor);
+/** 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);
+    if (!type) {
+        return invalid(`${path}.type is required.`);
     }
-    return { ok: true, value: actors };
-}
-function parseFocus(raw) {
-    if (!isRecord(raw)) {
-        return undefined;
+    if (REMOVED_ACTOR_TYPES.has(type)) {
+        return invalid(`${path}.type "${type}" is no longer a humanish actor. Use an actor a study route runs (one of: ${routableActorTypes().join(", ")}). To drive a study with a signed-in Claude Code, use type: local-agent with localAgent: claude.`);
     }
-    const 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;
+    return { ok: true, value: type };
 }
 /**
- * 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[]`.
+ * 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.
  */
-function parseRosterGroups(raw, actorIndex) {
-    if (raw === undefined) {
-        return { ok: true, value: undefined };
+export function parseActorFields(entry, path) {
+    const actor = {};
+    const persona = str(entry.persona);
+    if (persona)
+        actor.persona = persona;
+    const mission = str(entry.mission);
+    if (mission)
+        actor.mission = mission;
+    const model = str(entry.model);
+    if (model)
+        actor.model = model;
+    if (entry.maxOutputTokens !== undefined) {
+        if (!isMaxOutputTokens(entry.maxOutputTokens))
+            return invalid(`${path}.maxOutputTokens must be a positive safe integer.`);
+        actor.maxOutputTokens = entry.maxOutputTokens;
     }
-    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 localAgent = str(entry.localAgent);
+    if (entry.localAgent !== undefined) {
+        if (localAgent !== "codex" && localAgent !== "claude") {
+            return invalid(`${path}.localAgent must be "codex" or "claude" (the locally signed-in CLI that drives the study).`);
         }
-        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")}`,
-            });
+        actor.localAgent = localAgent;
+    }
+    if (entry.reasoningEffort !== undefined) {
+        if (!isReasoningEffort(entry.reasoningEffort)) {
+            return invalid(`${path}.reasoningEffort must be one of: ${reasoningEffortNames()}. Support is model-dependent, so a level this model does not accept fails on the first turn rather than being silently downgraded.`);
         }
+        actor.reasoningEffort = entry.reasoningEffort;
     }
-    return parseParticipantEntries(expanded, actorIndex);
+    const stopWhenResult = parseStopWhen(entry.stopWhen, `${path}.stopWhen`);
+    if (!stopWhenResult.ok)
+        return stopWhenResult;
+    if (stopWhenResult.value !== undefined)
+        actor.stopWhen = stopWhenResult.value;
+    const dwellResult = parseDwell(entry.dwell, `${path}.dwell`);
+    if (!dwellResult.ok)
+        return dwellResult;
+    if (dwellResult.value !== undefined)
+        actor.dwell = dwellResult.value;
+    const tasksResult = parseTasks(entry.tasks, `${path}.tasks`);
+    if (!tasksResult.ok)
+        return tasksResult;
+    if (tasksResult.value !== undefined)
+        actor.tasks = tasksResult.value;
+    return { ok: true, value: actor };
 }
 /**
- * Parse `actors[index].lanes` into a fan-out roster (computer-use E2B route). 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.
  */
-function parseParticipantEntries(raw, actorIndex) {
+export function parseParticipantEntries(raw, paths) {
     if (raw === undefined) {
         return { ok: true, value: undefined };
     }
     if (!Array.isArray(raw) || raw.length === 0) {
-        return invalid(`actors[${actorIndex}].lanes must be a non-empty array of participant objects ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }) when set.`);
+        return invalid(`${paths.list} must be a non-empty array of participant objects ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }) when set.`);
     }
     const entries = [];
     const seenIds = new Set();
     for (const [entryIndex, entry] of raw.entries()) {
         if (!isRecord(entry)) {
-            return invalid(`actors[${actorIndex}].lanes[${entryIndex}] must be an object ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }).`);
+            return invalid(`${paths.entry(entryIndex)} must be an object ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }).`);
         }
         const parsedEntry = {};
         const id = str(entry.id);
         if (id !== undefined) {
             if (!PARTICIPANT_ID_PATTERN.test(id) || id.length > PARTICIPANT_ID_MAX_CHARS) {
-                return invalid(`actors[${actorIndex}].lanes[${entryIndex}].id must be a public-safe token matching ${PARTICIPANT_ID_PATTERN} and at most ${PARTICIPANT_ID_MAX_CHARS} chars (it names the participant's evidence paths); got "${id}".`);
+                return invalid(`${paths.entry(entryIndex)}.id must be a public-safe token matching ${PARTICIPANT_ID_PATTERN} and at most ${PARTICIPANT_ID_MAX_CHARS} chars (it names the participant's evidence paths); got "${id}".`);
             }
             if (seenIds.has(id)) {
-                return invalid(`actors[${actorIndex}].lanes ids must be unique (duplicate "${id}").`);
+                return invalid(`${paths.list} ids must be unique (duplicate "${id}").`);
             }
             seenIds.add(id);
             parsedEntry.id = id;
@@ -220,24 +122,24 @@ function parseParticipantEntries(raw, actorIndex) {
         const device = str(entry.device);
         if (device !== undefined) {
             if (!isDevicePresetName(device)) {
-                return invalid(`actors[${actorIndex}].lanes[${entryIndex}].device must be one of: ${DEVICE_PRESET_NAMES.join(", ")}.`);
+                return invalid(`${paths.entry(entryIndex)}.device must be one of: ${DEVICE_PRESET_NAMES.join(", ")}.`);
             }
             parsedEntry.device = device;
         }
         const persona = str(entry.persona);
         if (persona !== undefined)
             parsedEntry.persona = persona;
-        const actorType = parseEntryMetadata(entry.actorType, `actors[${actorIndex}].lanes[${entryIndex}].actorType`);
+        const actorType = parseEntryMetadata(entry.actorType, `${paths.entry(entryIndex)}.actorType`);
         if (!actorType.ok)
             return actorType;
         if (actorType.value !== undefined)
             parsedEntry.actorType = actorType.value;
-        const surface = parseEntryMetadata(entry.surface, `actors[${actorIndex}].lanes[${entryIndex}].surface`);
+        const surface = parseEntryMetadata(entry.surface, `${paths.entry(entryIndex)}.surface`);
         if (!surface.ok)
             return surface;
         if (surface.value !== undefined)
             parsedEntry.surface = surface.value;
-        const caseGroup = parseEntryMetadata(entry.caseGroup, `actors[${actorIndex}].lanes[${entryIndex}].caseGroup`);
+        const caseGroup = parseEntryMetadata(entry.caseGroup, `${paths.entry(entryIndex)}.caseGroup`);
         if (!caseGroup.ok)
             return caseGroup;
         if (caseGroup.value !== undefined)
@@ -245,28 +147,28 @@ function parseParticipantEntries(raw, actorIndex) {
         const instruction = str(entry.instruction);
         if (instruction !== undefined)
             parsedEntry.instruction = instruction;
-        const stopWhenResult = parseStopWhen(entry.stopWhen, `actors[${actorIndex}].lanes[${entryIndex}].stopWhen`);
+        const stopWhenResult = parseStopWhen(entry.stopWhen, `${paths.entry(entryIndex)}.stopWhen`);
         if (!stopWhenResult.ok)
             return stopWhenResult;
         if (stopWhenResult.value !== undefined)
             parsedEntry.stopWhen = stopWhenResult.value;
-        const dwellResult = parseDwell(entry.dwell, `actors[${actorIndex}].lanes[${entryIndex}].dwell`);
+        const dwellResult = parseDwell(entry.dwell, `${paths.entry(entryIndex)}.dwell`);
         if (!dwellResult.ok)
             return dwellResult;
         if (dwellResult.value !== undefined)
             parsedEntry.dwell = dwellResult.value;
         if (entry.reasoningEffort !== undefined) {
             if (!isReasoningEffort(entry.reasoningEffort)) {
-                return invalid(`actors[${actorIndex}].lanes[${entryIndex}].reasoningEffort must be one of: ${reasoningEffortNames()}. Support is model-dependent, so a level this model does not accept fails on the first turn rather than being silently downgraded.`);
+                return invalid(`${paths.entry(entryIndex)}.reasoningEffort must be one of: ${reasoningEffortNames()}. Support is model-dependent, so a level this model does not accept fails on the first turn rather than being silently downgraded.`);
             }
             parsedEntry.reasoningEffort = entry.reasoningEffort;
         }
         const target = str(entry.target);
         if (target !== undefined) {
             if (!isHttpUrl(target)) {
-                return invalid(`actors[${actorIndex}].lanes[${entryIndex}].target must be an absolute http(s) URL.`);
+                return invalid(`${paths.entry(entryIndex)}.target must be an absolute http(s) URL.`);
             }
-            const credential = urlCredentialReason(`actors[${actorIndex}].lanes[${entryIndex}].target`, target);
+            const credential = urlCredentialReason(`${paths.entry(entryIndex)}.target`, target);
             if (credential)
                 return invalid(credential);
             parsedEntry.target = target;
@@ -275,7 +177,7 @@ function parseParticipantEntries(raw, actorIndex) {
         // it runs in sharedWorldValidationReason (where the route + serve.url are known).
         const entryPath = str(entry.entry);
         if (entryPath !== undefined) {
-            const credential = entryCredentialReason(`actors[${actorIndex}].lanes[${entryIndex}].entry`, entryPath);
+            const credential = entryCredentialReason(`${paths.entry(entryIndex)}.entry`, entryPath);
             if (credential)
                 return invalid(credential);
             parsedEntry.entry = entryPath;
@@ -284,7 +186,7 @@ function parseParticipantEntries(raw, actorIndex) {
         // exactly-one-host check runs in externalPublicSharedWorldValidationReason (route context).
         if (entry.host !== undefined) {
             if (typeof entry.host !== "boolean") {
-                return invalid(`actors[${actorIndex}].lanes[${entryIndex}].host must be a boolean (marks the designated host participant on the external-public shared-world route).`);
+                return invalid(`${paths.entry(entryIndex)}.host must be a boolean (marks the designated host participant on the external-public shared-world route).`);
             }
             if (entry.host)
                 parsedEntry.host = true;
@@ -368,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;

package/dist/study/parse/execution.js

@@ -33,14 +33,6 @@ 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
-    // error, never silently dropped (a cap that silently does nothing would be a safety lie).
-    const capsResult = parseCaps(raw.caps);
-    if (!capsResult.ok) {
-        return capsResult;
-    }
-    if (capsResult.value)
-        execution.caps = capsResult.value;
     const terminalResult = parseTerminal(raw.terminal);
     if (!terminalResult.ok) {
         return terminalResult;
@@ -217,45 +209,18 @@ function parseDesktop(raw) {
     }
     return { ok: true, value: Object.keys(desktop).length > 0 ? desktop : undefined };
 }
-export function parsePersonas(raw) {
-    if (!Array.isArray(raw)) {
-        return undefined;
-    }
-    const personas = raw.filter(isRecord);
-    return personas.length > 0 ? personas : undefined;
-}
-export function parseScenario(raw) {
-    if (!isRecord(raw)) {
-        return { ok: true, value: undefined };
-    }
-    const scenario = {};
-    const ref = str(raw.ref);
-    if (ref)
-        scenario.ref = ref;
-    if (isRecord(raw.inline))
-        scenario.inline = raw.inline;
-    const mode = str(raw.mode);
-    if (mode === "dry-run" || mode === "live")
-        scenario.mode = mode;
-    const capsResult = parseCaps(raw.caps);
-    if (!capsResult.ok) {
-        return capsResult;
-    }
-    if (capsResult.value)
-        scenario.caps = capsResult.value;
-    return { ok: true, value: Object.keys(scenario).length > 0 ? scenario : undefined };
-}
 /**
- * Parse `scenario.caps`. Returns a parse failure on a malformed value rather than silently
+ * 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.
+ * 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.
  */
-function parseCaps(raw) {
+export function parseCaps(raw) {
     if (raw === undefined) {
         return { ok: true, value: undefined };
     }
     if (!isRecord(raw)) {
-        return invalid("`scenario.caps` must be an object ({ maxUsd?, maxTotalUsd?, maxJobs?, maxMinutes? }).");
+        return invalid("`caps` must be an object ({ maxUsd?, maxTotalUsd?, maxJobs?, maxMinutes? }).");
     }
     const caps = {};
     for (const key of ["maxUsd", "maxTotalUsd", "maxJobs", "maxMinutes"]) {
@@ -263,7 +228,7 @@ function parseCaps(raw) {
             continue;
         const value = nonNegNumber(raw[key]);
         if (value === undefined) {
-            return invalid(`\`scenario.caps.${key}\` must be a non-negative number.`);
+            return invalid(`\`caps.${key}\` must be a non-negative number.`);
         }
         caps[key] = value;
     }

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

@@ -0,0 +1,36 @@
+import type { StudyRoute } from "../routing.js";
+import type { StudyParseFailure, StudySurfaces } from "../types.js";
+/** A document's `participants`, read before the participant entries parse. */
+export interface Participants {
+    count?: number;
+    instruction?: unknown;
+    /** The list entries, with each entry that has a count expanded into its participants. */
+    entries?: unknown[];
+    /** For each expanded entry, the index of the `participants` entry it came from. */
+    source: number[];
+}
+/** What a v3 document declares before its sections parse. */
+export interface StudyFront {
+    readonly route: StudyRoute;
+    readonly actor: Record<string, unknown>;
+    readonly participants: Participants;
+    readonly surfaces: StudySurfaces | undefined;
+}
+type Parsed<T> = {
+    ok: true;
+    value: T;
+} | StudyParseFailure;
+/** The refusal for a study with no `actor` object. */
+export declare const ACTOR_REQUIRED = "A study needs `actor:`, an object with at least `type`.";
+/** Why `route` is not a route a study can declare, or undefined when it is one. */
+export declare function routeNameReason(route: unknown): string | undefined;
+/**
+ * The checks a v3 document passes before its sections parse: no v2 key and no unknown key, a
+ * route, a mode, an `actor` object, a scenario string, and the `participants`, `surfaces` and
+ * `caps` keys its route takes. `anySharedWorldParticipants`, for migrate's v3 form of a v2 file:
+ * a shared world takes `participants` in every form computer use takes, or none, because a v2
+ * shared world could declare a count or no list. The shared-world checks then refuse it, as the v2
+ * parser does.
+ */
+export declare function readStudyFront(raw: Record<string, unknown>, anySharedWorldParticipants?: boolean): Parsed<StudyFront>;
+export {};