Tool features required by GoliathOmics

GoliathOmics consumes GoliathAlign (formerly mojo-align) and MethylExtractor only through the features below. Both utilities are standalone: they do not reference GoliathApp or GoliathOmics. A change in either tool that removes or renames a listed feature breaks GoliathOmics, even when the platform (goliath-gateway, database goliath, GOLIATH_WORK_ROOT) is unchanged. Direction: architecture/dependencies.md.

Inherited platform pieces use the goliath prefix. These tools stay separate repositories. They are not part of GoliathApp.

GoliathAlign

Toolchain pin: Mojo 1.1 / Modular 26.6. Not Mojo 1.0.0b2.

Image: goliath/methylgrapher (tags stay *-mojo-*). In-image tree: /opt/goliath-align, with /opt/mojo-align as a symlink for one cycle.

Checkout: GOLIATH_ALIGN_ROOT, or the sibling ../GoliathAlign. MOJO_ALIGN_ROOT and ../mojo-align remain one-cycle aliases.

Consumer: workers/methyl_worker/methylgrapher_wgbs_runner.py (sample.methylgrapher_wgbs_align, sample.methylgrapher_wgbs_extract).

Feature	What a break looks like
methylGrapher Align	WGBS pangenome alignment cannot start. No silent fallback to stock Giraffe.
methylGrapher MethylCall	Graph-aware methylation calls are not produced. Requires PrepareGenome artifacts ({index_prefix}.wl.gfa) on disk first.
methylGrapher MergeCpG	CpG merge step of the WGBS extract path fails.
methylGrapher help	The worker cannot probe the binary.
GPU target METHYLGRAPHER_TARGET_ACCELERATOR	NVIDIA targets from sm_90 upward, or an AMD arch via METHYLGRAPHER_AMDGPU_ARCH. Hosts whose default GPU is older than sm_52 do not compile.
Outputs: GAF, QC BAM, graph-aware H5	Downstream QC and extraction have nothing to read.

MethylExtractor

Not used on the WGBS pangenome path. That path uses GoliathAlign MethylCall / MergeCpG.

Binary layout: the release tarball stays on the shared volume (/work/goliath/releases/<version>/methyl-extractor-linux-<arch>.tar.gz); each machine extracts it onto local disk at METHYL_EXTRACTOR_HOME (default /opt/goliath/methyl-extractor-<arch>/, override root with GOLIATH_LOCAL_ROOT; never under the work mount, which ignores exec bits). HDF5_PLUGIN_PATH points at the zstd plugin shipped beside the binary. MethylExtractor links libhts.so.3, which the worker image does not have: scripts/assemble_release.sh runs scripts/bundle_methyl_extractor_libs.sh on each downloaded tarball, which copies libhts.so.3 (real versioned file plus soname link), libdeflate.so.0 and libhtscodecs.so.2 from the Ubuntu jammy .debs for that arch into the tarball's lib/, sets the binary's RUNPATH to $ORIGIN/../lib with patchelf; the manifest sha256 is computed after this step (MethylExtractor 2026.10.1+ tarballs already bundle every non-glibc library with that RUNPATH). The binary must run with no LD_LIBRARY_PATH: the local installer refuses one that does not, and neither its env.sh nor worker.env puts METHYL_EXTRACTOR_HOME/lib on LD_LIBRARY_PATH, because the bundled Ubuntu 22.04 libraries (libcurl 7.81, libssl, libzstd, libhts 1.13) would then shadow the host's for every other program (/usr/bin/curl failed with undefined symbol: curl_global_trace). GOLIATH_WORK_ROOT (alias METHYL_WORK_ROOT) is the mount that holds the tarball. Workflows that never extract do not need the mount.

Consumer: workers/methyl_worker/extract_runner.py (sample.methyl_extract) and methylextractionqc.

Feature	What a break looks like
MethylExtractor --help	The worker cannot confirm the binary or which flags it supports.
--threads	Thread count from resolved config is ignored.
--chrom-parallel	Chromosome-parallel extract cannot be requested.
--max-rss-gb	RSS cap from resolved config is ignored.
--min-mapq, --min-phred, --min-cov, --cap-cov	Alignment and coverage filters no longer match the action config.
--CHG, --CHH	Contexts other than CG are dropped. CG stays implicit.
--chrom-mapping	Contig name mapping no longer matches the reference.
--compression, --chunk-size	HDF5 layout written for downstream readers changes.
--read-level	Pattern-level output is skipped and only marginal H5 is emitted.
{chrom}-{context}.json sidecars	methylextractionqc cannot build the extraction manifest.
HDF5 output plus the zstd plugin	Sample H5 files do not open under HDF5_PLUGIN_PATH.