@quereus/quereus 0.1.0

package/dist/src/planner/cache/reference-graph.js

@@ -0,0 +1,139 @@
+/**
+ * Reference graph builder for materialization advisory
+ * Analyzes plan tree to identify nodes that would benefit from caching
+ */
+import { createLogger } from '../../common/logger.js';
+import { PlanNodeType } from '../nodes/plan-node-type.js';
+import { JoinNode } from '../nodes/join-node.js';
+const log = createLogger('optimizer:cache:reference-graph');
+/**
+ * Builds a reference graph for materialization decisions
+ */
+export class ReferenceGraphBuilder {
+    tuning;
+    refMap = new Map();
+    visited = new Set();
+    constructor(tuning) {
+        this.tuning = tuning;
+    }
+    /**
+     * Build reference statistics for all nodes in the plan tree
+     */
+    buildReferenceGraph(root) {
+        this.refMap.clear();
+        this.visited.clear();
+        // First pass: count parent references
+        this.countReferences(root, false);
+        // Second pass: identify loop contexts
+        this.identifyLoopContexts(root, false);
+        log('Built reference graph with %d nodes', this.refMap.size);
+        return new Map(this.refMap);
+    }
+    /**
+     * First pass: count how many parents reference each node
+     */
+    countReferences(node, inLoop) {
+        if (this.visited.has(node)) {
+            // Node seen again - increment parent count
+            const stats = this.refMap.get(node);
+            if (stats) {
+                stats.parentCount++;
+            }
+            return;
+        }
+        this.visited.add(node);
+        // Initialize stats for this node
+        const stats = {
+            parentCount: 1, // First time seeing this node
+            appearsInLoop: inLoop,
+            estimatedRows: this.getEstimatedRows(node),
+            deterministic: this.isDeterministic(node)
+        };
+        this.refMap.set(node, stats);
+        // Recurse to children
+        this.visitChildren(node, (child) => {
+            this.countReferences(child, inLoop);
+        });
+    }
+    /**
+     * Second pass: identify nodes that appear in loop contexts
+     */
+    identifyLoopContexts(node, inLoop) {
+        const stats = this.refMap.get(node);
+        if (!stats)
+            return;
+        // Update loop status if we're now in a loop context
+        if (inLoop && !stats.appearsInLoop) {
+            stats.appearsInLoop = true;
+            log('Node %s marked as appearing in loop', node.nodeType);
+        }
+        // Determine if children are in loop context
+        if (node instanceof JoinNode && node.joinType === 'inner') {
+            // Right side of nested loop join is in loop context
+            const [left, right] = node.getRelations();
+            this.identifyLoopContexts(left, inLoop);
+            this.identifyLoopContexts(right, true); // Right side is in loop
+        }
+        else {
+            // Recurse to all children with current loop status
+            this.visitChildren(node, (child) => {
+                this.identifyLoopContexts(child, inLoop);
+            });
+        }
+    }
+    /**
+     * Visit all children of a node
+     */
+    visitChildren(node, visitor) {
+        // Visit scalar expression children
+        for (const child of node.getChildren()) {
+            visitor(child);
+        }
+        // Visit relational children
+        if ('getRelations' in node) {
+            for (const relation of node.getRelations()) {
+                visitor(relation);
+            }
+        }
+    }
+    /**
+     * Get estimated row count for a node
+     */
+    getEstimatedRows(node) {
+        if ('estimatedRows' in node && typeof node.estimatedRows === 'number') {
+            return node.estimatedRows;
+        }
+        if (node.physical?.estimatedRows) {
+            return node.physical.estimatedRows;
+        }
+        return this.tuning.defaultRowEstimate;
+    }
+    /**
+     * Determine if a node is deterministic
+     */
+    isDeterministic(node) {
+        // Check physical properties first
+        if (node.physical?.deterministic !== undefined) {
+            return node.physical.deterministic;
+        }
+        // Node-type specific deterministic analysis
+        switch (node.nodeType) {
+            case PlanNodeType.TableScan:
+            case PlanNodeType.Values:
+            case PlanNodeType.Project:
+            case PlanNodeType.Filter:
+            case PlanNodeType.Sort:
+            case PlanNodeType.Aggregate:
+            case PlanNodeType.StreamAggregate:
+                return true;
+            case PlanNodeType.TableFunctionCall:
+                // Would need to check if the table function is deterministic
+                // For now, assume non-deterministic to be safe
+                return false;
+            default:
+                // Conservative default - assume deterministic unless proven otherwise
+                return true;
+        }
+    }
+}
+//# sourceMappingURL=reference-graph.js.map

package/dist/src/planner/cache/reference-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-graph.js","sourceRoot":"","sources":["../../../../src/planner/cache/reference-graph.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/cost/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Cost model helpers for query optimization
+ * Provides consistent cost estimation formulas across the optimizer
+ */
+/**
+ * Basic cost constants (in arbitrary "virtual CPU units")
+ */
+export declare const COST_CONSTANTS: {
+    /** Cost per row for sequential scan */
+    readonly SEQ_SCAN_PER_ROW: 1;
+    /** Base cost for starting a sequential scan */
+    readonly SEQ_SCAN_BASE: 0.1;
+    /** Cost per row for index seek */
+    readonly INDEX_SEEK_PER_ROW: 0.3;
+    /** Base cost for index seek operation */
+    readonly INDEX_SEEK_BASE: 0.5;
+    /** Cost per row for index scan */
+    readonly INDEX_SCAN_PER_ROW: 0.5;
+    /** Base cost for index scan operation */
+    readonly INDEX_SCAN_BASE: 0.3;
+    /** Cost per row for sorting */
+    readonly SORT_PER_ROW: 2;
+    /** Log base for sort cost calculations */
+    readonly SORT_LOG_BASE: 2;
+    /** Cost per row for filtering */
+    readonly FILTER_PER_ROW: 0.2;
+    /** Cost per row for projection */
+    readonly PROJECT_PER_ROW: 0.1;
+    /** Cost per output row for aggregation */
+    readonly AGGREGATE_PER_GROUP: 1.5;
+    /** Cost per input row for aggregation */
+    readonly AGGREGATE_PER_INPUT_ROW: 0.3;
+    /** Cost per row for nested loop join (inner side) */
+    readonly NL_JOIN_PER_INNER_ROW: 0.1;
+    /** Cost per row for nested loop join (outer side) */
+    readonly NL_JOIN_PER_OUTER_ROW: 1;
+    /** Cost per row for hash join build phase */
+    readonly HASH_JOIN_BUILD_PER_ROW: 0.8;
+    /** Cost per row for hash join probe phase */
+    readonly HASH_JOIN_PROBE_PER_ROW: 0.4;
+    /** Cost per row for distinct operation */
+    readonly DISTINCT_PER_ROW: 1.2;
+    /** Cost per row for limit operation */
+    readonly LIMIT_PER_ROW: 0.05;
+    /** Cost per row for cache access */
+    readonly CACHE_ACCESS_PER_ROW: 0.1;
+    /** Cost per row for cache population */
+    readonly CACHE_POPULATE_PER_ROW: 0.2;
+};
+/**
+ * Calculate cost for sequential scan
+ */
+export declare function seqScanCost(rows: number): number;
+/**
+ * Calculate cost for index seek (point lookup or tight range)
+ */
+export declare function indexSeekCost(rows: number): number;
+/**
+ * Calculate cost for index scan (range scan with ordering)
+ */
+export declare function indexScanCost(rows: number): number;
+/**
+ * Calculate cost for sorting operation
+ * Uses O(n log n) complexity
+ */
+export declare function sortCost(rows: number): number;
+/**
+ * Calculate cost for filter operation
+ */
+export declare function filterCost(inputRows: number): number;
+/**
+ * Calculate cost for projection operation
+ */
+export declare function projectCost(rows: number, projectionCount?: number): number;
+/**
+ * Calculate cost for aggregation operation
+ */
+export declare function aggregateCost(inputRows: number, outputRows: number): number;
+/**
+ * Calculate cost for nested loop join
+ */
+export declare function nestedLoopJoinCost(outerRows: number, innerRows: number): number;
+/**
+ * Calculate cost for hash join
+ */
+export declare function hashJoinCost(buildRows: number, probeRows: number): number;
+/**
+ * Calculate cost for distinct operation
+ */
+export declare function distinctCost(rows: number): number;
+/**
+ * Calculate cost for limit operation
+ */
+export declare function limitCost(inputRows: number, limitValue: number): number;
+/**
+ * Calculate cost for cache operations
+ */
+export declare function cacheCost(rows: number, accessCount?: number): number;
+/**
+ * Helper to choose the minimum cost option
+ */
+export declare function chooseCheapest<T>(options: Array<{
+    cost: number;
+    option: T;
+}>): T;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/planner/cost/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/planner/cost/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;GAEG;AACH,eAAO,MAAM,cAAc;IAC1B,uCAAuC;;IAEvC,+CAA+C;;IAG/C,kCAAkC;;IAElC,yCAAyC;;IAGzC,kCAAkC;;IAElC,yCAAyC;;IAGzC,+BAA+B;;IAE/B,0CAA0C;;IAG1C,iCAAiC;;IAGjC,kCAAkC;;IAGlC,0CAA0C;;IAE1C,yCAAyC;;IAGzC,qDAAqD;;IAErD,qDAAqD;;IAGrD,6CAA6C;;IAE7C,6CAA6C;;IAG7C,0CAA0C;;IAG1C,uCAAuC;;IAGvC,oCAAoC;;IAEpC,wCAAwC;;CAE/B,CAAC;AAEX;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,GAAE,MAAU,GAAG,MAAM,CAE7E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAG3E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG/E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAGvE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,GAAE,MAAU,GAAG,MAAM,CAIvE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,GAAG,CAAC,CAOhF"}

package/dist/src/planner/cost/index.js

@@ -0,0 +1,143 @@
+/**
+ * Cost model helpers for query optimization
+ * Provides consistent cost estimation formulas across the optimizer
+ */
+import { quereusError } from "../../common/errors.js";
+import { StatusCode } from "../../common/types.js";
+/**
+ * Basic cost constants (in arbitrary "virtual CPU units")
+ */
+export const COST_CONSTANTS = {
+    /** Cost per row for sequential scan */
+    SEQ_SCAN_PER_ROW: 1.0,
+    /** Base cost for starting a sequential scan */
+    SEQ_SCAN_BASE: 0.1,
+    /** Cost per row for index seek */
+    INDEX_SEEK_PER_ROW: 0.3,
+    /** Base cost for index seek operation */
+    INDEX_SEEK_BASE: 0.5,
+    /** Cost per row for index scan */
+    INDEX_SCAN_PER_ROW: 0.5,
+    /** Base cost for index scan operation */
+    INDEX_SCAN_BASE: 0.3,
+    /** Cost per row for sorting */
+    SORT_PER_ROW: 2.0,
+    /** Log base for sort cost calculations */
+    SORT_LOG_BASE: 2,
+    /** Cost per row for filtering */
+    FILTER_PER_ROW: 0.2,
+    /** Cost per row for projection */
+    PROJECT_PER_ROW: 0.1,
+    /** Cost per output row for aggregation */
+    AGGREGATE_PER_GROUP: 1.5,
+    /** Cost per input row for aggregation */
+    AGGREGATE_PER_INPUT_ROW: 0.3,
+    /** Cost per row for nested loop join (inner side) */
+    NL_JOIN_PER_INNER_ROW: 0.1,
+    /** Cost per row for nested loop join (outer side) */
+    NL_JOIN_PER_OUTER_ROW: 1.0,
+    /** Cost per row for hash join build phase */
+    HASH_JOIN_BUILD_PER_ROW: 0.8,
+    /** Cost per row for hash join probe phase */
+    HASH_JOIN_PROBE_PER_ROW: 0.4,
+    /** Cost per row for distinct operation */
+    DISTINCT_PER_ROW: 1.2,
+    /** Cost per row for limit operation */
+    LIMIT_PER_ROW: 0.05,
+    /** Cost per row for cache access */
+    CACHE_ACCESS_PER_ROW: 0.1,
+    /** Cost per row for cache population */
+    CACHE_POPULATE_PER_ROW: 0.2,
+};
+/**
+ * Calculate cost for sequential scan
+ */
+export function seqScanCost(rows) {
+    return COST_CONSTANTS.SEQ_SCAN_BASE + (rows * COST_CONSTANTS.SEQ_SCAN_PER_ROW);
+}
+/**
+ * Calculate cost for index seek (point lookup or tight range)
+ */
+export function indexSeekCost(rows) {
+    return COST_CONSTANTS.INDEX_SEEK_BASE + (rows * COST_CONSTANTS.INDEX_SEEK_PER_ROW);
+}
+/**
+ * Calculate cost for index scan (range scan with ordering)
+ */
+export function indexScanCost(rows) {
+    return COST_CONSTANTS.INDEX_SCAN_BASE + (rows * COST_CONSTANTS.INDEX_SCAN_PER_ROW);
+}
+/**
+ * Calculate cost for sorting operation
+ * Uses O(n log n) complexity
+ */
+export function sortCost(rows) {
+    if (rows <= 1)
+        return COST_CONSTANTS.SORT_PER_ROW;
+    return rows * Math.log2(rows) * COST_CONSTANTS.SORT_PER_ROW;
+}
+/**
+ * Calculate cost for filter operation
+ */
+export function filterCost(inputRows) {
+    return inputRows * COST_CONSTANTS.FILTER_PER_ROW;
+}
+/**
+ * Calculate cost for projection operation
+ */
+export function projectCost(rows, projectionCount = 1) {
+    return rows * projectionCount * COST_CONSTANTS.PROJECT_PER_ROW;
+}
+/**
+ * Calculate cost for aggregation operation
+ */
+export function aggregateCost(inputRows, outputRows) {
+    return (inputRows * COST_CONSTANTS.AGGREGATE_PER_INPUT_ROW) +
+        (outputRows * COST_CONSTANTS.AGGREGATE_PER_GROUP);
+}
+/**
+ * Calculate cost for nested loop join
+ */
+export function nestedLoopJoinCost(outerRows, innerRows) {
+    return (outerRows * COST_CONSTANTS.NL_JOIN_PER_OUTER_ROW) +
+        (outerRows * innerRows * COST_CONSTANTS.NL_JOIN_PER_INNER_ROW);
+}
+/**
+ * Calculate cost for hash join
+ */
+export function hashJoinCost(buildRows, probeRows) {
+    return (buildRows * COST_CONSTANTS.HASH_JOIN_BUILD_PER_ROW) +
+        (probeRows * COST_CONSTANTS.HASH_JOIN_PROBE_PER_ROW);
+}
+/**
+ * Calculate cost for distinct operation
+ */
+export function distinctCost(rows) {
+    // Distinct typically involves sorting or hashing
+    return rows * COST_CONSTANTS.DISTINCT_PER_ROW;
+}
+/**
+ * Calculate cost for limit operation
+ */
+export function limitCost(inputRows, limitValue) {
+    const processedRows = Math.min(inputRows, limitValue);
+    return processedRows * COST_CONSTANTS.LIMIT_PER_ROW;
+}
+/**
+ * Calculate cost for cache operations
+ */
+export function cacheCost(rows, accessCount = 1) {
+    const populateCost = rows * COST_CONSTANTS.CACHE_POPULATE_PER_ROW;
+    const accessCost = rows * accessCount * COST_CONSTANTS.CACHE_ACCESS_PER_ROW;
+    return populateCost + accessCost;
+}
+/**
+ * Helper to choose the minimum cost option
+ */
+export function chooseCheapest(options) {
+    if (options.length === 0) {
+        quereusError('No options provided to chooseCheapest', StatusCode.INTERNAL);
+    }
+    return options.reduce((min, current) => current.cost < min.cost ? current : min).option;
+}
+//# sourceMappingURL=index.js.map

package/dist/src/planner/cost/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/planner/cost/index.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/debug/logger-utils.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Debug namespace utilities for the Titan optimizer
+ * Provides standardized logger creation and debug conventions
+ */
+/**
+ * Create a logger for optimizer rules
+ * @param ruleName The name of the optimization rule
+ * @returns A debug logger with the standard optimizer:rule namespace
+ */
+export declare function ruleLog(ruleName: string): import("debug").Debugger;
+/**
+ * Create a logger for optimizer validation
+ * @param component The validation component (e.g., 'plan', 'attributes', 'ordering')
+ * @returns A debug logger with the standard optimizer:validate namespace
+ */
+export declare function validateLog(component?: string): import("debug").Debugger;
+/**
+ * Create a logger for runtime statistics
+ * @param component The stats component (e.g., 'metrics', 'summary', 'cache')
+ * @returns A debug logger with the standard runtime:stats namespace
+ */
+export declare function statsLog(component?: string): import("debug").Debugger;
+/**
+ * Create a logger for constant folding operations
+ * @param component The folding component (e.g., 'evaluation', 'binary-ops', 'functions')
+ * @returns A debug logger with the standard optimizer:folding namespace
+ */
+export declare function foldingLog(component?: string): import("debug").Debugger;
+/**
+ * Create a logger for plan emission
+ * @param emitterName The name of the emitter
+ * @returns A debug logger with the standard runtime:emit namespace
+ */
+export declare function emitLog(emitterName: string): import("debug").Debugger;
+/**
+ * Examples of debug namespace usage
+ *
+ * Enable all optimizer rules: DEBUG=optimizer:rule:* yarn test
+ * Enable plan validation: DEBUG=optimizer:validate yarn test
+ * Enable runtime stats: DEBUG=runtime:stats yarn test
+ * Enable specific rule: DEBUG=optimizer:rule:aggregate-streaming yarn test
+ * Enable everything: DEBUG=* yarn test
+ */
+//# sourceMappingURL=logger-utils.d.ts.map

package/dist/src/planner/debug/logger-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-utils.d.ts","sourceRoot":"","sources":["../../../../src/planner/debug/logger-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,4BAEvC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,SAAS,GAAE,MAAW,4BAGjD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,SAAS,GAAE,MAAW,4BAG9C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,GAAE,MAAW,4BAGhD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,WAAW,EAAE,MAAM,4BAE1C;AAMD;;;;;;;;GAQG"}

package/dist/src/planner/debug/logger-utils.js

@@ -0,0 +1,58 @@
+/**
+ * Debug namespace utilities for the Titan optimizer
+ * Provides standardized logger creation and debug conventions
+ */
+import { createLogger } from '../../common/logger.js';
+/**
+ * Create a logger for optimizer rules
+ * @param ruleName The name of the optimization rule
+ * @returns A debug logger with the standard optimizer:rule namespace
+ */
+export function ruleLog(ruleName) {
+    return createLogger(`optimizer:rule:${ruleName}`);
+}
+/**
+ * Create a logger for optimizer validation
+ * @param component The validation component (e.g., 'plan', 'attributes', 'ordering')
+ * @returns A debug logger with the standard optimizer:validate namespace
+ */
+export function validateLog(component = '') {
+    const namespace = component ? `optimizer:validate:${component}` : 'optimizer:validate';
+    return createLogger(namespace);
+}
+/**
+ * Create a logger for runtime statistics
+ * @param component The stats component (e.g., 'metrics', 'summary', 'cache')
+ * @returns A debug logger with the standard runtime:stats namespace
+ */
+export function statsLog(component = '') {
+    const namespace = component ? `runtime:stats:${component}` : 'runtime:stats';
+    return createLogger(namespace);
+}
+/**
+ * Create a logger for constant folding operations
+ * @param component The folding component (e.g., 'evaluation', 'binary-ops', 'functions')
+ * @returns A debug logger with the standard optimizer:folding namespace
+ */
+export function foldingLog(component = '') {
+    const namespace = component ? `optimizer:folding:${component}` : 'optimizer:folding';
+    return createLogger(namespace);
+}
+/**
+ * Create a logger for plan emission
+ * @param emitterName The name of the emitter
+ * @returns A debug logger with the standard runtime:emit namespace
+ */
+export function emitLog(emitterName) {
+    return createLogger(`runtime:emit:${emitterName}`);
+}
+/**
+ * Examples of debug namespace usage
+ *
+ * Enable all optimizer rules: DEBUG=optimizer:rule:* yarn test
+ * Enable plan validation: DEBUG=optimizer:validate yarn test
+ * Enable runtime stats: DEBUG=runtime:stats yarn test
+ * Enable specific rule: DEBUG=optimizer:rule:aggregate-streaming yarn test
+ * Enable everything: DEBUG=* yarn test
+ */
+//# sourceMappingURL=logger-utils.js.map

package/dist/src/planner/debug/logger-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-utils.js","sourceRoot":"","sources":["../../../../src/planner/debug/logger-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,QAAgB;IACvC,OAAO,YAAY,CAAC,kBAAkB,QAAQ,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,YAAoB,EAAE;IACjD,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,sBAAsB,SAAS,EAAE,CAAC,CAAC,CAAC,oBAAoB,CAAC;IACvF,OAAO,YAAY,CAAC,SAAS,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,YAAoB,EAAE;IAC9C,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,iBAAiB,SAAS,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC;IAC7E,OAAO,YAAY,CAAC,SAAS,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,YAAoB,EAAE;IAChD,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,qBAAqB,SAAS,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC;IACrF,OAAO,YAAY,CAAC,SAAS,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,WAAmB;IAC1C,OAAO,YAAY,CAAC,gBAAgB,WAAW,EAAE,CAAC,CAAC;AACpD,CAAC;AAMD;;;;;;;;GAQG"}

package/dist/src/planner/debug.d.ts

@@ -0,0 +1,53 @@
+import type { PlanNode } from './nodes/plan-node.js';
+import type { Instruction, InstructionTracer } from '../runtime/types.js';
+/**
+ * Detailed information about a PlanNode for debugging purposes.
+ */
+export interface PlanNodeDebugInfo {
+    id: string;
+    nodeType: string;
+    type: any;
+    estimatedCost: number;
+    estimatedRows?: number;
+    totalCost: number;
+    children: PlanNodeDebugInfo[];
+    relations: PlanNodeDebugInfo[];
+    properties: Record<string, any>;
+}
+/**
+ * Information about an instruction in the execution program.
+ */
+export interface InstructionDebugInfo {
+    index: number;
+    note?: string;
+    paramCount: number;
+    paramIndices: number[];
+    destination: number | null;
+    subPrograms?: SubProgramDebugInfo[];
+}
+/**
+ * Information about a sub-program for debugging purposes.
+ */
+export interface SubProgramDebugInfo {
+    programIndex: number;
+    instructionCount: number;
+    rootNote?: string;
+    instructions: InstructionDebugInfo[];
+}
+/**
+ * Serializes a PlanNode tree to a detailed JSON representation using the existing visit pattern.
+ */
+export declare function serializePlanTree(rootNode: PlanNode): string;
+/**
+ * Generates a human-readable program listing of instructions.
+ */
+export declare function generateInstructionProgram(instructions: readonly Instruction[], destinations: readonly (number | null)[]): string;
+/**
+ * Extracts detailed information about the instruction program structure.
+ */
+export declare function getInstructionDebugInfo(instructions: readonly Instruction[], destinations: readonly (number | null)[]): InstructionDebugInfo[];
+/**
+ * Generates a comprehensive trace report that includes sub-program execution details.
+ */
+export declare function generateTraceReport(tracer: InstructionTracer): string;
+//# sourceMappingURL=debug.d.ts.map

package/dist/src/planner/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../../src/planner/debug.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGrD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAK1E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,GAAG,CAAC;IACV,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAqDD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA+D5D;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,SAAS,WAAW,EAAE,EACpC,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GACvC,MAAM,CAoDR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,SAAS,WAAW,EAAE,EACpC,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GACvC,oBAAoB,EAAE,CA+BxB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iBAAiB,GACxB,MAAM,CA+CR"}