ENERGY-9: DMM motor-role mislabelling in item_020.rst (m29 DSY described as second-crystal Y; m29 is actually the downstream tank Y for in-beam / retracted mode-switch) — fixed in 2bm-docs

[decarlof]

Summary

The 2-BM manual/item_020.rst DMM block described 2bma:m29 (DMM DSY) as "Second crystal Y relative to the first" in the top-of-block Motors table, and the descriptive paragraph immediately below listed DSY alongside M2 Z and M2 Y as the three motors that "position the seco
nd crystal relative to the first". Both statements were wrong: m29 is the downstream tank Y used for the in-beam / retracted mode switch (constant within each mode at 0 in Mono / -10 in Pink, per ENERGY-5 / cora#254), and it does NOT do per-energy second-crystal fine positi
oning. The actual second-crystal fine Y is 2bma:m32 (M2 Y), which sweeps 25.12 → 13.92 mm across the six calibrated Mono energies to satisfy the Bragg condition (per ENERGY-1 / cora#249).

The mislabelling had lived silently in the docs for years alongside the corrected tank-motor sub-block added by the ENERGY-5 answer. The two descriptions were internally contradictory within the same DMM block — surfaced only when the DMM section was walked end-to-end during the CORA-a
t-2BM briefing preparation on 2026-08-13.

Why this matters (AI-safety framing)

Under human operation the mislabelling is inert: the operator knows the physical DMM layout, drives the motor they mean regardless of the doc's role text, and never touches the wrong one. The two DSY / M2 Y motors are physically distinct enough that no experienced operator would ev
er confuse them at the console.

Under AI-agent operation the doc IS the ground truth. An agent asked to "adjust the second-crystal Y" would resolve that against the Motors table + the paragraph below it, land on DSY (m29) as one of the three "second-crystal fine" motors listed, and drive it. The result would
be:

• The downstream tank Y arm rotating away from its in-beam position (0 mm) toward some Bragg-tracking-scale intermediate value (say ~20 mm),
• Breaking both the Bragg alignment (because M2 Y didn't move) AND the in-beam state (because DSY's only valid values are 0 in-beam and -10 retracted),
• Producing a hard failure that requires a full DMM re-alignment to recover.

This is exactly the class of silent-doc-error that makes autonomous operation risky if the accountability layer doesn't force the ground truth into machine-readable form. It is closely related to the DATA-8 / cora#655 start_date bug pattern
(silent, present for years, harmless under human ops, actively dangerous when a machine consumes the artefact at face value).

What CORA already knows (this is the fix, not a new discovery)

CORA's ENERGY-5 / cora#254 Asset model correctly represents the tank vs crystal split — the five tank/alignment motors (m25..m29) are two-state (mode-dependent constants), and the three energy-tracked motors (m30, m31, m32) are the per-energy Bragg + M2 Y sweep. This ticket i
s not a change request for CORA's Asset model; the CORA model is right.

This ticket documents the doc-side correction that brings the 2-BM manual/item_020.rst DMM block into consistency with the CORA Asset model, and captures the finding in CORA's accountability record for the "docs vs deployed reality" audit surface.

What was fixed

Commit (2bm-docs, decarlof/2bm-docs): 037772e — docs(item_020): correct DMM DSY / M2 Y motor-role descriptions per ENERGY-5 / ENERGY-1 findings

Two spots corrected in docs/source/manual/item_020.rst DMM block:

1. Motors table row for 2bma:m29 (DMM DSY). Was: "Second crystal Y relative to the first". Now: "Downstream tank Y (in-beam / retracted at mode switch; constant within each mode — see the tank / alignment sub-block below). NOT a second-crystal fine motor; that role belongs t
   o M2 Y (2bma:m32)."
2. Paragraph immediately after the Motors table. Was: "The second crystal is positioned relative to the first via the DSY (Y), M2 Z (along beam), and M2 Y motors." Now: describes the crystal-fine positioning as M2 Z + M2 Y only, links the per-energy sweep to cora#249 (ENERG
   Y-1), and explicitly states that DSY is NOT part of the crystal-fine positioning and only does mode-switch in-beam / retracted (with a link to cora#254 (ENERGY-5) for the tank-motor characterisation).

The DMM block now reads consistently end-to-end: motors table + descriptive paragraph + tank/alignment sub-block + per-energy-saved-positions sub-block all state the same picture.

Provenance for CORA's accountability record

• Bug surface date: 2026-08-13, during the "CORA at 2-BM" management-briefing preparation walk of the DMM block.
• Root cause: legacy doc text predating the ENERGY-5 answer; the sub-block added by ENERGY-5 corrected the tank-motor role but the top-of-block Motors table + surrounding paragraph were left un-reconciled.
• Which CORA question surfaced it: ENERGY-5 / cora#254 established the tank-motor semantics; ENERGY-1 / cora#249 gave the per-energy M2 Y table that unambiguously identifies m32 (not m29) as the second-crystal fine Y motor.
• Fix strategy: doc-side reconciliation only. No IOC change. No CORA Asset model change. The physical motor assignments are already correct in the IOC and correctly represented in the CORA Asset model; only the human-readable docs were wrong.
• AI-safety class: silent-doc-error, indistinguishable from a correct doc under human ops, actively dangerous under naive AI-agent consumption. Analogous to cora#655 (DATA-8) in surface class though different in mechanism.

Related

• ENERGY-1 / cora#249 — per-energy M2 Y table (m32, 25.12 → 13.92 mm across six Mono energies).
• ENERGY-5 / cora#254 — tank / alignment motors (m25..m29) are mode-dependent constants, not per-energy.
• DATA-8 / cora#655 — closely analogous class of silent-doc bug (also resolved-upstream, also ai-safety-relevant).