humanish 0.108.0 → 0.109.1

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: 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,7 +24,7 @@ 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";
@@ -36,22 +36,22 @@ 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 ?? "";
@@ -87,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) {
@@ -102,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.
@@ -125,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) {

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;

package/dist/routes/scripted/setup.js

@@ -2,7 +2,7 @@
 // the E2B key and subject env of a live clone, a browser to launch) and the values the run reads
 // (the evidence URL policy, the scrubber for clone values, the persona and the session budget).
 import { realpath } from "node:fs/promises";
-import { missingKeys, missingSubjectEnv } from "../../lab/requirements.js";
+import { missingKeys, missingSubjectEnv } from "../../study/requirements.js";
 import path from "node:path";
 import { resolveBrowserCommand } from "../../actors/scripted-browser/browser-command.js";
 import { describeMissingKeys } from "../../keys/key-resolution.js";
@@ -28,7 +28,7 @@ export async function prepareScriptedRun(plan, input) {
     const clone = plan.subject.kind === "clone" ? plan.subject : undefined;
     const evidenceAppUrl = evidenceAppUrlOf(plan.subject);
     const failed = (code, message) => ({
-        ...studyResultIdentity("scripted", plan.labId),
+        ...studyResultIdentity("scripted", plan.studyId),
         ok: false,
         cwd,
         actor: plan.actor,
@@ -67,14 +67,14 @@ export async function prepareScriptedRun(plan, input) {
     if (missing.length > 0) {
         return {
             ok: false,
-            result: failed("HUMANISH_SCRIPTED_KEYS_MISSING", `Live clone scripted-browser labs require ${missing.join(" and ")} (dry-run remains $0 and does not provision a subject). ${describeMissingKeys(missing, env)}`),
+            result: failed("HUMANISH_SCRIPTED_KEYS_MISSING", `Live clone scripted-browser studies require ${missing.join(" and ")} (dry-run remains $0 and does not provision a subject). ${describeMissingKeys(missing, env)}`),
         };
     }
     const unsetSubjectEnv = missingSubjectEnv(plan.requirements, env);
     if (unsetSubjectEnv.length > 0) {
         return {
             ok: false,
-            result: failed("HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING", `Subject env values missing for live clone scripted-browser lab: ${unsetSubjectEnv.join(", ")}.`),
+            result: failed("HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING", `Subject env values missing for a live clone scripted-browser study: ${unsetSubjectEnv.join(", ")}.`),
         };
     }
     const surfaces = plan.surfaces;

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

@@ -1,9 +1,9 @@
-import type { ScriptedPlan } from "../../lab/plan-types.js";
+import type { ScriptedPlan } from "../../study/plan-types.js";
 import { type PreparedRunArtifactPaths } from "../../run/paths.js";
 import type { RunSubjectStateStepRecord } from "../../run/bundle.js";
 import { type DesktopResourceObservation } from "../../substrates/e2b/desktop-resources.js";
-import type { LabDeps } from "../../lab/lab-deps.js";
-import type { RunLabHomes } from "../../lab/run-lab-homes.js";
+import type { StudyDeps } from "../../study/study-deps.js";
+import type { RunStudyHomes } from "../../study/run-study-homes.js";
 type ScriptedCloneSubject = Extract<ScriptedPlan["subject"], {
     readonly kind: "clone";
 }>;
@@ -11,9 +11,9 @@ type ScriptedCloneSubject = Extract<ScriptedPlan["subject"], {
 export interface ScriptedSubjectInputs {
     plan: ScriptedPlan;
     clone: ScriptedCloneSubject;
-    deps: LabDeps;
+    deps: StudyDeps;
     /** Runs after the subject sandbox exists and before provisioning. */
-    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
+    prepareDesktop?: NonNullable<RunStudyHomes["prepareDesktop"]>;
     env: Readonly<Record<string, string | undefined>>;
     e2bApiKey: string;
     runPaths: PreparedRunArtifactPaths;

package/dist/routes/scripted/subject.js

@@ -1,4 +1,4 @@
-// The provisioned subject of a live clone scripted-browser lab: one E2B desktop that clones,
+// The provisioned subject of a live clone scripted-browser study: one E2B desktop that clones,
 // seeds and serves the app, exposed through a tokenless getHost URL and killed by exact id at
 // teardown.
 import { commandDigestOf } from "../../subject/state.js";
@@ -74,7 +74,7 @@ export class ScriptedSubject {
                 metadata: {
                     mode: "scripted-browser-lab",
                     tool: "humanish",
-                    labId: plan.labId,
+                    labId: plan.studyId,
                     kind: "subject",
                     actor: plan.actor,
                 },
@@ -115,7 +115,7 @@ export class ScriptedSubject {
             ...timers,
         });
         if (typeof subjectDesktop.getHost !== "function") {
-            throw new Error("the installed @e2b/desktop SDK does not expose getHost(port); clone scripted-browser labs require it to reach the provisioned subject");
+            throw new Error("the installed @e2b/desktop SDK does not expose getHost(port); clone scripted-browser studies require it to reach the provisioned subject");
         }
         const rawHost = subjectDesktop.getHost(servePort(clone.serve.url));
         const hostUrl = /^https?:\/\//i.test(rawHost) ? rawHost : `https://${rawHost}`;

package/dist/routes/scripted/surface-records.d.ts

@@ -10,7 +10,7 @@ export interface ScriptedSurfaceContext {
     appUrl: string;
     createdAt: string;
     journey: BrowserPersonaJourney;
-    labId: string;
+    studyId: string;
     persona: ActorPersonaRef;
     sessionError?: string;
 }

package/dist/routes/scripted/surface-records.js

@@ -30,14 +30,14 @@ export function scriptedSurfaceRecords(context, surface, index, result, screensh
         summary: result
             ? `Scripted-browser actor (${context.actorId}) replayed ${context.journey.scenarioId} on the ${surface.id} surface; ${result.completionReason}.`
             : context.sessionError !== undefined
-                ? `Scripted lab failed before a terminal session verdict: ${context.sessionError}`
+                ? `The scripted run failed before a terminal session verdict: ${context.sessionError}`
                 : `Scripted-browser actor (${context.actorId}) against ${context.appUrl}; no session ran.`,
         startedAt: context.createdAt,
         updatedAt: result?.capture.capturedAt ?? context.createdAt,
     });
     const stream = participantStream(ids, {
         kind: "browser",
-        label: `${surface.label} · ${context.labId}`,
+        label: `${surface.label} · ${context.studyId}`,
         status,
         transport: "snapshot",
         updatedAt: result?.capture.capturedAt ?? context.createdAt,

package/dist/routes/scripted/surface-sessions.d.ts

@@ -1,11 +1,11 @@
 import { type ScriptedBrowserSessionOptions, type ScriptedBrowserSessionResult } from "../../actors/scripted-browser/actor.js";
-import type { ScriptedPlan } from "../../lab/plan-types.js";
+import type { ScriptedPlan } from "../../study/plan-types.js";
 import { type PreparedRunArtifactPaths } from "../../run/paths.js";
-import type { LabDeps } from "../../lab/lab-deps.js";
+import type { StudyDeps } from "../../study/study-deps.js";
 /** One session per surface, in parallel. */
 export declare function runScriptedSessions(session: Required<Pick<ScriptedBrowserSessionOptions, "appUrl" | "evidenceAppUrl" | "urlPolicy" | "journey" | "persona" | "timeoutMs" | "artifactRoot">>, run: {
     surfaces: ScriptedPlan["surfaces"];
-    deps: LabDeps;
+    deps: StudyDeps;
     browserCommand: string | undefined;
     runPaths: PreparedRunArtifactPaths;
 }): Promise<ScriptedBrowserSessionResult[]>;

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

@@ -1,21 +1,21 @@
 import type { ActorCompletionReason, ActorStatus } from "../../actors/contract.js";
-import type { LabEvent } from "../../lab/run-lab-events.js";
+import type { StudyEvent } from "../../study/run-study-events.js";
 import type { AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
-import type { LabConfig } from "../../lab/types.js";
+import type { StudyConfig } from "../../study/types.js";
 import type { ObserverResult } from "../../observer/render.js";
 import type { RunSubjectProvenance } from "../../run/bundle.js";
-import type { LabDeps } from "../../lab/lab-deps.js";
-import type { RunLabHomes } from "../../lab/run-lab-homes.js";
+import type { StudyDeps } from "../../study/study-deps.js";
+import type { RunStudyHomes } from "../../study/run-study-homes.js";
 import { type StudyResultIdentity } from "../../run/study-result.js";
-/** What a scripted run takes besides its plan. The plan carries the config, dry run and lab. */
-export type ScriptedRunInput = Omit<RunScriptedBrowserLabOptions, "config" | "dryRun" | "lab">;
-export interface RunScriptedBrowserLabOptions {
+/** What a scripted run takes besides its plan. The plan carries the config, dry run and study. */
+export type ScriptedRunInput = Omit<RunScriptedBrowserStudyOptions, "config" | "dryRun">;
+export interface RunScriptedBrowserStudyOptions {
     /** Cancels post-run analysis only. */
     analysisSignal?: AbortSignal;
-    /** Reports the analysis window to onEvent; built by normalizeRunLabOptions. */
-    emit?: (event: LabEvent) => void;
+    /** Reports the analysis window to onEvent; built by normalizeRunStudyOptions. */
+    emit?: (event: StudyEvent) => void;
     cwd: string;
-    config: LabConfig;
+    config: StudyConfig;
     /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
     dryRun: boolean;
     open?: boolean;
@@ -23,20 +23,20 @@ export interface RunScriptedBrowserLabOptions {
     /** Keys and subject env for the run. Defaults to process.env. Values are scrubbed; names persist. */
     env?: Readonly<Record<string, string | undefined>>;
     /** Runs after a clone subject's sandbox exists and before provisioning. */
-    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
+    prepareDesktop?: NonNullable<RunStudyHomes["prepareDesktop"]>;
     /** Test seams: the browser, the session, the E2B module, timers, the renderer and the clock. */
-    deps?: LabDeps;
+    deps?: StudyDeps;
 }
-interface ScriptedBrowserLabSession {
+interface ScriptedBrowserStudySession {
     surface: string;
     status: ActorStatus;
     completionReason: ActorCompletionReason;
     reason: string;
     screenshots: number;
 }
-export interface ScriptedBrowserLabResult extends AutomaticAnalysisResult, StudyResultIdentity<"scripted"> {
+export interface ScriptedBrowserStudyResult extends AutomaticAnalysisResult, StudyResultIdentity<"scripted"> {
     /** True when the bundle verified and (dry-run, or every session reached a terminal verdict
-     * without a harness error). The subject failing the script is successful evidence, and the lab
+     * without a harness error). The subject failing the script is successful evidence, and the run
      * does not fail for it. */
     ok: boolean;
     cwd: string;
@@ -58,11 +58,11 @@ export interface ScriptedBrowserLabResult extends AutomaticAnalysisResult, Study
         sourceDigest: string;
         steps: number;
     };
-    sessions: ScriptedBrowserLabSession[];
+    sessions: ScriptedBrowserStudySession[];
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_SCRIPTED_FAILED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_BROWSER_MISSING" | "HUMANISH_SCRIPTED_KEYS_MISSING" | "HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_GETHOST_UNAVAILABLE" | "HUMANISH_RUN_ID_IN_USE";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_SCRIPTED_FAILED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_BROWSER_MISSING" | "HUMANISH_SCRIPTED_KEYS_MISSING" | "HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_GETHOST_UNAVAILABLE" | "HUMANISH_RUN_ID_IN_USE";
         message: string;
     };
 }

package/dist/routes/scripted/types.js

@@ -1,2 +1,2 @@
-// The scripted-browser lab's schema constant, options and result types.
+// The scripted-browser study's schema constant, options and result types.
 import {} from "../../run/study-result.js";

package/dist/routes/shared-world/bundle-records.js

@@ -1,7 +1,7 @@
 // Each participant's records in a concurrent shared-world bundle: its simulation, its stream and
 // its events, projected from the actor's run result (or from the declaration on a dry run or while
 // running).
-import { participantAssignment } from "../../lab/participant-assignment.js";
+import { participantAssignment } from "../../study/participant-assignment.js";
 import { participantEvent, participantRecord, participantStream, } from "../../run/participant-records.js";
 import { declaredScreenForRender } from "../../substrates/e2b/desktop-geometry.js";
 import { publicSafeRouteLabel } from "./provenance.js";
@@ -68,7 +68,7 @@ function sharedWorldSimulation(ctx, spec, index, view) {
     const { taxonomy, outcome, session } = view;
     return participantRecord(spec, index + 1, {
         personaId: spec.persona.id,
-        scenarioId: `concurrent-shared-world-${args.plan.labId}`,
+        scenarioId: `concurrent-shared-world-${args.plan.studyId}`,
         status: view.status,
         streamKind: "browser",
         mode: "browser-sim",
@@ -93,7 +93,7 @@ function sharedWorldStream(ctx, spec, index, view) {
             ? {}
             : { assignment: participantAssignment(spec.evidenceAssignment) }),
         kind: "browser",
-        label: `Concurrent persona ${spec.planned.id}${taxonomy} · ${args.plan.labId}`,
+        label: `Concurrent persona ${spec.planned.id}${taxonomy} · ${args.plan.studyId}`,
         status: view.status,
         transport: "snapshot",
         updatedAt: args.run.createdAt,

package/dist/routes/shared-world/bundle.js

@@ -14,6 +14,7 @@ import { hostOriginDigest } from "./provenance.js";
 import { participantEvent, participantIds } from "../../run/participant-records.js";
 import { sharedWorldParticipantRecords } from "./bundle-records.js";
 import { CONCURRENT_ATTRIBUTION_LIMITS, EXTERNAL_PUBLIC_ATTRIBUTION_LIMITS, } from "./types.js";
+import { plural } from "../../run/text.js";
 /** Max windows live at the same instant (sweep over start/end points). The simultaneity
  *  count: the participant count says how many existed; this says how many ever ran at once. */
 export function maxSimultaneousWindows(windows) {
@@ -86,7 +87,7 @@ function formatSharedWorldActorOutcomes(outcomes, expectedCount) {
         .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
         .map(([reason, count]) => `${reason} ${count}/${expectedCount}`)
         .join(", ");
-    return `${passedSessions}/${expectedCount} actor session(s) passed credibility checks; mission endpoint: ${goalSatisfiedSessions}/${expectedCount} ended goal_satisfied; completion reasons: ${completionReasons}`;
+    return `${passedSessions}/${plural(expectedCount, "actor session")} passed credibility checks; mission endpoint: ${goalSatisfiedSessions}/${expectedCount} ended goal_satisfied; completion reasons: ${completionReasons}`;
 }
 /** The run's first two events: its creation and the shared plane's provenance. */
 function planeEvents(args, external) {
@@ -97,7 +98,7 @@ function planeEvents(args, external) {
         at: createdAt,
         level: "info",
         type: "concurrent-shared-world.run.created",
-        message: `Created a concurrent shared-world run for ${plan.labId} (actor ${descriptor.id}, ${actorSpecs.length} persona(s) on one shared app, at most ${plan.concurrency} at once).`,
+        message: `Created a concurrent shared-world run for ${plan.studyId} (actor ${descriptor.id}, ${plural(actorSpecs.length, "persona")} on one shared app, at most ${plan.concurrency} at once).`,
     });
     // Human-readable plane label, byte-stable for the clone route. local-tree has no repo slug: it
     // labels the packed archive instead (archiveSha256 + dirty/clean when the packed root was a git
@@ -111,7 +112,7 @@ function planeEvents(args, external) {
     // External-public plane provenance differs: an operator-declared, operator-owned public
     // deployment humanish neither provisioned nor seeded, with no getHost, no clone and no synthetic
     // attestation (claiming synthetic on a real site is a lie). The origin persists digest-only.
-    // planSharedWorldLab refuses an external-public plane without a declared owner; the fallback
+    // planSharedWorldStudy refuses an external-public plane without a declared owner; the fallback
     // says so rather than naming one.
     const externalPlaneOwner = plan.plane.kind === "external-public" ? plan.plane.owner : "(undeclared)";
     events.push(participantEvent(actorSpecs[0] ?? participantIds(0), {
@@ -120,7 +121,7 @@ function planeEvents(args, external) {
         level: "info",
         type: "concurrent-shared-world.plane.provenance",
         message: external
-            ? `Shared app: a public deployment the operator declares they own (${externalPlaneOwner}, authorized), used as it is, with no sandbox, clone or seed. humanish observed that each participant reached the declared origin (publicOriginDigest); it did not create or control the app. Ownership is the lab's declaration, and the data is not claimed to be synthetic.`
+            ? `Shared app: a public deployment the operator declares they own (${externalPlaneOwner}, authorized), used as it is, with no sandbox, clone or seed. humanish observed that each participant reached the declared origin (publicOriginDigest); it did not create or control the app. Ownership is the study's declaration, and the data is not claimed to be synthetic.`
             : dryRun
                 ? `Shared app declared: ${dryRunPlaneLabel}, to be served in the sandbox at a public sandbox URL (dry run: nothing ${args.subject.source === "local-tree" ? "packed" : "cloned"}). Seed recipe ${args.seedDigest}; synthetic subject, as the study declares; env names: ${args.subject.envNames?.join(", ") || "none"} (values never stored).`
                 : `Shared app: ${livePlaneLabel}, served at a public sandbox URL humanish created; seed recipe ${args.seedDigest}; synthetic subject, as the study declares; env names: ${args.subject.envNames?.join(", ") || "none"} (values never stored).`,
@@ -249,7 +250,7 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
     const deltas = (stateSeries ?? []).filter((snapshot, i) => i > 0 && snapshot.digest !== (stateSeries ?? [])[i - 1].digest).length;
     const stateSeriesLabel = external
         ? "stateSeries omitted (no authoritative shared-state proof on the external-public plane)"
-        : `stateSeries ${(stateSeries ?? []).length} snapshot(s), ${deltas} delta(s)`;
+        : `stateSeries ${plural((stateSeries ?? []).length, "snapshot")}, ${plural(deltas, "delta")}`;
     const convergenceLabel = external
         ? `; lobby convergence ${args.lobbyConvergenceDigest ? "shown (all participants reached one /lobby/CODE)" : "not observed"}`
         : "";
@@ -262,7 +263,7 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
         at: createdAt,
         level: "info",
         type: "concurrent-shared-world.concurrency",
-        message: `Concurrency: ${windows.length} participant(s)${dryRun ? " (dry run; $0)" : `, up to ${maxLive} live at once (cap ${capForReport}), overlap ${overlaps ? "shown" : "not observed"}`}; ${stateSeriesLabel}${convergenceLabel}. Attribution ceiling: ${sharedWorld.attributionLimits.join(", ")}. ${dryRun ? "This dry run proves nothing about live concurrency, scale, or adoption." : "This run reports only its own observed overlap and state changes; it does not prove scale, repeatability, or adopter-harness replacement."}`,
+        message: `Concurrency: ${plural(windows.length, "participant")}${dryRun ? " (dry run; $0)" : `, up to ${maxLive} live at once (cap ${capForReport}), overlap ${overlaps ? "shown" : "not observed"}`}; ${stateSeriesLabel}${convergenceLabel}. Attribution ceiling: ${sharedWorld.attributionLimits.join(", ")}. ${dryRun ? "This dry run proves nothing about live concurrency, scale, or adoption." : "This run reports only its own observed overlap and state changes; it does not prove scale, repeatability, or adopter-harness replacement."}`,
     });
     // The judge's verdict (judgeSharedWorld): every participant produced a terminal, engaged, passed
     // session. Mission endpoint and completion reasons are reported separately below; `outcomes[].ok`
@@ -277,13 +278,13 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
         // report "state delta(s) under load" (live). It reports lobby convergence instead.
         summary: dryRun
             ? external
-                ? `Concurrent shared-world dry run: ${actorSpecs.length} persona(s) declared against one public deployment, used as it is (no sandbox, clone or seed); no sandboxes launched, $0 spent.`
-                : `Concurrent shared-world dry run: ${actorSpecs.length} persona(s) declared against one app served at a public sandbox URL (${descriptor.id}); no sandboxes launched, $0 spent.`
+                ? `Concurrent shared-world dry run: ${plural(actorSpecs.length, "persona")} declared against one public deployment, used as it is (no sandbox, clone or seed); no sandboxes launched, $0 spent.`
+                : `Concurrent shared-world dry run: ${plural(actorSpecs.length, "persona")} declared against one app served at a public sandbox URL (${descriptor.id}); no sandboxes launched, $0 spent.`
             : inProgress
-                ? `In-progress concurrent shared-world Observer snapshot: ${actorSpecs.length} persona(s) running against one shared app; final verification is pending.`
+                ? `In-progress concurrent shared-world Observer snapshot: ${plural(actorSpecs.length, "persona")} running against one shared app; final verification is pending.`
                 : external
                     ? `Concurrent shared-world (one public deployment, ${actorSpecs.length} personas at once): swarm ${verdict === "pass" ? "ran coherently" : "did not run coherently"}; ${actorOutcomeSummary}; overlap ${overlaps ? "proven" : "not observed"}; ${args.lobbyConvergenceDigest ? `${actorSpecs.length} participants converged on one lobby` : "lobby convergence not observed"}.`
-                    : `Concurrent shared-world (one shared app, ${actorSpecs.length} personas at once): swarm ${verdict === "pass" ? "ran coherently" : "did not run coherently"}; ${actorOutcomeSummary}; overlap ${overlaps ? "proven" : "not observed"}; ${deltas} state delta(s) under load.`,
+                    : `Concurrent shared-world (one shared app, ${actorSpecs.length} personas at once): swarm ${verdict === "pass" ? "ran coherently" : "did not run coherently"}; ${actorOutcomeSummary}; overlap ${overlaps ? "proven" : "not observed"}; ${plural(deltas, "state delta")} under load.`,
         gaps: dryRun
             ? [
                 "This dry run launched no concurrent shared-world session; it checks the evidence shape only, not live behavior, scale, or adopter-harness replacement.",
@@ -333,16 +334,16 @@ export function buildConcurrentSharedWorldBundle(args) {
         persona: {
             id: actorSpecs[0]?.persona.id ?? "concurrent-persona",
             name: `Concurrent shared-world swarm (${actorSpecs.length} personas)`,
-            source: `study:${plan.labId}`,
+            source: `study:${plan.studyId}`,
             sourceDigest: actorSpecs[0]?.persona.promptDigest ?? args.seedDigest,
         },
         scenario: {
-            id: `concurrent-shared-world-${plan.labId}`,
-            title: plan.title ?? `Concurrent shared-world: ${plan.labId}`,
+            id: `concurrent-shared-world-${plan.studyId}`,
+            title: plan.title ?? `Concurrent shared-world: ${plan.studyId}`,
             goal: redactText(actorSpecs[0]?.evidenceInstructions ??
                 actorSpecs[0]?.instructions ??
                 "Concurrent shared-world interaction."),
-            source: `study:${plan.labId}`,
+            source: `study:${plan.studyId}`,
             sourceDigest: actorSpecs[0]?.persona.promptDigest ?? args.seedDigest,
         },
         lifecycle: [

package/dist/routes/shared-world/checkpoints.d.ts

@@ -1,6 +1,6 @@
 import type { Shell } from "../../substrates/shell.js";
 import { type DetachedTimers } from "../../substrates/detached.js";
-import { type LabSubjectState, type LabSubjectStateCheckpoint } from "../../lab/types.js";
+import { type StudySubjectState, type StudySubjectStateCheckpoint } from "../../study/types.js";
 import { type SharedWorldCheckpoint } from "../../run/shared-world-evidence.js";
 /** Combine a snapshot's per-probe digests into one sha256-16 (digest-only; no raw value). */
 export declare function combineCheckpointDigest(parts: string[]): string;
@@ -15,11 +15,11 @@ export declare function runCheckpointSnapshot(args: {
     shell: Shell;
     snapshotIndex: number;
     name: string;
-    checkpoints: LabSubjectStateCheckpoint[];
+    checkpoints: StudySubjectStateCheckpoint[];
     prevDigest: string | undefined;
     scrub: (text: string) => string;
     requestTimeoutMs: number;
     timers: DetachedTimers;
 }): Promise<SharedWorldCheckpoint>;
 /** sha256-16 over the ordered seed-step command digests: the seeded-state recipe identity. */
-export declare function seedRecipeDigest(state: LabSubjectState | undefined): string;
+export declare function seedRecipeDigest(state: StudySubjectState | undefined): string;

package/dist/routes/shared-world/checkpoints.js

@@ -1,7 +1,7 @@
 import { commandDigestOf } from "../../subject/state.js";
 import { SUBJECT_DIR } from "../../subject/steps.js";
 import { runDetachedStep } from "../../substrates/detached.js";
-import {} from "../../lab/types.js";
+import {} from "../../study/types.js";
 import { redactText } from "../../evidence/redaction.js";
 import {} from "../../run/shared-world-evidence.js";
 // Per-checkpoint probe budget (read-only aggregate probes are fast).

package/dist/routes/shared-world/comms.d.ts

@@ -1,18 +1,18 @@
 import { type ReceivingSource } from "../../comms/receiving-runtime.js";
-import type { SharedWorldPlan } from "../../lab/plan-types.js";
+import type { SharedWorldPlan } from "../../study/plan-types.js";
 import type { CommsReceivingRun } from "../../comms/receiving.js";
 import { type DeployedCommsCatch } from "../../comms/sandbox-catch.js";
-import type { LabCommsEmail, LabConfig } from "../../lab/types.js";
+import type { StudyCommsEmail, StudyConfig } from "../../study/types.js";
 import type { Shell } from "../../substrates/shell.js";
 import type { ConcurrentSharedWorldPlaneClass, ExternalCommsWiring, PlaneContext } from "./types.js";
-/** The in-sandbox email catch a provisioned plane deploys, when the lab declares one. */
+/** The in-sandbox email catch a provisioned plane deploys, when the study declares one. */
 export interface SubjectComms {
-    email: LabCommsEmail | undefined;
+    email: StudyCommsEmail | undefined;
     port: number | undefined;
     /** The catch's base URL, injected into the subject sandbox's env at create. */
     env: Record<string, string>;
 }
-export declare function subjectCommsOf(config: Pick<LabConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass): SubjectComms;
+export declare function subjectCommsOf(config: Pick<StudyConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass): SubjectComms;
 /**
  * Adopter-hosted ingress: on the external-public plane the harness provisions nothing, so
  * it cannot host a catch. The operator can, and then humanish still does every other part of
@@ -21,7 +21,7 @@ export declare function subjectCommsOf(config: Pick<LabConfig, "comms">, planeCl
  * the previously-inert block into a working one. Returns an error message when the declared catch
  * does not answer as a humanish catch.
  */
-export declare function prepareExternalComms(config: Pick<LabConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass, dryRun: boolean, warnings: string[], env: Record<string, string | undefined>): Promise<{
+export declare function prepareExternalComms(config: Pick<StudyConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass, dryRun: boolean, warnings: string[], env: Record<string, string | undefined>): Promise<{
     ok: true;
     wiring: ExternalCommsWiring | undefined;
 } | {
@@ -36,7 +36,7 @@ export declare function prepareExternalComms(config: Pick<LabConfig, "comms">, p
  * never blocks teardown (invariant: all sandboxes torn down by id in the plane's finally). Returns
  * the thread's path when one was written.
  */
-export declare function drainSubjectComms(ctx: PlaneContext, commsEmail: LabCommsEmail, subjectShell: Shell, deployedComms: DeployedCommsCatch): Promise<string | undefined>;
+export declare function drainSubjectComms(ctx: PlaneContext, commsEmail: StudyCommsEmail, subjectShell: Shell, deployedComms: DeployedCommsCatch): Promise<string | undefined>;
 /**
  * Adopter-hosted drain: same routing and digest-only artifact as the in-sandbox
  * catch. Only the transport differs (HTTP GET /deliveries against the catch the operator
@@ -44,10 +44,10 @@ export declare function drainSubjectComms(ctx: PlaneContext, commsEmail: LabComm
  * masks the run's own outcome. Returns the thread's path when one was written.
  */
 export declare function drainExternalComms(ctx: PlaneContext, comms: ExternalCommsWiring): Promise<string | undefined>;
-/** What receiving guards: the lab's email declaration and the subject env names and values. */
+/** What receiving guards: the study's email declaration and the subject env names and values. */
 export declare function receivingSourceOf(residual: SharedWorldPlan["residual"], env: readonly string[]): ReceivingSource;
 /**
- * Real email receiving, when the lab declares it on a live run. It registers the connection's
+ * Real email receiving, when the study declares it on a live run. It registers the connection's
  * secrets with the run's scrub before any desktop starts. Returns the message the run fails with
  * when setup fails.
  */

package/dist/routes/shared-world/comms.js

@@ -7,7 +7,8 @@ import { prepareReceivingRun } from "../../comms/receiving-runtime.js";
 import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, externalCatchHealthy, externalInboxUrl, } from "../../comms/sandbox-catch.js";
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { writeContainedOutputFile } from "../../run/contained-output.js";
-import { addressedRecipients } from "../../lab/parse/comms.js";
+import { addressedRecipients } from "../../study/parse/comms.js";
+import { plural } from "../../run/text.js";
 // Off-app comms: on the provisioned-getHost plane the harness owns the one subject sandbox, so
 // it can redirect the app's email-API sends into an in-sandbox catch and evidence them. Gated entirely
 // on config.comms: no comms declared → zero change. The base-URL env is injected into the subject
@@ -52,7 +53,7 @@ export async function prepareExternalComms(config, planeClass, dryRun, warnings,
             code: "HUMANISH_SHARED_WORLD_COMMS_TOKEN_INVALID",
             message: tokenRefusal,
         };
-    // Fail closed before any actor sandbox is created: a comms lab whose catch is unreachable
+    // Fail closed before any actor sandbox is created: a comms study whose catch is unreachable
     // collects nothing while every participant still spends. The probe asserts our service marker in
     // /health, so an adopter's proxy answering 200 for everything cannot pass for a catch.
     if (!dryRun && !(await externalCatchHealthy(externalComms))) {
@@ -91,7 +92,7 @@ export async function drainSubjectComms(ctx, commsEmail, subjectShell, deployedC
             return "comms/thread.json";
         }
         else if (collected.captured > 0) {
-            warnings.push(`The email catch captured ${collected.captured} email send(s), but none matched a declared recipient inbox, so no email evidence was written. Set comms.email.recipients[].address to the address the app sends to.`);
+            warnings.push(`The email catch captured ${plural(collected.captured, "email send")}, but none matched a declared recipient inbox, so no email evidence was written. Set comms.email.recipients[].address to the address the app sends to.`);
         }
         else {
             // Zero captures is the silent-broken shape: the app never posted to the catch.
@@ -120,7 +121,7 @@ export async function drainExternalComms(ctx, comms) {
     ctx.warnings.push(...warnings);
     return path;
 }
-/** What receiving guards: the lab's email declaration and the subject env names and values. */
+/** What receiving guards: the study's email declaration and the subject env names and values. */
 export function receivingSourceOf(residual, env) {
     const { comms } = residual;
     const { envValues } = residual.subject;
@@ -130,7 +131,7 @@ export function receivingSourceOf(residual, env) {
     };
 }
 /**
- * Real email receiving, when the lab declares it on a live run. It registers the connection's
+ * Real email receiving, when the study declares it on a live run. It registers the connection's
  * secrets with the run's scrub before any desktop starts. Returns the message the run fails with
  * when setup fails.
  */