@zakkster/lite-perf-gate 1.3.0 → 1.4.0

package/llms.txt

@@ -4,10 +4,20 @@ 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.
+Proves a hot path allocates nothing, or names what did. Five signals:
+  1. Scavenge count (perf_hooks GC minor) -- transient young-gen allocation.
   2. Custom counters (user-supplied statsOf) -- exact engine internals.
   3. Retained-heap delta (memoryUsage + gc) -- leak detector.
+  4. Old-gen activity (perf_hooks GC major + incremental) -- churn that
+     promotes or marks old space (PG-03a). GATE signal, default max 0.
+  5. External/arrayBuffers delta (memoryUsage().arrayBuffers + gc) --
+     backing-store memory heapUsed excludes (PG-03b). Default max 64 KB.
+
+Signals 4 and 5 are GATE signals, not a profiler: when either trips, the
+reason string names it and points at @zakkster/lite-gc-profiler for
+diagnosis. New in v1.4.0; new defaults CAN fail a previously-green suite
+exactly when a hot path fires an old-gen collection or grows external
+memory. See decisions/0003 for the GC-kind census that chose them.
 
 Scaling verdict: measure at N and k*N. Zero-alloc => ~0 scavenges at both.
 Detector self-validation: positive control (must scavenge) + negative
@@ -22,10 +32,21 @@ zgcSuite(config) -- register node:test cases.
   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).
+  config.allowEmpty: boolean -- controls-only detector smoke run (scenarios [] otherwise throws).
+  config.allowNoGc: boolean -- run without --expose-gc; retained is not gated, result.retainedReliable is false.
 
-measure(scenario, {N, k, flushMs}) -- raw MeasureResult.
+measure(scenario, {N, k, flushMs, allowNoGc}) -- raw MeasureResult.
+  N integer >=1, k integer >=2, flushMs finite >=0 (0 honored); bad values throw.
 verdict(result, thresholds) -- { pass: boolean, reasons: string[] }.
-runGate(config) -- standalone report, same config as zgcSuite.
+  Bad thresholds throw. thresholds.maxOldGen (default 0),
+  thresholds.maxArrayBuffersKB (default 64) join maxScavenges/maxRetainedKB.
+  Fail-closed reasons: '<signal>: not a number (fail closed)',
+  '<key>: no such counter measured (statsOf keys: ...)'. Over-budget:
+  'oldgen: N > 0 (old-gen GC activity -- diagnose with @zakkster/lite-gc-profiler)',
+  'arrayBuffers: NKB > 64KB (external memory -- diagnose with @zakkster/lite-gc-profiler)'.
+  arrayBuffers is skipped under allowNoGc; an explicit maxArrayBuffersKB with
+  allowNoGc throws (mirrors maxRetainedKB). oldgen gates even under allowNoGc.
+runGate(config) -- standalone report; returns {passed, code, results}, code 0 pass / 1 scenario or must-fail failure / 2 detector validation failed; never sets process.exitCode.
 
 ## Scenario shape
 
@@ -38,7 +59,9 @@ statsOf returns numeric counters; deltas are computed automatically.
 
 node --expose-gc --max-semi-space-size=4 --test your.test.mjs
 
---expose-gc is required. --max-semi-space-size=4 sharpens sensitivity.
+--expose-gc is REQUIRED: measure() throws without it, with the run command in
+the message. allowNoGc: true opts out and drops the retained signal.
+--max-semi-space-size=4 sharpens sensitivity.
 
 ## CI tuning
 
@@ -67,10 +90,46 @@ node:test, node:assert/strict.
 v1.1 suiteGate(config): SPP stream-fed budgets. config.source = Float64Array
 slab or { forEach(cb(packed,t,a,b)) } (lite-scope memory sink). budgets[] =
 { name, packed? | stream?+op | op, slot: t|a|b (default a), reduce:
-count|sum|max|mean|last (default max), max }. Delegates every comparison to
-verdict(); returns { name, pass, reasons, budgets: [{name, value, count,
-max, pass, reasons}] }. Never sets exit codes; CONT records (op 0x0F01) are
-never budget targets. No lite-scope import: coupled by SPP v1 protocol only.
+count|sum|max|mean|last (default max), max, minCount? }. Delegates every
+comparison to verdict(); returns { name, pass, reasons, budgets: [{name,
+value, count, max, minCount, pass, reasons}] }. Never sets exit codes. No
+lite-scope import: coupled by SPP v1 protocol only.
+
+v1.4.0 suiteGate doors (decisions/0004; the package's ONLY hot body is visit()):
+THROWS (data-integrity refusal, the caller handed us something we cannot read):
+  - a slab record whose packed header is not a u32 -- RangeError naming the
+    record index (slab lane) or the invocation index (forEach lane);
+  - a non-Float64Array typed-array source (Float32Array etc.) -- its forEach
+    binds (value, index, array) onto (packed, t, a, b); RangeError at dispatch;
+  - a forEach source whose ANY invocation is not four numbers (checked on
+    every record, naming the invocation index and the failing slot; a native
+    Array/TypedArray forEach binds (value, index, array); a non-number slot
+    like null/'3'/true would finitely coerce and pass silently otherwise).
+    A NaN slot is a number and passes this door; it fails closed at D-D only
+    when the reducer propagates it (sum/mean, or max/last at the extremum) --
+    under max/last/count a NaN coexisting with finite records is silently
+    excluded and the budget can pass (documented residue, decisions/0004);
+  - slot/reduce set to an inherited prototype key (slot 'toString', reduce
+    'constructor') -- null-proto lookup tables close this (PG-12);
+  - a budget targeting CONT (0x0F01), op form or packed low-16-bits form:
+    'CONT records are never budget targets (SPP v1)' (PG-13);
+  - a minCount that is not an integer >= 0.
+FAILS a budget (a verdict, we read it and it is out of budget):
+  - a reduced value that is not finite (NaN, Infinity, -Infinity) ->
+    '<name>: not a number (fail closed)' (PG-06 / D-D);
+  - count < minCount -> '<name>: matched <count> < minCount <n>'.
+Budget names may be any non-empty string, including 'toString', '__proto__',
+'constructor' -- legal end to end through toNDJSON. Without minCount a
+zero-match budget still reduces to 0, reports count 0, and PASSES (back-compat).
+The D-A u32 door is measured within noise on a 1M-record slab (torture T4).
+
+verdict()'s counter lane now fails closed on ANY non-finite measured value,
+not only NaN: Infinity / -Infinity now read '<key>: not a number (fail
+closed)' too (was '<key>: Infinity > <max>'). The other four lanes keep the
+NaN-only predicate (decisions/0004 D-D). This is the reduce-time door suiteGate
+delegates through, so there is one comparison authority for the string.
+
 v1.2 toNDJSON(x, meta?): NDJSON for CI artifacts; accepts suiteGate result,
 measure result, or array; budget lines then suite-gate summary; meta merged
-per line; trailing newline.
+per line; trailing newline. The budget-line shape is frozen: minCount is on
+the in-process result object, NOT on the NDJSON line.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-perf-gate",
-  "version": "1.3.0",
+  "version": "1.4.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",
@@ -30,8 +30,10 @@
     "prepublishOnly": "npm test"
   },
   "devDependencies": {
+    "@zakkster/lite-arena": "^1.9.0",
     "@zakkster/lite-gc-profiler": "^1.16.0",
-    "@zakkster/lite-leak": "^1.10.0"
+    "@zakkster/lite-leak": "^1.10.0",
+    "@zakkster/lite-scope": "^1.2.0"
   },
   "keywords": [
     "benchmark",