@rocicorp/zero 0.25.0-canary.0 → 0.25.0-canary.1

package/out/zql/src/planner/planner-debug.d.ts

@@ -0,0 +1,118 @@
+import type { PlannerConstraint } from './planner-constraint.ts';
+import type { CostEstimate, JoinType, NodeType } from './planner-node.ts';
+/**
+ * Structured debug events emitted during query planning.
+ * These events can be accumulated, printed, or analyzed to understand
+ * the planner's decision-making process.
+ */
+/**
+ * Starting a new planning attempt with a different root connection.
+ */
+export type AttemptStartEvent = {
+    type: 'attempt-start';
+    attemptNumber: number;
+    totalAttempts: number;
+};
+/**
+ * Snapshot of connection costs before selecting the next connection.
+ */
+export type ConnectionCostsEvent = {
+    type: 'connection-costs';
+    attemptNumber: number;
+    costs: Array<{
+        connection: string;
+        cost: number;
+        costEstimate: CostEstimate;
+        pinned: boolean;
+        constraints: Map<string, PlannerConstraint | undefined>;
+        constraintCosts: Map<string, CostEstimate>;
+    }>;
+};
+/**
+ * A connection was chosen and pinned.
+ */
+export type ConnectionSelectedEvent = {
+    type: 'connection-selected';
+    attemptNumber: number;
+    connection: string;
+    cost: number;
+    isRoot: boolean;
+};
+/**
+ * Constraints have been propagated through the graph.
+ */
+export type ConstraintsPropagatedEvent = {
+    type: 'constraints-propagated';
+    attemptNumber: number;
+    connectionConstraints: Array<{
+        connection: string;
+        constraints: Map<string, PlannerConstraint | undefined>;
+        constraintCosts: Map<string, CostEstimate>;
+    }>;
+};
+/**
+ * A complete plan was found for this attempt.
+ */
+export type PlanCompleteEvent = {
+    type: 'plan-complete';
+    attemptNumber: number;
+    totalCost: number;
+    nodeCosts: Array<{
+        node: string;
+        nodeType: NodeType;
+        costEstimate: CostEstimate;
+    }>;
+    joinStates: Array<{
+        join: string;
+        type: JoinType;
+    }>;
+};
+/**
+ * Planning attempt failed (e.g., unflippable join).
+ */
+export type PlanFailedEvent = {
+    type: 'plan-failed';
+    attemptNumber: number;
+    reason: string;
+};
+/**
+ * The best plan across all attempts was selected.
+ */
+export type BestPlanSelectedEvent = {
+    type: 'best-plan-selected';
+    bestAttemptNumber: number;
+    totalCost: number;
+    joinStates: Array<{
+        join: string;
+        type: JoinType;
+    }>;
+};
+/**
+ * Union of all debug event types.
+ */
+export type PlanDebugEvent = AttemptStartEvent | ConnectionCostsEvent | ConnectionSelectedEvent | ConstraintsPropagatedEvent | PlanCompleteEvent | PlanFailedEvent | BestPlanSelectedEvent;
+/**
+ * Interface for objects that receive debug events during planning.
+ */
+export interface PlanDebugger {
+    log(event: PlanDebugEvent): void;
+}
+/**
+ * Simple accumulator debugger that stores all events.
+ * Useful for tests and debugging.
+ */
+export declare class AccumulatorDebugger implements PlanDebugger {
+    readonly events: PlanDebugEvent[];
+    log(event: PlanDebugEvent): void;
+    /**
+     * Get all events of a specific type.
+     */
+    getEvents<T extends PlanDebugEvent['type']>(type: T): Extract<PlanDebugEvent, {
+        type: T;
+    }>[];
+    /**
+     * Format events as a human-readable string.
+     */
+    format(): string;
+}
+//# sourceMappingURL=planner-debug.d.ts.map

package/out/zql/src/planner/planner-debug.d.ts.map

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

package/out/zql/src/planner/planner-debug.js

@@ -0,0 +1,125 @@
+/**
+ * Simple accumulator debugger that stores all events.
+ * Useful for tests and debugging.
+ */
+export class AccumulatorDebugger {
+    events = [];
+    log(event) {
+        this.events.push(event);
+    }
+    /**
+     * Get all events of a specific type.
+     */
+    getEvents(type) {
+        return this.events.filter(e => e.type === type);
+    }
+    /**
+     * Format events as a human-readable string.
+     */
+    format() {
+        const lines = [];
+        for (const event of this.events) {
+            lines.push(formatEvent(event));
+        }
+        return lines.join('\n');
+    }
+}
+/**
+ * Format a constraint object as a human-readable string.
+ */
+function formatConstraint(constraint) {
+    if (!constraint)
+        return '{}';
+    const keys = Object.keys(constraint);
+    if (keys.length === 0)
+        return '{}';
+    return '{' + keys.join(', ') + '}';
+}
+/**
+ * Format a single debug event as a human-readable string.
+ */
+function formatEvent(event) {
+    switch (event.type) {
+        case 'attempt-start':
+            return `[Attempt ${event.attemptNumber + 1}/${event.totalAttempts}] Starting planning attempt`;
+        case 'connection-costs': {
+            const lines = [`[Attempt ${event.attemptNumber + 1}] Connection costs:`];
+            for (const c of event.costs) {
+                // Format the main connection info
+                // const limitStr = c.costEstimate.limit !== undefined
+                //   ? c.costEstimate.limit.toString()
+                //   : 'none';
+                lines.push(`  ${c.connection}: cost=${c.cost.toFixed(2)}, `);
+                // Format each branch's constraints with costs
+                if (c.constraints.size === 0) {
+                    const cost = c.constraintCosts.get('');
+                    const costStr = cost ? ` cost=${cost.rows.toFixed(2)}` : '';
+                    lines.push(`    Branch [none]: {}${costStr}`);
+                }
+                else {
+                    for (const [branchKey, constraint] of c.constraints) {
+                        const branchLabel = branchKey === '' ? 'none' : branchKey;
+                        const cost = c.constraintCosts.get(branchKey);
+                        const costStr = cost ? ` cost=${cost.rows.toFixed(2)}` : '';
+                        lines.push(`    Branch [${branchLabel}]: ${formatConstraint(constraint)}${costStr}`);
+                    }
+                }
+            }
+            return lines.join('\n');
+        }
+        case 'connection-selected':
+            return (`[Attempt ${event.attemptNumber + 1}] Selected ${event.isRoot ? 'ROOT' : ''} connection: ` +
+                `${event.connection} (cost=${event.cost.toFixed(2)})`);
+        case 'constraints-propagated': {
+            const lines = [
+                `[Attempt ${event.attemptNumber + 1}] Constraints propagated:`,
+            ];
+            for (const c of event.connectionConstraints) {
+                lines.push(`  ${c.connection}:`);
+                // Format each branch's constraints with costs
+                if (c.constraints.size === 0) {
+                    const cost = c.constraintCosts.get('');
+                    const costStr = cost ? ` cost=${cost.rows.toFixed(2)}` : '';
+                    lines.push(`    Branch [none]: {}${costStr}`);
+                }
+                else {
+                    for (const [branchKey, constraint] of c.constraints) {
+                        const branchLabel = branchKey === '' ? 'none' : branchKey;
+                        const cost = c.constraintCosts.get(branchKey);
+                        const costStr = cost ? ` cost=${cost.rows.toFixed(2)}` : '';
+                        lines.push(`    Branch [${branchLabel}]: ${formatConstraint(constraint)}${costStr}`);
+                    }
+                }
+            }
+            return lines.join('\n');
+        }
+        case 'plan-complete': {
+            const lines = [
+                `[Attempt ${event.attemptNumber + 1}] Plan complete! Total cost: ${event.totalCost.toFixed(2)}`,
+                `  Joins:`,
+            ];
+            for (const j of event.joinStates) {
+                lines.push(`    ${j.join}: ${j.type}`);
+            }
+            lines.push(`  Node costs:`);
+            for (const n of event.nodeCosts) {
+                lines.push(`    ${n.node} (${n.nodeType}): ${n.costEstimate.runningCost.toFixed(2)}`);
+            }
+            return lines.join('\n');
+        }
+        case 'plan-failed':
+            return `[Attempt ${event.attemptNumber + 1}] Plan FAILED: ${event.reason}`;
+        case 'best-plan-selected': {
+            const lines = [
+                `[FINAL] Best plan selected from attempt ${event.bestAttemptNumber + 1}`,
+                `  Total cost: ${event.totalCost.toFixed(2)}`,
+                `  Joins:`,
+            ];
+            for (const j of event.joinStates) {
+                lines.push(`    ${j.join}: ${j.type}`);
+            }
+            return lines.join('\n');
+        }
+    }
+}
+//# sourceMappingURL=planner-debug.js.map

package/out/zql/src/planner/planner-debug.js.map

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

package/out/zql/src/planner/planner-fan-in.d.ts

@@ -0,0 +1,37 @@
+import type { PlannerConstraint } from './planner-constraint.ts';
+import type { CostEstimate, JoinOrConnection, PlannerNode } from './planner-node.ts';
+/**
+ * A PlannerFanIn node can either be a normal FanIn or UnionFanIn.
+ *
+ * These have different performance characteristics so we need to distinguish them.
+ *
+ * A normal FanIn only does a single fetch to FanOut, regardless of how many internal
+ * branches / inputs it has.
+ *
+ * A UnionFanIn does a fetch per internal branch / input. This causes an exponential
+ * increase in cost if many UnionFanIns are chained after on another. E.g., `(A or B) AND (C or D)`.
+ *
+ * To capture this cost blow-up, union fan in assigns different branch patterns to their inputs.
+ *
+ * Since UFI will generate a unique branch pattern per input, planner-connection will yield a higher cost
+ * each time a UFI is present. planner-connection will return the sum of the costs of each unique branch pattern.
+ */
+export declare class PlannerFanIn {
+    #private;
+    readonly kind: "fan-in";
+    constructor(inputs: PlannerNode[]);
+    get type(): "FI" | "UFI";
+    closestJoinOrSource(): JoinOrConnection;
+    setOutput(node: PlannerNode): void;
+    get output(): PlannerNode;
+    reset(): void;
+    convertToUFI(): void;
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * Fan-in propagates to all of its inputs.
+     */
+    propagateUnlimitFromFlippedJoin(): void;
+    estimateCost(branchPattern?: number[]): CostEstimate;
+    propagateConstraints(branchPattern: number[], constraint: PlannerConstraint | undefined, from: PlannerNode): void;
+}
+//# sourceMappingURL=planner-fan-in.d.ts.map

package/out/zql/src/planner/planner-fan-in.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-fan-in.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-fan-in.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;;IACvB,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;gBAKtB,MAAM,EAAE,WAAW,EAAE;IAKjC,IAAI,IAAI,iBAEP;IAED,mBAAmB,IAAI,gBAAgB;IAIvC,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIlC,IAAI,MAAM,IAAI,WAAW,CAGxB;IAED,KAAK;IAIL,YAAY,IAAI,IAAI;IAIpB;;;OAGG;IACH,+BAA+B,IAAI,IAAI;IAavC,YAAY,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY;IAmFpD,oBAAoB,CAClB,aAAa,EAAE,MAAM,EAAE,EACvB,UAAU,EAAE,iBAAiB,GAAG,SAAS,EACzC,IAAI,EAAE,WAAW,GAChB,IAAI;CAsBR"}

package/out/zql/src/planner/planner-fan-in.js

@@ -0,0 +1,149 @@
+import { assert } from "../../../shared/src/asserts.js";
+/**
+ * A PlannerFanIn node can either be a normal FanIn or UnionFanIn.
+ *
+ * These have different performance characteristics so we need to distinguish them.
+ *
+ * A normal FanIn only does a single fetch to FanOut, regardless of how many internal
+ * branches / inputs it has.
+ *
+ * A UnionFanIn does a fetch per internal branch / input. This causes an exponential
+ * increase in cost if many UnionFanIns are chained after on another. E.g., `(A or B) AND (C or D)`.
+ *
+ * To capture this cost blow-up, union fan in assigns different branch patterns to their inputs.
+ *
+ * Since UFI will generate a unique branch pattern per input, planner-connection will yield a higher cost
+ * each time a UFI is present. planner-connection will return the sum of the costs of each unique branch pattern.
+ */
+export class PlannerFanIn {
+    kind = 'fan-in';
+    #type;
+    #output;
+    #inputs;
+    constructor(inputs) {
+        this.#type = 'FI';
+        this.#inputs = inputs;
+    }
+    get type() {
+        return this.#type;
+    }
+    closestJoinOrSource() {
+        return 'join';
+    }
+    setOutput(node) {
+        this.#output = node;
+    }
+    get output() {
+        assert(this.#output !== undefined, 'Output not set');
+        return this.#output;
+    }
+    reset() {
+        this.#type = 'FI';
+    }
+    convertToUFI() {
+        this.#type = 'UFI';
+    }
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * Fan-in propagates to all of its inputs.
+     */
+    propagateUnlimitFromFlippedJoin() {
+        for (const input of this.#inputs) {
+            if ('propagateUnlimitFromFlippedJoin' in input &&
+                typeof input.propagateUnlimitFromFlippedJoin === 'function') {
+                input.propagateUnlimitFromFlippedJoin();
+            }
+        }
+    }
+    estimateCost(branchPattern) {
+        // FanIn always sums costs of its inputs
+        // But it needs to pass the correct branch pattern to each input
+        let totalCost = {
+            rows: 0,
+            runningCost: 0,
+            startupCost: 0,
+            selectivity: 0,
+            limit: undefined,
+        };
+        branchPattern = branchPattern ?? [];
+        if (this.#type === 'FI') {
+            // Normal FanIn: all inputs get the same branch pattern with 0 prepended
+            const updatedPattern = [0, ...branchPattern];
+            let maxrows = 0;
+            let maxRunningCost = 0;
+            let maxStartupCost = 0;
+            // Track complement probability for OR selectivity: P(A OR B) = 1 - (1-A)(1-B)
+            let noMatchProb = 1.0;
+            for (const input of this.#inputs) {
+                const cost = input.estimateCost(updatedPattern);
+                if (cost.rows > maxrows) {
+                    maxrows = cost.rows;
+                }
+                if (cost.runningCost > maxRunningCost) {
+                    maxRunningCost = cost.runningCost;
+                }
+                // FI fetches from the root only once, so take the max startup cost
+                if (cost.startupCost > maxStartupCost) {
+                    maxStartupCost = cost.startupCost;
+                }
+                // OR branches: combine selectivities assuming independent events
+                // P(A OR B) = 1 - (1-A)(1-B)
+                // Track probability of NO match in any branch
+                noMatchProb *= 1 - cost.selectivity;
+                // all inputs should have the same limit.
+                assert(totalCost.limit === undefined || cost.limit === totalCost.limit, 'All FanIn inputs should have the same limit');
+                totalCost.limit = cost.limit;
+            }
+            totalCost.rows = maxrows;
+            totalCost.runningCost = maxRunningCost;
+            totalCost.startupCost = maxStartupCost;
+            totalCost.selectivity = 1 - noMatchProb;
+        }
+        else {
+            // Union FanIn (UFI): each input gets unique branch pattern
+            let i = 0;
+            // Track complement probability for OR selectivity: P(A OR B) = 1 - (1-A)(1-B)
+            let noMatchProb = 1.0;
+            for (const input of this.#inputs) {
+                const updatedPattern = [i, ...branchPattern];
+                const cost = input.estimateCost(updatedPattern);
+                totalCost.rows += cost.rows;
+                totalCost.runningCost += cost.runningCost;
+                // UFI runs all branches, so startup costs add up
+                totalCost.startupCost += cost.startupCost;
+                // OR branches: combine selectivities assuming independent events
+                // P(A OR B) = 1 - (1-A)(1-B)
+                // Track probability of NO match in any branch
+                noMatchProb *= 1 - cost.selectivity;
+                // all inputs should have the same limit.
+                assert(totalCost.limit === undefined || cost.limit === totalCost.limit, 'All FanIn inputs should have the same limit');
+                totalCost.limit = cost.limit;
+                i++;
+            }
+            totalCost.selectivity = 1 - noMatchProb;
+        }
+        return totalCost;
+    }
+    propagateConstraints(branchPattern, constraint, from) {
+        if (this.#type === 'FI') {
+            const updatedPattern = [0, ...branchPattern];
+            /**
+             * All inputs get the same branch pattern.
+             * 1. They cannot contribute differing constraints to their parent inputs because they are not flipped.
+             *    If they were flipped this would be of type UFI.
+             * 2. All inputs need to be called because they could be pinned. If they are pinned they could have constraints
+             *    to send to their children.
+             */
+            for (const input of this.#inputs) {
+                input.propagateConstraints(updatedPattern, constraint, from);
+            }
+            return;
+        }
+        let i = 0;
+        for (const input of this.#inputs) {
+            input.propagateConstraints([i, ...branchPattern], constraint, from);
+            i++;
+        }
+    }
+}
+//# sourceMappingURL=planner-fan-in.js.map

package/out/zql/src/planner/planner-fan-in.js.map

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

package/out/zql/src/planner/planner-fan-out.d.ts

@@ -0,0 +1,21 @@
+import type { PlannerConstraint } from './planner-constraint.ts';
+import type { CostEstimate, JoinOrConnection, PlannerNode } from './planner-node.ts';
+export declare class PlannerFanOut {
+    #private;
+    readonly kind: "fan-out";
+    constructor(input: PlannerNode);
+    get type(): "FO" | "UFO";
+    addOutput(node: PlannerNode): void;
+    get outputs(): PlannerNode[];
+    closestJoinOrSource(): JoinOrConnection;
+    propagateConstraints(branchPattern: number[], constraint: PlannerConstraint | undefined, _from: PlannerNode): void;
+    estimateCost(branchPattern?: number[]): CostEstimate;
+    convertToUFO(): void;
+    reset(): void;
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * Fan-out propagates to its input.
+     */
+    propagateUnlimitFromFlippedJoin(): void;
+}
+//# sourceMappingURL=planner-fan-out.d.ts.map

package/out/zql/src/planner/planner-fan-out.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-fan-out.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-fan-out.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,aAAa;;IACxB,QAAQ,CAAC,IAAI,EAAG,SAAS,CAAU;gBAKvB,KAAK,EAAE,WAAW;IAK9B,IAAI,IAAI,iBAEP;IAED,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIlC,IAAI,OAAO,IAAI,WAAW,EAAE,CAE3B;IAED,mBAAmB,IAAI,gBAAgB;IAIvC,oBAAoB,CAClB,aAAa,EAAE,MAAM,EAAE,EACvB,UAAU,EAAE,iBAAiB,GAAG,SAAS,EACzC,KAAK,EAAE,WAAW,GACjB,IAAI;IAIP,YAAY,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY;IAIpD,YAAY,IAAI,IAAI;IAIpB,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,+BAA+B,IAAI,IAAI;CAUxC"}

package/out/zql/src/planner/planner-fan-out.js

@@ -0,0 +1,45 @@
+export class PlannerFanOut {
+    kind = 'fan-out';
+    #type;
+    #outputs = [];
+    #input;
+    constructor(input) {
+        this.#type = 'FO';
+        this.#input = input;
+    }
+    get type() {
+        return this.#type;
+    }
+    addOutput(node) {
+        this.#outputs.push(node);
+    }
+    get outputs() {
+        return this.#outputs;
+    }
+    closestJoinOrSource() {
+        return this.#input.closestJoinOrSource();
+    }
+    propagateConstraints(branchPattern, constraint, _from) {
+        this.#input.propagateConstraints(branchPattern, constraint, this);
+    }
+    estimateCost(branchPattern) {
+        return this.#input.estimateCost(branchPattern);
+    }
+    convertToUFO() {
+        this.#type = 'UFO';
+    }
+    reset() {
+        this.#type = 'FO';
+    }
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * Fan-out propagates to its input.
+     */
+    propagateUnlimitFromFlippedJoin() {
+        if ('propagateUnlimitFromFlippedJoin' in this.#input &&
+            typeof this.#input.propagateUnlimitFromFlippedJoin === 'function') {
+            this.#input.propagateUnlimitFromFlippedJoin();
+        }
+    }
+}
+//# sourceMappingURL=planner-fan-out.js.map

package/out/zql/src/planner/planner-fan-out.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-fan-out.js","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-fan-out.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,aAAa;IACf,IAAI,GAAG,SAAkB,CAAC;IACnC,KAAK,CAAe;IACX,QAAQ,GAAkB,EAAE,CAAC;IAC7B,MAAM,CAAc;IAE7B,YAAY,KAAkB;QAC5B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,SAAS,CAAC,IAAiB;QACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,mBAAmB;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC3C,CAAC;IAED,oBAAoB,CAClB,aAAuB,EACvB,UAAyC,EACzC,KAAkB;QAElB,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,aAAa,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;IACpE,CAAC;IAED,YAAY,CAAC,aAAwB;QACnC,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;IACjD,CAAC;IAED,YAAY;QACV,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,+BAA+B;QAC7B,IACE,iCAAiC,IAAI,IAAI,CAAC,MAAM;YAChD,OAAO,IAAI,CAAC,MAAM,CAAC,+BAA+B,KAAK,UAAU,EACjE,CAAC;YAEC,IAAI,CAAC,MACN,CAAC,+BAA+B,EAAE,CAAC;QACtC,CAAC;IACH,CAAC;CACF"}

package/out/zql/src/planner/planner-graph.d.ts

@@ -0,0 +1,103 @@
+import type { PlannerJoin } from './planner-join.ts';
+import type { PlannerFanOut } from './planner-fan-out.ts';
+import type { PlannerFanIn } from './planner-fan-in.ts';
+import type { PlannerConnection } from './planner-connection.ts';
+import type { PlannerTerminus } from './planner-terminus.ts';
+import { PlannerSource, type ConnectionCostModel } from './planner-source.ts';
+import type { PlannerConstraint } from './planner-constraint.ts';
+import type { PlanDebugger } from './planner-debug.ts';
+/**
+ * Captured state of a plan for comparison and restoration.
+ */
+type PlanState = {
+    connections: Array<{
+        limit: number | undefined;
+    }>;
+    joins: Array<{
+        type: 'semi' | 'flipped';
+    }>;
+    fanOuts: Array<{
+        type: 'FO' | 'UFO';
+    }>;
+    fanIns: Array<{
+        type: 'FI' | 'UFI';
+    }>;
+    connectionConstraints: Array<Map<string, PlannerConstraint | undefined>>;
+};
+export declare class PlannerGraph {
+    #private;
+    joins: PlannerJoin[];
+    fanOuts: PlannerFanOut[];
+    fanIns: PlannerFanIn[];
+    connections: PlannerConnection[];
+    /**
+     * Reset all planning state back to initial values for another planning pass.
+     * Resets only mutable planning state - graph structure is unchanged.
+     *
+     * This allows replanning the same query graph with different strategies.
+     */
+    resetPlanningState(): void;
+    /**
+     * Create and register a source (table) in the graph.
+     */
+    addSource(name: string, model: ConnectionCostModel): PlannerSource;
+    /**
+     * Get a source by table name.
+     */
+    getSource(name: string): PlannerSource;
+    /**
+     * Check if a source exists by table name.
+     */
+    hasSource(name: string): boolean;
+    /**
+     * Set the terminus (final output) node of the graph.
+     * Constraint propagation starts from this node.
+     */
+    setTerminus(terminus: PlannerTerminus): void;
+    /**
+     * Initiate constraint propagation from the terminus node.
+     * This sends constraints up through the graph to update
+     * connection cost estimates.
+     */
+    propagateConstraints(): void;
+    /**
+     * Calculate total cost of the current plan.
+     * Total cost includes both startup cost (one-time, e.g., sorting) and running cost.
+     */
+    getTotalCost(): number;
+    /**
+     * Capture a lightweight snapshot of the current planning state.
+     * Used for backtracking during multi-start greedy search.
+     *
+     * Captures mutable state including pinned flags, join types, and
+     * constraint maps to avoid needing repropagation on restore.
+     *
+     * @returns A snapshot that can be restored via restorePlanningSnapshot()
+     */
+    capturePlanningSnapshot(): PlanState;
+    /**
+     * Restore planning state from a previously captured snapshot.
+     * Used for backtracking when a planning attempt fails.
+     *
+     * Restores pinned flags, join types, and constraint maps, eliminating
+     * the need for repropagation.
+     *
+     * @param state - Snapshot created by capturePlanningSnapshot()
+     */
+    restorePlanningSnapshot(state: PlanState): void;
+    /**
+     * Main planning algorithm using exhaustive join flip enumeration.
+     *
+     * Enumerates all possible flip patterns for flippable joins (2^n for n flippable joins).
+     * Each pattern represents a different query execution plan. We evaluate the cost of each
+     * plan and select the one with the lowest cost.
+     *
+     * Connections are used only for cost estimation - the flip patterns determine the plan.
+     * FanOut/FanIn states (FO/UFO and FI/UFI) are automatically derived from join flip states.
+     *
+     * @param planDebugger - Optional debugger to receive structured events during planning
+     */
+    plan(planDebugger?: PlanDebugger): void;
+}
+export {};
+//# sourceMappingURL=planner-graph.d.ts.map

package/out/zql/src/planner/planner-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-graph.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAC,aAAa,EAAE,KAAK,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAErD;;GAEG;AACH,KAAK,SAAS,GAAG;IACf,WAAW,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAAC,CAAC;IAChD,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAAC,CAAC;IACzC,OAAO,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAA;KAAC,CAAC,CAAC;IACrC,MAAM,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAA;KAAC,CAAC,CAAC;IACpC,qBAAqB,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC,CAAC,CAAC;CAC1E,CAAC;AAkBF,qBAAa,YAAY;;IAQvB,KAAK,EAAE,WAAW,EAAE,CAAM;IAC1B,OAAO,EAAE,aAAa,EAAE,CAAM;IAC9B,MAAM,EAAE,YAAY,EAAE,CAAM;IAC5B,WAAW,EAAE,iBAAiB,EAAE,CAAM;IAEtC;;;;;OAKG;IACH,kBAAkB;IAOlB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,aAAa;IAUlE;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAMtC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAI5C;;;;OAIG;IACH,oBAAoB,IAAI,IAAI;IAQ5B;;;OAGG;IACH,YAAY,IAAI,MAAM;IAKtB;;;;;;;;OAQG;IACH,uBAAuB,IAAI,SAAS;IAYpC;;;;;;;;OAQG;IACH,uBAAuB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAuI/C;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;CA8HxC"}