ThePirateRay/docs/research/m3-hardware-research-protocol.md

# M3 controller identity and status research protocol

- Status: Draft; not approved for execution
- Date: 2026-10-21
- Target: Makerspace Næstved JPT 100 W E2/M7 MOPA fiber laser
- Controller: JCZ/EZCAD2-compatible, observed USB `9588:9899`
- Scope: identity and read-only status only
- Hardware access authorized by this document: **no**

## Purpose

This protocol is the review gate between the completed no-device work and any
future controller access. It is deliberately narrower than a controller test:
it defines how a proposed session must be specified, reviewed, stopped and
recorded before an endpoint may be opened.

The public template is
`tests/fixtures/m3-hardware-protocol-template.json`. It contains no allowed USB
operation because the repository does not yet have sufficient evidence to name
exact request bytes, response constraints and safety behavior. That absence is
a blocker, not a field to fill by inference.

The validator can only report `incomplete`, `invalid`, or `ready_for_review`.
It always reports `hardware_access_authorized: false`. A later, session-specific
human approval must reference the immutable plan hash; neither this document
nor a successful validator run grants permission to touch hardware.

## Known facts and unresolved assumptions

Observed facts:

- Windows passively enumerated `USBLMCV4`, VID/PID `9588:9899`, device
  revision descriptor `0005`, with no compatible function driver installed.
- The LightBurn export identifies a `JCZFiber`/`LibUSB` JPT profile and a
  110 × 110 mm work area.
- BalorMK independently targets the same USB identity and provides a mock
  transport, but its live commands include motion- and emission-capable paths.

Not established:

- that descriptor `0005` is a board or firmware revision;
- that any apparently read-only controller request cannot reset state, move a
  galvo, arm the source or change an output;
- the currently mounted lens and correction profile by physical verification;
- a reviewed, reversible Windows driver strategy for this computer;
- the exact request/response bytes safe to use for identity or status.

## Non-negotiable scope

M3 may eventually cover controller enumeration, identity, firmware/capability
discovery and status. The following remain prohibited throughout this protocol:

- persistent writes or configuration changes;
- job or list upload and execution;
- galvo motion and physical framing;
- source arming or laser emission;
- replay of an unknown request or response;
- automatic retry after an abort or unexpected response.

M4 requires a new protocol. An M3 result cannot be stretched to authorize
motion, framing, marking, parameter sweeps or output-off assumptions.

## Gates before a session can be reviewed

### 1. Evidence gate

Every proposed operation must be listed individually with:

- a unique operation identifier and single purpose;
- public evidence provenance using an artifact ID;
- evidence level (`observed` or `independently-implemented`);
- exact request bytes—never wildcards, inferred fields or exploratory ranges;
- a bounded expected-response contract;
- one timeout and exactly one attempt;
- explicit `read-only-no-motion-no-emission` classification;
- `state_change_expected: false`.

An empty allowlist keeps the plan incomplete. A malformed or state-changing
operation makes it invalid.

### 2. Physical gate

Before connecting the research computer, the session plan must record:

- the reviewed physical method that prevents emission independently of
  software, and confirmation that it was verified;
- a cleared work area that assumes unexpected galvo motion is still possible;
- an accessible and tested emergency stop;
- a named safety observer present for the whole live portion;
- physical confirmation of the machine/profile identity and mounted optics.

“Laser power set to zero” or a UI toggle is not an independent emission
inhibition method.

### 3. Software and driver gate

- The production controller backend remains absent from The Pirate Ray.
- A narrow experiment harness must enforce the reviewed operation allowlist.
- Unknown responses are captured and stop the session; they are never replayed.
- No operation is retried automatically.
- The current Windows driver state is recorded privately before change.
- Driver installation, replacement and rollback require their own reviewed,
  reversible plan. This repository does not install or switch drivers.
- The normal LightBurn control computer is not modified for convenience.

### 4. People and review gate

The plan names an operator, safety observer and protocol reviewer. One person
may not silently fill all roles during execution. The reviewer checks the
machine identity, evidence for every allowlisted operation, physical isolation,
driver rollback, capture destination and stop/recovery procedures.

After `validate_m3_hardware_protocol.py` reports `ready_for_review`, freeze the
plan bytes and SHA-256. A separate approval record must identify that hash,
reviewer, approval time with timezone, location and exact session window. Any
plan edit invalidates that approval.

## Session sequence

The eventual reviewed session follows this order and stops at the first failed
gate:

1. Brief operator and observer; verify emergency-stop access.
2. Confirm machine, source, lens and controller identity without opening an
   endpoint.
3. Apply and verify the independent emission inhibition.
4. Clear the work area and assume motion remains possible.
5. Record the original Windows driver state and rollback evidence privately.
6. Verify hashes for the plan, harness and dependencies.
7. Start capture into the prepared private destination.
8. Connect only the allowlisted controller identity.
9. Execute one allowlisted operation once.
10. Compare the response only with its predeclared constraints.
11. Stop; do not improvise a follow-up request.
12. Disconnect, restore the reviewed driver state, and verify normal shutdown.
13. Hash raw evidence privately and create only sanitized derived public notes.

No batch of “harmless queries” is permitted. Additional operations require a
new reviewed plan or a new version of the allowlist.

## Immediate abort conditions

Any of these ends the session without automatic retry:

- unexpected galvo motion;
- any emission or source-arm indication;
- interlock state change;
- unexpected controller reset or disconnect;
- attempted transfer not present in the immutable allowlist;
- response outside the predeclared contract;
- stop request from either operator or observer.

On abort: stop the harness, disconnect USB if safe, use the reviewed physical
power-down procedure, preserve logs, record an incident, and do not send a
speculative reset/stop command. A controller stop command is itself prohibited
until separately evidenced and allowlisted.

## Evidence and publication

Raw captures, serials, instance identifiers, driver exports, photos and local
paths go to `ThePirateRay-PrivateStash` with byte count, SHA-256, acquisition
time, origin and classification. The public repository receives sanitized
derived notes and synthetic regression fixtures only. Vendor binaries are not
executed or committed publicly.

The session report must distinguish:

- **observed** bytes or state;
- **inferred** interpretation;
- **unknown** behavior requiring more evidence.

## Validate the draft plan

```powershell
python scripts/validate_m3_hardware_protocol.py `
  tests/fixtures/m3-hardware-protocol-template.json
```

The committed template is expected to return `incomplete`: roles, physical
controls, recovery, driver plan, session metadata and exact evidence-backed
operations are intentionally absent. Do not change those fields merely to make
the validator green.

## Current conclusion

The written-protocol roadmap requirement is now represented and testable, but
the protocol is not executable. The next evidence needed for M3 is a reviewed
driver/rollback strategy and a justified exact read-only operation contract.
Until those exist and a specific plan receives separate human approval, no USB
endpoint may be opened and no controller bytes may be sent.