fraim-framework 2.0.179 → 2.0.180

package/dist/src/fraim/db-service.js

@@ -0,0 +1,2387 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FraimDbService = void 0;
+const mongodb_1 = require("mongodb");
+const git_utils_1 = require("../core/utils/git-utils");
+const quality_evidence_1 = require("../core/quality-evidence");
+function sanitizeSessionRepoContext(repo) {
+    if (!repo || typeof repo !== 'object') {
+        return repo;
+    }
+    const sanitizedUrl = (0, git_utils_1.sanitizeRepoIdentifier)(typeof repo.url === 'string' ? repo.url : undefined);
+    const sanitizedRepo = {
+        ...repo,
+        url: sanitizedUrl
+    };
+    if ((!sanitizedRepo.name || sanitizedRepo.name === 'unknown') && sanitizedUrl) {
+        sanitizedRepo.name = sanitizedUrl.startsWith('https://')
+            ? sanitizedRepo.name
+            : sanitizedUrl;
+    }
+    return sanitizedRepo;
+}
+function normalizeUserIds(userIds) {
+    return [...new Set(userIds.filter(Boolean).map((value) => value.toLowerCase().trim()).filter(Boolean))];
+}
+function normalizeLabels(labels) {
+    const seen = new Set();
+    const normalized = [];
+    for (const label of labels) {
+        const cleaned = label.trim();
+        if (!cleaned)
+            continue;
+        const key = cleaned.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        normalized.push(cleaned);
+    }
+    return normalized;
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function buildLabelMatch(label) {
+    return { labels: { $regex: `^${escapeRegex(label)}$`, $options: 'i' } };
+}
+function mergeLabels(existing, labelsToAdd) {
+    const merged = normalizeLabels(existing || []);
+    const seen = new Set(merged.map((label) => label.toLowerCase()));
+    for (const label of labelsToAdd) {
+        const key = label.toLowerCase();
+        if (!seen.has(key)) {
+            merged.push(label);
+            seen.add(key);
+        }
+    }
+    return merged;
+}
+function removeLabels(existing, labelsToRemove) {
+    const removeSet = new Set(labelsToRemove.map((label) => label.toLowerCase()));
+    return normalizeLabels(existing || []).filter((label) => !removeSet.has(label.toLowerCase()));
+}
+class FraimDbService {
+    constructor() {
+        this.usageEventsCollectionName = 'fraim_usage_events';
+        const url = process.env.MONGODB_URI || process.env.MONGO_DATABASE_URL;
+        if (!url) {
+            throw new Error('MONGODB_URI or MONGO_DATABASE_URL not found in environment');
+        }
+        this.uri = url;
+        this.dbName = (0, git_utils_1.determineDatabaseName)();
+    }
+    async connect() {
+        FraimDbService.refCount++;
+        if (FraimDbService.connectionPromise) {
+            await FraimDbService.connectionPromise;
+            this.client = FraimDbService.client;
+            this.db = FraimDbService.db;
+            // Ensure per-instance collection handles are initialized when reusing shared connection.
+            await this.initializeCollections();
+            return;
+        }
+        FraimDbService.connectionPromise = (async () => {
+            try {
+                if (!FraimDbService.client) {
+                    FraimDbService.client = new mongodb_1.MongoClient(this.uri);
+                    await FraimDbService.client.connect();
+                    FraimDbService.db = FraimDbService.client.db(this.dbName);
+                }
+                this.client = FraimDbService.client;
+                this.db = FraimDbService.db;
+                console.log(`[FRAIM] Connected to MongoDB: ${this.uri.replace(/:([^:@]+)@/, ':****@')}, Database: ${this.dbName}`);
+                // Initialize collections and indexes
+                await this.initializeCollections();
+                await this.initializeIndexes();
+                await this.initializeUsageEventsCollection();
+                console.log(`✅ Connected to Fraim DB: ${this.dbName}`);
+            }
+            catch (error) {
+                FraimDbService.connectionPromise = undefined;
+                console.error('❌ Failed to connect to MongoDB:', error);
+                throw error;
+            }
+        })();
+        await FraimDbService.connectionPromise;
+    }
+    async initializeCollections() {
+        if (!this.db)
+            throw new Error('DB not connected during collection initialization');
+        this.keysCollection = this.db.collection('fraim_api_keys');
+        this.sessionsCollection = this.db.collection('fraim_telemetry_sessions');
+        this.signupsCollection = this.db.collection('fraim_website_signups');
+        this.salesCollection = this.db.collection('fraim_sales_inquiries');
+        this.accessTokensCollection = this.db.collection('fraim_access_tokens');
+        this.pendingVerificationsCollection = this.db.collection('fraim_pending_verifications');
+        this.webhookEventsCollection = this.db.collection('fraim_webhook_events');
+        this.partnerDiscountsCollection = this.db.collection('fraim_partner_discounts');
+        this.managerTeamsCollection = this.db.collection('fraim_manager_teams');
+        this.aiHubManagerAssignmentsCollection = this.db.collection('fraim_hub_manager_assignments');
+        this.qualityScoresCollection = this.db.collection('fraim_quality_scores');
+        this.personaEntitlementsCollection = this.db.collection('fraim_persona_entitlements');
+        // Issue #359 — OAuth-first login.
+        this.authSessionsCollection = this.db.collection('fraim_auth_sessions');
+        this.pendingOAuthCollection = this.db.collection('fraim_pending_oauth');
+        this.auditLogCollection = this.db.collection('fraim_audit_log');
+        // Issue #563 — shared organization context (FRAIM-cloud backend).
+        this.orgArtifactsCollection = this.db.collection('fraim_org_artifacts');
+        this.orgAuditCollection = this.db.collection('fraim_org_audit');
+    }
+    async initializeIndexes() {
+        if (!this.db)
+            throw new Error('DB not connected during index initialization');
+        await this.keysCollection.createIndex({ key: 1 }, { unique: true });
+        await this.keysCollection.createIndex({ userId: 1 });
+        await this.keysCollection.createIndex({ stripeSubscriptionId: 1 });
+        await this.keysCollection.createIndex({ status: 1 });
+        await this.keysCollection.createIndex({ expiresAt: 1 });
+        await this.sessionsCollection.createIndex({ sessionId: 1 }, { unique: true });
+        await this.sessionsCollection.createIndex({ userId: 1 });
+        await this.sessionsCollection.createIndex({ lastActive: -1 });
+        await this.signupsCollection.createIndex({ email: 1 }, { unique: true });
+        await this.signupsCollection.createIndex({ timestamp: -1 });
+        await this.salesCollection.createIndex({ email: 1 });
+        await this.salesCollection.createIndex({ timestamp: -1 });
+        await this.accessTokensCollection.createIndex({ token: 1 }, { unique: true });
+        // TTL index — createIndex is a no-op if the index already exists with the same options.
+        // Avoid drop+recreate: Cosmos DB PITR-restored accounts block index drops on restored collections.
+        await this.accessTokensCollection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+        await this.pendingVerificationsCollection.createIndex({ token: 1 }, { unique: true });
+        // Issue #563 — org artifacts are unique per (orgId, relativePath); audit reads newest-first.
+        // Index creation must never crash startup: Azure Cosmos DB (Mongo API) can
+        // reject a unique compound index, and connect() re-throws on failure. Logical
+        // uniqueness is already guaranteed by upsertOrgArtifact's replaceOne filter on
+        // { orgId, relativePath }, so the index is an optimization, not a correctness
+        // requirement — swallow failures like the other Cosmos-sensitive indexes above.
+        await this.orgArtifactsCollection.createIndex({ orgId: 1, relativePath: 1 }, { unique: true }).catch(() => { });
+        await this.orgAuditCollection.createIndex({ orgId: 1, at: -1 }).catch(() => { });
+        await this.pendingVerificationsCollection.createIndex({ email: 1 });
+        // Compound index covers `findOne({email}, { sort: { createdAt: -1 } })` —
+        // the request-access flow's lookup of the most-recent pending row per
+        // email. On real MongoDB the sort falls back to in-memory; on Cosmos
+        // MongoDB API it errors with "The index path corresponding to the
+        // specified order-by item is excluded" when `/createdAt` isn't in the
+        // indexing policy. Adding this index here makes a freshly restored
+        // Cosmos account functionally equivalent to the source for this flow,
+        // which is what the backup-validate Tier 2 drill caught (run
+        // 24962804320, 2026-04-26).
+        await this.pendingVerificationsCollection.createIndex({ email: 1, createdAt: -1 });
+        await this.pendingVerificationsCollection.createIndex({ email: 1, codeHash: 1 });
+        // TTL index — same pattern: create is idempotent, drop is not safe on restored accounts.
+        await this.pendingVerificationsCollection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+        await this.webhookEventsCollection.createIndex({ eventId: 1 }, { unique: true });
+        await this.webhookEventsCollection.createIndex({ type: 1 });
+        await this.webhookEventsCollection.createIndex({ receivedAt: -1 });
+        await this.partnerDiscountsCollection.createIndex({ type: 1, match: 1 }, { unique: true });
+        await this.partnerDiscountsCollection.createIndex({ active: 1 });
+        try {
+            await this.managerTeamsCollection.createIndex({ managerId: 1, memberId: 1 }, { unique: true });
+        }
+        catch (e) { /* already exists */ }
+        await this.managerTeamsCollection.createIndex({ memberId: 1 }).catch(() => { });
+        // Issue #540: manager-to-persona seat assignments.
+        await this.aiHubManagerAssignmentsCollection.createIndex({ workspaceId: 1, userKey: 1, personaKey: 1 }, { unique: true }).catch(() => { });
+        await this.aiHubManagerAssignmentsCollection.createIndex({ workspaceId: 1, personaKey: 1 }).catch(() => { });
+        // Quality scores collection — no TTL (retained for full program duration)
+        await this.qualityScoresCollection.createIndex({ userId: 1, jobName: 1, createdAt: -1 }).catch(() => { });
+        await this.qualityScoresCollection.createIndex({ jobName: 1, createdAt: -1 }).catch(() => { });
+        // [OPTIMIZATION] Covers getQualityScorecard per-stage queries:
+        // find({ userId, stageCategory, createdAt: {$gte:...} }).sort({ createdAt: 1 })
+        // Without this index each stage loop hit a full collection scan, causing N+1
+        // fan-out timeouts when loading 13 team members' scorecards in parallel.
+        await this.qualityScoresCollection.createIndex({ userId: 1, stageCategory: 1, createdAt: -1 }).catch(() => { });
+        await this.personaEntitlementsCollection.createIndex({ workspaceId: 1, personaKey: 1, hireMode: 1 }, { unique: true }).catch(() => { });
+        await this.personaEntitlementsCollection.createIndex({ stripeCustomerId: 1, status: 1 }).catch(() => { });
+        await this.personaEntitlementsCollection.createIndex({ stripeSubscriptionId: 1 }).catch(() => { });
+        await this.personaEntitlementsCollection.createIndex({ userId: 1, status: 1 }).catch(() => { });
+        // Issue #359 — OAuth-first login indices.
+        await this.authSessionsCollection.createIndex({ sessionId: 1 }, { unique: true }).catch(() => { });
+        await this.authSessionsCollection.createIndex({ userId: 1, revoked: 1 }).catch(() => { });
+        // TTL — sessions auto-expire 30d after creation. createIndex is idempotent.
+        await this.authSessionsCollection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 }).catch(() => { });
+        await this.pendingOAuthCollection.createIndex({ pendingId: 1 }, { unique: true }).catch(() => { });
+        // TTL — 10-min round-trip window.
+        await this.pendingOAuthCollection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 }).catch(() => { });
+        await this.auditLogCollection.createIndex({ sequence: 1 }).catch(() => { });
+        await this.auditLogCollection.createIndex({ userId: 1, ts: -1 }).catch(() => { });
+        await this.auditLogCollection.createIndex({ ts: -1 }).catch(() => { });
+    }
+    async createSession(session) {
+        if (!this.sessionsCollection)
+            throw new Error('DB not connected');
+        await this.sessionsCollection.replaceOne({ sessionId: session.sessionId }, {
+            ...session,
+            repo: sanitizeSessionRepoContext(session.repo)
+        }, { upsert: true });
+    }
+    async updateSessionActivity(sessionId, lastActive) {
+        if (!this.sessionsCollection)
+            return; // Fail silently
+        const updateDoc = { $set: { lastActive } };
+        await this.sessionsCollection.updateOne({ sessionId }, updateDoc);
+    }
+    // ─── Issue #563: shared organization context (FRAIM-cloud backend) ──────
+    async getOrgArtifacts(orgId) {
+        if (!this.orgArtifactsCollection)
+            throw new Error('DB not connected');
+        return await this.orgArtifactsCollection.find({ orgId }).toArray();
+    }
+    async upsertOrgArtifact(record) {
+        if (!this.orgArtifactsCollection)
+            throw new Error('DB not connected');
+        const { _id, ...replacement } = record;
+        await this.orgArtifactsCollection.replaceOne({ orgId: record.orgId, relativePath: record.relativePath }, replacement, { upsert: true });
+    }
+    async appendOrgAuditEntry(entry) {
+        if (!this.orgAuditCollection)
+            throw new Error('DB not connected');
+        await this.orgAuditCollection.insertOne(entry);
+    }
+    async getOrgAuditEntries(orgId) {
+        if (!this.orgAuditCollection)
+            throw new Error('DB not connected');
+        return await this.orgAuditCollection.find({ orgId }).sort({ at: -1 }).toArray();
+    }
+    async verifyApiKey(key) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        // Return the key regardless of isActive/status — the auth middleware
+        // is responsible for checking expiry and returning the right HTTP status.
+        return await this.keysCollection.findOne({ key });
+    }
+    async getActiveSessionByApiKey(key) {
+        if (!this.keysCollection || !this.sessionsCollection)
+            throw new Error('DB not connected');
+        // 1. Get user for this key
+        const apiKeyData = await this.verifyApiKey(key);
+        if (!apiKeyData)
+            return null;
+        // 2. Get latest session for this user (within last 24h)
+        const dayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
+        const session = await this.sessionsCollection.findOne({ userId: apiKeyData.userId, lastActive: { $gt: dayAgo } }, { sort: { lastActive: -1 } });
+        return session;
+    }
+    async getSessionByApiKeyAndSessionId(key, sessionId) {
+        if (!this.keysCollection || !this.sessionsCollection)
+            throw new Error('DB not connected');
+        const apiKeyData = await this.verifyApiKey(key);
+        if (!apiKeyData)
+            return null;
+        const dayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
+        const session = await this.sessionsCollection.findOne({
+            sessionId,
+            userId: apiKeyData.userId,
+            lastActive: { $gt: dayAgo }
+        });
+        return session;
+    }
+    async createAuthSession(input) {
+        if (!this.authSessionsCollection)
+            throw new Error('DB not connected');
+        const now = new Date();
+        const session = {
+            sessionId: input.sessionId,
+            userId: input.userId,
+            authMethod: input.authMethod,
+            createdAt: now,
+            lastSeenAt: now,
+            expiresAt: new Date(now.getTime() + FraimDbService.AUTH_SESSION_TTL_MS),
+            revoked: false,
+            revokedAt: null,
+            userAgent: input.userAgent,
+            ip: input.ip,
+        };
+        await this.authSessionsCollection.insertOne(session);
+        return session;
+    }
+    async getAuthSession(sessionId) {
+        if (!this.authSessionsCollection)
+            throw new Error('DB not connected');
+        return await this.authSessionsCollection.findOne({ sessionId });
+    }
+    async touchAuthSession(sessionId) {
+        if (!this.authSessionsCollection)
+            return;
+        await this.authSessionsCollection.updateOne({ sessionId, revoked: false }, { $set: { lastSeenAt: new Date() } });
+    }
+    async revokeAuthSession(sessionId) {
+        if (!this.authSessionsCollection)
+            throw new Error('DB not connected');
+        const result = await this.authSessionsCollection.updateOne({ sessionId, revoked: false }, { $set: { revoked: true, revokedAt: new Date() } });
+        return result.modifiedCount > 0;
+    }
+    async revokeAllAuthSessionsForUser(userId, exceptSessionId) {
+        if (!this.authSessionsCollection)
+            throw new Error('DB not connected');
+        const filter = { userId, revoked: false };
+        if (exceptSessionId)
+            filter.sessionId = { $ne: exceptSessionId };
+        const result = await this.authSessionsCollection.updateMany(filter, { $set: { revoked: true, revokedAt: new Date() } });
+        return result.modifiedCount;
+    }
+    async listActiveAuthSessionsForUser(userId) {
+        if (!this.authSessionsCollection)
+            throw new Error('DB not connected');
+        const now = new Date();
+        return await this.authSessionsCollection
+            .find({ userId, revoked: false, expiresAt: { $gt: now } })
+            .sort({ lastSeenAt: -1 })
+            .toArray();
+    }
+    async countTotalAuthSessionsForUser(userId) {
+        if (!this.authSessionsCollection)
+            throw new Error('DB not connected');
+        return await this.authSessionsCollection.countDocuments({ userId });
+    }
+    async createPendingOAuth(input) {
+        if (!this.pendingOAuthCollection)
+            throw new Error('DB not connected');
+        const now = new Date();
+        await this.pendingOAuthCollection.insertOne({
+            ...input,
+            createdAt: now,
+            expiresAt: new Date(now.getTime() + FraimDbService.PENDING_OAUTH_TTL_MS),
+        });
+    }
+    async consumePendingOAuth(pendingId) {
+        if (!this.pendingOAuthCollection)
+            throw new Error('DB not connected');
+        const now = new Date();
+        const result = await this.pendingOAuthCollection.findOneAndDelete({
+            pendingId,
+            expiresAt: { $gt: now },
+        });
+        return result?.value ?? result ?? null;
+    }
+    // ───────────────────────────────────────────────────────────────────────
+    // Issue #359 — Audit log persistence
+    // ───────────────────────────────────────────────────────────────────────
+    async appendAuditRecord(record) {
+        if (!this.auditLogCollection)
+            throw new Error('DB not connected');
+        await this.auditLogCollection.insertOne(record);
+    }
+    async listAuditRecordsForUser(userId, sinceMs, limit) {
+        if (!this.auditLogCollection)
+            throw new Error('DB not connected');
+        const since = new Date(Date.now() - sinceMs);
+        return await this.auditLogCollection
+            .find({ userId, ts: { $gte: since } })
+            .sort({ ts: -1 })
+            .limit(limit)
+            .toArray();
+    }
+    // ───────────────────────────────────────────────────────────────────────
+    // Issue #359 — Identity helpers
+    // ───────────────────────────────────────────────────────────────────────
+    async rotateApiKey(currentKey, newKey) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        const existing = await this.keysCollection.findOne({ key: currentKey });
+        if (!existing)
+            return false;
+        await this.keysCollection.insertOne({
+            ...existing,
+            _id: undefined,
+            key: newKey,
+            createdAt: new Date(),
+            isActive: true,
+        });
+        await this.keysCollection.updateOne({ key: currentKey }, { $set: { isActive: false, status: 'expired' } });
+        return true;
+    }
+    async listApiKeys() {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        return await this.keysCollection.find({}).toArray();
+    }
+    async createApiKey(data) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        await this.keysCollection.insertOne({
+            ...data,
+            isActive: true,
+            createdAt: new Date()
+        });
+    }
+    async revokeApiKey(key) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        const result = await this.keysCollection.updateOne({ key }, { $set: { isActive: false } });
+        return result.matchedCount > 0;
+    }
+    buildApiKeyTargetQuery(keys, userIds, labels = []) {
+        const uniqueKeys = [...new Set(keys.filter(Boolean))];
+        const uniqueUserIds = normalizeUserIds(userIds);
+        const uniqueLabels = normalizeLabels(labels);
+        const queryFilters = [];
+        if (uniqueKeys.length) {
+            queryFilters.push({ key: { $in: uniqueKeys } });
+        }
+        if (uniqueUserIds.length) {
+            queryFilters.push({ userId: { $in: uniqueUserIds } });
+        }
+        if (uniqueLabels.length) {
+            queryFilters.push({ $or: uniqueLabels.map(buildLabelMatch) });
+        }
+        if (queryFilters.length === 0) {
+            return { query: { _id: { $exists: false } }, uniqueKeys, uniqueUserIds, uniqueLabels };
+        }
+        return {
+            query: queryFilters.length === 1 ? queryFilters[0] : { $or: queryFilters },
+            uniqueKeys,
+            uniqueUserIds,
+            uniqueLabels
+        };
+    }
+    async updateApiKeyExpirations(keys, userIds, expiresAt, labels = []) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        const { query, uniqueKeys, uniqueUserIds, uniqueLabels } = this.buildApiKeyTargetQuery(keys, userIds, labels);
+        const existingKeys = await this.keysCollection
+            .find(query)
+            .toArray();
+        const updatedKeys = [];
+        const updatedUserIds = new Set();
+        const foundKeys = new Set(existingKeys.map((record) => record.key));
+        const foundUserIds = new Set(existingKeys.map((record) => record.userId.toLowerCase()));
+        const missingKeys = uniqueKeys.filter((key) => !foundKeys.has(key));
+        const missingUserIds = uniqueUserIds.filter((userId) => !foundUserIds.has(userId));
+        const nextStatus = expiresAt && expiresAt.getTime() <= Date.now() ? 'expired' : 'active';
+        for (const record of existingKeys) {
+            const status = record.status === 'suspended' ? 'suspended' : nextStatus;
+            const update = {
+                expiresAt,
+                status
+            };
+            if (record.tier === 'paid-subscription') {
+                update.currentPeriodEnd = expiresAt;
+            }
+            await this.keysCollection.updateOne({ key: record.key }, { $set: update });
+            updatedKeys.push(record.key);
+            updatedUserIds.add(record.userId);
+        }
+        return {
+            updatedKeys,
+            missingKeys,
+            updatedUserIds: [...updatedUserIds],
+            missingUserIds,
+            matchedLabels: uniqueLabels
+        };
+    }
+    async updateApiKeyLabels(keys, userIds, labels, operation) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        const normalizedLabels = normalizeLabels(labels);
+        if (normalizedLabels.length === 0) {
+            throw new Error('At least one label is required');
+        }
+        const { query, uniqueKeys, uniqueUserIds } = this.buildApiKeyTargetQuery(keys, userIds);
+        const existingKeys = await this.keysCollection.find(query).toArray();
+        const updatedKeys = [];
+        const updatedUserIds = new Set();
+        const foundKeys = new Set(existingKeys.map((record) => record.key));
+        const foundUserIds = new Set(existingKeys.map((record) => record.userId.toLowerCase()));
+        const missingKeys = uniqueKeys.filter((key) => !foundKeys.has(key));
+        const missingUserIds = uniqueUserIds.filter((userId) => !foundUserIds.has(userId));
+        for (const record of existingKeys) {
+            const nextLabels = operation === 'add'
+                ? mergeLabels(record.labels, normalizedLabels)
+                : removeLabels(record.labels, normalizedLabels);
+            await this.keysCollection.updateOne({ key: record.key }, { $set: { labels: nextLabels } });
+            updatedKeys.push(record.key);
+            updatedUserIds.add(record.userId);
+        }
+        return {
+            updatedKeys,
+            missingKeys,
+            updatedUserIds: [...updatedUserIds],
+            missingUserIds,
+            labels: normalizedLabels
+        };
+    }
+    /**
+     * Generates a cryptographically secure API key
+     */
+    generateApiKey(userId, orgId) {
+        const crypto = require('crypto');
+        const prefix = 'fraim_';
+        // 128-bit entropy keeps keys strong while being shorter/easier to handle.
+        const random = crypto.randomBytes(16).toString('hex'); // 32 characters
+        return `${prefix}${random}`;
+    }
+    async createWebsiteSignup(signup) {
+        if (!this.signupsCollection)
+            throw new Error('DB not connected');
+        try {
+            await this.signupsCollection.insertOne(signup);
+        }
+        catch (error) {
+            if (error.code === 11000) {
+                throw new Error('Email already registered');
+            }
+            throw error;
+        }
+    }
+    async getWebsiteSignups(limit = 100) {
+        if (!this.signupsCollection)
+            throw new Error('DB not connected');
+        return await this.signupsCollection.find({})
+            .sort({ timestamp: -1 })
+            .limit(limit)
+            .toArray();
+    }
+    async getSignupByEmail(email) {
+        if (!this.signupsCollection)
+            throw new Error('DB not connected');
+        return await this.signupsCollection.findOne({ email });
+    }
+    /** Get existing API key by userId (email for self-serve) */
+    async getApiKeyByUserId(userId, activeOnly = true) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const query = { userId };
+        if (activeOnly) {
+            // Match active status OR legacy isActive:true with no status field.
+            query.$or = [
+                { status: 'active' },
+                { status: { $exists: false }, isActive: true }
+            ];
+        }
+        return await this.db.collection('fraim_api_keys').findOne(query);
+    }
+    async createAccessToken(data) {
+        if (!this.accessTokensCollection)
+            throw new Error('DB not connected');
+        await this.accessTokensCollection.insertOne(data);
+    }
+    async getAccessToken(token) {
+        if (!this.accessTokensCollection)
+            throw new Error('DB not connected');
+        const doc = await this.accessTokensCollection.findOne({
+            token,
+            expiresAt: { $gt: new Date() }
+        });
+        return doc;
+    }
+    async markAccessTokenUsedForInstaller(token) {
+        if (!this.accessTokensCollection)
+            throw new Error('DB not connected');
+        const result = await this.accessTokensCollection.updateOne({ token }, { $set: { usedForInstaller: true } });
+        return result.matchedCount > 0;
+    }
+    async createSalesInquiry(inquiry) {
+        if (!this.salesCollection)
+            throw new Error('DB not connected');
+        await this.salesCollection.insertOne(inquiry);
+    }
+    async getSalesInquiries(limit = 100) {
+        if (!this.salesCollection)
+            throw new Error('DB not connected');
+        return await this.salesCollection.find({})
+            .sort({ timestamp: -1 })
+            .limit(limit)
+            .toArray();
+    }
+    // ========== Pending Verification Methods (Email Code / Verification Flow) ==========
+    async createPendingVerification(data) {
+        if (!this.pendingVerificationsCollection)
+            throw new Error('DB not connected');
+        await this.pendingVerificationsCollection.insertOne(data);
+    }
+    async getPendingVerification(token) {
+        if (!this.pendingVerificationsCollection)
+            throw new Error('DB not connected');
+        return await this.pendingVerificationsCollection.findOne({
+            token,
+            expiresAt: { $gt: new Date() },
+            verified: false
+        });
+    }
+    /**
+     * Return the pending-verification row regardless of verified/expired state.
+     */
+    async getPendingVerificationRaw(token) {
+        if (!this.pendingVerificationsCollection)
+            throw new Error('DB not connected');
+        return await this.pendingVerificationsCollection.findOne({ token });
+    }
+    async markVerificationUsed(token) {
+        if (!this.pendingVerificationsCollection)
+            throw new Error('DB not connected');
+        const result = await this.pendingVerificationsCollection.updateOne({ token }, {
+            $set: {
+                verified: true,
+                usedAt: new Date()
+            }
+        });
+        return result.matchedCount > 0;
+    }
+    async consumePendingVerificationByCode(email, codeHash) {
+        if (!this.pendingVerificationsCollection)
+            throw new Error('DB not connected');
+        const now = new Date();
+        const row = await this.pendingVerificationsCollection.findOne({
+            email: email.toLowerCase(),
+            codeHash,
+            expiresAt: { $gt: now },
+            verified: false
+        });
+        if (!row)
+            return null;
+        const result = await this.pendingVerificationsCollection.updateOne({ token: row.token, verified: false }, {
+            $set: {
+                verified: true,
+                usedAt: new Date()
+            }
+        });
+        return result.matchedCount > 0 ? row : null;
+    }
+    // ========== API Key Extended Methods (Expiration, Suspension, etc.) ==========
+    async getApiKeyByKey(key) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        return await this.keysCollection.findOne({ key });
+    }
+    async updateApiKey(key, update) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        const result = await this.keysCollection.updateOne({ key }, { $set: update });
+        return result.matchedCount > 0;
+    }
+    async updateApiKeyLastUsed(key) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        await this.keysCollection.updateOne({ key }, {
+            $set: { lastUsedAt: new Date() },
+            $inc: { apiCallCount: 1 }
+        });
+    }
+    async getApiKeyByStripeSubscriptionId(subscriptionId) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        return await this.keysCollection.findOne({ stripeSubscriptionId: subscriptionId });
+    }
+    async getApiKeyByStripeCustomerId(customerId) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        return await this.keysCollection.findOne({ stripeCustomerId: customerId });
+    }
+    async getApiKeyByWorkspaceId(workspaceId, activeOnly = true) {
+        if (!this.keysCollection)
+            throw new Error('DB not connected');
+        const query = { workspaceId };
+        if (activeOnly) {
+            query.$or = [
+                { status: 'active' },
+                { status: { $exists: false }, isActive: true }
+            ];
+        }
+        return await this.keysCollection.findOne(query);
+    }
+    async getPersonaEntitlement(workspaceId, personaKey, hireMode) {
+        if (!this.personaEntitlementsCollection)
+            throw new Error('DB not connected');
+        const query = { workspaceId, personaKey };
+        if (hireMode) {
+            query.hireMode = hireMode;
+        }
+        return await this.personaEntitlementsCollection.findOne(query, { sort: { updatedAt: -1 } });
+    }
+    async getPersonaEntitlementsByWorkspaceId(workspaceId, activeOnly = true) {
+        if (!this.personaEntitlementsCollection)
+            throw new Error('DB not connected');
+        const query = { workspaceId };
+        if (activeOnly) {
+            query.status = 'active';
+        }
+        return await this.personaEntitlementsCollection.find(query).sort({ personaKey: 1, hireMode: 1 }).toArray();
+    }
+    async listPersonaEntitlementsByStripeCustomerId(customerId) {
+        if (!this.personaEntitlementsCollection)
+            throw new Error('DB not connected');
+        return await this.personaEntitlementsCollection.find({ stripeCustomerId: customerId }).sort({ updatedAt: -1 }).toArray();
+    }
+    async getPersonaEntitlementsByUserId(userId, activeOnly = true) {
+        if (!this.personaEntitlementsCollection)
+            throw new Error('DB not connected');
+        const query = { userId };
+        if (activeOnly) {
+            query.status = 'active';
+        }
+        return await this.personaEntitlementsCollection.find(query).sort({ personaKey: 1, hireMode: 1 }).toArray();
+    }
+    async upsertPersonaEntitlement(entitlement) {
+        if (!this.personaEntitlementsCollection)
+            throw new Error('DB not connected');
+        const now = new Date();
+        await this.personaEntitlementsCollection.updateOne({
+            workspaceId: entitlement.workspaceId,
+            personaKey: entitlement.personaKey,
+            hireMode: entitlement.hireMode
+        }, {
+            $set: {
+                ...entitlement,
+                updatedAt: now
+            },
+            $setOnInsert: {
+                createdAt: now
+            }
+        }, { upsert: true });
+        const stored = await this.getPersonaEntitlement(entitlement.workspaceId, entitlement.personaKey, entitlement.hireMode);
+        if (!stored) {
+            throw new Error(`Failed to upsert persona entitlement for ${entitlement.workspaceId}/${entitlement.personaKey}/${entitlement.hireMode}`);
+        }
+        return stored;
+    }
+    async consumePersonaJobCredit(workspaceId, personaKey) {
+        if (!this.personaEntitlementsCollection)
+            throw new Error('DB not connected');
+        const result = await this.personaEntitlementsCollection.updateOne({
+            workspaceId,
+            personaKey,
+            hireMode: 'job',
+            status: 'active',
+            jobCreditsRemaining: { $gt: 0 }
+        }, {
+            $inc: { jobCreditsRemaining: -1 },
+            $set: { updatedAt: new Date() }
+        });
+        return result.modifiedCount > 0;
+    }
+    // ========== Stripe Webhook Event Tracking (Idempotency) ==========
+    async recordWebhookEvent(event) {
+        if (!this.webhookEventsCollection)
+            throw new Error('DB not connected');
+        try {
+            await this.webhookEventsCollection.insertOne(event);
+        }
+        catch (error) {
+            if (error.code === 11000) {
+                // Duplicate event ID - already processed
+                throw new Error('Webhook event already processed');
+            }
+            throw error;
+        }
+    }
+    async isWebhookEventProcessed(eventId) {
+        if (!this.webhookEventsCollection)
+            throw new Error('DB not connected');
+        const event = await this.webhookEventsCollection.findOne({ eventId, processed: true });
+        return event !== null;
+    }
+    async markWebhookEventProcessed(eventId) {
+        if (!this.webhookEventsCollection)
+            throw new Error('DB not connected');
+        const result = await this.webhookEventsCollection.updateOne({ eventId }, {
+            $set: {
+                processed: true,
+                processedAt: new Date()
+            }
+        });
+        return result.matchedCount > 0;
+    }
+    async markWebhookEventFailed(eventId, error) {
+        if (!this.webhookEventsCollection)
+            throw new Error('DB not connected');
+        const result = await this.webhookEventsCollection.updateOne({ eventId }, {
+            $set: {
+                lastError: error
+            },
+            $inc: {
+                retryCount: 1
+            }
+        });
+        return result.matchedCount > 0;
+    }
+    // ── Partner Discounts ──────────────────────────────────────────────────────
+    /** Look up an active partner discount for the given email.
+     *  Email-level match takes priority over domain-level. */
+    async lookupPartnerDiscount(email) {
+        if (!this.partnerDiscountsCollection)
+            throw new Error('DB not connected');
+        const lower = email.toLowerCase();
+        const domain = lower.split('@')[1];
+        // Email-level first
+        const emailMatch = await this.partnerDiscountsCollection.findOne({ type: 'email', match: lower, active: true });
+        if (emailMatch)
+            return emailMatch;
+        // Domain-level fallback
+        if (domain) {
+            return this.partnerDiscountsCollection.findOne({ type: 'domain', match: domain, active: true });
+        }
+        return null;
+    }
+    async createPartnerDiscount(entry) {
+        if (!this.partnerDiscountsCollection)
+            throw new Error('DB not connected');
+        const result = await this.partnerDiscountsCollection.insertOne(entry);
+        return { ...entry, _id: result.insertedId };
+    }
+    async listPartnerDiscounts() {
+        if (!this.partnerDiscountsCollection)
+            throw new Error('DB not connected');
+        return this.partnerDiscountsCollection.find({}).sort({ createdAt: -1 }).toArray();
+    }
+    async updatePartnerDiscount(id, update) {
+        if (!this.partnerDiscountsCollection)
+            throw new Error('DB not connected');
+        const { ObjectId } = await Promise.resolve().then(() => __importStar(require('mongodb')));
+        const result = await this.partnerDiscountsCollection.updateOne({ _id: new ObjectId(id) }, { $set: update });
+        return result.matchedCount > 0;
+    }
+    async incrementPartnerDiscountUseCount(id) {
+        if (!this.partnerDiscountsCollection)
+            throw new Error('DB not connected');
+        await this.partnerDiscountsCollection.updateOne({ _id: id }, { $inc: { useCount: 1 } });
+    }
+    // ===== USAGE ANALYTICS METHODS =====
+    /**
+     * Log a usage event for analytics tracking
+     */
+    async logUsageEvent(event) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        // Sanitize repository identifier for compliance (C1)
+        const repoIdentifier = (0, git_utils_1.sanitizeRepoIdentifier)(event.repoIdentifier);
+        const usageEvent = {
+            ...event,
+            repoIdentifier,
+            createdAt: new Date()
+        };
+        await collection.insertOne(usageEvent);
+    }
+    /**
+     * Get usage statistics for a given time range and optional filters
+     */
+    async getUsageStats(timeWindow, types, userId, repoIdentifier) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const { startDate, endDate } = this.resolveTimeWindow(timeWindow);
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        const matchStage = {
+            createdAt: this.buildCreatedAtMatch(timeWindow)
+        };
+        if (types && types.length > 0) {
+            matchStage.type = { $in: types };
+        }
+        if (userId) {
+            matchStage.userId = userId;
+        }
+        if (sanitizedRepo) {
+            matchStage.repoIdentifier = sanitizedRepo;
+        }
+        const pipeline = [
+            { $match: matchStage },
+            {
+                $group: {
+                    _id: null,
+                    totalEvents: { $sum: 1 },
+                    successfulEvents: { $sum: { $cond: ['$success', 1, 0] } },
+                    lastEventAt: { $max: '$createdAt' },
+                    eventsByType: {
+                        $push: {
+                            type: '$type',
+                            success: '$success'
+                        }
+                    }
+                }
+            }
+        ];
+        const result = await collection.aggregate(pipeline).toArray();
+        if (result.length === 0) {
+            return {
+                totalEvents: 0,
+                eventsByType: {},
+                successRate: 0,
+                timeRange: { start: startDate, end: endDate },
+                lastEventAt: null
+            };
+        }
+        const data = result[0];
+        const eventsByType = {
+            job: 0,
+            skill: 0,
+            rule: 0,
+            mentoring: 0,
+            session: 0
+        };
+        // Count events by type
+        data.eventsByType.forEach((event) => {
+            eventsByType[event.type] = (eventsByType[event.type] || 0) + 1;
+        });
+        return {
+            totalEvents: data.totalEvents,
+            eventsByType,
+            successRate: data.totalEvents > 0 ? (data.successfulEvents / data.totalEvents) * 100 : 0,
+            timeRange: { start: startDate, end: endDate },
+            lastEventAt: data.lastEventAt ?? null
+        };
+    }
+    async getLatestUsageEventAt(userId, types, repoIdentifier) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        const match = { userId };
+        if (types && types.length > 0) {
+            match.type = { $in: types };
+        }
+        if (sanitizedRepo) {
+            match.repoIdentifier = sanitizedRepo;
+        }
+        const latest = await collection.findOne(match, {
+            sort: { createdAt: -1 },
+            projection: { createdAt: 1 }
+        });
+        return latest?.createdAt ?? null;
+    }
+    /**
+     * Get top components by usage count
+     */
+    async getTopComponents(limit, timeWindow, types, userId, repoIdentifier) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        const matchStage = {
+            createdAt: this.buildCreatedAtMatch(timeWindow),
+            ...(userId && { userId }),
+            ...(sanitizedRepo && { repoIdentifier: sanitizedRepo })
+        };
+        if (types && types.length > 0) {
+            matchStage.type = { $in: types };
+        }
+        // When counting job events, exclude explicit complete events so each run is
+        // counted once. A completed run emits both start and complete; without this
+        // filter the dashboard would show double the runs count vs the runs list.
+        // Old-path events (no args.action field) pass through because $ne includes
+        // documents where the field is absent.
+        if (!types || types.includes('job')) {
+            matchStage['args.action'] = { $ne: 'complete' };
+        }
+        const pipeline = [
+            {
+                $match: matchStage
+            },
+            {
+                $group: {
+                    _id: { name: '$name', type: '$type' },
+                    category: { $first: '$category' },
+                    count: { $sum: 1 },
+                    successfulEvents: { $sum: { $cond: ['$success', 1, 0] } },
+                    lastUsed: { $max: '$createdAt' }
+                }
+            },
+            { $sort: { count: -1 } },
+            { $limit: limit }
+        ];
+        const results = await collection.aggregate(pipeline).toArray();
+        return results.map(result => ({
+            name: result._id.name,
+            type: result._id.type,
+            category: result.category,
+            count: result.count,
+            successRate: result.count > 0 ? (result.successfulEvents / result.count) * 100 : 0,
+            lastUsed: result.lastUsed
+        }));
+    }
+    /**
+     * Get usage pattern for a specific user (API key)
+     */
+    async getUserUsagePattern(userId) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const pipeline = [
+            { $match: { userId } },
+            {
+                $group: {
+                    _id: null,
+                    totalEvents: { $sum: 1 },
+                    usageByType: {
+                        $push: '$type'
+                    },
+                    lastActivity: { $max: '$createdAt' },
+                    components: {
+                        $push: {
+                            name: '$name',
+                            type: '$type',
+                            success: '$success'
+                        }
+                    }
+                }
+            }
+        ];
+        const result = await collection.aggregate(pipeline).toArray();
+        if (result.length === 0) {
+            return {
+                userId,
+                totalEvents: 0,
+                favoriteComponents: [],
+                usageByType: {},
+                lastActivity: new Date()
+            };
+        }
+        const data = result[0];
+        // Count usage by type
+        const usageByType = {
+            job: 0,
+            skill: 0,
+            rule: 0,
+            mentoring: 0,
+            session: 0
+        };
+        data.usageByType.forEach((type) => {
+            usageByType[type] = (usageByType[type] || 0) + 1;
+        });
+        // Get favorite components (top 5)
+        const componentCounts = {};
+        data.components.forEach((comp) => {
+            const key = `${comp.name}:${comp.type}`;
+            if (!componentCounts[key]) {
+                componentCounts[key] = {
+                    name: comp.name,
+                    type: comp.type,
+                    count: 0,
+                    successRate: 0,
+                    lastUsed: new Date()
+                };
+            }
+            componentCounts[key].count++;
+            if (comp.success)
+                componentCounts[key].successRate++;
+        });
+        // Calculate averages and sort
+        const favoriteComponents = Object.values(componentCounts)
+            .map(comp => ({
+            ...comp,
+            successRate: comp.count > 0 ? (comp.successRate / comp.count) * 100 : 0
+        }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 5);
+        return {
+            userId,
+            totalEvents: data.totalEvents,
+            favoriteComponents,
+            usageByType,
+            lastActivity: data.lastActivity
+        };
+    }
+    /**
+     * Clean up old usage events based on retention policy
+     */
+    async cleanupOldUsageEvents(retentionDays) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const cutoffDate = new Date();
+        cutoffDate.setDate(cutoffDate.getDate() - retentionDays);
+        const result = await collection.deleteMany({
+            createdAt: { $lt: cutoffDate }
+        });
+        return result.deletedCount || 0;
+    }
+    /**
+     * Get aggregated job runs over time for timeline bubble chart
+     */
+    async getJobRunsOverTime(timeWindow, userId, dateUnit, repoIdentifier) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const { days } = this.resolveTimeWindow(timeWindow);
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        const matchStage = {
+            type: 'job',
+            // Exclude explicit complete events so each run is counted once (at start).
+            // Old-path events have no args.action and are included by $ne.
+            'args.action': { $ne: 'complete' },
+            createdAt: this.buildCreatedAtMatch(timeWindow)
+        };
+        if (userId) {
+            matchStage.userId = userId;
+        }
+        if (sanitizedRepo) {
+            matchStage.repoIdentifier = sanitizedRepo;
+        }
+        // Determine group format based on dateUnit or auto-rollup
+        let format = '%Y-%m-%d';
+        if (dateUnit === 'week') {
+            format = '%Y-%U';
+        }
+        else if (dateUnit === 'month') {
+            format = '%Y-%m';
+        }
+        else if (!dateUnit) {
+            // Auto-rollup logic
+            if (days > 60) {
+                format = '%Y-%m';
+            }
+            else if (days > 14) {
+                format = '%Y-%U';
+            }
+        }
+        const pipeline = [
+            { $match: matchStage },
+            {
+                $group: {
+                    _id: {
+                        date: { $dateToString: { format, date: '$createdAt' } },
+                        name: '$name'
+                    },
+                    category: { $first: '$category' },
+                    count: { $sum: 1 },
+                    successRate: { $avg: { $cond: ['$success', 100, 0] } },
+                    minDate: { $min: '$createdAt' },
+                    maxDate: { $max: '$createdAt' },
+                    avgInputTokens: { $avg: { $ifNull: ['$tokenSnapshot.inputTokens', null] } },
+                    avgOutputTokens: { $avg: { $ifNull: ['$tokenSnapshot.outputTokens', null] } },
+                    avgCostUsd: { $avg: { $ifNull: ['$tokenSnapshot.costUsd', null] } }
+                }
+            },
+            {
+                $project: {
+                    _id: 0,
+                    // Use the latest activity timestamp within the rolled-up bucket so
+                    // timeline labels line up with "last active" and top-jobs data.
+                    date: '$maxDate',
+                    name: '$_id.name',
+                    category: 1,
+                    count: 1,
+                    successRate: 1,
+                    avgDurationMs: {
+                        $cond: [
+                            { $and: [{ $gt: ['$count', 1] }, { $ne: ['$maxDate', null] }] },
+                            { $divide: [{ $subtract: ['$maxDate', '$minDate'] }, '$count'] },
+                            null
+                        ]
+                    },
+                    avgInputTokens: 1,
+                    avgOutputTokens: 1,
+                    avgCostUsd: 1
+                }
+            },
+            { $sort: { date: 1 } }
+        ];
+        return await collection.aggregate(pipeline).toArray();
+    }
+    async getComponentTrend(componentName, componentType, timeWindow, userId, dateUnit, repoIdentifier) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const { days } = this.resolveTimeWindow(timeWindow);
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        const matchStage = {
+            name: componentName,
+            type: componentType,
+            createdAt: this.buildCreatedAtMatch(timeWindow)
+        };
+        if (userId) {
+            matchStage.userId = userId;
+        }
+        if (sanitizedRepo) {
+            matchStage.repoIdentifier = sanitizedRepo;
+        }
+        // Determine group format based on dateUnit or auto-rollup
+        let format = '%Y-%m-%d';
+        if (dateUnit === 'week') {
+            format = '%Y-%U';
+        }
+        else if (dateUnit === 'month') {
+            format = '%Y-%m';
+        }
+        else if (!dateUnit) {
+            // Auto-rollup logic
+            if (days > 60) {
+                format = '%Y-%m';
+            }
+            else if (days > 14) {
+                format = '%Y-%U';
+            }
+        }
+        const pipeline = [
+            { $match: matchStage },
+            {
+                $group: {
+                    _id: { $dateToString: { format, date: '$createdAt' } },
+                    count: { $sum: 1 },
+                    successfulEvents: { $sum: { $cond: ['$success', 1, 0] } }
+                }
+            },
+            { $sort: { _id: 1 } }
+        ];
+        const results = await collection.aggregate(pipeline).toArray();
+        const dataPoints = results.map(result => ({
+            date: new Date(result._id),
+            count: result.count,
+            successRate: result.count > 0 ? (result.successfulEvents / result.count) * 100 : 0
+        }));
+        // Calculate growth rate
+        const firstCount = dataPoints.length > 0 ? dataPoints[0].count : 0;
+        const lastCount = dataPoints.length > 0 ? dataPoints[dataPoints.length - 1].count : 0;
+        const totalGrowth = firstCount > 0 ? ((lastCount - firstCount) / firstCount) * 100 : 0;
+        return {
+            name: componentName,
+            type: componentType,
+            dataPoints,
+            totalGrowth
+        };
+    }
+    /**
+     * Initialize usage events collection with proper indexes
+     */
+    async initializeUsageEventsCollection() {
+        if (!this.db)
+            return;
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        // Create TTL index for automatic cleanup (90 days default)
+        await collection.createIndex({ createdAt: 1 }, { expireAfterSeconds: 90 * 24 * 60 * 60 } // 90 days in seconds
+        );
+        // Standard indexes
+        await collection.createIndex({ userId: 1, createdAt: -1 });
+        await collection.createIndex({ type: 1, createdAt: -1 });
+        await collection.createIndex({ name: 1, type: 1, createdAt: -1 });
+        await collection.createIndex({ sessionId: 1 });
+        // [OPTIMIZATION] Added for dashboard performance
+        await collection.createIndex({ userId: 1, name: 1, type: 1, createdAt: -1 });
+        await collection.createIndex({ userId: 1, success: 1, createdAt: -1 });
+        // [OPTIMIZATION] Covers heatmap + analytics type-filtered queries:
+        // getUsageForHeatmap({ userId, type: {$in:[...]}, createdAt: {$gte:...} })
+        // getUsageStats / getTopComponents when filtering by userId + type + createdAt
+        await collection.createIndex({ userId: 1, type: 1, createdAt: -1 });
+        // [OPTIMIZATION] Covers job-level timeline + token-usage queries:
+        // getJobRunTimeline({ jobId }) and getTokenUsageByJob({ jobId })
+        await collection.createIndex({ jobId: 1 });
+        // [OPTIMIZATION] Added for repo-level analytics performance
+        await collection.createIndex({ repoIdentifier: 1, createdAt: -1 });
+        await collection.createIndex({ userId: 1, repoIdentifier: 1, createdAt: -1 });
+    }
+    /**
+     * Get unique repositories that have generated telemetry for a user
+     */
+    async getUniqueRepos(userId) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const usageCollection = this.db.collection(this.usageEventsCollectionName);
+        const qualityCollection = this.db.collection('fraim_quality_scores');
+        const [usageRepos, qualityRepos] = await Promise.all([
+            usageCollection.distinct('repoIdentifier', {
+                userId,
+                repoIdentifier: { $type: 'string' }
+            }),
+            qualityCollection.distinct('repoIdentifier', {
+                userId,
+                repoIdentifier: { $type: 'string' }
+            })
+        ]);
+        const all = [...usageRepos, ...qualityRepos];
+        return Array.from(new Set(all
+            .map((repo) => (0, git_utils_1.sanitizeRepoIdentifier)(repo))
+            .filter((r) => typeof r === 'string'))).sort();
+    }
+    resolveTimeWindow(timeWindow) {
+        if (typeof timeWindow === 'number') {
+            const endDate = new Date();
+            const startDate = new Date(endDate.getTime() - timeWindow * 24 * 60 * 60 * 1000);
+            return { startDate, endDate, days: timeWindow };
+        }
+        const startDate = new Date(timeWindow.startDate);
+        const endDate = timeWindow.endDate ? new Date(timeWindow.endDate) : new Date();
+        const days = timeWindow.days ?? Math.max(1, Math.ceil((endDate.getTime() - startDate.getTime()) / (24 * 60 * 60 * 1000)) + 1);
+        return { startDate, endDate, days };
+    }
+    buildCreatedAtMatch(timeWindow) {
+        const { startDate, endDate } = this.resolveTimeWindow(timeWindow);
+        return {
+            $gte: startDate,
+            ...(endDate ? { $lte: endDate } : {})
+        };
+    }
+    buildQualityCreatedAtFilter(periodDays, startDate, endDate) {
+        if (startDate || endDate) {
+            const effectiveStart = startDate ?? new Date(0);
+            const effectiveEnd = endDate ?? new Date();
+            return { createdAt: { $gte: effectiveStart, $lte: effectiveEnd } };
+        }
+        if (typeof periodDays === 'number') {
+            return { createdAt: { $gte: new Date(Date.now() - periodDays * 24 * 60 * 60 * 1000) } };
+        }
+        return {};
+    }
+    async close() {
+        FraimDbService.refCount = Math.max(0, FraimDbService.refCount - 1);
+        if (FraimDbService.refCount === 0 && FraimDbService.client) {
+            await FraimDbService.client.close();
+            FraimDbService.client = undefined;
+            FraimDbService.db = undefined;
+            FraimDbService.connectionPromise = undefined;
+        }
+    }
+    getClient() {
+        return FraimDbService.client;
+    }
+    async getDb() {
+        if (!this.db) {
+            await this.connect();
+        }
+        if (!this.db) {
+            throw new Error('DB not connected');
+        }
+        return this.db;
+    }
+    /**
+     * Aggregate usage events for the personal brain heatmap.
+     * Returns per-component invocation counts within the optional time window.
+     */
+    async getUsageForHeatmap(userId, windowDays) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const matchStage = {
+            userId,
+            type: { $in: ['skill', 'job', 'mentoring'] },
+        };
+        if (windowDays !== null) {
+            const startDate = new Date();
+            startDate.setDate(startDate.getDate() - windowDays);
+            matchStage.createdAt = { $gte: startDate };
+        }
+        const pipeline = [
+            { $match: matchStage },
+            {
+                $group: {
+                    _id: {
+                        id: '$name',
+                        type: '$type',
+                        category: { $ifNull: ['$args.category', 'unknown'] }
+                    },
+                    invocationCount: { $sum: 1 },
+                    lastInvokedAt: { $max: '$createdAt' }
+                }
+            },
+            {
+                $project: {
+                    _id: 0,
+                    id: '$_id.id',
+                    type: '$_id.type',
+                    category: '$_id.category',
+                    invocationCount: 1,
+                    lastInvokedAt: 1
+                }
+            }
+        ];
+        return await collection.aggregate(pipeline).toArray();
+    }
+    // ===== MANAGER TEAMS METHODS =====
+    async addTeamMember(managerId, memberId) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        await this.db.collection('fraim_manager_teams').updateOne({ managerId, memberId }, { $setOnInsert: { managerId, memberId, createdAt: new Date() } }, { upsert: true });
+    }
+    async removeTeamMember(managerId, memberId) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        await this.db.collection('fraim_manager_teams').deleteOne({ managerId, memberId });
+    }
+    /**
+     * Convert a memberId/pattern to a MongoDB $regex string.
+     * Wildcards: '*@ezcorp.com' → '^.*@ezcorp\.com$', '*' → '^.*$'
+     * Literal: 'alice@example.com' → null (no regex needed)
+     */
+    memberIdToRegex(pattern) {
+        if (!pattern.includes('*'))
+            return null;
+        const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+        return `^${escaped}$`;
+    }
+    /**
+     * Returns all resolved team members for a manager.
+     * Wildcard patterns (memberId containing '*') are expanded by querying
+     * fraim_api_keys for all active users whose userId matches the pattern.
+     * The manager themselves is never included in the result.
+     */
+    async getTeamMembers(managerId) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const records = await this.db.collection('fraim_manager_teams').find({ managerId }).toArray();
+        const result = [];
+        const seen = new Set();
+        for (const record of records) {
+            const regex = this.memberIdToRegex(record.memberId);
+            if (!regex) {
+                // Literal member — include as-is (excluding manager themselves)
+                if (record.memberId !== managerId && !seen.has(record.memberId)) {
+                    seen.add(record.memberId);
+                    result.push(record);
+                }
+            }
+            else {
+                // Wildcard pattern — expand against all API keys (any status)
+                const matched = await this.db.collection('fraim_api_keys')
+                    .find({ userId: { $regex: regex, $options: 'i' } })
+                    .toArray();
+                for (const key of matched) {
+                    if (key.userId !== managerId && !seen.has(key.userId)) {
+                        seen.add(key.userId);
+                        result.push({ ...record, memberId: key.userId });
+                    }
+                }
+            }
+        }
+        const memberIds = result.map((record) => record.memberId);
+        if (memberIds.length === 0)
+            return result;
+        const keyRecords = await this.db.collection('fraim_api_keys')
+            .find({ userId: { $in: memberIds } }, { projection: { userId: 1, labels: 1 } })
+            .toArray();
+        const labelsByUserId = new Map(keyRecords.map((record) => [record.userId, normalizeLabels(record.labels || [])]));
+        return result.map((record) => ({
+            ...record,
+            labels: labelsByUserId.get(record.memberId) || []
+        }));
+    }
+    async getManagersForMember(memberId) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        // Exact-match records
+        const explicit = await this.db.collection('fraim_manager_teams')
+            .find({ memberId }).toArray();
+        // Pattern records (memberId contains '*')
+        const patterns = await this.db.collection('fraim_manager_teams')
+            .find({ memberId: { $regex: '\\*' } }).toArray();
+        const managerIds = new Set(explicit.map(r => r.managerId));
+        for (const record of patterns) {
+            const regex = this.memberIdToRegex(record.memberId);
+            if (regex && new RegExp(regex, 'i').test(memberId)) {
+                managerIds.add(record.managerId);
+            }
+        }
+        return Array.from(managerIds);
+    }
+    // ===== AI HUB MANAGER ASSIGNMENTS (Issue #540) =====
+    async getHubManagerAssignments(workspaceId, userKey) {
+        if (!this.aiHubManagerAssignmentsCollection)
+            return [];
+        return this.aiHubManagerAssignmentsCollection.find({ workspaceId, userKey }).toArray();
+    }
+    async addHubManagerAssignment(workspaceId, userKey, personaKey) {
+        if (!this.aiHubManagerAssignmentsCollection)
+            throw new Error('DB not connected');
+        const doc = { workspaceId, userKey, personaKey, assignedAt: new Date() };
+        await this.aiHubManagerAssignmentsCollection.updateOne({ workspaceId, userKey, personaKey }, { $setOnInsert: doc }, { upsert: true });
+        const saved = await this.aiHubManagerAssignmentsCollection.findOne({ workspaceId, userKey, personaKey });
+        return saved;
+    }
+    async removeHubManagerAssignment(workspaceId, userKey, personaKey) {
+        if (!this.aiHubManagerAssignmentsCollection)
+            return;
+        await this.aiHubManagerAssignmentsCollection.deleteOne({ workspaceId, userKey, personaKey });
+    }
+    async countHubManagerAssignments(workspaceId, personaKey) {
+        if (!this.aiHubManagerAssignmentsCollection)
+            return 0;
+        return this.aiHubManagerAssignmentsCollection.countDocuments({ workspaceId, personaKey });
+    }
+    async hasFraimSetup(userId) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const record = await this.db.collection('fraim_api_keys').findOne({ userId }, { projection: { _id: 1 } });
+        return !!record;
+    }
+    // ===== Quality Scores (Issue #251) =====
+    async insertQualityScore(record) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const stageCategory = record.stageCategory ?? quality_evidence_1.QUALITY_REGISTRY[record.jobName]?.stage ?? undefined;
+        const reviewContext = record.reviewContext
+            ? {
+                ...record.reviewContext,
+                repoIdentifier: (0, git_utils_1.sanitizeRepoIdentifier)(record.reviewContext.repoIdentifier)
+            }
+            : undefined;
+        const repoIdentifier = (0, git_utils_1.sanitizeRepoIdentifier)(record.repoIdentifier ?? reviewContext?.repoIdentifier);
+        await this.db.collection('fraim_quality_scores').insertOne({
+            ...record,
+            reviewContext,
+            repoIdentifier,
+            stageCategory,
+            createdAt: record.createdAt ?? new Date()
+        });
+    }
+    async getQualityScores(userId, jobName, limit, repoIdentifier) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const filter = { userId };
+        if (jobName)
+            filter.jobName = jobName;
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        if (sanitizedRepo)
+            filter.repoIdentifier = sanitizedRepo;
+        return this.db.collection('fraim_quality_scores')
+            .find(filter)
+            .sort({ createdAt: 1 }) // chronological for trajectory charts
+            .limit(limit ?? 100)
+            .toArray();
+    }
+    async getLatestQualityScore(userId, jobName, repoIdentifier) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        return this.db.collection('fraim_quality_scores').findOne({ userId, jobName, ...(sanitizedRepo ? { repoIdentifier: sanitizedRepo } : {}) }, { sort: { createdAt: -1 } });
+    }
+    async getQualityScoresByStage(userId, stageCategory, limit, repoIdentifier) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        return this.db.collection('fraim_quality_scores')
+            .find({ userId, stageCategory, ...(sanitizedRepo ? { repoIdentifier: sanitizedRepo } : {}) })
+            .sort({ createdAt: 1 })
+            .limit(limit ?? 100)
+            .toArray();
+    }
+    /**
+     * Build the quality scorecard: one summary per stage for a given user.
+     * Returns all stages (including those with no data) so the UI can show grey tiles.
+     */
+    async getQualityScorecard(userId, repoIdentifier, periodDays, startDate, endDate) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection('fraim_quality_scores');
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        const createdAtFilter = this.buildQualityCreatedAtFilter(periodDays, startDate, endDate);
+        // All stage queries + the gate findOne start concurrently in a single Promise.all.
+        const [stageResults, gateScore] = await Promise.all([
+            Promise.all(quality_evidence_1.ALL_STAGE_CATEGORIES.map(stageCategory => collection
+                .find({ userId, stageCategory, ...(sanitizedRepo ? { repoIdentifier: sanitizedRepo } : {}), ...createdAtFilter })
+                .sort({ createdAt: 1 })
+                .limit(100)
+                .toArray()
+                .then(scores => ({ stageCategory, scores })))),
+            collection.findOne({ userId, jobName: 'triage-customer-needs', ...(sanitizedRepo ? { repoIdentifier: sanitizedRepo } : {}), ...createdAtFilter }, { sort: { createdAt: -1 } }),
+        ]);
+        const stages = stageResults.map(({ stageCategory, scores }) => {
+            // Filter to records that have an actual composite score — some records
+            // (e.g., triage-customer-needs gate decisions) intentionally omit composite
+            // and should not drive the tile's latest-composite rendering.
+            const scoredRecords = scores.filter(s => typeof s.scores?.composite === 'number');
+            if (scoredRecords.length === 0) {
+                return {
+                    stageCategory,
+                    stageName: quality_evidence_1.STAGE_DISPLAY_NAMES[stageCategory] ?? stageCategory,
+                    latestComposite: null,
+                    trend: null,
+                    lastAssessedAt: null,
+                    assessmentCount: 0,
+                    sparkline: [],
+                    latestCoaching: null,
+                    latestGate: null,
+                };
+            }
+            const latest = scoredRecords[scoredRecords.length - 1];
+            const composites = scoredRecords.map(s => s.scores.composite);
+            const sparkline = composites.slice(-10); // last 10 scores
+            // Compute trend
+            let trend = 'stable';
+            if (composites.length >= 3) {
+                const midpoint = Math.floor(composites.length / 2);
+                const firstAvg = composites.slice(0, midpoint).reduce((a, b) => a + b, 0) / midpoint;
+                const secondAvg = composites.slice(midpoint).reduce((a, b) => a + b, 0) / (composites.length - midpoint);
+                if (secondAvg > firstAvg + 0.5)
+                    trend = 'improving';
+                else if (secondAvg < firstAvg - 0.5)
+                    trend = 'declining';
+            }
+            // Attach gate decision for customer-development stage (fetched above in parallel)
+            let latestGate = null;
+            if (stageCategory === 'customer-development' && gateScore?.scores?.gateDecision) {
+                latestGate = {
+                    decision: gateScore.scores.gateDecision,
+                    gaps: gateScore.scores.gaps ?? [],
+                };
+            }
+            return {
+                stageCategory,
+                stageName: quality_evidence_1.STAGE_DISPLAY_NAMES[stageCategory] ?? stageCategory,
+                latestComposite: latest.scores.composite ?? null,
+                trend,
+                lastAssessedAt: latest.createdAt,
+                assessmentCount: scoredRecords.length,
+                sparkline,
+                latestCoaching: latest.scores.coaching ?? null,
+                latestGate,
+            };
+        });
+        return stages;
+    }
+    /**
+     * Get full assessment history for a single stage (tile click detail view).
+     */
+    async getQualityStageDetail(userId, stageCategory, repoIdentifier, periodDays, startDate, endDate) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        const createdAtFilter = this.buildQualityCreatedAtFilter(periodDays, startDate, endDate);
+        const scores = await this.db.collection('fraim_quality_scores')
+            .find({ userId, stageCategory, ...(sanitizedRepo ? { repoIdentifier: sanitizedRepo } : {}), ...createdAtFilter })
+            .sort({ createdAt: 1 })
+            .limit(100)
+            .toArray();
+        const composites = scores.map(s => s.scores.composite ?? 0);
+        const avgComposite = composites.length > 0
+            ? Math.round(composites.reduce((a, b) => a + b, 0) / composites.length * 10) / 10
+            : 0;
+        let trend = 'stable';
+        if (composites.length >= 3) {
+            const midpoint = Math.floor(composites.length / 2);
+            const firstAvg = composites.slice(0, midpoint).reduce((a, b) => a + b, 0) / midpoint;
+            const secondAvg = composites.slice(midpoint).reduce((a, b) => a + b, 0) / (composites.length - midpoint);
+            if (secondAvg > firstAvg + 0.5)
+                trend = 'improving';
+            else if (secondAvg < firstAvg - 0.5)
+                trend = 'declining';
+        }
+        return {
+            stageCategory,
+            assessments: scores.map(s => ({
+                jobName: s.jobName,
+                jobId: s.jobId,
+                composite: s.scores.composite ?? 0,
+                scores: s.scores,
+                coaching: s.scores.coaching ?? '',
+                artifactPath: s.artifactPath,
+                createdAt: s.createdAt,
+            })),
+            count: scores.length,
+            avgComposite,
+            trend,
+        };
+    }
+    async getDominantCategory(userId, days) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const startDate = new Date();
+        startDate.setDate(startDate.getDate() - days);
+        const pipeline = [
+            { $match: { userId, createdAt: { $gte: startDate }, type: 'job', category: { $exists: true, $nin: [null, 'uncategorized'] } } },
+            { $group: { _id: '$category', count: { $sum: 1 } } },
+            { $sort: { count: -1 } },
+            { $limit: 1 }
+        ];
+        const result = await collection.aggregate(pipeline).toArray();
+        if (result.length === 0)
+            return null;
+        return { category: result[0]._id, count: result[0].count };
+    }
+    /**
+     * Get job completion metrics aggregated from usage events.
+     * Uses explicit type:'job' start/complete events for accurate tracking.
+     */
+    async getJobCompletionMetrics(startDate, jobName, userId, repoIdentifier, endDate) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        const createdAtMatch = { $gte: startDate, ...(endDate ? { $lte: endDate } : {}) };
+        // Check if we have explicit job lifecycle events
+        const explicitMatch = { type: 'job', 'args.action': 'start', createdAt: createdAtMatch };
+        if (jobName)
+            explicitMatch.name = jobName;
+        if (userId)
+            explicitMatch.userId = userId;
+        if (sanitizedRepo)
+            explicitMatch.repoIdentifier = sanitizedRepo;
+        const hasExplicit = await collection.countDocuments(explicitMatch) > 0;
+        // Use explicit events if available, fall back to mentoring events for legacy data
+        const matchStage = hasExplicit
+            ? { type: 'job', 'args.action': { $in: ['start', 'complete'] }, createdAt: createdAtMatch }
+            : { type: 'mentoring', createdAt: createdAtMatch };
+        if (jobName)
+            matchStage.name = jobName;
+        if (userId)
+            matchStage.userId = userId;
+        if (sanitizedRepo)
+            matchStage.repoIdentifier = sanitizedRepo;
+        const pipeline = [
+            { $match: matchStage },
+            { $sort: { createdAt: 1 } },
+            {
+                $group: {
+                    _id: { jobName: '$name', jobId: '$jobId' },
+                    startTime: { $min: '$createdAt' },
+                    completeTime: {
+                        $max: {
+                            $cond: [
+                                { $or: [
+                                        { $eq: ['$args.action', 'complete'] },
+                                        { $eq: ['$args.nextPhase', null] }
+                                    ] },
+                                '$createdAt', null
+                            ]
+                        }
+                    },
+                    hasStart: { $first: { $cond: [true, true, false] } },
+                    hasComplete: {
+                        $max: {
+                            $cond: [
+                                { $or: [
+                                        { $eq: ['$args.action', 'complete'] },
+                                        { $eq: ['$args.nextPhase', null] }
+                                    ] },
+                                true, false
+                            ]
+                        }
+                    },
+                    eventCount: { $sum: 1 }
+                }
+            },
+            {
+                $group: {
+                    _id: '$_id.jobName',
+                    totalStarted: { $sum: { $cond: ['$hasStart', 1, 0] } },
+                    totalCompleted: { $sum: { $cond: ['$hasComplete', 1, 0] } },
+                    completionDurations: {
+                        $push: {
+                            $cond: [
+                                { $and: ['$hasStart', '$hasComplete', { $ne: ['$startTime', null] }, { $ne: ['$completeTime', null] }] },
+                                { $subtract: ['$completeTime', '$startTime'] },
+                                null
+                            ]
+                        }
+                    },
+                    // Track last phase for abandoned jobs (started but not completed)
+                    abandonedPhases: {
+                        $push: {
+                            $cond: [
+                                { $and: ['$hasStart', { $not: '$hasComplete' }] },
+                                '$finalPhase',
+                                null
+                            ]
+                        }
+                    }
+                }
+            },
+            {
+                $project: {
+                    jobName: '$_id',
+                    totalStarted: 1,
+                    totalCompleted: 1,
+                    totalAbandoned: { $subtract: ['$totalStarted', '$totalCompleted'] },
+                    completionRate: {
+                        $cond: [
+                            { $gt: ['$totalStarted', 0] },
+                            { $divide: ['$totalCompleted', '$totalStarted'] },
+                            0
+                        ]
+                    },
+                    avgCompletionMs: {
+                        $cond: [
+                            { $gt: [{ $size: '$completionDurations' }, 0] },
+                            { $avg: '$completionDurations' },
+                            null
+                        ]
+                    },
+                    medianIdx: {
+                        $cond: [
+                            { $gt: [{ $size: '$completionDurations' }, 0] },
+                            { $floor: { $divide: [{ $size: '$completionDurations' }, 2] } },
+                            null
+                        ]
+                    },
+                    completionDurations: 1
+                }
+            }
+        ];
+        const results = await collection.aggregate(pipeline).toArray();
+        return results.map(result => {
+            // Calculate median from sorted durations
+            const durations = (result.completionDurations || []).filter((d) => typeof d === 'number').sort((a, b) => a - b);
+            const medianMs = durations.length > 0 ? durations[Math.floor(durations.length / 2)] : undefined;
+            return {
+                jobName: result.jobName,
+                totalRequested: result.totalStarted,
+                totalStarted: result.totalStarted,
+                totalCompleted: result.totalCompleted,
+                totalAbandoned: result.totalStarted - result.totalCompleted,
+                startRate: 1.0,
+                completionRate: result.completionRate,
+                overallRate: result.completionRate,
+                averageCompletionTime: result.avgCompletionMs ?? undefined,
+                medianCompletionTime: medianMs,
+                commonAbandonmentPhases: [],
+                timeRange: { start: startDate, end: new Date() }
+            };
+        });
+    }
+    /**
+     * Get timeline of all events for a specific jobId, ordered chronologically.
+     */
+    async getJobRunTimeline(jobId, userId, jobName) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        let match;
+        if (jobId.startsWith('sess_')) {
+            // Old-path run: jobId is actually a synthetic sess_<sessionId> key.
+            // Query by sessionId so the events (which have no jobId) are found.
+            const sessionId = jobId.slice(5);
+            match = { sessionId };
+            if (userId)
+                match.userId = userId;
+            if (jobName)
+                match.name = jobName;
+        }
+        else {
+            match = { jobId };
+            if (userId)
+                match.userId = userId;
+        }
+        return await collection.aggregate([
+            { $match: match },
+            { $sort: { createdAt: 1 } },
+            {
+                $project: {
+                    _id: 0,
+                    type: 1,
+                    name: 1,
+                    jobPhase: 1,
+                    createdAt: 1,
+                    success: 1,
+                    args: 1,
+                    tokenSnapshot: 1,
+                },
+            },
+        ]).toArray();
+    }
+    /**
+     * Get recent job runs with their start/complete status for a job name.
+     * Falls back to deriving runs from mentoring events for legacy data without explicit job start/complete events.
+     */
+    async getJobRuns(jobName, startDate, userId, limit = 50, repoIdentifier) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
+        // Match all job lifecycle events (including old-path events without args.action)
+        // and mentoring events. Old-path events from usage-collector.ts have args: { job: '<name>' }
+        // with no args.action and no jobId — they must be included so every invocation appears.
+        const match = {
+            $or: [
+                { type: 'job' },
+                { type: 'mentoring' },
+            ],
+            name: jobName,
+            createdAt: { $gte: startDate },
+        };
+        if (userId)
+            match.userId = userId;
+        if (sanitizedRepo)
+            match.repoIdentifier = sanitizedRepo;
+        const pipeline = [
+            { $match: match },
+            { $sort: { createdAt: 1 } },
+            {
+                $group: {
+                    // Old-path events have no jobId. Use sess_<sessionId> as a synthetic key so
+                    // each session forms its own run instead of collapsing all null-jobId events
+                    // from every session into one mega-bucket.
+                    _id: { $ifNull: ['$jobId', { $concat: ['sess_', { $ifNull: ['$sessionId', { $toString: '$_id' }] }] }] },
+                    jobName: { $first: '$name' },
+                    startedAt: { $min: '$createdAt' },
+                    completedAt: {
+                        $max: {
+                            $cond: [
+                                { $or: [
+                                        { $eq: ['$args.action', 'complete'] },
+                                        { $eq: ['$args.nextPhase', null] }
+                                    ] },
+                                '$createdAt', null
+                            ]
+                        }
+                    },
+                    isCompleted: {
+                        $max: {
+                            $cond: [
+                                { $or: [
+                                        { $eq: ['$args.action', 'complete'] },
+                                        { $eq: ['$args.nextPhase', null] }
+                                    ] },
+                                true, false
+                            ]
+                        }
+                    },
+                    lastPhase: { $last: '$args.currentPhase' },
+                    eventCount: { $sum: 1 },
+                    mentoringCount: {
+                        $sum: { $cond: [{ $eq: ['$type', 'mentoring'] }, 1, 0] }
+                    },
+                }
+            },
+            { $sort: { startedAt: -1 } },
+            { $limit: limit },
+            {
+                $project: {
+                    jobId: '$_id',
+                    jobName: 1,
+                    startedAt: 1,
+                    completedAt: 1,
+                    isCompleted: 1,
+                    lastPhase: 1,
+                    eventCount: 1,
+                    mentoringCount: 1,
+                    durationMs: {
+                        $cond: [
+                            { $and: ['$isCompleted', { $ne: ['$startedAt', null] }, { $ne: ['$completedAt', null] }] },
+                            { $subtract: ['$completedAt', '$startedAt'] },
+                            null
+                        ]
+                    }
+                }
+            }
+        ];
+        return await collection.aggregate(pipeline).toArray();
+    }
+    /**
+     * Get per-job token usage by computing delta between first and last
+     * cumulative Prometheus snapshots for a given jobId.
+     *
+     * Groups by claudeSessionId and uses the session with the most snapshots
+     * to avoid cross-session contamination.
+     */
+    async getTokenUsageByJob(jobId, userId) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const filter = { jobId, tokenSnapshot: { $exists: true, $ne: null } };
+        if (userId)
+            filter.userId = userId;
+        // Find all events for this job that have token snapshots
+        const events = await collection
+            .find(filter)
+            .sort({ createdAt: 1 })
+            .toArray();
+        if (events.length === 0)
+            return null;
+        // Group by claudeSessionId and pick the session with most snapshots
+        const bySession = new Map();
+        for (const event of events) {
+            const sid = event.tokenSnapshot?.claudeSessionId || 'unknown';
+            if (!bySession.has(sid))
+                bySession.set(sid, []);
+            bySession.get(sid).push(event);
+        }
+        let bestSession = events; // fallback: all events
+        let bestCount = 0;
+        for (const [, sessionEvents] of bySession) {
+            if (sessionEvents.length > bestCount) {
+                bestCount = sessionEvents.length;
+                bestSession = sessionEvents;
+            }
+        }
+        const first = bestSession[0].tokenSnapshot;
+        const last = bestSession[bestSession.length - 1].tokenSnapshot;
+        if (bestSession.length === 1) {
+            return {
+                jobId,
+                inputTokens: first.inputTokens,
+                outputTokens: first.outputTokens,
+                cacheReadTokens: first.cacheReadTokens,
+                cacheCreationTokens: first.cacheCreationTokens,
+                costUsd: first.costUsd,
+                model: first.model,
+                isPartial: true,
+                snapshotCount: 1,
+            };
+        }
+        // Compute deltas — negative means counter reset, return null
+        const delta = (end, start) => {
+            const d = end - start;
+            return d < 0 ? null : d;
+        };
+        const costDelta = last.costUsd - first.costUsd;
+        return {
+            jobId,
+            inputTokens: delta(last.inputTokens, first.inputTokens),
+            outputTokens: delta(last.outputTokens, first.outputTokens),
+            cacheReadTokens: delta(last.cacheReadTokens, first.cacheReadTokens),
+            cacheCreationTokens: delta(last.cacheCreationTokens, first.cacheCreationTokens),
+            costUsd: costDelta < 0 ? null : costDelta,
+            model: last.model,
+            isPartial: false,
+            snapshotCount: bestSession.length,
+        };
+    }
+    /**
+     * Get aggregated token usage summary across all jobs for a user.
+     */
+    async getTokenUsageSummary(userId, startDate) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const pipeline = [
+            {
+                $match: {
+                    userId,
+                    createdAt: { $gte: startDate },
+                    'tokenSnapshot': { $exists: true },
+                }
+            },
+            { $sort: { createdAt: 1 } },
+            {
+                $group: {
+                    _id: '$jobId',
+                    jobName: { $first: '$name' },
+                    snapshotCount: { $sum: 1 },
+                    firstInputTokens: { $first: '$tokenSnapshot.inputTokens' },
+                    lastInputTokens: { $last: '$tokenSnapshot.inputTokens' },
+                    firstOutputTokens: { $first: '$tokenSnapshot.outputTokens' },
+                    lastOutputTokens: { $last: '$tokenSnapshot.outputTokens' },
+                    firstCostUsd: { $first: '$tokenSnapshot.costUsd' },
+                    lastCostUsd: { $last: '$tokenSnapshot.costUsd' },
+                    model: { $last: '$tokenSnapshot.model' },
+                    startedAt: { $min: '$createdAt' },
+                    completedAt: { $max: '$createdAt' },
+                }
+            },
+            {
+                $project: {
+                    jobId: '$_id',
+                    jobName: 1,
+                    snapshotCount: 1,
+                    model: 1,
+                    startedAt: 1,
+                    completedAt: 1,
+                    inputTokens: {
+                        $cond: [
+                            { $gte: [{ $subtract: ['$lastInputTokens', '$firstInputTokens'] }, 0] },
+                            { $subtract: ['$lastInputTokens', '$firstInputTokens'] },
+                            null,
+                        ]
+                    },
+                    outputTokens: {
+                        $cond: [
+                            { $gte: [{ $subtract: ['$lastOutputTokens', '$firstOutputTokens'] }, 0] },
+                            { $subtract: ['$lastOutputTokens', '$firstOutputTokens'] },
+                            null,
+                        ]
+                    },
+                    costUsd: {
+                        $cond: [
+                            { $gte: [{ $subtract: ['$lastCostUsd', '$firstCostUsd'] }, 0] },
+                            { $subtract: ['$lastCostUsd', '$firstCostUsd'] },
+                            null,
+                        ]
+                    },
+                }
+            },
+            { $sort: { completedAt: -1 } },
+        ];
+        return await collection.aggregate(pipeline).toArray();
+    }
+    /**
+     * Issue #330 / R2.1 — aggregate token + cost usage for a user across a
+     * time window with optional repo filter. Computes per-job deltas, then
+     * sums them. Also rolls up by agent and by model so the dashboard can
+     * show "Cost by Agent" without a second round-trip.
+     */
+    async getUsageAggregate(opts) {
+        if (!this.db)
+            throw new Error('DB not connected');
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const dateFilter = { $gte: opts.startDate };
+        if (opts.endDate)
+            dateFilter.$lte = opts.endDate;
+        const baseMatch = {
+            userId: opts.userId,
+            createdAt: dateFilter,
+            jobId: { $exists: true, $ne: null },
+        };
+        const sanitizedRepo = (0, git_utils_1.sanitizeRepoIdentifier)(opts.repoIdentifier);
+        if (sanitizedRepo)
+            baseMatch.repoIdentifier = sanitizedRepo;
+        // Per-jobId delta computation. Each jobId emits one row carrying the
+        // delta + the most-recent agent/model attribution.
+        const perJobPipeline = [
+            { $match: baseMatch },
+            { $sort: { createdAt: 1 } },
+            {
+                $group: {
+                    _id: '$jobId',
+                    agent: { $last: { $ifNull: ['$agentName', 'unknown'] } },
+                    model: { $last: { $ifNull: ['$agentModel', '$tokenSnapshot.model'] } },
+                    snapshotCount: {
+                        $sum: { $cond: [{ $ifNull: ['$tokenSnapshot', false] }, 1, 0] },
+                    },
+                    firstInputTokens: { $first: '$tokenSnapshot.inputTokens' },
+                    lastInputTokens: { $last: '$tokenSnapshot.inputTokens' },
+                    firstOutputTokens: { $first: '$tokenSnapshot.outputTokens' },
+                    lastOutputTokens: { $last: '$tokenSnapshot.outputTokens' },
+                    firstCacheReadTokens: { $first: '$tokenSnapshot.cacheReadTokens' },
+                    lastCacheReadTokens: { $last: '$tokenSnapshot.cacheReadTokens' },
+                    firstCacheCreationTokens: { $first: '$tokenSnapshot.cacheCreationTokens' },
+                    lastCacheCreationTokens: { $last: '$tokenSnapshot.cacheCreationTokens' },
+                    firstCostUsd: { $first: '$tokenSnapshot.costUsd' },
+                    lastCostUsd: { $last: '$tokenSnapshot.costUsd' },
+                    firstUnavailableReason: { $first: '$tokenCaptureUnavailableReason' },
+                },
+            },
+            {
+                $project: {
+                    jobId: '$_id',
+                    agent: 1,
+                    model: 1,
+                    hasUsage: { $gt: ['$snapshotCount', 0] },
+                    unavailableReason: '$firstUnavailableReason',
+                    inputTokens: nonNegativeDelta('$firstInputTokens', '$lastInputTokens'),
+                    outputTokens: nonNegativeDelta('$firstOutputTokens', '$lastOutputTokens'),
+                    cacheReadTokens: nonNegativeDelta('$firstCacheReadTokens', '$lastCacheReadTokens'),
+                    cacheCreationTokens: nonNegativeDelta('$firstCacheCreationTokens', '$lastCacheCreationTokens'),
+                    costUsd: nonNegativeDelta('$firstCostUsd', '$lastCostUsd'),
+                },
+            },
+        ];
+        const perJob = await collection.aggregate(perJobPipeline).toArray();
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        let totalCacheReadTokens = 0;
+        let totalCacheCreationTokens = 0;
+        let totalCostUsd = 0;
+        let jobsWithUsageData = 0;
+        let jobsWithoutUsageData = 0;
+        const unavailableReasons = {};
+        const agentRollup = new Map();
+        const modelRollup = new Map();
+        for (const row of perJob) {
+            if (row.hasUsage) {
+                jobsWithUsageData++;
+                totalInputTokens += row.inputTokens || 0;
+                totalOutputTokens += row.outputTokens || 0;
+                totalCacheReadTokens += row.cacheReadTokens || 0;
+                totalCacheCreationTokens += row.cacheCreationTokens || 0;
+                const cost = row.costUsd || 0;
+                totalCostUsd += cost;
+                const agentKey = row.agent || 'unknown';
+                const aRow = agentRollup.get(agentKey) || {
+                    agent: agentKey, costUsd: 0, inputTokens: 0, outputTokens: 0, jobCount: 0,
+                };
+                aRow.costUsd += cost;
+                aRow.inputTokens += row.inputTokens || 0;
+                aRow.outputTokens += row.outputTokens || 0;
+                aRow.jobCount += 1;
+                agentRollup.set(agentKey, aRow);
+                const modelKey = `${agentKey}::${row.model || 'unknown'}`;
+                const mRow = modelRollup.get(modelKey) || {
+                    agent: agentKey, model: row.model || 'unknown', costUsd: 0, jobCount: 0,
+                };
+                mRow.costUsd += cost;
+                mRow.jobCount += 1;
+                modelRollup.set(modelKey, mRow);
+            }
+            else {
+                jobsWithoutUsageData++;
+                const reason = row.unavailableReason || 'unknown';
+                unavailableReasons[reason] = (unavailableReasons[reason] || 0) + 1;
+            }
+        }
+        return {
+            totalInputTokens,
+            totalOutputTokens,
+            totalCacheReadTokens,
+            totalCacheCreationTokens,
+            totalCostUsd,
+            jobsWithUsageData,
+            jobsWithoutUsageData,
+            byAgent: [...agentRollup.values()].sort((a, b) => b.costUsd - a.costUsd),
+            byModel: [...modelRollup.values()].sort((a, b) => b.costUsd - a.costUsd),
+            unavailableReasons: Object.keys(unavailableReasons).length > 0 ? unavailableReasons : undefined,
+        };
+    }
+    /**
+     * Issue #330 / R2.8 — per-job-name agent split for the per-job page.
+     */
+    async getJobAgentSummary(opts) {
+        const aggregate = await this.getUsageAggregateInternal({
+            userId: opts.userId,
+            startDate: opts.startDate,
+            endDate: opts.endDate,
+            repoIdentifier: opts.repoIdentifier,
+            jobName: opts.jobName,
+        });
+        return {
+            jobName: opts.jobName,
+            byAgent: aggregate.byAgent,
+            byModel: aggregate.byModel,
+            jobsWithUsageData: aggregate.jobsWithUsageData,
+            jobsWithoutUsageData: aggregate.jobsWithoutUsageData,
+        };
+    }
+    /**
+     * Internal: shared aggregate that optionally filters by jobName for R2.8.
+     */
+    async getUsageAggregateInternal(opts) {
+        if (!opts.jobName) {
+            return this.getUsageAggregate(opts);
+        }
+        // Add a name filter and reuse the existing implementation by inlining.
+        // Simpler than parameterizing the public API.
+        const original = this.getUsageAggregate.bind(this);
+        const collection = this.db.collection(this.usageEventsCollectionName);
+        const dateFilter = { $gte: opts.startDate };
+        if (opts.endDate)
+            dateFilter.$lte = opts.endDate;
+        const sanitizedRepo = (0, git_utils_1.sanitizeRepoIdentifier)(opts.repoIdentifier);
+        const baseMatch = {
+            userId: opts.userId,
+            createdAt: dateFilter,
+            jobId: { $exists: true, $ne: null },
+            name: opts.jobName,
+        };
+        if (sanitizedRepo)
+            baseMatch.repoIdentifier = sanitizedRepo;
+        // Re-run the same per-job pipeline but with the name filter applied.
+        const perJobPipeline = [
+            { $match: baseMatch },
+            { $sort: { createdAt: 1 } },
+            {
+                $group: {
+                    _id: '$jobId',
+                    agent: { $last: { $ifNull: ['$agentName', 'unknown'] } },
+                    model: { $last: { $ifNull: ['$agentModel', '$tokenSnapshot.model'] } },
+                    snapshotCount: {
+                        $sum: { $cond: [{ $ifNull: ['$tokenSnapshot', false] }, 1, 0] },
+                    },
+                    firstInputTokens: { $first: '$tokenSnapshot.inputTokens' },
+                    lastInputTokens: { $last: '$tokenSnapshot.inputTokens' },
+                    firstOutputTokens: { $first: '$tokenSnapshot.outputTokens' },
+                    lastOutputTokens: { $last: '$tokenSnapshot.outputTokens' },
+                    firstCacheReadTokens: { $first: '$tokenSnapshot.cacheReadTokens' },
+                    lastCacheReadTokens: { $last: '$tokenSnapshot.cacheReadTokens' },
+                    firstCacheCreationTokens: { $first: '$tokenSnapshot.cacheCreationTokens' },
+                    lastCacheCreationTokens: { $last: '$tokenSnapshot.cacheCreationTokens' },
+                    firstCostUsd: { $first: '$tokenSnapshot.costUsd' },
+                    lastCostUsd: { $last: '$tokenSnapshot.costUsd' },
+                    firstUnavailableReason: { $first: '$tokenCaptureUnavailableReason' },
+                },
+            },
+            {
+                $project: {
+                    jobId: '$_id',
+                    agent: 1,
+                    model: 1,
+                    hasUsage: { $gt: ['$snapshotCount', 0] },
+                    unavailableReason: '$firstUnavailableReason',
+                    inputTokens: nonNegativeDelta('$firstInputTokens', '$lastInputTokens'),
+                    outputTokens: nonNegativeDelta('$firstOutputTokens', '$lastOutputTokens'),
+                    cacheReadTokens: nonNegativeDelta('$firstCacheReadTokens', '$lastCacheReadTokens'),
+                    cacheCreationTokens: nonNegativeDelta('$firstCacheCreationTokens', '$lastCacheCreationTokens'),
+                    costUsd: nonNegativeDelta('$firstCostUsd', '$lastCostUsd'),
+                },
+            },
+        ];
+        const perJob = await collection.aggregate(perJobPipeline).toArray();
+        const agentRollup = new Map();
+        const modelRollup = new Map();
+        let jobsWithUsageData = 0, jobsWithoutUsageData = 0;
+        let totalInputTokens = 0, totalOutputTokens = 0, totalCacheReadTokens = 0, totalCacheCreationTokens = 0, totalCostUsd = 0;
+        for (const row of perJob) {
+            if (row.hasUsage) {
+                jobsWithUsageData++;
+                const cost = row.costUsd || 0;
+                totalInputTokens += row.inputTokens || 0;
+                totalOutputTokens += row.outputTokens || 0;
+                totalCacheReadTokens += row.cacheReadTokens || 0;
+                totalCacheCreationTokens += row.cacheCreationTokens || 0;
+                totalCostUsd += cost;
+                const agentKey = row.agent || 'unknown';
+                const aRow = agentRollup.get(agentKey) || {
+                    agent: agentKey, costUsd: 0, inputTokens: 0, outputTokens: 0, jobCount: 0,
+                };
+                aRow.costUsd += cost;
+                aRow.inputTokens += row.inputTokens || 0;
+                aRow.outputTokens += row.outputTokens || 0;
+                aRow.jobCount += 1;
+                agentRollup.set(agentKey, aRow);
+                const modelKey = `${agentKey}::${row.model || 'unknown'}`;
+                const mRow = modelRollup.get(modelKey) || {
+                    agent: agentKey, model: row.model || 'unknown', costUsd: 0, jobCount: 0,
+                };
+                mRow.costUsd += cost;
+                mRow.jobCount += 1;
+                modelRollup.set(modelKey, mRow);
+            }
+            else {
+                jobsWithoutUsageData++;
+            }
+        }
+        return {
+            totalInputTokens,
+            totalOutputTokens,
+            totalCacheReadTokens,
+            totalCacheCreationTokens,
+            totalCostUsd,
+            jobsWithUsageData,
+            jobsWithoutUsageData,
+            byAgent: [...agentRollup.values()].sort((a, b) => b.costUsd - a.costUsd),
+            byModel: [...modelRollup.values()].sort((a, b) => b.costUsd - a.costUsd),
+        };
+    }
+}
+exports.FraimDbService = FraimDbService;
+FraimDbService.refCount = 0;
+// ───────────────────────────────────────────────────────────────────────
+// Issue #359 — OAuth-first login: HTTP auth sessions
+// ───────────────────────────────────────────────────────────────────────
+FraimDbService.AUTH_SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30d
+// ───────────────────────────────────────────────────────────────────────
+// Issue #359 — Pending OAuth round-trip state
+// ───────────────────────────────────────────────────────────────────────
+FraimDbService.PENDING_OAUTH_TTL_MS = 10 * 60 * 1000;
+/**
+ * Helper for monotonic-counter delta projection — returns the difference
+ * (last - first) when non-negative, else 0. Mirrors getTokenUsageSummary
+ * but defaults to 0 instead of null so the totals math stays simple.
+ */
+function nonNegativeDelta(firstField, lastField) {
+    return {
+        $cond: [
+            { $gte: [{ $subtract: [lastField, firstField] }, 0] },
+            { $subtract: [lastField, firstField] },
+            0,
+        ],
+    };
+}