@rocicorp/zero 0.25.0-canary.0 → 0.25.0-canary.1

package/out/{chunk-MXPHMVU7.js → chunk-AIPM77UE.js}

@@ -96,6 +96,7 @@ import {
   normalizeAST,
   once,
   parse,
+  planIdSymbol,
   primaryKeySchema,
   primaryKeyValueRecordSchema,
   readFromDefaultHead,
@@ -123,7 +124,7 @@ import {
   withWrite,
   withWriteNoImplicitCommit,
   wrapIterable
-} from "./chunk-4RB4OYLQ.js";
+} from "./chunk-TJFNGO7E.js";
 import {
   assert,
   assertArray,
@@ -1511,6 +1512,223 @@ function rejectIfClosed(tx) {
   return tx.closed ? Promise.reject(new TransactionClosedError()) : void 0;
 }
 
+// ../zero-protocol/src/error-kind-enum.ts
+var error_kind_enum_exports = {};
+__export(error_kind_enum_exports, {
+  AuthInvalidated: () => AuthInvalidated,
+  ClientNotFound: () => ClientNotFound,
+  Internal: () => Internal,
+  InvalidConnectionRequest: () => InvalidConnectionRequest,
+  InvalidConnectionRequestBaseCookie: () => InvalidConnectionRequestBaseCookie,
+  InvalidConnectionRequestClientDeleted: () => InvalidConnectionRequestClientDeleted,
+  InvalidConnectionRequestLastMutationID: () => InvalidConnectionRequestLastMutationID,
+  InvalidMessage: () => InvalidMessage,
+  InvalidPush: () => InvalidPush,
+  MutationFailed: () => MutationFailed,
+  MutationRateLimited: () => MutationRateLimited,
+  PushFailed: () => PushFailed,
+  Rebalance: () => Rebalance,
+  Rehome: () => Rehome,
+  SchemaVersionNotSupported: () => SchemaVersionNotSupported,
+  ServerOverloaded: () => ServerOverloaded,
+  TransformFailed: () => TransformFailed,
+  Unauthorized: () => Unauthorized,
+  VersionNotSupported: () => VersionNotSupported
+});
+var AuthInvalidated = "AuthInvalidated";
+var ClientNotFound = "ClientNotFound";
+var InvalidConnectionRequest = "InvalidConnectionRequest";
+var InvalidConnectionRequestBaseCookie = "InvalidConnectionRequestBaseCookie";
+var InvalidConnectionRequestLastMutationID = "InvalidConnectionRequestLastMutationID";
+var InvalidConnectionRequestClientDeleted = "InvalidConnectionRequestClientDeleted";
+var InvalidMessage = "InvalidMessage";
+var InvalidPush = "InvalidPush";
+var PushFailed = "PushFailed";
+var MutationFailed = "MutationFailed";
+var MutationRateLimited = "MutationRateLimited";
+var Rebalance = "Rebalance";
+var Rehome = "Rehome";
+var TransformFailed = "TransformFailed";
+var Unauthorized = "Unauthorized";
+var VersionNotSupported = "VersionNotSupported";
+var SchemaVersionNotSupported = "SchemaVersionNotSupported";
+var ServerOverloaded = "ServerOverloaded";
+var Internal = "Internal";
+
+// ../zero-protocol/src/error-origin-enum.ts
+var error_origin_enum_exports = {};
+__export(error_origin_enum_exports, {
+  Client: () => Client,
+  Server: () => Server,
+  ZeroCache: () => ZeroCache
+});
+var Client = "client";
+var Server = "server";
+var ZeroCache = "zeroCache";
+
+// ../zero-protocol/src/error-reason-enum.ts
+var error_reason_enum_exports = {};
+__export(error_reason_enum_exports, {
+  Database: () => Database,
+  HTTP: () => HTTP,
+  Internal: () => Internal2,
+  OutOfOrderMutation: () => OutOfOrderMutation,
+  Parse: () => Parse,
+  Timeout: () => Timeout,
+  UnsupportedPushVersion: () => UnsupportedPushVersion
+});
+var Database = "database";
+var Parse = "parse";
+var OutOfOrderMutation = "oooMutation";
+var UnsupportedPushVersion = "unsupportedPushVersion";
+var Internal2 = "internal";
+var HTTP = "http";
+var Timeout = "timeout";
+
+// ../zero-protocol/src/mutation-id.ts
+var mutationIDSchema = valita_exports.object({
+  id: valita_exports.number(),
+  clientID: valita_exports.string()
+});
+
+// ../zero-protocol/src/error.ts
+var basicErrorKindSchema = literalUnion(
+  error_kind_enum_exports.AuthInvalidated,
+  error_kind_enum_exports.ClientNotFound,
+  error_kind_enum_exports.InvalidConnectionRequest,
+  error_kind_enum_exports.InvalidConnectionRequestBaseCookie,
+  error_kind_enum_exports.InvalidConnectionRequestLastMutationID,
+  error_kind_enum_exports.InvalidConnectionRequestClientDeleted,
+  error_kind_enum_exports.InvalidMessage,
+  error_kind_enum_exports.InvalidPush,
+  error_kind_enum_exports.MutationRateLimited,
+  error_kind_enum_exports.MutationFailed,
+  error_kind_enum_exports.Unauthorized,
+  error_kind_enum_exports.VersionNotSupported,
+  error_kind_enum_exports.SchemaVersionNotSupported,
+  error_kind_enum_exports.Internal
+);
+var basicErrorBodySchema = valita_exports.object({
+  kind: basicErrorKindSchema,
+  message: valita_exports.string(),
+  // this is optional for backwards compatibility
+  origin: literalUnion(error_origin_enum_exports.Server, error_origin_enum_exports.ZeroCache).optional()
+});
+var backoffErrorKindSchema = literalUnion(
+  error_kind_enum_exports.Rebalance,
+  error_kind_enum_exports.Rehome,
+  error_kind_enum_exports.ServerOverloaded
+);
+var backoffBodySchema = valita_exports.object({
+  kind: backoffErrorKindSchema,
+  message: valita_exports.string(),
+  minBackoffMs: valita_exports.number().optional(),
+  maxBackoffMs: valita_exports.number().optional(),
+  // Query parameters to send in the next reconnect. In the event of
+  // a conflict, these will be overridden by the parameters used by
+  // the client; it is the responsibility of the server to avoid
+  // parameter name conflicts.
+  //
+  // The parameters will only be added to the immediately following
+  // reconnect, and not after that.
+  reconnectParams: valita_exports.record(valita_exports.string()).optional(),
+  origin: valita_exports.literal(error_origin_enum_exports.ZeroCache).optional()
+});
+var pushFailedErrorKindSchema = valita_exports.literal(error_kind_enum_exports.PushFailed);
+var transformFailedErrorKindSchema = valita_exports.literal(error_kind_enum_exports.TransformFailed);
+var errorKindSchema = valita_exports.union(
+  basicErrorKindSchema,
+  backoffErrorKindSchema,
+  pushFailedErrorKindSchema,
+  transformFailedErrorKindSchema
+);
+var pushFailedBaseSchema = valita_exports.object({
+  kind: pushFailedErrorKindSchema,
+  details: jsonSchema.optional(),
+  mutationIDs: valita_exports.array(mutationIDSchema),
+  message: valita_exports.string()
+});
+var pushFailedBodySchema = valita_exports.union(
+  pushFailedBaseSchema.extend({
+    origin: valita_exports.literal(error_origin_enum_exports.Server),
+    reason: literalUnion(
+      error_reason_enum_exports.Database,
+      error_reason_enum_exports.Parse,
+      error_reason_enum_exports.OutOfOrderMutation,
+      error_reason_enum_exports.UnsupportedPushVersion,
+      error_reason_enum_exports.Internal
+    )
+  }),
+  pushFailedBaseSchema.extend({
+    origin: valita_exports.literal(error_origin_enum_exports.ZeroCache),
+    reason: valita_exports.literal(error_reason_enum_exports.HTTP),
+    status: valita_exports.number(),
+    bodyPreview: valita_exports.string().optional()
+  }),
+  pushFailedBaseSchema.extend({
+    origin: valita_exports.literal(error_origin_enum_exports.ZeroCache),
+    reason: literalUnion(
+      error_reason_enum_exports.Timeout,
+      error_reason_enum_exports.Parse,
+      error_reason_enum_exports.Internal
+    )
+  })
+);
+var transformFailedBaseSchema = valita_exports.object({
+  kind: transformFailedErrorKindSchema,
+  details: jsonSchema.optional(),
+  queryIDs: valita_exports.array(valita_exports.string()),
+  message: valita_exports.string()
+});
+var transformFailedBodySchema = valita_exports.union(
+  transformFailedBaseSchema.extend({
+    origin: valita_exports.literal(error_origin_enum_exports.Server),
+    reason: literalUnion(
+      error_reason_enum_exports.Database,
+      error_reason_enum_exports.Parse,
+      error_reason_enum_exports.Internal
+    )
+  }),
+  transformFailedBaseSchema.extend({
+    origin: valita_exports.literal(error_origin_enum_exports.ZeroCache),
+    reason: valita_exports.literal(error_reason_enum_exports.HTTP),
+    status: valita_exports.number(),
+    bodyPreview: valita_exports.string().optional()
+  }),
+  transformFailedBaseSchema.extend({
+    origin: valita_exports.literal(error_origin_enum_exports.ZeroCache),
+    reason: literalUnion(
+      error_reason_enum_exports.Timeout,
+      error_reason_enum_exports.Parse,
+      error_reason_enum_exports.Internal
+    )
+  })
+);
+var errorBodySchema = valita_exports.union(
+  basicErrorBodySchema,
+  backoffBodySchema,
+  pushFailedBodySchema,
+  transformFailedBodySchema
+);
+var errorMessageSchema = valita_exports.tuple([
+  valita_exports.literal("error"),
+  errorBodySchema
+]);
+var ProtocolError = class extends Error {
+  errorBody;
+  constructor(errorBody, options) {
+    super(errorBody.message, options);
+    this.name = "ProtocolError";
+    this.errorBody = errorBody;
+  }
+  get kind() {
+    return this.errorBody.kind;
+  }
+};
+function isProtocolError(error) {
+  return error instanceof ProtocolError;
+}
+
 // ../zero-protocol/src/custom-queries.ts
 var transformRequestBodySchema = valita_exports.array(
   valita_exports.object({
@@ -1531,16 +1749,25 @@ var appQueryErrorSchema = valita_exports.object({
   details: jsonSchema
 });
 var zeroErrorSchema = valita_exports.object({
+  /** @deprecated */
   error: valita_exports.literal("zero"),
+  /** @deprecated */
   id: valita_exports.string(),
+  /** @deprecated */
   name: valita_exports.string(),
+  /** @deprecated */
   details: jsonSchema
 });
 var httpQueryErrorSchema = valita_exports.object({
+  /** @deprecated */
   error: valita_exports.literal("http"),
+  /** @deprecated */
   id: valita_exports.string(),
+  /** @deprecated */
   name: valita_exports.string(),
+  /** @deprecated */
   status: valita_exports.number(),
+  /** @deprecated */
   details: jsonSchema
 });
 var erroredQuerySchema = valita_exports.union(
@@ -1559,49 +1786,18 @@ var transformErrorMessageSchema = valita_exports.tuple([
   valita_exports.literal("transformError"),
   valita_exports.array(erroredQuerySchema)
 ]);
-var transformResponseMessageSchema = valita_exports.tuple([
+var transformFailedMessageSchema = valita_exports.tuple([
+  valita_exports.literal("transformFailed"),
+  transformFailedBodySchema
+]);
+var transformOkMessageSchema = valita_exports.tuple([
   valita_exports.literal("transformed"),
   transformResponseBodySchema
 ]);
-
-// ../zero-protocol/src/error-kind-enum.ts
-var error_kind_enum_exports = {};
-__export(error_kind_enum_exports, {
-  AuthInvalidated: () => AuthInvalidated,
-  ClientNotFound: () => ClientNotFound,
-  Internal: () => Internal,
-  InvalidConnectionRequest: () => InvalidConnectionRequest,
-  InvalidConnectionRequestBaseCookie: () => InvalidConnectionRequestBaseCookie,
-  InvalidConnectionRequestClientDeleted: () => InvalidConnectionRequestClientDeleted,
-  InvalidConnectionRequestLastMutationID: () => InvalidConnectionRequestLastMutationID,
-  InvalidMessage: () => InvalidMessage,
-  InvalidPush: () => InvalidPush,
-  MutationFailed: () => MutationFailed,
-  MutationRateLimited: () => MutationRateLimited,
-  Rebalance: () => Rebalance,
-  Rehome: () => Rehome,
-  SchemaVersionNotSupported: () => SchemaVersionNotSupported,
-  ServerOverloaded: () => ServerOverloaded,
-  Unauthorized: () => Unauthorized,
-  VersionNotSupported: () => VersionNotSupported
-});
-var AuthInvalidated = "AuthInvalidated";
-var ClientNotFound = "ClientNotFound";
-var InvalidConnectionRequest = "InvalidConnectionRequest";
-var InvalidConnectionRequestBaseCookie = "InvalidConnectionRequestBaseCookie";
-var InvalidConnectionRequestLastMutationID = "InvalidConnectionRequestLastMutationID";
-var InvalidConnectionRequestClientDeleted = "InvalidConnectionRequestClientDeleted";
-var InvalidMessage = "InvalidMessage";
-var InvalidPush = "InvalidPush";
-var MutationFailed = "MutationFailed";
-var MutationRateLimited = "MutationRateLimited";
-var Rebalance = "Rebalance";
-var Rehome = "Rehome";
-var Unauthorized = "Unauthorized";
-var VersionNotSupported = "VersionNotSupported";
-var SchemaVersionNotSupported = "SchemaVersionNotSupported";
-var ServerOverloaded = "ServerOverloaded";
-var Internal = "Internal";
+var transformResponseMessageSchema = valita_exports.union(
+  transformOkMessageSchema,
+  transformFailedMessageSchema
+);
 
 // ../zero-schema/src/builder/table-builder.ts
 function table(name) {
@@ -1611,14 +1807,14 @@ function table(name) {
     primaryKey: []
   });
 }
-function string2() {
+function string4() {
   return new ColumnBuilder({
     type: "string",
     optional: false,
     customType: null
   });
 }
-function number2() {
+function number4() {
   return new ColumnBuilder({
     type: "number",
     optional: false,
@@ -2172,6 +2368,170 @@ function makeID(row, schema) {
   return JSON.stringify(schema.primaryKey.map((k) => row[k]));
 }
 
+// ../zero-client/src/client/client-error-kind-enum.ts
+var client_error_kind_enum_exports = {};
+__export(client_error_kind_enum_exports, {
+  AbruptClose: () => AbruptClose,
+  CleanClose: () => CleanClose,
+  ClientClosed: () => ClientClosed,
+  ConnectTimeout: () => ConnectTimeout,
+  DisconnectTimeout: () => DisconnectTimeout,
+  Hidden: () => Hidden,
+  Internal: () => Internal3,
+  InvalidMessage: () => InvalidMessage2,
+  NoSocketOrigin: () => NoSocketOrigin,
+  PingTimeout: () => PingTimeout,
+  PullTimeout: () => PullTimeout,
+  UnexpectedBaseCookie: () => UnexpectedBaseCookie,
+  UserDisconnect: () => UserDisconnect
+});
+var AbruptClose = "AbruptClose";
+var CleanClose = "CleanClose";
+var ClientClosed = "ClientClosed";
+var ConnectTimeout = "ConnectTimeout";
+var DisconnectTimeout = "DisconnectTimeout";
+var UnexpectedBaseCookie = "UnexpectedBaseCookie";
+var PingTimeout = "PingTimeout";
+var PullTimeout = "PullTimeout";
+var Hidden = "Hidden";
+var NoSocketOrigin = "NoSocketOrigin";
+var InvalidMessage2 = "InvalidMessage";
+var UserDisconnect = "UserDisconnect";
+var Internal3 = "Internal";
+
+// ../zero-client/src/client/connection-status-enum.ts
+var connection_status_enum_exports = {};
+__export(connection_status_enum_exports, {
+  Closed: () => Closed,
+  Connected: () => Connected,
+  Connecting: () => Connecting,
+  Disconnected: () => Disconnected,
+  Error: () => Error2
+});
+var Disconnected = "disconnected";
+var Connecting = "connecting";
+var Connected = "connected";
+var Error2 = "error";
+var Closed = "closed";
+
+// ../zero-client/src/client/error.ts
+var ClientError = class extends Error {
+  errorBody;
+  constructor(errorBody, options) {
+    super(errorBody.message, options);
+    this.name = "ClientError";
+    this.errorBody = { ...errorBody, origin: error_origin_enum_exports.Client };
+  }
+  get kind() {
+    return this.errorBody.kind;
+  }
+};
+function isServerError(ex) {
+  return isProtocolError(ex) && (ex.errorBody.origin === error_origin_enum_exports.Server || ex.errorBody.origin === error_origin_enum_exports.ZeroCache);
+}
+function isAuthError(ex) {
+  if (isServerError(ex)) {
+    if (isAuthErrorKind(ex.errorBody.kind)) {
+      return true;
+    }
+    if ((ex.errorBody.kind === error_kind_enum_exports.PushFailed || ex.errorBody.kind === error_kind_enum_exports.TransformFailed) && ex.errorBody.reason === error_reason_enum_exports.HTTP && (ex.errorBody.status === 401 || ex.errorBody.status === 403)) {
+      return true;
+    }
+  }
+  return false;
+}
+function isAuthErrorKind(kind) {
+  return kind === error_kind_enum_exports.AuthInvalidated || kind === error_kind_enum_exports.Unauthorized;
+}
+function getBackoffParams(error) {
+  if (isServerError(error)) {
+    switch (error.errorBody.kind) {
+      case error_kind_enum_exports.Rebalance:
+      case error_kind_enum_exports.Rehome:
+      case error_kind_enum_exports.ServerOverloaded:
+        return error.errorBody;
+    }
+  }
+  return void 0;
+}
+function isClientError(ex) {
+  return ex instanceof ClientError && ex.errorBody.origin === error_origin_enum_exports.Client;
+}
+var NO_STATUS_TRANSITION = "NO_STATUS_TRANSITION";
+function getErrorConnectionTransition(ex) {
+  if (isClientError(ex)) {
+    switch (ex.kind) {
+      // Connecting errors that should continue in the current state
+      case client_error_kind_enum_exports.AbruptClose:
+      case client_error_kind_enum_exports.CleanClose:
+      case client_error_kind_enum_exports.ConnectTimeout:
+      case client_error_kind_enum_exports.PingTimeout:
+      case client_error_kind_enum_exports.PullTimeout:
+      case client_error_kind_enum_exports.Hidden:
+      case client_error_kind_enum_exports.NoSocketOrigin:
+        return { status: NO_STATUS_TRANSITION, reason: ex };
+      // Fatal errors that should transition to error state
+      case client_error_kind_enum_exports.UnexpectedBaseCookie:
+      case client_error_kind_enum_exports.Internal:
+      case client_error_kind_enum_exports.InvalidMessage:
+      case client_error_kind_enum_exports.UserDisconnect:
+        return { status: connection_status_enum_exports.Error, reason: ex };
+      // Disconnected error (this should already result in a disconnected state)
+      case client_error_kind_enum_exports.DisconnectTimeout:
+        return { status: connection_status_enum_exports.Disconnected, reason: ex };
+      // Closed error (this should already result in a closed state)
+      case client_error_kind_enum_exports.ClientClosed:
+        return { status: connection_status_enum_exports.Closed, reason: ex };
+      default:
+        unreachable(ex.kind);
+    }
+  }
+  if (isAuthError(ex)) {
+    return { status: NO_STATUS_TRANSITION, reason: ex };
+  }
+  if (isServerError(ex)) {
+    switch (ex.kind) {
+      // Errors that should transition to error state
+      case error_kind_enum_exports.ClientNotFound:
+      case error_kind_enum_exports.InvalidConnectionRequest:
+      case error_kind_enum_exports.InvalidConnectionRequestBaseCookie:
+      case error_kind_enum_exports.InvalidConnectionRequestLastMutationID:
+      case error_kind_enum_exports.InvalidConnectionRequestClientDeleted:
+      case error_kind_enum_exports.InvalidMessage:
+      case error_kind_enum_exports.InvalidPush:
+      case error_kind_enum_exports.VersionNotSupported:
+      case error_kind_enum_exports.SchemaVersionNotSupported:
+      case error_kind_enum_exports.Internal:
+      case error_kind_enum_exports.PushFailed:
+      case error_kind_enum_exports.TransformFailed:
+        return { status: connection_status_enum_exports.Error, reason: ex };
+      // Errors that should continue with backoff/retry
+      case error_kind_enum_exports.Rebalance:
+      case error_kind_enum_exports.Rehome:
+      case error_kind_enum_exports.ServerOverloaded:
+        return { status: NO_STATUS_TRANSITION, reason: ex };
+      // Auth errors will eventually transition to needs-auth state
+      // For now, treat them as non-fatal so we can retry
+      case error_kind_enum_exports.AuthInvalidated:
+      case error_kind_enum_exports.Unauthorized:
+        return { status: NO_STATUS_TRANSITION, reason: ex };
+      // Mutation-specific errors don't affect connection state
+      case error_kind_enum_exports.MutationRateLimited:
+      case error_kind_enum_exports.MutationFailed:
+        return { status: NO_STATUS_TRANSITION, reason: ex };
+      default:
+        unreachable(ex.kind);
+    }
+  }
+  return {
+    status: connection_status_enum_exports.Error,
+    reason: new ClientError({
+      kind: client_error_kind_enum_exports.Internal,
+      message: "Unexpected internal error: " + (ex instanceof Error ? ex.message : typeof ex === "string" ? ex : String(ex ?? "Unknown error"))
+    })
+  };
+}
+
 // ../zero-client/src/client/update-needed-reason-type-enum.ts
 var update_needed_reason_type_enum_exports = {};
 __export(update_needed_reason_type_enum_exports, {
@@ -6283,6 +6643,24 @@ function validateOptions(options) {
   }
 }
 
+// ../shared/src/promise-race.ts
+var NO_PROMISES_MESSAGE = "No promises to race";
+var wrapPromise = (key, promise) => Promise.resolve(promise).then((result) => ({
+  key,
+  status: "fulfilled",
+  result
+}));
+async function promiseRace(promises) {
+  const keys = Object.keys(promises);
+  if (keys.length === 0) {
+    throw new Error(NO_PROMISES_MESSAGE);
+  }
+  const wrapped = keys.map(
+    (key) => wrapPromise(key, promises[key])
+  );
+  return await Promise.race(wrapped);
+}
+
 // ../shared/src/sentinels.ts
 function emptyFunction() {
 }
@@ -6292,38 +6670,6 @@ function identity(x) {
   return x;
 }
 
-// ../shared/src/subscribable.ts
-var Subscribable = class {
-  _listeners = /* @__PURE__ */ new Set();
-  /**
-   * Subscribe to the subscribable.
-   *
-   * @param listener - The listener to subscribe to.
-   * @returns A function to unsubscribe from the subscribable.
-   */
-  subscribe = (listener) => {
-    this._listeners.add(listener);
-    return () => {
-      this._listeners.delete(listener);
-    };
-  };
-  /**
-   * Notify all listeners.
-   *
-   * @param update - The update to notify listeners with.
-   */
-  notify = (update) => {
-    this._listeners.forEach((listener) => listener(update));
-  };
-  hasListeners = () => this._listeners.size > 0;
-  /**
-   * Unsubscribe all listeners.
-   */
-  cleanup = () => {
-    this._listeners.clear();
-  };
-};
-
 // ../zero-protocol/src/delete-clients.ts
 var deleteClientsBodySchema = valita_exports.union(
   readonlyObject({
@@ -6401,56 +6747,6 @@ function encodeSecProtocols(initConnectionMessage, authToken) {
   return encodeURIComponent(btoa(s));
 }
 
-// ../zero-protocol/src/error.ts
-var basicErrorKindSchema = literalUnion(
-  error_kind_enum_exports.AuthInvalidated,
-  error_kind_enum_exports.ClientNotFound,
-  error_kind_enum_exports.InvalidConnectionRequest,
-  error_kind_enum_exports.InvalidConnectionRequestBaseCookie,
-  error_kind_enum_exports.InvalidConnectionRequestLastMutationID,
-  error_kind_enum_exports.InvalidConnectionRequestClientDeleted,
-  error_kind_enum_exports.InvalidMessage,
-  error_kind_enum_exports.InvalidPush,
-  error_kind_enum_exports.MutationRateLimited,
-  error_kind_enum_exports.MutationFailed,
-  error_kind_enum_exports.Unauthorized,
-  error_kind_enum_exports.VersionNotSupported,
-  error_kind_enum_exports.SchemaVersionNotSupported,
-  error_kind_enum_exports.Internal
-);
-var basicErrorBodySchema = valita_exports.object({
-  kind: basicErrorKindSchema,
-  message: valita_exports.string()
-});
-var backoffErrorKindSchema = literalUnion(
-  error_kind_enum_exports.Rebalance,
-  error_kind_enum_exports.Rehome,
-  error_kind_enum_exports.ServerOverloaded
-);
-var backoffBodySchema = valita_exports.object({
-  kind: backoffErrorKindSchema,
-  message: valita_exports.string(),
-  minBackoffMs: valita_exports.number().optional(),
-  maxBackoffMs: valita_exports.number().optional(),
-  // Query parameters to send in the next reconnect. In the event of
-  // a conflict, these will be overridden by the parameters used by
-  // the client; it is the responsibility of the server to avoid
-  // parameter name conflicts.
-  //
-  // The parameters will only be added to the immediately following
-  // reconnect, and not after that.
-  reconnectParams: valita_exports.record(valita_exports.string()).optional()
-});
-var errorKindSchema = valita_exports.union(
-  basicErrorKindSchema,
-  backoffErrorKindSchema
-);
-var errorBodySchema = valita_exports.union(basicErrorBodySchema, backoffBodySchema);
-var errorMessageSchema = valita_exports.tuple([
-  valita_exports.literal("error"),
-  errorBodySchema
-]);
-
 // ../zero-protocol/src/mutation-type-enum.ts
 var CRUD = "crud";
 var Custom = "custom";
@@ -6522,17 +6818,17 @@ var pushBodySchema = valita_exports.object({
   requestID: valita_exports.string()
 });
 var pushMessageSchema = valita_exports.tuple([valita_exports.literal("push"), pushBodySchema]);
-var mutationIDSchema = valita_exports.object({
-  id: valita_exports.number(),
-  clientID: valita_exports.string()
-});
 var appErrorSchema = valita_exports.object({
   error: valita_exports.literal("app"),
   // The user can return any additional data here
   details: jsonSchema.optional()
 });
 var zeroErrorSchema2 = valita_exports.object({
-  error: literalUnion("oooMutation", "alreadyProcessed"),
+  error: valita_exports.union(
+    /** @deprecated push oooMutation errors are now represented as ['error', { ... }] messages */
+    valita_exports.literal("oooMutation"),
+    valita_exports.literal("alreadyProcessed")
+  ),
   details: jsonSchema.optional()
 });
 var mutationOkSchema = valita_exports.object({
@@ -6552,28 +6848,33 @@ var pushOkSchema = valita_exports.object({
   mutations: valita_exports.array(mutationResponseSchema)
 });
 var unsupportedPushVersionSchema = valita_exports.object({
+  /** @deprecated */
   error: valita_exports.literal("unsupportedPushVersion"),
-  // optional for backwards compatibility
-  // This field is included so the client knows which mutations
-  // were not processed by the server.
+  /** @deprecated */
   mutationIDs: valita_exports.array(mutationIDSchema).optional()
 });
 var unsupportedSchemaVersionSchema = valita_exports.object({
+  /** @deprecated */
   error: valita_exports.literal("unsupportedSchemaVersion"),
-  // optional for backwards compatibility
-  // This field is included so the client knows which mutations
-  // were not processed by the server.
+  /** @deprecated */
   mutationIDs: valita_exports.array(mutationIDSchema).optional()
 });
 var httpErrorSchema = valita_exports.object({
+  /** @deprecated */
   error: valita_exports.literal("http"),
+  /** @deprecated */
   status: valita_exports.number(),
+  /** @deprecated */
   details: valita_exports.string(),
+  /** @deprecated */
   mutationIDs: valita_exports.array(mutationIDSchema).optional()
 });
 var zeroPusherErrorSchema = valita_exports.object({
+  /** @deprecated */
   error: valita_exports.literal("zeroPusher"),
+  /** @deprecated */
   details: valita_exports.string(),
+  /** @deprecated */
   mutationIDs: valita_exports.array(mutationIDSchema).optional()
 });
 var pushErrorSchema = valita_exports.union(
@@ -6582,10 +6883,14 @@ var pushErrorSchema = valita_exports.union(
   httpErrorSchema,
   zeroPusherErrorSchema
 );
-var pushResponseSchema = valita_exports.union(pushOkSchema, pushErrorSchema);
+var pushResponseBodySchema = valita_exports.union(pushOkSchema, pushErrorSchema);
+var pushResponseSchema = valita_exports.union(
+  pushResponseBodySchema,
+  pushFailedBodySchema
+);
 var pushResponseMessageSchema = valita_exports.tuple([
   valita_exports.literal("pushResponse"),
-  pushResponseSchema
+  pushResponseBodySchema
 ]);
 var ackMutationResponsesMessageSchema = valita_exports.tuple([
   valita_exports.literal("ackMutationResponses"),
@@ -6750,7 +7055,7 @@ var downstreamSchema = valita_exports.union(
 );
 
 // ../zero-protocol/src/protocol-version.ts
-var PROTOCOL_VERSION = 37;
+var PROTOCOL_VERSION = 38;
 var MIN_SERVER_SUPPORTED_SYNC_PROTOCOL = 18;
 assert(MIN_SERVER_SUPPORTED_SYNC_PROTOCOL < PROTOCOL_VERSION);
 
@@ -9302,176 +9607,1426 @@ var UnionFanOut = class {
   }
 };
 
-// ../zql/src/query/expression.ts
-var ExpressionBuilder = class {
-  #exists;
-  constructor(exists) {
-    this.#exists = exists;
-    this.exists = this.exists.bind(this);
+// ../zql/src/planner/planner-fan-in.ts
+var PlannerFanIn = class {
+  kind = "fan-in";
+  #type;
+  #output;
+  #inputs;
+  constructor(inputs) {
+    this.#type = "FI";
+    this.#inputs = inputs;
   }
-  get eb() {
-    return this;
+  get type() {
+    return this.#type;
   }
-  cmp(field, opOrValue, value) {
-    return cmp(field, opOrValue, value);
+  closestJoinOrSource() {
+    return "join";
   }
-  cmpLit(left, op, right) {
-    return {
-      type: "simple",
-      left: isParameterReference(left) ? left[toStaticParam]() : { type: "literal", value: left },
-      right: isParameterReference(right) ? right[toStaticParam]() : { type: "literal", value: right },
-      op
-    };
+  setOutput(node) {
+    this.#output = node;
   }
-  and = and;
-  or = or;
-  not = not;
-  exists = (relationship, cb, options) => this.#exists(relationship, cb, options);
-};
-function and(...conditions) {
-  const expressions = filterTrue(filterUndefined(conditions));
-  if (expressions.length === 1) {
-    return expressions[0];
+  get output() {
+    assert(this.#output !== void 0, "Output not set");
+    return this.#output;
   }
-  if (expressions.some(isAlwaysFalse)) {
-    return FALSE;
+  reset() {
+    this.#type = "FI";
   }
-  return { type: "and", conditions: expressions };
-}
-function or(...conditions) {
-  const expressions = filterFalse(filterUndefined(conditions));
-  if (expressions.length === 1) {
-    return expressions[0];
+  convertToUFI() {
+    this.#type = "UFI";
   }
-  if (expressions.some(isAlwaysTrue)) {
-    return TRUE;
+  /**
+   * Propagate unlimiting when a parent join is flipped.
+   * Fan-in propagates to all of its inputs.
+   */
+  propagateUnlimitFromFlippedJoin() {
+    for (const input of this.#inputs) {
+      if ("propagateUnlimitFromFlippedJoin" in input && typeof input.propagateUnlimitFromFlippedJoin === "function") {
+        input.propagateUnlimitFromFlippedJoin();
+      }
+    }
   }
-  return { type: "or", conditions: expressions };
-}
-function not(expression) {
-  switch (expression.type) {
-    case "and":
-      return {
-        type: "or",
-        conditions: expression.conditions.map(not)
-      };
-    case "or":
-      return {
-        type: "and",
-        conditions: expression.conditions.map(not)
-      };
-    case "correlatedSubquery":
-      return {
-        type: "correlatedSubquery",
-        related: expression.related,
-        op: negateOperator(expression.op)
-      };
-    case "simple":
-      return {
-        type: "simple",
-        op: negateOperator(expression.op),
-        left: expression.left,
-        right: expression.right
-      };
+  estimateCost(branchPattern) {
+    let totalCost = {
+      rows: 0,
+      runningCost: 0,
+      startupCost: 0,
+      selectivity: 0,
+      limit: void 0
+    };
+    branchPattern = branchPattern ?? [];
+    if (this.#type === "FI") {
+      const updatedPattern = [0, ...branchPattern];
+      let maxrows = 0;
+      let maxRunningCost = 0;
+      let maxStartupCost = 0;
+      let noMatchProb = 1;
+      for (const input of this.#inputs) {
+        const cost = input.estimateCost(updatedPattern);
+        if (cost.rows > maxrows) {
+          maxrows = cost.rows;
+        }
+        if (cost.runningCost > maxRunningCost) {
+          maxRunningCost = cost.runningCost;
+        }
+        if (cost.startupCost > maxStartupCost) {
+          maxStartupCost = cost.startupCost;
+        }
+        noMatchProb *= 1 - cost.selectivity;
+        assert(
+          totalCost.limit === void 0 || cost.limit === totalCost.limit,
+          "All FanIn inputs should have the same limit"
+        );
+        totalCost.limit = cost.limit;
+      }
+      totalCost.rows = maxrows;
+      totalCost.runningCost = maxRunningCost;
+      totalCost.startupCost = maxStartupCost;
+      totalCost.selectivity = 1 - noMatchProb;
+    } else {
+      let i = 0;
+      let noMatchProb = 1;
+      for (const input of this.#inputs) {
+        const updatedPattern = [i, ...branchPattern];
+        const cost = input.estimateCost(updatedPattern);
+        totalCost.rows += cost.rows;
+        totalCost.runningCost += cost.runningCost;
+        totalCost.startupCost += cost.startupCost;
+        noMatchProb *= 1 - cost.selectivity;
+        assert(
+          totalCost.limit === void 0 || cost.limit === totalCost.limit,
+          "All FanIn inputs should have the same limit"
+        );
+        totalCost.limit = cost.limit;
+        i++;
+      }
+      totalCost.selectivity = 1 - noMatchProb;
+    }
+    return totalCost;
   }
-}
-function cmp(field, opOrValue, value) {
-  let op;
-  if (value === void 0) {
-    value = opOrValue;
-    op = "=";
-  } else {
-    op = opOrValue;
+  propagateConstraints(branchPattern, constraint, from) {
+    if (this.#type === "FI") {
+      const updatedPattern = [0, ...branchPattern];
+      for (const input of this.#inputs) {
+        input.propagateConstraints(updatedPattern, constraint, from);
+      }
+      return;
+    }
+    let i = 0;
+    for (const input of this.#inputs) {
+      input.propagateConstraints([i, ...branchPattern], constraint, from);
+      i++;
+    }
   }
-  return {
-    type: "simple",
-    left: { type: "column", name: field },
-    right: isParameterReference(value) ? value[toStaticParam]() : { type: "literal", value },
-    op
-  };
-}
-function isParameterReference(value) {
-  return value !== null && typeof value === "object" && value[toStaticParam];
-}
-var TRUE = {
-  type: "and",
-  conditions: []
-};
-var FALSE = {
-  type: "or",
-  conditions: []
 };
-function isAlwaysTrue(condition) {
-  return condition.type === "and" && condition.conditions.length === 0;
-}
-function isAlwaysFalse(condition) {
-  return condition.type === "or" && condition.conditions.length === 0;
-}
-function simplifyCondition(c) {
-  if (c.type === "simple" || c.type === "correlatedSubquery") {
-    return c;
+
+// ../zql/src/planner/planner-fan-out.ts
+var PlannerFanOut = class {
+  kind = "fan-out";
+  #type;
+  #outputs = [];
+  #input;
+  constructor(input) {
+    this.#type = "FO";
+    this.#input = input;
   }
-  if (c.conditions.length === 1) {
-    return simplifyCondition(c.conditions[0]);
+  get type() {
+    return this.#type;
   }
-  const conditions = flatten(c.type, c.conditions.map(simplifyCondition));
-  if (c.type === "and" && conditions.some(isAlwaysFalse)) {
-    return FALSE;
+  addOutput(node) {
+    this.#outputs.push(node);
   }
-  if (c.type === "or" && conditions.some(isAlwaysTrue)) {
-    return TRUE;
+  get outputs() {
+    return this.#outputs;
   }
-  return {
-    type: c.type,
-    conditions
-  };
-}
-function flatten(type, conditions) {
-  const flattened = [];
-  for (const c of conditions) {
-    if (c.type === type) {
-      flattened.push(...c.conditions);
-    } else {
-      flattened.push(c);
+  closestJoinOrSource() {
+    return this.#input.closestJoinOrSource();
+  }
+  propagateConstraints(branchPattern, constraint, _from) {
+    this.#input.propagateConstraints(branchPattern, constraint, this);
+  }
+  estimateCost(branchPattern) {
+    return this.#input.estimateCost(branchPattern);
+  }
+  convertToUFO() {
+    this.#type = "UFO";
+  }
+  reset() {
+    this.#type = "FO";
+  }
+  /**
+   * Propagate unlimiting when a parent join is flipped.
+   * Fan-out propagates to its input.
+   */
+  propagateUnlimitFromFlippedJoin() {
+    if ("propagateUnlimitFromFlippedJoin" in this.#input && typeof this.#input.propagateUnlimitFromFlippedJoin === "function") {
+      this.#input.propagateUnlimitFromFlippedJoin();
     }
   }
-  return flattened;
-}
-var negateSimpleOperatorMap = {
-  ["="]: "!=",
-  ["!="]: "=",
-  ["<"]: ">=",
-  [">"]: "<=",
-  [">="]: "<",
-  ["<="]: ">",
-  ["IN"]: "NOT IN",
-  ["NOT IN"]: "IN",
-  ["LIKE"]: "NOT LIKE",
-  ["NOT LIKE"]: "LIKE",
-  ["ILIKE"]: "NOT ILIKE",
-  ["NOT ILIKE"]: "ILIKE",
-  ["IS"]: "IS NOT",
-  ["IS NOT"]: "IS"
 };
-var negateOperatorMap = {
-  ...negateSimpleOperatorMap,
-  ["EXISTS"]: "NOT EXISTS",
-  ["NOT EXISTS"]: "EXISTS"
-};
-function negateOperator(op) {
-  return must(negateOperatorMap[op]);
-}
-function filterUndefined(array9) {
-  return array9.filter((e) => e !== void 0);
-}
-function filterTrue(conditions) {
-  return conditions.filter((c) => !isAlwaysTrue(c));
-}
-function filterFalse(conditions) {
-  return conditions.filter((c) => !isAlwaysFalse(c));
+
+// ../zql/src/planner/planner-constraint.ts
+function mergeConstraints(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return { ...a, ...b };
 }
 
-// ../zql/src/builder/like.ts
+// ../zql/src/planner/planner-connection.ts
+var PlannerConnection = class {
+  kind = "connection";
+  // ========================================================================
+  // IMMUTABLE STRUCTURE (set during construction, never changes)
+  // ========================================================================
+  #sort;
+  #filters;
+  #model;
+  table;
+  name;
+  // Human-readable name for debugging (defaults to table name)
+  #baseConstraints;
+  // Constraints from parent correlation
+  #baseLimit;
+  // Original limit from query structure (never modified)
+  selectivity;
+  // Fraction of rows passing filters (1.0 = no filtering)
+  #output;
+  // Set once during graph construction
+  // ========================================================================
+  // MUTABLE PLANNING STATE (changes during plan search)
+  // ========================================================================
+  /**
+   * Current limit during planning. Can be cleared (set to undefined) when a
+   * parent join is flipped, indicating this connection is now in an outer loop
+   * and should not be limited by EXISTS semantics.
+   */
+  limit;
+  /**
+   * Constraints accumulated from parent joins during planning.
+   * Key is a path through the graph (e.g., "0,1" for branch pattern [0,1]).
+   *
+   * Undefined constraints are possible when a FO converts to UFO and only
+   * a single join in the UFO is flipped - other branches report undefined.
+   */
+  #constraints;
+  /**
+   * Cached total cost (sum of all branches) to avoid redundant calculations.
+   * Invalidated when constraints change.
+   */
+  #cachedTotalCost = void 0;
+  /**
+   * Cached per-constraint costs to avoid redundant cost model calls.
+   * Maps constraint key (branch pattern string) to computed cost.
+   * Invalidated when constraints change.
+   */
+  #cachedConstraintCosts = /* @__PURE__ */ new Map();
+  #costDirty = true;
+  constructor(table2, model, sort, filters, baseConstraints, limit, name) {
+    this.table = table2;
+    this.name = name ?? table2;
+    this.#sort = sort;
+    this.#filters = filters;
+    this.#model = model;
+    this.#baseConstraints = baseConstraints;
+    this.#baseLimit = limit;
+    this.limit = limit;
+    this.#constraints = /* @__PURE__ */ new Map();
+    if (limit !== void 0 && filters) {
+      const costWithFilters = model(table2, sort, filters, void 0);
+      const costWithoutFilters = model(table2, sort, void 0, void 0);
+      this.selectivity = costWithoutFilters.rows > 0 ? costWithFilters.rows / costWithoutFilters.rows : 1;
+    } else {
+      this.selectivity = 1;
+    }
+  }
+  setOutput(node) {
+    this.#output = node;
+  }
+  get output() {
+    assert(this.#output !== void 0, "Output not set");
+    return this.#output;
+  }
+  closestJoinOrSource() {
+    return "connection";
+  }
+  /**
+   * Constraints are uniquely identified by their path through the
+   * graph.
+   *
+   * FO represents all sub-joins as a single path.
+   * UFO represents each sub-join as a separate path.
+   * The first branch in a UFO will match the path of FO so no re-set needs to happen
+   * when swapping from FO to UFO.
+   *
+   * FO swaps to UFO when a join inside FO-FI gets flipped.
+   *
+   * The max of the last element of the paths is the number of
+   * root branches.
+   */
+  propagateConstraints(path, c) {
+    const key = path.join(",");
+    this.#constraints.set(key, c);
+    this.#cachedTotalCost = void 0;
+    this.#cachedConstraintCosts.clear();
+    this.#costDirty = true;
+  }
+  estimateCost(branchPattern) {
+    if (branchPattern === void 0) {
+      if (!this.#costDirty && this.#cachedTotalCost !== void 0) {
+        return this.#cachedTotalCost;
+      }
+      let totalRows = 0;
+      let maxStartupCost = 0;
+      if (this.#constraints.size === 0) {
+        const key2 = "";
+        let cost2 = this.#cachedConstraintCosts.get(key2);
+        if (cost2 === void 0) {
+          const { startupCost: startupCost2, rows: rows2 } = this.#model(
+            this.table,
+            this.#sort,
+            this.#filters,
+            this.#baseConstraints
+          );
+          cost2 = {
+            rows: rows2,
+            runningCost: rows2,
+            startupCost: startupCost2,
+            selectivity: this.selectivity,
+            limit: this.limit
+          };
+          this.#cachedConstraintCosts.set(key2, cost2);
+        }
+        totalRows = cost2.rows;
+        maxStartupCost = cost2.startupCost;
+      } else {
+        for (const [key2, constraint2] of this.#constraints.entries()) {
+          let cost2 = this.#cachedConstraintCosts.get(key2);
+          if (cost2 === void 0) {
+            const mergedConstraint2 = mergeConstraints(
+              this.#baseConstraints,
+              constraint2
+            );
+            const { startupCost: startupCost2, rows: rows2 } = this.#model(
+              this.table,
+              this.#sort,
+              this.#filters,
+              mergedConstraint2
+            );
+            cost2 = {
+              rows: rows2,
+              runningCost: rows2,
+              startupCost: startupCost2,
+              selectivity: this.selectivity,
+              limit: this.limit
+            };
+            this.#cachedConstraintCosts.set(key2, cost2);
+          }
+          totalRows += cost2.rows;
+          maxStartupCost = Math.max(maxStartupCost, cost2.startupCost);
+        }
+      }
+      const ret = {
+        rows: totalRows,
+        runningCost: totalRows,
+        startupCost: maxStartupCost,
+        selectivity: this.selectivity,
+        limit: this.limit
+      };
+      this.#cachedTotalCost = ret;
+      this.#costDirty = false;
+      return ret;
+    }
+    const key = branchPattern.join(",");
+    let cost = this.#cachedConstraintCosts.get(key);
+    if (cost !== void 0) {
+      return cost;
+    }
+    const constraint = this.#constraints.get(key);
+    const mergedConstraint = mergeConstraints(
+      this.#baseConstraints,
+      constraint
+    );
+    const { startupCost, rows } = this.#model(
+      this.table,
+      this.#sort,
+      this.#filters,
+      mergedConstraint
+    );
+    cost = {
+      rows,
+      runningCost: rows,
+      startupCost,
+      selectivity: this.selectivity,
+      limit: this.limit
+    };
+    this.#cachedConstraintCosts.set(key, cost);
+    return cost;
+  }
+  /**
+   * Remove the limit from this connection.
+   * Called when a parent join is flipped, making this connection part of an
+   * outer loop that should produce all rows rather than stopping at the limit.
+   */
+  unlimit() {
+    if (this.limit !== void 0) {
+      this.limit = void 0;
+    }
+  }
+  /**
+   * Propagate unlimiting when a parent join is flipped.
+   * For connections, we simply remove the limit.
+   */
+  propagateUnlimitFromFlippedJoin() {
+    this.unlimit();
+  }
+  reset() {
+    this.#constraints.clear();
+    this.limit = this.#baseLimit;
+    this.#cachedTotalCost = void 0;
+    this.#cachedConstraintCosts.clear();
+    this.#costDirty = true;
+  }
+  /**
+   * Capture constraint state for snapshotting.
+   * Used by PlannerGraph to save/restore planning state.
+   */
+  captureConstraints() {
+    return new Map(this.#constraints);
+  }
+  /**
+   * Restore constraint state from a snapshot.
+   * Used by PlannerGraph to restore planning state.
+   */
+  restoreConstraints(constraints) {
+    this.#constraints.clear();
+    for (const [key, value] of constraints) {
+      this.#constraints.set(key, value);
+    }
+    this.#cachedTotalCost = void 0;
+    this.#cachedConstraintCosts.clear();
+    this.#costDirty = true;
+  }
+  /**
+   * Get current constraints for debugging.
+   * Returns a copy of the constraints map.
+   */
+  getConstraintsForDebug() {
+    return new Map(this.#constraints);
+  }
+  /**
+   * Get estimated cost for each constraint branch.
+   * Returns a map of constraint key to cost estimate.
+   * Forces cost calculation if not already cached.
+   */
+  getConstraintCostsForDebug() {
+    this.estimateCost(void 0);
+    return new Map(this.#cachedConstraintCosts);
+  }
+};
+
+// ../zql/src/planner/planner-source.ts
+var PlannerSource = class {
+  name;
+  #model;
+  constructor(name, model) {
+    this.name = name;
+    this.#model = model;
+  }
+  connect(sort, filters, baseConstraints, limit) {
+    return new PlannerConnection(
+      this.name,
+      this.#model,
+      sort,
+      filters,
+      baseConstraints,
+      limit
+    );
+  }
+};
+
+// ../zql/src/planner/planner-graph.ts
+var MAX_FLIPPABLE_JOINS = 13;
+var PlannerGraph = class {
+  // Sources indexed by table name
+  #sources = /* @__PURE__ */ new Map();
+  // The final output node where constraint propagation starts
+  #terminus = void 0;
+  // Collections of nodes with mutable planning state
+  joins = [];
+  fanOuts = [];
+  fanIns = [];
+  connections = [];
+  /**
+   * Reset all planning state back to initial values for another planning pass.
+   * Resets only mutable planning state - graph structure is unchanged.
+   *
+   * This allows replanning the same query graph with different strategies.
+   */
+  resetPlanningState() {
+    for (const j of this.joins) j.reset();
+    for (const fo of this.fanOuts) fo.reset();
+    for (const fi of this.fanIns) fi.reset();
+    for (const c of this.connections) c.reset();
+  }
+  /**
+   * Create and register a source (table) in the graph.
+   */
+  addSource(name, model) {
+    assert(
+      !this.#sources.has(name),
+      `Source ${name} already exists in the graph`
+    );
+    const source = new PlannerSource(name, model);
+    this.#sources.set(name, source);
+    return source;
+  }
+  /**
+   * Get a source by table name.
+   */
+  getSource(name) {
+    const source = this.#sources.get(name);
+    assert(source !== void 0, `Source ${name} not found in the graph`);
+    return source;
+  }
+  /**
+   * Check if a source exists by table name.
+   */
+  hasSource(name) {
+    return this.#sources.has(name);
+  }
+  /**
+   * Set the terminus (final output) node of the graph.
+   * Constraint propagation starts from this node.
+   */
+  setTerminus(terminus) {
+    this.#terminus = terminus;
+  }
+  /**
+   * Initiate constraint propagation from the terminus node.
+   * This sends constraints up through the graph to update
+   * connection cost estimates.
+   */
+  propagateConstraints() {
+    assert(
+      this.#terminus !== void 0,
+      "Cannot propagate constraints without a terminus node"
+    );
+    this.#terminus.propagateConstraints();
+  }
+  /**
+   * Calculate total cost of the current plan.
+   * Total cost includes both startup cost (one-time, e.g., sorting) and running cost.
+   */
+  getTotalCost() {
+    const estimate = must(this.#terminus).estimateCost();
+    return estimate.startupCost + estimate.runningCost;
+  }
+  /**
+   * Capture a lightweight snapshot of the current planning state.
+   * Used for backtracking during multi-start greedy search.
+   *
+   * Captures mutable state including pinned flags, join types, and
+   * constraint maps to avoid needing repropagation on restore.
+   *
+   * @returns A snapshot that can be restored via restorePlanningSnapshot()
+   */
+  capturePlanningSnapshot() {
+    return {
+      connections: this.connections.map((c) => ({
+        limit: c.limit
+      })),
+      joins: this.joins.map((j) => ({ type: j.type })),
+      fanOuts: this.fanOuts.map((fo) => ({ type: fo.type })),
+      fanIns: this.fanIns.map((fi) => ({ type: fi.type })),
+      connectionConstraints: this.connections.map((c) => c.captureConstraints())
+    };
+  }
+  /**
+   * Restore planning state from a previously captured snapshot.
+   * Used for backtracking when a planning attempt fails.
+   *
+   * Restores pinned flags, join types, and constraint maps, eliminating
+   * the need for repropagation.
+   *
+   * @param state - Snapshot created by capturePlanningSnapshot()
+   */
+  restorePlanningSnapshot(state) {
+    this.#validateSnapshotShape(state);
+    this.#restoreConnections(state);
+    this.#restoreJoins(state);
+    this.#restoreFanNodes(state);
+  }
+  /**
+   * Collect cost estimates from all nodes in the graph for debugging.
+   */
+  #collectNodeCosts() {
+    const costs = [];
+    for (const c of this.connections) {
+      costs.push({
+        node: c.name,
+        nodeType: "connection",
+        costEstimate: c.estimateCost(void 0)
+      });
+    }
+    for (const j of this.joins) {
+      costs.push({
+        node: j.getName(),
+        nodeType: "join",
+        costEstimate: j.estimateCost(void 0)
+      });
+    }
+    for (const fo of this.fanOuts) {
+      costs.push({
+        node: "FO",
+        nodeType: "fan-out",
+        costEstimate: fo.estimateCost(void 0)
+      });
+    }
+    for (const fi of this.fanIns) {
+      costs.push({
+        node: "FI",
+        nodeType: "fan-in",
+        costEstimate: fi.estimateCost(void 0)
+      });
+    }
+    return costs;
+  }
+  /**
+   * Validate that snapshot shape matches current graph structure.
+   */
+  #validateSnapshotShape(state) {
+    assert(
+      this.connections.length === state.connections.length,
+      "Plan state mismatch: connections"
+    );
+    assert(
+      this.joins.length === state.joins.length,
+      "Plan state mismatch: joins"
+    );
+    assert(
+      this.fanOuts.length === state.fanOuts.length,
+      "Plan state mismatch: fanOuts"
+    );
+    assert(
+      this.fanIns.length === state.fanIns.length,
+      "Plan state mismatch: fanIns"
+    );
+    assert(
+      this.connections.length === state.connectionConstraints.length,
+      "Plan state mismatch: connectionConstraints"
+    );
+  }
+  /**
+   * Restore connection pinned flags, limits, and constraint maps.
+   */
+  #restoreConnections(state) {
+    for (let i = 0; i < this.connections.length; i++) {
+      this.connections[i].limit = state.connections[i].limit;
+      this.connections[i].restoreConstraints(state.connectionConstraints[i]);
+    }
+  }
+  /**
+   * Restore join types and pinned flags.
+   */
+  #restoreJoins(state) {
+    for (let i = 0; i < this.joins.length; i++) {
+      const join = this.joins[i];
+      const targetState = state.joins[i];
+      join.reset();
+      if (targetState.type === "flipped") {
+        join.flip();
+      }
+    }
+  }
+  /**
+   * Restore FanOut and FanIn types.
+   */
+  #restoreFanNodes(state) {
+    for (let i = 0; i < this.fanOuts.length; i++) {
+      const fo = this.fanOuts[i];
+      const targetType = state.fanOuts[i].type;
+      if (targetType === "UFO" && fo.type === "FO") {
+        fo.convertToUFO();
+      }
+    }
+    for (let i = 0; i < this.fanIns.length; i++) {
+      const fi = this.fanIns[i];
+      const targetType = state.fanIns[i].type;
+      if (targetType === "UFI" && fi.type === "FI") {
+        fi.convertToUFI();
+      }
+    }
+  }
+  /**
+   * Main planning algorithm using exhaustive join flip enumeration.
+   *
+   * Enumerates all possible flip patterns for flippable joins (2^n for n flippable joins).
+   * Each pattern represents a different query execution plan. We evaluate the cost of each
+   * plan and select the one with the lowest cost.
+   *
+   * Connections are used only for cost estimation - the flip patterns determine the plan.
+   * 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
+   */
+  plan(planDebugger) {
+    const flippableJoins = this.joins.filter((j) => j.isFlippable());
+    if (flippableJoins.length > MAX_FLIPPABLE_JOINS) {
+      throw new Error(
+        `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}).`
+      );
+    }
+    const fofiCache = buildFOFICache(this);
+    const numPatterns = 2 ** flippableJoins.length;
+    let bestCost = Infinity;
+    let bestPlan = void 0;
+    let bestAttemptNumber = -1;
+    for (let pattern = 0; pattern < numPatterns; pattern++) {
+      this.resetPlanningState();
+      if (planDebugger) {
+        planDebugger.log({
+          type: "attempt-start",
+          attemptNumber: pattern,
+          totalAttempts: numPatterns
+        });
+      }
+      try {
+        for (let i = 0; i < flippableJoins.length; i++) {
+          if (pattern & 1 << i) {
+            flippableJoins[i].flip();
+          }
+        }
+        checkAndConvertFOFI(fofiCache);
+        propagateUnlimitForFlippedJoins(this);
+        this.propagateConstraints();
+        if (planDebugger) {
+          planDebugger.log({
+            type: "constraints-propagated",
+            attemptNumber: pattern,
+            connectionConstraints: this.connections.map((c) => ({
+              connection: c.name,
+              constraints: c.getConstraintsForDebug(),
+              constraintCosts: c.getConstraintCostsForDebug()
+            }))
+          });
+        }
+        const totalCost = this.getTotalCost();
+        if (planDebugger) {
+          planDebugger.log({
+            type: "plan-complete",
+            attemptNumber: pattern,
+            totalCost,
+            nodeCosts: this.#collectNodeCosts(),
+            joinStates: this.joins.map((j) => {
+              const info = j.getDebugInfo();
+              return {
+                join: info.name,
+                type: info.type
+              };
+            })
+          });
+        }
+        if (totalCost < bestCost) {
+          bestCost = totalCost;
+          bestPlan = this.capturePlanningSnapshot();
+          bestAttemptNumber = pattern;
+        }
+      } catch (e) {
+        if (planDebugger) {
+          planDebugger.log({
+            type: "plan-failed",
+            attemptNumber: pattern,
+            reason: `Flip pattern ${pattern.toString(2)} failed: ${e instanceof Error ? e.message : String(e)}`
+          });
+        }
+        continue;
+      }
+    }
+    if (bestPlan) {
+      this.restorePlanningSnapshot(bestPlan);
+      this.propagateConstraints();
+      if (planDebugger) {
+        planDebugger.log({
+          type: "best-plan-selected",
+          bestAttemptNumber,
+          totalCost: bestCost,
+          joinStates: this.joins.map((j) => ({
+            join: j.getName(),
+            type: j.type
+          }))
+        });
+      }
+    } else {
+      throw new Error(
+        "No valid query plan found. This should not happen - check query structure."
+      );
+    }
+  }
+};
+function buildFOFICache(graph) {
+  const cache = /* @__PURE__ */ new Map();
+  for (const fo of graph.fanOuts) {
+    const info = findFIAndJoins(fo);
+    cache.set(fo, info);
+  }
+  return cache;
+}
+function checkAndConvertFOFI(fofiCache) {
+  for (const [fo, info] of fofiCache) {
+    const hasFlippedJoin = info.joinsBetween.some((j) => j.type === "flipped");
+    if (info.fi && hasFlippedJoin) {
+      fo.convertToUFO();
+      info.fi.convertToUFI();
+    }
+  }
+}
+function findFIAndJoins(fo) {
+  const joinsBetween = [];
+  let fi = void 0;
+  const queue = [...fo.outputs];
+  const visited = /* @__PURE__ */ new Set();
+  while (queue.length > 0) {
+    const node = must(queue.shift());
+    if (visited.has(node)) continue;
+    visited.add(node);
+    switch (node.kind) {
+      case "join":
+        joinsBetween.push(node);
+        queue.push(node.output);
+        break;
+      case "fan-out":
+        queue.push(...node.outputs);
+        break;
+      case "fan-in":
+        fi = node;
+        break;
+      case "connection":
+        break;
+      case "terminus":
+        break;
+    }
+  }
+  return { fi, joinsBetween };
+}
+function propagateUnlimitForFlippedJoins(graph) {
+  for (const join of graph.joins) {
+    if (join.type === "flipped") {
+      join.propagateUnlimit();
+    }
+  }
+}
+
+// ../zql/src/planner/planner-join.ts
+var SEMI_JOIN_OVERHEAD_MULTIPLIER = 1.5;
+var PlannerJoin = class {
+  kind = "join";
+  #parent;
+  #child;
+  #parentConstraint;
+  #childConstraint;
+  #flippable;
+  planId;
+  #output;
+  // Set once during graph construction
+  // Reset between planning attempts
+  #type;
+  constructor(parent, child, parentConstraint, childConstraint, flippable, planId) {
+    this.#type = "semi";
+    this.#parent = parent;
+    this.#child = child;
+    this.#childConstraint = childConstraint;
+    this.#parentConstraint = parentConstraint;
+    this.#flippable = flippable;
+    this.planId = planId;
+  }
+  setOutput(node) {
+    this.#output = node;
+  }
+  get output() {
+    assert(this.#output !== void 0, "Output not set");
+    return this.#output;
+  }
+  closestJoinOrSource() {
+    return "join";
+  }
+  flipIfNeeded(input) {
+    if (input === this.#child) {
+      this.flip();
+    } else {
+      assert(
+        input === this.#parent,
+        "Can only flip a join from one of its inputs"
+      );
+    }
+  }
+  flip() {
+    assert(this.#type === "semi", "Can only flip a semi-join");
+    if (!this.#flippable) {
+      throw new UnflippableJoinError(
+        "Cannot flip a non-flippable join (e.g., NOT EXISTS)"
+      );
+    }
+    this.#type = "flipped";
+  }
+  get type() {
+    return this.#type;
+  }
+  isFlippable() {
+    return this.#flippable;
+  }
+  /**
+   * Propagate unlimiting through the child subgraph when this join is flipped.
+   * When a join is flipped, the child becomes the outer loop and should produce
+   * all rows rather than stopping at an EXISTS limit.
+   *
+   * Propagation rules:
+   * - Connection: call unlimit()
+   * - Semi-join: continue to parent (outer loop)
+   * - Flipped join: stop (already unlimited when it was flipped)
+   * - Fan-out/Fan-in: propagate to all inputs
+   */
+  propagateUnlimit() {
+    assert(this.#type === "flipped", "Can only unlimit a flipped join");
+    propagateUnlimitToNode(this.#child);
+  }
+  /**
+   * Called when a parent join is flipped and this join is part of its child subgraph.
+   * - Semi-join: continue propagation to parent (the outer loop)
+   * - Flipped join: stop propagation (already unlimited when it was flipped)
+   */
+  propagateUnlimitFromFlippedJoin() {
+    if (this.#type === "semi") {
+      propagateUnlimitToNode(this.#parent);
+    }
+  }
+  propagateConstraints(branchPattern, constraint) {
+    if (this.#type === "semi") {
+      this.#child.propagateConstraints(
+        branchPattern,
+        this.#childConstraint,
+        this
+      );
+      this.#parent.propagateConstraints(branchPattern, constraint, this);
+    } else if (this.#type === "flipped") {
+      this.#child.propagateConstraints(branchPattern, void 0, this);
+      this.#parent.propagateConstraints(
+        branchPattern,
+        mergeConstraints(constraint, this.#parentConstraint),
+        this
+      );
+    }
+  }
+  reset() {
+    this.#type = "semi";
+  }
+  estimateCost(branchPattern) {
+    const parentCost = this.#parent.estimateCost(branchPattern);
+    const childCost = this.#child.estimateCost(branchPattern);
+    let scanEst = parentCost.rows;
+    if (this.#type === "semi" && parentCost.limit !== void 0) {
+      if (childCost.selectivity !== 0) {
+        scanEst = Math.min(scanEst, parentCost.limit / childCost.selectivity);
+      }
+    }
+    if (this.#parent.closestJoinOrSource() === "join") {
+      const pipelineCost = this.#type === "flipped" ? childCost.startupCost + childCost.runningCost * (parentCost.startupCost + parentCost.runningCost) : parentCost.runningCost + SEMI_JOIN_OVERHEAD_MULTIPLIER * scanEst * (childCost.startupCost + childCost.runningCost);
+      return {
+        rows: parentCost.rows,
+        runningCost: pipelineCost,
+        startupCost: parentCost.startupCost,
+        selectivity: parentCost.selectivity,
+        limit: parentCost.limit
+      };
+    }
+    const nestedLoopCost = this.#type === "flipped" ? childCost.runningCost * (parentCost.startupCost + parentCost.runningCost) : SEMI_JOIN_OVERHEAD_MULTIPLIER * scanEst * (childCost.startupCost + childCost.runningCost);
+    return {
+      rows: parentCost.rows,
+      runningCost: nestedLoopCost,
+      startupCost: parentCost.startupCost,
+      selectivity: parentCost.selectivity,
+      limit: parentCost.limit
+    };
+  }
+  /**
+   * Get a human-readable name for this join for debugging.
+   * Format: "parentName ⋈ childName"
+   */
+  getName() {
+    const parentName = getNodeName(this.#parent);
+    const childName = getNodeName(this.#child);
+    return `${parentName} \u22C8 ${childName}`;
+  }
+  /**
+   * Get debug information about this join's state.
+   */
+  getDebugInfo() {
+    return {
+      name: this.getName(),
+      type: this.#type,
+      planId: this.planId
+    };
+  }
+};
+var UnflippableJoinError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnflippableJoinError";
+  }
+};
+function getNodeName(node) {
+  switch (node.kind) {
+    case "connection":
+      return node.name;
+    case "join":
+      return node.getName();
+    case "fan-out":
+      return "FO";
+    case "fan-in":
+      return "FI";
+    case "terminus":
+      return "terminus";
+  }
+}
+function propagateUnlimitToNode(node) {
+  if ("propagateUnlimitFromFlippedJoin" in node && typeof node.propagateUnlimitFromFlippedJoin === "function") {
+    node.propagateUnlimitFromFlippedJoin();
+  }
+}
+
+// ../zql/src/planner/planner-terminus.ts
+var PlannerTerminus = class {
+  kind = "terminus";
+  #input;
+  constructor(input) {
+    this.#input = input;
+  }
+  get pinned() {
+    return true;
+  }
+  closestJoinOrSource() {
+    return this.#input.closestJoinOrSource();
+  }
+  propagateConstraints() {
+    this.#input.propagateConstraints([], void 0, this);
+  }
+  estimateCost() {
+    return this.#input.estimateCost([]);
+  }
+  /**
+   * Propagate unlimiting when a parent join is flipped.
+   * Terminus doesn't participate in unlimiting.
+   */
+  propagateUnlimitFromFlippedJoin() {
+  }
+};
+
+// ../zql/src/planner/planner-builder.ts
+function wireOutput(from, to) {
+  switch (from.kind) {
+    case "connection":
+    case "join":
+    case "fan-in":
+      from.setOutput(to);
+      break;
+    case "fan-out":
+      from.addOutput(to);
+      break;
+    case "terminus":
+      assert(false, "Terminus nodes cannot have outputs");
+  }
+}
+function buildPlanGraph(ast, model, baseConstraints) {
+  const graph = new PlannerGraph();
+  let nextPlanId = 0;
+  const source = graph.addSource(ast.table, model);
+  const connection = source.connect(
+    ast.orderBy ?? [],
+    ast.where,
+    baseConstraints,
+    ast.limit
+  );
+  graph.connections.push(connection);
+  let end = connection;
+  if (ast.where) {
+    end = processCondition(
+      ast.where,
+      end,
+      graph,
+      model,
+      ast.table,
+      () => nextPlanId++
+    );
+  }
+  const terminus = new PlannerTerminus(end);
+  wireOutput(end, terminus);
+  graph.setTerminus(terminus);
+  const subPlans = {};
+  if (ast.related) {
+    for (const csq of ast.related) {
+      const alias = must(
+        csq.subquery.alias,
+        "Related subquery must have alias"
+      );
+      const childConstraints = extractConstraint(
+        csq.correlation.childField,
+        csq.subquery.table
+      );
+      subPlans[alias] = buildPlanGraph(csq.subquery, model, childConstraints);
+    }
+  }
+  return { plan: graph, subPlans };
+}
+function processCondition(condition, input, graph, model, parentTable, getPlanId) {
+  switch (condition.type) {
+    case "simple":
+      return input;
+    case "and":
+      return processAnd(condition, input, graph, model, parentTable, getPlanId);
+    case "or":
+      return processOr(condition, input, graph, model, parentTable, getPlanId);
+    case "correlatedSubquery":
+      return processCorrelatedSubquery(
+        condition,
+        input,
+        graph,
+        model,
+        parentTable,
+        getPlanId
+      );
+  }
+}
+function processAnd(condition, input, graph, model, parentTable, getPlanId) {
+  let end = input;
+  for (const subCondition of condition.conditions) {
+    end = processCondition(
+      subCondition,
+      end,
+      graph,
+      model,
+      parentTable,
+      getPlanId
+    );
+  }
+  return end;
+}
+function processOr(condition, input, graph, model, parentTable, getPlanId) {
+  const subqueryConditions = condition.conditions.filter(
+    (c) => c.type === "correlatedSubquery" || hasCorrelatedSubquery(c)
+  );
+  if (subqueryConditions.length === 0) {
+    return input;
+  }
+  const fanOut = new PlannerFanOut(input);
+  graph.fanOuts.push(fanOut);
+  wireOutput(input, fanOut);
+  const branches = [];
+  for (const subCondition of subqueryConditions) {
+    const branch = processCondition(
+      subCondition,
+      fanOut,
+      graph,
+      model,
+      parentTable,
+      getPlanId
+    );
+    branches.push(branch);
+    fanOut.addOutput(branch);
+  }
+  const fanIn = new PlannerFanIn(branches);
+  graph.fanIns.push(fanIn);
+  for (const branch of branches) {
+    wireOutput(branch, fanIn);
+  }
+  return fanIn;
+}
+function processCorrelatedSubquery(condition, input, graph, model, parentTable, getPlanId) {
+  const { related } = condition;
+  const childTable = related.subquery.table;
+  const childSource = graph.hasSource(childTable) ? graph.getSource(childTable) : graph.addSource(childTable, model);
+  const childConnection = childSource.connect(
+    related.subquery.orderBy ?? [],
+    related.subquery.where,
+    void 0,
+    // no base constraints for EXISTS/NOT EXISTS
+    condition.op === "EXISTS" ? 1 : void 0
+  );
+  graph.connections.push(childConnection);
+  let childEnd = childConnection;
+  if (related.subquery.where) {
+    childEnd = processCondition(
+      related.subquery.where,
+      childEnd,
+      graph,
+      model,
+      childTable,
+      getPlanId
+    );
+  }
+  const parentConstraint = extractConstraint(
+    related.correlation.parentField,
+    parentTable
+  );
+  const childConstraint = extractConstraint(
+    related.correlation.childField,
+    childTable
+  );
+  const planId = getPlanId();
+  condition[planIdSymbol] = planId;
+  const join = new PlannerJoin(
+    input,
+    childEnd,
+    parentConstraint,
+    childConstraint,
+    condition.op !== "NOT EXISTS",
+    planId
+  );
+  graph.joins.push(join);
+  wireOutput(input, join);
+  wireOutput(childEnd, join);
+  return join;
+}
+function hasCorrelatedSubquery(condition) {
+  if (condition.type === "correlatedSubquery") {
+    return true;
+  }
+  if (condition.type === "and" || condition.type === "or") {
+    return condition.conditions.some(hasCorrelatedSubquery);
+  }
+  return false;
+}
+function extractConstraint(fields, _tableName) {
+  return Object.fromEntries(fields.map((field) => [field, void 0]));
+}
+function planRecursively(plans, planDebugger) {
+  for (const subPlan of Object.values(plans.subPlans)) {
+    planRecursively(subPlan, planDebugger);
+  }
+  plans.plan.plan(planDebugger);
+}
+function planQuery(ast, model, planDebugger) {
+  const plans = buildPlanGraph(ast, model);
+  planRecursively(plans, planDebugger);
+  return applyPlansToAST(ast, plans);
+}
+function applyToCondition(condition, flippedIds) {
+  if (condition.type === "simple") {
+    return condition;
+  }
+  if (condition.type === "correlatedSubquery") {
+    const planId = condition[planIdSymbol];
+    const shouldFlip = planId !== void 0 && flippedIds.has(planId);
+    return {
+      ...condition,
+      flip: shouldFlip ? true : condition.flip,
+      related: {
+        ...condition.related,
+        subquery: {
+          ...condition.related.subquery,
+          where: condition.related.subquery.where ? applyToCondition(condition.related.subquery.where, flippedIds) : void 0
+        }
+      }
+    };
+  }
+  return {
+    ...condition,
+    conditions: condition.conditions.map((c) => applyToCondition(c, flippedIds))
+  };
+}
+function applyPlansToAST(ast, plans) {
+  const flippedIds = /* @__PURE__ */ new Set();
+  for (const join of plans.plan.joins) {
+    if (join.type === "flipped" && join.planId !== void 0) {
+      flippedIds.add(join.planId);
+    }
+  }
+  return {
+    ...ast,
+    where: ast.where ? applyToCondition(ast.where, flippedIds) : void 0,
+    related: ast.related?.map((csq) => {
+      const alias = must(
+        csq.subquery.alias,
+        "Related subquery must have alias"
+      );
+      const subPlan = plans.subPlans[alias];
+      return {
+        ...csq,
+        subquery: subPlan ? applyPlansToAST(csq.subquery, subPlan) : csq.subquery
+      };
+    })
+  };
+}
+
+// ../zql/src/query/expression.ts
+var ExpressionBuilder = class {
+  #exists;
+  constructor(exists) {
+    this.#exists = exists;
+    this.exists = this.exists.bind(this);
+  }
+  get eb() {
+    return this;
+  }
+  cmp(field, opOrValue, value) {
+    return cmp(field, opOrValue, value);
+  }
+  cmpLit(left, op, right) {
+    return {
+      type: "simple",
+      left: isParameterReference(left) ? left[toStaticParam]() : { type: "literal", value: left },
+      right: isParameterReference(right) ? right[toStaticParam]() : { type: "literal", value: right },
+      op
+    };
+  }
+  and = and;
+  or = or;
+  not = not;
+  exists = (relationship, cb, options) => this.#exists(relationship, cb, options);
+};
+function and(...conditions) {
+  const expressions = filterTrue(filterUndefined(conditions));
+  if (expressions.length === 1) {
+    return expressions[0];
+  }
+  if (expressions.some(isAlwaysFalse)) {
+    return FALSE;
+  }
+  return { type: "and", conditions: expressions };
+}
+function or(...conditions) {
+  const expressions = filterFalse(filterUndefined(conditions));
+  if (expressions.length === 1) {
+    return expressions[0];
+  }
+  if (expressions.some(isAlwaysTrue)) {
+    return TRUE;
+  }
+  return { type: "or", conditions: expressions };
+}
+function not(expression) {
+  switch (expression.type) {
+    case "and":
+      return {
+        type: "or",
+        conditions: expression.conditions.map(not)
+      };
+    case "or":
+      return {
+        type: "and",
+        conditions: expression.conditions.map(not)
+      };
+    case "correlatedSubquery":
+      return {
+        type: "correlatedSubquery",
+        related: expression.related,
+        op: negateOperator(expression.op)
+      };
+    case "simple":
+      return {
+        type: "simple",
+        op: negateOperator(expression.op),
+        left: expression.left,
+        right: expression.right
+      };
+  }
+}
+function cmp(field, opOrValue, value) {
+  let op;
+  if (value === void 0) {
+    value = opOrValue;
+    op = "=";
+  } else {
+    op = opOrValue;
+  }
+  return {
+    type: "simple",
+    left: { type: "column", name: field },
+    right: isParameterReference(value) ? value[toStaticParam]() : { type: "literal", value },
+    op
+  };
+}
+function isParameterReference(value) {
+  return value !== null && typeof value === "object" && value[toStaticParam];
+}
+var TRUE = {
+  type: "and",
+  conditions: []
+};
+var FALSE = {
+  type: "or",
+  conditions: []
+};
+function isAlwaysTrue(condition) {
+  return condition.type === "and" && condition.conditions.length === 0;
+}
+function isAlwaysFalse(condition) {
+  return condition.type === "or" && condition.conditions.length === 0;
+}
+function simplifyCondition(c) {
+  if (c.type === "simple" || c.type === "correlatedSubquery") {
+    return c;
+  }
+  if (c.conditions.length === 1) {
+    return simplifyCondition(c.conditions[0]);
+  }
+  const conditions = flatten(c.type, c.conditions.map(simplifyCondition));
+  if (c.type === "and" && conditions.some(isAlwaysFalse)) {
+    return FALSE;
+  }
+  if (c.type === "or" && conditions.some(isAlwaysTrue)) {
+    return TRUE;
+  }
+  return {
+    type: c.type,
+    conditions
+  };
+}
+function flatten(type, conditions) {
+  const flattened = [];
+  for (const c of conditions) {
+    if (c.type === type) {
+      flattened.push(...c.conditions);
+    } else {
+      flattened.push(c);
+    }
+  }
+  return flattened;
+}
+var negateSimpleOperatorMap = {
+  ["="]: "!=",
+  ["!="]: "=",
+  ["<"]: ">=",
+  [">"]: "<=",
+  [">="]: "<",
+  ["<="]: ">",
+  ["IN"]: "NOT IN",
+  ["NOT IN"]: "IN",
+  ["LIKE"]: "NOT LIKE",
+  ["NOT LIKE"]: "LIKE",
+  ["ILIKE"]: "NOT ILIKE",
+  ["NOT ILIKE"]: "ILIKE",
+  ["IS"]: "IS NOT",
+  ["IS NOT"]: "IS"
+};
+var negateOperatorMap = {
+  ...negateSimpleOperatorMap,
+  ["EXISTS"]: "NOT EXISTS",
+  ["NOT EXISTS"]: "EXISTS"
+};
+function negateOperator(op) {
+  return must(negateOperatorMap[op]);
+}
+function filterUndefined(array10) {
+  return array10.filter((e) => e !== void 0);
+}
+function filterTrue(conditions) {
+  return conditions.filter((c) => !isAlwaysTrue(c));
+}
+function filterFalse(conditions) {
+  return conditions.filter((c) => !isAlwaysFalse(c));
+}
+
+// ../zql/src/builder/like.ts
 function getLikePredicate(pattern, flags) {
   const op = getLikeOp(String(pattern), flags);
   return (lhs) => {
@@ -9666,8 +11221,11 @@ function transformFilters(filters) {
 }
 
 // ../zql/src/builder/builder.ts
-function buildPipeline(ast, delegate, queryID) {
+function buildPipeline(ast, delegate, queryID, costModel) {
   ast = delegate.mapAst ? delegate.mapAst(ast) : ast;
+  if (costModel) {
+    ast = planQuery(ast, costModel);
+  }
   return buildPipelineInternal(ast, delegate, queryID, "");
 }
 var EXISTS_LIMIT = 3;
@@ -11094,25 +12652,47 @@ var MockClientLockManager = class {
   }
 };
 
-// ../zero-client/src/client/connection-manager.ts
-import { resolver as resolver9 } from "@rocicorp/resolver";
-
-// ../zero-client/src/client/connection-status-enum.ts
-var connection_status_enum_exports = {};
-__export(connection_status_enum_exports, {
-  Closed: () => Closed,
-  Connected: () => Connected,
-  Connecting: () => Connecting,
-  Disconnected: () => Disconnected
-});
-var Disconnected = "disconnected";
-var Connecting = "connecting";
-var Connected = "connected";
-var Closed = "closed";
-
+// ../zero-client/src/client/connection-manager.ts
+import { resolver as resolver9 } from "@rocicorp/resolver";
+
+// ../shared/src/subscribable.ts
+var Subscribable = class {
+  _listeners = /* @__PURE__ */ new Set();
+  /**
+   * Subscribe to the subscribable.
+   *
+   * @param listener - The listener to subscribe to.
+   * @returns A function to unsubscribe from the subscribable.
+   */
+  subscribe = (listener) => {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  };
+  /**
+   * Notify all listeners.
+   *
+   * @param update - The update to notify listeners with.
+   */
+  notify = (update) => {
+    this._listeners.forEach((listener) => listener(update));
+  };
+  hasListeners = () => this._listeners.size > 0;
+  /**
+   * Unsubscribe all listeners.
+   */
+  cleanup = () => {
+    this._listeners.clear();
+  };
+};
+
 // ../zero-client/src/client/connection-manager.ts
 var DEFAULT_TIMEOUT_CHECK_INTERVAL_MS = 1e3;
-var ConnectionManager = class extends Subscribable {
+var TERMINAL_STATES = [
+  connection_status_enum_exports.Error
+];
+var ConnectionManager = class _ConnectionManager extends Subscribable {
   #state;
   /**
    * The timestamp when we first started trying to connect.
@@ -11160,14 +12740,34 @@ var ConnectionManager = class extends Subscribable {
   is(status) {
     return this.#state.name === status;
   }
+  /**
+   * Returns true if the current state is a terminal state
+   * that can be recovered from by calling connect().
+   */
+  isInTerminalState() {
+    return _ConnectionManager.isTerminalState(this.#state);
+  }
+  /**
+   * Returns true if the given status is a terminal state
+   * that can be recovered from by calling connect().
+   */
+  static isTerminalState(state) {
+    return TERMINAL_STATES.includes(
+      state.name
+    );
+  }
   /**
    * Returns true if the run loop should continue.
-   * The run loop continues in disconnected, connecting, and connected states.
+   * The run loop continues in disconnected, connecting, connected, and error states.
    * It stops in closed state.
    */
   shouldContinueRunLoop() {
     return this.#state.name !== connection_status_enum_exports.Closed;
   }
+  /**
+   * Waits for the next state change.
+   * @returns A promise that resolves when the next state change occurs.
+   */
   waitForStateChange() {
     return this.#nextStatePromise();
   }
@@ -11259,29 +12859,55 @@ var ConnectionManager = class extends Subscribable {
     return { nextStatePromise };
   }
   /**
-   * Transition to closed state.
-   * This is terminal - no further transitions are allowed.
+   * Transition to error state.
+   * This pauses the run loop until connect() is called.
+   * Resets the 5-minute retry window and attempt counter.
    *
    * @returns An object containing a promise that resolves on the next state change.
    */
-  closed() {
+  error(reason) {
     if (this.#state.name === connection_status_enum_exports.Closed) {
       return { nextStatePromise: this.#nextStatePromise() };
     }
+    if (this.#state.name === connection_status_enum_exports.Error) {
+      return { nextStatePromise: this.#nextStatePromise() };
+    }
     this.#connectingStartedAt = void 0;
     this.#maybeStopTimeoutInterval();
     this.#state = {
-      name: connection_status_enum_exports.Closed
+      name: connection_status_enum_exports.Error,
+      reason
     };
     const nextStatePromise = this.#publishStateAndGetPromise();
     return { nextStatePromise };
   }
+  /**
+   * Transition to closed state.
+   * This is terminal - no further transitions are allowed.
+   */
+  closed() {
+    if (this.#state.name === connection_status_enum_exports.Closed) {
+      return;
+    }
+    this.#connectingStartedAt = void 0;
+    this.#maybeStopTimeoutInterval();
+    this.#state = {
+      name: connection_status_enum_exports.Closed,
+      reason: new ClientError({
+        kind: client_error_kind_enum_exports.ClientClosed,
+        message: "Zero was explicitly closed by calling zero.close()"
+      })
+    };
+    this.#publishState();
+    this.cleanup();
+    return;
+  }
   cleanup = () => {
     this._listeners.clear();
     this.#resolveNextStateWaiters();
   };
   #resolveNextStateWaiters() {
-    this.#stateChangeResolver.resolve();
+    this.#stateChangeResolver.resolve(this.#state);
     this.#stateChangeResolver = resolver9();
   }
   #publishState() {
@@ -11305,7 +12931,12 @@ var ConnectionManager = class extends Subscribable {
     }
     const now = Date.now();
     if (now >= this.#state.disconnectAt) {
-      this.disconnected();
+      this.disconnected(
+        new ClientError({
+          kind: client_error_kind_enum_exports.DisconnectTimeout,
+          message: `Zero was unable to connect for ${Math.floor(this.#disconnectTimeoutMs / 1e3)} seconds and was disconnected`
+        })
+      );
       return true;
     }
     return false;
@@ -11326,6 +12957,56 @@ var ConnectionManager = class extends Subscribable {
     this.#timeoutInterval = void 0;
   }
 };
+var throwIfConnectionError = (state) => {
+  if (ConnectionManager.isTerminalState(state) || state.name === connection_status_enum_exports.Closed || (state.name === connection_status_enum_exports.Connecting || state.name === connection_status_enum_exports.Disconnected) && state.reason) {
+    if (isClientError(state.reason) && (state.reason.kind === client_error_kind_enum_exports.ConnectTimeout || state.reason.kind === client_error_kind_enum_exports.AbruptClose || state.reason.kind === client_error_kind_enum_exports.CleanClose)) {
+      return;
+    }
+    throw state.reason;
+  }
+};
+
+// ../zero-client/src/client/connection.ts
+var ConnectionImpl = class {
+  #connectionManager;
+  #lc;
+  #source;
+  constructor(connectionManager, lc) {
+    this.#connectionManager = connectionManager;
+    this.#lc = lc;
+    this.#source = new ConnectionSource(connectionManager);
+  }
+  get state() {
+    return this.#source;
+  }
+  async connect() {
+    const lc = this.#lc.withContext("connect");
+    if (!this.#connectionManager.isInTerminalState()) {
+      lc.debug?.(
+        "connect() called but not in a terminal state. Current state:",
+        this.#connectionManager.state.name
+      );
+      return;
+    }
+    lc.info?.(
+      `Resuming connection from state: ${this.#connectionManager.state.name}`
+    );
+    const { nextStatePromise } = this.#connectionManager.connecting();
+    await nextStatePromise;
+  }
+};
+var ConnectionSource = class {
+  #connectionManager;
+  constructor(connectionManager) {
+    this.#connectionManager = connectionManager;
+  }
+  get current() {
+    return this.#connectionManager.state;
+  }
+  get subscribe() {
+    return this.#connectionManager.subscribe;
+  }
+};
 
 // ../zql/src/ivm/memory-storage.ts
 import { compareUTF8 as compareUTF83 } from "compare-utf8";
@@ -13267,7 +14948,7 @@ function makeMessage(message, context, logLevel) {
 }
 
 // ../zero-client/src/client/version.ts
-var version2 = "0.25.0-canary.0";
+var version2 = "0.25.0-canary.1";
 
 // ../zero-client/src/client/log-options.ts
 var LevelFilterLogSink = class {
@@ -13323,74 +15004,6 @@ function createLogOptions(options, createDatadogLogSink = (options2) => new Data
   };
 }
 
-// ../zero-client/src/client/client-error-kind-enum.ts
-var client_error_kind_enum_exports = {};
-__export(client_error_kind_enum_exports, {
-  AbruptClose: () => AbruptClose,
-  CleanClose: () => CleanClose,
-  ClientClosed: () => ClientClosed,
-  ConnectTimeout: () => ConnectTimeout,
-  DisconnectTimeout: () => DisconnectTimeout,
-  Hidden: () => Hidden,
-  NoSocketOrigin: () => NoSocketOrigin,
-  PingTimeout: () => PingTimeout,
-  UnexpectedBaseCookie: () => UnexpectedBaseCookie
-});
-var AbruptClose = "AbruptClose";
-var CleanClose = "CleanClose";
-var ClientClosed = "ClientClosed";
-var ConnectTimeout = "ConnectTimeout";
-var DisconnectTimeout = "DisconnectTimeout";
-var UnexpectedBaseCookie = "UnexpectedBaseCookie";
-var PingTimeout = "PingTimeout";
-var Hidden = "Hidden";
-var NoSocketOrigin = "NoSocketOrigin";
-
-// ../zero-client/src/client/error.ts
-var BaseError = class extends Error {
-  errorBody;
-  constructor(errorBody, options) {
-    super(errorBody.kind + ": " + errorBody.message, options);
-    this.errorBody = errorBody;
-  }
-  get kind() {
-    return this.errorBody.kind;
-  }
-};
-var ServerError = class extends BaseError {
-  get name() {
-    return "ServerError";
-  }
-};
-var ClientError = class extends BaseError {
-  get name() {
-    return "ClientError";
-  }
-};
-function isServerError(ex) {
-  return ex instanceof ServerError;
-}
-function isAuthError(ex) {
-  return isServerError(ex) && isAuthErrorKind(ex.kind);
-}
-function isAuthErrorKind(kind) {
-  return kind === error_kind_enum_exports.AuthInvalidated || kind === error_kind_enum_exports.Unauthorized;
-}
-function isBackoffError(ex) {
-  if (isServerError(ex)) {
-    switch (ex.errorBody.kind) {
-      case error_kind_enum_exports.Rebalance:
-      case error_kind_enum_exports.Rehome:
-      case error_kind_enum_exports.ServerOverloaded:
-        return ex.errorBody;
-    }
-  }
-  return void 0;
-}
-function isClientError(ex) {
-  return ex instanceof ClientError;
-}
-
 // ../zero-client/src/client/metric-name-enum.ts
 var metric_name_enum_exports = {};
 __export(metric_name_enum_exports, {
@@ -13417,6 +15030,21 @@ function getLastConnectErrorValue(reason) {
 function camelToSnake(kind) {
   return kind.split(/\.?(?=[A-Z])/).join("_").toLowerCase();
 }
+function shouldReportConnectError(reason) {
+  if (!isClientError(reason)) {
+    return true;
+  }
+  switch (reason.kind) {
+    case client_error_kind_enum_exports.Hidden:
+    case client_error_kind_enum_exports.ClientClosed:
+    case client_error_kind_enum_exports.UserDisconnect:
+    case client_error_kind_enum_exports.CleanClose:
+    case client_error_kind_enum_exports.AbruptClose:
+      return false;
+    default:
+      return true;
+  }
+}
 var MetricManager = class {
   #reportIntervalMs;
   #host;
@@ -13647,10 +15275,11 @@ var MutationTracker = class {
   #allMutationsAppliedListeners;
   #lc;
   #ackMutations;
+  #onFatalError;
   #clientID;
   #largestOutstandingMutationID;
   #currentMutationID;
-  constructor(lc, ackMutations) {
+  constructor(lc, ackMutations, onFatalError) {
     this.#lc = lc.withContext("MutationTracker");
     this.#outstandingMutations = /* @__PURE__ */ new Map();
     this.#ephemeralIDsByMutationID = /* @__PURE__ */ new Map();
@@ -13658,6 +15287,7 @@ var MutationTracker = class {
     this.#largestOutstandingMutationID = 0;
     this.#currentMutationID = 0;
     this.#ackMutations = ackMutations;
+    this.#onFatalError = onFatalError;
   }
   setClientIDAndWatch(clientID, experimentalWatch) {
     assert(this.#clientID === void 0, "clientID already set");
@@ -13745,10 +15375,53 @@ var MutationTracker = class {
         "Received an error response when pushing mutations",
         response
       );
+      const fatalError = this.#fatalErrorFromPushError(response);
+      if (fatalError) {
+        this.#onFatalError(fatalError);
+      }
     } else {
       this.#processPushOk(response);
     }
   }
+  #fatalErrorFromPushError(error) {
+    switch (error.error) {
+      case "unsupportedPushVersion":
+        return new ProtocolError({
+          kind: error_kind_enum_exports.PushFailed,
+          origin: error_origin_enum_exports.ZeroCache,
+          reason: error_reason_enum_exports.Internal,
+          message: `Unsupported push version`,
+          mutationIDs: []
+        });
+      case "unsupportedSchemaVersion":
+        return new ProtocolError({
+          kind: error_kind_enum_exports.PushFailed,
+          origin: error_origin_enum_exports.ZeroCache,
+          reason: error_reason_enum_exports.Internal,
+          message: `Unsupported schema version`,
+          mutationIDs: []
+        });
+      case "http":
+        return new ProtocolError({
+          kind: error_kind_enum_exports.PushFailed,
+          origin: error_origin_enum_exports.ZeroCache,
+          reason: error_reason_enum_exports.HTTP,
+          status: error.status,
+          message: `Fetch from API server returned non-OK status ${error.status}: ${error.details ?? "unknown"}`,
+          mutationIDs: []
+        });
+      case "zeroPusher":
+        return new ProtocolError({
+          kind: error_kind_enum_exports.PushFailed,
+          origin: error_origin_enum_exports.ZeroCache,
+          reason: error_reason_enum_exports.Internal,
+          message: `ZeroPusher error: ${error.details ?? "unknown"}`,
+          mutationIDs: []
+        });
+      default:
+        unreachable(error);
+    }
+  }
   /**
    * DEPRECATED: to be removed when we switch to fully driving
    * mutation resolution via poke.
@@ -13842,6 +15515,17 @@ var MutationTracker = class {
     const entry = this.#outstandingMutations.get(ephemeralID);
     assert(entry && entry.mutationID === mid);
     this.#settleMutation(ephemeralID, entry, "reject", error);
+    if (error.error === "oooMutation") {
+      this.#onFatalError(
+        new ProtocolError({
+          kind: error_kind_enum_exports.InvalidPush,
+          origin: error_origin_enum_exports.Server,
+          reason: error_reason_enum_exports.Internal,
+          message: "Server reported an out-of-order mutation",
+          details: error.details
+        })
+      );
+    }
   }
   #processMutationOk(clientID, mid, result) {
     assert(
@@ -13891,16 +15575,13 @@ var MutationTracker = class {
   }
 };
 
-// ../zero-client/src/client/ping-result-enum.ts
-var TimedOut = 0;
-var Success = 1;
-
 // ../zero-client/src/client/query-manager.ts
 var QueryManager = class {
   #clientID;
   #clientToServer;
   #serverToClient;
   #send;
+  #onFatalError;
   #queries = /* @__PURE__ */ new Map();
   #recentQueriesMaxSize;
   #recentQueries = /* @__PURE__ */ new Set();
@@ -13914,7 +15595,7 @@ var QueryManager = class {
   #metrics = newMetrics();
   #queryMetrics = /* @__PURE__ */ new Map();
   #slowMaterializeThreshold;
-  constructor(lc, mutationTracker, clientID, tables, send2, experimentalWatch, recentQueriesMaxSize, queryChangeThrottleMs, slowMaterializeThreshold) {
+  constructor(lc, mutationTracker, clientID, tables, send2, experimentalWatch, recentQueriesMaxSize, queryChangeThrottleMs, slowMaterializeThreshold, onFatalError) {
     this.#lc = lc.withContext("QueryManager");
     this.#clientID = clientID;
     this.#clientToServer = clientToServer(tables);
@@ -13924,6 +15605,7 @@ var QueryManager = class {
     this.#mutationTracker = mutationTracker;
     this.#queryChangeThrottleMs = queryChangeThrottleMs;
     this.#slowMaterializeThreshold = slowMaterializeThreshold;
+    this.#onFatalError = onFatalError;
     this.#mutationTracker.onAllMutationsApplied(() => {
       if (this.#pendingRemovals.length === 0) {
         return;
@@ -14030,6 +15712,26 @@ var QueryManager = class {
       if (entry) {
         entry.gotCallbacks.forEach((callback) => callback(false, error));
       }
+      if (error.error !== "app") {
+        this.#onFatalError(
+          new ProtocolError(
+            error.error === "http" ? {
+              kind: error_kind_enum_exports.TransformFailed,
+              origin: error_origin_enum_exports.ZeroCache,
+              reason: error_reason_enum_exports.HTTP,
+              message: `HTTP ${error.status} transforming queries`,
+              status: error.status,
+              queryIDs: []
+            } : {
+              kind: error_kind_enum_exports.TransformFailed,
+              origin: error_origin_enum_exports.ZeroCache,
+              reason: error_reason_enum_exports.Internal,
+              message: `Unknown error transforming queries`,
+              queryIDs: []
+            }
+          )
+        );
+      }
     }
   }
   addCustom(ast, { name, args }, ttl, gotCallback) {
@@ -14845,20 +16547,20 @@ var Zero = class _Zero {
   };
   #zeroContext;
   queryDelegate;
-  #connectResolver = resolver11();
   #pendingPullsByRequestID = /* @__PURE__ */ new Map();
   #lastMutationIDReceived = 0;
   #socket = void 0;
   #socketResolver = resolver11();
   /**
-   * This resolver is only used for rejections. It is awaited in the connected
-   * state (including when waiting for a pong). It is rejected when we get an
-   * invalid message or an 'error' message.
+   * Utility promise that resolves when the socket transitions to connected.
+   * It rejects if we hit an error or timeout before the connected message.
+   * Used by push/pull helpers to queue work until the connection is usable.
    */
-  #rejectMessageError = void 0;
+  #connectResolver = resolver11();
   #closeAbortController = new AbortController();
   #visibilityWatcher;
   #connectionManager;
+  #connection;
   #activeClientsManager;
   #inspector;
   #connectStart = void 0;
@@ -14894,7 +16596,10 @@ var Zero = class _Zero {
       slowMaterializeThreshold = 5e3
     } = options;
     if (!userID) {
-      throw new Error("ZeroOptions.userID must not be empty.");
+      throw new ClientError({
+        kind: client_error_kind_enum_exports.Internal,
+        message: "ZeroOptions.userID must not be empty."
+      });
     }
     const server = getServer(options.server);
     this.#enableAnalytics = shouldEnableAnalytics(
@@ -14912,9 +16617,10 @@ var Zero = class _Zero {
       }
     }
     if (hiddenTabDisconnectDelay < 0) {
-      throw new Error(
-        "ZeroOptions.hiddenTabDisconnectDelay must not be negative."
-      );
+      throw new ClientError({
+        kind: client_error_kind_enum_exports.Internal,
+        message: "ZeroOptions.hiddenTabDisconnectDelay must not be negative."
+      });
     }
     this.#onlineManager = new OnlineManager();
     if (onOnlineChange) {
@@ -14933,7 +16639,12 @@ var Zero = class _Zero {
     });
     const { enableLegacyMutators = true, enableLegacyQueries = true } = schema;
     const replicacheMutators = {
-      [CRUD_MUTATION_NAME]: enableLegacyMutators ? makeCRUDMutator(schema) : () => Promise.reject(new Error("Zero CRUD mutators are not enabled."))
+      [CRUD_MUTATION_NAME]: enableLegacyMutators ? makeCRUDMutator(schema) : () => Promise.reject(
+        new ClientError({
+          kind: client_error_kind_enum_exports.Internal,
+          message: "Zero CRUD mutators are not enabled."
+        })
+      )
     };
     this.#ivmMain = new IVMSourceBranch(schema.tables);
     function assertUnique(key) {
@@ -14959,7 +16670,10 @@ var Zero = class _Zero {
     const lc = new ZeroLogContext(logOptions.logLevel, {}, logSink);
     this.#mutationTracker = new MutationTracker(
       lc,
-      (upTo) => this.#send(["ackMutationResponses", upTo])
+      (upTo) => this.#send(["ackMutationResponses", upTo]),
+      (error) => {
+        this.#disconnect(lc, error);
+      }
     );
     if (options.mutators) {
       for (const [namespaceOrKey, mutatorOrMutators] of Object.entries(
@@ -15065,6 +16779,7 @@ var Zero = class _Zero {
     this.#server = server;
     this.userID = userID;
     this.#lc = lc.withContext("clientID", rep.clientID);
+    this.#connection = new ConnectionImpl(this.#connectionManager, this.#lc);
     this.#mutationTracker.setClientIDAndWatch(
       rep.clientID,
       rep.experimentalWatch.bind(rep)
@@ -15135,7 +16850,10 @@ var Zero = class _Zero {
       rep.experimentalWatch.bind(rep),
       maxRecentQueries,
       options.queryChangeThrottleMs ?? DEFAULT_QUERY_CHANGE_THROTTLE_MS,
-      slowMaterializeThreshold
+      slowMaterializeThreshold,
+      (error) => {
+        this.#disconnect(lc, error);
+      }
     );
     this.#clientToServer = clientToServer(schema.tables);
     this.#deleteClientsManager = new DeleteClientsManager(
@@ -15326,6 +17044,25 @@ var Zero = class _Zero {
    * will throw an error.
    */
   mutateBatch;
+  /**
+   * The connection API for managing Zero's connection lifecycle.
+   *
+   * Use this to monitor connection state and manually control connections.
+   *
+   * @example
+   * ```ts
+   * // Subscribe to connection state changes
+   * z.connection.state.subscribe(state => {
+   *   console.log('Connection state:', state.name);
+   * });
+   *
+   * // Manually resume connection from error state
+   * await z.connection.connect();
+   * ```
+   */
+  get connection() {
+    return this.#connection;
+  }
   /**
    * Whether this Zero instance has been closed.
    *
@@ -15371,7 +17108,6 @@ var Zero = class _Zero {
       throw e;
     } finally {
       this.#connectionManager.closed();
-      this.#connectionManager.cleanup();
     }
   }
   #onMessage = (e) => {
@@ -15381,11 +17117,6 @@ var Zero = class _Zero {
       lc.debug?.("ignoring message because already closed");
       return;
     }
-    const rejectInvalidMessage = (e2) => this.#rejectMessageError?.reject(
-      new Error(
-        `Invalid message received from server: ${e2 instanceof Error ? e2.message + ". " : ""}${data}`
-      )
-    );
     let downMessage;
     const { data } = e;
     try {
@@ -15395,7 +17126,11 @@ var Zero = class _Zero {
         "passthrough"
       );
     } catch (e2) {
-      rejectInvalidMessage(e2);
+      const invalidMessageError = new ClientError({
+        kind: client_error_kind_enum_exports.InvalidMessage,
+        message: `Invalid message received from server: ${e2 instanceof Error ? e2.message + ". " : ""}${data}`
+      });
+      this.#disconnect(lc, invalidMessageError);
       return;
     }
     this.#messageCount++;
@@ -15430,9 +17165,14 @@ var Zero = class _Zero {
         break;
       case "inspect":
         break;
-      default:
-        msgType;
-        rejectInvalidMessage();
+      default: {
+        const invalidMessageError = new ClientError({
+          kind: client_error_kind_enum_exports.InvalidMessage,
+          message: `Invalid message received from server: ${data}`
+        });
+        this.#disconnect(lc, invalidMessageError);
+        return;
+      }
     }
   };
   #onOpen = () => {
@@ -15481,11 +17221,10 @@ var Zero = class _Zero {
       return;
     }
     lc.info?.(`${kind}: ${message}}`);
-    const error = new ServerError(downMessage[1]);
+    const error = new ProtocolError(downMessage[1]);
     lc.error?.(`${error.kind}:
 
 ${error.errorBody.message}`, error);
-    this.#rejectMessageError?.reject(error);
     lc.debug?.("Rejecting connect resolver due to error", error);
     this.#connectResolver.reject(error);
     this.#disconnect(lc, error);
@@ -15691,8 +17430,14 @@ ${error.errorBody.message}`, error);
     }
   }
   #disconnect(lc, reason, closeCode) {
-    if (this.#connectionManager.is(connection_status_enum_exports.Connecting)) {
+    if (shouldReportConnectError(reason)) {
       this.#connectErrorCount++;
+      this.#metrics.lastConnectError.set(getLastConnectErrorValue(reason));
+      this.#metrics.timeToConnectMs.set(DID_NOT_CONNECT_VALUE);
+      this.#metrics.setConnectError(reason);
+      if (this.#connectErrorCount % CHECK_CONNECTIVITY_ON_ERROR_FREQUENCY === 1) {
+        this.#checkConnectivity(`connectErrorCount=${this.#connectErrorCount}`);
+      }
     }
     lc.info?.("disconnecting", {
       navigatorOnline: localNavigator?.onLine,
@@ -15705,8 +17450,8 @@ ${error.errorBody.message}`, error);
       connectionState: this.#connectionManager.state,
       connectErrorCount: this.#connectErrorCount
     });
-    const connectionState = this.#connectionManager.state.name;
-    switch (connectionState) {
+    const connectionStatus = this.#connectionManager.state.name;
+    switch (connectionStatus) {
       case connection_status_enum_exports.Connected: {
         if (this.#connectStart !== void 0) {
           lc.error?.(
@@ -15715,26 +17460,15 @@ ${error.errorBody.message}`, error);
         }
         break;
       }
-      case connection_status_enum_exports.Disconnected:
-      case connection_status_enum_exports.Connecting: {
-        this.#metrics.lastConnectError.set(getLastConnectErrorValue(reason));
-        this.#metrics.timeToConnectMs.set(DID_NOT_CONNECT_VALUE);
-        this.#metrics.setConnectError(reason);
-        if (this.#connectErrorCount % CHECK_CONNECTIVITY_ON_ERROR_FREQUENCY === 1) {
-          this.#checkConnectivity(
-            `connectErrorCount=${this.#connectErrorCount}`
-          );
-        }
-        if (this.#connectStart === void 0) {
-          lc.error?.(
-            "disconnect() called while connecting but connect start time is undefined."
-          );
-        }
-        break;
-      }
       case connection_status_enum_exports.Closed:
-        lc.error?.("disconnect() called while closed");
+        lc.debug?.("disconnect() called while closed");
         return;
+      case connection_status_enum_exports.Disconnected:
+      case connection_status_enum_exports.Connecting:
+      case connection_status_enum_exports.Error:
+        break;
+      default:
+        unreachable(connectionStatus);
     }
     this.#socketResolver = resolver11();
     lc.debug?.("Creating new connect resolver");
@@ -15749,11 +17483,22 @@ ${error.errorBody.message}`, error);
     this.#socket = void 0;
     this.#lastMutationIDSent = NULL_LAST_MUTATION_ID_SENT;
     this.#pokeHandler.handleDisconnect();
-    const isStillConnecting = reason instanceof ClientError && (reason.kind === client_error_kind_enum_exports.ConnectTimeout || reason.kind === client_error_kind_enum_exports.Hidden);
-    if (isStillConnecting) {
-      this.#connectionManager.connecting(reason);
-    } else {
-      this.#connectionManager.disconnected(reason);
+    const transition = getErrorConnectionTransition(reason);
+    switch (transition.status) {
+      case connection_status_enum_exports.Error:
+        this.#connectionManager.error(transition.reason);
+        break;
+      case connection_status_enum_exports.Disconnected:
+        this.#connectionManager.disconnected(transition.reason);
+        break;
+      case connection_status_enum_exports.Closed:
+        this.#connectionManager.closed();
+        break;
+      case NO_STATUS_TRANSITION:
+        this.#connectionManager.connecting(transition.reason);
+        break;
+      default:
+        unreachable(transition);
     }
   }
   #handlePokeStart(_lc, pokeMessage) {
@@ -15872,7 +17617,7 @@ ${error.errorBody.message}`, error);
     this.#lc.info?.(`Starting Zero version: ${this.version}`);
     if (this.#server === null) {
       this.#lc.info?.("No socket origin provided, not starting connect loop.");
-      this.#connectionManager.disconnected(
+      this.#connectionManager.error(
         new ClientError({
           kind: client_error_kind_enum_exports.NoSocketOrigin,
           message: "No server socket origin provided"
@@ -15892,22 +17637,29 @@ ${error.errorBody.message}`, error);
     await this.#updateAuthToken(bareLogContext);
     let needsReauth = false;
     let lastReauthAttemptAt;
-    let gotError = false;
-    let backoffMs = RUN_LOOP_INTERVAL_MS;
+    let backoffMs;
     let additionalConnectParams;
     while (this.#connectionManager.shouldContinueRunLoop()) {
       runLoopCounter++;
       let lc = getLogContext();
       backoffMs = RUN_LOOP_INTERVAL_MS;
       try {
-        switch (this.#connectionManager.state.name) {
+        const currentState = this.#connectionManager.state;
+        switch (currentState.name) {
           case connection_status_enum_exports.Connecting:
           case connection_status_enum_exports.Disconnected: {
             if (this.#visibilityWatcher.visibilityState === "hidden") {
               this.#metrics.setDisconnectedWaitingForVisible();
               this.#totalToConnectStart = void 0;
             }
-            await this.#visibilityWatcher.waitForVisible();
+            const visibilityResult = await promiseRace({
+              visible: this.#visibilityWatcher.waitForVisible(),
+              stateChange: this.#connectionManager.waitForStateChange()
+            });
+            if (visibilityResult.key === "stateChange") {
+              throwIfConnectionError(visibilityResult.result);
+              break;
+            }
             if (needsReauth) {
               lastReauthAttemptAt = Date.now();
               await this.#updateAuthToken(lc, "invalid-token");
@@ -15917,13 +17669,10 @@ ${error.errorBody.message}`, error);
             }
             await this.#connect(lc, additionalConnectParams);
             additionalConnectParams = void 0;
-            if (this.closed) {
-              break;
-            }
+            throwIfConnectionError(this.#connectionManager.state);
             assert(this.#socket);
             lc = getLogContext();
             lc.debug?.("Connected successfully");
-            gotError = false;
             needsReauth = false;
             this.#setOnline(true);
             break;
@@ -15935,51 +17684,52 @@ ${error.errorBody.message}`, error);
               PING_INTERVAL_MS,
               controller.signal
             );
-            this.#rejectMessageError = resolver11();
-            const PING = 0;
-            const HIDDEN = 2;
-            const raceResult = await promiseRace([
-              pingTimeoutPromise,
-              pingTimeoutAborted,
-              this.#visibilityWatcher.waitForHidden(),
-              this.#connectionManager.waitForStateChange(),
-              this.#rejectMessageError.promise
-            ]);
-            if (this.closed) {
-              this.#rejectMessageError = void 0;
-              break;
-            }
-            switch (raceResult) {
-              case PING: {
-                const pingResult = await this.#ping(
-                  lc,
-                  this.#rejectMessageError.promise
-                );
-                if (pingResult === TimedOut) {
-                  gotError = true;
-                }
+            const raceResult = await promiseRace({
+              waitForPing: pingTimeoutPromise,
+              waitForPingAborted: pingTimeoutAborted,
+              tabHidden: this.#visibilityWatcher.waitForHidden(),
+              stateChange: this.#connectionManager.waitForStateChange()
+            });
+            switch (raceResult.key) {
+              case "waitForPing": {
+                await this.#ping(lc);
                 break;
               }
-              case HIDDEN:
-                this.#disconnect(
-                  lc,
-                  new ClientError({
-                    kind: client_error_kind_enum_exports.Hidden,
-                    message: "Connection closed because tab was hidden"
-                  })
-                );
+              case "waitForPingAborted":
+                break;
+              case "tabHidden": {
+                const hiddenError = new ClientError({
+                  kind: client_error_kind_enum_exports.Hidden,
+                  message: "Connection closed because tab was hidden"
+                });
+                this.#disconnect(lc, hiddenError);
                 this.#setOnline(false);
                 break;
+              }
+              case "stateChange":
+                throwIfConnectionError(raceResult.result);
+                break;
+              default:
+                unreachable(raceResult);
             }
-            this.#rejectMessageError = void 0;
+            break;
+          }
+          case connection_status_enum_exports.Error: {
+            lc.info?.(
+              `Run loop paused in error state. Call zero.connection.connect() to resume.`,
+              currentState.reason
+            );
+            await this.#connectionManager.waitForStateChange();
             break;
           }
           case connection_status_enum_exports.Closed:
-            this.#rejectMessageError = void 0;
             break;
+          default:
+            unreachable(currentState);
         }
       } catch (ex) {
-        if (!this.#connectionManager.is(connection_status_enum_exports.Connected)) {
+        const isClientClosedError = isClientError(ex) && ex.kind === client_error_kind_enum_exports.ClientClosed;
+        if (!this.#connectionManager.is(connection_status_enum_exports.Connected) && !isClientClosedError) {
           const level = isAuthError(ex) ? "warn" : "error";
           const kind = isServerError(ex) ? ex.kind : "Unknown Error";
           lc[level]?.("Failed to connect", ex, kind, {
@@ -15994,38 +17744,56 @@ ${error.errorBody.message}`, error);
           "exception:",
           ex
         );
-        if (isAuthError(ex)) {
-          const now = Date.now();
-          const msSinceLastReauthAttempt = lastReauthAttemptAt === void 0 ? Number.POSITIVE_INFINITY : now - lastReauthAttemptAt;
-          needsReauth = true;
-          if (msSinceLastReauthAttempt > RUN_LOOP_INTERVAL_MS) {
-            continue;
+        const transition = getErrorConnectionTransition(ex);
+        switch (transition.status) {
+          case NO_STATUS_TRANSITION: {
+            const backoffParams = getBackoffParams(transition.reason);
+            if (backoffParams) {
+              if (backoffParams.minBackoffMs !== void 0) {
+                backoffMs = Math.max(backoffMs, backoffParams.minBackoffMs);
+              }
+              if (backoffParams.maxBackoffMs !== void 0) {
+                backoffMs = Math.min(backoffMs, backoffParams.maxBackoffMs);
+              }
+              additionalConnectParams = backoffParams.reconnectParams;
+            }
+            if (isAuthError(transition.reason)) {
+              const now = Date.now();
+              const msSinceLastReauthAttempt = lastReauthAttemptAt === void 0 ? Number.POSITIVE_INFINITY : now - lastReauthAttemptAt;
+              needsReauth = true;
+              if (msSinceLastReauthAttempt > RUN_LOOP_INTERVAL_MS) {
+                continue;
+              }
+            }
+            this.#setOnline(false);
+            lc.debug?.(
+              "Sleeping",
+              backoffMs,
+              "ms before reconnecting due to error, state:",
+              this.#connectionManager.state
+            );
+            await sleep(backoffMs);
+            break;
           }
-        }
-        if (isServerError(ex) || isClientError(ex) && (ex.kind === client_error_kind_enum_exports.ConnectTimeout || ex.kind === client_error_kind_enum_exports.AbruptClose || ex.kind === client_error_kind_enum_exports.CleanClose)) {
-          gotError = true;
-        }
-        const backoffError = isBackoffError(ex);
-        if (backoffError) {
-          if (backoffError.minBackoffMs !== void 0) {
-            backoffMs = Math.max(backoffMs, backoffError.minBackoffMs);
+          case connection_status_enum_exports.Error: {
+            lc.debug?.("Fatal error encountered, transitioning to error state");
+            this.#setOnline(false);
+            this.#connectionManager.error(transition.reason);
+            break;
+          }
+          case connection_status_enum_exports.Disconnected: {
+            this.#setOnline(false);
+            this.#connectionManager.disconnected(transition.reason);
+            break;
           }
-          if (backoffError.maxBackoffMs !== void 0) {
-            backoffMs = Math.min(backoffMs, backoffError.maxBackoffMs);
+          case connection_status_enum_exports.Closed: {
+            this.#setOnline(false);
+            break;
           }
-          additionalConnectParams = backoffError.reconnectParams;
+          default:
+            unreachable(transition);
         }
       }
-      if (gotError) {
-        this.#setOnline(false);
-        lc.debug?.(
-          "Sleeping",
-          backoffMs,
-          "ms before reconnecting due to error, state:",
-          this.#connectionManager.state
-        );
-        await sleep(backoffMs);
-      }
     }
   }
   async #puller(req, requestID) {
@@ -16061,17 +17829,18 @@ ${error.errorBody.message}`, error);
     const pullResponseResolver = resolver11();
     this.#pendingPullsByRequestID.set(requestID, pullResponseResolver);
     try {
-      const TIMEOUT = 0;
-      const RESPONSE = 1;
-      const raceResult = await promiseRace([
-        sleep(PULL_TIMEOUT_MS),
-        pullResponseResolver.promise
-      ]);
-      switch (raceResult) {
-        case TIMEOUT:
+      const raceResult = await promiseRace({
+        timeout: sleep(PULL_TIMEOUT_MS),
+        success: pullResponseResolver.promise
+      });
+      switch (raceResult.key) {
+        case "timeout":
           lc.debug?.("Mutation recovery pull timed out");
-          throw new Error("Pull timed out");
-        case RESPONSE: {
+          throw new ClientError({
+            kind: client_error_kind_enum_exports.PullTimeout,
+            message: "Pull timed out"
+          });
+        case "success": {
           lc.debug?.("Returning mutation recovery pull response");
           const response = await pullResponseResolver.promise;
           return {
@@ -16087,10 +17856,15 @@ ${error.errorBody.message}`, error);
           };
         }
         default:
-          unreachable();
+          unreachable(raceResult);
       }
     } finally {
-      pullResponseResolver.reject("timed out");
+      pullResponseResolver.reject(
+        new ClientError({
+          kind: client_error_kind_enum_exports.PullTimeout,
+          message: "Pull timed out"
+        })
+      );
       this.#pendingPullsByRequestID.delete(requestID);
     }
   }
@@ -16100,6 +17874,8 @@ ${error.errorBody.message}`, error);
   /**
    * A rough heuristic for whether the client is currently online and
    * authenticated.
+   *
+   * @deprecated Use `connection` instead, which provides more detailed connection state.
    */
   get online() {
     return this.#onlineManager.online;
@@ -16111,15 +17887,14 @@ ${error.errorBody.message}`, error);
    *
    * @param listener - The listener to subscribe to.
    * @returns A function to unsubscribe the listener.
+   *
+   * @deprecated Use `connection` instead, which provides more detailed connection state.
    */
   onOnline = (listener) => this.#onlineManager.subscribe(listener);
   /**
    * Starts a ping and waits for a pong.
-   *
-   * If it takes too long to get a pong we disconnect and this returns
-   * {@linkcode PingResult.TimedOut}.
    */
-  async #ping(lc, messageErrorRejectionPromise) {
+  async #ping(lc) {
     lc.debug?.("pinging");
     const { promise, resolve } = resolver11();
     this.#onPong = resolve;
@@ -16127,25 +17902,37 @@ ${error.errorBody.message}`, error);
     const t0 = performance.now();
     assert(this.#socket);
     send(this.#socket, pingMessage);
-    const connected = await promiseRace([
-      promise,
-      sleep(PING_TIMEOUT_MS),
-      messageErrorRejectionPromise
-    ]) === 0;
+    const raceResult = await promiseRace({
+      waitForPong: promise,
+      pingTimeout: sleep(PING_TIMEOUT_MS),
+      stateChange: this.#connectionManager.waitForStateChange()
+    });
     const delta = performance.now() - t0;
-    if (!connected) {
-      lc.info?.("ping failed in", delta, "ms - disconnecting");
-      this.#disconnect(
-        lc,
-        new ClientError({
+    switch (raceResult.key) {
+      case "waitForPong": {
+        lc.debug?.("ping succeeded in", delta, "ms");
+        return;
+      }
+      case "pingTimeout": {
+        lc.info?.("ping failed in", delta, "ms - disconnecting");
+        const pingTimeoutError = new ClientError({
           kind: client_error_kind_enum_exports.PingTimeout,
-          message: "Server ping request timed out"
-        })
-      );
-      return TimedOut;
+          message: "Server ping request failed"
+        });
+        this.#disconnect(lc, pingTimeoutError);
+        throw pingTimeoutError;
+      }
+      case "stateChange": {
+        lc.debug?.(
+          "ping aborted due to connection state change",
+          raceResult.result
+        );
+        throwIfConnectionError(raceResult.result);
+        break;
+      }
+      default:
+        unreachable(raceResult);
     }
-    lc.debug?.("ping succeeded in", delta, "ms");
-    return Success;
   }
   // Sends a set of metrics to the server. Throws unless the server
   // returns 200.
@@ -16304,9 +18091,6 @@ function addWebSocketIDFromSocketToLogContext({ url }, lc) {
 function addWebSocketIDToLogContext(wsid, lc) {
   return lc.withContext("wsid", wsid);
 }
-function promiseRace(ps) {
-  return Promise.race(ps.map((p, i) => p.then(() => i)));
-}
 function assertValidRunOptions2(_options) {
 }
 async function makeActiveClientsManager(clientGroupID, clientID, signal, onDelete) {
@@ -16326,12 +18110,14 @@ export {
   dropDatabase,
   dropAllDatabases,
   TransactionClosedError,
+  error_kind_enum_exports,
+  error_origin_enum_exports,
+  error_reason_enum_exports,
   transformRequestMessageSchema,
   transformResponseMessageSchema,
-  error_kind_enum_exports,
   table,
-  string2 as string,
-  number2 as number,
+  string4 as string,
+  number4 as number,
   boolean,
   json,
   enumeration,
@@ -16344,7 +18130,10 @@ export {
   newQuerySymbol,
   AbstractQuery,
   clientToServer,
+  client_error_kind_enum_exports,
+  connection_status_enum_exports,
+  ClientError,
   update_needed_reason_type_enum_exports,
   Zero
 };
-//# sourceMappingURL=chunk-MXPHMVU7.js.map
+//# sourceMappingURL=chunk-AIPM77UE.js.map