ballrush-core 1.3.0 → 1.3.2

package/dist/repositories/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./mongo/user.repository";
 export * from "./mongo/group.repository";
+export * from "./mongo/group-repo.events";
 export * from "./mongo/event.repository";
 export * from "./mongo/event-template.repository";
 export * from "./mongo/stat-group.repository";

package/dist/repositories/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./mongo/user.repository"), exports);
 __exportStar(require("./mongo/group.repository"), exports);
+__exportStar(require("./mongo/group-repo.events"), exports);
 __exportStar(require("./mongo/event.repository"), exports);
 __exportStar(require("./mongo/event-template.repository"), exports);
 __exportStar(require("./mongo/stat-group.repository"), exports);

package/dist/repositories/mongo/group-repo.events.d.ts

@@ -0,0 +1,42 @@
+import { EventEmitter } from "events";
+export type SuspiciousGroupUpdateReason = "rating_regression" | "history_truncated";
+export interface SuspiciousGroupUpdate {
+    groupId: number;
+    reason: SuspiciousGroupUpdateReason;
+    /** Sum of all rating points across all participants — before this update */
+    sumBefore: number;
+    /** Sum of all rating points across all participants — after this update would be applied */
+    sumAfter: number;
+    /** sumAfter - sumBefore (negative = regression) */
+    delta: number;
+    /** Total ratingHistory entries in the document — before */
+    historyCountBefore: number;
+    /** Total ratingHistory entries — after */
+    historyCountAfter: number;
+    /** Top 10 individual losses (userId, delta), sorted by largest loss first */
+    topLosses: Array<{
+        userId: number;
+        deltaSum: number;
+        deltaHistoryLen: number;
+    }>;
+    /** First N lines of the call stack pointing at the caller */
+    callerStack: string;
+    /** true if the repository refused to apply the write because of regression guard */
+    refused: boolean;
+    /** ISO timestamp of when the event fired */
+    timestamp: string;
+}
+declare class GroupRepoEvents extends EventEmitter {
+    emitSuspicious(ev: SuspiciousGroupUpdate): void;
+}
+/**
+ * Singleton emitter the MongoGroupsRepository fires events on whenever it
+ * detects something unusual (e.g. a write that would drop total rating
+ * significantly, or shorten history). Wire a listener in the app's bootstrap
+ * to forward these to Telegram, Slack, etc.
+ *
+ *   import { groupRepoEvents } from "ballrush-core/repositories";
+ *   groupRepoEvents.on("suspicious", (ev) => { ... });
+ */
+export declare const groupRepoEvents: GroupRepoEvents;
+export {};

package/dist/repositories/mongo/group-repo.events.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupRepoEvents = void 0;
+const events_1 = require("events");
+class GroupRepoEvents extends events_1.EventEmitter {
+    emitSuspicious(ev) {
+        this.emit("suspicious", ev);
+    }
+}
+/**
+ * Singleton emitter the MongoGroupsRepository fires events on whenever it
+ * detects something unusual (e.g. a write that would drop total rating
+ * significantly, or shorten history). Wire a listener in the app's bootstrap
+ * to forward these to Telegram, Slack, etc.
+ *
+ *   import { groupRepoEvents } from "ballrush-core/repositories";
+ *   groupRepoEvents.on("suspicious", (ev) => { ... });
+ */
+exports.groupRepoEvents = new GroupRepoEvents();

package/dist/repositories/mongo/group.repository.js

@@ -3,6 +3,71 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MongoGroupsRepository = void 0;
 const group_mapper_1 = require("./group.mapper");
 const errors_1 = require("../../errors");
+const group_repo_events_1 = require("./group-repo.events");
+// Regression guard thresholds. Tunable via env:
+//   GROUPS_REGRESSION_GUARD=off — disable refusal (still logs + emits event)
+//   GROUPS_REGRESSION_ABS_DROP — absolute sum drop that counts as suspicious (default 50)
+//   GROUPS_REGRESSION_PCT_DROP — fractional drop (0..1) that counts as suspicious (default 0.05)
+function getRegressionGuardConfig() {
+    const enabled = (process.env.GROUPS_REGRESSION_GUARD ?? "on") !== "off";
+    const absDrop = Number(process.env.GROUPS_REGRESSION_ABS_DROP ?? 50);
+    const pctDrop = Number(process.env.GROUPS_REGRESSION_PCT_DROP ?? 0.05);
+    return { enabled, absDrop, pctDrop };
+}
+function sumOfHistory(participants) {
+    if (!participants)
+        return 0;
+    let total = 0;
+    for (const p of participants) {
+        for (const r of p.ratingHistory ?? [])
+            total += r.value ?? 0;
+    }
+    return total;
+}
+function countHistory(participants) {
+    if (!participants)
+        return 0;
+    let total = 0;
+    for (const p of participants)
+        total += (p.ratingHistory ?? []).length;
+    return total;
+}
+function computeTopLosses(before, after, limit = 10) {
+    const beforeBy = new Map();
+    for (const p of before)
+        beforeBy.set(p.userId, p);
+    const losses = [];
+    for (const a of after) {
+        const b = beforeBy.get(a.userId);
+        if (!b)
+            continue;
+        const bSum = (b.ratingHistory ?? []).reduce((s, r) => s + (r.value ?? 0), 0);
+        const aSum = (a.ratingHistory ?? []).reduce((s, r) => s + (r.value ?? 0), 0);
+        const deltaSum = aSum - bSum;
+        const deltaHistoryLen = (a.ratingHistory ?? []).length - (b.ratingHistory ?? []).length;
+        if (deltaSum < 0 || deltaHistoryLen < 0) {
+            losses.push({ userId: a.userId, deltaSum: Math.round(deltaSum * 100) / 100, deltaHistoryLen });
+        }
+    }
+    // also detect participants that disappeared entirely
+    const afterIds = new Set(after.map(p => p.userId));
+    for (const b of before) {
+        if (!afterIds.has(b.userId)) {
+            const bSum = (b.ratingHistory ?? []).reduce((s, r) => s + (r.value ?? 0), 0);
+            losses.push({
+                userId: b.userId,
+                deltaSum: Math.round(-bSum * 100) / 100,
+                deltaHistoryLen: -(b.ratingHistory ?? []).length,
+            });
+        }
+    }
+    losses.sort((x, y) => x.deltaSum - y.deltaSum);
+    return losses.slice(0, limit);
+}
+function shortStack(depth = 8) {
+    const raw = new Error().stack ?? "";
+    return raw.split("\n").slice(2, 2 + depth).join("\n");
+}
 class MongoGroupsRepository {
     constructor(GroupModel) {
         this.GroupModel = GroupModel;
@@ -58,6 +123,59 @@ class MongoGroupsRepository {
                 throw new errors_1.ValidationError('Group', 'updates', updates, 'updates object is required');
             }
             const write = (0, group_mapper_1.toDoc)(updates);
+            // --- Observability: log every full-document write of a group ---
+            // We log enough context to find the culprit after the fact if the
+            // historical Pattaya-style regression ever happens again.
+            const callerStack = shortStack();
+            const sumAfter = sumOfHistory(write.participants);
+            const historyCountAfter = countHistory(write.participants);
+            // Read current state ONCE for regression guard + alert payload.
+            const currentDoc = await this.GroupModel.findOne({ groupId }).lean();
+            const sumBefore = sumOfHistory(currentDoc?.participants ?? []);
+            const historyCountBefore = countHistory(currentDoc?.participants ?? []);
+            const delta = sumAfter - sumBefore;
+            const historyDelta = historyCountAfter - historyCountBefore;
+            console.log(`[GROUPS_UPDATE] groupId=${groupId} participants=${write.participants.length} ` +
+                `sumBefore=${sumBefore.toFixed(2)} sumAfter=${sumAfter.toFixed(2)} delta=${delta.toFixed(2)} ` +
+                `histBefore=${historyCountBefore} histAfter=${historyCountAfter} histDelta=${historyDelta}\n` +
+                `[GROUPS_UPDATE_STACK]\n${callerStack}`);
+            // --- Regression guard ---
+            const guard = getRegressionGuardConfig();
+            const absThreshold = Math.max(guard.absDrop, Math.abs(sumBefore) * guard.pctDrop);
+            const isRegression = currentDoc !== null && (delta < -absThreshold || // big rating drop
+                historyDelta < 0 // history shrank
+            );
+            if (isRegression) {
+                const topLosses = computeTopLosses((currentDoc?.participants ?? []), write.participants);
+                const event = {
+                    groupId,
+                    reason: (delta < -absThreshold ? "rating_regression" : "history_truncated"),
+                    sumBefore: Math.round(sumBefore * 100) / 100,
+                    sumAfter: Math.round(sumAfter * 100) / 100,
+                    delta: Math.round(delta * 100) / 100,
+                    historyCountBefore,
+                    historyCountAfter,
+                    topLosses,
+                    callerStack,
+                    refused: guard.enabled,
+                    timestamp: new Date().toISOString(),
+                };
+                console.error(`[GROUPS_REGRESSION] groupId=${groupId} reason=${event.reason} ` +
+                    `delta=${event.delta} histDelta=${historyDelta} refused=${event.refused}\n` +
+                    `topLosses=${JSON.stringify(event.topLosses)}\n` +
+                    `[GROUPS_REGRESSION_STACK]\n${callerStack}`);
+                // Fire-and-forget event for any listener (e.g. Telegram alerter in the bot).
+                try {
+                    group_repo_events_1.groupRepoEvents.emitSuspicious(event);
+                }
+                catch { /* never fail update because of a listener */ }
+                if (guard.enabled) {
+                    // Refuse the write — return null so callers can detect failure.
+                    // To bypass intentionally (e.g. legit reset by admin), run with:
+                    //   GROUPS_REGRESSION_GUARD=off
+                    return null;
+                }
+            }
             const doc = await this.GroupModel.findOneAndUpdate({ groupId }, { $set: write }, { new: true }).lean();
             return doc ? (0, group_mapper_1.toDomain)(doc) : null;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ballrush-core",
-    "version": "1.3.0",
+    "version": "1.3.2",
     "private": false,
     "license": "MIT",
     "main": "./dist/index.js",