@abloatai/ablo 0.8.0 → 0.9.0

package/dist/sync/HydrationCoordinator.js

@@ -25,24 +25,41 @@ import { postQuery } from '../query/client.js';
 export class HydrationCoordinator {
     opts;
     inFlight = new Map();
-    capabilityTokenProvider = null;
+    /**
+     * 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.
+     */
+    revalidating = new Set();
+    /**
+     * 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.
+     */
+    hydratedKeys = new Set();
+    authTokenProvider = null;
     constructor(opts) {
         this.opts = opts;
-        this.capabilityTokenProvider = opts.getCapabilityToken ?? null;
+        this.authTokenProvider = opts.getAuthToken ?? opts.getCapabilityToken ?? null;
     }
     /**
-     * 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.
      */
-    setCapabilityTokenProvider(provider) {
-        this.capabilityTokenProvider = provider;
+    setAuthTokenProvider(provider) {
+        this.authTokenProvider = provider;
     }
-    resolveToken() {
-        return this.capabilityTokenProvider?.() ?? undefined;
+    /** @deprecated Use `setAuthTokenProvider`. */
+    setCapabilityTokenProvider(provider) {
+        this.setAuthTokenProvider(provider);
     }
     /**
      * Fetch matching rows for a model, hydrating the pool from IDB or
@@ -58,48 +75,218 @@ export class HydrationCoordinator {
                 `not registered in the schema.`, { code: 'model_not_registered' });
         }
         const clauses = normalizeWhere(options?.where);
-        const queryKey = stableKey(modelName, clauses, options?.orderBy, options?.limit);
+        const queryKey = stableKey(modelName, clauses, options?.orderBy, options?.limit, options?.expand);
         // Single-flight: an identical hydration is already in flight.
         const inFlight = this.inFlight.get(queryKey);
         if (inFlight)
             return inFlight;
-        const work = this.runFetch(modelName, typename, ModelClass, clauses, options);
+        const work = this.runFetch(modelName, typename, ModelClass, clauses, options, queryKey);
         this.inFlight.set(queryKey, work);
         work.finally(() => {
             this.inFlight.delete(queryKey);
         });
         return work;
     }
-    async runFetch(modelName, typename, ModelClass, clauses, options) {
-        const wantsComplete = (options?.type ?? 'complete') === 'complete';
-        // Step 1 — pool hit. Skip when caller asked for complete:
-        // they want server-confirmed state, not a stale pool snapshot.
-        if (!wantsComplete) {
-            const fromPool = scanPool(this.opts.objectPool, ModelClass, clauses);
-            if (fromPool.length > 0)
-                return applyLimit(fromPool, options?.limit);
+    async runFetch(modelName, typename, ModelClass, clauses, options, queryKey) {
+        // `{ type: 'complete' }` is the only way to force a server round-trip:
+        // read-after-write certainty. Every other read is local-first.
+        const explicitComplete = options?.type === 'complete';
+        const expand = options?.expand;
+        const hasExpand = !!(expand && expand.length > 0);
+        // Fast path — this exact query was already satisfied from the server this
+        // session. The WebSocket delta stream has kept the pool fresh since, so a
+        // repeat read needs ZERO network: serve straight from local. This is what
+        // stops an already-open deck from re-querying on every navigation when no
+        // new deltas have arrived.
+        if (!explicitComplete && this.hydratedKeys.has(queryKey)) {
+            return applyLimit(await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand), options?.limit);
         }
-        // Step 2 — IndexedDB. Survives reload + offline.
-        const fromIdb = await scanIdb(this.opts.database, typename, clauses);
-        const idbModels = fromIdb
-            .map((raw) => this.hydrateOne(raw, typename))
-            .filter((m) => m !== null);
-        if (idbModels.length > 0) {
-            this.opts.objectPool.addBatch(idbModels, ModelScope.live);
-            if (!wantsComplete)
-                return applyLimit(idbModels, options?.limit);
+        // Not yet hydrated (or an explicit complete read). For a non-complete read
+        // WITHOUT expand, if there's anything local to show (warm pool, or IDB
+        // after a reload), hand it back immediately and confirm with the server
+        // ONCE in the background — then mark the key hydrated so subsequent reads
+        // are pure-local. First paint never blocks on the network.
+        //
+        // Expand queries are deliberately excluded here: a present primary says
+        // nothing about whether its relations are loaded. Returning the parent now
+        // would surface it with empty children and let `layersReady` flip before
+        // the layers exist (the "pop-in" the deck gate guards against). So an
+        // un-hydrated expand query falls through to the blocking fetch that brings
+        // parent + children together; the SECOND open is served by the fast path.
+        if (!explicitComplete && !hasExpand) {
+            const local = await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand);
+            if (local.length > 0) {
+                this.scheduleHydratingFetch(queryKey, modelName, typename, clauses, options);
+                return applyLimit(local, options?.limit);
+            }
+        }
+        // Cold cache, or caller demanded server-confirmed state: block on the
+        // network, then mark this query hydrated so future reads serve local.
+        const networkModels = await this.fetchFromNetwork(modelName, typename, clauses, options);
+        this.hydratedKeys.add(queryKey);
+        if (networkModels.length > 0)
+            return applyLimit(networkModels, options?.limit);
+        // Network returned nothing — fall back to whatever's local (e.g. a
+        // complete read whose server result was empty but IDB still holds rows).
+        return applyLimit(await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand), options?.limit);
+    }
+    /**
+     * 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.
+     */
+    async readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand) {
+        let local = scanPool(this.opts.objectPool, ModelClass, clauses);
+        if (local.length === 0) {
+            const fromIdb = await scanIdb(this.opts.database, typename, clauses);
+            const idbModels = fromIdb
+                .map((raw) => this.hydrateOne(raw, typename))
+                .filter((m) => m !== null);
+            if (idbModels.length > 0) {
+                this.opts.objectPool.addBatch(idbModels, ModelScope.live);
+                local = idbModels;
+            }
+        }
+        if (hasExpand && expand && local.length > 0) {
+            await this.hydrateExpandedFromLocal(modelName, local.map((m) => m.id), expand);
         }
-        // Step 3 — network. Last resort. Always runs when wantsComplete.
+        return local;
+    }
+    /**
+     * 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() {
+        this.hydratedKeys.clear();
+    }
+    /**
+     * 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.
+     */
+    async fetchFromNetwork(modelName, typename, clauses, options) {
         const networkRows = await this.queryNetwork(modelName, clauses, options);
         const networkModels = networkRows
             .map((raw) => this.hydrateOne(raw, typename))
             .filter((m) => m !== null);
         if (networkModels.length > 0) {
             this.opts.objectPool.addBatch(networkModels, ModelScope.live);
-            // Background IDB write — don't block the caller.
+            // Background IDB write — don't block the caller. Expanded children are
+            // persisted to their own stores inside `queryNetwork`/`hydrateExpanded`.
             void this.persistToIdb(modelName, networkRows);
         }
-        return applyLimit(networkModels.length > 0 ? networkModels : idbModels, options?.limit);
+        return networkModels;
+    }
+    /**
+     * 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.
+     */
+    scheduleHydratingFetch(queryKey, modelName, typename, clauses, options) {
+        if (this.revalidating.has(queryKey))
+            return;
+        this.revalidating.add(queryKey);
+        void this.fetchFromNetwork(modelName, typename, clauses, options)
+            .then(() => {
+            this.hydratedKeys.add(queryKey);
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            this.revalidating.delete(queryKey);
+        });
+    }
+    /**
+     * 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.
+     */
+    async hydrateExpandedFromLocal(parentModelName, parentIds, relationNames) {
+        if (parentIds.length === 0)
+            return;
+        const parentDef = this.getModelDef(parentModelName);
+        if (!parentDef?.relations)
+            return;
+        for (const rel of relationNames) {
+            const relDef = parentDef.relations[rel];
+            if (!relDef)
+                continue;
+            if (relDef.type !== 'hasMany' && relDef.type !== 'hasOne')
+                continue;
+            const targetKey = relDef.target;
+            const foreignKey = relDef.foreignKey;
+            if (!targetKey || !foreignKey)
+                continue;
+            const targetTypename = this.resolveTypename(targetKey);
+            // Skip parents whose children are already pool-resident (O(1) when the
+            // FK is indexed). Falls through to a local read for the rest.
+            const missing = parentIds.filter((pid) => this.opts.objectPool.getByForeignKey(targetTypename, foreignKey, pid).length === 0);
+            if (missing.length === 0)
+                continue;
+            const rows = await this.readChildrenLocal(targetTypename, foreignKey, missing);
+            const models = rows
+                .map((raw) => this.hydrateOne(this.stampTypename(raw, targetTypename), targetTypename))
+                .filter((m) => m !== null);
+            if (models.length > 0) {
+                this.opts.objectPool.addBatch(models, ModelScope.live);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async readChildrenLocal(childTypename, foreignKey, parentIds) {
+        const store = this.opts.database.getStore(childTypename);
+        if (!store)
+            return [];
+        const isIndexed = this.opts.registry.getIndexedProperties(childTypename).includes(foreignKey);
+        if (isIndexed) {
+            const collected = [];
+            for (const pid of parentIds) {
+                const rows = await store.getAllFromIndex(foreignKey, pid);
+                if (Array.isArray(rows))
+                    collected.push(...rows);
+            }
+            // A non-empty result means the index is live (browser IDB). Empty can
+            // mean "no children" OR "no physical index" (in-memory) — fall through
+            // to the scan so the in-memory/SSR path stays correct.
+            if (collected.length > 0)
+                return collected;
+        }
+        try {
+            const all = await store.getAll();
+            if (!Array.isArray(all))
+                return [];
+            const idSet = new Set(parentIds);
+            return all.filter((r) => idSet.has(r[foreignKey]));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Typed accessor for a model's schema definition (typename + relations). */
+    getModelDef(modelName) {
+        return this.opts.schema.models?.[modelName];
     }
     hydrateOne(raw, typename) {
         if (!raw || typeof raw !== 'object')
@@ -176,7 +363,7 @@ export class HydrationCoordinator {
         };
         const result = await postQuery({
             baseUrl: this.opts.baseUrl,
-            capabilityToken: this.resolveToken(),
+            getAuthToken: this.authTokenProvider ?? undefined,
         }, { queries: [query] });
         const rows = Array.isArray(result.results[0]) ? result.results[0] : [];
         // Normalize: wire rows lack `__typename` when the server elides it.
@@ -207,8 +394,7 @@ export class HydrationCoordinator {
      * → `_Typename`), so the SDK can't trust whatever string lands.
      */
     hydrateExpanded(parentModelName, rows, relationNames) {
-        const schemaModels = this.opts.schema.models;
-        const parentDef = schemaModels?.[parentModelName];
+        const parentDef = this.getModelDef(parentModelName);
         for (const row of rows) {
             if (!row || typeof row !== 'object')
                 continue;
@@ -223,8 +409,10 @@ export class HydrationCoordinator {
                 const targetTypename = targetKey ? this.resolveTypename(targetKey) : undefined;
                 const items = Array.isArray(nested) ? nested : [nested];
                 const models = [];
+                const stampedItems = [];
                 for (const item of items) {
                     const stamped = this.stampTypename(item, targetTypename);
+                    stampedItems.push(stamped);
                     const m = this.hydrateOne(stamped);
                     if (m)
                         models.push(m);
@@ -232,6 +420,13 @@ export class HydrationCoordinator {
                 if (models.length > 0) {
                     this.opts.objectPool.addBatch(models, ModelScope.live);
                 }
+                // Persist expanded children to their OWN typed store so they survive
+                // reload and can be re-served by `hydrateExpandedFromLocal` — without
+                // this, expand-fetched relations live only inside the parent's row
+                // and are lost to a lazy child query after a cold start.
+                if (stampedItems.length > 0 && targetKey) {
+                    void this.persistToIdb(targetKey, stampedItems);
+                }
             }
         }
     }
@@ -280,7 +475,7 @@ export class HydrationCoordinator {
     }
 }
 // ── Helpers ────────────────────────────────────────────────────────────
-function stableKey(modelName, clauses, orderBy, limit) {
+function stableKey(modelName, clauses, orderBy, limit, expand) {
     // Sort clauses by their stringified form so caller order doesn't
     // produce different dedup keys for semantically identical queries.
     const sorted = [...clauses].map((c) => [...c]).sort((a, b) => {
@@ -288,7 +483,11 @@ function stableKey(modelName, clauses, orderBy, limit) {
         const kb = JSON.stringify(b);
         return ka < kb ? -1 : ka > kb ? 1 : 0;
     });
-    return JSON.stringify({ modelName, where: sorted, orderBy, limit });
+    // Expand is part of the query identity: `slides where deck=d1` and the same
+    // with `expand:['layers']` hydrate different data, so they must not share a
+    // ledger/dedup key. Sorted so relation order doesn't fork the key.
+    const expandKey = expand && expand.length > 0 ? [...expand].sort() : undefined;
+    return JSON.stringify({ modelName, where: sorted, orderBy, limit, expand: expandKey });
 }
 function applyLimit(arr, limit) {
     return typeof limit === 'number' ? arr.slice(0, limit) : arr;

package/dist/sync/NetworkProbe.d.ts

@@ -6,12 +6,15 @@
  * 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 + session validity in a single round-trip. The probe hits
- * `/api/auth/check`, which runs the SAME auth middleware as the WebSocket
- * upgrade path:
- *   204 No Content → reachable, session cookie valid
- *   401/403        → reachable, session expired or invalid
- *   network fail   → unreachable
+ * 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}):
+ *   204 No Content                         → `reachable`        (credential valid)
+ *   401 `apikey_expired` (ephemeral key)   → `credential_stale` (re-mint & 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`
  *
  * 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
@@ -21,22 +24,53 @@
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
  */
-/** Result of a network probe */
-export interface ProbeResult {
-    /** Whether the server was reachable */
-    reachable: boolean;
-    /** Whether the session cookie is still valid (null if server unreachable) */
-    sessionValid: boolean | null;
+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 intent from a trio of
+ * booleans. Mirrors the {@link RecoveryClass} taxonomy at the connectivity tier.
+ */
+export declare const PROBE_OUTCOMES: readonly ["reachable", "unreachable", "session_expired", "credential_stale", "auth_blocked"];
+/** Zod enum derived from {@link PROBE_OUTCOMES}. */
+export declare const probeOutcomeSchema: z.ZodEnum<{
+    auth_blocked: "auth_blocked";
+    session_expired: "session_expired";
+    reachable: "reachable";
+    unreachable: "unreachable";
+    credential_stale: "credential_stale";
+}>;
+/** A single probe outcome. See {@link PROBE_OUTCOMES}. */
+export type ProbeOutcome = z.infer<typeof probeOutcomeSchema>;
+/** Result of a network probe: a single {@link ProbeOutcome} plus round-trip
+ *  latency (null when the probe never completed). */
+export declare const probeResultSchema: z.ZodObject<{
+    outcome: z.ZodEnum<{
+        auth_blocked: "auth_blocked";
+        session_expired: "session_expired";
+        reachable: "reachable";
+        unreachable: "unreachable";
+        credential_stale: "credential_stale";
+    }>;
+    latencyMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/** @see {@link probeResultSchema} */
+export type ProbeResult = z.infer<typeof probeResultSchema>;
+export interface NetworkProbeOptions {
+    /**
+     * Sync-server base URL (HTTP or WS scheme accepted). If omitted, falls
+     * back to the legacy `NEXT_PUBLIC_GO_SERVER_URL` default.
+     */
+    baseUrl?: string;
     /**
-     * Reachable, but a NON-retryable auth/config failure that is NOT a session
-     * expiry (e.g. `api_key_required`, `jwt_issuer_untrusted`). The session is
-     * fine — the data-plane rejected the credential TYPE — so neither
-     * reconnecting nor re-authenticating will help. The manager stops instead of
-     * looping. Distinct from `sessionValid: false` (genuine expiry → sign in).
+     * Optional bearer credential. Browser cookie deployments can omit this;
+     * bearer-first deployments must pass the same `ek_`/`rk_` token used by
+     * bootstrap and the WebSocket upgrade.
      */
-    authBlocked?: boolean;
-    /** Round-trip time in ms (null if failed) */
-    latencyMs: number | null;
+    getAuthToken?: AuthTokenGetter;
+    /** Compatibility fallback for callers with a copied token string. */
+    authToken?: string | null;
 }
 /**
  * Probe the sync engine server with a lightweight HEAD request.
@@ -44,8 +78,8 @@ export interface ProbeResult {
  * Returns reachability AND session status in a single call, so the
  * ConnectionStore can make the right state transition without guessing.
  *
- * @param baseUrl The sync-server base URL (HTTP or WS scheme accepted).
- *                If omitted, falls back to `NEXT_PUBLIC_GO_SERVER_URL` →
- *                `http://localhost:8080` for backwards compatibility.
+ * @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.
  */
-export declare function probeNetwork(baseUrl?: string): Promise<ProbeResult>;
+export declare function probeNetwork(input?: string | NetworkProbeOptions): Promise<ProbeResult>;