humanish 0.110.3 → 0.110.4

package/dist/study/config.js

@@ -63,7 +63,7 @@ import { invalid, optionalStr, str } from "./parse/values.js";
 import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
 import { ID_PATTERN, V2_SCHEMA, STUDY_SCHEMA, } from "./types.js";
-import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "./validation.js";
+import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, smtpValidationReason, 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. */
@@ -84,7 +84,7 @@ export function parseStudy(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.
+ * nothing. The v2 parser's tests call it directly; migrate reads v2 files through migrate/v2.ts.
  */
 export function parseStudyDocument(raw) {
     if (!isRecord(raw)) {
@@ -190,9 +190,18 @@ function parseV2(raw) {
         return commsResult;
     if (commsResult.value)
         config.comms = commsResult.value;
-    if (config.comms?.email?.smtp && config.subject.topology === "shared-world") {
-        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.");
-    }
+    return checkStudyConfig(config);
+}
+/**
+ * The checks that read more than one section of a parsed config, and the defaults they fill:
+ * shared-world `execution.concurrency`, `comms.email.recipients` and the local browser's defaults.
+ * parseV2 runs them once every section has parsed. parse/study.ts runs them on its v2 view of a v3
+ * study.
+ */
+export function checkStudyConfig(config) {
+    const smtpReason = smtpValidationReason(config);
+    if (smtpReason)
+        return invalid(smtpReason);
     const mediaReason = desktopMediaValidationReason(config);
     if (mediaReason)
         return invalid(mediaReason);

package/dist/study/doctor.js

@@ -9,6 +9,7 @@ import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/codex-admission.js";
 import { cli } from "../cli/invocation.js";
+import { actorOf } from "./study-fields.js";
 /** A ready row's message, with the schema values the launch recorded. */
 function readyMessage(message, readiness) {
     const additions = protocolAdditionsWarning(readiness.cliVersion, readiness.protocolAdditions);
@@ -151,7 +152,7 @@ export async function studySetupChecks(args) {
         {
             name: "study route",
             ok: true,
-            message: `${config.id}: ${config.actors[0]?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
+            message: `${config.id}: ${actorOf(config)?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
         },
     ];
     if (dryRun)
@@ -246,16 +247,16 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
         ];
     }
     if ((route !== "computer-use" && route !== "shared-world") ||
-        config.actors[0]?.type !== "local-agent")
+        actorOf(config)?.type !== "local-agent")
         return [];
-    const choice = config.actors[0]?.localAgent ?? "codex";
+    const choice = actorOf(config)?.localAgent ?? "codex";
     const agent = args.agents.find((entry) => entry.id === choice);
     if (local)
         return [await localCodexParticipantCheck({ env: args.env, readiness: checkAccount })];
     // A signed-in hosted Codex gets the operator handshake; its sign-in status alone does not show
     // that the operator's config, release and model admit a launch.
     if (choice === "codex" && agent?.authStatus === "authenticated")
-        return [await hostedCodexParticipantCheck(args, config.actors[0])];
+        return [await hostedCodexParticipantCheck(args, actorOf(config))];
     const outdated = agent === undefined ? undefined : localAgentVersionRefusal(agent);
     return [
         {

package/dist/study/{convert.d.ts → migrate/convert.d.ts}

@@ -1,4 +1,4 @@
-import { type StudyRoute } from "./routing.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 → migrate/convert.js}

@@ -1,16 +1,15 @@
 // Convert a humanish.lab.v2 study file to humanish.study.v3. It edits the parsed YAML document in
 // place and moves each pair node, so the comments on a moved key move with it. The result lists
 // 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.
+// differently from the v2 source with the dropped keys removed. v2.ts reads the v2 source.
 import { isAlias, isMap, isScalar, isSeq, LineCounter, Pair, parseDocument, Scalar, visit, YAMLMap, YAMLSeq, } from "yaml";
-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";
+import { parseStudy } from "../config.js";
+import { parseStudyV3 } from "../parse/study.js";
+import { posInt } from "../parse/values.js";
+import { planStudy } from "../plan.js";
+import { V2_SCHEMA, STUDY_SCHEMA } from "../types.js";
+import { deleteNodeFieldPath, deletePlainFieldPath, pairIndex, readFieldPath, } from "../field-paths.js";
+import { checkV2, droppedPaths, v2ShapeReason, v2ToV3Raw } from "./v2.js";
 function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -36,10 +35,19 @@ export function convertStudyText(text, cwd) {
         return refuse("it is not a YAML mapping.");
     if (raw.schema !== V2_SCHEMA)
         return refuse(`its schema is not ${V2_SCHEMA}.`);
-    const source = parseStudyDocument(raw);
+    // The v2 parser's checks: the sections and the v2-only budget rule, then the checks the formats
+    // share on the v3 form of the file, then the rules on v2 shapes the v3 form cannot hold.
+    const source = checkV2(raw);
     if (!source.ok)
-        return refuse(`it does not parse: ${source.error.message}`);
-    const route = routeOf(source.config);
+        return refuse(`it does not parse: ${source.message}`);
+    const study = source.value;
+    const { route } = study;
+    const view = parseStudyV3(v2ToV3Raw(raw, route), { inert: "report" });
+    if (!view.ok)
+        return refuse(`it does not parse: ${view.error.message}`);
+    const shape = v2ShapeReason(study);
+    if (shape)
+        return refuse(`it does not parse: ${shape}`);
     const actorRaw = Array.isArray(raw.actors) ? raw.actors[0] : undefined;
     if (route === "terminal" && isPlainRecord(actorRaw)) {
         for (const key of ["count", "laneFocus"]) {
@@ -50,7 +58,7 @@ export function convertStudyText(text, cwd) {
     }
     const root = doc.contents;
     const dropped = [];
-    for (const path of droppedPaths(source.config, route, raw)) {
+    for (const path of droppedPaths(study, view.inert ?? [])) {
         const value = readFieldPath(raw, path);
         const pairs = deleteNodeFieldPath(root, path);
         if (value === undefined || pairs.length === 0)
@@ -60,8 +68,7 @@ export function convertStudyText(text, cwd) {
     }
     const moved = [];
     // v2 reads some laneFocus values as no focus at all ({}, a valueless key, valueless fields).
-    const focused = focusOf(source.config.actors[0]) !== undefined;
-    const converted = convertDocument(root, route, focused, moved);
+    const converted = convertDocument(root, route, study.focus !== undefined, moved);
     if (!converted.ok)
         return converted;
     const out = doc.toString({ lineWidth: foldWidth(text), flowCollectionPadding: false });
@@ -69,7 +76,7 @@ export function convertStudyText(text, cwd) {
     const lost = lostComment(text, out, dropped);
     if (lost !== undefined)
         return refuse(`it would lose the comment "${lost}".`);
-    const check = samePlans(raw, dropped.map((key) => key.path), out, cwd);
+    const check = samePlans(raw, route, dropped.map((key) => key.path), out, cwd);
     if (!check.ok)
         return check;
     return { ok: true, conversion: { text: out, route, moved, dropped } };
@@ -105,16 +112,6 @@ function lostComment(source, output, dropped) {
     }
     return undefined;
 }
-// The inert-field table's paths for the route, plus terminal `execution.timeoutMs`, which no
-// terminal code reads. Parents come before their children, so a child under a dropped parent is
-// reported with the parent.
-function droppedPaths(config, route, raw) {
-    const paths = inertFieldPaths(config);
-    if (route === "terminal" && readFieldPath(raw, "execution.timeoutMs") !== undefined)
-        paths.push("execution.timeoutMs");
-    const depth = (path) => path.split(".").length;
-    return [...new Set(paths)].sort((left, right) => depth(left) - depth(right));
-}
 // Folded text is folded again on output. Most of a file's long lines end near the width its author
 // folded at, so the 90th percentile of their lengths stands for it, between 80 and 120.
 function foldWidth(text) {
@@ -406,19 +403,20 @@ function numericCount(pair) {
 function plain(value) {
     return JSON.parse(JSON.stringify(value));
 }
-function samePlans(raw, dropped, text, cwd) {
+// The YAML rewrite against v2ToV3Raw of the source without the dropped keys: two rewrites written
+// separately, which must parse to the same study and plan the same runs.
+function samePlans(raw, route, dropped, text, cwd) {
     const projected = structuredClone(raw);
     for (const path of dropped)
         deletePlainFieldPath(projected, path);
-    const before = parseStudyDocument(projected);
+    const before = parseStudy(v2ToV3Raw(projected, route));
     if (!before.ok) {
         return refuse(`it does not parse once the unread keys are dropped: ${before.error.message}`);
     }
-    const after = parseStudyDocument(parseDocument(text).toJS());
+    const after = parseStudy(parseDocument(text).toJS());
     if (!after.ok)
         return refuse(`its v3 form does not parse: ${after.error.message}`);
-    if (JSON.stringify(plain({ ...after.config, schema: V2_SCHEMA })) !==
-        JSON.stringify(plain(before.config))) {
+    if (JSON.stringify(plain(after.config)) !== JSON.stringify(plain(before.config))) {
         return refuse("its v3 form parses to a different study.");
     }
     for (const dryRun of [true, false]) {

package/dist/study/{migrate.d.ts → migrate/migrate.d.ts}

@@ -1,4 +1,4 @@
-import type { StudyRoute } from "./routing.js";
+import type { StudyRoute } from "../routing.js";
 import { type DroppedKey, type MovedKey } from "./convert.js";
 /** The schema of `humanish migrate --json`. */
 declare const MIGRATE_SCHEMA = "humanish.migrate-result.v1";

package/dist/study/{migrate.js → migrate/migrate.js}

@@ -14,9 +14,9 @@ import { randomUUID } from "node:crypto";
 import { link, lstat, readdir, readFile, realpath, rename, rmdir } from "node:fs/promises";
 import path from "node:path";
 import { parseDocument } from "yaml";
-import { isNodeError } from "../run/type-guards.js";
+import { isNodeError } from "../../run/type-guards.js";
 import { convertStudyText, isStudyV3 } from "./convert.js";
-import { otherStudyFiles, STUDY_DIRECTORIES, studyFileStem } from "./files.js";
+import { otherStudyFiles, STUDY_DIRECTORIES, studyFileStem } from "../files.js";
 import { assertDirectory, bindDirectory, exists, fileIdentity, NO_HARD_LINKS, removeChecked, removeOwned, restoreName, sameFile, sha256, writeOwned, } from "./owned-files.js";
 /** The schema of `humanish migrate --json`. */
 const MIGRATE_SCHEMA = "humanish.migrate-result.v1";

package/dist/study/{owned-files.js → migrate/owned-files.js}

@@ -6,7 +6,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
 import path from "node:path";
-import { isNodeError } from "../run/type-guards.js";
+import { isNodeError } from "../../run/type-guards.js";
 export function sha256(bytes) {
     return createHash("sha256").update(bytes).digest("hex");
 }

package/dist/study/migrate/v2.d.ts

@@ -0,0 +1,68 @@
+import { type StudyRoute } from "../routing.js";
+import { type StudyConfig, type StudyParticipantEntry, type StudyScenarioCaps } from "../types.js";
+type Raw = Record<string, unknown>;
+type Read<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    message: string;
+};
+/** `laneFocus`: the steer each of a counted group of participants gets. */
+interface V2Focus {
+    id?: string;
+    label?: string;
+    instruction?: string;
+}
+/** The `scenario` object. */
+interface V2Scenario {
+    ref?: string;
+    mode?: "dry-run" | "live";
+    inline?: Raw;
+    caps?: StudyScenarioCaps;
+}
+/** A v2 file that checkV2 accepted, as the v2 parser reads it. */
+export interface V2Study {
+    readonly route: StudyRoute;
+    /**
+     * The sections that decide the route and that the v2 parser's first cross-section checks read:
+     * subject, the actor without its participant keys, execution, policies and comms.
+     */
+    readonly composition: StudyConfig;
+    readonly count: number | undefined;
+    /** `actors[0].lanes`, or the participants `actors[0].roster` expands into. */
+    readonly entries: readonly StudyParticipantEntry[] | undefined;
+    readonly focus: V2Focus | undefined;
+    readonly executionCaps: StudyScenarioCaps | undefined;
+    readonly scenario: V2Scenario | undefined;
+    readonly personas: boolean;
+    readonly terminalTimeout: boolean;
+}
+/**
+ * Check a humanish.lab.v2 file the way the v2 parser does, up to the checks that read more than
+ * one section, and then the budget rule those checks apply first. Each refusal is that parser's
+ * message.
+ */
+export declare function checkV2(raw: Raw): Read<V2Study>;
+/**
+ * The refusals the v2 parser gives for shapes a v3 file cannot express, once the checks both
+ * formats share have passed on the study without them. A file that also breaks a shared check
+ * gets that check's message.
+ */
+export declare function v2ShapeReason(study: V2Study): string | undefined;
+/**
+ * A v2 file as a plain humanish.study.v3 record, for parseStudyV3 and parseStudy. It reads each key
+ * it moves the way the v2 parser reads it (`count` as a positive integer, `laneFocus` through its
+ * string fields, `roster` groups expanded, `scenario.ref` and `scenario.mode` as strings), and
+ * leaves out every key no v3 file can hold, so it parses whenever the v2 parser would. A caps
+ * block keeps the keys its route reads. A shared world keeps a count or no list, which only
+ * parseStudyV3's report mode takes.
+ */
+export declare function v2ToV3Raw(raw: Raw, route: StudyRoute): Raw;
+/**
+ * The keys migrate drops: the v2-only rows above and `inert`, the fields parseStudyV3 reports the
+ * route does not read, then terminal `execution.timeoutMs`, which no terminal code reads. Parents
+ * come before their children, so a child under a dropped parent is reported with the parent.
+ */
+export declare function droppedPaths(study: V2Study, inert: readonly string[]): string[];
+export {};