diff --git a/.github/workflows/lib_qec.yaml b/.github/workflows/lib_qec.yaml
index 7917e0456..43ad0c44c 100644
--- a/.github/workflows/lib_qec.yaml
+++ b/.github/workflows/lib_qec.yaml
@@ -135,6 +135,37 @@ jobs:
       - name: Run example tests
         run: bash scripts/ci/test_examples.sh qec
 
+      # ========================================================================
+      # Realtime decoding demo example
+      #
+      # Build the two example binaries against the INSTALLED SDK -- this is what
+      # enforces the installed-headers-only rule: a build-tree-only include
+      # would fail to compile here. Then drive the delivered decoding_server
+      # over UDP loopback with a real pymatching decode (the qpu-kernel source).
+      # No hardware: the FPGA source needs a ConnectX NIC and is not run in CI.
+      # ========================================================================
+      - name: Build & run realtime_decoding_demo (qpu-kernel, UDP loopback)
+        shell: bash
+        run: |
+          export PATH=/cudaq-install/bin:$PATH
+          # Mirror build_qec.sh: it builds+installs cudaq-realtime to
+          # $CUDAQ_REALTIME_ROOT, defaulting to /tmp/cudaq-realtime when unset
+          # (the case for this workflow). Track the same value so this step
+          # stays correct if the job ever sets CUDAQ_REALTIME_ROOT.
+          RT="${CUDAQ_REALTIME_ROOT:-/tmp/cudaq-realtime}"
+          EX=docs/sphinx/examples/qec/realtime_decoding_demo
+          cmake -S "$EX" -B /tmp/rtdemo-build -G Ninja \
+            -DCUDAQ_INSTALL_DIR=/cudaq-install \
+            -DCUDAQX_INSTALL_DIR="$HOME/.cudaqx" \
+            -DCUDAQ_REALTIME_DIR="$RT"
+          cmake --build /tmp/rtdemo-build -j
+          bash "$EX/run_realtime_decoding.sh" \
+            --source qpu-kernel --decoder pymatching \
+            --install-prefix "$HOME/.cudaqx" \
+            --cudaq-prefix /cudaq-install \
+            --realtime-lib-dir "$RT" \
+            --example-build-dir /tmp/rtdemo-build
+
       # ========================================================================
       # Upload build artifacts for GPU tests
       # ========================================================================
diff --git a/docs/sphinx/conf.py.in b/docs/sphinx/conf.py.in
index e60451a95..8edffa3e2 100644
--- a/docs/sphinx/conf.py.in
+++ b/docs/sphinx/conf.py.in
@@ -95,9 +95,13 @@ master_doc = 'index'
 # This pattern also affects html_static_path and html_extra_path.
 # Fragment files pulled in via ``.. include::`` must not also be processed as
 # standalone documents — doing so causes duplicate C++ / Python domain
-# declarations in the Sphinx domain registry.
+# declarations in the Sphinx domain registry.  Example-directory READMEs are
+# for the shipped example tree (rendered on GitHub), not standalone doc pages
+# -- without the exclusion they are ingested via the '.md' source suffix and
+# warn as toctree orphans.
 exclude_patterns = [
     '_templates',
+    'examples/**/README.md',
     'api/qec/nv_qldpc_decoder_api.rst',
     'api/qec/sliding_window_api.rst',
     'api/qec/trt_decoder_api.rst',
diff --git a/docs/sphinx/examples/qec/realtime_decoding_demo/CMakeLists.txt b/docs/sphinx/examples/qec/realtime_decoding_demo/CMakeLists.txt
new file mode 100644
index 000000000..71f257894
--- /dev/null
+++ b/docs/sphinx/examples/qec/realtime_decoding_demo/CMakeLists.txt
@@ -0,0 +1,220 @@
+# ============================================================================ #
+# Copyright (c) 2026 NVIDIA Corporation & Affiliates.                          #
+# All rights reserved.                                                         #
+#                                                                              #
+# This source code and the accompanying materials are made available under     #
+# the terms of the Apache License 2.0 which accompanies this distribution.     #
+# ============================================================================ #
+
+# Realtime-decoding example.
+#
+# This builds TWO sources, each two ways, against the *installed* CUDA-Q /
+# CUDA-QX SDK -- nothing here reaches into a build tree:
+#
+#   surface_code_realtime_decoding            generator: --target stim; writes
+#                                             the decoder config + syndrome
+#                                             files (pymatching /
+#                                             multi_error_lut / nv-qldpc).
+#   surface_code_realtime_decoding-cqr        lowered kernel: adds
+#                                             -frealtime-lowering -DQEC_APP_CQR;
+#                                             the live QPU kernel that streams
+#                                             syndromes to the delivered
+#                                             decoding_server.
+#   surface_code_ising_realtime_decoding      generator for the Ising decoder
+#                                             profile (trt_decoder: TensorRT
+#                                             predecoder + PyMatching), built
+#                                             from the surface_code-4 lineage
+#                                             the Ising artifacts are bound to.
+#   surface_code_ising_realtime_decoding-cqr  its lowered-kernel counterpart.
+#
+# The decoding_server and the FPGA playback tool are DELIVERABLES (installed,
+# not built here); run_realtime_decoding.sh resolves them from --install-prefix.
+
+cmake_minimum_required(VERSION 3.23)
+
+# The lowered-kernel binary links the realtime dispatch archive (relocatable
+# CUDA device code), so the project enables CUDA and needs an architecture for
+# the device-link step. Default to 80 (A100) -- an architecture the shipped
+# SDK's dispatch archive includes; override to match your GPU:
+# -DCMAKE_CUDA_ARCHITECTURES=90 for Hopper, 100 for Blackwell (e.g. GB200).
+if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+  set(CMAKE_CUDA_ARCHITECTURES 80)
+endif()
+
+project(realtime_decoding_demo LANGUAGES CXX CUDA)
+
+# ---------------------------------------------------------------------------- #
+# Locate the installed SDK.
+# ---------------------------------------------------------------------------- #
+# CUDA-Q: provides nvq++, cudaq/*.h, cudaq/realtime.h and the core runtime libs.
+if(NOT CUDAQ_INSTALL_DIR)
+  if(DEFINED ENV{CUDA_QUANTUM_PATH})
+    set(CUDAQ_INSTALL_DIR "$ENV{CUDA_QUANTUM_PATH}")
+  else()
+    set(CUDAQ_INSTALL_DIR "/usr/local/cudaq")
+  endif()
+endif()
+if(NOT EXISTS "${CUDAQ_INSTALL_DIR}/bin/nvq++")
+  message(FATAL_ERROR
+    "nvq++ not found under CUDAQ_INSTALL_DIR=${CUDAQ_INSTALL_DIR}. "
+    "Pass -DCUDAQ_INSTALL_DIR=<cuda-quantum install prefix>.")
+endif()
+
+# CUDA-QX: provides cudaq/qec/*.h and the QEC + realtime-decoding libs/plugins.
+if(NOT CUDAQX_INSTALL_DIR)
+  if(DEFINED ENV{CUDAQX_INSTALL_DIR})
+    set(CUDAQX_INSTALL_DIR "$ENV{CUDAQX_INSTALL_DIR}")
+  else()
+    message(FATAL_ERROR
+      "Set -DCUDAQX_INSTALL_DIR=<cuda-qx install prefix> (the directory that "
+      "holds include/cudaq/qec and lib/libcudaq-qec.so).")
+  endif()
+endif()
+if(NOT EXISTS "${CUDAQX_INSTALL_DIR}/include/cudaq/qec/code.h")
+  message(FATAL_ERROR
+    "CUDAQX_INSTALL_DIR=${CUDAQX_INSTALL_DIR} does not look like a CUDA-QX "
+    "install (missing include/cudaq/qec/code.h).")
+endif()
+
+set(NVQPP "${CUDAQ_INSTALL_DIR}/bin/nvq++")
+find_package(CUDAToolkit REQUIRED)
+
+# The realtime dispatch archive carries relocatable (RDC) device code, so the
+# -cqr executable must be linked with a CUDA device-link step (see below).
+# The explicit realtime prefix is searched FIRST: when the user passes a
+# separate CUDAQ_REALTIME_DIR they mean it to win over any copy the CUDA-Q
+# install carries, or the build silently mixes realtime revisions.
+find_library(CUDAQ_REALTIME_DISPATCH_LIB cudaq-realtime-dispatch
+  PATHS "${CUDAQ_REALTIME_DIR}" "${CUDAQ_INSTALL_DIR}" PATH_SUFFIXES lib REQUIRED)
+
+link_directories(
+  "${CUDAQX_INSTALL_DIR}/lib"
+  "${CUDAQX_INSTALL_DIR}/lib/decoder-plugins"
+  "${CUDAQ_INSTALL_DIR}/lib"
+  "${CUDAQ_INSTALL_DIR}/lib/plugins")
+
+set(_src "${CMAKE_CURRENT_SOURCE_DIR}/surface_code_realtime_decoding.cpp")
+set(_ising_src
+    "${CMAKE_CURRENT_SOURCE_DIR}/surface_code_ising_realtime_decoding.cpp")
+
+# Only the CUDA-QX headers need an explicit -I; nvq++ already knows its own
+# CUDA-Q include dir (cudaq/*.h, cudaq/realtime.h, common/*.h).
+set(_nvqpp_includes "-I${CUDAQX_INSTALL_DIR}/include")
+
+# CUDA-Q core libraries, listed AFTER the qec + simulation libs on purpose.
+# The simulation backend's static initializer registers into a global map owned
+# by libcudaq-common; ELF runs initializers in reverse DT_NEEDED (link) order,
+# so the qec/simulation libs must be listed FIRST (they initialize last) and the
+# cudaq core libs LAST (they initialize first) or the registration dereferences
+# a not-yet-constructed map and segfaults at startup.
+set(_cudaq_core_libs
+  cudaq-mlir-runtime nvqir nvqir-stim
+  cudaq-qec-realtime-decoding cudaq-qec-decoders
+  cudaq cudaq-platform-default cudaq-em-default
+  cudaq-common cudaq-operator cudaq-logger)
+
+# ---------------------------------------------------------------------------- #
+# Helper: compile the source with nvq++ into an object, in an isolated working
+# directory (nvq++ drops intermediates named after the source, so two compiles
+# of the same file must not share a cwd).
+# ---------------------------------------------------------------------------- #
+function(_add_nvqpp_object out_var obj_name src)
+  set(_obj "${CMAKE_CURRENT_BINARY_DIR}/${obj_name}.o")
+  set(_wd  "${CMAKE_CURRENT_BINARY_DIR}/${obj_name}.nvqpp")
+  file(MAKE_DIRECTORY "${_wd}")
+  add_custom_command(
+    OUTPUT "${_obj}"
+    COMMAND ${NVQPP} ${ARGN} -c -fPIC "${src}" -o "${_obj}" ${_nvqpp_includes}
+    DEPENDS "${src}"
+    WORKING_DIRECTORY "${_wd}"
+    COMMENT "Compiling with nvq++ (${obj_name})"
+    VERBATIM)
+  set_source_files_properties("${_obj}" PROPERTIES EXTERNAL_OBJECT TRUE GENERATED TRUE)
+  set(${out_var} "${_obj}" PARENT_SCOPE)
+endfunction()
+
+# ---------------------------------------------------------------------------- #
+# Generator (plain): writes the decoder config + syndrome files.
+# ---------------------------------------------------------------------------- #
+_add_nvqpp_object(_gen_obj generator "${_src}" --target stim)
+add_executable(surface_code_realtime_decoding "${_gen_obj}")
+set_target_properties(surface_code_realtime_decoding PROPERTIES LINKER_LANGUAGE CXX)
+# --no-as-needed: nvqir-stim (the --target stim simulator) and
+# cudaq-platform-default are pulled in at runtime by registration, not by a
+# direct symbol reference, so the default --as-needed would drop them from
+# DT_NEEDED and the process would crash at startup with no platform.
+target_link_libraries(surface_code_realtime_decoding PRIVATE
+  -Wl,--no-as-needed
+  cudaq-qec cudaq-qec-realtime-decoding
+  cudaq-qec-realtime-decoding-simulation ${_cudaq_core_libs}
+  -Wl,--as-needed
+  "${CUDAQ_REALTIME_DISPATCH_LIB}")
+target_link_options(surface_code_realtime_decoding PRIVATE
+  LINKER:--allow-shlib-undefined LINKER:--export-dynamic)
+
+# ---------------------------------------------------------------------------- #
+# Lowered kernel (-cqr): the live syndrome source over UDP.
+# LINKER_LANGUAGE CUDA + CUDA_RESOLVE_DEVICE_SYMBOLS runs the device-link
+# (nvcc -dlink) that resolves the dispatch archive's RDC registration symbols.
+# ---------------------------------------------------------------------------- #
+_add_nvqpp_object(_cqr_obj generator-cqr "${_src}"
+  --target stim -frealtime-lowering -DQEC_APP_CQR)
+add_executable(surface_code_realtime_decoding-cqr "${_cqr_obj}")
+set_target_properties(surface_code_realtime_decoding-cqr PROPERTIES
+  CUDA_SEPARABLE_COMPILATION ON
+  CUDA_RESOLVE_DEVICE_SYMBOLS ON
+  CUDA_STANDARD 17
+  LINKER_LANGUAGE CUDA)
+target_link_libraries(surface_code_realtime_decoding-cqr PRIVATE
+  -Wl,--no-as-needed
+  cudaq-qec cudaq-qec-realtime-decoding
+  cudaq-qec-realtime-decoding-simulation-cqr
+  # The in-process decoding service; also exports
+  # cudaqx_qec_device_call_dispatch_count, which the app prints as evidence
+  # that an external server (not the in-process service) did the decoding.
+  cudaq-qec-realtime-decoding-server-cqr
+  cudaq-device-call-runtime
+  ${_cudaq_core_libs}
+  -Wl,--as-needed
+  "${CUDAQ_REALTIME_DISPATCH_LIB}" CUDA::cudart)
+target_link_options(surface_code_realtime_decoding-cqr PRIVATE
+  LINKER:--allow-shlib-undefined LINKER:--export-dynamic)
+
+# ---------------------------------------------------------------------------- #
+# Ising decoder profile (trt_decoder): the surface_code-4-lineage source, same
+# two build variants. Requires no extra link inputs -- the TensorRT decoder is
+# a runtime-loaded plugin (lib/decoder-plugins/libcudaq-qec-trt-decoder.so in
+# the CUDA-QX install), discovered by the serving side, never linked here.
+# ---------------------------------------------------------------------------- #
+_add_nvqpp_object(_ising_gen_obj ising-generator "${_ising_src}" --target stim)
+add_executable(surface_code_ising_realtime_decoding "${_ising_gen_obj}")
+set_target_properties(surface_code_ising_realtime_decoding PROPERTIES
+  LINKER_LANGUAGE CXX)
+target_link_libraries(surface_code_ising_realtime_decoding PRIVATE
+  -Wl,--no-as-needed
+  cudaq-qec cudaq-qec-realtime-decoding
+  cudaq-qec-realtime-decoding-simulation ${_cudaq_core_libs}
+  -Wl,--as-needed
+  "${CUDAQ_REALTIME_DISPATCH_LIB}")
+target_link_options(surface_code_ising_realtime_decoding PRIVATE
+  LINKER:--allow-shlib-undefined LINKER:--export-dynamic)
+
+_add_nvqpp_object(_ising_cqr_obj ising-generator-cqr "${_ising_src}"
+  --target stim -frealtime-lowering -DQEC_APP_CQR)
+add_executable(surface_code_ising_realtime_decoding-cqr "${_ising_cqr_obj}")
+set_target_properties(surface_code_ising_realtime_decoding-cqr PROPERTIES
+  CUDA_SEPARABLE_COMPILATION ON
+  CUDA_RESOLVE_DEVICE_SYMBOLS ON
+  CUDA_STANDARD 17
+  LINKER_LANGUAGE CUDA)
+target_link_libraries(surface_code_ising_realtime_decoding-cqr PRIVATE
+  -Wl,--no-as-needed
+  cudaq-qec cudaq-qec-realtime-decoding
+  cudaq-qec-realtime-decoding-simulation-cqr
+  cudaq-qec-realtime-decoding-server-cqr
+  cudaq-device-call-runtime
+  ${_cudaq_core_libs}
+  -Wl,--as-needed
+  "${CUDAQ_REALTIME_DISPATCH_LIB}" CUDA::cudart)
+target_link_options(surface_code_ising_realtime_decoding-cqr PRIVATE
+  LINKER:--allow-shlib-undefined LINKER:--export-dynamic)
diff --git a/docs/sphinx/examples/qec/realtime_decoding_demo/prepare_ising_artifacts.py b/docs/sphinx/examples/qec/realtime_decoding_demo/prepare_ising_artifacts.py
new file mode 120000
index 000000000..a2ad54963
--- /dev/null
+++ b/docs/sphinx/examples/qec/realtime_decoding_demo/prepare_ising_artifacts.py
@@ -0,0 +1 @@
+../../../../../libs/qec/unittests/realtime/app_examples/prepare_ising_artifacts.py
\ No newline at end of file
diff --git a/docs/sphinx/examples/qec/realtime_decoding_demo/run_realtime_decoding.sh b/docs/sphinx/examples/qec/realtime_decoding_demo/run_realtime_decoding.sh
new file mode 100755
index 000000000..1381185ad
--- /dev/null
+++ b/docs/sphinx/examples/qec/realtime_decoding_demo/run_realtime_decoding.sh
@@ -0,0 +1,1063 @@
+#!/bin/bash
+# ============================================================================ #
+# Copyright (c) 2026 NVIDIA Corporation & Affiliates.                          #
+# All rights reserved.                                                         #
+#                                                                              #
+# This source code and the accompanying materials are made available under     #
+# the terms of the Apache License 2.0 which accompanies this distribution.     #
+# ============================================================================ #
+#
+# run_realtime_decoding.sh
+#
+# Drive the delivered decoding_server from one of two syndrome sources, both
+# decoding through the SAME prebuilt server:
+#
+#   --source qpu-kernel   The lowered QEC kernel supplies syndromes itself over
+#                         the udp wire, in software (no NIC) -- the portable,
+#                         hardware-free mode -- or over the cpu_roce wire
+#                         (--wire cpu_roce: real RDMA between two loopback-
+#                         cabled RoCE ports; topology from the same
+#                         CUDAQ_CPU_ROCE_TEST_* env vars as the in-tree
+#                         cpu_roce tests).  Every decoder is served on host
+#                         dispatch (a CPU thread calls the decoder; nv-qldpc
+#                         still decodes on its GPU).
+#
+#   --source fpga         The delivered hsb_fpga_syndrome_playback tool
+#                         streams pre-generated syndromes over RoCE from a REAL
+#                         FPGA into the server's RDMA ring (needs a ConnectX NIC
+#                         cabled to the FPGA).  CPU decoders ride the cpu_roce
+#                         wire on host dispatch; nv-qldpc defaults to the
+#                         hololink wire on device_graph dispatch (the GPU
+#                         device-call scheduler).  There is NO emulator here --
+#                         emulator testing lives in the unittests
+#                         hsb_fpga_decoding_server_test.sh.
+#
+# DELIVERABLES (consumed prebuilt from --install-prefix, never built here):
+#   decoding_server, hsb_fpga_syndrome_playback, the QEC + realtime libs,
+#   and the decoder plugins.
+# EXAMPLE BINARIES (the only things the user compiles; from --example-build-dir):
+#   surface_code_realtime_decoding       generator: writes config + syndromes
+#   surface_code_realtime_decoding-cqr   lowered kernel: the live syndrome source
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ============================================================================
+# Defaults
+# ============================================================================
+
+SOURCE="qpu-kernel"          # qpu-kernel | fpga
+DECODER="pymatching"         # pymatching | nv-qldpc-decoder | multi_error_lut
+
+# Where the deliverables live (bin/ + lib/).  Required unless the per-artifact
+# overrides below are all given.  No dev-tree fallback -- shipped code resolves
+# from one install prefix.
+INSTALL_PREFIX="${CUDAQX_INSTALL_DIR:-}"
+# CUDA-Q install (its runtime libs + realtime libs are needed on the load path).
+CUDAQ_PREFIX="${CUDA_QUANTUM_PATH:-/usr/local/cudaq}"
+# Optional separate realtime lib dir (udp transport / dispatch), if not colocated.
+REALTIME_LIB_DIR="${CUDAQ_REALTIME_DIR:-}"
+
+# The example's own build directory (holds the two compiled binaries).
+EXAMPLE_BUILD_DIR="${SCRIPT_DIR}/build"
+
+# Per-artifact overrides (power users); empty => resolved from the prefixes.
+SERVER_BIN=""
+PLAYBACK_BIN=""
+GENERATOR_BIN=""
+KERNEL_BIN=""
+NV_QLDPC_PLUGIN="${CUDAQ_QEC_NV_QLDPC_PLUGIN:-}"
+# Ising artifact directory for the trt_decoder profile (six locally prepared
+# files: model.onnx, H_csr.bin, O_csr.bin, priors.bin, metadata.txt,
+# D_sparse.txt). Nothing in it ships with CUDA-QX; see the docs recipe.
+ISING_ARTIFACTS_DIR="${QEC_ISING_ARTIFACTS_DIR:-}"
+
+# Surface-code experiment parameters. The generator applies two-qubit
+# depolarizing noise on the stabilizer-extraction CNOTs (p_cnot); the fixed
+# simulator seed makes every run -- and therefore the pass/fail counts --
+# reproducible (pass --seed -1 for unseeded runs).
+GEN_DISTANCE=3
+GEN_ROUNDS=4
+GEN_P_CNOT=0.001
+# SPAM (single-qubit depolarizing) rate for the Ising trt_decoder profile,
+# whose noise model is SPAM rather than CNOT depolarizing; 0.01 is the
+# published model's trained operating point.
+GEN_P_SPAM=0.01
+SEED=42
+# Explicit-flag trackers: the trt_decoder profile pins d=7/T=7/SPAM noise and
+# must reject conflicting explicit values rather than silently override them
+# (and only re-defaults --spacing when the user did not set it).
+DISTANCE_EXPLICIT=false
+ROUNDS_EXPLICIT=false
+PCNOT_EXPLICIT=false
+SPACING_EXPLICIT=false
+
+# Shot counts differ by mode: the FPGA plays back a fixed set through a 64-slot
+# RDMA RX ring; the qpu-kernel self-paces via its blocking get_corrections and
+# has no ring to overrun, so it runs more shots by default.  Both overridable.
+FPGA_SHOTS=85
+QPU_KERNEL_SHOTS=200
+NUM_SHOTS=""                 # explicit override
+# The FPGA playback BRAM holds 512 frames and per-round playback spends
+# (syndrome slices + 1 get_corrections) frames per shot. The Ising profile's
+# d7/T7 geometry has 8 slices/shot -> 9 frames/shot -> at most 56 shots per
+# playback run (504/512), just as the d3/T4 default 85 fills 510/512.
+TRT_FPGA_SHOTS=56
+
+# FPGA pacing (us): the playback engine's timer fires once per FRAME (one
+# BRAM window per frame), so a shot takes frames-per-shot x SPACING on the
+# wire.  Pacing keeps playback from overrunning the server's 64-slot RX
+# ring.  The qpu-kernel path needs none.
+SPACING="10"
+
+# The decoding server's two knobs (both default from --source/--decoder):
+#   WIRE     which bridge-provider library carries syndromes into the server
+#            (loaded at runtime as libcudaq-realtime-bridge-<name>.so)
+#   DISPATCH which engine consumes each decoder's ring: host (a CPU dispatcher
+#            thread) or device_graph (the GPU device-call scheduler)
+# The combination gate below rejects pairings this example has not wired up.
+WIRE=""                      # udp | cpu_roce | hololink
+DISPATCH=""                  # host | device_graph
+GPU_ID=0
+
+# Network (fpga source only).  The FPGA data path is same-/24 routed (no
+# gateway), so the bridge NIC's default IP lives on the FPGA's subnet.
+DO_SETUP_NETWORK=false
+IB_DEVICE=""                 # auto-detect first Up ConnectX
+BRIDGE_IP="192.168.0.1"
+FPGA_IP="192.168.0.2"
+MTU=4096
+PAGE_SIZE=384
+# RX ring depth for both FPGA paths, bounded by the HSB QP's 64 receive WQEs
+# (the FPGA writes frame rid to slot rid % NUM_SLOTS; more slots than WQEs drops
+# frames under load). The server clamps the cpu_roce wire's --num-slots to
+# this; the device_graph ring is capped to it in run_fpga.
+NUM_SLOTS=64
+FRAME_SIZE=64
+# Server lifetime failsafe (seconds). decoding_server's --timeout is a TOTAL
+# runtime cap (not inactivity): the server exits once elapsed time exceeds it,
+# even mid-run. 300 matches the in-tree surface_code-4 external-server tests;
+# the default 60 would kill long runs (large --num-shots, slow decoders).
+TIMEOUT=300
+VERIFY=true
+
+# ============================================================================
+# Argument parsing
+# ============================================================================
+
+print_usage() {
+    cat <<'EOF'
+Usage: run_realtime_decoding.sh --source {qpu-kernel|fpga} [options]
+
+Sources:
+  --source qpu-kernel     Lowered kernel streams syndromes over udp (no NIC) or,
+                          with --wire cpu_roce, over real RDMA (see below).
+  --source fpga           Delivered playback streams from a real FPGA over RoCE.
+
+Common:
+  --decoder NAME          pymatching (default) | nv-qldpc-decoder |
+                          multi_error_lut | trt_decoder (the Ising profile:
+                          TensorRT NN predecoder + PyMatching global decoder;
+                          pinned to d=7, rounds=7, SPAM noise 0.01, and
+                          requires the Ising artifact directory below)
+  --install-prefix DIR    Deliverables prefix (decoding_server, playback, libs,
+                          plugins in DIR/bin and DIR/lib).  Required (or give the
+                          per-artifact overrides).
+  --cudaq-prefix DIR      CUDA-Q install (default: $CUDA_QUANTUM_PATH or
+                          /usr/local/cudaq)
+  --realtime-lib-dir DIR  Extra realtime lib dir (udp transport / dispatch)
+  --example-build-dir DIR The example's build dir with the two binaries
+                          (default: <script dir>/build)
+  --nv-qldpc-plugin PATH  Prebuilt libcudaq-qec-nv-qldpc-decoder.so (or set
+                          CUDAQ_QEC_NV_QLDPC_PLUGIN); required for nv-qldpc
+  --ising-artifacts-dir D Prepared Ising artifact directory (model.onnx,
+                          H_csr.bin, O_csr.bin, priors.bin, metadata.txt,
+                          D_sparse.txt); required for trt_decoder (or set
+                          QEC_ISING_ARTIFACTS_DIR).  Absent/incomplete => the
+                          profile SKIPS (exit 77) listing what is missing.
+  --distance N            Surface-code distance (default 3; trt_decoder pins 7)
+  --num-rounds N          Measurement rounds (default 4; must be >= distance;
+                          trt_decoder pins 7)
+  --p-cnot F              Two-qubit depolarizing rate on the CNOTs (default
+                          0.001; not applicable to trt_decoder)
+  --p-spam F              SPAM depolarizing rate for trt_decoder (default 0.01,
+                          the published Ising model's operating point)
+  --seed N                Simulator seed; -1 = unseeded (default 42)
+  --num-shots N           Shots (default: 85 fpga / 200 qpu-kernel)
+  --gpu N                 GPU id for nv-qldpc (default 0)
+  --wire W                Bridge provider carrying syndromes into the server:
+                          udp | cpu_roce | hololink (default: derived --
+                          qpu-kernel -> udp; fpga -> cpu_roce for host
+                          dispatch, hololink for device_graph)
+  --dispatch D            Per-decoder ring consumer: host | device_graph
+                          (default: derived -- fpga + nv-qldpc-decoder ->
+                          device_graph, everything else -> host)
+
+Per-artifact overrides:
+  --server PATH  --playback PATH  --generator PATH  --kernel PATH
+
+Network:
+  --setup-network         Configure the NIC port(s) first (needs sudo): the
+                          FPGA-facing port for --source fpga, or the cpu_roce
+                          channel + daemon pair for --source qpu-kernel
+                          --wire cpu_roce
+  --mtu N                 MTU (default 4096)
+
+qpu-kernel + --wire cpu_roce only -- RDMA topology, via the same env vars as
+the in-tree cpu_roce tests (kernel side = channel, server side = daemon; two
+RoCE-capable ports, e.g. loopback-cabled):
+  CUDAQ_CPU_ROCE_TEST_CHANNEL_DEVICE   kernel-side IB device      (required)
+  CUDAQ_CPU_ROCE_TEST_CHANNEL_IP       kernel-side RoCE IPv4      (10.0.0.1)
+  CUDAQ_CPU_ROCE_TEST_DAEMON_DEVICE    server-side IB device      (required)
+  CUDAQ_CPU_ROCE_TEST_DAEMON_IP        server-side RoCE IPv4      (10.0.0.2)
+
+FPGA-only:
+  --device DEV            ConnectX IB device (default: auto-detect)
+  --bridge-ip ADDR        Server-side NIC IP (default 192.168.0.1; must share
+                          the FPGA's /24)
+  --fpga-ip ADDR          FPGA IP (default 192.168.0.2)
+  --spacing US            Playback pacing in us (default 10). The FPGA timer
+                          fires once per FRAME (one BRAM window), so a shot
+                          spans frames-per-shot x spacing; keeps the RX ring
+                          from overrunning
+  --no-verify             Skip playback correction verification
+
+  --help, -h              Show this help
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --source)           SOURCE="$2"; shift ;;
+        --decoder)          DECODER="$2"; shift ;;
+        --install-prefix)   INSTALL_PREFIX="$2"; shift ;;
+        --cudaq-prefix)     CUDAQ_PREFIX="$2"; shift ;;
+        --realtime-lib-dir) REALTIME_LIB_DIR="$2"; shift ;;
+        --example-build-dir) EXAMPLE_BUILD_DIR="$2"; shift ;;
+        --seed)             SEED="$2"; shift ;;
+        --nv-qldpc-plugin)  NV_QLDPC_PLUGIN="$2"; shift ;;
+        --distance)         GEN_DISTANCE="$2"; DISTANCE_EXPLICIT=true; shift ;;
+        --num-rounds)       GEN_ROUNDS="$2"; ROUNDS_EXPLICIT=true; shift ;;
+        --p-cnot)           GEN_P_CNOT="$2"; PCNOT_EXPLICIT=true; shift ;;
+        --p-spam)           GEN_P_SPAM="$2"; shift ;;
+        --ising-artifacts-dir) ISING_ARTIFACTS_DIR="$2"; shift ;;
+        --num-shots)        NUM_SHOTS="$2"; shift ;;
+        --gpu)              GPU_ID="$2"; shift ;;
+        --server)           SERVER_BIN="$2"; shift ;;
+        --playback)         PLAYBACK_BIN="$2"; shift ;;
+        --generator)        GENERATOR_BIN="$2"; shift ;;
+        --kernel)           KERNEL_BIN="$2"; shift ;;
+        --setup-network)    DO_SETUP_NETWORK=true ;;
+        --device)           IB_DEVICE="$2"; shift ;;
+        --bridge-ip)        BRIDGE_IP="$2"; shift ;;
+        --fpga-ip)          FPGA_IP="$2"; shift ;;
+        --mtu)              MTU="$2"; shift ;;
+        --spacing)          SPACING="$2"; SPACING_EXPLICIT=true; shift ;;
+        --wire)             WIRE="$2"; shift ;;
+        --dispatch)         DISPATCH="$2"; shift ;;
+        --no-verify)        VERIFY=false ;;
+        --help|-h)          print_usage; exit 0 ;;
+        *) echo "ERROR: unknown option: $1" >&2; print_usage >&2; exit 1 ;;
+    esac
+    shift
+done
+
+if [[ "$SOURCE" != "qpu-kernel" && "$SOURCE" != "fpga" ]]; then
+    echo "ERROR: --source must be qpu-kernel or fpga (got '$SOURCE')" >&2; exit 1
+fi
+
+# The bridge NIC and the FPGA must share a /24: there is no gateway on the
+# FPGA link, and --setup-network flushes the NIC and assigns BRIDGE_IP/24, so
+# a mismatched pair leaves the FPGA unreachable -- the run then dies minutes
+# later as an opaque hololink read_timeout_error. Reject it up front.
+if [[ "$SOURCE" == "fpga" && "${BRIDGE_IP%.*}" != "${FPGA_IP%.*}" ]]; then
+    echo "ERROR: --bridge-ip $BRIDGE_IP and --fpga-ip $FPGA_IP are on different" >&2
+    echo "       /24 subnets; the FPGA data path is same-subnet routed." >&2
+    exit 1
+fi
+
+# The example source also supports 'sliding_window', but that decoder is not
+# yet supported over the realtime decoding path to the GPU (it needs matching
+# updates to the proprietary cudevice archive), so this script does not accept
+# it.
+case "$DECODER" in
+    pymatching|nv-qldpc-decoder|multi_error_lut|trt_decoder) ;;
+    sliding_window)
+       echo "ERROR: sliding_window is not yet supported over the realtime" >&2
+       echo "       decoding path to the GPU." >&2; exit 1 ;;
+    *) echo "ERROR: --decoder must be pymatching, nv-qldpc-decoder," >&2
+       echo "       multi_error_lut, or trt_decoder (got '$DECODER')" >&2; exit 1 ;;
+esac
+
+# ---------------------------------------------------------------------------
+# The Ising profile (trt_decoder = TensorRT NN predecoder + PyMatching global
+# decoder) is pinned to the published model's operating point: d=7, rounds=7,
+# basis Z, orientation XV, SPAM noise (--p-spam, default 0.01). Conflicting
+# explicit knobs are rejected rather than silently overridden. On the FPGA the
+# playback BRAM caps it at TRT_FPGA_SHOTS shots per run (see above).
+# ---------------------------------------------------------------------------
+if [[ "$DECODER" == "trt_decoder" ]]; then
+    if { $DISTANCE_EXPLICIT && [[ "$GEN_DISTANCE" != 7 ]]; } || \
+       { $ROUNDS_EXPLICIT && [[ "$GEN_ROUNDS" != 7 ]]; }; then
+        echo "ERROR: the trt_decoder (Ising) profile supports distance=7," >&2
+        echo "       num-rounds=7 only (the published model's operating point)." >&2
+        exit 1
+    fi
+    if $PCNOT_EXPLICIT; then
+        echo "ERROR: trt_decoder uses SPAM noise (--p-spam), not --p-cnot." >&2
+        exit 1
+    fi
+    GEN_DISTANCE=7
+    GEN_ROUNDS=7
+    FPGA_SHOTS="$TRT_FPGA_SHOTS"
+    # d7/T7 sends 9 frames per shot (each frame paced by SPACING) into the
+    # server's 64-slot RX ring (~7 shots of buffer). At the 10us default the
+    # stream outruns the served rate and the ring overruns around shot 8-18
+    # (a corrupted stream then kills the decode with an invalid-syndrome
+    # matching error). 100us per frame is validated on hardware.
+    $SPACING_EXPLICIT || SPACING=100
+    if [[ "$SOURCE" == "fpga" && -n "$NUM_SHOTS" ]] && \
+       (( NUM_SHOTS > TRT_FPGA_SHOTS )); then
+        echo "ERROR: the FPGA playback BRAM holds 512 frames; at d7/T7" >&2
+        echo "       (9 frames/shot) at most $TRT_FPGA_SHOTS shots fit per run" >&2
+        echo "       (got --num-shots $NUM_SHOTS)." >&2
+        exit 1
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# Derive the wire + dispatch defaults, then gate on the combinations this
+# example has wired up and verified:
+#   qpu-kernel : udp wire,      host dispatch  (any decoder incl. trt_decoder)
+#   qpu-kernel : cpu_roce wire, host dispatch  (any decoder incl. trt_decoder)
+#   fpga       : cpu_roce wire, host dispatch  (any decoder incl. trt_decoder)
+#   fpga       : hololink wire, device_graph dispatch  (nv-qldpc-decoder)
+# Everything else is a real configuration of the decoding server that this
+# example does not (yet) exercise, so it is rejected with the reason.
+# ---------------------------------------------------------------------------
+if [[ -z "$DISPATCH" ]]; then
+    if [[ "$SOURCE" == "fpga" && "$DECODER" == "nv-qldpc-decoder" ]]; then
+        DISPATCH="device_graph"
+    else
+        DISPATCH="host"
+    fi
+fi
+case "$DISPATCH" in host|device_graph) ;;
+    *) echo "ERROR: --dispatch must be host or device_graph (got '$DISPATCH')" >&2; exit 1 ;;
+esac
+
+# nv-qldpc's GPU decode (plus first-call PTX JIT on new hardware) cannot
+# drain the server's 64-slot RX ring at the default 10us-per-frame playback
+# pacing -- measured on-rig: 171/510 frames captured (host dispatch) and
+# ~15/85 shots verified (device_graph) before the ring overruns. 100us per
+# frame clears the measured floors on both dispatch paths; an explicit
+# --spacing wins.
+if [[ "$SOURCE" == "fpga" && "$DECODER" == "nv-qldpc-decoder" ]] && \
+   ! $SPACING_EXPLICIT; then
+    SPACING=100
+fi
+
+[[ "$WIRE" == "cpu-roce" ]] && WIRE="cpu_roce"   # accept both spellings
+if [[ -z "$WIRE" ]]; then
+    if [[ "$SOURCE" == "qpu-kernel" ]]; then WIRE="udp"
+    elif [[ "$DISPATCH" == "device_graph" ]]; then WIRE="hololink"
+    else WIRE="cpu_roce"; fi
+fi
+case "$WIRE" in udp|cpu_roce|hololink) ;;
+    *) echo "ERROR: --wire must be udp, cpu_roce, or hololink (got '$WIRE')" >&2; exit 1 ;;
+esac
+
+if [[ "$SOURCE" == "qpu-kernel" ]]; then
+    if [[ "$WIRE" == "hololink" ]]; then
+        echo "ERROR: the qpu-kernel source is not wired to the hololink wire in" >&2
+        echo "       this example (use --wire udp or --wire cpu_roce)." >&2; exit 1
+    fi
+    if [[ "$DISPATCH" != "host" ]]; then
+        echo "ERROR: device_graph dispatch on the qpu-kernel source (pinned shared" >&2
+        echo "       rings) is not exposed by this example." >&2; exit 1
+    fi
+else
+    if [[ "$DISPATCH" == "device_graph" ]]; then
+        if [[ "$DECODER" != "nv-qldpc-decoder" ]]; then
+            echo "ERROR: device_graph dispatch serves only nv-qldpc-decoder" >&2
+            echo "       (got '$DECODER'); CPU decoders use --dispatch host." >&2; exit 1
+        fi
+        if [[ "$WIRE" != "hololink" ]]; then
+            echo "ERROR: device_graph dispatch on the FPGA requires the hololink" >&2
+            echo "       wire (got '$WIRE')." >&2; exit 1
+        fi
+    else
+        if [[ "$WIRE" != "cpu_roce" ]]; then
+            echo "ERROR: host dispatch on the FPGA requires the cpu_roce wire" >&2
+            echo "       (got '$WIRE')." >&2; exit 1
+        fi
+    fi
+fi
+
+# The provider library soname is hyphenated (libcudaq-realtime-bridge-cpu-roce.so)
+# while the conventional token is cpu_roce; the server's resolver composes the
+# soname literally from the token, so pass the hyphenated form on the wire.
+WIRE_TOKEN="$WIRE"
+[[ "$WIRE_TOKEN" == "cpu_roce" ]] && WIRE_TOKEN="cpu-roce"
+
+# ---------------------------------------------------------------------------
+# qpu-kernel over cpu_roce: RDMA topology.  Same four-env-var convention as
+# every in-tree cpu_roce test (CUDA-Q's CpuRoceChannelTester and the QEC
+# two-process test): the lowered kernel (channel) and the server (daemon) each
+# own one RoCE-capable port, cabled to the other.  The kernel binary reads the
+# CHANNEL_* values itself; the DAEMON_* values feed the server's
+# --device/--local-ip and double as the kernel's rendezvous target.
+# ---------------------------------------------------------------------------
+CHANNEL_DEVICE=""; CHANNEL_IP=""; DAEMON_DEVICE=""; DAEMON_IP=""
+if [[ "$SOURCE" == "qpu-kernel" && "$WIRE" == "cpu_roce" ]]; then
+    CHANNEL_DEVICE="${CUDAQ_CPU_ROCE_TEST_CHANNEL_DEVICE:-}"
+    CHANNEL_IP="${CUDAQ_CPU_ROCE_TEST_CHANNEL_IP:-10.0.0.1}"
+    DAEMON_DEVICE="${CUDAQ_CPU_ROCE_TEST_DAEMON_DEVICE:-}"
+    DAEMON_IP="${CUDAQ_CPU_ROCE_TEST_DAEMON_IP:-10.0.0.2}"
+    if [[ -z "$CHANNEL_DEVICE" || -z "$DAEMON_DEVICE" ]]; then
+        echo "ERROR: --wire cpu_roce needs the RDMA topology: set" >&2
+        echo "       CUDAQ_CPU_ROCE_TEST_CHANNEL_DEVICE (kernel-side IB device) and" >&2
+        echo "       CUDAQ_CPU_ROCE_TEST_DAEMON_DEVICE (server-side IB device)." >&2
+        echo "       IPs default to 10.0.0.1 / 10.0.0.2 (override with" >&2
+        echo "       CUDAQ_CPU_ROCE_TEST_CHANNEL_IP / _DAEMON_IP)." >&2
+        echo "       Available IB devices: $(ls /sys/class/infiniband 2>/dev/null | tr '\n' ' ')" >&2
+        exit 1
+    fi
+fi
+
+_log()  { echo "==> $*"; }
+_info() { echo "    $*"; }
+_warn() { echo "WARNING: $*" >&2; }
+_err()  { echo "ERROR: $*" >&2; }
+_banner() { echo; echo "========================================";
+            echo "  $*"; echo "========================================"; echo; }
+
+# ============================================================================
+# Path resolution (install-prefix only; per-artifact overrides win)
+# ============================================================================
+
+resolve_paths() {
+    # Canonicalize user-supplied paths first: generate_data runs the generator
+    # from a temp working dir, and library paths are exported to subprocesses,
+    # so a relative path that validates here would break there. Only rewrite
+    # values that resolve to an existing path -- missing paths stay as-is for
+    # the normal validation below.
+    local _v _abs
+    for _v in INSTALL_PREFIX CUDAQ_PREFIX REALTIME_LIB_DIR EXAMPLE_BUILD_DIR \
+              SERVER_BIN PLAYBACK_BIN GENERATOR_BIN KERNEL_BIN NV_QLDPC_PLUGIN; do
+        if [[ -n "${!_v}" ]]; then
+            if _abs=$(readlink -f -- "${!_v}" 2>/dev/null) && [[ -e "$_abs" ]]; then
+                printf -v "$_v" '%s' "$_abs"
+            fi
+        fi
+    done
+
+    if [[ -z "$SERVER_BIN"    && -n "$INSTALL_PREFIX" ]]; then SERVER_BIN="$INSTALL_PREFIX/bin/decoding_server"; fi
+    if [[ -z "$PLAYBACK_BIN"  && -n "$INSTALL_PREFIX" ]]; then PLAYBACK_BIN="$INSTALL_PREFIX/bin/hsb_fpga_syndrome_playback"; fi
+    # The Ising profile runs its own example pair (the surface_code-4-lineage
+    # source the artifacts are bound to); everything else runs the original.
+    local _example_stem="surface_code_realtime_decoding"
+    [[ "$DECODER" == "trt_decoder" ]] && _example_stem="surface_code_ising_realtime_decoding"
+    if [[ -z "$GENERATOR_BIN" ]]; then GENERATOR_BIN="$EXAMPLE_BUILD_DIR/${_example_stem}"; fi
+    if [[ -z "$KERNEL_BIN"    ]]; then KERNEL_BIN="$EXAMPLE_BUILD_DIR/${_example_stem}-cqr"; fi
+
+    if [[ -z "$SERVER_BIN" ]]; then
+        _err "No decoding_server: pass --install-prefix DIR (or --server PATH)."; exit 1
+    fi
+    if [[ ! -x "$SERVER_BIN" ]]; then _err "decoding_server not found/executable: $SERVER_BIN"; exit 1; fi
+    if [[ ! -x "$GENERATOR_BIN" ]]; then
+        _err "generator not found: $GENERATOR_BIN"
+        _err "Build the example first (cmake --build <dir>) or pass --generator PATH."; exit 1
+    fi
+    if [[ "$SOURCE" == "qpu-kernel" && ! -x "$KERNEL_BIN" ]]; then
+        _err "lowered kernel not found: $KERNEL_BIN (build the example, or --kernel PATH)"; exit 1
+    fi
+    if [[ "$SOURCE" == "fpga" && ! -x "$PLAYBACK_BIN" ]]; then
+        _err "playback tool not found: $PLAYBACK_BIN (a hololink-enabled deliverable)"; exit 1
+    fi
+
+    # Load path: deliverable libs + plugins, plus the CUDA-Q runtime/realtime.
+    # The explicit realtime override goes FIRST: a CUDA-Q prefix may carry its
+    # own libcudaq-realtime.so, and appending the override after it would let
+    # the prefix's copy shadow the one the user asked for (symptom: undefined
+    # symbol errors against the newer realtime ABI).
+    local p=""
+    [[ -n "$REALTIME_LIB_DIR" ]] && p="$REALTIME_LIB_DIR/lib:$REALTIME_LIB_DIR"
+    [[ -n "$INSTALL_PREFIX"   ]] && p="$p:$INSTALL_PREFIX/lib:$INSTALL_PREFIX/lib/decoder-plugins"
+    [[ -n "$CUDAQ_PREFIX"     ]] && p="$p:$CUDAQ_PREFIX/lib:$CUDAQ_PREFIX/lib/plugins"
+    p="${p#:}"
+    export LD_LIBRARY_PATH="${p}:${LD_LIBRARY_PATH:-}"
+
+    # nv-qldpc plugin must be dlopen-able from the deliverable plugins dir.
+    if [[ "$DECODER" == "nv-qldpc-decoder" ]]; then
+        if [[ -z "$NV_QLDPC_PLUGIN" && -n "$INSTALL_PREFIX" \
+              && -f "$INSTALL_PREFIX/lib/decoder-plugins/libcudaq-qec-nv-qldpc-decoder.so" ]]; then
+            NV_QLDPC_PLUGIN="$INSTALL_PREFIX/lib/decoder-plugins/libcudaq-qec-nv-qldpc-decoder.so"
+        fi
+        if [[ -z "$NV_QLDPC_PLUGIN" || ! -f "$NV_QLDPC_PLUGIN" ]]; then
+            _err "nv-qldpc-decoder plugin not available (pass --nv-qldpc-plugin or set"
+            _err "CUDAQ_QEC_NV_QLDPC_PLUGIN).  Skipping this decoder."
+            exit 77   # standard "skip" code
+        fi
+        local link="$INSTALL_PREFIX/lib/decoder-plugins/$(basename "$NV_QLDPC_PLUGIN")"
+        if [[ -n "$INSTALL_PREFIX" && ! -e "$link" ]]; then
+            # Fail fast: the server discovers plugins in this directory, so a
+            # silently failed link surfaces minutes later as an opaque
+            # "server did not construct an 'nv-qldpc-decoder' session".
+            if ! mkdir -p "$INSTALL_PREFIX/lib/decoder-plugins" 2>/dev/null \
+               || ! ln -sf "$NV_QLDPC_PLUGIN" "$link" 2>/dev/null; then
+                _err "cannot place the nv-qldpc plugin in $INSTALL_PREFIX/lib/decoder-plugins"
+                _err "(is the install prefix writable?)"; exit 1
+            fi
+        fi
+    fi
+
+    # trt_decoder needs (a) the SDK's TensorRT decoder plugin (shipped only
+    # when TensorRT was available at the SDK build) and (b) the locally
+    # prepared Ising artifact directory. Both absences are SKIPs, not
+    # failures, mirroring the nv-qldpc plugin policy.
+    if [[ "$DECODER" == "trt_decoder" ]]; then
+        if [[ -z "$INSTALL_PREFIX" \
+              || ! -f "$INSTALL_PREFIX/lib/decoder-plugins/libcudaq-qec-trt-decoder.so" ]]; then
+            _err "TensorRT decoder plugin not found:"
+            _err "  ${INSTALL_PREFIX:-<install-prefix>}/lib/decoder-plugins/libcudaq-qec-trt-decoder.so"
+            _err "Skipping the trt_decoder profile."
+            exit 77
+        fi
+        validate_ising_artifacts
+    fi
+}
+
+# The Ising artifact directory holds six locally prepared files (gated Hugging
+# Face weights + the NVIDIA/Ising-Decoding repository -- see the docs for the
+# recipe). Missing or empty files are listed BY NAME; an unprepared setup is a
+# SKIP (77), not a failure. metadata.txt's content (d7/T7/Z/XV) is enforced by
+# the generator binary itself.
+validate_ising_artifacts() {
+    if [[ -z "$ISING_ARTIFACTS_DIR" ]]; then
+        _err "trt_decoder needs the Ising artifact directory: pass"
+        _err "--ising-artifacts-dir DIR or set QEC_ISING_ARTIFACTS_DIR."
+        _err "See the example documentation for the preparation recipe."
+        _err "Skipping the trt_decoder profile."
+        exit 77
+    fi
+    local f missing=""
+    for f in model.onnx H_csr.bin O_csr.bin priors.bin metadata.txt D_sparse.txt; do
+        [[ -s "$ISING_ARTIFACTS_DIR/$f" ]] || missing="$missing $f"
+    done
+    if [[ -n "$missing" ]]; then
+        _err "Ising artifact directory '$ISING_ARTIFACTS_DIR' is incomplete;"
+        _err "missing or empty:$missing"
+        _err "See the example documentation for the preparation recipe."
+        _err "Skipping the trt_decoder profile."
+        exit 77
+    fi
+    # Canonicalize: the generator embeds this path (model.onnx) into the
+    # config, which the server later reads from a different working directory.
+    ISING_ARTIFACTS_DIR="$(readlink -f -- "$ISING_ARTIFACTS_DIR")"
+}
+
+# ============================================================================
+# Config + syndrome generation (uses the example's generator binary)
+# ============================================================================
+
+GEN_DIR=""
+CONFIG_FILE=""
+SYNDROMES_FILE=""
+
+generate_data() {
+    GEN_DIR="$(mktemp -d /tmp/realtime_decoding_demo.XXXXXX)"
+    CONFIG_FILE="$GEN_DIR/config_${DECODER}.yml"
+    SYNDROMES_FILE="$GEN_DIR/syndromes_${DECODER}.txt"
+
+    # The Ising profile's app takes SPAM noise and the artifact directory;
+    # the original app takes CNOT-depolarizing noise.
+    local gen_noise_args=(--p_cnot "$GEN_P_CNOT")
+    if [[ "$DECODER" == "trt_decoder" ]]; then
+        gen_noise_args=(--p_spam "$GEN_P_SPAM"
+                        --ising-artifacts-dir "$ISING_ARTIFACTS_DIR")
+    fi
+
+    _log "Generating decoder config (decoder=$DECODER, d=$GEN_DISTANCE, rounds=$GEN_ROUNDS)"
+    ( cd "$GEN_DIR" && "$GENERATOR_BIN" \
+        --distance "$GEN_DISTANCE" --num_rounds "$GEN_ROUNDS" "${gen_noise_args[@]}" \
+        --decoder_type "$DECODER" \
+        --save_dem "$CONFIG_FILE" ) >"$GEN_DIR/gen_config.log" 2>&1 || {
+        _err "config generation failed; see $GEN_DIR/gen_config.log"; tail -5 "$GEN_DIR/gen_config.log" >&2; exit 1; }
+
+    # nv-qldpc runs on a GPU: pin the decoder to --gpu via cuda_device_id (the
+    # host worker / device-graph scheduler both honor it). device_graph
+    # dispatch additionally needs the per-decoder `dispatch:` key. The
+    # generator omits these optional fields, so inject them under the
+    # decoder's `type:` line. pymatching/multi_error_lut need neither.
+    if [[ "$DECODER" == "nv-qldpc-decoder" ]]; then
+        local inject_dispatch=""
+        if [[ "$DISPATCH" == "device_graph" ]]; then
+            inject_dispatch="    dispatch:        device_graph"
+        fi
+        awk -v gpu="$GPU_ID" -v dp="$inject_dispatch" '{ print }
+             /^[[:space:]]*type:/ && !d { if (dp != "") print dp;
+                                          print "    cuda_device_id:  " gpu; d=1 }' \
+            "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
+        # Verify the injection landed: a YAML formatting change in the
+        # generator would otherwise silently drop --gpu / the dispatch
+        # override (pinning nv-qldpc to GPU 0, or leaving the decoder on host
+        # dispatch).
+        if ! grep -qE "^[[:space:]]*cuda_device_id:[[:space:]]*${GPU_ID}\$" "$CONFIG_FILE"; then
+            _err "config injection failed: cuda_device_id not found in $CONFIG_FILE"; exit 1
+        fi
+        if [[ -n "$inject_dispatch" ]] && \
+           ! grep -qE "^[[:space:]]*dispatch:[[:space:]]*device_graph\$" "$CONFIG_FILE"; then
+            _err "config injection failed: dispatch not found in $CONFIG_FILE"; exit 1
+        fi
+    fi
+
+    # The trt_decoder entry must carry the Ising model: a config with the
+    # right type but no onnx_load_path would silently construct a bare
+    # matching session on the server instead of the NN predecoder.
+    if [[ "$DECODER" == "trt_decoder" ]]; then
+        if ! grep -qE "type:[[:space:]]+trt_decoder" "$CONFIG_FILE" || \
+           ! grep -q "onnx_load_path" "$CONFIG_FILE"; then
+            _err "generated config lacks a trt_decoder entry with onnx_load_path: $CONFIG_FILE"
+            exit 1
+        fi
+    fi
+
+    # The FPGA source replays a pre-generated syndrome file; the qpu-kernel
+    # source generates syndromes live inside the kernel, so it needs none.
+    # For trt_decoder this run constructs the TensorRT decoder in-process
+    # (engine build from model.onnx) to compute the expected corrections the
+    # playback tool verifies per shot.
+    if [[ "$SOURCE" == "fpga" ]]; then
+        local shots="${NUM_SHOTS:-$FPGA_SHOTS}"
+        local synd_noise_args=(--p_cnot "$GEN_P_CNOT")
+        [[ "$DECODER" == "trt_decoder" ]] && synd_noise_args=(--p_spam "$GEN_P_SPAM")
+        _log "Generating $shots syndromes for playback"
+        ( cd "$GEN_DIR" && "$GENERATOR_BIN" \
+            --distance "$GEN_DISTANCE" --num_rounds "$GEN_ROUNDS" "${synd_noise_args[@]}" \
+            --seed "$SEED" --num_shots "$shots" --load_dem "$CONFIG_FILE" \
+            --save_syndrome "$SYNDROMES_FILE" ) >"$GEN_DIR/gen_syndromes.log" 2>&1 || {
+            _err "syndrome generation failed; see $GEN_DIR/gen_syndromes.log"; tail -5 "$GEN_DIR/gen_syndromes.log" >&2; exit 1; }
+    fi
+    _info "config:    $CONFIG_FILE"
+    if [[ "$SOURCE" == "fpga" ]]; then _info "syndromes: $SYNDROMES_FILE"; fi
+}
+
+# ============================================================================
+# Cleanup
+# ============================================================================
+PIDS=()
+cleanup() {
+    for pid in "${PIDS[@]:-}"; do
+        # `|| true` on the TERM: a pid reaped between the kill -0 and the kill
+        # -TERM would otherwise abort this EXIT trap under set -e AND override
+        # the script's exit status (a PASS run would exit nonzero).
+        [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null && { kill -TERM "$pid" 2>/dev/null || true; sleep 0.5;
+            kill -0 "$pid" 2>/dev/null && kill -KILL "$pid" 2>/dev/null || true; }
+    done
+    [[ -n "$GEN_DIR" && -d "$GEN_DIR" ]] && rm -rf "$GEN_DIR" || true
+}
+trap cleanup EXIT
+
+wait_for_pattern() {
+    local logfile="$1" pattern="$2" timeout_sec="$3" pid="${4:-}"
+    local waited=0
+    while (( waited < timeout_sec * 10 )); do
+        [[ -n "$pid" ]] && ! kill -0 "$pid" 2>/dev/null && { _err "process $pid died"; return 1; }
+        local m; m=$(grep -m1 "$pattern" "$logfile" 2>/dev/null || true)
+        [[ -n "$m" ]] && { echo "$m"; return 0; }
+        sleep 0.1; waited=$((waited + 1))
+    done
+    _err "timeout waiting for: $pattern"; return 1
+}
+
+# ============================================================================
+# qpu-kernel pass/fail criteria -- the same checks the in-tree surface-code
+# ctest drivers apply (surface_code-1-cqr-two-process-test.sh and
+# surface_code-4-yaml-test.sh), so this example fails on the same evidence as
+# the existing tests: hard decoder-failure messages, the corrections-line
+# completion proof, a residual logical-error ceiling of num_shots/50 (min 1),
+# and external-server evidence (the app's in-process dispatch count must be 0
+# + a server dispatch-count floor).
+# ============================================================================
+verify_qpu_kernel_output() {
+    local kernel_log="$1" server_log="$2" shots="$3"
+    local rc=0
+
+    _log "Checking realtime output (surface_code-4 test criteria)"
+
+    # A non-graphlike DEM handed to pymatching surfaces as "Invalid column in H".
+    if grep -q "Invalid column in H" "$kernel_log"; then
+        _err "found 'Invalid column in H' (decoder received a non-graphlike DEM)"; rc=1
+    fi
+    # Hard decoder-init / dispatch failures.
+    if grep -q "terminate called" "$kernel_log"; then
+        _err "found 'terminate called' (the app aborted)"; rc=1
+    fi
+    if grep -q "Decoder 0 not found" "$kernel_log"; then
+        _err "found 'Decoder 0 not found' (decoder was not registered)"; rc=1
+    fi
+    if grep -q "Error initializing decoders" "$kernel_log"; then
+        _err "found 'Error initializing decoders'"; rc=1
+    fi
+
+    # This line proves the realtime decoding path actually ran to completion.
+    if ! grep -q "Number of corrections decoder found:" "$kernel_log"; then
+        _err "missing 'Number of corrections decoder found:' line (decoding did not complete)"; rc=1
+    fi
+
+    # Residual logical errors must stay under the ceiling: a decoder that is
+    # wired up but decoding wrong produces ~random logicals, far above it.
+    local max_non_zero=$((shots / 50))
+    (( max_non_zero < 1 )) && max_non_zero=1
+    local non_zero
+    non_zero=$(grep "Number of non-zero values measured :" "$kernel_log" \
+        | awk -F': ' '{print $2}' | tr -d '[:space:]')
+    if ! [[ "$non_zero" =~ ^[0-9]+$ ]]; then
+        _err "'Number of non-zero values measured' is not a number (got '$non_zero')"; rc=1
+    elif (( non_zero > max_non_zero )); then
+        _err "residual logical errors ($non_zero) exceed ceiling ($max_non_zero) -- decoder appears wired-but-wrong"; rc=1
+    else
+        _info "residual logical errors: $non_zero (ceiling $max_non_zero) -- OK"
+    fi
+
+    # External-server evidence: the app's in-process decoding service must
+    # have dispatched NOTHING (decode did not silently stay local), and the
+    # server must have dispatched at least shots * (rounds + 3) RPCs --
+    # reset + (rounds+1) enqueues + get_corrections per shot.
+    local inproc
+    inproc=$(grep "CQR service dispatch count:" "$kernel_log" | awk -F': ' '{print $2}' | tr -d '[:space:]')
+    if [[ "$inproc" != "0" ]]; then
+        _err "in-process CQR dispatch count is '${inproc:-<missing>}' (expected 0); decode did not stay in the server"; rc=1
+    fi
+    local dispatches min_dispatches=$((shots * (GEN_ROUNDS + 3)))
+    dispatches=$(sed -n 's/^QEC_DECODING_SERVER_DISPATCHED count=\([0-9][0-9]*\)$/\1/p' \
+        "$server_log" | tail -n1)
+    if ! [[ "$dispatches" =~ ^[0-9]+$ ]] || (( dispatches < min_dispatches )); then
+        _err "server dispatch count '${dispatches:-<missing>}' is below $min_dispatches"; rc=1
+    else
+        _info "server evidence: dispatches=$dispatches (>= $min_dispatches) -- OK"
+    fi
+
+    # Per-decoder ring evidence (one ring per decoder in the YAML): decoder 0's
+    # ring must have carried traffic.
+    local ring0
+    ring0=$(sed -n 's/^QEC_DECODING_SERVER_RING decoder=0 dispatched=\([0-9][0-9]*\).*/\1/p' \
+        "$server_log" | tail -n1)
+    if ! [[ "$ring0" =~ ^[0-9]+$ ]] || (( ring0 == 0 )); then
+        _err "ring 0 dispatch count '${ring0:-<missing>}' (expected > 0)"; rc=1
+    else
+        _info "ring evidence: decoder 0 dispatched=$ring0 -- OK"
+    fi
+
+    return $rc
+}
+
+# ============================================================================
+# qpu-kernel source: lowered kernel drives the server over UDP
+# ============================================================================
+run_qpu_kernel() {
+    _banner "Realtime decoding: qpu-kernel source (wire=$WIRE), decoder=$DECODER"
+
+    local server_log; server_log="$GEN_DIR/server.log"
+    _log "Starting decoding_server on the $WIRE wire"
+    # The GPU for nv-qldpc is selected via cuda_device_id in the config (injected
+    # in generate_data), not a server flag.
+    local server_args=(--config="$CONFIG_FILE" --transport="$WIRE_TOKEN" --port=0
+                       --timeout="$TIMEOUT")
+    if [[ "$WIRE" == "cpu_roce" ]]; then
+        # The RDMA ring geometry (slots x slot-size) is part of the cpu_roce
+        # wire contract -- the lowered kernel's channel writes straight into
+        # the server's rings and hardcodes 8 x 256 -- so pin the server to it
+        # explicitly rather than relying on its defaults.
+        server_args+=(--device="$DAEMON_DEVICE" --local-ip="$DAEMON_IP"
+                      --num-slots=8 --slot-size=256)
+    fi
+    "$SERVER_BIN" "${server_args[@]}" >"$server_log" 2>&1 &
+    local spid=$!; PIDS+=("$spid")
+    # trt_decoder builds its TensorRT engine from model.onnx while the server
+    # constructs decoders, delaying READY; give it a longer allowance.
+    local ready_wait=60
+    [[ "$DECODER" == "trt_decoder" ]] && ready_wait=180
+    wait_for_pattern "$server_log" "QEC_DECODING_SERVER_READY" "$ready_wait" "$spid" >/dev/null || {
+        cat "$server_log" >&2; return 1; }
+    # udp: the UDP data port; cpu_roce: the TCP rendezvous port (the RDMA wire
+    # itself is negotiated via the QP/rkey exchange).
+    local port
+    port=$(grep -m1 "QEC_DECODING_SERVER_READY" "$server_log" \
+           | grep -oE 'port=[0-9]+' | head -1 | cut -d= -f2)
+    _info "server ready on the $WIRE wire, port $port (pid $spid)"
+
+    local shots="${NUM_SHOTS:-$QPU_KERNEL_SHOTS}"
+    local kernel_log; kernel_log="$GEN_DIR/kernel.log"
+    _log "Running lowered kernel: $shots shots"
+    # QEC_DECODING_SERVER_PORT routes every decoding device_call to the
+    # external server (the app brings the channel up itself in its
+    # QEC_APP_CQR build).  For cpu_roce the app additionally reads the
+    # transport selector and the channel-side RDMA topology from the env.
+    local kernel_env=(QEC_DECODING_SERVER_PORT="$port")
+    if [[ "$WIRE" == "cpu_roce" ]]; then
+        kernel_env+=(QEC_DECODING_SERVER_TRANSPORT=cpu_roce
+                     CUDAQ_CPU_ROCE_TEST_CHANNEL_DEVICE="$CHANNEL_DEVICE"
+                     CUDAQ_CPU_ROCE_TEST_CHANNEL_IP="$CHANNEL_IP"
+                     CUDAQ_CPU_ROCE_TEST_DAEMON_IP="$DAEMON_IP")
+    fi
+    local kernel_noise_args=(--p_cnot "$GEN_P_CNOT")
+    [[ "$DECODER" == "trt_decoder" ]] && kernel_noise_args=(--p_spam "$GEN_P_SPAM")
+    local rc=0
+    env "${kernel_env[@]}" \
+        "$KERNEL_BIN" --load_dem "$CONFIG_FILE" \
+        --distance "$GEN_DISTANCE" --num_rounds "$GEN_ROUNDS" \
+        "${kernel_noise_args[@]}" --seed "$SEED" \
+        --num_shots "$shots" 2>&1 | tee "$kernel_log" || rc=$?
+    # Stop the server and wait for it to exit so its shutdown stats
+    # (QEC_DECODING_SERVER_DISPATCHED ...) are flushed to the log.
+    kill -TERM "$spid" 2>/dev/null || true
+    wait "$spid" 2>/dev/null || true
+    if (( rc != 0 )); then
+        _err "realtime phase exited with non-zero status ($rc)"
+    fi
+    local vrc=0
+    verify_qpu_kernel_output "$kernel_log" "$server_log" "$shots" || vrc=$?
+    (( rc != 0 )) && return $rc
+    return $vrc
+}
+
+# ============================================================================
+# fpga source: delivered playback streams syndromes over RoCE from a real FPGA
+# (network helpers ported from the unittests hsb_fpga_decoding_server_test.sh)
+# ============================================================================
+
+ib_to_netdev() { ibdev2netdev | awk -v d="$1" -v p="${2:-1}" '$1==d && $3==p {print $5}'; }
+netdev_to_ib() { ibdev2netdev | awk -v i="$1" '$5==i {print $1}'; }
+
+ipv4_to_gid_suffix() {
+    local o1 o2 o3 o4; IFS='.' read -r o1 o2 o3 o4 <<< "$1"
+    printf "ffff:%02x%02x:%02x%02x" "$o1" "$o2" "$o3" "$o4"
+}
+wait_for_roce_v2_gid() {
+    local ib_dev="$1" ip="$2" timeout_s="${3:-15}" suffix gids types elapsed=0
+    suffix=$(ipv4_to_gid_suffix "$ip")
+    gids="/sys/class/infiniband/${ib_dev}/ports/1/gids"
+    types="/sys/class/infiniband/${ib_dev}/ports/1/gid_attrs/types"
+    [[ -d "$gids" ]] || return 0
+    while (( elapsed < timeout_s * 10 )); do
+        local g idx gid t
+        for g in "$gids"/*; do
+            idx=$(basename "$g"); gid=$(cat "$g" 2>/dev/null)
+            if [[ "$gid" == *":${suffix}" ]]; then
+                t=$(cat "${types}/${idx}" 2>/dev/null)
+                [[ "$t" == *"RoCE v2"* ]] && { _info "RoCE v2 GID ready: ${ib_dev}[${idx}]"; return 0; }
+            fi
+        done
+        sleep 0.1; elapsed=$((elapsed + 1))
+    done
+    _err "timed out waiting for RoCE v2 GID (${suffix}) on ${ib_dev}"; return 1
+}
+setup_port() {
+    local iface="$1" ip="$2" mtu="$3" ib_dev
+    _info "Configuring $iface: ip=$ip mtu=$mtu"
+    sudo ip link set "$iface" up
+    sudo ip link set "$iface" mtu "$mtu"
+    sudo ip addr flush dev "$iface"
+    sudo ip addr add "${ip}/24" dev "$iface"
+    ib_dev=$(netdev_to_ib "$iface")
+    if [[ -n "$ib_dev" ]] && command -v rdma &>/dev/null; then
+        local pc; pc=$(ls -d "/sys/class/infiniband/${ib_dev}/ports/"* 2>/dev/null | wc -l)
+        for p in $(seq 1 "$pc"); do sudo rdma link set "${ib_dev}/${p}" type eth || true; done
+    fi
+    command -v mlnx_qos &>/dev/null && sudo mlnx_qos -i "$iface" --trust=dscp 2>/dev/null || true
+    command -v ethtool  &>/dev/null && sudo ethtool -C "$iface" adaptive-rx off rx-usecs 0 2>/dev/null || true
+}
+seed_fpga_neighbor() {
+    local iface="$1" fpga_ip="$2" mac
+    ping -c 3 -W 1 -I "$iface" "$fpga_ip" >/dev/null 2>&1 || true
+    mac=$(ip neigh show "$fpga_ip" dev "$iface" 2>/dev/null \
+          | awk '{for(i=1;i<=NF;i++) if($i=="lladdr") print $(i+1)}' | head -1)
+    if [[ -n "$mac" ]]; then
+        sudo ip neigh replace "$fpga_ip" lladdr "$mac" nud permanent dev "$iface"
+        _info "static ARP: $fpga_ip -> $mac on $iface"
+    else
+        _err "could not resolve FPGA MAC for $fpga_ip on $iface (cabled? powered? ping $fpga_ip)"
+    fi
+}
+
+setup_network() {
+    _log "Setting up ConnectX network for the FPGA"
+    local iface
+    if [[ -n "$IB_DEVICE" ]]; then iface=$(ib_to_netdev "$IB_DEVICE" 1)
+    else iface=$(ibdev2netdev | awk '/\(Up\)/{print $5; exit}'); fi
+    [[ -n "$iface" ]] || { _err "cannot detect a ConnectX interface"; return 1; }
+    _info "server interface: $iface"
+    setup_port "$iface" "$BRIDGE_IP" "$MTU"
+    BRIDGE_DEVICE=$(netdev_to_ib "$iface")
+    wait_for_roce_v2_gid "$BRIDGE_DEVICE" "$BRIDGE_IP" 15 || true
+    seed_fpga_neighbor "$iface" "$FPGA_IP"
+}
+
+# qpu-kernel/cpu_roce network setup: give the channel and daemon ports their
+# RoCE IPv4s and wait for the matching RoCE v2 GIDs (the kernel populates a
+# GID asynchronously after `ip addr add`, and the transceiver's GID lookup
+# loses that race, notably after a cold boot).  Unlike the FPGA path there is
+# no peer to ARP-seed -- the RDMA endpoints cross the TCP rendezvous -- but a
+# stale copy of either IP on another interface would confuse routing, so
+# sweep it off first.
+_setup_roce_port() {
+    local role="$1" ib_dev="$2" ip="$3" iface other
+    iface=$(ib_to_netdev "$ib_dev" 1)
+    [[ -n "$iface" ]] || { _err "no netdev for IB device '$ib_dev' ($role)"; return 1; }
+    for other in $(ls /sys/class/net/ 2>/dev/null); do
+        [[ "$other" != "$iface" ]] && \
+            sudo ip addr del "${ip}/24" dev "$other" 2>/dev/null || true
+    done
+    _info "$role: $ib_dev ($iface) ip=$ip"
+    setup_port "$iface" "$ip" "$MTU"
+    wait_for_roce_v2_gid "$ib_dev" "$ip" 20
+}
+setup_network_cpu_roce() {
+    _log "Setting up the cpu_roce channel + daemon port pair"
+    _setup_roce_port "channel (kernel side)" "$CHANNEL_DEVICE" "$CHANNEL_IP"
+    _setup_roce_port "daemon (server side)"  "$DAEMON_DEVICE"  "$DAEMON_IP"
+
+    # Same-host port pairs never ARP for each other's address: the kernel
+    # routes local IPs via lo and never probes the wire, so the RoCE path
+    # resolution (ibv_modify_qp to RTR) times out with errno=110 unless static
+    # neighbor entries pin each peer IP to the other port's MAC -- the exact
+    # same-host analogue of the FPGA path's seed_fpga_neighbor. Harmless on a
+    # genuine two-host topology (the entries are simply correct there too when
+    # the devices are local; skipped if either netdev is not resolvable).
+    local ch_if dm_if ch_mac dm_mac
+    ch_if=$(ib_to_netdev "$CHANNEL_DEVICE" 1)
+    dm_if=$(ib_to_netdev "$DAEMON_DEVICE" 1)
+    if [[ -n "$ch_if" && -n "$dm_if" ]]; then
+        ch_mac=$(cat "/sys/class/net/$ch_if/address")
+        dm_mac=$(cat "/sys/class/net/$dm_if/address")
+        sudo ip neigh replace "$DAEMON_IP" lladdr "$dm_mac" nud permanent dev "$ch_if"
+        sudo ip neigh replace "$CHANNEL_IP" lladdr "$ch_mac" nud permanent dev "$dm_if"
+        _info "static neighbors: $DAEMON_IP -> $dm_mac on $ch_if; $CHANNEL_IP -> $ch_mac on $dm_if"
+    fi
+}
+
+start_roce_server() {
+    local peer_ip="$1" remote_qp="$2" server_log="$3"
+    _log "Starting decoding_server (wire=$WIRE, dispatch=$DISPATCH, remote-qp=$remote_qp)"
+    local ready
+    if [[ "$DISPATCH" == "device_graph" ]]; then
+        # All-device_graph config: the standalone device-graph transceiver
+        # brings up the wire itself (defaulting to the hololink provider) from
+        # the QEC_DEVICE_GRAPH_* env; no --transport flag is passed.
+        CUDA_MODULE_LOADING=EAGER \
+        QEC_DEVICE_GRAPH_DEVICE="$BRIDGE_DEVICE" \
+        QEC_DEVICE_GRAPH_PEER_IP="$peer_ip" \
+        QEC_DEVICE_GRAPH_REMOTE_QP="$((remote_qp))" \
+        QEC_DEVICE_GRAPH_FRAME_SIZE="$PAGE_SIZE" \
+        QEC_DEVICE_GRAPH_NUM_PAGES="$DEVICE_GRAPH_NUM_PAGES" \
+        "$SERVER_BIN" --config="$CONFIG_FILE" --timeout="$TIMEOUT" \
+            > >(tee "$server_log") 2>&1 &
+        ready="QEC_DECODING_SERVER_READY device_graph"
+    else
+        "$SERVER_BIN" --config="$CONFIG_FILE" --transport="$WIRE_TOKEN" --qp_config=hsb_fpga \
+            --device="$BRIDGE_DEVICE" --peer-ip="$peer_ip" --remote-qp="$remote_qp" \
+            --num-slots="$NUM_SLOTS" --slot-size="$PAGE_SIZE" --frame-size="$FRAME_SIZE" \
+            --timeout="$TIMEOUT" > >(tee "$server_log") 2>&1 &
+        ready="Bridge Ready"
+    fi
+    local spid=$!; PIDS+=("$spid"); SERVER_PID="$spid"
+    wait_for_pattern "$server_log" "$ready" 60 "$spid" >/dev/null || { cat "$server_log" >&2; return 1; }
+    wait_for_pattern "$server_log" "decoder 0 type: ${DECODER}" 5 "$spid" >/dev/null || {
+        _err "server did not construct a '${DECODER}' session"; cat "$server_log" >&2; return 1; }
+    # The RDMA handshake is published as qp=/rkey=/buffer_addr= tokens on ONE
+    # line: the READY line for host dispatch (the bridge provider's endpoint
+    # info rides it), or a dedicated QEC_DECODING_SERVER_ENDPOINT line from
+    # the device-graph transceiver. Scrape whichever arrives.
+    local ep_line
+    ep_line=$(wait_for_pattern "$server_log" "buffer_addr=" 5 "$spid") || return 1
+    SERVER_QP=$(sed -n 's/.*[[:space:]]qp=\([0-9a-fA-FxX]*\).*/\1/p' <<<"$ep_line")
+    SERVER_RKEY=$(sed -n 's/.*[[:space:]]rkey=\([0-9]*\).*/\1/p' <<<"$ep_line")
+    SERVER_ADDR=$(sed -n 's/.*[[:space:]]buffer_addr=\([0-9a-fA-FxX]*\).*/\1/p' <<<"$ep_line")
+    if [[ -z "$SERVER_QP" || -z "$SERVER_RKEY" || -z "$SERVER_ADDR" ]]; then
+        _err "endpoint line missing qp=/rkey=/buffer_addr= tokens: $ep_line"; return 1
+    fi
+    _info "server QP=$SERVER_QP RKey=$SERVER_RKEY Buffer=$SERVER_ADDR"
+}
+
+run_fpga() {
+    _banner "Realtime decoding: fpga source (RoCE), decoder=$DECODER"
+    # The HSB QP has a fixed 64-entry receive WQE depth and the receiver
+    # pre-posts one WQE per ring slot, so a ring with more slots than WQEs
+    # leaves slots un-posted and drops frames under load. Both FPGA paths run
+    # a WQE-depth ring: the cpu_roce wire via NUM_SLOTS (which the server also
+    # clamps), device_graph dispatch via DEVICE_GRAPH_NUM_PAGES here.
+    local HSB_WQE_DEPTH=64
+    local DEVICE_GRAPH_NUM_PAGES="$HSB_WQE_DEPTH"
+    if (( NUM_SLOTS > HSB_WQE_DEPTH )); then
+        _warn "NUM_SLOTS=$NUM_SLOTS exceeds the HSB WQE depth ($HSB_WQE_DEPTH); clamping"
+        NUM_SLOTS="$HSB_WQE_DEPTH"
+    fi
+    if [[ "$DISPATCH" == "device_graph" ]]; then
+        # DOCA requires the device-graph ring allocation (num_pages * page
+        # size) to be a multiple of the HOST page size. 64 x 384 B = 24 KiB
+        # satisfies 4K/8K-page kernels; on 16K/64K-page hosts (some aarch64
+        # configs) the server would reject the ring at startup, so fail fast
+        # with the constraint spelled out.
+        local host_page; host_page=$(getconf PAGESIZE)
+        if (( (DEVICE_GRAPH_NUM_PAGES * PAGE_SIZE) % host_page != 0 )); then
+            _err "device_graph ring ($DEVICE_GRAPH_NUM_PAGES slots x $PAGE_SIZE B) is not a multiple of this host's page size ($host_page B)."
+            _err "The HSB frame stride must be a multiple of $(( host_page / HSB_WQE_DEPTH )) B on this host; see the unittests"
+            _err "hsb_fpga_decoding_server_test.sh (--page-size) for a tunable-geometry run."
+            exit 1
+        fi
+    fi
+    : "${BRIDGE_DEVICE:=${IB_DEVICE:-rocep1s0f0}}"
+
+    local server_log="$GEN_DIR/server.log"
+    start_roce_server "$FPGA_IP" "0x2" "$server_log" || return 1
+
+    _log "Streaming syndromes from the FPGA via playback (spacing=${SPACING}us)"
+    # The FPGA writes syndrome frame rid to RDMA slot (rid % num-pages), so the
+    # playback ring modulus MUST equal the server's RX ring depth. Otherwise
+    # frames past one ring land outside the server's registered memory region
+    # and are silently lost, and the server starves after exactly one ring
+    # (num_slots). The cpu_roce wire's server ring is NUM_SLOTS; the
+    # device_graph ring is DEVICE_GRAPH_NUM_PAGES.
+    local pb_pages="$NUM_SLOTS"
+    if [[ "$DISPATCH" == "device_graph" ]]; then pb_pages="$DEVICE_GRAPH_NUM_PAGES"; fi
+    local args=( --hololink "$FPGA_IP" --per-round --config "$CONFIG_FILE"
+        --syndromes "$SYNDROMES_FILE" --qp-number "$SERVER_QP" --rkey "$SERVER_RKEY"
+        --buffer-addr "$SERVER_ADDR" --page-size "$PAGE_SIZE" --num-pages "$pb_pages" )
+    $VERIFY && args+=(--verify)
+    [[ -n "$NUM_SHOTS" ]] && args+=(--num-shots "$NUM_SHOTS")
+    [[ -n "$SPACING"   ]] && args+=(--spacing "$SPACING")
+    local rc=0
+    "$PLAYBACK_BIN" "${args[@]}" || rc=$?
+    kill -TERM "$SERVER_PID" 2>/dev/null || true; sleep 0.3
+    return $rc
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+main() {
+    _banner "Realtime Decoding Demo"
+    _info "source=$SOURCE  decoder=$DECODER  wire=$WIRE  dispatch=$DISPATCH"
+
+    resolve_paths
+    if $DO_SETUP_NETWORK; then
+        if [[ "$SOURCE" == "fpga" ]]; then setup_network
+        elif [[ "$SOURCE" == "qpu-kernel" && "$WIRE" == "cpu_roce" ]]; then
+            setup_network_cpu_roce
+        fi
+    fi
+    generate_data
+
+    local rc=0
+    if [[ "$SOURCE" == "qpu-kernel" ]]; then run_qpu_kernel || rc=$?
+    else run_fpga || rc=$?; fi
+
+    echo
+    if [[ $rc -eq 0 ]]; then _banner "REALTIME DECODING ($SOURCE / $DECODER): PASS"
+    else _banner "REALTIME DECODING ($SOURCE / $DECODER): FAIL"; fi
+    return $rc
+}
+main
diff --git a/docs/sphinx/examples/qec/realtime_decoding_demo/surface_code_ising_realtime_decoding.cpp b/docs/sphinx/examples/qec/realtime_decoding_demo/surface_code_ising_realtime_decoding.cpp
new file mode 100644
index 000000000..eba53fbf5
--- /dev/null
+++ b/docs/sphinx/examples/qec/realtime_decoding_demo/surface_code_ising_realtime_decoding.cpp
@@ -0,0 +1,1653 @@
+/*******************************************************************************
+ * Copyright (c) 2026 NVIDIA Corporation & Affiliates.                         *
+ * All rights reserved.                                                        *
+ *                                                                             *
+ * This source code and the accompanying materials are made available under    *
+ * the terms of the Apache License 2.0 which accompanies this distribution.    *
+ ******************************************************************************/
+
+// surface_code_ising_realtime_decoding.cpp
+//
+// Companion source to surface_code_realtime_decoding.cpp, dedicated to the
+// Ising decoder profile: a TensorRT neural-network predecoder plus a
+// PyMatching global decoder (decoder type `trt_decoder`), configured from a
+// locally prepared Ising artifact directory.
+//
+// This app follows the surface_code-4 lineage rather than the surface_code-1
+// lineage of its sibling, because the Ising model's artifacts are bound to
+// that lineage's conventions:
+//   - code orientation XV (the predecoder's training orientation),
+//   - per-round measurement layout [X-ancillas..., Z-ancillas...],
+//   - SPAM (single-qubit depolarizing) noise at the model's trained operating
+//     point (p_spam = 0.01 for the published d7/T7 checkpoint).
+// DO NOT reorder the measurement/enqueue schedule in the kernels below: the
+// artifact directory's D_sparse.txt maps Ising detector rows onto THIS exact
+// live measurement stream.
+//
+// The artifact directory (--ising-artifacts-dir, or QEC_ISING_ARTIFACTS_DIR)
+// holds six files, none of which ship with CUDA-QX:
+//   model.onnx    the exported Ising predecoder (from the gated Hugging Face
+//                 SafeTensors checkpoint via the NVIDIA/Ising-Decoding repo)
+//   H_csr.bin     detector-error matrix, Ising detector order (binary CSR)
+//   O_csr.bin     observables-flips matrix (binary CSR)
+//   priors.bin    per-error-mechanism priors (error_rate_vec)
+//   metadata.txt  key=value contract: basis=Z, code_rotation=XV, distance,
+//                 n_rounds
+//   D_sparse.txt  each Ising detector as a parity over THIS app's live
+//                 measurement buffer (generated with the shipped
+//                 prepare_ising_artifacts.py from this app's printed
+//                 CNOT schedules)
+// See the example documentation for the full preparation recipe.
+//
+// Two build variants (see CMakeLists.txt):
+//   surface_code_ising_realtime_decoding      generator: writes the decoder
+//       config YAML (--save_dem) embedding the Ising matrices + ONNX path,
+//       and captures/replays syndrome files (--save_syndrome/--load_syndrome).
+//   surface_code_ising_realtime_decoding-cqr  lowered kernel
+//       (-frealtime-lowering -DQEC_APP_CQR): streams the live syndromes to
+//       the delivered decoding_server over udp or cpu_roce.
+
+#include "cudaq.h"
+#include "cudaq/qec/code.h"
+#include "cudaq/qec/codes/surface_code.h"
+#include "cudaq/qec/decoder.h"
+#include "cudaq/qec/experiments.h"
+#include "cudaq/qec/pcm_utils.h"
+#include "cudaq/qec/realtime/decoding.h"
+#include "cudaq/qec/realtime/decoding_config.h"
+#ifdef QEC_APP_CQR
+#include "cudaq/realtime.h"
+#endif
+#include <algorithm>
+#include <cmath>
+#include <common/NoiseModel.h>
+#include <cstdint>
+#include <cstdlib>
+#include <cudaq/algorithms/dem.h>
+#include <fstream>
+#include <mutex>
+#include <sstream>
+#include <vector>
+
+namespace {
+std::string env_or(const char *name, const std::string &fallback) {
+  const char *value = std::getenv(name);
+  return (value && *value) ? std::string(value) : fallback;
+}
+} // namespace
+
+#ifdef QEC_APP_CQR
+// cqr build variant: this same application compiled with -frealtime-lowering
+// and linked against the simulation-cqr client wrappers, so every
+// cudaq::qec::decoding::* device_call crosses the cudaq-realtime wire to a
+// standalone decoding_server (QEC_DECODING_SERVER_PORT=<port>). The wire
+// defaults to udp loopback; set QEC_DECODING_SERVER_TRANSPORT=cpu_roce to use
+// the CPU RoCE RDMA channel instead (works over loopback-cabled ConnectX ports
+// or SoftRoCE/rdma_rxe; the RDMA topology comes from the same
+// CUDAQ_CPU_ROCE_TEST_* env vars as CUDA-Q's CpuRoceChannelTester).
+
+// In-process service self-check hook (defined in decoding-server-cqr):
+// non-zero only if device_calls actually traversed the host-dispatch ring.
+extern "C" std::uint64_t cudaqx_qec_device_call_dispatch_count();
+
+namespace {
+
+class realtime_channel_guard {
+public:
+  realtime_channel_guard() = default;
+  realtime_channel_guard(const realtime_channel_guard &) = delete;
+  realtime_channel_guard &operator=(const realtime_channel_guard &) = delete;
+
+  ~realtime_channel_guard() {
+    if (active_)
+      cudaq::realtime::finalize();
+  }
+
+  void initialize(const char *program) {
+    const char *port = std::getenv("QEC_DECODING_SERVER_PORT");
+    if (!port || port[0] == '\0')
+      throw std::runtime_error(
+          "QEC_DECODING_SERVER_PORT is required for external decoding");
+
+    std::vector<std::string> args = {program};
+    const std::string transport =
+        env_or("QEC_DECODING_SERVER_TRANSPORT", "udp");
+    if (transport == "cpu_roce") {
+      // The RDMA ring geometry (slots x slot-size) is part of the cpu_roce
+      // wire contract: the channel writes requests directly into the server's
+      // rings, so these must match decoding_server's --num-slots /
+      // --slot-size defaults (8 x 256).
+      args.push_back("--cudaq-device-call=cpu_roce");
+      args.push_back("--cudaq-device-call-slots=8");
+      args.push_back("--cudaq-device-call-slot-size=256");
+      args.push_back("ib-device=" +
+                     env_or("CUDAQ_CPU_ROCE_TEST_CHANNEL_DEVICE", "mlx5_0"));
+      args.push_back("local-ip=" +
+                     env_or("CUDAQ_CPU_ROCE_TEST_CHANNEL_IP", "10.0.0.1"));
+      args.push_back("rendezvous-host=" +
+                     env_or("CUDAQ_CPU_ROCE_TEST_DAEMON_IP", "10.0.0.2"));
+      args.push_back(std::string("rendezvous-port=") + port);
+    } else {
+      args.push_back("--cudaq-device-call=udp");
+      args.push_back("udp-host=127.0.0.1");
+      args.push_back(std::string("udp-port=") + port);
+    }
+    std::vector<char *> argv;
+    argv.reserve(args.size() + 1);
+    for (auto &arg : args)
+      argv.push_back(arg.data());
+    argv.push_back(nullptr);
+    int argc = static_cast<int>(args.size());
+    cudaq::realtime::initialize(argc, argv.data());
+    active_ = true;
+  }
+
+private:
+  bool active_ = false;
+};
+
+} // namespace
+#endif
+
+// Host-side decoding API (for syndrome capture)
+namespace cudaq::qec::decoding::host {
+void _set_syndrome_capture_callback(void (*callback)(const uint8_t *, size_t));
+}
+
+// Global syndrome capture state for --save_syndrome option.
+//
+// The live path enqueues a HETEROGENEOUS stream per shot: `num_rounds` uniform
+// syndrome rounds of `g_syndrome_bits_per_round` bits each (the prep round plus
+// the num_rounds-1 paired rounds), followed by ONE final DATA round of
+// `g_data_bits` bits (numData). The capture callback fires once per enqueue, in
+// chronological order, so it uses the per-shot enqueue index
+// (g_syndrome_count % g_enqueues_per_shot) to decide how many bits to record:
+// the syndrome rounds emit g_syndrome_bits_per_round, the last enqueue emits
+// g_data_bits.
+static std::ofstream g_syndrome_output_file;
+static std::mutex g_syndrome_file_mutex;
+static int g_syndrome_count = 0;
+static int g_enqueues_per_shot = 0;
+static int g_syndrome_bits_per_round = 0;
+static int g_data_bits = 0;
+
+// ---------------------------------------------------------------------------
+// Ising artifact interop (trt_decoder path)
+//
+// The Ising d/T/Z artifacts (generate_test_data.py) ship H_csr.bin/O_csr.bin/
+// priors.bin in *Ising detector order*, plus a D_sparse.txt we generate that
+// expresses each Ising detector as a parity over the *cudaqx* live measurement
+// buffer. With these, the trt+Ising config carries Ising's exact H/O/priors and
+// a D_sparse aligned to Ising's detector rows while reading the cudaqx stream.
+//
+// Geometry: cudaqx's surface code at orientation XV is identical to the Ising
+// geometry (Ising code_rotation string "XV" == first_bulk X, rotated_type V,
+// logical_direction XH) under the IDENTITY data and X-ancilla mapping; only the
+// Z-ancillas are permuted (a fixed bijection). D_sparse.txt encodes exactly
+// that: it takes Ising's detector->measurement map and translates each
+// measurement index from Ising's buffer order into cudaqx's buffer order
+// (X-ancilla and data identity, Z-ancilla permuted), so every D row reproduces
+// one of cudaqx's own detector bits, now in Ising's detector order.
+// ---------------------------------------------------------------------------
+
+// The six files every prepared artifact directory must contain. Checked up
+// front so a partial preparation fails with the complete list of gaps instead
+// of a low-level read error.
+static void require_ising_artifact_files(const std::string &dir) {
+  const char *required[] = {"model.onnx", "H_csr.bin",    "O_csr.bin",
+                            "priors.bin", "metadata.txt", "D_sparse.txt"};
+  std::string missing;
+  for (const char *name : required) {
+    std::ifstream f(dir + "/" + name, std::ios::binary);
+    if (!f || f.peek() == std::ifstream::traits_type::eof())
+      missing += std::string(" ") + name;
+  }
+  if (!missing.empty())
+    throw std::runtime_error(
+        "Ising artifact directory '" + dir +
+        "' is incomplete; missing or empty:" + missing +
+        " (see the realtime_decoding_demo documentation for the "
+        "preparation recipe)");
+}
+
+// Read a binary-CSR file (rows:u32, cols:u32, nnz:u32, indptr[(rows+1)*i32],
+// indices[nnz*i32]) and return it as a -1-terminated sparse row vector
+// (each row lists its non-zero column indices, terminated by -1) -- exactly the
+// shape pcm_to_sparse_vec produces. Also returns the row/col counts.
+static std::vector<std::int64_t>
+read_csr_bin_to_sparse_vec(const std::string &path, std::uint32_t &rows,
+                           std::uint32_t &cols) {
+  std::ifstream f(path, std::ios::binary);
+  if (!f)
+    throw std::runtime_error("Could not open Ising CSR file: " + path);
+  std::uint32_t nnz = 0;
+  f.read(reinterpret_cast<char *>(&rows), sizeof(rows));
+  f.read(reinterpret_cast<char *>(&cols), sizeof(cols));
+  f.read(reinterpret_cast<char *>(&nnz), sizeof(nnz));
+  std::vector<std::int32_t> indptr(rows + 1), indices(nnz);
+  f.read(reinterpret_cast<char *>(indptr.data()),
+         static_cast<std::streamsize>(indptr.size() * sizeof(std::int32_t)));
+  f.read(reinterpret_cast<char *>(indices.data()),
+         static_cast<std::streamsize>(indices.size() * sizeof(std::int32_t)));
+  if (!f)
+    throw std::runtime_error("Truncated Ising CSR file: " + path);
+  std::vector<std::int64_t> sparse;
+  for (std::uint32_t r = 0; r < rows; ++r) {
+    for (std::int32_t k = indptr[r]; k < indptr[r + 1]; ++k)
+      sparse.push_back(static_cast<std::int64_t>(indices[k]));
+    sparse.push_back(-1);
+  }
+  return sparse;
+}
+
+// Read priors.bin (n:u32, n*float64) -> error_rate_vec.
+static std::vector<double> read_priors_bin(const std::string &path) {
+  std::ifstream f(path, std::ios::binary);
+  if (!f)
+    throw std::runtime_error("Could not open Ising priors file: " + path);
+  std::uint32_t n = 0;
+  f.read(reinterpret_cast<char *>(&n), sizeof(n));
+  std::vector<double> priors(n);
+  f.read(reinterpret_cast<char *>(priors.data()),
+         static_cast<std::streamsize>(priors.size() * sizeof(double)));
+  if (!f)
+    throw std::runtime_error("Truncated Ising priors file: " + path);
+  return priors;
+}
+
+// Read D_sparse.txt -- a whitespace-separated, -1-terminated sparse detector
+// matrix. One row per Ising detector; entries are cudaqx live-buffer
+// measurement indices (so each row reproduces a cudaqx detector bit, in Ising's
+// detector order). Returns the flat -1-terminated vector and the row count.
+static std::vector<std::int64_t> read_D_sparse_txt(const std::string &path,
+                                                   std::size_t &numRows) {
+  std::ifstream f(path);
+  if (!f)
+    throw std::runtime_error("Could not open Ising D_sparse.txt file: " + path);
+  std::vector<std::int64_t> D;
+  std::int64_t v;
+  numRows = 0;
+  while (f >> v) {
+    D.push_back(v);
+    if (v == -1)
+      ++numRows;
+  }
+  return D;
+}
+
+// Read the artifact directory's metadata.txt (key=value lines) and enforce
+// that it matches THIS experiment: basis Z, code_rotation XV, and the same
+// distance / n_rounds. This is the semantic guard the dimensional checks
+// cannot provide -- so the artifacts' basis and orientation match the
+// experiment.
+static void enforce_ising_metadata(const std::string &bundle, int distance,
+                                   std::size_t numRounds) {
+  std::ifstream f(bundle + "/metadata.txt");
+  if (!f)
+    throw std::runtime_error("Ising artifacts missing metadata.txt: " + bundle +
+                             "/metadata.txt");
+  std::vector<std::pair<std::string, std::string>> kv;
+  std::string line;
+  while (std::getline(f, line)) {
+    while (!line.empty() && (line.back() == '\r' || line.back() == ' '))
+      line.pop_back();
+    auto eq = line.find('=');
+    if (eq != std::string::npos)
+      kv.emplace_back(line.substr(0, eq), line.substr(eq + 1));
+  }
+  auto require = [&](const std::string &key, const std::string &want) {
+    for (const auto &p : kv)
+      if (p.first == key) {
+        if (p.second != want)
+          throw std::runtime_error("Ising artifacts " + bundle +
+                                   ": metadata.txt " + key + "='" + p.second +
+                                   "' != required '" + want + "'");
+        return;
+      }
+    throw std::runtime_error("Ising artifacts " + bundle +
+                             ": metadata.txt missing key '" + key + "'");
+  };
+  require("basis", "Z");
+  require("code_rotation", "XV");
+  require("distance", std::to_string(distance));
+  require("n_rounds", std::to_string(numRounds));
+}
+
+// Flatten cudaqx's m2d into the -1-terminated sparse detector matrix, in
+// cudaqx detector order (D_sparse[i] == m2d.rows[i]). This is the
+// self-consistent D for the cudaqx-native pymatching entry, which carries
+// cudaqx's own dem_gen_circuit H/O. It references the same chronological
+// measurement indices the live path enqueues (385 bits for d7/T7), including
+// the final 49 data measurements used by the boundary detectors.
+static std::vector<std::int64_t>
+build_cudaqx_D_sparse(const cudaq::M2DSparseMatrix &m2d) {
+  std::vector<std::int64_t> D;
+  for (const auto &row : m2d.rows) {
+    for (auto meas : row)
+      D.push_back(static_cast<std::int64_t>(meas));
+    D.push_back(-1);
+  }
+  return D;
+}
+
+// Write the single-decoder config. `pymatching` carries cudaqx's own DEM;
+// `trt_decoder` carries the Ising artifacts: H/O/priors in Ising detector
+// order plus the Ising-ordered D_sparse over the cudaqx live buffer, and the
+// ONNX predecoder path (<artifacts>/model.onnx) so the decoding server's TRT
+// plugin builds its engine from the same model after reload.
+void save_dem_to_file(const std::vector<cudaq::qec::detector_error_model> &dems,
+                      std::string dem_filename,
+                      const std::vector<std::string> &decoder_types,
+                      const cudaq::M2DSparseMatrix &m2d,
+                      const std::string &ising_artifacts_dir, int distance,
+                      std::size_t numRounds) {
+  cudaq::qec::decoding::config::multi_decoder_config multi_config;
+  for (uint64_t i = 0; i < decoder_types.size(); i++) {
+    const std::string &decoder_type = decoder_types[i];
+    const auto &edem = dems[i];
+    cudaq::qec::decoding::config::decoder_config config;
+    config.id = i;
+    config.type = decoder_type;
+    config.block_size = edem.num_error_mechanisms();
+    config.syndrome_size = edem.num_detectors();
+    config.H_sparse = cudaq::qec::pcm_to_sparse_vec(edem.detector_error_matrix);
+    config.O_sparse =
+        cudaq::qec::pcm_to_sparse_vec(edem.observables_flips_matrix);
+    // Default D == cudaqx's m2d (cudaqx detector order), self-consistent with
+    // the dem_gen_circuit H/O above and with the full measurement stream the
+    // live path enqueues. The trt+Ising branch below overrides this with the
+    // Ising-ordered D_sparse.txt to match the Ising H/O.
+    config.D_sparse = build_cudaqx_D_sparse(m2d);
+
+    if (decoder_type == "pymatching") {
+      cudaqx::heterogeneous_map pm_args;
+      pm_args.insert("merge_strategy", "smallest_weight");
+      pm_args.insert("error_rate_vec", edem.error_rates);
+      config.decoder_custom_args = pm_args;
+    } else if (decoder_type == "trt_decoder") {
+      if (ising_artifacts_dir.empty())
+        throw std::runtime_error(
+            "trt_decoder requires an Ising artifact directory "
+            "(--ising-artifacts-dir or QEC_ISING_ARTIFACTS_DIR)");
+      // Enforce the artifacts' semantics match this experiment (basis Z,
+      // code_rotation XV, same d / n_rounds) before trusting the matrices.
+      require_ising_artifact_files(ising_artifacts_dir);
+      enforce_ising_metadata(ising_artifacts_dir, distance, numRounds);
+
+      cudaqx::heterogeneous_map trt_args;
+      // The TensorRT predecoder model is supplied through the saved decoder
+      // config so the same ONNX path is used after reload.
+      trt_args.insert("onnx_load_path", ising_artifacts_dir + "/model.onnx");
+      trt_args.insert("batch_size", std::size_t{1});
+      trt_args.insert("use_cuda_graph", true);
+      trt_args.insert("global_decoder", "pymatching");
+
+      cudaqx::heterogeneous_map pm_args;
+      pm_args.insert("merge_strategy", "smallest_weight");
+
+      // trt+Ising path: carry the Ising d/T/Z model. H/O/priors come from
+      // the artifacts (Ising detector order); D_sparse (D_sparse.txt)
+      // expresses each Ising detector as a parity over the cudaqx live
+      // measurement buffer, so the live stream feeds Ising's detectors in
+      // Ising's row order.
+      std::uint32_t hRows = 0, hCols = 0, oRows = 0, oCols = 0;
+      config.H_sparse = read_csr_bin_to_sparse_vec(
+          ising_artifacts_dir + "/H_csr.bin", hRows, hCols);
+      config.O_sparse = read_csr_bin_to_sparse_vec(
+          ising_artifacts_dir + "/O_csr.bin", oRows, oCols);
+      auto priors = read_priors_bin(ising_artifacts_dir + "/priors.bin");
+      std::size_t dRows = 0;
+      config.D_sparse =
+          read_D_sparse_txt(ising_artifacts_dir + "/D_sparse.txt", dRows);
+
+      if (hRows != m2d.rows.size())
+        throw std::runtime_error("Ising H rows (" + std::to_string(hRows) +
+                                 ") != cudaqx m2d detectors (" +
+                                 std::to_string(m2d.rows.size()) + ")");
+      if (dRows != m2d.rows.size())
+        throw std::runtime_error("D_sparse.txt rows (" + std::to_string(dRows) +
+                                 ") != cudaqx m2d detectors (" +
+                                 std::to_string(m2d.rows.size()) + ")");
+      if (hCols != oCols || hCols != priors.size())
+        throw std::runtime_error("Ising H/O/priors column counts disagree");
+
+      config.syndrome_size = hRows;
+      config.block_size = hCols;
+      pm_args.insert("error_rate_vec", priors);
+      printf("trt+Ising: loaded Ising artifacts '%s' (H %ux%u, O %u rows, "
+             "priors %zu); D_sparse from D_sparse.txt (%zu detectors)\n",
+             ising_artifacts_dir.c_str(), hRows, hCols, oRows, priors.size(),
+             dRows);
+      trt_args.insert("global_decoder_params", pm_args);
+
+      config.decoder_custom_args = trt_args;
+    }
+
+    multi_config.decoders.push_back(config);
+  }
+  std::string config_str = multi_config.to_yaml_str(200);
+  std::ofstream config_file(dem_filename);
+  config_file << config_str;
+  config_file.close();
+  if (!config_file)
+    throw std::runtime_error("failed to write decoder config: " + dem_filename);
+  std::string types_str;
+  for (std::size_t i = 0; i < decoder_types.size(); ++i)
+    types_str += (i ? "," : "") + decoder_types[i];
+  printf("Saved %s config to file: %s\n", types_str.c_str(),
+         dem_filename.c_str());
+  return;
+}
+
+// Parse and validate a saved decoder config: geometry guards, per-id types,
+// and the reconstructed DEM. Does NOT construct decoders -- instantiation is
+// the serving side's job (this process for in-process serving; the decoding
+// server for a server-served run).
+cudaq::qec::decoding::config::multi_decoder_config
+load_decoder_config(const std::string &dem_filename,
+                    cudaq::qec::detector_error_model &dem, uint64_t numLogical,
+                    uint64_t &measSpan,
+                    std::vector<std::string> &decoder_types_out) {
+  printf("load_decoder_config: Loading dem from file: %s\n",
+         dem_filename.c_str());
+  // Read dem_filename into a std::string
+  std::ifstream dem_file(dem_filename);
+  if (!dem_file)
+    throw std::runtime_error("could not open decoder config file: " +
+                             dem_filename);
+  std::string dem_str((std::istreambuf_iterator<char>(dem_file)),
+                      std::istreambuf_iterator<char>());
+  auto config =
+      cudaq::qec::decoding::config::multi_decoder_config::from_yaml_str(
+          dem_str);
+  if (numLogical != config.decoders.size())
+    throw std::runtime_error("numLogical [" + std::to_string(numLogical) +
+                             "] != config.decoders.size() [" +
+                             std::to_string(config.decoders.size()) + "]");
+  auto span_of = [](const std::vector<std::int64_t> &sparse) {
+    std::int64_t m = -1;
+    for (auto v : sparse)
+      if (v > m)
+        m = v;
+    return static_cast<uint64_t>(m + 1);
+  };
+  const auto &d0 = config.decoders[0];
+  const uint64_t span0 = span_of(d0.D_sparse);
+  decoder_types_out.assign(config.decoders.size(), std::string());
+  for (size_t k = 0; k < config.decoders.size(); ++k) {
+    const auto &dc = config.decoders[k];
+    if (dc.id < 0 || static_cast<size_t>(dc.id) >= config.decoders.size() ||
+        !decoder_types_out[dc.id].empty())
+      throw std::runtime_error(
+          "loaded config decoder ids must be unique and dense in [0, " +
+          std::to_string(config.decoders.size()) + "); entry " +
+          std::to_string(k) + " has id " + std::to_string(dc.id));
+    decoder_types_out[dc.id] = dc.type;
+    const size_t nobs = std::count(dc.O_sparse.begin(), dc.O_sparse.end(), -1);
+    if (nobs != 1)
+      throw std::runtime_error(
+          "loaded config decoder " + std::to_string(k) + " has " +
+          std::to_string(nobs) +
+          " observables; expected 1 (one observable per single-patch "
+          "surface-code decoder)");
+    if (dc.syndrome_size != d0.syndrome_size || span_of(dc.D_sparse) != span0)
+      throw std::runtime_error(
+          "loaded config decoder " + std::to_string(k) +
+          " geometry (detectors " + std::to_string(dc.syndrome_size) +
+          ", measurement span " + std::to_string(span_of(dc.D_sparse)) +
+          ") differs from decoder 0 (detectors " +
+          std::to_string(d0.syndrome_size) + ", span " + std::to_string(span0) +
+          "); all decoders must share one experiment geometry");
+  }
+
+  auto decoder_config = d0;
+  dem.detector_error_matrix = cudaq::qec::pcm_from_sparse_vec(
+      decoder_config.H_sparse, decoder_config.syndrome_size,
+      decoder_config.block_size);
+  size_t num_observables = std::count(decoder_config.O_sparse.begin(),
+                                      decoder_config.O_sparse.end(), -1);
+  dem.observables_flips_matrix = cudaq::qec::pcm_from_sparse_vec(
+      decoder_config.O_sparse, num_observables, decoder_config.block_size);
+  // The runtime decodes once the enqueued measurement buffer is full; that span
+  // is max(D_sparse)+1. Surface it so the caller can bind the config to this
+  // experiment's geometry (see the load_dem check in demo_circuit_host).
+  measSpan = span0;
+
+  std::string types_str;
+  for (std::size_t i = 0; i < decoder_types_out.size(); ++i)
+    types_str += (i ? "," : "") + decoder_types_out[i];
+  printf("Loaded %s config from file: %s\n", types_str.c_str(),
+         dem_filename.c_str());
+  return config;
+}
+
+std::vector<size_t> get_stab_cnot_schedule(char stab_type, int distance) {
+  // Build the stabilizer CNOT schedule from an XV-oriented grid (the
+  // predecoder's training orientation).
+  cudaq::qec::surface_code::stabilizer_grid grid(
+      distance, cudaq::qec::surface_code::sc_orientation::XV);
+  if (stab_type != 'X' && stab_type != 'Z') {
+    throw std::runtime_error(
+        "get_stab_cnot_schedule: Invalid stabilizer type. Must be 'X' or 'Z'.");
+  }
+  // CNOT pairs ordered by timestep within each stabilizer, so that mid-round
+  // ancilla (hook) errors land perpendicular to the logical operators.
+  // Stabilizer indices match the sorted parity-matrix rows and hence the
+  // ancilla indexing.
+  return stab_type == 'X' ? grid.get_cnot_schedule_pairs_x()
+                          : grid.get_cnot_schedule_pairs_z();
+}
+
+// Per-stabilizer data-qubit supports, ordered to match the ancilla measurement
+// order produced by get_stab_cnot_schedule(stab_type, ...). The supports are
+// derived from the same schedule matrix as the CNOT pairs (row s = ancilla s),
+// so support[s] lines up with ancilla[s] in the extraction kernels'
+// measurement vector by construction rather than via a parallel sort. This is
+// what the Ising MemoryCircuit boundary detectors pair against (a stabilizer's
+// data support XOR-ed with that stabilizer's last ancilla measurement).
+// Returns a flat vector of data-qubit indices plus per-stabilizer offsets
+// (offsets has size num_stabs+1; support s spans [offsets[s], offsets[s+1])),
+// the same flat+offset pattern as cnot_schedZ_flat.
+void get_stab_data_supports(char stab_type, int distance,
+                            std::vector<std::size_t> &supports_flat,
+                            std::vector<std::size_t> &supports_offsets) {
+  cudaq::qec::surface_code::stabilizer_grid grid(
+      distance, cudaq::qec::surface_code::sc_orientation::XV);
+  if (stab_type != 'X' && stab_type != 'Z') {
+    throw std::runtime_error(
+        "get_stab_data_supports: Invalid stabilizer type. Must be 'X' or 'Z'.");
+  }
+  auto sched = stab_type == 'X' ? grid.get_cnot_schedule_x()
+                                : grid.get_cnot_schedule_z();
+  supports_flat.clear();
+  supports_offsets.clear();
+  supports_offsets.push_back(0);
+  for (std::size_t s = 0; s < sched.shape()[0]; ++s) {
+    for (std::size_t d = 0; d < sched.shape()[1]; ++d) {
+      if (sched.at({s, d}) != 0)
+        supports_flat.push_back(d);
+    }
+    supports_offsets.push_back(supports_flat.size());
+  }
+}
+
+namespace cudaq::qec::qpu {
+
+__qpu__ void spam_error(cudaq::qec::patch logicalQubit, double p_spam_data,
+                        double p_spam_ancx, double p_spam_ancz) {
+  for (std::size_t i = 0; i < logicalQubit.data.size(); i++) {
+    cudaq::apply_noise<cudaq::depolarization1>(p_spam_data,
+                                               logicalQubit.data[i]);
+  }
+  for (std::size_t i = 0; i < logicalQubit.ancx.size(); i++) {
+    cudaq::apply_noise<cudaq::depolarization1>(p_spam_ancx,
+                                               logicalQubit.ancx[i]);
+  }
+  for (std::size_t i = 0; i < logicalQubit.ancz.size(); i++) {
+    cudaq::apply_noise<cudaq::depolarization1>(p_spam_ancz,
+                                               logicalQubit.ancz[i]);
+  }
+}
+
+__qpu__ std::vector<cudaq::measure_result>
+extract_z_syndrome(cudaq::qec::patch logicalQubit,
+                   const std::vector<std::size_t> &cnot_sched) {
+  for (std::size_t i = 0; i < cnot_sched.size(); i += 2) {
+    cudaq::x<cudaq::ctrl>(logicalQubit.data[cnot_sched[i + 1]],
+                          logicalQubit.ancz[cnot_sched[i]]);
+  }
+  auto results = mz(logicalQubit.ancz);
+  for (std::size_t i = 0; i < logicalQubit.ancz.size(); i++)
+    reset(logicalQubit.ancz[i]);
+  return results;
+}
+
+__qpu__ std::vector<cudaq::measure_result>
+extract_x_syndrome(cudaq::qec::patch logicalQubit,
+                   const std::vector<std::size_t> &cnot_sched) {
+  h(logicalQubit.ancx);
+  for (std::size_t i = 0; i < cnot_sched.size(); i += 2) {
+    cudaq::x<cudaq::ctrl>(logicalQubit.ancx[cnot_sched[i]],
+                          logicalQubit.data[cnot_sched[i + 1]]);
+  }
+  h(logicalQubit.ancx);
+  auto results = mz(logicalQubit.ancx);
+  for (std::size_t i = 0; i < logicalQubit.ancx.size(); i++)
+    reset(logicalQubit.ancx[i]);
+  return results;
+}
+
+__qpu__ void
+measure_syndrome_round(cudaq::qec::patch logicalQubit,
+                       const std::vector<std::size_t> &cnot_schedX_flat,
+                       const std::vector<std::size_t> &cnot_schedZ_flat,
+                       std::vector<cudaq::measure_result> &combined_syndrome) {
+  // Measure X-ancillas then Z-ancillas (combined layout [X..., Z...]). The
+  // shared helper keeps the DEM and the live enqueue path on the same ordering.
+  auto syndrome_x = extract_x_syndrome(logicalQubit, cnot_schedX_flat);
+  auto syndrome_z = extract_z_syndrome(logicalQubit, cnot_schedZ_flat);
+  int i = 0;
+  for (auto s : syndrome_x)
+    combined_syndrome[i++] = s;
+  for (auto s : syndrome_z)
+    combined_syndrome[i++] = s;
+}
+
+// Run ONE syndrome-extraction round on one patch and (optionally) enqueue it
+// to that patch's decoder. The round loop lives in demo_circuit_qpu so the
+// patches can be interleaved round-major. round_counter is the per-patch
+// monotonic enqueue index (0 = lock-in, 1..T-1 paired, T = data round):
+// logging-only on the in-process path, the round counter on the
+// decoding-server wire.
+__qpu__ void
+syndrome_round_once(cudaq::qview<> data, cudaq::qview<> xstab_anc,
+                    cudaq::qview<> zstab_anc,
+                    const std::vector<std::size_t> &cnot_schedX_flat,
+                    const std::vector<std::size_t> &cnot_schedZ_flat,
+                    bool do_spam, double p_spam, bool do_enqueue,
+                    int logical_qubit_idx, std::uint64_t round_counter) {
+  patch logical(data, xstab_anc, zstab_anc);
+  std::vector<cudaq::measure_result> combined_syndrome(xstab_anc.size() +
+                                                       zstab_anc.size());
+  // Inject errors BEFORE the measurement, matching the DEM kernel's
+  // spam-then-measure placement.
+  if (do_spam)
+    spam_error(logical, p_spam, 0.0, 0.0);
+  measure_syndrome_round(logical, cnot_schedX_flat, cnot_schedZ_flat,
+                         combined_syndrome);
+  if (do_enqueue)
+    cudaq::qec::decoding::enqueue_syndromes(
+        /*decoder_id=*/logical_qubit_idx, combined_syndrome, round_counter);
+}
+
+__qpu__ std::vector<std::uint64_t> demo_circuit_qpu(
+    bool allow_device_calls,
+    const cudaq::qec::code::one_qubit_encoding &statePrep, std::size_t numData,
+    std::size_t numAncx, std::size_t numAncz, std::size_t numRounds,
+    std::size_t numLogical, const std::vector<std::size_t> &cnot_schedX_flat,
+    const std::vector<std::size_t> &cnot_schedZ_flat,
+    const std::vector<double> &p_spam_per_patch, bool apply_corrections) {
+  // ret[i] = patch i's final data bits (numData bits, enforced < 64 in
+  // main()); ret[numLogical] = per-patch correction bitmask (bit i set iff
+  // decoder i predicted a logical flip).
+  std::vector<std::uint64_t> ret(numLogical + 1);
+  for (std::size_t k = 0; k <= numLogical; k++)
+    ret[k] = 0;
+
+  // Reset the decoder
+  if (allow_device_calls) {
+    for (int i = 0; i < numLogical; i++) {
+      cudaq::qec::decoding::reset_decoder(/*decoder_id=*/i);
+    }
+  }
+
+  // Allocate the data and ancilla qubits
+  cudaq::qvector data(numLogical * numData), xstab_anc(numLogical * numAncx),
+      zstab_anc(numLogical * numAncz);
+
+  // Call state prep
+  for (int i = 0; i < numLogical; i++) {
+    auto subData = data.slice(i * numData, numData);
+    auto subXstab_anc = xstab_anc.slice(i * numAncx, numAncx);
+    auto subZstab_anc = zstab_anc.slice(i * numAncz, numAncz);
+    patch logical(subData, subXstab_anc, subZstab_anc);
+    statePrep(logical);
+  }
+
+  // Round 0 (lock-in) for every patch: no spam; pins the stabilizer
+  // eigenvalues after prep.
+  for (int i = 0; i < numLogical; i++) {
+    syndrome_round_once(
+        data.slice(i * numData, numData), xstab_anc.slice(i * numAncx, numAncx),
+        zstab_anc.slice(i * numAncz, numAncz), cnot_schedX_flat,
+        cnot_schedZ_flat, /*do_spam=*/false, p_spam_per_patch[i],
+        /*do_enqueue=*/allow_device_calls, i,
+        /*round_counter=*/0);
+  }
+
+  // Paired rounds, ROUND-MAJOR: every patch measures round r before any patch
+  // measures round r+1. Each patch's own stream (spam BEFORE each paired
+  // round, then measure) is identical to the DEM kernel's schedule. This
+  // example decodes ONE volume of num_rounds rounds (no sliding windows), so
+  // each syndrome is enqueued EXACTLY ONCE.
+  for (std::size_t round = 0; round + 1 < numRounds; round++) {
+    for (int i = 0; i < numLogical; i++) {
+      syndrome_round_once(data.slice(i * numData, numData),
+                          xstab_anc.slice(i * numAncx, numAncx),
+                          zstab_anc.slice(i * numAncz, numAncz),
+                          cnot_schedX_flat, cnot_schedZ_flat, /*do_spam=*/true,
+                          p_spam_per_patch[i],
+                          /*do_enqueue=*/allow_device_calls, i,
+                          /*round_counter=*/round + 1);
+    }
+  }
+
+  // Final data round per patch: measure the data qubits in the logical (Z)
+  // basis and enqueue them as the LAST enqueue of that patch's stream,
+  // completing the num_rounds*(numAncx+numAncz)+numData-bit buffer the DEM was
+  // built under (385 at d7/T7). The decoder's boundary detectors XOR these
+  // data bits against the final-round Z-ancilla measurements.
+  for (int i = 0; i < numLogical; i++) {
+    auto subData = data.slice(i * numData, numData);
+    auto subMeas = mz(subData);
+    if (allow_device_calls)
+      cudaq::qec::decoding::enqueue_syndromes(/*decoder_id=*/i, subMeas,
+                                              /*round_counter=*/numRounds);
+    ret[i] = cudaq::to_integer(cudaq::to_bools(subMeas));
+  }
+
+  // Apply each decoder's correction classically: a transversal X on the data
+  // flips every measured data bit, so XOR the low-numData mask into that
+  // patch's word when its decoder predicts a logical flip. This matches the
+  // physical-X-then-measure result but lets us enqueue the (uncorrected) data
+  // bits first.
+  if (allow_device_calls && apply_corrections) {
+    for (int i = 0; i < numLogical; i++) {
+      auto correction_result = cudaq::qec::decoding::get_corrections(
+          /*decoder_id=*/i, /*return_size=*/1, /*reset=*/false);
+      if (correction_result[0] != 0) {
+        ret[numLogical] |= (1ull << i);
+        std::uint64_t mask = (1ull << numData) - 1;
+        ret[i] = ret[i] ^ mask;
+      }
+    }
+  }
+  return ret;
+}
+
+// DEM-generation kernel. The example uses two kernels that share one syndrome-
+// extraction helper (measure_syndrome_round): dem_gen_circuit (this one) is
+// sampled by dem_from_kernel to build the DEM, so it is a pure detector-
+// annotated circuit with no decoder calls; demo_circuit_qpu runs the live
+// experiment and makes the decoder RPC calls (enqueue_syndromes /
+// get_corrections). The two kernels need to stay in lockstep on the measurement
+// schedule (same rounds, X-then-Z order, spam-then-measure placement).
+//
+// dem_gen_circuit declares detectors; the layout is basis Z, orientation XV:
+//   - Block 0 (numAncz prep singles): one single-term detector per round-0
+//     Z-ancilla (deterministic after prep0 |0>_L).
+//   - Blocks 1+2 (paired): `pairedRounds` rounds, each pairing this round's
+//     full syndrome [X..., Z...] against the previous round's, via
+//     cudaq::detectors(prev, curr) (numAncx + numAncz detectors per round).
+//   - Block 3 (numAncz boundary): one detector per Z-stabilizer s, XOR-ing the
+//     final data measurements in that stabilizer's support with the
+//     last-round Z-ancilla measurement for that stabilizer.
+__qpu__ void
+dem_gen_circuit(const cudaq::qec::code::one_qubit_encoding &statePrep,
+                std::size_t numData, std::size_t numAncx, std::size_t numAncz,
+                std::size_t pairedRounds,
+                const std::vector<std::size_t> &cnot_schedX_flat,
+                const std::vector<std::size_t> &cnot_schedZ_flat, double p_spam,
+                const std::vector<std::size_t> &z_logical_indices,
+                const std::vector<std::size_t> &z_supports_flat,
+                const std::vector<std::size_t> &z_supports_offsets) {
+  cudaq::qvector data(numData), xstab_anc(numAncx), zstab_anc(numAncz);
+  patch logical(data, xstab_anc, zstab_anc);
+
+  statePrep(logical);
+
+  std::vector<cudaq::measure_result> prev(numAncz + numAncx);
+  measure_syndrome_round(logical, cnot_schedX_flat, cnot_schedZ_flat, prev);
+
+  // Block 0: prep singles on the round-0 Z-ancillas. Post-flip the combined
+  // syndrome is [X(numAncx), Z(numAncz)], so the Z-ancillas are
+  // prev[numAncx..].
+  for (std::size_t k = 0; k < numAncz; ++k)
+    cudaq::detector(prev[numAncx + k]);
+
+  // Blocks 1+2: paired cross-round detectors. Exactly `pairedRounds` rounds
+  // (the middle rounds plus the final round), giving
+  // pairedRounds * (numAncx + numAncz) detectors.
+  for (std::size_t round = 0; round < pairedRounds; ++round) {
+    spam_error(logical, /*p_spam_data=*/p_spam, /*p_spam_ancx=*/0.0,
+               /*p_spam_ancz=*/0.0);
+    std::vector<cudaq::measure_result> curr(numAncz + numAncx);
+    measure_syndrome_round(logical, cnot_schedX_flat, cnot_schedZ_flat, curr);
+    cudaq::detectors(prev, curr);
+    prev = curr;
+  }
+
+  auto dataM = mz(data);
+
+  // Block 3: boundary detectors. For each Z-stabilizer s, XOR its data-qubit
+  // support (from the final data measurement) with that stabilizer's last-round
+  // Z-ancilla measurement (prev still holds the final round syndrome).
+  for (std::size_t s = 0; s + 1 < z_supports_offsets.size(); ++s) {
+    std::vector<cudaq::measure_result> stab_data(z_supports_offsets[s + 1] -
+                                                 z_supports_offsets[s]);
+    std::size_t j = 0;
+    for (std::size_t t = z_supports_offsets[s]; t < z_supports_offsets[s + 1];
+         ++t)
+      stab_data[j++] = dataM[z_supports_flat[t]];
+    cudaq::detector(stab_data, prev[numAncx + s]);
+  }
+
+  std::vector<cudaq::measure_result> zlog(z_logical_indices.size());
+  for (std::size_t k = 0; k < z_logical_indices.size(); ++k)
+    zlog[k] = dataM[z_logical_indices[k]];
+  cudaq::logical_observable(zlog, /*observable_index=*/0);
+}
+} // namespace cudaq::qec::qpu
+
+void demo_circuit_host(const cudaq::qec::code &code, int distance,
+                       const std::vector<double> &p_spam_per_patch,
+                       cudaq::qec::operation statePrep, std::size_t numShots,
+                       std::size_t numRounds, std::size_t numLogical,
+                       std::string dem_filename, bool save_dem, bool load_dem,
+                       const std::vector<std::string> &decoder_types,
+                       bool save_syndrome = false, bool load_syndrome = false,
+                       std::string syndrome_filename = "",
+                       std::string ising_artifacts_dir = "") {
+  if (!code.contains_operation(statePrep))
+    throw std::runtime_error(
+        "sample_memory_circuit_error - requested state prep kernel not found.");
+
+  auto &prep =
+      code.get_operation<cudaq::qec::code::one_qubit_encoding>(statePrep);
+
+  auto numData = code.get_num_data_qubits();
+  auto numAncx = code.get_num_ancilla_x_qubits();
+  auto numAncz = code.get_num_ancilla_z_qubits();
+
+  auto cnot_schedX_flat = get_stab_cnot_schedule('X', distance);
+  auto cnot_schedZ_flat = get_stab_cnot_schedule('Z', distance);
+  std::size_t numSyndromesPerRound = 0;
+
+  // Print the CNOT schedules: prepare_ising_artifacts.py consumes these
+  // lines to build the artifact directory's D_sparse.txt against THIS app's
+  // measurement layout (its prepare mode runs this app itself; its d-sparse
+  // mode takes them from a saved sched.txt).
+  printf("cnot_schedX_flat: ");
+  for (std::size_t i = 0; i < cnot_schedX_flat.size(); i += 2)
+    printf("%lu %lu, ", cnot_schedX_flat[i], cnot_schedX_flat[i + 1]);
+  printf("\n");
+  printf("cnot_schedZ_flat: ");
+  for (std::size_t i = 0; i < cnot_schedZ_flat.size(); i += 2)
+    printf("%lu %lu, ", cnot_schedZ_flat[i], cnot_schedZ_flat[i + 1]);
+  printf("\n");
+
+  cudaq::noise_model noise;
+
+  // First get the DEM.
+  cudaq::qec::detector_error_model dem;
+  // Per-id decoder types read back from the YAML (run phase), for the
+  // per-decoder report lines.
+  std::vector<std::string> loaded_types;
+  if (load_dem) {
+    uint64_t measSpan = 0;
+    auto decoder_config = load_decoder_config(dem_filename, dem, numLogical,
+                                              measSpan, loaded_types);
+    const auto numDetectors = dem.detector_error_matrix.shape()[0];
+    const auto fullSyndromesPerRound = numAncx + numAncz;
+    // Bind the loaded config to this experiment's geometry: the detector count
+    // and the measurement-buffer span (max(D_sparse)+1) must both match the
+    // distance and num_rounds being run.
+    const auto expectedDetectors =
+        static_cast<std::size_t>(numRounds) * fullSyndromesPerRound;
+    const auto expectedSpan = expectedDetectors + numData;
+    if (numDetectors != expectedDetectors)
+      throw std::runtime_error(
+          "Loaded DEM detector count (" + std::to_string(numDetectors) +
+          ") does not match this experiment (d=" + std::to_string(distance) +
+          ", num_rounds=" + std::to_string(numRounds) + " -> expected " +
+          std::to_string(expectedDetectors) + ")");
+    if (measSpan != expectedSpan)
+      throw std::runtime_error(
+          "Loaded config measurement-buffer span max(D_sparse)+1 (" +
+          std::to_string(measSpan) +
+          ") does not match this experiment's enqueued bits (expected " +
+          std::to_string(expectedSpan) +
+          " = num_rounds*(numAncx+numAncz)+numData for d=" +
+          std::to_string(distance) +
+          ", num_rounds=" + std::to_string(numRounds) +
+          "); the YAML was generated for a different geometry");
+    numSyndromesPerRound = fullSyndromesPerRound;
+    // Construct local decoders only for the in-process executable. The external
+    // executable still performs all geometry validation above, but the server
+    // owns the decoder instances described by this same configuration.
+#ifdef QEC_APP_CQR
+    printf("External decoding server owns all configured decoder instances\n");
+#else
+    int rc = cudaq::qec::decoding::config::configure_decoders(decoder_config);
+    if (rc != 0)
+      throw std::runtime_error("configure_decoders failed (status " +
+                               std::to_string(rc) + ")");
+#endif
+  } else {
+    for (std::size_t i = 0; i < p_spam_per_patch.size(); ++i)
+      if (p_spam_per_patch[i] == 0.0)
+        throw std::runtime_error("--p_spam must be > 0 to generate a DEM");
+
+    // Left-column data qubits are the Z logical for XV. This must track the
+    // code's Z observable (code.get_observables_z()); if the orientation
+    // changes to XH/ZV the Z logical moves to the top row.
+    std::vector<std::size_t> z_logical_indices;
+    for (int i = 0; i < distance; ++i)
+      z_logical_indices.push_back(static_cast<std::size_t>(i) * distance);
+
+    // Z-stabilizer data-qubit supports, aligned to the Z-ancilla measurement
+    // order (support[s] <-> Z-ancilla[s]). Used to build the boundary
+    // detectors (basis Z).
+    std::vector<std::size_t> z_supports_flat, z_supports_offsets;
+    get_stab_data_supports('Z', distance, z_supports_flat, z_supports_offsets);
+
+    // The DEM detector layout is:
+    //   numAncz prep singles + pairedRounds * (numAncx + numAncz) paired
+    //   + numAncz boundary.
+    // This example decodes ONE volume of num_rounds rounds. Ising's n_rounds
+    // counts the state-prep round and the final logical-measurement round, so
+    // it has (n_rounds - 1) paired transitions. Here the round-0 syndrome is
+    // the prep round and the volume covers num_rounds syndrome rounds total, so
+    // there are (num_rounds - 1) paired rounds (the 5 middle + 1 final at d=7,
+    // num_rounds=7).
+    const std::size_t pairedRounds = static_cast<std::size_t>(numRounds) - 1;
+
+    // Both supported decoder types (pymatching, and trt_decoder's global
+    // pymatching stage) are matching decoders, so the DEM is always sampled
+    // with decomposition suggestions.
+    const bool decompose_errors = true;
+    cudaq::M2DSparseMatrix m2d;
+    std::vector<cudaq::qec::detector_error_model> patch_dems;
+    patch_dems.reserve(numLogical);
+    for (std::size_t patch = 0; patch < numLogical; ++patch) {
+      cudaq::M2DSparseMatrix patch_m2d;
+      cudaq::M2OSparseMatrix patch_m2o;
+      const std::string dem_text = cudaq::dem_from_kernel(
+          cudaq::qec::qpu::dem_gen_circuit, &noise,
+          cudaq::dem_options{.decompose_errors = decompose_errors}, patch_m2d,
+          patch_m2o, prep, numData, numAncx, numAncz, pairedRounds,
+          cnot_schedX_flat, cnot_schedZ_flat, p_spam_per_patch[patch],
+          z_logical_indices, z_supports_flat, z_supports_offsets);
+      if (patch == 0)
+        m2d = patch_m2d;
+      else if (patch_m2d.rows != m2d.rows)
+        throw std::runtime_error(
+            "per-patch DEMs produced different measurement mappings");
+
+      patch_dems.push_back(cudaq::qec::dem_from_stim_text(
+          dem_text, /*use_decomp_suggestions=*/decompose_errors));
+    }
+    dem = patch_dems.front();
+
+    numSyndromesPerRound = numAncx + numAncz;
+    printf("numSyndromesPerRound: %ld\n", numSyndromesPerRound);
+
+    if (save_dem) {
+      save_dem_to_file(patch_dems, dem_filename, decoder_types, m2d,
+                       ising_artifacts_dir, distance, numRounds);
+      return;
+    }
+  }
+
+  // Detector count for one volume of num_rounds rounds:
+  //   numAncz (prep singles) + (num_rounds-1)*(numAncx+numAncz) (paired)
+  //   + numAncz (boundary).
+  // This is divisible by numSyndromesPerRound (= numAncx+numAncz) into exactly
+  // num_rounds rounds ONLY because numAncx == numAncz for the rotated surface
+  // code (so the prep block numAncz and the boundary block numAncz together
+  // make one full numAncx+numAncz round).
+  if (dem.detector_error_matrix.shape()[0] % numSyndromesPerRound != 0) {
+    throw std::runtime_error("Num syndromes per round is not a divisor of "
+                             "the number of syndrome measurements");
+  }
+  size_t numRoundsOfSyndromData =
+      dem.detector_error_matrix.shape()[0] / numSyndromesPerRound;
+
+  if (numRoundsOfSyndromData != static_cast<std::size_t>(numRounds)) {
+    throw std::runtime_error("Num rounds of syndrome data [" +
+                             std::to_string(numRoundsOfSyndromData) +
+                             "] is not equal to num_rounds [" +
+                             std::to_string(numRounds) + "]");
+  }
+
+  // Setup syndrome capture if requested (--save_syndrome option)
+  if (save_syndrome) {
+    if (syndrome_filename.empty()) {
+      printf("Error: --save_syndrome requires a filename argument\n");
+      return;
+    }
+
+    g_syndrome_output_file.open(syndrome_filename,
+                                std::ios::out | std::ios::trunc);
+    if (!g_syndrome_output_file) {
+      printf("Error: Could not open syndrome file for writing: %s\n",
+             syndrome_filename.c_str());
+      return;
+    }
+
+    // Per-shot enqueue structure: num_rounds uniform syndrome rounds
+    // (numSyndromesPerRound bits each) + 1 final DATA round (numData bits). The
+    // capture callback fires once per enqueue in chronological order, so the
+    // per-shot enqueue index distinguishes the heterogeneous final round.
+    g_enqueues_per_shot = static_cast<int>(numRounds) + 1;
+    g_syndrome_bits_per_round = static_cast<int>(numSyndromesPerRound);
+    g_data_bits = static_cast<int>(numData);
+    g_syndrome_count = 0;
+
+    printf("Syndrome capture enabled: saving to %s\n",
+           syndrome_filename.c_str());
+    printf(
+        "Will capture %d enqueues per shot (%ld syndrome rounds of %d bits + "
+        "1 data round of %d bits)\n",
+        g_enqueues_per_shot, numRounds, g_syndrome_bits_per_round, g_data_bits);
+
+    // Write metadata to file header
+    g_syndrome_output_file << "NUM_DATA " << numData << "\n";
+    g_syndrome_output_file << "NUM_LOGICAL " << numLogical << "\n";
+    g_syndrome_output_file.flush();
+
+    // Register capture callback with decoder library
+    cudaq::qec::decoding::host::_set_syndrome_capture_callback(
+        [](const uint8_t *data, size_t len) {
+          std::lock_guard<std::mutex> lock(g_syndrome_file_mutex);
+          if (!g_syndrome_output_file.is_open())
+            return;
+
+          // Position of this enqueue within the current shot.
+          int enqueue_idx = g_syndrome_count % g_enqueues_per_shot;
+
+          // Write shot boundary marker at the start of each shot
+          if (enqueue_idx == 0) {
+            int shot_num = g_syndrome_count / g_enqueues_per_shot;
+            g_syndrome_output_file << "SHOT_START " << shot_num << "\n";
+          }
+
+          // The last enqueue of each shot is the final DATA round (numData
+          // bits); all others are uniform syndrome rounds. Record the true bit
+          // width on the ROUND_START line so replay can chunk it back exactly.
+          int bits_this_round = (enqueue_idx == g_enqueues_per_shot - 1)
+                                    ? g_data_bits
+                                    : g_syndrome_bits_per_round;
+
+          g_syndrome_output_file << "ROUND_START " << g_syndrome_count << " "
+                                 << bits_this_round << "\n";
+
+          // Unpack syndrome data - each byte contains 8 bits (packed format,
+          // MSB first). Emit exactly bits_this_round bits.
+          int bits_written = 0;
+          for (size_t i = 0; i < len && bits_written < bits_this_round; i++) {
+            uint8_t byte = data[i];
+            for (int bit_idx = 7; bit_idx >= 0; bit_idx--) {
+              if (bits_written >= bits_this_round)
+                break;
+              int bit = (byte >> bit_idx) & 1;
+              g_syndrome_output_file << bit << "\n";
+              bits_written++;
+            }
+          }
+          g_syndrome_output_file.flush();
+
+          g_syndrome_count++;
+        });
+  }
+
+  // Either run quantum simulation OR replay syndromes from file
+  std::vector<std::vector<std::uint64_t>> run_result;
+
+  if (load_syndrome) {
+    // Syndrome replay mode
+    if (syndrome_filename.empty())
+      throw std::runtime_error("--load_syndrome requires a filename argument");
+
+    printf("\n=== Syndrome Replay Mode ===\n");
+    printf("Loading syndromes from: %s\n", syndrome_filename.c_str());
+
+    std::ifstream syndrome_file(syndrome_filename);
+    if (!syndrome_file)
+      throw std::runtime_error("Could not open syndrome file: " +
+                               syndrome_filename);
+
+    // Read header and syndrome data. Each shot is stored as a list of rounds,
+    // and each round keeps its own bit count (the final DATA round has numData
+    // bits, the syndrome rounds have numSyndromesPerRound). The per-round width
+    // is read from the "ROUND_START <idx> <nbits>" header that the capture
+    // writes, so replay reconstructs the heterogeneous stream exactly.
+    std::size_t file_numData = 0;
+    std::size_t file_numLogical = 0;
+    std::vector<uint8_t> saved_corrections;
+    std::vector<std::vector<std::vector<uint8_t>>> saved_shots;
+    std::string line;
+
+    bool reading_syndromes = false;
+    bool saw_corrections_start = false;
+    bool saw_corrections_end = false;
+    while (std::getline(syndrome_file, line)) {
+      if (line.find("NUM_DATA") == 0) {
+        std::istringstream iss(line);
+        std::string tag;
+        iss >> tag >> file_numData;
+      } else if (line.find("NUM_LOGICAL") == 0) {
+        std::istringstream iss(line);
+        std::string tag;
+        iss >> tag >> file_numLogical;
+      } else if (line.find("CORRECTIONS_START") == 0) {
+        saw_corrections_start = true;
+        while (std::getline(syndrome_file, line)) {
+          if (line.find("CORRECTIONS_END") == 0) {
+            saw_corrections_end = true;
+            break;
+          }
+          uint8_t correction_bit = static_cast<uint8_t>(std::stoi(line));
+          saved_corrections.push_back(correction_bit);
+        }
+        printf("Read %zu saved corrections\n", saved_corrections.size());
+        break;
+      } else if (line.find("SHOT_START") == 0) {
+        saved_shots.emplace_back();
+        reading_syndromes = true;
+      } else if (line.find("ROUND_START") == 0) {
+        // Start a new round, read greedily until the next marker. The resulting
+        // per-shot round count and widths are validated against the known
+        // geometry after parsing, which is what catches a truncated/corrupt
+        // capture.
+        if (!saved_shots.empty())
+          saved_shots.back().emplace_back();
+        continue;
+      } else if (reading_syndromes) {
+        try {
+          int bit = std::stoi(line);
+          saved_shots.back().back().push_back(static_cast<uint8_t>(bit));
+        } catch (...) {
+          break;
+        }
+      }
+    }
+
+    printf("Read %zu shots with syndromes\n", saved_shots.size());
+
+    // Require a STRUCTURALLY COMPLETE capture so a truncated/corrupt file fails
+    // loudly instead of silently "passing" with no verification.
+    if (saved_shots.empty())
+      throw std::runtime_error(
+          "no shots parsed from syndrome file (empty or corrupt): " +
+          syndrome_filename);
+    if (!saw_corrections_start || !saw_corrections_end)
+      throw std::runtime_error(
+          "syndrome file is missing the CORRECTIONS_START/CORRECTIONS_END "
+          "footer (truncated or incomplete capture): " +
+          syndrome_filename);
+    if (file_numData != numData || file_numLogical != numLogical)
+      throw std::runtime_error(
+          "syndrome file parameters (numData=" + std::to_string(file_numData) +
+          ", numLogical=" + std::to_string(file_numLogical) +
+          ") do not match this run (numData=" + std::to_string(numData) +
+          ", numLogical=" + std::to_string(numLogical) + ")");
+    if (saved_corrections.size() != saved_shots.size())
+      throw std::runtime_error(
+          "syndrome file has " + std::to_string(saved_corrections.size()) +
+          " corrections for " + std::to_string(saved_shots.size()) +
+          " shots; expected exactly one correction per shot (truncated "
+          "capture)");
+    // Each shot must be the full enqueue stream: num_rounds syndrome rounds of
+    // numSyndromesPerRound bits + one final data round of numData bits.
+    const std::size_t expectedRounds = static_cast<std::size_t>(numRounds) + 1;
+    for (std::size_t s = 0; s < saved_shots.size(); ++s) {
+      const auto &rounds = saved_shots[s];
+      if (rounds.size() != expectedRounds)
+        throw std::runtime_error(
+            "syndrome file shot " + std::to_string(s) + " has " +
+            std::to_string(rounds.size()) + " rounds; expected " +
+            std::to_string(expectedRounds) +
+            " (num_rounds+1); truncated or wrong-geometry capture");
+      for (std::size_t r = 0; r < rounds.size(); ++r) {
+        const std::size_t expectedBits = (r + 1 == expectedRounds)
+                                             ? static_cast<std::size_t>(numData)
+                                             : numSyndromesPerRound;
+        if (rounds[r].size() != expectedBits)
+          throw std::runtime_error(
+              "syndrome file shot " + std::to_string(s) + " round " +
+              std::to_string(r) + " has " + std::to_string(rounds[r].size()) +
+              " bits; expected " + std::to_string(expectedBits) +
+              " (truncated or corrupt capture)");
+      }
+    }
+
+    syndrome_file.close();
+
+    // Process saved syndromes through decoder
+    printf("Feeding %zu shots of saved syndromes to decoder...\n",
+           saved_shots.size());
+
+    int corrections_matched = 0;
+    int corrections_mismatched = 0;
+
+    for (size_t shot_idx = 0; shot_idx < saved_shots.size(); shot_idx++) {
+      // Reset decoder for new shot
+      for (size_t logical_idx = 0; logical_idx < numLogical; logical_idx++) {
+        cudaq::qec::decoding::reset_decoder(logical_idx);
+      }
+
+      // Feed syndromes to the decoder one captured round at a time, each at its
+      // recorded width. This mirrors the live enqueue cadence exactly, so the
+      // boundary detectors -- which XOR the final data bits against the
+      // last-round Z-ancillas -- see the same data round the live path
+      // enqueued.
+      const auto &shot_rounds = saved_shots[shot_idx];
+      for (const auto &round_bits : shot_rounds) {
+        // Replay path: raw syndrome bits read from a saved file. Use the
+        // test-only `enqueue_syndromes_test` API since these bits have no
+        // measurement-event identity to preserve.
+        std::vector<bool> syndrome_round;
+        syndrome_round.reserve(round_bits.size());
+        for (uint8_t b : round_bits)
+          syndrome_round.push_back(static_cast<bool>(b));
+
+        // Enqueue this round for all logical qubits
+        for (size_t logical_idx = 0; logical_idx < numLogical; logical_idx++) {
+          cudaq::qec::decoding::enqueue_syndromes_test(logical_idx,
+                                                       syndrome_round);
+        }
+      }
+
+      // Get logical corrections from decoder
+      uint8_t correction_bit = 0;
+      for (size_t logical_idx = 0; logical_idx < numLogical; logical_idx++) {
+        auto corrections =
+            cudaq::qec::decoding::get_corrections(logical_idx, 1, false);
+        if (!corrections.empty() && corrections[0]) {
+          correction_bit = 1;
+        }
+      }
+
+      // Compare with saved correction if available
+      if (shot_idx < saved_corrections.size()) {
+        if (correction_bit == saved_corrections[shot_idx]) {
+          corrections_matched++;
+        } else {
+          corrections_mismatched++;
+          if (corrections_mismatched <= 10) {
+            printf("  Shot %zu: mismatch! Replayed=%u, Saved=%u\n", shot_idx,
+                   correction_bit, saved_corrections[shot_idx]);
+          }
+        }
+      }
+    }
+
+    printf("Replay complete: %zu shots processed\n", saved_shots.size());
+    if (!saved_corrections.empty()) {
+      printf("Correction verification: %d matched, %d mismatched\n",
+             corrections_matched, corrections_mismatched);
+      if (corrections_mismatched != 0)
+        throw std::runtime_error(
+            "replay correction mismatch: " +
+            std::to_string(corrections_mismatched) + " of " +
+            std::to_string(corrections_matched + corrections_mismatched) +
+            " shots differ from the captured run");
+      printf("SUCCESS: All corrections match!\n");
+    }
+    return;
+
+  } else {
+    // Normal quantum simulation mode
+    printf("\n=== Quantum Simulation Mode ===\n");
+
+    // If this is a remote platform (not local sim nor emulation), don't use the
+    // noise model.
+    run_result =
+        cudaq::get_platform().is_remote()
+            ? cudaq::run(numShots, cudaq::qec::qpu::demo_circuit_qpu,
+                         /*allow_device_calls=*/true, prep, numData, numAncx,
+                         numAncz, numRounds, numLogical, cnot_schedX_flat,
+                         cnot_schedZ_flat, p_spam_per_patch,
+                         /*apply_corrections=*/true)
+            : cudaq::run(numShots, noise, cudaq::qec::qpu::demo_circuit_qpu,
+                         /*allow_device_calls=*/true, prep, numData, numAncx,
+                         numAncz, numRounds, numLogical, cnot_schedX_flat,
+                         cnot_schedZ_flat, p_spam_per_patch,
+                         /*apply_corrections=*/true);
+  }
+  printf("Result size: %ld\n", run_result.size());
+  std::vector<std::vector<uint8_t>> logical_results;
+  auto obs_matrix = code.get_observables_z();
+  int num_non_zero_values = 0;
+  std::int64_t num_corrections = 0;
+  for (int i = 0; i < run_result.size(); i++) {
+    const auto &shot = run_result[i];
+    const std::uint64_t corrections_mask = shot[numLogical];
+    logical_results.emplace_back();
+    for (int j = 0; j < numLogical; j++) {
+      if ((corrections_mask >> j) & 1)
+        num_corrections++;
+      std::vector<double> result_vec(numData);
+      for (int l = 0; l < numData; l++) {
+        result_vec[l] = (shot[j] & (1ull << l)) ? 1.0 : 0.0;
+      }
+      cudaqx::tensor<uint8_t> result_tensor;
+      cudaq::qec::convert_vec_soft_to_tensor_hard(result_vec, result_tensor);
+      // Calculate the logical observable for each logical qubit
+      uint8_t logical_result = (obs_matrix.dot(result_tensor) % 2).at({0});
+      logical_results.back().push_back(logical_result);
+      if (logical_result != 0)
+        num_non_zero_values++;
+    }
+  }
+  printf("Number of non-zero values measured : %d\n", num_non_zero_values);
+  printf("Number of corrections decoder found: %ld\n", num_corrections);
+
+  // Save corrections to file if syndrome capture was enabled
+  if (save_syndrome && g_syndrome_output_file.is_open()) {
+    // Disable callback to stop capturing
+    cudaq::qec::decoding::host::_set_syndrome_capture_callback(nullptr);
+
+    // Save logical corrections for each shot (for verification during replay)
+    g_syndrome_output_file << "CORRECTIONS_START\n";
+    for (size_t i = 0; i < logical_results.size(); i++) {
+      uint8_t any_correction = run_result[i][numLogical] != 0 ? 1 : 0;
+      g_syndrome_output_file << static_cast<int>(any_correction) << "\n";
+    }
+    g_syndrome_output_file << "CORRECTIONS_END\n";
+    g_syndrome_output_file.close();
+    printf("Syndrome data saved to: %s\n", syndrome_filename.c_str());
+  }
+}
+
+void show_help() {
+  printf("Usage: surface_code_ising_realtime_decoding [options]\n");
+  printf("Options:\n");
+  printf("  --distance <int>    Distance of the surface code. Default: 7\n");
+  printf("  --num_shots <int>   Number of shots. Default: 10\n");
+  printf(
+      "  --p_spam <double>   SPAM probability. Range[0, 1]. Default: 0.01\n");
+  printf("  --num_rounds <int>  Number of measurement rounds. Default: "
+         "distance\n");
+  printf("  --seed <int>        Simulator seed; negative = unseeded. "
+         "Default: 42\n");
+  printf("  --decoder_type <string> Decoder for the generated config (with "
+         "--save_dem): 'trt_decoder' (TensorRT Ising predecoder + PyMatching "
+         "global decoder; the default) or 'pymatching'.\n");
+  printf("  --ising-artifacts-dir <dir> Prepared Ising artifact directory "
+         "containing model.onnx, H_csr.bin, O_csr.bin, priors.bin, "
+         "metadata.txt, and D_sparse.txt. Required with --decoder_type "
+         "trt_decoder and --save_dem; QEC_ISING_ARTIFACTS_DIR is honored "
+         "when the flag is absent. Nothing in this directory ships with "
+         "CUDA-QX -- see the example docs for the preparation recipe.\n");
+  printf("  --save_dem <string> Generate the DEM + decoder config and save to "
+         "a YAML file (generation phase).\n");
+  printf(
+      "  --yaml <string>     Run realtime decoding from a YAML config; the "
+      "decoder is read from the file. Do not combine with --decoder_type.\n");
+  printf("  --load_dem <string> Alias of --yaml.\n");
+  printf("  --save_syndrome <string> Save syndrome data to a file for later "
+         "replay (and FPGA playback).\n");
+  printf("  --load_syndrome <string> Load and replay syndrome data from a "
+         "file.\n");
+  printf("  --help              Show this help message\n");
+}
+
+int main(int argc, char **argv) {
+#ifdef QEC_APP_CQR
+  realtime_channel_guard realtime_channel;
+#endif
+  int num_shots = 10;
+  int distance = 7;
+  double p_spam = 0.01;
+  int num_rounds = -1; // Will be set to distance if not specified
+  int seed = 42;       // negative = unseeded
+  bool save_dem = false;
+  bool load_dem = false;
+  std::string dem_filename;
+
+  // Decoder type selection. This is a GENERATION-phase knob (used with
+  // --save_dem); with --yaml the decoder is read from the file.
+  std::string decoder_type = "trt_decoder"; // Default
+  bool decoder_type_explicit = false;
+  bool yaml_mode = false;
+  // The Ising artifact directory (six files; see the header comment). Flag
+  // overrides the QEC_ISING_ARTIFACTS_DIR environment variable.
+  std::string ising_artifacts_dir = env_or("QEC_ISING_ARTIFACTS_DIR", "");
+
+  // Syndrome save/load options
+  bool save_syndrome = false;
+  bool load_syndrome = false;
+  std::string syndrome_filename;
+
+  // This example is single-patch by design (one logical qubit, one decoder):
+  // the Ising artifacts describe one code patch.
+  const int num_logical = 1;
+
+  // Parse the command line arguments. Value-taking flags read the next argv
+  // entry through require_value, which errors out (rather than reading past the
+  // end of argv) when a flag is given with no following value; numeric flags go
+  // through require_int/require_double, which reject malformed values.
+  int i;
+  auto require_value = [&](const char *flag) -> std::string {
+    if (i + 1 >= argc) {
+      printf("Error: %s requires a value.\n", flag);
+      std::exit(1);
+    }
+    return argv[++i];
+  };
+  auto require_int = [&](const char *flag) -> int {
+    const std::string v = require_value(flag);
+    try {
+      std::size_t pos = 0;
+      int r = std::stoi(v, &pos);
+      if (pos != v.size())
+        throw std::invalid_argument(v);
+      return r;
+    } catch (const std::exception &) {
+      printf("Error: %s expects an integer, got '%s'.\n", flag, v.c_str());
+      std::exit(1);
+    }
+  };
+  auto require_double = [&](const char *flag) -> double {
+    const std::string v = require_value(flag);
+    try {
+      std::size_t pos = 0;
+      double r = std::stod(v, &pos);
+      if (pos != v.size())
+        throw std::invalid_argument(v);
+      return r;
+    } catch (const std::exception &) {
+      printf("Error: %s expects a number, got '%s'.\n", flag, v.c_str());
+      std::exit(1);
+    }
+  };
+  for (i = 1; i < argc; i++) {
+    std::string arg = argv[i];
+    if (arg == "--distance") {
+      distance = require_int("--distance");
+    } else if (arg == "--num_shots") {
+      num_shots = require_int("--num_shots");
+    } else if (arg == "--p_spam") {
+      p_spam = require_double("--p_spam");
+    } else if (arg == "--help" || arg == "-h") {
+      show_help();
+      return 0;
+    } else if (arg == "--num_rounds") {
+      num_rounds = require_int("--num_rounds");
+    } else if (arg == "--seed") {
+      seed = require_int("--seed");
+    } else if (arg == "--decoder_type") {
+      decoder_type = require_value("--decoder_type");
+      decoder_type_explicit = true;
+    } else if (arg == "--ising-artifacts-dir" ||
+               arg == "--ising_artifacts_dir") {
+      ising_artifacts_dir = require_value("--ising-artifacts-dir");
+    } else if (arg == "--save_dem") {
+      save_dem = true;
+      dem_filename = require_value("--save_dem");
+    } else if (arg == "--yaml" || arg == "--load_dem") {
+      // Realtime phase: the decoder is read from the YAML (authoritative).
+      load_dem = true;
+      yaml_mode = true;
+      dem_filename = require_value("--yaml");
+    } else if (arg == "--save_syndrome") {
+      save_syndrome = true;
+      syndrome_filename = require_value("--save_syndrome");
+    } else if (arg == "--load_syndrome") {
+      load_syndrome = true;
+      syndrome_filename = require_value("--load_syndrome");
+    } else {
+      printf("Unknown argument: %s\n", arg.c_str());
+      show_help();
+      return 1;
+    }
+  }
+
+  if (!load_dem && !save_dem && !load_syndrome) {
+    printf("Neither --save_dem nor --load_dem nor --load_syndrome was "
+           "specified. This is not a valid use case for this program.\n");
+    show_help();
+    return 1;
+  }
+
+  // Validate syndrome save/load options
+  if (save_syndrome && load_syndrome) {
+    printf("Error: Cannot use both --save_syndrome and --load_syndrome "
+           "together\n");
+    return 1;
+  }
+  if (save_syndrome && save_dem) {
+    printf("Error: Cannot use --save_syndrome with --save_dem\n");
+    printf("       --save_dem returns early without running simulation.\n");
+    return 1;
+  }
+
+  // Reject geometries the rotated surface-code kernel cannot build: the
+  // distance must be an odd integer >= 3, and each patch's final data bits
+  // are returned in one 64-bit word, so numData = d^2 must fit (d <= 7).
+  if (distance < 3 || distance % 2 == 0) {
+    printf("Error: distance must be an odd integer >= 3 (got %d).\n", distance);
+    return 1;
+  }
+  const std::int64_t num_data_bits =
+      static_cast<std::int64_t>(distance) * distance;
+  if (num_data_bits >= 64) {
+    printf("Error: distance %d has %lld data qubits; only numData < 64 "
+           "(d <= 7) is supported.\n",
+           distance, static_cast<long long>(num_data_bits));
+    return 1;
+  }
+  if (num_shots < 1) {
+    printf("Error: --num_shots must be >= 1 (got %d).\n", num_shots);
+    return 1;
+  }
+  if (!std::isfinite(p_spam) || p_spam < 0.0 || p_spam > 1.0) {
+    printf("Error: --p_spam must be a finite value in [0, 1] (got %g).\n",
+           p_spam);
+    return 1;
+  }
+  const std::vector<double> p_spam_per_patch(num_logical, p_spam);
+
+  // Set defaults if not specified
+  if (num_rounds == -1)
+    num_rounds = distance;
+  // --yaml is authoritative for the decoder; a co-passed --decoder_type would
+  // be ambiguous, so reject the combination.
+  if (yaml_mode && decoder_type_explicit) {
+    printf(
+        "Error: --decoder_type only applies to --save_dem (generation). "
+        "With --yaml the decoder is read from the file; do not pass both.\n");
+    return 1;
+  }
+  // --save_dem (generation) and --yaml (realtime) are separate phases that
+  // write and read the same config file.
+  if (yaml_mode && save_dem) {
+    printf("Error: --save_dem (generation) and --yaml (realtime) are separate "
+           "phases; do not pass both.\n");
+    return 1;
+  }
+
+  if (decoder_type != "trt_decoder" && decoder_type != "pymatching") {
+    printf("Error: --decoder_type must be 'trt_decoder' or 'pymatching' "
+           "(got '%s')\n",
+           decoder_type.c_str());
+    return 1;
+  }
+  const std::vector<std::string> decoder_types(num_logical, decoder_type);
+
+  if (num_rounds < 2) {
+    printf("Error: num_rounds (%d) must be >= 2 (a memory experiment needs at "
+           "least one cross-round detector).\n",
+           num_rounds);
+    return 1;
+  }
+  if (num_rounds < distance)
+    printf("Warning: num_rounds (%d) < distance (%d): decodable but not "
+           "fault-tolerant (fewer rounds than the code distance).\n",
+           num_rounds, distance);
+
+  // Syndrome replay feeds saved syndromes through a configured decoder, which
+  // only exists under --yaml.
+  if (load_syndrome && !yaml_mode) {
+    printf("Error: --load_syndrome requires --yaml (the decoder to replay "
+           "through is configured from the loaded config).\n");
+    return 1;
+  }
+
+  // The trt+Ising generation path needs the prepared artifact directory. Fail
+  // up front with the complete gap list rather than deep inside DEM
+  // generation. (The run phase reads everything from the YAML; the ONNX path
+  // embedded there is validated by the serving side.)
+  if (save_dem && decoder_type == "trt_decoder") {
+    if (ising_artifacts_dir.empty()) {
+      printf("Error: --decoder_type trt_decoder requires an Ising artifact "
+             "directory: pass --ising-artifacts-dir <dir> or set "
+             "QEC_ISING_ARTIFACTS_DIR.\n"
+             "The six artifact files are prepared locally (gated Hugging Face "
+             "weights + the NVIDIA/Ising-Decoding repository); see the "
+             "realtime_decoding_demo documentation for the recipe.\n");
+      return 1;
+    }
+    try {
+      require_ising_artifact_files(ising_artifacts_dir);
+      enforce_ising_metadata(ising_artifacts_dir, distance,
+                             static_cast<std::size_t>(num_rounds));
+    } catch (const std::exception &e) {
+      printf("Error: %s\n", e.what());
+      return 1;
+    }
+  }
+
+  if (seed >= 0) {
+    cudaq::set_random_seed(static_cast<std::size_t>(seed));
+    printf("Set RNG seed to %d for deterministic results\n", seed);
+  }
+
+  printf("Running with p_spam = %g, distance = %d, num_shots = %d, "
+         "num_rounds = %d\n",
+         p_spam, distance, num_shots, num_rounds);
+
+  // Build the code at code_rotation XV (the predecoder's training orientation),
+  // which sets the geometry and observable basis.
+  try {
+#ifdef QEC_APP_CQR
+    if (load_dem)
+      realtime_channel.initialize(argv[0]);
+#endif
+
+    auto code = cudaq::qec::get_code(
+        "surface_code",
+        cudaqx::heterogeneous_map{{"distance", distance},
+                                  {"orientation", std::string("XV")}});
+
+    demo_circuit_host(*code, distance, p_spam_per_patch,
+                      cudaq::qec::operation::prep0, num_shots, num_rounds,
+                      num_logical, dem_filename, save_dem, load_dem,
+                      decoder_types, save_syndrome, load_syndrome,
+                      syndrome_filename, ising_artifacts_dir);
+  } catch (const std::exception &e) {
+    // Configuration, channel, and geometry failures surface as a clean error
+    // rather than an uncaught-exception abort.
+    printf("Error: %s\n", e.what());
+    cudaq::qec::decoding::config::finalize_decoders();
+    return 1;
+  }
+
+#ifdef QEC_APP_CQR
+  if (load_dem) {
+    // Proof the shots' device_calls crossed the wire to the EXTERNAL server:
+    // this in-process counter stays 0 unless the in-process host-dispatch
+    // service (not the external decoding_server) served the calls.
+    printf("CQR service dispatch count: %llu\n",
+           static_cast<unsigned long long>(
+               cudaqx_qec_device_call_dispatch_count()));
+  }
+#endif
+
+  // Ensure clean shutdown
+  cudaq::qec::decoding::config::finalize_decoders();
+
+  return 0;
+}
diff --git a/docs/sphinx/examples/qec/realtime_decoding_demo/surface_code_realtime_decoding.cpp b/docs/sphinx/examples/qec/realtime_decoding_demo/surface_code_realtime_decoding.cpp
new file mode 100644
index 000000000..0f6937600
--- /dev/null
+++ b/docs/sphinx/examples/qec/realtime_decoding_demo/surface_code_realtime_decoding.cpp
@@ -0,0 +1,883 @@
+/*******************************************************************************
+ * Copyright (c) 2025 NVIDIA Corporation & Affiliates.                         *
+ * All rights reserved.                                                        *
+ *                                                                             *
+ * This source code and the accompanying materials are made available under    *
+ * the terms of the Apache License 2.0 which accompanies this distribution.    *
+ ******************************************************************************/
+
+// The realtime_decoding_demo example source (a copy of the in-tree
+// unittests/realtime/app_examples/surface_code-1.cpp, adapted in this header,
+// the usage line, and the --save_syndrome capture, which emits true-width
+// groups so the FPGA playback tool replays exact per-round measurement
+// counts). CMakeLists.txt builds it two ways against the installed SDK: a
+// plain generator (writes the decoder config and, for the FPGA source, the
+// playback syndrome file) and a lowered `-cqr` kernel (-frealtime-lowering
+// -DQEC_APP_CQR) that streams syndromes to the delivered decoding_server over
+// UDP. run_realtime_decoding.sh drives both.
+//
+// This demo drives a surface-code memory experiment with realtime decoding:
+//
+//   * The detector error model and measurement-to-detector map are obtained
+//     from `decoder_context_from_memory_circuit`.
+//   * The QPU kernel loops over logical qubits, calling a per-logical
+//     `memory_circuit` kernel that preps the state, streams every round's
+//     syndrome plus the final data readout to that logical's decoder, and
+//     returns the data measurements.
+//   * Circuit-level two-qubit depolarizing noise on the stabilizer-extraction
+//     CNOTs is used for both characterization and simulation.
+//
+// The same source runs on the local (Stim) target and, compiled with
+// `--target quantinuum --emulate`, on the Quantinuum QIR emulator: in both
+// cases the syndromes are generated on the QPU and decoded live through the
+// realtime decoding API.
+//
+// The host-side flow (see demo_circuit_host): configure the decoders
+// (setup_decoders), then take one of two paths --
+//   * --load_syndrome : replay_syndrome_file feeds a captured file to the
+//     decoders and verifies the corrections (no circuit is run);
+//   * otherwise       : run_experiment runs the shots, reports the logical
+//     error rate, and optionally captures the syndrome stream
+//     (--save_syndrome).
+
+#include "cudaq.h"
+#include "cudaq/qec/code.h"
+#include "cudaq/qec/decoder.h"
+#include "cudaq/qec/experiments.h"
+#include "cudaq/qec/noise_model.h"
+#include "cudaq/qec/pcm_utils.h"
+#include "cudaq/qec/realtime/decoding.h"
+#include "cudaq/qec/realtime/decoding_config.h"
+#include <cstdlib>
+#include <fstream>
+#include <mutex>
+#include <numeric>
+#include <sstream>
+#include <stdexcept>
+
+#ifdef QEC_APP_CQR
+// cqr build variant: this same application compiled with -frealtime-lowering
+// and linked against the simulation-cqr client wrappers, so every
+// cudaq::qec::decoding::* device_call crosses the cudaq-realtime wire instead
+// of resolving to the in-process trampolines. The decoding is served either by
+// the in-process decoding-server-cqr service
+// (CUDAQ_DEVICE_CALL_CHANNEL=host_dispatch) or by a standalone
+// decoding_server (QEC_DECODING_SERVER_PORT=<port>). The wire to the
+// server defaults to udp loopback; set QEC_DECODING_SERVER_TRANSPORT=cpu_roce
+// to use the CPU RoCE RDMA channel instead (works over SoftRoCE/rdma_rxe; the
+// RDMA topology comes from the same CUDAQ_CPU_ROCE_TEST_* env vars as CUDA-Q's
+// CpuRoceChannelTester).
+#include "cudaq/realtime.h"
+
+// In-process service self-check hook (defined in decoding-server-cqr):
+// non-zero only if device_calls actually traversed the host-dispatch ring.
+extern "C" std::uint64_t cudaqx_qec_device_call_dispatch_count();
+
+namespace {
+std::string env_or(const char *name, const std::string &fallback) {
+  const char *value = std::getenv(name);
+  return (value && *value) ? std::string(value) : fallback;
+}
+
+void initialize_realtime_channel(const char *prog) {
+  std::vector<std::string> args = {prog};
+  if (const char *port = std::getenv("QEC_DECODING_SERVER_PORT");
+      port && *port) {
+    const std::string transport =
+        env_or("QEC_DECODING_SERVER_TRANSPORT", "udp");
+    if (transport == "cpu_roce") {
+      // The RDMA ring geometry (slots x slot-size) is part of the cpu_roce
+      // wire contract: the channel writes requests directly into the server's
+      // rings, so these must match decoding_server's --num-slots /
+      // --slot-size defaults (8 x 256).
+      args.push_back("--cudaq-device-call=cpu_roce");
+      args.push_back("--cudaq-device-call-slots=8");
+      args.push_back("--cudaq-device-call-slot-size=256");
+      args.push_back("ib-device=" +
+                     env_or("CUDAQ_CPU_ROCE_TEST_CHANNEL_DEVICE", "mlx5_0"));
+      args.push_back("local-ip=" +
+                     env_or("CUDAQ_CPU_ROCE_TEST_CHANNEL_IP", "10.0.0.1"));
+      args.push_back("rendezvous-host=" +
+                     env_or("CUDAQ_CPU_ROCE_TEST_DAEMON_IP", "10.0.0.2"));
+      args.push_back(std::string("rendezvous-port=") + port);
+    } else {
+      args.push_back("--cudaq-device-call=udp");
+      args.push_back("udp-host=127.0.0.1");
+      args.push_back(std::string("udp-port=") + port);
+    }
+  }
+  std::vector<char *> argv;
+  for (auto &arg : args)
+    argv.push_back(arg.data());
+  argv.push_back(nullptr);
+  int argc = static_cast<int>(args.size());
+  cudaq::realtime::initialize(argc, argv.data());
+}
+} // namespace
+#endif
+
+// Host-side decoding API (for syndrome capture)
+namespace cudaq::qec::decoding::host {
+void _set_syndrome_capture_callback(void (*callback)(const uint8_t *, size_t));
+}
+
+namespace {
+
+// Command-line options, parsed in main() and threaded through as a bundle.
+struct run_options {
+  int distance = 5;
+  int num_shots = 10;
+  double p_cnot = 0.001; // two-qubit depolarizing rate on the CNOTs
+  int num_logical = 1;
+  int num_rounds = -1; // defaults to distance
+  int seed = 42;       // simulator seed; < 0 leaves the simulator unseeded
+  std::string decoder_type = "multi_error_lut";
+  int sw_window_size =
+      -1; // sliding_window size in rounds; defaults to distance
+  int sw_step_size = 1;
+  bool save_dem = false;
+  bool load_dem = false;
+  std::string dem_filename;
+  bool save_syndrome = false;
+  bool load_syndrome = false;
+  std::string syndrome_filename;
+};
+
+// The per-experiment inputs derived once from the code + options: register
+// sizes, the stabilizer support vectors, and the logical observable. The
+// syndrome stream is, per logical qubit, `num_rounds` interior groups of
+// `num_ancx + num_ancz` bits followed by one data group of `num_data` bits.
+struct experiment {
+  std::size_t num_data = 0, num_ancx = 0, num_ancz = 0;
+  std::size_t num_rounds = 0, num_logical = 0, num_obs = 0;
+  std::vector<std::size_t> x_vec, z_vec, obs_flat;
+};
+
+// --save_syndrome capture state. The library callback is a bare
+// `void(*)(const uint8_t *, size_t)` with no user-data pointer, so the
+// captureless callback below reaches this through a global.
+struct syndrome_capture_state {
+  std::ofstream file;
+  std::mutex mutex;
+  int count = 0;
+  int syndromes_per_shot = 0; // groups written per shot
+  // True per-group bit widths, used to trim the byte-padded packed bytes the
+  // callback receives back to the exact measurement counts. The FPGA playback
+  // tool sets each replayed frame's num_syndromes from the group's line
+  // count, and the decoder's per-shot measurement capacity is the exact sum
+  // (num_rounds * interior + data) -- byte-padded groups would overrun it.
+  int groups_per_logical = 0; // num_rounds interior groups + 1 data group
+  int interior_width = 0;     // num_ancx + num_ancz bits
+  int data_width = 0;         // num_data bits
+};
+syndrome_capture_state g_capture;
+
+} // namespace
+
+// Build one decoder config per logical qubit from the decoder_inputs produced
+// by `decoder_context_from_memory_circuit(...).full_component()`. All decoders
+// share the same DEM (`H_sparse`), observables (`O_sparse`) and
+// measurement-to-detector map (`D_sparse`); only the decoder type/parameters
+// differ. Per-decoder args use the declarative `heterogeneous_map` schema
+// (`decoder_custom_args`) validated by `multi_decoder_config`.
+static cudaq::qec::decoding::config::multi_decoder_config
+build_multi_decoder_config(const cudaq::qec::decoder_inputs &inputs,
+                           std::size_t num_syndromes_per_round,
+                           std::size_t num_boundary_syndromes,
+                           const run_options &opts) {
+  namespace config = cudaq::qec::decoding::config;
+  const auto &dem = inputs.dem;
+  const auto d_sparse = cudaq::qec::d_sparse(inputs.m2d);
+
+  config::multi_decoder_config multi_config;
+  for (int i = 0; i < opts.num_logical; i++) {
+    config::decoder_config dc;
+    dc.id = i;
+    dc.block_size = dem.num_error_mechanisms();
+    dc.syndrome_size = dem.num_detectors();
+    dc.H_sparse = cudaq::qec::pcm_to_sparse_vec(dem.detector_error_matrix);
+    dc.O_sparse = cudaq::qec::pcm_to_sparse_vec(dem.observables_flips_matrix);
+    dc.D_sparse = d_sparse;
+
+    if (opts.decoder_type == "nv-qldpc-decoder") {
+      dc.type = "nv-qldpc-decoder";
+      cudaqx::heterogeneous_map nv_args;
+      nv_args.insert("use_sparsity", true);
+      nv_args.insert("error_rate_vec", dem.error_rates);
+      nv_args.insert("max_iterations", 50);
+      nv_args.insert("bp_method", 3);   // min-sum + dmem (required for relay)
+      nv_args.insert("composition", 1); // sequential relay
+      nv_args.insert("gamma0", 0.0);
+      nv_args.insert("clip_value", 200.0);
+      nv_args.insert("repeatable", true);
+      cudaqx::heterogeneous_map srelay_args;
+      srelay_args.insert("pre_iter", std::size_t{5});
+      srelay_args.insert("num_sets", std::size_t{10});
+      srelay_args.insert("stopping_criterion", "All");
+      srelay_args.insert("stop_nconv", std::size_t{1});
+      nv_args.insert("srelay_config", srelay_args);
+      nv_args.insert("gamma_dist", std::vector<double>{0.1, 0.2});
+      dc.decoder_custom_args = nv_args;
+    } else if (opts.decoder_type == "sliding_window") {
+      dc.type = "sliding_window";
+      cudaqx::heterogeneous_map sw_args;
+      sw_args.insert("window_size", opts.sw_window_size);
+      sw_args.insert("step_size", opts.sw_step_size);
+      sw_args.insert("num_syndromes_per_round", num_syndromes_per_round);
+      sw_args.insert("num_boundary_syndromes", num_boundary_syndromes);
+      sw_args.insert("straddle_start_round", false);
+      sw_args.insert("straddle_end_round", true);
+      sw_args.insert("inner_decoder_name", "multi_error_lut");
+      sw_args.insert("error_rate_vec", dem.error_rates);
+      cudaqx::heterogeneous_map inner_lut_args;
+      inner_lut_args.insert("lut_error_depth", 2);
+      sw_args.insert("inner_decoder_params", inner_lut_args);
+      dc.decoder_custom_args = sw_args;
+    } else if (opts.decoder_type == "pymatching") {
+      dc.type = "pymatching";
+      cudaqx::heterogeneous_map pm_args;
+      pm_args.insert("merge_strategy", "smallest_weight");
+      pm_args.insert("error_rate_vec", dem.error_rates);
+      dc.decoder_custom_args = pm_args;
+    } else {
+      dc.type = "multi_error_lut";
+      cudaqx::heterogeneous_map lut_args;
+      lut_args.insert("lut_error_depth", 2);
+      dc.decoder_custom_args = lut_args;
+    }
+
+    multi_config.decoders.push_back(dc);
+  }
+  return multi_config;
+}
+
+namespace cudaq::qec::qpu {
+
+// Per-logical memory circuit kernel. Preps the logical qubit, streams
+// `num_rounds` syndrome groups plus the final data readout to the decoder, and
+// returns that final data measurement. The decoder computes detectors from the
+// measurement-to-detector map (D_sparse).
+__qpu__ std::vector<cudaq::measure_result> memory_circuit(
+    cudaq::qview<> data, cudaq::qview<> xstab_anc, cudaq::qview<> zstab_anc,
+    const cudaq::qec::code::stabilizer_round &stab_round,
+    const cudaq::qec::code::one_qubit_encoding &state_prep,
+    std::size_t num_rounds, const std::vector<std::size_t> &x_stabilizers,
+    const std::vector<std::size_t> &z_stabilizers, std::int64_t decoder_id) {
+  patch logical(data, xstab_anc, zstab_anc);
+  state_prep(logical);
+
+  // Lock-in round (round 0)
+  auto syndrome = stab_round(logical, x_stabilizers, z_stabilizers);
+  cudaq::qec::decoding::enqueue_syndromes(decoder_id, syndrome);
+
+  // Rounds 1..num_rounds-1: stream raw syndromes
+  for (std::size_t r = 1; r < num_rounds; r++) {
+    auto s = stab_round(logical, x_stabilizers, z_stabilizers);
+    cudaq::qec::decoding::enqueue_syndromes(decoder_id, s);
+  }
+
+  // Final data readout
+  auto data_meas = mz(data);
+  cudaq::qec::decoding::enqueue_syndromes(decoder_id, data_meas);
+  return data_meas;
+}
+
+// Shot kernel: run an independent surface-code memory experiment on each of
+// `num_logical` logical qubits and return, per logical qubit, its logical
+// observable value updated by the decoder's correction
+//
+// Return layout: the low 32 bits hold, per logical qubit,
+// bit i = logical qubit i's corrected observable (so num_logical <= 32); the
+// high 32 bits hold how many corrections the decoders applied this shot.
+__qpu__ std::int64_t demo_circuit_qpu(
+    const cudaq::qec::code::stabilizer_round &stab_round,
+    const cudaq::qec::code::one_qubit_encoding &state_prep,
+    std::size_t num_data, std::size_t num_ancx, std::size_t num_ancz,
+    std::size_t num_rounds, std::size_t num_logical,
+    const std::vector<std::size_t> &x_stabilizers,
+    const std::vector<std::size_t> &z_stabilizers,
+    const std::vector<std::size_t> &obs_matrix_flat,
+    std::size_t num_observables, const std::vector<std::int64_t> &decoder_ids) {
+  cudaq::qvector data(num_logical * num_data),
+      xstab_anc(num_logical * num_ancx), zstab_anc(num_logical * num_ancz);
+
+  for (std::size_t i = 0; i < num_logical; i++)
+    cudaq::qec::decoding::reset_decoder(decoder_ids[i]);
+
+  std::uint64_t num_corrections = 0;
+  std::uint64_t ret = 0;
+  for (std::size_t i = 0; i < num_logical; i++) {
+    // Stream this logical's rounds + data readout to its decoder, keeping the
+    // single data measurement it returns.
+    auto data_meas = memory_circuit(
+        data.slice(i * num_data, num_data),
+        xstab_anc.slice(i * num_ancx, num_ancx),
+        zstab_anc.slice(i * num_ancz, num_ancz), stab_round, state_prep,
+        num_rounds, x_stabilizers, z_stabilizers, decoder_ids[i]);
+
+    // Raw logical observable (row 0 of the observable matrix) from that
+    // readout.
+    bool obs = false;
+    for (std::size_t q = 0; q < num_data; q++)
+      if (obs_matrix_flat[q] != 0 && data_meas[q])
+        obs = !obs;
+
+    // Update it by the decoder's predicted observable flip.
+    auto correction = cudaq::qec::decoding::get_corrections(
+        static_cast<std::uint64_t>(decoder_ids[i]), num_observables,
+        /*reset=*/false);
+    if (correction[0]) {
+      obs = !obs;
+      num_corrections++;
+    }
+
+    if (obs)
+      ret |= std::uint64_t{1} << i;
+  }
+  // Corrections in the high 32 bits
+  ret |= num_corrections << 32;
+  return ret;
+}
+} // namespace cudaq::qec::qpu
+
+namespace {
+
+// Gather the experiment inputs (register sizes, stabilizer supports, logical
+// observable) from the code once.
+experiment make_experiment(const cudaq::qec::code &code,
+                           cudaq::qec::operation state_prep,
+                           const run_options &opts) {
+  experiment exp;
+  exp.num_data = code.get_num_data_qubits();
+  exp.num_ancx = code.get_num_ancilla_x_qubits();
+  exp.num_ancz = code.get_num_ancilla_z_qubits();
+  exp.num_rounds = static_cast<std::size_t>(opts.num_rounds);
+  exp.num_logical = static_cast<std::size_t>(opts.num_logical);
+
+  auto schedule_x = code.get_stabilizer_schedule_x();
+  auto schedule_z = code.get_stabilizer_schedule_z();
+  exp.x_vec.assign(schedule_x.data(), schedule_x.data() + schedule_x.size());
+  exp.z_vec.assign(schedule_z.data(), schedule_z.data() + schedule_z.size());
+
+  const bool is_z_prep = state_prep == cudaq::qec::operation::prep0 ||
+                         state_prep == cudaq::qec::operation::prep1;
+  auto obs_matrix =
+      is_z_prep ? code.get_observables_z() : code.get_observables_x();
+  exp.num_obs = obs_matrix.shape()[0];
+  exp.obs_flat.assign(obs_matrix.data(), obs_matrix.data() + obs_matrix.size());
+  return exp;
+}
+
+// Configure the decoders for the run. Returns true if they are ready and the
+// caller should proceed to run shots; false if the run is complete (--save_dem
+// wrote the config and exited) or a file could not be opened.
+//
+// --load_dem and --save_dem are the two ends of the same YAML round-trip a
+// standalone decoding_server uses:
+//   --load_dem <file> : read a saved config (the decoders may live in a
+//                       separate decoding_server fed the same YAML).
+//   --save_dem <file> : characterize the DEM, write the config YAML, and exit.
+//   (default)         : characterize and configure the decoders in-process.
+bool setup_decoders(const cudaq::qec::code &code,
+                    cudaq::qec::operation state_prep, const run_options &opts,
+                    cudaq::noise_model &noise) {
+  namespace config = cudaq::qec::decoding::config;
+
+  if (opts.load_dem) {
+    std::ifstream config_file(opts.dem_filename);
+    if (!config_file)
+      throw std::runtime_error("Could not open dem config file: " +
+                               opts.dem_filename);
+    std::stringstream config_text;
+    config_text << config_file.rdbuf();
+    auto cfg = config::multi_decoder_config::from_yaml_str(config_text.str());
+    config::configure_decoders(cfg);
+    printf("Loaded decoder config from %s (%zu decoders)\n",
+           opts.dem_filename.c_str(), cfg.decoders.size());
+    return true;
+  }
+
+  // Characterize the DEM and build the decoder configuration. full_component()
+  // canonicalizes both stabilizer types (boundary-aware) into decoder_inputs.
+  const bool decompose_errors = (opts.decoder_type == "pymatching");
+  auto ctx = cudaq::qec::decoder_context_from_memory_circuit(
+      code, state_prep, opts.num_rounds, noise, decompose_errors);
+  const auto inputs = ctx.full_component();
+  printf("DEM: %ld detectors x %ld error mechanisms\n",
+         inputs.dem.num_detectors(), inputs.dem.num_error_mechanisms());
+
+  const bool is_z_prep = state_prep == cudaq::qec::operation::prep0 ||
+                         state_prep == cudaq::qec::operation::prep1;
+  const std::size_t num_x_stabilizers = code.get_num_ancilla_x_qubits();
+  const std::size_t num_z_stabilizers = code.get_num_ancilla_z_qubits();
+  const std::size_t num_syndromes_per_round =
+      num_x_stabilizers + num_z_stabilizers;
+  const std::size_t num_boundary_syndromes =
+      is_z_prep ? num_z_stabilizers : num_x_stabilizers;
+  auto cfg = build_multi_decoder_config(inputs, num_syndromes_per_round,
+                                        num_boundary_syndromes, opts);
+
+  if (opts.save_dem) {
+    // Serialize the config to YAML -- the inverse of the decoding server's
+    // multi_decoder_config::from_yaml_str -- and exit; no shots are run.
+    std::ofstream(opts.dem_filename) << cfg.to_yaml_str(200);
+    printf("Saved decoder config to %s\n", opts.dem_filename.c_str());
+    return false;
+  }
+
+  config::configure_decoders(cfg);
+  return true;
+}
+
+// --save_syndrome: register a callback that tees every syndrome the decoder
+// receives during the live run into `filename`, so it can be replayed offline.
+void begin_syndrome_capture(const std::string &filename,
+                            const experiment &exp) {
+  g_capture.file.open(filename, std::ios::out | std::ios::trunc);
+  if (!g_capture.file)
+    throw std::runtime_error("Could not open syndrome file for writing: " +
+                             filename);
+  g_capture.count = 0;
+  g_capture.syndromes_per_shot =
+      static_cast<int>(exp.num_logical * (exp.num_rounds + 1));
+  g_capture.groups_per_logical = static_cast<int>(exp.num_rounds + 1);
+  g_capture.interior_width = static_cast<int>(exp.num_ancx + exp.num_ancz);
+  g_capture.data_width = static_cast<int>(exp.num_data);
+
+  printf("Syndrome capture enabled: saving to %s\n", filename.c_str());
+  g_capture.file << "NUM_DATA " << exp.num_data << "\n";
+  g_capture.file << "NUM_LOGICAL " << exp.num_logical << "\n";
+  g_capture.file.flush();
+
+  cudaq::qec::decoding::host::_set_syndrome_capture_callback(
+      [](const uint8_t *data, size_t len) {
+        std::lock_guard<std::mutex> lock(g_capture.mutex);
+        if (!g_capture.file.is_open())
+          return;
+
+        if (g_capture.count % g_capture.syndromes_per_shot == 0)
+          g_capture.file << "SHOT_START "
+                         << (g_capture.count / g_capture.syndromes_per_shot)
+                         << "\n";
+        g_capture.file << "ROUND_START " << g_capture.count << "\n";
+
+        // Emit exactly the group's true bit count (the packed bytes are
+        // byte-padded): the first num_rounds groups per logical are interior
+        // syndrome rounds, the last is the data readout.
+        const int group_in_logical =
+            g_capture.count % g_capture.groups_per_logical;
+        const size_t width = static_cast<size_t>(
+            group_in_logical < g_capture.groups_per_logical - 1
+                ? g_capture.interior_width
+                : g_capture.data_width);
+        // Unpack MSB-first, one bit per line.
+        for (size_t k = 0; k < width && k < len * 8; k++)
+          g_capture.file << ((data[k / 8] >> (7 - (k % 8))) & 1) << "\n";
+        g_capture.file.flush();
+        g_capture.count++;
+      });
+}
+
+// Append the per-shot corrections so a later --load_syndrome run can verify the
+// replayed corrections against them, then close the capture file.
+void finish_syndrome_capture(const std::vector<std::int64_t> &run_result,
+                             const std::string &filename) {
+  if (!g_capture.file.is_open())
+    return;
+  cudaq::qec::decoding::host::_set_syndrome_capture_callback(nullptr);
+  g_capture.file << "CORRECTIONS_START\n";
+  for (auto shot : run_result)
+    g_capture.file << ((shot >> 32) > 0 ? 1 : 0) << "\n";
+  g_capture.file << "CORRECTIONS_END\n";
+  g_capture.file.close();
+  printf("Syndrome data saved to: %s\n", filename.c_str());
+}
+
+// --load_syndrome: replay a captured syndrome file through the decoders (no
+// circuit is run) and check the resulting corrections match the ones saved
+// alongside the syndromes.
+void replay_syndrome_file(const std::string &filename, const experiment &exp) {
+  printf("\n=== Syndrome Replay Mode ===\n");
+  printf("Loading syndromes from: %s\n", filename.c_str());
+
+  std::ifstream syndrome_file(filename);
+  if (!syndrome_file)
+    throw std::runtime_error("Could not open syndrome file: " + filename);
+
+  // Parse the header, then per shot a list of ROUND_START-delimited groups
+  // (each a byte-aligned, MSB-first bit dump), then the per-shot corrections.
+  std::size_t file_num_data = 0, file_num_logical = 0;
+  std::vector<uint8_t> saved_corrections;
+  std::vector<std::vector<std::vector<bool>>>
+      saved_shots; // shot -> group -> bits
+  std::string line;
+  while (std::getline(syndrome_file, line)) {
+    std::istringstream iss(line);
+    std::string tag;
+    iss >> tag;
+    if (tag == "NUM_DATA") {
+      iss >> file_num_data;
+    } else if (tag == "NUM_LOGICAL") {
+      iss >> file_num_logical;
+    } else if (tag == "SHOT_START") {
+      saved_shots.emplace_back();
+    } else if (tag == "ROUND_START") {
+      if (!saved_shots.empty())
+        saved_shots.back().emplace_back();
+    } else if (tag == "CORRECTIONS_START") {
+      while (std::getline(syndrome_file, line)) {
+        if (line.find("CORRECTIONS_END") == 0)
+          break;
+        saved_corrections.push_back(static_cast<uint8_t>(std::stoi(line)));
+      }
+      break;
+    } else if (!tag.empty() && !saved_shots.empty() &&
+               !saved_shots.back().empty()) {
+      // A bit line belonging to the current group.
+      saved_shots.back().back().push_back(std::stoi(tag) != 0);
+    }
+  }
+
+  if (file_num_data != exp.num_data || file_num_logical != exp.num_logical)
+    throw std::runtime_error(
+        "Syndrome file mismatch: file has num_data=" +
+        std::to_string(file_num_data) +
+        " num_logical=" + std::to_string(file_num_logical) +
+        ", expected num_data=" + std::to_string(exp.num_data) +
+        " num_logical=" + std::to_string(exp.num_logical));
+
+  printf("Read %zu shots with syndromes\n", saved_shots.size());
+  printf("Feeding %zu shots of saved syndromes to decoder...\n",
+         saved_shots.size());
+
+  int matched = 0, mismatched = 0;
+  // Per logical qubit the stream is num_rounds interior groups of
+  // (num_ancx + num_ancz) bits, then one data group of num_data bits. Each
+  // stored group is byte-padded, so trim it back to this true width.
+  const std::size_t groups_per_logical = exp.num_rounds + 1;
+  const std::size_t interior_width = exp.num_ancx + exp.num_ancz;
+  for (std::size_t shot = 0; shot < saved_shots.size(); shot++) {
+    for (std::size_t l = 0; l < exp.num_logical; l++)
+      cudaq::qec::decoding::reset_decoder(l);
+
+    // Feed each group to the logical qubit it belongs to.
+    const auto &groups = saved_shots[shot];
+    for (std::size_t g = 0; g < groups.size(); g++) {
+      const std::size_t logical_idx = g / groups_per_logical;
+      if (logical_idx >= exp.num_logical)
+        break;
+      const std::size_t group_in_logical = g % groups_per_logical;
+      const std::size_t width =
+          group_in_logical < exp.num_rounds ? interior_width : exp.num_data;
+      std::vector<bool> bits(groups[g].begin(),
+                             groups[g].begin() +
+                                 std::min(width, groups[g].size()));
+      cudaq::qec::decoding::enqueue_syndromes_test(logical_idx, bits);
+    }
+
+    uint8_t correction_bit = 0;
+    for (std::size_t l = 0; l < exp.num_logical; l++) {
+      auto corrections = cudaq::qec::decoding::get_corrections(l, 1, false);
+      for (auto c : corrections)
+        if (c)
+          correction_bit = 1;
+    }
+
+    if (shot < saved_corrections.size()) {
+      if (correction_bit == saved_corrections[shot]) {
+        matched++;
+      } else {
+        mismatched++;
+        if (mismatched <= 10)
+          printf("  Shot %zu: mismatch! Replayed=%u, Saved=%u\n", shot,
+                 correction_bit, saved_corrections[shot]);
+      }
+    }
+  }
+
+  printf("Replay complete: %zu shots processed\n", saved_shots.size());
+  if (!saved_corrections.empty()) {
+    printf("Correction verification: %d matched, %d mismatched\n", matched,
+           mismatched);
+    if (mismatched > 0)
+      throw std::runtime_error(
+          "Replay correction mismatch: " + std::to_string(mismatched) + " of " +
+          std::to_string(matched + mismatched) + " shots did not match");
+    printf("SUCCESS: All corrections match!\n");
+  }
+}
+
+// Run `num_shots` shots of the experiment. The kernel generates each round's
+// syndrome on the QPU (simulated locally, or emulated on the hardware target)
+// and streams it to the decoder in real time; the logical correction comes
+// back before readout. A remote platform applies its own noise, so the local
+// model is not attached there.
+std::vector<std::int64_t>
+run_shots(std::size_t num_shots, cudaq::noise_model &noise,
+          const cudaq::qec::code::stabilizer_round &stab_round,
+          const cudaq::qec::code::one_qubit_encoding &prep,
+          const experiment &exp, const std::vector<std::int64_t> &decoder_ids) {
+  return cudaq::get_platform().is_remote()
+             ? cudaq::run(num_shots, cudaq::qec::qpu::demo_circuit_qpu,
+                          stab_round, prep, exp.num_data, exp.num_ancx,
+                          exp.num_ancz, exp.num_rounds, exp.num_logical,
+                          exp.x_vec, exp.z_vec, exp.obs_flat, exp.num_obs,
+                          decoder_ids)
+             : cudaq::run(num_shots, noise, cudaq::qec::qpu::demo_circuit_qpu,
+                          stab_round, prep, exp.num_data, exp.num_ancx,
+                          exp.num_ancz, exp.num_rounds, exp.num_logical,
+                          exp.x_vec, exp.z_vec, exp.obs_flat, exp.num_obs,
+                          decoder_ids);
+}
+
+// Decode the per-shot results and print the logical error rate.
+void report_results(const std::vector<std::int64_t> &run_result,
+                    std::size_t num_logical) {
+  printf("Result size: %ld\n", run_result.size());
+  int num_non_zero_values = 0;
+  std::int64_t num_corrections = 0;
+  for (auto shot : run_result) {
+    // High 32 bits: number of corrections the decoder applied this shot.
+    num_corrections += (shot >> 32);
+    // Low 32 bits: each logical qubit's observable, already updated by the
+    // decoder's correction. A set bit is a residual logical error.
+    for (std::size_t j = 0; j < num_logical; j++)
+      if ((shot >> j) & 1)
+        num_non_zero_values++;
+  }
+  printf("Number of non-zero values measured : %d\n", num_non_zero_values);
+  printf("Number of corrections decoder found: %ld\n", num_corrections);
+}
+
+// The live-run path: (optionally) start capturing the syndrome stream, run the
+// shots and report the logical error rate, then (optionally) persist the
+// per-shot corrections for a later --load_syndrome.
+void run_experiment(const cudaq::qec::code &code,
+                    cudaq::qec::operation state_prep, const run_options &opts,
+                    cudaq::noise_model &noise, const experiment &exp,
+                    const std::vector<std::int64_t> &decoder_ids) {
+  if (opts.save_syndrome)
+    begin_syndrome_capture(opts.syndrome_filename, exp);
+
+  auto &prep =
+      code.get_operation<cudaq::qec::code::one_qubit_encoding>(state_prep);
+  auto &stab_round = code.get_operation<cudaq::qec::code::stabilizer_round>(
+      cudaq::qec::operation::stabilizer_round);
+
+  // Seed the simulator so the sampled shots -- and thus the reported logical
+  // error / correction counts (and any captured syndromes) -- are reproducible.
+  if (opts.seed >= 0)
+    cudaq::set_random_seed(static_cast<std::size_t>(opts.seed));
+  auto run_result =
+      run_shots(opts.num_shots, noise, stab_round, prep, exp, decoder_ids);
+  report_results(run_result, exp.num_logical);
+
+  if (opts.save_syndrome)
+    finish_syndrome_capture(run_result, opts.syndrome_filename);
+}
+
+} // namespace
+
+// Host-side driver: configure the decoders, then either replay a saved syndrome
+// file or run the circuit and report the logical error rate.
+void demo_circuit_host(const cudaq::qec::code &code, const run_options &opts) {
+  const auto state_prep = cudaq::qec::operation::prep0;
+
+  // Circuit-level two-qubit depolarizing noise on the stabilizer-extraction
+  // CNOTs, shared by DEM characterization and shot simulation.
+  cudaq::noise_model noise;
+  noise.add_all_qubit_channel("x",
+                              cudaq::qec::two_qubit_depolarization(opts.p_cnot),
+                              /*num_controls=*/1);
+
+  const experiment exp = make_experiment(code, state_prep, opts);
+
+  // Configure the decoders. --save_dem stops here (config written, no shots).
+  if (!setup_decoders(code, state_prep, opts, noise))
+    return;
+
+  // One decoder id per logical qubit, matching config ids 0..num_logical-1.
+  std::vector<std::int64_t> decoder_ids(exp.num_logical);
+  std::iota(decoder_ids.begin(), decoder_ids.end(), 0);
+
+  // Two paths: replay a captured syndrome file, or run the live circuit.
+  if (opts.load_syndrome)
+    replay_syndrome_file(opts.syndrome_filename, exp);
+  else
+    run_experiment(code, state_prep, opts, noise, exp, decoder_ids);
+}
+
+void show_help() {
+  printf("Usage: surface_code_realtime_decoding [options]\n");
+  printf("Options:\n");
+  printf("  --distance <int>      Distance of the surface code. Default: 5\n");
+  printf("  --num_shots <int>     Number of shots. Default: 10\n");
+  printf("  --p_cnot <double>     Two-qubit depolarizing rate on CNOT gates. "
+         "Range[0, 1]. Default: 0.001\n");
+  printf("  --num_logical <int>   Number of logical qubits. Default: 1\n");
+  printf("  --num_rounds <int>    Number of measurement rounds. Default: "
+         "distance\n");
+  printf("  --seed <int>          Simulator seed for reproducible shots; "
+         "negative leaves it unseeded. Default: 42\n");
+  printf("  --decoder_type <string> Decoder type: 'multi_error_lut', "
+         "'nv-qldpc-decoder', 'sliding_window', or 'pymatching'. Default: "
+         "multi_error_lut\n");
+  printf("  --sw_window_size <int>  Sliding window size (only for "
+         "sliding_window decoder). Default: distance\n");
+  printf("  --sw_step_size <int>    Sliding window step size. Default: 1\n");
+  printf("  --save_dem <string> Characterize the DEM, write the decoder config "
+         "YAML to a file, and exit (to configure a standalone "
+         "decoding_server).\n");
+  printf("  --load_dem <string> Load the decoder config from a YAML file "
+         "instead of characterizing in-process.\n");
+  printf("  --save_syndrome <string> Save syndrome data to a file for later "
+         "replay.\n");
+  printf("  --load_syndrome <string> Load and replay syndrome data from a "
+         "file.\n");
+  printf("  --help              Show this help message\n");
+}
+
+int main(int argc, char **argv) {
+  run_options opts;
+
+  // A value-taking option must not read past argv, and a malformed number
+  // must exit with a message instead of unwinding out of main.
+  try {
+    for (int i = 1; i < argc; i++) {
+      std::string arg = argv[i];
+      auto next_value = [&]() -> const char * {
+        if (i + 1 >= argc)
+          throw std::runtime_error(arg + " requires a value");
+        return argv[++i];
+      };
+      if (arg == "--distance") {
+        opts.distance = std::stoi(next_value());
+      } else if (arg == "--num_shots") {
+        opts.num_shots = std::stoi(next_value());
+      } else if (arg == "--p_cnot") {
+        opts.p_cnot = std::stod(next_value());
+      } else if (arg == "--help" || arg == "-h") {
+        show_help();
+        return 0;
+      } else if (arg == "--num_logical") {
+        opts.num_logical = std::stoi(next_value());
+      } else if (arg == "--num_rounds") {
+        opts.num_rounds = std::stoi(next_value());
+      } else if (arg == "--seed") {
+        opts.seed = std::stoi(next_value());
+      } else if (arg == "--decoder_type") {
+        opts.decoder_type = next_value();
+      } else if (arg == "--sw_window_size") {
+        opts.sw_window_size = std::stoi(next_value());
+      } else if (arg == "--sw_step_size") {
+        opts.sw_step_size = std::stoi(next_value());
+      } else if (arg == "--save_dem") {
+        opts.save_dem = true;
+        opts.dem_filename = next_value();
+      } else if (arg == "--load_dem") {
+        opts.load_dem = true;
+        opts.dem_filename = next_value();
+      } else if (arg == "--save_syndrome") {
+        opts.save_syndrome = true;
+        opts.syndrome_filename = next_value();
+      } else if (arg == "--load_syndrome") {
+        opts.load_syndrome = true;
+        opts.syndrome_filename = next_value();
+      } else {
+        printf("Unknown argument: %s\n", arg.c_str());
+        show_help();
+        return 1;
+      }
+    }
+  } catch (const std::invalid_argument &) {
+    printf("Error: invalid numeric value on the command line\n");
+    show_help();
+    return 1;
+  } catch (const std::exception &e) {
+    printf("Error: %s\n", e.what());
+    show_help();
+    return 1;
+  }
+
+  if (opts.save_syndrome && opts.load_syndrome) {
+    printf("Error: Cannot use both --save_syndrome and --load_syndrome "
+           "together\n");
+    return 1;
+  }
+
+  if (opts.save_dem && opts.load_dem) {
+    printf("Error: Cannot use both --save_dem and --load_dem together\n");
+    return 1;
+  }
+
+  // --save_dem only characterizes the DEM and writes the config; it never runs
+  // shots, so it can't be combined with the syndrome capture/replay options.
+  if (opts.save_dem && (opts.save_syndrome || opts.load_syndrome)) {
+    printf("Error: --save_dem cannot be combined with --save_syndrome or "
+           "--load_syndrome\n");
+    return 1;
+  }
+
+  if (opts.num_rounds == -1)
+    opts.num_rounds = opts.distance;
+  if (opts.sw_window_size == -1)
+    opts.sw_window_size = opts.distance;
+
+  if (opts.decoder_type != "multi_error_lut" &&
+      opts.decoder_type != "sliding_window" &&
+      opts.decoder_type != "nv-qldpc-decoder" &&
+      opts.decoder_type != "pymatching") {
+    printf("Error: --decoder_type must be 'multi_error_lut', "
+           "'nv-qldpc-decoder', 'sliding_window', or 'pymatching'\n");
+    return 1;
+  }
+
+  if (opts.num_rounds < opts.distance) {
+    printf("Error: num_rounds (%d) must be at least equal to distance (%d)\n",
+           opts.num_rounds, opts.distance);
+    return 1;
+  }
+
+  if (opts.num_logical > 32) {
+    printf("num_logical > 32 is not supported.\n");
+    return 1;
+  }
+
+  printf("Running with p_cnot = %f, distance = %d, num_shots = %d, "
+         "num_rounds = %d\n",
+         opts.p_cnot, opts.distance, opts.num_shots, opts.num_rounds);
+  auto code = cudaq::qec::get_code(
+      "surface_code", cudaqx::heterogeneous_map{{"distance", opts.distance}});
+
+#ifdef QEC_APP_CQR
+  // Bring up the cudaq-realtime device-call channel for the shots' decoding
+  // device_calls. The --save_dem pass only characterizes the DEM (no shots, no
+  // device_calls), so it needs no channel.
+  if (!opts.save_dem)
+    initialize_realtime_channel(argv[0]);
+#endif
+
+  try {
+    demo_circuit_host(*code, opts);
+  } catch (const std::exception &e) {
+    printf("Error: %s\n", e.what());
+    cudaq::qec::decoding::config::finalize_decoders();
+    return 1;
+  }
+
+#ifdef QEC_APP_CQR
+  if (!opts.save_dem) {
+    // With CUDAQ_DEVICE_CALL_CHANNEL=host_dispatch this proves the shots'
+    // device_calls crossed the ring to the in-process decoding server (it stays
+    // 0 if they bypassed to a trampoline, or a udp channel routed them to an
+    // external server instead).
+    printf("CQR service dispatch count: %llu\n",
+           static_cast<unsigned long long>(
+               cudaqx_qec_device_call_dispatch_count()));
+    cudaq::realtime::finalize();
+  }
+#endif
+
+  cudaq::qec::decoding::config::finalize_decoders();
+  return 0;
+}
diff --git a/docs/sphinx/examples_rst/qec/examples.rst b/docs/sphinx/examples_rst/qec/examples.rst
index 8bd215188..bfd00cb06 100644
--- a/docs/sphinx/examples_rst/qec/examples.rst
+++ b/docs/sphinx/examples_rst/qec/examples.rst
@@ -14,6 +14,7 @@ Examples that illustrate how to use CUDA-QX for application development are avai
       Improving Relay BP Decoding With Gamma Ensembles <nv_qldpc_gamma_ensemble_user_guide.rst>
       DEM Sampling <dem_sampling.rst>
       Real-Time Decoding <realtime_decoding.rst>
+      Realtime Decoding with CUDA-Q Decoding Server <realtime_decoding_demo.rst>
       AI Predecoder with CUDA-Q Realtime <realtime_predecoder_pymatching.rst>
       AI Predecoder with CUDA-Q Realtime (with FPGA Data Injection) <realtime_predecoder_fpga.rst>
       Relay BP Decoding with CUDA-Q Realtime <realtime_relay_bp.rst>
diff --git a/docs/sphinx/examples_rst/qec/realtime_decoding_demo.rst b/docs/sphinx/examples_rst/qec/realtime_decoding_demo.rst
new file mode 100644
index 000000000..635b95bb4
--- /dev/null
+++ b/docs/sphinx/examples_rst/qec/realtime_decoding_demo.rst
@@ -0,0 +1,284 @@
+Realtime Decoding with CUDA-Q Decoding Server
+=============================================
+
+.. note::
+
+   This page describes a C++ example that you compile against the *installed*
+   CUDA-QX SDK. The decoding server and the FPGA playback tool it drives are
+   **deliverables** — prebuilt and installed alongside the SDK, not built from
+   this example.
+
+This example drives the delivered ``decoding_server`` from two different
+syndrome sources, both decoding through the **same prebuilt server**:
+
+- ``--source qpu-kernel`` — a lowered QEC kernel supplies syndromes itself over
+  **UDP**, in software. No NIC, no FPGA. This is the portable, hardware-free
+  path and is what CI exercises. With ``--wire cpu_roce`` the same kernel
+  carries its syndromes over **real RDMA** between two RoCE-capable ports
+  instead.
+- ``--source fpga`` — the delivered ``hsb_fpga_syndrome_playback`` tool
+  streams pre-generated syndromes over **RoCE from a real FPGA** into the
+  server's RDMA ring. Requires a ConnectX NIC cabled to the FPGA. There is no
+  emulator here.
+
+Both sources decode with any of three decoders — ``pymatching``,
+``multi_error_lut`` (CPU lookup table), and ``nv-qldpc-decoder`` (GPU
+relay-BP) — plus an opt-in fourth, ``trt_decoder`` (the Ising neural-network
+predecoder on TensorRT + a PyMatching global decoder; see
+`Ising decoder (TensorRT predecoder + PyMatching)`_). Runs are seeded
+(``--seed``, default 42), so the reported counts are reproducible.
+
+For the nv-qldpc Relay BP device-graph walkthrough see
+:doc:`/examples_rst/qec/realtime_relay_bp`; for the software-only pymatching
+benchmark see :doc:`/examples_rst/qec/realtime_predecoder_pymatching`.
+
+
+Deliverables versus the example
+-------------------------------
+
+**Deliverables** (installed, not built by this example):
+
+- ``decoding_server`` — the standalone server that owns the decoder instances.
+- ``hsb_fpga_syndrome_playback`` — the FPGA playback tool (present only in
+  the hololink-enabled deliverable image).
+- the QEC + realtime libraries and the decoder plugins.
+
+**The example** (the only thing you compile) is two sources, each built two
+ways against the installed SDK — using only installed headers and libraries:
+
+- ``surface_code_realtime_decoding`` — the **generator** (``--target stim``):
+  writes the decoder configuration and, for the FPGA source, a syndrome file.
+- ``surface_code_realtime_decoding-cqr`` — the **lowered kernel**
+  (``-frealtime-lowering -DQEC_APP_CQR``): the live
+  syndrome source that streams to the server over UDP or cpu_roce.
+- ``surface_code_ising_realtime_decoding`` / ``…-cqr`` — the same pair for the
+  opt-in Ising ``trt_decoder`` profile (a separate source whose measurement
+  layout matches the Ising artifacts; see the Ising section below).
+
+
+Building the example
+--------------------
+
+.. code-block:: bash
+
+   cmake -S . -B build \
+     -DCUDAQ_INSTALL_DIR=<cuda-quantum install prefix> \
+     -DCUDAQX_INSTALL_DIR=<cuda-qx install prefix>
+   cmake --build build
+
+In a CUDA-QX container ``CUDAQ_INSTALL_DIR`` defaults to ``/usr/local/cudaq``.
+If the realtime libraries are in a separate prefix, add
+``-DCUDAQ_REALTIME_DIR=<realtime prefix>``. The lowered kernel links the
+realtime dispatch archive (relocatable CUDA device code), so the build needs a
+CUDA toolchain; the device-link architecture defaults to ``80`` (Ampere) —
+override with ``-DCMAKE_CUDA_ARCHITECTURES=90`` for Hopper or
+``-DCMAKE_CUDA_ARCHITECTURES=100`` for Blackwell (e.g. GB200).
+
+
+Running
+-------
+
+``run_realtime_decoding.sh`` resolves the deliverables from ``--install-prefix``
+and the two example binaries from ``--example-build-dir`` (default ``./build``).
+
+QPU-kernel source (software, UDP, no hardware)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   ./run_realtime_decoding.sh --source qpu-kernel --decoder pymatching            --install-prefix <prefix>
+   ./run_realtime_decoding.sh --source qpu-kernel --decoder multi_error_lut       --install-prefix <prefix>
+   ./run_realtime_decoding.sh --source qpu-kernel --decoder nv-qldpc-decoder --gpu 0 --install-prefix <prefix>
+
+The lowered kernel runs the surface-code memory experiment and streams each
+shot's syndromes to the server over the ``udp`` wire; every decoder is served
+on ``host`` dispatch (a server CPU thread calls the decoder — nv-qldpc still
+decodes on its GPU) and the corrections come back before readout.
+
+QPU-kernel source over real RDMA (``--wire cpu_roce``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The same lowered kernel can carry its syndromes over the ``cpu_roce`` wire
+instead: its channel RDMA-writes each request straight into the server's ring.
+This needs two RoCE-capable ports that can reach each other (kernel side =
+*channel*, server side = *daemon*) — e.g. loopback-cabled ConnectX ports, or
+SoftRoCE (``rdma_rxe``) devices. The topology comes from the same environment
+variables as the in-tree cpu_roce tests; ``--setup-network`` assigns the IPs
+and waits for the RoCE v2 GIDs:
+
+.. code-block:: bash
+
+   export CUDAQ_CPU_ROCE_TEST_CHANNEL_DEVICE=<kernel-side ibdev>   # e.g. mlx5_0
+   export CUDAQ_CPU_ROCE_TEST_DAEMON_DEVICE=<server-side ibdev>    # e.g. mlx5_1
+   # IPs default to 10.0.0.1 (channel) / 10.0.0.2 (daemon); override with
+   # CUDAQ_CPU_ROCE_TEST_CHANNEL_IP / CUDAQ_CPU_ROCE_TEST_DAEMON_IP.
+
+   ./run_realtime_decoding.sh --source qpu-kernel --decoder pymatching            --wire cpu_roce --setup-network --install-prefix <prefix>
+   ./run_realtime_decoding.sh --source qpu-kernel --decoder multi_error_lut       --wire cpu_roce --setup-network --install-prefix <prefix>
+   ./run_realtime_decoding.sh --source qpu-kernel --decoder nv-qldpc-decoder --gpu 0 --wire cpu_roce --setup-network --install-prefix <prefix>
+
+The server's READY ``port=`` is then the TCP rendezvous port (the RDMA wire
+itself is negotiated via the QP/rkey exchange); dispatch stays ``host``, and
+the same pass/fail criteria apply unchanged.
+
+FPGA source (real FPGA over RoCE)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   ./run_realtime_decoding.sh --source fpga --decoder pymatching \
+       --setup-network --device <nic> --bridge-ip <host-ip> --fpga-ip <fpga-ip> \
+       --install-prefix <prefix>
+
+   ./run_realtime_decoding.sh --source fpga --decoder multi_error_lut \
+       --setup-network --device <nic> --bridge-ip <host-ip> --fpga-ip <fpga-ip> \
+       --install-prefix <prefix>
+
+   ./run_realtime_decoding.sh --source fpga --decoder nv-qldpc-decoder --gpu 0 \
+       --setup-network --device <nic> --bridge-ip <host-ip> --fpga-ip <fpga-ip> \
+       --install-prefix <prefix>
+
+``--setup-network`` configures the ConnectX interface (needs ``sudo``);
+``--spacing`` (default 10 µs) paces the playback so it does not overrun the
+server's 64-slot RDMA RX ring. The playback timer fires once per **frame**
+(one BRAM window), so a shot spans frames-per-shot × spacing. The
+``nv-qldpc-decoder`` profiles auto-pace slower — 100 µs per frame — because
+the GPU decode cannot drain the ring at 10 µs; an explicit ``--spacing``
+always wins (``trt_decoder`` auto-paces the same way).
+
+The server has two independent knobs, both derived automatically (override
+with ``--wire`` / ``--dispatch``): the **wire** is the bridge-provider library
+that carries syndromes into the server, and the **dispatch** is the engine
+consuming each decoder's ring. ``pymatching`` and ``multi_error_lut`` ride the
+``cpu_roce`` wire on ``host`` dispatch (a server CPU thread calls the
+decoder); ``nv-qldpc-decoder --gpu 0`` defaults to the ``hololink`` wire on
+``device_graph`` dispatch (the GPU device-call scheduler fires the Relay BP
+decode graph on-device) and can be forced onto the host path with
+``--dispatch host``.
+
+Both sources apply real pass/fail criteria. The qpu-kernel source uses the
+same checks as the in-tree surface-code tests — no decoder errors, a residual
+logical-error ceiling of ``num_shots/50``, an in-process dispatch count of 0
+(proof the decode stayed in the external server), and a server dispatch-count
+floor of ``num_shots * (num_rounds + 3)``. The FPGA source verifies every
+shot's corrections against the expected values computed at
+syndrome-generation time (the playback tool's per-shot verification).
+
+
+Ising decoder (TensorRT predecoder + PyMatching)
+------------------------------------------------
+
+The ``trt_decoder`` profile decodes with the published **Ising neural-network
+predecoder** (a TensorRT engine built from its ONNX export) chained into a
+PyMatching global decoder — the same decoder stack, served by the same
+``decoding_server``, over any of the wires above (host dispatch only).
+
+This profile is **opt-in** and never runs in CI: the model weights are a gated
+Hugging Face download, and the decoder inputs are prepared locally into a
+six-file *artifact directory* passed via ``--ising-artifacts-dir`` (or the
+``QEC_ISING_ARTIFACTS_DIR`` environment variable):
+
+``model.onnx`` (the exported predecoder), ``H_csr.bin`` / ``O_csr.bin``
+(detector-error and observables matrices, Ising detector order),
+``priors.bin`` (per-mechanism priors), ``metadata.txt`` (the contract:
+``basis=Z``, ``code_rotation=XV``, ``distance=7``, ``n_rounds=7``), and
+``D_sparse.txt`` (each Ising detector as a parity over this example's live
+measurement stream). A missing or incomplete directory makes the profile
+**skip** (exit 77) listing the absent files by name.
+
+The profile is pinned to the published model's operating point: distance 7,
+7 rounds, Z basis, XV orientation, SPAM noise ``--p-spam`` (default 0.01,
+replacing ``--p-cnot``). It runs its own example pair —
+``surface_code_ising_realtime_decoding``/``-cqr``, built from the same
+CMake configure — whose measurement layout matches the artifacts' binding
+(the sibling ``surface_code_realtime_decoding`` source uses a different
+orientation and per-round bit order and cannot consume these artifacts).
+
+.. code-block:: bash
+
+   ./run_realtime_decoding.sh --source qpu-kernel --decoder trt_decoder \
+       --ising-artifacts-dir <dir> --install-prefix <prefix>
+
+   ./run_realtime_decoding.sh --source qpu-kernel --decoder trt_decoder --wire cpu_roce \
+       --setup-network --ising-artifacts-dir <dir> --install-prefix <prefix>
+
+   ./run_realtime_decoding.sh --source fpga --decoder trt_decoder \
+       --setup-network --device <nic> --bridge-ip <host-ip> --fpga-ip <fpga-ip> \
+       --ising-artifacts-dir <dir> --install-prefix <prefix>
+
+On the FPGA source the playback BRAM (512 frames) caps this geometry at **56
+shots** per run (9 frames per shot: 8 syndrome slices + 1 corrections frame);
+the script defaults to exactly that, and also raises the per-frame
+``--spacing`` to 100 µs for this profile — at the default 10 µs the stream
+outruns the served rate and overruns the server's 64-slot RX ring (about 7
+shots of buffer).
+
+Preparing the artifact directory (once, on a machine with an NVIDIA GPU —
+the pinned workflow runs GPU inference for the export) is automated by the
+``prepare_ising_artifacts.py`` script that ships in this example's directory:
+
+1. Accept the gated model terms at
+   ``https://huggingface.co/nvidia/Ising-Decoder-SurfaceCode-1-Fast`` and
+   authenticate the ``hf`` CLI (``hf auth login``). The script also needs
+   ``git``, ``bash``, and the Ising exporter's Python packages
+   (``beliefmatching hydra ldpc matplotlib numpy omegaconf onnx pymatching
+   safetensors scipy stim torch``; on aarch64 install torch from a CUDA
+   wheel index).
+2. Run (from this example's directory, after building the example)::
+
+      python prepare_ising_artifacts.py \
+          --app build/surface_code_ising_realtime_decoding \
+          --artifacts-dir <dir>
+
+   This sparse-checkouts the pinned Ising-Decoding revision, downloads the
+   gated weights, exports the Z-basis ONNX model, generates the decoder
+   matrices, captures THIS example's printed CNOT schedules to build a
+   matching ``D_sparse.txt``, validates the six files, and installs them
+   atomically at ``<dir>``.
+
+For a custom Ising export, the script's ``d-sparse`` subcommand regenerates
+just the measurement mapping from a saved schedule printout — see
+``python prepare_ising_artifacts.py d-sparse --help``.
+
+Decoders
+--------
+
+.. list-table::
+   :header-rows: 1
+
+   * - decoder
+     - qpu-kernel (udp / cpu_roce wire)
+     - fpga (real FPGA)
+     - extra requirement
+   * - ``pymatching``
+     - CPU (udp: no hardware)
+     - NIC
+     - none
+   * - ``multi_error_lut``
+     - CPU (udp: no hardware)
+     - NIC
+     - none
+   * - ``nv-qldpc-decoder``
+     - GPU (host dispatch)
+     - NIC + GPU (device_graph dispatch)
+     - plugin + ``--gpu``
+   * - ``trt_decoder``
+     - GPU (host dispatch)
+     - NIC + GPU (host dispatch)
+     - TRT plugin + Ising artifacts (opt-in)
+
+The ``nv-qldpc-decoder`` profile needs the prebuilt plugin — auto-found in the
+install prefix, else ``--nv-qldpc-plugin <path.so>`` — and a GPU; if the plugin
+is unavailable the script exits ``77`` (skip).
+
+
+The example source
+------------------
+
+The Ising profile builds its own companion source,
+``surface_code_ising_realtime_decoding.cpp`` (plus the shipped
+``prepare_ising_artifacts.py`` used during artifact preparation), in
+the same example directory. The primary example source:
+
+.. literalinclude:: ../../examples/qec/realtime_decoding_demo/surface_code_realtime_decoding.cpp
+   :language: cpp
diff --git a/docs/sphinx/examples_rst/qec/realtime_relay_bp.rst b/docs/sphinx/examples_rst/qec/realtime_relay_bp.rst
index bb3fef278..f680c0786 100644
--- a/docs/sphinx/examples_rst/qec/realtime_relay_bp.rst
+++ b/docs/sphinx/examples_rst/qec/realtime_relay_bp.rst
@@ -15,6 +15,17 @@ configurations:
 - **Emulated end-to-end test** -- software FPGA emulator replaces real hardware
 - **FPGA end-to-end test** -- real FPGA connected via ConnectX RDMA/RoCE
 
+.. tip::
+
+   To run the nv-qldpc Relay BP decoder end-to-end against the delivered
+   ``decoding_server`` -- from either a real FPGA (GPU device-graph path) or a
+   lowered QPU kernel over UDP (GPU host-call path) -- use the
+   :doc:`/examples_rst/qec/realtime_decoding_demo` example with
+   ``--decoder nv-qldpc-decoder --gpu 0``. That example compiles against the
+   installed SDK and resolves the server + playback tool from the install
+   prefix. This page documents the underlying device-graph scheduler and its
+   emulator-based testing.
+
 Decode dispatch architecture
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/libs/qec/unittests/utils/CMakeLists.txt b/libs/qec/unittests/utils/CMakeLists.txt
index 4c4c9754f..cbfd7fdb1 100644
--- a/libs/qec/unittests/utils/CMakeLists.txt
+++ b/libs/qec/unittests/utils/CMakeLists.txt
@@ -200,6 +200,15 @@ target_link_libraries(hsb_fpga_syndrome_playback
     CUDA::cuda_driver
     Threads::Threads)
 
+# Ship the FPGA syndrome-playback tool as a deliverable alongside decoding_server
+# (see tools/decoding-server/CMakeLists.txt). This whole file is already gated by
+# the HSB tools, so this install is a no-op in the vanilla release and is
+# present only in the HSB-enabled deliverable image. The
+# realtime_decoding_demo example resolves this tool from the install prefix.
+install(TARGETS hsb_fpga_syndrome_playback
+  COMPONENT qec-tools
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
 # =========================================================================== #
 # gpu_roce_qldpc_graph_decoder_bridge
 # =========================================================================== #
diff --git a/libs/qec/unittests/utils/hsb_fpga_decoding_server_test.sh b/libs/qec/unittests/utils/hsb_fpga_decoding_server_test.sh
index 1872c4158..309ffe12c 100755
--- a/libs/qec/unittests/utils/hsb_fpga_decoding_server_test.sh
+++ b/libs/qec/unittests/utils/hsb_fpga_decoding_server_test.sh
@@ -108,8 +108,9 @@ GEN_SHOTS=100
 TRANSPORT=""
 # GPU for the gpu_roce scheduler + decode graph.
 GPU_ID=0
-# Server-side GPU RoCE ring depth. "auto" chooses a page count whose total
-# allocation satisfies the host page-size requirement.
+# Server-side GPU RoCE ring depth. "auto" uses the HSB QP's 64-entry receive
+# WQE depth (rings deeper than the WQE count drop frames under load); explicit
+# values above it are clamped.
 GPU_ROCE_NUM_PAGES=auto
 
 # Runtime nv-qldpc plugin for the Relay BP profile: the prebuilt
@@ -124,7 +125,8 @@ NV_QLDPC_PLUGIN="${CUDAQ_QEC_NV_QLDPC_PLUGIN:-}"
 
 # Network defaults
 IB_DEVICE=""           # auto-detect
-BRIDGE_IP="10.0.0.1"   # server-side NIC IP (kept the qldpc script's name)
+BRIDGE_IP=""           # resolved after arg parsing (kept the qldpc script's
+                       # name): emulate -> 10.0.0.1, real FPGA -> 192.168.0.1
 EMULATOR_IP="10.0.0.2"
 FPGA_IP="192.168.0.2"
 MTU=4096
@@ -133,10 +135,10 @@ MTU=4096
 TIMEOUT=60
 NUM_SHOTS=""
 PAGE_SIZE=384
-# CPU RoCE server ring slots.
+# RX ring depth for both transports, bounded by the HSB QP's 64 receive WQEs (a
+# ring with more slots than WQEs drops frames under load). The server clamps
+# cpu_roce --num-slots to this; the gpu_roce ring is capped to it below.
 NUM_SLOTS=64
-# FPGA/emulator playback window pages.
-PLAYBACK_NUM_PAGES=512
 # TX SGE bytes for the server's SEND responses.  RPCResponse (24B) + a
 # bit-packed correction byte fits well inside 64, keeping every response a
 # single 512-bit ILA beat.
@@ -208,7 +210,9 @@ Build options:
 
 Network options:
   --device DEV           ConnectX IB device name (default: auto-detect)
-  --bridge-ip ADDR       Server-side NIC IP (default: 10.0.0.1)
+  --bridge-ip ADDR       Server-side NIC IP (default: 10.0.0.1 with
+                         --emulate, 192.168.0.1 on the real FPGA; must share
+                         the FPGA's /24 in FPGA mode)
   --emulator-ip ADDR     Emulator IP (default: 10.0.0.2)
   --fpga-ip ADDR         FPGA IP for non-emulate mode (default: 192.168.0.2)
   --mtu N                MTU size (default: 4096)
@@ -221,10 +225,15 @@ Run options:
   --frame-size N         Server TX SGE bytes, cpu_roce only (default: 64;
                          gpu_roce uses page-size as QEC_DEVICE_GRAPH_FRAME_SIZE)
   --gpu N                GPU device id for gpu_roce (default: 0)
-  --gpu-roce-num-pages N Server GPU RoCE ring pages (default: auto-align;
-                         starts from playback window pages)
-  --playback-num-pages N FPGA/emulator playback window pages (default: 512)
-  --spacing N            Inter-shot spacing in microseconds (default: 10)
+  --gpu-roce-num-pages N Server GPU RoCE ring slots (default: the HSB 64-WQE
+                         depth; values above it are clamped, since a ring with
+                         more slots than WQEs drops frames)
+  --spacing N            Per-frame playback pacing in microseconds (default:
+                         10; the FPGA timer fires once per frame, so a shot
+                         spans frames-per-shot x spacing). The slow-decode
+                         profiles trt_decoder and nv-qldpc-decoder default
+                         to 100 instead, so the playback stream cannot
+                         overrun the 64-slot RX ring mid-decode
   --control-port N       UDP control port for emulator (default: 8193)
 
   --help, -h             Show this help
@@ -243,7 +252,6 @@ while [[ $# -gt 0 ]]; do
         --transport)        TRANSPORT="$2"; shift ;;
         --gpu)              GPU_ID="$2"; shift ;;
         --gpu-roce-num-pages) GPU_ROCE_NUM_PAGES="$2"; shift ;;
-        --playback-num-pages) PLAYBACK_NUM_PAGES="$2"; shift ;;
         --nv-qldpc-plugin)  NV_QLDPC_PLUGIN="$2"; shift ;;
         --config)           CONFIG_FILE="$2"; shift ;;
         --syndromes)        SYNDROMES_FILE="$2"; shift ;;
@@ -277,6 +285,22 @@ while [[ $# -gt 0 ]]; do
     shift
 done
 
+# Resolve the server-side NIC IP by mode: the emulate loop lives on
+# 10.0.0.0/24, the real FPGA on 192.168.0.0/24.  A bridge IP outside the
+# FPGA's subnet does not fail loudly -- the HSB control plane just
+# times out (read_uint32) as if the FPGA were dead -- so reject the
+# mismatch up front instead of letting it masquerade as broken hardware.
+if [[ -z "$BRIDGE_IP" ]]; then
+    if $EMULATE; then BRIDGE_IP="10.0.0.1"; else BRIDGE_IP="192.168.0.1"; fi
+fi
+if ! $EMULATE && [[ "${BRIDGE_IP%.*}" != "${FPGA_IP%.*}" ]]; then
+    echo "ERROR: --bridge-ip $BRIDGE_IP is not in the FPGA's /24 subnet" >&2
+    echo "       ($FPGA_IP): the HSB control plane would time out" >&2
+    echo "       (read_uint32) as if the FPGA were unreachable.  Pass a" >&2
+    echo "       matching --bridge-ip/--fpga-ip pair." >&2
+    exit 1
+fi
+
 # Derive the transport from the decoder profile unless explicitly chosen.
 if [[ -z "$TRANSPORT" ]]; then
     case "$DECODER" in
@@ -289,20 +313,60 @@ if [[ "$TRANSPORT" != "cpu_roce" && "$TRANSPORT" != "gpu_roce" ]]; then
     exit 1
 fi
 
-# Some DOCA registrations require the gpu_roce server ring allocation to be
-# host-page aligned. Keep playback capacity independent from the server ring,
-# and choose a server page count that satisfies the allocation contract.
-if [[ "$TRANSPORT" == "gpu_roce" && "$GPU_ROCE_NUM_PAGES" == "auto" ]]; then
-    HOST_PAGE_SIZE=$(getconf PAGESIZE 2>/dev/null || echo 4096)
-    SERVER_PAGE_SIZE=$(( ((PAGE_SIZE + 127) / 128) * 128 ))
-    GPU_ROCE_NUM_PAGES="$PLAYBACK_NUM_PAGES"
-    while (( (SERVER_PAGE_SIZE * GPU_ROCE_NUM_PAGES) % HOST_PAGE_SIZE != 0 )); do
-        ((GPU_ROCE_NUM_PAGES++))
-        if (( GPU_ROCE_NUM_PAGES > 65536 )); then
-            echo "ERROR: unable to auto-align gpu_roce ring for page-size=$PAGE_SIZE host-page-size=$HOST_PAGE_SIZE" >&2
-            exit 1
-        fi
-    done
+# Per-decoder playback pacing.  The playback engine's timer fires once per
+# FRAME (one BRAM window per frame), so --spacing is per-frame pacing and a
+# shot spans frames-per-shot x spacing on the wire.  A profile whose
+# per-shot decode latency exceeds that arrival window overruns the 64-slot
+# RX ring (dropped enqueues mis-assemble a shot's volume and the decode dies
+# with an invalid-syndrome matching error; the ILA sample count comes up
+# short).  For this test's profiles the slow ones are trt_decoder (fixed
+# per-invocation TensorRT engine overhead at batch 1) and nv-qldpc-decoder
+# (iterative relay-BP); pymatching decodes these d3 volumes in microseconds
+# and keeps the unpaced default -- the tightly paced path is part of what
+# its profile exercises.
+#
+# 100us clears every measured floor on this loop with margin: at d3/T4 the
+# host-dispatch runs fail at 25us (nv-qldpc) and 10us (trt) and pass at
+# 100us, and 100us is the validated value for the device-graph scheduler.
+# --spacing overrides.
+if [[ -z "$SPACING" ]]; then
+    case "$DECODER" in
+        trt_decoder|nv-qldpc-decoder) SPACING=100 ;;
+    esac
+fi
+
+# The HSB QP exposes a fixed 64-entry receive WQE depth, and the receiver
+# pre-posts one WQE per ring slot. A ring with MORE slots than WQEs leaves slots
+# un-posted and drops frames under load: cpu_roce (whose registered MR is only
+# num_slots wide) fails outright, and gpu_roce (deeper MR) drops occasionally.
+# So both transports cap the RX ring at the WQE depth -- cpu_roce via
+# NUM_SLOTS (the server clamps its --num-slots the same way), gpu_roce here.
+readonly HSB_WQE_DEPTH=64
+if (( NUM_SLOTS > HSB_WQE_DEPTH )); then
+    echo "WARNING: NUM_SLOTS=$NUM_SLOTS exceeds the HSB WQE depth" \
+         "($HSB_WQE_DEPTH); clamping so the playback ring modulus matches the" \
+         "server's clamped RX ring" >&2
+    NUM_SLOTS="$HSB_WQE_DEPTH"
+fi
+if [[ "$TRANSPORT" == "gpu_roce" ]]; then
+    if [[ "$GPU_ROCE_NUM_PAGES" == "auto" ]]; then
+        GPU_ROCE_NUM_PAGES="$HSB_WQE_DEPTH"
+    elif (( GPU_ROCE_NUM_PAGES > HSB_WQE_DEPTH )); then
+        echo "WARNING: --gpu-roce-num-pages=$GPU_ROCE_NUM_PAGES exceeds the HSB WQE" \
+             "depth ($HSB_WQE_DEPTH); clamping to $HSB_WQE_DEPTH to avoid dropped frames" >&2
+        GPU_ROCE_NUM_PAGES="$HSB_WQE_DEPTH"
+    fi
+    # DOCA requires the gpu_roce ring allocation (num_pages * page size) to be
+    # a multiple of the HOST page size (GpuRoceTransceiver rejects it at
+    # startup otherwise). 64 x 384 B = 24 KiB satisfies 4K/8K-page kernels;
+    # 16K/64K-page hosts (some aarch64 configs) need a larger stride.
+    host_page=$(getconf PAGESIZE)
+    if (( (GPU_ROCE_NUM_PAGES * PAGE_SIZE) % host_page != 0 )); then
+        echo "ERROR: gpu_roce ring ($GPU_ROCE_NUM_PAGES pages x $PAGE_SIZE B) is not a multiple of" >&2
+        echo "       this host's page size ($host_page B). Pass --page-size <multiple of" >&2
+        echo "       $(( host_page / GPU_ROCE_NUM_PAGES ))> so the WQE-depth ring stays host-page aligned." >&2
+        exit 1
+    fi
 fi
 
 # ============================================================================
@@ -987,8 +1051,16 @@ start_server() {
     _log "Starting decoding server (decoder=$DECODER, transport=$TRANSPORT," \
          "remote-qp=$remote_qp)"
 
-    local server_ld_path
-    server_ld_path="${CUDA_QUANTUM_DIR}/realtime/build/lib:${CUDAQX_DIR}/build/lib"
+    # The server dlopens the realtime bridge providers and needs the
+    # cudaq-realtime that matches .cudaq_version. Prefer an explicit
+    # CUDAQ_REALTIME_LIB_DIR, then the conventional realtime build dirs.
+    local server_ld_path rt_lib=""
+    for d in "${CUDAQ_REALTIME_LIB_DIR:-}" \
+             "${CUDA_QUANTUM_DIR}/realtime/build-bridge/lib" \
+             "${CUDA_QUANTUM_DIR}/realtime/build/lib"; do
+        [[ -n "$d" && -f "$d/libcudaq-realtime.so" ]] && { rt_lib="$d"; break; }
+    done
+    server_ld_path="${rt_lib}:${CUDAQX_DIR}/build/lib"
 
     local ready_pattern
     if [[ "$TRANSPORT" == "gpu_roce" ]]; then
@@ -1019,7 +1091,7 @@ start_server() {
         LD_LIBRARY_PATH="${server_ld_path}:${LD_LIBRARY_PATH:-}" \
         "$SERVER_BIN" \
             --config="$CONFIG_FILE" \
-            --transport=cpu_roce \
+            --transport=cpu-roce \
             --qp_config=hsb_fpga \
             --device="$BRIDGE_DEVICE" \
             --peer-ip="$peer_ip" \
@@ -1053,11 +1125,13 @@ start_server() {
         return 1
     }
 
-    # The transceiver publishes the provider's endpoint description verbatim
-    # (one `key=value ...` line); pull the RDMA rendezvous tokens the
-    # playback tool needs out of it.
+    # The RDMA rendezvous tokens (qp=/rkey=/buffer_addr=) are published on ONE
+    # line: the device-graph transceiver prints a dedicated
+    # QEC_DECODING_SERVER_ENDPOINT line, while the host/cpu-roce path carries
+    # the provider's endpoint info on the READY line itself. Scrape whichever
+    # arrives.
     local ep_line
-    ep_line=$(wait_for_pattern "$server_log" "QEC_DECODING_SERVER_ENDPOINT" 5 "$SERVER_PID") || return 1
+    ep_line=$(wait_for_pattern "$server_log" "buffer_addr=" 5 "$SERVER_PID") || return 1
 
     SERVER_QP=$(sed -n 's/.*[[:space:]]qp=\([0-9a-fA-FxX]*\).*/\1/p' <<<"$ep_line")
     SERVER_RKEY=$(sed -n 's/.*[[:space:]]rkey=\([0-9]*\).*/\1/p' <<<"$ep_line")
@@ -1077,6 +1151,16 @@ run_playback() {
     local hsb_ip="$1"; shift
 
     _log "Starting syndrome playback (hsb_ip=$hsb_ip)"
+    # The FPGA/emulator writes syndrome frame rid to RDMA slot (rid % num-pages);
+    # --num-pages programs that ring modulus (via the SIF RDMA target). It MUST
+    # equal the server's RX ring depth, or frames past one ring land outside the
+    # server's registered memory region and are silently lost -- the server then
+    # starves after exactly one ring's worth of slots. The cpu_roce server ring
+    # is NUM_SLOTS; the gpu_roce server ring is GPU_ROCE_NUM_PAGES (both == the 64
+    # WQE depth). This also programs the emulator's SIF target, so emulated mode
+    # tracks the same modulus.
+    local pb_pages="$NUM_SLOTS"
+    if [[ "$TRANSPORT" == "gpu_roce" ]]; then pb_pages="$GPU_ROCE_NUM_PAGES"; fi
     local playback_args=(
         --hsb-ip "$hsb_ip"
         --per-round
@@ -1086,7 +1170,7 @@ run_playback() {
         --rkey "$SERVER_RKEY"
         --buffer-addr "$SERVER_ADDR"
         --page-size "$PAGE_SIZE"
-        --num-pages "$PLAYBACK_NUM_PAGES"
+        --num-pages "$pb_pages"
         "$@"
     )
     if $VERIFY; then
@@ -1117,13 +1201,15 @@ run_emulated() {
     TEMP_FILES+=("$emu_log" "$server_log")
 
     # ---- 1. Start emulator ----
+    # The emulator's RDMA-write ring modulus is the SIF target the playback
+    # programs it with (target.max_buff + 1), not a CLI flag -- it does not parse
+    # --num-pages -- so run_playback's page count drives emulated mode too.
     _log "Starting FPGA emulator on port $CONTROL_PORT"
     "$EMULATOR_BIN" \
         --device="$EMULATOR_DEVICE" \
         --port="$CONTROL_PORT" \
         --bridge-ip="$BRIDGE_IP" \
         --page-size="$PAGE_SIZE" \
-        --num-pages="$PLAYBACK_NUM_PAGES" \
         > >(tee "$emu_log") 2>&1 &
     local emu_pid=$!
     PIDS_TO_KILL+=("$emu_pid")
diff --git a/libs/qec/unittests/utils/hsb_fpga_syndrome_playback.cpp b/libs/qec/unittests/utils/hsb_fpga_syndrome_playback.cpp
index 23becbaa4..a0fcd2f09 100644
--- a/libs/qec/unittests/utils/hsb_fpga_syndrome_playback.cpp
+++ b/libs/qec/unittests/utils/hsb_fpga_syndrome_playback.cpp
@@ -446,7 +446,10 @@ struct Options {
   std::optional<std::uint32_t> rdma_page_size; // ring buffer slot size (bytes)
   std::optional<std::uint32_t> rdma_num_pages; // number of ring buffer slots
   std::uint32_t spacing_us =
-      DEFAULT_TIMER_SPACING_US; // inter-shot spacing (us)
+      DEFAULT_TIMER_SPACING_US; // per-frame playback pacing (us): the FPGA
+                                // timer fires once per BRAM window (= one
+                                // frame), so a shot spans
+                                // frames-per-shot x spacing
 };
 
 void print_usage(const char *argv0) {
@@ -465,8 +468,11 @@ void print_usage(const char *argv0) {
       << "  --function-name <s>   RPC function name for dispatch "
          "(default: mock_decode)\n"
       << "  --num-shots <n>       Number of shots to play back (default: all)\n"
-      << "  --spacing <us>        Inter-shot spacing in microseconds "
-         "(default: 10)\n"
+      << "  --spacing <us>        Per-frame playback pacing in microseconds "
+         "(default: 10;\n"
+         "                        the FPGA timer fires once per frame, so a "
+         "shot spans\n"
+         "                        frames-per-shot x spacing)\n"
       << "  --verify              Capture and verify correction responses "
          "via ILA\n"
       << "  --per-round           Per-round protocol (device-graph scheduler): "