@zakkster/lite-perf-gate 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -22,6 +22,18 @@ Three signals: scavenge count (transient allocation), custom counters
 Scaling verdict: measure at N and k*N. Detector self-validation: the gate
 refuses to judge if the controls misbehave.
 
+### CI tuning
+
+- `flushMs` option (default 100ms; env var `PERF_GATE_FLUSH_MS`) controls
+  how long the harness waits after the hot loop before reading the
+  perf_hooks GC observer buffer. Bump to 250-500ms on noisy CI runners
+  where event-loop stalls can drop GC entries.
+- `gc2()` yields a `setImmediate` tick between its two `globalThis.gc()`
+  passes so any `FinalizationRegistry` cleanups scheduled by the first
+  pass run before the second. Prevents WeakRef/finalizer-driven teardown
+  (used in `lite-cleanup`, `lite-observe`, `lite-floating`) from leaving
+  the heap in an intermediate state and inflating retained deltas.
+
 ### Tests
 
 12 self-tests covering controls, verdict logic, counter deltas, and

package/PerfGate.d.ts

@@ -79,6 +79,12 @@ export interface GateConfig {
     negativeControl?: Scenario;
     /** Scenarios that MUST trip the gate (injected allocation self-tests). */
     mustFail?: Scenario[];
+    /**
+     * Wait (ms) after the hot loop before reading the GC observer buffer.
+     * Default 100 (or PERF_GATE_FLUSH_MS env var). Bump to 250-500 on
+     * noisy CI runners where event-loop stalls > 100ms may drop entries.
+     */
+    flushMs?: number;
 }
 
 export interface GateResult {
@@ -91,7 +97,7 @@ export interface GateResult {
  */
 export function measure(
     scenario: Scenario,
-    options?: { N?: number; k?: number }
+    options?: { N?: number; k?: number; flushMs?: number }
 ): Promise<MeasureResult>;
 
 /**

package/PerfGate.js

@@ -48,33 +48,53 @@ function makeGcCounter() {
     };
 }
 
-function gc2() {
+async function gc2() {
     if (typeof globalThis.gc === 'function') {
         globalThis.gc();
+        // Yield one task tick so any FinalizationRegistry cleanup callbacks
+        // registered from the first gc() get a chance to run before the
+        // second pass. Without this, WeakRef/FinalizationRegistry-driven
+        // teardown (used across the ecosystem in lite-cleanup / lite-observe
+        // / lite-floating) can leave the heap in an intermediate state
+        // between the two collections, inflating the retained delta.
+        await new Promise(function (r) { setImmediate(r); });
         globalThis.gc();
     }
 }
 
+// Default post-hot sleep before reading the GC observer buffer. The Node
+// perf_hooks 'gc' entries are delivered asynchronously, so we need to yield
+// long enough for the observer callback to fire. 100ms is a safe floor on
+// most systems; noisy CI runners (shared GitHub Actions, Docker under
+// contention) can stall the event loop for tens of milliseconds and drop
+// entries with a shorter wait. Override per-measurement via the `flushMs`
+// option, or globally via the PERF_GATE_FLUSH_MS environment variable.
+var DEFAULT_FLUSH_MS = 100;
+if (typeof process !== 'undefined' && process.env && process.env.PERF_GATE_FLUSH_MS) {
+    var envMs = parseInt(process.env.PERF_GATE_FLUSH_MS, 10);
+    if (envMs > 0 && envMs < 60000) DEFAULT_FLUSH_MS = envMs;
+}
+
 // ---------------------------------------------------------------------------
 // Core measurement
 // ---------------------------------------------------------------------------
 
-async function meterOnce(scenario, iters) {
+async function meterOnce(scenario, iters, flushMs) {
     const state = scenario.setup();
     scenario.hot(state, Math.min(iters, 20000));
-    gc2();
+    await gc2();
 
     const statsBefore = scenario.statsOf ? scenario.statsOf(state) : null;
     const heapBefore = process.memoryUsage().heapUsed;
 
     const gcc = makeGcCounter();
     scenario.hot(state, iters);
-    await sleep(40);
+    await sleep(flushMs);
     const minor = gcc.c.minor;
     const major = gcc.c.major;
     gcc.close();
 
-    gc2();
+    await gc2();
     const heapAfter = process.memoryUsage().heapUsed;
     const statsAfter = scenario.statsOf ? scenario.statsOf(state) : null;
     if (scenario.teardown) scenario.teardown(state);
@@ -114,14 +134,19 @@ async function meterOnce(scenario, iters) {
  * allocation via scavenge scaling.
  *
  * @param {Scenario} scenario
- * @param {{ N?: number, k?: number }} [options]
+ * @param {{ N?: number, k?: number, flushMs?: number }} [options]
+ *   flushMs: how long to wait after the hot loop before reading the GC
+ *   observer buffer. Default 100ms (or PERF_GATE_FLUSH_MS env var).
+ *   Bump if you see zero scavenges on scenarios that should allocate --
+ *   noisy CI runners may need 250-500ms.
  * @returns {Promise<MeasureResult>}
  */
 export async function measure(scenario, options) {
     const N = (options && options.N) || 200000;
     const k = (options && options.k) || 8;
-    const lo = await meterOnce(scenario, N);
-    const hi = await meterOnce(scenario, k * N);
+    const flushMs = (options && options.flushMs) || DEFAULT_FLUSH_MS;
+    const lo = await meterOnce(scenario, N, flushMs);
+    const hi = await meterOnce(scenario, k * N, flushMs);
     return {
         name: scenario.name, N: N, k: k,
         minorLo: lo.minor, minorHi: hi.minor,
@@ -264,7 +289,7 @@ export function formatResult(r) {
  */
 export function zgcSuite(config) {
     const scenarios = config.scenarios;
-    const opts = {N: config.N || 200000, k: config.k || 8};
+    const opts = {N: config.N || 200000, k: config.k || 8, flushMs: config.flushMs};
     const thresholds = {
         maxScavenges: config.maxScavenges !== undefined ? config.maxScavenges : 2,
         maxRetainedKB: config.maxRetainedKB !== undefined ? config.maxRetainedKB : 64,
@@ -327,7 +352,7 @@ export function zgcSuite(config) {
  */
 export async function runGate(config) {
     const scenarios = config.scenarios;
-    const opts = {N: config.N || 200000, k: config.k || 8};
+    const opts = {N: config.N || 200000, k: config.k || 8, flushMs: config.flushMs};
     const thresholds = {
         maxScavenges: config.maxScavenges !== undefined ? config.maxScavenges : 2,
         maxRetainedKB: config.maxRetainedKB !== undefined ? config.maxRetainedKB : 64,

package/README.md

@@ -134,6 +134,18 @@ Two V8 gotchas the controls handle:
 
 The default V8 semi-space is 16MB. At 200k iterations of 64-byte objects, you produce ~12MB -- possibly fitting without a single scavenge. `--max-semi-space-size=4` shrinks the young generation to 4MB, forcing scavenges on smaller cumulative allocation and sharpening sensitivity. The four-field positive control (`{x,y,z,w}`) provides margin even without this flag, but the flag is recommended for production gates.
 
+## CI tuning
+
+Node's `perf_hooks` delivers GC entries to the observer asynchronously. After the hot loop the harness waits before reading the entry count so the observer has time to flush. Default wait is **100ms**, which is safe on a dev machine but can be marginal on saturated CI runners.
+
+If you see intermittent zero-scavenge reports on scenarios that clearly allocate:
+
+- Bump globally via env var: `PERF_GATE_FLUSH_MS=300 node --test ...`
+- Per-suite: `zgcSuite({ scenarios, flushMs: 300 })`
+- Per-call: `measure(scenario, { flushMs: 500 })`
+
+`gc2()` (the harness's forced-collection helper) does one `gc()`, yields a `setImmediate` tick to let `FinalizationRegistry` cleanups run, then does a second `gc()`. Without the yield, WeakRef/finalizer-driven teardown (used across the ecosystem in `lite-cleanup`, `lite-observe`, `lite-floating`) can leave the heap in an intermediate state between the two collections and inflate the retained-heap delta.
+
 ## License
 
 MIT (c) Zahary Shinikchiev

package/llms.txt

@@ -21,8 +21,9 @@ zgcSuite(config) -- register node:test cases.
   config.counters: Record<string, number>  -- per-counter max delta.
   config.mustFail: Scenario[]    -- must trip the gate (self-test).
   config.N: number (default 200000), config.k: number (default 8).
+  config.flushMs: number (default 100, or PERF_GATE_FLUSH_MS env var).
 
-measure(scenario, {N, k}) -- raw MeasureResult.
+measure(scenario, {N, k, flushMs}) -- raw MeasureResult.
 verdict(result, thresholds) -- { pass: boolean, reasons: string[] }.
 runGate(config) -- standalone report, same config as zgcSuite.
 
@@ -39,6 +40,19 @@ node --expose-gc --max-semi-space-size=4 --test your.test.mjs
 
 --expose-gc is required. --max-semi-space-size=4 sharpens sensitivity.
 
+## CI tuning
+
+perf_hooks delivers GC entries asynchronously. Default 100ms wait after
+hot loop is safe on dev machines but can be marginal on saturated CI
+runners. If scenarios that should allocate report zero scavenges, bump
+flushMs (via option) or PERF_GATE_FLUSH_MS env var to 250-500ms.
+
+gc2() yields a setImmediate tick between its two gc() calls so any
+FinalizationRegistry cleanups scheduled by the first run before the
+second. Essential for ecosystems using WeakRef/FinalizationRegistry
+(lite-cleanup / lite-observe / lite-floating) -- without it the two-pass
+GC can leave the heap in an intermediate state and inflate retained deltas.
+
 ## Why scavenge counting
 
 Retained-heap delta misses transient garbage (freed before snapshot).

package/package.json

@@ -1,63 +1,63 @@
 {
-  "name": "@zakkster/lite-perf-gate",
-  "version": "1.0.0",
-  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "description": "Zero-GC and performance regression gate for node:test. Scavenge-counting, scaling verdict, detector self-validation. Proves your hot path allocates nothing -- or names what did.",
-  "type": "module",
-  "sideEffects": false,
-  "main": "./PerfGate.js",
-  "module": "./PerfGate.js",
-  "types": "./PerfGate.d.ts",
-  "exports": {
-    ".": {
-      "types": "./PerfGate.d.ts",
-      "node": "./PerfGate.js",
-      "import": "./PerfGate.js",
-      "default": "./PerfGate.js"
+    "name": "@zakkster/lite-perf-gate",
+    "version": "1.0.1",
+    "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+    "description": "Zero-GC and performance regression gate for node:test. Scavenge-counting, scaling verdict, detector self-validation. Proves your hot path allocates nothing -- or names what did.",
+    "type": "module",
+    "sideEffects": false,
+    "main": "./PerfGate.js",
+    "module": "./PerfGate.js",
+    "types": "./PerfGate.d.ts",
+    "exports": {
+        ".": {
+            "types": "./PerfGate.d.ts",
+            "node": "./PerfGate.js",
+            "import": "./PerfGate.js",
+            "default": "./PerfGate.js"
+        }
+    },
+    "files": [
+        "PerfGate.js",
+        "PerfGate.d.ts",
+        "README.md",
+        "llms.txt",
+        "LICENSE",
+        "CHANGELOG.md"
+    ],
+    "scripts": {
+        "test": "node --expose-gc --max-semi-space-size=4 --test test/self.test.mjs"
+    },
+    "keywords": [
+        "benchmark",
+        "regression",
+        "gate",
+        "zero-gc",
+        "gc",
+        "scavenge",
+        "allocation",
+        "performance",
+        "node-test",
+        "ci",
+        "perf-hooks"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "license": "MIT",
+    "homepage": "https://github.com/PeshoVurtoleta/lite-perf-gate#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/PeshoVurtoleta/lite-perf-gate.git"
+    },
+    "bugs": {
+        "url": "https://github.com/PeshoVurtoleta/lite-perf-gate/issues",
+        "email": "shinikchiev@yahoo.com"
+    },
+    "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/PeshoVurtoleta"
+    },
+    "engines": {
+        "node": ">=18"
     }
-  },
-  "files": [
-    "PerfGate.js",
-    "PerfGate.d.ts",
-    "README.md",
-    "llms.txt",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "test": "node --expose-gc --max-semi-space-size=4 --test test/self.test.mjs"
-  },
-  "keywords": [
-    "benchmark",
-    "regression",
-    "gate",
-    "zero-gc",
-    "gc",
-    "scavenge",
-    "allocation",
-    "performance",
-    "node-test",
-    "ci",
-    "perf-hooks"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "homepage": "https://github.com/PeshoVurtoleta/lite-perf-gate#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/PeshoVurtoleta/lite-perf-gate.git"
-  },
-  "bugs": {
-    "url": "https://github.com/PeshoVurtoleta/lite-perf-gate/issues",
-    "email": "shinikchiev@yahoo.com"
-  },
-  "funding": {
-    "type": "github",
-    "url": "https://github.com/sponsors/PeshoVurtoleta"
-  },
-  "engines": {
-    "node": ">=18"
-  }
 }