@abloatai/ablo 0.26.0 → 0.27.0

package/dist/sync/ConnectionManager.d.ts

@@ -1,24 +1,18 @@
 /**
- * ConnectionManager — single source of truth for the sync engine's
- * connection lifecycle. Absorbs the FSM every SDK consumer used to
- * rebuild by hand (apps/web's `ConnectionStore` was the reference
- * implementation — 605 LOC of FSM + watchdog + backoff).
+ * Owns the sync engine's connection lifecycle: the state machine that carries a
+ * client from a healthy connection, through a dropout, and back to live. It
+ * watches the browser's online/offline and visibility events, probes real
+ * connectivity and session validity with {@link probeNetwork}, applies retry
+ * backoff with a ceiling and jitter, and runs a watchdog for the cases where
+ * the browser never fires an event (VPN flips, captive portals). When it
+ * decides to recover, it drives the reconnect sequence — bootstrap, then
+ * WebSocket connect — through the {@link ConnectionCallbacks.onReconnect}
+ * callback and reacts to the outcome.
  *
- * What it owns:
- *  - Browser online/offline + visibility events
- *  - Network probe orchestration (via `probeNetwork`)
- *  - Session-validity checks (HEAD /api/auth/check)
- *  - Retry backoff with ceiling, jitter, and offline-aware parking
- *  - Watchdog for browser events that never fire (VPN, captive portal)
- *  - The reconnect → bootstrap → WebSocket connect sequence
- *
- * What it DOES NOT own:
- *  - The actual bootstrap / IndexedDB / ObjectPool work — that lives in
- *    `BaseSyncedStore.performReconnect()`. This class calls it via the
- *    `onReconnect` callback and reacts to the outcome.
- *
- * Designed to be embedded by `BaseSyncedStore`: one instance per store,
- * started on first successful connect, disposed on teardown.
+ * It deliberately does not perform the bootstrap, local-storage, or object-pool
+ * work itself; that lives in the embedding store, which the manager reaches
+ * only through its callbacks. One manager is created per store, started on the
+ * first successful connect and disposed on teardown.
  *
  *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
  *        │                              │                  │
@@ -29,20 +23,15 @@
  *        ▼
  *   WAITING_FOR_NETWORK
  *
- * Includes three fixes over the original app-side FSM:
- *   1. `backoff` accepts `NETWORK_ONLINE` / `TAB_VISIBLE` — jumps to
- *      probing immediately when the network comes back, without
- *      waiting for the backoff timer to elapse.
- *   2. `scheduleBackoff` parks in `waiting_for_network` (resetting
- *      `attempt`) when `navigator.onLine === false` at max retries,
- *      instead of hard-reloading an already-offline browser.
- *   3. A socket drop (`WS_DISCONNECTED`, typically code 1006) goes
- *      STRAIGHT to `probing_network`, not the passive `offline` state.
- *      1006 is browser-local and carries no connectivity signal, so on a
- *      healthy machine no `online`/`offline` event ever fires — parking in
- *      `offline` stranded recovery until the 30s watchdog, long enough for
- *      queued commits to roll back. Only a genuine OS-level `NETWORK_LOST`
- *      parks in `offline` and waits for the `online` event.
+ * Three behaviors are worth calling out. A network return or tab focus during a
+ * backoff delay jumps straight to probing instead of waiting out the full
+ * interval. Reaching the retry ceiling while the browser reports offline parks
+ * in `waiting_for_network` rather than hard-reloading a browser that has no
+ * network. And a socket drop (close code 1006) goes straight to probing rather
+ * than the passive `offline` state — 1006 is generated locally and carries no
+ * connectivity signal, so on a healthy machine no online/offline event ever
+ * fires; only a genuine operating-system network loss parks in `offline` to
+ * wait for the `online` event.
  */
 import { type ProbeResult } from './NetworkProbe.js';
 import type { AuthTokenGetter } from '../auth/credentialSource.js';
@@ -93,17 +82,18 @@ export interface ConnectionCallbacks {
     /** Run bootstrap + WebSocket reconnect. Returns the outcome. */
     onReconnect: () => Promise<'success' | 'session_error' | 'network_error'>;
     /**
-     * Re-mint the short-lived access credential (the Stripe-style `ek_`/`rk_`)
-     * and push it into the credential source, then report the outcome. Invoked
-     * on `refreshing_credential` — i.e. when a probe found the access key stale
-     * (`PROBE_CREDENTIAL_STALE`). Mirrors the `getToken` contract:
-     *   - `'refreshed'`     → a fresh credential is in place; re-probe & reconnect.
-     *   - `'session_error'` → the LONG-LIVED login is gone (mint returned null →
-     *                          401/403); terminal → sign out.
-     *   - `'network_error'` → couldn't reach the mint endpoint (offline/5xx/throw);
-     *                          transient → back off and retry, never sign out.
-     * Optional: a deployment with no re-mint path (e.g. a static `apiKey`) omits
-     * it, and the FSM falls back to a plain re-probe.
+     * Re-mints the short-lived access credential (the `ek_`/`rk_`) and pushes it
+     * into the credential source, then reports the outcome. Invoked in the
+     * `refreshing_credential` state — that is, when a probe found the access key
+     * stale (`PROBE_CREDENTIAL_STALE`). The three outcomes map onto recovery:
+     *   - `'refreshed'`     → a fresh credential is in place; re-probe and reconnect.
+     *   - `'session_error'` → the long-lived login itself is gone (the mint
+     *                          returned null, a 401/403); terminal, so sign out.
+     *   - `'network_error'` → the mint endpoint was unreachable (offline, 5xx, or
+     *                          a throw); transient, so back off and retry rather
+     *                          than sign out.
+     * Optional: a deployment with no re-mint path (for example a static `apiKey`)
+     * omits it, and the state machine falls back to a plain re-probe.
      */
     onRefreshCredential?: () => Promise<'refreshed' | 'session_error' | 'network_error'>;
     /** Called when the session is confirmed expired — route to signin. */
@@ -111,12 +101,11 @@ export interface ConnectionCallbacks {
     /** Called to tear down the WebSocket when entering a dead state. */
     onDisconnectWebSocket: () => void;
     /**
-     * Fired on every FSM state transition. Lets the embedding store
-     * mirror recovery progress into its visible `syncStatus` so the UI
-     * can show "Reconnecting…" instead of a sticky "offline" while the
-     * FSM cycles through `probing_network` → `reconnecting` → `backoff`.
-     * Optional — omitting it preserves the previous behavior where the
-     * FSM was opaque to the UI.
+     * Fires on every state transition. It lets the embedding store mirror
+     * recovery progress into its visible `syncStatus`, so the UI can show
+     * "Reconnecting…" instead of a sticky "offline" while the machine cycles
+     * through `probing_network` → `reconnecting` → `backoff`. Optional; when
+     * omitted, the state machine is simply opaque to the UI.
      */
     onStateChange?: (next: ConnectionState, prev: ConnectionState) => void;
 }

package/dist/sync/ConnectionManager.js

@@ -1,24 +1,18 @@
 /**
- * ConnectionManager — single source of truth for the sync engine's
- * connection lifecycle. Absorbs the FSM every SDK consumer used to
- * rebuild by hand (apps/web's `ConnectionStore` was the reference
- * implementation — 605 LOC of FSM + watchdog + backoff).
+ * Owns the sync engine's connection lifecycle: the state machine that carries a
+ * client from a healthy connection, through a dropout, and back to live. It
+ * watches the browser's online/offline and visibility events, probes real
+ * connectivity and session validity with {@link probeNetwork}, applies retry
+ * backoff with a ceiling and jitter, and runs a watchdog for the cases where
+ * the browser never fires an event (VPN flips, captive portals). When it
+ * decides to recover, it drives the reconnect sequence — bootstrap, then
+ * WebSocket connect — through the {@link ConnectionCallbacks.onReconnect}
+ * callback and reacts to the outcome.
  *
- * What it owns:
- *  - Browser online/offline + visibility events
- *  - Network probe orchestration (via `probeNetwork`)
- *  - Session-validity checks (HEAD /api/auth/check)
- *  - Retry backoff with ceiling, jitter, and offline-aware parking
- *  - Watchdog for browser events that never fire (VPN, captive portal)
- *  - The reconnect → bootstrap → WebSocket connect sequence
- *
- * What it DOES NOT own:
- *  - The actual bootstrap / IndexedDB / ObjectPool work — that lives in
- *    `BaseSyncedStore.performReconnect()`. This class calls it via the
- *    `onReconnect` callback and reacts to the outcome.
- *
- * Designed to be embedded by `BaseSyncedStore`: one instance per store,
- * started on first successful connect, disposed on teardown.
+ * It deliberately does not perform the bootstrap, local-storage, or object-pool
+ * work itself; that lives in the embedding store, which the manager reaches
+ * only through its callbacks. One manager is created per store, started on the
+ * first successful connect and disposed on teardown.
  *
  *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
  *        │                              │                  │
@@ -29,20 +23,15 @@
  *        ▼
  *   WAITING_FOR_NETWORK
  *
- * Includes three fixes over the original app-side FSM:
- *   1. `backoff` accepts `NETWORK_ONLINE` / `TAB_VISIBLE` — jumps to
- *      probing immediately when the network comes back, without
- *      waiting for the backoff timer to elapse.
- *   2. `scheduleBackoff` parks in `waiting_for_network` (resetting
- *      `attempt`) when `navigator.onLine === false` at max retries,
- *      instead of hard-reloading an already-offline browser.
- *   3. A socket drop (`WS_DISCONNECTED`, typically code 1006) goes
- *      STRAIGHT to `probing_network`, not the passive `offline` state.
- *      1006 is browser-local and carries no connectivity signal, so on a
- *      healthy machine no `online`/`offline` event ever fires — parking in
- *      `offline` stranded recovery until the 30s watchdog, long enough for
- *      queued commits to roll back. Only a genuine OS-level `NETWORK_LOST`
- *      parks in `offline` and waits for the `online` event.
+ * Three behaviors are worth calling out. A network return or tab focus during a
+ * backoff delay jumps straight to probing instead of waiting out the full
+ * interval. Reaching the retry ceiling while the browser reports offline parks
+ * in `waiting_for_network` rather than hard-reloading a browser that has no
+ * network. And a socket drop (close code 1006) goes straight to probing rather
+ * than the passive `offline` state — 1006 is generated locally and carries no
+ * connectivity signal, so on a healthy machine no online/offline event ever
+ * fires; only a genuine operating-system network loss parks in `offline` to
+ * wait for the `online` event.
  */
 import { makeAutoObservable, runInAction } from 'mobx';
 import { getContext } from '../context.js';
@@ -158,13 +147,13 @@ export class ConnectionManager {
                         // work.
                         return 'offline';
                     case 'WS_DISCONNECTED':
-                        // The socket died (typically code 1006) but the OS network is
-                        // almost certainly fine — 1006 is generated locally when the TCP
-                        // conn vanishes and carries NO connectivity signal, so the browser
-                        // fires no online/offline event. Probe IMMEDIATELY rather than
-                        // landing in the passive `offline` dead-end (which only escaped via
-                        // the 30s watchdog, long after queued commits rolled back). The
-                        // probe fast-fails if we genuinely ARE offline → waiting_for_network.
+                        // The socket died (typically code 1006) but the operating-system
+                        // network is almost certainly fine — 1006 is generated locally when
+                        // the TCP connection vanishes and carries no connectivity signal, so
+                        // the browser fires no online/offline event. Probe immediately rather
+                        // than landing in the passive `offline` dead-end (which only escaped
+                        // via the 30s watchdog, long after queued commits rolled back). The
+                        // probe fast-fails if we genuinely are offline → waiting_for_network.
                         return 'probing_network';
                     case 'WS_SESSION_ERROR':
                     case 'BOOTSTRAP_FAILED_SESSION':
@@ -233,15 +222,15 @@ export class ConnectionManager {
                         return null;
                 }
             case 'refreshing_credential':
-                // Re-minting the short-lived access key (the Stripe-style `ek_`/`rk_`).
-                // The login is presumed valid; this is NOT a sign-out state.
+                // Re-minting the short-lived access key (the `ek_`/`rk_`). The login is
+                // presumed valid; this is not a sign-out state.
                 switch (event.type) {
                     case 'CREDENTIAL_REFRESHED':
                         // Fresh key in hand — re-probe so we reconnect with it.
                         return 'probing_network';
                     case 'BOOTSTRAP_FAILED_SESSION':
                         // The re-mint hit a genuine 401/403: the long-lived login itself is
-                        // gone. THIS is the only path from here to sign-out.
+                        // gone. This is the only path from here to sign-out.
                         return 'session_expired';
                     case 'RECONNECT_FAILED':
                         // Couldn't reach the mint endpoint (offline/5xx/throw) — transient.
@@ -336,15 +325,15 @@ export class ConnectionManager {
                 this.callbacks?.onDisconnectWebSocket();
                 break;
             case 'probing_network':
-                // A socket drop (`WS_DISCONNECTED`) now lands here directly so recovery
-                // starts immediately. Tear the dead socket down FIRST — this is what
+                // A socket drop (`WS_DISCONNECTED`) lands here directly so recovery
+                // starts immediately. Tear the dead socket down first — that is what
                 // sets SyncWebSocket's `isManualClose=true` and suppresses its own
-                // scheduleReconnect, keeping the FSM the single reconnect authority on
-                // the human path. The teardown runs synchronously inside the
-                // `disconnected` emit, before `SyncWebSocket.onclose` checks the flag,
-                // so the timing matches the previous `offline`-entry teardown. We gate
-                // on the drop event specifically: the other paths into `probing_network`
-                // (TAB_VISIBLE re-validation, handshake retry, backoff elapse) must NOT
+                // reconnect, keeping this machine the single reconnect authority on the
+                // human path. The teardown runs synchronously inside the `disconnected`
+                // emit, before `SyncWebSocket.onclose` checks the flag, so the timing
+                // matches the previous `offline`-entry teardown. We gate on the drop
+                // event specifically: the other paths into `probing_network`
+                // (tab-focus re-validation, handshake retry, backoff elapse) must not
                 // tear down a socket that may still be live.
                 if (event.type === 'WS_DISCONNECTED') {
                     this.callbacks?.onDisconnectWebSocket();
@@ -364,11 +353,12 @@ export class ConnectionManager {
                 this.scheduleBackoff();
                 break;
             case 'auth_blocked':
-                // Stop — reachable but the credential was rejected (e.g.
-                // api_key_required / jwt_issuer_untrusted from the data plane). Neither
-                // reconnecting nor re-auth fixes it. Drop the socket and wait for a
-                // manual retry / re-probe. Crucially NOT onSessionExpired (no sign-out)
-                // and NOT a reconnect — that's the whole point of this state.
+                // Stop here — the server is reachable but rejected the credential (for
+                // example api_key_required or jwt_issuer_untrusted from the data plane).
+                // Neither reconnecting nor re-authenticating fixes it. Drop the socket
+                // and wait for a manual retry or a re-probe. This deliberately does not
+                // call onSessionExpired (no sign-out) and does not reconnect — that is
+                // the whole point of the state.
                 this.clearBackoffTimer();
                 this.callbacks?.onDisconnectWebSocket();
                 getContext().observability.breadcrumb('Auth blocked — reachable but credential rejected; not reconnecting or signing out', 'sync.offline', 'error');
@@ -602,16 +592,15 @@ export class ConnectionManager {
         this.watchdogTimer = setInterval(() => {
             if (this.disposed)
                 return;
-            // "Stuck" = parked in a non-active recovery state (offline,
-            // waiting_for_network, backoff). We deliberately do NOT gate on
-            // `navigator.onLine === true` here: per MDN, `navigator.onLine`
-            // is only reliable when it returns false ("definitely offline"),
-            // and even that lies after laptop wake / VPN flips. Gating the
-            // watchdog on `onLine` was the actual "offline forever" bug —
-            // when the browser briefly reported offline and never re-fired
-            // the `online` event, the FSM had no escape from `'offline'`.
-            // The probe itself fast-fails when truly offline (NetworkProbe.ts),
-            // so an unconditional retry costs nothing in the genuine case.
+            // "Stuck" means parked in a non-active recovery state (offline,
+            // waiting_for_network, backoff). This deliberately does not gate on
+            // `navigator.onLine === true`: per MDN, `navigator.onLine` is only
+            // reliable when it returns false ("definitely offline"), and even that
+            // lies after laptop wake or VPN flips. Gating the watchdog on `onLine`
+            // was what stranded the machine in `offline` forever — when the browser
+            // briefly reported offline and never re-fired the `online` event, there
+            // was no escape. The probe itself fast-fails when truly offline, so an
+            // unconditional retry costs nothing in the genuine case.
             const isStuck = this.state !== 'connected' &&
                 this.state !== 'session_expired' &&
                 this.state !== 'probing_network' &&

package/dist/sync/NetworkProbe.d.ts

@@ -1,36 +1,33 @@
 /**
- * NetworkProbe - Reliable network + session connectivity detection
+ * Detects real network and session connectivity for the sync engine. It exists
+ * because `navigator.onLine` is unreliable: it reports true whenever the device
+ * has a local network connection, even with no route to the internet, and after
+ * sleep/wake it can report true before Wi-Fi or DNS are working again.
  *
- * navigator.onLine is unreliable: it reports true whenever the device has a LAN
- * connection, even without actual internet access (MDN docs confirm this).
- * After laptop sleep/wake, it may report true before WiFi/DNS are functional.
- *
- * This module provides an authenticated probe against the sync server to verify
- * real connectivity + credential validity in a single round-trip. The probe
- * hits `/api/auth/check`, which runs the SAME auth middleware as the WebSocket
- * upgrade path, and classifies the response into a single {@link ProbeOutcome}
- * via the closed recovery taxonomy ({@link classifyRecovery}):
+ * The probe makes one authenticated request to the sync server's
+ * `/api/auth/check` endpoint — which runs the same auth middleware as the
+ * WebSocket upgrade — and classifies the response into a single
+ * {@link ProbeOutcome} through the recovery taxonomy ({@link classifyRecovery}):
  *   204 No Content                         → `reachable`        (credential valid)
- *   401 `apikey_expired` (ephemeral key)   → `credential_stale` (re-mint & retry, NO sign-out)
+ *   401 `apikey_expired` (ephemeral key)   → `credential_stale` (re-mint and retry, no sign-out)
  *   401 `session_expired` / bare 401       → `session_expired`  (sign out)
- *   401/403 credential-type/config/perm    → `auth_blocked`     (stop, no loop, no sign-out)
- *   network fail / offline                 → `unreachable`
+ *   401/403 credential-type/config/perm    → `auth_blocked`     (stop; no loop, no sign-out)
+ *   network failure / offline              → `unreachable`
  *
- * This closes a real gap: the browser's WebSocket API hides HTTP status from
- * the handshake, so a 401 on the WS upgrade surfaces only as `close code
- * 1006`. Without this HTTP probe, the client cannot distinguish auth failure
- * from a network blip and loops reconnecting forever instead of redirecting
- * the user to sign-in.
+ * This closes a real gap. The browser's WebSocket API hides the HTTP status of
+ * a failed handshake, so a 401 on the upgrade surfaces only as close code 1006.
+ * Without this HTTP probe, the client cannot tell an auth failure from a network
+ * blip, and loops reconnecting forever instead of sending the user to sign in.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
  */
 import { z } from 'zod';
 import { type AuthTokenGetter } from '../auth/credentialSource.js';
 /**
- * The closed set of probe outcomes — one value carrying both reachability and
- * credential disposition, so the {@link ConnectionManager} branches on a single
- * exhaustive discriminant instead of reconstructing claim from a trio of
- * booleans. Mirrors the {@link RecoveryClass} taxonomy at the connectivity tier.
+ * The complete set of probe outcomes. Each value carries both reachability and
+ * credential state, so {@link ConnectionManager} can branch on one exhaustive
+ * discriminant instead of piecing the situation together from several booleans.
+ * It mirrors the {@link RecoveryClass} taxonomy at the connectivity layer.
  */
 export declare const PROBE_OUTCOMES: readonly ["reachable", "unreachable", "session_expired", "credential_stale", "auth_blocked"];
 /** Zod enum derived from {@link PROBE_OUTCOMES}. */
@@ -74,13 +71,11 @@ export interface NetworkProbeOptions {
     authToken?: string | null;
 }
 /**
- * Probe the sync engine server with a lightweight HEAD request.
- *
- * Returns reachability AND session status in a single call, so the
- * ConnectionStore can make the right state transition without guessing.
+ * Probes the sync server with a lightweight HEAD request, returning both
+ * reachability and session status in a single call so {@link ConnectionManager}
+ * can pick the right state transition without guessing.
  *
- * @param input The sync-server base URL (HTTP or WS scheme accepted), or an
- *              options bag with `authToken`. A bare string is still accepted
- *              for backwards compatibility.
+ * @param input The sync-server base URL (an HTTP or WS scheme is accepted), or
+ *              an options bag. A bare string is also accepted.
  */
 export declare function probeNetwork(input?: string | NetworkProbeOptions): Promise<ProbeResult>;

package/dist/sync/NetworkProbe.js

@@ -1,26 +1,23 @@
 /**
- * NetworkProbe - Reliable network + session connectivity detection
+ * Detects real network and session connectivity for the sync engine. It exists
+ * because `navigator.onLine` is unreliable: it reports true whenever the device
+ * has a local network connection, even with no route to the internet, and after
+ * sleep/wake it can report true before Wi-Fi or DNS are working again.
  *
- * navigator.onLine is unreliable: it reports true whenever the device has a LAN
- * connection, even without actual internet access (MDN docs confirm this).
- * After laptop sleep/wake, it may report true before WiFi/DNS are functional.
- *
- * This module provides an authenticated probe against the sync server to verify
- * real connectivity + credential validity in a single round-trip. The probe
- * hits `/api/auth/check`, which runs the SAME auth middleware as the WebSocket
- * upgrade path, and classifies the response into a single {@link ProbeOutcome}
- * via the closed recovery taxonomy ({@link classifyRecovery}):
+ * The probe makes one authenticated request to the sync server's
+ * `/api/auth/check` endpoint — which runs the same auth middleware as the
+ * WebSocket upgrade — and classifies the response into a single
+ * {@link ProbeOutcome} through the recovery taxonomy ({@link classifyRecovery}):
  *   204 No Content                         → `reachable`        (credential valid)
- *   401 `apikey_expired` (ephemeral key)   → `credential_stale` (re-mint & retry, NO sign-out)
+ *   401 `apikey_expired` (ephemeral key)   → `credential_stale` (re-mint and retry, no sign-out)
  *   401 `session_expired` / bare 401       → `session_expired`  (sign out)
- *   401/403 credential-type/config/perm    → `auth_blocked`     (stop, no loop, no sign-out)
- *   network fail / offline                 → `unreachable`
+ *   401/403 credential-type/config/perm    → `auth_blocked`     (stop; no loop, no sign-out)
+ *   network failure / offline              → `unreachable`
  *
- * This closes a real gap: the browser's WebSocket API hides HTTP status from
- * the handshake, so a 401 on the WS upgrade surfaces only as `close code
- * 1006`. Without this HTTP probe, the client cannot distinguish auth failure
- * from a network blip and loops reconnecting forever instead of redirecting
- * the user to sign-in.
+ * This closes a real gap. The browser's WebSocket API hides the HTTP status of
+ * a failed handshake, so a 401 on the upgrade surfaces only as close code 1006.
+ * Without this HTTP probe, the client cannot tell an auth failure from a network
+ * blip, and loops reconnecting forever instead of sending the user to sign in.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
  */
@@ -30,24 +27,24 @@ import { classifyRecovery } from '../errors.js';
 import { withAuthHeaders } from '../auth/credentialSource.js';
 import { ABLO_DEFAULT_BASE_URL } from '../client/hostedEndpoints.js';
 /**
- * The closed set of probe outcomes — one value carrying both reachability and
- * credential disposition, so the {@link ConnectionManager} branches on a single
- * exhaustive discriminant instead of reconstructing claim from a trio of
- * booleans. Mirrors the {@link RecoveryClass} taxonomy at the connectivity tier.
+ * The complete set of probe outcomes. Each value carries both reachability and
+ * credential state, so {@link ConnectionManager} can branch on one exhaustive
+ * discriminant instead of piecing the situation together from several booleans.
+ * It mirrors the {@link RecoveryClass} taxonomy at the connectivity layer.
  */
 export const PROBE_OUTCOMES = [
     /** Server reachable and the access credential is currently valid. */
     'reachable',
-    /** Could not reach the server (offline / DNS / TLS / timeout). */
+    /** Could not reach the server (offline, DNS, TLS, or timeout). */
     'unreachable',
-    /** Reachable, but the long-lived login is gone → terminal, sign out. */
+    /** Reachable, but the long-lived login is gone. Terminal: sign out. */
     'session_expired',
-    /** Reachable, but the ephemeral access key (`ek_`/`rk_`) expired → silently
-     *  re-mint a fresh key from the still-valid login and retry. NOT a sign-out. */
+    /** Reachable, but the ephemeral access key (`ek_`/`rk_`) expired. Silently
+     *  re-mint a fresh key from the still-valid login and retry; not a sign-out. */
     'credential_stale',
-    /** Reachable, but the credential TYPE/config was rejected (wrong key kind,
-     *  untrusted issuer, no org, a 403) → stop; neither reconnecting nor re-auth
-     *  helps. Distinct from a sign-out. */
+    /** Reachable, but the credential's type or configuration was rejected (wrong
+     *  key kind, untrusted issuer, no organization, or a 403). Stop: neither
+     *  reconnecting nor re-authenticating helps. Distinct from a sign-out. */
     'auth_blocked',
 ];
 /** Zod enum derived from {@link PROBE_OUTCOMES}. */
@@ -62,13 +59,11 @@ const PROBE_TIMEOUT_MS = 4000;
 /**
  * Derive the probe URL from a sync-server base URL. Accepts `ws://`,
  * `wss://`, `http://`, `https://`, or a bare host — mirrors the
- * normalisation in `BootstrapHelper` / `createSyncEngine`.
+ * normalisation in `BootstrapFetcher` / `createSyncEngine`.
  */
 function resolveProbeUrl(baseUrl) {
     // No explicit baseUrl → probe the canonical hosted endpoint, matching the
-    // `Ablo()` default. (This used to fall back to the REMOVED Go engine's
-    // `NEXT_PUBLIC_GO_SERVER_URL` and then `http://localhost:8080`, so a probe
-    // without a baseUrl reported a healthy production deployment as offline.)
+    // `Ablo()` default.
     const resolved = baseUrl ?? ABLO_DEFAULT_BASE_URL;
     // Normalize ws → http so fetch() accepts the URL. Strip any trailing slash
     // so we don't produce `//api/auth/check`.
@@ -76,25 +71,23 @@ function resolveProbeUrl(baseUrl) {
     return `${httpBase}/api/auth/check`;
 }
 /**
- * Probe the sync engine server with a lightweight HEAD request.
- *
- * Returns reachability AND session status in a single call, so the
- * ConnectionStore can make the right state transition without guessing.
+ * Probes the sync server with a lightweight HEAD request, returning both
+ * reachability and session status in a single call so {@link ConnectionManager}
+ * can pick the right state transition without guessing.
  *
- * @param input The sync-server base URL (HTTP or WS scheme accepted), or an
- *              options bag with `authToken`. A bare string is still accepted
- *              for backwards compatibility.
+ * @param input The sync-server base URL (an HTTP or WS scheme is accepted), or
+ *              an options bag. A bare string is also accepted.
  */
 export async function probeNetwork(input) {
     const baseUrl = typeof input === 'string' ? input : input?.baseUrl;
     const getAuthToken = typeof input === 'string' ? undefined : input?.getAuthToken;
     const authToken = typeof input === 'string' ? undefined : input?.authToken;
     const url = resolveProbeUrl(baseUrl);
-    // Fast-fail: if navigator.onLine is false, skip the probe entirely.
-    // This is the ONE case where navigator.onLine is reliable (MDN: "false
-    // means definitely offline"). Use `=== false` rather than `!onLine`
-    // because Node 22+ exposes `navigator` with `onLine === undefined`,
-    // and `!undefined === true` would short-circuit the probe server-side.
+    // Fast-fail: if navigator.onLine is false, skip the probe entirely. This is
+    // the one case where navigator.onLine is reliable (MDN: "false means
+    // definitely offline"). Use `=== false` rather than `!onLine` because Node
+    // 22+ exposes `navigator` with `onLine === undefined`, and `!undefined` is
+    // true, which would short-circuit the probe server-side.
     if (typeof navigator !== 'undefined' && navigator.onLine === false) {
         return { outcome: 'unreachable', latencyMs: null };
     }
@@ -110,13 +103,13 @@ export async function probeNetwork(input) {
             headers,
         });
         const latencyMs = Math.round(performance.now() - start);
-        // The probe is a HEAD (no body), but the sync-server sets `X-Auth-Failure:
-        // <code>` on every auth rejection. Route the code through the closed
-        // recovery taxonomy so each failure mode gets its correct outcome — the
-        // whole reason this taxonomy exists: an expired ephemeral key
-        // (`access_credential_expiry`) must re-mint, NOT sign the user out the way
-        // a genuine login expiry (`session_expiry`) does, and NOT wedge the way a
-        // credential-type/config rejection (`auth_blocked`) does.
+        // The probe is a HEAD request (no body), but the server sets
+        // `X-Auth-Failure: <code>` on every auth rejection. Route the code through
+        // the recovery taxonomy so each failure mode gets its correct outcome. That
+        // distinction is the whole point: an expired ephemeral key
+        // (`access_credential_expiry`) must re-mint, not sign the user out the way a
+        // genuine login expiry (`session_expiry`) does, and not wedge the way a
+        // credential type or configuration rejection (`auth_blocked`) does.
         const authFailure = response.headers.get('x-auth-failure');
         if (authFailure) {
             const recovery = classifyRecovery(authFailure);
@@ -138,10 +131,11 @@ export async function probeNetwork(input) {
                 case 'auth_blocked':
                 case 'permission':
                 case 'none':
-                    // A non-expiry auth rejection — wrong credential type/config, a 403,
-                    // or an auth-tagged code this SDK doesn't recognise. Re-auth re-mints
-                    // the same rejected credential and retrying won't help, so STOP
-                    // rather than reconnect-loop or sign the user out.
+                    // A non-expiry auth rejection — wrong credential type or config, a
+                    // 403, or an auth-tagged code this SDK does not recognise.
+                    // Re-authenticating re-mints the same rejected credential and
+                    // retrying will not help, so stop rather than reconnect-loop or sign
+                    // the user out.
                     getContext().logger.debug('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
                         status: response.status,
                         code: authFailure,
@@ -160,20 +154,20 @@ export async function probeNetwork(input) {
             }
         }
         else if (response.status === 401) {
-            // Bare 401 with no READABLE structured code. This is AMBIGUOUS and must
-            // NOT sign the user out on its own — two common causes are both
+            // Bare 401 with no readable structured code. This is ambiguous and must
+            // not sign the user out on its own — two common causes are both
             // recoverable, and only one is a real logout:
-            //   1. The server DID send `X-Auth-Failure: apikey_expired`, but it's a
-            //      custom header on a cross-origin response and the server didn't list
-            //      it in `Access-Control-Expose-Headers`, so the browser stripped it to
-            //      null (the network-change logout bug). The access key just needs a
-            //      re-mint.
-            //   2. A genuinely expired access key on a non-Ablo proxy / cookie path.
-            // So route to `credential_stale`: the FSM attempts a re-mint, and the ONLY
-            // way to actually sign out is the re-mint resolving `null` (login truly
-            // gone). If no refresher is wired, the bounded attempt counter falls
-            // through to `auth_blocked` (stop) — still never a spurious logout. This
-            // upholds the invariant: null is the only terminal path, never a bare 401.
+            //   1. The server did send `X-Auth-Failure: apikey_expired`, but it is a
+            //      custom header on a cross-origin response the server did not list in
+            //      `Access-Control-Expose-Headers`, so the browser stripped it to
+            //      null. The access key just needs a re-mint.
+            //   2. A genuinely expired access key on a non-Ablo proxy or cookie path.
+            // So route to `credential_stale`: the state machine attempts a re-mint,
+            // and the only way to actually sign out is that re-mint resolving `null`
+            // (the login is truly gone). If no refresher is wired, the bounded attempt
+            // counter falls through to `auth_blocked` (stop) — still never a spurious
+            // logout. The invariant holds: null is the only terminal path, never a
+            // bare 401.
             getContext().logger.info('[NetworkProbe] Server reachable, bare 401 — re-mint (not sign-out)', {
                 latencyMs,
             });