P1: file parsers, sample sheet, discovery, CLI inspect

Readers for IDAT v3, BPM (locus entries v4-v8), CSV manifest, EGT
(data blocks 5-9) and GTC v3-v5 (plus a layout-preserving GTC writer);
sample-sheet validation (IN-001..IN-014), IDAT discovery and pairing
(IN-020..IN-022), message catalogue and exit codes (CLI-014/016),
JSON Lines logging (CLI-007/008), atomic writes (CLI-011), run manifest,
and `simurg inspect`.

Validation (docs/validation/P1.md): GTC, BPM and EGT readers agree
exactly with Illumina BeadArrayFiles on GSA v4 / GDA v1 files; GTCs
round-trip byte-identically; BPM and CSV manifests are consistent.

docs/messages.md

@@ -0,0 +1,47 @@
+# SimurgArray message catalogue
+
+Generated from `src/simurg/core/errors.py` — do not edit by hand.
+
+| Code | Level | Meaning | Spec |
+|---|---|---|---|
+| `E_BPM_CSV_MISMATCH` | error | BPM and CSV manifests describe different loci | IN-042 |
+| `E_BPM_FORMAT` | error | BPM manifest is malformed or unsupported | IN-040 |
+| `E_CONFIG_KEY` | error | Unknown key in --config YAML | CLI-019 |
+| `E_CONFIG_PARSE` | error | --config file is not valid YAML | CLI-019 |
+| `E_CSV_MANIFEST_FORMAT` | error | CSV manifest is malformed | IN-041 |
+| `E_DUP_GTC` | error | Several GTC files resolve to the same sample | IN-030 |
+| `E_DUP_IDAT` | error | Several IDAT pairs resolve to the same sample | IN-022 |
+| `E_EGT_LOAD` | error | Cluster (EGT) file cannot be loaded | IN-044 |
+| `E_FILE_NOT_FOUND` | error | Input file or folder does not exist | CLI-016 |
+| `E_FILE_UNREADABLE` | error | Input file cannot be read | CLI-016 |
+| `E_GTC_CORRUPT` | warning | GTC file failed validation; sample skipped | IN-032 |
+| `E_GTC_UNSUITABLE` | error | GTC lacks fields required by this command | IN-031 |
+| `E_IDAT_ENCRYPTED` | error | Encrypted (version 1) IDATs are not supported | IN-023 |
+| `E_IDAT_FORMAT` | error | IDAT file is malformed | IN-023 |
+| `E_IDAT_PAIR_MISMATCH` | error | Red and Grn IDATs of a sample do not match | IN-023 |
+| `E_INTERNAL` | error | Internal error (bug); rerun with --debug and report | CLI-014 |
+| `E_NO_INPUT` | error | Neither an input folder nor a sample sheet was given | CLI-006 |
+| `E_NO_INPUT_FOLDER` | error | Sample sheet has no RootFolder and no folder was given | CLI-006 |
+| `E_OUTPUT_EXISTS` | error | Outputs already exist; use --force or --resume | CLI-010 |
+| `E_SHEET_BARCODE_FORMAT` | error | Invalid SentrixBarcode_A / SentrixPosition_A value | IN-007 |
+| `E_SHEET_DELIMITER` | error | Sample sheet is not comma-delimited CSV | IN-001 |
+| `E_SHEET_DUP_COLUMN` | error | Duplicate column (column names are case-insensitive) | IN-003 |
+| `E_SHEET_DUP_SAMPLE` | error | The same barcode/position appears in several rows | IN-009 |
+| `E_SHEET_EMPTY` | error | Sample sheet has no data rows | IN-001 |
+| `E_SHEET_NAME_COLLISION` | error | Sample names are not unique or clash with sample IDs | IN-010 |
+| `E_SHEET_NAME_EMPTY` | error | Sample_Name is empty in at least one row | IN-010 |
+| `E_SHEET_NO_KEY_COLUMNS` | error | Sample sheet lacks SentrixBarcode_A/SentrixPosition_A | IN-002 |
+| `E_SHEET_RESERVED` | error | Sample sheet column collides with an output column | IN-005 |
+| `E_SHEET_TOO_LONG` | error | Sample sheet name or value longer than 500 characters | IN-006 |
+| `I_UNLISTED_IDATS` | info | IDAT pairs not listed in the sample sheet are ignored | IN-016 |
+| `W_DUP_IDAT_RESOLVED` | warning | Duplicate IDAT pair resolved by --on-duplicate-idat | IN-022 |
+| `W_EGT_NAME` | warning | Cluster file name is not portable | IN-045 |
+| `W_GTC_FOREIGN` | warning | GTC was produced by another tool | IN-031 |
+| `W_IDAT_NAME_MISMATCH` | warning | IDAT barcode/position disagrees with its file name | IN-023 |
+| `W_IDAT_NO_SCAN_TIME` | warning | IDAT has no scan entry in its run info | IN-024 |
+| `W_IDAT_UNPAIRED` | warning | IDAT channel file without its partner | IN-021 |
+| `W_MANIFEST_NO_REFSTRAND` | warning | Manifest lacks RefStrand annotation | IN-040 |
+| `W_SHEET_BARCODE_REPAIRED` | warning | Barcode written as a decimal was repaired | IN-007 |
+| `W_SHEET_EMPTY_COLUMN` | warning | Columns with empty headers are ignored | IN-004 |
+| `W_SHEET_ROOTFOLDER_OVERRIDDEN` | warning | CLI folder overrides the sheet RootFolder | IN-008 |
+| `W_SHEET_SEX_CONFLICT` | warning | Reported-sex columns disagree | IN-014 |