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

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

@@ -0,0 +1,271 @@
+import { assert } from "../../../shared/src/asserts.js";
+import { must } from "../../../shared/src/must.js";
+import { planIdSymbol } from "../../../zero-protocol/src/ast.js";
+import { PlannerFanIn } from "./planner-fan-in.js";
+import { PlannerFanOut } from "./planner-fan-out.js";
+import { PlannerGraph } from "./planner-graph.js";
+import { PlannerJoin } from "./planner-join.js";
+import { PlannerTerminus } from "./planner-terminus.js";
+function wireOutput(from, to) {
+  switch (from.kind) {
+    case "connection":
+    case "join":
+    case "fan-in":
+      from.setOutput(to);
+      break;
+    case "fan-out":
+      from.addOutput(to);
+      break;
+    case "terminus":
+      assert(false, "Terminus nodes cannot have outputs");
+  }
+}
+function buildPlanGraph(ast, model, isRoot, baseConstraints) {
+  const graph = new PlannerGraph();
+  let nextPlanId = 0;
+  const source = graph.addSource(ast.table, model);
+  const connection = source.connect(
+    ast.orderBy ?? [],
+    ast.where,
+    isRoot,
+    baseConstraints,
+    ast.limit
+  );
+  graph.connections.push(connection);
+  let end = connection;
+  if (ast.where) {
+    end = processCondition(
+      ast.where,
+      end,
+      graph,
+      model,
+      ast.table,
+      () => nextPlanId++
+    );
+  }
+  const terminus = new PlannerTerminus(end);
+  wireOutput(end, terminus);
+  graph.setTerminus(terminus);
+  const subPlans = {};
+  if (ast.related) {
+    for (const csq of ast.related) {
+      const alias = must(
+        csq.subquery.alias,
+        "Related subquery must have alias"
+      );
+      const childConstraints = extractConstraint(
+        csq.correlation.childField,
+        csq.subquery.table
+      );
+      subPlans[alias] = buildPlanGraph(
+        csq.subquery,
+        model,
+        true,
+        childConstraints
+      );
+    }
+  }
+  return { plan: graph, subPlans };
+}
+function processCondition(condition, input, graph, model, parentTable, getPlanId) {
+  switch (condition.type) {
+    case "simple":
+      return input;
+    case "and":
+      return processAnd(condition, input, graph, model, parentTable, getPlanId);
+    case "or":
+      return processOr(condition, input, graph, model, parentTable, getPlanId);
+    case "correlatedSubquery":
+      return processCorrelatedSubquery(
+        condition,
+        input,
+        graph,
+        model,
+        parentTable,
+        getPlanId
+      );
+  }
+}
+function processAnd(condition, input, graph, model, parentTable, getPlanId) {
+  let end = input;
+  for (const subCondition of condition.conditions) {
+    end = processCondition(
+      subCondition,
+      end,
+      graph,
+      model,
+      parentTable,
+      getPlanId
+    );
+  }
+  return end;
+}
+function processOr(condition, input, graph, model, parentTable, getPlanId) {
+  const subqueryConditions = condition.conditions.filter(
+    (c) => c.type === "correlatedSubquery" || hasCorrelatedSubquery(c)
+  );
+  if (subqueryConditions.length === 0) {
+    return input;
+  }
+  const fanOut = new PlannerFanOut(input);
+  graph.fanOuts.push(fanOut);
+  wireOutput(input, fanOut);
+  const branches = [];
+  for (const subCondition of subqueryConditions) {
+    const branch = processCondition(
+      subCondition,
+      fanOut,
+      graph,
+      model,
+      parentTable,
+      getPlanId
+    );
+    branches.push(branch);
+    fanOut.addOutput(branch);
+  }
+  const fanIn = new PlannerFanIn(branches);
+  graph.fanIns.push(fanIn);
+  for (const branch of branches) {
+    wireOutput(branch, fanIn);
+  }
+  return fanIn;
+}
+function processCorrelatedSubquery(condition, input, graph, model, parentTable, getPlanId) {
+  const { related } = condition;
+  const childTable = related.subquery.table;
+  const childSource = graph.hasSource(childTable) ? graph.getSource(childTable) : graph.addSource(childTable, model);
+  const childConnection = childSource.connect(
+    related.subquery.orderBy ?? [],
+    related.subquery.where,
+    false,
+    void 0,
+    // no base constraints for EXISTS/NOT EXISTS
+    condition.op === "EXISTS" ? 1 : void 0
+  );
+  graph.connections.push(childConnection);
+  let childEnd = childConnection;
+  if (related.subquery.where) {
+    childEnd = processCondition(
+      related.subquery.where,
+      childEnd,
+      graph,
+      model,
+      childTable,
+      getPlanId
+    );
+  }
+  const parentConstraint = extractConstraint(
+    related.correlation.parentField
+  );
+  const childConstraint = extractConstraint(
+    related.correlation.childField
+  );
+  const planId = getPlanId();
+  condition[planIdSymbol] = planId;
+  const isNotExists = condition.op === "NOT EXISTS";
+  const manualFlip = condition.flip;
+  let flippable;
+  let initialType;
+  if (isNotExists) {
+    flippable = false;
+    initialType = "semi";
+  } else if (manualFlip === true) {
+    flippable = false;
+    initialType = "flipped";
+  } else if (manualFlip === false) {
+    flippable = false;
+    initialType = "semi";
+  } else {
+    flippable = true;
+    initialType = "semi";
+  }
+  const join = new PlannerJoin(
+    input,
+    childEnd,
+    parentConstraint,
+    childConstraint,
+    flippable,
+    planId,
+    initialType
+  );
+  graph.joins.push(join);
+  wireOutput(input, join);
+  wireOutput(childEnd, join);
+  return join;
+}
+function hasCorrelatedSubquery(condition) {
+  if (condition.type === "correlatedSubquery") {
+    return true;
+  }
+  if (condition.type === "and" || condition.type === "or") {
+    return condition.conditions.some(hasCorrelatedSubquery);
+  }
+  return false;
+}
+function extractConstraint(fields, _tableName) {
+  return Object.fromEntries(fields.map((field) => [field, void 0]));
+}
+function planRecursively(plans, planDebugger) {
+  for (const subPlan of Object.values(plans.subPlans)) {
+    planRecursively(subPlan, planDebugger);
+  }
+  plans.plan.plan(planDebugger);
+}
+function planQuery(ast, model, planDebugger) {
+  const plans = buildPlanGraph(ast, model, true);
+  planRecursively(plans, planDebugger);
+  return applyPlansToAST(ast, plans);
+}
+function applyToCondition(condition, flippedIds) {
+  if (condition.type === "simple") {
+    return condition;
+  }
+  if (condition.type === "correlatedSubquery") {
+    const planId = condition[planIdSymbol];
+    const shouldFlip = planId !== void 0 && flippedIds.has(planId);
+    return {
+      ...condition,
+      flip: shouldFlip,
+      related: {
+        ...condition.related,
+        subquery: {
+          ...condition.related.subquery,
+          where: condition.related.subquery.where ? applyToCondition(condition.related.subquery.where, flippedIds) : void 0
+        }
+      }
+    };
+  }
+  return {
+    ...condition,
+    conditions: condition.conditions.map((c) => applyToCondition(c, flippedIds))
+  };
+}
+function applyPlansToAST(ast, plans) {
+  const flippedIds = /* @__PURE__ */ new Set();
+  for (const join of plans.plan.joins) {
+    if (join.type === "flipped" && join.planId !== void 0) {
+      flippedIds.add(join.planId);
+    }
+  }
+  return {
+    ...ast,
+    where: ast.where ? applyToCondition(ast.where, flippedIds) : void 0,
+    related: ast.related?.map((csq) => {
+      const alias = must(
+        csq.subquery.alias,
+        "Related subquery must have alias"
+      );
+      const subPlan = plans.subPlans[alias];
+      return {
+        ...csq,
+        subquery: subPlan ? applyPlansToAST(csq.subquery, subPlan) : csq.subquery
+      };
+    })
+  };
+}
+export {
+  applyPlansToAST,
+  buildPlanGraph,
+  planQuery
+};
+//# sourceMappingURL=planner-builder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner-builder.js","sources":["../../../../../zql/src/planner/planner-builder.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport type {\n  AST,\n  Condition,\n  Conjunction,\n  CorrelatedSubqueryCondition,\n  Disjunction,\n} from '../../../zero-protocol/src/ast.ts';\nimport {planIdSymbol} from '../../../zero-protocol/src/ast.ts';\nimport type {ConnectionCostModel} from './planner-connection.ts';\nimport type {PlannerConstraint} from './planner-constraint.ts';\nimport type {PlanDebugger} from './planner-debug.ts';\nimport {PlannerFanIn} from './planner-fan-in.ts';\nimport {PlannerFanOut} from './planner-fan-out.ts';\nimport {PlannerGraph} from './planner-graph.ts';\nimport {PlannerJoin} from './planner-join.ts';\nimport type {PlannerNode} from './planner-node.ts';\nimport {PlannerTerminus} from './planner-terminus.ts';\n\nfunction wireOutput(from: PlannerNode, to: PlannerNode): void {\n  switch (from.kind) {\n    case 'connection':\n    case 'join':\n    case 'fan-in':\n      from.setOutput(to);\n      break;\n    case 'fan-out':\n      from.addOutput(to);\n      break;\n    case 'terminus':\n      assert(false, 'Terminus nodes cannot have outputs');\n  }\n}\n\nexport type Plans = {\n  plan: PlannerGraph;\n  subPlans: {[key: string]: Plans};\n};\n\nexport function buildPlanGraph(\n  ast: AST,\n  model: ConnectionCostModel,\n  isRoot: boolean,\n  baseConstraints?: PlannerConstraint,\n): Plans {\n  const graph = new PlannerGraph();\n  let nextPlanId = 0;\n\n  const source = graph.addSource(ast.table, model);\n  const connection = source.connect(\n    ast.orderBy ?? [],\n    ast.where,\n    isRoot,\n    baseConstraints,\n    ast.limit,\n  );\n  graph.connections.push(connection);\n\n  let end: PlannerNode = connection;\n  if (ast.where) {\n    end = processCondition(\n      ast.where,\n      end,\n      graph,\n      model,\n      ast.table,\n      () => nextPlanId++,\n    );\n  }\n\n  const terminus = new PlannerTerminus(end);\n  wireOutput(end, terminus);\n  graph.setTerminus(terminus);\n\n  const subPlans: {[key: string]: Plans} = {};\n  if (ast.related) {\n    for (const csq of ast.related) {\n      const alias = must(\n        csq.subquery.alias,\n        'Related subquery must have alias',\n      );\n      const childConstraints = extractConstraint(\n        csq.correlation.childField,\n        csq.subquery.table,\n      );\n      subPlans[alias] = buildPlanGraph(\n        csq.subquery,\n        model,\n        true,\n        childConstraints,\n      );\n    }\n  }\n\n  return {plan: graph, subPlans};\n}\n\nfunction processCondition(\n  condition: Condition,\n  input: Exclude<PlannerNode, PlannerTerminus>,\n  graph: PlannerGraph,\n  model: ConnectionCostModel,\n  parentTable: string,\n  getPlanId: () => number,\n): Exclude<PlannerNode, PlannerTerminus> {\n  switch (condition.type) {\n    case 'simple':\n      return input;\n    case 'and':\n      return processAnd(condition, input, graph, model, parentTable, getPlanId);\n    case 'or':\n      return processOr(condition, input, graph, model, parentTable, getPlanId);\n    case 'correlatedSubquery':\n      return processCorrelatedSubquery(\n        condition,\n        input,\n        graph,\n        model,\n        parentTable,\n        getPlanId,\n      );\n  }\n}\n\nfunction processAnd(\n  condition: Conjunction,\n  input: Exclude<PlannerNode, PlannerTerminus>,\n  graph: PlannerGraph,\n  model: ConnectionCostModel,\n  parentTable: string,\n  getPlanId: () => number,\n): Exclude<PlannerNode, PlannerTerminus> {\n  let end = input;\n  for (const subCondition of condition.conditions) {\n    end = processCondition(\n      subCondition,\n      end,\n      graph,\n      model,\n      parentTable,\n      getPlanId,\n    );\n  }\n  return end;\n}\n\nfunction processOr(\n  condition: Disjunction,\n  input: Exclude<PlannerNode, PlannerTerminus>,\n  graph: PlannerGraph,\n  model: ConnectionCostModel,\n  parentTable: string,\n  getPlanId: () => number,\n): Exclude<PlannerNode, PlannerTerminus> {\n  const subqueryConditions = condition.conditions.filter(\n    c => c.type === 'correlatedSubquery' || hasCorrelatedSubquery(c),\n  );\n\n  if (subqueryConditions.length === 0) {\n    return input;\n  }\n\n  const fanOut = new PlannerFanOut(input);\n  graph.fanOuts.push(fanOut);\n  wireOutput(input, fanOut);\n\n  const branches: Exclude<PlannerNode, PlannerTerminus>[] = [];\n  for (const subCondition of subqueryConditions) {\n    const branch = processCondition(\n      subCondition,\n      fanOut,\n      graph,\n      model,\n      parentTable,\n      getPlanId,\n    );\n    branches.push(branch);\n    fanOut.addOutput(branch);\n  }\n\n  const fanIn = new PlannerFanIn(branches);\n  graph.fanIns.push(fanIn);\n  for (const branch of branches) {\n    wireOutput(branch, fanIn);\n  }\n\n  return fanIn;\n}\n\nfunction processCorrelatedSubquery(\n  condition: CorrelatedSubqueryCondition,\n  input: Exclude<PlannerNode, PlannerTerminus>,\n  graph: PlannerGraph,\n  model: ConnectionCostModel,\n  parentTable: string,\n  getPlanId: () => number,\n): Exclude<PlannerNode, PlannerTerminus> {\n  const {related} = condition;\n  const childTable = related.subquery.table;\n\n  const childSource = graph.hasSource(childTable)\n    ? graph.getSource(childTable)\n    : graph.addSource(childTable, model);\n\n  const childConnection = childSource.connect(\n    related.subquery.orderBy ?? [],\n    related.subquery.where,\n    false,\n    undefined, // no base constraints for EXISTS/NOT EXISTS\n    condition.op === 'EXISTS' ? 1 : undefined,\n  );\n  graph.connections.push(childConnection);\n\n  let childEnd: PlannerNode = childConnection;\n  if (related.subquery.where) {\n    childEnd = processCondition(\n      related.subquery.where,\n      childEnd,\n      graph,\n      model,\n      childTable,\n      getPlanId,\n    );\n  }\n\n  const parentConstraint = extractConstraint(\n    related.correlation.parentField,\n    parentTable,\n  );\n  const childConstraint = extractConstraint(\n    related.correlation.childField,\n    childTable,\n  );\n\n  const planId = getPlanId();\n  condition[planIdSymbol] = planId;\n\n  // Determine flippability and initial type based on flip flag and operator\n  const isNotExists = condition.op === 'NOT EXISTS';\n  const manualFlip = condition.flip;\n\n  let flippable: boolean;\n  let initialType: 'semi' | 'flipped';\n\n  if (isNotExists) {\n    // NOT EXISTS joins can never be flipped\n    flippable = false;\n    initialType = 'semi';\n  } else if (manualFlip === true) {\n    // User explicitly requested flip=true: start flipped, don't allow planner to change\n    flippable = false;\n    initialType = 'flipped';\n  } else if (manualFlip === false) {\n    // User explicitly requested flip=false: start semi, don't allow planner to change\n    flippable = false;\n    initialType = 'semi';\n  } else {\n    // flip is undefined: planner can decide\n    flippable = true;\n    initialType = 'semi';\n  }\n\n  const join = new PlannerJoin(\n    input,\n    childEnd,\n    parentConstraint,\n    childConstraint,\n    flippable,\n    planId,\n    initialType,\n  );\n  graph.joins.push(join);\n\n  wireOutput(input, join);\n  wireOutput(childEnd, join);\n\n  return join;\n}\n\nfunction hasCorrelatedSubquery(condition: Condition): boolean {\n  if (condition.type === 'correlatedSubquery') {\n    return true;\n  }\n  if (condition.type === 'and' || condition.type === 'or') {\n    return condition.conditions.some(hasCorrelatedSubquery);\n  }\n  return false;\n}\n\nfunction extractConstraint(\n  fields: readonly string[],\n  _tableName: string,\n): PlannerConstraint {\n  return Object.fromEntries(fields.map(field => [field, undefined]));\n}\n\nfunction planRecursively(plans: Plans, planDebugger?: PlanDebugger): void {\n  for (const subPlan of Object.values(plans.subPlans)) {\n    planRecursively(subPlan, planDebugger);\n  }\n  plans.plan.plan(planDebugger);\n}\n\nexport function planQuery(\n  ast: AST,\n  model: ConnectionCostModel,\n  planDebugger?: PlanDebugger,\n): AST {\n  const plans = buildPlanGraph(ast, model, true);\n  planRecursively(plans, planDebugger);\n  return applyPlansToAST(ast, plans);\n}\n\nfunction applyToCondition(\n  condition: Condition,\n  flippedIds: Set<number>,\n): Condition {\n  if (condition.type === 'simple') {\n    return condition;\n  }\n\n  if (condition.type === 'correlatedSubquery') {\n    const planId = (condition as unknown as Record<symbol, number>)[\n      planIdSymbol\n    ];\n    const shouldFlip = planId !== undefined && flippedIds.has(planId);\n\n    return {\n      ...condition,\n      flip: shouldFlip,\n      related: {\n        ...condition.related,\n        subquery: {\n          ...condition.related.subquery,\n          where: condition.related.subquery.where\n            ? applyToCondition(condition.related.subquery.where, flippedIds)\n            : undefined,\n        },\n      },\n    };\n  }\n\n  return {\n    ...condition,\n    conditions: condition.conditions.map(c => applyToCondition(c, flippedIds)),\n  };\n}\n\nexport function applyPlansToAST(ast: AST, plans: Plans): AST {\n  const flippedIds = new Set<number>();\n  for (const join of plans.plan.joins) {\n    if (join.type === 'flipped' && join.planId !== undefined) {\n      flippedIds.add(join.planId);\n    }\n  }\n\n  return {\n    ...ast,\n    where: ast.where ? applyToCondition(ast.where, flippedIds) : undefined,\n    related: ast.related?.map(csq => {\n      const alias = must(\n        csq.subquery.alias,\n        'Related subquery must have alias',\n      );\n      const subPlan = plans.subPlans[alias];\n      return {\n        ...csq,\n        subquery: subPlan\n          ? applyPlansToAST(csq.subquery, subPlan)\n          : csq.subquery,\n      };\n    }),\n  };\n}\n"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,124 @@
+import type { Condition, Ordering } from '../../../zero-protocol/src/ast.ts';
+import { type PlannerConstraint } from './planner-constraint.ts';
+import type { PlanDebugger } from './planner-debug.ts';
+import type { CostEstimate, JoinOrConnection, PlannerNode } from './planner-node.ts';
+/**
+ * Represents a connection to a source (table scan).
+ *
+ * # Dual State Pattern
+ * Like all planner nodes, PlannerConnection separates:
+ * 1. immutable structure: Ordering, filters, cost model (set at construction)
+ * 2. mutable state: Pinned status, constraints (mutated during planning)
+ *
+ * # Cost Estimation
+ * The ordering and filters determine the initial cost. As planning progresses,
+ * constraints from parent joins refine the cost estimate.
+ *
+ * # Constraint Flow
+ * When a connection is pinned as the outer loop, it reveals constraints for
+ * connected joins. These constraints propagate through the graph, allowing
+ * other connections to update their cost estimates.
+ *
+ * Example:
+ *
+ * ```ts
+ * builder.issue.whereExists('assignee', a => a.where('name', 'Alice'))
+ * ```
+ *
+ * ```
+ * [issue]  [assignee]
+ *   |         |
+ *   |         +-- where name = 'Alice'
+ *    \        /
+ *     \      /
+ *      [join]
+ *        |
+ * ```
+ *
+ * - Initial state: Both connections have no constraints, costs are unconstrained
+ * - If `issue` chosen first: Reveals constraint `assignee_id` for assignee connection
+ * - If `assignee` chosen first: Reveals constraint `assignee_id` for issue connection
+ * - Updated costs guide the next selection
+ *
+ * # Lifecycle
+ * 1. Construct with immutable structure (ordering, filters, cost model)
+ * 2. Wire to output node during graph construction
+ * 3. Planning mutates pinned status and accumulates constraints
+ * 4. reset() clears mutable state for replanning
+ */
+export declare class PlannerConnection {
+    #private;
+    readonly kind: "connection";
+    readonly table: string;
+    readonly name: string;
+    readonly selectivity: number;
+    /**
+     * Current limit during planning. Can be cleared (set to undefined) when a
+     * parent join is flipped, indicating this connection is now in an outer loop
+     * and should not be limited by EXISTS semantics.
+     */
+    limit: number | undefined;
+    constructor(table: string, model: ConnectionCostModel, sort: Ordering, filters: Condition | undefined, isRoot: boolean, baseConstraints?: PlannerConstraint, limit?: number, name?: string);
+    setOutput(node: PlannerNode): void;
+    get output(): PlannerNode;
+    closestJoinOrSource(): JoinOrConnection;
+    /**
+     * Constraints are uniquely identified by their path through the
+     * graph.
+     *
+     * FO represents all sub-joins as a single path.
+     * UFO represents each sub-join as a separate path.
+     * The first branch in a UFO will match the path of FO so no re-set needs to happen
+     * when swapping from FO to UFO.
+     *
+     * FO swaps to UFO when a join inside FO-FI gets flipped.
+     *
+     * The max of the last element of the paths is the number of
+     * root branches.
+     */
+    propagateConstraints(path: number[], c: PlannerConstraint | undefined, from?: PlannerNode, planDebugger?: PlanDebugger): void;
+    estimateCost(downstreamChildSelectivity: number, branchPattern: number[], planDebugger?: PlanDebugger): CostEstimate;
+    /**
+     * Remove the limit from this connection.
+     * Called when a parent join is flipped, making this connection part of an
+     * outer loop that should produce all rows rather than stopping at the limit.
+     */
+    unlimit(): void;
+    /**
+     * Propagate unlimiting when a parent join is flipped.
+     * For connections, we simply remove the limit.
+     */
+    propagateUnlimitFromFlippedJoin(): void;
+    reset(): void;
+    /**
+     * Capture constraint state for snapshotting.
+     * Used by PlannerGraph to save/restore planning state.
+     */
+    captureConstraints(): Map<string, PlannerConstraint | undefined>;
+    /**
+     * Restore constraint state from a snapshot.
+     * Used by PlannerGraph to restore planning state.
+     */
+    restoreConstraints(constraints: Map<string, PlannerConstraint | undefined>): void;
+    /** Get current constraints for debugging. */
+    getConstraintsForDebug(): Record<string, PlannerConstraint | undefined>;
+    /** Get filters for debugging. */
+    getFiltersForDebug(): Condition | undefined;
+    /** Get sort/ordering for debugging. */
+    getSortForDebug(): Ordering;
+    /** Get estimated cost for each constraint branch. */
+    getConstraintCostsForDebug(): Record<string, CostEstimate>;
+}
+type FanoutEst = {
+    fanout: number;
+    confidence: 'high' | 'med' | 'none';
+};
+export type FanoutCostModel = (columns: string[]) => FanoutEst;
+export type CostModelCost = {
+    startupCost: number;
+    rows: number;
+    fanout: FanoutCostModel;
+};
+export type ConnectionCostModel = (table: string, sort: Ordering, filters: Condition | undefined, constraint: PlannerConstraint | undefined) => CostModelCost;
+export {};
+//# sourceMappingURL=planner-connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner-connection.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,SAAS,EAAE,QAAQ,EAAC,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,iBAAiB;;IAC5B,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IAQtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAGtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAM7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;gBAqBxB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,mBAAmB,EAC1B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,MAAM,EAAE,OAAO,EACf,eAAe,CAAC,EAAE,iBAAiB,EACnC,KAAK,CAAC,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM;IA4Bf,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIlC,IAAI,MAAM,IAAI,WAAW,CAGxB;IAED,mBAAmB,IAAI,gBAAgB;IAIvC;;;;;;;;;;;;;OAaG;IACH,oBAAoB,CAClB,IAAI,EAAE,MAAM,EAAE,EACd,CAAC,EAAE,iBAAiB,GAAG,SAAS,EAChC,IAAI,CAAC,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,YAAY,GAC1B,IAAI;IAgBP,YAAY,CACV,0BAA0B,EAAE,MAAM,EAClC,aAAa,EAAE,MAAM,EAAE,EACvB,YAAY,CAAC,EAAE,YAAY,GAC1B,YAAY;IAqDf;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAaf;;;OAGG;IACH,+BAA+B,IAAI,IAAI;IAIvC,KAAK;IAOL;;;OAGG;IACH,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAIhE;;;OAGG;IACH,kBAAkB,CAChB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC,GACtD,IAAI;IASP,6CAA6C;IAC7C,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAQvE,iCAAiC;IACjC,kBAAkB,IAAI,SAAS,GAAG,SAAS;IAI3C,uCAAuC;IACvC,eAAe,IAAI,QAAQ;IAI3B,qDAAqD;IACrD,0BAA0B,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;CAO3D;AAED,KAAK,SAAS,GAAG;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;CACrC,CAAC;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAS,CAAC;AAE/D,MAAM,MAAM,aAAa,GAAG;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;CACzB,CAAC;AACF,MAAM,MAAM,mBAAmB,GAAG,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,UAAU,EAAE,iBAAiB,GAAG,SAAS,KACtC,aAAa,CAAC"}

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

@@ -0,0 +1,215 @@
+import { assert } from "../../../shared/src/asserts.js";
+import { mergeConstraints } from "./planner-constraint.js";
+import { omitFanout } from "./planner-node.js";
+class PlannerConnection {
+  kind = "connection";
+  // ========================================================================
+  // IMMUTABLE STRUCTURE (set during construction, never changes)
+  // ========================================================================
+  #sort;
+  #filters;
+  #model;
+  table;
+  name;
+  // Human-readable name for debugging (defaults to table name)
+  #baseConstraints;
+  // Constraints from parent correlation
+  #baseLimit;
+  // Original limit from query structure (never modified)
+  selectivity;
+  // Fraction of rows passing filters (1.0 = no filtering)
+  #output;
+  // Set once during graph construction
+  // ========================================================================
+  // MUTABLE PLANNING STATE (changes during plan search)
+  // ========================================================================
+  /**
+   * Current limit during planning. Can be cleared (set to undefined) when a
+   * parent join is flipped, indicating this connection is now in an outer loop
+   * and should not be limited by EXISTS semantics.
+   */
+  limit;
+  /**
+   * Constraints accumulated from parent joins during planning.
+   * Key is a path through the graph (e.g., "0,1" for branch pattern [0,1]).
+   *
+   * Undefined constraints are possible when a FO converts to UFO and only
+   * a single join in the UFO is flipped - other branches report undefined.
+   */
+  #constraints;
+  #isRoot;
+  /**
+   * Cached per-constraint costs to avoid redundant cost model calls.
+   * Maps constraint key (branch pattern string) to computed cost.
+   * Invalidated when constraints change.
+   */
+  #cachedConstraintCosts = /* @__PURE__ */ new Map();
+  constructor(table, model, sort, filters, isRoot, baseConstraints, limit, name) {
+    this.table = table;
+    this.name = name ?? table;
+    this.#sort = sort;
+    this.#filters = filters;
+    this.#model = model;
+    this.#baseConstraints = baseConstraints;
+    this.#baseLimit = limit;
+    this.limit = limit;
+    this.#constraints = /* @__PURE__ */ new Map();
+    this.#isRoot = isRoot;
+    if (limit !== void 0 && filters) {
+      const costWithFilters = model(table, sort, filters, void 0);
+      const costWithoutFilters = model(table, sort, void 0, void 0);
+      this.selectivity = costWithoutFilters.rows > 0 ? costWithFilters.rows / costWithoutFilters.rows : 1;
+    } else {
+      this.selectivity = 1;
+    }
+  }
+  setOutput(node) {
+    this.#output = node;
+  }
+  get output() {
+    assert(this.#output !== void 0, "Output not set");
+    return this.#output;
+  }
+  closestJoinOrSource() {
+    return "connection";
+  }
+  /**
+   * Constraints are uniquely identified by their path through the
+   * graph.
+   *
+   * FO represents all sub-joins as a single path.
+   * UFO represents each sub-join as a separate path.
+   * The first branch in a UFO will match the path of FO so no re-set needs to happen
+   * when swapping from FO to UFO.
+   *
+   * FO swaps to UFO when a join inside FO-FI gets flipped.
+   *
+   * The max of the last element of the paths is the number of
+   * root branches.
+   */
+  propagateConstraints(path, c, from, planDebugger) {
+    const key = path.join(",");
+    this.#constraints.set(key, c);
+    this.#cachedConstraintCosts.clear();
+    planDebugger?.log({
+      type: "node-constraint",
+      nodeType: "connection",
+      node: this.name,
+      branchPattern: path,
+      constraint: c,
+      from: from?.kind ?? "unknown"
+    });
+  }
+  estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
+    const key = branchPattern.join(",");
+    let cost = this.#cachedConstraintCosts.get(key);
+    if (cost !== void 0) {
+      return cost;
+    }
+    const constraint = this.#constraints.get(key);
+    const mergedConstraint = mergeConstraints(
+      this.#baseConstraints,
+      constraint
+    );
+    const { startupCost, fanout, rows } = this.#model(
+      this.table,
+      this.#sort,
+      this.#filters,
+      mergedConstraint
+    );
+    cost = {
+      startupCost,
+      scanEst: this.limit === void 0 ? rows : Math.min(rows, this.limit / downstreamChildSelectivity),
+      cost: 0,
+      returnedRows: rows,
+      selectivity: this.selectivity,
+      limit: this.limit,
+      fanout
+    };
+    this.#cachedConstraintCosts.set(key, cost);
+    if (planDebugger) {
+      planDebugger.log({
+        type: "node-cost",
+        nodeType: "connection",
+        node: this.name,
+        branchPattern,
+        downstreamChildSelectivity,
+        costEstimate: omitFanout(cost),
+        filters: this.#filters,
+        ordering: this.#sort
+      });
+    }
+    return cost;
+  }
+  /**
+   * Remove the limit from this connection.
+   * Called when a parent join is flipped, making this connection part of an
+   * outer loop that should produce all rows rather than stopping at the limit.
+   */
+  unlimit() {
+    if (this.#isRoot) {
+      return;
+    }
+    if (this.limit !== void 0) {
+      this.limit = void 0;
+    }
+  }
+  /**
+   * Propagate unlimiting when a parent join is flipped.
+   * For connections, we simply remove the limit.
+   */
+  propagateUnlimitFromFlippedJoin() {
+    this.unlimit();
+  }
+  reset() {
+    this.#constraints.clear();
+    this.limit = this.#baseLimit;
+    this.#cachedConstraintCosts.clear();
+  }
+  /**
+   * Capture constraint state for snapshotting.
+   * Used by PlannerGraph to save/restore planning state.
+   */
+  captureConstraints() {
+    return new Map(this.#constraints);
+  }
+  /**
+   * Restore constraint state from a snapshot.
+   * Used by PlannerGraph to restore planning state.
+   */
+  restoreConstraints(constraints) {
+    this.#constraints.clear();
+    for (const [key, value] of constraints) {
+      this.#constraints.set(key, value);
+    }
+    this.#cachedConstraintCosts.clear();
+  }
+  /** Get current constraints for debugging. */
+  getConstraintsForDebug() {
+    const record = {};
+    for (const [key, value] of this.#constraints) {
+      record[key] = value;
+    }
+    return record;
+  }
+  /** Get filters for debugging. */
+  getFiltersForDebug() {
+    return this.#filters;
+  }
+  /** Get sort/ordering for debugging. */
+  getSortForDebug() {
+    return this.#sort;
+  }
+  /** Get estimated cost for each constraint branch. */
+  getConstraintCostsForDebug() {
+    const record = {};
+    for (const [key, value] of this.#cachedConstraintCosts) {
+      record[key] = value;
+    }
+    return record;
+  }
+}
+export {
+  PlannerConnection
+};
+//# sourceMappingURL=planner-connection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner-connection.js","sources":["../../../../../zql/src/planner/planner-connection.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport type {Condition, Ordering} from '../../../zero-protocol/src/ast.ts';\nimport {\n  mergeConstraints,\n  type PlannerConstraint,\n} from './planner-constraint.ts';\nimport type {PlanDebugger} from './planner-debug.ts';\nimport {omitFanout} from './planner-node.ts';\nimport type {\n  CostEstimate,\n  JoinOrConnection,\n  PlannerNode,\n} from './planner-node.ts';\n\n/**\n * Represents a connection to a source (table scan).\n *\n * # Dual State Pattern\n * Like all planner nodes, PlannerConnection separates:\n * 1. immutable structure: Ordering, filters, cost model (set at construction)\n * 2. mutable state: Pinned status, constraints (mutated during planning)\n *\n * # Cost Estimation\n * The ordering and filters determine the initial cost. As planning progresses,\n * constraints from parent joins refine the cost estimate.\n *\n * # Constraint Flow\n * When a connection is pinned as the outer loop, it reveals constraints for\n * connected joins. These constraints propagate through the graph, allowing\n * other connections to update their cost estimates.\n *\n * Example:\n *\n * ```ts\n * builder.issue.whereExists('assignee', a => a.where('name', 'Alice'))\n * ```\n *\n * ```\n * [issue]  [assignee]\n *   |         |\n *   |         +-- where name = 'Alice'\n *    \\        /\n *     \\      /\n *      [join]\n *        |\n * ```\n *\n * - Initial state: Both connections have no constraints, costs are unconstrained\n * - If `issue` chosen first: Reveals constraint `assignee_id` for assignee connection\n * - If `assignee` chosen first: Reveals constraint `assignee_id` for issue connection\n * - Updated costs guide the next selection\n *\n * # Lifecycle\n * 1. Construct with immutable structure (ordering, filters, cost model)\n * 2. Wire to output node during graph construction\n * 3. Planning mutates pinned status and accumulates constraints\n * 4. reset() clears mutable state for replanning\n */\nexport class PlannerConnection {\n  readonly kind = 'connection' as const;\n\n  // ========================================================================\n  // IMMUTABLE STRUCTURE (set during construction, never changes)\n  // ========================================================================\n  readonly #sort: Ordering;\n  readonly #filters: Condition | undefined;\n  readonly #model: ConnectionCostModel;\n  readonly table: string;\n  readonly name: string; // Human-readable name for debugging (defaults to table name)\n  readonly #baseConstraints: PlannerConstraint | undefined; // Constraints from parent correlation\n  readonly #baseLimit: number | undefined; // Original limit from query structure (never modified)\n  readonly selectivity: number; // Fraction of rows passing filters (1.0 = no filtering)\n  #output?: PlannerNode | undefined; // Set once during graph construction\n\n  // ========================================================================\n  // MUTABLE PLANNING STATE (changes during plan search)\n  // ========================================================================\n  /**\n   * Current limit during planning. Can be cleared (set to undefined) when a\n   * parent join is flipped, indicating this connection is now in an outer loop\n   * and should not be limited by EXISTS semantics.\n   */\n  limit: number | undefined;\n\n  /**\n   * Constraints accumulated from parent joins during planning.\n   * Key is a path through the graph (e.g., \"0,1\" for branch pattern [0,1]).\n   *\n   * Undefined constraints are possible when a FO converts to UFO and only\n   * a single join in the UFO is flipped - other branches report undefined.\n   */\n  readonly #constraints: Map<string, PlannerConstraint | undefined>;\n\n  readonly #isRoot: boolean;\n\n  /**\n   * Cached per-constraint costs to avoid redundant cost model calls.\n   * Maps constraint key (branch pattern string) to computed cost.\n   * Invalidated when constraints change.\n   */\n  #cachedConstraintCosts: Map<string, CostEstimate> = new Map();\n\n  constructor(\n    table: string,\n    model: ConnectionCostModel,\n    sort: Ordering,\n    filters: Condition | undefined,\n    isRoot: boolean,\n    baseConstraints?: PlannerConstraint,\n    limit?: number,\n    name?: string,\n  ) {\n    this.table = table;\n    this.name = name ?? table;\n    this.#sort = sort;\n    this.#filters = filters;\n    this.#model = model;\n    this.#baseConstraints = baseConstraints;\n    this.#baseLimit = limit;\n    this.limit = limit;\n    this.#constraints = new Map();\n    this.#isRoot = isRoot;\n\n    // Compute selectivity for EXISTS child connections (baseLimit === 1)\n    // Selectivity = fraction of rows that pass filters\n    if (limit !== undefined && filters) {\n      const costWithFilters = model(table, sort, filters, undefined);\n      const costWithoutFilters = model(table, sort, undefined, undefined);\n      this.selectivity =\n        costWithoutFilters.rows > 0\n          ? costWithFilters.rows / costWithoutFilters.rows\n          : 1.0;\n    } else {\n      // Root connections or connections without filters\n      this.selectivity = 1.0;\n    }\n  }\n\n  setOutput(node: PlannerNode): void {\n    this.#output = node;\n  }\n\n  get output(): PlannerNode {\n    assert(this.#output !== undefined, 'Output not set');\n    return this.#output;\n  }\n\n  closestJoinOrSource(): JoinOrConnection {\n    return 'connection';\n  }\n\n  /**\n   * Constraints are uniquely identified by their path through the\n   * graph.\n   *\n   * FO represents all sub-joins as a single path.\n   * UFO represents each sub-join as a separate path.\n   * The first branch in a UFO will match the path of FO so no re-set needs to happen\n   * when swapping from FO to UFO.\n   *\n   * FO swaps to UFO when a join inside FO-FI gets flipped.\n   *\n   * The max of the last element of the paths is the number of\n   * root branches.\n   */\n  propagateConstraints(\n    path: number[],\n    c: PlannerConstraint | undefined,\n    from?: PlannerNode,\n    planDebugger?: PlanDebugger,\n  ): void {\n    const key = path.join(',');\n    this.#constraints.set(key, c);\n    // Constraints changed, invalidate cost caches\n    this.#cachedConstraintCosts.clear();\n\n    planDebugger?.log({\n      type: 'node-constraint',\n      nodeType: 'connection',\n      node: this.name,\n      branchPattern: path,\n      constraint: c,\n      from: from?.kind ?? 'unknown',\n    });\n  }\n\n  estimateCost(\n    downstreamChildSelectivity: number,\n    branchPattern: number[],\n    planDebugger?: PlanDebugger,\n  ): CostEstimate {\n    // Branch pattern specified - return cost for this specific branch\n    const key = branchPattern.join(',');\n\n    // Check per-constraint cache first\n    let cost = this.#cachedConstraintCosts.get(key);\n    if (cost !== undefined) {\n      return cost;\n    }\n\n    // Cache miss - compute and cache\n    const constraint = this.#constraints.get(key);\n    // Merge base constraints with propagated constraints\n    const mergedConstraint = mergeConstraints(\n      this.#baseConstraints,\n      constraint,\n    );\n    const {startupCost, fanout, rows} = this.#model(\n      this.table,\n      this.#sort,\n      this.#filters,\n      mergedConstraint,\n    );\n    cost = {\n      startupCost,\n      scanEst:\n        this.limit === undefined\n          ? rows\n          : Math.min(rows, this.limit / downstreamChildSelectivity),\n      cost: 0,\n      returnedRows: rows,\n      selectivity: this.selectivity,\n      limit: this.limit,\n      fanout,\n    };\n    this.#cachedConstraintCosts.set(key, cost);\n\n    if (planDebugger) {\n      planDebugger.log({\n        type: 'node-cost',\n        nodeType: 'connection',\n        node: this.name,\n        branchPattern,\n        downstreamChildSelectivity,\n        costEstimate: omitFanout(cost),\n        filters: this.#filters,\n        ordering: this.#sort,\n      });\n    }\n\n    return cost;\n  }\n\n  /**\n   * Remove the limit from this connection.\n   * Called when a parent join is flipped, making this connection part of an\n   * outer loop that should produce all rows rather than stopping at the limit.\n   */\n  unlimit(): void {\n    if (this.#isRoot) {\n      // We cannot unlimit root connections\n      return;\n    }\n    if (this.limit !== undefined) {\n      this.limit = undefined;\n      // Limit changes do not impact connection costs.\n      // Limit is taken into account at the join level.\n      // Given that, we do not need to invalidate cost caches here.\n    }\n  }\n\n  /**\n   * Propagate unlimiting when a parent join is flipped.\n   * For connections, we simply remove the limit.\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    this.unlimit();\n  }\n\n  reset() {\n    this.#constraints.clear();\n    this.limit = this.#baseLimit;\n    // Clear all cost caches\n    this.#cachedConstraintCosts.clear();\n  }\n\n  /**\n   * Capture constraint state for snapshotting.\n   * Used by PlannerGraph to save/restore planning state.\n   */\n  captureConstraints(): Map<string, PlannerConstraint | undefined> {\n    return new Map(this.#constraints);\n  }\n\n  /**\n   * Restore constraint state from a snapshot.\n   * Used by PlannerGraph to restore planning state.\n   */\n  restoreConstraints(\n    constraints: Map<string, PlannerConstraint | undefined>,\n  ): void {\n    this.#constraints.clear();\n    for (const [key, value] of constraints) {\n      this.#constraints.set(key, value);\n    }\n    // Constraints changed, invalidate cost caches\n    this.#cachedConstraintCosts.clear();\n  }\n\n  /** Get current constraints for debugging. */\n  getConstraintsForDebug(): Record<string, PlannerConstraint | undefined> {\n    const record: Record<string, PlannerConstraint | undefined> = {};\n    for (const [key, value] of this.#constraints) {\n      record[key] = value;\n    }\n    return record;\n  }\n\n  /** Get filters for debugging. */\n  getFiltersForDebug(): Condition | undefined {\n    return this.#filters;\n  }\n\n  /** Get sort/ordering for debugging. */\n  getSortForDebug(): Ordering {\n    return this.#sort;\n  }\n\n  /** Get estimated cost for each constraint branch. */\n  getConstraintCostsForDebug(): Record<string, CostEstimate> {\n    const record: Record<string, CostEstimate> = {};\n    for (const [key, value] of this.#cachedConstraintCosts) {\n      record[key] = value;\n    }\n    return record;\n  }\n}\n\ntype FanoutEst = {\n  fanout: number;\n  confidence: 'high' | 'med' | 'none';\n};\nexport type FanoutCostModel = (columns: string[]) => FanoutEst;\n\nexport type CostModelCost = {\n  startupCost: number;\n  rows: number;\n  fanout: FanoutCostModel;\n};\nexport type ConnectionCostModel = (\n  table: string,\n  sort: Ordering,\n  filters: Condition | undefined,\n  constraint: PlannerConstraint | undefined,\n) => CostModelCost;\n"],"names":[],"mappings":"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"}