humanish 0.110.2 → 0.110.4

package/dist/study/parse/study.js

@@ -0,0 +1,225 @@
+// humanish.study.v3, parsed into a config with the file's own keys (StudyV3). parseStudy still
+// rewrites a v3 file into the v2 spelling and parses that (parse/study-v3.ts).
+// tests/study/parse-differential.test.ts holds the two to the same result. The checks that read
+// more than one section still take the v2 shape, so they run on toLegacy's view of the study.
+import { isRecord } from "../../run/type-guards.js";
+import { checkStudyConfig } from "../config.js";
+import { routeOf } from "../routing.js";
+import { ID_PATTERN, STUDY_SCHEMA, V2_SCHEMA, } from "../types.js";
+import { inertFieldLabels, inertFieldPaths } from "../warnings.js";
+import { parseActorFields, parseActorType, parseParticipantEntries, withoutParticipants, withParticipants, } from "./actors.js";
+import { parseComms } from "./comms.js";
+import { parseDefaults, parseExecution, parsePolicies, parseReview } from "./execution.js";
+import { readStudyFront, studySpelling } from "./study-v3.js";
+import { parseSubject } from "./subject.js";
+import { invalid, nonNegNumber, optionalStr, str } from "./values.js";
+/**
+ * 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 function parseStudyV3(raw, options = {}) {
+    if (!isRecord(raw))
+        return invalid("A study file must be a YAML object.");
+    if (raw.schema !== STUDY_SCHEMA) {
+        return invalid(`The study schema must be ${STUDY_SCHEMA} or ${V2_SCHEMA}.`);
+    }
+    const front = readStudyFront(raw, options.inert === "report");
+    if (!front.ok)
+        return front;
+    const study = parseSections(raw, front.value);
+    if (!study.ok)
+        return study;
+    const spell = (message) => options.inert === "report"
+        ? message
+        : studySpelling(message, front.value.route, front.value.participants.source);
+    const checked = checkStudyConfig(toLegacy(study.value));
+    if (!checked.ok)
+        return invalid(spell(checked.error.message));
+    const { route } = study.value;
+    const taken = routeOf(checked.config);
+    if (taken !== route) {
+        return invalid(`This study declares route: ${route}, but its subject (source: ${checked.config.subject.source}) and actor (type: ${checked.config.actors[0]?.type}) take the ${taken} route. Change \`route\`, or change the subject or actor.`);
+    }
+    const config = withFilledDefaults(study.value, checked.config);
+    const warnings = checked.warnings.map(spell);
+    if (options.inert === "report") {
+        return { ok: true, config, warnings, inert: inertFieldPaths(checked.config) };
+    }
+    const inert = inertFieldLabels(checked.config);
+    if (inert.length > 0) {
+        return invalid(spell(`route: ${route} does not read ${inert.join(", ")}. Remove ${inert.length === 1 ? "it" : "them"}.`));
+    }
+    return { ok: true, config, warnings };
+}
+/**
+ * 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 function toLegacy(study) {
+    const { route, participants, caps } = study;
+    const group = typeof participants === "object" && !Array.isArray(participants) ? participants : undefined;
+    const actor = withParticipants(study.actor, {
+        count: typeof participants === "number" ? participants : (group?.count ?? study.surfaces?.length),
+        entries: Array.isArray(participants) ? participants : undefined,
+        instruction: group?.instruction,
+    });
+    const { source, ...subject } = study.subject;
+    const execution = caps !== undefined && route !== "terminal" ? { ...study.execution, caps } : study.execution;
+    const scenario = {
+        ...(study.scenario === undefined ? {} : { ref: study.scenario }),
+        ...(study.mode === undefined ? {} : { mode: study.mode }),
+        ...(caps !== undefined && route === "terminal" ? { caps } : {}),
+    };
+    return {
+        schema: study.schema,
+        id: study.id,
+        ...(study.title === undefined ? {} : { title: study.title }),
+        ...(study.description === undefined ? {} : { description: study.description }),
+        subject: route === "shared-world" ? { source, topology: "shared-world", ...subject } : study.subject,
+        actors: [actor],
+        ...(execution === undefined ? {} : { execution }),
+        ...(Object.keys(scenario).length > 0 ? { scenario } : {}),
+        ...(study.policies === undefined ? {} : { policies: study.policies }),
+        ...(study.review === undefined ? {} : { review: study.review }),
+        ...(study.defaults === undefined ? {} : { defaults: study.defaults }),
+        ...(study.comms === undefined ? {} : { comms: study.comms }),
+    };
+}
+// Each section in the order the v2 parser reads it, so a file with more than one error reports the
+// same one first.
+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 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 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);
+    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.surfaces === 2
+        ? ["desktop", "mobile"]
+        : front.surfaces === 1
+            ? ["desktop"]
+            : undefined;
+    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 }),
+        },
+    };
+}
+/**
+ * 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 function parseCaps(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (!isRecord(raw)) {
+        return invalid("`caps` must be an object ({ maxUsd?, maxTotalUsd?, maxJobs?, maxMinutes? }).");
+    }
+    const caps = {};
+    for (const key of ["maxUsd", "maxTotalUsd", "maxJobs", "maxMinutes"]) {
+        if (raw[key] === undefined)
+            continue;
+        const value = nonNegNumber(raw[key]);
+        if (value === undefined)
+            return invalid(`\`caps.${key}\` must be a non-negative number.`);
+        caps[key] = value;
+    }
+    return { ok: true, value: Object.keys(caps).length > 0 ? caps : undefined };
+}
+// checkStudyConfig fills defaults in the v2 view: a shared world's `execution.concurrency`,
+// `comms.email.recipients`, and the local browser's actor model and effort, execution timeout and
+// resolution and `review.analysis`. Each has the same path in both shapes, so it is copied back.
+function withFilledDefaults(study, checked) {
+    const [actor] = checked.actors;
+    const execution = { ...checked.execution };
+    delete execution.caps;
+    return {
+        ...study,
+        actor: actor === undefined ? study.actor : withoutParticipants(actor),
+        ...(Object.keys(execution).length > 0 ? { execution } : {}),
+        ...(checked.review === undefined ? {} : { review: checked.review }),
+        ...(checked.comms === undefined ? {} : { comms: checked.comms }),
+    };
+}

package/dist/study/parse/subject.js

@@ -176,7 +176,7 @@ function parseServedApp(raw, subject) {
         return stateResult;
     }
     if (stateResult.value) {
-        // Semantic validation is shared with the engine (runCuaActorStudy re-enforces it for
+        // Semantic validation is shared with the engine (planComputerUseStudy re-enforces it for
         // configs that arrive through the library API without the parser).
         const reason = subjectStateInvalidReason(stateResult.value, subject.env);
         if (reason) {

package/dist/study/persona-resolve.d.ts

@@ -1,6 +1,6 @@
 import { type ResolvedPersona } from "./persona.js";
 import { type PreparedSelectedOutputDirectory } from "../run/contained-output.js";
-import type { StudyActor } from "./types.js";
+import type { StudyConfig } from "./types.js";
 /** Title-case an id for the fallback display name (`skeptical-power-user` -> `Skeptical Power User`). */
 export declare function personaTitleFromId(personaId: string): string;
 /**
@@ -25,9 +25,7 @@ export declare function resolveCommittedPersonas(projectRoot: PreparedSelectedOu
  * Every persona id a study config could put on a browser participant: the roster when one is
  * declared, otherwise the actor-level persona that every fan-out participant inherits.
  */
-export declare function studyPersonaIds(config: {
-    actors?: readonly Pick<StudyActor, "persona" | "lanes">[];
-}): string[];
+export declare function studyPersonaIds(config: StudyConfig): string[];
 /**
  * Same resolution from a plain cwd, for the labs that carry a directory string rather than an
  * already-prepared root. Realpath-then-prepare mirrors the computer-use route so a symlinked cwd

package/dist/study/persona-resolve.js

@@ -6,6 +6,7 @@ import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../ru
 import { digestText, redactText } from "../evidence/redaction.js";
 import { realpath } from "node:fs/promises";
 import { rosterOf } from "./parse/actors.js";
+import { actorsOf } from "./study-fields.js";
 /** Persona ids are file-name segments, never paths: the same grammar the terminal route enforces. */
 const PERSONA_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 /** Title-case an id for the fallback display name (`skeptical-power-user` -> `Skeptical Power User`). */
@@ -86,7 +87,7 @@ export async function resolveCommittedPersonas(projectRoot, personaIds) {
  */
 export function studyPersonaIds(config) {
     const ids = [];
-    for (const actor of config.actors ?? []) {
+    for (const actor of actorsOf(config)) {
         if (actor.persona)
             ids.push(actor.persona);
         for (const entry of rosterOf(actor) ?? []) {

package/dist/study/plan-base.d.ts

@@ -2,7 +2,7 @@ import type { Brain, ComputerUsePlan, NonEmpty, PlannedAnalysis, ProvisionedSubj
 import type { StudyConfig } from "./types.js";
 export type Base = Omit<ComputerUsePlan, "route" | "actor" | "runner" | "concurrency" | "sessionBudgetMs" | "sandboxMs" | "caps" | "rerun">;
 export declare function isNonEmpty<T>(values: readonly T[]): values is NonEmpty<T>;
-export declare function capsOf(config: StudyConfig): ComputerUsePlan["caps"];
+export declare function planCaps(config: StudyConfig, route: "computer-use" | "shared-world"): ComputerUsePlan["caps"];
 export declare function provisionedSubject(config: StudyConfig): ProvisionedSubject | undefined;
 /** Keys, env and local tools a live run checks right before it acquires anything. */
 export declare function desktopRequirements(config: StudyConfig, args: {

package/dist/study/plan-base.js

@@ -1,6 +1,7 @@
 // What every route planner shares: the plan fields common to all routes, the frozen residual config,
 // and the requirement and subject helpers.
 import { DEFAULT_OPENAI_CU_MODEL } from "../actors/computer-use/openai-provider.js";
+import { actorOf, capsOf } from "./study-fields.js";
 // A YAML alias can make a parsed record contain itself (an inline persona that names its own
 // anchor), and structuredClone keeps the cycle, so each object is frozen once.
 function deepFreeze(value, frozen = new WeakSet()) {
@@ -43,8 +44,8 @@ function residualOf(config) {
 export function isNonEmpty(values) {
     return values.length > 0;
 }
-export function capsOf(config) {
-    const caps = config.execution?.caps;
+export function planCaps(config, route) {
+    const caps = capsOf(config, route);
     return {
         ...(caps?.maxUsd === undefined ? {} : { maxUsd: caps.maxUsd }),
         ...(caps?.maxTotalUsd === undefined ? {} : { maxTotalUsd: caps.maxTotalUsd }),
@@ -86,7 +87,7 @@ export function desktopRequirements(config, args) {
     return requirements;
 }
 export function brainOf(config, callerProvider) {
-    const actor = config.actors[0];
+    const actor = actorOf(config);
     if (callerProvider)
         return callerBrainOf(config);
     const declared = declaredModelOf(config);
@@ -99,7 +100,7 @@ export function callerBrainOf(config) {
     return { kind: "caller", ...declaredModelOf(config) };
 }
 function declaredModelOf(config) {
-    const model = config.actors[0]?.model;
+    const model = actorOf(config)?.model;
     return model === undefined ? {} : { declaredModel: model };
 }
 /** The model a participant's spend is priced at when its provider reports none. */

package/dist/study/plan-participants.js

@@ -2,9 +2,9 @@
 // Computer-use and shared-world participants share the desktop fields; each kind adds its own.
 import { resolveParticipantDevice } from "./device-presets.js";
 import { isSharedWorldComposition, participantIdAt } from "./routing.js";
-import { focusOf, rosterOf } from "./parse/actors.js";
+import { actorOf, participantList, declaredParticipantCount, participantInstruction, } from "./study-fields.js";
 function desktopParticipant(config, entry, index, kind, focus) {
-    const actor = config.actors[0];
+    const actor = actorOf(config);
     const device = resolveParticipantDevice(config, entry?.device);
     const personaId = entry?.persona ?? actor?.persona;
     const mission = actor?.mission;
@@ -39,12 +39,14 @@ function desktopParticipant(config, entry, index, kind, focus) {
  * override (`--count`) applies only when no roster is declared.
  */
 export function computerUseParticipants(config, countOverride) {
-    const actor = config.actors[0];
-    const roster = rosterOf(actor);
-    const count = roster ? roster.length : Math.max(1, countOverride ?? actor?.count ?? 1);
+    const actor = actorOf(config);
+    const roster = participantList(config);
+    const count = roster
+        ? roster.length
+        : Math.max(1, countOverride ?? declaredParticipantCount(config) ?? 1);
     return Array.from({ length: count }, (_, index) => {
         const entry = roster?.[index];
-        const focus = roster ? entry?.instruction : focusOf(actor)?.instruction;
+        const focus = roster ? entry?.instruction : participantInstruction(config);
         return {
             ...desktopParticipant(config, entry, index, "lane", focus),
             ...(actor?.tasks === undefined ? {} : { tasks: actor.tasks }),
@@ -54,7 +56,7 @@ export function computerUseParticipants(config, countOverride) {
 }
 /** The participants of a shared-world study, one per roster entry, typed by the plane they share. */
 export function sharedWorldParticipants(config) {
-    const roster = rosterOf(config.actors[0]) ?? [];
+    const roster = participantList(config) ?? [];
     const participantAt = (entry, index) => desktopParticipant(config, entry, index, "seat", entry.instruction);
     if (config.subject.source === "app-url") {
         return {
@@ -75,18 +77,17 @@ export function sharedWorldParticipants(config) {
 }
 /** The ids of the participants a computer-use or shared-world study runs, in roster order. */
 export function declaredParticipantIds(config) {
-    const actor = config.actors[0];
-    const roster = rosterOf(actor);
+    const roster = participantList(config);
     const kind = isSharedWorldComposition(config) ? "seat" : "lane";
     if (roster && roster.length > 0) {
         return roster.map((entry, index) => participantIdAt(index, entry.id, kind));
     }
-    const count = Math.max(1, actor?.count ?? 1);
+    const count = Math.max(1, declaredParticipantCount(config) ?? 1);
     return Array.from({ length: count }, (_, index) => participantIdAt(index, undefined, kind));
 }
 /** The entry URLs roster entries declare in place of the subject URL (computer use, app-url). */
 export function declaredTargets(config) {
-    return (rosterOf(config.actors[0]) ?? [])
+    return (participantList(config) ?? [])
         .map((entry) => entry.target)
         .filter((target) => target !== undefined);
 }

package/dist/study/plan.js

@@ -11,16 +11,17 @@ import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
 import { planBase } from "./plan-base.js";
 import { routeOf } from "./routing.js";
 import { automaticAnalysisRouteReason, taskProtocolValidationReason } from "./validation.js";
+import { declaredParticipantCount, modeOf } from "./study-fields.js";
 export { routeOf } from "./routing.js";
 /** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
 export function resolveStudyDryRun(config, override, fallback) {
     if (override !== undefined) {
         return override;
     }
-    if (config.scenario?.mode === "live") {
+    if (modeOf(config) === "live") {
         return false;
     }
-    if (config.scenario?.mode === "dry-run") {
+    if (modeOf(config) === "dry-run") {
         return true;
     }
     return fallback;
@@ -45,7 +46,7 @@ function planPreview(config, options, input) {
     const tasksReason = taskProtocolValidationReason(config);
     if (tasksReason)
         return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
-    const participantCount = options.count ?? config.actors[0]?.count ?? 4;
+    const participantCount = options.count ?? declaredParticipantCount(config) ?? 4;
     if (!Number.isSafeInteger(participantCount) || participantCount < 1)
         return refuse("HUMANISH_INVALID_PARTICIPANT_COUNT", "count must be a positive integer.");
     if (!input.dryRun)

package/dist/study/preflight-probes.js

@@ -12,9 +12,9 @@ import { acquireE2BDesktopSandbox, readE2BRelease } from "../substrates/e2b/sand
 import { e2bShell } from "../substrates/e2b/shell.js";
 import { redactText } from "../evidence/redaction.js";
 import { digest, fail, finalize } from "./preflight-result.js";
-import { rosterOf } from "./parse/actors.js";
 import { plural } from "../run/text.js";
 import { cli } from "../cli/invocation.js";
+import { participantList } from "./study-fields.js";
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 // Room on the probe's lease for desktop boot and teardown around the work it does.
 const PREFLIGHT_LEASE_BUFFER_MS = 5 * 60_000;
@@ -271,7 +271,7 @@ function targetUrlFor(config, target) {
         return config.subject.appUrl;
     }
     if (target.kind === "actors[0].lanes[].target") {
-        const rosterTarget = rosterOf(config.actors[0])?.find((entry) => entry.target && digest(entry.target) === target.targetDigest)?.target;
+        const rosterTarget = participantList(config)?.find((entry) => entry.target && digest(entry.target) === target.targetDigest)?.target;
         if (rosterTarget)
             return rosterTarget;
     }

package/dist/study/preflight.js

@@ -5,7 +5,7 @@ import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./prefli
 import { digest, fail, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
 import { routeOf } from "./plan.js";
 import { resolveStudyManifest } from "./discover.js";
-import { rosterOf } from "./parse/actors.js";
+import { participantList } from "./study-fields.js";
 const DEFAULT_PREFLIGHT_TIMEOUT_MS = 30_000;
 export async function runStudyPreflight(options) {
     const cwd = path.resolve(options.cwd);
@@ -82,7 +82,7 @@ function collectTargets(config) {
     if (config.subject.appUrl) {
         targets.push(makeTarget("subject.appUrl", "subject.appUrl", config.subject.appUrl));
     }
-    for (const [index, entry] of (rosterOf(config.actors[0]) ?? []).entries()) {
+    for (const [index, entry] of (participantList(config) ?? []).entries()) {
         if (entry.target) {
             targets.push(makeTarget(`actors[0].lanes[${index}].target`, "actors[0].lanes[].target", entry.target));
         }

package/dist/study/routing.js

@@ -1,5 +1,6 @@
 import { actorRegistry } from "../actors/registry.js";
 import { isLoopbackUrl } from "./parse/subject.js";
+import { actorOf, participantList, declaredParticipantCount, declaresSharedWorld, } from "./study-fields.js";
 // Hard cap on computer-use participants. No setting raises it: each participant is a paid desktop,
 // and they all run at once.
 export const MAX_COMPUTER_USE_PARTICIPANTS = 16;
@@ -50,11 +51,7 @@ export function registeredTerminalActors() {
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
 export function computerUseParticipantCount(config) {
-    const actor = config.actors[0];
-    if (actor?.lanes !== undefined) {
-        return actor.lanes.length;
-    }
-    return actor?.count ?? 1;
+    return participantList(config)?.length ?? declaredParticipantCount(config) ?? 1;
 }
 /**
  * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`
@@ -77,7 +74,7 @@ export function isComputerUseComposition(config) {
     // local-app drives the cua loop in-process (a custom executor + a non-vision provider), so it
     // routes to the computer-use route exactly like an app-url subject with a computer-use actor.
     if (config.subject.source === "app-url" || config.subject.source === "local-app") {
-        return actorResolvesToComputerUse(config.actors[0]?.type);
+        return actorResolvesToComputerUse(actorOf(config)?.type);
     }
     // desktop-cli hands the participant a terminal instead of a served page, but it is the
     // same route: same desktop, same actor, same prompt fields. Leaving it out of this predicate told
@@ -85,13 +82,13 @@ export function isComputerUseComposition(config) {
     // person reads a screen.
     if (config.subject.source === "desktop-cli") {
         return ((config.execution?.target === undefined || config.execution.target === "e2b-desktop") &&
-            actorResolvesToComputerUse(config.actors[0]?.type));
+            actorResolvesToComputerUse(actorOf(config)?.type));
     }
     // local-tree packs+uploads the working tree, then serves it exactly like a computer-use clone
     // subject: same e2b-desktop + computer-use-actor gate.
     return ((config.subject.source === "clone" || config.subject.source === "local-tree") &&
         config.execution?.target === "e2b-desktop" &&
-        actorResolvesToComputerUse(config.actors[0]?.type));
+        actorResolvesToComputerUse(actorOf(config)?.type));
 }
 /**
  * True when this config routes to the shared-world route: a clone or local-tree subject
@@ -108,9 +105,9 @@ export function isSharedWorldComposition(config) {
 /** The getHost provisioned-subject shared-world shape (clone/local-tree served + exposed in-sandbox). */
 export function isProvisionedSharedWorldComposition(config) {
     return ((config.subject.source === "clone" || config.subject.source === "local-tree") &&
-        config.subject.topology === "shared-world" &&
+        declaresSharedWorld(config) &&
         config.execution?.target === "e2b-desktop" &&
-        actorResolvesToComputerUse(config.actors[0]?.type));
+        actorResolvesToComputerUse(actorOf(config)?.type));
 }
 /**
  * The external-public shared-world shape: a real public deployment used directly as
@@ -123,9 +120,9 @@ export function isProvisionedSharedWorldComposition(config) {
  */
 export function isExternalPublicSharedWorldComposition(config) {
     return (config.subject.source === "app-url" &&
-        config.subject.topology === "shared-world" &&
+        declaresSharedWorld(config) &&
         config.execution?.target === "e2b-desktop" &&
-        actorResolvesToComputerUse(config.actors[0]?.type) &&
+        actorResolvesToComputerUse(actorOf(config)?.type) &&
         config.policies?.allowPublicTargets === true);
 }
 /**
@@ -162,12 +159,12 @@ export function isScriptedBrowserComposition(config) {
     return (isLocalScriptedBrowserComposition(config) || isProvisionedScriptedBrowserComposition(config));
 }
 function isLocalScriptedBrowserComposition(config) {
-    return (config.subject.source === "app-url" && actorResolvesToScriptedBrowser(config.actors[0]?.type));
+    return (config.subject.source === "app-url" && actorResolvesToScriptedBrowser(actorOf(config)?.type));
 }
 export function isProvisionedScriptedBrowserComposition(config) {
     return (config.subject.source === "clone" &&
         config.execution?.target === "e2b-desktop" &&
-        actorResolvesToScriptedBrowser(config.actors[0]?.type));
+        actorResolvesToScriptedBrowser(actorOf(config)?.type));
 }
 /**
  * True when this config routes to the terminal-product backend: a terminal-product subject whose
@@ -176,7 +173,7 @@ export function isProvisionedScriptedBrowserComposition(config) {
  * the single source of truth for routeOf and the warning logic.
  */
 export function isTerminalProductComposition(config) {
-    return (config.subject.source === "terminal-product" && actorResolvesToTerminal(config.actors[0]?.type));
+    return (config.subject.source === "terminal-product" && actorResolvesToTerminal(actorOf(config)?.type));
 }
 /**
  * The route a config takes. It never refuses: a config no route can run still gets the route

package/dist/study/run-study-options.js

@@ -6,8 +6,8 @@ import path from "node:path";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { resolveStudyDryRun } from "./plan.js";
 import { knownSecretValues, studyEventEmitter } from "./run-study-events.js";
-import { rosterOf } from "./parse/actors.js";
 import { studyResultIdentity } from "../run/study-result.js";
+import { actorOf, participantList } from "./study-fields.js";
 const unsupported = (option, route, reason) => ({
     ok: false,
     code: "HUMANISH_STUDY_OPTION_UNSUPPORTED",
@@ -105,7 +105,7 @@ export function normalizeRunStudyOptions(config, route, options) {
 export function optionRefusalOutcome(config, route, options, refusal) {
     const cwd = path.resolve(options.cwd);
     const error = { code: refusal.code, message: refusal.message };
-    const actor = config.actors[0]?.type ?? "";
+    const actor = actorOf(config)?.type ?? "";
     const dryRun = resolveStudyDryRun(config, options.dryRun, true) ?? true;
     const runId = options.runId ?? "not-created";
     const common = { ok: false, cwd, actor, dryRun, runId, warnings: [], error };
@@ -154,7 +154,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
                 },
             };
         case "shared-world": {
-            const participantCount = rosterOf(config.actors[0])?.length ?? 0;
+            const participantCount = participantList(config)?.length ?? 0;
             return {
                 route: "shared-world",
                 result: {

package/dist/study/study-fields.d.ts

@@ -0,0 +1,28 @@
+import type { StudyRoute } from "./routing.js";
+import type { StudyActor, StudyConfig, StudyParticipantEntry, StudyScenario, StudyScenarioCaps } from "./types.js";
+/** The actor that runs. A v3 file declares it as `actor`. */
+export declare function actorOf(config: StudyConfig): StudyActor | undefined;
+/**
+ * Every declared actor. parseStudy accepts exactly one; a library config may declare more, and the
+ * checks that refuse a second actor's settings read them all.
+ */
+export declare function actorsOf(config: StudyConfig): readonly StudyActor[];
+/** The participants listed one by one: a v3 `participants` list. Undefined when none is listed. */
+export declare function participantList(config: StudyConfig): readonly StudyParticipantEntry[] | undefined;
+/** The declared number of identical participants: v3 `participants: <n>` or `participants.count`. */
+export declare function declaredParticipantCount(config: StudyConfig): number | undefined;
+/** The steer each of a counted group of participants gets: v3 `participants.instruction`. */
+export declare function participantInstruction(config: StudyConfig): string | undefined;
+/** How many scripted surfaces run, 1 for desktop and 2 with mobile. A v3 file lists `surfaces`. */
+export declare function surfaceCount(config: StudyConfig): number | undefined;
+/** The declared run mode. A v3 file declares it as `mode`. */
+export declare function modeOf(config: StudyConfig): StudyScenario["mode"];
+/** The scripted route's scenario id or path. A v3 file declares it as `scenario`. */
+export declare function scenarioRefOf(config: StudyConfig): string | undefined;
+/**
+ * The spend caps a route enforces. A v3 file declares them as `caps`. The v2 shape keeps them in
+ * `execution.caps` on computer use and shared world, and in `scenario.caps` on terminal.
+ */
+export declare function capsOf(config: StudyConfig, route: Extract<StudyRoute, "computer-use" | "shared-world" | "terminal">): StudyScenarioCaps | undefined;
+/** True when the participants share one app. A v3 file declares `route: shared-world`. */
+export declare function declaresSharedWorld(config: StudyConfig): boolean;

package/dist/study/study-fields.js

@@ -0,0 +1,51 @@
+// The study's fields, read in one place. StudyConfig still has the humanish.lab.v2 shape
+// (`actors[0]`, `execution.caps`, `scenario.mode`), while a humanish.study.v3 file names the same
+// values `actor`, `participants`, `surfaces`, `caps`, `mode`, `scenario` and `route`. Code outside
+// the parser reads them through these functions, and tests/surface/study-config-reads.test.ts
+// refuses a direct read, so the config can take the v3 shape by changing this file.
+/** The actor that runs. A v3 file declares it as `actor`. */
+export function actorOf(config) {
+    return config.actors[0];
+}
+/**
+ * Every declared actor. parseStudy accepts exactly one; a library config may declare more, and the
+ * checks that refuse a second actor's settings read them all.
+ */
+export function actorsOf(config) {
+    return config.actors;
+}
+/** The participants listed one by one: a v3 `participants` list. Undefined when none is listed. */
+export function participantList(config) {
+    return config.actors[0]?.lanes;
+}
+/** The declared number of identical participants: v3 `participants: <n>` or `participants.count`. */
+export function declaredParticipantCount(config) {
+    return config.actors[0]?.count;
+}
+/** The steer each of a counted group of participants gets: v3 `participants.instruction`. */
+export function participantInstruction(config) {
+    return config.actors[0]?.laneFocus?.instruction;
+}
+/** How many scripted surfaces run, 1 for desktop and 2 with mobile. A v3 file lists `surfaces`. */
+export function surfaceCount(config) {
+    return config.actors[0]?.count;
+}
+/** The declared run mode. A v3 file declares it as `mode`. */
+export function modeOf(config) {
+    return config.scenario?.mode;
+}
+/** The scripted route's scenario id or path. A v3 file declares it as `scenario`. */
+export function scenarioRefOf(config) {
+    return config.scenario?.ref;
+}
+/**
+ * The spend caps a route enforces. A v3 file declares them as `caps`. The v2 shape keeps them in
+ * `execution.caps` on computer use and shared world, and in `scenario.caps` on terminal.
+ */
+export function capsOf(config, route) {
+    return route === "terminal" ? config.scenario?.caps : config.execution?.caps;
+}
+/** True when the participants share one app. A v3 file declares `route: shared-world`. */
+export function declaresSharedWorld(config) {
+    return config.subject.topology === "shared-world";
+}