OpenNest/docs/post-verification.md

# Verify a nest before posting

## Docked desktop validation

Choose **Nest > Validate Nest...** to inspect all plates without running the cut
planner or selecting a post processor. It opens the editor's read-only side panel
in **Validate Nest (live programs)** mode, distinct from the panel's unapplied
**Plan Cutting** proposal. The validation panel checks overlapping material,
missing lead-ins, and rapid crossings in the existing placed programs and cutting
order. Findings identify plate and part sequence numbers in a read-only grid;
incomplete or failed checks are never reported as clear. Select a row to switch
the main plate view to that plate and focus the finding. The scrollable report
retains every result and the selected finding's explanation.
While a finding is selected, its named parts retain their normal colors; other
parts use muted gray fills and visible gray outlines, lead-ins, and marks. Selecting
another finding updates the emphasis. Clearing the finding or closing validation
restores normal rendering without changing drawing colors or selection.

Overlaps use the same magenta material shading as **View > Overlap Check**. A
DPI-scaled ring expands and fades continuously while the finding is selected;
both its color and contrasting halo fade as it grows. For overlaps the ring marks the area centroid (possibly between
separate patches); for missing lead-ins it marks the contour start. Rapid warnings
pulse the offending orange dashed segment continuously and mark its contacts with
the completed contour using fixed-screen-size magenta crosshairs with white halos.
Contacts use native lines/arcs and the rapid check's existing numerical tolerances;
shared vertices and tangencies get one marker, and travel along an edge marks the
contact span endpoints. Start-only departure is excluded. Travel entirely inside
a contour has no boundary contact markers. Incomplete findings use the part center when available;
findings without a usable location do not invent a marker. Closing the inspector
clears the highlight and restores the original plate, zoom, and overlap display mode.

Validation does not change placements, programs, lead-ins, or cutting order, save
the nest, or write CNC output. Minimum spacing and plate boundaries are not checked.
It does not verify a post processor's final output. Posting still runs its own
fresh verification and consent flow.

Finish or cancel active nesting/fill operations before validating. The panel is
exclusive with editing and other side-panel actions while it owns the nest. The
main plate view remains available for wheel zoom, middle-button pan, and **F**
or middle-button double-click to fit. Panel X, Cancel or Escape requests
cancellation and waits for the worker to stop before restoring editing controls.
Switching to Plan mode also waits for any validation worker; it does not promote
a live validation report into a plan check. Closing the editor or main window
joins the worker before continuing the close. Posting while inspection is open
is refused; close the panel and use the fresh posting review. The former floating
validator window is retired; non-editor checks remain available through the
shared `PostVerificationAnalyzer` without an editor UI dependency.

## Posting workflow

The desktop's **Nest > Post > (post processor)** workflow checks every plate after
post settings are accepted and before asking where to save CNC output. The review
shows all three check categories, even when there are no findings:

- **Overlapping parts and clamps:** shared material between placed parts, including containment,
  and physical material overlapping an active clamp. Holes are subtracted; placing a part inside
  a sufficiently large cutout is not itself an overlap. The same review also warns if a nominal
  manual cut-off line crosses an active clamp, even when its regenerated cut is currently trimmed;
  a line contact has no material-overlap area. Removed clamps on that sheet are not checked.
  The placed cut-off program is checked too, so a definition edited without regenerating its
  cut still warns where the posted cut would cross a clamp (one warning per cut-off and clamp).
  Clamp zones are compared in the plate's quadrant frame. A missing or malformed clamp zone
  makes the clamp checks incomplete (a warning), never a clear result.
  This uses clean drawing geometry, not added lead-in/out paths.
- **Missing lead-ins:** cutting contours without an actual, nonzero lead-in in the
  placed program. Applying a lead-in to only one contour does not clear the other
  contours. Scribe-only work and scrap cutoff lines do not require lead-ins here.
  The cutting planner supports direct contour piercing without lead-ins; that does
  not suppress this pre-post review warning or grant posting consent.
- **Rapid crossings:** direct XY moves crossing closed, already-cut, untabbed
  contours in cutting order, or an active clamp's physical footprint. This includes
  earlier holes within the same part and previously cut parts. A future cut is not
  an obstacle yet. Actual uncut gaps are respected; enabling tabs in settings alone
  is not evidence that a gap exists. Clamp-rapid warnings are conservative: head
  height/retracts are not modeled, so inspect the emitted route and machine setup.
  A clamp whose footprint covers the program start point warns on every posting
  attempt by design; there is no exemption for the first rapid and no persisted
  bypass (settled decision D10).

Findings identify the plate and part's position in the cutting sequence. Read the
scrollable report, cancel to fix the nest, then post again to rerun verification.
Uncheckable geometry is reported as incomplete, not passed. The overlap check reads
clean drawing programs made of the built-in instructions only; a missing instruction
list, any other instruction type, or a hole stored as an absolute-mode subprogram
(OpenNest writes them incremental) makes that part's check incomplete. Multiple interrupted
cut fragments, or a lead-out after an open contour that might cut through a tab,
also require manual review rather than being assumed retained.

## Explicit override

With any warning, **Post Anyway** is disabled until the user selects:

> I understand the listed risks, including possible head crashes and machine or
> material damage. I choose to bypass these warnings and continue posting this nest.

Consent applies only to that posting attempt. Unchecking disables posting again;
opening another review always starts unchecked. Cancel, Escape, and the window's
close button do not write CNC files. Cancel is the default button. A clear report
still requires **Continue Posting**. An unexpected verification failure blocks
posting rather than allowing an override of an absent report.

The editor is modal during verification and posting dialogs. Posting is refused
while auto-nesting, interactive fill, or a busy plate action can still change the
nest. Cancellation keeps the modal dialog open until its worker has stopped.
No automatic repair, resequencing, lead-in insertion, or tab insertion is performed.

## Console

`--post` prints the same report. Warnings prevent CNC output (including overwriting
an existing file) and return exit code 1. After reviewing them, explicitly pass
`--acknowledge-post-risks` to accept the risks for that invocation. The switch does
not skip verification and is not persisted. When `--post` is requested, verification
must pass or be acknowledged before either nest saving or CNC writing. Nest-save
and CNC destinations must differ; collisions are refused even with acknowledgment.
Without `--post`, ordinary nest saving is unchanged; `--no-save` skips that save.

The raw `IPostProcessor` plugin interface remains a low-level writer. Third-party
callers must apply their own review/consent flow using `PostVerificationAnalyzer`;
the gate is installed at OpenNest's desktop and console posting entry points.

## Selected post and cut order

Cincinnati CI Fiber preserves the placed part/contour order and pierce positions
used by this check. The older Cincinnati CL post sorts parts and moves cutoffs;
Gravograph builds and optimizes separate tool passes. Those two posts, and unknown
plugins, therefore show an additional **incomplete final rapid sequence** warning
requiring acknowledgment even if the nest-level checks have no findings. This
change does not silently alter their existing CNC output order.

## Limits and maintainer contract

These checks are warnings, not a machine safety certification. They inspect the
nest's placed programs and direct XY travel, not a simulation of final NC output.
A post processor or controller may change routing, cutting order, lead-ins,
retract height, or parking moves. They check planar clamp footprints but not clamp
height, actual head clearance, tipping, slats or tab strength. Review the generated
CNC program and machine setup before cutting, even when this report has no warnings.

`OpenNest.Core/Diagnostics/PostVerificationAnalyzer` owns the cross-platform logic;
its report exposes findings, display text, and `CanPost(risksAcknowledged)`. Use
`AnalyzeForPost` at posting entry points so unknown post ordering is not silently
certified. `IPostVerificationSupport.PreservesPlacedProgramOrder` is an opt-in
contract, not a machine-safety claim; only declare it after verifying the writer's
part order, contour order, and pierce positions. The WinForms dialog renders the
report and enforces per-attempt consent. New callers
must keep inputs stable until analysis completes, honor cancellation, and never
treat incomplete analysis as a clear result. Keep analysis out of paint handlers.
The overlap diagnostic's documented numeric/tessellation limits also apply.

Future hardening should inspect a shared post-specific emitted motion stream,
including controller retracts and final parking, rather than pretending direct XY
geometry proves physical head clearance. The [fixed-program route foundation](cutting-planner.md)
reuses these motion/completion checks but is not yet a desktop planner or an Apply
API; its route-only `Ready` result does not replace fresh posting review.

## Verification on Windows

The core/console tests run cross-platform. Dialog tests and actual desktop behavior
require Windows; Linux cross-compilation is not runtime verification.

1. Run `dotnet test OpenNest.WinForms.Tests/OpenNest.WinForms.Tests.csproj`.
2. Post a nest containing two overlapping parts and a part without lead-ins.
   Verify the report lists the plates/parts, shows all check categories, and disables
   **Post Anyway** until consent is checked. Uncheck it to verify disabling again.
3. Cancel with the button, Escape, and X on separate attempts; none should open the
   output save dialog. Reopen the review and confirm consent is reset.
4. Use a sequence that cuts a closed untabbed part, moves to its far side, then
   rapids back across it. Verify a crossing warning. Change the sequence so the
   perimeter has not yet been cut, then assign a real tab gap and recheck the
   appropriate control cases. Include a hole crossed later in the same part.
5. Acknowledge the warnings and post through both a single-file and multi-file post.
   Confirm output and normal overwrite prompts. Post a clear, leaded nest with Cincinnati CI Fiber and
   verify the report still appears without requiring a risk override.
6. During a large verification, cancel; the editor must stay disabled until the
   worker exits, with no output. A fill still finishing after its progress dialog
   closes must prevent posting until it has completed.

For failures, record the menu action, nest fixture, selected post, visible report,
and exact exception text.