ostia 0.2.9 → 0.2.11

package/index.d.ts

@@ -1,119 +1,24 @@
 export declare function defineConfig(config: OstiaConfigInput): OstiaConfigInput;
 
-export interface CommandSpec {
-    command: string | string[];
-    label?: string;
-    /** Overrides `TimeOptions.prepare` for this command. */
-    prepare?: PrepareHook;
-    /** Overrides `TimeOptions.timeSource` for this command. */
-    timeSource?: TimeSource;
-    /** Overrides `TimeOptions.timeoutMs` for this command. */
-    timeoutMs?: number;
-    /** Overrides `TimeOptions.ignoreExitCodes` for this command. */
-    ignoreExitCodes?: number[];
-}
-
-export interface TimeOptions {
-    commands: (string | string[] | CommandSpec)[];
-    /** Runs before every trial of every command (warmup and instrumented
-     * trials included), unmeasured, in `cwd`/`env`: a command string / argv
-     * array spawned and awaited, or a function. hyperfine's `--prepare`. A
-     * `CommandSpec.prepare` overrides it per command. */
-    prepare?: PrepareHook;
-    /** Take every command's timing from a number in its own output instead of
-     * its wall clock (e.g. a build tool's `built in 342ms` line, which
-     * excludes runtime startup). A `CommandSpec.timeSource` overrides it per
-     * command. The parsed value becomes `timing.samples`; each trial keeps
-     * `wallNs` too. */
-    timeSource?: TimeSource;
-    /** Exact trial count. When set, `budgetMs` is ignored. */
-    samples?: number;
-    /** Wall-clock time budget for the sampling loop, ms (default: a
-     * hyperfine-style ~3s min-total-time loop when neither `samples` nor
-     * `budgetMs` is given). */
-    budgetMs?: number;
-    /** Hard floor on trials when no exact `samples` count is given. */
-    minSamples?: number;
-    warmup?: number;
-    /** Round-robin trials across commands (one trial per command, repeated)
-     * instead of running each command's whole trial loop to completion before
-     * the next command starts. Default: true when 2+ commands are given (a
-     * single command has nothing to interleave against). Spreads any drift
-     * over the run's wall-clock span (thermal throttling, a noisy neighbor
-     * process) evenly across every command instead of favoring whichever ran
-     * first or last. */
-    interleave?: boolean;
-    cwd?: string;
-    env?: Record<string, string>;
-    cpu?: boolean;
-    heap?: boolean;
-    cpuIntervalUs?: number;
-    outDir?: string;
-    /** Measure this machine's noise floor before the first command (default:
-     * true) and stamp it on the document as `environment`. Set false to skip
-     * the ~200ms reference measurement. */
-    noiseCheck?: boolean;
-    /** Kills a trial (or prepare hook) that hasn't finished after this many
-     * ms, with SIGKILL. No default: an unset `timeoutMs` never times out. A
-     * timed-out trial contributes no sample; if every trial of a command times
-     * out, that command has no timing stats. `CommandSpec.timeoutMs` overrides
-     * it per command. */
-    timeoutMs?: number;
-    /** Aborting cancels the run: in-flight trials are killed with SIGKILL, no
-     * further trials are scheduled, and `time()` resolves (never rejects)
-     * with the document built from whatever measurements had already
-     * completed, plus an `aborted` warning on the document's last
-     * measurement. */
-    signal?: AbortSignal;
-    /** Exit codes to treat as success (hyperfine's `--ignore-failure`): a
-     * trial exiting with one of these still contributes its sample and gets
-     * no `nonzero-exit` warning, as if it had exited 0. `CommandSpec.ignoreExitCodes`
-     * overrides it per command. */
-    ignoreExitCodes?: number[];
-}
-
-export declare function time(opts: TimeOptions): Promise<ProfileDocument>;
-
-interface ProfileOptions {
-    intervalUs?: number;
-    origin?: "inspector" | "jsc";
-    /** `profile()` runs `fn` in this process, so there's no child to kill: an
-     * already-aborted signal skips the profiler instrumentation entirely and
-     * just calls `fn` plain (still returning its `result`), with an `aborted`
-     * warning in place of CPU evidence. A signal that fires mid-capture can't
-     * interrupt `fn` once it's running. */
-    signal?: AbortSignal;
-}
-
-interface ProfileResult<T> {
-    result: T;
-    measurement: Measurement;
-    document: ProfileDocument;
-}
-
-export declare function profile<T>(fn: () => T | Promise<T>, opts?: ProfileOptions): Promise<ProfileResult<T>>;
-
 export interface WorkloadConfig {
     label?: string;
     command?: string[];
     suites?: string[];
-    /** `command` only. Globs of the files this command's timing depends on:
-     * `ostia ci` reuses a cached run while their contents are unchanged.
-     * Omitted, the workload always reruns; `[]` declares it depends on
-     * nothing and caches until the command or config changes. */
+    /** `command` only. Globs of the files the timing depends on: `ostia ci`
+     * reuses a cached run while their contents are unchanged. Omitted, the
+     * workload always reruns; `[]` caches until the command or config changes. */
     inputs?: string[];
     /** `command` only. Runs before every trial (warmup included), unmeasured:
-     * a command string / argv array in both `.ts` and JSON config, or a
-     * function in `ostia.config.ts`. A function-form hook makes the workload
-     * uncacheable for `ostia ci` (its effect can't be fingerprinted), so it
-     * always executes. */
+     * a command string / argv array, or in `ostia.config.ts` a function. A
+     * function makes the workload uncacheable for `ostia ci`. */
     prepare?: PrepareHook;
     /** `command` only. Take timing from a number in the command's own output
      * instead of its wall clock; see `TimeSource`. */
     timeSource?: TimeSource;
-    /** `command` only. Kills a trial (or prepare hook) that hasn't finished
-     * after this many ms. Overrides `ostia ci`'s 10-minute default per
-     * workload. */
+    /** `command`: kills a trial (or prepare hook) after this many ms.
+     * `suites`: kills a suite file's (or isolated task's) process after this
+     * many ms, overriding `bench.timeoutMs`. Overrides `ostia ci`'s 10-minute
+     * default. */
     timeoutMs?: number;
     /** `command` only. Exit codes to treat as success; see
      * `TimeOptions.ignoreExitCodes`. */
@@ -121,10 +26,9 @@ export interface WorkloadConfig {
 }
 
 interface BenchConfig {
-    /** Suite file globs, resolved with Bun.Glob against the config's directory
-     * (e.g. "bench/**\/*.bench.ts"). Ignored when suite files are also given
-     * on the command line - CLI args replace this list rather than merging
-     * with it. */
+    /** Suite file globs, resolved against the config's directory (e.g.
+     * "bench/**\/*.bench.ts"). Suite files given on the command line replace
+     * this list. */
     suites?: string[];
     preload?: string[];
     /** Extra flags for the `bun` process that runs each suite file; see
@@ -142,18 +46,37 @@ interface BenchConfig {
     filter?: string;
     isolate?: boolean;
     outDir?: string;
-    /** Kills a suite file's (or isolated task's) subprocess if it hasn't
-     * finished after this many ms. Overrides `ostia ci`'s 10-minute default. */
+    /** Kills a suite file's (or isolated task's) subprocess after this many
+     * ms; overrides `ostia ci`'s 10-minute default. */
     timeoutMs?: number;
 }
 
+export interface AbConfig {
+    /** Shell command(s) run once in a freshly extracted base tree, e.g. to
+     * build gitignored files the suites import; see `AbOptions.baseSetup`.
+     * `--base-setup` replaces this list. */
+    setup?: string | string[];
+    /** Base trees to keep cached; see `AbOptions.keepTrees`. `--keep-trees`
+     * overrides. Default: 5. */
+    keepTrees?: number;
+    /** Compare retained heap per call; see `AbOptions.alloc`. `--alloc` /
+     * `--no-alloc` override. `bench.alloc` doesn't apply to `ab`. */
+    alloc?: boolean;
+    /** Compare peak RSS of the first call; see `AbOptions.peakMem`.
+     * `--peak-mem` / `--no-peak-mem` override. `bench.peakMem` doesn't apply
+     * to `ab`. */
+    peakMem?: boolean;
+    /** Memory verdict threshold, percent; see `AbOptions.memThresholdPct`.
+     * `--mem-threshold` overrides. Default: 10. */
+    memThresholdPct?: number;
+}
+
 export interface OstiaConfig {
-    /** `command` workloads: exact trial count, same as `time()`'s `samples`.
-     * Unset, the `budgetMs`/`minSamples` loop decides. */
+    /** `command` workloads: exact trial count; see `time()`. */
     samples?: number;
-    /** `command` workloads: wall-clock sampling budget, ms; see `time()`. */
+    /** `command` workloads: sampling budget in ms; see `time()`. */
     budgetMs?: number;
-    /** `command` workloads: hard floor on trials; see `time()`. */
+    /** `command` workloads: floor on trials; see `time()`. */
     minSamples?: number;
     warmup: number;
     outDir: string;
@@ -162,20 +85,15 @@ export interface OstiaConfig {
     thresholds: Thresholds;
     workloads: WorkloadConfig[];
     bench?: BenchConfig;
-    /** `ostia ci`'s policy when a configured workload has no matching row in
-     * the baseline (by workload id): `"fail"` exits 2 naming the baseline
-     * file, `"warn"` lists it in the report without affecting the exit code.
-     * Unset (the default): `"fail"` when *every* configured workload is
-     * missing, `"warn"` otherwise - a totally stale/wrong baseline is a hard
-     * error, a handful of new workloads next to an otherwise-matching
-     * baseline is not. */
+    ab?: AbConfig;
+    /** `ostia ci`'s policy for a workload with no matching baseline row (by
+     * workload id): `"fail"` exits 2 naming the baseline file, `"warn"` lists
+     * it in the report. Unset: `"fail"` when every workload is missing (a
+     * stale or wrong baseline), `"warn"` otherwise. */
     onMissingBaseline?: "warn" | "fail";
-    /** Measures this machine's noise floor once per `ostia ci` invocation
-     * (default true) and stamps it on the candidate document as
-     * `environment`, the same reference measurement `time()`/`bench()` run -
-     * so `compare`'s noise-floor threshold widening applies to `ci` too, not
-     * only to ad hoc `time`/`bench` runs. `--no-noise-check` overrides this
-     * to false per invocation. */
+    /** Measure the machine's noise floor once per `ostia ci` run (default
+     * true) and stamp it on the candidate document, so `compare` widens its
+     * thresholds accordingly. `--no-noise-check` overrides this per run. */
     noiseCheck?: boolean;
 }
 
@@ -188,11 +106,9 @@ export interface Thresholds {
     frameSelfPct: number;
     heapTypePct: number;
     minFrameSelfUs: number;
-    /** Significance level for the Mann-Whitney p-value: a `regressed` /
-     * `improved` verdict also requires `pValue < alpha`. */
+    /** A `regressed` / `improved` verdict also requires Mann-Whitney `pValue < alpha`. */
     alpha: number;
-    /** Bootstrap resample rounds for the timing CI. Capped work regardless:
-     * see `bootstrapMedianDiffCi`. */
+    /** Bootstrap resample rounds for the timing CI. */
     bootstrapIterations: number;
 }
 
@@ -204,6 +120,8 @@ export interface CompareResult {
         baseOnly: Workload[];
         candOnly: Workload[];
     };
+    /** Every task on either side; see `ProfileDocument.compared`. */
+    compared: ComparedTask[];
     summary: ComparisonSummary;
 }
 
@@ -217,36 +135,31 @@ export interface ProfileDocument {
         os: string;
         arch: string;
     };
+    /** ISO timestamp; metadata only, never part of an id. */
     createdAt: string;
     workloads: Workload[];
     measurements: Measurement[];
     comparisons?: Comparison[];
-    /** Aggregate across `comparisons`, from `compareDocuments`/`ostia compare`/
-     * `ostia ci`. Additive, no schema bump. Absent wherever `comparisons` is. */
+    /** Aggregate across `comparisons`; present wherever `comparisons` is. */
     comparisonSummary?: ComparisonSummary;
-    /** Workload ids present on only one side of a `compareDocuments` call -
-     * candidates matched by id gone missing from the baseline, or vice versa.
-     * Additive, no schema bump; absent wherever `comparisons` is. Ids only
-     * (not full `Workload`s) to keep the document small; `ostia compare`'s
-     * printed report resolves labels from the two source documents directly. */
+    /** Workload ids on only one side of the comparison; present wherever
+     * `comparisons` is. */
     unmatched?: {
         baseOnly: string[];
         candOnly: string[];
     };
-    /** Machine conditions when this document was measured. Additive, no
-     * schema bump. Absent when `noiseCheck: false` (or `--no-noise-check`)
-     * skipped the reference measurement. */
+    /** Every task on either side of the comparison, one entry each: what
+     * `--format markdown` prints, flat for scripts. Present wherever
+     * `comparisons` is. */
+    compared?: ComparedTask[];
+    /** Machine conditions at measurement time; absent when the noise check was
+     * skipped. */
     environment?: Environment;
-    /** Run-level result of a paired A/B run (`ostia ab` / `ab()`): what the
-     * candidate was paired against and the gate's verdict. Additive, no schema
-     * bump. Present only on documents from `ab()`, whose measurements are
+    /** Run-level result of `ostia ab` / `ab()`, whose measurements are
      * `phase: "paired"`. */
     ab?: AbSummary;
-    /** Repo state when this document was measured, from `git rev-parse` /
-     * `git status --porcelain` in the process's cwd. Additive, no schema
-     * bump. Absent outside a git repo (or when `git` itself isn't
-     * available). Metadata only: never part of any fingerprint or id, so a
-     * commit or a dirty working tree never orphans a cached run or baseline. */
+    /** Repo state of the process's cwd; absent outside a git repo. Never part of
+     * an id or fingerprint, so a commit or dirty tree doesn't orphan a baseline. */
     git?: GitMetadata;
 }
 
@@ -257,12 +170,15 @@ interface GitMetadata {
 }
 
 interface NoiseFloor {
-    /** `mad / median` of the reference workload's trial times, as a percent -
-     * how noisy this machine is right now, independent of what's being
-     * measured. */
+    /** `mad / median` of a reference workload, percent: how noisy the machine is
+     * right now, independent of what's measured. */
     floorPct: number;
     referenceMedianNs: number;
     samples: number;
+    /** How much slower (positive) the reference ran at the end of the run than
+     * at the start, percent: the machine's drift over the run. Absent when the
+     * run didn't re-measure it (`profile()`, older documents). */
+    driftPct?: number;
 }
 
 interface Environment {
@@ -274,69 +190,51 @@ interface Environment {
 }
 
 export interface Workload {
-    /** Identifies what is measured, not where or when it ran: for a
-     * `subprocess` workload, a hash of the command argv, `prepare`
-     * (command form or function source), and `timeSource` spec -
-     * deliberately excluding `process.cwd()`, so a baseline saved from one
-     * checkout (a CI runner, a different worktree) still matches a candidate
-     * measured from another. For an `inprocess` workload, a hash of the
-     * function source (or, for a registry entry, the file/task name plus
-     * `params`). `label`, `description`, and `baseline` are annotations and
-     * never affect it. */
+    /** Identifies what is measured, not where or when. Subprocess: a hash of
+     * argv, `prepare` and `timeSource`, excluding `process.cwd()`. In-process: a
+     * hash of the function source, or for a registry entry the file, task name
+     * and `params`. Annotations (`label`, `description`, `baseline`) never
+     * affect it. */
     id: string;
     kind: "subprocess" | "inprocess";
     label?: string;
     command?: string[];
-    /** Command form of the `prepare` hook that ran before every trial of this
-     * command (`ostia time --prepare`, `time({ prepare })`, config `prepare`).
-     * Part of the workload id: the same command with and without a prepare
-     * step measures different things. A function-form hook isn't
-     * serializable and is omitted here (its source text is still hashed into
-     * the id). */
+    /** Command-form `prepare` hook run before every trial; part of the id. A
+     * function-form hook isn't serializable and is omitted (its source is still
+     * hashed into the id). */
     prepare?: string[];
-    /** Where this command's timing samples came from when not the subprocess
-     * wall clock: a regex over the command's own output and the unit of the
-     * number it captures. Part of the workload id, so the same command timed
-     * by wall clock and by its own report are two workloads. */
+    /** Takes samples from a number in the command's own output instead of the
+     * wall clock; part of the id. */
     timeSource?: {
         pattern: string;
         group?: number;
         unit?: "ns" | "us" | "ms" | "s";
     };
-    /** `task` is the "group/name" id the bench registry assigns; `group` is the
-     * enclosing `group()` name when there is one. Renderers prefer `group` over
-     * splitting `task` on "/", so task names may contain slashes. */
+    /** `task` is the registry's "group/name" id; `group` is the enclosing
+     * `group()` name. Renderers prefer `group` over splitting `task` on "/". */
     entry?: {
         file: string;
         task: string;
         group?: string;
     };
-    /** Marks this task as the in-run Relative reference for its group (see
-     * `task(name, fn, { baseline: true })`). At most one per group is
-     * meaningful; renderers use the first they encounter. */
+    /** The Relative reference for its group; renderers use the first one found. */
     baseline?: boolean;
-    /** What this task measures and why, from `task(name, fn, { description })`.
-     * Travels with the data so a reader of the document has intent, not just
-     * numbers. */
+    /** What this task measures and why, from `task(..., { description })`. */
     description?: string;
-    /** The enclosing group's `group(name, fn, { description })`. Repeated on every
-     * workload in the group so each record is self-contained. */
+    /** The enclosing group's description, repeated on every workload in it. */
     groupDescription?: string;
-    /** Whether this task ran in a subprocess dedicated to it alone (`isolate`
-     * on the task, its group, or the suite), vs. sharing its suite file's
-     * subprocess with other tasks. */
+    /** Ran in a subprocess of its own rather than sharing its suite file's. */
     isolated?: boolean;
-    /** Structured parameters this task point represents (e.g. `{ size: 800,
-     * impl: "fast" }`), from `task(name, fn, { params })` or a `sweep()` point.
-     * Lets renderers pivot and `compare` match on them instead of only on the
-     * task name. Part of the workload id when present, so two points that
-     * share a task name (a `sweep()`'s whole point) don't collide. */
+    /** From `task(..., { params })` or a `sweep()` point. Part of the id, so
+     * points sharing a task name don't collide. */
     params?: Record<string, string | number | boolean>;
-    /** From `task.skip()` or a `group.skip()` this task was inside. The runner
-     * never measures it, so this workload has no matching `Measurement`; a
-     * renderer prints it as a "- skipped" row instead of omitting it, and
-     * `compare` treats it as `unchanged` (with a `skipped` warning) rather
-     * than silently passing or failing to match it. */
+    /** Ids this task had under its former names (`task(..., { aliases })`), so
+     * `compare` and `ab` match a base measured before a rename. Never part of
+     * the id. */
+    formerIds?: string[];
+    /** From `task.skip()` / `group.skip()`: never measured, so no `Measurement`.
+     * Renderers print a "- skipped" row; `compare` treats it as `unchanged` with
+     * a `skipped` warning. */
     skipped?: boolean;
 }
 
@@ -355,38 +253,39 @@ interface Measurement {
     heap?: HeapEvidence;
     memory?: MemoryEvidence;
     jit?: JitTierBreakdown;
-    /** `phase: "paired"` only: the base side and the per-round ratios. The
-     * measurement's `timing` is the candidate side. */
+    /** `phase: "paired"` only; `timing` is then the candidate side. */
     paired?: PairedEvidence;
+    /** `phase: "paired"` only: the task threw on one side or both
+     * (`"both"`). Usually instead of `timing`/`paired`; when it threw in a
+     * confirmation repeat, `repeat` (from 1) says which, and `timing`/`paired`
+     * stay as the first process measured them. Either way the task isn't in
+     * `matched` or the geomean. */
+    threw?: {
+        side: "base" | "cand" | "both";
+        message: string;
+        repeat?: number;
+    };
     warnings: Warning[];
     artifacts: ArtifactRef[];
-    /** True when this timing measurement's trials were run round-robin against
-     * the other commands in the same `time()` call (`--interleave`, default on
-     * for 2+ commands) rather than run to completion before the next command
-     * started, so drift over the run's wall-clock span (thermal throttling, a
-     * noisy neighbor process) lands on every command equally instead of
-     * favoring whichever ran first or last. */
+    /** Trials ran round-robin with the other commands of the same `time()` call,
+     * so drift over the run hits every command equally. */
     interleaved?: boolean;
 }
 
 interface Trial {
     i: number;
     wallNs: number;
-    /** The command's self-reported time (ns) when the workload has a
-     * `timeSource`; `timing.samples` are these, not `wallNs`, in that case.
-     * `wallNs` stays alongside so a document keeps both. */
+    /** The command's self-reported time (ns) under a `timeSource`; these, not
+     * `wallNs`, are then the `timing.samples`. */
     reportedNs?: number;
     exitCode?: number;
     userNs?: number;
     systemNs?: number;
     maxRssBytes?: number;
-    /** Set when the trial was killed by `timeoutMs` before it exited on its
-     * own. `exitCode` is absent in that case: the kill signal, not the
-     * command, decided how the process ended. Contributes no sample. */
+    /** Killed by `timeoutMs`; `exitCode` is absent. Contributes no sample. */
     timedOut?: true;
-    /** Set when the workload has a `timeSource` and this trial's output didn't
-     * match its pattern. `reportedNs` is absent in that case (never a
-     * fallback to `wallNs`). Contributes no sample. */
+    /** Output didn't match the `timeSource` pattern; `reportedNs` is absent
+     * (never a `wallNs` fallback). Contributes no sample. */
     timeSourceNoMatch?: true;
 }
 
@@ -408,15 +307,11 @@ interface TimingStats {
     p75: number;
     /** 99th percentile, ns. */
     p99: number;
-    /** Median absolute deviation, ns: the median of `|sample - median|` across
-     * all samples. A robust spread measure that (unlike stddev) isn't skewed
-     * by the long right tail typical of wall-clock timings. */
+    /** Median absolute deviation, ns: a spread measure that, unlike stddev, the
+     * long right tail of wall-clock timings doesn't skew. */
     mad: number;
-    /** In-process trials batched into one timed block (see
-     * `measure/inprocess.ts`'s `sizeBatch`), set only when batching occurred.
-     * Absent for every subprocess timing measurement, and for an in-process
-     * one whose single call already cleared the batching threshold - a
-     * renderer treats an absent value the same as `1`. */
+    /** Calls batched into one timed block; absent (read as 1) unless batching
+     * occurred, and always absent for subprocess timing. */
     batch?: number;
 }
 
@@ -466,26 +361,22 @@ interface HeapEvidence {
 
 interface MemoryEvidence {
     origin: "resourceUsage" | "heapStats";
-    /** What a `phase: "memstats"` measurement measured: `"retained"` for
-     * `--alloc` (`bytesPerOp`), `"peak"` for `--peak-mem` (`peakBytes`).
-     * Absent on subprocess timing's `maxRssBytes`, and on `memstats`
-     * measurements written before this field existed, which are always
-     * `"retained"`. */
+    /** `memstats` only: `"retained"` (`--alloc`, `bytesPerOp`) or `"peak"`
+     * (`--peak-mem`, `peakBytes`). Absent means `"retained"` on older documents. */
     kind?: "retained" | "peak";
     /** Largest `Trial.maxRssBytes` across a timing measurement's trials. */
     maxRssBytes?: number;
-    /** Retained heap growth per call, from `ostia bench --alloc`: heap size
-     * delta (`bun:jsc`'s `heapStats().heapSize`, falling back to
-     * `process.memoryUsage().heapUsed`) around one batch bracketed by
-     * `Bun.gc(true)` on both sides, divided by the batch size. Garbage the
-     * calls create and drop is collected before the second reading, so this
-     * is what the calls keep alive (a leak check), not what they allocate. */
+    /** `--alloc`: heap growth per call across one batch bracketed by full GCs,
+     * so what the calls keep alive (a leak check), not what they allocate. */
     bytesPerOp?: number;
-    /** How far one call raised the process's RSS above where it started,
-     * garbage included, from `ostia bench --peak-mem`: median over 3 fresh
-     * processes, each making the task's first call after its `before` hooks
-     * and a full GC. A `peak-hidden` warning says when it may read low. */
+    /** `--peak-mem`: how far one call raised RSS, garbage included; median over
+     * 3 fresh processes. A `peak-hidden` warning says when it may read low. */
     peakBytes?: number;
+    /** In-process timing: the JS heap's size as of its last collection, just
+     * before the task's warmup and just after its last trial. Read without
+     * forcing a GC, so it never perturbs the timing. */
+    heapUsedBeforeBytes?: number;
+    heapUsedAfterBytes?: number;
 }
 
 interface JitTierBreakdown {
@@ -504,8 +395,7 @@ interface JitTierBreakdown {
 }
 
 interface PairedEvidence {
-    /** Rounds run: one base batch and one candidate batch each, alternating
-     * which goes first. */
+    /** One base batch and one candidate batch per round, alternating order. */
     rounds: number;
     /** Calls per side per round. */
     batch: number;
@@ -517,27 +407,48 @@ interface PairedEvidence {
     ratios: number[];
     medianRatio: number;
     /** 25th/75th percentile of `ratios`. */
-    p25: number;
-    p75: number;
-    /** Set when this process's rounds crossed the threshold: median ratio
-     * past `1 ± threshold` and on the same side of 1 in at least three
-     * quarters of rounds. */
+    ratioP25: number;
+    ratioP75: number;
+    /** Median ratio past `1 ± threshold` and on the same side of 1 in at least
+     * three quarters of rounds. */
     flagged?: "regressed" | "improved";
     /** Each fresh-process re-measurement of a flagged workload. */
     repeats?: {
         medianRatio: number;
-        p25: number;
-        p75: number;
+        ratioP25: number;
+        ratioP75: number;
         flagged?: "regressed" | "improved";
     }[];
     /** Set when `flagged` is: whether every repeat flagged the same way. */
     confirmed?: boolean;
     /** `flagged` when confirmed, else `"unchanged"`. */
     verdict: "regressed" | "improved" | "unchanged";
-    /** Whether the first call's return value was deep-equal on both sides
-     * (`Bun.deepEquals`, prototypes ignored). Informational: expected to be
-     * `false` for a change in behavior, never a failure. */
+    /** First call's return values were deep-equal on both sides; informational,
+     * never a failure. */
     sameOutput: boolean;
+    /** Set when the suite file's text differs from the base ref's copy, so
+     * each side may run a different benchmark (a fixed fixture, a changed
+     * input). With `sameOutput: false` too, the task is "not comparable": its
+     * verdict is `"unchanged"` and it's left out of the geomean. */
+    suiteChanged?: true;
+    /** `--alloc`: heap each call keeps alive after a full GC, per side, after
+     * a warmup batch; each the median of 3 fresh processes. */
+    retained?: MemoryChange;
+    /** `--peak-mem`: how far the task's first call raises RSS, per side,
+     * each the median of 3 fresh processes. */
+    peak?: MemoryChange;
+}
+
+interface MemoryChange {
+    baseBytes: number;
+    candBytes: number;
+    /** Past both `AbSummary.memory.thresholdPct` of the base and
+     * `floorBytes`; always `"unchanged"` on a not-comparable task. */
+    verdict: "regressed" | "improved" | "unchanged";
+    /** The smallest change that counts, bytes: 16 KiB over the batch's calls
+     * for `retained`; for `peak`, 1 MiB, or the freed memory a `peak-hidden`
+     * warning reports. */
+    floorBytes: number;
 }
 
 interface AbSummary {
@@ -545,6 +456,9 @@ interface AbSummary {
         ref: string;
         sha: string;
     };
+    /** Suite files, as given, that don't exist at the base ref: their tasks
+     * are all candidate-only. */
+    newSuites?: string[];
     rounds: number;
     thresholdPct: number;
     geomeanThresholdPct: number;
@@ -559,17 +473,31 @@ interface AbSummary {
     unconfirmed: number;
     /** Workloads whose first call returned different values on each side. */
     outputDiffers: number;
-    /** Geometric mean of each workload's median ratio, as a signed percent
-     * (negative: candidate faster on average). A flagged workload contributes
-     * the median over its main run and repeats. `null` when nothing was
-     * paired. */
+    /** Workloads whose suite file and output both changed (see
+     * `PairedEvidence.suiteChanged`); counted in `unchanged`, left out of
+     * `geomeanPct`. */
+    notComparable: number;
+    /** Workloads that threw on either side or both, and so weren't timed;
+     * not counted in `matched`. */
+    threw: number;
+    /** Present when any task had a memory reading (`--alloc`, `--peak-mem`):
+     * how many tasks' memory regressed or improved, on either reading. */
+    memory?: {
+        thresholdPct: number;
+        regressed: number;
+        improved: number;
+    };
+    /** Geometric mean of the workloads' median ratios, signed percent (negative:
+     * candidate faster); a flagged workload contributes its median over its main
+     * run and repeats. `null` when nothing was paired. */
     geomeanPct: number | null;
-    /** `"fail"` when any workload regressed (confirmed) or `geomeanPct`
-     * exceeds `geomeanThresholdPct`. */
+    /** `"fail"` when any workload regressed (confirmed), threw on the
+     * candidate side only, or `geomeanPct` exceeds `geomeanThresholdPct`, or
+     * any task's memory regressed. */
     verdict: "pass" | "fail";
 }
 
-declare const WARNING_CODES: readonly ["slow-first-run", "outliers-detected", "fast-command", "nonzero-exit", "artifact-missing", "empty-profile", "low-sample-count", "thin-comparison", "noisy-machine", "skipped", "jit-cold", "timeout", "aborted", "time-source-no-match", "environment-mismatch", "peak-hidden"];
+declare const WARNING_CODES: readonly ["slow-first-run", "outliers-detected", "fast-command", "nonzero-exit", "artifact-missing", "empty-profile", "low-sample-count", "thin-comparison", "noisy-machine", "skipped", "jit-cold", "timeout", "aborted", "time-source-no-match", "environment-mismatch", "peak-hidden", "suite-changed"];
 
 export type WarningCode = (typeof WARNING_CODES)[number];
 
@@ -594,19 +522,16 @@ export interface Comparison {
     timing?: {
         medianDeltaPct: number;
         meanDeltaPct: number;
-        /** 95% bootstrap confidence interval on the difference of medians,
-         * percent of the baseline median. Absent when either side had fewer
-         * than 5 samples (see the `thin-comparison` warning). */
+        /** 95% bootstrap CI on the difference of medians, percent of the baseline
+         * median. Absent below 5 samples a side (`thin-comparison`). */
         ci95?: [number, number];
-        /** Two-sided Mann-Whitney U p-value, tie-corrected normal approximation.
-         * Same absence condition as `ci95`. */
+        /** Two-sided Mann-Whitney U p-value; absent whenever `ci95` is. */
         pValue?: number;
-        /** Seed for the bootstrap's PRNG, so `ci95` is reproducible. */
+        /** Bootstrap PRNG seed, so `ci95` is reproducible. */
         seed?: number;
         verdict: "improved" | "regressed" | "unchanged";
     };
-    /** Attached when timing fell back to the point-estimate rule (thin
-     * samples) or otherwise carries a caveat about this comparison. */
+    /** Caveats about this comparison, e.g. a thin-sample point-estimate verdict. */
     warnings?: Warning[];
     frames?: {
         frameKey: string;
@@ -630,32 +555,81 @@ export interface Comparison {
         minFrameSelfUs: number;
         alpha: number;
         bootstrapIterations: number;
-        /** `max(timingPct, base.environment.noise.floorPct,
-         * cand.environment.noise.floorPct)` - the threshold timing was actually
-         * tested against, once machine noise widens it past `timingPct`. */
+        /** `max(timingPct, both documents' noise floors)`: what timing was tested against. */
         effectiveTimingPct: number;
     };
     verdict: "pass" | "fail";
 }
 
 interface ComparisonSummary {
-    /** `comparisons.length`: workloads present (and comparable) on both sides. */
+    /** `comparisons.length`. */
     matched: number;
     regressed: number;
     improved: number;
     unchanged: number;
-    /** Geometric mean of `cand/base` median ratios over matched timing
-     * comparisons, as a signed percent (negative: candidate faster on
-     * average). `null` when no comparison had a finite timing ratio. */
+    /** Geometric mean of `cand/base` median ratios, signed percent (negative:
+     * candidate faster). `null` when no comparison had a finite ratio. */
     geomeanPct: number | null;
-    /** Same value as `Comparison.thresholds.effectiveTimingPct` - one number
-     * for the whole document pair, since it depends only on `thresholds` and
-     * the two documents' `environment.noise.floorPct`, never per-workload. */
+    /** `Comparison.thresholds.effectiveTimingPct`, which is the same for the
+     * whole document pair. */
     effectiveTimingPct: number;
+    /** The machine's drift, percent, added to the timing threshold: the
+     * largest of each run's own drift (`NoiseFloor.driftPct`) and how far the
+     * reference loop's speed moved between the two runs. Absent when either
+     * document lacks a noise check. */
+    driftPct?: number;
     /** `"fail"` when any comparison's verdict is `"fail"`. */
     verdict: "pass" | "fail";
 }
 
+interface ComparedTask {
+    /** The candidate's workload id; the base's on a `missing-cand` task. */
+    workloadId: string;
+    /** Display name: the label, else the command, else the id. */
+    task: string;
+    group?: string;
+    /** Set when the base was matched through one of the task's `aliases`: the
+     * base's workload id and display name. */
+    renamedFrom?: {
+        workloadId: string;
+        task: string;
+    };
+    verdict: "improved" | "unchanged" | "regressed" | "missing-base" | "missing-cand";
+    /** The `Comparison` holding this task's frame and heap-type deltas and
+     * warnings; absent on a one-sided task. */
+    comparisonId?: string;
+    /** Whether the comparison passed the gate (timing, frames, heap types);
+     * absent on a one-sided task, which never fails it. */
+    pass?: boolean;
+    /** Absent on a one-sided or skipped task. */
+    timing?: {
+        unit: "ns";
+        baseMedian: number;
+        candMedian: number;
+        /** Absent on a document compared before ostia recorded it. */
+        baseSamples?: number;
+        candSamples: number;
+        medianDeltaPct: number;
+        /** Absent on a thin (<5 samples a side) comparison, with `pValue`. */
+        ci95?: [number, number];
+        pValue?: number;
+        /** `Comparison.thresholds.effectiveTimingPct`. */
+        thresholdPct: number;
+    };
+    /** Memory readings present on both sides; informational, never gated. */
+    memory?: MemoryDelta[];
+}
+
+interface MemoryDelta {
+    /** `heapUsedBefore`/`heapUsedAfter`: in-process heap around the timing
+     * run; `retained`: `--alloc`; `peak`: `--peak-mem`; `maxRss`: subprocess
+     * timing. */
+    reading: "heapUsedBefore" | "heapUsedAfter" | "retained" | "peak" | "maxRss";
+    baseBytes: number;
+    candBytes: number;
+    deltaPct: number;
+}
+
 export interface PrepareRun {
     phase: "warmup" | "timing" | "cpu" | "heap";
     index: number;
@@ -673,36 +647,36 @@ export interface TimeSource {
     unit?: TimeUnit;
 }
 
-interface InprocessTimingOptions {
-    /** Wall-clock budget for the sampling loop, per task (default: 500). The loop
-     * always runs for at least this long, unless `samples` is set. */
-    budgetMs?: number;
-    /** Exact trial count. When set, the budget is ignored and the loop runs
-     * exactly this many trials, however slow each one is - the in-process
-     * equivalent of `time()`'s `samples`. */
-    samples?: number;
-    /** Hard floor on the number of trials when no exact `samples` count is
-     * given. When set, the loop keeps sampling past the time budget until this
-     * many trials exist, however slow each one is. When unset, the floor is
-     * cost-aware (see `defaultSampleFloor`): as many trials as fit in the
-     * budget, capped at 20, but never below the rigor floor the task's per-trial cost
-     * earns it (3 at ≤1ms, rising to 10 for multi-second calls). */
-    minSamples?: number;
-    /** Warmup budget as a fraction of `budgetMs` (default: 0.1) - a fraction,
-     * not a call count, named `warmup` for cross-surface consistency with
-     * `time()`'s trial-count `warmup`; the two are genuinely different units (a
-     * fraction here, a count there), not papered over. Warmup always runs at
-     * least one call; for a task slower than the warmup budget that single call
-     * is the whole warmup. */
-    warmup?: number;
-    gc?: boolean;
-}
-
-export declare function keep(value: unknown): void;
+export type AbProgress = {
+    phase: "setup";
+    command: string;
+} | {
+    phase: "measure";
+    suite: number;
+    suites: number;
+    file: string;
+    /** Each suite runs twice, once with each side first. */
+    pass: number;
+    passes: number;
+    task: number;
+    tasks: number;
+    label: string;
+} | {
+    phase: "confirm";
+    repeat: number;
+    repeats: number;
+    label: string;
+} | {
+    phase: "memory";
+    run: number;
+    runs: number;
+    side: Side;
+    label: string;
+};
 
-interface AbOptions {
+export interface AbOptions {
     suites: string[];
-    /** Git ref whose committed tree is the base side (default: `"HEAD"`). The
+    /** Git ref whose committed tree is the base side (default: `"HEAD"`); the
      * candidate is the working tree, uncommitted changes included. */
     base?: string;
     /** Rounds per workload, each one base batch and one candidate batch of
@@ -715,9 +689,8 @@ interface AbOptions {
      * this many percent (default: 1.5): a broad slowdown too small to flag any
      * one workload. */
     geomeanThresholdPct?: number;
-    /** Fresh-process repeats of each flagged workload; it only counts when
-     * every repeat flags it the same way (default: 2; 0 trusts the first
-     * process). */
+    /** Fresh-process repeats of each flagged workload, which only counts when
+     * every repeat flags it the same way (default: 2; 0 trusts the first). */
     confirm?: number;
     filter?: string;
     preload?: string[];
@@ -725,98 +698,112 @@ interface AbOptions {
     outDir?: string;
     cwd?: string;
     noiseCheck?: boolean;
-    /** Kills a runner process (one suite file, or one repeat) after this many
-     * ms. No default. */
+    /** Also compare each side's retained heap per call (see
+     * `bench({ alloc })`) and how far its first call raises RSS (see
+     * `bench({ peakMem })`), each the median of 3 fresh processes per side.
+     * Task/group options override these. */
+    alloc?: boolean;
+    peakMem?: boolean;
+    /** Flag a memory reading that moves past this many percent of the base's
+     * and past its noise floor (default: 10). A memory regression fails the
+     * run. */
+    memThresholdPct?: number;
+    /** Shell commands run once, in order, in a freshly extracted base tree
+     * before it's used: to build what the suites import but git doesn't hold
+     * (generated or gitignored files). Each runs with its cwd at the tree's
+     * counterpart of `cwd`, the project's `node_modules` linked in, and
+     * `OSTIA_AB_SHA` / `OSTIA_AB_CANDIDATE_DIR` (the working tree's `cwd`) in
+     * its environment. The tree is cached per commit and command list. */
+    baseSetup?: string | string[];
+    /** Base trees to keep under `<outDir>/ab`, counting this run's: after a
+     * run, older ones go, least recently used first, unless one was used in
+     * the last hour (another run may still need it). Default: 5. */
+    keepTrees?: number;
+    /** SIGKILLs a runner process (one suite file or repeat), or a `baseSetup`
+     * command, after this many ms. */
     timeoutMs?: number;
     /** Aborting kills the running process and resolves with the suites that
-     * had finished, plus an `aborted` warning; repeats not yet run leave their
+     * had finished, plus an `aborted` warning; unrun repeats leave their
      * workloads unconfirmed. */
     signal?: AbortSignal;
+    /** Called as each setup command, task, confirmation repeat and memory
+     * process starts. */
+    onProgress?: (progress: AbProgress) => void;
+}
+
+export declare class AbBaseError extends OstiaUsageError {
+}
+
+export declare class AbSuiteError extends Error {
+    readonly side: Side;
+    constructor(message: string, side: Side);
+}
+
+export declare class AbSetupError extends Error {
 }
 
 export declare function ab(opts: AbOptions): Promise<ProfileDocument>;
 
-interface BenchOptions {
+declare class OstiaUsageError extends Error {
+}
+
+type Side = "base" | "cand";
+
+export interface BenchOptions {
     suites: string[];
     /** Wall-clock sampling budget per task, ms (default 500). */
     budgetMs?: number;
-    /** Exact trial count per task. When set, the budget is ignored - the
-     * in-process equivalent of `time()`'s `samples`. */
+    /** Exact trial count per task; the budget is ignored when set. */
     samples?: number;
     minSamples?: number;
     gc?: boolean;
     /** Capture one extra `phase: "cpu"` measurement per task (the task looped
-     * under the JSC sampling profiler for long enough to collect ~2,000
-     * samples, JIT tiers included), never mixed into the timing numbers.
-     * `TaskOptions.cpu` / `GroupOptions.cpu` override this per task or group. */
+     * under the JSC sampling profiler for ~2,000 samples, JIT tiers included),
+     * never mixed into the timing numbers. Task/group `cpu` overrides this. */
     cpu?: boolean;
     /** `cpu`'s sampling interval, µs (default: 100). A coarser interval
      * lengthens the capture to keep the sample count, up to 10s per task. */
     cpuIntervalUs?: number;
     /** Capture one extra `phase: "memstats"` measurement per task: retained
      * heap growth per call, from a batch with `Bun.gc(true)` on both sides.
-     * What the calls keep alive, not what they allocate - garbage is collected
-     * before the second reading. `TaskOptions.alloc` / `GroupOptions.alloc`
-     * override this per task or group. */
+     * What the calls keep alive, not what they allocate. Task/group `alloc`
+     * overrides this. */
     alloc?: boolean;
     /** Capture one extra `phase: "memstats"` measurement per task: how far the
-     * task's first call raises RSS, garbage included - the reading
-     * `alloc` can't give. Median of 3 fresh processes, each run with
-     * `OSTIA_PEAK_MEM=1` in its environment (see `measurePeakMem`).
-     * `TaskOptions.peakMem` / `GroupOptions.peakMem` override this per task or
-     * group. */
+     * task's first call raises RSS, garbage included. Median of 3 fresh
+     * processes, each run with `OSTIA_PEAK_MEM=1` in its environment (see
+     * `measurePeakMem`). Task/group `peakMem` overrides this. */
     peakMem?: boolean;
     filter?: string;
-    /** Suite files to run at once, each still in its own child process (default:
-     * 1). Files are independent by design, so this is a wall-clock win for
-     * multi-file suites, but concurrent CPU-bound processes contend for cores,
-     * caches, memory bandwidth and turbo headroom: timings taken under `jobs > 1`
-     * are noisier and not like-for-like with a baseline measured at 1. When
-     * `isolate` puts some tasks in their own subprocess, `jobs` pools across
-     * those per-task processes the same way - so the same noise/wall-clock
-     * tradeoff now scales with task count, not just file count. */
+    /** Suite files (or isolated tasks) to run at once, each in its own child
+     * process (default: 1). Concurrent CPU-bound processes contend for cores,
+     * caches and turbo headroom, so timings under `jobs > 1` are noisier and
+     * not like-for-like with a baseline measured at 1. */
     jobs?: number;
     outDir?: string;
     cwd?: string;
     /** Give every task its own subprocess instead of sharing its suite file's,
-     * isolating each task's JIT tier state, inline caches and heap shape from
-     * every other task the way suite files are already isolated from each
-     * other. `TaskOptions.isolate` / `GroupOptions.isolate` override this per
-     * task or group for mixed suites (e.g. a few outlier-prone tasks isolated,
-     * many cheap ones sharing a process). Multiplies process-spawn overhead by
-     * task count instead of file count. */
+     * isolating JIT tier state, inline caches and heap shape between tasks.
+     * Task/group `isolate` overrides this. Multiplies spawn overhead by task
+     * count instead of file count. */
     isolate?: boolean;
-    /** Scripts run, in order, before each suite file loads - in the same
-     * subprocess, so they can install globals (jsdom's `document`/`window`) or
-     * register a `Bun.plugin()` file-loader (e.g. for `.svelte`/`.vue`) ahead
-     * of the suite's own top-level code. Consumer-authored; ostia ships no
-     * preload scripts itself. */
+    /** Scripts run, in order, before each suite file loads, in the same
+     * subprocess: install globals (jsdom) or a `Bun.plugin()` loader ahead of
+     * the suite's top-level code. */
     preload?: string[];
-    /** Extra flags passed through to the `bun` invocation that runs each suite
-     * file (e.g. `["--conditions", "browser"]`), inserted before the runner
-     * script path so `bun` itself parses them rather than the runner. Useful
-     * for suites that import packages whose `exports` map branches on a
-     * resolution condition Bun doesn't set by default (e.g. Svelte/Vue's
-     * `browser` vs `default` builds). */
+    /** Extra flags for the `bun` invocation that runs each suite file (e.g.
+     * `["--conditions", "browser"]`), placed before the runner script path. */
     bunFlags?: string[];
     /** Measure this machine's noise floor once, before any suite runs
-     * (default: true), and stamp it on the document as
-     * `environment`. Set false to skip the ~200ms reference measurement. */
+     * (default: true), and stamp it on the document as `environment`. */
     noiseCheck?: boolean;
-    /** Kills a suite file's subprocess (or, under `isolate`, one task's
-     * dedicated subprocess) with SIGKILL if it hasn't finished after this many
-     * ms. No default: an unset `timeoutMs` never times out. Applies to the
-     * whole subprocess, not per task - the same granularity `isolate` already
-     * runs at. */
+    /** SIGKILLs a suite file's subprocess (or, under `isolate`, one task's) that
+     * hasn't finished after this many ms. No default. */
     timeoutMs?: number;
-    /** Aborting cancels the run: in-flight suite/isolated-task subprocesses
-     * are killed with SIGKILL, no new ones are started, and `bench()` resolves
-     * (never rejects) with whatever suites/tasks had already finished when the
-     * signal fired, plus an `aborted` warning on the document's last
-     * measurement. A suite subprocess killed mid-run contributes nothing (it
-     * only writes its result once, at the end), so a suite that was in flight
-     * when the signal fired is dropped entirely rather than partially
-     * represented. */
+    /** Aborting kills in-flight subprocesses, starts no new ones, and resolves
+     * (never rejects) with whatever suites/tasks had finished, plus an
+     * `aborted` warning on the last measurement. A suite killed mid-run is
+     * dropped entirely: it only writes its result once, at the end. */
     signal?: AbortSignal;
 }
 
@@ -838,6 +825,10 @@ export interface TaskOptions {
     /** Per-task hard floor on trials; overrides the suite-wide `--min-samples` /
      * `minSamples`. */
     minSamples?: number;
+    /** Former names of this task in the same group, so `compare` and `ab`
+     * match a base measured before a rename instead of reporting the old name
+     * as removed and the new one as new. */
+    aliases?: string[];
     /** What this task measures and why. Flows into `Workload.description` so the
      * intent travels with the numbers instead of living only in a source comment. */
     description?: string;
@@ -907,38 +898,39 @@ export interface GroupOptions {
     after?: Hook;
 }
 
-interface GroupFn {
-    (name: string, fn: () => void, opts?: GroupOptions): void;
+type GroupRegistrar = (name: string, fn: () => void, opts?: GroupOptions) => void;
+
+interface GroupFn extends GroupRegistrar {
     /** Registers every task inside as skipped: the runner never measures
      * them, but the document still carries their workloads (marked
      * `Workload.skipped`). */
-    skip: (name: string, fn: () => void, opts?: GroupOptions) => void;
+    skip: GroupRegistrar;
     /** When any task or group in the suite uses `.only`, the runner restricts
      * the whole suite file to only those tasks (before `--filter` narrows
      * further) and prints a one-line notice to stderr. */
-    only: (name: string, fn: () => void, opts?: GroupOptions) => void;
+    only: GroupRegistrar;
 }
 
 export declare const group: GroupFn;
 
-interface TaskFn {
-    (name: string, fn: () => unknown | Promise<unknown>, opts?: TaskOptions): void;
+type TaskRegistrar = (name: string, fn: () => unknown | Promise<unknown>, opts?: TaskOptions) => void;
+
+interface TaskFn extends TaskRegistrar {
     /** Registers the task as skipped: the runner never measures it, but the
      * document still carries its workload (marked `Workload.skipped`) so a
      * renderer or `compare` can say so explicitly instead of the task simply
      * being absent. */
-    skip: (name: string, fn: () => unknown | Promise<unknown>, opts?: TaskOptions) => void;
+    skip: TaskRegistrar;
     /** When any task or group in the suite uses `.only`, the runner restricts
      * the whole suite file to only those tasks (before `--filter` narrows
      * further) and prints a one-line notice to stderr. */
-    only: (name: string, fn: () => unknown | Promise<unknown>, opts?: TaskOptions) => void;
+    only: TaskRegistrar;
 }
 
 export declare const task: TaskFn;
 
 export interface RunOptions extends MeasureTasksOpts {
-    /** Regex, matched against "group/name" task ids - same semantics as
-     * `ostia bench --filter` / `bench({ filter })`. */
+    /** Regex matched against "group/name" task ids, as in `bench({ filter })`. */
     filter?: string;
     /** Skip printing the report to stdout; still returns the document. */
     quiet?: boolean;
@@ -950,6 +942,11 @@ export declare function run(opts?: RunOptions): Promise<ProfileDocument>;
 
 type FormatName = "table" | "json" | "markdown" | "jsonl" | "minimal" | "collapsed" | "mermaid" | "speedscope" | "cpuprofile";
 
+export interface VizOptions {
+    /** Render this measurement only, instead of every CPU measurement. */
+    measurementId?: string;
+}
+
 interface RenderResult {
     text?: string;
     files?: {
@@ -964,32 +961,44 @@ interface Renderer<O = unknown> {
 }
 
 interface MeasureTasksOpts extends InprocessTimingOptions {
-    /** Suite-wide default for capturing an extra `phase: "cpu"` measurement
-     * per task (task/group `TaskOptions.cpu`/`GroupOptions.cpu` still win). */
+    /** Suite-wide default for capturing an extra `phase: "cpu"` measurement per
+     * task (task/group `cpu` still wins). */
     cpu?: boolean;
     /** `cpu`'s sampling interval, µs (default: 100). */
     cpuIntervalUs?: number;
     /** Suite-wide default for capturing an extra `phase: "memstats"`
-     * measurement per task (task/group `TaskOptions.alloc`/`GroupOptions.alloc`
-     * still win). */
+     * measurement per task (task/group `alloc` still wins). */
     alloc?: boolean;
-    /** Stamped onto every workload this call produces, recording whether it
-     * ran in a subprocess dedicated to it alone. */
+    /** Stamped onto every workload: it ran in a subprocess dedicated to it. */
     markIsolated?: boolean;
     /** Measure this machine's noise floor before the first task (default:
-     * true) and stamp it on the document as `environment`. Set false to skip
-     * the ~200ms reference measurement. */
+     * true) and stamp it on the document as `environment`. */
     noiseCheck?: boolean;
 }
 
+interface InprocessTimingOptions {
+    /** Wall-clock budget for the sampling loop, per task (default: 500). */
+    budgetMs?: number;
+    /** Exact trial count; the budget is ignored. */
+    samples?: number;
+    /** Keep sampling past the budget until this many trials exist. When unset
+     * the floor is cost-aware (see `defaultSampleFloor`). */
+    minSamples?: number;
+    /** Warmup budget as a fraction of `budgetMs` (default: 0.1); unlike
+     * `time()`'s `warmup`, which is a trial count. Always runs at least one call. */
+    warmup?: number;
+    gc?: boolean;
+}
+
+export declare function keep(value: unknown): void;
+
 type SweepPoint<T extends Record<string, readonly unknown[]>> = {
     [K in keyof T]: T[K][number];
 };
 
 export declare function sweep<T extends Record<string, readonly unknown[]>>(dims: T, fn: (point: SweepPoint<T>) => void): void;
 
-export declare function newDocument(workloads: Workload[], measurements: Measurement[], environment?: Environment): ProfileDocument;
-export { newDocument as createDocument };
+export declare function createDocument(workloads: Workload[], measurements: Measurement[], environment?: Environment): ProfileDocument;
 
 export declare function saveDocument(doc: ProfileDocument, path: string): Promise<void>;
 
@@ -1005,9 +1014,45 @@ export declare class OstiaDocumentError extends Error {
 
 export declare function loadDocument(path: string): Promise<ProfileDocument>;
 
-export declare const renderers: Record<FormatName, Renderer<any>>;
+export interface ProfileOptions {
+    /** Sampling interval in µs; default 1000. Named like `time()`'s and
+     * `bench()`'s option, the config key and `--cpu-interval`. */
+    cpuIntervalUs?: number;
+    /** Names the workload: it becomes the label and, instead of the function's
+     * name and source, what the id hashes, so closures that differ only in
+     * captured values get distinct ids and the id survives editing the function. */
+    name?: string;
+    /** `"inspector"` (default) captures through CDP and writes a portable
+     * .cpuprofile; `"jsc"` uses `bun:jsc.profile` and adds LLInt/Baseline/DFG/FTL
+     * tier data. */
+    origin?: "inspector" | "jsc";
+    /** There's no child to kill, so an already-aborted signal skips the profiler,
+     * calls `fn` plain (still returning its `result`) and records an `aborted`
+     * warning instead of CPU evidence. It can't interrupt a running `fn`. */
+    signal?: AbortSignal;
+}
+
+export interface ProfileResult<T> {
+    result: T;
+    measurement: Measurement;
+    document: ProfileDocument;
+}
+
+export declare function profile<T>(fn: () => T | Promise<T>, opts?: ProfileOptions): Promise<ProfileResult<T>>;
+
+export declare const renderers: {
+    table: Renderer<unknown>;
+    json: Renderer<unknown>;
+    markdown: Renderer<unknown>;
+    jsonl: Renderer<unknown>;
+    minimal: Renderer<MinimalRenderOptions>;
+    collapsed: Renderer<VizOptions>;
+    mermaid: Renderer<MermaidOptions>;
+    speedscope: Renderer<VizOptions>;
+    cpuprofile: Renderer<VizOptions>;
+};
 
-export declare const MINIMAL_PROTOCOL_VERSION: 1;
+export declare const MINIMAL_PROTOCOL_VERSION: 2;
 
 interface MinimalWarning {
     code: string;
@@ -1015,64 +1060,72 @@ interface MinimalWarning {
 }
 
 interface MinimalDelta {
+    /** The base's median, ns: the row's own `median` is the candidate's. */
+    baseMedian?: number;
     medianPct: number;
     meanPct: number;
     verdict: "improved" | "regressed" | "unchanged";
     pass: boolean;
-    /** 95% bootstrap CI on the difference of medians and the Mann-Whitney
-     * p-value behind the verdict. Absent on a thin (<5 samples/side)
-     * comparison, which falls back to a point-estimate threshold. */
+    /** 95% bootstrap CI on the difference of medians; absent (with `pValue`)
+     * on a thin (<5 samples/side) comparison. */
     ci95?: [number, number];
     pValue?: number;
-    /** The threshold this delta was actually tested against, once machine
-     * noise widened it past `thresholds.timingPct` - see
-     * `Comparison.thresholds.effectiveTimingPct`. */
+    /** The threshold actually tested against, after machine noise widened it. */
     effectiveTimingPct: number;
     matched: true;
+    /** The base task's name, when it was matched through an alias. */
+    renamedFrom?: string;
 }
 
 interface MinimalPaired {
     /** Base side's median per-call time, ns. */
     baseMedian: number;
     medianRatio: number;
-    p25: number;
-    p75: number;
+    ratioP25: number;
+    ratioP75: number;
     rounds: number;
-    /** Final: `flagged` when fresh processes confirmed it, else
-     * `"unchanged"`. */
+    /** `flagged` when fresh processes confirmed it, else `"unchanged"`. */
     verdict: "regressed" | "improved" | "unchanged";
-    /** What this workload's first process saw, before confirmation. */
+    /** What the first process saw, before confirmation. */
     flagged?: "regressed" | "improved";
     confirmed?: boolean;
     /** Median ratio of each fresh-process repeat. */
     repeats?: number[];
     sameOutput: boolean;
+    /** The suite file differs from the base's copy. */
+    suiteChanged?: true;
+    /** `--alloc`: retained heap per call on each side. */
+    retained?: MinimalMemoryChange;
+    /** `--peak-mem`: first-call RSS rise on each side. */
+    peak?: MinimalMemoryChange;
+}
+
+interface MinimalMemoryChange {
+    base: number;
+    cand: number;
+    verdict: "regressed" | "improved" | "unchanged";
+    floor: number;
 }
 
 interface MinimalRunLine {
     event: "run";
     protocolVersion: typeof MINIMAL_PROTOCOL_VERSION;
     schemaVersion: ProfileDocument["schemaVersion"];
-    /** Join key back to `Workload.id` / `Comparison.candidateMeasurementId` -
-     * stable across a `time`/`compare`/`ci` invocation of the same command,
-     * unlike `task` (a label, not an identity). */
+    /** Join key to `Workload.id` / `Comparison.candidateMeasurementId`; unlike
+     * `task`, stable across invocations. */
     workloadId: string;
     task: string;
     group?: string;
     description?: string;
     groupDescription?: string;
-    /** From `task(name, fn, { params })` or a `sweep()` point. */
     params?: Record<string, string | number | boolean>;
-    /** From `task.skip()` / `group.skip()`: no measurement was taken, so every
-     * stats field below is absent on this line. */
+    /** `task.skip()` / `group.skip()`: no measurement, so every stats field is absent. */
     skipped?: true;
     unit?: "ns";
+    /** 0, with every stats field absent, when no trial produced a sample (all
+     * timed out or missed the `timeSource` pattern); see `warnings`. */
     samples?: number;
-    /** In-process trials batched into one timed block (see
-     * `measure/inprocess.ts`'s `sizeBatch`) so the timer's own resolution
-     * doesn't dominate a sub-microsecond task's reading. 1 when the timing
-     * engine never batched (every subprocess run, and any in-process run
-     * whose single call already clears the batching threshold). */
+    /** In-process trials batched into one timed block; 1 when never batched. */
     batch: number;
     mean?: number;
     median?: number;
@@ -1087,24 +1140,30 @@ interface MinimalRunLine {
     /** Median user / system CPU time per trial, ns: subprocess commands only. */
     userNs?: number;
     systemNs?: number;
-    /** `--alloc`: heap each call keeps alive after a full GC, whole bytes. */
+    /** `--alloc`: heap each call keeps alive after a full GC, bytes. */
     retainedBytesPerOp?: number;
     /** `--peak-mem`: how far the task's first call raised RSS, bytes. */
     peakBytes?: number;
     /** Median over the group's reference median (its baseline task, else its
-     * fastest). Only present when the document has more than one timing run. */
+     * fastest); only when the document has more than one timing run. */
     relative?: number;
     baseline?: true;
-    /** `mad / median` of the machine's ~200ms reference measurement - how
-     * noisy this machine is right now, independent of what's being measured.
-     * From `document.environment`; absent when `noiseCheck: false` skipped it. */
+    /** The machine's noise floor from `document.environment`; absent when the
+     * noise check was skipped. */
     noiseFloorPct?: number;
     warnings: MinimalWarning[];
-    /** From `comparisons` when present (ostia compare / ci): the change against
-     * the baseline document for this task. */
+    /** The change against the baseline document (`compare` / `ci`). */
     delta?: MinimalDelta;
-    /** `ab` only; see `MinimalPaired`. */
     paired?: MinimalPaired;
+    /** `ab` only, instead of stats and `paired`: the task threw on one side
+     * (`"base"`/`"cand"`) or both, so it isn't judged on time. `message` is
+     * the error's first lines; `repeat` (from 1) is set when it threw in a
+     * confirmation repeat. */
+    threw?: {
+        side: "base" | "cand" | "both";
+        message: string;
+        repeat?: number;
+    };
 }
 
 interface MinimalUnmatchedLine {
@@ -1131,6 +1190,8 @@ interface MinimalSummaryLine {
     missingBaseline?: number;
     geomeanPct: number | null;
     effectiveTimingPct: number;
+    /** `compare`/`ci`: the machine's drift, added to the timing threshold. */
+    driftPct?: number;
     noiseFloorPct?: number;
     /** `ci` only. */
     baseline?: {
@@ -1144,19 +1205,112 @@ interface MinimalSummaryLine {
     };
     /** `ab` only: the gate on `geomeanPct`. */
     geomeanThresholdPct?: number;
-    /** `ab` only: flagged in the first process but not reproduced by the
-     * fresh-process repeats; counted in `unchanged`. */
+    /** `ab` only: flagged in the first process but not reproduced; counted in `unchanged`. */
     unconfirmed?: number;
-    /** `ab` only: workloads whose first call returned different values on the
-     * two sides. Informational. */
+    /** `ab` only: workloads whose first call returned different values on the two sides. */
     outputDiffers?: number;
+    notComparable?: number;
+    threw?: number;
+    newSuites?: string[];
+    /** `ab` only, with `--alloc` or `--peak-mem`: tasks whose memory
+     * regressed or improved, and the threshold, percent. */
+    memory?: {
+        thresholdPct: number;
+        regressed: number;
+        improved: number;
+    };
     git?: {
         base?: GitMetadata;
         cand?: GitMetadata;
     };
     exportedTo?: string;
-    verdict: "pass" | "fail";
+    /** `pass` (exit 0), `fail` (exit 1: a regression), else `error` (exit 2, or
+     * 130 when cancelled): no verdict was reached. */
+    verdict: "pass" | "fail" | "error";
     exitCode: number;
 }
 
 export type MinimalEvent = MinimalRunLine | MinimalUnmatchedLine | MinimalSummaryLine;
+
+export interface MinimalProtocolContext {
+    command: "compare" | "ci" | "ab";
+    exitCode: number;
+    unmatched?: {
+        baseOnly: Workload[];
+        candOnly: Workload[];
+    };
+    baseGit?: GitMetadata;
+    candGit?: GitMetadata;
+    baseline?: {
+        name: string;
+        path: string;
+    };
+    cached?: number;
+    executed?: number;
+    failed?: number;
+    missingBaseline?: number;
+    exportedTo?: string;
+}
+
+export interface MinimalRenderOptions {
+    protocol?: MinimalProtocolContext;
+}
+
+export interface MermaidOptions extends VizOptions {
+    topN?: number;
+}
+
+export interface CommandSpec {
+    command: string | string[];
+    label?: string;
+    /** Overrides `TimeOptions.prepare` for this command. */
+    prepare?: PrepareHook;
+    /** Overrides `TimeOptions.timeSource` for this command. */
+    timeSource?: TimeSource;
+    /** Overrides `TimeOptions.timeoutMs` for this command. */
+    timeoutMs?: number;
+    /** Overrides `TimeOptions.ignoreExitCodes` for this command. */
+    ignoreExitCodes?: number[];
+}
+
+export interface TimeOptions {
+    commands: (string | string[] | CommandSpec)[];
+    /** Runs unmeasured before every trial (warmup and instrumented included), in
+     * `cwd`/`env`: a command spawned and awaited, or a function. */
+    prepare?: PrepareHook;
+    /** Take timing from a number in each command's own output (e.g. a build
+     * tool's `built in 342ms`) instead of its wall clock. */
+    timeSource?: TimeSource;
+    /** Exact trial count; when set, `budgetMs` is ignored. */
+    samples?: number;
+    /** Wall-clock budget for the sampling loop, ms. Default: ~3s when neither
+     * `samples` nor `budgetMs` is given. */
+    budgetMs?: number;
+    /** Floor on trials when no exact `samples` is given. */
+    minSamples?: number;
+    warmup?: number;
+    /** Round-robin trials across commands instead of finishing each command
+     * first, so drift hits every command equally. Default: true with 2+ commands. */
+    interleave?: boolean;
+    cwd?: string;
+    env?: Record<string, string>;
+    cpu?: boolean;
+    heap?: boolean;
+    cpuIntervalUs?: number;
+    outDir?: string;
+    /** Measure the machine's noise floor first (default true, ~200ms) and stamp
+     * it on the document as `environment`. */
+    noiseCheck?: boolean;
+    /** SIGKILLs a trial (or prepare hook) still running after this many ms. No
+     * default. A timed-out trial contributes no sample. */
+    timeoutMs?: number;
+    /** Abort kills in-flight trials, schedules no more, and resolves (never
+     * rejects) with the completed measurements plus an `aborted` warning on the
+     * last one. */
+    signal?: AbortSignal;
+    /** Exit codes to treat as success (hyperfine's `--ignore-failure`): the
+     * trial still contributes its sample and gets no `nonzero-exit` warning. */
+    ignoreExitCodes?: number[];
+}
+
+export declare function time(opts: TimeOptions): Promise<ProfileDocument>;