@abloatai/ablo 0.35.0 → 0.37.0

package/dist/RuntimeContext.js

@@ -1,80 +0,0 @@
-/**
- * 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 './transaction/errors.js';
-// ─────────────────────────────────────────────
-// No-op defaults for optional dependencies
-// ─────────────────────────────────────────────
-// Re-exported, not redeclared. `@ablo/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 './transaction/logger.js';
-/** 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/SyncClient.d.ts

@@ -1,551 +0,0 @@
-/**
- * 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 { EventEmitter } from 'events';
-import { MutationQueue } from './transactions/mutations/MutationQueue.js';
-import { type CommitLatencySample } from './transactions/mutations/commitLatency.js';
-import { type UnconfirmedWritesMetrics } from './transactions/mutations/UnconfirmedWrites.js';
-import type { Database } from './Database.js';
-import type { WriteOptions } from './interfaces/index.js';
-import { LogPosition } from './transaction/logPosition.js';
-import type { DurableWriteStore } from './transactions/mutations/durableWriteStore.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 objectPool;
-    private database;
-    private get mutationExecutor();
-    private networkMonitor;
-    private observers;
-    private userId;
-    private organizationId;
-    private pendingMutations;
-    private readonly stagedMutationIds;
-    private pendingJournalBatch;
-    private journalFlushScheduled;
-    private readonly commitOutboxNamespace;
-    /**
-     * 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);
-    /**
-     * 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;
-    /**
-     * Clear all pending mutations for a specific model
-     * Called before deletion to prevent "record not found" errors on the server
-     */
-    private clearPendingMutationsForModel;
-    /**
-     * 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.
-     */
-    private queueMutation;
-    private scheduleJournalFlush;
-    private flushPendingMutationJournal;
-    private syncScheduled;
-    private scheduleSync;
-    private pendingMutationRecord;
-    private persistPendingMutation;
-    /**
-     * Restore the mutation queue from IndexedDB.
-     *
-     * The persisted record was written by an earlier session, possibly by an
-     * older build of the SDK, so each entry is validated as it is replayed:
-     * corrupt entries are dropped and logged at debug level, and a failure is
-     * never swallowed silently, because the survival of offline writes must be
-     * observable.
-     */
-    private restoreMutationQueue;
-    /**
-     * Process pending mutations - can be called by SyncedStore when online
-     *
-     * Best Practice: Only sync models that still exist locally (local-first principle)
-     * - If a model was deleted locally → skip any pending updates/creates for it
-     * - This prevents "record not found" errors from fast copy-paste-delete workflows
-     */
-    processPendingMutations(): Promise<void>;
-    /**
-     * Stage mutation to MutationQueue - mutations in same tick are batched via microtask
-     *
-     * @param mutation.capturedChanges - Pre-captured changes to use instead of re-reading from model
-     */
-    private stageMutation;
-    /**
-     * 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;
-    /**
-     * 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: import('./transactions/mutations/MutationQueue.js').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: import('./transactions/mutations/MutationQueue.js').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: {
-        action: string;
-        modelName: string;
-        modelId: string;
-        data?: Record<string, unknown> | null;
-        /**
-         * Server-stamped transaction id, echoing the client's commit op
-         * id. Used by echo detection to recognize "this is the
-         * confirmation of a mutation I've already applied locally."
-         * Optional because system-emitted deltas (sync_group changes,
-         * schema-derived deltas, etc.) don't have a client transaction.
-         */
-        transactionId?: string;
-    }[], 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 {};