humanish 0.106.1 → 0.108.0

package/dist/lab/parse/study-v3.js

@@ -0,0 +1,259 @@
+// humanish.study.v3, the study format. A study declares its route, one `actor`, its `participants`
+// and one `caps` block. studyToV2 rewrites a v3 document into the v2 spelling, so both formats run
+// through one parser and parse into the same LabConfig. parseLabConfig then checks the declared
+// route against the one the config takes, and refuses any field that route does not read.
+import { isRecord } from "../../run/type-guards.js";
+import { findUnknownStudyKey } from "../keys.js";
+import { LAB_CONFIG_SCHEMA } from "../types.js";
+import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./actors.js";
+import { invalid, posInt } from "./values.js";
+// The values `route:` takes: every route routeOf can return.
+const ROUTES = [
+    "preview",
+    "computer-use",
+    "shared-world",
+    "terminal",
+    "scripted",
+];
+// The caps keys each route reads. Computer use and shared world stop on estimated model spend;
+// the terminal route checks its spend ledger, product jobs and the command deadline.
+const CAPS_KEYS = {
+    preview: [],
+    "computer-use": ["maxUsd", "maxTotalUsd"],
+    "shared-world": ["maxUsd", "maxTotalUsd"],
+    terminal: ["maxUsd", "maxJobs", "maxMinutes"],
+    scripted: [],
+};
+/** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
+export function studyToV2(raw) {
+    const moved = movedKeyReason(raw);
+    if (moved)
+        return invalid(moved);
+    const unknownKey = findUnknownStudyKey(raw);
+    if (unknownKey)
+        return invalid(unknownKey);
+    const route = ROUTES.find((name) => name === raw.route);
+    if (route === undefined) {
+        return invalid(`A study needs \`route:\`, one of ${ROUTES.join(", ")}.`);
+    }
+    if (raw.mode !== undefined && raw.mode !== "dry-run" && raw.mode !== "live") {
+        return invalid("`mode` must be `dry-run` or `live`. Leave it out for a dry run.");
+    }
+    if (!isRecord(raw.actor)) {
+        return invalid("A study needs `actor:`, an object with at least `type`.");
+    }
+    if (raw.scenario !== undefined && typeof raw.scenario !== "string") {
+        return invalid("`scenario` is a scenario id or a path to one, as a string.");
+    }
+    const participants = participantsOf(route, raw.participants);
+    if (!participants.ok)
+        return participants;
+    const surfaces = surfaceCount(route, raw.surfaces);
+    if (!surfaces.ok)
+        return surfaces;
+    const capsReason = capsKeysReason(route, raw.caps);
+    if (capsReason)
+        return invalid(capsReason);
+    // The v2 inert-field table does not list this one, but the terminal planner never reads it.
+    if (route === "terminal" && isRecord(raw.execution) && raw.execution.timeoutMs !== undefined) {
+        return invalid("route: terminal does not read `execution.timeoutMs`: `caps.maxMinutes` is the command deadline. Remove it.");
+    }
+    const { count, instruction, entries, source } = participants.value;
+    // The v2 actor keys that hold participants.
+    const v2Participants = [
+        ["count", count ?? surfaces.value],
+        ["laneFocus", instruction === undefined ? undefined : { instruction }],
+        ["lanes", entries],
+    ];
+    const actor = { ...raw.actor };
+    for (const [key, value] of v2Participants)
+        if (value !== undefined)
+            actor[key] = value;
+    const caps = raw.caps;
+    const scenario = {};
+    if (raw.scenario !== undefined)
+        scenario.ref = raw.scenario;
+    if (raw.mode !== undefined)
+        scenario.mode = raw.mode;
+    if (caps !== undefined && route === "terminal")
+        scenario.caps = caps;
+    const execution = caps !== undefined && route !== "terminal"
+        ? withKey(raw.execution, "caps", caps)
+        : raw.execution;
+    const subject = route === "shared-world" ? withKey(raw.subject, "topology", "shared-world") : raw.subject;
+    const v2 = { schema: LAB_CONFIG_SCHEMA };
+    const fields = [
+        ["id", raw.id],
+        ["title", raw.title],
+        ["description", raw.description],
+        ["subject", subject],
+        ["actors", [actor]],
+        ["execution", execution],
+        ["scenario", Object.keys(scenario).length > 0 ? scenario : undefined],
+        ["policies", raw.policies],
+        ["review", raw.review],
+        ["defaults", raw.defaults],
+        ["comms", raw.comms],
+    ];
+    for (const [key, value] of fields)
+        if (value !== undefined)
+            v2[key] = value;
+    return { ok: true, value: { route, v2, participantSource: source } };
+}
+/**
+ * Spell a v2 parser message the way the study file is written: `actors[0].lanes[3]` becomes the
+ * `participants` entry it came from, `execution.caps` and `scenario.caps` become `caps`, and so on.
+ */
+export function studySpelling(message, route, participantSource) {
+    return (message
+        .replaceAll(/actors\[0\]\.lanes\[(\d+)\]/g, (_match, index) => `participants[${participantSource[Number(index)] ?? index}]`)
+        // "an `actors[0].lanes` roster" reads "a `participants` list" in a v3 file.
+        .replaceAll(/\ban `actors\[0\]\.(lanes|roster)` roster\b/g, "a `participants` list")
+        .replaceAll(/actors\[0\]\.(lanes|roster)\b/g, "participants")
+        .replaceAll(/actors\[0\]\.laneFocus(\.instruction)?/g, "participants.instruction")
+        .replaceAll(/actors\[0\]\.count\b/g, route === "scripted" ? "surfaces" : "participants")
+        .replaceAll("actors[0]", "actor")
+        .replaceAll(/\b(execution|scenario)\.caps\b/g, "caps")
+        .replaceAll(/\bscenario\.mode\b/g, "mode")
+        .replaceAll(/\bscenario\.ref\b/g, "scenario")
+        .replaceAll("subject.topology: shared-world", "route: shared-world"));
+}
+// The v2 keys a hand-converted file is most likely to keep, each with where it went.
+function movedKeyReason(raw) {
+    if (raw.actors !== undefined) {
+        return "A study has one `actor:` object, and its participants go in `participants:`. `actors:` is the humanish.lab.v2 spelling.";
+    }
+    if (isRecord(raw.actor)) {
+        for (const key of ["count", "lanes", "roster", "laneFocus"]) {
+            if (raw.actor[key] !== undefined) {
+                return `\`actor.${key}\` moved to \`participants:\`: a count, \`{ count, instruction }\`, or a list of participants.`;
+            }
+        }
+    }
+    if (isRecord(raw.subject) && raw.subject.topology !== undefined) {
+        return "`subject.topology` moved to `route:`. A shared world is `route: shared-world`.";
+    }
+    if (isRecord(raw.execution) && raw.execution.caps !== undefined) {
+        return "`execution.caps` moved to a top-level `caps:` block.";
+    }
+    return undefined;
+}
+function participantsOf(route, raw) {
+    if (raw === undefined) {
+        if (route === "shared-world")
+            return invalid(listOnly(route));
+        return { ok: true, value: { source: [] } };
+    }
+    switch (route) {
+        case "scripted":
+            return invalid("route: scripted takes no `participants`. It replays committed steps on `surfaces`: [desktop] or [desktop, mobile].");
+        case "terminal":
+            return invalid("route: terminal takes no `participants`. It runs one agent.");
+        case "preview":
+            return typeof raw === "number"
+                ? countOf(raw)
+                : invalid("route: preview takes `participants` as a count, such as `participants: 4`.");
+        case "shared-world":
+            return Array.isArray(raw) ? entriesOf(raw) : invalid(listOnly(route));
+        case "computer-use":
+            if (typeof raw === "number")
+                return countOf(raw);
+            if (Array.isArray(raw))
+                return entriesOf(raw);
+            return homogeneousOf(raw);
+    }
+}
+function listOnly(route) {
+    return `route: ${route} takes \`participants\` as a list of at least two entries, one per participant in the shared world.`;
+}
+function countOf(raw) {
+    const count = posInt(raw);
+    if (count === undefined)
+        return invalid("`participants` must be a positive integer.");
+    return { ok: true, value: { count, source: [] } };
+}
+// `{ count, instruction }`: participants that share one instruction. The count stays a count, so
+// `--count` still overrides it.
+function homogeneousOf(raw) {
+    if (!isRecord(raw)) {
+        return invalid("`participants` is a count, an object `{ count, instruction }`, or a list of participants.");
+    }
+    const extra = Object.keys(raw).filter((key) => key !== "count" && key !== "instruction");
+    if (extra.length > 0) {
+        return invalid(`\`participants\` as an object takes only \`count\` and \`instruction\`, and every participant gets them. To set ${extra.map((key) => `\`${key}\``).join(", ")}, write participants as a list.`);
+    }
+    const participants = { source: [] };
+    if (raw.count !== undefined) {
+        const count = typeof raw.count === "number" ? posInt(raw.count) : undefined;
+        if (count === undefined)
+            return invalid("`participants.count` must be a positive integer.");
+        participants.count = count;
+    }
+    if (raw.instruction !== undefined)
+        participants.instruction = raw.instruction;
+    return { ok: true, value: participants };
+}
+// A list entry with `count: n` is a group: n participants `<id>-01` to `<id>-NN`, even when n is 1.
+// The v2 parser then checks every entry and the expanded ids for collisions.
+function entriesOf(raw) {
+    const entries = [];
+    const source = [];
+    for (const [index, entry] of raw.entries()) {
+        if (!isRecord(entry) || entry.count === undefined) {
+            entries.push(entry);
+            source.push(index);
+            continue;
+        }
+        const count = typeof entry.count === "number" ? posInt(entry.count) : undefined;
+        if (count === undefined) {
+            return invalid(`participants[${index}].count must be a positive integer.`);
+        }
+        const id = entry.id;
+        if (typeof id !== "string" ||
+            !PARTICIPANT_ID_PATTERN.test(id) ||
+            id.length > PARTICIPANT_ID_MAX_CHARS - 3) {
+            return invalid(`participants[${index}] has a count, so it needs an \`id\` matching ${PARTICIPANT_ID_PATTERN} of at most ${PARTICIPANT_ID_MAX_CHARS - 3} characters. Its participants are <id>-01 to <id>-${String(count).padStart(2, "0")}.`);
+        }
+        const shared = { ...entry };
+        delete shared.count;
+        for (let n = 1; n <= count; n += 1) {
+            entries.push({ ...shared, id: `${id}-${String(n).padStart(2, "0")}` });
+            source.push(index);
+        }
+    }
+    return { ok: true, value: { entries, source } };
+}
+// Scripted surfaces become the v2 count: 1 is desktop, 2 adds mobile.
+function surfaceCount(route, raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (route !== "scripted") {
+        return invalid(`\`surfaces\` belongs to route: scripted. This study's route is ${route}; remove it.`);
+    }
+    if (Array.isArray(raw) && raw.length === 1 && raw[0] === "desktop")
+        return { ok: true, value: 1 };
+    if (Array.isArray(raw) && raw.length === 2 && raw[0] === "desktop" && raw[1] === "mobile") {
+        return { ok: true, value: 2 };
+    }
+    return invalid("`surfaces` must be [desktop] or [desktop, mobile].");
+}
+function capsKeysReason(route, raw) {
+    if (raw === undefined)
+        return undefined;
+    const read = CAPS_KEYS[route];
+    if (read.length === 0)
+        return `route: ${route} reads no \`caps\`; remove the block.`;
+    if (!isRecord(raw))
+        return undefined;
+    const unread = Object.keys(raw).filter((key) => !read.includes(key));
+    if (unread.length === 0)
+        return undefined;
+    return `route: ${route} reads only ${read.map((key) => `caps.${key}`).join(", ")}. Remove ${unread.map((key) => `caps.${key}`).join(", ")}.`;
+}
+// Add one key to a section. A section that is not an object passes through unchanged, so the v2
+// parser refuses it with its own message.
+function withKey(section, key, value) {
+    if (section === undefined)
+        return { [key]: value };
+    return isRecord(section) ? { ...section, [key]: value } : section;
+}

package/dist/lab/parse/subject-state.d.ts

@@ -1,10 +1,10 @@
 import type { LabConfigParseFailure, LabSubjectState } from "../types.js";
 /**
- * LITERAL non-secret subject env. Real apps need configuration before they will boot — a public base
- * URL, a transport selector, a feature flag — and none of that is secret. Routing it through
+ * Literal non-secret subject env. Real apps need configuration before they will boot: a public base
+ * URL, a transport selector, a feature flag, and none of that is secret. Routing it through
  * `subject.env` would force an adopter to carry a private env file just to reproduce a public study.
  *
- * These values ARE recorded in evidence (they are part of how the subject was configured), so a
+ * These values are recorded in evidence (they are part of how the subject was configured), so a
  * value that looks like a credential is refused here rather than committed to a public repo.
  */
 export declare function parseEnvValues(raw: unknown): {
@@ -14,8 +14,8 @@ export declare function parseEnvValues(raw: unknown): {
 /**
  * Structural parse of `subject.state` into a candidate LabSubjectState. Deliberately keeps
  * unrecognized `when`/`timeoutMs` values in the candidate (instead of silently dropping
- * them) so subjectStateInvalidReason rejects them — a state declaration that silently does
- * less than it says would violate invariant 6.
+ * them) so subjectStateInvalidReason rejects them: a state declaration that silently does
+ * less than it says would claim more than its mechanism does.
  */
 export declare function parseState(raw: unknown): {
     ok: true;
@@ -23,8 +23,8 @@ export declare function parseState(raw: unknown): {
 } | LabConfigParseFailure;
 /**
  * Semantic validation for `subject.state`, shared by parseLabConfig and the engine
- * (runCuaActorLab re-enforces it on configs that arrive through the library API). Returns
+ * (the route re-enforces it on configs that arrive through runLab). Returns
  * the failure message, or null when the declaration is valid. Reads the candidate
- * defensively — library callers can hand the engine arbitrarily-shaped objects.
+ * defensively: library callers can hand the engine arbitrarily-shaped objects.
  */
 export declare function subjectStateInvalidReason(state: LabSubjectState, env: readonly string[] | undefined): string | null;

package/dist/lab/parse/subject-state.js

@@ -2,25 +2,26 @@
 // the structural parse of `subject.state`, and subjectStateInvalidReason, the semantic check
 // parseLabConfig and the computer-use route share.
 import { containsSensitive } from "../../evidence/redaction.js";
-import { ENV_NAME_PATTERN, invalid, isRecord, posInt, str, strList } from "./values.js";
+import { ENV_NAME_PATTERN, invalid, posInt, str, strList } from "./values.js";
+import { isRecord } from "../../run/type-guards.js";
 /**
- * LITERAL non-secret subject env. Real apps need configuration before they will boot — a public base
- * URL, a transport selector, a feature flag — and none of that is secret. Routing it through
+ * Literal non-secret subject env. Real apps need configuration before they will boot: a public base
+ * URL, a transport selector, a feature flag, and none of that is secret. Routing it through
  * `subject.env` would force an adopter to carry a private env file just to reproduce a public study.
  *
- * These values ARE recorded in evidence (they are part of how the subject was configured), so a
+ * These values are recorded in evidence (they are part of how the subject was configured), so a
  * value that looks like a credential is refused here rather than committed to a public repo.
  */
 export function parseEnvValues(raw) {
     if (raw === undefined)
         return { ok: true };
     if (!isRecord(raw)) {
-        return invalid("`subject.envValues` must be a mapping of env var NAME to a literal non-secret value.");
+        return invalid("`subject.envValues` must map environment variable names to literal values that are not secret.");
     }
     const envValues = {};
     for (const [name, rawValue] of Object.entries(raw)) {
         if (!ENV_NAME_PATTERN.test(name)) {
-            return invalid(`subject.envValues keys must be env var NAMES like NEXT_PUBLIC_APP_URL (got "${name}").`);
+            return invalid(`subject.envValues keys must be environment variable names like NEXT_PUBLIC_APP_URL, and "${name}" is not one.`);
         }
         const value = typeof rawValue === "number" || typeof rawValue === "boolean"
             ? String(rawValue)
@@ -29,9 +30,9 @@ export function parseEnvValues(raw) {
             return invalid(`\`subject.envValues.${name}\` must be a string, number, or boolean.`);
         }
         // Reuse the redaction module's own detector rather than inventing a second opinion about what
-        // a secret looks like — the two must never disagree about the same string.
+        // a secret looks like; the two must never disagree about the same string.
         if (containsSensitive(value)) {
-            return invalid(`\`subject.envValues.${name}\` looks like a secret or a local path, and these values are committed with the lab and recorded in evidence. Declare the NAME in \`subject.env\` instead — those values come from the caller's environment and never persist.`);
+            return invalid(`\`subject.envValues.${name}\` looks like a secret or a local path, and envValues are committed with the study and recorded in evidence. List the name in \`subject.env\` instead: its value then comes from your environment and is never stored.`);
         }
         envValues[name] = value;
     }
@@ -40,8 +41,8 @@ export function parseEnvValues(raw) {
 /**
  * Structural parse of `subject.state` into a candidate LabSubjectState. Deliberately keeps
  * unrecognized `when`/`timeoutMs` values in the candidate (instead of silently dropping
- * them) so subjectStateInvalidReason rejects them — a state declaration that silently does
- * less than it says would violate invariant 6.
+ * them) so subjectStateInvalidReason rejects them: a state declaration that silently does
+ * less than it says would claim more than its mechanism does.
  */
 export function parseState(raw) {
     if (raw === undefined) {
@@ -67,7 +68,7 @@ export function parseState(raw) {
     if (raw.external !== undefined) {
         const external = strList(raw.external);
         if (!external) {
-            return invalid("`subject.state.external` must be a non-empty list of env var NAMES when set.");
+            return invalid("`subject.state.external` must be a non-empty list of environment variable names when it is set.");
         }
         state.external = external;
     }
@@ -78,7 +79,7 @@ export function parseState(raw) {
         state.checkpoint = raw.checkpoint.map((probe) => ({
             name: typeof probe.name === "string" ? probe.name.trim() : "",
             command: typeof probe.command === "string" ? probe.command.trim() : "",
-            // Preserve the redact list verbatim (literal secret values may contain commas, so do NOT
+            // Preserve the redact list verbatim (literal secret values may contain commas, so do not
             // run it through the comma-splitting strList); subjectStateInvalidReason validates the shape.
             ...(probe.redact === undefined ? {} : { redact: probe.redact }),
         }));
@@ -86,7 +87,7 @@ export function parseState(raw) {
     return { ok: true, value: state };
 }
 // The step name interpolates into in-sandbox script/status/log paths (`subject-state-<name>`);
-// the strict shape is load-bearing, exactly like the repo slug.
+// so the shape is strict, exactly like the repo slug.
 const STATE_STEP_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const STATE_STEP_NAME_MAX_CHARS = 40;
 const STATE_STEP_WHENS = [
@@ -96,9 +97,9 @@ const STATE_STEP_WHENS = [
 ];
 /**
  * Semantic validation for `subject.state`, shared by parseLabConfig and the engine
- * (runCuaActorLab re-enforces it on configs that arrive through the library API). Returns
+ * (the route re-enforces it on configs that arrive through runLab). Returns
  * the failure message, or null when the declaration is valid. Reads the candidate
- * defensively — library callers can hand the engine arbitrarily-shaped objects.
+ * defensively: library callers can hand the engine arbitrarily-shaped objects.
  */
 export function subjectStateInvalidReason(state, env) {
     const seed = state.seed;
@@ -139,11 +140,11 @@ export function subjectStateInvalidReason(state, env) {
     }
     if (external !== undefined) {
         if (!Array.isArray(external) || external.length === 0) {
-            return "`subject.state.external` must be a non-empty list of env var NAMES when set.";
+            return "`subject.state.external` must be a non-empty list of environment variable names when it is set.";
         }
         for (const name of external) {
             if (typeof name !== "string" || !ENV_NAME_PATTERN.test(name)) {
-                return "subject.state.external entries must be env var NAMES like DATABASE_URL; values come from the caller's environment and are never persisted.";
+                return "subject.state.external entries must be environment variable names like DATABASE_URL. Their values come from your environment and are never stored.";
             }
             if (!env?.includes(name)) {
                 return "subject.state.external names must also be declared in subject.env (the declaration must name a provisioned channel).";

package/dist/lab/parse/subject.js

@@ -1,6 +1,7 @@
 import { normalizeExtraExcludeEntry } from "../../subject/local-tree-archive.js";
-import { ENV_NAME_PATTERN, invalid, isRecord, posInt, str, strList } from "./values.js";
+import { ENV_NAME_PATTERN, invalid, posInt, str, strList } from "./values.js";
 import { parseEnvValues, parseState, subjectStateInvalidReason } from "./subject-state.js";
+import { isRecord } from "../../run/type-guards.js";
 export function parseSubject(raw) {
     if (!isRecord(raw)) {
         return invalid("Lab `subject` is required and must be an object.");
@@ -16,9 +17,9 @@ export function parseSubject(raw) {
         return invalid("`subject.source` must be one of: this-repo, clone, app-url, local-app, terminal-product, desktop-cli, local-tree.");
     }
     const subject = { source };
-    // topology is enum-validated everywhere; its SEMANTICS (shared-world requires clone × e2b-desktop
+    // topology is enum-validated everywhere; its semantics (shared-world requires clone × e2b-desktop
     // × a ≥2 roster) are enforced in the shared-world cross-validation below, and a set-but-unconsumed
-    // topology warns as inert off the shared-world route (invariant 6).
+    // topology warns as inert off the shared-world route.
     if (raw.topology !== undefined) {
         const topology = str(raw.topology);
         if (topology !== "per-lane-worlds" && topology !== "shared-world") {
@@ -26,12 +27,12 @@ export function parseSubject(raw) {
         }
         subject.topology = topology;
     }
-    // exposure is enum-validated everywhere; it is REQUIRED on the concurrent shared-world route (the
+    // exposure is enum-validated everywhere; it is required on the concurrent shared-world route (the
     // getHost synthetic-subject attestation) and warns inert elsewhere.
     if (raw.exposure !== undefined) {
         const exposure = str(raw.exposure);
         if (exposure !== "synthetic") {
-            return invalid("`subject.exposure` must be `synthetic` (the author attestation that the getHost-exposed subject is synthetic seeded data).");
+            return invalid("`subject.exposure` must be `synthetic`: your statement that the subject served on a public sandbox URL holds only synthetic seeded data.");
         }
         subject.exposure = exposure;
     }
@@ -56,15 +57,15 @@ export function parseSubject(raw) {
 }
 /** The first field set on a source it cannot act on, in the order parseSubject has always checked. */
 function misplacedFieldFailure(source, raw) {
-    // `product` is terminal-product-only; reject it elsewhere (invariant 6: a field that cannot act
-    // on this route is an honest parse error, not silently dropped).
+    // `product` is terminal-product-only; reject it elsewhere. A field that cannot act on this
+    // route is a parse error and is never silently dropped.
     if (source !== "terminal-product" && source !== "desktop-cli" && raw.product !== undefined) {
         return invalid("`subject.product` applies only to terminal-product and desktop-cli subjects (the CLI a participant studies from public surfaces).");
     }
-    // appUrl is app-url/local-app-only; a terminal-product subject drives PUBLIC surfaces, not a
-    // single loopback app — reject appUrl on it.
+    // appUrl is app-url/local-app-only; a terminal-product subject drives public surfaces instead of a
+    // single loopback app, so reject appUrl on it.
     if (source === "terminal-product" && raw.appUrl !== undefined) {
-        return invalid("`subject.appUrl` does not apply to terminal-product subjects — declare `subject.product.publicSurfaces` (the agent works from public surfaces, not one loopback app).");
+        return invalid("`subject.appUrl` does not apply to a terminal-product subject: its agent works from the product's public pages. List them in `subject.product.publicSurfaces` instead.");
     }
     // serve/env/state are shared between clone (cloned app) and local-tree (packed working
     // tree): both routes serve a subject in-sandbox with the same install/build/start/url +
@@ -78,7 +79,7 @@ function misplacedFieldFailure(source, raw) {
     if (source !== "clone" && source !== "local-tree" && raw.state !== undefined) {
         return invalid("`subject.state` applies only to clone subjects or local-tree subjects (the lab seeds the state it serves).");
     }
-    // repos/clone are clone-ONLY (a fresh-clone subject's git inputs). local-tree packs the
+    // repos/clone are clone-only (a fresh-clone subject's git inputs). local-tree packs the
     // resolution cwd itself, so it has no repo slug to clone and gets its own precise reasons
     // rather than falling through to the generic clone-only message below.
     if (source === "local-tree" && raw.repos !== undefined) {
@@ -88,19 +89,19 @@ function misplacedFieldFailure(source, raw) {
         return invalid("`subject.clone` does not apply to local-tree subjects. Declare `subject.localTree` instead (keep/exclude/maxArchiveBytes).");
     }
     // Rejected, never silently dropped, on app-url/local-app/this-repo/terminal-product subjects
-    // too (invariant 6: a field that cannot act on this route is an honest parse error).
+    // too: a field that cannot act on this route is a parse error.
     if (source !== "clone" && raw.repos !== undefined) {
         return invalid("`subject.repos` applies only to clone subjects (the owner/repo slugs to clone).");
     }
     if (source !== "clone" && raw.clone !== undefined) {
         return invalid("`subject.clone` applies only to clone subjects (clone depth/fanout/keep).");
     }
-    // localTree is local-tree-ONLY (pack/upload knobs for the packed working tree).
+    // localTree is local-tree-only (pack/upload knobs for the packed working tree).
     if (source !== "local-tree" && raw.localTree !== undefined) {
         return invalid("`subject.localTree` applies only to local-tree subjects (keep/exclude/maxArchiveBytes for packing the working tree).");
     }
-    // publicTarget is app-url-ONLY (the external-public shared-world ownership attestation). It is
-    // meaningless without a real public deployment as the plane — reject it elsewhere (invariant 6).
+    // publicTarget is app-url-only (the external-public shared-world ownership attestation). It is
+    // meaningless without a real public deployment as the plane, so reject it elsewhere.
     if (source !== "app-url" && raw.publicTarget !== undefined) {
         return invalid("`subject.publicTarget` applies only to app-url subjects on the external-public shared-world route (the operator's ownership attestation for a real public deployment used directly as the shared plane).");
     }
@@ -124,7 +125,7 @@ function parseCloneSubject(raw, subject) {
 }
 function parseLocalTreeSubject(raw, subject) {
     // A local-tree subject exists to be packed and served; there is no other way to boot it, so
-    // serve is REQUIRED here. Clone subjects get the same requirement from each route's checks in
+    // serve is required here. Clone subjects get the same requirement from each route's checks in
     // parseLabConfig.
     if (raw.serve === undefined) {
         return invalid("`subject.serve` is required when source is local-tree: a local-tree subject exists to be packed and served, so declare install/build/start/url exactly like the clone route.");
@@ -156,11 +157,11 @@ function parseServedApp(raw, subject) {
     if (raw.env !== undefined) {
         const env = strList(raw.env);
         if (!env || env.length === 0) {
-            return invalid("`subject.env` must be a non-empty list of env var NAMES when set.");
+            return invalid("`subject.env` must be a non-empty list of environment variable names when it is set.");
         }
         const badName = env.find((name) => !ENV_NAME_PATTERN.test(name));
         if (badName) {
-            return invalid(`subject.env entries must be env var NAMES like DATABASE_URL (got "${badName}"); values come from the caller's environment and are never persisted.`);
+            return invalid(`subject.env entries must be environment variable names like DATABASE_URL, and "${badName}" is not one. Their values come from your environment and are never stored.`);
         }
         subject.env = env;
     }
@@ -191,11 +192,11 @@ function parseAppSubject(raw, source, subject) {
     }
     // app-url: shape-only here; the loopback-vs-public-target gate is applied in the
     // cross-validation block below, where policies.allowPublicTargets is available.
-    // local-app: an in-process local dev server — ALWAYS loopback (no public-target option),
+    // local-app: an in-process local dev server, always loopback (no public-target option),
     // so the loopback wall is enforced right here at parse.
     if (source === "local-app") {
         if (!isLoopbackUrl(appUrl)) {
-            return invalid("`subject.appUrl` must be a loopback URL (127.0.0.1/localhost) on a local-app subject — it drives an already-running LOCAL dev server in-process; public targets are not supported on this route.");
+            return invalid("`subject.appUrl` must be a loopback URL (127.0.0.1 or localhost) on a local-app subject: humanish drives your running dev server from this process, so it cannot reach a public URL.");
         }
     }
     else if (!isHttpUrl(appUrl)) {
@@ -203,7 +204,7 @@ function parseAppSubject(raw, source, subject) {
     }
     subject.appUrl = appUrl;
     // publicTarget (external-public shared-world ownership attestation) is app-url-only. Shape it
-    // here; its REQUIRED-on-that-route semantics live in externalPublicSharedWorldValidationReason.
+    // here; its required-on-that-route semantics live in externalPublicSharedWorldValidationReason.
     if (source === "app-url" && raw.publicTarget !== undefined) {
         const publicTargetResult = parsePublicTarget(raw.publicTarget);
         if (!publicTargetResult.ok) {
@@ -225,22 +226,22 @@ function parseProductSubject(raw, subject) {
 // "example-operator/lobby-trivia" or a bare org name). Slash allowed for the owner/repo convention.
 export const PUBLIC_TARGET_OWNER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_./-]*$/;
 /** Parse the external-public shared-world ownership attestation ({ owner, authorized: true }). The
- *  harness cannot verify ownership — this is author-trust, surfaced honestly in the evidence class. */
+ *  harness cannot verify ownership: this is author-trust, and the evidence class says so. */
 function parsePublicTarget(raw) {
     if (!isRecord(raw)) {
-        return invalid("`subject.publicTarget` must be an object ({ owner, authorized: true }) — the operator's ownership attestation for the external-public shared plane.");
+        return invalid("`subject.publicTarget` must be an object, `{ owner, authorized: true }`, declaring that you own or operate the public deployment.");
     }
     const owner = str(raw.owner);
     if (!owner || !PUBLIC_TARGET_OWNER_PATTERN.test(owner)) {
         return invalid("`subject.publicTarget.owner` must be a public-safe operator/repo label (e.g. owner/repo); it is recorded in evidence, so it must carry no secret.");
     }
     if (raw.authorized !== true) {
-        return invalid("`subject.publicTarget.authorized` must be true — you must attest you own/operate the public deployment used as the shared plane (author-trust; the harness cannot verify ownership).");
+        return invalid("`subject.publicTarget.authorized` must be true to declare that you own or operate the public deployment. humanish cannot check ownership, so the study states it.");
     }
     return { ok: true, value: { owner, authorized: true } };
 }
 // The product name interpolates into evidence labels and the composed prompt; the public-safe
-// token shape is the same load-bearing constraint as a lab id.
+// token shape is the same strict constraint as a lab id.
 const PRODUCT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 function parseProduct(raw) {
     if (!isRecord(raw)) {
@@ -262,7 +263,7 @@ function parseProduct(raw) {
         if (upload.startsWith("/") ||
             /^[A-Za-z]:/.test(upload) ||
             upload.split(/[\\/]/).includes("..")) {
-            return invalid("`subject.product.upload` must stay inside the project — no absolute paths and no `..` segments.");
+            return invalid("`subject.product.upload` must stay inside the project: use a relative path with no `..` segments.");
         }
     }
     const install = str(raw.install);
@@ -288,7 +289,7 @@ function parseProduct(raw) {
         },
     };
 }
-// Public-safe stance: a computer-use actor's ENTRY URL is always an app the lab owner runs on
+// Public-safe stance: a computer-use actor's entry URL is always an app the lab owner runs on
 // loopback (inside the sandbox), never an arbitrary public site. (The constraint binds the
 // entry point; a navigation watchdog for mid-session escapes is a later slice.) Exported so
 // the engine re-enforces the same boundary on configs that arrive through the library API.
@@ -329,7 +330,7 @@ function parseServe(raw) {
     }
     const url = str(raw.url);
     if (!url || !isLoopbackUrl(url)) {
-        return invalid("`subject.serve.url` must be a loopback http(s) URL (127.0.0.1 or localhost) — the app is served INSIDE the sandbox.");
+        return invalid("`subject.serve.url` must be a loopback http(s) URL (127.0.0.1 or localhost), because the app runs inside the sandbox.");
     }
     const serve = { start, url };
     const install = str(raw.install);
@@ -367,7 +368,7 @@ function parseClone(raw) {
 /**
  * Structural parse of `subject.localTree`, mirroring parseClone. Unlike parseClone (which
  * silently drops an out-of-range depth/fanout), an invalid exclude/maxArchiveBytes value is
- * REJECTED, never silently dropped: a caller who typed an empty exclude entry or a non-positive
+ * rejected, never silently dropped: a caller who typed an empty exclude entry or a non-positive
  * maxArchiveBytes almost certainly meant something, and the archive-size cap is a safety knob,
  * not a cosmetic default.
  */

package/dist/lab/parse/values.d.ts

@@ -2,7 +2,6 @@ import type { LabConfigParseFailure } from "../types.js";
 export declare const REPO_SLUG_PATTERN: RegExp;
 export declare const ENV_NAME_PATTERN: RegExp;
 export declare function invalid(message: string): LabConfigParseFailure;
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function str(value: unknown): string | undefined;
 export declare function optionalStr(key: string, value: unknown): Record<string, string>;
 export declare function strList(value: unknown): string[] | undefined;
@@ -12,6 +11,6 @@ export declare function strList(value: unknown): string[] | undefined;
  */
 export declare function readPositiveInt(value: string | undefined, fallback: number): number;
 export declare function posInt(value: unknown): number | undefined;
-/** A non-negative finite number (0 allowed — caps default to 0 = no-spend). Accepts a numeric
+/** A non-negative finite number (0 allowed; caps default to 0 = no-spend). Accepts a numeric
  *  string too, since YAML scalars can arrive as strings. */
 export declare function nonNegNumber(value: unknown): number | undefined;

package/dist/lab/parse/values.js

@@ -1,11 +1,8 @@
-// The slug interpolates into an in-sandbox shell command; the strict shape is load-bearing.
+// The slug interpolates into an in-sandbox shell command, so its shape is strict.
 export const REPO_SLUG_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 export const ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
 export function invalid(message) {
-    return { ok: false, error: { code: "HUMANISH_LAB_INVALID", message } };
-}
-export function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+    return { ok: false, error: { code: "HUMANISH_STUDY_INVALID", message } };
 }
 export function str(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
@@ -51,7 +48,7 @@ export function posInt(value) {
     }
     return undefined;
 }
-/** A non-negative finite number (0 allowed — caps default to 0 = no-spend). Accepts a numeric
+/** A non-negative finite number (0 allowed; caps default to 0 = no-spend). Accepts a numeric
  *  string too, since YAML scalars can arrive as strings. */
 export function nonNegNumber(value) {
     if (typeof value === "number" && Number.isFinite(value) && value >= 0) {