De-bias pilot-shaped vocabulary from the fleet-enriched model (energy_change + naming)#540
Merged
Merged
Conversation
…t shape
energy_change was authored from the 2-BM pilot and its description mirrored
2-BM's specific optics ("the DMM Bragg arms + M2 offset, and the
beam-tracking sample-slit vertical pair"). 2-BM is a bending-magnet
beamline (zero InsertionDevice), so that is the degenerate, mono-only
coordination -- not the fleet norm. The 81-beamline enrichment data shows
the dominant shape is a coordinated multi-device group: monochromator PLUS
a gap-tracked insertion-device source (56/81 have an InsertionDevice, ~21
gap-track it with mono energy), often plus beam-following mirrors / slits,
realized over an energy PseudoAxis (~30 beamlines) whose partition rule
decomposes the commanded energy into the real axes.
This is the intentional-modeling-not-mirroring correction: the pilot's
implementation leaked into what is meant to be a federation-portable
capability. The STRUCTURE was right and the fleet confirms it (energy is a
Capability -> Method -> Procedure coordinated move over a PseudoAxis, NOT a
device Role or a new compound primitive -- both would duplicate existing
machinery). Only the CONTENT was 2-BM-shaped.
Rewrites the description to name the intent, source-agnostic: coordinate
every energy-driven axis the DEPLOYMENT declares (mono Bragg or PGM
grating+c-value; commonly a gap-tracked undulator, and APPLE-II phase; any
beam-following mirror offset / slit pair), decomposed per-deployment by the
energy PseudoAxis partition rule; the bending-magnet mono-only case (2-BM)
is called out as the degenerate shape, not the template. Adds the
readback/Calibration distinction (some beamlines expose energy read-only)
alongside the existing scan-vs-set distinction.
ENERGY-1: structure confirmed by the fleet; content de-2-BM'd. No energy
Role or compound-axis primitive coined (the PseudoAxis + Procedure already
model it); the energy methods correctly keep needed_families (the
coordination is the Capability/Procedure's job, not a Role contract).
Co-Authored-By: Claude <noreply@anthropic.com>
Coverage report
This PR does not seem to contain any modification to coverable code. |
…ffix The 46-family fleet exposed a contradiction the ~15-family pilot never tripped: naming.md stated "a thing-noun, NOT an agent-noun (which names a Role)" as a bright line, and flagged "any agent-noun used as a Family name" as a smell. But ~10 legitimate Families are agent-noun-shaped (Monochromator, Manipulator, Collimator, Condenser, Transfocator, Polarization/ElectronAnalyzer, and the blessed TemperatureController / FlowController). The rule as written forbade the exact form the same doc endorses two lines later (<Domain>Controller). The suffix heuristic was being stated as a law; at pilot scale the proxy never visibly failed, at fleet scale it does. Fix: demote grammar from verdict to evidence. The real discriminator is the axis -- a Family is a device you install (has instances and ports), a Role is a job a Method binds (neither). Spelling is the usual tell, not the gate. Established device-class names that are agent-noun-shaped (Monochromator) stay Families; the "bare agent-noun Family" smell is narrowed to its true target: an instance-less functional word masquerading as a device (the retired Imager, a bare Controller), not agent-noun spelling as such. Also lands the symmetric carve-out for the Shutter Role (from the seed work): a Role may take an established thing-noun when the agent form is unnatural (Shutter, not Shutterer) -- decided by instances-and-ports, not suffix. Edits: the Three-axes table + tell, the Family rule, the Role rule, the aggregate-decision list, and the smell. This is the naming analogue of the energy_change de-bias: the pilot DESIGN generalized to the fleet unchanged; the enrichment revealed where a heuristic was written as a law and needed demoting to a heuristic. No rename, no code, no reviewer change (the R1-R6 field-naming reviewer is a separate rule set, unaffected). Co-Authored-By: Claude <noreply@anthropic.com>
xmap
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
Two corrections from the same finding: the 2-BM pilot design generalizes to the 81-beamline fleet unchanged, but the enrichment data exposed two places where pilot-era specifics or over-strong heuristics leaked into what are meant to be federation-portable references. Neither is a redesign; both strip pilot-isms so the vocabulary matches the generality the design already had.
Commit 1 -
energy_changecapability de-biasThe description named 2-BM's exact optics (
DMM Bragg arms + M2 offset + sample-slit vertical pair). 2-BM is bending-magnet (zero InsertionDevice), so that is the degenerate mono-only case. Fleet: 56/81 have an insertion device, ~21 gap-track it with mono energy, ~30 model energy as a PseudoAxis decomposing to real motors.Rewrote source-agnostic: coordinate every energy-driven axis the deployment declares (mono Bragg or PGM grating+c-value; commonly a gap-tracked undulator + APPLE-II phase; beam-following mirror/slit), decomposed by the energy PseudoAxis partition rule; the BM mono-only case is called out as degenerate, not the template. Adds the readback/Calibration distinction.
Verdict (ENERGY-1): structure confirmed by the fleet (Capability -> Method -> Procedure over a PseudoAxis; no energy Role, no new primitive - both would duplicate existing PseudoAxis + Procedure machinery); only content was 2-BM-shaped.
Commit 2 - naming.md Family/Role discriminator
The 46-family fleet exposed a contradiction the ~15-family pilot never tripped: naming.md stated "a thing-noun, NOT an agent-noun" as a bright line and flagged "any agent-noun Family" as a smell, yet ~10 legitimate Families are agent-noun-shaped (
Monochromator,Manipulator,Collimator,TemperatureController...). The rule forbade the exact form the same doc endorses (<Domain>Controller).Fix: the axis is the decider, grammar is only the usual tell. A Family is a device you install (instances + ports); a Role is a job a Method binds (neither). Established agent-noun device-class names stay Families; the "bare agent-noun Family" smell is narrowed to its true target (an instance-less job masquerading as a device, e.g. the retired
Imager). Lands the symmetricShutter-Role carve-out (a Role may take a thing-noun when the agent form is unnatural). No rename, no code; the R1-R6 field-naming reviewer is a separate rule set, unaffected.Test plan
pytest tests/unit/deployments/test_catalog_descriptor.py(descriptor + render)mkdocs build --strictcleanGenerated with Claude Code