@zakkster/lite-perf-gate 1.0.1 → 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

package/PerfGate.d.ts

@@ -129,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';
@@ -428,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

package/llms.txt

@@ -63,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,63 +1,63 @@
 {
-    "name": "@zakkster/lite-perf-gate",
-    "version": "1.0.1",
-    "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"
+  "name": "@zakkster/lite-perf-gate",
+  "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",
+  "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"
+  }
 }