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

package/dist/index.d.ts

@@ -1,142 +1,49 @@
-/** 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[];
+/** Presentation hints only: field types still determine query/filter semantics. */
+interface JsonCellDisplay {
+    kind: "json";
+    /** auto accepts objects, JSON text and repeatedly encoded/escaped JSON text.
+     * value keeps a native string literal; json parses text once; escaped unwraps it. */
+    encoding?: "auto" | "value" | "json" | "escaped";
+    /** Maximum string-unwrapping passes, 1–8. Default 4. */
+    maxDecodeDepth?: number;
+    /** Inline preview length, 20–500 characters. Default 80. */
+    previewLength?: number;
+    /** Override initially expanded container levels, 0–8.
+     * The root starts open. By default, nested containers with up to 3 entries
+     * open; larger nested containers collapse. */
+    expandDepth?: number;
 }
-/** 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 CalendarDisplay = {
+    style?: "human" | "iso" | "custom";
+    pattern?: string;
+    /** UTC by default; an IANA timezone or local may be selected explicitly. */
+    timeZone?: string;
+    locale?: string;
+};
+type CellDisplay = JsonCellDisplay | ({
+    kind: "date" | "datetime";
+    sourceUnit?: "iso" | "epochSeconds" | "epochMilliseconds";
+} & CalendarDisplay) | ({
+    kind: "time";
+    sourceUnit?: "iso" | "epochSeconds" | "epochMilliseconds" | "secondsOfDay" | "millisecondsOfDay";
+} & CalendarDisplay) | {
+    kind: "duration";
+    sourceUnit?: "milliseconds" | "seconds" | "minutes" | "hours" | "days";
+    style?: "human" | "long" | "clock" | "custom";
+    pattern?: string;
+    decimals?: number;
+} | {
+    kind: "number" | "percent";
+    decimals?: number;
+    locale?: string;
+} | {
+    kind: "chip";
+    labels?: Record<string, string>;
+    tones?: Record<string, "neutral" | "success" | "warning" | "danger">;
+} | {
+    kind: "text";
+    truncate?: boolean;
+};
 
 type FieldType = "text" | "number" | "enum" | "datetime" | "bool" | "textarray";
 type Align = "left" | "right" | "center";
@@ -241,7 +148,14 @@ interface FieldDef<Row = any, V = unknown> {
     group?: string;
     alias?: string;
     aliases?: string[];
+    /** Declarative built-in presentation, independent of the query's field type.
+     * An explicit render function or registered render key takes precedence. */
+    display?: CellDisplay;
     render?: string | CellRenderer<Row, V>;
+    property?: PropertyFieldConfig;
+    /** Structured provenance for relationship discovery; never SQL text. */
+    origin?: FieldOrigin;
+    relationship?: FieldRelationship;
 }
 /** The frontend's loaded schema for one dataset. */
 interface FieldSchema<Row = any> {
@@ -257,27 +171,575 @@ 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: {
-    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>;
+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";
+/** Calendar grouping, currently executed over complete local populations. */
+interface MetricDateGrouping {
+    field: string;
+    interval: "hour" | "day" | "week" | "month" | "year";
+    /** IANA timezone identifier; omitted settings retain UTC behavior. */
+    timeZone?: string;
+    includeEmpty: boolean;
+    range: "query" | "observed" | "custom";
+    start?: string;
+    end?: string;
+}
+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";
+    /** Maximum displayed groups; does not change the computed result or ordering. */
+    maxGroups?: number;
+    /** Show the exact additive remainder in pie/donut (default true) or list (default false). */
+    showOther?: boolean;
+    list?: {
+        showBars?: boolean;
+        useGroupColors?: boolean;
+        showValues?: boolean;
+        /** Place the line bar beside the label (default) or underneath a wrapping label. */
+        barPosition?: "inline" | "below";
+        /** Maximum wrapped label lines for below bars (positive integer); omitted means unlimited. */
+        maxLabelLines?: number;
+    };
+    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;
+}
+
+/** Formats change presentation only; values retain their original types/units. */
+type PropertyFormat = MetricValueFormat | {
+    kind: "text" | "code" | "boolean" | "chips";
+} | JsonCellDisplay | Extract<CellDisplay, {
+    kind: "chip";
+}> | {
+    kind: "relative";
+    sourceUnit?: "iso" | "epochSeconds" | "epochMilliseconds";
+} | {
+    kind: "currency";
+    currency: string;
+    decimals?: number;
+};
+interface PropertyFieldConfig {
+    enabled?: boolean;
+    default?: boolean;
+    /** Detail-specific renderer. Table renderers remain unchanged. */
+    render?: string;
+    format?: PropertyFormat;
+}
+interface PropertySelection {
+    /** Instance identity allows the same field to appear with different formats. */
+    id: string;
+    field: string;
+    label?: string;
+    render?: string;
+    format?: PropertyFormat;
+}
+/** Independent of object identity and collection QueryState. [] shows no fields. */
+interface PropertyViewState {
+    version: 1;
+    properties: PropertySelection[];
+    /** Property label column width as a percentage, shared with the saved view. */
+    labelWidth?: number;
+}
+declare const MAX_PROPERTIES = 200;
+declare function normalizePropertyFormat(input: unknown): PropertyFormat | undefined;
+/** Strict envelope/version checks prevent interpreting future saved views as empty. */
+declare function normalizePropertyView(input: unknown): PropertyViewState;
+declare function createPropertyView<Row>(schema: FieldSchema<Row>, names?: string[]): PropertyViewState;
+interface FieldOrigin {
+    table: string;
+    column: string;
+}
+/** Backend discovery groups composite key columns in constraint order. */
+interface ForeignKey {
+    sourceTable: string;
+    sourceColumns: string[];
+    targetTable: string;
+    targetColumns: string[];
+}
+interface ObjectTypeDefinition {
+    name: string;
+    table: string;
+    keyFields: string[];
+}
+interface FieldRelationship {
+    objectType: string;
+    /** Target key field -> local catalogue field, including composite keys. */
+    key: Record<string, string>;
+}
+interface ObjectReference {
+    objectType: string;
+    key: Record<string, RowId>;
+}
+interface ResolvedObjectReference {
+    reference: ObjectReference;
+    label?: string;
+    href?: string;
+}
+/** Hosts resolve a batch through their authorized APIs, and own application routes. */
+interface RelationshipAdapter {
+    resolve(references: ObjectReference[], signal?: AbortSignal): Promise<ResolvedObjectReference[]>;
+}
+declare function objectReferenceKey(reference: ObjectReference): string;
+declare function readObjectReference<Row>(field: FieldDef<Row>, fields: FieldDef<Row>[], row: Row): ObjectReference | null;
+/** Only unambiguous, fully mapped constraints become links. Explicit metadata wins. */
+declare function discoverFieldRelationships<Row>(fields: FieldDef<Row>[], keys: ForeignKey[], types: ObjectTypeDefinition[]): FieldDef<Row>[];
+
+/** 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;
+}
+
+type GroupedRow = Record<string, unknown>;
+type Row = GroupedRow;
+type SummaryOp = AggOp | "row" | "formula";
+interface RepresentativeOrder {
+    field: string;
+    dir: "asc" | "desc";
+    nulls: "first" | "last";
+}
+interface RepresentativeRow {
+    orderBy: RepresentativeOrder[];
+}
+interface SummaryColumn {
+    id: string;
+    op: SummaryOp;
+    field?: string;
+    expression?: string;
+    label?: string;
+}
+interface GroupingView {
+    version: 2;
+    mode: "rows" | "groups";
+    keys: string[];
+    summaries: SummaryColumn[];
+    representative: RepresentativeRow | null;
+    input: QueryState;
+    result: QueryState;
+}
+/** One grouping stage over the complete source population. QueryState.where is
+ * HAVING in this mode; source.where is the pre-group WHERE. The source snapshot
+ * also restores the record layout, paging, metrics and item details on exit. */
+interface GroupingDefinition {
+    keys: string[];
+    summaries: SummaryColumn[];
+    representative: RepresentativeRow | null;
+    diagnostics?: string[];
+}
+interface GroupingState extends GroupingDefinition {
+    source: QueryState;
+}
+declare const GROUP_ID_FIELD = "__qt_group_id__";
+declare const MAX_REPRESENTATIVE_SORTS = 8;
+declare const MAX_SUMMARY_COLUMNS = 64;
+declare const MAX_RESULT_GROUPS = 10000;
+declare function withoutGrouping(query: QueryState): QueryState;
+declare const OP_LABEL: Record<SummaryOp, string>;
+/** Bind aggregation helpers to this instance's source catalogue. */
+declare function createGroupingModel<InputRow>(inputSchema: FieldSchema<InputRow>): {
+    inputSchema: FieldSchema<InputRow>;
+    sourceField: (name: string) => FieldDef<InputRow, unknown> | undefined;
+    groupableFields: FieldDef<InputRow, unknown>[];
+    summaryFields: FieldDef<InputRow, unknown>[];
+    representativeFields: FieldDef<InputRow, unknown>[];
+    representativeLabel: (rule: RepresentativeRow) => string;
+    allowedOps: (field?: string) => SummaryOp[];
+    summaryExpression: (column: SummaryColumn) => string;
+    summaryProblem: (column: SummaryColumn) => string | null;
+    summaryLabel: (column: SummaryColumn) => string;
+    resultSchema: (keys: string[], summaries: SummaryColumn[]) => FieldSchema<Row>;
+    groupRows: (rows: InputRow[], schema: FieldSchema<InputRow>, keys: string[], summaries: SummaryColumn[], rule?: RepresentativeRow | null) => Row[];
+    filteredInput: (rows: InputRow[], query: QueryState, schema: FieldSchema<InputRow>, options?: QueryEvaluationOptions) => InputRow[];
+    reconcileRepresentative: (query: QueryState, summaries: SummaryColumn[], schema: FieldSchema<Row>, remove: boolean) => QueryState;
+    validate: (definition: GroupingDefinition) => void;
+};
+type GroupingModel<Row> = ReturnType<typeof createGroupingModel<Row>>;
+/** Evaluate the WHERE and grouping stages once; callers apply HAVING and paging
+ * with the resulting schema and withoutGrouping(query). Never accepts a page
+ * fetched by a transport as a complete source dataset. */
+declare function prepareGrouping<Row>(rows: Row[], schema: FieldSchema<Row>, grouping: GroupingState, options?: QueryEvaluationOptions): {
+    inputs: Row[];
+    rows: GroupedRow[];
+    schema: FieldSchema<GroupedRow>;
+};
+
+/** 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 {
+    dateGrouping?: MetricDateGrouping;
+    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;
+}
+/** Detail affordances are presentation state, never backend SELECT fields. */
+type ItemPropertyMode = "hover" | "modal" | "expand";
+type ItemDetailMode = ItemPropertyMode | "page";
+interface ItemPageOptions {
+    /** Empty uses the current page with the item modal and query state. */
+    urlTemplate: string;
+    target: "_blank" | "_self";
+}
+/** Reserved presentation column; never sent to a data source. */
+declare const ITEM_DETAILS_COLUMN = "__qt_item_details__";
+interface ItemDetailsState {
+    modes: ItemDetailMode[];
+    /** A self-contained view travels with shared links; saved-view IDs are device-local. */
+    view?: PropertyViewState;
+    /** Independent layouts for each modality. Legacy view is the fallback. */
+    views?: Partial<Record<ItemPropertyMode, PropertyViewState>>;
+    page?: ItemPageOptions;
+    active?: {
+        id: RowId;
+        mode: "modal" | "expand";
+    };
+}
+interface QueryState {
+    /** Optional row-producing stage. `grouping.source` is the original record
+     * query (its WHERE runs first). This query selects/filters/sorts the groups;
+     * its `where` therefore represents HAVING. Only one stage is supported. */
+    grouping?: GroupingState;
+    itemDetails?: ItemDetailsState;
+    /** Ordered SELECT list + per-column widths. Empty = the schema's default columns. */
+    select: SelectColumn[];
+    /** Refit columns to each viewer's table viewport after loading. Manual width
+     *  changes clear this view preference; omitted/false uses stored widths. */
+    fitToScreen?: boolean;
+    /** 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;
+
+/** Literal templates only: substitution never evaluates code or nested paths. */
+declare function itemPageFields(template: string): string[];
+declare function validateItemPageTemplate<Row>(template: string, schema: FieldSchema<Row>): string | null;
+declare function renderItemPageTemplate<Row>(template: string, schema: FieldSchema<Row>, row: Row, id: RowId | null, query: string): string | null;
 
 /** 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 +782,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;
@@ -345,11 +807,18 @@ declare function isMeasurable(field: FieldDef): boolean;
  *  default off, but `aggregate.groupable: true` opts any backend field in. */
 declare function isGroupable(field: FieldDef): boolean;
 
-/** QueryState → base64url token (omitting defaults). All-default query → "". */
+declare const MAX_QUERY_STATE_BYTES: number;
+declare class QueryDecodeError extends Error {
+    readonly code: "invalid" | "too_large" | "unsupported_version";
+    constructor(code: "invalid" | "too_large" | "unsupported_version", message: string);
+}
+/** v2 JSON or raw-DEFLATE UTF-8, whichever produces the shorter URL token. */
 declare function encodeQuery(q: QueryState): string;
 /** base64url token → QueryState. Tolerant: bad input and legacy shapes both
  *  normalize to a valid QueryState (never throws). */
 declare function decodeQuery(token: string): QueryState;
+/** Navigation uses this decoder so corrupt links cannot silently run defaults. */
+declare function decodeQueryStrict(token: string): QueryState;
 /** The backend request derived from a QueryState + its schema. Mirrors the Go
  *  `WireQuery`. View-only state (column widths) is intentionally absent. */
 interface ServerQuery {
@@ -371,22 +840,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 +888,200 @@ interface AggregationResult {
  *  unknown field are dropped — the server has no SQL for them. */
 declare function toAggregationQuery<Row>(q: QueryState, schema: FieldSchema<Row>): AggregationRequest;
 
+interface QuerySnapshot {
+    version: 1;
+    code: string;
+    token: string;
+    createdAt: number;
+}
+/** The host owns authenticated, durable storage. Save is immutable/idempotent
+ * by code: an existing code may never be assigned a different token. */
+interface QuerySnapshotStore {
+    save(key: string, snapshot: QuerySnapshot, signal?: AbortSignal): Promise<QuerySnapshot>;
+    resolve(key: string, code: string, signal?: AbortSignal): Promise<QuerySnapshot | null>;
+}
+interface QuerySnapshotCache {
+    get(key: string, code: string): QuerySnapshot | null;
+    find(key: string, token: string): QuerySnapshot | null;
+    put(key: string, snapshot: QuerySnapshot): void;
+    isDurable?(key: string, code: string): boolean;
+    markDurable?(key: string, code: string): void;
+}
+interface QueryLink {
+    url: string;
+    kind: "inline" | "local" | "durable";
+    bytes: number;
+    snapshotCode?: string;
+}
+interface QueryLinkOptions {
+    /** Complete URL budget, including host parameters and fragment. Default 2000. */
+    maxUrlBytes?: number;
+    cache?: QuerySnapshotCache;
+}
+declare function validateQuerySnapshot(input: unknown): QuerySnapshot;
+/** FIFO entries are scoped by dataset. One bounded envelope makes each write
+ * atomic; the new entry is protected from eviction and stored before URL use.
+ * Browser profiles, origins, and devices do not share these entries. */
+declare function localQuerySnapshotCache(options?: {
+    storage?: Pick<Storage, "getItem" | "setItem">;
+    storageKey?: string;
+    maxEntries?: number;
+    maxBytes?: number;
+}): QuerySnapshotCache;
+declare function memoryQuerySnapshotCache(): QuerySnapshotCache;
+type QuerySnapshotHttpErrorCode = "quota" | "forbidden" | "conflict" | "unavailable" | "storage" | "http";
+/** HTTP failures retain structured information for host error formatting. The
+ * message is plain text suitable for displaying in the Save/Share UI. */
+declare class QuerySnapshotHttpError extends Error {
+    readonly status: number;
+    readonly code: QuerySnapshotHttpErrorCode;
+    readonly detail?: string | undefined;
+    readonly serverCode?: string | undefined;
+    readonly name = "QuerySnapshotHttpError";
+    constructor(status: number, code: QuerySnapshotHttpErrorCode, message: string, detail?: string | undefined, serverCode?: string | undefined);
+}
+declare function httpQuerySnapshotStore(base: string, fetcher?: typeof fetch): QuerySnapshotStore;
+interface QueryLinkService {
+    local(query: QueryState, baseUrl: string, parameter?: string): QueryLink;
+    durable(query: QueryState, baseUrl: string, parameter?: string): Promise<QueryLink>;
+    snapshot(query: QueryState): Promise<QuerySnapshot | null>;
+    resolve(url: string, parameter?: string, signal?: AbortSignal): Promise<QueryState | null>;
+}
+/** Local URL synchronization never writes to the server. Only explicit
+ * snapshot/durable calls (Save/Share/Bookmark) promote state to the host store. */
+declare function createQueryLinkService(key: string, store?: QuerySnapshotStore, options?: QueryLinkOptions): QueryLinkService;
+
+/** 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 {
+    /** Host-approved canonical predicates; omitted retains the closed default. */
+    filter?: boolean;
+    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;
+    };
+}>;
+
+/** Functions available only in aggregate expressions, separate from row formulas. */
+declare const METRIC_FUNCTIONS: FormulaFunction[];
+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 +1089,99 @@ 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 QueryCapabilitiesV3 {
+    version: 3;
+    groupedRows: boolean;
+    calendarGrouping: boolean;
+    computedSourceFilters: boolean;
+    regex: boolean;
+    regexSourceFilters?: boolean;
+    regexAggregateExpressions?: boolean;
+    maxRows: number;
+    maxGroups: number;
+    maxPopulation: number;
+    profile: string;
+}
+interface QueryRequestV3 {
+    version: 3;
+    profile: string;
+    now: number;
+    expectedRevisions: Record<string, string>;
+    planToken?: string;
+    snapshot?: string;
+    source: ServerQuery;
+    result: ServerQuery;
+    grouping?: GroupingDefinition;
+    rows: boolean;
+    metrics: AggregationClause[];
+    diagnostics: string[];
+}
+interface QueryResultV3 {
+    version: 3;
+    now: number;
+    sourceTotal: number;
+    rows: Record<string, unknown>[];
+    total: number;
+    schema: {
+        name: string;
+        idField: string;
+        fields: {
+            name: string;
+            type: string;
+        }[];
+    };
+    metrics: AggregationResult["metrics"];
+    execution: ComputedExecution;
+}
+/** The handshake supplies authority, including capabilities for computed keys
+ * absent from the base schema. Labels may be supplied by the editable catalogue. */
+declare function sourceExecutionSchema<Row>(schema: FieldSchema<Row>, execution?: ComputedExecution, catalogue?: readonly {
+    id: string;
+    label: string;
+    revision: string;
+}[]): FieldSchema<Row>;
+declare function toQueryRequestV3<Row>(query: QueryState, baseSchema: FieldSchema<Row>, capabilities: QueryCapabilitiesV3, execution?: ComputedExecution, options?: {
+    now?: number;
+    rows?: boolean;
+}): QueryRequestV3;
+declare function validateQueryResultV3(result: QueryResultV3, request: QueryRequestV3, schema: FieldSchema): void;
 
 interface FetchRowsResult<Row> {
     rows: Row[];
@@ -452,6 +1215,11 @@ interface FieldStats {
     max?: string | number;
 }
 interface Transport<Row = any> {
+    queryCapabilities?: QueryCapabilitiesV3;
+    fetchQueryV3?(query: QueryRequestV3, signal?: AbortSignal): Promise<QueryResultV3>;
+    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>>;
@@ -473,6 +1241,7 @@ interface Transport<Row = any> {
     fetchFieldStats?(fields: string[], signal?: AbortSignal): Promise<Record<string, FieldStats>>;
 }
 interface SavedQuery {
+    snapshotCode?: string;
     id: string;
     name: string;
     /** Epoch millis; injected by the caller so core stays deterministic/testable. */
@@ -484,6 +1253,8 @@ interface SavedQuery {
  *  on one origin don't collide. Async to allow backend implementations; the
  *  browser adapters can still resolve synchronously. */
 interface StorageAdapter {
+    /** Optional authenticated server store. Ordinary URL sync never calls it. */
+    snapshots?: QuerySnapshotStore;
     loadLast(key: string): Promise<QueryState | null>;
     saveLast(key: string, query: QueryState): Promise<void>;
     listSaved(key: string): Promise<SavedQuery[]>;
@@ -494,7 +1265,10 @@ interface StorageAdapter {
     setDefaultSaved?(key: string, id: string | null): Promise<void>;
     /** Persist a named query snapshot. Rejects when a saved query with the same
      *  name already exists in the key namespace. */
-    saveNamed(key: string, name: string, query: QueryState, savedAt: number): Promise<SavedQuery>;
+    saveNamed(key: string, name: string, query: QueryState, savedAt: number, snapshotCode?: string): Promise<SavedQuery>;
+    /** Atomically replace a named query's state, preserving its id, name and default
+     * selection. On rejection the original entry must remain unchanged. */
+    updateNamed?(key: string, id: string, query: QueryState, savedAt: number, snapshotCode?: string): Promise<SavedQuery>;
     deleteSaved(key: string, id: string): Promise<void>;
 }
 /** In-memory persistence used by default by the React package. It supports the
@@ -506,119 +1280,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 +1293,63 @@ 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[];
+
+declare const METRIC_DATE_INTERVALS: readonly ["hour", "day", "week", "month", "year"];
+/** Strict calendar input; timestamps require an explicit offset. */
+declare function metricDateTime(value: MetricValue, timeZone?: string): number;
+declare function metricDateFloor(time: number, interval: MetricDateGrouping["interval"], timeZone?: string): number;
+declare function metricDateNext(time: number, interval: MetricDateGrouping["interval"], timeZone?: string): number;
+declare function validateDateGrouping(config: MetricDateGrouping): void;
+/** Only conjunctive bounds prove a domain; OR alternatives are not bounds. */
+declare function metricDateRange(config: MetricDateGrouping, query: QueryState, observed: readonly number[], now: number, canonical: (field: string) => string): [number, number] | undefined;
+
+interface SavedPropertyView {
+    id: string;
+    name: string;
+    savedAt: number;
+    view: PropertyViewState;
+}
+interface PropertyViewStorage {
+    loadLast(objectType: string): Promise<PropertyViewState | null>;
+    saveLast(objectType: string, view: PropertyViewState): Promise<void>;
+    listSaved(objectType: string): Promise<SavedPropertyView[]>;
+    saveNamed(objectType: string, name: string, view: PropertyViewState, savedAt: number): Promise<SavedPropertyView>;
+    deleteSaved(objectType: string, id: string): Promise<void>;
+    loadDefaultSaved(objectType: string): Promise<SavedPropertyView | null>;
+    setDefaultSaved(objectType: string, id: string | null): Promise<void>;
+}
+/** The JSON-backed factory also supports application-owned synchronous preferences. */
+declare function jsonPropertyViewStorage(read: (key: string) => string | null, write: (key: string, value: string) => void): PropertyViewStorage;
+declare function memoryPropertyViewStorage(): PropertyViewStorage;
+/** Durable browser persistence is explicitly opt-in, independently of table storage. */
+declare function localPropertyViewStorage(): PropertyViewStorage;
+
+interface SourceDependencies {
+    fields: string[];
+    baseFields: string[];
+    identity: string;
+    paths: Record<string, string>;
+}
+/** Source inputs are distinct from result/HAVING aliases. Includes hidden ROW
+ * inputs and transitive computed/derived dependencies, even when not selected. */
+declare function sourceDependencies<Row>(query: QueryState, schema: FieldSchema<Row>, resolveComputed?: (name: string) => FormulaPlan | undefined): SourceDependencies;
+
+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 CellDisplay, 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 FieldOrigin, type FieldRelationship, type FieldSchema, type FieldSource, type FieldStats, type FieldType, type FilterConfig, type FilterOp, type FilterValues, type ForeignKey, type FormulaDiagnostic, FormulaError, type FormulaFunction, type FormulaNode, type FormulaPlan, type FormulaResult, type FormulaType, type FormulaValue, GROUP_ID_FIELD, type GroupedRow, type GroupingDefinition, type GroupingModel, type GroupingState, type GroupingView, ITEM_DETAILS_COLUMN, type ItemDetailMode, type ItemDetailsState, type ItemPageOptions, type ItemPropertyMode, type JsonCellDisplay, MAX_AGGREGATIONS, MAX_GROUP_BY_FIELDS, MAX_ORDER_BY_TERMS, MAX_PROPERTIES, MAX_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_STATE_BYTES, MAX_QUERY_TOKEN_LENGTH, MAX_RELATIVE_TIME_MS, MAX_REPRESENTATIVE_SORTS, MAX_RESULT_GROUPS, MAX_SELECT_COLUMNS, MAX_SUMMARY_COLUMNS, MAX_WHERE_CLAUSES, METRIC_DATE_INTERVALS, METRIC_FUNCTIONS, type MetricAxisScale, type MetricBoxSummary, type MetricCapabilities, type MetricDateGrouping, 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, OP_LABEL, type ObjectReference, type ObjectTypeDefinition, type OpChoice, type OpPair, type OrGroup, type OrderByClause, type PreviewGroup, type PropertyFieldConfig, type PropertyFormat, type PropertySelection, type PropertyViewState, type PropertyViewStorage, type QueryCapabilitiesV3, QueryDecodeError, type QueryEvaluationOptions, type QueryLink, type QueryLinkOptions, type QueryLinkService, type QueryRequestV3, type QueryResultV3, type QuerySnapshot, type QuerySnapshotCache, QuerySnapshotHttpError, type QuerySnapshotHttpErrorCode, type QuerySnapshotStore, type QueryState, type RegexInspection, type RelationshipAdapter, type RepresentativeOrder, type RepresentativeRow, type ResolvedObjectReference, type RowComputedValues, type RowId, type SavedPropertyView, type SavedQuery, type SelectColumn, type SelectConfig, type ServerQuery, type ServerQueryV2, type SetFilterMetadata, type SetFilterMode, type SortConfig, type SourceDependencies, type StorageAdapter, type SummaryColumn, type SummaryOp, type Transport, type WhereClause, type WhereTerm, aggOpAllowedForType, aggOpNeedsField, aggOpsForField, applyAggregations, applyQuery, boxSummary, coerceValue, compareMetricValues, compileFormula, compileMetric, computedFieldName, createGroupingModel, createPropertyView, createQueryLinkService, createSetFilter, decodeQuery, decodeQueryStrict, discoverFieldRelationships, encodeQuery, evaluateMetricReductions, evaluateMetrics, filterValues, formulaRuntime, groupPreview, hasRegex, histogramCounts, histogramEdges, httpComputedColumnStore, httpQuerySnapshotStore, indexFields, isComputedCellError, isComputedField, isFilterable, isGroupable, isMeasurable, isNegativePredicate, isOrGroup, isPushdownFilter, isSelectable, isSortable, itemPageFields, jsonPropertyViewStorage, loadSchema, localPropertyViewStorage, localQuerySnapshotCache, localStorageAdapter, mapSetFilterValues, matchesClause, memoryComputedColumnStore, memoryPropertyViewStorage, memoryQuerySnapshotCache, memoryStorageAdapter, metricAggregatePlans, metricComputationKey, metricDateFloor, metricDateNext, metricDateRange, metricDateTime, metricDependencies, metricExpression, metricPlans, negateClause, normalizePropertyFormat, normalizePropertyView, normalizeQueryState, objectReferenceKey, opAllowedForType, opPairsForField, opsForField, parseRelativeDuration, percentile, predicatesOf, prepareGrouping, queriesEqual, readFieldValue, readObjectReference, readSetFilter, reduceMetricValues, renderItemPageTemplate, resolveFieldName, selectMetricShownRows, selectedFields, sourceDependencies, sourceExecutionSchema, stripSetFilter, toAggregationQuery, toMetricQuery, toQueryRequestV3, toServerQuery, toServerQueryV2, validateComputedColumn, validateDateGrouping, validateItemPageTemplate, validateMetric, validateQueryResultV3, validateQuerySnapshot, withoutGrouping };