# Bench rules

These rules apply to every model building or optimizing an OpenNest engine. Engines are no longer
a competition between models: each engine targets a job lane (rectangles, circles, rings,
irregular), and a change lands only when it beats that lane's current best on the benchmark.
`README.md` in this folder covers what counts as an engine; this file covers how the run works.

## Your workspace

- You are working in a copy of OpenNest. Your engine is `Engines/OpenNest.Engine.__NAME__/`.
- Other engines in OpenNest-Engines are open to read, compare against and borrow from. Credit
  borrowed ideas in your report. Do not edit another engine's folder in the same change.
- Do not edit `OpenNest.Core`, `OpenNest.Engine`, `OpenNest.Benchmark` or anything else outside
  your engine folder, except for throwaway tools under `tools/` and scratch work under
  `bench-local/` (see below). If shared code has a bug that blocks you, work around it in your
  engine and describe the bug in your report.

## Version control

- At the start, if this copy is not already a git repository, run `git init` in the copy's root
  and commit everything as `Initial bench copy` before changing anything.
- Commit every time the engine reaches a working state (it builds and the tests pass), with a
  message that says what changed and why, plus any benchmark numbers you measured.
- When an experiment makes things worse, go back to the last good commit rather than
  patching forward. Do not rewrite or squash history; the commit log is part of the record
  of your run.
- Do not add a git remote or push anywhere.

## Real parts

- Real production drawings are available read-only at `/mnt/rogers/PEP Drawings/Archive`
  (on hermes.lan) or `Y:\Archive` (on Windows); both are the same archive.
  Use them to build realistic benchmark jobs.
- Never modify, move or delete anything in the archive.
- Do not copy DXF files into your engine folder, and do not commit archive paths, file names or
  part numbers inside your engine folder. The engine folder may be published; these drawings
  are customer property. Keep manifests, results and notes that reference the archive under
  `bench-local/` in the copy's root instead.
- Acceptance also uses jobs you did not tune on. Tune for real parts in general, not for the
  specific drawings you tested with.

## Tests and scoring

- `Engine.Testing/` is the shared, read-only test kit supplied beside engine folders in
  bench copies. Reference it for shapes, job construction, layout assertions and inherited
  engine contract tests; do not copy or edit it during an engine optimization run.
- Placement must be deterministic: no clocks, unseeded randomness or environment variables
  may influence placement. Budgets count work. Wall time may stop work only through the
  host's cancellation token. Diagnostics must not affect placement decisions.
- Keep the starter tests in `tests/` and keep them passing. Add tests; do not weaken,
  skip or delete existing ones. If you believe an existing test is wrong, leave it and explain
  why in your report.
- Engines are scored by `OpenNest.Benchmark`. Every layout goes through `NestValidator`; an
  invalid layout places nothing and pays the unplaced-part penalty, so validity comes before
  utilization.
- Benchmark with `--parallel 1` whenever you report timing.

## Your report

When you finish, update `README.md` in your engine folder to replace the template text with:

- the algorithm and why you chose it,
- what you tried that did not work,
- benchmark results (synthetic jobs only in the README; real-part results go in
  `bench-local/`),
- any shared-code bugs or improvements you found, with measured numbers, so they can be
  upstreamed.