humanish 0.110.3 → 0.111.0

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;
@@ -45,16 +46,12 @@ export function registeredTerminalActors() {
     return registeredActorsOn("terminal");
 }
 /**
- * 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 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
@@ -99,8 +96,8 @@ export function isComputerUseComposition(config) {
  * `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 function isSharedWorldComposition(config) {
     return (isProvisionedSharedWorldComposition(config) || isExternalPublicSharedWorldComposition(config));
@@ -108,13 +105,13 @@ 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
- * 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
@@ -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.d.ts

@@ -4,7 +4,7 @@ import type { StudyConfig } from "./types.js";
 import { type StudyEvent } from "./run-study-events.js";
 type Refusal = {
     ok: false;
-    code: "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED";
+    code: "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID";
     message: string;
 };
 type Normalized = {

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

@@ -27,7 +27,7 @@ export interface StudyDeps {
     readonly subjectPhaseSink?: (event: SubjectPhaseEvent, participant?: ParticipantRef) => void;
     /**
      * Shared world: runs each participant's computer-use session in place of the actor's own. The
-     * planner reads whether it is set: a custom runner cannot enforce actors[0].maxOutputTokens.
+     * planner reads whether it is set: a custom runner cannot enforce actor.maxOutputTokens.
      */
     readonly runSession?: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
     /**

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

@@ -0,0 +1,19 @@
+import type { StudyActor, StudyCaps, StudyConfig, StudyParticipantEntry } from "./types.js";
+/** The actor that runs. */
+export declare function actorOf(config: StudyConfig): StudyActor | undefined;
+/** The participants listed one by one: a `participants` list. Undefined when none is listed. */
+export declare function participantList(config: StudyConfig): readonly StudyParticipantEntry[] | undefined;
+/** The declared number of identical participants: `participants: <n>` or `participants.count`. */
+export declare function declaredParticipantCount(config: StudyConfig): number | undefined;
+/** The steer each of a counted group of participants gets: `participants.instruction`. */
+export declare function participantInstruction(config: StudyConfig): string | undefined;
+/** How many scripted surfaces run, 1 for desktop and 2 with mobile. */
+export declare function surfaceCount(config: StudyConfig): number | undefined;
+/** The declared run mode. */
+export declare function modeOf(config: StudyConfig): StudyConfig["mode"];
+/** The scripted route's scenario id or path. */
+export declare function scenarioRefOf(config: StudyConfig): string | undefined;
+/** The spend caps the route enforces. parseStudy refuses a key the route does not read. */
+export declare function capsOf(config: StudyConfig): StudyCaps | undefined;
+/** True when the participants share one app: `route: shared-world`. */
+export declare function declaresSharedWorld(config: StudyConfig): boolean;

package/dist/study/study-fields.js

@@ -0,0 +1,46 @@
+// The study's fields, read in one place. Participants are the one read that is not a field: a v3
+// study declares them as a count, as `{ count, instruction }` or as a list, and the accessors below
+// read each form. tests/surface/study-config-reads.test.ts refuses a direct read of a humanish.lab.v2
+// field anywhere outside migrate.
+/** The actor that runs. */
+export function actorOf(config) {
+    return config.actor;
+}
+/** The participants listed one by one: a `participants` list. Undefined when none is listed. */
+export function participantList(config) {
+    return Array.isArray(config.participants) ? config.participants : undefined;
+}
+/** The declared number of identical participants: `participants: <n>` or `participants.count`. */
+export function declaredParticipantCount(config) {
+    const { participants } = config;
+    if (typeof participants === "number")
+        return participants;
+    return isGroup(participants) ? participants.count : undefined;
+}
+/** The steer each of a counted group of participants gets: `participants.instruction`. */
+export function participantInstruction(config) {
+    return isGroup(config.participants) ? config.participants.instruction : undefined;
+}
+/** How many scripted surfaces run, 1 for desktop and 2 with mobile. */
+export function surfaceCount(config) {
+    return config.surfaces?.length;
+}
+/** The declared run mode. */
+export function modeOf(config) {
+    return config.mode;
+}
+/** The scripted route's scenario id or path. */
+export function scenarioRefOf(config) {
+    return config.scenario;
+}
+/** The spend caps the route enforces. parseStudy refuses a key the route does not read. */
+export function capsOf(config) {
+    return config.caps;
+}
+/** True when the participants share one app: `route: shared-world`. */
+export function declaresSharedWorld(config) {
+    return config.route === "shared-world";
+}
+function isGroup(participants) {
+    return typeof participants === "object" && participants !== null && !Array.isArray(participants);
+}

package/dist/study/summary.js

@@ -18,7 +18,7 @@ import { inspectStudyManifest } from "./discover.js";
 import { isComputerUseComposition } from "./routing.js";
 import { probeKeySources } from "../keys/key-resolution.js";
 import { receivingRequiredKey } from "../comms/setup.js";
-import { rosterOf } from "./parse/actors.js";
+import { actorOf, participantList, declaredParticipantCount, capsOf, surfaceCount, } from "./study-fields.js";
 export const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
 /**
  * The effort every participant will run at, or `"per-lane"` when they differ. A participant that declares nothing
@@ -26,10 +26,8 @@ export const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
  * reported as the resolved value, exactly as `model` reports its default rather than hiding it.
  */
 function reasoningEffortOf(config) {
-    const actors = config.actors;
-    const actor = actors?.[0];
-    const fallback = actor?.reasoningEffort ?? DEFAULT_OPENAI_CU_REASONING_EFFORT;
-    const roster = rosterOf(actor) ?? [];
+    const fallback = actorOf(config)?.reasoningEffort ?? DEFAULT_OPENAI_CU_REASONING_EFFORT;
+    const roster = participantList(config) ?? [];
     const resolved = new Set(roster.map((entry) => entry.reasoningEffort ?? fallback));
     if (resolved.size > 1)
         return "per-lane";
@@ -49,15 +47,19 @@ function subjectOf(config) {
 }
 /** How many participants, and who; collapsed when they are all the same persona. */
 function participantsOf(config) {
-    const actors = config.actors;
-    const actor = actors?.[0];
+    const actor = actorOf(config);
     if (actor === undefined)
         return undefined;
-    const rosterPersonas = (rosterOf(actor) ?? [])
+    const rosterPersonas = (participantList(config) ?? [])
         .map((entry) => entry.persona)
         .filter((persona) => typeof persona === "string");
     const personas = rosterPersonas.length > 0 ? rosterPersonas : actor.persona === undefined ? [] : [actor.persona];
-    const count = actor.count ?? rosterOf(actor)?.length ?? personas.length ?? 1;
+    // A scripted study's participants are its surfaces, one replay on each.
+    const count = declaredParticipantCount(config) ??
+        surfaceCount(config) ??
+        participantList(config)?.length ??
+        personas.length ??
+        1;
     const unique = [...new Set(personas)];
     if (unique.length === 0)
         return `${count} participant${count === 1 ? "" : "s"}`;
@@ -65,11 +67,11 @@ function participantsOf(config) {
     // are named, because which personas are in a study is the study's design.
     return unique.length === 1 ? `${count} × ${unique[0]}` : unique.join(" · ");
 }
-/** The computer-use caps; `execution.caps` is inert on other routes, so none is drawn there. */
-function capsOf(config) {
+/** The computer-use caps. Other routes draw none. */
+function summaryCapsOf(config) {
     if (!isComputerUseComposition(config))
         return {};
-    const caps = config.execution?.caps;
+    const caps = capsOf(config);
     return {
         ...(typeof caps?.maxUsd === "number" ? { laneUsd: caps.maxUsd } : {}),
         ...(typeof caps?.maxTotalUsd === "number" ? { studyUsd: caps.maxTotalUsd } : {}),
@@ -84,7 +86,6 @@ export async function readStudySummary(cwd, study, options = {}) {
     if (inspected === null || !inspected.ok || inspected.config === undefined)
         return null;
     const config = inspected.config;
-    const actors = config.actors;
     const route = routeOf(inspected.config);
     let keysReady;
     let missingKeys;
@@ -128,7 +129,7 @@ export async function readStudySummary(cwd, study, options = {}) {
     // Computed once: a test-then-use pair reads as though the two calls could differ.
     const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route);
     const subject = subjectOf(config);
-    const participants = participantsOf(config);
+    const participants = participantsOf(inspected.config);
     const runtime = options.checkKeys === true && isLocalBrowserStudy(inspected.config)
         ? await localRuntimeStatus({
             ...(options.env ? { env: options.env } : {}),
@@ -138,7 +139,7 @@ export async function readStudySummary(cwd, study, options = {}) {
         : undefined;
     const participantReadiness = options.checkKeys === true &&
         isLocalBrowserStudy(inspected.config) &&
-        inspected.config.actors[0]?.type === "local-agent"
+        actorOf(inspected.config)?.type === "local-agent"
         ? await localCodexParticipantCheck({ env: options.env ?? process.env })
         : undefined;
     return {
@@ -165,9 +166,9 @@ export async function readStudySummary(cwd, study, options = {}) {
         ...(typeof config.description === "string" ? { description: config.description.trim() } : {}),
         ...(subject === undefined ? {} : { subject }),
         ...(participants === undefined ? {} : { participants }),
-        model: actors?.[0]?.model ?? DEFAULT_OPENAI_CU_MODEL,
-        reasoningEffort: reasoningEffortOf(config),
-        caps: capsOf(inspected.config),
+        model: actorOf(inspected.config)?.model ?? DEFAULT_OPENAI_CU_MODEL,
+        reasoningEffort: reasoningEffortOf(inspected.config),
+        caps: summaryCapsOf(inspected.config),
         ...(keysReady === undefined ? {} : { keysReady }),
         ...(missingKeys === undefined ? {} : { missingKeys }),
         ...(planRefusal === undefined ? {} : { planRefusal }),

package/dist/study/types.d.ts

@@ -2,7 +2,7 @@ import { type StudyAnalysis } from "../analysis/automatic-config.js";
 import type { StudyTask } from "./tasks.js";
 import type { DwellWindow, StopWhen } from "../actors/stop-conditions.js";
 import { type ReasoningEffort } from "../actors/reasoning-effort.js";
-export declare const V2_SCHEMA = "humanish.lab.v2";
+import type { StudyRoute } from "./routing.js";
 /** The study format: it declares its route, one actor, its participants and one caps block. */
 export declare const STUDY_SCHEMA = "humanish.study.v3";
 export declare const ID_PATTERN: RegExp;
@@ -17,16 +17,6 @@ export declare const ID_PATTERN: RegExp;
  * error, never a desktop attempt. See docs/architecture/state-driven-executor.md.
  */
 type StudySubjectSource = "this-repo" | "clone" | "app-url" | "local-app" | "terminal-product" | "desktop-cli" | "local-tree";
-/**
- * How a subject's world relates across participants. `per-lane-worlds` (the default; absent ==
- * this) is the only fan-out topology the computer-use route ships: N participants, N independent
- * worlds, isolation + per-participant attribution. `shared-world` is the declared override: one
- * mutable service plane that N participants use at the same time, so their actions interact through
- * shared state. Consumed only on the shared-world routes (a provisioned clone plane, or an
- * external-public app-url plane) with a computer-use actor; inert/warned everywhere else
- * (claims match mechanism).
- */
-type StudySubjectTopology = "per-lane-worlds" | "shared-world";
 export interface StudySubjectClone {
     /** git clone depth; 1 (shallow) by default. Consumed on the computer-use clone route. */
     depth?: number;
@@ -188,26 +178,18 @@ export interface StudySubjectProduct {
 }
 export interface StudySubject {
     source: StudySubjectSource;
-    /**
-     * World topology across participants. Absent == `per-lane-worlds` (the isolation default; every
-     * existing study is byte-stable). `shared-world` is the declared override: one mutable service
-     * plane, N participants at once, each in its role. Consumed only on the shared-world routes (a
-     * provisioned clone or an external-public app-url plane, a computer-use actor, and a roster of ≥2
-     * participants); inert/warned elsewhere.
-     */
-    topology?: StudySubjectTopology;
     /**
      * Concurrent shared-world route only: the author's required attestation that the
      * subject behind the internet-reachable `getHost` URL is synthetic seeded data. The concurrent
      * route exposes the subject on a tokenless public URL for the run's duration, so real/external
      * data must never sit behind it. This is author-trust + a provenance gate (verify also requires
      * `subject.state.provenance == "seeded"`). It does not guarantee the data is synthetic. Required when
-     * `topology: shared-world` + `execution.concurrency > 1`; inert/warned elsewhere.
+     * `route: shared-world` + `execution.concurrency > 1`; inert/warned elsewhere.
      */
     exposure?: "synthetic";
     /**
      * External-public shared-world route only: the author's required ownership
-     * attestation when a real public deployment (`source: app-url` + `topology: shared-world` +
+     * attestation when a real public deployment (`source: app-url` + `route: shared-world` +
      * `concurrency > 1` + `policies.allowPublicTargets: true`) is used directly as the shared plane.
      * The harness neither provisions nor exposes this target (no getHost, no clone, no seed), so it
      * cannot attest the data is synthetic; instead the operator must attest they own/operate it.
@@ -275,12 +257,6 @@ export interface StudySubject {
      */
     localTree?: StudySubjectLocalTree;
 }
-export interface StudyParticipantFocus {
-    id?: string;
-    label?: string;
-    /** Per-participant steer appended to the actor's mission. Consumed on the app-url route. */
-    instruction?: string;
-}
 /**
  * One participant in a differentiated fan-out on the computer-use E2B route (`per-lane-worlds`).
  * Each entry becomes an independent E2B desktop sandbox with its own persona/device/starting-steer. All
@@ -293,7 +269,7 @@ export interface StudyParticipantEntry {
     id?: string;
     /**
      * App-defined actor type label for grouping simulated users ("operator", "viewer",
-     * "maintainer", etc.). It is separate from the execution actor dispatch key (`actors[0].type`);
+     * "maintainer", etc.). It is separate from the execution actor dispatch key (`actor.type`);
      * it is adapter-owned taxonomy for roster/readback.
      */
     actorType?: string;
@@ -301,7 +277,7 @@ export interface StudyParticipantEntry {
     surface?: string;
     /** App-defined correlation id tying participants to one shared case/account/work item. */
     caseGroup?: string;
-    /** Persona id/label threaded into this participant's actor prompt. Default: actors[0].persona. */
+    /** Persona id/label threaded into this participant's actor prompt. Default: actor.persona. */
     persona?: string;
     /** Named hosted-screen preset for this participant. XOR raw execution.desktop.resolution. */
     device?: string;
@@ -344,17 +320,6 @@ export interface StudyParticipantEntry {
      */
     host?: boolean;
 }
-/**
- * Compact authoring sugar for repeated participant groups. The parser expands each group into concrete
- * `lanes[]` with deterministic ids (`<group.id>-01`, `<group.id>-02`, ...). The runtime never
- * consumes this shape directly; it always sees ordinary `LabActorLane` entries.
- */
-export interface StudyActorRosterGroup extends Omit<StudyParticipantEntry, "id"> {
-    /** Public-safe group id; prefixes generated participant ids. */
-    id: string;
-    /** Number of participants to generate for this group. */
-    count: number;
-}
 export interface StudyActor {
     /**
      * The actor label. On computer-use (including shared-world), scripted-browser, and
@@ -364,18 +329,8 @@ export interface StudyActor {
      * the descriptor for dispatch and capability enforcement.
      */
     type: string;
-    /** Participant count, route-specific (see the scope header in config.ts): synthetic simCount; scripted
-     *  surface roster {1 = desktop, 2 = desktop + mobile, default 1}; computer-use E2B route the
-     *  homogeneous fan-out participant count (cap 16). XOR `lanes`. */
-    count?: number;
-    /** Computer-use E2B route: a differentiated fan-out roster (`per-lane-worlds`). XOR `count`,
-     *  `roster`, and `laneFocus`. Cap 16 participants. Consumed only on the cua E2B route
-     *  (inert/warned elsewhere). */
-    lanes?: StudyParticipantEntry[];
     /** Persona id/label threaded into the actor prompt. Consumed on the app-url route. */
     persona?: string;
-    /** Consumed on the app-url route (laneFocus.instruction appended to the mission). XOR `lanes`. */
-    laneFocus?: StudyParticipantFocus;
     /** Free-form mission threaded into the actor prompt. Consumed on the app-url route. A mission on
      *  its own is a complete, valid study; `tasks` is additive, never required. */
     mission?: string;
@@ -403,7 +358,7 @@ export interface StudyActor {
      */
     localAgent?: "codex" | "claude";
     /**
-     * How hard the model is asked to think, per turn. A `lanes[]` entry's `reasoningEffort` overrides this.
+     * How hard the model is asked to think, per turn. A `participants` entry's `reasoningEffort` overrides this.
      *
      * Absent means the provider's default, and absence is recorded as absence: a run that did not
      * declare an effort does not claim one. Support is model-dependent (see src/actors/reasoning-effort.ts),
@@ -418,12 +373,12 @@ export interface StudyActor {
      */
     reasoningEffort?: ReasoningEffort;
     /**
-     * Deterministic completion guard used as the default for CUA participants. A `lanes[]` entry's stopWhen
+     * Deterministic completion guard used as the default for CUA participants. A `participants` entry's stopWhen
      * overrides this value.
      */
     stopWhen?: StopWhen;
     /**
-     * A declared observation window, the default for every participant; a `lanes[]` entry's dwell overrides
+     * A declared observation window, the default for every participant; a `participants` entry's dwell overrides
      * it. `when` is a stopWhen-shaped condition (absent: the window opens after the first
      * observation); `ms` is the hold, `everyMs` the frame cadence (default 10 s), `then` whether
      * the participant continues afterwards (default) or the session ends. The harness takes no
@@ -544,20 +499,6 @@ export interface StudyExecution {
      */
     concurrency?: number;
     desktop?: StudyExecutionDesktop;
-    /**
-     * Blast-radius budget for each computer-use participant. Consumed on the computer-use route:
-     * `caps.maxUsd`, when set, is a fail-closed abort: the session stops the moment its running
-     * estimated spend crosses it (the runaway-retry guard), and a cap on a model src/run/pricing.ts
-     * cannot price is refused at preflight rather than run uncapped. It is a per-participant cap:
-     * enforced inside each participant's loop, so an N-participant fan-out can spend up to N × maxUsd
-     * before any participant aborts (the run warns with the true ~N × cap ceiling).
-     * `caps.maxTotalUsd` is the shared study budget: one ledger across every participant, the knob a
-     * researcher actually reasons with. Absent = uncapped (the historical CUA behavior); maxUsd: 0
-     * still permits a request before reported usage trips it. Inert (warned) on non-computer-use
-     * routes. Reuses the same StudyScenarioCaps shape as the terminal route's `scenario.caps` (not a
-     * fork).
-     */
-    caps?: StudyScenarioCaps;
     /** `terminal-product` route: the terminal transport + stdin posture. Consumed on that route. */
     terminal?: StudyExecutionTerminal;
     /** `terminal-product` route: runtime key placement, defaulting to openai-egress, an external
@@ -583,48 +524,45 @@ export interface StudyExecution {
      */
     egressAllow?: string[];
 }
-type StudyScenarioMode = "dry-run" | "live";
+type StudyMode = "dry-run" | "live";
 /**
- * The blast-radius budget for a route that passes a live key to an in-sandbox command.
- * Per the safety contract, the live key is never exercised without a fail-closed cap in force.
- * All values are non-negative numbers (0 is the no-spend default). Live runs require maxUsd and a
- * positive maxMinutes; maxUsd/maxJobs are checked after the session against known ledger signals
- * and maxMinutes is enforced as the command wall clock. Codex tokens are unpriced, so a live run
- * refuses a positive maxUsd unless a costProbe measures spend (HUMANISH_TERMINAL_UNPRICED_CAP).
+ * A study's spend, job and time caps, the top-level `caps` block. Each route reads its own keys, and
+ * parseStudy refuses a key the route does not read. All values are non-negative numbers.
+ *
+ * Computer use and shared world read `maxUsd` and `maxTotalUsd`. `maxUsd`, when set, is a
+ * fail-closed abort for each participant: the session stops the moment its running estimated spend
+ * crosses it (the runaway-retry guard), and a cap on a model src/run/pricing.ts cannot price is
+ * refused at preflight rather than run uncapped. It is enforced inside each participant's loop, so
+ * an N-participant fan-out can spend up to N × maxUsd before any participant aborts (the run warns
+ * with the true ~N × cap ceiling). Absent = uncapped; maxUsd: 0 still permits a request before
+ * reported usage trips it.
+ *
+ * The terminal route passes a live key to an in-sandbox command, and per the safety contract the
+ * live key is never exercised without a fail-closed cap in force. It reads `maxUsd`, `maxJobs` and
+ * `maxMinutes` (0 is the no-spend default). Live runs require maxUsd and a positive maxMinutes;
+ * maxUsd/maxJobs are checked after the session against known ledger signals and maxMinutes is
+ * enforced as the command wall clock. Codex tokens are unpriced, so a live run refuses a positive
+ * maxUsd unless a costProbe measures spend (HUMANISH_TERMINAL_UNPRICED_CAP).
  */
-export interface StudyScenarioCaps {
+export interface StudyCaps {
     /** Max USD the run may spend (provider + product). 0 = no-spend. */
     maxUsd?: number;
     /**
      * study-level model-spend budget, the number a researcher actually reasons with: "this
      * study is N participants, roughly $X", decided once, up front, where recruiting decisions are
-     * made. The computer-use route reads it from `execution.caps.maxTotalUsd` only: every participant's
-     * running estimated model spend feeds one shared ledger, and the moment the run total crosses
-     * this, each participant stops at its next turn with `budget_reached` (status `incomplete`:
-     * the participant ran out of budget; never `gave_up`, because a study-level stop is not the
-     * participant's doing). Estimated model spend only; desktop-minutes ride the cost summary but
-     * not this ledger. Independent of the per-participant `maxUsd` backstop; either, both, or neither may
-     * be set. A positive `scenario.caps.maxTotalUsd` on a computer-use study is a parse error; on the
-     * terminal route it is inert (warned), since the single agent's maxUsd already caps the run.
+     * made. Computer use and shared world only: every participant's running estimated model spend
+     * feeds one shared ledger, and the moment the run total crosses this, each participant stops at
+     * its next turn with `budget_reached` (status `incomplete`: the participant ran out of budget;
+     * never `gave_up`, because a study-level stop is not the participant's doing). Estimated model
+     * spend only; desktop-minutes ride the cost summary but not this ledger. Independent of the
+     * per-participant `maxUsd` backstop; either, both, or neither may be set.
      */
     maxTotalUsd?: number;
-    /** Max billable product jobs the agent may trigger. 0 = none. */
+    /** Terminal: max billable product jobs the agent may trigger. 0 = none. */
     maxJobs?: number;
-    /** Max wall-clock minutes for the agent session. */
+    /** Terminal: max wall-clock minutes for the agent session. */
     maxMinutes?: number;
 }
-export interface StudyScenario {
-    /** Reference a committed scenario by id (humanish/scenarios/<ref>.yaml) or path. Consumed
-     *  (and required) on the scripted-browser route; forward-declared elsewhere. */
-    ref?: string;
-    /** Or inline the scenario body. Forward-declared: no route reads it yet, so a set value warns. */
-    inline?: Record<string, unknown>;
-    /** dry-run = a synthetic bundle with no provider spend; live = real run. Consumed. */
-    mode?: StudyScenarioMode;
-    /** Spend/job/time caps. Consumed (recorded in the bundle) on the terminal-product route;
-     *  inert (warned) elsewhere. */
-    caps?: StudyScenarioCaps;
-}
 export interface StudyPolicies {
     /**
      * Redact target repo labels in durable artifacts. Consumed on the computer-use,
@@ -721,7 +659,7 @@ export interface StudyCommsReceivingEmail {
 interface StudyCommsCaptureEmail {
     connection?: never;
     allowedOrigins?: never;
-    /** Which implementation backs the inbox (a backend discriminator, distinct from `scenario.mode`):
+    /** Which implementation backs the inbox (a backend discriminator, distinct from `mode`):
      *  `fake` (default) is an in-harness in-memory inbox in the Fowler test-double sense: an in-sandbox
      *  catch captures the app's sends. Provider-backed receiving uses the separate
      *  StudyCommsReceivingEmail configuration selected by a saved connection. */
@@ -788,23 +726,47 @@ export interface StudyCommsRecipient {
      *  for the persona surface's default address (not drain-matched). */
     address?: string;
 }
+/**
+ * A humanish.study.v3 study as parseStudy returns it, with the keys the file has: the declared
+ * route, one actor, its participants and one caps block.
+ */
 export interface StudyConfig {
-    /** The format the file was written in. Both parse into this one shape. */
-    schema: typeof V2_SCHEMA | typeof STUDY_SCHEMA;
+    schema: typeof STUDY_SCHEMA;
     id: string;
     title?: string;
     description?: string;
+    /** The route the study declares. parseStudy refuses one its subject and actor do not take. */
+    route: StudyRoute;
+    /** Absent: a dry run. */
+    mode?: StudyMode;
     subject: StudySubject;
-    actors: StudyActor[];
+    actor: StudyActor;
+    /** Preview, computer-use and shared-world, in the form the file used. */
+    participants?: StudyParticipants;
+    /** Scripted only. */
+    surfaces?: StudySurfaces;
+    /** The caps keys the route reads. */
+    caps?: StudyCaps;
     execution?: StudyExecution;
-    /** Forward-declared: no route reads it yet, so a set value warns. */
-    personas?: Record<string, unknown>[];
-    scenario?: StudyScenario;
+    /** Scripted: a committed scenario id or path. */
+    scenario?: string;
     policies?: StudyPolicies;
     review?: StudyReview;
     defaults?: StudyDefaults;
     comms?: StudyComms;
 }
+/**
+ * A count, a count with one instruction for every participant, or a list. parseStudy expands a list
+ * entry with a `count` into its participants, `<id>-01` to `<id>-NN`.
+ */
+type StudyParticipants = number | StudyParticipantGroup | StudyParticipantEntry[];
+/** `participants` as identical participants that share one instruction. */
+export interface StudyParticipantGroup {
+    count?: number;
+    instruction?: string;
+}
+/** The scripted surfaces: desktop, or desktop and mobile. */
+export type StudySurfaces = readonly ["desktop"] | readonly ["desktop", "mobile"];
 interface StudyParseSuccess {
     ok: true;
     config: StudyConfig;

package/dist/study/types.js

@@ -1,6 +1,5 @@
 import {} from "../analysis/automatic-config.js";
 import {} from "../actors/reasoning-effort.js";
-export const V2_SCHEMA = "humanish.lab.v2";
 /** The study format: it declares its route, one actor, its participants and one caps block. */
 export const STUDY_SCHEMA = "humanish.study.v3";
 // Must start alphanumeric so an id never collides with the path-vs-id resolver heuristic