humanish 0.106.1 → 0.108.0

package/dist/run-lab.js

@@ -6,10 +6,9 @@
 // refusal before it loads a declared review scorer.
 import { computerUseInput, scriptedInput, sharedWorldInput, terminalInput, } from "./lab/route-inputs.js";
 import { planLab, resolveLabDryRun, routeOf } from "./lab/plan.js";
-import { normalizeRunLabOptions, optionRefusalOutcome, } from "./lab/run-lab-options.js";
+import { normalizeRunLabOptions, optionRefusalOutcome, removedOptionRefusal, } from "./lab/run-lab-options.js";
 import {} from "./lab/types.js";
 import { admitComputerUsePlan, computerUseLabRefusal } from "./routes/computer-use/route.js";
-import { participantDesktopOf } from "./routes/computer-use/participant-desktop.js";
 import {} from "./routes/computer-use/types.js";
 import { admitPreviewPlan, previewLabRefusal } from "./routes/preview.js";
 import { admitScriptedPlan, scriptedLabRefusal } from "./routes/scripted/route.js";
@@ -19,48 +18,57 @@ import {} from "./routes/shared-world/types.js";
 import { admitTerminalPlan, terminalLabRefusal } from "./routes/terminal/route.js";
 import {} from "./routes/terminal/types.js";
 import {} from "./run/bundle.js";
-import {} from "./run/results.js";
-import {} from "./run/status.js";
 import { isLocalBrowserLab, localBrowserDefaults } from "./substrates/local/runtime-config.js";
 /**
  * Runs a lab on its route. The options are checked against the route and mapped into the route's
  * hook bags before anything runs. Each route closes the run it started on every exit through its
  * own run scope (`src/run/run.ts`).
  */
-export async function runLab(config, options) {
-    const prepared = await prepareLab(config, options);
+export async function runLab(config, options, deps = {}) {
+    const prepared = await prepareLab(config, options, deps);
     return prepared.ok ? prepared.run() : prepared.outcome;
 }
+/**
+ * runLab as the package exports it (`src/index.ts`): the public options only. A JavaScript caller
+ * that passes a field RunLabOptions no longer has is refused in the route's own result envelope
+ * before anything runs.
+ */
+export async function runPackageLab(config, options) {
+    const removed = removedOptionRefusal(options);
+    if (removed === undefined)
+        return runLab(config, options);
+    const lab = localBrowserDefaults(config);
+    return optionRefusalOutcome(lab, routeOf(lab), options, removed);
+}
 /**
  * Normalizes the options and plans the lab once, so a caller can present a refusal before it loads
- * anything the run needs. A local browser study's desktop lane and provider are bound first, so the
- * plan is made with them; with createDesktopLane the caller provides the desktop, and with
- * buildExecutor it drives the app in process and needs none.
+ * anything the run needs. A local browser study's provider is bound first, so the plan is made with
+ * it, and its desktop goes to the computer-use run as `localVm`; with inProcess the caller drives
+ * the app in process and needs no desktop.
  */
-export async function prepareLab(config, options) {
+export async function prepareLab(config, options, deps = {}) {
     const lab = localBrowserDefaults(config);
     const route = routeOf(lab);
     const normalized = normalizeRunLabOptions(lab, route, options);
     if (!normalized.ok)
         return { ok: false, outcome: optionRefusalOutcome(lab, route, options, normalized) };
-    const hooks = normalized.options.cuaHooks;
-    const localVm = isLocalBrowserLab(lab) &&
-        (hooks === undefined || participantDesktopOf(hooks) === undefined) &&
-        hooks?.buildExecutor === undefined
-        ? (await import("./routes/computer-use/local-vm.js")).prepareLocalVmStudy
+    // An in-process executor needs no desktop, and a caller that already prepared the study passes
+    // its localVm, which a second study would replace.
+    const prepareLocalVm = isLocalBrowserLab(lab) && options.inProcess === undefined && options.localVm === undefined
+        ? (await import("./routes/computer-use/local-vm.js")).prepareLocalVmRun
         : undefined;
-    const study = localVm?.({ ...normalized.options, config: lab });
-    const planning = study?.options ?? normalized.options;
-    const planned = planLab(lab, planning);
+    const vm = prepareLocalVm?.({ ...normalized.options, config: lab });
+    const planning = vm === undefined ? normalized.options : { ...vm.options, localVm: vm.localVm };
+    const planned = planLab(lab, planning, deps);
     if (!planned.ok) {
-        await study?.close();
-        const outcome = await refusalOutcome(lab, planning, planned.refusal);
+        await vm?.close();
+        const outcome = await refusalOutcome(lab, planning, planned.refusal, deps, normalized.emit);
         outcome.result.warnings.push(...normalized.warnings);
         return { ok: false, outcome };
     }
-    const admitted = await admitPlan(lab, planning, planned.planned.plan);
+    const admitted = await admitPlan(lab, planning, planned.planned.plan, deps, normalized.emit);
     if (!admitted.ok) {
-        await study?.close();
+        await vm?.close();
         admitted.outcome.result.warnings.push(...normalized.warnings);
         return { ok: false, outcome: admitted.outcome };
     }
@@ -88,61 +96,55 @@ export async function prepareLab(config, options) {
                 return outcome;
             }
             finally {
-                await study?.close();
+                await vm?.close();
             }
         },
     };
 }
 /** The route's admit function for a plan, with the route's input from the run's options. */
-async function admitPlan(config, options, plan) {
+async function admitPlan(config, options, plan, deps, emit) {
     switch (plan.route) {
         case "preview":
             return admitPreviewPlan(plan, options);
         case "computer-use":
-            return admitComputerUsePlan(plan, computerUseInput(options), config);
+            return admitComputerUsePlan(plan, computerUseInput(options, deps, emit), config);
         case "scripted":
-            return admitScriptedPlan(plan, scriptedInput(options));
+            return admitScriptedPlan(plan, scriptedInput(options, deps, emit));
         case "terminal":
-            return admitTerminalPlan(plan, terminalInput(options));
+            return admitTerminalPlan(plan, terminalInput(options, deps, emit));
         case "shared-world":
-            return admitSharedWorldPlan(plan, sharedWorldInput(options), config);
+            return admitSharedWorldPlan(plan, sharedWorldInput(options, deps, emit), config);
     }
 }
 /** The refused route's own result, with the envelope and analysis record its runner returns. */
-async function refusalOutcome(config, options, refusal) {
+async function refusalOutcome(config, options, refusal, deps, emit) {
     // Spend-safe default: a lab goes live only when the config (or CLI) says so.
     const dryRun = resolveLabDryRun(config, options.dryRun, true) ?? true;
-    const lab = options.lab === undefined ? {} : { lab: options.lab };
     switch (refusal.route) {
         case "preview":
             return {
                 route: "preview",
-                backend: "synthetic",
-                result: previewLabRefusal(options.cwd, refusal),
+                result: previewLabRefusal(options.cwd, config.id, refusal),
             };
         case "computer-use":
             return {
                 route: "computer-use",
-                backend: "cua",
-                result: await computerUseLabRefusal({ ...computerUseInput(options), ...lab, config, dryRun }, refusal),
+                result: await computerUseLabRefusal({ ...computerUseInput(options, deps, emit), config, dryRun }, refusal),
             };
         case "scripted":
             return {
                 route: "scripted",
-                backend: "scripted",
-                result: await scriptedLabRefusal({ ...scriptedInput(options), ...lab, config, dryRun }, refusal),
+                result: await scriptedLabRefusal({ ...scriptedInput(options, deps, emit), config, dryRun }, refusal),
             };
         case "terminal":
             return {
                 route: "terminal",
-                backend: "terminal",
-                result: await terminalLabRefusal({ ...terminalInput(options), ...lab, config, dryRun }, refusal),
+                result: await terminalLabRefusal({ ...terminalInput(options, deps, emit), config, dryRun }, refusal),
             };
         case "shared-world":
             return {
                 route: "shared-world",
-                backend: "concurrent-shared-world",
-                result: await sharedWorldLabRefusal({ ...sharedWorldInput(options), ...lab, config, dryRun }, refusal),
+                result: await sharedWorldLabRefusal({ ...sharedWorldInput(options, deps, emit), config, dryRun }, refusal),
             };
     }
 }

package/dist/study/convert.d.ts

@@ -0,0 +1,33 @@
+import type { StudyRoute } from "../lab/parse/study-v3.js";
+/** A key the conversion moved, by its v2 path and its v3 path. */
+export interface MovedKey {
+    readonly from: string;
+    readonly to: string;
+}
+/** A key the conversion dropped because the study's route never reads it. */
+export interface DroppedKey {
+    readonly path: string;
+    readonly value: unknown;
+    /** The comments that sat on the dropped key, which the v3 file no longer has. */
+    readonly comments?: string;
+}
+/** A v2 file converted to v3. */
+interface StudyConversion {
+    readonly text: string;
+    readonly route: StudyRoute;
+    readonly moved: readonly MovedKey[];
+    readonly dropped: readonly DroppedKey[];
+}
+/** The conversion, or why the file cannot be converted as it stands. */
+export type StudyConversionResult = {
+    readonly ok: true;
+    readonly conversion: StudyConversion;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Whether a parsed YAML value is a v3 study file. */
+export declare function isStudyV3(raw: unknown): boolean;
+/** Convert one v2 file's text. `cwd` is the project the plan check plans in. */
+export declare function convertStudyText(text: string, cwd: string): StudyConversionResult;
+export {};

package/dist/study/convert.js

@@ -0,0 +1,432 @@
+// 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.
+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 { deleteNodeFieldPath, deletePlainFieldPath, pairIndex, readFieldPath, } from "./field-paths.js";
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function refuse(reason) {
+    return { ok: false, reason };
+}
+/** Whether a parsed YAML value is a v3 study file. */
+export function isStudyV3(raw) {
+    return isPlainRecord(raw) && raw.schema === STUDY_SCHEMA;
+}
+/** Convert one v2 file's text. `cwd` is the project the plan check plans in. */
+export function convertStudyText(text, cwd) {
+    const lineCounter = new LineCounter();
+    const doc = parseDocument(text, { lineCounter });
+    if (doc.errors.length > 0)
+        return refuse(`it is not valid YAML: ${doc.errors[0].message}`);
+    const anchorLine = firstAnchorLine(doc, lineCounter);
+    if (anchorLine !== undefined) {
+        return refuse(`line ${anchorLine} uses a YAML anchor or alias. Write the value out in full, then migrate.`);
+    }
+    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 (!source.ok)
+        return refuse(`it does not parse: ${source.error.message}`);
+    const route = routeOf(source.config);
+    const actorRaw = Array.isArray(raw.actors) ? raw.actors[0] : undefined;
+    if (route === "terminal" && isPlainRecord(actorRaw)) {
+        for (const key of ["count", "laneFocus"]) {
+            if (actorRaw[key] !== undefined) {
+                return refuse(`actors[0].${key} does nothing on the terminal route, and a v3 terminal study has no participants. Remove it, then migrate.`);
+            }
+        }
+    }
+    const root = doc.contents;
+    const dropped = [];
+    for (const path of droppedPaths(source.config, route, raw)) {
+        const value = readFieldPath(raw, path);
+        const pairs = deleteNodeFieldPath(root, path);
+        if (value === undefined || pairs.length === 0)
+            continue;
+        const comments = pairComments(pairs);
+        dropped.push({ path, value, ...(comments === undefined ? {} : { comments }) });
+    }
+    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);
+    if (!converted.ok)
+        return converted;
+    const out = doc.toString({ lineWidth: foldWidth(text), flowCollectionPadding: false });
+    // Fail closed: a comment the conversion did not carry over or report stops it.
+    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);
+    if (!check.ok)
+        return check;
+    return { ok: true, conversion: { text: out, route, moved, dropped } };
+}
+// Every comment line in a YAML text, trimmed.
+function commentLinesOf(text) {
+    const doc = parseDocument(text);
+    const found = [doc.commentBefore ?? "", doc.comment ?? ""];
+    visit(doc, (_key, node) => {
+        // An implicit empty value, as `id` in `{id, instruction: x}`, is a null node.
+        if (typeof node !== "object" || node === null)
+            return;
+        const commented = node;
+        found.push(commented.commentBefore ?? "", commented.comment ?? "");
+    });
+    return found
+        .flatMap((comment) => comment.split("\n"))
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+// The first comment line of the source that is neither in the output nor in a dropped key's report.
+function lostComment(source, output, dropped) {
+    const kept = new Map();
+    const reported = dropped.flatMap((key) => (key.comments ?? "").split("\n"));
+    for (const line of [...commentLinesOf(output), ...reported.map((line) => line.trim())])
+        if (line)
+            kept.set(line, (kept.get(line) ?? 0) + 1);
+    for (const line of commentLinesOf(source)) {
+        const left = kept.get(line) ?? 0;
+        if (left === 0)
+            return line;
+        kept.set(line, left - 1);
+    }
+    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) {
+    const long = text
+        .split("\n")
+        .map((line) => line.length)
+        .filter((length) => length > 60)
+        .sort((left, right) => left - right);
+    if (long.length === 0)
+        return 80;
+    const width = long[Math.min(long.length - 1, Math.floor(long.length * 0.9))];
+    return Math.min(120, Math.max(80, width));
+}
+function firstAnchorLine(doc, lineCounter) {
+    let line;
+    visit(doc, (_key, node) => {
+        const anchored = isAlias(node) ||
+            (typeof node === "object" &&
+                node !== null &&
+                "anchor" in node &&
+                Boolean(node.anchor));
+        if (!anchored)
+            return undefined;
+        const offset = node.range?.[0] ?? 0;
+        line = lineCounter.linePos(offset).line;
+        return visit.BREAK;
+    });
+    return line;
+}
+// Every comment on a node and everything under it.
+function subtreeComments(node, found) {
+    if (typeof node !== "object" || node === null)
+        return;
+    const commented = node;
+    if (commented.commentBefore)
+        found.push(commented.commentBefore);
+    if (commented.comment)
+        found.push(commented.comment);
+    if (isMap(node) || isSeq(node)) {
+        for (const item of node.items) {
+            if (item instanceof Pair) {
+                subtreeComments(item.key, found);
+                subtreeComments(item.value, found);
+            }
+            else
+                subtreeComments(item, found);
+        }
+    }
+}
+function pairComments(pairs) {
+    const found = [];
+    for (const pair of pairs) {
+        subtreeComments(pair.key, found);
+        subtreeComments(pair.value, found);
+    }
+    const text = found
+        .flatMap((comment) => comment.split("\n"))
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join("\n");
+    return text.length > 0 ? text : undefined;
+}
+function keyNode(pair) {
+    return pair.key;
+}
+function rename(pair, key) {
+    keyNode(pair).value = key;
+}
+function addCommentBefore(pair, comment) {
+    if (!comment)
+        return;
+    const key = keyNode(pair);
+    key.commentBefore = key.commentBefore ? `${comment}\n${key.commentBefore}` : comment;
+}
+// Remove `key` from a mapping. A comment the mapping holds above its first key belongs to that key.
+function take(map, key) {
+    if (!isMap(map))
+        return undefined;
+    const index = pairIndex(map, key);
+    if (index < 0)
+        return undefined;
+    const [pair] = map.items.splice(index, 1);
+    if (index === 0 && map.commentBefore) {
+        addCommentBefore(pair, map.commentBefore);
+        map.commentBefore = null;
+    }
+    return pair;
+}
+function insertAfter(map, anchors, ...pairs) {
+    const anchor = anchors.map((key) => pairIndex(map, key)).find((index) => index >= 0);
+    map.items.splice(anchor === undefined ? 0 : anchor + 1, 0, ...pairs);
+}
+// A removed section's trailing comment goes above the pair that followed the section, which is
+// where it sat in the file, or to the end of the file when nothing followed.
+function keepTrailingComment(root, next, comment) {
+    if (!comment)
+        return;
+    if (next !== undefined)
+        addCommentBefore(next, comment);
+    else
+        root.comment = root.comment ? `${root.comment}\n${comment}` : comment;
+}
+// Remove a key from a top-level section, and the section with it once it is empty. The section's
+// own comments move to the promoted key.
+function promote(root, section, key) {
+    const index = pairIndex(root, section);
+    if (index < 0)
+        return undefined;
+    const container = root.items[index];
+    const pair = take(container.value, key);
+    if (pair === undefined)
+        return undefined;
+    if (isMap(container.value) && container.value.items.length === 0) {
+        const next = root.items[index + 1];
+        root.items.splice(index, 1);
+        addCommentBefore(pair, keyNode(container).commentBefore);
+        keepTrailingComment(root, next, container.value.comment);
+    }
+    return pair;
+}
+function convertDocument(root, route, focused, moved) {
+    const schema = root.items[pairIndex(root, "schema")];
+    if (schema && isScalar(schema.value))
+        schema.value.value = STUDY_SCHEMA;
+    // actors[0] becomes actor, at the same position.
+    const actorsPair = root.items[pairIndex(root, "actors")];
+    if (!actorsPair || !isSeq(actorsPair.value) || !isMap(actorsPair.value.items[0]))
+        return refuse("its actors list does not hold one actor mapping.");
+    const list = actorsPair.value;
+    const actor = list.items[0];
+    if (list.commentBefore)
+        actor.commentBefore = [list.commentBefore, actor.commentBefore].filter(Boolean).join("\n");
+    if (list.comment)
+        actor.comment = [actor.comment, list.comment].filter(Boolean).join("\n");
+    rename(actorsPair, "actor");
+    actorsPair.value = actor;
+    moved.push({ from: "actors[0]", to: "actor" });
+    let after = "actor";
+    const participants = participantsPair(actor, route, focused, moved);
+    if (participants !== undefined) {
+        insertAfter(root, [after], participants);
+        after = String(keyNode(participants).value);
+    }
+    const capsSection = route === "terminal" ? "scenario" : "execution";
+    const caps = promote(root, capsSection, "caps");
+    if (caps !== undefined) {
+        insertAfter(root, [after], caps);
+        moved.push({ from: `${capsSection}.caps`, to: "caps" });
+    }
+    // scenario.ref becomes scenario, a string, where scenario was; scenario.mode becomes mode.
+    let mode;
+    const scenarioIndex = pairIndex(root, "scenario");
+    if (scenarioIndex >= 0) {
+        const scenario = root.items[scenarioIndex];
+        mode = take(scenario.value, "mode");
+        const ref = take(scenario.value, "ref");
+        if (isMap(scenario.value) && scenario.value.items.length > 0) {
+            return refuse(`scenario still holds ${scenario.value.items.map((pair) => String(keyNode(pair).value)).join(", ")} after conversion.`);
+        }
+        const next = root.items[scenarioIndex + 1];
+        root.items.splice(scenarioIndex, 1);
+        const promoted = mode ?? ref;
+        // A comment on the `scenario:` line sits on the section's value, a mapping or an empty scalar,
+        // when nothing took it.
+        const value = scenario.value;
+        const note = [keyNode(scenario).commentBefore, value?.commentBefore].filter(Boolean).join("\n");
+        if (promoted !== undefined)
+            addCommentBefore(promoted, note);
+        else
+            keepTrailingComment(root, next, note);
+        keepTrailingComment(root, next, value?.comment);
+        if (ref !== undefined) {
+            rename(ref, "scenario");
+            root.items.splice(scenarioIndex, 0, ref);
+            moved.push({ from: "scenario.ref", to: "scenario" });
+        }
+        if (mode !== undefined)
+            moved.push({ from: "scenario.mode", to: "mode" });
+    }
+    const routePair = new Pair(new Scalar("route"), new Scalar(route));
+    // subject.topology says shared-world; route says it now, and takes its comments.
+    const subject = root.items[pairIndex(root, "subject")];
+    const topology = route === "shared-world" && subject ? take(subject.value, "topology") : undefined;
+    if (topology !== undefined) {
+        addCommentBefore(routePair, keyNode(topology).commentBefore);
+        const value = topology.value;
+        addCommentBefore(routePair, value?.commentBefore);
+        if (value?.comment)
+            routePair.value.comment = value.comment;
+        moved.push({ from: "subject.topology", to: "route" });
+    }
+    insertAfter(root, ["description", "title", "id"], ...[routePair, mode].filter((pair) => pair !== undefined));
+    return { ok: true };
+}
+// The participant keys leave the actor for `participants`, or `surfaces` on the scripted route.
+function participantsPair(actor, route, focused, moved) {
+    const count = take(actor, "count");
+    const entries = take(actor, "lanes");
+    const roster = take(actor, "roster");
+    let focus = take(actor, "laneFocus");
+    // A `laneFocus` v2 reads as no focus converts as if absent. Every comment in it goes above the
+    // count, or to the end of the actor.
+    if (focus !== undefined && !focused) {
+        const found = [];
+        subtreeComments(focus.key, found);
+        subtreeComments(focus.value, found);
+        const notes = found.join("\n");
+        if (count !== undefined)
+            addCommentBefore(count, notes);
+        else if (notes)
+            actor.comment = [actor.comment, notes].filter(Boolean).join("\n");
+        focus = undefined;
+    }
+    if (route === "scripted") {
+        if (count === undefined)
+            return undefined;
+        const surfaces = new YAMLSeq();
+        surfaces.flow = true;
+        const two = isScalar(count.value) && Number(count.value.value) === 2;
+        surfaces.items.push(new Scalar("desktop"), ...(two ? [new Scalar("mobile")] : []));
+        if (isScalar(count.value) && count.value.comment)
+            surfaces.comment = count.value.comment;
+        if (isScalar(count.value))
+            addCommentBefore(count, count.value.commentBefore);
+        rename(count, "surfaces");
+        count.value = surfaces;
+        moved.push({ from: "actors[0].count", to: "surfaces" });
+        return count;
+    }
+    const list = entries ?? roster;
+    if (list !== undefined) {
+        if (isSeq(list.value))
+            for (const item of list.value.items)
+                if (isMap(item))
+                    numericCount(item.items[pairIndex(item, "count")]);
+        rename(list, "participants");
+        moved.push({ from: `actors[0].${entries ? "lanes" : "roster"}`, to: "participants" });
+        return list;
+    }
+    if (focus !== undefined) {
+        const instruction = take(focus.value, "instruction");
+        const homogeneous = new YAMLMap();
+        // laneFocus's mapping, or the empty scalar a valueless `laneFocus:` holds, carries its comments.
+        const focusValue = focus.value;
+        if (focusValue?.comment)
+            homogeneous.comment = focusValue.comment;
+        if (focusValue?.commentBefore)
+            homogeneous.commentBefore = focusValue.commentBefore;
+        // Fields v2 read as unset (`id: null`) go with the old mapping; their comments stay.
+        const rest = [];
+        if (isMap(focus.value))
+            for (const item of focus.value.items) {
+                subtreeComments(item.key, rest);
+                subtreeComments(item.value, rest);
+            }
+        if (rest.length > 0)
+            homogeneous.comment = [homogeneous.comment, ...rest].filter(Boolean).join("\n");
+        numericCount(count);
+        if (count !== undefined)
+            homogeneous.items.push(count);
+        if (instruction !== undefined)
+            homogeneous.items.push(instruction);
+        rename(focus, "participants");
+        focus.value = homogeneous;
+        moved.push({ from: "actors[0].laneFocus", to: "participants" });
+        if (count !== undefined)
+            moved.push({ from: "actors[0].count", to: "participants.count" });
+        return focus;
+    }
+    if (count !== undefined) {
+        numericCount(count);
+        rename(count, "participants");
+        moved.push({ from: "actors[0].count", to: "participants" });
+        return count;
+    }
+    return undefined;
+}
+// v2 reads a count written as a digit string, such as "2"; v3 takes a number, so write the number.
+function numericCount(pair) {
+    if (pair === undefined || !isScalar(pair.value) || typeof pair.value.value !== "string")
+        return;
+    const count = posInt(pair.value.value);
+    if (count === undefined)
+        return;
+    pair.value.value = count;
+    pair.value.type = Scalar.PLAIN;
+}
+// JSON drops undefined fields, so two configs built through different branches compare by value.
+function plain(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function samePlans(raw, dropped, text, cwd) {
+    const projected = structuredClone(raw);
+    for (const path of dropped)
+        deletePlainFieldPath(projected, path);
+    const before = parseLabConfig(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());
+    if (!after.ok)
+        return refuse(`its v3 form does not parse: ${after.error.message}`);
+    if (JSON.stringify(plain({ ...after.config, schema: LAB_CONFIG_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 }));
+        if (JSON.stringify(v2) !== JSON.stringify(v3)) {
+            return refuse(`its v3 form plans a different ${dryRun ? "dry" : "live"} run.`);
+        }
+    }
+    return { ok: true };
+}

package/dist/study/field-paths.d.ts

@@ -0,0 +1,12 @@
+import { type Pair, type YAMLMap } from "yaml";
+/** The value at `path`, or for a `[]` segment the values found in each item; undefined if none. */
+export declare function readFieldPath(root: unknown, path: string): unknown;
+/** Delete `path` from a parsed object. Returns whether anything was deleted. */
+export declare function deletePlainFieldPath(root: unknown, path: string): boolean;
+/** The index of `key`'s pair in a YAML mapping, or -1. */
+export declare function pairIndex(map: YAMLMap, key: string): number;
+/**
+ * Delete `path` from a YAML document's root mapping. Returns the deleted pairs, including the
+ * mappings a deletion left empty, so the caller can report their comments.
+ */
+export declare function deleteNodeFieldPath(root: unknown, path: string): Pair[];