humanish 0.106.1 → 0.108.0

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

@@ -1,36 +1,32 @@
+import type { LabDeps } from "../../lab/lab-deps.js";
+import type { LabEvent } from "../../lab/run-lab-events.js";
+import type { RunLabHomes } from "../../lab/run-lab-homes.js";
 import type { SharedWorldJudgment } from "../../run/judge.js";
-import type { CuaActorSessionOptions } from "../../actors/computer-use/actor.js";
-import type { CuaLoopResult } from "../../actors/computer-use/loop.js";
-import type { BrowserLabAdapterHooks } from "../../lab/adapter-extension.js";
-import type { SubjectPhaseEvent } from "../../subject/steps.js";
-import type { DetachedTimers } from "../../substrates/detached.js";
-import type { E2BDesktopModule, E2BDesktopSandbox } from "../../substrates/e2b/sdk.js";
-import type { AutomaticAnalysisHooks, AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
+import type { BrowserScorer } from "../../lab/adapter-extension.js";
+import type { AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
 import type { CuaActorDescriptor } from "../../actors/registry.js";
 import type { CommsReceivingRun } from "../../comms/receiving.js";
 import type { LabCommsEmail, LabCommsExternal, LabConfig } from "../../lab/types.js";
 import type { DesktopResourceObservation } from "../../substrates/e2b/desktop-resources.js";
-import type { ObserverResult, renderObserver } from "../../observer/render.js";
+import type { ObserverResult } from "../../observer/render.js";
 import type { ObserverRuntimeStreamUrl } from "../../observer/run-routes.js";
-import type { RunBundle, RunScorerProvenance, RunSubjectProvenance, RunSubjectStateStepRecord } from "../../run/bundle.js";
+import type { BundleRun, RunBundle, RunScorerProvenance, RunSubjectProvenance, RunSubjectStateStepRecord } from "../../run/bundle.js";
 import type { RunScope } from "../../run/run.js";
 import type { SharedWorldStateSnapshot } from "../../run/shared-world-evidence.js";
 import type { LocalTreeArchive } from "../../subject/local-tree-archive.js";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { LiveTraceFlush } from "../computer-use/live-flush.js";
 import type { CuaParticipantDeps, DesktopParticipantRun, CuaRunBudget, ParticipantRunOutcome } from "../computer-use/types.js";
 import type { ProvisionedPlaneSetup } from "./provisioned.js";
 import type { SharedWorldPlan } from "../../lab/plan-types.js";
-export declare const CONCURRENT_SHARED_WORLD_LAB_SCHEMA = "humanish.concurrent-shared-world-lab-result.v1";
+import { type StudyResultIdentity } from "../../run/study-result.js";
 export declare const CONCURRENT_SHARED_WORLD_PROVIDER_METADATA: {
     readonly mode: "concurrent-shared-world-lab";
     readonly tool: "humanish";
 };
 export declare const CONCURRENT_ATTRIBUTION_LIMITS: readonly ["concurrent", "best-effort-causal-attribution", "non-deterministic-shared-state", "window-and-snapshot-granularity", "contention-observed-not-proven-safe", "state-change-not-isolated-to-actors"];
 export interface RunConcurrentSharedWorldLabOptions {
-    automaticAnalysis?: AutomaticAnalysisHooks;
-    /** Which manifest produced this run (#455); threaded into the status record + bundle. */
-    lab?: RunLabProvenance;
+    /** Cancels post-run analysis only. */
+    analysisSignal?: AbortSignal;
     cwd: string;
     config: LabConfig;
     /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
@@ -40,27 +36,45 @@ export interface RunConcurrentSharedWorldLabOptions {
     onObserverReady?: (observer: ObserverResult & {
         ok: true;
     }) => Promise<void> | void;
-    hooks?: SharedWorldLabHooks;
-    /** Present only when the browser-route scorer hooks were CONFIG-DECLARED and loaded by the CLI
-     *  (#316); core-stamped onto the bundle as evidence. Absent for library callers. */
+    /** Keys and subject env for the run. Defaults to process.env. */
+    env?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Runs after a sandbox exists and before anything is provisioned on it: the provisioned plane's
+     * subject sandbox, then each participant's desktop. The external-public plane has participants
+     * only.
+     */
+    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
+    /** Awaited after a participant's live stream starts, and again after its sandbox is gone. */
+    onStream?: NonNullable<RunLabHomes["onStream"]>;
+    /** Reports subject phases to onEvent; built by normalizeRunLabOptions. */
+    emit?: (event: LabEvent) => void;
+    /** Test seams. */
+    deps?: LabDeps;
+    /** Scores the assembled evidence: `RunLabOptions.scorer`, or the scorer the CLI loads. */
+    scorer?: BrowserScorer;
+    /** Present only when the scorer was config-declared and loaded by the CLI;
+     *  core-stamped onto the bundle as evidence. Absent for library callers. */
     scorerProvenance?: RunScorerProvenance;
 }
 /** What a shared-world run takes besides its plan. The plan carries the config, dry run and lab. */
 export type SharedWorldRunInput = Omit<RunConcurrentSharedWorldLabOptions, "config" | "dryRun" | "lab">;
-export type ConcurrentSharedWorldLabErrorCode = "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_CONFLICT" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_INVALID" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_KEYS_MISSING"
-/** A local-agent brain's CLI is not on PATH. */
- | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_AGENT_MISSING"
+export type ConcurrentSharedWorldLabErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_SHARED_WORLD_FAILED" | "HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED" | "HUMANISH_SHARED_WORLD_INVALID" | "HUMANISH_SHARED_WORLD_KEYS_MISSING"
+/** A local-agent brain's CLI is not on `PATH`. */
+ | "HUMANISH_SHARED_WORLD_AGENT_MISSING"
 /** A local-agent brain's CLI is signed out, or could not report its sign-in status. */
- | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_AGENT_SIGNIN_REQUIRED"
+ | "HUMANISH_SHARED_WORLD_AGENT_SIGNIN_REQUIRED"
 /** A dollar cap that cannot be priced: an unpriced model, or a ChatGPT-account Codex brain. */
- | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_UNPRICED_CAP" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_GETHOST_UNAVAILABLE" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_HANDOFF_TIMEOUT" | "HUMANISH_RUN_ID_IN_USE"
-/** A declared adopter-hosted comms catch (#328) did not answer as a humanish catch — fail closed
- *  BEFORE any actor spend, since the funnel would silently collect nothing. */
- | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_CATCH_UNREACHABLE";
-/** The two plane classes of the concurrent shared-world route (#164 phase 2). */
+ | "HUMANISH_SHARED_WORLD_UNPRICED_CAP" | "HUMANISH_SHARED_WORLD_SUBJECT_ENV_MISSING" | "HUMANISH_SHARED_WORLD_GETHOST_UNAVAILABLE" | "HUMANISH_SHARED_WORLD_HANDOFF_TIMEOUT" | "HUMANISH_RUN_ID_IN_USE"
+/** A declared adopter-hosted comms catch did not answer as a humanish catch. Fail closed
+ *  before any actor spend, since the funnel would silently collect nothing. */
+ | "HUMANISH_SHARED_WORLD_COMMS_CATCH_UNREACHABLE"
+/** comms.email.external.authTokenEnv names a token shorter than MIN_CATCH_TOKEN_LENGTH or not
+ *  well-formed Unicode (src/comms/external-evidence.ts). Refused before the catch is probed. */
+ | "HUMANISH_SHARED_WORLD_COMMS_TOKEN_INVALID";
+/** The two plane classes of the concurrent shared-world route. */
 export type ConcurrentSharedWorldPlaneClass = "provisioned-getHost" | "external-public";
 export declare const EXTERNAL_PUBLIC_ATTRIBUTION_LIMITS: readonly ["concurrent", "best-effort-causal-attribution", "non-deterministic-shared-state", "window-and-snapshot-granularity", "contention-observed-not-proven-safe", "state-change-not-isolated-to-actors", "external-public-plane", "operator-attested-target-not-harness-controlled", "no-synthetic-attestation", "no-authoritative-shared-state-proof", "concurrency-by-temporal-co-occupancy-only"];
-/** One persona's OUTCOME against the contended world (the "M of N" headline). */
+/** One persona's outcome against the contended world (the "M of N" headline). */
 export interface ConcurrentSharedWorldParticipantResult {
     id: string;
     index: number;
@@ -88,15 +102,13 @@ export interface ConcurrentSharedWorldParticipantResult {
         message: string;
     };
 }
-export interface ConcurrentSharedWorldLabResult extends AutomaticAnalysisResult {
-    schema: typeof CONCURRENT_SHARED_WORLD_LAB_SCHEMA;
+export interface ConcurrentSharedWorldLabResult extends AutomaticAnalysisResult, StudyResultIdentity<"shared-world"> {
     ok: boolean;
     cwd: string;
-    labId: string;
     actor: string;
     topology: "shared-world";
     topologyMode: "concurrent";
-    /** The DECLARED number of persona seats. */
+    /** The declared number of personas. */
     roleCount: number;
     /** Effective in-flight bound (execution.concurrency). */
     concurrency: number;
@@ -104,17 +116,17 @@ export interface ConcurrentSharedWorldLabResult extends AutomaticAnalysisResult
     runId: string;
     /** The harness-minted getHost URL the actors drove (tokenless; live only). */
     host?: string;
-    /** The ONE subject sandbox lifecycle proof. */
+    /** The one subject sandbox lifecycle proof. */
     subjectSandbox?: {
         sandboxId: string;
         killed: boolean;
     };
     /** Whether ≥2 actor windows overlapped in time (proven concurrency; live only). */
     overlapProven?: boolean;
-    /** Max lanes observed live at the same instant (live only) — the honest simultaneity number; a
-     *  6-lane run capped at 3 reports 3 here, never 6 (#350). */
+    /** Max participants observed live at the same instant (live only): the simultaneity number; a
+     *  6-participant run capped at 3 reports 3 here, never 6. */
     maxSimultaneousLanes?: number;
-    /** Subject provenance (invariant 5): the ONE shared plane. */
+    /** Subject provenance: the one shared plane. */
     subject?: RunSubjectProvenance;
     roles: ConcurrentSharedWorldParticipantResult[];
     observer?: ObserverResult;
@@ -145,11 +157,12 @@ type StartedRun = Extract<Awaited<ReturnType<RunScope["startRun"]>>, {
 export interface PlaneContext {
     plan: SharedWorldPlan;
     input: SharedWorldRunInput;
-    /** Read by the computer-use lane runner, whose hooks and desktop setup take the whole config.
-     *  Seats, their count and their host and entry come from the plan's participants. */
+    /** Read for the subject's serve URL, which each participant's subject names. Participants, their
+     *  count and their host and entry come from the plan's participants. */
     config: LabConfig;
     descriptor: CuaActorDescriptor;
-    hooks: SharedWorldLabHooks;
+    /** The run's test seams; empty outside tests. */
+    deps: LabDeps;
     env: Record<string, string | undefined>;
     concurrency: number;
     runBudget: CuaRunBudget | undefined;
@@ -157,6 +170,9 @@ export interface PlaneContext {
     openaiApiKey: string;
     e2bApiKey: string;
     scrubKnownValues: (text: string) => string;
+    /** The values scrubKnownValues removes. Real email receiving adds its secrets before participants
+     *  start. */
+    knownSecretValues: readonly string[];
     cwd: string;
     run: StartedRun;
     runId: string;
@@ -175,8 +191,9 @@ export interface PlaneContext {
     warnings: string[];
 }
 /**
- * What the seats feed while they run. A plane sets the attached Observer and starts the trace
- * flush; the runtime stream hooks append stream URLs; the orchestrator reads all three at finish.
+ * What the participants feed while they run. A plane sets the attached Observer and starts the
+ * trace flush; each participant's onStream appends stream URLs; the orchestrator reads all three at
+ * finish.
  */
 export interface LiveParticipants {
     observer?: ObserverResult & {
@@ -185,7 +202,7 @@ export interface LiveParticipants {
     flush?: LiveTraceFlush;
     readonly streamUrls: ObserverRuntimeStreamUrl[];
 }
-/** An adopter-hosted comms catch (#328) and the inbox its personas open. */
+/** An adopter-hosted comms catch and the inbox its personas open. */
 export interface ExternalCommsWiring {
     external: LabCommsExternal;
     email: LabCommsEmail;
@@ -195,14 +212,12 @@ export interface ExternalCommsWiring {
 export interface ConcurrentBundleArgs {
     /** The run's judgment (judgeSharedWorldRun over the other fields). */
     judgment: SharedWorldJudgment;
-    /** Lab provenance for the bundle\'s own `lab` field (#455). */
-    lab?: RunLabProvenance;
+    /** The run this bundle belongs to; the bundle head reads its id, mode, start and lab. */
+    run: BundleRun;
     plan: SharedWorldPlan;
     descriptor: CuaActorDescriptor;
-    createdAt: string;
     dryRun: boolean;
     inProgress?: boolean;
-    runId: string;
     source: RunBundle["source"];
     actorSpecs: DesktopParticipantRun[];
     actorResults: ActorRunResult[];
@@ -213,17 +228,18 @@ export interface ConcurrentBundleArgs {
     hostDigest?: string;
     /** Run-level digest-only comms-thread evidence path (humanish.comms-thread.v1), when a comms lab
      *  captured mail into the subject sandbox's catch. Registered on the first persona stream (it is a
-     *  property of the ONE shared app, not of any single persona). */
+     *  property of the one shared app, and belongs to no single persona). */
     commsArtifactPath?: string;
-    /** #164 phase 2: the plane-class discriminator (default provisioned-getHost, byte-stable). */
+    /** The plane-class discriminator (default provisioned-getHost, byte-stable). */
     planeClass?: ConcurrentSharedWorldPlaneClass;
-    /** external-public only: sha256-16 of the OBSERVED origin the seats converged on (the convergence
-     *  proof — what the seats actually reached, tolerant of a declared->observed redirect). */
+    /** external-public only: sha256-16 of the observed origin the participants converged on (the
+     *  convergence proof: what the participants actually reached, tolerant of a declared->observed
+     *  redirect). */
     publicOriginDigest?: string;
-    /** external-public only: sha256-16 of the operator-DECLARED plane origin (evidence/reference only;
-     *  NOT asserted equal to the observed origin — a cross-origin redirect is normal and expected). */
+    /** external-public only: sha256-16 of the operator-declared plane origin (evidence/reference only;
+     *  never asserted equal to the observed origin, since a cross-origin redirect is normal). */
     declaredOriginDigest?: string;
-    /** external-public only: sha256-16 of the shared /lobby/CODE path all seats converged on. */
+    /** external-public only: sha256-16 of the /lobby/CODE path all participants converged on. */
     lobbyConvergenceDigest?: string;
     runError?: string;
     /** The provisioned plane's own desktop; absent on external-public planes and dry runs. */
@@ -236,6 +252,8 @@ export interface PlaneResults {
     subjectCommit: string | undefined;
     subjectSandboxId: string | undefined;
     subjectKilled: boolean;
+    /** The subject sandbox's scrubbed release warning when its release is unconfirmed. */
+    subjectReleaseWarning: string | undefined;
     subjectDesktop: SubjectDesktopUsage | undefined;
     getHostUrl: string | undefined;
     publicOriginDigest: string | undefined;
@@ -262,93 +280,4 @@ export interface FinishFacts {
     stateSnapshots: SharedWorldStateSnapshot[];
     declaredOriginDigest: string | undefined;
 }
-/**
- * Library-level hooks mirroring CuaActorLabHooks — the DI seams that let CI drive the FULL
- * orchestration with fakes at $0/zero-network. The fake desktop module records create/kill BY id
- * and exposes NO `list` method (the by-id teardown rail is then provable by construction).
- */
-export interface SharedWorldLabHooks extends BrowserLabAdapterHooks {
-    /** Lazy-load the E2B desktop module (tests inject a fake; default loadE2BDesktopModule). */
-    loadDesktopModule?: () => Promise<E2BDesktopModule>;
-    /**
-     * Runs after a sandbox is created and before anything is provisioned on it. The provisioned
-     * plane calls it for the subject sandbox with no lane, then for each seat's desktop with its lane;
-     * the external-public plane calls it for the seats only.
-     */
-    prepareDesktop?: (desktop: E2BDesktopSandbox, lane?: {
-        laneId: string;
-        laneIndex: number;
-        laneCount: number;
-    }) => Promise<void>;
-    /**
-     * Awaited after a seat's live desktop stream starts. The URL carries an auth key and must never
-     * be persisted. A rejection becomes a run warning, as on the computer-use route.
-     */
-    onRuntimeStreamReady?: (stream: {
-        laneId: string;
-        sandboxId: string;
-        simId: string;
-        streamId: string;
-        url: string;
-    }) => Promise<void> | void;
-    /** Awaited after a seat's sandbox is gone, for seats whose stream started. Rejections are swallowed. */
-    onRuntimeStreamEnded?: (stream: {
-        laneId: string;
-        simId: string;
-        streamId: string;
-    }) => Promise<void> | void;
-    /** The per-seat computer-use session runner (default: the resolved actor descriptor's). */
-    runSession?: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
-    /** The operator environment (keys + subject env values). Defaults to process.env. */
-    env?: Record<string, string | undefined>;
-    renderObserverFn?: typeof renderObserver;
-    /** Injected clock/sleep for the detached-step polling (tests only). */
-    detachedTimers?: DetachedTimers;
-    /**
-     * Subject-provisioning phase sink (mirrors CuaActorLabHooks.onPhase): one call per
-     * started/completed boundary during the ONE shared-plane provision (clone route: clone, install,
-     * build, serve start, ready, subject.state seed-step groups; local-tree route: upload, extract,
-     * install, build, serve start, ready, seed-step groups - no clone phase). Defaults to one stderr
-     * line per event. Override in tests to capture instead of writing to real stderr.
-     */
-    onPhase?: (event: SubjectPhaseEvent) => void;
-    /**
-     * CONCURRENT route only (#164 phase 2): the harness clock used to MEASURE each actor's laneWindow
-     * [start,end] (default Date.now). The deterministic heart test does NOT override this — overlap is
-     * produced by a rendezvous latch in the fake runSession + measured by the REAL clock (FIX-1), so
-     * the windows are real, not injected. (A test may override only for non-overlap assertions.)
-     */
-    now?: () => number;
-    /** CONCURRENT route only: the background stateSeries prober cadence (ms). Default 1000. */
-    proberCadenceMs?: number;
-    /**
-     * EXTERNAL-PUBLIC concurrent route only (#164 phase 2): the host-first handoff barrier deadline
-     * (ms). The host seat must surface a shared-session (/lobby/CODE) URL within this budget or the run
-     * fails closed with HUMANISH_CONCURRENT_SHARED_WORLD_LAB_HANDOFF_TIMEOUT and no follower opens.
-     * Default 120000 (also capped by execution.timeoutMs). Tests inject a short value to exercise the
-     * fail-closed path deterministically.
-     */
-    handoffDeadlineMs?: number;
-    /**
-     * EXTERNAL-PUBLIC concurrent route only: the vision reader that extracts a /lobby/CODE off a seat's
-     * screenshot frame (the CDP-independent handoff relay + per-seat convergence observation). Defaults to
-     * the real single-frame OpenAI read (readLobbyCodeFromFrame). Tests inject a fake so the barrier's
-     * handoff + convergence proof can be exercised deterministically without a live vision call.
-     */
-    readLobbyCodeFromFrame?: (frame: Buffer, apiKey: string) => Promise<string | undefined>;
-    /**
-     * Local-tree packing DI seam (tests only, no npm dependency needed to exercise the route):
-     * defaults to createLocalTreeArchive(root, opts) plus a host-side read of the produced archive
-     * file into an ArrayBuffer (the SAME default routes/computer-use/route.ts uses). Called ONCE per run, before
-     * the ONE shared-plane sandbox is created, on the live local-tree route.
-     */
-    packLocalTree?: (args: {
-        root: string;
-        extraExclude?: string[];
-        maxArchiveBytes?: number;
-    }) => Promise<{
-        archive: LocalTreeArchive;
-        buffer: ArrayBuffer;
-    }>;
-}
 export {};

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

@@ -1,11 +1,11 @@
 // The concurrent shared-world route's schema constants, attribution limits, options and result
-// types, and the per-seat result the planes collect.
-export const CONCURRENT_SHARED_WORLD_LAB_SCHEMA = "humanish.concurrent-shared-world-lab-result.v1";
+// types, and the per-participant result the planes collect.
+import {} from "../../run/study-result.js";
 export const CONCURRENT_SHARED_WORLD_PROVIDER_METADATA = {
     mode: "concurrent-shared-world-lab",
     tool: "humanish",
 };
-// The verify-enforced CONCURRENT attribution ceiling (FIX-5). Mirrored in
+// The verify-enforced concurrent attribution ceiling. Mirrored in
 // verify/shared-world-concurrent.ts CONCURRENT_REQUIRED_LIMITS.
 export const CONCURRENT_ATTRIBUTION_LIMITS = [
     "concurrent",
@@ -15,8 +15,8 @@ export const CONCURRENT_ATTRIBUTION_LIMITS = [
     "contention-observed-not-proven-safe",
     "state-change-not-isolated-to-actors",
 ];
-// EXTERNAL-PUBLIC plane class: the honest-downgrade attribution ceiling. The concurrent family
-// (an honest ceiling) PLUS the mandatory external-public disclosures — mirrored in the required
+// External-public plane class: the downgraded attribution ceiling. The concurrent family
+// plus the mandatory external-public disclosures, mirrored in the required
 // set in verify/shared-world-concurrent.ts (CONCURRENT_ATTRIBUTION_LIMITS +
 // EXTERNAL_PUBLIC_EXTRA_LIMITS). Verify fails closed on a missing one.
 export const EXTERNAL_PUBLIC_ATTRIBUTION_LIMITS = [

package/dist/routes/terminal/adapter.d.ts

@@ -1,27 +1,27 @@
 import type { ActorTrace } from "../../actors/contract.js";
 import { type RunBundle, type RunScorerProvenance } from "../../run/bundle.js";
 import { type ScorerOutcome } from "../../lab/adapter-extension.js";
-import type { TerminalLedgers, TerminalProductLabHooks } from "./types.js";
+import type { TerminalLedgers, TerminalScorer } from "./types.js";
 /**
- * Run the layer-6 product-adapter extension seam (issue #154 acceptance #8) over the assembled
- * evidence and attach its results to the bundle IN PLACE — without core knowing any product noun.
+ * Run the product-adapter extension seam over the assembled
+ * evidence and attach its results to the bundle in place, without core knowing any product noun.
  * The review is not touched here: the returned failures are folded into it by the caller.
  *
  *  - `score`: when present, the returned namespaced `RunAdapterScore` lands on `bundle.adapterScore`.
- *    For a LIBRARY caller (no `scorerProvenance`), the adapter score is additive and never a
- *    failure. For a CONFIG-DECLARED scorer (#316; `scorerProvenance` present), a status:"fail" is a
- *    failure (the keystone lane is the product's own definition of pass/fail), and so is a scorer
- *    that THROWS or returns a malformed value, so a crashed declared gate is never a silent green.
+ *    For a library caller (no `scorerProvenance`), the adapter score is additive and never a
+ *    failure. For a config-declared scorer (`scorerProvenance` present), a status:"fail" is a
+ *    failure (the keystone route is the product's own definition of pass/fail), and so is a scorer
+ *    that throws or returns a malformed value, so a crashed declared gate is never a silent green.
  *  - `deriveFeedback`: when present, the returned candidates are appended to
  *    `bundle.feedbackCandidates`; each carries its own namespaced `adapter` product-noun block.
  *
  * Defense in depth: the adapter's namespaced payloads are re-serialized through the run's scrub +
- * redact, and any candidate / score that does not satisfy core's exported shape is DROPPED with a
+ * redact, and any candidate / score that does not satisfy core's exported shape is dropped with a
  * warning (a malformed adapter output never poisons a verifiable bundle). The bundle verifier
  * re-checks the surviving shapes downstream, so the seam stays fail-closed end to end.
  */
 export declare function applyAdapterExtensionSeam(args: {
-    hooks: TerminalProductLabHooks;
+    scorer: TerminalScorer | undefined;
     bundle: RunBundle;
     trace: ActorTrace;
     ledgers: TerminalLedgers;
@@ -31,7 +31,7 @@ export declare function applyAdapterExtensionSeam(args: {
     runId: string;
     sanitize: (text: string) => string;
     warnings: string[];
-    /** Present only when the scorer was CONFIG-DECLARED (#316) — the "declared" marker that opts the
+    /** Present only when the scorer was config-declared. It is the "declared" marker that opts the
      *  terminal route into flip-on-fail. Absent for library callers (additive, back-compat). */
     scorerProvenance?: RunScorerProvenance;
 }): Promise<ScorerOutcome>;