@abloatai/ablo 0.26.0 → 0.27.0

package/dist/sync/deltaPipeline.js

@@ -1,27 +1,25 @@
 /**
- * deltaPipeline — the incoming-delta dedup/batch/flush pipeline.
- *
- * Extracted from BaseSyncedStore.ts as a cohesive leaf: state-signature
- * dedup, per-delta bookkeeping + enqueue, the live-traffic debounce, and
- * the IDB→pool flush. The store keeps thin protected delegates with
- * unchanged signatures, and the leaf routes every call to a protected
- * override point (getStateFields, isCustomEntity, deduplicateDeltas,
- * flushPendingDeltas, the G/S handlers, …) back through the minimal
- * {@link DeltaPipelineContext} so subclass dynamic dispatch is preserved.
- * `applyDeltaFrame` — the authoritative-apply correctness seam — stays in
- * BaseSyncedStore and drives this pipeline via `enqueueDelta` +
- * `flushPendingDeltas`.
+ * The pipeline that takes incoming deltas from the server and lands them in
+ * local state. It has four stages: deduplicating deltas by state signature,
+ * per-delta bookkeeping and enqueue, a debounce for live traffic, and a flush
+ * that writes to the local store and then the in-memory pool. Every call it
+ * makes back into the surrounding store — resolving state fields, identifying
+ * custom entities, deduplicating, flushing, handling sync-group changes —
+ * routes through the {@link DeltaPipelineContext} interface, so a subclass that
+ * overrides any of those hooks still takes effect. The atomic frame-apply entry
+ * point lives on the store and drives this pipeline through {@link enqueueDelta}
+ * and {@link flushPendingDeltas}.
  */
 import { runInAction } from 'mobx';
 import { getContext } from '../context.js';
-import { ModelScope } from '../ObjectPool.js';
+import { ModelScope } from '../InstanceCache.js';
 /**
- * A 'G'/'S' handler rejected AFTER the applied watermark already advanced —
- * the delta will never be re-delivered, so a failed SECURITY clear (revoked
- * data must not persist) would otherwise be permanently silent. Fall back to
- * the bluntest safe response: drop the whole in-memory pool and force a full
- * re-bootstrap so local state is rebuilt from server truth. Never throws —
- * this runs inside the delta pipeline's fire-and-forget seam.
+ * Handles a sync-group ('G' or 'S') delta whose handler rejected after the
+ * applied watermark had already advanced. That delta will never be redelivered,
+ * so a failed security clear — revoked data that must not stay cached — would
+ * otherwise fail silently. The safe fallback is blunt: drop the whole in-memory
+ * pool and force a full re-bootstrap, rebuilding local state from the server.
+ * It never throws, because it runs inside the pipeline's fire-and-forget path.
  */
 export function handleGroupHandlerFailure(ctx, delta, error) {
     getContext().logger.error('Your access changed but cached data could not be cleared — resetting local data.', {
@@ -41,7 +39,7 @@ export function handleGroupHandlerFailure(ctx, delta, error) {
         // Best-effort: the reconnect/bootstrap cycle self-heals on next connect.
     }
 }
-/** State signature for delta deduplication */
+/** Builds a small signature of a delta's state fields, used to detect no-op duplicate deltas. */
 function extractStateSignature(ctx, delta) {
     if (!delta.data || typeof delta.data !== 'object')
         return null;
@@ -110,19 +108,19 @@ export function deduplicateDeltas(ctx, deltas) {
     return result.sort((a, b) => a.id - b.id);
 }
 /**
- * Per-delta bookkeeping + enqueue. Returns `true` when the delta was
- * pushed onto `pendingDeltas` (a regular batchable I/U/C/D delta that a
- * subsequent flush must drain), `false` when it was skipped (dedup),
- * deferred (bootstrap queue), or handled immediately out-of-band (G/S
- * sync-group mutations). Does NOT schedule a flush — callers decide
- * whether to debounce (live) or flush atomically (catch-up frame).
+ * Performs per-delta bookkeeping and enqueues the delta. Returns `true` when
+ * the delta was pushed onto `pendingDeltas` — a regular batchable insert,
+ * update, covering, or delete that a later flush must drain — and `false` when
+ * it was skipped as a duplicate, deferred into the bootstrap queue, or handled
+ * immediately (a 'G'/'S' sync-group change). It does not schedule the flush
+ * itself; the caller chooses whether to debounce live traffic or flush a
+ * catch-up frame atomically.
  */
 export function enqueueDelta(ctx, delta, options = {}) {
     // Dedup guard — skip already-processed deltas. The `applied` watermark is a
-    // valid skip threshold ONLY for in-order live traffic; an authoritative
-    // catch-up frame bypasses it (see `applyDeltaFrame`) so an out-of-order
-    // live delta that advanced the watermark can't cause the frame's lower ids
-    // to be silently dropped.
+    // valid skip threshold only for in-order live traffic; an authoritative
+    // catch-up frame bypasses it, so an out-of-order live delta that advanced the
+    // watermark can't cause the frame's lower ids to be dropped silently.
     if (!options.authoritative && delta.id > 0 && delta.id <= ctx.highestProcessedSyncId) {
         return false;
     }
@@ -135,10 +133,11 @@ export function enqueueDelta(ctx, delta, options = {}) {
     }
     // Advance watermark
     ctx.advanceApplied(delta.id);
-    // Sync group added — handle immediately. Supports both legacy
-    // (addedGroups/removedGroups) and incremental (group/userId) payloads.
-    // NOT fire-and-forget: the watermark above already advanced, so a rejected
-    // handler (a failed security clear) must trigger the fallback, not vanish.
+    // Sync group added — handle immediately. Accepts both the batched
+    // (addedGroups/removedGroups) and incremental (group/userId) payloads. This
+    // is deliberately not fire-and-forget: the watermark has already advanced, so
+    // a rejected handler (a failed security clear) must trigger the fallback
+    // rather than vanish.
     if (delta.actionType === 'G') {
         void ctx.handleSyncGroupChange(delta).catch((error) => {
             handleGroupHandlerFailure(ctx, delta, error);
@@ -154,16 +153,16 @@ export function enqueueDelta(ctx, delta, options = {}) {
         });
         return false;
     }
-    // DELETE — fire the cascade cancel immediately (O(1) via FK index;
-    // must run BEFORE any subsequent update on the same model lands so
-    // pending update transactions for soon-deleted children don't race
-    // their parent's delete) but route the IDB+pool write through the
-    // same batched path as UPDATEs. The previous immediate-flush path
-    // produced N IDB writes + N pool mutations + N `models:changed`
-    // events when a peer deleted a chart with N layers; the batched
-    // path produces one of each per microtask flush. Dedup in
-    // `flushPendingDeltas` handles the U-then-D-on-same-model case
-    // correctly via arrival-order replay through `processDeltaBatch`.
+    // Delete — run the cascade cancel immediately (O(1) through the foreign-key
+    // index; it must run before any later update on the same model lands, so
+    // pending update transactions for soon-deleted children don't race their
+    // parent's delete). The persistence and pool write still goes through the
+    // same batched path as updates: flushing each delete on its own produced one
+    // store write, one pool mutation, and one `models:changed` event per row, so
+    // deleting a parent with many children fanned out into many of each, whereas
+    // the batched path collapses them into one per flush. Deduplication in
+    // `flushPendingDeltas` handles an update-then-delete on the same model by
+    // replaying in arrival order.
     if (delta.actionType === 'D') {
         ctx.cascadeCancelTransactionsForDeletedParent(delta.modelName, delta.modelId);
     }
@@ -183,13 +182,16 @@ export function scheduleDeltaFlush(ctx) {
         }, ctx.smartSyncOptions.batchingDelay);
     }
 }
-/** Flush pending deltas with deduplication and batched ObjectPool mutations */
-/** Flush pending deltas with deduplication. Delegates pool writes to SyncClient. */
+/**
+ * Flushes the queued deltas: deduplicates them, applies custom-entity deltas
+ * straight to the pool, writes the rest to the local store and then the pool,
+ * and advances the acknowledgement cursor once the store write has committed.
+ */
 export async function flushPendingDeltas(ctx) {
     if (ctx.pendingDeltas.length === 0)
         return;
     const deduplicatedDeltas = ctx.deduplicateDeltas(ctx.pendingDeltas);
-    // Custom entities → apply directly to ObjectPool (skip IDB)
+    // Custom entities → apply straight to the pool, skipping the local store.
     const customDeltas = deduplicatedDeltas.filter((d) => ctx.isCustomEntity(d.modelName));
     if (customDeltas.length > 0) {
         runInAction(() => {
@@ -219,10 +221,10 @@ export async function flushPendingDeltas(ctx) {
             }
         });
     }
-    // Regular deltas → IDB then ObjectPool via SyncClient.
-    // 'G' and 'S' deltas are routed upstream (handleSyncGroupChange,
-    // handleGroupRemoved) and never reach flushPendingDeltas, but the
-    // Database.processDelta signature accepts them defensively.
+    // Regular deltas → the local store, then the pool.
+    // 'G' and 'S' deltas are handled earlier (handleSyncGroupChange /
+    // handleGroupRemoved) and never reach here, though the persistence
+    // signature accepts them defensively.
     const regularDeltas = deduplicatedDeltas.filter((d) => !ctx.isCustomEntity(d.modelName));
     const batch = await ctx.processDeltaBatch(regularDeltas.map((d) => ({
         syncId: d.id,
@@ -230,30 +232,27 @@ export async function flushPendingDeltas(ctx) {
         modelName: d.modelName,
         modelId: d.modelId,
         data: typeof d.data === 'string' ? JSON.parse(d.data) : d.data,
-        // Thread `transactionId` through so the receive layer can
-        // recognize echoes of locally-applied transactions and skip
-        // the pool mutation. See `OPTIMISTIC_RECONCILIATION.md`.
+        // Thread `transactionId` through so the receive layer can recognize
+        // echoes of locally-applied transactions and skip the pool mutation.
         transactionId: d.transactionId,
     })));
     const dbResults = batch.results;
-    // Delegate ObjectPool writes to SyncClient (owns pool operations)
+    // Apply the batch results to the in-memory pool.
     ctx.applyDeltaBatchToPool(dbResults);
-    // Acknowledge + advance sync cursor — gated on IDB persistence.
+    // Acknowledge and advance the sync cursor, gated on persistence.
     //
-    // We MUST ack `persistedSyncId` (the high-water mark of deltas whose
-    // store transaction actually committed), NOT the input batch's last
-    // delta id. Acking by input range advances the server's view past
-    // deltas that never wrote to IDB; the next catch-up request would
-    // then send the advanced cursor and the server replies "you're up
-    // to date" — losing the un-persisted delta forever. This is the
-    // Replicache "same-transaction" invariant: the cursor and the
-    // persisted view must be consistent.
+    // We must acknowledge `persistedSyncId` — the high-water mark of deltas whose
+    // store transaction actually committed — not the input batch's last delta id.
+    // Acknowledging the input range would advance the server's view past deltas
+    // that never persisted; the next catch-up would then send the advanced cursor,
+    // the server would answer "you're up to date", and the unpersisted delta would
+    // be lost. The cursor and the persisted state must move together.
     const persistedSyncId = batch.persistedSyncId;
     if (persistedSyncId > ctx.lastAckedId) {
         ctx.acknowledge(persistedSyncId);
         ctx.advancePersisted(persistedSyncId);
     }
-    // Cache invalidation is automatic via SyncClient 'models:changed' event
+    // Cache invalidation happens automatically via the 'models:changed' event.
     ctx.pendingDeltas = [];
     if (ctx.batchTimer) {
         clearTimeout(ctx.batchTimer);

package/dist/sync/groupChange.d.ts

@@ -1,23 +1,26 @@
 /**
- * groupChange — sync-group change / shrinkage handling.
+ * Handles the delta types that change which sync groups a session can see. A
+ * sync group is a fan-out scope the server uses to decide which entities a
+ * client receives. When a session's membership changes, these handlers update
+ * the client's subscription list; when access is revoked, they clear cached
+ * data and trigger a full re-bootstrap so revoked rows cannot linger on the
+ * device.
  *
- * Extracted from BaseSyncedStore.ts as a cohesive leaf: the 'G'/'S' delta
- * handlers (incremental group-added, legacy group-diff, group-removed), the
- * group-set math, the force-re-bootstrap trigger, and the security-critical
- * shrinkage check. The store keeps thin protected delegates with unchanged
- * signatures — subclass override points stay overridable, and the leaf
- * routes every cross-handler call back through the minimal
- * {@link GroupChangeContext} so dynamic dispatch is preserved.
+ * Every handler takes a {@link GroupChangeContext}, the narrow facade through
+ * which it reaches the client's local storage and connection lifecycle hooks.
  */
 import type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload } from './SyncWebSocket.js';
 /**
- * What the group-change handlers need back from their host store —
- * narrow collaborator facades plus the host's own protected hooks (so a
- * subclass override of e.g. `forceFullRebootstrap` still takes effect).
+ * The collaborators the group-change handlers depend on. It gathers the
+ * client's local storage, in-memory pool, and connection lifecycle hooks
+ * behind one narrow interface, so the handlers stay decoupled from the larger
+ * store that supplies them.
  */
 export interface GroupChangeContext {
-    /** Local persistence — SECURITY clears, subscription metadata, and the
-     *  full-bootstrap flag. Structural subset of `Database`. */
+    /**
+     * Local persistence. Performs the security clear, reads and writes the
+     * subscription metadata, and sets the flag that forces a full bootstrap.
+     */
     readonly database: {
         clear(): Promise<void>;
         getWorkspaceMetadata(): Promise<{
@@ -28,84 +31,83 @@ export interface GroupChangeContext {
         }): Promise<void>;
         markRequiresFullBootstrap(): void;
     };
-    /** The in-memory pool — cleared alongside IDB on revocation. */
+    /** The in-memory object cache, cleared alongside local storage when access is revoked. */
     readonly objectPool: {
         clear(): void;
     };
-    /** Groups the CURRENT socket is subscribed to (`syncWebSocket?.getSyncGroups() ?? []`). */
+    /** Returns the sync groups the live connection is currently subscribed to. */
     getSubscribedSyncGroups(): readonly string[];
-    /** The session's authoritative groups via the host's `resolveSyncGroups`;
-     *  null when no user context has been set yet. */
+    /**
+     * Returns the session's authoritative sync groups, resolved from the current
+     * user context via {@link resolveSyncGroups}; null when no user context has
+     * been set yet.
+     */
     getCurrentSyncGroups(): readonly string[] | null;
-    /** `userContext?.bootstrapMode` — 'none' participants never re-bootstrap. */
+    /**
+     * Returns the session's bootstrap mode. A value of 'none' means the
+     * participant never pulls a baseline, so it never re-bootstraps.
+     */
     getBootstrapMode(): 'full' | 'none' | undefined;
-    /** Disconnect the live socket (part of the force-re-bootstrap cycle). */
+    /** Disconnects the live connection, one step of the forced re-bootstrap cycle. */
     disconnectWebSocket(): void;
-    /** Forward to the host's `onConnectionEvent` lifecycle hook (no-op when unwired). */
+    /** Emits a connection lifecycle event to any registered listener; a no-op when none is set. */
     emitConnectionEvent(event: string): void;
     handleGroupAdded(payload: GroupAddedPayload, syncId: number): Promise<void>;
     computeUpdatedSyncGroups(payload: SyncGroupChangePayload): string[];
     forceFullRebootstrap(): void;
 }
 /**
- * Handle an actionType 'G' delta.
+ * Handles a 'G' (group-change) delta. The server sends two shapes of this
+ * delta, told apart by the payload:
  *
- * The server emits 'G' via two distinct pathways, distinguished by payload
- * shape:
+ *   Incremental — `{ group, userId }`: the recipient was added to a single
+ *   sync group. No re-bootstrap follows; the newly visible entities arrive as
+ *   ordinary 'C' (covering) deltas through the normal insert path.
  *
- *   Incremental (EmitGroupAdded):   { group, userId }
- *     - The recipient was added to a single sync group.
- *     - Subsequent 'C' (Covering) deltas deliver each newly-visible entity.
- *     - No re-bootstrap — entities arrive via the normal insert path.
- *
- *   Legacy (EmitGroupChange):       { addedGroups, removedGroups }
- *     - Single delta carrying the full group membership diff.
- *     - Forces a full re-bootstrap (disconnect + reconnect + fetch all).
- *     - Deprecated on the server; kept here for wire-level backward compat.
+ *   Full diff — `{ addedGroups, removedGroups }`: one delta carrying the whole
+ *   membership change. This forces a full re-bootstrap (disconnect, reconnect,
+ *   and refetch), clearing cached data first if any group was removed.
  */
 export declare function handleSyncGroupChange(ctx: GroupChangeContext, delta: SyncDelta): Promise<void>;
 /**
- * Handle an incremental GroupAdded delta.
- *
- * Adds the new group to the subscription metadata without triggering a
- * re-bootstrap. The server will follow up with 'C' (Covering) deltas for
- * each newly-visible entity, which flow through the normal insert path.
+ * Handles an incremental group-added delta. It records the new sync group in
+ * the subscription metadata without forcing a re-bootstrap; the server then
+ * sends a 'C' (covering) delta for each newly visible entity, which flows
+ * through the normal insert path.
  */
 export declare function handleGroupAdded(ctx: GroupChangeContext, payload: GroupAddedPayload, syncId: number): Promise<void>;
 /**
- * Handle an actionType 'S' (GroupRemoved) delta.
- *
- * Signals that the recipient has lost access to a sync group. Because
- * the client does not track per-entity group membership, we can't
- * selectively purge entities belonging to that group. The safe fallback
- * is the legacy behavior: clear local state and force a re-bootstrap
- * with the updated group list.
- *
- * Future optimization: track group membership in the ObjectPool so 'S'
- * can do a targeted purge instead of a full re-bootstrap.
+ * Handles an 'S' (group-removed) delta, which signals the recipient has lost
+ * access to a sync group. The client does not track which entities belong to
+ * which group, so it cannot purge only the affected rows; instead it clears
+ * local state and forces a re-bootstrap with the updated group list.
  */
 export declare function handleGroupRemoved(ctx: GroupChangeContext, delta: SyncDelta): Promise<void>;
-/** Compute new sync groups after applying additions and removals */
+/** Computes the new sync-group set after applying the additions and removals in a diff. */
 export declare function computeUpdatedSyncGroups(ctx: GroupChangeContext, payload: SyncGroupChangePayload): string[];
-/** Force a full re-bootstrap via connection lifecycle event.
- *
- * No-op for `bootstrapMode: 'none'` participants — they never pull
- * baseline state, so a "force re-bootstrap" trigger (sync-group
- * shrink, scope revocation) instead just flushes the local pool and
- * relies on covering deltas to repopulate the data they actually
+/**
+ * Forces a full re-bootstrap by marking local storage as needing one,
+ * disconnecting, and emitting a connection lifecycle event that the reconnect
+ * path acts on. Does nothing for participants whose bootstrap mode is 'none':
+ * they never pull a baseline, so after a trigger such as a sync-group shrink or
+ * an access revocation they rely on covering deltas to repopulate the data they
  * subscribe to.
  */
 export declare function forceFullRebootstrap(ctx: GroupChangeContext): void;
 /**
- * Single source of truth for the sync-group list this session is
- * subscribed to. Server-issued (`context.syncGroups`) is authoritative.
- * When absent, the SDK subscribes to no explicit groups. Both
- * `checkSyncGroupShrinkage` and `setupWebSocketSync` resolve through
- * here so the WS subscription and the security-critical shrinkage
- * check can never disagree.
+ * Resolves the sync-group list this session subscribes to, and is the single
+ * place that decision is made. The server-issued `context.syncGroups` is
+ * authoritative; when it is absent, the session subscribes to no explicit
+ * groups. {@link checkSyncGroupShrinkage} and connection setup both read
+ * through here, so the live subscription and the access-revocation check can
+ * never disagree.
  */
 export declare function resolveSyncGroups(context: {
     syncGroups?: readonly string[];
 }): readonly string[];
-/** Check if sync groups shrank since last session — force full bootstrap if so */
+/**
+ * Compares the session's current sync groups against the set stored from the
+ * last session. If any group is now missing, access has narrowed, so this
+ * clears cached data and forces a full bootstrap before recording the new set.
+ */
 export declare function checkSyncGroupShrinkage(ctx: GroupChangeContext): Promise<void>;