drizzle-cube 0.5.7 → 0.6.0

package/dist/server/server/filter-cache.d.ts

@@ -0,0 +1,73 @@
+import { SQL } from 'drizzle-orm';
+import { Filter, FilterCondition, FilterCache } from './types';
+/**
+ * Generates a deterministic cache key for a filter
+ * Keys are based on filter content (member, operator, values) not object identity
+ */
+export declare function getFilterKey(filter: Filter): string;
+/**
+ * Generates a cache key for time dimension date range filters
+ */
+export declare function getTimeDimensionFilterKey(dimension: string, dateRange: string | string[]): string;
+/**
+ * Cache statistics for debugging and monitoring
+ */
+export interface FilterCacheStats {
+    hits: number;
+    misses: number;
+    cacheSize: number;
+}
+/**
+ * Manages filter SQL caching for a single query execution
+ *
+ * Design principles:
+ * - Immutable SQL: Once cached, SQL objects are never modified
+ * - Cache lifetime: Created at query start, discarded after query execution
+ * - Key by content: Filters with same member/operator/values share SQL
+ * - Thread-safe: No shared mutable state between queries
+ */
+export declare class FilterCacheManager implements FilterCache {
+    private cache;
+    private stats;
+    /**
+     * Get cached SQL or build and cache it
+     *
+     * @param key - The cache key (use getFilterKey or getTimeDimensionFilterKey)
+     * @param builder - Function to build the SQL if not cached
+     * @returns The cached or freshly built SQL, or null if builder returns null
+     */
+    getOrBuild(key: string, builder: () => SQL | null): SQL | null;
+    /**
+     * Check if a key exists in the cache without affecting stats
+     */
+    has(key: string): boolean;
+    /**
+     * Get cached SQL without building (returns undefined if not cached)
+     */
+    get(key: string): SQL | undefined;
+    /**
+     * Pre-populate cache with multiple filters
+     * Useful for batch initialization at query start
+     */
+    preload(entries: Array<{
+        key: string;
+        sql: SQL;
+    }>): void;
+    /**
+     * Store a single entry in the cache
+     */
+    set(key: string, sql: SQL): void;
+    /**
+     * Get cache statistics for debugging
+     */
+    getStats(): FilterCacheStats;
+    /**
+     * Clear the cache (normally not needed as cache is per-query)
+     */
+    clear(): void;
+}
+/**
+ * Flatten nested AND/OR filters into individual filter conditions
+ * Useful for pre-building all filters at query start
+ */
+export declare function flattenFilters(filters: Filter[]): FilterCondition[];

package/dist/server/server/gap-filler.d.ts

@@ -0,0 +1,48 @@
+import { SemanticQuery } from './types/query';
+import { TimeGranularity } from './types/core';
+/**
+ * Maximum number of time buckets gap filling will generate. Beyond this, gap
+ * filling is skipped entirely (data is returned unmodified) to avoid both
+ * runaway memory use and silent truncation of real rows.
+ */
+export declare const MAX_GAP_FILL_BUCKETS = 10000;
+export interface GapFillerConfig {
+    /** The time dimension key (e.g., 'Sales.date') */
+    timeDimensionKey: string;
+    /** Time granularity for bucket generation */
+    granularity: TimeGranularity;
+    /** Date range [start, end] */
+    dateRange: [Date, Date];
+    /** Value to fill for missing measures (default: 0) */
+    fillValue: number | null;
+    /** List of measure keys in the data */
+    measures: string[];
+    /** List of dimension keys in the data (excluding time dimensions) */
+    dimensions: string[];
+}
+/**
+ * Generate all time buckets for a given date range and granularity
+ */
+export declare function generateTimeBuckets(startDate: Date, endDate: Date, granularity: TimeGranularity): Date[];
+/**
+ * Fill time series gaps in query result data
+ *
+ * @param data - Original query result data
+ * @param config - Gap filling configuration
+ * @returns Data with gaps filled
+ */
+export declare function fillTimeSeriesGaps(data: Record<string, unknown>[], config: GapFillerConfig): Record<string, unknown>[];
+/**
+ * Parse date range from query time dimension
+ * Handles both array format ['2024-01-01', '2024-01-31'] and string format
+ */
+export declare function parseDateRange(dateRange: string | string[] | undefined): [Date, Date] | null;
+/**
+ * Apply gap filling to query result data based on query configuration
+ *
+ * @param data - Original query result data
+ * @param query - The semantic query
+ * @param measures - List of measure names in the result
+ * @returns Data with gaps filled (if applicable)
+ */
+export declare function applyGapFilling(data: Record<string, unknown>[], query: SemanticQuery, measures: string[]): Record<string, unknown>[];

package/dist/server/server/index.d.ts

@@ -0,0 +1,38 @@
+import { DrizzleDatabase } from './types';
+import { SemanticLayerCompiler } from './compiler';
+/**
+ * Drizzle Cube - Semantic Layer for Drizzle ORM
+ * Drizzle ORM-first semantic layer with Cube.js compatibility
+ */
+export { SemanticLayerCompiler } from './compiler';
+export { QueryExecutor } from './executor';
+export { detectQueryMode, detectQueryModes, getActiveQueryModes, hasComparisonMode, hasFunnelMode, hasFlowMode, hasRetentionMode } from './query-modes';
+export type { QueryMode, QueryModeFlags } from './query-modes';
+export { LogicalPlanner } from './logical-plan';
+export { DrizzleSqlBuilder } from './physical-plan';
+export { CTEBuilder, ComparisonQueryBuilder, FunnelQueryBuilder, FlowQueryBuilder, RetentionQueryBuilder } from './builders';
+export { CalculatedMeasureResolver, JoinPathResolver } from './resolvers';
+export { LogicalPlanBuilder, IdentityOptimiser, OptimiserPipeline } from './logical-plan';
+export type { LogicalNode, QueryNode, SimpleSource, CTEPreAggregate, CubeRef, MeasureRef, DimensionRef, LogicalPlanWithAnalysis, PlanOptimiser, OptimiserContext } from './logical-plan';
+export { DrizzlePlanBuilder } from './physical-plan';
+export { createDatabaseExecutor, createPostgresExecutor, createSQLiteExecutor, createMySQLExecutor, createDuckDBExecutor, createDatabendExecutor, createSnowflakeExecutor, BaseDatabaseExecutor, PostgresExecutor, SQLiteExecutor, MySQLExecutor, DuckDBExecutor, DatabendExecutor, SnowflakeExecutor } from './executors';
+export { resolveSqlExpression, createMultiCubeContext, resolveCubeReference, getJoinType } from './cube-utils';
+export { defineCube } from './cube-utils';
+export { generateCacheKey, normalizeQuery, fnv1aHash, strongHash, getCubeInvalidationPattern } from './cache-utils';
+export { MemoryCacheProvider } from './cache-providers';
+export { STEP0_VALIDATION_PROMPT, SYSTEM_PROMPT_TEMPLATE, STEP1_SYSTEM_PROMPT, STEP2_SYSTEM_PROMPT, buildStep0Prompt, buildSystemPrompt, buildStep1Prompt, buildStep2Prompt, EXPLAIN_ANALYSIS_PROMPT, buildExplainAnalysisPrompt, formatCubeSchemaForExplain, formatExistingIndexes } from './prompts';
+export type { Step0Result, PromptContext, DimensionValues, Step1Result } from './prompts';
+export { handleAgentChat, getToolDefinitions, createToolExecutor, buildAgentSystemPrompt } from './agent';
+export type { AgentChatRequest, AgentConfig, AgentObservabilityHooks, AgentSSEEvent, PortletBlockData, MarkdownBlockData, ToolExecutionResult } from './agent';
+export { discoverCubes, findBestFieldMatch, suggestQuery, validateQuery as aiValidateQuery } from './ai';
+export type { CubeDiscoveryResult, DiscoveryOptions, QuerySuggestion, ValidationResult as AIValidationResult, ValidationError as AIValidationError, ValidationWarning as AIValidationWarning } from './ai';
+export type * from './types';
+export type { SQL } from 'drizzle-orm';
+/**
+ * Create a new semantic layer instance with Drizzle integration
+ * Use this when you need multiple isolated instances
+ */
+export declare function createDrizzleSemanticLayer(options: {
+    drizzle: DrizzleDatabase;
+    schema?: any;
+}): SemanticLayerCompiler;

package/dist/server/server/logical-plan/cte-planner-helpers.d.ts

@@ -0,0 +1,37 @@
+import { Cube, CubeJoin, SemanticQuery } from '../types';
+/** A resolved CTE join key (column names plus the underlying column objects). */
+export interface CTEJoinKey {
+    sourceColumn: string;
+    targetColumn: string;
+    sourceColumnObj: any;
+    targetColumnObj: any;
+}
+/** A join definition located relative to a primary/target cube pair. */
+export interface FoundJoinInfo {
+    sourceCube: Cube;
+    joinDef: CubeJoin;
+    reversed?: boolean;
+}
+/**
+ * Derive the CTE join keys for a located join definition, handling
+ * belongsToMany junctions and reversed (belongsTo-back-to-primary) joins.
+ */
+export declare function deriveCTEJoinKeys(joinInfo: FoundJoinInfo, primaryCube: Cube): CTEJoinKey[];
+/**
+ * Derive the join keys connecting a downstream dimension cube through the CTE
+ * cube, handling belongsToMany (via junction sourceKey) and regular joins.
+ */
+export declare function deriveDownstreamJoinKeys(joinDef: CubeJoin): CTEJoinKey[];
+/**
+ * Find join information for a target cube, searching (in priority order):
+ * 1. The primary cube's direct join to the target.
+ * 2. The target cube's join back to the primary (reverse lookup → reversed).
+ * 3. Any other registered cube's join to the target.
+ */
+export declare function findJoinInfoForCube(cubes: Map<string, Cube>, primaryCube: Cube, targetCubeName: string): FoundJoinInfo | null;
+/**
+ * Collect the names of cubes (other than the CTE cube) that contribute
+ * dimensions, time dimensions, or filter members to the query. These are the
+ * candidate downstream cubes that may need to join through the CTE.
+ */
+export declare function collectDimensionCubeNames(query: SemanticQuery, cteCubeName: string): Set<string>;

package/dist/server/server/logical-plan/cte-planner.d.ts

@@ -0,0 +1,104 @@
+import { Cube, QueryContext, PhysicalQueryPlan, SemanticQuery } from '../types';
+import { ResolverCache } from './planner-utils';
+import { FilterPropagation } from './filter-propagation';
+import { JoinRef } from './types';
+export declare class CTEPlanner {
+    private readonly resolverCache;
+    private readonly filterPropagation;
+    constructor(resolverCache: ResolverCache, filterPropagation: FilterPropagation);
+    /**
+     * 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
+     */
+    planPreAggregationCTEs(cubes: Map<string, Cube>, primaryCube: Cube, joinCubes: JoinRef[], query: SemanticQuery, _ctx: QueryContext): PhysicalQueryPlan['preAggregationCTEs'];
+    /**
+     * Build a single pre-aggregation CTE for one join-cube entry, or return null
+     * when the cube contributes no aggregate measures / has no resolvable join.
+     */
+    private buildCTEForJoinCube;
+    /**
+     * Resolve the join keys (and any intermediate joins to absorb) for a CTE cube.
+     *
+     * Analyses the path from primary to the CTE cube: if an intermediate hasMany
+     * exists, returns the corrected keys plus intermediate joins; otherwise locates
+     * the join definition and derives keys from it.
+     */
+    private resolveCTEJoinKeys;
+    /**
+     * Locate the join definition for a CTE cube, preferring the final step of the
+     * analysed path and falling back to a primary/reverse/any-cube search.
+     */
+    private locateJoinInfo;
+    /**
+     * 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 query The semantic query (drives query-aware path selection)
+     */
+    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 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;
+    /**
+     * 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;
+}

package/dist/server/server/logical-plan/filter-propagation.d.ts

@@ -0,0 +1,44 @@
+import { Cube, SemanticQuery, PropagatingFilter, Filter } from '../types';
+export declare class FilterPropagation {
+    /**
+     * 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)
+     */
+    findPropagatingFilters(query: SemanticQuery, cteCube: Cube, allCubes: Map<string, Cube>): PropagatingFilter[];
+    /**
+     * Collect cube names referenced by filters and by time-dimension date ranges.
+     */
+    private collectFilterCubeNames;
+    /**
+     * Build a single PropagatingFilter for a filterCube → cteCube hasMany edge,
+     * or null when the cube contributes no filters / the join has no keys.
+     */
+    private buildPropagatingFilter;
+    /**
+     * Extract cube names from filters into a Set (helper for findPropagatingFilters)
+     */
+    extractFilterCubeNamesToSet(filters: Filter[], cubesSet: Set<string>): void;
+    /**
+     * 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
+     */
+    extractFiltersForCube(filters: Filter[], targetCubeName: string): Filter[];
+    /**
+     * Check if all simple filters in a filter array belong to the specified cube
+     * Recursively checks nested AND/OR filters
+     */
+    allFiltersFromCube(filters: Filter[], targetCubeName: string): boolean;
+    /**
+     * Extract time dimension date range filters as regular filters for a specific cube
+     */
+    extractTimeDimensionFiltersForCube(query: SemanticQuery, targetCubeName: string): Filter[];
+}

package/dist/server/server/logical-plan/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Logical Plan module — multi-stage query pipeline.
+ *
+ * Exports:
+ * - Types: LogicalNode tree types
+ * - LogicalPlanBuilder: SemanticQuery → LogicalNode tree
+ * - Optimisers: PlanOptimiser interface and built-in passes
+ */
+export type { LogicalNode, LogicalNodeType, LogicalNodeBase, QueryNode, SimpleSource, FullKeyAggregate, CTEPreAggregate, KeysDeduplication, MultiFactMerge, CubeRef, MeasureRef, DimensionRef, TimeDimensionRef, ColumnRef, OrderByRef, JoinRef, LogicalSchema } from './types';
+export { LogicalPlanner } from './logical-planner';
+export { LogicalPlanBuilder } from './logical-plan-builder';
+export type { LogicalPlanWithAnalysis } from './logical-plan-builder';
+export { JoinPlanner } from './join-planner';
+export { CTEPlanner } from './cte-planner';
+export { FilterPropagation } from './filter-propagation';
+export { PlanAnalysisReporter } from './plan-analysis-reporter';
+export { ResolverCache, analyzeCubeUsage, extractCubeNamesFromFilter } from './planner-utils';
+export type { PlanOptimiser, OptimiserContext, OptimiserEngineType } from './optimiser';
+export { IdentityOptimiser, OptimiserPipeline } from './optimiser';

package/dist/server/server/logical-plan/join-planner.d.ts

@@ -0,0 +1,27 @@
+import { Cube, CubeJoin, SemanticQuery } from '../types';
+import { ResolverCache } from './planner-utils';
+import { JoinRef } from './types';
+export declare class JoinPlanner {
+    private readonly resolverCache;
+    constructor(resolverCache: ResolverCache);
+    /**
+     * 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)
+     */
+    buildJoinPlan(cubes: Map<string, Cube>, primaryCube: Cube, cubeNames: string[], _ctx: unknown, query: SemanticQuery): JoinRef[];
+    /**
+     * Build a single symbolic JoinRef for a join-path step. Handles belongsToMany
+     * (junction-table) joins and regular (belongsTo/hasOne/hasMany) joins. The join
+     * conditions and security WHERE are materialized later by DrizzlePlanBuilder;
+     * only the join type is resolved here (it depends on the effective relationship).
+     */
+    private buildJoinRef;
+    /**
+     * Find hasMany join definition from primary cube to target cube
+     */
+    findHasManyJoinDef(primaryCube: Cube, targetCubeName: string, cubes?: Map<string, Cube>): CubeJoin | null;
+}

package/dist/server/server/logical-plan/logical-plan-builder.d.ts

@@ -0,0 +1,58 @@
+import { Cube, QueryContext } from '../types';
+import { QueryAnalysis } from '../types/analysis';
+import { SemanticQuery } from '../types/query';
+import { LogicalPlanner } from './logical-planner';
+import { QueryNode } from './types';
+export interface LogicalPlanWithAnalysis {
+    plan: QueryNode;
+    analysis: QueryAnalysis;
+}
+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;
+}

package/dist/server/server/logical-plan/logical-planner.d.ts

@@ -0,0 +1,39 @@
+import { Cube, QueryContext, PhysicalQueryPlan, SemanticQuery, PrimaryCubeAnalysis, JoinPathAnalysis, QueryWarning } from '../types';
+import { JoinRef } from './types';
+export declare class LogicalPlanner {
+    private readonly resolverCache;
+    private readonly joinPlanner;
+    private readonly ctePlanner;
+    private readonly reporter;
+    /**
+     * Analyze a semantic query to determine which cubes are involved
+     */
+    analyzeCubeUsage(query: SemanticQuery): Set<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): JoinRef[];
+    /**
+     * 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: JoinRef[], 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[];
+}

package/dist/server/server/logical-plan/optimiser.d.ts

@@ -0,0 +1,34 @@
+import { LogicalNode } from './types';
+/** Database engine the optimiser is targeting (all 7 supported engines). */
+export type OptimiserEngineType = 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+/** Context available to optimiser passes */
+export interface OptimiserContext {
+    /** Database engine type for engine-specific rewrites */
+    engineType: OptimiserEngineType;
+}
+/** A single optimiser pass that rewrites a logical plan */
+export 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}

package/dist/server/server/logical-plan/plan-analysis-reporter.d.ts

@@ -0,0 +1,59 @@
+import { Cube, PhysicalQueryPlan, SemanticQuery, PrimaryCubeAnalysis, JoinPathAnalysis, QueryWarning } from '../types';
+import { ResolverCache } from './planner-utils';
+export declare class PlanAnalysisReporter {
+    private readonly resolverCache;
+    constructor(resolverCache: ResolverCache);
+    /**
+     * Analyze why a particular cube was chosen as primary
+     */
+    analyzePrimaryCubeSelection(cubeNames: string[], query: SemanticQuery, cubes: Map<string, Cube>): PrimaryCubeAnalysis;
+    /**
+     * Build the scored candidate list (dimension count, join count, reachability).
+     */
+    private buildPrimaryCubeCandidates;
+    /**
+     * Tier 1: select the cube with the most query dimensions that can reach all
+     * others. Returns null when no dimension-based winner applies.
+     */
+    private selectByDimensions;
+    /**
+     * Tier 2: among cubes that can reach all others, select the most connected.
+     * Returns null when no candidate can reach all others.
+     */
+    private selectByConnectivity;
+    /**
+     * 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.
+     */
+    analyzeJoinPath(cubes: Map<string, Cube>, fromCube: string, toCube: string, query?: SemanticQuery): JoinPathAnalysis;
+    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.
+     */
+    generateWarnings(query: SemanticQuery, preAggregationCTEs?: PhysicalQueryPlan['preAggregationCTEs']): QueryWarning[];
+    /**
+     * 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;
+}

package/dist/server/server/logical-plan/planner-utils.d.ts

@@ -0,0 +1,20 @@
+import { Cube, SemanticQuery } from '../types';
+import { JoinPathResolver } from '../resolvers/join-path-resolver';
+/**
+ * Caches a JoinPathResolver per cubes map to avoid repeated instantiation.
+ * Shared by all sub-planners so a single query reuses one resolver per cubes map.
+ */
+export declare class ResolverCache {
+    private cache;
+    get(cubes: Map<string, Cube>): JoinPathResolver;
+}
+/**
+ * Analyze a semantic query to determine which cubes are involved.
+ * Scans measures, dimensions, time dimensions, filters and ORDER BY members.
+ */
+export declare function analyzeCubeUsage(query: SemanticQuery): Set<string>;
+/**
+ * Recursively extract cube names from a filter (handles logical AND/OR filters)
+ * into the provided set.
+ */
+export declare function extractCubeNamesFromFilter(filter: any, cubesUsed: Set<string>): void;