humanish 0.106.1 → 0.108.0

package/dist/lab/keys.js

@@ -92,8 +92,11 @@ const ACTOR = {
     type: true,
     count: true,
     lanes: PARTICIPANT_ENTRY,
-    // Roster groups are lanes with a count; the parser expands them into lanes.
-    roster: { ...PARTICIPANT_ENTRY, count: true },
+    // Roster groups are participants with a count; the parser expands them into `lanes[]`.
+    roster: {
+        ...PARTICIPANT_ENTRY,
+        count: true,
+    },
     persona: true,
     mission: true,
     model: true,
@@ -200,14 +203,45 @@ const LAB_KEYS = {
     defaults: { open: true },
     comms: { email: EMAIL },
 };
+function without(shape, ...keys) {
+    return Object.fromEntries(Object.entries(shape).filter(([key]) => !keys.includes(key)));
+}
+// humanish.study.v3. The route is declared, so `subject.topology` goes. The participant keys leave
+// the actor for `participants`, and `caps` is one top-level block. Top-level `personas` and
+// `scenario.inline` are read by no route, and `scenario` is a string.
+const STUDY_KEYS = {
+    schema: true,
+    id: true,
+    title: true,
+    description: true,
+    route: true,
+    mode: true,
+    subject: without(SUBJECT, "topology"),
+    actor: without(ACTOR, "count", "lanes", "roster", "laneFocus"),
+    // A count, `{ count, instruction }` or a list of entries. studyToV2 checks which form the route
+    // takes; an entry with a count is a group.
+    participants: { ...PARTICIPANT_ENTRY, count: true },
+    surfaces: true,
+    caps: CAPS,
+    execution: without(EXECUTION, "caps"),
+    scenario: true,
+    policies: LAB_KEYS.policies,
+    review: LAB_KEYS.review,
+    defaults: LAB_KEYS.defaults,
+    comms: LAB_KEYS.comms,
+};
 /** The first key in `raw` that LAB_KEYS does not list, as an error message; undefined if none. */
 export function findUnknownLabKey(raw) {
-    return walk(raw, LAB_KEYS, "");
+    return walk(raw, LAB_KEYS, "", "lab");
+}
+/** The first key in a humanish.study.v3 document that the format does not have; undefined if none. */
+export function findUnknownStudyKey(raw) {
+    return walk(raw, STUDY_KEYS, "", "study");
 }
-function walk(value, shape, path) {
+function walk(value, shape, path, noun) {
     if (Array.isArray(value)) {
         for (const [index, item] of value.entries()) {
-            const found = walk(item, shape, `${path}[${index}]`);
+            const found = walk(item, shape, `${path}[${index}]`, noun);
             if (found)
                 return found;
         }
@@ -220,23 +254,23 @@ function walk(value, shape, path) {
     // Object.hasOwn: a key like `constructor` must not match Object.prototype.
     const unknown = Object.keys(record).filter((key) => !Object.hasOwn(shape, key));
     if (unknown.length > 0)
-        return unknownKeysMessage(path, unknown, known);
+        return unknownKeysMessage(path, unknown, known, noun);
     for (const [key, child] of Object.entries(record)) {
         const expected = shape[key];
         if (expected !== true && expected !== undefined) {
-            const found = walk(child, expected, path ? `${path}.${key}` : key);
+            const found = walk(child, expected, path ? `${path}.${key}` : key, noun);
             if (found)
                 return found;
         }
     }
     return undefined;
 }
-function unknownKeysMessage(path, unknown, known) {
+function unknownKeysMessage(path, unknown, known, noun) {
     const named = unknown.map((key) => {
         const suggestion = closest(key, known);
         return suggestion ? `${key} (did you mean \`${suggestion}\`?)` : key;
     });
-    return `Unknown lab field(s)${path ? ` in \`${path}\`` : ""}: ${named.join(", ")}. Known fields: ${known.join(", ")}.`;
+    return `Unknown ${noun} field(s)${path ? ` in \`${path}\`` : ""}: ${named.join(", ")}. Known fields: ${known.join(", ")}.`;
 }
 // The known key within edit distance 2, or one that differs only in case.
 function closest(key, known) {

package/dist/lab/lab-deps.d.ts

@@ -0,0 +1,80 @@
+import type { ScriptedBrowserSessionOptions, ScriptedBrowserSessionResult } from "../actors/scripted-browser/actor.js";
+import type { ScriptedBrowserLaunchArgs, ScriptedBrowserLike } from "../actors/scripted-browser/types.js";
+import type { CuaActorSessionOptions } from "../actors/computer-use/actor.js";
+import type { AutomaticAnalysisDeps, runAutomaticAnalysis } from "../analysis/automatic.js";
+import type { CuaLoopResult } from "../actors/computer-use/loop.js";
+import type { renderObserver } from "../observer/render.js";
+import type { TerminalCostProbe } from "../routes/terminal/types.js";
+import type { DetachedTimers } from "../substrates/detached.js";
+import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
+import type { LocalTreeArchive } from "../subject/local-tree-archive.js";
+import type { SubjectPhaseEvent } from "../subject/steps.js";
+import type { ParticipantRef } from "./run-lab-events.js";
+export interface LabDeps {
+    /** Loads the E2B SDK. Defaults to loadE2BDesktopModule. */
+    readonly desktopModule?: () => Promise<E2BDesktopModule>;
+    /** Renders the Observer. Defaults to renderObserver. */
+    readonly renderObserver?: typeof renderObserver;
+    /** The clock, in epoch milliseconds. Defaults to Date.now. */
+    readonly now?: () => number;
+    /** Clock and sleep for detached provisioning steps. */
+    readonly detachedTimers?: DetachedTimers;
+    /**
+     * Computer use and shared world: where subject-provisioning phases go in place of stderr. A
+     * computer-use phase names its participant; a shared-world plane's names none. onEvent still
+     * receives every phase.
+     */
+    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.
+     */
+    readonly runSession?: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
+    /**
+     * Shared world: packs a local-tree subject on the host. Defaults to createLocalTreeArchive and a
+     * read of the archive it writes. Called once per run, before the subject sandbox exists.
+     */
+    readonly packLocalTree?: (args: {
+        root: string;
+        extraExclude?: string[];
+        maxArchiveBytes?: number;
+    }) => Promise<{
+        archive: LocalTreeArchive;
+        buffer: ArrayBuffer;
+    }>;
+    /** Shared world: the background stateSeries prober's cadence in milliseconds. Defaults to 1000. */
+    readonly proberCadenceMs?: number;
+    /**
+     * Shared world, external-public plane: how long the host has to surface a /lobby/CODE URL
+     * before the run fails closed. Defaults to 120000, capped by execution.timeoutMs.
+     */
+    readonly handoffDeadlineMs?: number;
+    /**
+     * Shared world, external-public plane: reads a /lobby/CODE off a participant's screenshot.
+     * Defaults to the single-frame OpenAI read.
+     */
+    readonly readLobbyCodeFromFrame?: (frame: Buffer, apiKey: string) => Promise<string | undefined>;
+    /**
+     * Every route: post-run analysis in place of the real one. `run` replaces
+     * the real analysis runner, and `deps` (provider fetch, keys, clock) reach the analysis only,
+     * never a participant.
+     */
+    readonly analysis?: {
+        readonly run?: typeof runAutomaticAnalysis;
+        readonly deps?: AutomaticAnalysisDeps;
+    };
+    /** Scripted: runs one surface's session in place of the scripted-browser actor. */
+    readonly runScriptedSession?: (options: ScriptedBrowserSessionOptions) => Promise<ScriptedBrowserSessionResult>;
+    /**
+     * Scripted: launches the browser each session drives, so no browser binary is resolved. The
+     * planner reads whether it, or browserCommand, is set: a live run then needs no host browser.
+     */
+    readonly launchBrowser?: (args: ScriptedBrowserLaunchArgs) => Promise<ScriptedBrowserLike>;
+    /** Scripted: the browser binary to launch; operators use HUMANISH_BROWSER_COMMAND. */
+    readonly browserCommand?: string;
+    /**
+     * Terminal: known spend lines for the cost ledger. The planner reads whether it is set, since
+     * only a measured line can trip a positive maxUsd.
+     */
+    readonly costProbe?: TerminalCostProbe;
+}

package/dist/lab/lab-deps.js

@@ -0,0 +1,4 @@
+// Test seams: the implementations a test puts in place of the real ones. The internal runLab takes
+// them as its third argument and each route runner as `deps`; the package's runLab takes none.
+// Each field defaults to the real implementation.
+export {};

package/dist/lab/parse/actors.js

@@ -3,8 +3,9 @@ import { isReasoningEffort, reasoningEffortNames } from "../../actors/reasoning-
 import { isMaxOutputTokens } from "../../actors/output-token-limit.js";
 import { isHttpUrl } from "./subject.js";
 import { registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, } from "../routing.js";
-import { invalid, isRecord, posInt, str } from "./values.js";
-// A lane id interpolates into per-lane evidence paths (screenshots/<id>/, actors/<id>.json), so
+import { invalid, posInt, str } from "./values.js";
+import { isRecord } from "../../run/type-guards.js";
+// A participant id interpolates into its evidence paths (screenshots/<id>/, actors/<id>.json), so
 // it must be a public-safe path token, same shape as a lab id.
 export const PARTICIPANT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 export const PARTICIPANT_ID_MAX_CHARS = 40;
@@ -21,8 +22,8 @@ export function focusOf(actor) {
 // Actor ids humanish no longer registers. Rejecting them at parse keeps a lab that names one
 // from running on a route that ignores actors[0].type, such as a this-repo dry run.
 const REMOVED_ACTOR_TYPES = new Set(["pi-agent-core", "claude-agent-sdk"]);
-// Only actors on a lane a route dispatches. codex-app-server is registered but declares only the
-// "code" lane, which no lab route runs, so naming it would lead to the same dead end.
+// Only actors of a run kind a route dispatches. codex-app-server is registered but declares only
+// the "code" run kind, which no study route runs, so naming it would lead to the same dead end.
 function routableActorTypes() {
     return [
         ...registeredComputerUseActors(),
@@ -56,10 +57,10 @@ export function parseActors(raw) {
         if (count !== undefined)
             actor.count = count;
         if (entry.lanes !== undefined && entry.roster !== undefined) {
-            return invalid(`actors[${index}].lanes and actors[${index}].roster are mutually exclusive: declare participants in \`lanes\` OR in compact \`roster\` groups, not both.`);
+            return invalid(`Set either actors[${index}].lanes or actors[${index}].roster, not both: list participants one by one in \`lanes\`, or in groups in \`roster\`.`);
         }
         if (entry.roster !== undefined && count !== undefined) {
-            return invalid(`actors[${index}].roster and actors[${index}].count are mutually exclusive — use compact differentiated groups OR a homogeneous count, not both.`);
+            return invalid(`Set either actors[${index}].roster or actors[${index}].count, not both: \`roster\` declares groups of distinct participants, and \`count\` declares identical ones.`);
         }
         if (entry.roster !== undefined && entry.laneFocus !== undefined) {
             return invalid(`actors[${index}].roster and actors[${index}].laneFocus are mutually exclusive: a roster group's instruction is each participant's steer.`);
@@ -138,7 +139,7 @@ function parseFocus(raw) {
     return Object.keys(focus).length > 0 ? focus : undefined;
 }
 /**
- * Parse `actors[index].roster` compact groups into concrete lanes. This is authoring sugar for
+ * Parse `actors[index].roster` compact groups into concrete `lanes[]` entries. This is authoring sugar for
  * "N users of M adapter-owned types across S surfaces"; the runtime receives only `lanes[]`.
  */
 function parseRosterGroups(raw, actorIndex) {
@@ -159,7 +160,7 @@ function parseRosterGroups(raw, actorIndex) {
             return invalid(`actors[${actorIndex}].roster[${groupIndex}].id is required and must be a public-safe token matching ${PARTICIPANT_ID_PATTERN}.`);
         }
         if (!PARTICIPANT_ID_PATTERN.test(groupId) || groupId.length > PARTICIPANT_ID_MAX_CHARS - 3) {
-            return invalid(`actors[${actorIndex}].roster[${groupIndex}].id must be a public-safe token matching ${PARTICIPANT_ID_PATTERN} and at most ${PARTICIPANT_ID_MAX_CHARS - 3} chars (generated participant ids use <id>-NN); got "${groupId}".`);
+            return invalid(`actors[${actorIndex}].roster[${groupIndex}].id must match ${PARTICIPANT_ID_PATTERN} and be at most ${PARTICIPANT_ID_MAX_CHARS - 3} characters, because each generated participant id adds a suffix like "-01"; "${groupId}" is not.`);
         }
         if (seenGroupIds.has(groupId)) {
             return invalid(`actors[${actorIndex}].roster group ids must be unique (duplicate "${groupId}").`);
@@ -183,11 +184,11 @@ function parseRosterGroups(raw, actorIndex) {
 }
 /**
  * Parse `actors[index].lanes` into a fan-out roster (computer-use E2B route). Structural only:
- * each lane is `{ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?,
+ * each entry is `{ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?,
  * entry?, host?, reasoningEffort?, stopWhen?, dwell? }`.
- * Lane ids (when declared) must be public-safe path tokens and unique; lane grouping metadata
- * must be public-safe tokens; a lane device must be a known preset name. The
- * route-scoped cross-validation (lanes XOR count/laneFocus, device XOR raw resolution, cap 16)
+ * Participant ids (when declared) must be public-safe path tokens and unique; grouping metadata
+ * must be public-safe tokens; a device must be a known preset name. The
+ * route-scoped cross-validation (`lanes` XOR `count`/`laneFocus`, device XOR raw resolution, cap 16)
  * runs in parseLabConfig where the route is known.
  */
 function parseParticipantEntries(raw, actorIndex) {
@@ -271,7 +272,7 @@ function parseParticipantEntries(raw, actorIndex) {
         const entryPath = str(entry.entry);
         if (entryPath !== undefined)
             parsedEntry.entry = entryPath;
-        // `host` marks the designated host seat on the external-public shared-world route; the
+        // `host` marks the designated host on the external-public shared-world route; the
         // exactly-one-host check runs in externalPublicSharedWorldValidationReason (route context).
         if (entry.host !== undefined) {
             if (typeof entry.host !== "boolean") {
@@ -286,7 +287,7 @@ function parseParticipantEntries(raw, actorIndex) {
 }
 /**
  * The researcher's protocol. Each task carries what the participant is asked to do and, optionally,
- * the observation that proves it happened — reusing `stopWhen`, so a criterion is exactly as
+ * the observation that proves it happened, reusing `stopWhen`, so a criterion is exactly as
  * expressive as a stop condition and an author who knows one knows the other.
  *
  * A task with no `success` is allowed on purpose: some things you ask a participant to do (think
@@ -313,7 +314,7 @@ function parseTasks(raw, field) {
         seen.add(id);
         const goal = str(entry.goal);
         if (goal === undefined) {
-            return invalid(`\`${field}[${index}].goal\` is required — what the PARTICIPANT is asked to do, in their language.`);
+            return invalid(`\`${field}[${index}].goal\` is required: what the participant is asked to do, in their own words.`);
         }
         const successResult = parseStopWhen(entry.success, `${field}[${index}].success`);
         if (!successResult.ok)
@@ -326,7 +327,7 @@ function parseTasks(raw, field) {
     }
     return { ok: true, value: tasks };
 }
-/** The bounds a dwell window (#510) must sit inside: at least one frame, at most an hour. */
+/** The bounds a dwell window must sit inside: at least one frame, at most an hour. */
 const DWELL_MIN_MS = 1_000;
 const DWELL_MAX_MS = 3_600_000;
 const DWELL_DEFAULT_EVERY_MS = 10_000;

package/dist/lab/parse/comms.js

@@ -1,4 +1,5 @@
-import { invalid, isRecord, posInt, str } from "./values.js";
+import { invalid, posInt, str } from "./values.js";
+import { isRecord } from "../../run/type-guards.js";
 // Fail-loud (never silently swallow a comms setting): a malformed `comms` block returns a parse
 // failure rather than being dropped.
 export function parseComms(raw) {
@@ -29,8 +30,8 @@ function parseCommsEmail(raw) {
     if (raw.kind !== undefined && raw.kind !== "fake") {
         return invalid("`comms.email.kind` must be `fake`.");
     }
-    // external ingress (#328): the ADOPTER runs the catch, so there is no subject env for humanish to
-    // inject and `injectEnv` becomes meaningless rather than merely unused — the operator points their
+    // external ingress: the adopter runs the catch, so there is no subject env for humanish to
+    // inject and `injectEnv` has nothing to name: the operator points their
     // own app at their own catch. Parse it first so the injectEnv requirement can key off it.
     const external = parseExternalCatch(raw.external);
     if (!external.ok)
@@ -126,7 +127,7 @@ function parseExternalCatch(raw) {
         return invalid("`comms.email.external` must be a mapping.");
     const catchBaseUrl = str(raw.catchBaseUrl);
     if (catchBaseUrl === undefined) {
-        return invalid("`comms.email.external.catchBaseUrl` is required — the base URL of the catch YOU run (humanish reads its GET /deliveries and your app POSTs its sends to it).");
+        return invalid("`comms.email.external.catchBaseUrl` is required: the base URL of the catch you run. Your app sends its mail to it, and humanish reads GET /deliveries from it.");
     }
     for (const [field, value] of [
         ["catchBaseUrl", catchBaseUrl],
@@ -147,7 +148,7 @@ function parseExternalCatch(raw) {
     }
     const authTokenEnv = str(raw.authTokenEnv);
     if (authTokenEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(authTokenEnv)) {
-        return invalid(`\`comms.email.external.authTokenEnv\` must be a valid env var NAME (got "${authTokenEnv}"); the value is read at runtime and never persisted.`);
+        return invalid(`\`comms.email.external.authTokenEnv\` must be an environment variable name, and "${authTokenEnv}" is not one. Its value is read when the run starts and never stored.`);
     }
     const inboxBaseUrl = str(raw.inboxBaseUrl);
     return {
@@ -174,7 +175,7 @@ function parseSmtp(raw) {
     const hostEnv = envName(raw.hostEnv, "hostEnv");
     const portEnv = envName(raw.portEnv, "portEnv");
     if (hostEnv === undefined || portEnv === undefined) {
-        return invalid("`comms.email.smtp` needs both `hostEnv` and `portEnv` — the subject-env vars your app reads for its SMTP host and port. The harness sets them to its own loopback listener.");
+        return invalid("`comms.email.smtp` needs both `hostEnv` and `portEnv`: the environment variables your app reads for its SMTP host and port. humanish sets them to its own loopback listener.");
     }
     if (hostEnv.startsWith("__invalid__") || portEnv.startsWith("__invalid__")) {
         return invalid("`comms.email.smtp.hostEnv` and `portEnv` must be valid env var names.");
@@ -226,7 +227,7 @@ export function addressedRecipients(email) {
         ? []
         : [{ participantId: recipient.lane, address: recipient.address }]);
 }
-/** `comms.email.recipients`: which lane each captured address belongs to. */
+/** `comms.email.recipients`: which participant each captured address belongs to. */
 function parseRecipients(raw) {
     if (raw === undefined)
         return { ok: true, value: undefined };

package/dist/lab/parse/execution.js

@@ -1,7 +1,8 @@
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { DEVICE_PRESET_NAMES, isDevicePresetName } from "../device-presets.js";
 import { isExactRuntimeVersion } from "../../routes/terminal/runtime.js";
-import { invalid, isRecord, nonNegNumber, posInt, str } from "./values.js";
+import { invalid, nonNegNumber, posInt, str } from "./values.js";
+import { isRecord } from "../../run/type-guards.js";
 export function parseExecution(raw) {
     if (raw === undefined) {
         return { ok: true, value: undefined };
@@ -32,7 +33,7 @@ export function parseExecution(raw) {
     }
     if (desktopResult.value)
         execution.desktop = desktopResult.value;
-    // Reuse the terminal lane's caps parser (same shape, not a fork) — a malformed budget is a hard
+    // Reuse the terminal route's caps parser (same shape, not a fork); a malformed budget is a hard
     // error, never silently dropped (a cap that silently does nothing would be a safety lie).
     const capsResult = parseCaps(raw.caps);
     if (!capsResult.ok) {
@@ -89,9 +90,9 @@ function parseTerminal(raw) {
         const transport = str(raw.transport);
         if (transport !== "exec-stream") {
             // "pty" is deliberately rejected: stdin is disabled, so the capture is a non-interactive
-            // exec stream — an interactive-PTY label would overstate the mechanism (invariant 6 + the
-            // goal packet's PTY ruling). True duplex PTY does not ship.
-            return invalid("`execution.terminal.transport` must be exec-stream — captured non-interactive exec output (stdin disabled) is not an interactive PTY; true duplex PTY transport is not supported.");
+            // exec stream, and an interactive-PTY label would overstate the mechanism. True duplex PTY
+            // does not ship.
+            return invalid("`execution.terminal.transport` must be exec-stream: the route captures the agent's output with stdin closed, and an interactive terminal (pty) is not supported.");
         }
         terminal.transport = transport;
     }
@@ -102,9 +103,9 @@ function parseTerminal(raw) {
         }
         if (stdin === "sent") {
             // Assisted input is forbidden until the interventions ledger + comparability flag + verify
-            // check exist (safety contract item 7) — shipping it now would let an assisted run pose as
-            // autonomous green proof.
-            return invalid("`execution.terminal.stdin: sent` (assisted input) is not supported — the current route cannot capture assisted input with a non-comparable marker. stdin is disabled by default.");
+            // check exist (the terminal route's stdin rule); shipping it now would let an assisted run
+            // pose as autonomous green proof.
+            return invalid("`execution.terminal.stdin: sent` (assisted input) is not supported: the route cannot yet mark a run that received typed help as different from an unassisted one. Remove the setting; stdin stays closed.");
         }
         terminal.stdin = stdin;
     }
@@ -152,13 +153,13 @@ function parseDesktop(raw) {
         }
         desktop.browser = browser;
     }
-    // A custom E2B desktop template NAME or ID. Trimmed non-empty when present; deliberately NOT
-    // allowlisted (any string is a valid template name/id — over-restricting would reject real
+    // A custom E2B desktop template name or ID. Trimmed non-empty when present; deliberately not
+    // allowlisted (any string is a valid template name/id; over-restricting would reject real
     // adopter images). An explicitly-set but blank/whitespace value is a mistake, not a template.
     if (raw.template !== undefined) {
         const template = str(raw.template);
         if (template === undefined) {
-            return invalid("`execution.desktop.template` must be a non-empty E2B desktop template NAME or ID when set (any string is accepted; there is no allowlist).");
+            return invalid("`execution.desktop.template` must be a non-empty E2B desktop template name or ID when it is set. Any name is accepted.");
         }
         desktop.template = template;
     }
@@ -246,8 +247,8 @@ export function parseScenario(raw) {
 }
 /**
  * Parse `scenario.caps`. Returns a parse failure on a malformed value rather than silently
- * dropping a budget declaration (a cap that silently does nothing would be a safety lie —
- * invariant 6). Each cap must be a non-negative finite number.
+ * dropping a budget declaration (a cap that silently does nothing would claim protection it
+ * does not give). Each cap must be a non-negative finite number.
  */
 function parseCaps(raw) {
     if (raw === undefined) {
@@ -338,7 +339,7 @@ function parseReviewScorer(raw) {
         return invalid("`review.scorer` must be a mapping with a `ref` path (e.g. { ref: scorers/product.mjs }).");
     const unknownKeys = Object.keys(raw).filter((key) => key !== "ref");
     if (unknownKeys.length > 0) {
-        return invalid(`Unknown \`review.scorer\` field(s): ${unknownKeys.join(", ")}. review.scorer accepts only \`ref\` (a repo-relative scorer-module path).`);
+        return invalid(`\`review.scorer\` accepts only \`ref\` (a scorer module path relative to the project), and these fields are unknown: ${unknownKeys.join(", ")}.`);
     }
     const ref = str(raw.ref);
     if (!ref)

package/dist/lab/parse/study-v3.d.ts

@@ -0,0 +1,23 @@
+import { type LabConfigParseFailure } from "../types.js";
+declare const ROUTES: readonly ["preview", "computer-use", "shared-world", "terminal", "scripted"];
+/** A route a study declares. */
+export type StudyRoute = (typeof ROUTES)[number];
+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[];
+}
+type Parsed<T> = {
+    ok: true;
+    value: T;
+} | LabConfigParseFailure;
+/** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
+export declare function studyToV2(raw: Record<string, unknown>): Parsed<StudyDocument>;
+/**
+ * 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 {};