humanish 0.110.3 → 0.111.0

package/dist/study/parse/{study-v3.js → front.js}

@@ -1,10 +1,8 @@
-// humanish.study.v3, the study format. A study declares its route, one `actor`, its `participants`
-// and one `caps` block. studyToV2 rewrites a v3 document into the v2 spelling, so both formats run
-// through one parser and parse into the same StudyConfig. parseStudy then checks the declared
-// route against the one the config takes, and refuses any field that route does not read.
+// What a humanish.study.v3 document declares before its sections parse: its route, one `actor`,
+// its `participants` or `surfaces`, and the `caps` keys the route reads. config.ts parses the
+// sections after these checks pass.
 import { isRecord } from "../../run/type-guards.js";
 import { findUnknownStudyKey } from "../keys.js";
-import { V2_SCHEMA } from "../types.js";
 import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./actors.js";
 import { invalid, posInt } from "./values.js";
 // The values `route:` takes: every route routeOf can return.
@@ -24,8 +22,23 @@ const CAPS_KEYS = {
     terminal: ["maxUsd", "maxJobs", "maxMinutes"],
     scripted: [],
 };
-/** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
-export function studyToV2(raw) {
+/** The refusal for a study with no `actor` object. */
+export 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 function routeNameReason(route) {
+    return ROUTES.some((name) => name === route)
+        ? undefined
+        : `A study needs \`route:\`, one of ${ROUTES.join(", ")}.`;
+}
+/**
+ * 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);
@@ -33,90 +46,33 @@ export function studyToV2(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 (route === undefined)
+        return invalid(routeNameReason(raw.route));
     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 (!isRecord(raw.actor))
+        return invalid(ACTOR_REQUIRED);
     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);
+    const participants = participantsOf(anySharedWorldParticipants && route === "shared-world" ? "computer-use" : route, raw.participants);
     if (!participants.ok)
         return participants;
-    const surfaces = surfaceCount(route, raw.surfaces);
+    const surfaces = surfacesOf(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.
+    // The inert-field rows (warnings.ts) do not list this one; 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;
-    // The v2 actor keys that hold participants.
-    const v2Participants = [
-        ["count", count ?? surfaces.value],
-        ["laneFocus", instruction === undefined ? undefined : { instruction }],
-        ["lanes", entries],
-    ];
-    const actor = { ...raw.actor };
-    for (const [key, value] of v2Participants)
-        if (value !== undefined)
-            actor[key] = value;
-    const caps = raw.caps;
-    const scenario = {};
-    if (raw.scenario !== undefined)
-        scenario.ref = raw.scenario;
-    if (raw.mode !== undefined)
-        scenario.mode = raw.mode;
-    if (caps !== undefined && route === "terminal")
-        scenario.caps = caps;
-    const execution = caps !== undefined && route !== "terminal"
-        ? withKey(raw.execution, "caps", caps)
-        : raw.execution;
-    const subject = route === "shared-world" ? withKey(raw.subject, "topology", "shared-world") : raw.subject;
-    const v2 = { schema: V2_SCHEMA };
-    const fields = [
-        ["id", raw.id],
-        ["title", raw.title],
-        ["description", raw.description],
-        ["subject", subject],
-        ["actors", [actor]],
-        ["execution", execution],
-        ["scenario", Object.keys(scenario).length > 0 ? scenario : undefined],
-        ["policies", raw.policies],
-        ["review", raw.review],
-        ["defaults", raw.defaults],
-        ["comms", raw.comms],
-    ];
-    for (const [key, value] of fields)
-        if (value !== undefined)
-            v2[key] = value;
-    return { ok: true, value: { route, v2, participantSource: source } };
-}
-/**
- * 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.
- */
-export function studySpelling(message, route, participantSource) {
-    return (message
-        .replaceAll(/actors\[0\]\.lanes\[(\d+)\]/g, (_match, index) => `participants[${participantSource[Number(index)] ?? index}]`)
-        // "an `actors[0].lanes` roster" reads "a `participants` list" in a v3 file.
-        .replaceAll(/\ban `actors\[0\]\.(lanes|roster)` roster\b/g, "a `participants` list")
-        .replaceAll(/actors\[0\]\.(lanes|roster)\b/g, "participants")
-        .replaceAll(/actors\[0\]\.laneFocus(\.instruction)?/g, "participants.instruction")
-        .replaceAll(/actors\[0\]\.count\b/g, route === "scripted" ? "surfaces" : "participants")
-        .replaceAll("actors[0]", "actor")
-        .replaceAll(/\b(execution|scenario)\.caps\b/g, "caps")
-        .replaceAll(/\bscenario\.mode\b/g, "mode")
-        .replaceAll(/\bscenario\.ref\b/g, "scenario")
-        .replaceAll("subject.topology: shared-world", "route: shared-world"));
+    return {
+        ok: true,
+        value: { route, actor: raw.actor, participants: participants.value, surfaces: surfaces.value },
+    };
 }
 // The v2 keys a hand-converted file is most likely to keep, each with where it went.
 function movedKeyReason(raw) {
@@ -194,7 +150,7 @@ function homogeneousOf(raw) {
     return { ok: true, value: participants };
 }
 // A list entry with `count: n` is a group: n participants `<id>-01` to `<id>-NN`, even when n is 1.
-// The v2 parser then checks every entry and the expanded ids for collisions.
+// config.ts then checks every entry and the expanded ids for collisions.
 function entriesOf(raw) {
     const entries = [];
     const source = [];
@@ -223,17 +179,17 @@ function entriesOf(raw) {
     }
     return { ok: true, value: { entries, source } };
 }
-// Scripted surfaces become the v2 count: 1 is desktop, 2 adds mobile.
-function surfaceCount(route, raw) {
+function surfacesOf(route, raw) {
     if (raw === undefined)
         return { ok: true, value: undefined };
     if (route !== "scripted") {
         return invalid(`\`surfaces\` belongs to route: scripted. This study's route is ${route}; remove it.`);
     }
-    if (Array.isArray(raw) && raw.length === 1 && raw[0] === "desktop")
-        return { ok: true, value: 1 };
+    if (Array.isArray(raw) && raw.length === 1 && raw[0] === "desktop") {
+        return { ok: true, value: ["desktop"] };
+    }
     if (Array.isArray(raw) && raw.length === 2 && raw[0] === "desktop" && raw[1] === "mobile") {
-        return { ok: true, value: 2 };
+        return { ok: true, value: ["desktop", "mobile"] };
     }
     return invalid("`surfaces` must be [desktop] or [desktop, mobile].");
 }
@@ -250,10 +206,3 @@ function capsKeysReason(route, raw) {
         return undefined;
     return `route: ${route} reads only ${read.map((key) => `caps.${key}`).join(", ")}. Remove ${unread.map((key) => `caps.${key}`).join(", ")}.`;
 }
-// Add one key to a section. A section that is not an object passes through unchanged, so the v2
-// parser refuses it with its own message.
-function withKey(section, key, value) {
-    if (section === undefined)
-        return { [key]: value };
-    return isRecord(section) ? { ...section, [key]: value } : section;
-}

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

@@ -1,4 +1,6 @@
 import type { StudyParseFailure, StudySubject } from "../types.js";
+/** True when `raw` is a subject mapping whose `source` parseSubject accepts. */
+export declare function hasSubjectSource(raw: unknown): boolean;
 export declare function parseSubject(raw: unknown): {
     ok: true;
     value: StudySubject;

package/dist/study/parse/subject.js

@@ -3,31 +3,28 @@ import { ENV_NAME_PATTERN, invalid, posInt, str, strList } from "./values.js";
 import { parseEnvValues, parseState, subjectStateInvalidReason } from "./subject-state.js";
 import { isRecord } from "../../run/type-guards.js";
 import { urlCredentialReason } from "./url-credentials.js";
+const SOURCES = [
+    "this-repo",
+    "clone",
+    "app-url",
+    "local-app",
+    "desktop-cli",
+    "terminal-product",
+    "local-tree",
+];
+/** True when `raw` is a subject mapping whose `source` parseSubject accepts. */
+export function hasSubjectSource(raw) {
+    return isRecord(raw) && SOURCES.some((name) => name === str(raw.source));
+}
 export function parseSubject(raw) {
     if (!isRecord(raw)) {
         return invalid("`subject` is required and must be an object.");
     }
-    const source = str(raw.source);
-    if (source !== "this-repo" &&
-        source !== "clone" &&
-        source !== "app-url" &&
-        source !== "local-app" &&
-        source !== "desktop-cli" &&
-        source !== "terminal-product" &&
-        source !== "local-tree") {
+    const source = SOURCES.find((name) => name === str(raw.source));
+    if (source === undefined) {
         return invalid("`subject.source` must be one of: this-repo, clone, app-url, local-app, terminal-product, desktop-cli, local-tree.");
     }
     const subject = { source };
-    // topology is enum-validated everywhere; its semantics (shared-world requires clone × e2b-desktop
-    // × a ≥2 roster) are enforced in the shared-world cross-validation below, and a set-but-unconsumed
-    // topology warns as inert off the shared-world route.
-    if (raw.topology !== undefined) {
-        const topology = str(raw.topology);
-        if (topology !== "per-lane-worlds" && topology !== "shared-world") {
-            return invalid("`subject.topology` must be per-lane-worlds (the default) or shared-world.");
-        }
-        subject.topology = topology;
-    }
     // exposure is enum-validated everywhere; it is required on the concurrent shared-world route (the
     // getHost synthetic-subject attestation) and warns inert elsewhere.
     if (raw.exposure !== undefined) {

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

@@ -5,7 +5,7 @@ import { parseResolvedPersona, PersonaConfigError } from "./persona.js";
 import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
 import { digestText, redactText } from "../evidence/redaction.js";
 import { realpath } from "node:fs/promises";
-import { rosterOf } from "./parse/actors.js";
+import { actorOf, participantList } 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,13 +86,12 @@ export async function resolveCommittedPersonas(projectRoot, personaIds) {
  */
 export function studyPersonaIds(config) {
     const ids = [];
-    for (const actor of config.actors ?? []) {
-        if (actor.persona)
-            ids.push(actor.persona);
-        for (const entry of rosterOf(actor) ?? []) {
-            if (entry.persona)
-                ids.push(entry.persona);
-        }
+    const persona = actorOf(config)?.persona;
+    if (persona)
+        ids.push(persona);
+    for (const entry of participantList(config) ?? []) {
+        if (entry.persona)
+            ids.push(entry.persona);
     }
     return [...new Set(ids)];
 }

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): 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()) {
@@ -13,11 +14,10 @@ function deepFreeze(value, frozen = new WeakSet()) {
     return value;
 }
 function residualOf(config) {
-    const { comms, policies, personas, defaults, review } = config;
+    const { comms, policies, defaults, review } = config;
     return deepFreeze(structuredClone({
         ...(comms === undefined ? {} : { comms }),
         ...(policies === undefined ? {} : { policies }),
-        ...(personas === undefined ? {} : { personas }),
         ...(defaults === undefined ? {} : { defaults }),
         ...(review === undefined ? {} : { review }),
         ...(config.execution?.desktop === undefined && config.execution?.target === undefined
@@ -43,8 +43,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) {
+    const caps = capsOf(config);
     return {
         ...(caps?.maxUsd === undefined ? {} : { maxUsd: caps.maxUsd }),
         ...(caps?.maxTotalUsd === undefined ? {} : { maxTotalUsd: caps.maxTotalUsd }),
@@ -86,7 +86,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 +99,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.d.ts

@@ -9,7 +9,7 @@ export interface Participant {
     readonly id: string;
     /** 0-based position in the roster. Bundle `sim-NNN` and `stream-NNN` ids derive from it. */
     readonly index: number;
-    /** `lanes[i].persona ?? actors[0].persona`. The route compiles the committed persona file. */
+    /** `participants[i].persona ?? actor.persona`. The route compiles the committed persona file. */
     readonly personaId: string | undefined;
     /** The declared mission and per-participant focus. An absent mission takes the route's default. */
     readonly assignment: {
@@ -30,7 +30,7 @@ interface DesktopParticipant extends Participant {
         readonly preset: DevicePreset;
         readonly resolution: [number, number];
     };
-    /** The `lanes[]` entry's value, else actor value, else absent (the provider default is recorded in the trace). */
+    /** The `participants` entry's value, else actor value, else absent (the provider default is recorded in the trace). */
     readonly limits: {
         readonly stopWhen?: StopWhen;
         readonly dwell?: DwellWindow;

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-types.d.ts

@@ -8,7 +8,7 @@ import type { RunStudyProvenance } from "../run/study-provenance.js";
 import type { ComputerUseRefusal } from "../routes/computer-use/plan.js";
 import type { SharedWorldRefusal } from "../routes/shared-world/plan.js";
 import type { ComputerUseParticipant, ExternalPublicParticipant, ProvisionedParticipant } from "./plan-participants.js";
-import type { StudyConfig, StudyExecutionTerminal, StudyRuntimeAuth, StudyScenarioCaps, StudySubjectProduct, StudySubjectServe, StudySubjectState, StudySubjectStateCheckpoint } from "./types.js";
+import type { StudyConfig, StudyExecutionTerminal, StudyRuntimeAuth, StudyCaps, StudySubjectProduct, StudySubjectServe, StudySubjectState, StudySubjectStateCheckpoint } from "./types.js";
 export type NonEmpty<T> = readonly [T, ...T[]];
 type AtLeastTwo<T> = readonly [T, T, ...T[]];
 /**
@@ -48,7 +48,7 @@ export type Requirement = {
  * VM study read it before a plan exists. Shared world, terminal and scripted still read some config
  * fields at run time.
  */
-export type ResidualConfig = Pick<StudyConfig, "comms" | "policies" | "personas" | "defaults" | "review"> & {
+export type ResidualConfig = Pick<StudyConfig, "comms" | "policies" | "defaults" | "review"> & {
     readonly execution?: Pick<NonNullable<StudyConfig["execution"]>, "desktop" | "target">;
     readonly subject: Pick<StudyConfig["subject"], "clone" | "localTree" | "repos" | "envValues">;
 };
@@ -83,7 +83,7 @@ interface PreviewPlan extends PlanBase {
 }
 /**
  * The model driving a desktop participant. `caller` is the library caller's createProvider.
- * `declaredModel` is actors[0].model as the study wrote it, absent when undeclared: the providers
+ * `declaredModel` is actor.model as the study wrote it, absent when undeclared: the providers
  * take it as written, and spend is priced at it, else the default (pricedModel). An openai
  * brain's `model` is the one its provider runs, with that default applied.
  */
@@ -229,10 +229,10 @@ export type TerminalPlan = PlanBase & {
     readonly stdin?: NonNullable<StudyExecutionTerminal["stdin"]>;
 } & ({
     readonly dryRun: true;
-    readonly caps?: StudyScenarioCaps;
+    readonly caps?: StudyCaps;
 } | {
     readonly dryRun: false;
-    readonly caps: StudyScenarioCaps & {
+    readonly caps: StudyCaps & {
         readonly maxUsd: number;
         readonly maxMinutes: number;
     };

package/dist/study/plan.js

@@ -1,5 +1,5 @@
 // The route decision. A study's route follows from its composition (subject.source,
-// execution.target, the first actor's registered run kind, subject.topology), never from a
+// execution.target, the actor's registered run kind, `route: shared-world`), never from a
 // declared kind. This is the only function that decides it.
 import { resolveAutomaticAnalysis } from "../analysis/automatic-config.js";
 import { callerDrivingOf, planComputerUseStudy } from "../routes/computer-use/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;
@@ -25,7 +25,7 @@ export async function runPublicPreviewPreflight(ctx) {
             { name: "route", ok: false, message: routeError },
         ]);
     }
-    const rosterTargets = ctx.targets.filter((target) => target.kind === "actors[0].lanes[].target");
+    const rosterTargets = ctx.targets.filter((target) => target.kind === "participants[].target");
     const publicTargets = rosterTargets.length > 0
         ? rosterTargets
         : ctx.targets.filter((target) => target.kind === "subject.appUrl");
@@ -270,8 +270,8 @@ function targetUrlFor(config, target) {
     if (target.kind === "subject.appUrl" && config.subject.appUrl) {
         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;
+    if (target.kind === "participants[].target") {
+        const rosterTarget = participantList(config)?.find((entry) => entry.target && digest(entry.target) === target.targetDigest)?.target;
         if (rosterTarget)
             return rosterTarget;
     }

package/dist/study/preflight.d.ts

@@ -12,7 +12,7 @@ export interface StudyPreflightCheck {
 }
 export interface StudyPreflightTarget {
     label: string;
-    kind: "subject.appUrl" | "actors[0].lanes[].target" | "subject.serve.url" | "subject.product.publicSurface";
+    kind: "subject.appUrl" | "participants[].target" | "subject.serve.url" | "subject.product.publicSurface";
     targetDigest: string;
     originDigest?: string;
     loopback: boolean;

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,9 +82,9 @@ 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));
+            targets.push(makeTarget(`participants[${index}].target`, "participants[].target", entry.target));
         }
     }
     if (config.subject.serve?.url) {

package/dist/study/routing.d.ts

@@ -9,8 +9,8 @@ export declare function registeredScriptedBrowserActors(): string[];
 export declare function actorResolvesToTerminal(type: string | undefined): boolean;
 export declare function registeredTerminalActors(): string[];
 /**
- * The declared fan-out participant count on the computer-use route: a `lanes[]` roster's length, else
- * a homogeneous `count`, else 1. The single source of truth shared by the parser, the engine,
+ * The declared fan-out participant count on the computer-use route: a `participants` list's
+ * length, else a participant count, else 1. The single source of truth shared by the parser, the engine,
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
 export declare function computerUseParticipantCount(config: StudyConfig): number;
@@ -36,15 +36,15 @@ export declare function isComputerUseComposition(config: StudyConfig): boolean;
  * `shared-world` topology. Mirror of isComputerUseComposition; the single source of truth shared by
  * routeOf (which checks it before the computer-use route) and the warning logic. Every
  * shared-world study runs its participants at once (`execution.concurrency` >= 2). The same
- * clone/local-tree × e2b-desktop × computer-use composition without `topology: shared-world` stays per-lane-worlds
- * (the computer-use route); the topology declaration is the override switch.
+ * clone/local-tree × e2b-desktop × computer-use composition without `route: shared-world` stays per-lane-worlds
+ * (the computer-use route); the route declaration is the override switch.
  */
 export declare function isSharedWorldComposition(config: StudyConfig): boolean;
 /** The getHost provisioned-subject shared-world shape (clone/local-tree served + exposed in-sandbox). */
 export declare function isProvisionedSharedWorldComposition(config: StudyConfig): boolean;
 /**
  * The external-public shared-world shape: a real public deployment used directly as
- * the shared plane: `source: app-url` + `topology: shared-world` + a computer-use actor on
+ * the shared plane: `source: app-url` + `route: shared-world` + a computer-use actor on
  * e2b-desktop + `policies.allowPublicTargets: true`. No getHost, no clone, no subject sandbox, no
  * seed. The operator-ownership attestation `subject.publicTarget` is required (validated in
  * externalPublicSharedWorldValidationReason, not here; this predicate is the router only, so a