@lensmcp/node-instrumentation 1.16.29 → 1.16.31

package/index.d.ts

@@ -1,5 +1,7 @@
-export { lensEmit, isLensWriting, PROJECT, EVENT_FILE } from './lib/emit';
+export { lensEmit, isLensWriting, PROJECT, EVENT_FILE, EVENT_MAX_BYTES, EVENT_MAX_FILES, maybeRotateEventFile } from './lib/emit';
 export type { LensSeverity } from './lib/emit';
+export { createEventFloodGuard } from './lib/flood-guard';
+export type { FloodGuard, FloodGuardOptions, FloodAdmit } from './lib/flood-guard';
 export { installRequireHook } from './lib/require-hook';
 export type { ModuleTap } from './lib/require-hook';
 export { tapEgress } from './lib/tap-egress';

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1E,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,iCAAiC,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClI,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,iCAAiC,EAAE,MAAM,eAAe,CAAC"}

package/index.js

@@ -1,11 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.installLensmcpNodeInstrumentation = exports.installChildAppBridge = exports.nestTap = exports.bullmqTap = exports.redisTap = exports.pgTap = exports.tapExec = exports.tapFs = exports.tapEgress = exports.installRequireHook = exports.EVENT_FILE = exports.PROJECT = exports.isLensWriting = exports.lensEmit = void 0;
+exports.installLensmcpNodeInstrumentation = exports.installChildAppBridge = exports.nestTap = exports.bullmqTap = exports.redisTap = exports.pgTap = exports.tapExec = exports.tapFs = exports.tapEgress = exports.installRequireHook = exports.createEventFloodGuard = exports.maybeRotateEventFile = exports.EVENT_MAX_FILES = exports.EVENT_MAX_BYTES = exports.EVENT_FILE = exports.PROJECT = exports.isLensWriting = exports.lensEmit = void 0;
 var emit_1 = require("./lib/emit");
 Object.defineProperty(exports, "lensEmit", { enumerable: true, get: function () { return emit_1.lensEmit; } });
 Object.defineProperty(exports, "isLensWriting", { enumerable: true, get: function () { return emit_1.isLensWriting; } });
 Object.defineProperty(exports, "PROJECT", { enumerable: true, get: function () { return emit_1.PROJECT; } });
 Object.defineProperty(exports, "EVENT_FILE", { enumerable: true, get: function () { return emit_1.EVENT_FILE; } });
+Object.defineProperty(exports, "EVENT_MAX_BYTES", { enumerable: true, get: function () { return emit_1.EVENT_MAX_BYTES; } });
+Object.defineProperty(exports, "EVENT_MAX_FILES", { enumerable: true, get: function () { return emit_1.EVENT_MAX_FILES; } });
+Object.defineProperty(exports, "maybeRotateEventFile", { enumerable: true, get: function () { return emit_1.maybeRotateEventFile; } });
+var flood_guard_1 = require("./lib/flood-guard");
+Object.defineProperty(exports, "createEventFloodGuard", { enumerable: true, get: function () { return flood_guard_1.createEventFloodGuard; } });
 var require_hook_1 = require("./lib/require-hook");
 Object.defineProperty(exports, "installRequireHook", { enumerable: true, get: function () { return require_hook_1.installRequireHook; } });
 var tap_egress_1 = require("./lib/tap-egress");

package/lib/emit.d.ts

@@ -1,3 +1,26 @@
+/** Per-generation cap for the events.jsonl bus (a long-running dev session hit 9 GB in the wild, and
+ *  a 254 MB file OOM-crash-looped every ingesting consumer in the 2026-07-28 flood). Override with
+ *  `LENSMCP_EVENT_MAX_BYTES` (default 50 MB). 0/invalid ⇒ the default. */
+export declare const EVENT_MAX_BYTES: number;
+/** Rotated generations kept as history (`events.jsonl.1` … `.N`, newest → oldest). With the live
+ *  file that bounds a workspace to (N+1) × EVENT_MAX_BYTES (~300 MB at defaults). Override with
+ *  `LENSMCP_EVENT_MAX_FILES`. */
+export declare const EVENT_MAX_FILES: number;
+/**
+ * Round-robin rotation for a bus file: when the live file exceeds the per-generation cap, drop the
+ * oldest generation, shift `.1` → `.2` → … → `.N`, and rename the live file to `.1` (the next append
+ * recreates it fresh). Throttled by a per-file byte counter so we `statSync` at most ~once per MB,
+ * not per event. Best-effort + fs-tap-safe (pristine refs, callers hold `writing`). Many processes
+ * append to the same path — the final `renameSync` is atomic, so a concurrent rotate that loses the
+ * race just throws ENOENT and no-ops (a racing shift can at worst mis-order HISTORY generations,
+ * never touch the live file). Exported so every OTHER writer to the shared bus (the cluster
+ * gateway's observability emit) enforces the same contract — the gateway was the one writer with NO
+ * rotation, which is how foodguard's bus outgrew every consumer. `caps` exists for tests.
+ */
+export declare function maybeRotateEventFile(file: string, addedBytes: number, caps?: {
+    maxBytes?: number;
+    maxFiles?: number;
+}): void;
 export type LensSeverity = 'info' | 'error';
 export type LogSeverity = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
 /** Service identity stamped on every event (set by the cluster serve executor). */

package/lib/emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/lib/emit.ts"],"names":[],"mappings":"AAiDA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC;AAC5C,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAE3E,mFAAmF;AACnF,eAAO,MAAM,OAAO,EAAE,MACkD,CAAC;AAEzE,yEAAyE;AACzE,eAAO,MAAM,UAAU,EAAE,MACsD,CAAC;AAKhF,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,kFAAkF;AAClF,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,GAChB,IAAI,CAiCN;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA2BlE"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/lib/emit.ts"],"names":[],"mappings":"AAwBA;;0EAE0E;AAC1E,eAAO,MAAM,eAAe,QAGxB,CAAC;AACL;;iCAEiC;AACjC,eAAO,MAAM,eAAe,QAGxB,CAAC;AAIL;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,IAAI,CA+BN;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC;AAC5C,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAE3E,mFAAmF;AACnF,eAAO,MAAM,OAAO,EAAE,MACkD,CAAC;AAEzE,yEAAyE;AACzE,eAAO,MAAM,UAAU,EAAE,MACsD,CAAC;AAYhF,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,kFAAkF;AAClF,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,GAChB,IAAI,CAoCN;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA6BlE"}

package/lib/emit.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EVENT_FILE = exports.PROJECT = void 0;
+exports.EVENT_FILE = exports.PROJECT = exports.EVENT_MAX_FILES = exports.EVENT_MAX_BYTES = void 0;
+exports.maybeRotateEventFile = maybeRotateEventFile;
 exports.isLensWriting = isLensWriting;
 exports.lensEmit = lensEmit;
 exports.lensLog = lensLog;
@@ -20,37 +21,75 @@ const tslib_1 = require("tslib");
  */
 const nodeFs = tslib_1.__importStar(require("node:fs"));
 const node_path_1 = require("node:path");
+const flood_guard_1 = require("./flood-guard");
 // Pristine references, frozen at load — immune to the fs tap's later patching.
 const appendFileSync = nodeFs.appendFileSync;
 const mkdirSync = nodeFs.mkdirSync;
 const statSync = nodeFs.statSync;
 const renameSync = nodeFs.renameSync;
-/** Cap the events.jsonl so a long-running dev session can't grow it to gigabytes (it hit 9 GB in the
- *  wild). Override with `LENSMCP_EVENT_MAX_BYTES` (default 256 MB). 0/invalid ⇒ the default. */
-const MAX_EVENT_BYTES = (() => {
+const unlinkSync = nodeFs.unlinkSync;
+/** Per-generation cap for the events.jsonl bus (a long-running dev session hit 9 GB in the wild, and
+ *  a 254 MB file OOM-crash-looped every ingesting consumer in the 2026-07-28 flood). Override with
+ *  `LENSMCP_EVENT_MAX_BYTES` (default 50 MB). 0/invalid ⇒ the default. */
+exports.EVENT_MAX_BYTES = (() => {
     const n = Number(process.env['LENSMCP_EVENT_MAX_BYTES']);
-    return Number.isFinite(n) && n > 0 ? n : 256 * 1024 * 1024;
+    return Number.isFinite(n) && n > 0 ? n : 50 * 1024 * 1024;
+})();
+/** Rotated generations kept as history (`events.jsonl.1` … `.N`, newest → oldest). With the live
+ *  file that bounds a workspace to (N+1) × EVENT_MAX_BYTES (~300 MB at defaults). Override with
+ *  `LENSMCP_EVENT_MAX_FILES`. */
+exports.EVENT_MAX_FILES = (() => {
+    const n = Number(process.env['LENSMCP_EVENT_MAX_FILES']);
+    return Number.isFinite(n) && n >= 1 && n <= 20 ? Math.floor(n) : 5;
 })();
 const ROTATE_CHECK_BYTES = 1024 * 1024; // statSync at most ~once per MB appended (cheap amortized)
-let bytesSinceCheck = 0;
+const bytesSinceCheck = new Map();
 /**
- * Rotate the bus when it exceeds {@link MAX_EVENT_BYTES}: rename `events.jsonl` → `events.jsonl.1`
- * (keeping ONE previous generation; the next append recreates a fresh file). Throttled by a byte
- * counter so we `statSync` at most ~once per MB, not per event. Best-effort + fs-tap-safe (pristine
- * refs, called while `writing` is already true). Many processes append to the same path — `renameSync`
- * is atomic, so a concurrent rotate that loses the race just throws ENOENT and no-ops.
+ * Round-robin rotation for a bus file: when the live file exceeds the per-generation cap, drop the
+ * oldest generation, shift `.1` → `.2` → … → `.N`, and rename the live file to `.1` (the next append
+ * recreates it fresh). Throttled by a per-file byte counter so we `statSync` at most ~once per MB,
+ * not per event. Best-effort + fs-tap-safe (pristine refs, callers hold `writing`). Many processes
+ * append to the same path — the final `renameSync` is atomic, so a concurrent rotate that loses the
+ * race just throws ENOENT and no-ops (a racing shift can at worst mis-order HISTORY generations,
+ * never touch the live file). Exported so every OTHER writer to the shared bus (the cluster
+ * gateway's observability emit) enforces the same contract — the gateway was the one writer with NO
+ * rotation, which is how foodguard's bus outgrew every consumer. `caps` exists for tests.
  */
-function rotateIfLarge(lineBytes) {
-    bytesSinceCheck += lineBytes;
-    if (bytesSinceCheck < ROTATE_CHECK_BYTES)
+function maybeRotateEventFile(file, addedBytes, caps) {
+    const sofar = (bytesSinceCheck.get(file) ?? 0) + addedBytes;
+    if (sofar < ROTATE_CHECK_BYTES && caps === undefined) {
+        bytesSinceCheck.set(file, sofar);
         return;
-    bytesSinceCheck = 0;
+    }
+    bytesSinceCheck.set(file, 0);
+    const maxBytes = caps?.maxBytes ?? exports.EVENT_MAX_BYTES;
+    const maxFiles = caps?.maxFiles ?? exports.EVENT_MAX_FILES;
+    try {
+        if (statSync(file).size <= maxBytes)
+            return;
+    }
+    catch {
+        return; /* missing / already rotated by another writer — fine */
+    }
+    try {
+        unlinkSync(`${file}.${maxFiles}`);
+    }
+    catch {
+        /* no oldest generation to drop */
+    }
+    for (let gen = maxFiles - 1; gen >= 1; gen--) {
+        try {
+            renameSync(`${file}.${gen}`, `${file}.${gen + 1}`);
+        }
+        catch {
+            /* that generation doesn't exist (yet) */
+        }
+    }
     try {
-        if (statSync(exports.EVENT_FILE).size > MAX_EVENT_BYTES)
-            renameSync(exports.EVENT_FILE, `${exports.EVENT_FILE}.1`);
+        renameSync(file, `${file}.1`);
     }
     catch {
-        /* missing / already rotated by another writer — fine */
+        /* lost the rotate race to a concurrent writer — its cascade already ran */
     }
 }
 /** Service identity stamped on every event (set by the cluster serve executor). */
@@ -59,6 +98,12 @@ exports.PROJECT = process.env['LENSMCP_PROJECT'] || process.env['SERVICE_NAME']
 exports.EVENT_FILE = process.env['LENSMCP_EVENT_FILE'] || `${process.cwd()}/.lensmcp/events.jsonl`;
 let writing = false;
 let dirReady = false;
+// Flood guards: one hot fingerprint (a query fired in a loop, a component rendering per frame) keeps
+// its first burst + a trickle with `floodSuppressed` counts, instead of flooding the bus file. Logs get
+// a laxer bucket — boot storms of a few hundred lines are normal; sustained >20 lines/s is log-spam the
+// bus shouldn't mirror unboundedly.
+const emitGuard = (0, flood_guard_1.createEventFloodGuard)({ burst: 30, perSec: 5 });
+const logGuard = (0, flood_guard_1.createEventFloodGuard)({ burst: 120, perSec: 20 });
 /** True while the lens itself is appending — the fs tap skips self-writes. */
 function isLensWriting() {
     return writing;
@@ -66,6 +111,10 @@ function isLensWriting() {
 function lensEmit(source, severity, title, raw, fingerprint, flowCtx) {
     try {
         writing = true;
+        const fp = fingerprint ?? `${source}:${String(raw['name'] ?? source)}`;
+        const admit = emitGuard.admit(fp);
+        if (!admit.ok)
+            return; // flood-guarded — the next admitted event carries the suppressed count
         if (!dirReady) {
             mkdirSync((0, node_path_1.dirname)(exports.EVENT_FILE), { recursive: true });
             dirReady = true;
@@ -84,11 +133,11 @@ function lensEmit(source, severity, title, raw, fingerprint, flowCtx) {
                 ...(flowCtx?.requestId ? { requestId: flowCtx.requestId } : {}),
                 ...(flowCtx?.originNodeId ? { originNodeId: flowCtx.originNodeId } : {}),
             },
-            fingerprint: fingerprint ?? `${source}:${String(raw['name'] ?? source)}`,
+            fingerprint: fp,
             title,
-            raw: { project: exports.PROJECT, ...raw },
+            raw: { project: exports.PROJECT, ...raw, ...(admit.suppressed > 0 ? { floodSuppressed: admit.suppressed } : {}) },
         }) + '\n';
-        rotateIfLarge(line.length);
+        maybeRotateEventFile(exports.EVENT_FILE, line.length);
         appendFileSync(exports.EVENT_FILE, line);
     }
     catch {
@@ -107,6 +156,9 @@ function lensEmit(source, severity, title, raw, fingerprint, flowCtx) {
 function lensLog(severity, title) {
     try {
         writing = true;
+        const admit = logGuard.admit(`log:${exports.PROJECT}`);
+        if (!admit.ok)
+            return; // log-spam guard — the next admitted line carries the suppressed count
         if (!dirReady) {
             mkdirSync((0, node_path_1.dirname)(exports.EVENT_FILE), { recursive: true });
             dirReady = true;
@@ -121,9 +173,9 @@ function lensLog(severity, title) {
             context: { sessionId: 'pending', projectName: exports.PROJECT },
             fingerprint: `log:${exports.PROJECT}`,
             title,
-            raw: { project: exports.PROJECT, kind: 'log' },
+            raw: { project: exports.PROJECT, kind: 'log', ...(admit.suppressed > 0 ? { floodSuppressed: admit.suppressed } : {}) },
         }) + '\n';
-        rotateIfLarge(line.length);
+        maybeRotateEventFile(exports.EVENT_FILE, line.length);
         appendFileSync(exports.EVENT_FILE, line);
     }
     catch {

package/lib/flood-guard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-fingerprint event flood guard — a token bucket per fingerprint, shared by
+ * every bus WRITER (lensEmit, the cluster gateway's observability emit, the
+ * bridge env sink mirrors it). One hot fingerprint (an app retrying a fetch in
+ * a loop, a valtio store churning per frame) must not be able to write hundreds
+ * of lines/sec into events.jsonl: the 2026-07-28 incident sustained ~680 ev/s,
+ * grew the bus file to 254 MB in two hours, and OOM-crash-looped every consumer
+ * that ingests it. The guard keeps the SIGNAL (the first burst, then a trickle
+ * with a `floodSuppressed` count) while dropping the redundant repetition.
+ */
+export interface FloodAdmit {
+    ok: boolean;
+    /** Events dropped for this fingerprint since the last admitted one (0 normally). */
+    suppressed: number;
+}
+export interface FloodGuard {
+    admit(fingerprint: string): FloodAdmit;
+}
+export interface FloodGuardOptions {
+    /** Instantaneous burst allowance per fingerprint (bucket capacity). Default 30. */
+    burst?: number;
+    /** Sustained events/sec per fingerprint (bucket refill). Default 5. */
+    perSec?: number;
+    /** Max distinct fingerprints tracked before stale buckets are evicted. Default 2048. */
+    maxKeys?: number;
+}
+export declare function createEventFloodGuard(opts?: FloodGuardOptions): FloodGuard;
+//# sourceMappingURL=flood-guard.d.ts.map

package/lib/flood-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flood-guard.d.ts","sourceRoot":"","sources":["../../src/lib/flood-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAmBD,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,UAAU,CA0C1E"}

package/lib/flood-guard.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Per-fingerprint event flood guard — a token bucket per fingerprint, shared by
+ * every bus WRITER (lensEmit, the cluster gateway's observability emit, the
+ * bridge env sink mirrors it). One hot fingerprint (an app retrying a fetch in
+ * a loop, a valtio store churning per frame) must not be able to write hundreds
+ * of lines/sec into events.jsonl: the 2026-07-28 incident sustained ~680 ev/s,
+ * grew the bus file to 254 MB in two hours, and OOM-crash-looped every consumer
+ * that ingests it. The guard keeps the SIGNAL (the first burst, then a trickle
+ * with a `floodSuppressed` count) while dropping the redundant repetition.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEventFloodGuard = createEventFloodGuard;
+/** `LENSMCP_EVENT_MAX_EPS` overrides the sustained per-fingerprint rate; `0`/`off` disables the guard. */
+function envPerSec() {
+    const raw = process.env['LENSMCP_EVENT_MAX_EPS'];
+    if (raw === undefined || raw === '')
+        return undefined;
+    if (raw === 'off')
+        return 'off';
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        return undefined;
+    return n <= 0 ? 'off' : n;
+}
+function createEventFloodGuard(opts) {
+    const env = envPerSec();
+    if (env === 'off')
+        return { admit: () => ({ ok: true, suppressed: 0 }) };
+    const perSec = env ?? opts?.perSec ?? 5;
+    const burst = Math.max(1, opts?.burst ?? Math.max(30, perSec * 4));
+    const maxKeys = opts?.maxKeys ?? 2048;
+    const buckets = new Map();
+    const evictStale = (now) => {
+        // A full bucket carries no state worth keeping — evict anything idle >60s.
+        for (const [k, b] of buckets) {
+            if (now - b.lastSeenAt > 60_000)
+                buckets.delete(k);
+        }
+        // Pathological cardinality (unique fingerprints per event) — reset rather than grow.
+        if (buckets.size > maxKeys)
+            buckets.clear();
+    };
+    return {
+        admit(fingerprint) {
+            const now = Date.now();
+            let b = buckets.get(fingerprint);
+            if (!b) {
+                if (buckets.size >= maxKeys)
+                    evictStale(now);
+                b = { tokens: burst, lastRefillAt: now, suppressed: 0, lastSeenAt: now };
+                buckets.set(fingerprint, b);
+            }
+            b.lastSeenAt = now;
+            const elapsed = now - b.lastRefillAt;
+            if (elapsed > 0) {
+                b.tokens = Math.min(burst, b.tokens + (elapsed / 1000) * perSec);
+                b.lastRefillAt = now;
+            }
+            if (b.tokens >= 1) {
+                b.tokens -= 1;
+                const suppressed = b.suppressed;
+                b.suppressed = 0;
+                return { ok: true, suppressed };
+            }
+            b.suppressed += 1;
+            return { ok: false, suppressed: 0 };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/node-instrumentation",
-  "version": "1.16.29",
+  "version": "1.16.31",
   "main": "./index.js",
   "types": "./index.d.ts",
   "exports": {
@@ -15,7 +15,7 @@
     }
   },
   "dependencies": {
-    "@lensmcp/nest-instrumentation": "1.16.29",
+    "@lensmcp/nest-instrumentation": "1.16.31",
     "tslib": "^2.3.0"
   },
   "optionalDependencies": {