@katerai/sdk 0.9.0 → 0.11.0

package/resources/v1/compiler/compiler.d.ts

@@ -0,0 +1,2291 @@
+import { APIResource } from "../../../core/resource.js";
+import * as CompilerAPI from "./compiler.js";
+import * as CacheAPI from "./cache.js";
+import { Cache } from "./cache.js";
+import * as CombinationAPI from "./combination.js";
+import { Combination as CombinationAPICombination, CombinationPreviewParams, CombinationPreviewResponse } from "./combination.js";
+import * as ManifestAPI from "./manifest.js";
+import { ManifestRegenerateAndCreatePrParams, ManifestRegenerateAndCreatePrResponse } from "./manifest.js";
+import { APIPromise } from "../../../core/api-promise.js";
+import { RequestOptions } from "../../../internal/request-options.js";
+export declare class Compiler extends APIResource {
+    cache: CacheAPI.Cache;
+    combination: CombinationAPI.Combination;
+    manifest: ManifestAPI.Manifest;
+    /**
+     * Compile a resolved query to SQL.
+     *
+     * Takes a previously resolved query and generates the final SQL statement for the
+     * target dialect.
+     *
+     * RLS: Filtered to current client (ClientRLSDB).
+     */
+    compile(params: CompilerCompileParams, options?: RequestOptions): APIPromise<CompilerCompileResponse>;
+    /**
+     * Compile a dashboard YAML file into fully resolved widget data.
+     *
+     * Reads a dashboard YAML from the client repo, resolves all data slots, executes
+     * queries, applies filters, and returns renderable widget data.
+     *
+     * RLS: Filtered to current client (ClientRLSDB).
+     */
+    compileDashboard(params: CompilerCompileDashboardParams, options?: RequestOptions): APIPromise<CompilerCompileDashboardResponse>;
+    /**
+     * Enumerate every valid query configuration for a connection.
+     *
+     * Generates all valid combinations of optional dimensions, measures, calculations,
+     * filters, and variable values, constrained by widget category rules.
+     *
+     * RLS: Filtered to current client (ClientRLSDB).
+     */
+    enumerate(params: CompilerEnumerateParams, options?: RequestOptions): APIPromise<CompilerEnumerateResponse>;
+    /**
+     * Execute a query with transparent caching.
+     *
+     * Compiles the resolved query to SQL, checks the cache for existing results,
+     * executes against the warehouse on cache miss, and stores the result for future
+     * requests. Cache failures are invisible to the caller.
+     *
+     * RLS: Filtered to current client (ClientRLSDB).
+     */
+    execute(params: CompilerExecuteParams, options?: RequestOptions): APIPromise<CompilerExecuteResponse>;
+    /**
+     * Resolve a query template with user-selected parameters.
+     *
+     * Takes a query reference and variable selections, returns the fully resolved
+     * query object ready for compilation.
+     *
+     * RLS: Filtered to current client (ClientRLSDB).
+     */
+    resolve(params: CompilerResolveParams, options?: RequestOptions): APIPromise<CompilerResolveResponse>;
+    /**
+     * Validate a schema file set against a connection.
+     *
+     * Checks all views, queries, and related schemas for correctness and returns any
+     * errors or warnings found.
+     *
+     * RLS: Filtered to current client (ClientRLSDB).
+     */
+    validate(params: CompilerValidateParams, options?: RequestOptions): APIPromise<CompilerValidateResponse>;
+}
+/**
+ * Chart configuration with variable references
+ */
+export interface ChartConfig {
+    /**
+     * Field or variable reference for color grouping
+     */
+    color_by?: string | null;
+    /**
+     * Comparison mode for single_value widgets (e.g., previous_period, target)
+     */
+    comparison?: 'previous_period' | 'target' | null;
+    /**
+     * Field or variable reference for size
+     */
+    size?: string | null;
+    /**
+     * Field or variable reference for stacking
+     */
+    stack_by?: string | null;
+    /**
+     * Target value for comparison: target mode
+     */
+    target_value?: string | null;
+    /**
+     * Field or variable reference for x-axis
+     */
+    x_axis?: string | null;
+    /**
+     * Field or variable reference for y-axis
+     */
+    y_axis?: string | null;
+}
+/**
+ * A single compiler validation or compilation error.
+ */
+export interface CompilerErrorItem {
+    /**
+     * Machine-readable error code
+     */
+    code: string;
+    /**
+     * Human-readable error description
+     */
+    message: string;
+    /**
+     * Column number in the source file
+     */
+    column?: number | null;
+    /**
+     * Source file path where the error occurred
+     */
+    file?: string | null;
+    /**
+     * Line number in the source file
+     */
+    line?: number | null;
+    /**
+     * Reference to the source element (e.g. view or query name)
+     */
+    ref?: string | null;
+    /**
+     * Suggested fix for this error
+     */
+    remediation?: string | null;
+}
+/**
+ * An inline field definition for dimensions/measures/calculations
+ */
+export interface InlineField {
+    /**
+     * Unique identifier for this inline field
+     */
+    kater_id: string;
+    /**
+     * Name of the inline field
+     */
+    name: string;
+    /**
+     * SQL expression for the field
+     */
+    sql: string;
+    /**
+     * Human-readable label
+     */
+    label?: string | null;
+}
+/**
+ * Compilation manifest with all named objects.
+ */
+export interface Manifest {
+    generated_at: string;
+    objects: {
+        [key: string]: ManifestEntry;
+    };
+    schema_version?: string;
+}
+/**
+ * A single object entry in the manifest.
+ */
+export interface ManifestEntry {
+    kater_id: string;
+    name: string;
+    type: string;
+    label?: string | null;
+    parent_id?: string | null;
+    source_file?: string | null;
+}
+/**
+ * A reference with optional label override
+ */
+export interface RefWithLabel {
+    /**
+     * Reference using ref(), var(), or expr() syntax
+     */
+    ref: string;
+    /**
+     * Optional label override for this reference
+     */
+    label?: string | null;
+}
+/**
+ * A subquery condition for EXISTS/NOT EXISTS filters
+ */
+export interface SubqueryCondition {
+    /**
+     * Reference to the source view/table for the subquery
+     */
+    from: string;
+    /**
+     * WHERE conditions for the subquery
+     */
+    where: Array<string>;
+}
+/**
+ * Response model for SQL compilation.
+ */
+export interface CompilerCompileResponse {
+    /**
+     * SQL dialect used (e.g. 'snowflake')
+     */
+    dialect: string;
+    /**
+     * Whether compilation succeeded
+     */
+    success: boolean;
+    /**
+     * Maps UUID column aliases to human-readable names and types
+     */
+    column_map?: Array<CompilerCompileResponse.ColumnMap>;
+    /**
+     * Compilation errors
+     */
+    errors?: Array<CompilerErrorItem>;
+    /**
+     * Compilation manifest with all named objects.
+     */
+    manifest?: Manifest | null;
+    /**
+     * Compilation metadata from the compiler.
+     */
+    metadata?: CompilerCompileResponse.Metadata | null;
+    /**
+     * Write-back request ID. Non-null when files were dispatched to CLI via WebSocket.
+     */
+    request_id?: string | null;
+    /**
+     * Generated SQL statement
+     */
+    sql?: string | null;
+}
+export declare namespace CompilerCompileResponse {
+    /**
+     * Maps a UUID column alias to its human-readable name and type.
+     */
+    interface ColumnMap {
+        /**
+         * Field type: dimension, measure, or calculation
+         */
+        field_type: string;
+        /**
+         * UUID string used as SQL column alias
+         */
+        kater_id: string;
+        /**
+         * Human-readable column name
+         */
+        name: string;
+        /**
+         * Aggregation type for measures: sum, count, min, max, avg, unknown. None for
+         * non-measures.
+         */
+        aggregation?: string | null;
+        /**
+         * Display label
+         */
+        label?: string | null;
+    }
+    /**
+     * Compilation metadata from the compiler.
+     */
+    interface Metadata {
+        /**
+         * SQL dialect used (e.g. 'snowflake')
+         */
+        dialect: string;
+        /**
+         * Reference to the compiled query
+         */
+        query_ref: string;
+        /**
+         * Dimension names used in compilation
+         */
+        dimensions_used?: Array<string>;
+        /**
+         * Filter names used in compilation
+         */
+        filters_used?: Array<string>;
+        /**
+         * Measure names used in compilation
+         */
+        measures_used?: Array<string>;
+        /**
+         * View names used in compilation
+         */
+        views_used?: Array<string>;
+    }
+}
+/**
+ * Response from dashboard compilation — fully resolved dashboard.
+ */
+export interface CompilerCompileDashboardResponse {
+    /**
+     * Dashboard context for widgets
+     */
+    context: CompilerCompileDashboardResponse.Context;
+    /**
+     * Dashboard metadata
+     */
+    dashboard: CompilerCompileDashboardResponse.Dashboard;
+    /**
+     * Dashboard-level compilation errors
+     */
+    errors?: Array<CompilerErrorItem>;
+    /**
+     * Resolved filter definitions with current values
+     */
+    filters?: Array<CompilerCompileDashboardResponse.Filter>;
+    /**
+     * Fully resolved widgets with data + config
+     */
+    widgets?: Array<CompilerCompileDashboardResponse.Widget>;
+}
+export declare namespace CompilerCompileDashboardResponse {
+    /**
+     * Dashboard context for widgets
+     */
+    interface Context {
+        /**
+         * Active filter values: {name: {value, label}}
+         */
+        filters?: {
+            [key: string]: {
+                [key: string]: unknown;
+            };
+        } | null;
+        /**
+         * Active timeframe: {label, start, end}
+         */
+        timeframe?: {
+            [key: string]: string;
+        } | null;
+        /**
+         * Dashboard topic: {label, time_dimension}
+         */
+        topic?: {
+            [key: string]: string;
+        } | null;
+    }
+    /**
+     * Dashboard metadata
+     */
+    interface Dashboard {
+        /**
+         * Dashboard name
+         */
+        name: string;
+        /**
+         * Dashboard description
+         */
+        description?: string | null;
+        /**
+         * Dashboard kater_id
+         */
+        kater_id?: string | null;
+        /**
+         * Dashboard display label
+         */
+        label?: string | null;
+        /**
+         * Dashboard topic reference
+         */
+        topic?: string | null;
+    }
+    /**
+     * A resolved dashboard filter with current value and presets.
+     */
+    interface Filter {
+        /**
+         * Filter type: date_range, multi_select, select
+         */
+        filter_type: string;
+        /**
+         * Filter name
+         */
+        name: string;
+        /**
+         * Whether null (All) is allowed
+         */
+        allow_null?: boolean;
+        /**
+         * Whether filter auto-applies to queries
+         */
+        auto_apply?: boolean;
+        /**
+         * Current filter value
+         */
+        current_value?: string | Array<string> | null;
+        /**
+         * Default value specification
+         */
+        default?: {
+            [key: string]: string;
+        } | null;
+        /**
+         * Field reference for data-driven filters
+         */
+        field?: string | null;
+        /**
+         * Label for null/All option
+         */
+        null_label?: string | null;
+        /**
+         * Available presets
+         */
+        presets?: Array<{
+            [key: string]: string;
+        }> | null;
+    }
+    /**
+     * A fully resolved widget ready for rendering.
+     */
+    interface Widget {
+        /**
+         * Column metadata (single or multi-query)
+         */
+        column_map: Array<Widget.UnionMember0> | Array<Array<Widget.UnionMember1>>;
+        /**
+         * Fully resolved WidgetConfig
+         */
+        config: {
+            [key: string]: unknown;
+        };
+        /**
+         * Query result data (single or multi-query)
+         */
+        data: Array<{
+            [key: string]: unknown;
+        }> | Array<Array<{
+            [key: string]: unknown;
+        }>>;
+        /**
+         * Grid position
+         */
+        grid: Widget.Grid;
+        /**
+         * Widget unique identifier
+         */
+        kater_id: string;
+        /**
+         * Widget name
+         */
+        name: string;
+        /**
+         * Display mode for multi-query: 'tabs' or 'grid'
+         */
+        display_mode?: string | null;
+        /**
+         * Per-widget compilation errors
+         */
+        errors?: Array<CompilerAPI.CompilerErrorItem>;
+        /**
+         * Per-slot configs for multi-query containers
+         */
+        slot_configs?: Array<{
+            [key: string]: unknown;
+        }> | null;
+        /**
+         * Resolved widget type
+         */
+        widget_type?: string | null;
+    }
+    namespace Widget {
+        /**
+         * Maps a UUID column alias to its human-readable name and type.
+         */
+        interface UnionMember0 {
+            /**
+             * Field type: dimension, measure, or calculation
+             */
+            field_type: string;
+            /**
+             * UUID string used as SQL column alias
+             */
+            kater_id: string;
+            /**
+             * Human-readable column name
+             */
+            name: string;
+            /**
+             * Aggregation type for measures: sum, count, min, max, avg, unknown. None for
+             * non-measures.
+             */
+            aggregation?: string | null;
+            /**
+             * Display label
+             */
+            label?: string | null;
+        }
+        /**
+         * Maps a UUID column alias to its human-readable name and type.
+         */
+        interface UnionMember1 {
+            /**
+             * Field type: dimension, measure, or calculation
+             */
+            field_type: string;
+            /**
+             * UUID string used as SQL column alias
+             */
+            kater_id: string;
+            /**
+             * Human-readable column name
+             */
+            name: string;
+            /**
+             * Aggregation type for measures: sum, count, min, max, avg, unknown. None for
+             * non-measures.
+             */
+            aggregation?: string | null;
+            /**
+             * Display label
+             */
+            label?: string | null;
+        }
+        /**
+         * Grid position
+         */
+        interface Grid {
+            h?: number;
+            w?: number;
+            x?: number;
+            y?: number;
+        }
+    }
+}
+/**
+ * Response model for query combination enumeration.
+ */
+export interface CompilerEnumerateResponse {
+    /**
+     * All valid query configurations
+     */
+    combinations: Array<CompilerEnumerateResponse.Combination>;
+    /**
+     * Total number of combinations
+     */
+    total_count: number;
+}
+export declare namespace CompilerEnumerateResponse {
+    /**
+     * A single valid query configuration.
+     */
+    interface Combination {
+        /**
+         * Query template reference (e.g. 'q:COMPLIANCE_OVERVIEW')
+         */
+        query_ref: string;
+        /**
+         * Widget category (e.g. 'axis', 'table')
+         */
+        widget_category: string;
+        /**
+         * Deterministic UUID v5 for this combination
+         */
+        combination_id?: string | null;
+        /**
+         * Human-readable label for the query
+         */
+        query_label?: string | null;
+        /**
+         * Field-to-role mapping (e.g. {'due_month': 'x_axis'})
+         */
+        roles?: {
+            [key: string]: string;
+        };
+        /**
+         * Selected optional calculation names
+         */
+        selected_calculations?: Array<string>;
+        /**
+         * Selected optional dimension names
+         */
+        selected_dimensions?: Array<string>;
+        /**
+         * Selected optional filter names
+         */
+        selected_filters?: Array<string>;
+        /**
+         * Selected optional measure names
+         */
+        selected_measures?: Array<string>;
+        /**
+         * Variable name to value assignments
+         */
+        variable_assignments?: {
+            [key: string]: unknown;
+        };
+        /**
+         * Resolved widget type (e.g. 'axis_metric_by_dimensiondate')
+         */
+        widget_type?: string | null;
+    }
+}
+/**
+ * Response model for query execution.
+ */
+export interface CompilerExecuteResponse {
+    /**
+     * SQL dialect used
+     */
+    dialect: string;
+    /**
+     * Whether execution succeeded
+     */
+    success: boolean;
+    /**
+     * Whether the result was served from cache
+     */
+    cache_hit?: boolean;
+    /**
+     * Maps UUID column aliases to human-readable names
+     */
+    column_map?: Array<CompilerExecuteResponse.ColumnMap>;
+    /**
+     * Query result rows as list of column-value dicts
+     */
+    data?: Array<{
+        [key: string]: unknown;
+    }>;
+    /**
+     * Compilation errors (if any)
+     */
+    errors?: Array<CompilerErrorItem>;
+    /**
+     * Total execution time in milliseconds
+     */
+    execution_time_ms?: number;
+    /**
+     * Compilation metadata from the compiler.
+     */
+    metadata?: CompilerExecuteResponse.Metadata | null;
+    /**
+     * Number of rows returned
+     */
+    row_count?: number;
+    /**
+     * Generated SQL statement
+     */
+    sql?: string | null;
+}
+export declare namespace CompilerExecuteResponse {
+    /**
+     * Maps a UUID column alias to its human-readable name and type.
+     */
+    interface ColumnMap {
+        /**
+         * Field type: dimension, measure, or calculation
+         */
+        field_type: string;
+        /**
+         * UUID string used as SQL column alias
+         */
+        kater_id: string;
+        /**
+         * Human-readable column name
+         */
+        name: string;
+        /**
+         * Aggregation type for measures: sum, count, min, max, avg, unknown. None for
+         * non-measures.
+         */
+        aggregation?: string | null;
+        /**
+         * Display label
+         */
+        label?: string | null;
+    }
+    /**
+     * Compilation metadata from the compiler.
+     */
+    interface Metadata {
+        /**
+         * SQL dialect used (e.g. 'snowflake')
+         */
+        dialect: string;
+        /**
+         * Reference to the compiled query
+         */
+        query_ref: string;
+        /**
+         * Dimension names used in compilation
+         */
+        dimensions_used?: Array<string>;
+        /**
+         * Filter names used in compilation
+         */
+        filters_used?: Array<string>;
+        /**
+         * Measure names used in compilation
+         */
+        measures_used?: Array<string>;
+        /**
+         * View names used in compilation
+         */
+        views_used?: Array<string>;
+    }
+}
+/**
+ * Response model for a resolved query.
+ */
+export interface CompilerResolveResponse {
+    /**
+     * The fully resolved query object
+     */
+    resolved_query: CompilerResolveResponse.ResolvedQuery;
+    /**
+     * Dependency graph between schema objects.
+     */
+    dependency_graph?: CompilerResolveResponse.DependencyGraph | null;
+    /**
+     * Compilation manifest with all named objects.
+     */
+    manifest?: Manifest | null;
+    /**
+     * Files auto-fixed due to renamed refs. None when no renames detected.
+     */
+    ref_fixes?: Array<CompilerResolveResponse.RefFix> | null;
+    /**
+     * Write-back request ID. Non-null when ref-fix files were dispatched to CLI via
+     * WebSocket.
+     */
+    request_id?: string | null;
+}
+export declare namespace CompilerResolveResponse {
+    /**
+     * The fully resolved query object
+     */
+    interface ResolvedQuery {
+        /**
+         * Unique identifier for this resolved query instance
+         */
+        kater_id: string;
+        /**
+         * Name from the leaf query in the inheritance chain
+         */
+        name: string;
+        /**
+         * Reference to the original query template this was resolved from
+         */
+        source_query: string;
+        /**
+         * Reference to the topic this query uses (always known after inheritance
+         * resolution)
+         */
+        topic: string;
+        /**
+         * Widget category that determines data shape constraints
+         */
+        widget_category: 'axis' | 'funnel' | 'heatmap' | 'image' | 'kpi_card' | 'pie' | 'table' | 'text';
+        /**
+         * Usage guidance for AI processing
+         */
+        ai_context?: string | null;
+        /**
+         * Merged required + selected optional calculations
+         */
+        calculations?: Array<CompilerAPI.RefWithLabel | CompilerAPI.InlineField | string> | null;
+        /**
+         * Chart recommendations preserved for evaluation
+         */
+        chart_hints?: Array<ResolvedQuery.ChartHint1Output | ResolvedQuery.ChartHint2Output> | null;
+        /**
+         * Custom properties
+         */
+        custom_properties?: {
+            [key: string]: unknown;
+        } | null;
+        /**
+         * Description of the query
+         */
+        description?: string | null;
+        /**
+         * Merged required + selected optional dimensions
+         */
+        dimensions?: Array<CompilerAPI.RefWithLabel | CompilerAPI.InlineField | string> | null;
+        /**
+         * Widget types within the declared widget_category that must NOT render this query
+         */
+        disallowed_widget_types?: Array<'axis_metric_by_dimension' | 'axis_metric_by_dimensiondate' | 'axis_metric_by_dimensiondate_sliced_by_dimension' | 'axis_scatter_plot' | 'funnel_funnel_chart' | 'heatmap_heatmap' | 'image_image_grid' | 'image_single_image' | 'kpi_measure_with_dimension_expression' | 'kpi_measure_with_secondary_metric' | 'kpi_single_measure_compared_to_prev_period_sparkline' | 'kpi_single_value' | 'pie_pie_chart' | 'table_data_table' | 'table_fancy_subtotal_table' | 'table_key_value_list' | 'table_styled_table' | 'text_data_readout_with_sparkline' | 'text_narrative_text'> | null;
+        /**
+         * Merged required + selected optional filters
+         */
+        filters?: Array<ResolvedQuery.InlineFormulaFilter | string | ResolvedQuery.InlineExistsFilter1 | ResolvedQuery.InlineExistsFilter2> | null;
+        /**
+         * Ordered list of query refs that were merged during inheritance resolution
+         */
+        inheritance_chain?: Array<string> | null;
+        /**
+         * Human-readable label with var() values substituted
+         */
+        label?: string | null;
+        /**
+         * Maximum number of rows to return
+         */
+        limit?: number | null;
+        /**
+         * Merged required + selected optional measures
+         */
+        measures?: Array<CompilerAPI.RefWithLabel | CompilerAPI.InlineField | string> | null;
+        /**
+         * Sort order specification for query results. Use desc for descending
+         * (highest/newest first) and asc for ascending (lowest/oldest first).
+         */
+        order_by?: ResolvedQuery.OrderBy | null;
+        /**
+         * The matched chart recommendation after evaluating chart hints
+         */
+        resolved_chart?: ResolvedQuery.ResolvedChart | null;
+        /**
+         * Full variable definitions with bound values
+         */
+        resolved_variables?: Array<ResolvedQuery.ResolvedVariable> | null;
+        /**
+         * Resolved select_from entries with CTE metadata
+         */
+        select_from?: Array<ResolvedQuery.SelectFrom> | null;
+    }
+    namespace ResolvedQuery {
+        /**
+         * A chart recommendation rule
+         */
+        interface ChartHint1Output {
+            /**
+             * Chart configuration with variable references
+             */
+            config: CompilerAPI.ChartConfig;
+            /**
+             * Type of chart visualization
+             */
+            recommend: 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value';
+            /**
+             * Conditions based on variable values - can be single value (string) or multiple
+             * values (array)
+             */
+            when: {
+                [key: string]: string | Array<string>;
+            };
+        }
+        /**
+         * A chart recommendation rule
+         */
+        interface ChartHint2Output {
+            default: ChartHint2Output.Default;
+        }
+        namespace ChartHint2Output {
+            interface Default {
+                /**
+                 * Chart configuration with variable references
+                 */
+                config: CompilerAPI.ChartConfig;
+                /**
+                 * Type of chart visualization
+                 */
+                recommend: 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value';
+            }
+        }
+        /**
+         * An inline filter using a SQL/expression formula
+         */
+        interface InlineFormulaFilter {
+            /**
+             * Name of the inline filter
+             */
+            name: string;
+            /**
+             * SQL expression for the filter condition
+             */
+            sql: string;
+        }
+        /**
+         * An inline filter using EXISTS or NOT EXISTS with a subquery
+         */
+        interface InlineExistsFilter1 {
+            /**
+             * EXISTS subquery condition
+             */
+            exists: CompilerAPI.SubqueryCondition;
+            /**
+             * Name of the inline filter
+             */
+            name: string;
+            /**
+             * Description of the filter
+             */
+            description?: string | null;
+            /**
+             * Human-readable label
+             */
+            label?: string | null;
+            /**
+             * A subquery condition for EXISTS/NOT EXISTS filters
+             */
+            not_exists?: CompilerAPI.SubqueryCondition | null;
+        }
+        /**
+         * An inline filter using EXISTS or NOT EXISTS with a subquery
+         */
+        interface InlineExistsFilter2 {
+            /**
+             * Name of the inline filter
+             */
+            name: string;
+            /**
+             * NOT EXISTS subquery condition
+             */
+            not_exists: CompilerAPI.SubqueryCondition;
+            /**
+             * Description of the filter
+             */
+            description?: string | null;
+            /**
+             * A subquery condition for EXISTS/NOT EXISTS filters
+             */
+            exists?: CompilerAPI.SubqueryCondition | null;
+            /**
+             * Human-readable label
+             */
+            label?: string | null;
+        }
+        /**
+         * Sort order specification for query results. Use desc for descending
+         * (highest/newest first) and asc for ascending (lowest/oldest first).
+         */
+        interface OrderBy {
+            /**
+             * Fields to sort in ascending order (lowest/oldest first)
+             */
+            asc?: Array<string> | null;
+            /**
+             * Fields to sort in descending order (highest/newest first)
+             */
+            desc?: Array<string> | null;
+        }
+        /**
+         * The matched chart recommendation after evaluating chart hints
+         */
+        interface ResolvedChart {
+            /**
+             * Chart configuration
+             */
+            config: CompilerAPI.ChartConfig;
+            /**
+             * Recommended chart type
+             */
+            recommend: 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value';
+        }
+        /**
+         * A variable definition with its bound value
+         */
+        interface ResolvedVariable {
+            /**
+             * The concrete value bound for this resolution
+             */
+            bound_value: string | number | boolean | Array<string | number | boolean>;
+            /**
+             * Default value for this variable
+             */
+            default: string | number | boolean | Array<string | number | boolean>;
+            /**
+             * Unique identifier for this variable
+             */
+            kater_id: string;
+            /**
+             * Variable name identifier
+             */
+            name: string;
+            /**
+             * Data type of the variable
+             */
+            type: 'STRING' | 'INT' | 'FLOAT' | 'DATE' | 'TIMESTAMP' | 'BOOL' | 'STRING[]' | 'INT[]' | 'FLOAT[]' | 'DATE[]' | 'DIMENSION' | 'MEASURE' | 'CALCULATION' | 'FILTER';
+            /**
+             * Allowed values configuration
+             */
+            allowed_values?: ResolvedVariable.VariableAllowedValues1 | ResolvedVariable.VariableAllowedValues2 | null;
+            /**
+             * Constraints for variable types
+             */
+            constraints?: ResolvedVariable.Constraints | null;
+            /**
+             * Description of the variable's purpose
+             */
+            description?: string | null;
+            /**
+             * True if bound_value equals the default value
+             */
+            is_default?: boolean | null;
+            /**
+             * True if this is a runtime variable (not resolved at compile time). Runtime
+             * variables have var() placeholders left in compiled SQL for literal substitution
+             * at execution time.
+             */
+            is_runtime?: boolean | null;
+            /**
+             * Human-readable label for the variable
+             */
+            label?: string | null;
+        }
+        namespace ResolvedVariable {
+            /**
+             * Allowed values for a variable - either static list or from column
+             */
+            interface VariableAllowedValues1 {
+                /**
+                 * Static list of allowed values with optional labels
+                 */
+                static: Array<VariableAllowedValues1.Static>;
+            }
+            namespace VariableAllowedValues1 {
+                /**
+                 * A value with optional display label
+                 */
+                interface Static {
+                    /**
+                     * The actual value
+                     */
+                    value: string | number | boolean;
+                    /**
+                     * Human-readable label for the value
+                     */
+                    label?: string | null;
+                }
+            }
+            /**
+             * Allowed values for a variable - either static list or from column
+             */
+            interface VariableAllowedValues2 {
+                /**
+                 * Reference to column for dynamic values
+                 */
+                from_column: string;
+                /**
+                 * Cache time-to-live in seconds
+                 */
+                cache_ttl?: number;
+                /**
+                 * Maximum number of values to retrieve
+                 */
+                limit?: number;
+                /**
+                 * Sort order for values
+                 */
+                order_by?: 'asc' | 'desc';
+            }
+            /**
+             * Constraints for variable types
+             */
+            interface Constraints {
+                /**
+                 * Maximum allowed value
+                 */
+                max?: number | null;
+                /**
+                 * Maximum length for STRING variables
+                 */
+                max_length?: number | null;
+                /**
+                 * Minimum allowed value
+                 */
+                min?: number | null;
+                /**
+                 * Step increment for numeric input
+                 */
+                step?: number | null;
+            }
+        }
+        /**
+         * A resolved select_from entry with CTE metadata
+         */
+        interface SelectFrom {
+            /**
+             * CTE alias used in the WITH clause (e.g., **sf_compliance_rate**base)
+             */
+            cte_alias: string;
+            /**
+             * Columns produced by the CTE, available as q:query_name.field_name in the parent
+             */
+            output_columns: Array<SelectFrom.OutputColumn>;
+            /**
+             * Reference to the source query
+             */
+            ref: string;
+            /**
+             * Variable overrides passed to the referenced query
+             */
+            variables?: {
+                [key: string]: string | number | boolean;
+            } | null;
+        }
+        namespace SelectFrom {
+            /**
+             * A column produced by a select_from CTE
+             */
+            interface OutputColumn {
+                /**
+                 * The SQL column alias in the CTE output
+                 */
+                column_alias: string;
+                /**
+                 * The field name used in q:query_name.field_name references
+                 */
+                field_name: string;
+                /**
+                 * Original type of the field in the source query
+                 */
+                source_type: 'dimension' | 'dimension_date' | 'measure' | 'calculation';
+            }
+        }
+    }
+    /**
+     * Dependency graph between schema objects.
+     */
+    interface DependencyGraph {
+        /**
+         * Edge relationships with UUID string keys
+         */
+        edges: {
+            [key: string]: {
+                [key: string]: Array<string>;
+            };
+        };
+        /**
+         * UUID string to node mapping
+         */
+        nodes: {
+            [key: string]: DependencyGraph.Nodes;
+        };
+    }
+    namespace DependencyGraph {
+        /**
+         * A node in the dependency graph.
+         */
+        interface Nodes {
+            /**
+             * Source file path
+             */
+            file: string;
+            /**
+             * Fully qualified name (e.g. 'dim_customer.region')
+             */
+            fqn: string;
+            /**
+             * UUID of the schema object
+             */
+            kater_id: string;
+            /**
+             * Line number in source file
+             */
+            line: number;
+            /**
+             * Node type: QUERY, VIEW, DIMENSION, MEASURE, FILTER, EXPRESSION
+             */
+            node_type: string;
+            /**
+             * Column number in source file
+             */
+            column?: number;
+        }
+    }
+    /**
+     * A file that was modified by auto-fix with its replacements.
+     */
+    interface RefFix {
+        /**
+         * Path to the modified file
+         */
+        file_path: string;
+        /**
+         * Full updated file content after fixes
+         */
+        new_content: string;
+        /**
+         * Individual ref replacements made in this file
+         */
+        replacements: Array<RefFix.Replacement>;
+    }
+    namespace RefFix {
+        /**
+         * A single ref replacement within a file.
+         */
+        interface Replacement {
+            /**
+             * Path to the file containing the replaced ref
+             */
+            file_path: string;
+            /**
+             * Line number where the replacement occurred
+             */
+            line_number: number;
+            /**
+             * Updated reference string
+             */
+            new_ref: string;
+            /**
+             * Original reference string
+             */
+            old_ref: string;
+        }
+    }
+}
+/**
+ * Response model for schema validation.
+ */
+export interface CompilerValidateResponse {
+    /**
+     * Whether validation passed without errors
+     */
+    success: boolean;
+    /**
+     * Per-connection validation results with dependency graphs
+     */
+    connection_results?: Array<CompilerValidateResponse.ConnectionResult>;
+    /**
+     * Validation errors
+     */
+    errors?: Array<CompilerErrorItem>;
+    /**
+     * Write-back request ID. Non-null when files were dispatched to CLI via WebSocket.
+     */
+    request_id?: string | null;
+    /**
+     * Validation warnings
+     */
+    warnings?: Array<CompilerErrorItem>;
+}
+export declare namespace CompilerValidateResponse {
+    /**
+     * Validation result for a single connection.
+     */
+    interface ConnectionResult {
+        /**
+         * Connection UUID
+         */
+        connection_id: string;
+        /**
+         * Connection name
+         */
+        connection_name: string;
+        /**
+         * Whether this connection validated without errors
+         */
+        success: boolean;
+        /**
+         * Dependency graph between schema objects.
+         */
+        dependency_graph?: ConnectionResult.DependencyGraph | null;
+        /**
+         * Validation errors for this connection
+         */
+        errors?: Array<CompilerAPI.CompilerErrorItem>;
+        /**
+         * Compilation manifest with all named objects.
+         */
+        manifest?: CompilerAPI.Manifest | null;
+        /**
+         * Files auto-fixed due to renamed refs. None when no renames detected.
+         */
+        ref_fixes?: Array<ConnectionResult.RefFix> | null;
+        /**
+         * Validation warnings for this connection
+         */
+        warnings?: Array<CompilerAPI.CompilerErrorItem>;
+    }
+    namespace ConnectionResult {
+        /**
+         * Dependency graph between schema objects.
+         */
+        interface DependencyGraph {
+            /**
+             * Edge relationships with UUID string keys
+             */
+            edges: {
+                [key: string]: {
+                    [key: string]: Array<string>;
+                };
+            };
+            /**
+             * UUID string to node mapping
+             */
+            nodes: {
+                [key: string]: DependencyGraph.Nodes;
+            };
+        }
+        namespace DependencyGraph {
+            /**
+             * A node in the dependency graph.
+             */
+            interface Nodes {
+                /**
+                 * Source file path
+                 */
+                file: string;
+                /**
+                 * Fully qualified name (e.g. 'dim_customer.region')
+                 */
+                fqn: string;
+                /**
+                 * UUID of the schema object
+                 */
+                kater_id: string;
+                /**
+                 * Line number in source file
+                 */
+                line: number;
+                /**
+                 * Node type: QUERY, VIEW, DIMENSION, MEASURE, FILTER, EXPRESSION
+                 */
+                node_type: string;
+                /**
+                 * Column number in source file
+                 */
+                column?: number;
+            }
+        }
+        /**
+         * A file that was modified by auto-fix with its replacements.
+         */
+        interface RefFix {
+            /**
+             * Path to the modified file
+             */
+            file_path: string;
+            /**
+             * Full updated file content after fixes
+             */
+            new_content: string;
+            /**
+             * Individual ref replacements made in this file
+             */
+            replacements: Array<RefFix.Replacement>;
+        }
+        namespace RefFix {
+            /**
+             * A single ref replacement within a file.
+             */
+            interface Replacement {
+                /**
+                 * Path to the file containing the replaced ref
+                 */
+                file_path: string;
+                /**
+                 * Line number where the replacement occurred
+                 */
+                line_number: number;
+                /**
+                 * Updated reference string
+                 */
+                new_ref: string;
+                /**
+                 * Original reference string
+                 */
+                old_ref: string;
+            }
+        }
+    }
+}
+export interface CompilerCompileParams {
+    /**
+     * Body param: Connection to compile against
+     */
+    connection_id: string;
+    /**
+     * Body param: Previously resolved query object from /resolve
+     */
+    resolved_query: CompilerCompileParams.ResolvedQuery;
+    /**
+     * Query param
+     */
+    source?: string | null;
+    /**
+     * Body param: Tenant key for multi-tenant compilation. For database tenancy, maps
+     * to the tenant's database. For row tenancy, used as the row-level filter value.
+     */
+    tenant_key?: string | null;
+    /**
+     * Header param
+     */
+    'X-Kater-CLI-ID'?: string;
+}
+export declare namespace CompilerCompileParams {
+    /**
+     * Previously resolved query object from /resolve
+     */
+    interface ResolvedQuery {
+        /**
+         * Unique identifier for this resolved query instance
+         */
+        kater_id: string;
+        /**
+         * Name from the leaf query in the inheritance chain
+         */
+        name: string;
+        /**
+         * Reference to the original query template this was resolved from
+         */
+        source_query: string;
+        /**
+         * Reference to the topic this query uses (always known after inheritance
+         * resolution)
+         */
+        topic: string;
+        /**
+         * Widget category that determines data shape constraints
+         */
+        widget_category: 'axis' | 'funnel' | 'heatmap' | 'image' | 'kpi_card' | 'pie' | 'table' | 'text';
+        /**
+         * Usage guidance for AI processing
+         */
+        ai_context?: string | null;
+        /**
+         * Merged required + selected optional calculations
+         */
+        calculations?: Array<CompilerAPI.RefWithLabel | CompilerAPI.InlineField | string> | null;
+        /**
+         * Chart recommendations preserved for evaluation
+         */
+        chart_hints?: Array<ResolvedQuery.ChartHint1Input | ResolvedQuery.ChartHint2Input> | null;
+        /**
+         * Custom properties
+         */
+        custom_properties?: {
+            [key: string]: unknown;
+        } | null;
+        /**
+         * Description of the query
+         */
+        description?: string | null;
+        /**
+         * Merged required + selected optional dimensions
+         */
+        dimensions?: Array<CompilerAPI.RefWithLabel | CompilerAPI.InlineField | string> | null;
+        /**
+         * Widget types within the declared widget_category that must NOT render this query
+         */
+        disallowed_widget_types?: Array<'axis_metric_by_dimension' | 'axis_metric_by_dimensiondate' | 'axis_metric_by_dimensiondate_sliced_by_dimension' | 'axis_scatter_plot' | 'funnel_funnel_chart' | 'heatmap_heatmap' | 'image_image_grid' | 'image_single_image' | 'kpi_measure_with_dimension_expression' | 'kpi_measure_with_secondary_metric' | 'kpi_single_measure_compared_to_prev_period_sparkline' | 'kpi_single_value' | 'pie_pie_chart' | 'table_data_table' | 'table_fancy_subtotal_table' | 'table_key_value_list' | 'table_styled_table' | 'text_data_readout_with_sparkline' | 'text_narrative_text'> | null;
+        /**
+         * Merged required + selected optional filters
+         */
+        filters?: Array<ResolvedQuery.InlineFormulaFilter | string | ResolvedQuery.InlineExistsFilter1 | ResolvedQuery.InlineExistsFilter2> | null;
+        /**
+         * Ordered list of query refs that were merged during inheritance resolution
+         */
+        inheritance_chain?: Array<string> | null;
+        /**
+         * Human-readable label with var() values substituted
+         */
+        label?: string | null;
+        /**
+         * Maximum number of rows to return
+         */
+        limit?: number | null;
+        /**
+         * Merged required + selected optional measures
+         */
+        measures?: Array<CompilerAPI.RefWithLabel | CompilerAPI.InlineField | string> | null;
+        /**
+         * Sort order specification for query results. Use desc for descending
+         * (highest/newest first) and asc for ascending (lowest/oldest first).
+         */
+        order_by?: ResolvedQuery.OrderBy | null;
+        /**
+         * The matched chart recommendation after evaluating chart hints
+         */
+        resolved_chart?: ResolvedQuery.ResolvedChart | null;
+        /**
+         * Full variable definitions with bound values
+         */
+        resolved_variables?: Array<ResolvedQuery.ResolvedVariable> | null;
+        /**
+         * Resolved select_from entries with CTE metadata
+         */
+        select_from?: Array<ResolvedQuery.SelectFrom> | null;
+    }
+    namespace ResolvedQuery {
+        /**
+         * A chart recommendation rule
+         */
+        interface ChartHint1Input {
+            /**
+             * Chart configuration with variable references
+             */
+            config: CompilerAPI.ChartConfig;
+            /**
+             * Type of chart visualization
+             */
+            recommend: 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value';
+            /**
+             * Conditions based on variable values - can be single value (string) or multiple
+             * values (array)
+             */
+            when: {
+                [key: string]: string | Array<string>;
+            };
+        }
+        /**
+         * A chart recommendation rule
+         */
+        interface ChartHint2Input {
+            default: ChartHint2Input.Default;
+        }
+        namespace ChartHint2Input {
+            interface Default {
+                /**
+                 * Chart configuration with variable references
+                 */
+                config: CompilerAPI.ChartConfig;
+                /**
+                 * Type of chart visualization
+                 */
+                recommend: 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value';
+            }
+        }
+        /**
+         * An inline filter using a SQL/expression formula
+         */
+        interface InlineFormulaFilter {
+            /**
+             * Name of the inline filter
+             */
+            name: string;
+            /**
+             * SQL expression for the filter condition
+             */
+            sql: string;
+        }
+        /**
+         * An inline filter using EXISTS or NOT EXISTS with a subquery
+         */
+        interface InlineExistsFilter1 {
+            /**
+             * EXISTS subquery condition
+             */
+            exists: CompilerAPI.SubqueryCondition;
+            /**
+             * Name of the inline filter
+             */
+            name: string;
+            /**
+             * Description of the filter
+             */
+            description?: string | null;
+            /**
+             * Human-readable label
+             */
+            label?: string | null;
+            /**
+             * A subquery condition for EXISTS/NOT EXISTS filters
+             */
+            not_exists?: CompilerAPI.SubqueryCondition | null;
+        }
+        /**
+         * An inline filter using EXISTS or NOT EXISTS with a subquery
+         */
+        interface InlineExistsFilter2 {
+            /**
+             * Name of the inline filter
+             */
+            name: string;
+            /**
+             * NOT EXISTS subquery condition
+             */
+            not_exists: CompilerAPI.SubqueryCondition;
+            /**
+             * Description of the filter
+             */
+            description?: string | null;
+            /**
+             * A subquery condition for EXISTS/NOT EXISTS filters
+             */
+            exists?: CompilerAPI.SubqueryCondition | null;
+            /**
+             * Human-readable label
+             */
+            label?: string | null;
+        }
+        /**
+         * Sort order specification for query results. Use desc for descending
+         * (highest/newest first) and asc for ascending (lowest/oldest first).
+         */
+        interface OrderBy {
+            /**
+             * Fields to sort in ascending order (lowest/oldest first)
+             */
+            asc?: Array<string> | null;
+            /**
+             * Fields to sort in descending order (highest/newest first)
+             */
+            desc?: Array<string> | null;
+        }
+        /**
+         * The matched chart recommendation after evaluating chart hints
+         */
+        interface ResolvedChart {
+            /**
+             * Chart configuration
+             */
+            config: CompilerAPI.ChartConfig;
+            /**
+             * Recommended chart type
+             */
+            recommend: 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value';
+        }
+        /**
+         * A variable definition with its bound value
+         */
+        interface ResolvedVariable {
+            /**
+             * The concrete value bound for this resolution
+             */
+            bound_value: string | number | boolean | Array<string | number | boolean>;
+            /**
+             * Default value for this variable
+             */
+            default: string | number | boolean | Array<string | number | boolean>;
+            /**
+             * Unique identifier for this variable
+             */
+            kater_id: string;
+            /**
+             * Variable name identifier
+             */
+            name: string;
+            /**
+             * Data type of the variable
+             */
+            type: 'STRING' | 'INT' | 'FLOAT' | 'DATE' | 'TIMESTAMP' | 'BOOL' | 'STRING[]' | 'INT[]' | 'FLOAT[]' | 'DATE[]' | 'DIMENSION' | 'MEASURE' | 'CALCULATION' | 'FILTER';
+            /**
+             * Allowed values configuration
+             */
+            allowed_values?: ResolvedVariable.VariableAllowedValues1 | ResolvedVariable.VariableAllowedValues2 | null;
+            /**
+             * Constraints for variable types
+             */
+            constraints?: ResolvedVariable.Constraints | null;
+            /**
+             * Description of the variable's purpose
+             */
+            description?: string | null;
+            /**
+             * True if bound_value equals the default value
+             */
+            is_default?: boolean | null;
+            /**
+             * True if this is a runtime variable (not resolved at compile time). Runtime
+             * variables have var() placeholders left in compiled SQL for literal substitution
+             * at execution time.
+             */
+            is_runtime?: boolean | null;
+            /**
+             * Human-readable label for the variable
+             */
+            label?: string | null;
+        }
+        namespace ResolvedVariable {
+            /**
+             * Allowed values for a variable - either static list or from column
+             */
+            interface VariableAllowedValues1 {
+                /**
+                 * Static list of allowed values with optional labels
+                 */
+                static: Array<VariableAllowedValues1.Static>;
+            }
+            namespace VariableAllowedValues1 {
+                /**
+                 * A value with optional display label
+                 */
+                interface Static {
+                    /**
+                     * The actual value
+                     */
+                    value: string | number | boolean;
+                    /**
+                     * Human-readable label for the value
+                     */
+                    label?: string | null;
+                }
+            }
+            /**
+             * Allowed values for a variable - either static list or from column
+             */
+            interface VariableAllowedValues2 {
+                /**
+                 * Reference to column for dynamic values
+                 */
+                from_column: string;
+                /**
+                 * Cache time-to-live in seconds
+                 */
+                cache_ttl?: number;
+                /**
+                 * Maximum number of values to retrieve
+                 */
+                limit?: number;
+                /**
+                 * Sort order for values
+                 */
+                order_by?: 'asc' | 'desc';
+            }
+            /**
+             * Constraints for variable types
+             */
+            interface Constraints {
+                /**
+                 * Maximum allowed value
+                 */
+                max?: number | null;
+                /**
+                 * Maximum length for STRING variables
+                 */
+                max_length?: number | null;
+                /**
+                 * Minimum allowed value
+                 */
+                min?: number | null;
+                /**
+                 * Step increment for numeric input
+                 */
+                step?: number | null;
+            }
+        }
+        /**
+         * A resolved select_from entry with CTE metadata
+         */
+        interface SelectFrom {
+            /**
+             * CTE alias used in the WITH clause (e.g., **sf_compliance_rate**base)
+             */
+            cte_alias: string;
+            /**
+             * Columns produced by the CTE, available as q:query_name.field_name in the parent
+             */
+            output_columns: Array<SelectFrom.OutputColumn>;
+            /**
+             * Reference to the source query
+             */
+            ref: string;
+            /**
+             * Variable overrides passed to the referenced query
+             */
+            variables?: {
+                [key: string]: string | number | boolean;
+            } | null;
+        }
+        namespace SelectFrom {
+            /**
+             * A column produced by a select_from CTE
+             */
+            interface OutputColumn {
+                /**
+                 * The SQL column alias in the CTE output
+                 */
+                column_alias: string;
+                /**
+                 * The field name used in q:query_name.field_name references
+                 */
+                field_name: string;
+                /**
+                 * Original type of the field in the source query
+                 */
+                source_type: 'dimension' | 'dimension_date' | 'measure' | 'calculation';
+            }
+        }
+    }
+}
+export interface CompilerCompileDashboardParams {
+    /**
+     * Body param: Connection to compile against
+     */
+    connection_id: string;
+    /**
+     * Body param: Relative path within the connection (e.g.
+     * 'dashboards/compliance_overview')
+     */
+    dashboard_path: string;
+    /**
+     * Query param
+     */
+    source?: string | null;
+    /**
+     * Body param: Optional filter overrides from UI
+     */
+    filters?: {
+        [key: string]: string | Array<string> | null;
+    } | null;
+    /**
+     * Body param: Optional tenant key for multi-tenant execution
+     */
+    tenant_key?: string | null;
+    /**
+     * Header param
+     */
+    'X-Kater-CLI-ID'?: string;
+}
+export interface CompilerEnumerateParams {
+    /**
+     * Body param: Connection to enumerate against
+     */
+    connection_id: string;
+    /**
+     * Query param
+     */
+    source?: string | null;
+    /**
+     * Body param: Optional query refs to limit enumeration. If omitted, enumerates all
+     * queries.
+     */
+    query_refs?: Array<string> | null;
+    /**
+     * Body param: Tenant key for multi-tenant clients. Required when the client uses
+     * row or database tenancy.
+     */
+    tenant_key?: string | null;
+    /**
+     * Header param
+     */
+    'X-Kater-CLI-ID'?: string;
+}
+export interface CompilerExecuteParams {
+    /**
+     * Body param: Connection to execute against
+     */
+    connection_id: string;
+    /**
+     * Body param: Previously resolved query object from /resolve
+     */
+    resolved_query: CompilerExecuteParams.ResolvedQuery;
+    /**
+     * Query param
+     */
+    source?: string | null;
+    /**
+     * Body param: Tenant key for multi-tenant execution
+     */
+    tenant_key?: string | null;
+    /**
+     * Header param
+     */
+    'X-Kater-CLI-ID'?: string;
+}
+export declare namespace CompilerExecuteParams {
+    /**
+     * Previously resolved query object from /resolve
+     */
+    interface ResolvedQuery {
+        /**
+         * Unique identifier for this resolved query instance
+         */
+        kater_id: string;
+        /**
+         * Name from the leaf query in the inheritance chain
+         */
+        name: string;
+        /**
+         * Reference to the original query template this was resolved from
+         */
+        source_query: string;
+        /**
+         * Reference to the topic this query uses (always known after inheritance
+         * resolution)
+         */
+        topic: string;
+        /**
+         * Widget category that determines data shape constraints
+         */
+        widget_category: 'axis' | 'funnel' | 'heatmap' | 'image' | 'kpi_card' | 'pie' | 'table' | 'text';
+        /**
+         * Usage guidance for AI processing
+         */
+        ai_context?: string | null;
+        /**
+         * Merged required + selected optional calculations
+         */
+        calculations?: Array<CompilerAPI.RefWithLabel | CompilerAPI.InlineField | string> | null;
+        /**
+         * Chart recommendations preserved for evaluation
+         */
+        chart_hints?: Array<ResolvedQuery.ChartHint1Input | ResolvedQuery.ChartHint2Input> | null;
+        /**
+         * Custom properties
+         */
+        custom_properties?: {
+            [key: string]: unknown;
+        } | null;
+        /**
+         * Description of the query
+         */
+        description?: string | null;
+        /**
+         * Merged required + selected optional dimensions
+         */
+        dimensions?: Array<CompilerAPI.RefWithLabel | CompilerAPI.InlineField | string> | null;
+        /**
+         * Widget types within the declared widget_category that must NOT render this query
+         */
+        disallowed_widget_types?: Array<'axis_metric_by_dimension' | 'axis_metric_by_dimensiondate' | 'axis_metric_by_dimensiondate_sliced_by_dimension' | 'axis_scatter_plot' | 'funnel_funnel_chart' | 'heatmap_heatmap' | 'image_image_grid' | 'image_single_image' | 'kpi_measure_with_dimension_expression' | 'kpi_measure_with_secondary_metric' | 'kpi_single_measure_compared_to_prev_period_sparkline' | 'kpi_single_value' | 'pie_pie_chart' | 'table_data_table' | 'table_fancy_subtotal_table' | 'table_key_value_list' | 'table_styled_table' | 'text_data_readout_with_sparkline' | 'text_narrative_text'> | null;
+        /**
+         * Merged required + selected optional filters
+         */
+        filters?: Array<ResolvedQuery.InlineFormulaFilter | string | ResolvedQuery.InlineExistsFilter1 | ResolvedQuery.InlineExistsFilter2> | null;
+        /**
+         * Ordered list of query refs that were merged during inheritance resolution
+         */
+        inheritance_chain?: Array<string> | null;
+        /**
+         * Human-readable label with var() values substituted
+         */
+        label?: string | null;
+        /**
+         * Maximum number of rows to return
+         */
+        limit?: number | null;
+        /**
+         * Merged required + selected optional measures
+         */
+        measures?: Array<CompilerAPI.RefWithLabel | CompilerAPI.InlineField | string> | null;
+        /**
+         * Sort order specification for query results. Use desc for descending
+         * (highest/newest first) and asc for ascending (lowest/oldest first).
+         */
+        order_by?: ResolvedQuery.OrderBy | null;
+        /**
+         * The matched chart recommendation after evaluating chart hints
+         */
+        resolved_chart?: ResolvedQuery.ResolvedChart | null;
+        /**
+         * Full variable definitions with bound values
+         */
+        resolved_variables?: Array<ResolvedQuery.ResolvedVariable> | null;
+        /**
+         * Resolved select_from entries with CTE metadata
+         */
+        select_from?: Array<ResolvedQuery.SelectFrom> | null;
+    }
+    namespace ResolvedQuery {
+        /**
+         * A chart recommendation rule
+         */
+        interface ChartHint1Input {
+            /**
+             * Chart configuration with variable references
+             */
+            config: CompilerAPI.ChartConfig;
+            /**
+             * Type of chart visualization
+             */
+            recommend: 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value';
+            /**
+             * Conditions based on variable values - can be single value (string) or multiple
+             * values (array)
+             */
+            when: {
+                [key: string]: string | Array<string>;
+            };
+        }
+        /**
+         * A chart recommendation rule
+         */
+        interface ChartHint2Input {
+            default: ChartHint2Input.Default;
+        }
+        namespace ChartHint2Input {
+            interface Default {
+                /**
+                 * Chart configuration with variable references
+                 */
+                config: CompilerAPI.ChartConfig;
+                /**
+                 * Type of chart visualization
+                 */
+                recommend: 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value';
+            }
+        }
+        /**
+         * An inline filter using a SQL/expression formula
+         */
+        interface InlineFormulaFilter {
+            /**
+             * Name of the inline filter
+             */
+            name: string;
+            /**
+             * SQL expression for the filter condition
+             */
+            sql: string;
+        }
+        /**
+         * An inline filter using EXISTS or NOT EXISTS with a subquery
+         */
+        interface InlineExistsFilter1 {
+            /**
+             * EXISTS subquery condition
+             */
+            exists: CompilerAPI.SubqueryCondition;
+            /**
+             * Name of the inline filter
+             */
+            name: string;
+            /**
+             * Description of the filter
+             */
+            description?: string | null;
+            /**
+             * Human-readable label
+             */
+            label?: string | null;
+            /**
+             * A subquery condition for EXISTS/NOT EXISTS filters
+             */
+            not_exists?: CompilerAPI.SubqueryCondition | null;
+        }
+        /**
+         * An inline filter using EXISTS or NOT EXISTS with a subquery
+         */
+        interface InlineExistsFilter2 {
+            /**
+             * Name of the inline filter
+             */
+            name: string;
+            /**
+             * NOT EXISTS subquery condition
+             */
+            not_exists: CompilerAPI.SubqueryCondition;
+            /**
+             * Description of the filter
+             */
+            description?: string | null;
+            /**
+             * A subquery condition for EXISTS/NOT EXISTS filters
+             */
+            exists?: CompilerAPI.SubqueryCondition | null;
+            /**
+             * Human-readable label
+             */
+            label?: string | null;
+        }
+        /**
+         * Sort order specification for query results. Use desc for descending
+         * (highest/newest first) and asc for ascending (lowest/oldest first).
+         */
+        interface OrderBy {
+            /**
+             * Fields to sort in ascending order (lowest/oldest first)
+             */
+            asc?: Array<string> | null;
+            /**
+             * Fields to sort in descending order (highest/newest first)
+             */
+            desc?: Array<string> | null;
+        }
+        /**
+         * The matched chart recommendation after evaluating chart hints
+         */
+        interface ResolvedChart {
+            /**
+             * Chart configuration
+             */
+            config: CompilerAPI.ChartConfig;
+            /**
+             * Recommended chart type
+             */
+            recommend: 'line' | 'bar' | 'stacked_bar' | 'area' | 'pie' | 'donut' | 'scatter' | 'table' | 'heatmap' | 'single_value';
+        }
+        /**
+         * A variable definition with its bound value
+         */
+        interface ResolvedVariable {
+            /**
+             * The concrete value bound for this resolution
+             */
+            bound_value: string | number | boolean | Array<string | number | boolean>;
+            /**
+             * Default value for this variable
+             */
+            default: string | number | boolean | Array<string | number | boolean>;
+            /**
+             * Unique identifier for this variable
+             */
+            kater_id: string;
+            /**
+             * Variable name identifier
+             */
+            name: string;
+            /**
+             * Data type of the variable
+             */
+            type: 'STRING' | 'INT' | 'FLOAT' | 'DATE' | 'TIMESTAMP' | 'BOOL' | 'STRING[]' | 'INT[]' | 'FLOAT[]' | 'DATE[]' | 'DIMENSION' | 'MEASURE' | 'CALCULATION' | 'FILTER';
+            /**
+             * Allowed values configuration
+             */
+            allowed_values?: ResolvedVariable.VariableAllowedValues1 | ResolvedVariable.VariableAllowedValues2 | null;
+            /**
+             * Constraints for variable types
+             */
+            constraints?: ResolvedVariable.Constraints | null;
+            /**
+             * Description of the variable's purpose
+             */
+            description?: string | null;
+            /**
+             * True if bound_value equals the default value
+             */
+            is_default?: boolean | null;
+            /**
+             * True if this is a runtime variable (not resolved at compile time). Runtime
+             * variables have var() placeholders left in compiled SQL for literal substitution
+             * at execution time.
+             */
+            is_runtime?: boolean | null;
+            /**
+             * Human-readable label for the variable
+             */
+            label?: string | null;
+        }
+        namespace ResolvedVariable {
+            /**
+             * Allowed values for a variable - either static list or from column
+             */
+            interface VariableAllowedValues1 {
+                /**
+                 * Static list of allowed values with optional labels
+                 */
+                static: Array<VariableAllowedValues1.Static>;
+            }
+            namespace VariableAllowedValues1 {
+                /**
+                 * A value with optional display label
+                 */
+                interface Static {
+                    /**
+                     * The actual value
+                     */
+                    value: string | number | boolean;
+                    /**
+                     * Human-readable label for the value
+                     */
+                    label?: string | null;
+                }
+            }
+            /**
+             * Allowed values for a variable - either static list or from column
+             */
+            interface VariableAllowedValues2 {
+                /**
+                 * Reference to column for dynamic values
+                 */
+                from_column: string;
+                /**
+                 * Cache time-to-live in seconds
+                 */
+                cache_ttl?: number;
+                /**
+                 * Maximum number of values to retrieve
+                 */
+                limit?: number;
+                /**
+                 * Sort order for values
+                 */
+                order_by?: 'asc' | 'desc';
+            }
+            /**
+             * Constraints for variable types
+             */
+            interface Constraints {
+                /**
+                 * Maximum allowed value
+                 */
+                max?: number | null;
+                /**
+                 * Maximum length for STRING variables
+                 */
+                max_length?: number | null;
+                /**
+                 * Minimum allowed value
+                 */
+                min?: number | null;
+                /**
+                 * Step increment for numeric input
+                 */
+                step?: number | null;
+            }
+        }
+        /**
+         * A resolved select_from entry with CTE metadata
+         */
+        interface SelectFrom {
+            /**
+             * CTE alias used in the WITH clause (e.g., **sf_compliance_rate**base)
+             */
+            cte_alias: string;
+            /**
+             * Columns produced by the CTE, available as q:query_name.field_name in the parent
+             */
+            output_columns: Array<SelectFrom.OutputColumn>;
+            /**
+             * Reference to the source query
+             */
+            ref: string;
+            /**
+             * Variable overrides passed to the referenced query
+             */
+            variables?: {
+                [key: string]: string | number | boolean;
+            } | null;
+        }
+        namespace SelectFrom {
+            /**
+             * A column produced by a select_from CTE
+             */
+            interface OutputColumn {
+                /**
+                 * The SQL column alias in the CTE output
+                 */
+                column_alias: string;
+                /**
+                 * The field name used in q:query_name.field_name references
+                 */
+                field_name: string;
+                /**
+                 * Original type of the field in the source query
+                 */
+                source_type: 'dimension' | 'dimension_date' | 'measure' | 'calculation';
+            }
+        }
+    }
+}
+export interface CompilerResolveParams {
+    /**
+     * Body param: Connection to resolve against
+     */
+    connection_id: string;
+    /**
+     * Body param: Reference to the query template (e.g. 'ref(MY_QUERY)')
+     */
+    query_ref: string;
+    /**
+     * Query param
+     */
+    source?: string | null;
+    /**
+     * Body param: Automatically fix broken refs caused by renames. Defaults to True.
+     */
+    auto_fix?: boolean;
+    /**
+     * Body param: Comma-separated slot selections and variable assignments. Reserved
+     * keys: measure, dimension, filter, calculation. All other keys are variable
+     * assignments. Example: 'measure=Compliance
+     * Rate,dimension=Department,breakdown=region'
+     */
+    combination?: string;
+    /**
+     * Header param
+     */
+    'X-Kater-CLI-ID'?: string;
+}
+export interface CompilerValidateParams {
+    /**
+     * Query param
+     */
+    source?: string | null;
+    /**
+     * Body param: Automatically fix broken refs caused by renames. Defaults to True.
+     */
+    auto_fix?: boolean;
+    /**
+     * Body param: Optional connection IDs to validate. If omitted, validates all
+     * connections.
+     */
+    connection_ids?: Array<string> | null;
+    /**
+     * Header param
+     */
+    'X-Kater-CLI-ID'?: string;
+}
+export declare namespace Compiler {
+    export { type ChartConfig as ChartConfig, type CompilerErrorItem as CompilerErrorItem, type InlineField as InlineField, type Manifest as Manifest, type ManifestEntry as ManifestEntry, type RefWithLabel as RefWithLabel, type SubqueryCondition as SubqueryCondition, type CompilerCompileResponse as CompilerCompileResponse, type CompilerCompileDashboardResponse as CompilerCompileDashboardResponse, type CompilerEnumerateResponse as CompilerEnumerateResponse, type CompilerExecuteResponse as CompilerExecuteResponse, type CompilerResolveResponse as CompilerResolveResponse, type CompilerValidateResponse as CompilerValidateResponse, type CompilerCompileParams as CompilerCompileParams, type CompilerCompileDashboardParams as CompilerCompileDashboardParams, type CompilerEnumerateParams as CompilerEnumerateParams, type CompilerExecuteParams as CompilerExecuteParams, type CompilerResolveParams as CompilerResolveParams, type CompilerValidateParams as CompilerValidateParams, };
+    export { Cache as Cache };
+    export { CombinationAPICombination as Combination, type CombinationPreviewResponse as CombinationPreviewResponse, type CombinationPreviewParams as CombinationPreviewParams, };
+    export { type ManifestRegenerateAndCreatePrResponse as ManifestRegenerateAndCreatePrResponse, type ManifestRegenerateAndCreatePrParams as ManifestRegenerateAndCreatePrParams, };
+}
+//# sourceMappingURL=compiler.d.ts.map