humanish 0.110.3 → 0.111.0

package/dist/study/keys.d.ts

@@ -1,3 +1,251 @@
+export type KeyShape = {
+    readonly [key: string]: true | KeyShape;
+};
+export declare const CAPS: {
+    maxUsd: true;
+    maxTotalUsd: true;
+    maxJobs: true;
+    maxMinutes: true;
+};
+export declare const PARTICIPANT_ENTRY: {
+    id: true;
+    actorType: true;
+    surface: true;
+    caseGroup: true;
+    persona: true;
+    device: true;
+    instruction: true;
+    target: true;
+    entry: true;
+    host: true;
+    reasoningEffort: true;
+    stopWhen: {
+        any: {
+            id: true;
+            urlIncludes: true;
+            urlPathEquals: true;
+            textIncludes: true;
+            appStatePathEquals: {
+                path: true;
+                equals: true;
+            };
+        };
+    };
+    dwell: {
+        ms: true;
+        everyMs: true;
+        then: true;
+        when: {
+            any: {
+                id: true;
+                urlIncludes: true;
+                urlPathEquals: true;
+                textIncludes: true;
+                appStatePathEquals: {
+                    path: true;
+                    equals: true;
+                };
+            };
+        };
+    };
+};
+export declare const SUBJECT: {
+    source: true;
+    exposure: true;
+    appUrl: true;
+    repos: true;
+    env: true;
+    envValues: true;
+    clone: {
+        depth: true;
+        fanout: true;
+        keep: true;
+    };
+    localTree: {
+        exclude: true;
+        keep: true;
+        maxArchiveBytes: true;
+    };
+    product: {
+        name: true;
+        install: true;
+        workdir: true;
+        upload: true;
+        publicSurfaces: true;
+    };
+    publicTarget: {
+        owner: true;
+        authorized: true;
+    };
+    serve: {
+        install: true;
+        installTimeoutMs: true;
+        build: true;
+        buildTimeoutMs: true;
+        start: true;
+        url: true;
+        readyTimeoutMs: true;
+    };
+    state: {
+        seed: {
+            name: true;
+            command: true;
+            when: true;
+            timeoutMs: true;
+        };
+        external: true;
+        checkpoint: {
+            name: true;
+            command: true;
+            redact: true;
+        };
+    };
+};
+export declare const ACTOR: {
+    type: true;
+    persona: true;
+    mission: true;
+    model: true;
+    maxOutputTokens: true;
+    localAgent: true;
+    reasoningEffort: true;
+    stopWhen: {
+        any: {
+            id: true;
+            urlIncludes: true;
+            urlPathEquals: true;
+            textIncludes: true;
+            appStatePathEquals: {
+                path: true;
+                equals: true;
+            };
+        };
+    };
+    dwell: {
+        ms: true;
+        everyMs: true;
+        then: true;
+        when: {
+            any: {
+                id: true;
+                urlIncludes: true;
+                urlPathEquals: true;
+                textIncludes: true;
+                appStatePathEquals: {
+                    path: true;
+                    equals: true;
+                };
+            };
+        };
+    };
+    tasks: {
+        id: true;
+        goal: true;
+        success: {
+            any: {
+                id: true;
+                urlIncludes: true;
+                urlPathEquals: true;
+                textIncludes: true;
+                appStatePathEquals: {
+                    path: true;
+                    equals: true;
+                };
+            };
+        };
+    };
+};
+export declare const EXECUTION: {
+    target: true;
+    runtime: {
+        version: true;
+    };
+    runtimeAuth: true;
+    concurrency: true;
+    timeoutMs: true;
+    completionTimeoutMs: true;
+    egressAllow: true;
+    terminal: {
+        stdin: true;
+        transport: true;
+    };
+    desktop: {
+        template: true;
+        browser: true;
+        device: true;
+        resolution: true;
+        sandboxTimeoutMs: true;
+        codexAppServer: true;
+        recording: true;
+        fidelity: {
+            mobileEmulation: true;
+            deviceScaleFactor: true;
+            touch: true;
+            userAgent: true;
+        };
+        media: {
+            camera: {
+                source: true;
+            };
+            microphone: {
+                source: true;
+            };
+        };
+    };
+};
+/** The sections a humanish.lab.v2 file shares with a v3 one. */
+export declare const SHARED_SECTIONS: {
+    policies: {
+        redactRepos: true;
+        redactScreenshots: true;
+        allowPublicTargets: true;
+        mediaPermission: true;
+        allowPrivateRepoAccess: true;
+        allowProviderCredentials: true;
+        allowPaymentCredentials: true;
+        allowGitHubMutation: true;
+    };
+    review: {
+        scoring: true;
+        milestones: true;
+        vocabulary: true;
+        scorer: {
+            ref: true;
+        };
+        analysis: true;
+    };
+    defaults: {
+        open: true;
+    };
+    comms: {
+        email: {
+            kind: true;
+            connection: true;
+            port: true;
+            smtp: {
+                hostEnv: true;
+                portEnv: true;
+                port: true;
+                userEnv: true;
+                user: true;
+                passwordEnv: true;
+                password: true;
+            };
+            external: {
+                catchBaseUrl: true;
+                inboxBaseUrl: true;
+                authTokenEnv: true;
+            };
+            injectEnv: true;
+            linkOrigin: true;
+            allowedOrigins: true;
+            recipients: {
+                lane: true;
+                address: true;
+            };
+        };
+    };
+};
 /**
  * Whether a dotted key path, such as `caps.maxUsd` or `participants[0].persona`, names a key a
  * humanish.study.v3 file can set. A path below a leaf is not one: `scenario.ref`, where `scenario`
@@ -10,7 +258,7 @@ export declare function isStudyKeyPath(path: string): boolean;
  * study file reference to these paths.
  */
 export declare function studyKeyPaths(depth: number): string[];
-/** The first key in `raw` that V2_KEYS does not list, as an error message; undefined if none. */
-export declare function findUnknownV2Key(raw: unknown): string | undefined;
 /** The first key in a humanish.study.v3 document that the format does not have; undefined if none. */
 export declare function findUnknownStudyKey(raw: unknown): string | undefined;
+/** The first key in `raw` that `shape` does not list, as an error message; undefined if none. */
+export declare function findUnknownKey(raw: unknown, shape: KeyShape): string | undefined;

package/dist/study/keys.js

@@ -1,7 +1,8 @@
 // Every mapping key parseStudy reads, by path. A key that is not listed fails the study as
 // unknown, so a typo stops the run instead of being dropped. `true` marks a leaf: its parser
 // checks the value (scalars, lists, and mappings that check their own keys). Each level satisfies
-// the parsed type's keys, so a field added to a Lab* interface must be added here too.
+// the parsed type's keys, so a field added to a Study* interface must be added here too.
+// migrate/v2.ts builds the humanish.lab.v2 table from the exported sections.
 const STOP_WHEN = {
     any: {
         id: true,
@@ -17,17 +18,17 @@ const STOP_WHEN = {
 const DWELL = {
     ms: true,
     everyMs: true,
-    // oxlint-disable-next-line unicorn/no-thenable -- `then` is the documented dwell field of humanish.lab.v2
+    // oxlint-disable-next-line unicorn/no-thenable -- `then` is the documented dwell field of a study
     then: true,
     when: STOP_WHEN,
 };
-const CAPS = {
+export const CAPS = {
     maxUsd: true,
     maxTotalUsd: true,
     maxJobs: true,
     maxMinutes: true,
 };
-const PARTICIPANT_ENTRY = {
+export const PARTICIPANT_ENTRY = {
     id: true,
     actorType: true,
     surface: true,
@@ -42,9 +43,8 @@ const PARTICIPANT_ENTRY = {
     stopWhen: STOP_WHEN,
     dwell: DWELL,
 };
-const SUBJECT = {
+export const SUBJECT = {
     source: true,
-    topology: true,
     exposure: true,
     appUrl: true,
     repos: true,
@@ -88,15 +88,8 @@ const SUBJECT = {
         },
     },
 };
-const ACTOR = {
+export const ACTOR = {
     type: true,
-    count: true,
-    lanes: PARTICIPANT_ENTRY,
-    // Roster groups are participants with a count; the parser expands them into `lanes[]`.
-    roster: {
-        ...PARTICIPANT_ENTRY,
-        count: true,
-    },
     persona: true,
     mission: true,
     model: true,
@@ -106,13 +99,8 @@ const ACTOR = {
     stopWhen: STOP_WHEN,
     dwell: DWELL,
     tasks: { id: true, goal: true, success: STOP_WHEN },
-    laneFocus: {
-        id: true,
-        label: true,
-        instruction: true,
-    },
 };
-const EXECUTION = {
+export const EXECUTION = {
     target: true,
     runtime: { version: true },
     runtimeAuth: true,
@@ -120,7 +108,6 @@ const EXECUTION = {
     timeoutMs: true,
     completionTimeoutMs: true,
     egressAllow: true,
-    caps: CAPS,
     terminal: { stdin: true, transport: true },
     desktop: {
         template: true,
@@ -166,22 +153,25 @@ const EMAIL = {
     allowedOrigins: true,
     recipients: { lane: true, address: true },
 };
-const V2_KEYS = {
+// humanish.study.v3. A list entry with a `count` is a group, so `participants` keys an entry's keys
+// and a group's together: parseStudy checks which form the route takes.
+const STUDY_KEYS = {
     schema: true,
     id: true,
     title: true,
     description: true,
+    route: true,
+    mode: true,
     subject: SUBJECT,
-    actors: ACTOR,
-    execution: EXECUTION,
-    // Inline personas are validated by the persona resolver.
-    personas: true,
-    scenario: {
-        ref: true,
-        mode: true,
-        inline: true,
-        caps: CAPS,
+    actor: ACTOR,
+    participants: {
+        ...PARTICIPANT_ENTRY,
+        count: true,
     },
+    surfaces: true,
+    caps: CAPS,
+    execution: EXECUTION,
+    scenario: true,
     policies: {
         redactRepos: true,
         redactScreenshots: true,
@@ -203,32 +193,12 @@ const V2_KEYS = {
     defaults: { open: true },
     comms: { email: EMAIL },
 };
-function without(shape, ...keys) {
-    return Object.fromEntries(Object.entries(shape).filter(([key]) => !keys.includes(key)));
-}
-// humanish.study.v3. The route is declared, so `subject.topology` goes. The participant keys leave
-// the actor for `participants`, and `caps` is one top-level block. Top-level `personas` and
-// `scenario.inline` are read by no route, and `scenario` is a string.
-const STUDY_KEYS = {
-    schema: true,
-    id: true,
-    title: true,
-    description: true,
-    route: true,
-    mode: true,
-    subject: without(SUBJECT, "topology"),
-    actor: without(ACTOR, "count", "lanes", "roster", "laneFocus"),
-    // A count, `{ count, instruction }` or a list of entries. studyToV2 checks which form the route
-    // takes; an entry with a count is a group.
-    participants: { ...PARTICIPANT_ENTRY, count: true },
-    surfaces: true,
-    caps: CAPS,
-    execution: without(EXECUTION, "caps"),
-    scenario: true,
-    policies: V2_KEYS.policies,
-    review: V2_KEYS.review,
-    defaults: V2_KEYS.defaults,
-    comms: V2_KEYS.comms,
+/** The sections a humanish.lab.v2 file shares with a v3 one. */
+export const SHARED_SECTIONS = {
+    policies: STUDY_KEYS.policies,
+    review: STUDY_KEYS.review,
+    defaults: STUDY_KEYS.defaults,
+    comms: STUDY_KEYS.comms,
 };
 /**
  * Whether a dotted key path, such as `caps.maxUsd` or `participants[0].persona`, names a key a
@@ -262,13 +232,13 @@ export function studyKeyPaths(depth) {
     visit(STUDY_KEYS, "", 1);
     return paths;
 }
-/** The first key in `raw` that V2_KEYS does not list, as an error message; undefined if none. */
-export function findUnknownV2Key(raw) {
-    return walk(raw, V2_KEYS, "", "study");
-}
 /** The first key in a humanish.study.v3 document that the format does not have; undefined if none. */
 export function findUnknownStudyKey(raw) {
-    return walk(raw, STUDY_KEYS, "", "study");
+    return findUnknownKey(raw, STUDY_KEYS);
+}
+/** The first key in `raw` that `shape` does not list, as an error message; undefined if none. */
+export function findUnknownKey(raw, shape) {
+    return walk(raw, shape, "", "study");
 }
 function walk(value, shape, path, noun) {
     if (Array.isArray(value)) {

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,14 @@
 // 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, parseStudyV3 } from "../config.js";
+import { posInt } from "../parse/values.js";
+import { planStudy } from "../plan.js";
+import { STUDY_SCHEMA } from "../types.js";
+import { deleteNodeFieldPath, deletePlainFieldPath, pairIndex, readFieldPath, } from "../field-paths.js";
+import { checkV2, droppedPaths, V2_SCHEMA, v2ShapeReason, v2ToV3Raw } from "./v2.js";
 function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -36,10 +34,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 +57,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 +67,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 +75,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 +111,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 +402,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,78 @@
+import { type StudyRoute } from "../routing.js";
+import { type StudyCaps, type StudyConfig, type StudyParticipantEntry } from "../types.js";
+/** The schema of the study format before humanish.study.v3. */
+export declare const V2_SCHEMA = "humanish.lab.v2";
+/** 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>.";
+type Raw = Record<string, unknown>;
+/** Where each humanish 0.110 StudyConfig field a config still sets went; empty when it sets none. */
+export declare function v2FieldMoves(config: unknown): string[];
+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?: StudyCaps;
+}
+/** 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,
+     * as a StudyConfig: subject, the actor, execution, policies and comms. Its `route` is the file's
+     * route, `shared-world` when `subject.topology` declares one, so routeOf and the composition
+     * checks read the declaration as the v2 parser did.
+     */
+    readonly composition: StudyConfig;
+    readonly topology: "per-lane-worlds" | "shared-world" | undefined;
+    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: StudyCaps | 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 (v3 paths, mapped back to the file's), 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 {};