humanish 0.107.0 → 0.108.0

package/docs/contracts/run-bundle.md

@@ -1,12 +1,10 @@
 # Run Bundle Contract
 
-Date: 2026-06-02 (current-state note updated 2026-07-14)
-
-Status: `humanish.run-bundle.v1` is the shipped evidence contract. The
-TypeScript shape in `src/run/bundle.ts` (with `streams[]` in `src/run/streams.ts` and
-`sharedWorld` as `SharedWorldEvidence` in `src/run/shared-world-evidence.ts`) and fail-closed verification in `src/verify/verify.ts` are
-authoritative; this document explains the stable public fields and extension
-rules rather than independently versioning the runtime.
+`humanish.run-bundle.v1` is the evidence contract. The TypeScript shape in `src/run/bundle.ts`
+(with `streams[]` in `src/run/streams.ts` and `sharedWorld` as `SharedWorldEvidence` in
+`src/run/shared-world-evidence.ts`) and the fail-closed checks in `src/verify/verify.ts` are the
+source of truth. This page explains the stable public fields and the extension rules; it does not
+version the runtime separately.
 
 ## Purpose
 
@@ -22,12 +20,16 @@ runId: "<core run id>"
 mode: "dry-run|live"
 simCount: 1
 createdAt: "<ISO timestamp>"
-lab: # optional, additive: which manifest produced this run
-  id: "<lab id>"
-  path: "humanish/labs/<lab id>.yaml"
-  origin: "committed|ignored|explicit"
 cwd: "[target-cwd]"
 artifactRoot: ".humanish/runs/<run-id>"
+study: # optional, additive: which study file produced this run
+  id: "<study id>"
+  path: "humanish/studies/<study id>.yaml"
+  origin: "committed|ignored|explicit"
+lab: # the same value as study, written until 0.109
+  id: "<study id>"
+  path: "humanish/studies/<study id>.yaml"
+  origin: "committed|ignored|explicit"
 source:
   packageName: "<public package name or null>"
   humanishSource: "present|missing"
@@ -190,7 +192,7 @@ field means no retained video, not proof that nothing happened between captures.
 Verification checks the local file, declared size, MP4 header and matching artifact
 entry without loading the whole video into memory. Raw continuous media makes the
 run `local_only` regardless of screenshot redaction. Analysis input remains text
-and screenshots. See [desktop recording](../architecture/desktop-recording.md).
+and screenshots. See [desktop recording](https://humanish.dev/docs/desktop-recording).
 
 ## Hosted Desktop Geometry
 
@@ -199,10 +201,10 @@ different facts separate:
 
 - `screen.requested`: the E2B/X screen size requested by config;
 - `screen.verified`: the screen size measured in-sandbox with `xdpyinfo`;
-- `screen.declared`: the device preset the lab ASKED for, present only when it differs from
+- `screen.declared`: the device preset the study asked for, present only when it differs from
   `screen.requested` because the rendered width was floored to Chrome's ~500px window minimum.
   `verified` compares the floored number with itself and reports a match, so a matching
-  `verified` block is NOT evidence that the preset width rendered. When `declared` is present,
+  `verified` block is not evidence that the preset width rendered. When `declared` is present,
   it did not: a `mobile` (414) and a `small-mobile` (360) participant both render at 500 and are
   indistinguishable by rendered width;
 - `browserWindow`: measured browser bounds after the window-fill attempt; physical X client
@@ -232,8 +234,8 @@ exactly; this hosted-desktop rule does not change that contract.
 ## Subject Provenance
 
 `subject` is an optional, additive top-level field: structured provenance for
-what the computer-use, shared-world or scripted-browser backend actually drove (code pin plus state story). It
-is absent on pre-existing bundles and on bundles from backends that have not
+what the computer-use, shared-world or scripted route actually drove (code pin plus state story). It
+is absent on pre-existing bundles and on bundles from routes that have not
 adopted it. The field shape, its three sources (`clone`, `app-url`,
 `local-tree`), and the `humanish verify` checks that guard it are the schema doc's
 job, not this one: see the `subject` entry under
@@ -246,7 +248,7 @@ enters this field; identity is digests, a sha, a boolean, and counts.
 ## Cost Estimate (advisory)
 
 `cost` is optional and additive (`humanish.run-cost-summary.v1`): the
-computer-use, shared-world, scripted-browser or terminal-product run's cost ESTIMATE: the sum of each participant's
+computer-use, shared-world, scripted-browser or terminal-product run's cost estimate: the sum of each participant's
 token-derived model cost plus E2B desktop compute lines. New independent CUA runs
 emit one line per owned desktop, keyed by public participant ID and carrying observed CPU/memory,
 resource source, host-measured minutes, and the derived per-second rate. Concurrent
@@ -254,7 +256,7 @@ shared-world runs carry the same lines for each participant, plus a desktop line
 `laneId: subject` for a provisioned plane; an external-public plane is not a humanish
 desktop and has no line. Older single aggregate desktop lines remain valid. Missing resource metadata stays
 unpriced; unconfirmed cleanup adds an unknown remaining-lifetime line. It is an
-ESTIMATE, never authoritative: every dollar is a rate-table multiply from the
+estimate, never authoritative: every dollar is a rate-table multiply from the
 operator-editable `src/run/pricing.ts`, carries the pricing `ratesAsOf` date and
 `source`, and is surfaced with the "estimated (rates as of `<date>`)" label. It is
 never shown as a bare charge. It follows the same **declared-absent** discipline as the
@@ -268,7 +270,7 @@ a provisioned clone records the clone's desktop as a `laneId: subject` line. A l
 without `cost` has an unmeasured spend. A live terminal run's `cost` prices the E2B terminal
 sandbox as a `desktop-minutes` line from its acquired-to-cleanup span and `e2b.getInfo` size.
 Its Codex `model-tokens` line prices the agent's tokens from the model passed as `--model`
-(`actors[0].model`, else `gpt-5.6-sol`). Codex reports usage per turn, summed over the turn's
+(`actor.model`, else `gpt-5.6-sol`). Codex reports usage per turn, summed over the turn's
 requests, so the line prices every token at the base tier and carries
 `basis: aggregated_turns_base_rate`. It stays `null` with `no_token_usage` when Codex reported
 none. `terminal-ledgers.json` still counts those tokens without a price, because its provider line
@@ -283,7 +285,7 @@ This bundle subtotal excludes separate study-analysis requests. Use
 `humanish stats` for the complete retained estimate and explicit accounting
 gaps across run costs and analysis attempts. See [study cost statistics](study-costs.md).
 
-`humanish verify` treats cost as ADVISORY on magnitude and FAIL-CLOSED on
+`humanish verify` treats cost as advisory on magnitude and fail-closed on
 labeling: absence passes, but a claimed dollar figure without its `ratesAsOf`
 date + `source`, or a total that does not match its known lines, fails. Verify
 never inspects the magnitude, so a correctly-labeled large estimate still passes.
@@ -325,34 +327,33 @@ under its namespace.
 Multi-participant browser/shared-world routes may carry optional participant grouping metadata:
 
 ```yaml
-actors:
-  - type: openai-computer-use
-    lanes:
-      - id: lane-01
-        actorType: viewer
-        surface: intake
-        caseGroup: case-001
+actor:
+  type: openai-computer-use
+participants:
+  - id: lane-01
+    actorType: viewer
+    surface: intake
+    caseGroup: case-001
 ```
 
-For repeated participants, authors can use compact roster groups. The parser expands
-each group into deterministic `lanes[]` before the engine runs:
+For repeated participants, a `participants` entry can take a `count`. The parser expands
+each such group into deterministic participants before the engine runs:
 
 ```yaml
-actors:
-  - type: openai-computer-use
-    roster:
-      - id: viewer
-        count: 3
-        actorType: viewer
-        surface: review-queue
-        caseGroup: case-001
-        persona: curious-reviewer
-        device: desktop
+actor:
+  type: openai-computer-use
+participants:
+  - id: viewer
+    count: 3
+    actorType: viewer
+    surface: review-queue
+    caseGroup: case-001
+    persona: curious-reviewer
+    device: desktop
 ```
 
-The generated participant ids are `<group.id>-01`, `<group.id>-02`, and so on. `roster`
-is mutually exclusive with explicit `lanes`, homogeneous `count`, and
-`laneFocus`; it is an authoring convenience, not a second runtime shape.
+The generated participant ids are `<group.id>-01`, `<group.id>-02`, and so on, even when
+`count` is 1. A group is an authoring convenience, not a second runtime shape.
 
 These fields are adapter-owned labels, not core enums. They let downstream
 projects express "N actors of M app-defined types across S surfaces" without
@@ -364,7 +365,7 @@ are projected into:
 - Observer `laneGroups[]`;
 - human-readable Observer stream labels.
 
-`actorType` is deliberately separate from `actors[0].type`. The latter selects
+`actorType` is deliberately separate from `actor.type`. The latter selects
 the humanish execution actor, such as `openai-computer-use` or `scripted-browser`.
 The former is the app-defined simulated user bucket, such as `viewer`,
 `maintainer`, or a downstream adapter's own role label.
@@ -485,7 +486,7 @@ humanish:
 
 For public OSS runs, previews could include allowlisted setup files such as
 `package.json`, `.gitignore`, `humanish/config.ts`, and
-`humanish/labs/*.yaml` / `humanish/personas/*.yaml` /
+`humanish/studies/*.yaml` / `humanish/personas/*.yaml` /
 `humanish/scenarios/*.yaml`. For token-backed or private maintainer runs, raw
 previews were suppressed by default. Generated state, `.git`, `.env*`, `.npmrc`,
 browser profiles, `node_modules`, `.humanish/`, and arbitrary source files were