@bldrs-ai/conway 1.556.1524 → 1.558.1533

package/compiled/examples/browser-bundled.cjs

@@ -30,7 +30,7 @@ var import_node_process = require("node:process");
 var readline = __toESM(require("node:readline"), 1);
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.556.1524";
+var versionString = "Conway v1.558.1533";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";

package/compiled/examples/cli-bundled.cjs

@@ -14965,7 +14965,7 @@ ${t5.join("\n")}` : "";
 var import_process = require("process");
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.556.1524";
+var versionString = "Conway v1.558.1533";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {

package/compiled/examples/cli-step-bundled.cjs

@@ -15943,7 +15943,7 @@ var ParsingBuffer = class {
 };
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.556.1524";
+var versionString = "Conway v1.558.1533";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {

package/compiled/examples/validator-bundled.cjs

@@ -944,7 +944,7 @@ var EntityTypesIfcCount = 909;
 var entity_types_ifc_gen_default = EntityTypesIfc;
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.556.1524";
+var versionString = "Conway v1.558.1533";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";

package/compiled/src/core/retained_memory.d.ts

@@ -87,8 +87,16 @@ export declare function canSettleMemory(): boolean;
  * produces `parseTimeMs` / `geometryTimeMs` / `totalTimeMs` — baseline before
  * the load starts, retained sample after teardown. That property is what
  * makes the retention columns free, and it is checkable by measurement: a run
- * with `--expose-gc` and a run without share identical code, so if the timing
- * columns move between them, the settle is leaking into the measured window.
+ * with `--expose-gc` and a run without share identical code, so any movement
+ * in the timing columns between them is down to the settle. The SIGN says
+ * which way: gc-on slower is the settle leaking into the measured window,
+ * which is a bug; gc-on faster is the pre-load settle taking engine-init
+ * garbage OUT of that window. That is an absolute cost of about 10 ms per
+ * load, measured as 13-16% of `parseTimeMs` on models that parse in ~60 ms
+ * and unresolvable against one that parses in 578 ms, so read a ratio
+ * against the model's own parse time. `rc-regression.yml` runs both
+ * conditions in one job; see design/new/perf-measurement.md §"The settle
+ * also cleans the window".
  *
  * @return {Promise<SettledMemorySample | undefined>} The settled sample, or
  * undefined where no collector is exposed — in which case the caller emits

package/compiled/src/core/retained_memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retained_memory.d.ts","sourceRoot":"","sources":["../../../src/core/retained_memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AASH;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAElC,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAA;IAEhB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAA;IAErB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAE/B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;IAEb,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAA;IAElB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,IAAI,CAAE,MAAM,IAAI,CAAE,GAAG,SAAS,CAKtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAKzC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,qBAAqB,IACvC,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAuB3C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,4BAA4B,CAC9C,QAAQ,EAAE,MAAM,GAAI,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAG/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,mBAAmB,GAAG,SAAS,EACzC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,GAAI,gBAAgB,GAAG,SAAS,CAa5E"}
+{"version":3,"file":"retained_memory.d.ts","sourceRoot":"","sources":["../../../src/core/retained_memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AASH;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAElC,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAA;IAEhB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAA;IAErB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAE/B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;IAEb,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAA;IAElB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,IAAI,CAAE,MAAM,IAAI,CAAE,GAAG,SAAS,CAKtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAKzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,qBAAqB,IACvC,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAuB3C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,4BAA4B,CAC9C,QAAQ,EAAE,MAAM,GAAI,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAG/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,mBAAmB,GAAG,SAAS,EACzC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,GAAI,gBAAgB,GAAG,SAAS,CAa5E"}

package/compiled/src/core/retained_memory.js

@@ -72,8 +72,16 @@ export function canSettleMemory() {
  * produces `parseTimeMs` / `geometryTimeMs` / `totalTimeMs` — baseline before
  * the load starts, retained sample after teardown. That property is what
  * makes the retention columns free, and it is checkable by measurement: a run
- * with `--expose-gc` and a run without share identical code, so if the timing
- * columns move between them, the settle is leaking into the measured window.
+ * with `--expose-gc` and a run without share identical code, so any movement
+ * in the timing columns between them is down to the settle. The SIGN says
+ * which way: gc-on slower is the settle leaking into the measured window,
+ * which is a bug; gc-on faster is the pre-load settle taking engine-init
+ * garbage OUT of that window. That is an absolute cost of about 10 ms per
+ * load, measured as 13-16% of `parseTimeMs` on models that parse in ~60 ms
+ * and unresolvable against one that parses in 578 ms, so read a ratio
+ * against the model's own parse time. `rc-regression.yml` runs both
+ * conditions in one job; see design/new/perf-measurement.md §"The settle
+ * also cleans the window".
  *
  * @return {Promise<SettledMemorySample | undefined>} The settled sample, or
  * undefined where no collector is exposed — in which case the caller emits

package/compiled/src/ifc/ifc_regression_batch_main.js

@@ -29,9 +29,18 @@ const CHILD_NODE_FLAGS = '--experimental-specifier-resolution=node';
  * both samples sit outside the timed region — baseline before the load,
  * retained sample after teardown — so a run with the flag and a run without
  * should produce the same timing columns from identical code. Set the
- * variable to `0`, `false` or `off` for the without side of that A/B. If the
- * timing columns move between the two, the settle is reaching the measured
- * window, and that is a bug rather than a tolerance.
+ * variable to `0`, `false` or `off` for the without side of that A/B; the
+ * `rebless` job of `.github/workflows/rc-regression.yml` does exactly that
+ * for its second, control pass, because the two conditions have to share a
+ * runner for the comparison to mean anything (between two CI runs the timing
+ * columns carry a ~1.5x runner scale factor against a ~1% effect).
+ *
+ * Read any movement with its sign. Gc-on SLOWER means the settle is reaching
+ * the measured window, which is a bug rather than a tolerance. Gc-on FASTER
+ * means the opposite — the pre-load settle collects engine-init garbage that
+ * the flag-off run collects inside the timed region instead. That is about
+ * 10 ms per load: 13-16% of `parseTimeMs` on a model that parses in ~60 ms,
+ * and lost in the noise on one that parses in 578 ms.
  *
  * @return {boolean} True unless CONWAY_PERF_EXPOSE_GC disables it.
  */

package/compiled/src/ifc/ifc_regression_main.js

@@ -221,7 +221,11 @@ function displayErrors(filePath) {
  */
 async function main() {
     try {
-        await conwayGeom.initialize();
+        const initializationStatus = await conwayGeom.initialize();
+        if (!initializationStatus) {
+            console.error("Couldn't initialize conway-geom, exiting...");
+            return;
+        }
         Environment.checkEnvironment();
         Logger.initializeWasmCallbacks();
         doWork();
@@ -345,21 +349,20 @@ function doWork() {
         }
         model.nullOnErrors = !strict;
         const geomStartMs = Date.now();
-        const result = await geometryExtraction(model);
+        const scene = geometryExtraction(model);
         const geomEndMs = Date.now();
         const geometryTimeMs = geomEndMs - geomStartMs;
         const totalTimeMs = geomEndMs - parseStartMs;
-        const perfStatus = result === void 0 ? "FAIL" : "OK";
+        const perfStatus = scene === void 0 ? "FAIL" : "OK";
         // Sized before anything downstream can release meshes, and only on
         // the OK path: a failed extraction leaves a partial cache whose size
         // is not this model's geometry footprint.
-        const geometryMemoryBytes = result !== void 0 ?
+        const geometryMemoryBytes = scene !== void 0 ?
             model.geometry.calculateGeometrySize() : void 0;
         // The heap is grow-only, so this is the run's high-water mark even
-        // though it is read once, after the fact. geometryExtraction hands
-        // back the engine it brought up; there is no heap to measure when
-        // it failed before that.
-        const wasmModule = result?.[1].wasmModule;
+        // though it is read once, after the fact. conwayGeom is the engine
+        // every extraction in this process runs against.
+        const wasmModule = conwayGeom.wasmModule;
         const wasmHeapBytes = wasmModule !== void 0 ?
             wasmHeapByteLength(wasmModule) : void 0;
         // Instants captured here, where they have always been captured, so
@@ -397,7 +400,7 @@ function doWork() {
         // AFTP sizing pass: no-op unless the wasm module was built with
         // CONWAY_ALLOC_TELEMETRY (see conway-geom structures/alloc_telemetry.h).
         conwayGeom.dumpAllocTelemetry(path.basename(ifcFile));
-        if (result === void 0) {
+        if (scene === void 0) {
             Logger.error("Couldn't extract geometry");
         }
         else {
@@ -468,17 +471,23 @@ function doWork() {
         .help().argv;
 }
 /**
- * Function to extract Geometry from an IfcStepModel
+ * Function to extract Geometry from an IfcStepModel.
+ *
+ * Runs against the module-level `conwayGeom` that `main()` brought up, the
+ * way the AP214 child does. It used to construct and initialise a *second*
+ * `ConwayGeometry` here (conway#557), which made the engine that did the work
+ * a different object from the one `main()` initialised and
+ * `dumpAllocTelemetry` reported on — so the telemetry described an idle
+ * module, and the second engine's linear memory (106.5 MB on MB-Khaya
+ * against engine A's untouched 16 MB arena) was allocated inside the
+ * retention window and never released.
  *
  * @param model
+ * @return {IfcSceneBuilder | undefined} The extracted scene, or undefined on
+ * failure.
  */
-async function geometryExtraction(model) {
-    const conwaywasm = new ConwayGeometry();
-    const initializationStatus = await conwaywasm.initialize();
-    if (!initializationStatus) {
-        return;
-    }
-    const conwayModel = new IfcGeometryExtraction(conwaywasm, model);
+function geometryExtraction(model) {
+    const conwayModel = new IfcGeometryExtraction(conwayGeom, model);
     RegressionCaptureState.memoization = MemoizationCapture.FULL;
     // parse + extract data model + geometry data
     const [extractionResult, scene] = conwayModel.extractIFCGeometryData();
@@ -486,5 +495,5 @@ async function geometryExtraction(model) {
         console.error("Could not extract geometry, exiting...");
         return void 0;
     }
-    return [scene, conwaywasm];
+    return scene;
 }

package/compiled/src/ifc/ifc_regression_single_engine.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ifc_regression_single_engine.test.d.ts.map

package/compiled/src/ifc/ifc_regression_single_engine.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ifc_regression_single_engine.test.d.ts","sourceRoot":"","sources":["../../../src/ifc/ifc_regression_single_engine.test.ts"],"names":[],"mappings":""}

package/compiled/src/ifc/ifc_regression_single_engine.test.js

@@ -0,0 +1,61 @@
+import fs from 'fs';
+import path from 'path';
+import { describe, expect, test } from '@jest/globals';
+/**
+ * One wasm engine per regression child, and it is the engine the extraction
+ * runs against (conway#557).
+ *
+ * The IFC child used to initialise a `ConwayGeometry` in `main()` and then
+ * construct a *second* one inside `geometryExtraction`. The extraction ran
+ * against the second; `dumpAllocTelemetry` — and, later, `peakWasmHeapMb` —
+ * reported on the first, which never did any work. Measured on MB-Khaya
+ * before the fix: telemetry engine 16,777,216 bytes of untouched initial
+ * arena, extraction engine 106,496,000 bytes, `sameObject=false`. The second
+ * engine was also created after `settleAndSampleMemoryForPerf` took the
+ * pre-load baseline, so its whole footprint landed inside the retention
+ * window and put a ~55-60 MB constant into every IFC `retainedRssMb`.
+ *
+ * This is asserted against the SOURCE TEXT rather than by running the
+ * children, because both are process entry points: they call `main()` at
+ * module scope and drive `yargs` off `process.argv`, so importing either one
+ * from a test starts a regression run. The property is structural — how many
+ * engines the file builds and which one every consumer names — so the text is
+ * where it can be checked at all. A runtime equivalent would need the child
+ * to expose its engines, which is a larger change to production code than the
+ * defect warrants.
+ */
+describe('regression children use a single wasm engine', () => {
+    // Resolved from the repo root rather than relative to this file: the test
+    // runs from compiled/src/ifc, and the TypeScript sources are not part of
+    // the tsc output. Jest's rootDir is the repo root.
+    const ifcSource = fs.readFileSync(path.resolve(process.cwd(), 'src/ifc/ifc_regression_main.ts'), 'utf8');
+    const ap214Source = fs.readFileSync(path.resolve(process.cwd(), 'src/AP214E3_2010/ap214_regression_main.ts'), 'utf8');
+    /**
+     * Count non-overlapping matches of a global pattern.
+     *
+     * @param source Text to search.
+     * @param pattern Global regular expression to count matches of.
+     * @return {number} Number of matches.
+     */
+    function countMatches(source, pattern) {
+        return (source.match(pattern) ?? []).length;
+    }
+    test('the IFC child constructs exactly one ConwayGeometry', () => {
+        expect(countMatches(ifcSource, /new ConwayGeometry\(/g)).toBe(1);
+    });
+    test('the AP214 child constructs exactly one ConwayGeometry', () => {
+        // The reference for what right looks like here; it has always had one.
+        expect(countMatches(ap214Source, /new ConwayGeometry\(/g)).toBe(1);
+    });
+    test('the IFC extraction, telemetry and heap figure name one engine', () => {
+        expect(ifcSource).toContain('new IfcGeometryExtraction(conwayGeom, model)');
+        expect(ifcSource).toContain('conwayGeom.dumpAllocTelemetry(');
+        expect(ifcSource).toContain('const wasmModule = conwayGeom.wasmModule');
+    });
+    test('the AP214 extraction, telemetry and heap figure name one engine', () => {
+        expect(ap214Source)
+            .toContain('new AP214GeometryExtraction(conwayGeom, model)');
+        expect(ap214Source).toContain('conwayGeom.dumpAllocTelemetry(');
+        expect(ap214Source).toContain('const wasmModule = conwayGeom.wasmModule');
+    });
+});

package/compiled/src/scripts/bless_perf_snapshot.test.js

@@ -16,7 +16,7 @@ import { createRequire } from 'module';
 const require_ = createRequire(import.meta.url);
 // Resolved from the repo root: the test runs from compiled/src/scripts, and
 // scripts/ is not part of the tsc build. Jest's rootDir is the repo root.
-const { DETAIL_COLUMNS, findPreviousSnapshot, isChronologicalDelta, removeStaleDeltas, writeDetailCsv, versionCompare, } = require_(path.resolve(process.cwd(), 'scripts/bless_perf_snapshot.cjs'));
+const { DETAIL_COLUMNS, findPreviousSnapshot, isChronologicalDelta, removeStaleDeltas, renderReadme, writeDetailCsv, versionCompare, } = require_(path.resolve(process.cwd(), 'scripts/bless_perf_snapshot.cjs'));
 const { parseCsv } = require_(path.resolve(process.cwd(), 'scripts/csv_rfc4180.cjs'));
 let workDir;
 beforeEach(() => {
@@ -328,3 +328,90 @@ describe('isChronologicalDelta', () => {
         }
     });
 });
+describe('renderReadme', () => {
+    const info = {
+        engine: 'conway1.560.1600-ci',
+        repoName: 'test-models',
+        modelCount: 97,
+        retentionCount: 97,
+        deltaName: 'conway1.451.1357-ci_1.560.1600_delta.csv',
+        previousName: 'conway1.451.1357-ci_test-models',
+    };
+    test('does not repeat the pre-#553 claim that geometryMemoryMb is N/A', () => {
+        // #553 restored geometryMemoryMb on the conway-native writer (SKYLARK250
+        // reads 185.22 against the 185.836 recorded at 1.451). The README shipped
+        // beside the 1.549 snapshot still says it is unmeasured, which is now the
+        // opposite of the truth for a column carrying real data; that text was
+        // removed from this template, and this keeps it out.
+        const text = renderReadme(info);
+        expect(text).not.toContain('`geometryMemoryMb` is absent here');
+        expect(text).toContain('`schemaVersion`,\n`preprocessorVersion` and `originatingSystem` are `N/A`');
+        // The N/A-is-not-a-zero framing is the point of #548 and must survive for
+        // the columns genuinely absent from an older snapshot.
+        expect(text).toContain('That is a missing\nmeasurement, not a zero');
+    });
+    test('says on its own face whether the settle ran', () => {
+        // A directory of N/A retention must explain itself without anyone having
+        // to find the workflow that produced it.
+        expect(renderReadme(info)).toContain('Retention is measured on 97 of 97');
+        expect(renderReadme({ ...info, retentionCount: 0 }))
+            .toContain('Retention is `N/A` on every row here');
+    });
+    test('names the blessed pass as the one this snapshot came from', () => {
+        const text = renderReadme(info);
+        expect(text).toContain('CONWAY_PERF_EXPOSE_GC=0');
+        expect(text).toContain('The control pass is never blessed');
+    });
+    test('the N/A inventory covers the retention columns, not just FAIL rows', () => {
+        // A settle-less snapshot used to assert both 'Every other column is
+        // measured - with the exception of a row whose loadStatus is not OK' and
+        // 'Retention is `N/A` on every row here', four paragraphs apart in one
+        // file. The retention columns read N/A on an OK row whenever the run had
+        // no --expose-gc, which is exactly the run this branch describes.
+        const text = renderReadme({ ...info, retentionCount: 0 });
+        expect(text).toContain('Retention is `N/A` on every row here');
+        expect(text).not.toContain('Every other column is measured — with the');
+        expect(text).toContain('the three retention columns carry `N/A`');
+        expect(text).toContain('on an `OK` row as\nmuch as a failed one');
+    });
+    test('attributes the geometryMemoryMb split to the writers #555 measured', () => {
+        // #555 measured 16.8 vs 22.3 MB between `ifc_command_line_main` and the
+        // IFC regression child - two IFC pipelines. MB-Khaya never reaches the
+        // AP214 child, so pinning that figure to the IFC-row-vs-STEP-row split
+        // this file mixes would cite evidence for a claim it does not support.
+        const text = renderReadme(info);
+        expect(text).toContain('The IFC **CLI** and the IFC\nregression child read 16.8 vs 22.3 MB');
+        expect(text).toContain('has not been measured to disagree');
+    });
+    test('describes the second-engine term as closed by #557, not as current', () => {
+        // conway#557 landed: both regression children now extract on the engine
+        // main() initialised. A README still saying an IFC row carries ~100 MB of
+        // second engine would be describing a world that no longer exists - and
+        // the boundary that DOES matter now is that pre-#557 snapshots carry the
+        // constant and this one does not.
+        const text = renderReadme(info);
+        expect(text).toContain('carried a second, unrelated split until conway#557');
+        expect(text).toContain('~55-60 MB constant on every IFC row');
+        expect(text).not.toContain('roughly 100 MB');
+        expect(text).toContain('A snapshot blessed\nbefore conway#557');
+    });
+    test('warns off the misreadings the columns invite', () => {
+        const text = renderReadme(info);
+        // Retention is live model + leak, not leak.
+        expect(text).toContain('still-live model plus anything genuinely leaked');
+        // The two columns that are pipeline-scoped, with their issues.
+        expect(text).toContain('conway/issues/555');
+        expect(text).toContain('conway/issues/557');
+        // The third native quantity, and the arrayBuffers/external subset rule.
+        expect(text).toContain('getAllocationSize');
+        expect(text).toContain('ArrayBuffer subset');
+        // Cross-run timing carries the runner scale factor.
+        expect(text).toContain('median 1.55x');
+    });
+    test('names the delta and its predecessor, or says there is none', () => {
+        expect(renderReadme(info)).toContain('`conway1.451.1357-ci_1.560.1600_delta.csv` diffs this run against ' +
+            '`../conway1.451.1357-ci_test-models/`.');
+        expect(renderReadme({ ...info, deltaName: '', previousName: '' }))
+            .toContain('no delta was produced');
+    });
+});

package/compiled/src/scripts/perf_ab_compare.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=perf_ab_compare.test.d.ts.map

package/compiled/src/scripts/perf_ab_compare.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf_ab_compare.test.d.ts","sourceRoot":"","sources":["../../../src/scripts/perf_ab_compare.test.ts"],"names":[],"mappings":""}

package/compiled/src/scripts/perf_ab_compare.test.js

@@ -0,0 +1,218 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, test } from '@jest/globals';
+import { createRequire } from 'module';
+/**
+ * The rc-regression GC-settle A/B comparator (scripts/perf_ab_compare.cjs).
+ *
+ * The rc job runs the corpus twice in one job — the blessed pass in the
+ * shipped configuration, then a control pass with `CONWAY_PERF_EXPOSE_GC=0` —
+ * and differences them there, because between two separate CI runs the timing
+ * columns carry a ~1.5x runner scale factor two orders of magnitude larger
+ * than the ~1% effect under test (conway#554). This pins the three things
+ * that make the resulting number readable: that a control pass which measured
+ * retention is called out as an invalid A/B rather than reported as a result,
+ * that `N/A` propagates instead of being coerced to 0 (#548), and that
+ * `Date.now()`-quantised rows are excluded from the ratio statistics rather
+ * than allowed to dominate them.
+ */
+/* eslint-disable no-magic-numbers -- the literals here are the fixture
+   timings and percentile fractions the cases are about; naming a 0.1 or a
+   110 ms parse would hide the shape each case exists to express. */
+const require_ = createRequire(import.meta.url);
+const { RATIO_FLOOR_MS, checkSwitch, compareRuns, numeric, percentile, readPerfCsv, renderCsv, renderMarkdown, summariseColumn, } = require_(path.resolve(process.cwd(), 'scripts/perf_ab_compare.cjs'));
+/**
+ * A perf.csv row with the columns this comparator reads, overridable per test.
+ *
+ * @param overrides Column values to set.
+ * @return {PerfRow} The row.
+ */
+function row(overrides) {
+    return {
+        status: 'OK',
+        parseTimeMs: '100',
+        geometryTimeMs: '1000',
+        totalTimeMs: '1100',
+        heapUsedMb: '50.00',
+        rssMb: '300.00',
+        peakRssMb: '310.00',
+        retainedRssMb: 'N/A',
+        retainedHeapUsedMb: 'N/A',
+        retainedExternalMb: 'N/A',
+        ...overrides,
+    };
+}
+/**
+ * A blessed-pass row: the settle ran, so retention is measured.
+ *
+ * @param overrides Column values to set.
+ * @return {PerfRow} The row.
+ */
+function blessedRow(overrides) {
+    return row({
+        retainedRssMb: '380.00',
+        retainedHeapUsedMb: '10.00',
+        retainedExternalMb: '47.00',
+        ...overrides,
+    });
+}
+describe('readPerfCsv', () => {
+    let workDir;
+    beforeEach(() => {
+        workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'perf-ab-'));
+    });
+    afterEach(() => {
+        fs.rmSync(workDir, { recursive: true, force: true });
+    });
+    test('reads the 16-column perf.csv both passes write', () => {
+        // The exact header ifc_regression_main.ts emits, with a control-pass row:
+        // the file this comparator is pointed at in CI, not a reduced stand-in.
+        const file = path.join(workDir, 'perf-nogc.csv');
+        fs.writeFileSync(file, 'file,status,parseTimeMs,geometryTimeMs,totalTimeMs,geometryMemoryMb,' +
+            'peakWasmHeapMb,rssMb,peakRssMb,heapUsedMb,heapTotalMb,externalMb,' +
+            'arrayBuffersMb,retainedRssMb,retainedHeapUsedMb,retainedExternalMb\n' +
+            'AC20-FZK-Haus.ifc,OK,76,436,512,1.69,35.13,289.39,289.52,54.40,84.34,' +
+            '9.98,7.93,N/A,N/A,N/A\n');
+        const rows = readPerfCsv(file);
+        expect(rows).toHaveLength(1);
+        expect(rows[0].file).toBe('AC20-FZK-Haus.ifc');
+        expect(rows[0].totalTimeMs).toBe('512');
+        expect(rows[0].retainedRssMb).toBe('N/A');
+    });
+    test('an empty file is no rows, not a throw', () => {
+        const file = path.join(workDir, 'empty.csv');
+        fs.writeFileSync(file, '');
+        expect(readPerfCsv(file)).toEqual([]);
+    });
+});
+describe('numeric', () => {
+    test('treats N/A and blank as absent rather than zero', () => {
+        // #548: parseValue returning 0.0 for a missing column produced a phantom
+        // -185.836 MB "win" for SKYLARK250. Nothing in this file may repeat it.
+        expect(numeric('N/A')).toBeNull();
+        expect(numeric('')).toBeNull();
+        expect(numeric(undefined)).toBeNull();
+        expect(numeric('0')).toBe(0);
+        expect(numeric('12.5')).toBe(12.5);
+    });
+});
+describe('percentile', () => {
+    test('interpolates between samples and handles the empty case', () => {
+        expect(percentile([1, 2, 3, 4], 0.5)).toBeCloseTo(2.5);
+        expect(percentile([1, 2, 3, 4, 5], 0.1)).toBeCloseTo(1.4);
+        expect(percentile([], 0.5)).toBeNull();
+    });
+});
+describe('checkSwitch', () => {
+    test('a control pass with no retention against a blessed pass with it is valid', () => {
+        const check = checkSwitch([blessedRow({ file: 'a.ifc' }), blessedRow({ file: 'b.ifc' })], [row({ file: 'a.ifc' }), row({ file: 'b.ifc' })]);
+        expect(check.valid).toBe(true);
+        expect(check.blessedMeasured).toBe(2);
+        expect(check.controlMeasured).toBe(0);
+    });
+    test('a control pass that measured retention is not an A/B at all', () => {
+        // The env switch never reached the children, so both passes ran the same
+        // configuration and every timing ratio below is noise against noise.
+        const check = checkSwitch([blessedRow({ file: 'a.ifc' })], [blessedRow({ file: 'a.ifc' })]);
+        expect(check.valid).toBe(false);
+        expect(check.controlMeasured).toBe(1);
+    });
+    test('a blessed pass with no retention is equally not an A/B', () => {
+        const check = checkSwitch([row({ file: 'a.ifc' })], [row({ file: 'a.ifc' })]);
+        expect(check.valid).toBe(false);
+    });
+});
+describe('summariseColumn', () => {
+    const pairs = (blessed, control) => blessed.map((value, index) => ({
+        file: `m${index}.ifc`,
+        blessed: row({ file: `m${index}.ifc`, ...value }),
+        control: row({ file: `m${index}.ifc`, ...control[index] }),
+    }));
+    test('ratio, sign count and median delta', () => {
+        const stat = summariseColumn(pairs([{ totalTimeMs: '110' }, { totalTimeMs: '90' }, { totalTimeMs: '100' }], [{ totalTimeMs: '100' }, { totalTimeMs: '100' }, { totalTimeMs: '100' }]), 'totalTimeMs', true);
+        expect(stat.n).toBe(3);
+        expect(stat.medianRatio).toBeCloseTo(1.0);
+        expect(stat.slower).toBe(1);
+        expect(stat.medianDelta).toBe(0);
+    });
+    test('rows under the quantisation floor are counted out, not counted in', () => {
+        // A 3 ms parse carries a +/-1 ms Date.now() tick — a 33% "ratio" that is
+        // pure rounding, and there are enough tiny models in the corpus to swamp
+        // the median with them.
+        const stat = summariseColumn(pairs([{ parseTimeMs: '3' }, { parseTimeMs: '4' }, { parseTimeMs: '200' }], [{ parseTimeMs: '1' }, { parseTimeMs: '2' }, { parseTimeMs: '100' }]), 'parseTimeMs', true);
+        expect(RATIO_FLOOR_MS).toBe(10);
+        expect(stat.floored).toBe(2);
+        expect(stat.n).toBe(1);
+        expect(stat.medianRatio).toBeCloseTo(2.0);
+    });
+    test('a zero on the control side is floored, not dropped uncounted', () => {
+        // 0 ms is BELOW the 10 ms floor, so it belongs in `floored`. Testing
+        // `off === 0` ahead of the floor dropped such a row out of both counts,
+        // leaving n + floored unable to account for every pair - which the
+        // module header promises they can. Reachable: box.ifc parses in 1 ms in
+        // the committed snapshots, one Date.now() tick from 0, and a
+        // zero-geometry model's geometryTimeMs is the same story.
+        const stat = summariseColumn(pairs([{ geometryTimeMs: '0' }, { geometryTimeMs: '200' }], [{ geometryTimeMs: '0' }, { geometryTimeMs: '100' }]), 'geometryTimeMs', true);
+        expect(stat.floored).toBe(1);
+        expect(stat.n).toBe(1);
+        expect(stat.floored + stat.n).toBe(2);
+    });
+    test('the floor is not applied to the memory columns', () => {
+        const stat = summariseColumn(pairs([{ heapUsedMb: '5.0' }], [{ heapUsedMb: '8.0' }]), 'heapUsedMb', false);
+        expect(stat.floored).toBe(0);
+        expect(stat.n).toBe(1);
+    });
+    test('an unmeasured cell on either side drops the pair, it does not read zero', () => {
+        const stat = summariseColumn(pairs([{ totalTimeMs: 'N/A' }, { totalTimeMs: '200' }], [{ totalTimeMs: '100' }, { totalTimeMs: 'N/A' }]), 'totalTimeMs', true);
+        expect(stat.n).toBe(0);
+        expect(stat.medianRatio).toBeNull();
+    });
+});
+describe('compareRuns', () => {
+    test('joins on file, and reports rows only one pass produced', () => {
+        const comparison = compareRuns([blessedRow({ file: 'a.ifc' }), blessedRow({ file: 'only-blessed.ifc' })], [row({ file: 'a.ifc' }), row({ file: 'only-control.ifc' })]);
+        expect(comparison.pairs.map((pair) => pair.file)).toEqual(['a.ifc']);
+        expect(comparison.blessedOnly).toEqual(['only-blessed.ifc']);
+        expect(comparison.controlOnly).toEqual(['only-control.ifc']);
+    });
+    test('a model that failed in either pass is not timed against one that did not', () => {
+        const comparison = compareRuns([blessedRow({ file: 'a.ifc', status: 'FAIL' })], [row({ file: 'a.ifc' })]);
+        expect(comparison.pairs).toHaveLength(0);
+    });
+    test('summarises the three timing columns and the memory columns', () => {
+        const comparison = compareRuns([blessedRow({ file: 'a.ifc' })], [row({ file: 'a.ifc' })]);
+        expect(comparison.timing.map((stat) => stat.column))
+            .toEqual(['parseTimeMs', 'geometryTimeMs', 'totalTimeMs']);
+        expect(comparison.memory.map((stat) => stat.column))
+            .toEqual(['heapUsedMb', 'rssMb', 'peakRssMb']);
+    });
+});
+describe('renderMarkdown', () => {
+    test('a valid A/B says so, and reports the sign rule in both directions', () => {
+        const text = renderMarkdown(compareRuns([blessedRow({ file: 'a.ifc' })], [row({ file: 'a.ifc' })]), 'bldrs-ai/test-models');
+        expect(text).toContain('**Switch check: OK.**');
+        expect(text).toContain('gc on SLOWER');
+        expect(text).toContain('gc on FASTER');
+    });
+    test('an invalid A/B is labelled INVALID rather than presented as a result', () => {
+        const text = renderMarkdown(compareRuns([blessedRow({ file: 'a.ifc' })], [blessedRow({ file: 'a.ifc' })]), 'bldrs-ai/test-models');
+        expect(text).toContain('INVALID');
+        expect(text).toContain('answers nothing about the settle');
+    });
+});
+describe('renderCsv', () => {
+    test('carries both passes, the ratio, and the blessed retention columns', () => {
+        const text = renderCsv(compareRuns([blessedRow({ file: 'a.ifc', totalTimeMs: '110' })], [row({ file: 'a.ifc', totalTimeMs: '100' })]));
+        const [header, dataRow] = text.trim().split('\n');
+        expect(header).toContain('totalTimeMs_gcOn,totalTimeMs_gcOff,totalTimeMs_ratio');
+        expect(header).toContain('retainedRssMb_gcOn');
+        expect(dataRow).toContain('110,100,1.1000');
+        expect(dataRow).toContain('380.00');
+    });
+    test('an unmeasured input yields N/A, never a fabricated ratio', () => {
+        const text = renderCsv(compareRuns([blessedRow({ file: 'a.ifc', totalTimeMs: 'N/A' })], [row({ file: 'a.ifc', totalTimeMs: '100' })]));
+        const dataRow = text.trim().split('\n')[1];
+        expect(dataRow).toContain('N/A,100,N/A');
+    });
+});

package/compiled/src/version/version.js

@@ -5,5 +5,5 @@
 // only the first segment (major) is meaningful and is the one CI carries forward.
 // Must stay in `vN.N.N` shape: the CI stamp regex, scripts/updateVersion.mjs, and
 // statistics.ts all match `v\d+\.\d+\.\d+`.
-const versionString = 'Conway v1.556.1524';
+const versionString = 'Conway v1.558.1533';
 export { versionString };