@zakkster/lite-perf-gate 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [1.2.0] - 2026-07-07
+
+- **`toNDJSON(x, meta?)`** -- NDJSON verdict output for CI artifacts.
+  Accepts a `suiteGate()` result, a `measure()` result, or an array of
+  either; emits `budget` lines before their `suite-gate` summary line and
+  `measure` lines, with optional per-run `meta` fields merged into every
+  line. Otherwise the API is frozen, per the suite roadmap.
+
+## [1.1.0] - 2026-07-07
+
+- **`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,
+  matched by packed header, stream+op, or op-only), and delegates every
+  threshold comparison to `verdict()` -- one comparison authority,
+  per-budget structured results. No package import: lite-perf-gate speaks
+  the Scope Probe Protocol (SPP v1), it does not depend on lite-scope.
+  suiteGate never touches process exit codes; runner semantics (0/1/3 in
+  the VersionMatrix scripts, 0/1/2 in `runGate`) stay in the runner layer.
+  CONT continuation records are never budget targets in v1.1.
+- **Version discipline fix**: `VERSION` now reads `1.2.0` and the self-test
+  asserts it against `package.json` (the published 1.0.1 tarball shipped
+  `VERSION = '1.0.0'` because the old test pinned a literal instead of the
+  manifest -- that class of slip is now structurally impossible).
+
 ## [1.0.0] - 2026-07-07
 
 Initial release. Generalized from the `@zakkster/lite-signal` zero-GC gate
@@ -22,6 +47,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>;
 
 /**
@@ -123,3 +129,67 @@ export function runGate(config: GateConfig): Promise<GateResult>;
 
 /** @internal */
 export function _controlKeepAlive(): number;
+
+// ---------------------------------------------------------------------------
+// suiteGate (v1.1) + toNDJSON (v1.2)
+// ---------------------------------------------------------------------------
+
+/** forEach-style SPP record source (e.g. a lite-scope memory sink). */
+export interface SppRecordSource {
+    forEach(cb: (packed: number, t: number, a: number, b: number) => void): void;
+}
+
+export interface SuiteBudget {
+    name: string;
+    /** Exact packed header (streamId << 16 | opcode). */
+    packed?: number;
+    /** Stream id; combine with op for an exact match. */
+    stream?: number;
+    /** Opcode; alone it matches the op on any stream. */
+    op?: number;
+    /** Record slot to read. Default 'a'. */
+    slot?: 't' | 'a' | 'b';
+    /** Reduction over matching records. Default 'max'. */
+    reduce?: 'count' | 'sum' | 'max' | 'mean' | 'last';
+    /** Inclusive budget: verdict() flags value > max. */
+    max: number;
+}
+
+export interface SuiteBudgetResult {
+    name: string;
+    value: number;
+    count: number;
+    max: number;
+    pass: boolean;
+    reasons: string[];
+}
+
+export interface SuiteGateResult {
+    name: string;
+    pass: boolean;
+    reasons: string[];
+    budgets: SuiteBudgetResult[];
+}
+
+/**
+ * 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).
+ */
+export function suiteGate(config: {
+    source: Float64Array | SppRecordSource;
+    budgets: SuiteBudget[];
+    name?: string;
+}): SuiteGateResult;
+
+/**
+ * Serialize suiteGate() and/or measure() results as NDJSON for CI
+ * artifacts: one JSON object per line, budget lines before their
+ * suite-gate summary, trailing newline. `meta` fields merge into every
+ * line; core fields win on collision.
+ */
+export function toNDJSON(
+    x: SuiteGateResult | MeasureResult | Array<SuiteGateResult | MeasureResult>,
+    meta?: Record<string, unknown>
+): string;

package/PerfGate.js

@@ -17,7 +17,7 @@
  * MIT License
  */
 
-export const VERSION = '1.0.0';
+export const VERSION = '1.2.0';
 
 import {PerformanceObserver, constants} from 'node:perf_hooks';
 import {setTimeout as sleep} from 'node:timers/promises';
@@ -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,
@@ -403,3 +428,230 @@ export async function runGate(config) {
     }
     return {passed: passed, results: results};
 }
+
+// ---------------------------------------------------------------------------
+// suiteGate -- SPP stream-fed budgets (v1.1)
+// ---------------------------------------------------------------------------
+// lite-perf-gate does NOT import @zakkster/lite-scope. Probes, gates, and
+// consumers are coupled by the Scope Probe Protocol (SPP v1 -- PROTOCOL.md
+// in lite-scope), never by packages. The two protocol facts used here:
+//   - a record is 4 numbers [packed, t, a, b], where
+//     packed = (streamId << 16 | opcode) >>> 0, both u16;
+//   - opcode 0x0F01 (CONT) is a wide-record continuation and is never a
+//     budget target. Budgets therefore see the base record's t/a/b slots;
+//     extended CONT payload slots are out of scope for v1.1 (a lite-scope
+//     side bridge can pre-reduce wide records if that ever gates).
+// suiteGate never touches process exit codes: runner semantics (0 pass /
+// 1 regression / 3 recapture in the VersionMatrix scripts, 0/1/2 in
+// runGate) stay in the runner layer. All threshold comparison is delegated
+// to verdict() -- one comparison authority, per-budget.
+
+var SPP_OP_CONT = 0x0F01;
+
+var SUITE_REDUCES = {count: 1, sum: 1, max: 1, mean: 1, last: 1};
+var SUITE_SLOTS = {t: 1, a: 2, b: 3};
+
+function suiteMatcher(b, i) {
+    if (b.packed !== undefined) {
+        if (!Number.isInteger(b.packed) || b.packed < 0 || b.packed > 0xFFFFFFFF) {
+            throw new RangeError('suiteGate: budget[' + i + '] packed must be a u32');
+        }
+        return {exact: b.packed >>> 0, op: -1};
+    }
+    if (b.op === undefined || !Number.isInteger(b.op) || b.op < 0 || b.op > 0xFFFF) {
+        throw new RangeError('suiteGate: budget[' + i + '] needs a u16 op (with optional stream), or packed');
+    }
+    if (b.stream !== undefined) {
+        if (!Number.isInteger(b.stream) || b.stream < 0 || b.stream > 0xFFFF) {
+            throw new RangeError('suiteGate: budget[' + i + '] stream must be a u16');
+        }
+        return {exact: ((b.stream << 16) | b.op) >>> 0, op: -1};
+    }
+    return {exact: -1, op: b.op}; // op-only: matches the op on any stream
+}
+
+/**
+ * Evaluate SPP stream records against numeric budgets. Pure reduction plus
+ * per-budget delegation to verdict(); no measurement, no exit codes, no
+ * record emission (callers bridge verdicts to GATE_VERDICT meta records).
+ *
+ * @param {object} config
+ * @param {Float64Array | { forEach: (cb: (packed: number, t: number, a: number, b: number) => void) => void }} config.source
+ *   A contiguous SPP slab (length divisible by 4) or any forEach-style
+ *   record source (e.g. a lite-scope memory sink).
+ * @param {Array<{
+ *   name: string,
+ *   packed?: number, stream?: number, op?: number,
+ *   slot?: 't' | 'a' | 'b',
+ *   reduce?: 'count' | 'sum' | 'max' | 'mean' | 'last',
+ *   max: number
+ * }>} config.budgets
+ *   slot defaults to 'a', reduce to 'max'. Budgets that match zero records
+ *   reduce to 0 (count 0 is reported so callers can tell silence from luck).
+ * @param {string} [config.name='suite-gate']
+ * @returns {{
+ *   name: string, pass: boolean, reasons: string[],
+ *   budgets: Array<{ name: string, value: number, count: number, max: number, pass: boolean, reasons: string[] }>
+ * }}
+ */
+export function suiteGate(config) {
+    if (!config || typeof config !== 'object') {
+        throw new TypeError('suiteGate: expects a config object');
+    }
+    const source = config.source;
+    const budgets = config.budgets;
+    if (!Array.isArray(budgets) || budgets.length === 0) {
+        throw new TypeError('suiteGate: budgets must be a non-empty array');
+    }
+
+    const n = budgets.length;
+    const match = new Array(n);
+    const slot = new Array(n);
+    const reduce = new Array(n);
+    const seen = {};
+    for (let i = 0; i < n; i++) {
+        const b = budgets[i];
+        if (!b || typeof b.name !== 'string' || b.name.length === 0) {
+            throw new TypeError('suiteGate: budget[' + i + '] needs a non-empty name');
+        }
+        if (seen[b.name]) throw new RangeError('suiteGate: duplicate budget name "' + b.name + '"');
+        seen[b.name] = 1;
+        if (typeof b.max !== 'number' || !isFinite(b.max)) {
+            throw new RangeError('suiteGate: budget "' + b.name + '" needs a finite numeric max');
+        }
+        const sl = b.slot === undefined ? 'a' : b.slot;
+        if (SUITE_SLOTS[sl] === undefined) {
+            throw new RangeError('suiteGate: budget "' + b.name + '" slot must be t, a, or b');
+        }
+        const rd = b.reduce === undefined ? 'max' : b.reduce;
+        if (SUITE_REDUCES[rd] === undefined) {
+            throw new RangeError('suiteGate: budget "' + b.name + '" reduce must be count, sum, max, mean, or last');
+        }
+        match[i] = suiteMatcher(b, i);
+        slot[i] = SUITE_SLOTS[sl];
+        reduce[i] = rd;
+    }
+
+    const count = new Float64Array(n);
+    const sum = new Float64Array(n);
+    const maxv = new Float64Array(n);
+    const last = new Float64Array(n);
+    maxv.fill(-Infinity);
+
+    function visit(packed, t, a, b) {
+        const op = packed & 0xFFFF;
+        if (op === SPP_OP_CONT) return;
+        for (let i = 0; i < n; i++) {
+            const m = match[i];
+            if (m.exact >= 0 ? (packed >>> 0) !== m.exact : op !== m.op) continue;
+            const val = slot[i] === 1 ? t : slot[i] === 2 ? a : b;
+            count[i] += 1;
+            sum[i] += val;
+            if (val > maxv[i]) maxv[i] = val;
+            last[i] = val;
+        }
+    }
+
+    if (source && typeof source.forEach === 'function' && !(source instanceof Float64Array)) {
+        source.forEach(visit);
+    } else if (source instanceof Float64Array) {
+        if (source.length % 4 !== 0) {
+            throw new RangeError('suiteGate: slab length must be divisible by 4');
+        }
+        for (let r = 0; r < source.length; r += 4) {
+            visit(source[r], source[r + 1], source[r + 2], source[r + 3]);
+        }
+    } else {
+        throw new TypeError('suiteGate: source must be a Float64Array slab or a forEach record source');
+    }
+
+    const perBudget = [];
+    const reasons = [];
+    let pass = true;
+    for (let i = 0; i < n; i++) {
+        const b = budgets[i];
+        let value;
+        if (reduce[i] === 'count') value = count[i];
+        else if (reduce[i] === 'sum') value = sum[i];
+        else if (reduce[i] === 'max') value = count[i] > 0 ? maxv[i] : 0;
+        else if (reduce[i] === 'mean') value = count[i] > 0 ? sum[i] / count[i] : 0;
+        else value = count[i] > 0 ? last[i] : 0;
+
+        const counters = {};
+        counters[b.name] = value;
+        const ct = {};
+        ct[b.name] = b.max;
+        const v = verdict(
+            {name: b.name, minorHi: 0, majorHi: 0, retainedKB_hi: 0, counters_hi: counters},
+            {counters: ct}
+        );
+        if (!v.pass) pass = false;
+        for (let ri = 0; ri < v.reasons.length; ri++) reasons.push(v.reasons[ri]);
+        perBudget.push({
+            name: b.name, value: value, count: count[i], max: b.max,
+            pass: v.pass, reasons: v.reasons
+        });
+    }
+
+    return {
+        name: typeof config.name === 'string' ? config.name : 'suite-gate',
+        pass: pass,
+        reasons: reasons,
+        budgets: perBudget
+    };
+}
+
+// ---------------------------------------------------------------------------
+// toNDJSON -- verdict output for CI artifacts (v1.2)
+// ---------------------------------------------------------------------------
+
+function ndjsonSuiteGate(r, meta, lines) {
+    for (let i = 0; i < r.budgets.length; i++) {
+        const b = r.budgets[i];
+        lines.push(JSON.stringify(Object.assign({}, meta, {
+            type: 'budget', gate: r.name, name: b.name,
+            value: b.value, count: b.count, max: b.max, pass: b.pass
+        })));
+    }
+    lines.push(JSON.stringify(Object.assign({}, meta, {
+        type: 'suite-gate', name: r.name, pass: r.pass, reasons: r.reasons
+    })));
+}
+
+function ndjsonMeasure(r, meta, lines) {
+    lines.push(JSON.stringify(Object.assign({}, meta, {
+        type: 'measure', name: r.name, N: r.N, k: r.k,
+        minorLo: r.minorLo, minorHi: r.minorHi,
+        majorLo: r.majorLo, majorHi: r.majorHi,
+        retainedKB_lo: r.retainedKB_lo, retainedKB_hi: r.retainedKB_hi,
+        counters_lo: r.counters_lo, counters_hi: r.counters_hi
+    })));
+}
+
+/**
+ * Serialize gate output as NDJSON for CI artifacts: one JSON object per
+ * line, budget lines before their suite-gate summary line, trailing
+ * newline. Accepts a suiteGate() result, a measure() result, or an array
+ * mixing both. `meta` fields (run id, package, version, ...) are merged
+ * into every line; core fields win on collision.
+ *
+ * @param {object | object[]} x
+ * @param {object} [meta]
+ * @returns {string}
+ */
+export function toNDJSON(x, meta) {
+    const rows = Array.isArray(x) ? x : [x];
+    const m = meta && typeof meta === 'object' ? meta : {};
+    const lines = [];
+    for (let i = 0; i < rows.length; i++) {
+        const r = rows[i];
+        if (r && Array.isArray(r.budgets) && typeof r.pass === 'boolean') {
+            ndjsonSuiteGate(r, m, lines);
+        } else if (r && typeof r.minorHi === 'number' && typeof r.N === 'number') {
+            ndjsonMeasure(r, m, lines);
+        } else {
+            throw new TypeError('toNDJSON: row ' + i + ' is neither a suiteGate result nor a measure result');
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/README.md

@@ -24,6 +24,44 @@ npm install @zakkster/lite-perf-gate
 
 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.
 
+
+## suiteGate -- SPP stream-fed budgets (v1.1)
+
+Gate live probe streams, not just measured scenarios. `suiteGate()` reads
+SPP records (a `Float64Array` slab or any `forEach(cb(packed, t, a, b))`
+source -- a `@zakkster/lite-scope` memory sink qualifies), reduces each
+budget's metric, and delegates every comparison to `verdict()`:
+
+```js
+import { suiteGate, toNDJSON } from '@zakkster/lite-perf-gate';
+
+const gate = suiteGate({
+    name: 'ci-gate',
+    source: sink.toSlab(),          // or the sink itself (forEach source)
+    budgets: [
+        { name: 'gc.pause.max', stream: 2, op: 0x0201, slot: 'a', reduce: 'max',   max: 8 },
+        { name: 'leak.orphans',            op: 0x0801,            reduce: 'count', max: 0 },
+        { name: 'inp.worst',               op: 0x0601, slot: 'a', reduce: 'max',   max: 200 }
+    ]
+});
+
+process.stdout.write(toNDJSON(gate, { pkg: 'my-lib', run: process.env.CI_RUN }));
+if (!gate.pass) process.exitCode = 1;   // exit codes stay in YOUR runner
+```
+
+No package coupling: lite-perf-gate speaks the Scope Probe Protocol
+(SPP v1, `PROTOCOL.md` in lite-scope) and never imports lite-scope.
+CONT continuation records are never budget targets (base-record slots
+only in v1.1). `suiteGate` returns structured per-budget verdicts and
+leaves exit codes to the runner layer.
+
+## toNDJSON -- CI artifacts (v1.2)
+
+One JSON object per line: `budget` lines, then the `suite-gate` summary;
+`measure()` results serialize as `measure` lines. Optional `meta` fields
+(package, run id, versions) merge into every line. Pipe to a file in your
+gate script and attach it as a CI artifact.
+
 ## Quick start
 
 ```js
@@ -134,6 +172,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).
@@ -49,3 +63,14 @@ is the only reliable detector of transient allocation in V8.
 
 Single-file ESM. Imports only node:perf_hooks, node:timers/promises,
 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.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-perf-gate",
-  "version": "1.0.0",
+  "version": "1.2.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",