humanish 0.106.1 → 0.108.0

package/dist/run/bundle-shape.js

@@ -47,14 +47,14 @@ export function isRunBundle(value) {
         (value.subject === undefined || isRunSubjectProvenance(value.subject)) &&
         (value.desktopBrowser === undefined || isDesktopBrowserEvidence(value.desktopBrowser)) &&
         (value.rerun === undefined || isRunRerunLineage(value.rerun)) &&
-        // Optional shared-world fields. Tolerant SHAPE guard only; the interaction semantics
+        // Optional shared-world fields. Tolerant shape guard only; the interaction semantics
         // (timeline well-formedness, single-plane, delta-on-pass) are the verify check's job.
         (value.attributionClass === undefined ||
             value.attributionClass === "isolated" ||
             value.attributionClass === "shared-world") &&
         (value.sharedWorld === undefined || isSharedWorldEvidence(value.sharedWorld)) &&
         // Optional, adapter-namespaced product score (the extension seam). When present, validate only
-        // its SHAPE; core never reads the adapter's `data` payload.
+        // its shape; core never reads the adapter's `data` payload.
         (value.adapterScore === undefined || isRunAdapterScore(value.adapterScore)) &&
         // Optional scorer provenance. Library callers may omit it; when present it must be
         // well-shaped.
@@ -156,9 +156,9 @@ function isDesktopBrowserEvidence(value) {
 }
 /** Short lowercase-hex content digest (digestText default is 12 chars; tolerate longer future digests). */
 const SCORER_DIGEST_PATTERN = /^[a-f0-9]{12,64}$/;
-/** Shape guard for RunScorerProvenance (#316), mirroring isRunSubjectProvenance: tolerated-absent in
+/** Shape guard for RunScorerProvenance, mirroring isRunSubjectProvenance: tolerated-absent in
  *  isRunBundle, well-shaped when present. Semantics (does the digest still match the file) are not a
- *  verify concern — the block is core-stamped evidence of what was loaded, not a re-execution proof. */
+ *  verify concern: the block is core-stamped evidence of what was loaded and proves no re-execution. */
 function isRunScorerProvenance(value) {
     return (isRecord(value) &&
         value.schema === "humanish.scorer-provenance.v1" &&
@@ -171,7 +171,7 @@ function isRunScorerProvenance(value) {
         value.exports.length > 0 &&
         value.exports.every((name) => name === "score" || name === "deriveFeedback" || name === "deriveArtifacts"));
 }
-function isRunAdapterScore(value) {
+export function isRunAdapterScore(value) {
     return (isRecord(value) &&
         value.schema === "humanish.adapter-score.v1" &&
         typeof value.namespace === "string" &&
@@ -182,8 +182,8 @@ function isRunAdapterScore(value) {
         typeof value.summary === "string" &&
         (value.data === undefined || isRecord(value.data)));
 }
-// The local-tree archive content pin: sha256 hex, full 64 chars (NOT the repo's 16-char
-// display-digest convention -- this value is the provenance pin itself, persisted in full).
+// The local-tree archive content pin: sha256 hex, full 64 chars (unlike the repo's 16-char
+// display-digest convention; this value is the provenance pin itself, persisted in full).
 export const ARCHIVE_SHA256_PATTERN = /^[a-f0-9]{64}$/;
 function isRunSubjectProvenance(value) {
     if (!isRecord(value))

package/dist/run/bundle.d.ts

@@ -1,7 +1,7 @@
 import type { CommsReceivingEvidence } from "../comms/receiving-types.js";
 import { type CapturedGitState } from "./git-state.js";
 import type { SharedWorldEvidence } from "./shared-world-evidence.js";
-import type { RunLabProvenance } from "./status.js";
+import { type RunStudyProvenance } from "./study-provenance.js";
 import type { RunSimulationStatus, RunStream, RunStreamKind } from "./streams.js";
 export declare const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v1";
 /** The run bundle file, relative to the run directory. */
@@ -10,17 +10,17 @@ export declare const REVIEW_SCHEMA = "humanish.review.v1";
 export declare const PUBLIC_TARGET_CWD = "[target-cwd]";
 /**
  * A namespaced, product-agnostic score a thin adapter attaches to the bundle via a route's `score`
- * hook, on terminal-product or a browser route (the layer-6 extension seam, issue #154 acceptance
- * #8). Core never reads its `data` and knows none of the adopter's nouns — the `namespace` (e.g.
+ * hook, on terminal-product or a browser route (the adapter extension seam).
+ * Core never reads its `data` and knows none of the adopter's nouns: the `namespace` (e.g.
  * `"acme-pixelforge"`) scopes the whole record so core schemas stay product-agnostic and a future
  * inert-field audit does not misfire on a noun core never owned. The adopter's real scorecard
- * (component weights, product rubric) lives in ITS repo and is summarized into the generic
- * status/score/summary; everything product-specific rides under `data`. This is NOT a built-in
- * product scorer — it is the SEAM the adopter's scorer plugs into without forking core.
+ * (component weights, product rubric) lives in the adopter's repo and is summarized into the generic
+ * status/score/summary; everything product-specific rides under `data`. Core ships no built-in
+ * product scorer; this is the seam the adopter's scorer plugs into without forking core.
  */
 export interface RunAdapterScore {
     schema: "humanish.adapter-score.v1";
-    /** The adapter's namespace — non-core, product-scoped (e.g. an adopter slug). Required + non-empty. */
+    /** The adapter's namespace: non-core, product-scoped (e.g. an adopter slug). Required + non-empty. */
     namespace: string;
     status: "pass" | "partial" | "fail";
     /** A 0-100 summary the adapter derived from its own (off-core) rubric. */
@@ -56,20 +56,19 @@ export interface RunFeedbackCandidate {
     proposed_next_state: "watch" | "adapter-hardening" | "target-app-setup" | "actor-auth" | "setup-quality-review" | "study-quality-review";
     acceptance_proof: string[];
     /**
-     * OPTIONAL, ADAPTER-NAMESPACED product-noun block (the layer-6 extension seam, issue #154
-     * acceptance #8 + the "record product-specific concepts as NON-core nouns" list). A thin adapter
-     * records product-specific concepts — public CLI/product command observed, hosted product
+     * Optional, adapter-namespaced product-noun block (the adapter extension seam). A thin adapter
+     * records product-specific concepts: public CLI/product command observed, hosted product
      * success-or-blocker, feedback id/draft observed, media/job/asset ids, explicit
-     * no-media/no-provider-spend proof, defection/friction risk — WITHOUT making any of them core
+     * no-media/no-provider-spend proof, defection/friction risk, without making any of them core
      * primitives. They ride under a single namespaced field so core's feedback enums
      * (`evidence.kind`, `proposed_next_state`) stay product-agnostic and a future inert-field audit
-     * never misfires on a noun core never owned. Core validates only the SHAPE (a non-empty
+     * never misfires on a noun core never owned. Core validates only the shape (a non-empty
      * `namespace` + a `data` record); the keys inside `data` are the adapter's, never core's.
      */
     adapter?: {
         /** Non-core, product-scoped namespace (e.g. an adopter slug). Required + non-empty. */
         namespace: string;
-        /** The adapter's product nouns. Core never reads these keys — it stays product-agnostic. */
+        /** The adapter's product nouns. Core never reads these keys, so it stays product-agnostic. */
         data: Record<string, unknown>;
     };
 }
@@ -87,21 +86,21 @@ export interface RunAdapterArtifact {
     note: string;
 }
 /**
- * Provenance for a CONFIG-DECLARED adopter scorer (#316): the repo-relative entry path and a digest
- * of its ENTRY-MODULE bytes, recorded so a `review.scorer.ref`/`--scorer` run honestly states which
- * out-of-tree judgment it attached. Core-computed (path + digest), never adopter-supplied. A LIBRARY
- * caller (hooks passed directly through RunLabOptions) has implicit provenance — their code IS their
- * provenance — so this block is ABSENT there and every pre-#316 bundle stays byte-stable + verifiable.
+ * Provenance for a config-declared adopter scorer: the repo-relative entry path and a digest
+ * of its entry-module bytes, recorded so a `review.scorer.ref`/`--scorer` run states which
+ * out-of-tree judgment it attached. Core-computed (path + digest), never adopter-supplied. A library
+ * caller (hooks passed directly through RunLabOptions) has implicit provenance, because its code is its
+ * provenance, so this block is absent there and every older bundle stays byte-stable + verifiable.
  *
- * The digest pins the entry file's IDENTITY, not its behavioral closure: a `export { score } from
+ * The digest pins the entry file's identity only; modules it loads are outside it: a `export { score } from
  * "../outside.mjs"` re-export is not captured, and `import()` re-opens the path (a benign same-author
- * TOCTOU). Treat it as evidence-not-gate, and do NOT extend the loader to less-trusted config.
+ * TOCTOU). Treat it as evidence-not-gate, and do not extend the loader to less-trusted config.
  */
 export interface RunScorerProvenance {
     schema: "humanish.scorer-provenance.v1";
     /** Repo-relative entry path (e.g. "scorers/example.mjs"), clamped inside the target cwd. */
     ref: string;
-    /** digestText over the readContainedRegularFile ENTRY bytes — the entry module only, not a lockfile of the executed graph. */
+    /** digestText over the readContainedRegularFile entry bytes: the entry module only, with no lockfile of the executed graph. */
     digest: string;
     /** Which door declared it: the committed manifest, or the CLI `--scorer` override. */
     source: "manifest" | "cli-flag";
@@ -135,7 +134,7 @@ export interface RunEvent {
 /**
  * One executed (or declared) subject-state seed step. Live records carry execution fields
  * (ok/exitCode/timedOut/durationMs); dry-run "declared, not run" records carry only the
- * declaration (name, phase, command DIGEST). The command itself never persists — the digest
+ * declaration (name, phase, command digest). The command itself never persists; the digest
  * pins "same recipe" across bundles while the lab YAML in the consumer's repo stays the
  * plaintext source of truth (publish-safe by construction).
  */
@@ -151,8 +150,8 @@ export interface RunSubjectStateStepRecord {
     durationMs?: number;
 }
 /**
- * Structured subject provenance (invariant 5): what the subject WAS — code pin (repo/commit,
- * or a local-tree archive digest) AND state story. Optional additive field on
+ * Structured subject provenance: what the subject was, as a code pin (repo/commit,
+ * or a local-tree archive digest) and state story. Optional additive field on
  * humanish.run-bundle.v1; absent on bundles from backends that have not adopted it (and on all
  * pre-existing bundles).
  */
@@ -165,7 +164,7 @@ export interface RunSubjectProvenance {
     commit?: string;
     /**
      * Local-tree-route only (additive): 64 lowercase-hex sha256 over the sorted packed-entries
-     * list (docs/contracts/schemas.md). This is the provenance PIN for the local-tree route: a
+     * list (docs/contracts/schemas.md). This is the provenance pin for the local-tree route: a
      * dirty working tree cannot be commit-pinned, so the archive content digest stands in for it.
      */
     archiveSha256?: string;
@@ -174,21 +173,21 @@ export interface RunSubjectProvenance {
      * at pack time. Absent when the packed root was not a git work tree at all.
      */
     dirty?: boolean;
-    /** Declared env NAMES provisioned for the subject — names only, values never. */
+    /** Declared env names provisioned for the subject; names only, never values. */
     envNames?: string[];
     state: {
         /**
-         * seeded: live run, steps declared, ALL ran ok, no external state declared.
-         * unpinned: external state declared (seed records, if any, still attached — migrating
+         * seeded: live run, steps declared, all ran ok, no external state declared.
+         * unpinned: external state declared (seed records, if any, still attached; migrating
          *   an external DB is still unpinned overall).
-         * declared-not-run: steps declared but not (all) executed ok — dry-run contract bundles
+         * declared-not-run: steps declared but not (all) executed ok: dry-run contract bundles
          *   and failed live provisioning.
-         * undeclared: no subject.state block (stateless apps, app-url subjects) — the explicit
-         *   "absence declared" marker invariant 5 requires.
-         * external-public: (#164 phase 2) an operator-DECLARED, operator-OWNED public deployment used
-         *   directly as the shared plane — humanish neither provisioned nor seeded it (no getHost, no
-         *   clone, no in-sandbox filesystem). NOT "seeded" (nothing was seeded), NOT "unpinned" (this is
-         *   an owned target, not an uncontrolled external DB). The honest marker for the external-public
+         * undeclared: no subject.state block (stateless apps, app-url subjects), the explicit
+         *   "absence declared" marker that provenance requires when there is none.
+         * external-public: an operator-declared, operator-owned public deployment used
+         *   directly as the shared plane; humanish neither provisioned nor seeded it (no getHost, no
+         *   clone, no in-sandbox filesystem). It is not "seeded" (nothing was seeded) and not "unpinned" (this is
+         *   an owned target, not an uncontrolled external DB). The marker for the external-public
          *   plane class; verify asserts it in place of the getHost seeded gate.
          */
         provenance: "seeded" | "unpinned" | "declared-not-run" | "undeclared" | "external-public";
@@ -197,10 +196,10 @@ export interface RunSubjectProvenance {
     };
 }
 /**
- * How well a run attributed INTERACTION between actors — a new, ORTHOGONAL honesty axis to the
+ * How well a run attributed interaction between actors: a separate evidence axis, orthogonal to the
  * persona-sampling evidence classes (which answer "how representative is the actor?"). Absent ==
- * `isolated` (every existing bundle byte-stable). `shared-world` means N roles drove ONE mutable
- * plane and their per-role attribution is weaker (its ceiling is pinned in `sharedWorld.attributionLimits`).
+ * `isolated` (every existing bundle byte-stable). `shared-world` means N participants drove one
+ * mutable plane and their per-participant attribution is weaker (its ceiling is pinned in `sharedWorld.attributionLimits`).
  */
 type RunAttributionClass = "isolated" | "shared-world";
 export interface RunBundle {
@@ -254,20 +253,20 @@ export interface RunBundle {
     };
     review: ReviewSummary;
     feedbackCandidates: RunFeedbackCandidate[];
-    /** Structured subject provenance (invariant 5). Optional and additive: emitted by the
+    /** Structured subject provenance. Optional and additive: emitted by the
      * computer-use and shared-world backends and the clone scripted-browser route; tolerated absent
      * everywhere else. */
     subject?: RunSubjectProvenance;
     /**
-     * The custom E2B desktop TEMPLATE (image) the run's sandbox(es) actually launched on, from
-     * `execution.desktop.template` — so the evidence shows WHICH image ran (a subject needing
+     * The custom E2B desktop template (image) the run's sandbox(es) actually launched on, from
+     * `execution.desktop.template`, so the evidence shows which image ran (a subject needing
      * runtimes the stock `desktop` image lacks runs on an adopter's template). Optional + additive:
      * present only when a template was configured (absent == the stock `desktop` template, every
      * pre-existing bundle byte-stable). A template name is public-safe (not a secret).
      */
     desktopTemplate?: string;
     /**
-     * Browser family requested for hosted desktop actor lanes and the in-sandbox command that opened
+     * Browser family requested for hosted desktop participants and the in-sandbox command that opened
      * it, when explicitly configured. Optional + additive; absent means the historical default opener
      * path was used or the backend does not create a headed desktop.
      */
@@ -275,7 +274,7 @@ export interface RunBundle {
         requested: "default" | "chrome" | "chromium" | "firefox";
         resolved?: string;
         /**
-         * Synthetic media devices the browser was launched with (#509): the camera feed's origin and
+         * Synthetic media devices the browser was launched with: the camera feed's origin and
          * in-sandbox path, how the permission dialog is answered, and the exact flags.
          */
         media?: {
@@ -291,13 +290,13 @@ export interface RunBundle {
         };
     };
     /**
-     * Optional lineage for a run that intentionally re-executes selected lanes from a prior
-     * multi-lane run. This keeps retry-like workflows explicit: the new run is linked to the old
+     * Optional lineage for a run that intentionally re-executes selected participants from a
+     * prior multi-participant run. This keeps retry-like workflows explicit: the new run is linked to the old
      * evidence, but it never mutates or silently "fixes" the original verdict.
      */
     rerun?: RunRerunLineage;
     /**
-     * The interaction-attribution honesty axis (#164). Absent == `isolated` (every existing bundle
+     * The interaction-attribution evidence axis. Absent == `isolated` (every existing bundle
      * byte-stable). Set to `shared-world` by the shared-world backend, paired with `sharedWorld`.
      */
     attributionClass?: RunAttributionClass;
@@ -307,20 +306,20 @@ export interface RunBundle {
      */
     sharedWorld?: SharedWorldEvidence;
     /**
-     * OPTIONAL, ADAPTER-NAMESPACED product score (the layer-6 extension seam, issue #154 acceptance
-     * #8). A thin adapter's `score` hook returns a `RunAdapterScore`; the lane attaches it here
-     * WITHOUT core knowing any product noun (the score is namespaced + its breakdown lives in `data`).
+     * Optional, adapter-namespaced product score (the adapter extension seam).
+     * A thin adapter's `score` hook returns a `RunAdapterScore`; the route attaches it here
+     * without core knowing any product noun (the score is namespaced + its breakdown lives in `data`).
      * The default mission-based verdict (`review`) is unchanged when no scorer hook is given.
      */
     adapterScore?: RunAdapterScore;
     /**
-     * OPTIONAL provenance for a CONFIG-DECLARED scorer (#316). Present only when the scorer was loaded
-     * from `review.scorer.ref` / `--scorer`; absent for library callers and every pre-#316 bundle
+     * Optional provenance for a config-declared scorer. Present only when the scorer was loaded
+     * from `review.scorer.ref` / `--scorer`; absent for library callers and every older bundle
      * (tolerated-absent in isRunBundle so those still verify). Evidence, not a gate.
      */
     scorerProvenance?: RunScorerProvenance;
     /**
-     * OPTIONAL, ADAPTER-NAMESPACED product/state proof artifacts. Core validates
+     * Optional, adapter-namespaced product/state proof artifacts. Core validates
      * shape and local relative artifact references, then verifies the referenced
      * files exist. The adapter owns the payload schema under `namespace`.
      */
@@ -332,38 +331,41 @@ export interface RunBundle {
      */
     providerResources?: RunProviderResource[];
     /**
-     * Which lab manifest produced this run (#455). Optional + additive: absent on every bundle
-     * written before this contract and on library callers who pass a LabConfig directly (the run is
-     * then honestly lab-less rather than guessed). For older bundles a reader may fall back to
-     * `inferLegacyLabId`, which reads only the historical `persona.source = "lab:<id>"` convention.
+     * Which study file produced this run. Absent on a bundle written before this field and on a
+     * library caller's run (the run then has no study id rather than a guessed one). Read it, and
+     * `lab` and the source convention of older bundles, through studyProvenanceOf.
      */
-    lab?: RunLabProvenance;
+    study?: RunStudyProvenance;
+    /** `study`'s value, written beside it until 0.109. */
+    lab?: RunStudyProvenance;
     /**
-     * OPTIONAL, ADDITIVE run-level cost ESTIMATE (humanish.run-cost-summary.v1): the sum of every
-     * lane's model-token estimate PLUS the E2B desktop-minute estimate, carrying the SAME
+     * Optional, additive run-level cost estimate (humanish.run-cost-summary.v1): the sum of every
+     * participant's model-token estimate plus the E2B desktop-minute estimate, carrying the same
      * null-discipline the terminal cost ledger already ships. Absent on pre-existing bundles and
-     * dry runs; a live run that spends nothing records an explicit zero with no lines. Every dollar figure here is an ESTIMATE,
+     * dry runs; a live run that spends nothing records an explicit zero with no lines. Every dollar figure here is an estimate,
      * never an authoritative charge; verify asserts its LABELING/provenance, never its magnitude.
      */
     cost?: RunCostSummary;
 }
 /**
- * One contributing cost line of a RunCostSummary. A line is PRESENT even when it cannot be priced
- * (records that we TRIED and could not) — an unpriceable line carries estimatedCostUsd: null + a
- * `reason` and contributes NOTHING to the summary total (invariant 5). `estimatedCostUsd` is NEVER
+ * One contributing cost line of a RunCostSummary. A line is present even when it cannot be priced
+ * (it records that we tried and could not): an unpriceable line carries estimatedCostUsd: null + a
+ * `reason` and contributes nothing to the summary total. `estimatedCostUsd` is never
  * coerced to 0.
  */
 export interface RunCostLine {
     kind: "model-tokens" | "desktop-minutes";
     laneId?: string;
     modelId?: string;
-    /** null = NOT MEASURED / no rate; never coerced to 0. */
+    /** null = not measured / no rate; never coerced to 0. */
     estimatedCostUsd: number | null;
     reason?: "no_rate_for_model" | "no_rate_for_desktop" | "no_token_usage" | "no_duration" | "closing_usage_unreported" | "interaction_usage_unreported" | "no_desktop_resources" | "desktop_lifetime_incomplete" | "account_billing_unknown";
     /** Pricing provenance date; non-null iff estimatedCostUsd is non-null. */
     ratesAsOf: string | null;
     source?: string;
     placeholder?: boolean;
+    /** A model-tokens line priced from runtime-turn totals at the base tier (ActorEstimatedCost). */
+    basis?: "aggregated_turns_base_rate";
     /** Optional allocation evidence on newer desktop lines; older aggregate lines remain valid. */
     desktop?: {
         minutes: number | null;
@@ -378,15 +380,15 @@ export interface RunCostLine {
     };
 }
 /**
- * The run-level cost ESTIMATE. `estimatedTotalUsd` is the rounded sum of ONLY the non-null
- * `breakdown` lines; it is null iff EVERY line is null (never 0-coerced). `fullyEstimated` is
- * false when any applicable line is null (the total is then a LOWER BOUND). Every non-null dollar
+ * The run-level cost estimate. `estimatedTotalUsd` is the rounded sum of only the non-null
+ * `breakdown` lines; it is null iff every line is null (never 0-coerced). `fullyEstimated` is
+ * false when any applicable line is null (the total is then a lower bound). Every non-null dollar
  * figure carries `ratesAsOf`; `placeholder` is true when any contributing rate is a stand-in.
  */
 export interface RunCostSummary {
     schema: "humanish.run-cost-summary.v1";
     currency: "usd";
-    /** Sum of the KNOWN (non-null) lines; null iff every applicable line is null; 0 with no lines
+    /** Sum of the known (non-null) lines; null iff every applicable line is null; 0 with no lines
      *  for a spend-free run. */
     estimatedTotalUsd: number | null;
     /** Oldest asOf across contributing rates; null when nothing was priced. */
@@ -404,7 +406,7 @@ export interface RunCostSummary {
     };
     /** Host-side create->teardown span in minutes; null when no sandbox was created. */
     desktopMinutes: number | null;
-    /** Honest "estimated; <x> unmeasured" statement. */
+    /** The "estimated; <x> unmeasured" statement. */
     note: string;
 }
 export interface RunProviderResource {
@@ -436,19 +438,19 @@ export interface RunRerunLineage {
     }>;
 }
 /**
- * What happened to the PARTICIPANTS in a study, with the denominator attached.
+ * What happened to the participants in a study, with the denominator attached.
  *
- * A stakeholder watching through the glass forms conclusions from vivid moments — that is the
+ * A stakeholder watching through the glass forms conclusions from vivid moments. That is the
  * classic failure of the viewing room, and it is why researchers synthesize rather than letting the
  * room decide. So anything shown to a stakeholder carries its count, or it becomes a machine for
  * manufacturing certainty from n=1 (docs/principles/three-roles.md).
  *
- * These are OUTCOMES, not scores. `abandoned` is the most valuable thing a usability study
+ * These are outcomes, not scores. `abandoned` is the most valuable thing a usability study
  * produces, and `harnessFailed` is the only member that says the instrument, rather than the
  * product, is what went wrong.
  */
 export interface ParticipantOutcomes {
-    /** Participants whose sessions reached a terminal state — the denominator for every count below. */
+    /** Participants whose sessions reached a terminal state: the denominator for every count below. */
     total: number;
     /** Recorded successful sessions; completion provenance depends on the actor and its evidence. */
     reachedGoal: number;
@@ -463,7 +465,7 @@ export interface ParticipantOutcomes {
     /**
      * Participants who reported friction or a defect on the way, whatever their outcome.
      *
-     * This is NOT a failure count and it overlaps the others on purpose — someone can reach the goal
+     * This is not a failure count, and it overlaps the others on purpose: someone can reach the goal
      * and still tell you the road there was broken. A live two-persona run made the case: both
      * participants signed in, so "2/2 reached the goal" was true, and the keyboard-first one also
      * reported that the signature step could not be completed without a mouse. Reporting only the
@@ -480,61 +482,66 @@ export interface ReviewSummary {
      * The study result, separate from the verdict above.
      *
      * `verdict` answers a gate-shaped question and has to collapse a run to one word. This answers
-     * the research question — what happened to the people in the study — and does not collapse: a run
+     * the research question (what happened to the people in the study) and does not collapse: a run
      * where two of three participants finished is not usefully "fail", and a run where the harness
      * broke is a different thing from one where a persona gave up. Absent on a dry-run contract
      * bundle, which has no participants.
      */
     participants?: ParticipantOutcomes;
     /**
-     * The study's per-task completion rates (#414) — present only when the lab declared a protocol
+     * The study's per-task completion rates, present only when the lab declared a protocol
      * and at least one session produced a funnel. Absent means no protocol was measured, never that
      * everyone finished.
      */
-    tasks?: StudyTaskFunnel;
+    tasks?: RunTaskFunnel;
 }
 /**
  * The study's task funnel: for each declared task, how many participants completed it, out of how
- * many sessions produced a funnel. This is "where did people get stuck" as data — the number a
- * researcher reads first — where the per-participant funnels answer it one journey at a time.
+ * many sessions produced a funnel. This is "where did people get stuck" as data, the number a
+ * researcher reads first, where the per-participant funnels answer it one journey at a time.
  *
- * Aggregated by task id in declaration order. Every lane in a run shares the actor's protocol, so
+ * Aggregated by task id in declaration order. Every participant in a run shares the actor's protocol, so
  * ids line up across participants; a funnel missing a task id (a future mixed-protocol route)
  * simply does not count toward that task's denominator.
  */
-export interface StudyTaskFunnel {
-    /** Sessions that produced a funnel — the denominator for every count below. */
+export interface RunTaskFunnel {
+    /** Sessions that produced a funnel: the denominator for every count below. */
     sessions: number;
     tasks: Array<{
         id: string;
         /** Participants whose sessions corroborated this task complete. */
         completed: number;
-        /** Sessions whose protocol declared this task — its denominator. */
+        /** Sessions whose protocol declared this task: its denominator. */
         sessions: number;
         /** False when the task declared no success criterion: asked for, never measurable. */
         observable: boolean;
         /** Sessions where this task's criteria were never evaluated, because the observations they
          *  read never arrived. Counted apart from failures: "0/3 completed" with 3 unmeasured is a
-         *  statement about our instrument, not about the participants (#514). */
+         *  statement about our instrument, not about the participants. */
         unmeasured: number;
     }>;
 }
+/** The run a bundle belongs to: the Run startRun returned, or a test's stand-in. */
+export interface BundleRun {
+    readonly runId: string;
+    readonly mode: RunBundle["mode"];
+    readonly createdAt: string;
+    /** The manifest the run came from, as the plan carried it to startRun. */
+    readonly lab?: RunStudyProvenance | undefined;
+}
 /**
- * The fields every run bundle starts with, in the saved order. A route passes its run, mode and
- * participant count; the public target cwd and the run's own artifact root are the defaults.
+ * The fields every run bundle starts with, in the saved order. The run supplies its id, mode,
+ * start time and lab; the route passes the participant count and source. The public target cwd
+ * and the run's own artifact root are the defaults.
  */
-export declare function bundleHead(args: {
+export declare function bundleHead(run: BundleRun, args: {
     /** Publication restrictions (real communications), saved right after the schema. */
     publication?: RunBundle["publication"];
-    runId: string;
-    mode: RunBundle["mode"];
     participants: number;
-    createdAt: string;
     cwd?: string;
     artifactRoot?: string;
-    lab?: RunLabProvenance;
     source: RunBundle["source"];
-}): Pick<RunBundle, "schema" | "publication" | "runId" | "mode" | "simCount" | "createdAt" | "cwd" | "artifactRoot" | "lab" | "source">;
+}): Pick<RunBundle, "schema" | "publication" | "runId" | "mode" | "simCount" | "createdAt" | "cwd" | "artifactRoot" | "study" | "lab" | "source">;
 /** The files every run directory holds, as the bundle names them. */
 export declare function bundleArtifacts(): RunBundle["artifacts"];
 export declare function buildRunSource(args: {

package/dist/run/bundle.js

@@ -1,25 +1,27 @@
 import path from "node:path";
 import { captureGitState } from "./git-state.js";
+import { studyFields } from "./study-provenance.js";
 export const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v1";
 /** The run bundle file, relative to the run directory. */
 export const RUN_BUNDLE_FILE = "run.json";
 export const REVIEW_SCHEMA = "humanish.review.v1";
 export const PUBLIC_TARGET_CWD = "[target-cwd]";
 /**
- * The fields every run bundle starts with, in the saved order. A route passes its run, mode and
- * participant count; the public target cwd and the run's own artifact root are the defaults.
+ * The fields every run bundle starts with, in the saved order. The run supplies its id, mode,
+ * start time and lab; the route passes the participant count and source. The public target cwd
+ * and the run's own artifact root are the defaults.
  */
-export function bundleHead(args) {
+export function bundleHead(run, args) {
     return {
         schema: RUN_BUNDLE_SCHEMA,
         ...(args.publication === undefined ? {} : { publication: args.publication }),
-        runId: args.runId,
-        mode: args.mode,
+        runId: run.runId,
+        mode: run.mode,
         simCount: args.participants,
-        createdAt: args.createdAt,
+        createdAt: run.createdAt,
         cwd: args.cwd ?? PUBLIC_TARGET_CWD,
-        artifactRoot: args.artifactRoot ?? path.join(".humanish", "runs", args.runId),
-        ...(args.lab === undefined ? {} : { lab: args.lab }),
+        artifactRoot: args.artifactRoot ?? path.join(".humanish", "runs", run.runId),
+        ...studyFields(run.lab),
         source: args.source,
     };
 }

package/dist/run/cost-summary.js

@@ -66,6 +66,7 @@ function modelCostLines(participants) {
             ratesAsOf: est.ratesAsOf,
             ...(est.source === undefined ? {} : { source: est.source }),
             ...(est.placeholder ? { placeholder: true } : {}),
+            ...(est.basis === undefined ? {} : { basis: est.basis }),
         });
     }
     return breakdown;
@@ -123,8 +124,8 @@ function costTotals(breakdown) {
     let anyKnown = false;
     let anyNull = false;
     let placeholder = false;
-    // Aggregate freshness is CONSERVATIVE: an aggregate estimate is only as current as its OLDEST
-    // contributing rate, so ratesAsOf takes the MIN (oldest) asOf — MAX would overclaim freshness the
+    // Aggregate freshness is conservative: an aggregate estimate is only as current as its oldest
+    // contributing rate, so ratesAsOf takes the minimum (oldest) asOf; the maximum would overclaim freshness the
     // moment operator-edited rates in src/run/pricing.ts diverge. Each breakdown line keeps its own true asOf.
     let minRatesAsOf = null;
     for (const line of breakdown) {
@@ -151,8 +152,8 @@ function costTotals(breakdown) {
 function costNote(args, totals) {
     const { estimatedTotalUsd, anyNull, placeholder, minRatesAsOf } = totals;
     const estimateNote = estimatedTotalUsd === null
-        ? `No priced spend lines this run — every cost line is DECLARED ABSENT (unknown rate / no usage / no duration); nothing is guessed. ${args.participants.some((participant) => participant.trace.executionProfile?.billing === "account-unknown") ? "Account billing remains unknown; API prices do not measure account spend." : "Add a rate to src/run/pricing.ts to estimate this model."}`
-        : `Estimated ${estimatedTotalUsd} USD total${anyNull ? " (LOWER BOUND — some lines unmeasured/unpriced)" : ""}${placeholder ? "; includes PLACEHOLDER rate(s) — confirm before trusting the magnitude" : ""}. Every figure is an ESTIMATE (rates as of ${minRatesAsOf} — the OLDEST contributing rate, since an aggregate is only as fresh as its stalest input), a rate-table multiply, NOT an authoritative provider charge.`;
+        ? `No cost line in this run has a price: each lacks a rate, usage or a duration, and none is guessed. ${args.participants.some((participant) => participant.trace.executionProfile?.billing === "account-unknown") ? "Account billing remains unknown; API prices do not measure account spend." : "Each line's reason says what is missing."}`
+        : `Estimated ${estimatedTotalUsd} USD total${anyNull ? " (a lower bound: some lines are unmeasured or unpriced)" : ""}${placeholder ? "; it uses a placeholder rate, so confirm the rate before relying on the amount" : ""}. Every figure multiplies usage by a rate table (rates as of ${minRatesAsOf}, the oldest rate used), so it is an estimate and not the provider's charge.`;
     return (estimateNote +
         ((args.desktops?.length ?? 0) > 0
             ? args.desktops.some((usage) => usage.observation !== undefined && "resources" in usage.observation)
@@ -204,7 +205,7 @@ export function spendFreeCostSummary() {
         breakdown: [],
         tokenUsage: { input: 0, output: 0, total: 0 },
         desktopMinutes: null,
-        note: "No model request and no hosted desktop: this run spent $0 by construction.",
+        note: "This run made no model request and used no hosted desktop, so it cost $0.",
     };
 }
 // Convert a host-side desktop span (ms) into billed minutes, or undefined when no sandbox ran.

package/dist/run/costs.d.ts

@@ -1,6 +1,6 @@
 import type { RunIndexEntry } from "./run-index.js";
 /** Additive accounting for retained attempts. Null means no estimate, never an invented zero. */
-export interface StudyCosts {
+export interface CostTotals {
     estimatedTotalUsd: number | null;
     runEstimatedUsd: number | null;
     analysisEstimatedUsd: number | null;
@@ -16,12 +16,12 @@ export interface StudyCosts {
     /** No retained history, legacy report-only usage, or unreadable/conflicting accounting. */
     analysisHistoryUncertainRuns: number;
 }
-export interface StudyCostRow {
+export interface CostRow {
     runId: string;
-    costs: StudyCosts;
+    costs: CostTotals;
     warnings: string[];
 }
-export declare function emptyStudyCosts(): StudyCosts;
-export declare function addStudyCosts(into: StudyCosts, next: StudyCosts): void;
+export declare function emptyCostTotals(): CostTotals;
+export declare function addCostTotals(into: CostTotals, next: CostTotals): void;
 /** A read-only, bounded accounting pass. Never validates findings, dispatches, repairs or writes. */
-export declare function readStudyCosts(cwd: string, entry: RunIndexEntry): Promise<StudyCostRow>;
+export declare function readCostTotals(cwd: string, entry: RunIndexEntry): Promise<CostRow>;