humanish 0.118.0 → 0.119.0

package/dist/study/warnings.js

@@ -302,11 +302,19 @@ export function forwardDeclaredWarnings(config) {
         ];
     // A declared cap below the participant count is legal but loud: the roster promises N live actors
     // and the cap delivers waves of M. Say so up front (inspect + dry-run + run): a green run in
-    // waves is otherwise indistinguishable from the all-live run the author meant.
+    // waves is otherwise indistinguishable from the all-live run the author meant. A roster that
+    // declares when its participants start never promised them all at once; the plan's schedule
+    // says who waits for a slot.
     {
-        const participantCount = participantList(config)?.length ?? declaredParticipantCount(config) ?? 1;
+        const roster = participantList(config);
+        const participantCount = roster?.length ?? declaredParticipantCount(config) ?? 1;
         const cap = config.execution?.concurrency;
-        if (routes.cua && cap !== undefined && participantCount > 1 && cap < participantCount) {
+        const scheduled = roster?.some((entry) => entry.startAfterMs !== undefined) === true;
+        if (routes.cua &&
+            !scheduled &&
+            cap !== undefined &&
+            participantCount > 1 &&
+            cap < participantCount) {
             warnings.push(`execution.concurrency ${cap} caps a ${participantCount}-participant roster: participants run in waves of ${cap}, never all live at once. Remove execution.concurrency (the default runs all ${participantCount} participants simultaneously) or set it to ${participantCount}; declare a lower cap only to bound simultaneous paid desktops.`);
         }
     }

package/docs/contracts/run-bundle.md

@@ -65,7 +65,7 @@ scenario:
   goal: "<scenario goal>"
   source: "<scenario source>"
   sourceDigest: "<sha256>"
-simulations: [] # simCount entries, each paired with its streams
+simulations: [] # simCount entries, each paired with its streams; `arrival` when the study declares starts
 streams: []
 events: []
 artifacts:

package/docs/contracts/schemas.md

@@ -215,6 +215,18 @@ The rest of this section names keys by their v3 spelling:
   `<id>-01` … `<id>-NN`, even when n is 1, before the engine runs (`viewer-01`,
   `viewer-02`, ...), so the runtime and run bundle keep one normalized participant
   shape. Ids are checked for collisions after expansion;
+- `participants[].startAfterMs` (computer-use and shared-world): when the participant
+  starts, in whole milliseconds after the run starts its participants, from 0 to 86,400,000
+  (24 hours). A `count` group's `startEveryMs` gives member k the start
+  `startAfterMs + (k - 1) * startEveryMs`, expanded at parse time like the ids. Refused: an
+  interval without `count`, a member past 24 hours, a start on a study of one participant, and a
+  later start for the external-public `host`. Participants start in order of their starts, each
+  at its time or when a slot frees under `execution.concurrency` and the E2B plan's limit,
+  whichever is later (`runOnSchedule` in `src/study/arrivals.ts`). Each participant's desktop is
+  created when it starts. The plan (`arrivals`, `planArrivals`) reports the first and last start
+  and the most participants at once with every session at its full budget, and the provisioned
+  shared world's subject sandbox serves until the last session can end, which the plan checks
+  against the sandbox ceiling. A rerun starts its selected participants together;
 - `execution.concurrency` (computer-use E2B routes, including shared-world): a
   cap on participants in flight at once. When omitted, every participant runs
   simultaneously: both routes resolve it when they plan, from the final participant count
@@ -516,7 +528,13 @@ Core-owned fields:
 - `artifactRoot`
 - `source.git`
 - `lifecycle`
-- `simulations`
+- `simulations`: one record per participant. On the computer-use and shared-world routes, a
+  study that declares `participants[].startAfterMs` gives each record `arrival:
+  { startAfterMs, scheduledAt?, startedAt? }`: the participant's offset (0 when its entry declares
+  none), the moment the run started its participants plus that offset, and when its desktop was
+  requested, which is later than `scheduledAt` when it waited for a free slot. A dry run records
+  only the offset, and a participant that never started has no `startedAt`. The record's own
+  `startedAt` is the run's creation time.
 - `streams`
 - `events`
 - `redaction`

package/docs/contracts/study-analysis.md

@@ -37,17 +37,27 @@ The estimate counts the instructions, evidence packet and result schema at 3
 UTF-8 bytes per input token, adds 2,048 framing tokens and each capture's
 high-detail image tokens, and prices input at the model's highest input rate.
 The expected output is 12,000 tokens plus 1,000 per participant, at most the
-output allowance; the worst case spends the whole allowance. `admission` in
+output allowance; the worst case spends the whole allowance. A run with more than
+16 participants sends one request per cohort and a merge request
+([runs with more than 16 participants](#runs-with-more-than-16-participants)),
+and the estimate is their sum, each request priced on its own long-context tier.
+The merge request's input is its instructions, packet and schema, counted the same
+way, plus each cohort's report at that request's whole output allowance; it is
+expected to write what one request covering every participant would. `admission` in
 `--json` output has `estimatedCostUsd` (the expected cost), `worstCaseCostUsd`,
 `admittedCostUsd` (the figure compared with the cap: the expected cost plus 10%,
 or the worst case when that is lower), `maxCostUsd`, `inputTokenAllowance` (the
-input tokens priced) and `outputTokenAllowance`. On 148 billed gpt-6-astra
+input tokens priced), `outputTokenAllowance` (each request's) and `requests` (the
+requests the costs cover: 1, or each cohort's and the merge request; null when the
+input or configuration was refused). The dry run's worst case for more than one
+request says every request writes its whole allowance and names the cohort and merge
+requests, in the words the plan's analysis line uses. On 148 billed gpt-6-astra
 analyses the expected cost was 1.08 to 7.3 times the bill, and 1.08 to 1.32
 times for those billed $1 or more.
 A refusal's message gives the expected cost, the worst case, the cap, and
 `humanish analyze --run <id> --max-cost <n>` with `n` the worst case rounded up.
 
-The default deadline is ten minutes. With no explicit output-token limit, analysis
+The default deadline is ten minutes for each request. With no explicit output-token limit, analysis
 uses 32,768 tokens if admission fits the declared budget, or retains the prior
 16,384-token allowance otherwise. Explicit limits are never adjusted. Selection
 happens before dispatch; `admission.outputTokenAllowance` exposes it in dry-run,
@@ -64,6 +74,48 @@ success. Findings keep reported concerns and observed recovery distinct across
 participants. Other supported models can be selected explicitly, but evidence
 reference validation does not certify their interpretation of small visual details.
 
+## Runs with more than 16 participants
+
+One analysis covers up to 128 participants, the most streams it reads from a run
+bundle. A request covers at most 16 (`EVIDENCE_LIMITS.cohortParticipants` in
+`src/analysis/analysis-limits.ts`). A run with more is split into the fewest
+cohorts of at most 16, with participants dealt in roster order: 17 participants
+make cohorts of 9 and 8, 24 make two of 12, 40 make 14, 13 and 13, and 100 make
+seven. Each cohort's packet is selected under the packet limits below on its own,
+so each participant keeps at least the evidence a 16-participant run gives it.
+Evidence IDs are numbered across the whole run, so they stay unique.
+
+Each cohort request uses the standard instructions, schema and validation, with
+only its own participants' evidence and captures. Up to four run at once for
+OpenAI, which keeps four requests at the packet limits under the lowest paid
+tier's gpt-6-astra rate limit of 1,000,000 tokens a minute; Codex runs one at a
+time. Then one merge request reads the cohort reports, never the evidence or the
+captures. It writes the summary, findings, design findings, concern reviews and
+limitations for the whole run; the participant reviews are the cohorts' own.
+Its findings, design findings and concern reviews may cite only evidence that a
+cohort report cites in its own findings, design findings or concern reviews
+(`analysis_validation_failed_merge_reference_invalid` otherwise), and the merged
+report passes the same reference, membership and basis checks against the run's
+whole packet as a single request's report does.
+
+The attempt has one execution start, one receipt and one `analysis.json`, with the
+run's participants, coverage and evidence and the summed usage of every request
+sent. The artifact schema is unchanged. Its stored limits grew to hold eight
+cohorts: 6,400 evidence items, 320 captures and 16 MiB. If a cohort request fails
+or is rejected, no further request starts, requests already sent finish, no merge
+request is sent and the attempt fails with that request's code, with no findings;
+a warning names the cohort's size. A failed merge request fails the attempt the same way. The usage
+still counts every request sent. Findings from part of the participants are not
+kept as a report on the run.
+
+The first live cohort analysis, on a 24-participant computer-use run, sent two
+cohort requests of 12 participants and the merge request in 5 minutes 6 seconds.
+Its expected cost was $6.08, 2.3 times its $2.65 bill, and each of its 447
+citations resolved in the run's packet. A second analysis of the same run, with
+the current merge instructions, billed $1.92, most of its input served from the
+provider's prompt cache, and each of its 466 citations resolved. Two runs do not
+calibrate the merge request's estimate.
+
 ## Explicit Codex account analysis
 
 An existing completed recording can use a separate restricted Codex analyst:
@@ -85,8 +137,9 @@ converted to API authentication.
 Omit `--max-cost` and `--max-output-tokens` for Codex. Numeric declarations are
 rejected because this transport does not enforce them. `maxCostUsd` and
 `maxOutputTokens` are stored as null. The existing evidence bounds, one analyst
-turn, bounded response bytes and whole-operation timeout still apply. One turn
-is not a claim of one upstream billed request; account limits apply. Reported
+turn per request (one per cohort, and the merge request), bounded response bytes
+and whole-operation timeout still apply. One turn is not a claim of one upstream
+billed request; account limits apply. Reported
 tokens remain inspectable, but dollar estimates, admission dollars and rate dates
 remain null. Interrupted token observations remain explicitly incomplete.
 
@@ -128,7 +181,7 @@ stopped, an operator can remove the empty lock directory and retry.
 
 ## Evidence and findings
 
-The packet currently admits up to 16 participants, 800 evidence items, 40 PNG
+Each request's packet admits up to 16 participants, 800 evidence items, 40 PNG
 captures, 160 KiB of text and 20 MiB of images. Individual source files, image
 dimensions and result sizes have separate limits. Count and text budgets are
 distributed across included participants, with unused capacity from short

package/docs/principles/invariants-and-defaults.md

@@ -87,20 +87,20 @@ Right most of the time, overridable with declared friction (an explicit config f
 env gate, a warning in the run output). Overriding a default is a supported use case;
 silently drifting from one is not.
 
-| Default                                     | Why it is the default                                                                                                                                                                                                                                               | Legitimate override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Dry-run                                     | Spend safety (the live-spend rule sets the floor; dry-run keeps it far away)                                                                                                                                                                                        | `mode: live`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Post-run analysis on supported live studies | Findings accompany the recording; a separate $3 cap on its expected cost is visible before execution                                                                                                                                                                | `review.analysis: false` disables it; an explicit mapping sets another analysis budget. Dry-run and unsupported routes never dispatch; missing default credentials produce a recorded skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Separate worlds (`per-lane-worlds`)         | Isolation, attribution, reproducibility                                                                                                                                                                                                                             | `route: shared-world`: N participants against one mutable plane for scenarios that are about interaction between participants. Every participant runs at once: `execution.concurrency` must be two or more, and an omitted value fills to the number of participants. The plane is one getHost-exposed subject sandbox with synthetic seeded data, or an operator-owned public deployment (external-public), driven by N actor sandboxes. The bundle declares the weaker `attributionClass: shared-world` and a verify-enforced `attributionLimits` ceiling (`best-effort-causal-attribution` and the rest of the concurrent set). Sequential turns at `execution.concurrency: 1` were removed in 0.106.0. |
-| External key placement                      | Smallest blast radius: when the keyed process (e.g. a computer-use provider loop) runs outside the sandbox, its key never enters                                                                                                                                    | In-sandbox placement when the keyed process runs inside (an agent harness under test); declared per actor type, with a spend budget                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Loopback entry URLs                         | Public-safety: never drive third-party sites unbidden                                                                                                                                                                                                               | `policies.allowPublicTargets` for an owner-declared deployment/preview (a Vercel preview of your own app). Multi-participant public/preview fan-out needs explicit `participants[].target` for every participant, so the adapter-owned topology is declared rather than inferred. Provisioned clone subjects always serve in-sandbox on loopback                                                                                                                                                                                                                                                                                                                                                           |
-| Full-fidelity screenshots, local            | The common case is watching a run of your own app locally; blur destroys the deliverable. Raw frames live in gitignored `.humanish/` (this repo's CI adds a binary-asset commit scan; downstream projects rely on the scaffolded `.gitignore` and their own review) | `policies.redactScreenshots: true` blurs at capture; `export --format bundle --redact-screenshots` produces a separate verified copy of a completed run                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| Synthetic, seeded state                     | Pinned provenance; no real user data in evidence paths                                                                                                                                                                                                              | Declared external state, recorded as unpinned in provenance                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| Single participant                          | Cost + evidence simplicity                                                                                                                                                                                                                                          | Declared fan-out where the route supports it: `participants: N` (homogeneous), an explicit `participants` list (differentiated persona/device/instruction), or list entries with a `count` that expand into one entry per participant on the computer-use E2B route (separate worlds, at most 100; `execution.concurrency` and the E2B plan bound concurrent paid participants)                                                                                                                                                                                                                                                                                                                            |
-| Stock `desktop` template                    | The stock E2B desktop image is right for most subjects; absent `execution.desktop.template` keeps `Sandbox.create(opts)` byte-stable                                                                                                                                | `execution.desktop.template` names a custom E2B desktop image (any name/id, no allowlist) for a subject needing baked-in runtimes the stock image lacks (e.g. node/bun/a local Postgres); it is threaded to `Sandbox.create(template, opts)` on every desktop-creating route and recorded in the bundle as `desktopTemplate` (public-safe)                                                                                                                                                                                                                                                                                                                                                                 |
-| Desktop default URL opener                  | Preserve the route/image's historical browser/default opener behavior when unset                                                                                                                                                                                    | `execution.desktop.browser` set to `chrome`, `chromium` or `firefox` makes the hosted CUA/shared-world browser choice explicit, fail-closed, and recorded as `desktopBrowser` in the run bundle                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| Loopback-only observer serving              | Run bundles are local by default (public-safety plank 3); the serve/watch surfaces bind `127.0.0.1` unconditionally, and exposing them is publishing-adjacent, so exposure is fail-closed and carries declared friction                                             | `humanish observe --all --expose` behind tunnel-edge auth (ngrok `--oauth google` with `--allow-email`/`--allow-domain` allow rules, or an operator `--public-url` you secure), or `--expose --safe` (open, gated on verify-`share_ready` runs only). `watch --expose` streams a live run behind edge auth (a live run is never `share_ready`, so `--safe` alone is refused). humanish carries no in-process auth; both print computed warnings naming exactly what became reachable                                                                                                                                                                                                                       |
-| Generous wall-clock safety cap              | `execution.timeoutMs` bounds runaway spend, not a goal; ~30 min is reasonable for open-ended "watch it play"                                                                                                                                                        | A session that reaches the cap after productive activity is recorded as `budget_reached` (status `passed`, a non-failure completion, exit `0`), distinct from a zero-progress `timed_out` (a failure, exit `2`). Goal-directed studies set a tight `timeoutMs` and read `completionReason` to confirm the goal, not the cap                                                                                                                                                                                                                                                                                                                                                                                |
+| Default                                     | Why it is the default                                                                                                                                                                                                                                               | Legitimate override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dry-run                                     | Spend safety (the live-spend rule sets the floor; dry-run keeps it far away)                                                                                                                                                                                        | `mode: live`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Post-run analysis on supported live studies | Findings accompany the recording; a separate $3 cap on its expected cost is visible before execution                                                                                                                                                                | `review.analysis: false` disables it; an explicit mapping sets another analysis budget. Dry-run and unsupported routes never dispatch; missing default credentials produce a recorded skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Separate worlds (`per-lane-worlds`)         | Isolation, attribution, reproducibility                                                                                                                                                                                                                             | `route: shared-world`: N participants against one mutable plane for scenarios that are about interaction between participants. Participants run at once, as many as `execution.concurrency` (two or more) and the E2B plan's limit allow, unless the study declares when each one starts (`participants[].startAfterMs`). The plane is one getHost-exposed subject sandbox with synthetic seeded data, or an operator-owned public deployment (external-public), driven by N actor sandboxes. The bundle declares the weaker `attributionClass: shared-world` and a verify-enforced `attributionLimits` ceiling (`best-effort-causal-attribution` and the rest of the concurrent set). Sequential turns at `execution.concurrency: 1` were removed in 0.106.0. |
+| External key placement                      | Smallest blast radius: when the keyed process (e.g. a computer-use provider loop) runs outside the sandbox, its key never enters                                                                                                                                    | In-sandbox placement when the keyed process runs inside (an agent harness under test); declared per actor type, with a spend budget                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Loopback entry URLs                         | Public-safety: never drive third-party sites unbidden                                                                                                                                                                                                               | `policies.allowPublicTargets` for an owner-declared deployment/preview (a Vercel preview of your own app). Multi-participant public/preview fan-out needs explicit `participants[].target` for every participant, so the adapter-owned topology is declared rather than inferred. Provisioned clone subjects always serve in-sandbox on loopback                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Full-fidelity screenshots, local            | The common case is watching a run of your own app locally; blur destroys the deliverable. Raw frames live in gitignored `.humanish/` (this repo's CI adds a binary-asset commit scan; downstream projects rely on the scaffolded `.gitignore` and their own review) | `policies.redactScreenshots: true` blurs at capture; `export --format bundle --redact-screenshots` produces a separate verified copy of a completed run                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Synthetic, seeded state                     | Pinned provenance; no real user data in evidence paths                                                                                                                                                                                                              | Declared external state, recorded as unpinned in provenance                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Single participant                          | Cost + evidence simplicity                                                                                                                                                                                                                                          | Declared fan-out where the route supports it: `participants: N` (homogeneous), an explicit `participants` list (differentiated persona/device/instruction), or list entries with a `count` that expand into one entry per participant on the computer-use E2B route (separate worlds, at most 100; `execution.concurrency` and the E2B plan bound concurrent paid participants)                                                                                                                                                                                                                                                                                                                                                                                |
+| Stock `desktop` template                    | The stock E2B desktop image is right for most subjects; absent `execution.desktop.template` keeps `Sandbox.create(opts)` byte-stable                                                                                                                                | `execution.desktop.template` names a custom E2B desktop image (any name/id, no allowlist) for a subject needing baked-in runtimes the stock image lacks (e.g. node/bun/a local Postgres); it is threaded to `Sandbox.create(template, opts)` on every desktop-creating route and recorded in the bundle as `desktopTemplate` (public-safe)                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Desktop default URL opener                  | Preserve the route/image's historical browser/default opener behavior when unset                                                                                                                                                                                    | `execution.desktop.browser` set to `chrome`, `chromium` or `firefox` makes the hosted CUA/shared-world browser choice explicit, fail-closed, and recorded as `desktopBrowser` in the run bundle                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Loopback-only observer serving              | Run bundles are local by default (public-safety plank 3); the serve/watch surfaces bind `127.0.0.1` unconditionally, and exposing them is publishing-adjacent, so exposure is fail-closed and carries declared friction                                             | `humanish observe --all --expose` behind tunnel-edge auth (ngrok `--oauth google` with `--allow-email`/`--allow-domain` allow rules, or an operator `--public-url` you secure), or `--expose --safe` (open, gated on verify-`share_ready` runs only). `watch --expose` streams a live run behind edge auth (a live run is never `share_ready`, so `--safe` alone is refused). humanish carries no in-process auth; both print computed warnings naming exactly what became reachable                                                                                                                                                                                                                                                                           |
+| Generous wall-clock safety cap              | `execution.timeoutMs` bounds runaway spend, not a goal; ~30 min is reasonable for open-ended "watch it play"                                                                                                                                                        | A session that reaches the cap after productive activity is recorded as `budget_reached` (status `passed`, a non-failure completion, exit `0`), distinct from a zero-progress `timed_out` (a failure, exit `2`). Goal-directed studies set a tight `timeoutMs` and read `completionReason` to confirm the goal, not the cap                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 ## The placement rule (worked example)
 

package/docs/product/automatic-analysis.md

@@ -29,7 +29,13 @@ estimate gives two numbers: the expected cost, and the worst case if the analyst
 spends its whole output allowance. `humanish study check` gives the expected cost
 range for the study's participant count, from a run that keeps no evidence to one
 that keeps the most evidence admission admits under the cap, at most the evidence limits. When
-the cap admits no analysis at all, it says so instead. Use `analyze --dry-run --max-cost <usd>` on retained
+the cap admits no analysis at all, it says so instead. A study of more than 16 participants is
+analysed in cohorts of at most 16, one request each, and one more request merges their reports;
+the range covers every request and the analysis line names them (see
+[runs with more than 16 participants](../contracts/study-analysis.md#runs-with-more-than-16-participants)).
+The default $3 cap refuses the analysis of 17 participants even for a run that keeps no evidence,
+so a default analysis of more than 16 participants is skipped with
+`AUTOMATIC_ANALYSIS_ADMISSION_REFUSED` unless `review.analysis.maxCostUsd` admits it. Use `analyze --dry-run --max-cost <usd>` on retained
 evidence to inspect the expected cost, the worst case and the selected token
 allowance before deliberately choosing a larger budget. Explicit
 `maxOutputTokens` and `--max-output-tokens` limits are honored exactly. The output allowance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.118.0",
+  "version": "0.119.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",

package/dist/study/automatic-analysis-plan.d.ts

@@ -1,28 +0,0 @@
-import { type AutomaticAnalysisResult } from "../analysis/automatic-completion.js";
-import { type AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
-import type { StudyRoute } from "./routing.js";
-/** The reason a run records for an analysis its study has too many participants for. */
-export declare const PARTICIPANT_LIMIT_SKIP = "AUTOMATIC_ANALYSIS_PARTICIPANT_LIMIT";
-/** The CLI's words for that reason, after "analysis: ". */
-export declare const PARTICIPANT_LIMIT_SKIP_TEXT: string;
-/** The skip a study of `participants` gets, or undefined when its analysis runs. */
-export declare function analysisSkipFor(participants: number): typeof PARTICIPANT_LIMIT_SKIP | undefined;
-/** The analysis budget the plan line shows, and the skip when the analysis will not run. */
-export type StudyAnalysisBudget = AutomaticAnalysisBudget & {
-    readonly skip?: typeof PARTICIPANT_LIMIT_SKIP;
-};
-/**
- * The budget of a study's automatic analysis after a live run of `participants`, or undefined
- * when none is planned. A skipped analysis carries no expected cost, since it spends nothing.
- */
-export declare function studyAnalysisBudget(raw: unknown, route: StudyRoute, participants: number): StudyAnalysisBudget | undefined;
-/** The line `run` and `study check` print about the analysis after a live run. */
-export declare function formatStudyAnalysisBudget(budget: StudyAnalysisBudget): string;
-/** A run's result with its analysis recorded as skipped for its participant count. */
-export declare function withParticipantLimitSkip<T>(result: T, trigger: "default" | "explicit"): T & AutomaticAnalysisResult;
-/**
- * Whether a run's automatic analysis lets the command exit 0. A participant-count skip of the
- * analysis a study did not ask for passes, like the default analysis's missing-key skip; a skip of
- * an explicit request fails, like that request's missing key.
- */
-export declare function studyAnalysisSucceeded(result: AutomaticAnalysisResult): boolean;

package/dist/study/automatic-analysis-plan.js

@@ -1,57 +0,0 @@
-// What automatic analysis does for a study of N participants. One analysis reads at most
-// EVIDENCE_LIMITS.participants of them (the analysis module owns that number). A study with more
-// runs every participant and records its analysis as skipped for that reason, where the analysis
-// would otherwise cover the first participants and drop the rest. The plan line, the run's
-// analysis record and the CLI's exit code all read the skip from here. Once the analysis covers
-// every participant a study may have, the skip never applies and this module can go.
-import { automaticAnalysisSucceeded, } from "../analysis/automatic-completion.js";
-import { automaticAnalysisBudget, formatAutomaticAnalysisBudget, } from "../analysis/automatic-config.js";
-import { EVIDENCE_LIMITS } from "../analysis/evidence.js";
-/** The reason a run records for an analysis its study has too many participants for. */
-export const PARTICIPANT_LIMIT_SKIP = "AUTOMATIC_ANALYSIS_PARTICIPANT_LIMIT";
-/** The CLI's words for that reason, after "analysis: ". */
-export const PARTICIPANT_LIMIT_SKIP_TEXT = `not run, because the study has more than ${EVIDENCE_LIMITS.participants} participants and automatic analysis reads at most ${EVIDENCE_LIMITS.participants}`;
-/** The skip a study of `participants` gets, or undefined when its analysis runs. */
-export function analysisSkipFor(participants) {
-    return participants > EVIDENCE_LIMITS.participants ? PARTICIPANT_LIMIT_SKIP : undefined;
-}
-/**
- * The budget of a study's automatic analysis after a live run of `participants`, or undefined
- * when none is planned. A skipped analysis carries no expected cost, since it spends nothing.
- */
-export function studyAnalysisBudget(raw, route, participants) {
-    const skip = analysisSkipFor(participants);
-    if (skip === undefined)
-        return automaticAnalysisBudget(raw, route, participants);
-    const budget = automaticAnalysisBudget(raw, route);
-    return budget && { ...budget, participants, skip };
-}
-/** The line `run` and `study check` print about the analysis after a live run. */
-export function formatStudyAnalysisBudget(budget) {
-    if (budget.skip === undefined)
-        return formatAutomaticAnalysisBudget(budget);
-    const next = budget.trigger === "default"
-        ? "Set review.analysis: false to leave it out of this plan."
-        : "The analysis this study asks for will be recorded as skipped and the run will exit 2; set review.analysis: false or run fewer participants.";
-    return `After live runs: automatic analysis will not run. This study has ${budget.participants ?? "more"} participants, and automatic analysis reads at most ${EVIDENCE_LIMITS.participants}. ${next}`;
-}
-/** A run's result with its analysis recorded as skipped for its participant count. */
-export function withParticipantLimitSkip(result, trigger) {
-    return {
-        ...result,
-        ...(trigger === "default" ? { automaticAnalysisTrigger: trigger } : {}),
-        automaticAnalysis: { state: "skipped", reason: PARTICIPANT_LIMIT_SKIP },
-    };
-}
-/**
- * Whether a run's automatic analysis lets the command exit 0. A participant-count skip of the
- * analysis a study did not ask for passes, like the default analysis's missing-key skip; a skip of
- * an explicit request fails, like that request's missing key.
- */
-export function studyAnalysisSucceeded(result) {
-    const value = result.automaticAnalysis;
-    return (automaticAnalysisSucceeded(result) ||
-        (result.automaticAnalysisTrigger === "default" &&
-            value?.state === "skipped" &&
-            value.reason === PARTICIPANT_LIMIT_SKIP));
-}