feat(map): orphansRequireUnmappedMate orphan-emission policy

Add MappingConstraintPolicy.orphansRequireUnmappedMate. When set, joinReadsAndFilter
only emits single-mate (orphan) mappings for a read whose mate produced no mappings
at all, instead of reporting the union of both mates' orphans when a pair has no
concordant mapping. Default false (union; unchanged behavior). Backs salmon's
--orphansRequireUnmappedMate flag.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B7JMur5DmDpECddErpi2JS

Author: rob-p

include/Util.hpp

@@ -117,6 +117,11 @@ namespace pufferfish {
         bool noOrphans;
         bool noDiscordant;
         bool noDovetail;
+        // When true, only emit single-mate (orphan) mappings for a read whose
+        // mate is entirely unmapped; do not report orphans for both mates of a
+        // pair that mapped to disjoint reference sets (salmon's
+        // --orphansRequireUnmappedMate).
+        bool orphansRequireUnmappedMate{false};
         // after merging chains for paired-end reads 
         // only chains having this threshold score 
         // *with respect to the best chain on the same target*

src/Util.cpp

@@ -316,8 +316,17 @@ pufferfish::util::MergeResult joinReadsAndFilter(
                 */
             } // for (auto &clustItr : memClusters) [ over all transcripts]
         };
-        orphanFiller(leftMemClusters, true);
-        orphanFiller(rightMemClusters, false);
+        // Under --orphansRequireUnmappedMate, only report orphans for a mate when
+        // the *other* mate produced no mappings at all (it is truly unmapped), so
+        // a read that mapped only alongside a mate mapping to a disjoint reference
+        // set is not reported as an orphan. Default: report the union of both.
+        bool reqUnmapped = mpol.orphansRequireUnmappedMate;
+        if (!reqUnmapped || rightMemClusters.size() == 0) {
+            orphanFiller(leftMemClusters, true);
+        }
+        if (!reqUnmapped || leftMemClusters.size() == 0) {
+            orphanFiller(rightMemClusters, false);
+        }
     }
     if (sameTxpCount == 0) {
       if (leftOrphan and !rightOrphan) {