humanish 0.110.4 → 0.111.1

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/migrate/convert.js

@@ -3,13 +3,12 @@
 // 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. v2.ts reads the v2 source.
 import { isAlias, isMap, isScalar, isSeq, LineCounter, Pair, parseDocument, Scalar, visit, YAMLMap, YAMLSeq, } from "yaml";
-import { parseStudy } from "../config.js";
-import { parseStudyV3 } from "../parse/study.js";
+import { parseStudy, parseStudyV3 } from "../config.js";
 import { posInt } from "../parse/values.js";
 import { planStudy } from "../plan.js";
-import { V2_SCHEMA, STUDY_SCHEMA } from "../types.js";
+import { STUDY_SCHEMA } from "../types.js";
 import { deleteNodeFieldPath, deletePlainFieldPath, pairIndex, readFieldPath, } from "../field-paths.js";
-import { checkV2, droppedPaths, v2ShapeReason, v2ToV3Raw } from "./v2.js";
+import { checkV2, droppedPaths, V2_SCHEMA, v2ShapeReason, v2ToV3Raw } from "./v2.js";
 function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

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

@@ -1,6 +1,17 @@
 import { type StudyRoute } from "../routing.js";
-import { type StudyConfig, type StudyParticipantEntry, type StudyScenarioCaps } from "../types.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[];
+/**
+ * The v2 key a hand-converted humanish.study.v3 file is most likely to keep, with where it went;
+ * undefined when the file keeps none. parse/front.ts refuses the file with it.
+ */
+export declare function movedV2KeyReason(raw: Raw): string | undefined;
 type Read<T> = {
     ok: true;
     value: T;
@@ -19,21 +30,24 @@ interface V2Scenario {
     ref?: string;
     mode?: "dry-run" | "live";
     inline?: Raw;
-    caps?: StudyScenarioCaps;
+    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:
-     * subject, the actor without its participant keys, execution, policies and comms.
+     * 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: StudyScenarioCaps | undefined;
+    readonly executionCaps: StudyCaps | undefined;
     readonly scenario: V2Scenario | undefined;
     readonly personas: boolean;
     readonly terminalTimeout: boolean;
@@ -61,8 +75,9 @@ export declare function v2ShapeReason(study: V2Study): string | undefined;
 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.
+ * 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 {};