Add arbitrary fixed-effect contrasts

docs/FORMAT.md

@@ -84,6 +84,22 @@ indices[offsets[i]:offsets[i+1]]
 
 An index must be in `[0, n_extra_covariate_rows)`, and a task cannot reference the same row twice.
 
+## Named shared fixed-effect contrasts
+
+Optional arbitrary hypotheses use two files. `--contrast-matrix` is a
+row-major `float64` matrix with shape `n_contrasts x n_base_covariates`; its
+columns follow `base_x` exactly. Task-specific extra fixed-effect columns are
+assigned zero weights automatically. `--contrast-metadata` is a UTF-8 TSV:
+
+```text
+contrast_index  contrast_id  rhs
+0               group_a_b    0
+```
+
+Indices are consecutive and zero based, IDs are unique, and every matrix row
+must contain a nonzero weight. Each row tests `L beta = rhs` with the method
+selected by `--fixed-effect-test` (Satterthwaite or Kenward-Roger).
+
 ## Block output
 
 For block number `KKKKKK`:
@@ -96,6 +112,12 @@ block_KKKKKK.fixed_se.f64.bin
 block_KKKKKK.fixed_stat.f64.bin
 block_KKKKKK.fixed_ddf.f64.bin
 block_KKKKKK.fixed_p.f64.bin
+block_KKKKKK.contrast_estimate.f64.bin
+block_KKKKKK.contrast_se.f64.bin
+block_KKKKKK.contrast_stat.f64.bin
+block_KKKKKK.contrast_numdf.f64.bin
+block_KKKKKK.contrast_ddf.f64.bin
+block_KKKKKK.contrast_p.f64.bin
 block_KKKKKK.complete
 ```
 
@@ -119,6 +141,7 @@ grad_inf
 fixed_test_method
 fixed_test_status
 fixed_test_offset
+contrast_test_offset
 extra_joint_num_df
 extra_joint_den_df
 extra_joint_f
@@ -142,12 +165,13 @@ The covariance array uses the row-wise packed lower triangle:
 The `.complete` marker is written last and contains tab-separated key/value rows:
 
 ```text
-format  spectra-reml-block-v2
+format  spectra-reml-block-v3
 block   0
 tasks   256
 beta_elements  4096
 cov_elements   34816
 fixed_test_elements  4096
+contrast_test_elements  1280
 ```
 
 Consumers must ignore blocks without `.complete`.
@@ -180,6 +204,13 @@ one numerator degree of freedom. For every task with extra covariates, the
 summary also contains an F test of the joint null that all task-specific fixed
 effects are zero.
 
+The six `contrast_*` arrays share `contrast_test_offset` and follow the
+contrast metadata order. A one-row Satterthwaite contrast reports a signed t
+statistic; Kenward-Roger reports an F statistic with one numerator degree of
+freedom. Both methods retain the signed `L beta` estimate and their adjusted
+standard error. Negative `contrast_test_offset` means that no valid contrast
+tests were emitted for that task.
+
 `fixed_test_status` is one of:
 
 ```text
@@ -218,9 +249,13 @@ fixed_effect_se_json
 fixed_effect_statistic_json
 fixed_effect_denominator_df_json
 fixed_effect_p_value_json
+contrast_estimate_json
+contrast_standard_error_json
+contrast_statistic_json
+contrast_numerator_df_json
+contrast_denominator_df_json
+contrast_p_value_json
 ```
 
-Project-specific software can attach coefficient names. The public C++
-inference API also accepts general linear hypotheses `L beta = rhs`; the batch
-format currently emits coefficient-wise tests and the joint extra-covariate
-test.
+Contrast JSON arrays follow `contrast_index`; IDs and right-hand sides are
+stored in the manifest-referenced contrast metadata TSV.