humanish 0.107.0 → 0.109.0

package/dist/routes/scripted/bundle.js

@@ -1,18 +1,20 @@
-// Assemble the scripted-browser lab's run bundle from its sessions, and the review summary and
+// Assemble the scripted-browser study's run bundle from its sessions, and the review summary and
 // markdown that ship with it.
+import { verdictText } from "../../run/judge.js";
 import { redactText } from "../../evidence/redaction.js";
 import { buildRunCostSummary, desktopSpanToMinutes, spendFreeCostSummary, } from "../../run/cost-summary.js";
 import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
 import {} from "../../run/streams.js";
 import { participantEvent, recordIdOf } from "../../run/participant-records.js";
 import { scriptedSurfaceIds, scriptedSurfaceRecords } from "./surface-records.js";
+import { plural } from "../../run/text.js";
 /**
- * Project the scripted lab run into a humanish.run-bundle.v1 (no schema change — a new
- * producer only). The load-bearing line is `stream.actor = result.trace`: the provider-neutral
+ * Project the scripted run into a humanish.run-bundle.v1 (no schema change: a new
+ * producer only). The key line is `stream.actor = result.trace`: the provider-neutral
  * ActorTrace seam the Observer renders and verifyRun's engagement check reads. Exported for
  * the bundle-builder tests.
  */
-export function buildScriptedLabBundle(args) {
+export function buildScriptedStudyBundle(args) {
     const resultBySurface = new Map(args.sessionResults.map((result) => [result.capture.surface.id, result]));
     // Each surface's records are stamped with the run's start.
     const context = { ...args, createdAt: args.run.createdAt };
@@ -26,7 +28,7 @@ export function buildScriptedLabBundle(args) {
         persona: {
             id: args.persona.id,
             name: `Scripted journey persona (${args.persona.id})`,
-            source: `lab:${args.labId}`,
+            source: `study:${args.studyId}`,
             sourceDigest: args.persona.promptDigest,
         },
         scenario: {
@@ -40,7 +42,7 @@ export function buildScriptedLabBundle(args) {
             {
                 at: args.run.createdAt,
                 event: "scripted-lab.run.created",
-                message: `Created scripted-browser lab run with ${args.surfaces.length} surface${args.surfaces.length === 1 ? "" : "s"} (actor ${args.actorId}).`,
+                message: `Created a scripted-browser run with ${args.surfaces.length} surface${args.surfaces.length === 1 ? "" : "s"} (actor ${args.actorId}).`,
             },
         ],
         simulations: records.map((record) => record.simulation),
@@ -49,8 +51,8 @@ export function buildScriptedLabBundle(args) {
         redaction: {
             status: "passed",
             notes: ranLive
-                ? "Scripted step URLs are sanitized to loopback origin+path (query/hash redacted) and step text passes text redaction. Screenshots are FULL-FIDELITY (raw), retained for local use in gitignored .humanish — NOT redacted for publishing; policies.redactScreenshots is not yet supported on this route."
-                : "Dry-run contract bundle: no browser ran and no screenshots were captured. The scenario contract is digest-pinned; live step text passes text redaction when a session runs.",
+                ? "Scripted step URLs are reduced to loopback origin and path (query and hash removed), and step text passes text redaction. Screenshots are unblurred and kept for local use in the gitignored .humanish/ folder; they are not redacted for publishing, and policies.redactScreenshots is not supported on this route yet."
+                : "Dry-run bundle: no browser ran and no screenshots were captured. The scenario is digest-pinned; live step text passes text redaction when a session runs.",
         },
         artifacts: bundleArtifacts(),
         review,
@@ -68,18 +70,18 @@ function scriptedEvents(args) {
             at: args.run.createdAt,
             level: "info",
             type: "scripted-lab.run.created",
-            message: `Created scripted-browser lab run for ${args.labId} (actor ${args.actorId}, ${args.surfaces.length} surface${args.surfaces.length === 1 ? "" : "s"}).`,
+            message: `Created a scripted-browser run for ${args.studyId} (actor ${args.actorId}, ${args.surfaces.length} surface${args.surfaces.length === 1 ? "" : "s"}).`,
         },
         {
             id: "event-001-subject",
             at: args.run.createdAt,
             level: "info",
             type: "scripted-lab.subject.declared",
-            // Invariant 5: provenance recorded or its absence declared. The lab did not provision
+            // Provenance is recorded or its absence declared. humanish did not provision
             // this subject on app-url routes; clone routes carry structured subject provenance below.
             message: args.subject
                 ? `Provisioned synthetic subject: clone of ${args.subject.repo}${args.subject.commit ? `@${args.subject.commit}` : ""}, served + getHost-exposed in-sandbox; env names: ${args.subject.envNames?.join(", ") || "none"} (values never persisted); state provenance: ${args.subject.state.provenance}; evidence host digest: ${args.hostDigest ?? "dry-run"}.`
-                : `Subject app declared at ${args.appUrl}; the lab did not provision it — subject build/commit provenance is UNPINNED; evidence binds to the scenario digest ${args.scenarioSourceDigest}.`,
+                : `Subject app declared at ${args.appUrl}; humanish did not provision it, so its build and commit are unpinned. The evidence is tied to the scenario digest ${args.scenarioSourceDigest}.`,
         },
         {
             id: "event-002-spend",
@@ -98,7 +100,7 @@ function scriptedEvents(args) {
                 at: result.capture.capturedAt,
                 level: result.status === "passed" ? "info" : "warn",
                 type: `scripted-lab.session.${result.completionReason}`,
-                message: `${result.capture.surface.id}: ${result.status} — ${result.reason}`,
+                message: `${result.capture.surface.id}: ${result.status} (${result.reason})`,
             }));
         }
     }
@@ -117,7 +119,7 @@ function scriptedEvents(args) {
             at: args.run.createdAt,
             level: "info",
             type: "scripted-lab.contract.ready",
-            message: `Dry-run contract bundle ready: scenario ${args.journey.scenarioId} @ ${args.scenarioSourceDigest} (${args.scenarioSource}, ${args.journey.steps.length} step${args.journey.steps.length === 1 ? "" : "s"}) parsed and digest-pinned; switch scenario.mode to live to actuate a real browser.`,
+            message: `Dry-run bundle ready: scenario ${args.journey.scenarioId} @ ${args.scenarioSourceDigest} (${args.scenarioSource}, ${args.journey.steps.length} step${args.journey.steps.length === 1 ? "" : "s"}) parsed and digest-pinned; switch scenario.mode to live to actuate a real browser.`,
         });
     }
     return events;
@@ -143,7 +145,7 @@ function buildScriptedReview(args) {
         return {
             schema: REVIEW_SCHEMA,
             verdict: args.verdict,
-            summary: `Scripted lab failed before a terminal session verdict: ${args.sessionError}`,
+            summary: `The scripted run failed before a terminal session verdict: ${args.sessionError}`,
             gaps: [],
         };
     }
@@ -151,8 +153,8 @@ function buildScriptedReview(args) {
         return {
             schema: REVIEW_SCHEMA,
             verdict: args.verdict,
-            summary: `Dry-run contract for scenario ${args.journey.scenarioId} (${args.scenarioSource}, ${args.journey.steps.length} steps) against ${args.appUrl}: composition and scenario contract proven at $0; no browser ran.`,
-            gaps: ["Live scripted session not yet run (dry-run contract only)."],
+            summary: `Dry run of scenario ${args.journey.scenarioId} (${args.scenarioSource}, ${args.journey.steps.length} steps) against ${args.appUrl}: composition and scenario checked at $0; no browser ran.`,
+            gaps: ["Live scripted session not yet run (dry run only)."],
         };
     }
     const passed = args.sessionResults.filter((result) => result.status === "passed").length;
@@ -176,12 +178,12 @@ export function renderScriptedReviewMarkdown(bundle) {
         "",
         `- run: ${bundle.runId}`,
         `- mode: ${bundle.mode}`,
-        `- verdict: ${bundle.review.verdict}`,
+        `- verdict: ${verdictText(bundle.review.verdict, bundle.mode)}`,
         `- summary: ${bundle.review.summary}`,
         `- scenario: ${bundle.scenario.id} @ ${bundle.scenario.sourceDigest} (${bundle.scenario.source})`,
         ...(subject ? [`- subject: ${subject.message}`] : []),
         ...(spend ? [`- spend: ${spend.message}`] : []),
-        ...traces.map(({ stream, trace }) => `- ${recordIdOf(stream)}: ${trace.provider} (${trace.lane}/${trace.protocol}) ${trace.status} (${trace.completionReason}); ${trace.counts.actions ?? 0} step action(s), ${trace.counts.screenshots ?? 0} raw screenshot(s)`),
+        ...traces.map(({ stream, trace }) => `- ${recordIdOf(stream)}: ${trace.provider} (${trace.lane}/${trace.protocol}) ${trace.status} (${trace.completionReason}); ${plural(trace.counts.actions ?? 0, "step action")}, ${plural(trace.counts.screenshots ?? 0, "raw screenshot")}`),
         ...(bundle.review.gaps.length > 0
             ? ["", "## Gaps", ...bundle.review.gaps.map((gap) => `- ${gap}`)]
             : []),

package/dist/routes/scripted/plan.d.ts

@@ -1,8 +1,8 @@
-import type { LabDeps } from "../../lab/lab-deps.js";
-import type { RoutePlanResult, RouteRefusal, ScriptedPlan } from "../../lab/plan-types.js";
-import type { LabConfig } from "../../lab/types.js";
-/** The error a scripted lab returns before a run starts. */
-export interface ScriptedRefusal extends RouteRefusal<"scripted", "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE"> {
+import type { StudyDeps } from "../../study/study-deps.js";
+import type { RoutePlanResult, RouteRefusal, ScriptedPlan } from "../../study/plan-types.js";
+import type { StudyConfig } from "../../study/types.js";
+/** The error a scripted study returns before a run starts. */
+export interface ScriptedRefusal extends RouteRefusal<"scripted", "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE"> {
     /**
      * Set on the receiving, analysis and tasks refusals. The route returns those before it opens its
      * run scope, so their result has its own field order and no automatic-analysis record.
@@ -16,12 +16,12 @@ export type ScriptedPlanResult = RoutePlanResult<ScriptedPlan, ScriptedRefusal>;
 /** The app URL a run's evidence names: a provisioned subject's getHost URL is never persisted. */
 export declare function evidenceAppUrlOf(subject: ScriptedPlan["subject"]): string;
 /** Whether a test injected the browser, so a live run needs no host browser. */
-export declare function injectedBrowser(deps: LabDeps | undefined): boolean;
+export declare function injectedBrowser(deps: StudyDeps | undefined): boolean;
 /**
- * Plan a scripted-browser lab. It is called for any config handed to the scripted runner, not only
+ * Plan a scripted-browser study. It is called for any config handed to the scripted runner, not only
  * one routeOf sends here, so a config for another route gets this route's refusal.
  */
-export declare function planScriptedLab(config: LabConfig, input: {
+export declare function planScriptedStudy(config: StudyConfig, input: {
     readonly dryRun: boolean;
     /** A test's injected browser means a live run needs no host browser. */
     readonly injectedBrowser?: boolean;

package/dist/routes/scripted/plan.js

@@ -5,8 +5,8 @@ import { actorRegistry, isScriptedBrowserActorDescriptor } from "../../actors/re
 import { normalizeLocalAppUrl } from "../../actors/scripted-browser/steps.js";
 import { browserSurfaces } from "../../actors/scripted-browser/types.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
-import { isNonEmpty, planBase, provisionedSubject } from "../../lab/plan-base.js";
-import { cloneTargetValidationReason, desktopMediaValidationReason, taskProtocolValidationReason, } from "../../lab/validation.js";
+import { isNonEmpty, planBase, provisionedSubject } from "../../study/plan-base.js";
+import { cloneTargetValidationReason, desktopMediaValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 // Default surface roster is 1 (desktop only): the defaults-table single-participant row governs;
 // `count: 2` is the declared override that adds the mobile surface.
 const DEFAULT_SURFACE_COUNT = 1;
@@ -19,33 +19,33 @@ export function injectedBrowser(deps) {
     return Boolean(deps?.launchBrowser || deps?.browserCommand);
 }
 /**
- * Plan a scripted-browser lab. It is called for any config handed to the scripted runner, not only
+ * Plan a scripted-browser study. It is called for any config handed to the scripted runner, not only
  * one routeOf sends here, so a config for another route gets this route's refusal.
  */
-export function planScriptedLab(config, input) {
+export function planScriptedStudy(config, input) {
     const refuse = (code, message, extras = {}) => ({
         ok: false,
         refusal: { route: "scripted", code, message, ...extras },
     });
     const beforeScope = { beforeScope: true };
     if (String(config.comms?.email?.kind) === "real")
-        return refuse("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", "Real email receiving is unsupported on the scripted route. Use a supported hosted computer-use browser lab.", beforeScope);
+        return refuse("HUMANISH_SCRIPTED_SCENARIO_INVALID", "Real email receiving is unsupported on the scripted route. Use a supported hosted computer-use browser study.", beforeScope);
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
     if (!analysis.ok)
-        return refuse("HUMANISH_LAB_ANALYSIS_INVALID", analysis.message, beforeScope);
+        return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message, beforeScope);
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
-        return refuse("HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason, beforeScope);
+        return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason, beforeScope);
     const mediaReason = desktopMediaValidationReason(config);
     if (mediaReason)
-        return refuse("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", mediaReason);
+        return refuse("HUMANISH_SCRIPTED_SCENARIO_INVALID", mediaReason);
     const cloneTargetReason = cloneTargetValidationReason(config);
     if (cloneTargetReason)
-        return refuse("HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE", cloneTargetReason);
+        return refuse("HUMANISH_SCRIPTED_SUBJECT_UNSAFE", cloneTargetReason);
     const actorType = config.actors[0]?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isScriptedBrowserActorDescriptor(descriptor))
-        return refuse("HUMANISH_SCRIPTED_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered scripted-browser actor.`);
+        return refuse("HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered scripted-browser actor.`);
     const actor = descriptor.id;
     // The parser checks the loopback entry too; a library caller skips the parser. A clone's URL is
     // minted by getHost during the run, and its evidence names only the placeholder.
@@ -53,19 +53,19 @@ export function planScriptedLab(config, input) {
     if (config.subject.source === "clone") {
         const provisioned = provisionedSubject(config);
         if (provisioned?.kind !== "clone" || !provisioned.repo)
-            return refuse("HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE", "clone scripted-browser labs require one subject repo plus subject.serve; parseLabConfig should have rejected this config.", { actor, appUrl: "[provisioned-subject]" });
+            return refuse("HUMANISH_SCRIPTED_SUBJECT_UNSAFE", "clone scripted-browser studies require one subject repo plus subject.serve; parseStudy should have rejected this config.", { actor, appUrl: "[provisioned-subject]" });
         subject = provisioned;
     }
     else {
         const appUrl = normalizeLocalAppUrl(config.subject.appUrl ?? "");
         if (!appUrl)
-            return refuse("HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE", "subject.appUrl must be a loopback http(s) URL (127.0.0.1 or localhost) on the scripted-browser route.", { actor });
+            return refuse("HUMANISH_SCRIPTED_SUBJECT_UNSAFE", "subject.appUrl must be a loopback http(s) URL (127.0.0.1 or localhost) on the scripted-browser route.", { actor });
         subject = { kind: "loopback", appUrl };
     }
     // The steps are the actor, so there is no built-in journey to fall back on.
     const scenarioRef = config.scenario?.ref;
     if (!scenarioRef?.trim())
-        return refuse("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", "scripted-browser labs require `scenario.ref` — the committed scenario's browser steps are what this actor executes.", { actor, appUrl: evidenceAppUrlOf(subject) });
+        return refuse("HUMANISH_SCRIPTED_SCENARIO_INVALID", "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.", { actor, appUrl: evidenceAppUrlOf(subject) });
     const requirements = [];
     if (!input.dryRun && subject.kind === "clone") {
         requirements.push({ kind: "key", name: "E2B_API_KEY" });

package/dist/routes/scripted/result.d.ts

@@ -1,13 +1,13 @@
 import type { ActorPersonaRef } from "../../actors/contract.js";
 import type { ScriptedBrowserSessionResult } from "../../actors/scripted-browser/actor.js";
 import type { BrowserPersonaJourney } from "../../actors/scripted-browser/types.js";
-import type { ScriptedPlan } from "../../lab/plan-types.js";
+import type { ScriptedPlan } from "../../study/plan-types.js";
 import type { RunBundle } from "../../run/bundle.js";
 import type { RunScope } from "../../run/run.js";
 import { type ExecutionFailure } from "../../run/judge.js";
 import type { ObserverResult } from "../../observer/render.js";
 import type { ScriptedSubject } from "./subject.js";
-import { type ScriptedBrowserLabResult } from "./types.js";
+import { type ScriptedBrowserStudyResult } from "./types.js";
 /** What the finish reads from the run. */
 export interface ScriptedFinishInputs {
     plan: ScriptedPlan;
@@ -48,4 +48,4 @@ export declare function scriptedExecutionFailures(args: {
     subject: Pick<ScriptedSubject, "sandboxId" | "killed" | "releaseWarning"> | undefined;
     observer: Pick<ObserverResult, "ok" | "error">;
 }): ExecutionFailure[];
-export declare function finishScriptedRun(inputs: ScriptedFinishInputs): Promise<ScriptedBrowserLabResult>;
+export declare function finishScriptedRun(inputs: ScriptedFinishInputs): Promise<ScriptedBrowserStudyResult>;

package/dist/routes/scripted/result.js

@@ -1,9 +1,10 @@
 import { judgeExecution, sandboxCleanupFailure, judgeScripted, OUTCOME_POLICIES, resultOk, } from "../../run/judge.js";
 import { validatePreparedRunArtifactPaths } from "../../run/paths.js";
 import { resolveSubjectState } from "../computer-use/subject-projection.js";
-import { buildScriptedLabBundle } from "./bundle.js";
+import { buildScriptedStudyBundle } from "./bundle.js";
 import { existingScreenshots } from "./session-result.js";
-import { SCRIPTED_BROWSER_LAB_SCHEMA } from "./types.js";
+import {} from "./types.js";
+import { studyResultIdentity } from "../../run/study-result.js";
 /** What judgeScripted reads from one surface's session. Scripted has no engagement or blocker rule. */
 function scriptedSurfaceFacts(result) {
     return {
@@ -36,7 +37,7 @@ export function scriptedExecutionFailures(args) {
             ? [
                 {
                     kind: "harness",
-                    message: "Scripted lab did not produce terminal sessions for every surface.",
+                    message: "The scripted run did not produce terminal sessions for every surface.",
                 },
             ]
             : []),
@@ -48,7 +49,7 @@ export function scriptedExecutionFailures(args) {
             : [
                 {
                     kind: "evidence",
-                    message: observer.error?.message ?? "Observer failed for the scripted lab run.",
+                    message: observer.error?.message ?? "Observer failed for the scripted run.",
                 },
             ]),
     ];
@@ -89,14 +90,14 @@ export async function finishScriptedRun(inputs) {
         expected: surfaces.length,
         surfaces: sessionResults.map(scriptedSurfaceFacts),
     });
-    const bundle = buildScriptedLabBundle({
+    const bundle = buildScriptedStudyBundle({
         run,
         actorId: actor,
         appUrl: evidenceAppUrl,
         dryRun,
         journey,
-        labId: plan.labId,
-        ...(plan.title ? { labTitle: plan.title } : {}),
+        studyId: plan.studyId,
+        ...(plan.title ? { studyTitle: plan.title } : {}),
         persona,
         scenarioSource: scenario.source,
         scenarioSourceDigest: scenario.sourceDigest,
@@ -116,7 +117,7 @@ export async function finishScriptedRun(inputs) {
     const finished = await run.finish(bundle);
     // Surface the local-fidelity posture so the operator knows the bundle is not publish-safe as-is.
     if (sessionResults.some((result) => result.trace.redaction.screenshots === "raw")) {
-        warnings.push("Screenshots are full-fidelity (raw) for local use — the bundle stays in gitignored .humanish and nothing scans these pixels; review them before sharing anywhere. policies.redactScreenshots is not yet supported on the scripted route.");
+        warnings.push("Screenshots are unblurred for local use: the bundle stays in the gitignored .humanish/ folder and nothing scans these pixels, so review them before sharing. policies.redactScreenshots is not supported on the scripted route yet.");
     }
     const observer = await finished.renderObserver();
     await validatePreparedRunArtifactPaths(runPaths);
@@ -135,10 +136,9 @@ export async function finishScriptedRun(inputs) {
     await finished.recordOutcome({ ok, execution });
     const harnessErrorSession = sessionResults.find((result) => result.completionReason === "harness_error");
     return {
-        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+        ...studyResultIdentity("scripted", plan.studyId),
         ok,
         cwd,
-        labId: plan.labId,
         actor,
         appUrl: evidenceAppUrl,
         dryRun,
@@ -167,13 +167,13 @@ export async function finishScriptedRun(inputs) {
             ? {}
             : {
                 error: {
-                    code: "HUMANISH_SCRIPTED_LAB_FAILED",
+                    code: "HUMANISH_SCRIPTED_FAILED",
                     message: sessionError ??
                         (observer.ok
                             ? harnessErrorSession
                                 ? `Scripted session ended with a harness error: ${harnessErrorSession.reason}`
-                                : "Scripted lab did not produce terminal sessions for every surface."
-                            : (observer.error?.message ?? "Observer failed for the scripted lab run.")),
+                                : "The scripted run did not produce terminal sessions for every surface."
+                            : (observer.error?.message ?? "Observer failed for the scripted run.")),
                 },
             }),
     };

package/dist/routes/scripted/route.d.ts

@@ -1,28 +1,28 @@
-import type { ScriptedPlan } from "../../lab/plan-types.js";
-import type { AdmittedPlan } from "../../run-lab.js";
+import type { ScriptedPlan } from "../../study/plan-types.js";
+import type { AdmittedPlan } from "../../run-study.js";
 import { type ScriptedRefusal } from "./plan.js";
-import { type RunScriptedBrowserLabOptions, type ScriptedBrowserLabResult, type ScriptedRunInput } from "./types.js";
+import { type RunScriptedBrowserStudyOptions, type ScriptedBrowserStudyResult, type ScriptedRunInput } from "./types.js";
 /**
  * The config-taking entry point. It plans, returns a refusal with the envelope the route has always
  * returned at that refusal's stage, and otherwise runs the plan.
  */
-export declare function runScriptedBrowserLab(options: RunScriptedBrowserLabOptions): Promise<ScriptedBrowserLabResult>;
+export declare function runScriptedBrowserStudy(options: RunScriptedBrowserStudyOptions): Promise<ScriptedBrowserStudyResult>;
 /**
- * A refused scripted lab's result, at the refusal's stage: a before-scope refusal has its own field
+ * A refused scripted study's result, at the refusal's stage: a before-scope refusal has its own field
  * order and no analysis record; the others come after the output directory checks.
  */
-export declare function scriptedLabRefusal(options: RunScriptedBrowserLabOptions, refusal: ScriptedRefusal): Promise<ScriptedBrowserLabResult>;
+export declare function scriptedStudyRefusal(options: RunScriptedBrowserStudyOptions, refusal: ScriptedRefusal): Promise<ScriptedBrowserStudyResult>;
 /**
- * runLab's step for a scripted plan. It takes no scorer, and its local checks (keys, a browser)
+ * runStudyWith's step for a scripted plan. It takes no scorer, and its local checks (keys, a browser)
  * run inside the run, so it returns the run.
  */
 export declare function admitScriptedPlan(plan: ScriptedPlan, input: ScriptedRunInput): AdmittedPlan<"scripted">;
 /**
  * Run a scripted plan. The run scope gives a direct library caller the same status-record lifetime
  * the CLI gets: returning from this function finalizes any record the run opened, whichever of its
- * fail-closed exits it took. Each route opens its own scope; `runLab` opens none. Without this a
+ * fail-closed exits it took. Each route opens its own scope; `runStudyWith` opens none. Without this a
  * test or an adopter calling the route directly leaves
  * the 5s cadence ticking into a directory something else is deleting, which surfaces as an
  * unrelated ENOTEMPTY.
  */
-export declare function runScriptedPlan(plan: ScriptedPlan, input: ScriptedRunInput): Promise<ScriptedBrowserLabResult>;
+export declare function runScriptedPlan(plan: ScriptedPlan, input: ScriptedRunInput): Promise<ScriptedBrowserStudyResult>;

package/dist/routes/scripted/route.js

@@ -10,7 +10,7 @@
 // against a real app (it fills forms and clicks buttons). A dry run parses and digest-pins the
 // scenario and writes the contract bundle without touching anything.
 //
-// Subject provenance (invariant 5): an app-url run declares that the lab did not provision the
+// Subject provenance: an app-url run declares that humanish did not provision the
 // subject, so its build provenance is unpinned and the evidence binds to the scenario digest. A
 // clone run records commit, env names, state provenance and a host digest, never the raw getHost
 // URL or a secret value.
@@ -24,42 +24,42 @@ import { buildRunSource } from "../../run/bundle.js";
 import { prepareSelectedOutputDirectory } from "../../run/contained-output.js";
 import { runScope } from "../../run/run.js";
 import { renderScriptedReviewMarkdown } from "./bundle.js";
-import { injectedBrowser, planScriptedLab } from "./plan.js";
+import { injectedBrowser, planScriptedStudy } from "./plan.js";
 import { finishScriptedRun } from "./result.js";
 import { UnsafeScriptedSessionResultError } from "./session-result.js";
 import { prepareScriptedRun } from "./setup.js";
 import { ScriptedSubject } from "./subject.js";
 import { runScriptedSessions, writeSurfaceTraces } from "./surface-sessions.js";
-import { SCRIPTED_BROWSER_LAB_SCHEMA, } from "./types.js";
+import {} from "./types.js";
+import { studyResultIdentity } from "../../run/study-result.js";
 /**
  * The config-taking entry point. It plans, returns a refusal with the envelope the route has always
  * returned at that refusal's stage, and otherwise runs the plan.
  */
-export async function runScriptedBrowserLab(options) {
+export async function runScriptedBrowserStudy(options) {
     const { config, dryRun, ...input } = options;
-    // planScriptedLab makes every configuration refusal, in the order this route always has.
-    const planned = planScriptedLab(config, {
+    // planScriptedStudy makes every configuration refusal, in the order this route always has.
+    const planned = planScriptedStudy(config, {
         dryRun,
         injectedBrowser: injectedBrowser(input.deps),
     });
     if (planned.ok)
         return runScriptedPlan(planned.plan, input);
-    return scriptedLabRefusal(options, planned.refusal);
+    return scriptedStudyRefusal(options, planned.refusal);
 }
 /**
- * A refused scripted lab's result, at the refusal's stage: a before-scope refusal has its own field
+ * A refused scripted study's result, at the refusal's stage: a before-scope refusal has its own field
  * order and no analysis record; the others come after the output directory checks.
  */
-export async function scriptedLabRefusal(options, refusal) {
+export async function scriptedStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
     const cwd = path.resolve(options.cwd);
     const actorType = config.actors[0]?.type ?? "";
     if (refusal.beforeScope)
         return {
-            schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+            ...studyResultIdentity("scripted", config.id),
             ok: false,
             cwd,
-            labId: config.id,
             actor: actorType,
             dryRun,
             runId: options.runId ?? "not-created",
@@ -72,10 +72,9 @@ export async function scriptedLabRefusal(options, refusal) {
     const physicalCwd = await realpath(cwd);
     await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
     const refused = {
-        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+        ...studyResultIdentity("scripted", config.id),
         ok: false,
         cwd,
-        labId: config.id,
         actor: refusal.actor ?? actorType,
         appUrl: refusal.appUrl ?? config.subject.appUrl ?? "",
         dryRun,
@@ -88,7 +87,7 @@ export async function scriptedLabRefusal(options, refusal) {
     return completeAutomaticAnalysis(refused, undefined, analysis.ok ? analysis.config : undefined, options, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
 }
 /**
- * runLab's step for a scripted plan. It takes no scorer, and its local checks (keys, a browser)
+ * runStudyWith's step for a scripted plan. It takes no scorer, and its local checks (keys, a browser)
  * run inside the run, so it returns the run.
  */
 export function admitScriptedPlan(plan, input) {
@@ -103,7 +102,7 @@ export function admitScriptedPlan(plan, input) {
 /**
  * Run a scripted plan. The run scope gives a direct library caller the same status-record lifetime
  * the CLI gets: returning from this function finalizes any record the run opened, whichever of its
- * fail-closed exits it took. Each route opens its own scope; `runLab` opens none. Without this a
+ * fail-closed exits it took. Each route opens its own scope; `runStudyWith` opens none. Without this a
  * test or an adopter calling the route directly leaves
  * the 5s cadence ticking into a directory something else is deleting, which surfaces as an
  * unrelated ENOTEMPTY.
@@ -126,7 +125,7 @@ async function runScriptedPlanInScope(plan, input, scope) {
         runId: input.runId,
         mintRunId: makeScriptedRunId,
         mode: dryRun ? "dry-run" : "live",
-        lab: plan.lab,
+        study: plan.study,
         renderReview: renderScriptedReviewMarkdown,
         observer: { open: input.open === true, render: setup.deps.renderObserver },
     });

package/dist/routes/scripted/scenario.d.ts

@@ -11,7 +11,7 @@ interface ResolvedScriptedScenario {
  * Resolve and consume `scenario.ref`. Path-style refs (contain a separator or end .yaml/.yml)
  * resolve against cwd and are clamped inside it: a ../../ escape is rejected, never recorded
  * as repo-relative provenance. Id-style refs must be public-safe tokens and resolve to
- * humanish/scenarios/<ref>.yaml (then .yml). Every failure mode is fail-closed. planScriptedLab
+ * humanish/scenarios/<ref>.yaml (then .yml). Every failure mode is fail-closed. planScriptedStudy
  * has already refused a missing or blank ref.
  */
 export declare function resolveScriptedScenario(projectRoot: PreparedSelectedOutputDirectory, ref: string): Promise<ResolvedScriptedScenario | {

package/dist/routes/scripted/scenario.js

@@ -1,4 +1,4 @@
-// Resolve a scripted-browser lab's `scenario.ref` to a committed scenario file and parse its
+// Resolve a scripted-browser study's `scenario.ref` to a committed scenario file and parse its
 // `browser.steps` into the journey the actor runs. The ref is an id or a repo-relative path that must
 // stay inside the project; provenance records it repo-relative with the scenario's digest.
 import { parse as parseYaml } from "yaml";
@@ -6,14 +6,14 @@ import path from "node:path";
 import { parseBrowserPersonaJourneyFromScenario } from "../../actors/scripted-browser/journey.js";
 import { digestText } from "../../evidence/redaction.js";
 import { readContainedRegularFile, } from "../../run/contained-output.js";
-// Same public-safe token shape the lab id uses; an id-style scenario.ref must match it before
+// Same public-safe token shape the study id uses; an id-style scenario.ref must match it before
 // it is interpolated into a repo path.
 const SCENARIO_REF_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 /**
  * Resolve and consume `scenario.ref`. Path-style refs (contain a separator or end .yaml/.yml)
  * resolve against cwd and are clamped inside it: a ../../ escape is rejected, never recorded
  * as repo-relative provenance. Id-style refs must be public-safe tokens and resolve to
- * humanish/scenarios/<ref>.yaml (then .yml). Every failure mode is fail-closed. planScriptedLab
+ * humanish/scenarios/<ref>.yaml (then .yml). Every failure mode is fail-closed. planScriptedStudy
  * has already refused a missing or blank ref.
  */
 export async function resolveScriptedScenario(projectRoot, ref) {
@@ -26,7 +26,7 @@ export async function resolveScriptedScenario(projectRoot, ref) {
         if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
             return {
                 ok: false,
-                message: `scenario.ref path must stay inside the target cwd (got "${trimmed}") — provenance is recorded repo-relative and an escaping path cannot be.`,
+                message: `scenario.ref must stay inside the project directory, and "${trimmed}" does not: the run records it relative to the project.`,
             };
         }
         source = relative.split(path.sep).join("/");
@@ -80,7 +80,7 @@ export async function resolveScriptedScenario(projectRoot, ref) {
     if (!parsed.journey) {
         return {
             ok: false,
-            message: `${source} declares no executable browser steps — the scripted-browser actor needs a scenario with browser.steps.`,
+            message: `${source} declares no browser steps, and the scripted-browser actor needs a scenario with browser.steps.`,
         };
     }
     return { ok: true, journey: parsed.journey, source, sourceDigest };

package/dist/routes/scripted/setup.d.ts

@@ -1,15 +1,15 @@
 import type { ActorPersonaRef } from "../../actors/contract.js";
 import type { BrowserPersonaJourney, ScriptedBrowserEvidenceUrlPolicy } from "../../actors/scripted-browser/types.js";
-import type { ScriptedPlan } from "../../lab/plan-types.js";
-import { type ScriptedBrowserLabResult, type ScriptedRunInput } from "./types.js";
-import type { LabDeps } from "../../lab/lab-deps.js";
+import type { ScriptedPlan } from "../../study/plan-types.js";
+import { type ScriptedBrowserStudyResult, type ScriptedRunInput } from "./types.js";
+import type { StudyDeps } from "../../study/study-deps.js";
 /** What setup hands the run: the plan's subject and scenario, keys and the browser to launch. */
 export interface ScriptedRunSetup {
     cwd: string;
     physicalCwd: string;
-    deps: LabDeps;
+    deps: StudyDeps;
     warnings: string[];
-    failed: (code: NonNullable<ScriptedBrowserLabResult["error"]>["code"], message: string) => ScriptedBrowserLabResult;
+    failed: (code: NonNullable<ScriptedBrowserStudyResult["error"]>["code"], message: string) => ScriptedBrowserStudyResult;
     clone: Extract<ScriptedPlan["subject"], {
         readonly kind: "clone";
     }> | undefined;
@@ -39,7 +39,7 @@ export interface ScriptedRunSetup {
  */
 export declare function prepareScriptedRun(plan: ScriptedPlan, input: ScriptedRunInput): Promise<{
     ok: false;
-    result: ScriptedBrowserLabResult;
+    result: ScriptedBrowserStudyResult;
 } | {
     ok: true;
     setup: ScriptedRunSetup;