@zakkster/lite-perf-gate 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,261 @@
 # Changelog
 
+## [1.4.0] - 2026-09-13
+
+> One release, three roadmap sessions. The registry latest was 1.3.0;
+> sessions P2, P3 and P4 were developed against interim targets 1.4.0,
+> 1.5.0 and 1.6.0 -- none of which was ever published -- and ship
+> together here as 1.4.0. Session records under decisions/ keep their
+> original target numbers as history.
+
+### suiteGate record doors, inherited-key hardening, CONT rejection, minCount (session P4)
+
+#### Added
+
+- **`minCount`, the presence assertion (the ONE surface addition).** An
+  optional per-budget integer >= 0. Without it, a budget whose `op` is a
+  typo matches zero records, reduces to 0, and passes forever -- the
+  `count: 0` was reported and nothing ever looked at it. With
+  `minCount: n`, a budget that matched fewer than `n` records FAILS with
+  `'<name>: matched <count> < minCount <n>'`. It delegates through a
+  SECOND `verdict()` call carrying the shortfall (`minCount - count`) as a
+  maximum of 0 -- one comparison authority, and `verdict()` stays
+  max-only and unaware a minimum exists (decisions/0004 D-G).
+  `SuiteBudgetResult` gains `minCount` (0 when omitted); the NDJSON budget
+  line is deliberately UNCHANGED (schema frozen).
+- **Back-compat, stated and pinned:** WITHOUT `minCount`, a zero-match
+  budget still reduces to 0, still reports `count: 0`, and still PASSES
+  (v1.1 behavior). `minCount: 0` is provably inert (result deep-equal to
+  omitting it). Presence assertions are opt-in because silence is
+  legitimately a pass for budgets like 'no gc pause over 8ms'.
+- **Torture T4 activates: the suiteGate reduction gate.** `measureOps`
+  over `suiteGate` on a preallocated 1M-record slab with 8 budgets, gated
+  on per-record retained bytes (the 1M-vs-1K `bytesPerOp` difference),
+  `checkOps(maxBytesPerOp)`, `checkNoGc(maxMajor 0, maxArrayBuffersGrowth
+  0)`, and an `nsPerRecord < 25` catastrophe ceiling. Runs BEFORE T5 so no
+  `measureOps` is ever in flight inside T5's `GcProfiler` window. A
+  `TORTURE_CONTROL=allocating-visit` lane (test-code only) drives a
+  forEach shim that RETAINS one object per record and MUST fail T4.
+
+#### Changed
+
+- **PG-06: wrong-shaped record sources now THROW, naming the record
+  index.** The same over-budget record used to reach three different
+  verdicts by container: FAIL as a `Float64Array` slab (correct), PASS as
+  a `Float32Array` (native `forEach` binds `(value, index, array)` ->
+  reduced value `-Infinity`, count 1), PASS as an array of tuples
+  (count 0). Now: a slab record whose packed header is not a u32 throws a
+  `RangeError` naming the record index (D-A, in the slab driver loop);
+  a non-`Float64Array` (or cross-realm) typed-array source throws at
+  dispatch naming its constructor (D-C); a `forEach` source whose ANY
+  invocation is not four numbers throws naming the invocation index and
+  the failing slot (D-B, checked on every record -- a `null`/`'3'`/`true`
+  slot at a later record would finitely coerce and pass a budget silently
+  otherwise). A NaN slot is a number and passes D-B by design: 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 (count inflated, minCount satisfied), identically on both lanes --
+  a documented residue (decisions/0004).
+- **PG-06 / D-D: a reduced value that is not finite FAILS closed.**
+  `verdict()`'s counter lane predicate widened by ONE line from
+  `actual !== actual` to `!isFinite(actual)`, so `Infinity` and
+  `-Infinity` now read `'<name>: not a number (fail closed)'`. This closes
+  the `-Infinity` fail-open the P2 reviewer documented as
+  unreachable-until-P4. Public side effect: a `statsOf` counter delta of
+  `Infinity` now reads `'k: not a number (fail closed)'` instead of
+  `'k: Infinity > 0'` -- still a failure, only the wording changed. The
+  other four verdict lanes keep the NaN-only predicate (decisions/0004
+  D-D scope note).
+- **PG-12: inherited prototype keys no longer corrupt validation.**
+  `SUITE_SLOTS` / `SUITE_REDUCES` are null-proto, so `slot: 'toString'`
+  throws `slot must be` and `reduce: 'constructor'` throws `reduce must
+  be`; the duplicate-name map (`seen`) and the per-budget `counters`/`ct`
+  objects are null-proto, so a budget legitimately NAMED `toString`,
+  `hasOwnProperty`, `__proto__`, or `constructor` is legal end to end,
+  through `toNDJSON` too (verified by round-trip, incl. a name with a
+  quote and a newline).
+- **PG-13: a budget targeting CONT (0x0F01) now throws at config,** both
+  the `{op: 0x0F01}` and the packed low-16-bits forms:
+  `'CONT records are never budget targets (SPP v1)'`. `visit` skips CONT
+  by protocol, so such a budget passed vacuously forever. The v1.1
+  self-test that PINNED that vacuous pass is rewritten this release,
+  deliberately; the CONT RECORD-in-slab protocol behavior is unchanged.
+- **`visit`'s body is byte-identical to v1.5.0.** The D-A per-record door
+  lives in the slab driver loop (`if (p !== p >>> 0) badRecord(r >> 2, p)`),
+  which already holds the index; the `forEach` lane gets a separate
+  `visitChecked` wrapper. `meterOnce`, `gc2`, `zgcSuite`, `runGate` are
+  unchanged; `verdict()` changed exactly one line.
+- **T4 cost (darwin 25.6.0, Node v26.3.1, `--expose-gc
+  --max-semi-space-size=4`):** nsPerRecord p50 15.5310 (v1.5.0) ->
+  15.7637 (v1.6.0), delta +0.2327 ns/record; min delta +0.0661. The
+  v1.5.0 back-to-back noise band was 15.3637 / 15.5310 / 18.0343
+  (min/p50/max), a 2.6706 ns spread -- the door's delta is far inside it,
+  so D-A ships per record. Per-record retained bytes measured 0.00000
+  (min, noise to 0.00123), well under the 0.01 gate (decisions/0004).
+
+### Bypass signals -- oldGen + arrayBuffers lanes, census-driven (session P3)
+
+#### Added
+
+- **Two new gate signals, chosen from a GC-kind census, close the
+  allocation bypasses (PG-02, PG-03).** The gate now measures FIVE
+  signals: scavenges, custom counters, retained heap, plus (4) **old-gen
+  activity** (`major + incremental`, threshold `maxOldGen` default 0) and
+  (5) **external/arrayBuffers growth** (`memoryUsage().arrayBuffers`
+  delta, threshold `maxArrayBuffersKB` default 64). Both are GATE signals,
+  not a profiler: each over-budget reason ends with "diagnose with
+  @zakkster/lite-gc-profiler". The boundary law holds -- no GC-kind
+  breakdown on results beyond the two composed counters.
+- **The GC-kind census (decisions/0003).** Before any signal froze, a raw
+  `PerformanceObserver` census (`test/probes/census-0003.mjs`, repo-only)
+  logged kind + flags + timing across the bypass corpus, three corpus
+  runs plus a 100-rep x 2 ambient distribution. It falsified the naive
+  design: on Node v26.3.1, C1's 600KB-string LO churn (PG-02) fires
+  `oldGen=0` in-window and a flat settle, so it is a DOCUMENTED HOLE, not
+  a catch (Axis A4). C2's Float64Array churn fires `oldGen=2` (caught).
+  C3's 16MB pool grows `arrayBuffers` 16384KB while retained reads <64KB
+  (caught). Ambient old-gen and arrayBuffers were 0 across all 200 reps,
+  so the defaults (0 / 64) cause zero spurious failures.
+- **`controlLarge` + external detector integrity.** A bounded, mask-gated
+  retained 64KB-ArrayBuffer pool (deterministic 832KB arrayBuffers at the
+  pinned k*N, 13x the gate) validates signal 5 on every `zgcSuite`/`runGate`
+  run, as the third argument to the ONE `validateDetector(pos, neg, large,
+  maxScav)` predicate (no fork). A `largeControl` config override and a
+  negative-control old-gen clause (the arithmetic control must fire 0
+  old-gen) complete the detector. Because a retained-external control
+  leaves a V8 scheduled-scavenge residue that poisons the next
+  scavenge-gated measurement (mechanism proven in decisions/0003, not
+  drainable), `controlLarge` is measured LAST in `runGate` and last in
+  `zgcSuite`'s detector block; nothing scavenge-gated follows it.
+- **`MeasureResult` gains `oldGenLo/oldGenHi` and
+  `arrayBuffersKB_lo/arrayBuffersKB_hi`** (additive -- no existing key
+  changes). `toNDJSON`'s measure line carries them. `formatResult` shows
+  old-gen and arrayBuffers only when nonzero.
+- **Torture T3** activates: the PG-02/PG-03 bypasses as permanent
+  bare-child fixtures at pinned windows, all judged at default thresholds,
+  plus a `TORTURE_CONTROL=zero-signal` lane (test-code only) that zeroes
+  the two new fields in-child and MUST make T3 fail.
+
+#### Changed
+
+- **New defaults CAN fail a previously-green suite** -- exactly when a hot
+  path fires an old-gen collection (`maxOldGen: 0`) or grows external
+  memory past 64KB (`maxArrayBuffersKB: 64`). That is the release: the
+  gate now sees PG-03a and PG-03b. The 0/200 ambient census reps are the
+  evidence a genuinely zero-alloc path trips neither.
+- **PG-02 (600KB-string LO churn) is recorded as an uncatchable hole on
+  Node v26.3.1**, not silently "fixed": it fires no countable GC event any
+  lane can gate, and T3's t3a asserts its measured signature so a future
+  Node that closes the hole will flip the fixture.
+- **`allowNoGc: true` with an explicit `maxArrayBuffersKB` throws** (new
+  `NO_ARRAYBUFFERS` door, mirroring `maxRetainedKB`); the arrayBuffers
+  lane is not applied at all when `retainedReliable === false`. The
+  old-gen lane comes from the observer, not `memoryUsage`, so it gates
+  even under `allowNoGc`.
+- **The measurement window and `suiteGate` are byte-identical to v1.4.0.**
+  The observer callback gained two compare-and-increment branches
+  (incremental, weakcb -- outside the hot body); `incremental` is read
+  after `gcc.close()`, and the arrayBuffers captures reuse the existing
+  before/after `memoryUsage()` points. `gc2` and `suiteGate` are
+  untouched (P4 owns suiteGate).
+
+### Fail-closed doors -- thresholds, options, instrument, process contract (session P2)
+
+#### Changed
+
+- **Thresholds throw instead of passing everything (PG-04).**
+  `maxScavenges` and `maxRetainedKB` must be finite numbers >= 0 and
+  every `counters` maximum must be a finite number; NaN, Infinity,
+  negative counts and non-numbers now raise TypeError/RangeError at
+  config time, prefixed `lite-perf-gate: <where>: ` and naming the
+  field and the value. Reproduction inverted:
+  `verdict(r, {maxScavenges: NaN, maxRetainedKB: NaN})` used to pass a
+  result carrying 999 scavenges and 9999KB retained.
+- **A NaN measurement fails instead of passing (PG-04).** A gated signal
+  that is not a finite number now produces
+  `'<signal>: not a number (fail closed)'` -- `scavenges`, `retained`,
+  or the counter's own key. A NaN measurement is evidence of a broken
+  instrument, never of a clean hot path.
+- **A counter threshold that matches nothing fails (PG-05).** A typo'd
+  key produces `'<key>: no such counter measured (statsOf keys: ...)'`;
+  counter thresholds set against a scenario with no `statsOf` produce
+  one `'counters: ... (fail closed)'` reason. Previously
+  `{poolGrowth: 0}` against a measured `poolGrowths: 99` passed with
+  zero reasons, forever, silently.
+- **Missing `--expose-gc` throws (PG-11).** `measure()` -- and so
+  `zgcSuite`/`runGate` -- refuses at entry when `globalThis.gc` is not
+  a function, with the exact run command in the message. Previously
+  `gc2()` no-opped and the retained signal judged uncollected garbage
+  (a plain-node run produced a spurious `retained: 2901KB > 64KB`).
+- **Empty scenario lists throw (PG-08).** `zgcSuite`/`runGate` reject a
+  missing, non-array or empty `scenarios`; pass `allowEmpty: true` for a
+  controls-only detector smoke run. `runGate`'s old `PASS -- 0/0
+  scenarios` rubber stamp is now `detector only (allowEmpty, 0
+  scenarios gated)`, and zgcSuite's control test renames itself
+  `detector validation only (allowEmpty, 0 scenarios)`.
+- **`measure()` options are validated, and `flushMs: 0` is honored
+  (PG-09).** `N` integer >= 1, `k` integer >= 2, `flushMs` finite >= 0,
+  `allowNoGc`/`allowEmpty` strictly boolean (a truthy non-`true` value
+  throws). Every `(options && options.X) || DEFAULT` resolution is now
+  `!== undefined`, so `flushMs: 0` reaches the sleep instead of
+  silently meaning 100ms -- the one backward-incompatible behavior
+  change in this release. `{N: -1}` used to skip every loop and make
+  the POSITIVE CONTROL report zero allocation; `{k: 0.5}` used to
+  invert the two-scale design; `{flushMs: -50}` used to collapse the
+  observer window to ~1ms with a Node TimeoutNegativeWarning.
+- **Scenario shapes are validated at the same door.** `name` a non-empty
+  string, `setup`/`hot` functions, `statsOf`/`teardown` functions when
+  present -- across `scenarios[]`, `mustFail[]`, `positiveControl` and
+  `negativeControl`, each named by its position in the message.
+- **`runGate`'s exit-code claim is corrected (PG-14).** The old
+  docstring -- and the 1.2.0 entry below -- promised "exit codes 0/1/2"
+  and set none. `runGate` never touches `process.exitCode`: runner
+  semantics stay in the runner layer. It now RETURNS `code` and the
+  docs say "map result.code to your exit code".
+
+#### Added
+
+- **`code: 0 | 1 | 2` on GateResult.** 0 pass, 1 a failing scenario or
+  an uncaught `mustFail`, 2 detector validation failed.
+  `passed === (code === 0)`, asserted by test. Additive: `passed` and
+  `results` are unchanged.
+- **`allowNoGc`** (measure options + GateConfig). Runs without
+  `--expose-gc`; the result carries `retainedReliable: false`, the
+  retained rule is not applied at all (the default 64KB threshold
+  included), `retainedKB_lo/_hi` remain as diagnostics, and scavenges
+  and counters still gate. Combining it with an explicit
+  `maxRetainedKB` throws: retained is ungateable without the flag.
+- **`allowEmpty`** (GateConfig). The only sanctioned empty gate: a
+  controls-only detector smoke run, which is exactly what the torture
+  suite's T1a child is.
+- **`retainedReliable`** on MeasureResult. `false` only when `measure()`
+  ran without `globalThis.gc`; an absent field means reliable.
+- **Torture tier T2 -- fail-closed doors** (`test/torture/t2-doors.mjs`):
+  sixteen door cases hit from OUTSIDE the library, each with its passing
+  twin one valid step away, plus two children spawned WITHOUT
+  `--expose-gc` (one asserting the throw carries the run command, one
+  asserting the `allowNoGc` retained behavior). Third
+  control-for-the-control: `TORTURE_CONTROL=no-doors npm run torture`
+  routes the NaN cases through a legacy fail-open shim and T2 MUST fail.
+- **Six self-tests** (28 -> 34): threshold doors, NaN measurements,
+  unknown/absent counters, measure option doors including a timing proof
+  that `flushMs: 0` is honored, the empty-gate doors, and `runGate`
+  codes 0/1/2 in bare children with `process.exitCode` asserted
+  untouched in all three.
+- **`decisions/0002-fail-closed.md`** -- the six policies, the rejected
+  `allowNoGc` shapes, and the standing rejection of an `inconclusive`
+  third verdict.
+
+#### Notes
+
+- Hot bodies are untouched: `meterOnce`'s measurement window (between
+  `makeGcCounter()` and `gcc.close()`) and `suiteGate`'s `visit` have a
+  byte-identical diff. Every door is config-time or verdict-time.
+- suiteGate sources that reduce to NaN now fail their budget closed
+  instead of passing silently -- a down payment on PG-06; the record
+  doors themselves are P4.
+
 ## [1.3.0] - 2026-09-13
 
 ### Changed

package/PerfGate.d.ts

@@ -38,12 +38,33 @@ export interface MeasureResult {
     minorHi: number;
     majorLo: number;
     majorHi: number;
+    /** Old-gen activity (major + incremental) at N. */
+    oldGenLo: number;
+    /** Old-gen activity (major + incremental) at k*N. GATE signal (default max 0). */
+    oldGenHi: number;
     retainedKB_lo: number;
     retainedKB_hi: number;
+    /** External/backing-store (memoryUsage().arrayBuffers) delta in KB at N. */
+    arrayBuffersKB_lo: number;
+    /** External delta in KB at k*N. GATE signal (default max 64). */
+    arrayBuffersKB_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;
+    /** False when measured without --expose-gc (allowNoGc). Absent means reliable. */
+    retainedReliable?: boolean;
+}
+
+export interface MeasureOptions {
+    /** Iteration count (low). Integer >= 1. Default 200000. */
+    N?: number;
+    /** Scale factor (high = k*N). Integer >= 2. Default 8. */
+    k?: number;
+    /** Wait (ms) after the hot loop. Finite >= 0 (0 is legal and honored). Default 100. */
+    flushMs?: number;
+    /** Run without --expose-gc; retained is dropped and retainedReliable is false. */
+    allowNoGc?: boolean;
 }
 
 export interface Thresholds {
@@ -51,6 +72,16 @@ export interface Thresholds {
     maxScavenges?: number;
     /** Max retained heap growth in KB. Default 64. */
     maxRetainedKB?: number;
+    /**
+     * Max allowed old-gen activity (major + incremental) at k*N. Default 0.
+     * When it trips, diagnose the cause with @zakkster/lite-gc-profiler.
+     */
+    maxOldGen?: number;
+    /**
+     * Max allowed external/arrayBuffers growth in KB at k*N. Default 64.
+     * Ungated under allowNoGc; an explicit value with allowNoGc throws.
+     */
+    maxArrayBuffersKB?: number;
     /** Per-counter maximum allowed delta. */
     counters?: Record<string, number>;
 }
@@ -71,33 +102,55 @@ export interface GateConfig {
     maxScavenges?: number;
     /** Max retained heap growth in KB. Default 64. */
     maxRetainedKB?: number;
+    /** Max old-gen activity (major + incremental) at k*N. Default 0. */
+    maxOldGen?: number;
+    /** Max external/arrayBuffers growth in KB at k*N. Default 64 (undefined under allowNoGc). */
+    maxArrayBuffersKB?: number;
     /** Counter thresholds for statsOf deltas. */
     counters?: Record<string, number>;
     /** Override positive control. */
     positiveControl?: Scenario;
     /** Override negative control. */
     negativeControl?: Scenario;
+    /** Override the large/external detector control (controlLarge). */
+    largeControl?: 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.
+     * 0 is legal and honored.
      */
     flushMs?: number;
+    /**
+     * Permit an empty scenarios array: the ONLY sanctioned empty gate, a
+     * controls-only detector smoke run. Otherwise an empty/missing/non-array
+     * scenarios throws.
+     */
+    allowEmpty?: boolean;
+    /**
+     * Run without --expose-gc. The retained rule is not applied at all (the
+     * default 64KB threshold included) and combining it with an explicit
+     * maxRetainedKB throws. Scavenges and counters still gate.
+     */
+    allowNoGc?: boolean;
 }
 
 export interface GateResult {
     passed: boolean;
+    /** 0 pass, 1 scenario or must-fail failure, 2 detector validation failed. passed === (code === 0). */
+    code: 0 | 1 | 2;
     results: MeasureResult[];
 }
 
 /**
  * Measure a scenario at N and k*N iterations. Returns raw measurements.
+ * Bad options throw; missing --expose-gc throws unless allowNoGc is set.
  */
 export function measure(
     scenario: Scenario,
-    options?: { N?: number; k?: number; flushMs?: number }
+    options?: MeasureOptions
 ): Promise<MeasureResult>;
 
 /**
@@ -114,6 +167,13 @@ export const controlPositive: Scenario;
 /** Built-in negative control (pure arithmetic, zero allocation). */
 export const controlNegative: Scenario;
 
+/**
+ * Built-in large/external control: a bounded, mask-gated retained pool of 64KB
+ * ArrayBuffers that trips the arrayBuffers signal. Validates the external
+ * detector in zgcSuite/runGate (decisions/0003).
+ */
+export const controlLarge: Scenario;
+
 /**
  * Register node:test cases: detector validation, scenario gating, and
  * must-fail self-tests. The primary public API.
@@ -123,7 +183,8 @@ export const controlNegative: Scenario;
 export function zgcSuite(config: GateConfig): void;
 
 /**
- * Standalone human-readable gate report. Returns pass/fail and raw results.
+ * Standalone human-readable gate report. Returns `{ passed, code, results }`;
+ * never touches process.exitCode -- map result.code to your exit code.
  */
 export function runGate(config: GateConfig): Promise<GateResult>;
 
@@ -153,6 +214,13 @@ export interface SuiteBudget {
     reduce?: 'count' | 'sum' | 'max' | 'mean' | 'last';
     /** Inclusive budget: verdict() flags value > max. */
     max: number;
+    /**
+     * Optional presence assertion. Integer >= 0 (else RangeError at config).
+     * Fails the budget when fewer records matched than minCount, with reason
+     * '<name>: matched <count> < minCount <n>'. Omitted or 0 is inert: a
+     * zero-match budget still reduces to 0 and passes (v1.1 back-compat).
+     */
+    minCount?: number;
 }
 
 export interface SuiteBudgetResult {
@@ -160,6 +228,8 @@ export interface SuiteBudgetResult {
     value: number;
     count: number;
     max: number;
+    /** The effective minCount (0 when the budget omitted it). */
+    minCount: number;
     pass: boolean;
     reasons: string[];
 }
@@ -175,7 +245,20 @@ export interface SuiteGateResult {
  * Evaluate SPP stream records against numeric budgets. Pure reduction with
  * per-budget delegation to verdict(); no measurement, no process exit
  * codes, no record emission. Wide-record CONT payloads are not budget
- * targets in v1.1 (base-record t/a/b slots only).
+ * targets (base-record t/a/b slots only).
+ *
+ * The source contract (v1.4.0 record doors, decisions/0004):
+ *  THROWS (data-integrity refusal): a slab record whose packed header is not
+ *  a u32 (RangeError naming the record index); a non-Float64Array or
+ *  cross-realm typed-array source (its forEach binds (value, index, array));
+ *  a forEach source whose ANY invocation is not four numbers (checked every
+ *  record, naming the invocation index and slot); slot/reduce
+ *  inherited-prototype keys; a budget targeting CONT (0x0F01), op or packed
+ *  form; a bad minCount.
+ *  FAILS a budget (verdict): a reduced value that is not finite ->
+ *  '<name>: not a number (fail closed)'; count < minCount ->
+ *  '<name>: matched <count> < minCount <n>'. Budget names may be any non-empty
+ *  string, including 'toString' / '__proto__' / 'constructor'.
  */
 export function suiteGate(config: {
     source: Float64Array | SppRecordSource;