humanish 0.107.0 → 0.108.0

package/dist/lab/config.js

@@ -1,38 +1,40 @@
 // humanish.lab.v2: a lab is a composition over code primitives. There is no hardcoded lab kind.
+// A humanish.study.v3 file is rewritten into this spelling first (parse/study-v3.ts), and then must
+// take the route it declares and set no field that route does not read.
 //
 // Scope (read before trusting field names): the engine routes by
-// subject.source × execution.target (disambiguated by the actor lane where both axes
+// subject.source × execution.target (disambiguated by the actor's run kind where both axes
 // collide) and consumes a deliberately small set of fields:
 //   subject.source/repos/appUrl/serve/env/state/clone.{depth,fanout,keep}, actors[0].count,
 //   execution.target + execution.desktop.codexAppServer, scenario.mode,
 //   policies.redactRepos, defaults.open.
 // On the computer-use routes (app-url × e2b-desktop, and clone × e2b-desktop with a
-// computer-use actor), `actors[0].type` is load-bearing: it must resolve to a registered
+// computer-use actor), `actors[0].type` selects the actor: it must resolve to a registered
 // computer-use actor, and that descriptor runs the session. Those routes also consume
 // actors[0].{mission,persona,laneFocus.instruction,model,reasoningEffort}, execution.timeoutMs,
 // execution.desktop.{browser,resolution,sandboxTimeoutMs}, and (clone)
 // subject.{serve,env,state,clone.depth}.
 // On the scripted-browser route (app-url × local-or-absent, or clone × e2b-desktop, with a
-// registered scripted-browser actor), `actors[0].type` is equally load-bearing, and the route
+// registered scripted-browser actor), `actors[0].type` selects the actor too, and the route
 // consumes scenario.ref (required there, because the committed scenario's browser steps are what the
 // actor executes), actors[0].{persona,count}, and execution.timeoutMs. On the provisioned
 // clone slice it also consumes subject.{repos,serve,env,state,exposure,clone.depth} and
 // execution.desktop.template. actors[0].{mission,laneFocus,model} are inert on that route
 // because no model runs, and most execution.desktop.* fields remain forward-declared (device
-// presets belong to the cua route — scripted surfaces are the driver's own desktop/mobile
+// presets belong to the computer-use route; scripted surfaces are the driver's own desktop/mobile
 // viewports where isMobile/DSF genuinely render via playwright emulation).
 // On the other routes those fields remain forward-declared and are not yet consumed:
 // parseLabConfig emits a warning listing any such field that is set, so `lab inspect` shows
 // the truth.
 //
-// NOTE on actors[0].count: it now carries ROUTE-SPECIFIC meanings — synthetic route: simCount;
+// NOTE on actors[0].count: it carries route-specific meanings. Preview route: simCount;
 // scripted-browser route: surface roster {1 = desktop, 2 = desktop + mobile}, default 1 (the
 // defaults-table single-participant row governs; count: 2 is the declared override); computer-use
 // E2B route: the homogeneous fan-out participant count (N identical participants, each its own E2B
-// desktop), capped at 16; the in-process/local-app cua route stays single-participant (no E2B to
-// fan out).
+// desktop), capped at 16; the in-process/local-app computer-use route stays single-participant (no
+// E2B to fan out).
 //
-// NOTE on actors[0].lanes / actors[0].roster (computer-use E2B route, this slice): a
+// NOTE on actors[0].lanes / actors[0].roster (computer-use E2B route): a
 // differentiated fan-out roster: each `{ id?, persona?, device?, instruction?, target? }` becomes one
 // independent E2B desktop (`per-lane-worlds`, the default topology). `roster[]` is parser sugar for
 // repeated groups and is normalized into `lanes[]` before the engine sees it. `lanes|roster` XOR
@@ -40,13 +42,13 @@
 // XOR `actors[0].laneFocus` (each entry's `instruction` is the roster's steer); `lanes[].device` XOR
 // raw `execution.desktop.resolution`. `execution.concurrency` bounds in-flight participants (default:
 // the participant count, all at once; env HUMANISH_CUA_MAX_CONCURRENCY may only lower it, per invariant
-// 3). On every non-cua route normalized `lanes` are inert (warned). subject.clone.fanout is
-// rejected on the cua route. `lanes[].target` is app-url × computer-use only: an absolute browser
-// URL this participant opens instead of `subject.appUrl`; it is the generic setup-produced-target
-// handoff, not a service topology primitive.
+// 3). On every non-computer-use route normalized `lanes` are inert (warned). subject.clone.fanout
+// is rejected on the computer-use route. `lanes[].target` is app-url × computer-use only: an
+// absolute browser URL this participant opens instead of `subject.appUrl`; it is the generic
+// setup-produced-target handoff, not a service topology primitive.
 //
 // There is deliberately no v1 compatibility: v1 had zero real users. Breaking schema changes
-// bump the version honestly.
+// bump the version.
 import { isLocalBrowserLab, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
 import { isRecord } from "../run/type-guards.js";
 import { compositionReason } from "./composition-rules.js";
@@ -54,13 +56,14 @@ import { findUnknownLabKey } from "./keys.js";
 import { parseActors, rosterOf } from "./parse/actors.js";
 import { parseComms, recipientParticipantId } from "./parse/comms.js";
 import { parseDefaults, parseExecution, parsePersonas, parsePolicies, parseReview, parseScenario, } from "./parse/execution.js";
+import { studySpelling, studyToV2 } from "./parse/study-v3.js";
 import { parseSubject } from "./parse/subject.js";
 import { invalid, optionalStr, str } from "./parse/values.js";
-import { isComputerUseComposition, isSharedWorldComposition } from "./routing.js";
+import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
-import { ID_PATTERN, LAB_CONFIG_SCHEMA, } from "./types.js";
+import { ID_PATTERN, LAB_CONFIG_SCHEMA, STUDY_SCHEMA, } from "./types.js";
 import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "./validation.js";
-import { forwardDeclaredWarnings } from "./warnings.js";
+import { forwardDeclaredWarnings, inertFieldLabels } from "./warnings.js";
 /**
  * Validate a parsed YAML object into a LabConfig. Pure: the caller owns file IO. Structural
  * validation only. Fields the engine does not yet consume are accepted but reported in
@@ -70,9 +73,41 @@ export function parseLabConfig(raw) {
     if (!isRecord(raw)) {
         return invalid("Lab manifest must be a YAML object.");
     }
+    if (raw.schema === STUDY_SCHEMA)
+        return parseStudy(raw);
     if (raw.schema !== LAB_CONFIG_SCHEMA) {
-        return invalid(`Lab schema must be ${LAB_CONFIG_SCHEMA}.`);
+        return invalid(`Lab schema must be ${STUDY_SCHEMA} or ${LAB_CONFIG_SCHEMA}.`);
     }
+    return parseV2(raw);
+}
+/**
+ * A v3 study parses through the v2 parser, then must take the route it declares and set no field
+ * that route does not read. A v2 file gets those fields as a warning instead.
+ */
+function parseStudy(raw) {
+    const document = studyToV2(raw);
+    if (!document.ok)
+        return document;
+    const { route, v2, participantSource } = document.value;
+    const spell = (message) => studySpelling(message, route, participantSource);
+    const parsed = parseV2(v2);
+    if (!parsed.ok)
+        return invalid(spell(parsed.error.message));
+    const taken = routeOf(parsed.config);
+    if (taken !== route) {
+        return invalid(`This study declares route: ${route}, but its subject (source: ${parsed.config.subject.source}) and actor (type: ${parsed.config.actors[0]?.type}) take the ${taken} route. Change \`route\`, or change the subject or actor.`);
+    }
+    const inert = inertFieldLabels(parsed.config);
+    if (inert.length > 0) {
+        return invalid(spell(`route: ${route} does not read ${inert.join(", ")}. Remove ${inert.length === 1 ? "it" : "them"}.`));
+    }
+    return {
+        ok: true,
+        config: { ...parsed.config, schema: STUDY_SCHEMA },
+        warnings: parsed.warnings.map(spell),
+    };
+}
+function parseV2(raw) {
     const unknownKey = findUnknownLabKey(raw);
     if (unknownKey)
         return invalid(unknownKey);
@@ -150,11 +185,12 @@ export function parseLabConfig(raw) {
     const scenarioCapsReason = scenarioCapsValidationReason(config);
     if (scenarioCapsReason)
         return invalid(scenarioCapsReason);
-    // All-parallel default (#350): a multi-seat lab that does not declare execution.concurrency runs
-    // every seat at once; the declared field is a cap the author chose, never a mode. Independent
-    // computer-use participants resolve that default from the final participant count when they plan, after any
-    // --count override, so the parser leaves it unset for them. A shared world's roster is fixed, so
-    // its default is filled here for the envelopes and warnings that read the parsed config.
+    // All-parallel default: a multi-participant study that does not declare execution.concurrency
+    // runs every participant at once; the declared field is a cap the author chose, never a mode.
+    // Independent computer-use participants resolve that default from the final participant count
+    // when they plan, after any --count override, so the parser leaves it unset for them. A shared
+    // world's roster is fixed, so its default is filled here for the envelopes and warnings that read
+    // the parsed config.
     {
         const participantCount = rosterOf(config.actors[0])?.length ?? config.actors[0]?.count ?? 1;
         if (participantCount > 1 &&
@@ -163,8 +199,8 @@ export function parseLabConfig(raw) {
             config.execution = { ...config.execution, concurrency: participantCount };
         }
     }
-    // Email that just works (#351): the funnel's only handoff to an actor is the per-participant
-    // inbox instruction, gated on recipients[]. Guessed participant ids broke a field run —
+    // Email that just works: the funnel's only handoff to an actor is the per-participant
+    // inbox instruction, gated on recipients[]. Guessed participant ids broke a field run:
     // recipients copied from a single-participant example matched nothing, so every actor was left inbox-blind with zero
     // signal. Omitted recipients are therefore filled (one deterministic address per participant);
     // a recipient naming an unknown participant is a hard error listing the real ids; declared
@@ -206,5 +242,9 @@ export function parseLabConfig(raw) {
         if (reason)
             return invalid(reason);
     }
-    return { ok: true, config: normalized, warnings: forwardDeclaredWarnings(normalized) };
+    return {
+        ok: true,
+        config: normalized,
+        warnings: forwardDeclaredWarnings(normalized),
+    };
 }

package/dist/lab/deprecated-fields.d.ts

@@ -0,0 +1,10 @@
+/** One deprecated field: what to read instead, and how to compute the old value. */
+export interface DeprecatedField {
+    readonly replacement: string;
+    readonly read: () => unknown;
+}
+/** Adds `fields` to `value` as warning getters and returns `value`. */
+export declare function withDeprecatedFields<T extends object>(value: T, owner: {
+    readonly name: string;
+    readonly code: `HUMANISH_${string}`;
+}, fields: Readonly<Record<string, DeprecatedField>>): T;

package/dist/lab/deprecated-fields.js

@@ -0,0 +1,24 @@
+// Deprecated fields on a value humanish hands to a caller. Each is a getter that warns once per
+// process when read. The getters are not enumerable, so a spread, `Object.assign`,
+// `JSON.stringify` or `structuredClone` of the value skips them and warns about no field the
+// caller never named; `"name" in value` still finds them. Core never reads them.
+const warned = new Set();
+/** Adds `fields` to `value` as warning getters and returns `value`. */
+export function withDeprecatedFields(value, owner, fields) {
+    return Object.defineProperties(value, Object.fromEntries(Object.entries(fields).map(([field, { replacement, read }]) => [
+        field,
+        {
+            enumerable: false,
+            get: () => {
+                warnOnce(`${owner.name}.${field}`, replacement, owner.code);
+                return read();
+            },
+        },
+    ])));
+}
+function warnOnce(name, replacement, code) {
+    if (warned.has(name))
+        return;
+    warned.add(name);
+    process.emitWarning(`${name} is deprecated and is removed in the next minor. Use ${replacement}.`, { type: "DeprecationWarning", code });
+}

package/dist/lab/device-presets.d.ts

@@ -55,7 +55,7 @@ export declare const DEVICE_PRESETS: {
 export type DevicePresetName = keyof typeof DEVICE_PRESETS;
 /**
  * Default device for a run that does not declare one. `desktop` (1440x950) is the median
- * first-run laptop screen — the in-house desktop default, within 10px of the 1440x960 dry-run
+ * first-run laptop screen, the in-house desktop default, within 10px of the 1440x960 dry-run
  * surface in src/run/dry-run.ts. `wide` (1920x1080), the most-common external monitor, is one
  * keystroke away (`execution.desktop.device: wide`) but is deliberately not the default,
  * because the median device a first-time user arrives on is a laptop, not a 1080p monitor.
@@ -67,22 +67,22 @@ export declare function isDevicePresetName(value: unknown): value is DevicePrese
 /** Resolve a preset name (or undefined) to its preset, falling back to the default. */
 export declare function resolveDevicePreset(name: DevicePresetName | undefined): DevicePreset;
 /**
- * The narrowest browser WINDOW Chrome/Chromium will render on the E2B desktop. Chrome refuses to
+ * The narrowest browser window Chrome/Chromium will render on the E2B desktop. Chrome refuses to
  * make its window narrower than this (~500 CSS px observed: a 414-wide X screen produced a 500-wide
- * window that OVERFLOWED it, clipping the right edge of the page off-screen). So the physically
- * RENDERED screen width is floored here: a sub-500 mobile preset (mobile 414, small-mobile 360,
- * narrow-mobile 320) gets a 500-wide screen the window fits exactly — no clip. The device PRESET keeps
+ * window that overflowed it, clipping the right edge of the page off-screen). So the physically
+ * rendered screen width is floored here: a sub-500 mobile preset (mobile 414, small-mobile 360,
+ * narrow-mobile 320) gets a 500-wide screen the window fits exactly, with no clip. The device preset keeps
  * its true identity (isMobile, nominal width) for the persona prompt + metadata; only the rendered
  * screen is floored. True sub-500 CSS-viewport rendering (page laid out at 414 regardless of window
- * width, via CDP device-metric emulation) is the separate #221 upgrade.
+ * width, via CDP device-metric emulation) is the separate mobileEmulation option.
  */
 export declare const MIN_DESKTOP_RENDER_WIDTH = 500;
-/** Floor a screen resolution's WIDTH to what Chrome can actually render (see MIN_DESKTOP_RENDER_WIDTH). */
+/** Floor a screen resolution's width to what Chrome can actually render (see MIN_DESKTOP_RENDER_WIDTH). */
 export declare function floorRenderResolution(resolution: readonly [number, number]): [number, number];
 /**
  * Resolve a participant's device + rendered resolution (most-specific wins, exactly as the
  * single-participant path always has): a raw execution.desktop.resolution escape hatch (only legal
- * when no roster entry sets a device — XOR enforced at parse) → the participant's named device → the run-wide
+ * when no roster entry sets a device; XOR enforced at parse) → the participant's named device → the run-wide
  * execution.desktop.device → the default preset. A raw resolution is an unnamed custom desktop
  * (non-mobile, DSF 1): we never claim a named preset's mobile/DPR for hand-set geometry. The rendered
  * `resolution` is floored to MIN_DESKTOP_RENDER_WIDTH so the browser window fits its X screen (no clip);

package/dist/lab/device-presets.js

@@ -4,13 +4,13 @@
  * the per-line notes record where the two reference sims agree vs. diverge.
  */
 export const DEVICE_PRESETS = {
-    // phone — both reference sims agree
+    // phone: both reference sims agree
     mobile: { width: 414, height: 896, isMobile: true, deviceScaleFactor: 3 },
-    // small phone — both reference sims agree
+    // small phone: both reference sims agree
     "small-mobile": { width: 360, height: 740, isMobile: true, deviceScaleFactor: 3 },
     // older narrow phone
     "narrow-mobile": { width: 320, height: 700, isMobile: true, deviceScaleFactor: 2 },
-    // tablet — both reference sims agree
+    // tablet: both reference sims agree
     tablet: { width: 820, height: 1180, isMobile: false, deviceScaleFactor: 2 },
     // laptop baseline (the in-house desktop screen; close to the 1440x960 dry-run surface in
     // src/run/dry-run.ts)
@@ -20,7 +20,7 @@ export const DEVICE_PRESETS = {
 };
 /**
  * Default device for a run that does not declare one. `desktop` (1440x950) is the median
- * first-run laptop screen — the in-house desktop default, within 10px of the 1440x960 dry-run
+ * first-run laptop screen, the in-house desktop default, within 10px of the 1440x960 dry-run
  * surface in src/run/dry-run.ts. `wide` (1920x1080), the most-common external monitor, is one
  * keystroke away (`execution.desktop.device: wide`) but is deliberately not the default,
  * because the median device a first-time user arrives on is a laptop, not a 1080p monitor.
@@ -36,24 +36,24 @@ export function resolveDevicePreset(name) {
     return DEVICE_PRESETS[name ?? DEFAULT_DEVICE_PRESET];
 }
 /**
- * The narrowest browser WINDOW Chrome/Chromium will render on the E2B desktop. Chrome refuses to
+ * The narrowest browser window Chrome/Chromium will render on the E2B desktop. Chrome refuses to
  * make its window narrower than this (~500 CSS px observed: a 414-wide X screen produced a 500-wide
- * window that OVERFLOWED it, clipping the right edge of the page off-screen). So the physically
- * RENDERED screen width is floored here: a sub-500 mobile preset (mobile 414, small-mobile 360,
- * narrow-mobile 320) gets a 500-wide screen the window fits exactly — no clip. The device PRESET keeps
+ * window that overflowed it, clipping the right edge of the page off-screen). So the physically
+ * rendered screen width is floored here: a sub-500 mobile preset (mobile 414, small-mobile 360,
+ * narrow-mobile 320) gets a 500-wide screen the window fits exactly, with no clip. The device preset keeps
  * its true identity (isMobile, nominal width) for the persona prompt + metadata; only the rendered
  * screen is floored. True sub-500 CSS-viewport rendering (page laid out at 414 regardless of window
- * width, via CDP device-metric emulation) is the separate #221 upgrade.
+ * width, via CDP device-metric emulation) is the separate mobileEmulation option.
  */
 export const MIN_DESKTOP_RENDER_WIDTH = 500;
-/** Floor a screen resolution's WIDTH to what Chrome can actually render (see MIN_DESKTOP_RENDER_WIDTH). */
+/** Floor a screen resolution's width to what Chrome can actually render (see MIN_DESKTOP_RENDER_WIDTH). */
 export function floorRenderResolution(resolution) {
     return [Math.max(resolution[0], MIN_DESKTOP_RENDER_WIDTH), resolution[1]];
 }
 /**
  * Resolve a participant's device + rendered resolution (most-specific wins, exactly as the
  * single-participant path always has): a raw execution.desktop.resolution escape hatch (only legal
- * when no roster entry sets a device — XOR enforced at parse) → the participant's named device → the run-wide
+ * when no roster entry sets a device; XOR enforced at parse) → the participant's named device → the run-wide
  * execution.desktop.device → the default preset. A raw resolution is an unnamed custom desktop
  * (non-mobile, DSF 1): we never claim a named preset's mobile/DPR for hand-set geometry. The rendered
  * `resolution` is floored to MIN_DESKTOP_RENDER_WIDTH so the browser window fits its X screen (no clip);

package/dist/lab/discover.d.ts

@@ -1,7 +1,7 @@
 import type { ActorPersonaRef } from "../actors/contract.js";
 import { type LabConfig } from "./types.js";
-declare const LAB_LIST_SCHEMA = "humanish.lab-list.v1";
-declare const LAB_INSPECT_SCHEMA = "humanish.lab-inspect.v1";
+declare const STUDY_LIST_SCHEMA = "humanish.study-list.v1";
+declare const STUDY_SHOW_SCHEMA = "humanish.study-show.v1";
 type LabOrigin = "committed" | "ignored" | "explicit";
 interface ResolvedLabConfig {
     config: LabConfig;
@@ -12,9 +12,10 @@ interface ResolvedLabConfig {
 export interface LabResolveFailure {
     ok: false;
     cwd: string;
-    lab: string;
+    /** The study the caller asked for, as given. */
+    study: string;
     error: {
-        code: "HUMANISH_LAB_NOT_FOUND" | "HUMANISH_LAB_INVALID";
+        code: "HUMANISH_STUDY_NOT_FOUND" | "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_AMBIGUOUS";
         message: string;
     };
     warnings: string[];
@@ -30,16 +31,18 @@ export interface LabListEntry {
     title?: string;
     /**
      * The manifest's own first sentence. The list is where someone decides which study to open, and a
-     * list of names cannot answer "what is this one" for a project with twenty labs in it — the
+     * list of names cannot answer "what is this one" for a project with twenty labs in it; the
      * stakeholder feedback that added this was, verbatim, "so i know wtf they are".
      */
     description?: string;
+    /** Why `run` refuses this file by name: its stem also names a file in the other directory family. */
+    error?: string;
 }
 export interface LabListResult {
-    schema: typeof LAB_LIST_SCHEMA;
+    schema: typeof STUDY_LIST_SCHEMA;
     ok: true;
     cwd: string;
-    labs: LabListEntry[];
+    studies: LabListEntry[];
     warnings: string[];
 }
 export interface LabInspectResult {
@@ -49,10 +52,11 @@ export interface LabInspectResult {
         resolved: boolean;
         brief?: ActorPersonaRef["brief"];
     }>;
-    schema: typeof LAB_INSPECT_SCHEMA;
+    schema: typeof STUDY_SHOW_SCHEMA;
     ok: boolean;
     cwd: string;
-    lab: string;
+    /** The study the caller asked for, as given. */
+    study: string;
     config?: LabConfig;
     origin?: LabOrigin;
     path?: string;