@delali/sirannon-db 0.2.3-next.26 → 0.2.3-next.28

package/dist/{chunk-WJ67DTD6.mjs → chunk-3UHAPQBW.mjs}

@@ -737,6 +737,12 @@ function refusalErrorCode(code) {
 
 // src/client/transport/ws-headers.ts
 var HEADERS_UNSUPPORTED_MESSAGE = "This runtime builds a WebSocket from the global constructor, which carries no handshake header, so 'headers' reaches the server on HTTP requests but never on the WebSocket upgrade. Carry the credential in 'webSocketProtocols' as well, which a browser handshake does carry, or create the client with { transport: 'http' }.";
+var SUBPROTOCOL_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+var MALFORMED_SUBPROTOCOL_REASON = "a subprotocol is one or more of the characters a header token allows, so it carries no space, comma, or quotation mark and is never empty";
+var REPEATED_SUBPROTOCOL_REASON = "a handshake refuses an offer that repeats a subprotocol";
+function subprotocolMessage(index, reason) {
+  return `Entry ${index} of 'webSocketProtocols' cannot be offered, because ${reason}. The entry carries a credential, so it is left out of this message.`;
+}
 function currentRuntime() {
   return globalThis;
 }
@@ -753,6 +759,24 @@ function assertHandshakeHeadersSupported(headers, webSocketProtocols, runtime =
   if (runtimeSupportsHandshakeHeaders(runtime)) return;
   throw new RemoteError("INVALID_ARGUMENT", HEADERS_UNSUPPORTED_MESSAGE);
 }
+function assertWebSocketProtocolsValid(webSocketProtocols) {
+  if (webSocketProtocols === void 0) return;
+  const offered = typeof webSocketProtocols === "string" ? [webSocketProtocols] : webSocketProtocols;
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, value] of offered.entries()) {
+    if (!SUBPROTOCOL_TOKEN.test(value)) {
+      throw new RemoteError("INVALID_ARGUMENT", subprotocolMessage(index, MALFORMED_SUBPROTOCOL_REASON));
+    }
+    if (seen.has(value)) {
+      throw new RemoteError("INVALID_ARGUMENT", subprotocolMessage(index, REPEATED_SUBPROTOCOL_REASON));
+    }
+    seen.add(value);
+  }
+}
+function assertWebSocketCredentials(headers, webSocketProtocols, runtime = currentRuntime()) {
+  assertWebSocketProtocolsValid(webSocketProtocols);
+  assertHandshakeHeadersSupported(headers, webSocketProtocols, runtime);
+}
 
 // src/client/transport/ws-connect.ts
 function createSocket(url, options) {
@@ -1382,7 +1406,7 @@ var WebSocketTransport = class {
 function resolveTransportSettings(options) {
   const transport = options?.transport ?? "websocket";
   if (transport === "websocket") {
-    assertHandshakeHeadersSupported(options?.headers, options?.webSocketProtocols);
+    assertWebSocketCredentials(options?.headers, options?.webSocketProtocols);
   }
   return {
     transport,
@@ -1446,4 +1470,4 @@ var DatabaseClient = class {
   }
 };
 
-export { DEFAULT_HTTP_REQUEST_TIMEOUT_MS, DatabaseClient, HttpTransport, RemoteDatabase, RemoteError, RemoteLiveQuery, RemoteSubscriptionBuilderImpl, SQL_REFUSED_MESSAGE, STAGED_STREAM_CAPABILITY, ServerCapabilities, WebSocketTransport, createEndpointTransport, decodeTaggedValues, encodeTaggedValues, postJson, toBaseUrl, toServerBaseUrl, toWsUrl, unrefTimer, verifyDeviceSyncCapabilities };
+export { DEFAULT_HTTP_REQUEST_TIMEOUT_MS, DatabaseClient, HttpTransport, RemoteDatabase, RemoteError, RemoteLiveQuery, RemoteSubscriptionBuilderImpl, SQL_REFUSED_MESSAGE, STAGED_STREAM_CAPABILITY, ServerCapabilities, WebSocketTransport, assertWebSocketCredentials, createEndpointTransport, decodeTaggedValues, encodeTaggedValues, postJson, toBaseUrl, toServerBaseUrl, toWsUrl, unrefTimer, verifyDeviceSyncCapabilities };

package/dist/client/index.d.ts

@@ -161,8 +161,10 @@ interface SyncControllerOptions {
     databaseId: string;
     /** Tables this device syncs. */
     tables: readonly string[];
-    /** Headers attached to every request and to the WebSocket upgrade. */
+    /** Headers attached to every HTTP request, and to the pull subscription's WebSocket upgrade in a runtime whose WebSocket carries a handshake header. */
     headers?: Record<string, string>;
+    /** Subprotocols offered on the pull subscription's WebSocket upgrade, which is how a browser device carries a credential. The controller offers `sirannon.v1` ahead of them. */
+    webSocketProtocols?: string | string[];
     /** Changes sent in one push. */
     batchSize?: number;
     /** Milliseconds between pushes of locally recorded changes. */
@@ -187,6 +189,8 @@ interface SyncControllerOptions {
     resolver?: ConflictResolver | ((table: string) => ConflictResolver);
     /** Called for each change this device pulls. */
     onChange?: (event: ChangeEvent) => void;
+    /** Called with this device's status when the controller changes state, pushes a batch, applies a pulled batch, needs a resync, or records or clears an error. */
+    onStatusChange?: (status: SyncStatus) => void;
     /** Called when the server says the device must download a fresh snapshot. */
     onResyncRequired?: () => void;
     /** Called as each snapshot page arrives. */
@@ -275,15 +279,20 @@ declare class SyncController {
     private readonly pull;
     private readonly push;
     private readonly resync;
+    private readonly statusChanges;
     private port;
     private deviceId;
     private capabilities;
     private schemaVersion;
-    private state;
+    private syncState;
     private pullRetryTimer;
     private consecutivePullFailures;
+    private pendingPushCount;
     private lastError;
     constructor(db: Database, options: SyncControllerOptions);
+    private get state();
+    private setState;
+    private setError;
     /**
      * Connects to the server and starts pushing and pulling changes.
      */
@@ -306,6 +315,8 @@ declare class SyncController {
      * @returns The device's state, cursors, pending push count, and last failure.
      */
     status(): Promise<SyncStatus>;
+    private captureStatus;
+    private refreshOutboxCount;
     /**
      * Pushes local changes now instead of waiting for the next interval.
      */

package/dist/client/index.mjs

@@ -1,5 +1,5 @@
-import { DatabaseClient, createEndpointTransport, toBaseUrl, DEFAULT_HTTP_REQUEST_TIMEOUT_MS, postJson, decodeTaggedValues, RemoteError, encodeTaggedValues, STAGED_STREAM_CAPABILITY, verifyDeviceSyncCapabilities, unrefTimer, toWsUrl, WebSocketTransport } from '../chunk-WJ67DTD6.mjs';
-export { HttpTransport, RemoteDatabase, RemoteError, RemoteLiveQuery, RemoteSubscriptionBuilderImpl, SQL_REFUSED_MESSAGE, ServerCapabilities, WebSocketTransport } from '../chunk-WJ67DTD6.mjs';
+import { DatabaseClient, createEndpointTransport, toBaseUrl, DEFAULT_HTTP_REQUEST_TIMEOUT_MS, postJson, decodeTaggedValues, RemoteError, encodeTaggedValues, assertWebSocketCredentials, STAGED_STREAM_CAPABILITY, verifyDeviceSyncCapabilities, unrefTimer, toWsUrl, WebSocketTransport } from '../chunk-3UHAPQBW.mjs';
+export { HttpTransport, RemoteDatabase, RemoteError, RemoteLiveQuery, RemoteSubscriptionBuilderImpl, SQL_REFUSED_MESSAGE, ServerCapabilities, WebSocketTransport } from '../chunk-3UHAPQBW.mjs';
 
 // src/core/sync/canonicalise.ts
 function canonicaliseForChecksum(value) {
@@ -697,6 +697,7 @@ var PullStream = class {
     const encodedId = encodeURIComponent(this.config.databaseId);
     const transport = new WebSocketTransport(`${this.config.wsBaseUrl}/db/${encodedId}`, {
       headers: this.config.headers,
+      protocols: this.config.webSocketProtocols,
       requestTimeout: this.config.requestTimeout
     });
     this.transport = transport;
@@ -1053,6 +1054,10 @@ var ResyncScheduler = class {
 };
 
 // src/client/sync-controller-wiring.ts
+function describeError(err) {
+  const code = err instanceof Error && "code" in err ? String(err.code) : "UNKNOWN_ERROR";
+  return { code, message: err instanceof Error ? err.message : String(err) };
+}
 var DEFAULT_BATCH_SIZE = 100;
 var DEFAULT_PUSH_INTERVAL_MS = 1e3;
 var DEFAULT_ACK_INTERVAL_MS = 2e3;
@@ -1086,6 +1091,7 @@ function createSyncCollaborators(baseUrl, options, host) {
       databaseId: options.databaseId,
       tables: options.tables,
       headers: options.headers,
+      webSocketProtocols: options.webSocketProtocols,
       ackIntervalMs: options.ackIntervalMs ?? DEFAULT_ACK_INTERVAL_MS,
       requestTimeout: options.requestTimeout,
       immediateAckAfterChanges: options.immediateAckAfterChanges,
@@ -1120,6 +1126,75 @@ function createSyncCollaborators(baseUrl, options, host) {
   return { push, pull, resync };
 }
 
+// src/client/sync-status-notifier.ts
+var MIN_OUTBOX_COUNT_INTERVAL_MS = 100;
+var SyncStatusNotifier = class {
+  constructor(listener, capture, refreshOutboxCount) {
+    this.listener = listener;
+    this.capture = capture;
+    this.refreshOutboxCount = refreshOutboxCount;
+  }
+  queued = [];
+  flushing = false;
+  counting = false;
+  countTimer = null;
+  lastCountAt = 0;
+  /**
+   * Captures the controller's status now and delivers it on a microtask.
+   */
+  notify() {
+    if (this.listener === void 0) return;
+    this.queued.push(this.capture());
+    this.scheduleFlush();
+    this.scheduleCount();
+  }
+  scheduleFlush() {
+    if (this.flushing) return;
+    this.flushing = true;
+    queueMicrotask(() => {
+      this.flushing = false;
+      this.flush();
+    });
+  }
+  flush() {
+    const listener = this.listener;
+    if (listener === void 0) return;
+    while (this.queued.length > 0) {
+      const status = this.queued.shift();
+      if (status === void 0) return;
+      try {
+        listener(status);
+      } catch {
+      }
+    }
+  }
+  scheduleCount() {
+    if (this.counting || this.countTimer !== null) return;
+    const waitMs = Math.max(0, this.lastCountAt + MIN_OUTBOX_COUNT_INTERVAL_MS - Date.now());
+    this.countTimer = setTimeout(() => {
+      this.countTimer = null;
+      void this.runCount();
+    }, waitMs);
+    unrefTimer(this.countTimer);
+  }
+  async runCount() {
+    this.counting = true;
+    let changed = false;
+    try {
+      changed = await this.refreshOutboxCount();
+    } catch {
+      changed = false;
+    } finally {
+      this.lastCountAt = Date.now();
+      this.counting = false;
+    }
+    if (changed) {
+      this.queued.push(this.capture());
+      this.scheduleFlush();
+    }
+  }
+};
+
 // src/client/sync-controller.ts
 var SyncController = class {
   constructor(db, options) {
@@ -1128,19 +1203,24 @@ var SyncController = class {
     this.baseUrl = toBaseUrl(options.url);
     this.pushIntervalMs = options.pushIntervalMs ?? DEFAULT_PUSH_INTERVAL_MS;
     this.maxPushRetryDelayMs = options.maxPushRetryDelayMs ?? DEFAULT_MAX_PUSH_RETRY_DELAY_MS;
+    assertWebSocketCredentials(options.headers, options.webSocketProtocols);
+    this.statusChanges = new SyncStatusNotifier(
+      options.onStatusChange,
+      () => this.captureStatus(),
+      () => this.refreshOutboxCount()
+    );
     const collaborators = createSyncCollaborators(this.baseUrl, options, {
       state: () => this.state,
       port: () => this.port,
       schemaVersion: () => this.schemaVersion ?? 0,
       reconcileSchema: () => this.reconcileSchema(),
       recordError: (err) => this.recordError(err),
-      clearError: () => {
-        this.lastError = null;
-      },
+      clearError: () => this.setError(null),
       markResyncRequired: () => this.markResyncRequired(),
       onApplyFailure: (err) => this.handleApplyFailure(err),
       onApplySuccess: () => {
         this.consecutivePullFailures = 0;
+        this.statusChanges.notify();
       },
       download: () => this.downloadSnapshot({ pageSize: options.snapshotPageSize, onProgress: options.onSnapshotProgress })
     });
@@ -1154,20 +1234,34 @@ var SyncController = class {
   pull;
   push;
   resync;
+  statusChanges;
   port = null;
   deviceId = null;
   capabilities = null;
   schemaVersion = null;
-  state = "stopped";
+  syncState = "stopped";
   pullRetryTimer = null;
   consecutivePullFailures = 0;
+  pendingPushCount = 0;
   lastError = null;
+  get state() {
+    return this.syncState;
+  }
+  setState(next) {
+    if (this.syncState === next) return;
+    this.syncState = next;
+    this.statusChanges.notify();
+  }
+  setError(failure) {
+    this.lastError = failure;
+    this.statusChanges.notify();
+  }
   /**
    * Connects to the server and starts pushing and pulling changes.
    */
   async start() {
     if (this.state === "running" || this.state === "starting") return;
-    this.state = "starting";
+    this.setState("starting");
     try {
       await this.verifyCapabilities();
       this.pull.stagedStream = this.capabilities?.includes(STAGED_STREAM_CAPABILITY) ?? false;
@@ -1192,10 +1286,10 @@ var SyncController = class {
       if (!this.resync.required) {
         await this.openPull();
       }
-      this.state = "running";
+      this.setState("running");
     } catch (err) {
       this.teardownStream();
-      this.state = "stopped";
+      this.setState("stopped");
       throw err;
     }
     this.push.start();
@@ -1210,7 +1304,7 @@ var SyncController = class {
   pause() {
     if (this.state !== "running") return;
     this.teardownStream();
-    this.state = "paused";
+    this.setState("paused");
     void this.pull.persist();
   }
   /**
@@ -1218,7 +1312,7 @@ var SyncController = class {
    */
   async resume() {
     if (this.state !== "paused") return;
-    this.state = "stopped";
+    this.setState("stopped");
     await this.start();
   }
   /**
@@ -1227,7 +1321,7 @@ var SyncController = class {
   async stop() {
     if (this.state === "stopped") return;
     this.teardownStream();
-    this.state = "stopped";
+    this.setState("stopped");
     await this.pull.persist();
   }
   /**
@@ -1236,20 +1330,29 @@ var SyncController = class {
    * @returns The device's state, cursors, pending push count, and last failure.
    */
   async status() {
-    const pendingPushCount = this.port ? await this.port.countOutboxPending(this.push.cursor) : 0;
+    await this.refreshOutboxCount();
+    return this.captureStatus();
+  }
+  captureStatus() {
     return {
       state: this.state,
       deviceId: this.deviceId,
       serverCapabilities: this.capabilities,
       schemaVersion: this.schemaVersion,
-      pendingPushCount,
+      pendingPushCount: this.pendingPushCount,
       lastPushedSeq: this.push.cursor,
       lastPulledSeq: this.pull.pullSeq,
-      pushCaughtUp: pendingPushCount === 0,
+      pushCaughtUp: this.pendingPushCount === 0,
       resyncRequired: this.resync.required,
       lastError: this.lastError
     };
   }
+  async refreshOutboxCount() {
+    const counted = this.port === null ? 0 : await this.port.countOutboxPending(this.push.cursor);
+    const changed = counted !== this.pendingPushCount;
+    this.pendingPushCount = counted;
+    return changed;
+  }
   /**
    * Pushes local changes now instead of waiting for the next interval.
    */
@@ -1283,16 +1386,17 @@ var SyncController = class {
     if (result.status === "resync-required") {
       this.markResyncRequired();
     } else if (result.status === "ahead") {
-      this.lastError = {
+      this.setError({
         code: "SCHEMA_AHEAD",
         message: `Device schema version ${result.schemaVersion} is ahead of server version ${result.serverVersion}`
-      };
+      });
     }
     return result.status;
   }
   markResyncRequired() {
     this.resync.markRequired();
     this.resync.schedule();
+    this.statusChanges.notify();
   }
   /**
    * Replaces the local database with a fresh copy from the server and resumes syncing from it.
@@ -1311,7 +1415,7 @@ var SyncController = class {
       throw new Error("Snapshot download requires a started sync controller");
     }
     this.teardownStream();
-    this.state = "snapshotting";
+    this.setState("snapshotting");
     try {
       await this.push.drainFully(port);
       await downloadDatabaseSnapshot(port, {
@@ -1325,22 +1429,22 @@ var SyncController = class {
       this.schemaVersion = await this.localSchemaVersion();
       await port.setResyncRequired(false);
       this.resync.recordSuccess();
-      this.lastError = null;
+      this.setError(null);
     } catch (err) {
       const failure = describeError(err);
-      this.lastError = failure;
+      this.setError(failure);
       this.resync.recordFailure();
       const databaseUsable = await this.snapshotGateOpen(port);
-      this.state = "stopped";
+      this.setState("stopped");
       try {
         await this.start();
       } catch {
-        this.state = "paused";
+        this.setState("paused");
       }
       this.resync.complete({ ok: false, error: failure, databaseUsable, retrying: this.resync.retryScheduled });
       throw err;
     }
-    this.state = "stopped";
+    this.setState("stopped");
     try {
       await this.start();
     } finally {
@@ -1361,7 +1465,7 @@ var SyncController = class {
     }
   }
   recordError(err) {
-    this.lastError = describeError(err);
+    this.setError(describeError(err));
   }
   handleApplyFailure(err) {
     this.recordError(err);
@@ -1407,7 +1511,7 @@ var SyncController = class {
     if (this.resync.required) return;
     if (status === "ahead") throw refusal;
     this.pull.teardown();
-    this.lastError = null;
+    this.setError(null);
     await this.pull.open(deviceId, this.schemaVersion ?? 0);
   }
   teardownStream() {
@@ -1420,9 +1524,5 @@ var SyncController = class {
     this.pull.teardown();
   }
 };
-function describeError(err) {
-  const code = err instanceof Error && "code" in err ? String(err.code) : "UNKNOWN_ERROR";
-  return { code, message: err instanceof Error ? err.message : String(err) };
-}
 
 export { FieldMergeResolver, LWWResolver, PrimaryWinsResolver, SirannonClient, SyncController, downloadDatabaseSnapshot, encodeSyncBatch, pushSyncBatch };

package/dist/client/topology.mjs

@@ -1,4 +1,4 @@
-import { DatabaseClient, toBaseUrl, createEndpointTransport, RemoteError, toServerBaseUrl, unrefTimer } from '../chunk-WJ67DTD6.mjs';
+import { DatabaseClient, toBaseUrl, createEndpointTransport, RemoteError, toServerBaseUrl, unrefTimer } from '../chunk-3UHAPQBW.mjs';
 
 // src/client/cluster-routing.ts
 function clusterRoutingFingerprint(state) {

package/dist/replication/index.d.ts

@@ -1,17 +1,17 @@
 export { F as FieldMergeResolver, L as LWWResolver, P as PrimaryWinsResolver } from '../primary-wins-B0np8JS3.js';
 import { H as HLCTimestamp, R as ReplicationBatch, C as ConflictResolver, A as ApplyResult, S as SyncTableManifest } from '../types-CjhxcjhA.js';
 export { a as ConflictContext, b as ConflictResolution, c as ReplicationChange } from '../types-CjhxcjhA.js';
+import { R as ReplicationStatusInfo } from '../server-options-BVAFmguz.js';
+import { r as ClusterReadEndpointInfo, C as ClusterStatusInfo, e as SQLiteConnection, T as Transaction } from '../types-CXoPBeDM.js';
+import { C as CoordinatorRuntimeStatus, g as ReplicationStatus, h as SyncPhase, I as InFlightBatch, P as PeerState, a as ForwardedTransactionResult, b as SyncBatch, c as SyncComplete, d as SyncAck, S as SyncRequest, i as ReplicationConfig, j as SyncState, k as ReplicationErrorEvent, R as ReplicationAck, l as Topology, f as TopologyRole } from '../types-DxoEm08T.js';
+export { F as ForwardedTransaction, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-DxoEm08T.js';
 import { c as ReplicationGroupState, e as CoordinatorWatchDisposer } from '../types-CMBcFPhb.js';
 export { A as AcquireControllerLeaseInput, a as AcquireControllerLeaseResult, h as AdmitNodeToInSyncSetInput, C as ClusterCoordinator, f as CompareAndAdvancePrimaryTermInput, g as CompareAndAdvancePrimaryTermResult, j as CoordinatorCompatibilityMetadata, k as CoordinatorLease, b as CoordinatorNodeSession, l as CoordinatorPrimary, P as PromoteEligibleReplicaInput, R as RegisterNodeSessionInput, d as ReplicationGroupWatcher, S as SetReplicationGroupStateInput, U as UpdateInSyncSetInput, i as UpdateNodeMaintenanceInput } from '../types-CMBcFPhb.js';
 import { EventEmitter } from 'node:events';
 import { C as ChangeTracker } from '../change-tracker-C2Z8UbI0.js';
 import { D as Database } from '../database-DvSvONb-.js';
-import { e as SQLiteConnection, T as Transaction } from '../types-CXoPBeDM.js';
 import { P as Params, Q as QueryOptions, E as ExecuteResult } from '../query-types-BvkzxKQv.js';
-import { g as SyncPhase, I as InFlightBatch, P as PeerState, a as ForwardedTransactionResult, b as SyncBatch, c as SyncComplete, d as SyncAck, S as SyncRequest, h as ReplicationConfig, i as SyncState, j as ReplicationStatus, k as ReplicationErrorEvent, R as ReplicationAck, l as Topology, f as TopologyRole } from '../types-DtUwSmAQ.js';
-export { F as ForwardedTransaction, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-DtUwSmAQ.js';
 import { S as SirannonError } from '../errors-Dei4GdBb.js';
-import '../server-options-BVAFmguz.js';
 import '../operation-registry-6qErmUT2.js';
 import '../types-BCejqzNA.js';
 
@@ -64,6 +64,53 @@ declare class HLC {
     static encode(wallMs: number, logical: number, nodeId: string): string;
 }
 
+/**
+ * What a node needs to know beyond its own engine state to describe its group.
+ *
+ * @public
+ */
+interface ClusterStatusOptions {
+    /** Identifier of the database the reported status describes. */
+    databaseId: string;
+    /** Address a client reaches each node on, keyed by node id. */
+    endpoints: Readonly<Record<string, string>>;
+}
+/**
+ * Turns one node's engine status into the figures its readiness endpoint reports.
+ *
+ * @param status - Status the replication engine reports for this node.
+ * @returns The replication figures, ready to return from `getReplicationStatus`.
+ *
+ * @public
+ */
+declare function toReplicationStatusInfo(status: ReplicationStatus): ReplicationStatusInfo;
+/**
+ * Turns one node's engine status into what `GET /db/{id}/cluster` reports about its group.
+ *
+ * @param status - Status the replication engine reports for this node.
+ * @param options - The database this status describes and the address of each node.
+ * @returns The group status, ready to return from `getClusterStatus`.
+ *
+ * @public
+ */
+declare function toClusterStatusInfo(status: ReplicationStatus, options: ClusterStatusOptions): ClusterStatusInfo;
+/**
+ * Lists every node a client can read from, with the read concerns each one serves.
+ *
+ * A node counts towards majority and is neither quarantined, being taken out of
+ * service, nor being rebuilt to appear at all. A node the group counts as in
+ * sync serves both `local` and `majority`; one that has fallen behind serves
+ * `local` alone, because the engine answers a `local` read without any in-sync
+ * check.
+ *
+ * @param coordinator - Group state this node last read from the coordinator.
+ * @param endpoints - Address a client reaches each node on, keyed by node id.
+ * @returns One entry per node a client can read from.
+ *
+ * @public
+ */
+declare function toClusterReadEndpoints(coordinator: CoordinatorRuntimeStatus, endpoints: Readonly<Record<string, string>>): ClusterReadEndpointInfo[];
+
 /**
  * Persistent change log that bridges CDC events and the replication protocol.
  *
@@ -668,4 +715,4 @@ declare class PrimaryReplicaTopology implements Topology {
     requiresConflictResolution(): boolean;
 }
 
-export { ApplyResult, AuthorityError, BatchValidationError, ConflictError, ConflictResolver, CoordinatorError, CoordinatorWatchDisposer, FailoverError, ForwardedTransactionResult, HLC, HLCTimestamp, NoSafePrimaryError, NodeDrainingError, NodeNotInSyncError, PeerState, PeerTracker, PrimaryReplicaTopology, ProtocolVersionMismatchError, ReadConcernError, ReplicationAck, ReplicationBatch, ReplicationConfig, ReplicationEngine, ReplicationError, ReplicationErrorEvent, ReplicationGroupState, ReplicationLog, ReplicationStatus, StalePrimaryError, SyncAck, SyncBatch, SyncComplete, SyncError, SyncPhase, SyncRequest, SyncState, SyncTableManifest, Topology, TopologyError, TopologyRole, TransportError, UnsafeRecoveryRequiredError, WriteConcernError, generateNodeId, validateNodeId };
+export { ApplyResult, AuthorityError, BatchValidationError, type ClusterStatusOptions, ConflictError, ConflictResolver, CoordinatorError, CoordinatorWatchDisposer, FailoverError, ForwardedTransactionResult, HLC, HLCTimestamp, NoSafePrimaryError, NodeDrainingError, NodeNotInSyncError, PeerState, PeerTracker, PrimaryReplicaTopology, ProtocolVersionMismatchError, ReadConcernError, ReplicationAck, ReplicationBatch, ReplicationConfig, ReplicationEngine, ReplicationError, ReplicationErrorEvent, ReplicationGroupState, ReplicationLog, ReplicationStatus, StalePrimaryError, SyncAck, SyncBatch, SyncComplete, SyncError, SyncPhase, SyncRequest, SyncState, SyncTableManifest, Topology, TopologyError, TopologyRole, TransportError, UnsafeRecoveryRequiredError, WriteConcernError, generateNodeId, toClusterReadEndpoints, toClusterStatusInfo, toReplicationStatusInfo, validateNodeId };

package/dist/replication/index.mjs

@@ -118,6 +118,50 @@ var PrimaryWinsResolver = class {
   }
 };
 
+// src/replication/cluster-status.ts
+function toReplicationStatusInfo(status) {
+  const coordinator = status.coordinator;
+  return {
+    role: status.role,
+    writeForwarding: true,
+    peers: status.peers.length,
+    localSeq: status.localSeq,
+    health: status.health,
+    replicationGroupId: coordinator?.groupId,
+    primaryTerm: coordinator?.primaryTerm,
+    currentPrimary: coordinator?.currentPrimary?.nodeId,
+    coordinator: coordinator && { connected: coordinator.connected, authority: coordinator.authority },
+    controller: coordinator && { state: coordinator.controllerState },
+    inSyncReplicas: coordinator?.inSyncNodeIds.filter((nodeId) => nodeId !== coordinator.currentPrimary?.nodeId),
+    laggingReplicas: coordinator?.votingDataBearingNodeIds.filter(
+      (nodeId) => !coordinator.inSyncNodeIds.includes(nodeId)
+    ),
+    syncState: status.syncState?.phase
+  };
+}
+function toClusterStatusInfo(status, options) {
+  const coordinator = status.coordinator;
+  return {
+    databaseId: options.databaseId,
+    replicationGroupId: coordinator?.groupId,
+    role: status.role,
+    currentPrimary: coordinator?.currentPrimary ? { ...coordinator.currentPrimary } : coordinator?.currentPrimary ?? null,
+    primaryTerm: coordinator?.primaryTerm,
+    readEndpoints: coordinator && toClusterReadEndpoints(coordinator, options.endpoints),
+    health: status.health.state,
+    healthReason: status.health.reason
+  };
+}
+function toClusterReadEndpoints(coordinator, endpoints) {
+  return coordinator.votingDataBearingNodeIds.filter(
+    (nodeId) => !coordinator.faultedNodeIds.includes(nodeId) && !coordinator.drainingNodeIds.includes(nodeId) && !coordinator.repairingNodeIds.includes(nodeId)
+  ).map((nodeId) => ({
+    nodeId,
+    endpoint: endpoints[nodeId] ?? "",
+    readConcerns: coordinator.inSyncNodeIds.includes(nodeId) ? ["local", "majority"] : ["local"]
+  }));
+}
+
 // src/replication/log/schema.ts
 var SchemaOps = class {
   constructor(conn, changesTable) {
@@ -3256,4 +3300,4 @@ var PrimaryReplicaTopology = class {
   }
 };
 
-export { FieldMergeResolver, PeerTracker, PrimaryReplicaTopology, PrimaryWinsResolver, ReplicationEngine, ReplicationLog, generateNodeId, validateNodeId };
+export { FieldMergeResolver, PeerTracker, PrimaryReplicaTopology, PrimaryWinsResolver, ReplicationEngine, ReplicationLog, generateNodeId, toClusterReadEndpoints, toClusterStatusInfo, toReplicationStatusInfo, validateNodeId };

package/dist/transport/grpc.d.ts

@@ -1,7 +1,7 @@
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 import { Client, ClientDuplexStream, CallOptions, Metadata, ServiceError, ClientUnaryCall, ChannelCredentials, ClientOptions, ServerDuplexStream, Server } from '@grpc/grpc-js';
 import { HealthImplementation } from 'grpc-health-check';
-import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, N as NodeInfo, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, e as ReplicationTransport, f as TopologyRole, T as TransportConfig } from '../types-DtUwSmAQ.js';
+import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, N as NodeInfo, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, e as ReplicationTransport, f as TopologyRole, T as TransportConfig } from '../types-DxoEm08T.js';
 import { R as ReplicationBatch } from '../types-CjhxcjhA.js';
 import '../change-tracker-C2Z8UbI0.js';
 import '../types-CXoPBeDM.js';

package/dist/transport/memory.d.ts

@@ -1,4 +1,4 @@
-import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-DtUwSmAQ.js';
+import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-DxoEm08T.js';
 import { R as ReplicationBatch } from '../types-CjhxcjhA.js';
 import '../change-tracker-C2Z8UbI0.js';
 import '../types-CXoPBeDM.js';

package/dist/{types-DtUwSmAQ.d.ts → types-DxoEm08T.d.ts}

@@ -496,4 +496,4 @@ interface ReplicationErrorEvent {
     recoverable: boolean;
 }
 
-export type { ForwardedTransaction as F, InFlightBatch as I, NodeInfo as N, PeerState as P, ReplicationAck as R, SyncRequest as S, TransportConfig as T, ForwardedTransactionResult as a, SyncBatch as b, SyncComplete as c, SyncAck as d, ReplicationTransport as e, TopologyRole as f, SyncPhase as g, ReplicationConfig as h, SyncState as i, ReplicationStatus as j, ReplicationErrorEvent as k, Topology as l };
+export type { CoordinatorRuntimeStatus as C, ForwardedTransaction as F, InFlightBatch as I, NodeInfo as N, PeerState as P, ReplicationAck as R, SyncRequest as S, TransportConfig as T, ForwardedTransactionResult as a, SyncBatch as b, SyncComplete as c, SyncAck as d, ReplicationTransport as e, TopologyRole as f, ReplicationStatus as g, SyncPhase as h, ReplicationConfig as i, SyncState as j, ReplicationErrorEvent as k, Topology as l };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@delali/sirannon-db",
   "type": "module",
-  "version": "0.2.3-next.26",
+  "version": "0.2.3-next.28",
   "description": "A production-grade library that turns SQLite databases into a networked data layer with real-time subscriptions.",
   "author": "Delali (https://sondelali.com)",
   "license": "Apache-2.0",