humanish 0.108.0 → 0.109.0

package/dist/run/status.d.ts

@@ -32,6 +32,11 @@ interface RunStatusOutcome {
     };
     /** The run-level estimate, `null` when declared absent (never coerced to 0). */
     estimatedCostUsd?: number | null;
+    /**
+     * `cost.fullyEstimated`: false when some participant or desktop usage has no price, so the
+     * estimate is a lower bound. Absent means unknown, as in every record written before 0.109.
+     */
+    estimatedCostComplete?: boolean;
     durationMs?: number;
 }
 /** The outcome a finalized status record carries, read from the bundle that was just written. */
@@ -43,7 +48,10 @@ export interface RunStatusRecord {
     mode: "dry-run" | "live";
     /** Absent when the run did not come from a study file (a library caller, a bare `run`). */
     study?: RunStudyProvenance;
-    /** `study`'s value, written beside it until 0.109. Read either through studyProvenanceOf. */
+    /**
+     * `study`'s value, as runs saved by 0.108 and earlier wrote it. humanish no longer writes it.
+     * Read either through studyProvenanceOf.
+     */
     lab?: RunStudyProvenance;
     /** The pid that owns the run, for local liveness checks. */
     pid: number;
@@ -79,7 +87,7 @@ export interface RunStatusHandle {
 export interface BeginRunStatusOptions {
     runId: string;
     mode: "dry-run" | "live";
-    lab?: RunStudyProvenance | undefined;
+    study?: RunStudyProvenance | undefined;
 }
 /**
  * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that

package/dist/run/status.js

@@ -1,12 +1,12 @@
 // Run identity and liveness on disk: one small record per run, written by every backend, that says
-// which lab the run belongs to and whether it is still alive. A reader can list and classify runs
+// which study the run belongs to and whether it is still alive. A reader can list and classify runs
 // from it without parsing every bundle, and can tell a live run from an abandoned one.
 //
 // run.json remains the evidence of record. This file is a derived index and liveness record:
 // `verify` never gates on it, nothing here is a claim about what a participant did, and when the
 // two disagree run.json wins and this file can be rebuilt from it.
 //
-// Public safety: it holds only the run id, the lab id/path/origin (the strings `humanish lab list`
+// Public safety: it holds only the run id, the study id/path/origin (the strings `humanish study list`
 // prints), the mode, a local pid and timestamps. It holds no hostname or user/path identity: an
 // operator may share the run directory, so a share-safety gate must have nothing to strip here.
 import { isProvenanceField, studyFields } from "./study-provenance.js";
@@ -42,6 +42,9 @@ export function runStatusOutcome(bundle) {
         ...(bundle.cost?.estimatedTotalUsd === undefined
             ? {}
             : { estimatedCostUsd: bundle.cost.estimatedTotalUsd }),
+        ...(typeof bundle.cost?.fullyEstimated === "boolean"
+            ? { estimatedCostComplete: bundle.cost.fullyEstimated }
+            : {}),
     };
 }
 /**
@@ -57,7 +60,7 @@ export function beginRunStatus(runPaths, options) {
         runId: options.runId,
         state: "running",
         mode: options.mode,
-        ...studyFields(options.lab),
+        ...studyFields(options.study),
         pid: process.pid,
         startedAt,
         updatedAt: startedAt,

package/dist/run/streams.d.ts

@@ -64,7 +64,7 @@ export interface RunDesktopGeometry {
             source: "xdpyinfo";
         };
         /**
-         * The device preset as declared by the lab, present only when it differs from `requested`
+         * The device preset as declared by the study, present only when it differs from `requested`
          * because the rendered width was floored to MIN_DESKTOP_RENDER_WIDTH.
          *
          * Without this, a floored run is indistinguishable from a faithful one: `verified` compares
@@ -96,7 +96,7 @@ export interface RunDesktopGeometry {
         source: "cdp";
     };
     /**
-     * Mobile fidelity beyond viewport size, present only when the lab asked for it. `requested`
+     * Mobile fidelity beyond viewport size, present only when the study asked for it. `requested`
      * is what was applied through CDP; `resolved` is what the page reported about itself afterwards
      * and is the proof, never copied from the request. A run without this block is a
      * responsive-viewport study, whatever its preset is named.

package/dist/run/study-provenance.d.ts

@@ -26,10 +26,12 @@ export declare function studyProvenanceOf(record: {
         source?: unknown;
     };
 }): RunStudyProvenance | undefined;
-/** `study` and `lab` with the same value, as run.json and status.json write them until 0.109. */
+/**
+ * `study`, as run.json and status.json write it. 0.108 wrote `lab` beside it with the same value;
+ * 0.109 stopped, and studyProvenanceOf still reads `lab` from those runs.
+ */
 export declare function studyFields(study: RunStudyProvenance | undefined): {
     study?: RunStudyProvenance;
-    lab?: RunStudyProvenance;
 };
 /**
  * The study id a run names by the `study:<id>` or `lab:<id>` convention on its persona or scenario

package/dist/run/study-provenance.js

@@ -1,5 +1,5 @@
-// Which study a saved run came from. run.json and status.json write it as `study`, and as `lab`
-// with the same value until 0.109 drops `lab`. Every reader goes through
+// Which study a saved run came from. run.json and status.json write it as `study`; runs saved by
+// 0.108 and earlier also carry `lab` with the same value. Every reader goes through
 // studyProvenanceOf, which also reads a run older than both fields by the `study:<id>` or
 // `lab:<id>` convention on its persona and scenario sources.
 const ORIGINS = ["committed", "ignored", "explicit"];
@@ -38,9 +38,12 @@ export function studyProvenanceOf(record) {
     const id = inferLegacyStudyId(record);
     return id === undefined ? undefined : { id };
 }
-/** `study` and `lab` with the same value, as run.json and status.json write them until 0.109. */
+/**
+ * `study`, as run.json and status.json write it. 0.108 wrote `lab` beside it with the same value;
+ * 0.109 stopped, and studyProvenanceOf still reads `lab` from those runs.
+ */
 export function studyFields(study) {
-    return study === undefined ? {} : { study, lab: study };
+    return study === undefined ? {} : { study };
 }
 /**
  * The study id a run names by the `study:<id>` or `lab:<id>` convention on its persona or scenario

package/dist/run/study-result.d.ts

@@ -6,11 +6,6 @@ export interface StudyResultIdentity<R extends string> {
     route: R;
     /** The study's `id`. */
     studyId: string;
-    /**
-     * The study's `id`, the same value as `studyId`.
-     * @deprecated Read `studyId`. The next minor removes it.
-     */
-    labId: string;
 }
 /** The identity fields for a result of route `route` from the study `studyId`. */
 export declare function studyResultIdentity<R extends string>(route: R, studyId: string): StudyResultIdentity<R>;

package/dist/run/study-result.js

@@ -5,5 +5,5 @@
 export const STUDY_RESULT_SCHEMA = "humanish.study-result.v1";
 /** The identity fields for a result of route `route` from the study `studyId`. */
 export function studyResultIdentity(route, studyId) {
-    return { schema: STUDY_RESULT_SCHEMA, route, studyId, labId: studyId };
+    return { schema: STUDY_RESULT_SCHEMA, route, studyId };
 }

package/dist/run-study.d.ts

@@ -0,0 +1,112 @@
+import type { LocalVmInput } from "./routes/computer-use/types.js";
+import { type LateScorer } from "./study/route-inputs.js";
+import { type StudyRoute } from "./study/plan.js";
+import type { StudyDeps } from "./study/study-deps.js";
+import type { RunStudyDriving, RunStudyHomes } from "./study/run-study-homes.js";
+import { type StudyConfig } from "./study/types.js";
+import type { ObserverResult } from "./observer/render.js";
+import { type CuaActorStudyResult } from "./routes/computer-use/types.js";
+import { type PreviewStudyResult } from "./routes/preview.js";
+import { type ScriptedBrowserStudyResult } from "./routes/scripted/types.js";
+import { type ConcurrentSharedWorldStudyResult } from "./routes/shared-world/types.js";
+import { type TerminalProductStudyResult } from "./routes/terminal/types.js";
+import { type RunScorerProvenance } from "./run/bundle.js";
+import type { RunStudyProvenance } from "./run/study-provenance.js";
+/**
+ * Runs a study on its route. The options are checked against the route and mapped into the route's
+ * hook bags before anything runs. Each route closes the run it started on every exit through its
+ * own run scope (`src/run/run.ts`).
+ */
+export declare function runStudyWith(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): Promise<StudyOutcome>;
+/**
+ * The package's study runner (`src/index.ts`): runStudyWith with the public options only. A
+ * JavaScript caller that passes a field RunStudyOptions no longer has, or a humanish.lab.v2 config,
+ * is refused in the route's own result envelope before anything runs.
+ */
+export declare function runStudy(config: StudyConfig, options: RunStudyOptions): Promise<StudyOutcome>;
+/** A study planned once: the route's refusal, or the run of its plan. */
+export type PreparedStudy = {
+    readonly ok: false;
+    readonly outcome: StudyOutcome;
+} | {
+    readonly ok: true;
+    /** Runs the plan. A scorer loaded after planning joins the run's hooks; it changes no plan. */
+    run(scorer?: LateScorer): Promise<StudyOutcome>;
+};
+/**
+ * Normalizes the options and plans the study once, so a caller can present a refusal before it loads
+ * anything the run needs. A local browser study's provider is bound first, so the plan is made with
+ * it, and its desktop goes to the computer-use run as `localVm`; with inProcess the caller drives
+ * the app in process and needs no desktop.
+ */
+export declare function prepareStudy(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): Promise<PreparedStudy>;
+/**
+ * What a package caller passes to runStudy: the run's settings and the typed homes (`RunStudyHomes`,
+ * `RunStudyDriving`). Each wins over the config when provided.
+ */
+export type RunStudyOptions = RunStudyBase & RunStudyHomes & RunStudyDriving;
+interface RunStudyBase {
+    cwd: string;
+    runId?: string;
+    dryRun?: boolean;
+    open?: boolean;
+    /** Participant count override: preview participants or computer-use desktops. */
+    count?: number;
+    /** CUA fan-out only: create a new run for failed/selected participants from a prior run. */
+    rerun?: {
+        sourceRunId: string;
+        participantIds?: string[];
+    };
+    onObserverReady?: (observer: ObserverResult & {
+        ok: true;
+    }) => Promise<void> | void;
+}
+/** runStudyWith's options inside the package: the public ones plus what only the CLI and tests set. */
+export type InternalRunStudyOptions = RunStudyOptions & RunStudyInternals;
+interface RunStudyInternals {
+    /**
+     * Which manifest this run came from. planStudy puts it on the plan, and the route reads
+     * plan.study for the run's status record and bundle. Absent for a library caller that passes a
+     * StudyConfig directly; that run records no study.
+     */
+    study?: RunStudyProvenance;
+    /**
+     * Config-declared scorer provenance, forwarded alongside the
+     * loaded scorer. Its presence is the "declared" marker the terminal route reads to flip a
+     * status:"fail" verdict; the browser routes stamp it as evidence (they already flip). Core-computed
+     * (path + digest), never adopter-supplied; absent for library callers.
+     */
+    scorerProvenance?: RunScorerProvenance;
+    /** The local VM study's desktop, analysis gate and signal, for a local browser study. */
+    localVm?: LocalVmInput;
+}
+/** A run's result and the route it ran on. */
+interface RouteOutcome<R extends StudyRoute, T> {
+    route: R;
+    result: T;
+}
+export type StudyOutcome = RouteOutcome<"preview", PreviewStudyResult> | RouteOutcome<"computer-use", CuaActorStudyResult> | RouteOutcome<"scripted", ScriptedBrowserStudyResult> | RouteOutcome<"terminal", TerminalProductStudyResult> | RouteOutcome<"shared-world", ConcurrentSharedWorldStudyResult>;
+/**
+ * A plan past its route's local checks that need no scorer: the refusal they returned, or the
+ * route's run, which takes a scorer loaded after them.
+ */
+export type AdmittedPlan<R extends StudyRoute = StudyRoute> = {
+    readonly ok: false;
+    readonly outcome: Extract<StudyOutcome, {
+        route: R;
+    }>;
+} | {
+    readonly ok: true;
+    run(scorer?: LateScorer): Promise<Extract<StudyOutcome, {
+        route: R;
+    }>>;
+};
+/** The result of a run on route `R`, the `result` of that route's `StudyOutcome`. */
+export type StudyResult<R extends StudyRoute = StudyRoute> = {
+    preview: PreviewStudyResult;
+    "computer-use": CuaActorStudyResult;
+    scripted: ScriptedBrowserStudyResult;
+    terminal: TerminalProductStudyResult;
+    "shared-world": ConcurrentSharedWorldStudyResult;
+}[R];
+export {};

package/dist/{run-lab.js → run-study.js}

@@ -1,72 +1,79 @@
-// runLab runs one lab. It normalizes the caller's options, binds a local browser study's desktop
-// and provider, and plans the lab once with planLab. A refused plan returns the route's own result
+// runStudyWith runs one study. It normalizes the caller's options, binds a local browser study's desktop
+// and provider, and plans the study once with planStudy. A refused plan returns the route's own result
 // envelope before anything starts. One switch on plan.route then calls the route's admit function,
 // which runs the route's local checks that need no scorer (keys, subject env, the local agent) and
-// returns the route's run. prepareLab is the same path in two steps, so the CLI can present either
+// returns the route's run. prepareStudy is the same path in two steps, so the CLI can present either
 // refusal before it loads a declared review scorer.
-import { computerUseInput, scriptedInput, sharedWorldInput, terminalInput, } from "./lab/route-inputs.js";
-import { planLab, resolveLabDryRun, routeOf } from "./lab/plan.js";
-import { normalizeRunLabOptions, optionRefusalOutcome, removedOptionRefusal, } from "./lab/run-lab-options.js";
-import {} from "./lab/types.js";
-import { admitComputerUsePlan, computerUseLabRefusal } from "./routes/computer-use/route.js";
+import { computerUseInput, scriptedInput, sharedWorldInput, terminalInput, } from "./study/route-inputs.js";
+import { planStudy, resolveStudyDryRun, routeOf } from "./study/plan.js";
+import { normalizeRunStudyOptions, optionRefusalOutcome, removedOptionRefusal, } from "./study/run-study-options.js";
+import { V2_SCHEMA } from "./study/types.js";
+import { V2_UNSUPPORTED_MESSAGE } from "./study/config.js";
+import { admitComputerUsePlan, computerUseStudyRefusal } from "./routes/computer-use/route.js";
 import {} from "./routes/computer-use/types.js";
-import { admitPreviewPlan, previewLabRefusal } from "./routes/preview.js";
-import { admitScriptedPlan, scriptedLabRefusal } from "./routes/scripted/route.js";
+import { admitPreviewPlan, previewStudyRefusal, } from "./routes/preview.js";
+import { admitScriptedPlan, scriptedStudyRefusal } from "./routes/scripted/route.js";
 import {} from "./routes/scripted/types.js";
-import { admitSharedWorldPlan, sharedWorldLabRefusal } from "./routes/shared-world/route.js";
+import { admitSharedWorldPlan, sharedWorldStudyRefusal } from "./routes/shared-world/route.js";
 import {} from "./routes/shared-world/types.js";
-import { admitTerminalPlan, terminalLabRefusal } from "./routes/terminal/route.js";
+import { admitTerminalPlan, terminalStudyRefusal } from "./routes/terminal/route.js";
 import {} from "./routes/terminal/types.js";
 import {} from "./run/bundle.js";
-import { isLocalBrowserLab, localBrowserDefaults } from "./substrates/local/runtime-config.js";
+import { isLocalBrowserStudy, localBrowserDefaults } from "./substrates/local/runtime-config.js";
 /**
- * Runs a lab on its route. The options are checked against the route and mapped into the route's
+ * Runs a study on its route. The options are checked against the route and mapped into the route's
  * hook bags before anything runs. Each route closes the run it started on every exit through its
  * own run scope (`src/run/run.ts`).
  */
-export async function runLab(config, options, deps = {}) {
-    const prepared = await prepareLab(config, options, deps);
+export async function runStudyWith(config, options, deps = {}) {
+    const prepared = await prepareStudy(config, options, deps);
     return prepared.ok ? prepared.run() : prepared.outcome;
 }
 /**
- * runLab as the package exports it (`src/index.ts`): the public options only. A JavaScript caller
- * that passes a field RunLabOptions no longer has is refused in the route's own result envelope
- * before anything runs.
+ * The package's study runner (`src/index.ts`): runStudyWith with the public options only. A
+ * JavaScript caller that passes a field RunStudyOptions no longer has, or a humanish.lab.v2 config,
+ * is refused in the route's own result envelope before anything runs.
  */
-export async function runPackageLab(config, options) {
-    const removed = removedOptionRefusal(options);
-    if (removed === undefined)
-        return runLab(config, options);
-    const lab = localBrowserDefaults(config);
-    return optionRefusalOutcome(lab, routeOf(lab), options, removed);
+export async function runStudy(config, options) {
+    const refusal = config.schema === V2_SCHEMA
+        ? {
+            ok: false,
+            code: "HUMANISH_STUDY_V2_UNSUPPORTED",
+            message: V2_UNSUPPORTED_MESSAGE,
+        }
+        : removedOptionRefusal(options);
+    if (refusal === undefined)
+        return runStudyWith(config, options);
+    const study = localBrowserDefaults(config);
+    return optionRefusalOutcome(study, routeOf(study), options, refusal);
 }
 /**
- * Normalizes the options and plans the lab once, so a caller can present a refusal before it loads
+ * Normalizes the options and plans the study once, so a caller can present a refusal before it loads
  * anything the run needs. A local browser study's provider is bound first, so the plan is made with
  * it, and its desktop goes to the computer-use run as `localVm`; with inProcess the caller drives
  * the app in process and needs no desktop.
  */
-export async function prepareLab(config, options, deps = {}) {
-    const lab = localBrowserDefaults(config);
-    const route = routeOf(lab);
-    const normalized = normalizeRunLabOptions(lab, route, options);
+export async function prepareStudy(config, options, deps = {}) {
+    const study = localBrowserDefaults(config);
+    const route = routeOf(study);
+    const normalized = normalizeRunStudyOptions(study, route, options);
     if (!normalized.ok)
-        return { ok: false, outcome: optionRefusalOutcome(lab, route, options, normalized) };
+        return { ok: false, outcome: optionRefusalOutcome(study, route, options, normalized) };
     // An in-process executor needs no desktop, and a caller that already prepared the study passes
     // its localVm, which a second study would replace.
-    const prepareLocalVm = isLocalBrowserLab(lab) && options.inProcess === undefined && options.localVm === undefined
+    const prepareLocalVm = isLocalBrowserStudy(study) && options.inProcess === undefined && options.localVm === undefined
         ? (await import("./routes/computer-use/local-vm.js")).prepareLocalVmRun
         : undefined;
-    const vm = prepareLocalVm?.({ ...normalized.options, config: lab });
+    const vm = prepareLocalVm?.({ ...normalized.options, config: study });
     const planning = vm === undefined ? normalized.options : { ...vm.options, localVm: vm.localVm };
-    const planned = planLab(lab, planning, deps);
+    const planned = planStudy(study, planning, deps);
     if (!planned.ok) {
         await vm?.close();
-        const outcome = await refusalOutcome(lab, planning, planned.refusal, deps, normalized.emit);
+        const outcome = await refusalOutcome(study, planning, planned.refusal, deps, normalized.emit);
         outcome.result.warnings.push(...normalized.warnings);
         return { ok: false, outcome };
     }
-    const admitted = await admitPlan(lab, planning, planned.planned.plan, deps, normalized.emit);
+    const admitted = await admitPlan(study, planning, planned.planned.plan, deps, normalized.emit);
     if (!admitted.ok) {
         await vm?.close();
         admitted.outcome.result.warnings.push(...normalized.warnings);
@@ -81,9 +88,9 @@ export async function prepareLab(config, options, deps = {}) {
                 if (scorer !== undefined) {
                     // Checks the scorer against the route and the caller's options, as if passed up front.
                     // Only its refusal is used; its options and warnings array are not.
-                    const withScorer = normalizeRunLabOptions(lab, route, { ...options, ...scorer });
+                    const withScorer = normalizeRunStudyOptions(study, route, { ...options, ...scorer });
                     if (!withScorer.ok) {
-                        const outcome = optionRefusalOutcome(lab, route, options, withScorer);
+                        const outcome = optionRefusalOutcome(study, route, options, withScorer);
                         outcome.result.warnings.push(...normalized.warnings);
                         return outcome;
                     }
@@ -118,33 +125,33 @@ async function admitPlan(config, options, plan, deps, emit) {
 }
 /** The refused route's own result, with the envelope and analysis record its runner returns. */
 async function refusalOutcome(config, options, refusal, deps, emit) {
-    // Spend-safe default: a lab goes live only when the config (or CLI) says so.
-    const dryRun = resolveLabDryRun(config, options.dryRun, true) ?? true;
+    // Spend-safe default: a study goes live only when the config (or CLI) says so.
+    const dryRun = resolveStudyDryRun(config, options.dryRun, true) ?? true;
     switch (refusal.route) {
         case "preview":
             return {
                 route: "preview",
-                result: previewLabRefusal(options.cwd, config.id, refusal),
+                result: previewStudyRefusal(options.cwd, config.id, refusal),
             };
         case "computer-use":
             return {
                 route: "computer-use",
-                result: await computerUseLabRefusal({ ...computerUseInput(options, deps, emit), config, dryRun }, refusal),
+                result: await computerUseStudyRefusal({ ...computerUseInput(options, deps, emit), config, dryRun }, refusal),
             };
         case "scripted":
             return {
                 route: "scripted",
-                result: await scriptedLabRefusal({ ...scriptedInput(options, deps, emit), config, dryRun }, refusal),
+                result: await scriptedStudyRefusal({ ...scriptedInput(options, deps, emit), config, dryRun }, refusal),
             };
         case "terminal":
             return {
                 route: "terminal",
-                result: await terminalLabRefusal({ ...terminalInput(options, deps, emit), config, dryRun }, refusal),
+                result: await terminalStudyRefusal({ ...terminalInput(options, deps, emit), config, dryRun }, refusal),
             };
         case "shared-world":
             return {
                 route: "shared-world",
-                result: await sharedWorldLabRefusal({ ...sharedWorldInput(options, deps, emit), config, dryRun }, refusal),
+                result: await sharedWorldStudyRefusal({ ...sharedWorldInput(options, deps, emit), config, dryRun }, refusal),
             };
     }
 }

package/dist/{lab → study}/adapter-extension.d.ts

@@ -1,5 +1,4 @@
 import type { RunAdapterArtifact, RunAdapterScore, RunBundle, RunFeedbackCandidate, RunScorerProvenance } from "../run/bundle.js";
-type BrowserAdapterBackend = "cua" | "shared-world" | "concurrent-shared-world";
 /** The routes that call a browser scorer. */
 type BrowserScorerRoute = "computer-use" | "shared-world";
 /**
@@ -7,7 +6,7 @@ type BrowserScorerRoute = "computer-use" | "shared-world";
  * evidence/rubrics stay in the adopter's repo; core provides the assembled bundle
  * plus stable run identifiers and never learns product nouns.
  */
-export interface BrowserLabScoringContext {
+export interface BrowserScoringContext {
     bundle: RunBundle;
     /**
      * Absolute path to the ignored run directory. Adapter hooks may write their
@@ -15,28 +14,17 @@ export interface BrowserLabScoringContext {
      * `deriveArtifacts`. This path is runtime-only and must never be persisted.
      */
     runDir: string;
-    labId: string;
+    /** The study id. */
+    studyId: string;
     runId: string;
     actor: string;
     /** The route that ran the participants. */
     route: BrowserScorerRoute;
-    /**
-     * @deprecated Use `route`. `cua` is `computer-use` and `concurrent-shared-world` is
-     * `shared-world`. Reading it warns once per process; the next minor removes it.
-     */
-    backend: BrowserAdapterBackend;
     dryRun: boolean;
     /** How many participants the run had. */
     participantCount: number;
-    /**
-     * @deprecated Use `participantCount`, which has the same value. Reading it warns once per
-     * process; the next minor removes it.
-     */
-    laneCount: number;
 }
-/** The context a route passes to applyBrowserScorer; the deprecated fields derive from it. */
-type BrowserScoringFacts = Omit<BrowserLabScoringContext, "backend" | "laneCount">;
-/** The scorer functions a computer-use or shared-world run calls: `RunLabOptions.scorer`. */
+/** The scorer functions a computer-use or shared-world run calls: `RunStudyOptions.scorer`. */
 export interface BrowserScorer {
     /**
      * Browser-route extension seam: a thin adapter may score the assembled
@@ -44,20 +32,20 @@ export interface BrowserScorer {
      * namespaced `bundle.adapterScore`; product-specific component detail belongs
      * in `data`, not in core enums or review text.
      */
-    score?: (ctx: BrowserLabScoringContext) => RunAdapterScore | Promise<RunAdapterScore>;
+    score?: (ctx: BrowserScoringContext) => RunAdapterScore | Promise<RunAdapterScore>;
     /**
      * Companion seam for public-safe, adapter-namespaced feedback candidates.
      * Malformed candidates are dropped before bundle persistence so core remains
      * verifiable even when an adapter misbehaves.
      */
-    deriveFeedback?: (ctx: BrowserLabScoringContext) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
+    deriveFeedback?: (ctx: BrowserScoringContext) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
     /**
      * Optional product/state proof artifact references. The adapter writes files
      * under `ctx.runDir` and returns local relative paths. Core stores only the
      * namespaced references and `verify` fails closed if referenced files are
      * missing or nonlocal.
      */
-    deriveArtifacts?: (ctx: BrowserLabScoringContext) => RunAdapterArtifact[] | Promise<RunAdapterArtifact[]>;
+    deriveArtifacts?: (ctx: BrowserScoringContext) => RunAdapterArtifact[] | Promise<RunAdapterArtifact[]>;
 }
 /** What a scorer found against the run, for the route's final review fold (foldScorerFailures). */
 export interface ScorerOutcome {
@@ -70,7 +58,7 @@ export declare const DECLARED_SCORER_MALFORMED = "Declared product scorer return
 export declare function declaredScorerThrew(detail: string): string;
 export declare function applyBrowserScorer(args: {
     scorer: BrowserScorer | undefined;
-    context: BrowserScoringFacts;
+    context: BrowserScoringContext;
     bundle: RunBundle;
     sanitize: (text: string) => string;
     warnings: string[];

package/dist/{lab → study}/adapter-extension.js

@@ -1,19 +1,7 @@
 import path from "node:path";
 import { isRunAdapterScore } from "../run/bundle-shape.js";
-import { withDeprecatedFields } from "./deprecated-fields.js";
 import { isRunFeedbackCandidate } from "../run/feedback-shape.js";
 import { isRecord } from "../run/type-guards.js";
-const OLDER_BACKEND = {
-    "computer-use": "cua",
-    "shared-world": "concurrent-shared-world",
-};
-/** The scorer's context: the facts, plus the older `backend` and `laneCount` (deprecated-fields.ts). */
-function scorerContext(facts) {
-    return withDeprecatedFields({ ...facts }, { name: "BrowserLabScoringContext", code: "HUMANISH_SCORING_CONTEXT_FIELD_DEPRECATED" }, {
-        backend: { replacement: "route", read: () => OLDER_BACKEND[facts.route] },
-        laneCount: { replacement: "participantCount", read: () => facts.participantCount },
-    });
-}
 /** A declared scorer that returned a malformed value never rendered a verdict. */
 export const DECLARED_SCORER_MALFORMED = "Declared product scorer returned a malformed value instead of a verdict; a declared gate that cannot render a pass is recorded as a fail, never a silent pass.";
 /** A declared scorer that threw never rendered a verdict. `detail` is already sanitized. */
@@ -33,10 +21,10 @@ export async function applyBrowserScorer(args) {
     // The scorer sees a read-only view of the bundle: it cannot mutate noSpend/cost/review in place to
     // launder a verdict (a tamper attempt throws in the scorer's strict-mode ESM and is caught below as
     // a hook failure). The seam still stamps the real bundle.
-    const scoringContext = scorerContext({
+    const scoringContext = {
         ...context,
         bundle: frozenBundleView(context.bundle),
-    });
+    };
     const scrubValue = (value) => {
         const encoded = JSON.stringify(value);
         return encoded === undefined ? value : JSON.parse(sanitize(encoded));

package/dist/{lab → study}/adapter-scorer-loader.d.ts

@@ -1,17 +1,17 @@
-import type { BrowserLabScoringContext } from "./adapter-extension.js";
+import type { BrowserScoringContext } from "./adapter-extension.js";
 import type { TerminalProductScoringContext } from "../routes/terminal/types.js";
-import type { LabRoute } from "./plan.js";
+import type { StudyRoute } from "./plan.js";
 import type { RunAdapterArtifact, RunAdapterScore, RunFeedbackCandidate, RunScorerProvenance } from "../run/bundle.js";
 /** The read-model context a loaded scorer sees: the terminal or browser scoring context. The module
  *  narrows it at runtime (`"product" in ctx` ⇒ terminal; `"route" in ctx` ⇒ browser). */
-export type AdapterScoringContext = TerminalProductScoringContext | BrowserLabScoringContext;
+export type AdapterScoringContext = TerminalProductScoringContext | BrowserScoringContext;
 /**
  * The adopter-facing scorer module contract. Export any subset of these from a `.mjs` (or a
  * `.js`/`.cjs` whose package.json type matches): named exports or a single default object. The
  * loader wires only these three; an exported `executor`/`env`/`provisionSubject`/`costProbe` is never
  * picked up (the whitelist is the scope guard). A module exporting none of them is a hard load error.
  *
- * `C` is the context `score` and `deriveFeedback` read: `BrowserLabScoringContext` for a scorer
+ * `C` is the context `score` and `deriveFeedback` read: `BrowserScoringContext` for a scorer
  * written for computer use and shared world, `TerminalProductScoringContext` for one written for
  * terminal runs, or the default union for one that narrows at runtime.
  */
@@ -19,22 +19,22 @@ export interface AdapterScorerModule<C extends AdapterScoringContext = AdapterSc
     score?: (ctx: C) => RunAdapterScore | Promise<RunAdapterScore>;
     deriveFeedback?: (ctx: C) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
     /** Browser-route only; inert on the terminal route, whose TerminalScorer has no artifacts seam. */
-    deriveArtifacts?: (ctx: BrowserLabScoringContext) => RunAdapterArtifact[] | Promise<RunAdapterArtifact[]>;
+    deriveArtifacts?: (ctx: BrowserScoringContext) => RunAdapterArtifact[] | Promise<RunAdapterArtifact[]>;
 }
 /**
- * A scorer written for computer use and shared world, as `RunLabOptions.scorer` takes it. Those
+ * A scorer written for computer use and shared world, as `RunStudyOptions.scorer` takes it. Those
  * routes pass the browser context; another route that calls it passes a context it was not written
  * for. The call states the kind, so the module itself needs no cast.
  */
-export declare function browserScorer(scorer: AdapterScorerModule<BrowserLabScoringContext>): AdapterScorerModule;
-/** A scorer written for terminal runs, as `RunLabOptions.scorer` takes it (see browserScorer). */
+export declare function browserScorer(scorer: AdapterScorerModule<BrowserScoringContext>): AdapterScorerModule;
+/** A scorer written for terminal runs, as `RunStudyOptions.scorer` takes it (see browserScorer). */
 export declare function terminalScorer(scorer: AdapterScorerModule<TerminalProductScoringContext>): AdapterScorerModule;
 /**
  * The scorer as a computer-use or shared-world run calls it, with the browser context. The caller
  * chose the context it wrote the scorer for; only the route knows which context it passes, so the
  * narrowing is here. A terminal-typed scorer on a browser route reads fields the context lacks.
  */
-export declare function browserRouteScorer(scorer: AdapterScorerModule): AdapterScorerModule<BrowserLabScoringContext>;
+export declare function browserRouteScorer(scorer: AdapterScorerModule): AdapterScorerModule<BrowserScoringContext>;
 /** The scorer as a terminal run calls it, with the terminal context (see browserRouteScorer). */
 export declare function terminalRouteScorer(scorer: AdapterScorerModule): AdapterScorerModule<TerminalProductScoringContext>;
 type AdapterScorerLoadErrorCode = "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
@@ -57,7 +57,7 @@ export type AdapterScorerLoadResult = {
 export declare function loadAdapterScorer(args: {
     cwd: string;
     ref: string;
-    route: LabRoute;
+    route: StudyRoute;
     source: "manifest" | "cli-flag";
 }): Promise<AdapterScorerLoadResult>;
 export {};

package/dist/{lab → study}/adapter-scorer-loader.js

@@ -5,7 +5,7 @@
 // satisfied no-spend proof, so it stays library-only.
 //
 // Trust model: the party who writes `review.scorer.ref` is the party
-// who runs `humanish lab run` in their own checkout: identical trust to humanish.lab.yml or a
+// who runs `humanish run` in their own checkout: identical trust to humanish.lab.yml or a
 // package.json script. The loader adds no new execution capability; it relocates where the reference is
 // declared. Containment is entry-file-only: `readContainedRegularFile` blocks abs/`..`/symlink/
 // hardlink/realpath-escape/TOCTOU on the entry module, but `import()` then executes the transitive
@@ -20,14 +20,14 @@ import { pathToFileURL } from "node:url";
 import { digestText, redactText } from "../evidence/redaction.js";
 import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
 /**
- * A scorer written for computer use and shared world, as `RunLabOptions.scorer` takes it. Those
+ * A scorer written for computer use and shared world, as `RunStudyOptions.scorer` takes it. Those
  * routes pass the browser context; another route that calls it passes a context it was not written
  * for. The call states the kind, so the module itself needs no cast.
  */
 export function browserScorer(scorer) {
     return scorer;
 }
-/** A scorer written for terminal runs, as `RunLabOptions.scorer` takes it (see browserScorer). */
+/** A scorer written for terminal runs, as `RunStudyOptions.scorer` takes it (see browserScorer). */
 export function terminalScorer(scorer) {
     return scorer;
 }

package/dist/study/composition-rules.d.ts

@@ -0,0 +1,7 @@
+import type { StudyConfig } from "./types.js";
+/** The first composition rule a config breaks, in the parser's order, or null. */
+export declare function compositionReason(config: StudyConfig): string | null;
+/** Why a this-repo study cannot run live. The parser and the preview planner both refuse with it. */
+export declare const THIS_REPO_DRY_RUN_ONLY = "this-repo studies are dry-run only; use a clone or app-url subject for a live run.";
+/** A desktop-cli subject with no product to study. The computer-use planner checks this too. */
+export declare function desktopCliProductReason(config: StudyConfig): string | null;