Phase 1: Revive SchedulerFreebyrd with full T1+DWT+MCT pipeline

Implement the freebyrd scheduler as a working alternative decompression
path (activated via GRK_SCHEDULER=freebyrd). The scheduler runs a
sequential pipeline: parallel T1 block decode → DWT → MCT/DC-shift.

Key changes:
- SchedulerFreebyrd.cpp: Full implementation of decodeBlocks(), runDWT(),
  and postProcess(). Blocks are collected across all components and
  decoded in parallel via tf::Taskflow::emplace(). DWT uses WaveletReverse
  with a DwtFlowHelper (minimal SchedulerStandard subclass) to provide
  the ImageComponentFlow infrastructure. MCT/DC-shift runs via Mct
  schedule_decompress_rev/irrev.
- SchedulerFreebyrd.h: Added DwtFlowHelper forward decl, CoderPool
  member, updated constructor to accept CoderPool*.
- TileProcessor.cpp: Pass coderPool to SchedulerFreebyrd constructor.

Output is bit-exact with the standard scheduler for lossless (5/3) and
matches for lossy (9/7). All 2069 existing tests pass.

Author: Grok Compression

src/lib/core/scheduling/freebyrd/SchedulerFreebyrd.cpp

@@ -15,45 +15,302 @@
  *
  */
 
-// Stub implementation — freebyrd thread pool has been removed.
-// SchedulerFreebyrd remains as a skeleton so the build succeeds but
-// setting GRK_SCHEDULER=freebyrd will log an error and fall back.
+#include "TFSingleton.h"
 
+#include "geometry.h"
+#include "ISparseCanvas.h"
+#include "grk_restrict.h"
+#include "CodeStreamLimits.h"
+#include "TileWindow.h"
+#include "Quantizer.h"
 #include "Logger.h"
+#include "buffer.h"
+#include "GrkObjectWrapper.h"
+#include "TileFutureManager.h"
+#include "ImageComponentFlow.h"
+#include "IStream.h"
+#include "FetchCommon.h"
+#include "TPFetchSeq.h"
+#include "GrkImageMeta.h"
+#include "GrkImage.h"
+#include "MarkerParser.h"
+#include "PLMarker.h"
+#include "SIZMarker.h"
+#include "PPMMarker.h"
+namespace grk
+{
+struct ITileProcessor;
+}
+#include "CodeStream.h"
+#include "PacketLengthCache.h"
+#include "ICoder.h"
+#include "CoderPool.h"
+#include "BitIO.h"
+#include "TagTree.h"
+#include "CodeblockCompress.h"
+#include "CodeblockDecompress.h"
+#include "Precinct.h"
+#include "Subband.h"
+#include "Resolution.h"
+#include "CodecScheduler.h"
+#include "TileComponentWindow.h"
+#include "canvas/tile/Tile.h"
+#include "mct.h"
+#include "ITileProcessor.h"
+#include "CoderFactory.h"
+#include "WaveletReverse.h"
+#include "WaveletPoolData.h"
+#include "TileBlocks.h"
+#include "SchedulerStandard.h"
+#include "ImageComponentFlow.h"
 #include "SchedulerFreebyrd.h"
 
 namespace grk
 {
 
-SchedulerFreebyrd::SchedulerFreebyrd(uint16_t numcomps, uint8_t prec)
-    : numcomps_(numcomps), prec_(prec), success_(true)
+// Minimal concrete SchedulerStandard subclass for providing ImageComponentFlow to WaveletReverse
+class DwtFlowHelper : public SchedulerStandard
+{
+public:
+  explicit DwtFlowHelper(uint16_t numComps) : SchedulerStandard(numComps) {}
+  bool scheduleT1([[maybe_unused]] ITileProcessor* proc) override { return true; }
+  void release(void) override { SchedulerStandard::release(); }
+
+  void setupComponentFlow(uint16_t compno, uint8_t numRes, bool regionDecompress)
+  {
+    if(compno >= numcomps_)
+      return;
+    if(imageComponentFlow_[compno])
+      delete imageComponentFlow_[compno];
+    imageComponentFlow_[compno] = new ImageComponentFlow(numRes);
+    if(regionDecompress)
+      imageComponentFlow_[compno]->setRegionDecompression();
+    // addTo must be called before graph to initialize composition tasks
+    imageComponentFlow_[compno]->addTo(*this);
+    SchedulerStandard::graph(compno);
+  }
+};
+
+SchedulerFreebyrd::SchedulerFreebyrd(uint16_t numcomps, uint8_t prec, CoderPool* streamPool)
+    : numcomps_(numcomps), prec_(prec), success_(true), streamPool_(streamPool),
+      waveletPoolData_(new WaveletPoolData()), dwtHelper_(new DwtFlowHelper(numcomps))
 {}
 
 SchedulerFreebyrd::~SchedulerFreebyrd()
 {
   release();
+  delete waveletPoolData_;
+  delete dwtHelper_;
 }
 
 void SchedulerFreebyrd::release()
 {
   blocksByComp_.clear();
 }
 
-bool SchedulerFreebyrd::decompressTile([[maybe_unused]] ITileProcessor* tileProcessor)
+bool SchedulerFreebyrd::decompressTile(ITileProcessor* tileProcessor)
 {
-  grklog.error("SchedulerFreebyrd: freebyrd backend has been removed. "
-               "Unset GRK_SCHEDULER or use the default scheduler.");
-  return false;
+  success_ = true;
+
+  if(!decodeBlocks(tileProcessor))
+    return false;
+
+  if(!runDWT(tileProcessor))
+    return false;
+
+  if(!postProcess(tileProcessor))
+    return false;
+
+  return success_;
 }
 
-bool SchedulerFreebyrd::decodeBlocks([[maybe_unused]] ITileProcessor* tileProcessor)
+bool SchedulerFreebyrd::decodeBlocks(ITileProcessor* tileProcessor)
 {
-  return false;
+  auto tcp = tileProcessor->getTCP();
+  bool cacheAll =
+      (tileProcessor->getTileCacheStrategy() & GRK_TILE_CACHE_ALL) == GRK_TILE_CACHE_ALL;
+  uint32_t num_threads = (uint32_t)TFSingleton::num_threads();
+  bool finalLayer = tcp->layersToDecompress_ == tcp->numLayers_;
+
+  // Collect all blocks across all components
+  std::vector<std::shared_ptr<t1::DecompressBlockExec>> allBlocks;
+
+  struct BlockDecodeContext
+  {
+    CoderPool* pool;
+    uint8_t cblkwExpn;
+    uint8_t cblkhExpn;
+    bool cacheAll;
+    bool isHT;
+    uint32_t tileCacheStrategy;
+    uint16_t cbw;
+    uint16_t cbh;
+  };
+  std::vector<BlockDecodeContext> blockContexts;
+
+  for(uint16_t compno = 0; compno < numcomps_; ++compno)
+  {
+    if(!tileProcessor->shouldDecodeComponent(compno))
+      continue;
+
+    auto tccp = tcp->tccps_ + compno;
+    uint16_t cbw = tccp->cblkw_expn_ ? (uint16_t)(1 << tccp->cblkw_expn_) : 0U;
+    uint16_t cbh = tccp->cblkh_expn_ ? (uint16_t)(1 << tccp->cblkh_expn_) : 0U;
+    auto activePool = &coderPool_;
+    if(streamPool_ && streamPool_->contains(tccp->cblkw_expn_, tccp->cblkh_expn_))
+      activePool = streamPool_;
+
+    if(!cacheAll)
+    {
+      activePool->makeCoders(
+          num_threads, tccp->cblkw_expn_, tccp->cblkh_expn_,
+          [tcp, cbw, cbh, tileProcessor]() -> std::shared_ptr<t1::ICoder> {
+            return std::shared_ptr<t1::ICoder>(t1::CoderFactory::makeCoder(
+                tcp->isHT(), false, cbw, cbh, tileProcessor->getTileCacheStrategy()));
+          });
+    }
+
+    auto tilec = tileProcessor->getTile()->comps_ + compno;
+    auto wholeTileDecoding = tilec->isWholeTileDecoding();
+    uint8_t resBegin =
+        cacheAll ? (uint8_t)tilec->currentPacketProgressionState_.numResolutionsRead() : 0;
+    uint8_t resUpperBound = tilec->nextPacketProgressionState_.numResolutionsRead();
+
+    for(uint8_t resno = resBegin; resno < resUpperBound; ++resno)
+    {
+      auto res = tilec->resolutions_ + resno;
+      for(uint8_t bandIndex = 0; bandIndex < res->numBands_; ++bandIndex)
+      {
+        auto band = res->band + bandIndex;
+        auto paddedBandWindow = tilec->getBandWindowPadded(resno, band->orientation_);
+        for(auto precinct : band->precincts_)
+        {
+          if(!wholeTileDecoding && !paddedBandWindow->nonEmptyIntersection(precinct))
+            continue;
+          for(uint32_t cblkno = 0; cblkno < precinct->getNumCblks(); ++cblkno)
+          {
+            auto cblkBounds = precinct->getCodeBlockBounds(cblkno);
+            if(!wholeTileDecoding && !paddedBandWindow->nonEmptyIntersection(&cblkBounds))
+              continue;
+
+            auto cblk = precinct->getDecompressBlock(cblkno);
+            auto block = std::make_shared<t1::DecompressBlockExec>(cacheAll);
+            block->x = cblk->x0();
+            block->y = cblk->y0();
+            block->postProcessor_ =
+                tcp->isHT() ? t1::DecompressBlockPostProcessor<int32_t>(
+                                  [tilec](int32_t* srcData, t1::DecompressBlockExec* blk,
+                                          uint16_t stride) {
+                                    tilec->postProcessBlockHT(srcData, blk, stride);
+                                  })
+                            : t1::DecompressBlockPostProcessor<int32_t>(
+                                  [tilec](int32_t* srcData, t1::DecompressBlockExec* blk,
+                                          [[maybe_unused]] uint16_t stride) {
+                                    tilec->postProcessBlock(srcData, blk);
+                                  });
+            block->bandIndex = bandIndex;
+            block->bandNumbps = band->maxBitPlanes_;
+            block->bandOrientation = band->orientation_;
+            block->cblk = cblk;
+            block->cblk_sty = tccp->cblkStyle_;
+            block->qmfbid = tccp->qmfbid_;
+            block->resno = resno;
+            block->roishift = tccp->roishift_;
+            block->stepsize = band->stepsize_;
+            block->k_msbs = (uint8_t)(band->maxBitPlanes_ - cblk->numbps());
+            block->R_b = prec_ + gain_b[band->orientation_];
+            block->finalLayer_ = finalLayer;
+
+            allBlocks.push_back(block);
+            blockContexts.push_back({activePool, tccp->cblkw_expn_, tccp->cblkh_expn_, cacheAll,
+                                     tcp->isHT(), tileProcessor->getTileCacheStrategy(), cbw, cbh});
+          }
+        }
+      }
+    }
+    tilec->currentPacketProgressionState_ = tilec->nextPacketProgressionState_;
+  }
+
+  if(allBlocks.empty())
+    return true;
+
+  // Decode all blocks in parallel using TaskFlow
+  tf::Taskflow taskflow;
+  for(size_t i = 0; i < allBlocks.size(); ++i)
+  {
+    taskflow.emplace([this, i, &allBlocks, &blockContexts, tileProcessor]() {
+      if(!success_)
+        return;
+      auto& block = allBlocks[i];
+      auto& ctx = blockContexts[i];
+      t1::ICoder* coder = nullptr;
+      if(block->needsCachedCoder())
+      {
+        coder = t1::CoderFactory::makeCoder(ctx.isHT, false, ctx.cbw, ctx.cbh,
+                                            ctx.tileCacheStrategy);
+      }
+      else if(!ctx.cacheAll)
+      {
+        auto threadnum = TFSingleton::get().this_worker_id();
+        coder = ctx.pool->getCoder((size_t)threadnum, ctx.cblkwExpn, ctx.cblkhExpn).get();
+      }
+      try
+      {
+        if(!block->open(coder))
+          success_ = false;
+      }
+      catch(const std::runtime_error& rerr)
+      {
+        grklog.error(rerr.what());
+        success_ = false;
+      }
+    });
+  }
+  TFSingleton::get().run(taskflow).wait();
+
+  return success_;
 }
 
-bool SchedulerFreebyrd::runDWT([[maybe_unused]] ITileProcessor* tileProcessor)
+bool SchedulerFreebyrd::runDWT(ITileProcessor* tileProcessor)
 {
-  return false;
+  auto tcp = tileProcessor->getTCP();
+
+  // Release any previous ImageComponentFlow state and clear the taskflow
+  dwtHelper_->release();
+  dwtHelper_->clear();
+
+  for(uint16_t compno = 0; compno < numcomps_; ++compno)
+  {
+    if(!tileProcessor->shouldDecodeComponent(compno))
+      continue;
+
+    auto tilec = tileProcessor->getTile()->comps_ + compno;
+    uint8_t numRes = tilec->nextPacketProgressionState_.numResolutionsRead();
+    if(numRes <= 1)
+      continue;
+
+    // Create ImageComponentFlow for this component (required by WaveletReverse)
+    dwtHelper_->setupComponentFlow(compno, numRes, !tilec->isWholeTileDecoding());
+
+    auto tccp = tcp->tccps_ + compno;
+    auto maxDim = std::max(tileProcessor->getCodingParams()->t_width_,
+                           tileProcessor->getCodingParams()->t_height_);
+
+    WaveletReverse wavelet(dwtHelper_, tilec, compno, tilec->windowUnreducedBounds(), numRes,
+                           tccp->qmfbid_, maxDim, tcp->wholeTileDecompress_, waveletPoolData_);
+    if(!wavelet.decompress())
+      return false;
+
+    // WaveletReverse::decompress() only schedules tasks into the flow —
+    // we must actually run them.
+    TFSingleton::get().run(*dwtHelper_).wait();
+
+    // Clear the taskflow for the next component
+    dwtHelper_->release();
+    dwtHelper_->clear();
+  }
+
+  return true;
 }
 
 bool SchedulerFreebyrd::runCascadeDWT97([[maybe_unused]] ITileProcessor* tileProcessor,
@@ -74,9 +331,49 @@ bool SchedulerFreebyrd::runSeparateDWT16([[maybe_unused]] ITileProcessor* tilePr
   return false;
 }
 
-bool SchedulerFreebyrd::postProcess([[maybe_unused]] ITileProcessor* tileProcessor)
+bool SchedulerFreebyrd::postProcess(ITileProcessor* tileProcessor)
 {
-  return false;
+  if(!tileProcessor->doPostT1())
+    return true;
+
+  auto tcp = tileProcessor->getTCP();
+  auto mct = tileProcessor->getMCT();
+
+  if(tileProcessor->needsMctDecompress())
+  {
+    // MCT with DC shift
+    FlowComponent mctComp;
+    if(tcp->tccps_->qmfbid_ == 1)
+      mct->schedule_decompress_rev(&mctComp, true);
+    else
+      mct->schedule_decompress_irrev(&mctComp, true);
+
+    TFSingleton::get().run(mctComp).wait();
+  }
+  else
+  {
+    // DC shift only, per component
+    for(uint16_t compno = 0; compno < numcomps_; ++compno)
+    {
+      if(!tileProcessor->shouldDecodeComponent(compno))
+        continue;
+
+      auto tccp = tcp->tccps_ + compno;
+      auto tilec = tileProcessor->getTile()->comps_ + compno;
+      uint8_t numRes = tilec->nextPacketProgressionState_.numResolutionsRead();
+
+      // Freebyrd doesn't fuse DC shift into wavelet, so always apply it
+      FlowComponent dcComp;
+      if(tccp->qmfbid_ == 1)
+        mct->schedule_decompress_dc_shift_rev(&dcComp, compno);
+      else
+        mct->schedule_decompress_dc_shift_irrev(&dcComp, compno);
+
+      TFSingleton::get().run(dcComp).wait();
+    }
+  }
+
+  return true;
 }
 
 } // namespace grk