@abloatai/ablo 0.26.0 → 0.28.0

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,
             });

package/dist/sync/{HydrationCoordinator.d.ts → OnDemandLoader.d.ts}

@@ -1,33 +1,34 @@
 /**
- * HydrationCoordinator — the lazy-load lane of the sync engine.
+ * Loads model rows on demand — the lazy-load path of the sync engine. When
+ * something needs an entity that the initial bootstrap did not fetch,
+ * {@link OnDemandLoader.fetch | fetch} finds it and populates the
+ * in-memory {@link InstanceCache} so the rest of the engine can read it normally.
  *
- * Bridges "I need this entity but bootstrap didn't fetch it" → pool
- * hydration. Replaces the per-app loader files (documentLoaders,
- * slideLayerLoaders, layoutLoaders, ensureVaultFiles, ensureDataroomFiles)
- * with one engine-level path.
+ * A fetch resolves against three tiers in order, stopping at the first that can
+ * answer:
+ *   1. The object pool — if rows already in memory match the query, return them.
+ *   2. Local storage — if matching rows exist there, hydrate the pool and return.
+ *   3. The network — post the query to `/sync/query`, then hydrate both the pool
+ *      and local storage.
  *
- * Lookup order on `fetch(modelName, where)`:
- *   1. ObjectPool — if rows already match the where, return them (cheap).
- *   2. IndexedDB — if matching rows exist locally, hydrate pool, return.
- *   3. Network — `postQuery` against `/sync/query`, hydrate pool + IDB.
+ * Concurrent calls with the same query key share one in-flight promise, so a
+ * burst of components mounting and asking for the same data on first paint
+ * triggers a single fetch rather than one each.
  *
- * Single-flight dedup: concurrent calls with the same query key share
- * one in-flight promise. Prevents the loader anti-pattern where N
- * components mount and fire N identical hydrations on first paint.
- *
- * The coordinator does NOT replace bootstrap (full sync of `instant`
- * models) or live deltas (WS push). It only fills the gap for `lazy`
- * models accessed by id/where after the engine is ready.
+ * The coordinator does not replace the bootstrap (which fully syncs instantly
+ * loaded models) or the live delta stream (pushed over the WebSocket). It only
+ * fills the gap for lazily loaded models read by id or filter after the engine
+ * is ready.
  */
-import type { ObjectPool } from '../ObjectPool.js';
+import type { InstanceCache } from '../InstanceCache.js';
 import type { Database } from '../Database.js';
 import type { Model } from '../Model.js';
 import type { ModelRegistry } from '../ModelRegistry.js';
 import type { RecoveryClass } from '../errorCodes.js';
 import type { LoadWhere, WhereClause } from '../query/types.js';
 import type { Schema } from '../schema/schema.js';
-export interface HydrationCoordinatorOptions {
-    readonly objectPool: ObjectPool;
+export interface OnDemandLoaderOptions {
+    readonly objectPool: InstanceCache;
     readonly database: Database;
     readonly registry: ModelRegistry;
     readonly schema: Schema;
@@ -43,11 +44,11 @@ export interface HydrationCoordinatorOptions {
 }
 export interface FetchOptions<T> {
     /**
-     * Filter clauses for the lookup. Accepts either the equality-object
-     * form (`{ id: 'abc' }` → `WHERE id = 'abc'`, array values → `IN`)
-     * or the explicit tuple form (`[['name', 'ILIKE', '%Goldman%']]`)
-     * matching the wire `WhereClause[]` 1:1. Multiple entries AND
-     * together. See `LoadWhere` in `../query/types.ts` for the full shape.
+     * Filter clauses for the lookup. Accepts either the equality-object form
+     * (`{ id: 'abc' }` becomes `WHERE id = 'abc'`, and an array value becomes an
+     * `IN`) or the explicit tuple form (`[['name', 'ILIKE', '%Acme%']]`), which
+     * mirrors the wire `WhereClause[]` exactly. Multiple entries combine with AND.
+     * See {@link LoadWhere} for the full shape.
      */
     readonly where?: LoadWhere<T>;
     readonly orderBy?: {
@@ -72,7 +73,7 @@ export interface FetchOptions<T> {
      */
     readonly expand?: readonly string[];
 }
-export declare class HydrationCoordinator {
+export declare class OnDemandLoader {
     private readonly opts;
     private readonly inFlight;
     /**
@@ -86,9 +87,9 @@ export declare class HydrationCoordinator {
     /**
      * Query keys that have been satisfied from the server at least once this
      * session. Once a key is here, repeat reads serve purely from the pool with
-     * NO network: the WebSocket delta stream keeps those pool rows fresh, so
-     * re-running the HTTP query would be redundant polling. This is the ledger
-     * that stops an already-open deck from re-querying on every navigation.
+     * no network round-trip: the WebSocket delta stream keeps those pool rows
+     * fresh, so re-running the HTTP query would be redundant polling. This ledger
+     * is what stops an already-open view from re-querying on every navigation.
      *
      * Cleared on reconnect (see {@link invalidate}) so that, after a connection
      * drop where deltas may have been missed, the next read re-confirms once.
@@ -96,15 +97,15 @@ export declare class HydrationCoordinator {
     private readonly hydratedKeys;
     private authTokenProvider;
     /**
-     * The auth-recovery backbone (the store's `recoverFromAuthRejection`),
-     * late-bound like {@link setAuthTokenProvider} because the store doesn't
+     * The credential-recovery hook (the store's `recoverFromAuthRejection`),
+     * late-bound like {@link setAuthTokenProvider} because the store does not
      * exist yet when the coordinator is constructed. Handed to `postQuery` so a
-     * 401 on the lazy lane re-mints through the SAME single-flight path the WS
-     * probe and proactive pre-roll use, then replays once — instead of silently
-     * returning empty rows against an expired key forever.
+     * 401 on the lazy lane re-mints through the same single-flight path the
+     * WebSocket probe uses, then replays the query once — instead of silently
+     * returning empty rows against an expired key.
      */
     private credentialRecovery;
-    constructor(opts: HydrationCoordinatorOptions);
+    constructor(opts: OnDemandLoaderOptions);
     /**
      * Late-bind the auth token getter. Browser cookie consumers can omit this;
      * bearer consumers need it so lazy HTTP queries use the same credential as
@@ -144,13 +145,13 @@ export declare class HydrationCoordinator {
      */
     private fetchFromNetwork;
     /**
-     * Fire-and-forget the ONE server confirm for a query that was just served
-     * from local cache but isn't hydrated yet. On success the key is marked
-     * hydrated, so every later read serves pure-local with no network until a
+     * Fires the single background confirm for a query that was just served from
+     * local cache but is not hydrated yet. On success the key is marked hydrated,
+     * so every later read serves purely from local with no network until a
      * reconnect invalidates the ledger. Deduped per query key so a render burst
-     * doesn't stampede. Errors are swallowed — the caller already has a usable
-     * local snapshot, and a failed confirm leaves the key un-hydrated so the
-     * next read simply tries again.
+     * does not stampede. Errors are swallowed — the caller already has a usable
+     * local snapshot, and a failed confirm leaves the key un-hydrated so the next
+     * read simply tries again.
      */
     private scheduleHydratingFetch;
     /**
@@ -185,7 +186,7 @@ export declare class HydrationCoordinator {
      * `postgres.camel` driver leaves behind when the server's SQL
      * bakes `__typename` into a JSONB literal — the driver's
      * snake↔camel transform misreads `__typename` as `_typename` with
-     * a leading underscore and produces `_Typename`. ObjectPool only
+     * a leading underscore and produces `_Typename`. InstanceCache only
      * recognises `__typename`, so without this step nested rows fall
      * through to the 'Unknown' branch and never instantiate.
      */