@abloatai/ablo 0.26.0 → 0.27.0

package/dist/surface.d.ts

@@ -1,28 +1,35 @@
 /**
- * Machine-checked public API-surface manifest — the SDK owns the description of
- * its OWN surface, bound to the real exported types at COMPILE TIME so the MCP
- * `get_api_surface` / docs can never drift from reality.
+ * A machine-checked manifest of this package's public API surface. It lists,
+ * as string tuples, the method names on `ablo.<model>`, the keys accepted by
+ * the list-style read options, and the keys of the client constructor
+ * options. Each tuple is proven equal to the keys of its source interface at
+ * compile time, so the lists cannot drift from the real types: add or remove
+ * a name on either side without updating the matching tuple and this file
+ * fails to compile, in both directions — no name the interface lacks, and no
+ * interface key the tuple omits.
  *
- * This exists because the hand-authored surface (apps/sync-web/.../api-surface.ts)
- * once named `load` / `count` / `scope` — verbs/options that don't exist — with no
- * coupling to the code. The fix: the name lists live HERE, next to the types, and
- * each is proven EXACTLY equal to the keys of its source interface via
- * `Expect<Equal<…>>`. Add or remove a verb/option without updating the matching
- * tuple and THIS FILE FAILS TO COMPILE (the `Equal` constraint is checked eagerly
- * at the alias declaration — both directions: no phantom name, no missing name).
- *
- * Consumers (the MCP `get_api_surface`) import these NAME tuples and build their
- * prose from them, so a summary can never reference a verb that doesn't exist.
- * NAMES are guaranteed; descriptions stay hand-written (prose can't be type-checked).
+ * Documentation tooling reads these tuples to describe the surface, which
+ * guarantees a generated summary never names a method or option that does
+ * not exist. The names are verified here; their prose descriptions are
+ * written by hand, since prose cannot be type-checked.
+ */
+/**
+ * The names of every method available on `ablo.<model>`, matching the keys of
+ * the {@link ModelOperations} interface. Documentation tooling reads this
+ * tuple, so it is the one list of model-verb names a generated summary can
+ * describe.
  */
-/** Every method on `ablo.<model>` (the stateful `ModelOperations`). The single
- *  source of truth for the model-verb names the docs/MCP may describe. */
 export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "get", "getAll", "getCount", "create", "update", "delete", "claim", "watch", "onChange"];
-/** Keys accepted by `list`/`getAll`/`onChange` options (`LocalReadOptions`).
- *  Note `state` (lifecycle filter) — NOT `scope` (a historic doc drift). */
+/**
+ * The option keys accepted by `list`, `getAll`, and `onChange`, matching the
+ * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
+ * `state`, not `scope`.
+ */
 export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orderBy", "limit", "offset", "state"];
-/** Public keys of `AbloOptions`. `schema` is required; the rest are optional
- *  (the locked happy path is `Ablo({ schema, apiKey, databaseUrl, transport })`). */
+/**
+ * The keys of the client constructor options, {@link AbloOptions}. Only
+ * `schema` is required; every other key is optional.
+ */
 export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "databaseUrl", "persistence", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];

package/dist/surface.js

@@ -1,23 +1,25 @@
 /**
- * Machine-checked public API-surface manifest — the SDK owns the description of
- * its OWN surface, bound to the real exported types at COMPILE TIME so the MCP
- * `get_api_surface` / docs can never drift from reality.
+ * A machine-checked manifest of this package's public API surface. It lists,
+ * as string tuples, the method names on `ablo.<model>`, the keys accepted by
+ * the list-style read options, and the keys of the client constructor
+ * options. Each tuple is proven equal to the keys of its source interface at
+ * compile time, so the lists cannot drift from the real types: add or remove
+ * a name on either side without updating the matching tuple and this file
+ * fails to compile, in both directions — no name the interface lacks, and no
+ * interface key the tuple omits.
  *
- * This exists because the hand-authored surface (apps/sync-web/.../api-surface.ts)
- * once named `load` / `count` / `scope` — verbs/options that don't exist — with no
- * coupling to the code. The fix: the name lists live HERE, next to the types, and
- * each is proven EXACTLY equal to the keys of its source interface via
- * `Expect<Equal<…>>`. Add or remove a verb/option without updating the matching
- * tuple and THIS FILE FAILS TO COMPILE (the `Equal` constraint is checked eagerly
- * at the alias declaration — both directions: no phantom name, no missing name).
- *
- * Consumers (the MCP `get_api_surface`) import these NAME tuples and build their
- * prose from them, so a summary can never reference a verb that doesn't exist.
- * NAMES are guaranteed; descriptions stay hand-written (prose can't be type-checked).
+ * Documentation tooling reads these tuples to describe the surface, which
+ * guarantees a generated summary never names a method or option that does
+ * not exist. The names are verified here; their prose descriptions are
+ * written by hand, since prose cannot be type-checked.
  */
 // ── the per-`ablo.<model>` verb surface ────────────────────────────────────
-/** Every method on `ablo.<model>` (the stateful `ModelOperations`). The single
- *  source of truth for the model-verb names the docs/MCP may describe. */
+/**
+ * The names of every method available on `ablo.<model>`, matching the keys of
+ * the {@link ModelOperations} interface. Documentation tooling reads this
+ * tuple, so it is the one list of model-verb names a generated summary can
+ * describe.
+ */
 export const PUBLIC_MODEL_VERBS = [
     'retrieve',
     'list',
@@ -32,8 +34,11 @@ export const PUBLIC_MODEL_VERBS = [
     'onChange',
 ];
 // ── the read/list query option surface ─────────────────────────────────────
-/** Keys accepted by `list`/`getAll`/`onChange` options (`LocalReadOptions`).
- *  Note `state` (lifecycle filter) — NOT `scope` (a historic doc drift). */
+/**
+ * The option keys accepted by `list`, `getAll`, and `onChange`, matching the
+ * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
+ * `state`, not `scope`.
+ */
 export const PUBLIC_LIST_OPTION_KEYS = [
     'where',
     'filter',
@@ -43,8 +48,10 @@ export const PUBLIC_LIST_OPTION_KEYS = [
     'state',
 ];
 // ── the `Ablo({ … })` constructor option surface ───────────────────────────
-/** Public keys of `AbloOptions`. `schema` is required; the rest are optional
- *  (the locked happy path is `Ablo({ schema, apiKey, databaseUrl, transport })`). */
+/**
+ * The keys of the client constructor options, {@link AbloOptions}. Only
+ * `schema` is required; every other key is optional.
+ */
 export const PUBLIC_ABLO_OPTION_KEYS = [
     'schema',
     'apiKey',

package/dist/sync/{BootstrapHelper.d.ts → BootstrapFetcher.d.ts}

@@ -1,25 +1,30 @@
 /**
- * BootstrapHelper - Fixed to always fetch fresh data
- * Removed problematic caching that was serving stale data
+ * 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.
  */
 export interface BootstrapData {
     type: 'full' | 'partial';
     lastSyncId: number;
     /**
-     * Model rows keyed by typename. Each row is opaque to the SDK at this
-     * boundary — the per-model shape is asserted by the consumer (sync
-     * engine reduce + IDB write) using the registered schema.
+     * Model rows keyed by type name. Each row is opaque at this boundary; the
+     * engine asserts the per-model shape against the registered schema when it
+     * reduces the rows and writes them to local storage.
      */
     models?: Record<string, unknown[]>;
     deltas?: ValidatedServerDelta[];
     deltaCount?: number;
-    /** Model types whose server-side query failed (timeout, RLS error, etc.) */
+    /** Model types whose server-side query failed (timeout, RLS error, and the like). */
     failedModels?: string[];
     timestamp: number;
     /**
-     * The server's ACTIVE schema content hash for this tenant (same `schemaHash`
-     * the CLI push computes). Present once the tenant has pushed a schema; the
-     * client compares it to its own `config.expectedSchemaHash` to warn on drift.
+     * The content hash of the schema the server currently has active for this
+     * tenant — the same hash `ablo push` computes. Present once a schema has been
+     * pushed. The client compares it against its own `expectedSchemaHash` to warn
+     * when the app's schema and the deployed schema have drifted apart.
      */
     schemaHash?: string;
 }
@@ -40,40 +45,38 @@ export interface BootstrapOptions {
      */
     baseUrl?: string;
     /**
-     * Private cache namespace for offline bootstrap fallback. Hosted SDK
-     * callers do not pass this; Ablo sets it after auth resolves the
-     * account scope.
+     * Namespace for the offline bootstrap cache. Most callers leave this unset;
+     * the SDK fills it in once authentication has resolved the account scope, so
+     * the fallback cache is partitioned per account.
      */
     cacheScope?: string | null;
     /**
-     * @deprecated Use `cacheScope`. Kept so older self-hosted code that
-     * still constructs BootstrapHelper directly keeps its cache namespace.
+     * @deprecated Use `cacheScope`. Retained so code that constructs
+     * {@link BootstrapFetcher} directly keeps its cache namespace.
      */
     organizationId?: string;
     syncGroups?: string[];
     maxRetries?: number;
     retryDelay?: number;
-    /** Timeout for individual fetch requests in ms (default: 30000) */
+    /** How long to wait for a single fetch before timing out, in milliseconds. Default 10000 (10 seconds). */
     fetchTimeout?: number;
     /**
-     * Model names to request in bootstrap. When set, the server only returns
-     * these models — everything else is skipped. Derived from the schema's
-     * `load` strategy: only models with `load: 'instant'` (or unset, which
-     * defaults to instant) are included.
-     *
-     * When absent, the server returns all models (backward compatible with
-     * old clients that don't send a models param).
+     * The model names to request. When set, the server returns only these models
+     * and skips the rest. This is derived from each model's `load` strategy: only
+     * models loaded instantly (the default) are included. When unset, the server
+     * returns every model.
      */
     instantModels?: string[];
     /**
-     * Shared SDK credential getter. Preferred over `setAuthToken`; read at
-     * request time so token refreshes apply without recreating BootstrapHelper.
+     * Getter for the current credential, read at request time so a refreshed
+     * token takes effect without recreating the helper. Preferred over
+     * {@link BootstrapFetcher.setAuthToken}.
      */
     getAuthToken?: AuthTokenGetter;
 }
 import { type AuthTokenGetter } from '../auth/credentialSource.js';
 import { type ValidatedServerDelta } from './schemas.js';
-export declare class BootstrapHelper {
+export declare class BootstrapFetcher {
     private options;
     private abortController;
     /** Warn about schema drift at most once per helper. */
@@ -95,20 +98,10 @@ export declare class BootstrapHelper {
     setCacheScope(cacheScope: string): void;
     setSyncGroups(syncGroups: readonly string[] | undefined): void;
     /**
-     * Compatibility setter for direct BootstrapHelper users. The SDK-owned
-     * `Ablo()` path passes `getAuthToken` and does not mutate this helper.
+     * Sets a fixed credential for callers that construct the helper directly.
+     * The SDK instead supplies `getAuthToken` and never calls this.
      */
     setAuthToken(authToken: string | undefined): void;
-    /**
-     * Create a promise that rejects after a timeout
-     * Used to race against fetch requests that may hang indefinitely
-     */
-    private createTimeoutPromise;
-    /**
-     * Wrap a promise with a timeout - if the promise doesn't resolve within
-     * the timeout period, the AbortController is triggered and an error is thrown
-     */
-    private withTimeout;
     /**
      * Fetch bootstrap data from sync engine with partial bootstrap support
      * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
@@ -116,11 +109,12 @@ export declare class BootstrapHelper {
      */
     fetchBootstrap(lastSyncId?: number, 
     /**
-     * Per-call sync-group override for SCOPED hydrate-on-enter. When provided,
-     * the request uses THESE groups instead of `this.options.syncGroups`,
-     * WITHOUT mutating the shared options (so a concurrent full bootstrap is
-     * unaffected). Also bypasses the offline full-snapshot cache below, which
-     * holds the connection's full bootstrap and would be wrong for a subset.
+     * 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?: readonly string[]): Promise<BootstrapData>;
     /**

package/dist/sync/{BootstrapHelper.js → BootstrapFetcher.js}

@@ -1,13 +1,17 @@
 /**
- * BootstrapHelper - Fixed to always fetch fresh data
- * Removed problematic caching that was serving stale data
+ * 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 { getContext } from '../context.js';
 import { SyncSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '../errors.js';
 import { withAuthHeaders } from '../auth/credentialSource.js';
 // SyncObservability replaced by getContext().observability
 import { parseBootstrapResponse } from './schemas.js';
-export class BootstrapHelper {
+export class BootstrapFetcher {
     options;
     abortController = null;
     /** Warn about schema drift at most once per helper. */
@@ -39,23 +43,20 @@ export class BootstrapHelper {
             `\`ablo push\` to deploy your schema (or update this app to match the deployed one).`, { clientSchemaHash: clientHash, serverSchemaHash: serverHash });
     }
     constructor(options) {
-        // Defaults are spread first; the explicit `baseUrl` then takes precedence
-        // and is computed from `options.baseUrl` (or the localhost fallback).
-        //
-        // Historical note: a previous version of this constructor placed
-        // `baseUrl: \`${baseUrl}/api\`` BEFORE the `...options` spread, which
-        // meant the spread silently overwrote it back to the caller's value
-        // and the `/api` suffix was dead code. Both Ablo and `createSyncEngine`
-        // already pass `${url}/api` explicitly, so removing the suffix here
-        // preserves the actual on-the-wire behavior while making the contract
-        // explicit: callers pass the full base URL including `/api`.
+        // 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,
             fetchTimeout: 10_000, // 10 second timeout per request - fail fast for good UX
             ...options,
-            baseUrl: options.baseUrl || 'http://localhost:8080/api',
+            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
@@ -73,8 +74,8 @@ export class BootstrapHelper {
         this.options.syncGroups = [...(syncGroups ?? [])];
     }
     /**
-     * Compatibility setter for direct BootstrapHelper users. The SDK-owned
-     * `Ablo()` path passes `getAuthToken` and does not mutate this helper.
+     * Sets a fixed credential for callers that construct the helper directly.
+     * The SDK instead supplies `getAuthToken` and never calls this.
      */
     setAuthToken(authToken) {
         if (!authToken) {
@@ -83,26 +84,6 @@ export class BootstrapHelper {
         }
         this.options.authToken = authToken;
     }
-    /**
-     * Create a promise that rejects after a timeout
-     * Used to race against fetch requests that may hang indefinitely
-     */
-    createTimeoutPromise(ms, operation) {
-        return new Promise((_, reject) => {
-            setTimeout(() => {
-                reject(new AbloConnectionError(`Bootstrap ${operation} timed out after ${ms}ms`, {
-                    code: 'bootstrap_fetch_timeout',
-                }));
-            }, ms);
-        });
-    }
-    /**
-     * Wrap a promise with a timeout - if the promise doesn't resolve within
-     * the timeout period, the AbortController is triggered and an error is thrown
-     */
-    async withTimeout(promise, timeoutMs, operation) {
-        return Promise.race([promise, this.createTimeoutPromise(timeoutMs, operation)]);
-    }
     /**
      * Fetch bootstrap data from sync engine with partial bootstrap support
      * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
@@ -110,11 +91,12 @@ export class BootstrapHelper {
      */
     async fetchBootstrap(lastSyncId, 
     /**
-     * Per-call sync-group override for SCOPED hydrate-on-enter. When provided,
-     * the request uses THESE groups instead of `this.options.syncGroups`,
-     * WITHOUT mutating the shared options (so a concurrent full bootstrap is
-     * unaffected). Also bypasses the offline full-snapshot cache below, which
-     * holds the connection's full bootstrap and would be wrong for a subset.
+     * 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) {
         // organizationId omitted — server reads it from auth identity.
@@ -135,10 +117,19 @@ export class BootstrapHelper {
             params.append('models', this.options.instantModels.join(','));
         }
         const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
-        // If offline, try cached bootstrap. Skipped for a scoped override — the
-        // cache holds the FULL snapshot, which is not a valid answer to a subset
+        // 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.
-        if (!syncGroupsOverride && typeof navigator !== 'undefined' && navigator && navigator.onLine === false) {
+        //
+        // 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;
@@ -160,7 +151,7 @@ export class BootstrapHelper {
                     type: data.type,
                     lastSyncId: data.lastSyncId,
                     modelCount: data.models ? Object.keys(data.models).length : 0,
-                    deltaCount: data.deltaCount || 0,
+                    deltaCount: data.deltaCount ?? 0,
                     totalItems: data.models
                         ? Object.values(data.models).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0)
                         : 0,
@@ -220,11 +211,9 @@ export class BootstrapHelper {
      * Fetch bootstrap with ETag, returning 304 hints
      */
     async fetchBootstrapWithETag() {
-        // organizationId is intentionally NOT sent. Server resolves it from
-        // the authenticated identity (`c.var.identity.organizationId`) —
-        // see `apps/sync-server/src/routes/bootstrap.ts`. Sending it
-        // client-side was historical: it predated the auth-context pipeline
-        // and forced a cross-org guard to defend against the SDK lying.
+        // 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) {
@@ -252,7 +241,10 @@ export class BootstrapHelper {
         }
         if (!res.ok) {
             const bodyText = await res.text().catch(() => '');
-            let parsed = bodyText;
+            // 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);
@@ -261,12 +253,13 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            // Translate the canonical envelope FIRST so the server's specific code +
-            // message survive (e.g. `api_key_required`, `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/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: re-logging-in
+            // 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' ||
@@ -277,8 +270,7 @@ export class BootstrapHelper {
             }
             throw translated;
         }
-        const rawJson = await res.json();
-        const data = parseBootstrapResponse(rawJson);
+        const data = parseBootstrapResponse(await res.json());
         this.warnOnSchemaDrift(data.schemaHash);
         // Persist payload for offline
         try {
@@ -286,7 +278,10 @@ export class BootstrapHelper {
                 this.saveCachedBootstrap(this.options.cacheScope, data);
             }
         }
-        catch { }
+        catch {
+            // 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');
         return { notModified: false, data, etag };
     }
@@ -329,7 +324,9 @@ export class BootstrapHelper {
         clearTimeout(timeoutId);
         if (!response.ok) {
             const bodyText = await response.text().catch(() => '');
-            let parsed = bodyText;
+            // 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);
@@ -341,7 +338,7 @@ export class BootstrapHelper {
             // 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);
+            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) &&
@@ -350,8 +347,7 @@ export class BootstrapHelper {
             }
             throw translated;
         }
-        const rawJson = await response.json();
-        const data = parseBootstrapResponse(rawJson);
+        const data = parseBootstrapResponse(await response.json());
         this.warnOnSchemaDrift(data.schemaHash);
         // Save a copy for offline
         try {
@@ -359,7 +355,10 @@ export class BootstrapHelper {
                 this.saveCachedBootstrap(this.options.cacheScope, data);
             }
         }
-        catch { }
+        catch {
+            // Offline persistence is best-effort; a failed cache write must not
+            // block returning the freshly fetched data.
+        }
         return data;
     }
     /**
@@ -369,10 +368,9 @@ export class BootstrapHelper {
      */
     async fetchEntity(modelName, id) {
         const url = `${this.options.baseUrl}/sync/entity/${modelName}/${id}`;
-        // Same `fetchTimeout` deadline `performFetch` uses — this was the one
-        // fetch in this file with no AbortSignal, so a hung self-heal read could
-        // stall its caller forever. A LOCAL controller (not `this.abortController`)
-        // so an entity self-heal never cancels a concurrent bootstrap fetch.
+        // 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;
@@ -401,7 +399,9 @@ export class BootstrapHelper {
         }
         if (!response.ok) {
             const bodyText = await response.text().catch(() => '');
-            let parsed = bodyText;
+            // 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);
@@ -410,9 +410,9 @@ export class BootstrapHelper {
                     // Keep as string.
                 }
             }
-            throw translateHttpError(response.status, parsed || `Entity fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            throw translateHttpError(response.status, parsed ?? `Entity fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
         }
-        return await response.json();
+        return (await response.json());
     }
     // ─────────────────────────────────────────────────────────────────────
     /**
@@ -426,7 +426,7 @@ export class BootstrapHelper {
             const keysToRemove = [];
             for (let i = 0; i < localStorage.length; i++) {
                 const key = localStorage.key(i);
-                if (key && key.includes('sync-bootstrap')) {
+                if (key?.includes('sync-bootstrap')) {
                     keysToRemove.push(key);
                 }
             }
@@ -495,10 +495,10 @@ export class BootstrapHelper {
             });
             if (!response.ok)
                 return false;
-            const data = await response.json();
-            return data.status === 'healthy';
+            const body = (await response.json());
+            return body.status === 'healthy';
         }
-        catch (error) {
+        catch {
             getContext().observability.breadcrumb('Health check failed', 'sync.bootstrap', 'warning');
             return false;
         }