humanish 0.110.4 → 0.111.0

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

@@ -1,12 +1,5 @@
 import type { StudyRoute } from "../routing.js";
-import { type StudyParseFailure } from "../types.js";
-export interface StudyDocument {
-    readonly route: StudyRoute;
-    /** The same document in the humanish.lab.v2 spelling. */
-    readonly v2: Record<string, unknown>;
-    /** For each expanded participant, the index of the `participants` entry it came from. */
-    readonly participantSource: readonly number[];
-}
+import type { StudyParseFailure, StudySurfaces } from "../types.js";
 /** A document's `participants`, read before the participant entries parse. */
 export interface Participants {
     count?: number;
@@ -21,15 +14,16 @@ export interface StudyFront {
     readonly route: StudyRoute;
     readonly actor: Record<string, unknown>;
     readonly participants: Participants;
-    /** The scripted surfaces as a count: 1 is desktop, 2 adds mobile. */
-    readonly surfaces: number | undefined;
+    readonly surfaces: StudySurfaces | undefined;
 }
 type Parsed<T> = {
     ok: true;
     value: T;
 } | StudyParseFailure;
-/** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
-export declare function studyToV2(raw: Record<string, unknown>): Parsed<StudyDocument>;
+/** The refusal for a study with no `actor` object. */
+export declare const ACTOR_REQUIRED = "A study needs `actor:`, an object with at least `type`.";
+/** Why `route` is not a route a study can declare, or undefined when it is one. */
+export declare function routeNameReason(route: unknown): string | undefined;
 /**
  * The checks a v3 document passes before its sections parse: no v2 key and no unknown key, a
  * route, a mode, an `actor` object, a scenario string, and the `participants`, `surfaces` and
@@ -39,9 +33,4 @@ export declare function studyToV2(raw: Record<string, unknown>): Parsed<StudyDoc
  * parser does.
  */
 export declare function readStudyFront(raw: Record<string, unknown>, anySharedWorldParticipants?: boolean): Parsed<StudyFront>;
-/**
- * Spell a v2 parser message the way the study file is written: `actors[0].lanes[3]` becomes the
- * `participants` entry it came from, `execution.caps` and `scenario.caps` become `caps`, and so on.
- */
-export declare function studySpelling(message: string, route: StudyRoute, participantSource: readonly number[]): string;
 export {};

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,53 +22,13 @@ 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) {
-    const front = readStudyFront(raw);
-    if (!front.ok)
-        return front;
-    const { route } = front.value;
-    const { count, instruction, entries, source } = front.value.participants;
-    // The v2 actor keys that hold participants.
-    const v2Participants = [
-        ["count", count ?? front.value.surfaces],
-        ["laneFocus", instruction === undefined ? undefined : { instruction }],
-        ["lanes", entries],
-    ];
-    const actor = { ...front.value.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 } };
+/** 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
@@ -88,28 +46,26 @@ export function readStudyFront(raw, anySharedWorldParticipants = false) {
     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(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.");
     }
@@ -118,24 +74,6 @@ export function readStudyFront(raw, anySharedWorldParticipants = false) {
         value: { route, actor: raw.actor, participants: participants.value, surfaces: surfaces.value },
     };
 }
-/**
- * Spell a v2 parser message the way the study file is written: `actors[0].lanes[3]` becomes the
- * `participants` entry it came from, `execution.caps` and `scenario.caps` become `caps`, and so on.
- */
-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"));
-}
 // The v2 keys a hand-converted file is most likely to keep, each with where it went.
 function movedKeyReason(raw) {
     if (raw.actors !== undefined) {
@@ -212,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 = [];
@@ -241,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].");
 }
@@ -268,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.js

@@ -5,8 +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 { actorsOf } from "./study-fields.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`). */
@@ -87,13 +86,12 @@ export async function resolveCommittedPersonas(projectRoot, personaIds) {
  */
 export function studyPersonaIds(config) {
     const ids = [];
-    for (const actor of actorsOf(config)) {
-        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 planCaps(config: StudyConfig, route: "computer-use" | "shared-world"): 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

@@ -14,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
@@ -44,8 +43,8 @@ function residualOf(config) {
 export function isNonEmpty(values) {
     return values.length > 0;
 }
-export function planCaps(config, route) {
-    const caps = capsOf(config, route);
+export function planCaps(config) {
+    const caps = capsOf(config);
     return {
         ...(caps?.maxUsd === undefined ? {} : { maxUsd: caps.maxUsd }),
         ...(caps?.maxTotalUsd === undefined ? {} : { maxTotalUsd: caps.maxTotalUsd }),

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-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";

package/dist/study/preflight-probes.js

@@ -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,7 +270,7 @@ function targetUrlFor(config, target) {
     if (target.kind === "subject.appUrl" && config.subject.appUrl) {
         return config.subject.appUrl;
     }
-    if (target.kind === "actors[0].lanes[].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

@@ -84,7 +84,7 @@ function collectTargets(config) {
     }
     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

package/dist/study/routing.js

@@ -46,8 +46,8 @@ 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) {
@@ -96,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));
@@ -111,7 +111,7 @@ export function isProvisionedSharedWorldComposition(config) {
 }
 /**
  * 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

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/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

@@ -1,28 +1,19 @@
-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`. */
+import type { StudyActor, StudyCaps, StudyConfig, StudyParticipantEntry } from "./types.js";
+/** The actor that runs. */
 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. */
+/** 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: v3 `participants: <n>` or `participants.count`. */
+/** 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: v3 `participants.instruction`. */
+/** 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. A v3 file lists `surfaces`. */
+/** How many scripted surfaces run, 1 for desktop and 2 with mobile. */
 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`. */
+/** 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 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`. */
+/** 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;