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

package/out/{chunk-MXPHMVU7.js → chunk-COKJ5W7V.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,58 +1512,102 @@ function rejectIfClosed(tx) {
   return tx.closed ? Promise.reject(new TransactionClosedError()) : void 0;
 }
 
-// ../zero-protocol/src/custom-queries.ts
-var transformRequestBodySchema = valita_exports.array(
-  valita_exports.object({
-    id: valita_exports.string(),
-    name: valita_exports.string(),
-    args: readonly(valita_exports.array(jsonSchema))
-  })
-);
-var transformedQuerySchema = valita_exports.object({
-  id: valita_exports.string(),
-  name: valita_exports.string(),
-  ast: astSchema
-});
-var appQueryErrorSchema = valita_exports.object({
-  error: valita_exports.literal("app"),
-  id: valita_exports.string(),
-  name: valita_exports.string(),
-  details: jsonSchema
-});
-var zeroErrorSchema = valita_exports.object({
-  error: valita_exports.literal("zero"),
-  id: valita_exports.string(),
-  name: valita_exports.string(),
-  details: jsonSchema
-});
-var httpQueryErrorSchema = valita_exports.object({
-  error: valita_exports.literal("http"),
-  id: valita_exports.string(),
-  name: valita_exports.string(),
-  status: valita_exports.number(),
-  details: jsonSchema
-});
-var erroredQuerySchema = valita_exports.union(
-  appQueryErrorSchema,
-  httpQueryErrorSchema,
-  zeroErrorSchema
-);
-var transformResponseBodySchema = valita_exports.array(
-  valita_exports.union(transformedQuerySchema, erroredQuerySchema)
-);
-var transformRequestMessageSchema = valita_exports.tuple([
-  valita_exports.literal("transform"),
-  transformRequestBodySchema
-]);
-var transformErrorMessageSchema = valita_exports.tuple([
-  valita_exports.literal("transformError"),
-  valita_exports.array(erroredQuerySchema)
-]);
-var transformResponseMessageSchema = valita_exports.tuple([
-  valita_exports.literal("transformed"),
-  transformResponseBodySchema
-]);
+// ../shared/src/error.ts
+function getErrorMessage(error) {
+  return getErrorMessageInternal(error, /* @__PURE__ */ new Set());
+}
+function getErrorMessageInternal(error, seen) {
+  if (typeof error === "string") {
+    return error;
+  }
+  if (typeof error === "object" && error !== null) {
+    if (seen.has(error)) {
+      return "Circular error reference detected while extracting the error message.";
+    }
+    seen.add(error);
+  }
+  if (error instanceof Error) {
+    if (error.message) {
+      return error.message;
+    }
+    if ("cause" in error) {
+      const cause = error.cause;
+      if (cause !== void 0) {
+        const causeMessage = getErrorMessageInternal(cause, seen);
+        if (causeMessage) {
+          return causeMessage;
+        }
+      }
+    }
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    const message = error.message;
+    if (message) {
+      return message;
+    }
+  }
+  try {
+    const json2 = jsonSchema.parse(error);
+    return `Parsed message: ${JSON.stringify(json2)}`;
+  } catch (_e) {
+  }
+  return `Unknown error of type ${typeof error} was thrown and the message could not be determined. See cause for details.`;
+}
+function getErrorDetails(error) {
+  if (error instanceof Error) {
+    if ("details" in error) {
+      try {
+        return jsonSchema.parse(error?.details);
+      } catch (_e) {
+      }
+    }
+    if (error.name && error.name !== "Error") {
+      return { name: error.name };
+    }
+    return void 0;
+  }
+  if (typeof error === "object" && error !== null && "details" in error) {
+    try {
+      return jsonSchema.parse(error?.details);
+    } catch (_e) {
+    }
+  }
+  try {
+    return jsonSchema.parse(error);
+  } catch (_e) {
+  }
+  return void 0;
+}
+
+// ../zero-protocol/src/application-error.ts
+var ApplicationError = class extends Error {
+  /**
+   * This maps onto errors for transform and push app-level failures.
+   */
+  #details;
+  constructor(message, options) {
+    super(message, { cause: options?.cause });
+    this.name = "ApplicationError";
+    this.#details = options?.details ?? void 0;
+  }
+  get details() {
+    return this.#details;
+  }
+};
+function isApplicationError(error) {
+  return error instanceof ApplicationError;
+}
+function wrapWithApplicationError(error) {
+  if (isApplicationError(error)) {
+    return error;
+  }
+  const message = getErrorMessage(error);
+  const details = getErrorDetails(error);
+  return new ApplicationError(message, {
+    cause: error,
+    details
+  });
+}
 
 // ../zero-protocol/src/error-kind-enum.ts
 var error_kind_enum_exports = {};
@@ -1578,10 +1623,12 @@ __export(error_kind_enum_exports, {
   InvalidPush: () => InvalidPush,
   MutationFailed: () => MutationFailed,
   MutationRateLimited: () => MutationRateLimited,
+  PushFailed: () => PushFailed,
   Rebalance: () => Rebalance,
   Rehome: () => Rehome,
   SchemaVersionNotSupported: () => SchemaVersionNotSupported,
   ServerOverloaded: () => ServerOverloaded,
+  TransformFailed: () => TransformFailed,
   Unauthorized: () => Unauthorized,
   VersionNotSupported: () => VersionNotSupported
 });
@@ -1593,16 +1640,255 @@ var InvalidConnectionRequestLastMutationID = "InvalidConnectionRequestLastMutati
 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(),
+  /**
+   * The mutationIDs of the mutations that failed to process.
+   * This can be a subset of the mutationIDs in the request.
+   */
+  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(),
+  /**
+   * The queryIDs of the queries that failed to transform.
+   */
+  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({
+    id: valita_exports.string(),
+    name: valita_exports.string(),
+    args: readonly(valita_exports.array(jsonSchema))
+  })
+);
+var transformedQuerySchema = valita_exports.object({
+  id: valita_exports.string(),
+  name: valita_exports.string(),
+  ast: astSchema
+});
+var appErroredQuerySchema = valita_exports.object({
+  error: valita_exports.literal("app"),
+  id: valita_exports.string(),
+  name: valita_exports.string(),
+  // optional for backwards compatibility
+  message: valita_exports.string().optional(),
+  details: jsonSchema.optional()
+});
+var parseErroredQuerySchema = valita_exports.object({
+  error: valita_exports.literal("parse"),
+  id: valita_exports.string(),
+  name: valita_exports.string(),
+  message: valita_exports.string(),
+  details: jsonSchema.optional()
+});
+var erroredQuerySchema = valita_exports.union(
+  appErroredQuerySchema,
+  parseErroredQuerySchema
+);
+var transformResponseBodySchema = valita_exports.array(
+  valita_exports.union(transformedQuerySchema, erroredQuerySchema)
+);
+var transformRequestMessageSchema = valita_exports.tuple([
+  valita_exports.literal("transform"),
+  transformRequestBodySchema
+]);
+var transformErrorMessageSchema = valita_exports.tuple([
+  valita_exports.literal("transformError"),
+  valita_exports.array(erroredQuerySchema)
+]);
+var transformFailedMessageSchema = valita_exports.tuple([
+  valita_exports.literal("transformFailed"),
+  transformFailedBodySchema
+]);
+var transformOkMessageSchema = valita_exports.tuple([
+  valita_exports.literal("transformed"),
+  transformResponseBodySchema
+]);
+var transformResponseMessageSchema = valita_exports.union(
+  transformOkMessageSchema,
+  transformFailedMessageSchema
+);
+
 // ../zero-schema/src/builder/table-builder.ts
 function table(name) {
   return new TableBuilder({
@@ -1611,14 +1897,14 @@ function table(name) {
     primaryKey: []
   });
 }
-function string2() {
+function string4() {
   return new ColumnBuilder({
     type: "string",
     optional: false,
     customType: null
   });
 }
-function number2() {
+function number3() {
   return new ColumnBuilder({
     type: "number",
     optional: false,
@@ -2172,37 +2458,207 @@ function makeID(row, schema) {
   return JSON.stringify(schema.primaryKey.map((k) => row[k]));
 }
 
-// ../zero-client/src/client/update-needed-reason-type-enum.ts
-var update_needed_reason_type_enum_exports = {};
-__export(update_needed_reason_type_enum_exports, {
-  NewClientGroup: () => NewClientGroup,
-  SchemaVersionNotSupported: () => SchemaVersionNotSupported2,
-  VersionNotSupported: () => VersionNotSupported2
+// ../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 NewClientGroup = "NewClientGroup";
-var VersionNotSupported2 = "VersionNotSupported";
-var SchemaVersionNotSupported2 = "SchemaVersionNotSupported";
-
-// ../zero-client/src/client/zero.ts
-import "@rocicorp/logger";
-import { resolver as resolver11 } from "@rocicorp/resolver";
+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";
 
-// ../replicache/src/replicache-impl.ts
-import { Lock } from "@rocicorp/lock";
-import { consoleLogSink as consoleLogSink2 } from "@rocicorp/logger";
-import { resolver as resolver6 } 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,
+  Error: () => Error2,
+  NeedsAuth: () => NeedsAuth
+});
+var Disconnected = "disconnected";
+var Connecting = "connecting";
+var Connected = "connected";
+var NeedsAuth = "needs-auth";
+var Error2 = "error";
+var Closed = "closed";
 
-// ../shared/src/document-visible.ts
-import { resolver as resolver3 } from "@rocicorp/resolver";
-function getDocumentVisibilityWatcher(doc, hiddenIntervalMS, signal) {
-  return doc ? new DocumentVisibilityWatcherImpl(doc, hiddenIntervalMS, signal) : new DocumentVisibilityWatcherNoDoc();
-}
-var DocumentVisibilityWatcherImpl = class {
-  #doc;
-  #hiddenIntervalMS;
-  #timeoutID = 0;
-  // This trails doc.visibilityState by hiddenIntervalMS when being hidden. This
-  // is because we want to wait for the tab to be hidden for a while before
+// ../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 (ex.kind === error_kind_enum_exports.AuthInvalidated || ex.kind === error_kind_enum_exports.Unauthorized) {
+      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 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 (isAuthError(ex)) {
+    return {
+      status: connection_status_enum_exports.NeedsAuth,
+      reason: 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 (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:
+      // PushFailed and TransformFailed can be auth errors (401/403)
+      // or other errors - handle non-auth cases here
+      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 are handled above by isAuthError check
+      case error_kind_enum_exports.AuthInvalidated:
+      case error_kind_enum_exports.Unauthorized:
+        return {
+          status: connection_status_enum_exports.NeedsAuth,
+          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, {
+  NewClientGroup: () => NewClientGroup,
+  SchemaVersionNotSupported: () => SchemaVersionNotSupported2,
+  VersionNotSupported: () => VersionNotSupported2
+});
+var NewClientGroup = "NewClientGroup";
+var VersionNotSupported2 = "VersionNotSupported";
+var SchemaVersionNotSupported2 = "SchemaVersionNotSupported";
+
+// ../zero-client/src/client/zero.ts
+import "@rocicorp/logger";
+import { resolver as resolver11 } from "@rocicorp/resolver";
+
+// ../replicache/src/replicache-impl.ts
+import { Lock } from "@rocicorp/lock";
+import { consoleLogSink as consoleLogSink2 } from "@rocicorp/logger";
+import { resolver as resolver6 } from "@rocicorp/resolver";
+
+// ../shared/src/document-visible.ts
+import { resolver as resolver3 } from "@rocicorp/resolver";
+function getDocumentVisibilityWatcher(doc, hiddenIntervalMS, signal) {
+  return doc ? new DocumentVisibilityWatcherImpl(doc, hiddenIntervalMS, signal) : new DocumentVisibilityWatcherNoDoc();
+}
+var DocumentVisibilityWatcherImpl = class {
+  #doc;
+  #hiddenIntervalMS;
+  #timeoutID = 0;
+  // This trails doc.visibilityState by hiddenIntervalMS when being hidden. This
+  // is because we want to wait for the tab to be hidden for a while before
   // considering as hidden.
   visibilityState;
   #promises = /* @__PURE__ */ new Set();
@@ -6283,6 +6739,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 +6766,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 +6843,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,24 +6914,25 @@ 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
+  message: valita_exports.string().optional(),
   details: jsonSchema.optional()
 });
-var zeroErrorSchema2 = valita_exports.object({
-  error: literalUnion("oooMutation", "alreadyProcessed"),
+var zeroErrorSchema = valita_exports.object({
+  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({
   // The user can return any additional data here
   data: jsonSchema.optional()
 });
-var mutationErrorSchema = valita_exports.union(appErrorSchema, zeroErrorSchema2);
+var mutationErrorSchema = valita_exports.union(appErrorSchema, zeroErrorSchema);
 var mutationResultSchema = valita_exports.union(
   mutationOkSchema,
   mutationErrorSchema
@@ -6552,28 +6945,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 +6980,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 +7152,7 @@ var downstreamSchema = valita_exports.union(
 );
 
 // ../zero-protocol/src/protocol-version.ts
-var PROTOCOL_VERSION = 37;
+var PROTOCOL_VERSION = 39;
 var MIN_SERVER_SUPPORTED_SYNC_PROTOCOL = 18;
 assert(MIN_SERVER_SUPPORTED_SYNC_PROTOCOL < PROTOCOL_VERSION);
 
@@ -9227,80 +9629,1385 @@ var UnionFanIn = class {
         return;
       }
     }
-    assert(hadMatch, "Pusher was not one of the inputs to union-fan-in!");
-    this.#output.push(change, this);
+    assert(hadMatch, "Pusher was not one of the inputs to union-fan-in!");
+    this.#output.push(change, this);
+  }
+  fanOutStartedPushing() {
+    assert(this.#fanOutPushStarted === false);
+    this.#fanOutPushStarted = true;
+  }
+  fanOutDonePushing(fanOutChangeType) {
+    assert(this.#fanOutPushStarted);
+    this.#fanOutPushStarted = false;
+    if (this.#inputs.length === 0) {
+      return;
+    }
+    if (this.#accumulatedPushes.length === 0) {
+      return;
+    }
+    pushAccumulatedChanges(
+      this.#accumulatedPushes,
+      this.#output,
+      this,
+      fanOutChangeType,
+      mergeRelationships,
+      makeAddEmptyRelationships(this.#schema)
+    );
+  }
+  setOutput(output) {
+    this.#output = output;
+  }
+};
+
+// ../zql/src/ivm/union-fan-out.ts
+var UnionFanOut = class {
+  #destroyCount = 0;
+  #unionFanIn;
+  #input;
+  #outputs = [];
+  constructor(input) {
+    this.#input = input;
+    input.setOutput(this);
+  }
+  setFanIn(fanIn) {
+    assert(!this.#unionFanIn, "FanIn already set for this FanOut");
+    this.#unionFanIn = fanIn;
+  }
+  push(change) {
+    must(this.#unionFanIn).fanOutStartedPushing();
+    for (const output of this.#outputs) {
+      output.push(change, this);
+    }
+    must(this.#unionFanIn).fanOutDonePushing(change.type);
+  }
+  setOutput(output) {
+    this.#outputs.push(output);
+  }
+  getSchema() {
+    return this.#input.getSchema();
+  }
+  fetch(req) {
+    return this.#input.fetch(req);
+  }
+  cleanup(_req) {
+    return [];
+  }
+  destroy() {
+    if (this.#destroyCount < this.#outputs.length) {
+      ++this.#destroyCount;
+      if (this.#destroyCount === this.#outputs.length) {
+        this.#input.destroy();
+      }
+    } else {
+      throw new Error("FanOut already destroyed once for each output");
+    }
+  }
+};
+
+// ../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 type() {
+    return this.#type;
+  }
+  closestJoinOrSource() {
+    return "join";
+  }
+  setOutput(node) {
+    this.#output = node;
+  }
+  get output() {
+    assert(this.#output !== void 0, "Output not set");
+    return this.#output;
+  }
+  reset() {
+    this.#type = "FI";
+  }
+  convertToUFI() {
+    this.#type = "UFI";
+  }
+  /**
+   * 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();
+      }
+    }
+  }
+  estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
+    let totalCost = {
+      returnedRows: 0,
+      cost: 0,
+      scanEst: 0,
+      startupCost: 0,
+      selectivity: 0,
+      limit: void 0
+    };
+    if (this.#type === "FI") {
+      const updatedPattern = [0, ...branchPattern];
+      let maxrows = 0;
+      let maxRunningCost = 0;
+      let maxStartupCost = 0;
+      let maxScanEst = 0;
+      let noMatchProb = 1;
+      for (const input of this.#inputs) {
+        const cost = input.estimateCost(
+          downstreamChildSelectivity,
+          updatedPattern,
+          planDebugger
+        );
+        if (cost.returnedRows > maxrows) {
+          maxrows = cost.returnedRows;
+        }
+        if (cost.cost > maxRunningCost) {
+          maxRunningCost = cost.cost;
+        }
+        if (cost.startupCost > maxStartupCost) {
+          maxStartupCost = cost.startupCost;
+        }
+        if (cost.scanEst > maxScanEst) {
+          maxScanEst = cost.scanEst;
+        }
+        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.returnedRows = maxrows;
+      totalCost.cost = maxRunningCost;
+      totalCost.selectivity = 1 - noMatchProb;
+      totalCost.startupCost = maxStartupCost;
+      totalCost.scanEst = maxScanEst;
+    } else {
+      let i = 0;
+      let noMatchProb = 1;
+      for (const input of this.#inputs) {
+        const updatedPattern = [i, ...branchPattern];
+        const cost = input.estimateCost(
+          downstreamChildSelectivity,
+          updatedPattern,
+          planDebugger
+        );
+        totalCost.returnedRows += cost.returnedRows;
+        totalCost.cost += cost.cost;
+        totalCost.scanEst += cost.scanEst;
+        totalCost.startupCost = 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;
+    }
+    planDebugger?.log({
+      type: "node-cost",
+      nodeType: "fan-in",
+      node: this.#type,
+      branchPattern,
+      downstreamChildSelectivity,
+      costEstimate: totalCost
+    });
+    return totalCost;
+  }
+  propagateConstraints(branchPattern, constraint, from, planDebugger) {
+    planDebugger?.log({
+      type: "node-constraint",
+      nodeType: "fan-in",
+      node: this.#type,
+      branchPattern,
+      constraint,
+      from: from?.kind ?? "unknown"
+    });
+    if (this.#type === "FI") {
+      const updatedPattern = [0, ...branchPattern];
+      for (const input of this.#inputs) {
+        input.propagateConstraints(
+          updatedPattern,
+          constraint,
+          this,
+          planDebugger
+        );
+      }
+      return;
+    }
+    let i = 0;
+    for (const input of this.#inputs) {
+      input.propagateConstraints(
+        [i, ...branchPattern],
+        constraint,
+        this,
+        planDebugger
+      );
+      i++;
+    }
+  }
+};
+
+// ../zql/src/planner/planner-fan-out.ts
+var PlannerFanOut = class {
+  kind = "fan-out";
+  #type;
+  #outputs = [];
+  #input;
+  constructor(input) {
+    this.#type = "FO";
+    this.#input = input;
+  }
+  get type() {
+    return this.#type;
+  }
+  addOutput(node) {
+    this.#outputs.push(node);
+  }
+  get outputs() {
+    return this.#outputs;
+  }
+  closestJoinOrSource() {
+    return this.#input.closestJoinOrSource();
+  }
+  propagateConstraints(branchPattern, constraint, from, planDebugger) {
+    planDebugger?.log({
+      type: "node-constraint",
+      nodeType: "fan-out",
+      node: "FO",
+      branchPattern,
+      constraint,
+      from: from?.kind ?? "unknown"
+    });
+    this.#input.propagateConstraints(
+      branchPattern,
+      constraint,
+      this,
+      planDebugger
+    );
+  }
+  estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
+    const ret = this.#input.estimateCost(
+      downstreamChildSelectivity,
+      branchPattern,
+      planDebugger
+    );
+    planDebugger?.log({
+      type: "node-cost",
+      nodeType: "fan-out",
+      node: "FO",
+      branchPattern,
+      downstreamChildSelectivity,
+      costEstimate: ret
+    });
+    return ret;
+  }
+  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();
+    }
+  }
+};
+
+// ../zql/src/planner/planner-constraint.ts
+function mergeConstraints(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return { ...a, ...b };
+}
+
+// ../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;
+  #isRoot;
+  /**
+   * 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();
+  constructor(table2, model, sort, filters, isRoot, 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();
+    this.#isRoot = isRoot;
+    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, from, planDebugger) {
+    const key = path.join(",");
+    this.#constraints.set(key, c);
+    this.#cachedConstraintCosts.clear();
+    planDebugger?.log({
+      type: "node-constraint",
+      nodeType: "connection",
+      node: this.name,
+      branchPattern: path,
+      constraint: c,
+      from: from?.kind ?? "unknown"
+    });
+  }
+  estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
+    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 = {
+      startupCost,
+      scanEst: this.limit === void 0 ? rows : Math.min(rows, this.limit / downstreamChildSelectivity),
+      cost: 0,
+      returnedRows: rows,
+      selectivity: this.selectivity,
+      limit: this.limit
+    };
+    this.#cachedConstraintCosts.set(key, cost);
+    planDebugger?.log({
+      type: "node-cost",
+      nodeType: "connection",
+      node: this.name,
+      branchPattern,
+      downstreamChildSelectivity,
+      costEstimate: cost,
+      filters: this.#filters
+    });
+    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.#isRoot) {
+      return;
+    }
+    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.#cachedConstraintCosts.clear();
+  }
+  /**
+   * 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.#cachedConstraintCosts.clear();
+  }
+  /**
+   * Get current constraints for debugging.
+   * Returns a copy of the constraints map.
+   */
+  getConstraintsForDebug() {
+    return new Map(this.#constraints);
+  }
+  /**
+   * Get filters for debugging.
+   * Returns the filters applied to this connection.
+   */
+  getFiltersForDebug() {
+    return this.#filters;
+  }
+  /**
+   * Get estimated cost for each constraint branch.
+   * Returns a map of constraint key to cost estimate.
+   * Forces cost calculation if not already cached.
+   */
+  getConstraintCostsForDebug() {
+    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, isRoot, baseConstraints, limit) {
+    return new PlannerConnection(
+      this.name,
+      this.#model,
+      sort,
+      filters,
+      isRoot,
+      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(planDebugger) {
+    assert(
+      this.#terminus !== void 0,
+      "Cannot propagate constraints without a terminus node"
+    );
+    this.#terminus.propagateConstraints(planDebugger);
+  }
+  /**
+   * Calculate total cost of the current plan.
+   * Total cost includes both startup cost (one-time, e.g., sorting) and running cost.
+   */
+  getTotalCost(planDebugger) {
+    const estimate = must(this.#terminus).estimateCost(planDebugger);
+    return estimate.cost + estimate.startupCost;
+  }
+  /**
+   * 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);
+  }
+  /**
+   * 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;
+    const forcePattern = void 0;
+    for (let pattern = 0; pattern < numPatterns; pattern++) {
+      if (forcePattern !== void 0 && pattern !== forcePattern) {
+        continue;
+      }
+      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(planDebugger);
+        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(planDebugger);
+        if (planDebugger) {
+          planDebugger.log({
+            type: "plan-complete",
+            attemptNumber: pattern,
+            totalCost,
+            flipPattern: pattern,
+            // Bitmask of which joins are flipped
+            // TODO: we'll need a different way to collect these
+            // 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(planDebugger);
+      if (planDebugger) {
+        planDebugger.log({
+          type: "best-plan-selected",
+          bestAttemptNumber,
+          totalCost: bestCost,
+          flipPattern: bestAttemptNumber,
+          // The best attempt number is also the flip pattern
+          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
+function translateConstraintsForFlippedJoin(incomingConstraint, parentConstraint, childConstraint) {
+  if (!incomingConstraint) return void 0;
+  const parentKeys = Object.keys(parentConstraint);
+  const childKeys = Object.keys(childConstraint);
+  const translated = {};
+  for (const [key, value] of Object.entries(incomingConstraint)) {
+    const index = parentKeys.indexOf(key);
+    if (index !== -1) {
+      translated[childKeys[index]] = value;
+    }
+  }
+  return Object.keys(translated).length > 0 ? translated : void 0;
+}
+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 when this join is flipped.
+   * When a join is flipped:
+   * 1. Child becomes outer loop → produces all rows (unlimited)
+   * 2. Parent is fetched once per child row → effectively unlimited
+   *
+   * Example: If child produces 896 rows, parent is fetched 896 times.
+   * Even if each fetch returns 1 row, parent produces 896 total rows.
+   *
+   * Propagation rules:
+   * - Connection: call unlimit()
+   * - Semi-join: continue to parent (outer loop)
+   * - Flipped join: stop (already unlimited when it was flipped)
+   * - Fan-out/Fan-in: propagate to all inputs
+   */
+  propagateUnlimit() {
+    assert(this.#type === "flipped", "Can only unlimit a flipped join");
+    this.#parent.propagateUnlimitFromFlippedJoin();
+    this.#child.propagateUnlimitFromFlippedJoin();
+  }
+  /**
+   * 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") {
+      this.#parent.propagateUnlimitFromFlippedJoin();
+    }
+  }
+  propagateConstraints(branchPattern, constraint, from, planDebugger) {
+    planDebugger?.log({
+      type: "node-constraint",
+      nodeType: "join",
+      node: this.getName(),
+      branchPattern,
+      constraint,
+      from: from ? getNodeName(from) : "unknown"
+    });
+    if (this.#type === "semi") {
+      this.#child.propagateConstraints(
+        branchPattern,
+        this.#childConstraint,
+        this,
+        planDebugger
+      );
+      this.#parent.propagateConstraints(
+        branchPattern,
+        constraint,
+        this,
+        planDebugger
+      );
+    } else if (this.#type === "flipped") {
+      const translatedConstraint = translateConstraintsForFlippedJoin(
+        constraint,
+        this.#parentConstraint,
+        this.#childConstraint
+      );
+      this.#child.propagateConstraints(
+        branchPattern,
+        translatedConstraint,
+        this,
+        planDebugger
+      );
+      this.#parent.propagateConstraints(
+        branchPattern,
+        mergeConstraints(constraint, this.#parentConstraint),
+        this,
+        planDebugger
+      );
+    }
   }
-  fanOutStartedPushing() {
-    assert(this.#fanOutPushStarted === false);
-    this.#fanOutPushStarted = true;
+  reset() {
+    this.#type = "semi";
   }
-  fanOutDonePushing(fanOutChangeType) {
-    assert(this.#fanOutPushStarted);
-    this.#fanOutPushStarted = false;
-    if (this.#inputs.length === 0) {
-      return;
-    }
-    if (this.#accumulatedPushes.length === 0) {
-      return;
-    }
-    pushAccumulatedChanges(
-      this.#accumulatedPushes,
-      this.#output,
-      this,
-      fanOutChangeType,
-      mergeRelationships,
-      makeAddEmptyRelationships(this.#schema)
+  estimateCost(downstreamChildSelectivity, branchPattern, planDebugger) {
+    const child = this.#child.estimateCost(1, branchPattern, planDebugger);
+    const parent = this.#parent.estimateCost(
+      // Selectivity flows up the graph from child to parent
+      // so we can determine the total selectivity of all ANDed exists checks.
+      child.selectivity * downstreamChildSelectivity,
+      branchPattern,
+      planDebugger
     );
+    let costEstimate;
+    if (this.type === "semi") {
+      costEstimate = {
+        startupCost: parent.startupCost,
+        scanEst: parent.limit === void 0 ? parent.returnedRows : Math.min(
+          parent.returnedRows,
+          parent.limit / downstreamChildSelectivity
+        ),
+        cost: parent.cost + parent.scanEst * (child.startupCost + child.scanEst),
+        returnedRows: parent.returnedRows * child.selectivity,
+        selectivity: child.selectivity * parent.selectivity,
+        limit: parent.limit
+      };
+    } else {
+      costEstimate = {
+        startupCost: child.startupCost,
+        scanEst: parent.limit === void 0 ? parent.returnedRows : Math.min(
+          parent.returnedRows * child.returnedRows,
+          parent.limit / downstreamChildSelectivity
+        ),
+        cost: child.cost + child.scanEst * (parent.startupCost + parent.scanEst),
+        returnedRows: parent.returnedRows * child.returnedRows * child.selectivity,
+        selectivity: parent.selectivity * child.selectivity,
+        limit: parent.limit
+      };
+    }
+    planDebugger?.log({
+      type: "node-cost",
+      nodeType: "join",
+      node: this.getName(),
+      branchPattern,
+      downstreamChildSelectivity,
+      costEstimate,
+      joinType: this.#type
+    });
+    return costEstimate;
   }
-  setOutput(output) {
-    this.#output = output;
+  /**
+   * 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";
+  }
+}
 
-// ../zql/src/ivm/union-fan-out.ts
-var UnionFanOut = class {
-  #destroyCount = 0;
-  #unionFanIn;
+// ../zql/src/planner/planner-terminus.ts
+var PlannerTerminus = class {
+  kind = "terminus";
   #input;
-  #outputs = [];
   constructor(input) {
     this.#input = input;
-    input.setOutput(this);
   }
-  setFanIn(fanIn) {
-    assert(!this.#unionFanIn, "FanIn already set for this FanOut");
-    this.#unionFanIn = fanIn;
+  get pinned() {
+    return true;
   }
-  push(change) {
-    must(this.#unionFanIn).fanOutStartedPushing();
-    for (const output of this.#outputs) {
-      output.push(change, this);
+  closestJoinOrSource() {
+    return this.#input.closestJoinOrSource();
+  }
+  propagateConstraints(planDebugger) {
+    this.#input.propagateConstraints([], void 0, this, planDebugger);
+  }
+  estimateCost(planDebugger) {
+    return this.#input.estimateCost(1, [], planDebugger);
+  }
+  /**
+   * Propagate unlimiting when a parent join is flipped.
+   * Terminus doesn't participate in unlimiting.
+   */
+  propagateUnlimitFromFlippedJoin() {
+  }
+};
+
+// ../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, isRoot, baseConstraints) {
+  const graph = new PlannerGraph();
+  let nextPlanId = 0;
+  const source = graph.addSource(ast.table, model);
+  const connection = source.connect(
+    ast.orderBy ?? [],
+    ast.where,
+    isRoot,
+    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,
+        true,
+        childConstraints
+      );
     }
-    must(this.#unionFanIn).fanOutDonePushing(change.type);
   }
-  setOutput(output) {
-    this.#outputs.push(output);
+  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
+      );
   }
-  getSchema() {
-    return this.#input.getSchema();
+}
+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
+    );
   }
-  fetch(req) {
-    return this.#input.fetch(req);
+  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;
   }
-  cleanup(_req) {
-    return [];
+  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);
   }
-  destroy() {
-    if (this.#destroyCount < this.#outputs.length) {
-      ++this.#destroyCount;
-      if (this.#destroyCount === this.#outputs.length) {
-        this.#input.destroy();
+  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,
+    false,
+    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, true);
+  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
+        }
       }
-    } else {
-      throw new Error("FanOut already destroyed once for each output");
+    };
+  }
+  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 {
@@ -9461,8 +11168,8 @@ var negateOperatorMap = {
 function negateOperator(op) {
   return must(negateOperatorMap[op]);
 }
-function filterUndefined(array9) {
-  return array9.filter((e) => e !== void 0);
+function filterUndefined(array10) {
+  return array10.filter((e) => e !== void 0);
 }
 function filterTrue(conditions) {
   return conditions.filter((c) => !isAlwaysTrue(c));
@@ -9666,8 +11373,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;
@@ -11097,22 +12807,45 @@ 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";
+// ../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.NeedsAuth,
+  connection_status_enum_exports.Error
+];
+var ConnectionManager = class _ConnectionManager extends Subscribable {
   #state;
   /**
    * The timestamp when we first started trying to connect.
@@ -11160,14 +12893,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.
-   * It stops in closed state.
+   * The run loop continues in all states except closed.
+   * In needs-auth and error states, the run loop pauses and waits for connect() to be called.
    */
   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();
   }
@@ -11217,42 +12970,88 @@ var ConnectionManager = class extends Subscribable {
    *
    * @returns An object containing a promise that resolves on the next state change.
    */
-  connected() {
+  connected() {
+    if (this.#state.name === connection_status_enum_exports.Closed) {
+      return { nextStatePromise: this.#nextStatePromise() };
+    }
+    if (this.#state.name === connection_status_enum_exports.Connected) {
+      return { nextStatePromise: this.#nextStatePromise() };
+    }
+    this.#connectingStartedAt = void 0;
+    this.#maybeStopTimeoutInterval();
+    this.#state = {
+      name: connection_status_enum_exports.Connected
+    };
+    const nextStatePromise = this.#publishStateAndGetPromise();
+    return { nextStatePromise };
+  }
+  /**
+   * Transition to disconnected state.
+   * This is called when the 5-minute timeout expires, or when we're intentionally
+   * disconnecting due to an error (this will eventually be a separate state, error).
+   * The run loop will continue trying to reconnect.
+   *
+   * @returns An object containing a promise that resolves on the next state change.
+   */
+  disconnected(reason) {
+    if (this.#state.name === connection_status_enum_exports.Closed) {
+      return { nextStatePromise: this.#nextStatePromise() };
+    }
+    if (this.#state.name === connection_status_enum_exports.Disconnected) {
+      return { nextStatePromise: this.#nextStatePromise() };
+    }
+    if (this.#state.name === connection_status_enum_exports.Connected) {
+      this.#connectingStartedAt = void 0;
+    }
+    this.#maybeStopTimeoutInterval();
+    this.#state = {
+      name: connection_status_enum_exports.Disconnected,
+      reason
+    };
+    const nextStatePromise = this.#publishStateAndGetPromise();
+    return { nextStatePromise };
+  }
+  /**
+   * Transition to needs-auth state.
+   * This pauses the run loop until connect() is called with new credentials.
+   * Resets the retry window and attempt counter.
+   *
+   * @returns An object containing a promise that resolves on the next state change.
+   */
+  needsAuth(reason) {
     if (this.#state.name === connection_status_enum_exports.Closed) {
       return { nextStatePromise: this.#nextStatePromise() };
     }
-    if (this.#state.name === connection_status_enum_exports.Connected) {
+    if (this.#state.name === connection_status_enum_exports.NeedsAuth) {
       return { nextStatePromise: this.#nextStatePromise() };
     }
     this.#connectingStartedAt = void 0;
     this.#maybeStopTimeoutInterval();
     this.#state = {
-      name: connection_status_enum_exports.Connected
+      name: connection_status_enum_exports.NeedsAuth,
+      reason
     };
     const nextStatePromise = this.#publishStateAndGetPromise();
     return { nextStatePromise };
   }
   /**
-   * Transition to disconnected state.
-   * This is called when the 5-minute timeout expires, or when we're intentionally
-   * disconnecting due to an error (this will eventually be a separate state, error).
-   * The run loop will continue trying to reconnect.
+   * Transition to error state.
+   * This pauses the run loop until connect() is called.
+   * Resets the retry window and attempt counter.
    *
    * @returns An object containing a promise that resolves on the next state change.
    */
-  disconnected(reason) {
+  error(reason) {
     if (this.#state.name === connection_status_enum_exports.Closed) {
       return { nextStatePromise: this.#nextStatePromise() };
     }
-    if (this.#state.name === connection_status_enum_exports.Disconnected) {
+    if (this.#state.name === connection_status_enum_exports.Error) {
       return { nextStatePromise: this.#nextStatePromise() };
     }
-    if (this.#state.name === connection_status_enum_exports.Connected) {
-      this.#connectingStartedAt = void 0;
-    }
+    this.#connectingStartedAt = void 0;
     this.#maybeStopTimeoutInterval();
     this.#state = {
-      name: connection_status_enum_exports.Disconnected,
+      name: connection_status_enum_exports.Error,
       reason
     };
     const nextStatePromise = this.#publishStateAndGetPromise();
@@ -11261,27 +13060,30 @@ var ConnectionManager = class extends Subscribable {
   /**
    * Transition to closed state.
    * This is terminal - no further transitions are allowed.
-   *
-   * @returns An object containing a promise that resolves on the next state change.
    */
   closed() {
     if (this.#state.name === connection_status_enum_exports.Closed) {
-      return { nextStatePromise: this.#nextStatePromise() };
+      return;
     }
     this.#connectingStartedAt = void 0;
     this.#maybeStopTimeoutInterval();
     this.#state = {
-      name: connection_status_enum_exports.Closed
+      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()"
+      })
     };
-    const nextStatePromise = this.#publishStateAndGetPromise();
-    return { nextStatePromise };
+    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 +13107,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 +13133,62 @@ 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;
+  #setAuth;
+  constructor(connectionManager, lc, setAuth) {
+    this.#connectionManager = connectionManager;
+    this.#lc = lc;
+    this.#source = new ConnectionSource(connectionManager);
+    this.#setAuth = setAuth;
+  }
+  get state() {
+    return this.#source;
+  }
+  async connect(opts) {
+    const lc = this.#lc.withContext("connect");
+    if (opts && "auth" in opts) {
+      lc.debug?.("Updating auth credential from connect()");
+      this.#setAuth(opts.auth);
+    }
+    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 +15130,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.2";
 
 // ../zero-client/src/client/log-options.ts
 var LevelFilterLogSink = class {
@@ -13323,74 +15186,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 +15212,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 +15457,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 +15469,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");
@@ -13698,7 +15510,7 @@ var MutationTracker = class {
   rejectMutation(id, e) {
     const entry = this.#outstandingMutations.get(id);
     if (entry) {
-      this.#settleMutation(id, entry, "reject", e);
+      this.#settleMutation(id, entry, "reject", wrapWithApplicationError(e));
     }
   }
   /**
@@ -13745,10 +15557,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.
@@ -13841,7 +15696,28 @@ var MutationTracker = class {
     );
     const entry = this.#outstandingMutations.get(ephemeralID);
     assert(entry && entry.mutationID === mid);
-    this.#settleMutation(ephemeralID, entry, "reject", error);
+    this.#settleMutation(
+      ephemeralID,
+      entry,
+      "reject",
+      error.error === "app" ? new ApplicationError(
+        error.message ?? `Unknown application error: ${error.error}`,
+        error.details ? { details: error.details } : void 0
+      ) : new Error(
+        error.error === "alreadyProcessed" ? "Mutation already processed" : error.error === "oooMutation" ? "Server reported an out-of-order mutation" : `Unknown fallback error with mutation ID ${mid}: ${error.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 +15767,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 +15787,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 +15797,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;
@@ -14027,8 +15901,21 @@ var QueryManager = class {
     for (const error of errors) {
       const queryId = error.id;
       const entry = this.#queries.get(queryId);
-      if (entry) {
+      if (!entry) {
+        continue;
+      }
+      if (error.error === "app" || error.error === "parse") {
         entry.gotCallbacks.forEach((callback) => callback(false, error));
+      } else {
+        this.#onFatalError(
+          new ProtocolError({
+            kind: error_kind_enum_exports.TransformFailed,
+            origin: error_origin_enum_exports.ZeroCache,
+            reason: error_reason_enum_exports.Internal,
+            message: `Unknown error transforming queries: ${JSON.stringify(error)}`,
+            queryIDs: []
+          })
+        );
       }
     }
   }
@@ -14689,13 +16576,17 @@ function rafFallback(callback) {
 }
 
 // ../zero-client/src/client/zero-rep.ts
+var REPLICACHE_NO_AUTH_TOKEN = "";
+var toReplicacheAuthToken = (auth) => auth ?? REPLICACHE_NO_AUTH_TOKEN;
+var fromReplicacheAuthToken = (auth) => !auth ? void 0 : auth;
 var ZeroRep = class {
   #context;
   #ivmMain;
   #customMutatorsEnabled;
   #mutationTracker;
   #store;
-  #auth;
+  // matches replicache's auth token type
+  #auth = REPLICACHE_NO_AUTH_TOKEN;
   constructor(context, ivmMain, customMutatorsEnabled, mutationTracker) {
     this.#context = context;
     this.#ivmMain = ivmMain;
@@ -14703,11 +16594,7 @@ var ZeroRep = class {
     this.#mutationTracker = mutationTracker;
   }
   set auth(auth) {
-    if (auth === "") {
-      this.#auth = void 0;
-    } else {
-      this.#auth = auth;
-    }
+    this.#auth = auth;
   }
   async init(hash, store) {
     const diffs = [];
@@ -14733,7 +16620,7 @@ var ZeroRep = class {
     }
     return this.#ivmMain.forkToHead(must(this.#store), desiredHead, readOptions).then((branch) => ({
       ivmSources: branch,
-      token: this.#auth
+      token: fromReplicacheAuthToken(this.#auth)
     }));
   };
   advance = (expectedHash, newHash, diffs) => {
@@ -14845,20 +16732,21 @@ 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;
+  #unsubscribeConnectionState = void 0;
   #activeClientsManager;
   #inspector;
   #connectStart = void 0;
@@ -14894,7 +16782,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 +16803,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) {
@@ -14931,9 +16823,19 @@ var Zero = class _Zero {
     this.#connectionManager = new ConnectionManager({
       disconnectTimeoutMs: DEFAULT_DISCONNECT_TIMEOUT_MS
     });
+    const syncOnlineState = (state) => {
+      this.#onlineManager.setOnline(state.name === connection_status_enum_exports.Connected);
+    };
+    syncOnlineState(this.#connectionManager.state);
+    this.#unsubscribeConnectionState = this.#connectionManager.subscribe(syncOnlineState);
     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 +16861,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 +16970,11 @@ 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,
+      (auth) => this.#setAuth(auth)
+    );
     this.#mutationTracker.setClientIDAndWatch(
       rep.clientID,
       rep.experimentalWatch.bind(rep)
@@ -15135,7 +17045,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 +17239,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.
    *
@@ -15349,6 +17281,8 @@ var Zero = class _Zero {
         return;
       }
       lc.debug?.("Closing Zero instance. Stack:", new Error().stack);
+      this.#unsubscribeConnectionState?.();
+      this.#unsubscribeConnectionState = void 0;
       this.#onlineManager.cleanup();
       if (!this.#connectionManager.is(connection_status_enum_exports.Disconnected)) {
         this.#disconnect(
@@ -15371,7 +17305,6 @@ var Zero = class _Zero {
       throw e;
     } finally {
       this.#connectionManager.closed();
-      this.#connectionManager.cleanup();
     }
   }
   #onMessage = (e) => {
@@ -15381,11 +17314,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 +17323,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 +17362,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 +17418,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);
@@ -15607,15 +17543,19 @@ ${error.errorBody.message}`, error);
    * attempt times out.
    */
   async #connect(lc, additionalConnectParams) {
-    assert(this.#server);
+    if (this.closed) {
+      return;
+    }
+    assert(this.#server, "No server provided");
     assert(
-      this.#connectionManager.is(connection_status_enum_exports.Disconnected) || this.#connectionManager.is(connection_status_enum_exports.Connecting)
+      this.#connectionManager.is(connection_status_enum_exports.Disconnected) || this.#connectionManager.is(connection_status_enum_exports.Connecting),
+      "connect() called from invalid state: " + this.#connectionManager.state.name
     );
     const wsid = nanoid();
     lc = addWebSocketIDToLogContext(wsid, lc);
     lc.info?.("Connecting...", { navigatorOnline: localNavigator?.onLine });
     this.#connectionManager.connecting();
-    assert(this.#connectStart === void 0);
+    assert(this.#connectStart === void 0, "connect start time is defined");
     const now = Date.now();
     this.#connectStart = now;
     if (this.#totalToConnectStart === void 0) {
@@ -15655,7 +17595,7 @@ ${error.errorBody.message}`, error);
       await this.clientGroupID,
       this.#clientSchema,
       this.userID,
-      this.#rep.auth,
+      fromReplicacheAuthToken(this.#rep.auth),
       this.#lastMutationIDReceived,
       wsid,
       this.#options.logLevel === "debug",
@@ -15691,8 +17631,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 +17651,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 +17661,16 @@ ${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.NeedsAuth:
+      case connection_status_enum_exports.Error:
+        break;
+      default:
+        unreachable(connectionStatus);
     }
     this.#socketResolver = resolver11();
     lc.debug?.("Creating new connect resolver");
@@ -15749,11 +17685,25 @@ ${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.NeedsAuth:
+        this.#connectionManager.needsAuth(transition.reason);
+        break;
+      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) {
@@ -15860,19 +17810,11 @@ ${error.errorBody.message}`, error);
       }
     };
   }
-  async #updateAuthToken(lc, error) {
-    const { auth: authOption } = this.#options;
-    const auth = await (typeof authOption === "function" ? authOption(error) : authOption);
-    if (auth) {
-      lc.debug?.("Got auth token");
-      this.#rep.auth = auth;
-    }
-  }
   async #runLoop() {
     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"
@@ -15889,43 +17831,40 @@ ${error.errorBody.message}`, error);
       }
       return lc.withContext("runLoopCounter", runLoopCounter);
     };
-    await this.#updateAuthToken(bareLogContext);
-    let needsReauth = false;
-    let lastReauthAttemptAt;
-    let gotError = false;
-    let backoffMs = RUN_LOOP_INTERVAL_MS;
+    const { auth } = this.#options;
+    this.#setAuth(auth);
+    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();
-            if (needsReauth) {
-              lastReauthAttemptAt = Date.now();
-              await this.#updateAuthToken(lc, "invalid-token");
+            const visibilityResult = await promiseRace({
+              visible: this.#visibilityWatcher.waitForVisible(),
+              stateChange: this.#connectionManager.waitForStateChange()
+            });
+            if (visibilityResult.key === "stateChange") {
+              throwIfConnectionError(visibilityResult.result);
+              break;
             }
             if (reloadScheduled()) {
               break;
             }
             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;
           }
           case connection_status_enum_exports.Connected: {
@@ -15935,51 +17874,59 @@ ${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 "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);
                 break;
               }
-              case HIDDEN:
-                this.#disconnect(
-                  lc,
-                  new ClientError({
-                    kind: client_error_kind_enum_exports.Hidden,
-                    message: "Connection closed because tab was hidden"
-                  })
-                );
-                this.#setOnline(false);
+              case "stateChange":
+                throwIfConnectionError(raceResult.result);
                 break;
+              default:
+                unreachable(raceResult);
             }
-            this.#rejectMessageError = void 0;
+            break;
+          }
+          case connection_status_enum_exports.NeedsAuth: {
+            lc.info?.(
+              `Run loop paused in needs-auth state. Call zero.connection.connect({auth}) to resume.`,
+              currentState.reason
+            );
+            await this.#connectionManager.waitForStateChange();
+            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 +17941,51 @@ ${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;
+            }
+            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.NeedsAuth: {
+            lc.debug?.(
+              "Auth error encountered, transitioning to needs-auth state"
+            );
+            this.#connectionManager.needsAuth(transition.reason);
+            break;
+          }
+          case connection_status_enum_exports.Error: {
+            lc.debug?.("Fatal error encountered, transitioning to error state");
+            this.#connectionManager.error(transition.reason);
+            break;
+          }
+          case connection_status_enum_exports.Disconnected: {
+            this.#connectionManager.disconnected(transition.reason);
+            break;
           }
-          if (backoffError.maxBackoffMs !== void 0) {
-            backoffMs = Math.min(backoffMs, backoffError.maxBackoffMs);
+          case connection_status_enum_exports.Closed: {
+            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 +18021,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,19 +18048,31 @@ ${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);
     }
   }
-  #setOnline(online) {
-    this.#onlineManager.setOnline(online);
+  /**
+   * Sets the authentication token on the replicache instance.
+   *
+   * @param auth - The authentication token to set.
+   */
+  #setAuth(auth) {
+    this.#rep.auth = toReplicacheAuthToken(auth);
   }
   /**
    * 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 +18084,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 +18099,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 +18288,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 +18307,15 @@ export {
   dropDatabase,
   dropAllDatabases,
   TransactionClosedError,
+  ApplicationError,
+  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,
+  number3 as number,
   boolean,
   json,
   enumeration,
@@ -16344,7 +18328,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-COKJ5W7V.js.map