ThePirateRay/docs/research/m1-no-device-acceptance.md

M1 no-device build and acceptance checkpoint

• Date: 2026-10-20
• Rayforge commit: c28918c87f8273dd1d244f5a057addc192807fa5
• Scope: packaged Windows desktop and consolidated offline acceptance
• Hardware access: prohibited

Goal

Close the remaining software-controlled part of M1 with one reproducible checkpoint rather than treating isolated spikes as a finished desktop flow. The checkpoint has two outputs:

1. a pinned Windows Rayforge bundle containing the external PirateRay no-device addon;
2. one machine-readable acceptance report covering all current transport-free evidence.

Neither output authorizes USB discovery, controller commands, galvo movement, physical framing, arming or laser output.

On-demand build

Run the build only when a Windows artifact is required:

scripts/build_rayforge_windows_checkpoint.ps1

The script fetches the exact revision from upstreams/rayforge.json, stages the no-device addon into the ignored build checkout, invokes Rayforge's upstream MSYS2 build and creates a portable ZIP plus installer hashes under .build/artifacts/. Normal clone, documentation and test workflows do not download or install the build stack.

The checkpoint script never installs the Windows toolchain. If the reviewed runtime is unavailable, it stops and reports the missing prerequisite. Any toolchain preparation remains a separate, explicitly invoked upstream action or should happen on a dedicated build runner.

Before staging, the script rejects transport imports in the addon. The build manifest records the exact upstream commit and hashes every addon source file, the portable archive and installer. It does not claim the GUI has been tested.

Copy the ZIP, installer and JSON manifest together, then verify an externally produced checkpoint without launching either binary:

python scripts/verify_rayforge_windows_checkpoint.py `
  .build/artifacts/rayforge-windows-checkpoint.json `
  --output .build/artifacts/rayforge-windows-verification.json

The verifier requires portable artifact names, checks sizes and SHA-256 digests, rejects unsafe ZIP paths, confirms the pinned Rayforge commit and compares every packaged addon file with its recorded digest. It never executes the application or installer, and a passing result retains the manual GUI interaction gate.

Automated acceptance

Run with the isolated Rayforge Python environment:

python scripts/run_m1_no_device_acceptance.py <rayforge-checkout> `
  --output .build/artifacts/m1-no-device-acceptance.json

The runner executes the complete repository test suite and public-repository guard, then collects and hashes the regression-verified golden reports for the addon lifecycle, graphical workflow model, layer model, recipe model, JCZ equivalence, negative cases, cancellation/recovery and both LightBurn import spikes. It passes only when the repository checks pass, transport remains absent, the controller backend remains unreachable, negative cases fail closed, cancellation requires recovery and incomplete LightBurn import still blocks encoding.

Manual packaged-app checklist

Use only the isolated no-device profile and an empty work area. Do not connect or configure a controller.

1. Pass the non-executing artifact verifier above.
2. Launch the portable build with a fresh application-data directory.
3. Confirm the UI identifies the state as offline/no-device.
4. Open synthetic geometry and inspect the 110 × 110 mm synthetic field.
5. Name, color, select and reorder layers.
6. Verify canvas visibility and output participation are independent.
7. Edit power, speed, frequency and pulse width and confirm Hz/ns labels.
8. Apply the synthetic unverified recipe; confirm mismatched compatibility is blocked and no approved label appears.
9. Preview enabled geometry, ordering, hatch and out-of-field diagnostics.
10. Save and reopen; confirm geometry, order and supported settings survive.
11. Start simulation, hold, resume, cancel and explicitly recover.
12. Exit and preserve only the sanitized acceptance report and screenshots.

Any device discovery prompt, physical-device status, transport attempt or unlabelled framing action is a stop condition and fails the checkpoint.

Remaining external gates

• A known-working private .lbrn2 is still required before implementing project-level QPulseWidth mapping.
• Human interaction results from the packaged build must be recorded before ADR 0002 can be accepted.
• Physical controller behavior remains outside M1.