@lensmcp/memory-tracker 1.23.13 → 1.24.0

package/README.md

@@ -2,7 +2,7 @@
 
 Track memory growth in long-lived JavaScript containers, attribute it to the flow that caused it, and surface suspected leaks as LensMCP events.
 
-`@lensmcp/memory-tracker` instruments the mutating methods of `Map`, `Set`, and `Array` instances in place. Every mutation updates a per-container "owner" record (item count plus a rough byte estimate) and is attributed to the active request/flow. When a flow grows a container past a threshold and the items do not shrink back, the tracker emits a `memory-retention` ("memory leak suspected") event. It also reports stale generations of disposed singletons that still retain bytes. The result is a deterministic, attributable memory signal in the LensMCP lens — instead of a flat heap graph, you see *which owner grew, by how much, and under which flow*.
+`@lensmcp/memory-tracker` instruments the mutating methods of `Map`, `Set`, and `Array` instances in place. Every mutation updates a per-container "owner" record (item count plus a rough byte estimate) and is attributed to the active request/flow. When a flow grows a container past a threshold and the items do not shrink back, the tracker emits a `memory-retention` ("memory leak suspected") event. The result is a deterministic, attributable memory signal in the LensMCP lens — instead of a flat heap graph, you see *which owner grew, by how much, and under which flow*.
 
 It is designed to run in "light mode" inside the LensMCP node/NestJS instrumentation: zero sampling timers in the hot path, bounded per-mutation work, and a pluggable event sink so the host process forwards events to the LensMCP bus.
 
@@ -33,7 +33,6 @@ configureMemoryTracker({
   sessionId: 'session-123',
   sink: (event) => bus.publish(event),
   leakItemThreshold: 50,                       // items of growth that flips a suspected leak (default 50)
-  staleGenerationBytesThreshold: 1024 * 1024,  // bytes a disposed singleton may retain (default 1 MB)
   settleMs: 1000,                              // grace period after a flow ends (default 1000)
   contextGetter: () => currentLensmcpContext(), // optional: returns { sessionId, flowId?, requestId?, originNodeId? }
 });
@@ -64,13 +63,12 @@ const flaggedOwnerIds = onFlowSettled('req-42'); // string[] of suspected-leak o
 
 ## API
 
-- **`configureMemoryTracker(opts)`** — Set the active session id, the event `sink`, the optional `contextGetter`, and detector thresholds (`leakItemThreshold`, `staleGenerationBytesThreshold`, `settleMs`). Returns the resolved options. Must be called before events are emitted.
+- **`configureMemoryTracker(opts)`** — Set the active session id, the event `sink`, the optional `contextGetter`, and detector thresholds (`leakItemThreshold`, `settleMs`). Returns the resolved options. Must be called before events are emitted. (`staleGenerationBytesThreshold` is still accepted and ignored.)
 - **`trackContainer({ ownerInstanceId, fieldName, container })`** — Instrument a `Map`/`Set`/`Array` in place so each mutation updates its owner record and emits a `memory-mutation` event. Idempotent and non-destructive.
 - **`onFlowStart(flowId)`** — Snapshot every owner's item count at the start of a flow.
 - **`onFlowSettled(flowId)`** — Compare each owner's attributed growth against `leakItemThreshold`; emit `memory-retention` for owners that grew and stayed resident. Returns the flagged owner ids.
-- **`checkStaleGeneration({ logicalId, instanceId, generation, retainedBytes })`** — On singleton disposal, emit `singleton-stale-generation` when retained bytes exceed `staleGenerationBytesThreshold`. Returns whether it flagged.
 - **`allOwners()` / `getOwner(ownerId)` / `ownerKey(ownerInstanceId, fieldName)`** — Inspect the owner registry: list owner snapshots, fetch one record, or compute an owner key (`<ownerInstanceId>::<fieldName>`).
-- **`emitMutation` / `emitRetention` / `emitStaleGeneration`** — Low-level emit helpers that build each memory `BaseEvent` and push it to the sink (used internally; exported for advanced hosts).
+- **`emitMutation` / `emitRetention`** — Low-level emit helpers that build each memory `BaseEvent` and push it to the sink (used internally; exported for advanced hosts).
 - **`activeMemoryOptions()` / `currentMemoryContext()` / `resetMemoryTracker()`** — Read the resolved options, read the current flow context, or reset tracker state (test hook).
 - **`markFlowStart` / `recordFlowDelta` / `flowGrowth` / `ensureOwner` / `resetOwners`** — Lower-level owner/flow primitives behind the detectors.
 - **Types** — `MemoryEventSink`, `MemoryContext`, `ResolvedMemoryOptions`, `MemoryOwnerSnapshot`, `MemoryContainerKind`, `MemoryMutationOperation`, and the `TrackContainerArgs` input.
@@ -79,11 +77,13 @@ const flaggedOwnerIds = onFlowSettled('req-42'); // string[] of suspected-leak o
 
 `@lensmcp/memory-tracker` is enabled by `@lensmcp/nest-instrumentation` via its `memory` option (the node instrumentation does the same). The host supplies the `sessionId`, the event `sink`, and a `contextGetter` bound to its own request context, and brackets each request with `onFlowStart` / `onFlowSettled`.
 
-Every event is a `@lensmcp/protocol-types` `BaseEvent` with `source` and `category` of `memory`, carrying one of three payload kinds:
+Every event is a `@lensmcp/protocol-types` `BaseEvent` with `source` and `category` of `memory`, carrying one of two payload kinds:
 
 - `memory-mutation` — `debug` severity; per-mutation before/after counts and an estimated byte delta.
 - `memory-retention` — `warning` severity; the "memory leak suspected" signal (owner id, flow, growth) surfaced in the lens.
-- `singleton-stale-generation` — `warning` severity; a disposed singleton generation still retaining bytes.
+
+A hot-swapped app generation that stays in memory after its close is not this package's signal: the dev cluster's
+pod proves it from the heap itself and publishes `pod-memory-retained` (see `lensmcp mem`).
 
 These events flow through the host's sink to the LensMCP bus, where the lens renders them in the **"memory leak suspected"** channel.
 

package/index.d.ts

@@ -2,5 +2,5 @@ export { configureMemoryTracker, activeMemoryOptions, currentMemoryContext, rese
 export { trackContainer, type TrackContainerArgs } from './lib/track-container.js';
 export { ensureOwner, allOwners, getOwner, ownerKey, resetOwners, markFlowStart, recordFlowDelta, flowGrowth, } from './lib/owners.js';
 export { emitMutation, emitRetention, emitStaleGeneration } from './lib/emit.js';
-export { onFlowStart, onFlowSettled, checkStaleGeneration, } from './lib/detectors.js';
+export { onFlowStart, onFlowSettled, checkStaleGeneration } from './lib/detectors.js';
 export type { MemoryEventSink, MemoryContext, ResolvedMemoryOptions, MemoryOwnerSnapshot, MemoryContainerKind, MemoryMutationOperation, } from './lib/types.js';

package/lib/context.d.ts

@@ -11,6 +11,7 @@ export declare function configureMemoryTracker(opts: {
     sessionId: string;
     sink: MemoryEventSink;
     leakItemThreshold?: number;
+    /** @deprecated Ignored — see `ResolvedMemoryOptions.staleGenerationBytesThreshold`. */
     staleGenerationBytesThreshold?: number;
     settleMs?: number;
     contextGetter?: ContextGetter;

package/lib/detectors.d.ts

@@ -5,6 +5,12 @@ export declare function onFlowStart(flowId: string): void;
  * the list of flagged owner ids (also useful for tests).
  */
 export declare function onFlowSettled(flowKey: string, flowId?: string): string[];
+/**
+ * @deprecated Kept for API compatibility only — nothing in LensMCP calls it, because no host can
+ * measure a disposed singleton's retained bytes cheaply. A hot-swapped generation that outlives its
+ * close is proven by `@lensmcp/cluster` itself (`pod-memory-retained`, issues/closed/pod-memory-02).
+ * Will be removed in the next major version.
+ */
 export declare function checkStaleGeneration(args: {
     logicalId: string;
     instanceId: string;

package/lib/emit.d.ts

@@ -22,6 +22,11 @@ export declare function emitRetention(args: {
     context?: MemoryContext;
     timestamp?: number;
 }): void;
+/**
+ * @deprecated Kept for API compatibility only (see `checkStaleGeneration`). Hot-swap generations that
+ * outlive their close are reported by `@lensmcp/cluster` as `pod-memory-retained`. Will be removed in the
+ * next major version.
+ */
 export declare function emitStaleGeneration(args: {
     options: ResolvedMemoryOptions;
     logicalId: string;

package/lib/types.d.ts

@@ -19,7 +19,11 @@ export interface ResolvedMemoryOptions {
     sink: MemoryEventSink;
     /** Owner growth (in items) within a flow that flips a suspected leak. Default 50. */
     leakItemThreshold: number;
-    /** Bytes retained by a disposed singleton that flags stale-generation. Default 1MB. */
+    /**
+     * @deprecated Read by nothing since `checkStaleGeneration` was removed (it had no caller); kept so existing
+     * `configureMemoryTracker` calls still compile. Stale hot-swap generations are reported by the cluster pod
+     * (`pod-memory-retained`).
+     */
     staleGenerationBytesThreshold: number;
     /** ms to wait after flow end before checking owner shrinkage. Default 1000. */
     settleMs: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/memory-tracker",
-  "version": "1.23.13",
+  "version": "1.24.0",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",
@@ -14,7 +14,7 @@
     }
   },
   "dependencies": {
-    "@lensmcp/protocol-types": "1.23.13",
+    "@lensmcp/protocol-types": "1.24.0",
     "tslib": "^2.3.0"
   },
   "license": "Apache-2.0",