@abloatai/ablo 0.25.0 → 0.26.0

package/dist/sync/deltaPipeline.js

@@ -0,0 +1,262 @@
+/**
+ * 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`.
+ */
+import { runInAction } from 'mobx';
+import { getContext } from '../context.js';
+import { ModelScope } from '../ObjectPool.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.
+ */
+export function handleGroupHandlerFailure(ctx, delta, error) {
+    getContext().logger.error('Your access changed but cached data could not be cleared — resetting local data.', {
+        syncId: delta.id,
+        error: error instanceof Error ? error.message : String(error),
+    });
+    try {
+        ctx.objectPool.clear();
+    }
+    catch {
+        // In-memory clear must never mask the re-bootstrap below.
+    }
+    try {
+        ctx.forceFullRebootstrap();
+    }
+    catch {
+        // Best-effort: the reconnect/bootstrap cycle self-heals on next connect.
+    }
+}
+/** State signature for delta deduplication */
+function extractStateSignature(ctx, delta) {
+    if (!delta.data || typeof delta.data !== 'object')
+        return null;
+    const data = typeof delta.data === 'string'
+        ? JSON.parse(delta.data)
+        : (delta.data);
+    // Generic state fields — subclasses can override getStateFields() for model-specific fields
+    const fieldsToCheck = ctx.getStateFields(delta.modelName);
+    const signature = {
+        actionType: delta.actionType,
+        modelName: delta.modelName,
+    };
+    for (const field of fieldsToCheck) {
+        if (field in data)
+            signature[field] = data[field];
+    }
+    return signature;
+}
+function isSameState(a, b) {
+    if (!a || !b)
+        return false;
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length)
+        return false;
+    return keys.every((k) => a[k] === b[k]);
+}
+/** Deduplicate deltas to the same entity — keep meaningful state transitions only */
+export function deduplicateDeltas(ctx, deltas) {
+    const byEntity = new Map();
+    for (const d of deltas) {
+        const key = `${d.modelName}:${d.modelId}`;
+        if (!byEntity.has(key))
+            byEntity.set(key, []);
+        byEntity.get(key).push(d);
+    }
+    const result = [];
+    for (const entityDeltas of byEntity.values()) {
+        const sorted = entityDeltas.sort((a, b) => a.id - b.id);
+        // DELETE wins — it's the final state
+        const del = sorted.find((d) => d.actionType === 'D');
+        if (del) {
+            result.push(del);
+            continue;
+        }
+        // Keep deltas that represent different states
+        const unique = [];
+        let prev = null;
+        for (const d of sorted) {
+            const sig = extractStateSignature(ctx, d);
+            if (!isSameState(prev, sig)) {
+                unique.push(d);
+                prev = sig;
+            }
+        }
+        if (unique.length > 0) {
+            result.push(...unique);
+        }
+        else {
+            // `sorted` is never empty (every byEntity bucket gets at least one
+            // delta pushed) — the guard only narrows the indexed access.
+            const last = sorted.at(-1);
+            if (last)
+                result.push(last);
+        }
+    }
+    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).
+ */
+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.
+    if (!options.authoritative && delta.id > 0 && delta.id <= ctx.highestProcessedSyncId) {
+        return false;
+    }
+    // Confirm awaiting transactions via sync ID threshold (before batching)
+    ctx.onDeltaReceived(delta.id);
+    // Queue during active bootstrap
+    if (ctx.bootstrapDeltaQueue !== null) {
+        ctx.bootstrapDeltaQueue.push(delta);
+        return false;
+    }
+    // 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.
+    if (delta.actionType === 'G') {
+        void ctx.handleSyncGroupChange(delta).catch((error) => {
+            handleGroupHandlerFailure(ctx, delta, error);
+        });
+        return false;
+    }
+    // Sync group removed — handle immediately. Clears affected local state
+    // and forces re-bootstrap with the updated group list. Same fallback:
+    // a failed revocation clear escalates instead of leaving revoked rows.
+    if (delta.actionType === 'S') {
+        void ctx.handleGroupRemoved(delta).catch((error) => {
+            handleGroupHandlerFailure(ctx, delta, error);
+        });
+        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`.
+    if (delta.actionType === 'D') {
+        ctx.cascadeCancelTransactionsForDeletedParent(delta.modelName, delta.modelId);
+    }
+    ctx.pendingDeltas.push(delta);
+    return true;
+}
+/** Debounce a flush for live single-delta traffic. */
+export function scheduleDeltaFlush(ctx) {
+    if (ctx.batchTimer)
+        clearTimeout(ctx.batchTimer);
+    if (ctx.pendingDeltas.length >= ctx.smartSyncOptions.maxBatchSize) {
+        void ctx.flushPendingDeltas().catch(ctx.handleFlushError);
+    }
+    else {
+        ctx.batchTimer = setTimeout(() => {
+            void ctx.flushPendingDeltas().catch(ctx.handleFlushError);
+        }, ctx.smartSyncOptions.batchingDelay);
+    }
+}
+/** Flush pending deltas with deduplication and batched ObjectPool mutations */
+/** Flush pending deltas with deduplication. Delegates pool writes to SyncClient. */
+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)
+    const customDeltas = deduplicatedDeltas.filter((d) => ctx.isCustomEntity(d.modelName));
+    if (customDeltas.length > 0) {
+        runInAction(() => {
+            for (const delta of customDeltas) {
+                const data = typeof delta.data === 'string'
+                    ? JSON.parse(delta.data)
+                    : (delta.data);
+                // 'C' (Covering) is treated identically to 'I' here — the client
+                // gained permission to see the entity, so we insert it into the
+                // pool as if newly created.
+                if (delta.actionType === 'I' || delta.actionType === 'U' || delta.actionType === 'C') {
+                    const existing = ctx.objectPool.get(delta.modelId);
+                    if (existing) {
+                        existing.updateFromData(data);
+                    }
+                    else {
+                        const model = ctx.createCustomEntity(delta.modelName, delta.modelId, data);
+                        if (model) {
+                            model.markAsPersisted();
+                            ctx.objectPool.add(model, ModelScope.live);
+                        }
+                    }
+                }
+                else if (delta.actionType === 'D') {
+                    ctx.objectPool.remove(delta.modelId);
+                }
+            }
+        });
+    }
+    // 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.
+    const regularDeltas = deduplicatedDeltas.filter((d) => !ctx.isCustomEntity(d.modelName));
+    const batch = await ctx.processDeltaBatch(regularDeltas.map((d) => ({
+        syncId: d.id,
+        actionType: d.actionType,
+        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`.
+        transactionId: d.transactionId,
+    })));
+    const dbResults = batch.results;
+    // Delegate ObjectPool writes to SyncClient (owns pool operations)
+    ctx.applyDeltaBatchToPool(dbResults);
+    // Acknowledge + advance sync cursor — gated on IDB 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.
+    const persistedSyncId = batch.persistedSyncId;
+    if (persistedSyncId > ctx.lastAckedId) {
+        ctx.acknowledge(persistedSyncId);
+        ctx.advancePersisted(persistedSyncId);
+    }
+    // Cache invalidation is automatic via SyncClient 'models:changed' event
+    ctx.pendingDeltas = [];
+    if (ctx.batchTimer) {
+        clearTimeout(ctx.batchTimer);
+        ctx.batchTimer = null;
+    }
+}

package/dist/sync/groupChange.d.ts

@@ -0,0 +1,111 @@
+/**
+ * groupChange — sync-group change / shrinkage handling.
+ *
+ * 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.
+ */
+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).
+ */
+export interface GroupChangeContext {
+    /** Local persistence — SECURITY clears, subscription metadata, and the
+     *  full-bootstrap flag. Structural subset of `Database`. */
+    readonly database: {
+        clear(): Promise<void>;
+        getWorkspaceMetadata(): Promise<{
+            subscribedSyncGroups?: string[];
+        } | null>;
+        updateWorkspaceMetadata(metadata: {
+            subscribedSyncGroups: string[];
+        }): Promise<void>;
+        markRequiresFullBootstrap(): void;
+    };
+    /** The in-memory pool — cleared alongside IDB on revocation. */
+    readonly objectPool: {
+        clear(): void;
+    };
+    /** Groups the CURRENT socket is subscribed to (`syncWebSocket?.getSyncGroups() ?? []`). */
+    getSubscribedSyncGroups(): readonly string[];
+    /** The session's authoritative groups via the host's `resolveSyncGroups`;
+     *  null when no user context has been set yet. */
+    getCurrentSyncGroups(): readonly string[] | null;
+    /** `userContext?.bootstrapMode` — 'none' participants never re-bootstrap. */
+    getBootstrapMode(): 'full' | 'none' | undefined;
+    /** Disconnect the live socket (part of the force-re-bootstrap cycle). */
+    disconnectWebSocket(): void;
+    /** Forward to the host's `onConnectionEvent` lifecycle hook (no-op when unwired). */
+    emitConnectionEvent(event: string): void;
+    handleGroupAdded(payload: GroupAddedPayload, syncId: number): Promise<void>;
+    computeUpdatedSyncGroups(payload: SyncGroupChangePayload): string[];
+    forceFullRebootstrap(): void;
+}
+/**
+ * Handle an actionType 'G' delta.
+ *
+ * The server emits 'G' via two distinct pathways, distinguished by payload
+ * shape:
+ *
+ *   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.
+ */
+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.
+ */
+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.
+ */
+export declare function handleGroupRemoved(ctx: GroupChangeContext, delta: SyncDelta): Promise<void>;
+/** Compute new sync groups after applying additions and removals */
+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
+ * 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.
+ */
+export declare function resolveSyncGroups(context: {
+    syncGroups?: readonly string[];
+}): readonly string[];
+/** Check if sync groups shrank since last session — force full bootstrap if so */
+export declare function checkSyncGroupShrinkage(ctx: GroupChangeContext): Promise<void>;

package/dist/sync/groupChange.js

@@ -0,0 +1,246 @@
+/**
+ * groupChange — sync-group change / shrinkage handling.
+ *
+ * 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.
+ */
+import { getContext } from '../context.js';
+/** Sentinel for a 'G'/'S' payload that could not be parsed (vs a valid
+ *  `null`/absent payload, which the handlers already tolerate). */
+const MALFORMED_PAYLOAD = Symbol('malformed-group-change-payload');
+/**
+ * Parse a group-change delta payload without ever throwing. The server
+ * serializes these as JSON strings; a corrupt frame used to escape the
+ * whole delta pipeline as an unhandled rejection AFTER the watermark had
+ * advanced — the delta is never re-delivered, so the security clear it
+ * carried was permanently lost.
+ */
+function parseGroupChangePayload(delta) {
+    if (typeof delta.data !== 'string')
+        return delta.data;
+    try {
+        return JSON.parse(delta.data);
+    }
+    catch (error) {
+        getContext().logger.debug('[BaseSyncedStore] Malformed group-change payload', {
+            syncId: delta.id,
+            actionType: delta.actionType,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return MALFORMED_PAYLOAD;
+    }
+}
+/**
+ * The legacy-clear fallback for an unparseable group-change delta: we know
+ * access changed but not how, so treat it as a revocation — clear cached
+ * data (IDB + pool) and force a full re-bootstrap with server truth.
+ */
+async function clearForUnknownGroupChange(ctx, delta, kind) {
+    getContext().logger.debug(`[BaseSyncedStore] Unreadable ${kind} payload — clearing cached data and re-bootstrapping`, { syncId: delta.id });
+    // SECURITY: same rationale as the legacy removedGroups path — revoked data
+    // must not persist if the device goes offline before the re-bootstrap.
+    await ctx.database.clear();
+    ctx.objectPool.clear();
+    ctx.forceFullRebootstrap();
+}
+/**
+ * Handle an actionType 'G' delta.
+ *
+ * The server emits 'G' via two distinct pathways, distinguished by payload
+ * shape:
+ *
+ *   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.
+ */
+export async function handleSyncGroupChange(ctx, delta) {
+    const raw = parseGroupChangePayload(delta);
+    if (raw === MALFORMED_PAYLOAD) {
+        // Malformed payload — we can't know WHICH groups changed, and this
+        // delta will never be re-delivered (the watermark already advanced).
+        // Degrade to the legacy security path: assume a removal, clear cached
+        // data, and rebuild from server truth. Never throw out of the pipeline.
+        await clearForUnknownGroupChange(ctx, delta, 'sync-group change');
+        return;
+    }
+    const rawObj = (raw ?? {});
+    // Detect incremental payload shape: { group, userId }
+    if (typeof rawObj.group === 'string' && typeof rawObj.userId === 'string') {
+        const incremental = {
+            group: rawObj.group,
+            userId: rawObj.userId,
+        };
+        await ctx.handleGroupAdded(incremental, delta.id);
+        return;
+    }
+    // Legacy payload: { addedGroups, removedGroups }
+    const payload = {
+        removedGroups: rawObj.removedGroups ?? [],
+        addedGroups: rawObj.addedGroups ?? [],
+    };
+    getContext().logger.info('[BaseSyncedStore] Sync group change received (legacy)', {
+        removedGroups: payload.removedGroups,
+        addedGroups: payload.addedGroups,
+        syncId: delta.id,
+    });
+    // SECURITY: If groups were removed, clear cached data immediately.
+    // This prevents revoked data from persisting if the device goes offline
+    // before the full re-bootstrap completes.
+    if (payload.removedGroups.length > 0) {
+        await ctx.database.clear();
+        ctx.objectPool.clear();
+        getContext().logger.info('[BaseSyncedStore] Cleared cached data due to revoked sync groups', {
+            removedGroups: payload.removedGroups,
+        });
+    }
+    const updatedGroups = ctx.computeUpdatedSyncGroups(payload);
+    await ctx.database.updateWorkspaceMetadata({ subscribedSyncGroups: updatedGroups });
+    ctx.forceFullRebootstrap();
+}
+/**
+ * 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.
+ */
+export async function handleGroupAdded(ctx, payload, syncId) {
+    getContext().logger.info('[BaseSyncedStore] Group added (incremental)', {
+        group: payload.group,
+        syncId,
+    });
+    const current = new Set(ctx.getSubscribedSyncGroups());
+    current.add(payload.group);
+    await ctx.database.updateWorkspaceMetadata({ subscribedSyncGroups: Array.from(current) });
+    // Note: no forceFullRebootstrap() — covering deltas will bring the entities.
+}
+/**
+ * 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.
+ */
+export async function handleGroupRemoved(ctx, delta) {
+    const raw = parseGroupChangePayload(delta);
+    if (raw === MALFORMED_PAYLOAD) {
+        // Malformed 'S' payload — access WAS revoked but we can't tell which
+        // group. Degrade to the legacy clear (the safe direction for a
+        // security delta) instead of throwing out of the pipeline.
+        await clearForUnknownGroupChange(ctx, delta, 'group-removed');
+        return;
+    }
+    const rawObj = (raw ?? {});
+    const groupKey = typeof rawObj.group === 'string' ? rawObj.group : undefined;
+    if (!groupKey) {
+        getContext().logger.debug('[BaseSyncedStore] Group removed delta missing group key', {
+            syncId: delta.id,
+        });
+        return;
+    }
+    getContext().logger.info('[BaseSyncedStore] Group removed', {
+        group: groupKey,
+        syncId: delta.id,
+    });
+    // SECURITY: Clear cached data before re-bootstrap. This prevents
+    // revoked-group data from persisting if the device goes offline
+    // between receiving 'S' and completing the re-bootstrap.
+    await ctx.database.clear();
+    ctx.objectPool.clear();
+    // Update subscription metadata so the re-bootstrap fetches the
+    // correct set of groups.
+    const current = new Set(ctx.getSubscribedSyncGroups());
+    current.delete(groupKey);
+    await ctx.database.updateWorkspaceMetadata({ subscribedSyncGroups: Array.from(current) });
+    ctx.forceFullRebootstrap();
+}
+/** Compute new sync groups after applying additions and removals */
+export function computeUpdatedSyncGroups(ctx, payload) {
+    const current = new Set(ctx.getSubscribedSyncGroups());
+    for (const g of payload.removedGroups)
+        current.delete(g);
+    for (const g of payload.addedGroups)
+        current.add(g);
+    return Array.from(current);
+}
+/** 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
+ * subscribe to.
+ */
+export function forceFullRebootstrap(ctx) {
+    if (ctx.getBootstrapMode() === 'none') {
+        getContext().logger.info('[BaseSyncedStore] forceFullRebootstrap skipped (bootstrapMode=none)');
+        return;
+    }
+    ctx.database.markRequiresFullBootstrap();
+    ctx.disconnectWebSocket();
+    ctx.emitConnectionEvent('WS_DISCONNECTED');
+}
+/**
+ * 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.
+ */
+export function resolveSyncGroups(context) {
+    if (context.syncGroups && context.syncGroups.length > 0) {
+        return context.syncGroups;
+    }
+    return [];
+}
+/** Check if sync groups shrank since last session — force full bootstrap if so */
+export async function checkSyncGroupShrinkage(ctx) {
+    const currentSyncGroups = ctx.getCurrentSyncGroups();
+    if (!currentSyncGroups)
+        return;
+    try {
+        const metadata = await ctx.database.getWorkspaceMetadata();
+        const stored = metadata?.subscribedSyncGroups ?? [];
+        if (stored.length === 0)
+            return;
+        const currentGroups = new Set(currentSyncGroups);
+        const removedGroups = stored.filter((g) => !currentGroups.has(g));
+        if (removedGroups.length > 0) {
+            getContext().logger.info('[BaseSyncedStore] Sync groups shrank — forcing full bootstrap', {
+                removedGroups,
+                storedCount: stored.length,
+                currentCount: currentGroups.size,
+            });
+            // SECURITY: Clear cached data before re-bootstrap to prevent
+            // revoked-group data from persisting if device goes offline
+            await ctx.database.clear();
+            ctx.objectPool.clear();
+            ctx.database.markRequiresFullBootstrap();
+        }
+        await ctx.database.updateWorkspaceMetadata({
+            subscribedSyncGroups: Array.from(currentGroups),
+        });
+    }
+    catch (error) {
+        getContext().logger.debug('[BaseSyncedStore] Failed to check sync group shrinkage', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}

package/dist/sync/heartbeat.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Application-level heartbeat for the sync WebSocket.
+ *
+ * The browser WebSocket API hides RFC 6455 protocol-level ping/pong from
+ * JavaScript, so the server's `ws.ping()` keepalive can't be observed by
+ * client code — meaning the client cannot tell a healthy idle connection
+ * apart from a "zombie" socket where TCP silently broke (laptop sleep,
+ * NAT timeout, mobile handoff). We send an application-level
+ * `{ type: 'ping' }` every 30s and force-close the socket if no inbound
+ * traffic arrives within 10s. ANY inbound message counts as
+ * proof-of-life — the explicit `pong` is just a guarantee that something
+ * will arrive even on an idle stream.
+ */
+/**
+ * One cadence for both sides: the SDK's application-level ping runs at the
+ * same `PING_INTERVAL_MS` as the server's RFC 6455 keepalive (and the claim
+ * lease window is derived from it — see `wire/protocol.ts`).
+ */
+export declare const HEARTBEAT_INTERVAL_MS = 30000;
+export declare const HEARTBEAT_TIMEOUT_MS = 10000;
+/**
+ * The slice of the socket the heartbeat needs — kept minimal so this
+ * leaf never depends on the SyncWebSocket class itself.
+ */
+export interface HeartbeatTransport {
+    /** True only while the underlying socket is `OPEN`. */
+    isSocketOpen(): boolean;
+    /** Send the `{ type: 'ping' }` frame; throws when the socket is already dead. */
+    sendPing(): void;
+    /**
+     * Force-close the socket from the client side (private 4xxx code) so
+     * `onclose` fires and runs the owner's reconnect / handshake-failed
+     * dispatch.
+     */
+    forceClose(reason: string): void;
+}
+/**
+ * Every `HEARTBEAT_INTERVAL_MS` while `OPEN`, send `{ type: 'ping' }`
+ * and arm a `HEARTBEAT_TIMEOUT_MS` watchdog. Any inbound frame (the
+ * owner's `onmessage` calls {@link clearHeartbeatTimeout}) clears the
+ * watchdog. If the watchdog fires, we treat the connection as zombie
+ * and force-close it — `onclose` then triggers the existing reconnect
+ * path.
+ *
+ * Why both sides need this:
+ *  - The server sends RFC 6455 protocol pings via `ws.ping()` every
+ *    30s. Browsers auto-respond with a pong but DO NOT expose either
+ *    frame to JavaScript, so the client is blind to its own keepalive.
+ *  - On a half-open TCP (laptop wake, NAT timeout, mobile handoff)
+ *    the browser may keep `readyState === OPEN` for minutes before
+ *    the OS surfaces the broken connection. App-level traffic is
+ *    the only signal we can observe.
+ */
+export declare class HeartbeatController {
+    private readonly transport;
+    private heartbeatTimer;
+    private heartbeatTimeoutTimer;
+    constructor(transport: HeartbeatTransport);
+    start(): void;
+    stop(): void;
+    clearHeartbeatTimeout(): void;
+}