@zakkster/lite-perf-gate 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [1.0.0] - 2026-07-07
+
+Initial release. Generalized from the `@zakkster/lite-signal` zero-GC gate
+(`test/zgc/`) into a standalone, engine-agnostic library.
+
+### Public API
+
+- **`zgcSuite(config)`** -- register `node:test` cases for detector
+  validation, scenario gating, and must-fail self-tests.
+- **`measure(scenario, options?)`** -- raw measurement at N and k*N.
+- **`verdict(result, thresholds?)`** -- evaluate against thresholds.
+- **`runGate(config)`** -- standalone human-readable report.
+- **`formatResult(result)`** -- one-line summary.
+- **`controlPositive` / `controlNegative`** -- built-in detector controls.
+
+### Methodology
+
+Three signals: scavenge count (transient allocation), custom counters
+(exact engine internals via `statsOf`), retained-heap delta (leaks).
+Scaling verdict: measure at N and k*N. Detector self-validation: the gate
+refuses to judge if the controls misbehave.
+
+### Tests
+
+12 self-tests covering controls, verdict logic, counter deltas, and
+result shape.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PerfGate.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @zakkster/lite-perf-gate
+ * Zero-GC and performance regression gate for node:test.
+ *
+ * Copyright (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License
+ */
+
+export declare const VERSION: string;
+
+/** A measurement scenario. Engine-agnostic. */
+export interface Scenario<State = any> {
+    /** Human-readable name shown in reports and test labels. */
+    name: string;
+    /** Build the graph / state. Called once per measurement pass. */
+    setup(): State;
+    /**
+     * The hot loop. Must run `n` iterations against `state`. This is the
+     * ONLY code inside the measurement window.
+     */
+    hot(state: State, n: number): void;
+    /**
+     * Return an object of numeric counters (e.g. `{ poolGrowths: 0 }`).
+     * Called before and after the hot loop; deltas are computed automatically.
+     */
+    statsOf?(state: State): Record<string, number>;
+    /** Clean up after measurement. */
+    teardown?(state: State): void;
+}
+
+export interface MeasureResult {
+    name: string;
+    N: number;
+    k: number;
+    /** Minor GC (scavenge) count at N iterations. */
+    minorLo: number;
+    /** Minor GC (scavenge) count at k*N iterations. */
+    minorHi: number;
+    majorLo: number;
+    majorHi: number;
+    retainedKB_lo: number;
+    retainedKB_hi: number;
+    /** Custom counter deltas at N, or null if no statsOf. */
+    counters_lo: Record<string, number> | null;
+    /** Custom counter deltas at k*N, or null if no statsOf. */
+    counters_hi: Record<string, number> | null;
+}
+
+export interface Thresholds {
+    /** Max allowed scavenges at k*N. Default 2. */
+    maxScavenges?: number;
+    /** Max retained heap growth in KB. Default 64. */
+    maxRetainedKB?: number;
+    /** Per-counter maximum allowed delta. */
+    counters?: Record<string, number>;
+}
+
+export interface Verdict {
+    pass: boolean;
+    reasons: string[];
+}
+
+export interface GateConfig {
+    /** Zero-GC scenarios to gate. */
+    scenarios: Scenario[];
+    /** Iteration count (low). Default 200000. */
+    N?: number;
+    /** Scale factor (high = k*N). Default 8. */
+    k?: number;
+    /** Max allowed scavenges at k*N. Default 2. */
+    maxScavenges?: number;
+    /** Max retained heap growth in KB. Default 64. */
+    maxRetainedKB?: number;
+    /** Counter thresholds for statsOf deltas. */
+    counters?: Record<string, number>;
+    /** Override positive control. */
+    positiveControl?: Scenario;
+    /** Override negative control. */
+    negativeControl?: Scenario;
+    /** Scenarios that MUST trip the gate (injected allocation self-tests). */
+    mustFail?: Scenario[];
+}
+
+export interface GateResult {
+    passed: boolean;
+    results: MeasureResult[];
+}
+
+/**
+ * Measure a scenario at N and k*N iterations. Returns raw measurements.
+ */
+export function measure(
+    scenario: Scenario,
+    options?: { N?: number; k?: number }
+): Promise<MeasureResult>;
+
+/**
+ * Evaluate a measurement result against thresholds.
+ */
+export function verdict(r: MeasureResult, thresholds?: Thresholds): Verdict;
+
+/** One-line summary of a measurement result. */
+export function formatResult(r: MeasureResult): string;
+
+/** Built-in positive control (allocates per iteration). */
+export const controlPositive: Scenario;
+
+/** Built-in negative control (pure arithmetic, zero allocation). */
+export const controlNegative: Scenario;
+
+/**
+ * Register node:test cases: detector validation, scenario gating, and
+ * must-fail self-tests. The primary public API.
+ *
+ * Run with: `node --expose-gc --max-semi-space-size=4 --test your.test.mjs`
+ */
+export function zgcSuite(config: GateConfig): void;
+
+/**
+ * Standalone human-readable gate report. Returns pass/fail and raw results.
+ */
+export function runGate(config: GateConfig): Promise<GateResult>;
+
+/** @internal */
+export function _controlKeepAlive(): number;

package/PerfGate.js

@@ -0,0 +1,405 @@
+/**
+ * @zakkster/lite-perf-gate
+ * Zero-GC and performance regression gate for node:test.
+ *
+ * Three measurement signals, each for what it can actually see:
+ *   1. Scavenge count (perf_hooks 'gc', minor) -- the reliable detector
+ *      of TRANSIENT allocation. Retained-heap misses it (freed before
+ *      snapshot); the V8 sampling profiler misses it (reports live-at-stop).
+ *   2. Custom counters (user-supplied statsOf) -- exact engine internals.
+ *   3. Retained-heap delta (memoryUsage + gc) -- leak detector.
+ *
+ * Pass/fail uses scaling: measure at N and k*N. Zero-alloc => ~0 scavenges
+ * at both; allocation => scavenges scale with total bytes. Controls validate
+ * the detector on every run.
+ *
+ * Copyright (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License
+ */
+
+export const VERSION = '1.0.0';
+
+import {PerformanceObserver, constants} from 'node:perf_hooks';
+import {setTimeout as sleep} from 'node:timers/promises';
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+
+const MINOR = constants.NODE_PERFORMANCE_GC_MINOR;
+const MAJOR = constants.NODE_PERFORMANCE_GC_MAJOR;
+
+// ---------------------------------------------------------------------------
+// GC counter
+// ---------------------------------------------------------------------------
+
+function makeGcCounter() {
+    const c = {minor: 0, major: 0};
+    const obs = new PerformanceObserver(function (list) {
+        for (const e of list.getEntries()) {
+            const k = e.detail ? e.detail.kind : e.kind;
+            if (k === MINOR) c.minor++;
+            else if (k === MAJOR) c.major++;
+        }
+    });
+    obs.observe({entryTypes: ['gc']});
+    return {
+        c: c, close: function () {
+            obs.disconnect();
+        }
+    };
+}
+
+function gc2() {
+    if (typeof globalThis.gc === 'function') {
+        globalThis.gc();
+        globalThis.gc();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Core measurement
+// ---------------------------------------------------------------------------
+
+async function meterOnce(scenario, iters) {
+    const state = scenario.setup();
+    scenario.hot(state, Math.min(iters, 20000));
+    gc2();
+
+    const statsBefore = scenario.statsOf ? scenario.statsOf(state) : null;
+    const heapBefore = process.memoryUsage().heapUsed;
+
+    const gcc = makeGcCounter();
+    scenario.hot(state, iters);
+    await sleep(40);
+    const minor = gcc.c.minor;
+    const major = gcc.c.major;
+    gcc.close();
+
+    gc2();
+    const heapAfter = process.memoryUsage().heapUsed;
+    const statsAfter = scenario.statsOf ? scenario.statsOf(state) : null;
+    if (scenario.teardown) scenario.teardown(state);
+
+    let counters = null;
+    if (statsBefore !== null && statsAfter !== null) {
+        counters = {};
+        for (const key in statsAfter) {
+            if (typeof statsAfter[key] === 'number' && typeof statsBefore[key] === 'number') {
+                counters[key] = statsAfter[key] - statsBefore[key];
+            }
+        }
+    }
+
+    return {minor: minor, major: major, retainedKB: (heapAfter - heapBefore) / 1024, counters: counters};
+}
+
+// ---------------------------------------------------------------------------
+// measure -- public, returns raw numbers
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} Scenario
+ * @property {string} name
+ * @property {() => any} setup          Build the graph / state. Called once.
+ * @property {(state: any, n: number) => void} hot
+ *   The hot loop. Must run `n` iterations against `state`. This is the ONLY
+ *   code inside the measurement window.
+ * @property {(state: any) => object} [statsOf]
+ *   Return an object of numeric counters. Called before and after; deltas
+ *   are computed automatically.
+ * @property {(state: any) => void} [teardown]
+ */
+
+/**
+ * Measure a scenario at two iteration counts (N and k*N) to detect
+ * allocation via scavenge scaling.
+ *
+ * @param {Scenario} scenario
+ * @param {{ N?: number, k?: number }} [options]
+ * @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);
+    return {
+        name: scenario.name, N: N, k: k,
+        minorLo: lo.minor, minorHi: hi.minor,
+        majorLo: lo.major, majorHi: hi.major,
+        retainedKB_lo: lo.retainedKB, retainedKB_hi: hi.retainedKB,
+        counters_lo: lo.counters, counters_hi: hi.counters
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Built-in controls
+// ---------------------------------------------------------------------------
+
+const __posKeep = [];
+
+/** @internal -- reference to keep the positive-control sink alive. */
+export function _controlKeepAlive() {
+    return __posKeep.length;
+}
+
+/** Positive control: allocates a heap object per iteration. */
+export const controlPositive = {
+    name: 'CONTROL+ (allocates {x,y,z,w} per iter)',
+    setup: function () {
+        return {};
+    },
+    hot: function (_s, n) {
+        for (let i = 0; i < n; i++) __posKeep.push({x: i, y: i + 1, z: i + 2, w: i + 3});
+        if (__posKeep.length > 3000000) __posKeep.length = 0;
+    }
+};
+
+/** Negative control: pure arithmetic, zero allocation. */
+export const controlNegative = {
+    name: 'CONTROL- (pure arithmetic)',
+    setup: function () {
+        return {acc: 0};
+    },
+    hot: function (s, n) {
+        let a = s.acc;
+        for (let i = 0; i < n; i++) a += (i * 3) ^ i;
+        s.acc = a;
+    }
+};
+
+// ---------------------------------------------------------------------------
+// Verdict
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate a measurement against thresholds.
+ *
+ * @param {MeasureResult} r
+ * @param {object} [thresholds]
+ * @param {number} [thresholds.maxScavenges=2]
+ * @param {number} [thresholds.maxRetainedKB=64]
+ * @param {Record<string, number>} [thresholds.counters]
+ *   Per-counter maximum allowed delta. E.g. `{ poolGrowths: 0 }`.
+ * @returns {{ pass: boolean, reasons: string[] }}
+ */
+export function verdict(r, thresholds) {
+    const maxScav = (thresholds && thresholds.maxScavenges !== undefined) ? thresholds.maxScavenges : 2;
+    const maxRetKB = (thresholds && thresholds.maxRetainedKB !== undefined) ? thresholds.maxRetainedKB : 64;
+    const ct = (thresholds && thresholds.counters) || null;
+    const reasons = [];
+
+    if (r.minorHi > maxScav) {
+        reasons.push('scavenges: ' + r.minorHi + ' > ' + maxScav + ' (transient allocation)');
+    }
+    if (r.retainedKB_hi > maxRetKB) {
+        reasons.push('retained: ' + r.retainedKB_hi.toFixed(0) + 'KB > ' + maxRetKB + 'KB');
+    }
+    if (ct !== null && r.counters_hi !== null) {
+        for (const key in ct) {
+            const actual = r.counters_hi[key];
+            if (actual !== undefined && actual > ct[key]) {
+                reasons.push(key + ': ' + actual + ' > ' + ct[key]);
+            }
+        }
+    }
+    return {pass: reasons.length === 0, reasons: reasons};
+}
+
+// ---------------------------------------------------------------------------
+// Format
+// ---------------------------------------------------------------------------
+
+/**
+ * One-line summary of a measurement result.
+ * @param {MeasureResult} r
+ * @returns {string}
+ */
+export function formatResult(r) {
+    let s = r.name +
+        '\n    scavenges  N:' + String(r.minorLo).padStart(3) +
+        '  ' + r.k + 'N:' + String(r.minorHi).padStart(3) +
+        '   retained ' + r.retainedKB_hi.toFixed(0) + 'KB';
+    if (r.counters_hi !== null) {
+        for (const key in r.counters_hi) {
+            s += '   ' + key + ' \u0394' + String(r.counters_hi[key]).padStart(6);
+        }
+    }
+    return s;
+}
+
+// ---------------------------------------------------------------------------
+// zgcSuite -- the node:test integration (primary public API)
+// ---------------------------------------------------------------------------
+
+/**
+ * Register node:test cases that validate detector controls, measure each
+ * scenario, and assert the zero-GC verdict.
+ *
+ * @example
+ *   import { zgcSuite } from '@zakkster/lite-perf-gate';
+ *
+ *   zgcSuite({
+ *       scenarios: [
+ *           { name: 'deep chain', setup: buildDeep, hot: runDeep,
+ *             statsOf: s => s.registry.stats() },
+ *       ],
+ *       counters: { poolGrowths: 0, totalAllocations: 0 },
+ *       mustFail: [injectedAllocScenario]
+ *   });
+ *
+ * Run with: node --expose-gc --max-semi-space-size=4 --test your.test.mjs
+ *
+ * @param {object} config
+ * @param {Scenario[]} config.scenarios       Zero-GC scenarios to gate.
+ * @param {number} [config.N=200000]          Iteration count (low).
+ * @param {number} [config.k=8]              Scale factor (high = k*N).
+ * @param {number} [config.maxScavenges=2]    Max allowed scavenges at k*N.
+ * @param {number} [config.maxRetainedKB=64]  Max retained heap growth.
+ * @param {Record<string, number>} [config.counters]
+ *   Counter thresholds for statsOf deltas.
+ * @param {Scenario} [config.positiveControl]  Override positive control.
+ * @param {Scenario} [config.negativeControl]  Override negative control.
+ * @param {Scenario[]} [config.mustFail]
+ *   Scenarios that MUST trip the gate (injected allocation self-tests).
+ */
+export function zgcSuite(config) {
+    const scenarios = config.scenarios;
+    const opts = {N: config.N || 200000, k: config.k || 8};
+    const thresholds = {
+        maxScavenges: config.maxScavenges !== undefined ? config.maxScavenges : 2,
+        maxRetainedKB: config.maxRetainedKB !== undefined ? config.maxRetainedKB : 64,
+        counters: config.counters || null
+    };
+    const posCtrl = config.positiveControl || controlPositive;
+    const negCtrl = config.negativeControl || controlNegative;
+    const mustFail = config.mustFail || [];
+    const maxScav = thresholds.maxScavenges;
+
+    test('perf-gate: detector sees a known allocation (positive control)', async function () {
+        const r = await measure(posCtrl, opts);
+        _controlKeepAlive();
+        assert.ok(r.minorHi > maxScav + 3,
+            'positive control should force scavenges, saw ' + r.minorHi +
+            ' (need >' + (maxScav + 3) + '). Run with --expose-gc --max-semi-space-size=4.');
+    });
+
+    test('perf-gate: detector reads ~0 for a non-allocating loop (negative control)', async function () {
+        const r = await measure(negCtrl, opts);
+        assert.ok(r.minorHi <= maxScav,
+            'no-op control forced ' + r.minorHi + ' scavenges (need <=' + maxScav + ')');
+    });
+
+    for (let i = 0; i < scenarios.length; i++) {
+        (function (sc) {
+            test('zero-GC: ' + sc.name, async function () {
+                const r = await measure(sc, opts);
+                const v = verdict(r, thresholds);
+                assert.ok(v.pass,
+                    sc.name + ' FAILED:\n  ' + v.reasons.join('\n  ') +
+                    '\n  ' + formatResult(r));
+            });
+        })(scenarios[i]);
+    }
+
+    for (let j = 0; j < mustFail.length; j++) {
+        (function (sc) {
+            test('perf-gate: MUST CATCH ' + sc.name, async function () {
+                const r = await measure(sc, opts);
+                const v = verdict(r, thresholds);
+                assert.ok(!v.pass,
+                    'gate failed to flag a known allocation: ' + sc.name +
+                    '\n  ' + formatResult(r));
+            });
+        })(mustFail[j]);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// runGate -- standalone human-readable report
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a gate check and print a human-readable report. Exit codes:
+ *   0 = pass, 1 = allocation detected, 2 = detector validation failed.
+ *
+ * @param {object} config  Same shape as zgcSuite.
+ * @returns {Promise<{ passed: boolean, results: MeasureResult[] }>}
+ */
+export async function runGate(config) {
+    const scenarios = config.scenarios;
+    const opts = {N: config.N || 200000, k: config.k || 8};
+    const thresholds = {
+        maxScavenges: config.maxScavenges !== undefined ? config.maxScavenges : 2,
+        maxRetainedKB: config.maxRetainedKB !== undefined ? config.maxRetainedKB : 64,
+        counters: config.counters || null
+    };
+    const posCtrl = config.positiveControl || controlPositive;
+    const negCtrl = config.negativeControl || controlNegative;
+    const mustFail = config.mustFail || [];
+    const maxScav = thresholds.maxScavenges;
+    const N = opts.N;
+    const k = opts.k;
+
+    console.log('Zero-GC gate \u2014 scavenge scaling (N=' + N + ', ' + k + 'N=' + (k * N) + ')\n');
+
+    const pos = await measure(posCtrl, opts);
+    const neg = await measure(negCtrl, opts);
+    console.log('== controls ==');
+    console.log(formatResult(pos));
+    console.log(formatResult(neg));
+    _controlKeepAlive();
+
+    if (pos.minorHi <= maxScav + 3 || neg.minorHi > maxScav) {
+        console.log('\n!! DETECTOR VALIDATION FAILED: positive ' + pos.minorHi +
+            ' (need >' + (maxScav + 3) + '), negative ' + neg.minorHi +
+            ' (need <=' + maxScav + ').');
+        return {passed: false, results: []};
+    }
+    console.log('\ndetector validated: positive forced ' + pos.minorHi +
+        ' scavenges, negative forced ' + neg.minorHi + '.\n');
+
+    console.log('== scenarios ==');
+    const results = [];
+    for (let i = 0; i < scenarios.length; i++) {
+        const r = await measure(scenarios[i], opts);
+        results.push(r);
+        console.log(formatResult(r));
+    }
+
+    let mustFailOK = true;
+    if (mustFail.length > 0) {
+        console.log('\n== must-fail (gate self-test) ==');
+        for (let j = 0; j < mustFail.length; j++) {
+            const mf = await measure(mustFail[j], opts);
+            const mfv = verdict(mf, thresholds);
+            if (mfv.pass) mustFailOK = false;
+            console.log((mfv.pass ? 'MISSED ' : 'CAUGHT ') + formatResult(mf));
+        }
+    }
+
+    console.log('\n' + '='.repeat(72));
+    const failures = [];
+    for (let s = 0; s < results.length; s++) {
+        const v = verdict(results[s], thresholds);
+        console.log('  ' + (v.pass ? 'PASS' : 'FAIL') + '  ' + results[s].name);
+        if (!v.pass) {
+            failures.push(results[s]);
+            for (let ri = 0; ri < v.reasons.length; ri++) {
+                console.log('       ' + v.reasons[ri]);
+            }
+        }
+    }
+    console.log('='.repeat(72));
+
+    const passed = failures.length === 0 && mustFailOK;
+    if (passed) {
+        console.log('\nZERO-GC GATE: PASS \u2014 ' + results.length + '/' + results.length + ' scenarios.');
+    } else {
+        const why = failures.map(function (f) {
+            return f.name;
+        });
+        if (!mustFailOK) why.push('must-fail scenario was not caught');
+        console.log('\nZERO-GC GATE: FAIL \u2014 ' + why.join('; '));
+    }
+    return {passed: passed, results: results};
+}

package/README.md

@@ -0,0 +1,139 @@
+# @zakkster/lite-perf-gate
+
+[![npm version](https://img.shields.io/npm/v/@zakkster/lite-perf-gate.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-perf-gate)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Hot%20path-00C853?style=for-the-badge&logo=leaf&logoColor=white)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-perf-gate?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-perf-gate)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-perf-gate?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-perf-gate)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-perf-gate?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-perf-gate)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+> Prove your hot path allocates nothing -- or name what did.
+
+Zero-GC and performance regression gate for `node:test`. Scavenge-counting with scaling verdict, built-in detector self-validation, and CI pass/fail. No sampling, no heuristics, no false passes.
+
+```bash
+npm install @zakkster/lite-perf-gate
+```
+
+## Why this exists
+
+`benchmark.js` is dead. `tinybench` and `mitata` measure throughput but don't **gate** -- they can't fail a CI build when a hot path starts allocating. The V8 sampling heap profiler reports live-at-stop bytes, silently **missing transient garbage** -- the exact GC pressure a zero-alloc claim is about. Retained-heap delta (`heapUsed` before/after + `gc()`) misses it too: freed before snapshot.
+
+Scavenge-counting is the only reliable detector of transient allocation. This library packages the methodology into a `node:test`-native harness that validates its own detector on every run.
+
+## Quick start
+
+```js
+// test/zero-gc.test.mjs
+import { zgcSuite } from '@zakkster/lite-perf-gate';
+
+zgcSuite({
+    scenarios: [
+        {
+            name: 'steady-state propagation',
+            setup() {
+                const engine = buildYourGraph();
+                return engine;
+            },
+            hot(engine, n) {
+                for (let i = 0; i < n; i++) engine.update(i);
+            },
+            statsOf(engine) {
+                return engine.stats();  // { poolGrowths, totalAllocations, ... }
+            }
+        }
+    ],
+    counters: { poolGrowths: 0, totalAllocations: 0 }
+});
+```
+
+```bash
+node --expose-gc --max-semi-space-size=4 --test test/zero-gc.test.mjs
+```
+
+## What it does
+
+1. **Validates the detector.** A positive control (allocates per iteration) must force scavenges. A negative control (pure arithmetic) must force ~0. If either fails, the gate refuses to judge -- you get an explicit "detector broken" error, not a silent false pass.
+
+2. **Measures at two scales.** Each scenario runs at N and k\*N iterations. A zero-alloc path shows ~0 scavenges at both; an allocating path shows scavenges scaling with bytes. The comparison is not hostage to one absolute threshold.
+
+3. **Asserts the verdict.** Scavenges, retained-heap, and custom counter deltas are checked against thresholds. A failure names the signal that tripped.
+
+4. **Self-tests the gate.** `mustFail` scenarios inject a known allocation and assert the gate catches it. If your gate can't catch a leak, it tells you.
+
+## Three signals, each for what it can see
+
+| Signal | Detects | Misses |
+|--------|---------|--------|
+| Scavenge count (`perf_hooks` GC minor) | Transient allocation (the GC pressure zero-alloc claims are about) | Nothing in the young-gen domain |
+| Custom counters (`statsOf` deltas) | Exact engine internals (pool growth, node allocation) | Anything outside the engine's own bookkeeping |
+| Retained-heap delta (`memoryUsage` + `gc()`) | Leaks (memory that survives GC) | Transient garbage (freed before snapshot) |
+
+## API
+
+### `zgcSuite(config)`
+
+Register `node:test` cases for detector validation, scenario gating, and must-fail self-tests.
+
+```ts
+interface GateConfig {
+    scenarios: Scenario[];          // your hot-path scenarios
+    N?: number;                     // iteration count, default 200000
+    k?: number;                     // scale factor, default 8
+    maxScavenges?: number;          // threshold at k*N, default 2
+    maxRetainedKB?: number;         // heap growth threshold, default 64
+    counters?: Record<string, number>; // per-counter max delta
+    positiveControl?: Scenario;     // override built-in
+    negativeControl?: Scenario;     // override built-in
+    mustFail?: Scenario[];          // must trip the gate
+}
+```
+
+### `measure(scenario, options?)`
+
+Raw measurement at N and k\*N. Returns `MeasureResult` with scavenge counts, retained heap, and counter deltas.
+
+### `verdict(result, thresholds?)`
+
+Evaluate a `MeasureResult` against thresholds. Returns `{ pass: boolean, reasons: string[] }`.
+
+### `runGate(config)`
+
+Standalone human-readable report. Same config as `zgcSuite`. Returns `{ passed, results }`.
+
+### `Scenario`
+
+```ts
+interface Scenario<State = any> {
+    name: string;
+    setup(): State;
+    hot(state: State, n: number): void;
+    statsOf?(state: State): Record<string, number>;
+    teardown?(state: State): void;
+}
+```
+
+The `hot` function is the ONLY code inside the measurement window. `setup` and `teardown` run outside.
+
+## Measurement traps (why it's built this way)
+
+Two approaches were tried and rejected -- both produce **false passes**:
+
+- **Retained-heap delta alone** only sees retention. A hot path that allocates and frees every iteration shows ~0 delta -- yet that transient churn is exactly the GC pressure the claim is about.
+- **V8 sampling heap profiler** (`HeapProfiler.startSampling`) reports live-at-stop sampled bytes, so it likewise misses transient garbage.
+
+Two V8 gotchas the controls handle:
+
+- **Escape analysis / scalar replacement** erases function-local throwaway allocations entirely. The positive control allocates into a module-level sink that genuinely escapes.
+- **GC PerformanceObserver entries are async.** The window is followed by a timer tick before the count is read, and the count is snapshotted before the harness's own `gc()` calls.
+
+## `--max-semi-space-size=4`
+
+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.
+
+## License
+
+MIT (c) Zahary Shinikchiev

package/llms.txt

@@ -0,0 +1,51 @@
+# @zakkster/lite-perf-gate
+
+Zero-GC and performance regression gate for node:test.
+
+## What it does
+
+Proves a hot path allocates nothing, or names what did. Three signals:
+  1. Scavenge count (perf_hooks GC minor) -- transient allocation.
+  2. Custom counters (user-supplied statsOf) -- exact engine internals.
+  3. Retained-heap delta (memoryUsage + gc) -- leak detector.
+
+Scaling verdict: measure at N and k*N. Zero-alloc => ~0 scavenges at both.
+Detector self-validation: positive control (must scavenge) + negative
+control (must not scavenge) run on every gate invocation. If either fails,
+the gate refuses to judge.
+
+## Primary API
+
+zgcSuite(config) -- register node:test cases.
+  config.scenarios: Scenario[]   -- the hot paths to gate.
+  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).
+
+measure(scenario, {N, k}) -- raw MeasureResult.
+verdict(result, thresholds) -- { pass: boolean, reasons: string[] }.
+runGate(config) -- standalone report, same config as zgcSuite.
+
+## Scenario shape
+
+{ name, setup(), hot(state, n), statsOf?(state), teardown?(state) }
+
+setup() builds the graph. hot(state, n) is the ONLY code in the window.
+statsOf returns numeric counters; deltas are computed automatically.
+
+## Run with
+
+node --expose-gc --max-semi-space-size=4 --test your.test.mjs
+
+--expose-gc is required. --max-semi-space-size=4 sharpens sensitivity.
+
+## Why scavenge counting
+
+Retained-heap delta misses transient garbage (freed before snapshot).
+V8 sampling profiler misses it (reports live-at-stop). Scavenge counting
+is the only reliable detector of transient allocation in V8.
+
+## Zero dependencies
+
+Single-file ESM. Imports only node:perf_hooks, node:timers/promises,
+node:test, node:assert/strict.

package/package.json

@@ -0,0 +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"
+    }
+  },
+  "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"
+  }
+}