@abloatai/ablo 0.3.0

package/dist/sync/HydrationCoordinator.js

@@ -0,0 +1,468 @@
+/**
+ * HydrationCoordinator — the lazy-load lane of the sync engine.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { ModelScope } from '../ObjectPool.js';
+import { postQuery } from '../query/client.js';
+export class HydrationCoordinator {
+    opts;
+    inFlight = new Map();
+    capabilityTokenProvider = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.capabilityTokenProvider = 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.
+     */
+    setCapabilityTokenProvider(provider) {
+        this.capabilityTokenProvider = provider;
+    }
+    resolveToken() {
+        return this.capabilityTokenProvider?.() ?? undefined;
+    }
+    /**
+     * Fetch matching rows for a model, hydrating the pool from IDB or
+     * network if not already present. Idempotent and single-flight
+     * deduped on the (modelName, where, orderBy, limit) tuple.
+     */
+    async fetch(modelName, options) {
+        const typename = this.resolveTypename(modelName);
+        const ModelClass = this.opts.registry.getModelByName(typename)
+            ?? this.opts.registry.getModelByName(modelName);
+        if (!ModelClass) {
+            throw new Error(`HydrationCoordinator.fetch: unknown model "${modelName}" — ` +
+                `not registered in the schema.`);
+        }
+        const clauses = normalizeWhere(options?.where);
+        const queryKey = stableKey(modelName, clauses, options?.orderBy, options?.limit);
+        // 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);
+        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);
+        }
+        // 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);
+        }
+        // Step 3 — network. Last resort. Always runs when wantsComplete.
+        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.
+            void this.persistToIdb(modelName, networkRows);
+        }
+        return applyLimit(networkModels.length > 0 ? networkModels : idbModels, options?.limit);
+    }
+    hydrateOne(raw, typename) {
+        if (!raw || typeof raw !== 'object')
+            return null;
+        const obj = raw;
+        if (typeof obj.id !== 'string')
+            return null;
+        if (this.opts.objectPool.has(obj.id)) {
+            // Pool already has this entity, but the row coming from the
+            // network is the freshest server-confirmed state. Apply the new
+            // fields onto the existing instance instead of returning the
+            // stale model verbatim — otherwise a `load()` that re-fetches
+            // after a missed delta (WS dropped, tab slept, redeploy) silently
+            // discards the fresh state and the consumer keeps seeing the
+            // birth-time snapshot forever. `updateFromData` is the same
+            // primitive `ObjectPool.upsert()` uses for delta application,
+            // so the behaviour matches "delta-applied" semantics exactly.
+            const existing = this.opts.objectPool.get(obj.id);
+            if (existing) {
+                const stamped = this.stampTypename(obj, typename);
+                existing.updateFromData(stamped);
+                return existing;
+            }
+            return null;
+        }
+        // Stamp the known relation typename onto the row when the source
+        // (IndexedDB rows, sometimes network rows) didn't carry one. Without
+        // this, ObjectPool.createFromData falls through to the 'Unknown'
+        // model-name branch and emits the
+        // "ObjectPool.createFromData: No model identifier found" warning,
+        // failing to hydrate the entity from cache (network path then has to
+        // re-populate it). The typename comes from the schema relation
+        // (`'SlideLayer'`, `'SlideLayoutLayer'`, etc.) so no guessing involved.
+        const stamped = this.stampTypename(obj, typename);
+        return this.opts.objectPool.createFromData(stamped);
+    }
+    /**
+     * Stamp `__typename` onto a row when it's known (from the schema's
+     * relation target). Strips the mangled `_Typename` key the
+     * `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
+     * recognises `__typename`, so without this step nested rows fall
+     * through to the 'Unknown' branch and never instantiate.
+     */
+    stampTypename(item, typename) {
+        if (!item || typeof item !== 'object' || !typename)
+            return item;
+        const obj = item;
+        if (obj.__typename === typename)
+            return obj;
+        const { _Typename: _drop, ...rest } = obj;
+        void _drop;
+        return { __typename: typename, ...rest };
+    }
+    async queryNetwork(modelName, clauses, options) {
+        const typename = this.resolveTypename(modelName);
+        const orderEntries = options?.orderBy ? Object.entries(options.orderBy) : [];
+        const firstOrder = orderEntries[0];
+        const query = {
+            model: typename,
+            where: clauses.map((c) => columnizeClause(c)),
+            ...(firstOrder
+                ? {
+                    orderBy: columnize(firstOrder[0]),
+                    order: firstOrder[1] ?? 'asc',
+                }
+                : {}),
+            ...(options?.limit ? { limit: options.limit } : {}),
+            ...(options?.expand && options.expand.length > 0
+                ? { related: options.expand }
+                : {}),
+        };
+        const result = await postQuery({
+            baseUrl: this.opts.baseUrl,
+            capabilityToken: this.resolveToken(),
+        }, { queries: [query] });
+        const rows = Array.isArray(result.results[0]) ? result.results[0] : [];
+        // Normalize: wire rows lack `__typename` when the server elides it.
+        const normalized = rows.map((row) => {
+            if (row && typeof row === 'object' && !('__typename' in row)) {
+                return { __typename: typename, ...row };
+            }
+            return row;
+        });
+        // Expand: server returns related entities nested under each row
+        // (`row.layers = [{...}, ...]`). Walk the nested shape, stamp the
+        // typename from the schema's relation metadata (the server bakes
+        // `__typename` into the JSONB but the postgres.camel driver
+        // mangles it to `_Typename` mid-flight, so client-side stamping
+        // is the only reliable path), hydrate each related row into its
+        // own typed pool, then leave the nested arrays in place on the
+        // primary row.
+        if (options?.expand && options.expand.length > 0) {
+            this.hydrateExpanded(modelName, normalized, options.expand);
+        }
+        return normalized;
+    }
+    /**
+     * Hydrate nested expanded rows. Resolves each relation's target
+     * typename via the schema and stamps `__typename` on every nested
+     * row before passing to `hydrateOne` — the server's JSONB
+     * `__typename` field gets mangled by `postgres.camel` (`__typename`
+     * → `_Typename`), so the SDK can't trust whatever string lands.
+     */
+    hydrateExpanded(parentModelName, rows, relationNames) {
+        const schemaModels = this.opts.schema.models;
+        const parentDef = schemaModels?.[parentModelName];
+        for (const row of rows) {
+            if (!row || typeof row !== 'object')
+                continue;
+            const obj = row;
+            for (const rel of relationNames) {
+                const nested = obj[rel];
+                if (!nested)
+                    continue;
+                // Resolve target typename via parent's relations map.
+                const relDef = parentDef?.relations?.[rel];
+                const targetKey = relDef?.target;
+                const targetTypename = targetKey ? this.resolveTypename(targetKey) : undefined;
+                const items = Array.isArray(nested) ? nested : [nested];
+                const models = [];
+                for (const item of items) {
+                    const stamped = this.stampTypename(item, targetTypename);
+                    const m = this.hydrateOne(stamped);
+                    if (m)
+                        models.push(m);
+                }
+                if (models.length > 0) {
+                    this.opts.objectPool.addBatch(models, ModelScope.live);
+                }
+            }
+        }
+    }
+    async persistToIdb(modelName, rows) {
+        const store = this.opts.database.getStore(this.resolveTypename(modelName));
+        if (!store)
+            return;
+        for (const row of rows) {
+            try {
+                await store.put(row);
+            }
+            catch {
+                // IDB writes are best-effort — a transient quota/transaction
+                // failure shouldn't break the hydration's primary purpose.
+            }
+        }
+    }
+    resolveTypename(modelName) {
+        // Schema is the source of truth for wire typenames. The model proxy
+        // is keyed by camelCase plural (`slideLayers`) but the wire query +
+        // ObjectPool typeIndex use the typename (`SlideLayer`).
+        const def = this.opts.schema
+            .models?.[modelName];
+        return def?.typename ?? modelName;
+    }
+}
+// ── Helpers ────────────────────────────────────────────────────────────
+function stableKey(modelName, clauses, orderBy, limit) {
+    // 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) => {
+        const ka = JSON.stringify(a);
+        const kb = JSON.stringify(b);
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    return JSON.stringify({ modelName, where: sorted, orderBy, limit });
+}
+function applyLimit(arr, limit) {
+    return typeof limit === 'number' ? arr.slice(0, limit) : arr;
+}
+function scanPool(pool, ModelClass, clauses) {
+    const all = pool.getByType(ModelClass);
+    if (clauses.length === 0)
+        return all;
+    return all.filter((entity) => matchesClauses(entity, clauses));
+}
+async function scanIdb(database, modelName, clauses) {
+    const store = database.getStore(modelName);
+    if (!store)
+        return [];
+    // Fast path: a single equality `id` lookup hits the primary key.
+    const eqClauses = extractEqClauses(clauses);
+    if (clauses.length === 1 && eqClauses.id !== undefined && typeof eqClauses.id === 'string') {
+        try {
+            const row = await store.get(eqClauses.id);
+            return row ? [row] : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    // Index-aware path: when every clause is equality and exactly one
+    // non-id string column is constrained, hit that column's index for
+    // an O(matches) read. Anything involving LIKE/ILIKE/ranges falls
+    // through to full-scan + filter.
+    if (clausesAreAllEquality(clauses)) {
+        const indexedKeys = Object.keys(eqClauses).filter((k) => k !== 'id' && typeof eqClauses[k] === 'string');
+        if (indexedKeys.length === 1) {
+            const idxKey = indexedKeys[0];
+            try {
+                const rows = await store.getAllFromIndex(idxKey, eqClauses[idxKey]);
+                if (Array.isArray(rows)) {
+                    return rows.filter((r) => matchesClauses(r, clauses));
+                }
+            }
+            catch {
+                // index doesn't exist — fall through to full-scan path.
+            }
+        }
+    }
+    try {
+        const rows = await store.getAll();
+        return Array.isArray(rows)
+            ? rows.filter((r) => matchesClauses(r, clauses))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Normalize `LoadWhere<T>` input to the canonical `readonly WhereClause[]`
+ * tuple form used throughout `runFetch`. Tuple inputs pass through; object
+ * inputs become one `['col', '=', val]` or `['col', 'IN', vals]` per key.
+ *
+ * Detection: an array whose first element is itself an array is treated
+ * as tuple form. Object form is the fallback.
+ *
+ * Exported so callers can pre-normalize (e.g., for tests, or to inspect
+ * the canonical clauses before passing them to `load`/`subscribe`).
+ */
+export function normalizeWhere(where) {
+    if (where == null)
+        return [];
+    if (Array.isArray(where)) {
+        // Tuple form — assumed to already use server-side column names.
+        return where;
+    }
+    if (typeof where === 'object') {
+        const obj = where;
+        return Object.entries(obj).map(([key, value]) => {
+            if (Array.isArray(value)) {
+                return [key, 'IN', value];
+            }
+            return [key, value];
+        });
+    }
+    return [];
+}
+/**
+ * Apply `columnize` to the column name of a wire-bound clause so the
+ * server sees `slide_id` instead of `slideId`. Tuple-form clauses from
+ * callers are passed through unchanged — they already supply the wire
+ * column name (matches what existing `postQuery` consumers do).
+ */
+function columnizeClause(clause) {
+    const col = clause[0];
+    // If the column already looks snake_case (no uppercase letters), assume
+    // the caller is already using server-side naming. Otherwise camelize→snake.
+    const finalCol = /[A-Z]/.test(col) ? columnize(col) : col;
+    if (clause.length === 2)
+        return [finalCol, clause[1]];
+    return [finalCol, clause[1], clause[2]];
+}
+/** Equality-only subset of clauses, keyed by column. Used by IDB fast paths. */
+function extractEqClauses(clauses) {
+    const out = {};
+    for (const c of clauses) {
+        if (c.length === 2) {
+            out[c[0]] = c[1];
+        }
+        else if (c[1] === '=') {
+            out[c[0]] = c[2];
+        }
+    }
+    return out;
+}
+function clausesAreAllEquality(clauses) {
+    return clauses.every((c) => c.length === 2 || c[1] === '=');
+}
+/**
+ * Operator-aware predicate. Mirrors the server's WhereOp semantics for
+ * local matching against pool/IDB rows. LIKE/ILIKE use SQL wildcards
+ * (`%` = any chars, `_` = one char) translated to a JS regex.
+ *
+ * Exported so callers can apply the same predicate to in-memory
+ * collections (tests, batch operations) using the canonical clauses.
+ */
+export function matchesClauses(entity, clauses) {
+    for (const clause of clauses) {
+        const col = clause[0];
+        const op = clause.length === 2 ? '=' : clause[1];
+        const expected = clause.length === 2 ? clause[1] : clause[2];
+        const v = entity[col];
+        if (!matchOp(v, op, expected))
+            return false;
+    }
+    return true;
+}
+function matchOp(actual, op, expected) {
+    switch (op) {
+        case '=':
+            return actual === expected;
+        case '!=':
+            return actual !== expected;
+        case '<':
+            return compareOrdered(actual, expected, (a, b) => a < b);
+        case '<=':
+            return compareOrdered(actual, expected, (a, b) => a <= b);
+        case '>':
+            return compareOrdered(actual, expected, (a, b) => a > b);
+        case '>=':
+            return compareOrdered(actual, expected, (a, b) => a >= b);
+        case 'IN':
+            return Array.isArray(expected) && expected.some((alt) => alt === actual);
+        case 'NOT IN':
+            return Array.isArray(expected) && !expected.some((alt) => alt === actual);
+        case 'IS':
+            // SQL `IS` is null-equality; the only meaningful right-hand side here is null.
+            return actual === expected;
+        case 'IS NOT':
+            return actual !== expected;
+        case 'LIKE':
+            return typeof actual === 'string' && typeof expected === 'string' && likeRegex(expected, false).test(actual);
+        case 'NOT LIKE':
+            return typeof actual === 'string' && typeof expected === 'string' && !likeRegex(expected, false).test(actual);
+        case 'ILIKE':
+            return typeof actual === 'string' && typeof expected === 'string' && likeRegex(expected, true).test(actual);
+        case 'NOT ILIKE':
+            return typeof actual === 'string' && typeof expected === 'string' && !likeRegex(expected, true).test(actual);
+    }
+}
+/**
+ * Ordered comparison helper. Both operands must be non-null and the same
+ * comparable primitive (string-vs-string or number-vs-number). Mixed
+ * types fall back to JS's loose ordering, which would be confusing — so
+ * we reject early to match SQL semantics (a NULL operand yields false).
+ */
+function compareOrdered(actual, expected, cmp) {
+    if (actual == null || expected == null)
+        return false;
+    if (typeof actual === 'number' && typeof expected === 'number') {
+        return cmp(actual, expected);
+    }
+    if (typeof actual === 'string' && typeof expected === 'string') {
+        return cmp(actual, expected);
+    }
+    return false;
+}
+/** Translate a SQL LIKE/ILIKE pattern to a JS regex (`%` → `.*`, `_` → `.`). */
+function likeRegex(pattern, insensitive) {
+    // Escape regex specials *except* `%` and `_`, then translate those.
+    const escaped = pattern.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+    const body = escaped.replace(/%/g, '.*').replace(/_/g, '.');
+    return new RegExp(`^${body}$`, insensitive ? 'i' : '');
+}
+/**
+ * Schema fields are camelCase (`slideId`); the wire query expects
+ * the server-side column name. The query server's input resolver
+ * casing-folds, but we send snake_case to match the convention used
+ * by the existing loaders' postQuery calls (`'slide_id'` etc.).
+ */
+function columnize(field) {
+    return field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}

package/dist/sync/NetworkProbe.d.ts

@@ -0,0 +1,43 @@
+/**
+ * NetworkProbe - Reliable network + session connectivity detection
+ *
+ * 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 + 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
+ *
+ * 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.
+ *
+ * @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;
+    /** Round-trip time in ms (null if failed) */
+    latencyMs: number | 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.
+ *
+ * @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.
+ */
+export declare function probeNetwork(baseUrl?: string): Promise<ProbeResult>;

package/dist/sync/NetworkProbe.js

@@ -0,0 +1,113 @@
+/**
+ * NetworkProbe - Reliable network + session connectivity detection
+ *
+ * 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 + 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
+ *
+ * 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.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
+ */
+import { getContext } from '../context.js';
+import { SyncSessionError } from '../errors.js';
+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`.
+ */
+function resolveProbeUrl(baseUrl) {
+    // Fall back to the legacy env var so callers that haven't been migrated
+    // to pass an explicit baseUrl keep working.
+    const resolved = baseUrl ??
+        (typeof process !== 'undefined' ? process.env?.NEXT_PUBLIC_GO_SERVER_URL : undefined) ??
+        'http://localhost:8080';
+    // Normalize ws → http so fetch() accepts the URL. Strip any trailing slash
+    // so we don't produce `//api/auth/check`.
+    const httpBase = resolved.replace(/^ws/, 'http').replace(/\/+$/, '');
+    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.
+ *
+ * @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.
+ */
+export async function probeNetwork(baseUrl) {
+    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.
+    if (typeof navigator !== 'undefined' && navigator.onLine === false) {
+        return { reachable: false, sessionValid: null, latencyMs: null };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    const start = performance.now();
+    try {
+        const response = await fetch(url, {
+            method: 'HEAD',
+            credentials: 'include', // Send cookies for session check
+            signal: controller.signal,
+            // Cache-bust to avoid stale responses
+            headers: { 'Cache-Control': 'no-cache' },
+        });
+        const latencyMs = Math.round(performance.now() - start);
+        if (SyncSessionError.isSessionErrorResponse(response.status)) {
+            // Server reachable but session expired/invalid
+            getContext().logger.info('[NetworkProbe] Server reachable, session expired', {
+                status: response.status,
+                latencyMs,
+            });
+            return { reachable: true, sessionValid: false, latencyMs };
+        }
+        // 2xx (including 204) means reachable + session valid.
+        // 3xx/4xx (non-auth) still prove connectivity even though the probe
+        // expected 204; log a warning so misconfigurations surface instead of
+        // silently passing.
+        if (response.status < 200 || response.status >= 300) {
+            getContext().logger.warn('[NetworkProbe] Unexpected probe response', {
+                status: response.status,
+                url,
+                latencyMs,
+            });
+        }
+        else {
+            getContext().logger.debug('[NetworkProbe] Server reachable, session valid', {
+                status: response.status,
+                latencyMs,
+            });
+        }
+        return { reachable: true, sessionValid: true, latencyMs };
+    }
+    catch (error) {
+        clearTimeout(timeout);
+        const isAbort = error instanceof DOMException && error.name === 'AbortError';
+        getContext().logger.info('[NetworkProbe] Probe failed', {
+            reason: isAbort ? 'timeout' : error.message,
+        });
+        return { reachable: false, sessionValid: null, latencyMs: null };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/sync/OfflineFlush.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OfflineFlush — Replays queued offline mutations on reconnect.
+ *
+ * SDK-generic version: delegates to MutationDispatcher from context.
+ */
+export declare function flushOfflineQueueOnce(): Promise<{
+    processed: number;
+    failed: number;
+}>;

package/dist/sync/OfflineFlush.js

@@ -0,0 +1,22 @@
+/**
+ * OfflineFlush — Replays queued offline mutations on reconnect.
+ *
+ * SDK-generic version: delegates to MutationDispatcher from context.
+ */
+import { OfflineTransactionStore } from './OfflineTransactionStore.js';
+import { getContext } from '../context.js';
+let _offlineTxStore = null;
+function getOfflineTxStore() {
+    if (!_offlineTxStore) {
+        _offlineTxStore = new OfflineTransactionStore();
+    }
+    return _offlineTxStore;
+}
+export async function flushOfflineQueueOnce() {
+    const store = getOfflineTxStore();
+    await store.init();
+    const dispatcher = getContext().mutationDispatcher;
+    return store.flush(async (tx) => {
+        await dispatcher.dispatch(tx.opName, tx.request.variables || {});
+    });
+}