@crvouga/atlas 0.4.0 → 0.6.0

package/dist/core/src/privacy.d.ts

@@ -1,8 +1,35 @@
+/**
+ * @module Privacy scanning
+ *
+ * Keeps real personal data out of the media and manifests a run produces and shares: patterns for
+ * data that must never appear, an allow-list for synthetic emails, and an allow-list of hosts a run may
+ * target. Findings describe what matched without repeating it. These are pure functions of their input;
+ * the runner applies them to the text a driver reports after each step and to the finished manifest.
+ *
+ * @see docs/statecharts.md
+ */
 import type { PrivacyRules } from './run/types.js';
 /** Defaults that fit any product: no real-looking emails, SSNs or card numbers in media or manifests. */
 export declare const DEFAULT_PRIVACY: Required<PrivacyRules>;
+/**
+ * Combines a project's `PrivacyRules` with `DEFAULT_PRIVACY`: its `deny` and `allowEmails` are added
+ * to the defaults, while its `allowHosts`, when given, replaces the default hosts (so list loopback
+ * again if you still need it).
+ */
 export declare function mergePrivacy(rules?: PrivacyRules): Required<PrivacyRules>;
-/** What in `text` looks like real personal data, described without repeating it. */
+/**
+ * Scans `text` for real-looking personal data and returns one description per finding, each
+ * prefixed by `where` and never containing the matched text (an email is shortened to its first
+ * letter and domain). Flags emails not matching `rules.allowEmails` and anything matching a
+ * `rules.deny` pattern. Returns an empty array when the text is clean.
+ *
+ * @param rules the merged rules (`mergePrivacy`).
+ */
 export declare function privacyFindings(text: string, where: string, rules: Required<PrivacyRules>): string[];
-/** Refuse to run against anything but the allowed hosts (loopback by default). */
+/**
+ * Throws unless every URL's hostname is in `rules.allowHosts` (loopback by default), so a run
+ * cannot touch a real environment by accident.
+ *
+ * @throws Error naming the first refused host, or a `TypeError` for a URL that does not parse.
+ */
 export declare function assertAllowedTarget(urls: string[], rules: Required<PrivacyRules>): void;

package/dist/core/src/privacy.js

@@ -11,6 +11,11 @@ export const DEFAULT_PRIVACY = {
     allowEmails: [/@example\.(com|org|net)$/i, /\.(test|example|invalid|localhost|local)$/i],
     allowHosts: ['127.0.0.1', 'localhost', '::1', '[::1]']
 };
+/**
+ * Combines a project's `PrivacyRules` with `DEFAULT_PRIVACY`: its `deny` and `allowEmails` are added
+ * to the defaults, while its `allowHosts`, when given, replaces the default hosts (so list loopback
+ * again if you still need it).
+ */
 export function mergePrivacy(rules = {}) {
     return {
         deny: [...DEFAULT_PRIVACY.deny, ...(rules.deny ?? [])],
@@ -18,7 +23,14 @@ export function mergePrivacy(rules = {}) {
         allowHosts: rules.allowHosts ?? DEFAULT_PRIVACY.allowHosts
     };
 }
-/** What in `text` looks like real personal data, described without repeating it. */
+/**
+ * Scans `text` for real-looking personal data and returns one description per finding, each
+ * prefixed by `where` and never containing the matched text (an email is shortened to its first
+ * letter and domain). Flags emails not matching `rules.allowEmails` and anything matching a
+ * `rules.deny` pattern. Returns an empty array when the text is clean.
+ *
+ * @param rules the merged rules (`mergePrivacy`).
+ */
 export function privacyFindings(text, where, rules) {
     const findings = [];
     for (const email of text.match(EMAIL) ?? []) {
@@ -32,7 +44,12 @@ export function privacyFindings(text, where, rules) {
             findings.push(`${where}: something shaped like ${name}`);
     return findings;
 }
-/** Refuse to run against anything but the allowed hosts (loopback by default). */
+/**
+ * Throws unless every URL's hostname is in `rules.allowHosts` (loopback by default), so a run
+ * cannot touch a real environment by accident.
+ *
+ * @throws Error naming the first refused host, or a `TypeError` for a URL that does not parse.
+ */
 export function assertAllowedTarget(urls, rules) {
     for (const url of urls) {
         const host = new URL(url).hostname;

package/dist/core/src/report/formats.d.ts

@@ -1,3 +1,13 @@
+/**
+ * @module Run report formats
+ *
+ * Pure converters from a run's manifest (or a chart) to the formats other tools read: JUnit XML, CTRF
+ * JSON, WebVTT captions and a Mermaid state diagram. They take plain data, do no I/O and are
+ * deterministic. The manifest is read through a minimal structural type, so only the fields named
+ * there are required of it.
+ *
+ * @see docs/statecharts.md
+ */
 import type { MachineConfig } from '../spec/types.js';
 import type { TimelineEntry } from '../run/types.js';
 type ManifestLike = {
@@ -23,9 +33,19 @@ type ManifestLike = {
         }[];
     }[];
 };
-/** JUnit XML (the format every CI system reads): one test case per path. */
+/**
+ * Renders the manifest as JUnit XML (the format every CI system reads): one test case per path,
+ * with `classname` the path kind (`journey` or `generated`). A failed path is a `failure` carrying
+ * the last attempt's error, a `not-reached` path is `skipped` (with the blocking reason when there is
+ * one), and a flaky path passes with a note in `system-out`. The suite time is the run duration in seconds.
+ */
 export declare function toJUnit(manifest: ManifestLike): string;
-/** CTRF (Common Test Report Format, https://ctrf.io) JSON. */
+/**
+ * Renders the manifest as CTRF (Common Test Report Format, https://ctrf.io) JSON: one test per
+ * path, its steps as `steps`. `flaky` paths are `passed` with `flaky: true`, `not-reached` is
+ * `skipped`, and the failed path's trace (if any) is attached. Per-test `duration` is always 0:
+ * only the run's start and stop times are recorded.
+ */
 export declare function toCtrf(manifest: ManifestLike): {
     reportFormat: string;
     specVersion: string;
@@ -62,8 +82,18 @@ export declare function toCtrf(manifest: ManifestLike): {
         }[];
     };
 };
-/** WebVTT captions for a clip, one cue per timeline entry. */
+/**
+ * Renders WebVTT captions for a clip, one cue per timeline entry. A cue lasts until the next entry
+ * (or the clip's end), at least 500 ms and at most 4 s.
+ *
+ * @param timeline the step's entries, with `atMs` relative to the start of the clip.
+ * @param durationMs the clip's length in milliseconds.
+ */
 export declare function toWebVtt(timeline: TimelineEntry[], durationMs: number): string;
-/** A Mermaid `stateDiagram-v2` of a machine, with nested and parallel states. */
+/**
+ * Renders a machine as a Mermaid `stateDiagram-v2` with nested and parallel states. States get
+ * short ids (`s0`, `s1`, ... in order of first use) and keep their names as labels; `:` and `;` in event
+ * names are replaced by spaces because Mermaid reads them as syntax. Written as `chart.mmd` in every run.
+ */
 export declare function toMermaid(machine: MachineConfig): string;
 export {};

package/dist/core/src/report/formats.js

@@ -1,6 +1,11 @@
 import { targetOf } from '../spec/types.js';
 const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-/** JUnit XML (the format every CI system reads): one test case per path. */
+/**
+ * Renders the manifest as JUnit XML (the format every CI system reads): one test case per path,
+ * with `classname` the path kind (`journey` or `generated`). A failed path is a `failure` carrying
+ * the last attempt's error, a `not-reached` path is `skipped` (with the blocking reason when there is
+ * one), and a flaky path passes with a note in `system-out`. The suite time is the run duration in seconds.
+ */
 export function toJUnit(manifest) {
     const cases = manifest.paths.map((p) => {
         const body = p.status === 'failed'
@@ -24,7 +29,12 @@ export function toJUnit(manifest) {
         ''
     ].join('\n');
 }
-/** CTRF (Common Test Report Format, https://ctrf.io) JSON. */
+/**
+ * Renders the manifest as CTRF (Common Test Report Format, https://ctrf.io) JSON: one test per
+ * path, its steps as `steps`. `flaky` paths are `passed` with `flaky: true`, `not-reached` is
+ * `skipped`, and the failed path's trace (if any) is attached. Per-test `duration` is always 0:
+ * only the run's start and stop times are recorded.
+ */
 export function toCtrf(manifest) {
     const status = (s) => (s === 'passed' ? 'passed' : s === 'failed' ? 'failed' : s === 'flaky' ? 'passed' : 'skipped');
     const tests = manifest.paths.map((p) => ({
@@ -62,7 +72,13 @@ function vttTime(ms) {
     const pad = (n, w = 2) => String(n).padStart(w, '0');
     return `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}.${pad(d.getUTCMilliseconds(), 3)}`;
 }
-/** WebVTT captions for a clip, one cue per timeline entry. */
+/**
+ * Renders WebVTT captions for a clip, one cue per timeline entry. A cue lasts until the next entry
+ * (or the clip's end), at least 500 ms and at most 4 s.
+ *
+ * @param timeline the step's entries, with `atMs` relative to the start of the clip.
+ * @param durationMs the clip's length in milliseconds.
+ */
 export function toWebVtt(timeline, durationMs) {
     const cues = timeline.map((e, i) => {
         const end = Math.min(timeline[i + 1]?.atMs ?? durationMs, e.atMs + 4_000);
@@ -71,7 +87,11 @@ export function toWebVtt(timeline, durationMs) {
     });
     return `WEBVTT\n\n${cues.join('\n\n')}\n`;
 }
-/** A Mermaid `stateDiagram-v2` of a machine, with nested and parallel states. */
+/**
+ * Renders a machine as a Mermaid `stateDiagram-v2` with nested and parallel states. States get
+ * short ids (`s0`, `s1`, ... in order of first use) and keep their names as labels; `:` and `;` in event
+ * names are replaced by spaces because Mermaid reads them as syntax. Written as `chart.mmd` in every run.
+ */
 export function toMermaid(machine) {
     const ids = new Map();
     const id = (name) => {

package/dist/core/src/report/markdown.d.ts

@@ -1,8 +1,23 @@
+/**
+ * @module Markdown chart map
+ *
+ * Renders a chart (usually the composed product) as a Markdown document for the people who own the
+ * product, not for developers: plain Markdown with internal links, so it renders on any code host
+ * and diffs with the chart. Pure and deterministic.
+ */
 import type { Journey, MachineConfig } from '../spec/types.js';
 /**
  * A readable map of a chart for the people who own the product: one section per area (parallel
  * regions apart), each state with what it means, what the user sees, and every event that can
  * happen there and where it leads, then the named journeys. Plain Markdown, so it renders on any
  * code host and diffs with the chart.
+ *
+ * Top-level states become sections, and each region of a top-level parallel state gets its own. A
+ * `snapshot` is shown only when it contains whitespace (so an identifier-like snapshot is left out),
+ * and a state with `confidence: 'assumed'` is marked as unconfirmed. Links use GitHub's heading anchors.
+ *
+ * @param machine the chart, composed if child charts should be inlined.
+ * @param journeys the named journeys to list at the end; none by default.
+ * @see docs/statecharts.md
  */
 export declare function toMarkdown(machine: MachineConfig, journeys?: Journey[]): string;

package/dist/core/src/report/markdown.js

@@ -47,6 +47,14 @@ const cell = (text) => text.replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ');
  * regions apart), each state with what it means, what the user sees, and every event that can
  * happen there and where it leads, then the named journeys. Plain Markdown, so it renders on any
  * code host and diffs with the chart.
+ *
+ * Top-level states become sections, and each region of a top-level parallel state gets its own. A
+ * `snapshot` is shown only when it contains whitespace (so an identifier-like snapshot is left out),
+ * and a state with `confidence: 'assumed'` is marked as unconfirmed. Links use GitHub's heading anchors.
+ *
+ * @param machine the chart, composed if child charts should be inlined.
+ * @param journeys the named journeys to list at the end; none by default.
+ * @see docs/statecharts.md
  */
 export function toMarkdown(machine, journeys = []) {
     const sections = sectionsOf(machine);

package/dist/core/src/run/clients.d.ts

@@ -1,4 +1,5 @@
 import type { Driver, EventImplementation, Implementation, StateImplementation } from './types.js';
+/** Options for `combineDrivers`. */
 export type CombineDriversOptions = {
     /**
      * `focused` (default) screenshots the client a state is recognised on; `all` also screenshots
@@ -13,16 +14,36 @@ export type CombineDriversOptions = {
  * act on (`onClient`, `combineImplementations`), so screenshots and clips come from that client's
  * screen. Timeline entries are tagged with the client that made them.
  *
- *   combineDrivers({ member: webdriverDriver(appiumIos), operator: playwrightDriver(), api: httpDriver(url) })
+ * The combined driver's `concurrency` is the smallest of the drivers' (1 for any that give none),
+ * its `pacing` is the first driver's that has one, and its name lists `<client>:<driver name>`.
+ * If any client fails to open, the ones that did open are closed and the open throws naming that client.
+ * Closing returns the first client's trace as `trace` and every client's in `traces`. Without
+ * a `focus`, `screenshot` and `record` use the first driver that supports them and `text` joins every
+ * client's text.
+ *
+ * @throws Error when `drivers` is empty.
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const driver = combineDrivers<{ member: Page; api: HttpClient }>({
+ *   member: playwrightDriver(),
+ *   api: httpDriver('http://127.0.0.1:4000')
+ * });
  */
 export declare function combineDrivers<M extends Record<string, unknown>>(drivers: {
     [K in keyof M]: Driver<M[K]>;
 }, options?: CombineDriversOptions): Driver<M>;
-/** A state implementation written for one client's context, lifted to a multi-client context. */
+/**
+ * Lifts a state implementation written against one client's context to the combined context and
+ * sets its `client`, so its screenshot comes from that client's screen.
+ */
 export declare function onClient<K extends string, C>(client: K, impl: StateImplementation<C>): StateImplementation<Record<K, C>>;
-/** An event implementation written for one client's context, lifted to a multi-client context. */
+/**
+ * Lifts an event implementation written against one client's context to the combined context and
+ * sets its `client`, so its clip comes from that client's screen and its timeline entries are tagged with it.
+ */
 export declare function onClient<K extends string, C>(client: K, impl: EventImplementation<C>): EventImplementation<Record<K, C>>;
-/** Part of an implementation: what one client does and shows, or what spans clients. */
+/** Part of an implementation (any subset of its fields): what one client does and shows, or what spans clients. */
 export type ImplementationPart<C> = Partial<Implementation<C>>;
 /**
  * Merge per-client implementations into one. Each client's part is written against that client's
@@ -30,6 +51,21 @@ export type ImplementationPart<C> = Partial<Implementation<C>>;
  * driver work unchanged; `shared` holds what needs several clients at once (read an id on one
  * screen, act on it on another). `shared.setup` runs first (seed data), then each client's setup
  * in the order the clients are listed. An event or state implemented twice is an error.
+ *
+ * A seed with the same name in several parts runs `shared`'s first, then each client's; the combined
+ * seed's `at` is the first one's and its `how` joins all of them. Correlation ids are pooled,
+ * and `canStart` returns the first reason any part gives.
+ *
+ * @param parts the implementation of each client, against that client's own context.
+ * @param shared events, states, seeds and setup that need several clients at once, against the combined context.
+ * @throws Error when an event or state is implemented by more than one part (including `shared`).
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const implementation = combineImplementations<{ member: SignalContext; api: HttpClient }>(
+ *   { member: { events: {}, states: {} }, api: { events: {}, states: {} } },
+ *   { setup: async ({ api }) => void (await api.post('/test/reset')) }
+ * );
  */
 export declare function combineImplementations<M extends Record<string, unknown>>(parts: {
     [K in keyof M]?: ImplementationPart<M[K]>;
@@ -37,6 +73,9 @@ export declare function combineImplementations<M extends Record<string, unknown>
 /**
  * Merge parts of one implementation written against the same context, such as one file per area
  * of a large chart (sign-up, checkout, results). Events, states and seeds must each be
- * implemented once; setups run in order, and correlation ids are pooled.
+ * implemented once; setups run in order, `canStart` returns the first reason any part gives, and
+ * correlation ids are pooled without duplicates.
+ *
+ * @throws Error when an event, state or seed appears in more than one part.
  */
 export declare function mergeImplementations<C>(...parts: ImplementationPart<C>[]): Implementation<C>;

package/dist/core/src/run/clients.js

@@ -1,3 +1,14 @@
+/**
+ * @module Multi-client composition
+ *
+ * Lets one run drive several clients at once (a phone, a desktop browser, an API) by combining their
+ * drivers into one driver whose context is a record keyed by client name, and their implementations
+ * into one implementation. Each event and state records which client it acts on, which decides whose
+ * screen is photographed and recorded. Owns no driver behaviour of its own; it only routes to the
+ * drivers it is given.
+ *
+ * @see docs/statecharts.md
+ */
 import path from 'node:path';
 const inClientDirectory = (file, client) => path.join(path.dirname(file), client, path.basename(file));
 /**
@@ -7,7 +18,21 @@ const inClientDirectory = (file, client) => path.join(path.dirname(file), client
  * act on (`onClient`, `combineImplementations`), so screenshots and clips come from that client's
  * screen. Timeline entries are tagged with the client that made them.
  *
- *   combineDrivers({ member: webdriverDriver(appiumIos), operator: playwrightDriver(), api: httpDriver(url) })
+ * The combined driver's `concurrency` is the smallest of the drivers' (1 for any that give none),
+ * its `pacing` is the first driver's that has one, and its name lists `<client>:<driver name>`.
+ * If any client fails to open, the ones that did open are closed and the open throws naming that client.
+ * Closing returns the first client's trace as `trace` and every client's in `traces`. Without
+ * a `focus`, `screenshot` and `record` use the first driver that supports them and `text` joins every
+ * client's text.
+ *
+ * @throws Error when `drivers` is empty.
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const driver = combineDrivers<{ member: Page; api: HttpClient }>({
+ *   member: playwrightDriver(),
+ *   api: httpDriver('http://127.0.0.1:4000')
+ * });
  */
 export function combineDrivers(drivers, options = {}) {
     const names = Object.keys(drivers);
@@ -95,6 +120,7 @@ export function combineDrivers(drivers, options = {}) {
     };
 }
 const scoped = (tools, client) => ({ ...tools, timeline: tools.timeline.for(client) });
+/** Lifts a state or an event implementation to a client of a multi-client context (see the overloads above); a value with `recognize` is a state. */
 export function onClient(client, impl) {
     if ('recognize' in impl) {
         const { recognize, lookIn, settle, checks, ...rest } = impl;
@@ -121,6 +147,21 @@ export function onClient(client, impl) {
  * driver work unchanged; `shared` holds what needs several clients at once (read an id on one
  * screen, act on it on another). `shared.setup` runs first (seed data), then each client's setup
  * in the order the clients are listed. An event or state implemented twice is an error.
+ *
+ * A seed with the same name in several parts runs `shared`'s first, then each client's; the combined
+ * seed's `at` is the first one's and its `how` joins all of them. Correlation ids are pooled,
+ * and `canStart` returns the first reason any part gives.
+ *
+ * @param parts the implementation of each client, against that client's own context.
+ * @param shared events, states, seeds and setup that need several clients at once, against the combined context.
+ * @throws Error when an event or state is implemented by more than one part (including `shared`).
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const implementation = combineImplementations<{ member: SignalContext; api: HttpClient }>(
+ *   { member: { events: {}, states: {} }, api: { events: {}, states: {} } },
+ *   { setup: async ({ api }) => void (await api.post('/test/reset')) }
+ * );
  */
 export function combineImplementations(parts, shared = {}) {
     const clients = Object.keys(parts);
@@ -197,7 +238,10 @@ export function combineImplementations(parts, shared = {}) {
 /**
  * Merge parts of one implementation written against the same context, such as one file per area
  * of a large chart (sign-up, checkout, results). Events, states and seeds must each be
- * implemented once; setups run in order, and correlation ids are pooled.
+ * implemented once; setups run in order, `canStart` returns the first reason any part gives, and
+ * correlation ids are pooled without duplicates.
+ *
+ * @throws Error when an event, state or seed appears in more than one part.
  */
 export function mergeImplementations(...parts) {
     const events = {};

package/dist/core/src/run/execute.d.ts

@@ -17,6 +17,7 @@ export type Shard = {
 };
 /** What a run reports about: the spec, the scope, and the implementation's metadata. */
 export type RunContext<C> = {
+    /** The loaded charts. Their files are re-read (to hash them into `specVersion`) when the manifest is built. */
     bundle: SpecBundle;
     composition: Composition;
     graph: ChartGraph;
@@ -24,20 +25,27 @@ export type RunContext<C> = {
     implementation: Implementation<C>;
     /** The journeys of the plan, as the paths they are cut into; journeys are reported from them. */
     journeys?: PlannedJourney[];
+    /** The plan's seeds, reported in the manifest with the paths that start from and verify each. */
     seeds?: PlannedSeed[];
+    /** How a business event name is recognised, by name; see `EventMatcher`. */
     eventMatchers?: Record<string, EventMatcher>;
     privacy?: PrivacyRules;
     /** Recorded in the manifest as the run's environment. */
     environment?: Record<string, unknown>;
 };
+/** Everything `runPaths` needs: the `RunContext`, the paths to run and how to run them. */
 export type RunOptions<C> = RunContext<C> & {
+    /** The whole plan, in plan order. Paths marked `skipRun` are reported but not run. The manifest covers all of them. */
     paths: PlannedPath[];
     driver: Driver<C>;
     mode: RunMode;
     /** Runs land in `<outputRoot>/<run-id>/`. */
     outputRoot: string;
+    /** Whether a failed path runs a second time to tell flaky from broken; true unless `false`. */
     retry?: boolean;
+    /** How long to wait for a state to be recognised after an event, in milliseconds; 45 000 when omitted. */
     stepTimeoutMs?: number;
+    /** Where business events come from. Sources named with a `log:` prefix are treated as log files, not CloudEvents sources. */
     eventSources?: EventSource[];
     /** Path attempts that run at once, capped by the driver's `concurrency`; 1 when omitted. */
     workers?: number;
@@ -48,7 +56,10 @@ export type RunOptions<C> = RunContext<C> & {
         runDir: string;
         outcomes: Record<string, PathOutcome>;
     };
+    /** Receives progress lines; writes to stdout when omitted. */
     log?: (line: string) => void;
+    /** Receives privacy-checked manifest snapshots as paths and steps change. */
+    onProgress?: (manifest: Manifest) => void;
 };
 type StepResult = {
     transition: string;
@@ -83,44 +94,68 @@ type Observed = {
  */
 export type PathOutcome = {
     id: string;
+    /** The path's `key`; outcomes are matched across runs by it, not by `id`. */
     key: string;
+    /** `failed` when the last attempt failed, `flaky` when the first failed and the retry passed, `not-reached` when the path stopped at a blocked event, else `passed`. */
     status: Status;
     attempts: Attempt[];
     steps: StepResult[];
     stoppedAt: string | null;
     observed: Observed[];
+    /** Where and why the last attempt failed; `null` when it did not. */
     failure: {
         state: string;
         recognizer: RecognizerResult | null;
         looksLike: string[];
         shot: Image | null;
     } | null;
+    /** Privacy findings from the text the driver reported; they fail the run. */
     leaks: string[];
+    /** Wall-clock milliseconds for all attempts of the path. */
     durationMs: number;
     /** How long the last attempt took to seed (or set up) and recognise its start. */
     setupMs?: number;
     /** The run the outcome was taken from, when it was reused rather than run again. */
     reusedFrom?: string;
 };
-/** A rough cost of a path before it has ever run: setting it up, then each step. */
+/** A rough cost in milliseconds of a path that has never run (5 s to set up, 2.5 s a step); used to order and shard paths. */
 export declare const estimateMs: (p: PlannedPath) => number;
 /**
  * The paths one shard runs: longest first onto the least loaded shard, by the plan alone, so
  * every machine computes the same split. Paths reported without running go to the first shard.
  */
 export declare function shardPaths(paths: PlannedPath[], shard: Shard): PlannedPath[];
-/** The plan keys and outcomes a run wrote, for merging shards and reusing passed paths. */
+/**
+ * Reads the `outcomes.json` of a run directory: the run id and each finished path's outcome by key.
+ * Returns `null` when the file is missing or unreadable, never throws.
+ */
 export declare function readOutcomes(runDir: string): {
     runId: string;
     outcomes: Record<string, PathOutcome>;
 } | null;
-/** How long each path took in the newest run under `outputRoot` that recorded it, by path key. */
+/**
+ * Milliseconds each path took, by path key, taken from the newest of the last 10 runs under
+ * `outputRoot` that ran it (outcomes reused from elsewhere are ignored). Empty when the directory
+ * does not exist. `runPaths` uses it to start the slowest paths first.
+ */
 export declare function durationHistory(outputRoot: string): Record<string, number>;
-/** The newest run under `outputRoot` that wrote outcomes. */
+/** The directory of the newest run under `outputRoot` that wrote `outcomes.json` (run ids sort by time), or `null`. */
 export declare function latestRun(outputRoot: string): string | null;
 /**
- * Fold path outcomes into the run's report, in plan order: the same plan and outcomes always give
- * the same manifest, however many workers ran them, in whatever order they finished.
+ * Folds path outcomes into the run's manifest object, in plan order: the same plan and outcomes
+ * always give the same manifest, however many workers ran them, in whatever order they finished.
+ *
+ * A state or transition is `passed` when a path reached it, `flaky` when only a flaky path did,
+ * `failed` when any failure touched it (a failed check fails its state), else `not-reached`. Reaching a
+ * state also marks its ancestors reached. The whole manifest is scanned for privacy findings, and any
+ * finding sets `privacy.passed` to false. Reads the chart files (for `specVersion`) and runs `git`
+ * in the current directory (for `commit` and `branch`, `null` when that fails). Apart from the
+ * wall-clock fields (`finishedAt`, `updatedAt`, `durationMs`) and those that depend on the working
+ * directory (`commit`, `branch`, `specDirectory`), two folds of the same outcomes are identical.
+ *
+ * @param outcomes finished or in-progress outcomes by path key; a path with none is `queued` or `running`.
+ * @param run.activePaths ids of the paths in flight; they are reported `running` and not counted complete.
+ * @param run.extra extra fields merged into `run` of the manifest (workers, shard, reused, mergedFrom).
  */
 export declare function buildManifest<C>(context: RunContext<C>, paths: PlannedPath[], outcomes: Map<string, PathOutcome>, run: {
     id: string;
@@ -235,6 +270,7 @@ export declare function buildManifest<C>(context: RunContext<C>, paths: PlannedP
         key: string;
         name: string;
         kind: PlannedPath["kind"];
+        progress?: "queued" | "running" | "complete";
         status: Status;
         attempts: Attempt[];
         steps: StepResult[];
@@ -305,8 +341,13 @@ export declare function buildManifest<C>(context: RunContext<C>, paths: PlannedP
         mermaid: string;
     };
 };
+/** The manifest object `buildManifest` returns; it is what `manifest.json` contains. */
 export type Manifest = ReturnType<typeof buildManifest>;
-/** Write a run's manifest, reports and outcomes; returns the manifest. */
+/**
+ * Writes a run's `junit.xml`, `ctrf.json`, `chart.mmd`, `outcomes.json` and `manifest.json` into
+ * `runDir` (each through a temporary file and a rename, so a reader never sees half a file) and returns
+ * the manifest. `outcomes.json` holds only finished paths, not those in `run.activePaths`.
+ */
 export declare function writeRun<C>(runDir: string, context: RunContext<C>, paths: PlannedPath[], outcomes: Map<string, PathOutcome>, run: Parameters<typeof buildManifest>[3]): {
     $schema: string;
     schemaVersion: number;
@@ -409,6 +450,7 @@ export declare function writeRun<C>(runDir: string, context: RunContext<C>, path
         key: string;
         name: string;
         kind: PlannedPath["kind"];
+        progress?: "queued" | "running" | "complete";
         status: Status;
         attempts: Attempt[];
         steps: StepResult[];
@@ -480,9 +522,14 @@ export declare function writeRun<C>(runDir: string, context: RunContext<C>, path
     };
 };
 /**
- * Compose the outcomes of several runs of the same plan (the shards of one run, or a rerun of the
- * paths that failed) into one run, folded in plan order. Media are copied in, so the merged run
- * stands on its own. Later runs win when two ran the same path.
+ * Composes the outcomes of several runs of the same plan (the shards of one run, or a rerun and
+ * the run before it) into one new run directory under `options.outputRoot`, folded in plan order. Media are
+ * copied in, so the merged run stands on its own. Later entries of `runDirs` win when two ran the same
+ * path; outcomes whose key is not in `paths` are ignored. The merged run's mode and driver name are
+ * taken from the run manifests unless `options` gives them.
+ *
+ * @returns the new `runDir`, its `manifest`, and `ok` (privacy passed and no path failed).
+ * @throws Error when a run directory has no `outcomes.json`.
  */
 export declare function mergeRuns<C>(context: RunContext<C>, paths: PlannedPath[], runDirs: string[], options: {
     outputRoot: string;
@@ -595,6 +642,7 @@ export declare function mergeRuns<C>(context: RunContext<C>, paths: PlannedPath[
             key: string;
             name: string;
             kind: PlannedPath["kind"];
+            progress?: "queued" | "running" | "complete";
             status: Status;
             attempts: Attempt[];
             steps: StepResult[];
@@ -668,12 +716,22 @@ export declare function mergeRuns<C>(context: RunContext<C>, paths: PlannedPath[
     ok: boolean;
 };
 /**
- * Run planned paths against a system through a driver. Paths start from their seed (or the
- * implementation's `setup`) and run on a pool of workers, longest first, each attempt in its own
- * driver context; every state is recognised from the outside after every step; a failed path is
- * retried once to tell flaky from broken. The manifest is rewritten as each path finishes, from
- * all outcomes so far in plan order, so a crash keeps what ran and the order paths finished in
- * never changes the report.
+ * Runs planned paths against a system through a driver and writes the run to
+ * `<outputRoot>/<timestamp>-<mode>/`. Paths start from their seed (or the implementation's
+ * `setup`) and run on a pool of workers, longest first (by earlier timings, else `estimateMs`),
+ * each attempt in its own driver context; every state is recognised from the outside after every step;
+ * a failed path is retried once to tell flaky from broken. The manifest is rewritten as each path
+ * finishes, from all outcomes so far in plan order, so a crash keeps what ran and the order paths
+ * finished in never changes the report.
+ *
+ * Workers are capped by `driver.concurrency` (1 if the driver gives none) and by the number of paths.
+ * Without `implementation.correlate`, a run on several workers reports business events as "no
+ * signal" rather than guess which attempt they belong to. While it runs it installs
+ * `uncaughtException` and `unhandledRejection` handlers that log and swallow stray errors from
+ * drivers, and removes them when it ends. Passed paths of `options.reuse` are kept instead of re-run.
+ *
+ * @returns the run directory, the final manifest, and `ok` (privacy passed and no path failed).
+ * @see docs/statecharts.md
  */
 export declare function runPaths<C>(options: RunOptions<C>): Promise<{
     runDir: string;
@@ -779,6 +837,7 @@ export declare function runPaths<C>(options: RunOptions<C>): Promise<{
             key: string;
             name: string;
             kind: PlannedPath["kind"];
+            progress?: "queued" | "running" | "complete";
             status: Status;
             attempts: Attempt[];
             steps: StepResult[];