humanish 0.106.1 → 0.108.0

package/dist/lab/adapter-extension.d.ts

@@ -1,7 +1,9 @@
 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";
 /**
- * Product-agnostic scoring context for browser/computer-use lanes. Product-specific
+ * Product-agnostic scoring context for browser/computer-use routes. Product-specific
  * evidence/rubrics stay in the adopter's repo; core provides the assembled bundle
  * plus stable run identifiers and never learns product nouns.
  */
@@ -16,13 +18,28 @@ export interface BrowserLabScoringContext {
     labId: 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;
 }
-export interface BrowserLabAdapterHooks {
+/** 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`. */
+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.
@@ -47,29 +64,34 @@ 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 applyBrowserAdapterHooks(args: {
-    hooks: BrowserLabAdapterHooks | undefined;
-    context: BrowserLabScoringContext;
+export declare function applyBrowserScorer(args: {
+    scorer: BrowserScorer | undefined;
+    context: BrowserScoringFacts;
     bundle: RunBundle;
     sanitize: (text: string) => string;
     warnings: string[];
-    hookLabel: 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>;
+/**
+ * A feedback candidate a scorer returned, accepted at the seam: the bundle's candidate shape with a
+ * non-empty summary. The browser and terminal seams both use it, so a candidate either seam drops
+ * never reaches a bundle.
+ */
+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/adapter-extension.js

@@ -1,106 +1,128 @@
 import path from "node:path";
-import { isFeedbackIdempotencyKey } from "../run/feedback-shape.js";
-/** A DECLARED scorer that returned a malformed value never rendered a verdict. */
+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. */
+/** 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.`;
 }
-export async function applyBrowserAdapterHooks(args) {
-    const { hooks, context, bundle, sanitize, warnings, hookLabel, scorerProvenance } = args;
-    if (!hooks?.score && !hooks?.deriveFeedback && !hooks?.deriveArtifacts)
+export async function applyBrowserScorer(args) {
+    const { scorer, context, bundle, sanitize, warnings, scorerProvenance } = args;
+    if (!scorer?.score && !scorer?.deriveFeedback && !scorer?.deriveArtifacts)
         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 = {
+    // a hook failure). The seam still stamps the real bundle.
+    const scoringContext = scorerContext({
         ...context,
         bundle: frozenBundleView(context.bundle),
-    };
+    });
     const scrubValue = (value) => {
         const encoded = JSON.stringify(value);
         return encoded === undefined ? value : JSON.parse(sanitize(encoded));
     };
     const failures = [];
-    if (hooks.score) {
+    if (scorer?.score) {
         try {
-            const score = await hooks.score(scoringContext);
+            const score = await scorer.score(scoringContext);
             const cleaned = scrubValue(score);
-            if (isAdapterScoreShape(cleaned)) {
+            if (isRunAdapterScore(cleaned)) {
                 bundle.adapterScore = cleaned;
                 const message = adapterScoreFailureMessage(bundle);
                 if (message !== undefined)
                     failures.push(message);
             }
             else {
-                warnings.push(`${hookLabel}.score returned a value that is not a well-formed humanish.adapter-score.v1 (non-empty namespace + status + numeric score + summary); dropped so the bundle stays verifiable.`);
+                warnings.push(`scorer.score returned a value that is not a well-formed humanish.adapter-score.v1 (non-empty namespace + status + numeric score + summary); dropped so the bundle stays verifiable.`);
                 if (declared)
                     failures.push(DECLARED_SCORER_MALFORMED);
             }
         }
         catch (error) {
             const detail = sanitize(error instanceof Error ? error.message : String(error));
-            warnings.push(`${hookLabel}.score threw (${detail}); dropped so the bundle stays verifiable.`);
+            warnings.push(`scorer.score threw (${detail}); dropped so the bundle stays verifiable.`);
             if (declared)
                 failures.push(declaredScorerThrew(detail));
         }
     }
-    if (hooks.deriveFeedback) {
+    if (scorer?.deriveFeedback) {
         try {
-            const candidates = await hooks.deriveFeedback(scoringContext);
+            const candidates = await scorer.deriveFeedback(scoringContext);
             const accepted = [];
             for (const candidate of Array.isArray(candidates) ? candidates : []) {
                 const cleaned = scrubValue(candidate);
-                if (isAdapterFeedbackCandidateShape(cleaned))
+                if (isAdapterFeedbackCandidate(cleaned))
                     accepted.push(cleaned);
                 else
-                    warnings.push(`${hookLabel}.deriveFeedback returned a candidate that is not a well-formed humanish.feedback-candidate.v1 (or its adapter block lacked a non-empty namespace + data record); dropped so the bundle stays verifiable.`);
+                    warnings.push(`scorer.deriveFeedback returned a candidate that is not a well-formed humanish.feedback-candidate.v1 (or its adapter block lacked a non-empty namespace + data record); dropped so the bundle stays verifiable.`);
             }
             if (accepted.length > 0) {
                 bundle.feedbackCandidates = [...bundle.feedbackCandidates, ...accepted];
             }
         }
         catch (error) {
-            warnings.push(`${hookLabel}.deriveFeedback threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
+            warnings.push(`scorer.deriveFeedback threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
         }
     }
-    if (hooks.deriveArtifacts) {
+    if (scorer?.deriveArtifacts) {
         try {
-            const artifacts = await hooks.deriveArtifacts(scoringContext);
+            const artifacts = await scorer.deriveArtifacts(scoringContext);
             const accepted = [];
             for (const artifact of Array.isArray(artifacts) ? artifacts : []) {
                 const cleaned = scrubValue(artifact);
                 if (isAdapterArtifactShape(cleaned))
                     accepted.push(cleaned);
                 else
-                    warnings.push(`${hookLabel}.deriveArtifacts returned an artifact that is not a well-formed humanish.adapter-artifact.v1 (non-empty namespace + label + local path + supported kind); dropped so the bundle stays verifiable.`);
+                    warnings.push(`scorer.deriveArtifacts returned an artifact that is not a well-formed humanish.adapter-artifact.v1 (non-empty namespace + label + local path + supported kind); dropped so the bundle stays verifiable.`);
             }
             if (accepted.length > 0) {
                 bundle.adapterArtifacts = [...(bundle.adapterArtifacts ?? []), ...accepted];
             }
         }
         catch (error) {
-            warnings.push(`${hookLabel}.deriveArtifacts threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
+            warnings.push(`scorer.deriveArtifacts threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
         }
     }
     return { failures };
 }
+/**
+ * A feedback candidate a scorer returned, accepted at the seam: the bundle's candidate shape with a
+ * non-empty summary. The browser and terminal seams both use it, so a candidate either seam drops
+ * never reaches a bundle.
+ */
+export function isAdapterFeedbackCandidate(value) {
+    return isRunFeedbackCandidate(value) && value.summary.trim().length > 0;
+}
 export function adapterScoreFailureMessage(bundle) {
     return bundle.adapterScore?.status === "fail"
         ? `Adapter scorer failed the run: ${bundle.adapterScore.summary}`
         : 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);
@@ -115,62 +137,6 @@ export function frozenBundleView(bundle) {
     freeze(clone);
     return clone;
 }
-function isAdapterScoreShape(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        value.schema === "humanish.adapter-score.v1" &&
-        typeof value.namespace === "string" &&
-        value.namespace.trim().length > 0 &&
-        ["pass", "partial", "fail"].includes(value.status) &&
-        typeof value.score === "number" &&
-        Number.isFinite(value.score) &&
-        typeof value.summary === "string" &&
-        (value.data === undefined ||
-            (typeof value.data === "object" &&
-                value.data !== null &&
-                !Array.isArray(value.data))));
-}
-function isAdapterFeedbackCandidateShape(value) {
-    if (!isRecord(value))
-        return false;
-    const candidate = value;
-    if (candidate.schema !== "humanish.feedback-candidate.v1" ||
-        typeof candidate.id !== "string" ||
-        typeof candidate.run_id !== "string" ||
-        (candidate.stream_id !== undefined && typeof candidate.stream_id !== "string") ||
-        typeof candidate.adapter_id !== "string" ||
-        typeof candidate.scenario_id !== "string" ||
-        typeof candidate.persona_id !== "string" ||
-        !isFeedbackActor(candidate.actor) ||
-        !isFeedbackSubstrate(candidate.substrate) ||
-        !isFeedbackFailureOwner(candidate.failure_owner) ||
-        typeof candidate.summary !== "string" ||
-        candidate.summary.trim().length === 0 ||
-        typeof candidate.expected !== "string" ||
-        typeof candidate.actual !== "string" ||
-        !Array.isArray(candidate.evidence) ||
-        !candidate.evidence.every(isFeedbackEvidence) ||
-        !isRecord(candidate.redaction) ||
-        candidate.redaction.status !== "passed" ||
-        typeof candidate.redaction.notes !== "string" ||
-        !isFeedbackIdempotencyKey(candidate.idempotency_key) ||
-        !isFeedbackNextState(candidate.proposed_next_state) ||
-        !Array.isArray(candidate.acceptance_proof) ||
-        !candidate.acceptance_proof.every((item) => typeof item === "string")) {
-        return false;
-    }
-    if (candidate.adapter !== undefined) {
-        const adapter = candidate.adapter;
-        if (!isRecord(adapter) ||
-            typeof adapter.namespace !== "string" ||
-            adapter.namespace.trim().length === 0 ||
-            !isRecord(adapter.data)) {
-            return false;
-        }
-    }
-    return true;
-}
 function isAdapterArtifactShape(value) {
     if (!isRecord(value))
         return false;
@@ -186,9 +152,6 @@ function isAdapterArtifactShape(value) {
         typeof artifact.note === "string" &&
         artifact.note.trim().length > 0);
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function isSafeRelativeArtifactPath(value) {
     return (value.trim().length > 0 &&
         !path.isAbsolute(value) &&
@@ -204,50 +167,3 @@ function isAdapterArtifactKind(value) {
         value === "filesystem" ||
         value === "summary");
 }
-function isFeedbackActor(value) {
-    return (value === "codex-tui" ||
-        value === "codex-exec" ||
-        value === "codex-app-server" ||
-        value === "computer-use" ||
-        value === "synthetic-dry-run" ||
-        value === "unknown");
-}
-function isFeedbackSubstrate(value) {
-    return (value === "e2b-desktop" ||
-        value === "local-desktop" ||
-        value === "e2b-terminal" ||
-        value === "local-filesystem" ||
-        value === "codex-app-server" ||
-        value === "unknown");
-}
-function isFeedbackFailureOwner(value) {
-    return (value === "harness" ||
-        value === "target-app" ||
-        value === "actor" ||
-        value === "environment" ||
-        value === "unknown");
-}
-function isFeedbackNextState(value) {
-    return (value === "watch" ||
-        value === "adapter-hardening" ||
-        value === "target-app-setup" ||
-        value === "actor-auth" ||
-        value === "setup-quality-review" ||
-        value === "study-quality-review");
-}
-function isFeedbackEvidence(value) {
-    if (!isRecord(value))
-        return false;
-    return (typeof value.path === "string" &&
-        value.path.length > 0 &&
-        !path.isAbsolute(value.path) &&
-        !value.path.includes("://") &&
-        !value.path.includes("..") &&
-        (value.kind === "review" ||
-            value.kind === "state" ||
-            value.kind === "log" ||
-            value.kind === "trace" ||
-            value.kind === "screenshot" ||
-            value.kind === "filesystem") &&
-        typeof value.note === "string");
-}

package/dist/lab/adapter-scorer-loader.d.ts

@@ -2,22 +2,42 @@ import type { BrowserLabScoringContext } from "./adapter-extension.js";
 import type { TerminalProductScoringContext } from "../routes/terminal/types.js";
 import type { LabRoute } 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; `"backend" in ctx` ⇒ browser). */
+/** 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;
 /**
- * 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
+ * written for computer use and shared world, `TerminalProductScoringContext` for one written for
+ * terminal runs, or the default union for one that narrows at runtime.
  */
-export interface AdapterScorerModule {
-    score?: (ctx: AdapterScoringContext) => RunAdapterScore | Promise<RunAdapterScore>;
-    deriveFeedback?: (ctx: AdapterScoringContext) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
-    /** Browser-route only; inert on the terminal route (TerminalProductLabHooks carries no artifacts seam). */
+export interface AdapterScorerModule<C extends AdapterScoringContext = AdapterScoringContext> {
+    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[]>;
 }
-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";
+/**
+ * A scorer written for computer use and shared world, as `RunLabOptions.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 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>;
+/** 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";
 export type AdapterScorerLoadResult = {
     ok: true;
     hooks: AdapterScorerModule;
@@ -32,7 +52,7 @@ 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;

package/dist/lab/adapter-scorer-loader.js

@@ -1,38 +1,62 @@
-// #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 lab 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";
 import { pathToFileURL } from "node:url";
 import { digestText, redactText } from "../evidence/redaction.js";
 import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
-/** 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. */
+/**
+ * A scorer written for computer use and shared world, as `RunLabOptions.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). */
+export function terminalScorer(scorer) {
+    return scorer;
+}
+/**
+ * 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 function browserRouteScorer(scorer) {
+    return scorer;
+}
+/** The scorer as a terminal run calls it, with the terminal context (see browserRouteScorer). */
+export function terminalRouteScorer(scorer) {
+    return scorer;
+}
+/** 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;
@@ -40,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));
@@ -67,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 {
@@ -90,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";
@@ -115,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",