Declarative decoder parameter schemas: pluggable realtime decoder configuration

[bmhowe23]

Declarative decoder parameter schemas: true third-party support for realtime decoding

TL;DR

config.cpp was a closed shop: every decoder's YAML parameters were hard-coded into
typed structs, a std::variant, and per-type LLVM YAML traits inside the core library.
A third-party decoder could implement the decoder interface from its own plugin, but
could never be configured through the realtime YAML without patching and rebuilding
CUDA-Q QEC.

This PR replaces all of that with one declarative schema per decoder, registered by the
same shared library that registers the decoder itself. The framework does the rest —
parsing, emission, validation, defaulting, Python conversion, and standalone JSON Schema
export are all generic. Net size: +2.5k/−2.2k lines, and the additions are mostly
tests and docs; the core config machinery is smaller than what it replaces.

Headline benefits

🔌 True third-party realtime decoders. A plugin makes itself fully YAML-configurable
with one registration in its own .so — zero framework changes, zero rebuilds:

register_decoder_schema({"my_decoder", {
    {"strength", k::f64},
    {"mode",     k::string, /*required=*/true},
}});

Proven end-to-end: a demo decoder was built against a sandbox cmake --install tree
using only installed headers, dropped into decoder-plugins/, and ran realtime decoding
with its own YAML parameters — no cudaqx source edits.

🧰 Maintainability: each parameter exists in exactly one place. Previously, adding
one decoder parameter meant touching ~6 places (struct field, variant traits, YAML
mapping, to_heterogeneous_map, Python binding, docs). Now it is one line in the
decoder's own schema. The core gets rid of ~900 lines of per-decoder ladders, and the
YAML walker, validator, and JSON exporter never change when decoders are added.

🐍 Usability: plain dicts and maps, with introspection. No more per-decoder config
classes to learn:

config.decoder_custom_args = {"error_rate_vec": rates, "merge_strategy": "smallest_weight"}
qec.decoder_param_schema("pymatching")   # discover any decoder's parameters at runtime

Values are converted to the schema's declared types (Python ints are fine for float
parameters, negative ints for int32 parameters), and mistakes fail with messages like
Parameter 'bp_seed' of 'nv-qldpc-decoder' expects a 32-bit int value.

✅ Validability, three ways.

• Parse time: unknown keys and missing required keys are rejected by the framework —
  decoders never write those checks.

• Programmatic: config.validate_custom_args() applies the same checks to dict/map-built
  configs before use; decoders can attach cross-field hooks (e.g. sliding_window rejects
  step_size > window_size at config time instead of deep in the constructor).

• Offline: qec.decoder_config_json_schema() exports a standard JSON Schema
  (draft 2020-12) built from whatever plugins are loaded, so CI and editors can lint
  config files without loading the library at all:

  python3 -c "import cudaq_qec; print(cudaq_qec.decoder_config_json_schema())" > schema.json
  check-jsonschema --schemafile schema.json my_config.yaml

🔁 Behavior preserved. YAML round-trips byte-match the old output; trt's default
global_decoder_params materialization, sliding_window's inner-decoder handling, and
configure_decoders status-code semantics are unchanged and covered by tests (31 C++ /
28 Python in the touched suites, all green).

The main downside: this is a breaking change

The typed config classes are gone — nv_qldpc_decoder_config, trt_decoder_config,
sliding_window_config, pymatching_config, chromobius_config, etc. (C++ and Python),
with no deprecation shims. Migration is mechanical:

# before                                      # after
cfg = qec.nv_qldpc_decoder_config()
cfg.max_iterations = 50                       dc.decoder_custom_args = {"max_iterations": 50}
dc.set_decoder_custom_args(cfg)

One structural consequence to be aware of: a decoder's YAML section is only parseable when
its plugin (and therefore its schema) is loaded. Hosts that parse-and-forward configs for
decoders they don't have locally need that decoder's plugin present. The nv-qldpc-decoder
schema is temporarily hosted in-tree until the proprietary plugin registers it itself.

Follow-ups (out of scope here)

• Move nv-qldpc-decoder / srelay_bp schema registration into the proprietary plugin.
• sparse_binary_matrix parameter kind with scipy pass-through (parked on a separate
  branch for its own PR).
• Optionally constrain discriminated sections (e.g. global_decoder) to decoder-role
  schemas rather than any registered name.

🤖 Generated with Claude Code