fix(engine): enforce whole-job safety invariants

Task 5 of the whole-job engine API: add a geometry safety gate that
validates every candidate trial before the runner commits accounting.

- NestJobPlacementValidator: closed-contour validity, rotation-policy
  compliance, work-area containment per quadrant, hole-aware material
  overlap, and required part spacing. Overlap is interior-only, so
  zero-clearance edge/corner contact remains a valid placement.
- NestJobValidator: route candidate validation through the geometry
  gate; reject unusable/unclosed/degenerate contours up front.
- NestJobRunner: wrap candidate evaluation in a progress bridge that
  tags legacy engine detail with the current candidate context.
- LegacyPlateNesterAdapter: forward IProgress to the legacy engine so
  its progress surfaces under the active candidate.
- Tests: geometry (quadrants, rotations, touching, containment, holes,
  empty stock, real Default/Strip smoke), validation, and cancellation
  suites; repaired test fakes that emitted out-of-bounds or overlapping
  placements the gate now correctly rejects.

Engine.Tests: 70 passed, 0 failed, 0 skipped in Debug and Release.
Windows-only OpenNest.Tests not run on Linux.
This commit is contained in:
aj
2026-09-18 05:56:37 -04:00
parent 75c8adc76c
commit 2b0b962c8f
12 changed files with 760 additions and 29 deletions
@@ -16,7 +16,7 @@ public class FiniteStockJobTests
}
internal static PlateCandidate One(PlatePlacementRequest request) => new(new[]
{ new NestJobPlacement(request.Parts[0].Id, 99, 1, 2, 0) });
{ new NestJobPlacement(request.Parts[0].Id, 99, 0, 0, 0) });
[Theory]
[InlineData(3, 3, 0, NestJobStatus.Complete, NestJobStopReason.Completed)]
@@ -108,7 +108,7 @@ public class FiniteStockJobTests
public void MixedStockCanBeEvaluated()
{
var job = Job();
var mixed = new NestJob(job.Parts, job.Plates.Concat(new[] { new NestPlateStock("other", new Size(10, 20), 2) }));
var mixed = new NestJob(job.Parts, job.Plates.Concat(new[] { new NestPlateStock("other", new Size(20, 10), 2) }));
var result = new NestJobRunner(_ => new Nester(One)).Solve(mixed);
Assert.Equal(NestJobStatus.Complete, result.Status);
}
@@ -58,7 +58,11 @@ public class JobAdapterTests
{
Assert.NotSame(items[0].Drawing, items[1].Drawing);
foreach (var item in items) item.Drawing.Name = "identical";
return items.Select(i => new Part(i.Drawing)).ToList();
return new List<Part>
{
new Part(items[0].Drawing, new Vector(0, 0)),
new Part(items[1].Drawing, new Vector(10, 0))
};
}));
var result = new NestJobRunner(_ => adapter).Solve(job);
Assert.Equal(new[] { "a", "b" }, result.Plates[0].Placements.Select(p => p.PartId));
@@ -0,0 +1,114 @@
using OpenNest.CNC;
using OpenNest.Geometry;
namespace OpenNest.Engine.Tests.Jobs;
public class NestJobCancellationTests
{
[Fact]
public void PreTrialCancellationSkipsCandidateWorkAndPreservesInput()
{
using var cancellation = new CancellationTokenSource();
cancellation.Cancel();
var nester = new CancellableNester(_ => new PlateCandidate(Array.Empty<NestJobPlacement>()));
var part = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(4, 3)), 1);
var sourceGeometry = part.Geometry.Motions.ToArray();
var stock = new NestPlateStock("stock", new Size(20, 30), 1);
var job = new NestJob(new[] { part }, new[] { stock });
Assert.Throws<OperationCanceledException>(() => new NestJobRunner(_ => nester).Solve(job, token: cancellation.Token));
Assert.Equal(0, nester.Calls);
Assert.Equal(sourceGeometry, job.Parts[0].Geometry.Motions);
Assert.Equal(1, job.Parts[0].Quantity);
Assert.Equal(1, job.Plates[0].Quantity);
}
[Fact]
public void CancellationDuringCandidateThrowsWithoutCommitOrInputMutation()
{
using var cancellation = new CancellationTokenSource();
var reports = new List<NestJobProgress>();
var part = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(4, 3)), 1);
var sourceGeometry = part.Geometry.Motions.ToArray();
var stock = new NestPlateStock("stock", new Size(20, 30), 1);
var job = new NestJob(new[] { part }, new[] { stock });
var nester = new CancellableNester((_, token) =>
{
cancellation.Cancel();
token.ThrowIfCancellationRequested();
return new PlateCandidate(Array.Empty<NestJobPlacement>());
});
Assert.Throws<OperationCanceledException>(() => new NestJobRunner(_ => nester)
.Solve(job, new InlineProgress(reports.Add), cancellation.Token));
Assert.Equal(1, nester.Calls);
Assert.DoesNotContain(reports, report => report.Stage == NestJobStage.PlateCommitted);
Assert.Equal(sourceGeometry, job.Parts[0].Geometry.Motions);
Assert.Equal(1, job.Parts[0].Quantity);
Assert.Equal(1, job.Plates[0].Quantity);
}
[Fact]
public void LegacyProgressIsWrappedWithCurrentCandidateContext()
{
var reports = new List<NestJobProgress>();
var part = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(4, 3)), 1);
var job = new NestJob(new[] { part }, new[] { new NestPlateStock("stock", new Size(20, 30), 1) });
var runner = new NestJobRunner(_ => new LegacyPlateNesterAdapter(plate => new ReportingEngine(plate)));
var result = runner.Solve(job, new InlineProgress(reports.Add));
Assert.Equal(NestJobStopReason.NoPlacementFound, result.StopReason);
var legacy = Assert.Single(reports.Where(report => report.LegacyProgress != null));
Assert.Equal(NestJobStage.EvaluatingCandidate, legacy.Stage);
Assert.Equal("stock", legacy.StockId);
Assert.Equal(0, legacy.PlateIndex);
Assert.Equal(0, legacy.CommittedPlates);
Assert.Equal(0, legacy.CommittedParts);
Assert.Equal("legacy detail", legacy.LegacyProgress!.Description);
}
private sealed class InlineProgress(Action<NestJobProgress> report) : IProgress<NestJobProgress>
{
public void Report(NestJobProgress value) => report(value);
}
private sealed class CancellableNester : IPlateNester
{
private readonly Func<PlatePlacementRequest, CancellationToken, PlateCandidate> place;
public CancellableNester(Func<PlatePlacementRequest, PlateCandidate> place)
{
this.place = (request, _) => place(request);
}
public CancellableNester(Func<PlatePlacementRequest, CancellationToken, PlateCandidate> place)
{
this.place = place;
}
public int Calls { get; private set; }
public PlateCandidate Place(PlatePlacementRequest request, IProgress<NestJobProgress>? progress = null,
CancellationToken token = default)
{
Calls++;
return place(request, token);
}
}
private sealed class ReportingEngine(Plate plate) : NestEngineBase(plate)
{
public override string Name => "reporting";
public override string Description => "reports progress";
public override List<Part> Nest(List<NestItem> items, IProgress<NestProgress>? progress,
CancellationToken token)
{
progress?.Report(new NestProgress { Description = "legacy detail" });
return new List<Part>();
}
}
}
@@ -0,0 +1,159 @@
using OpenNest.Geometry;
namespace OpenNest.Engine.Tests.Jobs;
public class NestJobGeometryTests
{
[Fact]
public void CandidateOutsideUsableWorkAreaFailsWithoutMutatingInput()
{
var part = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(4, 3)), 1);
var sourceGeometry = part.Geometry.Motions.ToArray();
var stock = new NestPlateStock("stock", new Size(20, 30), 1,
edgeSpacing: new Spacing(2, 1, 3, 4));
var job = new NestJob(new[] { part }, new[] { stock });
var runner = new NestJobRunner(_ => new CandidateNester(new[] { new NestJobPlacement("part", 0, 26, 1, 0) }));
Assert.Throws<InvalidOperationException>(() => runner.Solve(job));
Assert.Equal(sourceGeometry, job.Parts[0].Geometry.Motions);
Assert.Equal(1, job.Parts[0].Quantity);
Assert.Equal(1, job.Plates[0].Quantity);
}
[Theory]
[InlineData(1, 0, 0)]
[InlineData(2, -11, 0)]
[InlineData(3, -11, -7)]
[InlineData(4, 0, -7)]
public void UnequalRectanglesFitAtEachQuadrantsUsableOrigin(int quadrant, double x, double y)
{
var part = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(2, 3)), 1);
var stock = new NestPlateStock("stock", new Size(7, 11), 1, quadrant: quadrant);
var job = new NestJob(new[] { part }, new[] { stock });
var result = Solve(job, new NestJobPlacement("part", 0, x, y, 0));
Assert.Equal(NestJobStatus.Complete, result.Status);
Assert.Equal(new NestJobPlacement("part", 0, x, y, 0), Assert.Single(result.Plates[0].Placements));
}
[Fact]
public void FixedAndBoundedRotationPoliciesRejectDisallowedAngles()
{
var fixedPart = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(4, 2)), 1,
rotation: RotationPolicy.Fixed(System.Math.PI / 2));
var fixedJob = new NestJob(new[] { fixedPart }, new[] { new NestPlateStock("stock", new Size(10, 10), 1) });
Assert.Throws<InvalidOperationException>(() => Solve(fixedJob, new NestJobPlacement("part", 0, 0, 0, 0)));
var fixedResult = Solve(fixedJob, new NestJobPlacement("part", 0, 2, 0, System.Math.PI / 2));
Assert.Equal(NestJobStatus.Complete, fixedResult.Status);
var boundedPart = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(4, 2)), 1,
rotation: RotationPolicy.BoundedSweep(0, System.Math.PI / 2, System.Math.PI / 4));
var boundedJob = new NestJob(new[] { boundedPart }, new[] { new NestPlateStock("stock", new Size(10, 10), 1) });
Assert.Throws<InvalidOperationException>(() => Solve(boundedJob,
new NestJobPlacement("part", 0, 2, 0, System.Math.PI / 3)));
var boundedResult = Solve(boundedJob, new NestJobPlacement("part", 0, 2, 0, System.Math.PI / 4));
Assert.Equal(NestJobStatus.Complete, boundedResult.Status);
}
[Fact]
public void EdgeTouchingIsAllowedAtZeroSpacingAndRejectedAtPositiveSpacing()
{
var part = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(2, 2)), 2);
var touching = new[]
{
new NestJobPlacement("part", 0, 0, 0, 0),
new NestJobPlacement("part", 1, 2, 0, 0)
};
var zeroSpacing = new NestJob(new[] { part }, new[] { new NestPlateStock("stock", new Size(10, 10), 1) });
var positiveSpacing = new NestJob(new[] { part }, new[] { new NestPlateStock("stock", new Size(10, 10), 1, 0.1) });
Assert.Equal(NestJobStatus.Complete, Solve(zeroSpacing, touching).Status);
Assert.Throws<InvalidOperationException>(() => Solve(positiveSpacing, touching));
}
[Fact]
public void OverlapAndContainmentAreRejected()
{
var outer = new NestJobPart("outer", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(6, 6)), 1);
var inner = new NestJobPart("inner", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(2, 2)), 1);
var job = new NestJob(new[] { outer, inner }, new[] { new NestPlateStock("stock", new Size(20, 20), 1) });
Assert.Throws<InvalidOperationException>(() => Solve(job,
new NestJobPlacement("outer", 0, 0, 0, 0),
new NestJobPlacement("inner", 0, 2, 2, 0)));
}
[Fact]
public void EmptyStockStopsWithoutCallingCandidateNester()
{
var nester = new CountingNester();
var part = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(2, 2)), 1);
var job = new NestJob(new[] { part }, Array.Empty<NestPlateStock>());
var result = new NestJobRunner(_ => nester).Solve(job);
Assert.Equal(NestJobStopReason.StockExhausted, result.StopReason);
Assert.Equal(0, nester.Calls);
}
[Theory]
[InlineData("Default")]
[InlineData("Strip")]
public void RealEngineSmokeCasesPreserveInputAndProduceSafeAccounting(string strategy)
{
var drawing = new Drawing("generated rectangle", TestDrawingFactory.Rectangle(6, 4));
var part = DrawingJobMapper.FromDrawing("part", drawing, 3);
var sourceGeometry = part.Geometry.Motions.ToArray();
var stock = new NestPlateStock("stock", new Size(30, 50), 1, 1, new Spacing(1, 1, 1, 1));
var job = new NestJob(new[] { part }, new[] { stock }, new NestJobOptions(strategy));
var result = new NestJobRunner(PlateNesterFactory.Create).Solve(job);
var materialized = NestResultMaterializer.Materialize(job, result);
Assert.Equal(NestJobStatus.Complete, result.Status);
Assert.All(result.Fulfillment, fulfillment => Assert.Equal(fulfillment.Requested,
fulfillment.Placed + fulfillment.Unplaced));
Assert.Equal(sourceGeometry, job.Parts[0].Geometry.Motions);
Assert.Equal(3, job.Parts[0].Quantity);
Assert.Equal(1, job.Plates[0].Quantity);
Assert.All(materialized.Nest.Plates, plate =>
{
var workArea = plate.WorkArea();
Assert.All(plate.Parts, placed =>
{
Assert.True(placed.BoundingBox.Left >= workArea.Left - 1e-6);
Assert.True(placed.BoundingBox.Right <= workArea.Right + 1e-6);
Assert.True(placed.BoundingBox.Bottom >= workArea.Bottom - 1e-6);
Assert.True(placed.BoundingBox.Top <= workArea.Top + 1e-6);
});
for (var left = 0; left < plate.Parts.Count; left++)
for (var right = left + 1; right < plate.Parts.Count; right++)
Assert.False(plate.Parts[left].Intersects(plate.Parts[right], out _));
});
}
private static NestJobResult Solve(NestJob job, params NestJobPlacement[] placements) =>
new NestJobRunner(_ => new CandidateNester(placements)).Solve(job);
private sealed class CandidateNester(IEnumerable<NestJobPlacement> placements) : IPlateNester
{
public PlateCandidate Place(PlatePlacementRequest request, IProgress<NestJobProgress>? progress = null,
CancellationToken token = default) => new(placements);
}
private sealed class CountingNester : IPlateNester
{
public int Calls { get; private set; }
public PlateCandidate Place(PlatePlacementRequest request, IProgress<NestJobProgress>? progress = null,
CancellationToken token = default)
{
Calls++;
return new PlateCandidate(Array.Empty<NestJobPlacement>());
}
}
}
@@ -66,7 +66,7 @@ public class NestJobStockSelectionTests
var area = Solve(new[] { Part("p", 1) }, new[] { Stock("large", 20, 20, 1), Stock("small", 10, 10, 1) },
request => Candidate(request, "p"));
var envelope = Solve(new[] { Part("p", 2) }, new[] { Stock("a", 10, 10, 1), Stock("b", 10, 10, 1) },
request => request.Stock.Id == "a" ? CandidatePair("p", 0, 10) : CandidatePair("p", 0, 1));
request => request.Stock.Id == "a" ? CandidatePair("p", 4, 5) : CandidatePair("p", 4, 0));
var inputOrder = Solve(new[] { Part("p", 1) }, new[] { Stock("first", 10, 10, 1), Stock("second", 10, 10, 1) },
request => Candidate(request, "p"));
@@ -93,7 +93,7 @@ public class NestJobStockSelectionTests
new NestJobRunner(_ => new Nester(place)).Solve(new NestJob(parts, stock, options));
private static NestJobPart Part(string id, int quantity, int priority = 0) =>
new(id, PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle()), quantity, priority);
new(id, PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(4, 5)), quantity, priority);
private static NestPlateStock Stock(string id, double width, double length, int? quantity) =>
new(id, new Size(width, length), quantity);
@@ -103,10 +103,10 @@ public class NestJobStockSelectionTests
return new PlateCandidate(new[] { new NestJobPlacement(id, 0, firstX, 0, 0) });
}
private static PlateCandidate CandidatePair(string id, double first, double second) => new(new[]
private static PlateCandidate CandidatePair(string id, double secondX, double secondY) => new(new[]
{
new NestJobPlacement(id, 0, first, first, 0),
new NestJobPlacement(id, 1, second, second, 0)
new NestJobPlacement(id, 0, 0, 0, 0),
new NestJobPlacement(id, 1, secondX, secondY, 0)
});
private static PlateCandidate Empty() => new(Array.Empty<NestJobPlacement>());
@@ -0,0 +1,120 @@
using OpenNest.CNC;
using OpenNest.Geometry;
namespace OpenNest.Engine.Tests.Jobs;
public class NestJobValidationTests
{
[Fact]
public void IncrementalContoursUseAccumulatedCoordinates()
{
var program = new Program(Mode.Incremental);
program.MoveTo(0, 0);
program.LineTo(4, 0);
program.LineTo(0, 3);
program.LineTo(-4, 0);
program.LineTo(0, -3);
var job = new NestJob(new[]
{
new NestJobPart("part", PartGeometrySnapshot.FromProgram(program), 1)
}, new[] { new NestPlateStock("stock", new Size(10, 10), 1) });
var result = Solve(job, new NestJobPlacement("part", 0, 0, 0, 0));
Assert.Equal(NestJobStatus.Complete, result.Status);
Assert.Equal(new PartFulfillment("part", 1, 1, 0), Assert.Single(result.Fulfillment));
}
[Fact]
public void CandidateInsideAnotherRequirementsHoleDoesNotOverlapMaterial()
{
var outer = new NestJobPart("outer", PartGeometrySnapshot.FromProgram(RectangleWithHole()), 1);
var inner = new NestJobPart("inner", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(2, 2)), 1);
var job = new NestJob(new[] { outer, inner }, new[] { new NestPlateStock("stock", new Size(20, 20), 1) });
var result = Solve(job,
new NestJobPlacement("outer", 0, 0, 0, 0),
new NestJobPlacement("inner", 0, 4, 4, 0));
Assert.Equal(NestJobStatus.Complete, result.Status);
Assert.Single(result.Plates);
Assert.Equal(2, result.Plates[0].Placements.Count);
}
[Fact]
public void UnknownOrOverproducingCandidateFailsBeforeCommitWithoutChangingInput()
{
var reports = new List<NestJobProgress>();
var part = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(2, 2)), 1);
var stock = new NestPlateStock("stock", new Size(20, 20), 1);
var job = new NestJob(new[] { part }, new[] { stock });
var runner = new NestJobRunner(_ => new CandidateNester(new[]
{
new NestJobPlacement("part", 0, 0, 0, 0),
new NestJobPlacement("unknown", 0, 4, 0, 0)
}));
Assert.Throws<InvalidOperationException>(() => runner.Solve(job, new InlineProgress(reports.Add)));
Assert.Equal(1, job.Parts[0].Quantity);
Assert.Equal(1, job.Plates[0].Quantity);
Assert.DoesNotContain(reports, report => report.Stage == NestJobStage.PlateCommitted);
}
[Fact]
public void CandidateThatOverproducesIsRejectedRatherThanClamped()
{
var part = new NestJobPart("part", PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(2, 2)), 1);
var job = new NestJob(new[] { part }, new[] { new NestPlateStock("stock", new Size(20, 20), 1) });
Assert.Throws<InvalidOperationException>(() => Solve(job,
new NestJobPlacement("part", 0, 0, 0, 0),
new NestJobPlacement("part", 1, 4, 0, 0)));
Assert.Equal(1, job.Parts[0].Quantity);
Assert.Equal(1, job.Plates[0].Quantity);
}
[Theory]
[InlineData(true)]
[InlineData(false)]
public void OpenOrZeroLengthContoursAreRejected(bool zeroLength)
{
var program = new Program();
program.MoveTo(0, 0);
program.LineTo(4, 0);
if (zeroLength) program.LineTo(4, 0);
program.LineTo(4, 3);
program.LineTo(0, 3);
if (zeroLength) program.LineTo(0, 0);
var job = new NestJob(new[] { new NestJobPart("part", PartGeometrySnapshot.FromProgram(program), 1) },
new[] { new NestPlateStock("stock", new Size(20, 20), 1) });
Assert.Throws<ArgumentException>(() => new NestJobRunner(_ => new CandidateNester(Array.Empty<NestJobPlacement>())).Solve(job));
}
private static NestJobResult Solve(NestJob job, params NestJobPlacement[] placements) =>
new NestJobRunner(_ => new CandidateNester(placements)).Solve(job);
private static Program RectangleWithHole()
{
var program = TestDrawingFactory.Rectangle(10, 10);
program.MoveTo(3, 3);
program.LineTo(3, 7);
program.LineTo(7, 7);
program.LineTo(7, 3);
program.LineTo(3, 3);
return program;
}
private sealed class CandidateNester(IEnumerable<NestJobPlacement> placements) : IPlateNester
{
public PlateCandidate Place(PlatePlacementRequest request, IProgress<NestJobProgress>? progress = null,
CancellationToken token = default) => new(placements);
}
private sealed class InlineProgress(Action<NestJobProgress> report) : IProgress<NestJobProgress>
{
public void Report(NestJobProgress value) => report(value);
}
}