agentic-qe 1.8.3 → 1.9.0

package/dist/core/memory/SwarmMemoryManager.js

@@ -46,6 +46,9 @@ Object.defineProperty(exports, "AccessLevel", { enumerable: true, get: function
 Object.defineProperty(exports, "Permission", { enumerable: true, get: function () { return AccessControl_1.Permission; } });
 Object.defineProperty(exports, "AccessControlError", { enumerable: true, get: function () { return AccessControl_1.AccessControlError; } });
 const AgentDBManager_1 = require("./AgentDBManager");
+const PatternCache_1 = require("./PatternCache");
+const memory_1 = require("../../telemetry/instrumentation/memory");
+const types_1 = require("../../types");
 /**
  * SwarmMemoryManager - Manages persistent memory for agent swarm coordination
  *
@@ -84,6 +87,12 @@ class SwarmMemoryManager {
         this.accessControl = new AccessControl_1.AccessControl();
         this.aclCache = new Map();
         this.lastModifiedTimestamps = new Map();
+        // Initialize pattern cache with LRU eviction (100 entries, 60s TTL)
+        this.patternCache = new PatternCache_1.PatternCache({
+            maxSize: 100,
+            ttl: 60000,
+            enableStats: true
+        });
     }
     run(sql, params = []) {
         if (!this.db) {
@@ -192,8 +201,18 @@ class SwarmMemoryManager {
         metadata TEXT,
         ttl INTEGER NOT NULL DEFAULT ${this.TTL_POLICY.patterns},
         expires_at INTEGER,
-        created_at INTEGER NOT NULL
+        created_at INTEGER NOT NULL,
+        agent_id TEXT
       )
+    `);
+        // Create indexes for O(log n) pattern queries (Issue #57)
+        await this.run(`
+      CREATE INDEX IF NOT EXISTS idx_patterns_agent_confidence
+      ON patterns(agent_id, confidence DESC)
+    `);
+        await this.run(`
+      CREATE INDEX IF NOT EXISTS idx_patterns_agent
+      ON patterns(agent_id)
     `);
         // Table 6: Consensus State (TTL: 7 days)
         await this.run(`
@@ -384,6 +403,16 @@ class SwarmMemoryManager {
         await this.run(`CREATE INDEX IF NOT EXISTS idx_learning_metrics_agent ON learning_metrics(agent_id)`);
         this.initialized = true;
     }
+    /**
+     * Store a key-value pair in memory with OpenTelemetry instrumentation
+     *
+     * Automatically instruments the memory store operation with distributed tracing.
+     * Records namespace, key, value size, TTL, and operation performance metrics.
+     *
+     * @param key - Memory key
+     * @param value - Value to store (will be JSON serialized)
+     * @param options - Store options including partition, TTL, access control
+     */
     async store(key, value, options = {}) {
         // Auto-initialize if not initialized
         if (!this.initialized) {
@@ -395,44 +424,73 @@ class SwarmMemoryManager {
         const partition = options.partition || 'default';
         const owner = options.owner || 'system';
         const accessLevel = options.accessLevel || AccessControl_1.AccessLevel.PRIVATE;
-        const createdAt = Date.now();
-        const expiresAt = options.ttl ? createdAt + (options.ttl * 1000) : null;
-        const metadata = options.metadata ? JSON.stringify(options.metadata) : null;
-        // Check write permission if updating existing entry
-        const existing = await this.queryOne(`SELECT owner, access_level, team_id, swarm_id FROM memory_entries WHERE key = ? AND partition = ?`, [key, partition]);
-        if (existing && options.owner) {
-            // Verify write permission
-            const permCheck = this.accessControl.checkPermission({
-                agentId: options.owner,
-                resourceOwner: existing.owner,
-                accessLevel: existing.access_level,
-                permission: AccessControl_1.Permission.WRITE,
-                teamId: options.teamId,
-                resourceTeamId: existing.team_id,
-                swarmId: options.swarmId,
-                resourceSwarmId: existing.swarm_id
-            });
-            if (!permCheck.allowed) {
-                throw new AccessControl_1.AccessControlError(`Write denied: ${permCheck.reason}`);
+        const valueJson = JSON.stringify(value);
+        const valueSize = valueJson.length;
+        // Create instrumentation span
+        const { span, context: spanContext } = memory_1.memorySpanManager.startStoreSpan({
+            agentId: { id: owner, type: types_1.QEAgentType.FLEET_COMMANDER, created: new Date() },
+            namespace: partition,
+            key,
+            valueSize,
+            ttl: options.ttl,
+        });
+        const startTime = Date.now();
+        try {
+            const createdAt = Date.now();
+            const expiresAt = options.ttl ? createdAt + (options.ttl * 1000) : null;
+            const metadata = options.metadata ? JSON.stringify(options.metadata) : null;
+            // Check write permission if updating existing entry
+            const existing = await this.queryOne(`SELECT owner, access_level, team_id, swarm_id FROM memory_entries WHERE key = ? AND partition = ?`, [key, partition]);
+            if (existing && options.owner) {
+                // Verify write permission
+                const permCheck = this.accessControl.checkPermission({
+                    agentId: options.owner,
+                    resourceOwner: existing.owner,
+                    accessLevel: existing.access_level,
+                    permission: AccessControl_1.Permission.WRITE,
+                    teamId: options.teamId,
+                    resourceTeamId: existing.team_id,
+                    swarmId: options.swarmId,
+                    resourceSwarmId: existing.swarm_id
+                });
+                if (!permCheck.allowed) {
+                    throw new AccessControl_1.AccessControlError(`Write denied: ${permCheck.reason}`);
+                }
             }
+            await this.run(`INSERT OR REPLACE INTO memory_entries
+         (key, partition, value, metadata, created_at, expires_at, owner, access_level, team_id, swarm_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+                key,
+                partition,
+                valueJson,
+                metadata,
+                createdAt,
+                expiresAt,
+                owner,
+                accessLevel,
+                options.teamId || null,
+                options.swarmId || null
+            ]);
+            // Track modification for QUIC sync
+            const entryKey = `${partition}:${key}`;
+            this.lastModifiedTimestamps.set(entryKey, createdAt);
+            // Complete span successfully
+            const durationMs = Date.now() - startTime;
+            memory_1.memorySpanManager.completeStoreSpan(span, {
+                success: true,
+                durationMs,
+            });
+        }
+        catch (error) {
+            // Complete span with error
+            const durationMs = Date.now() - startTime;
+            memory_1.memorySpanManager.completeStoreSpan(span, {
+                success: false,
+                durationMs,
+                error: error,
+            });
+            throw error;
         }
-        await this.run(`INSERT OR REPLACE INTO memory_entries
-       (key, partition, value, metadata, created_at, expires_at, owner, access_level, team_id, swarm_id)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
-            key,
-            partition,
-            JSON.stringify(value),
-            metadata,
-            createdAt,
-            expiresAt,
-            owner,
-            accessLevel,
-            options.teamId || null,
-            options.swarmId || null
-        ]);
-        // Track modification for QUIC sync
-        const entryKey = `${partition}:${key}`;
-        this.lastModifiedTimestamps.set(entryKey, createdAt);
     }
     /**
      * Alias for store() method to maintain compatibility with MemoryStore interface
@@ -456,6 +514,16 @@ class SwarmMemoryManager {
         }
         return this.retrieve(key, options);
     }
+    /**
+     * Retrieve a value from memory with OpenTelemetry instrumentation
+     *
+     * Automatically instruments the memory retrieve operation with distributed tracing.
+     * Records namespace, key, whether the value was found, value size, and performance metrics.
+     *
+     * @param key - Memory key
+     * @param options - Retrieve options including partition, agentId for access control
+     * @returns Retrieved value or null if not found
+     */
     async retrieve(key, options = {}) {
         // Auto-initialize if not initialized
         if (!this.initialized) {
@@ -465,55 +533,35 @@ class SwarmMemoryManager {
             throw new Error('Memory manager not initialized. Call initialize() first.');
         }
         const partition = options.partition || 'default';
-        const now = Date.now();
-        let query = `SELECT value, owner, access_level, team_id, swarm_id
-                 FROM memory_entries WHERE key = ? AND partition = ?`;
-        const params = [key, partition];
-        if (!options.includeExpired) {
-            query += ` AND (expires_at IS NULL OR expires_at > ?)`;
-            params.push(now);
-        }
-        const row = await this.queryOne(query, params);
-        if (!row) {
-            return null;
-        }
-        // Check read permission if agentId provided
-        if (options.agentId) {
-            const permCheck = this.accessControl.checkPermission({
-                agentId: options.agentId,
-                resourceOwner: row.owner,
-                accessLevel: row.access_level,
-                permission: AccessControl_1.Permission.READ,
-                teamId: options.teamId,
-                resourceTeamId: row.team_id,
-                swarmId: options.swarmId,
-                resourceSwarmId: row.swarm_id,
-                isSystemAgent: options.isSystemAgent
-            });
-            if (!permCheck.allowed) {
-                throw new AccessControl_1.AccessControlError(`Read denied: ${permCheck.reason}`);
+        const agentId = options.agentId || 'system';
+        // Create instrumentation span
+        const { span, context: spanContext } = memory_1.memorySpanManager.startRetrieveSpan({
+            agentId: { id: agentId, type: types_1.QEAgentType.FLEET_COMMANDER, created: new Date() },
+            namespace: partition,
+            key,
+        });
+        const startTime = Date.now();
+        try {
+            const now = Date.now();
+            let query = `SELECT value, owner, access_level, team_id, swarm_id
+                   FROM memory_entries WHERE key = ? AND partition = ?`;
+            const params = [key, partition];
+            if (!options.includeExpired) {
+                query += ` AND (expires_at IS NULL OR expires_at > ?)`;
+                params.push(now);
             }
-        }
-        return JSON.parse(row.value);
-    }
-    async query(pattern, options = {}) {
-        if (!this.db) {
-            throw new Error('Memory manager not initialized');
-        }
-        const partition = options.partition || 'default';
-        const now = Date.now();
-        let query = `SELECT key, value, partition, created_at, expires_at, owner, access_level, team_id, swarm_id
-                 FROM memory_entries
-                 WHERE partition = ? AND key LIKE ?`;
-        const params = [partition, pattern];
-        if (!options.includeExpired) {
-            query += ` AND (expires_at IS NULL OR expires_at > ?)`;
-            params.push(now);
-        }
-        const rows = await this.queryAll(query, params);
-        // Filter by access control if agentId provided
-        const filteredRows = options.agentId
-            ? rows.filter((row) => {
+            const row = await this.queryOne(query, params);
+            if (!row) {
+                // Complete span - not found
+                const durationMs = Date.now() - startTime;
+                memory_1.memorySpanManager.completeRetrieveSpan(span, {
+                    found: false,
+                    durationMs,
+                });
+                return null;
+            }
+            // Check read permission if agentId provided
+            if (options.agentId) {
                 const permCheck = this.accessControl.checkPermission({
                     agentId: options.agentId,
                     resourceOwner: row.owner,
@@ -525,50 +573,178 @@ class SwarmMemoryManager {
                     resourceSwarmId: row.swarm_id,
                     isSystemAgent: options.isSystemAgent
                 });
-                return permCheck.allowed;
-            })
-            : rows;
-        return filteredRows.map((row) => ({
-            key: row.key,
-            value: JSON.parse(row.value),
-            partition: row.partition,
-            createdAt: row.created_at,
-            expiresAt: row.expires_at,
-            owner: row.owner,
-            accessLevel: row.access_level,
-            teamId: row.team_id,
-            swarmId: row.swarm_id
-        }));
+                if (!permCheck.allowed) {
+                    throw new AccessControl_1.AccessControlError(`Read denied: ${permCheck.reason}`);
+                }
+            }
+            const valueSize = row.value.length;
+            const parsedValue = JSON.parse(row.value);
+            // Complete span successfully
+            const durationMs = Date.now() - startTime;
+            memory_1.memorySpanManager.completeRetrieveSpan(span, {
+                found: true,
+                valueSize,
+                durationMs,
+            });
+            return parsedValue;
+        }
+        catch (error) {
+            // Complete span with error
+            const durationMs = Date.now() - startTime;
+            memory_1.memorySpanManager.completeRetrieveSpan(span, {
+                found: false,
+                durationMs,
+                error: error,
+            });
+            throw error;
+        }
     }
+    /**
+     * Query/search memory entries by pattern with OpenTelemetry instrumentation
+     *
+     * Automatically instruments the memory search operation with distributed tracing.
+     * Records namespace, search pattern, result count, and performance metrics.
+     *
+     * @param pattern - SQL LIKE pattern for key matching
+     * @param options - Retrieve options including partition, agentId for access control
+     * @returns Array of matching memory entries
+     */
+    async query(pattern, options = {}) {
+        if (!this.db) {
+            throw new Error('Memory manager not initialized');
+        }
+        const partition = options.partition || 'default';
+        const agentId = options.agentId || 'system';
+        // Create instrumentation span
+        const { span, context: spanContext } = memory_1.memorySpanManager.startSearchSpan({
+            agentId: { id: agentId, type: types_1.QEAgentType.FLEET_COMMANDER, created: new Date() },
+            namespace: partition,
+            pattern,
+        });
+        const startTime = Date.now();
+        try {
+            const now = Date.now();
+            let query = `SELECT key, value, partition, created_at, expires_at, owner, access_level, team_id, swarm_id
+                   FROM memory_entries
+                   WHERE partition = ? AND key LIKE ?`;
+            const params = [partition, pattern];
+            if (!options.includeExpired) {
+                query += ` AND (expires_at IS NULL OR expires_at > ?)`;
+                params.push(now);
+            }
+            const rows = await this.queryAll(query, params);
+            // Filter by access control if agentId provided
+            const filteredRows = options.agentId
+                ? rows.filter((row) => {
+                    const permCheck = this.accessControl.checkPermission({
+                        agentId: options.agentId,
+                        resourceOwner: row.owner,
+                        accessLevel: row.access_level,
+                        permission: AccessControl_1.Permission.READ,
+                        teamId: options.teamId,
+                        resourceTeamId: row.team_id,
+                        swarmId: options.swarmId,
+                        resourceSwarmId: row.swarm_id,
+                        isSystemAgent: options.isSystemAgent
+                    });
+                    return permCheck.allowed;
+                })
+                : rows;
+            const results = filteredRows.map((row) => ({
+                key: row.key,
+                value: JSON.parse(row.value),
+                partition: row.partition,
+                createdAt: row.created_at,
+                expiresAt: row.expires_at,
+                owner: row.owner,
+                accessLevel: row.access_level,
+                teamId: row.team_id,
+                swarmId: row.swarm_id
+            }));
+            // Complete span successfully
+            const durationMs = Date.now() - startTime;
+            memory_1.memorySpanManager.completeSearchSpan(span, {
+                resultCount: results.length,
+                durationMs,
+            });
+            return results;
+        }
+        catch (error) {
+            // Complete span with error
+            const durationMs = Date.now() - startTime;
+            memory_1.memorySpanManager.completeSearchSpan(span, {
+                resultCount: 0,
+                durationMs,
+                error: error,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Delete a key from memory with OpenTelemetry instrumentation
+     *
+     * Automatically instruments the memory delete operation with distributed tracing.
+     * Records namespace, key, and operation performance metrics.
+     *
+     * @param key - Memory key to delete
+     * @param partition - Memory partition (namespace)
+     * @param options - Delete options including agentId for access control
+     */
     async delete(key, partition = 'default', options = {}) {
         if (!this.db) {
             throw new Error('Memory manager not initialized');
         }
-        // Check delete permission if agentId provided
-        if (options.agentId) {
-            const row = await this.queryOne(`SELECT owner, access_level, team_id, swarm_id FROM memory_entries WHERE key = ? AND partition = ?`, [key, partition]);
-            if (row) {
-                const permCheck = this.accessControl.checkPermission({
-                    agentId: options.agentId,
-                    resourceOwner: row.owner,
-                    accessLevel: row.access_level,
-                    permission: AccessControl_1.Permission.DELETE,
-                    teamId: options.teamId,
-                    resourceTeamId: row.team_id,
-                    swarmId: options.swarmId,
-                    resourceSwarmId: row.swarm_id,
-                    isSystemAgent: options.isSystemAgent
-                });
-                if (!permCheck.allowed) {
-                    throw new AccessControl_1.AccessControlError(`Delete denied: ${permCheck.reason}`);
+        const agentId = options.agentId || 'system';
+        // Create instrumentation span
+        const { span, context: spanContext } = memory_1.memorySpanManager.startDeleteSpan({
+            agentId: { id: agentId, type: types_1.QEAgentType.FLEET_COMMANDER, created: new Date() },
+            namespace: partition,
+            key,
+        });
+        const startTime = Date.now();
+        try {
+            // Check delete permission if agentId provided
+            if (options.agentId) {
+                const row = await this.queryOne(`SELECT owner, access_level, team_id, swarm_id FROM memory_entries WHERE key = ? AND partition = ?`, [key, partition]);
+                if (row) {
+                    const permCheck = this.accessControl.checkPermission({
+                        agentId: options.agentId,
+                        resourceOwner: row.owner,
+                        accessLevel: row.access_level,
+                        permission: AccessControl_1.Permission.DELETE,
+                        teamId: options.teamId,
+                        resourceTeamId: row.team_id,
+                        swarmId: options.swarmId,
+                        resourceSwarmId: row.swarm_id,
+                        isSystemAgent: options.isSystemAgent
+                    });
+                    if (!permCheck.allowed) {
+                        throw new AccessControl_1.AccessControlError(`Delete denied: ${permCheck.reason}`);
+                    }
                 }
             }
+            await this.run(`DELETE FROM memory_entries WHERE key = ? AND partition = ?`, [key, partition]);
+            // Clean up ACL if exists
+            const resourceId = `${partition}:${key}`;
+            await this.run(`DELETE FROM memory_acl WHERE resource_id = ?`, [resourceId]);
+            this.aclCache.delete(resourceId);
+            // Complete span successfully
+            const durationMs = Date.now() - startTime;
+            memory_1.memorySpanManager.completeDeleteSpan(span, {
+                success: true,
+                durationMs,
+            });
+        }
+        catch (error) {
+            // Complete span with error
+            const durationMs = Date.now() - startTime;
+            memory_1.memorySpanManager.completeDeleteSpan(span, {
+                success: false,
+                durationMs,
+                error: error,
+            });
+            throw error;
         }
-        await this.run(`DELETE FROM memory_entries WHERE key = ? AND partition = ?`, [key, partition]);
-        // Clean up ACL if exists
-        const resourceId = `${partition}:${key}`;
-        await this.run(`DELETE FROM memory_acl WHERE resource_id = ?`, [resourceId]);
-        this.aclCache.delete(resourceId);
     }
     async clear(partition = 'default') {
         if (!this.db) {
@@ -797,8 +973,10 @@ class SwarmMemoryManager {
         const now = Date.now();
         const ttl = pattern.ttl !== undefined ? pattern.ttl : this.TTL_POLICY.patterns;
         const expiresAt = ttl > 0 ? now + (ttl * 1000) : null;
-        await this.run(`INSERT OR REPLACE INTO patterns (id, pattern, confidence, usage_count, metadata, ttl, expires_at, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+        // Extract agent_id from metadata for indexed lookups (O(log n) vs O(n))
+        const agentId = pattern.metadata?.agent_id || pattern.metadata?.agentId || null;
+        await this.run(`INSERT OR REPLACE INTO patterns (id, pattern, confidence, usage_count, metadata, ttl, expires_at, created_at, agent_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
             id,
             pattern.pattern,
             pattern.confidence,
@@ -806,8 +984,11 @@ class SwarmMemoryManager {
             pattern.metadata ? JSON.stringify(pattern.metadata) : null,
             ttl,
             expiresAt,
-            now
+            now,
+            agentId
         ]);
+        // Invalidate cache for this agent to ensure consistency
+        this.invalidatePatternCacheForAgent(agentId);
         return id;
     }
     async getPattern(patternName) {
@@ -835,9 +1016,31 @@ class SwarmMemoryManager {
         if (!this.db) {
             throw new Error('Memory manager not initialized');
         }
-        await this.run(`UPDATE patterns
+        // Get the agent_id before updating to invalidate correct cache entries
+        const pattern = this.queryOne(`SELECT agent_id, metadata FROM patterns WHERE pattern = ?`, [patternName]);
+        this.run(`UPDATE patterns
        SET usage_count = usage_count + 1
        WHERE pattern = ?`, [patternName]);
+        // Invalidate cache for affected agent
+        if (pattern) {
+            const agentId = pattern.agent_id ||
+                (pattern.metadata ? JSON.parse(pattern.metadata).agent_id || JSON.parse(pattern.metadata).agentId : null);
+            this.invalidatePatternCacheForAgent(agentId);
+        }
+    }
+    /**
+     * Invalidate pattern cache for a specific agent
+     * Call this after any pattern mutation to maintain cache coherence
+     */
+    invalidatePatternCacheForAgent(agentId) {
+        if (agentId) {
+            this.patternCache.invalidate(agentId);
+        }
+        else {
+            // Nuclear option for NULL agent_id - clear entire cache
+            // This is expensive but ensures correctness for pre-migration data
+            this.patternCache.clear();
+        }
     }
     async queryPatternsByConfidence(threshold) {
         if (!this.db) {
@@ -865,23 +1068,49 @@ class SwarmMemoryManager {
      * @param minConfidence Minimum confidence threshold (default: 0)
      * @returns Array of patterns belonging to the agent
      */
+    /**
+     * Escape special LIKE pattern characters to prevent SQL injection
+     */
+    escapeLikePattern(value) {
+        return value.replace(/[%_\\]/g, '\\$&');
+    }
     async queryPatternsByAgent(agentId, minConfidence = 0) {
         if (!this.db) {
             throw new Error('Memory manager not initialized');
         }
+        // Check cache first (O(1) lookup)
+        const cacheKey = PatternCache_1.PatternCache.generateKey(agentId, minConfidence);
+        const cached = this.patternCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
         const now = Date.now();
-        const rows = await this.queryAll(`SELECT id, pattern, confidence, usage_count, metadata, ttl, created_at
+        const escapedAgentId = this.escapeLikePattern(agentId);
+        // Split into two queries to ensure index usage on the fast path
+        // Query 1: O(log n) - Use index for agent_id column (post-migration data)
+        const indexedRows = this.queryAll(`SELECT id, pattern, confidence, usage_count, metadata, ttl, created_at
        FROM patterns
-       WHERE confidence >= ?
+       WHERE agent_id = ?
+         AND confidence >= ?
          AND (expires_at IS NULL OR expires_at > ?)
-         AND (metadata LIKE ? OR metadata LIKE ?)
+       ORDER BY confidence DESC`, [agentId, minConfidence, now]);
+        // Query 2: O(n) - Fallback LIKE scan for pre-migration data (agent_id IS NULL)
+        const nullRows = this.queryAll(`SELECT id, pattern, confidence, usage_count, metadata, ttl, created_at
+       FROM patterns
+       WHERE agent_id IS NULL
+         AND confidence >= ?
+         AND (expires_at IS NULL OR expires_at > ?)
+         AND (metadata LIKE ? ESCAPE '\\' OR metadata LIKE ? ESCAPE '\\')
        ORDER BY confidence DESC`, [
             minConfidence,
             now,
-            `%"agent_id":"${agentId}"%`,
-            `%"agentId":"${agentId}"%`
+            `%"agent_id":"${escapedAgentId}"%`,
+            `%"agentId":"${escapedAgentId}"%`
         ]);
-        return rows.map((row) => ({
+        // Combine results and sort by confidence (descending)
+        const allRows = [...indexedRows, ...nullRows];
+        allRows.sort((a, b) => b.confidence - a.confidence);
+        const patterns = allRows.map((row) => ({
             id: row.id,
             pattern: row.pattern,
             confidence: row.confidence,
@@ -890,6 +1119,21 @@ class SwarmMemoryManager {
             ttl: row.ttl,
             createdAt: row.created_at
         }));
+        // Cache results for subsequent lookups
+        this.patternCache.set(cacheKey, patterns);
+        return patterns;
+    }
+    /**
+     * Get pattern cache statistics for monitoring
+     */
+    getPatternCacheStats() {
+        return this.patternCache.getStats();
+    }
+    /**
+     * Clear pattern cache (useful after bulk updates)
+     */
+    clearPatternCache() {
+        this.patternCache.clear();
     }
     // ============================================================================
     // Table 6: Consensus State (TTL: 7 days)