drizzle-cube 0.5.8 → 0.6.1

package/dist/server/builders/flow-query-builder.d.ts

@@ -0,0 +1,136 @@
+import { DatabaseAdapter } from '../adapters/base-adapter.js';
+import { FlowQueryConfig, FlowResultRow } from '../types/flow.js';
+import { AnalysisConfigValidationResult } from '../types/validation.js';
+import { Cube, QueryContext, SemanticQuery } from '../types/index.js';
+export declare class FlowQueryBuilder {
+    private filterBuilder;
+    private dateTimeBuilder;
+    private databaseAdapter;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Check if query contains flow configuration
+     */
+    hasFlow(query: SemanticQuery): boolean;
+    /**
+     * Validate flow configuration
+     */
+    validateConfig(config: FlowQueryConfig, cubes: Map<string, Cube>): AnalysisConfigValidationResult;
+    /**
+     * Validate a `Cube.dimension` member string: format, cube existence, and
+     * dimension existence. i18n message factories let each call site supply its
+     * own keys while sharing the branch structure.
+     */
+    private validateMemberDimension;
+    /** Validate the flow binding key (single member or per-cube mappings). */
+    private validateBindingKey;
+    /** Validate the flow starting step (required + filter + name warning). */
+    private validateStartingStep;
+    /** Validate flow step-depth bounds and emit high-depth performance warnings. */
+    private validateDepthBounds;
+    /** Validate the flow join strategy and its engine support. */
+    private validateJoinStrategy;
+    /**
+     * 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
+     */
+    buildFlowQuery(config: FlowQueryConfig, cubes: Map<string, Cube>, context: QueryContext): ReturnType<typeof context.db.select>;
+    /**
+     * Transform raw SQL result to FlowResultRow
+     * The raw result contains rows with record_type = 'node' or 'link'
+     */
+    transformResult(rawResult: Record<string, unknown>[]): FlowResultRow;
+    /**
+     * Resolve flow configuration to SQL expressions
+     */
+    private resolveFlowConfig;
+    /**
+     * 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 non-null sub-conditions of a logical/group filter. */
+    private buildSubConditions;
+    /** Combine sub-conditions with AND/OR, collapsing the 0- and 1-element cases. */
+    private combineConditions;
+    /**
+     * 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/AFTER the starting point using LATERAL joins
+     *
+     * Direction-parameterised: 'before' walks backwards (time `<` reference,
+     * ORDER BY DESC, `before_step_N` aliases, bounded by `stepsBefore`); 'after'
+     * walks forwards (time `>`, ORDER BY ASC, `after_step_N`, `stepsAfter`).
+     * Uses ORDER BY ... LIMIT 1 to fetch the immediate predecessor/successor via index.
+     */
+    private buildDirectionalCTEsLateral;
+    /**
+     * Build CTEs for steps BEFORE/AFTER the starting point using ROW_NUMBER()
+     *
+     * Direction-parameterised: 'before' finds the immediate predecessor (time `<`
+     * reference, ROW_NUMBER ORDER BY DESC, `before_step_N` aliases, bounded by
+     * `stepsBefore`); 'after' finds the immediate successor (time `>`, ORDER BY ASC,
+     * `after_step_N`, `stepsAfter`). For sunburst mode, accumulates event_path
+     * (prepend for before, append for after).
+     */
+    private buildDirectionalCTEsWindow;
+    /**
+     * Build a single node-aggregation UNION arm for a before/after step.
+     *
+     * Sankey groups by `event_type` (converging paths); sunburst groups by
+     * `event_path` (unique tree branches). The node-id prefix and layer are
+     * emitted via sql.raw() because they're hardcoded constants (not user input)
+     * and avoid multi-digit parameter issues in DuckDB.
+     */
+    private buildNodeArm;
+    /**
+     * Build a single link-aggregation UNION arm between two adjacent step CTEs
+     * (before→before or after→after). Sankey keys transitions on `event_type`,
+     * sunburst on `event_path`. Source/target id prefixes are sql.raw() constants.
+     */
+    private buildAdjacentLinkArm;
+    /**
+     * 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;
+}

package/dist/server/{server/builders → builders}/funnel-query-builder.d.ts

@@ -1,6 +1,6 @@
-import { DatabaseAdapter } from '../adapters/base-adapter';
-import { FunnelQueryConfig, FunnelResultRow } from '../types/funnel';
-import { Cube, QueryContext, SemanticQuery } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter.js';
+import { FunnelQueryConfig, FunnelResultRow } from '../types/funnel.js';
+import { Cube, QueryContext, SemanticQuery, AnalysisConfigValidationResult } from '../types/index.js';
 export declare class FunnelQueryBuilder {
     private databaseAdapter;
     private filterBuilder;
@@ -13,10 +13,15 @@ export declare class FunnelQueryBuilder {
     /**
      * Validate funnel configuration
      */
-    validateConfig(config: FunnelQueryConfig, cubes: Map<string, Cube>): {
-        isValid: boolean;
-        errors: string[];
-    };
+    validateConfig(config: FunnelQueryConfig, cubes: Map<string, Cube>): AnalysisConfigValidationResult;
+    /** Validate the funnel binding key (single member or per-cube mappings). */
+    private validateBindingKey;
+    /** Validate the funnel time dimension member. */
+    private validateTimeDimension;
+    /** Validate a single funnel step (name, cube, filters, timeToConvert). */
+    private validateStep;
+    /** Validate the member filters of a single funnel step. */
+    private validateStepFilters;
     /**
      * Build complete funnel query using Drizzle's query builder pattern
      *
@@ -32,6 +37,8 @@ export declare class FunnelQueryBuilder {
      * Transform raw SQL result to FunnelResultRow[]
      */
     transformResult(rawResult: Record<string, unknown>[], config: FunnelQueryConfig): FunnelResultRow[];
+    /** Attach the per-step conversion-time metrics to a funnel result row. */
+    private applyTimeMetrics;
     /**
      * Extract cube names referenced in step filters
      */
@@ -68,6 +75,10 @@ export declare class FunnelQueryBuilder {
      * @param context - Query context with security context
      */
     private buildFilterCondition;
+    /** Combine a logical/group filter's sub-conditions into a single SQL condition. */
+    private buildLogicalFilterCondition;
+    /** Build a simple (member) filter condition, validating values and cross-cube join paths. */
+    private buildSimpleFilterCondition;
     /**
      * Build CTE for a single step using Drizzle's $with() pattern
      *

package/dist/server/{server/builders → builders}/group-by-builder.d.ts

@@ -1,6 +1,6 @@
 import { SQL, AnyColumn } from 'drizzle-orm';
-import { Cube, SemanticQuery, QueryContext, PhysicalQueryPlan } from '../types';
-import { DateTimeBuilder } from './date-time-builder';
+import { Cube, SemanticQuery, QueryContext, PhysicalQueryPlan } from '../types/index.js';
+import { DateTimeBuilder } from './date-time-builder.js';
 export declare class GroupByBuilder {
     private dateTimeBuilder;
     constructor(dateTimeBuilder: DateTimeBuilder);
@@ -24,4 +24,15 @@ export declare class GroupByBuilder {
      * Window functions do not require GROUP BY and operate on individual rows.
      */
     buildGroupByFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: PhysicalQueryPlan): (SQL | AnyColumn)[];
+    /**
+     * Determine whether the query contains at least one aggregate (or calculated,
+     * or post-aggregation window over an aggregate) measure — which forces GROUP BY.
+     */
+    private hasAggregateMeasures;
+    /** True when `measure` is a post-aggregation window over an aggregate base measure. */
+    private isWindowOverAggregate;
+    /** Resolve a single dimension into its GROUP BY expression (CTE-aware). */
+    private resolveDimensionGroupField;
+    /** Resolve a single time dimension into its GROUP BY expression (CTE-aware). */
+    private resolveTimeDimensionGroupField;
 }

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

@@ -0,0 +1,13 @@
+/**
+ * Builders Index
+ * Re-exports all query builder components for modular imports
+ */
+export { DateTimeBuilder } from './date-time-builder.js';
+export { FilterBuilder } from './filter-builder.js';
+export { GroupByBuilder } from './group-by-builder.js';
+export { MeasureBuilder } from './measure-builder.js';
+export { CTEBuilder } from './cte-builder.js';
+export { ComparisonQueryBuilder } from './comparison-query-builder.js';
+export { FunnelQueryBuilder } from './funnel-query-builder.js';
+export { FlowQueryBuilder } from './flow-query-builder.js';
+export { RetentionQueryBuilder } from './retention-query-builder.js';

package/dist/server/{server/builders → builders}/measure-builder.d.ts

@@ -1,7 +1,7 @@
 import { SQL } from 'drizzle-orm';
-import { Cube, QueryContext, PhysicalQueryPlan } from '../types';
-import { DatabaseAdapter } from '../adapters/base-adapter';
-import { ResolvedMeasures } from '../template-substitution';
+import { Cube, QueryContext, PhysicalQueryPlan } from '../types/index.js';
+import { DatabaseAdapter } from '../adapters/base-adapter.js';
+import { ResolvedMeasures } from '../template-substitution.js';
 export declare class MeasureBuilder {
     private databaseAdapter;
     constructor(databaseAdapter: DatabaseAdapter);
@@ -17,6 +17,17 @@ export declare class MeasureBuilder {
      * @returns Map of measure names to SQL builder functions
      */
     buildResolvedMeasures(measureNames: string[], cubeMap: Map<string, Cube>, context: QueryContext, customMeasureBuilder?: (measureName: string, measure: any, cube: Cube) => SQL): ResolvedMeasures;
+    /**
+     * First-pass classification of a user-requested measure: sorts it into the
+     * regular/calculated buckets and seeds `allMeasuresToResolve` with its
+     * (transitive) dependencies. Post-aggregation windows only contribute their
+     * base measure as a dependency.
+     */
+    private classifyRequestedMeasure;
+    /** Seed `allMeasuresToResolve` with the direct + transitive deps of a calculated measure. */
+    private collectCalculatedDependencies;
+    /** Second-pass classification of a dependency measure into the regular/calculated buckets. */
+    private classifyDependencyMeasure;
     /**
      * Build calculated measure expression by substituting {member} references
      * with resolved SQL expressions
@@ -41,10 +52,21 @@ export declare class MeasureBuilder {
         measures: string[];
         cube: Cube;
     }, allCubes: Map<string, Cube>, context: QueryContext): SQL;
+    /**
+     * Re-aggregate a pre-aggregated CTE column based on the original measure type.
+     * For pre-aggregated values in CTEs we re-aggregate properly:
+     * - count/sum/number → SUM
+     * - avg → AVG (ideally a weighted average, but simple AVG for now)
+     * - min/max → MIN/MAX
+     * - anything else → SUM
+     */
+    private reAggregateCteColumn;
     /**
      * Build measure expression for HAVING clause, handling CTE references correctly
      */
     buildHavingMeasureExpression(cubeName: string, fieldKey: string, measure: any, context: QueryContext, queryPlan?: PhysicalQueryPlan): SQL;
+    /** Build a HAVING measure expression that references a pre-aggregation CTE column. */
+    private buildHavingCteMeasure;
     /**
      * Build measure expression with aggregation and filters
      * Note: This should NOT be called for calculated measures
@@ -54,6 +76,27 @@ export declare class MeasureBuilder {
      * @param cube - Optional cube reference for resolving dimension references (window functions)
      */
     buildMeasureExpression(measure: any, context: QueryContext, cube?: Cube): SQL;
+    /**
+     * Wrap a base expression in a CASE WHEN for measures carrying `filters`,
+     * producing conditional aggregation. Returns the original expression when
+     * there are no filters.
+     */
+    private applyMeasureFilters;
+    /** Apply the aggregation function implied by `measure.type` to `baseExpr`. */
+    private applyAggregation;
+    /**
+     * Run a statistical-function builder, falling back to MAX(NULL) with a warning
+     * when the engine doesn't support it (shared by stddev/variance/percentile).
+     */
+    private buildStatistical;
+    /** Resolve the percentile value implied by a percentile-family measure type. */
+    private resolvePercentile;
+    /** Build a (per-row) window-function measure expression. */
+    private buildWindowMeasure;
+    /** Resolve a window function's partitionBy dimension references to SQL expressions. */
+    private resolveWindowPartitions;
+    /** Resolve a window function's orderBy dimension/measure references to SQL expressions. */
+    private resolveWindowOrder;
     /**
      * List of measure types that are window functions
      * Window functions require special handling in CTEs:

package/dist/server/{server/builders → builders}/retention-query-builder.d.ts

@@ -1,6 +1,6 @@
-import { DatabaseAdapter } from '../adapters/base-adapter';
-import { RetentionQueryConfig, RetentionResultRow } from '../types/retention';
-import { Cube, QueryContext, SemanticQuery } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter.js';
+import { RetentionQueryConfig, RetentionResultRow } from '../types/retention.js';
+import { Cube, QueryContext, SemanticQuery, AnalysisConfigValidationResult } from '../types/index.js';
 export declare class RetentionQueryBuilder {
     private databaseAdapter;
     private filterBuilder;
@@ -13,10 +13,17 @@ export declare class RetentionQueryBuilder {
     /**
      * Validate retention configuration against registered cubes
      */
-    validateConfig(config: RetentionQueryConfig, cubes: Map<string, Cube>): {
-        isValid: boolean;
-        errors: string[];
-    };
+    validateConfig(config: RetentionQueryConfig, cubes: Map<string, Cube>): AnalysisConfigValidationResult;
+    /** Validate the retention time dimension (used for cohort entry and activity). */
+    private validateTimeDimension;
+    /** Validate the retention binding key (single member or per-cube mappings). */
+    private validateBindingKey;
+    /** Validate optional retention breakdown dimensions. */
+    private validateBreakdownDimensions;
+    /** Validate retention period bounds, granularity, and retention type. */
+    private validatePeriodsAndEnums;
+    /** Validate the (required) retention date range: presence, parseability, ordering. */
+    private validateDateRange;
     /**
      * Build the retention SQL query using CTEs
      *
@@ -38,10 +45,6 @@ export declare class RetentionQueryBuilder {
      * 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
      */
@@ -92,9 +95,4 @@ export declare class RetentionQueryBuilder {
      * 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;
 }

package/dist/server/cache-providers/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cache providers for Drizzle Cube
+ */
+export { MemoryCacheProvider } from './memory.js';
+export type { MemoryCacheProviderOptions } from './memory.js';

package/dist/server/{server/cache-providers → cache-providers}/memory.d.ts

@@ -1,4 +1,4 @@
-import { CacheProvider, CacheGetResult } from '../types';
+import { CacheProvider, CacheGetResult } from '../types/index.js';
 /**
  * Options for MemoryCacheProvider
  */

package/dist/server/{server/cache-utils.d.ts → cache-utils.d.ts}

@@ -1,4 +1,4 @@
-import { SemanticQuery, SecurityContext } from './types';
+import { SemanticQuery, SecurityContext } from './types/index.js';
 /**
  * Configuration for cache key generation
  */
@@ -15,10 +15,11 @@ export interface CacheKeyConfig {
  *
  * Key structure: {prefix}query:{queryHash}:ctx:{securityHash}
  *
- * Uses FNV-1a hash for:
- * - Speed: ~3x faster than SHA-256
- * - Simplicity: No dependencies required
- * - Sufficient collision resistance for cache keys
+ * Uses a 128-bit FNV-1a-based hash (see {@link strongHash}) for both the query
+ * and the security context. A 128-bit digest is required here for correctness,
+ * not just speed: the security-context hash provides tenant isolation, and a
+ * collision serves one tenant's cached result to another. The full input is
+ * hashed (no truncation) so large queries cannot collide on a shared prefix.
  *
  * @param query - The semantic query to cache
  * @param securityContext - Security context for tenant isolation
@@ -42,7 +43,7 @@ export declare function normalizeQuery(query: SemanticQuery): SemanticQuery;
  */
 export declare function sortObject<T>(obj: T): T;
 /**
- * FNV-1a hash - fast, non-cryptographic hash function
+ * FNV-1a hash - fast, non-cryptographic 32-bit hash function
  * Returns hex string for cache key readability
  *
  * Properties:
@@ -50,10 +51,29 @@ export declare function sortObject<T>(obj: T): T;
  * - Low collision rate for similar strings
  * - Deterministic across runs
  *
+ * Note: a 32-bit digest is too narrow to isolate tenants by itself — use
+ * {@link strongHash} for cache keys. Retained for backwards compatibility.
+ *
  * @param str - String to hash
  * @returns 8-character hex string
  */
 export declare function fnv1aHash(str: string): string;
+/**
+ * 128-bit FNV-1a-based hash for cache keys.
+ *
+ * Computes four independent 32-bit FNV-1a lanes (distinct offset bases, each
+ * mixed with the byte position) and concatenates them into a 32-character hex
+ * digest. This widens the key space from 2^32 to 2^128 so security-context and
+ * query collisions are vanishingly unlikely — collisions here are not merely a
+ * cache miss, they are a cross-tenant data-disclosure risk.
+ *
+ * The entire input is hashed (no truncation), and the input length is mixed in
+ * to disambiguate shared prefixes. `Math.imul` performs a true 32-bit multiply.
+ *
+ * @param str - String to hash
+ * @returns 32-character hex string (128 bits)
+ */
+export declare function strongHash(str: string): string;
 /**
  * Generate invalidation pattern for a cube
  * Used when cube data changes and all related cache entries need clearing

package/dist/server/compiler-metadata.d.ts

@@ -0,0 +1,11 @@
+import { Cube, MeasureMetadata, DimensionMetadata, CubeRelationshipMetadata, HierarchyMetadata, TimeGranularity } from './types/index.js';
+/** Default time granularities used when a time dimension omits `granularities`. */
+export declare const DEFAULT_TIME_GRANULARITIES: TimeGranularity[];
+/** Build measure metadata, normalizing drillMembers to fully-qualified names. */
+export declare function buildMeasureMetadata(cube: Cube): MeasureMetadata[];
+/** Build dimension metadata, including granularities for time dimensions. */
+export declare function buildDimensionMetadata(cube: Cube): DimensionMetadata[];
+/** Build relationship metadata from a cube's joins, resolving target cubes. */
+export declare function buildRelationshipMetadata(cube: Cube, cubes: Map<string, Cube>, getColumnName: (column: any) => string): CubeRelationshipMetadata[];
+/** Build hierarchy metadata, qualifying level names to full member names. */
+export declare function buildHierarchyMetadata(cube: Cube): HierarchyMetadata[];

package/dist/server/{server/compiler.d.ts → compiler.d.ts}

@@ -1,9 +1,12 @@
-import { SemanticQuery, QueryResult, SecurityContext, DatabaseExecutor, CubeMetadata, Cube, QueryAnalysis, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, RLSSetupFn } from './types';
+import { SemanticQuery, QueryResult, SecurityContext, DatabaseExecutor, CubeMetadata, Cube, QueryAnalysis, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, RLSSetupFn } from './types/index.js';
+import { PlanOptimiser } from './logical-plan/index.js';
+export { validateQueryAgainstCubes } from './query-validator.js';
 export declare class SemanticLayerCompiler {
     private cubes;
     private metadataCache?;
     private cacheConfig?;
     private rlsSetup?;
+    private planOptimiser?;
     private db?;
     private schema?;
     private engineType?;
@@ -21,6 +24,11 @@ export declare class SemanticLayerCompiler {
          * Dry-run/SQL generation is NOT wrapped in a transaction.
          */
         rlsSetup?: RLSSetupFn;
+        /**
+         * Optional logical-plan optimiser injected into every QueryExecutor.
+         * Defaults to a no-op IdentityOptimiser when omitted.
+         */
+        planOptimiser?: PlanOptimiser;
     });
     /**
      * Set or update the database connection
@@ -105,14 +113,8 @@ export declare class SemanticLayerCompiler {
      * Handles different column types and extracts the actual column name
      */
     private getColumnName;
-    /**
-     * Default time granularities for time dimensions (ordered from least to most granular)
-     * Used when dimension.granularities is not specified
-     */
-    private static readonly DEFAULT_TIME_GRANULARITIES;
     /**
      * Generate cube metadata for API responses from cubes
-     * Optimized version that minimizes object iterations
      * Includes drill-down support: drillMembers on measures, granularities on time dimensions, hierarchies
      */
     private generateCubeMetadata;
@@ -208,11 +210,3 @@ export declare class SemanticLayerCompiler {
      */
     analyzeQuery(query: SemanticQuery, securityContext: SecurityContext): QueryAnalysis;
 }
-/**
- * Validate a query against a cubes map
- * Standalone function that can be used by both compiler and executor
- */
-export declare function validateQueryAgainstCubes(cubes: Map<string, Cube>, query: SemanticQuery): {
-    isValid: boolean;
-    errors: string[];
-};

package/dist/server/{server/cube-utils.d.ts → cube-utils.d.ts}

@@ -1,5 +1,5 @@
 import { SQL, AnyColumn } from 'drizzle-orm';
-import { Cube, CubeJoin, QueryContext, MultiCubeQueryContext, SqlExpression, SecurityContext } from './types';
+import { Cube, CubeJoin, Dimension, QueryContext, MultiCubeQueryContext, SqlExpression } from './types/index.js';
 /**
  * Resolve cube reference (handles direct, lazy, and string name references)
  *
@@ -99,6 +99,18 @@ export declare function safeKey(key: string): string;
  * @returns Isolated SQL expression safe for reuse
  */
 export declare function resolveSqlExpression(expr: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL), ctx: QueryContext): AnyColumn | SQL;
+/**
+ * Resolve a dimension's SQL expression for use in a filter condition.
+ *
+ * For non-time dimensions, use the raw column so Drizzle preserves column type
+ * metadata for proper parameter binding (e.g. UUID columns need type info) — this
+ * deliberately bypasses isolateSqlExpression. For time dimensions, keep isolated
+ * SQL because normalizeDate() returns strings.
+ *
+ * Centralises the filter-field resolution that was previously copy-pasted across
+ * the filter builder, executor, and funnel/flow/retention builders.
+ */
+export declare function resolveFilterFieldExpr(dimension: Dimension, ctx: QueryContext): AnyColumn | SQL;
 /**
  * Helper to create multi-cube query context
  */
@@ -111,6 +123,16 @@ export declare function isFunctionSqlExpression(expr: SqlExpression): expr is (c
  * Helper function to create cubes
  */
 export declare function defineCube(name: string, definition: Omit<Cube, 'name'>): Cube;
+/**
+ * Build the Drizzle join condition for a regular (belongsTo/hasOne/hasMany)
+ * join from its symbolic CubeJoin definition. Columns are isolated to prevent
+ * Drizzle's mutable queryChunks from corrupting reused expressions. The
+ * condition is symmetric, so it is correct for reversed joins as-is.
+ *
+ * This is the materialization counterpart used by DrizzlePlanBuilder; it
+ * mirrors JoinPathResolver.buildJoinCondition(joinDef, null, null).
+ */
+export declare function buildRegularJoinCondition(joinDef: CubeJoin): SQL;
 /**
  * Expanded join information for belongsToMany relationships
  */
@@ -121,13 +143,16 @@ export interface ExpandedBelongsToManyJoin {
         table: any;
         condition: SQL;
     }>;
-    /** Security conditions for junction table (if any) */
-    junctionSecurityConditions?: SQL[];
 }
 /**
  * Expand a belongsToMany join into junction table joins
  * This converts a many-to-many relationship into two separate joins:
  * 1. Source cube -> Junction table
  * 2. Junction table -> Target cube
+ *
+ * Junction-table security is intentionally NOT materialized here: it must be
+ * applied (in the WHERE clause) at physical-build time from the stored
+ * `through.securitySql` function with the request's security context, so the
+ * join conditions here are a pure function of the join definition.
  */
-export declare function expandBelongsToManyJoin(joinDef: CubeJoin, securityContext: SecurityContext): ExpandedBelongsToManyJoin;
+export declare function expandBelongsToManyJoin(joinDef: CubeJoin): ExpandedBelongsToManyJoin;

package/dist/server/{server/database-utils.d.ts → database-utils.d.ts}

@@ -1,4 +1,4 @@
-import { DatabaseAdapter } from './adapters/base-adapter';
+import { DatabaseAdapter } from './adapters/base-adapter.js';
 /**
  * Create a database adapter for the specified engine type
  * @param engineType - The database engine type

package/dist/server/execution/annotation-builder.d.ts

@@ -0,0 +1,12 @@
+import { PhysicalQueryPlan, SemanticQuery, MeasureAnnotation, DimensionAnnotation, TimeDimensionAnnotation } from '../types/index.js';
+/**
+ * Generate annotations for UI metadata - unified approach.
+ * Collects measure/dimension/timeDimension titles from every cube in the plan
+ * (primary + joins + multi-fact merge groups).
+ */
+export declare function buildAnnotations(queryPlan: PhysicalQueryPlan, query: SemanticQuery): {
+    measures: Record<string, MeasureAnnotation>;
+    dimensions: Record<string, DimensionAnnotation>;
+    segments: Record<string, never>;
+    timeDimensions: Record<string, TimeDimensionAnnotation>;
+};

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

@@ -0,0 +1,19 @@
+import { Cube, SemanticQuery, QueryContext } from '../types/index.js';
+import { FilterCacheManager } from '../filter-cache.js';
+import { DrizzleSqlBuilder } from '../physical-plan/drizzle-sql-builder.js';
+export declare class FilterCachePreloader {
+    private readonly queryBuilder;
+    constructor(queryBuilder: DrizzleSqlBuilder);
+    /**
+     * 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
+     */
+    preload(query: SemanticQuery, filterCache: FilterCacheManager, cubes: Map<string, Cube>, context: QueryContext): void;
+    /** Resolve the dimension a filter/time-dimension member refers to, or null. */
+    private resolveMemberDimension;
+    /** Pre-build and cache the SQL for a single simple (non-logical) filter. */
+    private preloadRegularFilter;
+    /** Pre-build and cache the date-range SQL for a single time dimension. */
+    private preloadTimeDimensionFilter;
+}

package/dist/server/execution/mode-router.d.ts

@@ -0,0 +1,25 @@
+import { Cube, SemanticQuery } from '../types/index.js';
+import { ComparisonQueryBuilder } from '../builders/comparison-query-builder.js';
+import { FunnelQueryBuilder } from '../builders/funnel-query-builder.js';
+import { FlowQueryBuilder } from '../builders/flow-query-builder.js';
+import { RetentionQueryBuilder } from '../builders/retention-query-builder.js';
+export type QueryExecutionMode = 'regular' | 'comparison' | 'funnel' | 'flow' | 'retention';
+export interface ModeRouterBuilders {
+    comparison: ComparisonQueryBuilder;
+    funnel: FunnelQueryBuilder;
+    flow: FlowQueryBuilder;
+    retention: RetentionQueryBuilder;
+}
+export declare class ModeRouter {
+    private readonly builders;
+    constructor(builders: ModeRouterBuilders);
+    /**
+     * Resolve the single active execution mode for a query.
+     * Throws if more than one analysis mode is present.
+     */
+    resolveMode(query: SemanticQuery): QueryExecutionMode;
+    /**
+     * Validate a query for its resolved mode. Throws a translated error on failure.
+     */
+    validateForMode(mode: QueryExecutionMode, cubes: Map<string, Cube>, query: SemanticQuery): void;
+}

package/dist/server/execution/query-result-cache.d.ts

@@ -0,0 +1,21 @@
+import { SecurityContext, SemanticQuery, QueryResult, CacheConfig } from '../types/index.js';
+export declare class QueryResultCache {
+    private readonly cacheConfig?;
+    constructor(cacheConfig?: CacheConfig | undefined);
+    /**
+     * Returns the cache key when caching is enabled and a provider is configured,
+     * otherwise undefined (which disables lookup and store).
+     */
+    generateKey(query: SemanticQuery, securityContext: SecurityContext): string | undefined;
+    /**
+     * Look up a cached result. Returns the cached value (with cache metadata
+     * attached) on a hit, or undefined on miss / bypass / no-cache. Emits
+     * hit/miss events; lookup errors are non-fatal.
+     */
+    lookup(cacheKey: string | undefined, skipCache: boolean): Promise<QueryResult | undefined>;
+    /**
+     * Store a fresh result under the given key. No-ops when caching is disabled
+     * or the key is undefined. Store errors are non-fatal.
+     */
+    store(cacheKey: string | undefined, result: QueryResult): Promise<void>;
+}