drizzle-cube 0.5.7 → 0.5.8

package/dist/server/server/prompts/step1-shape-prompt.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Step 1: Query Shape Determination Prompt
+ *
+ * This prompt is used in the first stage of the multi-stage AI query generation flow.
+ * It analyzes the user's request to determine:
+ * 1. Whether this is a regular query or funnel query
+ * 2. Which dimensions need actual values from the database
+ *
+ * The output of this step determines whether we need to fetch dimension values
+ * from the database before generating the final query.
+ *
+ * @see https://github.com/cliftonc/drizzle-cube/blob/main/src/server/prompts/step1-shape-prompt.ts
+ */
+/**
+ * System prompt for Step 1: Analyze query shape and identify dimensions needing values.
+ *
+ * Placeholders:
+ * - {CUBE_SCHEMA} - JSON-formatted cube schema
+ * - {USER_PROMPT} - User's natural language query
+ */
+export declare const STEP1_SYSTEM_PROMPT = "You are analyzing a data query request to determine its structure.\n\nGiven the cube schema and user query, determine:\n1. What type of query this is (regular query or funnel)\n2. What dimensions will need filtering with specific categorical values\n\nCUBE SCHEMA:\n{CUBE_SCHEMA}\n\nRESPONSE FORMAT:\nReturn JSON with:\n{\n  \"queryType\": \"query\" | \"funnel\",\n  \"dimensionsNeedingValues\": [\"CubeName.dimensionName\", ...],\n  \"reasoning\": \"Brief explanation of what dimensions need values and why\"\n}\n\nRULES:\n- For funnels, you'll typically need values for the event type dimension to define the steps\n- For regular queries with categorical filters, list those dimensions where you need to know valid values\n- Only list dimensions where you would otherwise have to guess the filter values\n- If no dimension values are needed (e.g., numeric filters, date ranges, simple aggregations), return empty array\n- Common dimensions needing values: status fields, type fields, category fields, event types\n- Do NOT list dimensions for: date ranges, numeric comparisons, name searches\n\nUSER QUERY:\n{USER_PROMPT}\n\nReturn ONLY valid JSON - no explanations or markdown:";
+/**
+ * Build the Step 1 prompt for query shape analysis
+ *
+ * @param cubeSchema - JSON-formatted cube schema
+ * @param userPrompt - User's natural language query
+ * @returns Complete prompt ready to send to AI
+ */
+export declare function buildStep1Prompt(cubeSchema: string, userPrompt: string): string;

package/dist/server/server/prompts/step2-complete-prompt.d.ts

@@ -0,0 +1,19 @@
+import { DimensionValues } from './types.js';
+/**
+ * System prompt for Step 2: Generate final query with actual dimension values.
+ *
+ * Placeholders:
+ * - {CUBE_SCHEMA} - JSON-formatted cube schema
+ * - {USER_PROMPT} - User's natural language query
+ * - {DIMENSION_VALUES} - JSON object of dimension names to their actual values
+ */
+export declare const STEP2_SYSTEM_PROMPT = "Complete the data query using actual dimension values from the database.\n\nORIGINAL USER REQUEST: {USER_PROMPT}\n\nCUBE SCHEMA:\n{CUBE_SCHEMA}\n\nAVAILABLE DIMENSION VALUES (from the actual database):\n{DIMENSION_VALUES}\n\nComplete the query using ONLY the values listed above for any dimension filters.\nDo NOT invent or guess filter values - use exactly what's available.\nMatch user intent to the closest available values (e.g., if user says \"opened\" but only \"created\" exists, use \"created\").\n\nRESPONSE FORMAT (same as single-step):\n{\n  \"query\": { /* Cube.js query OR funnel query with actual filter values */ },\n  \"chartType\": \"line\"|\"bar\"|\"area\"|\"pie\"|\"scatter\"|\"bubble\"|\"table\"|\"funnel\",\n  \"chartConfig\": {\n    \"xAxis\": string[],\n    \"yAxis\": string[],\n    \"series\": string[],\n    \"sizeField\": string,\n    \"colorField\": string\n  }\n}\n\nFUNNEL QUERY STRUCTURE (if queryType was \"funnel\"):\n{\n  \"funnel\": {\n    \"bindingKey\": \"PREvents.prNumber\",\n    \"timeDimension\": \"PREvents.timestamp\",\n    \"steps\": [\n      {\n        \"name\": \"Created\",\n        \"filter\": [\n          { \"member\": \"PREvents.eventType\", \"operator\": \"equals\", \"values\": [\"created\"] },\n          { \"member\": \"PREvents.timestamp\", \"operator\": \"inDateRange\", \"values\": [\"last 6 months\"] }\n        ]\n      },\n      {\n        \"name\": \"Merged\",\n        \"filter\": { \"member\": \"PREvents.eventType\", \"operator\": \"equals\", \"values\": [\"merged\"] }\n      }\n    ],\n    \"includeTimeMetrics\": true\n  }\n}\n\nCRITICAL FILTER FORMAT RULES:\n- filter MUST be a flat array of filter objects: [{ member, operator, values }, ...]\n- filter MUST NOT be nested arrays: NOT [[{ member, operator, values }]]\n- For a single filter, use object format: { \"member\": \"...\", \"operator\": \"...\", \"values\": [...] }\n- For multiple filters on step 0, use flat array: [{ filter1 }, { filter2 }] (NOT [[filter1, filter2]])\n- The time filter (inDateRange) goes ONLY on step 0's filter, not on other steps.\n\nReturn ONLY valid JSON - no explanations or markdown:";
+/**
+ * Build the Step 2 prompt with actual dimension values from the database
+ *
+ * @param cubeSchema - JSON-formatted cube schema
+ * @param userPrompt - User's natural language query
+ * @param dimensionValues - Actual dimension values fetched from database
+ * @returns Complete prompt ready to send to AI
+ */
+export declare function buildStep2Prompt(cubeSchema: string, userPrompt: string, dimensionValues: DimensionValues): string;

package/dist/server/server/prompts/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Types for AI prompt building
+ *
+ * These types define the structure of data passed between the multi-stage
+ * AI query generation flow.
+ *
+ * @see https://github.com/cliftonc/drizzle-cube/blob/main/src/server/prompts/types.ts
+ */
+/**
+ * Context required to build any AI prompt
+ */
+export interface PromptContext {
+    /** JSON-formatted cube schema with measures, dimensions, and relationships */
+    cubeSchema: string;
+    /** The user's natural language query */
+    userPrompt: string;
+}
+/**
+ * Actual dimension values fetched from the database
+ * Used in Step 2 to provide real values for filter generation
+ */
+export interface DimensionValues {
+    /** Map of dimension name to array of distinct values */
+    [dimensionName: string]: string[];
+}
+/**
+ * Result from Step 1: Query shape analysis
+ * Determines what type of query to generate and what dimension values are needed
+ */
+export interface Step1Result {
+    /** Type of query to generate */
+    queryType: 'query' | 'funnel';
+    /** Dimensions that need actual values from the database for filters */
+    dimensionsNeedingValues: string[];
+    /** AI's reasoning for why these dimensions need values */
+    reasoning: string;
+}

package/dist/server/server/resolvers/calculated-measure-resolver.d.ts

@@ -0,0 +1,93 @@
+import { Cube, Measure } from '../types/cube';
+/**
+ * Dependency information for a calculated measure
+ */
+export interface MeasureDependency {
+    /** Full measure name (e.g., "Cube.measure" or "measure") */
+    measureName: string;
+    /** Referenced cube name (null if same cube) */
+    cubeName: string | null;
+    /** Referenced field name */
+    fieldName: string;
+}
+/**
+ * Calculated Measure Resolver
+ * Manages dependency resolution for calculated measures
+ */
+export declare class CalculatedMeasureResolver {
+    private dependencyGraph;
+    private cubes;
+    constructor(cubes: Map<string, Cube> | Cube);
+    /**
+     * Extract {member} references from calculatedSql template
+     * Supports both {measure} and {Cube.measure} syntax
+     *
+     * @param calculatedSql - Template string with {member} references
+     * @returns Array of dependency information
+     */
+    extractDependencies(calculatedSql: string): MeasureDependency[];
+    /**
+     * Build dependency graph for all calculated measures in a cube
+     *
+     * @param cube - The cube containing measures
+     */
+    buildGraph(cube: Cube): void;
+    /**
+     * Build dependency graph for multiple cubes
+     *
+     * @param cubes - Map of cubes to analyze
+     */
+    buildGraphForMultipleCubes(cubes: Map<string, Cube>): void;
+    /**
+     * Calculate in-degree for each node (number of measures depending on it)
+     */
+    private calculateInDegrees;
+    /**
+     * Perform topological sort using Kahn's algorithm
+     * Returns measures in dependency order (dependencies first)
+     *
+     * @param measureNames - List of measure names to sort
+     * @returns Sorted array of measure names
+     * @throws Error if circular dependency detected
+     */
+    topologicalSort(measureNames: string[]): string[];
+    /**
+     * Detect circular dependencies using DFS
+     * Returns the cycle path if found, null otherwise
+     *
+     * @returns Array representing the cycle, or null
+     */
+    detectCycle(): string[] | null;
+    /**
+     * DFS helper for cycle detection
+     */
+    private dfs;
+    /**
+     * Get all dependencies for a specific measure (direct and transitive)
+     *
+     * @param measureName - Full measure name (e.g., "Cube.measure")
+     * @returns Set of all dependency measure names
+     */
+    getAllDependencies(measureName: string): Set<string>;
+    /**
+     * Validate that all dependencies exist
+     *
+     * @param cube - The cube to validate
+     * @throws Error if dependencies are missing
+     */
+    validateDependencies(cube: Cube): void;
+    /**
+     * Auto-populate dependencies array for calculated measures
+     * Updates the measure objects with detected dependencies
+     *
+     * @param cube - The cube to update
+     */
+    populateDependencies(cube: Cube): void;
+    /**
+     * Check if a measure is a calculated measure
+     *
+     * @param measure - The measure to check
+     * @returns True if the measure is calculated
+     */
+    static isCalculatedMeasure(measure: Measure): boolean;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Resolvers Index
+ * Re-exports resolver components for modular imports
+ */
+export { CalculatedMeasureResolver } from './calculated-measure-resolver';
+export { JoinPathResolver } from './join-path-resolver';

package/dist/server/server/resolvers/join-path-resolver.d.ts

@@ -0,0 +1,152 @@
+import { Cube, CubeJoin } from '../types';
+import { SQL } from 'drizzle-orm';
+/**
+ * Internal representation of a join path step
+ * Used during path finding - simpler than the public JoinPathStep analysis type
+ */
+export interface InternalJoinPathStep {
+    /** Source cube name */
+    fromCube: string;
+    /** Target cube name */
+    toCube: string;
+    /** The join definition from the source cube */
+    joinDef: CubeJoin;
+    /** True when this step was discovered via a reversed edge (target cube defines the join back to source) */
+    reversed?: boolean;
+}
+/**
+ * Score breakdown for a candidate preferred path.
+ */
+export interface PreferredPathScoreBreakdown {
+    preferredJoinBonus: number;
+    preferredCubeBonus: number;
+    lengthPenalty: number;
+}
+/**
+ * A scored candidate path considered by preferred-path selection.
+ */
+export interface PreferredPathCandidateScore {
+    path: InternalJoinPathStep[];
+    score: number;
+    usesPreferredJoin: boolean;
+    preferredCubesInPath: number;
+    usesProcessed: boolean;
+    scoreBreakdown: PreferredPathScoreBreakdown;
+}
+/**
+ * Detailed preferred-path selection output for analysis/debug UIs.
+ */
+export interface PreferredPathSelection {
+    strategy: 'preferred' | 'fallbackShortest';
+    preferredCubes: string[];
+    selectedIndex: number;
+    candidates: PreferredPathCandidateScore[];
+    selectedPath: InternalJoinPathStep[] | null;
+}
+/**
+ * Resolves join paths between cubes and manages connectivity caching.
+ * Supports bidirectional path finding: both forward (outgoing) joins and
+ * reverse (incoming) joins are traversable. Reversed steps are marked with
+ * `reversed: true` so downstream code can adjust join type and analysis.
+ */
+export declare class JoinPathResolver {
+    private cubes;
+    private connectivityCache;
+    /** Maps cubeName → joins that TARGET that cube (incoming edges) */
+    private reverseIndex;
+    /**
+     * @param cubes Map of cube name to cube definition
+     */
+    constructor(cubes: Map<string, Cube>);
+    /**
+     * Build reverse adjacency index: for each cube's outgoing join A→B,
+     * store an entry under B pointing back to A.
+     *
+     * Excludes belongsToMany joins because reversing them requires swapping
+     * sourceKey/targetKey in the junction table configuration, which is
+     * error-prone. The 2-hop forward path through the junction table handles
+     * these relationships correctly.
+     */
+    private buildReverseIndex;
+    /**
+     * Find the shortest join path from source cube to target cube
+     * Uses BFS algorithm for optimal path discovery
+     *
+     * @param fromCube Source cube name
+     * @param toCube Target cube name
+     * @param alreadyProcessed Set of cubes to exclude from path finding
+     * @returns Array of join steps or null if no path exists
+     */
+    findPath(fromCube: string, toCube: string, alreadyProcessed?: Set<string>): InternalJoinPathStep[] | null;
+    /**
+     * Find path that prefers going through specified cubes when possible
+     * Used when certain cubes have measures in the query - ensures joins go through
+     * the semantically correct path (e.g., through junction tables when their measures are used)
+     *
+     * IMPORTANT: This method allows paths to go THROUGH already-processed cubes (as intermediate
+     * steps) but won't return them as new cubes to add. This is crucial for preferring paths
+     * through cubes that have measures (like junction tables).
+     *
+     * Path scoring priority (highest to lowest):
+     * 1. Paths using joins with `preferredFor` that includes the target cube (score +10)
+     * 2. Paths going through cubes with measures in the query (score +1 per cube)
+     * 3. Paths reusing already-processed cubes
+     * 4. Shorter paths
+     *
+     * @param fromCube Source cube name
+     * @param toCube Target cube name
+     * @param preferredCubes Set of cube names to prefer in the path (usually cubes with measures)
+     * @param alreadyProcessed Set of cubes already in the join plan (can be used as intermediates)
+     * @returns Array of join steps or null if no path exists
+     */
+    findPathPreferring(fromCube: string, toCube: string, preferredCubes: Set<string>, alreadyProcessed?: Set<string>): InternalJoinPathStep[] | null;
+    /**
+     * Find preferred path with candidate scoring telemetry.
+     * Used by analysis/debug panels to explain planner decisions.
+     */
+    findPathPreferringDetailed(fromCube: string, toCube: string, preferredCubes: Set<string>, alreadyProcessed?: Set<string>): PreferredPathSelection;
+    /**
+     * Find all possible paths between two cubes (up to maxDepth)
+     * Used by findPathPreferring to evaluate multiple paths
+     *
+     * @param fromCube Source cube name
+     * @param toCube Target cube name
+     * @param alreadyProcessed Set of cubes to exclude from path finding
+     * @param maxDepth Maximum path length to search (default 4 to avoid explosion)
+     * @returns Array of all valid paths
+     */
+    private findAllPaths;
+    /**
+     * Check if a cube can reach all other cubes in the list via joins
+     *
+     * @param fromCube Starting cube name
+     * @param allCubes List of all cubes that must be reachable
+     * @returns true if all cubes are reachable
+     */
+    canReachAll(fromCube: string, allCubes: string[]): boolean;
+    /**
+     * Forward-only path finding (no reverse edges).
+     * Used by canReachAll for primary cube selection to preserve join semantics.
+     */
+    private findForwardOnlyPath;
+    /**
+     * Build SQL join condition from join definition
+     *
+     * @param joinDef The cube join definition
+     * @param sourceAlias Optional alias for source table (null uses actual column)
+     * @param targetAlias Optional alias for target table (null uses actual column)
+     * @returns SQL condition for the join
+     */
+    buildJoinCondition(joinDef: CubeJoin, sourceAlias: string | null, targetAlias: string | null): SQL;
+    /**
+     * Get all reachable cubes from a starting cube
+     * Useful for analyzing cube connectivity
+     *
+     * @param fromCube Starting cube name
+     * @returns Set of all reachable cube names
+     */
+    getReachableCubes(fromCube: string): Set<string>;
+    private getCacheKey;
+    private getFromCache;
+    private setInCache;
+}

package/dist/server/server/template-substitution.d.ts

@@ -0,0 +1,57 @@
+import { SQL } from 'drizzle-orm';
+import { Cube, QueryContext } from './types/cube';
+/**
+ * Resolved measure SQL builders
+ * Maps full measure names (e.g., "Cube.measure") to functions that build their SQL
+ * Using functions instead of SQL objects avoids mutation and shared reference issues
+ */
+export type ResolvedMeasures = Map<string, () => SQL>;
+/**
+ * Substitution context
+ */
+export interface SubstitutionContext {
+    /** The cube being processed */
+    cube: Cube;
+    /** All available cubes for cross-cube references */
+    allCubes: Map<string, Cube>;
+    /** Already resolved measure SQL expressions */
+    resolvedMeasures: ResolvedMeasures;
+    /** Query context for SQL generation */
+    queryContext: QueryContext;
+}
+/**
+ * Substitute {member} references in calculatedSql template
+ *
+ * Replaces {member} with the corresponding SQL expression from resolvedMeasures.
+ * Supports both same-cube ({measure}) and cross-cube ({Cube.measure}) references.
+ *
+ * @param calculatedSql - Template string with {member} references
+ * @param context - Substitution context
+ * @returns SQL expression with substituted values
+ * @throws Error if referenced measure is not resolved
+ */
+export declare function substituteTemplate(calculatedSql: string, context: SubstitutionContext): SQL;
+/**
+ * Validate calculatedSql template syntax
+ *
+ * @param calculatedSql - Template string to validate
+ * @returns Validation result
+ */
+export declare function validateTemplateSyntax(calculatedSql: string): {
+    isValid: boolean;
+    errors: string[];
+};
+/**
+ * Check if a template contains any member references
+ *
+ * @param calculatedSql - Template string to check
+ * @returns True if template contains {member} references
+ */
+export declare function hasMemberReferences(calculatedSql: string): boolean;
+/**
+ * Get list of all unique member references in a template
+ *
+ * @param calculatedSql - Template string
+ * @returns Array of unique full member names (e.g., ["Cube.measure", "otherMeasure"])
+ */
+export declare function getMemberReferences(calculatedSql: string, currentCube: string): string[];

package/dist/server/server/types/analysis.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Query Analysis Types
+ * Provides transparency into query planning decisions for debugging
+ */
+/**
+ * Reason why a cube was selected as primary (FROM table)
+ */
+export type PrimaryCubeSelectionReason = 'most_dimensions' | 'most_connected' | 'alphabetical_fallback' | 'single_cube';
+/**
+ * Candidate cube considered for primary selection
+ */
+export interface PrimaryCubeCandidate {
+    /** Cube name */
+    cubeName: string;
+    /** Number of dimensions from this cube in the query */
+    dimensionCount: number;
+    /** Number of join definitions on this cube */
+    joinCount: number;
+    /** Whether this cube can reach all other required cubes */
+    canReachAll: boolean;
+}
+/**
+ * Primary cube selection analysis
+ */
+export interface PrimaryCubeAnalysis {
+    /** Name of the selected primary cube */
+    selectedCube: string;
+    /** Reason for selection */
+    reason: PrimaryCubeSelectionReason;
+    /** Human-readable explanation */
+    explanation: string;
+    /** Other candidates that were considered */
+    candidates?: PrimaryCubeCandidate[];
+}
+/**
+ * Single step in a join path
+ */
+export interface JoinPathStep {
+    /** Source cube name */
+    fromCube: string;
+    /** Target cube name */
+    toCube: string;
+    /** Relationship type used (effective, after reversal if applicable) */
+    relationship: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    /** SQL join type that will be used */
+    joinType: 'inner' | 'left' | 'right' | 'full';
+    /** Join condition columns */
+    joinColumns: Array<{
+        sourceColumn: string;
+        targetColumn: string;
+    }>;
+    /** Junction table info for belongsToMany */
+    junctionTable?: {
+        tableName: string;
+        sourceColumns: string[];
+        targetColumns: string[];
+    };
+    /** True when this step was discovered via a reversed edge */
+    reversed?: boolean;
+}
+/**
+ * Complete join path from primary to target cube
+ */
+export interface JoinPathAnalysis {
+    /** Target cube name */
+    targetCube: string;
+    /** Whether a path was found */
+    pathFound: boolean;
+    /** The join steps (if found) */
+    path?: JoinPathStep[];
+    /** Total path length */
+    pathLength?: number;
+    /** Error message if path not found */
+    error?: string;
+    /** Cubes that were visited during BFS search */
+    visitedCubes?: string[];
+    /** Path selection decision and scoring details (when preferred routing is used) */
+    selection?: {
+        strategy: 'shortest' | 'preferred' | 'fallbackShortest';
+        preferredCubes?: string[];
+        selectedRank?: number;
+        selectedScore?: number;
+        candidates?: Array<{
+            rank: number;
+            score: number;
+            usesPreferredJoin: boolean;
+            preferredCubesInPath: number;
+            usesProcessed: boolean;
+            scoreBreakdown: {
+                preferredJoinBonus: number;
+                preferredCubeBonus: number;
+                lengthPenalty: number;
+            };
+            path: JoinPathStep[];
+        }>;
+    };
+}
+/**
+ * Pre-aggregation CTE analysis
+ */
+/**
+ * Reason why a cube requires a CTE
+ */
+export type CTEReason = 'hasMany' | 'fanOutPrevention';
+export interface PreAggregationAnalysis {
+    /** Cube being pre-aggregated */
+    cubeName: string;
+    /** CTE alias in the query */
+    cteAlias: string;
+    /** Why this cube needs a CTE (human-readable explanation) */
+    reason: string;
+    /** Typed reason for programmatic use */
+    reasonType?: CTEReason;
+    /** Measures included in CTE (aggregate measures + window base measures) */
+    measures: string[];
+    /** Join keys used */
+    joinKeys: Array<{
+        sourceColumn: string;
+        targetColumn: string;
+    }>;
+    /**
+     * Type of CTE:
+     * - 'aggregate': Standard CTE with GROUP BY (count, sum, avg, etc.)
+     *
+     * Note: Window function CTEs are no longer used. Post-aggregation window
+     * functions are applied in the outer query after data is aggregated.
+     */
+    cteType?: 'aggregate';
+}
+/**
+ * Query structure summary
+ */
+export interface QuerySummary {
+    /** Query type: 'single_cube', 'multi_cube_join', or 'multi_cube_cte' */
+    queryType: 'single_cube' | 'multi_cube_join' | 'multi_cube_cte';
+    /** Strategy selected for multiplied-measure handling / multi-fact merge */
+    measureStrategy?: 'simple' | 'keysDeduplication' | 'ctePreAggregateFallback' | 'multiFactMerge';
+    /** Total number of joins */
+    joinCount: number;
+    /** Total number of CTEs */
+    cteCount: number;
+    /** Has hasMany relationships requiring aggregation */
+    hasPreAggregation: boolean;
+    /**
+     * Whether query contains post-aggregation window function measures.
+     * These window functions (lag, lead, rank, etc.) operate on aggregated
+     * data and are applied in the outer query after CTEs.
+     */
+    hasWindowFunctions?: boolean;
+}
+/**
+ * Structured planner trace for explain/dry-run UIs.
+ * Captures key decisions made during logical planning.
+ */
+export interface PlanningTraceStep {
+    /** Pipeline phase name */
+    phase: 'cube_usage' | 'primary_cube_selection' | 'join_planning' | 'cte_planning' | 'measure_strategy' | 'warnings';
+    /** Short summary of what was decided */
+    decision: string;
+    /** Optional machine-readable details */
+    details?: Record<string, unknown>;
+}
+export interface PlanningTrace {
+    /** Ordered decision trace */
+    steps: PlanningTraceStep[];
+}
+/**
+ * Complete query analysis result
+ */
+export interface QueryAnalysis {
+    /** Timestamp of analysis */
+    timestamp: string;
+    /** Number of cubes involved */
+    cubeCount: number;
+    /** List of all cubes used */
+    cubesInvolved: string[];
+    /** Primary cube selection details */
+    primaryCube: PrimaryCubeAnalysis;
+    /** Join path analysis for each joined cube */
+    joinPaths: JoinPathAnalysis[];
+    /** Pre-aggregation CTE details */
+    preAggregations: PreAggregationAnalysis[];
+    /** Overall query structure summary */
+    querySummary: QuerySummary;
+    /** Warnings or potential issues */
+    warnings?: string[];
+    /** Structured decision trace for debugging and dry-run UIs */
+    planningTrace?: PlanningTrace;
+}