@abloatai/humans 0.37.0

package/dist/local/stores/openIDBWithTimeout.js

@@ -0,0 +1,153 @@
+/**
+ * The error raised when opening an IndexedDB database does not complete in a
+ * bounded time. {@link openIDBWithTimeout} throws it in two situations: another
+ * browser tab is holding an older version of the database open and blocking the
+ * upgrade (`reason: 'blocked'`), or the open request produced no result at all
+ * within the timeout (`reason: 'timeout'`).
+ *
+ * The native open request can otherwise hang indefinitely — when a blocking tab
+ * never closes its connection, neither the success nor the error callback fires,
+ * and any code awaiting the open waits forever. Turning that into a thrown error
+ * lets the surrounding application show a recoverable failure instead of an
+ * unbreakable spinner.
+ */
+export class IDBOpenTimeoutError extends Error {
+    dbName;
+    reason;
+    /**
+     * A stable identifier for this failure, independent of the message text. When
+     * this error is wrapped into an {@link AbloError} by `toAbloError`, the string
+     * code is preserved, so error handlers can recognize a wedged-storage failure
+     * and offer a recovery path rather than matching on the message.
+     */
+    code = 'storage_open_timeout';
+    constructor(dbName, reason, message) {
+        super(message);
+        this.dbName = dbName;
+        this.reason = reason;
+        this.name = 'IDBOpenTimeoutError';
+    }
+}
+/**
+ * Returns true when a caught value is the storage-open-timeout failure. It
+ * detects the failure by its stable `code`, so it still matches after the error
+ * has been wrapped into an {@link AbloError} or another error type.
+ */
+export function isStorageOpenTimeout(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        err.code === 'storage_open_timeout');
+}
+export function openIDBWithTimeout(name, version, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    return new Promise((resolve, reject) => {
+        const request = version === undefined
+            ? indexedDB.open(name)
+            : indexedDB.open(name, version);
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        if (options.onUpgrade) {
+            request.onupgradeneeded = (event) => {
+                options.onUpgrade(request, event);
+            };
+        }
+        request.onsuccess = () => {
+            // If we already timed out or were blocked and rejected, this is a late
+            // success: the native open eventually completed after we gave up. The
+            // resulting connection is orphaned — nothing up the stack holds it, so
+            // nothing will close it. A leaked open connection holds an IndexedDB lock
+            // that wedges every later open or delete of this database name, so close
+            // it here to keep a timed-out attempt from poisoning the store.
+            if (settled) {
+                try {
+                    request.result.close();
+                }
+                catch {
+                    // Best-effort — a half-open connection may already be unusable.
+                }
+                return;
+            }
+            const db = request.result;
+            // Required resilience handler per the IndexedDB specification: close this
+            // connection as soon as any other context wants to upgrade or delete the
+            // database. Without it, a connection that ignores `versionchange` blocks
+            // the other context's request indefinitely — a common cause of a database
+            // that stays wedged across reloads. Closing here makes the store release
+            // itself.
+            db.onversionchange = () => {
+                try {
+                    db.close();
+                }
+                catch {
+                    // Already closing/closed — nothing to do.
+                }
+                try {
+                    options.onVersionChange?.();
+                }
+                catch {
+                    // A consumer reaction must never break the close.
+                }
+            };
+            settle(() => { resolve(db); });
+        };
+        request.onerror = () => { settle(() => { reject(request.error); }); };
+        // The critical handler: another tab is blocking us. Native API leaves
+        // the request pending indefinitely; we fail fast with a clear error so
+        // the UI can tell the user to close other tabs.
+        request.onblocked = () => {
+            settle(() => {
+                reject(new IDBOpenTimeoutError(name, 'blocked', `IndexedDB \"${name}\" open blocked — another tab is holding an ` +
+                    `older version. Close other Ablo tabs and reload.`));
+            });
+        };
+        // Catch-all timeout: even without `onblocked`, some browsers in some
+        // storage states hang without firing any event. Bounded wait →
+        // deterministic error.
+        const timer = setTimeout(() => {
+            settle(() => {
+                reject(new IDBOpenTimeoutError(name, 'timeout', `IndexedDB \"${name}\" open did not resolve within ${timeoutMs}ms. ` +
+                    `Storage may be in a bad state — clearing site data and reloading ` +
+                    `usually fixes this.`));
+            });
+        }, timeoutMs);
+    });
+}
+/**
+ * Deletes an IndexedDB database within a bounded time — the delete counterpart
+ * to {@link openIDBWithTimeout}. It is used to recover from a wedged backing
+ * store: when opening a database times out, the caller can delete it and start
+ * fresh, which is safe for any database whose contents can be rebuilt on the
+ * next load.
+ *
+ * Like an open request, a native delete can hang indefinitely — it fires a
+ * blocked event and waits when another connection still holds the database, and
+ * on a truly stuck store it fires no event at all. Both cases become a bounded,
+ * resolved result here, so the caller never spins.
+ *
+ * Resolves to `true` on a clean delete and `false` when the delete was blocked
+ * or timed out. Either way the caller can decide whether to retry the open; a
+ * delete that did nothing leaves the store no worse off.
+ */
+export function deleteIDBWithTimeout(name, timeoutMs = 5_000) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const request = indexedDB.deleteDatabase(name);
+        request.onsuccess = () => { settle(true); };
+        request.onerror = () => { settle(false); };
+        request.onblocked = () => { settle(false); };
+        const timer = setTimeout(() => { settle(false); }, timeoutMs);
+    });
+}

package/dist/local/stores/persistenceCleanup.d.ts

@@ -0,0 +1,7 @@
+import type { DatabaseInfo } from './DatabaseManager.js';
+type DeleteDatabase = (name: string) => Promise<boolean>;
+/** Exact data-store names that can contain the current identity's state. */
+export declare function persistenceDatabaseNamesForDeletion(current: DatabaseInfo | null): string[];
+/** Delete authenticated IndexedDB state after its owners have closed handles. */
+export declare function purgeIndexedDbPersistence(current: DatabaseInfo | null, deleteDatabase?: DeleteDatabase): Promise<void>;
+export {};

package/dist/local/stores/persistenceCleanup.js

@@ -0,0 +1,26 @@
+import { AbloConnectionError } from '@abloatai/transaction/errors';
+import { deleteIDBWithTimeout } from './openIDBWithTimeout.js';
+import { v1PersistenceDatabaseNameForDeletion } from './v1PersistenceDeletion.js';
+/** Exact data-store names that can contain the current identity's state. */
+export function persistenceDatabaseNamesForDeletion(current) {
+    if (!current)
+        return ['ablo-sync'];
+    return [
+        current.name,
+        v1PersistenceDatabaseNameForDeletion(current.userId, current.workspaceId, current.userVersion ?? 1),
+        // Retired pre-identity store. It cannot be attributed safely, so any
+        // terminal cleanup removes it rather than attempting to reuse its data.
+        'ablo-sync',
+    ];
+}
+/** Delete authenticated IndexedDB state after its owners have closed handles. */
+export async function purgeIndexedDbPersistence(current, deleteDatabase = deleteIDBWithTimeout) {
+    const failed = new Set();
+    for (const name of persistenceDatabaseNamesForDeletion(current)) {
+        if (!(await deleteDatabase(name)))
+            failed.add(name);
+    }
+    if (failed.size > 0) {
+        throw new AbloConnectionError(`Could not remove authenticated local data from: ${[...failed].join(', ')}`, { code: 'db_cleanup_failed' });
+    }
+}

package/dist/local/stores/persistenceIdentity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The complete authenticated plane that owns one local replica. The same
+ * participant can have different data in a project, sandbox, or environment;
+ * those replicas must never share a namespace.
+ */
+export interface PersistenceIdentity {
+    readonly participantId: string;
+    readonly participantKind: string;
+    readonly organizationId: string;
+    readonly projectId: string | null;
+    readonly environment: 'sandbox' | 'production' | null;
+    readonly sandboxId: string | null;
+}
+export interface PersistedIdentityMetadata {
+    readonly namespaceVersion?: number;
+    readonly userId: string;
+    readonly workspaceId: string;
+    readonly participantKind?: string;
+    readonly projectId?: string | null;
+    readonly environment?: 'sandbox' | 'production' | null;
+    readonly sandboxId?: string | null;
+}
+export declare const PERSISTENCE_NAMESPACE_VERSION = 2;
+/** Collision-resistant IndexedDB name for one authenticated data plane. */
+export declare function persistenceDatabaseName(identity: PersistenceIdentity, userVersion?: number): Promise<string>;
+/** Defense-in-depth check after namespace lookup and before persisted reads. */
+export declare function persistenceIdentityMatches(info: PersistedIdentityMetadata, identity: PersistenceIdentity): boolean;

package/dist/local/stores/persistenceIdentity.js

@@ -0,0 +1,38 @@
+import { AbloConnectionError } from '@abloatai/transaction/errors';
+export const PERSISTENCE_NAMESPACE_VERSION = 2;
+function canonicalIdentity(identity, userVersion) {
+    return JSON.stringify([
+        PERSISTENCE_NAMESPACE_VERSION,
+        identity.projectId,
+        identity.environment,
+        identity.sandboxId,
+        identity.organizationId,
+        identity.participantKind,
+        identity.participantId,
+        userVersion,
+    ]);
+}
+async function sha256Hex(value) {
+    const cryptoProvider = Reflect.get(globalThis, 'crypto');
+    const subtle = cryptoProvider?.subtle;
+    if (!subtle) {
+        throw new AbloConnectionError('Secure local persistence requires Web Crypto SHA-256 support.', { code: 'db_secure_hash_unavailable' });
+    }
+    const digest = await subtle.digest('SHA-256', new TextEncoder().encode(value));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** Collision-resistant IndexedDB name for one authenticated data plane. */
+export async function persistenceDatabaseName(identity, userVersion = 1) {
+    const digest = await sha256Hex(canonicalIdentity(identity, userVersion));
+    return `ablo_v${PERSISTENCE_NAMESPACE_VERSION}_${digest}`;
+}
+/** Defense-in-depth check after namespace lookup and before persisted reads. */
+export function persistenceIdentityMatches(info, identity) {
+    return (info.namespaceVersion === PERSISTENCE_NAMESPACE_VERSION &&
+        info.userId === identity.participantId &&
+        info.workspaceId === identity.organizationId &&
+        info.participantKind === identity.participantKind &&
+        (info.projectId ?? null) === identity.projectId &&
+        (info.environment ?? null) === identity.environment &&
+        (info.sandboxId ?? null) === identity.sandboxId);
+}

package/dist/local/stores/syncAction.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The persisted local action record consumed by `SyncActionStore`. It is a
+ * client materialization artifact, not a transaction-layer wire shape: the
+ * authoritative broadcast vocabulary is the settlement core's delta wire
+ * schema, while this one adds the local `__class` discriminator IndexedDB uses.
+ */
+import { z } from 'zod';
+export declare const syncActionSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    action: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
+        A: "A";
+        V: "V";
+        C: "C";
+        G: "G";
+        S: "S";
+    }>;
+    data: z.ZodUnknown;
+    __class: z.ZodDefault<z.ZodLiteral<"SyncAction">>;
+}, z.core.$strip>;
+export type SyncAction = z.infer<typeof syncActionSchema>;
+export type SyncActionType = SyncAction['action'];

package/dist/local/stores/syncAction.js

@@ -0,0 +1,16 @@
+/**
+ * The persisted local action record consumed by `SyncActionStore`. It is a
+ * client materialization artifact, not a transaction-layer wire shape: the
+ * authoritative broadcast vocabulary is the settlement core's delta wire
+ * schema, while this one adds the local `__class` discriminator IndexedDB uses.
+ */
+import { z } from 'zod';
+import { syncDeltaActionSchema } from '@abloatai/transaction/wire/delta';
+export const syncActionSchema = z.object({
+    id: z.number(),
+    modelName: z.string(),
+    modelId: z.string(),
+    action: syncDeltaActionSchema,
+    data: z.unknown(),
+    __class: z.literal('SyncAction').default('SyncAction'),
+});

package/dist/local/stores/v1PersistenceDeletion.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Migration-only knowledge of the removed v1 IndexedDB namespace. Nothing in
+ * this module may be used to open or hydrate data; it exists only to find and
+ * delete stores created by clients before persistence namespace v2.
+ *
+ * Remove after the v1 cleanup support window.
+ */
+export declare function v1PersistenceDatabaseNameForDeletion(participantId: string, organizationId: string, userVersion: number): string;

package/dist/local/stores/v1PersistenceDeletion.js

@@ -0,0 +1,16 @@
+/**
+ * Migration-only knowledge of the removed v1 IndexedDB namespace. Nothing in
+ * this module may be used to open or hydrate data; it exists only to find and
+ * delete stores created by clients before persistence namespace v2.
+ *
+ * Remove after the v1 cleanup support window.
+ */
+export function v1PersistenceDatabaseNameForDeletion(participantId, organizationId, userVersion) {
+    const combined = `${participantId}:${organizationId}:${userVersion}`;
+    let hash = 0;
+    for (let index = 0; index < combined.length; index++) {
+        hash = (hash << 5) - hash + combined.charCodeAt(index);
+        hash &= hash;
+    }
+    return `ablo_${Math.abs(hash).toString(16).padStart(8, '0')}`;
+}

package/dist/local/sync/BootstrapFetcher.d.ts

@@ -0,0 +1,284 @@
+/**
+ * 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 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, and the like). */
+    failedModels?: string[];
+    timestamp: number;
+    /**
+     * 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;
+    /**
+     * Present when a paged single-model request stopped at its row limit with
+     * rows remaining: pass it back as the next page's `cursor`. Absent on the
+     * final page, on unpaged responses, and from servers that predate paging.
+     */
+    nextCursor?: string;
+}
+export interface BootstrapFetchResult {
+    notModified: boolean;
+    data?: BootstrapData;
+    etag?: string | null;
+}
+export interface BootstrapOptions {
+    /**
+     * Full base URL of the sync server's HTTP API, **including the `/api`
+     * prefix**. The bootstrap endpoint is appended as `/sync/bootstrap`, so
+     * the final request hits `${baseUrl}/sync/bootstrap`.
+     *
+     * Example: `'http://localhost:8080/api'` → `http://localhost:8080/api/sync/bootstrap`
+     *
+     * Default: `'http://localhost:8080/api'`.
+     */
+    baseUrl?: string;
+    /**
+     * 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`. Retained so code that constructs
+     * {@link BootstrapFetcher} directly keeps its cache namespace.
+     */
+    organizationId?: string;
+    syncGroups?: string[];
+    maxRetries?: number;
+    retryDelay?: number;
+    /**
+     * How long to wait for the server to START responding (response headers), in
+     * milliseconds. Default 20000 (20 seconds).
+     *
+     * Deliberately NOT a bound on the whole download: a cold-start snapshot can
+     * be tens of megabytes, and its transfer time depends on the connection. A
+     * healthy download that is actively delivering bytes is never aborted, no
+     * matter how long it takes — {@link stallTimeout} guards the body instead.
+     */
+    fetchTimeout?: number;
+    /**
+     * The longest quiet gap allowed between body chunks while downloading, in
+     * milliseconds. Default 15000 (15 seconds). This is the progress watchdog:
+     * it aborts a download whose stream has gone silent (dead connection,
+     * hung proxy) without ever penalizing a slow-but-moving transfer.
+     */
+    stallTimeout?: number;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    runtime?: RuntimeContext;
+}
+import type { RuntimeContext } from '../RuntimeContext.js';
+import { type AuthTokenGetter } from '@abloatai/transaction/auth/credentialSource';
+import { type ValidatedServerDelta } from './schemas.js';
+export declare class BootstrapFetcher {
+    private options;
+    private readonly 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.
+     */
+    private readonly activeControllers;
+    /**
+     * 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}.
+     */
+    private readonly flights;
+    /** Warn about schema drift at most once per helper. */
+    private schemaDriftWarned;
+    /**
+     * 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.
+     */
+    private cancelActive;
+    /**
+     * 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(): number;
+    get baseUrl(): string;
+    /**
+     * 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.
+     */
+    private warnOnSchemaDrift;
+    /** Fetch the server's per-model schema surface and warn precisely — or stay
+     *  silent when every model this client declares matches (additive lead). */
+    private resolveSemanticDrift;
+    private warnWholeHashDrift;
+    constructor(options: BootstrapOptions);
+    /**
+     * Update the offline-cache namespace once auth has resolved the server-side
+     * account scope. This is intentionally not a public organizationId input.
+     */
+    setCacheScope(cacheScope: string): void;
+    setSyncGroups(syncGroups: readonly string[] | undefined): void;
+    /**
+     * 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;
+    /**
+     * 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)
+     */
+    fetchBootstrap(lastSyncId?: number, 
+    /**
+     * 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>;
+    /**
+     * 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.
+     */
+    private flightKey;
+    /** One bootstrap, start to finish. {@link fetchBootstrap} owns whether it runs. */
+    private runBootstrap;
+    /**
+     * 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.
+     */
+    private fetchWithRetries;
+    /**
+     * 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.
+     */
+    private fetchChunkedBootstrap;
+    /**
+     * Fetch bootstrap with ETag, returning 304 hints
+     */
+    fetchBootstrapWithETag(): Promise<BootstrapFetchResult>;
+    private fetchWithETagUsing;
+    /**
+     * 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).
+     */
+    private readJsonWithStallGuard;
+    /**
+     * 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.
+     */
+    private fetchOnce;
+    private fetchOnceWith;
+    /**
+     * 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).
+     */
+    fetchEntity(modelName: string, id: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Clear all cached bootstrap data
+     */
+    clearCache(): void;
+    private getBootstrapCacheKey;
+    private saveCachedBootstrap;
+    private loadCachedBootstrap;
+    /**
+     * 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(): void;
+    /**
+     * Helper to delay execution
+     */
+    private delay;
+    /**
+     * Get health status of sync engine
+     */
+    checkHealth(): Promise<boolean>;
+}
+/**
+ * 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 declare function mergeBootstrapChunks(chunks: readonly BootstrapData[]): BootstrapData;