humanish 0.110.2 → 0.110.4

package/dist/study/parse/actors.js

@@ -46,14 +46,11 @@ export function parseActors(raw) {
         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 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;
@@ -68,54 +65,16 @@ export function parseActors(raw) {
         }
         const rosterResult = entry.roster !== undefined
             ? parseRosterGroups(entry.roster, index)
-            : parseParticipantEntries(entry.lanes, index);
+            : parseParticipantEntries(entry.lanes, lanePaths(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 fields = parseActorFields(entry, path);
+        if (!fields.ok)
+            return fields;
+        Object.assign(actor, fields.value);
         const focus = parseFocus(entry.laneFocus);
         if (focus)
             actor.laneFocus = focus;
@@ -123,6 +82,86 @@ export function parseActors(raw) {
     }
     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);
+    if (!type) {
+        return invalid(`${path}.type is required.`);
+    }
+    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.`);
+    }
+    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.
+ */
+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;
+    }
+    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).`);
+        }
+        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;
+    }
+    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 };
+}
+/** 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;
@@ -181,10 +220,18 @@ function parseRosterGroups(raw, actorIndex) {
             });
         }
     }
-    return parseParticipantEntries(expanded, actorIndex);
+    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 `actors[index].lanes` into a fan-out roster (computer-use E2B route). Structural only:
+ * 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? }`.
  * Participant ids (when declared) must be public-safe path tokens and unique; grouping metadata
@@ -192,27 +239,27 @@ function parseRosterGroups(raw, actorIndex) {
  * route-scoped cross-validation (`lanes` XOR `count`/`laneFocus`, device XOR raw resolution, 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 +267,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 +292,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 +322,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 +331,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;

package/dist/study/parse/execution.js

@@ -255,7 +255,7 @@ function parseCaps(raw) {
         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 +263,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/study-v3.d.ts

@@ -7,12 +7,38 @@ export interface StudyDocument {
     /** For each expanded participant, the index of the `participants` entry it came from. */
     readonly participantSource: readonly number[];
 }
+/** 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;
+    /** The scripted surfaces as a count: 1 is desktop, 2 adds mobile. */
+    readonly surfaces: number | undefined;
+}
 type Parsed<T> = {
     ok: true;
     value: T;
 } | StudyParseFailure;
 /** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
 export declare function studyToV2(raw: Record<string, unknown>): Parsed<StudyDocument>;
+/**
+ * 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>;
 /**
  * Spell a v2 parser message the way the study file is written: `actors[0].lanes[3]` becomes the
  * `participants` entry it came from, `execution.caps` and `scenario.caps` become `caps`, and so on.

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

@@ -26,46 +26,18 @@ const CAPS_KEYS = {
 };
 /** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
 export function studyToV2(raw) {
-    const moved = movedKeyReason(raw);
-    if (moved)
-        return invalid(moved);
-    const unknownKey = findUnknownStudyKey(raw);
-    if (unknownKey)
-        return invalid(unknownKey);
-    const route = ROUTES.find((name) => name === raw.route);
-    if (route === undefined) {
-        return invalid(`A study needs \`route:\`, one of ${ROUTES.join(", ")}.`);
-    }
-    if (raw.mode !== undefined && raw.mode !== "dry-run" && raw.mode !== "live") {
-        return invalid("`mode` must be `dry-run` or `live`. Leave it out for a dry run.");
-    }
-    if (!isRecord(raw.actor)) {
-        return invalid("A study needs `actor:`, an object with at least `type`.");
-    }
-    if (raw.scenario !== undefined && typeof raw.scenario !== "string") {
-        return invalid("`scenario` is a scenario id or a path to one, as a string.");
-    }
-    const participants = participantsOf(route, raw.participants);
-    if (!participants.ok)
-        return participants;
-    const surfaces = surfaceCount(route, raw.surfaces);
-    if (!surfaces.ok)
-        return surfaces;
-    const capsReason = capsKeysReason(route, raw.caps);
-    if (capsReason)
-        return invalid(capsReason);
-    // The v2 inert-field table does not list this one, but the terminal planner never reads it.
-    if (route === "terminal" && isRecord(raw.execution) && raw.execution.timeoutMs !== undefined) {
-        return invalid("route: terminal does not read `execution.timeoutMs`: `caps.maxMinutes` is the command deadline. Remove it.");
-    }
-    const { count, instruction, entries, source } = participants.value;
+    const front = readStudyFront(raw);
+    if (!front.ok)
+        return front;
+    const { route } = front.value;
+    const { count, instruction, entries, source } = front.value.participants;
     // The v2 actor keys that hold participants.
     const v2Participants = [
-        ["count", count ?? surfaces.value],
+        ["count", count ?? front.value.surfaces],
         ["laneFocus", instruction === undefined ? undefined : { instruction }],
         ["lanes", entries],
     ];
-    const actor = { ...raw.actor };
+    const actor = { ...front.value.actor };
     for (const [key, value] of v2Participants)
         if (value !== undefined)
             actor[key] = value;
@@ -100,6 +72,52 @@ export function studyToV2(raw) {
             v2[key] = value;
     return { ok: true, value: { route, v2, participantSource: source } };
 }
+/**
+ * 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 function readStudyFront(raw, anySharedWorldParticipants = false) {
+    const moved = movedKeyReason(raw);
+    if (moved)
+        return invalid(moved);
+    const unknownKey = findUnknownStudyKey(raw);
+    if (unknownKey)
+        return invalid(unknownKey);
+    const route = ROUTES.find((name) => name === raw.route);
+    if (route === undefined) {
+        return invalid(`A study needs \`route:\`, one of ${ROUTES.join(", ")}.`);
+    }
+    if (raw.mode !== undefined && raw.mode !== "dry-run" && raw.mode !== "live") {
+        return invalid("`mode` must be `dry-run` or `live`. Leave it out for a dry run.");
+    }
+    if (!isRecord(raw.actor)) {
+        return invalid("A study needs `actor:`, an object with at least `type`.");
+    }
+    if (raw.scenario !== undefined && typeof raw.scenario !== "string") {
+        return invalid("`scenario` is a scenario id or a path to one, as a string.");
+    }
+    const participants = participantsOf(anySharedWorldParticipants && route === "shared-world" ? "computer-use" : route, raw.participants);
+    if (!participants.ok)
+        return participants;
+    const surfaces = surfaceCount(route, raw.surfaces);
+    if (!surfaces.ok)
+        return surfaces;
+    const capsReason = capsKeysReason(route, raw.caps);
+    if (capsReason)
+        return invalid(capsReason);
+    // The v2 inert-field table does not list this one, but the terminal planner never reads it.
+    if (route === "terminal" && isRecord(raw.execution) && raw.execution.timeoutMs !== undefined) {
+        return invalid("route: terminal does not read `execution.timeoutMs`: `caps.maxMinutes` is the command deadline. Remove it.");
+    }
+    return {
+        ok: true,
+        value: { route, actor: raw.actor, participants: participants.value, surfaces: surfaces.value },
+    };
+}
 /**
  * Spell a v2 parser message the way the study file is written: `actors[0].lanes[3]` becomes the
  * `participants` entry it came from, `execution.caps` and `scenario.caps` become `caps`, and so on.

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

@@ -0,0 +1,38 @@
+import { type StudyConfig, type StudyParseFailure, type StudyScenarioCaps, type StudyV3 } from "../types.js";
+interface StudyV3Options {
+    /**
+     * `report`, for `humanish migrate`: list the fields the route does not read in `inert`, as v2
+     * paths, in place of refusing the study for them, and give the checks' messages as they wrote
+     * them, in the v2 spelling of the file migrate converts. 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: StudyV3;
+    warnings: string[];
+    inert?: string[];
+} | StudyParseFailure;
+type Parsed<T> = {
+    ok: true;
+    value: T;
+} | StudyParseFailure;
+/**
+ * Validate a parsed humanish.study.v3 document into a StudyV3, with the messages parseStudy gives.
+ * Pure: the caller owns file IO. parseStudy refuses a humanish.lab.v2 document before this runs.
+ */
+export declare function parseStudyV3(raw: unknown, options?: StudyV3Options): StudyV3ParseResult;
+/**
+ * A v3 study in the v2 spelling: the actor holds its participants, `caps` moves under `execution`
+ * or `scenario`, and a shared world is `subject.topology: shared-world`. The checks that read more
+ * than one section run on this view until StudyConfig has the v3 shape.
+ */
+export declare function toLegacy(study: StudyV3): StudyConfig;
+/**
+ * A caps block's values. A value that is not a non-negative number refuses the study: a cap that
+ * does nothing must not look like one that holds. readStudyFront has checked the keys against the
+ * route; migrate checks a v2 file's two blocks with it.
+ */
+export declare function parseCaps(raw: unknown): Parsed<StudyScenarioCaps | undefined>;
+export {};