@abloatai/humans 0.37.0

package/dist/local/RuntimeContext.d.ts

@@ -0,0 +1,52 @@
+/**
+ * RuntimeContext — Runtime dependency container
+ *
+ * All SDK classes receive this context at construction time.
+ * It bundles every injectable dependency so constructors stay clean.
+ */
+import type { Logger, ObservabilityProvider, Analytics, SessionErrorDetector, OnlineStatusProvider, ModelDebugLoggerContract, MutationExecutor, RuntimeConfig } from './interfaces/index.js';
+import type { ModelMetadata } from '@abloatai/transaction/types';
+export interface RuntimeContext {
+    /** Structured logger */
+    logger: Logger;
+    /** Error tracking & performance monitoring */
+    observability: ObservabilityProvider;
+    /** Product analytics (optional) */
+    analytics?: Analytics;
+    /** Session error detection for auth redirect decisions */
+    sessionErrorDetector: SessionErrorDetector;
+    /** Network connectivity detection */
+    onlineStatus: OnlineStatusProvider;
+    /** Model operation debug logging (optional, dev-only) */
+    modelDebugLogger?: ModelDebugLoggerContract;
+    /** Backend mutation transport (GraphQL, REST, etc.) */
+    mutationExecutor: MutationExecutor;
+    /** Application-specific sync configuration */
+    config: RuntimeConfig;
+    /**
+     * Model metadata lookup. Injected by the client (it wires this from its
+     * `ModelRegistry`) so the settlement core can resolve a model's metadata
+     * without importing the registry — the dependency inversion that keeps the
+     * core free of the client's `Model` layer (ADR 0013).
+     */
+    getModelMetadata: (name: string) => ModelMetadata | undefined;
+}
+export { noopLogger } from '@abloatai/transaction/logger';
+/** No-op observability — silently discards all observability calls */
+export declare const noopObservability: ObservabilityProvider;
+/** No-op analytics — silently discards all analytics calls */
+export declare const noopAnalytics: Analytics;
+/** Browser-native online status provider */
+export declare const browserOnlineStatus: OnlineStatusProvider;
+/** Session error detector — delegates to AbloSessionError so detection is
+ *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
+export declare const defaultSessionErrorDetector: SessionErrorDetector;
+/**
+ * Fallback config used when the context is read before
+ * `createSyncEngine(...)` has initialized it (tests, early-boot code
+ * paths). An empty `modelCreatePriority` means every model falls through
+ * to `defaultCreatePriority`, so ordering is flat — fine for tests that
+ * never exercise FK ordering; consumers who do rely on it should finish
+ * wiring the engine before the first `create()` fires.
+ */
+export declare const emptyConfig: RuntimeConfig;

package/dist/local/RuntimeContext.js

@@ -0,0 +1,80 @@
+/**
+ * RuntimeContext — Runtime dependency container
+ *
+ * All SDK classes receive this context at construction time.
+ * It bundles every injectable dependency so constructors stay clean.
+ */
+import { AbloSessionError } from '@abloatai/transaction/errors';
+// ─────────────────────────────────────────────
+// No-op defaults for optional dependencies
+// ─────────────────────────────────────────────
+// Re-exported, not redeclared. `@abloatai/transaction/logger` owns the no-op that
+// sits beside the `Logger` port. This package held a second, behaviourally
+// identical copy, and half of it imported the canonical one while the other
+// half imported this — so any change of semantics there would have reached
+// only one side, invisibly, because the identifier reads the same at both.
+export { noopLogger } from '@abloatai/transaction/logger';
+/** No-op observability — silently discards all observability calls */
+export const noopObservability = {
+    setContext() { },
+    setConnectionState() { },
+    breadcrumb() { },
+    captureRollback() { },
+    captureMutationFailure() { },
+    captureBootstrapFailure() { },
+    captureReconciliation() { },
+    captureDeltaRetryExhausted() { },
+    captureWebSocketError() { },
+    captureSelfHealing() { },
+    captureClaim() { },
+    captureConflict() { },
+    captureCommitZeroSyncId() { },
+    startSpan(_name, _op, fn, _attributes) {
+        return fn();
+    },
+    async startSpanAsync(_name, _op, fn, _attributes) {
+        return fn();
+    },
+};
+/** No-op analytics — silently discards all analytics calls */
+export const noopAnalytics = {
+    capture() { },
+};
+/** Browser-native online status provider */
+export const browserOnlineStatus = {
+    isOnline() {
+        // Only `navigator.onLine === false` is the MDN-reliable "definitely offline"
+        // signal. Don't use `!navigator.onLine`: Node 18+ exposes a global
+        // `navigator` whose `onLine` is `undefined`, which `!` would read as offline —
+        // wedging every Node/server client (agents, worker, MCP) into a false offline.
+        return !(typeof navigator !== 'undefined' && navigator.onLine === false);
+    },
+};
+/** Session error detector — delegates to AbloSessionError so detection is
+ *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
+export const defaultSessionErrorDetector = {
+    isSessionError(error) {
+        if (error && typeof error === 'object' && 'isSessionError' in error) {
+            return error.isSessionError;
+        }
+        return false;
+    },
+    isSessionErrorResponse(status, body) {
+        return AbloSessionError.isSessionErrorResponse(status, body);
+    },
+};
+/**
+ * Fallback config used when the context is read before
+ * `createSyncEngine(...)` has initialized it (tests, early-boot code
+ * paths). An empty `modelCreatePriority` means every model falls through
+ * to `defaultCreatePriority`, so ordering is flat — fine for tests that
+ * never exercise FK ordering; consumers who do rely on it should finish
+ * wiring the engine before the first `create()` fires.
+ */
+export const emptyConfig = {
+    modelCreatePriority: new Map(),
+    defaultCreatePriority: 40,
+    defaultNonCreatePriority: 50,
+    essentialFields: {},
+    classNameFallbackMap: {},
+};

package/dist/local/SyncClient.d.ts

@@ -0,0 +1,516 @@
+/**
+ * Applies model mutations and manages the offline write queue. The
+ * SyncClient turns local create, update, delete, and archive calls into
+ * optimistic changes, holds them while the client is offline, sends them to
+ * the server when connectivity returns, and resolves conflicts when the
+ * server's version of a row disagrees with the local one. It sits between the
+ * reactive object pool and the {@link MutationQueue} that delivers writes
+ * over the network.
+ */
+import { InstanceCache } from './InstanceCache.js';
+import { Model } from './Model.js';
+import type { AppliedChange } from '../plugin.js';
+import type { RuntimeContext } from './RuntimeContext.js';
+import { EventEmitter } from 'events';
+import { MutationQueue, type QueuedMutation } from './transactions/mutations/MutationQueue.js';
+import { type CommitLatencySample } from './transactions/mutations/commitLatency.js';
+import { type UnconfirmedWritesMetrics } from './transactions/mutations/UnconfirmedWrites.js';
+import type { DurableWriteStore } from './transactions/mutations/durableWriteStore.js';
+import type { Database } from './Database.js';
+import type { WriteOptions } from './interfaces/index.js';
+import { LogPosition } from './logPosition.js';
+interface SyncObserver {
+    onSync?: (event: SyncEvent) => void;
+}
+interface SyncEvent {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'rollback';
+    modelType: string;
+    model?: Model;
+    modelId?: string;
+    transactionType?: string;
+}
+interface SyncState {
+    connectionState: 'connected' | 'disconnected' | 'connecting';
+    pendingMutations: number;
+    lastSyncAt?: Date;
+    error?: Error;
+}
+export interface RehydrationStats {
+    added: number;
+    updated: number;
+    removed: number;
+    skipped: number;
+    healed: number;
+    elapsedMs: number;
+}
+export declare class SyncClient extends EventEmitter {
+    private readonly runtime;
+    private objectPool;
+    private database;
+    private readonly mutationPersistence;
+    private readonly reconnectDrain;
+    private get mutationExecutor();
+    private networkMonitor;
+    /**
+     * @internal — test seam, stripped from the published declarations by
+     * `stripInternal`. Unit suites deliver queue lifecycle events directly.
+     */
+    readonly mutationQueue: MutationQueue;
+    private observers;
+    private userId;
+    private organizationId;
+    private pendingStages;
+    private readonly commitOutboxNamespace;
+    /** Compatibility view for diagnostics; transaction state lives in the queue. */
+    private get pendingMutations();
+    /**
+     * Tracks the ids of transactions the client has applied optimistically but
+     * the server has not yet confirmed. When a delta arrives, the receive path
+     * consults this set to recognize the echo of the client's own mutation and
+     * skip the now-redundant pool update; the IndexedDB write still runs,
+     * because the delta is the authoritative version of the row. Without this
+     * discriminator, an optimistically applied delete followed by a
+     * server-confirmed create echo would resurrect the row for the window
+     * between the two confirmations.
+     *
+     * The set is bounded with first-in-first-out eviction, and
+     * {@link SyncClient.getEchoMetrics} exposes its counters.
+     */
+    private readonly echoTracker;
+    private connectionState;
+    private isDisposed;
+    /**
+     * The client's position in the global delta order, held as the single
+     * canonical {@link LogPosition} instance. The store advances `applied` and
+     * `persisted` as deltas land, the queue advances `acked` on commit
+     * responses, and snapshots and claims read `readFloor`.
+     */
+    readonly position: LogPosition;
+    constructor(objectPool: InstanceCache, database: Database, commitOutbox?: DurableWriteStore, commitOutboxNamespace?: string, runtime?: RuntimeContext);
+    /**
+     * Setup network monitoring handlers
+     */
+    private setupNetworkMonitoring;
+    /**
+     * Handle transaction rollback. Two distinct shapes flow through this
+     * event:
+     *
+     *   1. **Server-rejected rollback** (`reason === 'permanent_error'`,
+     *      `'max_retries_exhausted'`, `'conflict_server_wins'`) — the
+     *      optimistic state is wrong, the row exists, restore previous
+     *      state and notify the UI.
+     *
+     *   2. **Local-cancellation cleanup** (`reason === 'model_cancelled'`,
+     *      `'cascade_parent_deleted'`) — the user deleted this model (or
+     *      its parent), so a pending UPDATE on it gets cancelled. There's
+     *      nothing to restore (the model is doomed) and no UI notification
+     *      needed (the delete itself already triggered re-renders). Just
+     *      discard the optimistic state silently.
+     *
+     * Treating both paths the same caused the deletion-flicker bug: every
+     * cancelled update on a multi-child record fired a per-model observer
+     * event and a `[SyncClient.rollback]` warn, producing N renders and N
+     * spam log lines for one user-initiated delete.
+     */
+    private setupTransactionRollbackHandling;
+    /**
+     * Forward reconciliation requests from the {@link MutationQueue} to the
+     * sync layer. When delta confirmation times out, the queue emits
+     * `reconciliation:needed` instead of rolling back, so optimistic state the
+     * server may already have committed is never destroyed.
+     */
+    private setupReconciliationForwarding;
+    /**
+     * Persist unconfirmed transactions to IndexedDB. When delta-confirmation
+     * retries are exhausted, the transaction is cached so it survives a tab
+     * close. On the next session, a WebSocket reconnect and delta catch-up
+     * deliver the missing deltas and confirm the transaction.
+     */
+    private setupAwaitingTransactionPersistence;
+    /** Persist an unconfirmed transaction to IndexedDB (never rejects — failures are captured). */
+    private persistAwaitingTransaction;
+    /** Drop the persisted awaiting-row once confirmed (never rejects). */
+    private removeAwaitingTransaction;
+    /**
+     * Initialize sync client with authentication
+     */
+    initialize(userId: string, organizationId: string): Promise<void>;
+    /**
+     * The organization this client writes under (set by `initialize`).
+     * Read by the model proxy so `create()` defaults `organizationId` the
+     * same way the mutator path does — `null` until identity is wired.
+     */
+    getOrganizationId(): string | null;
+    /**
+     * Self-healing helper for individual model records.
+     *
+     * Two registry-driven repair passes run on every row hydrated from
+     * IndexedDB or merged from a delta:
+     *
+     * 1. **Auto-fill** — for each `autoFill` rule the consumer's schema
+     *    declares on this model, copy the corresponding identity value
+     *    (`organizationId` / `userId`) onto the row when it's missing.
+     *    Repairs rows from a past version that didn't write the field.
+     *
+     * 2. **Required-field gate** — if the row is missing any field listed
+     *    in the model's `requiredFields`, return `null` so the caller
+     *    skips this record. Used for FK columns whose absence renders the
+     *    row unrecoverable (e.g. a Block with no sectionId).
+     *
+     * The engine itself is product-neutral: model identity (which fields
+     * to back-fill, which absences are fatal) lives entirely in the
+     * consumer schema.
+     */
+    healModelRecord(modelType: string, data: Record<string, unknown>): {
+        data: Record<string, unknown>;
+        healed: boolean;
+    } | null;
+    /**
+     * Hydrate InstanceCache with data from Database
+     * Called after bootstrap is complete
+     */
+    hydrateFromDatabase(): Promise<void>;
+    /**
+     * Re-hydrate InstanceCache from IndexedDB when the pool already has data.
+     *
+     * Unlike hydrateFromDatabase() (which uses addBatch and skips existing IDs),
+     * this method properly:
+     *   1. Upserts models — updates existing models in-place, adds new ones
+     *   2. Removes ghosts — deletes models from the pool that no longer exist in IndexedDB
+     *
+     * Used by background bootstrap, network recovery, and server-triggered re-bootstrap.
+     */
+    rehydrateFromDatabase(): Promise<RehydrationStats>;
+    /**
+     * Apply a mutation to a model optimistically and queue it for server sync.
+     * IndexedDB is updated only once the server confirms the change with a delta
+     * packet.
+     *
+     * A model's changes are captured before the pool action runs, because a pool
+     * operation such as an upsert can clear the model's local change set;
+     * capturing first ensures those changes are never lost. The captured set is
+     * frozen and handed to {@link queueMutation}.
+     */
+    private mutate;
+    private pendingChangedTypes;
+    private markModelChanged;
+    /**
+     * Capture model changes immutably BEFORE any pool operations
+     * This prevents the fragile pattern of reading changes after state modification
+     */
+    private captureModelChanges;
+    /** Add new model (CREATE) - works offline */
+    add(model: Model, options?: WriteOptions): void;
+    /** Update existing model (UPDATE) - works offline */
+    update(model: Model, options?: WriteOptions): void;
+    /**
+     * Update existing model with pre-computed changes.
+     * Used by saveManyOptimized when incoming models have empty change-tracking
+     * (e.g. freshly constructed cell models from a bulk document decomposition).
+     */
+    updateWithChanges(model: Model, changes?: Record<string, unknown>): void;
+    /** Expose the GraphQL client for atomic mutations (e.g., createSectionWithBlocks).
+     *  Used by SyncedStore for operations that bypass the transaction queue
+     *  but still need optimistic pool updates at the sync layer. */
+    get gql(): import("./interfaces/index.js").MutationExecutor;
+    /** Delete model (DELETE) - works offline */
+    delete(model: Model, options?: WriteOptions): void;
+    /**
+     * Upload a file and create its attachment record. The upload runs through
+     * the {@link MutationQueue}, and a model is built from the server's
+     * response and added to the pool.
+     */
+    uploadFile(file: File, options: {
+        id: string;
+        attachableType: string;
+        attachableId: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Model | null>;
+    /**
+     * Batch upload files — single GraphQL call + parallel S3 PUTs.
+     *
+     * Returns the raw `Model[]` built by the object pool (typename is
+     * determined by the payload the server returns — currently always
+     * `Attachment`). The SDK has no knowledge of app-specific model classes,
+     * so it cannot honestly claim a narrower return type; consumers that
+     * need an `Attachment[]` project through their own typed accessor
+     * (e.g. `store.query.attachments.findMany({ where: { id: IN ids } })`)
+     * after the upload resolves.
+     */
+    batchUploadFiles(files: File[], options: {
+        ids: string[];
+        attachableType: string;
+        attachableId: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Model[]>;
+    /** Archive model (ARCHIVE) - works offline */
+    archive(model: Model): void;
+    /**
+     * Append a mutation to the pending queue and schedule its sync work.
+     *
+     * IndexedDB persistence and the server push are deferred to a microtask, so
+     * many pushes within the same tick collapse into a single serialization and
+     * a single process call. Without the deferral, queueing a hundred mutations
+     * at once — a large paste, a document import, bulk row creation — would
+     * reserialize the whole growing queue a hundred times, an O(N²) cost in
+     * `model.toJSON()`.
+     *
+     * @param mutation.capturedChanges - Pre-captured, frozen changes, used to
+     *   avoid re-reading a model after pool operations that might clear them.
+     */
+    /** Stage one mutation through the queue, which owns durability and execution. */
+    private stageMutation;
+    private scheduleSync;
+    processPendingMutations(): Promise<void>;
+    /**
+     * Resolve a conflict between the local model and incoming server data,
+     * called while processing deltas from the WebSocket. Certain server states,
+     * such as deletions and deactivations, always take precedence even when the
+     * local model has unsynced changes, so the two sides stay consistent.
+     */
+    resolveConflicts(localModel: Model, serverData: Record<string, unknown>): Model;
+    /**
+     * Extract the critical state fields from server data. These are the states
+     * that must be honored even when the local model has unsynced changes. The
+     * conflict resolver reads exactly these fields and no others.
+     */
+    private extractCriticalState;
+    /**
+     * Check if critical state changes exist that require forcing server state
+     */
+    private hasCriticalStateChange;
+    /**
+     * Handle network reconnection
+     */
+    private handleReconnection;
+    /**
+     * Handle network disconnection
+     */
+    private handleDisconnection;
+    /**
+     * Get current sync state
+     */
+    getState(): SyncState;
+    /**
+     * Set connection state
+     */
+    private setConnectionState;
+    /**
+     * Subscribe to events with disposer pattern
+     */
+    subscribe(event: string, handler: (data?: unknown) => void): () => void;
+    /**
+     * Add observer for sync events
+     */
+    addObserver(observer: SyncObserver): void;
+    /**
+     * Remove observer
+     */
+    removeObserver(observer: SyncObserver): void;
+    /**
+     * Notify all observers
+     */
+    private notifyObservers;
+    /**
+     * Disconnect from sync
+     */
+    disconnect(): void;
+    /**
+     * Mark the sync client as connected
+     * Called when WebSocket successfully connects (can happen independently of browser online/offline)
+     */
+    markConnected(): void;
+    private drainPendingSettlements;
+    /**
+     * Dispose and cleanup
+     */
+    dispose(): void;
+    /**
+     * Notify the {@link MutationQueue} of an incoming delta so it can confirm
+     * hosted writes by sync-id threshold and queued forwards by their echoed
+     * source-batch correlation id.
+     * @param syncId - The sync id of the received delta.
+     * @param transactionId - Optional server echo of the originating local write.
+     * @param correlationId - Opaque batch identity decoded from a source WAL echo.
+     */
+    onDeltaReceived(syncId: number, transactionId?: string, correlationId?: string): void;
+    /**
+     * Cancel pending transactions for child entities orphaned by a parent's
+     * deletion. The store calls this when a delete delta arrives for a parent,
+     * cancelling any queued writes on children that reference it.
+     *
+     * @param childModelName - The child model type (for example, `Block`).
+     * @param foreignKey - The foreign-key property name (for example, `sectionId`).
+     * @param parentId - The id of the deleted parent.
+     * @returns The number of transactions cancelled.
+     */
+    cancelTransactionsByForeignKey(childModelName: string, foreignKey: string, parentId: string): number;
+    /**
+     * Wait for a transaction to be confirmed by its delta echo. Delegates to the
+     * {@link MutationQueue}, which handles the confirmation timeout.
+     */
+    waitForDeltaConfirmation(transactionId: string): Promise<void>;
+    /**
+     * Force sync now - process pending mutations
+     */
+    syncNow(): Promise<void>;
+    /**
+     * Get sync statistics. Return type is inferred from the literal so
+     * the call site sees the actual shape — `connectionState` narrowed
+     * to its three states, `objectPoolStats` typed by `InstanceCache.getStats`.
+     */
+    getSyncStats(): {
+        connectionState: 'connected' | 'disconnected' | 'connecting';
+        pendingMutations: number;
+        objectPoolStats: ReturnType<InstanceCache['getStats']>;
+    };
+    /**
+     * Get pending transaction count from MutationQueue
+     * Used by SyncedStore to compute hasUnsyncedChanges
+     */
+    getPendingTransactionCount(): number;
+    /**
+     * Subscribe to transaction events for sync status tracking
+     * Returns unsubscribe function
+     */
+    onTransactionEvent(event: 'created' | 'completed' | 'failed', callback: () => void): () => void;
+    /**
+     * Subscribe to mutation failures with the full payload. Mirrors the
+     * underlying MutationQueue 'transaction:failed' shape so consumers
+     * can render typed UI (toast keyed by `AbloError.type`, route-level
+     * "this entity reverted" boundaries, telemetry).
+     *
+     * Distinct from `onTransactionEvent('failed', cb)`, which serves the
+     * parameterless `pendingChanges` counter and intentionally drops the
+     * payload. The two coexist: the counter callback stays lightweight, while
+     * this typed listener drives user-visible surfaces.
+     */
+    onMutationFailure(listener: (payload: {
+        transaction: QueuedMutation;
+        error: Error;
+        permanent?: boolean;
+    }) => void): () => void;
+    /**
+     * Subscribe to commit round-trip latency, split into the local seal and the
+     * remote acknowledgement. Fires once per completed commit.
+     *
+     * Taps the {@link MutationQueue} emitter for the same reason
+     * {@link onMutationFailure} does: the commit lifecycle events originate
+     * there and the SyncClient's own emitter never rebroadcasts them.
+     */
+    onCommitLatency(listener: (sample: CommitLatencySample) => void): () => void;
+    /**
+     * Subscribe to local transaction creation with the full {@link QueuedMutation}
+     * payload (`type`, `modelName`, `modelId`, `data`, `previousData`). This is
+     * the feed the store's local-mutation subscription taps for undo recording.
+     *
+     * It subscribes to the {@link MutationQueue}'s emitter directly, since
+     * that is the only emitter that fires `transaction:created`. The SyncClient's
+     * own emitter (reached through {@link subscribe}) never rebroadcasts that
+     * event, so routing undo through `subscribe('transaction:created')` would
+     * record nothing. {@link onMutationFailure} taps the queue for the same
+     * reason.
+     */
+    onLocalTransaction(listener: (tx: QueuedMutation) => void): () => void;
+    /**
+     * Wait for the latest in-flight transaction for (modelName, modelId)
+     * to be confirmed by the server, or reject if it's rolled back.
+     * Resolves immediately when no transaction is in flight — see
+     * `MutationQueue.confirmationFor` for the lookup contract.
+     *
+     * Distinct from `waitForDeltaConfirmation(transactionId)` which keys
+     * off a known tx id; this variant is for call sites that hold a
+     * Model reference but never see the underlying transaction.
+     */
+    waitForConfirmation(modelName: string, modelId: string): Promise<void>;
+    /**
+     * Get detailed debug info for the sync debug page
+     */
+    getDebugInfo(): {
+        connectionState: "connected" | "disconnected" | "connecting";
+        pendingMutationsCount: number;
+        mutationQueue: {
+            lastSeenSyncId: number;
+            awaitingDeltaCount: number;
+            awaitingDeltaTransactions: {
+                id: string;
+                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                modelName: string;
+                modelId: string;
+                syncIdNeeded: number | undefined;
+                createdAt: number;
+                age: number;
+            }[];
+            pendingTransactions: {
+                id: string;
+                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                modelName: string;
+                modelId: string;
+            }[];
+            executingTransactions: {
+                id: string;
+                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                modelName: string;
+                modelId: string;
+            }[];
+        };
+    };
+    unassignEntity(entityType: string, entityId: string): Promise<void>;
+    reassignEntity(entityType: string, entityId: string, assigneeType: string, assigneeId: string, id?: string): Promise<void>;
+    /**
+     * Apply a batch of delta results from Database to the InstanceCache.
+     * Owns: model creation, upsert, remove, archive, conflict resolution.
+     * Returns: nothing — InstanceCache is updated in place.
+     */
+    /**
+     * Mark a local transaction as optimistically applied. The matching
+     * server delta (when it arrives with the same `transactionId`) will
+     * be recognized as an echo and skip the pool mutation. Called
+     * automatically by `MutationQueue` when a transaction is staged;
+     * exposed publicly so tests can drive the API directly.
+     */
+    markTransactionPending(transactionId: string): void;
+    /**
+     * Read echo-detection counters: hits, rollbacks, evictions, and the
+     * current pending-set size. Surfaced for production observability
+     * — a sustained `evictions > 0` rate or `rollbacks` spike is a
+     * health signal worth alerting on.
+     */
+    getEchoMetrics(): Readonly<UnconfirmedWritesMetrics>;
+    /**
+     * Package-internal accessor for the {@link MutationQueue}. Used by
+     * `Ablo.commits.create()` to route raw multi-operation envelopes through the
+     * same retry-on-reconnect lane as the model proxy path, and by tests to
+     * exercise the queue's interaction with {@link markTransactionPending} on the
+     * real instance the SyncClient subscribes to. It is not re-exported to SDK
+     * consumers; `Ablo` is the public surface.
+     */
+    getMutationQueue(): MutationQueue;
+    applyDeltaBatchToPool(dbResults: readonly AppliedChange[], enrichRelations: (modelName: string, data: Record<string, unknown>) => Record<string, unknown>): void;
+    /**
+     * Apply bootstrap data to the InstanceCache with ghost removal.
+     * Owns: model creation, batch upsert, ghost detection + removal.
+     */
+    applyBootstrapDataToPool(bootstrapData: {
+        models?: Record<string, unknown[]>;
+        failedModels?: string[];
+    }, protectedIds?: ReadonlySet<string>, options?: {
+        /**
+         * Scoped backfill for the hydrate-on-enter path: the snapshot covers only
+         * the groups just entered, not the whole model type. Two behaviors change
+         * so the subset cannot corrupt the pool. First, the upsert is
+         * version-guarded ({@link InstanceCache.upsertIfNewer}) so a concurrent live
+         * delta is not clobbered back to the snapshot version. Second, ghost
+         * removal is skipped, because a subset snapshot must never evict rows of
+         * the same type that belong to other, unhydrated groups.
+         */
+        scoped?: boolean;
+    }): {
+        added: number;
+        updated: number;
+        removed: number;
+        skipped: number;
+        healed: number;
+    };
+}
+export {};