@pythia-software/query-table-core 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1,143 +1,3 @@
-/** All filter operators across both source projects, unioned. Every value can
- *  be NULL, so `is_null`/`is_not_null` are valid for every field type. */
-type FilterOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "contains" | "starts_with" | "ends_with" | "matches_regex" | "not_matches_regex" | "length_gt" | "length_lt" | "length_eq" | "includes" | "is_null" | "is_not_null";
-/** A single filter predicate (a "literal" in CNF terms). `value` is always the
- *  raw string the UI captured; coercion to number/bool/date happens at
- *  apply/compile time based on the field's declared type (never on the value's
- *  runtime shape). Unused for the nullary ops (`is_null`/`is_not_null`).
- *
- *  `negated` wraps the predicate in a logical NOT. It is only ever set for ops
- *  that have no complementary operator (`contains`/`starts_with`/`ends_with`/
- *  `includes`); ops with a complement negate by flipping the op itself (`>=`→`<`,
- *  `=`→`!=`, `is_null`→`is_not_null`, `matches_regex`→`not_matches_regex`) — see
- *  `negateClause` in ops.ts. NOT is null-exclusive: a NULL/empty value satisfies
- *  neither the predicate nor its negation, matching `not_matches_regex`. */
-interface WhereClause {
-    field: string;
-    op: FilterOp;
-    value: string;
-    negated?: boolean;
-    setFilter?: SetFilterMetadata;
-}
-type SetFilterMode = "any" | "all" | "none" | "empty";
-/** Presentation-only identity; execution always uses the accompanying predicates. */
-interface SetFilterMetadata {
-    id: string;
-    mode: SetFilterMode;
-    values: string[];
-}
-/** A disjunction of predicates — the inner OR of conjunctive normal form. Every
- *  member is a plain literal; nesting is intentionally not allowed yet (CNF
- *  only), but the object shape leaves room to grow. */
-interface OrGroup {
-    any: WhereClause[];
-    setFilter?: SetFilterMetadata;
-}
-/** One conjunct of the WHERE clause: either a single predicate or an OR group.
- *  `QueryState.where` is the AND of these terms, so the whole WHERE is
- *  conjunctive normal form — `(a) AND (b OR c) AND (d)`. A bare literal is
- *  equivalent to a one-element OR group; normalization flattens singleton groups
- *  back to a literal so equality/encoding stay canonical. */
-type WhereTerm = WhereClause | OrGroup;
-/** Narrow a term to an OR group. A literal always carries `field`; a group never
- *  does and always carries an `any` array. */
-declare function isOrGroup(term: WhereTerm): term is OrGroup;
-/** The predicate literals a term contributes, in order: the term itself for a
- *  literal, or its members for a group. Handy for anything that must visit every
- *  predicate regardless of grouping (field allowlisting, SELECT projection). */
-declare function predicatesOf(term: WhereTerm): WhereClause[];
-/** One ORDER BY term. Array order in `QueryState.orderBy` is the sort priority. */
-interface OrderByClause {
-    field: string;
-    dir: "asc" | "desc";
-    /** NULL placement. Omitted = "last" (the historical default both projects used,
-     *  preserved so old `?q=` links round-trip identically). */
-    nulls?: "first" | "last";
-    /** Sort by the first capture group of a regex match (or by the whole match
-     *  when the pattern has no capture group). A non-match produces NULL. Regex
-     *  syntax is interpreted by the executor (JavaScript locally, PostgreSQL on
-     *  the bundled Go backend), so portable patterns should use their common
-     *  syntax subset. */
-    extract?: {
-        regex: string;
-    };
-}
-/** One column in the SELECT list, plus the view state that travels with it.
- *  Order in `QueryState.select` is the left-to-right display order. */
-interface SelectColumn {
-    field: string;
-    /** Pixel width override. Omitted = FieldDef.select.width, else the type default. */
-    width?: number;
-}
-/** A single aggregate operation. `count` is the only op that needs no measure
- *  column (it counts rows); the rest reduce one column's values. The server-side
- *  matrix (backends/go aggOpAllowed + the TS AGG_OPS_BY_TYPE) decides which ops a
- *  field's type permits. */
-type AggOp = "count" | "count_distinct" | "sum" | "avg" | "min" | "max";
-/** One optional "metric" pinned above the table: a single aggregate over a single
- *  measure column, optionally broken down by one or more group columns.
- *
- *  Scope is deliberately the *whole filtered set* — the same WHERE as the table,
- *  but NOT its ORDER BY / LIMIT / OFFSET. It is always evaluated on the server
- *  (a real GROUP BY), so it reflects every matching row, not just the visible
- *  page. Lives inside QueryState so it round-trips through `?q=`, saved queries,
- *  and undo/redo for free — a saved query is a saved dashboard. */
-interface AggregationClause {
-    /** Stable id; keys the metric panel and survives a `?q=` round-trip. */
-    id: string;
-    op: AggOp;
-    /** Measure column (FieldDef.name). Omit only for `count` (⇒ COUNT(*)). */
-    field?: string;
-    /** Group-by columns, in axis order. `[]` = a single grand-total value.
-     *  One ⇒ a list/bar breakdown; two ⇒ an x/y pivot; three+ ⇒ a flat table. */
-    groupBy: string[];
-    /** Panel header override; defaults to a derived label like "avg total". */
-    label?: string;
-}
-interface QueryState {
-    /** Ordered SELECT list + per-column widths. Empty = the schema's default columns. */
-    select: SelectColumn[];
-    /** WHERE in conjunctive normal form: the AND of these terms, each a single
-     *  predicate or an OR group. A flat list of literals (no groups) is the common
-     *  case and the legacy shape, decoded unchanged. */
-    where: WhereTerm[];
-    /** Multi-sort terms in priority order. Empty = the schema's default sort. */
-    orderBy: OrderByClause[];
-    /** Page size. */
-    limit: number;
-    /** Page offset (rows). */
-    offset: number;
-    /** Optional aggregate metrics shown above the table. Omitted/empty = none.
-     *  Each runs as its own server GROUP BY over the WHERE-filtered set (no paging). */
-    aggregations?: AggregationClause[];
-}
-/** A row's stable identity, used for selection and per-row refresh. */
-type RowId = string | number;
-/** The query a fresh table starts from before schema defaults are layered on.
- *  Empty `select`/`orderBy`/`where` mean "defer to the schema", which also keeps
- *  encoded `?q=` tokens short (defaults are omitted). */
-declare const EMPTY_QUERY: QueryState;
-/** Structural limits applied whenever query state crosses a trust boundary
- * (URL, storage, an imperative setQuery call, or a server projection). Row
- * limits may use the full safe-integer range; consumers and their backends own
- * any smaller operational cap appropriate for their dataset. */
-declare const MAX_QUERY_LIMIT: number;
-declare const MAX_QUERY_OFFSET = 1000000;
-declare const MAX_SELECT_COLUMNS = 200;
-declare const MAX_WHERE_CLAUSES = 100;
-declare const MAX_ORDER_BY_TERMS = 20;
-declare const MAX_AGGREGATIONS = 20;
-declare const MAX_GROUP_BY_FIELDS = 20;
-declare const MAX_QUERY_TOKEN_LENGTH: number;
-/** Convert unknown input into a bounded, structurally valid QueryState.
- * Invalid members are dropped; invalid scalar paging values use the supplied
- * fallback. This function is intentionally schema-agnostic—field allowlisting
- * still happens in toServerQuery and in the backend compiler. */
-declare function normalizeQueryState(input: unknown, fallback?: QueryState): QueryState;
-/** Structural equality on two queries — used to decide whether a `?q=` write or a
- *  refetch is actually needed (avoids history spam / redundant fetches). */
-declare function queriesEqual(a: QueryState, b: QueryState): boolean;
-
 type FieldType = "text" | "number" | "enum" | "datetime" | "bool" | "textarray";
 type Align = "left" | "right" | "center";
 /** A cell renderer is resolved by name against a `RenderRegistry` (in
@@ -257,27 +117,356 @@ interface FieldSchema<Row = any> {
     /** Page size for a fresh query. */
     defaultLimit?: number;
 }
-declare function isFilterable(f: FieldDef): boolean;
-declare function isPushdownFilter(f: FieldDef): boolean;
-declare function isSortable(f: FieldDef): boolean;
-declare function isSelectable(f: FieldDef): boolean;
-declare function filterValues(f: FieldDef): FilterValues;
-/** Index fields by name for O(1) lookup. */
-declare function indexFields<Row>(schema: FieldSchema<Row>): Map<string, FieldDef<Row>>;
-/** Resolve the ordered, selectable FieldDefs for a query, falling back to schema
- *  defaults, then to every `select.default` field. Unknown/duplicate/unselectable
- *  names in `select` are dropped. */
-declare function selectedFields<Row>(schema: FieldSchema<Row>, q: {
+declare function isFilterable(f: FieldDef): boolean;
+declare function isPushdownFilter(f: FieldDef): boolean;
+declare function isSortable(f: FieldDef): boolean;
+declare function isSelectable(f: FieldDef): boolean;
+declare function filterValues(f: FieldDef): FilterValues;
+/** Index fields by name for O(1) lookup. */
+declare function indexFields<Row>(schema: FieldSchema<Row>): Map<string, FieldDef<Row>>;
+/** Resolve the ordered, selectable FieldDefs for a query, falling back to schema
+ *  defaults, then to every `select.default` field. Unknown/duplicate/unselectable
+ *  names in `select` are dropped. */
+declare function selectedFields<Row>(schema: FieldSchema<Row>, q: {
+    select: SelectColumn[];
+}): FieldDef<Row>[];
+/** Return the canonical name for a query token, or undefined when unresolved. */
+declare function resolveFieldName<Row>(schema: FieldSchema<Row>, field: string): string | undefined;
+/** Read a field's value from a row: derived `accessor` if present, else the
+ *  backend `path` (dotted) / `name`. Returns null when any path segment is missing. */
+declare function readFieldValue<Row, V = unknown>(field: FieldDef<Row, V>, row: Row): V | null;
+/** Parse + validate a raw JSON schema document into a FieldSchema. The doc is the
+ *  same one the Go backend loads; here we drop backend `bindings` (the frontend
+ *  never sees SQL) and leave `render` as a string key the consumer maps to a
+ *  renderer at runtime. Throws with a readable message on a malformed document. */
+declare function loadSchema<Row = any>(doc: unknown): FieldSchema<Row>;
+
+type FormulaType = Exclude<FieldType, "enum"> | "null";
+type FormulaValue = string | number | boolean | string[] | null;
+interface FormulaDiagnostic {
+    message: string;
+    from: number;
+    to: number;
+}
+type FormulaNode = {
+    kind: "literal";
+    value: FormulaValue;
+    from: number;
+    to: number;
+} | {
+    kind: "field";
+    name: string;
+    valueType?: FormulaType;
+    from: number;
+    to: number;
+} | {
+    kind: "call";
+    name: string;
+    args: FormulaNode[];
+    from: number;
+    to: number;
+};
+interface FormulaPlan {
+    ast: FormulaNode;
+    dependencies: string[];
+    type: FormulaType;
+}
+interface RegexInspection {
+    input: string;
+    start: number;
+    end: number;
+    groups: (string | null)[];
+}
+interface FormulaResult {
+    value: FormulaValue;
+    error?: string;
+    regex?: RegexInspection;
+}
+interface FormulaFunction {
+    name: string;
+    signature: string;
+    description: string;
+    min: number;
+    max: number;
+    result: FormulaType | "branch";
+    args: FormulaType[] | "any";
+}
+declare const FORMULA_FUNCTIONS: FormulaFunction[];
+declare class FormulaError extends Error {
+    from: number;
+    to: number;
+    constructor(message: string, from?: number, to?: number);
+}
+declare function compileFormula(source: string, fields: readonly {
+    name: string;
+    type: FieldType;
+}[], resolve?: (name: string) => FormulaPlan | undefined, extension?: (node: FormulaNode, check: (node: FormulaNode) => FormulaType) => FormulaType | undefined): FormulaPlan;
+/** Self-contained runtime: serialized into the browser worker, never user code. */
+declare function formulaRuntime(ast: FormulaNode, inputs: Record<string, FormulaValue>, extension?: (node: Extract<FormulaNode, {
+    kind: "call";
+}>) => FormulaResult | undefined): FormulaResult;
+
+type MetricValue = number | string | boolean | null;
+type MetricKey = MetricValue;
+type MetricScope = "allMatching" | "shownRows";
+interface MetricValueFormat {
+    kind: "number" | "percent" | "duration" | "date" | "time" | "datetime";
+    decimals?: number;
+    sourceUnit?: "milliseconds" | "seconds" | "minutes" | "hours" | "days" | "iso" | "epochSeconds" | "epochMilliseconds" | "secondsOfDay" | "millisecondsOfDay";
+    style?: "human" | "long" | "clock" | "custom" | "iso";
+    pattern?: string;
+    timeZone?: string;
+}
+/** Bounds use raw result units; omitted bounds are inferred from the data. */
+interface MetricAxisScale {
+    mode?: "linear" | "log";
+    min?: number;
+    max?: number;
+}
+interface MetricDisplay {
+    kind: "auto" | "value" | "table" | "list" | "bar-horizontal" | "bar-vertical" | "line" | "pie" | "donut" | "scatter" | "box" | "histogram";
+    valueLabel?: string;
+    xLabel?: string;
+    yLabel?: string;
+    format?: MetricValueFormat;
+    xFormat?: MetricValueFormat;
+    yFormat?: MetricValueFormat;
+    legendPosition?: "left" | "right" | "top" | "bottom" | "none";
+    list?: {
+        showBars?: boolean;
+        useGroupColors?: boolean;
+        showValues?: boolean;
+    };
+    pivot?: {
+        swap?: boolean;
+        rowDir?: "asc" | "desc";
+        columnDir?: "asc" | "desc";
+    };
+    boxMean?: boolean;
+    xScale?: MetricAxisScale;
+    yScale?: MetricAxisScale;
+}
+interface MetricLayout {
+    widthRem: number;
+    heightRem: number;
+    minWidthRem: number;
+    minHeightRem: number;
+}
+interface MetricDistribution {
+    kind: "box" | "histogram";
+    input: string;
+    whiskers?: "minmax" | "tukey";
+    bins?: number;
+}
+interface MetricSort {
+    key: "value" | "y" | "count" | "samples" | `group${number}`;
+    dir: "asc" | "desc";
+    nulls?: "first" | "last";
+}
+interface MetricBoxSummary {
+    n: number;
+    min: number;
+    q1: number;
+    median: number;
+    q3: number;
+    max: number;
+    mean: number;
+    low: number;
+    high: number;
+    outliers: number[];
+    outlierCount: number;
+    whiskers: "minmax" | "tukey";
+    method: "exact-linear";
+}
+type MetricDistributionResult = {
+    kind: "box";
+    summary: MetricBoxSummary | null;
+} | {
+    kind: "histogram";
+    edges: number[];
+    counts: number[];
+    n: number;
+};
+interface MetricDiagnostic extends FormulaDiagnostic {
+    metricId?: string;
+    code?: string;
+}
+/** Host must enforce snapshot against the row response; this token alone does not pin data. */
+interface MetricQuery {
+    snapshot?: string;
+    profile?: string;
+    expectedRevisions?: Record<string, string>;
+    planToken?: string;
+    version: 2;
+    where: WhereTerm[];
+    orderBy: OrderByClause[];
+    limit: number;
+    offset: number;
+    metrics: AggregationClause[];
+    diagnostics: MetricDiagnostic[];
+}
+interface MetricCapabilities {
+    version: 2;
+    expressions?: boolean;
+    shownRows?: boolean;
+    distributions?: boolean;
+    computedFields?: boolean;
+    maxGroups?: number;
+    profile?: string;
+}
+
+/** All filter operators across both source projects, unioned. Every value can
+ *  be NULL, so `is_null`/`is_not_null` are valid for every field type. */
+type FilterOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "contains" | "starts_with" | "ends_with" | "matches_regex" | "not_matches_regex" | "length_gt" | "length_lt" | "length_eq" | "includes" | "is_null" | "is_not_null";
+/** A single filter predicate (a "literal" in CNF terms). `value` is always the
+ *  raw string the UI captured; coercion to number/bool/date happens at
+ *  apply/compile time based on the field's declared type (never on the value's
+ *  runtime shape). Datetime comparisons also accept signed duration offsets
+ *  such as "-1h" or "+8d2h10m", resolved relative to execution time.
+ *  Unused for the nullary ops (`is_null`/`is_not_null`).
+ *
+ *  `negated` wraps the predicate in a logical NOT. It is only ever set for ops
+ *  that have no complementary operator (`contains`/`starts_with`/`ends_with`/
+ *  `includes`); ops with a complement negate by flipping the op itself (`>=`→`<`,
+ *  `=`→`!=`, `is_null`→`is_not_null`, `matches_regex`→`not_matches_regex`) — see
+ *  `negateClause` in ops.ts. NOT is null-exclusive: a NULL/empty value satisfies
+ *  neither the predicate nor its negation, matching `not_matches_regex`. */
+interface WhereClause {
+    field: string;
+    op: FilterOp;
+    value: string;
+    negated?: boolean;
+    setFilter?: SetFilterMetadata;
+}
+type SetFilterMode = "any" | "all" | "none" | "empty";
+/** Presentation-only identity; execution always uses the accompanying predicates. */
+interface SetFilterMetadata {
+    id: string;
+    mode: SetFilterMode;
+    values: string[];
+}
+/** A disjunction of predicates — the inner OR of conjunctive normal form. Every
+ *  member is a plain literal; nesting is intentionally not allowed yet (CNF
+ *  only), but the object shape leaves room to grow. */
+interface OrGroup {
+    any: WhereClause[];
+    setFilter?: SetFilterMetadata;
+}
+/** One conjunct of the WHERE clause: either a single predicate or an OR group.
+ *  `QueryState.where` is the AND of these terms, so the whole WHERE is
+ *  conjunctive normal form — `(a) AND (b OR c) AND (d)`. A bare literal is
+ *  equivalent to a one-element OR group; normalization flattens singleton groups
+ *  back to a literal so equality/encoding stay canonical. */
+type WhereTerm = WhereClause | OrGroup;
+/** Narrow a term to an OR group. A literal always carries `field`; a group never
+ *  does and always carries an `any` array. */
+declare function isOrGroup(term: WhereTerm): term is OrGroup;
+/** The predicate literals a term contributes, in order: the term itself for a
+ *  literal, or its members for a group. Handy for anything that must visit every
+ *  predicate regardless of grouping (field allowlisting, SELECT projection). */
+declare function predicatesOf(term: WhereTerm): WhereClause[];
+/** One ORDER BY term. Array order in `QueryState.orderBy` is the sort priority. */
+interface OrderByClause {
+    field: string;
+    dir: "asc" | "desc";
+    /** NULL placement. Omitted = "last" (the historical default both projects used,
+     *  preserved so old `?q=` links round-trip identically). */
+    nulls?: "first" | "last";
+    /** Sort by the first capture group of a regex match (or by the whole match
+     *  when the pattern has no capture group). A non-match produces NULL. Regex
+     *  syntax is interpreted by the executor (JavaScript locally, PostgreSQL on
+     *  the bundled Go backend), so portable patterns should use their common
+     *  syntax subset. */
+    extract?: {
+        regex: string;
+    };
+}
+/** One column in the SELECT list, plus the view state that travels with it.
+ *  Order in `QueryState.select` is the left-to-right display order. */
+interface SelectColumn {
+    field: string;
+    /** Pixel width override. Omitted = FieldDef.select.width, else the type default. */
+    width?: number;
+}
+/** A single aggregate operation. `count` is the only op that needs no measure
+ *  column (it counts rows); the rest reduce one column's values. The server-side
+ *  matrix (backends/go aggOpAllowed + the TS AGG_OPS_BY_TYPE) decides which ops a
+ *  field's type permits. */
+type AggOp = "count" | "count_distinct" | "sum" | "avg" | "min" | "max";
+/** One optional "metric" pinned above the table: a single aggregate over a single
+ *  measure column, optionally broken down by one or more group columns.
+ *
+ *  Scope is deliberately the *whole filtered set* — the same WHERE as the table,
+ *  but NOT its ORDER BY / LIMIT / OFFSET. It is always evaluated on the server
+ *  (a real GROUP BY), so it reflects every matching row, not just the visible
+ *  page. Lives inside QueryState so it round-trips through `?q=`, saved queries,
+ *  and undo/redo for free — a saved query is a saved dashboard. */
+interface AggregationClause {
+    expression?: string;
+    expressionY?: string;
+    scope?: MetricScope;
+    sort?: MetricSort[];
+    groupLimit?: number;
+    display?: MetricDisplay;
+    layout?: MetricLayout;
+    distribution?: MetricDistribution;
+    diagnostics?: string[];
+    /** Preserved source operation when this client does not implement it. */
+    unsupportedOp?: string;
+    /** Stable id; keys the metric panel and survives a `?q=` round-trip. */
+    id: string;
+    op: AggOp;
+    /** Measure column (FieldDef.name). Omit only for `count` (⇒ COUNT(*)). */
+    field?: string;
+    /** Group-by columns, in axis order. `[]` = a single grand-total value.
+     *  One ⇒ a list/bar breakdown; two ⇒ an x/y pivot; three+ ⇒ a flat table. */
+    groupBy: string[];
+    /** Panel header override; defaults to a derived label like "avg total". */
+    label?: string;
+}
+interface QueryState {
+    /** Ordered SELECT list + per-column widths. Empty = the schema's default columns. */
     select: SelectColumn[];
-}): FieldDef<Row>[];
-/** Read a field's value from a row: derived `accessor` if present, else the
- *  backend `path` (dotted) / `name`. Returns null when any path segment is missing. */
-declare function readFieldValue<Row, V = unknown>(field: FieldDef<Row, V>, row: Row): V | null;
-/** Parse + validate a raw JSON schema document into a FieldSchema. The doc is the
- *  same one the Go backend loads; here we drop backend `bindings` (the frontend
- *  never sees SQL) and leave `render` as a string key the consumer maps to a
- *  renderer at runtime. Throws with a readable message on a malformed document. */
-declare function loadSchema<Row = any>(doc: unknown): FieldSchema<Row>;
+    /** WHERE in conjunctive normal form: the AND of these terms, each a single
+     *  predicate or an OR group. A flat list of literals (no groups) is the common
+     *  case and the legacy shape, decoded unchanged. */
+    where: WhereTerm[];
+    /** Multi-sort terms in priority order. Empty = the schema's default sort. */
+    orderBy: OrderByClause[];
+    /** Page size. */
+    limit: number;
+    /** Page offset (rows). */
+    offset: number;
+    /** Optional aggregate metrics shown above the table. Omitted/empty = none.
+     *  Each runs as its own server GROUP BY over the WHERE-filtered set (no paging). */
+    aggregations?: AggregationClause[];
+}
+/** A row's stable identity, used for selection and per-row refresh. */
+type RowId = string | number;
+/** The query a fresh table starts from before schema defaults are layered on.
+ *  Empty `select`/`orderBy`/`where` mean "defer to the schema", which also keeps
+ *  encoded `?q=` tokens short (defaults are omitted). */
+declare const EMPTY_QUERY: QueryState;
+/** Structural limits applied whenever query state crosses a trust boundary
+ * (URL, storage, an imperative setQuery call, or a server projection). Row
+ * limits may use the full safe-integer range; consumers and their backends own
+ * any smaller operational cap appropriate for their dataset. */
+declare const MAX_QUERY_LIMIT: number;
+declare const MAX_QUERY_OFFSET = 1000000;
+declare const MAX_SELECT_COLUMNS = 200;
+declare const MAX_WHERE_CLAUSES = 100;
+declare const MAX_ORDER_BY_TERMS = 20;
+declare const MAX_AGGREGATIONS = 20;
+declare const MAX_GROUP_BY_FIELDS = 20;
+declare const MAX_QUERY_TOKEN_LENGTH: number;
+/** Convert unknown input into a bounded, structurally valid QueryState.
+ * Invalid members are dropped; invalid scalar paging values use the supplied
+ * fallback. This function is intentionally schema-agnostic—field allowlisting
+ * still happens in toServerQuery and in the backend compiler. */
+declare function normalizeQueryState(input: unknown, fallback?: QueryState): QueryState;
+/** Structural equality on two queries — used to decide whether a `?q=` write or a
+ *  refetch is actually needed (avoids history spam / redundant fetches). */
+declare function queriesEqual(a: QueryState, b: QueryState): boolean;
 
 /** The logical negation of a predicate. Prefers flipping to the complementary
  *  operator (nicer to read, and the server's op allowlist already covers it);
@@ -320,7 +509,7 @@ declare function opAllowedForType(type: FieldType, op: FilterOp): boolean;
 /** Coerce a raw string value to the type the field expects, for client-side
  *  comparison. Throws on invalid input (e.g. a non-numeric value on a number
  *  field) so callers can surface it rather than silently mis-filtering. */
-declare function coerceValue(type: FieldType, raw: string): string | number | boolean;
+declare function coerceValue(type: FieldType, raw: string, now?: number): string | number | boolean;
 
 /** Default aggregate ops per field type. A FieldDef.aggregate.ops overrides this.
  *  `count`/`count_distinct` work on anything countable; sum/avg are numeric-only;
@@ -371,22 +560,40 @@ declare function toServerQuery<Row>(q: QueryState, schema: FieldSchema<Row>): Se
  *  metrics describe every matching row, not the visible page. Mirrors the Go
  *  AggSpec list. */
 interface AggregationRequest {
+    diagnostics?: MetricDiagnostic[];
     where: WhereTerm[];
     aggregations: AggregationClause[];
 }
 /** One group's result. `keys` has one entry per AggregationClause.groupBy field,
  *  in axis order (`[]` for a grand total); a null key is the NULL/empty bucket. */
 interface AggregationBucket {
-    keys: (string | null)[];
+    keys: MetricKey[];
+    error?: string;
+    y?: MetricValue;
+    yError?: string;
+    components?: {
+        expression: string;
+        value: MetricValue;
+    }[];
+    nullCount?: number;
+    inputErrorCount?: number;
+    distribution?: MetricDistributionResult;
     /** The metric: a number for count/sum/avg, or the column's value for min/max
      *  (which may be a string for text/datetime). null when undefined (e.g. avg of
      *  an all-null column). */
-    value: number | string | null;
+    value: MetricValue;
     /** COUNT(*) of rows in the group — always present, even when `value` isn't a
      *  count, so the panel can show group sizes / shares. */
     count: number;
 }
 interface AggregationResultEntry {
+    /** Exact omitted additive quantity; unavailable for ratios/averages/distinct. */
+    other?: AggregationBucket;
+    error?: string;
+    scope?: MetricScope;
+    processedRows?: number;
+    groupCount?: number;
+    coverage?: "exact" | "partial";
     /** Echoes AggregationClause.id. */
     id: string;
     buckets: AggregationBucket[];
@@ -401,6 +608,145 @@ interface AggregationResult {
  *  unknown field are dropped — the server has no SQL for them. */
 declare function toAggregationQuery<Row>(q: QueryState, schema: FieldSchema<Row>): AggregationRequest;
 
+/** Reserved field token namespace. Query state stores IDs, never formula source. */
+declare const COMPUTED_PREFIX = "@computed/";
+declare const computedFieldName: (id: string) => string;
+declare const isComputedField: (name: string) => boolean;
+interface ComputedColumn {
+    id: string;
+    label: string;
+    expression: {
+        language: "qt-expr";
+        version: 1;
+        source: string;
+    };
+    /** Optimistic concurrency token issued by the store. */
+    revision: string;
+}
+type ComputedColumnDraft = Omit<ComputedColumn, "revision">;
+interface ComputedColumnStore {
+    /** Return the complete authorized catalogue for this dataset. */
+    list(dataset: string, signal?: AbortSignal): Promise<ComputedColumn[]>;
+    /** null creates a new ID; updates must match the current revision. */
+    save(dataset: string, column: ComputedColumnDraft, expectedRevision: string | null): Promise<ComputedColumn>;
+    /** Optional push invalidation, including changes from other sessions. */
+    subscribe?(dataset: string, listener: () => void): () => void;
+}
+declare function validateComputedColumn(input: unknown): ComputedColumn;
+declare function memoryComputedColumnStore(seed?: Record<string, ComputedColumn[]>): ComputedColumnStore;
+/** REST adapter. The implementing server owns authorization and DB persistence.
+ * GET base?dataset=… → ComputedColumn[]
+ * PUT base?dataset=… → {column, expectedRevision} → ComputedColumn
+ * Return HTTP 409 for a stale revision. No formula evaluation happens there. */
+declare function httpComputedColumnStore(base: string, fetcher?: typeof fetch): ComputedColumnStore;
+interface ComputedCellError {
+    computedError: string;
+}
+declare function isComputedCellError(value: unknown): value is ComputedCellError;
+interface PreviewGroup {
+    inputs: FormulaValue[];
+    result: FormulaResult;
+    count: number;
+}
+interface ColumnPreview {
+    dependencies: string[];
+    groups: PreviewGroup[];
+    processed: number;
+    total: number;
+    nulls: number;
+    errors: number;
+}
+declare function groupPreview(dependencies: string[], inputs: Record<string, FormulaValue>[], results: FormulaResult[], total: number): ColumnPreview;
+/** Server-issued capabilities are hints for client planning, never authorization. */
+interface ComputedFieldCapabilities {
+    type: FieldType;
+    select: boolean;
+    sort: boolean;
+    measure: boolean;
+    group: boolean;
+    reason?: string;
+}
+interface ComputedExecution {
+    profile: string;
+    planToken: string;
+    resolvedRevisions: Record<string, string>;
+    fields: Record<string, ComputedFieldCapabilities>;
+    fingerprint?: string;
+    snapshot?: string;
+}
+type RowComputedValues = Record<string, {
+    value: MetricValue;
+    error?: {
+        code: string;
+    };
+}>;
+
+/** Portable datetime/offset bound in milliseconds (also below MAX_SAFE_INTEGER). */
+declare const MAX_RELATIVE_TIME_MS = 8640000000000000;
+/** A signed elapsed offset, e.g. -1h or +8d2h10m. The sign applies to the
+ * complete sum. Returns null for absolute values or invalid duration syntax.
+ * Units are lowercase; amounts are whole integers. No whitespace, calendar
+ * arithmetic, locale, or Date.parse heuristics are used. */
+declare function parseRelativeDuration(value: string): number | null;
+/** Local execution only. The server independently owns its execution clock. */
+interface QueryEvaluationOptions {
+    now?: number;
+}
+
+interface MetricPlan extends FormulaPlan {
+    aggregates: Extract<FormulaNode, {
+        kind: "call";
+    }>[];
+    aggregateTypes: FormulaType[];
+}
+declare function compileMetric(expression: string, schema: FieldSchema | readonly FieldDef[], resolve?: (name: string) => FormulaPlan | undefined): MetricPlan;
+/** Row plans for worker evaluation. Null denotes COUNT(), which requires only row count. */
+declare function metricAggregatePlans(plan: MetricPlan): (FormulaPlan | null)[];
+/** Reduce exact per-row worker results; errors are not silently treated as NULL. */
+interface MetricReductionOptions {
+    /** Retained distinct entries, independently bounded from row count. */
+    maxDistinctValues?: number;
+    /** Conservative UTF-16 payload plus per-entry storage estimate. */
+    maxDistinctBytes?: number;
+}
+declare function reduceMetricValues(node: Extract<FormulaNode, {
+    kind: "call";
+}>, results: readonly FormulaResult[], options?: MetricReductionOptions): FormulaResult;
+/** Evaluate the group AST lazily from reductions indexed like plan.aggregates.
+ * A dead IF/COALESCE branch does not observe a failed aggregate in that branch. */
+declare function evaluateMetricReductions(plan: MetricPlan, reductions: readonly FormulaResult[]): FormulaResult;
+declare function metricExpression(clause: AggregationClause): string;
+declare function hasRegex(plan: FormulaPlan): boolean;
+declare function metricPlans(c: AggregationClause, schema: FieldSchema, resolve?: (name: string) => FormulaPlan | undefined): FormulaPlan[];
+declare function validateMetric(c: AggregationClause, schema: FieldSchema, resolve?: (name: string) => FormulaPlan | undefined): FormulaDiagnostic[];
+declare function metricDependencies(c: AggregationClause, schema: FieldSchema, resolve?: (name: string) => FormulaPlan | undefined): string[];
+declare function metricComputationKey(clauses: readonly AggregationClause[]): string;
+declare function toMetricQuery<Row>(q: QueryState, schema: FieldSchema<Row>, execution?: ComputedExecution): MetricQuery;
+/** Safe pre-worker page selection. A supplied committed page needs no query execution.
+ * Query regex is never executed here; all-matching regex filtering is unsupported. */
+declare function selectMetricShownRows<Row>(rows: Row[], q: QueryState, schema: FieldSchema<Row>, options?: MetricEvaluationOptions<Row>): Row[];
+interface MetricEvaluationOptions<Row = unknown> extends QueryEvaluationOptions, MetricReductionOptions {
+    resolveComputed?: (name: string) => FormulaPlan | undefined;
+    /** Called only for regex row ASTs, using cached results from a terminable worker. */
+    evaluateInput?: (node: FormulaNode, row: Row, plan: FormulaPlan) => FormulaResult;
+    /** Exact committed page supplied by the host after filters/order/window. */
+    /** Escaped tuple length bound, in UTF-16 code units (default 65,536). */
+    maxGroupKeyLength?: number;
+    /** Retained group keys, map/bucket overhead and row references, plus key scratch space (default 16 MB). */
+    maxGroupBytes?: number;
+    shownRows?: Row[];
+    maxRows?: number;
+    maxGroups?: number;
+    /** Per-metric operation budget (default 10,000,000, allowing simple paired
+     * aggregates across the default one-million-row population limit). */
+    maxOperations?: number;
+    /** @deprecated Regex requires cached evaluateInput; this flag grants no execution permission. */ allowRegex?: boolean;
+    signal?: AbortSignal;
+}
+/** Typed lexicographic ordering with null placement independent of direction. */
+declare function compareMetricValues(a: MetricValue, b: MetricValue): number;
+declare function evaluateMetrics<Row>(rows: Row[], q: QueryState, schema: FieldSchema<Row>, options?: MetricEvaluationOptions<Row>): AggregationResult;
+
 interface ApplyResult<Row> {
     /** The page slice (after filter + sort + offset/limit). */
     rows: Row[];
@@ -408,17 +754,42 @@ interface ApplyResult<Row> {
     total: number;
 }
 /** Filter + multi-sort + paginate `rows` per `q`, resolving field types/paths
- *  from `schema`. Pure; never mutates `rows`. Clauses/sorts on unknown fields are
+ *  from `schema`. Never mutates `rows`. Relative predicates use options.now or
+ *  one captured Date.now(). Clauses/sorts on unknown fields are
  *  ignored (the backend already enforced its own allowlist). */
-declare function applyQuery<Row>(rows: Row[], q: QueryState, schema: FieldSchema<Row>): ApplyResult<Row>;
+declare function applyQuery<Row>(rows: Row[], q: QueryState, schema: FieldSchema<Row>, options?: QueryEvaluationOptions): ApplyResult<Row>;
 /** Does one row satisfy one clause? Exposed for the CellMenu preview + tests. */
-declare function matchesClause<Row>(row: Row, clause: WhereClause, schema: FieldSchema<Row>): boolean;
+declare function matchesClause<Row>(row: Row, clause: WhereClause, schema: FieldSchema<Row>, options?: QueryEvaluationOptions): boolean;
 /** Client-side mirror of the backend GROUP BY (the executor for `clientRows`
  *  mode / the demo). Scope matches the server contract: the WHERE-filtered set
  *  only — ORDER BY / LIMIT / OFFSET are intentionally ignored, so a metric
  *  reflects every matching row, not the visible page. Must agree with
  *  backends/go's aggregate compile on op semantics. */
-declare function applyAggregations<Row>(rows: Row[], q: QueryState, schema: FieldSchema<Row>): AggregationResult;
+declare function applyAggregations<Row>(rows: Row[], q: QueryState, schema: FieldSchema<Row>, options?: MetricEvaluationOptions<Row>): AggregationResult;
+
+/** Versioned row projection keeps server-computed payload separate from host row fields. */
+interface ServerQueryV2 extends ServerQuery {
+    version: 2;
+    profile: string;
+    expectedRevisions: Record<string, string>;
+    planToken?: string;
+    /** Host must enforce this binding against the row response. */
+    snapshot?: string;
+    diagnostics: MetricDiagnostic[];
+}
+interface FetchRowsResultV2<Row> {
+    version: 2;
+    rows: Row[];
+    total: number;
+    computed: {
+        id: RowId;
+        values: RowComputedValues;
+    }[];
+    execution: ComputedExecution;
+}
+/** Project with a previously resolved server capability envelope. This does not
+ * authorize definitions or upload their source; the backend revalidates revisions. */
+declare function toServerQueryV2<Row>(q: QueryState, schema: FieldSchema<Row>, execution: ComputedExecution): ServerQueryV2;
 
 interface FetchRowsResult<Row> {
     rows: Row[];
@@ -452,6 +823,9 @@ interface FieldStats {
     max?: string | number;
 }
 interface Transport<Row = any> {
+    fetchRowsV2?(query: ServerQueryV2, signal?: AbortSignal): Promise<FetchRowsResultV2<Row>>;
+    metricCapabilities?: MetricCapabilities;
+    fetchMetrics?(query: MetricQuery, signal?: AbortSignal): Promise<AggregationResult>;
     /** Run a server query. The only required method — a purely client-side table
      *  can omit a Transport entirely and rely on applyQuery over local rows. */
     fetchRows(query: ServerQuery, signal?: AbortSignal): Promise<FetchRowsResult<Row>>;
@@ -506,119 +880,6 @@ declare function memoryStorageAdapter(): StorageAdapter;
  * datasets. Falls back to no persistence when storage is unavailable. */
 declare function localStorageAdapter(): StorageAdapter;
 
-type FormulaType = Exclude<FieldType, "enum"> | "null";
-type FormulaValue = string | number | boolean | string[] | null;
-interface FormulaDiagnostic {
-    message: string;
-    from: number;
-    to: number;
-}
-type FormulaNode = {
-    kind: "literal";
-    value: FormulaValue;
-    from: number;
-    to: number;
-} | {
-    kind: "field";
-    name: string;
-    valueType?: FormulaType;
-    from: number;
-    to: number;
-} | {
-    kind: "call";
-    name: string;
-    args: FormulaNode[];
-    from: number;
-    to: number;
-};
-interface FormulaPlan {
-    ast: FormulaNode;
-    dependencies: string[];
-    type: FormulaType;
-}
-interface RegexInspection {
-    input: string;
-    start: number;
-    end: number;
-    groups: (string | null)[];
-}
-interface FormulaResult {
-    value: FormulaValue;
-    error?: string;
-    regex?: RegexInspection;
-}
-interface FormulaFunction {
-    name: string;
-    signature: string;
-    description: string;
-    min: number;
-    max: number;
-    result: FormulaType | "branch";
-    args: FormulaType[] | "any";
-}
-declare const FORMULA_FUNCTIONS: FormulaFunction[];
-declare class FormulaError extends Error {
-    from: number;
-    to: number;
-    constructor(message: string, from?: number, to?: number);
-}
-declare function compileFormula(source: string, fields: readonly {
-    name: string;
-    type: FieldType;
-}[], resolve?: (name: string) => FormulaPlan | undefined): FormulaPlan;
-/** Self-contained runtime: serialized into the browser worker, never user code. */
-declare function formulaRuntime(ast: FormulaNode, inputs: Record<string, FormulaValue>): FormulaResult;
-
-/** Reserved field token namespace. Query state stores IDs, never formula source. */
-declare const COMPUTED_PREFIX = "@computed/";
-declare const computedFieldName: (id: string) => string;
-declare const isComputedField: (name: string) => boolean;
-interface ComputedColumn {
-    id: string;
-    label: string;
-    expression: {
-        language: "qt-expr";
-        version: 1;
-        source: string;
-    };
-    /** Optimistic concurrency token issued by the store. */
-    revision: string;
-}
-type ComputedColumnDraft = Omit<ComputedColumn, "revision">;
-interface ComputedColumnStore {
-    /** Return the complete authorized catalogue for this dataset. */
-    list(dataset: string, signal?: AbortSignal): Promise<ComputedColumn[]>;
-    /** null creates a new ID; updates must match the current revision. */
-    save(dataset: string, column: ComputedColumnDraft, expectedRevision: string | null): Promise<ComputedColumn>;
-    /** Optional push invalidation, including changes from other sessions. */
-    subscribe?(dataset: string, listener: () => void): () => void;
-}
-declare function validateComputedColumn(input: unknown): ComputedColumn;
-declare function memoryComputedColumnStore(seed?: Record<string, ComputedColumn[]>): ComputedColumnStore;
-/** REST adapter. The implementing server owns authorization and DB persistence.
- * GET base?dataset=… → ComputedColumn[]
- * PUT base?dataset=… → {column, expectedRevision} → ComputedColumn
- * Return HTTP 409 for a stale revision. No formula evaluation happens there. */
-declare function httpComputedColumnStore(base: string, fetcher?: typeof fetch): ComputedColumnStore;
-interface ComputedCellError {
-    computedError: string;
-}
-declare function isComputedCellError(value: unknown): value is ComputedCellError;
-interface PreviewGroup {
-    inputs: FormulaValue[];
-    result: FormulaResult;
-    count: number;
-}
-interface ColumnPreview {
-    dependencies: string[];
-    groups: PreviewGroup[];
-    processed: number;
-    total: number;
-    nulls: number;
-    errors: number;
-}
-declare function groupPreview(dependencies: string[], inputs: Record<string, FormulaValue>[], results: FormulaResult[], total: number): ColumnPreview;
-
 /** Compile an explicitly identified editor into existing CNF predicates. */
 declare function createSetFilter(field: string, mode: SetFilterMode, values: string[], id: string): WhereTerm[];
 /** Remove presentation metadata at transport boundaries, including inner literals. */
@@ -632,4 +893,23 @@ declare function readSetFilter(where: WhereTerm[], index: number): {
 /** Canonicalize consumer-owned value aliases without disconnecting editor metadata. */
 declare function mapSetFilterValues(where: WhereTerm[], canonicalize: (field: string, value: string) => string): WhereTerm[];
 
-export { AGG_OPS_BY_TYPE, AGG_OPS_NEEDING_FIELD, type AggOp, type AggregateConfig, type AggregationBucket, type AggregationClause, type AggregationRequest, type AggregationResult, type AggregationResultEntry, type Align, type ApplyResult, type BackendField, COMPUTED_PREFIX, type CellRenderer, type ColumnPreview, type ComputedCellError, type ComputedColumn, type ComputedColumnDraft, type ComputedColumnStore, type DerivedField, type DistinctValuesQuery, type DistinctValuesResult, EMPTY_QUERY, FORMULA_FUNCTIONS, type FetchRowsResult, type FieldDef, type FieldSchema, type FieldSource, type FieldStats, type FieldType, type FilterConfig, type FilterOp, type FilterValues, type FormulaDiagnostic, FormulaError, type FormulaFunction, type FormulaNode, type FormulaPlan, type FormulaResult, type FormulaType, type FormulaValue, MAX_AGGREGATIONS, MAX_GROUP_BY_FIELDS, MAX_ORDER_BY_TERMS, MAX_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_TOKEN_LENGTH, MAX_SELECT_COLUMNS, MAX_WHERE_CLAUSES, NULLARY_OPS, OPS_BY_TYPE, type OpChoice, type OpPair, type OrGroup, type OrderByClause, type PreviewGroup, type QueryState, type RegexInspection, type RowId, type SavedQuery, type SelectColumn, type SelectConfig, type ServerQuery, type SetFilterMetadata, type SetFilterMode, type SortConfig, type StorageAdapter, type Transport, type WhereClause, type WhereTerm, aggOpAllowedForType, aggOpNeedsField, aggOpsForField, applyAggregations, applyQuery, coerceValue, compileFormula, computedFieldName, createSetFilter, decodeQuery, encodeQuery, filterValues, formulaRuntime, groupPreview, httpComputedColumnStore, indexFields, isComputedCellError, isComputedField, isFilterable, isGroupable, isMeasurable, isNegativePredicate, isOrGroup, isPushdownFilter, isSelectable, isSortable, loadSchema, localStorageAdapter, mapSetFilterValues, matchesClause, memoryComputedColumnStore, memoryStorageAdapter, negateClause, normalizeQueryState, opAllowedForType, opPairsForField, opsForField, predicatesOf, queriesEqual, readFieldValue, readSetFilter, selectedFields, stripSetFilter, toAggregationQuery, toServerQuery, validateComputedColumn };
+declare function percentile(sorted: number[], p: number): number | null;
+declare function boxSummary(values: number[], whiskers?: "minmax" | "tukey"): {
+    n: number;
+    min: number;
+    q1: number;
+    median: number;
+    q3: number;
+    max: number;
+    mean: number;
+    low: number;
+    high: number;
+    outliers: number[];
+    outlierCount: number;
+    whiskers: "minmax" | "tukey";
+    method: "exact-linear";
+} | null;
+declare function histogramEdges(values: number[], bins: number): number[];
+declare function histogramCounts(values: number[], edges: number[]): number[];
+
+export { AGG_OPS_BY_TYPE, AGG_OPS_NEEDING_FIELD, type AggOp, type AggregateConfig, type AggregationBucket, type AggregationClause, type AggregationRequest, type AggregationResult, type AggregationResultEntry, type Align, type ApplyResult, type BackendField, COMPUTED_PREFIX, type CellRenderer, type ColumnPreview, type ComputedCellError, type ComputedColumn, type ComputedColumnDraft, type ComputedColumnStore, type ComputedExecution, type ComputedFieldCapabilities, type DerivedField, type DistinctValuesQuery, type DistinctValuesResult, EMPTY_QUERY, FORMULA_FUNCTIONS, type FetchRowsResult, type FetchRowsResultV2, type FieldDef, type FieldSchema, type FieldSource, type FieldStats, type FieldType, type FilterConfig, type FilterOp, type FilterValues, type FormulaDiagnostic, FormulaError, type FormulaFunction, type FormulaNode, type FormulaPlan, type FormulaResult, type FormulaType, type FormulaValue, MAX_AGGREGATIONS, MAX_GROUP_BY_FIELDS, MAX_ORDER_BY_TERMS, MAX_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_TOKEN_LENGTH, MAX_RELATIVE_TIME_MS, MAX_SELECT_COLUMNS, MAX_WHERE_CLAUSES, type MetricAxisScale, type MetricBoxSummary, type MetricCapabilities, type MetricDiagnostic, type MetricDisplay, type MetricDistribution, type MetricDistributionResult, type MetricEvaluationOptions, type MetricKey, type MetricLayout, type MetricPlan, type MetricQuery, type MetricReductionOptions, type MetricScope, type MetricSort, type MetricValue, type MetricValueFormat, NULLARY_OPS, OPS_BY_TYPE, type OpChoice, type OpPair, type OrGroup, type OrderByClause, type PreviewGroup, type QueryEvaluationOptions, type QueryState, type RegexInspection, type RowComputedValues, type RowId, type SavedQuery, type SelectColumn, type SelectConfig, type ServerQuery, type ServerQueryV2, type SetFilterMetadata, type SetFilterMode, type SortConfig, type StorageAdapter, type Transport, type WhereClause, type WhereTerm, aggOpAllowedForType, aggOpNeedsField, aggOpsForField, applyAggregations, applyQuery, boxSummary, coerceValue, compareMetricValues, compileFormula, compileMetric, computedFieldName, createSetFilter, decodeQuery, encodeQuery, evaluateMetricReductions, evaluateMetrics, filterValues, formulaRuntime, groupPreview, hasRegex, histogramCounts, histogramEdges, httpComputedColumnStore, indexFields, isComputedCellError, isComputedField, isFilterable, isGroupable, isMeasurable, isNegativePredicate, isOrGroup, isPushdownFilter, isSelectable, isSortable, loadSchema, localStorageAdapter, mapSetFilterValues, matchesClause, memoryComputedColumnStore, memoryStorageAdapter, metricAggregatePlans, metricComputationKey, metricDependencies, metricExpression, metricPlans, negateClause, normalizeQueryState, opAllowedForType, opPairsForField, opsForField, parseRelativeDuration, percentile, predicatesOf, queriesEqual, readFieldValue, readSetFilter, reduceMetricValues, resolveFieldName, selectMetricShownRows, selectedFields, stripSetFilter, toAggregationQuery, toMetricQuery, toServerQuery, toServerQueryV2, validateComputedColumn, validateMetric };