plan for refactor chi scan

## 6. Testing & validation

flying_chi runs against the live IOC — no unit-testable layer. Validation is

empirical, via the operator and the archiver:

1. **Smoke test with beam off.** Run the sweep; confirm no exceptions,

   confirm all three PVs gave back ≥30 samples each, confirm the restore

   block actually restored `VELO`, `VMAX`, `BDST`, `EventUpdatePeriod`, and

   slit gaps (use `caget` to check post-run state).

2. **Back-to-back comparison with CHI_scan.py** on the same sample/slit

   setup, beam on. Compare the fitted chi centre from each; they should

   agree within the fit error bar (typically 0.05–0.1°).

3. **Archiver cross-check** — after a successful flying_chi run, query the

   archiver for `BL4B:Mot:chis.RBV` and `BL4B:Det:N1:Det1:EventRate_RBV`

   across the sweep window using `setup/archiver-query.sh`. Confirm the

   camonitor samples we captured line up with the archived sample density

   (they should — camonitor sees the same CA monitor updates the archive

   engine does).

4. **Failure-mode test**: set `event_update_period_ms = 10`, run — expect

   the pre-flight cadence check to raise a clear error instead of

   completing an under-sampled sweep.

### 6.1 Execution environment constraint

flying_chi runs against the live IOC — **no unit-testable layer**, and the

implementing agent runs on a **development machine with archiver access

only**. It cannot `caput` to the beamline, `ssh` to the DAS server, or

launch the script directly. All interactive testing is performed by the

operator on the instrument while the agent observes the result through the

archiver and logs shared into `/SNS/users/6ov/BL4B/...`.

The validation protocol is therefore **prompt-and-observe**:

1. Agent prepares a self-contained test-run script or prompt block

   (parameters, expected behaviour, expected archiver PVs and window).

2. Operator runs it at the beamline, copy-pastes console output into a

   shared file, or simply confirms it completed.

3. Agent queries the archiver (`setup/archiver-query.sh`) for the time

   window of the run and cross-checks:

   - that the motor actually swept `startCHI → endCHI` in one shot

     (chis.RBV trace is monotonic, no mid-sweep pauses),

   - that `EventRate_RBV` posted samples throughout the sweep (no dropouts

     indicating the detector stopped updating),

   - that `PCharge` incremented (beam was on, or explicitly confirm it

     was off for beam-off smoke tests),

   - that `.VELO`, `.VMAX`, `.BDST`, slit Y-gaps, and `EventUpdatePeriod`

     are back at their pre-run values at the end of the window (this is

     the restore-block integrity check — the archiver sees these PVs too).

Any PV visible to the archiver (verified: `BL4B:Mot:chis.RBV`, `.DMOV`,

`.VELO`, `.VMAX`, `.BDST`; `BL4B:Det:N1:Det1:EventRate_RBV`; `PCharge`;

slit gap readbacks) is directly queryable by the agent. PVs that the

archiver *doesn't* record (e.g., the computed σ samples inside the

Python script's memory) must be saved to a text/CSV file by the operator

and inspected via shared filesystem.

### 6.2 Test sequence

| # | Test | What operator does | What agent verifies (archiver / shared file) |

|---|---|---|---|

| T1 | Beam-off smoke test | Run flying_chi with `startCHI=-0.2, endCHI=+0.2, flight_velocity=0.1`, beam **off**. Capture console output to `/SNS/users/6ov/BL4B/<date>/flying_chi-T1.txt`. | (a) `chis.RBV` swept monotonically across the window. (b) All flight-mutated PVs (`VELO` if set, `VMAX` if set, `BDST`, `EventUpdatePeriod`, three slit Y-gaps) match pre-window values post-window. (c) Console log reports ≥30 samples per profile PV. |

| T2 | Pre-flight cadence-check failure | Run with `event_update_period_ms = 10`. | Script aborts before the sweep starts (no chis motion in archiver). Console shows the explicit cadence-check error. Verifies §5.3 defensive code path. |

| T3 | Back-to-back with CHI_scan.py, beam on | Run CHI_scan.py to completion; immediately run flying_chi.py on the same sample/slit geometry. Save both scripts' console output. | (a) Archiver shows the 11 discrete dwell steps of CHI_scan.py followed by one continuous sweep of flying_chi.py. (b) Fitted chi centres from the two scripts agree within the larger of the two reported fit error bars. (c) flying_chi wall-clock time ≤ CHI_scan.py wall-clock time for the same sweep span. |

| T4 | MoveToXFit follow-through | Same as T3 with `MoveToXFit=True`. | Archiver shows a final `chis.put` to the fitted centre after the sweep ends. RBV converges to that value within `.RDBD`. |

| T5 | Restore-on-interrupt | Operator runs the sweep and hits Ctrl-C mid-flight. | Archiver shows `EventUpdatePeriod`, `VELO`, `VMAX`, `BDST`, and slit Y-gaps restored to pre-run values, even though the sweep did not reach `endCHI`. Proves the `try/finally` guards cover the interrupt path. |

### 6.3 Archiver query recipe for the agent

Per-test template the agent runs on the dev machine:

```bash

# Wrap the operator-reported run window; pad by ±30s for restore visibility

START='2026-04-XX HH:MM:00'

END='2026-04-XX HH:MM:00'

./setup/archiver-query.sh \

    --pv 'BL4B:Mot:chis.RBV,BL4B:Mot:chis.DMOV,BL4B:Mot:chis.VELO,BL4B:Mot:chis.VMAX,BL4B:Mot:chis.BDST,BL4B:Det:N1:EventUpdatePeriod,BL4B:Det:N1:Det1:EventRate_RBV,BL4B:Det:PCharge,BL4B:Mot:si:Y:Gap:Readback,BL4B:Mot:s1:Y:Gap:Readback,BL4B:Mot:s2:Y:Gap:Readback' \

    --start "$START" --end "$END" \

    --format csv -o /tmp/flying_chi-TN.csv

```

Pre-flight: confirm each of these PVs is archived by running

`./setup/archiver-query.sh --search 'BL4B:Mot:chis*'` once and noting which

fields are present. If `.VELO` / `.VMAX` / `.BDST` are not archived (they

often aren't — archive engines typically skip rarely-changing config

fields), the restore check for those must fall back to operator-reported

pre/post `caget` snapshots pasted into the test file.

### 6.4 Archiver limitations to plan around

- **Restore checks for config fields** (`.VELO`, `.VMAX`, `.BDST`,

  `EventUpdatePeriod`) may require the operator to `caget` them before and

  after each run and paste the output into the test log. The agent should

  ship a pre/post snapshot command to the operator as part of every test.

- **In-memory σ arrays** are not archivable by definition. Have the script

  save `(tCHI, vCHI, sX, sY, intensity)` to a CSV under

  `/SNS/users/6ov/BL4B/<date>/flying_chi-<run_id>.csv` so the agent can

  post-mortem the fit quality without needing to re-run.

- **Camonitor ≠ archiver sample density.** Camonitor timestamps reflect

  every CA monitor update; the archiver may decimate via its own ADEL /

  MDEL dead-bands on some fields. Expect fewer archiver samples than

  camonitor samples for fast-moving observables — this is normal, not a

  bug.

---

> The script output for Q5 is at /SNS/users/6ov/BL4B/2026/04/14/baseline-event-update-period.txt, please review it. You may write your plan into the tasking project, plan/refactor-chi-scan-with-flying-callback-technique.md

Claude developed [refactor-chi-scan-with-flying-callback-technique.md](refactor-chi-scan-with-flying-callback-technique.md)

### Prompt 3.3

> Great! Regarding 'Testing', you are executing on a development machine which has only archiver access. Where testing is needed, please prompt me to perform the needed operations on the instrument, while you observe the response through the archiver. I like your plan to validate by using the archiver data script we developed. Please update the plan to document this. Should we start a new context to execute the plan?