@abloatai/ablo 0.34.1 → 0.35.0

package/dist/source/footprint.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The footprint — every object Ablo leaves inside a customer's own database,
+ * declared once.
+ *
+ * Four things need this list and each used to carry its own copy: the setup SQL
+ * that creates the objects, the replication runtime that reads them, the audit
+ * that tells a customer what Ablo put there, and (eventually) the teardown that
+ * removes them. They drifted, as hand-maintained copies do — `ABLO_PUBLICATION`
+ * was declared twice, under a comment insisting the literals "MUST equal the
+ * CLI's" and pointing at a file that no longer held it, and the audit went on
+ * looking for a footprint from an earlier era while seeing none of what Ablo
+ * installs today.
+ *
+ * The audit is the copy that matters most. A customer runs it to answer "what is
+ * still in my database", and a stale list answers "nothing" — which reads as
+ * clean rather than as unexamined. So the list lives here, every consumer
+ * derives from it, and an object added to Ablo's setup is visible to the audit
+ * because it could not have been added anywhere else.
+ *
+ * Retired objects stay in the list, marked {@link FootprintArtifact.retired}.
+ * They are no longer installed, but a database connected to an older Ablo still
+ * holds them, and those are precisely the ones a customer would never think to
+ * look for.
+ */
+/** The Postgres object class, which decides how the audit looks it up. */
+export type FootprintKind = 'publication' | 'slot' | 'role' | 'table' | 'type';
+export interface FootprintArtifact {
+    readonly kind: FootprintKind;
+    readonly name: string;
+    /** What it is for, in the words a customer reading an audit would want. */
+    readonly purpose: string;
+    /**
+     * Installed only for a data source that reports through the signed endpoint
+     * rather than the write-ahead log.
+     */
+    readonly endpointOnly?: boolean;
+    /**
+     * No longer installed by any current version. A database that once ran an
+     * older Ablo still holds it; the audit reports it so it can be cleaned up.
+     */
+    readonly retired?: boolean;
+    /**
+     * What it costs to leave behind, when leaving it behind costs something. The
+     * audit leads with this, because "you still have an object named X" is not a
+     * reason to act and "this one is retaining your write-ahead log" is.
+     */
+    readonly hazard?: string;
+}
+/**
+ * The publication Ablo's replication reads from. Constant by design: a
+ * publication declares what streams, and several readers are meant to share one
+ * (`publication_names` is a per-stream option, not slot state).
+ */
+export declare const ABLO_PUBLICATION = "ablo_publication";
+/**
+ * The replication slot that holds Ablo's position in the write-ahead log.
+ *
+ * Constant, and it should not be — a slot stores ONE position, so two
+ * connections sharing this name compete for the same marker. It is why a
+ * database can be connected to one plane at a time. ADR 0020 derives it per
+ * connection; {@link isValidReplicationSlotName} is the check a derived name
+ * has to pass.
+ */
+export declare const ABLO_REPLICATION_SLOT = "ablo_slot";
+/** The least-privilege login Ablo reads with. Per-connection under ADR 0020. */
+export declare const ABLO_REPLICATION_ROLE = "ablo_replicator";
+/** The separate least-privilege login used only for row writes. */
+export declare const ABLO_WRITE_ROLE = "ablo_writer";
+/** The bookkeeping table that makes a retried write land once. */
+export declare const ABLO_IDEMPOTENCY_TABLE = "ablo_idempotency";
+/** The transactional outbox an endpoint source reports through. */
+export declare const ABLO_OUTBOX_TABLE = "ablo_outbox";
+/**
+ * Postgres will not accept a replication slot name outside this shape — the
+ * check is in `ReplicationSlotValidateNameInternal`, and identifier quoting does
+ * not exempt a name from it. Anything derived into a slot name is validated
+ * here, at the point it is derived, rather than failing at the point it is used.
+ */
+export declare const REPLICATION_SLOT_NAME: RegExp;
+export declare function isValidReplicationSlotName(name: string): boolean;
+/** The four plane axes a connection is identified by. */
+export interface FootprintPlane {
+    readonly organizationId: string;
+    readonly environment: string;
+    /** '' for the organization-default project. */
+    readonly projectId?: string;
+    /** '' for the default sandbox. */
+    readonly sandboxId?: string;
+}
+/** The names one connection owns. Nothing here is shared with another plane. */
+export interface FootprintNames {
+    readonly slot: string;
+    readonly publication: string;
+    readonly replicationRole: string;
+    readonly writeRole: string;
+}
+/**
+ * The objects this connection owns, named so no other connection can claim them.
+ *
+ * A slot stores ONE position, so two connections sharing a name compete for the
+ * same marker and Postgres reports nothing — which is why the constants these
+ * replace made a database connectable to one plane at a time. The publication
+ * and roles are derived from the same digest so a database's footprint reads as
+ * one set per connection rather than a mix of shared and private objects.
+ *
+ * Stable: the same plane always derives the same names, so re-running setup is a
+ * no-op rather than a second installation.
+ */
+export declare function footprintNamesFor(plane: FootprintPlane): FootprintNames;
+/** Everything Ablo has ever put in a customer's database, current and retired. */
+export declare const ABLO_FOOTPRINT: readonly FootprintArtifact[];

package/dist/source/idempotency.js

@@ -11,8 +11,8 @@
  */
 import { createHash } from 'node:crypto';
 import { z } from 'zod';
-import { AbloValidationError } from '../errors.js';
-import { COMMIT_CORRELATION_ID_MAX_LENGTH, correlationIdSchema, } from '../wire/commit.js';
+import { AbloValidationError } from '../transaction/errors.js';
+import { COMMIT_CORRELATION_ID_MAX_LENGTH, correlationIdSchema, } from '../transaction/wire/commit.js';
 const SOURCE_ECHO_TRANSACTION_ID_PREFIX = 'ablo_echo_tx_v1:';
 const sourceOperationTransactionIdSchema = z
     .string()

package/dist/source/index.d.ts

@@ -20,3 +20,4 @@ export { prismaDataSource, type PrismaLike, type PrismaDataSourceOptions } from
 export { adapterTableMigrations, endpointOutboxMigrations, idempotencyLedgerMigrations, } from './migrations.js';
 export { createKyselyMutationAdapter, createKyselyMutationCore, kyselyDataSource, kyselyDirectMutation, kyselyOperationRowId, type KyselyCompiledQuery, type KyselyDeleteBuilder, type KyselyInsertBuilder, type KyselyInsertValuesBuilder, type KyselyLike, type KyselyMutationCore, type KyselyReturningExecutable, type KyselySelectBuilder, type KyselyTransactionBuilder, type KyselyUpdateBuilder, type KyselyUpdateSetBuilder, } from './adapters/kysely.js';
 export { sourceOperationsIntentHash, sourceChangeIntentHash, assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceEchoTransactionIdSchema, encodeSourceEchoTransactionId, decodeSourceEchoTransactionId, type SourceEchoTransactionId, } from './idempotency.js';
+export { ABLO_FOOTPRINT, ABLO_PUBLICATION, ABLO_REPLICATION_SLOT, ABLO_REPLICATION_ROLE, ABLO_WRITE_ROLE, ABLO_IDEMPOTENCY_TABLE, ABLO_OUTBOX_TABLE, REPLICATION_SLOT_NAME, isValidReplicationSlotName, footprintNamesFor, type FootprintArtifact, type FootprintKind, type FootprintNames, type FootprintPlane, } from './footprint.js';

package/dist/source/index.js

@@ -25,3 +25,6 @@ export { prismaDataSource } from './adapters/prisma.js';
 export { adapterTableMigrations, endpointOutboxMigrations, idempotencyLedgerMigrations, } from './migrations.js';
 export { createKyselyMutationAdapter, createKyselyMutationCore, kyselyDataSource, kyselyDirectMutation, kyselyOperationRowId, } from './adapters/kysely.js';
 export { sourceOperationsIntentHash, sourceChangeIntentHash, assertSourceIdempotencyIntent, assertSourceIdempotencyRetention, sourceEchoTransactionIdSchema, encodeSourceEchoTransactionId, decodeSourceEchoTransactionId, } from './idempotency.js';
+// What Ablo leaves inside a customer's database, declared once — read by the
+// setup SQL, the replication runtime, and the audit that reports it back.
+export { ABLO_FOOTPRINT, ABLO_PUBLICATION, ABLO_REPLICATION_SLOT, ABLO_REPLICATION_ROLE, ABLO_WRITE_ROLE, ABLO_IDEMPOTENCY_TABLE, ABLO_OUTBOX_TABLE, REPLICATION_SLOT_NAME, isValidReplicationSlotName, footprintNamesFor, } from './footprint.js';

package/dist/source/next.d.ts

@@ -19,7 +19,7 @@
  * For hand-written handlers, or another framework, call the core `dataSource()`
  * directly and export its result however that framework expects.
  */
-import type { SchemaRecord } from '../schema/schema.js';
+import type { SchemaRecord } from '../transaction/schema/schema.js';
 import { type DataSourceOptions } from './factory.js';
 /**
  * The options for `dataSourceNext`, which are exactly the core

package/dist/source/signing.d.ts

@@ -25,8 +25,15 @@ export interface SourceSignatureOptions {
 }
 /** Inputs to {@link verifyAbloSourceRequest}. */
 export interface SourceSignatureVerificationOptions {
-    /** The incoming request, whose headers carry the signature to check. */
-    readonly request: Request;
+    /**
+     * The incoming request, whose headers carry the signature to check. Any
+     * request-shaped object works: a fetch `Request` (its `Headers` is read with
+     * `.get`), or a plain header record like Node's `req.headers` — matching
+     * what the runtime has always accepted.
+     */
+    readonly request: {
+        readonly headers?: Headers | Record<string, string | string[] | undefined>;
+    };
     /** The request body, which must match what was signed. */
     readonly body: string;
     /** The API key to verify against. */

package/dist/source/signing.js

@@ -43,7 +43,10 @@ function getHeader(request, name) {
         return headers.get(name);
     }
     const record = headers;
-    return record[name] ?? record[name.toLowerCase()] ?? null;
+    const value = record[name] ?? record[name.toLowerCase()] ?? null;
+    // Node folds repeated headers into an array; the signature headers are
+    // single-valued, so the first entry is the one that was signed.
+    return Array.isArray(value) ? (value[0] ?? null) : value;
 }
 /**
  * Parse a `webhook-signature` header per the Standard Webhooks spec.

package/dist/source/types.d.ts

@@ -9,7 +9,9 @@
  * and context types your source implements. {@link sourceEventForOperation}
  * builds a change-event marker from an operation.
  */
-import type { Environment } from '../environment.js';
+import type { Environment } from '../transaction/environment.js';
+import type { CommitOperationType, OnStaleMode } from '../transaction/coordination/schema.js';
+import type { ParticipantKind } from '../transaction/types/participant.js';
 /** A scalar value that can appear in a source filter. */
 export type SourcePrimitive = string | number | boolean | null;
 /**
@@ -58,7 +60,7 @@ export type SourceListResult<Row> = readonly Row[] | SourceListPage<Row>;
  */
 export interface SourceRequestContext {
     readonly participantId?: string;
-    readonly participantKind?: 'user' | 'agent' | 'system';
+    readonly participantKind?: ParticipantKind;
     readonly organizationId?: string;
     /** Trusted project plane selected by the authenticating credential. */
     readonly projectId?: string;
@@ -83,13 +85,13 @@ export interface SourceRequestContext {
  * do when the row changed since it was read at `readAt`.
  */
 export interface SourceOperation {
-    readonly type: 'CREATE' | 'UPDATE' | 'DELETE' | 'ARCHIVE' | 'UNARCHIVE';
+    readonly type: CommitOperationType;
     readonly model: string;
     readonly id?: string | null;
     readonly input?: Record<string, unknown> | null;
     readonly transactionId?: string | null;
     readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
+    readonly onStale?: OnStaleMode | null;
 }
 /**
  * A computed change to one row, ready to append to the change log. Your

package/dist/source/types.js

@@ -9,7 +9,7 @@
  * and context types your source implements. {@link sourceEventForOperation}
  * builds a change-event marker from an operation.
  */
-import { AbloValidationError } from '../errors.js';
+import { AbloValidationError } from '../transaction/errors.js';
 /**
  * Build the {@link SourceEvent} marker you should record in your outbox table,
  * within the same transaction as the row change it describes.

package/dist/stores/ObjectStore.d.ts

@@ -2,7 +2,7 @@
  * The IndexedDB-backed object store: durable, per-model record storage for
  * the browser. See {@link ObjectStore}.
  */
-import type { ModelMetadata } from '../types/index.js';
+import type { ModelMetadata } from '../transaction/types/index.js';
 import type { ObjectStoreContract } from './ObjectStoreContract.js';
 /**
  * IDB transaction options type (TypeScript's lib.dom.d.ts may be outdated)

package/dist/stores/SyncActionStore.d.ts

@@ -2,7 +2,7 @@
  * A local, IndexedDB-backed store for the sync actions (change deltas) the
  * server sends. See {@link SyncActionStore}.
  */
-import type { SyncAction } from '../types/index.js';
+import { type SyncAction } from './syncAction.js';
 /**
  * Stores the sync actions (the change deltas) the server sends, keyed by
  * their sync id, and tracks which ones have been applied. It keeps a

package/dist/stores/SyncActionStore.js

@@ -3,8 +3,8 @@
  * server sends. See {@link SyncActionStore}.
  */
 // Uses native IndexedDB for maximum performance
-import { z } from 'zod';
 import { getContext } from '../context.js';
+import { syncActionSchema } from './syncAction.js';
 /**
  * The validation boundary for rows read back from the store. A row may have
  * been written by an earlier session, so this build cannot assume its shape.
@@ -13,17 +13,9 @@ import { getContext } from '../context.js';
  * {@link SyncAction}. A row that fails to parse is dropped and logged rather
  * than replayed as a malformed delta.
  */
-const storedSyncActionSchema = z.object({
-    id: z.number(),
-    modelName: z.string(),
-    modelId: z.string(),
-    action: z.enum(['I', 'U', 'A', 'D', 'C', 'G', 'S', 'V']),
-    data: z.unknown(),
-    __class: z.literal('SyncAction').default('SyncAction'),
-});
 /** Parse one stored row into a SyncAction, or `null` (dropped + logged). */
 function toSyncAction(row) {
-    const parsed = storedSyncActionSchema.safeParse(row);
+    const parsed = syncActionSchema.safeParse(row);
     if (!parsed.success) {
         getContext().logger.debug('[SyncActionStore] Dropping malformed stored sync action', {
             issues: parsed.error.issues.map((i) => i.path.join('.')).join(', '),

package/dist/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/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 '../transaction/wire/delta.js';
+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/surface.d.ts

@@ -19,9 +19,9 @@
  * tuple, so it is the one list of model-verb names a generated summary can
  * describe.
  */
-export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "get", "getAll", "getCount", "create", "update", "delete", "claim", "track", "join", "onChange"];
+export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "local", "create", "update", "delete", "claim", "track", "join", "onChange"];
 /**
- * The option keys accepted by `list`, `getAll`, and `onChange`, matching the
+ * The option keys accepted by `local.list` and `onChange`, matching the
  * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
  * `state`, not `scope`.
  */
@@ -30,7 +30,7 @@ export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orde
  * 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", "persistence", "durableWrites", "commitOutbox", "commitOutboxScope", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "persistence", "durableWrites", "commitOutbox", "commitOutboxScope", "transport", "debug", "logLevel", "logger", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser", "collaborationEvents", "plugins", "wait"];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
 export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -23,9 +23,7 @@
 export const PUBLIC_MODEL_VERBS = [
     'retrieve',
     'list',
-    'get',
-    'getAll',
-    'getCount',
+    'local',
     'create',
     'update',
     'delete',
@@ -36,7 +34,7 @@ export const PUBLIC_MODEL_VERBS = [
 ];
 // ── the read/list query option surface ─────────────────────────────────────
 /**
- * The option keys accepted by `list`, `getAll`, and `onChange`, matching the
+ * The option keys accepted by `local.list` and `onChange`, matching the
  * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
  * `state`, not `scope`.
  */
@@ -64,10 +62,14 @@ export const PUBLIC_ABLO_OPTION_KEYS = [
     'transport',
     'debug',
     'logLevel',
+    'logger',
     'authToken',
     'baseURL',
     'fetch',
     'defaultHeaders',
     'defaultQuery',
     'dangerouslyAllowBrowser',
+    'collaborationEvents',
+    'plugins',
+    'wait',
 ];

package/dist/sync/BootstrapFetcher.d.ts

@@ -27,6 +27,12 @@ export interface BootstrapData {
      * 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;
@@ -58,8 +64,23 @@ export interface BootstrapOptions {
     syncGroups?: string[];
     maxRetries?: number;
     retryDelay?: number;
-    /** How long to wait for a single fetch before timing out, in milliseconds. Default 10000 (10 seconds). */
+    /**
+     * 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
@@ -74,13 +95,48 @@ export interface BootstrapOptions {
      */
     getAuthToken?: AuthTokenGetter;
 }
-import { type AuthTokenGetter } from '../auth/credentialSource.js';
+import { type AuthTokenGetter } from '../transaction/auth/credentialSource.js';
 import { type ValidatedServerDelta } from './schemas.js';
 export declare class BootstrapFetcher {
     private options;
-    private abortController;
+    /**
+     * 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
@@ -100,6 +156,10 @@ export declare class BootstrapFetcher {
      * 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
@@ -127,14 +187,54 @@ export declare class BootstrapFetcher {
      * 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 the actual fetch request with timeout protection
+     * 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 performFetch;
+    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.
@@ -149,7 +249,12 @@ export declare class BootstrapFetcher {
     private saveCachedBootstrap;
     private loadCachedBootstrap;
     /**
-     * Abort ongoing fetch request
+     * Abort every ongoing bootstrap request (including all chunks of a
+     * chunked cold start). Entity self-heal fetches are unaffected.
+     *
+     * The flight registry is cleared first and synchronously, so a caller that
+     * bootstraps again in the same tick starts a fresh request rather than
+     * joining the one being torn down.
      */
     abort(): void;
     /**
@@ -161,3 +266,15 @@ export declare class BootstrapFetcher {
      */
     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;