@rocicorp/zero 0.24.2025102200 → 0.25.0-canary.1

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

@@ -0,0 +1,411 @@
+import { assert } from "../../../shared/src/asserts.js";
+import { PlannerSource } from "./planner-source.js";
+import { must } from "../../../shared/src/must.js";
+/**
+ * Maximum number of flippable joins to attempt exhaustive enumeration.
+ * With n flippable joins, we explore 2^n plans.
+ * 10 joins = 1024 plans (~100-200ms), 12 joins = 4096 plans (~400ms - 1 second)
+ */
+const MAX_FLIPPABLE_JOINS = 13;
+export class PlannerGraph {
+    // Sources indexed by table name
+    #sources = new Map();
+    // The final output node where constraint propagation starts
+    #terminus = undefined;
+    // Collections of nodes with mutable planning state
+    joins = [];
+    fanOuts = [];
+    fanIns = [];
+    connections = [];
+    /**
+     * 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() {
+        for (const j of this.joins)
+            j.reset();
+        for (const fo of this.fanOuts)
+            fo.reset();
+        for (const fi of this.fanIns)
+            fi.reset();
+        for (const c of this.connections)
+            c.reset();
+    }
+    /**
+     * Create and register a source (table) in the graph.
+     */
+    addSource(name, model) {
+        assert(!this.#sources.has(name), `Source ${name} already exists in the graph`);
+        const source = new PlannerSource(name, model);
+        this.#sources.set(name, source);
+        return source;
+    }
+    /**
+     * Get a source by table name.
+     */
+    getSource(name) {
+        const source = this.#sources.get(name);
+        assert(source !== undefined, `Source ${name} not found in the graph`);
+        return source;
+    }
+    /**
+     * Check if a source exists by table name.
+     */
+    hasSource(name) {
+        return this.#sources.has(name);
+    }
+    /**
+     * Set the terminus (final output) node of the graph.
+     * Constraint propagation starts from this node.
+     */
+    setTerminus(terminus) {
+        this.#terminus = terminus;
+    }
+    /**
+     * Initiate constraint propagation from the terminus node.
+     * This sends constraints up through the graph to update
+     * connection cost estimates.
+     */
+    propagateConstraints() {
+        assert(this.#terminus !== undefined, 'Cannot propagate constraints without a terminus node');
+        this.#terminus.propagateConstraints();
+    }
+    /**
+     * Calculate total cost of the current plan.
+     * Total cost includes both startup cost (one-time, e.g., sorting) and running cost.
+     */
+    getTotalCost() {
+        const estimate = must(this.#terminus).estimateCost();
+        return estimate.startupCost + estimate.runningCost;
+    }
+    /**
+     * 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() {
+        return {
+            connections: this.connections.map(c => ({
+                limit: c.limit,
+            })),
+            joins: this.joins.map(j => ({ type: j.type })),
+            fanOuts: this.fanOuts.map(fo => ({ type: fo.type })),
+            fanIns: this.fanIns.map(fi => ({ type: fi.type })),
+            connectionConstraints: this.connections.map(c => c.captureConstraints()),
+        };
+    }
+    /**
+     * 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) {
+        this.#validateSnapshotShape(state);
+        this.#restoreConnections(state);
+        this.#restoreJoins(state);
+        this.#restoreFanNodes(state);
+    }
+    /**
+     * Collect cost estimates from all nodes in the graph for debugging.
+     */
+    #collectNodeCosts() {
+        const costs = [];
+        // Collect connection costs
+        for (const c of this.connections) {
+            costs.push({
+                node: c.name,
+                nodeType: 'connection',
+                costEstimate: c.estimateCost(undefined),
+            });
+        }
+        // Collect join costs
+        for (const j of this.joins) {
+            costs.push({
+                node: j.getName(),
+                nodeType: 'join',
+                costEstimate: j.estimateCost(undefined),
+            });
+        }
+        // Collect fan-out costs
+        for (const fo of this.fanOuts) {
+            costs.push({
+                node: 'FO',
+                nodeType: 'fan-out',
+                costEstimate: fo.estimateCost(undefined),
+            });
+        }
+        // Collect fan-in costs
+        for (const fi of this.fanIns) {
+            costs.push({
+                node: 'FI',
+                nodeType: 'fan-in',
+                costEstimate: fi.estimateCost(undefined),
+            });
+        }
+        return costs;
+    }
+    /**
+     * Validate that snapshot shape matches current graph structure.
+     */
+    #validateSnapshotShape(state) {
+        assert(this.connections.length === state.connections.length, 'Plan state mismatch: connections');
+        assert(this.joins.length === state.joins.length, 'Plan state mismatch: joins');
+        assert(this.fanOuts.length === state.fanOuts.length, 'Plan state mismatch: fanOuts');
+        assert(this.fanIns.length === state.fanIns.length, 'Plan state mismatch: fanIns');
+        assert(this.connections.length === state.connectionConstraints.length, 'Plan state mismatch: connectionConstraints');
+    }
+    /**
+     * Restore connection pinned flags, limits, and constraint maps.
+     */
+    #restoreConnections(state) {
+        for (let i = 0; i < this.connections.length; i++) {
+            this.connections[i].limit = state.connections[i].limit;
+            this.connections[i].restoreConstraints(state.connectionConstraints[i]);
+        }
+    }
+    /**
+     * Restore join types and pinned flags.
+     */
+    #restoreJoins(state) {
+        for (let i = 0; i < this.joins.length; i++) {
+            const join = this.joins[i];
+            const targetState = state.joins[i];
+            // Reset to initial state first
+            join.reset();
+            // Apply target state
+            if (targetState.type === 'flipped') {
+                join.flip();
+            }
+        }
+    }
+    /**
+     * Restore FanOut and FanIn types.
+     */
+    #restoreFanNodes(state) {
+        for (let i = 0; i < this.fanOuts.length; i++) {
+            const fo = this.fanOuts[i];
+            const targetType = state.fanOuts[i].type;
+            if (targetType === 'UFO' && fo.type === 'FO') {
+                fo.convertToUFO();
+            }
+        }
+        for (let i = 0; i < this.fanIns.length; i++) {
+            const fi = this.fanIns[i];
+            const targetType = state.fanIns[i].type;
+            if (targetType === 'UFI' && fi.type === 'FI') {
+                fi.convertToUFI();
+            }
+        }
+    }
+    /**
+     * 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) {
+        // Get all flippable joins
+        const flippableJoins = this.joins.filter(j => j.isFlippable());
+        // Safety check: throw if too many flippable joins
+        if (flippableJoins.length > MAX_FLIPPABLE_JOINS) {
+            throw new Error(`Query has ${flippableJoins.length} EXISTS checks in a single RELATED call (or in the top level query), which would require ` +
+                `${2 ** flippableJoins.length} plan evaluations. This may be very slow. ` +
+                `Consider simplifying the query or increasing MAX_FLIPPABLE_JOINS (currently set to ${MAX_FLIPPABLE_JOINS}).`);
+        }
+        // Build FO→FI cache once to avoid redundant BFS traversals in each iteration
+        const fofiCache = buildFOFICache(this);
+        const numPatterns = 2 ** flippableJoins.length;
+        let bestCost = Infinity;
+        let bestPlan = undefined;
+        let bestAttemptNumber = -1;
+        // Enumerate all flip patterns
+        for (let pattern = 0; pattern < numPatterns; pattern++) {
+            // Reset to initial state
+            this.resetPlanningState();
+            if (planDebugger) {
+                planDebugger.log({
+                    type: 'attempt-start',
+                    attemptNumber: pattern,
+                    totalAttempts: numPatterns,
+                });
+            }
+            try {
+                // Apply flip pattern (treat pattern as bitmask)
+                // Bit i set to 1 means flip join i
+                for (let i = 0; i < flippableJoins.length; i++) {
+                    if (pattern & (1 << i)) {
+                        flippableJoins[i].flip();
+                    }
+                }
+                // Derive FO/UFO and FI/UFI states from join flip states
+                checkAndConvertFOFI(fofiCache);
+                // Propagate unlimiting for flipped joins
+                propagateUnlimitForFlippedJoins(this);
+                // Propagate constraints through the graph
+                this.propagateConstraints();
+                if (planDebugger) {
+                    planDebugger.log({
+                        type: 'constraints-propagated',
+                        attemptNumber: pattern,
+                        connectionConstraints: this.connections.map(c => ({
+                            connection: c.name,
+                            constraints: c.getConstraintsForDebug(),
+                            constraintCosts: c.getConstraintCostsForDebug(),
+                        })),
+                    });
+                }
+                // Evaluate this plan
+                const totalCost = this.getTotalCost();
+                if (planDebugger) {
+                    planDebugger.log({
+                        type: 'plan-complete',
+                        attemptNumber: pattern,
+                        totalCost,
+                        nodeCosts: this.#collectNodeCosts(),
+                        joinStates: this.joins.map(j => {
+                            const info = j.getDebugInfo();
+                            return {
+                                join: info.name,
+                                type: info.type,
+                            };
+                        }),
+                    });
+                }
+                // Track best plan
+                if (totalCost < bestCost) {
+                    bestCost = totalCost;
+                    bestPlan = this.capturePlanningSnapshot();
+                    bestAttemptNumber = pattern;
+                }
+            }
+            catch (e) {
+                // This flip pattern is invalid (shouldn't happen with proper isFlippable() checks)
+                if (planDebugger) {
+                    planDebugger.log({
+                        type: 'plan-failed',
+                        attemptNumber: pattern,
+                        reason: `Flip pattern ${pattern.toString(2)} failed: ${e instanceof Error ? e.message : String(e)}`,
+                    });
+                }
+                continue;
+            }
+        }
+        // Restore best plan
+        if (bestPlan) {
+            this.restorePlanningSnapshot(bestPlan);
+            // Propagate constraints to ensure all derived state is consistent
+            this.propagateConstraints();
+            if (planDebugger) {
+                planDebugger.log({
+                    type: 'best-plan-selected',
+                    bestAttemptNumber,
+                    totalCost: bestCost,
+                    joinStates: this.joins.map(j => ({
+                        join: j.getName(),
+                        type: j.type,
+                    })),
+                });
+            }
+        }
+        else {
+            // No valid plan found (all patterns failed)
+            throw new Error('No valid query plan found. This should not happen - check query structure.');
+        }
+    }
+}
+/**
+ * Build cache of FO→FI relationships and joins between them.
+ * Called once at the start of planning to avoid redundant BFS traversals.
+ */
+function buildFOFICache(graph) {
+    const cache = new Map();
+    for (const fo of graph.fanOuts) {
+        const info = findFIAndJoins(fo);
+        cache.set(fo, info);
+    }
+    return cache;
+}
+/**
+ * Check if any joins downstream of a FanOut (before reaching FanIn) are flipped.
+ * If so, convert the FO to UFO and the FI to UFI.
+ *
+ * This must be called after join flipping and before propagateConstraints.
+ */
+function checkAndConvertFOFI(fofiCache) {
+    for (const [fo, info] of fofiCache) {
+        const hasFlippedJoin = info.joinsBetween.some(j => j.type === 'flipped');
+        if (info.fi && hasFlippedJoin) {
+            fo.convertToUFO();
+            info.fi.convertToUFI();
+        }
+    }
+}
+/**
+ * Traverse from a FanOut through its outputs to find the corresponding FanIn
+ * and collect all joins along the way.
+ */
+function findFIAndJoins(fo) {
+    const joinsBetween = [];
+    let fi = undefined;
+    // BFS through FO outputs to find FI and collect joins
+    const queue = [...fo.outputs];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const node = must(queue.shift());
+        if (visited.has(node))
+            continue;
+        visited.add(node);
+        switch (node.kind) {
+            case 'join':
+                joinsBetween.push(node);
+                queue.push(node.output);
+                break;
+            case 'fan-out':
+                // Nested FO - traverse its outputs
+                queue.push(...node.outputs);
+                break;
+            case 'fan-in':
+                // Found the FI - this is the boundary, don't traverse further
+                fi = node;
+                break;
+            case 'connection':
+                // Shouldn't happen in a well-formed graph
+                break;
+            case 'terminus':
+                // Reached the end without finding FI
+                break;
+        }
+    }
+    return { fi, joinsBetween };
+}
+/**
+ * Propagate unlimiting to all flipped joins in the graph.
+ * When a join is flipped, its child becomes the outer loop and should no longer
+ * be limited by EXISTS semantics.
+ *
+ * This must be called after join flipping and before propagateConstraints.
+ */
+function propagateUnlimitForFlippedJoins(graph) {
+    for (const join of graph.joins) {
+        if (join.type === 'flipped') {
+            join.propagateUnlimit();
+        }
+    }
+}
+//# sourceMappingURL=planner-graph.js.map

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

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

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

@@ -0,0 +1,81 @@
+import { type PlannerConstraint } from './planner-constraint.ts';
+import type { CostEstimate, JoinOrConnection, PlannerNode } from './planner-node.ts';
+/**
+ * Represents a join between two data streams (parent and child).
+ *
+ * # Dual-State Pattern
+ * Like all planner nodes, PlannerJoin separates:
+ * 1. IMMUTABLE STRUCTURE: Parent/child nodes, constraints, flippability
+ * 2. MUTABLE STATE: Join type (semi/flipped), pinned status
+ *
+ * # Join Flipping
+ * A join can be in two states:
+ * - 'semi': Parent is outer loop, child is inner (semi-join for EXISTS)
+ * - 'flipped': Child is outer loop, parent is inner
+ *
+ * Flipping is the key optimization: choosing which table scans first.
+ * NOT EXISTS joins cannot be flipped (#flippable = false).
+ *
+ * # Constraint Propagation
+ * - Semi-join: Sends childConstraint to child, forwards received constraints to parent
+ * - Flipped join: Sends undefined to child, merges parentConstraint with received to parent
+ * - Unpinned join: Only forwards constraints to parent (doesn't constrain child yet)
+ *
+ * # Lifecycle
+ * 1. Construct with immutable structure (parent, child, constraints, flippability)
+ * 2. Wire to output node during graph construction
+ * 3. Planning calls flipIfNeeded() based on connection selection order
+ * 4. pin() locks the join type once chosen
+ * 5. reset() clears mutable state (type → 'semi', pinned → false)
+ */
+export declare class PlannerJoin {
+    #private;
+    readonly kind: "join";
+    readonly planId: number;
+    constructor(parent: PlannerNode, child: PlannerNode, parentConstraint: PlannerConstraint, childConstraint: PlannerConstraint, flippable: boolean, planId: number);
+    setOutput(node: PlannerNode): void;
+    get output(): PlannerNode;
+    closestJoinOrSource(): JoinOrConnection;
+    flipIfNeeded(input: PlannerNode): void;
+    flip(): void;
+    get type(): 'semi' | 'flipped';
+    isFlippable(): boolean;
+    /**
+     * Propagate unlimiting through the child subgraph when this join is flipped.
+     * When a join is flipped, the child becomes the outer loop and should produce
+     * all rows rather than stopping at an EXISTS limit.
+     *
+     * Propagation rules:
+     * - Connection: call unlimit()
+     * - Semi-join: continue to parent (outer loop)
+     * - Flipped join: stop (already unlimited when it was flipped)
+     * - Fan-out/Fan-in: propagate to all inputs
+     */
+    propagateUnlimit(): void;
+    /**
+     * Called when a parent join is flipped and this join is part of its child subgraph.
+     * - Semi-join: continue propagation to parent (the outer loop)
+     * - Flipped join: stop propagation (already unlimited when it was flipped)
+     */
+    propagateUnlimitFromFlippedJoin(): void;
+    propagateConstraints(branchPattern: number[], constraint: PlannerConstraint | undefined): void;
+    reset(): void;
+    estimateCost(branchPattern?: number[]): CostEstimate;
+    /**
+     * Get a human-readable name for this join for debugging.
+     * Format: "parentName ⋈ childName"
+     */
+    getName(): string;
+    /**
+     * Get debug information about this join's state.
+     */
+    getDebugInfo(): {
+        name: string;
+        type: 'semi' | 'flipped';
+        planId: number;
+    };
+}
+export declare class UnflippableJoinError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=planner-join.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner-join.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-join.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAoB3B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,WAAW;;IACtB,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAOhC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAOtB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,WAAW,EAClB,gBAAgB,EAAE,iBAAiB,EACnC,eAAe,EAAE,iBAAiB,EAClC,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,MAAM;IAWhB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIlC,IAAI,MAAM,IAAI,WAAW,CAGxB;IAED,mBAAmB,IAAI,gBAAgB;IAIvC,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAWtC,IAAI,IAAI,IAAI;IAUZ,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IACD,WAAW,IAAI,OAAO;IAItB;;;;;;;;;;OAUG;IACH,gBAAgB,IAAI,IAAI;IAKxB;;;;OAIG;IACH,+BAA+B,IAAI,IAAI;IAOvC,oBAAoB,CAClB,aAAa,EAAE,MAAM,EAAE,EACvB,UAAU,EAAE,iBAAiB,GAAG,SAAS,GACxC,IAAI;IA2BP,KAAK,IAAI,IAAI;IAIb,YAAY,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY;IAkDpD;;;OAGG;IACH,OAAO,IAAI,MAAM;IAMjB;;OAEG;IACH,YAAY,IAAI;QACd,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;QACzB,MAAM,EAAE,MAAM,CAAC;KAChB;CAOF;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B"}