humanish 0.107.0 → 0.109.0

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

@@ -1,74 +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 {} from "./run/results.js";
-import {} from "./run/status.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);
@@ -83,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;
                     }
@@ -120,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, 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,68 +14,57 @@ 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 (#165): a thin adapter may score the assembled
+     * Browser-route extension seam: a thin adapter may score the assembled
      * browser/shared-world evidence without forking core. The score is stored as
      * 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 {
     /** Why the scorer failed the run, in order; empty when it did not. */
     failures: string[];
 }
-/** A DECLARED scorer that returned a malformed value never rendered a verdict. */
+/** A declared scorer that returned a malformed value never rendered a verdict. */
 export declare 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. */
+/** A declared scorer that threw never rendered a verdict. `detail` is already sanitized. */
 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[];
-    /** Present only when the scorer was CONFIG-DECLARED (#316); core-stamped onto the bundle as
+    /** Present only when the scorer was config-declared; core-stamped onto the bundle as
      *  evidence of which out-of-tree module was loaded. Absent for library callers. Its presence also
-     *  makes a THROWING or MALFORMED scorer a failure — a declared gate that cannot render a pass is
+     *  makes a throwing or malformed scorer a failure: a declared gate that cannot render a pass is
      *  a fail, never a silent green. */
     scorerProvenance?: RunScorerProvenance;
 }): Promise<ScorerOutcome>;
@@ -88,10 +76,10 @@ export declare function applyBrowserScorer(args: {
 export declare function isAdapterFeedbackCandidate(value: unknown): value is RunFeedbackCandidate;
 export declare function adapterScoreFailureMessage(bundle: RunBundle): string | undefined;
 /**
- * Deep-freeze a structured clone so a loaded scorer sees a READ-ONLY bundle: it cannot mutate
+ * Deep-freeze a structured clone so a loaded scorer sees a read-only bundle: it cannot mutate
  * noSpend/cost/review in place to launder a verdict (which would defeat the costProbe-not-loadable
  * guarantee). A tamper attempt throws in the scorer's strict-mode ESM and is caught as a hook failure.
- * Legitimate read-only scoring is unaffected. The seam always stamps the REAL bundle, never this view.
+ * Legitimate read-only scoring is unaffected. The seam always stamps the real bundle, never this view.
  */
 export declare function frozenBundleView(bundle: RunBundle): RunBundle;
 export {};

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

@@ -2,44 +2,9 @@ import path from "node:path";
 import { isRunAdapterScore } from "../run/bundle-shape.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",
-};
-const warnedFields = new Set();
-function warnOlderField(name, replacement) {
-    if (warnedFields.has(name))
-        return;
-    warnedFields.add(name);
-    process.emitWarning(`BrowserLabScoringContext.${name} is deprecated and is removed in the next minor. Use ${replacement}.`, { type: "DeprecationWarning", code: "HUMANISH_SCORING_CONTEXT_FIELD_DEPRECATED" });
-}
-/**
- * The scorer's context: the facts, plus the older `backend` and `laneCount` as getters that warn
- * once when a scorer reads them. They are not enumerable, so a spread, `Object.assign`,
- * `JSON.stringify` or `structuredClone` of the context skips them and warns about no field the
- * code never named. `"backend" in ctx` still finds them. Core never reads them.
- */
-function scorerContext(facts) {
-    return Object.defineProperties({ ...facts }, {
-        backend: {
-            enumerable: false,
-            get: () => {
-                warnOlderField("backend", "route");
-                return OLDER_BACKEND[facts.route];
-            },
-        },
-        laneCount: {
-            enumerable: false,
-            get: () => {
-                warnOlderField("laneCount", "participantCount");
-                return facts.participantCount;
-            },
-        },
-    });
-}
-/** A DECLARED scorer that returned a malformed value never rendered a verdict. */
+/** 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. */
+/** A declared scorer that threw never rendered a verdict. `detail` is already sanitized. */
 export function declaredScorerThrew(detail) {
     return `Declared product scorer threw before returning a verdict (${detail}); a crashed declared gate is recorded as a fail, never a silent pass.`;
 }
@@ -49,17 +14,17 @@ export async function applyBrowserScorer(args) {
         return { failures: [] };
     const declared = scorerProvenance !== undefined;
     // Record the loaded scorer's identity regardless of hook outcome (a throwing/invalid scorer was
-    // still loaded and attempted). A VALID status:"fail" is a failure (library + declared, the
-    // pre-#316 (#165) path); a DECLARED scorer that THROWS or returns MALFORMED is one too (below).
+    // still loaded and attempted). A valid status:"fail" is a failure (library + declared, the
+    // original path); a declared scorer that throws or returns a malformed value is one too (below).
     if (scorerProvenance)
         bundle.scorerProvenance = scorerProvenance;
-    // The scorer sees a READ-ONLY view of the bundle: it cannot mutate noSpend/cost/review in place to
+    // 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({
+    // a hook failure). The seam still stamps the real bundle.
+    const scoringContext = {
         ...context,
         bundle: frozenBundleView(context.bundle),
-    });
+    };
     const scrubValue = (value) => {
         const encoded = JSON.stringify(value);
         return encoded === undefined ? value : JSON.parse(sanitize(encoded));
@@ -142,10 +107,10 @@ export function adapterScoreFailureMessage(bundle) {
         : undefined;
 }
 /**
- * Deep-freeze a structured clone so a loaded scorer sees a READ-ONLY bundle: it cannot mutate
+ * Deep-freeze a structured clone so a loaded scorer sees a read-only bundle: it cannot mutate
  * noSpend/cost/review in place to launder a verdict (which would defeat the costProbe-not-loadable
  * guarantee). A tamper attempt throws in the scorer's strict-mode ESM and is caught as a hook failure.
- * Legitimate read-only scoring is unaffected. The seam always stamps the REAL bundle, never this view.
+ * Legitimate read-only scoring is unaffected. The seam always stamps the real bundle, never this view.
  */
 export function frozenBundleView(bundle) {
     const clone = structuredClone(bundle);

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
+/** 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 (#316). 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.
+ * 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,25 +19,25 @@ 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_LAB_SCORER_BAD_REF" | "HUMANISH_LAB_SCORER_NOT_FOUND" | "HUMANISH_LAB_SCORER_LOAD_FAILED" | "HUMANISH_LAB_SCORER_NO_HOOKS" | "HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND";
+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";
 export type AdapterScorerLoadResult = {
     ok: true;
     hooks: AdapterScorerModule;
@@ -52,12 +52,12 @@ export type AdapterScorerLoadResult = {
 /**
  * Resolve + load a config-declared scorer module. Resolution clones scenario.ref exactly
  * (prepareSelectedOutputDirectory → cwd-clamp → readContainedRegularFile), then `import()`s the
- * entry file in a BROAD try/catch. The digest is over the readContainedRegularFile ENTRY bytes.
+ * entry file in a broad try/catch. The digest is over the readContainedRegularFile entry bytes.
  */
 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

@@ -1,18 +1,18 @@
-// #316 — CLI-loadable adopter scorer. Resolve `review.scorer.ref` / `--scorer` to an out-of-tree
-// scorer module, load it fail-closed (typed error + exit 2, PRE-SPEND), and pick off ONLY the
+// CLI-loadable adopter scorer. Resolve `review.scorer.ref` / `--scorer` to an out-of-tree
+// scorer module, load it fail-closed (typed error + exit 2, before any spend), and pick off only the
 // whitelisted read-model hooks {score, deriveFeedback, deriveArtifacts}. `costProbe` is deliberately
-// NOT loadable — an injected provider cost line overwrites the core-measured one and can forge a
+// not loadable: an injected provider cost line overwrites the core-measured one and can forge a
 // satisfied no-spend proof, so it stays library-only.
 //
-// TRUST MODEL (stated plainly, no overclaims): 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
-// package.json script. #316 adds ZERO new execution capability; it relocates WHERE the reference is
-// declared. Containment is ENTRY-FILE-ONLY: `readContainedRegularFile` blocks abs/`..`/symlink/
+// Trust model: the party who writes `review.scorer.ref` is the party
+// 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
 // graph + npm deps with no clamp, and `import()` runs top-level module code before any whitelist
-// check. The whitelist bounds the WIRED HOOK SURFACE, not arbitrary import-time code; the
+// check. The whitelist bounds the wired hook surface and does not cover import-time code; the
 // trusted-in-process boundary is the actual safety carrier. The seam's output re-scrub is a
-// best-effort denylist, NOT containment. `review.scorer.ref` entries are executable code — review a
+// best-effort denylist that provides no containment. `review.scorer.ref` entries are executable code, so review a
 // PR that adds one as code, not config.
 import { realpath } from "node:fs/promises";
 import path from "node:path";
@@ -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;
 }
@@ -43,20 +43,20 @@ export function browserRouteScorer(scorer) {
 export function terminalRouteScorer(scorer) {
     return scorer;
 }
-/** The routes whose hooks bag can carry the loaded scorer. A declared scorer on ANY other route
- *  (scripted or preview) aborts at load — a gate that cannot run must never green-pass. */
+/** The routes that can run the loaded scorer. A declared scorer on any other route
+ *  (scripted or preview) aborts at load: a gate that cannot run must never green-pass. */
 const SCORER_CAPABLE_ROUTES = new Set([
     "terminal",
     "computer-use",
     "shared-world",
 ]);
-/** `.mjs` is required-canonical; `.js`/`.cjs` accepted but the module system is the adopter repo's
- *  package.json `type`. `.ts` is rejected — the compiled `dist/` CLI ships no TypeScript loader. */
+/** `.mjs` is the recommended extension; `.js`/`.cjs` accepted but the module system is the adopter repo's
+ *  package.json `type`. `.ts` is rejected: the compiled `dist/` CLI ships no TypeScript loader. */
 const SCORER_EXTENSIONS = new Set([".mjs", ".js", ".cjs"]);
 /**
  * Resolve + load a config-declared scorer module. Resolution clones scenario.ref exactly
  * (prepareSelectedOutputDirectory → cwd-clamp → readContainedRegularFile), then `import()`s the
- * entry file in a BROAD try/catch. The digest is over the readContainedRegularFile ENTRY bytes.
+ * entry file in a broad try/catch. The digest is over the readContainedRegularFile entry bytes.
  */
 export async function loadAdapterScorer(args) {
     const { route, source } = args;
@@ -64,25 +64,25 @@ export async function loadAdapterScorer(args) {
         ok: false,
         error: { code, message },
     });
-    // A declared gate that cannot run on this route must ABORT (never silently green-pass).
+    // A declared gate that cannot run on this route must abort (never silently green-pass).
     if (!SCORER_CAPABLE_ROUTES.has(route)) {
-        return fail("HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND", `review.scorer.ref is declared but this lab resolves to the ${route} route, which has no adopter-scorer seam. A declared scorer that cannot run must fail closed rather than pass silently — declare it on a terminal, computer-use or shared-world lab.`);
+        return fail("HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND", `review.scorer.ref is set, but this study runs on the ${route} route, which cannot run a scorer. The run stops here so the scorer is not silently skipped. Use it with a terminal, computer-use or shared-world study, or remove review.scorer.ref.`);
     }
     const trimmed = args.ref.trim();
     if (!trimmed) {
-        return fail("HUMANISH_LAB_SCORER_BAD_REF", "review.scorer.ref must be a non-empty repo-relative path ending in .mjs (recommended), .js, or .cjs.");
+        return fail("HUMANISH_STUDY_SCORER_BAD_REF", "review.scorer.ref must be a non-empty repo-relative path ending in .mjs (recommended), .js, or .cjs.");
     }
-    // Provenance is recorded repo-relative — an absolute ref (even one that happens to land inside cwd)
+    // Provenance is recorded repo-relative: an absolute ref (even one that happens to land inside cwd)
     // is rejected up front rather than silently rewritten to its in-tree relative form.
     if (path.isAbsolute(trimmed)) {
-        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a repo-relative path, not absolute — provenance is recorded repo-relative.`);
+        return fail("HUMANISH_STUDY_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a path relative to the project, not an absolute path, because the run records it relative to the project.`);
     }
     const ext = path.extname(trimmed).toLowerCase();
     if (ext === ".ts") {
-        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" ends in .ts, but the shipped CLI runs compiled JS with no TypeScript loader. Precompile to .mjs (recommended) or .js/.cjs.`);
+        return fail("HUMANISH_STUDY_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" ends in .ts, but the shipped CLI runs compiled JS with no TypeScript loader. Precompile to .mjs (recommended) or .js/.cjs.`);
     }
     if (!SCORER_EXTENSIONS.has(ext)) {
-        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a repo-relative PATH ending in .mjs (recommended), .js, or .cjs — an id-style ref is not supported.`);
+        return fail("HUMANISH_STUDY_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a path relative to the project ending in .mjs (recommended), .js or .cjs.`);
     }
     // Root token: realpath(cwd) → prepareSelectedOutputDirectory(dirname, cwd). Mirrors scenario.ref.
     const physicalCwd = await realpath(path.resolve(args.cwd));
@@ -91,18 +91,18 @@ export async function loadAdapterScorer(args) {
     const absolutePath = path.resolve(root.physicalPath, trimmed);
     const relative = path.relative(root.physicalPath, absolutePath);
     if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must stay inside the target cwd — provenance is recorded repo-relative and an escaping/absolute path (a cwd parent, node_modules above cwd, an absolute path) cannot be.`);
+        return fail("HUMANISH_STUDY_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must stay inside the project directory, because the run records it relative to the project; a path into a parent directory cannot be recorded that way.`);
     }
     const relPosix = relative.split(path.sep).join("/");
-    // Fail-closed containment gate on the ENTRY file only: rejects symlink, nlink>1, realpath-escape,
+    // Fail-closed containment gate on the entry file only: rejects symlink, nlink>1, realpath-escape,
     // TOCTOU. Its returned bytes are the digest input.
     const bytes = await readContainedRegularFile(root, relPosix);
     if (!bytes) {
-        return fail("HUMANISH_LAB_SCORER_NOT_FOUND", `review.scorer.ref "${trimmed}" could not be read as a contained regular file (${relPosix}). A scorer must be a regular file inside the target cwd — no symlink, no hardlink, no realpath escape.`);
+        return fail("HUMANISH_STUDY_SCORER_NOT_FOUND", `review.scorer.ref "${trimmed}" could not be read as a regular file inside the project (${relPosix}). Use a plain file there: not a symlink or a hard link, and not a path that resolves outside the project.`);
     }
     const digest = digestText(bytes.toString("utf8"));
-    // Import the entry module in a BROAD try/catch (ERR_MODULE_NOT_FOUND / SyntaxError / ERR_REQUIRE_ESM
-    // / top-level throw). import() executes the transitive graph — the cwd clamp guards only the ENTRY
+    // Import the entry module in a broad try/catch (ERR_MODULE_NOT_FOUND / SyntaxError / ERR_REQUIRE_ESM
+    // / top-level throw). import() executes the transitive graph, and the cwd clamp guards only the entry
     // file; out-of-tree/transitive code is acceptable only because of the trust boundary above.
     let mod;
     try {
@@ -114,12 +114,12 @@ export async function loadAdapterScorer(args) {
         const hint = /ERR_REQUIRE_ESM|import statement outside a module|Cannot use import statement|Unexpected (?:token|identifier)|SyntaxError/i.test(detail)
             ? ' Use a .mjs entry file, or set "type": "module" in the nearest package.json.'
             : "";
-        return fail("HUMANISH_LAB_SCORER_LOAD_FAILED", `review.scorer.ref "${trimmed}" failed to load: ${redactText(detail)}.${hint}`);
+        return fail("HUMANISH_STUDY_SCORER_LOAD_FAILED", `review.scorer.ref "${trimmed}" failed to load: ${redactText(detail)}.${hint}`);
     }
-    // mod.default ?? mod, then pick off ONLY the whitelist. An exported executor/env/costProbe is never
-    // wired — the whitelist is the scope guard. `exports` records the hooks ACTUALLY WIRED for this
+    // mod.default ?? mod, then pick off only the whitelist. An exported executor/env/costProbe is never
+    // wired; the whitelist is the scope guard. `exports` records the hooks actually wired for this
     // backend: deriveArtifacts is browser-only, so on the terminal route it is neither wired nor
-    // recorded (a scorer that exported ONLY deriveArtifacts there wires nothing and fails closed below,
+    // recorded (a scorer that exported only deriveArtifacts there wires nothing and fails closed below,
     // never a silent no-op).
     const picked = (mod.default ?? mod);
     const terminalRoute = route === "terminal";
@@ -139,9 +139,9 @@ export async function loadAdapterScorer(args) {
     }
     if (exports.length === 0) {
         const artifactsOnly = terminalRoute && typeof picked.deriveArtifacts === "function";
-        return fail("HUMANISH_LAB_SCORER_NO_HOOKS", artifactsOnly
+        return fail("HUMANISH_STUDY_SCORER_NO_HOOKS", artifactsOnly
             ? `review.scorer.ref "${trimmed}" exported only deriveArtifacts, which is browser-only and inert on the terminal route. Export score and/or deriveFeedback for a terminal-product scorer.`
-            : `review.scorer.ref "${trimmed}" loaded but exported none of the adopter-scorer hooks (score, deriveFeedback, deriveArtifacts). Export at least one (named, or on a single default object). costProbe is intentionally NOT loadable.`);
+            : `review.scorer.ref "${trimmed}" loaded but exports none of score, deriveFeedback or deriveArtifacts. Export at least one, as a named export or on a default object. costProbe cannot be loaded from a scorer file.`);
     }
     const provenance = {
         schema: "humanish.scorer-provenance.v1",

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;