@rocicorp/zero 0.26.1 → 0.26.2-canary.1

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

@@ -1 +1 @@
-{"version":3,"file":"planner-graph.js","sources":["../../../../../zql/src/planner/planner-graph.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport type {PlanDebugger} from './planner-debug.ts';\nimport type {PlannerConnection} from './planner-connection.ts';\nimport type {PlannerConstraint} from './planner-constraint.ts';\nimport type {PlannerFanIn} from './planner-fan-in.ts';\nimport type {PlannerFanOut} from './planner-fan-out.ts';\nimport type {PlannerJoin} from './planner-join.ts';\nimport {omitFanout} from './planner-node.ts';\nimport type {PlannerNode} from './planner-node.ts';\nimport {PlannerSource, type ConnectionCostModel} from './planner-source.ts';\nimport type {PlannerTerminus} from './planner-terminus.ts';\n\n/**\n * Captured state of a plan for comparison and restoration.\n */\nexport type PlanState = {\n  connections: Array<{limit: number | undefined}>;\n  joins: Array<{type: 'semi' | 'flipped'}>;\n  fanOuts: Array<{type: 'FO' | 'UFO'}>;\n  fanIns: Array<{type: 'FI' | 'UFI'}>;\n  connectionConstraints: Array<Map<string, PlannerConstraint | undefined>>;\n};\n\n/**\n * Maximum number of flippable joins to attempt exhaustive enumeration.\n * With n flippable joins, we explore 2^n plans.\n * 10 joins = 1024 plans (~100-200ms), 12 joins = 4096 plans (~400ms - 1 second)\n */\nconst MAX_FLIPPABLE_JOINS = 9;\n\n/**\n * Cached information about FanOut→FanIn relationships.\n * Computed once during planning to avoid redundant BFS traversals.\n */\ntype FOFIInfo = {\n  fi: PlannerFanIn | undefined;\n  joinsBetween: PlannerJoin[];\n};\n\nexport class PlannerGraph {\n  // Sources indexed by table name\n  readonly #sources = new Map<string, PlannerSource>();\n\n  // The final output node where constraint propagation starts\n  #terminus: PlannerTerminus | undefined = undefined;\n\n  // Collections of nodes with mutable planning state\n  joins: PlannerJoin[] = [];\n  fanOuts: PlannerFanOut[] = [];\n  fanIns: PlannerFanIn[] = [];\n  connections: PlannerConnection[] = [];\n\n  /**\n   * Reset all planning state back to initial values for another planning pass.\n   * Resets only mutable planning state - graph structure is unchanged.\n   *\n   * This allows replanning the same query graph with different strategies.\n   */\n  resetPlanningState() {\n    for (const j of this.joins) j.reset();\n    for (const fo of this.fanOuts) fo.reset();\n    for (const fi of this.fanIns) fi.reset();\n    for (const c of this.connections) c.reset();\n  }\n\n  /**\n   * Create and register a source (table) in the graph.\n   */\n  addSource(name: string, model: ConnectionCostModel): PlannerSource {\n    assert(\n      !this.#sources.has(name),\n      `Source ${name} already exists in the graph`,\n    );\n    const source = new PlannerSource(name, model);\n    this.#sources.set(name, source);\n    return source;\n  }\n\n  /**\n   * Get a source by table name.\n   */\n  getSource(name: string): PlannerSource {\n    const source = this.#sources.get(name);\n    assert(source !== undefined, `Source ${name} not found in the graph`);\n    return source;\n  }\n\n  /**\n   * Check if a source exists by table name.\n   */\n  hasSource(name: string): boolean {\n    return this.#sources.has(name);\n  }\n\n  /**\n   * Set the terminus (final output) node of the graph.\n   * Constraint propagation starts from this node.\n   */\n  setTerminus(terminus: PlannerTerminus): void {\n    this.#terminus = terminus;\n  }\n\n  /**\n   * Initiate constraint propagation from the terminus node.\n   * This sends constraints up through the graph to update\n   * connection cost estimates.\n   */\n  propagateConstraints(planDebugger?: PlanDebugger): void {\n    assert(\n      this.#terminus !== undefined,\n      'Cannot propagate constraints without a terminus node',\n    );\n    this.#terminus.propagateConstraints(planDebugger);\n  }\n\n  /**\n   * Calculate total cost of the current plan.\n   * Total cost includes both startup cost (one-time, e.g., sorting) and running cost.\n   */\n  getTotalCost(planDebugger?: PlanDebugger): number {\n    const estimate = must(this.#terminus).estimateCost(planDebugger);\n    return estimate.cost + estimate.startupCost;\n  }\n\n  /**\n   * Capture a lightweight snapshot of the current planning state.\n   * Used for backtracking during multi-start greedy search.\n   *\n   * Captures mutable state including pinned flags, join types, and\n   * constraint maps to avoid needing repropagation on restore.\n   *\n   * @returns A snapshot that can be restored via restorePlanningSnapshot()\n   */\n  capturePlanningSnapshot(): PlanState {\n    return {\n      connections: this.connections.map(c => ({\n        limit: c.limit,\n      })),\n      joins: this.joins.map(j => ({type: j.type})),\n      fanOuts: this.fanOuts.map(fo => ({type: fo.type})),\n      fanIns: this.fanIns.map(fi => ({type: fi.type})),\n      connectionConstraints: this.connections.map(c => c.captureConstraints()),\n    };\n  }\n\n  /**\n   * Restore planning state from a previously captured snapshot.\n   * Used for backtracking when a planning attempt fails.\n   *\n   * Restores pinned flags, join types, and constraint maps, eliminating\n   * the need for repropagation.\n   *\n   * @param state - Snapshot created by capturePlanningSnapshot()\n   */\n  restorePlanningSnapshot(state: PlanState): void {\n    this.#validateSnapshotShape(state);\n    this.#restoreConnections(state);\n    this.#restoreJoins(state);\n    this.#restoreFanNodes(state);\n  }\n\n  /**\n   * Validate that snapshot shape matches current graph structure.\n   */\n  #validateSnapshotShape(state: PlanState): void {\n    assert(\n      this.connections.length === state.connections.length,\n      'Plan state mismatch: connections',\n    );\n    assert(\n      this.joins.length === state.joins.length,\n      'Plan state mismatch: joins',\n    );\n    assert(\n      this.fanOuts.length === state.fanOuts.length,\n      'Plan state mismatch: fanOuts',\n    );\n    assert(\n      this.fanIns.length === state.fanIns.length,\n      'Plan state mismatch: fanIns',\n    );\n    assert(\n      this.connections.length === state.connectionConstraints.length,\n      'Plan state mismatch: connectionConstraints',\n    );\n  }\n\n  /**\n   * Restore connection pinned flags, limits, and constraint maps.\n   */\n  #restoreConnections(state: PlanState): void {\n    for (let i = 0; i < this.connections.length; i++) {\n      this.connections[i].limit = state.connections[i].limit;\n      this.connections[i].restoreConstraints(state.connectionConstraints[i]);\n    }\n  }\n\n  /**\n   * Restore join types and pinned flags.\n   */\n  #restoreJoins(state: PlanState): void {\n    for (let i = 0; i < this.joins.length; i++) {\n      const join = this.joins[i];\n      const targetState = state.joins[i];\n\n      // Reset to initial state first\n      join.reset();\n\n      // Apply target state\n      if (targetState.type === 'flipped' && join.type !== 'flipped') {\n        join.flip();\n      }\n      assert(\n        targetState.type === join.type,\n        'join is not in the correct state after reset',\n      );\n    }\n  }\n\n  /**\n   * Restore FanOut and FanIn types.\n   */\n  #restoreFanNodes(state: PlanState): void {\n    for (let i = 0; i < this.fanOuts.length; i++) {\n      const fo = this.fanOuts[i];\n      const targetType = state.fanOuts[i].type;\n      if (targetType === 'UFO' && fo.type === 'FO') {\n        fo.convertToUFO();\n      }\n    }\n\n    for (let i = 0; i < this.fanIns.length; i++) {\n      const fi = this.fanIns[i];\n      const targetType = state.fanIns[i].type;\n      if (targetType === 'UFI' && fi.type === 'FI') {\n        fi.convertToUFI();\n      }\n    }\n  }\n\n  /**\n   * Main planning algorithm using exhaustive join flip enumeration.\n   *\n   * Enumerates all possible flip patterns for flippable joins (2^n for n flippable joins).\n   * Each pattern represents a different query execution plan. We evaluate the cost of each\n   * plan and select the one with the lowest cost.\n   *\n   * Connections are used only for cost estimation - the flip patterns determine the plan.\n   * FanOut/FanIn states (FO/UFO and FI/UFI) are automatically derived from join flip states.\n   *\n   * @param planDebugger - Optional debugger to receive structured events during planning\n   * @param lc - Optional logger for warnings\n   */\n  plan(planDebugger?: PlanDebugger, lc?: LogContext): void {\n    // Get all flippable joins\n    const flippableJoins = this.joins.filter(j => j.isFlippable());\n\n    // Too many flippable joins - skip optimization and run as-is\n    if (flippableJoins.length > MAX_FLIPPABLE_JOINS) {\n      lc?.warn?.(\n        `Query has ${flippableJoins.length} EXISTS checks which would require ` +\n          `${2 ** flippableJoins.length} plan evaluations. Skipping optimization.`,\n      );\n      return;\n    }\n\n    // Build FO→FI cache once to avoid redundant BFS traversals in each iteration\n    const fofiCache = buildFOFICache(this);\n\n    const numPatterns =\n      flippableJoins.length === 0 ? 0 : 2 ** flippableJoins.length;\n    let bestCost = Infinity;\n    let bestPlan: PlanState | undefined = undefined;\n    let bestAttemptNumber = -1;\n\n    // Enumerate all flip patterns\n    for (let pattern = 0; pattern < numPatterns; pattern++) {\n      // Reset to initial state\n      this.resetPlanningState();\n\n      if (planDebugger) {\n        planDebugger.log({\n          type: 'attempt-start',\n          attemptNumber: pattern,\n          totalAttempts: numPatterns,\n        });\n      }\n\n      // Apply flip pattern (treat pattern as bitmask)\n      // Bit i set to 1 means flip join i\n      for (let i = 0; i < flippableJoins.length; i++) {\n        if (pattern & (1 << i)) {\n          flippableJoins[i].flip();\n        }\n      }\n\n      // Derive FO/UFO and FI/UFI states from join flip states\n      checkAndConvertFOFI(fofiCache);\n\n      // Propagate unlimiting for flipped joins\n      propagateUnlimitForFlippedJoins(this);\n\n      // Propagate constraints through the graph\n      this.propagateConstraints(planDebugger);\n\n      if (planDebugger) {\n        planDebugger.log({\n          type: 'constraints-propagated',\n          attemptNumber: pattern,\n          connectionConstraints: this.connections.map(c => {\n            const constraintCosts = c.getConstraintCostsForDebug();\n            const constraintCostsWithoutFanout: Record<\n              string,\n              Omit<(typeof constraintCosts)[string], 'fanout'>\n            > = {};\n            for (const [key, cost] of Object.entries(constraintCosts)) {\n              constraintCostsWithoutFanout[key] = omitFanout(cost);\n            }\n            return {\n              connection: c.name,\n              constraints: c.getConstraintsForDebug(),\n              constraintCosts: constraintCostsWithoutFanout,\n            };\n          }),\n        });\n      }\n\n      // Evaluate this plan\n      const totalCost = this.getTotalCost(planDebugger);\n\n      if (planDebugger) {\n        planDebugger.log({\n          type: 'plan-complete',\n          attemptNumber: pattern,\n          totalCost,\n          flipPattern: pattern, // Bitmask of which joins are flipped\n          planSnapshot: this.capturePlanningSnapshot(),\n          joinStates: this.joins.map(j => {\n            const info = j.getDebugInfo();\n            return {\n              join: info.name,\n              type: info.type,\n            };\n          }),\n        });\n      }\n\n      // Track best plan\n      if (totalCost < bestCost) {\n        bestCost = totalCost;\n        bestPlan = this.capturePlanningSnapshot();\n        bestAttemptNumber = pattern;\n      }\n    }\n\n    // Restore best plan\n    if (bestPlan) {\n      this.restorePlanningSnapshot(bestPlan);\n      // Propagate constraints to ensure all derived state is consistent\n      this.propagateConstraints(planDebugger);\n\n      if (planDebugger) {\n        planDebugger.log({\n          type: 'best-plan-selected',\n          bestAttemptNumber,\n          totalCost: bestCost,\n          flipPattern: bestAttemptNumber, // The best attempt number is also the flip pattern\n          joinStates: this.joins.map(j => ({\n            join: j.getName(),\n            type: j.type,\n          })),\n        });\n      }\n    } else {\n      assert(\n        numPatterns === 0,\n        'no plan was found but flippable joins did exist!',\n      );\n    }\n  }\n}\n\n/**\n * Build cache of FO→FI relationships and joins between them.\n * Called once at the start of planning to avoid redundant BFS traversals.\n */\nfunction buildFOFICache(graph: PlannerGraph): Map<PlannerFanOut, FOFIInfo> {\n  const cache = new Map<PlannerFanOut, FOFIInfo>();\n\n  for (const fo of graph.fanOuts) {\n    const info = findFIAndJoins(fo);\n    cache.set(fo, info);\n  }\n\n  return cache;\n}\n\n/**\n * Check if any joins downstream of a FanOut (before reaching FanIn) are flipped.\n * If so, convert the FO to UFO and the FI to UFI.\n *\n * This must be called after join flipping and before propagateConstraints.\n */\nfunction checkAndConvertFOFI(fofiCache: Map<PlannerFanOut, FOFIInfo>): void {\n  for (const [fo, info] of fofiCache) {\n    const hasFlippedJoin = info.joinsBetween.some(j => j.type === 'flipped');\n    if (info.fi && hasFlippedJoin) {\n      fo.convertToUFO();\n      info.fi.convertToUFI();\n    }\n  }\n}\n\n/**\n * Traverse from a FanOut through its outputs to find the corresponding FanIn\n * and collect all joins along the way.\n */\nfunction findFIAndJoins(fo: PlannerFanOut): FOFIInfo {\n  const joinsBetween: PlannerJoin[] = [];\n  let fi: PlannerFanIn | undefined = undefined;\n\n  // BFS through FO outputs to find FI and collect joins\n  const queue: PlannerNode[] = [...fo.outputs];\n  const visited = new Set<PlannerNode>();\n\n  while (queue.length > 0) {\n    const node = must(queue.shift());\n    if (visited.has(node)) continue;\n    visited.add(node);\n\n    switch (node.kind) {\n      case 'join':\n        joinsBetween.push(node);\n        queue.push(node.output);\n        break;\n      case 'fan-out':\n        // Nested FO - traverse its outputs\n        queue.push(...node.outputs);\n        break;\n      case 'fan-in':\n        // Found the FI - this is the boundary, don't traverse further\n        fi = node;\n        break;\n      case 'connection':\n        // Shouldn't happen in a well-formed graph\n        break;\n      case 'terminus':\n        // Reached the end without finding FI\n        break;\n    }\n  }\n\n  return {fi, joinsBetween};\n}\n\n/**\n * Propagate unlimiting to all flipped joins in the graph.\n * When a join is flipped, its child becomes the outer loop and should no longer\n * be limited by EXISTS semantics.\n *\n * This must be called after join flipping and before propagateConstraints.\n */\nfunction propagateUnlimitForFlippedJoins(graph: PlannerGraph): void {\n  for (const join of graph.joins) {\n    if (join.type === 'flipped') {\n      join.propagateUnlimit();\n    }\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"planner-graph.js","names":["#sources","#terminus","#validateSnapshotShape","#restoreConnections","#restoreJoins","#restoreFanNodes"],"sources":["../../../../../zql/src/planner/planner-graph.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport type {PlanDebugger} from './planner-debug.ts';\nimport type {PlannerConnection} from './planner-connection.ts';\nimport type {PlannerConstraint} from './planner-constraint.ts';\nimport type {PlannerFanIn} from './planner-fan-in.ts';\nimport type {PlannerFanOut} from './planner-fan-out.ts';\nimport type {PlannerJoin} from './planner-join.ts';\nimport {omitFanout} from './planner-node.ts';\nimport type {PlannerNode} from './planner-node.ts';\nimport {PlannerSource, type ConnectionCostModel} from './planner-source.ts';\nimport type {PlannerTerminus} from './planner-terminus.ts';\n\n/**\n * Captured state of a plan for comparison and restoration.\n */\nexport type PlanState = {\n  connections: Array<{limit: number | undefined}>;\n  joins: Array<{type: 'semi' | 'flipped'}>;\n  fanOuts: Array<{type: 'FO' | 'UFO'}>;\n  fanIns: Array<{type: 'FI' | 'UFI'}>;\n  connectionConstraints: Array<Map<string, PlannerConstraint | undefined>>;\n};\n\n/**\n * Maximum number of flippable joins to attempt exhaustive enumeration.\n * With n flippable joins, we explore 2^n plans.\n * 10 joins = 1024 plans (~100-200ms), 12 joins = 4096 plans (~400ms - 1 second)\n */\nconst MAX_FLIPPABLE_JOINS = 9;\n\n/**\n * Cached information about FanOut→FanIn relationships.\n * Computed once during planning to avoid redundant BFS traversals.\n */\ntype FOFIInfo = {\n  fi: PlannerFanIn | undefined;\n  joinsBetween: PlannerJoin[];\n};\n\nexport class PlannerGraph {\n  // Sources indexed by table name\n  readonly #sources = new Map<string, PlannerSource>();\n\n  // The final output node where constraint propagation starts\n  #terminus: PlannerTerminus | undefined = undefined;\n\n  // Collections of nodes with mutable planning state\n  joins: PlannerJoin[] = [];\n  fanOuts: PlannerFanOut[] = [];\n  fanIns: PlannerFanIn[] = [];\n  connections: PlannerConnection[] = [];\n\n  /**\n   * Reset all planning state back to initial values for another planning pass.\n   * Resets only mutable planning state - graph structure is unchanged.\n   *\n   * This allows replanning the same query graph with different strategies.\n   */\n  resetPlanningState() {\n    for (const j of this.joins) j.reset();\n    for (const fo of this.fanOuts) fo.reset();\n    for (const fi of this.fanIns) fi.reset();\n    for (const c of this.connections) c.reset();\n  }\n\n  /**\n   * Create and register a source (table) in the graph.\n   */\n  addSource(name: string, model: ConnectionCostModel): PlannerSource {\n    assert(\n      !this.#sources.has(name),\n      `Source ${name} already exists in the graph`,\n    );\n    const source = new PlannerSource(name, model);\n    this.#sources.set(name, source);\n    return source;\n  }\n\n  /**\n   * Get a source by table name.\n   */\n  getSource(name: string): PlannerSource {\n    const source = this.#sources.get(name);\n    assert(source !== undefined, `Source ${name} not found in the graph`);\n    return source;\n  }\n\n  /**\n   * Check if a source exists by table name.\n   */\n  hasSource(name: string): boolean {\n    return this.#sources.has(name);\n  }\n\n  /**\n   * Set the terminus (final output) node of the graph.\n   * Constraint propagation starts from this node.\n   */\n  setTerminus(terminus: PlannerTerminus): void {\n    this.#terminus = terminus;\n  }\n\n  /**\n   * Initiate constraint propagation from the terminus node.\n   * This sends constraints up through the graph to update\n   * connection cost estimates.\n   */\n  propagateConstraints(planDebugger?: PlanDebugger): void {\n    assert(\n      this.#terminus !== undefined,\n      'Cannot propagate constraints without a terminus node',\n    );\n    this.#terminus.propagateConstraints(planDebugger);\n  }\n\n  /**\n   * Calculate total cost of the current plan.\n   * Total cost includes both startup cost (one-time, e.g., sorting) and running cost.\n   */\n  getTotalCost(planDebugger?: PlanDebugger): number {\n    const estimate = must(this.#terminus).estimateCost(planDebugger);\n    return estimate.cost + estimate.startupCost;\n  }\n\n  /**\n   * Capture a lightweight snapshot of the current planning state.\n   * Used for backtracking during multi-start greedy search.\n   *\n   * Captures mutable state including pinned flags, join types, and\n   * constraint maps to avoid needing repropagation on restore.\n   *\n   * @returns A snapshot that can be restored via restorePlanningSnapshot()\n   */\n  capturePlanningSnapshot(): PlanState {\n    return {\n      connections: this.connections.map(c => ({\n        limit: c.limit,\n      })),\n      joins: this.joins.map(j => ({type: j.type})),\n      fanOuts: this.fanOuts.map(fo => ({type: fo.type})),\n      fanIns: this.fanIns.map(fi => ({type: fi.type})),\n      connectionConstraints: this.connections.map(c => c.captureConstraints()),\n    };\n  }\n\n  /**\n   * Restore planning state from a previously captured snapshot.\n   * Used for backtracking when a planning attempt fails.\n   *\n   * Restores pinned flags, join types, and constraint maps, eliminating\n   * the need for repropagation.\n   *\n   * @param state - Snapshot created by capturePlanningSnapshot()\n   */\n  restorePlanningSnapshot(state: PlanState): void {\n    this.#validateSnapshotShape(state);\n    this.#restoreConnections(state);\n    this.#restoreJoins(state);\n    this.#restoreFanNodes(state);\n  }\n\n  /**\n   * Validate that snapshot shape matches current graph structure.\n   */\n  #validateSnapshotShape(state: PlanState): void {\n    assert(\n      this.connections.length === state.connections.length,\n      'Plan state mismatch: connections',\n    );\n    assert(\n      this.joins.length === state.joins.length,\n      'Plan state mismatch: joins',\n    );\n    assert(\n      this.fanOuts.length === state.fanOuts.length,\n      'Plan state mismatch: fanOuts',\n    );\n    assert(\n      this.fanIns.length === state.fanIns.length,\n      'Plan state mismatch: fanIns',\n    );\n    assert(\n      this.connections.length === state.connectionConstraints.length,\n      'Plan state mismatch: connectionConstraints',\n    );\n  }\n\n  /**\n   * Restore connection pinned flags, limits, and constraint maps.\n   */\n  #restoreConnections(state: PlanState): void {\n    for (let i = 0; i < this.connections.length; i++) {\n      this.connections[i].limit = state.connections[i].limit;\n      this.connections[i].restoreConstraints(state.connectionConstraints[i]);\n    }\n  }\n\n  /**\n   * Restore join types and pinned flags.\n   */\n  #restoreJoins(state: PlanState): void {\n    for (let i = 0; i < this.joins.length; i++) {\n      const join = this.joins[i];\n      const targetState = state.joins[i];\n\n      // Reset to initial state first\n      join.reset();\n\n      // Apply target state\n      if (targetState.type === 'flipped' && join.type !== 'flipped') {\n        join.flip();\n      }\n      assert(\n        targetState.type === join.type,\n        'join is not in the correct state after reset',\n      );\n    }\n  }\n\n  /**\n   * Restore FanOut and FanIn types.\n   */\n  #restoreFanNodes(state: PlanState): void {\n    for (let i = 0; i < this.fanOuts.length; i++) {\n      const fo = this.fanOuts[i];\n      const targetType = state.fanOuts[i].type;\n      if (targetType === 'UFO' && fo.type === 'FO') {\n        fo.convertToUFO();\n      }\n    }\n\n    for (let i = 0; i < this.fanIns.length; i++) {\n      const fi = this.fanIns[i];\n      const targetType = state.fanIns[i].type;\n      if (targetType === 'UFI' && fi.type === 'FI') {\n        fi.convertToUFI();\n      }\n    }\n  }\n\n  /**\n   * Main planning algorithm using exhaustive join flip enumeration.\n   *\n   * Enumerates all possible flip patterns for flippable joins (2^n for n flippable joins).\n   * Each pattern represents a different query execution plan. We evaluate the cost of each\n   * plan and select the one with the lowest cost.\n   *\n   * Connections are used only for cost estimation - the flip patterns determine the plan.\n   * FanOut/FanIn states (FO/UFO and FI/UFI) are automatically derived from join flip states.\n   *\n   * @param planDebugger - Optional debugger to receive structured events during planning\n   * @param lc - Optional logger for warnings\n   */\n  plan(planDebugger?: PlanDebugger, lc?: LogContext): void {\n    // Get all flippable joins\n    const flippableJoins = this.joins.filter(j => j.isFlippable());\n\n    // Too many flippable joins - skip optimization and run as-is\n    if (flippableJoins.length > MAX_FLIPPABLE_JOINS) {\n      lc?.warn?.(\n        `Query has ${flippableJoins.length} EXISTS checks which would require ` +\n          `${2 ** flippableJoins.length} plan evaluations. Skipping optimization.`,\n      );\n      return;\n    }\n\n    // Build FO→FI cache once to avoid redundant BFS traversals in each iteration\n    const fofiCache = buildFOFICache(this);\n\n    const numPatterns =\n      flippableJoins.length === 0 ? 0 : 2 ** flippableJoins.length;\n    let bestCost = Infinity;\n    let bestPlan: PlanState | undefined = undefined;\n    let bestAttemptNumber = -1;\n\n    // Enumerate all flip patterns\n    for (let pattern = 0; pattern < numPatterns; pattern++) {\n      // Reset to initial state\n      this.resetPlanningState();\n\n      if (planDebugger) {\n        planDebugger.log({\n          type: 'attempt-start',\n          attemptNumber: pattern,\n          totalAttempts: numPatterns,\n        });\n      }\n\n      // Apply flip pattern (treat pattern as bitmask)\n      // Bit i set to 1 means flip join i\n      for (let i = 0; i < flippableJoins.length; i++) {\n        if (pattern & (1 << i)) {\n          flippableJoins[i].flip();\n        }\n      }\n\n      // Derive FO/UFO and FI/UFI states from join flip states\n      checkAndConvertFOFI(fofiCache);\n\n      // Propagate unlimiting for flipped joins\n      propagateUnlimitForFlippedJoins(this);\n\n      // Propagate constraints through the graph\n      this.propagateConstraints(planDebugger);\n\n      if (planDebugger) {\n        planDebugger.log({\n          type: 'constraints-propagated',\n          attemptNumber: pattern,\n          connectionConstraints: this.connections.map(c => {\n            const constraintCosts = c.getConstraintCostsForDebug();\n            const constraintCostsWithoutFanout: Record<\n              string,\n              Omit<(typeof constraintCosts)[string], 'fanout'>\n            > = {};\n            for (const [key, cost] of Object.entries(constraintCosts)) {\n              constraintCostsWithoutFanout[key] = omitFanout(cost);\n            }\n            return {\n              connection: c.name,\n              constraints: c.getConstraintsForDebug(),\n              constraintCosts: constraintCostsWithoutFanout,\n            };\n          }),\n        });\n      }\n\n      // Evaluate this plan\n      const totalCost = this.getTotalCost(planDebugger);\n\n      if (planDebugger) {\n        planDebugger.log({\n          type: 'plan-complete',\n          attemptNumber: pattern,\n          totalCost,\n          flipPattern: pattern, // Bitmask of which joins are flipped\n          planSnapshot: this.capturePlanningSnapshot(),\n          joinStates: this.joins.map(j => {\n            const info = j.getDebugInfo();\n            return {\n              join: info.name,\n              type: info.type,\n            };\n          }),\n        });\n      }\n\n      // Track best plan\n      if (totalCost < bestCost) {\n        bestCost = totalCost;\n        bestPlan = this.capturePlanningSnapshot();\n        bestAttemptNumber = pattern;\n      }\n    }\n\n    // Restore best plan\n    if (bestPlan) {\n      this.restorePlanningSnapshot(bestPlan);\n      // Propagate constraints to ensure all derived state is consistent\n      this.propagateConstraints(planDebugger);\n\n      if (planDebugger) {\n        planDebugger.log({\n          type: 'best-plan-selected',\n          bestAttemptNumber,\n          totalCost: bestCost,\n          flipPattern: bestAttemptNumber, // The best attempt number is also the flip pattern\n          joinStates: this.joins.map(j => ({\n            join: j.getName(),\n            type: j.type,\n          })),\n        });\n      }\n    } else {\n      assert(\n        numPatterns === 0,\n        'no plan was found but flippable joins did exist!',\n      );\n    }\n  }\n}\n\n/**\n * Build cache of FO→FI relationships and joins between them.\n * Called once at the start of planning to avoid redundant BFS traversals.\n */\nfunction buildFOFICache(graph: PlannerGraph): Map<PlannerFanOut, FOFIInfo> {\n  const cache = new Map<PlannerFanOut, FOFIInfo>();\n\n  for (const fo of graph.fanOuts) {\n    const info = findFIAndJoins(fo);\n    cache.set(fo, info);\n  }\n\n  return cache;\n}\n\n/**\n * Check if any joins downstream of a FanOut (before reaching FanIn) are flipped.\n * If so, convert the FO to UFO and the FI to UFI.\n *\n * This must be called after join flipping and before propagateConstraints.\n */\nfunction checkAndConvertFOFI(fofiCache: Map<PlannerFanOut, FOFIInfo>): void {\n  for (const [fo, info] of fofiCache) {\n    const hasFlippedJoin = info.joinsBetween.some(j => j.type === 'flipped');\n    if (info.fi && hasFlippedJoin) {\n      fo.convertToUFO();\n      info.fi.convertToUFI();\n    }\n  }\n}\n\n/**\n * Traverse from a FanOut through its outputs to find the corresponding FanIn\n * and collect all joins along the way.\n */\nfunction findFIAndJoins(fo: PlannerFanOut): FOFIInfo {\n  const joinsBetween: PlannerJoin[] = [];\n  let fi: PlannerFanIn | undefined = undefined;\n\n  // BFS through FO outputs to find FI and collect joins\n  const queue: PlannerNode[] = [...fo.outputs];\n  const visited = new Set<PlannerNode>();\n\n  while (queue.length > 0) {\n    const node = must(queue.shift());\n    if (visited.has(node)) continue;\n    visited.add(node);\n\n    switch (node.kind) {\n      case 'join':\n        joinsBetween.push(node);\n        queue.push(node.output);\n        break;\n      case 'fan-out':\n        // Nested FO - traverse its outputs\n        queue.push(...node.outputs);\n        break;\n      case 'fan-in':\n        // Found the FI - this is the boundary, don't traverse further\n        fi = node;\n        break;\n      case 'connection':\n        // Shouldn't happen in a well-formed graph\n        break;\n      case 'terminus':\n        // Reached the end without finding FI\n        break;\n    }\n  }\n\n  return {fi, joinsBetween};\n}\n\n/**\n * Propagate unlimiting to all flipped joins in the graph.\n * When a join is flipped, its child becomes the outer loop and should no longer\n * be limited by EXISTS semantics.\n *\n * This must be called after join flipping and before propagateConstraints.\n */\nfunction propagateUnlimitForFlippedJoins(graph: PlannerGraph): void {\n  for (const join of graph.joins) {\n    if (join.type === 'flipped') {\n      join.propagateUnlimit();\n    }\n  }\n}\n"],"mappings":"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"}

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

@@ -1,246 +1,261 @@
 import { assert } from "../../../shared/src/asserts.js";
-import { mergeConstraints } from "./planner-constraint.js";
 import { omitFanout } from "./planner-node.js";
+import { mergeConstraints } from "./planner-constraint.js";
+//#region ../zql/src/planner/planner-join.ts
+/**
+* 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 void 0;
-  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) {
-      translated[childKeys[index]] = value;
-    }
-  }
-  return Object.keys(translated).length > 0 ? translated : void 0;
-}
-class PlannerJoin {
-  kind = "join";
-  #parent;
-  #child;
-  #parentConstraint;
-  #childConstraint;
-  #flippable;
-  planId;
-  #output;
-  // Set once during graph construction
-  // Reset between planning attempts
-  #type;
-  #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;
-    this.#parentConstraint = parentConstraint;
-    this.#flippable = flippable;
-    this.planId = planId;
-  }
-  setOutput(node) {
-    this.#output = node;
-  }
-  get output() {
-    assert(this.#output !== void 0, "Output not set");
-    return this.#output;
-  }
-  closestJoinOrSource() {
-    return "join";
-  }
-  flipIfNeeded(input) {
-    if (input === this.#child) {
-      this.flip();
-    } else {
-      assert(
-        input === this.#parent,
-        "Can only flip a join from one of its inputs"
-      );
-    }
-  }
-  flip() {
-    assert(this.#type === "semi", "Can only flip a semi-join");
-    if (!this.#flippable) {
-      throw new UnflippableJoinError(
-        "Cannot flip a non-flippable join (e.g., NOT EXISTS)"
-      );
-    }
-    this.#type = "flipped";
-  }
-  get type() {
-    return this.#type;
-  }
-  isFlippable() {
-    return this.#flippable;
-  }
-  /**
-   * 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()
-   * - 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() {
-    assert(this.#type === "flipped", "Can only unlimit a flipped join");
-    this.#child.propagateUnlimitFromFlippedJoin();
-  }
-  /**
-   * Called when a parent join is flipped and this join is part of its child subgraph.
-   * Continue propagation to parent (the outer loop).
-   * If we are hitting a semi-join, the parent drives.
-   * If we are hitting a flip-join, well now we have to unlimit its parent too!
-   */
-  propagateUnlimitFromFlippedJoin() {
-    this.#parent.propagateUnlimitFromFlippedJoin();
-  }
-  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") {
-      this.#child.propagateConstraints(
-        branchPattern,
-        this.#childConstraint,
-        this,
-        planDebugger
-      );
-      this.#parent.propagateConstraints(
-        branchPattern,
-        constraint,
-        this,
-        planDebugger
-      );
-    } else if (this.#type === "flipped") {
-      const translatedConstraint = translateConstraintsForFlippedJoin(
-        constraint,
-        this.#parentConstraint,
-        this.#childConstraint
-      );
-      this.#child.propagateConstraints(
-        branchPattern,
-        translatedConstraint,
-        this,
-        planDebugger
-      );
-      this.#parent.propagateConstraints(
-        branchPattern,
-        mergeConstraints(constraint, this.#parentConstraint),
-        this,
-        planDebugger
-      );
-    }
-  }
-  reset() {
-    this.#type = this.#initialType;
-  }
-  estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
-    const child = this.#child.estimateCost(1, branchPattern, planDebugger);
-    const fanoutFactor = child.fanout(Object.keys(this.#childConstraint));
-    const scaledChildSelectivity = 1 - Math.pow(1 - child.selectivity, fanoutFactor.fanout);
-    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.
-      this.#type === "flipped" ? 1 * downstreamChildSelectivity : scaledChildSelectivity * downstreamChildSelectivity,
-      branchPattern,
-      planDebugger
-    );
-    let costEstimate;
-    if (this.type === "semi") {
-      costEstimate = {
-        startupCost: parent.startupCost,
-        scanEst: parent.limit === void 0 ? parent.returnedRows : Math.min(
-          parent.returnedRows,
-          downstreamChildSelectivity === 0 ? 0 : 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,
-        fanout: parent.fanout
-      };
-    } else {
-      costEstimate = {
-        startupCost: child.startupCost,
-        scanEst: parent.limit === void 0 ? parent.returnedRows * child.returnedRows : Math.min(
-          parent.returnedRows * child.returnedRows,
-          downstreamChildSelectivity === 0 ? 0 : parent.limit / downstreamChildSelectivity
-        ),
-        cost: child.cost + child.scanEst * (parent.startupCost + parent.cost + parent.scanEst),
-        // the child selectivity is not relevant here because it has already been taken into account via the flipping.
-        // I.e., `child.returnedRows` is the estimated number of rows produced by the child _after_ taking filtering into account.
-        returnedRows: parent.returnedRows * child.returnedRows,
-        selectivity: parent.selectivity * child.selectivity,
-        limit: parent.limit,
-        fanout: parent.fanout
-      };
-    }
-    if (planDebugger) {
-      planDebugger.log({
-        type: "node-cost",
-        nodeType: "join",
-        node: this.getName(),
-        branchPattern,
-        downstreamChildSelectivity,
-        costEstimate: omitFanout(costEstimate),
-        joinType: this.#type
-      });
-    }
-    return costEstimate;
-  }
-  /**
-   * Get a human-readable name for this join for debugging.
-   * Format: "parentName ⋈ childName"
-   */
-  getName() {
-    const parentName = getNodeName(this.#parent);
-    const childName = getNodeName(this.#child);
-    return `${parentName} ⋈ ${childName}`;
-  }
-  /**
-   * Get debug information about this join's state.
-   */
-  getDebugInfo() {
-    return {
-      name: this.getName(),
-      type: this.#type,
-      planId: this.planId
-    };
-  }
-}
-class UnflippableJoinError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "UnflippableJoinError";
-  }
+	if (!incomingConstraint) return void 0;
+	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) translated[childKeys[index]] = value;
+	}
+	return Object.keys(translated).length > 0 ? translated : void 0;
 }
+/**
+* Semi-join overhead multiplier.
+*
+* Semi-joins represent correlated subqueries (EXISTS checks) which have
+* execution overhead compared to flipped joins, even when logical row counts
+* are identical. This overhead comes from:
+* - Need to execute a separate correlation check for each parent row
+* - Cannot leverage combined constraint checking as effectively as flipped joins
+*
+* A multiplier of 1.5 means semi-joins are estimated to be ~50% more expensive
+* than equivalent flipped joins, which empirically matches observed performance
+* differences in production workloads (e.g., 1.7x in zbugs benchmarks).
+*
+* Flipped joins have a different overhead in that they become unlimited. This
+* is accounted for when propagating unlimits rather than here.
+*/
+/**
+* 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)
+*/
+var PlannerJoin = class {
+	kind = "join";
+	#parent;
+	#child;
+	#parentConstraint;
+	#childConstraint;
+	#flippable;
+	planId;
+	#output;
+	#type;
+	#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;
+		this.#parentConstraint = parentConstraint;
+		this.#flippable = flippable;
+		this.planId = planId;
+	}
+	setOutput(node) {
+		this.#output = node;
+	}
+	get output() {
+		assert(this.#output !== void 0, "Output not set");
+		return this.#output;
+	}
+	closestJoinOrSource() {
+		return "join";
+	}
+	flipIfNeeded(input) {
+		if (input === this.#child) this.flip();
+		else assert(input === this.#parent, "Can only flip a join from one of its inputs");
+	}
+	flip() {
+		assert(this.#type === "semi", "Can only flip a semi-join");
+		if (!this.#flippable) throw new UnflippableJoinError("Cannot flip a non-flippable join (e.g., NOT EXISTS)");
+		this.#type = "flipped";
+	}
+	get type() {
+		return this.#type;
+	}
+	isFlippable() {
+		return this.#flippable;
+	}
+	/**
+	* 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()
+	* - 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() {
+		assert(this.#type === "flipped", "Can only unlimit a flipped join");
+		this.#child.propagateUnlimitFromFlippedJoin();
+	}
+	/**
+	* Called when a parent join is flipped and this join is part of its child subgraph.
+	* Continue propagation to parent (the outer loop).
+	* If we are hitting a semi-join, the parent drives.
+	* If we are hitting a flip-join, well now we have to unlimit its parent too!
+	*/
+	propagateUnlimitFromFlippedJoin() {
+		this.#parent.propagateUnlimitFromFlippedJoin();
+	}
+	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") {
+			this.#child.propagateConstraints(branchPattern, this.#childConstraint, this, planDebugger);
+			this.#parent.propagateConstraints(branchPattern, constraint, this, planDebugger);
+		} else if (this.#type === "flipped") {
+			const translatedConstraint = translateConstraintsForFlippedJoin(constraint, this.#parentConstraint, this.#childConstraint);
+			this.#child.propagateConstraints(branchPattern, translatedConstraint, this, planDebugger);
+			this.#parent.propagateConstraints(branchPattern, mergeConstraints(constraint, this.#parentConstraint), this, planDebugger);
+		}
+	}
+	reset() {
+		this.#type = this.#initialType;
+	}
+	estimateCost(downstreamChildSelectivity, 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);
+		const fanoutFactor = child.fanout(Object.keys(this.#childConstraint));
+		const scaledChildSelectivity = 1 - Math.pow(1 - child.selectivity, fanoutFactor.fanout);
+		/**
+		* 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(this.#type === "flipped" ? 1 * downstreamChildSelectivity : scaledChildSelectivity * downstreamChildSelectivity, branchPattern, planDebugger);
+		let costEstimate;
+		if (this.type === "semi") costEstimate = {
+			startupCost: parent.startupCost,
+			scanEst: parent.limit === void 0 ? parent.returnedRows : Math.min(parent.returnedRows, downstreamChildSelectivity === 0 ? 0 : 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,
+			fanout: parent.fanout
+		};
+		else costEstimate = {
+			startupCost: child.startupCost,
+			scanEst: parent.limit === void 0 ? parent.returnedRows * child.returnedRows : Math.min(parent.returnedRows * child.returnedRows, downstreamChildSelectivity === 0 ? 0 : parent.limit / downstreamChildSelectivity),
+			cost: child.cost + child.scanEst * (parent.startupCost + parent.cost + parent.scanEst),
+			returnedRows: parent.returnedRows * child.returnedRows,
+			selectivity: parent.selectivity * child.selectivity,
+			limit: parent.limit,
+			fanout: parent.fanout
+		};
+		if (planDebugger) planDebugger.log({
+			type: "node-cost",
+			nodeType: "join",
+			node: this.getName(),
+			branchPattern,
+			downstreamChildSelectivity,
+			costEstimate: omitFanout(costEstimate),
+			joinType: this.#type
+		});
+		return costEstimate;
+	}
+	/**
+	* Get a human-readable name for this join for debugging.
+	* Format: "parentName ⋈ childName"
+	*/
+	getName() {
+		return `${getNodeName(this.#parent)} ⋈ ${getNodeName(this.#child)}`;
+	}
+	/**
+	* Get debug information about this join's state.
+	*/
+	getDebugInfo() {
+		return {
+			name: this.getName(),
+			type: this.#type,
+			planId: this.planId
+		};
+	}
+};
+var UnflippableJoinError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "UnflippableJoinError";
+	}
+};
+/**
+* Get a human-readable name for any planner node.
+* Used for debugging and tracing.
+*/
 function getNodeName(node) {
-  switch (node.kind) {
-    case "connection":
-      return node.name;
-    case "join":
-      return node.getName();
-    case "fan-out":
-      return "FO";
-    case "fan-in":
-      return "FI";
-    case "terminus":
-      return "terminus";
-  }
+	switch (node.kind) {
+		case "connection": return node.name;
+		case "join": return node.getName();
+		case "fan-out": return "FO";
+		case "fan-in": return "FI";
+		case "terminus": return "terminus";
+	}
 }
-export {
-  PlannerJoin,
-  UnflippableJoinError
-};
-//# sourceMappingURL=planner-join.js.map
+//#endregion
+export { PlannerJoin };
+
+//# sourceMappingURL=planner-join.js.map