@rocicorp/zero 0.25.0-canary.8 → 0.25.0-canary.9

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

@@ -0,0 +1,98 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ReadonlyJSONValue } from '../../../shared/src/json.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 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>;
+/**
+ * The return type of defineMutatorWithType. A function matching the
+ * defineMutator overloads but with Schema, Context, and WrappedTransaction
+ * pre-bound.
+ */
+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>;
+};
+/**
+ * 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`.
+ *
+ * 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;
+    /**
+     * 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>;
+};
+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;
+};
+/**
+ * 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

@@ -0,0 +1 @@
+{"version":3,"file":"mutator.d.ts","sourceRoot":"","sources":["../../../../../zql/src/mutate/mutator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,6BAA6B,CAAC;AAEnE,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mCAAmC,CAAC;AAC9D,OAAO,KAAK,EAAC,cAAc,EAAE,WAAW,EAAC,MAAM,aAAa,CAAC;AAM7D,QAAA,MAAM,gBAAgB,eAAW,CAAC;AAElC,wBAAgB,mBAAmB,CACjC,OAAO,SAAS,MAAM,EACtB,QAAQ,EACR,MAAM,SAAS,iBAAiB,GAAG,SAAS,EAC5C,OAAO,SAAS,iBAAiB,GAAG,SAAS,EAC7C,mBAAmB,GAAG,OAAO,EAE7B,CAAC,EAAE,OAAO,GACT,CAAC,IAAI,iBAAiB,CACvB,OAAO,EACP,QAAQ,EACR,MAAM,EACN,OAAO,EACP,mBAAmB,CACpB,CAGA;AAED,MAAM,MAAM,iBAAiB,CAC3B,OAAO,SAAS,MAAM,EACtB,QAAQ,EACR,MAAM,SAAS,iBAAiB,GAAG,SAAS,EAC5C,OAAO,SAAS,iBAAiB,GAAG,SAAS,EAC7C,mBAAmB,IACjB,CAAC,CAAC,OAAO,EAAE;IACb,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,QAAQ,CAAC;IACd,EAAE,EAAE,WAAW,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;CAC/C,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG;IACrB,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC;IACzB,SAAS,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC1D,CAAC;AAGF,wBAAgB,aAAa,CAC3B,OAAO,SAAS,MAAM,EACtB,QAAQ,EACR,MAAM,SAAS,iBAAiB,GAAG,SAAS,EAC5C,OAAO,SAAS,iBAAiB,GAAG,SAAS,EAC7C,mBAAmB,EAEnB,SAAS,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5C,OAAO,EAAE,CAAC,OAAO,EAAE;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,QAAQ,CAAC;IACd,EAAE,EAAE,WAAW,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;CAC/C,KAAK,OAAO,CAAC,IAAI,CAAC,GAClB,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC;AAG9E,wBAAgB,aAAa,CAC3B,OAAO,SAAS,MAAM,EACtB,QAAQ,EACR,KAAK,SAAS,iBAAiB,GAAG,SAAS,EAC3C,mBAAmB,EAEnB,OAAO,EAAE,CAAC,OAAO,EAAE;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,QAAQ,CAAC;IACd,EAAE,EAAE,WAAW,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;CAC/C,KAAK,OAAO,CAAC,IAAI,CAAC,GAClB,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,CAAC,CAAC;AAqD3E,wBAAgB,qBAAqB,CACnC,OAAO,SAAS,MAAM,KACnB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAGnD,wBAAgB,qBAAqB,CACnC,OAAO,SAAS,MAAM,EACtB,QAAQ,KACL,kBAAkB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAGpD,wBAAgB,qBAAqB,CACnC,OAAO,SAAS,MAAM,EACtB,QAAQ,EACR,mBAAmB,KAChB,kBAAkB,CAAC,OAAO,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC;AAOhE;;;;GAIG;AACH,KAAK,kBAAkB,CACrB,OAAO,SAAS,MAAM,EACtB,QAAQ,EACR,mBAAmB,IACjB;IAEF,CAAC,KAAK,SAAS,iBAAiB,GAAG,SAAS,EAC1C,OAAO,EAAE,CAAC,OAAO,EAAE;QACjB,IAAI,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,QAAQ,CAAC;QACd,EAAE,EAAE,WAAW,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;KAC/C,KAAK,OAAO,CAAC,IAAI,CAAC,GAClB,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,CAAC,CAAC;IAG3E,CACE,MAAM,SAAS,iBAAiB,GAAG,SAAS,EAC5C,OAAO,SAAS,iBAAiB,GAAG,SAAS,EAE7C,SAAS,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5C,OAAO,EAAE,CAAC,OAAO,EAAE;QACjB,IAAI,EAAE,OAAO,CAAC;QACd,GAAG,EAAE,QAAQ,CAAC;QACd,EAAE,EAAE,WAAW,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;KAC/C,KAAK,OAAO,CAAC,IAAI,CAAC,GAClB,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC;CAC/E,CAAC;AAMF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,OAAO,CACjB,OAAO,SAAS,MAAM,EACtB,QAAQ,EACR,UAAU,SAAS,iBAAiB,GAAG,SAAS,EAChD,mBAAmB,GAAG,OAAO,IAC3B,eAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,CAAC,GAAG;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE;QACrB,IAAI,EAAE,UAAU,CAAC;QACjB,GAAG,EAAE,QAAQ,CAAC;QACd,EAAE,EAAE,cAAc,CAAC;KACpB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB,CAAC;AAMF,KAAK,eAAe,CAClB,OAAO,SAAS,MAAM,EACtB,QAAQ,EACR,UAAU,SAAS,iBAAiB,GAAG,SAAS,EAChD,mBAAmB,IACjB,CAAC,UAAU,CAAC,SAAS,CAAC,SAAS,CAAC,GAChC,MAAM,eAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,CAAC,GACzE,SAAS,SAAS,UAAU,GAC1B,CACE,IAAI,CAAC,EAAE,UAAU,KACd,eAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,CAAC,GACxE,CACE,IAAI,EAAE,UAAU,KACb,eAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,CAAC,CAAC;AAG/E,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,CACzB,OAAO,SAAS,MAAM,EACtB,QAAQ,EACR,UAAU,SAAS,iBAAiB,GAAG,SAAS,EAChD,mBAAmB,IACjB;IACF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,CAAC,CAAC;IAC9E,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAQ7D"}

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

@@ -0,0 +1,35 @@
+import { must } from "../../../shared/src/must.js";
+const defineMutatorTag = Symbol();
+function isMutatorDefinition(f) {
+  return typeof f === "function" && !!f[defineMutatorTag];
+}
+function defineMutator(validatorOrMutator, mutator) {
+  let validator;
+  let actualMutator;
+  if (typeof validatorOrMutator === "function") {
+    validator = void 0;
+    actualMutator = validatorOrMutator;
+  } else {
+    validator = validatorOrMutator;
+    actualMutator = must(mutator);
+  }
+  const f = actualMutator;
+  f[defineMutatorTag] = true;
+  f.validator = validator;
+  return f;
+}
+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";
+}
+export {
+  defineMutator,
+  defineMutatorWithType,
+  isMutator,
+  isMutatorDefinition
+};
+//# sourceMappingURL=mutator.js.map

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

@@ -0,0 +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;"}

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

@@ -100,22 +100,14 @@ export declare class PlannerConnection {
      * Used by PlannerGraph to restore planning state.
      */
     restoreConstraints(constraints: Map<string, PlannerConstraint | undefined>): void;
-    /**
-     * Get current constraints for debugging.
-     * Returns a copy of the constraints map.
-     */
-    getConstraintsForDebug(): Map<string, PlannerConstraint | undefined>;
-    /**
-     * Get filters for debugging.
-     * Returns the filters applied to this connection.
-     */
+    /** Get current constraints for debugging. */
+    getConstraintsForDebug(): Record<string, PlannerConstraint | undefined>;
+    /** Get filters for debugging. */
     getFiltersForDebug(): Condition | undefined;
-    /**
-     * Get estimated cost for each constraint branch.
-     * Returns a map of constraint key to cost estimate.
-     * Forces cost calculation if not already cached.
-     */
-    getConstraintCostsForDebug(): Map<string, CostEstimate>;
+    /** Get sort/ordering for debugging. */
+    getSortForDebug(): Ordering;
+    /** Get estimated cost for each constraint branch. */
+    getConstraintCostsForDebug(): Record<string, CostEstimate>;
 }
 type FanoutEst = {
     fanout: number;

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

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

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

@@ -1,5 +1,6 @@
 import { assert } from "../../../shared/src/asserts.js";
 import { mergeConstraints } from "./planner-constraint.js";
+import { omitFanout } from "./planner-node.js";
 class PlannerConnection {
   kind = "connection";
   // ========================================================================
@@ -126,15 +127,18 @@ class PlannerConnection {
       fanout
     };
     this.#cachedConstraintCosts.set(key, cost);
-    planDebugger?.log({
-      type: "node-cost",
-      nodeType: "connection",
-      node: this.name,
-      branchPattern,
-      downstreamChildSelectivity,
-      costEstimate: cost,
-      filters: this.#filters
-    });
+    if (planDebugger) {
+      planDebugger.log({
+        type: "node-cost",
+        nodeType: "connection",
+        node: this.name,
+        branchPattern,
+        downstreamChildSelectivity,
+        costEstimate: omitFanout(cost),
+        filters: this.#filters,
+        ordering: this.#sort
+      });
+    }
     return cost;
   }
   /**
@@ -180,27 +184,29 @@ class PlannerConnection {
     }
     this.#cachedConstraintCosts.clear();
   }
-  /**
-   * Get current constraints for debugging.
-   * Returns a copy of the constraints map.
-   */
+  /** Get current constraints for debugging. */
   getConstraintsForDebug() {
-    return new Map(this.#constraints);
+    const record = {};
+    for (const [key, value] of this.#constraints) {
+      record[key] = value;
+    }
+    return record;
   }
-  /**
-   * Get filters for debugging.
-   * Returns the filters applied to this connection.
-   */
+  /** Get filters for debugging. */
   getFiltersForDebug() {
     return this.#filters;
   }
-  /**
-   * Get estimated cost for each constraint branch.
-   * Returns a map of constraint key to cost estimate.
-   * Forces cost calculation if not already cached.
-   */
+  /** Get sort/ordering for debugging. */
+  getSortForDebug() {
+    return this.#sort;
+  }
+  /** Get estimated cost for each constraint branch. */
   getConstraintCostsForDebug() {
-    return new Map(this.#cachedConstraintCosts);
+    const record = {};
+    for (const [key, value] of this.#cachedConstraintCosts) {
+      record[key] = value;
+    }
+    return record;
   }
 }
 export {

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

@@ -1 +1 @@
-{"version":3,"file":"planner-connection.js","sources":["../../../../../zql/src/planner/planner-connection.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport type {Condition, Ordering} from '../../../zero-protocol/src/ast.ts';\nimport {\n  mergeConstraints,\n  type PlannerConstraint,\n} from './planner-constraint.ts';\nimport type {PlanDebugger} from './planner-debug.ts';\nimport type {\n  CostEstimate,\n  JoinOrConnection,\n  PlannerNode,\n} from './planner-node.ts';\n\n/**\n * Represents a connection to a source (table scan).\n *\n * # Dual State Pattern\n * Like all planner nodes, PlannerConnection separates:\n * 1. immutable structure: Ordering, filters, cost model (set at construction)\n * 2. mutable state: Pinned status, constraints (mutated during planning)\n *\n * # Cost Estimation\n * The ordering and filters determine the initial cost. As planning progresses,\n * constraints from parent joins refine the cost estimate.\n *\n * # Constraint Flow\n * When a connection is pinned as the outer loop, it reveals constraints for\n * connected joins. These constraints propagate through the graph, allowing\n * other connections to update their cost estimates.\n *\n * Example:\n *\n * ```ts\n * builder.issue.whereExists('assignee', a => a.where('name', 'Alice'))\n * ```\n *\n * ```\n * [issue]  [assignee]\n *   |         |\n *   |         +-- where name = 'Alice'\n *    \\        /\n *     \\      /\n *      [join]\n *        |\n * ```\n *\n * - Initial state: Both connections have no constraints, costs are unconstrained\n * - If `issue` chosen first: Reveals constraint `assignee_id` for assignee connection\n * - If `assignee` chosen first: Reveals constraint `assignee_id` for issue connection\n * - Updated costs guide the next selection\n *\n * # Lifecycle\n * 1. Construct with immutable structure (ordering, filters, cost model)\n * 2. Wire to output node during graph construction\n * 3. Planning mutates pinned status and accumulates constraints\n * 4. reset() clears mutable state for replanning\n */\nexport class PlannerConnection {\n  readonly kind = 'connection' as const;\n\n  // ========================================================================\n  // IMMUTABLE STRUCTURE (set during construction, never changes)\n  // ========================================================================\n  readonly #sort: Ordering;\n  readonly #filters: Condition | undefined;\n  readonly #model: ConnectionCostModel;\n  readonly table: string;\n  readonly name: string; // Human-readable name for debugging (defaults to table name)\n  readonly #baseConstraints: PlannerConstraint | undefined; // Constraints from parent correlation\n  readonly #baseLimit: number | undefined; // Original limit from query structure (never modified)\n  readonly selectivity: number; // Fraction of rows passing filters (1.0 = no filtering)\n  #output?: PlannerNode | undefined; // Set once during graph construction\n\n  // ========================================================================\n  // MUTABLE PLANNING STATE (changes during plan search)\n  // ========================================================================\n  /**\n   * Current limit during planning. Can be cleared (set to undefined) when a\n   * parent join is flipped, indicating this connection is now in an outer loop\n   * and should not be limited by EXISTS semantics.\n   */\n  limit: number | undefined;\n\n  /**\n   * Constraints accumulated from parent joins during planning.\n   * Key is a path through the graph (e.g., \"0,1\" for branch pattern [0,1]).\n   *\n   * Undefined constraints are possible when a FO converts to UFO and only\n   * a single join in the UFO is flipped - other branches report undefined.\n   */\n  readonly #constraints: Map<string, PlannerConstraint | undefined>;\n\n  readonly #isRoot: boolean;\n\n  /**\n   * Cached per-constraint costs to avoid redundant cost model calls.\n   * Maps constraint key (branch pattern string) to computed cost.\n   * Invalidated when constraints change.\n   */\n  #cachedConstraintCosts: Map<string, CostEstimate> = new Map();\n\n  constructor(\n    table: string,\n    model: ConnectionCostModel,\n    sort: Ordering,\n    filters: Condition | undefined,\n    isRoot: boolean,\n    baseConstraints?: PlannerConstraint,\n    limit?: number,\n    name?: string,\n  ) {\n    this.table = table;\n    this.name = name ?? table;\n    this.#sort = sort;\n    this.#filters = filters;\n    this.#model = model;\n    this.#baseConstraints = baseConstraints;\n    this.#baseLimit = limit;\n    this.limit = limit;\n    this.#constraints = new Map();\n    this.#isRoot = isRoot;\n\n    // Compute selectivity for EXISTS child connections (baseLimit === 1)\n    // Selectivity = fraction of rows that pass filters\n    if (limit !== undefined && filters) {\n      const costWithFilters = model(table, sort, filters, undefined);\n      const costWithoutFilters = model(table, sort, undefined, undefined);\n      this.selectivity =\n        costWithoutFilters.rows > 0\n          ? costWithFilters.rows / costWithoutFilters.rows\n          : 1.0;\n    } else {\n      // Root connections or connections without filters\n      this.selectivity = 1.0;\n    }\n  }\n\n  setOutput(node: PlannerNode): void {\n    this.#output = node;\n  }\n\n  get output(): PlannerNode {\n    assert(this.#output !== undefined, 'Output not set');\n    return this.#output;\n  }\n\n  closestJoinOrSource(): JoinOrConnection {\n    return 'connection';\n  }\n\n  /**\n   * Constraints are uniquely identified by their path through the\n   * graph.\n   *\n   * FO represents all sub-joins as a single path.\n   * UFO represents each sub-join as a separate path.\n   * The first branch in a UFO will match the path of FO so no re-set needs to happen\n   * when swapping from FO to UFO.\n   *\n   * FO swaps to UFO when a join inside FO-FI gets flipped.\n   *\n   * The max of the last element of the paths is the number of\n   * root branches.\n   */\n  propagateConstraints(\n    path: number[],\n    c: PlannerConstraint | undefined,\n    from?: PlannerNode,\n    planDebugger?: PlanDebugger,\n  ): void {\n    const key = path.join(',');\n    this.#constraints.set(key, c);\n    // Constraints changed, invalidate cost caches\n    this.#cachedConstraintCosts.clear();\n\n    planDebugger?.log({\n      type: 'node-constraint',\n      nodeType: 'connection',\n      node: this.name,\n      branchPattern: path,\n      constraint: c,\n      from: from?.kind ?? 'unknown',\n    });\n  }\n\n  estimateCost(\n    downstreamChildSelectivity: number,\n    branchPattern: number[],\n    planDebugger?: PlanDebugger,\n  ): CostEstimate {\n    // Branch pattern specified - return cost for this specific branch\n    const key = branchPattern.join(',');\n\n    // Check per-constraint cache first\n    let cost = this.#cachedConstraintCosts.get(key);\n    if (cost !== undefined) {\n      return cost;\n    }\n\n    // Cache miss - compute and cache\n    const constraint = this.#constraints.get(key);\n    // Merge base constraints with propagated constraints\n    const mergedConstraint = mergeConstraints(\n      this.#baseConstraints,\n      constraint,\n    );\n    const {startupCost, fanout, rows} = this.#model(\n      this.table,\n      this.#sort,\n      this.#filters,\n      mergedConstraint,\n    );\n    cost = {\n      startupCost,\n      scanEst:\n        this.limit === undefined\n          ? rows\n          : Math.min(rows, this.limit / downstreamChildSelectivity),\n      cost: 0,\n      returnedRows: rows,\n      selectivity: this.selectivity,\n      limit: this.limit,\n      fanout,\n    };\n    this.#cachedConstraintCosts.set(key, cost);\n\n    planDebugger?.log({\n      type: 'node-cost',\n      nodeType: 'connection',\n      node: this.name,\n      branchPattern,\n      downstreamChildSelectivity,\n      costEstimate: cost,\n      filters: this.#filters,\n    });\n\n    return cost;\n  }\n\n  /**\n   * Remove the limit from this connection.\n   * Called when a parent join is flipped, making this connection part of an\n   * outer loop that should produce all rows rather than stopping at the limit.\n   */\n  unlimit(): void {\n    if (this.#isRoot) {\n      // We cannot unlimit root connections\n      return;\n    }\n    if (this.limit !== undefined) {\n      this.limit = undefined;\n      // Limit changes do not impact connection costs.\n      // Limit is taken into account at the join level.\n      // Given that, we do not need to invalidate cost caches here.\n    }\n  }\n\n  /**\n   * Propagate unlimiting when a parent join is flipped.\n   * For connections, we simply remove the limit.\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    this.unlimit();\n  }\n\n  reset() {\n    this.#constraints.clear();\n    this.limit = this.#baseLimit;\n    // Clear all cost caches\n    this.#cachedConstraintCosts.clear();\n  }\n\n  /**\n   * Capture constraint state for snapshotting.\n   * Used by PlannerGraph to save/restore planning state.\n   */\n  captureConstraints(): Map<string, PlannerConstraint | undefined> {\n    return new Map(this.#constraints);\n  }\n\n  /**\n   * Restore constraint state from a snapshot.\n   * Used by PlannerGraph to restore planning state.\n   */\n  restoreConstraints(\n    constraints: Map<string, PlannerConstraint | undefined>,\n  ): void {\n    this.#constraints.clear();\n    for (const [key, value] of constraints) {\n      this.#constraints.set(key, value);\n    }\n    // Constraints changed, invalidate cost caches\n    this.#cachedConstraintCosts.clear();\n  }\n\n  /**\n   * Get current constraints for debugging.\n   * Returns a copy of the constraints map.\n   */\n  getConstraintsForDebug(): Map<string, PlannerConstraint | undefined> {\n    return new Map(this.#constraints);\n  }\n\n  /**\n   * Get filters for debugging.\n   * Returns the filters applied to this connection.\n   */\n  getFiltersForDebug(): Condition | undefined {\n    return this.#filters;\n  }\n\n  /**\n   * Get estimated cost for each constraint branch.\n   * Returns a map of constraint key to cost estimate.\n   * Forces cost calculation if not already cached.\n   */\n  getConstraintCostsForDebug(): Map<string, CostEstimate> {\n    // Return copy of cached costs\n    return new Map(this.#cachedConstraintCosts);\n  }\n}\n\ntype FanoutEst = {\n  fanout: number;\n  confidence: 'high' | 'med' | 'none';\n};\nexport type FanoutCostModel = (columns: string[]) => FanoutEst;\n\nexport type CostModelCost = {\n  startupCost: number;\n  rows: number;\n  fanout: FanoutCostModel;\n};\nexport type ConnectionCostModel = (\n  table: string,\n  sort: Ordering,\n  filters: Condition | undefined,\n  constraint: PlannerConstraint | undefined,\n) => CostModelCost;\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"planner-connection.js","sources":["../../../../../zql/src/planner/planner-connection.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport type {Condition, Ordering} from '../../../zero-protocol/src/ast.ts';\nimport {\n  mergeConstraints,\n  type PlannerConstraint,\n} from './planner-constraint.ts';\nimport type {PlanDebugger} from './planner-debug.ts';\nimport {omitFanout} from './planner-node.ts';\nimport type {\n  CostEstimate,\n  JoinOrConnection,\n  PlannerNode,\n} from './planner-node.ts';\n\n/**\n * Represents a connection to a source (table scan).\n *\n * # Dual State Pattern\n * Like all planner nodes, PlannerConnection separates:\n * 1. immutable structure: Ordering, filters, cost model (set at construction)\n * 2. mutable state: Pinned status, constraints (mutated during planning)\n *\n * # Cost Estimation\n * The ordering and filters determine the initial cost. As planning progresses,\n * constraints from parent joins refine the cost estimate.\n *\n * # Constraint Flow\n * When a connection is pinned as the outer loop, it reveals constraints for\n * connected joins. These constraints propagate through the graph, allowing\n * other connections to update their cost estimates.\n *\n * Example:\n *\n * ```ts\n * builder.issue.whereExists('assignee', a => a.where('name', 'Alice'))\n * ```\n *\n * ```\n * [issue]  [assignee]\n *   |         |\n *   |         +-- where name = 'Alice'\n *    \\        /\n *     \\      /\n *      [join]\n *        |\n * ```\n *\n * - Initial state: Both connections have no constraints, costs are unconstrained\n * - If `issue` chosen first: Reveals constraint `assignee_id` for assignee connection\n * - If `assignee` chosen first: Reveals constraint `assignee_id` for issue connection\n * - Updated costs guide the next selection\n *\n * # Lifecycle\n * 1. Construct with immutable structure (ordering, filters, cost model)\n * 2. Wire to output node during graph construction\n * 3. Planning mutates pinned status and accumulates constraints\n * 4. reset() clears mutable state for replanning\n */\nexport class PlannerConnection {\n  readonly kind = 'connection' as const;\n\n  // ========================================================================\n  // IMMUTABLE STRUCTURE (set during construction, never changes)\n  // ========================================================================\n  readonly #sort: Ordering;\n  readonly #filters: Condition | undefined;\n  readonly #model: ConnectionCostModel;\n  readonly table: string;\n  readonly name: string; // Human-readable name for debugging (defaults to table name)\n  readonly #baseConstraints: PlannerConstraint | undefined; // Constraints from parent correlation\n  readonly #baseLimit: number | undefined; // Original limit from query structure (never modified)\n  readonly selectivity: number; // Fraction of rows passing filters (1.0 = no filtering)\n  #output?: PlannerNode | undefined; // Set once during graph construction\n\n  // ========================================================================\n  // MUTABLE PLANNING STATE (changes during plan search)\n  // ========================================================================\n  /**\n   * Current limit during planning. Can be cleared (set to undefined) when a\n   * parent join is flipped, indicating this connection is now in an outer loop\n   * and should not be limited by EXISTS semantics.\n   */\n  limit: number | undefined;\n\n  /**\n   * Constraints accumulated from parent joins during planning.\n   * Key is a path through the graph (e.g., \"0,1\" for branch pattern [0,1]).\n   *\n   * Undefined constraints are possible when a FO converts to UFO and only\n   * a single join in the UFO is flipped - other branches report undefined.\n   */\n  readonly #constraints: Map<string, PlannerConstraint | undefined>;\n\n  readonly #isRoot: boolean;\n\n  /**\n   * Cached per-constraint costs to avoid redundant cost model calls.\n   * Maps constraint key (branch pattern string) to computed cost.\n   * Invalidated when constraints change.\n   */\n  #cachedConstraintCosts: Map<string, CostEstimate> = new Map();\n\n  constructor(\n    table: string,\n    model: ConnectionCostModel,\n    sort: Ordering,\n    filters: Condition | undefined,\n    isRoot: boolean,\n    baseConstraints?: PlannerConstraint,\n    limit?: number,\n    name?: string,\n  ) {\n    this.table = table;\n    this.name = name ?? table;\n    this.#sort = sort;\n    this.#filters = filters;\n    this.#model = model;\n    this.#baseConstraints = baseConstraints;\n    this.#baseLimit = limit;\n    this.limit = limit;\n    this.#constraints = new Map();\n    this.#isRoot = isRoot;\n\n    // Compute selectivity for EXISTS child connections (baseLimit === 1)\n    // Selectivity = fraction of rows that pass filters\n    if (limit !== undefined && filters) {\n      const costWithFilters = model(table, sort, filters, undefined);\n      const costWithoutFilters = model(table, sort, undefined, undefined);\n      this.selectivity =\n        costWithoutFilters.rows > 0\n          ? costWithFilters.rows / costWithoutFilters.rows\n          : 1.0;\n    } else {\n      // Root connections or connections without filters\n      this.selectivity = 1.0;\n    }\n  }\n\n  setOutput(node: PlannerNode): void {\n    this.#output = node;\n  }\n\n  get output(): PlannerNode {\n    assert(this.#output !== undefined, 'Output not set');\n    return this.#output;\n  }\n\n  closestJoinOrSource(): JoinOrConnection {\n    return 'connection';\n  }\n\n  /**\n   * Constraints are uniquely identified by their path through the\n   * graph.\n   *\n   * FO represents all sub-joins as a single path.\n   * UFO represents each sub-join as a separate path.\n   * The first branch in a UFO will match the path of FO so no re-set needs to happen\n   * when swapping from FO to UFO.\n   *\n   * FO swaps to UFO when a join inside FO-FI gets flipped.\n   *\n   * The max of the last element of the paths is the number of\n   * root branches.\n   */\n  propagateConstraints(\n    path: number[],\n    c: PlannerConstraint | undefined,\n    from?: PlannerNode,\n    planDebugger?: PlanDebugger,\n  ): void {\n    const key = path.join(',');\n    this.#constraints.set(key, c);\n    // Constraints changed, invalidate cost caches\n    this.#cachedConstraintCosts.clear();\n\n    planDebugger?.log({\n      type: 'node-constraint',\n      nodeType: 'connection',\n      node: this.name,\n      branchPattern: path,\n      constraint: c,\n      from: from?.kind ?? 'unknown',\n    });\n  }\n\n  estimateCost(\n    downstreamChildSelectivity: number,\n    branchPattern: number[],\n    planDebugger?: PlanDebugger,\n  ): CostEstimate {\n    // Branch pattern specified - return cost for this specific branch\n    const key = branchPattern.join(',');\n\n    // Check per-constraint cache first\n    let cost = this.#cachedConstraintCosts.get(key);\n    if (cost !== undefined) {\n      return cost;\n    }\n\n    // Cache miss - compute and cache\n    const constraint = this.#constraints.get(key);\n    // Merge base constraints with propagated constraints\n    const mergedConstraint = mergeConstraints(\n      this.#baseConstraints,\n      constraint,\n    );\n    const {startupCost, fanout, rows} = this.#model(\n      this.table,\n      this.#sort,\n      this.#filters,\n      mergedConstraint,\n    );\n    cost = {\n      startupCost,\n      scanEst:\n        this.limit === undefined\n          ? rows\n          : Math.min(rows, this.limit / downstreamChildSelectivity),\n      cost: 0,\n      returnedRows: rows,\n      selectivity: this.selectivity,\n      limit: this.limit,\n      fanout,\n    };\n    this.#cachedConstraintCosts.set(key, cost);\n\n    if (planDebugger) {\n      planDebugger.log({\n        type: 'node-cost',\n        nodeType: 'connection',\n        node: this.name,\n        branchPattern,\n        downstreamChildSelectivity,\n        costEstimate: omitFanout(cost),\n        filters: this.#filters,\n        ordering: this.#sort,\n      });\n    }\n\n    return cost;\n  }\n\n  /**\n   * Remove the limit from this connection.\n   * Called when a parent join is flipped, making this connection part of an\n   * outer loop that should produce all rows rather than stopping at the limit.\n   */\n  unlimit(): void {\n    if (this.#isRoot) {\n      // We cannot unlimit root connections\n      return;\n    }\n    if (this.limit !== undefined) {\n      this.limit = undefined;\n      // Limit changes do not impact connection costs.\n      // Limit is taken into account at the join level.\n      // Given that, we do not need to invalidate cost caches here.\n    }\n  }\n\n  /**\n   * Propagate unlimiting when a parent join is flipped.\n   * For connections, we simply remove the limit.\n   */\n  propagateUnlimitFromFlippedJoin(): void {\n    this.unlimit();\n  }\n\n  reset() {\n    this.#constraints.clear();\n    this.limit = this.#baseLimit;\n    // Clear all cost caches\n    this.#cachedConstraintCosts.clear();\n  }\n\n  /**\n   * Capture constraint state for snapshotting.\n   * Used by PlannerGraph to save/restore planning state.\n   */\n  captureConstraints(): Map<string, PlannerConstraint | undefined> {\n    return new Map(this.#constraints);\n  }\n\n  /**\n   * Restore constraint state from a snapshot.\n   * Used by PlannerGraph to restore planning state.\n   */\n  restoreConstraints(\n    constraints: Map<string, PlannerConstraint | undefined>,\n  ): void {\n    this.#constraints.clear();\n    for (const [key, value] of constraints) {\n      this.#constraints.set(key, value);\n    }\n    // Constraints changed, invalidate cost caches\n    this.#cachedConstraintCosts.clear();\n  }\n\n  /** Get current constraints for debugging. */\n  getConstraintsForDebug(): Record<string, PlannerConstraint | undefined> {\n    const record: Record<string, PlannerConstraint | undefined> = {};\n    for (const [key, value] of this.#constraints) {\n      record[key] = value;\n    }\n    return record;\n  }\n\n  /** Get filters for debugging. */\n  getFiltersForDebug(): Condition | undefined {\n    return this.#filters;\n  }\n\n  /** Get sort/ordering for debugging. */\n  getSortForDebug(): Ordering {\n    return this.#sort;\n  }\n\n  /** Get estimated cost for each constraint branch. */\n  getConstraintCostsForDebug(): Record<string, CostEstimate> {\n    const record: Record<string, CostEstimate> = {};\n    for (const [key, value] of this.#cachedConstraintCosts) {\n      record[key] = value;\n    }\n    return record;\n  }\n}\n\ntype FanoutEst = {\n  fanout: number;\n  confidence: 'high' | 'med' | 'none';\n};\nexport type FanoutCostModel = (columns: string[]) => FanoutEst;\n\nexport type CostModelCost = {\n  startupCost: number;\n  rows: number;\n  fanout: FanoutCostModel;\n};\nexport type ConnectionCostModel = (\n  table: string,\n  sort: Ordering,\n  filters: Condition | undefined,\n  constraint: PlannerConstraint | undefined,\n) => CostModelCost;\n"],"names":[],"mappings":";;;AA0DO,MAAM,kBAAkB;AAAA,EACpB,OAAO;AAAA;AAAA;AAAA;AAAA,EAKP;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASS;AAAA,EAEA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOT,6CAAwD,IAAA;AAAA,EAExD,YACE,OACA,OACA,MACA,SACA,QACA,iBACA,OACA,MACA;AACA,SAAK,QAAQ;AACb,SAAK,OAAO,QAAQ;AACpB,SAAK,QAAQ;AACb,SAAK,WAAW;AAChB,SAAK,SAAS;AACd,SAAK,mBAAmB;AACxB,SAAK,aAAa;AAClB,SAAK,QAAQ;AACb,SAAK,mCAAmB,IAAA;AACxB,SAAK,UAAU;AAIf,QAAI,UAAU,UAAa,SAAS;AAClC,YAAM,kBAAkB,MAAM,OAAO,MAAM,SAAS,MAAS;AAC7D,YAAM,qBAAqB,MAAM,OAAO,MAAM,QAAW,MAAS;AAClE,WAAK,cACH,mBAAmB,OAAO,IACtB,gBAAgB,OAAO,mBAAmB,OAC1C;AAAA,IACR,OAAO;AAEL,WAAK,cAAc;AAAA,IACrB;AAAA,EACF;AAAA,EAEA,UAAU,MAAyB;AACjC,SAAK,UAAU;AAAA,EACjB;AAAA,EAEA,IAAI,SAAsB;AACxB,WAAO,KAAK,YAAY,QAAW,gBAAgB;AACnD,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,sBAAwC;AACtC,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgBA,qBACE,MACA,GACA,MACA,cACM;AACN,UAAM,MAAM,KAAK,KAAK,GAAG;AACzB,SAAK,aAAa,IAAI,KAAK,CAAC;AAE5B,SAAK,uBAAuB,MAAA;AAE5B,kBAAc,IAAI;AAAA,MAChB,MAAM;AAAA,MACN,UAAU;AAAA,MACV,MAAM,KAAK;AAAA,MACX,eAAe;AAAA,MACf,YAAY;AAAA,MACZ,MAAM,MAAM,QAAQ;AAAA,IAAA,CACrB;AAAA,EACH;AAAA,EAEA,aACE,4BACA,eACA,cACc;AAEd,UAAM,MAAM,cAAc,KAAK,GAAG;AAGlC,QAAI,OAAO,KAAK,uBAAuB,IAAI,GAAG;AAC9C,QAAI,SAAS,QAAW;AACtB,aAAO;AAAA,IACT;AAGA,UAAM,aAAa,KAAK,aAAa,IAAI,GAAG;AAE5C,UAAM,mBAAmB;AAAA,MACvB,KAAK;AAAA,MACL;AAAA,IAAA;AAEF,UAAM,EAAC,aAAa,QAAQ,KAAA,IAAQ,KAAK;AAAA,MACvC,KAAK;AAAA,MACL,KAAK;AAAA,MACL,KAAK;AAAA,MACL;AAAA,IAAA;AAEF,WAAO;AAAA,MACL;AAAA,MACA,SACE,KAAK,UAAU,SACX,OACA,KAAK,IAAI,MAAM,KAAK,QAAQ,0BAA0B;AAAA,MAC5D,MAAM;AAAA,MACN,cAAc;AAAA,MACd,aAAa,KAAK;AAAA,MAClB,OAAO,KAAK;AAAA,MACZ;AAAA,IAAA;AAEF,SAAK,uBAAuB,IAAI,KAAK,IAAI;AAEzC,QAAI,cAAc;AAChB,mBAAa,IAAI;AAAA,QACf,MAAM;AAAA,QACN,UAAU;AAAA,QACV,MAAM,KAAK;AAAA,QACX;AAAA,QACA;AAAA,QACA,cAAc,WAAW,IAAI;AAAA,QAC7B,SAAS,KAAK;AAAA,QACd,UAAU,KAAK;AAAA,MAAA,CAChB;AAAA,IACH;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,UAAgB;AACd,QAAI,KAAK,SAAS;AAEhB;AAAA,IACF;AACA,QAAI,KAAK,UAAU,QAAW;AAC5B,WAAK,QAAQ;AAAA,IAIf;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,kCAAwC;AACtC,SAAK,QAAA;AAAA,EACP;AAAA,EAEA,QAAQ;AACN,SAAK,aAAa,MAAA;AAClB,SAAK,QAAQ,KAAK;AAElB,SAAK,uBAAuB,MAAA;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,qBAAiE;AAC/D,WAAO,IAAI,IAAI,KAAK,YAAY;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,mBACE,aACM;AACN,SAAK,aAAa,MAAA;AAClB,eAAW,CAAC,KAAK,KAAK,KAAK,aAAa;AACtC,WAAK,aAAa,IAAI,KAAK,KAAK;AAAA,IAClC;AAEA,SAAK,uBAAuB,MAAA;AAAA,EAC9B;AAAA;AAAA,EAGA,yBAAwE;AACtE,UAAM,SAAwD,CAAA;AAC9D,eAAW,CAAC,KAAK,KAAK,KAAK,KAAK,cAAc;AAC5C,aAAO,GAAG,IAAI;AAAA,IAChB;AACA,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,qBAA4C;AAC1C,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,kBAA4B;AAC1B,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,6BAA2D;AACzD,UAAM,SAAuC,CAAA;AAC7C,eAAW,CAAC,KAAK,KAAK,KAAK,KAAK,wBAAwB;AACtD,aAAO,GAAG,IAAI;AAAA,IAChB;AACA,WAAO;AAAA,EACT;AACF;"}

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

@@ -1,4 +1,6 @@
-import type { Condition } from '../../../zero-protocol/src/ast.ts';
+import type * as v from '../../../shared/src/valita.ts';
+import type { Condition, Ordering } from '../../../zero-protocol/src/ast.ts';
+import type { attemptStartEventJSONSchema, bestPlanSelectedEventJSONSchema, connectionSelectedEventJSONSchema, nodeConstraintEventJSONSchema, PlanDebugEventJSON, planFailedEventJSONSchema } from '../../../zero-protocol/src/analyze-query-result.ts';
 import type { PlannerConstraint } from './planner-constraint.ts';
 import type { CostEstimate, JoinType } from './planner-node.ts';
 import type { PlanState } from './planner-graph.ts';
@@ -10,11 +12,7 @@ import type { PlanState } from './planner-graph.ts';
 /**
  * Starting a new planning attempt with a different root connection.
  */
-export type AttemptStartEvent = {
-    type: 'attempt-start';
-    attemptNumber: number;
-    totalAttempts: number;
-};
+export type AttemptStartEvent = v.Infer<typeof attemptStartEventJSONSchema>;
 /**
  * Snapshot of connection costs before selecting the next connection.
  */
@@ -24,22 +22,16 @@ export type ConnectionCostsEvent = {
     costs: Array<{
         connection: string;
         cost: number;
-        costEstimate: CostEstimate;
+        costEstimate: Omit<CostEstimate, 'fanout'>;
         pinned: boolean;
-        constraints: Map<string, PlannerConstraint | undefined>;
-        constraintCosts: Map<string, CostEstimate>;
+        constraints: Record<string, PlannerConstraint | undefined>;
+        constraintCosts: Record<string, Omit<CostEstimate, 'fanout'>>;
     }>;
 };
 /**
  * A connection was chosen and pinned.
  */
-export type ConnectionSelectedEvent = {
-    type: 'connection-selected';
-    attemptNumber: number;
-    connection: string;
-    cost: number;
-    isRoot: boolean;
-};
+export type ConnectionSelectedEvent = v.Infer<typeof connectionSelectedEventJSONSchema>;
 /**
  * Constraints have been propagated through the graph.
  */
@@ -48,8 +40,8 @@ export type ConstraintsPropagatedEvent = {
     attemptNumber: number;
     connectionConstraints: Array<{
         connection: string;
-        constraints: Map<string, PlannerConstraint | undefined>;
-        constraintCosts: Map<string, CostEstimate>;
+        constraints: Record<string, PlannerConstraint | undefined>;
+        constraintCosts: Record<string, Omit<CostEstimate, 'fanout'>>;
     }>;
 };
 /**
@@ -69,24 +61,11 @@ export type PlanCompleteEvent = {
 /**
  * Planning attempt failed (e.g., unflippable join).
  */
-export type PlanFailedEvent = {
-    type: 'plan-failed';
-    attemptNumber: number;
-    reason: string;
-};
+export type PlanFailedEvent = v.Infer<typeof planFailedEventJSONSchema>;
 /**
  * The best plan across all attempts was selected.
  */
-export type BestPlanSelectedEvent = {
-    type: 'best-plan-selected';
-    bestAttemptNumber: number;
-    totalCost: number;
-    flipPattern: number;
-    joinStates: Array<{
-        join: string;
-        type: JoinType;
-    }>;
-};
+export type BestPlanSelectedEvent = v.Infer<typeof bestPlanSelectedEventJSONSchema>;
 /**
  * A node computed its cost estimate during planning.
  * Emitted by nodes during estimateCost() traversal.
@@ -99,8 +78,9 @@ export type NodeCostEvent = {
     node: string;
     branchPattern: number[];
     downstreamChildSelectivity: number;
-    costEstimate: CostEstimate;
+    costEstimate: Omit<CostEstimate, 'fanout'>;
     filters?: Condition | undefined;
+    ordering?: Ordering | undefined;
     joinType?: JoinType | undefined;
 };
 /**
@@ -108,15 +88,7 @@ export type NodeCostEvent = {
  * Emitted by nodes during propagateConstraints() traversal.
  * attemptNumber is added by the debugger.
  */
-export type NodeConstraintEvent = {
-    type: 'node-constraint';
-    attemptNumber?: number;
-    nodeType: 'connection' | 'join' | 'fan-out' | 'fan-in' | 'terminus';
-    node: string;
-    branchPattern: number[];
-    constraint: PlannerConstraint | undefined;
-    from: string;
-};
+export type NodeConstraintEvent = v.Infer<typeof nodeConstraintEventJSONSchema>;
 /**
  * Union of all debug event types.
  */
@@ -146,4 +118,26 @@ export declare class AccumulatorDebugger implements PlanDebugger {
      */
     format(): string;
 }
+/**
+ * Serialize an array of debug events to JSON-compatible format.
+ * The fanout function is already omitted when events are created.
+ * The planSnapshot is excluded as it's internal state not needed for debugging.
+ */
+export declare function serializePlanDebugEvents(events: PlanDebugEvent[]): PlanDebugEventJSON[];
+/**
+ * Format planner debug events as a human-readable string.
+ * Works with JSON-serialized events (from inspector API) or native events (from AccumulatorDebugger).
+ *
+ * @param events - Array of planner debug events (either JSON or native format)
+ * @returns Formatted string showing planning attempts, costs, and final plan selection
+ *
+ * @example
+ * ```typescript
+ * const result = await inspector.analyzeQuery(query, { plannerDebug: true });
+ * if (result.plannerEvents) {
+ *   console.log(formatPlannerEvents(result.plannerEvents));
+ * }
+ * ```
+ */
+export declare function formatPlannerEvents(events: PlanDebugEventJSON[] | PlanDebugEvent[]): string;
 //# sourceMappingURL=planner-debug.d.ts.map

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

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