@rocicorp/zero 0.25.0-canary.9 → 0.25.1

package/out/zql/src/mutate/mutator.d.ts

@@ -1,98 +1,94 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { ReadonlyJSONValue } from '../../../shared/src/json.ts';
+import type { DefaultContext, DefaultSchema, DefaultWrappedTransaction } from '../../../zero-types/src/default-types.ts';
 import type { Schema } from '../../../zero-types/src/schema.ts';
 import type { AnyTransaction, Transaction } from './custom.ts';
-declare const defineMutatorTag: unique symbol;
-export declare function isMutatorDefinition<TSchema extends Schema, TContext, TInput extends ReadonlyJSONValue | undefined, TOutput extends ReadonlyJSONValue | undefined, TWrappedTransaction = unknown>(f: unknown): f is MutatorDefinition<TSchema, TContext, TInput, TOutput, TWrappedTransaction>;
-export type MutatorDefinition<TSchema extends Schema, TContext, TInput extends ReadonlyJSONValue | undefined, TOutput extends ReadonlyJSONValue | undefined, TWrappedTransaction> = ((options: {
-    args: TOutput;
-    ctx: TContext;
-    tx: Transaction<TSchema, TWrappedTransaction>;
-}) => Promise<void>) & {
-    [defineMutatorTag]: true;
-    validator: StandardSchemaV1<TInput, TOutput> | undefined;
+export type MutatorDefinitionTypes<TInput extends ReadonlyJSONValue | undefined, TOutput, TContext, TWrappedTransaction> = 'MutatorDefinition' & {
+    readonly $input: TInput;
+    readonly $output: TOutput;
+    readonly $context: TContext;
+    readonly $wrappedTransaction: TWrappedTransaction;
 };
-export declare function defineMutator<TSchema extends Schema, TContext, TInput extends ReadonlyJSONValue | undefined, TOutput extends ReadonlyJSONValue | undefined, TWrappedTransaction>(validator: StandardSchemaV1<TInput, TOutput>, mutator: (options: {
-    args: TOutput;
-    ctx: TContext;
-    tx: Transaction<TSchema, TWrappedTransaction>;
-}) => Promise<void>): MutatorDefinition<TSchema, TContext, TInput, TOutput, TWrappedTransaction>;
-export declare function defineMutator<TSchema extends Schema, TContext, TArgs extends ReadonlyJSONValue | undefined, TWrappedTransaction>(mutator: (options: {
-    args: TArgs;
-    ctx: TContext;
-    tx: Transaction<TSchema, TWrappedTransaction>;
-}) => Promise<void>): MutatorDefinition<TSchema, TContext, TArgs, TArgs, TWrappedTransaction>;
-export declare function defineMutatorWithType<TSchema extends Schema>(): TypedDefineMutator<TSchema, unknown, unknown>;
-export declare function defineMutatorWithType<TSchema extends Schema, TContext>(): TypedDefineMutator<TSchema, TContext, unknown>;
-export declare function defineMutatorWithType<TSchema extends Schema, TContext, TWrappedTransaction>(): TypedDefineMutator<TSchema, TContext, TWrappedTransaction>;
+export type MutatorDefinition<TInput extends ReadonlyJSONValue | undefined, TOutput extends ReadonlyJSONValue | undefined, TContext = DefaultContext, TWrappedTransaction = DefaultWrappedTransaction> = {
+    readonly 'fn': MutatorDefinitionFunction<TOutput, TContext, AnyTransaction>;
+    readonly 'validator': StandardSchemaV1<TInput, TOutput> | undefined;
+    readonly '~': MutatorDefinitionTypes<TInput, TOutput, TContext, TWrappedTransaction>;
+};
+export type AnyMutatorDefinition = MutatorDefinition<any, any, any, any>;
+export declare function isMutatorDefinition(f: unknown): f is AnyMutatorDefinition;
+export declare function defineMutator<TInput extends ReadonlyJSONValue | undefined = ReadonlyJSONValue | undefined, TSchema extends Schema = DefaultSchema, TContext = DefaultContext, TWrappedTransaction = DefaultWrappedTransaction>(mutator: MutatorDefinitionFunction<TInput, TContext, Transaction<TSchema, TWrappedTransaction>>): MutatorDefinition<TInput, TInput, TContext, TWrappedTransaction>;
+export declare function defineMutator<TInput extends ReadonlyJSONValue | undefined = undefined, TOutput extends ReadonlyJSONValue | undefined = TInput, TSchema extends Schema = DefaultSchema, TContext = DefaultContext, TWrappedTransaction = DefaultWrappedTransaction>(validator: StandardSchemaV1<TInput, TOutput>, mutator: MutatorDefinitionFunction<TOutput, TContext, Transaction<TSchema, TWrappedTransaction>>): MutatorDefinition<TInput, TOutput, TContext, TWrappedTransaction>;
+export declare function defineMutatorWithType<TSchema extends Schema, TContext = unknown, TWrappedTransaction = unknown>(): TypedDefineMutator<TSchema, TContext, TWrappedTransaction>;
 /**
  * The return type of defineMutatorWithType. A function matching the
  * defineMutator overloads but with Schema, Context, and WrappedTransaction
  * pre-bound.
+ *
+ * This is used as a workaround to using DefaultTypes (e.g. when using
+ * multiple Zero instances).
  */
 type TypedDefineMutator<TSchema extends Schema, TContext, TWrappedTransaction> = {
-    <TArgs extends ReadonlyJSONValue | undefined>(mutator: (options: {
-        args: TArgs;
-        ctx: TContext;
-        tx: Transaction<TSchema, TWrappedTransaction>;
-    }) => Promise<void>): MutatorDefinition<TSchema, TContext, TArgs, TArgs, TWrappedTransaction>;
-    <TInput extends ReadonlyJSONValue | undefined, TOutput extends ReadonlyJSONValue | undefined>(validator: StandardSchemaV1<TInput, TOutput>, mutator: (options: {
-        args: TOutput;
-        ctx: TContext;
-        tx: Transaction<TSchema, TWrappedTransaction>;
-    }) => Promise<void>): MutatorDefinition<TSchema, TContext, TInput, TOutput, TWrappedTransaction>;
+    <TArgs extends ReadonlyJSONValue | undefined>(mutator: MutatorDefinitionFunction<TArgs, TContext, Transaction<TSchema, TWrappedTransaction>>): MutatorDefinition<TArgs, TArgs, TContext, TWrappedTransaction>;
+    <TInput extends ReadonlyJSONValue | undefined, TOutput extends ReadonlyJSONValue | undefined>(validator: StandardSchemaV1<TInput, TOutput>, mutator: MutatorDefinitionFunction<TOutput, TContext, Transaction<TSchema, TWrappedTransaction>>): MutatorDefinition<TInput, TOutput, TContext, TWrappedTransaction>;
+};
+export type MutatorDefinitionFunction<TOutput extends ReadonlyJSONValue | undefined, TContext, TTransaction> = (options: {
+    args: TOutput;
+    ctx: TContext;
+    tx: TTransaction;
+}) => Promise<void>;
+export type MutatorTypes<TInput extends ReadonlyJSONValue | undefined, TSchema extends Schema, TContext, TWrappedTransaction> = 'Mutator' & {
+    readonly $input: TInput;
+    readonly $schema: TSchema;
+    readonly $context: TContext;
+    readonly $wrappedTransaction: TWrappedTransaction;
 };
 /**
  * A callable wrapper around a MutatorDefinition, created by `defineMutators()`.
  *
- * Accessed like `mutators.foo.bar`, and called to create a MutationRequest:
- * `mutators.foo.bar(42)` returns a `MutationRequest`.
+ * Accessed like `mutators.foo.bar`, and called to create a MutateRequest:
+ * `mutators.foo.bar(42)` returns a `MutateRequest`.
  *
  * The `fn` property is used for execution and takes raw JSON args (for rebase
  * and server wire format cases) that are validated internally.
- *
- * @template TSchema - The schema type
- * @template TContext - The context type available during mutation execution
- * @template TArgsInput - The argument type accepted by the callable (before validation)
- * @template TWrappedTransaction - The wrapped transaction type
  */
-export type Mutator<TSchema extends Schema, TContext, TArgsInput extends ReadonlyJSONValue | undefined, TWrappedTransaction = unknown> = MutatorCallable<TSchema, TContext, TArgsInput, TWrappedTransaction> & {
-    readonly mutatorName: string;
+export type Mutator<TInput extends ReadonlyJSONValue | undefined, TSchema extends Schema = DefaultSchema, TContext = DefaultContext, TWrappedTransaction = DefaultWrappedTransaction> = {
+    readonly 'mutatorName': string;
     /**
      * Execute the mutation. Args are ReadonlyJSONValue because this is called
      * during rebase (from stored JSON) and on the server (from wire format).
      * Validation happens internally before the recipe function runs.
-     *
-     * The tx parameter uses AnyTransaction to avoid contravariance issues when
-     * calling from generic code. The implementation casts to the specific type.
      */
-    readonly fn: (options: {
-        args: TArgsInput;
-        ctx: TContext;
-        tx: AnyTransaction;
-    }) => Promise<void>;
+    readonly 'fn': MutatorDefinitionFunction<TInput, TContext, Transaction<TSchema, TWrappedTransaction>>;
+    readonly '~': MutatorTypes<TInput, TSchema, TContext, TWrappedTransaction>;
+} & MutatorCallable<TInput, TSchema, TContext, TWrappedTransaction>;
+type MutatorCallable<TInput extends ReadonlyJSONValue | undefined, TSchema extends Schema, TContext, TWrappedTransaction> = [TInput] extends [undefined] ? () => MutateRequest<TInput, TSchema, TContext, TWrappedTransaction> : undefined extends TInput ? {
+    (): MutateRequest<TInput, TSchema, TContext, TWrappedTransaction>;
+    (args?: TInput): MutateRequest<TInput, TSchema, TContext, TWrappedTransaction>;
+} : {
+    (args: TInput): MutateRequest<TInput, TSchema, TContext, TWrappedTransaction>;
+};
+export type AnyMutator = Mutator<any, any, any, any>;
+/**
+ * Checks if a value is a Mutator (the result of processing a MutatorDefinition
+ * through defineMutators).
+ */
+export declare function isMutator<S extends Schema>(value: unknown): value is Mutator<any, S, any, any>;
+export type MutateRequestTypes<TInput extends ReadonlyJSONValue | undefined, TSchema extends Schema, TContext, TWrappedTransaction> = 'MutateRequest' & {
+    readonly $input: TInput;
+    readonly $schema: TSchema;
+    readonly $context: TContext;
+    readonly $wrappedTransaction: TWrappedTransaction;
 };
-type MutatorCallable<TSchema extends Schema, TContext, TArgsInput extends ReadonlyJSONValue | undefined, TWrappedTransaction> = [TArgsInput] extends [undefined] ? () => MutationRequest<TSchema, TContext, TArgsInput, TWrappedTransaction> : undefined extends TArgsInput ? (args?: TArgsInput) => MutationRequest<TSchema, TContext, TArgsInput, TWrappedTransaction> : (args: TArgsInput) => MutationRequest<TSchema, TContext, TArgsInput, TWrappedTransaction>;
-export type AnyMutator = Mutator<Schema, any, any, any>;
 /**
  * The result of calling a Mutator with arguments.
  *
  * Created by `mutators.foo.bar(42)`, executed by `zero.mutate(mr)` on the client
  * or `mr.mutator.fn({tx, ctx, args: mr.args})` on the server.
- *
- * @template TSchema - The schema type
- * @template TContext - The context type available during mutation execution
- * @template TArgsInput - The argument type (before validation, sent to server)
- * @template TWrappedTransaction - The wrapped transaction type
  */
-export type MutationRequest<TSchema extends Schema, TContext, TArgsInput extends ReadonlyJSONValue | undefined, TWrappedTransaction> = {
-    readonly mutator: Mutator<TSchema, TContext, TArgsInput, TWrappedTransaction>;
-    readonly args: TArgsInput;
+export type MutateRequest<TInput extends ReadonlyJSONValue | undefined, TSchema extends Schema = DefaultSchema, TContext = DefaultContext, TWrappedTransaction = DefaultWrappedTransaction> = {
+    readonly 'mutator': Mutator<TInput, TSchema, TContext, TWrappedTransaction>;
+    readonly 'args': TInput;
+    readonly '~': MutateRequestTypes<TInput, TSchema, TContext, TWrappedTransaction>;
 };
-/**
- * Checks if a value is a Mutator (the result of processing a MutatorDefinition
- * through defineMutators).
- */
-export declare function isMutator(value: unknown): value is AnyMutator;
 export {};
 //# sourceMappingURL=mutator.d.ts.map

package/out/zql/src/mutate/mutator.d.ts.map

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

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

@@ -1,7 +1,6 @@
 import { must } from "../../../shared/src/must.js";
-const defineMutatorTag = Symbol();
 function isMutatorDefinition(f) {
-  return typeof f === "function" && !!f[defineMutatorTag];
+  return typeof f === "object" && f !== null && f["~"] === "MutatorDefinition";
 }
 function defineMutator(validatorOrMutator, mutator) {
   let validator;
@@ -13,18 +12,18 @@ function defineMutator(validatorOrMutator, mutator) {
     validator = validatorOrMutator;
     actualMutator = must(mutator);
   }
-  const f = actualMutator;
-  f[defineMutatorTag] = true;
-  f.validator = validator;
-  return f;
+  const mutatorDefinition = {
+    "fn": actualMutator,
+    "validator": validator,
+    "~": "MutatorDefinition"
+  };
+  return mutatorDefinition;
 }
 function defineMutatorWithType() {
   return defineMutator;
 }
 function isMutator(value) {
-  return typeof value === "function" && // oxlint-disable-next-line no-explicit-any
-  typeof value.mutatorName === "string" && // oxlint-disable-next-line no-explicit-any
-  typeof value.fn === "function";
+  return typeof value === "function" && typeof value.mutatorName === "string" && typeof value.fn === "function";
 }
 export {
   defineMutator,

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

@@ -1 +1 @@
-{"version":3,"file":"mutator.js","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 {Schema} from '../../../zero-types/src/schema.ts';\nimport type {AnyTransaction, Transaction} from './custom.ts';\n\n// ----------------------------------------------------------------------------\n// defineMutator\n// ----------------------------------------------------------------------------\n\nconst defineMutatorTag = Symbol();\n\nexport function isMutatorDefinition<\n  TSchema extends Schema,\n  TContext,\n  TInput extends ReadonlyJSONValue | undefined,\n  TOutput extends ReadonlyJSONValue | undefined,\n  TWrappedTransaction = unknown,\n>(\n  f: unknown,\n): f is MutatorDefinition<\n  TSchema,\n  TContext,\n  TInput,\n  TOutput,\n  TWrappedTransaction\n> {\n  // oxlint-disable-next-line no-explicit-any\n  return typeof f === 'function' && !!(f as any)[defineMutatorTag];\n}\n\nexport type MutatorDefinition<\n  TSchema extends Schema,\n  TContext,\n  TInput extends ReadonlyJSONValue | undefined,\n  TOutput extends ReadonlyJSONValue | undefined,\n  TWrappedTransaction,\n> = ((options: {\n  args: TOutput;\n  ctx: TContext;\n  tx: Transaction<TSchema, TWrappedTransaction>;\n}) => Promise<void>) & {\n  [defineMutatorTag]: true;\n  validator: StandardSchemaV1<TInput, TOutput> | undefined;\n};\n\n// Overload 1: Call with validator\nexport function defineMutator<\n  TSchema extends Schema,\n  TContext,\n  TInput extends ReadonlyJSONValue | undefined,\n  TOutput extends ReadonlyJSONValue | undefined,\n  TWrappedTransaction,\n>(\n  validator: StandardSchemaV1<TInput, TOutput>,\n  mutator: (options: {\n    args: TOutput;\n    ctx: TContext;\n    tx: Transaction<TSchema, TWrappedTransaction>;\n  }) => Promise<void>,\n): MutatorDefinition<TSchema, TContext, TInput, TOutput, TWrappedTransaction>;\n\n// Overload 2: Call without validator\nexport function defineMutator<\n  TSchema extends Schema,\n  TContext,\n  TArgs extends ReadonlyJSONValue | undefined,\n  TWrappedTransaction,\n>(\n  mutator: (options: {\n    args: TArgs;\n    ctx: TContext;\n    tx: Transaction<TSchema, TWrappedTransaction>;\n  }) => Promise<void>,\n): MutatorDefinition<TSchema, TContext, TArgs, TArgs, TWrappedTransaction>;\n\n// Implementation\nexport function defineMutator<\n  TSchema extends Schema,\n  TContext,\n  TInput extends ReadonlyJSONValue | undefined,\n  TOutput extends ReadonlyJSONValue | undefined,\n  TWrappedTransaction,\n>(\n  validatorOrMutator:\n    | StandardSchemaV1<TInput, TOutput>\n    | ((options: {\n        args: TOutput;\n        ctx: TContext;\n        tx: Transaction<TSchema, TWrappedTransaction>;\n      }) => Promise<void>),\n  mutator?: (options: {\n    args: TOutput;\n    ctx: TContext;\n    tx: Transaction<TSchema, TWrappedTransaction>;\n  }) => Promise<void>,\n): MutatorDefinition<TSchema, TContext, TInput, TOutput, TWrappedTransaction> {\n  let validator: StandardSchemaV1<TInput, TOutput> | undefined;\n  let actualMutator: (options: {\n    args: TOutput;\n    ctx: TContext;\n    tx: Transaction<TSchema, TWrappedTransaction>;\n  }) => Promise<void>;\n\n  if (typeof validatorOrMutator === 'function') {\n    // defineMutator(mutator) - no validator\n    validator = undefined;\n    actualMutator = validatorOrMutator;\n  } else {\n    // defineMutator(validator, mutator)\n    validator = validatorOrMutator;\n    actualMutator = must(mutator);\n  }\n\n  const f = actualMutator as MutatorDefinition<\n    TSchema,\n    TContext,\n    TInput,\n    TOutput,\n    TWrappedTransaction\n  >;\n  f[defineMutatorTag] = true;\n  f.validator = validator;\n  return f;\n}\n\n// Overload 1: Just Schema\nexport function defineMutatorWithType<\n  TSchema extends Schema,\n>(): TypedDefineMutator<TSchema, unknown, unknown>;\n\n// Overload 2: Schema and Context\nexport function defineMutatorWithType<\n  TSchema extends Schema,\n  TContext,\n>(): TypedDefineMutator<TSchema, TContext, unknown>;\n\n// Overload 3: Schema, Context, and WrappedTransaction\nexport function defineMutatorWithType<\n  TSchema extends Schema,\n  TContext,\n  TWrappedTransaction,\n>(): TypedDefineMutator<TSchema, TContext, TWrappedTransaction>;\n\n// Implementation\nexport function defineMutatorWithType() {\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 */\ntype TypedDefineMutator<\n  TSchema extends Schema,\n  TContext,\n  TWrappedTransaction,\n> = {\n  // Without validator\n  <TArgs extends ReadonlyJSONValue | undefined>(\n    mutator: (options: {\n      args: TArgs;\n      ctx: TContext;\n      tx: Transaction<TSchema, TWrappedTransaction>;\n    }) => Promise<void>,\n  ): MutatorDefinition<TSchema, TContext, TArgs, TArgs, TWrappedTransaction>;\n\n  // With validator\n  <\n    TInput extends ReadonlyJSONValue | undefined,\n    TOutput extends ReadonlyJSONValue | undefined,\n  >(\n    validator: StandardSchemaV1<TInput, TOutput>,\n    mutator: (options: {\n      args: TOutput;\n      ctx: TContext;\n      tx: Transaction<TSchema, TWrappedTransaction>;\n    }) => Promise<void>,\n  ): MutatorDefinition<TSchema, TContext, TInput, TOutput, TWrappedTransaction>;\n};\n\n// ----------------------------------------------------------------------------\n// Mutator and MutationRequest types\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 MutationRequest:\n * `mutators.foo.bar(42)` returns a `MutationRequest`.\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 *\n * @template TSchema - The schema type\n * @template TContext - The context type available during mutation execution\n * @template TArgsInput - The argument type accepted by the callable (before validation)\n * @template TWrappedTransaction - The wrapped transaction type\n */\nexport type Mutator<\n  TSchema extends Schema,\n  TContext,\n  TArgsInput extends ReadonlyJSONValue | undefined,\n  TWrappedTransaction = unknown,\n> = MutatorCallable<TSchema, TContext, TArgsInput, TWrappedTransaction> & {\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   * The tx parameter uses AnyTransaction to avoid contravariance issues when\n   * calling from generic code. The implementation casts to the specific type.\n   */\n  readonly fn: (options: {\n    args: TArgsInput;\n    ctx: TContext;\n    tx: AnyTransaction;\n  }) => Promise<void>;\n};\n\n// Helper type for the callable part of Mutator\n// When TArgsInput is undefined, the function is callable with 0 args\n// When TArgsInput includes undefined (optional), args is optional\n// Otherwise, args is required\ntype MutatorCallable<\n  TSchema extends Schema,\n  TContext,\n  TArgsInput extends ReadonlyJSONValue | undefined,\n  TWrappedTransaction,\n> = [TArgsInput] extends [undefined]\n  ? () => MutationRequest<TSchema, TContext, TArgsInput, TWrappedTransaction>\n  : undefined extends TArgsInput\n    ? (\n        args?: TArgsInput,\n      ) => MutationRequest<TSchema, TContext, TArgsInput, TWrappedTransaction>\n    : (\n        args: TArgsInput,\n      ) => MutationRequest<TSchema, TContext, TArgsInput, TWrappedTransaction>;\n\n// oxlint-disable-next-line no-explicit-any\nexport type AnyMutator = Mutator<Schema, any, any, any>;\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 *\n * @template TSchema - The schema type\n * @template TContext - The context type available during mutation execution\n * @template TArgsInput - The argument type (before validation, sent to server)\n * @template TWrappedTransaction - The wrapped transaction type\n */\nexport type MutationRequest<\n  TSchema extends Schema,\n  TContext,\n  TArgsInput extends ReadonlyJSONValue | undefined,\n  TWrappedTransaction,\n> = {\n  readonly mutator: Mutator<TSchema, TContext, TArgsInput, TWrappedTransaction>;\n  readonly args: TArgsInput;\n};\n\n/**\n * Checks if a value is a Mutator (the result of processing a MutatorDefinition\n * through defineMutators).\n */\nexport function isMutator(value: unknown): value is AnyMutator {\n  return (\n    typeof value === 'function' &&\n    // oxlint-disable-next-line no-explicit-any\n    typeof (value as any).mutatorName === 'string' &&\n    // oxlint-disable-next-line no-explicit-any\n    typeof (value as any).fn === 'function'\n  );\n}\n"],"names":[],"mappings":";AAUA,MAAM,mBAAmB,OAAA;AAElB,SAAS,oBAOd,GAOA;AAEA,SAAO,OAAO,MAAM,cAAc,CAAC,CAAE,EAAU,gBAAgB;AACjE;AAgDO,SAAS,cAOd,oBAOA,SAK4E;AAC5E,MAAI;AACJ,MAAI;AAMJ,MAAI,OAAO,uBAAuB,YAAY;AAE5C,gBAAY;AACZ,oBAAgB;AAAA,EAClB,OAAO;AAEL,gBAAY;AACZ,oBAAgB,KAAK,OAAO;AAAA,EAC9B;AAEA,QAAM,IAAI;AAOV,IAAE,gBAAgB,IAAI;AACtB,IAAE,YAAY;AACd,SAAO;AACT;AAqBO,SAAS,wBAAwB;AACtC,SAAO;AACT;AA0HO,SAAS,UAAU,OAAqC;AAC7D,SACE,OAAO,UAAU;AAAA,EAEjB,OAAQ,MAAc,gBAAgB;AAAA,EAEtC,OAAQ,MAAc,OAAO;AAEjC;"}
+{"version":3,"file":"mutator.js","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} 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 (typeof validatorOrMutator === 'function') {\n    // defineMutator(mutator) - no validator\n    validator = undefined;\n    actualMutator = validatorOrMutator;\n  } else {\n    // defineMutator(validator, mutator)\n    validator = validatorOrMutator;\n    actualMutator = must(mutator);\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\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': MutatorDefinitionFunction<\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"],"names":[],"mappings":";AA8CO,SAAS,oBAAoB,GAAuC;AACzE,SACE,OAAO,MAAM,YACb,MAAM,QACL,EAAwB,GAAG,MAAM;AAEtC;AAiCO,SAAS,cAOd,oBAOA,SAKmE;AACnE,MAAI;AACJ,MAAI;AAMJ,MAAI,OAAO,uBAAuB,YAAY;AAE5C,gBAAY;AACZ,oBAAgB;AAAA,EAClB,OAAO;AAEL,gBAAY;AACZ,oBAAgB,KAAK,OAAO;AAAA,EAC9B;AAEA,QAAM,oBAKF;AAAA,IACF,MAAM;AAAA,IAKN,aAAa;AAAA,IACb,KAAK;AAAA,EAAA;AAOP,SAAO;AACT;AAGO,SAAS,wBAIgD;AAC9D,SAAO;AACT;AA4HO,SAAS,UACd,OAEoC;AACpC,SACE,OAAO,UAAU,cACjB,OAAQ,MAAkC,gBAAgB,YAC1D,OAAQ,MAAyB,OAAO;AAE5C;"}

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

@@ -1,3 +1,4 @@
+import type { LogContext } from '@rocicorp/logger';
 import type { AST } from '../../../zero-protocol/src/ast.ts';
 import type { ConnectionCostModel } from './planner-connection.ts';
 import type { PlannerConstraint } from './planner-constraint.ts';
@@ -10,6 +11,6 @@ export type Plans = {
     };
 };
 export declare function buildPlanGraph(ast: AST, model: ConnectionCostModel, isRoot: boolean, baseConstraints?: PlannerConstraint): Plans;
-export declare function planQuery(ast: AST, model: ConnectionCostModel, planDebugger?: PlanDebugger): AST;
+export declare function planQuery(ast: AST, model: ConnectionCostModel, planDebugger?: PlanDebugger, lc?: LogContext): AST;
 export declare function applyPlansToAST(ast: AST, plans: Plans): AST;
 //# sourceMappingURL=planner-builder.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"planner-builder.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-builder.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,GAAG,EAKJ,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAoBhD,MAAM,MAAM,KAAK,GAAG;IAClB,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAA;KAAC,CAAC;CAClC,CAAC;AAEF,wBAAgB,cAAc,CAC5B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,OAAO,EACf,eAAe,CAAC,EAAE,iBAAiB,GAClC,KAAK,CAmDP;AAgND,wBAAgB,SAAS,CACvB,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,mBAAmB,EAC1B,YAAY,CAAC,EAAE,YAAY,GAC1B,GAAG,CAIL;AAqCD,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,GAAG,GAAG,CAyB3D"}
+{"version":3,"file":"planner-builder.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,KAAK,EACV,GAAG,EAKJ,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAoBhD,MAAM,MAAM,KAAK,GAAG;IAClB,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAA;KAAC,CAAC;CAClC,CAAC;AAEF,wBAAgB,cAAc,CAC5B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,OAAO,EACf,eAAe,CAAC,EAAE,iBAAiB,GAClC,KAAK,CAmDP;AAoND,wBAAgB,SAAS,CACvB,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,mBAAmB,EAC1B,YAAY,CAAC,EAAE,YAAY,EAC3B,EAAE,CAAC,EAAE,UAAU,GACd,GAAG,CAIL;AAqCD,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,GAAG,GAAG,CAyB3D"}

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

@@ -205,15 +205,15 @@ function hasCorrelatedSubquery(condition) {
 function extractConstraint(fields, _tableName) {
   return Object.fromEntries(fields.map((field) => [field, void 0]));
 }
-function planRecursively(plans, planDebugger) {
+function planRecursively(plans, planDebugger, lc) {
   for (const subPlan of Object.values(plans.subPlans)) {
-    planRecursively(subPlan, planDebugger);
+    planRecursively(subPlan, planDebugger, lc);
   }
-  plans.plan.plan(planDebugger);
+  plans.plan.plan(planDebugger, lc);
 }
-function planQuery(ast, model, planDebugger) {
+function planQuery(ast, model, planDebugger, lc) {
   const plans = buildPlanGraph(ast, model, true);
-  planRecursively(plans, planDebugger);
+  planRecursively(plans, planDebugger, lc);
   return applyPlansToAST(ast, plans);
 }
 function applyToCondition(condition, flippedIds) {

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

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

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

@@ -133,9 +133,9 @@ export declare function serializePlanDebugEvents(events: PlanDebugEvent[]): Plan
  *
  * @example
  * ```typescript
- * const result = await inspector.analyzeQuery(query, { plannerDebug: true });
- * if (result.plannerEvents) {
- *   console.log(formatPlannerEvents(result.plannerEvents));
+ * const result = await inspector.analyzeQuery(query, { joinPlans: true });
+ * if (result.joinPlans) {
+ *   console.log(formatPlannerEvents(result.joinPlans));
  * }
  * ```
  */

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

@@ -1 +1 @@
-{"version":3,"file":"planner-debug.js","sources":["../../../../../zql/src/planner/planner-debug.ts"],"sourcesContent":["import type * as v from '../../../shared/src/valita.ts';\nimport type {\n  Condition,\n  Ordering,\n  ValuePosition,\n} from '../../../zero-protocol/src/ast.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 {PlannerConstraint} from './planner-constraint.ts';\nimport type {CostEstimate, JoinType} from './planner-node.ts';\nimport type {PlanState} from './planner-graph.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: (\n    | NodeConstraintEvent\n    | Extract<PlanDebugEventJSON, {type: 'node-constraint'}>\n  )[] = [];\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, { plannerDebug: true });\n * if (result.plannerEvents) {\n *   console.log(formatPlannerEvents(result.plannerEvents));\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"],"names":["events"],"mappings":"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"}
+{"version":3,"file":"planner-debug.js","sources":["../../../../../zql/src/planner/planner-debug.ts"],"sourcesContent":["import type * as v from '../../../shared/src/valita.ts';\nimport type {\n  Condition,\n  Ordering,\n  ValuePosition,\n} from '../../../zero-protocol/src/ast.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 {PlannerConstraint} from './planner-constraint.ts';\nimport type {CostEstimate, JoinType} from './planner-node.ts';\nimport type {PlanState} from './planner-graph.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: (\n    | NodeConstraintEvent\n    | Extract<PlanDebugEventJSON, {type: 'node-constraint'}>\n  )[] = [];\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"],"names":["events"],"mappings":"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"}

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

@@ -1,3 +1,4 @@
+import type { LogContext } from '@rocicorp/logger';
 import type { PlanDebugger } from './planner-debug.ts';
 import type { PlannerConnection } from './planner-connection.ts';
 import type { PlannerConstraint } from './planner-constraint.ts';
@@ -96,7 +97,8 @@ export declare class PlannerGraph {
      * FanOut/FanIn states (FO/UFO and FI/UFI) are automatically derived from join flip states.
      *
      * @param planDebugger - Optional debugger to receive structured events during planning
+     * @param lc - Optional logger for warnings
      */
-    plan(planDebugger?: PlanDebugger): void;
+    plan(planDebugger?: PlanDebugger, lc?: LogContext): void;
 }
 //# sourceMappingURL=planner-graph.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"planner-graph.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-graph.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAGnD,OAAO,EAAC,aAAa,EAAE,KAAK,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,WAAW,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAAC,CAAC;IAChD,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAAC,CAAC;IACzC,OAAO,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAA;KAAC,CAAC,CAAC;IACrC,MAAM,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAA;KAAC,CAAC,CAAC;IACpC,qBAAqB,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC,CAAC,CAAC;CAC1E,CAAC;AAkBF,qBAAa,YAAY;;IAQvB,KAAK,EAAE,WAAW,EAAE,CAAM;IAC1B,OAAO,EAAE,aAAa,EAAE,CAAM;IAC9B,MAAM,EAAE,YAAY,EAAE,CAAM;IAC5B,WAAW,EAAE,iBAAiB,EAAE,CAAM;IAEtC;;;;;OAKG;IACH,kBAAkB;IAOlB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,aAAa;IAUlE;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAMtC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAI5C;;;;OAIG;IACH,oBAAoB,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAQvD;;;OAGG;IACH,YAAY,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,MAAM;IAKjD;;;;;;;;OAQG;IACH,uBAAuB,IAAI,SAAS;IAYpC;;;;;;;;OAQG;IACH,uBAAuB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAsF/C;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;CAgIxC"}
+{"version":3,"file":"planner-graph.d.ts","sourceRoot":"","sources":["../../../../../zql/src/planner/planner-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAGnD,OAAO,EAAC,aAAa,EAAE,KAAK,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,WAAW,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAAC,CAAC;IAChD,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAAC,CAAC;IACzC,OAAO,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAA;KAAC,CAAC,CAAC;IACrC,MAAM,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAA;KAAC,CAAC,CAAC;IACpC,qBAAqB,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC,CAAC,CAAC;CAC1E,CAAC;AAkBF,qBAAa,YAAY;;IAQvB,KAAK,EAAE,WAAW,EAAE,CAAM;IAC1B,OAAO,EAAE,aAAa,EAAE,CAAM;IAC9B,MAAM,EAAE,YAAY,EAAE,CAAM;IAC5B,WAAW,EAAE,iBAAiB,EAAE,CAAM;IAEtC;;;;;OAKG;IACH,kBAAkB;IAOlB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,aAAa;IAUlE;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAMtC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAI5C;;;;OAIG;IACH,oBAAoB,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAQvD;;;OAGG;IACH,YAAY,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,MAAM;IAKjD;;;;;;;;OAQG;IACH,uBAAuB,IAAI,SAAS;IAYpC;;;;;;;;OAQG;IACH,uBAAuB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAsF/C;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,YAAY,CAAC,EAAE,YAAY,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,IAAI;CA+HzD"}

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

@@ -1,6 +1,5 @@
 import { assert } from "../../../shared/src/asserts.js";
 import { must } from "../../../shared/src/must.js";
-import { PlannerException } from "../error.js";
 import { omitFanout } from "./planner-node.js";
 import { PlannerSource } from "./planner-source.js";
 const MAX_FLIPPABLE_JOINS = 9;
@@ -195,14 +194,15 @@ class PlannerGraph {
    * FanOut/FanIn states (FO/UFO and FI/UFI) are automatically derived from join flip states.
    *
    * @param planDebugger - Optional debugger to receive structured events during planning
+   * @param lc - Optional logger for warnings
    */
-  plan(planDebugger) {
+  plan(planDebugger, lc) {
     const flippableJoins = this.joins.filter((j) => j.isFlippable());
     if (flippableJoins.length > MAX_FLIPPABLE_JOINS) {
-      throw new PlannerException(
-        "max_flippable_joins",
-        `Query has ${flippableJoins.length} EXISTS checks in a single RELATED call (or in the top level query), which would require ${2 ** flippableJoins.length} plan evaluations. This may be very slow. Consider simplifying the query or increasing MAX_FLIPPABLE_JOINS (currently set to ${MAX_FLIPPABLE_JOINS}).`
+      lc?.warn?.(
+        `Query has ${flippableJoins.length} EXISTS checks which would require ${2 ** flippableJoins.length} plan evaluations. Skipping optimization.`
       );
+      return;
     }
     const fofiCache = buildFOFICache(this);
     const numPatterns = flippableJoins.length === 0 ? 0 : 2 ** flippableJoins.length;