@statezero/core 0.2.45 → 0.2.47

package/dist/syncEngine/stores/operationEventHandlers.js

@@ -7,6 +7,7 @@ import { QuerySet } from '../../flavours/django/querySet.js';
 import { isEqual, isNil } from 'lodash-es';
 import hash from 'object-hash';
 import { filter, applyOrderBy } from '../../filtering/localFiltering.js';
+import { recordDebugEvent } from '../../debug/statezeroDebug.js';
 /**
  * Check if two model classes represent the same model.
  * Uses property comparison instead of reference equality to handle
@@ -38,11 +39,31 @@ function routeCreateOperation(operation, applyAction) {
     Array.from(querysetStoreRegistry._stores.entries()).forEach(([semanticKey, store]) => {
         if (!isSameModel(store.modelClass, modelClass))
             return;
+        recordDebugEvent({
+            type: "routing",
+            operationId: operation.operationId,
+            operationType: operation.type,
+            semanticKey,
+            modelName: store.modelClass?.modelName,
+            configKey: store.modelClass?.configKey,
+            phase: "start",
+        });
         const serializerOptions = store.queryset?._serializerOptions || {};
         const { offset, limit } = serializerOptions;
         // Offset > 0: can't determine position based on slicing
         if (offset != null && offset > 0) {
             operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, true));
+            recordDebugEvent({
+                type: "routing",
+                operationId: operation.operationId,
+                operationType: operation.type,
+                semanticKey,
+                modelName: store.modelClass?.modelName,
+                configKey: store.modelClass?.configKey,
+                decision: "offset>0",
+                optimistic: false,
+                verify: true,
+            });
             return;
         }
         // Evaluate if instances match this queryset's filter
@@ -53,6 +74,17 @@ function routeCreateOperation(operation, applyAction) {
         if (matchingInstances.length === 0) {
             // Local filter says no match - trust it (local filtering is robust)
             operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, false));
+            recordDebugEvent({
+                type: "routing",
+                operationId: operation.operationId,
+                operationType: operation.type,
+                semanticKey,
+                modelName: store.modelClass?.modelName,
+                configKey: store.modelClass?.configKey,
+                decision: "filter:no-match",
+                optimistic: false,
+                verify: false,
+            });
             return;
         }
         // Item matches filter - check limit
@@ -75,6 +107,17 @@ function routeCreateOperation(operation, applyAction) {
                     // If some ground truth items couldn't be rendered, we can't trust local sort
                     if (currentItems.length < store.groundTruthPks.length) {
                         operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, true));
+                        recordDebugEvent({
+                            type: "routing",
+                            operationId: operation.operationId,
+                            operationType: operation.type,
+                            semanticKey,
+                            modelName: store.modelClass?.modelName,
+                            configKey: store.modelClass?.configKey,
+                            decision: "limit:ordering:incomplete-render",
+                            optimistic: false,
+                            verify: true,
+                        });
                         return;
                     }
                     const allItems = [...currentItems, ...matchingInstances];
@@ -88,14 +131,47 @@ function routeCreateOperation(operation, applyAction) {
                     if (anyInTopN) {
                         applyAction(store);
                         operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(true, false));
+                        recordDebugEvent({
+                            type: "routing",
+                            operationId: operation.operationId,
+                            operationType: operation.type,
+                            semanticKey,
+                            modelName: store.modelClass?.modelName,
+                            configKey: store.modelClass?.configKey,
+                            decision: "limit:ordering:in-top",
+                            optimistic: true,
+                            verify: false,
+                        });
                     }
                     else {
                         operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, false));
+                        recordDebugEvent({
+                            type: "routing",
+                            operationId: operation.operationId,
+                            operationType: operation.type,
+                            semanticKey,
+                            modelName: store.modelClass?.modelName,
+                            configKey: store.modelClass?.configKey,
+                            decision: "limit:ordering:out",
+                            optimistic: false,
+                            verify: false,
+                        });
                     }
                 }
                 else {
                     // No ordering - new items go at end, won't be in first N
                     operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, false));
+                    recordDebugEvent({
+                        type: "routing",
+                        operationId: operation.operationId,
+                        operationType: operation.type,
+                        semanticKey,
+                        modelName: store.modelClass?.modelName,
+                        configKey: store.modelClass?.configKey,
+                        decision: "limit:no-ordering",
+                        optimistic: false,
+                        verify: false,
+                    });
                 }
                 return;
             }
@@ -104,6 +180,17 @@ function routeCreateOperation(operation, applyAction) {
         // Matches filter, has room or no limit - DEFINITELY_YES
         applyAction(store);
         operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(true, false));
+        recordDebugEvent({
+            type: "routing",
+            operationId: operation.operationId,
+            operationType: operation.type,
+            semanticKey,
+            modelName: store.modelClass?.modelName,
+            configKey: store.modelClass?.configKey,
+            decision: "match:has-room",
+            optimistic: true,
+            verify: false,
+        });
     });
 }
 /**
@@ -351,7 +438,6 @@ export function initEventHandler() {
     operationEvents.on(Status.CONFIRMED, handleOperationConfirmed);
     operationEvents.on(Status.REJECTED, handleOperationRejected);
     operationEvents.on(Status.MUTATED, handleOperationMutated);
-    console.log('Operation event handler initialized');
 }
 /**
  * Clean up by removing all event listeners
@@ -362,5 +448,4 @@ export function cleanupEventHandler() {
     operationEvents.off(Status.CONFIRMED, handleOperationConfirmed);
     operationEvents.off(Status.REJECTED, handleOperationRejected);
     operationEvents.off(Status.MUTATED, handleOperationMutated);
-    console.log('Operation event handler cleaned up');
 }

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

@@ -55,6 +55,6 @@ export class QuerysetStore {
      * Sync this queryset with the database.
      * Fetches from DB and sets ground truth.
      */
-    sync(): Promise<void>;
+    sync(canonical_id?: null): Promise<void>;
 }
 import { Cache } from '../cache/cache.js';

package/dist/syncEngine/stores/querysetStore.js

@@ -6,6 +6,7 @@ import { modelStoreRegistry } from '../registries/modelStoreRegistry.js';
 import { processIncludedEntities } from '../../flavours/django/makeApiCall.js';
 import { Cache } from '../cache/cache.js';
 import { filter } from "../../filtering/localFiltering.js";
+import { recordDebugEvent } from "../../debug/statezeroDebug.js";
 export class QuerysetStore {
     constructor(modelClass, fetchFn, queryset, initialGroundTruthPks = null, initialOperations = null, options = {}) {
         this.modelClass = modelClass;
@@ -48,7 +49,6 @@ export class QuerysetStore {
         if (this.groundTruthPks.length === 0 && this.operationsMap.size === 0) {
             const cached = this.qsCache.get(this.cacheKey);
             if (!isNil(cached) && !isEmpty(cached)) {
-                console.log(`[QuerysetStore] Hydrated ${this.modelClass.modelName} queryset with ${cached.length} items from cache`);
                 this.setGroundTruth(cached);
             }
         }
@@ -186,6 +186,17 @@ export class QuerysetStore {
         if (fromCache) {
             const cachedResult = this.qsCache.get(this.cacheKey);
             if (Array.isArray(cachedResult)) {
+                recordDebugEvent({
+                    type: "render",
+                    source: "cache",
+                    semanticKey: this.queryset.semanticKey,
+                    modelName: this.modelClass.modelName,
+                    configKey: this.modelClass.configKey,
+                    optimistic,
+                    groundTruthCount: this.groundTruthPks.length,
+                    operationsCount: this.operationsMap.size,
+                    resultCount: cachedResult.length,
+                });
                 return cachedResult;
             }
         }
@@ -197,12 +208,29 @@ export class QuerysetStore {
             : this.renderFromData(optimistic);
         // Validate against model store and apply local filtering/sorting
         let result = this._getValidatedAndFilteredPks(pks);
+        const preLimitCount = result.length;
         // Apply pagination limit
         const limit = this.queryset.build().serializerOptions?.limit;
         if (limit) {
             result = result.slice(0, limit);
         }
         this.setCache(result);
+        recordDebugEvent({
+            type: "render",
+            source: this.groundTruthPks.length === 0 && this.lastSync === null
+                ? "modelStore"
+                : "groundTruth",
+            semanticKey: this.queryset.semanticKey,
+            modelName: this.modelClass.modelName,
+            configKey: this.modelClass.configKey,
+            optimistic,
+            groundTruthCount: this.groundTruthPks.length,
+            operationsCount: this.operationsMap.size,
+            rawCount: Array.isArray(pks) ? pks.length : 0,
+            filteredCount: preLimitCount,
+            resultCount: result.length,
+            limit,
+        });
         return result;
     }
     renderFromData(optimistic = true) {
@@ -258,22 +286,29 @@ export class QuerysetStore {
      * Sync this queryset with the database.
      * Fetches from DB and sets ground truth.
      */
-    async sync() {
+    async sync(canonical_id = null) {
         const id = this.modelClass.modelName;
         if (this.isSyncing) {
             console.warn(`[QuerysetStore ${id}] Already syncing, request ignored.`);
             return;
         }
         this.isSyncing = true;
-        console.log(`[${id}] Starting sync...`);
+        recordDebugEvent({
+            type: "sync",
+            phase: "start",
+            semanticKey: this.queryset.semanticKey,
+            modelName: this.modelClass.modelName,
+            configKey: this.modelClass.configKey,
+            canonicalId: canonical_id,
+        });
         try {
             const response = await this.fetchFn({
                 ast: this.queryset.build(),
                 modelClass: this.modelClass,
+                canonical_id,
             });
             const { data, included } = response;
             if (!isNil(data)) {
-                console.log(`[${id}] Sync fetch completed. Received: ${JSON.stringify(data)}.`);
                 // Clear previous included PKs tracking before processing new data
                 this.includedPks.clear();
                 // Persist all instances (including nested) to the model store
@@ -282,10 +317,28 @@ export class QuerysetStore {
             }
             this.setOperations(this.getInflightOperations());
             this.lastSync = Date.now();
-            console.log(`[${id}] Sync completed.`);
+            recordDebugEvent({
+                type: "sync",
+                phase: "success",
+                semanticKey: this.queryset.semanticKey,
+                modelName: this.modelClass.modelName,
+                configKey: this.modelClass.configKey,
+                canonicalId: canonical_id,
+                dataCount: Array.isArray(data) ? data.length : 0,
+                includedCount: included ? Object.keys(included).length : 0,
+            });
         }
         catch (e) {
             console.error(`[${id}] Failed to sync ground truth:`, e);
+            recordDebugEvent({
+                type: "sync",
+                phase: "error",
+                semanticKey: this.queryset.semanticKey,
+                modelName: this.modelClass.modelName,
+                configKey: this.modelClass.configKey,
+                canonicalId: canonical_id,
+                message: e?.message,
+            });
         }
         finally {
             this.isSyncing = false;

package/dist/syncEngine/sync.d.ts

@@ -5,6 +5,8 @@ export class EventPayload {
     operation_id: any;
     pk_field_name: any;
     configKey: any;
+    canonical_id: any;
+    server_ts_ms: any;
     instances: any;
     _cachedInstances: any;
     get modelClass(): Function | null;

package/dist/syncEngine/sync.js

@@ -2,6 +2,7 @@ import { getAllEventReceivers } from "../core/eventReceivers.js";
 import { operationRegistry } from "./stores/operation.js";
 import { initializeAllEventReceivers } from "../config.js";
 import { getEventReceiver } from "../core/eventReceivers.js";
+import { recordDebugEvent } from "../debug/statezeroDebug.js";
 import { querysetStoreRegistry, QuerysetStoreRegistry, } from "./registries/querysetStoreRegistry.js";
 import { modelStoreRegistry, ModelStoreRegistry, } from "./registries/modelStoreRegistry.js";
 import { metricRegistry, MetricRegistry } from "./registries/metricRegistry.js";
@@ -16,6 +17,8 @@ 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 || null;
+        this.server_ts_ms = data.server_ts_ms || null;
         // 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) {
@@ -48,6 +51,16 @@ export class EventPayload {
 export class SyncManager {
     constructor() {
         this.handleEvent = (event) => {
+            recordDebugEvent({
+                type: "event",
+                modelName: event.model,
+                configKey: event.configKey,
+                semanticKey: `${event.configKey || "default"}::${event.model}`,
+                eventType: event.type || event.event,
+                instanceCount: Array.isArray(event.instances) ? event.instances.length : 0,
+                operationId: event.operation_id,
+                socketId: event.socket_id,
+            });
             let payload = new EventPayload(event);
             let isLocalOperation = operationRegistry.has(payload.operation_id);
             // Always process metrics immediately (they're lightweight)
@@ -141,18 +154,15 @@ export class SyncManager {
             const intervalSeconds = config.periodicSyncIntervalSeconds;
             // If null or undefined, don't start periodic sync
             if (!intervalSeconds) {
-                console.log("[SyncManager] Periodic sync disabled (set to null)");
                 return;
             }
             const intervalMs = intervalSeconds * 1000;
             this.periodicSyncTimer = setInterval(() => {
                 this.syncStaleQuerysets();
             }, intervalMs);
-            console.log(`[SyncManager] Periodic sync started: ${intervalSeconds}s intervals`);
         }
         catch (error) {
             // If no config, don't start periodic sync by default
-            console.log("[SyncManager] No config found, periodic sync disabled by default");
         }
     }
     async syncStaleQuerysets() {
@@ -174,7 +184,6 @@ export class SyncManager {
             }
         }
         if (storesToSync.length > 0) {
-            console.log(`[SyncManager] Periodic sync: syncing ${storesToSync.length} stores`);
             // Run all groupSync calls in parallel - they coordinate via shared promise cache
             await Promise.all(storesToSync.map(store => querysetRegistry.groupSync(store.queryset, operationId, dbSyncedKeys)));
         }
@@ -266,7 +275,6 @@ export class SyncManager {
         }
         if (storesToSync.length === 0)
             return;
-        console.log(`[SyncManager] Syncing ${storesToSync.length} querysets needing verification for operation ${operationId}`);
         const syncOperationId = `maybe-sync-${uuidv7()}`;
         const dbSyncedKeys = new Set([...this.followedQuerysets]
             .map(qs => qs.semanticKey)
@@ -289,7 +297,6 @@ export class SyncManager {
         const waitTime = Date.now() - this.batchStartTime;
         this.eventBatch.clear();
         this.batchStartTime = null;
-        console.log(`[SyncManager] Processing batch of ${events.length} events (reason: ${reason}, waited: ${waitTime}ms)`);
         // Group events by model for efficient processing
         const eventsByModel = new Map();
         events.forEach((event) => {
@@ -345,8 +352,9 @@ export class SyncManager {
         }
         if (storesToSync.length === 0)
             return;
-        // Sync all relevant stores for this model
-        console.log(`[SyncManager] Syncing ${storesToSync.length} queryset stores for ${representativeEvent.model}`);
+        // Pick canonical_id from the latest event by server_ts_ms
+        const latestEvent = allEvents.reduce((latest, evt) => (evt.server_ts_ms || 0) > (latest.server_ts_ms || 0) ? evt : latest, allEvents[0]);
+        const canonical_id = latestEvent.canonical_id;
         // Generate operationId for this batch - querysets in same chain will coordinate
         const operationId = `remote-event-${uuidv7()}`;
         // Get dbSynced keys (followed querysets that have stores)
@@ -356,7 +364,7 @@ export class SyncManager {
             .map(qs => qs.semanticKey)
             .filter(key => registry._stores.has(key)));
         // Run all groupSync calls in parallel - they coordinate via shared promise cache
-        Promise.all(storesToSync.map(store => registry.groupSync(store.queryset, operationId, dbSyncedKeys)));
+        Promise.all(storesToSync.map(store => registry.groupSync(store.queryset, operationId, dbSyncedKeys, canonical_id)));
     }
     processMetrics(event) {
         const registry = this.registries.get(MetricRegistry);
@@ -371,7 +379,6 @@ export class SyncManager {
                 }
                 // Check if this queryset (or any parent) is being followed
                 if (this.isQuerysetFollowed(entry.queryset)) {
-                    console.log(`syncing metric store for key: ${key}`);
                     entry.store.sync();
                 }
             }
@@ -417,7 +424,6 @@ export class SyncManager {
             }
         });
         if (pksToSync.length > 0) {
-            console.log(`[SyncManager] Syncing ${pksToSync.length} nested-only PKs for ${event.model}: ${pksToSync}`);
             modelStore.sync(pksToSync);
         }
     }

package/dist/vue-entry.d.ts

@@ -4,6 +4,7 @@ import { MetricAdaptor } from './adaptors/vue/index.js';
 import { useQueryset } from './adaptors/vue/index.js';
 import { querysets } from './adaptors/vue/index.js';
 import { LayoutRenderer } from './adaptors/vue/index.js';
+import { StateZeroDebugPanel } from './adaptors/vue/index.js';
 import { AlertElement } from './adaptors/vue/index.js';
 import { LabelElement } from './adaptors/vue/index.js';
 import { DividerElement } from './adaptors/vue/index.js';
@@ -12,4 +13,4 @@ import { GroupElement } from './adaptors/vue/index.js';
 import { TabsElement } from './adaptors/vue/index.js';
 import { ErrorBlock } from './adaptors/vue/index.js';
 import { createDefaultComponents } from './adaptors/vue/index.js';
-export { ModelAdaptor, QuerySetAdaptor, MetricAdaptor, useQueryset, querysets, LayoutRenderer, AlertElement, LabelElement, DividerElement, DisplayElement, GroupElement, TabsElement, ErrorBlock, createDefaultComponents };
+export { ModelAdaptor, QuerySetAdaptor, MetricAdaptor, useQueryset, querysets, LayoutRenderer, StateZeroDebugPanel, AlertElement, LabelElement, DividerElement, DisplayElement, GroupElement, TabsElement, ErrorBlock, createDefaultComponents };

package/dist/vue-entry.js

@@ -1,7 +1,7 @@
 import { ModelAdaptor, QuerySetAdaptor, MetricAdaptor, useQueryset, querysets } from './adaptors/vue/index.js';
-import { LayoutRenderer, AlertElement, LabelElement, DividerElement, DisplayElement, GroupElement, TabsElement, ErrorBlock, createDefaultComponents } from './adaptors/vue/index.js';
+import { LayoutRenderer, StateZeroDebugPanel, AlertElement, LabelElement, DividerElement, DisplayElement, GroupElement, TabsElement, ErrorBlock, createDefaultComponents } from './adaptors/vue/index.js';
 export { 
 // Reactivity
 ModelAdaptor, QuerySetAdaptor, MetricAdaptor, useQueryset, querysets, 
 // Layout components
-LayoutRenderer, AlertElement, LabelElement, DividerElement, DisplayElement, GroupElement, TabsElement, ErrorBlock, createDefaultComponents };
+LayoutRenderer, StateZeroDebugPanel, AlertElement, LabelElement, DividerElement, DisplayElement, GroupElement, TabsElement, ErrorBlock, createDefaultComponents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statezero/core",
-  "version": "0.2.45",
+  "version": "0.2.47",
   "type": "module",
   "module": "ESNext",
   "description": "The type-safe frontend client for StateZero - connect directly to your backend models with zero boilerplate",