YAML interface: feature parity gaps with the discoal CLI

[nspope]

As of: e08c756 in nsp-yaml-revamp.

Tracker of which CLI features are exposed in the YAML schema and which are not.

The CLI is documented under docs/*.rst and parsed by src/core/discoal_multipop.c. YAML surface is the cyaml schema in src/core/configInterface.h plus the runtime validation in src/core/configInterface.c.

CLI features absent from the YAML interface

These are documented (or just present) in the CLI but cannot be
expressed in a YAML config.

1. Prior distributions for ABC / ML pipelines. The CLI exposes -Pt, -Pr / -Pre, -Pa, -Pu, -PuA, -Px, -Pf, -Pc, -Pe1, -Pe2 (see docs/advanced_features.rst). None have YAML equivalents; the YAML schema treats every parameter as a single point value. This is the largest single gap.
2. Linked-locus sweeps (-ls, -ld, -ln). These simulate a sweep occurring outside the sampled region at a specified genetic distance. Documented in docs/selection.rst; no YAML field controls leftRho / leftRhoFlag.
3. Recurrent sweeps left of the locus (-L). The YAML's recurrent_sweep_rate only maps to -R (within-locus recurrent hitchhiking). There is no way to ask for -L semantics from YAML.
4. Admixture events (-ea time admixedPop sourcePop1 sourcePop2 proportion). Documented in docs/population_structure.rst. The YAML's population_splits are simple two-way mergers; admixture-style joins (one population draws ancestry from two sources at one time) have no schema entry.
5. Fixed segregating sites count (-s). Asks discoal to condition on a specific segsites value rather than drawing one. No YAML equivalent.
6. Conditional simulation (-C low high, see docs/advanced_features.rst). Asks discoal to retry until recombination falls in a specified range. No YAML equivalent.
7. External trajectory file (-S filename). Reads a sweep allele-frequency trajectory from disk instead of simulating one. No YAML equivalent.
8. Time discretization step (-i deltaTMod). Controls the sweep simulation step size; documented in docs/selection.rst. No YAML equivalent.
9. Functional ancient samples. The CLI -A samples pop time works. The YAML's demographic_events.ancient_samples is in the schema but the parser exits with Ancient sample events not yet implemented if any are present.

Schema entries with no working implementation

The YAML schema accepts five field names that don't actually deliver what they advertise. They divide into two flavors: silent stubs (the parser accepts the value and writes a global, but nothing in the simulator ever reads that global), and loud stubs (the parser rejects the value with an explicit error). Both are worth tracking because they take up surface area in the schema and config_examples/all_options.yaml without earning their keep.

Silent stubs — accepted, written to a global, never read:

• output.finite_output. Sets finiteOutputFlag = 1. A grep of the simulator (excluding the global declaration in
  discoal.h and the zero-init in discoal_multipop.c) finds zero readers. Setting the field has no effect.
• output.output_type: "haplotype". The switch arm in parse_output_block is empty with a // FIXME: it is not clear what should be done here comment. discoal emits its default ms-style stdout regardless.
• output.output_type: "snp_array". Same — empty switch arm, same FIXME, no behavior change. Only output_type: "tree_sequence" actually does anything.

Loud stubs — accepted by the schema, rejected at runtime:

• demographic_events.migration_rate_changes. Rejected with "migration_rate_changes are not yet implemented (no handler in the main event loop)". There is also no CLI primitive for time-varying migration (no -em), so the gap is symmetric; this was the root cause of the config_examples/demes_example.yaml parity failure (see Demes importer emits unfaithful migration events #82).
• demographic_events.ancient_samples. Rejected with "Ancient sample events not yet implemented". The CLI form (-A samples pop time) does work, so this one is also a CLI parity gap (cross-listed under the section above).

Recommendation for either flavor: implement, or remove from the schema and from config_examples/all_options.yaml. The current state — accepting the field but not delivering — is the worst of both, since users will reasonably assume the schema is the spec.

Functional-parity differences (syntactic only, not gaps)

Worth knowing but not actionable.

• Migration matrix. YAML uses a single migration_matrix: block of rows. The CLI uses -M for a uniform matrix and -m i j rate for individual cells; together they can express the same matrices. The YAML form is denser for full-matrix scenarios; the CLI form is denser for sparse ones.
• Single-population convenience. The CLI accepts the model with no -p (one population, all samples in pop 0). The YAML achieves the same by omitting the demography: block — the parser has an explicit fallback in parse_simulation_block that initializes npops = 1, sampleSizes[0] = sample_size, currentSize[0] = 1.0. Documented behavior, but worth mentioning explicitly in the YAML doc since users coming from the CLI may not realize they can drop the block entirely.
• output_type: "tree_sequence" ↔ -ts <file>. Equivalent. YAML unsimplified_tree_sequence: true ↔ CLI -F. Equivalent.
• Time and rate scaling. Identical between YAML and CLI: both use the 2N convention, scaled by the parser's * 2.0 to land in 4N internally.