humanish 0.108.0 → 0.109.0

package/dist/{lab → study}/composition-rules.js

@@ -1,8 +1,8 @@
-// Which subject, target and actor compositions a lab may declare. Each rule returns the refusal
+// Which subject, target and actor compositions a study may declare. Each rule returns the refusal
 // message for the first thing its composition gets wrong, or null. compositionReason runs them in
-// the parser's order, and only parseLabConfig calls it. planLab does not: each route planner checks
+// the parser's order, and only parseStudy calls it. planStudy does not: each route planner checks
 // a library caller's config itself, under its route's error codes. The planners call the shared
-// checks in lab/validation.ts and desktopCliProductReason below. The other subject rules here have
+// checks in study/validation.ts and desktopCliProductReason below. The other subject rules here have
 // planner counterparts whose conditions and wording differ (clone serve and repo, local-tree
 // target, in-process fan-out, loopback targets, scripted scenario.ref).
 import { isLoopbackUrl } from "./parse/subject.js";
@@ -30,14 +30,14 @@ export function compositionReason(config) {
         terminalValidationReason(config) ??
         cloneActorValidationReason(config));
 }
-/** Why a this-repo lab cannot run live. The parser and the preview planner both refuse with it. */
-export const THIS_REPO_DRY_RUN_ONLY = "this-repo labs are dry-run only; use a clone or app-url subject for a live run.";
+/** Why a this-repo study cannot run live. The parser and the preview planner both refuse with it. */
+export const THIS_REPO_DRY_RUN_ONLY = "this-repo studies are dry-run only; use a clone or app-url subject for a live run.";
 // this-repo subjects run locally and dry-run only: there is no live execution target for the
 // host repo (clone/app-url provide that). Reject the mis-configs rather than silently mishandle.
 function thisRepoValidationReason(config) {
     if (config.subject.source === "this-repo") {
         if (config.execution?.target) {
-            return "`execution.target` applies only to clone/app-url/local-app subjects; this-repo labs run locally.";
+            return "`execution.target` applies only to clone/app-url/local-app subjects; this-repo studies run locally.";
         }
         if (config.scenario?.mode === "live") {
             return THIS_REPO_DRY_RUN_ONLY;
@@ -51,7 +51,7 @@ function thisRepoValidationReason(config) {
 // desktop), and no public-target policy (it is always loopback; the loopback shape was already
 // enforced in parseSubject). The actual "no inProcess executor supplied" case is inherently an
 // engine-time decision (the parser cannot know whether a library caller will pass one), so
-// it fails closed in runCuaActorLab with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
+// it fails closed in runCuaActorStudy with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
         const type = config.actors[0]?.type ?? "";
@@ -106,7 +106,7 @@ function appUrlValidationReason(config) {
                 return "app-url computer-use subjects require `execution.target: local` or `e2b-desktop`.";
             }
             if (!actorResolvesToComputerUse(type)) {
-                return `actors[0].type must be a registered computer-use actor for app-url × e2b-desktop labs (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
+                return `actors[0].type must be a registered computer-use actor for app-url × e2b-desktop studies (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
             }
             // Multi-participant fan-out is consumed on this route (`per-lane-worlds`; the shared cua
             // cross-validation below enforces `lanes`/`count` XOR rules, the 16 cap, and the
@@ -136,7 +136,7 @@ function scriptedBrowserValidationReason(config) {
             return "A clone subject with a scripted-browser actor needs `subject.serve` (start and url): humanish starts the app in the sandbox before the browser steps run.";
         }
         if ((config.subject.repos?.length ?? 0) !== 1) {
-            return "clone scripted-browser labs require exactly one repo in subject.repos.";
+            return "clone scripted-browser studies require exactly one repo in subject.repos.";
         }
         const repo = config.subject.repos?.[0] ?? "";
         if (!REPO_SLUG_PATTERN.test(repo)) {
@@ -188,7 +188,7 @@ function cloneComputerUseValidationReason(config) {
             return "A clone subject on the computer-use route needs `subject.serve` (start and url): humanish starts the app in the sandbox before the participant opens it.";
         }
         if ((config.subject.repos?.length ?? 0) !== 1) {
-            return "computer-use clone labs serve one repo; declare exactly one repo in subject.repos.";
+            return "computer-use clone studies serve one repo; declare exactly one repo in subject.repos.";
         }
         const repo = config.subject.repos?.[0] ?? "";
         if (!REPO_SLUG_PATTERN.test(repo)) {
@@ -278,14 +278,14 @@ function terminalValidationReason(config) {
     }
     return null;
 }
-// A clone lab is served in-sandbox for a participant to drive, so only a computer-use or a
+// A clone study is served in-sandbox for a participant to drive, so only a computer-use or a
 // scripted-browser actor can run it. Any other actor would parse and then fail at run start.
 // Terminal actors were already refused above with their own message.
 function cloneActorValidationReason(config) {
     if (config.subject.source === "clone") {
         const type = config.actors[0]?.type ?? "";
         if (!actorResolvesToComputerUse(type) && !actorResolvesToScriptedBrowser(type)) {
-            return `clone subjects need a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}) or scripted-browser actor (one of: ${registeredScriptedBrowserActors().join(", ")}); the lab clones and serves the app for that participant to drive. Got "${type}".`;
+            return `clone subjects need a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}) or scripted-browser actor (one of: ${registeredScriptedBrowserActors().join(", ")}); humanish clones and serves the app for that participant to drive. Got "${type}".`;
         }
     }
     return null;

package/dist/study/config.d.ts

@@ -0,0 +1,15 @@
+import { type StudyParseResult } from "./types.js";
+/** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
+export declare const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study, which humanish no longer reads. Convert its file with humanish migrate <path>.";
+/**
+ * The package's study parser (src/index.ts) and the one discovery uses: a humanish.study.v3
+ * document. It refuses a humanish.lab.v2 one with HUMANISH_STUDY_V2_UNSUPPORTED.
+ */
+export declare function parseStudy(raw: unknown): StudyParseResult;
+/**
+ * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
+ * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
+ * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
+ * nothing. migrate's conversion (convert.ts) calls it directly, since it reads v2 files.
+ */
+export declare function parseStudyDocument(raw: unknown): StudyParseResult;

package/dist/{lab → study}/config.js

@@ -1,4 +1,5 @@
-// humanish.lab.v2: a lab is a composition over code primitives. There is no hardcoded lab kind.
+// The normalized config, in the humanish.lab.v2 spelling: a study composes code primitives, with no
+// hardcoded study 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.
 //
@@ -24,7 +25,7 @@
 // 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
+// parseStudy emits a warning listing any such field that is set, so `study show` shows
 // the truth.
 //
 // NOTE on actors[0].count: it carries route-specific meanings. Preview route: simCount;
@@ -49,10 +50,10 @@
 //
 // There is deliberately no v1 compatibility: v1 had zero real users. Breaking schema changes
 // bump the version.
-import { isLocalBrowserLab, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
+import { isLocalBrowserStudy, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
 import { isRecord } from "../run/type-guards.js";
 import { compositionReason } from "./composition-rules.js";
-import { findUnknownLabKey } from "./keys.js";
+import { findUnknownV2Key } 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";
@@ -61,22 +62,38 @@ import { parseSubject } from "./parse/subject.js";
 import { invalid, optionalStr, str } from "./parse/values.js";
 import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
-import { ID_PATTERN, LAB_CONFIG_SCHEMA, STUDY_SCHEMA, } from "./types.js";
+import { ID_PATTERN, V2_SCHEMA, STUDY_SCHEMA, } from "./types.js";
 import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "./validation.js";
 import { forwardDeclaredWarnings, inertFieldLabels } from "./warnings.js";
+import { plural } from "../run/text.js";
+/** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
+export const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study, which humanish no longer reads. Convert its file with humanish migrate <path>.";
 /**
- * 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
- * `warnings` so `lab inspect` never silently swallows a setting that does nothing.
+ * The package's study parser (src/index.ts) and the one discovery uses: a humanish.study.v3
+ * document. It refuses a humanish.lab.v2 one with HUMANISH_STUDY_V2_UNSUPPORTED.
  */
-export function parseLabConfig(raw) {
+export function parseStudy(raw) {
+    if (isRecord(raw) && raw.schema === V2_SCHEMA)
+        return {
+            ok: false,
+            error: { code: "HUMANISH_STUDY_V2_UNSUPPORTED", message: V2_UNSUPPORTED_MESSAGE },
+        };
+    return parseStudyDocument(raw);
+}
+/**
+ * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
+ * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
+ * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
+ * nothing. migrate's conversion (convert.ts) calls it directly, since it reads v2 files.
+ */
+export function parseStudyDocument(raw) {
     if (!isRecord(raw)) {
-        return invalid("Lab manifest must be a YAML object.");
+        return invalid("A study file 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 ${STUDY_SCHEMA} or ${LAB_CONFIG_SCHEMA}.`);
+        return parseV3(raw);
+    if (raw.schema !== V2_SCHEMA) {
+        return invalid(`The study schema must be ${STUDY_SCHEMA} or ${V2_SCHEMA}.`);
     }
     return parseV2(raw);
 }
@@ -84,7 +101,7 @@ export function parseLabConfig(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) {
+function parseV3(raw) {
     const document = studyToV2(raw);
     if (!document.ok)
         return document;
@@ -108,12 +125,12 @@ function parseStudy(raw) {
     };
 }
 function parseV2(raw) {
-    const unknownKey = findUnknownLabKey(raw);
+    const unknownKey = findUnknownV2Key(raw);
     if (unknownKey)
         return invalid(unknownKey);
     const id = str(raw.id);
     if (!id || !ID_PATTERN.test(id)) {
-        return invalid("Lab id must be a public-safe token starting with a letter or digit (/^[A-Za-z0-9][A-Za-z0-9_.-]*$/).");
+        return invalid("The study id must be a public-safe token starting with a letter or digit (/^[A-Za-z0-9][A-Za-z0-9_.-]*$/).");
     }
     const subjectResult = parseSubject(raw.subject);
     if (!subjectResult.ok) {
@@ -128,7 +145,7 @@ function parseV2(raw) {
         return executionResult;
     }
     const config = {
-        schema: LAB_CONFIG_SCHEMA,
+        schema: V2_SCHEMA,
         id,
         ...optionalStr("title", raw.title),
         ...optionalStr("description", raw.description),
@@ -174,7 +191,7 @@ function parseV2(raw) {
     if (commsResult.value)
         config.comms = commsResult.value;
     if (config.comms?.email?.smtp && config.subject.topology === "shared-world") {
-        return invalid("SMTP capture is not yet wired for shared-world labs. Use the default per-lane-worlds topology for SMTP, or configure supported HTTP email capture for concurrent shared-world labs.");
+        return invalid("SMTP capture is not supported yet for shared-world studies. Use the default per-lane-worlds topology for SMTP, or configure supported HTTP email capture for concurrent shared-world studies.");
     }
     const mediaReason = desktopMediaValidationReason(config);
     if (mediaReason)
@@ -220,7 +237,7 @@ function parseV2(raw) {
         else {
             const unknown = email.recipients.filter((recipient) => !participantIds.includes(recipientParticipantId(recipient)));
             if (unknown.length > 0) {
-                return invalid(`comms.email.recipients name participant(s) that do not exist: ${unknown.map((r) => `"${recipientParticipantId(r)}"`).join(", ")}. This lab's participant ids are: ${participantIds.join(", ")}. A recipient's \`lane\` must match one of them exactly: the inbox instruction is injected per participant, and a mismatch disables the email funnel for that participant.`);
+                return invalid(`comms.email.recipients name ${plural(unknown.length, "participant")} that ${unknown.length === 1 ? "does" : "do"} not exist: ${unknown.map((r) => `"${recipientParticipantId(r)}"`).join(", ")}. This study's participant ids are: ${participantIds.join(", ")}. A recipient's \`lane\` must match one of them exactly: the inbox instruction is injected per participant, and a mismatch disables the email funnel for that participant.`);
             }
             if (!email.recipients.some((recipient) => recipient.address !== undefined)) {
                 return invalid("comms.email.recipients cover no participant with an address, so no actor would be told an inbox exists and no captured mail could match. Give at least one recipient an address, or omit `recipients` entirely (every participant then gets a deterministic address automatically).");
@@ -237,7 +254,7 @@ function parseV2(raw) {
     if (analysisReason)
         return invalid(analysisReason);
     const normalized = localBrowserDefaults(config);
-    if (isLocalBrowserLab(normalized)) {
+    if (isLocalBrowserStudy(normalized)) {
         const reason = localBrowserUnsupportedReason(normalized);
         if (reason)
             return invalid(reason);

package/dist/study/convert.d.ts

@@ -1,4 +1,4 @@
-import type { StudyRoute } from "../lab/parse/study-v3.js";
+import { type StudyRoute } from "./routing.js";
 /** A key the conversion moved, by its v2 path and its v3 path. */
 export interface MovedKey {
     readonly from: string;

package/dist/study/convert.js

@@ -3,13 +3,13 @@
 // every key it moved and every key it dropped. It refuses a file whose v3 form would parse or plan
 // differently from the v2 source with the dropped keys removed.
 import { isAlias, isMap, isScalar, isSeq, LineCounter, Pair, parseDocument, Scalar, visit, YAMLMap, YAMLSeq, } from "yaml";
-import { parseLabConfig } from "../lab/config.js";
-import { focusOf } from "../lab/parse/actors.js";
-import { posInt } from "../lab/parse/values.js";
-import { planLab } from "../lab/plan.js";
-import { routeOf } from "../lab/routing.js";
-import { LAB_CONFIG_SCHEMA, STUDY_SCHEMA } from "../lab/types.js";
-import { inertFieldPaths } from "../lab/warnings.js";
+import { parseStudyDocument } from "./config.js";
+import { focusOf } from "./parse/actors.js";
+import { posInt } from "./parse/values.js";
+import { planStudy } from "./plan.js";
+import { routeOf } from "./routing.js";
+import { V2_SCHEMA, STUDY_SCHEMA } from "./types.js";
+import { inertFieldPaths } from "./warnings.js";
 import { deleteNodeFieldPath, deletePlainFieldPath, pairIndex, readFieldPath, } from "./field-paths.js";
 function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -34,9 +34,9 @@ export function convertStudyText(text, cwd) {
     const raw = doc.toJS();
     if (!isPlainRecord(raw) || !isMap(doc.contents))
         return refuse("it is not a YAML mapping.");
-    if (raw.schema !== LAB_CONFIG_SCHEMA)
-        return refuse(`its schema is not ${LAB_CONFIG_SCHEMA}.`);
-    const source = parseLabConfig(raw);
+    if (raw.schema !== V2_SCHEMA)
+        return refuse(`its schema is not ${V2_SCHEMA}.`);
+    const source = parseStudyDocument(raw);
     if (!source.ok)
         return refuse(`it does not parse: ${source.error.message}`);
     const route = routeOf(source.config);
@@ -410,20 +410,20 @@ function samePlans(raw, dropped, text, cwd) {
     const projected = structuredClone(raw);
     for (const path of dropped)
         deletePlainFieldPath(projected, path);
-    const before = parseLabConfig(projected);
+    const before = parseStudyDocument(projected);
     if (!before.ok) {
         return refuse(`it does not parse once the unread keys are dropped: ${before.error.message}`);
     }
-    const after = parseLabConfig(parseDocument(text).toJS());
+    const after = parseStudyDocument(parseDocument(text).toJS());
     if (!after.ok)
         return refuse(`its v3 form does not parse: ${after.error.message}`);
-    if (JSON.stringify(plain({ ...after.config, schema: LAB_CONFIG_SCHEMA })) !==
+    if (JSON.stringify(plain({ ...after.config, schema: V2_SCHEMA })) !==
         JSON.stringify(plain(before.config))) {
         return refuse("its v3 form parses to a different study.");
     }
     for (const dryRun of [true, false]) {
-        const v2 = plain(planLab(before.config, { cwd, dryRun }));
-        const v3 = plain(planLab(after.config, { cwd, dryRun }));
+        const v2 = plain(planStudy(before.config, { cwd, dryRun }));
+        const v3 = plain(planStudy(after.config, { cwd, dryRun }));
         if (JSON.stringify(v2) !== JSON.stringify(v3)) {
             return refuse(`its v3 form plans a different ${dryRun ? "dry" : "live"} run.`);
         }

package/dist/{lab → study}/device-presets.d.ts

@@ -1,4 +1,4 @@
-import type { LabConfig } from "./types.js";
+import type { StudyConfig } from "./types.js";
 export interface DevicePreset {
     /** Requested device width; the hosted physical screen may be widened to its minimum. */
     width: number;
@@ -88,7 +88,7 @@ export declare function floorRenderResolution(resolution: readonly [number, numb
  * `resolution` is floored to MIN_DESKTOP_RENDER_WIDTH so the browser window fits its X screen (no clip);
  * `preset` keeps the declared device identity (a mobile preset stays 414/isMobile for the prompt).
  */
-export declare function resolveParticipantDevice(config: LabConfig, 
+export declare function resolveParticipantDevice(config: StudyConfig, 
 /** The device the participant's roster entry names, if any. */
 device: string | undefined): {
     name: string;

package/dist/{lab → study}/discover.d.ts

@@ -1,32 +1,32 @@
 import type { ActorPersonaRef } from "../actors/contract.js";
-import { type LabConfig } from "./types.js";
+import { type StudyConfig } from "./types.js";
 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;
-    origin: LabOrigin;
+type StudyOrigin = "committed" | "ignored" | "explicit";
+interface ResolvedStudyConfig {
+    config: StudyConfig;
+    origin: StudyOrigin;
     path: string;
     warnings: string[];
 }
-export interface LabResolveFailure {
+export interface StudyResolveFailure {
     ok: false;
     cwd: string;
     /** The study the caller asked for, as given. */
     study: string;
     error: {
-        code: "HUMANISH_STUDY_NOT_FOUND" | "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_AMBIGUOUS";
+        code: "HUMANISH_STUDY_NOT_FOUND" | "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_RETIRED_DIRECTORY";
         message: string;
     };
     warnings: string[];
 }
-export type LabResolveResult = ({
+export type StudyResolveResult = ({
     ok: true;
-} & ResolvedLabConfig) | LabResolveFailure;
-export interface LabListEntry {
+} & ResolvedStudyConfig) | StudyResolveFailure;
+export interface StudyListEntry {
     id: string;
-    source: LabConfig["subject"]["source"];
-    origin: LabOrigin;
+    source: StudyConfig["subject"]["source"];
+    origin: StudyOrigin;
     path: string;
     title?: string;
     /**
@@ -35,17 +35,23 @@ export interface LabListEntry {
      * 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 {
+/** A file in a study directory that humanish no longer reads, with what to do about it. */
+interface RetiredStudyFile {
+    path: string;
+    code: "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_RETIRED_DIRECTORY";
+    message: string;
+}
+export interface StudyListResult {
     schema: typeof STUDY_LIST_SCHEMA;
     ok: true;
     cwd: string;
-    studies: LabListEntry[];
+    studies: StudyListEntry[];
+    /** Each also has its message in `warnings`. */
+    retired: RetiredStudyFile[];
     warnings: string[];
 }
-export interface LabInspectResult {
+export interface StudyInspectResult {
     /** Persona context only, before route instructions and runtime grants. */
     personas?: Array<{
         id: string;
@@ -57,13 +63,13 @@ export interface LabInspectResult {
     cwd: string;
     /** The study the caller asked for, as given. */
     study: string;
-    config?: LabConfig;
-    origin?: LabOrigin;
+    config?: StudyConfig;
+    origin?: StudyOrigin;
     path?: string;
-    error?: LabResolveFailure["error"];
+    error?: StudyResolveFailure["error"];
     warnings: string[];
 }
-export declare function resolveLabManifest(cwd: string, lab: string): Promise<LabResolveResult>;
-export declare function listLabManifests(cwd: string): Promise<LabListResult>;
-export declare function inspectLabManifest(cwd: string, lab: string): Promise<LabInspectResult>;
+export declare function resolveStudyManifest(cwd: string, study: string): Promise<StudyResolveResult>;
+export declare function listStudyManifests(cwd: string): Promise<StudyListResult>;
+export declare function inspectStudyManifest(cwd: string, study: string): Promise<StudyInspectResult>;
 export {};