@abloatai/ablo 0.36.0 → 0.37.0

package/dist/sync/BootstrapFetcher.js

@@ -1,964 +0,0 @@
-/**
- * Fetches the initial snapshot the sync engine needs before it can go live: the
- * current rows for the requested models plus the sync position from which to
- * resume live updates. It calls the sync server's `/sync/bootstrap` HTTP
- * endpoint, retries transient failures with backoff, and can fall back to a
- * cached snapshot when the device is offline. {@link BootstrapData} is the
- * shape it returns; {@link BootstrapOptions} configures it.
- */
-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;
-    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;
-    }
-    /**
-     * Advisory schema-drift check: compare the server's active schema hash (on the
-     * bootstrap response) against the hash this client was built with. A mismatch
-     * means the app's schema and the deployed schema have diverged — reads/writes
-     * relying on undeployed changes will later fail with an opaque DB constraint
-     * error. Warn once, actionably; never throws or blocks the bootstrap.
-     *
-     * The message names the SERVER it connected to, and spans all three real
-     * causes rather than assuming "you forgot to push". Drift most often means the
-     * schema was pushed to a different server, project, or environment than this
-     * client points at (a bare `ablo push` targets the hosted default; a local app
-     * usually reads a local server) — so the first, load-bearing pointer is `ablo
-     * status`, which names the exact org/project/environment the key resolves to
-     * and the deployed hash, turning "which of these is it?" into one glance. The
-     * older "Run `ablo push`" copy sent everyone down one path and confused the
-     * common wrong-target and version-skew cases.
-     */
-    warnOnSchemaDrift(serverHash) {
-        if (this.schemaDriftWarned || !serverHash)
-            return;
-        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 = 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.
-        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 ` +
-            `server, project, or environment than this client points at — run \`ablo status\` to see ` +
-            `the exact org, project, and environment your key resolves to, alongside the deployed ` +
-            `hash, and confirm they match here. Your local schema may simply not be pushed to this ` +
-            `server yet — run \`ablo push\` against it. Or this client and the server may have been ` +
-            `built with different Ablo versions, which can hash an identical schema differently — ` +
-            `align the versions. This check is advisory and never blocks the connection.`, {
-            clientSchemaHash: clientHash,
-            serverSchemaHash: serverHash,
-            serverUrl: this.baseUrl,
-            ...(org ? { organizationId: org } : {}),
-        });
-    }
-    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.
-        this.options = {
-            syncGroups: [],
-            maxRetries: 3,
-            retryDelay: 1000,
-            // 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
-            // cache namespace for callers that still construct BootstrapFetcher
-            // directly with the old field instead of `cacheScope`.
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            cacheScope: options.cacheScope ?? options.organizationId ?? null,
-        };
-        // Do not clear cache here; keep offline fallback available
-    }
-    /**
-     * Update the offline-cache namespace once auth has resolved the server-side
-     * account scope. This is intentionally not a public organizationId input.
-     */
-    setCacheScope(cacheScope) {
-        if (cacheScope.trim().length === 0)
-            return;
-        this.options.cacheScope = cacheScope;
-    }
-    setSyncGroups(syncGroups) {
-        this.options.syncGroups = [...(syncGroups ?? [])];
-    }
-    /**
-     * Sets a fixed credential for callers that construct the helper directly.
-     * The SDK instead supplies `getAuthToken` and never calls this.
-     */
-    setAuthToken(authToken) {
-        if (!authToken) {
-            delete this.options.authToken;
-            return;
-        }
-        this.options.authToken = authToken;
-    }
-    /**
-     * Fetch bootstrap data from sync engine with partial bootstrap support
-     * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
-     * @returns Bootstrap data (either full snapshot or delta batch)
-     */
-    async fetchBootstrap(lastSyncId, 
-    /**
-     * A per-call set of sync groups for a scoped hydrate-on-enter. When given,
-     * the request uses these groups instead of the configured `syncGroups`, and
-     * does so without mutating the shared options, so a concurrent full
-     * bootstrap is unaffected. It also bypasses the offline snapshot cache,
-     * which holds the full bootstrap and would be a wrong answer to a subset
-     * 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();
-        // Add lastSyncId for partial bootstrap support
-        if (lastSyncId !== undefined && lastSyncId > 0) {
-            params.append('lastSyncId', lastSyncId.toString());
-        }
-        // Add sync groups (per-call override wins over the configured set).
-        (syncGroupsOverride ?? this.options.syncGroups).forEach((group) => {
-            params.append('syncGroups', group);
-        });
-        // Selective bootstrap: only request instant-strategy models.
-        // When present, the server skips all other models → smaller payload.
-        // When absent, server returns all models (backward compat).
-        if (this.options.instantModels && this.options.instantModels.length > 0) {
-            params.append('models', this.options.instantModels.join(','));
-        }
-        const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
-        // If offline, try the cached bootstrap. Skipped for a scoped override: the
-        // cache holds the full snapshot, which is not a valid answer to a subset
-        // request; a scoped hydrate just soft-fails offline and retries on re-enter.
-        //
-        // Only an explicit `false` means offline. `navigator.onLine` is *typed*
-        // `boolean`, but at runtime it is `boolean | undefined`: Node 21+ exposes a
-        // global `navigator` whose `onLine` is `undefined`. Reading `!navigator.onLine`
-        // would treat that `undefined` as offline and falsely short-circuit to the
-        // (empty, under `persistence: 'memory'`) cache — throwing instead of fetching.
-        // Capturing it at its true runtime type keeps the `=== false` honest (and lets
-        // the boolean-literal-compare lint rule see the nullable it really is).
-        const navigatorOnline = typeof navigator !== 'undefined' ? navigator.onLine : undefined;
-        if (!syncGroupsOverride && navigatorOnline === false) {
-            const cached = this.options.cacheScope
-                ? this.loadCachedBootstrap(this.options.cacheScope)
-                : null;
-            if (cached) {
-                this.runtime.logger.info('Using cached bootstrap (offline)');
-                return cached;
-            }
-            throw new AbloConnectionError('Offline and no cached bootstrap available', {
-                code: 'bootstrap_offline_no_cache',
-            });
-        }
-        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 {
-                return await this.fetchOnce(url, lane);
-            }
-            catch (error) {
-                // SessionError should NOT be retried - the session is invalid and needs re-authentication
-                if (AbloSessionError.isSessionError(error)) {
-                    this.runtime.observability.breadcrumb('Bootstrap session error - redirecting to sign-in', 'sync.bootstrap', 'warning', {
-                        statusCode: (error).statusCode,
-                    });
-                    throw error;
-                }
-                // Don't retry NON-retryable errors. A 401/403/4xx auth or client error
-                // (api_key_required, jwt_issuer_untrusted, …) will NOT succeed by
-                // repeating the same request with the same credential — retrying just
-                // hammers the server and floods the console with doomed requests. Only
-                // transient failures (5xx, 429, timeouts, network blips, or an
-                // unclassified error with no code) flow through to the retry/backoff.
-                const ablo = toAbloError(error);
-                if (ablo.code && !isRetryableCode(ablo.code)) {
-                    this.runtime.observability.breadcrumb('Bootstrap non-retryable error — failing fast', 'sync.bootstrap', 'warning', { code: ablo.code, httpStatus: ablo.httpStatus });
-                    throw ablo;
-                }
-                lastError = error;
-                this.runtime.observability.breadcrumb('Bootstrap fetch failed', 'sync.bootstrap', 'warning', {
-                    attempt: attempt + 1,
-                });
-                if (attempt < this.options.maxRetries - 1) {
-                    await this.delay(this.options.retryDelay * Math.pow(2, attempt));
-                }
-            }
-        }
-        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
-     */
-    async fetchBootstrapWithETag() {
-        // The organization id is intentionally not sent. The server resolves it
-        // from the authenticated identity, so the client cannot select or spoof an
-        // organization it is not scoped to.
-        const params = new URLSearchParams();
-        this.options.syncGroups.forEach((g) => { params.append('syncGroups', g); });
-        if (this.options.instantModels && this.options.instantModels.length > 0) {
-            params.append('models', this.options.instantModels.join(','));
-        }
-        const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
-        // Note: ETag caching is deliberately app-side, not SDK-side. The server
-        // still returns an ETag on responses, which is captured below and
-        // forwarded to callers via BootstrapFetchResult.etag — apps that want
-        // conditional revalidation (If-None-Match) implement it at their own
-        // level where they own the cache-key namespace. The 304 branch below
-        // remains defensively in place for when a caller enables revalidation.
-        const headers = withAuthHeaders(this.options.getAuthToken, { 'Content-Type': 'application/json' }, this.options.authToken);
-        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: controller.signal,
-        });
-        const etag = res.headers.get('ETag');
-        if (res.status === 304) {
-            // Log for telemetry
-            this.runtime.logger.info('[Bootstrap] 304 Not Modified - using cached data');
-            return { notModified: true, etag };
-        }
-        if (!res.ok) {
-            const bodyText = await res.text().catch(() => '');
-            // Map an empty body to undefined so the `??` below falls through to the
-            // synthetic message — translateHttpError renders an empty string body as
-            // an empty error message, which is useless to the caller.
-            let parsed = bodyText || undefined;
-            if (bodyText) {
-                try {
-                    parsed = JSON.parse(bodyText);
-                }
-                catch {
-                    // Keep as string.
-                }
-            }
-            // Translate the canonical envelope first so the server's specific code
-            // and message survive (for example `api_key_required` or
-            // `jwt_issuer_untrusted`).
-            const translated = translateHttpError(res.status, parsed ?? `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
-            // Only a genuine session or JWT expiry — or a bare auth failure carrying
-            // no structured code — should drive the sign-in redirect. A specific auth
-            // code like `api_key_required` is not an expired session: signing in again
-            // mints the same credential and loops. Surface it as its real typed error
-            // instead of a `session_expired` wrapping the stringified body.
-            if (translated.code === 'session_expired' ||
-                translated.code === 'jwt_expired' ||
-                ((res.status === 401 || res.status === 403) &&
-                    translated.code === undefined)) {
-                throw new AbloSessionError(translated.message, res.status);
-            }
-            throw translated;
-        }
-        const data = parseBootstrapResponse(await this.readJsonWithStallGuard(res, controller), this.runtime);
-        this.warnOnSchemaDrift(data.schemaHash);
-        // Persist payload 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.
-        }
-        this.runtime.logger.info('[Bootstrap] 200 OK - received new data');
-        return { notModified: false, data, etag };
-    }
-    /**
-     * 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 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);
-        }
-        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(() => {
-            this.runtime.observability.breadcrumb('Bootstrap fetch timeout', 'sync.bootstrap', 'warning', {
-                timeoutMs: this.options.fetchTimeout,
-            });
-            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 {
-            response = await fetch(url, {
-                method: 'GET',
-                headers: withAuthHeaders(this.options.getAuthToken, {
-                    'Content-Type': 'application/json',
-                    'Cache-Control': 'no-cache, no-store, must-revalidate',
-                    Pragma: 'no-cache',
-                }, this.options.authToken),
-                signal: controller.signal,
-                cache: 'no-store', // Force browser to not cache
-            });
-        }
-        catch (error) {
-            clearTimeout(timeoutId);
-            throw classifyRequestFailure(error, controller, 'The bootstrap request was aborted before the server responded');
-        }
-        clearTimeout(timeoutId);
-        if (!response.ok) {
-            const bodyText = await response.text().catch(() => '');
-            // Map an empty body to undefined so the `??` below falls through to the
-            // synthetic message (see the note on the primary fetch path).
-            let parsed = bodyText || undefined;
-            if (bodyText) {
-                try {
-                    parsed = JSON.parse(bodyText);
-                }
-                catch {
-                    // Keep as string.
-                }
-            }
-            // Same code-aware handling as the primary bootstrap fetch: preserve the
-            // server's specific code/message; only a genuine expiry (or a bare,
-            // code-less auth failure) drives the sign-in redirect.
-            const translated = translateHttpError(response.status, parsed ?? `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
-            if (translated.code === 'session_expired' ||
-                translated.code === 'jwt_expired' ||
-                ((response.status === 401 || response.status === 403) &&
-                    translated.code === undefined)) {
-                throw new AbloSessionError(translated.message, response.status);
-            }
-            throw translated;
-        }
-        const data = parseBootstrapResponse(await this.readJsonWithStallGuard(response, controller), this.runtime);
-        this.warnOnSchemaDrift(data.schemaHash);
-        // Offline caching happens in `fetchBootstrap` on the assembled result —
-        // caching here would let a single-model chunk overwrite the full snapshot.
-        return data;
-    }
-    /**
-     * Fetch a single entity by ID (on-demand self-healing).
-     * Returns `null` for 404 (entity deleted) — this is an expected state, not an error.
-     * Throws for unexpected HTTP errors (5xx, network failures).
-     */
-    async fetchEntity(modelName, id) {
-        const url = `${this.options.baseUrl}/sync/entity/${modelName}/${id}`;
-        // Uses the same `fetchTimeout` deadline as `performFetch`. A local
-        // AbortController, rather than the shared `this.abortController`, means an
-        // entity self-heal never cancels a concurrent bootstrap fetch.
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => { controller.abort(); }, this.options.fetchTimeout);
-        let response;
-        try {
-            response = await fetch(url, {
-                method: 'GET',
-                headers: withAuthHeaders(this.options.getAuthToken, {
-                    'Content-Type': 'application/json',
-                }, this.options.authToken),
-                signal: controller.signal,
-            });
-        }
-        catch (error) {
-            // Convert abort to the existing typed timeout error (same code as the
-            // bootstrap fetch path) so callers get a retryable connection error.
-            if (error instanceof Error && error.name === 'AbortError') {
-                throw new AbloConnectionError(`Entity fetch timed out after ${this.options.fetchTimeout}ms`, { code: 'bootstrap_fetch_timeout', cause: error });
-            }
-            throw error;
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
-        if (response.status === 404) {
-            return null;
-        }
-        if (!response.ok) {
-            const bodyText = await response.text().catch(() => '');
-            // Map an empty body to undefined so the `??` below falls through to the
-            // synthetic message (see the note on the primary fetch path).
-            let parsed = bodyText || undefined;
-            if (bodyText) {
-                try {
-                    parsed = JSON.parse(bodyText);
-                }
-                catch {
-                    // Keep as string.
-                }
-            }
-            throw translateHttpError(response.status, parsed ?? `Entity fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
-        }
-        return (await response.json());
-    }
-    // ─────────────────────────────────────────────────────────────────────
-    /**
-     * Clear all cached bootstrap data
-     */
-    clearCache() {
-        if (typeof window === 'undefined')
-            return;
-        try {
-            // Clear all bootstrap cache keys
-            const keysToRemove = [];
-            for (let i = 0; i < localStorage.length; i++) {
-                const key = localStorage.key(i);
-                if (key?.includes('sync-bootstrap')) {
-                    keysToRemove.push(key);
-                }
-            }
-            keysToRemove.forEach((key) => {
-                localStorage.removeItem(key);
-                this.runtime.logger.debug('Cleared cache key', { key });
-            });
-        }
-        catch (error) {
-            this.runtime.logger.debug('Failed to clear cache', { error });
-        }
-    }
-    // Cache helpers for offline bootstrap
-    getBootstrapCacheKey(orgId) {
-        return `ablo:bootstrap:${orgId}`;
-    }
-    saveCachedBootstrap(orgId, data) {
-        if (typeof window === 'undefined')
-            return;
-        try {
-            localStorage.setItem(this.getBootstrapCacheKey(orgId), JSON.stringify(data));
-        }
-        catch (e) {
-            this.runtime.logger.debug('Failed to cache bootstrap payload', {
-                error: e instanceof Error ? e.message : String(e),
-            });
-        }
-    }
-    loadCachedBootstrap(orgId) {
-        if (typeof window === 'undefined')
-            return null;
-        try {
-            const raw = localStorage.getItem(this.getBootstrapCacheKey(orgId));
-            if (!raw)
-                return null;
-            return JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
-    }
-    /**
-     * 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() {
-        this.flights.clear();
-        this.cancelActive(cancelled('Bootstrap aborted by its caller'));
-    }
-    /**
-     * Helper to delay execution
-     */
-    delay(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
-    }
-    /**
-     * Get health status of sync engine
-     */
-    async checkHealth() {
-        try {
-            const response = await fetch(`${this.options.baseUrl}/health`, {
-                method: 'GET',
-                signal: AbortSignal.timeout(5000),
-                cache: 'no-store',
-            });
-            if (!response.ok)
-                return false;
-            const body = (await response.json());
-            return body.status === 'healthy';
-        }
-        catch {
-            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 } : {}),
-    };
-}