zerodrift 1.0.0

package/dist/core/StoreManager.d.ts

@@ -0,0 +1,839 @@
+/**
+ * StoreManager — the top-level orchestrator.
+ *
+ * Owns: ObjectPool, Database, TransactionQueue, SyncConnection, all Stores.
+ *
+ * Bootstrap phases (for loading indicators):
+ *   idle → creatingStores → connectingDatabase → determiningBootstrapType
+ *        → fetching → writingToDatabase → hydrating → connectingSync → ready
+ *
+ * Batch API:
+ *   storeManager.batch(() => {
+ *     issue.title = "x"; issue.save();
+ *     team.name = "y"; team.save();
+ *   });
+ *   storeManager.undo(); // reverts both
+ *
+ * Lazy loading:
+ *   storeManager.getOrLoadCollection("Issue", "teamId", teamId)
+ *   storeManager.getOrLoadById("DocumentContent", docId)
+ */
+import { ObjectPool } from "./ObjectPool";
+import { BootstrapType, type StorageAdapter, type DatabaseMeta, type PartialIndexEntry } from "./Database";
+import { TransactionQueue, type TransactionSender, type UndoableActionHandlers } from "./TransactionQueue";
+import { type DeltaPacket, type SSEClientFactory, type SyncMessageTransform } from "./SyncConnection";
+import { type ModelStreamMessageTransform } from "./ModelStream";
+import { type IndexBatchFetcher } from "./BatchModelLoader";
+import { BaseModel } from "./BaseModel";
+import { BootstrapPhase, type ModelMeta, type PropertyMeta, type PropertyChange, type FieldTransform, type EngineErrorContext, type EngineErrorHandler, type CommitRouteHandler, type OnModelTouchedHandler } from "./types";
+/**
+ * Thrown when a delete/archive is blocked by an onDelete: "restrict" relationship.
+ *
+ * Example: if Label has @Reference("Team", { onDelete: "restrict" }) and you
+ * try to delete a Team that has Labels pointing to it, this error is thrown
+ * with details about which model and property blocked the deletion.
+ */
+export declare class RestrictDeleteError extends Error {
+    deletedModelName: string;
+    deletedModelId: string;
+    restrictedByModel: string;
+    restrictedByProperty: string;
+    constructor(deletedModelName: string, deletedModelId: string, restrictedByModel: string, restrictedByProperty: string);
+}
+export interface BootstrapResponse {
+    lastSyncId: number;
+    subscribedSyncGroups: string[];
+    models: Record<string, Record<string, unknown>[]>;
+    /** Server-side schema version. Mismatch with stored value → full bootstrap. */
+    backendDatabaseVersion?: number;
+    /**
+     * Tombstones for records the client may already have but the server has
+     * since deleted, grouped by model name. Safe to omit when the client has
+     * no prior state (e.g. first-time full bootstrap).
+     */
+    deletedIds?: Record<string, string[]>;
+}
+export interface FetcherContext {
+    currentMeta?: DatabaseMeta | null;
+}
+export interface BootstrapFetcherOptions extends FetcherContext {
+    sinceSyncId?: number;
+    onlyModels?: string[];
+    /**
+     * Scope the response to records belonging to these sync groups. Set by the
+     * engine when activating a sync group at runtime or reacting to a delta that
+     * added the client to new groups. Server should ignore unrelated records.
+     */
+    syncGroups?: string[];
+}
+export type BootstrapFetcher = (type: BootstrapType.Full | BootstrapType.Partial, options?: BootstrapFetcherOptions) => Promise<BootstrapResponse>;
+export interface ModelStreamConfig {
+    url: string;
+    onStatusChange?: (connected: boolean) => void;
+    /**
+     * Use when the backend sends a different envelope than the engine's
+     * canonical `{ modelName, modelId, data }`.
+     */
+    transform?: ModelStreamMessageTransform;
+}
+export type OnDemandFetcher = (modelName: string, indexKey: string, value: string) => Promise<Record<string, unknown>[]>;
+export type OnDemandBatchFetcher = (modelName: string, ids: string[]) => Promise<Record<string, unknown>[]>;
+/**
+ * On-demand (progressive) loading strategy for `Partial` / `Lazy` models.
+ * A discriminated union so an index-batch backend can't be half-configured
+ * — the old flat shape let `serverSupportsCompoundIndexKeys` be set without
+ * an `onDemandIndexBatchFetcher`, which silently did nothing.
+ *
+ * - `perKey`: `fetch(modelName, indexKey, value)` is called the first time a
+ *   collection/index is accessed; `batchFetch` coalesces missing id lookups
+ *   for `getByIds`. Supply either or both (they drive different reads —
+ *   `getByIndex` vs `getByIds`). Results are written to IDB + hydrated.
+ * - `indexBatch`: concurrent `getByIndex` calls (incl. `coveringIndexes`
+ *   fan-out) coalesce into one `fetch` per microtask. `compound` opts in to
+ *   dotted server-side-join index keys; `threshold` overrides
+ *   {@link COMPOUND_FETCH_THRESHOLD}.
+ */
+export type OnDemandConfig = {
+    mode: "perKey";
+    fetch?: OnDemandFetcher;
+    batchFetch?: OnDemandBatchFetcher;
+} | {
+    mode: "indexBatch";
+    fetch: IndexBatchFetcher;
+    compound?: {
+        threshold?: number;
+    };
+};
+export interface TransportConfig {
+    bootstrapFetcher: BootstrapFetcher;
+    transactionSender?: TransactionSender;
+    syncUrl?: string;
+    /**
+     * Optional async hook that returns the user's sync-group memberships
+     * before any bootstrap fetch runs. The returned groups are append-only
+     * unioned with `dbMeta.subscribedSyncGroups` (so a stale persisted set
+     * never shrinks the live one) and persisted, so every downstream
+     * `bootstrapFetcher` call can pass `syncGroups` from one canonical source
+     * rather than relying on the server inferring scope from auth/session.
+     * Fires after the storage adapter connects but before the bootstrap type
+     * is determined, so seeded groups can influence Full vs Partial. Failure
+     * is fatal. Return `[]` (or omit) if the server owns scope.
+     */
+    bootstrapSyncGroups?: () => Promise<string[]>;
+    /** Secondary model update streams (e.g. a calculation service). */
+    modelStreams?: ModelStreamConfig[];
+    /**
+     * Custom SSE client factory. Defaults to the browser's `EventSource`.
+     * Override to run outside the browser (Node/agent):
+     * `sseClientFactory: (url) => new EventSource(url)`. When set, `sseInit`
+     * is ignored — your factory owns any options.
+     */
+    sseClientFactory?: SSEClientFactory;
+    /**
+     * Init options forwarded to the default browser EventSource (e.g.
+     * `{ withCredentials: true }`). Applies to the main stream and every
+     * `modelStreams` entry. Ignored when `sseClientFactory` is set.
+     */
+    sseInit?: EventSourceInit;
+    /**
+     * Use when the backend sends a different envelope than the canonical
+     * `DeltaPacket`. Return null to drop a message.
+     */
+    syncTransform?: SyncMessageTransform;
+}
+export interface LoadingConfig {
+    /**
+     * How deep `RefCollection`s walk the parent's outgoing FK chain when
+     * auto-deriving covering axes. Defaults to 3 (matching Linear). 1 = only
+     * the parent's direct FKs; 0 = disable auto-derivation (manual
+     * `coveringIndexes` still applies). Higher values exponentially increase
+     * the registry-walk surface for diminishing returns.
+     */
+    transientIndexDepth?: number;
+    /**
+     * Two-phase full bootstrap. If provided, the first fetch loads only the
+     * critical models (everything NOT in this list); once interactive, a
+     * background fetch loads these. If omitted, all models load in one
+     * request.
+     */
+    deferredModels?: string[];
+    /**
+     * Progressive / on-demand loading for `Partial` / `Lazy` models — they're
+     * excluded from bootstrap and fetched on first access, written to IDB,
+     * and hydrated. See {@link OnDemandConfig}.
+     */
+    onDemand?: OnDemandConfig;
+}
+export interface PersistenceConfig {
+    /**
+     * Custom storage backend. Defaults to IndexedDB (`Database`). Override
+     * for environments without IndexedDB (`new MemoryAdapter()`), or
+     * implement `StorageAdapter` for SQLite/Redis/etc. If omitted, `Database`
+     * falls back to in-memory when IndexedDB is unavailable (no persistence
+     * across restarts, no crash).
+     */
+    storageAdapter?: StorageAdapter;
+    /**
+     * Maximum undo entries kept in memory. Defaults to 100. Lower it for
+     * long-running agents that make many writes and don't need deep history
+     * (each entry holds model snapshots).
+     */
+    undoLimit?: number;
+}
+export interface HooksConfig<TContext = unknown> {
+    onPhaseChange?: (phase: BootstrapPhase, detail?: string) => void;
+    onDeltaPacket?: (packet: DeltaPacket) => void;
+    onReady?: () => void;
+    /**
+     * Single hook for every async failure the engine catches internally
+     * (eager loads, SSE parse errors, transaction retries, deferred fetches).
+     * Receives the error and a tagged-union `EngineErrorContext`. Throwing
+     * from it is swallowed. Without it, internal failures are silently
+     * dropped.
+     */
+    onError?: EngineErrorHandler;
+    /**
+     * Called when a sync group is removed (`deactivateSyncGroup` or an SSE
+     * `removedSyncGroups`). `dbMeta.subscribedSyncGroups` is already updated;
+     * SSE reconnect waits for the returned promise. Use it to evict pool/IDB
+     * records — `sm` exposes `evictByIndex` / `evictWhere`, `objectPool`,
+     * `database`.
+     */
+    onSyncGroupDelete?: (groupId: string, sm: StoreManager<TContext>) => void | Promise<void>;
+}
+export interface AdvancedConfig<TContext = unknown> {
+    /**
+     * Mint the `id` for newly-constructed client-side models. Not invoked for
+     * server/IDB-hydrated records. Receives the live context from
+     * `setContext` (or `<SyncProvider context>`); `undefined` until set.
+     * Defaults to `crypto.randomUUID()`.
+     */
+    identifierFn?: (meta: ModelMeta, context: TContext | undefined) => string;
+    /**
+     * Stamp a field transform onto each `(model, property)` at engine init
+     * (walked once). The transform fires inside the property setter before
+     * the MobX box, receiving the value, instance, and live context — use it
+     * to canonicalize cross-cutting input (tenant-prefix FKs, normalize
+     * strings) without per-field decorators. Per-StoreManager storage.
+     */
+    applyFieldTransforms?: (meta: ModelMeta, prop: PropertyMeta) => FieldTransform<TContext> | undefined;
+    /**
+     * Route user-initiated commits before they hit the pool / queue. Fires
+     * from `commitCreate` (before pool insert + enqueue) and `commitUpdate`
+     * (before enqueue). `"skip"` suppresses; a redirect replays the intent
+     * against a different model id (optionally restoring the original's
+     * pre-edit boxes). Delta/SSE writes do NOT fire this. Pair with
+     * `materializePoolOnly` / `clonePoolOnly` for pool-only redirect targets.
+     */
+    routeCommit?: CommitRouteHandler;
+    /**
+     * Fired the instant a clean model becomes dirty (first pending change
+     * since last save/discard), synchronously inside the setter before any
+     * `save()`. For eager side-effects that must not wait for a commit (e.g.
+     * materializing a draft-layer scaffold). The write is still routed at
+     * `save()` via `routeCommit`. Runs on the setter hot path — keep it fast.
+     * NOT fired during redirect replay or delta/SSE hydrates.
+     */
+    onModelTouched?: OnModelTouchedHandler;
+    /**
+     * Hooks for undoing/redoing remote side-effects committed via non-model
+     * APIs (bulk endpoints, server workflows). Tracked on the same undo stack
+     * as model transactions; on undo the engine calls `undoableActions.undo`
+     * with the recorded `UndoableAction`. Each handler returns the
+     * compensating action (or `void` if symmetric). Wire
+     * `StoreManager.runUndoable(fn)` at the call site. Failures route to
+     * `onError` with `kind: "undoableAction"`.
+     */
+    undoableActions?: UndoableActionHandlers;
+}
+/**
+ * Public engine config, grouped by concern. `transport` is required
+ * (carries the required `bootstrapFetcher`); the rest are optional.
+ */
+export interface StoreManagerConfig<TContext = unknown> {
+    workspaceId: string;
+    transport: TransportConfig;
+    loading?: LoadingConfig;
+    persistence?: PersistenceConfig;
+    hooks?: HooksConfig<TContext>;
+    advanced?: AdvancedConfig<TContext>;
+}
+/**
+ * @internal Flattened shape the engine reads internally. The public grouped
+ * `StoreManagerConfig` is normalized into this exactly once (constructor),
+ * so the rest of the engine collapses to one stable surface. Exported only
+ * for the test factory.
+ *
+ * Derived structurally from the grouped sub-interfaces (minus `onDemand`,
+ * which the discriminated union expands into the flat `onDemand*` fields
+ * below) so the "flat = projection of grouped" invariant is compiler-
+ * enforced — rename a field in one place and this follows automatically.
+ */
+export type NormalizedConfig<TContext = unknown> = Omit<TransportConfig & LoadingConfig & PersistenceConfig & HooksConfig<TContext> & AdvancedConfig<TContext>, "onDemand"> & {
+    workspaceId: string;
+    onDemandFetcher?: OnDemandFetcher;
+    onDemandBatchFetcher?: OnDemandBatchFetcher;
+    onDemandIndexBatchFetcher?: IndexBatchFetcher;
+    serverSupportsCompoundIndexKeys?: boolean;
+    compoundIndexFetchThreshold?: number;
+};
+/** @internal Grouped public config → flat internal config. Single mapping
+ * point; the discriminated `onDemand` union expands to the legacy flat
+ * onDemand* fields here. */
+export declare function normalizeConfig<TContext = unknown>(c: StoreManagerConfig<TContext>): NormalizedConfig<TContext>;
+export declare class StoreManager<TContext = unknown> {
+    readonly objectPool: ObjectPool;
+    readonly database: StorageAdapter;
+    readonly transactionQueue: TransactionQueue;
+    get transientIndexDepth(): number;
+    private stores;
+    private syncConnection;
+    private modelStreams;
+    private config;
+    private context;
+    private fieldTransforms;
+    hasFieldTransforms: boolean;
+    hasModelTouchedHandler: boolean;
+    private _phase;
+    private _error;
+    private stopped;
+    private loadedModelsUnsub;
+    private syncReconnectTimer;
+    /**
+     * Hot cache of collection coverage, keyed by `"modelName:indexKey:value"`.
+     * Each value carries the structured tuple plus the `firstSyncId` (the
+     * `lastSyncId` at the time of fetch). Mirrored to the storage adapter's
+     * `__partialIndexes` store, so coverage survives reload.
+     */
+    private partialIndexCoverage;
+    private loadedIds;
+    /** Models whose IDB rows have been hydrated into the pool at least once
+     * this session. `getOrLoadAll`'s cache-hit path skips a full IDB scan
+     * when a model is in this set — pool stays current via SSE
+     * (`shouldHydrateInsert` honors `*`-coverage, see `isModelFullyLoaded`),
+     * so a fresh IDB read would just rediscover what pool already holds.
+     * Cleared whenever `objectPool.clear()` is called. */
+    private poolSyncedFromIDB;
+    /** Models that have at least one `*`-coverage entry in
+     * `partialIndexCoverage` (any scope). Mirror of those entries — kept so
+     * `isModelFullyLoaded` is O(1) on the SSE insert hot path. Updated
+     * wherever `partialIndexCoverage` mutates a `"*"` row. */
+    private fullyLoadedModels;
+    /** Models with an in-flight `getOrLoadAll` (or `fetchDeferredModels`)
+     * fetch. Refcounted because two fetches with different scopes can overlap.
+     * `isModelFullyLoaded` returns true while pending so `shouldHydrateInsert`
+     * starts admitting SSE deltas immediately — otherwise inserts arriving
+     * during the fetch window would land only in IDB and the snapshot's older
+     * `hydrateAndPut` pass would overwrite the pool with stale data. */
+    private pendingFullLoadRefcount;
+    /** Tombstone set populated by SSE `D`/`A` handlers while a model has a
+     * pending full-load. The merge step at the end of `getOrLoadAll` /
+     * `fetchDeferredModels` filters snapshot records through this set so a
+     * delete that arrived after the server's snapshot doesn't get resurrected.
+     * Cleared when the last in-flight fetch for the model completes. */
+    private inflightDeletes;
+    /** Per-(model, scope) in-flight `getOrLoadAll` promises so concurrent calls
+     * coalesce instead of double-fetching. Keyed by `coverageKey`. */
+    private inflightFullLoads;
+    /** Sync groups returned by `config.bootstrapSyncGroups`. Used as a
+     * pre-Phase-1 source for `subscribedSyncGroupsForFetch` (when no prior
+     * dbMeta exists, currentMeta is still null at fetch time) and unioned
+     * into the meta written by `saveMeta` after Phase 1/Partial completes. */
+    private seededSyncGroups;
+    /** Wired only when `onDemandIndexBatchFetcher` is configured. */
+    private indexBatchLoader;
+    /** Set of models touched inside the currently open `atomic()` scope.
+     * `null` when no scope is active. Mutations register themselves via
+     * `registerAtomicTouch` (called from `BaseModel.propertyChanged`). */
+    private activeAtomicScope;
+    /** True only while the engine replays a redirected commit onto its target.
+     * Gates every user-intent hook (`routeCommit`, `onModelTouched`) so the
+     * engine's own `assign()`/`save()` during replay isn't mistaken for a
+     * fresh user edit. */
+    private suppressUserIntentHooks;
+    constructor(config: StoreManagerConfig<TContext>);
+    /** Push the live context (e.g. user/tenant info) used by `identifierFn`.
+     * Read at id-mint time, not captured — call this whenever the relevant
+     * context changes. The React `<SyncProvider context={...}>` prop is a
+     * thin wrapper over this. */
+    setContext(ctx: TContext): void;
+    /** Apply any registered field transform for `(instance, propName)` against
+     * `value`, returning the result (or `value` unchanged when no rule applies).
+     * Setters short-circuit on `hasFieldTransforms` first — by the time this
+     * runs we know at least one rule exists somewhere in the engine. */
+    applyTransform(instance: BaseModel, propName: string, value: unknown): unknown;
+    private static fieldTransformKey;
+    /** Mint a fresh id, honoring `identifierFn` when configured. Folds the
+     * registry lookup in so callers can skip it entirely on the no-config
+     * path — `new Model()` is hot. */
+    mintId(instance: BaseModel): string;
+    get phase(): BootstrapPhase;
+    get error(): Error | null;
+    get isReady(): boolean;
+    private setPhase;
+    /**
+     * Route an internal error to `config.onError`. No-op when the hook isn't
+     * configured. Wrapped in try/catch so a buggy adopter handler can't crash
+     * the engine.
+     */
+    emitError(err: unknown, context: EngineErrorContext): void;
+    bootstrap(): Promise<void>;
+    /**
+     * Full bootstrap — two-phase fetch. Only Eager models are ever shipped;
+     * Lazy / Partial / LocalOnly / Ephemeral load on demand
+     * or via SSE.
+     *
+     * Phase 1: critical Eager models (everything NOT in deferredModels).
+     *          Write to IDB, hydrate into ObjectPool. UI can render.
+     *
+     * Phase 2: deferred Eager models (Comment, Reaction, Attachment, etc.)
+     *          in the background after the engine is marked ready.
+     *
+     * If deferredModels is not configured, every Eager model is fetched in
+     * a single request.
+     */
+    private fullBootstrap;
+    /**
+     * Background fetch for deferred models (phase 2).
+     * Runs after the engine is ready — the UI is already interactive.
+     * Uses Full bootstrap because the client has never fetched these models before.
+     * Any changes that occurred concurrently during phase 1 are covered by SSE,
+     * which connects before this method runs.
+     *
+     * Bypasses clearModelStore to avoid clobbering concurrent SSE writes to IDB.
+     * Uses writeModelsIfAbsent + tombstone filter to merge with SSE — see
+     * `agent-docs/04-lazy-loading.md` for the in-flight merge invariants.
+     */
+    private fetchDeferredModels;
+    /** Fold the result of `bootstrapSyncGroups` into `dbMeta`. When prior
+     * meta exists we persist immediately so `localBootstrap` (no `saveMeta`
+     * of its own) and a subsequent reload see the seeded groups; `saveMeta`
+     * is safe here because `lastSyncId` is preserved. With no prior meta,
+     * stash on the instance — calling `saveMeta` with `lastSyncId: 0` would
+     * coerce a fresh bootstrap into the `Local` path. Phase 1's `saveMeta`
+     * will fold the stashed set in. */
+    private applySeededSyncGroups;
+    /** Persist `dbMeta` after a Full bootstrap response, folding in any
+     * `seededSyncGroups` left over from `bootstrapSyncGroups`. Shared by the
+     * Phase-1 and single-phase branches of `fullBootstrap`. */
+    private persistFullBootstrapMeta;
+    /** Append-only merge: bootstrap responses never shrink the subscription set. */
+    private static mergeSubscribedGroups;
+    /** Canonical scope for bootstrap-style fetches: persisted set, then the
+     * pre-Phase-1 seeded fallback, else `undefined`. */
+    private subscribedSyncGroupsForFetch;
+    /**
+     * Evict tombstones from IDB (skipping Ephemeral models) and the pool.
+     * Run AFTER the upsert pass — if an id is in both `res.models` and
+     * `res.deletedIds` the tombstone wins (server's delete is authoritative).
+     * Cascade/invalidate are skipped; those flow via SSE D actions.
+     */
+    private applyDeletedIds;
+    private partialBootstrap;
+    private localBootstrap;
+    commitCreate(model: BaseModel): void;
+    commitUpdate(modelId: string, modelName: string, changes: Record<string, PropertyChange>): void;
+    private resolveCommitRoute;
+    private applyCreateRoute;
+    private applyUpdateRoute;
+    private previousDataFor;
+    /**
+     * Hydrate server-shaped records straight into the pool — no
+     * `CreateTransaction`, no server round-trip, no IDB write. Mirrors the insert
+     * path SSE uses (`ObjectPool.hydrateAndPut`), so inverse links,
+     * `@ReferenceCollection` membership, and `notifyModelChanged` reactivity all
+     * wire up automatically.
+     */
+    materializePoolOnly<T extends BaseModel = BaseModel>(modelName: string, records: Record<string, unknown>[], options?: {
+        onCollision?: "error" | "hydrate";
+    }): T[];
+    /**
+     * Convenience wrapper around `materializePoolOnly` for cloning existing
+     * sources into pool-only optimistic mirrors.
+     *
+     * `transform` receives each source's serialized data plus the source
+     * instance and must return a fully-formed record with a different `id`.
+     * Use it to rewrite ids and any FK fields that should point at the
+     * new scope.
+     *
+     * Intended for optimistic in-memory mirrors while the server fork-fetch
+     * is in flight. When the server's records eventually arrive via SSE on
+     * the same ids, `hydrate()` runs in place and the pendingChanges rebase
+     * keeps any user edits the user has stacked on top.
+     *
+     * Throws if `transform` returns the source id unchanged — that would
+     * silently overwrite the original instance.
+     */
+    clonePoolOnly<T extends BaseModel>(sources: T[], transform: (data: Record<string, unknown>, source: T) => Record<string, unknown>): T[];
+    /**
+     * Delete a model WITH client-side cascade and restrict validation.
+     *
+     * Pre-validation: checks for References with onDelete: "restrict".
+     * If any model instance references the one being deleted via a restrict
+     * relationship, the delete is refused with a RestrictDeleteError.
+     *
+     * Cascade: walks the ModelRegistry for:
+     *   - BackReferences pointing at this model → delete those "owned" models
+     *   - References with onDelete: "cascade" → delete those dependent models
+     *   - References with onDelete: "nullify" → set the reference to null
+     *
+     * All operations are grouped in a batch so undo reverses everything.
+     */
+    deleteModel(model: BaseModel): Promise<void> | undefined;
+    /** Archive a model WITH client-side cascade and restrict validation. */
+    archiveModel(model: BaseModel): Promise<void> | undefined;
+    /**
+     * Check if any Reference with onDelete: "restrict" blocks this deletion.
+     *
+     * Walks all registered models. For each Reference property that points
+     * to the model type being deleted and has onDelete: "restrict", checks
+     * if any instance in the ObjectPool actually references the target ID.
+     *
+     * Returns the first restriction found, or null if deletion is allowed.
+     */
+    private checkDeleteRestriction;
+    /**
+     * Client-side cascade: find and delete/nullify models that reference the
+     * one being deleted. Mirrors SyncConnection.cascadeDelete but creates
+     * actual transactions (so undo works).
+     */
+    private cascadeDeleteClient;
+    /** Same cascade logic for archive. */
+    private cascadeArchiveClient;
+    /**
+     * Called by SyncConnection when new sync groups are added.
+     * Fetches all models scoped to those groups from the server,
+     * writes to IDB, and hydrates eager-load ones into the pool.
+     *
+     * Example: user joins team "t-design" → fetch all Issues, Comments,
+     * etc. that belong to that team.
+     */
+    private handleSyncGroupsAdded;
+    /**
+     * Called by SyncConnection when a delta packet's `removedSyncGroups` lists
+     * groups the client no longer has access to. SyncConnection has already
+     * updated `dbMeta.subscribedSyncGroups`.
+     */
+    private handleSyncGroupsRemoved;
+    /**
+     * Fire `onSyncGroupDelete` once per group, serially. Errors thrown by the
+     * adopter's callback are caught and routed to `onError` so one bad group
+     * doesn't abort cleanup for the rest.
+     */
+    private fireOnSyncGroupDelete;
+    /**
+     * Scoped bootstrap-fetcher call: same fetcher used by full/partial bootstrap,
+     * scoped to a subset of groups via `syncGroups` and to Eager models only.
+     *
+     * Returns `schemaMismatch: true` if the server reports a schema version that
+     * doesn't match what's stored — in that case a full re-bootstrap has already
+     * been triggered and the caller should bail.
+     */
+    private fetchSyncGroupModels;
+    /**
+     * Targeted full fetch for Eager models added to the registry since the
+     * last connect. Runs after partial bootstrap so existing models keep their
+     * delta-only path; new Eager models get a full snapshot. Non-Eager
+     * additions are silently dropped — they load on demand or not at all.
+     */
+    private fetchNewlyAddedModels;
+    /** Write a bootstrap response into IDB + the in-memory pool, then apply
+     * any tombstones it carries. Shared by `fetchSyncGroupModels` and
+     * `fetchNewlyAddedModels` — both are targeted full fetches. */
+    private applyBootstrapResponse;
+    /**
+     * Write records for Eager models into the pool. Updates existing instances
+     * in-place; creates new ones via hydrateAndPut for models not yet in memory.
+     */
+    private hydrateEagerModels;
+    /**
+     * Activate a sync group: subscribe to SSE deltas for the group and
+     * optionally fetch its models from the server.
+     *
+     * By default (fetch: true) models are fetched, written to IDB, and hydrated
+     * into the pool before reconnecting. Pass `{ fetch: false }` to subscribe
+     * without fetching — useful when you want SSE deltas to start flowing but
+     * will load models lazily later.
+     *
+     * Pass `{ ephemeral: true }` for session-scoped groups that should not
+     * survive page reloads. The group subscription is kept in memory only —
+     * models are still written to IDB as usual, but the group itself is not
+     * saved to meta.
+     *
+     * Idempotent — does nothing if the group is already active.
+     *
+     * Uses the same `bootstrapFetcher` as initial bootstrap, scoped via the
+     * `syncGroups` option. The server should return only records belonging to
+     * those groups.
+     */
+    activateSyncGroup(groupId: string | string[], { fetch, ephemeral, }?: {
+        fetch?: boolean;
+        ephemeral?: boolean;
+    }): Promise<void>;
+    /**
+     * Deactivate a sync group: drop it from the subscribed list, fire
+     * `onSyncGroupDelete` (if configured) so the app can evict pool/IDB records,
+     * and reconnect SSE so the server stops streaming deltas for it.
+     *
+     * If `onSyncGroupDelete` isn't configured the group's records remain in the
+     * pool/IDB. Use `sm.evictByIndex` / `sm.evictWhere` inside the callback, or
+     * walk `ModelRegistry.allModels()` for a generic sweeper.
+     *
+     * Idempotent — does nothing if the group is not currently active.
+     */
+    deactivateSyncGroup(groupId: string | string[]): Promise<void>;
+    /** Run a function inside a batch. All save() calls share a batchId.
+     * Accepts both sync and async functions — endBatch is always called
+     * after the function (or its returned Promise) completes.
+     */
+    batch(fn: () => void): string;
+    batch(fn: () => Promise<void>): Promise<string>;
+    beginBatch(): string;
+    endBatch(id: string): void;
+    /**
+     * Stage optimistic edits with all-or-nothing local commit semantics.
+     *
+     *   storeManager.atomic(async () => {
+     *     book.assign({ title: "X" });
+     *     issue.assign({ status: "done" });
+     *     await api.call();
+     *   });
+     *
+     * Any model mutated inside `fn` registers with the active scope. On
+     * resolve, every touched model's `save()` is called once (wrapped in a
+     * single batch so undo collapses to one entry). On throw, every touched
+     * model's `discardUnsavedChanges()` runs and the error re-throws.
+     *
+     * SSE deltas that arrive on a touched field during an `await` rebase the
+     * model's `pendingChanges` baseline (see `BaseModel.hydrate`) — the
+     * optimistic value stays visible, and a discard lands on the server's
+     * latest known value rather than a stale pre-edit one.
+     *
+     * `runUndoable` side effects pass through unchanged: their server
+     * mutation is not rolled back when the atomic block throws. Compensate
+     * them yourself in the caller's catch if needed.
+     *
+     * Nested atomic scopes are not supported.
+     */
+    atomic<T>(fn: () => T): T;
+    atomic<T>(fn: () => Promise<T>): Promise<T>;
+    /** @internal */
+    registerAtomicTouch(model: BaseModel): void;
+    /** @internal Called from `BaseModel.propertyChanged` on the clean→dirty
+     * transition. Suppressed during the engine's own redirect replay so the
+     * draft target's `assign()` doesn't re-trigger a user-facing "first edit".
+     * BaseModel guards on `hasModelTouchedHandler` before calling. */
+    fireModelTouched(model: BaseModel, modelName: string): void;
+    undo(): Promise<import("./TransactionQueue").UndoResult | null>;
+    redo(): Promise<import("./TransactionQueue").UndoResult | null>;
+    /**
+     * Run a remote side-effect that returns a `changeLogId`, and record it on
+     * the undo stack so the next `undo()` invokes the consumer's
+     * `undoableActions.undo` handler with that id.
+     *
+     * The function may return either the `changeLogId` string directly, or any
+     * object with a `changeLogId` field — in which case the full object is
+     * returned to the caller. Inside an open `batch()`, the action joins the
+     * batch and undoes alongside the model transactions.
+     *
+     * If `fn` throws, nothing is recorded.
+     */
+    runUndoable<T extends string | {
+        changeLogId: string;
+    }>(fn: () => Promise<T> | T, opts?: {
+        actionType?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<T>;
+    /**
+     * Builds the `partialIndexCoverage` cache key. The `indexKey` segment is
+     * usually a real model field name, but the value `ALL_INDEX_KEY_SENTINEL`
+     * (`"*"`) is reserved for `getOrLoadAll` whole-table coverage and must
+     * not collide with any real field name.
+     */
+    private static collectionKey;
+    private static modelIdKey;
+    /** Pool-first collection lookup where indexKey === value (e.g. all Issues for a team). */
+    getOrLoadCollection<T extends BaseModel = BaseModel>(modelName: string, indexKey: string, value: string): Promise<T[]>;
+    isCollectionLoaded(modelName: string, indexKey: string, value: string): boolean;
+    /** True when the model has `*`-coverage (a completed `getOrLoadAll`) or
+     * a full-load fetch is currently in flight. Read on the SSE insert hot
+     * path via `shouldHydrateInsert` — the in-flight branch is what makes
+     * deltas land in the pool during the fetch window. */
+    isModelFullyLoaded(modelName: string): boolean;
+    /** Called by SSE D/A processing whenever a delete arrives. While a model
+     * has a pending full-load, the id is recorded so the in-flight fetch's
+     * merge step can drop a stale-snapshot resurrection. No-op when no fetch
+     * is pending — keeps the hot path cheap. */
+    recordInflightDelete(modelName: string, id: string): void;
+    /** Increment the in-flight refcount for `modelName`. Must be paired with
+     * `endPendingFullLoad`. While refcount > 0, `isModelFullyLoaded` returns
+     * true (admitting SSE inserts to the pool) and `recordInflightDelete`
+     * tracks tombstones. */
+    private beginPendingFullLoad;
+    /** Decrement the in-flight refcount. When it hits 0, drop the tombstone
+     * set — any snapshot that needed it has already merged. */
+    private endPendingFullLoad;
+    /** Strip records whose id was tombstoned by an SSE delete during the
+     * in-flight full-load window. Common case (no pending deletes) returns
+     * the input unchanged so the caller doesn't allocate. */
+    private filterTombstoned;
+    /**
+     * Derive-on-read for compound coverage: a direct triple
+     * `(modelName, indexKey, value)` is implicitly covered when a previously-
+     * fetched compound query `(modelName, "indexKey.fk", parent.fk)` exists
+     * AND the parent of `value` shares that FK value. Walks one hop on the
+     * parent — must stay in sync with `collapseGroup` in
+     * `CompoundIndexFetcher.ts`. If the rewriter ever recurses (e.g. to
+     * `taskId.projectId.workspaceId`), this loop needs the same recursion
+     * or covered reads will silently miss and re-fetch.
+     *
+     * Skipped (returns false) when:
+     *   - `indexKey` is already a dotted path (we only check direct keys)
+     *   - the FK's referent model isn't registered
+     *   - `value`'s parent isn't in the pool
+     *   - no outgoing FK on the parent has a matching compound coverage
+     */
+    private isCoveredByCompound;
+    /** Mark a `(modelName, indexKey, value)` query as fully covered locally as
+     * of `firstSyncId`. Updates the in-memory hot cache and the storage
+     * adapter's persistent store. */
+    private markPartialIndexLoaded;
+    /**
+     * Absorb the response from a synthetic compound query produced by
+     * `wrapCompoundFetcher`. The full response bag is written to IDB so
+     * future direct lookups within the compound's coverage area find their
+     * records — `BatchModelLoader.flush` only delivers per-waiter slices,
+     * which would otherwise drop records for parents that weren't in the
+     * original batch. The compound key itself is recorded in
+     * `partialIndexCoverage` so derive-on-read can short-circuit subsequent
+     * direct loads.
+     */
+    private absorbCompoundResponse;
+    /**
+     * Returns every recorded `(modelName, indexKey, value, firstSyncId)` tuple
+     * known to this client. Adopters can ship the result to the server alongside
+     * a partial fetch so it can return only deltas since each scope's
+     * `firstSyncId` instead of re-shipping the full snapshot.
+     */
+    getPartialIndexCoverage(): PartialIndexEntry[];
+    /** Walk the pool for `modelName`, removing instances matching `predicate`. */
+    private evictFromPool;
+    /**
+     * Remove every record of `modelName` matching `predicate` from pool and IDB.
+     * Predicate receives hydrated instances (pool) and raw records (IDB); write
+     * predicates that test plain property values so they work on both shapes.
+     * IDB side is a full cursor scan — prefer `evictByIndex` when the match is
+     * "indexed column equals value".
+     */
+    evictWhere(modelName: string, predicate: (m: Record<string, unknown>) => boolean): Promise<number>;
+    /**
+     * Remove every record where `record[indexKey] === value`, using the IDB
+     * index for the database side. Pool side is still a linear scan (no
+     * secondary in-memory index by field value). Also clears the matching
+     * `loadedCollections` cache key so a future `getOrLoadCollection(modelName,
+     * indexKey, value)` re-fetches from the server instead of trusting IDB.
+     */
+    evictByIndex(modelName: string, indexKey: string, value: string): Promise<void>;
+    /**
+     * Cascade `evictByIndex` across every model type that owns this FK. Use
+     * when an "owner" id (workspaceId, teamId, userId, …) goes away and the
+     * client should drop every related row in one call. Models that don't
+     * declare `indexKey` as `indexed: true` are skipped — `deleteModelsByIndex`
+     * falls back to a full-store cursor scan when the index is missing, and
+     * walking every store at every call is rarely what the caller wants.
+     */
+    evictAllByIndex(indexKey: string, value: string): Promise<void>;
+    /** Pool-first bulk lookup by ID (for OwnedCollection resolution). */
+    getOrLoadByIds<T extends BaseModel = BaseModel>(modelName: string, ids: string[]): Promise<T[]>;
+    /** Pool-first single-model lookup by ID. */
+    getOrLoadById<T extends BaseModel = BaseModel>(modelName: string, id: string): Promise<T | null>;
+    /**
+     * Load every instance of `modelName`, optionally scoped to a set of sync
+     * groups. Triggers a Full bootstrap fetch on first call, hydrates the
+     * results, and records coverage so subsequent same-scope calls short-circuit.
+     *
+     * Per-strategy behavior:
+     *   - Eager / Ephemeral — already fully resident; returns pool snapshot.
+     *   - Local — returns IDB contents (no server hit).
+     *   - Lazy / Partial — fetches and hydrates.
+     *
+     * Coverage is tracked in `partialIndexCoverage` under the
+     * `ALL_INDEX_KEY_SENTINEL` reserved indexKey — adopters never see it but it
+     * coexists with real indexKeys, so callers must avoid using "*" themselves.
+     *
+     * Concurrent SSE deltas during the fetch are merged via a pending-flag +
+     * tombstone scheme — see `agent-docs/04-lazy-loading.md` for the full
+     * invariants. Concurrent calls with the same `(modelName, scope)` coalesce
+     * into one fetch via `inflightFullLoads`.
+     */
+    getOrLoadAll<T extends BaseModel = BaseModel>(modelName: string, opts?: {
+        syncGroups?: string[];
+    }): Promise<T[]>;
+    /** Hydrate every IDB row for a covered (or Local) model into the pool.
+     * Used the first time `getOrLoadAll` runs this session against a model
+     * whose `*`-coverage was already recorded (e.g. on a warm reload). */
+    private hydrateFullLoadFromIDB;
+    /** Fetch the snapshot and merge it with whatever the SSE pipeline wrote
+     * during the in-flight window. See the JSDoc on `getOrLoadAll` for the
+     * merge invariants (skip pool-present, drop tombstoned, IDB if-absent). */
+    private fetchAndMergeFullLoad;
+    /** Hydrate `records` into the pool as instances of `modelName` and
+     * return them. Skips any record whose model isn't registered.
+     * Intended for stories and tests, not production. */
+    seed<T extends BaseModel = BaseModel>(modelName: string, records: Record<string, unknown>[]): T[];
+    /** Bulk seed: takes the same shape as `BootstrapResponse.models`. Useful
+     * for one-shot story setup that hydrates a graph in one call. */
+    seedMany(modelsByName: Record<string, Record<string, unknown>[]>): void;
+    /**
+     * Sync filter over the pool for records of `modelName` whose `indexKey`
+     * field matches `value`. Used by the typed `store.<entity>.peekByIndex`
+     * surface and shared with the diff path inside `refreshCollection`.
+     */
+    peekByIndex<T extends BaseModel = BaseModel>(modelName: string, indexKey: string, value: string): T[];
+    /**
+     * Re-fetch a collection from the server, replacing stale pool data.
+     * Existing instances are updated in-place so references held by
+     * components/hooks remain valid. Models the server no longer returns
+     * are removed from the pool.
+     */
+    refreshCollection<T extends BaseModel = BaseModel>(modelName: string, indexKey: string, value: string): Promise<T[]>;
+    /**
+     * Re-fetch specific models by ID from the server.
+     * Existing instances are updated in-place so references remain valid.
+     */
+    refreshModels(modelName: string, ids: string[]): Promise<BaseModel[]>;
+    /**
+     * Re-fetch all previously loaded collections and models for a given model type.
+     * Existing instances are updated in-place so references remain valid.
+     * Models the server no longer returns are removed from the pool.
+     */
+    refreshAllOfModel(modelName: string): Promise<void>;
+    status(): {
+        phase: BootstrapPhase;
+        error: string | undefined;
+        workspaceId: string;
+        objectPoolSize: number;
+        objectPoolCounts: Record<string, number>;
+        pending: number;
+        undoDepth: number;
+        redoDepth: number;
+        syncConnected: boolean;
+        lastSyncId: number;
+    };
+    /** Drop in-memory pool + the per-session "we hydrated from IDB" mirror.
+     * Used by the schema-mismatch fallback in delta processing and sync-
+     * group fetches: when the server's data shape changes we throw away the
+     * pool and re-bootstrap. The two clears are an invariant pair —
+     * extracting the helper enforces it across both call sites instead of
+     * trusting future authors to remember. `partialIndexCoverage` is NOT
+     * cleared here because the schema-mismatch path keeps coverage entries;
+     * the `fullyLoadedModels` mirror stays consistent with that. */
+    private resetPoolState;
+    teardown(): Promise<void>;
+    /** Debounced reconnect for SSE when `loadedModels` mutates. A burst of
+     * transitions in the same tick (or across awaited writes in the same
+     * async chain) coalesces into a single reconnect. setTimeout — not
+     * queueMicrotask — so consecutive `await db.writeModels(A); await
+     * db.writeModels(B)` doesn't reconnect twice. */
+    private scheduleSyncReconnect;
+}