humanish 0.104.3 → 0.106.0

package/dist/lab/parse/comms.js

@@ -0,0 +1,246 @@
+import { invalid, isRecord, posInt, str } from "./values.js";
+// Fail-loud (never silently swallow a comms setting): a malformed `comms` block returns a parse
+// failure rather than being dropped.
+export function parseComms(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (!isRecord(raw))
+        return invalid("`comms` must be a mapping.");
+    const comms = {};
+    if (raw.email !== undefined) {
+        const email = parseCommsEmail(raw.email);
+        if (!email.ok)
+            return email;
+        comms.email = email.value;
+    }
+    return { ok: true, value: Object.keys(comms).length > 0 ? comms : undefined };
+}
+function parseCommsEmail(raw) {
+    if (!isRecord(raw))
+        return invalid("`comms.email` must be a mapping.");
+    if (raw.connection !== undefined)
+        return parseEmailConnection(raw);
+    const unknown = Object.keys(raw).filter((key) => !["kind", "injectEnv", "port", "smtp", "linkOrigin", "recipients", "external"].includes(key));
+    if (unknown.length)
+        return invalid("Unknown email capture setting. Real inboxes select a saved `comms.email.connection`.");
+    if (raw.kind === "real") {
+        return invalid("Real inboxes require `comms.email.connection` naming a saved connection; omit kind.");
+    }
+    if (raw.kind !== undefined && raw.kind !== "fake") {
+        return invalid("`comms.email.kind` must be `fake`.");
+    }
+    // external ingress (#328): the ADOPTER runs the catch, so there is no subject env for humanish to
+    // inject and `injectEnv` becomes meaningless rather than merely unused — the operator points their
+    // own app at their own catch. Parse it first so the injectEnv requirement can key off it.
+    const external = parseExternalCatch(raw.external);
+    if (!external.ok)
+        return external;
+    const smtp = parseSmtp(raw.smtp);
+    if (!smtp.ok)
+        return smtp;
+    const injectEnv = str(raw.injectEnv);
+    if (injectEnv === undefined && external.value === undefined && smtp.value === undefined) {
+        return invalid("`comms.email` needs a transport: `injectEnv` (the subject-env var set to the catch's HTTP base URL, e.g. RESEND_BASE_URL), or `smtp` (host/port env vars, for an app that sends over SMTP), or `external` on an adopter-hosted plane where you run the catch yourself.");
+    }
+    if (injectEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(injectEnv)) {
+        return invalid(`\`comms.email.injectEnv\` must be a valid env var name (got "${injectEnv}").`);
+    }
+    const email = {
+        kind: "fake",
+        ...(injectEnv === undefined ? {} : { injectEnv }),
+        ...(smtp.value === undefined ? {} : { smtp: smtp.value }),
+        ...(external.value === undefined ? {} : { external: external.value }),
+    };
+    const port = parseCatchPort(raw.port);
+    if (!port.ok)
+        return port;
+    if (port.value !== undefined)
+        email.port = port.value;
+    const recipients = parseRecipients(raw.recipients);
+    if (!recipients.ok)
+        return recipients;
+    if (recipients.value !== undefined)
+        email.recipients = recipients.value;
+    if (raw.linkOrigin !== undefined) {
+        const linkOrigin = str(raw.linkOrigin);
+        if (linkOrigin === undefined)
+            return invalid("`comms.email.linkOrigin` must be a string.");
+        try {
+            new URL(linkOrigin);
+        }
+        catch {
+            return invalid(`\`comms.email.linkOrigin\` must be an absolute URL origin (got "${linkOrigin}").`);
+        }
+        email.linkOrigin = linkOrigin;
+    }
+    return { ok: true, value: email };
+}
+/** A real inbox: a saved connection, with optional link and allowed origins and nothing else. */
+function parseEmailConnection(raw) {
+    const unsupported = Object.keys(raw).filter((key) => !["connection", "linkOrigin", "allowedOrigins"].includes(key));
+    if (unsupported.length)
+        return invalid("An email connection cannot be mixed with capture settings, kind, recipients, or provider options. Use only connection, optional linkOrigin and allowedOrigins.");
+    if (typeof raw.connection !== "string" || !/^[a-z][a-z0-9-]{0,47}$/.test(raw.connection))
+        return invalid("`comms.email.connection` must name a saved connection (lowercase letters, digits and hyphens; at most 48 characters).");
+    const value = { kind: "real", connection: raw.connection };
+    if (raw.linkOrigin !== undefined) {
+        const parsed = exactOrigin(raw.linkOrigin);
+        if (!parsed)
+            return invalid("`comms.email.linkOrigin` must be an exact http(s) origin without credentials, query or fragment.");
+        value.linkOrigin = parsed;
+    }
+    if (raw.allowedOrigins !== undefined) {
+        if (!Array.isArray(raw.allowedOrigins) || raw.allowedOrigins.length > 16)
+            return invalid("`comms.email.allowedOrigins` must contain at most 16 exact http(s) origins.");
+        const origins = raw.allowedOrigins.map(exactOrigin);
+        if (origins.some((entry) => entry === undefined))
+            return invalid("`comms.email.allowedOrigins` accepts exact http(s) origins without credentials, query or fragment.");
+        value.allowedOrigins = [...new Set(origins)];
+    }
+    return { ok: true, value };
+}
+/** The origin of an http(s) URL with no credentials, path, query or fragment, else undefined. */
+function exactOrigin(input) {
+    if (typeof input !== "string")
+        return undefined;
+    try {
+        const url = new URL(input);
+        return ["http:", "https:"].includes(url.protocol) &&
+            !url.username &&
+            !url.password &&
+            url.pathname === "/" &&
+            !url.search &&
+            !url.hash
+            ? url.origin
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `comms.email.external`: the catch the adopter runs, its inbox and the env var holding its token. */
+function parseExternalCatch(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (!isRecord(raw))
+        return invalid("`comms.email.external` must be a mapping.");
+    const catchBaseUrl = str(raw.catchBaseUrl);
+    if (catchBaseUrl === undefined) {
+        return invalid("`comms.email.external.catchBaseUrl` is required — the base URL of the catch YOU run (humanish reads its GET /deliveries and your app POSTs its sends to it).");
+    }
+    for (const [field, value] of [
+        ["catchBaseUrl", catchBaseUrl],
+        ["inboxBaseUrl", str(raw.inboxBaseUrl)],
+    ]) {
+        if (value === undefined)
+            continue;
+        let parsed;
+        try {
+            parsed = new URL(value);
+        }
+        catch {
+            return invalid(`\`comms.email.external.${field}\` must be an absolute http(s) URL (got "${value}").`);
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return invalid(`\`comms.email.external.${field}\` must be an absolute http(s) URL (got "${value}").`);
+        }
+    }
+    const authTokenEnv = str(raw.authTokenEnv);
+    if (authTokenEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(authTokenEnv)) {
+        return invalid(`\`comms.email.external.authTokenEnv\` must be a valid env var NAME (got "${authTokenEnv}"); the value is read at runtime and never persisted.`);
+    }
+    const inboxBaseUrl = str(raw.inboxBaseUrl);
+    return {
+        ok: true,
+        value: {
+            catchBaseUrl,
+            ...(inboxBaseUrl === undefined ? {} : { inboxBaseUrl }),
+            ...(authTokenEnv === undefined ? {} : { authTokenEnv }),
+        },
+    };
+}
+/** SMTP transport, for apps that send mail through SMTP rather than a provider's HTTP API. */
+function parseSmtp(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (!isRecord(raw))
+        return invalid("`comms.email.smtp` must be a mapping.");
+    const envName = (value, field) => {
+        const name = str(value);
+        if (name === undefined)
+            return undefined;
+        return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : `__invalid__${field}`;
+    };
+    const hostEnv = envName(raw.hostEnv, "hostEnv");
+    const portEnv = envName(raw.portEnv, "portEnv");
+    if (hostEnv === undefined || portEnv === undefined) {
+        return invalid("`comms.email.smtp` needs both `hostEnv` and `portEnv` — the subject-env vars your app reads for its SMTP host and port. The harness sets them to its own loopback listener.");
+    }
+    if (hostEnv.startsWith("__invalid__") || portEnv.startsWith("__invalid__")) {
+        return invalid("`comms.email.smtp.hostEnv` and `portEnv` must be valid env var names.");
+    }
+    let smtpPort = 2525;
+    if (raw.port !== undefined) {
+        const parsed = posInt(raw.port);
+        if (parsed === undefined || parsed > 65_535)
+            return invalid("`comms.email.smtp.port` must be a positive integer ≤ 65535.");
+        smtpPort = parsed;
+    }
+    const userEnv = envName(raw.userEnv, "userEnv");
+    const passwordEnv = envName(raw.passwordEnv, "passwordEnv");
+    if (userEnv?.startsWith("__invalid__") || passwordEnv?.startsWith("__invalid__")) {
+        return invalid("`comms.email.smtp.userEnv` and `passwordEnv` must be valid env var names.");
+    }
+    return {
+        ok: true,
+        value: {
+            port: smtpPort,
+            hostEnv,
+            portEnv,
+            ...(userEnv === undefined ? {} : { userEnv }),
+            ...(passwordEnv === undefined ? {} : { passwordEnv }),
+            ...(str(raw.user) === undefined ? {} : { user: str(raw.user) }),
+            ...(str(raw.password) === undefined ? {} : { password: str(raw.password) }),
+        },
+    };
+}
+/** `comms.email.port`: the catch's HTTP port. */
+function parseCatchPort(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    const port = posInt(raw);
+    if (port === undefined)
+        return invalid("`comms.email.port` must be a positive integer.");
+    // Cap at 65534: the catch reserves port+1 for the read-only inbox listener on the shared-world route.
+    if (port > 65_534)
+        return invalid("`comms.email.port` must be ≤ 65534 (the catch reserves port+1 for the inbox listener).");
+    return { ok: true, value: port };
+}
+/** The participant a declared inbox recipient belongs to. The manifest spells it `lane`. */
+export function recipientParticipantId(recipient) {
+    return recipient.lane;
+}
+/** The declared recipients that name an address, in declaration order, by participant id. */
+export function addressedRecipients(email) {
+    return (email.recipients ?? []).flatMap((recipient) => recipient.address === undefined
+        ? []
+        : [{ participantId: recipient.lane, address: recipient.address }]);
+}
+/** `comms.email.recipients`: which lane each captured address belongs to. */
+function parseRecipients(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (!Array.isArray(raw))
+        return invalid("`comms.email.recipients` must be a list.");
+    const recipients = [];
+    for (const entry of raw) {
+        if (!isRecord(entry))
+            return invalid("each `comms.email.recipients` entry must be a mapping.");
+        const lane = str(entry.lane);
+        if (lane === undefined)
+            return invalid("each `comms.email.recipients` entry needs a `lane`.");
+        const address = str(entry.address);
+        recipients.push({ lane, ...(address === undefined ? {} : { address }) });
+    }
+    return { ok: true, value: recipients };
+}

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

@@ -0,0 +1,19 @@
+import type { LabConfigParseFailure, LabDefaults, LabExecution, LabPolicies, LabReview, LabScenario } from "../types.js";
+export declare function parseExecution(raw: unknown): {
+    ok: true;
+    value: LabExecution | undefined;
+} | LabConfigParseFailure;
+export declare function parsePersonas(raw: unknown): Record<string, unknown>[] | undefined;
+export declare function parseScenario(raw: unknown): {
+    ok: true;
+    value: LabScenario | undefined;
+} | LabConfigParseFailure;
+export declare function parsePolicies(raw: unknown): {
+    ok: true;
+    value: LabPolicies | undefined;
+} | LabConfigParseFailure;
+export declare function parseReview(raw: unknown): {
+    ok: true;
+    value: LabReview | undefined;
+} | LabConfigParseFailure;
+export declare function parseDefaults(raw: unknown): LabDefaults | undefined;

package/dist/lab/parse/execution.js

@@ -0,0 +1,356 @@
+import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
+import { DEVICE_PRESET_NAMES, isDevicePresetName } from "../device-presets.js";
+import { isExactRuntimeVersion } from "../../routes/terminal/runtime.js";
+import { invalid, isRecord, nonNegNumber, posInt, str } from "./values.js";
+export function parseExecution(raw) {
+    if (raw === undefined) {
+        return { ok: true, value: undefined };
+    }
+    if (!isRecord(raw)) {
+        return invalid("`execution` must be an object.");
+    }
+    const execution = {};
+    if (raw.target !== undefined) {
+        const target = str(raw.target);
+        if (target !== "local" && target !== "e2b-desktop" && target !== "e2b-terminal") {
+            return invalid("`execution.target` must be local, e2b-desktop, or e2b-terminal.");
+        }
+        execution.target = target;
+    }
+    const timeoutMs = posInt(raw.timeoutMs);
+    if (timeoutMs !== undefined)
+        execution.timeoutMs = timeoutMs;
+    const completionTimeoutMs = posInt(raw.completionTimeoutMs);
+    if (completionTimeoutMs !== undefined)
+        execution.completionTimeoutMs = completionTimeoutMs;
+    const concurrency = posInt(raw.concurrency);
+    if (concurrency !== undefined)
+        execution.concurrency = concurrency;
+    const desktopResult = parseDesktop(raw.desktop);
+    if (!desktopResult.ok) {
+        return desktopResult;
+    }
+    if (desktopResult.value)
+        execution.desktop = desktopResult.value;
+    // Reuse the terminal lane's caps parser (same shape, not a fork) — a malformed budget is a hard
+    // error, never silently dropped (a cap that silently does nothing would be a safety lie).
+    const capsResult = parseCaps(raw.caps);
+    if (!capsResult.ok) {
+        return capsResult;
+    }
+    if (capsResult.value)
+        execution.caps = capsResult.value;
+    const terminalResult = parseTerminal(raw.terminal);
+    if (!terminalResult.ok) {
+        return terminalResult;
+    }
+    if (terminalResult.value)
+        execution.terminal = terminalResult.value;
+    if (raw.runtime !== undefined) {
+        if (!isRecord(raw.runtime) ||
+            Object.keys(raw.runtime).some((key) => key !== "version") ||
+            !isExactRuntimeVersion(raw.runtime.version)) {
+            return invalid("`execution.runtime` must contain only an exact Codex `version` (for example 0.153.3); tags, ranges, URLs, and unknown fields are not accepted.");
+        }
+        execution.runtime = { version: raw.runtime.version };
+    }
+    if (raw.runtimeAuth !== undefined) {
+        const runtimeAuth = str(raw.runtimeAuth);
+        if (runtimeAuth !== "openai-env" && runtimeAuth !== "openai-egress") {
+            return invalid("`execution.runtimeAuth` must be openai-env or openai-egress (the terminal agent's runtime-auth channel).");
+        }
+        execution.runtimeAuth = runtimeAuth;
+    }
+    if (raw.egressAllow !== undefined) {
+        if (!Array.isArray(raw.egressAllow) || raw.egressAllow.some((h) => typeof h !== "string")) {
+            return invalid("`execution.egressAllow` must be an array of host strings.");
+        }
+        const hosts = raw.egressAllow.map((h) => h.trim()).filter((h) => h.length > 0);
+        if (hosts.length === 0) {
+            // An empty list would deny everything including the agent's own model endpoint, which
+            // fails as an unexplained hang rather than a refusal. Say so at parse time.
+            return invalid("`execution.egressAllow` was declared but empty. Declaring it denies all other egress, so " +
+                "an empty list denies everything, including the agent's own provider endpoint. Remove " +
+                "the field for unrestricted egress, or list the hosts the run needs.");
+        }
+        execution.egressAllow = hosts;
+    }
+    return { ok: true, value: Object.keys(execution).length > 0 ? execution : undefined };
+}
+function parseTerminal(raw) {
+    if (raw === undefined) {
+        return { ok: true, value: undefined };
+    }
+    if (!isRecord(raw)) {
+        return invalid("`execution.terminal` must be an object ({ transport?, stdin? }).");
+    }
+    const terminal = {};
+    if (raw.transport !== undefined) {
+        const transport = str(raw.transport);
+        if (transport !== "exec-stream") {
+            // "pty" is deliberately rejected: stdin is disabled, so the capture is a non-interactive
+            // exec stream — an interactive-PTY label would overstate the mechanism (invariant 6 + the
+            // goal packet's PTY ruling). True duplex PTY does not ship.
+            return invalid("`execution.terminal.transport` must be exec-stream — captured non-interactive exec output (stdin disabled) is not an interactive PTY; true duplex PTY transport is not supported.");
+        }
+        terminal.transport = transport;
+    }
+    if (raw.stdin !== undefined) {
+        const stdin = str(raw.stdin);
+        if (stdin !== "disabled" && stdin !== "planned" && stdin !== "sent") {
+            return invalid("`execution.terminal.stdin` must be disabled, planned, or sent.");
+        }
+        if (stdin === "sent") {
+            // Assisted input is forbidden until the interventions ledger + comparability flag + verify
+            // check exist (safety contract item 7) — shipping it now would let an assisted run pose as
+            // autonomous green proof.
+            return invalid("`execution.terminal.stdin: sent` (assisted input) is not supported — the current route cannot capture assisted input with a non-comparable marker. stdin is disabled by default.");
+        }
+        terminal.stdin = stdin;
+    }
+    return { ok: true, value: Object.keys(terminal).length > 0 ? terminal : undefined };
+}
+function parseDesktop(raw) {
+    if (!isRecord(raw)) {
+        return { ok: true, value: undefined };
+    }
+    const desktop = {};
+    if (raw.recording !== undefined) {
+        if (!isRecord(raw.recording) ||
+            typeof raw.recording.audio !== "boolean" ||
+            Object.keys(raw.recording).some((key) => key !== "audio")) {
+            return invalid("`execution.desktop.recording` must be { audio: true|false }; omit it for snapshots only.");
+        }
+        desktop.recording = { audio: raw.recording.audio };
+    }
+    if (raw.device !== undefined) {
+        const device = str(raw.device);
+        if (!device || !isDevicePresetName(device)) {
+            return invalid(`\`execution.desktop.device\` must be one of: ${DEVICE_PRESET_NAMES.join(", ")}.`);
+        }
+        desktop.device = device;
+    }
+    if (raw.resolution !== undefined) {
+        const resolution = raw.resolution;
+        if (!Array.isArray(resolution) ||
+            resolution.length !== 2 ||
+            !resolution.every((value) => Number.isInteger(value) && value > 0)) {
+            return invalid("`execution.desktop.resolution` must be two positive integers [width, height].");
+        }
+        desktop.resolution = [resolution[0], resolution[1]];
+    }
+    const sandboxTimeoutMs = posInt(raw.sandboxTimeoutMs);
+    if (sandboxTimeoutMs !== undefined)
+        desktop.sandboxTimeoutMs = sandboxTimeoutMs;
+    if (raw.browser !== undefined) {
+        const browser = str(raw.browser);
+        if (browser !== "default" &&
+            browser !== "chrome" &&
+            browser !== "chromium" &&
+            browser !== "firefox") {
+            return invalid("`execution.desktop.browser` must be default, chrome, chromium, or firefox.");
+        }
+        desktop.browser = browser;
+    }
+    // A custom E2B desktop template NAME or ID. Trimmed non-empty when present; deliberately NOT
+    // allowlisted (any string is a valid template name/id — over-restricting would reject real
+    // adopter images). An explicitly-set but blank/whitespace value is a mistake, not a template.
+    if (raw.template !== undefined) {
+        const template = str(raw.template);
+        if (template === undefined) {
+            return invalid("`execution.desktop.template` must be a non-empty E2B desktop template NAME or ID when set (any string is accepted; there is no allowlist).");
+        }
+        desktop.template = template;
+    }
+    if (typeof raw.codexAppServer === "boolean")
+        desktop.codexAppServer = raw.codexAppServer;
+    if (raw.fidelity !== undefined) {
+        if (!isRecord(raw.fidelity) || typeof raw.fidelity.mobileEmulation !== "boolean") {
+            return invalid("`execution.desktop.fidelity` must be an object with `mobileEmulation: true|false` (optional deviceScaleFactor, touch, userAgent).");
+        }
+        const fidelity = { mobileEmulation: raw.fidelity.mobileEmulation };
+        if (raw.fidelity.deviceScaleFactor !== undefined) {
+            const scale = raw.fidelity.deviceScaleFactor;
+            if (typeof scale !== "number" || !Number.isFinite(scale) || scale <= 0 || scale > 4) {
+                return invalid("`execution.desktop.fidelity.deviceScaleFactor` must be a number greater than 0 and at most 4.");
+            }
+            fidelity.deviceScaleFactor = scale;
+        }
+        if (raw.fidelity.touch !== undefined) {
+            if (typeof raw.fidelity.touch !== "boolean") {
+                return invalid("`execution.desktop.fidelity.touch` must be true or false.");
+            }
+            fidelity.touch = raw.fidelity.touch;
+        }
+        if (raw.fidelity.userAgent !== undefined) {
+            const userAgent = str(raw.fidelity.userAgent);
+            if (userAgent === undefined) {
+                return invalid("`execution.desktop.fidelity.userAgent` must be a non-empty string when set.");
+            }
+            fidelity.userAgent = userAgent;
+        }
+        desktop.fidelity = fidelity;
+    }
+    if (raw.media !== undefined) {
+        if (!isRecord(raw.media)) {
+            return invalid("`execution.desktop.media` must be an object with `camera` and/or `microphone` ({ source }).");
+        }
+        const media = {};
+        if (raw.media.camera !== undefined) {
+            const source = isRecord(raw.media.camera) ? str(raw.media.camera.source) : undefined;
+            if (source === undefined || (source !== "synthetic" && !source.endsWith(".y4m"))) {
+                return invalid("`execution.desktop.media.camera.source` must be `synthetic` or a path to a `.y4m` file (Chrome's fake video capture reads Y4M).");
+            }
+            media.camera = { source };
+        }
+        if (raw.media.microphone !== undefined) {
+            const source = isRecord(raw.media.microphone) ? str(raw.media.microphone.source) : undefined;
+            if (source !== "speech")
+                return invalid("`execution.desktop.media.microphone.source` must be `speech`. Microphone source-file injection is unsupported.");
+            media.microphone = { source };
+        }
+        if (media.camera === undefined && media.microphone === undefined) {
+            return invalid("`execution.desktop.media` declares neither `camera` nor `microphone`.");
+        }
+        desktop.media = media;
+    }
+    return { ok: true, value: Object.keys(desktop).length > 0 ? desktop : undefined };
+}
+export function parsePersonas(raw) {
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const personas = raw.filter(isRecord);
+    return personas.length > 0 ? personas : undefined;
+}
+export function parseScenario(raw) {
+    if (!isRecord(raw)) {
+        return { ok: true, value: undefined };
+    }
+    const scenario = {};
+    const ref = str(raw.ref);
+    if (ref)
+        scenario.ref = ref;
+    if (isRecord(raw.inline))
+        scenario.inline = raw.inline;
+    const mode = str(raw.mode);
+    if (mode === "dry-run" || mode === "live")
+        scenario.mode = mode;
+    const capsResult = parseCaps(raw.caps);
+    if (!capsResult.ok) {
+        return capsResult;
+    }
+    if (capsResult.value)
+        scenario.caps = capsResult.value;
+    return { ok: true, value: Object.keys(scenario).length > 0 ? scenario : undefined };
+}
+/**
+ * Parse `scenario.caps`. Returns a parse failure on a malformed value rather than silently
+ * dropping a budget declaration (a cap that silently does nothing would be a safety lie —
+ * invariant 6). Each cap must be a non-negative finite number.
+ */
+function parseCaps(raw) {
+    if (raw === undefined) {
+        return { ok: true, value: undefined };
+    }
+    if (!isRecord(raw)) {
+        return invalid("`scenario.caps` must be an object ({ maxUsd?, maxTotalUsd?, maxJobs?, maxMinutes? }).");
+    }
+    const caps = {};
+    for (const key of ["maxUsd", "maxTotalUsd", "maxJobs", "maxMinutes"]) {
+        if (raw[key] === undefined)
+            continue;
+        const value = nonNegNumber(raw[key]);
+        if (value === undefined) {
+            return invalid(`\`scenario.caps.${key}\` must be a non-negative number.`);
+        }
+        caps[key] = value;
+    }
+    return { ok: true, value: Object.keys(caps).length > 0 ? caps : undefined };
+}
+const POLICY_FLAGS = [
+    "redactRepos",
+    "redactScreenshots",
+    "allowPublicTargets",
+    "allowPrivateRepoAccess",
+    "allowProviderCredentials",
+    "allowPaymentCredentials",
+    "allowGitHubMutation",
+];
+export function parsePolicies(raw) {
+    if (!isRecord(raw)) {
+        return { ok: true, value: undefined };
+    }
+    // A quoted "true" would otherwise be dropped and the policy left at its default.
+    for (const flag of POLICY_FLAGS) {
+        if (raw[flag] !== undefined && typeof raw[flag] !== "boolean")
+            return invalid(`\`policies.${flag}\` must be true or false (unquoted).`);
+    }
+    const policies = {};
+    if (typeof raw.redactRepos === "boolean")
+        policies.redactRepos = raw.redactRepos;
+    if (typeof raw.redactScreenshots === "boolean")
+        policies.redactScreenshots = raw.redactScreenshots;
+    if (typeof raw.allowPublicTargets === "boolean")
+        policies.allowPublicTargets = raw.allowPublicTargets;
+    if (raw.mediaPermission === "prompt" || raw.mediaPermission === "granted")
+        policies.mediaPermission = raw.mediaPermission;
+    if (typeof raw.allowPrivateRepoAccess === "boolean")
+        policies.allowPrivateRepoAccess = raw.allowPrivateRepoAccess;
+    if (typeof raw.allowProviderCredentials === "boolean")
+        policies.allowProviderCredentials = raw.allowProviderCredentials;
+    if (typeof raw.allowPaymentCredentials === "boolean")
+        policies.allowPaymentCredentials = raw.allowPaymentCredentials;
+    if (typeof raw.allowGitHubMutation === "boolean")
+        policies.allowGitHubMutation = raw.allowGitHubMutation;
+    return { ok: true, value: Object.keys(policies).length > 0 ? policies : undefined };
+}
+export function parseReview(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (!isRecord(raw))
+        return invalid("`review` must be a mapping.");
+    const analysis = resolveAutomaticAnalysis(raw.analysis);
+    if (!analysis.ok)
+        return invalid(analysis.message);
+    const review = {};
+    if (raw.analysis !== undefined)
+        review.analysis = raw.analysis === false ? false : { ...raw.analysis };
+    const scoring = str(raw.scoring);
+    if (scoring)
+        review.scoring = scoring;
+    const milestones = str(raw.milestones);
+    if (milestones)
+        review.milestones = milestones;
+    const vocabulary = str(raw.vocabulary);
+    if (vocabulary)
+        review.vocabulary = vocabulary;
+    if (raw.scorer !== undefined) {
+        const scorer = parseReviewScorer(raw.scorer);
+        if (!scorer.ok)
+            return scorer;
+        review.scorer = scorer.value;
+    }
+    return { ok: true, value: Object.keys(review).length > 0 ? review : undefined };
+}
+function parseReviewScorer(raw) {
+    if (!isRecord(raw))
+        return invalid("`review.scorer` must be a mapping with a `ref` path (e.g. { ref: scorers/product.mjs }).");
+    const unknownKeys = Object.keys(raw).filter((key) => key !== "ref");
+    if (unknownKeys.length > 0) {
+        return invalid(`Unknown \`review.scorer\` field(s): ${unknownKeys.join(", ")}. review.scorer accepts only \`ref\` (a repo-relative scorer-module path).`);
+    }
+    const ref = str(raw.ref);
+    if (!ref)
+        return invalid("`review.scorer.ref` must be a non-empty repo-relative path to a scorer module (.mjs recommended; .js/.cjs accepted).");
+    return { ok: true, value: { ref } };
+}
+export function parseDefaults(raw) {
+    if (!isRecord(raw)) {
+        return undefined;
+    }
+    const defaults = {};
+    if (typeof raw.open === "boolean")
+        defaults.open = raw.open;
+    return Object.keys(defaults).length > 0 ? defaults : undefined;
+}

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

@@ -0,0 +1,30 @@
+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
+ * `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
+ * value that looks like a credential is refused here rather than committed to a public repo.
+ */
+export declare function parseEnvValues(raw: unknown): {
+    ok: true;
+    value?: Record<string, string>;
+} | LabConfigParseFailure;
+/**
+ * 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.
+ */
+export declare function parseState(raw: unknown): {
+    ok: true;
+    value: LabSubjectState | undefined;
+} | 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 failure message, or null when the declaration is valid. Reads the candidate
+ * defensively — library callers can hand the engine arbitrarily-shaped objects.
+ */
+export declare function subjectStateInvalidReason(state: LabSubjectState, env: readonly string[] | undefined): string | null;