Add GARI support to decoder CLIs

[arshpreetmaan]

Summary

This PR adds C++ CLI support for consuming the GARI matrix and layout files produced by the Python utilities in #273.

• Add --gari-layout support to Tesseract and Simplex.
• Validate the GARI layout schema, detector counts, detector mapping, and observable counts.
• Map physical detector events from circuits or shot files into the corresponding GARI matrix rows.
• Treat virtual detector rows as zero when constructing decoder shots.
• Use physical-then-virtual detector traversal by default in Tesseract.
• Generate explicit index, BFS, or coordinate detector orderings from the original source circuit, map the resulting physical detector order through the GARI layout, and append virtual detectors in their natural order.

Simplex applies the source-to-GARI detector mapping but does not otherwise interpret detector ordering.

Example

Generate a GARI matrix and layout from a circuit:

python src/py/_tesseract_py_util/gari.py \
    --circuit circuit_file.stim \
    --prior xor \
    --out-dir gari_output

This produces:

gari_output/circuit_file_gari_xor.dem
gari_output/circuit_file_gari_xor_layout.json

Tesseract can sample from the original circuit and decode using the GARI matrix:

./bazel-bin/src/tesseract \
    --circuit circuit_file.stim \
    --dem gari_output/circuit_file_gari_xor.dem \
    --gari-layout gari_output/circuit_file_gari_xor_layout.json \
    --sample-num-shots 100 \
    --sample-seed 1234 \
    --threads 1 \
    --pqlimit 1000000 \
    --beam 5 \
    --beam-climbing \
    --no-revisit-dets \
    --print-stats \
    --stats-out gari-stats.json

We recommend using a smaller beam size (5 or 10 than usual longbeam 20) which provides a useful runtime/accuracy tradeoff while decoding with GARI dem as GARI reduces the row (check) weight by roughly 10 times for the tested BB codes and color codes circuits.

Detector-order options are omitted above, so Tesseract processes the GARI rows in their stored physical-then-virtual order. If explicit detector ordering is requested, Tesseract constructs the order from the source circuit, maps only the physical detector portion, and keeps the virtual detector portion in its natural order.

The same files can be used with Simplex:

./bazel-bin/src/simplex \
    --circuit circuit_file.stim \
    --dem gari_output/circuit_file_gari_xor.dem \
    --gari-layout gari_output/circuit_file_gari_xor_layout.json \
    --sample-num-shots 100 \
    --sample-seed 1234 \
    --threads 1 \
    --stats-out simplex_gari_stats.json

Note: The GARI DEM is a decoding representation and is never sampled. Detection-event data must either be sampled from the original source circuit or loaded from a file containing detector events in the original source-circuit detector order. The companion layout maps those source detector events into the physical GARI rows; virtual GARI rows are initialized to zero. When decoding source-circuit detection-event files against a GARI DEM, --gari-layout must be supplied. Without the layout, the CLI interprets the records in the loaded DEM's detector space and cannot infer the source-to-GARI permutation. The .dem and _layout.json files must be the pair generated from the same source circuit.