@bldrs-ai/conway 1.553.1520 → 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.553.1520";
+var versionString = "Conway v1.558.1533";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";
@@ -45,6 +45,10 @@ var BlendMode;
 })(BlendMode || (BlendMode = {}));
 
 // compiled/src/statistics/statistics.js
+var RETAINED_MB_PRECISION = 3;
+function formatRetained(value) {
+  return value !== void 0 ? `${value.toFixed(RETAINED_MB_PRECISION)} MB` : "N/A";
+}
 var Statistics = class {
   // Getters and setters
   /**
@@ -166,6 +170,63 @@ var Statistics = class {
   setWasmHeapPeak(value) {
     this.wasmHeapPeak = value;
   }
+  /**
+   * RSS still held after the model was torn down, over a settled pre-load
+   * baseline (conway#554).
+   *
+   * @return {number | undefined} - retained RSS in MB, or undefined where the
+   * settle could not run
+   */
+  getRetainedRss() {
+    return this.retainedRss;
+  }
+  /**
+   * Both samples behind this figure are settled (`gc(); await setImmediate();
+   * gc()`) and both sit outside the timed region, so recording it costs the
+   * timing columns nothing. Leave it undefined rather than passing an
+   * unsettled difference: that is GC-timing noise, and it would be read as a
+   * leak signal.
+   *
+   * @param value - retained RSS in MB, signed
+   */
+  setRetainedRss(value) {
+    this.retainedRss = value;
+  }
+  /**
+   * V8 live heap still held after teardown, over the settled pre-load
+   * baseline (conway#554).
+   *
+   * @return {number | undefined} - retained heapUsed in MB, or undefined
+   * where the settle could not run
+   */
+  getRetainedHeapUsed() {
+    return this.retainedHeapUsed;
+  }
+  /**
+   *
+   * @param value - retained heapUsed in MB, signed
+   */
+  setRetainedHeapUsed(value) {
+    this.retainedHeapUsed = value;
+  }
+  /**
+   * Off-heap bytes still held after teardown, over the settled pre-load
+   * baseline (conway#554). This is where a released source buffer or parse
+   * structure that is still pinned shows up; heapUsed cannot see them.
+   *
+   * @return {number | undefined} - retained external in MB, or undefined
+   * where the settle could not run
+   */
+  getRetainedExternal() {
+    return this.retainedExternal;
+  }
+  /**
+   *
+   * @param value - retained external in MB, signed
+   */
+  setRetainedExternal(value) {
+    this.retainedExternal = value;
+  }
   /**
    *
    * @return {string | undefined} - preprocessor version or undefined
@@ -297,9 +358,10 @@ var Statistics = class {
       versionStr = "Version not defined";
     }
     const products = this.productCount !== void 0 ? `Products: ${this.productCount}, ` : "";
+    const retained = `Retained RSS Delta: ${formatRetained(this.retainedRss)}, Retained Heap-Used Delta: ${formatRetained(this.retainedHeapUsed)}, Retained External Delta: ${formatRetained(this.retainedExternal)}, `;
     const breakdown = this.formatGeometryTypeCounts();
     const geometryTypes = breakdown !== void 0 ? `, Geometry Types: ${breakdown}` : "";
-    return `[${dateString}]: Load Status: ${this.loadStatus}, Project Name: ${this.projectName}, Version: ${versionStr}, Conway Version: ${conwayVersionNumber}-${wasmType}, Parse Time: ${this.parseTime} ms, Geometry Time: ${this.geometryTime} ms, Total Time: ${this.totalTime} ms, Geometry Memory: ${this.geometryMemory?.toFixed(3)} MB, WASM Heap High-Water: ${this.wasmHeapPeak?.toFixed(3)} MB, ` + products + `Memory Statistics: ${this.memoryStatistics}, Preprocessor Version: ${this.preprocessorVersion}, Originating System: ${this.originatingSystem}` + geometryTypes;
+    return `[${dateString}]: Load Status: ${this.loadStatus}, Project Name: ${this.projectName}, Version: ${versionStr}, Conway Version: ${conwayVersionNumber}-${wasmType}, Parse Time: ${this.parseTime} ms, Geometry Time: ${this.geometryTime} ms, Total Time: ${this.totalTime} ms, Geometry Memory: ${this.geometryMemory?.toFixed(3)} MB, WASM Heap High-Water: ${this.wasmHeapPeak?.toFixed(3)} MB, ` + retained + products + `Memory Statistics: ${this.memoryStatistics}, Preprocessor Version: ${this.preprocessorVersion}, Originating System: ${this.originatingSystem}` + geometryTypes;
   }
 };
 

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.553.1520";
+var versionString = "Conway v1.558.1533";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {
@@ -15719,6 +15719,10 @@ function toAlphaMode(wasmModule, blendMode) {
 }
 
 // compiled/src/statistics/statistics.js
+var RETAINED_MB_PRECISION = 3;
+function formatRetained(value) {
+  return value !== void 0 ? `${value.toFixed(RETAINED_MB_PRECISION)} MB` : "N/A";
+}
 var Statistics = class {
   // Getters and setters
   /**
@@ -15840,6 +15844,63 @@ var Statistics = class {
   setWasmHeapPeak(value) {
     this.wasmHeapPeak = value;
   }
+  /**
+   * RSS still held after the model was torn down, over a settled pre-load
+   * baseline (conway#554).
+   *
+   * @return {number | undefined} - retained RSS in MB, or undefined where the
+   * settle could not run
+   */
+  getRetainedRss() {
+    return this.retainedRss;
+  }
+  /**
+   * Both samples behind this figure are settled (`gc(); await setImmediate();
+   * gc()`) and both sit outside the timed region, so recording it costs the
+   * timing columns nothing. Leave it undefined rather than passing an
+   * unsettled difference: that is GC-timing noise, and it would be read as a
+   * leak signal.
+   *
+   * @param value - retained RSS in MB, signed
+   */
+  setRetainedRss(value) {
+    this.retainedRss = value;
+  }
+  /**
+   * V8 live heap still held after teardown, over the settled pre-load
+   * baseline (conway#554).
+   *
+   * @return {number | undefined} - retained heapUsed in MB, or undefined
+   * where the settle could not run
+   */
+  getRetainedHeapUsed() {
+    return this.retainedHeapUsed;
+  }
+  /**
+   *
+   * @param value - retained heapUsed in MB, signed
+   */
+  setRetainedHeapUsed(value) {
+    this.retainedHeapUsed = value;
+  }
+  /**
+   * Off-heap bytes still held after teardown, over the settled pre-load
+   * baseline (conway#554). This is where a released source buffer or parse
+   * structure that is still pinned shows up; heapUsed cannot see them.
+   *
+   * @return {number | undefined} - retained external in MB, or undefined
+   * where the settle could not run
+   */
+  getRetainedExternal() {
+    return this.retainedExternal;
+  }
+  /**
+   *
+   * @param value - retained external in MB, signed
+   */
+  setRetainedExternal(value) {
+    this.retainedExternal = value;
+  }
   /**
    *
    * @return {string | undefined} - preprocessor version or undefined
@@ -15971,9 +16032,10 @@ var Statistics = class {
       versionStr = "Version not defined";
     }
     const products = this.productCount !== void 0 ? `Products: ${this.productCount}, ` : "";
+    const retained = `Retained RSS Delta: ${formatRetained(this.retainedRss)}, Retained Heap-Used Delta: ${formatRetained(this.retainedHeapUsed)}, Retained External Delta: ${formatRetained(this.retainedExternal)}, `;
     const breakdown = this.formatGeometryTypeCounts();
     const geometryTypes = breakdown !== void 0 ? `, Geometry Types: ${breakdown}` : "";
-    return `[${dateString}]: Load Status: ${this.loadStatus}, Project Name: ${this.projectName}, Version: ${versionStr}, Conway Version: ${conwayVersionNumber}-${wasmType}, Parse Time: ${this.parseTime} ms, Geometry Time: ${this.geometryTime} ms, Total Time: ${this.totalTime} ms, Geometry Memory: ${this.geometryMemory?.toFixed(3)} MB, WASM Heap High-Water: ${this.wasmHeapPeak?.toFixed(3)} MB, ` + products + `Memory Statistics: ${this.memoryStatistics}, Preprocessor Version: ${this.preprocessorVersion}, Originating System: ${this.originatingSystem}` + geometryTypes;
+    return `[${dateString}]: Load Status: ${this.loadStatus}, Project Name: ${this.projectName}, Version: ${versionStr}, Conway Version: ${conwayVersionNumber}-${wasmType}, Parse Time: ${this.parseTime} ms, Geometry Time: ${this.geometryTime} ms, Total Time: ${this.totalTime} ms, Geometry Memory: ${this.geometryMemory?.toFixed(3)} MB, WASM Heap High-Water: ${this.wasmHeapPeak?.toFixed(3)} MB, ` + retained + products + `Memory Statistics: ${this.memoryStatistics}, Preprocessor Version: ${this.preprocessorVersion}, Originating System: ${this.originatingSystem}` + geometryTypes;
   }
 };
 

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

@@ -15943,7 +15943,7 @@ var ParsingBuffer = class {
 };
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.553.1520";
+var versionString = "Conway v1.558.1533";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {
@@ -16697,6 +16697,10 @@ function toAlphaMode(wasmModule, blendMode) {
 }
 
 // compiled/src/statistics/statistics.js
+var RETAINED_MB_PRECISION = 3;
+function formatRetained(value) {
+  return value !== void 0 ? `${value.toFixed(RETAINED_MB_PRECISION)} MB` : "N/A";
+}
 var Statistics = class {
   // Getters and setters
   /**
@@ -16818,6 +16822,63 @@ var Statistics = class {
   setWasmHeapPeak(value) {
     this.wasmHeapPeak = value;
   }
+  /**
+   * RSS still held after the model was torn down, over a settled pre-load
+   * baseline (conway#554).
+   *
+   * @return {number | undefined} - retained RSS in MB, or undefined where the
+   * settle could not run
+   */
+  getRetainedRss() {
+    return this.retainedRss;
+  }
+  /**
+   * Both samples behind this figure are settled (`gc(); await setImmediate();
+   * gc()`) and both sit outside the timed region, so recording it costs the
+   * timing columns nothing. Leave it undefined rather than passing an
+   * unsettled difference: that is GC-timing noise, and it would be read as a
+   * leak signal.
+   *
+   * @param value - retained RSS in MB, signed
+   */
+  setRetainedRss(value) {
+    this.retainedRss = value;
+  }
+  /**
+   * V8 live heap still held after teardown, over the settled pre-load
+   * baseline (conway#554).
+   *
+   * @return {number | undefined} - retained heapUsed in MB, or undefined
+   * where the settle could not run
+   */
+  getRetainedHeapUsed() {
+    return this.retainedHeapUsed;
+  }
+  /**
+   *
+   * @param value - retained heapUsed in MB, signed
+   */
+  setRetainedHeapUsed(value) {
+    this.retainedHeapUsed = value;
+  }
+  /**
+   * Off-heap bytes still held after teardown, over the settled pre-load
+   * baseline (conway#554). This is where a released source buffer or parse
+   * structure that is still pinned shows up; heapUsed cannot see them.
+   *
+   * @return {number | undefined} - retained external in MB, or undefined
+   * where the settle could not run
+   */
+  getRetainedExternal() {
+    return this.retainedExternal;
+  }
+  /**
+   *
+   * @param value - retained external in MB, signed
+   */
+  setRetainedExternal(value) {
+    this.retainedExternal = value;
+  }
   /**
    *
    * @return {string | undefined} - preprocessor version or undefined
@@ -16949,9 +17010,10 @@ var Statistics = class {
       versionStr = "Version not defined";
     }
     const products = this.productCount !== void 0 ? `Products: ${this.productCount}, ` : "";
+    const retained = `Retained RSS Delta: ${formatRetained(this.retainedRss)}, Retained Heap-Used Delta: ${formatRetained(this.retainedHeapUsed)}, Retained External Delta: ${formatRetained(this.retainedExternal)}, `;
     const breakdown = this.formatGeometryTypeCounts();
     const geometryTypes = breakdown !== void 0 ? `, Geometry Types: ${breakdown}` : "";
-    return `[${dateString}]: Load Status: ${this.loadStatus}, Project Name: ${this.projectName}, Version: ${versionStr}, Conway Version: ${conwayVersionNumber}-${wasmType}, Parse Time: ${this.parseTime} ms, Geometry Time: ${this.geometryTime} ms, Total Time: ${this.totalTime} ms, Geometry Memory: ${this.geometryMemory?.toFixed(3)} MB, WASM Heap High-Water: ${this.wasmHeapPeak?.toFixed(3)} MB, ` + products + `Memory Statistics: ${this.memoryStatistics}, Preprocessor Version: ${this.preprocessorVersion}, Originating System: ${this.originatingSystem}` + geometryTypes;
+    return `[${dateString}]: Load Status: ${this.loadStatus}, Project Name: ${this.projectName}, Version: ${versionStr}, Conway Version: ${conwayVersionNumber}-${wasmType}, Parse Time: ${this.parseTime} ms, Geometry Time: ${this.geometryTime} ms, Total Time: ${this.totalTime} ms, Geometry Memory: ${this.geometryMemory?.toFixed(3)} MB, WASM Heap High-Water: ${this.wasmHeapPeak?.toFixed(3)} MB, ` + retained + products + `Memory Statistics: ${this.memoryStatistics}, Preprocessor Version: ${this.preprocessorVersion}, Originating System: ${this.originatingSystem}` + geometryTypes;
   }
 };
 

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.553.1520";
+var versionString = "Conway v1.558.1533";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";
@@ -959,6 +959,10 @@ var BlendMode;
 })(BlendMode || (BlendMode = {}));
 
 // compiled/src/statistics/statistics.js
+var RETAINED_MB_PRECISION = 3;
+function formatRetained(value) {
+  return value !== void 0 ? `${value.toFixed(RETAINED_MB_PRECISION)} MB` : "N/A";
+}
 var Statistics = class {
   // Getters and setters
   /**
@@ -1080,6 +1084,63 @@ var Statistics = class {
   setWasmHeapPeak(value) {
     this.wasmHeapPeak = value;
   }
+  /**
+   * RSS still held after the model was torn down, over a settled pre-load
+   * baseline (conway#554).
+   *
+   * @return {number | undefined} - retained RSS in MB, or undefined where the
+   * settle could not run
+   */
+  getRetainedRss() {
+    return this.retainedRss;
+  }
+  /**
+   * Both samples behind this figure are settled (`gc(); await setImmediate();
+   * gc()`) and both sit outside the timed region, so recording it costs the
+   * timing columns nothing. Leave it undefined rather than passing an
+   * unsettled difference: that is GC-timing noise, and it would be read as a
+   * leak signal.
+   *
+   * @param value - retained RSS in MB, signed
+   */
+  setRetainedRss(value) {
+    this.retainedRss = value;
+  }
+  /**
+   * V8 live heap still held after teardown, over the settled pre-load
+   * baseline (conway#554).
+   *
+   * @return {number | undefined} - retained heapUsed in MB, or undefined
+   * where the settle could not run
+   */
+  getRetainedHeapUsed() {
+    return this.retainedHeapUsed;
+  }
+  /**
+   *
+   * @param value - retained heapUsed in MB, signed
+   */
+  setRetainedHeapUsed(value) {
+    this.retainedHeapUsed = value;
+  }
+  /**
+   * Off-heap bytes still held after teardown, over the settled pre-load
+   * baseline (conway#554). This is where a released source buffer or parse
+   * structure that is still pinned shows up; heapUsed cannot see them.
+   *
+   * @return {number | undefined} - retained external in MB, or undefined
+   * where the settle could not run
+   */
+  getRetainedExternal() {
+    return this.retainedExternal;
+  }
+  /**
+   *
+   * @param value - retained external in MB, signed
+   */
+  setRetainedExternal(value) {
+    this.retainedExternal = value;
+  }
   /**
    *
    * @return {string | undefined} - preprocessor version or undefined
@@ -1211,9 +1272,10 @@ var Statistics = class {
       versionStr = "Version not defined";
     }
     const products = this.productCount !== void 0 ? `Products: ${this.productCount}, ` : "";
+    const retained = `Retained RSS Delta: ${formatRetained(this.retainedRss)}, Retained Heap-Used Delta: ${formatRetained(this.retainedHeapUsed)}, Retained External Delta: ${formatRetained(this.retainedExternal)}, `;
     const breakdown = this.formatGeometryTypeCounts();
     const geometryTypes = breakdown !== void 0 ? `, Geometry Types: ${breakdown}` : "";
-    return `[${dateString}]: Load Status: ${this.loadStatus}, Project Name: ${this.projectName}, Version: ${versionStr}, Conway Version: ${conwayVersionNumber}-${wasmType}, Parse Time: ${this.parseTime} ms, Geometry Time: ${this.geometryTime} ms, Total Time: ${this.totalTime} ms, Geometry Memory: ${this.geometryMemory?.toFixed(3)} MB, WASM Heap High-Water: ${this.wasmHeapPeak?.toFixed(3)} MB, ` + products + `Memory Statistics: ${this.memoryStatistics}, Preprocessor Version: ${this.preprocessorVersion}, Originating System: ${this.originatingSystem}` + geometryTypes;
+    return `[${dateString}]: Load Status: ${this.loadStatus}, Project Name: ${this.projectName}, Version: ${versionStr}, Conway Version: ${conwayVersionNumber}-${wasmType}, Parse Time: ${this.parseTime} ms, Geometry Time: ${this.geometryTime} ms, Total Time: ${this.totalTime} ms, Geometry Memory: ${this.geometryMemory?.toFixed(3)} MB, WASM Heap High-Water: ${this.wasmHeapPeak?.toFixed(3)} MB, ` + retained + products + `Memory Statistics: ${this.memoryStatistics}, Preprocessor Version: ${this.preprocessorVersion}, Originating System: ${this.originatingSystem}` + geometryTypes;
   }
 };
 

package/compiled/src/AP214E3_2010/ap214_regression_main.js

@@ -10,6 +10,7 @@ import path from "path";
 import crypto from "crypto";
 import { ConwayGeometry } from "../../dependencies/conway-geom/index.js";
 import { wasmHeapByteLength } from "../core/wasm_heap.js";
+import { retainedMemoryMb, settleAndSampleMemoryForPerf, } from "../core/retained_memory.js";
 import Logger from "../logging/logger.js";
 import Environment from "../utilities/environment.js";
 import { ExtractResult } from "../core/shared_constants.js";
@@ -44,6 +45,21 @@ const KB_PER_MB = 1024;
 const PERF_MB_PRECISION = 2;
 /** Placeholder for a column this row has no measurement for. */
 const UNMEASURED = "N/A";
+/**
+ * Capture the end-of-load memory figures for a perf row.
+ *
+ * @param geometryMemoryBytes Geometry payload conway allocated, in bytes.
+ * @param wasmHeapBytes Wasm linear-memory high-water in bytes.
+ * @return {PerfMemory} The captured figures, with retention still unset.
+ */
+function capturePerfMemory(geometryMemoryBytes, wasmHeapBytes) {
+    return {
+        instant: process.memoryUsage(),
+        peakRssKb: process.resourceUsage().maxRSS,
+        geometryMemoryBytes,
+        wasmHeapBytes,
+    };
+}
 /**
  * Write a single-row per-file perf CSV at the given path, matching the
  * column layout of the IFC regression child so the batch aggregator can
@@ -58,42 +74,55 @@ const UNMEASURED = "N/A";
  * (`src/ifc/ifc_regression_main.ts`), which is the writer these columns have
  * to stay identical to.
  *
+ * `retainedRssMb` / `retainedHeapUsedMb` / `retainedExternalMb` are the other
+ * half (conway#554): settled-after-teardown minus settled-before-load, so a
+ * signed measure of what one cycle left behind, and `N/A` where `global.gc`
+ * was not exposed to settle with. No `retainedWasmHeapMb` — the wasm heap is
+ * grow-only, so over one cycle it could only restate `peakWasmHeapMb`.
+ *
  * @param perfPath Path to write the CSV to. Empty string disables.
  * @param stepFile Source STEP file path (basename used as the row key).
  * @param status OK or FAIL.
  * @param parseTimeMs Parse stage duration in ms.
  * @param geometryTimeMs Geometry extraction duration in ms.
  * @param totalTimeMs Sum of parse + geometry in ms.
- * @param geometryMemoryBytes Geometry payload conway allocated, in bytes, or
- * undefined where no geometry was extracted (written as N/A).
- * @param wasmHeapBytes Wasm linear-memory high-water in bytes, or undefined
- * where the module was never brought up (written as N/A).
+ * @param memory The row's memory figures, captured at the points in the load
+ * each is defined at. Defaults to capturing the end-of-load instants here,
+ * which is what the FAIL paths want — they have nothing else to report.
  */
-async function writePerfCsvIfRequested(perfPath, stepFile, status, parseTimeMs, geometryTimeMs, totalTimeMs, geometryMemoryBytes, wasmHeapBytes) {
+async function writePerfCsvIfRequested(perfPath, stepFile, status, parseTimeMs, geometryTimeMs, totalTimeMs, memory = capturePerfMemory()) {
     if (perfPath.length === 0) {
         return;
     }
-    const mem = process.memoryUsage();
+    const mem = memory.instant;
     const rssMb = (mem.rss / BYTES_PER_MB).toFixed(PERF_MB_PRECISION);
     const heapUsedMb = (mem.heapUsed / BYTES_PER_MB).toFixed(PERF_MB_PRECISION);
     const heapTotalMb = (mem.heapTotal / BYTES_PER_MB).toFixed(PERF_MB_PRECISION);
     const externalMb = (mem.external / BYTES_PER_MB).toFixed(PERF_MB_PRECISION);
     const arrayBuffersMb = (mem.arrayBuffers / BYTES_PER_MB).toFixed(PERF_MB_PRECISION);
     // maxRSS is reported in kilobytes, unlike memoryUsage() which is in bytes.
-    const peakRssMb = (process.resourceUsage().maxRSS / KB_PER_MB).toFixed(PERF_MB_PRECISION);
-    const geometryMemoryMb = geometryMemoryBytes !== void 0 ?
-        (geometryMemoryBytes / BYTES_PER_MB).toFixed(PERF_MB_PRECISION) :
+    const peakRssMb = (memory.peakRssKb / KB_PER_MB).toFixed(PERF_MB_PRECISION);
+    const geometryMemoryMb = memory.geometryMemoryBytes !== void 0 ?
+        (memory.geometryMemoryBytes / BYTES_PER_MB).toFixed(PERF_MB_PRECISION) :
         UNMEASURED;
-    const peakWasmHeapMb = wasmHeapBytes !== void 0 ?
-        (wasmHeapBytes / BYTES_PER_MB).toFixed(PERF_MB_PRECISION) :
+    const peakWasmHeapMb = memory.wasmHeapBytes !== void 0 ?
+        (memory.wasmHeapBytes / BYTES_PER_MB).toFixed(PERF_MB_PRECISION) :
         UNMEASURED;
+    const retained = memory.retained;
+    const retainedRssMb = retained !== void 0 ?
+        retained.rssMb.toFixed(PERF_MB_PRECISION) : UNMEASURED;
+    const retainedHeapUsedMb = retained !== void 0 ?
+        retained.heapUsedMb.toFixed(PERF_MB_PRECISION) : UNMEASURED;
+    const retainedExternalMb = retained !== void 0 ?
+        retained.externalMb.toFixed(PERF_MB_PRECISION) : UNMEASURED;
     const fileName = csvSafeString(path.basename(stepFile));
     const header = "file,status,parseTimeMs,geometryTimeMs,totalTimeMs,geometryMemoryMb," +
         "peakWasmHeapMb,rssMb,peakRssMb,heapUsedMb,heapTotalMb,externalMb," +
-        "arrayBuffersMb\n";
+        "arrayBuffersMb,retainedRssMb,retainedHeapUsedMb,retainedExternalMb\n";
     const row = `${fileName},${status},${parseTimeMs},${geometryTimeMs},${totalTimeMs},` +
         `${geometryMemoryMb},${peakWasmHeapMb},${rssMb},${peakRssMb},` +
-        `${heapUsedMb},${heapTotalMb},${externalMb},${arrayBuffersMb}\n`;
+        `${heapUsedMb},${heapTotalMb},${externalMb},${arrayBuffersMb},` +
+        `${retainedRssMb},${retainedHeapUsedMb},${retainedExternalMb}\n`;
     try {
         await fsPromises.writeFile(perfPath, header + row);
     }
@@ -172,6 +201,18 @@ function doWork() {
         const strict = argv["strict"] ?? false;
         const digest = argv["digest"] ?? false;
         const perfPath = argv["perf"] ?? "";
+        // Settled pre-load baseline for the retention columns (conway#554).
+        // Here rather than at process start: `main()` has already brought
+        // conway-geom up, so the wasm module's fixed cost sits below the
+        // baseline instead of being charged to every model as the same
+        // constant. Before `readFileSync` because the source buffer is part of
+        // what a load must give back, and outside the timed region because
+        // `parseStartMs` has not been taken yet.
+        //
+        // `...ForPerf` skips the settle when no perf row is coming, for the
+        // reason recorded on that function: the batch passes `--expose-gc` to
+        // every child, not just the ones given `--perf`.
+        const memoryBaseline = await settleAndSampleMemoryForPerf(perfPath);
         try {
             stepBuffer = fs.readFileSync(stepFile);
         }
@@ -249,7 +290,19 @@ function doWork() {
         const wasmModule = conwayGeom.wasmModule;
         const wasmHeapBytes = wasmModule !== void 0 ?
             wasmHeapByteLength(wasmModule) : void 0;
-        await writePerfCsvIfRequested(perfPath, stepFile, perfStatus, parseTimeMs, geometryTimeMs, totalTimeMs, geometryMemoryBytes, wasmHeapBytes);
+        // Instants captured here, where they have always been captured, so
+        // the teardown below cannot change what rssMb/heapUsedMb/externalMb
+        // mean.
+        const memory = capturePerfMemory(geometryMemoryBytes, wasmHeapBytes);
+        // Teardown, then the settled retained sample. This path had no
+        // explicit release before conway#554 — see the matching comment in
+        // the IFC child, which records that finding in full.
+        // Not gated on `perfPath` — the digest runs after it, and one path to
+        // the blessed output beats saving the work. The settle below IS
+        // gated; see `memoryBaseline` above.
+        model.invalidate(true);
+        memory.retained = retainedMemoryMb(memoryBaseline, await settleAndSampleMemoryForPerf(perfPath));
+        await writePerfCsvIfRequested(perfPath, stepFile, perfStatus, parseTimeMs, geometryTimeMs, totalTimeMs, memory);
         // 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(stepFile));

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

@@ -0,0 +1,142 @@
+/**
+ * Settled process-memory sampling for the retention columns (conway#554).
+ *
+ * The perf bench's other memory columns answer "does this survive?" — peaks,
+ * and end-of-load instants. This one answers "do we leak?": what is still
+ * held after a load has been torn down. Share loads models repeatedly into
+ * one long-lived tab, so retention compounds in a way a single load never
+ * shows, and it is invisible to every peak. See
+ * design/new/perf-measurement.md §"Peak and delta answer different questions".
+ *
+ * A retention figure is a DIFFERENCE between two samples, so both of them
+ * have to be settled or the difference is GC timing rather than retention.
+ * SKYLARK250 reads 2547 MB un-GC'd against 981 MB as post-GC live heap — a
+ * 2.6x spread from sampling alone, which is larger than any leak this is
+ * meant to find. Hence `settleAndSampleMemory` is the only sampler here:
+ * there is deliberately no un-settled variant to reach for.
+ *
+ * When `global.gc` is not exposed the settle cannot run, and every caller
+ * must emit N/A rather than a number. That is why the sampler returns
+ * `undefined` instead of falling back to an unsettled `process.memoryUsage()`
+ * — an unsettled retention figure is noise wearing a number, and would be
+ * read as a leak signal. Same family as the `parseValue` -> `0.0`
+ * fabrication conway#548 fixed.
+ */
+/**
+ * A settled sample of the three process-memory quantities a retention delta
+ * is taken over. Bytes, straight out of `process.memoryUsage()`.
+ *
+ * `heapUsed` and `external` are disjoint (`external` holds the ArrayBuffer
+ * backing stores and other off-heap bytes V8 knows about) and neither sees
+ * the wasm heap, which is why RSS is here as well rather than being derived.
+ */
+export interface SettledMemorySample {
+    /** Resident set size in bytes. */
+    rssBytes: number;
+    /** V8 live heap in bytes, post-collection. */
+    heapUsedBytes: number;
+    /** Off-heap bytes V8 accounts for, post-collection. */
+    externalBytes: number;
+}
+/** A retention delta, in MB, over one load/teardown cycle. */
+export interface RetainedMemoryMb {
+    /** RSS held after teardown, over the pre-load baseline. */
+    rssMb: number;
+    /** V8 live heap held after teardown, over the pre-load baseline. */
+    heapUsedMb: number;
+    /** Off-heap bytes held after teardown, over the pre-load baseline. */
+    externalMb: number;
+}
+/**
+ * The forced-collection hook, when the host exposes one.
+ *
+ * Node only defines `global.gc` under `--expose-gc`; browsers only under
+ * `--js-flags="--expose-gc"`. Absence is the normal case, not an error.
+ *
+ * @return {(() => void) | undefined} The collector, or undefined where the
+ * host does not expose one.
+ */
+export declare function exposedGc(): (() => void) | undefined;
+/**
+ * Whether a settled sample can be taken at all in this process, without
+ * paying for a collection to find out.
+ *
+ * No production caller: every call site instead calls
+ * `settleAndSampleMemory` and treats `undefined` as N/A, which is one branch
+ * rather than two and cannot drift out of agreement with the sampler. This
+ * stays exported as the cheap probe for tests that need to assert the
+ * no-collector path without a collector present.
+ *
+ * @return {boolean} True where both the collector and node's memory
+ * accounting are available.
+ */
+export declare function canSettleMemory(): boolean;
+/**
+ * Settle the heap, then sample it.
+ *
+ * The settle is `gc(); await setImmediate(); gc()`, and each part earns its
+ * place. Two collections catch objects whose freeing makes more garbage
+ * unreachable. The interleaved turn is what lets queued frees actually run —
+ * notably ArrayBuffer backing-store release, without which `external` reads
+ * high, which matters here because `external` is one of the three sampled
+ * quantities. One GC plus an idle turn is not enough on its own (V8's GC has
+ * concurrent phases, so a turn does not imply a finished collection), and two
+ * back-to-back GCs with no turn between is not enough either.
+ *
+ * This perturbs timing, so every call site must sit OUTSIDE the region that
+ * 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 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
+ * N/A. Never returns an unsettled sample.
+ */
+export declare function settleAndSampleMemory(): Promise<SettledMemorySample | undefined>;
+/**
+ * The settled sample for a perf row, taken only when a perf row is coming.
+ *
+ * The gate is not an optimisation detail, it is the difference between
+ * charging a cost to a run that uses it and charging it to one that does not.
+ * `ifc_regression_batch_main.ts` launches EVERY regression child with
+ * `--expose-gc`, not only the ones given `--perf`, so a child that settles
+ * unconditionally makes a digest-only run pay two forced full collections per
+ * model for a figure `writePerfCsvIfRequested` immediately discards. Measured
+ * on node 22: one settle costs ~0.8 s on a 500 MB live heap and ~1.6 s on a
+ * 1 GB one.
+ *
+ * It lives here rather than inlined at each call site so both regression
+ * children share one definition of "is retention wanted", and so it can be
+ * pinned by a test — an unnecessary settle is invisible in the output, so
+ * nothing downstream would catch a regression to an unconditional one.
+ *
+ * @param perfPath The child's `--perf` destination. Empty means no perf row
+ * is being written, so no sample is taken and no collection is forced.
+ * @return {Promise<SettledMemorySample | undefined>} The settled sample, or
+ * undefined when no perf row is wanted or no collector is exposed.
+ */
+export declare function settleAndSampleMemoryForPerf(perfPath: string): Promise<SettledMemorySample | undefined>;
+/**
+ * Difference two settled samples into the retention columns.
+ *
+ * Deltas are signed and may legitimately come out negative: a cycle can end
+ * with the allocator holding less than the baseline did, and rounding that up
+ * to zero would hide exactly the direction a fix is trying to move.
+ *
+ * @param baseline The settled sample taken before the load.
+ * @param retained The settled sample taken after teardown.
+ * @return {RetainedMemoryMb | undefined} The retention delta in MB, or
+ * undefined when either sample is missing (the settle could not run).
+ */
+export declare function retainedMemoryMb(baseline: SettledMemorySample | undefined, retained: SettledMemorySample | undefined): RetainedMemoryMb | undefined;
+//# sourceMappingURL=retained_memory.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}