@zakkster/lite-perf-gate 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+## [1.3.0] - 2026-09-13
+
+### Changed
+
+- **Positive control is a bounded 64-slot ring, not a grow-forever sink.**
+  The stock control stored every `{x,y,z,w}` into a module-level array to
+  defeat escape analysis -- but 100% survival trained V8's allocation-site
+  pretenuring, so the site was promoted to old space and the scavenge signal
+  died. At LIBRARY DEFAULTS in a fresh process the count went DOWN as the
+  work went UP and `runGate` refused with DETECTOR VALIDATION FAILED (PG-01).
+  The control now writes `__posRing[i & 63] = {x,y,z,w}`: the store still
+  escapes, but every object is overwritten within 64 iterations, so the
+  site's survival ratio stays ~0. Measured, fresh process, N=200000 k=8,
+  `--expose-gc --max-semi-space-size=4`:
+
+  | control                    | minorLo | minorHi | majorHi | retainedKB_hi |
+  | -------------------------- | ------- | ------- | ------- | ------------- |
+  | stock grow-forever sink    | 2       | 1       | 1       | ~100784       |
+  | 64-slot ring (this release)| 2       | 21      | 0       | ~11           |
+
+  See `decisions/0001-positive-control.md`.
+- **Footprint is bounded by construction.** One `measure(controlPositive)`
+  at defaults grew the post-gc heap ~113MB with the stock sink and poisoned
+  every later measurement in the same process (a subsequent negative control
+  then forced 6 scavenges against a ceiling of 2, PG-10). At most 64 objects
+  (~3KB) are retained now; post-gc growth is sub-megabyte.
+- **`_controlKeepAlive()` returns ring occupancy (0..64), not a push count.**
+  Its purpose -- a read that touches every slot so V8 cannot sink the stores
+  -- is unchanged; it no longer returns a monotonically growing number.
+- **Detector-validation margin is decoupled from the consumer's budget.**
+  The old predicate `pos.minorHi > maxScavenges + 3` coupled the evidence
+  the instrument owes to the budget the user set for their own code
+  (`maxScavenges: 40` silently demanded a 43-scavenge control). One shared
+  predicate `validateDetector(pos, neg, maxScav)` now governs both zgcSuite
+  and runGate, with its own constants: `CONTROL_FLOOR = 6` (positive control
+  scavenges at k*N), `CONTROL_SCALE = 2` (minorHi >= 2*minorLo when
+  minorLo > 0), `CONTROL_NEG_CEIL = 2` (negative ceiling, tightened by
+  `min(maxScavenges, 2)`). Every clause is written `!(x >= limit)` so a NaN
+  count fails closed. A consumer at the default `maxScavenges: 2` sees the
+  identical effective floor.
+- **One detector-validation test replaces two.** zgcSuite measures positive
+  then negative in one test so the negative doubles as the in-suite
+  poisoning regression.
+
+### Added
+
+- **Torture suite** (`npm run torture`, `test/torture.mjs` +
+  `test/torture/`): T1 detector matrix (bare child processes at library
+  defaults -- the PG-01 reproduction inverted, ring scaling at N in
+  {50000, 200000}, and the PG-10 poisoning regression) and T5 footprint +
+  4096-cycle soak (bounded control footprint, lite-leak registration count
+  back to 0, flat heap band, `checkNoGc` pass over the profiler window).
+  T2/T3/T4 register as named skipped tiers for P2/P3/P4. Two env-gated
+  controls-for-the-controls prove the tiers can fail:
+  `TORTURE_CONTROL=stock-control` fails T1, `TORTURE_CONTROL=leaky-soak`
+  fails T5.
+- **Two child-process self-tests** (PG-15): zgcSuite is green end-to-end at
+  library defaults, and goes red (DETECTOR VALIDATION FAILED / need >=6)
+  when the positive control is sabotaged with the stock grow-forever shape.
+  26 -> 28 self-tests.
+- **devDependencies** `@zakkster/lite-gc-profiler ^1.16.0` and
+  `@zakkster/lite-leak ^1.10.0` -- dev-only, for the torture suite; the
+  library still ships zero runtime dependencies and `files[]` is unchanged.
+- **`.gitignore`** for `/node_modules/`, `/package-lock.json`, `.DS_Store`
+  (the lockfile is not committed in this suite).
+
+### Notes
+
+- Every number above was measured on a single machine: darwin, Node
+  v26.3.1, `--expose-gc --max-semi-space-size=4`, reproduced twice. There
+  is no nvm here; the multi-Node matrix is a CI intent, not a claim this
+  release verifies. `CONTROL_FLOOR = 6` absorbs the large-semi-space
+  direction (a default 16MB young generation buys ~5-6 scavenges instead of
+  21); scavenge count is a function of bytes allocated per semi-space byte,
+  not of CPU speed.
+- No verdict changes (P2), no new signals such as maxMajors or external
+  deltas (P3), no suiteGate work (P4), no README rewrite (P5). The
+  measurement window in `meterOnce` and suiteGate's visit are byte-identical
+  to 1.2.2.
+- The demo `<title>` no longer embeds a version; it went stale every release.
+
+## [1.2.2] - 2026-09-13
+
+- **Version truth**: `VERSION` reads `1.2.2` and agrees with
+  `package.json` and this file. The published 1.2.1 tarball shipped
+  `VERSION = '1.2.0'`; see the 1.2.1 entry below.
+- **`prepublishOnly: npm test`** -- the publish path now runs the suite.
+  The guard test caught the 1.2.1 slip locally; nothing forced it to run
+  before `npm publish`. That gap, not the string, was the defect.
+- **Self-test**: the VERSION test no longer pins a literal; it asserts
+  only `VERSION === package.json.version`. The literal forced a test edit
+  every release, which is the friction that got skipped.
+- Housekeeping: `var -> let/const` in `PerfGate.js`, trailing newline at
+  EOF restored, demo `<title>` version.
+- No API change and no behavior change to any exported function.
+
+## [1.2.1] - 2026-07-08
+
+Retroactive entry, written 2026-09-13: 1.2.1 was published with no
+changelog entry.
+
+- Housekeeping only: `var -> let/const` cleanup in `PerfGate.js` and the
+  `package.json` bump. Verified by unpacking the published tarball: no
+  API change and no behavior change relative to 1.2.0.
+- **Known defect, fixed in 1.2.2**: the tarball shipped
+  `export const VERSION = '1.2.0';` and a CHANGELOG ending at 1.2.0. The
+  self-test that asserts VERSION against the manifest would have caught
+  it; there was no `prepublishOnly` to make it run.
+
 ## [1.2.0] - 2026-07-07
 
 - **`toNDJSON(x, meta?)`** -- NDJSON verdict output for CI artifacts.
@@ -10,6 +119,10 @@
 
 ## [1.1.0] - 2026-07-07
 
+> Never published standalone. The registry has 1.0.0, 1.0.1, 1.2.0,
+> 1.2.1 -- no 1.1.0. The features below first reached the registry
+> inside 1.2.0.
+
 - **`suiteGate(config)`** -- SPP stream-fed budgets. Consumes a Float64Array
   slab or any forEach record source (a lite-scope memory sink qualifies),
   reduces per-budget metrics (count/sum/max/mean/last over slot t/a/b,

package/PerfGate.js

@@ -17,7 +17,7 @@
  * MIT License
  */
 
-export const VERSION = '1.2.0';
+export const VERSION = '1.3.0';
 
 import {PerformanceObserver, constants} from 'node:perf_hooks';
 import {setTimeout as sleep} from 'node:timers/promises';
@@ -162,22 +162,48 @@ export async function measure(scenario, options) {
 // Built-in controls
 // ---------------------------------------------------------------------------
 
-const __posKeep = [];
+// The positive control must defeat TWO V8 adaptations at once:
+//   1. escape analysis / scalar replacement -- an object that never escapes
+//      is never allocated, so the control must store it somewhere real;
+//   2. allocation-site pretenuring -- a site whose objects keep SURVIVING is
+//      promoted to old space, and the scavenge signal dies (PG-01).
+// A 64-slot ring satisfies both: the store escapes, and every object is
+// overwritten within 64 iterations, so the site's survival ratio stays ~0.
+// Measured, fresh process, N=200000 k=8, --expose-gc --max-semi-space-size=4:
+// minorLo=2 minorHi=21 majorHi=0 retainedKB_hi~11 (stock sink: 2 -> 1, ~100MB).
+// See decisions/0001-positive-control.md.
+
+const CONTROL_RING_SIZE = 64;
+const CONTROL_RING_MASK = CONTROL_RING_SIZE - 1;
+const __posRing = new Array(CONTROL_RING_SIZE).fill(null);
 
-/** @internal -- reference to keep the positive-control sink alive. */
+/**
+ * @internal -- the read that keeps the positive-control ring alive.
+ * Touches every slot so V8 cannot sink or eliminate the stores in
+ * controlPositive.hot, and returns the live occupancy. The sink is bounded
+ * by construction: after any number of iterations at most 64 objects (~3KB)
+ * are retained, so one measurement can never poison the next (PG-10).
+ * @returns {number} occupied ring slots, 0..64
+ */
 export function _controlKeepAlive() {
-    return __posKeep.length;
+    let live = 0;
+    for (let i = 0; i < CONTROL_RING_SIZE; i++) {
+        const o = __posRing[i];
+        if (o !== null && o.w >= o.x) live++;
+    }
+    return live;
 }
 
-/** Positive control: allocates a heap object per iteration. */
+/** Positive control: allocates one short-lived heap object per iteration. */
 export const controlPositive = {
-    name: 'CONTROL+ (allocates {x,y,z,w} per iter)',
+    name: 'CONTROL+ ({x,y,z,w} per iter into a 64-slot ring)',
     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;
+        for (let i = 0; i < n; i++) {
+            __posRing[i & CONTROL_RING_MASK] = {x: i, y: i + 1, z: i + 2, w: i + 3};
+        }
     }
 };
 
@@ -194,6 +220,46 @@ export const controlNegative = {
     }
 };
 
+// ---------------------------------------------------------------------------
+// Detector validation
+// ---------------------------------------------------------------------------
+
+// Detector-validation floors, DECOUPLED from the consumer's scenario
+// thresholds on purpose: the evidence the instrument owes does not get
+// cheaper because a consumer raised maxScavenges. decisions/0001.
+const CONTROL_FLOOR = 6;     // positive control: scavenges at k*N
+const CONTROL_SCALE = 2;     // positive control: minorHi / minorLo
+const CONTROL_NEG_CEIL = 2;  // negative control: hard ceiling
+
+/**
+ * The ONE detector-validation predicate. zgcSuite and runGate both call it;
+ * neither forks it. Comparisons are written so a NaN count fails closed.
+ *
+ * @param {MeasureResult} pos  positive-control measurement
+ * @param {MeasureResult} neg  negative-control measurement
+ * @param {number} maxScav     suite scavenge threshold (tightens neg only)
+ * @returns {{ ok: boolean, reason: string | null }}
+ */
+function validateDetector(pos, neg, maxScav) {
+    const flags = ' Run with --expose-gc --max-semi-space-size=4.';
+    if (!(pos.minorHi >= CONTROL_FLOOR)) {
+        return {ok: false, reason: 'positive control forced ' + pos.minorHi +
+            ' scavenges at ' + pos.k + 'N (need >=' + CONTROL_FLOOR + ').' + flags};
+    }
+    if (pos.minorLo > 0 && !(pos.minorHi >= CONTROL_SCALE * pos.minorLo)) {
+        return {ok: false, reason: 'positive control did not scale: ' +
+            pos.minorLo + ' at N, ' + pos.minorHi + ' at ' + pos.k +
+            'N (need >=' + (CONTROL_SCALE * pos.minorLo) + ').' + flags};
+    }
+    const negCeil = maxScav < CONTROL_NEG_CEIL ? maxScav : CONTROL_NEG_CEIL;
+    if (!(neg.minorHi <= negCeil)) {
+        return {ok: false, reason: 'negative control forced ' + neg.minorHi +
+            ' scavenges (need <=' + negCeil + ') -- noisy process, or a prior ' +
+            'measurement poisoned it.' + flags};
+    }
+    return {ok: true, reason: null};
+}
+
 // ---------------------------------------------------------------------------
 // Verdict
 // ---------------------------------------------------------------------------
@@ -302,18 +368,13 @@ export function zgcSuite(config) {
     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);
+    test('perf-gate: detector validation (positive + negative controls)', async function () {
+        const pos = 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 + ')');
+        const neg = await measure(negCtrl, opts);
+        const v = validateDetector(pos, neg, maxScav);
+        assert.ok(v.ok, 'DETECTOR VALIDATION FAILED: ' + v.reason +
+            '\n  ' + formatResult(pos) + '\n  ' + formatResult(neg));
     });
 
     for (let i = 0; i < scenarios.length; i++) {
@@ -376,14 +437,14 @@ export async function runGate(config) {
     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 + ').');
+    const dv = validateDetector(pos, neg, maxScav);
+    if (!dv.ok) {
+        console.log('\n!! DETECTOR VALIDATION FAILED: ' + dv.reason);
         return {passed: false, results: []};
     }
     console.log('\ndetector validated: positive forced ' + pos.minorHi +
-        ' scavenges, negative forced ' + neg.minorHi + '.\n');
+        ' scavenges at ' + k + 'N (' + pos.minorLo + ' at N, floor ' +
+        CONTROL_FLOOR + '), negative forced ' + neg.minorHi + '.\n');
 
     console.log('== scenarios ==');
     const results = [];
@@ -656,4 +717,4 @@ export function toNDJSON(x, meta) {
         }
     }
     return lines.join('\n') + '\n';
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-perf-gate",
-  "version": "1.2.1",
+  "version": "1.3.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",
@@ -25,7 +25,13 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --expose-gc --max-semi-space-size=4 --test test/self.test.mjs"
+    "test": "node --expose-gc --max-semi-space-size=4 --test test/self.test.mjs",
+    "torture": "node --expose-gc --max-semi-space-size=4 test/torture.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@zakkster/lite-gc-profiler": "^1.16.0",
+    "@zakkster/lite-leak": "^1.10.0"
   },
   "keywords": [
     "benchmark",