| Reference sets | `reference_sets/<category>/<version>/` | Curves, arrays, distortion models, optics, cosmic-ray data, and other files |
| Release compositions | `releases/<release>.yaml` | A small lock manifest that pins one definition set and one exact version of every reference category |
Every definition-set directory uses the fixed filenames `detector_types.yaml`,
`readout_modes.yaml`, `calibration_profiles.yaml`, `focal_plane.yaml`, and
`reference_assignments.yaml`; no additional definition-set manifest is required.
A release can therefore combine, for example, cosmic-ray references `1.0.0`
with filter transmissions `2.1.0`. Pins are always exact; values such as `2.x`
are not accepted as release policy.
The built-in compositions currently pin:
-`legacy-v1`: definition set `legacy/1.0.0`;
-`next-v1`: definition set `next/1.0.0` with 31 science slots (`00` through
`30`) and the existing FGS definitions;
- reference set `1.0.0` for each category in both compositions.
Released versions should be treated as immutable. Publish changed definitions
or reference files under a new version, then add or update a composition
manifest to pin those exact versions. This avoids copying unchanged reference
files into every definition release.
Instrument releases are immutable directories under `releases/`. Add a new
directory for a new release; do not silently rewrite a release already used for
production.
`legacy-v1` preserves the values formerly stored in the simulator's legacy
`chip_definition.json` file.
## Catalog ownership
| Catalog | Owns |
|---|---|
| `detector_types.yaml` | Detector families and concrete detector types, including QE filenames, size, pitch, technology, and nominal electronics |
| `readout_modes.yaml` | Channel boxes, transforms, per-channel scan regions, raw placement, and output order |
