Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

BUILD-PERF-M4 (first pass): exact SectionChain, B-spline and text-profile speedups

Claudec85f61bbec71
diff --git a/Aetheris.Kernel.Core/Geometry/Surfaces/BSplineSurfaceWithKnots.cs b/Aetheris.Kernel.Core/Geometry/Surfaces/BSplineSurfaceWithKnots.cs
index 2f52d705..b59ef320 100644
--- a/Aetheris.Kernel.Core/Geometry/Surfaces/BSplineSurfaceWithKnots.cs
+++ b/Aetheris.Kernel.Core/Geometry/Surfaces/BSplineSurfaceWithKnots.cs
@@ -167,7 +167,7 @@ public sealed record BSplineSurfaceWithKnots
// BUILD-PERF-M2: evaluation runs on flat arrays of the same data (no interface dispatch, no
// heap scratch). The arithmetic and its order are unchanged, so results are bit-identical.
- var arrays = EvaluationArrays.GetValue(this, static surface => new Arrays(surface));
+ var arrays = ReferenceEquals(lastSurface, this) ? lastArrays! : Remember(this);
if (arrays.WeightedNet is not null && arrays.WeightNet is not null)
{
var numerator = EvaluateNet(arrays.WeightedNet, arrays, uClamped, vClamped);
@@ -180,6 +180,17 @@ public sealed record BSplineSurfaceWithKnots
// Kept beside the record, not in it: record equality and `with` copies stay as they were.
private static readonly System.Runtime.CompilerServices.ConditionalWeakTable<BSplineSurfaceWithKnots, Arrays> EvaluationArrays = new();
+ // Evaluations come in long runs on one surface; skip the table lookup for those (BUILD-PERF-M4).
+ [ThreadStatic] private static BSplineSurfaceWithKnots? lastSurface;
+ [ThreadStatic] private static Arrays? lastArrays;
+
+ private static Arrays Remember(BSplineSurfaceWithKnots surface)
+ {
+ var arrays = EvaluationArrays.GetValue(surface, static item => new Arrays(item));
+ lastArrays = arrays;
+ lastSurface = surface;
+ return arrays;
+ }
private sealed class Arrays
{
@@ -195,8 +206,14 @@ public sealed record BSplineSurfaceWithKnots
DomainStartV = surface.DomainStartV;
DomainEndU = surface.DomainEndU;
DomainEndV = surface.DomainEndV;
+ var length = Net.Length > 0 ? Net[0].Length : -1;
+ RowLength = new[] { Net, WeightedNet, WeightNet }.All(net => net is null || (net.Length == Net.Length && net.All(row => row.Length == length)))
+ ? length : -1;
}
+ /// <summary>The common row length of a rectangular net (every net shares it), or -1.</summary>
+ public readonly int RowLength;
+
public readonly Point3D[][] Net;
public readonly Point3D[][]? WeightedNet;
public readonly Point3D[][]? WeightNet;
@@ -220,6 +237,19 @@ public sealed record BSplineSurfaceWithKnots
return EvaluateCurve(net[^1], a.DegreeV, a.KnotsV, a.DomainStartV, a.DomainEndV, vClamped);
var span = FindSpan(net.Length, a.DegreeU, a.KnotsU, uClamped);
Span<Point3D> rowPoints = a.DegreeU < 32 ? stackalloc Point3D[a.DegreeU + 1] : new Point3D[a.DegreeU + 1];
+ var v = ClampToDomain(vClamped, a.DomainStartV, a.DomainEndV);
+ if (a.RowLength > 0 && !(double.Abs(v - a.DomainEndV) <= 1e-12d))
+ {
+ // Every row of a rectangular net has the same V span: find it once, not once per row.
+ var vSpan = FindSpan(a.RowLength, a.DegreeV, a.KnotsV, v);
+ Span<Point3D> d = a.DegreeV < 32 ? stackalloc Point3D[a.DegreeV + 1] : new Point3D[a.DegreeV + 1];
+ for (var i = 0; i <= a.DegreeU; i++)
+ {
+ net[span - a.DegreeU + i].AsSpan(vSpan - a.DegreeV, a.DegreeV + 1).CopyTo(d);
+ rowPoints[i] = BlendActiveSpan(d, vSpan, a.DegreeV, a.KnotsV, v);
+ }
+ return BlendActiveSpan(rowPoints, span, a.DegreeU, a.KnotsU, uClamped);
+ }
for (var i = 0; i <= a.DegreeU; i++)
{
rowPoints[i] = EvaluateCurve(net[span - a.DegreeU + i], a.DegreeV, a.KnotsV, a.DomainStartV, a.DomainEndV, vClamped);
diff --git a/Aetheris.Kernel.Firmament/Materializer/PlanarTextProfiles.cs b/Aetheris.Kernel.Firmament/Materializer/PlanarTextProfiles.cs
index 41e528d8..ee2bf6a2 100644
--- a/Aetheris.Kernel.Firmament/Materializer/PlanarTextProfiles.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/PlanarTextProfiles.cs
@@ -27,6 +27,30 @@ public static class PlanarTextProfiles
public static PlanarTextProfileResult Build(string content, double height,
PlanarTextAlignment alignment = PlanarTextAlignment.Left,
ConstructionPlane? supportFrame = null, string featureId = "Text")
+ {
+ // BUILD-PERF-M4: outline conversion and glyph normalization are a pure function of these
+ // arguments (one font, immutable records) and cost ~1.3 s per bolt rebuild; recent results
+ // are reused. Only frame-free requests are memoized.
+ if (supportFrame is not null || content is null) return BuildUncached(content!, height, alignment, supportFrame, featureId);
+ var key = (content, BitConverter.DoubleToInt64Bits(height), alignment, featureId);
+ lock (RecentBuilds)
+ {
+ var hit = RecentBuilds.FindIndex(entry => entry.Key == key);
+ if (hit >= 0) return RecentBuilds[hit].Result;
+ }
+ var result = BuildUncached(content, height, alignment, null, featureId);
+ lock (RecentBuilds)
+ {
+ RecentBuilds.Add((key, result));
+ if (RecentBuilds.Count > 16) RecentBuilds.RemoveAt(0);
+ }
+ return result;
+ }
+
+ private static readonly List<((string, long, PlanarTextAlignment, string) Key, PlanarTextProfileResult Result)> RecentBuilds = [];
+
+ private static PlanarTextProfileResult BuildUncached(string content, double height,
+ PlanarTextAlignment alignment, ConstructionPlane? supportFrame, string featureId)
{
var diagnostics = new List<string>();
if (string.IsNullOrEmpty(content)) diagnostics.Add("text-content-empty");
diff --git a/Aetheris.Surfacing/SectionChainSelfIntersectionValidator.cs b/Aetheris.Surfacing/SectionChainSelfIntersectionValidator.cs
index 34dc2675..cd9ebfc8 100644
--- a/Aetheris.Surfacing/SectionChainSelfIntersectionValidator.cs
+++ b/Aetheris.Surfacing/SectionChainSelfIntersectionValidator.cs
@@ -24,11 +24,14 @@ internal static class SectionChainSelfIntersectionValidator
if (chain.StartTermination == SectionTermination.Cap) proxies.AddRange(Cap(chain.Sections[0], -1, "StartTermination"));
if (chain.EndTermination == SectionTermination.Cap) proxies.AddRange(Cap(chain.Sections[^1], chain.Sections.Count - 1, "EndTermination"));
var candidates = 0; var qualified = 0;
- for (var left = 0; left < proxies.Count; left++) for (var right = left + 1; right < proxies.Count; right++)
+ // BUILD-PERF-M4: the candidate pairs (non-neighbours whose tolerance-expanded bounds
+ // intersect) come from a sweep over X instead of testing every pair. They are then visited in
+ // the same (left, right) order as the all-pairs loop, so the verdict, the reported pair and
+ // the candidate/qualified counts are identical.
+ foreach (var (left, right) in CandidatePairs(proxies))
{
var a = proxies[left]; var b = proxies[right];
if (SameOrAuthorizedNeighbor(a, b)) continue;
- if (!a.Bounds.Expanded(Tolerance).Intersects(b.Bounds.Expanded(Tolerance))) continue;
candidates++;
if (!TrianglesIntersect(a, b, Tolerance)) { qualified++; continue; }
var detail = $"{a.Owner}:{a.Span} intersects {b.Owner}:{b.Span}; validation-only proxy={UDivisions}x{VDivisions}, tolerance={Tolerance:R}.";
@@ -49,6 +52,29 @@ internal static class SectionChainSelfIntersectionValidator
}
}
+ /// <summary>Every pair (left &lt; right) whose expanded bounds intersect, in (left, right) order.</summary>
+ private static List<(int Left, int Right)> CandidatePairs(List<Triangle> proxies)
+ {
+ var expanded = proxies.Select(triangle => triangle.Bounds.Expanded(Tolerance)).ToArray();
+ var order = Enumerable.Range(0, expanded.Length).ToArray();
+ var keys = expanded.Select(bounds => bounds.MinX).ToArray();
+ Array.Sort(keys, order);
+ var pairs = new List<(int, int)>();
+ for (var i = 0; i < order.Length; i++)
+ {
+ var first = expanded[order[i]];
+ // Bounds whose MinX exceeds this MaxX cannot overlap it in X, nor can any later one.
+ for (var j = i + 1; j < order.Length && keys[j] <= first.MaxX; j++)
+ {
+ if (!first.Intersects(expanded[order[j]])) continue;
+ var (left, right) = order[i] < order[j] ? (order[i], order[j]) : (order[j], order[i]);
+ pairs.Add((left, right));
+ }
+ }
+ pairs.Sort();
+ return pairs;
+ }
+
private static SectionChainSelfIntersectionValidationResult Result(bool passed, int candidates, int qualified, string detail) =>
new(passed, new("DeterministicBroadphasePlusTriangleProxy", passed, Tolerance,
"Closed single-loop X3 chains; profile crossings and adjacent foldover are checked separately; tessellation is validation-only and is not a global proof.",
diff --git a/Aetheris.Surfacing/SectionChains.cs b/Aetheris.Surfacing/SectionChains.cs
index 22537947..1b633884 100644
--- a/Aetheris.Surfacing/SectionChains.cs
+++ b/Aetheris.Surfacing/SectionChains.cs
@@ -142,7 +142,11 @@ public sealed record SectionChainMaterializationResult(
public SectionChainSelfIntersectionEvidence? SelfIntersection { get; init; }
public SectionChainContinuityEvidence? ContinuityEvidence { get; init; }
public SectionChainSmoothSelectionEvidence? SmoothSelection { get; init; }
- public string? PreviewSvg { get; init; }
+ /// <summary>Wireframe preview of the body. Rendered on first read (BUILD-PERF-M4: only the CLI
+ /// reads it, and rendering was ~7% of a guitar build) from a snapshot taken at materialization.</summary>
+ public string? PreviewSvg { get => previewSvg?.Value; init => previewSvg = new(() => value); }
+ private Lazy<string?>? previewSvg;
+ internal BrepBody? PreviewSource { init => previewSvg = value is null ? null : new(() => BrepWireframeSvgRenderer.Render(value).Svg); }
}
public sealed record SectionChainBoundaryContinuityEvidence(string SectionId, double MaximumPositionError,
@@ -361,7 +365,7 @@ public static class SectionChainMaterializer
return new(authoredChain, body, Structure(chain), evidence, diagnostics,
new(profileMs, correspondenceMs, transitionMs, stitchMs, validationMs))
{ GeometricJoins = geometricJoins, ProfileNormalization = normalization, Pcurves = pcurveEvidence, SelfIntersection = selfIntersection.Evidence, ContinuityEvidence = continuityEvidence,
- SmoothSelection = smoothSelection, PreviewSvg = body is null ? null : BrepWireframeSvgRenderer.Render(body).Svg };
+ SmoothSelection = smoothSelection, PreviewSource = body?.Clone() };
}
private static IReadOnlyList<SurfacingDiagnostic> Validate(SectionChain chain, IReadOnlyList<PreparedSection> sections)
diff --git a/Aetheris.Surfacing/SmoothSectionChains.cs b/Aetheris.Surfacing/SmoothSectionChains.cs
index c973c8ce..476e888f 100644
--- a/Aetheris.Surfacing/SmoothSectionChains.cs
+++ b/Aetheris.Surfacing/SmoothSectionChains.cs
@@ -173,14 +173,17 @@ internal static class SmoothSectionChainBuilder
SectionProfileCurve.PolynomialBSpline spline => spline.ControlPoints.Select(section.Frame.Transform),
_ => Array.Empty<Point3D>()
})).ToArray();
- var diagonal = new Vector3D(points.Max(p => p.X) - points.Min(p => p.X), points.Max(p => p.Y) - points.Min(p => p.Y), points.Max(p => p.Z) - points.Min(p => p.Z)).Length;
+ // The bounding box is loop-invariant (it was re-scanned six times per sample); same values.
+ double minX = points.Min(p => p.X), maxX = points.Max(p => p.X), minY = points.Min(p => p.Y),
+ maxY = points.Max(p => p.Y), minZ = points.Min(p => p.Z), maxZ = points.Max(p => p.Z);
+ var diagonal = new Vector3D(maxX - minX, maxY - minY, maxZ - minZ).Length;
var max = 0d;
foreach (var patch in patches) for (var u = 0; u <= 8; u++) for (var v = 0; v <= 8; v++)
{
var p = patch.Evaluate(u / 8d, v / 8d);
- var outside = Math.Max(0, points.Min(x => x.X) - p.X) + Math.Max(0, p.X - points.Max(x => x.X))
- + Math.Max(0, points.Min(x => x.Y) - p.Y) + Math.Max(0, p.Y - points.Max(x => x.Y))
- + Math.Max(0, points.Min(x => x.Z) - p.Z) + Math.Max(0, p.Z - points.Max(x => x.Z));
+ var outside = Math.Max(0, minX - p.X) + Math.Max(0, p.X - maxX)
+ + Math.Max(0, minY - p.Y) + Math.Max(0, p.Y - maxY)
+ + Math.Max(0, minZ - p.Z) + Math.Max(0, p.Z - maxZ);
max = Math.Max(max, outside / Math.Max(diagonal, 1e-9));
}
return max;
diff --git a/Aetheris.Web.Perf/build-perf-budgets.json b/Aetheris.Web.Perf/build-perf-budgets.json
index d110fa59..cb976e91 100644
--- a/Aetheris.Web.Perf/build-perf-budgets.json
+++ b/Aetheris.Web.Perf/build-perf-budgets.json
@@ -1,32 +1,32 @@
{
"schema": "aetheris/build-perf-budgets/m0",
"note": "Machine-independent fields always gate; *Milliseconds fields gate only with --check-time on the recorded machine.",
- "recordedOn": "vm \u00b7 2 CPU \u00b7 Unix 6.18.44.114",
- "recordedCommit": "59d785c + BUILD-PERF-M3 working tree",
+ "recordedOn": "vm \u00B7 2 CPU \u00B7 Unix 6.18.44.114",
+ "recordedCommit": "ac297514b2e3",
"projects": {
"bracket": {
"stepDataSha256": "c3323aa5717fbd198c6148ab082623f0f5920c42487c6dd5f398da4abd2d4170",
"meshSha256": "b0ec1fb0d1d40af0e6b13fe9fa1ddd38167ebde5f3f3fd946eeaac4ba97509f9",
"rebuildMatchesCold": true,
"cold": {
- "invokeMilliseconds": 739.5,
- "responseBytes": 29435,
- "allocatedBytes": 6275824
+ "invokeMilliseconds": 663.9,
+ "responseBytes": 29418,
+ "allocatedBytes": 4959600
},
"warm": {
- "invokeMilliseconds": 32.9,
- "responseBytes": 29413,
- "allocatedBytes": 3594672
+ "invokeMilliseconds": 4.4,
+ "responseBytes": 29141,
+ "allocatedBytes": 580904
},
"noChangeRebuild": {
- "invokeMilliseconds": 31.4,
- "responseBytes": 29338,
- "allocatedBytes": 3493480
+ "invokeMilliseconds": 3.5,
+ "responseBytes": 29067,
+ "allocatedBytes": 577656
},
"rootCommentEdit": {
- "invokeMilliseconds": 32.9,
- "responseBytes": 29369,
- "allocatedBytes": 3495448
+ "invokeMilliseconds": 4.3,
+ "responseBytes": 29103,
+ "allocatedBytes": 630776
}
},
"bolt": {
@@ -34,29 +34,29 @@
"meshSha256": "aa9262734e2c79801a33b60f318d646b7a81aebda0b2bea9c0e711b775f835a6",
"rebuildMatchesCold": true,
"cold": {
- "invokeMilliseconds": 5584.9,
- "responseBytes": 6952210,
- "allocatedBytes": 1905403056
+ "invokeMilliseconds": 5620.5,
+ "responseBytes": 6952197,
+ "allocatedBytes": 957124552
},
"warm": {
- "invokeMilliseconds": 3722.3,
- "responseBytes": 6952197,
- "allocatedBytes": 1870209832
+ "invokeMilliseconds": 2186.9,
+ "responseBytes": 6952173,
+ "allocatedBytes": 885366696
},
"noChangeRebuild": {
- "invokeMilliseconds": 3305.3,
- "responseBytes": 6952145,
- "allocatedBytes": 1869492264
+ "invokeMilliseconds": 1816.5,
+ "responseBytes": 6952123,
+ "allocatedBytes": 885153208
},
"leafCommentEdit": {
- "invokeMilliseconds": 2990.6,
- "responseBytes": 6952139,
- "allocatedBytes": 1869110760
+ "invokeMilliseconds": 1537.9,
+ "responseBytes": 6952121,
+ "allocatedBytes": 882119736
},
"rootCommentEdit": {
- "invokeMilliseconds": 3149.3,
- "responseBytes": 6952170,
- "allocatedBytes": 1869112208
+ "invokeMilliseconds": 1567.8,
+ "responseBytes": 6952157,
+ "allocatedBytes": 882214976
}
},
"atlas": {
@@ -64,33 +64,33 @@
"meshSha256": "49fe7e6ef3adce069b21582e99cb1f16876aa10d8da9b13b4b4e029a8b6c2c0b",
"rebuildMatchesCold": true,
"cold": {
- "invokeMilliseconds": 9105.4,
- "responseBytes": 1768201,
- "allocatedBytes": 3398890448,
+ "invokeMilliseconds": 4639.7,
+ "responseBytes": 1771521,
+ "allocatedBytes": 619200920,
"reusedDefinitions": 0
},
"warm": {
- "invokeMilliseconds": 3824.6,
- "responseBytes": 1768079,
- "allocatedBytes": 3377597592,
+ "invokeMilliseconds": 2013.7,
+ "responseBytes": 1771430,
+ "allocatedBytes": 609566080,
"reusedDefinitions": 0
},
"noChangeRebuild": {
- "invokeMilliseconds": 85.3,
- "responseBytes": 1724775,
- "allocatedBytes": 34339800,
+ "invokeMilliseconds": 117.6,
+ "responseBytes": 1728477,
+ "allocatedBytes": 25563536,
"reusedDefinitions": 24
},
"leafCommentEdit": {
- "invokeMilliseconds": 938.6,
- "responseBytes": 1749125,
- "allocatedBytes": 475902936,
- "reusedDefinitions": 2
+ "invokeMilliseconds": 89.3,
+ "responseBytes": 1728489,
+ "allocatedBytes": 25796136,
+ "reusedDefinitions": 24
},
"rootCommentEdit": {
- "invokeMilliseconds": 99.4,
- "responseBytes": 1724800,
- "allocatedBytes": 33935376,
+ "invokeMilliseconds": 89,
+ "responseBytes": 1728508,
+ "allocatedBytes": 25557928,
"reusedDefinitions": 24
}
},
@@ -99,39 +99,39 @@
"meshSha256": "700ae75e20a1c49685e3d6478b4ff7e714cb28bd36491caf786c63c591a6a2c6",
"rebuildMatchesCold": true,
"cold": {
- "invokeMilliseconds": 23600.6,
- "responseBytes": 9095710,
- "allocatedBytes": 9593820240,
+ "invokeMilliseconds": 10850,
+ "responseBytes": 9100217,
+ "allocatedBytes": 1906481344,
"reusedDefinitions": 0
},
"warm": {
- "invokeMilliseconds": 12679.1,
- "responseBytes": 9095289,
- "allocatedBytes": 9522156512,
+ "invokeMilliseconds": 5270.6,
+ "responseBytes": 9099983,
+ "allocatedBytes": 1848811200,
"reusedDefinitions": 0
},
"noChangeRebuild": {
- "invokeMilliseconds": 272.6,
- "responseBytes": 9006961,
- "allocatedBytes": 134558096,
+ "invokeMilliseconds": 344.4,
+ "responseBytes": 9014038,
+ "allocatedBytes": 92704448,
"reusedDefinitions": 56
},
"leafValueEdit": {
- "invokeMilliseconds": 3860.7,
- "responseBytes": 9070832,
- "allocatedBytes": 2333644672,
- "reusedDefinitions": 4
+ "invokeMilliseconds": 339.9,
+ "responseBytes": 9016040,
+ "allocatedBytes": 123028784,
+ "reusedDefinitions": 54
},
"leafCommentEdit": {
- "invokeMilliseconds": 5863.5,
- "responseBytes": 9008448,
- "allocatedBytes": 4266198336,
+ "invokeMilliseconds": 1143.5,
+ "responseBytes": 9015249,
+ "allocatedBytes": 574376840,
"reusedDefinitions": 55
},
"rootCommentEdit": {
- "invokeMilliseconds": 245.2,
- "responseBytes": 9006983,
- "allocatedBytes": 134139752,
+ "invokeMilliseconds": 130.8,
+ "responseBytes": 9014055,
+ "allocatedBytes": 91458568,
"reusedDefinitions": 56
}
},
@@ -140,29 +140,29 @@
"meshSha256": "ce00e129709c10a86151b4bea6f000947cf1c51e0bb4a226b67aea8f3d54a15a",
"rebuildMatchesCold": true,
"cold": {
- "invokeMilliseconds": 5516,
- "responseBytes": 2698128,
- "allocatedBytes": 661968768
+ "invokeMilliseconds": 2656.4,
+ "responseBytes": 2711150,
+ "allocatedBytes": 335707048
},
"warm": {
- "invokeMilliseconds": 2593.5,
- "responseBytes": 2697961,
- "allocatedBytes": 643069968
+ "invokeMilliseconds": 1394.6,
+ "responseBytes": 2711082,
+ "allocatedBytes": 324714384
},
"noChangeRebuild": {
- "invokeMilliseconds": 593.8,
- "responseBytes": 2626917,
- "allocatedBytes": 177762208
+ "invokeMilliseconds": 162.3,
+ "responseBytes": 2640572,
+ "allocatedBytes": 38404312
},
"leafCommentEdit": {
- "invokeMilliseconds": 1691.6,
- "responseBytes": 2674512,
- "allocatedBytes": 587303904
+ "invokeMilliseconds": 140.6,
+ "responseBytes": 2640573,
+ "allocatedBytes": 38407392
},
"rootCommentEdit": {
- "invokeMilliseconds": 490.6,
- "responseBytes": 2626928,
- "allocatedBytes": 180846088
+ "invokeMilliseconds": 163.8,
+ "responseBytes": 2640601,
+ "allocatedBytes": 38371888
}
}
}
diff --git a/docs/development/milestones/general/build-perf-ladder.md b/docs/development/milestones/general/build-perf-ladder.md
index 786ba57f..ee1d1310 100644
--- a/docs/development/milestones/general/build-perf-ladder.md
+++ b/docs/development/milestones/general/build-perf-ladder.md
@@ -152,6 +152,13 @@ In order of measured share, re-profiled after M1–M3:
Exit: guitar warm native build target set from M0 data (working target ≤ 5 s from 13.9 s); full
`Aetheris.slnx` test lane green; STEP unchanged or justified.
+**First pass** ([BUILD-PERF-M4](../../../release/BUILD-PERF-M4.md)): meaningful progression, all
+bit-exact. SectionChain self-intersection validation via an X sweep (same verdict, pair and
+counts), MaximumOvershoot bounding box hoisted, lazy preview SVG, B-spline V-span reuse, text
+profile memo. Guitar `CarvedMaple` edit 5.7 → 1.14 s, warm 7.6 → 5.3 s (target ≤ 5 s: at the line),
+bolt edit 3.1 → 1.6 s. Remaining share is the 8193-sample bounded-pcurve qualification (policy
+decision) and the bolt's two mass-property enclosure checks.
+
### M5 — First paint
- Showcase projects ship a precomputed binary display mesh keyed by source hash; the editor shows
diff --git a/docs/release/BUILD-PERF-M4.md b/docs/release/BUILD-PERF-M4.md
new file mode 100644
index 00000000..5441f742
--- /dev/null
+++ b/docs/release/BUILD-PERF-M4.md
@@ -0,0 +1,57 @@
+# BUILD-PERF-M4 — Kernel hotspots (first pass)
+
+Ladder: [build-perf-ladder.md](../development/milestones/general/build-perf-ladder.md) ·
+previous: [BUILD-PERF-M2](BUILD-PERF-M2.md).
+
+**State: meaningful progression.** Every change is bit-exact: STEP and display-mesh hashes are
+identical for every showcase project. The guitar `CarvedMaple` edit, the slow edit left by M2, fell
+5.7 s → 1.14 s natively. The guitar warm build is 5.3 s (median of 3, runs 4.6–5.7 s) against the
+≤ 5 s working target. The rest of the edit time is the bounded-pcurve qualification sampling. Making
+it cheaper is a policy decision, not an optimization (see the end).
+
+## Changes
+
+1. **SectionChain self-intersection validation.** The validator tested every triangle pair of its
+ 24×6 proxy (O(n²)). Candidate pairs (non-neighbours whose tolerance-expanded bounds intersect) now
+ come from a sweep over X. They are visited in the same (left, right) order, so the verdict, the
+ reported pair and the candidate/qualified counts in the evidence are identical. CarvedMaple:
+ 2.66 s → ~0.08 s.
+2. **SectionChain materialization.**
+ - `SmoothSectionChainBuilder.MaximumOvershoot` re-scanned the chain's bounding box six times for
+ each of its 81 samples per patch; the box is now computed once.
+ - The wireframe preview SVG (read only by the CLI) is rendered on first read, from a body snapshot
+ taken at materialization.
+ - Guitar `sectionchain.materialize`: 5.0 s → 0.55 s.
+3. **B-spline surface evaluation.** A rectangular net finds its V knot span once per evaluation
+ instead of once per row. The last surface's flat arrays are kept per thread, skipping the
+ table lookup in long runs (99.8% hit rate on the guitar). Arithmetic and its order are unchanged.
+4. **Planar text profiles.** Outline conversion and glyph normalization for the maker mark are a pure
+ function of (content, height, alignment, feature id); the last 16 results are reused. Bolt edit
+ 3.0 s → 1.5 s.
+
+## Results (native, median of 3, 2-core container)
+
+| Project | Scenario | M2 | M4 |
+|---|---|---|---|
+| guitar | `CarvedMaple` comment edit | 5.70 s (M1) | **1.14 s** |
+| guitar | warm build | 7.64 s | **5.27 s** |
+| guitar | cold build | 16.4 s | **10.9 s** |
+| guitar | knob value edit | ~0.40 s | 0.34 s |
+| atlas | cold / warm | 7.3 / 2.7 s | **4.6 / 2.0 s** |
+| bolt | root comment edit | 3.06 s | **1.57 s** |
+| bolt | cold | 6.9 s | 5.6 s |
+
+New ratchet baseline written (`Aetheris.Web.Perf/build-perf-budgets.json`). Full lane 4581/4581.
+AOT browser numbers to be re-measured on the author's machine.
+
+## What remains, with evidence
+
+- **Bounded pcurve qualification** (`pcurve.bounded-build`, 856 of the 1 144 ms CarvedMaple edit;
+ 3.0 s of the guitar cold build). 80% of it is `MaximumResidual`: every recovered spline pcurve is
+ lifted and compared at **8193** samples, plus up to 4097 inverse samples while refining. One guitar
+ cold build performs about 10.5 million B-spline surface evaluations. The arithmetic is now as lean
+ as it can be without changing results. Fewer lift samples, or an adaptive (error-bounded) residual,
+ would change the qualification evidence each binding records, so it is a policy decision.
+- **Bolt**: two `BrepMassProperties.Evaluate` enclosure checks (thread composition and maker-mark
+ imprint, ~2.3 s together, tessellation-based) are now the bulk of every bolt rebuild.
+- **Datum-seat validation** on cold builds (guitar 1.2 s): tessellates every placed body once.