humanish 0.0.1 → 0.15.1

package/dist/lab-config.d.ts

@@ -0,0 +1,583 @@
+import type { StopWhen } from "./stop-conditions.js";
+export declare const LAB_CONFIG_SCHEMA = "humanish.lab.v2";
+/**
+ * Where the run acts: the host repo, a fresh clone, a running app a browser actor drives
+ * (`app-url`), an already-running LOCAL dev server driven IN-PROCESS via a custom
+ * CuaExecutor with NO clone and NO E2B desktop (`local-app`), or the operator's own local
+ * working tree packed and provisioned in-sandbox in place of a clone (`local-tree`).
+ * `local-app` routes to the cua backend and is library-assisted: a caller supplies
+ * `cuaHooks.buildExecutor` + `buildProvider` (no built-in driver exists yet), and the engine
+ * fails closed (HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR) when run without them: a structured
+ * error, never a desktop attempt. See docs/architecture/state-driven-executor.md.
+ */
+export type LabSubjectSource = "this-repo" | "clone" | "app-url" | "local-app" | "terminal-product" | "local-tree";
+/**
+ * How a subject's WORLD relates across actor lanes. `per-lane-worlds` (the default; absent ==
+ * this) is the only fan-out topology the computer-use route ships — N lanes, N independent
+ * worlds, isolation + per-lane attribution. `shared-world` (#164) is the DECLARED override: ONE
+ * provisioned, mutable service plane that N role SEATS take turns against IN DECLARED ORDER, so
+ * their actions interact through shared state. Consumed ONLY on the shared-world route (clone ×
+ * e2b-desktop × a computer-use actor); inert/warned everywhere else (invariant 6).
+ */
+export type LabSubjectTopology = "per-lane-worlds" | "shared-world";
+export interface LabSubjectClone {
+    /** git clone depth; 1 (shallow) by default. Consumed on the computer-use clone route. */
+    depth?: number;
+    /** how many independent clone lanes to fan out (one sandbox/desktop each). */
+    fanout?: number;
+    /** keep the disposable clone for debugging instead of discarding. */
+    keep?: boolean;
+}
+/**
+ * `local-tree`: how the operator's own working tree is packed and provisioned in-sandbox in
+ * place of a clone. Internal shape (not re-exported from src/index.ts, same as LabSubjectClone).
+ */
+export interface LabSubjectLocalTree {
+    /** extra archive excludes (path prefixes/basenames) added on top of the always-on denylist. */
+    exclude?: string[];
+    /** keep the disposable sandbox on failure for debugging (mirrors subject.clone.keep). */
+    keep?: boolean;
+    /** upload size cap override in bytes; default 256 MiB. */
+    maxArchiveBytes?: number;
+}
+/** How a cloned subject is installed/built/started inside the sandbox (computer-use route). */
+export interface LabSubjectServe {
+    /** Optional bounded install step (e.g. "pnpm install --frozen-lockfile"). */
+    install?: string;
+    /** Optional bounded build step. */
+    build?: string;
+    /** Required long-lived start command — launched detached; the sandbox lifecycle owns it. */
+    start: string;
+    /** Loopback entry URL: the readiness-probe target and the URL the actor drives. The lab
+     *  serves the clone INSIDE the sandbox, so this is always loopback (not subject to
+     *  allowPublicTargets — that governs app-url subjects, i.e. external deployments). */
+    url: string;
+    /** Budget for the served app to answer the readiness probe. Default 180000. */
+    readyTimeoutMs?: number;
+    /** Override the install-step timeout (default 600000). Monorepos can exceed it. */
+    installTimeoutMs?: number;
+    /** Override the build-step timeout (default 600000). Large builds can exceed it. */
+    buildTimeoutMs?: number;
+}
+/** When a state step runs, relative to the serve sequence (clone subjects, computer-use route). */
+export type LabStateStepWhen = "before-build" | "before-start" | "after-ready";
+export interface LabSubjectStateStep {
+    /**
+     * [a-z0-9-] step label (must start alphanumeric), <=40 chars, unique across steps; becomes
+     * the detached-step name `subject-state-<name>` (interpolates into in-sandbox file paths —
+     * the shape is load-bearing, validated at parse AND re-enforced in the engine).
+     */
+    name: string;
+    /**
+     * Author-trusted shell command (same trust class as serve.install/build/start — the
+     * "serve commands are author-trusted" corollary). Runs detached in the subject directory
+     * with an atomic status file, kill-on-timeout, and a capped log tail. Persisted in
+     * evidence as a sha256-16 DIGEST only, never as text.
+     */
+    command: string;
+    /**
+     * Phase: before-build (after install — for builds that read the DB, e.g. SSG),
+     * before-start (after build, before the server launches — migrations, SQL/file fixtures,
+     * an in-sandbox `service postgresql start`), after-ready (after the readiness probe —
+     * fixtures loaded through the RUNNING app's API). Default: before-start.
+     */
+    when?: LabStateStepWhen;
+    /** Wall-clock budget per step. Default 300000. */
+    timeoutMs?: number;
+}
+/**
+ * A shared-world state CHECKPOINT: an author-trusted, READ-ONLY, AGGREGATE/DIGEST probe command
+ * (counts, max-timestamps, hashes) run at baseline and after each role's turn. Reuses the
+ * seed-step validation shape (name [a-z0-9-] ≤40, unique; command required). Persisted DIGEST-ONLY
+ * (only sha256-16(scrub+redact(stdout)) ever lands — never the raw value), same lockdown as the
+ * seed surface. Consumed ONLY on the shared-world route (#164); inert/warned elsewhere.
+ */
+export interface LabSubjectStateCheckpoint {
+    /**
+     * [a-z0-9-] probe label (must start alphanumeric), <=40 chars, unique across checkpoints;
+     * names the detached step (`checkpoint-<snapshot>-<name>`) — load-bearing shape, validated at
+     * parse AND re-enforced in the engine.
+     */
+    name: string;
+    /**
+     * Author-trusted READ-ONLY shell command (same trust class as serve/seed — the "serve commands
+     * are author-trusted" corollary). Its stdout is scrubbed + pattern-redacted, then digested
+     * (sha256-16); the raw value never persists.
+     */
+    command: string;
+    /**
+     * Optional extra literal values to scrub from this probe's stdout before digesting (author-known
+     * values that may appear in the probe output, beyond the harness-provisioned env values which are
+     * always scrubbed). Names/values are NEVER persisted — only the digest is.
+     */
+    redact?: string[];
+}
+/** The subject's STATE story (clone subjects): seeded in-sandbox, or declared external. */
+export interface LabSubjectState {
+    /** Ordered seed/migration/fixture steps. Order within a phase is declaration order. */
+    seed?: LabSubjectStateStep[];
+    /**
+     * Env var NAMES whose values point at state the lab does NOT control (e.g. a shared dev
+     * DB). Must be a subset of subject.env (so the declaration is mechanically backed by a
+     * provisioned name, not a vibe). Flips state provenance to "unpinned".
+     */
+    external?: string[];
+    /**
+     * Shared-world state checkpoints (#164): read-only digest probes run at baseline + after each
+     * role's turn to produce the harness-clocked interaction timeline. Consumed ONLY on the
+     * shared-world route; inert/warned elsewhere (invariant 6). Shape-validated everywhere.
+     */
+    checkpoint?: LabSubjectStateCheckpoint[];
+}
+/**
+ * `terminal-product`: the product-under-study a terminal agent must discover and use from PUBLIC
+ * SURFACES ONLY (the terminal-product route's subject). The subject is NOT provisioned/cloned —
+ * the agent drives the declared public surfaces, so provenance is UNPINNED (invariant 5). The
+ * concrete product name + surfaces are operator data; committed fixtures use a NEUTRAL mock name.
+ */
+export interface LabSubjectProduct {
+    /** Public-safe product label (shape-validated like a lab id; interpolates into evidence). */
+    name: string;
+    /**
+     * The product's PUBLIC surfaces — the only world the agent sees. Each must be an http(s) URL
+     * (e.g. a docs page, an llms.txt, a skill manifest). Validated at parse; recorded in evidence.
+     */
+    publicSurfaces: string[];
+}
+export interface LabSubject {
+    source: LabSubjectSource;
+    /**
+     * WORLD topology across actor lanes. Absent == `per-lane-worlds` (the isolation default; every
+     * existing lab is byte-stable). `shared-world` is the declared override (#164): one mutable
+     * service plane, N role seats taking turns. Consumed ONLY on the shared-world route (clone ×
+     * e2b-desktop × a computer-use actor + a roster of ≥2 lanes); inert/warned elsewhere.
+     */
+    topology?: LabSubjectTopology;
+    /**
+     * CONCURRENT shared-world route ONLY (#164 phase 2): the author's REQUIRED attestation that the
+     * subject behind the internet-reachable `getHost` URL is SYNTHETIC seeded data. The concurrent
+     * route exposes the subject on a tokenless public URL for the run's duration, so real/external
+     * data must never sit behind it. This is author-trust + a provenance gate (verify also requires
+     * `subject.state.provenance == "seeded"`), NOT a no-real-data guarantee. Required when
+     * `topology: shared-world` + `execution.concurrency > 1`; inert/warned elsewhere.
+     */
+    exposure?: "synthetic";
+    /** `clone`: one or more owner/repo slugs (public or authorized-private). */
+    repos?: string[];
+    clone?: LabSubjectClone;
+    /**
+     * `app-url`: a loopback http(s) URL the computer-use actor drives (127.0.0.1/localhost
+     * only — driving arbitrary public sites is not allowed). The URL must be reachable from
+     * INSIDE the desktop sandbox; library callers provision it via the prepareDesktop hook.
+     * For a config-only path use `clone` + `serve` — the lab serves the app itself.
+     *
+     * `local-app`: the loopback http(s) URL of an already-running LOCAL dev server the caller's
+     * custom CuaExecutor drives in-process (no sandbox, no public-target option — always
+     * loopback). Passed to `buildExecutor` so the bridge knows where the app lives.
+     */
+    appUrl?: string;
+    /** `clone` (computer-use route): how the cloned app is served in-sandbox. */
+    serve?: LabSubjectServe;
+    /**
+     * Env var NAMES the subject app needs, provisioned into the sandbox from the caller's
+     * environment (--env-file). Names are recorded in evidence; values never are. Consumed
+     * on the computer-use clone route.
+     */
+    env?: string[];
+    /**
+     * `clone` (computer-use route): the subject's state story — seed/migration/fixture steps
+     * executed in-sandbox around the serve sequence, and/or declared external state. Recorded
+     * in the run bundle as structured provenance (invariant 5): seeded with command digests,
+     * UNPINNED for external state, declared-not-run for dry-run/failed provisioning.
+     */
+    state?: LabSubjectState;
+    /**
+     * `terminal-product` (terminal route): the product the terminal agent discovers + uses from
+     * PUBLIC surfaces only. Consumed on the terminal route; rejected on every other source.
+     */
+    product?: LabSubjectProduct;
+    /**
+     * `local-tree` (computer-use route): local-tree packs the lab resolution cwd (the project
+     * directory humanish runs from) instead of cloning a repo. `exclude` adds extra archive excludes
+     * on top of the always-on denylist; `keep` preserves the sandbox on failure for debugging;
+     * `maxArchiveBytes` caps the upload. Consumed on the local-tree route; rejected on every other
+     * source.
+     */
+    localTree?: LabSubjectLocalTree;
+}
+export interface LabActorLaneFocus {
+    id?: string;
+    label?: string;
+    /** Per-lane steer appended to the actor's mission. Consumed on the app-url route. */
+    instruction?: string;
+}
+/**
+ * One differentiated fan-out lane on the computer-use E2B route (per-lane worlds). Each lane
+ * becomes an independent E2B desktop sandbox with its own persona/device/starting-steer. All
+ * fields optional: an omitted persona/device/instruction inherits the actor-level default. `id`
+ * defaults to `lane-01`..`lane-NN` and must be a public-safe token (it names per-lane evidence
+ * paths). Consumed ONLY on the computer-use E2B route (inert/warned elsewhere).
+ */
+export interface LabActorLane {
+    /** Public-safe lane label (interpolates into per-lane evidence paths). Default lane-NN. */
+    id?: string;
+    /**
+     * App-defined actor type label for grouping simulated users ("operator", "viewer",
+     * "maintainer", etc.). This is NOT the execution actor dispatch key (`actors[0].type`);
+     * it is adapter-owned taxonomy for roster/readback.
+     */
+    actorType?: string;
+    /** App-defined surface label for grouping lanes that start from different product areas. */
+    surface?: string;
+    /** App-defined correlation id tying lanes to one shared case/account/work item. */
+    caseGroup?: string;
+    /** Persona id/label threaded into this lane's actor prompt. Default: actors[0].persona. */
+    persona?: string;
+    /** Named device preset this lane renders at. XOR raw execution.desktop.resolution. */
+    device?: string;
+    /** Per-lane steer appended to this lane's mission (the roster's per-lane focus). */
+    instruction?: string;
+    /**
+     * Deterministic lane completion guard. When set, this lane stops as soon as the runtime
+     * observation matches any declared rule; actor-level stopWhen is used as the default.
+     */
+    stopWhen?: StopWhen;
+    /**
+     * App-url computer-use ONLY: absolute browser URL this lane opens instead of `subject.appUrl`.
+     * This is the generic setup-produced-target handoff for crawler/swarm labs: product adapters may
+     * start any topology they need, then hand Humanish explicit lane targets. Public/non-loopback
+     * targets still require `policies.allowPublicTargets: true`. Inert/rejected on clone, local-app,
+     * shared-world, scripted-browser, and terminal routes.
+     */
+    target?: string;
+    /**
+     * Shared-world ONLY (#164): this role's per-seat loopback entry route, resolved against
+     * `subject.serve.url` and REQUIRED to be same-origin (loopback) with it — the seat opens
+     * `serve.url + entry`. Validated at parse AND re-enforced in the engine. Inert/warned on every
+     * non-shared-world route (the per-lane-worlds fan-out roster has no per-lane entry).
+     */
+    entry?: string;
+}
+/**
+ * Compact authoring sugar for repeated lane groups. The parser expands each group into concrete
+ * `lanes[]` with deterministic ids (`<group.id>-01`, `<group.id>-02`, ...). The runtime never
+ * consumes this shape directly; it always sees ordinary `LabActorLane` entries.
+ */
+export interface LabActorRosterGroup extends Omit<LabActorLane, "id"> {
+    /** Public-safe group id; prefixes generated lane ids. */
+    id: string;
+    /** Number of lanes to generate for this group. */
+    count: number;
+}
+export interface LabActor {
+    /**
+     * The actor label. On app-url subjects this is a REAL dispatch key: it must resolve to a
+     * registered computer-use actor (e.g. openai-computer-use, paired with e2b-desktop) or a
+     * registered scripted-browser actor (e.g. scripted-browser, local execution), and that
+     * descriptor runs the session. On other routes it remains a free-form label (built-ins use
+     * descriptive labels like synthetic-persona, humanish-setup, codex-app-server).
+     */
+    type: string;
+    /** Lane count — route-specific (see HONEST SCOPE header): synthetic simCount; scripted
+     *  surface roster {1 = desktop, 2 = desktop + mobile, default 1}; computer-use E2B route the
+     *  HOMOGENEOUS fan-out lane count (cap 16). XOR `lanes`. */
+    count?: number;
+    /** Computer-use E2B route: a DIFFERENTIATED fan-out roster (per-lane worlds). XOR `count`,
+     *  `roster`, and `laneFocus`. Cap 16 lanes. Consumed only on the cua E2B route
+     *  (inert/warned elsewhere). */
+    lanes?: LabActorLane[];
+    /** Persona id/label threaded into the actor prompt. Consumed on the app-url route. */
+    persona?: string;
+    /** Consumed on the app-url route (laneFocus.instruction appended to the mission). XOR `lanes`. */
+    laneFocus?: LabActorLaneFocus;
+    /** Free-form mission threaded into the actor prompt. Consumed on the app-url route. */
+    mission?: string;
+    /** Provider model override. Consumed on the app-url route. */
+    model?: string;
+    /**
+     * Deterministic completion guard used as the default for CUA lanes. Lane-level stopWhen
+     * overrides this value.
+     */
+    stopWhen?: StopWhen;
+}
+export type LabExecutionTarget = "local" | "e2b-desktop" | "e2b-terminal";
+/** Terminal transport: the captured non-interactive exec stream (stdin disabled). NOT an
+ *  interactive duplex PTY — labeling captured exec output "pty" would be a claim/mechanism
+ *  mismatch (invariant 6 + the goal packet's PTY ruling), so this lane uses "exec-stream". */
+export type LabTerminalTransport = "exec-stream";
+/** Whether operator stdin reaches the in-sandbox agent. Disabled by default (the run is
+ *  autonomous + comparable to an unassisted baseline). "planned" reserves the interventions-ledger
+ *  path SLICE 2 builds; "sent" (assisted input) is NOT shippable until the ledger + comparability
+ *  flag + verify check exist (the safety contract forbids an assisted run masquerading as green). */
+export type LabTerminalStdin = "disabled" | "planned" | "sent";
+export interface LabExecutionTerminal {
+    /** Transport label. Default (and only honest value this slice) is "exec-stream". */
+    transport?: LabTerminalTransport;
+    /** Operator stdin posture. Default "disabled". */
+    stdin?: LabTerminalStdin;
+}
+/**
+ * The runtime-auth channel for the in-sandbox agent (terminal route). "openai-env" declares that
+ * OPENAI_API_KEY/CODEX_API_KEY is the runtime key — to be injected ONLY into the command-scoped
+ * `codex` invocation (keyPlacement "in-sandbox-command-scoped"), never sandbox-global. DECLARED
+ * this slice (recorded as names-only evidence); the engine injection lands in SLICE 2.
+ */
+export type LabRuntimeAuth = "openai-env";
+export type LabDesktopBrowser = "default" | "chrome" | "chromium" | "firefox";
+export interface LabExecutionDesktop {
+    /**
+     * Named device preset (mobile / small-mobile / narrow-mobile / tablet / desktop / wide) the
+     * run renders at. Consumed on the computer-use route; default `desktop` (1440x950). On that
+     * route only width/height physically render (the X screen is sized to the preset, so
+     * width-based responsive CSS fires) — touch/DPR/UA are sim-parity prompt signals, not rendered.
+     */
+    device?: string;
+    /** Raw desktop resolution [width, height] — an escape hatch that overrides `device`. */
+    resolution?: [number, number];
+    /**
+     * Browser family to launch for hosted desktop actor lanes. Absent/default preserves the
+     * historical desktop opener behavior. A concrete value means "launch this browser or fail"
+     * instead of silently accepting the template's default URL opener.
+     */
+    browser?: LabDesktopBrowser;
+    /** Sandbox server-side timeout. Consumed on the app-url route. */
+    sandboxTimeoutMs?: number;
+    /**
+     * Custom E2B desktop TEMPLATE (image) the run launches on — a non-empty template NAME or ID —
+     * instead of the stock `desktop` template. Lets a subject that needs runtimes the stock image
+     * lacks (e.g. node/bun/a local Postgres baked into an adopter-maintained image) run as-is. Any
+     * string is a valid template name/id (there is no allowlist). Consumed ONLY on the
+     * `execution.target: e2b-desktop` computer-use routes (the cua/shared-world/concurrent backends
+     * that call `Sandbox.create`); inert/warned on every route that creates no desktop. Threaded to
+     * `Sandbox.create(template, opts)`; absent leaves the byte-stable `Sandbox.create(opts)` default.
+     * A template name is public-safe (not a secret) and is recorded in the run bundle.
+     */
+    template?: string;
+    /** Use the Codex app-server client mode for headed desktop actor surfaces. Consumed (meta). */
+    codexAppServer?: boolean;
+}
+export interface LabExecution {
+    target?: LabExecutionTarget;
+    /** Actor session wall-clock budget. Consumed on the app-url route. */
+    timeoutMs?: number;
+    /** FORWARD-DECLARED. */
+    completionTimeoutMs?: number;
+    /** FORWARD-DECLARED. */
+    concurrency?: number;
+    desktop?: LabExecutionDesktop;
+    /** `terminal-product` route: the terminal transport + stdin posture. Consumed on that route. */
+    terminal?: LabExecutionTerminal;
+    /** `terminal-product` route: the in-sandbox agent's runtime-auth channel. Consumed (names-only
+     *  evidence this slice; command-scoped injection in SLICE 2). Inert on other routes. */
+    runtimeAuth?: LabRuntimeAuth;
+}
+export type LabScenarioMode = "dry-run" | "live";
+/**
+ * The blast-radius budget for a route that places a live key inside the sandbox (terminal route).
+ * Per the safety contract, the live key is never exercised without a fail-closed cap in force.
+ * All values are non-negative numbers (0 is the no-spend default). DECLARED + recorded this slice;
+ * SLICE 2 folds in a minimal fail-closed cap and SLICE 3 enforces the full ledger.
+ */
+export interface LabScenarioCaps {
+    /** Max USD the run may spend (provider + product). 0 = no-spend. */
+    maxUsd?: number;
+    /** Max billable product jobs the agent may trigger. 0 = none. */
+    maxJobs?: number;
+    /** Max wall-clock minutes for the agent session. */
+    maxMinutes?: number;
+}
+export interface LabScenario {
+    /** Reference a committed scenario by id (humanish/scenarios/<ref>.yaml) or path. CONSUMED
+     *  (and REQUIRED) on the scripted-browser route; FORWARD-DECLARED elsewhere. */
+    ref?: string;
+    /** Or inline the scenario body. FORWARD-DECLARED (PR #2). */
+    inline?: Record<string, unknown>;
+    /** dry-run = contract evidence (no provider spend); live = real run. Consumed. */
+    mode?: LabScenarioMode;
+    /** Spend/job/time caps. Consumed (recorded in the bundle) on the terminal-product route;
+     *  inert (warned) elsewhere. */
+    caps?: LabScenarioCaps;
+}
+export interface LabPolicies {
+    /**
+     * Redact target repo labels in durable artifacts. Consumed on the meta route and on the
+     * computer-use clone route (provenance), where it DEFAULTS to true when the clone
+     * authenticates via GITHUB_TOKEN (a token-bearing clone is treated as private until
+     * declared otherwise).
+     */
+    redactRepos?: boolean;
+    /**
+     * Blur+downscale persisted screenshots on the computer-use route. Default FALSE — the common
+     * case is watching a sim of your OWN app locally (gitignored .humanish), where full fidelity is
+     * the deliverable. Set true for unowned subjects or bundles meant to be shared as-is. The
+     * provider always sees raw frames; this only governs what is persisted. Raw bundles stay
+     * local (gitignored, commit-scan-guarded); a redact-on-export step for them is planned.
+     */
+    redactScreenshots?: boolean;
+    /**
+     * Allow an app-url subject to point at a non-loopback (public/preview/staging) URL the lab
+     * owner declares. Default FALSE (loopback-only). The invariant is "the actor drives a target
+     * the owner declared" — setting this IS that declaration (e.g. a Vercel preview of your app).
+     */
+    allowPublicTargets?: boolean;
+    /**
+     * Terminal-product credential-boundary policies — all DEFAULT FALSE (deny-by-default). They are
+     * DECLARED + recorded this slice; the engine ENFORCES them by construction (what the sandbox is
+     * and is not given) + verifier checks in SLICE 2. Setting any to true is an affirmative,
+     * recorded declaration that widens the agent's blast radius.
+     */
+    /** Allow the in-sandbox agent to clone/inspect a private/downstream repo. Default FALSE — the
+     *  agent works from PUBLIC surfaces only (safety contract item 3). */
+    allowPrivateRepoAccess?: boolean;
+    /** Allow media/creative-provider keys into the sandbox. Default FALSE (only the runtime LLM key
+     *  enters, command-scoped — safety contract item 4). */
+    allowProviderCredentials?: boolean;
+    /** Allow payment-provider keys into the sandbox. Default FALSE. */
+    allowPaymentCredentials?: boolean;
+    /** Allow GitHub write tokens (mutating operations) into the sandbox. Default FALSE. */
+    allowGitHubMutation?: boolean;
+}
+export interface LabReview {
+    /** FORWARD-DECLARED (PR #2). */
+    scoring?: string;
+    /** FORWARD-DECLARED (PR #2). */
+    milestones?: string;
+    /** FORWARD-DECLARED (PR #2). */
+    vocabulary?: string;
+}
+export interface LabDefaults {
+    open?: boolean;
+}
+export interface LabConfig {
+    schema: typeof LAB_CONFIG_SCHEMA;
+    id: string;
+    title?: string;
+    description?: string;
+    subject: LabSubject;
+    actors: LabActor[];
+    execution?: LabExecution;
+    /** FORWARD-DECLARED (PR #2). */
+    personas?: Record<string, unknown>[];
+    scenario?: LabScenario;
+    policies?: LabPolicies;
+    review?: LabReview;
+    defaults?: LabDefaults;
+}
+export interface LabConfigParseSuccess {
+    ok: true;
+    config: LabConfig;
+    warnings: string[];
+}
+export interface LabConfigParseFailure {
+    ok: false;
+    error: {
+        code: "HUMANISH_LAB_INVALID";
+        message: string;
+    };
+}
+export type LabConfigParseResult = LabConfigParseSuccess | LabConfigParseFailure;
+/**
+ * Validate a parsed YAML object into a LabConfig. Pure: the caller owns file IO. Structural
+ * validation only. Fields the engine does not yet consume are accepted but reported in
+ * `warnings` so `lab inspect` never silently swallows a setting that does nothing.
+ */
+export declare function parseLabConfig(raw: unknown): LabConfigParseResult;
+export declare const MAX_CUA_LANES = 16;
+/** True when `type` resolves to a registered terminal actor (the "terminal" lane). Exported so
+ *  the engine + tests can resolve the dispatch the same way the parser does. */
+export declare function actorResolvesToTerminal(type: string | undefined): boolean;
+/**
+ * True when this config routes to the computer-use backend: an app-url subject whose first
+ * actor resolves to a registered computer-use actor, or a clone subject on a hosted desktop
+ * whose first actor does. Single source of truth — selectLabBackend and the warning logic
+ * both use it. (The app-url branch used to be unconditionally true; it narrowed when the
+ * scripted-browser lane arrived. Behavior-preserving for every parse-valid config —
+ * selectLabBackend keeps a bare app-url fallback to the cua backend so library-API configs
+ * with unknown actors still hit its fail-closed ACTOR_UNSUPPORTED.)
+ */
+/**
+ * The declared fan-out lane count on the computer-use route: a `lanes[]` roster's length, else
+ * a homogeneous `count`, else 1. The single source of truth shared by the parser, the engine,
+ * and the pre-flight plan so the lane count is computed ONE way everywhere.
+ */
+export declare function cuaLaneCount(config: LabConfig): number;
+/**
+ * Cross-validate the computer-use fan-out declaration (per-lane worlds). Returns the failure
+ * message, or null when valid. Enforced at parse AND re-enforced in the engine (runCuaActorLab
+ * is itself exported npm surface). Structural lane shape (id/device validity, id uniqueness) is
+ * already checked in parseLanes; this is the route-scoped XOR/cap/policy layer.
+ */
+export declare function cuaLaneValidationReason(config: LabConfig): string | null;
+/**
+ * Engine-level path-token validation for configs supplied directly through the
+ * public TypeScript/JavaScript API instead of parseLabConfig.
+ */
+export declare function laneRosterStructuralValidationReason(config: LabConfig): string | null;
+/**
+ * Cross-validate a `topology: shared-world` declaration (#164). Returns the failure message, or
+ * null when valid. Enforced at parse AND re-enforced in the engine (runSharedWorldLab is exported
+ * npm surface). The shared-world override REQUIRES: a clone or local-tree source + e2b-desktop
+ * target + a computer-use actor + a `subject.serve` block + an `actors[0].lanes` roster of ≥2 roles (the
+ * roster IS the role roster — no parallel roles[] field), and every role `entry` must resolve
+ * same-origin (loopback) with serve.url. Fail-closed: a half-declared shared-world is rejected,
+ * never silently downgraded.
+ */
+export declare function sharedWorldValidationReason(config: LabConfig): string | null;
+export declare function routesToComputerUse(config: LabConfig): boolean;
+/**
+ * True when this config routes to the SHARED-WORLD backend (#164): a clone or local-tree subject
+ * on a hosted desktop whose first actor resolves to a computer-use actor AND that declares the
+ * `shared-world` topology. Mirror of routesToComputerUse; the single source of truth shared by
+ * selectLabBackend (which checks it BEFORE the cua route) and the warning logic. The same
+ * clone/local-tree × e2b-desktop × computer-use composition WITHOUT `topology: shared-world` stays per-lane-worlds
+ * (the cua route) — the topology declaration is the override switch.
+ */
+export declare function routesToSharedWorld(config: LabConfig): boolean;
+/**
+ * True when this config routes to the CONCURRENT shared-world backend (#164 phase 2): a shared-world
+ * config with `execution.concurrency > 1` (N actor seats driving ONE getHost-exposed plane AT ONCE).
+ * `concurrency` absent or 1 stays the sequential PoC (`routesToSharedWorld` → the sequential
+ * backend). selectLabBackend checks this BEFORE routesToSharedWorld.
+ */
+export declare function routesToConcurrentSharedWorld(config: LabConfig): boolean;
+/**
+ * Cross-validate a CONCURRENT shared-world declaration (#164 phase 2). Returns the failure message,
+ * or null when valid. Includes the base shared-world checks PLUS the concurrent extras: a synthetic
+ * subject attestation (FIX-3), a 0.0.0.0 serve bind (FIX-4 — getHost only routes to a port bound on
+ * all interfaces), and no `subject.clone.keep`/`subject.localTree.keep` (FIX-9 - either would
+ * orphan actor sandboxes). Enforced at parse AND re-enforced in the engine (runConcurrentSharedWorld
+ * is exported npm surface).
+ */
+export declare function concurrentSharedWorldValidationReason(config: LabConfig): string | null;
+/**
+ * Resolve a shared-world seat's entry URL from `serve.url` + a role's `entry` (relative path or
+ * same-origin absolute URL). Returns null when the combination is not a same-origin loopback URL
+ * (the load-bearing public-safety boundary — a seat only ever drives the in-sandbox app).
+ */
+export declare function resolveSeatUrl(serveUrl: string, entry: string | undefined): string | null;
+/**
+ * True when this config routes to the scripted-browser backend: an app-url subject whose
+ * first actor resolves to a registered scripted-browser actor (execution.target local or
+ * absent — the parse layer enforces that pairing). Mirror of routesToComputerUse; the single
+ * source of truth for selectLabBackend and the warning logic.
+ */
+export declare function routesToScriptedBrowser(config: LabConfig): boolean;
+export declare function routesToLocalScriptedBrowser(config: LabConfig): boolean;
+export declare function routesToProvisionedScriptedBrowser(config: LabConfig): boolean;
+/**
+ * True when this config routes to the terminal-product backend: a terminal-product subject whose
+ * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent —
+ * the parse layer enforces that pairing). Mirror of routesToComputerUse/routesToScriptedBrowser;
+ * the single source of truth for selectLabBackend and the warning logic.
+ */
+export declare function routesToTerminalProduct(config: LabConfig): boolean;
+export declare function isLoopbackUrl(value: string): boolean;
+/** A well-formed http(s) URL (any host). Shape gate before the loopback/public-target policy. */
+export declare function isHttpUrl(value: string): boolean;
+/**
+ * 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;