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

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

@@ -1,5 +1,32 @@
 import { assert } from "../../../shared/src/asserts.js";
 import { mergeConstraints, } from "./planner-constraint.js";
+/**
+ * Translate constraints for a flipped join from parent space to child space.
+ * Matches the runtime behavior of FlippedJoin.fetch() which translates
+ * parent constraints to child constraints using index-based key mapping.
+ *
+ * Example:
+ *   parentConstraint = {issueID: undefined, projectID: undefined}
+ *   childConstraint = {id: undefined, projectID: undefined}
+ *   incomingConstraint = {issueID: 5}
+ *   result = {id: 5}  // issueID at index 0 maps to id at index 0
+ */
+function translateConstraintsForFlippedJoin(incomingConstraint, parentConstraint, childConstraint) {
+    if (!incomingConstraint)
+        return undefined;
+    const parentKeys = Object.keys(parentConstraint);
+    const childKeys = Object.keys(childConstraint);
+    const translated = {};
+    for (const [key, value] of Object.entries(incomingConstraint)) {
+        const index = parentKeys.indexOf(key);
+        if (index !== -1) {
+            // Found this key in parent at position `index`
+            // Map to child key at same position
+            translated[childKeys[index]] = value;
+        }
+    }
+    return Object.keys(translated).length > 0 ? translated : undefined;
+}
 /**
  * Semi-join overhead multiplier.
  *
@@ -16,7 +43,7 @@ import { mergeConstraints, } from "./planner-constraint.js";
  * Flipped joins have a different overhead in that they become unlimited. This
  * is accounted for when propagating unlimits rather than here.
  */
-const SEMI_JOIN_OVERHEAD_MULTIPLIER = 1.5;
+// const SEMI_JOIN_OVERHEAD_MULTIPLIER = 1.5;
 /**
  * Represents a join between two data streams (parent and child).
  *
@@ -56,8 +83,10 @@ export class PlannerJoin {
     #output; // Set once during graph construction
     // Reset between planning attempts
     #type;
-    constructor(parent, child, parentConstraint, childConstraint, flippable, planId) {
-        this.#type = 'semi';
+    #initialType;
+    constructor(parent, child, parentConstraint, childConstraint, flippable, planId, initialType = 'semi') {
+        this.#type = initialType;
+        this.#initialType = initialType;
         this.#parent = parent;
         this.#child = child;
         this.#childConstraint = childConstraint;
@@ -97,9 +126,13 @@ export class PlannerJoin {
         return this.#flippable;
     }
     /**
-     * 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.
+     * Propagate unlimiting when this join is flipped.
+     * When a join is flipped:
+     * 1. Child becomes outer loop → produces all rows (unlimited)
+     * 2. Parent is fetched once per child row → effectively unlimited
+     *
+     * Example: If child produces 896 rows, parent is fetched 896 times.
+     * Even if each fetch returns 1 row, parent produces 896 total rows.
      *
      * Propagation rules:
      * - Connection: call unlimit()
@@ -109,7 +142,8 @@ export class PlannerJoin {
      */
     propagateUnlimit() {
         assert(this.#type === 'flipped', 'Can only unlimit a flipped join');
-        propagateUnlimitToNode(this.#child);
+        this.#parent.propagateUnlimitFromFlippedJoin();
+        this.#child.propagateUnlimitFromFlippedJoin(); // Up the child chain
     }
     /**
      * Called when a parent join is flipped and this join is part of its child subgraph.
@@ -118,73 +152,139 @@ export class PlannerJoin {
      */
     propagateUnlimitFromFlippedJoin() {
         if (this.#type === 'semi') {
-            propagateUnlimitToNode(this.#parent);
+            this.#parent.propagateUnlimitFromFlippedJoin();
         }
         // For flipped joins, stop propagation
     }
-    propagateConstraints(branchPattern, constraint) {
+    propagateConstraints(branchPattern, constraint, from, planDebugger) {
+        planDebugger?.log({
+            type: 'node-constraint',
+            nodeType: 'join',
+            node: this.getName(),
+            branchPattern,
+            constraint,
+            from: from ? getNodeName(from) : 'unknown',
+        });
         if (this.#type === 'semi') {
             // A semi-join always has constraints for its child.
             // They are defined by the correlation between parent and child.
-            this.#child.propagateConstraints(branchPattern, this.#childConstraint, this);
+            this.#child.propagateConstraints(branchPattern, this.#childConstraint, this, planDebugger);
             // A semi-join forwards constraints to its parent.
-            this.#parent.propagateConstraints(branchPattern, constraint, this);
+            this.#parent.propagateConstraints(branchPattern, constraint, this, planDebugger);
         }
         else if (this.#type === 'flipped') {
-            // A flipped join has no constraints to pass to its child.
-            // It is a standalone fetch that is relying on the filters of the child
-            // connection to do the heavy work.
-            this.#child.propagateConstraints(branchPattern, undefined, this);
+            // A flipped join translates constraints from parent space to child space.
+            // This matches FlippedJoin.fetch() runtime behavior where parent constraints
+            // on join keys are translated to child constraints.
+            // Example: If parent has {issueID: 5} and join maps issueID→id,
+            // child gets {id: 5} allowing index usage.
+            const translatedConstraint = translateConstraintsForFlippedJoin(constraint, this.#parentConstraint, this.#childConstraint);
+            this.#child.propagateConstraints(branchPattern, translatedConstraint, this, planDebugger);
             // A flipped join will have constraints to send to its parent.
             // - The constraints its output sent
             // - The constraints its child creates
-            this.#parent.propagateConstraints(branchPattern, mergeConstraints(constraint, this.#parentConstraint), this);
+            this.#parent.propagateConstraints(branchPattern, mergeConstraints(constraint, this.#parentConstraint), this, planDebugger);
         }
     }
     reset() {
-        this.#type = 'semi';
-    }
-    estimateCost(branchPattern) {
-        const parentCost = this.#parent.estimateCost(branchPattern);
-        const childCost = this.#child.estimateCost(branchPattern);
-        let scanEst = parentCost.rows;
-        if (this.#type === 'semi' && parentCost.limit !== undefined) {
-            if (childCost.selectivity !== 0) {
-                scanEst = Math.min(scanEst, parentCost.limit / childCost.selectivity);
-            }
+        this.#type = this.#initialType;
+    }
+    estimateCost(
+    /**
+     * This argument is to deal with consecutive `andExists` statements.
+     * Each one will constrain how often a parent row passes all constraints.
+     * This means that we have to scan more and more parent rows the more
+     * constraints we add.
+     */
+    downstreamChildSelectivity, 
+    /**
+     * branchPattern uniquely identifies OR branches in the graph.
+     * Each path through an OR will have unique constraints to apply to the source
+     * connection.
+     * branchPattern allows us to correlate a path through the graph
+     * to the constraints that should be applied for that path.
+     *
+     * Example graph:
+     *  UFO
+     * /  \
+     * J1   J2
+     * \  /
+     *  UFI
+     *
+     * J1 and J2 are joins inside an OR (FO).
+     * branchPattern [0] = path through J1
+     * branchPattern [1] = path through J2
+     *
+     * If many ORs are nested, branchPattern will have multiple elements
+     * representing each level of OR.
+     *
+     * If no joins are flipped within the `OR`, then only a single
+     * branchPattern element will be needed, as FO represents all sub-joins
+     * as a single path.
+     */
+    branchPattern, planDebugger) {
+        /**
+         * downstreamChildSelectivity accumulates up a parent chain, not
+         * up child chains. Child chains represent independent sub-graphs.
+         * So we pass 1 for `downstreamChildSelectivity` when estimating child cost.
+         * Put another way, downstreamChildSelectivity impacts how many parent
+         * rows are returned.
+         */
+        const child = this.#child.estimateCost(1, branchPattern, planDebugger);
+        /**
+         * How selective is the graph from this point forward?
+         * If we are _very_ selective then we must scan more parent rows
+         * before finding a match.
+         * E.g., if childSelectivity = 0.1 and downstreamChildSelectivity = 0.5
+         * then we only pass 5% of parent rows (0.1 * 0.5 = 0.05).
+         *
+         * This is used to estimate how many rows will be pulled from the parent
+         * when trying to satisfy downstream constraints and a limit.
+         *
+         * NOTE: We do not know if the probabilities are correlated so we assume independence.
+         * This is a fundamental limitation of the planner.
+         */
+        const parent = this.#parent.estimateCost(
+        // Selectivity flows up the graph from child to parent
+        // so we can determine the total selectivity of all ANDed exists checks.
+        child.selectivity * downstreamChildSelectivity, branchPattern, planDebugger);
+        let costEstimate;
+        if (this.type === 'semi') {
+            costEstimate = {
+                startupCost: parent.startupCost,
+                scanEst: parent.limit === undefined
+                    ? parent.returnedRows
+                    : Math.min(parent.returnedRows, parent.limit / downstreamChildSelectivity),
+                cost: parent.cost +
+                    parent.scanEst * (child.startupCost + child.cost + child.scanEst),
+                returnedRows: parent.returnedRows * child.selectivity,
+                selectivity: child.selectivity * parent.selectivity,
+                limit: parent.limit,
+            };
         }
-        if (this.#parent.closestJoinOrSource() === 'join') {
-            // if the parent is a join, we're in a pipeline rather than nesting of joins.
-            const pipelineCost = this.#type === 'flipped'
-                ? childCost.startupCost +
-                    childCost.runningCost *
-                        (parentCost.startupCost + parentCost.runningCost)
-                : parentCost.runningCost +
-                    SEMI_JOIN_OVERHEAD_MULTIPLIER *
-                        scanEst *
-                        (childCost.startupCost + childCost.runningCost);
-            return {
-                rows: parentCost.rows,
-                runningCost: pipelineCost,
-                startupCost: parentCost.startupCost,
-                selectivity: parentCost.selectivity,
-                limit: parentCost.limit,
+        else {
+            costEstimate = {
+                startupCost: child.startupCost,
+                scanEst: parent.limit === undefined
+                    ? parent.returnedRows
+                    : Math.min(parent.returnedRows * child.returnedRows, parent.limit / downstreamChildSelectivity),
+                cost: child.cost +
+                    child.scanEst * (parent.startupCost + parent.cost + parent.scanEst),
+                returnedRows: parent.returnedRows * child.returnedRows * child.selectivity,
+                selectivity: parent.selectivity * child.selectivity,
+                limit: parent.limit,
             };
         }
-        // if the parent is a source, we're in a nested loop join
-        const nestedLoopCost = this.#type === 'flipped'
-            ? childCost.runningCost *
-                (parentCost.startupCost + parentCost.runningCost)
-            : SEMI_JOIN_OVERHEAD_MULTIPLIER *
-                scanEst *
-                (childCost.startupCost + childCost.runningCost);
-        return {
-            rows: parentCost.rows,
-            runningCost: nestedLoopCost,
-            startupCost: parentCost.startupCost,
-            selectivity: parentCost.selectivity,
-            limit: parentCost.limit,
-        };
+        planDebugger?.log({
+            type: 'node-cost',
+            nodeType: 'join',
+            node: this.getName(),
+            branchPattern,
+            downstreamChildSelectivity,
+            costEstimate,
+            joinType: this.#type,
+        });
+        return costEstimate;
     }
     /**
      * Get a human-readable name for this join for debugging.
@@ -230,17 +330,4 @@ function getNodeName(node) {
             return 'terminus';
     }
 }
-/**
- * Propagate unlimiting through a node in the planner graph.
- * Called recursively to unlimit all nodes in a subgraph when a join is flipped.
- *
- * This calls the propagateUnlimitFromFlippedJoin() method on each node,
- * which implements the type-specific logic.
- */
-function propagateUnlimitToNode(node) {
-    if ('propagateUnlimitFromFlippedJoin' in node &&
-        typeof node.propagateUnlimitFromFlippedJoin === 'function') {
-        node.propagateUnlimitFromFlippedJoin();
-    }
-}
 //# sourceMappingURL=planner-join.js.map

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

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

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

@@ -9,9 +9,36 @@ import type { PlannerTerminus } from './planner-terminus.ts';
  */
 export type PlannerNode = PlannerJoin | PlannerConnection | PlannerFanOut | PlannerFanIn | PlannerTerminus;
 export type CostEstimate = {
-    rows: number;
-    runningCost: number;
     startupCost: number;
+    scanEst: number;
+    /**
+     * The cumulative cost to run the pipeline so far.
+     *
+     * In a semi-join, each row output by the parent is multiplied by the cost to evaluate the child.
+     * In a flipped join, each row output by the child is multiplied by the cost to evaluate the parent.
+     *
+     * "each row output by the parent" is determined by the downstreamChildSelectivity parameter in combination
+     * with the limit or the rows output by the parent node.
+     *
+     * We pull on the parent and stop when hitting a limit or exhausting rows.
+     */
+    cost: number;
+    /**
+     * The number of rows output from a node.
+     * - For a connection, this is the estimated number of rows returned by the source query.
+     * - For a semi-join, this is the estimated number of rows that pass the semi-join filter.
+     * - For a flipped join, this is the estimated number of rows that match all child rows.
+     * - For fan-in, this is the sum of the rows from each input.
+     * - For fan-out, this is the rows from its input.
+     */
+    returnedRows: number;
+    /**
+     * The selectivity of the node.
+     * For a connection, this is the fraction of rows passing filters (1.0 = no filtering).
+     * For joins, this is the fraction of parent rows that match child rows.
+     * For fan-in, this is the probability of a match in any branch, assuming independent events.
+     * For fan-out, this is the selectivity of its input.
+     */
     selectivity: number;
     limit: number | undefined;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"planner-node.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,iBAAiB,GACjB,aAAa,GACb,YAAY,GACZ,eAAe,CAAC;AAEpB,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAE3C,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,YAAY,CAAC;AAErD,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"planner-node.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,iBAAiB,GACjB,aAAa,GACb,YAAY,GACZ,eAAe,CAAC;AAEpB,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;;OAUG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAE3C,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,YAAY,CAAC;AAErD,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC"}

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

@@ -6,6 +6,6 @@ export declare class PlannerSource {
     #private;
     readonly name: string;
     constructor(name: string, model: ConnectionCostModel);
-    connect(sort: Ordering, filters: Condition | undefined, baseConstraints?: PlannerConstraint, limit?: number): PlannerConnection;
+    connect(sort: Ordering, filters: Condition | undefined, isRoot: boolean, baseConstraints?: PlannerConstraint, limit?: number): PlannerConnection;
 }
 //# sourceMappingURL=planner-source.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"planner-source.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAE,QAAQ,EAAC,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAE/D,YAAY,EAAC,mBAAmB,EAAC,CAAC;AAElC,qBAAa,aAAa;;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGV,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB;IAKpD,OAAO,CACL,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,eAAe,CAAC,EAAE,iBAAiB,EACnC,KAAK,CAAC,EAAE,MAAM,GACb,iBAAiB;CAUrB"}
+{"version":3,"file":"planner-source.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAE,QAAQ,EAAC,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAE/D,YAAY,EAAC,mBAAmB,EAAC,CAAC;AAElC,qBAAa,aAAa;;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGV,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB;IAKpD,OAAO,CACL,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,MAAM,EAAE,OAAO,EACf,eAAe,CAAC,EAAE,iBAAiB,EACnC,KAAK,CAAC,EAAE,MAAM,GACb,iBAAiB;CAWrB"}

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

@@ -6,8 +6,8 @@ export class PlannerSource {
         this.name = name;
         this.#model = model;
     }
-    connect(sort, filters, baseConstraints, limit) {
-        return new PlannerConnection(this.name, this.#model, sort, filters, baseConstraints, limit);
+    connect(sort, filters, isRoot, baseConstraints, limit) {
+        return new PlannerConnection(this.name, this.#model, sort, filters, isRoot, baseConstraints, limit);
     }
 }
 //# sourceMappingURL=planner-source.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"planner-source.js","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-source.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,GAElB,MAAM,yBAAyB,CAAC;AAKjC,MAAM,OAAO,aAAa;IACf,IAAI,CAAS;IACb,MAAM,CAAsB;IAErC,YAAY,IAAY,EAAE,KAA0B;QAClD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,OAAO,CACL,IAAc,EACd,OAA8B,EAC9B,eAAmC,EACnC,KAAc;QAEd,OAAO,IAAI,iBAAiB,CAC1B,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,MAAM,EACX,IAAI,EACJ,OAAO,EACP,eAAe,EACf,KAAK,CACN,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"planner-source.js","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-source.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,GAElB,MAAM,yBAAyB,CAAC;AAKjC,MAAM,OAAO,aAAa;IACf,IAAI,CAAS;IACb,MAAM,CAAsB;IAErC,YAAY,IAAY,EAAE,KAA0B;QAClD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,OAAO,CACL,IAAc,EACd,OAA8B,EAC9B,MAAe,EACf,eAAmC,EACnC,KAAc;QAEd,OAAO,IAAI,iBAAiB,CAC1B,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,MAAM,EACX,IAAI,EACJ,OAAO,EACP,MAAM,EACN,eAAe,EACf,KAAK,CACN,CAAC;IACJ,CAAC;CACF"}

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

@@ -1,12 +1,13 @@
+import type { PlanDebugger } from './planner-debug.ts';
 import type { CostEstimate, JoinOrConnection, PlannerNode } from './planner-node.ts';
 export declare class PlannerTerminus {
     #private;
     readonly kind: "terminus";
-    constructor(input: PlannerNode);
+    constructor(input: Exclude<PlannerNode, PlannerTerminus>);
     get pinned(): boolean;
     closestJoinOrSource(): JoinOrConnection;
-    propagateConstraints(): void;
-    estimateCost(): CostEstimate;
+    propagateConstraints(planDebugger?: PlanDebugger): void;
+    estimateCost(planDebugger?: PlanDebugger): CostEstimate;
     /**
      * Propagate unlimiting when a parent join is flipped.
      * Terminus doesn't participate in unlimiting.

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

@@ -1 +1 @@
-{"version":3,"file":"planner-terminus.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-terminus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,eAAe;;IAC1B,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;gBAGxB,KAAK,EAAE,WAAW;IAI9B,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,mBAAmB,IAAI,gBAAgB;IAIvC,oBAAoB,IAAI,IAAI;IAI5B,YAAY,IAAI,YAAY;IAK5B;;;OAGG;IACH,+BAA+B,IAAI,IAAI;CAGxC"}
+{"version":3,"file":"planner-terminus.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-terminus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,eAAe;;IAC1B,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;gBAGxB,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE,eAAe,CAAC;IAIxD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,mBAAmB,IAAI,gBAAgB;IAIvC,oBAAoB,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAIvD,YAAY,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,YAAY;IAKvD;;;OAGG;IACH,+BAA+B,IAAI,IAAI;CAGxC"}

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

@@ -10,12 +10,12 @@ export class PlannerTerminus {
     closestJoinOrSource() {
         return this.#input.closestJoinOrSource();
     }
-    propagateConstraints() {
-        this.#input.propagateConstraints([], undefined, this);
+    propagateConstraints(planDebugger) {
+        this.#input.propagateConstraints([], undefined, this, planDebugger);
     }
-    estimateCost() {
+    estimateCost(planDebugger) {
         // Terminus starts the cost estimation flow with empty branch pattern
-        return this.#input.estimateCost([]);
+        return this.#input.estimateCost(1, [], planDebugger);
     }
     /**
      * Propagate unlimiting when a parent join is flipped.

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

@@ -1 +1 @@
-{"version":3,"file":"planner-terminus.js","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-terminus.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,eAAe;IACjB,IAAI,GAAG,UAAmB,CAAC;IAC3B,MAAM,CAAc;IAE7B,YAAY,KAAkB;QAC5B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC;IACd,CAAC;IAED,mBAAmB;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC3C,CAAC;IAED,oBAAoB;QAClB,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IACxD,CAAC;IAED,YAAY;QACV,qEAAqE;QACrE,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,+BAA+B;QAC7B,mDAAmD;IACrD,CAAC;CACF"}
+{"version":3,"file":"planner-terminus.js","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-terminus.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,eAAe;IACjB,IAAI,GAAG,UAAmB,CAAC;IAC3B,MAAM,CAAwC;IAEvD,YAAY,KAA4C;QACtD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC;IACd,CAAC;IAED,mBAAmB;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC3C,CAAC;IAED,oBAAoB,CAAC,YAA2B;QAC9C,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;IACtE,CAAC;IAED,YAAY,CAAC,YAA2B;QACtC,qEAAqE;QACrE,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,YAAY,CAAC,CAAC;IACvD,CAAC;IAED;;;OAGG;IACH,+BAA+B;QAC7B,mDAAmD;IACrD,CAAC;CACF"}

package/out/zql/src/query/chained-query.d.ts

@@ -0,0 +1,35 @@
+import type { SimpleOperator } from '../../../zero-protocol/src/ast.ts';
+import type { Schema } from '../../../zero-types/src/schema.ts';
+import type { ExpressionFactory, ParameterReference } from './expression.ts';
+import type { AvailableRelationships, DestTableName, ExistsOptions, GetFilterType, NoCompoundTypeSelector, PullRow, PullTableSchema, Query } from './query.ts';
+/**
+ * Function type for chaining one query to another.
+ */
+type ChainQuery<TSchema extends Schema, TTable extends keyof TSchema['tables'] & string, TReturn1, TReturn2, TContext> = (q: Query<TSchema, TTable, TReturn1, TContext>) => Query<TSchema, TTable, TReturn2, TContext>;
+export type AnyChainQuery = ChainQuery<Schema, string, PullRow<string, Schema>, PullRow<string, Schema>, unknown>;
+/**
+ * Chained query that applies a transformation function to a parent query.
+ * This represents a query operation that builds on top of another query.
+ */
+export declare class ChainedQuery<TSchema extends Schema, TTable extends keyof TSchema['tables'] & string, TReturn, TContext> implements Query<TSchema, TTable, TReturn, TContext> {
+    #private;
+    constructor(parent: {
+        withContext(ctx: TContext): Query<TSchema, TTable, unknown>;
+    }, chainFn: AnyChainQuery);
+    withContext(ctx: TContext): Query<TSchema, TTable, TReturn>;
+    one(): ChainedQuery<TSchema, TTable, TReturn | undefined, TContext>;
+    whereExists<TRelationship extends AvailableRelationships<TTable, TSchema>>(relationship: TRelationship, options?: ExistsOptions): ChainedQuery<TSchema, TTable, TReturn, TContext>;
+    whereExists<TRelationship extends AvailableRelationships<TTable, TSchema>>(relationship: TRelationship, cb: (q: Query<TSchema, DestTableName<TTable, TSchema, TRelationship>, TContext>) => Query<TSchema, string, TContext>, options?: ExistsOptions): ChainedQuery<TSchema, TTable, TReturn, TContext>;
+    related<TRelationship extends AvailableRelationships<TTable, TSchema>>(relationship: TRelationship): ChainedQuery<TSchema, TTable, TReturn & Record<string, unknown>, TContext>;
+    related<TRelationship extends AvailableRelationships<TTable, TSchema>, TSub extends Query<TSchema, string, unknown>>(relationship: TRelationship, cb: (q: Query<TSchema, DestTableName<TTable, TSchema, TRelationship>, TContext>) => TSub): ChainedQuery<TSchema, TTable, TReturn & Record<string, unknown>, TContext>;
+    where<TSelector extends NoCompoundTypeSelector<PullTableSchema<TTable, TSchema>>, TOperator extends SimpleOperator>(field: TSelector, op: TOperator, value: GetFilterType<PullTableSchema<TTable, TSchema>, TSelector, TOperator> | ParameterReference): ChainedQuery<TSchema, TTable, TReturn, TContext>;
+    where<TSelector extends NoCompoundTypeSelector<PullTableSchema<TTable, TSchema>>>(field: TSelector, value: GetFilterType<PullTableSchema<TTable, TSchema>, TSelector, '='> | ParameterReference): ChainedQuery<TSchema, TTable, TReturn, TContext>;
+    where(expressionFactory: ExpressionFactory<TSchema, TTable>): ChainedQuery<TSchema, TTable, TReturn, TContext>;
+    start(row: Partial<PullRow<TTable, TSchema>>, opts?: {
+        inclusive: boolean;
+    }): ChainedQuery<TSchema, TTable, TReturn, TContext>;
+    limit(limit: number): ChainedQuery<TSchema, TTable, TReturn, TContext>;
+    orderBy<TSelector extends keyof PullTableSchema<TTable, TSchema>['columns']>(field: TSelector, direction: 'asc' | 'desc'): ChainedQuery<TSchema, TTable, TReturn, TContext>;
+}
+export {};
+//# sourceMappingURL=chained-query.d.ts.map

package/out/zql/src/query/chained-query.d.ts.map

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

package/out/zql/src/query/chained-query.js

@@ -0,0 +1,66 @@
+var _a;
+/**
+ * Chained query that applies a transformation function to a parent query.
+ * This represents a query operation that builds on top of another query.
+ */
+export class ChainedQuery {
+    #parent;
+    #chainFn;
+    #q;
+    constructor(parent, chainFn) {
+        this.#parent = parent;
+        this.#chainFn = chainFn;
+    }
+    withContext(ctx) {
+        if (this.#q) {
+            return this.#q;
+        }
+        // This is a chained query - get the parent query and apply the chain function
+        const parentQuery = this.#parent.withContext(ctx);
+        this.#q = this.#chainFn(parentQuery);
+        return this.#q;
+    }
+    #withChain(fn) {
+        return new _a(this, fn);
+    }
+    // Query interface methods
+    one() {
+        return this.#withChain(q => q.one());
+    }
+    whereExists(relationship, cbOrOptions, options) {
+        if (typeof cbOrOptions === 'function') {
+            return this.#withChain(q => q.whereExists(relationship, cbOrOptions, options));
+        }
+        return this.#withChain(q => q.whereExists(relationship, cbOrOptions));
+    }
+    related(relationship, cb) {
+        if (cb) {
+            return this.#withChain(q => q.related(relationship, cb));
+        }
+        return this.#withChain(q => q.related(relationship));
+    }
+    where(fieldOrExpressionFactory, opOrValue, value) {
+        if (typeof fieldOrExpressionFactory === 'function') {
+            return this.#withChain(q => q.where(fieldOrExpressionFactory));
+        }
+        if (value !== undefined) {
+            return this.#withChain(q => 
+            // Cast to bypass TypeScript's strict type checking - this proxy method needs runtime flexibility
+            q.where(fieldOrExpressionFactory, opOrValue, value));
+        }
+        return this.#withChain(q => 
+        // Cast to bypass TypeScript's strict type checking - this proxy method needs runtime flexibility
+        q.where(fieldOrExpressionFactory, opOrValue));
+    }
+    start(row, opts) {
+        return this.#withChain(q => q.start(row, opts));
+    }
+    limit(limit) {
+        return this.#withChain(q => q.limit(limit));
+    }
+    orderBy(field, direction) {
+        return this.#withChain(q => q.orderBy(field, direction));
+    }
+}
+_a = ChainedQuery;
+//# sourceMappingURL=chained-query.js.map

package/out/zql/src/query/chained-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chained-query.js","sourceRoot":"","sources":["../../../../../zql/src/query/chained-query.ts"],"names":[],"mappings":";AAoCA;;;GAGG;AACH,MAAM,OAAO,YAAY;IAOd,OAAO,CAEd;IACO,QAAQ,CAAgB;IACjC,EAAE,CAA8C;IAEhD,YACE,MAAqE,EACrE,OAAsB;QAEtB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,WAAW,CAAC,GAAa;QACvB,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC,EAAE,CAAC;QACjB,CAAC;QAED,8EAA8E;QAC9E,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAClD,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAuB,CAI9C,CAAC;QACF,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;IAED,UAAU,CACR,EAEuC;QAEvC,OAAO,IAAI,EAAY,CACrB,IAAqE,EACrE,EAAmB,CACpB,CAAC;IACJ,CAAC;IAED,0BAA0B;IAE1B,GAAG;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IACvC,CAAC;IAiBD,WAAW,CACT,YAAqD,EACrD,WAIiB,EACjB,OAAuB;QAEvB,IAAI,OAAO,WAAW,KAAK,UAAU,EAAE,CAAC;YACtC,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CACzB,CAAC,CAAC,WAAW,CACX,YAAsB,EACtB,WAAmD,EACnD,OAAO,CACR,CACF,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CACzB,CAAC,CAAC,WAAW,CAAC,YAAsB,EAAE,WAAW,CAAC,CACnD,CAAC;IACJ,CAAC;IAkBD,OAAO,CACL,YAAqD,EACrD,EAEqC;QAOrC,IAAI,EAAE,EAAE,CAAC;YACP,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CACzB,CAAC,CAAC,OAAO,CACP,YAAsB,EACtB,EAA0C,CAC3C,CAMF,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CACzB,CAAC,CAAC,OAAO,CAAC,YAAsB,CAAC,CAMlC,CAAC;IACJ,CAAC;IAuBD,KAAK,CACH,wBAEsC,EACtC,SAAmB,EACnB,KAAe;QAEf,IAAI,OAAO,wBAAwB,KAAK,UAAU,EAAE,CAAC;YACnD,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;YACzB,iGAAiG;YAE/F,CAOD,CAAC,KAAK,CAAC,wBAAwB,EAAE,SAAS,EAAE,KAAK,CAAC,CACpD,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;QACzB,iGAAiG;QAE/F,CAGD,CAAC,KAAK,CAAC,wBAAwB,EAAE,SAAS,CAAC,CAC7C,CAAC;IACJ,CAAC;IAED,KAAK,CACH,GAAsC,EACtC,IAA2B;QAE3B,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,KAAa;QACjB,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO,CACL,KAAgB,EAChB,SAAyB;QAEzB,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAe,EAAE,SAAS,CAAC,CAAC,CAAC;IACrE,CAAC;CACF"}

package/out/zql/src/query/define-query.d.ts

@@ -0,0 +1,51 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ReadonlyJSONValue } from '../../../shared/src/json.ts';
+import type { Schema } from '../../../zero-types/src/schema.ts';
+import type { Query } from './query.ts';
+export type DefineQueryOptions<Input, Output> = {
+    validator?: StandardSchemaV1<Input, Output> | undefined;
+};
+/**
+ * Function type for root query functions that take context and args.
+ */
+export type DefineQueryFunc<TSchema extends Schema, TTable extends keyof TSchema['tables'] & string, TReturn, TContext, TArgs> = (options: {
+    ctx: TContext;
+    args: TArgs;
+}) => Query<TSchema, TTable, TReturn, TContext>;
+export type NamedQueryFunction<TName extends string, TSchema extends Schema, TTable extends keyof TSchema['tables'] & string, TReturn, TContext, TOutput extends ReadonlyJSONValue | undefined, TInput extends ReadonlyJSONValue | undefined> = ([TOutput] extends [undefined] ? (() => Query<TSchema, TTable, TReturn, TContext>) & ((args: undefined) => Query<TSchema, TTable, TReturn, TContext>) : undefined extends TOutput ? (args?: TInput) => Query<TSchema, TTable, TReturn, TContext> : (args: TInput) => Query<TSchema, TTable, TReturn, TContext>) & {
+    queryName: TName;
+};
+export type AnyNamedQueryFunction = NamedQueryFunction<string, Schema, string, any, any, ReadonlyJSONValue | undefined, ReadonlyJSONValue | undefined>;
+export declare function defineQuery<TName extends string, TSchema extends Schema, TTable extends keyof TSchema['tables'] & string, TReturn, TContext, TArgs extends ReadonlyJSONValue | undefined>(name: TName, queryFn: DefineQueryFunc<TSchema, TTable, TReturn, TContext, TArgs>): NamedQueryFunction<TName, TSchema, TTable, TReturn, TContext, TArgs, TArgs>;
+export declare function defineQuery<TName extends string, TSchema extends Schema, TTable extends keyof TSchema['tables'] & string, TReturn, TContext, TOutput extends ReadonlyJSONValue | undefined, TInput extends ReadonlyJSONValue | undefined = TOutput>(name: TName, options: DefineQueryOptions<TInput, TOutput>, queryFn: DefineQueryFunc<TSchema, TTable, TReturn, TContext, TOutput>): NamedQueryFunction<TName, TSchema, TTable, TReturn, TContext, TOutput, TInput>;
+export declare function defineQuery<TName extends string, TSchema extends Schema, TTable extends keyof TSchema['tables'] & string, TReturn, TContext, TArgs extends ReadonlyJSONValue | undefined>(name: TName, options: {}, queryFn: DefineQueryFunc<TSchema, TTable, TReturn, TContext, TArgs>): NamedQueryFunction<TName, TSchema, TTable, TReturn, TContext, TArgs, TArgs>;
+/**
+ * Creates a type-safe query definition function that is parameterized by a
+ * custom context type.
+ *
+ * This utility allows you to define queries with explicit context typing,
+ * ensuring that the query function receives the correct context type. It
+ * returns a function that can be used to define named queries with schema,
+ * table, input, and output types.
+ *
+ * @typeParam TContext - The type of the context object that will be passed to
+ * the query function.
+ *
+ * @returns A function for defining named queries with the specified context
+ * type.
+ *
+ * @example
+ * ```ts
+ * const defineQuery = defineQueryWithContextType<MyContext>();
+ * const myQuery = defineQuery(
+ *   "getUser",
+ *   {validator: z.string()},
+ *   ({ctx, args}) => {
+ *     ctx satisfies MyContext;
+ *     ...
+ *   },
+ * );
+ * ```
+ */
+export declare function defineQueryWithContextType<TContext>(): <TName extends string, TSchema extends Schema, TTable extends keyof TSchema['tables'] & string, TReturn, TOutput extends ReadonlyJSONValue | undefined, TInput extends ReadonlyJSONValue | undefined = TOutput>(name: TName, optionsOrQueryFn: DefineQueryOptions<TInput, TOutput> | DefineQueryFunc<TSchema, TTable, TReturn, TContext, TOutput>, queryFn?: DefineQueryFunc<TSchema, TTable, TReturn, TContext, TOutput>) => NamedQueryFunction<TName, TSchema, TTable, TReturn, TContext, TOutput, TInput>;
+//# sourceMappingURL=define-query.d.ts.map