106 lines
4.5 KiB
Markdown
106 lines
4.5 KiB
Markdown
# 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:
|
||
|
||
```powershell
|
||
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:
|
||
|
||
```powershell
|
||
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:
|
||
|
||
```powershell
|
||
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.
|