@abloatai/ablo 0.34.1 → 0.36.0

package/dist/sync/BootstrapFetcher.js

@@ -6,16 +6,117 @@
  * cached snapshot when the device is offline. {@link BootstrapData} is the
  * shape it returns; {@link BootstrapOptions} configures it.
  */
-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 { globalRuntime } from '../context.js';
+import { AbloError, AbloSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '../transaction/errors.js';
+import { withAuthHeaders } from '../transaction/auth/credentialSource.js';
+import { classifySchemaDrift, describeSchemaDrift, } from './schemaDrift.js';
+// SyncObservability replaced by this.runtime.observability
 import { parseBootstrapResponse } from './schemas.js';
+/**
+ * Rows per page for the chunked cold-start bootstrap. Matches the server's
+ * hard cap on the `limit` query parameter — asking for more is silently
+ * clamped, so this is the largest honest page.
+ */
+const PAGE_LIMIT = 5000;
+/**
+ * Runaway guard for the per-model paging loop: a server that keeps returning
+ * a `nextCursor` past this many pages is looping, not paginating. At
+ * {@link PAGE_LIMIT} rows per page this allows a million rows per model
+ * before the loop is declared broken.
+ */
+const MAX_PAGES_PER_MODEL = 200;
+/** How many model chunks a cold start fetches at once. */
+const CHUNK_CONCURRENCY = 3;
+/**
+ * The reason handed to `abort()` when a request is stopped deliberately —
+ * superseded by a newer bootstrap, or abandoned because the bootstrap it
+ * belonged to had already failed elsewhere.
+ */
+const cancelled = (why) => new AbloConnectionError(why, { code: 'bootstrap_cancelled' });
+/** Matches by `name` rather than `instanceof`: an abort that crosses a worker
+ *  boundary is structured-cloned, which drops the prototype. */
+const isAbortError = (value) => typeof value === 'object' &&
+    value !== null &&
+    'name' in value &&
+    value.name === 'AbortError';
+/**
+ * What a failed request should report.
+ *
+ * A fetch aborted *with a reason* rejects with that exact reason object, so a
+ * deliberate cancellation and a watchdog firing both arrive here already typed
+ * and pass straight through — which is the whole point of passing one. Only a
+ * bare abort needs translating: a signal aborted with no reason, the browser's
+ * stop button, a closing tab. That case is the one that genuinely means the
+ * transfer died, so it becomes a retryable timeout.
+ *
+ * The signal's reason is preferred over the thrown value because a pre-aborted
+ * signal rejects before any request is made, and because interior code may have
+ * wrapped the rejection on its way out.
+ */
+function classifyRequestFailure(error, controller, diedMessage) {
+    const reason = controller.signal.aborted ? controller.signal.reason : error;
+    if (reason instanceof AbloError)
+        return reason;
+    if (isAbortError(reason)) {
+        return new AbloConnectionError(diedMessage, {
+            code: 'bootstrap_fetch_timeout',
+            ...(reason instanceof Error ? { cause: reason } : {}),
+        });
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
 export class BootstrapFetcher {
     options;
-    abortController = null;
+    runtime;
+    /**
+     * Every in-flight request's controller, tagged with the lane it belongs to. A
+     * registry rather than a single field because a chunked cold start runs
+     * several model fetches concurrently — aborting one request (its own
+     * TTFB/stall watchdog) must never take its siblings down, while
+     * {@link abort} takes down all of them.
+     */
+    activeControllers = new Map();
+    /**
+     * Non-scoped bootstraps currently running, keyed by request identity. A
+     * second call for the same snapshot joins the one already in flight rather
+     * than cancelling and restarting it — see {@link fetchBootstrap}.
+     */
+    flights = new Map();
     /** Warn about schema drift at most once per helper. */
     schemaDriftWarned = false;
+    /**
+     * Abort every in-flight request in `lane` — or in every lane when none is
+     * given — with an explicit reason.
+     *
+     * The reason is load-bearing, not decoration. `fetch` rejects with the exact
+     * value handed to `abort()`, so passing a typed error is what lets the retry
+     * loop below tell a deliberate cancellation apart from a dead connection. A
+     * bare `abort()` produces an `AbortError` indistinguishable from the one the
+     * browser's stop button produces, and a retry loop that cannot tell them
+     * apart re-issues the requests it just killed.
+     */
+    cancelActive(reason, lane) {
+        for (const [controller, controllerLane] of this.activeControllers) {
+            if (lane !== undefined && controllerLane !== lane)
+                continue;
+            controller.abort(reason);
+            this.activeControllers.delete(controller);
+        }
+    }
+    /**
+     * The longest a single bootstrap can run before every watchdog below has
+     * necessarily fired, derived from those watchdogs rather than guessed. A
+     * caller wanting an outer deadline reads this instead of picking a number,
+     * so it cannot set one shorter than the work it wraps. A cold start pages
+     * through its models {@link CHUNK_CONCURRENCY} at a time; each request may
+     * spend `fetchTimeout` waiting for response headers and `stallTimeout`
+     * waiting for the next body chunk, and may be retried `maxRetries` times.
+     */
+    get budgetMs() {
+        const models = Math.max(this.options.instantModels?.length ?? 1, 1);
+        const waves = Math.ceil(models / CHUNK_CONCURRENCY);
+        return (waves * (this.options.fetchTimeout + this.options.stallTimeout) * this.options.maxRetries);
+    }
     get baseUrl() {
         return this.options.baseUrl;
     }
@@ -39,24 +140,78 @@ export class BootstrapFetcher {
     warnOnSchemaDrift(serverHash) {
         if (this.schemaDriftWarned || !serverHash)
             return;
-        const clientHash = getContext().config.expectedSchemaHash;
+        const clientHash = this.runtime.config.expectedSchemaHash;
         if (!clientHash || clientHash === serverHash)
             return;
         // A projection (`selectModels`/`omitModels`) hashes its subset, which never
         // equals the full schema a server runs — so it also carries the source
         // schema's hash. Matching that means the client is a faithful subset of the
         // deployed schema: current, not drifted. Only warn when neither matches.
-        const sourceHash = getContext().config.expectedSourceSchemaHash;
+        const sourceHash = this.runtime.config.expectedSourceSchemaHash;
         if (sourceHash && sourceHash === serverHash)
             return;
         this.schemaDriftWarned = true;
         const org = this.options.organizationId;
         const where = org ? `${this.baseUrl} (org ${org})` : this.baseUrl;
+        // The whole-schema hashes differ — but that alone can't distinguish "the
+        // server gained models this build never touches" (fine, say nothing) from
+        // "a model this client uses moved" (name it). Resolve the semantic answer
+        // from the server's per-model surface before speaking; fall back to the
+        // hash message only when that surface is unavailable (older server,
+        // network hiccup). Fire-and-forget: never blocks or fails the bootstrap.
+        const clientModels = this.runtime.config.expectedModelHashes;
+        if (clientModels && Object.keys(clientModels).length > 0) {
+            void this.resolveSemanticDrift(clientModels, clientHash, serverHash, where);
+            return;
+        }
+        this.warnWholeHashDrift(clientHash, serverHash, where);
+    }
+    /** Fetch the server's per-model schema surface and warn precisely — or stay
+     *  silent when every model this client declares matches (additive lead). */
+    async resolveSemanticDrift(clientModels, clientHash, serverHash, where) {
+        try {
+            const res = await fetch(`${this.options.baseUrl}/schema`, {
+                method: 'GET',
+                headers: withAuthHeaders(this.options.getAuthToken, {}, this.options.authToken),
+            });
+            if (!res.ok)
+                throw new Error(`schema read-back ${res.status}`);
+            const body = (await res.json());
+            const models = Array.isArray(body.models)
+                ? body.models.flatMap((m) => {
+                    const entry = m;
+                    return typeof entry.key === 'string'
+                        ? [{ key: entry.key, ...(typeof entry.hash === 'string' ? { hash: entry.hash } : {}) }]
+                        : [];
+                })
+                : [];
+            const finding = classifySchemaDrift(clientModels, models);
+            if (finding.kind === 'aligned')
+                return; // additive server lead — not this client's concern
+            if (finding.kind !== 'unknown') {
+                this.runtime.logger.warn(describeSchemaDrift(finding, where), {
+                    clientSchemaHash: clientHash,
+                    serverSchemaHash: serverHash,
+                    serverUrl: this.baseUrl,
+                    ...(finding.kind === 'unpushed'
+                        ? { unpushedModels: finding.models }
+                        : { changedModels: finding.models, unpushedModels: finding.unpushed }),
+                });
+                return;
+            }
+        }
+        catch {
+            /* surface unavailable — fall through to the hash message */
+        }
+        this.warnWholeHashDrift(clientHash, serverHash, where);
+    }
+    warnWholeHashDrift(clientHash, serverHash, where) {
+        const org = this.options.organizationId;
         // Self-brand the message ("Ablo:") rather than rely on the default logger's
         // `[Ablo]` namespace — consumers wiring their own logger (pino, etc.) lose
         // that prefix, and a drift warning that reads like the app's own log is
         // worse than none. The brand tells them at a glance who is talking.
-        getContext().logger.warn(`Ablo: Schema drift — the schema this client was built with (${clientHash}) is not the ` +
+        this.runtime.logger.warn(`Ablo: Schema drift — the schema this client was built with (${clientHash}) is not the ` +
             `one active on the server it connected to (${serverHash} at ${where}). Until they match, ` +
             `operations that depend on the difference will fail later with an opaque database error. ` +
             `This is usually one of three things. The schema may have been pushed to a different ` +
@@ -73,6 +228,7 @@ export class BootstrapFetcher {
         });
     }
     constructor(options) {
+        this.runtime = options.runtime ?? globalRuntime;
         // Defaults are spread first; the explicit `baseUrl` then takes precedence,
         // resolved from `options.baseUrl` or the localhost fallback. Callers pass
         // the full base URL, including the `/api` prefix.
@@ -80,7 +236,11 @@ export class BootstrapFetcher {
             syncGroups: [],
             maxRetries: 3,
             retryDelay: 1000,
-            fetchTimeout: 10_000, // 10 second timeout per request - fail fast for good UX
+            // Time-to-first-byte bound only. The server currently materializes the
+            // whole snapshot before sending headers, so a cold start on a large org
+            // legitimately needs more than a "fail fast" allowance here.
+            fetchTimeout: 20_000,
+            stallTimeout: 15_000,
             ...options,
             baseUrl: options.baseUrl ?? 'http://localhost:8080/api',
             // Reading the deprecated `organizationId` is deliberate: it preserves the
@@ -129,6 +289,56 @@ export class BootstrapFetcher {
      * request.
      */
     syncGroupsOverride) {
+        // A scoped hydrate answers a different question than the full bootstrap and
+        // runs in its own lane: it never joins one, and is never superseded by one.
+        if (syncGroupsOverride)
+            return this.runBootstrap(lastSyncId, syncGroupsOverride);
+        // Single-flight. Three callers reach this independently — first load,
+        // background refresh, and reconnect — and before this they raced: each new
+        // call cancelled whatever was running and started over, so a socket that
+        // reconnected mid-cold-start restarted the whole snapshot, repeatedly. The
+        // same request now joins the one in flight instead.
+        const key = this.flightKey(lastSyncId);
+        const joined = this.flights.get(key);
+        if (joined) {
+            this.runtime.logger.debug('Joining the bootstrap already in flight', { key });
+            return joined;
+        }
+        // A request for something else genuinely does supersede: the running one is
+        // not the answer being asked for. Retire it from the registry first, so a
+        // caller arriving in the same tick cannot join a flight that is dying.
+        if (this.flights.size > 0) {
+            this.flights.clear();
+            this.cancelActive(cancelled('Superseded by a newer bootstrap request'), 'bootstrap');
+        }
+        const flight = this.runBootstrap(lastSyncId);
+        this.flights.set(key, flight);
+        // The cleanup chain is terminated with `catch` so this derived promise can
+        // never surface as an unhandled rejection even when every caller handled the
+        // failure, and the delete is guarded by identity so a flight registered
+        // after a supersede is not evicted by its predecessor's cleanup.
+        void flight
+            .catch(() => undefined)
+            .finally(() => {
+            if (this.flights.get(key) === flight)
+                this.flights.delete(key);
+        });
+        return flight;
+    }
+    /**
+     * The identity of a bootstrap request: everything that determines its answer.
+     * Two calls with the same key are asking the same question, so the second can
+     * take the first's result.
+     */
+    flightKey(lastSyncId) {
+        return JSON.stringify({
+            lastSyncId: lastSyncId !== undefined && lastSyncId > 0 ? lastSyncId : 0,
+            syncGroups: [...this.options.syncGroups].sort(),
+            models: [...(this.options.instantModels ?? [])].sort(),
+        });
+    }
+    /** One bootstrap, start to finish. {@link fetchBootstrap} owns whether it runs. */
+    async runBootstrap(lastSyncId, syncGroupsOverride) {
         // organizationId omitted — server reads it from auth identity.
         // See `fetchBootstrapWithETag` for the full rationale.
         const params = new URLSearchParams();
@@ -164,39 +374,87 @@ export class BootstrapFetcher {
                 ? this.loadCachedBootstrap(this.options.cacheScope)
                 : null;
             if (cached) {
-                getContext().logger.info('Using cached bootstrap (offline)');
+                this.runtime.logger.info('Using cached bootstrap (offline)');
                 return cached;
             }
             throw new AbloConnectionError('Offline and no cached bootstrap available', {
                 code: 'bootstrap_offline_no_cache',
             });
         }
-        getContext().logger.info('Fetching fresh bootstrap data', { url });
-        // Fetch with retries
+        this.runtime.logger.info('Fetching fresh bootstrap data', { url });
+        const lane = syncGroupsOverride ? 'scoped' : 'bootstrap';
+        // Chunk a COLD start by model: each instant model is its own request, so
+        // one giant model can't make the whole snapshot undeliverable, and a
+        // dropped connection costs one model, not everything. Each chunk is
+        // consistent at its own sync position; the merge anchors at the MINIMUM
+        // position, and the regular WS catch-up (`sync_request` → delta replay)
+        // closes the skew — full-row deltas make the overlapping re-apply
+        // convergent. Warm partials, scoped hydrates, and clients without a
+        // model list (server returns everything) stay on the single request.
+        const instantModels = this.options.instantModels ?? [];
+        const chunked = (lastSyncId === undefined || lastSyncId <= 0) &&
+            !syncGroupsOverride &&
+            instantModels.length > 1;
+        try {
+            const data = chunked
+                ? await this.fetchChunkedBootstrap(instantModels, this.options.syncGroups)
+                : await this.fetchWithRetries(url, lane);
+            this.runtime.logger.info('Bootstrap data fetched', {
+                type: data.type,
+                lastSyncId: data.lastSyncId,
+                chunked,
+                modelCount: data.models ? Object.keys(data.models).length : 0,
+                deltaCount: data.deltaCount ?? 0,
+                totalItems: data.models
+                    ? Object.values(data.models).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0)
+                    : 0,
+            });
+            // Persist for offline fallback
+            if (this.options.cacheScope) {
+                this.saveCachedBootstrap(this.options.cacheScope, data);
+            }
+            return data;
+        }
+        catch (error) {
+            // Session and non-retryable errors already failed fast inside the
+            // retry loop; they must ALSO skip the cached fallback (a stale
+            // snapshot is not an answer to "your credential is invalid").
+            if (AbloSessionError.isSessionError(error)) {
+                throw error;
+            }
+            const ablo = toAbloError(error);
+            if (ablo.code && !isRetryableCode(ablo.code)) {
+                throw ablo;
+            }
+            // Transient failure after exhausting retries → cached fallback.
+            const cached = this.options.cacheScope
+                ? this.loadCachedBootstrap(this.options.cacheScope)
+                : null;
+            if (cached) {
+                this.runtime.observability.breadcrumb('Bootstrap cache fallback', 'sync.bootstrap', 'warning', {
+                    error: ablo.message,
+                });
+                return cached;
+            }
+            throw ablo;
+        }
+    }
+    /**
+     * One bootstrap URL, fetched with backoff. Session errors and other
+     * non-retryable failures throw immediately; only transient failures
+     * (5xx, 429, timeouts, network blips) consume attempts. A cancellation is
+     * deliberate and therefore non-retryable — it leaves through the same gate.
+     */
+    async fetchWithRetries(url, lane) {
         let lastError = null;
         for (let attempt = 0; attempt < this.options.maxRetries; attempt++) {
             try {
-                const data = await this.performFetch(url);
-                getContext().logger.info('Bootstrap data fetched', {
-                    type: data.type,
-                    lastSyncId: data.lastSyncId,
-                    modelCount: data.models ? Object.keys(data.models).length : 0,
-                    deltaCount: data.deltaCount ?? 0,
-                    totalItems: data.models
-                        ? Object.values(data.models).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0)
-                        : 0,
-                });
-                // Persist for offline fallback
-                if (this.options.cacheScope) {
-                    this.saveCachedBootstrap(this.options.cacheScope, data);
-                }
-                return data;
+                return await this.fetchOnce(url, lane);
             }
             catch (error) {
                 // SessionError should NOT be retried - the session is invalid and needs re-authentication
-                // Also do NOT fallback to cache - the user must sign in again
-                if (SyncSessionError.isSessionError(error)) {
-                    getContext().observability.breadcrumb('Bootstrap session error - redirecting to sign-in', 'sync.bootstrap', 'warning', {
+                if (AbloSessionError.isSessionError(error)) {
+                    this.runtime.observability.breadcrumb('Bootstrap session error - redirecting to sign-in', 'sync.bootstrap', 'warning', {
                         statusCode: (error).statusCode,
                     });
                     throw error;
@@ -209,11 +467,11 @@ export class BootstrapFetcher {
                 // unclassified error with no code) flow through to the retry/backoff.
                 const ablo = toAbloError(error);
                 if (ablo.code && !isRetryableCode(ablo.code)) {
-                    getContext().observability.breadcrumb('Bootstrap non-retryable error — failing fast', 'sync.bootstrap', 'warning', { code: ablo.code, httpStatus: ablo.httpStatus });
+                    this.runtime.observability.breadcrumb('Bootstrap non-retryable error — failing fast', 'sync.bootstrap', 'warning', { code: ablo.code, httpStatus: ablo.httpStatus });
                     throw ablo;
                 }
                 lastError = error;
-                getContext().observability.breadcrumb('Bootstrap fetch failed', 'sync.bootstrap', 'warning', {
+                this.runtime.observability.breadcrumb('Bootstrap fetch failed', 'sync.bootstrap', 'warning', {
                     attempt: attempt + 1,
                 });
                 if (attempt < this.options.maxRetries - 1) {
@@ -221,22 +479,78 @@ export class BootstrapFetcher {
                 }
             }
         }
-        // On error, attempt cached fallback (but NOT for session errors - already handled above)
-        const cached = this.options.cacheScope
-            ? this.loadCachedBootstrap(this.options.cacheScope)
-            : null;
-        if (cached) {
-            getContext().observability.breadcrumb('Bootstrap cache fallback', 'sync.bootstrap', 'warning', {
-                error: lastError?.message,
-            });
-            return cached;
-        }
         throw lastError
             ? toAbloError(lastError)
             : new AbloConnectionError('Failed to fetch bootstrap data', {
                 code: 'bootstrap_fetch_timeout',
             });
     }
+    /**
+     * Cold-start bootstrap, one request per instant model with a small
+     * concurrency cap. Any chunk's terminal failure fails the whole
+     * bootstrap (a partial snapshot must never masquerade as a full one)
+     * and cancels its siblings.
+     */
+    async fetchChunkedBootstrap(models, syncGroups) {
+        this.runtime.logger.info('Bootstrap chunked by model', {
+            models: models.length,
+        });
+        const queue = [...models];
+        const chunks = [];
+        // Shared by the concurrent workers below, so it is deliberately re-read
+        // after `await` points where a sibling may have set it. Held on an object
+        // rather than in a `let`: the guard inside the worker narrows a plain
+        // binding to `null` for the rest of the loop body, and the compiler has no
+        // way to know a sibling can overwrite it mid-await.
+        const firstFailure = { error: null };
+        const worker = async () => {
+            for (;;) {
+                const model = queue.shift();
+                if (model === undefined || firstFailure.error !== null)
+                    return;
+                try {
+                    // Page through the model: each request is bounded to PAGE_LIMIT
+                    // rows, so no single response grows with the model's size. A
+                    // server without paging ignores `limit` and returns the whole
+                    // model with no nextCursor — one page, previous behavior.
+                    let cursor;
+                    for (let pageNo = 0;; pageNo++) {
+                        if (pageNo >= MAX_PAGES_PER_MODEL) {
+                            throw new AbloConnectionError(`Bootstrap for model "${model}" exceeded ${MAX_PAGES_PER_MODEL} pages — the server keeps returning a next page`, { code: 'bootstrap_fetch_timeout' });
+                        }
+                        const params = new URLSearchParams();
+                        syncGroups.forEach((group) => {
+                            params.append('syncGroups', group);
+                        });
+                        params.append('models', model);
+                        params.append('limit', String(PAGE_LIMIT));
+                        if (cursor !== undefined)
+                            params.append('cursor', cursor);
+                        const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
+                        const data = await this.fetchWithRetries(url, 'bootstrap');
+                        chunks.push(data);
+                        if (data.nextCursor === undefined)
+                            break;
+                        cursor = data.nextCursor;
+                    }
+                }
+                catch (error) {
+                    // First failure wins — a later sibling's error must not mask it.
+                    firstFailure.error ??=
+                        error instanceof Error ? error : new Error(String(error));
+                    // The siblings are abandoned, not broken: the snapshot they belong to
+                    // is already lost. Saying so in the abort reason is what keeps each
+                    // of them from retrying a request nobody is waiting for any more.
+                    this.cancelActive(cancelled(`Abandoned: the bootstrap chunk for "${model}" failed`), 'bootstrap');
+                    return;
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(CHUNK_CONCURRENCY, models.length) }, worker));
+        if (firstFailure.error !== null)
+            throw firstFailure.error;
+        return mergeBootstrapChunks(chunks);
+    }
     /**
      * Fetch bootstrap with ETag, returning 304 hints
      */
@@ -257,16 +571,25 @@ export class BootstrapFetcher {
         // level where they own the cache-key namespace. The 304 branch below
         // remains defensively in place for when a caller enables revalidation.
         const headers = withAuthHeaders(this.options.getAuthToken, { 'Content-Type': 'application/json' }, this.options.authToken);
-        this.abortController = new AbortController();
+        const controller = new AbortController();
+        this.activeControllers.set(controller, 'bootstrap');
+        try {
+            return await this.fetchWithETagUsing(url, headers, controller);
+        }
+        finally {
+            this.activeControllers.delete(controller);
+        }
+    }
+    async fetchWithETagUsing(url, headers, controller) {
         const res = await fetch(url, {
             method: 'GET',
             headers,
-            signal: this.abortController.signal,
+            signal: controller.signal,
         });
         const etag = res.headers.get('ETag');
         if (res.status === 304) {
             // Log for telemetry
-            getContext().logger.info('[Bootstrap] 304 Not Modified - using cached data');
+            this.runtime.logger.info('[Bootstrap] 304 Not Modified - using cached data');
             return { notModified: true, etag };
         }
         if (!res.ok) {
@@ -296,11 +619,11 @@ export class BootstrapFetcher {
                 translated.code === 'jwt_expired' ||
                 ((res.status === 401 || res.status === 403) &&
                     translated.code === undefined)) {
-                throw new SyncSessionError(translated.message, res.status);
+                throw new AbloSessionError(translated.message, res.status);
             }
             throw translated;
         }
-        const data = parseBootstrapResponse(await res.json());
+        const data = parseBootstrapResponse(await this.readJsonWithStallGuard(res, controller), this.runtime);
         this.warnOnSchemaDrift(data.schemaHash);
         // Persist payload for offline
         try {
@@ -312,23 +635,100 @@ export class BootstrapFetcher {
             // Offline persistence is best-effort; a failed cache write must not
             // block returning the freshly fetched data.
         }
-        getContext().logger.info('[Bootstrap] 200 OK - received new data');
+        this.runtime.logger.info('[Bootstrap] 200 OK - received new data');
         return { notModified: false, data, etag };
     }
     /**
-     * Perform the actual fetch request with timeout protection
+     * Read a response body as a stream under a progress watchdog: the stall
+     * timer re-arms on every chunk, so only a silent stream is aborted — a
+     * slow-but-moving download is never killed for total duration. A cold-start
+     * snapshot can be tens of megabytes; bounding its total transfer time was
+     * what trapped large orgs in an endless full-bootstrap retry loop.
+     *
+     * Falls back to `response.json()` when the response exposes no readable
+     * stream (empty bodies, some test doubles).
      */
-    async performFetch(url) {
-        // Cancel any previous in-flight request
-        if (this.abortController) {
-            this.abortController.abort();
+    async readJsonWithStallGuard(response, controller) {
+        const body = response.body;
+        if (!body)
+            return response.json();
+        const reader = body.getReader();
+        const chunks = [];
+        let receivedBytes = 0;
+        let stallTimer;
+        // The watchdog must not depend on the stream being wired to the fetch
+        // signal (that plumbing is implementation-specific), so a stall races a
+        // rejection against each read instead of only aborting the controller.
+        let stallReject;
+        const stalled = new Promise((_, reject) => {
+            stallReject = reject;
+        });
+        // A stall can fire in the microtask gap between two read races; without a
+        // standing handler that would surface as an unhandled rejection.
+        stalled.catch(() => undefined);
+        const armStallTimer = () => {
+            clearTimeout(stallTimer);
+            stallTimer = setTimeout(() => {
+                this.runtime.observability.breadcrumb('Bootstrap download stalled', 'sync.bootstrap', 'warning', { receivedBytes, stallTimeoutMs: this.options.stallTimeout });
+                const stallError = new AbloConnectionError(`Bootstrap download stalled: no data received for ${this.options.stallTimeout}ms (${receivedBytes} bytes arrived before the stream went quiet)`, { code: 'bootstrap_fetch_timeout' });
+                stallReject?.(stallError);
+                // Then tear the transfer down: abort frees the socket under real
+                // fetch; cancel unblocks readers on streams not wired to the signal.
+                // Both carry the same error, so whichever path wins the race below
+                // reports one message rather than two descriptions of one stall.
+                controller.abort(stallError);
+                void reader.cancel().catch(() => undefined);
+            }, this.options.stallTimeout);
+        };
+        try {
+            armStallTimer();
+            for (;;) {
+                const { done, value } = await Promise.race([reader.read(), stalled]);
+                if (done)
+                    break;
+                chunks.push(value);
+                receivedBytes += value.byteLength;
+                armStallTimer();
+            }
+        }
+        catch (error) {
+            throw classifyRequestFailure(error, controller, `Bootstrap download aborted after ${receivedBytes} bytes`);
+        }
+        finally {
+            clearTimeout(stallTimer);
         }
-        this.abortController = new AbortController();
+        const bytes = new Uint8Array(receivedBytes);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    /**
+     * Perform one fetch. The timeout here bounds time to response headers
+     * only; the body download is guarded by the stall watchdog in
+     * {@link readJsonWithStallGuard}. Superseding an older in-flight
+     * bootstrap is the caller's job ({@link fetchBootstrap} cancels the
+     * registry) — chunk requests run through here concurrently and must
+     * not cancel each other.
+     */
+    async fetchOnce(url, lane) {
+        const controller = new AbortController();
+        this.activeControllers.set(controller, lane);
+        try {
+            return await this.fetchOnceWith(url, controller);
+        }
+        finally {
+            this.activeControllers.delete(controller);
+        }
+    }
+    async fetchOnceWith(url, controller) {
         const timeoutId = setTimeout(() => {
-            getContext().observability.breadcrumb('Bootstrap fetch timeout', 'sync.bootstrap', 'warning', {
+            this.runtime.observability.breadcrumb('Bootstrap fetch timeout', 'sync.bootstrap', 'warning', {
                 timeoutMs: this.options.fetchTimeout,
             });
-            this.abortController?.abort();
+            controller.abort(new AbloConnectionError(`Bootstrap fetch timed out after ${this.options.fetchTimeout}ms waiting for the server to respond`, { code: 'bootstrap_fetch_timeout' }));
         }, this.options.fetchTimeout);
         let response;
         try {
@@ -339,17 +739,13 @@ export class BootstrapFetcher {
                     'Cache-Control': 'no-cache, no-store, must-revalidate',
                     Pragma: 'no-cache',
                 }, this.options.authToken),
-                signal: this.abortController.signal,
+                signal: controller.signal,
                 cache: 'no-store', // Force browser to not cache
             });
         }
         catch (error) {
             clearTimeout(timeoutId);
-            // Convert abort to timeout error for better error messaging
-            if (error instanceof Error && error.name === 'AbortError') {
-                throw new AbloConnectionError(`Bootstrap fetch timed out after ${this.options.fetchTimeout}ms`, { code: 'bootstrap_fetch_timeout', cause: error });
-            }
-            throw error;
+            throw classifyRequestFailure(error, controller, 'The bootstrap request was aborted before the server responded');
         }
         clearTimeout(timeoutId);
         if (!response.ok) {
@@ -373,22 +769,14 @@ export class BootstrapFetcher {
                 translated.code === 'jwt_expired' ||
                 ((response.status === 401 || response.status === 403) &&
                     translated.code === undefined)) {
-                throw new SyncSessionError(translated.message, response.status);
+                throw new AbloSessionError(translated.message, response.status);
             }
             throw translated;
         }
-        const data = parseBootstrapResponse(await response.json());
+        const data = parseBootstrapResponse(await this.readJsonWithStallGuard(response, controller), this.runtime);
         this.warnOnSchemaDrift(data.schemaHash);
-        // Save a copy for offline
-        try {
-            if (this.options.cacheScope) {
-                this.saveCachedBootstrap(this.options.cacheScope, data);
-            }
-        }
-        catch {
-            // Offline persistence is best-effort; a failed cache write must not
-            // block returning the freshly fetched data.
-        }
+        // Offline caching happens in `fetchBootstrap` on the assembled result —
+        // caching here would let a single-model chunk overwrite the full snapshot.
         return data;
     }
     /**
@@ -462,11 +850,11 @@ export class BootstrapFetcher {
             }
             keysToRemove.forEach((key) => {
                 localStorage.removeItem(key);
-                getContext().logger.debug('Cleared cache key', { key });
+                this.runtime.logger.debug('Cleared cache key', { key });
             });
         }
         catch (error) {
-            getContext().logger.debug('Failed to clear cache', { error });
+            this.runtime.logger.debug('Failed to clear cache', { error });
         }
     }
     // Cache helpers for offline bootstrap
@@ -480,7 +868,7 @@ export class BootstrapFetcher {
             localStorage.setItem(this.getBootstrapCacheKey(orgId), JSON.stringify(data));
         }
         catch (e) {
-            getContext().logger.debug('Failed to cache bootstrap payload', {
+            this.runtime.logger.debug('Failed to cache bootstrap payload', {
                 error: e instanceof Error ? e.message : String(e),
             });
         }
@@ -499,13 +887,16 @@ export class BootstrapFetcher {
         }
     }
     /**
-     * Abort ongoing fetch request
+     * Abort every ongoing bootstrap request (including all chunks of a
+     * chunked cold start). Entity self-heal fetches are unaffected.
+     *
+     * The flight registry is cleared first and synchronously, so a caller that
+     * bootstraps again in the same tick starts a fresh request rather than
+     * joining the one being torn down.
      */
     abort() {
-        if (this.abortController) {
-            this.abortController.abort();
-            this.abortController = null;
-        }
+        this.flights.clear();
+        this.cancelActive(cancelled('Bootstrap aborted by its caller'));
     }
     /**
      * Helper to delay execution
@@ -529,8 +920,45 @@ export class BootstrapFetcher {
             return body.status === 'healthy';
         }
         catch {
-            getContext().observability.breadcrumb('Health check failed', 'sync.bootstrap', 'warning');
+            this.runtime.observability.breadcrumb('Health check failed', 'sync.bootstrap', 'warning');
             return false;
         }
     }
 }
+/**
+ * Assemble per-model chunk responses into one full snapshot.
+ *
+ * Each chunk is internally consistent at its own sync position, and the
+ * positions differ (the chunks were served seconds apart). Anchoring the
+ * merged snapshot at the MINIMUM position turns that skew into an ordinary
+ * "briefly offline client": the WS catch-up replays every delta from the
+ * anchor, and since deltas carry full rows, re-applying one a later chunk
+ * already reflects converges to the same state. Anchoring at anything later
+ * would silently skip deltas for the earliest-fetched models.
+ */
+export function mergeBootstrapChunks(chunks) {
+    const models = {};
+    const failedModels = [];
+    let lastSyncId = Number.POSITIVE_INFINITY;
+    let timestamp = 0;
+    let schemaHash;
+    for (const chunk of chunks) {
+        // Concatenate per model: pages of one model arrive as separate chunks.
+        for (const [name, rows] of Object.entries(chunk.models ?? {})) {
+            (models[name] ??= []).push(...rows);
+        }
+        if (chunk.failedModels)
+            failedModels.push(...chunk.failedModels);
+        lastSyncId = Math.min(lastSyncId, chunk.lastSyncId);
+        timestamp = Math.max(timestamp, chunk.timestamp);
+        schemaHash ??= chunk.schemaHash;
+    }
+    return {
+        type: 'full',
+        lastSyncId: Number.isFinite(lastSyncId) ? lastSyncId : 0,
+        models,
+        ...(failedModels.length > 0 ? { failedModels } : {}),
+        timestamp,
+        ...(schemaHash !== undefined ? { schemaHash } : {}),
+    };
+}