@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/charts/chart-plan.d.ts

@@ -0,0 +1,674 @@
+/**
+ * Which chart a table becomes and the data it plots. {@link planChart} is the
+ * local best guess over a {@link TableAnalysis}: the chart kind, the label
+ * column and the measure columns to draw. A host may substitute its own
+ * {@link ChartPlan} (a model's pick for a multi-series table); either way
+ * {@link buildChart} turns it into the {@link ChartSpec} that
+ * {@link renderChartSvg} draws, and {@link worthCharting} decides whether
+ * the picture says more than the table already does.
+ *
+ * The heuristics were fitted on ~7k tables from real assistant answers: the
+ * label is the first text column (index columns like `#`/`Rank` never are),
+ * table order is kept (most tables are deliberately unsorted), total rows stay
+ * out of the scale, and units never share an axis. Rows whose labels repeat
+ * (`Model | Harness | …`) are named by the text columns that tell them apart
+ * ({@link ChartPlan.qualifiers}), nested under one of them
+ * ({@link ChartPlan.group}) when it already runs in blocks; otherwise names
+ * sharing a leading part nest under it (`glm new`, `glm prior`), and names are
+ * shortened for display wherever they stay distinct. A row named as the
+ * baseline becomes the {@link ChartPlan.reference} the others read against;
+ * before/after values spanning decades, or rows of very different sizes
+ * beside a baseline column, draw as factors of change.
+ *
+ * A plan also carries what the table means ({@link guessMeaning} locally, a
+ * judge's answers in `smart` mode): which way each measure improves, what
+ * competes, the rows it is about, a status column, and the one
+ * {@link tableTakeaways | takeaway} stated as its title.
+ */
+import { type Dimension, type Status, type TableAnalysis, type TableColumn } from "./table-data";
+/**
+ * Which way a measure improves: `higher` (pass rate, throughput, speedup) or
+ * `lower` (cost, latency, errors). Measures that improve neither way (counts,
+ * sizes, shares, ids) have none.
+ */
+export type Polarity = "higher" | "lower";
+/** Which way a table's alternatives run: down its rows or across its plotted columns. */
+export type Rivals = "rows" | "columns";
+/**
+ * Chart kinds, by the table shapes they fit:
+ * - `bar`: one measure across categories.
+ * - `paired`: one quantity under two conditions per category (before/after, old vs new), or `a → b` cells.
+ * - `grouped`: two to four same-unit measures per category that are not one before/after pair.
+ * - `stacked`: same-unit parts of one whole per category (`Cached + Uncached input + Output = Total`), one segmented bar each;
+ *   outcome counts (`ok | fail`) as each category's mix ({@link ChartPlan.normalize}).
+ * - `line`: measures over an ordered axis (dates, runs, sizes).
+ * - `heatmap`: a matrix of same-unit values.
+ * - `multiples`: measures in different units, each scaled on its own; transposed when each row is its own metric.
+ * - `share`: parts of a whole in one bar: percentages summing to 100, or counts splitting one total (items by status).
+ * - `diverging`: signed changes around zero.
+ * - `scatter`: two continuous measures per item.
+ * - `change`: metrics in different units against a baseline column (before/after), as factors.
+ * - `progress`: scores out of a total (`12/12`), as filled tracks.
+ * - `timeline`: one measure's rows laid end to end on one axis, in table order or at an offset column
+ *   (pipeline steps to time scale, parts of a buffer at their offsets).
+ * - `waterfall`: one measure's rows building up, step by step in table order, to their total (a total row
+ *   or their sum), with any cap row as a rule.
+ * - `dots`: two to six same-unit series per category as dots on one shared axis (a Cleveland dot plot),
+ *   logarithmic when the values span decades; generalizes the dumbbell beyond two series.
+ * - `range`: values written as `a–b` intervals, as floating bars from low to high, with an optional
+ *   central estimate and a stated reference (a budget, a price, 1×); series in other units get their own band.
+ * - `slope`: each category's value at two to four ordered stages (`Baseline | Best (Iter 3) | Iter 4`),
+ *   a line per category from stage to stage, labelled at both ends; moves toned by polarity.
+ * - `butterfly`: two opposing amounts per category (`Added | Removed`, `Wins | Losses`) as back-to-back
+ *   bars from a shared spine, each row's net beside it.
+ * - `bullet`: one measured value per row against that row's own target, budget or limit (a `Target ≤ 200 µs`
+ *   column), each as a share of its target on one axis: a bar (a `p50 / p99` span) to a target mark, toned by
+ *   whether it stays on the target's side ({@link ChartPlan.target}).
+ * - `ladder`: quantiles of one measurement per category (`p50 | p90 | p99 | max` columns, `p50 / p99`
+ *   cells), each row a line from its lowest quantile to its highest with a mark at each, on one shared
+ *   axis (logarithmic when the tails span decades); one ladder per condition measured (`Startup`, `Wall`).
+ * - `histogram`: counts or shares over rows that are ordered bins (`1`, `2–5`, `6–20`, `100+`), as
+ *   columns in bin order; two to four distributions side by side, as shares of each one's total when
+ *   their totals differ ({@link ChartPlan.normalize}).
+ * - `stat`: a small table comparing two conditions (old vs new, on vs off) on one to four metrics, as a tile
+ *   per metric: the factor between them in big figures over a short bar per condition ({@link statShape}).
+ */
+export type ChartKind = "bar" | "paired" | "grouped" | "line" | "heatmap" | "multiples" | "share" | "diverging" | "scatter" | "change" | "progress" | "stacked" | "timeline" | "waterfall" | "dots" | "range" | "slope" | "butterfly" | "bullet" | "ladder" | "histogram" | "stat";
+/** What to draw from a table: the kind, the columns naming each category, and the columns plotted. */
+export interface ChartPlan {
+    readonly kind: ChartKind;
+    /** Column naming each category (or holding the x values of a line); rows are numbered without one. */
+    readonly label: number | undefined;
+    /** Columns joined to the label to tell rows apart (`Sonnet 5.5 · bash`); none by default. */
+    readonly qualifiers?: readonly number[];
+    /**
+     * Naming column whose values nest the rows: rows regroup by its values in
+     * order of first appearance (table order within each), and a label column
+     * writes each value once beside its block. Lines keep their x order and ignore it.
+     */
+    readonly group?: number;
+    /**
+     * Plotted columns, in order; a `change` measures the rest against the first (or its `a → b` cells),
+     * a `slope` runs through them as stages, and a `butterfly` draws the first leftward (the losing side).
+     */
+    readonly series: readonly number[];
+    /**
+     * `change` over metric pairs (`Baseline Turns | Iter1 Turns | Baseline Tokens
+     * In | Iter1 Tokens In`): the baseline column of each series, in order, so
+     * each series is measured against its own before column instead of the first.
+     */
+    readonly baselines?: readonly number[];
+    /** Each data row is its own series (a metric with its own unit) and the plotted columns are the categories. */
+    readonly transpose: boolean;
+    /**
+     * Heatmap cells shaded on one scale across every cell (default), each
+     * series on its own, or each row on its own. A `series`-shaded heatmap of
+     * at most {@link MAX_PANELS} series draws as a grid of bars instead, each
+     * column on its own axis: its columns are different quantities.
+     */
+    readonly shading?: Shading;
+    /**
+     * Rows whose `column` cell reads `value` are the reference the others are
+     * read against (`Harness` = `baseline`), one per group; none by default.
+     */
+    readonly reference?: RowReference;
+    /**
+     * Rows ranked by a plotted column instead of table order (rankings,
+     * leaderboards); within each group when grouped. Lines and scatters keep
+     * their x order, `change` charts table order. Table order by default: most
+     * tables are deliberately ordered.
+     */
+    readonly order?: RowOrder;
+    /**
+     * `stacked`: the column the plotted parts make up (`Total`), labelling each
+     * bar with its written figure and drawing any rest it holds beyond the parts
+     * as an unlabelled track. Without it a bar ends at the parts' sum.
+     */
+    readonly whole?: number;
+    /**
+     * `stacked`: each bar spans 100% of its category's total (its whole, else
+     * its parts' sum), so rows of very different sizes compare by their mix.
+     * Absent: normalized when the parts are outcomes ({@link outcomeTones}:
+     * `ok | fail`, `Pass | Fail | Skip`), whose rates are the point, over
+     * totals {@link MIX_SPREAD}× apart or more.
+     * `histogram`: each distribution as shares of its own total, so populations
+     * of different sizes compare by shape. Absent: normalized when two or more
+     * count columns' totals lie {@link MIX_SPREAD}× apart or more.
+     */
+    readonly normalize?: boolean;
+    /**
+     * `timeline`: the column holding each segment's start (`Offset`, `Start`),
+     * in the plotted column's dimension; without it segments follow one another
+     * in table order from zero.
+     */
+    readonly offsets?: number;
+    /**
+     * `waterfall`: the row (by index) of a cap the steps build toward (`Hard
+     * cap`, `Budget`), drawn as a rule across the steps instead of a step.
+     */
+    readonly limit?: number;
+    /**
+     * `bullet`: the column holding each row's target (`Target` `≤ 200 µs`, `§6
+     * budget`, `Limit`), which the one plotted series is measured against
+     * ({@link findTarget}).
+     */
+    readonly target?: number;
+    /** Which way each column improves, by column index; neutral columns absent. */
+    readonly polarity?: Readonly<Record<number, Polarity>>;
+    /** Which way each row's metric improves, by row index, where rows are metrics ({@link rowsAreMetrics}). */
+    readonly rowPolarity?: Readonly<Record<number, Polarity>>;
+    /**
+     * What competes, so each contest's best value (by {@link polarity}) is
+     * marked: `rows` are alternatives scored by every measure (models,
+     * configs, arms: the best per column); `columns` are alternatives measured
+     * on every row (`Record | Map | string[]` per scenario: the best per row).
+     * Absent for parts of a whole, steps, or items described side by side.
+     */
+    readonly rivals?: Rivals;
+    /** Rows the table is about (the recommended option, `current`, `ours`, the bolded row), by row index. */
+    readonly focus?: readonly number[];
+    /** Column whose status cells (`ok`, `FAIL`, `pending`, ✅) badge each row's name. */
+    readonly status?: number;
+    /** The chart's title: one fact stated over it, the text of one of {@link tableTakeaways}; none by default. */
+    readonly title?: string;
+}
+/** A naming cell marking reference rows: column index and cell text. */
+export interface RowReference {
+    readonly column: number;
+    readonly value: string;
+}
+/** Rows sorted by `column`'s values, largest first (`descending`) or smallest first. */
+export interface RowOrder {
+    readonly column: number;
+    readonly direction: "descending" | "ascending";
+}
+/**
+ * How a heatmap shades its cells: `shared` compares every cell with every
+ * other; `series` compares within each column (different quantities, like
+ * input vs. reasoning tokens), so one large column does not wash out the
+ * rest; `row` compares within each row (one measure across conditions, rows
+ * of very different sizes), so one large row does not wash out the rest.
+ */
+export type Shading = "shared" | "series" | "row";
+/** One plotted value. */
+export interface ChartPoint {
+    /** Value in base units (seconds, bytes, …). */
+    readonly value: number;
+    /** The number as the table wrote it (`~$250`, `12.5 ms`), shown as the value label. */
+    readonly text: string;
+    /** The table bolded the cell. */
+    readonly emphasis: boolean;
+    /** Upper end of a range cell (`24–72 h`). */
+    readonly upper?: number;
+    /** The spread a `± e` cell states around the value (`3.67s ± 0.69`), drawn as a whisker either side of it. */
+    readonly error?: number;
+}
+/**
+ * Which side of its target a value must stay: at or under it (`max`: `≤ 200
+ * µs`, a budget, a limit) or at or over it (`min`: `≥ 0.85`, `≥ 700 MB/s`).
+ */
+export type Bound = "max" | "min";
+/**
+ * A row's target in a `bullet` chart, as the table wrote it: a value, or a
+ * window it must fall in (`60–100 ms`, its {@link ChartPoint.upper}), and the
+ * {@link Bound} the measure must keep; absent when neither the cell, the
+ * header nor the measure's polarity says which side.
+ */
+export interface ChartTarget extends ChartPoint {
+    readonly bound?: Bound;
+}
+export interface ChartSeries {
+    readonly name: string;
+    readonly dim: Dimension;
+    /** Currency symbol or rate unit the axis prints; empty for other dimensions. */
+    readonly unit: string;
+    /** One per category; `null` where the cell holds no number of this series' dimension. */
+    readonly points: readonly (ChartPoint | null)[];
+    /** Status words standing in for a value (`TIMEOUT`, `OOM`), one per category. */
+    readonly notes: readonly (string | undefined)[];
+    /** Which way the series improves; absent when neutral. */
+    readonly polarity?: Polarity;
+    /** Category of the series' best value, marked when its rows are rivals; absent when tied or neutral. */
+    readonly best?: number;
+}
+/** Consecutive categories sharing a leading name, which a label column writes once beside its members. */
+export interface ChartGroup {
+    /** The shared name; empty for a run of rows outside every group, written as members only. */
+    readonly name: string;
+    /** The rest of each member category's name, in order; empty where the group's name alone names the row. */
+    readonly members: readonly string[];
+}
+/** The data a chart draws, independent of how it is drawn. */
+export interface ChartSpec {
+    readonly kind: ChartKind;
+    /**
+     * One name per category: the label cell, joined with the cells that tell
+     * repeated labels apart (`Sonnet 5.5 · bash`); without groups, shortened
+     * for display where names stay distinct (`openai/gpt-5.5:xhi` → `gpt-5.5`).
+     */
+    readonly categories: readonly string[];
+    /**
+     * `categories` nested under their {@link ChartPlan.group} values
+     * (`Sonnet 5.5` → `baseline`, `bash`, `http`), covering them in order; without
+     * a group, under a leading part their names share (`glm new`, `glm prior` →
+     * `glm` → `new`, `prior`). Absent when neither applies, or when each series is a row.
+     */
+    readonly groups?: readonly ChartGroup[];
+    readonly series: readonly ChartSeries[];
+    /**
+     * Numeric x positions of a line, the x measure of a scatter, or each
+     * `timeline` segment's start ({@link ChartPlan.offsets}), one per category.
+     */
+    readonly x?: {
+        readonly name: string;
+        readonly dim: Dimension;
+        readonly unit: string;
+        readonly values: readonly number[];
+    };
+    /** Total/summary rows, printed under the chart instead of skewing its scale. */
+    readonly caption?: string;
+    /** Name of the category axis: the headers of the columns naming the rows. */
+    readonly axis: string;
+    /** What a `change` measures against (its baseline column); its points are factors of it. */
+    readonly baseline?: string;
+    /**
+     * The `change` is measured against a rival column — the one leading most rows — rather than a before
+     * state: its bars are gaps to that rival (`+22%` slower than `tsc-rs, 8`), never improvements or regressions.
+     */
+    readonly rival?: boolean;
+    /** How a heatmap shades its cells; `shared` when absent. */
+    readonly shading?: Shading;
+    /**
+     * Indices of the categories the others read against ({@link ChartPlan.reference}),
+     * at most one per group: bars and bar grids mark each with a dashed rule at
+     * its value through its group, and single bars print the others' change from it.
+     */
+    readonly reference?: readonly number[];
+    /** `stacked`: the whole each category's parts make up ({@link ChartPlan.whole}), one point per category. */
+    readonly whole?: ChartSeries;
+    /**
+     * `stacked`: each bar is its category's mix, parts as percentages of its total; `histogram`: each
+     * distribution as shares of its own total ({@link ChartPlan.normalize}).
+     */
+    readonly normalized?: boolean;
+    /**
+     * Outcome of each part of a whole, coloring it `success`/`warning`/`error`/
+     * `muted` instead of a series color: per series of a `stacked` chart
+     * (`ok | fail` headers), per category of a `share` (`✅ Resolved`, `❌ Remaining`);
+     * `undefined` for a part naming none. Absent unless most parts read as
+     * statuses ({@link outcomeTones}) and they are not all alike.
+     */
+    readonly tones?: readonly (Status | undefined)[];
+    /**
+     * `waterfall`: the bar the steps build to — the table's total row as
+     * written, else the steps' sum written like their figures (`~$8.0M`).
+     */
+    readonly total?: {
+        readonly name: string;
+        readonly point: ChartPoint;
+    };
+    /**
+     * `range`: the central estimate of the first series' intervals, one point per category, from a
+     * plotted column whose values all fall inside them (`≈ $6,700` beside `$6.0k–7.3k`); drawn as a tick.
+     */
+    readonly estimate?: ChartSeries;
+    /**
+     * `bullet`: each category's target ({@link ChartPlan.target}), against the
+     * first series' point; `null` where the row states none in its unit.
+     */
+    readonly targets?: readonly (ChartTarget | null)[];
+    /** `bullet`: what the targets are called, lowercased from their header (`target`, `budget`, `limit`). */
+    readonly targetName?: string;
+    /**
+     * The one fact the chart states over it ({@link ChartPlan.title}: `Every
+     * scenario improved (median 14× less)`); no title line without one.
+     */
+    readonly title?: string;
+    /**
+     * Muted note beside the title. Absent: the renderer writes how the chart
+     * encodes the data where that is not obvious (`log scale`, `scaled per column`).
+     */
+    readonly subtitle?: string;
+    /**
+     * The two series of a `paired` chart are one quantity before and after
+     * (`a → b` cells, before/after headers per {@link isTransition}): drawn as a
+     * transition — a hollow muted start, a connector fading into the lead color,
+     * a solid end, and the figures as `a → b`. Otherwise the pair are peers
+     * (`xutf` vs `std`, two conditions without an order) drawn in two series
+     * colors without direction. Only condition pairs ({@link isConditionPair} or
+     * the judge's `pair`) draw as `paired` at all. A `ladder`'s two ladders
+     * (`before fix` | `after fix`) by the same reading: the first muted.
+     */
+    readonly transition?: boolean;
+    /** Marks laid over the chart by a planner: reference lines, highlighted categories, callouts. */
+    readonly annotations?: readonly ChartAnnotation[];
+    /**
+     * Each series is a table row (a metric in its own unit) and the categories
+     * are the plotted columns ({@link ChartPlan.transpose}); {@link axis} then
+     * names the series rather than the categories.
+     */
+    readonly transposed?: boolean;
+    /** Which way each category's metric improves where categories are metrics or items moving by a factor (`change`); neutral absent. */
+    readonly categoryPolarity?: readonly (Polarity | undefined)[];
+    /**
+     * Per category, the series holding its best value where the plotted
+     * columns are rivals sharing a unit and a polarity; absent where tied.
+     */
+    readonly leaders?: readonly (number | undefined)[];
+    /** Status of each category (`ok`, `FAIL`, `pending`), badged beside its name. */
+    readonly status?: readonly (Status | undefined)[];
+    /** Header of the column the {@link status} badges come from, named in their key. */
+    readonly statusName?: string;
+    /**
+     * Status columns the chart does not plot (`Preserves layout? | Machine-parseable? | Renderable?`),
+     * drawn as a matrix of status dots between the row names and the marks, each column headed by its
+     * name; two to {@link MAX_MATRIX}, in place of the single {@link status} badge.
+     */
+    readonly matrix?: readonly StatusColumn[];
+    /**
+     * `ladder`: the series of each ladder drawn on every category, lowest quantile first; one ladder per
+     * condition measured (`Startup p50 | Startup p95 | Wall p50 | Wall p95`), named by it (empty when
+     * there is one). Each series is named by its quantile (`p50`, `max`).
+     */
+    readonly ladders?: readonly ChartLadder[];
+}
+/** One measurement's quantiles in a `ladder` chart: its name and its series, lowest quantile first. */
+export interface ChartLadder {
+    readonly name: string;
+    readonly series: readonly number[];
+}
+/** A status column of a {@link ChartSpec.matrix}: its header and each category's status. */
+export interface StatusColumn {
+    readonly name: string;
+    readonly statuses: readonly (Status | undefined)[];
+}
+/** A fact a chart could state as its title, from {@link tableTakeaways}. */
+export interface Takeaway {
+    /** What the fact is about (`top:pass%`, `move:Build units`), unique among one chart's takeaways. */
+    readonly key: string;
+    readonly text: string;
+    /** Striking on its figures alone (a large move, a far outlier, a sweep): worth stating without a judge. */
+    readonly striking: boolean;
+}
+/**
+ * A mark a planner lays over a chart; the renderer draws each kind where the
+ * chart supports it (bar-like kinds and lines) and skips it elsewhere.
+ * - `reference`: a dashed rule across the plot at `value` (base units of the
+ *   first series), labelled at its end (`budget 200 ms`, `baseline`).
+ * - `highlight`: a soft band behind category `category` (an index into
+ *   {@link ChartSpec.categories}) and its label set in full strength.
+ * - `callout`: short `text` beside the mark of `category` in `series` (default
+ *   0) with a leader line (`60× the rest`, `fastest`).
+ */
+export type ChartAnnotation = {
+    readonly kind: "reference";
+    readonly value: number;
+    readonly label: string;
+    /** Series whose axis the value is on, for charts with an axis per unit (`range` bands); 0 by default. */
+    readonly series?: number;
+} | {
+    readonly kind: "highlight";
+    readonly category: number;
+} | {
+    readonly kind: "callout";
+    readonly category: number;
+    readonly series?: number;
+    readonly text: string;
+};
+/** The local best guess at a chart for `table`, or `undefined` when no chart fits. */
+export declare function planChart(table: TableAnalysis): ChartPlan | undefined;
+/**
+ * Whether a model should pick `table`'s chart (`tui.autoGraph: smart`):
+ * multi-series tables, and tables whose rows may be named by a number the
+ * `guess` plots (`Thread | State`, `Finding | Current`), where only meaning
+ * tells a name from a measure.
+ */
+export declare function shouldJudge(table: TableAnalysis, guess: ChartPlan | undefined): boolean;
+/** Measure columns before `guess`'s text label column: numbers that may only name their rows. */
+export declare function leadingMeasures(table: TableAnalysis, guess: ChartPlan): TableColumn[];
+/**
+ * Facts about `table` a chart could state as its headline under `plan`'s
+ * meaning, strongest first: those of the chart `plan` draws (its moves, its
+ * trend), and of measures side by side, under each of `contests` (`plan`'s
+ * own {@link ChartPlan.rivals} by default; a judge is offered either reading's).
+ * `scope` says which measures stand side by side: `drawn` (the default, what
+ * a title may state) only those the chart draws ({@link drawnNames}) — a
+ * headline citing a column the chart leaves out (`Total` beside a chart of
+ * `vs current`) names a figure the reader cannot find on it; `table` every
+ * measure (a row best on measures the chart leaves out), the options a judge
+ * weighs while it may still pick a chart drawing them.
+ */
+export declare function tableTakeaways(table: TableAnalysis, plan: ChartPlan, contests?: readonly (Rivals | undefined)[], scope?: "drawn" | "table"): Takeaway[];
+/**
+ * What a chart draws, by name: its series, its x measure (not the row names a line runs along), the
+ * whole its parts stack to and the baseline its factors are of — the columns (or, transposed, rows) a
+ * headline may cite.
+ */
+export declare function drawnNames(spec: ChartSpec): Set<string>;
+/**
+ * The local guess at what `plan`'s rows and measures mean: header keywords
+ * for each measure's {@link Polarity} (resources like tokens or memory only
+ * beside a baseline), rivals from the label's header, focus from bolded or
+ * `(current)` row names, and a status column whose cells vary.
+ */
+export declare function guessMeaning(table: TableAnalysis, plan: ChartPlan): Pick<ChartPlan, "polarity" | "rowPolarity" | "rivals" | "focus" | "status">;
+/** Whether `plan`'s rows may each be a metric of their own: a `change`, a transposed table, or mixed-unit columns. */
+export declare function rowsAreMetrics(table: TableAnalysis, plan: ChartPlan): boolean;
+/** Most segments one share bar keeps legible; more parts read as bars (a planner's `share` pick included). */
+export declare const MAX_SHARE_SEGMENTS = 10;
+/**
+ * Same-unit count or percent measures whose headers each lead with an outcome
+ * (`ok | fail`, `Pass | Partial | Fail`) of more than one kind: the parts of
+ * each row's attempts, read as its mix.
+ */
+export declare function outcomeColumns(measures: readonly TableColumn[]): TableColumn[] | undefined;
+/**
+ * The outcome each of `names` leads with (`ok`, `FAIL`, ✅, or none) when at
+ * least {@link TONED_SHARE} of them lead with one, `good` and something else
+ * among them: parts colored by what they say rather than by series
+ * (`✅ FIXED | 🟡 PARTIAL | 🎨 VISUAL? | ❌ OPEN`). `undefined` otherwise.
+ */
+export declare function outcomeTones(names: readonly string[]): (Status | undefined)[] | undefined;
+/** A measured column and the column of targets it is held to ({@link findTarget}). */
+export interface TargetColumns {
+    readonly measured: TableColumn;
+    readonly target: TableColumn;
+}
+/**
+ * The column of targets `table` holds its measure to, read from headers and cells: a header naming targets
+ * ({@link TARGET_HEADER}) over cells mostly holding one ({@link targetCell}) and mostly written as bounds (`≤
+ * 200 µs`), which a word naming nothing else ({@link TARGET_WORD}: `Target`, `Budget`) does without; never the
+ * first column, which keys the rows (a `limit` setting each row tries). The measure held to it is the nearest
+ * column to it (left first), not itself mostly bounds, whose cells share a unit and a sign convention with the
+ * targets ({@link measuredCell}) in two rows or more, in half the rows or more, and in at least half of the
+ * rows writing both. `undefined` when none.
+ */
+export declare function findTarget(table: TableAnalysis): TargetColumns | undefined;
+/**
+ * How `point` stands against `target`: `met` when it keeps the target's side (its worst end — the high end
+ * under a ceiling, the low end over a floor — at or past the target; inside a window), `close` when met
+ * within {@link CLOSE_SHARE}; `share` its worst end over the target (the window's top), `undefined` for a
+ * zero target. `undefined` for a target without a bound or window. Exported for the renderer.
+ */
+export declare function targetStanding(point: ChartPoint, target: ChartTarget): {
+    readonly met: boolean;
+    readonly close: boolean;
+    readonly share: number | undefined;
+} | undefined;
+/**
+ * Whether the table's prose carries it, so a chart of `columns` would only
+ * restate small whole numbers set beside sentences: text columns (other than
+ * the label) whose typical cells add up to {@link PROSE_CELL} characters a
+ * row, next to plotted values that are all whole numbers up to
+ * {@link MAX_PROSE_COUNT} (tiers, ratings, fixes per PR).
+ */
+export declare function proseLed(table: TableAnalysis, columns: readonly TableColumn[]): boolean;
+/**
+ * The data `plan` draws from `table`, or `undefined` when it leaves fewer than
+ * two categories or no series with two values. The kind is fitted to the
+ * series it ends up with ({@link fitKind}), so any plan — a model's pick
+ * included — draws as something the renderer supports.
+ */
+export declare function buildChart(table: TableAnalysis, plan: ChartPlan): ChartSpec | undefined;
+/** One quantile of a {@link Ladder}: a column holding it alone, or one item of a column's slash lists. */
+export interface Rung {
+    readonly column: TableColumn;
+    /** Which listed value of each cell (`p99` of `79 / 124 µs`); absent when the column holds the quantile alone. */
+    readonly slot?: number;
+    /** How many values each cell of a listing column holds (the quantiles its header lists). */
+    readonly slots?: number;
+    /** The quantile as the header writes it (`p50`, `max`). */
+    readonly name: string;
+    /** Where it ranks: 0 the minimum, 50 the median (or a mean beside quantiles), 100 the maximum. */
+    readonly rank: number;
+    /** The unit the header gives bare numbers (`cpu p50 / p95 (ms)`): their dimension and base factor. */
+    readonly scale?: readonly [Dimension, number];
+}
+/**
+ * Quantiles of one measurement per row (`p50 | p90 | p99 | max`, `Startup p50 | Startup p95`,
+ * `p50 / p99` cells), lowest rank first, all of one dimension.
+ */
+export interface Ladder {
+    /** The measurement (`Startup`, `zoom 1`); empty when its headers name nothing but quantiles. */
+    readonly name: string;
+    readonly rungs: readonly Rung[];
+    readonly dim: Dimension;
+    /** Currency symbol or rate unit the axis prints; empty for other dimensions. */
+    readonly unit: string;
+}
+/**
+ * `table`'s quantile ladders ({@link quantileLadders}) beside the `label` column, when their columns
+ * are at least half of what the table measures and no column holds per-row targets ({@link findTarget}:
+ * quantiles held to targets are a `bullet`): the table is about the distributions. Every column
+ * but the label may hold quantiles, measures and text alike — a quantile alike in every row (`p50` 2,
+ * 2) is no measure, and a list of three (`1.69 / 2.59 / 3.17`) reads as prose.
+ */
+export declare function tableLadders(table: TableAnalysis, label: number | undefined): Ladder[] | undefined;
+/** The columns `ladders` read their quantiles from, each once, in ladder order. */
+export declare function ladderColumns(ladders: readonly Ladder[]): number[];
+/**
+ * The quantile ladders among `measures`: columns whose headers each name one quantile of one
+ * measurement (`p50 | p90 | p99`, `Startup p50 | Startup p95`; a bare `p95` after `TTFT p50` joins
+ * it), and columns whose headers name a slash list of quantiles over cells listing that many values
+ * (`p50 / p99` over `79 / 124 µs`). A ladder needs two quantiles, one of them neither the minimum nor
+ * the maximum, one dimension, and its values rising with rank in {@link ORDERED_SHARE} of the rows
+ * holding two (two such rows at least); ladders in
+ * another dimension than the first leave, at most {@link MAX_LADDERS} stay. `undefined` when none.
+ */
+export declare function quantileLadders(measures: readonly TableColumn[], rows: readonly number[]): Ladder[] | undefined;
+/**
+ * `rows` as ordered bins of `column`: {@link MIN_BINS} to {@link MAX_BINS} cells each a value, a range
+ * or an open end (`1 | 2–5 | 6–20 | 21–100 | 100+`, `<1 ms | 1–10 ms | >10 ms`), not all single values,
+ * running one way and meeting end to start — no overlap, a gap of at most one between whole-number bins
+ * (or one written digit between decimal ones). The rows in ascending bin order, else `undefined`.
+ */
+export declare function binRows(column: TableColumn, rows: readonly number[]): number[] | undefined;
+/**
+ * The column whose rows are `table`'s ordered bins ({@link binRows}) — its label, else its first column —
+ * with the measures counting each bin ({@link frequencyColumns}); `undefined` unless both hold.
+ */
+export declare function histogramColumns(table: TableAnalysis, measures?: readonly TableColumn[]): {
+    bins: TableColumn;
+    counts: TableColumn[];
+} | undefined;
+/**
+ * The same-unit measures plotted as intervals when values written `a–b` make
+ * up most of the numbers of at least one of them ({@link RANGE_SHARE}), with the
+ * measures sharing its unit (an estimate column, a pair's other side); other
+ * units' interval columns join as bands of their own. At most {@link MAX_RANGES}.
+ */
+export declare function rangeColumns(measures: readonly TableColumn[], rows: readonly number[]): TableColumn[] | undefined;
+/**
+ * Whether `columns` over `rows` read best as dots: three to six columns of one measurement
+ * ({@link DOT_DIMS}) spanning {@link DOT_SPREAD}× or more, where grouped bars from zero would flatten
+ * the small values — one quantity whose rows sit apart on a log axis, or rows too tight for one axis
+ * beside a baseline column their factors can be read against ({@link dotLayout}).
+ */
+export declare function dotsFit(columns: readonly TableColumn[], rows: readonly number[]): boolean;
+/**
+ * The middle of a value written `a–b`, which a factor between two intervals compares: the geometric
+ * mean (`5.7–9.6 ms` → 7.4 ms), the arithmetic one from zero; a single value is its own.
+ */
+export declare function intervalMiddle(point: ChartPoint): number;
+/**
+ * Whether two headers name one quantity under two conditions — the one
+ * before/after helper every pair decision goes through (the judge's `pair`
+ * answer stands in for it where the headers say nothing): a before/after word
+ * ({@link isTransition}) or the same words around one that differs (`gpt-5.5
+ * window | gpt-5.4 (target) window`, `Q5_K_M | Q4_K_M`). Identical headers (a
+ * list wrapped into two halves) and unrelated quantities (`Verts | Faces`,
+ * `Tier | New Findings`) are no pair.
+ */
+export declare function isConditionPair(first: string, second: string): boolean;
+/**
+ * The direction of a condition pair: `first` names the before state and
+ * `second` the after one (`Baseline | Iter20`, `old (diff) | new`, `Stock |
+ * Patched`), so the pair reads as a move from `first` to `second`. A pair
+ * without such words (`xutf | std`, `Q5_K_M | Q4_K_M`) has no direction: peers.
+ */
+export declare function isTransition(first: string, second: string): boolean;
+/**
+ * Three to {@link MAX_STAGES} adjacent same-unit measures holding one quantity
+ * at successive stages of a run: a before column (`Baseline`, `Original`)
+ * followed by later stages ({@link STAGE_HEADER}: `Iter 1 | Iter 2`, `Best (Iter
+ * 3) | Iter 4`, `Round 1 | Now`), each typically within {@link QUANTITY_SPREAD}×
+ * of the first row by row (a `Tokens In (Iter2)` beside turns is another
+ * quantity). Deltas and totals end the run. `undefined` when no such run exists.
+ */
+export declare function stageColumns(measures: readonly TableColumn[], rows: readonly number[]): TableColumn[] | undefined;
+/**
+ * Two same-unit measures of opposing amounts ({@link OPPOSED}: `Removed |
+ * Added`, `Losses | Wins`), the losing side first, neither a delta or a total
+ * and neither naming both sides; `undefined` when no such pair exists.
+ */
+export declare function opposedColumns(measures: readonly TableColumn[]): [TableColumn, TableColumn] | undefined;
+/**
+ * Each category's value of `entry` as a factor of its group's reference
+ * category ({@link ChartSpec.reference}; the whole chart is one group without
+ * groups): `undefined` for the reference itself, outside any referenced
+ * group, or where either value is missing or not positive.
+ */
+export declare function referenceFactors(spec: ChartSpec, entry: ChartSeries): (number | undefined)[];
+/**
+ * A share in percent as a chart writes it: whole percents, one decimal within
+ * 1 of either end (`0.4%`, `99.6%`) so a sliver never rounds to nothing or
+ * everything, and `<0.1%` / `>99.9%` past that. Exported for the renderer.
+ */
+export declare function percentText(percent: number): string;
+/**
+ * Whether a chart of `spec` reads faster than its table: at least four
+ * categories (or small-multiple panels), and either nine plotted values or a
+ * 3× spread within a series. On a model-judged sample of assistant tables this
+ * gate kept 85% of the tables a chart clearly helped while rejecting most two-
+ * and three-row ones. A `change` needs three metrics and one moving by
+ * {@link NOTABLE_FACTOR} either way: its factors are what the table lacks.
+ * Series holding one value in all their categories but one (`5/5` in eight
+ * of nine rows) say nothing bars add to.
+ */
+export declare function worthCharting(spec: ChartSpec): boolean;
+/**
+ * Columns that may join `label` in naming rows: short text or date columns
+ * whose cells vary (a column of one value tells no rows apart).
+ */
+export declare function namingColumns(table: TableAnalysis, label: TableColumn | undefined): TableColumn[];
+/**
+ * The local guess at the columns naming rows beside `label`: the fewest of
+ * `spare` (by default {@link namingColumns}) that tell repeated labels apart
+ * (`Model | Harness`), the one with the fewest distinct values first (a factor
+ * like `Harness`, not a notes column); and as the group, the first naming
+ * column already running in blocks, so table order stays as written.
+ */
+export declare function guessNaming(table: TableAnalysis, label: TableColumn | undefined, spare?: readonly TableColumn[]): {
+    qualifiers: readonly number[];
+    group: number | undefined;
+};
+/**
+ * How a heatmap of `columns` over `rows` should shade: each column on its own
+ * when two columns typically differ {@link QUANTITY_SPREAD}× within a row
+ * (different quantities, like input vs. reasoning tokens), each row on its
+ * own when two rows typically do within a column (one measure on a small and
+ * a huge item) and a row's cells typically differ {@link ROW_CONTRAST}×,
+ * else one scale for every cell. The local default of the
+ * judge's shading answer.
+ */
+export declare function guessShading(columns: readonly TableColumn[], rows: readonly number[]): Shading;