@statezero/core 0.2.1 → 0.2.3

package/dist/adaptors/vue/composables.js

@@ -9,6 +9,18 @@ export const querysets = new Map(); // Map of composableId -> queryset
 function updateSyncManager() {
     // Get unique querysets from all active composables
     const uniqueQuerysets = new Set(querysets.values());
+    // Unsubscribe from querysets no longer followed
+    for (const [key, info] of syncManager.activeSubscriptions) {
+        if (!uniqueQuerysets.has(info.queryset)) {
+            syncManager.unsubscribeFromNamespace(info.queryset);
+        }
+    }
+    // Subscribe to new querysets
+    for (const queryset of uniqueQuerysets) {
+        if (!syncManager.activeSubscriptions.has(queryset.semanticKey)) {
+            syncManager.subscribeToNamespace(queryset);
+        }
+    }
     syncManager.followedQuerysets = uniqueQuerysets;
 }
 export function useQueryset(querysetFactory) {

package/dist/core/eventReceivers.js

@@ -83,6 +83,21 @@ export class PusherEventReceiver {
                 clearTimeout(this.connectionTimeoutId);
                 this.connectionTimeoutId = null;
             }
+            // Notify connected event
+            this.eventHandlers.forEach((handler) => {
+                if (handler.onReconnected) {
+                    handler.onReconnected();
+                }
+            });
+        });
+        this.pusherClient.connection.bind("disconnected", () => {
+            console.log(`Pusher client disconnected for backend: ${this.configKey}.`);
+            // Notify disconnected event
+            this.eventHandlers.forEach((handler) => {
+                if (handler.onDisconnected) {
+                    handler.onDisconnected();
+                }
+            });
         });
         this.pusherClient.connection.bind("failed", () => {
             this._logConnectionError("Pusher connection explicitly failed.");

package/dist/flavours/django/makeApiCall.d.ts

@@ -5,8 +5,9 @@
  * @param {ModelStoreRegistry} modelStoreRegistry - The model store registry to use
  * @param {Object} included - The included entities object from the response
  * @param {Function} ModelClass - The base model class to get the configKey from
+ * @param {QuerySet} [queryset] - Optional queryset to track which PKs came from this fetch
  */
-export function processIncludedEntities(modelStoreRegistry: ModelStoreRegistry, included: Object, ModelClass: Function): void;
+export function processIncludedEntities(modelStoreRegistry: ModelStoreRegistry, included: Object, ModelClass: Function, queryset?: QuerySet): void;
 /**
  * Makes an API call to the backend with the given QuerySet.
  * Automatically handles FileObject replacement with file paths for write operations.
@@ -15,6 +16,8 @@ export function processIncludedEntities(modelStoreRegistry: ModelStoreRegistry,
  * @param {string} operationType - The type of operation to perform.
  * @param {Object} args - Additional arguments for the operation.
  * @param {string} operationId - A unique id for the operation
+ * @param {Function} beforeExit - Optional callback before returning
+ * @param {string} canonicalId - Optional canonical_id for cache sharing
  * @returns {Promise<Object>} The API response.
  */
-export function makeApiCall(querySet: QuerySet, operationType: string, args: Object | undefined, operationId: string, beforeExit?: null): Promise<Object>;
+export function makeApiCall(querySet: QuerySet, operationType: string, args: Object | undefined, operationId: string, beforeExit?: Function, canonicalId?: string): Promise<Object>;

package/dist/flavours/django/makeApiCall.js

@@ -4,6 +4,7 @@ import { configInstance } from '../../config.js';
 import { replaceTempPks } from './tempPk.js';
 import { parseStateZeroError, MultipleObjectsReturned, DoesNotExist } from './errors.js';
 import { FileObject } from './files.js';
+import { querysetStoreRegistry } from '../../syncEngine/registries/querysetStoreRegistry.js';
 const apiCallQueue = new PQueue({ concurrency: 1 });
 /**
  * Process included entities from a response and register them in the model store.
@@ -12,11 +13,17 @@ const apiCallQueue = new PQueue({ concurrency: 1 });
  * @param {ModelStoreRegistry} modelStoreRegistry - The model store registry to use
  * @param {Object} included - The included entities object from the response
  * @param {Function} ModelClass - The base model class to get the configKey from
+ * @param {QuerySet} [queryset] - Optional queryset to track which PKs came from this fetch
  */
-export function processIncludedEntities(modelStoreRegistry, included, ModelClass) {
+export function processIncludedEntities(modelStoreRegistry, included, ModelClass, queryset = null) {
     if (!included)
         return;
     const configKey = ModelClass.configKey;
+    // Get the queryset store if a queryset is provided
+    let querysetStore = null;
+    if (queryset) {
+        querysetStore = querysetStoreRegistry.getStore(queryset);
+    }
     try {
         // Process each model type
         for (const [modelName, entityMap] of Object.entries(included)) {
@@ -26,6 +33,17 @@ export function processIncludedEntities(modelStoreRegistry, included, ModelClass
                 console.error(`Model class not found for ${modelName} in config ${configKey}`);
                 throw new Error(`Model class not found for ${modelName}`);
             }
+            // Track which PKs are included if a queryset store is available
+            if (querysetStore) {
+                if (!querysetStore.includedPks.has(modelName)) {
+                    querysetStore.includedPks.set(modelName, new Set());
+                }
+                const pksSet = querysetStore.includedPks.get(modelName);
+                // Add all PKs from this model to the set
+                for (const pk of Object.keys(entityMap)) {
+                    pksSet.add(Number(pk));
+                }
+            }
             // Register each entity in the model store
             for (const [pk, entity] of Object.entries(entityMap)) {
                 modelStoreRegistry.setEntity(EntityClass, pk, entity);
@@ -45,9 +63,11 @@ export function processIncludedEntities(modelStoreRegistry, included, ModelClass
  * @param {string} operationType - The type of operation to perform.
  * @param {Object} args - Additional arguments for the operation.
  * @param {string} operationId - A unique id for the operation
+ * @param {Function} beforeExit - Optional callback before returning
+ * @param {string} canonicalId - Optional canonical_id for cache sharing
  * @returns {Promise<Object>} The API response.
  */
-export async function makeApiCall(querySet, operationType, args = {}, operationId, beforeExit = null) {
+export async function makeApiCall(querySet, operationType, args = {}, operationId, beforeExit = null, canonicalId = null) {
     const ModelClass = querySet.ModelClass;
     const config = configInstance.getConfig();
     const backend = config.backendConfigs[ModelClass.configKey];
@@ -90,6 +110,9 @@ export async function makeApiCall(querySet, operationType, args = {}, operationI
     if (operationId) {
         headers["X-Operation-ID"] = operationId;
     }
+    if (canonicalId) {
+        headers["X-Canonical-ID"] = canonicalId;
+    }
     // Use the queue for write operations, bypass for read operations
     const apiCall = async () => {
         try {

package/dist/flavours/django/queryExecutor.js

@@ -62,7 +62,7 @@ export class QueryExecutor {
             if (isNil(data) || (Array.isArray(data) && data.length === 0)) {
                 return null;
             }
-            processIncludedEntities(modelStoreRegistry, included, ModelClass);
+            processIncludedEntities(modelStoreRegistry, included, ModelClass, querySet);
             const realPk = Array.isArray(data) ? data[0] : data;
             // swap in the real PK on the same instance, will trigger reactivity
             live.pk = realPk;
@@ -90,7 +90,7 @@ export class QueryExecutor {
         const live = querysetStoreRegistry.getEntity(qs);
         const promise = makeApiCall(qs, op, args).then((resp) => {
             const { data, included } = resp.data;
-            processIncludedEntities(modelStoreRegistry, included, qs.ModelClass);
+            processIncludedEntities(modelStoreRegistry, included, qs.ModelClass, qs);
             const pks = Array.isArray(data) ? data : [];
             querysetStoreRegistry.setEntity(qs, pks);
             return querysetStoreRegistry.getEntity(qs);
@@ -129,7 +129,7 @@ export class QueryExecutor {
             const { data, included, model_name } = response.data;
             const created = response.metadata.created;
             // Process included entities
-            processIncludedEntities(modelStoreRegistry, included, ModelClass);
+            processIncludedEntities(modelStoreRegistry, included, ModelClass, querySet);
             // Get the real PK
             const pk = Array.isArray(data) ? data[0] : data;
             // Update PK if we created a new instance
@@ -307,7 +307,7 @@ export class QueryExecutor {
             .then((response) => {
             const { data, included, model_name } = response.data;
             // Process included entities
-            processIncludedEntities(modelStoreRegistry, included, ModelClass);
+            processIncludedEntities(modelStoreRegistry, included, ModelClass, querySet);
             // Get the real PK
             const pk = Array.isArray(data) ? data[0] : data;
             live.pk = pk;
@@ -372,7 +372,7 @@ export class QueryExecutor {
             .then((response) => {
             const { data, included, model_name } = response.data;
             // Process included entities
-            processIncludedEntities(modelStoreRegistry, included, ModelClass);
+            processIncludedEntities(modelStoreRegistry, included, ModelClass, querySet);
             // Get the real PKs
             const pks = Array.isArray(data) ? data : [];
             // Update each live instance with its real PK
@@ -426,7 +426,7 @@ export class QueryExecutor {
             .then((response) => {
             const { data: raw, included, model_name } = response.data;
             // Process included entities
-            processIncludedEntities(modelStoreRegistry, included, ModelClass);
+            processIncludedEntities(modelStoreRegistry, included, ModelClass, querySet);
             // Swap in the real PK
             const pk = Array.isArray(raw) ? raw[0] : raw;
             live.pk = pk;

package/dist/flavours/django/querySet.js

@@ -3,7 +3,6 @@ import { Model } from "./model.js";
 import { ModelSerializer, relationshipFieldSerializer, dateFieldSerializer } from "./serializers.js";
 import axios from "axios";
 import { QueryExecutor } from "./queryExecutor.js";
-import { json } from "stream/consumers";
 import { v7 } from "uuid";
 import hash from "object-hash";
 import rfdc from "rfdc";

package/dist/syncEngine/namespaceUtils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generate a stable hash for a namespace dictionary.
+ * Must match the backend implementation in statezero/core/namespace_utils.py
+ *
+ * @param {Object} namespace - Namespace dictionary (e.g., {room_id: 5})
+ * @returns {string} MD5 hash of the namespace
+ */
+export function getNamespaceHash(namespace: Object): string;
+/**
+ * Extract namespace fields from a queryset filter.
+ * Namespace fields are those that use exact equality (not __gt, __lt, etc.)
+ *
+ * @param {Object} filters - Queryset filters
+ * @returns {Object} Namespace dictionary
+ */
+export function extractNamespaceFromFilter(filters: Object): Object;

package/dist/syncEngine/namespaceUtils.js

@@ -0,0 +1,32 @@
+import crypto from 'crypto-js';
+/**
+ * Generate a stable hash for a namespace dictionary.
+ * Must match the backend implementation in statezero/core/namespace_utils.py
+ *
+ * @param {Object} namespace - Namespace dictionary (e.g., {room_id: 5})
+ * @returns {string} MD5 hash of the namespace
+ */
+export function getNamespaceHash(namespace) {
+    // Sort keys to ensure stable hash
+    const namespaceJson = JSON.stringify(namespace, Object.keys(namespace).sort());
+    return crypto.MD5(namespaceJson).toString();
+}
+/**
+ * Extract namespace fields from a queryset filter.
+ * Namespace fields are those that use exact equality (not __gt, __lt, etc.)
+ *
+ * @param {Object} filters - Queryset filters
+ * @returns {Object} Namespace dictionary
+ */
+export function extractNamespaceFromFilter(filters) {
+    if (!filters)
+        return {};
+    const namespace = {};
+    for (const [key, value] of Object.entries(filters)) {
+        // Only include exact matches (not lookups like __gt, __in, etc.)
+        if (!key.includes('__')) {
+            namespace[key] = value;
+        }
+    }
+    return namespace;
+}

package/dist/syncEngine/registries/querysetStoreRegistry.js

@@ -174,14 +174,17 @@ export class QuerysetStoreRegistry {
             current = current.__parent;
         }
         // Create a new temporary store
-        const fetchQueryset = async ({ ast, modelClass }) => {
+        const fetchQueryset = async ({ ast, modelClass, canonical_id }) => {
             // Directly assemble the request and call the API to avoid recursive logic from the
             // queryset back to the registry / store
             const payload = {
                 ...ast,
                 type: 'list'
             };
-            const response = await makeApiCall(queryset, 'list', payload);
+            const response = await makeApiCall(queryset, 'list', payload, null, // operationId
+            null, // beforeExit
+            canonical_id // canonical_id for caching
+            );
             return response.data;
         };
         let initialGroundTruthPks = null;

package/dist/syncEngine/stores/modelStore.d.ts

@@ -37,6 +37,13 @@ export class ModelStore {
     getTrimmedOperations(): any[];
     getInflightOperations(): any[];
     prune(): void;
+    /**
+     * Prune model instances that aren't referenced by any queryset store.
+     * This prevents unbounded cache growth from included nested models.
+     *
+     * @param {QuerysetStoreRegistry} querysetStoreRegistry - The registry to check for queryset references
+     */
+    pruneUnreferencedInstances(querysetStoreRegistry: QuerysetStoreRegistry): void;
     render(pks?: null, optimistic?: boolean): any[];
     sync(pks?: null): Promise<void>;
 }

package/dist/syncEngine/stores/modelStore.js

@@ -396,6 +396,43 @@ export class ModelStore {
         this.setOperations(this.getInflightOperations());
         this.setCache(renderedPks);
     }
+    /**
+     * Prune model instances that aren't referenced by any queryset store.
+     * This prevents unbounded cache growth from included nested models.
+     *
+     * @param {QuerysetStoreRegistry} querysetStoreRegistry - The registry to check for queryset references
+     */
+    pruneUnreferencedInstances(querysetStoreRegistry) {
+        const pkField = this.pkField;
+        const modelName = this.modelClass.modelName;
+        // Collect all PKs that are needed by ANY queryset (permanent or temporary)
+        const neededPks = new Set();
+        for (const [semanticKey, store] of querysetStoreRegistry._stores.entries()) {
+            // Check top-level PKs (groundTruthPks)
+            if (store.modelClass.modelName === modelName) {
+                store.groundTruthPks.forEach(pk => neededPks.add(pk));
+            }
+            // Check included PKs (nested models)
+            if (store.includedPks.has(modelName)) {
+                const includedPkSet = store.includedPks.get(modelName);
+                includedPkSet.forEach(pk => neededPks.add(pk));
+            }
+        }
+        // Filter ground truth to only keep needed PKs
+        const filteredGroundTruth = this.groundTruthArray.filter(instance => {
+            if (!instance || typeof instance !== 'object' || !(pkField in instance)) {
+                return false;
+            }
+            return neededPks.has(instance[pkField]);
+        });
+        const removedCount = this.groundTruthArray.length - filteredGroundTruth.length;
+        if (removedCount > 0) {
+            console.log(`[ModelStore ${modelName}] Pruned ${removedCount} unreferenced instances (${filteredGroundTruth.length} remaining)`);
+            this.groundTruthArray = filteredGroundTruth;
+            // Update the cache to reflect the pruned data
+            this.setCache(filteredGroundTruth);
+        }
+    }
     // Render methods
     render(pks = null, optimistic = true) {
         const pksSet = pks === null

package/dist/syncEngine/stores/querysetStore.d.ts

@@ -10,6 +10,7 @@ export class QuerysetStore {
     isTemp: any;
     pruneThreshold: any;
     getRootStore: any;
+    includedPks: Map<any, any>;
     qsCache: Cache;
     _lastRenderedPks: any[] | null;
     renderCallbacks: Set<any>;
@@ -45,6 +46,6 @@ export class QuerysetStore {
     renderFromRoot(optimistic: boolean | undefined, rootStore: any): any[];
     renderFromData(optimistic?: boolean): any[];
     applyOperation(operation: any, currentPks: any): any;
-    sync(forceFromDb?: boolean): Promise<void>;
+    sync(options?: {}): Promise<void>;
 }
 import { Cache } from '../cache/cache.js';

package/dist/syncEngine/stores/querysetStore.js

@@ -20,6 +20,9 @@ export class QuerysetStore {
         this.getRootStore = options.getRootStore || null;
         this.groundTruthPks = initialGroundTruthPks || [];
         this.operationsMap = new Map();
+        // Track which model PKs are in this queryset's included data
+        // Map<modelName, Set<pk>>
+        this.includedPks = new Map();
         if (Array.isArray(initialOperations)) {
             for (const opData of initialOperations) {
                 const existing = operationRegistry.get(opData.operationId);
@@ -266,7 +269,8 @@ export class QuerysetStore {
         }
         return currentPks;
     }
-    async sync(forceFromDb = false) {
+    async sync(options = {}) {
+        const { canonical_id, forceFromDb = false } = typeof options === 'boolean' ? { forceFromDb: options } : options;
         const id = this.modelClass.modelName;
         if (this.isSyncing) {
             console.warn(`[QuerysetStore ${id}] Already syncing, request ignored.`);
@@ -289,17 +293,26 @@ export class QuerysetStore {
         this.isSyncing = true;
         console.log(`[${id}] Starting sync...`);
         try {
-            const response = await this.fetchFn({
+            // Build request with canonical_id
+            const requestBody = {
                 ast: this.queryset.build(),
                 modelClass: this.modelClass,
-            });
+            };
+            // Include canonical_id if provided (for cache sharing)
+            if (canonical_id) {
+                requestBody.canonical_id = canonical_id;
+            }
+            const response = await this.fetchFn(requestBody);
             const { data, included } = response;
             if (isNil(data)) {
                 return;
             }
             console.log(`[${id}] Sync fetch completed. Received: ${JSON.stringify(data)}.`);
+            // Clear previous included PKs tracking before processing new data
+            this.includedPks.clear();
             // Persists all the instances (including nested instances) to the model store
-            processIncludedEntities(modelStoreRegistry, included, this.modelClass);
+            // Pass this queryset to track which PKs are in the included data
+            processIncludedEntities(modelStoreRegistry, included, this.modelClass, this.queryset);
             this.setGroundTruth(data);
             this.setOperations(this.getInflightOperations());
             this.lastSync = Date.now();

package/dist/syncEngine/sync.d.ts

@@ -5,6 +5,7 @@ export class EventPayload {
     operation_id: any;
     pk_field_name: any;
     configKey: any;
+    canonical_id: any;
     instances: any;
     _cachedInstances: any;
     get modelClass(): Function | null;
@@ -23,15 +24,22 @@ export class SyncManager {
     maxWaitMs: number;
     batchStartTime: number | null;
     syncQueue: PQueue<import("p-queue/dist/priority-queue").default, import("p-queue").QueueAddOptions>;
+    activeSubscriptions: Map<any, any>;
+    currentCanonicalId: any;
     withTimeout(promise: any, ms: any): Promise<any>;
     /**
      * Initialize event handlers for all event receivers
      */
     initialize(): void;
+    handleDisconnect(): void;
+    handleReconnect(): void;
     startPeriodicSync(): void;
     syncStaleQuerysets(): void;
+    pruneUnreferencedModels(): void;
     isStoreFollowed(registry: any, semanticKey: any): boolean;
     cleanup(): void;
+    subscribeToNamespace(queryset: any): Promise<void>;
+    unsubscribeFromNamespace(queryset: any): Promise<void>;
     followModel(registry: any, modelClass: any): void;
     unfollowModel(registry: any, modelClass: any): void;
     manageRegistry(registry: any): void;

package/dist/syncEngine/sync.js

@@ -16,6 +16,7 @@ export class EventPayload {
         this.operation_id = data.operation_id;
         this.pk_field_name = data.pk_field_name;
         this.configKey = data.configKey;
+        this.canonical_id = data.canonical_id;
         // Parse PK fields to numbers in instances
         this.instances = data.instances?.map(instance => {
             if (instance && this.pk_field_name && instance[this.pk_field_name] != null) {
@@ -50,6 +51,10 @@ export class SyncManager {
         this.handleEvent = (event) => {
             let payload = new EventPayload(event);
             let isLocalOperation = operationRegistry.has(payload.operation_id);
+            // Store canonical_id for upcoming refetches
+            if (event.canonical_id) {
+                this.currentCanonicalId = event.canonical_id;
+            }
             // Always process metrics immediately (they're lightweight)
             if (this.registries.has(MetricRegistry)) {
                 this.processMetrics(payload);
@@ -97,6 +102,9 @@ export class SyncManager {
         this.batchStartTime = null;
         // SyncQueue
         this.syncQueue = new PQueue({ concurrency: 1 });
+        // Namespace subscription tracking
+        this.activeSubscriptions = new Map(); // semanticKey -> {queryset, subscribedAt}
+        this.currentCanonicalId = null; // Store canonical_id from events
     }
     withTimeout(promise, ms) {
         // If no timeout specified, use 2x the periodic sync interval, or 30s as fallback
@@ -123,15 +131,31 @@ export class SyncManager {
         initializeAllEventReceivers();
         // Get all registered event receivers
         const eventReceivers = getAllEventReceivers();
+        // Create event handler with connection lifecycle methods
+        const eventHandlerWithLifecycle = this.handleEvent.bind(this);
+        eventHandlerWithLifecycle.onReconnected = this.handleReconnect.bind(this);
+        eventHandlerWithLifecycle.onDisconnected = this.handleDisconnect.bind(this);
         // Register the event handlers with each receiver
         eventReceivers.forEach((receiver, configKey) => {
             if (receiver) {
                 // Model events go to handleEvent
-                receiver.addModelEventHandler(this.handleEvent.bind(this));
+                receiver.addModelEventHandler(eventHandlerWithLifecycle);
             }
         });
         this.startPeriodicSync();
     }
+    handleDisconnect() {
+        // Clear local subscription state on disconnect
+        this.activeSubscriptions.clear();
+        console.log('[SyncManager] Cleared subscriptions on disconnect');
+    }
+    handleReconnect() {
+        // Resubscribe to all active querysets after reconnect
+        console.log('[SyncManager] Resubscribing to active querysets after reconnect');
+        for (const queryset of this.followedQuerysets) {
+            this.subscribeToNamespace(queryset);
+        }
+    }
     startPeriodicSync() {
         if (this.periodicSyncTimer)
             return;
@@ -171,6 +195,18 @@ export class SyncManager {
         if (syncedCount > 0) {
             console.log(`[SyncManager] Periodic sync: ${syncedCount} stores pushed to the sync queue`);
         }
+        // Prune unreferenced model instances
+        this.pruneUnreferencedModels();
+    }
+    pruneUnreferencedModels() {
+        const modelRegistry = this.registries.get(ModelStoreRegistry);
+        const querysetRegistry = this.registries.get(QuerysetStoreRegistry);
+        if (!modelRegistry || !querysetRegistry)
+            return;
+        // Prune each model store
+        for (const [modelClass, store] of modelRegistry._stores.entries()) {
+            store.pruneUnreferencedInstances(querysetRegistry);
+        }
     }
     isStoreFollowed(registry, semanticKey) {
         const followingQuerysets = registry.followingQuerysets.get(semanticKey);
@@ -195,6 +231,97 @@ export class SyncManager {
             this.maxWaitTimer = null;
         }
     }
+    async subscribeToNamespace(queryset) {
+        const key = queryset.semanticKey;
+        // Skip if already subscribed
+        if (this.activeSubscriptions.has(key))
+            return;
+        try {
+            const config = getConfig();
+            const backendConfig = config.backendConfigs[queryset.modelClass.configKey];
+            if (!backendConfig) {
+                console.error(`[SyncManager] Backend config not found for: ${queryset.modelClass.configKey}`);
+                return;
+            }
+            const apiUrl = backendConfig.API_URL;
+            // Get Pusher socket ID
+            const eventReceiver = getEventReceiver(queryset.modelClass.configKey);
+            const socketId = eventReceiver?.pusherClient?.connection?.socket_id;
+            if (!socketId) {
+                console.warn('[SyncManager] No socket_id available for subscription');
+                return;
+            }
+            // Send subscription request to backend
+            const response = await fetch(`${apiUrl}/namespaces/subscribe/`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    socket_id: socketId,
+                    model_name: queryset.modelClass.modelName,
+                    filter: queryset._filters // Backend extracts namespace from this
+                })
+            });
+            const result = await response.json();
+            if (!result.success) {
+                throw new Error('Subscription failed');
+            }
+            // Subscribe to the namespace-specific Pusher channel
+            const namespaceChannel = result.channel; // e.g., "django_app.Message:abc123hash"
+            eventReceiver?.subscribe(namespaceChannel);
+            this.activeSubscriptions.set(key, {
+                queryset,
+                subscribedAt: Date.now(),
+                channel: namespaceChannel,
+                namespace_hash: result.namespace_hash
+            });
+            console.log(`[SyncManager] Subscribed to namespace channel: ${namespaceChannel}`);
+        }
+        catch (error) {
+            console.error('[SyncManager] Namespace subscription failed:', error);
+        }
+    }
+    async unsubscribeFromNamespace(queryset) {
+        const key = queryset.semanticKey;
+        if (!this.activeSubscriptions.has(key))
+            return;
+        const subscription = this.activeSubscriptions.get(key);
+        try {
+            const config = getConfig();
+            const backendConfig = config.backendConfigs[queryset.modelClass.configKey];
+            if (!backendConfig) {
+                console.error(`[SyncManager] Backend config not found for: ${queryset.modelClass.configKey}`);
+                return;
+            }
+            const apiUrl = backendConfig.API_URL;
+            const eventReceiver = getEventReceiver(queryset.modelClass.configKey);
+            const socketId = eventReceiver?.pusherClient?.connection?.socket_id;
+            if (!socketId)
+                return;
+            // Unsubscribe from the Pusher channel
+            if (subscription.channel) {
+                eventReceiver?.unsubscribe(subscription.channel);
+            }
+            // Notify backend to remove subscription
+            await fetch(`${apiUrl}/namespaces/unsubscribe/`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    socket_id: socketId,
+                    model_name: queryset.modelClass.modelName,
+                    filter: queryset._filters
+                })
+            });
+            this.activeSubscriptions.delete(key);
+            console.log(`[SyncManager] Unsubscribed from namespace channel: ${subscription.channel}`);
+        }
+        catch (error) {
+            console.error('[SyncManager] Namespace unsubscription failed:', error);
+        }
+    }
     followModel(registry, modelClass) {
         const models = this.followedModels.get(registry) || new Set();
         this.followedModels.set(registry, models);
@@ -296,7 +423,9 @@ export class SyncManager {
         // Sync all relevant stores for this model
         console.log(`[SyncManager] Syncing ${storesToSync.length} queryset stores for ${representativeEvent.model}`);
         storesToSync.forEach((store) => {
-            this.syncQueue.add(() => this.withTimeout(store.sync()));
+            this.syncQueue.add(() => this.withTimeout(store.sync({
+                canonical_id: representativeEvent.canonical_id // Pass canonical_id
+            })));
         });
     }
     processMetrics(event) {
@@ -319,7 +448,48 @@ export class SyncManager {
         }
     }
     processModels(event) {
-        return;
+        const registry = this.registries.get(ModelStoreRegistry);
+        if (!registry)
+            return;
+        const modelStore = registry.getStore(event.modelClass);
+        if (!modelStore)
+            return;
+        // Get PKs from the event
+        const eventPks = new Set((event.instances || [])
+            .filter(inst => inst && inst[event.pk_field_name] != null)
+            .map(inst => inst[event.pk_field_name]));
+        if (eventPks.size === 0)
+            return;
+        // Get PKs that are already in the model store's ground truth
+        const groundTruthPks = new Set(modelStore.groundTruthPks);
+        // Get PKs that are top-level in ANY queryset for this model (not just followed ones)
+        const querysetRegistry = this.registries.get(QuerysetStoreRegistry);
+        const topLevelQuerysetPks = new Set();
+        if (querysetRegistry) {
+            for (const [semanticKey, store] of querysetRegistry._stores.entries()) {
+                // Check ALL querysets for this model (permanent and temporary)
+                if (store.modelClass.modelName === event.model &&
+                    store.modelClass.configKey === event.configKey) {
+                    // Get this queryset's ground truth PKs (top-level instances)
+                    // Don't use render() as it applies operations - we just want ground truth
+                    store.groundTruthPks.forEach(pk => topLevelQuerysetPks.add(pk));
+                }
+            }
+        }
+        // Find PKs that are:
+        // 1. In the event
+        // 2. Already in ground truth (we're tracking them)
+        // 3. NOT top-level in any queryset (they're only nested/included)
+        const pksToSync = [];
+        eventPks.forEach(pk => {
+            if (groundTruthPks.has(pk) && !topLevelQuerysetPks.has(pk)) {
+                pksToSync.push(pk);
+            }
+        });
+        if (pksToSync.length > 0) {
+            console.log(`[SyncManager] Syncing ${pksToSync.length} nested-only PKs for ${event.model}: ${pksToSync}`);
+            this.syncQueue.add(() => this.withTimeout(modelStore.sync(pksToSync)));
+        }
     }
 }
 const syncManager = new SyncManager();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statezero/core",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "module": "ESNext",
   "description": "The type-safe frontend client for StateZero - connect directly to your backend models with zero boilerplate",
@@ -32,6 +32,7 @@
     "test:e2e": "vitest run --config=vitest.sequential.config.ts tests/e2e",
     "generate:test-apps": "ts-node scripts/generate-test-apps.js",
     "test:adaptors": "playwright test tests/adaptors",
+    "test:integration": "playwright test --config=playwright.integration.config.ts",
     "test:coverage": "vitest run --coverage",
     "build": "tsc",
     "parse-queries": "node scripts/perfect-query-parser.js",