drizzle-cube 0.3.32 → 0.4.0

package/dist/server/index.d.ts

@@ -277,6 +277,151 @@ export declare interface CacheProvider {
     close?(): Promise<void>;
 }
 
+/**
+ * Calculated Measure Resolver
+ * Manages dependency resolution for calculated measures
+ */
+export declare class CalculatedMeasureResolver {
+    private dependencyGraph;
+    private cubes;
+    constructor(cubes: Map<string, Cube> | Cube);
+    /**
+     * Extract {member} references from calculatedSql template
+     * Supports both {measure} and {Cube.measure} syntax
+     *
+     * @param calculatedSql - Template string with {member} references
+     * @returns Array of dependency information
+     */
+    extractDependencies(calculatedSql: string): MeasureDependency[];
+    /**
+     * Build dependency graph for all calculated measures in a cube
+     *
+     * @param cube - The cube containing measures
+     */
+    buildGraph(cube: Cube): void;
+    /**
+     * Build dependency graph for multiple cubes
+     *
+     * @param cubes - Map of cubes to analyze
+     */
+    buildGraphForMultipleCubes(cubes: Map<string, Cube>): void;
+    /**
+     * Calculate in-degree for each node (number of measures depending on it)
+     */
+    private calculateInDegrees;
+    /**
+     * Perform topological sort using Kahn's algorithm
+     * Returns measures in dependency order (dependencies first)
+     *
+     * @param measureNames - List of measure names to sort
+     * @returns Sorted array of measure names
+     * @throws Error if circular dependency detected
+     */
+    topologicalSort(measureNames: string[]): string[];
+    /**
+     * Detect circular dependencies using DFS
+     * Returns the cycle path if found, null otherwise
+     *
+     * @returns Array representing the cycle, or null
+     */
+    detectCycle(): string[] | null;
+    /**
+     * DFS helper for cycle detection
+     */
+    private dfs;
+    /**
+     * Get all dependencies for a specific measure (direct and transitive)
+     *
+     * @param measureName - Full measure name (e.g., "Cube.measure")
+     * @returns Set of all dependency measure names
+     */
+    getAllDependencies(measureName: string): Set<string>;
+    /**
+     * Validate that all dependencies exist
+     *
+     * @param cube - The cube to validate
+     * @throws Error if dependencies are missing
+     */
+    validateDependencies(cube: Cube): void;
+    /**
+     * Auto-populate dependencies array for calculated measures
+     * Updates the measure objects with detected dependencies
+     *
+     * @param cube - The cube to update
+     */
+    populateDependencies(cube: Cube): void;
+    /**
+     * Check if a measure is a calculated measure
+     *
+     * @param measure - The measure to check
+     * @returns True if the measure is calculated
+     */
+    static isCalculatedMeasure(measure: Measure): boolean;
+}
+
+/** Reference to a column for join keys */
+declare interface ColumnRef {
+    column: AnyColumn;
+    alias?: string;
+}
+
+export declare class ComparisonQueryBuilder {
+    private dateTimeBuilder;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Check if a query contains compareDateRange
+     */
+    hasComparison(query: SemanticQuery): boolean;
+    /**
+     * Get the time dimension with compareDateRange
+     */
+    getComparisonTimeDimension(query: SemanticQuery): TimeDimension | undefined;
+    /**
+     * Normalize compareDateRange entries to concrete date ranges
+     * Handles both relative strings ('last 30 days') and explicit arrays (['2024-01-01', '2024-01-31'])
+     */
+    normalizePeriods(compareDateRange: (string | [string, string])[]): NormalizedPeriod[];
+    /**
+     * Create sub-query for a specific period
+     * Replaces compareDateRange with a concrete dateRange for that period
+     */
+    createPeriodQuery(query: SemanticQuery, period: NormalizedPeriod): SemanticQuery;
+    /**
+     * Calculate the day-of-period index for a date
+     * Used for aligning data points across periods in overlay mode
+     */
+    calculatePeriodDayIndex(date: Date | string, periodStart: Date, granularity: TimeGranularity): number;
+    /**
+     * Add period metadata to result rows
+     */
+    addPeriodMetadata(data: Record<string, unknown>[], period: NormalizedPeriod, timeDimensionKey: string, granularity: TimeGranularity): ComparisonResultRow[];
+    /**
+     * Merge results from multiple period queries
+     * Adds period metadata and creates combined result with annotation
+     */
+    mergeComparisonResults(periodResults: Array<{
+        result: QueryResult;
+        period: NormalizedPeriod;
+    }>, timeDimension: TimeDimension, granularity: TimeGranularity): QueryResult;
+    /**
+     * Sort merged results by period index and then by time dimension
+     * Ensures consistent ordering for client-side processing
+     */
+    sortComparisonResults(data: ComparisonResultRow[], timeDimensionKey: string): ComparisonResultRow[];
+}
+
+/**
+ * Extended result row with period metadata for alignment
+ */
+declare interface ComparisonResultRow extends Record<string, unknown> {
+    /** Period label (e.g., "2024-01-01 - 2024-01-31") */
+    __period: string;
+    /** Period index (0 = current, 1 = prior, etc.) */
+    __periodIndex: number;
+    /** Day-of-period index for alignment in overlay mode */
+    __periodDayIndex: number;
+}
+
 /**
  * Compiled cube with execution function
  */
@@ -328,6 +473,100 @@ export declare function createPostgresExecutor(db: DrizzleDatabase, schema?: any
  */
 export declare function createSQLiteExecutor(db: DrizzleDatabase, schema?: any): SQLiteExecutor;
 
+/**
+ * CTEBuilder handles the construction of Common Table Expressions
+ * for pre-aggregation in hasMany relationship queries.
+ *
+ * This enables efficient aggregation of "many" side data before joining,
+ * preventing the Cartesian product explosion that would occur with direct JOINs.
+ */
+export declare class CTEBuilder {
+    private queryBuilder;
+    constructor(queryBuilder: DrizzleSqlBuilder);
+    /**
+     * Build pre-aggregation CTE for hasMany relationships
+     *
+     * Creates a CTE that:
+     * 1. Selects join keys and aggregated measures
+     * 2. Applies security context filtering
+     * 3. Groups by join keys and requested dimensions
+     * 4. Handles propagating filters from related cubes
+     * 5. Handles multi-hop join paths by absorbing intermediate tables (fan-out prevention)
+     */
+    buildPreAggregationCTE(cteInfo: CTEInfo, query: SemanticQuery, context: QueryContext, queryPlan: PhysicalQueryPlan, preBuiltFilterMap?: Map<string, SQL[]>): any;
+    /**
+     * Build join condition for CTE
+     *
+     * Creates the ON clause for joining a CTE to the main query.
+     * Uses stored column objects for type-safe joins.
+     *
+     * For multi-hop paths with intermediate joins:
+     * - The CTE includes columns from intermediate tables
+     * - The join condition uses the intermediate's primary-connected column
+     * - Example: departments.id = employeeteams_agg.department_id (not employee_id!)
+     */
+    buildCTEJoinCondition(joinCube: PhysicalQueryPlan['joinCubes'][0], cteAlias: string, queryPlan: PhysicalQueryPlan): SQL;
+    /**
+     * Resolve source-side join expression for CTE joins.
+     *
+     * When two cubes are both materialized as CTEs in the same query, join keys can
+     * still point to the original table column object (e.g. departments.id). In that
+     * case the table is no longer present in FROM/JOIN, so rewrite to the upstream CTE
+     * alias column (e.g. departments_agg.id).
+     */
+    private resolveCTEJoinSourceColumn;
+    /**
+     * Build a subquery filter for propagating filters from related cubes.
+     *
+     * This generates: cteCube.FK IN (SELECT sourceCube.PK FROM sourceCube WHERE filters...)
+     *
+     * Example: For Productivity CTE with Employees.createdAt filter:
+     * employee_id IN (SELECT id FROM employees WHERE organisation_id = $1 AND created_at >= $date)
+     *
+     * For composite keys, uses EXISTS instead of IN for better database compatibility:
+     * EXISTS (SELECT 1 FROM source WHERE source.pk1 = cte.fk1 AND source.pk2 = cte.fk2 AND <filters>)
+     */
+    buildPropagatingFilterSubquery(propFilter: PropagatingFilter, context: QueryContext): SQL | null;
+}
+
+/**
+ * CTE information type extracted from runtime physical plan context
+ */
+declare type CTEInfo = NonNullable<PhysicalQueryPlan['preAggregationCTEs']>[0];
+
+/**
+ * CTE pre-aggregation node.
+ * Represents a WITH clause that pre-aggregates a hasMany cube
+ * to prevent fan-out in the outer query.
+ */
+export declare interface CTEPreAggregate extends LogicalNodeBase {
+    readonly type: 'ctePreAggregate';
+    /** The cube being pre-aggregated */
+    cube: CubeRef;
+    /** Table alias for the cube in the main query */
+    alias: string;
+    /** CTE alias (WITH clause name) */
+    cteAlias: string;
+    /** Keys connecting CTE back to the main query */
+    joinKeys: JoinKeyInfo[];
+    /** Measure names included in this CTE */
+    measures: string[];
+    /** Cross-cube filter propagation */
+    propagatingFilters?: PropagatingFilter[];
+    /** Downstream join keys for transitive joins through this CTE */
+    downstreamJoinKeys?: DownstreamJoinKeyInfo[];
+    /** Intermediate joins absorbed into this CTE for fan-out prevention */
+    intermediateJoins?: IntermediateJoinInfo[];
+    /** CTE type (currently only 'aggregate') */
+    cteType: 'aggregate';
+    /**
+     * Reason for creating this CTE:
+     * - 'hasMany': Direct hasMany target — outer query uses SUM
+     * - 'fanOutPrevention': Affected by hasMany elsewhere — outer query uses MAX
+     */
+    cteReason: 'hasMany' | 'fanOutPrevention';
+}
+
 /**
  * Pre-aggregation CTE analysis
  */
@@ -339,7 +578,7 @@ export declare type CTEReason = 'hasMany' | 'fanOutPrevention';
 /**
  * Cube definition focused on Drizzle query building
  */
-declare interface Cube {
+export declare interface Cube {
     name: string;
     title?: string;
     description?: string;
@@ -375,8 +614,6 @@ declare interface Cube {
     /** Additional metadata */
     meta?: Record<string, any>;
 }
-export { Cube }
-export { Cube as SemanticCube }
 
 /**
  * Helper type for creating type-safe cubes
@@ -432,7 +669,7 @@ export declare interface CubeDiscoveryResult {
 /**
  * Type-safe cube join definition with lazy loading support
  */
-declare interface CubeJoin {
+export declare interface CubeJoin {
     /** Target cube reference - lazy loaded to avoid circular dependencies */
     targetCube: Cube | (() => Cube);
     /** Semantic relationship - determines join behavior */
@@ -479,8 +716,6 @@ declare interface CubeJoin {
         securitySql?: (securityContext: SecurityContext) => SQL | SQL[];
     };
 }
-export { CubeJoin }
-export { CubeJoin as SemanticJoin }
 
 /**
  * Cube metadata for API responses
@@ -507,6 +742,14 @@ export declare interface CubeMetadata {
     meta?: Record<string, any>;
 }
 
+/** Reference to a registered cube */
+export declare interface CubeRef {
+    /** Cube name (e.g. 'Employees') */
+    name: string;
+    /** Resolved cube object */
+    cube: Cube;
+}
+
 /**
  * Relationship types supported by cube joins
  */
@@ -749,7 +992,7 @@ export declare function defineCube(name: string, definition: Omit<Cube, 'name'>)
 /**
  * Dimension definition
  */
-declare interface Dimension {
+export declare interface Dimension {
     name: string;
     title?: string;
     description?: string;
@@ -778,8 +1021,6 @@ declare interface Dimension {
      */
     granularities?: TimeGranularity[];
 }
-export { Dimension }
-export { Dimension as SemanticDimension }
 
 export declare interface DimensionAnnotation {
     title: string;
@@ -813,6 +1054,16 @@ export declare interface DimensionMetadata {
     granularities?: TimeGranularity[];
 }
 
+/** Reference to a dimension on a specific cube */
+export declare interface DimensionRef {
+    /** Fully qualified name: CubeName.dimensionName */
+    name: string;
+    /** Cube that owns this dimension */
+    cube: CubeRef;
+    /** Local dimension name (without cube prefix) */
+    localName: string;
+}
+
 export declare type DimensionType = 'string' | 'number' | 'time' | 'boolean';
 
 /**
@@ -880,6 +1131,156 @@ export declare interface DrizzleDatabase {
     schema?: unknown;
 }
 
+/**
+ * Converts optimised logical plans into runtime physical query plans,
+ * then builds executable Drizzle queries.
+ */
+export declare class DrizzlePlanBuilder {
+    private readonly queryBuilder;
+    private readonly cteBuilder;
+    private readonly databaseAdapter;
+    constructor(queryBuilder: DrizzleSqlBuilder, cteBuilder: CTEBuilder, databaseAdapter: DatabaseAdapter);
+    /**
+     * Build runtime physical context from an optimised logical plan.
+     * This is the physical-builder input for SQL generation.
+     */
+    derivePhysicalPlanContext(plan: QueryNode): PhysicalQueryPlan;
+    private derivePhysicalPlanContextFromMultiFact;
+    private derivePhysicalPlanContextFromFullKeyAggregate;
+    private toSemanticQuery;
+    private resolvePhysicalSimpleSource;
+    private resolvePhysicalSimpleSourceFromKeysDedup;
+    private resolveKeysDeduplicationMeta;
+    /**
+     * Build unified query that works for both single and multi-cube queries.
+     */
+    build(queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext): any;
+    private tryBuildKeysDeduplicationQuery;
+    private tryBuildMultiFactMergeQuery;
+    private buildMultiFactUnionKeysFallbackQuery;
+    private buildSharedKeySelection;
+    private selectRuntimeMergeStrategy;
+    private supportsFullOuterJoin;
+    private coalesceQualifiedColumn;
+    private canExecuteKeysDeduplication;
+    private queryContainsMeasureFilter;
+    private getPrimaryKeyDimensions;
+    /**
+     * Build type-specific outer aggregation for keys deduplication.
+     * Each measure type needs different re-aggregation in the outer query:
+     * - sum/count/number: SUM (re-combine additive values)
+     * - min: MIN (preserve minimum across groups)
+     * - max: MAX (preserve maximum across groups)
+     * - avg: SUM(sums) / NULLIF(SUM(counts), 0) (weighted average from decomposed parts)
+     */
+    private buildKeysOuterAggregation;
+    private applyJoinByType;
+}
+
+export declare class DrizzleSqlBuilder {
+    private dateTimeBuilder;
+    private filterBuilder;
+    private groupByBuilder;
+    private measureBuilder;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Build resolvedMeasures map for a set of measures
+     * Delegates to MeasureBuilder
+     */
+    buildResolvedMeasures(measureNames: string[], cubeMap: Map<string, Cube>, context: QueryContext, customMeasureBuilder?: (measureName: string, measure: any, cube: Cube) => SQL): ResolvedMeasures;
+    /**
+     * Build dynamic selections for measures, dimensions, and time dimensions
+     * Works for both single and multi-cube queries
+     * Handles calculated measures with dependency resolution
+     */
+    buildSelections(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext): Record<string, SQL | AnyColumn>;
+    /**
+     * Build calculated measure expression by substituting {member} references
+     * Delegates to MeasureBuilder
+     */
+    buildCalculatedMeasure(measure: any, cube: Cube, allCubes: Map<string, Cube>, resolvedMeasures: ResolvedMeasures, context: QueryContext): SQL;
+    /**
+     * Build resolved measures map for a calculated measure from CTE columns
+     * Delegates to MeasureBuilder
+     */
+    buildCTECalculatedMeasure(measure: any, cube: Cube, cteInfo: {
+        cteAlias: string;
+        measures: string[];
+        cube: Cube;
+    }, allCubes: Map<string, Cube>, context: QueryContext): SQL;
+    /**
+     * Build measure expression for HAVING clause, handling CTE references correctly
+     * Delegates to MeasureBuilder
+     */
+    private buildHavingMeasureExpression;
+    /**
+     * Build measure expression with aggregation and filters
+     * Delegates to MeasureBuilder
+     */
+    buildMeasureExpression(measure: any, context: QueryContext, cube?: Cube): SQL;
+    /**
+     * Build time dimension expression with granularity using database adapter
+     * Delegates to DateTimeBuilder
+     */
+    buildTimeDimensionExpression(dimensionSql: any, granularity: string | undefined, context: QueryContext): SQL;
+    /**
+     * Build WHERE conditions from semantic query filters (dimensions only)
+     * Works for both single and multi-cube queries
+     * @param preBuiltFilters - Optional map of cube name to pre-built filter SQL for parameter deduplication
+     */
+    buildWhereConditions(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: PhysicalQueryPlan, preBuiltFilters?: Map<string, SQL[]>): SQL[];
+    /**
+     * Build HAVING conditions from semantic query filters (measures only)
+     * Works for both single and multi-cube queries
+     */
+    buildHavingConditions(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: PhysicalQueryPlan): SQL[];
+    /**
+     * Process a single filter (basic or logical)
+     * @param filterType - 'where' for dimension filters, 'having' for measure filters
+     */
+    private processFilter;
+    /**
+     * Build filter condition using Drizzle operators
+     * Delegates to FilterBuilder
+     */
+    private buildFilterCondition;
+    /**
+     * Build date range condition for time dimensions
+     * Delegates to DateTimeBuilder
+     */
+    buildDateRangeCondition(fieldExpr: AnyColumn | SQL, dateRange: string | string[]): SQL | null;
+    /**
+     * Build GROUP BY fields from dimensions and time dimensions
+     * Delegates to GroupByBuilder
+     */
+    buildGroupByFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: any): (SQL | AnyColumn)[];
+    /**
+     * Build ORDER BY clause with automatic time dimension sorting
+     */
+    buildOrderBy(query: SemanticQuery, selectedFields?: string[]): SQL[];
+    /**
+     * Collect numeric field names (measures + numeric dimensions) for type conversion
+     * Works for both single and multi-cube queries
+     */
+    collectNumericFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery): string[];
+    /**
+     * Apply LIMIT and OFFSET to a query with validation
+     * If offset is provided without limit, add a reasonable default limit
+     */
+    applyLimitAndOffset<T>(query: T, semanticQuery: SemanticQuery): T;
+    /**
+     * Public wrapper for buildFilterCondition - used by executor for cache preloading
+     * This allows pre-building filter SQL before query construction
+     */
+    buildFilterConditionPublic(fieldExpr: AnyColumn | SQL, operator: FilterOperator, values: any[], field?: any, dateRange?: string | string[]): SQL | null;
+    /**
+     * Build a logical filter (AND/OR) - used by executor for cache preloading
+     * This handles nested filter structures and builds combined SQL
+     * Delegates to FilterBuilder
+     */
+    buildLogicalFilter(filter: Filter, cubes: Map<string, Cube>, context: QueryContext): SQL | null;
+}
+
 export declare class DuckDBExecutor extends BaseDatabaseExecutor {
     execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
     /**
@@ -1137,55 +1538,162 @@ export declare function findBestFieldMatch(metadata: CubeMetadata[], fieldName:
     type: 'measure' | 'dimension';
 } | null;
 
-/**
- * Flow query configuration for server-side execution
- * This is the configuration extracted from SemanticQuery.flow
- */
-declare interface FlowQueryConfig {
+export declare class FlowQueryBuilder {
+    private filterBuilder;
+    private dateTimeBuilder;
+    private databaseAdapter;
+    constructor(databaseAdapter: DatabaseAdapter);
     /**
-     * Binding key that identifies individual entities (e.g., userId)
-     * Can be a single string like 'Events.userId' or array for multi-cube
+     * Check if query contains flow configuration
      */
-    bindingKey: string | {
-        cube: string;
-        dimension: string;
-    }[];
+    hasFlow(query: SemanticQuery): boolean;
     /**
-     * Time dimension used for ordering events
-     * Can be a single string like 'Events.timestamp' or array for multi-cube
+     * Validate flow configuration
      */
-    timeDimension: string | {
-        cube: string;
-        dimension: string;
-    }[];
+    validateConfig(config: FlowQueryConfig, cubes: Map<string, Cube>): FlowValidationResult;
     /**
-     * The starting step from which we explore paths
-     * Defines the anchor point for bidirectional flow analysis
+     * Build complete flow query using Drizzle's query builder pattern
+     *
+     * Creates a series of CTEs to:
+     * 1. Find entities at the starting step
+     * 2. Walk backwards N steps to find preceding events
+     * 3. Walk forwards N steps to find following events
+     * 4. Aggregate into nodes and links for Sankey visualization
      */
-    startingStep: {
-        /** Display name for the starting step */
-        name: string;
-        /** Filter(s) that identify events for this starting step */
-        filter?: Filter | Filter[];
-    };
-    /** Number of steps to explore BEFORE the starting step (0-5) */
-    stepsBefore: number;
-    /** Number of steps to explore AFTER the starting step (0-5) */
-    stepsAfter: number;
+    buildFlowQuery(config: FlowQueryConfig, cubes: Map<string, Cube>, context: QueryContext): ReturnType<typeof context.db.select>;
     /**
-     * Event dimension that categorizes events (e.g., 'Events.eventType')
-     * This dimension's values become the node labels in the Sankey diagram
+     * Transform raw SQL result to FlowResultRow
+     * The raw result contains rows with record_type = 'node' or 'link'
      */
-    eventDimension: string;
+    transformResult(rawResult: Record<string, unknown>[]): FlowResultRow;
     /**
-     * Optional limit on the number of entities to process
-     * Useful for performance on large datasets
+     * Resolve flow configuration to SQL expressions
      */
-    entityLimit?: number;
+    private resolveFlowConfig;
     /**
-     * Output mode for flow data aggregation
-     * - 'sankey': Aggregate by (layer, event_type) - standard flow visualization where paths can converge
-     * - 'sunburst': Path-qualified nodes for hierarchical tree visualization where each path is unique
+     * Resolve the cube for flow analysis
+     */
+    private resolveCube;
+    /**
+     * Resolve binding key expression
+     */
+    private resolveBindingKey;
+    /**
+     * Resolve time dimension expression
+     */
+    private resolveTimeDimension;
+    /**
+     * Resolve event dimension expression
+     */
+    private resolveEventDimension;
+    /**
+     * Build filter conditions for the starting step
+     */
+    private buildStartingStepFilters;
+    /**
+     * Build a single filter condition
+     */
+    private buildFilterCondition;
+    /**
+     * Build the starting entities CTE
+     * Finds all entities matching the starting step filter with their start time and event type
+     * For sunburst mode, also initializes event_path with the starting event type
+     */
+    private buildStartingEntitiesCTE;
+    /**
+     * Build CTEs for steps BEFORE the starting point using LATERAL joins
+     * Uses ORDER BY ... DESC LIMIT 1 to fetch immediate predecessor via index
+     */
+    private buildBeforeCTEsLateral;
+    /**
+     * Build CTEs for steps AFTER the starting point using LATERAL joins
+     * Uses ORDER BY ... ASC LIMIT 1 to fetch immediate successor via index
+     */
+    private buildAfterCTEsLateral;
+    /**
+     * Build CTEs for steps BEFORE the starting point
+     * Each CTE finds the immediate predecessor event for entities from the previous CTE
+     *
+     * Uses ROW_NUMBER() window function to get exactly the Nth previous event
+     * For sunburst mode, accumulates event_path by prepending to previous path
+     */
+    private buildBeforeCTEsWindow;
+    /**
+     * Build CTEs for steps AFTER the starting point
+     * Each CTE finds the immediate successor event for entities from the previous CTE
+     *
+     * Uses ROW_NUMBER() window function to get exactly the Nth following event
+     * For sunburst mode, accumulates event_path by concatenating with previous path
+     */
+    private buildAfterCTEsWindow;
+    /**
+     * Build the nodes aggregation CTE
+     * Aggregates counts per (layer, event_type) combination using UNION ALL
+     * For sunburst mode, aggregates by event_path for unique tree branches
+     */
+    private buildNodesAggregationCTE;
+    /**
+     * Build the links aggregation CTE
+     * Counts transitions between adjacent layers
+     * For sunburst mode, uses event_path for unique branch identification
+     */
+    private buildLinksAggregationCTE;
+    /**
+     * Build the final result CTE
+     * Combines nodes and links into a single result set with record_type discriminator
+     */
+    private buildFinalResultCTE;
+}
+
+/**
+ * Flow query configuration for server-side execution
+ * This is the configuration extracted from SemanticQuery.flow
+ */
+declare interface FlowQueryConfig {
+    /**
+     * Binding key that identifies individual entities (e.g., userId)
+     * Can be a single string like 'Events.userId' or array for multi-cube
+     */
+    bindingKey: string | {
+        cube: string;
+        dimension: string;
+    }[];
+    /**
+     * Time dimension used for ordering events
+     * Can be a single string like 'Events.timestamp' or array for multi-cube
+     */
+    timeDimension: string | {
+        cube: string;
+        dimension: string;
+    }[];
+    /**
+     * The starting step from which we explore paths
+     * Defines the anchor point for bidirectional flow analysis
+     */
+    startingStep: {
+        /** Display name for the starting step */
+        name: string;
+        /** Filter(s) that identify events for this starting step */
+        filter?: Filter | Filter[];
+    };
+    /** Number of steps to explore BEFORE the starting step (0-5) */
+    stepsBefore: number;
+    /** Number of steps to explore AFTER the starting step (0-5) */
+    stepsAfter: number;
+    /**
+     * Event dimension that categorizes events (e.g., 'Events.eventType')
+     * This dimension's values become the node labels in the Sankey diagram
+     */
+    eventDimension: string;
+    /**
+     * Optional limit on the number of entities to process
+     * Useful for performance on large datasets
+     */
+    entityLimit?: number;
+    /**
+     * Output mode for flow data aggregation
+     * - 'sankey': Aggregate by (layer, event_type) - standard flow visualization where paths can converge
+     * - 'sunburst': Path-qualified nodes for hierarchical tree visualization where each path is unique
      * @default 'sankey'
      */
     outputMode?: 'sankey' | 'sunburst';
@@ -1198,6 +1706,24 @@ declare interface FlowQueryConfig {
     joinStrategy?: 'auto' | 'lateral' | 'window';
 }
 
+/**
+ * Flow result row returned from query execution
+ * Contains the complete Sankey diagram data
+ */
+declare interface FlowResultRow {
+    nodes: SankeyNode[];
+    links: SankeyLink[];
+}
+
+/**
+ * Flow validation result
+ */
+declare interface FlowValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+
 /**
  * FNV-1a hash - fast, non-cryptographic hash function
  * Returns hex string for cache key readability
@@ -1235,6 +1761,18 @@ export declare function formatExistingIndexes(indexes: Array<{
     is_primary?: boolean;
 }>): string;
 
+/**
+ * Full key aggregate: merges results from multiple subqueries
+ * that share the same dimension key set.
+ */
+declare interface FullKeyAggregate extends LogicalNodeBase {
+    readonly type: 'fullKeyAggregate';
+    /** Subqueries whose results will be merged */
+    subqueries: LogicalNode[];
+    /** Shared dimensions used as the merge key */
+    dimensions: DimensionRef[];
+}
+
 /**
  * Binding key mapping for multi-cube funnels
  * Maps the user/entity identifier across different cubes
@@ -1254,6 +1792,138 @@ export declare interface FunnelCapabilities {
     supportsIntervalArithmetic: boolean;
 }
 
+export declare class FunnelQueryBuilder {
+    private databaseAdapter;
+    private filterBuilder;
+    private dateTimeBuilder;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Check if query contains funnel configuration
+     */
+    hasFunnel(query: SemanticQuery): boolean;
+    /**
+     * Validate funnel configuration
+     */
+    validateConfig(config: FunnelQueryConfig, cubes: Map<string, Cube>): {
+        isValid: boolean;
+        errors: string[];
+    };
+    /**
+     * Build complete funnel query using Drizzle's query builder pattern
+     *
+     * Uses the industry-standard "sequential CTEs" pattern where each step
+     * joins to the previous step CTE. This automatically enforces funnel
+     * constraints (monotonically decreasing counts).
+     *
+     * Returns a Drizzle query builder that supports .toSQL() for dry-run
+     * and can be executed directly for results.
+     */
+    buildFunnelQuery(config: FunnelQueryConfig, cubes: Map<string, Cube>, context: QueryContext): ReturnType<typeof context.db.select>;
+    /**
+     * Transform raw SQL result to FunnelResultRow[]
+     */
+    transformResult(rawResult: Record<string, unknown>[], config: FunnelQueryConfig): FunnelResultRow[];
+    /**
+     * Extract cube names referenced in step filters
+     */
+    private extractFilterCubeNames;
+    /**
+     * Resolve steps with their cube, SQL expressions, and filter conditions
+     */
+    private resolveSteps;
+    /**
+     * Resolve the cube for a step
+     */
+    private resolveCubeForStep;
+    /**
+     * Resolve binding key expression for a cube
+     */
+    private resolveBindingKey;
+    /**
+     * Resolve time dimension expression for a cube
+     */
+    private resolveTimeDimension;
+    /**
+     * Build filter conditions for a step
+     * @param step - The funnel step
+     * @param baseCube - The step's primary cube
+     * @param cubes - All cubes available for cross-cube filtering
+     * @param context - Query context with security context
+     */
+    private buildStepFilters;
+    /**
+     * Build a single filter condition
+     * @param filter - The filter to build
+     * @param baseCube - The step's primary cube
+     * @param cubes - All cubes available for cross-cube filtering
+     * @param context - Query context with security context
+     */
+    private buildFilterCondition;
+    /**
+     * Build CTE for a single step using Drizzle's $with() pattern
+     *
+     * For step 0 (entry point): queries raw data directly
+     * For subsequent steps: joins to the previous step CTE to enforce sequential progression
+     *
+     * This implements the industry-standard "sequential CTEs" pattern where each step
+     * only includes binding_keys that successfully completed the previous step.
+     *
+     * @param step - The resolved step configuration
+     * @param context - Query context with security context
+     * @param previousStepCTE - Reference to the previous step's CTE (undefined for step 0)
+     */
+    private buildStepCTE;
+    /**
+     * Build CTE for the first step (step 0) - entry point
+     *
+     * Queries raw data directly with security context and step filters.
+     * Gets the first occurrence per binding key.
+     */
+    private buildFirstStepCTE;
+    /**
+     * Build CTE for subsequent steps (step 1+) - joins to previous step
+     *
+     * This is the key to the sequential funnel pattern:
+     * - INNER JOINs to the previous step CTE (only includes binding_keys that completed previous step)
+     * - Applies temporal constraints (must occur after previous step)
+     * - Applies step-specific filters and time-to-convert windows
+     *
+     * This automatically ensures monotonically decreasing counts.
+     */
+    private buildSubsequentStepCTE;
+    /**
+     * Helper to add cross-cube JOINs to a step query
+     * Extracted to avoid duplication between first and subsequent step methods
+     */
+    private addCrossJoinsToQuery;
+    /**
+     * Build funnel results CTE that joins all step times for time metric calculation
+     *
+     * With the sequential CTE pattern, each step CTE already contains only the
+     * binding_keys that successfully completed that step. This CTE simply joins
+     * them together to enable time difference calculations.
+     *
+     * No CASE expressions needed - the temporal filtering is already done in each step CTE.
+     */
+    private buildFunnelResultsCTE;
+    /**
+     * Build aggregation CTE with counts and optional time metrics
+     *
+     * OPTIMIZATION: Uses single-pass aggregation over funnel_joined CTE instead of
+     * multiple scalar subqueries. This reduces table scans from 13+ to 1 for a typical
+     * 3-step funnel with time metrics.
+     *
+     * - Step counts: COUNT(*) for step_0, COUNT(step_N_time) for subsequent steps
+     * - Time metrics: Uses database-specific conditional aggregation (FILTER clause for
+     *   PostgreSQL, CASE WHEN for MySQL/SQLite)
+     * - Percentiles: Still use subqueries since PERCENTILE_CONT with FILTER is non-standard
+     *
+     * Important: All SQL fields must have explicit aliases via .as() for Drizzle
+     * to properly reference them when selecting from the CTE
+     */
+    private buildAggregationCTE;
+}
+
 /**
  * Funnel query configuration
  */
@@ -1414,6 +2084,15 @@ export declare interface HierarchyMetadata {
     levels: string[];
 }
 
+/**
+ * No-op optimiser — returns the plan unchanged.
+ * Used as the default in Phase 1 and as a baseline for testing.
+ */
+export declare class IdentityOptimiser implements PlanOptimiser {
+    readonly name = "identity";
+    optimise(plan: LogicalNode): LogicalNode;
+}
+
 /**
  * Information about a database index
  */
@@ -1448,6 +2127,19 @@ export declare interface IntermediateJoinInfo {
     cteJoinColumn: AnyColumn;
 }
 
+/**
+ * Internal representation of a join path step
+ * Used during path finding - simpler than the public JoinPathStep analysis type
+ */
+declare interface InternalJoinPathStep {
+    /** Source cube name */
+    fromCube: string;
+    /** Target cube name */
+    toCube: string;
+    /** The join definition from the source cube */
+    joinDef: CubeJoin;
+}
+
 /**
  * Type guard for multi-cube binding key
  */
@@ -1480,6 +2172,29 @@ export declare function isRetentionQuery(query: unknown): query is {
     retention: RetentionQueryConfig;
 };
 
+/**
+ * Planned join entry used by runtime physical builders.
+ */
+export declare interface JoinCubePlanEntry {
+    cube: Cube;
+    alias: string;
+    joinType: 'inner' | 'left' | 'right' | 'full';
+    joinCondition: SQL;
+    /** Relationship type from the join definition that produced this entry */
+    relationship?: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    /** Junction table information for belongsToMany relationships */
+    junctionTable?: {
+        table: Table;
+        alias: string;
+        joinType: 'inner' | 'left' | 'right' | 'full';
+        joinCondition: SQL;
+        /** Optional security SQL function to apply to junction table */
+        securitySql?: (securityContext: SecurityContext) => SQL | SQL[];
+        /** Source cube name for the belongsToMany relationship (needed for CTE rewriting) */
+        sourceCubeName?: string;
+    };
+}
+
 /**
  * Join key information for CTE joins
  * Describes how a CTE should be joined to the main query
@@ -1521,6 +2236,114 @@ export declare interface JoinPathAnalysis {
     error?: string;
     /** Cubes that were visited during BFS search */
     visitedCubes?: string[];
+    /** Path selection decision and scoring details (when preferred routing is used) */
+    selection?: {
+        strategy: 'shortest' | 'preferred' | 'fallbackShortest';
+        preferredCubes?: string[];
+        selectedRank?: number;
+        selectedScore?: number;
+        candidates?: Array<{
+            rank: number;
+            score: number;
+            usesPreferredJoin: boolean;
+            preferredCubesInPath: number;
+            usesProcessed: boolean;
+            scoreBreakdown: {
+                preferredJoinBonus: number;
+                preferredCubeBonus: number;
+                lengthPenalty: number;
+            };
+            path: JoinPathStep[];
+        }>;
+    };
+}
+
+/**
+ * Resolves join paths between cubes and manages connectivity caching
+ */
+export declare class JoinPathResolver {
+    private cubes;
+    private connectivityCache;
+    /**
+     * @param cubes Map of cube name to cube definition
+     */
+    constructor(cubes: Map<string, Cube>);
+    /**
+     * Find the shortest join path from source cube to target cube
+     * Uses BFS algorithm for optimal path discovery
+     *
+     * @param fromCube Source cube name
+     * @param toCube Target cube name
+     * @param alreadyProcessed Set of cubes to exclude from path finding
+     * @returns Array of join steps or null if no path exists
+     */
+    findPath(fromCube: string, toCube: string, alreadyProcessed?: Set<string>): InternalJoinPathStep[] | null;
+    /**
+     * Find path that prefers going through specified cubes when possible
+     * Used when certain cubes have measures in the query - ensures joins go through
+     * the semantically correct path (e.g., through junction tables when their measures are used)
+     *
+     * IMPORTANT: This method allows paths to go THROUGH already-processed cubes (as intermediate
+     * steps) but won't return them as new cubes to add. This is crucial for preferring paths
+     * through cubes that have measures (like junction tables).
+     *
+     * Path scoring priority (highest to lowest):
+     * 1. Paths using joins with `preferredFor` that includes the target cube (score +10)
+     * 2. Paths going through cubes with measures in the query (score +1 per cube)
+     * 3. Paths reusing already-processed cubes
+     * 4. Shorter paths
+     *
+     * @param fromCube Source cube name
+     * @param toCube Target cube name
+     * @param preferredCubes Set of cube names to prefer in the path (usually cubes with measures)
+     * @param alreadyProcessed Set of cubes already in the join plan (can be used as intermediates)
+     * @returns Array of join steps or null if no path exists
+     */
+    findPathPreferring(fromCube: string, toCube: string, preferredCubes: Set<string>, alreadyProcessed?: Set<string>): InternalJoinPathStep[] | null;
+    /**
+     * Find preferred path with candidate scoring telemetry.
+     * Used by analysis/debug panels to explain planner decisions.
+     */
+    findPathPreferringDetailed(fromCube: string, toCube: string, preferredCubes: Set<string>, alreadyProcessed?: Set<string>): PreferredPathSelection;
+    /**
+     * Find all possible paths between two cubes (up to maxDepth)
+     * Used by findPathPreferring to evaluate multiple paths
+     *
+     * @param fromCube Source cube name
+     * @param toCube Target cube name
+     * @param alreadyProcessed Set of cubes to exclude from path finding
+     * @param maxDepth Maximum path length to search (default 4 to avoid explosion)
+     * @returns Array of all valid paths
+     */
+    private findAllPaths;
+    /**
+     * Check if a cube can reach all other cubes in the list via joins
+     *
+     * @param fromCube Starting cube name
+     * @param allCubes List of all cubes that must be reachable
+     * @returns true if all cubes are reachable
+     */
+    canReachAll(fromCube: string, allCubes: string[]): boolean;
+    /**
+     * Build SQL join condition from join definition
+     *
+     * @param joinDef The cube join definition
+     * @param sourceAlias Optional alias for source table (null uses actual column)
+     * @param targetAlias Optional alias for target table (null uses actual column)
+     * @returns SQL condition for the join
+     */
+    buildJoinCondition(joinDef: CubeJoin, sourceAlias: string | null, targetAlias: string | null): SQL;
+    /**
+     * Get all reachable cubes from a starting cube
+     * Useful for analyzing cube connectivity
+     *
+     * @param fromCube Starting cube name
+     * @returns Set of all reachable cube names
+     */
+    getReachableCubes(fromCube: string): Set<string>;
+    private getCacheKey;
+    private getFromCache;
+    private setInCache;
 }
 
 /**
@@ -1548,41 +2371,382 @@ export declare interface JoinPathStep {
     };
 }
 
+declare interface JoinRef {
+    /** Target cube being joined */
+    target: CubeRef;
+    /** Table alias in the generated SQL */
+    alias: string;
+    /** SQL join type */
+    joinType: 'inner' | 'left' | 'right' | 'full';
+    /** Drizzle SQL join condition (pre-built by the planner) */
+    joinCondition: SQL;
+    /** Relationship type from the join definition */
+    relationship?: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    /** Junction table for belongsToMany relationships */
+    junctionTable?: {
+        table: Table;
+        alias: string;
+        joinType: 'inner' | 'left' | 'right' | 'full';
+        joinCondition: SQL;
+        securitySql?: (securityContext: SecurityContext) => SQL | SQL[];
+        sourceCubeName?: string;
+    };
+}
+
 export declare type JoinType = 'left' | 'right' | 'inner' | 'full';
 
+/**
+ * Keys-based deduplication for multiplied measures.
+ */
+declare interface KeysDeduplication extends LogicalNodeBase {
+    readonly type: 'keysDeduplication';
+    /** SELECT DISTINCT PKs + dims */
+    keysSource: LogicalNode;
+    /** Aggregated measures source */
+    measureSource: LogicalNode;
+    /** Primary key columns to join on */
+    joinOn: ColumnRef[];
+    /** Measure names NOT from the multiplied cube (pre-aggregated in keys CTE) */
+    regularMeasures?: string[];
+}
+
 export declare interface LogicalFilter {
     and?: Filter[];
     or?: Filter[];
 }
 
+export declare type LogicalNode = QueryNode | SimpleSource | FullKeyAggregate | CTEPreAggregate | KeysDeduplication | MultiFactMerge;
+
+/** Base interface shared by all logical plan nodes */
+declare interface LogicalNodeBase {
+    readonly type: LogicalNodeType;
+    readonly schema: LogicalSchema;
+}
+
+/** Discriminated union tag for all node types */
+declare type LogicalNodeType = 'query' | 'simpleSource' | 'fullKeyAggregate' | 'ctePreAggregate' | 'keysDeduplication' | 'multiFactMerge';
+
+export declare class LogicalPlanBuilder {
+    private readonly queryPlanner;
+    constructor(queryPlanner: LogicalPlanner);
+    /**
+     * Build a logical plan from a semantic query.
+     */
+    plan(cubes: Map<string, Cube>, query: SemanticQuery, ctx: QueryContext): QueryNode;
+    /**
+     * Build a logical plan and an explicit decision trace for dry-run/explain.
+     * The analysis is produced from the same phase outputs used to build the plan.
+     */
+    planWithAnalysis(cubes: Map<string, Cube>, query: SemanticQuery, ctx: QueryContext): LogicalPlanWithAnalysis;
+    private buildSourceFromPhases;
+    private buildSimpleSourceFromPhases;
+    /**
+     * Detect and build multi-fact merge for star-schema style queries where:
+     * - measures come from 2+ cubes
+     * - all grouping dimensions/timeDimensions come from one shared dimension cube
+     * - each measure cube directly belongsTo/hasOne that shared cube
+     */
+    private tryBuildMultiFactMergeSource;
+    private hasDirectJoinToSharedDimension;
+    private buildGroupQueryNode;
+    private projectFiltersToAllowedCubes;
+    private projectFilterNodeToAllowedCubes;
+    private classifyMeasuresForStrategy;
+    private selectMeasureStrategy;
+    /**
+     * Initial execution scope for keys deduplication:
+     * - exactly one multiplied cube
+     * - all query measures belong to that cube
+     * - only additive measure types currently handled by the physical keys path
+     * - no measure filters (HAVING) in the query
+     */
+    private isKeysDeduplicationExecutionSupported;
+    private queryHasMeasureFilter;
+    private buildKeysDeduplicationSource;
+    private isDeduplicationSafeMeasure;
+    private getPrimaryKeyColumns;
+    private deduplicateColumnRefs;
+    private buildQueryNode;
+    private buildPreAggregationAnalysis;
+    private buildMeasureRefs;
+    private buildDimensionRefs;
+    private buildTimeDimensionRefs;
+    private buildOrderByRefs;
+    private toCubeRef;
+    private buildCTESchema;
+}
+
 /**
- * Measure definition
+ * Pre-aggregation plan for handling hasMany relationships
  */
-declare interface Measure {
-    name: string;
-    title?: string;
-    description?: string;
+export declare class LogicalPlanner {
+    private resolverCache;
     /**
-     * Alternative names for this measure
-     * Used by AI agents for natural language matching
-     * @example ['revenue', 'sales', 'income'] for a totalRevenue measure
+     * Get or create a JoinPathResolver for the given cubes map
      */
-    synonyms?: string[];
-    type: MeasureType;
+    private getResolver;
     /**
-     * Column to aggregate or SQL expression
-     * Optional for calculated measures (type: 'calculated') which use calculatedSql instead
+     * Analyze a semantic query to determine which cubes are involved
      */
-    sql?: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL);
-    /** Display format */
-    format?: string;
-    /** Whether to show in UI */
-    shown?: boolean;
-    /** Filters applied to this measure */
-    filters?: Array<(ctx: QueryContext) => SQL>;
-    /** Rolling window configuration */
-    rollingWindow?: {
-        trailing?: string;
+    analyzeCubeUsage(query: SemanticQuery): Set<string>;
+    /**
+     * Build query-level path hints (Cube-style) from all query members:
+     * measures, dimensions, time dimensions, filters, and order-by.
+     * These hints guide path selection toward the semantic query grain.
+     */
+    private collectPathHintCubes;
+    /**
+     * Recursively extract cube names from filters (handles logical filters)
+     */
+    private extractCubeNamesFromFilter;
+    /**
+     * Extract measures referenced in filters (for CTE inclusion)
+     */
+    private extractMeasuresFromFilters;
+    /**
+     * Recursively extract measures from filters for a specific cube
+     * Only includes filter members that are actually measures (not dimensions)
+     */
+    private extractMeasuresFromFilter;
+    /**
+     * Choose the primary cube based on query analysis
+     * Uses a consistent strategy to avoid measure order dependencies
+     *
+     * Delegates to analyzePrimaryCubeSelection() for the actual logic,
+     * ensuring a single source of truth for primary cube selection.
+     */
+    choosePrimaryCube(cubeNames: string[], query: SemanticQuery, cubes?: Map<string, Cube>): string;
+    /**
+     * Analyze primary cube selection with candidate details.
+     * Exposed for LogicalPlanBuilder so dry-run/analyze can report
+     * exactly which selection rule was used.
+     */
+    analyzePrimaryCube(cubeNames: string[], query: SemanticQuery, cubes: Map<string, Cube>): PrimaryCubeAnalysis;
+    /**
+     * Analyze join path for a specific target cube.
+     * Exposed for LogicalPlanBuilder to provide join decision trace.
+     */
+    analyzeJoinPathForTarget(cubes: Map<string, Cube>, fromCube: string, toCube: string, query?: SemanticQuery): JoinPathAnalysis;
+    /**
+     * Build join plan for a known primary cube.
+     * Exposed for LogicalPlanBuilder so logical planning can compose
+     * planner phases directly.
+     */
+    buildJoinPlanForPrimary(cubes: Map<string, Cube>, primaryCube: Cube, cubeNames: string[], ctx: QueryContext, query: SemanticQuery): PhysicalQueryPlan['joinCubes'];
+    /**
+     * Build pre-aggregation CTE plan from a primary cube and join plan.
+     * Exposed for LogicalPlanBuilder phase composition.
+     */
+    buildPreAggregationCTEs(cubes: Map<string, Cube>, primaryCube: Cube, joinCubes: PhysicalQueryPlan['joinCubes'], query: SemanticQuery, ctx: QueryContext): PhysicalQueryPlan['preAggregationCTEs'];
+    /**
+     * Generate query warnings from pre-aggregation analysis.
+     * Exposed for LogicalPlanBuilder phase composition.
+     */
+    buildWarnings(query: SemanticQuery, preAggregationCTEs?: PhysicalQueryPlan['preAggregationCTEs']): QueryWarning[];
+    /**
+     * Build join plan for multi-cube query
+     * Supports both direct joins and transitive joins through intermediate cubes
+     *
+     * Uses query-aware path selection to prefer joining through cubes that have
+     * measures in the query (e.g., joining Teams through EmployeeTeams when
+     * EmployeeTeams.count is a measure)
+     */
+    private buildJoinPlan;
+    /**
+     * Plan pre-aggregation CTEs for hasMany relationships to prevent fan-out
+     * Note: belongsToMany relationships handle fan-out differently through their junction table structure
+     * and don't require CTEs - the two-hop join with the junction table provides natural grouping
+     *
+     * CRITICAL FAN-OUT PREVENTION LOGIC:
+     * When a query contains ANY hasMany relationship in the join graph, ALL cubes with measures
+     * that could be affected by row multiplication need CTEs. This includes:
+     *
+     * 1. Cubes with direct hasMany FROM primary (existing logic)
+     * 2. Cubes with measures that would be multiplied due to hasMany elsewhere in the query
+     *    - Example: Query has Departments.totalBudget + Productivity.recordCount
+     *    - Employees hasMany → Productivity causes row multiplication
+     *    - Departments.totalBudget would be inflated without CTE pre-aggregation
+     */
+    private planPreAggregationCTEs;
+    /**
+     * Find join information TO a cube (reverse lookup)
+     * Used when the primary cube needs a CTE and we need to find how other cubes join to it
+     */
+    private findJoinInfoToCube;
+    /**
+     * Analyze the join path from primary cube to a target CTE cube.
+     * Detects if there are intermediate hasMany relationships that would cause fan-out.
+     *
+     * Returns information about:
+     * - The full join path
+     * - Whether there are hasMany relationships ON the path (not just at the end)
+     * - Which intermediate tables need to be absorbed into the CTE
+     * - The correct join key to use (from primary cube's connection point)
+     *
+     * @param cubes Map of all registered cubes
+     * @param primaryCube The primary cube (FROM clause)
+     * @param targetCubeName The CTE cube we're analyzing the path to
+     * @param ctx Query context for security filtering
+     */
+    private analyzeJoinPathToPrimary;
+    /**
+     * Compute CTE reasons from the actual join plan entries.
+     *
+     * Instead of scanning all registered cubes (which causes false positives when
+     * unrelated hasMany relationships exist), this walks only the planned joins
+     * using the `relationship` field now stored on each JoinCubePlanEntry.
+     *
+     * Algorithm:
+     * 1. Scan join plan entries for hasMany/belongsToMany relationships
+     * 2. If none found → return empty map (no CTEs needed)
+     * 3. hasMany/belongsToMany targets with measures → 'hasMany'
+     * 4. Other join cubes with measures (not hasMany source) → 'fanOutPrevention'
+     */
+    private computeCTEReasons;
+    /**
+     * Find join information for a cube from any cube in the query
+     * This extends findHasManyJoinDef to work with any relationship type
+     * and to search from any source cube, not just the primary
+     */
+    private findJoinInfoForCube;
+    /**
+     * Find downstream cubes that need join keys included in the CTE.
+     *
+     * When a query has dimensions from a cube (e.g., Teams.name) and measures from
+     * a junction cube (e.g., EmployeeTeams.count), the junction CTE needs to include
+     * the join key to the dimension cube (team_id) so the dimension cube can be
+     * joined through the CTE instead of via an alternative path.
+     *
+     * @param cteCube The cube being converted to a CTE (e.g., EmployeeTeams)
+     * @param query The semantic query with dimensions and measures
+     * @param allCubes Map of all registered cubes
+     * @returns Array of downstream join key info for cubes needing join through this CTE
+     */
+    private findDownstreamJoinKeys;
+    /**
+     * Expand calculated measures to include their dependencies
+     */
+    private expandCalculatedMeasureDependencies;
+    /**
+     * Extract measure references from calculatedSql template
+     */
+    private extractDependenciesFromTemplate;
+    /**
+     * Find hasMany join definition from primary cube to target cube
+     */
+    private findHasManyJoinDef;
+    /**
+     * Find filters that need to propagate from related cubes to a CTE cube.
+     * When cube A has filters and a hasMany relationship to cube B (the CTE cube),
+     * A's filters should propagate into B's CTE via a subquery.
+     *
+     * Example: Employees.createdAt filter should propagate to Productivity CTE
+     * via: employee_id IN (SELECT id FROM employees WHERE created_at >= $date)
+     */
+    private findPropagatingFilters;
+    /**
+     * Extract cube names from filters into a Set (helper for findPropagatingFilters)
+     */
+    private extractFilterCubeNamesToSet;
+    /**
+     * Extract filters for a specific cube from the filter array
+     *
+     * Logic for preserving filter semantics:
+     * - AND: Safe to extract only matching branches (AND of fewer conditions is more permissive)
+     * - OR: Must include ALL branches or skip entirely (partial OR changes semantics)
+     *       If any branch belongs to another cube, skip the entire OR to be safe
+     *       since we can't evaluate the other cube's conditions
+     */
+    private extractFiltersForCube;
+    /**
+     * Check if all simple filters in a filter array belong to the specified cube
+     * Recursively checks nested AND/OR filters
+     */
+    private allFiltersFromCube;
+    /**
+     * Extract time dimension date range filters as regular filters for a specific cube
+     */
+    private extractTimeDimensionFiltersForCube;
+    /**
+     * Analyze why a particular cube was chosen as primary
+     */
+    private analyzePrimaryCubeSelection;
+    /**
+     * Analyze the join path between two cubes with detailed step information
+     *
+     * Uses JoinPathResolver.findPath() for the actual path finding,
+     * then converts the result to human-readable analysis format.
+     */
+    private analyzeJoinPath;
+    private convertInternalPathToJoinPathSteps;
+    private buildJoinPathSelectionAnalysis;
+    private mapPreferredCandidate;
+    /**
+     * Generate warnings for query edge cases that users should be aware of.
+     * Currently detects:
+     * - FAN_OUT_NO_DIMENSIONS: Query has hasMany CTEs but no dimensions to group by
+     *
+     * Note: AVG measures in hasMany CTEs can produce mathematically imprecise results
+     * (average of averages vs weighted average), but this warning was removed as it
+     * fired too aggressively. The issue only occurs when the outer grouping is coarser
+     * than the CTE grouping, which is rare in practice. The limitation is documented
+     * in executor.ts comments.
+     */
+    private generateWarnings;
+    /**
+     * Detect when a query has measures from multiple cubes with hasMany relationships
+     * but no dimensions to provide grouping context.
+     *
+     * This is an edge case where:
+     * - Query has measures from 2+ cubes
+     * - At least one CTE exists (indicating hasMany relationship)
+     * - Query has NO dimensions AND NO time dimensions with granularity
+     *
+     * The SQL is technically correct (CTEs with GROUP BY on join keys), but users
+     * may be confused by the aggregated results without visible grouping.
+     */
+    private checkFanOutNoDimensions;
+}
+
+export declare interface LogicalPlanWithAnalysis {
+    plan: QueryNode;
+    analysis: QueryAnalysis;
+}
+
+declare interface LogicalSchema {
+    measures: MeasureRef[];
+    dimensions: DimensionRef[];
+    timeDimensions: TimeDimensionRef[];
+}
+
+/**
+ * Measure definition
+ */
+export declare interface Measure {
+    name: string;
+    title?: string;
+    description?: string;
+    /**
+     * Alternative names for this measure
+     * Used by AI agents for natural language matching
+     * @example ['revenue', 'sales', 'income'] for a totalRevenue measure
+     */
+    synonyms?: string[];
+    type: MeasureType;
+    /**
+     * Column to aggregate or SQL expression
+     * Optional for calculated measures (type: 'calculated') which use calculatedSql instead
+     */
+    sql?: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL);
+    /** Display format */
+    format?: string;
+    /** Whether to show in UI */
+    shown?: boolean;
+    /** Filters applied to this measure */
+    filters?: Array<(ctx: QueryContext) => SQL>;
+    /** Rolling window configuration */
+    rollingWindow?: {
+        trailing?: string;
         leading?: string;
         offset?: string;
     };
@@ -1677,8 +2841,6 @@ declare interface Measure {
         };
     };
 }
-export { Measure }
-export { Measure as SemanticMeasure }
 
 /**
  * Annotation interfaces for UI metadata
@@ -1690,6 +2852,18 @@ export declare interface MeasureAnnotation {
     format?: MeasureFormat;
 }
 
+/**
+ * Dependency information for a calculated measure
+ */
+declare interface MeasureDependency {
+    /** Full measure name (e.g., "Cube.measure" or "measure") */
+    measureName: string;
+    /** Referenced cube name (null if same cube) */
+    cubeName: string | null;
+    /** Referenced field name */
+    fieldName: string;
+}
+
 export declare type MeasureFormat = 'currency' | 'percent' | 'number' | 'integer';
 
 /**
@@ -1715,6 +2889,16 @@ export declare interface MeasureMetadata {
     drillMembers?: string[];
 }
 
+/** Reference to a measure on a specific cube */
+export declare interface MeasureRef {
+    /** Fully qualified name: CubeName.measureName */
+    name: string;
+    /** Cube that owns this measure */
+    cube: CubeRef;
+    /** Local measure name (without cube prefix) */
+    localName: string;
+}
+
 /**
  * Type enums and constants
  */
@@ -1836,6 +3020,20 @@ export declare interface MultiCubeQueryContext extends QueryContext {
     currentCube: Cube;
 }
 
+/**
+ * Multi-fact merge: combines independent fact subqueries
+ * that share dimensions.
+ */
+declare interface MultiFactMerge extends LogicalNodeBase {
+    readonly type: 'multiFactMerge';
+    /** Independent fact subqueries */
+    groups: LogicalNode[];
+    /** Shared dimensions for the merge */
+    sharedDimensions: DimensionRef[];
+    /** How to combine the groups */
+    mergeStrategy: 'fullJoin' | 'leftJoin' | 'innerJoin';
+}
+
 export declare type MySQLDatabase = MySql2Database<any>;
 
 export declare class MySQLExecutor extends BaseDatabaseExecutor {
@@ -1859,6 +3057,20 @@ export declare class MySQLExecutor extends BaseDatabaseExecutor {
     getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
 }
 
+/**
+ * Normalized period range with start/end dates and metadata
+ */
+declare interface NormalizedPeriod {
+    /** Start date of the period */
+    start: Date;
+    /** End date of the period */
+    end: Date;
+    /** Human-readable label for the period */
+    label: string;
+    /** Index in the comparison (0 = first/current, 1 = second/prior, etc.) */
+    index: number;
+}
+
 /**
  * Normalize query for consistent hashing
  * Sorts arrays and object keys to ensure same query = same hash
@@ -1868,6 +3080,31 @@ export declare class MySQLExecutor extends BaseDatabaseExecutor {
  */
 export declare function normalizeQuery(query: SemanticQuery): SemanticQuery;
 
+/** Context available to optimiser passes */
+export declare interface OptimiserContext {
+    /** Database engine type for engine-specific rewrites */
+    engineType: 'postgres' | 'mysql' | 'sqlite' | 'duckdb';
+}
+
+/**
+ * Runs a sequence of optimiser passes in order.
+ * Short-circuits if a pass returns a different reference (for future use).
+ */
+export declare class OptimiserPipeline implements PlanOptimiser {
+    readonly name = "pipeline";
+    private passes;
+    constructor(passes?: PlanOptimiser[]);
+    optimise(plan: LogicalNode, context: OptimiserContext): LogicalNode;
+    addPass(pass: PlanOptimiser): void;
+}
+
+/** Order-by specification */
+declare interface OrderByRef {
+    /** Fully qualified field name */
+    name: string;
+    direction: 'asc' | 'desc';
+}
+
 /**
  * Period comparison metadata for compareDateRange queries
  * Provides information about the periods being compared
@@ -1884,20 +3121,86 @@ export declare interface PeriodComparisonMetadata {
 }
 
 /**
- * Type helpers for specific database types
+ * Runtime physical-plan context used by query execution builders.
+ * This is the only runtime plan context consumed by SQL builders.
  */
-export declare type PostgresDatabase = PostgresJsDatabase<any>;
-
-export declare class PostgresExecutor extends BaseDatabaseExecutor {
-    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+export declare interface PhysicalQueryPlan {
+    /** Primary cube that drives the query */
+    primaryCube: Cube;
+    /** Additional cubes to join (empty for single-cube queries) */
+    joinCubes: JoinCubePlanEntry[];
+    /** Pre-aggregation CTEs for hasMany relationships to prevent fan-out */
+    preAggregationCTEs?: PreAggregationCTEInfo[];
     /**
-     * Convert numeric string fields to numbers (only for measure fields)
+     * Optional keys-based deduplication metadata.
+     * When present, physical builders may choose a keys+aggregate execution path.
      */
-    private convertNumericFields;
+    keysDeduplication?: {
+        multipliedCubeName: string;
+        primaryKeyDimensions: string[];
+        /** Measure names NOT from the multiplied cube (pre-aggregated in keys CTE) */
+        regularMeasures?: string[];
+    };
     /**
-     * Coerce a value to a number if it represents a numeric type
+     * Optional multi-fact merge metadata.
+     * When present, SQL builders execute independent grouped subqueries and
+     * merge them by shared dimension keys.
      */
-    private coerceToNumber;
+    multiFactMerge?: {
+        mergeStrategy: 'fullJoin' | 'leftJoin' | 'innerJoin';
+        sharedDimensions: string[];
+        groups: Array<{
+            alias: string;
+            query: SemanticQuery;
+            queryPlan: PhysicalQueryPlan;
+            measures: string[];
+        }>;
+    };
+    /** Warnings about potential query issues (e.g., fan-out without dimensions) */
+    warnings?: QueryWarning[];
+}
+
+export declare interface PlanningTrace {
+    /** Ordered decision trace */
+    steps: PlanningTraceStep[];
+}
+
+/**
+ * Structured planner trace for explain/dry-run UIs.
+ * Captures key decisions made during logical planning.
+ */
+export declare interface PlanningTraceStep {
+    /** Pipeline phase name */
+    phase: 'cube_usage' | 'primary_cube_selection' | 'join_planning' | 'cte_planning' | 'measure_strategy' | 'warnings';
+    /** Short summary of what was decided */
+    decision: string;
+    /** Optional machine-readable details */
+    details?: Record<string, unknown>;
+}
+
+/** A single optimiser pass that rewrites a logical plan */
+export declare interface PlanOptimiser {
+    /** Human-readable name for debugging / explain output */
+    readonly name: string;
+    /** Rewrite the plan tree. Must return a valid plan (may return the same reference). */
+    optimise(plan: LogicalNode, context: OptimiserContext): LogicalNode;
+}
+
+/**
+ * Type helpers for specific database types
+ */
+export declare type PostgresDatabase = PostgresJsDatabase<any>;
+
+export declare class PostgresExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
     getEngineType(): 'postgres';
     /**
      * Execute EXPLAIN on a SQL query to get the execution plan
@@ -1996,6 +3299,38 @@ export declare interface PreAggregationCTEInfo {
     cteReason?: 'hasMany' | 'fanOutPrevention';
 }
 
+/**
+ * A scored candidate path considered by preferred-path selection.
+ */
+declare interface PreferredPathCandidateScore {
+    path: InternalJoinPathStep[];
+    score: number;
+    usesPreferredJoin: boolean;
+    preferredCubesInPath: number;
+    usesProcessed: boolean;
+    scoreBreakdown: PreferredPathScoreBreakdown;
+}
+
+/**
+ * Score breakdown for a candidate preferred path.
+ */
+declare interface PreferredPathScoreBreakdown {
+    preferredJoinBonus: number;
+    preferredCubeBonus: number;
+    lengthPenalty: number;
+}
+
+/**
+ * Detailed preferred-path selection output for analysis/debug UIs.
+ */
+declare interface PreferredPathSelection {
+    strategy: 'preferred' | 'fallbackShortest';
+    preferredCubes: string[];
+    selectedIndex: number;
+    candidates: PreferredPathCandidateScore[];
+    selectedPath: InternalJoinPathStep[] | null;
+}
+
 /**
  * Primary cube selection analysis
  */
@@ -2151,110 +3486,8 @@ export declare interface QueryAnalysis {
     querySummary: QuerySummary;
     /** Warnings or potential issues */
     warnings?: string[];
-}
-
-export declare class QueryBuilder {
-    private dateTimeBuilder;
-    private filterBuilder;
-    private groupByBuilder;
-    private measureBuilder;
-    constructor(databaseAdapter: DatabaseAdapter);
-    /**
-     * Build resolvedMeasures map for a set of measures
-     * Delegates to MeasureBuilder
-     */
-    buildResolvedMeasures(measureNames: string[], cubeMap: Map<string, Cube>, context: QueryContext, customMeasureBuilder?: (measureName: string, measure: any, cube: Cube) => SQL): ResolvedMeasures;
-    /**
-     * Build dynamic selections for measures, dimensions, and time dimensions
-     * Works for both single and multi-cube queries
-     * Handles calculated measures with dependency resolution
-     */
-    buildSelections(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext): Record<string, SQL | AnyColumn>;
-    /**
-     * Build calculated measure expression by substituting {member} references
-     * Delegates to MeasureBuilder
-     */
-    buildCalculatedMeasure(measure: any, cube: Cube, allCubes: Map<string, Cube>, resolvedMeasures: ResolvedMeasures, context: QueryContext): SQL;
-    /**
-     * Build resolved measures map for a calculated measure from CTE columns
-     * Delegates to MeasureBuilder
-     */
-    buildCTECalculatedMeasure(measure: any, cube: Cube, cteInfo: {
-        cteAlias: string;
-        measures: string[];
-        cube: Cube;
-    }, allCubes: Map<string, Cube>, context: QueryContext): SQL;
-    /**
-     * Build measure expression for HAVING clause, handling CTE references correctly
-     * Delegates to MeasureBuilder
-     */
-    private buildHavingMeasureExpression;
-    /**
-     * Build measure expression with aggregation and filters
-     * Delegates to MeasureBuilder
-     */
-    buildMeasureExpression(measure: any, context: QueryContext, cube?: Cube): SQL;
-    /**
-     * Build time dimension expression with granularity using database adapter
-     * Delegates to DateTimeBuilder
-     */
-    buildTimeDimensionExpression(dimensionSql: any, granularity: string | undefined, context: QueryContext): SQL;
-    /**
-     * Build WHERE conditions from semantic query filters (dimensions only)
-     * Works for both single and multi-cube queries
-     * @param preBuiltFilters - Optional map of cube name to pre-built filter SQL for parameter deduplication
-     */
-    buildWhereConditions(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: QueryPlan, preBuiltFilters?: Map<string, SQL[]>): SQL[];
-    /**
-     * Build HAVING conditions from semantic query filters (measures only)
-     * Works for both single and multi-cube queries
-     */
-    buildHavingConditions(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: QueryPlan): SQL[];
-    /**
-     * Process a single filter (basic or logical)
-     * @param filterType - 'where' for dimension filters, 'having' for measure filters
-     */
-    private processFilter;
-    /**
-     * Build filter condition using Drizzle operators
-     * Delegates to FilterBuilder
-     */
-    private buildFilterCondition;
-    /**
-     * Build date range condition for time dimensions
-     * Delegates to DateTimeBuilder
-     */
-    buildDateRangeCondition(fieldExpr: AnyColumn | SQL, dateRange: string | string[]): SQL | null;
-    /**
-     * Build GROUP BY fields from dimensions and time dimensions
-     * Delegates to GroupByBuilder
-     */
-    buildGroupByFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: any): (SQL | AnyColumn)[];
-    /**
-     * Build ORDER BY clause with automatic time dimension sorting
-     */
-    buildOrderBy(query: SemanticQuery, selectedFields?: string[]): SQL[];
-    /**
-     * Collect numeric field names (measures + numeric dimensions) for type conversion
-     * Works for both single and multi-cube queries
-     */
-    collectNumericFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery): string[];
-    /**
-     * Apply LIMIT and OFFSET to a query with validation
-     * If offset is provided without limit, add a reasonable default limit
-     */
-    applyLimitAndOffset<T>(query: T, semanticQuery: SemanticQuery): T;
-    /**
-     * Public wrapper for buildFilterCondition - used by executor for cache preloading
-     * This allows pre-building filter SQL before query construction
-     */
-    buildFilterConditionPublic(fieldExpr: AnyColumn | SQL, operator: FilterOperator, values: any[], field?: any, dateRange?: string | string[]): SQL | null;
-    /**
-     * Build a logical filter (AND/OR) - used by executor for cache preloading
-     * This handles nested filter structures and builds combined SQL
-     * Delegates to FilterBuilder
-     */
-    buildLogicalFilter(filter: Filter, cubes: Map<string, Cube>, context: QueryContext): SQL | null;
+    /** Structured decision trace for debugging and dry-run UIs */
+    planningTrace?: PlanningTrace;
 }
 
 /**
@@ -2275,7 +3508,7 @@ export declare interface QueryCacheMetadata {
  * Query context passed to cube SQL functions
  * Provides access to database, schema, and security context
  */
-declare interface QueryContext {
+export declare interface QueryContext {
     /** Drizzle database instance */
     db: DrizzleDatabase;
     /** Database schema (tables, columns, etc.) */
@@ -2292,20 +3525,19 @@ declare interface QueryContext {
      */
     filterCache?: FilterCacheManager;
 }
-export { QueryContext }
-export { QueryContext as SemanticQueryContext }
 
 export declare class QueryExecutor {
     private dbExecutor;
     private queryBuilder;
-    private queryPlanner;
-    private cteBuilder;
+    private drizzlePlanBuilder;
     private databaseAdapter;
     private comparisonQueryBuilder;
     private funnelQueryBuilder;
     private flowQueryBuilder;
     private retentionQueryBuilder;
     private cacheConfig?;
+    private logicalPlanBuilder;
+    private planOptimiser;
     constructor(dbExecutor: DatabaseExecutor, cacheConfig?: CacheConfig);
     /**
      * Unified query execution method that handles both single and multi-cube queries
@@ -2313,411 +3545,180 @@ export declare class QueryExecutor {
      */
     execute(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext, options?: ExecutionOptions): Promise<QueryResult>;
     /**
-     * Legacy interface for single cube queries
-     */
-    executeQuery(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<QueryResult>;
-    /**
-     * Execute a comparison query with caching support
-     * Wraps executeComparisonQuery with cache set logic
-     */
-    private executeComparisonQueryWithCache;
-    /**
-     * Execute a comparison query with multiple date periods
-     * Expands compareDateRange into multiple sub-queries and merges results
-     */
-    private executeComparisonQuery;
-    /**
-     * Execute a funnel query with caching support
-     */
-    private executeFunnelQueryWithCache;
-    /**
-     * Execute a funnel analysis query
-     */
-    private executeFunnelQuery;
-    /**
-     * Execute a flow query with caching support
-     */
-    private executeFlowQueryWithCache;
-    /**
-     * Execute a flow analysis query
-     * Produces Sankey diagram data (nodes and links)
-     */
-    private executeFlowQuery;
-    /**
-     * Execute a retention query with caching support
-     */
-    private executeRetentionQueryWithCache;
-    /**
-     * Execute a retention analysis query
-     * Calculates cohort-based retention rates
-     */
-    private executeRetentionQuery;
-    /**
-     * Standard query execution (non-comparison)
-     * This is the core execution logic extracted for use by comparison queries
-     */
-    private executeStandardQuery;
-    /**
-     * Validate that all cubes in the query plan have proper security filtering.
-     * Emits a warning if a cube's sql() function doesn't return a WHERE clause.
-     *
-     * Security is critical in multi-tenant applications - this validation helps
-     * detect cubes that may leak data across tenants.
-     */
-    private validateSecurityContext;
-    /**
-     * Build unified query that works for both single and multi-cube queries
-     */
-    private buildUnifiedQuery;
-    /**
-     * Convert query plan to cube map for QueryBuilder methods
-     */
-    private getCubesFromPlan;
-    /**
-     * For hasMany CTEs, detect when the outer query grain already matches the CTE join key.
-     * In that case, re-aggregation should use MAX (not SUM) to avoid multiplying values by
-     * lower-grain primary cube rows.
-     */
-    private shouldUseMaxForHasManyAtJoinKeyGrain;
-    /**
-     * Checks whether query grouping includes a dimension backed by the given column.
-     */
-    private queryGroupsByColumn;
-    /**
-     * Generate raw SQL for debugging (without execution) - unified approach
-     */
-    generateSQL(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<{
-        sql: string;
-        params?: any[];
-    }>;
-    /**
-     * Generate raw SQL for multi-cube queries without execution - unified approach
-     */
-    generateMultiCubeSQL(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
-        sql: string;
-        params?: any[];
-    }>;
-    /**
-     * Generate SQL for a funnel query without execution (dry-run)
-     * Returns the actual CTE-based SQL that would be executed
-     */
-    dryRunFunnel(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
-        sql: string;
-        params?: any[];
-    }>;
-    /**
-     * Generate SQL for a flow query without execution (dry-run)
-     * Returns the actual CTE-based SQL that would be executed
-     */
-    dryRunFlow(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
-        sql: string;
-        params?: any[];
-    }>;
-    /**
-     * Generate SQL for a retention query without execution (dry-run)
-     * Returns the actual CTE-based SQL that would be executed
-     */
-    dryRunRetention(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
-        sql: string;
-        params?: any[];
-    }>;
-    /**
-     * Execute EXPLAIN on a query to get the execution plan
-     * Generates the SQL using the same secure path as execute/generateSQL,
-     * then runs EXPLAIN on the database.
-     */
-    explainQuery(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext, options?: ExplainOptions): Promise<ExplainResult>;
-    /**
-     * Generate SQL using unified approach (works for both single and multi-cube)
-     */
-    private generateUnifiedSQL;
-    /**
-     * Generate annotations for UI metadata - unified approach
-     */
-    private generateAnnotations;
-    /**
-     * Pre-build filter SQL and store in cache for reuse across CTEs and main query
-     * This enables parameter deduplication - the same filter values are shared
-     * rather than appearing as separate parameters in different parts of the query
+     * Build a logical plan for a query without executing it.
+     * Useful for testing, debugging, and plan inspection.
      */
-    private preloadFilterCache;
+    buildLogicalPlan(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): QueryNode;
     /**
-     * Build post-aggregation window function expression
-     *
-     * Post-aggregation windows operate on already-aggregated data:
-     * 1. The base measure is aggregated (e.g., SUM(revenue))
-     * 2. The window function is applied (e.g., LAG(...) OVER ORDER BY date)
-     * 3. An optional operation is applied (e.g., current - previous)
-     *
-     * @param measure - The window function measure definition
-     * @param baseMeasureExpr - The aggregated base measure expression
-     * @param query - The semantic query (for dimension context)
-     * @param context - Query context
-     * @param cube - The cube containing this measure
-     * @returns SQL expression for the window function
+     * Analyze planning decisions for a regular query using the same logical
+     * planning path as execution and dry-run SQL generation.
      */
-    private buildPostAggregationWindowExpression;
-}
-
-/**
- * Unified Query Plan for both single and multi-cube queries
- * - For single-cube queries: joinCubes array is empty
- * - For multi-cube queries: joinCubes contains the additional cubes to join
- * - selections, whereConditions, and groupByFields are populated by QueryBuilder
- */
-export declare interface QueryPlan {
-    /** Primary cube that drives the query */
-    primaryCube: Cube;
-    /** Additional cubes to join (empty for single-cube queries) */
-    joinCubes: Array<{
-        cube: Cube;
-        alias: string;
-        joinType: 'inner' | 'left' | 'right' | 'full';
-        joinCondition: SQL;
-        /** Junction table information for belongsToMany relationships */
-        junctionTable?: {
-            table: Table;
-            alias: string;
-            joinType: 'inner' | 'left' | 'right' | 'full';
-            joinCondition: SQL;
-            /** Optional security SQL function to apply to junction table */
-            securitySql?: (securityContext: SecurityContext) => SQL | SQL[];
-            /** Source cube name for the belongsToMany relationship (needed for CTE rewriting) */
-            sourceCubeName?: string;
-        };
-    }>;
-    /** Combined field selections across all cubes (built by QueryBuilder) */
-    selections: Record<string, SQL | AnyColumn>;
-    /** WHERE conditions for the entire query (built by QueryBuilder) */
-    whereConditions: SQL[];
-    /** GROUP BY fields if aggregations are present (built by QueryBuilder) */
-    groupByFields: (SQL | AnyColumn)[];
-    /** Pre-aggregation CTEs for hasMany relationships to prevent fan-out */
-    preAggregationCTEs?: PreAggregationCTEInfo[];
-    /** Warnings about potential query issues (e.g., fan-out without dimensions) */
-    warnings?: QueryWarning[];
-}
-
-/**
- * Pre-aggregation plan for handling hasMany relationships
- */
-export declare class QueryPlanner {
-    private resolverCache;
+    analyzeQuery(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): QueryAnalysis;
     /**
-     * Get or create a JoinPathResolver for the given cubes map
-     */
-    private getResolver;
-    /**
-     * Analyze a semantic query to determine which cubes are involved
-     */
-    analyzeCubeUsage(query: SemanticQuery): Set<string>;
-    /**
-     * Recursively extract cube names from filters (handles logical filters)
-     */
-    private extractCubeNamesFromFilter;
-    /**
-     * Extract measures referenced in filters (for CTE inclusion)
-     */
-    private extractMeasuresFromFilters;
-    /**
-     * Recursively extract measures from filters for a specific cube
-     * Only includes filter members that are actually measures (not dimensions)
-     */
-    private extractMeasuresFromFilter;
-    /**
-     * Create a unified query plan that works for both single and multi-cube queries
-     */
-    createQueryPlan(cubes: Map<string, Cube>, query: SemanticQuery, ctx: QueryContext): QueryPlan;
-    /**
-     * Choose the primary cube based on query analysis
-     * Uses a consistent strategy to avoid measure order dependencies
-     *
-     * Delegates to analyzePrimaryCubeSelection() for the actual logic,
-     * ensuring a single source of truth for primary cube selection.
-     */
-    choosePrimaryCube(cubeNames: string[], query: SemanticQuery, cubes?: Map<string, Cube>): string;
-    /**
-     * Build join plan for multi-cube query
-     * Supports both direct joins and transitive joins through intermediate cubes
-     *
-     * Uses query-aware path selection to prefer joining through cubes that have
-     * measures in the query (e.g., joining Teams through EmployeeTeams when
-     * EmployeeTeams.count is a measure)
+     * Legacy interface for single cube queries
      */
-    private buildJoinPlan;
-    /**
-     * Plan pre-aggregation CTEs for hasMany relationships to prevent fan-out
-     * Note: belongsToMany relationships handle fan-out differently through their junction table structure
-     * and don't require CTEs - the two-hop join with the junction table provides natural grouping
-     *
-     * CRITICAL FAN-OUT PREVENTION LOGIC:
-     * When a query contains ANY hasMany relationship in the join graph, ALL cubes with measures
-     * that could be affected by row multiplication need CTEs. This includes:
-     *
-     * 1. Cubes with direct hasMany FROM primary (existing logic)
-     * 2. Cubes with measures that would be multiplied due to hasMany elsewhere in the query
-     *    - Example: Query has Departments.totalBudget + Productivity.recordCount
-     *    - Employees hasMany → Productivity causes row multiplication
-     *    - Departments.totalBudget would be inflated without CTE pre-aggregation
+    executeQuery(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<QueryResult>;
+    /**
+     * Execute a comparison query with caching support
+     * Wraps executeComparisonQuery with cache set logic
      */
-    private planPreAggregationCTEs;
+    private executeComparisonQueryWithCache;
     /**
-     * Find join information TO a cube (reverse lookup)
-     * Used when the primary cube needs a CTE and we need to find how other cubes join to it
+     * Execute a comparison query with multiple date periods
+     * Expands compareDateRange into multiple sub-queries and merges results
      */
-    private findJoinInfoToCube;
+    private executeComparisonQuery;
+    private buildComparisonExecutionPlan;
     /**
-     * Analyze the join path from primary cube to a target CTE cube.
-     * Detects if there are intermediate hasMany relationships that would cause fan-out.
-     *
-     * Returns information about:
-     * - The full join path
-     * - Whether there are hasMany relationships ON the path (not just at the end)
-     * - Which intermediate tables need to be absorbed into the CTE
-     * - The correct join key to use (from primary cube's connection point)
-     *
-     * @param cubes Map of all registered cubes
-     * @param primaryCube The primary cube (FROM clause)
-     * @param targetCubeName The CTE cube we're analyzing the path to
-     * @param ctx Query context for security filtering
+     * Execute a funnel query with caching support
      */
-    private analyzeJoinPathToPrimary;
+    private executeFunnelQueryWithCache;
     /**
-     * Detect all hasMany relationships that could affect the query
-     *
-     * This searches ALL cubes involved in the query (including intermediary cubes)
-     * to find any hasMany relationships that could cause row multiplication.
-     *
-     * Key insight: A hasMany relationship in ANY cube that's part of the join path
-     * will cause fan-out. We need to detect hasMany from:
-     * 1. The primary cube
-     * 2. All join cubes
-     * 3. Any intermediate cubes that form the join path
+     * Execute a funnel analysis query
      */
-    private detectHasManyInQuery;
+    private executeFunnelQuery;
     /**
-     * Determine if and why a cube needs pre-aggregation (CTE)
-     *
-     * Returns:
-     * - 'hasMany': Cube is the TARGET of a hasMany relationship - needs SUM in outer query
-     * - 'fanOutPrevention': Cube has measures affected by hasMany elsewhere - needs MAX in outer query
-     * - null: No CTE needed
-     *
-     * Key insight: When ANY hasMany exists in a query, ALL cubes with additive measures (sum, count)
-     * that are joined to the hasMany source cube are at risk of inflation.
+     * Execute a flow query with caching support
      */
-    private getCTEReason;
+    private executeFlowQueryWithCache;
     /**
-     * Find join information for a cube from any cube in the query
-     * This extends findHasManyJoinDef to work with any relationship type
-     * and to search from any source cube, not just the primary
+     * Execute a flow analysis query
+     * Produces Sankey diagram data (nodes and links)
      */
-    private findJoinInfoForCube;
+    private executeFlowQuery;
     /**
-     * Find downstream cubes that need join keys included in the CTE.
-     *
-     * When a query has dimensions from a cube (e.g., Teams.name) and measures from
-     * a junction cube (e.g., EmployeeTeams.count), the junction CTE needs to include
-     * the join key to the dimension cube (team_id) so the dimension cube can be
-     * joined through the CTE instead of via an alternative path.
-     *
-     * @param cteCube The cube being converted to a CTE (e.g., EmployeeTeams)
-     * @param query The semantic query with dimensions and measures
-     * @param allCubes Map of all registered cubes
-     * @returns Array of downstream join key info for cubes needing join through this CTE
+     * Execute a retention query with caching support
      */
-    private findDownstreamJoinKeys;
+    private executeRetentionQueryWithCache;
     /**
-     * Expand calculated measures to include their dependencies
+     * Execute a retention analysis query
+     * Calculates cohort-based retention rates
      */
-    private expandCalculatedMeasureDependencies;
+    private executeRetentionQuery;
     /**
-     * Extract measure references from calculatedSql template
+     * Standard query execution (non-comparison)
+     * This is the core execution logic extracted for use by comparison queries
      */
-    private extractDependenciesFromTemplate;
+    private executeStandardQuery;
     /**
-     * Find hasMany join definition from primary cube to target cube
+     * Create a query context with optional filter cache.
      */
-    private findHasManyJoinDef;
+    private createQueryContext;
     /**
-     * Find filters that need to propagate from related cubes to a CTE cube.
-     * When cube A has filters and a hasMany relationship to cube B (the CTE cube),
-     * A's filters should propagate into B's CTE via a subquery.
-     *
-     * Example: Employees.createdAt filter should propagate to Productivity CTE
-     * via: employee_id IN (SELECT id FROM employees WHERE created_at >= $date)
+     * Normalize engine type for optimiser passes.
+     * SingleStore follows MySQL SQL semantics for planner choices.
      */
-    private findPropagatingFilters;
+    private getOptimiserEngineType;
     /**
-     * Extract cube names from filters into a Set (helper for findPropagatingFilters)
+     * Shared regular-query planning pipeline used by execute, dry-run SQL,
+     * and analysis. This is the single source of planning truth.
      */
-    private extractFilterCubeNamesToSet;
+    private buildRegularQueryArtifacts;
     /**
-     * Extract filters for a specific cube from the filter array
+     * Validate that all cubes in the query plan have proper security filtering.
+     * Emits a warning if a cube's sql() function doesn't return a WHERE clause.
      *
-     * Logic for preserving filter semantics:
-     * - AND: Safe to extract only matching branches (AND of fewer conditions is more permissive)
-     * - OR: Must include ALL branches or skip entirely (partial OR changes semantics)
-     *       If any branch belongs to another cube, skip the entire OR to be safe
-     *       since we can't evaluate the other cube's conditions
+     * Security is critical in multi-tenant applications - this validation helps
+     * detect cubes that may leak data across tenants.
      */
-    private extractFiltersForCube;
+    private validateSecurityContext;
     /**
-     * Check if all simple filters in a filter array belong to the specified cube
-     * Recursively checks nested AND/OR filters
+     * Generate raw SQL for debugging (without execution) - unified approach
      */
-    private allFiltersFromCube;
+    generateSQL(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
     /**
-     * Extract time dimension date range filters as regular filters for a specific cube
+     * Generate raw SQL for multi-cube queries without execution - unified approach
      */
-    private extractTimeDimensionFiltersForCube;
+    generateMultiCubeSQL(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
     /**
-     * Analyze query planning decisions without building the full query
-     * Returns detailed metadata about how the query plan would be constructed
-     * Used for debugging and transparency in the playground UI
+     * Generate SQL for a funnel query without execution (dry-run)
+     * Returns the actual CTE-based SQL that would be executed
      */
-    analyzeQueryPlan(cubes: Map<string, Cube>, query: SemanticQuery, _ctx: QueryContext): QueryAnalysis;
+    dryRunFunnel(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
     /**
-     * Analyze why a particular cube was chosen as primary
+     * Generate SQL for a flow query without execution (dry-run)
+     * Returns the actual CTE-based SQL that would be executed
      */
-    private analyzePrimaryCubeSelection;
+    dryRunFlow(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
     /**
-     * Analyze the join path between two cubes with detailed step information
-     *
-     * Uses JoinPathResolver.findPath() for the actual path finding,
-     * then converts the result to human-readable analysis format.
+     * Generate SQL for a retention query without execution (dry-run)
+     * Returns the actual CTE-based SQL that would be executed
      */
-    private analyzeJoinPath;
+    dryRunRetention(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
     /**
-     * Analyze pre-aggregation requirements for hasMany relationships
-     * This mirrors the logic in planPreAggregationCTEs to ensure analysis matches execution
+     * Execute EXPLAIN on a query to get the execution plan
+     * Generates the SQL using the same secure path as execute/generateSQL,
+     * then runs EXPLAIN on the database.
      */
-    private analyzePreAggregations;
+    explainQuery(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext, options?: ExplainOptions): Promise<ExplainResult>;
     /**
-     * Generate warnings for query edge cases that users should be aware of.
-     * Currently detects:
-     * - FAN_OUT_NO_DIMENSIONS: Query has hasMany CTEs but no dimensions to group by
-     *
-     * Note: AVG measures in hasMany CTEs can produce mathematically imprecise results
-     * (average of averages vs weighted average), but this warning was removed as it
-     * fired too aggressively. The issue only occurs when the outer grouping is coarser
-     * than the CTE grouping, which is rare in practice. The limitation is documented
-     * in executor.ts comments.
+     * Generate SQL for any query mode without execution.
+     * This is the canonical dry-run SQL entrypoint used by explain/adapters.
      */
-    private generateWarnings;
+    dryRunSQL(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
     /**
-     * Detect when a query has measures from multiple cubes with hasMany relationships
-     * but no dimensions to provide grouping context.
-     *
-     * This is an edge case where:
-     * - Query has measures from 2+ cubes
-     * - At least one CTE exists (indicating hasMany relationship)
-     * - Query has NO dimensions AND NO time dimensions with granularity
-     *
-     * The SQL is technically correct (CTEs with GROUP BY on join keys), but users
-     * may be confused by the aggregated results without visible grouping.
+     * Generate SQL using unified approach (works for both single and multi-cube)
      */
-    private checkFanOutNoDimensions;
+    private generateUnifiedSQL;
+    private resolveQueryMode;
+    private validateQueryForMode;
+    private executeQueryByModeWithCache;
+    private executeRegularQueryWithCache;
+    private cacheResult;
+    private generateSqlForMode;
+    private generateComparisonSQL;
+    /**
+     * Generate annotations for UI metadata - unified approach
+     */
+    private generateAnnotations;
+    /**
+     * Pre-build filter SQL and store in cache for reuse across CTEs and main query
+     * This enables parameter deduplication - the same filter values are shared
+     * rather than appearing as separate parameters in different parts of the query
+     */
+    private preloadFilterCache;
+}
+
+/**
+ * Root query node — represents the outermost SELECT.
+ * Wraps a source node with dimensions, measures, filters, ordering, etc.
+ */
+export declare interface QueryNode extends LogicalNodeBase {
+    readonly type: 'query';
+    /** Source of rows (SimpleSource, FullKeyAggregate, etc.) */
+    source: LogicalNode;
+    /** Dimensions to group by */
+    dimensions: DimensionRef[];
+    /** Measures to aggregate */
+    measures: MeasureRef[];
+    /** User-supplied filters */
+    filters: Filter[];
+    /** Time dimensions with granularity / date range */
+    timeDimensions: TimeDimensionRef[];
+    /** ORDER BY clauses */
+    orderBy: OrderByRef[];
+    limit?: number;
+    offset?: number;
+    /** Planning warnings surfaced to the caller */
+    warnings: QueryWarning[];
 }
 
 /**
@@ -2768,6 +3769,8 @@ export declare interface QuerySuggestion {
 export declare interface QuerySummary {
     /** Query type: 'single_cube', 'multi_cube_join', or 'multi_cube_cte' */
     queryType: 'single_cube' | 'multi_cube_join' | 'multi_cube_cte';
+    /** Strategy selected for multiplied-measure handling / multi-fact merge */
+    measureStrategy?: 'simple' | 'keysDeduplication' | 'ctePreAggregateFallback' | 'multiFactMerge';
     /** Total number of joins */
     joinCount: number;
     /** Total number of CTEs */
@@ -2861,6 +3864,104 @@ export declare interface RetentionDateRange {
     end: string;
 }
 
+export declare class RetentionQueryBuilder {
+    private databaseAdapter;
+    private filterBuilder;
+    private dateTimeBuilder;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Check if query contains retention configuration
+     */
+    hasRetention(query: SemanticQuery): boolean;
+    /**
+     * Validate retention configuration against registered cubes
+     */
+    validateConfig(config: RetentionQueryConfig, cubes: Map<string, Cube>): {
+        isValid: boolean;
+        errors: string[];
+    };
+    /**
+     * Build the retention SQL query using CTEs
+     *
+     * CTE Structure (Simplified Mixpanel-style):
+     * 1. cohort_base - Users entering the cohort (first event in date range)
+     *    - When breakdown is specified, includes breakdown_value
+     * 2. activity_periods - All activity with period_number relative to cohort entry
+     * 3. cohort_sizes - Aggregate cohort sizes (per breakdown value if applicable)
+     * 4. retention_counts - Retained users per period (and breakdown value)
+     * 5. Final SELECT - Join with retention rate calculation
+     */
+    buildRetentionQuery(config: RetentionQueryConfig, cubes: Map<string, Cube>, context: QueryContext): any;
+    /**
+     * Transform raw SQL results to RetentionResultRow[]
+     */
+    transformResult(rawResult: unknown[], config: RetentionQueryConfig): RetentionResultRow[];
+    /**
+     * Resolve retention configuration with SQL expressions
+     * Same cube/dimension used for both cohort entry and activity detection
+     */
+    private resolveConfig;
+    /**
+     * Resolve binding key expression for a cube
+     */
+    private resolveBindingKey;
+    /**
+     * Build filter conditions from config filters
+     */
+    private buildFilterConditions;
+    /**
+     * Build a single filter condition
+     */
+    private buildSingleFilterCondition;
+    /**
+     * Build cohort_base CTE
+     * Groups users by their first activity (cohort entry) within the date range.
+     * When breakdowns are specified, includes breakdown values for each dimension.
+     */
+    private buildCohortBaseCTE;
+    /**
+     * Build date range condition for WHERE clause
+     * Filters records to those within the specified date range
+     */
+    private buildDateRangeCondition;
+    /**
+     * Build date range condition for HAVING clause
+     * Used to filter aggregated cohort_period values
+     */
+    private buildDateRangeHavingCondition;
+    /**
+     * Build activity_periods CTE
+     * Joins activity events to cohort_base and calculates period_number.
+     * Includes breakdown values from cohort_base when breakdowns are specified.
+     */
+    private buildActivityPeriodsCTE;
+    /**
+     * Build cohort_sizes CTE
+     * Aggregates the size of the cohort (or per breakdown combination if specified).
+     */
+    private buildCohortSizesCTE;
+    /**
+     * Build retention_counts CTE
+     * Aggregates retained users per period (and breakdown combination if specified).
+     */
+    private buildRetentionCountsCTE;
+    /**
+     * Build rolling retention counts query
+     * For rolling retention, a user is retained in period N if they were active
+     * in period N or any later period
+     */
+    private buildRollingRetentionCountsQuery;
+    /**
+     * Build period number expression using database-specific DATE_DIFF
+     */
+    private buildPeriodNumberExpression;
+    /**
+     * Extract dimension name from a dimension reference
+     * Handles both 'CubeName.dimName' and just 'dimName' formats
+     */
+    private extractDimensionName;
+}
+
 /**
  * Retention query configuration (Simplified Mixpanel-style format)
  *
@@ -2954,6 +4055,40 @@ export declare interface RetentionTimeDimensionMapping {
     dimension: string;
 }
 
+/**
+ * A link (edge) in the Sankey diagram
+ * Represents a transition between two nodes
+ */
+declare interface SankeyLink {
+    /** Source node ID */
+    source: string;
+    /** Target node ID */
+    target: string;
+    /** Count of entities that follow this path */
+    value: number;
+}
+
+/**
+ * A node in the Sankey diagram
+ * Represents an event type at a specific layer (distance from starting step)
+ */
+declare interface SankeyNode {
+    /**
+     * Unique identifier for this node
+     * Format: "before_{depth}_{eventType}" or "after_{depth}_{eventType}" or "start_{eventType}"
+     */
+    id: string;
+    /** Display name (typically the event type value) */
+    name: string;
+    /**
+     * Layer position in the Sankey diagram
+     * Negative for steps before starting step, 0 for starting step, positive for after
+     */
+    layer: number;
+    /** Total count of entities passing through this node */
+    value?: number;
+}
+
 /**
  * Security context passed to cube SQL functions
  * Contains user/tenant-specific data for filtering
@@ -2991,6 +4126,18 @@ export declare class SemanticLayerCompiler {
      * Check if database executor is configured
      */
     hasExecutor(): boolean;
+    /**
+     * Get configured executor or throw.
+     */
+    private requireExecutor;
+    /**
+     * Create a query executor with optional cache integration.
+     */
+    private createQueryExecutor;
+    /**
+     * Format SQL result using current engine dialect.
+     */
+    private formatSqlResult;
     /**
      * Register a simplified cube with dynamic query building
      * Validates calculated measures during registration
@@ -3063,6 +4210,13 @@ export declare class SemanticLayerCompiler {
         sql: string;
         params?: any[];
     }>;
+    /**
+     * Canonical dry-run SQL generation entrypoint for all query modes.
+     */
+    dryRun(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
     /**
      * Get SQL for a funnel query without executing it (debugging)
      * Returns the actual CTE-based SQL that would be executed for funnel queries
@@ -3237,6 +4391,20 @@ export declare interface SemanticQuery {
     retention?: RetentionQueryConfig;
 }
 
+/**
+ * Simple source: one primary cube optionally joined to other cubes.
+ * This is the runtime physical-source shape used by SQL generation today.
+ */
+export declare interface SimpleSource extends LogicalNodeBase {
+    readonly type: 'simpleSource';
+    /** Primary cube (FROM clause) */
+    primaryCube: CubeRef;
+    /** Cubes joined to the primary */
+    joins: JoinRef[];
+    /** Pre-aggregation CTEs attached to this source */
+    ctes: CTEPreAggregate[];
+}
+
 export { SQL }
 
 /**
@@ -3394,6 +4562,18 @@ export declare interface TimeDimensionAnnotation {
     granularity?: TimeGranularity;
 }
 
+/** Reference to a time dimension with granularity/dateRange */
+declare interface TimeDimensionRef {
+    /** Fully qualified dimension name */
+    name: string;
+    cube: CubeRef;
+    localName: string;
+    granularity?: TimeGranularity;
+    dateRange?: string | string[];
+    fillMissingDates?: boolean;
+    compareDateRange?: (string | [string, string])[];
+}
+
 export declare type TimeGranularity = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
 
 /**