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

package/out/packages/zql/src/mutate/custom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.js","names":[],"sources":["../../../../../../zql/src/mutate/custom.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport type {AST} from '../../../zero-protocol/src/ast.ts';\nimport type {\n  DefaultSchema,\n  DefaultWrappedTransaction,\n} from '../../../zero-types/src/default-types.ts';\nimport type {Schema} from '../../../zero-types/src/schema.ts';\nimport type {ServerSchema} from '../../../zero-types/src/server-schema.ts';\nimport type {Format} from '../ivm/view.ts';\nimport type {HumanReadable, Query, RunOptions} from '../query/query.ts';\nimport type {ConditionalSchemaQuery} from '../query/schema-query.ts';\nimport type {CRUDMutateRequest, SchemaCRUD, TransactionMutate} from './crud.ts';\n\ntype ClientID = string;\n\n/**\n * A base transaction interface that any Transaction<S, T> is assignable to.\n * Used in places where the schema type doesn't need to be preserved,\n * like the public signature of Mutator.fn.\n */\nexport interface AnyTransaction {\n  readonly location: Location;\n  readonly clientID: string;\n  readonly mutationID: number;\n  readonly reason: TransactionReason;\n}\n\nexport type Location = 'client' | 'server';\nexport type TransactionReason = 'optimistic' | 'rebase' | 'authoritative';\n\nexport interface TransactionBase<S extends Schema> {\n  readonly location: Location;\n  readonly clientID: ClientID;\n  /**\n   * The ID of the mutation that is being applied.\n   */\n  readonly mutationID: number;\n\n  /**\n   * The reason for the transaction.\n   */\n  readonly reason: TransactionReason;\n\n  readonly mutate: TransactionMutate<S>;\n  /**\n   * @deprecated Use {@linkcode createBuilder} with `tx.run(zql.table.where(...))` instead.\n   */\n  readonly query: ConditionalSchemaQuery<S>;\n\n  run<TTable extends keyof S['tables'] & string, TReturn>(\n    query: Query<TTable, S, TReturn>,\n    options?: RunOptions,\n  ): Promise<HumanReadable<TReturn>>;\n}\n\nexport type Transaction<\n  S extends Schema = DefaultSchema,\n  TWrappedTransaction = DefaultWrappedTransaction,\n> = ServerTransaction<S, TWrappedTransaction> | ClientTransaction<S>;\n\nexport interface ServerTransaction<\n  S extends Schema = DefaultSchema,\n  TWrappedTransaction = DefaultWrappedTransaction,\n> extends TransactionBase<S> {\n  readonly location: 'server';\n  readonly reason: 'authoritative';\n  readonly dbTransaction: DBTransaction<TWrappedTransaction>;\n}\n\n/**\n * An instance of this is passed to custom mutator implementations and\n * allows reading and writing to the database and IVM at the head at which the\n * mutator is being applied.\n */\nexport interface ClientTransaction<\n  S extends Schema = DefaultSchema,\n> extends TransactionBase<S> {\n  readonly location: 'client';\n  readonly reason: 'optimistic' | 'rebase';\n}\n\nexport interface Row {\n  [column: string]: unknown;\n}\n\nexport interface DBConnection<TWrappedTransaction> {\n  transaction: <T>(\n    cb: (tx: DBTransaction<TWrappedTransaction>) => Promise<T>,\n  ) => Promise<T>;\n}\n\nexport interface DBTransaction<T> extends Queryable {\n  readonly wrappedTransaction: T;\n  runQuery<TReturn>(\n    ast: AST,\n    format: Format,\n    schema: Schema,\n    serverSchema: ServerSchema,\n  ): Promise<HumanReadable<TReturn>>;\n}\n\ninterface Queryable {\n  query: (query: string, args: unknown[]) => Promise<Iterable<Row>>;\n}\n\n/**\n * A callable mutate shape with optional table helpers used by helper factories\n * like `makeMutateCRUD`. Transactions expose `SchemaCRUD` instead of this type.\n */\nexport type MutateCRUD<S extends Schema, AddSchemaCRUD extends boolean> = {\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  (request: CRUDMutateRequest<S, any, any, any>): Promise<void>;\n} & (AddSchemaCRUD extends true ? SchemaCRUD<S> : {});\n\nexport function customMutatorKey(sep: string, parts: string[]) {\n  for (const part of parts) {\n    assert(\n      !part.includes(sep),\n      `mutator names/namespaces must not include a ${sep}`,\n    );\n  }\n  return parts.join(sep);\n}\n"],"mappings":";;AAkHA,SAAgB,iBAAiB,KAAa,OAAiB;CAC7D,KAAK,MAAM,QAAQ,OACjB,OACE,CAAC,KAAK,SAAS,GAAG,GAClB,+CAA+C,KACjD;CAEF,OAAO,MAAM,KAAK,GAAG;AACvB"}

package/out/packages/zql/src/mutate/mutator-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutator-registry.js","names":[],"sources":["../../../../../../zql/src/mutate/mutator-registry.ts"],"sourcesContent":["import {\n  deepMerge,\n  isPlainObject,\n  type DeepMerge,\n} from '../../../shared/src/deep-merge.ts';\nimport type {ReadonlyJSONValue} from '../../../shared/src/json.ts';\nimport {\n  getValueAtPath,\n  iterateLeaves,\n} from '../../../shared/src/object-traversal.ts';\nimport type {\n  BaseDefaultSchema,\n  DefaultSchema,\n} from '../../../zero-types/src/default-types.ts';\nimport type {Schema} from '../../../zero-types/src/schema.ts';\nimport {validateInput} from '../query/validate-input.ts';\nimport type {Transaction} from './custom.ts';\nimport {\n  isMutator,\n  isMutatorDefinition,\n  type AnyMutator,\n  type AnyMutatorDefinition,\n  type MutateRequest,\n  type MutateRequestTypes,\n  type Mutator,\n  type MutatorDefinition,\n  type MutatorExecutionFunction,\n  type MutatorTypes,\n} from './mutator.ts';\n\n/**\n * Creates a MutatorRegistry from a tree of MutatorDefinitions,\n * optionally extending a base MutatorRegistry.\n *\n * @example\n * ```ts\n * // Create a new registry\n * const mutators = defineMutators({\n *   user: {\n *     create: defineMutator(...),\n *     delete: defineMutator(...),\n *   },\n *   post: {\n *     publish: defineMutator(...),\n *   },\n * });\n *\n * // Extend an existing registry (e.g., for server-side overrides)\n * const serverMutators = defineMutators(mutators, {\n *   user: {\n *     create: defineMutator(...),  // overrides mutators.user.create\n *   },\n *   // post.publish is inherited from mutators\n * });\n *\n * // Access mutators by path\n * const mr = mutators.user.create({name: 'Alice'});\n *\n * // Execute on client\n * zero.mutate(mr);\n *\n * // Execute on server\n * mr.mutator.fn({tx, ctx, args: mr.args});\n *\n * // Lookup by name (for server-side dispatch)\n * const mutator = getMutator(mutators, 'user.create');\n * ```\n */\nexport function defineMutators<\n  // let MD infer freely so defaults aren't erased by a MutatorDefinitions constraint\n  const MD,\n  S extends BaseDefaultSchema = DefaultSchema,\n>(\n  // we assert types here for clear error messages\n  definitions: MD & AssertMutatorDefinitions<MD>,\n): MutatorRegistry<EnsureMutatorDefinitions<MD>, S>;\n\nexport function defineMutators<\n  // same as MD above, but for TBase and TOverrides\n  const TBase,\n  const TOverrides,\n  S extends BaseDefaultSchema = DefaultSchema,\n>(\n  base:\n    | MutatorRegistry<EnsureMutatorDefinitions<TBase>, S>\n    | (TBase & AssertMutatorDefinitions<TBase>),\n  overrides: TOverrides & AssertMutatorDefinitions<TOverrides>,\n): MutatorRegistry<\n  DeepMerge<\n    EnsureMutatorDefinitions<TBase>,\n    EnsureMutatorDefinitions<TOverrides>,\n    AnyMutatorDefinition\n  >,\n  S\n>;\n\nexport function defineMutators(\n  definitionsOrBase: MutatorDefinitions | AnyMutatorRegistry,\n  maybeOverrides?: MutatorDefinitions,\n): AnyMutatorRegistry {\n  function processDefinitions(\n    definitions: MutatorDefinitions,\n    path: string[],\n  ): Record<string | symbol, unknown> {\n    const result: Record<string | symbol, unknown> = {\n      ['~']: 'MutatorRegistry',\n    };\n\n    for (const [key, value] of Object.entries(definitions)) {\n      path.push(key);\n      const name = path.join('.');\n\n      if (isMutatorDefinition(value)) {\n        result[key] = createMutator(name, value);\n      } else {\n        // Nested definitions\n        result[key] = processDefinitions(value, path);\n      }\n      path.pop();\n    }\n\n    return result;\n  }\n\n  if (maybeOverrides !== undefined) {\n    // Merge base and overrides\n    let base: Record<string | symbol, unknown>;\n    if (!isMutatorRegistry(definitionsOrBase)) {\n      base = processDefinitions(definitionsOrBase, []);\n    } else {\n      base = definitionsOrBase;\n    }\n\n    const processed = processDefinitions(maybeOverrides, []);\n\n    const merged = deepMerge(base, processed, isMutatorLeaf);\n    merged['~'] = 'MutatorRegistry';\n    return merged as AnyMutatorRegistry;\n  }\n\n  return processDefinitions(\n    definitionsOrBase as MutatorDefinitions,\n    [],\n  ) as AnyMutatorRegistry;\n}\n\nconst isMutatorLeaf = (value: unknown): boolean =>\n  !isPlainObject(value) || isMutator(value);\n\n/**\n * Creates a function that can be used to define mutators with a specific schema.\n */\nexport function defineMutatorsWithType<\n  TSchema extends Schema,\n>(): TypedDefineMutators<TSchema> {\n  return defineMutators;\n}\n\n/**\n * The return type of defineMutatorsWithType. A function matching the\n * defineMutators overloads but with Schema pre-bound.\n */\ntype TypedDefineMutators<S extends Schema> = {\n  // Single definitions\n  <MD>(\n    definitions: MD & AssertMutatorDefinitions<MD>,\n  ): MutatorRegistry<EnsureMutatorDefinitions<MD>, S>;\n\n  // Base and overrides\n  <TBase, TOverrides>(\n    base:\n      | MutatorRegistry<EnsureMutatorDefinitions<TBase>, S>\n      | (TBase & AssertMutatorDefinitions<TBase>),\n    overrides: TOverrides,\n  ): MutatorRegistry<\n    DeepMerge<\n      EnsureMutatorDefinitions<TBase>,\n      EnsureMutatorDefinitions<TOverrides>,\n      AnyMutatorDefinition\n    >,\n    S\n  >;\n};\n\nexport type AssertMutatorDefinitions<MD> = MD extends MutatorDefinitions\n  ? unknown\n  : never;\n\nexport type EnsureMutatorDefinitions<MD> = MD extends MutatorDefinitions\n  ? MD\n  : never;\n\n/**\n * Checks if a value is a MutatorRegistry.\n */\nexport function isMutatorRegistry(value: unknown): value is AnyMutatorRegistry {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as Record<string, unknown>)['~'] === 'MutatorRegistry'\n  );\n}\n\nexport type MutatorRegistryTypes<TSchema extends Schema> = 'MutatorRegistry' & {\n  readonly $schema: TSchema;\n};\n\n/**\n * The result of defineMutators(). A tree of Mutators with a tag for detection.\n */\nexport type MutatorRegistry<\n  MD extends MutatorDefinitions,\n  TSchema extends Schema,\n> = ToMutatorTree<MD, TSchema> & {\n  ['~']: MutatorRegistryTypes<TSchema>;\n};\n\n/**\n * A branded type for use in type constraints. Use this instead of\n * `MutatorRegistry<S, C, any>` to avoid TypeScript drilling into\n * the complex ToMutatorTree structure and hitting variance issues.\n */\nexport type AnyMutatorRegistry = {\n  ['~']: MutatorRegistryTypes<Schema>;\n  [key: string]: unknown;\n};\n\n/**\n * Transforms a MutatorDefinitions into a tree of Mutators.\n * Each MutatorDefinition becomes a Mutator at the same path.\n * Uses TInput for the callable args (TOutput is only used internally for validation).\n */\nexport type ToMutatorTree<\n  MD extends MutatorDefinitions,\n  TSchema extends Schema,\n> = {\n  readonly [K in keyof MD]: MD[K] extends AnyMutatorDefinition\n    ? // pull types from the phantom property\n      Mutator<\n        MD[K]['~']['$input'],\n        TSchema,\n        MD[K]['~']['$context'],\n        MD[K]['~']['$wrappedTransaction']\n      >\n    : MD[K] extends MutatorDefinitions\n      ? ToMutatorTree<MD[K], TSchema>\n      : never;\n};\n\nexport type FromMutatorTree<\n  MD extends MutatorDefinitions,\n  TSchema extends Schema,\n> = {\n  readonly [K in keyof MD]: MD[K] extends AnyMutatorDefinition\n    ? // pull types from the phantom property\n      Mutator<\n        ReadonlyJSONValue | undefined, // intentionally left as generic to avoid variance issues\n        TSchema,\n        MD[K]['~']['$context'],\n        MD[K]['~']['$wrappedTransaction']\n      >\n    : MD[K] extends MutatorDefinitions\n      ? FromMutatorTree<MD[K], TSchema>\n      : never;\n}[keyof MD];\n\n/**\n * A tree of MutatorDefinitions, possibly nested.\n */\nexport type MutatorDefinitions = {\n  readonly [key: string]: AnyMutatorDefinition | MutatorDefinitions;\n};\n\nfunction createMutator<\n  ArgsInput extends ReadonlyJSONValue | undefined,\n  ArgsOutput extends ReadonlyJSONValue | undefined,\n  TSchema extends Schema,\n  C,\n  TWrappedTransaction,\n>(\n  name: string,\n  definition: MutatorDefinition<ArgsInput, ArgsOutput, C, TWrappedTransaction>,\n): Mutator<ArgsInput, TSchema, C, TWrappedTransaction> {\n  const {validator} = definition;\n\n  // fn takes ReadonlyJSONValue args because it's called during rebase (from\n  // stored JSON) and on the server (from wire format). Validation happens here.\n  const fn: MutatorExecutionFunction<\n    ArgsInput,\n    C,\n    Transaction<TSchema, TWrappedTransaction>\n  > = async options => {\n    const validatedArgs = validator\n      ? validateInput(name, options.args, validator, 'mutator')\n      : (options.args as unknown as ArgsOutput);\n    await definition.fn({\n      args: validatedArgs,\n      ctx: options.ctx as C,\n      tx: options.tx,\n    });\n  };\n\n  const mutator = (\n    args: ArgsInput,\n  ): MutateRequest<ArgsInput, TSchema, C, TWrappedTransaction> => ({\n    args,\n    '~': 'MutateRequest' as MutateRequestTypes<\n      ArgsInput,\n      TSchema,\n      C,\n      TWrappedTransaction\n    >,\n    'mutator': mutator as unknown as Mutator<\n      ArgsInput,\n      TSchema,\n      C,\n      TWrappedTransaction\n    >,\n  });\n\n  mutator.mutatorName = name;\n  mutator.fn = fn;\n  mutator['~'] = 'Mutator' as unknown as MutatorTypes<\n    ArgsInput,\n    TSchema,\n    C,\n    TWrappedTransaction\n  >;\n\n  return mutator as unknown as Mutator<\n    ArgsInput,\n    TSchema,\n    C,\n    TWrappedTransaction\n  >;\n}\n\nexport function* iterateMutators(\n  registry: AnyMutatorRegistry,\n): Iterable<AnyMutator> {\n  yield* iterateLeaves(registry, isMutator);\n}\n\n/**\n * Gets a Mutator by its dot-separated name from a MutatorRegistry.\n * Returns undefined if not found.\n */\nexport function getMutator<\n  MD extends MutatorDefinitions,\n  TSchema extends Schema,\n>(\n  registry: MutatorRegistry<MD, TSchema>,\n  name: string,\n): FromMutatorTree<MD, TSchema> | undefined {\n  const m = getValueAtPath(registry, name, '.');\n  return m as FromMutatorTree<MD, TSchema> | undefined;\n}\n\n/**\n * Gets a Mutator by its dot-separated name from a MutatorRegistry.\n * Throws if not found.\n */\nexport function mustGetMutator<\n  MD extends MutatorDefinitions,\n  TSchema extends Schema,\n>(\n  registry: MutatorRegistry<MD, TSchema>,\n  name: string,\n): FromMutatorTree<MD, TSchema> {\n  const mutator = getMutator(registry, name);\n  if (mutator === undefined) {\n    throw new Error(`Mutator not found: ${name}`);\n  }\n  return mutator;\n}\n"],"mappings":";;;;;AAgGA,SAAgB,eACd,mBACA,gBACoB;CACpB,SAAS,mBACP,aACA,MACkC;EAClC,MAAM,SAA2C,GAC9C,MAAM,kBACT;EAEA,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,WAAW,GAAG;GACtD,KAAK,KAAK,GAAG;GACb,MAAM,OAAO,KAAK,KAAK,GAAG;GAE1B,IAAI,oBAAoB,KAAK,GAC3B,OAAO,OAAO,cAAc,MAAM,KAAK;QAGvC,OAAO,OAAO,mBAAmB,OAAO,IAAI;GAE9C,KAAK,IAAI;EACX;EAEA,OAAO;CACT;CAEA,IAAI,mBAAmB,KAAA,GAAW;EAEhC,IAAI;EACJ,IAAI,CAAC,kBAAkB,iBAAiB,GACtC,OAAO,mBAAmB,mBAAmB,CAAC,CAAC;OAE/C,OAAO;EAGT,MAAM,YAAY,mBAAmB,gBAAgB,CAAC,CAAC;EAEvD,MAAM,SAAS,UAAU,MAAM,WAAW,aAAa;EACvD,OAAO,OAAO;EACd,OAAO;CACT;CAEA,OAAO,mBACL,mBACA,CAAC,CACH;AACF;AAEA,IAAM,iBAAiB,UACrB,CAAC,cAAc,KAAK,KAAK,UAAU,KAAK;;;;AAK1C,SAAgB,yBAEkB;CAChC,OAAO;AACT;;;;AAuCA,SAAgB,kBAAkB,OAA6C;CAC7E,OACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAkC,SAAS;AAEhD;AAwEA,SAAS,cAOP,MACA,YACqD;CACrD,MAAM,EAAC,cAAa;CAIpB,MAAM,KAIF,OAAM,YAAW;EACnB,MAAM,gBAAgB,YAClB,cAAc,MAAM,QAAQ,MAAM,WAAW,SAAS,IACrD,QAAQ;EACb,MAAM,WAAW,GAAG;GAClB,MAAM;GACN,KAAK,QAAQ;GACb,IAAI,QAAQ;EACd,CAAC;CACH;CAEA,MAAM,WACJ,UAC+D;EAC/D;EACA,KAAK;EAML,WAAW;CAMb;CAEA,QAAQ,cAAc;CACtB,QAAQ,KAAK;CACb,QAAQ,OAAO;CAOf,OAAO;AAMT;AAEA,UAAiB,gBACf,UACsB;CACtB,OAAO,cAAc,UAAU,SAAS;AAC1C;;;;;AAMA,SAAgB,WAId,UACA,MAC0C;CAE1C,OADU,eAAe,UAAU,MAAM,GAClC;AACT;;;;;AAMA,SAAgB,eAId,UACA,MAC8B;CAC9B,MAAM,UAAU,WAAW,UAAU,IAAI;CACzC,IAAI,YAAY,KAAA,GACd,MAAM,IAAI,MAAM,sBAAsB,MAAM;CAE9C,OAAO;AACT"}

package/out/packages/zql/src/mutate/mutator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutator.js","names":[],"sources":["../../../../../../zql/src/mutate/mutator.ts"],"sourcesContent":["import type {StandardSchemaV1} from '@standard-schema/spec';\nimport type {ReadonlyJSONValue} from '../../../shared/src/json.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport type {\n  DefaultContext,\n  DefaultSchema,\n  DefaultWrappedTransaction,\n  IsUnknown,\n} from '../../../zero-types/src/default-types.ts';\nimport type {Schema} from '../../../zero-types/src/schema.ts';\nimport type {AnyTransaction, Transaction} from './custom.ts';\n\n// ----------------------------------------------------------------------------\n// defineMutator\n// ----------------------------------------------------------------------------\n\nexport type MutatorDefinitionTypes<\n  TInput extends ReadonlyJSONValue | undefined,\n  TOutput,\n  TContext,\n  TWrappedTransaction,\n> = 'MutatorDefinition' & {\n  readonly $input: TInput;\n  readonly $output: TOutput;\n  readonly $context: TContext;\n  readonly $wrappedTransaction: TWrappedTransaction;\n};\n\nexport type MutatorDefinition<\n  TInput extends ReadonlyJSONValue | undefined,\n  TOutput extends ReadonlyJSONValue | undefined,\n  TContext = DefaultContext,\n  TWrappedTransaction = DefaultWrappedTransaction,\n> = {\n  readonly 'fn': MutatorDefinitionFunction<TOutput, TContext, AnyTransaction>;\n  readonly 'validator': StandardSchemaV1<TInput, TOutput> | undefined;\n  readonly '~': MutatorDefinitionTypes<\n    TInput,\n    TOutput,\n    TContext,\n    TWrappedTransaction\n  >;\n};\n\n// oxlint-disable-next-line no-explicit-any\nexport type AnyMutatorDefinition = MutatorDefinition<any, any, any, any>;\n\nexport function isMutatorDefinition(f: unknown): f is AnyMutatorDefinition {\n  return (\n    typeof f === 'object' &&\n    f !== null &&\n    (f as {['~']?: unknown})['~'] === 'MutatorDefinition'\n  );\n}\n\n// Overload for no validator\nexport function defineMutator<\n  TInput extends ReadonlyJSONValue | undefined = ReadonlyJSONValue | undefined,\n  TSchema extends Schema = DefaultSchema,\n  TContext = DefaultContext,\n  TWrappedTransaction = DefaultWrappedTransaction,\n>(\n  mutator: MutatorDefinitionFunction<\n    TInput,\n    TContext,\n    Transaction<TSchema, TWrappedTransaction>\n  >,\n): MutatorDefinition<TInput, TInput, TContext, TWrappedTransaction>;\n\n// Overload for validator\nexport function defineMutator<\n  TInput extends ReadonlyJSONValue | undefined = undefined,\n  TOutput extends ReadonlyJSONValue | undefined = TInput,\n  TSchema extends Schema = DefaultSchema,\n  TContext = DefaultContext,\n  TWrappedTransaction = DefaultWrappedTransaction,\n>(\n  validator: StandardSchemaV1<TInput, TOutput>,\n  mutator: MutatorDefinitionFunction<\n    TOutput,\n    TContext,\n    Transaction<TSchema, TWrappedTransaction>\n  >,\n): MutatorDefinition<TInput, TOutput, TContext, TWrappedTransaction>;\n\n// Implementation\nexport function defineMutator<\n  TInput extends ReadonlyJSONValue | undefined = undefined,\n  TOutput extends ReadonlyJSONValue | undefined = TInput,\n  TSchema extends Schema = DefaultSchema,\n  TContext = DefaultContext,\n  TWrappedTransaction = DefaultWrappedTransaction,\n>(\n  validatorOrMutator:\n    | StandardSchemaV1<TInput, TOutput>\n    | MutatorDefinitionFunction<\n        TOutput,\n        TContext,\n        Transaction<TSchema, TWrappedTransaction>\n      >,\n  mutator?: MutatorDefinitionFunction<\n    TOutput,\n    TContext,\n    Transaction<TSchema, TWrappedTransaction>\n  >,\n): MutatorDefinition<TInput, TOutput, TContext, TWrappedTransaction> {\n  let validator: StandardSchemaV1<TInput, TOutput> | undefined;\n  let actualMutator: MutatorDefinitionFunction<\n    TOutput,\n    TContext,\n    Transaction<TSchema, TWrappedTransaction>\n  >;\n\n  if ('~standard' in validatorOrMutator) {\n    // defineMutator(validator, mutator)\n    validator = validatorOrMutator;\n    actualMutator = must(mutator);\n  } else {\n    // defineMutator(mutator) - no validator\n    validator = undefined;\n    actualMutator = validatorOrMutator;\n  }\n\n  const mutatorDefinition: MutatorDefinition<\n    TInput,\n    TOutput,\n    TContext,\n    TWrappedTransaction\n  > = {\n    'fn': actualMutator as MutatorDefinitionFunction<\n      TOutput,\n      TContext,\n      AnyTransaction\n    >,\n    'validator': validator,\n    '~': 'MutatorDefinition' as unknown as MutatorDefinitionTypes<\n      TInput,\n      TOutput,\n      TContext,\n      TWrappedTransaction\n    >,\n  };\n  return mutatorDefinition;\n}\n\n// intentionally not using DefaultSchema, DefaultContext, or DefaultWrappedTransaction\nexport function defineMutatorWithType<\n  TSchema extends Schema,\n  TContext = unknown,\n  TWrappedTransaction = unknown,\n>(): TypedDefineMutator<TSchema, TContext, TWrappedTransaction> {\n  return defineMutator;\n}\n\n/**\n * The return type of defineMutatorWithType. A function matching the\n * defineMutator overloads but with Schema, Context, and WrappedTransaction\n * pre-bound.\n *\n * This is used as a workaround to using DefaultTypes (e.g. when using\n * multiple Zero instances).\n */\ntype TypedDefineMutator<\n  TSchema extends Schema,\n  TContext,\n  TWrappedTransaction,\n> = {\n  // Without validator\n  <TArgs extends ReadonlyJSONValue | undefined>(\n    mutator: MutatorDefinitionFunction<\n      TArgs,\n      TContext,\n      Transaction<TSchema, TWrappedTransaction>\n    >,\n  ): MutatorDefinition<TArgs, TArgs, TContext, TWrappedTransaction>;\n\n  // With validator\n  <\n    TInput extends ReadonlyJSONValue | undefined,\n    TOutput extends ReadonlyJSONValue | undefined,\n  >(\n    validator: StandardSchemaV1<TInput, TOutput>,\n    mutator: MutatorDefinitionFunction<\n      TOutput,\n      TContext,\n      Transaction<TSchema, TWrappedTransaction>\n    >,\n  ): MutatorDefinition<TInput, TOutput, TContext, TWrappedTransaction>;\n};\n\nexport type MutatorDefinitionFunction<\n  TOutput extends ReadonlyJSONValue | undefined,\n  TContext,\n  TTransaction,\n> = (options: {\n  args: TOutput;\n  ctx: TContext;\n  tx: TTransaction;\n}) => Promise<void>;\n\nexport type MutatorExecutionFunction<\n  TOutput extends ReadonlyJSONValue | undefined,\n  TContext,\n  TTransaction,\n> = (\n  options: MutatorExecutionOptions<TOutput, TContext, TTransaction>,\n) => Promise<void>;\n\ntype MutatorExecutionOptions<\n  TOutput extends ReadonlyJSONValue | undefined,\n  TContext,\n  TTransaction,\n> = undefined extends TOutput\n  ? IsUnknown<TContext> extends true\n    ? {args?: TOutput | undefined; tx: TTransaction; ctx?: TContext | undefined}\n    : {args?: TOutput | undefined; tx: TTransaction; ctx: TContext}\n  : IsUnknown<TContext> extends true\n    ? {args: TOutput; tx: TTransaction; ctx?: TContext | undefined}\n    : {args: TOutput; tx: TTransaction; ctx: TContext};\n\n// ----------------------------------------------------------------------------\n// Mutator and MutateRequest types\n// ----------------------------------------------------------------------------\n\nexport type MutatorTypes<\n  TInput extends ReadonlyJSONValue | undefined,\n  TSchema extends Schema,\n  TContext,\n  TWrappedTransaction,\n> = 'Mutator' & {\n  readonly $input: TInput;\n  readonly $schema: TSchema;\n  readonly $context: TContext;\n  readonly $wrappedTransaction: TWrappedTransaction;\n};\n\n/**\n * A callable wrapper around a MutatorDefinition, created by `defineMutators()`.\n *\n * Accessed like `mutators.foo.bar`, and called to create a MutateRequest:\n * `mutators.foo.bar(42)` returns a `MutateRequest`.\n *\n * The `fn` property is used for execution and takes raw JSON args (for rebase\n * and server wire format cases) that are validated internally.\n */\nexport type Mutator<\n  TInput extends ReadonlyJSONValue | undefined,\n  TSchema extends Schema = DefaultSchema,\n  TContext = DefaultContext,\n  TWrappedTransaction = DefaultWrappedTransaction,\n> = {\n  readonly 'mutatorName': string;\n  /**\n   * Execute the mutation. Args are ReadonlyJSONValue because this is called\n   * during rebase (from stored JSON) and on the server (from wire format).\n   * Validation happens internally before the recipe function runs.\n   */\n  readonly 'fn': MutatorExecutionFunction<\n    TInput,\n    TContext,\n    Transaction<TSchema, TWrappedTransaction>\n  >;\n  readonly '~': MutatorTypes<TInput, TSchema, TContext, TWrappedTransaction>;\n} & MutatorCallable<TInput, TSchema, TContext, TWrappedTransaction>;\n\n// Helper type for the callable part of Mutator\n// When TInput is undefined, the function is callable with 0 args\n// When TInput includes undefined (optional), args is optional\n// Otherwise, args is required\ntype MutatorCallable<\n  TInput extends ReadonlyJSONValue | undefined,\n  TSchema extends Schema,\n  TContext,\n  TWrappedTransaction,\n> = [TInput] extends [undefined]\n  ? () => MutateRequest<TInput, TSchema, TContext, TWrappedTransaction>\n  : undefined extends TInput\n    ? {\n        (): MutateRequest<TInput, TSchema, TContext, TWrappedTransaction>;\n        (\n          args?: TInput,\n        ): MutateRequest<TInput, TSchema, TContext, TWrappedTransaction>;\n      }\n    : {\n        (\n          args: TInput,\n        ): MutateRequest<TInput, TSchema, TContext, TWrappedTransaction>;\n      };\n\n// oxlint-disable-next-line no-explicit-any\nexport type AnyMutator = Mutator<any, any, any, any>;\n\n/**\n * Checks if a value is a Mutator (the result of processing a MutatorDefinition\n * through defineMutators).\n */\nexport function isMutator<S extends Schema>(\n  value: unknown,\n  // oxlint-disable-next-line no-explicit-any\n): value is Mutator<any, S, any, any> {\n  return (\n    typeof value === 'function' &&\n    typeof (value as {mutatorName?: unknown}).mutatorName === 'string' &&\n    typeof (value as {fn?: unknown}).fn === 'function'\n  );\n}\n\nexport type MutateRequestTypes<\n  TInput extends ReadonlyJSONValue | undefined,\n  TSchema extends Schema,\n  TContext,\n  TWrappedTransaction,\n> = 'MutateRequest' & {\n  readonly $input: TInput;\n  readonly $schema: TSchema;\n  readonly $context: TContext;\n  readonly $wrappedTransaction: TWrappedTransaction;\n};\n\n/**\n * The result of calling a Mutator with arguments.\n *\n * Created by `mutators.foo.bar(42)`, executed by `zero.mutate(mr)` on the client\n * or `mr.mutator.fn({tx, ctx, args: mr.args})` on the server.\n */\nexport type MutateRequest<\n  TInput extends ReadonlyJSONValue | undefined,\n  TSchema extends Schema = DefaultSchema,\n  TContext = DefaultContext,\n  TWrappedTransaction = DefaultWrappedTransaction,\n> = {\n  readonly 'mutator': Mutator<TInput, TSchema, TContext, TWrappedTransaction>;\n  readonly 'args': TInput;\n  readonly '~': MutateRequestTypes<\n    TInput,\n    TSchema,\n    TContext,\n    TWrappedTransaction\n  >;\n};\n"],"mappings":";;AA+CA,SAAgB,oBAAoB,GAAuC;CACzE,OACE,OAAO,MAAM,YACb,MAAM,QACL,EAAwB,SAAS;AAEtC;AAiCA,SAAgB,cAOd,oBAOA,SAKmE;CACnE,IAAI;CACJ,IAAI;CAMJ,IAAI,eAAe,oBAAoB;EAErC,YAAY;EACZ,gBAAgB,KAAK,OAAO;CAC9B,OAAO;EAEL,YAAY,KAAA;EACZ,gBAAgB;CAClB;CAqBA,OAAO;EAbL,MAAM;EAKN,aAAa;EACb,KAAK;CAOA;AACT;AAGA,SAAgB,wBAIgD;CAC9D,OAAO;AACT;;;;;AAgJA,SAAgB,UACd,OAEoC;CACpC,OACE,OAAO,UAAU,cACjB,OAAQ,MAAkC,gBAAgB,YAC1D,OAAQ,MAAyB,OAAO;AAE5C"}

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

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

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

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

package/out/packages/zql/src/planner/planner-constraint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-constraint.js","names":[],"sources":["../../../../../../zql/src/planner/planner-constraint.ts"],"sourcesContent":["/**\n * We do not know the value a constraint will take until runtime.\n *\n * However, we do know the column.\n *\n * E.g., we know that `issue.assignee_id` will be constrained to typeof issue.assignee_id.\n */\nexport type PlannerConstraint = Record<string, undefined>;\n\n/**\n * Multiple flipped joins will contribute extra constraints to a parent join.\n * These need to be merged.\n */\nexport function mergeConstraints(\n  a: PlannerConstraint | undefined,\n  b: PlannerConstraint | undefined,\n): PlannerConstraint | undefined {\n  if (!a) return b;\n  if (!b) return a;\n  return {...a, ...b};\n}\n"],"mappings":";;;;;AAaA,SAAgB,iBACd,GACA,GAC+B;CAC/B,IAAI,CAAC,GAAG,OAAO;CACf,IAAI,CAAC,GAAG,OAAO;CACf,OAAO;EAAC,GAAG;EAAG,GAAG;CAAC;AACpB"}

package/out/packages/zql/src/planner/planner-debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-debug.js","names":[],"sources":["../../../../../../zql/src/planner/planner-debug.ts"],"sourcesContent":["import type * as v from '../../../shared/src/valita.ts';\nimport type {\n  attemptStartEventJSONSchema,\n  bestPlanSelectedEventJSONSchema,\n  connectionSelectedEventJSONSchema,\n  nodeConstraintEventJSONSchema,\n  PlanDebugEventJSON,\n  planFailedEventJSONSchema,\n} from '../../../zero-protocol/src/analyze-query-result.ts';\nimport type {\n  Condition,\n  Ordering,\n  ValuePosition,\n} from '../../../zero-protocol/src/ast.ts';\nimport type {PlannerConstraint} from './planner-constraint.ts';\nimport type {PlanState} from './planner-graph.ts';\nimport type {CostEstimate, JoinType} from './planner-node.ts';\n\n/**\n * Structured debug events emitted during query planning.\n * These events can be accumulated, printed, or analyzed to understand\n * the planner's decision-making process.\n */\n\n/**\n * Starting a new planning attempt with a different root connection.\n */\nexport type AttemptStartEvent = v.Infer<typeof attemptStartEventJSONSchema>;\n\n/**\n * Snapshot of connection costs before selecting the next connection.\n */\nexport type ConnectionCostsEvent = {\n  type: 'connection-costs';\n  attemptNumber: number;\n  costs: Array<{\n    connection: string;\n    cost: number;\n    costEstimate: Omit<CostEstimate, 'fanout'>;\n    pinned: boolean;\n    constraints: Record<string, PlannerConstraint | undefined>;\n    constraintCosts: Record<string, Omit<CostEstimate, 'fanout'>>;\n  }>;\n};\n\n/**\n * A connection was chosen and pinned.\n */\nexport type ConnectionSelectedEvent = v.Infer<\n  typeof connectionSelectedEventJSONSchema\n>;\n\n/**\n * Constraints have been propagated through the graph.\n */\nexport type ConstraintsPropagatedEvent = {\n  type: 'constraints-propagated';\n  attemptNumber: number;\n  connectionConstraints: Array<{\n    connection: string;\n    constraints: Record<string, PlannerConstraint | undefined>;\n    constraintCosts: Record<string, Omit<CostEstimate, 'fanout'>>;\n  }>;\n};\n\n/**\n * A complete plan was found for this attempt.\n */\nexport type PlanCompleteEvent = {\n  type: 'plan-complete';\n  attemptNumber: number;\n  totalCost: number;\n  flipPattern: number; // Bitmask indicating which joins are flipped\n  joinStates: Array<{\n    join: string;\n    type: JoinType;\n  }>;\n  // Planning snapshot that can be restored and applied to AST\n  planSnapshot: PlanState;\n};\n\n/**\n * Planning attempt failed (e.g., unflippable join).\n */\nexport type PlanFailedEvent = v.Infer<typeof planFailedEventJSONSchema>;\n\n/**\n * The best plan across all attempts was selected.\n */\nexport type BestPlanSelectedEvent = v.Infer<\n  typeof bestPlanSelectedEventJSONSchema\n>;\n\n/**\n * A node computed its cost estimate during planning.\n * Emitted by nodes during estimateCost() traversal.\n * attemptNumber is added by the debugger.\n */\nexport type NodeCostEvent = {\n  type: 'node-cost';\n  attemptNumber?: number;\n  nodeType: 'connection' | 'join' | 'fan-out' | 'fan-in' | 'terminus';\n  node: string;\n  branchPattern: number[];\n  downstreamChildSelectivity: number;\n  costEstimate: Omit<CostEstimate, 'fanout'>;\n  filters?: Condition | undefined; // Only for connections\n  ordering?: Ordering | undefined; // Only for connections\n  joinType?: JoinType | undefined; // Only for joins\n};\n\n/**\n * A node received constraints during constraint propagation.\n * Emitted by nodes during propagateConstraints() traversal.\n * attemptNumber is added by the debugger.\n */\nexport type NodeConstraintEvent = v.Infer<typeof nodeConstraintEventJSONSchema>;\n\n/**\n * Union of all debug event types.\n */\nexport type PlanDebugEvent =\n  | AttemptStartEvent\n  | ConnectionCostsEvent\n  | ConnectionSelectedEvent\n  | ConstraintsPropagatedEvent\n  | PlanCompleteEvent\n  | PlanFailedEvent\n  | BestPlanSelectedEvent\n  | NodeCostEvent\n  | NodeConstraintEvent;\n\n/**\n * Interface for objects that receive debug events during planning.\n */\nexport interface PlanDebugger {\n  log(event: PlanDebugEvent): void;\n}\n\n/**\n * Simple accumulator debugger that stores all events.\n * Useful for tests and debugging.\n */\nexport class AccumulatorDebugger implements PlanDebugger {\n  readonly events: PlanDebugEvent[] = [];\n  private currentAttempt = 0;\n\n  log(event: PlanDebugEvent): void {\n    // Track current attempt number\n    if (event.type === 'attempt-start') {\n      this.currentAttempt = event.attemptNumber;\n    }\n\n    // Add attempt number to node events\n    if (event.type === 'node-cost' || event.type === 'node-constraint') {\n      (event as NodeCostEvent | NodeConstraintEvent).attemptNumber =\n        this.currentAttempt;\n    }\n\n    this.events.push(event);\n  }\n\n  /**\n   * Get all events of a specific type.\n   */\n  getEvents<T extends PlanDebugEvent['type']>(\n    type: T,\n  ): Extract<PlanDebugEvent, {type: T}>[] {\n    return this.events.filter(e => e.type === type) as Extract<\n      PlanDebugEvent,\n      {type: T}\n    >[];\n  }\n\n  /**\n   * Format events as a human-readable string.\n   */\n  format(): string {\n    return formatPlannerEvents(this.events);\n  }\n}\n\n/**\n * Format a constraint object as a human-readable string.\n */\nfunction formatConstraint(\n  constraint: PlannerConstraint | Record<string, unknown> | null | undefined,\n): string {\n  if (!constraint) return '{}';\n  const keys = Object.keys(constraint);\n  if (keys.length === 0) return '{}';\n  return '{' + keys.join(', ') + '}';\n}\n\n/**\n * Format a ValuePosition (column, literal, or static parameter) as a human-readable string.\n */\nfunction formatValuePosition(value: ValuePosition): string {\n  switch (value.type) {\n    case 'column':\n      return value.name;\n    case 'literal':\n      // Format literal values with SQL-style quoting for strings\n      if (typeof value.value === 'string') {\n        return `'${value.value}'`;\n      }\n      return JSON.stringify(value.value);\n    case 'static':\n      return `@${value.anchor}.${Array.isArray(value.field) ? value.field.join('.') : value.field}`;\n  }\n}\n\n/**\n * Format a Condition (filter) as a human-readable string.\n */\nfunction formatFilter(filter: Condition | undefined): string {\n  if (!filter) return 'none';\n\n  switch (filter.type) {\n    case 'simple':\n      return `${formatValuePosition(filter.left)} ${filter.op} ${formatValuePosition(filter.right)}`;\n    case 'and':\n      return `(${filter.conditions.map(formatFilter).join(' AND ')})`;\n    case 'or':\n      return `(${filter.conditions.map(formatFilter).join(' OR ')})`;\n    case 'correlatedSubquery':\n      return `EXISTS(${filter.related.subquery.table})`;\n    default:\n      return JSON.stringify(filter);\n  }\n}\n\n/**\n * Format an Ordering as a human-readable string.\n */\nfunction formatOrdering(ordering: Ordering | undefined): string {\n  if (!ordering || ordering.length === 0) return 'none';\n  return ordering\n    .map(([field, direction]) => `${field} ${direction}`)\n    .join(', ');\n}\n\n/**\n * Format a compact summary for a single planning attempt.\n */\nfunction formatAttemptSummary(\n  attemptNum: number,\n  events: (PlanDebugEvent | PlanDebugEventJSON)[],\n): string[] {\n  const lines: string[] = [];\n\n  // Find the attempt-start event to get total attempts\n  const startEvent = events.find(e => e.type === 'attempt-start') as\n    | AttemptStartEvent\n    | undefined;\n  const totalAttempts = startEvent?.totalAttempts ?? '?';\n\n  // Calculate number of bits needed for pattern\n  const numBits =\n    typeof totalAttempts === 'number'\n      ? Math.ceil(Math.log2(totalAttempts)) || 1\n      : 1;\n  const bitPattern = attemptNum.toString(2).padStart(numBits, '0');\n\n  lines.push(\n    `[Attempt ${attemptNum + 1}/${totalAttempts}] Pattern ${attemptNum} (${bitPattern})`,\n  );\n\n  // Collect connection costs (use array to preserve all connections, including duplicates)\n  const connectionCostEvents: (\n    | NodeCostEvent\n    | Extract<PlanDebugEventJSON, {type: 'node-cost'}>\n  )[] = [];\n  const connectionConstraintEvents: NodeConstraintEvent[] = [];\n\n  for (const event of events) {\n    if (event.type === 'node-cost' && event.nodeType === 'connection') {\n      connectionCostEvents.push(event);\n    }\n    if (event.type === 'node-constraint' && event.nodeType === 'connection') {\n      connectionConstraintEvents.push(event);\n    }\n  }\n\n  // Show connection summary\n  if (connectionCostEvents.length > 0) {\n    lines.push('  Connections:');\n    for (const cost of connectionCostEvents) {\n      // Find matching constraint event (same node name and branch pattern)\n      const constraint = connectionConstraintEvents.find(\n        c =>\n          c.node === cost.node &&\n          c.branchPattern.join(',') === cost.branchPattern.join(','),\n      )?.constraint;\n\n      const constraintStr = formatConstraint(constraint);\n      const filterStr = formatFilter(cost.filters);\n      const orderingStr = formatOrdering(cost.ordering);\n      const limitStr =\n        cost.costEstimate.limit !== undefined\n          ? cost.costEstimate.limit.toString()\n          : 'none';\n\n      lines.push(`    ${cost.node}:`);\n      lines.push(\n        `      cost=${cost.costEstimate.cost.toFixed(2)}, startup=${cost.costEstimate.startupCost.toFixed(2)}, scan=${cost.costEstimate.scanEst.toFixed(2)}`,\n      );\n      lines.push(\n        `      rows=${cost.costEstimate.returnedRows.toFixed(2)}, selectivity=${cost.costEstimate.selectivity.toFixed(8)}, limit=${limitStr}`,\n      );\n      lines.push(\n        `      downstreamChildSelectivity=${cost.downstreamChildSelectivity.toFixed(8)}`,\n      );\n      lines.push(`      constraints=${constraintStr}`);\n      lines.push(`      filters=${filterStr}`);\n      lines.push(`      ordering=${orderingStr}`);\n    }\n  }\n\n  // Collect join costs from node-cost events\n  const joinCosts: (\n    | NodeCostEvent\n    | Extract<PlanDebugEventJSON, {type: 'node-cost'}>\n  )[] = [];\n  for (const event of events) {\n    if (event.type === 'node-cost' && event.nodeType === 'join') {\n      joinCosts.push(event);\n    }\n  }\n\n  if (joinCosts.length > 0) {\n    lines.push('  Joins:');\n    for (const cost of joinCosts) {\n      const typeStr = cost.joinType ? ` (${cost.joinType})` : '';\n      const limitStr =\n        cost.costEstimate.limit !== undefined\n          ? cost.costEstimate.limit.toString()\n          : 'none';\n\n      lines.push(`    ${cost.node}${typeStr}:`);\n      lines.push(\n        `      cost=${cost.costEstimate.cost.toFixed(2)}, startup=${cost.costEstimate.startupCost.toFixed(2)}, scan=${cost.costEstimate.scanEst.toFixed(2)}`,\n      );\n      lines.push(\n        `      rows=${cost.costEstimate.returnedRows.toFixed(2)}, selectivity=${cost.costEstimate.selectivity.toFixed(8)}, limit=${limitStr}`,\n      );\n      lines.push(\n        `      downstreamChildSelectivity=${cost.downstreamChildSelectivity.toFixed(8)}`,\n      );\n    }\n  }\n\n  // Find completion/failure events\n  const completeEvent = events.find(e => e.type === 'plan-complete') as\n    | PlanCompleteEvent\n    | undefined;\n  const failedEvent = events.find(e => e.type === 'plan-failed') as\n    | PlanFailedEvent\n    | undefined;\n\n  // Show final status\n\n  if (completeEvent) {\n    lines.push(\n      `  ✓ Plan complete: total cost = ${completeEvent.totalCost.toFixed(2)}`,\n    );\n  } else if (failedEvent) {\n    lines.push(`  ✗ Plan failed: ${failedEvent.reason}`);\n  }\n\n  return lines;\n}\n\n/**\n * Convert undefined values to null in a constraint object for JSON serialization.\n * PlannerConstraint uses Record<string, undefined> which loses keys during JSON.stringify.\n */\nfunction convertConstraintUndefinedToNull(\n  constraint: PlannerConstraint | Record<string, unknown> | undefined | null,\n): Record<string, unknown> | undefined | null {\n  if (constraint === undefined) {\n    return undefined;\n  }\n  if (constraint === null) {\n    return null;\n  }\n  const result: Record<string, unknown> = {};\n  for (const [key, val] of Object.entries(constraint)) {\n    result[key] = val === undefined ? null : val;\n  }\n  return result;\n}\n\n/**\n * Serialize a single debug event to JSON-compatible format.\n * The fanout function is already omitted when events are created.\n * The planSnapshot is excluded as it's internal state not needed for debugging.\n * Undefined values in constraints are converted to null for JSON serialization.\n */\nfunction serializeEvent(event: PlanDebugEvent): PlanDebugEventJSON {\n  // Remove planSnapshot from plan-complete events\n  if (event.type === 'plan-complete') {\n    const {planSnapshot: _, ...rest} = event;\n    return rest as PlanDebugEventJSON;\n  }\n\n  // Convert constraint undefined values to null for specific event types\n  if (event.type === 'node-constraint') {\n    return {\n      ...event,\n      constraint: convertConstraintUndefinedToNull(event.constraint),\n    } as PlanDebugEventJSON;\n  }\n\n  if (event.type === 'connection-costs') {\n    return {\n      ...event,\n      costs: event.costs.map(cost => ({\n        ...cost,\n        constraints: Object.fromEntries(\n          Object.entries(cost.constraints).map(([key, val]) => [\n            key,\n            convertConstraintUndefinedToNull(val),\n          ]),\n        ),\n      })),\n    } as PlanDebugEventJSON;\n  }\n\n  if (event.type === 'constraints-propagated') {\n    return {\n      ...event,\n      connectionConstraints: event.connectionConstraints.map(cc => ({\n        ...cc,\n        constraints: Object.fromEntries(\n          Object.entries(cc.constraints).map(([key, val]) => [\n            key,\n            convertConstraintUndefinedToNull(val),\n          ]),\n        ),\n      })),\n    } as PlanDebugEventJSON;\n  }\n\n  return event as PlanDebugEventJSON;\n}\n\n/**\n * Serialize an array of debug events to JSON-compatible format.\n * The fanout function is already omitted when events are created.\n * The planSnapshot is excluded as it's internal state not needed for debugging.\n */\nexport function serializePlanDebugEvents(\n  events: PlanDebugEvent[],\n): PlanDebugEventJSON[] {\n  return events.map(serializeEvent);\n}\n\n/**\n * Format planner debug events as a human-readable string.\n * Works with JSON-serialized events (from inspector API) or native events (from AccumulatorDebugger).\n *\n * @param events - Array of planner debug events (either JSON or native format)\n * @returns Formatted string showing planning attempts, costs, and final plan selection\n *\n * @example\n * ```typescript\n * const result = await inspector.analyzeQuery(query, { joinPlans: true });\n * if (result.joinPlans) {\n *   console.log(formatPlannerEvents(result.joinPlans));\n * }\n * ```\n */\nexport function formatPlannerEvents(\n  events: PlanDebugEventJSON[] | PlanDebugEvent[],\n): string {\n  const lines: string[] = [];\n\n  // Group events by attempt\n  const eventsByAttempt = new Map<\n    number,\n    (PlanDebugEventJSON | PlanDebugEvent)[]\n  >();\n  let bestPlanEvent:\n    | {\n        type: 'best-plan-selected';\n        bestAttemptNumber: number;\n        totalCost: number;\n        flipPattern: number;\n        joinStates: Array<{join: string; type: string}>;\n      }\n    | undefined;\n\n  for (const event of events) {\n    if ('attemptNumber' in event) {\n      const attempt = event.attemptNumber;\n      if (attempt !== undefined) {\n        let attemptEvents = eventsByAttempt.get(attempt);\n        if (!attemptEvents) {\n          attemptEvents = [];\n          eventsByAttempt.set(attempt, attemptEvents);\n        }\n        attemptEvents.push(event);\n      }\n    } else if (event.type === 'best-plan-selected') {\n      // Save for displaying at the end\n      bestPlanEvent = event;\n    }\n  }\n\n  // Format each attempt as a compact summary\n  for (const [attemptNum, events] of eventsByAttempt.entries()) {\n    lines.push(...formatAttemptSummary(attemptNum, events));\n    lines.push(''); // Blank line between attempts\n  }\n\n  // Show the final plan selection\n  if (bestPlanEvent) {\n    lines.push('─'.repeat(60));\n    lines.push(\n      `✓ Best plan: Attempt ${bestPlanEvent.bestAttemptNumber + 1} (cost=${bestPlanEvent.totalCost.toFixed(2)})`,\n    );\n    if (bestPlanEvent.joinStates.length > 0) {\n      lines.push('  Join types:');\n      for (const j of bestPlanEvent.joinStates) {\n        lines.push(`    ${j.join}: ${j.type}`);\n      }\n    }\n    lines.push('─'.repeat(60));\n  }\n\n  return lines.join('\\n');\n}\n"],"mappings":"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"}

package/out/packages/zql/src/planner/planner-fan-in.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-fan-in.js","names":["#inputs","#type","#output"],"sources":["../../../../../../zql/src/planner/planner-fan-in.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport type {PlannerConstraint} 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 * A PlannerFanIn node can either be a normal FanIn or UnionFanIn.\n *\n * These have different performance characteristics so we need to distinguish them.\n *\n * A normal FanIn only does a single fetch to FanOut, regardless of how many internal\n * branches / inputs it has.\n *\n * A UnionFanIn does a fetch per internal branch / input. This causes an exponential\n * increase in cost if many UnionFanIns are chained after on another. E.g., `(A or B) AND (C or D)`.\n *\n * To capture this cost blow-up, union fan in assigns different branch patterns to their inputs.\n *\n * Since UFI will generate a unique branch pattern per input, planner-connection will yield a higher cost\n * each time a UFI is present. planner-connection will return the sum of the costs of each unique branch pattern.\n */\nexport class PlannerFanIn {\n  readonly kind = 'fan-in' as const;\n  #type: 'FI' | 'UFI';\n  #output?: PlannerNode | undefined;\n  readonly #inputs: Exclude<PlannerNode, PlannerTerminus>[];\n\n  constructor(inputs: Exclude<PlannerNode, PlannerTerminus>[]) {\n    this.#type = 'FI';\n    this.#inputs = inputs;\n  }\n\n  get type() {\n    return this.#type;\n  }\n\n  closestJoinOrSource(): JoinOrConnection {\n    return 'join';\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  reset() {\n    this.#type = 'FI';\n  }\n\n  convertToUFI(): void {\n    this.#type = 'UFI';\n  }\n\n  /**\n   * Propagate unlimiting when a parent join is flipped.\n   * Fan-in propagates to all of its inputs.\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    for (const input of this.#inputs) {\n      if (\n        'propagateUnlimitFromFlippedJoin' in input &&\n        typeof input.propagateUnlimitFromFlippedJoin === 'function'\n      ) {\n        (\n          input as {propagateUnlimitFromFlippedJoin(): void}\n        ).propagateUnlimitFromFlippedJoin();\n      }\n    }\n  }\n\n  estimateCost(\n    downstreamChildSelectivity: number,\n    branchPattern: number[],\n    planDebugger?: PlanDebugger,\n  ): CostEstimate {\n    // FanIn always sums costs of its inputs\n    // But it needs to pass the correct branch pattern to each input\n    let totalCost: CostEstimate = {\n      returnedRows: 0,\n      cost: 0,\n      scanEst: 0,\n      startupCost: 0,\n      selectivity: 0,\n      limit: undefined,\n      fanout: () => {\n        throw new Error('Failed to set fanout model');\n      },\n    };\n\n    if (this.#type === 'FI') {\n      // Normal FanIn: all inputs get the same branch pattern with 0 prepended\n      const updatedPattern = [0, ...branchPattern];\n      let maxrows = 0;\n      let maxRunningCost = 0;\n      let maxStartupCost = 0;\n      let maxScanEst = 0;\n\n      let noMatchProb = 1.0;\n      for (const input of this.#inputs) {\n        const cost = input.estimateCost(\n          downstreamChildSelectivity,\n          updatedPattern,\n          planDebugger,\n        );\n        totalCost.fanout = cost.fanout;\n        if (cost.returnedRows > maxrows) {\n          maxrows = cost.returnedRows;\n        }\n        if (cost.cost > maxRunningCost) {\n          maxRunningCost = cost.cost;\n        }\n        if (cost.startupCost > maxStartupCost) {\n          maxStartupCost = cost.startupCost;\n        }\n        if (cost.scanEst > maxScanEst) {\n          maxScanEst = cost.scanEst;\n        }\n\n        // OR branches: combine selectivities assuming independent events\n        // P(A OR B) = 1 - (1-A)(1-B)\n        // Track probability of NO match in any branch\n        noMatchProb *= 1 - cost.selectivity;\n\n        // all inputs should have the same limit.\n        assert(\n          totalCost.limit === undefined || cost.limit === totalCost.limit,\n          'All FanIn inputs should have the same limit',\n        );\n        totalCost.limit = cost.limit;\n      }\n\n      totalCost.returnedRows = maxrows;\n      totalCost.cost = maxRunningCost;\n      totalCost.selectivity = 1 - noMatchProb;\n      totalCost.startupCost = maxStartupCost;\n      totalCost.scanEst = maxScanEst;\n    } else {\n      // Union FanIn (UFI): each input gets unique branch pattern\n      let i = 0;\n\n      let noMatchProb = 1.0;\n      for (const input of this.#inputs) {\n        const updatedPattern = [i, ...branchPattern];\n        const cost = input.estimateCost(\n          downstreamChildSelectivity,\n          updatedPattern,\n          planDebugger,\n        );\n        totalCost.fanout = cost.fanout;\n        totalCost.returnedRows += cost.returnedRows;\n        totalCost.cost += cost.cost;\n        totalCost.scanEst += cost.scanEst;\n        totalCost.startupCost = totalCost.startupCost + cost.startupCost;\n\n        // OR branches: combine selectivities assuming independent events\n        // P(A OR B) = 1 - (1-A)(1-B)\n        // Track probability of NO match in any branch\n        noMatchProb *= 1 - cost.selectivity;\n\n        // all inputs should have the same limit.\n        assert(\n          totalCost.limit === undefined || cost.limit === totalCost.limit,\n          'All FanIn inputs should have the same limit',\n        );\n        totalCost.limit = cost.limit;\n        i++;\n      }\n      totalCost.selectivity = 1 - noMatchProb;\n    }\n\n    if (planDebugger) {\n      planDebugger.log({\n        type: 'node-cost',\n        nodeType: 'fan-in',\n        node: this.#type,\n        branchPattern,\n        downstreamChildSelectivity,\n        costEstimate: omitFanout(totalCost),\n      });\n    }\n\n    return totalCost;\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: 'fan-in',\n      node: this.#type,\n      branchPattern,\n      constraint,\n      from: from?.kind ?? 'unknown',\n    });\n\n    if (this.#type === 'FI') {\n      const updatedPattern = [0, ...branchPattern];\n      /**\n       * All inputs get the same branch pattern.\n       * 1. They cannot contribute differing constraints to their parent inputs because they are not flipped.\n       *    If they were flipped this would be of type UFI.\n       * 2. All inputs need to be called because they could be pinned. If they are pinned they could have constraints\n       *    to send to their children.\n       */\n      for (const input of this.#inputs) {\n        input.propagateConstraints(\n          updatedPattern,\n          constraint,\n          this,\n          planDebugger,\n        );\n      }\n      return;\n    }\n\n    let i = 0;\n    for (const input of this.#inputs) {\n      input.propagateConstraints(\n        [i, ...branchPattern],\n        constraint,\n        this,\n        planDebugger,\n      );\n      i++;\n    }\n  }\n}\n"],"mappings":"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"}

package/out/packages/zql/src/planner/planner-fan-out.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-fan-out.js","names":["#outputs","#input","#type"],"sources":["../../../../../../zql/src/planner/planner-fan-out.ts"],"sourcesContent":["import type {PlannerConstraint} 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\nexport class PlannerFanOut {\n  readonly kind = 'fan-out' as const;\n  #type: 'FO' | 'UFO';\n  readonly #outputs: PlannerNode[] = [];\n  readonly #input: Exclude<PlannerNode, PlannerTerminus>;\n\n  constructor(input: Exclude<PlannerNode, PlannerTerminus>) {\n    this.#type = 'FO';\n    this.#input = input;\n  }\n\n  get type() {\n    return this.#type;\n  }\n\n  addOutput(node: PlannerNode): void {\n    this.#outputs.push(node);\n  }\n\n  get outputs(): PlannerNode[] {\n    return this.#outputs;\n  }\n\n  closestJoinOrSource(): JoinOrConnection {\n    return this.#input.closestJoinOrSource();\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: 'fan-out',\n      node: 'FO',\n      branchPattern,\n      constraint,\n      from: from?.kind ?? 'unknown',\n    });\n\n    this.#input.propagateConstraints(\n      branchPattern,\n      constraint,\n      this,\n      planDebugger,\n    );\n  }\n\n  estimateCost(\n    downstreamChildSelectivity: number,\n    branchPattern: number[],\n    planDebugger?: PlanDebugger,\n  ): CostEstimate {\n    const ret = this.#input.estimateCost(\n      downstreamChildSelectivity,\n      branchPattern,\n      planDebugger,\n    );\n\n    if (planDebugger) {\n      planDebugger.log({\n        type: 'node-cost',\n        nodeType: 'fan-out',\n        node: 'FO',\n        branchPattern,\n        downstreamChildSelectivity,\n        costEstimate: omitFanout(ret),\n      });\n    }\n\n    return ret;\n  }\n\n  convertToUFO(): void {\n    this.#type = 'UFO';\n  }\n\n  reset(): void {\n    this.#type = 'FO';\n  }\n\n  /**\n   * Propagate unlimiting when a parent join is flipped.\n   * Fan-out propagates to its input.\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    if (\n      'propagateUnlimitFromFlippedJoin' in this.#input &&\n      typeof this.#input.propagateUnlimitFromFlippedJoin === 'function'\n    ) {\n      (\n        this.#input as {propagateUnlimitFromFlippedJoin(): void}\n      ).propagateUnlimitFromFlippedJoin();\n    }\n  }\n}\n"],"mappings":";;AAUA,IAAa,gBAAb,MAA2B;CACzB,OAAgB;CAChB;CACA,WAAmC,CAAC;CACpC;CAEA,YAAY,OAA8C;EACxD,KAAKE,QAAQ;EACb,KAAKD,SAAS;CAChB;CAEA,IAAI,OAAO;EACT,OAAO,KAAKC;CACd;CAEA,UAAU,MAAyB;EACjC,KAAKF,SAAS,KAAK,IAAI;CACzB;CAEA,IAAI,UAAyB;EAC3B,OAAO,KAAKA;CACd;CAEA,sBAAwC;EACtC,OAAO,KAAKC,OAAO,oBAAoB;CACzC;CAEA,qBACE,eACA,YACA,MACA,cACM;EACN,cAAc,IAAI;GAChB,MAAM;GACN,UAAU;GACV,MAAM;GACN;GACA;GACA,MAAM,MAAM,QAAQ;EACtB,CAAC;EAED,KAAKA,OAAO,qBACV,eACA,YACA,MACA,YACF;CACF;CAEA,aACE,4BACA,eACA,cACc;EACd,MAAM,MAAM,KAAKA,OAAO,aACtB,4BACA,eACA,YACF;EAEA,IAAI,cACF,aAAa,IAAI;GACf,MAAM;GACN,UAAU;GACV,MAAM;GACN;GACA;GACA,cAAc,WAAW,GAAG;EAC9B,CAAC;EAGH,OAAO;CACT;CAEA,eAAqB;EACnB,KAAKC,QAAQ;CACf;CAEA,QAAc;EACZ,KAAKA,QAAQ;CACf;;;;;CAMA,kCAAwC;EACtC,IACE,qCAAqC,KAAKD,UAC1C,OAAO,KAAKA,OAAO,oCAAoC,YAEvD,KACOA,OACL,gCAAgC;CAEtC;AACF"}

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

@@ -0,0 +1 @@
+{"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 {PlannerConnection} from './planner-connection.ts';\nimport type {PlannerConstraint} from './planner-constraint.ts';\nimport type {PlanDebugger} from './planner-debug.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/packages/zql/src/planner/planner-join.js

@@ -0,0 +1,262 @@
+import { assert } from "../../../shared/src/asserts.js";
+import { getMultiConstraintChunkSize } from "../ivm/flipped-join.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;
+}
+/**
+* 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 + Math.ceil(child.scanEst / getMultiConstraintChunkSize()) * parent.startupCost + child.scanEst * (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";
+	}
+}
+//#endregion
+export { PlannerJoin };
+
+//# sourceMappingURL=planner-join.js.map

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

@@ -0,0 +1 @@
+{"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 {getMultiConstraintChunkSize} from '../ivm/flipped-join.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        // FlippedJoin batches child→parent lookups into chunks of\n        // getMultiConstraintChunkSize(), issuing one IN-list query per\n        // chunk. So `parent.startupCost` (statement prepare + plan\n        // setup) is paid once per chunk, not once per child row. The\n        // per-seek work (`parent.cost` index walk + `parent.scanEst`\n        // rows) still scales with child row count: each IN value still\n        // does its own index seek.\n        cost:\n          child.cost +\n          Math.ceil(child.scanEst / getMultiConstraintChunkSize()) *\n            parent.startupCost +\n          child.scanEst * (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":"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"}

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

@@ -0,0 +1 @@
+{"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;CAC7B,OAAO;AACT"}