@abloatai/ablo 0.8.0 → 0.9.0

package/dist/source/next.js

@@ -0,0 +1,26 @@
+/**
+ * Next.js App Router adapter for Data Source. The core `dataSource()` already
+ * returns a Web-standard `(Request) => Promise<Response>`, which Next App Router
+ * accepts directly — so this is pure ergonomics: wire an ORM `adapter` in via the
+ * bridge and hand back a named `POST` so the customer's route file is the minimum:
+ *
+ *   // app/api/ablo/source/route.ts
+ *   import { dataSourceNext } from '@abloatai/ablo/source/next';
+ *   import { prismaDataSource } from '@abloatai/ablo/source';
+ *   import { schema } from '@/ablo/schema';
+ *   import { prisma } from '@/lib/prisma';
+ *
+ *   export const { POST } = dataSourceNext({
+ *     schema,
+ *     apiKey: process.env.ABLO_API_KEY!,
+ *     adapter: prismaDataSource(prisma, schema),
+ *   });
+ *
+ * Day-one scope: Next + the adapter form only. Hand-written handlers use the core
+ * `dataSource()` directly; Hono/Express are the same one-liner and land on demand
+ * — not pre-built.
+ */
+import { dataSource } from './index.js';
+export function dataSourceNext(options) {
+    return { POST: dataSource(options) };
+}

package/dist/sync/BootstrapHelper.d.ts

@@ -61,7 +61,13 @@ export interface BootstrapOptions {
      * old clients that don't send a models param).
      */
     instantModels?: string[];
+    /**
+     * Shared SDK credential getter. Preferred over `setAuthToken`; read at
+     * request time so token refreshes apply without recreating BootstrapHelper.
+     */
+    getAuthToken?: AuthTokenGetter;
 }
+import { type AuthTokenGetter } from '../auth/credentialSource.js';
 import { type ValidatedServerDelta } from './schemas.js';
 export declare class BootstrapHelper {
     private options;
@@ -74,6 +80,10 @@ export declare class BootstrapHelper {
      */
     setCacheScope(cacheScope: string): void;
     setSyncGroups(syncGroups: readonly string[] | undefined): void;
+    /**
+     * Compatibility setter for direct BootstrapHelper users. The SDK-owned
+     * `Ablo()` path passes `getAuthToken` and does not mutate this helper.
+     */
     setAuthToken(authToken: string | undefined): void;
     /**
      * Create a promise that rejects after a timeout

package/dist/sync/BootstrapHelper.js

@@ -4,6 +4,7 @@
  */
 import { getContext } from '../context.js';
 import { SyncSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '../errors.js';
+import { withAuthHeaders } from '../auth/credentialSource.js';
 // SyncObservability replaced by getContext().observability
 import { parseBootstrapResponse } from './schemas.js';
 export class BootstrapHelper {
@@ -46,6 +47,10 @@ export class BootstrapHelper {
     setSyncGroups(syncGroups) {
         this.options.syncGroups = [...(syncGroups ?? [])];
     }
+    /**
+     * Compatibility setter for direct BootstrapHelper users. The SDK-owned
+     * `Ablo()` path passes `getAuthToken` and does not mutate this helper.
+     */
     setAuthToken(authToken) {
         if (!authToken) {
             delete this.options.authToken;
@@ -197,15 +202,11 @@ export class BootstrapHelper {
         // conditional revalidation (If-None-Match) implement it at their own
         // level where they own the cache-key namespace. The 304 branch below
         // remains defensively in place for when a caller enables revalidation.
-        const headers = { 'Content-Type': 'application/json' };
-        if (this.options.authToken) {
-            headers.Authorization = `Bearer ${this.options.authToken}`;
-        }
+        const headers = withAuthHeaders(this.options.getAuthToken, { 'Content-Type': 'application/json' }, this.options.authToken);
         this.abortController = new AbortController();
         const res = await fetch(url, {
             method: 'GET',
             headers,
-            credentials: 'include',
             signal: this.abortController.signal,
         });
         const etag = res.headers.get('ETag');
@@ -272,15 +273,11 @@ export class BootstrapHelper {
         try {
             response = await fetch(url, {
                 method: 'GET',
-                headers: {
+                headers: withAuthHeaders(this.options.getAuthToken, {
                     'Content-Type': 'application/json',
                     'Cache-Control': 'no-cache, no-store, must-revalidate',
                     Pragma: 'no-cache',
-                    ...(this.options.authToken
-                        ? { Authorization: `Bearer ${this.options.authToken}` }
-                        : {}),
-                },
-                credentials: 'include',
+                }, this.options.authToken),
                 signal: this.abortController.signal,
                 cache: 'no-store', // Force browser to not cache
             });
@@ -337,10 +334,9 @@ export class BootstrapHelper {
         const url = `${this.options.baseUrl}/sync/entity/${modelName}/${id}`;
         const response = await fetch(url, {
             method: 'GET',
-            headers: {
+            headers: withAuthHeaders(this.options.getAuthToken, {
                 'Content-Type': 'application/json',
-            },
-            credentials: 'include',
+            }, this.options.authToken),
         });
         if (response.status === 404) {
             return null;
@@ -436,7 +432,6 @@ export class BootstrapHelper {
         try {
             const response = await fetch(`${this.options.baseUrl}/health`, {
                 method: 'GET',
-                credentials: 'include',
                 signal: AbortSignal.timeout(5000),
                 cache: 'no-store',
             });

package/dist/sync/ConnectionManager.d.ts

@@ -34,7 +34,8 @@
  *      instead of hard-reloading an already-offline browser.
  */
 import { type ProbeResult } from './NetworkProbe.js';
-export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'auth_blocked' | 'session_expired';
+import type { AuthTokenGetter } from '../auth/credentialSource.js';
+export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'refreshing_credential' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'auth_blocked' | 'session_expired';
 export type ConnectionEvent = {
     type: 'NETWORK_LOST';
 } | {
@@ -54,8 +55,18 @@ export type ConnectionEvent = {
     sessionValid: boolean;
 } | {
     type: 'PROBE_AUTH_BLOCKED';
+}
+/** The probe saw an expired ephemeral access key (`access_credential_expiry`).
+ *  Recoverable: re-mint a fresh `ek_`/`rk_` and re-probe — never a sign-out. */
+ | {
+    type: 'PROBE_CREDENTIAL_STALE';
 } | {
     type: 'PROBE_FAILED';
+}
+/** A fresh access credential is available (the re-mint succeeded, or one was
+ *  pushed in via `setAuthToken`). Re-probe so a parked connection picks it up. */
+ | {
+    type: 'CREDENTIAL_REFRESHED';
 } | {
     type: 'RECONNECT_SUCCESS';
 } | {
@@ -70,6 +81,20 @@ export type ConnectionEvent = {
 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.
+     */
+    onRefreshCredential?: () => Promise<'refreshed' | 'session_error' | 'network_error'>;
     /** Called when the session is confirmed expired — route to signin. */
     onSessionExpired: () => void;
     /** Called to tear down the WebSocket when entering a dead state. */
@@ -90,6 +115,12 @@ export interface ConnectionManagerOptions {
      * default of `probeNetwork`.
      */
     baseUrl?: string;
+    /**
+     * Current bearer credential for authenticated probes. Read lazily so token
+     * refreshes pushed through `Ablo.setAuthToken()` are used by the next probe
+     * without recreating the manager.
+     */
+    getAuthToken?: AuthTokenGetter;
     /** Override retry ceilings / jitter. Production should leave defaults. */
     backoff?: Partial<typeof DEFAULT_BACKOFF>;
 }
@@ -109,8 +140,12 @@ export declare class ConnectionManager {
     private debounceTimer;
     private watchdogTimer;
     private stuckCycles;
+    /** Consecutive access-key re-mints in the current recovery cycle; reset on
+     *  reaching `connected`. See {@link MAX_CREDENTIAL_REFRESH_ATTEMPTS}. */
+    private credentialRefreshAttempts;
     private disposed;
     private readonly baseUrl?;
+    private readonly getAuthToken?;
     private readonly backoff;
     private handleBrowserOnline;
     private handleBrowserOffline;
@@ -122,6 +157,25 @@ export declare class ConnectionManager {
     private transition;
     private onEnterState;
     private runProbe;
+    /**
+     * Re-mint the short-lived access key on `refreshing_credential`. Delegates to
+     * the `onRefreshCredential` callback (which mints a fresh `ek_`/`rk_` from the
+     * still-valid login and pushes it into the credential source) and maps its
+     * tri-state outcome onto the FSM:
+     *   - `refreshed`     → `CREDENTIAL_REFRESHED` → re-probe & reconnect.
+     *   - `session_error` → `BOOTSTRAP_FAILED_SESSION` → sign out (login is gone).
+     *   - `network_error` → `RECONNECT_FAILED` → back off & retry (never sign out).
+     *
+     * A bounded attempt counter guards against a hot loop where the server keeps
+     * reporting the key stale even after a "successful" re-mint (e.g. a clock skew
+     * or a mint that returns an already-rejected key): after
+     * `MAX_CREDENTIAL_REFRESH_ATTEMPTS` we fall through to `auth_blocked` (stop,
+     * no sign-out) rather than spin. The counter resets once we reach `connected`.
+     *
+     * When no refresher is wired (e.g. a static `apiKey` deployment), we re-probe
+     * directly — the credential source's own scheduler owns refresh there.
+     */
+    private runRefreshCredential;
     private runReconnect;
     private scheduleBackoff;
     private setupBrowserListeners;

package/dist/sync/ConnectionManager.js

@@ -46,6 +46,10 @@ const DEFAULT_BACKOFF = {
 const ONLINE_DEBOUNCE_MS = 500;
 const WATCHDOG_INTERVAL_MS = 30_000;
 const MAX_STUCK_CYCLES_BEFORE_RELOAD = 6;
+/** Cap on consecutive access-key re-mints before giving up to `auth_blocked`.
+ *  Stops a hot loop if the server keeps reporting the key stale even after a
+ *  "successful" re-mint (clock skew, a mint returning an already-rejected key). */
+const MAX_CREDENTIAL_REFRESH_ATTEMPTS = 3;
 // ─── ConnectionManager ────────────────────────────────────────────────────
 export class ConnectionManager {
     // Observable state
@@ -59,14 +63,19 @@ export class ConnectionManager {
     debounceTimer = null;
     watchdogTimer = null;
     stuckCycles = 0;
+    /** Consecutive access-key re-mints in the current recovery cycle; reset on
+     *  reaching `connected`. See {@link MAX_CREDENTIAL_REFRESH_ATTEMPTS}. */
+    credentialRefreshAttempts = 0;
     disposed = false;
     baseUrl;
+    getAuthToken;
     backoff;
     handleBrowserOnline = null;
     handleBrowserOffline = null;
     handleVisibilityChange = null;
     constructor(options = {}) {
         this.baseUrl = options.baseUrl;
+        this.getAuthToken = options.getAuthToken;
         this.backoff = { ...DEFAULT_BACKOFF, ...(options.backoff ?? {}) };
         makeAutoObservable(this, {}, { autoBind: true });
     }
@@ -151,6 +160,7 @@ export class ConnectionManager {
                     case 'MANUAL_RETRY':
                     case 'TAB_VISIBLE':
                     case 'WS_HANDSHAKE_FAILED':
+                    case 'CREDENTIAL_REFRESHED':
                         return 'probing_network';
                     case 'WS_SESSION_ERROR':
                     case 'BOOTSTRAP_FAILED_SESSION':
@@ -162,6 +172,9 @@ export class ConnectionManager {
                 switch (event.type) {
                     case 'PROBE_SUCCESS':
                         return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_CREDENTIAL_STALE':
+                        // Access key expired but the login is fine — re-mint, don't sign out.
+                        return 'refreshing_credential';
                     case 'PROBE_AUTH_BLOCKED':
                         return 'auth_blocked';
                     case 'PROBE_FAILED':
@@ -177,6 +190,7 @@ export class ConnectionManager {
                     case 'TAB_VISIBLE':
                     case 'MANUAL_RETRY':
                     case 'BACKOFF_ELAPSED':
+                    case 'CREDENTIAL_REFRESHED':
                         return 'probing_network';
                     case 'NETWORK_LOST':
                         return 'offline';
@@ -187,6 +201,8 @@ export class ConnectionManager {
                 switch (event.type) {
                     case 'PROBE_SUCCESS':
                         return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_CREDENTIAL_STALE':
+                        return 'refreshing_credential';
                     case 'PROBE_AUTH_BLOCKED':
                         return 'auth_blocked';
                     case 'NETWORK_LOST':
@@ -194,6 +210,31 @@ export class ConnectionManager {
                     default:
                         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.
+                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.
+                        return 'session_expired';
+                    case 'RECONNECT_FAILED':
+                        // Couldn't reach the mint endpoint (offline/5xx/throw) — transient.
+                        // Back off and retry; never sign out for a network failure.
+                        return 'backoff';
+                    case 'PROBE_AUTH_BLOCKED':
+                        // Bounded-attempt fallback: the key keeps coming back stale even
+                        // after re-mint (see runRefreshCredential's attempt guard). Stop
+                        // looping without signing out.
+                        return 'auth_blocked';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    default:
+                        return null;
+                }
             case 'reconnecting':
                 switch (event.type) {
                     case 'RECONNECT_SUCCESS':
@@ -218,10 +259,11 @@ export class ConnectionManager {
                         return 'probing_network';
                     case 'NETWORK_ONLINE':
                     case 'TAB_VISIBLE':
-                        // Network came back while we were waiting out a backoff
-                        // delay — jump straight to probing instead of waiting the
-                        // full exponential interval. Fixes the "doesn't retrigger
-                        // when internet comes back" bug.
+                    case 'CREDENTIAL_REFRESHED':
+                        // Network came back (or a fresh credential arrived) while we were
+                        // waiting out a backoff delay — jump straight to probing instead of
+                        // waiting the full exponential interval. Fixes the "doesn't
+                        // retrigger when internet comes back" bug.
                         return 'probing_network';
                     case 'NETWORK_LOST':
                         return 'offline';
@@ -235,12 +277,14 @@ export class ConnectionManager {
                 // Reachable, but the data-plane rejected the credential (non-retryable,
                 // non-expiry — e.g. api_key_required, jwt_issuer_untrusted). Don't
                 // auto-reconnect and don't sign out. Allow a manual retry or a
-                // tab-focus / network-return re-probe (e.g. after a server deploy);
-                // a network drop parks offline; a genuine session error still expires.
+                // tab-focus / network-return / fresh-credential re-probe (e.g. after a
+                // server deploy or an out-of-band re-mint); a network drop parks
+                // offline; a genuine session error still expires.
                 switch (event.type) {
                     case 'MANUAL_RETRY':
                     case 'TAB_VISIBLE':
                     case 'NETWORK_ONLINE':
+                    case 'CREDENTIAL_REFRESHED':
                         return 'probing_network';
                     case 'NETWORK_LOST':
                         return 'offline';
@@ -261,6 +305,9 @@ export class ConnectionManager {
         switch (state) {
             case 'connected':
                 this.clearBackoffTimer();
+                runInAction(() => {
+                    this.credentialRefreshAttempts = 0;
+                });
                 break;
             case 'offline':
                 this.clearBackoffTimer();
@@ -275,6 +322,9 @@ export class ConnectionManager {
             case 'reconnecting':
                 this.runReconnect();
                 break;
+            case 'refreshing_credential':
+                this.runRefreshCredential();
+                break;
             case 'backoff':
                 this.scheduleBackoff();
                 break;
@@ -299,24 +349,108 @@ export class ConnectionManager {
     // ── Async operations ─────────────────────────────────────────────────
     async runProbe() {
         try {
-            const result = await probeNetwork(this.baseUrl);
+            const result = await probeNetwork({
+                baseUrl: this.baseUrl,
+                getAuthToken: this.getAuthToken,
+            });
             runInAction(() => {
                 this.lastProbeResult = result;
             });
-            if (result.authBlocked) {
-                this.send({ type: 'PROBE_AUTH_BLOCKED' });
-            }
-            else if (result.reachable) {
-                this.send({ type: 'PROBE_SUCCESS', sessionValid: result.sessionValid ?? true });
-            }
-            else {
-                this.send({ type: 'PROBE_FAILED' });
+            // One probe outcome → one event. Exhaustive over ProbeOutcome so a new
+            // outcome can't be silently dropped.
+            switch (result.outcome) {
+                case 'reachable':
+                    this.send({ type: 'PROBE_SUCCESS', sessionValid: true });
+                    break;
+                case 'session_expired':
+                    // Genuine login expiry — terminal. (PROBE_SUCCESS with
+                    // sessionValid:false routes to session_expired in the FSM.)
+                    this.send({ type: 'PROBE_SUCCESS', sessionValid: false });
+                    break;
+                case 'credential_stale':
+                    // Access key expired but the login is fine — re-mint, don't sign out.
+                    this.send({ type: 'PROBE_CREDENTIAL_STALE' });
+                    break;
+                case 'auth_blocked':
+                    this.send({ type: 'PROBE_AUTH_BLOCKED' });
+                    break;
+                case 'unreachable':
+                    this.send({ type: 'PROBE_FAILED' });
+                    break;
+                default: {
+                    const _exhaustive = result.outcome;
+                    void _exhaustive;
+                    this.send({ type: 'PROBE_FAILED' });
+                }
             }
         }
         catch {
             this.send({ type: 'PROBE_FAILED' });
         }
     }
+    /**
+     * Re-mint the short-lived access key on `refreshing_credential`. Delegates to
+     * the `onRefreshCredential` callback (which mints a fresh `ek_`/`rk_` from the
+     * still-valid login and pushes it into the credential source) and maps its
+     * tri-state outcome onto the FSM:
+     *   - `refreshed`     → `CREDENTIAL_REFRESHED` → re-probe & reconnect.
+     *   - `session_error` → `BOOTSTRAP_FAILED_SESSION` → sign out (login is gone).
+     *   - `network_error` → `RECONNECT_FAILED` → back off & retry (never sign out).
+     *
+     * A bounded attempt counter guards against a hot loop where the server keeps
+     * reporting the key stale even after a "successful" re-mint (e.g. a clock skew
+     * or a mint that returns an already-rejected key): after
+     * `MAX_CREDENTIAL_REFRESH_ATTEMPTS` we fall through to `auth_blocked` (stop,
+     * no sign-out) rather than spin. The counter resets once we reach `connected`.
+     *
+     * When no refresher is wired (e.g. a static `apiKey` deployment), we re-probe
+     * directly — the credential source's own scheduler owns refresh there.
+     */
+    async runRefreshCredential() {
+        if (this.credentialRefreshAttempts >= MAX_CREDENTIAL_REFRESH_ATTEMPTS) {
+            getContext().logger.warn('[ConnectionManager] Access key still stale after repeated re-mints — stopping', { attempts: this.credentialRefreshAttempts });
+            runInAction(() => {
+                this.credentialRefreshAttempts = 0;
+            });
+            this.send({ type: 'PROBE_AUTH_BLOCKED' });
+            return;
+        }
+        runInAction(() => {
+            this.credentialRefreshAttempts += 1;
+        });
+        const refresher = this.callbacks?.onRefreshCredential;
+        if (!refresher) {
+            // No re-mint path wired — re-probe with whatever the credential source
+            // holds (a static-key deployment refreshes out-of-band, if at all).
+            this.send({ type: 'CREDENTIAL_REFRESHED' });
+            return;
+        }
+        try {
+            const result = await refresher();
+            switch (result) {
+                case 'refreshed':
+                    this.send({ type: 'CREDENTIAL_REFRESHED' });
+                    break;
+                case 'session_error':
+                    this.send({ type: 'BOOTSTRAP_FAILED_SESSION' });
+                    break;
+                case 'network_error':
+                    this.send({ type: 'RECONNECT_FAILED' });
+                    break;
+                default: {
+                    const _exhaustive = result;
+                    void _exhaustive;
+                    this.send({ type: 'RECONNECT_FAILED' });
+                }
+            }
+        }
+        catch (error) {
+            // A thrown refresher is transient by contract (offline / mint endpoint
+            // unreachable) — back off and retry, never sign out.
+            getContext().logger.warn('[ConnectionManager] Credential re-mint threw (transient)', { error });
+            this.send({ type: 'RECONNECT_FAILED' });
+        }
+    }
     async runReconnect() {
         if (!this.callbacks)
             return;
@@ -431,6 +565,7 @@ export class ConnectionManager {
             const isStuck = this.state !== 'connected' &&
                 this.state !== 'session_expired' &&
                 this.state !== 'probing_network' &&
+                this.state !== 'refreshing_credential' &&
                 this.state !== 'reconnecting';
             if (isStuck) {
                 this.stuckCycles++;
@@ -467,7 +602,11 @@ export class ConnectionManager {
     get isConnected() { return this.state === 'connected'; }
     get isOffline() { return this.state === 'offline' || this.state === 'waiting_for_network'; }
     get isReconnecting() {
-        return this.state === 'probing_network' || this.state === 'reconnecting' || this.state === 'backoff';
+        return (this.state === 'probing_network' ||
+            this.state === 'validating_session' ||
+            this.state === 'refreshing_credential' ||
+            this.state === 'reconnecting' ||
+            this.state === 'backoff');
     }
     get isSessionExpired() { return this.state === 'session_expired'; }
     get offlineDuration() {

package/dist/sync/HydrationCoordinator.d.ts

@@ -33,12 +33,11 @@ export interface HydrationCoordinatorOptions {
     /** Bootstrap base URL (without trailing slash), e.g. `https://api.example.com/api`. */
     readonly baseUrl: string;
     /**
-     * Lazy getter for the active capability token. Resolved per-request
-     * so cap refreshes propagate without re-instantiating the coordinator.
-     * Optional: browser consumers ride session cookies and can omit this;
-     * Node consumers (agent-worker) must wire it through or HTTP queries
-     * fail with 401 because cookies aren't available.
+     * Lazy getter for the active bearer token. Resolved per request so refreshes
+     * propagate without re-instantiating the coordinator.
      */
+    readonly getAuthToken?: () => string | null;
+    /** @deprecated Use `getAuthToken`. */
     readonly getCapabilityToken?: () => string | null;
 }
 export interface FetchOptions<T> {
@@ -55,10 +54,14 @@ export interface FetchOptions<T> {
     };
     readonly limit?: number;
     /**
-     * `'complete'` (default): wait for network round-trip even if local
-     * data exists, so the caller observes server-confirmed state.
-     * `'unknown'`: return whatever's in the pool/IDB immediately and
-     * fire the network in the background.
+     * Freshness mode. When omitted, the default is derived from the model's
+     * load strategy: `lazy` models default to `'unknown'` (local-first), while
+     * `instant`/`partial` models default to `'complete'`.
+     *
+     * `'complete'`: wait for the network round-trip even if local data exists,
+     * so the caller observes server-confirmed state (read-after-write).
+     * `'unknown'`: return whatever's in the pool/IDB immediately and fire the
+     * network refresh in the background (stale-while-revalidate).
      */
     readonly type?: 'complete' | 'unknown';
     /**
@@ -71,18 +74,35 @@ export interface FetchOptions<T> {
 export declare class HydrationCoordinator {
     private readonly opts;
     private readonly inFlight;
-    private capabilityTokenProvider;
+    /**
+     * Query keys with a background confirm currently in flight. Distinct from
+     * {@link inFlight} (which dedupes *blocking* callers awaiting the same
+     * fetch): this set dedupes the fire-and-forget network confirm kicked off
+     * after a local-first read returns cached data, so a burst of mounts that
+     * all hit the warm pool/IDB don't each spawn their own redundant fetch.
+     */
+    private readonly revalidating;
+    /**
+     * 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.
+     *
+     * Cleared on reconnect (see {@link invalidate}) so that, after a connection
+     * drop where deltas may have been missed, the next read re-confirms once.
+     */
+    private readonly hydratedKeys;
+    private authTokenProvider;
     constructor(opts: HydrationCoordinatorOptions);
     /**
-     * Late-bind the capability token getter. Used by `Ablo.ts` to wire
-     * the token closure after the coordinator is constructed (the token
-     * isn't known until auth resolves, which happens after component
-     * construction). Browser consumers ride session cookies and don't
-     * need this; Node consumers (agent-worker) MUST call it or HTTP
-     * queries fail with 401 because cookies aren't available.
+     * 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
+     * bootstrap and the WebSocket.
      */
+    setAuthTokenProvider(provider: () => string | null): void;
+    /** @deprecated Use `setAuthTokenProvider`. */
     setCapabilityTokenProvider(provider: () => string | null): void;
-    private resolveToken;
     /**
      * Fetch matching rows for a model, hydrating the pool from IDB or
      * network if not already present. Idempotent and single-flight
@@ -90,6 +110,62 @@ export declare class HydrationCoordinator {
      */
     fetch<T>(modelName: string, options?: FetchOptions<T>): Promise<Model[]>;
     private runFetch;
+    /**
+     * Read a query's rows from local storage only — pool first, then IndexedDB
+     * on a pool miss (cold start after reload, or LRU eviction), hydrating the
+     * pool from IDB as a side effect. Resolves requested `expand` relations from
+     * their own local stores too. Never touches the network.
+     */
+    private readLocal;
+    /**
+     * Drop the hydration ledger so the next read of each query re-confirms with
+     * the server. Called on reconnect — after a connection drop, deltas may have
+     * been missed, so the "WS keeps the pool fresh" assumption no longer holds
+     * until a fresh fetch (or the engine's delta catch-up) reconciles.
+     */
+    invalidate(): void;
+    /**
+     * Run the network leg of a fetch: query the server, hydrate primary rows
+     * (and any expanded relations) into the pool, and persist them to IDB.
+     * Shared by the blocking path (`runFetch` step 3) and the background
+     * revalidation kicked off after an `'unknown'` local hit.
+     */
+    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
+     * 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.
+     */
+    private scheduleHydratingFetch;
+    /**
+     * Hydrate a parent's `hasMany`/`hasOne` relations from their OWN local
+     * stores (pool first, then IndexedDB by the FK secondary index) into the
+     * pool. The mirror of {@link hydrateExpanded} for the local read path:
+     * `hydrateExpanded` walks server-JOINed nested rows, this walks the child
+     * model's own store keyed by the relation's foreign key.
+     *
+     * Fully schema-driven via the relation's `target` + `foreignKey` — no
+     * per-model special-casing. `belongsTo` relations are skipped: those point
+     * at a single parent (the inverse direction), already covered by the
+     * primary scan when that parent is itself the fetched model.
+     */
+    private hydrateExpandedFromLocal;
+    /**
+     * Read a child model's rows from local storage by foreign key.
+     *
+     * Uses the FK secondary index (O(matches) per parent) only when the schema
+     * declares one — `getAllFromIndex` resolves `[]` for a missing index rather
+     * than throwing, so the decision is made up front from the registry, not by
+     * catching. Unindexed FKs — and in-memory stores, which carry no secondary
+     * indexes at all — fall back to a single full-store scan filtered in JS.
+     */
+    private readChildrenLocal;
+    /** Typed accessor for a model's schema definition (typename + relations). */
+    private getModelDef;
     private hydrateOne;
     /**
      * Stamp `__typename` onto a row when it's known (from the schema's