@rocicorp/zero 0.26.1 → 0.26.2-canary.4

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

@@ -1 +1 @@
-{"version":3,"file":"planner-join.js","sources":["../../../../../zql/src/planner/planner-join.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.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';\nimport type {PlannerTerminus} from './planner-terminus.ts';\n\n/**\n * Translate constraints for a flipped join from parent space to child space.\n * Matches the runtime behavior of FlippedJoin.fetch() which translates\n * parent constraints to child constraints using index-based key mapping.\n *\n * Example:\n *   parentConstraint = {issueID: undefined, projectID: undefined}\n *   childConstraint = {id: undefined, projectID: undefined}\n *   incomingConstraint = {issueID: 5}\n *   result = {id: 5}  // issueID at index 0 maps to id at index 0\n */\nfunction translateConstraintsForFlippedJoin(\n  incomingConstraint: PlannerConstraint | undefined,\n  parentConstraint: PlannerConstraint,\n  childConstraint: PlannerConstraint,\n): PlannerConstraint | undefined {\n  if (!incomingConstraint) return undefined;\n\n  const parentKeys = Object.keys(parentConstraint);\n  const childKeys = Object.keys(childConstraint);\n  const translated: PlannerConstraint = {};\n\n  for (const [key, value] of Object.entries(incomingConstraint)) {\n    const index = parentKeys.indexOf(key);\n    if (index !== -1) {\n      // Found this key in parent at position `index`\n      // Map to child key at same position\n      translated[childKeys[index]] = value;\n    }\n  }\n\n  return Object.keys(translated).length > 0 ? translated : undefined;\n}\n\n/**\n * Semi-join overhead multiplier.\n *\n * Semi-joins represent correlated subqueries (EXISTS checks) which have\n * execution overhead compared to flipped joins, even when logical row counts\n * are identical. This overhead comes from:\n * - Need to execute a separate correlation check for each parent row\n * - Cannot leverage combined constraint checking as effectively as flipped joins\n *\n * A multiplier of 1.5 means semi-joins are estimated to be ~50% more expensive\n * than equivalent flipped joins, which empirically matches observed performance\n * differences in production workloads (e.g., 1.7x in zbugs benchmarks).\n *\n * Flipped joins have a different overhead in that they become unlimited. This\n * is accounted for when propagating unlimits rather than here.\n */\n// const SEMI_JOIN_OVERHEAD_MULTIPLIER = 1.5;\n\n/**\n * Represents a join between two data streams (parent and child).\n *\n * # Dual-State Pattern\n * Like all planner nodes, PlannerJoin separates:\n * 1. IMMUTABLE STRUCTURE: Parent/child nodes, constraints, flippability\n * 2. MUTABLE STATE: Join type (semi/flipped), pinned status\n *\n * # Join Flipping\n * A join can be in two states:\n * - 'semi': Parent is outer loop, child is inner (semi-join for EXISTS)\n * - 'flipped': Child is outer loop, parent is inner\n *\n * Flipping is the key optimization: choosing which table scans first.\n * NOT EXISTS joins cannot be flipped (#flippable = false).\n *\n * # Constraint Propagation\n * - Semi-join: Sends childConstraint to child, forwards received constraints to parent\n * - Flipped join: Sends undefined to child, merges parentConstraint with received to parent\n * - Unpinned join: Only forwards constraints to parent (doesn't constrain child yet)\n *\n * # Lifecycle\n * 1. Construct with immutable structure (parent, child, constraints, flippability)\n * 2. Wire to output node during graph construction\n * 3. Planning calls flipIfNeeded() based on connection selection order\n * 4. pin() locks the join type once chosen\n * 5. reset() clears mutable state (type → 'semi', pinned → false)\n */\nexport class PlannerJoin {\n  readonly kind = 'join' as const;\n\n  readonly #parent: Exclude<PlannerNode, PlannerTerminus>;\n  readonly #child: Exclude<PlannerNode, PlannerTerminus>;\n  readonly #parentConstraint: PlannerConstraint;\n  readonly #childConstraint: PlannerConstraint;\n  readonly #flippable: boolean;\n  readonly planId: number;\n  #output?: PlannerNode | undefined; // Set once during graph construction\n\n  // Reset between planning attempts\n  #type: 'semi' | 'flipped';\n  readonly #initialType: 'semi' | 'flipped';\n\n  constructor(\n    parent: Exclude<PlannerNode, PlannerTerminus>,\n    child: Exclude<PlannerNode, PlannerTerminus>,\n    parentConstraint: PlannerConstraint,\n    childConstraint: PlannerConstraint,\n    flippable: boolean,\n    planId: number,\n    initialType: 'semi' | 'flipped' = 'semi',\n  ) {\n    this.#type = initialType;\n    this.#initialType = initialType;\n    this.#parent = parent;\n    this.#child = child;\n    this.#childConstraint = childConstraint;\n    this.#parentConstraint = parentConstraint;\n    this.#flippable = flippable;\n    this.planId = planId;\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 'join';\n  }\n\n  flipIfNeeded(input: PlannerNode): void {\n    if (input === this.#child) {\n      this.flip();\n    } else {\n      assert(\n        input === this.#parent,\n        'Can only flip a join from one of its inputs',\n      );\n    }\n  }\n\n  flip(): void {\n    assert(this.#type === 'semi', 'Can only flip a semi-join');\n    if (!this.#flippable) {\n      throw new UnflippableJoinError(\n        'Cannot flip a non-flippable join (e.g., NOT EXISTS)',\n      );\n    }\n    this.#type = 'flipped';\n  }\n\n  get type(): 'semi' | 'flipped' {\n    return this.#type;\n  }\n  isFlippable(): boolean {\n    return this.#flippable;\n  }\n\n  /**\n   * Propagate unlimiting when this join is flipped.\n   * When a join is flipped:\n   * 1. Child becomes outer loop → produces all rows (unlimited)\n   * 2. Parent is fetched once per child row → effectively unlimited\n   *\n   * Example: If child produces 896 rows, parent is fetched 896 times.\n   * Even if each fetch returns 1 row, parent produces 896 total rows.\n   *\n   * Propagation rules:\n   * - Connection: call unlimit()\n   * - Semi-join: continue to parent (outer loop)\n   * - Flipped join: stop (already unlimited when it was flipped)\n   * - Fan-out/Fan-in: propagate to all inputs\n   */\n  propagateUnlimit(): void {\n    assert(this.#type === 'flipped', 'Can only unlimit a flipped join');\n    // Parent stays limited; child becomes unlimited\n    this.#child.propagateUnlimitFromFlippedJoin(); // Up the child chain\n  }\n\n  /**\n   * Called when a parent join is flipped and this join is part of its child subgraph.\n   * Continue propagation to parent (the outer loop).\n   * If we are hitting a semi-join, the parent drives.\n   * If we are hitting a flip-join, well now we have to unlimit its parent too!\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    this.#parent.propagateUnlimitFromFlippedJoin();\n  }\n\n  propagateConstraints(\n    branchPattern: number[],\n    constraint: PlannerConstraint | undefined,\n    from?: PlannerNode,\n    planDebugger?: PlanDebugger,\n  ): void {\n    planDebugger?.log({\n      type: 'node-constraint',\n      nodeType: 'join',\n      node: this.getName(),\n      branchPattern,\n      constraint,\n      from: from ? getNodeName(from) : 'unknown',\n    });\n\n    if (this.#type === 'semi') {\n      // A semi-join always has constraints for its child.\n      // They are defined by the correlation between parent and child.\n      this.#child.propagateConstraints(\n        branchPattern,\n        this.#childConstraint,\n        this,\n        planDebugger,\n      );\n      // A semi-join forwards constraints to its parent.\n      this.#parent.propagateConstraints(\n        branchPattern,\n        constraint,\n        this,\n        planDebugger,\n      );\n    } else if (this.#type === 'flipped') {\n      // A flipped join translates constraints from parent space to child space.\n      // This matches FlippedJoin.fetch() runtime behavior where parent constraints\n      // on join keys are translated to child constraints.\n      // Example: If parent has {issueID: 5} and join maps issueID→id,\n      // child gets {id: 5} allowing index usage.\n      const translatedConstraint = translateConstraintsForFlippedJoin(\n        constraint,\n        this.#parentConstraint,\n        this.#childConstraint,\n      );\n      this.#child.propagateConstraints(\n        branchPattern,\n        translatedConstraint,\n        this,\n        planDebugger,\n      );\n      // A flipped join will have constraints to send to its parent.\n      // - The constraints its output sent\n      // - The constraints its child creates\n      this.#parent.propagateConstraints(\n        branchPattern,\n        mergeConstraints(constraint, this.#parentConstraint),\n        this,\n        planDebugger,\n      );\n    }\n  }\n\n  reset(): void {\n    this.#type = this.#initialType;\n  }\n\n  estimateCost(\n    /**\n     * This argument is to deal with consecutive `andExists` statements.\n     * Each one will constrain how often a parent row passes all constraints.\n     * This means that we have to scan more and more parent rows the more\n     * constraints we add.\n     *\n     * DownstreamChildSelectivity factors in fanout factor\n     * from parent -> child\n     */\n    downstreamChildSelectivity: number,\n    /**\n     * branchPattern uniquely identifies OR branches in the graph.\n     * Each path through an OR will have unique constraints to apply to the source\n     * connection.\n     * branchPattern allows us to correlate a path through the graph\n     * to the constraints that should be applied for that path.\n     *\n     * Example graph:\n     *  UFO\n     * /  \\\n     * J1   J2\n     * \\  /\n     *  UFI\n     *\n     * J1 and J2 are joins inside an OR (FO).\n     * branchPattern [0] = path through J1\n     * branchPattern [1] = path through J2\n     *\n     * If many ORs are nested, branchPattern will have multiple elements\n     * representing each level of OR.\n     *\n     * If no joins are flipped within the `OR`, then only a single\n     * branchPattern element will be needed, as FO represents all sub-joins\n     * as a single path.\n     */\n    branchPattern: number[],\n    planDebugger?: PlanDebugger,\n  ): CostEstimate {\n    /**\n     * downstreamChildSelectivity accumulates up a parent chain, not\n     * up child chains. Child chains represent independent sub-graphs.\n     * So we pass 1 for `downstreamChildSelectivity` when estimating child cost.\n     * Put another way, downstreamChildSelectivity impacts how many parent\n     * rows are returned.\n     */\n    const child = this.#child.estimateCost(1, branchPattern, planDebugger);\n\n    const fanoutFactor = child.fanout(Object.keys(this.#childConstraint));\n    // Factor in how many child rows match a parent row.\n    // E.g., if an issue has 10 comments on average then we're more\n    // likely to hit a comment compared to if an issue has 1 comment on average.\n    // If an index is all nulls (no parents match any children)\n    // this will collapse to 0.\n    const scaledChildSelectivity =\n      1 - Math.pow(1 - child.selectivity, fanoutFactor.fanout);\n\n    // Why do we not need fanout in the other direction?\n    // E.g., for an `inventory -> film` flipped-join, if each film has 100 inventories (100 copies)\n    // then we're more likely to hit an inventory row compared to if each film has 1 inventory.\n    // Flipped-join already accounts for this because the child selectivity is implicitly accounted\n    // for. The returned row estimate of the child is already representative of how many\n    // rows the child will have post-filtering.\n\n    /**\n     * How selective is the graph from this point forward?\n     * If we are _very_ selective then we must scan more parent rows\n     * before finding a match.\n     * E.g., if childSelectivity = 0.1 and downstreamChildSelectivity = 0.5\n     * then we only pass 5% of parent rows (0.1 * 0.5 = 0.05).\n     *\n     * This is used to estimate how many rows will be pulled from the parent\n     * when trying to satisfy downstream constraints and a limit.\n     *\n     * NOTE: We do not know if the probabilities are correlated so we assume independence.\n     * This is a fundamental limitation of the planner.\n     */\n    const parent = this.#parent.estimateCost(\n      // Selectivity flows up the graph from child to parent\n      // so we can determine the total selectivity of all ANDed exists checks.\n      this.#type === 'flipped'\n        ? 1 * downstreamChildSelectivity\n        : scaledChildSelectivity * downstreamChildSelectivity,\n      branchPattern,\n      planDebugger,\n    );\n\n    let costEstimate: CostEstimate;\n\n    if (this.type === 'semi') {\n      costEstimate = {\n        startupCost: parent.startupCost,\n        scanEst:\n          parent.limit === undefined\n            ? parent.returnedRows\n            : Math.min(\n                parent.returnedRows,\n                downstreamChildSelectivity === 0\n                  ? 0\n                  : parent.limit / downstreamChildSelectivity,\n              ),\n        cost:\n          parent.cost +\n          parent.scanEst * (child.startupCost + child.cost + child.scanEst),\n        returnedRows: parent.returnedRows * child.selectivity,\n        selectivity: child.selectivity * parent.selectivity,\n        limit: parent.limit,\n        fanout: parent.fanout,\n      };\n    } else {\n      costEstimate = {\n        startupCost: child.startupCost,\n        scanEst:\n          parent.limit === undefined\n            ? parent.returnedRows * child.returnedRows\n            : Math.min(\n                parent.returnedRows * child.returnedRows,\n                downstreamChildSelectivity === 0\n                  ? 0\n                  : parent.limit / downstreamChildSelectivity,\n              ),\n        cost:\n          child.cost +\n          child.scanEst * (parent.startupCost + parent.cost + parent.scanEst),\n        // the child selectivity is not relevant here because it has already been taken into account via the flipping.\n        // I.e., `child.returnedRows` is the estimated number of rows produced by the child _after_ taking filtering into account.\n        returnedRows: parent.returnedRows * child.returnedRows,\n        selectivity: parent.selectivity * child.selectivity,\n        limit: parent.limit,\n        fanout: parent.fanout,\n      };\n    }\n\n    if (planDebugger) {\n      planDebugger.log({\n        type: 'node-cost',\n        nodeType: 'join',\n        node: this.getName(),\n        branchPattern,\n        downstreamChildSelectivity,\n        costEstimate: omitFanout(costEstimate),\n        joinType: this.#type,\n      });\n    }\n\n    return costEstimate;\n  }\n\n  /**\n   * Get a human-readable name for this join for debugging.\n   * Format: \"parentName ⋈ childName\"\n   */\n  getName(): string {\n    const parentName = getNodeName(this.#parent);\n    const childName = getNodeName(this.#child);\n    return `${parentName} ⋈ ${childName}`;\n  }\n\n  /**\n   * Get debug information about this join's state.\n   */\n  getDebugInfo(): {\n    name: string;\n    type: 'semi' | 'flipped';\n    planId: number;\n  } {\n    return {\n      name: this.getName(),\n      type: this.#type,\n      planId: this.planId,\n    };\n  }\n}\n\nexport class UnflippableJoinError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'UnflippableJoinError';\n  }\n}\n\n/**\n * Get a human-readable name for any planner node.\n * Used for debugging and tracing.\n */\nfunction getNodeName(node: PlannerNode): string {\n  switch (node.kind) {\n    case 'connection':\n      return node.name;\n    case 'join':\n      return node.getName();\n    case 'fan-out':\n      return 'FO';\n    case 'fan-in':\n      return 'FI';\n    case 'terminus':\n      return 'terminus';\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"planner-join.js","names":["#parent","#child","#parentConstraint","#childConstraint","#flippable","#initialType","#type","#output"],"sources":["../../../../../zql/src/planner/planner-join.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.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';\nimport type {PlannerTerminus} from './planner-terminus.ts';\n\n/**\n * Translate constraints for a flipped join from parent space to child space.\n * Matches the runtime behavior of FlippedJoin.fetch() which translates\n * parent constraints to child constraints using index-based key mapping.\n *\n * Example:\n *   parentConstraint = {issueID: undefined, projectID: undefined}\n *   childConstraint = {id: undefined, projectID: undefined}\n *   incomingConstraint = {issueID: 5}\n *   result = {id: 5}  // issueID at index 0 maps to id at index 0\n */\nfunction translateConstraintsForFlippedJoin(\n  incomingConstraint: PlannerConstraint | undefined,\n  parentConstraint: PlannerConstraint,\n  childConstraint: PlannerConstraint,\n): PlannerConstraint | undefined {\n  if (!incomingConstraint) return undefined;\n\n  const parentKeys = Object.keys(parentConstraint);\n  const childKeys = Object.keys(childConstraint);\n  const translated: PlannerConstraint = {};\n\n  for (const [key, value] of Object.entries(incomingConstraint)) {\n    const index = parentKeys.indexOf(key);\n    if (index !== -1) {\n      // Found this key in parent at position `index`\n      // Map to child key at same position\n      translated[childKeys[index]] = value;\n    }\n  }\n\n  return Object.keys(translated).length > 0 ? translated : undefined;\n}\n\n/**\n * Semi-join overhead multiplier.\n *\n * Semi-joins represent correlated subqueries (EXISTS checks) which have\n * execution overhead compared to flipped joins, even when logical row counts\n * are identical. This overhead comes from:\n * - Need to execute a separate correlation check for each parent row\n * - Cannot leverage combined constraint checking as effectively as flipped joins\n *\n * A multiplier of 1.5 means semi-joins are estimated to be ~50% more expensive\n * than equivalent flipped joins, which empirically matches observed performance\n * differences in production workloads (e.g., 1.7x in zbugs benchmarks).\n *\n * Flipped joins have a different overhead in that they become unlimited. This\n * is accounted for when propagating unlimits rather than here.\n */\n// const SEMI_JOIN_OVERHEAD_MULTIPLIER = 1.5;\n\n/**\n * Represents a join between two data streams (parent and child).\n *\n * # Dual-State Pattern\n * Like all planner nodes, PlannerJoin separates:\n * 1. IMMUTABLE STRUCTURE: Parent/child nodes, constraints, flippability\n * 2. MUTABLE STATE: Join type (semi/flipped), pinned status\n *\n * # Join Flipping\n * A join can be in two states:\n * - 'semi': Parent is outer loop, child is inner (semi-join for EXISTS)\n * - 'flipped': Child is outer loop, parent is inner\n *\n * Flipping is the key optimization: choosing which table scans first.\n * NOT EXISTS joins cannot be flipped (#flippable = false).\n *\n * # Constraint Propagation\n * - Semi-join: Sends childConstraint to child, forwards received constraints to parent\n * - Flipped join: Sends undefined to child, merges parentConstraint with received to parent\n * - Unpinned join: Only forwards constraints to parent (doesn't constrain child yet)\n *\n * # Lifecycle\n * 1. Construct with immutable structure (parent, child, constraints, flippability)\n * 2. Wire to output node during graph construction\n * 3. Planning calls flipIfNeeded() based on connection selection order\n * 4. pin() locks the join type once chosen\n * 5. reset() clears mutable state (type → 'semi', pinned → false)\n */\nexport class PlannerJoin {\n  readonly kind = 'join' as const;\n\n  readonly #parent: Exclude<PlannerNode, PlannerTerminus>;\n  readonly #child: Exclude<PlannerNode, PlannerTerminus>;\n  readonly #parentConstraint: PlannerConstraint;\n  readonly #childConstraint: PlannerConstraint;\n  readonly #flippable: boolean;\n  readonly planId: number;\n  #output?: PlannerNode | undefined; // Set once during graph construction\n\n  // Reset between planning attempts\n  #type: 'semi' | 'flipped';\n  readonly #initialType: 'semi' | 'flipped';\n\n  constructor(\n    parent: Exclude<PlannerNode, PlannerTerminus>,\n    child: Exclude<PlannerNode, PlannerTerminus>,\n    parentConstraint: PlannerConstraint,\n    childConstraint: PlannerConstraint,\n    flippable: boolean,\n    planId: number,\n    initialType: 'semi' | 'flipped' = 'semi',\n  ) {\n    this.#type = initialType;\n    this.#initialType = initialType;\n    this.#parent = parent;\n    this.#child = child;\n    this.#childConstraint = childConstraint;\n    this.#parentConstraint = parentConstraint;\n    this.#flippable = flippable;\n    this.planId = planId;\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 'join';\n  }\n\n  flipIfNeeded(input: PlannerNode): void {\n    if (input === this.#child) {\n      this.flip();\n    } else {\n      assert(\n        input === this.#parent,\n        'Can only flip a join from one of its inputs',\n      );\n    }\n  }\n\n  flip(): void {\n    assert(this.#type === 'semi', 'Can only flip a semi-join');\n    if (!this.#flippable) {\n      throw new UnflippableJoinError(\n        'Cannot flip a non-flippable join (e.g., NOT EXISTS)',\n      );\n    }\n    this.#type = 'flipped';\n  }\n\n  get type(): 'semi' | 'flipped' {\n    return this.#type;\n  }\n  isFlippable(): boolean {\n    return this.#flippable;\n  }\n\n  /**\n   * Propagate unlimiting when this join is flipped.\n   * When a join is flipped:\n   * 1. Child becomes outer loop → produces all rows (unlimited)\n   * 2. Parent is fetched once per child row → effectively unlimited\n   *\n   * Example: If child produces 896 rows, parent is fetched 896 times.\n   * Even if each fetch returns 1 row, parent produces 896 total rows.\n   *\n   * Propagation rules:\n   * - Connection: call unlimit()\n   * - Semi-join: continue to parent (outer loop)\n   * - Flipped join: stop (already unlimited when it was flipped)\n   * - Fan-out/Fan-in: propagate to all inputs\n   */\n  propagateUnlimit(): void {\n    assert(this.#type === 'flipped', 'Can only unlimit a flipped join');\n    // Parent stays limited; child becomes unlimited\n    this.#child.propagateUnlimitFromFlippedJoin(); // Up the child chain\n  }\n\n  /**\n   * Called when a parent join is flipped and this join is part of its child subgraph.\n   * Continue propagation to parent (the outer loop).\n   * If we are hitting a semi-join, the parent drives.\n   * If we are hitting a flip-join, well now we have to unlimit its parent too!\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    this.#parent.propagateUnlimitFromFlippedJoin();\n  }\n\n  propagateConstraints(\n    branchPattern: number[],\n    constraint: PlannerConstraint | undefined,\n    from?: PlannerNode,\n    planDebugger?: PlanDebugger,\n  ): void {\n    planDebugger?.log({\n      type: 'node-constraint',\n      nodeType: 'join',\n      node: this.getName(),\n      branchPattern,\n      constraint,\n      from: from ? getNodeName(from) : 'unknown',\n    });\n\n    if (this.#type === 'semi') {\n      // A semi-join always has constraints for its child.\n      // They are defined by the correlation between parent and child.\n      this.#child.propagateConstraints(\n        branchPattern,\n        this.#childConstraint,\n        this,\n        planDebugger,\n      );\n      // A semi-join forwards constraints to its parent.\n      this.#parent.propagateConstraints(\n        branchPattern,\n        constraint,\n        this,\n        planDebugger,\n      );\n    } else if (this.#type === 'flipped') {\n      // A flipped join translates constraints from parent space to child space.\n      // This matches FlippedJoin.fetch() runtime behavior where parent constraints\n      // on join keys are translated to child constraints.\n      // Example: If parent has {issueID: 5} and join maps issueID→id,\n      // child gets {id: 5} allowing index usage.\n      const translatedConstraint = translateConstraintsForFlippedJoin(\n        constraint,\n        this.#parentConstraint,\n        this.#childConstraint,\n      );\n      this.#child.propagateConstraints(\n        branchPattern,\n        translatedConstraint,\n        this,\n        planDebugger,\n      );\n      // A flipped join will have constraints to send to its parent.\n      // - The constraints its output sent\n      // - The constraints its child creates\n      this.#parent.propagateConstraints(\n        branchPattern,\n        mergeConstraints(constraint, this.#parentConstraint),\n        this,\n        planDebugger,\n      );\n    }\n  }\n\n  reset(): void {\n    this.#type = this.#initialType;\n  }\n\n  estimateCost(\n    /**\n     * This argument is to deal with consecutive `andExists` statements.\n     * Each one will constrain how often a parent row passes all constraints.\n     * This means that we have to scan more and more parent rows the more\n     * constraints we add.\n     *\n     * DownstreamChildSelectivity factors in fanout factor\n     * from parent -> child\n     */\n    downstreamChildSelectivity: number,\n    /**\n     * branchPattern uniquely identifies OR branches in the graph.\n     * Each path through an OR will have unique constraints to apply to the source\n     * connection.\n     * branchPattern allows us to correlate a path through the graph\n     * to the constraints that should be applied for that path.\n     *\n     * Example graph:\n     *  UFO\n     * /  \\\n     * J1   J2\n     * \\  /\n     *  UFI\n     *\n     * J1 and J2 are joins inside an OR (FO).\n     * branchPattern [0] = path through J1\n     * branchPattern [1] = path through J2\n     *\n     * If many ORs are nested, branchPattern will have multiple elements\n     * representing each level of OR.\n     *\n     * If no joins are flipped within the `OR`, then only a single\n     * branchPattern element will be needed, as FO represents all sub-joins\n     * as a single path.\n     */\n    branchPattern: number[],\n    planDebugger?: PlanDebugger,\n  ): CostEstimate {\n    /**\n     * downstreamChildSelectivity accumulates up a parent chain, not\n     * up child chains. Child chains represent independent sub-graphs.\n     * So we pass 1 for `downstreamChildSelectivity` when estimating child cost.\n     * Put another way, downstreamChildSelectivity impacts how many parent\n     * rows are returned.\n     */\n    const child = this.#child.estimateCost(1, branchPattern, planDebugger);\n\n    const fanoutFactor = child.fanout(Object.keys(this.#childConstraint));\n    // Factor in how many child rows match a parent row.\n    // E.g., if an issue has 10 comments on average then we're more\n    // likely to hit a comment compared to if an issue has 1 comment on average.\n    // If an index is all nulls (no parents match any children)\n    // this will collapse to 0.\n    const scaledChildSelectivity =\n      1 - Math.pow(1 - child.selectivity, fanoutFactor.fanout);\n\n    // Why do we not need fanout in the other direction?\n    // E.g., for an `inventory -> film` flipped-join, if each film has 100 inventories (100 copies)\n    // then we're more likely to hit an inventory row compared to if each film has 1 inventory.\n    // Flipped-join already accounts for this because the child selectivity is implicitly accounted\n    // for. The returned row estimate of the child is already representative of how many\n    // rows the child will have post-filtering.\n\n    /**\n     * How selective is the graph from this point forward?\n     * If we are _very_ selective then we must scan more parent rows\n     * before finding a match.\n     * E.g., if childSelectivity = 0.1 and downstreamChildSelectivity = 0.5\n     * then we only pass 5% of parent rows (0.1 * 0.5 = 0.05).\n     *\n     * This is used to estimate how many rows will be pulled from the parent\n     * when trying to satisfy downstream constraints and a limit.\n     *\n     * NOTE: We do not know if the probabilities are correlated so we assume independence.\n     * This is a fundamental limitation of the planner.\n     */\n    const parent = this.#parent.estimateCost(\n      // Selectivity flows up the graph from child to parent\n      // so we can determine the total selectivity of all ANDed exists checks.\n      this.#type === 'flipped'\n        ? 1 * downstreamChildSelectivity\n        : scaledChildSelectivity * downstreamChildSelectivity,\n      branchPattern,\n      planDebugger,\n    );\n\n    let costEstimate: CostEstimate;\n\n    if (this.type === 'semi') {\n      costEstimate = {\n        startupCost: parent.startupCost,\n        scanEst:\n          parent.limit === undefined\n            ? parent.returnedRows\n            : Math.min(\n                parent.returnedRows,\n                downstreamChildSelectivity === 0\n                  ? 0\n                  : parent.limit / downstreamChildSelectivity,\n              ),\n        cost:\n          parent.cost +\n          parent.scanEst * (child.startupCost + child.cost + child.scanEst),\n        returnedRows: parent.returnedRows * child.selectivity,\n        selectivity: child.selectivity * parent.selectivity,\n        limit: parent.limit,\n        fanout: parent.fanout,\n      };\n    } else {\n      costEstimate = {\n        startupCost: child.startupCost,\n        scanEst:\n          parent.limit === undefined\n            ? parent.returnedRows * child.returnedRows\n            : Math.min(\n                parent.returnedRows * child.returnedRows,\n                downstreamChildSelectivity === 0\n                  ? 0\n                  : parent.limit / downstreamChildSelectivity,\n              ),\n        cost:\n          child.cost +\n          child.scanEst * (parent.startupCost + parent.cost + parent.scanEst),\n        // the child selectivity is not relevant here because it has already been taken into account via the flipping.\n        // I.e., `child.returnedRows` is the estimated number of rows produced by the child _after_ taking filtering into account.\n        returnedRows: parent.returnedRows * child.returnedRows,\n        selectivity: parent.selectivity * child.selectivity,\n        limit: parent.limit,\n        fanout: parent.fanout,\n      };\n    }\n\n    if (planDebugger) {\n      planDebugger.log({\n        type: 'node-cost',\n        nodeType: 'join',\n        node: this.getName(),\n        branchPattern,\n        downstreamChildSelectivity,\n        costEstimate: omitFanout(costEstimate),\n        joinType: this.#type,\n      });\n    }\n\n    return costEstimate;\n  }\n\n  /**\n   * Get a human-readable name for this join for debugging.\n   * Format: \"parentName ⋈ childName\"\n   */\n  getName(): string {\n    const parentName = getNodeName(this.#parent);\n    const childName = getNodeName(this.#child);\n    return `${parentName} ⋈ ${childName}`;\n  }\n\n  /**\n   * Get debug information about this join's state.\n   */\n  getDebugInfo(): {\n    name: string;\n    type: 'semi' | 'flipped';\n    planId: number;\n  } {\n    return {\n      name: this.getName(),\n      type: this.#type,\n      planId: this.planId,\n    };\n  }\n}\n\nexport class UnflippableJoinError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'UnflippableJoinError';\n  }\n}\n\n/**\n * Get a human-readable name for any planner node.\n * Used for debugging and tracing.\n */\nfunction getNodeName(node: PlannerNode): string {\n  switch (node.kind) {\n    case 'connection':\n      return node.name;\n    case 'join':\n      return node.getName();\n    case 'fan-out':\n      return 'FO';\n    case 'fan-in':\n      return 'FI';\n    case 'terminus':\n      return 'terminus';\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAyBA,SAAS,mCACP,oBACA,kBACA,iBAC+B;AAC/B,KAAI,CAAC,mBAAoB,QAAO,KAAA;CAEhC,MAAM,aAAa,OAAO,KAAK,iBAAiB;CAChD,MAAM,YAAY,OAAO,KAAK,gBAAgB;CAC9C,MAAM,aAAgC,EAAE;AAExC,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,mBAAmB,EAAE;EAC7D,MAAM,QAAQ,WAAW,QAAQ,IAAI;AACrC,MAAI,UAAU,GAGZ,YAAW,UAAU,UAAU;;AAInC,QAAO,OAAO,KAAK,WAAW,CAAC,SAAS,IAAI,aAAa,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiD3D,IAAa,cAAb,MAAyB;CACvB,OAAgB;CAEhB;CACA;CACA;CACA;CACA;CACA;CACA;CAGA;CACA;CAEA,YACE,QACA,OACA,kBACA,iBACA,WACA,QACA,cAAkC,QAClC;AACA,QAAA,OAAa;AACb,QAAA,cAAoB;AACpB,QAAA,SAAe;AACf,QAAA,QAAc;AACd,QAAA,kBAAwB;AACxB,QAAA,mBAAyB;AACzB,QAAA,YAAkB;AAClB,OAAK,SAAS;;CAGhB,UAAU,MAAyB;AACjC,QAAA,SAAe;;CAGjB,IAAI,SAAsB;AACxB,SAAO,MAAA,WAAiB,KAAA,GAAW,iBAAiB;AACpD,SAAO,MAAA;;CAGT,sBAAwC;AACtC,SAAO;;CAGT,aAAa,OAA0B;AACrC,MAAI,UAAU,MAAA,MACZ,MAAK,MAAM;MAEX,QACE,UAAU,MAAA,QACV,8CACD;;CAIL,OAAa;AACX,SAAO,MAAA,SAAe,QAAQ,4BAA4B;AAC1D,MAAI,CAAC,MAAA,UACH,OAAM,IAAI,qBACR,sDACD;AAEH,QAAA,OAAa;;CAGf,IAAI,OAA2B;AAC7B,SAAO,MAAA;;CAET,cAAuB;AACrB,SAAO,MAAA;;;;;;;;;;;;;;;;;CAkBT,mBAAyB;AACvB,SAAO,MAAA,SAAe,WAAW,kCAAkC;AAEnE,QAAA,MAAY,iCAAiC;;;;;;;;CAS/C,kCAAwC;AACtC,QAAA,OAAa,iCAAiC;;CAGhD,qBACE,eACA,YACA,MACA,cACM;AACN,gBAAc,IAAI;GAChB,MAAM;GACN,UAAU;GACV,MAAM,KAAK,SAAS;GACpB;GACA;GACA,MAAM,OAAO,YAAY,KAAK,GAAG;GAClC,CAAC;AAEF,MAAI,MAAA,SAAe,QAAQ;AAGzB,SAAA,MAAY,qBACV,eACA,MAAA,iBACA,MACA,aACD;AAED,SAAA,OAAa,qBACX,eACA,YACA,MACA,aACD;aACQ,MAAA,SAAe,WAAW;GAMnC,MAAM,uBAAuB,mCAC3B,YACA,MAAA,kBACA,MAAA,gBACD;AACD,SAAA,MAAY,qBACV,eACA,sBACA,MACA,aACD;AAID,SAAA,OAAa,qBACX,eACA,iBAAiB,YAAY,MAAA,iBAAuB,EACpD,MACA,aACD;;;CAIL,QAAc;AACZ,QAAA,OAAa,MAAA;;CAGf,aAUE,4BA0BA,eACA,cACc;;;;;;;;EAQd,MAAM,QAAQ,MAAA,MAAY,aAAa,GAAG,eAAe,aAAa;EAEtE,MAAM,eAAe,MAAM,OAAO,OAAO,KAAK,MAAA,gBAAsB,CAAC;EAMrE,MAAM,yBACJ,IAAI,KAAK,IAAI,IAAI,MAAM,aAAa,aAAa,OAAO;;;;;;;;;;;;;;EAsB1D,MAAM,SAAS,MAAA,OAAa,aAG1B,MAAA,SAAe,YACX,IAAI,6BACJ,yBAAyB,4BAC7B,eACA,aACD;EAED,IAAI;AAEJ,MAAI,KAAK,SAAS,OAChB,gBAAe;GACb,aAAa,OAAO;GACpB,SACE,OAAO,UAAU,KAAA,IACb,OAAO,eACP,KAAK,IACH,OAAO,cACP,+BAA+B,IAC3B,IACA,OAAO,QAAQ,2BACpB;GACP,MACE,OAAO,OACP,OAAO,WAAW,MAAM,cAAc,MAAM,OAAO,MAAM;GAC3D,cAAc,OAAO,eAAe,MAAM;GAC1C,aAAa,MAAM,cAAc,OAAO;GACxC,OAAO,OAAO;GACd,QAAQ,OAAO;GAChB;MAED,gBAAe;GACb,aAAa,MAAM;GACnB,SACE,OAAO,UAAU,KAAA,IACb,OAAO,eAAe,MAAM,eAC5B,KAAK,IACH,OAAO,eAAe,MAAM,cAC5B,+BAA+B,IAC3B,IACA,OAAO,QAAQ,2BACpB;GACP,MACE,MAAM,OACN,MAAM,WAAW,OAAO,cAAc,OAAO,OAAO,OAAO;GAG7D,cAAc,OAAO,eAAe,MAAM;GAC1C,aAAa,OAAO,cAAc,MAAM;GACxC,OAAO,OAAO;GACd,QAAQ,OAAO;GAChB;AAGH,MAAI,aACF,cAAa,IAAI;GACf,MAAM;GACN,UAAU;GACV,MAAM,KAAK,SAAS;GACpB;GACA;GACA,cAAc,WAAW,aAAa;GACtC,UAAU,MAAA;GACX,CAAC;AAGJ,SAAO;;;;;;CAOT,UAAkB;AAGhB,SAAO,GAFY,YAAY,MAAA,OAAa,CAEvB,KADH,YAAY,MAAA,MAAY;;;;;CAO5C,eAIE;AACA,SAAO;GACL,MAAM,KAAK,SAAS;GACpB,MAAM,MAAA;GACN,QAAQ,KAAK;GACd;;;AAIL,IAAa,uBAAb,cAA0C,MAAM;CAC9C,YAAY,SAAiB;AAC3B,QAAM,QAAQ;AACd,OAAK,OAAO;;;;;;;AAQhB,SAAS,YAAY,MAA2B;AAC9C,SAAQ,KAAK,MAAb;EACE,KAAK,aACH,QAAO,KAAK;EACd,KAAK,OACH,QAAO,KAAK,SAAS;EACvB,KAAK,UACH,QAAO;EACT,KAAK,SACH,QAAO;EACT,KAAK,WACH,QAAO"}

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

@@ -1,8 +1,12 @@
+//#region ../zql/src/planner/planner-node.ts
+/**
+* Omit the fanout function from a cost estimate for serialization.
+*/
 function omitFanout(cost) {
-  const { fanout: _, ...rest } = cost;
-  return rest;
+	const { fanout: _, ...rest } = cost;
+	return rest;
 }
-export {
-  omitFanout
-};
-//# sourceMappingURL=planner-node.js.map
+//#endregion
+export { omitFanout };
+
+//# sourceMappingURL=planner-node.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"planner-node.js","sources":["../../../../../zql/src/planner/planner-node.ts"],"sourcesContent":["import type {FanoutCostModel, PlannerConnection} from './planner-connection.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 type {PlannerTerminus} from './planner-terminus.ts';\n\n/**\n * Union of all node types that can appear in the planner graph.\n * All nodes follow the dual-state pattern described above.\n */\nexport type PlannerNode =\n  | PlannerJoin\n  | PlannerConnection\n  | PlannerFanOut\n  | PlannerFanIn\n  | PlannerTerminus;\n\nexport type CostEstimate = {\n  startupCost: number;\n  scanEst: number;\n\n  /**\n   * The cumulative cost to run the pipeline so far.\n   *\n   * In a semi-join, each row output by the parent is multiplied by the cost to evaluate the child.\n   * In a flipped join, each row output by the child is multiplied by the cost to evaluate the parent.\n   *\n   * \"each row output by the parent\" is determined by the downstreamChildSelectivity parameter in combination\n   * with the limit or the rows output by the parent node.\n   *\n   * We pull on the parent and stop when hitting a limit or exhausting rows.\n   */\n  cost: number;\n\n  /**\n   * The number of rows output from a node.\n   * - For a connection, this is the estimated number of rows returned by the source query.\n   * - For a semi-join, this is the estimated number of rows that pass the semi-join filter.\n   * - For a flipped join, this is the estimated number of rows that match all child rows.\n   * - For fan-in, this is the sum of the rows from each input.\n   * - For fan-out, this is the rows from its input.\n   */\n  returnedRows: number;\n\n  /**\n   * The selectivity of the node.\n   * For a connection, this is the fraction of rows passing filters (1.0 = no filtering).\n   * For joins, this is the fraction of parent rows that match child rows.\n   * For fan-in, this is the probability of a match in any branch, assuming independent events.\n   * For fan-out, this is the selectivity of its input.\n   */\n  selectivity: number;\n  limit: number | undefined;\n\n  fanout: FanoutCostModel;\n};\n\n/**\n * Omit the fanout function from a cost estimate for serialization.\n */\nexport function omitFanout(cost: CostEstimate): Omit<CostEstimate, 'fanout'> {\n  const {fanout: _, ...rest} = cost;\n  return rest;\n}\n\nexport type NodeType = PlannerNode['kind'];\n\nexport type JoinOrConnection = 'join' | 'connection';\n\nexport type JoinType = PlannerJoin['type'];\n"],"names":[],"mappings":"AA4DO,SAAS,WAAW,MAAkD;AAC3E,QAAM,EAAC,QAAQ,GAAG,GAAG,SAAQ;AAC7B,SAAO;AACT;"}
+{"version":3,"file":"planner-node.js","names":[],"sources":["../../../../../zql/src/planner/planner-node.ts"],"sourcesContent":["import type {FanoutCostModel, PlannerConnection} from './planner-connection.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 type {PlannerTerminus} from './planner-terminus.ts';\n\n/**\n * Union of all node types that can appear in the planner graph.\n * All nodes follow the dual-state pattern described above.\n */\nexport type PlannerNode =\n  | PlannerJoin\n  | PlannerConnection\n  | PlannerFanOut\n  | PlannerFanIn\n  | PlannerTerminus;\n\nexport type CostEstimate = {\n  startupCost: number;\n  scanEst: number;\n\n  /**\n   * The cumulative cost to run the pipeline so far.\n   *\n   * In a semi-join, each row output by the parent is multiplied by the cost to evaluate the child.\n   * In a flipped join, each row output by the child is multiplied by the cost to evaluate the parent.\n   *\n   * \"each row output by the parent\" is determined by the downstreamChildSelectivity parameter in combination\n   * with the limit or the rows output by the parent node.\n   *\n   * We pull on the parent and stop when hitting a limit or exhausting rows.\n   */\n  cost: number;\n\n  /**\n   * The number of rows output from a node.\n   * - For a connection, this is the estimated number of rows returned by the source query.\n   * - For a semi-join, this is the estimated number of rows that pass the semi-join filter.\n   * - For a flipped join, this is the estimated number of rows that match all child rows.\n   * - For fan-in, this is the sum of the rows from each input.\n   * - For fan-out, this is the rows from its input.\n   */\n  returnedRows: number;\n\n  /**\n   * The selectivity of the node.\n   * For a connection, this is the fraction of rows passing filters (1.0 = no filtering).\n   * For joins, this is the fraction of parent rows that match child rows.\n   * For fan-in, this is the probability of a match in any branch, assuming independent events.\n   * For fan-out, this is the selectivity of its input.\n   */\n  selectivity: number;\n  limit: number | undefined;\n\n  fanout: FanoutCostModel;\n};\n\n/**\n * Omit the fanout function from a cost estimate for serialization.\n */\nexport function omitFanout(cost: CostEstimate): Omit<CostEstimate, 'fanout'> {\n  const {fanout: _, ...rest} = cost;\n  return rest;\n}\n\nexport type NodeType = PlannerNode['kind'];\n\nexport type JoinOrConnection = 'join' | 'connection';\n\nexport type JoinType = PlannerJoin['type'];\n"],"mappings":";;;;AA4DA,SAAgB,WAAW,MAAkD;CAC3E,MAAM,EAAC,QAAQ,GAAG,GAAG,SAAQ;AAC7B,QAAO"}

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

@@ -1,24 +1,17 @@
 import { PlannerConnection } from "./planner-connection.js";
-class PlannerSource {
-  name;
-  #model;
-  constructor(name, model) {
-    this.name = name;
-    this.#model = model;
-  }
-  connect(sort, filters, isRoot, baseConstraints, limit) {
-    return new PlannerConnection(
-      this.name,
-      this.#model,
-      sort,
-      filters,
-      isRoot,
-      baseConstraints,
-      limit
-    );
-  }
-}
-export {
-  PlannerSource
+//#region ../zql/src/planner/planner-source.ts
+var PlannerSource = class {
+	name;
+	#model;
+	constructor(name, model) {
+		this.name = name;
+		this.#model = model;
+	}
+	connect(sort, filters, isRoot, baseConstraints, limit) {
+		return new PlannerConnection(this.name, this.#model, sort, filters, isRoot, baseConstraints, limit);
+	}
 };
-//# sourceMappingURL=planner-source.js.map
+//#endregion
+export { PlannerSource };
+
+//# sourceMappingURL=planner-source.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"planner-source.js","sources":["../../../../../zql/src/planner/planner-source.ts"],"sourcesContent":["import type {Condition, Ordering} from '../../../zero-protocol/src/ast.ts';\nimport {\n  PlannerConnection,\n  type ConnectionCostModel,\n} from './planner-connection.ts';\nimport type {PlannerConstraint} from './planner-constraint.ts';\n\nexport type {ConnectionCostModel};\n\nexport class PlannerSource {\n  readonly name: string;\n  readonly #model: ConnectionCostModel;\n\n  constructor(name: string, model: ConnectionCostModel) {\n    this.name = name;\n    this.#model = model;\n  }\n\n  connect(\n    sort: Ordering,\n    filters: Condition | undefined,\n    isRoot: boolean,\n    baseConstraints?: PlannerConstraint,\n    limit?: number,\n  ): PlannerConnection {\n    return new PlannerConnection(\n      this.name,\n      this.#model,\n      sort,\n      filters,\n      isRoot,\n      baseConstraints,\n      limit,\n    );\n  }\n}\n"],"names":[],"mappings":";AASO,MAAM,cAAc;AAAA,EAChB;AAAA,EACA;AAAA,EAET,YAAY,MAAc,OAA4B;AACpD,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,QACE,MACA,SACA,QACA,iBACA,OACmB;AACnB,WAAO,IAAI;AAAA,MACT,KAAK;AAAA,MACL,KAAK;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ;AACF;"}
+{"version":3,"file":"planner-source.js","names":["#model"],"sources":["../../../../../zql/src/planner/planner-source.ts"],"sourcesContent":["import type {Condition, Ordering} from '../../../zero-protocol/src/ast.ts';\nimport {\n  PlannerConnection,\n  type ConnectionCostModel,\n} from './planner-connection.ts';\nimport type {PlannerConstraint} from './planner-constraint.ts';\n\nexport type {ConnectionCostModel};\n\nexport class PlannerSource {\n  readonly name: string;\n  readonly #model: ConnectionCostModel;\n\n  constructor(name: string, model: ConnectionCostModel) {\n    this.name = name;\n    this.#model = model;\n  }\n\n  connect(\n    sort: Ordering,\n    filters: Condition | undefined,\n    isRoot: boolean,\n    baseConstraints?: PlannerConstraint,\n    limit?: number,\n  ): PlannerConnection {\n    return new PlannerConnection(\n      this.name,\n      this.#model,\n      sort,\n      filters,\n      isRoot,\n      baseConstraints,\n      limit,\n    );\n  }\n}\n"],"mappings":";;AASA,IAAa,gBAAb,MAA2B;CACzB;CACA;CAEA,YAAY,MAAc,OAA4B;AACpD,OAAK,OAAO;AACZ,QAAA,QAAc;;CAGhB,QACE,MACA,SACA,QACA,iBACA,OACmB;AACnB,SAAO,IAAI,kBACT,KAAK,MACL,MAAA,OACA,MACA,SACA,QACA,iBACA,MACD"}

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

@@ -1,29 +1,29 @@
-class PlannerTerminus {
-  kind = "terminus";
-  #input;
-  constructor(input) {
-    this.#input = input;
-  }
-  get pinned() {
-    return true;
-  }
-  closestJoinOrSource() {
-    return this.#input.closestJoinOrSource();
-  }
-  propagateConstraints(planDebugger) {
-    this.#input.propagateConstraints([], void 0, this, planDebugger);
-  }
-  estimateCost(planDebugger) {
-    return this.#input.estimateCost(1, [], planDebugger);
-  }
-  /**
-   * Propagate unlimiting when a parent join is flipped.
-   * Terminus doesn't participate in unlimiting.
-   */
-  propagateUnlimitFromFlippedJoin() {
-  }
-}
-export {
-  PlannerTerminus
+//#region ../zql/src/planner/planner-terminus.ts
+var PlannerTerminus = class {
+	kind = "terminus";
+	#input;
+	constructor(input) {
+		this.#input = input;
+	}
+	get pinned() {
+		return true;
+	}
+	closestJoinOrSource() {
+		return this.#input.closestJoinOrSource();
+	}
+	propagateConstraints(planDebugger) {
+		this.#input.propagateConstraints([], void 0, this, planDebugger);
+	}
+	estimateCost(planDebugger) {
+		return this.#input.estimateCost(1, [], planDebugger);
+	}
+	/**
+	* Propagate unlimiting when a parent join is flipped.
+	* Terminus doesn't participate in unlimiting.
+	*/
+	propagateUnlimitFromFlippedJoin() {}
 };
-//# sourceMappingURL=planner-terminus.js.map
+//#endregion
+export { PlannerTerminus };
+
+//# sourceMappingURL=planner-terminus.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"planner-terminus.js","sources":["../../../../../zql/src/planner/planner-terminus.ts"],"sourcesContent":["import type {PlanDebugger} from './planner-debug.ts';\nimport type {\n  CostEstimate,\n  JoinOrConnection,\n  PlannerNode,\n} from './planner-node.ts';\n\nexport class PlannerTerminus {\n  readonly kind = 'terminus' as const;\n  readonly #input: Exclude<PlannerNode, PlannerTerminus>;\n\n  constructor(input: Exclude<PlannerNode, PlannerTerminus>) {\n    this.#input = input;\n  }\n\n  get pinned(): boolean {\n    return true;\n  }\n\n  closestJoinOrSource(): JoinOrConnection {\n    return this.#input.closestJoinOrSource();\n  }\n\n  propagateConstraints(planDebugger?: PlanDebugger): void {\n    this.#input.propagateConstraints([], undefined, this, planDebugger);\n  }\n\n  estimateCost(planDebugger?: PlanDebugger): CostEstimate {\n    // Terminus starts the cost estimation flow with empty branch pattern\n    return this.#input.estimateCost(1, [], planDebugger);\n  }\n\n  /**\n   * Propagate unlimiting when a parent join is flipped.\n   * Terminus doesn't participate in unlimiting.\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    // No-op: terminus doesn't need to unlimit anything\n  }\n}\n"],"names":[],"mappings":"AAOO,MAAM,gBAAgB;AAAA,EAClB,OAAO;AAAA,EACP;AAAA,EAET,YAAY,OAA8C;AACxD,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,IAAI,SAAkB;AACpB,WAAO;AAAA,EACT;AAAA,EAEA,sBAAwC;AACtC,WAAO,KAAK,OAAO,oBAAA;AAAA,EACrB;AAAA,EAEA,qBAAqB,cAAmC;AACtD,SAAK,OAAO,qBAAqB,CAAA,GAAI,QAAW,MAAM,YAAY;AAAA,EACpE;AAAA,EAEA,aAAa,cAA2C;AAEtD,WAAO,KAAK,OAAO,aAAa,GAAG,CAAA,GAAI,YAAY;AAAA,EACrD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,kCAAwC;AAAA,EAExC;AACF;"}
+{"version":3,"file":"planner-terminus.js","names":["#input"],"sources":["../../../../../zql/src/planner/planner-terminus.ts"],"sourcesContent":["import type {PlanDebugger} from './planner-debug.ts';\nimport type {\n  CostEstimate,\n  JoinOrConnection,\n  PlannerNode,\n} from './planner-node.ts';\n\nexport class PlannerTerminus {\n  readonly kind = 'terminus' as const;\n  readonly #input: Exclude<PlannerNode, PlannerTerminus>;\n\n  constructor(input: Exclude<PlannerNode, PlannerTerminus>) {\n    this.#input = input;\n  }\n\n  get pinned(): boolean {\n    return true;\n  }\n\n  closestJoinOrSource(): JoinOrConnection {\n    return this.#input.closestJoinOrSource();\n  }\n\n  propagateConstraints(planDebugger?: PlanDebugger): void {\n    this.#input.propagateConstraints([], undefined, this, planDebugger);\n  }\n\n  estimateCost(planDebugger?: PlanDebugger): CostEstimate {\n    // Terminus starts the cost estimation flow with empty branch pattern\n    return this.#input.estimateCost(1, [], planDebugger);\n  }\n\n  /**\n   * Propagate unlimiting when a parent join is flipped.\n   * Terminus doesn't participate in unlimiting.\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    // No-op: terminus doesn't need to unlimit anything\n  }\n}\n"],"mappings":";AAOA,IAAa,kBAAb,MAA6B;CAC3B,OAAgB;CAChB;CAEA,YAAY,OAA8C;AACxD,QAAA,QAAc;;CAGhB,IAAI,SAAkB;AACpB,SAAO;;CAGT,sBAAwC;AACtC,SAAO,MAAA,MAAY,qBAAqB;;CAG1C,qBAAqB,cAAmC;AACtD,QAAA,MAAY,qBAAqB,EAAE,EAAE,KAAA,GAAW,MAAM,aAAa;;CAGrE,aAAa,cAA2C;AAEtD,SAAO,MAAA,MAAY,aAAa,GAAG,EAAE,EAAE,aAAa;;;;;;CAOtD,kCAAwC"}

package/out/zql/src/query/complete-ordering.js

@@ -1,71 +1,47 @@
 import { assert } from "../../../shared/src/asserts.js";
 import { must } from "../../../shared/src/must.js";
+//#region ../zql/src/query/complete-ordering.ts
 function completeOrdering(ast, getPrimaryKey) {
-  const primaryKey = must(getPrimaryKey(ast.table));
-  return {
-    ...ast,
-    ...ast.related ? {
-      related: ast.related?.map((r) => ({
-        ...r,
-        subquery: completeOrdering(r.subquery, getPrimaryKey)
-      }))
-    } : void 0,
-    ...ast.where ? {
-      where: completeOrderingInCondition(ast.where, getPrimaryKey)
-    } : void 0,
-    orderBy: addPrimaryKeys(primaryKey, ast.orderBy)
-  };
+	const primaryKey = must(getPrimaryKey(ast.table));
+	return {
+		...ast,
+		...ast.related ? { related: ast.related?.map((r) => ({
+			...r,
+			subquery: completeOrdering(r.subquery, getPrimaryKey)
+		})) } : void 0,
+		...ast.where ? { where: completeOrderingInCondition(ast.where, getPrimaryKey) } : void 0,
+		orderBy: addPrimaryKeys(primaryKey, ast.orderBy)
+	};
 }
 function assertOrderingIncludesPK(ordering, pk) {
-  const orderingFields = ordering.map(([field]) => field);
-  const missingFields = pk.filter((pkField) => !orderingFields.includes(pkField));
-  assert(
-    missingFields.length === 0,
-    `Ordering must include all primary key fields. Missing: ${missingFields.join(
-      ", "
-    )}.`
-  );
+	const orderingFields = ordering.map(([field]) => field);
+	const missingFields = pk.filter((pkField) => !orderingFields.includes(pkField));
+	assert(missingFields.length === 0, `Ordering must include all primary key fields. Missing: ${missingFields.join(", ")}.`);
 }
 function completeOrderingInCondition(condition, getPrimaryKey) {
-  if (!condition) {
-    return condition;
-  }
-  if (condition.type === "simple") {
-    return condition;
-  }
-  if (condition.type === "correlatedSubquery") {
-    return {
-      ...condition,
-      related: {
-        ...condition.related,
-        subquery: completeOrdering(condition.related.subquery, getPrimaryKey)
-      }
-    };
-  }
-  condition.type;
-  return {
-    ...condition,
-    conditions: condition.conditions.map(
-      (c) => completeOrderingInCondition(c, getPrimaryKey)
-    )
-  };
+	if (!condition) return condition;
+	if (condition.type === "simple") return condition;
+	if (condition.type === "correlatedSubquery") return {
+		...condition,
+		related: {
+			...condition.related,
+			subquery: completeOrdering(condition.related.subquery, getPrimaryKey)
+		}
+	};
+	condition.type;
+	return {
+		...condition,
+		conditions: condition.conditions.map((c) => completeOrderingInCondition(c, getPrimaryKey))
+	};
 }
 function addPrimaryKeys(primaryKey, orderBy) {
-  orderBy = orderBy ?? [];
-  const primaryKeysToAdd = new Set(primaryKey);
-  for (const [field] of orderBy) {
-    primaryKeysToAdd.delete(field);
-  }
-  if (primaryKeysToAdd.size === 0) {
-    return orderBy;
-  }
-  return [
-    ...orderBy,
-    ...[...primaryKeysToAdd].map((key) => [key, "asc"])
-  ];
+	orderBy = orderBy ?? [];
+	const primaryKeysToAdd = new Set(primaryKey);
+	for (const [field] of orderBy) primaryKeysToAdd.delete(field);
+	if (primaryKeysToAdd.size === 0) return orderBy;
+	return [...orderBy, ...[...primaryKeysToAdd].map((key) => [key, "asc"])];
 }
-export {
-  assertOrderingIncludesPK,
-  completeOrdering
-};
-//# sourceMappingURL=complete-ordering.js.map
+//#endregion
+export { assertOrderingIncludesPK, completeOrdering };
+
+//# sourceMappingURL=complete-ordering.js.map

package/out/zql/src/query/complete-ordering.js.map

@@ -1 +1 @@
-{"version":3,"file":"complete-ordering.js","sources":["../../../../../zql/src/query/complete-ordering.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport type {AST, Condition, Ordering} from '../../../zero-protocol/src/ast.ts';\nimport type {PrimaryKey} from '../../../zero-protocol/src/primary-key.ts';\n\nexport function completeOrdering(\n  ast: AST,\n  getPrimaryKey: (tableName: string) => PrimaryKey,\n): AST {\n  const primaryKey = must(getPrimaryKey(ast.table));\n  return {\n    ...ast,\n    ...(ast.related\n      ? {\n          related: ast.related?.map(r => ({\n            ...r,\n            subquery: completeOrdering(r.subquery, getPrimaryKey),\n          })),\n        }\n      : undefined),\n    ...(ast.where\n      ? {\n          where: completeOrderingInCondition(ast.where, getPrimaryKey),\n        }\n      : undefined),\n    orderBy: addPrimaryKeys(primaryKey, ast.orderBy),\n  };\n}\n\nexport function assertOrderingIncludesPK(\n  ordering: Ordering,\n  pk: PrimaryKey,\n): void {\n  // oxlint-disable-next-line unicorn/prefer-set-has -- Array is more appropriate here for small collections\n  const orderingFields = ordering.map(([field]) => field);\n  const missingFields = pk.filter(pkField => !orderingFields.includes(pkField));\n\n  assert(\n    missingFields.length === 0,\n    `Ordering must include all primary key fields. Missing: ${missingFields.join(\n      ', ',\n    )}.`,\n  );\n}\n\nfunction completeOrderingInCondition<C extends Condition | undefined>(\n  condition: C,\n  getPrimaryKey: (tableName: string) => PrimaryKey,\n): C {\n  if (!condition) {\n    return condition;\n  }\n  if (condition.type === 'simple') {\n    return condition;\n  }\n  if (condition.type === 'correlatedSubquery') {\n    return {\n      ...condition,\n      related: {\n        ...condition.related,\n        subquery: completeOrdering(condition.related.subquery, getPrimaryKey),\n      },\n    };\n  }\n  condition.type satisfies 'and' | 'or';\n  return {\n    ...condition,\n    conditions: condition.conditions.map(c =>\n      completeOrderingInCondition(c, getPrimaryKey),\n    ),\n  };\n}\n\nfunction addPrimaryKeys(\n  primaryKey: PrimaryKey,\n  orderBy: Ordering | undefined,\n): Ordering {\n  orderBy = orderBy ?? [];\n  const primaryKeysToAdd = new Set(primaryKey);\n\n  for (const [field] of orderBy) {\n    primaryKeysToAdd.delete(field);\n  }\n\n  if (primaryKeysToAdd.size === 0) {\n    return orderBy;\n  }\n\n  return [\n    ...orderBy,\n    ...[...primaryKeysToAdd].map(key => [key, 'asc'] as [string, 'asc']),\n  ];\n}\n"],"names":[],"mappings":";;AAKO,SAAS,iBACd,KACA,eACK;AACL,QAAM,aAAa,KAAK,cAAc,IAAI,KAAK,CAAC;AAChD,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAI,IAAI,UACJ;AAAA,MACE,SAAS,IAAI,SAAS,IAAI,CAAA,OAAM;AAAA,QAC9B,GAAG;AAAA,QACH,UAAU,iBAAiB,EAAE,UAAU,aAAa;AAAA,MAAA,EACpD;AAAA,IAAA,IAEJ;AAAA,IACJ,GAAI,IAAI,QACJ;AAAA,MACE,OAAO,4BAA4B,IAAI,OAAO,aAAa;AAAA,IAAA,IAE7D;AAAA,IACJ,SAAS,eAAe,YAAY,IAAI,OAAO;AAAA,EAAA;AAEnD;AAEO,SAAS,yBACd,UACA,IACM;AAEN,QAAM,iBAAiB,SAAS,IAAI,CAAC,CAAC,KAAK,MAAM,KAAK;AACtD,QAAM,gBAAgB,GAAG,OAAO,CAAA,YAAW,CAAC,eAAe,SAAS,OAAO,CAAC;AAE5E;AAAA,IACE,cAAc,WAAW;AAAA,IACzB,0DAA0D,cAAc;AAAA,MACtE;AAAA,IAAA,CACD;AAAA,EAAA;AAEL;AAEA,SAAS,4BACP,WACA,eACG;AACH,MAAI,CAAC,WAAW;AACd,WAAO;AAAA,EACT;AACA,MAAI,UAAU,SAAS,UAAU;AAC/B,WAAO;AAAA,EACT;AACA,MAAI,UAAU,SAAS,sBAAsB;AAC3C,WAAO;AAAA,MACL,GAAG;AAAA,MACH,SAAS;AAAA,QACP,GAAG,UAAU;AAAA,QACb,UAAU,iBAAiB,UAAU,QAAQ,UAAU,aAAa;AAAA,MAAA;AAAA,IACtE;AAAA,EAEJ;AACA,YAAU;AACV,SAAO;AAAA,IACL,GAAG;AAAA,IACH,YAAY,UAAU,WAAW;AAAA,MAAI,CAAA,MACnC,4BAA4B,GAAG,aAAa;AAAA,IAAA;AAAA,EAC9C;AAEJ;AAEA,SAAS,eACP,YACA,SACU;AACV,YAAU,WAAW,CAAA;AACrB,QAAM,mBAAmB,IAAI,IAAI,UAAU;AAE3C,aAAW,CAAC,KAAK,KAAK,SAAS;AAC7B,qBAAiB,OAAO,KAAK;AAAA,EAC/B;AAEA,MAAI,iBAAiB,SAAS,GAAG;AAC/B,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAG,CAAC,GAAG,gBAAgB,EAAE,IAAI,CAAA,QAAO,CAAC,KAAK,KAAK,CAAoB;AAAA,EAAA;AAEvE;"}
+{"version":3,"file":"complete-ordering.js","names":[],"sources":["../../../../../zql/src/query/complete-ordering.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport type {AST, Condition, Ordering} from '../../../zero-protocol/src/ast.ts';\nimport type {PrimaryKey} from '../../../zero-protocol/src/primary-key.ts';\n\nexport function completeOrdering(\n  ast: AST,\n  getPrimaryKey: (tableName: string) => PrimaryKey,\n): AST {\n  const primaryKey = must(getPrimaryKey(ast.table));\n  return {\n    ...ast,\n    ...(ast.related\n      ? {\n          related: ast.related?.map(r => ({\n            ...r,\n            subquery: completeOrdering(r.subquery, getPrimaryKey),\n          })),\n        }\n      : undefined),\n    ...(ast.where\n      ? {\n          where: completeOrderingInCondition(ast.where, getPrimaryKey),\n        }\n      : undefined),\n    orderBy: addPrimaryKeys(primaryKey, ast.orderBy),\n  };\n}\n\nexport function assertOrderingIncludesPK(\n  ordering: Ordering,\n  pk: PrimaryKey,\n): void {\n  // oxlint-disable-next-line unicorn/prefer-set-has -- Array is more appropriate here for small collections\n  const orderingFields = ordering.map(([field]) => field);\n  const missingFields = pk.filter(pkField => !orderingFields.includes(pkField));\n\n  assert(\n    missingFields.length === 0,\n    `Ordering must include all primary key fields. Missing: ${missingFields.join(\n      ', ',\n    )}.`,\n  );\n}\n\nfunction completeOrderingInCondition<C extends Condition | undefined>(\n  condition: C,\n  getPrimaryKey: (tableName: string) => PrimaryKey,\n): C {\n  if (!condition) {\n    return condition;\n  }\n  if (condition.type === 'simple') {\n    return condition;\n  }\n  if (condition.type === 'correlatedSubquery') {\n    return {\n      ...condition,\n      related: {\n        ...condition.related,\n        subquery: completeOrdering(condition.related.subquery, getPrimaryKey),\n      },\n    };\n  }\n  condition.type satisfies 'and' | 'or';\n  return {\n    ...condition,\n    conditions: condition.conditions.map(c =>\n      completeOrderingInCondition(c, getPrimaryKey),\n    ),\n  };\n}\n\nfunction addPrimaryKeys(\n  primaryKey: PrimaryKey,\n  orderBy: Ordering | undefined,\n): Ordering {\n  orderBy = orderBy ?? [];\n  const primaryKeysToAdd = new Set(primaryKey);\n\n  for (const [field] of orderBy) {\n    primaryKeysToAdd.delete(field);\n  }\n\n  if (primaryKeysToAdd.size === 0) {\n    return orderBy;\n  }\n\n  return [\n    ...orderBy,\n    ...[...primaryKeysToAdd].map(key => [key, 'asc'] as [string, 'asc']),\n  ];\n}\n"],"mappings":";;;AAKA,SAAgB,iBACd,KACA,eACK;CACL,MAAM,aAAa,KAAK,cAAc,IAAI,MAAM,CAAC;AACjD,QAAO;EACL,GAAG;EACH,GAAI,IAAI,UACJ,EACE,SAAS,IAAI,SAAS,KAAI,OAAM;GAC9B,GAAG;GACH,UAAU,iBAAiB,EAAE,UAAU,cAAc;GACtD,EAAE,EACJ,GACD,KAAA;EACJ,GAAI,IAAI,QACJ,EACE,OAAO,4BAA4B,IAAI,OAAO,cAAc,EAC7D,GACD,KAAA;EACJ,SAAS,eAAe,YAAY,IAAI,QAAQ;EACjD;;AAGH,SAAgB,yBACd,UACA,IACM;CAEN,MAAM,iBAAiB,SAAS,KAAK,CAAC,WAAW,MAAM;CACvD,MAAM,gBAAgB,GAAG,QAAO,YAAW,CAAC,eAAe,SAAS,QAAQ,CAAC;AAE7E,QACE,cAAc,WAAW,GACzB,0DAA0D,cAAc,KACtE,KACD,CAAC,GACH;;AAGH,SAAS,4BACP,WACA,eACG;AACH,KAAI,CAAC,UACH,QAAO;AAET,KAAI,UAAU,SAAS,SACrB,QAAO;AAET,KAAI,UAAU,SAAS,qBACrB,QAAO;EACL,GAAG;EACH,SAAS;GACP,GAAG,UAAU;GACb,UAAU,iBAAiB,UAAU,QAAQ,UAAU,cAAc;GACtE;EACF;AAEH,WAAU;AACV,QAAO;EACL,GAAG;EACH,YAAY,UAAU,WAAW,KAAI,MACnC,4BAA4B,GAAG,cAAc,CAC9C;EACF;;AAGH,SAAS,eACP,YACA,SACU;AACV,WAAU,WAAW,EAAE;CACvB,MAAM,mBAAmB,IAAI,IAAI,WAAW;AAE5C,MAAK,MAAM,CAAC,UAAU,QACpB,kBAAiB,OAAO,MAAM;AAGhC,KAAI,iBAAiB,SAAS,EAC5B,QAAO;AAGT,QAAO,CACL,GAAG,SACH,GAAG,CAAC,GAAG,iBAAiB,CAAC,KAAI,QAAO,CAAC,KAAK,MAAM,CAAoB,CACrE"}

package/out/zql/src/query/create-builder.js

@@ -1,30 +1,22 @@
-import { recordProxy } from "../../../shared/src/record-proxy.js";
 import { newQuery } from "./query-impl.js";
+import { recordProxy } from "../../../shared/src/record-proxy.js";
 import { newRunnableQuery } from "./runnable-query-impl.js";
+//#region ../zql/src/query/create-builder.ts
+/**
+* Returns a set of query builders for the given schema.
+*/
 function createBuilder(schema) {
-  return createBuilderWithQueryFactory(
-    schema,
-    (table) => newQuery(schema, table)
-  );
+	return createBuilderWithQueryFactory(schema, (table) => newQuery(schema, table));
 }
+/** @deprecated Use {@linkcode createBuilder} with `tx.run(zql.table.where(...))` instead. */
 function createRunnableBuilder(delegate, schema) {
-  if (!schema.enableLegacyQueries) {
-    return void 0;
-  }
-  return createBuilderWithQueryFactory(
-    schema,
-    (table) => newRunnableQuery(delegate, schema, table)
-  );
+	if (!schema.enableLegacyQueries) return;
+	return createBuilderWithQueryFactory(schema, (table) => newRunnableQuery(delegate, schema, table));
 }
 function createBuilderWithQueryFactory(schema, queryFactory) {
-  const target = Object.assign(/* @__PURE__ */ Object.create(null), schema.tables);
-  return recordProxy(
-    target,
-    (_tableSchema, prop) => queryFactory(prop)
-  );
+	return recordProxy(Object.assign(Object.create(null), schema.tables), (_tableSchema, prop) => queryFactory(prop));
 }
-export {
-  createBuilder,
-  createRunnableBuilder
-};
-//# sourceMappingURL=create-builder.js.map
+//#endregion
+export { createBuilder, createRunnableBuilder };
+
+//# sourceMappingURL=create-builder.js.map

package/out/zql/src/query/create-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-builder.js","sources":["../../../../../zql/src/query/create-builder.ts"],"sourcesContent":["import {recordProxy} from '../../../shared/src/record-proxy.ts';\nimport type {Schema} from '../../../zero-types/src/schema.ts';\nimport type {QueryDelegate} from './query-delegate.ts';\nimport {newQuery} from './query-impl.ts';\nimport type {Query} from './query.ts';\nimport {newRunnableQuery} from './runnable-query-impl.ts';\nimport type {ConditionalSchemaQuery, SchemaQuery} from './schema-query.ts';\n\n/**\n * Returns a set of query builders for the given schema.\n */\nexport function createBuilder<S extends Schema>(schema: S): SchemaQuery<S> {\n  return createBuilderWithQueryFactory(schema, table =>\n    newQuery(schema, table),\n  );\n}\n\n/** @deprecated Use {@linkcode createBuilder} with `tx.run(zql.table.where(...))` instead. */\nexport function createRunnableBuilder<S extends Schema>(\n  delegate: QueryDelegate,\n  schema: S,\n): ConditionalSchemaQuery<S> {\n  if (!schema.enableLegacyQueries) {\n    return undefined as ConditionalSchemaQuery<S>;\n  }\n\n  return createBuilderWithQueryFactory(schema, table =>\n    newRunnableQuery(delegate, schema, table),\n  ) as ConditionalSchemaQuery<S>;\n}\n\nfunction createBuilderWithQueryFactory<S extends Schema>(\n  schema: S,\n  queryFactory: (table: keyof S['tables'] & string) => Query<string, S>,\n): SchemaQuery<S> {\n  // Create a target with no prototype so accessing unknown properties returns\n  // undefined instead of inherited Object.prototype methods (e.g., toString).\n  // This fixes React 19 dev mode compatibility where accessing $$typeof should\n  // return undefined rather than throwing.\n  const target = Object.assign(Object.create(null), schema.tables) as Record<\n    string,\n    unknown\n  >;\n\n  // No onMissing handler needed - unknown properties return undefined due to\n  // null prototype, which is the desired behavior for normal JS object semantics.\n  return recordProxy(target, (_tableSchema, prop) =>\n    queryFactory(prop),\n  ) as SchemaQuery<S>;\n}\n"],"names":[],"mappings":";;;AAWO,SAAS,cAAgC,QAA2B;AACzE,SAAO;AAAA,IAA8B;AAAA,IAAQ,CAAA,UAC3C,SAAS,QAAQ,KAAK;AAAA,EAAA;AAE1B;AAGO,SAAS,sBACd,UACA,QAC2B;AAC3B,MAAI,CAAC,OAAO,qBAAqB;AAC/B,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IAA8B;AAAA,IAAQ,CAAA,UAC3C,iBAAiB,UAAU,QAAQ,KAAK;AAAA,EAAA;AAE5C;AAEA,SAAS,8BACP,QACA,cACgB;AAKhB,QAAM,SAAS,OAAO,OAAO,uBAAO,OAAO,IAAI,GAAG,OAAO,MAAM;AAO/D,SAAO;AAAA,IAAY;AAAA,IAAQ,CAAC,cAAc,SACxC,aAAa,IAAI;AAAA,EAAA;AAErB;"}
+{"version":3,"file":"create-builder.js","names":[],"sources":["../../../../../zql/src/query/create-builder.ts"],"sourcesContent":["import {recordProxy} from '../../../shared/src/record-proxy.ts';\nimport type {Schema} from '../../../zero-types/src/schema.ts';\nimport type {QueryDelegate} from './query-delegate.ts';\nimport {newQuery} from './query-impl.ts';\nimport type {Query} from './query.ts';\nimport {newRunnableQuery} from './runnable-query-impl.ts';\nimport type {ConditionalSchemaQuery, SchemaQuery} from './schema-query.ts';\n\n/**\n * Returns a set of query builders for the given schema.\n */\nexport function createBuilder<S extends Schema>(schema: S): SchemaQuery<S> {\n  return createBuilderWithQueryFactory(schema, table =>\n    newQuery(schema, table),\n  );\n}\n\n/** @deprecated Use {@linkcode createBuilder} with `tx.run(zql.table.where(...))` instead. */\nexport function createRunnableBuilder<S extends Schema>(\n  delegate: QueryDelegate,\n  schema: S,\n): ConditionalSchemaQuery<S> {\n  if (!schema.enableLegacyQueries) {\n    return undefined as ConditionalSchemaQuery<S>;\n  }\n\n  return createBuilderWithQueryFactory(schema, table =>\n    newRunnableQuery(delegate, schema, table),\n  ) as ConditionalSchemaQuery<S>;\n}\n\nfunction createBuilderWithQueryFactory<S extends Schema>(\n  schema: S,\n  queryFactory: (table: keyof S['tables'] & string) => Query<string, S>,\n): SchemaQuery<S> {\n  // Create a target with no prototype so accessing unknown properties returns\n  // undefined instead of inherited Object.prototype methods (e.g., toString).\n  // This fixes React 19 dev mode compatibility where accessing $$typeof should\n  // return undefined rather than throwing.\n  const target = Object.assign(Object.create(null), schema.tables) as Record<\n    string,\n    unknown\n  >;\n\n  // No onMissing handler needed - unknown properties return undefined due to\n  // null prototype, which is the desired behavior for normal JS object semantics.\n  return recordProxy(target, (_tableSchema, prop) =>\n    queryFactory(prop),\n  ) as SchemaQuery<S>;\n}\n"],"mappings":";;;;;;;AAWA,SAAgB,cAAgC,QAA2B;AACzE,QAAO,8BAA8B,SAAQ,UAC3C,SAAS,QAAQ,MAAM,CACxB;;;AAIH,SAAgB,sBACd,UACA,QAC2B;AAC3B,KAAI,CAAC,OAAO,oBACV;AAGF,QAAO,8BAA8B,SAAQ,UAC3C,iBAAiB,UAAU,QAAQ,MAAM,CAC1C;;AAGH,SAAS,8BACP,QACA,cACgB;AAYhB,QAAO,YAPQ,OAAO,OAAO,OAAO,OAAO,KAAK,EAAE,OAAO,OAAO,GAOpC,cAAc,SACxC,aAAa,KAAK,CACnB"}

package/out/zql/src/query/error.js

@@ -1,13 +1,11 @@
-class QueryParseError extends Error {
-  constructor(opts) {
-    super(
-      opts?.cause instanceof Error ? `Failed to parse arguments for query: ${opts.cause.message}` : `Failed to parse arguments for query`,
-      opts
-    );
-    this.name = "QueryParseError";
-  }
-}
-export {
-  QueryParseError
+//#region ../zql/src/query/error.ts
+var QueryParseError = class extends Error {
+	constructor(opts) {
+		super(opts?.cause instanceof Error ? `Failed to parse arguments for query: ${opts.cause.message}` : `Failed to parse arguments for query`, opts);
+		this.name = "QueryParseError";
+	}
 };
-//# sourceMappingURL=error.js.map
+//#endregion
+export { QueryParseError };
+
+//# sourceMappingURL=error.js.map

package/out/zql/src/query/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sources":["../../../../../zql/src/query/error.ts"],"sourcesContent":["export class QueryParseError extends Error {\n  constructor(opts: ErrorOptions) {\n    super(\n      opts?.cause instanceof Error\n        ? `Failed to parse arguments for query: ${opts.cause.message}`\n        : `Failed to parse arguments for query`,\n      opts,\n    );\n    this.name = 'QueryParseError';\n  }\n}\n"],"names":[],"mappings":"AAAO,MAAM,wBAAwB,MAAM;AAAA,EACzC,YAAY,MAAoB;AAC9B;AAAA,MACE,MAAM,iBAAiB,QACnB,wCAAwC,KAAK,MAAM,OAAO,KAC1D;AAAA,MACJ;AAAA,IAAA;AAEF,SAAK,OAAO;AAAA,EACd;AACF;"}
+{"version":3,"file":"error.js","names":[],"sources":["../../../../../zql/src/query/error.ts"],"sourcesContent":["export class QueryParseError extends Error {\n  constructor(opts: ErrorOptions) {\n    super(\n      opts?.cause instanceof Error\n        ? `Failed to parse arguments for query: ${opts.cause.message}`\n        : `Failed to parse arguments for query`,\n      opts,\n    );\n    this.name = 'QueryParseError';\n  }\n}\n"],"mappings":";AAAA,IAAa,kBAAb,cAAqC,MAAM;CACzC,YAAY,MAAoB;AAC9B,QACE,MAAM,iBAAiB,QACnB,wCAAwC,KAAK,MAAM,YACnD,uCACJ,KACD;AACD,OAAK,OAAO"}

package/out/zql/src/query/escape-like.js

@@ -1,7 +1,8 @@
+//#region ../zql/src/query/escape-like.ts
 function escapeLike(val) {
-  return val.replace(/[%_]/g, "\\$&");
+	return val.replace(/[%_]/g, "\\$&");
 }
-export {
-  escapeLike
-};
-//# sourceMappingURL=escape-like.js.map
+//#endregion
+export { escapeLike };
+
+//# sourceMappingURL=escape-like.js.map

package/out/zql/src/query/escape-like.js.map

@@ -1 +1 @@
-{"version":3,"file":"escape-like.js","sources":["../../../../../zql/src/query/escape-like.ts"],"sourcesContent":["export function escapeLike(val: string) {\n  return val.replace(/[%_]/g, '\\\\$&');\n}\n"],"names":[],"mappings":"AAAO,SAAS,WAAW,KAAa;AACtC,SAAO,IAAI,QAAQ,SAAS,MAAM;AACpC;"}
+{"version":3,"file":"escape-like.js","names":[],"sources":["../../../../../zql/src/query/escape-like.ts"],"sourcesContent":["export function escapeLike(val: string) {\n  return val.replace(/[%_]/g, '\\\\$&');\n}\n"],"mappings":";AAAA,SAAgB,WAAW,KAAa;AACtC,QAAO,IAAI,QAAQ,SAAS,OAAO"}