drizzle-cube 0.5.8 → 0.6.0

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

@@ -1,44 +1,14 @@
 import { Cube, QueryContext, PhysicalQueryPlan, SemanticQuery, PrimaryCubeAnalysis, JoinPathAnalysis, QueryWarning } from '../types';
-/**
- * Pre-aggregation plan for handling hasMany relationships
- */
+import { JoinRef } from './types';
 export declare class LogicalPlanner {
-    private resolverCache;
-    /**
-     * Get or create a JoinPathResolver for the given cubes map
-     */
-    private getResolver;
+    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>;
-    /**
-     * 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
@@ -55,178 +25,15 @@ export declare class LogicalPlanner {
      * 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'];
+    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: PhysicalQueryPlan['joinCubes'], query: SemanticQuery, ctx: QueryContext): PhysicalQueryPlan['preAggregationCTEs'];
+    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[];
-    /**
-     * 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;
 }

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

@@ -1,8 +1,10 @@
 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: 'postgres' | 'mysql' | 'sqlite' | 'duckdb';
+    engineType: OptimiserEngineType;
 }
 /** A single optimiser pass that rewrites a logical plan */
 export interface PlanOptimiser {

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;

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

@@ -1,7 +1,7 @@
-import { SQL, AnyColumn, Table } from 'drizzle-orm';
-import { Cube, JoinKeyInfo, PropagatingFilter, IntermediateJoinInfo, DownstreamJoinKeyInfo } from '../types/cube';
+import { AnyColumn, Table } from 'drizzle-orm';
+import { Cube, CubeJoin, JoinKeyInfo, PropagatingFilter, IntermediateJoinInfo, DownstreamJoinKeyInfo } from '../types/cube';
 import { Filter } from '../types/query';
-import { SecurityContext, QueryWarning, TimeGranularity } from '../types/core';
+import { QueryWarning, TimeGranularity } from '../types/core';
 /** Reference to a registered cube */
 export interface CubeRef {
     /** Cube name (e.g. 'Employees') */
@@ -59,19 +59,25 @@ export interface JoinRef {
     target: CubeRef;
     /** Table alias in the generated SQL */
     alias: string;
-    /** SQL join type */
+    /** SQL join type (already resolved from the effective relationship) */
     joinType: 'inner' | 'left' | 'right' | 'full';
-    /** Drizzle SQL join condition (pre-built by the planner) */
-    joinCondition: SQL;
+    /**
+     * Symbolic join definition. The Drizzle join condition is materialized from
+     * this by DrizzlePlanBuilder — the logical plan itself holds no SQL and no
+     * baked security context.
+     */
+    joinDef: CubeJoin;
     /** Relationship type from the join definition */
     relationship?: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
-    /** Junction table for belongsToMany relationships */
+    /**
+     * Junction table for belongsToMany relationships (symbolic).
+     * The junction join condition and security WHERE are materialized from
+     * `joinDef.through` by DrizzlePlanBuilder at physical-plan time.
+     */
     junctionTable?: {
         table: Table;
         alias: string;
         joinType: 'inner' | 'left' | 'right' | 'full';
-        joinCondition: SQL;
-        securitySql?: (securityContext: SecurityContext) => SQL | SQL[];
         sourceCubeName?: string;
     };
 }
@@ -102,6 +108,8 @@ export interface QueryNode extends LogicalNodeBase {
     orderBy: OrderByRef[];
     limit?: number;
     offset?: number;
+    /** When true, skip GROUP BY (raw rows) */
+    ungrouped?: boolean;
     /** Planning warnings surfaced to the caller */
     warnings: QueryWarning[];
 }

package/dist/server/server/measure-classification.d.ts

@@ -0,0 +1,40 @@
+import { Cube } from './types';
+/**
+ * Measure types that are window functions. Window functions require special
+ * handling: no GROUP BY in the CTE, no re-aggregation in the outer query, and
+ * they return individual rows rather than grouped results.
+ */
+export declare const WINDOW_FUNCTION_TYPES: readonly ["lag", "lead", "rank", "denseRank", "rowNumber", "ntile", "firstValue", "lastValue", "movingAvg", "movingSum"];
+/** Check if a measure type is a window function. */
+export declare function isWindowFunction(measureType: string): boolean;
+/**
+ * Check if a measure is a post-aggregation window function.
+ * Post-aggregation windows reference a base `measure` in their windowConfig,
+ * indicating they operate on aggregated data rather than raw rows.
+ */
+export declare function isPostAggregationWindow(measure: any): boolean;
+/**
+ * Resolve the base-measure reference for a post-aggregation window function to a
+ * fully qualified name (e.g. 'totalRevenue' -> 'Sales.totalRevenue').
+ * Returns null when the measure is not a post-aggregation window.
+ */
+export declare function getWindowBaseMeasure(measure: any, cubeName: string): string | null;
+/**
+ * Default operation for a window function type.
+ * - lag/lead default to 'difference' (compare current vs previous/next)
+ * - all others default to 'raw'
+ */
+export declare function getDefaultWindowOperation(windowType: string): 'raw' | 'difference' | 'ratio' | 'percentChange';
+/**
+ * Categorize measures for post-aggregation window-function handling.
+ * - aggregateMeasures: regular aggregates (count, sum, avg, etc.)
+ * - postAggWindowMeasures: window functions referencing a base measure
+ * - requiredBaseMeasures: base measures those windows depend on (auto-added)
+ */
+export declare function categorizeForPostAggregation(measureNames: string[], cubeMap: Map<string, Cube>): {
+    aggregateMeasures: string[];
+    postAggWindowMeasures: string[];
+    requiredBaseMeasures: Set<string>;
+};
+/** Whether any measure in the list is a post-aggregation window function. */
+export declare function hasPostAggregationWindows(measureNames: string[], cubeMap: Map<string, Cube>): boolean;

package/dist/server/server/physical-plan/drizzle-plan-builder.d.ts

@@ -17,9 +17,29 @@ export declare class DrizzlePlanBuilder {
      * This is the physical-builder input for SQL generation.
      */
     derivePhysicalPlanContext(plan: QueryNode): PhysicalQueryPlan;
+    /**
+     * Materialize a symbolic JoinRef into a runtime JoinCubePlanEntry, building
+     * the Drizzle join condition(s) from the join definition. This is the seam
+     * where the logical plan's symbolic join refs become executable SQL — the
+     * planner no longer pre-builds any join SQL.
+     *
+     * Junction-table security is NOT materialized here: the stored
+     * `through.securitySql` function is carried forward and applied (in the WHERE
+     * clause) at build time with the request's security context.
+     */
+    private materializeJoin;
     private derivePhysicalPlanContextFromMultiFact;
     private derivePhysicalPlanContextFromFullKeyAggregate;
-    private toSemanticQuery;
+    /**
+     * Reconstruct a SemanticQuery from a (possibly optimised) QueryNode.
+     *
+     * This is the materialization seam that makes the logical plan a real IR:
+     * the executor derives the query the physical builder consumes from the
+     * optimised plan, so optimiser rewrites of measures/filters/limit/etc. take
+     * effect in the generated SQL. Must faithfully round-trip every field the
+     * physical builder and processors read off a SemanticQuery.
+     */
+    toSemanticQuery(node: QueryNode): SemanticQuery;
     private resolvePhysicalSimpleSource;
     private resolvePhysicalSimpleSourceFromKeysDedup;
     private resolveKeysDeduplicationMeta;
@@ -27,24 +47,4 @@ export declare class DrizzlePlanBuilder {
      * 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;
 }

package/dist/server/server/physical-plan/drizzle-sql-builder.d.ts

@@ -54,6 +54,15 @@ export declare class DrizzleSqlBuilder {
      * @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[];
+    /**
+     * Append a single regular filter's WHERE condition, preferring pre-built
+     * filter SQL (for parameter deduplication) and skipping CTE-handled cubes.
+     */
+    private appendWhereFilter;
+    /** Append a time dimension's date-range WHERE condition (cached when possible). */
+    private appendTimeDimensionWhere;
+    /** Whether a cube is materialized in a pre-aggregation CTE of the plan. */
+    private cubeIsInCTE;
     /**
      * Build HAVING conditions from semantic query filters (measures only)
      * Works for both single and multi-cube queries
@@ -64,6 +73,8 @@ export declare class DrizzleSqlBuilder {
      * @param filterType - 'where' for dimension filters, 'having' for measure filters
      */
     private processFilter;
+    /** Build a WHERE condition for a dimension filter, honouring CTE skips and the filter cache. */
+    private processWhereDimensionFilter;
     /**
      * Build filter condition using Drizzle operators
      * Delegates to FilterBuilder

package/dist/server/server/physical-plan/processors/index.d.ts

@@ -2,5 +2,7 @@ export { buildCTEState } from './cte-processor';
 export { buildModifiedSelections } from './selection-processor';
 export { applyJoins } from './joins-processor';
 export { applyPredicatesAndFinalize } from './predicates-processor';
+export { buildKeysDeduplicationQuery } from './keys-dedup-processor';
+export { buildMultiFactMergeQuery } from './multi-fact-processor';
 export type { PhysicalBuildDependencies, CTEBuildState, JoinBuildState, SelectionMap, DownstreamJoinState } from './shared';
 export { getCubesFromPlan } from './shared';

package/dist/server/server/physical-plan/processors/keys-dedup-processor.d.ts

@@ -0,0 +1,13 @@
+import { PhysicalQueryPlan, QueryContext, SemanticQuery } from '../../types';
+import { PhysicalBuildDependencies } from './shared';
+/**
+ * Build the dual-CTE keys-deduplication query, or return null when the plan
+ * does not qualify (caller falls back to the standard build).
+ *
+ * The query splits into:
+ *  - a "keys" CTE that groups by the query grain + multiplied cube primary key
+ *    (pre-aggregating regular measures), and
+ *  - a "pk_agg" CTE that pre-aggregates the multiplied cube's measures per PK,
+ * then re-aggregates both in an outer query joined on the primary key.
+ */
+export declare function buildKeysDeduplicationQuery(queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext, deps: PhysicalBuildDependencies): any | null;

package/dist/server/server/physical-plan/processors/multi-fact-processor.d.ts

@@ -0,0 +1,13 @@
+import { PhysicalQueryPlan, QueryContext, SemanticQuery } from '../../types';
+import { PhysicalBuildDependencies } from './shared';
+/**
+ * Build a function for `build()` so each group CTE can be materialized through
+ * the standard physical-plan builder without a class dependency.
+ */
+export type GroupQueryBuilder = (queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext) => any;
+/**
+ * Build a multi-fact-merge query (joining independent measure groups on shared
+ * grain keys), or return null when the plan does not qualify. Falls back to a
+ * UNION-of-keys strategy when a FULL OUTER JOIN is requested but unsupported.
+ */
+export declare function buildMultiFactMergeQuery(queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext, deps: PhysicalBuildDependencies, buildGroup: GroupQueryBuilder): any | null;

package/dist/server/server/physical-plan/processors/shared.d.ts

@@ -30,4 +30,9 @@ export interface JoinBuildState {
     absorbedIntermediateCubes: Set<string>;
 }
 export type SelectionMap = Record<string, any>;
+/**
+ * Apply a join of the given type to a Drizzle query builder.
+ * Shared by the physical-plan builders that assemble CTE/merge queries.
+ */
+export declare function applyJoinByType(drizzleQuery: any, joinType: 'inner' | 'left' | 'right' | 'full', joinTarget: any, joinCondition: SQL): any;
 export declare function getCubesFromPlan(queryPlan: PhysicalQueryPlan): Map<string, Cube>;

package/dist/server/server/query-handlers.d.ts

@@ -0,0 +1,79 @@
+import { SemanticLayerCompiler } from './compiler';
+import { SemanticQuery, SecurityContext } from './types';
+import { CubeDiscoveryResult } from './ai/discovery';
+/**
+ * Discovery request body
+ */
+export interface DiscoverRequest {
+    /** Topic or keyword to search for */
+    topic?: string;
+    /** Natural language intent */
+    intent?: string;
+    /** Maximum results to return */
+    limit?: number;
+    /** Minimum relevance score (0-1) */
+    minScore?: number;
+}
+/**
+ * Load request body - execute a query
+ */
+export interface LoadRequest {
+    /** Query to execute */
+    query: SemanticQuery;
+}
+/**
+ * Discovery response shape returned by `handleDiscover`.
+ *
+ * In addition to the matched cubes, the response embeds the full query
+ * language reference and the date filtering decision tree. This is the
+ * primary delivery mechanism for query-construction guidance: clients
+ * cannot be relied upon to forward `prompts/*` content to the model, so
+ * we piggyback on `discover` (the mandated first call in our workflow)
+ * to guarantee the model sees the rules before it builds a query.
+ *
+ * The fields are stable strings — consumers may render or strip them as
+ * they see fit, but the MCP `discover` tool relies on them being present.
+ */
+export interface DiscoverResponse {
+    /** Matched cubes (possibly empty) with measures, dimensions, and joins */
+    cubes: CubeDiscoveryResult[];
+    /**
+     * Complete TypeScript DSL reference for query construction. Source of
+     * truth for field naming, filter operators, time dimensions, and
+     * analysis modes (funnel/flow/retention).
+     */
+    queryLanguageReference: string;
+    /**
+     * Decision tree for date filtering vs time grouping. The single most
+     * common source of incorrect queries — read this whenever the user
+     * mentions a time period.
+     */
+    dateFilteringGuide: string;
+}
+/**
+ * Handle /discover endpoint - find relevant cubes based on topic/intent.
+ *
+ * Always returns `queryLanguageReference` and `dateFilteringGuide` alongside
+ * the matched cubes. See `DiscoverResponse` for the rationale.
+ */
+export declare function handleDiscover(semanticLayer: SemanticLayerCompiler, body: DiscoverRequest): Promise<DiscoverResponse>;
+/**
+ * Normalize AI-generated query fields before validation/execution.
+ * Fixes common LLM mistakes:
+ * - Double-prefixed fields: "Teams.Teams.name" -> "Teams.name"
+ * - Order as array: [{key: dir}] -> {key: dir}
+ * - Underscore order keys: "Teams_count" -> "Teams.count"
+ * - Invalid order keys dropped (falls back to first measure desc)
+ *
+ * This runs in the shared handleLoad path so both MCP and Agent benefit.
+ */
+export declare function normalizeQueryFields(query: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Handle /load endpoint - execute a query and return results
+ * This completes the AI workflow: discover → suggest → validate → load
+ */
+export declare function handleLoad(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: LoadRequest): Promise<{
+    data: Record<string, unknown>[];
+    annotation: any;
+    query: SemanticQuery;
+}>;

package/dist/server/server/query-modes.d.ts

@@ -0,0 +1,28 @@
+import { SemanticQuery } from './types';
+export type QueryMode = 'regular' | 'comparison' | 'funnel' | 'flow' | 'retention';
+export interface QueryModeFlags {
+    comparison: boolean;
+    funnel: boolean;
+    flow: boolean;
+    retention: boolean;
+}
+/** A query is a comparison when a time dimension carries a compareDateRange with ≥2 ranges. */
+export declare function hasComparisonMode(query: SemanticQuery): boolean;
+/**
+ * A query is a funnel when it has a funnel config with ≥2 steps.
+ * Null-safe on `steps` — a `funnel: {}` payload must not throw here.
+ */
+export declare function hasFunnelMode(query: SemanticQuery): boolean;
+/** A query is a flow when it has a flow config with a startingStep and eventDimension. */
+export declare function hasFlowMode(query: SemanticQuery): boolean;
+/** A query is a retention when it has a retention config with a timeDimension and bindingKey. */
+export declare function hasRetentionMode(query: SemanticQuery): boolean;
+/** Per-mode booleans for a query. */
+export declare function detectQueryModes(query: SemanticQuery): QueryModeFlags;
+/**
+ * Active non-regular modes for a query, in execution-priority order
+ * (comparison, funnel, flow, retention). A well-formed query matches at most one.
+ */
+export declare function getActiveQueryModes(query: SemanticQuery): Exclude<QueryMode, 'regular'>[];
+/** The single priority mode for a query, or 'regular' when none match. */
+export declare function detectQueryMode(query: SemanticQuery): QueryMode;