@abloatai/ablo 0.26.0 → 0.28.0

package/dist/BaseSyncedStore.js

@@ -1,20 +1,19 @@
 /**
- * BaseSyncedStore — Generic sync store base class for the SDK.
+ * The base class that application-specific sync stores extend. It supplies the
+ * shared orchestration for reads, writes, delta processing, and bootstrap, and
+ * exports the core types those stores build on.
  *
- * Exports the core types, interfaces, and a base class that app-specific
- * stores extend. The base class provides query/mutation/delta/bootstrap
- * orchestration. Subclasses add domain-specific lazy-loading, collaboration
- * events, and model enrichment.
- *
- * Design: The app's SyncedStore extends this and adds its own methods.
- * This file only contains types and the abstract contract — the actual
- * implementation stays in the app's SyncedStore.ts until we incrementally
- * pull generic methods into this base class.
+ * A subclass adds its own domain behavior — lazy-loaded relations,
+ * collaboration events, and model enrichment — by overriding the protected
+ * extension points defined here. The heavy lifting is delegated to injected
+ * collaborators: {@link SyncClient} owns pool writes and the transaction
+ * queue, {@link Database} owns local persistence, {@link InstanceCache} holds the
+ * in-memory models, and {@link ModelRegistry} holds their metadata.
  */
 import { makeObservable, observable, action, computed, runInAction } from 'mobx';
 import { AbloConnectionError, AbloValidationError, toAbloError } from './errors.js';
 import { ConnectionManager } from './sync/ConnectionManager.js';
-import { AreaOfInterestManager } from './sync/AreaOfInterestManager.js';
+import { SubscriptionManager } from './sync/SubscriptionManager.js';
 import { resolveParticipantSyncGroups, } from './sync/participants.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { PropertyType } from './types/index.js';
@@ -23,7 +22,7 @@ import { QueryProcessor } from './core/QueryProcessor.js';
 import { Model, rowAsModel } from './Model.js';
 import { getContext } from './context.js';
 import { SyncSessionError, isAccessCredentialExpiryCloseReason } from './errors.js';
-import { ModelScope } from './ObjectPool.js';
+import { ModelScope } from './InstanceCache.js';
 import { LazyReferenceCollection } from './LazyReferenceCollection.js';
 import { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
 import { CredentialLifecycle } from './sync/credentialLifecycle.js';
@@ -38,21 +37,20 @@ export const BOOTSTRAP_CONFIG = {
 };
 // Re-export for clean API
 export { ModelScope };
-// deriveSyncPlanFromSchema (pure schema → sync-plan derivation) moved to
-// sync/syncPlan.ts; re-exported so importers are unchanged.
+// deriveSyncPlanFromSchema derives a sync plan from a schema and is
+// re-exported here.
 export { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
 // ── Base class ──────────────────────────────────────────────────────────────
 /**
- * BaseSyncedStore — abstract base for app-specific sync stores.
- *
- * Provides the dependency structure, observable status, and protected
- * accessors that subclasses use. The actual sync orchestration (initialize,
- * delta processing, bootstrap, query, save, delete, etc.) lives in the
- * app's concrete subclass for now — methods will be pulled up into this
- * base class incrementally as they are genericized.
+ * The abstract base class that application-specific sync stores extend. It
+ * carries the injected collaborators, the observable sync status, and the
+ * orchestration for initialization, delta processing, bootstrap, and the
+ * read and write API. A subclass supplies its own domain behavior by
+ * overriding the protected extension points defined here and by typing its
+ * collaboration events through the generic parameter.
  *
- * Subclasses MUST call `super(dependencies, config)` and then set up
- * their own MobX observables.
+ * A subclass must call `super(dependencies, config)` and then set up its own
+ * MobX observables.
  *
  * Generic over `TCollaboration` — an app-defined event map for real-time
  * collaboration events (cursors, selections, presence beyond the core set).
@@ -120,23 +118,23 @@ export class BaseSyncedStore {
     // ── Area-of-interest (dynamic read subscription) ─────────────────
     //
     // `enterScope`/`leaveScope` move the connection's read interest as the
-    // user navigates (open/close a deck, sheet, doc); `pinScope`/`unpinScope`
+    // user navigates (open or close a deck, sheet, or doc); `pinScope`/`unpinScope`
     // express prominence (an active claim keeps a group subscribed). All four
-    // resolve the scope to sync-group strings through the SAME resolver the
+    // resolve the scope to sync-group strings through the same resolver the
     // claim path uses (`resolveParticipantSyncGroups`), so read interest and
-    // write claims always agree on the string for a given entity. No-ops
-    // before the socket exists. Soft state — they never reject for an offline
-    // transport (see `AreaOfInterestManager.reconcile`).
+    // write claims always agree on the string for a given entity. They are
+    // no-ops before the socket exists, and they never reject when the transport
+    // is offline (see {@link SubscriptionManager.reconcile}).
     scopeToGroups(scope) {
         return resolveParticipantSyncGroups(scope, this.schema);
     }
     /**
-     * Bring a scope into view → subscribe to its groups. With
-     * `{ hydrate: true }`, ALSO backfill the groups' current state into the pool
-     * after the subscription is active (the game "spawn snapshot + delta stream"
-     * pattern): subscribe-first so no live delta is missed in the gap, then
-     * snapshot. Hydration is soft — a failed backfill never rejects `enterScope`
-     * and the live tail still flows.
+     * Bring a scope into view and subscribe to its sync groups. With
+     * `{ hydrate: true }`, also backfill the groups' current state into the pool
+     * once the subscription is active. The order matters: subscribing first
+     * guarantees no live delta is missed in the gap before the snapshot lands.
+     * Hydration is best-effort — a failed backfill never rejects `enterScope`,
+     * and the live delta stream keeps flowing regardless.
      */
     enterScope(scope, opts) {
         const mgr = this.areaOfInterest;
@@ -149,11 +147,11 @@ export class BaseSyncedStore {
         return subscribed.then(() => this.hydrateGroups(groups));
     }
     /**
-     * Backfill the current state of `syncGroups` into the pool via a PURE scoped
-     * snapshot fetch + the version-guarded, ghost-free scoped apply. Idempotent
-     * (skips groups already hydrated) and single-flight (concurrent enters of the
-     * same group share one fetch). Soft-fails: on error the groups are NOT marked
-     * hydrated, so a later re-enter retries.
+     * Backfill the current state of `syncGroups` into the pool with a side-effect-free
+     * scoped snapshot fetch followed by the version-guarded scoped apply. The call
+     * is idempotent (it skips groups already hydrated) and single-flight (concurrent
+     * enters of the same group share one fetch). On error the groups are left
+     * unmarked, so a later re-enter retries.
      */
     async hydrateGroups(syncGroups) {
         const need = syncGroups.filter((g) => !this.hydratedGroups.has(g) && !this.hydratingGroups.has(g));
@@ -222,15 +220,9 @@ export class BaseSyncedStore {
     initialized = false;
     dataReady = false;
     // ── User context ──
-    // Identity context the consumer wired in at construction. The shape
-    // (`{userId, organizationId, teamIds}`) is currently a fixed contract
-    // because the Go-era bootstrap protocol embedded those keys in scope
-    // tokens; the SDK should eventually expose this as an opaque
-    // `principal` blob so consumers with different identity models
-    // aren't forced into user/org. See the architectural note in the
-    // README — "currentUserId" is a domain concept, not an SDK
-    // primitive, and the host (apps/web/SyncEngineProvider) is the
-    // right place to surface it.
+    // The identity the consumer supplied to `initialize()`: user id,
+    // organization id, and optional team ids. Reads are scoped to this
+    // identity, and the sync-group subscription is derived from it.
     userContext = null;
     // ── Smart sync ──
     /**
@@ -272,18 +264,16 @@ export class BaseSyncedStore {
         this._syncServerUrl = dependencies.url;
         // Set this store as the global Model store
         Model.setStore(this);
-        // ── Schema-derived sync plan (Phase 2) ─────────────────────────────
+        // ── Schema-derived sync plan ───────────────────────────────────────
         //
-        // When a schema is provided, derive FK indexes and the enrichment
-        // plan from declarative annotations on the schema's `belongsTo`
-        // relations. Explicit config fields layer on top, so subclasses
-        // (like Ablo's SyncedStore) can pass hardcoded arrays without
-        // needing a full schema.generated.ts.
+        // When a schema is provided, derive foreign-key indexes and the
+        // enrichment plan from the declarative annotations on its `belongsTo`
+        // relations. Explicit config fields layer on top, so a subclass can
+        // pass hardcoded arrays without supplying a full schema.
         //
-        // Order matters: schema-derived first, config second, so that in a
-        // future where Ablo passes both (schema AND explicit config), the
-        // explicit config entries are registered last and can't be
-        // accidentally shadowed by schema derivation.
+        // Order matters: schema-derived entries are registered first and
+        // config entries second, so that when a caller supplies both, the
+        // explicit config entries win and are never shadowed by derivation.
         const derived = dependencies.schema
             ? deriveSyncPlanFromSchema(dependencies.schema)
             : { enrichmentPlan: [], foreignKeyIndexes: [] };
@@ -294,9 +284,8 @@ export class BaseSyncedStore {
         for (const { modelName, fieldName } of mergedForeignKeyIndexes) {
             this.objectPool.registerForeignKey(modelName, fieldName);
         }
-        // Legacy override hook — still called AFTER schema-driven registration
-        // so subclasses can add more FKs on top of the declarative set.
-        // Kept for backwards compat; subclasses migrate to config at leisure.
+        // Override hook — called after schema-driven registration so a subclass
+        // can add more foreign keys on top of the declarative set.
         this.registerForeignKeys();
         this.enrichmentPlan = [
             ...derived.enrichmentPlan,
@@ -328,15 +317,13 @@ export class BaseSyncedStore {
                 this.queryProcessor.invalidateCache(`.*${name}.*`);
             }
         });
-        // Make sync status fields observable so consumer code can do
+        // Make the sync-status fields observable so consumer code can do
         //   reaction(() => store.isReady, ...)
         //   observer(() => store.isOffline)
         // and actually receive notifications. Without these annotations,
-        // `syncStatus` / `dataReady` are plain properties and the derived
-        // getters (isReady, isSyncing, isOffline, ...) never emit change
-        // signals — a trap that has burned multiple downstream apps
-        // (one stuck forever on the loading skeleton because `reaction`
-        // to `store.isReady` never fired). Explicit > accidental.
+        // `syncStatus` and `dataReady` are plain properties, and the derived
+        // getters (isReady, isSyncing, isOffline, and the rest) never emit
+        // change signals — so a `reaction` on `store.isReady` would never fire.
         makeObservable(this, {
             syncStatus: observable,
             dataReady: observable,
@@ -350,17 +337,17 @@ export class BaseSyncedStore {
     }
     // ── Protected extension points ────────────────────────────────────────────
     /**
-     * Register foreign key indexes for O(1) lookups.
+     * Register foreign-key indexes for constant-time lookups.
      *
-     * Legacy override hook — in Phase 2 the preferred way to declare FK
-     * indexes is via `config.foreignKeyIndexes` at construction time, or
-     * by marking the `belongsTo` relation with `{ index: true }` in the
-     * schema. This hook still fires AFTER the schema-derived + config
-     * registrations, so subclasses can layer additional FKs on top.
+     * This is an override hook. The preferred way to declare a foreign-key
+     * index is `config.foreignKeyIndexes` at construction time, or marking the
+     * `belongsTo` relation with `{ index: true }` in the schema. The hook fires
+     * after the schema-derived and config registrations, so a subclass can
+     * layer additional indexes on top.
      */
     registerForeignKeys() { }
     /**
-     * Enrich delta data with related models from the ObjectPool.
+     * Enrich delta data with related models from the InstanceCache.
      *
      * Base implementation walks `this.enrichmentPlan` — entries populated
      * from the schema's `{ enrich: true }` relations and from
@@ -615,7 +602,7 @@ export class BaseSyncedStore {
                 this.syncWebSocket?.disconnect();
                 this.updateSyncStatus({ state: 'error', error: error });
                 // SECURITY: Clear locally cached data when session is invalid
-                this.database.clear().catch(() => { });
+                this.database.clear({ includeWriteJournal: true }).catch(() => { });
                 this.objectPool.clear();
                 return 'session_error';
             }
@@ -656,11 +643,12 @@ export class BaseSyncedStore {
         return this.credentialLifecycle.refresh();
     }
     /**
-     * THE auth-recovery backbone for HTTP transports (lazy query lane etc.):
-     * classify-driven single-flight re-mint with the same FSM outcome routing
-     * the WS probe and proactive pre-roll use. `'retry'` ⇒ a fresh credential
-     * is in the credential source, replay the request ONCE. Full contract on
-     * {@link CredentialLifecycle.recoverFromAuthRejection}.
+     * The authentication-recovery path for HTTP transports, such as the lazy
+     * query lane. It runs a single-flight credential re-mint driven by the
+     * rejection's recovery class, routing outcomes through the same state
+     * machine the WebSocket probe uses. `'retry'` means a fresh credential is
+     * now in the credential source and the request should be replayed once.
+     * Full contract on {@link CredentialLifecycle.recoverFromAuthRejection}.
      */
     async recoverFromAuthRejection(recovery) {
         return this.credentialLifecycle.recoverFromAuthRejection(recovery);
@@ -676,11 +664,11 @@ export class BaseSyncedStore {
         this.connectionManager?.send({ type: 'CREDENTIAL_REFRESHED' });
     }
     /**
-     * Install the access-credential lifecycle the CLIENT owns: register
-     * `getToken` as the reactive re-mint hook AND arm the browser-only
-     * proactive pre-roll (refresh timer + OS-wake re-mint). Idempotent
-     * (a second call replaces the first); torn down on {@link disconnect}.
-     * Full rationale on {@link CredentialLifecycle.start}.
+     * Install the client-owned access-credential lifecycle: register `getToken`
+     * as the reactive re-mint hook and arm the browser-only proactive refresh
+     * (a refresh timer plus an OS-wake re-mint). Idempotent — a second call
+     * replaces the first — and torn down on {@link disconnect}. Full rationale
+     * on {@link CredentialLifecycle.start}.
      */
     startCredentialLifecycle(getToken, opts) {
         this.credentialLifecycle.start(getToken, opts);
@@ -689,12 +677,12 @@ export class BaseSyncedStore {
     stopCredentialLifecycle() {
         this.credentialLifecycle.stop();
     }
-    // ── Sync Group Management ────────────────────────────────────────────────
+    // ── Sync group management ────────────────────────────────────────────────
     //
-    // Implementation extracted to sync/groupChange.ts. The methods below stay
-    // as thin protected delegates with unchanged signatures — subclass
-    // override points remain overridable, and the leaf routes cross-handler
-    // calls back through `groupChangeContext()` so dynamic dispatch holds.
+    // The implementation lives in the sync/groupChange module. The methods
+    // below are thin protected delegates that keep their signatures, so
+    // subclass override points still work; the module routes cross-handler
+    // calls back through `groupChangeContext()` to preserve dynamic dispatch.
     /** Narrow context the group-change leaf talks back through. */
     groupChangeContext() {
         return {
@@ -726,8 +714,9 @@ export class BaseSyncedStore {
         return groupChange.handleGroupAdded(this.groupChangeContext(), payload, syncId);
     }
     /**
-     * Handle an actionType 'S' (GroupRemoved) delta — SECURITY clear of local
-     * state + full re-bootstrap. See {@link groupChange.handleGroupRemoved}.
+     * Handle an actionType 'S' (GroupRemoved) delta: for safety, clear the
+     * revoked local state and trigger a full re-bootstrap. See
+     * {@link groupChange.handleGroupRemoved}.
      */
     async handleGroupRemoved(delta) {
         return groupChange.handleGroupRemoved(this.groupChangeContext(), delta);
@@ -758,10 +747,10 @@ export class BaseSyncedStore {
     }
     // ── Bootstrap apply ──────────────────────────────────────────────────────
     //
-    // Implementation extracted to sync/bootstrapApply.ts. Thin protected
-    // delegates below keep the signatures (and subclass overridability)
-    // unchanged; the leaf talks back through `poolContext()` — enrichment
-    // stays pre-bound to `this.enrichRelations` so that override point holds.
+    // The implementation lives in the sync/bootstrapApply module. The protected
+    // delegates below keep their signatures and subclass overridability; the
+    // module talks back through `poolContext()`, with enrichment pre-bound to
+    // `this.enrichRelations` so that override point still applies.
     /** Narrow context the bootstrap-apply leaf talks back through. */
     poolContext() {
         const store = this;
@@ -777,8 +766,7 @@ export class BaseSyncedStore {
             applyDeltaFrame: (deltas) => { this.applyDeltaFrame(deltas); },
         };
     }
-    /** Apply bootstrap data to the ObjectPool with ghost removal */
-    /** Apply bootstrap data to the ObjectPool. Delegates pool writes to SyncClient. */
+    /** Apply bootstrap data to the {@link InstanceCache}, removing entities that are no longer present (ghost removal). Pool writes are delegated to {@link SyncClient}. */
     applyBootstrapToPool(bootstrapResult, protectedIds) {
         return bootstrapApply.applyBootstrapToPool(this.poolContext(), bootstrapResult, protectedIds);
     }
@@ -791,19 +779,15 @@ export class BaseSyncedStore {
         if (this.initialized)
             return { success: true };
         this.userContext = context;
-        // Propagate identity to SyncClient. Without this, every mutation
-        // silently drops in `processPendingMutations` / `stageMutation` with
-        // `userId=null, organizationId=null`. Previously the SDK assumed
-        // callers would call `syncClient.initialize()` themselves as a
-        // separate step — that never happened from createSyncEngine, and
-        // the drop was invisible because both guard sites just early-return
-        // rather than throw. The right fix is to do it here where the store
-        // receives the context, so identity is one source of truth.
-        yield this.syncClient.initialize(context.userId, context.organizationId);
         try {
             this.updateSyncStatus({ state: 'syncing', progress: 0 });
-            // Open database
+            // The commit outbox and offline mutation journal live in IndexedDB.
+            // Open it before SyncClient restores either one; reading first used to
+            // make persistence silently look empty on every cold start.
             yield this.database.open(context.userId, context.organizationId);
+            // Propagate identity only after storage is ready, then restore sealed
+            // requests before accepting fresh mutations.
+            yield this.syncClient.initialize(context.userId, context.organizationId);
             // Hydrate from IndexedDB (fast, cached data)
             let hasLocalData = false;
             try {
@@ -1146,7 +1130,7 @@ export class BaseSyncedStore {
         // connection. baseGroups (the org/user scopes) are always subscribed;
         // enterScope/leaveScope move per-entity interest. Recreated with the
         // socket; torn down via the disposer pushed below.
-        this.areaOfInterest = new AreaOfInterestManager({
+        this.areaOfInterest = new SubscriptionManager({
             transport: this.syncWebSocket,
             baseGroups: this.resolveSyncGroups(context),
         });
@@ -1217,7 +1201,7 @@ export class BaseSyncedStore {
             this.updateSyncStatus({ state: 'error', error, isSessionError: true });
             // SECURITY: Clear IndexedDB data on session expiry.
             // When auth is revoked, locally cached data must not persist on disk.
-            this.database.clear().catch((clearErr) => {
+            this.database.clear({ includeWriteJournal: true }).catch((clearErr) => {
                 // consumer register: session ended, but cached data may remain on disk
                 getContext().logger.error('Your session ended, but some locally cached data could not be cleared from this device.');
                 getContext().logger.debug('[BaseSyncedStore] Failed to clear database on session error', clearErr);
@@ -1394,14 +1378,14 @@ export class BaseSyncedStore {
         this.disposers.push(unsubCreated, unsubCompleted, unsubFailed);
         this.syncWebSocket.connect();
     }
-    // ── Delta Processing Pipeline ─────────────────────────────────────────────
+    // ── Delta processing pipeline ─────────────────────────────────────────────
     //
-    // Implementation extracted to sync/deltaPipeline.ts (dedup, enqueue
-    // bookkeeping, debounce, flush). The methods below stay as thin protected
-    // delegates with unchanged signatures, and the leaf routes every call to
-    // a protected override point back through `deltaPipelineContext` so
-    // subclass dynamic dispatch is preserved. `applyDeltaFrame` — the
-    // authoritative-apply correctness seam — deliberately stays here.
+    // The implementation lives in the sync/deltaPipeline module (deduplication,
+    // enqueue bookkeeping, debounce, flush). The methods below are thin protected
+    // delegates with unchanged signatures, and the module routes every call to a
+    // protected override point back through `deltaPipelineContext`, so subclass
+    // dynamic dispatch is preserved. `applyDeltaFrame`, the authoritative-apply
+    // correctness point, deliberately stays here.
     /** Memoized pipeline context — `enqueueDelta` runs once per delta, so the
      *  accessor object is built once and reused (the get/set accessors always
      *  read the live host fields). */
@@ -1464,35 +1448,36 @@ export class BaseSyncedStore {
     /**
      * Apply a complete, server-delivered delta frame atomically.
      *
-     * A `delta_batch` WS event (reconnect/catch-up replay) already carries
-     * the FULL set of missed deltas. Routing it through the per-delta
-     * `processDeltaWithBatching` path re-chunks it via the live-traffic
-     * debounce timer + `maxBatchSize` force-flush, so a 300-delta catch-up
-     * fans out into ~6 separate `flushPendingDeltas` cycles — each its own
-     * IDB write, pool mutation, `models:changed` emit, and React re-render.
-     * The decks gallery visibly re-sorts and "pops in" once per chunk.
+     * A `delta_batch` WebSocket event (a reconnect or catch-up replay) already
+     * carries the full set of missed deltas. Routing it through the per-delta
+     * `processDeltaWithBatching` path would re-chunk it via the live-traffic
+     * debounce timer and `maxBatchSize` force-flush, so a 300-delta catch-up
+     * would fan out into several separate `flushPendingDeltas` cycles — each its
+     * own local write, pool mutation, `models:changed` emit, and re-render, so
+     * the UI visibly repaints once per chunk.
      *
-     * Here we run the per-delta bookkeeping (dedup, ack, version vector,
-     * watermark, G/S routing, D cascade) for every delta WITHOUT scheduling
-     * a flush, then flush ONCE — collapsing the whole frame into a single
-     * IDB write + pool mutation + `models:changed` + re-render. Same code
-     * for the post-bootstrap replay of deltas queued during bootstrap.
+     * Instead, this runs the per-delta bookkeeping (deduplication, ack, version
+     * vector, watermark, group-change routing, delete cascade) for every delta
+     * without scheduling a flush, then flushes once — collapsing the whole frame
+     * into a single local write, pool mutation, `models:changed` emit, and
+     * re-render. The post-bootstrap replay of deltas queued during bootstrap
+     * uses the same path.
      *
-     * (Named `applyDeltaFrame`, not `processDeltaBatch`, to avoid confusion
-     * with `Database.processDeltaBatch` — the lower-level IDB write this
-     * eventually drives through `flushPendingDeltas`.)
+     * It is named `applyDeltaFrame`, not `processDeltaBatch`, to avoid confusion
+     * with {@link Database.processDeltaBatch} — the lower-level local write this
+     * eventually drives through `flushPendingDeltas`.
      */
     applyDeltaFrame(deltas) {
         let enqueuedAny = false;
         for (const delta of deltas) {
-            // A delta_batch frame is the server's AUTHORITATIVE, ordered answer to
+            // A delta_batch frame is the server's authoritative, ordered answer to
             // "everything in my stream after cursor C" (reconnect/catch-up replay or
-            // post-bootstrap drain). Apply every delta it carries — do NOT subject it
+            // post-bootstrap drain). Apply every delta it carries; do not subject it
             // to the live-traffic watermark dedup (`id <= applied`).
             //
             // That watermark is only valid under in-order delivery, and reconnect
-            // breaks the assumption: an in-flight LIVE broadcast for a gap delta can
-            // land out of order BEFORE the catch-up fills the ids below it (e.g. the
+            // breaks the assumption: an in-flight live broadcast for a gap delta can
+            // land out of order before the catch-up fills the ids below it (e.g. the
             // server acks a write, then the test/client reconnects, then that write's
             // pending broadcast arrives on the fresh socket — id 4 live before the
             // catch-up's [2,3,4]). Applying id 4 advances `applied` to 4, and the
@@ -1565,16 +1550,15 @@ export class BaseSyncedStore {
             });
         }
     }
-    /** Flush pending deltas with deduplication and batched ObjectPool mutations */
-    /** Flush pending deltas with deduplication. Delegates pool writes to SyncClient. */
+    /** Flush pending deltas with deduplication. Pool writes are delegated to {@link SyncClient}. */
     async flushPendingDeltas() {
         return deltaPipeline.flushPendingDeltas(this.deltaPipelineContext);
     }
-    // ── Core Mutations (thin delegation to SyncClient) ────────────────────────
+    // ── Core mutations (thin delegation to SyncClient) ────────────────────────
     //
-    // BaseSyncedStore is an orchestrator, not an implementor.
-    // SyncClient owns: ObjectPool operations, TransactionQueue, IDB writes.
-    // BaseSyncedStore owns: validation, hooks, pending delete tracking.
+    // This class orchestrates; it does not implement the writes. {@link SyncClient}
+    // owns the object-pool operations, the transaction queue, and local writes.
+    // This class owns validation, lifecycle hooks, and pending-delete tracking.
     /** Check if a model type is local-only (no sync). Override for domain-specific models. */
     isLocalOnlyModel(_modelName) {
         return false;
@@ -1646,9 +1630,9 @@ export class BaseSyncedStore {
         this.syncClient.update(model);
     }
     // ── Query API ────────────────────────────────────────────────────────────
-    // `store.query.<model>.*` was DELETED — `ablo.<model>.get/getAll` is the
-    // one read surface. Custom mutators still read transactionally through
-    // `tx.<model>` (mutators/Transaction.ts), which owns `createReaderActions`.
+    // `ablo.<model>.get` / `ablo.<model>.getAll` is the read surface for
+    // application code. Custom mutators read transactionally through
+    // `tx.<model>`, backed by `createReaderActions`.
     /** Retrieve a single entity by id. Synchronous pool read. */
     retrieve(_modelClass, id) {
         return this.objectPool.get(id);
@@ -1692,10 +1676,10 @@ export class BaseSyncedStore {
         return this.objectPool.create(wireTypename, data);
     }
     /**
-     * Legacy class-based query entry point — kept for callers that still pass
-     * a Model constructor + options object. New code should use the typed
-     * `store.query.<modelKey>` namespace instead, which returns properly
-     * inferred schema types without needing a class value or cast.
+     * Query entry point for callers that hold a {@link Model} constructor and an
+     * options object. It filters, orders, and paginates the matching models from
+     * the pool. Prefer the schema-typed read surface (`ablo.<model>.list`) where
+     * you can, since it infers concrete row types without a class value or cast.
      */
     queryByClass(modelClass, options) {
         const modelName = this.objectPool.registry.getModelNameFromConstructor(modelClass);
@@ -1804,8 +1788,7 @@ export class BaseSyncedStore {
         return this.lastAckedId;
     }
     // ── Status convenience getters ──────────────────────────────────────────
-    // Thin wrappers over syncStatus for consumer ergonomics. Previously on
-    // SyncedStore; moved here so createSyncEngine consumers get them too.
+    // Thin wrappers over `syncStatus` for consumer ergonomics.
     get isReady() {
         // Ready if: fully synced (idle + 100%) OR local data loaded (dataReady + syncing in background)
         return (this.syncStatus.state === 'idle' && this.syncStatus.progress >= 100)