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

package/README.md

@@ -3,6 +3,10 @@
 Framework-agnostic query state, schema contracts, filtering, sorting,
 aggregation, serialization, and transport/storage interfaces for query-table.
 
+Also exports object property view definitions, normalization/defaults, separate
+property storage adapters, and foreign-key relationship mapping contracts. See
+[object property views](../../docs/object-properties.md).
+
 ## Install
 
 ```bash
@@ -40,6 +44,17 @@ Query state is bounded whenever it crosses the library's URL, storage, or
 server-projection boundaries. SQL expressions remain trusted server-side schema
 configuration; request values are never SQL fragments.
 
+## Compact URLs and query snapshots
+
+`encodeQuery` chooses versioned JSON or raw-DEFLATE tokens, packs intact set
+filters once, and shares identical property layouts. `decodeQueryStrict` reports
+invalid/unsupported/oversized links; `decodeQuery` is the tolerant convenience
+decoder. `createQueryLinkService` keeps fitting views inline and oversized views
+in a bounded FIFO browser cache. Its explicit `durable`/`snapshot` calls promote
+immutable codes through an injected `QuerySnapshotStore`; ordinary `local` calls
+never write to the server. `httpQuerySnapshotStore` implements the host REST
+contract. See [URL state and saved-search links](../../docs/url-state-and-saved-search-design.md).
+
 Text filters include `matches_regex` / `not_matches_regex`. An order term may
 set `extract: { regex: "..." }` to compare the first capture group (or the whole
 match when there is no capture group); non-matches sort as nulls.
@@ -110,3 +125,10 @@ PostgreSQL numeric and also conservatively bounds SUM's absolute population sum.
 Do not claim identical acceptance, intermediate overflow, or bit-for-bit numeric
 parity; negotiate the backend profile and compare supported floating results
 with tolerances. The host must enforce the negotiated profile and execution budgets.
+
+## Cell presentation
+
+`FieldDef.display` accepts the serializable `CellDisplay` union for JSON, temporal,
+duration, numeric, text, and chip presentation. It is independent of `FieldType`
+and backend query capabilities. `loadSchema` validates display options, and
+codegen preserves them in frontend schemas. See the [cell display guide](../../docs/cell-displays.md).

package/dist/index.d.ts

@@ -1,3 +1,50 @@
+/** 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;
+}
+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";
 /** A cell renderer is resolved by name against a `RenderRegistry` (in
@@ -101,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> {
@@ -209,6 +263,17 @@ declare function formulaRuntime(ast: FormulaNode, inputs: Record<string, Formula
 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;
@@ -232,10 +297,18 @@ interface MetricDisplay {
     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;
@@ -315,6 +388,170 @@ interface MetricCapabilities {
     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";
@@ -402,6 +639,7 @@ type AggOp = "count" | "count_distinct" | "sum" | "avg" | "min" | "max";
  *  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;
@@ -424,9 +662,39 @@ interface AggregationClause {
     /** 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. */
@@ -468,6 +736,11 @@ declare function normalizeQueryState(input: unknown, fallback?: QueryState): Que
  *  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);
  *  falls back to toggling the `negated` flag when the op has no complement, or
@@ -534,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 {
@@ -608,6 +888,69 @@ 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;
@@ -659,6 +1002,8 @@ interface ColumnPreview {
 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;
@@ -681,18 +1026,8 @@ type RowComputedValues = Record<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;
-}
-
+/** Functions available only in aggregate expressions, separate from row formulas. */
+declare const METRIC_FUNCTIONS: FormulaFunction[];
 interface MetricPlan extends FormulaPlan {
     aggregates: Extract<FormulaNode, {
         kind: "call";
@@ -791,6 +1126,63 @@ interface FetchRowsResultV2<Row> {
  * 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[];
     /** Total matching rows before pagination (for "N of M" + paging bounds). */
@@ -823,6 +1215,8 @@ 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>;
@@ -847,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. */
@@ -858,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[]>;
@@ -868,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
@@ -912,4 +1312,44 @@ declare function boxSummary(values: number[], whiskers?: "minmax" | "tukey"): {
 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 };
+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 };