bulltrackers-module 1.0.592 → 1.0.593

package/functions/old-generic-api/admin-api/index.js

@@ -0,0 +1,895 @@
+/**
+ * @fileoverview Admin API Router
+ * Sub-module for system observability, debugging, and visualization.
+ * Mounted at /admin within the Generic API.
+ * UPDATED: Added Stale Task Detection, Root Data Health, and SimHash Inspection.
+ */
+
+const express = require('express');
+const pLimit = require('p-limit');
+const { getManifest } = require('../../computation-system/topology/ManifestLoader');
+const { normalizeName } = require('../../computation-system/utils/utils');
+
+/**
+ * Factory to create the Admin Router.
+ * @param {object} config - System configuration.
+ * @param {object} dependencies - { db, logger, ... }
+ * @param {object} unifiedCalculations - The injected calculations package.
+ */
+const createAdminRouter = (config, dependencies, unifiedCalculations) => {
+    const router = express.Router();
+    const { db, logger } = dependencies;
+
+    // Helper to get fresh manifest
+    const getFullManifest = () => getManifest([], unifiedCalculations, dependencies);
+
+    // --- 1. TOPOLOGY VISUALIZER ---
+    router.get('/topology', async (req, res) => {
+        try {
+            const manifest = getFullManifest();
+            const nodes = [];
+            const edges = [];
+
+            manifest.forEach(calc => {
+                nodes.push({
+                    id: calc.name,
+                    data: { 
+                        label: calc.name,
+                        layer: calc.category,
+                        pass: calc.pass,
+                        isHistorical: calc.isHistorical,
+                        type: calc.type
+                    },
+                    position: { x: 0, y: 0 }
+                });
+
+                if (calc.dependencies) {
+                    calc.dependencies.forEach(dep => {
+                        edges.push({
+                            id: `e-${dep}-${calc.name}`,
+                            source: normalizeName(dep),
+                            target: calc.name,
+                            type: 'smoothstep'
+                        });
+                    });
+                }
+                
+                if (calc.rootDataDependencies) {
+                    calc.rootDataDependencies.forEach(root => {
+                        const rootId = `ROOT_${root.toUpperCase()}`;
+                        if (!nodes.find(n => n.id === rootId)) {
+                            nodes.push({
+                                id: rootId,
+                                type: 'input',
+                                data: { label: `${root.toUpperCase()} DB` },
+                                position: { x: 0, y: 0 },
+                                style: { background: '#f0f0f0', border: '1px solid #777' }
+                            });
+                        }
+                        edges.push({
+                            id: `e-root-${root}-${calc.name}`,
+                            source: rootId,
+                            target: calc.name,
+                            animated: true,
+                            style: { stroke: '#ff0072' }
+                        });
+                    });
+                }
+            });
+
+            res.json({ summary: { totalNodes: nodes.length, totalEdges: edges.length }, nodes, edges });
+        } catch (e) {
+            logger.log('ERROR', '[AdminAPI] Topology build failed', e);
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 2. STATUS MATRIX (Calendar / State UI) ---
+    router.get('/matrix', async (req, res) => {
+        const { start, end } = req.query;
+        if (!start || !end) return res.status(400).json({ error: "Start and End dates required." });
+
+        try {
+            const startDate = new Date(String(start));
+            const endDate = new Date(String(end));
+            const dates = [];
+            for (let d = new Date(startDate); d <= endDate; d.setDate(d.getDate() + 1)) {
+                dates.push(d.toISOString().slice(0, 10));
+            }
+
+            const manifest = getFullManifest();
+            const allCalcNames = new Set(manifest.map(c => c.name));
+
+            const limit = pLimit(20);
+            const matrix = {};
+
+            await Promise.all(dates.map(date => limit(async () => {
+                // Fetch Status and Root Data Availability
+                const [statusSnap, rootSnap] = await Promise.all([
+                    db.collection('computation_status').doc(date).get(),
+                    db.collection('system_root_data_index').doc(date).get()
+                ]);
+
+                const statusData = statusSnap.exists ? statusSnap.data() : {};
+                const rootData = rootSnap.exists ? rootSnap.data() : { status: { hasPortfolio: false } };
+
+                const dateStatus = {};
+
+                // Check every calculation in the Manifest
+                allCalcNames.forEach(calcName => {
+                    const entry = statusData[calcName];
+                    
+                    if (!entry) {
+                        // If root data exists but calc is missing -> PENDING
+                        // If no root data -> WAITING_DATA
+                        dateStatus[calcName] = rootData.status?.hasPortfolio ? 'PENDING' : 'WAITING_DATA';
+                    } else if (typeof entry === 'object') {
+                        if (entry.hash && typeof entry.hash === 'string' && entry.hash.startsWith('IMPOSSIBLE')) {
+                            dateStatus[calcName] = 'IMPOSSIBLE';
+                        } else if (entry.hash === false) {
+                            dateStatus[calcName] = 'BLOCKED';
+                        } else {
+                            dateStatus[calcName] = 'COMPLETED';
+                        }
+                    } else if (entry === 'IMPOSSIBLE') {
+                        dateStatus[calcName] = 'IMPOSSIBLE';
+                    } else {
+                        dateStatus[calcName] = 'COMPLETED';
+                    }
+                });
+
+                matrix[date] = {
+                    dataAvailable: rootData.status || {},
+                    calculations: dateStatus
+                };
+            })));
+
+            res.json(matrix);
+        } catch (e) {
+            logger.log('ERROR', '[AdminAPI] Matrix fetch failed', e);
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 3. PIPELINE STATE (Progress Bar) ---
+    router.get('/pipeline/state', async (req, res) => {
+        const { date } = req.query;
+        if (!date) return res.status(400).json({ error: "Date required" });
+
+        try {
+            const passes = ['1', '2', '3', '4', '5'];
+            const state = await Promise.all(passes.map(async (pass) => {
+                // We use the Audit Ledger which is the source of truth for execution state
+                const tasksSnap = await db.collection(`computation_audit_ledger/${date}/passes/${pass}/tasks`).get();
+                
+                const stats = {
+                    pending: 0,
+                    inProgress: 0,
+                    completed: 0,
+                    failed: 0,
+                    totalMemoryMB: 0,
+                    avgDurationMs: 0
+                };
+                
+                const durations = [];
+                
+                tasksSnap.forEach(doc => {
+                    const data = doc.data();
+                    const s = (data.status || 'UNKNOWN').toLowerCase();
+                    if (stats[s] !== undefined) stats[s]++;
+                    else stats[s] = 1;
+
+                    if (data.telemetry?.lastMemory?.rssMB) {
+                        stats.totalMemoryMB += data.telemetry.lastMemory.rssMB;
+                    }
+                    if (data.completedAt && data.startedAt) {
+                        durations.push(new Date(data.completedAt).getTime() - new Date(data.startedAt).getTime());
+                    }
+                });
+
+                stats.avgDurationMs = durations.length ? 
+                    Math.round(durations.reduce((a, b) => a + b, 0) / durations.length) : 0;
+
+                return { pass, stats, totalTasks: tasksSnap.size };
+            }));
+
+            res.json({ date, passes: state });
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 4. DEPENDENCY TRACER (Blast Radius) ---
+    router.get('/trace/:calcName', async (req, res) => {
+        const { calcName } = req.params;
+        const mode = req.query.mode || 'downstream'; // 'upstream' or 'downstream'
+        
+        try {
+            const manifest = getFullManifest();
+            const manifestMap = new Map(manifest.map(c => [c.name, c]));
+            
+            if (!manifestMap.has(calcName)) return res.status(404).json({ error: 'Calculation not found' });
+
+            const trace = { root: calcName, chain: [] };
+
+            if (mode === 'upstream') {
+                // What does X depend on?
+                const visited = new Set();
+                const walk = (name, depth = 0) => {
+                    if (visited.has(name) || depth > 10) return;
+                    visited.add(name);
+                    const calc = manifestMap.get(name);
+                    if (!calc) return;
+                    
+                    trace.chain.push({ 
+                        name, depth, pass: calc.pass, type: calc.type 
+                    });
+                    
+                    calc.dependencies?.forEach(dep => walk(dep, depth + 1));
+                };
+                walk(calcName);
+            } else {
+                // What depends on X? (Downstream / Impact)
+                const reverseGraph = new Map();
+                manifest.forEach(c => {
+                    c.dependencies?.forEach(dep => {
+                        const normDep = normalizeName(dep);
+                        if (!reverseGraph.has(normDep)) reverseGraph.set(normDep, []);
+                        reverseGraph.get(normDep).push(c.name);
+                    });
+                });
+
+                const visited = new Set();
+                const walk = (name, depth = 0) => {
+                    if (visited.has(name) || depth > 10) return;
+                    visited.add(name);
+                    
+                    const calc = manifestMap.get(name);
+                    trace.chain.push({ 
+                        name, depth, pass: calc?.pass 
+                    });
+
+                    reverseGraph.get(name)?.forEach(child => walk(child, depth + 1));
+                };
+                walk(calcName);
+            }
+
+            res.json(trace);
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 5. CONTRACT VIOLATIONS (Quality Gate) ---
+    router.get('/violations', async (req, res) => {
+        const days = parseInt(String(req.query.days)) || 7;
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - days);
+
+        try {
+            // Check DLQ for Semantic Failures (Hard Violations)
+            const dlqSnap = await db.collection('computation_dead_letter_queue')
+                .where('finalAttemptAt', '>', cutoff)
+                .where('error.stage', '==', 'SEMANTIC_GATE')
+                .limit(50)
+                .get();
+
+            const violations = [];
+            dlqSnap.forEach(doc => {
+                const data = doc.data();
+                violations.push({
+                    id: doc.id,
+                    computation: data.originalData.computation,
+                    date: data.originalData.date,
+                    reason: data.error.message,
+                    type: 'HARD_VIOLATION',
+                    timestamp: data.finalAttemptAt
+                });
+            });
+
+            // Check Audit Logs for Soft Anomalies (Statistical warnings)
+            const anomalySnap = await db.collectionGroup('history')
+                .where('triggerTime', '>', cutoff.toISOString())
+                .where('anomalies', '!=', []) // Firestore != operator
+                .limit(50)
+                .get();
+
+            anomalySnap.forEach(doc => {
+                const data = doc.data();
+                data.anomalies?.forEach(anomaly => {
+                    violations.push({
+                        id: doc.id,
+                        computation: data.computationName,
+                        date: data.targetDate,
+                        reason: anomaly,
+                        type: 'SOFT_ANOMALY',
+                        timestamp: data.triggerTime
+                    });
+                });
+            });
+
+            // Sort by time desc
+            violations.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+
+            res.json({ count: violations.length, violations });
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 6. MEMORY HOTSPOTS (Forensics) ---
+    router.get('/memory/hotspots', async (req, res) => {
+        const thresholdMB = parseInt(String(req.query.threshold)) || 1000; // 1GB default
+        
+        try {
+            // Ledger tasks maintain 'telemetry.lastMemory'
+            // We use collectionGroup to search across all dates/passes
+            const snapshot = await db.collectionGroup('tasks')
+                .where('telemetry.lastMemory.rssMB', '>', thresholdMB)
+                .orderBy('telemetry.lastMemory.rssMB', 'desc')
+                .limit(20)
+                .get();
+
+            const hotspots = [];
+            snapshot.forEach(doc => {
+                const data = doc.data();
+                hotspots.push({
+                    computation: data.computation,
+                    rssMB: data.telemetry.lastMemory.rssMB,
+                    heapMB: data.telemetry.lastMemory.heapUsedMB,
+                    status: data.status,
+                    worker: data.workerId,
+                    date: doc.ref.parent.parent.parent.parent.id // traversing path to get date
+                });
+            });
+            
+            res.json({ count: hotspots.length, hotspots });
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 7. FLIGHT RECORDER (Inspection) ---
+    router.get('/inspect/:date/:calcName', async (req, res) => {
+        const { date, calcName } = req.params;
+        try {
+            const passes = ['1', '2', '3', '4', '5'];
+            let executionRecord = null;
+
+            await Promise.all(passes.map(async (pass) => {
+                if (executionRecord) return;
+                const ref = db.doc(`computation_audit_ledger/${date}/passes/${pass}/tasks/${calcName}`);
+                const snap = await ref.get();
+                if (snap.exists) executionRecord = { pass, ...snap.data() };
+            }));
+
+            if (!executionRecord) return res.status(404).json({ status: 'NOT_FOUND' });
+
+            const contractSnap = await db.collection('system_contracts').doc(calcName).get();
+            
+            res.json({
+                execution: executionRecord,
+                contract: contractSnap.exists ? contractSnap.data() : null
+            });
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 8. COST & RESOURCE ANALYSIS ---
+    router.get('/analytics/costs', async (req, res) => {
+        const { date, days } = req.query;
+        // Default to today if no date, or range if days provided
+        const targetDate = date || new Date().toISOString().slice(0, 10);
+        
+        // Simple Cost Model (Estimates)
+        const COSTS = {
+            write: 0.18 / 100000,
+            read:  0.06 / 100000,
+            delete: 0.02 / 100000,
+            compute_std_sec:  0.000023, // 1vCPU 2GB (approx)
+            compute_high_sec: 0.000092  // 2vCPU 8GB (approx)
+        };
+
+        try {
+            const auditRef = db.collection('computation_audit_logs');
+            // We scan the 'history' subcollectionGroup for the given date(s)
+            // Note: This can be expensive. In prod, you'd want aggregate counters.
+            const query = db.collectionGroup('history').where('targetDate', '==', targetDate);
+            const snap = await query.get();
+
+            let totalCost = 0;
+            const byPass = {};
+            const byCalc = {};
+
+            snap.forEach(doc => {
+                const data = doc.data();
+                const ops = data.firestoreOps || { reads: 0, writes: 0, deletes: 0 };
+                const durationSec = (data.durationMs || 0) / 1000;
+                const tier = data.resourceTier || 'standard';
+
+                const ioCost = (ops.writes * COSTS.write) + (ops.reads * COSTS.read) + (ops.deletes * COSTS.delete);
+                const computeCost = durationSec * (tier === 'high-mem' ? COSTS.compute_high_sec : COSTS.compute_std_sec);
+                const itemCost = ioCost + computeCost;
+
+                totalCost += itemCost;
+
+                // Aggregations
+                const pass = data.pass || 'unknown';
+                if (!byPass[pass]) byPass[pass] = { cost: 0, runs: 0, duration: 0 };
+                byPass[pass].cost += itemCost;
+                byPass[pass].runs++;
+                byPass[pass].duration += durationSec;
+
+                const calc = data.computationName;
+                if (!byCalc[calc]) byCalc[calc] = { cost: 0, runs: 0, ops: { r:0, w:0 } };
+                byCalc[calc].cost += itemCost;
+                byCalc[calc].runs++;
+                byCalc[calc].ops.r += ops.reads;
+                byCalc[calc].ops.w += ops.writes;
+            });
+
+            // Top 10 Expensive Calcs
+            const topCalcs = Object.entries(byCalc)
+                .sort((a, b) => b[1].cost - a[1].cost)
+                .slice(0, 10)
+                .map(([name, stats]) => ({ name, ...stats }));
+
+            res.json({
+                date: targetDate,
+                totalCostUSD: totalCost,
+                breakdown: {
+                    byPass,
+                    topCalculations: topCalcs
+                },
+                meta: { model: COSTS }
+            });
+
+        } catch (e) { res.status(500).json({ error: e.message }); }
+    });
+
+    // --- 9. REROUTE (OOM) ANALYSIS ---
+    router.get('/analytics/reroutes', async (req, res) => {
+        const { date } = req.query;
+        if (!date) return res.status(400).json({ error: "Date required" });
+
+        try {
+            // Find all runs that used high-mem
+            const query = db.collectionGroup('history')
+                .where('targetDate', '==', date)
+                .where('resourceTier', '==', 'high-mem');
+            
+            const snap = await query.get();
+            const reroutes = [];
+
+            snap.forEach(doc => {
+                const data = doc.data();
+                reroutes.push({
+                    computation: data.computationName,
+                    pass: data.pass,
+                    trigger: data.trigger?.reason,
+                    peakMemoryMB: data.peakMemoryMB,
+                    durationMs: data.durationMs,
+                    runId: data.runId
+                });
+            });
+
+            res.json({ count: reroutes.length, reroutes });
+        } catch (e) { res.status(500).json({ error: e.message }); }
+    });
+
+    // --- 10. LIVE DASHBOARD (Snapshot) ---
+    // Poll this endpoint to simulate a WebSocket feed
+    router.get('/live/dashboard', async (req, res) => {
+        const today = new Date().toISOString().slice(0, 10);
+        try {
+            // Query the Ledger for Active Tasks
+            // We look at all passes for today
+            const passes = ['1', '2', '3', '4', '5'];
+            const activeTasks = [];
+            const recentFailures = [];
+
+            await Promise.all(passes.map(async (pass) => {
+                const colRef = db.collection(`computation_audit_ledger/${today}/passes/${pass}/tasks`);
+                
+                // Get Running
+                const runningSnap = await colRef.where('status', 'in', ['PENDING', 'IN_PROGRESS']).get();
+                runningSnap.forEach(doc => {
+                    activeTasks.push({ pass, ...doc.data() });
+                });
+
+                // Get Recent Failures (last 10 mins?? hard to query without index, just grab failures)
+                const failSnap = await colRef.where('status', '==', 'FAILED').get();
+                failSnap.forEach(doc => {
+                    recentFailures.push({ pass, ...doc.data() });
+                });
+            }));
+
+            // Get Pipeline Stage (which pass is active?)
+            // We infer this by seeing which pass has pending tasks
+            let currentStage = 'IDLE';
+            for (const p of passes) {
+                const hasActive = activeTasks.some(t => t.pass === p);
+                if (hasActive) { currentStage = `PASS_${p}`; break; }
+            }
+
+            res.json({
+                status: 'success',
+                timestamp: new Date(),
+                pipelineState: currentStage,
+                activeCount: activeTasks.length,
+                failureCount: recentFailures.length,
+                tasks: activeTasks,
+                failures: recentFailures
+            });
+
+        } catch (e) { res.status(500).json({ error: e.message }); }
+    });
+
+    // =========================================================================
+    // NEW DEBUGGING ROUTES (Added 2025-12-19)
+    // =========================================================================
+
+    // --- 11. STALE COMPUTATION DETECTOR ("Zombie Hunter") ---
+    router.get('/debug/stale', async (req, res) => {
+        const thresholdMins = parseInt(String(req.query.threshold)) || 15;
+        const cutoffTime = Date.now() - (thresholdMins * 60 * 1000);
+        
+        try {
+            // Scanning collectionGroup 'tasks' is expensive, so we focus on 'IN_PROGRESS'
+            // and filter in memory if necessary, or rely on composite index if available.
+            const snapshot = await db.collectionGroup('tasks')
+                .where('status', '==', 'IN_PROGRESS')
+                .get();
+
+            const zombies = [];
+            snapshot.forEach(doc => {
+                const data = doc.data();
+                
+                // Determine last activity (Heartbeat > StartedAt > 0)
+                const lastActivity = data.telemetry?.lastHeartbeat 
+                    ? new Date(data.telemetry.lastHeartbeat).getTime() 
+                    : (data.startedAt ? new Date(data.startedAt).getTime() : 0);
+
+                if (lastActivity < cutoffTime) {
+                    zombies.push({
+                        computation: data.computation || doc.id,
+                        workerId: data.workerId || 'unknown',
+                        startedAt: data.startedAt,
+                        lastHeartbeat: data.telemetry?.lastHeartbeat,
+                        stagnantMinutes: Math.floor((Date.now() - lastActivity) / 60000),
+                        path: doc.ref.path // Useful for manual deletion
+                    });
+                }
+            });
+
+            // Sort by most stagnant
+            zombies.sort((a, b) => b.stagnantMinutes - a.stagnantMinutes);
+
+            res.json({
+                count: zombies.length,
+                thresholdMins,
+                zombies
+            });
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 12. ROOT DATA HEALTH CHECK ---
+    // Debugs the "Available but marked missing" issue
+    router.get('/debug/root-data-health', async (req, res) => {
+        const { start, end } = req.query;
+        if (!start || !end) return res.status(400).json({ error: "Start and End dates required." });
+
+        try {
+            const startDate = new Date(String(start));
+            const endDate = new Date(String(end));
+            const dates = [];
+            for (let d = new Date(startDate); d <= endDate; d.setDate(d.getDate() + 1)) {
+                dates.push(d.toISOString().slice(0, 10));
+            }
+
+            const report = {};
+            const limit = pLimit(10);
+
+            await Promise.all(dates.map(date => limit(async () => {
+                const rootDoc = await db.collection('system_root_data_index').doc(date).get();
+                if (!rootDoc.exists) {
+                    report[date] = { exists: false, status: 'MISSING_INDEX' };
+                } else {
+                    const data = rootDoc.data();
+                    report[date] = {
+                        exists: true,
+                        status: 'OK',
+                        flags: data.status, // hasHistory, hasPortfolio, etc.
+                        lastUpdated: data.lastUpdated
+                    };
+                }
+            })));
+
+            res.json(report);
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 13. SIMHASH INSPECTOR ---
+    // Debugs "Why did this run? Code Changed?"
+    router.get('/debug/simhash/:hash', async (req, res) => {
+        const { hash } = req.params;
+        try {
+            const doc = await db.collection('system_simhash_registry').doc(hash).get();
+            if (!doc.exists) return res.status(404).json({ error: "Hash not found in registry." });
+            
+            res.json(doc.data());
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // --- 10. DEVELOPER USER MANAGEMENT (Force Sync & Lookup) ---
+    // Only accessible to developer accounts
+    
+    /**
+     * POST /admin/users/:cid/sync
+     * Force sync a signed-in user (developer only)
+     * Allows developers to trigger sync for any user to fix stuck accounts
+     */
+    router.post('/users/:cid/sync', async (req, res) => {
+        const { cid } = req.params;
+        const { userCid: developerCid } = req.query; // Developer's CID
+        
+        if (!developerCid) {
+            return res.status(400).json({ 
+                success: false,
+                error: "Missing userCid",
+                message: "Please provide userCid query parameter (your developer CID)"
+            });
+        }
+        
+        // SECURITY: Only allow developer accounts
+        const { isDeveloperAccount } = require('../user-api/helpers/dev/dev_helpers');
+        if (!isDeveloperAccount(Number(developerCid))) {
+            logger.log('WARN', `[AdminAPI] Unauthorized sync attempt by non-developer ${developerCid}`);
+            return res.status(403).json({ 
+                success: false,
+                error: "Forbidden",
+                message: "This endpoint is only available for developer accounts"
+            });
+        }
+        
+        const targetCidNum = Number(cid);
+        if (isNaN(targetCidNum) || targetCidNum <= 0) {
+            return res.status(400).json({
+                success: false,
+                error: "Invalid CID",
+                message: "Please provide a valid user CID"
+            });
+        }
+        
+        try {
+            // Import sync helper
+            const { requestUserSync } = require('../user-api/helpers/sync/user_sync_helpers');
+            
+            // Create a mock request object with the target CID
+            const mockReq = {
+                params: { userCid: String(targetCidNum) },
+                query: { userCid: String(developerCid), sourcePage: 'admin' },
+                headers: {},
+                body: {}
+            };
+            
+            // Call the sync function
+            await requestUserSync(mockReq, res, dependencies, config);
+            
+            logger.log('INFO', `[AdminAPI] Developer ${developerCid} force-synced user ${targetCidNum}`);
+            
+        } catch (error) {
+            logger.log('ERROR', `[AdminAPI] Error force-syncing user ${targetCidNum}`, error);
+            return res.status(500).json({
+                success: false,
+                error: "Internal server error",
+                message: error.message
+            });
+        }
+    });
+    
+    /**
+     * GET /admin/users/:cid/lookup
+     * Look up user information by CID (developer only)
+     * Helps developers find users to sync
+     */
+    router.get('/users/:cid/lookup', async (req, res) => {
+        const { cid } = req.params;
+        const { userCid: developerCid } = req.query; // Developer's CID
+        
+        if (!developerCid) {
+            return res.status(400).json({ 
+                success: false,
+                error: "Missing userCid",
+                message: "Please provide userCid query parameter (your developer CID)"
+            });
+        }
+        
+        // SECURITY: Only allow developer accounts
+        const { isDeveloperAccount } = require('../user-api/helpers/dev/dev_helpers');
+        if (!isDeveloperAccount(Number(developerCid))) {
+            logger.log('WARN', `[AdminAPI] Unauthorized lookup attempt by non-developer ${developerCid}`);
+            return res.status(403).json({ 
+                success: false,
+                error: "Forbidden",
+                message: "This endpoint is only available for developer accounts"
+            });
+        }
+        
+        const targetCidNum = Number(cid);
+        if (isNaN(targetCidNum) || targetCidNum <= 0) {
+            return res.status(400).json({
+                success: false,
+                error: "Invalid CID",
+                message: "Please provide a valid user CID"
+            });
+        }
+        
+        try {
+            const signedInUsersCollection = config.signedInUsersCollection || 'signed_in_users';
+            const { checkIfUserIsPI } = require('../user-api/helpers/core/user_status_helpers');
+            
+            // Check if user is a PI
+            const rankEntry = await checkIfUserIsPI(db, targetCidNum, config, logger);
+            const isPI = !!rankEntry;
+            
+            // Get signed-in user data
+            const userDoc = await db.collection(signedInUsersCollection).doc(String(targetCidNum)).get();
+            const userData = userDoc.exists ? userDoc.data() : null;
+            
+            // Get verification data
+            const verificationsCollection = config.verificationsCollection || 'verifications';
+            let verificationData = null;
+            if (userData && userData.username) {
+                const verificationDoc = await db.collection(verificationsCollection)
+                    .doc(userData.username.toLowerCase())
+                    .get();
+                if (verificationDoc.exists) {
+                    verificationData = verificationDoc.data();
+                }
+            }
+            
+            // Get latest sync request status
+            const syncRequestsRef = db.collection('user_sync_requests')
+                .doc(String(targetCidNum))
+                .collection('requests')
+                .orderBy('createdAt', 'desc')
+                .limit(1);
+            
+            const latestSyncSnapshot = await syncRequestsRef.get();
+            let latestSync = null;
+            if (!latestSyncSnapshot.empty) {
+                latestSync = {
+                    requestId: latestSyncSnapshot.docs[0].id,
+                    ...latestSyncSnapshot.docs[0].data()
+                };
+            }
+            
+            // Get data status directly (don't use the endpoint wrapper)
+            let dataStatus = null;
+            try {
+                const { signedInUsersCollection, signedInHistoryCollection } = config;
+                const { findLatestPortfolioDate } = require('../user-api/helpers/core/data_lookup_helpers');
+                const CANARY_BLOCK_ID = '19M';
+                const today = new Date().toISOString().split('T')[0];
+                
+                // Check portfolio
+                const portfolioDate = await findLatestPortfolioDate(db, signedInUsersCollection, targetCidNum, 30);
+                const portfolioExists = !!portfolioDate;
+                const isPortfolioFallback = portfolioDate && portfolioDate !== today;
+                
+                // Check history
+                let historyExists = false;
+                let historyDate = null;
+                let isHistoryFallback = false;
+                
+                const historyCollection = signedInHistoryCollection || 'signed_in_user_history';
+                const todayHistoryRef = db.collection(historyCollection)
+                    .doc(CANARY_BLOCK_ID)
+                    .collection('snapshots')
+                    .doc(today)
+                    .collection('parts');
+                
+                const todayHistorySnapshot = await todayHistoryRef.get();
+                
+                if (!todayHistorySnapshot.empty) {
+                    historyExists = true;
+                    historyDate = today;
+                } else {
+                    // Check fallback dates
+                    for (let i = 1; i <= 30; i++) {
+                        const checkDate = new Date(today);
+                        checkDate.setDate(checkDate.getDate() - i);
+                        const dateStr = checkDate.toISOString().split('T')[0];
+                        
+                        const historyRef = db.collection(historyCollection)
+                            .doc(CANARY_BLOCK_ID)
+                            .collection('snapshots')
+                            .doc(dateStr)
+                            .collection('parts');
+                        
+                        const snapshot = await historyRef.get();
+                        if (!snapshot.empty) {
+                            // Check if this user's data exists in any part
+                            for (const partDoc of snapshot.docs) {
+                                const partData = partDoc.data();
+                                if (partData.users && partData.users[String(targetCidNum)]) {
+                                    historyExists = true;
+                                    historyDate = dateStr;
+                                    isHistoryFallback = true;
+                                    break;
+                                }
+                            }
+                            if (historyExists) break;
+                        }
+                    }
+                }
+                
+                dataStatus = {
+                    portfolioAvailable: portfolioExists,
+                    historyAvailable: historyExists,
+                    date: portfolioDate || today,
+                    portfolioDate: portfolioDate,
+                    historyDate: historyDate,
+                    isPortfolioFallback: isPortfolioFallback,
+                    isHistoryFallback: isHistoryFallback,
+                    requestedDate: today,
+                    userCid: String(targetCidNum)
+                };
+            } catch (e) {
+                logger.log('WARN', `[AdminAPI] Error getting data status: ${e.message}`);
+            }
+            
+            const result = {
+                success: true,
+                cid: targetCidNum,
+                isPI: isPI,
+                userData: userData ? {
+                    username: userData.username,
+                    fullName: userData.fullName,
+                    avatar: userData.avatar,
+                    verifiedAt: userData.verifiedAt,
+                    lastLogin: userData.lastLogin,
+                    isOptOut: userData.isOptOut
+                } : null,
+                piData: rankEntry ? {
+                    username: rankEntry.UserName || rankEntry.username,
+                    aum: rankEntry.AUMValue,
+                    copiers: rankEntry.Copiers,
+                    riskScore: rankEntry.RiskScore,
+                    gain: rankEntry.Gain
+                } : null,
+                verification: verificationData ? {
+                    status: verificationData.status,
+                    verifiedAt: verificationData.verifiedAt,
+                    isOptOut: verificationData.isOptOut
+                } : null,
+                latestSync: latestSync,
+                dataStatus: dataStatus
+            };
+            
+            logger.log('INFO', `[AdminAPI] Developer ${developerCid} looked up user ${targetCidNum}`);
+            
+            return res.status(200).json(result);
+            
+        } catch (error) {
+            logger.log('ERROR', `[AdminAPI] Error looking up user ${targetCidNum}`, error);
+            return res.status(500).json({
+                success: false,
+                error: "Internal server error",
+                message: error.message
+            });
+        }
+    });
+
+    return router;
+};
+
+module.exports = createAdminRouter;