From 924270b3ba41c19a468f36b13345edff89e6db2a Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Tue, 11 Aug 2026 23:02:46 -0700
Subject: [PATCH 1/8] feat(metrics): add reason-keyed template filter
 accounting

Introduce TemplateFilterReason and TemplateFilterCounts: one variant per
rejection site in the pre-grouping template filter, and a collector that
records every decision in both template and primary-read units. This
replaces the practice of reusing group's fgbio output schema as the
measurement primitive, which capped the reason vocabulary at fgbio's four
discard columns.

Named template_filter rather than filter because fgumi filter is a real
command with its own metrics, and every module in this crate is named for
the command it measures.
---
 crates/fgumi-metrics/src/lib.rs             |   2 +
 crates/fgumi-metrics/src/template_filter.rs | 298 ++++++++++++++++++++
 2 files changed, 300 insertions(+)
 create mode 100644 crates/fgumi-metrics/src/template_filter.rs

diff --git a/crates/fgumi-metrics/src/lib.rs b/crates/fgumi-metrics/src/lib.rs
index d26520e8d..9c2b134ea 100644
--- a/crates/fgumi-metrics/src/lib.rs
+++ b/crates/fgumi-metrics/src/lib.rs
@@ -18,6 +18,7 @@ pub mod group;
 pub mod rejection;
 pub mod shared;
 pub mod simplex;
+pub mod template_filter;
 pub mod writer;
 
 use serde::{Deserialize, Serialize};
@@ -106,6 +107,7 @@ pub use group::{FamilySizeMetrics, PositionGroupSizeMetrics, UmiGroupingMetrics}
 pub use rejection::{RejectionReason, format_count};
 pub use shared::UmiMetric;
 pub use simplex::{SimplexFamilySizeMetric, SimplexMetricsCollector, SimplexYieldMetric};
+pub use template_filter::{TemplateFilterCounts, TemplateFilterReason};
 pub use writer::{read_metrics, read_metrics_auto, write_metrics};
 
 #[cfg(test)]
diff --git a/crates/fgumi-metrics/src/template_filter.rs b/crates/fgumi-metrics/src/template_filter.rs
new file mode 100644
index 000000000..18ddde326
--- /dev/null
+++ b/crates/fgumi-metrics/src/template_filter.rs
@@ -0,0 +1,298 @@
+//! Template-level filter accounting shared by the `group` and `dedup` commands.
+//!
+//! Both commands run the same pre-grouping template filter but report it
+//! differently: `group` emits fgbio's five-column `UmiGroupingMetric` in
+//! **primary-record** units, `dedup` emits fgumi-native `filtered_*` columns in
+//! **template** units. [`TemplateFilterCounts`] is the single measurement those
+//! two views render from, so it records every decision in both units and keys
+//! rejections by [`TemplateFilterReason`] — one variant per rejection site in the
+//! filter, independent of any output file's column vocabulary.
+
+/// Why the pre-grouping template filter rejected a template.
+///
+/// One variant per rejection site, not per output column: fgbio's
+/// `UmiGroupingMetric` collapses six of these into a single
+/// `discarded_poor_alignment` column, which is a property of that file format
+/// rather than of the filter. Adding a rejection site requires adding a variant
+/// here, which breaks the exhaustive matches in every renderer until each decides
+/// what to do with it.
+///
+/// `#[repr(usize)]` is load-bearing: [`TemplateFilterCounts`] indexes its arrays
+/// by `reason as usize`, and [`Self::ALL`] is ordered to match.
+// `EnumIter` (test-only) auto-generates `iter()` so coverage assertions enumerate
+// every variant without a hand-maintained list that can drift.
+#[cfg_attr(test, derive(strum::EnumIter))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(usize)]
+pub enum TemplateFilterReason {
+    /// A record was shorter than the minimum BAM record length (corrupt input).
+    MalformedRecord,
+    /// The template had neither an R1 nor an R2 primary record.
+    NoPrimaryReads,
+    /// Every primary read in the template was unmapped.
+    Unmapped,
+    /// A primary read carried the QC-fail (`0x200`) flag.
+    NotPassingFilter,
+    /// A mapped primary read's mapping quality was below the threshold.
+    LowMappingQuality,
+    /// A primary read's mate mapping quality (`MQ` tag) was below the threshold.
+    LowMateMappingQuality,
+    /// A primary read had no UMI tag.
+    MissingUmi,
+    /// The UMI contained at least one `N` base.
+    NsInUmi,
+    /// The UMI was shorter than the configured minimum length.
+    UmiTooShort,
+}
+
+impl TemplateFilterReason {
+    /// Number of variants.
+    pub const COUNT: usize = 9;
+
+    /// Every variant, in discriminant order.
+    pub const ALL: [Self; Self::COUNT] = [
+        Self::MalformedRecord,
+        Self::NoPrimaryReads,
+        Self::Unmapped,
+        Self::NotPassingFilter,
+        Self::LowMappingQuality,
+        Self::LowMateMappingQuality,
+        Self::MissingUmi,
+        Self::NsInUmi,
+        Self::UmiTooShort,
+    ];
+
+    /// Snake-case identifier for this reason, used as the suffix of the
+    /// `filtered_*` column in `dedup`'s metrics file and in log summaries.
+    #[must_use]
+    pub fn column_suffix(self) -> &'static str {
+        match self {
+            Self::MalformedRecord => "malformed_record",
+            Self::NoPrimaryReads => "no_primary_reads",
+            Self::Unmapped => "unmapped",
+            Self::NotPassingFilter => "not_passing_filter",
+            Self::LowMappingQuality => "low_mapping_quality",
+            Self::LowMateMappingQuality => "low_mate_mapping_quality",
+            Self::MissingUmi => "missing_umi",
+            Self::NsInUmi => "ns_in_umi",
+            Self::UmiTooShort => "umi_too_short",
+        }
+    }
+}
+
+/// Per-reason accounting for the pre-grouping template filter.
+///
+/// The filter is the only writer: each template that enters is recorded exactly
+/// once, via [`Self::record_accepted`] or [`Self::record_rejected`]. That makes
+/// `total == accepted + sum(rejected)` true by construction in both units.
+///
+/// Counts are tracked in two units simultaneously:
+/// - **templates**: one per template, regardless of how many records it holds
+/// - **primary reads**: the number of primary (non-secondary, non-supplementary)
+///   records in the template, which is fgbio's unit for `UmiGroupingMetric`
+///
+/// A template with neither an R1 nor an R2 contributes `1` template and `0`
+/// primary reads, so the units are not proportional and neither is derivable
+/// from the other.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct TemplateFilterCounts {
+    accepted_templates: u64,
+    accepted_primary_reads: u64,
+    rejected_templates: [u64; TemplateFilterReason::COUNT],
+    rejected_primary_reads: [u64; TemplateFilterReason::COUNT],
+}
+
+impl TemplateFilterCounts {
+    /// Creates an empty set of counts.
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Records a template that passed the filter, carrying `primary_reads`
+    /// primary records.
+    pub fn record_accepted(&mut self, primary_reads: u64) {
+        self.accepted_templates += 1;
+        self.accepted_primary_reads += primary_reads;
+    }
+
+    /// Records a template rejected for `reason`, carrying `primary_reads` primary
+    /// records.
+    pub fn record_rejected(&mut self, reason: TemplateFilterReason, primary_reads: u64) {
+        self.rejected_templates[reason as usize] += 1;
+        self.rejected_primary_reads[reason as usize] += primary_reads;
+    }
+
+    /// Adds every count in `other` into `self`.
+    pub fn merge(&mut self, other: &Self) {
+        self.accepted_templates += other.accepted_templates;
+        self.accepted_primary_reads += other.accepted_primary_reads;
+        for index in 0..TemplateFilterReason::COUNT {
+            self.rejected_templates[index] += other.rejected_templates[index];
+            self.rejected_primary_reads[index] += other.rejected_primary_reads[index];
+        }
+    }
+
+    /// Templates that passed the filter.
+    #[must_use]
+    pub fn accepted_templates(&self) -> u64 {
+        self.accepted_templates
+    }
+
+    /// Primary reads in templates that passed the filter.
+    #[must_use]
+    pub fn accepted_primary_reads(&self) -> u64 {
+        self.accepted_primary_reads
+    }
+
+    /// Templates rejected for `reason`.
+    #[must_use]
+    pub fn rejected_templates(&self, reason: TemplateFilterReason) -> u64 {
+        self.rejected_templates[reason as usize]
+    }
+
+    /// Primary reads in templates rejected for `reason`.
+    #[must_use]
+    pub fn rejected_primary_reads(&self, reason: TemplateFilterReason) -> u64 {
+        self.rejected_primary_reads[reason as usize]
+    }
+
+    /// Templates rejected for any reason.
+    #[must_use]
+    pub fn total_rejected_templates(&self) -> u64 {
+        self.rejected_templates.iter().sum()
+    }
+
+    /// Primary reads in templates rejected for any reason.
+    #[must_use]
+    pub fn total_rejected_primary_reads(&self) -> u64 {
+        self.rejected_primary_reads.iter().sum()
+    }
+
+    /// Templates that entered the filter (accepted plus rejected).
+    #[must_use]
+    pub fn total_templates(&self) -> u64 {
+        self.accepted_templates + self.total_rejected_templates()
+    }
+
+    /// Primary reads that entered the filter (accepted plus rejected).
+    #[must_use]
+    pub fn total_primary_reads(&self) -> u64 {
+        self.accepted_primary_reads + self.total_rejected_primary_reads()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use strum::IntoEnumIterator;
+
+    /// `TemplateFilterCounts` indexes its arrays by `reason as usize`, so `ALL`
+    /// must list every variant in discriminant order or counts land in the wrong
+    /// bucket.
+    #[test]
+    fn all_covers_every_variant_in_discriminant_order() {
+        assert_eq!(TemplateFilterReason::ALL.len(), TemplateFilterReason::COUNT);
+        assert_eq!(TemplateFilterReason::iter().count(), TemplateFilterReason::COUNT);
+        for (position, &reason) in TemplateFilterReason::ALL.iter().enumerate() {
+            assert_eq!(reason as usize, position, "{reason:?} is out of order in ALL");
+        }
+    }
+
+    /// Column suffixes become metric column names: unique and `snake_case`.
+    #[test]
+    fn column_suffixes_are_unique_snake_case() {
+        let mut seen = std::collections::HashSet::new();
+        for reason in TemplateFilterReason::ALL {
+            let suffix = reason.column_suffix();
+            assert!(seen.insert(suffix), "duplicate column suffix {suffix}");
+            assert!(
+                suffix.bytes().all(|b| b.is_ascii_lowercase() || b == b'_'),
+                "{suffix} is not snake_case"
+            );
+        }
+    }
+
+    /// The central invariant: every template entering the filter is recorded
+    /// exactly once, so totals reconcile in both units.
+    #[rstest::rstest]
+    #[case::only_accepts(&[], 3, 2)]
+    #[case::only_rejects(&[(TemplateFilterReason::NsInUmi, 2)], 0, 0)]
+    #[case::mixed(&[(TemplateFilterReason::NotPassingFilter, 2), (TemplateFilterReason::MalformedRecord, 1)], 4, 2)]
+    #[case::zero_primary_reads(&[(TemplateFilterReason::NoPrimaryReads, 0)], 1, 2)]
+    fn totals_reconcile(
+        #[case] rejects: &[(TemplateFilterReason, u64)],
+        #[case] accepts: u64,
+        #[case] primary_reads_per_accept: u64,
+    ) {
+        let mut counts = TemplateFilterCounts::new();
+        for _ in 0..accepts {
+            counts.record_accepted(primary_reads_per_accept);
+        }
+        for &(reason, primary_reads) in rejects {
+            counts.record_rejected(reason, primary_reads);
+        }
+
+        assert_eq!(
+            counts.total_templates(),
+            counts.accepted_templates() + counts.total_rejected_templates()
+        );
+        assert_eq!(
+            counts.total_primary_reads(),
+            counts.accepted_primary_reads() + counts.total_rejected_primary_reads()
+        );
+        assert_eq!(counts.accepted_templates(), accepts);
+        assert_eq!(counts.accepted_primary_reads(), accepts * primary_reads_per_accept);
+        assert_eq!(counts.total_rejected_templates(), rejects.len() as u64);
+        assert_eq!(
+            counts.total_rejected_primary_reads(),
+            rejects.iter().map(|&(_, n)| n).sum::<u64>()
+        );
+    }
+
+    /// A rejection lands in its own bucket and nowhere else.
+    #[rstest::rstest]
+    #[case::malformed(TemplateFilterReason::MalformedRecord)]
+    #[case::no_primary(TemplateFilterReason::NoPrimaryReads)]
+    #[case::unmapped(TemplateFilterReason::Unmapped)]
+    #[case::non_pf(TemplateFilterReason::NotPassingFilter)]
+    #[case::low_mapq(TemplateFilterReason::LowMappingQuality)]
+    #[case::low_mate_mapq(TemplateFilterReason::LowMateMappingQuality)]
+    #[case::missing_umi(TemplateFilterReason::MissingUmi)]
+    #[case::ns_in_umi(TemplateFilterReason::NsInUmi)]
+    #[case::umi_too_short(TemplateFilterReason::UmiTooShort)]
+    fn rejection_lands_in_exactly_one_bucket(#[case] recorded: TemplateFilterReason) {
+        let mut counts = TemplateFilterCounts::new();
+        counts.record_rejected(recorded, 2);
+
+        for reason in TemplateFilterReason::ALL {
+            let expected_templates = u64::from(reason == recorded);
+            let expected_reads = if reason == recorded { 2 } else { 0 };
+            assert_eq!(counts.rejected_templates(reason), expected_templates, "{reason:?}");
+            assert_eq!(counts.rejected_primary_reads(reason), expected_reads, "{reason:?}");
+        }
+    }
+
+    /// Merge aggregates per-worker counters; it must be additive on every field.
+    #[test]
+    fn merge_is_additive() {
+        let mut left = TemplateFilterCounts::new();
+        left.record_accepted(2);
+        left.record_rejected(TemplateFilterReason::NsInUmi, 2);
+
+        let mut right = TemplateFilterCounts::new();
+        right.record_accepted(1);
+        right.record_rejected(TemplateFilterReason::NsInUmi, 2);
+        right.record_rejected(TemplateFilterReason::Unmapped, 2);
+
+        left.merge(&right);
+
+        assert_eq!(left.accepted_templates(), 2);
+        assert_eq!(left.accepted_primary_reads(), 3);
+        assert_eq!(left.rejected_templates(TemplateFilterReason::NsInUmi), 2);
+        assert_eq!(left.rejected_primary_reads(TemplateFilterReason::NsInUmi), 4);
+        assert_eq!(left.rejected_templates(TemplateFilterReason::Unmapped), 1);
+        assert_eq!(left.total_templates(), 5);
+        assert_eq!(left.total_primary_reads(), 9);
+    }
+}

From 33ed4183bc8180dd5c0bfc107355acfe229d3908 Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Tue, 11 Aug 2026 23:11:36 -0700
Subject: [PATCH 2/8] test(group): pin the fgbio five-column grouping metrics
 header

The struct-level test pins UmiGroupingMetrics' serialization; this pins what
the command actually writes, so an internal refactor of the filter
accounting cannot change the file fgbio has to be able to read.
---
 tests/integration/test_group_command.rs | 42 +++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/tests/integration/test_group_command.rs b/tests/integration/test_group_command.rs
index e488152cb..f32f8c2e4 100644
--- a/tests/integration/test_group_command.rs
+++ b/tests/integration/test_group_command.rs
@@ -110,6 +110,48 @@ fn test_group_command_rejects_n_bases_in_umi() {
     assert!(metric.discarded_ns_in_umi > 0, "Should have discarded reads with N in UMI");
 }
 
+/// `group`'s metrics file is fgbio's `UmiGroupingMetric` and must stay exactly
+/// five columns with fgbio's spellings, whatever fgumi tracks internally. The
+/// struct-level test in `fgumi-metrics` pins the serialization; this pins what the
+/// command actually writes to disk, so an internal refactor of the filter
+/// accounting cannot change the file fgbio has to be able to read.
+#[test]
+fn test_grouping_metrics_header_is_fgbio_five_columns() {
+    let temp_dir = TempDir::new().expect("Failed to create temp dir");
+    let input_bam = temp_dir.path().join("input.bam");
+    let output_bam = temp_dir.path().join("output.bam");
+    let metrics_file = temp_dir.path().join("metrics.txt");
+
+    create_test_input_bam(&input_bam);
+
+    let cmd = GroupReadsByUmi::try_parse_from([
+        "group",
+        "--input",
+        input_bam.to_str().unwrap(),
+        "--output",
+        output_bam.to_str().unwrap(),
+        "--strategy",
+        "identity",
+        "--edits",
+        "0",
+        "--grouping-metrics",
+        metrics_file.to_str().unwrap(),
+        "--compression-level",
+        "1",
+    ])
+    .expect("failed to parse group args");
+    cmd.execute("fgumi group").expect("Failed to run group command");
+
+    let content = fs::read_to_string(&metrics_file).expect("Failed to read metrics file");
+    assert_eq!(
+        content.lines().next(),
+        Some(
+            "accepted_sam_records\tdiscarded_non_pf\tdiscarded_poor_alignment\t\
+             discarded_ns_in_umi\tdiscarded_umis_to_short"
+        )
+    );
+}
+
 /// Helper function to create a test BAM file with multiple UMI families.
 fn create_test_input_bam(path: &PathBuf) {
     let header = create_minimal_header("chr1", 10000);

From ee66dd522e3bef811d01cc8e2a54fa91859cf2db Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Tue, 11 Aug 2026 23:24:51 -0700
Subject: [PATCH 3/8] refactor: record filter rejections by reason in group and
 dedup

Replace FilterMetrics with TemplateFilterCounts in both filters. FilterMetrics
was group's fgbio output schema used as a measurement primitive: four discard
buckets named after fgbio's columns, which dedup borrowed while counting a
different unit into them (its `accepted_templates` field held a primary-read
count in group and a template count in dedup).

group's .grouping_metrics.txt is unchanged -- verified byte-identical across
three filter regimes -- because UmiGroupingMetrics::set_filter_counts projects
the nine reasons back onto fgbio's four columns in primary-record units.
dedup's metrics file is also unchanged here; wiring the new counts into its
output is a separate change.

Both filters are converted together because deleting FilterMetrics breaks
dedup, and every commit must build.

The existing filter tests now assert the specific reason rather than the
bucket, which immediately caught a mislabelled case: the dedup
truncated-aux-record test was reported as a poor-alignment rejection when the
record actually clears the length check and is rejected for a missing UMI.
---
 crates/fgumi-metrics/src/group.rs |  94 ++++++++++++++
 src/lib/commands/dedup.rs         | 195 ++++++++++++++++--------------
 src/lib/commands/group.rs         | 134 ++++++++++----------
 src/lib/grouper.rs                |  42 +------
 src/lib/metrics/mod.rs            |   2 +
 5 files changed, 269 insertions(+), 198 deletions(-)

diff --git a/crates/fgumi-metrics/src/group.rs b/crates/fgumi-metrics/src/group.rs
index 8179977d9..b10dfbd96 100644
--- a/crates/fgumi-metrics/src/group.rs
+++ b/crates/fgumi-metrics/src/group.rs
@@ -6,6 +6,7 @@
 use serde::{Deserialize, Serialize};
 
 use crate::Metric;
+use crate::template_filter::{TemplateFilterCounts, TemplateFilterReason};
 
 /// Build a size distribution from (size, count) pairs.
 ///
@@ -107,6 +108,43 @@ impl UmiGroupingMetrics {
     pub fn new() -> Self {
         Self::default()
     }
+
+    /// Fills the fgbio filter columns from [`TemplateFilterCounts`].
+    ///
+    /// fgbio's `UmiGroupingMetric` counts **primary records**, not templates, so
+    /// this reads the primary-read side of `counts`. The exhaustive match makes
+    /// adding a new [`TemplateFilterReason`] a compile error until it is assigned
+    /// a column, so a rejection can never be silently dropped from the output.
+    ///
+    /// Six reasons share `discarded_poor_alignment` because fgbio's schema has no
+    /// finer bucket for them. That collapse is lossy and is retained only for
+    /// fgbio parity; `dedup` reports each reason separately.
+    ///
+    /// Leaves the family-size and summary fields untouched; the caller fills those.
+    pub fn set_filter_counts(&mut self, counts: &TemplateFilterCounts) {
+        self.total_records = counts.total_primary_reads();
+        self.accepted_records = counts.accepted_primary_reads();
+        self.discarded_non_pf = 0;
+        self.discarded_poor_alignment = 0;
+        self.discarded_ns_in_umi = 0;
+        self.discarded_umi_too_short = 0;
+
+        for reason in TemplateFilterReason::ALL {
+            let reads = counts.rejected_primary_reads(reason);
+            let column = match reason {
+                TemplateFilterReason::NotPassingFilter => &mut self.discarded_non_pf,
+                TemplateFilterReason::NsInUmi => &mut self.discarded_ns_in_umi,
+                TemplateFilterReason::UmiTooShort => &mut self.discarded_umi_too_short,
+                TemplateFilterReason::MalformedRecord
+                | TemplateFilterReason::NoPrimaryReads
+                | TemplateFilterReason::Unmapped
+                | TemplateFilterReason::LowMappingQuality
+                | TemplateFilterReason::LowMateMappingQuality
+                | TemplateFilterReason::MissingUmi => &mut self.discarded_poor_alignment,
+            };
+            *column += reads;
+        }
+    }
 }
 
 impl Metric for UmiGroupingMetrics {
@@ -258,6 +296,62 @@ mod tests {
         assert_eq!(metrics.unique_molecule_ids, 0);
     }
 
+    /// fgbio columns are in **primary-read** units, and the six reasons fgbio has
+    /// no bucket for must all land in `discarded_poor_alignment`. This mapping is
+    /// what keeps group's output byte-identical across the `TemplateFilterCounts`
+    /// refactor.
+    #[rstest::rstest]
+    #[case::malformed(TemplateFilterReason::MalformedRecord, 0, 2, 0, 0)]
+    #[case::no_primary(TemplateFilterReason::NoPrimaryReads, 0, 2, 0, 0)]
+    #[case::unmapped(TemplateFilterReason::Unmapped, 0, 2, 0, 0)]
+    #[case::non_pf(TemplateFilterReason::NotPassingFilter, 2, 0, 0, 0)]
+    #[case::low_mapq(TemplateFilterReason::LowMappingQuality, 0, 2, 0, 0)]
+    #[case::low_mate_mapq(TemplateFilterReason::LowMateMappingQuality, 0, 2, 0, 0)]
+    #[case::missing_umi(TemplateFilterReason::MissingUmi, 0, 2, 0, 0)]
+    #[case::ns_in_umi(TemplateFilterReason::NsInUmi, 0, 0, 2, 0)]
+    #[case::umi_too_short(TemplateFilterReason::UmiTooShort, 0, 0, 0, 2)]
+    fn set_filter_counts_maps_reasons_to_fgbio_columns(
+        #[case] reason: TemplateFilterReason,
+        #[case] expected_non_pf: u64,
+        #[case] expected_poor_alignment: u64,
+        #[case] expected_ns_in_umi: u64,
+        #[case] expected_umi_too_short: u64,
+    ) {
+        let mut counts = TemplateFilterCounts::new();
+        counts.record_accepted(2);
+        counts.record_rejected(reason, 2);
+
+        let mut metrics = UmiGroupingMetrics::new();
+        metrics.set_filter_counts(&counts);
+
+        assert_eq!(metrics.accepted_records, 2, "accepted is in primary-read units");
+        assert_eq!(metrics.total_records, 4);
+        assert_eq!(metrics.discarded_non_pf, expected_non_pf);
+        assert_eq!(metrics.discarded_poor_alignment, expected_poor_alignment);
+        assert_eq!(metrics.discarded_ns_in_umi, expected_ns_in_umi);
+        assert_eq!(metrics.discarded_umi_too_short, expected_umi_too_short);
+    }
+
+    /// No rejection may be dropped: the four fgbio columns must sum to the total.
+    #[test]
+    fn set_filter_counts_conserves_every_rejection() {
+        let mut counts = TemplateFilterCounts::new();
+        counts.record_accepted(2);
+        for reason in TemplateFilterReason::ALL {
+            counts.record_rejected(reason, 2);
+        }
+
+        let mut metrics = UmiGroupingMetrics::new();
+        metrics.set_filter_counts(&counts);
+
+        let discarded = metrics.discarded_non_pf
+            + metrics.discarded_poor_alignment
+            + metrics.discarded_ns_in_umi
+            + metrics.discarded_umi_too_short;
+        assert_eq!(discarded, counts.total_rejected_primary_reads());
+        assert_eq!(metrics.total_records, metrics.accepted_records + discarded);
+    }
+
     #[test]
     fn test_umi_grouping_metrics_serializes_fgbio_five_columns() {
         use fgoxide::io::DelimFile;
diff --git a/src/lib/commands/dedup.rs b/src/lib/commands/dedup.rs
index 24266b763..60fc12006 100644
--- a/src/lib/commands/dedup.rs
+++ b/src/lib/commands/dedup.rs
@@ -23,11 +23,10 @@ use std::sync::Arc;
 use std::sync::atomic::{AtomicU64, Ordering};
 
 use crate::assigner::{PairedUmiAssigner, Strategy, UmiAssigner};
-use crate::grouper::{
-    FilterMetrics, RawPositionGroup, RecordPositionGrouper, build_templates_from_records,
-};
+use crate::grouper::{RawPositionGroup, RecordPositionGrouper, build_templates_from_records};
 use crate::logging::OperationTimer;
 use crate::metrics::group::FamilySizeMetrics;
+use crate::metrics::{TemplateFilterCounts, TemplateFilterReason};
 use crate::read_info::LibraryIndex;
 use crate::sam::SamTag;
 use crate::sam::is_template_coordinate_sorted;
@@ -87,8 +86,8 @@ pub struct DedupMetrics {
     pub supplementary_reads: u64,
     /// Secondary/supplementary without `tc` tag
     pub missing_tc_tag: u64,
-    /// Filter metrics from position grouping
-    pub filter_metrics: FilterMetrics,
+    /// Per-reason counts from the template filter.
+    pub filter_counts: TemplateFilterCounts,
 }
 
 impl DedupMetrics {
@@ -103,7 +102,7 @@ impl DedupMetrics {
         self.secondary_reads += other.secondary_reads;
         self.supplementary_reads += other.supplementary_reads;
         self.missing_tc_tag += other.missing_tc_tag;
-        self.filter_metrics.merge(&other.filter_metrics);
+        self.filter_counts.merge(&other.filter_counts);
     }
 
     /// Calculate duplicate rate.
@@ -298,9 +297,11 @@ fn score_template(template: &Template) -> i64 {
 fn filter_template(
     template: &Template,
     config: &DedupFilterConfig,
-    metrics: &mut FilterMetrics,
+    counts: &mut TemplateFilterCounts,
 ) -> bool {
-    metrics.total_templates += 1;
+    // Primary-record count, recorded alongside the template count so `group` and
+    // `dedup` can render the same measurement in their respective units.
+    let primary_reads = u64::from(template.r1().is_some()) + u64::from(template.r2().is_some());
 
     // Fail closed when *any* record (primary, secondary, or supplementary) is
     // shorter than the minimum BAM record length: a truncated record indicates
@@ -308,7 +309,7 @@ fn filter_template(
     // malformed record silently dropped (and later panic in RawRecordView::new
     // on the dedup/serialize path).
     if template.records().iter().any(|r| r.len() < fgumi_raw_bam::MIN_BAM_RECORD_LEN) {
-        metrics.discarded_poor_alignment += 1;
+        counts.record_rejected(TemplateFilterReason::MalformedRecord, primary_reads);
         return false;
     }
 
@@ -316,7 +317,7 @@ fn filter_template(
     let raw_r2 = template.r2();
 
     if raw_r1.is_none() && raw_r2.is_none() {
-        metrics.discarded_poor_alignment += 1;
+        counts.record_rejected(TemplateFilterReason::NoPrimaryReads, primary_reads);
         return false;
     }
 
@@ -325,7 +326,7 @@ fn filter_template(
         && raw_r2
             .is_none_or(|r| (RawRecordView::new(r).flags() & fgumi_raw_bam::flags::UNMAPPED) != 0);
     if both_unmapped {
-        metrics.discarded_poor_alignment += 1;
+        counts.record_rejected(TemplateFilterReason::Unmapped, primary_reads);
         return false;
     }
 
@@ -334,14 +335,14 @@ fn filter_template(
         let flg = RawRecordView::new(raw).flags();
 
         if !config.include_non_pf && (flg & fgumi_raw_bam::flags::QC_FAIL) != 0 {
-            metrics.discarded_non_pf += 1;
+            counts.record_rejected(TemplateFilterReason::NotPassingFilter, primary_reads);
             return false;
         }
 
         if (flg & fgumi_raw_bam::flags::UNMAPPED) == 0 {
             let mapq = fgumi_raw_bam::mapq(raw);
             if mapq < config.min_mapq {
-                metrics.discarded_poor_alignment += 1;
+                counts.record_rejected(TemplateFilterReason::LowMappingQuality, primary_reads);
                 return false;
             }
         }
@@ -415,7 +416,7 @@ fn filter_template(
             // Compare as signed so a negative MQ (e.g., MQ:c:-1) fails the filter
             // rather than wrapping to 255 via `as u8`.
             if mq < i64::from(config.min_mapq) {
-                metrics.discarded_poor_alignment += 1;
+                counts.record_rejected(TemplateFilterReason::LowMateMappingQuality, primary_reads);
                 return false;
             }
         }
@@ -428,25 +429,25 @@ fn filter_template(
         if let Some(umi_bytes) = found_umi {
             match validate_umi(umi_bytes) {
                 UmiValidation::ContainsN => {
-                    metrics.discarded_ns_in_umi += 1;
+                    counts.record_rejected(TemplateFilterReason::NsInUmi, primary_reads);
                     return false;
                 }
                 UmiValidation::Valid(base_count) => {
                     if let Some(min_len) = config.min_umi_length
                         && base_count < min_len
                     {
-                        metrics.discarded_umi_too_short += 1;
+                        counts.record_rejected(TemplateFilterReason::UmiTooShort, primary_reads);
                         return false;
                     }
                 }
             }
         } else {
-            metrics.discarded_poor_alignment += 1;
+            counts.record_rejected(TemplateFilterReason::MissingUmi, primary_reads);
             return false;
         }
     }
 
-    metrics.accepted_templates += 1;
+    counts.record_accepted(primary_reads);
     true
 }
 
@@ -805,13 +806,13 @@ fn process_position_group(
         };
 
     // Filter templates
-    let mut filter_metrics = FilterMetrics::new();
+    let mut filter_counts = TemplateFilterCounts::new();
     let filtered_templates: Vec<Template> = candidate_templates
         .into_iter()
-        .filter(|t| filter_template(t, filter_config, &mut filter_metrics))
+        .filter(|t| filter_template(t, filter_config, &mut filter_counts))
         .collect();
 
-    dedup_metrics.filter_metrics = filter_metrics;
+    dedup_metrics.filter_counts = filter_counts;
 
     if filtered_templates.is_empty() && passthrough_templates.is_empty() {
         return Ok(ProcessedDedupGroup {
@@ -1834,11 +1835,11 @@ mod tests {
     #[test]
     fn test_filter_template_accepts_valid_template() {
         let config = default_filter_config();
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let template = create_mapped_template_with_umi("q1", "ACGTACGT", 30);
 
         assert!(filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_templates(), 1);
     }
 
     // ========================================================================
@@ -1931,11 +1932,11 @@ mod tests {
     #[test]
     fn test_filter_template_rejects_low_mapq() {
         let config = default_filter_config(); // min_mapq = 20
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let template = create_mapped_template_with_umi("q1", "ACGTACGT", 10); // MAPQ 10 < 20
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_poor_alignment, 1);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::LowMappingQuality), 1);
     }
 
     /// Truncated mate must reject the template (fail closed) rather than
@@ -1944,7 +1945,7 @@ mod tests {
     #[test]
     fn test_filter_template_rejects_truncated_mate() {
         let config = default_filter_config();
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         // A valid R1 (full record) and a truncated R2 (16 bytes; below MIN_BAM_RECORD_LEN = 32).
         let mut b = RawSamBuilder::new();
@@ -1973,8 +1974,12 @@ mod tests {
         };
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_poor_alignment, 1, "truncated mate must fail closed");
-        assert_eq!(metrics.accepted_templates, 0);
+        assert_eq!(
+            metrics.rejected_templates(TemplateFilterReason::MalformedRecord),
+            1,
+            "truncated mate must fail closed"
+        );
+        assert_eq!(metrics.accepted_templates(), 0);
     }
 
     /// A truncated secondary or supplementary alignment must also reject the
@@ -1983,7 +1988,7 @@ mod tests {
     #[test]
     fn test_filter_template_rejects_truncated_secondary() {
         let config = default_filter_config();
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         let mut b1 = RawSamBuilder::new();
         b1.read_name(b"q1")
@@ -2026,35 +2031,39 @@ mod tests {
         };
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_poor_alignment, 1, "truncated secondary must fail closed");
-        assert_eq!(metrics.accepted_templates, 0);
+        assert_eq!(
+            metrics.rejected_templates(TemplateFilterReason::MalformedRecord),
+            1,
+            "truncated secondary must fail closed"
+        );
+        assert_eq!(metrics.accepted_templates(), 0);
     }
 
     #[test]
     fn test_filter_template_rejects_umi_with_n() {
         let config = default_filter_config();
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let template = create_mapped_template_with_umi("q1", "ACNTACGT", 30); // N in UMI
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_ns_in_umi, 1);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::NsInUmi), 1);
     }
 
     #[test]
     fn test_filter_template_rejects_short_umi() {
         let mut config = default_filter_config();
         config.min_umi_length = Some(8); // Require 8 bases
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let template = create_mapped_template_with_umi("q1", "ACGT", 30); // Only 4 bases
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_umi_too_short, 1);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::UmiTooShort), 1);
     }
 
     #[test]
     fn test_filter_template_rejects_missing_umi_tag() {
         let config = default_filter_config();
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         // Create template without RX tag
         let record = {
@@ -2073,13 +2082,13 @@ mod tests {
             .expect("test template construction should not fail");
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_poor_alignment, 1);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::MissingUmi), 1);
     }
 
     #[test]
     fn test_filter_template_rejects_qc_fail() {
         let config = default_filter_config(); // include_non_pf = false
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         let record = {
             let mut b = RawSamBuilder::new();
@@ -2098,14 +2107,14 @@ mod tests {
             .expect("test template construction should not fail");
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_non_pf, 1);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::NotPassingFilter), 1);
     }
 
     #[test]
     fn test_filter_template_accepts_qc_fail_when_included() {
         let mut config = default_filter_config();
         config.include_non_pf = true; // Include QC-fail reads
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         let record = {
             let mut b = RawSamBuilder::new();
@@ -2124,13 +2133,13 @@ mod tests {
             .expect("test template construction should not fail");
 
         assert!(filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_templates(), 1);
     }
 
     #[test]
     fn test_filter_template_rejects_unmapped() {
         let config = default_filter_config();
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         let record = {
             let mut b = RawSamBuilder::new();
@@ -2145,18 +2154,18 @@ mod tests {
             .expect("test template construction should not fail");
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_poor_alignment, 1);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::Unmapped), 1);
     }
 
     #[test]
     fn test_filter_template_accepts_paired_umi_with_dash() {
         // Paired UMIs have format "ACGT-TGCA" with a dash separator
         let config = default_filter_config();
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let template = create_mapped_template_with_umi("q1", "ACGT-TGCA", 30);
 
         assert!(filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_templates(), 1);
     }
 
     // ========================================================================
@@ -2607,27 +2616,27 @@ mod tests {
     #[test]
     fn test_filter_paired_template_accepts_valid() {
         let config = default_filter_config();
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let template = create_paired_mapped_template_with_umi("q1", "ACGTACGT", 30, 30);
 
         assert!(filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_templates(), 1);
     }
 
     #[test]
     fn test_filter_paired_template_rejects_r2_low_mapq() {
         let config = default_filter_config(); // min_mapq = 20
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let template = create_paired_mapped_template_with_umi("q1", "ACGTACGT", 30, 10);
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_poor_alignment, 1);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::LowMappingQuality), 1);
     }
 
     #[test]
     fn test_filter_paired_template_rejects_r2_umi_with_n() {
         let config = default_filter_config();
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         // R1 has valid UMI, but R2 has N in UMI
         let r1 = {
             let mut b = RawSamBuilder::new();
@@ -2659,18 +2668,18 @@ mod tests {
             .expect("test template construction should not fail");
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_ns_in_umi, 1);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::NsInUmi), 1);
     }
 
     #[test]
     fn test_filter_paired_no_reads_rejected() {
         // Template with no primary reads (empty records list)
         let config = default_filter_config();
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let template = Template::new(b"empty".to_vec());
 
         assert!(!filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_poor_alignment, 1);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::NoPrimaryReads), 1);
     }
 
     // ========================================================================
@@ -2818,8 +2827,9 @@ mod tests {
 
     #[test]
     fn test_filter_template_raw_truncated_record_no_panic() {
-        // After fix: truncated records no longer panic -- they gracefully return false
-        // (rejected as poor alignment due to missing UMI tag).
+        // After fix: truncated records no longer panic -- they gracefully return false.
+        // The aux block is truncated rather than the record itself, so the record
+        // clears the minimum-length check and is rejected for the missing UMI tag.
 
         let raw = make_raw_bam_record_truncated_aux();
         let template =
@@ -2832,12 +2842,12 @@ mod tests {
             min_umi_length: None,
             no_umi: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         // Should not panic; should reject gracefully due to missing UMI
         let result = filter_template(&template, &config, &mut metrics);
         assert!(!result, "Truncated record should be rejected");
-        assert_eq!(metrics.discarded_poor_alignment, 1);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::MissingUmi), 1);
     }
 
     // Test that the raw-byte mode MQ tag issue actually occurs in filter_template_raw
@@ -2876,15 +2886,15 @@ mod tests {
             min_umi_length: None,
             no_umi: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         // After fix: filter_template_raw now uses find_int_tag which handles all integer types.
         // The template should be REJECTED because mate MAPQ=10 < min_mapq=20.
         let result = filter_template(&template, &config, &mut metrics);
 
         assert!(!result, "Template with low mate MAPQ should be rejected");
-        assert_eq!(metrics.accepted_templates, 0);
-        assert_eq!(metrics.discarded_poor_alignment, 1);
+        assert_eq!(metrics.accepted_templates(), 0);
+        assert_eq!(metrics.rejected_templates(TemplateFilterReason::LowMateMappingQuality), 1);
     }
 
     // ========================================================================
@@ -3072,52 +3082,49 @@ mod tests {
     // filter_template_raw passing/rejecting tests
     // ========================================================================
 
-    /// Which `FilterMetrics` field an `rstest` case expects to advance.
-    #[derive(Debug, Clone, Copy)]
-    enum FilterExpect {
-        Accepted,
-        PoorAlignment,
-        NonPf,
-        NsInUmi,
-        UmiTooShort,
-    }
+    /// What an `rstest` case expects the filter to record: `None` for an accepted
+    /// template, or the specific reason it was rejected for. This used to be a
+    /// bespoke enum mirroring fgbio's four discard columns, which forced
+    /// `rejects_low_mapq` and `rejects_unmapped` to share one `PoorAlignment`
+    /// expectation; keying on `TemplateFilterReason` tells them apart.
+    type FilterExpect = Option<TemplateFilterReason>;
 
     #[rstest]
     #[case::accepts_valid(
         fgumi_raw_bam::flags::PAIRED
             | fgumi_raw_bam::flags::FIRST_SEGMENT
             | fgumi_raw_bam::flags::MATE_UNMAPPED,
-        30, b"ACGTACGT", 20, None, true, FilterExpect::Accepted
+        30, b"ACGTACGT", 20, None, true, None
     )]
     #[case::rejects_low_mapq(
         fgumi_raw_bam::flags::PAIRED
             | fgumi_raw_bam::flags::FIRST_SEGMENT
             | fgumi_raw_bam::flags::MATE_UNMAPPED,
-        10, b"ACGT", 20, None, false, FilterExpect::PoorAlignment
+        10, b"ACGT", 20, None, false, Some(TemplateFilterReason::LowMappingQuality)
     )]
     #[case::rejects_qc_fail(
         fgumi_raw_bam::flags::PAIRED
             | fgumi_raw_bam::flags::FIRST_SEGMENT
             | fgumi_raw_bam::flags::MATE_UNMAPPED
             | fgumi_raw_bam::flags::QC_FAIL,
-        30, b"ACGT", 0, None, false, FilterExpect::NonPf
+        30, b"ACGT", 0, None, false, Some(TemplateFilterReason::NotPassingFilter)
     )]
     #[case::rejects_umi_with_n(
         fgumi_raw_bam::flags::PAIRED
             | fgumi_raw_bam::flags::FIRST_SEGMENT
             | fgumi_raw_bam::flags::MATE_UNMAPPED,
-        30, b"ANGT", 0, None, false, FilterExpect::NsInUmi
+        30, b"ANGT", 0, None, false, Some(TemplateFilterReason::NsInUmi)
     )]
     #[case::rejects_short_umi(
         fgumi_raw_bam::flags::PAIRED
             | fgumi_raw_bam::flags::FIRST_SEGMENT
             | fgumi_raw_bam::flags::MATE_UNMAPPED,
-        30, b"AC", 0, Some(6), false, FilterExpect::UmiTooShort
+        30, b"AC", 0, Some(6), false, Some(TemplateFilterReason::UmiTooShort)
     )]
     #[case::rejects_unmapped(
         fgumi_raw_bam::flags::UNMAPPED
             | fgumi_raw_bam::flags::MATE_UNMAPPED,
-        0, b"ACGT", 0, None, false, FilterExpect::PoorAlignment
+        0, b"ACGT", 0, None, false, Some(TemplateFilterReason::Unmapped)
     )]
     fn test_filter_template_raw(
         #[case] flags: u16,
@@ -3138,15 +3145,15 @@ mod tests {
             min_umi_length,
             no_umi: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         assert_eq!(filter_template(&template, &config, &mut metrics), expect_pass);
-        match expect {
-            FilterExpect::Accepted => assert_eq!(metrics.accepted_templates, 1),
-            FilterExpect::PoorAlignment => assert_eq!(metrics.discarded_poor_alignment, 1),
-            FilterExpect::NonPf => assert_eq!(metrics.discarded_non_pf, 1),
-            FilterExpect::NsInUmi => assert_eq!(metrics.discarded_ns_in_umi, 1),
-            FilterExpect::UmiTooShort => assert_eq!(metrics.discarded_umi_too_short, 1),
+        // Assert across every reason, not just the expected one, so a case cannot
+        // pass while also incrementing a bucket it should not have touched.
+        for reason in TemplateFilterReason::ALL {
+            let expected = u64::from(expect == Some(reason));
+            assert_eq!(metrics.rejected_templates(reason), expected, "{reason:?}");
         }
+        assert_eq!(metrics.accepted_templates(), u64::from(expect.is_none()));
     }
 
     // ========================================================================
@@ -3205,7 +3212,7 @@ mod tests {
     fn test_filter_template_accepts_missing_umi_when_no_umi_mode() {
         let mut config = default_filter_config();
         config.no_umi = true;
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         // Create template without RX tag
         let record = {
@@ -3225,19 +3232,19 @@ mod tests {
 
         // In no_umi mode, templates without UMI tags should be accepted
         assert!(filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_templates(), 1);
     }
 
     #[test]
     fn test_filter_template_accepts_umi_with_n_when_no_umi_mode() {
         let mut config = default_filter_config();
         config.no_umi = true;
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let template = create_mapped_template_with_umi("q1", "ACNTACGT", 30);
 
         // In no_umi mode, UMIs with N should be accepted (UMI validation is skipped)
         assert!(filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_templates(), 1);
     }
 
     #[test]
@@ -3245,12 +3252,12 @@ mod tests {
         let mut config = default_filter_config();
         config.min_umi_length = Some(8);
         config.no_umi = true;
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let template = create_mapped_template_with_umi("q1", "ACGT", 30);
 
         // In no_umi mode, short UMIs should be accepted (min_umi_length is not checked)
         assert!(filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_templates(), 1);
     }
 
     // ========================================================================
@@ -3325,11 +3332,11 @@ mod tests {
             min_umi_length: None,
             no_umi: true,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         // In no_umi mode, templates without UMI tags should be accepted
         assert!(filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_templates(), 1);
     }
 
     #[test]
@@ -3353,11 +3360,11 @@ mod tests {
             min_umi_length: None,
             no_umi: true,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         // In no_umi mode, UMIs with N should be accepted (UMI validation is skipped)
         assert!(filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_templates(), 1);
     }
 
     #[test]
@@ -3381,10 +3388,10 @@ mod tests {
             min_umi_length: Some(6),
             no_umi: true,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
 
         // In no_umi mode, short UMIs should be accepted (min_umi_length is not checked)
         assert!(filter_template(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_templates(), 1);
     }
 }
diff --git a/src/lib/commands/group.rs b/src/lib/commands/group.rs
index 0afeeaadb..8aab055ea 100644
--- a/src/lib/commands/group.rs
+++ b/src/lib/commands/group.rs
@@ -7,11 +7,11 @@ use crate::commands::common::{
     build_pipeline_config, is_r1_genomically_earlier_raw,
 };
 use crate::grouper::{
-    FilterMetrics, ProcessedPositionGroup, RawPositionGroup, RecordPositionGrouper,
-    build_templates_from_records,
+    ProcessedPositionGroup, RawPositionGroup, RecordPositionGrouper, build_templates_from_records,
 };
 use crate::logging::{OperationTimer, log_umi_grouping_summary};
 use crate::metrics::group::{FamilySizeMetrics, PositionGroupSizeMetrics, UmiGroupingMetrics};
+use crate::metrics::{TemplateFilterCounts, TemplateFilterReason};
 use crate::per_thread_accumulator::PerThreadAccumulator;
 use crate::read_info::LibraryIndex;
 use crate::sam::is_template_coordinate_sorted;
@@ -70,11 +70,15 @@ fn estimate_templates_heap_size(templates: &[Template]) -> usize {
 struct GroupMetricsAccumulator {
     family_sizes: AHashMap<usize, u64>,
     position_group_sizes: AHashMap<usize, u64>,
-    filter_metrics: FilterMetrics,
+    filter_counts: TemplateFilterCounts,
 }
 
 impl GroupMetricsAccumulator {
-    fn record_group(&mut self, family_sizes: AHashMap<usize, u64>, filter_metrics: &FilterMetrics) {
+    fn record_group(
+        &mut self,
+        family_sizes: AHashMap<usize, u64>,
+        filter_counts: &TemplateFilterCounts,
+    ) {
         let position_group_size: u64 = family_sizes.values().sum();
         for (size, count) in family_sizes {
             *self.family_sizes.entry(size).or_insert(0) += count;
@@ -82,7 +86,7 @@ impl GroupMetricsAccumulator {
         if position_group_size > 0 {
             *self.position_group_sizes.entry(position_group_size as usize).or_insert(0) += 1;
         }
-        self.filter_metrics.merge(filter_metrics);
+        self.filter_counts.merge(filter_counts);
     }
 }
 
@@ -112,13 +116,14 @@ struct GroupFilterConfig {
 fn filter_template_raw(
     template: &Template,
     config: &GroupFilterConfig,
-    metrics: &mut FilterMetrics,
+    counts: &mut TemplateFilterCounts,
 ) -> bool {
     use fgumi_raw_bam;
     use fgumi_raw_bam::RawRecordView;
 
+    // Recorded once at the accept/reject site rather than on entry, so the
+    // accepted + rejected == total invariant holds by construction.
     let primary_reads = u64::from(template.r1().is_some()) + u64::from(template.r2().is_some());
-    metrics.total_templates += primary_reads;
 
     // Fail closed when *any* record (primary, secondary, or supplementary) is
     // shorter than the minimum BAM record length: a truncated record indicates
@@ -126,7 +131,7 @@ fn filter_template_raw(
     // treated as a single-read template, and never reaching RawRecordView::new
     // on a malformed slice).
     if template.records().iter().any(|r| r.len() < fgumi_raw_bam::MIN_BAM_RECORD_LEN) {
-        metrics.discarded_poor_alignment += primary_reads;
+        counts.record_rejected(TemplateFilterReason::MalformedRecord, primary_reads);
         return false;
     }
 
@@ -135,7 +140,7 @@ fn filter_template_raw(
     let num_primary_reads = primary_reads;
 
     if raw_r1.is_none() && raw_r2.is_none() {
-        metrics.discarded_poor_alignment += num_primary_reads;
+        counts.record_rejected(TemplateFilterReason::NoPrimaryReads, num_primary_reads);
         return false;
     }
 
@@ -145,7 +150,7 @@ fn filter_template_raw(
         && raw_r2
             .is_none_or(|r| (RawRecordView::new(r).flags() & fgumi_raw_bam::flags::UNMAPPED) != 0);
     if both_unmapped && !config.allow_unmapped {
-        metrics.discarded_poor_alignment += num_primary_reads;
+        counts.record_rejected(TemplateFilterReason::Unmapped, num_primary_reads);
         return false;
     }
 
@@ -154,13 +159,13 @@ fn filter_template_raw(
         let flg = RawRecordView::new(raw).flags();
 
         if !config.include_non_pf && (flg & fgumi_raw_bam::flags::QC_FAIL) != 0 {
-            metrics.discarded_non_pf += num_primary_reads;
+            counts.record_rejected(TemplateFilterReason::NotPassingFilter, num_primary_reads);
             return false;
         }
 
         if (flg & fgumi_raw_bam::flags::UNMAPPED) == 0 && fgumi_raw_bam::mapq(raw) < config.min_mapq
         {
-            metrics.discarded_poor_alignment += num_primary_reads;
+            counts.record_rejected(TemplateFilterReason::LowMappingQuality, num_primary_reads);
             return false;
         }
     }
@@ -238,7 +243,7 @@ fn filter_template_raw(
             && let Some(mq) = found_mq
             && mq < i64::from(config.min_mapq)
         {
-            metrics.discarded_poor_alignment += num_primary_reads;
+            counts.record_rejected(TemplateFilterReason::LowMateMappingQuality, num_primary_reads);
             return false;
         }
 
@@ -251,25 +256,26 @@ fn filter_template_raw(
         if let Some(umi_bytes) = found_umi {
             match validate_umi(umi_bytes) {
                 UmiValidation::ContainsN => {
-                    metrics.discarded_ns_in_umi += num_primary_reads;
+                    counts.record_rejected(TemplateFilterReason::NsInUmi, num_primary_reads);
                     return false;
                 }
                 UmiValidation::Valid(base_count) => {
                     if let Some(min_len) = config.min_umi_length
                         && base_count < min_len
                     {
-                        metrics.discarded_umi_too_short += num_primary_reads;
+                        counts
+                            .record_rejected(TemplateFilterReason::UmiTooShort, num_primary_reads);
                         return false;
                     }
                 }
             }
         } else {
-            metrics.discarded_poor_alignment += num_primary_reads;
+            counts.record_rejected(TemplateFilterReason::MissingUmi, num_primary_reads);
             return false;
         }
     }
 
-    metrics.accepted_templates += num_primary_reads;
+    counts.record_accepted(num_primary_reads);
     true
 }
 
@@ -901,16 +907,11 @@ pub struct GroupReadsByUmi {
 ///
 /// Shared by both the pipeline and single-threaded execution paths.
 fn build_grouping_metrics(
-    filter_metrics: &FilterMetrics,
+    filter_counts: &TemplateFilterCounts,
     family_size_counter: &AHashMap<usize, u64>,
 ) -> UmiGroupingMetrics {
     let mut metrics = UmiGroupingMetrics::new();
-    metrics.total_records = filter_metrics.total_templates;
-    metrics.accepted_records = filter_metrics.accepted_templates;
-    metrics.discarded_non_pf = filter_metrics.discarded_non_pf;
-    metrics.discarded_poor_alignment = filter_metrics.discarded_poor_alignment;
-    metrics.discarded_ns_in_umi = filter_metrics.discarded_ns_in_umi;
-    metrics.discarded_umi_too_short = filter_metrics.discarded_umi_too_short;
+    metrics.set_filter_counts(filter_counts);
 
     metrics.total_families = family_size_counter.values().sum::<u64>();
     metrics.unique_molecule_ids = metrics.total_families;
@@ -1244,12 +1245,12 @@ impl Command for GroupReadsByUmi {
                     return Ok(ProcessedPositionGroup {
                         templates: Vec::new(),
                         family_sizes: AHashMap::new(),
-                        filter_metrics: FilterMetrics::new(),
+                        filter_counts: TemplateFilterCounts::new(),
                         input_record_count,
                         distinct_mi_count: 0,
                     });
                 }
-                let mut filter_metrics = FilterMetrics::new();
+                let mut filter_counts = TemplateFilterCounts::new();
 
                 // Track memory usage if debug mode is enabled (optimized for hot path)
                 #[cfg(feature = "memory-debug")]
@@ -1283,7 +1284,7 @@ impl Command for GroupReadsByUmi {
                 // Filter templates
                 let filtered_templates: Vec<Template> = all_templates
                     .into_iter()
-                    .filter(|t| filter_template_raw(t, &filter_config, &mut filter_metrics))
+                    .filter(|t| filter_template_raw(t, &filter_config, &mut filter_counts))
                     .collect();
 
                 // Track filtered template memory (optimized for hot path).
@@ -1321,7 +1322,7 @@ impl Command for GroupReadsByUmi {
                     return Ok(ProcessedPositionGroup {
                         templates: Vec::new(),
                         family_sizes: AHashMap::new(),
-                        filter_metrics,
+                        filter_counts,
                         input_record_count,
                         distinct_mi_count: 0,
                     });
@@ -1429,7 +1430,7 @@ impl Command for GroupReadsByUmi {
                 Ok(ProcessedPositionGroup {
                     templates,
                     family_sizes,
-                    filter_metrics,
+                    filter_counts,
                     input_record_count,
                     distinct_mi_count,
                 })
@@ -1454,7 +1455,7 @@ impl Command for GroupReadsByUmi {
                 // Memory stays O(threads × distinct sizes) instead of growing
                 // one hashmap per position group.
                 accumulators_clone.with_slot(|acc| {
-                    acc.record_group(processed.family_sizes, &processed.filter_metrics);
+                    acc.record_group(processed.family_sizes, &processed.filter_counts);
                 });
 
                 // Save input record count for progress tracking
@@ -1550,7 +1551,7 @@ impl Command for GroupReadsByUmi {
         // requiring unique ownership.
         let mut family_size_counter: AHashMap<usize, u64> = AHashMap::with_capacity(50);
         let mut position_group_size_counter: AHashMap<usize, u64> = AHashMap::with_capacity(50);
-        let mut total_filter_metrics = FilterMetrics::new();
+        let mut total_filter_counts = TemplateFilterCounts::new();
 
         for slot in accumulators.slots() {
             let acc = slot.lock();
@@ -1560,10 +1561,10 @@ impl Command for GroupReadsByUmi {
             for (&size, &count) in &acc.position_group_sizes {
                 *position_group_size_counter.entry(size).or_insert(0) += count;
             }
-            total_filter_metrics.merge(&acc.filter_metrics);
+            total_filter_counts.merge(&acc.filter_counts);
         }
 
-        let metrics = build_grouping_metrics(&total_filter_metrics, &family_size_counter);
+        let metrics = build_grouping_metrics(&total_filter_counts, &family_size_counter);
         log_umi_grouping_summary(&metrics);
 
         // Write all metrics (individual flags and --metrics prefix)
@@ -1620,7 +1621,7 @@ impl GroupReadsByUmi {
         let mut grouper = RecordPositionGrouper::new();
 
         // Metrics accumulators (no lock-free queue needed in single-threaded mode)
-        let mut total_filter_metrics = FilterMetrics::new();
+        let mut total_filter_counts = TemplateFilterCounts::new();
         let mut family_size_counter: AHashMap<usize, u64> = AHashMap::with_capacity(50);
         let mut position_group_size_counter: AHashMap<usize, u64> = AHashMap::with_capacity(50);
         let mut next_mi_base: u64 = 0;
@@ -1655,7 +1656,7 @@ impl GroupReadsByUmi {
                     self.parallel_group_min_templates.as_ref(),
                     raw_tag,
                     assign_tag_bytes,
-                    &mut total_filter_metrics,
+                    &mut total_filter_counts,
                     &mut family_size_counter,
                     &mut position_group_size_counter,
                     &mut next_mi_base,
@@ -1679,7 +1680,7 @@ impl GroupReadsByUmi {
                 self.parallel_group_min_templates.as_ref(),
                 raw_tag,
                 assign_tag_bytes,
-                &mut total_filter_metrics,
+                &mut total_filter_counts,
                 &mut family_size_counter,
                 &mut position_group_size_counter,
                 &mut next_mi_base,
@@ -1694,7 +1695,7 @@ impl GroupReadsByUmi {
         writer.into_inner().finish().context("Failed to finish output BAM")?;
         info!("Wrote output to {}", self.io.output.display());
 
-        let metrics = build_grouping_metrics(&total_filter_metrics, &family_size_counter);
+        let metrics = build_grouping_metrics(&total_filter_counts, &family_size_counter);
         log_umi_grouping_summary(&metrics);
 
         // Write all metrics (individual flags and --metrics prefix)
@@ -1723,7 +1724,7 @@ impl GroupReadsByUmi {
         parallel_group_min_templates: Option<&ParallelMinTemplates>,
         raw_tag: [u8; 2],
         assign_tag_bytes: [u8; 2],
-        total_filter_metrics: &mut FilterMetrics,
+        total_filter_counts: &mut TemplateFilterCounts,
         family_size_counter: &mut AHashMap<usize, u64>,
         position_group_size_counter: &mut AHashMap<usize, u64>,
         next_mi_base: &mut u64,
@@ -1733,15 +1734,15 @@ impl GroupReadsByUmi {
         // Build templates from raw records
         let all_templates = build_templates_from_records(group.records)?;
 
-        let mut filter_metrics = FilterMetrics::new();
+        let mut filter_counts = TemplateFilterCounts::new();
 
         // Filter templates
         let filtered_templates: Vec<Template> = all_templates
             .into_iter()
-            .filter(|t| filter_template_raw(t, filter_config, &mut filter_metrics))
+            .filter(|t| filter_template_raw(t, filter_config, &mut filter_counts))
             .collect();
 
-        total_filter_metrics.merge(&filter_metrics);
+        total_filter_counts.merge(&filter_counts);
 
         if filtered_templates.is_empty() {
             return Ok(());
@@ -3027,7 +3028,7 @@ mod tests {
     ) -> Result<()> {
         // Same dataset as test_metrics_prefix_writes_all_files, plus one
         // extra N-containing UMI pair (discarded) so the parity check also
-        // covers the `filter_metrics` merge in the per-thread accumulators:
+        // covers the `filter_counts` merge in the per-thread accumulators:
         //   Position group 1 (pos 100,300): UMI AAA x3 + CCC x1 = 2 families
         //   Position group 2 (pos 200,400): UMI AAA x2          = 1 family
         //   Position group 3 (pos 300,500): UMI AAA/CCC/GGG x1  = 3 families
@@ -5976,9 +5977,9 @@ mod tests {
             no_umi: false,
             allow_unmapped: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         assert!(filter_template_raw(&template, &config, &mut metrics));
-        assert_eq!(metrics.accepted_templates, 1);
+        assert_eq!(metrics.accepted_primary_reads(), 1);
     }
 
     #[test]
@@ -6001,9 +6002,9 @@ mod tests {
             no_umi: false,
             allow_unmapped: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         assert!(!filter_template_raw(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_poor_alignment, 1);
+        assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::LowMappingQuality), 1);
     }
 
     #[test]
@@ -6027,9 +6028,9 @@ mod tests {
             no_umi: false,
             allow_unmapped: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         assert!(!filter_template_raw(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_non_pf, 1);
+        assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::NotPassingFilter), 1);
     }
 
     #[test]
@@ -6052,9 +6053,9 @@ mod tests {
             no_umi: false,
             allow_unmapped: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         assert!(!filter_template_raw(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_ns_in_umi, 1);
+        assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::NsInUmi), 1);
     }
 
     #[test]
@@ -6077,9 +6078,9 @@ mod tests {
             no_umi: false,
             allow_unmapped: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         assert!(!filter_template_raw(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_umi_too_short, 1);
+        assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::UmiTooShort), 1);
     }
 
     #[test]
@@ -6100,9 +6101,9 @@ mod tests {
             no_umi: false,
             allow_unmapped: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         assert!(!filter_template_raw(&template, &config, &mut metrics));
-        assert_eq!(metrics.discarded_poor_alignment, 1);
+        assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::Unmapped), 1);
     }
 
     /// A truncated secondary or supplementary alignment must reject the whole
@@ -6145,12 +6146,12 @@ mod tests {
             no_umi: false,
             allow_unmapped: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         assert!(
             !filter_template_raw(&template, &config, &mut metrics),
             "truncated secondary must cause the template to be rejected"
         );
-        assert_eq!(metrics.discarded_poor_alignment, 2);
+        assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::MalformedRecord), 2);
     }
 
     #[test]
@@ -6195,7 +6196,7 @@ mod tests {
             no_umi: false,
             allow_unmapped: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         assert!(
             !filter_template_raw(&template, &config, &mut metrics),
             "truncated R1 must cause the template to be rejected"
@@ -6268,7 +6269,7 @@ mod tests {
             no_umi: false,
             allow_unmapped: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         assert!(
             !filter_template_raw(&template, &config, &mut metrics),
             "negative mate MQ must compare below min_mapq (signed semantics)"
@@ -6297,7 +6298,7 @@ mod tests {
             no_umi: false,
             allow_unmapped: false,
         };
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         // Supplementary-only template has no primary R1/R2 → raw_r1() returns None
         assert!(!filter_template_raw(&template, &config, &mut metrics));
     }
@@ -6647,12 +6648,12 @@ mod tests {
             allow_unmapped: true,
         };
 
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let should_keep = filter_template_raw(&template, &config, &mut metrics);
 
         assert!(should_keep, "Unmapped template should be kept when allow_unmapped=true");
-        assert_eq!(metrics.total_templates, 2, "Should count 2 records");
-        assert_eq!(metrics.discarded_poor_alignment, 0, "Should not discard for poor alignment");
+        assert_eq!(metrics.total_primary_reads(), 2, "Should count 2 records");
+        assert_eq!(metrics.total_rejected_primary_reads(), 0, "Should not discard anything");
 
         Ok(())
     }
@@ -6671,14 +6672,15 @@ mod tests {
             allow_unmapped: false,
         };
 
-        let mut metrics = FilterMetrics::new();
+        let mut metrics = TemplateFilterCounts::new();
         let should_keep = filter_template_raw(&template, &config, &mut metrics);
 
         assert!(!should_keep, "Unmapped template should be rejected when allow_unmapped=false");
-        assert_eq!(metrics.total_templates, 2, "Should count 2 records");
+        assert_eq!(metrics.total_primary_reads(), 2, "Should count 2 records");
         assert_eq!(
-            metrics.discarded_poor_alignment, 2,
-            "Should discard both reads for poor alignment"
+            metrics.rejected_primary_reads(TemplateFilterReason::Unmapped),
+            2,
+            "Should discard both reads as unmapped"
         );
 
         Ok(())
diff --git a/src/lib/grouper.rs b/src/lib/grouper.rs
index 16afdd561..5217df990 100644
--- a/src/lib/grouper.rs
+++ b/src/lib/grouper.rs
@@ -12,6 +12,7 @@ use noodles::sam::alignment::RecordBuf;
 
 use crate::template::{Template, TemplateBatch};
 use crate::unified_pipeline::{BatchWeight, DecodedRecord, Grouper, MemoryEstimate};
+use fgumi_metrics::TemplateFilterCounts;
 use fgumi_raw_bam;
 use fgumi_raw_bam::{RawRecord, raw_record_to_record_buf};
 
@@ -278,48 +279,13 @@ impl MemoryEstimate for ProcessedPositionGroup {
         // Each entry is ~24 bytes (key + value + overhead)
         let family_sizes_size = self.family_sizes.len() * 24;
 
-        // filter_metrics: FilterMetrics is mostly inline (u64 fields)
+        // filter_counts: TemplateFilterCounts is entirely inline (u64 fields + arrays)
         // Just a small struct overhead
 
         templates_size + templates_vec_overhead + family_sizes_size
     }
 }
 
-/// Metrics tracking what was filtered during processing.
-#[derive(Default, Clone, Debug)]
-pub struct FilterMetrics {
-    /// Total templates seen before filtering.
-    pub total_templates: u64,
-    /// Templates accepted after filtering.
-    pub accepted_templates: u64,
-    /// Templates discarded because they weren't passing filter.
-    pub discarded_non_pf: u64,
-    /// Templates discarded due to poor alignment.
-    pub discarded_poor_alignment: u64,
-    /// Templates discarded due to Ns in UMI.
-    pub discarded_ns_in_umi: u64,
-    /// Templates discarded due to UMI being too short.
-    pub discarded_umi_too_short: u64,
-}
-
-impl FilterMetrics {
-    /// Create new empty metrics.
-    #[must_use]
-    pub fn new() -> Self {
-        Self::default()
-    }
-
-    /// Merge another `FilterMetrics` into this one.
-    pub fn merge(&mut self, other: &FilterMetrics) {
-        self.total_templates += other.total_templates;
-        self.accepted_templates += other.accepted_templates;
-        self.discarded_non_pf += other.discarded_non_pf;
-        self.discarded_poor_alignment += other.discarded_poor_alignment;
-        self.discarded_ns_in_umi += other.discarded_ns_in_umi;
-        self.discarded_umi_too_short += other.discarded_umi_too_short;
-    }
-}
-
 /// Result of processing a position group through UMI assignment.
 #[derive(Debug)]
 pub struct ProcessedPositionGroup {
@@ -328,8 +294,8 @@ pub struct ProcessedPositionGroup {
     pub templates: Vec<Template>,
     /// Family size counts for this position group.
     pub family_sizes: ahash::AHashMap<usize, u64>,
-    /// Filter metrics for this position group (thread-local, merged later).
-    pub filter_metrics: FilterMetrics,
+    /// Filter counts for this position group (thread-local, merged later).
+    pub filter_counts: TemplateFilterCounts,
     /// Total input records processed (for progress tracking).
     pub input_record_count: u64,
     /// Number of distinct numeric molecule IDs assigned in this group (i.e., the
diff --git a/src/lib/metrics/mod.rs b/src/lib/metrics/mod.rs
index 633462104..4091af4d6 100644
--- a/src/lib/metrics/mod.rs
+++ b/src/lib/metrics/mod.rs
@@ -24,6 +24,7 @@ pub use fgumi_metrics::duplex;
 pub use fgumi_metrics::group;
 pub use fgumi_metrics::shared;
 pub use fgumi_metrics::simplex;
+pub use fgumi_metrics::template_filter;
 pub use fgumi_metrics::writer;
 
 // Re-export commonly used types
@@ -36,4 +37,5 @@ pub use duplex::{
 };
 pub use group::{FamilySizeMetrics, PositionGroupSizeMetrics, UmiGroupingMetrics};
 pub use shared::UmiMetric;
+pub use template_filter::{TemplateFilterCounts, TemplateFilterReason};
 pub use writer::{read_metrics, write_metrics, write_metrics_auto};

From 72ef6b4e5e949a27295cd4aa17ec7a7ec2941691 Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Tue, 11 Aug 2026 23:26:27 -0700
Subject: [PATCH 4/8] refactor(dedup): rename DedupMetrics to DedupCounts

Distinguish the per-worker accumulator from the serializable metrics schema,
which moves to fgumi-metrics as DeduplicationMetrics.
---
 src/lib/commands/dedup.rs | 170 +++++++++++++++++++-------------------
 1 file changed, 87 insertions(+), 83 deletions(-)

diff --git a/src/lib/commands/dedup.rs b/src/lib/commands/dedup.rs
index 60fc12006..97b7644da 100644
--- a/src/lib/commands/dedup.rs
+++ b/src/lib/commands/dedup.rs
@@ -65,9 +65,13 @@ const DUPLICATE_FLAG: u16 = 0x400;
 // Metrics
 //////////////////////////////////////////////////////////////////////////////
 
-/// Metrics collected during deduplication.
+/// Per-worker deduplication counters, merged into a single total and then
+/// rendered into the serializable metrics schema for output.
+///
+/// Named `Counts` rather than `Metrics` to keep it distinct from the file
+/// schema: this is the accumulator, that is the file.
 #[derive(Debug, Default, Clone)]
-pub struct DedupMetrics {
+pub struct DedupCounts {
     /// Total templates processed
     pub total_templates: u64,
     /// Templates marked as duplicates
@@ -90,9 +94,9 @@ pub struct DedupMetrics {
     pub filter_counts: TemplateFilterCounts,
 }
 
-impl DedupMetrics {
-    /// Merge another `DedupMetrics` into this one.
-    pub fn merge(&mut self, other: &DedupMetrics) {
+impl DedupCounts {
+    /// Merge another `DedupCounts` into this one.
+    pub fn merge(&mut self, other: &DedupCounts) {
         self.total_templates += other.total_templates;
         self.duplicate_templates += other.duplicate_templates;
         self.unique_templates += other.unique_templates;
@@ -116,7 +120,7 @@ impl DedupMetrics {
     }
 }
 
-/// Serializable version of `DedupMetrics` for file output.
+/// Serializable version of `DedupCounts` for file output.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 struct DedupMetricsOutput {
     total_templates: u64,
@@ -134,8 +138,8 @@ struct DedupMetricsOutput {
     missing_tc_tag: u64,
 }
 
-impl From<&DedupMetrics> for DedupMetricsOutput {
-    fn from(m: &DedupMetrics) -> Self {
+impl From<&DedupCounts> for DedupMetricsOutput {
+    fn from(m: &DedupCounts) -> Self {
         Self {
             total_templates: m.total_templates,
             unique_templates: m.unique_templates,
@@ -157,9 +161,9 @@ impl From<&DedupMetrics> for DedupMetricsOutput {
 
 /// Metrics collected per position group, aggregated after pipeline completion.
 #[derive(Default, Debug)]
-struct CollectedDedupMetrics {
+struct CollectedDedupCounts {
     /// Dedup-specific metrics
-    dedup_metrics: DedupMetrics,
+    dedup_counts: DedupCounts,
     /// Family size counts
     family_sizes: AHashMap<usize, u64>,
 }
@@ -175,7 +179,7 @@ pub struct ProcessedDedupGroup {
     /// Family size counts for this group.
     pub family_sizes: AHashMap<usize, u64>,
     /// Dedup metrics for this group.
-    pub dedup_metrics: DedupMetrics,
+    pub dedup_counts: DedupCounts,
     /// Total input records processed (for progress tracking).
     pub input_record_count: u64,
     /// Number of distinct numeric `MoleculeId`s assigned in this group.
@@ -196,7 +200,7 @@ impl MemoryEstimate for ProcessedDedupGroup {
         self.templates.iter().map(MemoryEstimate::estimate_heap_size).sum::<usize>()
             + self.templates.capacity() * std::mem::size_of::<Template>()
             + self.family_sizes.capacity() * std::mem::size_of::<(usize, u64)>()
-            + std::mem::size_of::<DedupMetrics>()
+            + std::mem::size_of::<DedupCounts>()
     }
 }
 
@@ -704,24 +708,24 @@ fn assign_umi_groups(
 ///
 /// Optimized with fast paths for small families (size 1-3) to avoid
 /// allocation and sorting overhead for the common case.
-fn mark_duplicates_in_family(templates: &mut [&mut Template], dedup_metrics: &mut DedupMetrics) {
+fn mark_duplicates_in_family(templates: &mut [&mut Template], dedup_counts: &mut DedupCounts) {
     match templates.len() {
         0 => return,
         1 => {
             // Single template - not a duplicate
-            dedup_metrics.unique_templates += 1;
+            dedup_counts.unique_templates += 1;
             return;
         }
         2 => {
             // Fast path for size 2 (very common case) - no allocation needed
             let s0 = score_template(templates[0]);
             let s1 = score_template(templates[1]);
-            dedup_metrics.unique_templates += 1;
-            dedup_metrics.duplicate_templates += 1;
+            dedup_counts.unique_templates += 1;
+            dedup_counts.duplicate_templates += 1;
             if s0 >= s1 {
-                mark_template_as_duplicate(templates[1], dedup_metrics);
+                mark_template_as_duplicate(templates[1], dedup_counts);
             } else {
-                mark_template_as_duplicate(templates[0], dedup_metrics);
+                mark_template_as_duplicate(templates[0], dedup_counts);
             }
             return;
         }
@@ -730,17 +734,17 @@ fn mark_duplicates_in_family(templates: &mut [&mut Template], dedup_metrics: &mu
             let s0 = score_template(templates[0]);
             let s1 = score_template(templates[1]);
             let s2 = score_template(templates[2]);
-            dedup_metrics.unique_templates += 1;
-            dedup_metrics.duplicate_templates += 2;
+            dedup_counts.unique_templates += 1;
+            dedup_counts.duplicate_templates += 2;
             if s0 >= s1 && s0 >= s2 {
-                mark_template_as_duplicate(templates[1], dedup_metrics);
-                mark_template_as_duplicate(templates[2], dedup_metrics);
+                mark_template_as_duplicate(templates[1], dedup_counts);
+                mark_template_as_duplicate(templates[2], dedup_counts);
             } else if s1 >= s0 && s1 >= s2 {
-                mark_template_as_duplicate(templates[0], dedup_metrics);
-                mark_template_as_duplicate(templates[2], dedup_metrics);
+                mark_template_as_duplicate(templates[0], dedup_counts);
+                mark_template_as_duplicate(templates[2], dedup_counts);
             } else {
-                mark_template_as_duplicate(templates[0], dedup_metrics);
-                mark_template_as_duplicate(templates[1], dedup_metrics);
+                mark_template_as_duplicate(templates[0], dedup_counts);
+                mark_template_as_duplicate(templates[1], dedup_counts);
             }
             return;
         }
@@ -756,21 +760,21 @@ fn mark_duplicates_in_family(templates: &mut [&mut Template], dedup_metrics: &mu
     scores.sort_by(|a, b| b.1.cmp(&a.1));
 
     // First template (highest score) is representative
-    dedup_metrics.unique_templates += 1;
+    dedup_counts.unique_templates += 1;
 
     // Mark all others as duplicates
     for (idx, _score) in scores.iter().skip(1) {
-        mark_template_as_duplicate(templates[*idx], dedup_metrics);
-        dedup_metrics.duplicate_templates += 1;
+        mark_template_as_duplicate(templates[*idx], dedup_counts);
+        dedup_counts.duplicate_templates += 1;
     }
 }
 
 /// Marks all reads in a template as duplicates.
-fn mark_template_as_duplicate(template: &mut Template, dedup_metrics: &mut DedupMetrics) {
+fn mark_template_as_duplicate(template: &mut Template, dedup_counts: &mut DedupCounts) {
     for raw in template.records_mut().iter_mut() {
         let flg = RawRecordView::new(raw.as_ref()).flags();
         fgumi_raw_bam::set_flags(raw, flg | DUPLICATE_FLAG);
-        dedup_metrics.duplicate_reads += 1;
+        dedup_counts.duplicate_reads += 1;
     }
 }
 
@@ -788,7 +792,7 @@ fn process_position_group(
     no_umi: bool,
     include_unmapped: bool,
 ) -> io::Result<ProcessedDedupGroup> {
-    let mut dedup_metrics = DedupMetrics::default();
+    let mut dedup_counts = DedupCounts::default();
     let input_record_count = group.records.len() as u64;
 
     // Build templates from raw records (deferred from Group step)
@@ -812,13 +816,13 @@ fn process_position_group(
         .filter(|t| filter_template(t, filter_config, &mut filter_counts))
         .collect();
 
-    dedup_metrics.filter_counts = filter_counts;
+    dedup_counts.filter_counts = filter_counts;
 
     if filtered_templates.is_empty() && passthrough_templates.is_empty() {
         return Ok(ProcessedDedupGroup {
             templates: Vec::new(),
             family_sizes: AHashMap::new(),
-            dedup_metrics,
+            dedup_counts,
             input_record_count,
             distinct_mi_count: 0,
         });
@@ -878,30 +882,30 @@ fn process_position_group(
 
             // Get mutable references to family templates (single collection, not double)
             let mut family_refs: Vec<&mut Template> = templates[start..end].iter_mut().collect();
-            mark_duplicates_in_family(&mut family_refs, &mut dedup_metrics);
+            mark_duplicates_in_family(&mut family_refs, &mut dedup_counts);
         }
     }
 
     // Count reads and check for missing tc tags
     let tc_tag_bytes: [u8; 2] = *TC_TAG.as_ref();
     for template in &templates {
-        dedup_metrics.total_templates += 1;
+        dedup_counts.total_templates += 1;
         for raw in template.records() {
-            dedup_metrics.total_reads += 1;
+            dedup_counts.total_reads += 1;
             let flg = RawRecordView::new(raw.as_ref()).flags();
             let is_secondary = (flg & fgumi_raw_bam::flags::SECONDARY) != 0;
             let is_supplementary = (flg & fgumi_raw_bam::flags::SUPPLEMENTARY) != 0;
 
             if is_secondary {
-                dedup_metrics.secondary_reads += 1;
+                dedup_counts.secondary_reads += 1;
             }
             if is_supplementary {
-                dedup_metrics.supplementary_reads += 1;
+                dedup_counts.supplementary_reads += 1;
             }
             if is_secondary || is_supplementary {
                 let aux = fgumi_raw_bam::aux_data_slice(raw);
                 if fgumi_raw_bam::find_tag_type(aux, tc_tag_bytes).is_none() {
-                    dedup_metrics.missing_tc_tag += 1;
+                    dedup_counts.missing_tc_tag += 1;
                 }
             }
         }
@@ -912,22 +916,22 @@ fn process_position_group(
     // serialize step writes them verbatim (no MI tag, duplicate flag left as in the
     // input). Count them as unique output so the record totals match what is written.
     for template in &passthrough_templates {
-        dedup_metrics.total_templates += 1;
-        dedup_metrics.unique_templates += 1;
+        dedup_counts.total_templates += 1;
+        dedup_counts.unique_templates += 1;
         for raw in template.records() {
-            dedup_metrics.total_reads += 1;
+            dedup_counts.total_reads += 1;
             let flg = RawRecordView::new(raw.as_ref()).flags();
             if (flg & fgumi_raw_bam::flags::SECONDARY) != 0 {
-                dedup_metrics.secondary_reads += 1;
+                dedup_counts.secondary_reads += 1;
             }
             if (flg & fgumi_raw_bam::flags::SUPPLEMENTARY) != 0 {
-                dedup_metrics.supplementary_reads += 1;
+                dedup_counts.supplementary_reads += 1;
             }
         }
     }
     templates.extend(passthrough_templates);
 
-    dedup_metrics.unique_reads = dedup_metrics.total_reads - dedup_metrics.duplicate_reads;
+    dedup_counts.unique_reads = dedup_counts.total_reads - dedup_counts.duplicate_reads;
 
     // Compute the number of distinct numeric molecule IDs assigned in this group.
     // Mirrors `fgumi group`: assigners hand out numeric IDs 0, 1, 2, ... contiguously,
@@ -940,7 +944,7 @@ fn process_position_group(
     Ok(ProcessedDedupGroup {
         templates,
         family_sizes,
-        dedup_metrics,
+        dedup_counts,
         input_record_count,
         distinct_mi_count,
     })
@@ -1245,8 +1249,8 @@ impl Command for MarkDuplicates {
         };
 
         // Shared state for collecting metrics
-        let collected_metrics: Arc<Mutex<CollectedDedupMetrics>> =
-            Arc::new(Mutex::new(CollectedDedupMetrics::default()));
+        let collected_metrics: Arc<Mutex<CollectedDedupCounts>> =
+            Arc::new(Mutex::new(CollectedDedupCounts::default()));
 
         // Clone values needed by closures
         let strategy = effective_strategy;
@@ -1323,7 +1327,7 @@ impl Command for MarkDuplicates {
                 // Collect metrics
                 {
                     let mut agg = collected_metrics_clone.lock();
-                    agg.dedup_metrics.merge(&processed.dedup_metrics);
+                    agg.dedup_counts.merge(&processed.dedup_counts);
                     for (size, count) in &processed.family_sizes {
                         *agg.family_sizes.entry(*size).or_insert(0) += count;
                     }
@@ -1404,12 +1408,12 @@ impl Command for MarkDuplicates {
         let aggregated = Arc::try_unwrap(collected_metrics)
             .expect("bug: metrics Arc still shared after pipeline join")
             .into_inner();
-        let final_metrics = aggregated.dedup_metrics;
+        let final_metrics = aggregated.dedup_counts;
         let final_family_sizes = aggregated.family_sizes;
 
         // Write metrics file
         if let Some(metrics_path) = &self.metrics {
-            write_dedup_metrics(&final_metrics, metrics_path)?;
+            write_dedup_counts(&final_metrics, metrics_path)?;
         }
 
         // Write family size histogram
@@ -1450,7 +1454,7 @@ impl Command for MarkDuplicates {
 // Metrics writing
 //////////////////////////////////////////////////////////////////////////////
 
-fn write_dedup_metrics(metrics: &DedupMetrics, path: &PathBuf) -> Result<()> {
+fn write_dedup_counts(metrics: &DedupCounts, path: &PathBuf) -> Result<()> {
     let output: DedupMetricsOutput = metrics.into();
     DelimFile::default()
         .write_tsv(path, [output])
@@ -1542,22 +1546,22 @@ mod tests {
     #[test]
     fn test_duplicate_rate_calculation() {
         let metrics =
-            DedupMetrics { total_templates: 100, duplicate_templates: 25, ..Default::default() };
+            DedupCounts { total_templates: 100, duplicate_templates: 25, ..Default::default() };
         assert!((metrics.duplicate_rate() - 0.25).abs() < 0.001);
     }
 
     #[test]
     fn test_duplicate_rate_zero_templates() {
-        let metrics = DedupMetrics::default();
+        let metrics = DedupCounts::default();
         assert!((metrics.duplicate_rate() - 0.0).abs() < f64::EPSILON);
     }
 
     #[test]
     fn test_metrics_merge() {
         let mut m1 =
-            DedupMetrics { total_templates: 10, duplicate_templates: 2, ..Default::default() };
+            DedupCounts { total_templates: 10, duplicate_templates: 2, ..Default::default() };
 
-        let m2 = DedupMetrics { total_templates: 20, duplicate_templates: 5, ..Default::default() };
+        let m2 = DedupCounts { total_templates: 20, duplicate_templates: 5, ..Default::default() };
 
         m1.merge(&m2);
         assert_eq!(m1.total_templates, 30);
@@ -1575,7 +1579,7 @@ mod tests {
 
     #[test]
     fn test_mark_duplicates_empty_family() {
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut templates: Vec<&mut Template> = vec![];
         mark_duplicates_in_family(&mut templates, &mut metrics);
         assert_eq!(metrics.unique_templates, 0);
@@ -1584,7 +1588,7 @@ mod tests {
 
     #[test]
     fn test_mark_duplicates_single_template() {
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[30, 30, 30, 30]);
         let mut templates: Vec<&mut Template> = vec![&mut t1];
         mark_duplicates_in_family(&mut templates, &mut metrics);
@@ -1597,7 +1601,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_size_2_first_higher() {
         // Fast path for size 2: first template has higher score
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[15, 15, 15, 15]); // Score: 60
         let mut t2 = create_test_template("q2", &[10, 10, 10, 10]); // Score: 0 (all q < 15)
         let mut templates: Vec<&mut Template> = vec![&mut t1, &mut t2];
@@ -1612,7 +1616,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_size_2_second_higher() {
         // Fast path for size 2: second template has higher score
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[5, 5, 5, 5]); // Score: 0 (all q < 15)
         let mut t2 = create_test_template("q2", &[15, 15, 15, 15]); // Score: 60
         let mut templates: Vec<&mut Template> = vec![&mut t1, &mut t2];
@@ -1627,7 +1631,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_size_3_first_highest() {
         // Fast path for size 3: first template has highest score
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[15, 15, 15, 15]); // Score: 60
         let mut t2 = create_test_template("q2", &[10, 10, 10, 10]); // Score: 0 (all q < 15)
         let mut t3 = create_test_template("q3", &[5, 5, 5, 5]); // Score: 0 (all q < 15)
@@ -1644,7 +1648,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_size_3_second_highest() {
         // Fast path for size 3: second template has highest score
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[5, 5, 5, 5]); // Score: 0 (all q < 15)
         let mut t2 = create_test_template("q2", &[15, 15, 15, 15]); // Score: 60
         let mut t3 = create_test_template("q3", &[10, 10, 10, 10]); // Score: 0 (all q < 15)
@@ -1661,7 +1665,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_size_3_third_highest() {
         // Fast path for size 3: third template has highest score
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[5, 5, 5, 5]); // Score: 0 (all q < 15)
         let mut t2 = create_test_template("q2", &[10, 10, 10, 10]); // Score: 0 (all q < 15)
         let mut t3 = create_test_template("q3", &[15, 15, 15, 15]); // Score: 60
@@ -1678,7 +1682,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_size_4_general_case() {
         // General case for size 4+: uses Vec and sort
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[5, 5, 5, 5]); // Score: 0 (all q < 15)
         let mut t2 = create_test_template("q2", &[15, 15, 15, 15]); // Score: 60 (highest)
         let mut t3 = create_test_template("q3", &[10, 10, 10, 10]); // Score: 0 (all q < 15)
@@ -1697,7 +1701,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_counts_duplicate_reads() {
         // Verify duplicate_reads metric is incremented for each read in duplicate templates
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[15, 15, 15, 15]); // Score: 60 (1 read)
         let mut t2 = create_test_template("q2", &[5, 5, 5, 5]); // Score: 0 (all q < 15; 1 read)
         let mut templates: Vec<&mut Template> = vec![&mut t1, &mut t2];
@@ -1713,7 +1717,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_tie_breaking_size_2() {
         // When scores are equal, first template should be kept (deterministic)
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[10, 10, 10, 10]); // Score: 0 (all < 15)
         let mut t2 = create_test_template("q2", &[10, 10, 10, 10]); // Score: 0 (tie)
         let mut templates: Vec<&mut Template> = vec![&mut t1, &mut t2];
@@ -1729,7 +1733,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_tie_breaking_size_3_all_equal() {
         // All three have equal scores - first template should be kept
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[10, 10, 10, 10]); // Score: 0 (all < 15)
         let mut t2 = create_test_template("q2", &[10, 10, 10, 10]); // Score: 0
         let mut t3 = create_test_template("q3", &[10, 10, 10, 10]); // Score: 0
@@ -1747,7 +1751,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_tie_breaking_size_3_second_and_third_tie() {
         // First is lower, second and third tie - second should win
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[10, 10, 10, 10]); // Score: 0 (all < 15)
         let mut t2 = create_test_template("q2", &[20, 20, 20, 20]); // Score: 80
         let mut t3 = create_test_template("q3", &[20, 20, 20, 20]); // Score: 80 (tie with t2)
@@ -1765,7 +1769,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_tie_breaking_size_4_all_equal() {
         // All four have equal scores - first template should be kept
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[10, 10, 10, 10]); // Score: 0 (all < 15)
         let mut t2 = create_test_template("q2", &[10, 10, 10, 10]); // Score: 0
         let mut t3 = create_test_template("q3", &[10, 10, 10, 10]); // Score: 0
@@ -1785,7 +1789,7 @@ mod tests {
     #[test]
     fn test_mark_duplicates_tie_breaking_size_4_partial_tie() {
         // Third and fourth tie for highest - third should win
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         let mut t1 = create_test_template("q1", &[10, 10, 10, 10]); // Score: 0 (all < 15)
         let mut t2 = create_test_template("q2", &[16, 16, 16, 16]); // Score: 64
         let mut t3 = create_test_template("q3", &[20, 20, 20, 20]); // Score: 80
@@ -2416,7 +2420,7 @@ mod tests {
         for template in &mut templates {
             by_family.entry(template.mi.to_vec_index()).or_default().push(template);
         }
-        let mut metrics = DedupMetrics::default();
+        let mut metrics = DedupCounts::default();
         for (_mi, mut family) in by_family {
             mark_duplicates_in_family(&mut family, &mut metrics);
         }
@@ -2683,12 +2687,12 @@ mod tests {
     }
 
     // ========================================================================
-    // DedupMetrics tests
+    // DedupCounts tests
     // ========================================================================
 
     #[test]
     fn test_metrics_merge_all_fields() {
-        let mut m1 = DedupMetrics {
+        let mut m1 = DedupCounts {
             total_templates: 10,
             duplicate_templates: 2,
             unique_templates: 8,
@@ -2701,7 +2705,7 @@ mod tests {
             ..Default::default()
         };
 
-        let m2 = DedupMetrics {
+        let m2 = DedupCounts {
             total_templates: 5,
             duplicate_templates: 1,
             unique_templates: 4,
@@ -2729,13 +2733,13 @@ mod tests {
     #[test]
     fn test_duplicate_rate_all_duplicates() {
         let metrics =
-            DedupMetrics { total_templates: 50, duplicate_templates: 50, ..Default::default() };
+            DedupCounts { total_templates: 50, duplicate_templates: 50, ..Default::default() };
         assert!((metrics.duplicate_rate() - 1.0).abs() < f64::EPSILON);
     }
 
     #[test]
     fn test_metrics_default() {
-        let metrics = DedupMetrics::default();
+        let metrics = DedupCounts::default();
         assert_eq!(metrics.total_templates, 0);
         assert_eq!(metrics.duplicate_templates, 0);
         assert_eq!(metrics.unique_templates, 0);
@@ -2748,8 +2752,8 @@ mod tests {
     }
 
     #[test]
-    fn test_dedup_metrics_output_from() {
-        let metrics = DedupMetrics {
+    fn test_dedup_counts_output_from() {
+        let metrics = DedupCounts {
             total_templates: 100,
             duplicate_templates: 25,
             unique_templates: 75,
@@ -2780,8 +2784,8 @@ mod tests {
     /// rate is written as `1`, not serde's raw `1.0` — consistent with the other
     /// fgumi metric files.
     #[test]
-    fn test_dedup_metrics_duplicate_rate_uses_float_formatter() -> Result<()> {
-        let metrics = DedupMetrics {
+    fn test_dedup_counts_duplicate_rate_uses_float_formatter() -> Result<()> {
+        let metrics = DedupCounts {
             total_templates: 2,
             duplicate_templates: 2,
             unique_templates: 0,
@@ -2789,7 +2793,7 @@ mod tests {
         };
         let dir = tempfile::tempdir()?;
         let path = dir.path().join("dedup.metrics.txt");
-        write_dedup_metrics(&metrics, &path)?;
+        write_dedup_counts(&metrics, &path)?;
 
         let text = std::fs::read_to_string(&path)?;
         let data_row = text.lines().nth(1).expect("metrics data row");
@@ -3190,7 +3194,7 @@ mod tests {
         let batch = ProcessedDedupGroup {
             templates,
             family_sizes: AHashMap::new(),
-            dedup_metrics: DedupMetrics::default(),
+            dedup_counts: DedupCounts::default(),
             input_record_count: 1,
             distinct_mi_count: 0,
         };

From f5b3c8e86409c16e7693af58f841d3cce87e9fe0 Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Tue, 11 Aug 2026 23:30:29 -0700
Subject: [PATCH 5/8] feat(metrics): add DeduplicationMetrics with per-reason
 filter columns

Move dedup's metrics file schema into the fgumi-metrics crate and give it a
column per template filter reason, plus passthrough_templates for the
--include-unmapped templates that bypass the filter and so appeared in no
tally at all.

Living in this crate also means the metrics reference page is generated by
cargo xtask like every other metric type, rather than dedup being the one
schema with no documentation.

Nothing writes these columns yet; wiring the counts into the output file is
the next change.
---
 crates/fgumi-metrics/src/dedup.rs | 164 ++++++++++++++++++++++++++++++
 crates/fgumi-metrics/src/lib.rs   |   2 +
 src/lib/commands/dedup.rs         |   8 ++
 3 files changed, 174 insertions(+)
 create mode 100644 crates/fgumi-metrics/src/dedup.rs

diff --git a/crates/fgumi-metrics/src/dedup.rs b/crates/fgumi-metrics/src/dedup.rs
new file mode 100644
index 000000000..42faf266d
--- /dev/null
+++ b/crates/fgumi-metrics/src/dedup.rs
@@ -0,0 +1,164 @@
+//! Metrics for the `dedup` command.
+
+use serde::{Deserialize, Serialize};
+
+use crate::Metric;
+
+/// Metrics written by `fgumi dedup --metrics`.
+///
+/// Three sections, in column order:
+///
+/// 1. **Filtering** — `filtered_templates` through `passthrough_templates`.
+///    `dedup` is a read *filter* as well as a duplicate marker: templates failing
+///    the pre-grouping filter are dropped and never reach the output. The
+///    `filtered_*` columns give the count per reason in **template** units — note
+///    that `group`'s fgbio-shaped `.grouping_metrics.txt` counts primary
+///    *records*, so the two files' discard counts are not comparable.
+/// 2. **Deduplication** — `total_templates` through `duplicate_reads`, covering
+///    only what survived filtering.
+/// 3. **Diagnostics** — `secondary_reads`, `supplementary_reads`,
+///    `missing_tc_tag`.
+///
+/// Templates read from the input are `filtered_templates + total_templates`; that
+/// sum is not emitted as its own column because it is derivable, matching
+/// [`crate::group::UmiGroupingMetrics`]' treatment of its derivable fields.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct DeduplicationMetrics {
+    /// Templates dropped by the filter, for any reason.
+    pub filtered_templates: u64,
+    /// Dropped because a record was shorter than the minimum BAM record length
+    /// (corrupt input).
+    pub filtered_malformed_record: u64,
+    /// Dropped because the template had neither a primary R1 nor a primary R2.
+    pub filtered_no_primary_reads: u64,
+    /// Dropped because no primary read was mapped. Always zero with
+    /// `--include-unmapped`, which routes these to `passthrough_templates`.
+    pub filtered_unmapped: u64,
+    /// Dropped because a primary read carried the QC-fail flag.
+    pub filtered_not_passing_filter: u64,
+    /// Dropped because a mapped primary read's mapping quality was below
+    /// `--min-map-q`.
+    pub filtered_low_mapping_quality: u64,
+    /// Dropped because a primary read's `MQ` tag was below `--min-map-q`.
+    pub filtered_low_mate_mapping_quality: u64,
+    /// Dropped because a primary read had no UMI tag.
+    pub filtered_missing_umi: u64,
+    /// Dropped because the UMI contained an `N` base.
+    pub filtered_ns_in_umi: u64,
+    /// Dropped because the UMI was shorter than `--min-umi-length`.
+    pub filtered_umi_too_short: u64,
+    /// Templates emitted untouched by `--include-unmapped`: never filtered, never
+    /// marked, never MI-tagged. Counted as unique in the columns below.
+    pub passthrough_templates: u64,
+    /// Templates written to the output (accepted by the filter, plus
+    /// pass-throughs) — not the number read from the input.
+    pub total_templates: u64,
+    /// Templates kept as the representative of their UMI family.
+    pub unique_templates: u64,
+    /// Templates marked as duplicates.
+    pub duplicate_templates: u64,
+    /// `duplicate_templates / total_templates`, or 0 when nothing was output.
+    #[serde(with = "crate::float")]
+    pub duplicate_rate: f64,
+    /// Reads written to the output.
+    pub total_reads: u64,
+    /// Reads not marked as duplicates.
+    pub unique_reads: u64,
+    /// Reads marked as duplicates.
+    pub duplicate_reads: u64,
+    /// Secondary alignments seen in the output.
+    pub secondary_reads: u64,
+    /// Supplementary alignments seen in the output.
+    pub supplementary_reads: u64,
+    /// Secondary/supplementary reads lacking the `tc` tag that `fgumi zipper`
+    /// adds and template-coordinate ordering requires.
+    pub missing_tc_tag: u64,
+}
+
+impl DeduplicationMetrics {
+    /// Creates a metrics struct with all counts initialized to zero.
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
+impl Metric for DeduplicationMetrics {
+    fn metric_name() -> &'static str {
+        "deduplication"
+    }
+}
+
+impl crate::ProcessingMetrics for DeduplicationMetrics {
+    fn total_input(&self) -> u64 {
+        self.filtered_templates + self.total_templates
+    }
+
+    fn total_output(&self) -> u64 {
+        self.total_templates
+    }
+
+    fn total_filtered(&self) -> u64 {
+        self.filtered_templates
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::template_filter::TemplateFilterReason;
+    use fgoxide::io::DelimFile;
+    use tempfile::NamedTempFile;
+
+    fn header_of(metrics: DeduplicationMetrics) -> String {
+        let file = NamedTempFile::new().expect("temp file");
+        DelimFile::default().write_tsv(file.path(), [metrics]).expect("write");
+        std::fs::read_to_string(file.path())
+            .expect("read")
+            .lines()
+            .next()
+            .expect("header")
+            .to_string()
+    }
+
+    /// Every filter reason must have a column. This is the test that would have
+    /// caught fgumi#739: the counts existed and were merged correctly, then were
+    /// dropped at the serialization boundary because no column held them.
+    #[test]
+    fn every_filter_reason_has_a_column() {
+        let header = header_of(DeduplicationMetrics::default());
+        let columns: Vec<&str> = header.split('\t').collect();
+        for reason in TemplateFilterReason::ALL {
+            let column = format!("filtered_{}", reason.column_suffix());
+            assert!(columns.contains(&column.as_str()), "missing {column} for {reason:?}");
+        }
+    }
+
+    /// Column order is the file's contract; pin it whole so a field reorder is a
+    /// deliberate, reviewed change rather than a silent schema break.
+    #[test]
+    fn serializes_expected_columns_in_order() {
+        assert_eq!(
+            header_of(DeduplicationMetrics::default()),
+            "filtered_templates\tfiltered_malformed_record\tfiltered_no_primary_reads\t\
+             filtered_unmapped\tfiltered_not_passing_filter\tfiltered_low_mapping_quality\t\
+             filtered_low_mate_mapping_quality\tfiltered_missing_umi\tfiltered_ns_in_umi\t\
+             filtered_umi_too_short\tpassthrough_templates\ttotal_templates\tunique_templates\t\
+             duplicate_templates\tduplicate_rate\ttotal_reads\tunique_reads\tduplicate_reads\t\
+             secondary_reads\tsupplementary_reads\tmissing_tc_tag"
+        );
+    }
+
+    #[test]
+    fn processing_metrics_reconciles_input_from_the_columns() {
+        use crate::ProcessingMetrics;
+        let metrics = DeduplicationMetrics {
+            filtered_templates: 10,
+            total_templates: 90,
+            ..DeduplicationMetrics::default()
+        };
+        assert_eq!(metrics.total_input(), 100);
+        assert_eq!(metrics.total_output(), 90);
+        assert_eq!(metrics.total_filtered(), 10);
+    }
+}
diff --git a/crates/fgumi-metrics/src/lib.rs b/crates/fgumi-metrics/src/lib.rs
index 9c2b134ea..aaeace398 100644
--- a/crates/fgumi-metrics/src/lib.rs
+++ b/crates/fgumi-metrics/src/lib.rs
@@ -12,6 +12,7 @@
 pub mod clip;
 pub mod consensus;
 pub mod correct;
+pub mod dedup;
 pub mod duplex;
 pub mod float;
 pub mod group;
@@ -99,6 +100,7 @@ pub trait ProcessingMetrics {
 pub use clip::{ClipCounts, ClippingMetrics, ClippingMetricsCollection, ReadType};
 pub use consensus::{ConsensusCallerKind, ConsensusKvMetric, ConsensusMetrics};
 pub use correct::UmiCorrectionMetrics;
+pub use dedup::DeduplicationMetrics;
 pub use duplex::{
     DuplexFamilySizeMetric, DuplexMetricsCollector, DuplexUmiMetric, DuplexYieldMetric,
     FamilySizeMetric,
diff --git a/src/lib/commands/dedup.rs b/src/lib/commands/dedup.rs
index 97b7644da..4776551d9 100644
--- a/src/lib/commands/dedup.rs
+++ b/src/lib/commands/dedup.rs
@@ -92,6 +92,9 @@ pub struct DedupCounts {
     pub missing_tc_tag: u64,
     /// Per-reason counts from the template filter.
     pub filter_counts: TemplateFilterCounts,
+    /// Templates emitted untouched by `--include-unmapped`, which bypass the
+    /// filter entirely and so appear in no `filter_counts` bucket.
+    pub passthrough_templates: u64,
 }
 
 impl DedupCounts {
@@ -107,6 +110,7 @@ impl DedupCounts {
         self.supplementary_reads += other.supplementary_reads;
         self.missing_tc_tag += other.missing_tc_tag;
         self.filter_counts.merge(&other.filter_counts);
+        self.passthrough_templates += other.passthrough_templates;
     }
 
     /// Calculate duplicate rate.
@@ -916,6 +920,10 @@ fn process_position_group(
     // serialize step writes them verbatim (no MI tag, duplicate flag left as in the
     // input). Count them as unique output so the record totals match what is written.
     for template in &passthrough_templates {
+        // Counted separately from `filter_counts`: these templates were split off
+        // before the filter ran, so they appear in no rejection bucket and in no
+        // accepted count. Without this they would be invisible in the accounting.
+        dedup_counts.passthrough_templates += 1;
         dedup_counts.total_templates += 1;
         dedup_counts.unique_templates += 1;
         for raw in template.records() {

From c09a4ffc10006e538c6360ff1e0631814015598e Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Tue, 11 Aug 2026 23:42:47 -0700
Subject: [PATCH 6/8] fix(dedup)!: report filtered template counts in the
 metrics file

The template filter's per-reason counts were collected, merged across
workers, and then dropped: DedupMetricsOutput had no field for them. A run
that filtered out every input template reported a row of zeros with no
indication anything had been dropped, and logged only 'Deduplication
complete: 0 templates'.

Serialize them, log a per-reason summary so --metrics is not the only
channel, and assert the reconciliation filtered_templates + total_templates
== templates read, so a future column cannot go missing the same way.

BREAKING CHANGE: dedup --metrics gains eleven columns. Consumers parsing it
positionally must be updated; consumers keyed on column names are
unaffected.

Closes #739
---
 src/lib/commands/dedup.rs               | 237 ++++++++++++++++--------
 src/lib/metrics/mod.rs                  |   2 +
 tests/integration/test_dedup_command.rs | 135 ++++++++++++++
 3 files changed, 292 insertions(+), 82 deletions(-)

diff --git a/src/lib/commands/dedup.rs b/src/lib/commands/dedup.rs
index 4776551d9..1d664d6d1 100644
--- a/src/lib/commands/dedup.rs
+++ b/src/lib/commands/dedup.rs
@@ -25,6 +25,7 @@ use std::sync::atomic::{AtomicU64, Ordering};
 use crate::assigner::{PairedUmiAssigner, Strategy, UmiAssigner};
 use crate::grouper::{RawPositionGroup, RecordPositionGrouper, build_templates_from_records};
 use crate::logging::OperationTimer;
+use crate::metrics::DeduplicationMetrics;
 use crate::metrics::group::FamilySizeMetrics;
 use crate::metrics::{TemplateFilterCounts, TemplateFilterReason};
 use crate::read_info::LibraryIndex;
@@ -47,7 +48,6 @@ use log::info;
 use noodles::sam::Header;
 use noodles::sam::alignment::record::data::field::Tag;
 use parking_lot::Mutex;
-use serde::{Deserialize, Serialize};
 
 use crate::commands::command::Command;
 use crate::commands::common::{
@@ -56,7 +56,7 @@ use crate::commands::common::{
 };
 use crate::sam::TC_TAG;
 use fgumi_raw_bam;
-use fgumi_raw_bam::RawRecordView;
+use fgumi_raw_bam::{RawRecord, RawRecordView};
 
 /// Duplicate flag bit in SAM flags (0x400)
 const DUPLICATE_FLAG: u16 = 0x400;
@@ -124,37 +124,33 @@ impl DedupCounts {
     }
 }
 
-/// Serializable version of `DedupCounts` for file output.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-struct DedupMetricsOutput {
-    total_templates: u64,
-    unique_templates: u64,
-    duplicate_templates: u64,
-    // DXM3-04: format the one fraction column like fgbio's DecimalFormat, matching
-    // the float serialization #504 wired onto the fgumi-metrics-crate structs.
-    #[serde(with = "fgumi_metrics::float")]
-    duplicate_rate: f64,
-    total_reads: u64,
-    unique_reads: u64,
-    duplicate_reads: u64,
-    secondary_reads: u64,
-    supplementary_reads: u64,
-    missing_tc_tag: u64,
-}
-
-impl From<&DedupCounts> for DedupMetricsOutput {
-    fn from(m: &DedupCounts) -> Self {
+impl From<&DedupCounts> for DeduplicationMetrics {
+    fn from(counts: &DedupCounts) -> Self {
+        use TemplateFilterReason as Reason;
+        let filter = &counts.filter_counts;
         Self {
-            total_templates: m.total_templates,
-            unique_templates: m.unique_templates,
-            duplicate_templates: m.duplicate_templates,
-            duplicate_rate: m.duplicate_rate(),
-            total_reads: m.total_reads,
-            unique_reads: m.unique_reads,
-            duplicate_reads: m.duplicate_reads,
-            secondary_reads: m.secondary_reads,
-            supplementary_reads: m.supplementary_reads,
-            missing_tc_tag: m.missing_tc_tag,
+            filtered_templates: filter.total_rejected_templates(),
+            filtered_malformed_record: filter.rejected_templates(Reason::MalformedRecord),
+            filtered_no_primary_reads: filter.rejected_templates(Reason::NoPrimaryReads),
+            filtered_unmapped: filter.rejected_templates(Reason::Unmapped),
+            filtered_not_passing_filter: filter.rejected_templates(Reason::NotPassingFilter),
+            filtered_low_mapping_quality: filter.rejected_templates(Reason::LowMappingQuality),
+            filtered_low_mate_mapping_quality: filter
+                .rejected_templates(Reason::LowMateMappingQuality),
+            filtered_missing_umi: filter.rejected_templates(Reason::MissingUmi),
+            filtered_ns_in_umi: filter.rejected_templates(Reason::NsInUmi),
+            filtered_umi_too_short: filter.rejected_templates(Reason::UmiTooShort),
+            passthrough_templates: counts.passthrough_templates,
+            total_templates: counts.total_templates,
+            unique_templates: counts.unique_templates,
+            duplicate_templates: counts.duplicate_templates,
+            duplicate_rate: counts.duplicate_rate(),
+            total_reads: counts.total_reads,
+            unique_reads: counts.unique_reads,
+            duplicate_reads: counts.duplicate_reads,
+            secondary_reads: counts.secondary_reads,
+            supplementary_reads: counts.supplementary_reads,
+            missing_tc_tag: counts.missing_tc_tag,
         }
     }
 }
@@ -493,6 +489,34 @@ fn template_is_unmapped_passthrough(template: &Template) -> bool {
 // UMI assignment (adapted from group command)
 //////////////////////////////////////////////////////////////////////////////
 
+/// Count one output record into `counts`: the read itself, whether it is secondary
+/// and/or supplementary, and whether a non-primary record is missing its `tc` tag.
+///
+/// Shared by both counting loops in `process_position_group` — the filtered templates
+/// and the `--include-unmapped` pass-throughs — so the two cannot drift on which
+/// records are checked. A missing `tc` on a non-primary record is a hard failure once
+/// the per-worker counts are merged, so a loop that counts non-primary reads without
+/// checking their `tc` tag is a hole in that check, not just an accounting gap.
+fn count_record(raw: &RawRecord, tc_tag_bytes: [u8; 2], counts: &mut DedupCounts) {
+    counts.total_reads += 1;
+    let flg = RawRecordView::new(raw.as_ref()).flags();
+    let is_secondary = (flg & fgumi_raw_bam::flags::SECONDARY) != 0;
+    let is_supplementary = (flg & fgumi_raw_bam::flags::SUPPLEMENTARY) != 0;
+
+    if is_secondary {
+        counts.secondary_reads += 1;
+    }
+    if is_supplementary {
+        counts.supplementary_reads += 1;
+    }
+    if is_secondary || is_supplementary {
+        let aux = fgumi_raw_bam::aux_data_slice(raw);
+        if fgumi_raw_bam::find_tag_type(aux, tc_tag_bytes).is_none() {
+            counts.missing_tc_tag += 1;
+        }
+    }
+}
+
 /// Extract UMI for a read, handling paired UMI strategies.
 fn umi_for_read(umi: &str, is_r1_earlier: bool, assigner: &dyn UmiAssigner) -> Result<String> {
     if assigner.split_templates_by_pair_orientation() {
@@ -895,23 +919,7 @@ fn process_position_group(
     for template in &templates {
         dedup_counts.total_templates += 1;
         for raw in template.records() {
-            dedup_counts.total_reads += 1;
-            let flg = RawRecordView::new(raw.as_ref()).flags();
-            let is_secondary = (flg & fgumi_raw_bam::flags::SECONDARY) != 0;
-            let is_supplementary = (flg & fgumi_raw_bam::flags::SUPPLEMENTARY) != 0;
-
-            if is_secondary {
-                dedup_counts.secondary_reads += 1;
-            }
-            if is_supplementary {
-                dedup_counts.supplementary_reads += 1;
-            }
-            if is_secondary || is_supplementary {
-                let aux = fgumi_raw_bam::aux_data_slice(raw);
-                if fgumi_raw_bam::find_tag_type(aux, tc_tag_bytes).is_none() {
-                    dedup_counts.missing_tc_tag += 1;
-                }
-            }
+            count_record(raw, tc_tag_bytes, &mut dedup_counts);
         }
     }
 
@@ -927,14 +935,12 @@ fn process_position_group(
         dedup_counts.total_templates += 1;
         dedup_counts.unique_templates += 1;
         for raw in template.records() {
-            dedup_counts.total_reads += 1;
-            let flg = RawRecordView::new(raw.as_ref()).flags();
-            if (flg & fgumi_raw_bam::flags::SECONDARY) != 0 {
-                dedup_counts.secondary_reads += 1;
-            }
-            if (flg & fgumi_raw_bam::flags::SUPPLEMENTARY) != 0 {
-                dedup_counts.supplementary_reads += 1;
-            }
+            // Same accounting as the filtered templates above, `tc` check included.
+            // `template_is_unmapped_passthrough` only inspects the primary r1/r2, so a
+            // template routed here can still carry secondary/supplementary records; if
+            // they were counted but not checked, --include-unmapped would be a way to
+            // slip a `tc`-less non-primary read past the hard failure below.
+            count_record(raw, tc_tag_bytes, &mut dedup_counts);
         }
     }
     templates.extend(passthrough_templates);
@@ -1421,7 +1427,7 @@ impl Command for MarkDuplicates {
 
         // Write metrics file
         if let Some(metrics_path) = &self.metrics {
-            write_dedup_counts(&final_metrics, metrics_path)?;
+            write_dedup_metrics(&final_metrics, metrics_path)?;
         }
 
         // Write family size histogram
@@ -1452,6 +1458,22 @@ impl Command for MarkDuplicates {
             );
         }
 
+        // --metrics is optional, so it must not be the only channel reporting
+        // dropped templates: a run that filters everything otherwise logs a bare
+        // "0 templates" and is indistinguishable from empty input. Reasons are
+        // named by their column suffix so the log points at the metrics column.
+        let filtered = final_metrics.filter_counts.total_rejected_templates();
+        if filtered > 0 {
+            let reasons: Vec<String> = TemplateFilterReason::ALL
+                .into_iter()
+                .filter_map(|reason| {
+                    let count = final_metrics.filter_counts.rejected_templates(reason);
+                    (count > 0).then(|| format!("{count} {}", reason.column_suffix()))
+                })
+                .collect();
+            info!("Filtered out {filtered} templates before marking: {}", reasons.join(", "));
+        }
+
         timer.log_completion(final_metrics.total_reads);
 
         Ok(())
@@ -1462,8 +1484,8 @@ impl Command for MarkDuplicates {
 // Metrics writing
 //////////////////////////////////////////////////////////////////////////////
 
-fn write_dedup_counts(metrics: &DedupCounts, path: &PathBuf) -> Result<()> {
-    let output: DedupMetricsOutput = metrics.into();
+fn write_dedup_metrics(counts: &DedupCounts, path: &PathBuf) -> Result<()> {
+    let output: DeduplicationMetrics = counts.into();
     DelimFile::default()
         .write_tsv(path, [output])
         .with_context(|| format!("Failed to write dedup metrics: {}", path.display()))?;
@@ -2759,9 +2781,20 @@ mod tests {
         assert_eq!(metrics.missing_tc_tag, 0);
     }
 
+    /// The point of fgumi#739: every count the filter collects must survive the
+    /// trip to the output struct. Distinct per-reason counts so a mis-wired field
+    /// cannot pass by accident.
     #[test]
-    fn test_dedup_counts_output_from() {
-        let metrics = DedupCounts {
+    fn dedup_metrics_output_carries_every_filter_reason() {
+        let mut filter_counts = TemplateFilterCounts::new();
+        for (offset, reason) in TemplateFilterReason::ALL.into_iter().enumerate() {
+            for _ in 0..=offset {
+                filter_counts.record_rejected(reason, 2);
+            }
+        }
+        filter_counts.record_accepted(2);
+
+        let counts = DedupCounts {
             total_templates: 100,
             duplicate_templates: 25,
             unique_templates: 75,
@@ -2771,47 +2804,87 @@ mod tests {
             secondary_reads: 10,
             supplementary_reads: 5,
             missing_tc_tag: 2,
-            ..Default::default()
+            passthrough_templates: 3,
+            filter_counts,
         };
-        let output = DedupMetricsOutput::from(&metrics);
-
+        let output = DeduplicationMetrics::from(&counts);
+
+        assert_eq!(output.filtered_malformed_record, 1);
+        assert_eq!(output.filtered_no_primary_reads, 2);
+        assert_eq!(output.filtered_unmapped, 3);
+        assert_eq!(output.filtered_not_passing_filter, 4);
+        assert_eq!(output.filtered_low_mapping_quality, 5);
+        assert_eq!(output.filtered_low_mate_mapping_quality, 6);
+        assert_eq!(output.filtered_missing_umi, 7);
+        assert_eq!(output.filtered_ns_in_umi, 8);
+        assert_eq!(output.filtered_umi_too_short, 9);
+        assert_eq!(output.filtered_templates, 45);
+        assert_eq!(output.passthrough_templates, 3);
         assert_eq!(output.total_templates, 100);
-        assert_eq!(output.duplicate_templates, 25);
         assert_eq!(output.unique_templates, 75);
+        assert_eq!(output.duplicate_templates, 25);
         assert!((output.duplicate_rate - 0.25).abs() < 0.001);
         assert_eq!(output.total_reads, 200);
-        assert_eq!(output.duplicate_reads, 50);
         assert_eq!(output.unique_reads, 150);
+        assert_eq!(output.duplicate_reads, 50);
         assert_eq!(output.secondary_reads, 10);
         assert_eq!(output.supplementary_reads, 5);
         assert_eq!(output.missing_tc_tag, 2);
     }
 
-    /// DXM3-04: `duplicate_rate` serializes through the fgbio-style float
-    /// formatter (#504's now-public `fgumi_metrics::float`), so a whole-number
-    /// rate is written as `1`, not serde's raw `1.0` — consistent with the other
-    /// fgumi metric files.
+    /// Nothing may vanish silently: everything read is either filtered or written.
+    #[rstest]
+    #[case::nothing_filtered(0, 10, 0)]
+    #[case::everything_filtered(7, 0, 0)]
+    #[case::mixed(3, 5, 2)]
+    fn dedup_metrics_output_reconciles(
+        #[case] rejected: u64,
+        #[case] accepted: u64,
+        #[case] passthrough: u64,
+    ) {
+        let mut filter_counts = TemplateFilterCounts::new();
+        for _ in 0..rejected {
+            filter_counts.record_rejected(TemplateFilterReason::NsInUmi, 2);
+        }
+        for _ in 0..accepted {
+            filter_counts.record_accepted(2);
+        }
+
+        let counts = DedupCounts {
+            total_templates: accepted + passthrough,
+            passthrough_templates: passthrough,
+            filter_counts,
+            ..DedupCounts::default()
+        };
+        let output = DeduplicationMetrics::from(&counts);
+
+        assert_eq!(
+            output.filtered_templates + output.total_templates,
+            rejected + accepted + passthrough
+        );
+    }
+
+    /// `duplicate_rate` serializes through the fgbio-style float formatter, so a
+    /// whole-number rate is written as `1`, not serde's raw `1.0`. Located by
+    /// column name rather than position, so adding a column cannot silently
+    /// invalidate this.
     #[test]
     fn test_dedup_counts_duplicate_rate_uses_float_formatter() -> Result<()> {
-        let metrics = DedupCounts {
+        let counts = DedupCounts {
             total_templates: 2,
             duplicate_templates: 2,
             unique_templates: 0,
-            ..Default::default()
+            ..DedupCounts::default()
         };
         let dir = tempfile::tempdir()?;
         let path = dir.path().join("dedup.metrics.txt");
-        write_dedup_counts(&metrics, &path)?;
+        write_dedup_metrics(&counts, &path)?;
 
         let text = std::fs::read_to_string(&path)?;
-        let data_row = text.lines().nth(1).expect("metrics data row");
-        let columns: Vec<&str> = data_row.split('\t').collect();
-        // Field order: total, unique, duplicate templates, then duplicate_rate.
-        assert_eq!(
-            columns.get(3).copied(),
-            Some("1"),
-            "duplicate_rate must format as `1`, not `1.0`; row: {data_row:?}"
-        );
+        let header: Vec<&str> = text.lines().next().expect("header").split('\t').collect();
+        let row: Vec<&str> = text.lines().nth(1).expect("data row").split('\t').collect();
+        let index = header.iter().position(|&c| c == "duplicate_rate").expect("column");
+        assert_eq!(row.get(index).copied(), Some("1"));
         Ok(())
     }
 
diff --git a/src/lib/metrics/mod.rs b/src/lib/metrics/mod.rs
index 4091af4d6..b7dedd63b 100644
--- a/src/lib/metrics/mod.rs
+++ b/src/lib/metrics/mod.rs
@@ -20,6 +20,7 @@ pub use fgumi_metrics::{FLOAT_PRECISION, Metric, ProcessingMetrics, format_float
 pub use fgumi_metrics::clip;
 pub use fgumi_metrics::consensus;
 pub use fgumi_metrics::correct;
+pub use fgumi_metrics::dedup;
 pub use fgumi_metrics::duplex;
 pub use fgumi_metrics::group;
 pub use fgumi_metrics::shared;
@@ -31,6 +32,7 @@ pub use fgumi_metrics::writer;
 pub use clip::{ClippingMetrics, ClippingMetricsCollection, ReadType};
 pub use consensus::{ConsensusKvMetric, ConsensusMetrics};
 pub use correct::UmiCorrectionMetrics;
+pub use dedup::DeduplicationMetrics;
 pub use duplex::{
     DuplexFamilySizeMetric, DuplexMetricsCollector, DuplexUmiMetric, DuplexYieldMetric,
     FamilySizeMetric,
diff --git a/tests/integration/test_dedup_command.rs b/tests/integration/test_dedup_command.rs
index 3d9bdb692..11c6e067f 100644
--- a/tests/integration/test_dedup_command.rs
+++ b/tests/integration/test_dedup_command.rs
@@ -8,8 +8,10 @@
 use clap::Parser;
 use rstest::rstest;
 
+use fgoxide::io::DelimFile;
 use fgumi_lib::commands::command::Command;
 use fgumi_lib::commands::dedup::MarkDuplicates;
+use fgumi_lib::metrics::DeduplicationMetrics;
 use fgumi_lib::sam::SamTag;
 use fgumi_raw_bam::{RawRecord, SamBuilder, flags};
 use noodles::bam;
@@ -149,6 +151,75 @@ fn test_dedup_command_basic() {
     assert_eq!(count, 10, "All reads should be in output (marked, not removed)");
 }
 
+/// End-to-end guard for fgumi#739. With a mapping-quality threshold no read can
+/// meet, every template is dropped -- and the metrics file must say so, rather
+/// than reporting a row of zeros with no indication anything was discarded.
+///
+/// This is the regression test for the reported bug: before the fix, the counts
+/// were collected and merged correctly, then dropped at the serialization
+/// boundary because the output struct had no field to hold them.
+///
+/// The same input is run twice -- once unfiltered, once with the threshold -- and
+/// the templates that reach the output in the first run must equal the templates
+/// reported as filtered in the second. Asserting the two against each other,
+/// rather than against a hard-coded count, keeps the test about the accounting
+/// invariant instead of about how this fixture happens to group into templates.
+#[test]
+fn test_dedup_metrics_report_filtered_templates() {
+    fn run_dedup(temp_dir: &TempDir, label: &str, min_map_q: &str) -> DeduplicationMetrics {
+        let input_bam = temp_dir.path().join(format!("{label}.in.bam"));
+        let output_bam = temp_dir.path().join(format!("{label}.out.bam"));
+        let metrics_path = temp_dir.path().join(format!("{label}.metrics.txt"));
+
+        create_sorted_bam(&input_bam, create_duplicate_group("dup1", "ACGTACGT", 3, 100));
+
+        let cmd = MarkDuplicates::try_parse_from([
+            "dedup",
+            "--input",
+            input_bam.to_str().unwrap(),
+            "--output",
+            output_bam.to_str().unwrap(),
+            "--strategy",
+            "identity",
+            "--min-map-q",
+            min_map_q,
+            "--metrics",
+            metrics_path.to_str().unwrap(),
+            "--compression-level",
+            "1",
+        ])
+        .expect("failed to parse dedup args");
+        cmd.execute("fgumi dedup").expect("Dedup command failed");
+
+        let rows: Vec<DeduplicationMetrics> =
+            DelimFile::default().read_tsv(&metrics_path).expect("failed to read dedup metrics");
+        rows.into_iter().next().expect("one metrics row")
+    }
+
+    let temp_dir = TempDir::new().unwrap();
+
+    // Baseline: nothing is filtered, so every template reaches the output.
+    let kept = run_dedup(&temp_dir, "kept", "0");
+    assert_eq!(kept.filtered_templates, 0, "baseline should filter nothing");
+    assert!(kept.total_templates > 0, "baseline should emit templates");
+
+    // Same input, mapping-quality threshold no read can meet.
+    let dropped = run_dedup(&temp_dir, "dropped", "61");
+
+    assert_eq!(
+        dropped.filtered_templates, kept.total_templates,
+        "every template the baseline emitted should be reported as filtered"
+    );
+    assert_eq!(
+        dropped.filtered_low_mapping_quality, kept.total_templates,
+        "and all of them attributed to low mapping quality"
+    );
+    assert_eq!(dropped.total_templates, 0, "nothing should reach the output");
+    assert_eq!(dropped.filtered_ns_in_umi, 0, "no other reason should be credited");
+    assert_eq!(dropped.filtered_missing_umi, 0);
+    assert_eq!(dropped.filtered_unmapped, 0);
+}
+
 /// Test dedup command with metrics output.
 #[test]
 fn test_dedup_command_with_metrics() {
@@ -296,6 +367,70 @@ fn test_dedup_include_unmapped(
     assert_eq!(unmapped_seen, expected_unmapped, "unexpected unmapped-read count");
 }
 
+/// Create a secondary alignment for `name` with no `tc` tag.
+///
+/// `ref_id`/`pos` of `None` leave it unplaced, so it travels in the same
+/// template-coordinate group as an unmapped primary pair of the same name.
+fn create_secondary_without_tc(name: &str, umi: &str, placed: bool) -> RawRecord {
+    let mut b = SamBuilder::new();
+    b.read_name(name.as_bytes())
+        .sequence(b"ACGTACGT")
+        .qualities(&[30; 8])
+        .flags(flags::PAIRED | flags::SECONDARY | flags::FIRST_SEGMENT)
+        .add_string_tag(SamTag::RX, umi.as_bytes());
+    if placed {
+        // Same coordinate as `create_duplicate_group`'s R1, so it travels in that
+        // template's position group.
+        b.ref_id(0).pos(99).mapq(60).cigar_ops(&[fgumi_raw_bam::testutil::encode_op(0, 8)]);
+    } else {
+        b.flags(flags::PAIRED | flags::SECONDARY | flags::FIRST_SEGMENT | flags::UNMAPPED);
+    }
+    b.build()
+}
+
+/// A secondary/supplementary read with no `tc` tag is a hard failure, and
+/// `--include-unmapped` must not be a way around it.
+///
+/// `template_is_unmapped_passthrough` decides on the primary `r1`/`r2` alone, so a
+/// template whose primaries are both unmapped is routed to the pass-through partition
+/// carrying whatever non-primary records came with it. Those records are still counted
+/// as `secondary_reads`/`supplementary_reads`, so if the pass-through loop skipped the
+/// `tc` check, `--include-unmapped` would report the read and waive the failure that
+/// the same read triggers on any other template.
+#[rstest]
+#[case::passthrough_template("unmapped1", false)]
+#[case::filtered_template("dup1_0", true)]
+fn test_dedup_missing_tc_fails_on_every_template(#[case] name: &str, #[case] placed: bool) {
+    let temp_dir = TempDir::new().unwrap();
+    let input_bam = temp_dir.path().join("input.bam");
+    let output_bam = temp_dir.path().join("output.bam");
+
+    let mut records = create_duplicate_group("dup1", "ACGTACGT", 3, 100);
+    records.extend(create_unmapped_pair("unmapped1", "TGCATGCA"));
+    records.push(create_secondary_without_tc(name, "TGCATGCA", placed));
+    create_sorted_bam(&input_bam, records);
+
+    let cmd = MarkDuplicates::try_parse_from([
+        "dedup",
+        "--input",
+        input_bam.to_str().unwrap(),
+        "--output",
+        output_bam.to_str().unwrap(),
+        "--strategy",
+        "identity",
+        "--include-unmapped",
+        "--compression-level",
+        "1",
+    ])
+    .expect("failed to parse dedup args");
+
+    let err = cmd.execute("fgumi dedup").expect_err("a tc-less secondary read must fail dedup");
+    assert!(
+        err.to_string().contains("missing the `tc` tag"),
+        "expected the tc-tag failure, got: {err}"
+    );
+}
+
 /// Regression test for OOM with large position groups in `--no-umi` mode.
 ///
 /// WES data can have extreme depth pileups at capture targets, creating positions

From be6041c4f52e7ccf46ea124d00f9dced98dfcaeb Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Wed, 12 Aug 2026 00:11:06 -0700
Subject: [PATCH 7/8] refactor: share one template filter between group and
 dedup

The two implementations were a copy-paste pair. A normalized diff showed them
semantically identical except for a single condition: group gated the
fully-unmapped rejection on --allow-unmapped, dedup always rejected. That is
now TemplateFilterConfig::allow_unmapped, which dedup sets to false because
its --include-unmapped pass-throughs are split off before the filter runs.

Keeping them separate was already a liability, and the reason-recording
change made it worse: nine rejection sites each that had to stay in sync.

While consolidating, reuse what the raw-BAM crate already owns rather than
carrying new copies:

- Drop a second copy of fgumi-raw-bam's integer-aux decode ladder and publish
  that crate's extract_int_value instead. Reusing find_int_tag would have been
  the obvious call but costs a second scan of the aux block per primary read;
  taking the decoder alone keeps the single pass.
- Use RawRecord::is_unmapped / is_qc_fail / is_mate_unmapped instead of
  hand-rolled flag masks, which also removes two RawRecordView constructions
  from the per-read loops.
- Extract template_has_malformed_record and template_is_fully_unmapped, and
  have dedup's --include-unmapped pass-through check call them. It had been
  re-deriving this function's first three branches with inverted polarity, so
  the two could drift on what malformed and unmapped mean.
- Extract the aux-block scan into scan_aux_for_mq_and_umi; the merged function
  was long enough to trip clippy::too_many_lines, and the scan is a
  self-contained parser that reads better named than inlined. It returns early
  when neither tag is wanted.
- Turn set_filter_counts into the from_filter_counts constructor: it was only
  ever called on a freshly defaulted struct, so its four zeroing assignments
  were dead, and 'from' is the repo's convention for factories.
- Give TemplateFilterConfig a hand-written Default (a derived one would produce
  an invalid all-zero umi_tag), collapsing 18 six-field literals in tests.
- ProcessedDedupGroup::estimate_heap_size no longer adds size_of::<DedupCounts>();
  the counts are inline, not heap, and the term inflated the queue's memory
  estimate for small groups.

Both commands' existing filter tests stay where they are: they now exercise
the shared function through each command's own fixtures, which is broader
coverage than a single merged table. The new test in template_filter covers
allow_unmapped, the one branch that distinguishes the callers.

group's .grouping_metrics.txt re-verified byte-identical across three filter
regimes; dedup's metrics unchanged on the same input.
---
 crates/fgumi-metrics/src/group.rs |  34 +--
 crates/fgumi-raw-bam/src/lib.rs   |   4 +-
 crates/fgumi-raw-bam/src/tags.rs  | 108 +++++++--
 src/lib/commands/dedup.rs         | 284 +++--------------------
 src/lib/commands/group.rs         | 360 ++++--------------------------
 src/lib/mod.rs                    |   1 +
 src/lib/template_filter.rs        | 288 ++++++++++++++++++++++++
 7 files changed, 477 insertions(+), 602 deletions(-)
 create mode 100644 src/lib/template_filter.rs

diff --git a/crates/fgumi-metrics/src/group.rs b/crates/fgumi-metrics/src/group.rs
index b10dfbd96..88bb42921 100644
--- a/crates/fgumi-metrics/src/group.rs
+++ b/crates/fgumi-metrics/src/group.rs
@@ -109,7 +109,7 @@ impl UmiGroupingMetrics {
         Self::default()
     }
 
-    /// Fills the fgbio filter columns from [`TemplateFilterCounts`].
+    /// Builds the fgbio filter columns from [`TemplateFilterCounts`].
     ///
     /// fgbio's `UmiGroupingMetric` counts **primary records**, not templates, so
     /// this reads the primary-read side of `counts`. The exhaustive match makes
@@ -120,30 +120,32 @@ impl UmiGroupingMetrics {
     /// finer bucket for them. That collapse is lossy and is retained only for
     /// fgbio parity; `dedup` reports each reason separately.
     ///
-    /// Leaves the family-size and summary fields untouched; the caller fills those.
-    pub fn set_filter_counts(&mut self, counts: &TemplateFilterCounts) {
-        self.total_records = counts.total_primary_reads();
-        self.accepted_records = counts.accepted_primary_reads();
-        self.discarded_non_pf = 0;
-        self.discarded_poor_alignment = 0;
-        self.discarded_ns_in_umi = 0;
-        self.discarded_umi_too_short = 0;
+    /// Leaves the family-size and summary fields at their defaults; the caller
+    /// fills those.
+    #[must_use]
+    pub fn from_filter_counts(counts: &TemplateFilterCounts) -> Self {
+        let mut metrics = Self {
+            total_records: counts.total_primary_reads(),
+            accepted_records: counts.accepted_primary_reads(),
+            ..Self::default()
+        };
 
         for reason in TemplateFilterReason::ALL {
             let reads = counts.rejected_primary_reads(reason);
             let column = match reason {
-                TemplateFilterReason::NotPassingFilter => &mut self.discarded_non_pf,
-                TemplateFilterReason::NsInUmi => &mut self.discarded_ns_in_umi,
-                TemplateFilterReason::UmiTooShort => &mut self.discarded_umi_too_short,
+                TemplateFilterReason::NotPassingFilter => &mut metrics.discarded_non_pf,
+                TemplateFilterReason::NsInUmi => &mut metrics.discarded_ns_in_umi,
+                TemplateFilterReason::UmiTooShort => &mut metrics.discarded_umi_too_short,
                 TemplateFilterReason::MalformedRecord
                 | TemplateFilterReason::NoPrimaryReads
                 | TemplateFilterReason::Unmapped
                 | TemplateFilterReason::LowMappingQuality
                 | TemplateFilterReason::LowMateMappingQuality
-                | TemplateFilterReason::MissingUmi => &mut self.discarded_poor_alignment,
+                | TemplateFilterReason::MissingUmi => &mut metrics.discarded_poor_alignment,
             };
             *column += reads;
         }
+        metrics
     }
 }
 
@@ -321,8 +323,7 @@ mod tests {
         counts.record_accepted(2);
         counts.record_rejected(reason, 2);
 
-        let mut metrics = UmiGroupingMetrics::new();
-        metrics.set_filter_counts(&counts);
+        let metrics = UmiGroupingMetrics::from_filter_counts(&counts);
 
         assert_eq!(metrics.accepted_records, 2, "accepted is in primary-read units");
         assert_eq!(metrics.total_records, 4);
@@ -341,8 +342,7 @@ mod tests {
             counts.record_rejected(reason, 2);
         }
 
-        let mut metrics = UmiGroupingMetrics::new();
-        metrics.set_filter_counts(&counts);
+        let metrics = UmiGroupingMetrics::from_filter_counts(&counts);
 
         let discarded = metrics.discarded_non_pf
             + metrics.discarded_poor_alignment
diff --git a/crates/fgumi-raw-bam/src/lib.rs b/crates/fgumi-raw-bam/src/lib.rs
index f4e650312..186a9f7c3 100644
--- a/crates/fgumi-raw-bam/src/lib.rs
+++ b/crates/fgumi-raw-bam/src/lib.rs
@@ -123,8 +123,8 @@ pub use fgumi_tag::{AsTagBytes, SamTag};
 pub use tags::{
     ArrayTagRef, AuxStringTags, AuxTagsIter, RawTagsEditor, RawTagsMut, RawTagsView, TagEntry,
     TagValue, TemplateAuxTags, append_i32_array_tag, append_signed_int_tag, array_tag_element_u16,
-    array_tag_to_vec_u16, extract_aux_string_tags, extract_template_aux_tags, find_array_tag,
-    find_float_tag, find_int_tag, find_mc_tag_in_record, find_string_tag,
+    array_tag_to_vec_u16, extract_aux_string_tags, extract_int_value, extract_template_aux_tags,
+    find_array_tag, find_float_tag, find_int_tag, find_mc_tag_in_record, find_string_tag,
     find_string_tag_in_record, find_string_tag_position, find_tag_type, find_uint8_tag,
     normalize_int_tag_to_smallest_signed, read_tc_template_coordinate, remove_tag,
     reverse_array_tag_in_place, reverse_complement_string_tag_in_place,
diff --git a/crates/fgumi-raw-bam/src/tags.rs b/crates/fgumi-raw-bam/src/tags.rs
index e68d73955..3fa6f1a1d 100644
--- a/crates/fgumi-raw-bam/src/tags.rs
+++ b/crates/fgumi-raw-bam/src/tags.rs
@@ -146,31 +146,50 @@ pub fn find_int_tag(aux_data: &[u8], tag: impl AsTagBytes) -> Option<i64> {
     extract_int_value(aux_data, p, val_type)
 }
 
+/// Borrow the `width` value bytes of the tag entry that starts at `p`.
+///
+/// The value begins at `p + 3`, after the two tag bytes and the type byte. Returns
+/// `None` if that range overflows `usize` or runs past the end of `aux_data`.
+///
+/// Every offset is computed with checked arithmetic because `p` reaches
+/// `extract_int_value` from the caller rather than from a `find_tag_position` scan:
+/// a position near `usize::MAX` would otherwise wrap and decode unrelated bytes.
+#[inline]
+fn tag_value_bytes(aux_data: &[u8], p: usize, width: usize) -> Option<&[u8]> {
+    let start = p.checked_add(3)?;
+    let end = start.checked_add(width)?;
+    aux_data.get(start..end)
+}
+
 /// Extract an integer value at position `p` with the given type byte.
 ///
-/// Shared by [`find_int_tag`] and [`find_mi_tag`].
-fn extract_int_value(aux_data: &[u8], p: usize, val_type: u8) -> Option<i64> {
+/// Shared by [`find_int_tag`] and `find_mi_tag`, and by callers that walk the
+/// aux block themselves and already hold the tag's position and type byte — they
+/// get the decode ladder without paying for a second `find_tag_position` scan.
+///
+/// Returns `None` for a non-integer type byte, and for any `p` whose value bytes
+/// do not lie wholly within `aux_data`.
+#[must_use]
+pub fn extract_int_value(aux_data: &[u8], p: usize, val_type: u8) -> Option<i64> {
     match val_type {
-        b'c' if p + 4 <= aux_data.len() => Some(i64::from(aux_data[p + 3].cast_signed())),
-        b'C' if p + 4 <= aux_data.len() => Some(i64::from(aux_data[p + 3])),
-        b's' if p + 5 <= aux_data.len() => {
-            Some(i64::from(i16::from_le_bytes([aux_data[p + 3], aux_data[p + 4]])))
+        b'c' => Some(i64::from(tag_value_bytes(aux_data, p, 1)?[0].cast_signed())),
+        b'C' => Some(i64::from(tag_value_bytes(aux_data, p, 1)?[0])),
+        b's' => {
+            let bytes = tag_value_bytes(aux_data, p, 2)?;
+            Some(i64::from(i16::from_le_bytes([bytes[0], bytes[1]])))
         }
-        b'S' if p + 5 <= aux_data.len() => {
-            Some(i64::from(u16::from_le_bytes([aux_data[p + 3], aux_data[p + 4]])))
+        b'S' => {
+            let bytes = tag_value_bytes(aux_data, p, 2)?;
+            Some(i64::from(u16::from_le_bytes([bytes[0], bytes[1]])))
+        }
+        b'i' => {
+            let bytes = tag_value_bytes(aux_data, p, 4)?;
+            Some(i64::from(i32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]])))
+        }
+        b'I' => {
+            let bytes = tag_value_bytes(aux_data, p, 4)?;
+            Some(i64::from(u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]])))
         }
-        b'i' if p + 7 <= aux_data.len() => Some(i64::from(i32::from_le_bytes([
-            aux_data[p + 3],
-            aux_data[p + 4],
-            aux_data[p + 5],
-            aux_data[p + 6],
-        ]))),
-        b'I' if p + 7 <= aux_data.len() => Some(i64::from(u32::from_le_bytes([
-            aux_data[p + 3],
-            aux_data[p + 4],
-            aux_data[p + 5],
-            aux_data[p + 6],
-        ]))),
         _ => None,
     }
 }
@@ -2413,6 +2432,55 @@ mod tests {
         assert_eq!(find_int_tag(&aux, b"ZZ"), None);
     }
 
+    // ========================================================================
+    // extract_int_value bounds tests
+    // ========================================================================
+
+    /// `extract_int_value` is public and takes `p` from the caller rather than from a
+    /// `find_tag_position` scan, so a position near `usize::MAX` reaches the decode
+    /// ladder. With unchecked `p + 3` / `p + 4` / `p + 7` the guard wraps to a small
+    /// number, passes the length check, and the ladder then decodes bytes from a
+    /// wrapped offset — the wrong value, silently, in a release build.
+    #[rstest]
+    #[case::signed_byte(b'c')]
+    #[case::unsigned_byte(b'C')]
+    #[case::signed_short(b's')]
+    #[case::unsigned_short(b'S')]
+    #[case::signed_int(b'i')]
+    #[case::unsigned_int(b'I')]
+    fn test_extract_int_value_rejects_positions_that_overflow(#[case] type_byte: u8) {
+        let aux = [b'X', b'Y', type_byte, 1, 2, 3, 4, 5];
+        // Every `p` within a value width of the top of the address space: `p + 3`,
+        // `p + 4`, and `p + 7` all wrap for at least one of these.
+        for delta in 0..8usize {
+            let p = usize::MAX - delta;
+            assert_eq!(
+                extract_int_value(&aux, p, type_byte),
+                None,
+                "type {} at p = usize::MAX - {delta} must not decode",
+                type_byte as char
+            );
+        }
+    }
+
+    /// The in-bounds ladder is unchanged: a value that ends exactly at the end of the
+    /// aux block still decodes, and one byte short of that still does not.
+    #[rstest]
+    #[case::signed_byte(b'c', 1)]
+    #[case::unsigned_byte(b'C', 1)]
+    #[case::signed_short(b's', 2)]
+    #[case::unsigned_short(b'S', 2)]
+    #[case::signed_int(b'i', 4)]
+    #[case::unsigned_int(b'I', 4)]
+    fn test_extract_int_value_boundary(#[case] type_byte: u8, #[case] width: usize) {
+        let mut exact = vec![b'X', b'Y', type_byte];
+        exact.extend(std::iter::repeat_n(0u8, width));
+        assert_eq!(extract_int_value(&exact, 0, type_byte), Some(0));
+
+        let truncated = &exact[..exact.len() - 1];
+        assert_eq!(extract_int_value(truncated, 0, type_byte), None);
+    }
+
     // --- Per-type find_int_tag tests ---
 
     #[test]
diff --git a/src/lib/commands/dedup.rs b/src/lib/commands/dedup.rs
index 1d664d6d1..1e3581033 100644
--- a/src/lib/commands/dedup.rs
+++ b/src/lib/commands/dedup.rs
@@ -32,7 +32,10 @@ use crate::read_info::LibraryIndex;
 use crate::sam::SamTag;
 use crate::sam::is_template_coordinate_sorted;
 use crate::template::Template;
-use crate::umi::{UmiValidation, validate_umi};
+use crate::template_filter::{
+    TemplateFilterConfig, filter_template, template_has_malformed_record,
+    template_is_fully_unmapped,
+};
 use crate::unified_pipeline::{
     BatchWeight, GroupKeyConfig, Grouper, MemoryEstimate,
     run_bam_pipeline_from_reader_with_mi_assign,
@@ -200,7 +203,6 @@ impl MemoryEstimate for ProcessedDedupGroup {
         self.templates.iter().map(MemoryEstimate::estimate_heap_size).sum::<usize>()
             + self.templates.capacity() * std::mem::size_of::<Template>()
             + self.family_sizes.capacity() * std::mem::size_of::<(usize, u64)>()
-            + std::mem::size_of::<DedupCounts>()
     }
 }
 
@@ -208,21 +210,6 @@ impl MemoryEstimate for ProcessedDedupGroup {
 // Configuration
 //////////////////////////////////////////////////////////////////////////////
 
-/// Configuration for template filtering during deduplication.
-#[derive(Clone)]
-struct DedupFilterConfig {
-    /// UMI tag bytes (e.g., [b'R', b'X']).
-    umi_tag: [u8; 2],
-    /// Minimum mapping quality.
-    min_mapq: u8,
-    /// Whether to include non-PF reads.
-    include_non_pf: bool,
-    /// Minimum UMI length.
-    min_umi_length: Option<usize>,
-    /// Skip UMI validation; group by template coordinate, orientation-agnostically.
-    no_umi: bool,
-}
-
 //////////////////////////////////////////////////////////////////////////////
 // Duplicate scoring
 //////////////////////////////////////////////////////////////////////////////
@@ -296,165 +283,6 @@ fn score_template(template: &Template) -> i64 {
 // Template filtering (adapted from group command)
 //////////////////////////////////////////////////////////////////////////////
 
-/// Filter a template based on filtering criteria.
-/// Returns true if the template should be kept.
-fn filter_template(
-    template: &Template,
-    config: &DedupFilterConfig,
-    counts: &mut TemplateFilterCounts,
-) -> bool {
-    // Primary-record count, recorded alongside the template count so `group` and
-    // `dedup` can render the same measurement in their respective units.
-    let primary_reads = u64::from(template.r1().is_some()) + u64::from(template.r2().is_some());
-
-    // Fail closed when *any* record (primary, secondary, or supplementary) is
-    // shorter than the minimum BAM record length: a truncated record indicates
-    // corrupt input, so the template must be rejected rather than have the
-    // malformed record silently dropped (and later panic in RawRecordView::new
-    // on the dedup/serialize path).
-    if template.records().iter().any(|r| r.len() < fgumi_raw_bam::MIN_BAM_RECORD_LEN) {
-        counts.record_rejected(TemplateFilterReason::MalformedRecord, primary_reads);
-        return false;
-    }
-
-    let raw_r1 = template.r1();
-    let raw_r2 = template.r2();
-
-    if raw_r1.is_none() && raw_r2.is_none() {
-        counts.record_rejected(TemplateFilterReason::NoPrimaryReads, primary_reads);
-        return false;
-    }
-
-    let both_unmapped = raw_r1
-        .is_none_or(|r| (RawRecordView::new(r).flags() & fgumi_raw_bam::flags::UNMAPPED) != 0)
-        && raw_r2
-            .is_none_or(|r| (RawRecordView::new(r).flags() & fgumi_raw_bam::flags::UNMAPPED) != 0);
-    if both_unmapped {
-        counts.record_rejected(TemplateFilterReason::Unmapped, primary_reads);
-        return false;
-    }
-
-    // Phase 1: Flag-based checks
-    for raw in [raw_r1, raw_r2].into_iter().flatten() {
-        let flg = RawRecordView::new(raw).flags();
-
-        if !config.include_non_pf && (flg & fgumi_raw_bam::flags::QC_FAIL) != 0 {
-            counts.record_rejected(TemplateFilterReason::NotPassingFilter, primary_reads);
-            return false;
-        }
-
-        if (flg & fgumi_raw_bam::flags::UNMAPPED) == 0 {
-            let mapq = fgumi_raw_bam::mapq(raw);
-            if mapq < config.min_mapq {
-                counts.record_rejected(TemplateFilterReason::LowMappingQuality, primary_reads);
-                return false;
-            }
-        }
-    }
-
-    // Phase 2: Single-pass tag lookups (MQ + UMI in one aux scan)
-    for raw in [raw_r1, raw_r2].into_iter().flatten() {
-        let flg = RawRecordView::new(raw).flags();
-        let aux = fgumi_raw_bam::aux_data_slice(raw);
-        let check_mq = (flg & fgumi_raw_bam::flags::MATE_UNMAPPED) == 0;
-        let check_umi = !config.no_umi;
-
-        let mut found_mq: Option<i64> = None;
-        let mut found_umi: Option<&[u8]> = None;
-        let mut p = 0;
-        while p + 3 <= aux.len() {
-            let t = [aux[p], aux[p + 1]];
-            let val_type = aux[p + 2];
-
-            if check_umi && t == config.umi_tag && val_type == b'Z' {
-                let start = p + 3;
-                if let Some(end) = aux[start..].iter().position(|&b| b == 0) {
-                    found_umi = Some(&aux[start..start + end]);
-                    p = start + end + 1;
-                } else {
-                    break;
-                }
-                if !check_mq || found_mq.is_some() {
-                    break;
-                }
-                continue;
-            }
-
-            if check_mq && t == *SamTag::MQ {
-                found_mq = match val_type {
-                    b'C' if p + 3 < aux.len() => Some(i64::from(aux[p + 3])),
-                    b'c' if p + 3 < aux.len() => Some(i64::from(aux[p + 3] as i8)),
-                    b'S' if p + 5 <= aux.len() => {
-                        Some(i64::from(u16::from_le_bytes([aux[p + 3], aux[p + 4]])))
-                    }
-                    b's' if p + 5 <= aux.len() => {
-                        Some(i64::from(i16::from_le_bytes([aux[p + 3], aux[p + 4]])))
-                    }
-                    b'I' if p + 7 <= aux.len() => Some(i64::from(u32::from_le_bytes([
-                        aux[p + 3],
-                        aux[p + 4],
-                        aux[p + 5],
-                        aux[p + 6],
-                    ]))),
-                    b'i' if p + 7 <= aux.len() => Some(i64::from(i32::from_le_bytes([
-                        aux[p + 3],
-                        aux[p + 4],
-                        aux[p + 5],
-                        aux[p + 6],
-                    ]))),
-                    _ => None,
-                };
-            }
-
-            if let Some(size) = fgumi_raw_bam::tag_value_size(val_type, &aux[p + 3..]) {
-                p += 3 + size;
-            } else {
-                break;
-            }
-            if (!check_umi || found_umi.is_some()) && (!check_mq || found_mq.is_some()) {
-                break;
-            }
-        }
-
-        if check_mq && let Some(mq) = found_mq {
-            // Compare as signed so a negative MQ (e.g., MQ:c:-1) fails the filter
-            // rather than wrapping to 255 via `as u8`.
-            if mq < i64::from(config.min_mapq) {
-                counts.record_rejected(TemplateFilterReason::LowMateMappingQuality, primary_reads);
-                return false;
-            }
-        }
-
-        // Skip UMI validation in no-umi mode
-        if config.no_umi {
-            continue;
-        }
-
-        if let Some(umi_bytes) = found_umi {
-            match validate_umi(umi_bytes) {
-                UmiValidation::ContainsN => {
-                    counts.record_rejected(TemplateFilterReason::NsInUmi, primary_reads);
-                    return false;
-                }
-                UmiValidation::Valid(base_count) => {
-                    if let Some(min_len) = config.min_umi_length
-                        && base_count < min_len
-                    {
-                        counts.record_rejected(TemplateFilterReason::UmiTooShort, primary_reads);
-                        return false;
-                    }
-                }
-            }
-        } else {
-            counts.record_rejected(TemplateFilterReason::MissingUmi, primary_reads);
-            return false;
-        }
-    }
-
-    counts.record_accepted(primary_reads);
-    true
-}
-
 /// Returns `true` when a template has no mapped primary read (both mates unmapped,
 /// or a single unmapped read) and is not truncated/corrupt.
 ///
@@ -465,24 +293,12 @@ fn filter_template(
 /// so they still fall through to `filter_template` and are dropped — a corrupt record
 /// must never be passed through to the output.
 fn template_is_unmapped_passthrough(template: &Template) -> bool {
-    // A truncated record indicates corrupt input; leave it for `filter_template` to
-    // reject rather than emitting a malformed record.
-    if template.records().iter().any(|r| r.len() < fgumi_raw_bam::MIN_BAM_RECORD_LEN) {
-        return false;
-    }
-
-    let raw_r1 = template.r1();
-    let raw_r2 = template.r2();
-
-    // A template with no primary read at all is a poor-alignment discard, not a
-    // pass-through; let `filter_template` account for it.
-    if raw_r1.is_none() && raw_r2.is_none() {
-        return false;
-    }
-
-    raw_r1.is_none_or(|r| (RawRecordView::new(r).flags() & fgumi_raw_bam::flags::UNMAPPED) != 0)
-        && raw_r2
-            .is_none_or(|r| (RawRecordView::new(r).flags() & fgumi_raw_bam::flags::UNMAPPED) != 0)
+    // Both predicates are the shared filter's own, so the two cannot drift on what
+    // "malformed" or "unmapped" means. A truncated record is deliberately NOT a
+    // pass-through: it is left for `filter_template` to reject, so a corrupt record
+    // is never emitted verbatim. A template with no primary read at all is likewise
+    // left to the filter, which accounts for it as `NoPrimaryReads`.
+    !template_has_malformed_record(template) && template_is_fully_unmapped(template)
 }
 
 //////////////////////////////////////////////////////////////////////////////
@@ -813,7 +629,7 @@ fn mark_template_as_duplicate(template: &mut Template, dedup_counts: &mut DedupC
 /// Process a position group for deduplication.
 fn process_position_group(
     group: RawPositionGroup,
-    filter_config: &DedupFilterConfig,
+    filter_config: &TemplateFilterConfig,
     assigner: &dyn UmiAssigner,
     raw_tag: SamTag,
     min_umi_length: Option<usize>,
@@ -1254,12 +1070,16 @@ impl Command for MarkDuplicates {
         let cell_tag = Tag::from(SamTag::CB);
         let assign_tag_bytes: [u8; 2] = *SamTag::MI;
 
-        let filter_config = DedupFilterConfig {
+        let filter_config = TemplateFilterConfig {
             umi_tag: *raw_tag,
             min_mapq,
             include_non_pf: self.include_non_pf_reads,
             min_umi_length: self.min_umi_length,
             no_umi: self.no_umi,
+            // Always false: --include-unmapped splits no-mapped-read templates off
+            // *before* the filter runs (see `template_is_unmapped_passthrough`), so
+            // an unmapped template reaching the filter is always a rejection.
+            allow_unmapped: false,
         };
 
         // Shared state for collecting metrics
@@ -1840,14 +1660,8 @@ mod tests {
     // filter_template tests
     // ========================================================================
 
-    fn default_filter_config() -> DedupFilterConfig {
-        DedupFilterConfig {
-            umi_tag: *SamTag::RX,
-            min_mapq: 20,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-        }
+    fn default_filter_config() -> TemplateFilterConfig {
+        TemplateFilterConfig { min_mapq: 20, ..Default::default() }
     }
 
     /// Helper to create a mapped template with UMI tag
@@ -2911,7 +2725,7 @@ mod tests {
     }
 
     #[test]
-    fn test_filter_template_raw_truncated_record_no_panic() {
+    fn test_filter_template_raw_record_truncated_no_panic() {
         // After fix: truncated records no longer panic -- they gracefully return false.
         // The aux block is truncated rather than the record itself, so the record
         // clears the minimum-length check and is rejected for the missing UMI tag.
@@ -2920,13 +2734,7 @@ mod tests {
         let template =
             Template::from_records(vec![raw]).expect("test template construction should not fail");
 
-        let config = DedupFilterConfig {
-            umi_tag: *SamTag::RX,
-            min_mapq: 20,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-        };
+        let config = TemplateFilterConfig { min_mapq: 20, ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
 
         // Should not panic; should reject gracefully due to missing UMI
@@ -2935,9 +2743,9 @@ mod tests {
         assert_eq!(metrics.rejected_templates(TemplateFilterReason::MissingUmi), 1);
     }
 
-    // Test that the raw-byte mode MQ tag issue actually occurs in filter_template_raw
+    // Test that the raw-byte mode MQ tag issue actually occurs in filter_template
     #[test]
-    fn test_filter_template_raw_mq_tag_type_mismatch_bypasses_filter() {
+    fn test_filter_template_raw_record_mq_tag_type_mismatch() {
         // Build a BAM record with exact sizes so aux data is contiguous.
         // Header(32) + name(4) + cigar(4) + seq(2) + qual(4) = 46 bytes before aux
         let mut rec = vec![0u8; 46];
@@ -2964,16 +2772,10 @@ mod tests {
         let template = Template::from_records(vec![RawRecord::from(rec)])
             .expect("test template construction should not fail");
 
-        let config = DedupFilterConfig {
-            umi_tag: *SamTag::RX,
-            min_mapq: 20,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-        };
+        let config = TemplateFilterConfig { min_mapq: 20, ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
 
-        // After fix: filter_template_raw now uses find_int_tag which handles all integer types.
+        // After fix: filter_template now uses find_int_tag which handles all integer types.
         // The template should be REJECTED because mate MAPQ=10 < min_mapq=20.
         let result = filter_template(&template, &config, &mut metrics);
 
@@ -3164,7 +2966,7 @@ mod tests {
     }
 
     // ========================================================================
-    // filter_template_raw passing/rejecting tests
+    // filter_template passing/rejecting tests
     // ========================================================================
 
     /// What an `rstest` case expects the filter to record: `None` for an accepted
@@ -3211,7 +3013,7 @@ mod tests {
             | fgumi_raw_bam::flags::MATE_UNMAPPED,
         0, b"ACGT", 0, None, false, Some(TemplateFilterReason::Unmapped)
     )]
-    fn test_filter_template_raw(
+    fn test_filter_template(
         #[case] flags: u16,
         #[case] mapq: u8,
         #[case] umi: &'static [u8],
@@ -3223,12 +3025,13 @@ mod tests {
         let raw = make_raw_bam_for_dedup(b"rea", flags, mapq, 4, &[20, 20, 20, 20], umi);
         let template =
             Template::from_records(vec![raw]).expect("test template construction should not fail");
-        let config = DedupFilterConfig {
+        let config = TemplateFilterConfig {
             umi_tag: *SamTag::RX,
             min_mapq,
             include_non_pf: false,
             min_umi_length,
             no_umi: false,
+            allow_unmapped: false,
         };
         let mut metrics = TemplateFilterCounts::new();
         assert_eq!(filter_template(&template, &config, &mut metrics), expect_pass);
@@ -3398,7 +3201,7 @@ mod tests {
     }
 
     #[test]
-    fn test_filter_template_raw_accepts_missing_umi_when_no_umi_mode() {
+    fn test_filter_template_raw_record_accepts_missing_umi_when_no_umi_mode() {
         let raw = make_raw_bam_for_dedup_no_tags(
             b"rea",
             fgumi_raw_bam::flags::PAIRED
@@ -3410,13 +3213,7 @@ mod tests {
         );
         let template =
             Template::from_records(vec![raw]).expect("test template construction should not fail");
-        let config = DedupFilterConfig {
-            umi_tag: *SamTag::RX,
-            min_mapq: 20,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: true,
-        };
+        let config = TemplateFilterConfig { min_mapq: 20, no_umi: true, ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
 
         // In no_umi mode, templates without UMI tags should be accepted
@@ -3425,7 +3222,7 @@ mod tests {
     }
 
     #[test]
-    fn test_filter_template_raw_accepts_umi_with_n_when_no_umi_mode() {
+    fn test_filter_template_raw_record_accepts_umi_with_n_when_no_umi_mode() {
         let raw = make_raw_bam_for_dedup(
             b"rea",
             fgumi_raw_bam::flags::PAIRED
@@ -3438,13 +3235,7 @@ mod tests {
         );
         let template =
             Template::from_records(vec![raw]).expect("test template construction should not fail");
-        let config = DedupFilterConfig {
-            umi_tag: *SamTag::RX,
-            min_mapq: 0,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: true,
-        };
+        let config = TemplateFilterConfig { no_umi: true, ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
 
         // In no_umi mode, UMIs with N should be accepted (UMI validation is skipped)
@@ -3453,7 +3244,7 @@ mod tests {
     }
 
     #[test]
-    fn test_filter_template_raw_accepts_short_umi_when_no_umi_mode() {
+    fn test_filter_template_raw_record_accepts_short_umi_when_no_umi_mode() {
         let raw = make_raw_bam_for_dedup(
             b"rea",
             fgumi_raw_bam::flags::PAIRED
@@ -3466,13 +3257,8 @@ mod tests {
         );
         let template =
             Template::from_records(vec![raw]).expect("test template construction should not fail");
-        let config = DedupFilterConfig {
-            umi_tag: *SamTag::RX,
-            min_mapq: 0,
-            include_non_pf: false,
-            min_umi_length: Some(6),
-            no_umi: true,
-        };
+        let config =
+            TemplateFilterConfig { min_umi_length: Some(6), no_umi: true, ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
 
         // In no_umi mode, short UMIs should be accepted (min_umi_length is not checked)
diff --git a/src/lib/commands/group.rs b/src/lib/commands/group.rs
index 8aab055ea..df93db165 100644
--- a/src/lib/commands/group.rs
+++ b/src/lib/commands/group.rs
@@ -10,17 +10,17 @@ use crate::grouper::{
     ProcessedPositionGroup, RawPositionGroup, RecordPositionGrouper, build_templates_from_records,
 };
 use crate::logging::{OperationTimer, log_umi_grouping_summary};
+use crate::metrics::TemplateFilterCounts;
 use crate::metrics::group::{FamilySizeMetrics, PositionGroupSizeMetrics, UmiGroupingMetrics};
-use crate::metrics::{TemplateFilterCounts, TemplateFilterReason};
 use crate::per_thread_accumulator::PerThreadAccumulator;
 use crate::read_info::LibraryIndex;
 use crate::sam::is_template_coordinate_sorted;
 use crate::template::Template;
+use crate::template_filter::{TemplateFilterConfig, filter_template};
 use crate::umi::parallel_assigner::{
     ParallelAdjacencyAssigner, ParallelEditAssigner, ParallelIdentityAssigner,
     ParallelPairedAssigner,
 };
-use crate::umi::{UmiValidation, validate_umi};
 use crate::unified_pipeline::DecodedRecord;
 use crate::unified_pipeline::compute_group_key_from_raw;
 use crate::unified_pipeline::{
@@ -90,195 +90,10 @@ impl GroupMetricsAccumulator {
     }
 }
 
-/// Configuration for template filtering during group processing.
-#[derive(Clone)]
-struct GroupFilterConfig {
-    /// UMI tag bytes (e.g., [b'R', b'X']).
-    umi_tag: [u8; 2],
-    /// Minimum mapping quality.
-    min_mapq: u8,
-    /// Whether to include non-PF reads.
-    include_non_pf: bool,
-    /// Minimum UMI length (None to disable).
-    min_umi_length: Option<usize>,
-    /// Skip UMI validation; group by template coordinate and strand of origin alone.
-    no_umi: bool,
-    /// Whether to allow fully unmapped templates (both reads unmapped).
-    allow_unmapped: bool,
-}
-
 // =============================================================================
 // Raw-byte filter and helper functions
 // =============================================================================
 
-/// Filter a template in raw-byte mode based on filtering criteria.
-/// Returns true if the template should be kept, false if it should be discarded.
-fn filter_template_raw(
-    template: &Template,
-    config: &GroupFilterConfig,
-    counts: &mut TemplateFilterCounts,
-) -> bool {
-    use fgumi_raw_bam;
-    use fgumi_raw_bam::RawRecordView;
-
-    // Recorded once at the accept/reject site rather than on entry, so the
-    // accepted + rejected == total invariant holds by construction.
-    let primary_reads = u64::from(template.r1().is_some()) + u64::from(template.r2().is_some());
-
-    // Fail closed when *any* record (primary, secondary, or supplementary) is
-    // shorter than the minimum BAM record length: a truncated record indicates
-    // corrupt input, so the whole template must be rejected (not silently
-    // treated as a single-read template, and never reaching RawRecordView::new
-    // on a malformed slice).
-    if template.records().iter().any(|r| r.len() < fgumi_raw_bam::MIN_BAM_RECORD_LEN) {
-        counts.record_rejected(TemplateFilterReason::MalformedRecord, primary_reads);
-        return false;
-    }
-
-    let raw_r1 = template.r1();
-    let raw_r2 = template.r2();
-    let num_primary_reads = primary_reads;
-
-    if raw_r1.is_none() && raw_r2.is_none() {
-        counts.record_rejected(TemplateFilterReason::NoPrimaryReads, num_primary_reads);
-        return false;
-    }
-
-    // Check if both reads are unmapped
-    let both_unmapped = raw_r1
-        .is_none_or(|r| (RawRecordView::new(r).flags() & fgumi_raw_bam::flags::UNMAPPED) != 0)
-        && raw_r2
-            .is_none_or(|r| (RawRecordView::new(r).flags() & fgumi_raw_bam::flags::UNMAPPED) != 0);
-    if both_unmapped && !config.allow_unmapped {
-        counts.record_rejected(TemplateFilterReason::Unmapped, num_primary_reads);
-        return false;
-    }
-
-    // Phase 1: Cheap flag-based checks
-    for raw in [raw_r1, raw_r2].into_iter().flatten() {
-        let flg = RawRecordView::new(raw).flags();
-
-        if !config.include_non_pf && (flg & fgumi_raw_bam::flags::QC_FAIL) != 0 {
-            counts.record_rejected(TemplateFilterReason::NotPassingFilter, num_primary_reads);
-            return false;
-        }
-
-        if (flg & fgumi_raw_bam::flags::UNMAPPED) == 0 && fgumi_raw_bam::mapq(raw) < config.min_mapq
-        {
-            counts.record_rejected(TemplateFilterReason::LowMappingQuality, num_primary_reads);
-            return false;
-        }
-    }
-
-    // Phase 2: Single-pass tag lookups (MQ + UMI in one aux scan)
-    for raw in [raw_r1, raw_r2].into_iter().flatten() {
-        let flg = RawRecordView::new(raw).flags();
-        let aux = fgumi_raw_bam::aux_data_slice(raw);
-        let check_mq = (flg & fgumi_raw_bam::flags::MATE_UNMAPPED) == 0;
-        let check_umi = !config.no_umi;
-
-        // Single pass over aux data to find both MQ and UMI tags
-        let mut found_mq: Option<i64> = None;
-        let mut found_umi: Option<&[u8]> = None;
-        let mut p = 0;
-        while p + 3 <= aux.len() {
-            let t = [aux[p], aux[p + 1]];
-            let val_type = aux[p + 2];
-
-            if check_umi && t == config.umi_tag && val_type == b'Z' {
-                let start = p + 3;
-                if let Some(end) = aux[start..].iter().position(|&b| b == 0) {
-                    found_umi = Some(&aux[start..start + end]);
-                    p = start + end + 1;
-                } else {
-                    break;
-                }
-                if !check_mq || found_mq.is_some() {
-                    break;
-                }
-                continue;
-            }
-
-            if check_mq && t == *SamTag::MQ {
-                // Extract MQ value (common types: C/c/S/s/I/i)
-                found_mq = match val_type {
-                    b'C' if p + 3 < aux.len() => Some(i64::from(aux[p + 3])),
-                    b'c' if p + 3 < aux.len() => Some(i64::from(aux[p + 3] as i8)),
-                    b'S' if p + 5 <= aux.len() => {
-                        Some(i64::from(u16::from_le_bytes([aux[p + 3], aux[p + 4]])))
-                    }
-                    b's' if p + 5 <= aux.len() => {
-                        Some(i64::from(i16::from_le_bytes([aux[p + 3], aux[p + 4]])))
-                    }
-                    b'I' if p + 7 <= aux.len() => Some(i64::from(u32::from_le_bytes([
-                        aux[p + 3],
-                        aux[p + 4],
-                        aux[p + 5],
-                        aux[p + 6],
-                    ]))),
-                    b'i' if p + 7 <= aux.len() => Some(i64::from(i32::from_le_bytes([
-                        aux[p + 3],
-                        aux[p + 4],
-                        aux[p + 5],
-                        aux[p + 6],
-                    ]))),
-                    _ => None,
-                };
-            }
-
-            if let Some(size) = fgumi_raw_bam::tag_value_size(val_type, &aux[p + 3..]) {
-                p += 3 + size;
-            } else {
-                break;
-            }
-            if (!check_umi || found_umi.is_some()) && (!check_mq || found_mq.is_some()) {
-                break;
-            }
-        }
-
-        // Check mate MAPQ. Compare in i64 so a malformed `MQ:i:-1` (or any
-        // negative value from a signed integer aux type) reads as below the
-        // threshold instead of wrapping into a large positive u8.
-        if check_mq
-            && let Some(mq) = found_mq
-            && mq < i64::from(config.min_mapq)
-        {
-            counts.record_rejected(TemplateFilterReason::LowMateMappingQuality, num_primary_reads);
-            return false;
-        }
-
-        // Skip UMI validation in no-umi mode
-        if config.no_umi {
-            continue;
-        }
-
-        // Check UMI for Ns and minimum length
-        if let Some(umi_bytes) = found_umi {
-            match validate_umi(umi_bytes) {
-                UmiValidation::ContainsN => {
-                    counts.record_rejected(TemplateFilterReason::NsInUmi, num_primary_reads);
-                    return false;
-                }
-                UmiValidation::Valid(base_count) => {
-                    if let Some(min_len) = config.min_umi_length
-                        && base_count < min_len
-                    {
-                        counts
-                            .record_rejected(TemplateFilterReason::UmiTooShort, num_primary_reads);
-                        return false;
-                    }
-                }
-            }
-        } else {
-            counts.record_rejected(TemplateFilterReason::MissingUmi, num_primary_reads);
-            return false;
-        }
-    }
-
-    counts.record_accepted(num_primary_reads);
-    true
-}
-
 /// Get pair orientation from raw-byte template.
 fn get_pair_orientation_raw(template: &Template) -> (bool, bool) {
     use fgumi_raw_bam;
@@ -910,8 +725,7 @@ fn build_grouping_metrics(
     filter_counts: &TemplateFilterCounts,
     family_size_counter: &AHashMap<usize, u64>,
 ) -> UmiGroupingMetrics {
-    let mut metrics = UmiGroupingMetrics::new();
-    metrics.set_filter_counts(filter_counts);
+    let mut metrics = UmiGroupingMetrics::from_filter_counts(filter_counts);
 
     metrics.total_families = family_size_counter.values().sum::<u64>();
     metrics.unique_molecule_ids = metrics.total_families;
@@ -1081,7 +895,7 @@ impl Command for GroupReadsByUmi {
         let cell_tag = Tag::from(SamTag::CB);
 
         // Create filter configuration
-        let filter_config = GroupFilterConfig {
+        let filter_config = TemplateFilterConfig {
             umi_tag: raw_tag,
             min_mapq,
             include_non_pf: self.include_non_pf_reads,
@@ -1284,7 +1098,7 @@ impl Command for GroupReadsByUmi {
                 // Filter templates
                 let filtered_templates: Vec<Template> = all_templates
                     .into_iter()
-                    .filter(|t| filter_template_raw(t, &filter_config, &mut filter_counts))
+                    .filter(|t| filter_template(t, &filter_config, &mut filter_counts))
                     .collect();
 
                 // Track filtered template memory (optimized for hot path).
@@ -1594,7 +1408,7 @@ impl GroupReadsByUmi {
         raw_tag: [u8; 2],
         assign_tag_bytes: [u8; 2],
         cell_tag: Tag,
-        filter_config: &GroupFilterConfig,
+        filter_config: &TemplateFilterConfig,
         timer: &OperationTimer,
     ) -> Result<()> {
         info!("Using single-threaded mode");
@@ -1716,7 +1530,7 @@ impl GroupReadsByUmi {
     #[allow(clippy::too_many_arguments)]
     fn process_and_write_position_group(
         group: RawPositionGroup,
-        filter_config: &GroupFilterConfig,
+        filter_config: &TemplateFilterConfig,
         strategy: Strategy,
         effective_edits: u32,
         index_threshold: IndexThreshold,
@@ -1739,7 +1553,7 @@ impl GroupReadsByUmi {
         // Filter templates
         let filtered_templates: Vec<Template> = all_templates
             .into_iter()
-            .filter(|t| filter_template_raw(t, filter_config, &mut filter_counts))
+            .filter(|t| filter_template(t, filter_config, &mut filter_counts))
             .collect();
 
         total_filter_counts.merge(&filter_counts);
@@ -1960,6 +1774,7 @@ fn with_extension(prefix: &Path, suffix: &str) -> PathBuf {
 mod tests {
     use super::*;
     use crate::assigner::{IdentityUmiAssigner, PairedUmiAssigner, Strategy};
+    use crate::metrics::TemplateFilterReason;
     use bstr::BString;
     use fgumi_raw_bam::{
         SamBuilder as RawSamBuilder, flags, raw_record_to_record_buf, testutil::encode_op,
@@ -5901,7 +5716,7 @@ mod tests {
     }
 
     // ========================================================================
-    // Raw-byte filter_template_raw tests
+    // Raw-byte filter_template tests
     // ========================================================================
 
     /// Build a raw BAM record with specified flags, mapq, and UMI for testing.
@@ -5958,7 +5773,7 @@ mod tests {
     }
 
     #[test]
-    fn test_group_filter_template_raw_accepts_valid() {
+    fn test_group_filter_template_accepts_valid() {
         let raw = make_raw_bam_for_group(
             b"rea",
             fgumi_raw_bam::flags::PAIRED
@@ -5969,21 +5784,14 @@ mod tests {
         );
         let template =
             Template::from_records(vec![raw]).expect("Template::from_raw_records should succeed");
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 20,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { min_mapq: 20, ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
-        assert!(filter_template_raw(&template, &config, &mut metrics));
+        assert!(filter_template(&template, &config, &mut metrics));
         assert_eq!(metrics.accepted_primary_reads(), 1);
     }
 
     #[test]
-    fn test_group_filter_template_raw_rejects_low_mapq() {
+    fn test_group_filter_template_rejects_low_mapq() {
         let raw = make_raw_bam_for_group(
             b"rea",
             fgumi_raw_bam::flags::PAIRED
@@ -5994,21 +5802,14 @@ mod tests {
         );
         let template =
             Template::from_records(vec![raw]).expect("Template::from_raw_records should succeed");
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 20,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { min_mapq: 20, ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
-        assert!(!filter_template_raw(&template, &config, &mut metrics));
+        assert!(!filter_template(&template, &config, &mut metrics));
         assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::LowMappingQuality), 1);
     }
 
     #[test]
-    fn test_group_filter_template_raw_rejects_qc_fail() {
+    fn test_group_filter_template_rejects_qc_fail() {
         let raw = make_raw_bam_for_group(
             b"rea",
             fgumi_raw_bam::flags::PAIRED
@@ -6020,21 +5821,14 @@ mod tests {
         );
         let template =
             Template::from_records(vec![raw]).expect("Template::from_raw_records should succeed");
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 0,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
-        assert!(!filter_template_raw(&template, &config, &mut metrics));
+        assert!(!filter_template(&template, &config, &mut metrics));
         assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::NotPassingFilter), 1);
     }
 
     #[test]
-    fn test_group_filter_template_raw_rejects_umi_with_n() {
+    fn test_group_filter_template_rejects_umi_with_n() {
         let raw = make_raw_bam_for_group(
             b"rea",
             fgumi_raw_bam::flags::PAIRED
@@ -6045,21 +5839,14 @@ mod tests {
         );
         let template =
             Template::from_records(vec![raw]).expect("Template::from_raw_records should succeed");
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 0,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
-        assert!(!filter_template_raw(&template, &config, &mut metrics));
+        assert!(!filter_template(&template, &config, &mut metrics));
         assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::NsInUmi), 1);
     }
 
     #[test]
-    fn test_group_filter_template_raw_rejects_short_umi() {
+    fn test_group_filter_template_rejects_short_umi() {
         let raw = make_raw_bam_for_group(
             b"rea",
             fgumi_raw_bam::flags::PAIRED
@@ -6070,21 +5857,14 @@ mod tests {
         );
         let template =
             Template::from_records(vec![raw]).expect("Template::from_raw_records should succeed");
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 0,
-            include_non_pf: false,
-            min_umi_length: Some(6),
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { min_umi_length: Some(6), ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
-        assert!(!filter_template_raw(&template, &config, &mut metrics));
+        assert!(!filter_template(&template, &config, &mut metrics));
         assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::UmiTooShort), 1);
     }
 
     #[test]
-    fn test_group_filter_template_raw_rejects_unmapped() {
+    fn test_group_filter_template_rejects_unmapped() {
         let raw = make_raw_bam_for_group(
             b"rea",
             fgumi_raw_bam::flags::UNMAPPED | fgumi_raw_bam::flags::MATE_UNMAPPED,
@@ -6093,16 +5873,9 @@ mod tests {
         );
         let template =
             Template::from_records(vec![raw]).expect("Template::from_raw_records should succeed");
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 0,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
-        assert!(!filter_template_raw(&template, &config, &mut metrics));
+        assert!(!filter_template(&template, &config, &mut metrics));
         assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::Unmapped), 1);
     }
 
@@ -6110,7 +5883,7 @@ mod tests {
     /// template too — the previous r1()/r2()-only guard let truncated
     /// non-primary records slip through.
     #[test]
-    fn test_group_filter_template_raw_truncated_secondary_rejected() {
+    fn test_group_filter_template_truncated_secondary_rejected() {
         let valid_r1 = make_raw_bam_for_group(
             b"rea",
             fgumi_raw_bam::flags::PAIRED | fgumi_raw_bam::flags::FIRST_SEGMENT,
@@ -6138,26 +5911,19 @@ mod tests {
             cached_umi_position: None,
         };
 
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 0,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
         assert!(
-            !filter_template_raw(&template, &config, &mut metrics),
+            !filter_template(&template, &config, &mut metrics),
             "truncated secondary must cause the template to be rejected"
         );
         assert_eq!(metrics.rejected_primary_reads(TemplateFilterReason::MalformedRecord), 2);
     }
 
     #[test]
-    fn test_group_filter_template_raw_truncated_record_treated_as_missing() {
+    fn test_group_filter_template_truncated_record_treated_as_missing() {
         // Construct a Template by bypassing from_records validation so that
-        // raw_records[0] is shorter than MIN_BAM_RECORD_LEN. filter_template_raw
+        // raw_records[0] is shorter than MIN_BAM_RECORD_LEN. filter_template
         // must reject the template, accounting for the missing primary read.
         let short_rec = fgumi_raw_bam::RawRecord::from(vec![0u8; 16]);
         let valid_rec = make_raw_bam_for_group(
@@ -6188,17 +5954,10 @@ mod tests {
             cached_umi_position: None,
         };
 
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 0,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
         assert!(
-            !filter_template_raw(&template, &config, &mut metrics),
+            !filter_template(&template, &config, &mut metrics),
             "truncated R1 must cause the template to be rejected"
         );
     }
@@ -6207,7 +5966,7 @@ mod tests {
     /// non-negative threshold, not wrapped to a large positive `u8` (which
     /// would let malformed records slip past `min_mapq`).
     #[test]
-    fn test_group_filter_template_raw_negative_mate_mq_rejected() {
+    fn test_group_filter_template_negative_mate_mq_rejected() {
         // Build R1 + R2 where R2 carries an aux MQ:i:-1 (signed int aux type).
         fn make_with_neg_mate_mq(name: &[u8], flag: u16, mapq: u8) -> fgumi_raw_bam::RawRecord {
             let seq_len = 4usize;
@@ -6261,23 +6020,16 @@ mod tests {
         let template =
             Template::from_records(vec![r1, r2]).expect("template construction should succeed");
 
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 20,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { min_mapq: 20, ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
         assert!(
-            !filter_template_raw(&template, &config, &mut metrics),
+            !filter_template(&template, &config, &mut metrics),
             "negative mate MQ must compare below min_mapq (signed semantics)"
         );
     }
 
     #[test]
-    fn test_group_filter_template_raw_no_primary_reads() {
+    fn test_group_filter_template_no_primary_reads() {
         // Template with only supplementary records → no raw_r1/raw_r2
         let supp = make_raw_bam_for_group(
             b"rea",
@@ -6290,17 +6042,10 @@ mod tests {
         );
         let template =
             Template::from_records(vec![supp]).expect("Template::from_raw_records should succeed");
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 0,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { ..Default::default() };
         let mut metrics = TemplateFilterCounts::new();
         // Supplementary-only template has no primary R1/R2 → raw_r1() returns None
-        assert!(!filter_template_raw(&template, &config, &mut metrics));
+        assert!(!filter_template(&template, &config, &mut metrics));
     }
 
     // ========================================================================
@@ -6639,17 +6384,11 @@ mod tests {
         let (r1, r2) = build_unmapped_test_pair("unmapped", "AAAAAA");
         let template = Template::from_records(vec![r1, r2])?;
 
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 1,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: true,
-        };
+        let config =
+            TemplateFilterConfig { min_mapq: 1, allow_unmapped: true, ..Default::default() };
 
         let mut metrics = TemplateFilterCounts::new();
-        let should_keep = filter_template_raw(&template, &config, &mut metrics);
+        let should_keep = filter_template(&template, &config, &mut metrics);
 
         assert!(should_keep, "Unmapped template should be kept when allow_unmapped=true");
         assert_eq!(metrics.total_primary_reads(), 2, "Should count 2 records");
@@ -6663,17 +6402,10 @@ mod tests {
         let (r1, r2) = build_unmapped_test_pair("unmapped", "AAAAAA");
         let template = Template::from_records(vec![r1, r2])?;
 
-        let config = GroupFilterConfig {
-            umi_tag: [b'R', b'X'],
-            min_mapq: 1,
-            include_non_pf: false,
-            min_umi_length: None,
-            no_umi: false,
-            allow_unmapped: false,
-        };
+        let config = TemplateFilterConfig { min_mapq: 1, ..Default::default() };
 
         let mut metrics = TemplateFilterCounts::new();
-        let should_keep = filter_template_raw(&template, &config, &mut metrics);
+        let should_keep = filter_template(&template, &config, &mut metrics);
 
         assert!(!should_keep, "Unmapped template should be rejected when allow_unmapped=false");
         assert_eq!(metrics.total_primary_reads(), 2, "Should count 2 records");
diff --git a/src/lib/mod.rs b/src/lib/mod.rs
index 06f6ae129..6188e2e6a 100644
--- a/src/lib/mod.rs
+++ b/src/lib/mod.rs
@@ -151,6 +151,7 @@ pub mod sam;
 pub mod system;
 pub mod tag_reversal;
 pub mod template;
+pub mod template_filter;
 pub mod umi;
 pub mod unified_pipeline;
 pub mod validation;
diff --git a/src/lib/template_filter.rs b/src/lib/template_filter.rs
new file mode 100644
index 000000000..54df93dba
--- /dev/null
+++ b/src/lib/template_filter.rs
@@ -0,0 +1,288 @@
+//! The pre-grouping template filter shared by the `group` and `dedup` commands.
+//!
+//! Both commands drop templates that fail the same criteria before grouping them
+//! by position and UMI. This module owns the single implementation; per-reason
+//! accounting goes into a [`TemplateFilterCounts`], which each command renders
+//! into its own metrics schema (see `fgumi_metrics::template_filter`).
+//!
+//! The two commands were previously separate, near-identical copies that differed
+//! only in how they handled a fully unmapped template — the behaviour now
+//! expressed by [`TemplateFilterConfig::allow_unmapped`].
+
+use crate::metrics::{TemplateFilterCounts, TemplateFilterReason};
+use crate::sam::SamTag;
+use crate::template::Template;
+use crate::umi::{UmiValidation, validate_umi};
+use fgumi_raw_bam;
+use fgumi_raw_bam::RawRecord;
+
+/// Criteria for [`filter_template`].
+#[derive(Debug, Clone)]
+pub struct TemplateFilterConfig {
+    /// UMI tag bytes (e.g. `[b'R', b'X']`).
+    pub umi_tag: [u8; 2],
+    /// Minimum mapping quality, applied to a read's own `MAPQ` and to its mate's
+    /// `MQ` tag.
+    pub min_mapq: u8,
+    /// Keep reads flagged QC-fail rather than discarding them.
+    pub include_non_pf: bool,
+    /// Minimum UMI length; `None` disables the check.
+    pub min_umi_length: Option<usize>,
+    /// Skip UMI validation entirely (missing UMI, Ns, and length are not checked).
+    pub no_umi: bool,
+    /// Accept templates whose every primary read is unmapped.
+    ///
+    /// `group` sets this from `--allow-unmapped`. `dedup` always passes `false`:
+    /// its `--include-unmapped` pass-throughs are split off *before* the filter
+    /// runs, so an unmapped template reaching this function is always a rejection.
+    pub allow_unmapped: bool,
+}
+
+/// Returns `true` when any record in the template is shorter than the minimum BAM
+/// record length, i.e. the input is truncated or corrupt.
+///
+/// Shared with `dedup`'s `--include-unmapped` pass-through check so the two agree
+/// on what "malformed" means: a corrupt record must never be passed through.
+#[must_use]
+pub fn template_has_malformed_record(template: &Template) -> bool {
+    template.records().iter().any(|r| r.len() < fgumi_raw_bam::MIN_BAM_RECORD_LEN)
+}
+
+/// Returns `true` when the template has no mapped primary read.
+///
+/// Shared with `dedup`'s `--include-unmapped` pass-through check so the two agree
+/// on what "unmapped" means. A template with neither primary read present is not
+/// "unmapped" — see [`TemplateFilterReason::NoPrimaryReads`] — so this returns
+/// `false` for it.
+#[must_use]
+pub fn template_is_fully_unmapped(template: &Template) -> bool {
+    let (raw_r1, raw_r2) = (template.r1(), template.r2());
+    if raw_r1.is_none() && raw_r2.is_none() {
+        return false;
+    }
+    raw_r1.is_none_or(RawRecord::is_unmapped) && raw_r2.is_none_or(RawRecord::is_unmapped)
+}
+
+impl Default for TemplateFilterConfig {
+    /// The CLI defaults: standard `RX` UMI tag, no mapping-quality or UMI-length
+    /// minimum, and no exceptions. Deliberately hand-written rather than derived —
+    /// a derived `umi_tag` would be `[0, 0]`, which is not a valid tag.
+    fn default() -> Self {
+        Self {
+            umi_tag: *SamTag::RX,
+            min_mapq: 0,
+            include_non_pf: false,
+            min_umi_length: None,
+            no_umi: false,
+            allow_unmapped: false,
+        }
+    }
+}
+
+/// Filters a template against `config`, recording the outcome in `counts`.
+///
+/// Returns `true` when the template should be kept. Every call records exactly
+/// one outcome — one accept or one rejection with a specific
+/// [`TemplateFilterReason`] — so the counts always reconcile.
+pub fn filter_template(
+    template: &Template,
+    config: &TemplateFilterConfig,
+    counts: &mut TemplateFilterCounts,
+) -> bool {
+    // Primary-record count, recorded alongside the template count so `group` and
+    // `dedup` can render the same measurement in their respective units.
+    let primary_reads = u64::from(template.r1().is_some()) + u64::from(template.r2().is_some());
+
+    // Fail closed when *any* record (primary, secondary, or supplementary) is
+    // shorter than the minimum BAM record length: a truncated record indicates
+    // corrupt input, so the template must be rejected rather than have the
+    // malformed record silently dropped (and later panic in RawRecordView::new
+    // on the dedup/serialize path).
+    if template_has_malformed_record(template) {
+        counts.record_rejected(TemplateFilterReason::MalformedRecord, primary_reads);
+        return false;
+    }
+
+    let raw_r1 = template.r1();
+    let raw_r2 = template.r2();
+
+    if raw_r1.is_none() && raw_r2.is_none() {
+        counts.record_rejected(TemplateFilterReason::NoPrimaryReads, primary_reads);
+        return false;
+    }
+
+    if template_is_fully_unmapped(template) && !config.allow_unmapped {
+        counts.record_rejected(TemplateFilterReason::Unmapped, primary_reads);
+        return false;
+    }
+
+    // Phase 1: Flag-based checks
+    for raw in [raw_r1, raw_r2].into_iter().flatten() {
+        if !config.include_non_pf && raw.is_qc_fail() {
+            counts.record_rejected(TemplateFilterReason::NotPassingFilter, primary_reads);
+            return false;
+        }
+
+        if !raw.is_unmapped() {
+            let mapq = fgumi_raw_bam::mapq(raw);
+            if mapq < config.min_mapq {
+                counts.record_rejected(TemplateFilterReason::LowMappingQuality, primary_reads);
+                return false;
+            }
+        }
+    }
+
+    // Phase 2: Single-pass tag lookups (MQ + UMI in one aux scan)
+    for raw in [raw_r1, raw_r2].into_iter().flatten() {
+        let aux = fgumi_raw_bam::aux_data_slice(raw);
+        let check_mq = !raw.is_mate_unmapped();
+        let check_umi = !config.no_umi;
+
+        let (found_mq, found_umi) =
+            scan_aux_for_mq_and_umi(aux, config.umi_tag, check_mq, check_umi);
+
+        // Compare as signed so a negative MQ (e.g. `MQ:c:-1`) fails the filter rather
+        // than wrapping to 255 via `as u8`. `found_mq` is `Some` only when `check_mq`
+        // was set, so no further guard is needed here.
+        if let Some(mq) = found_mq
+            && mq < i64::from(config.min_mapq)
+        {
+            counts.record_rejected(TemplateFilterReason::LowMateMappingQuality, primary_reads);
+            return false;
+        }
+
+        // Skip UMI validation in no-umi mode
+        if config.no_umi {
+            continue;
+        }
+
+        if let Some(umi_bytes) = found_umi {
+            match validate_umi(umi_bytes) {
+                UmiValidation::ContainsN => {
+                    counts.record_rejected(TemplateFilterReason::NsInUmi, primary_reads);
+                    return false;
+                }
+                UmiValidation::Valid(base_count) => {
+                    if let Some(min_len) = config.min_umi_length
+                        && base_count < min_len
+                    {
+                        counts.record_rejected(TemplateFilterReason::UmiTooShort, primary_reads);
+                        return false;
+                    }
+                }
+            }
+        } else {
+            counts.record_rejected(TemplateFilterReason::MissingUmi, primary_reads);
+            return false;
+        }
+    }
+
+    counts.record_accepted(primary_reads);
+    true
+}
+
+/// Scans a record's aux block once for both the `MQ` tag and the UMI tag.
+///
+/// Returns `(mate_mapping_quality, umi_bytes)`, either of which is `None` when the
+/// tag is absent, unparseable, or was not requested. A single pass is used because
+/// this runs once per primary read of every template in the input.
+///
+/// `check_mq` and `check_umi` let the caller skip the half it does not need — the
+/// scan stops as soon as everything requested has been found.
+fn scan_aux_for_mq_and_umi(
+    aux: &[u8],
+    umi_tag: [u8; 2],
+    check_mq: bool,
+    check_umi: bool,
+) -> (Option<i64>, Option<&[u8]>) {
+    if !check_mq && !check_umi {
+        return (None, None);
+    }
+    let mut found_mq: Option<i64> = None;
+    let mut found_umi: Option<&[u8]> = None;
+    let mut p = 0;
+    while p + 3 <= aux.len() {
+        let t = [aux[p], aux[p + 1]];
+        let val_type = aux[p + 2];
+
+        if check_umi && t == umi_tag && val_type == b'Z' {
+            let start = p + 3;
+            if let Some(end) = aux[start..].iter().position(|&b| b == 0) {
+                found_umi = Some(&aux[start..start + end]);
+                p = start + end + 1;
+            } else {
+                break;
+            }
+            if !check_mq || found_mq.is_some() {
+                break;
+            }
+            continue;
+        }
+
+        if check_mq && t == *SamTag::MQ {
+            found_mq = fgumi_raw_bam::extract_int_value(aux, p, val_type);
+        }
+
+        if let Some(size) = fgumi_raw_bam::tag_value_size(val_type, &aux[p + 3..]) {
+            p += 3 + size;
+        } else {
+            break;
+        }
+        if (!check_umi || found_umi.is_some()) && (!check_mq || found_mq.is_some()) {
+            break;
+        }
+    }
+    (found_mq, found_umi)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use fgumi_raw_bam::SamBuilder;
+
+    /// Builds a template whose every primary read is unmapped.
+    fn unmapped_template() -> Template {
+        let mut builder = SamBuilder::new();
+        builder
+            .read_name(b"unmapped")
+            .sequence(b"ACGT")
+            .qualities(&[30; 4])
+            .flags(fgumi_raw_bam::flags::UNMAPPED | fgumi_raw_bam::flags::MATE_UNMAPPED)
+            .add_string_tag(SamTag::RX, b"ACGT");
+        Template::from_records(vec![builder.build()]).expect("template construction")
+    }
+
+    fn config(allow_unmapped: bool) -> TemplateFilterConfig {
+        TemplateFilterConfig {
+            umi_tag: *SamTag::RX,
+            min_mapq: 0,
+            include_non_pf: false,
+            min_umi_length: None,
+            no_umi: false,
+            allow_unmapped,
+        }
+    }
+
+    /// `allow_unmapped` is the only behavioural difference between the two callers
+    /// this function was unified from: `group` sets it from `--allow-unmapped`,
+    /// while `dedup` always passes `false` because its `--include-unmapped`
+    /// pass-throughs are split off before the filter runs. Both settings are
+    /// exercised here so the merge cannot silently lose one command's behaviour.
+    #[rstest::rstest]
+    #[case::rejected_when_disallowed(false, false)]
+    #[case::accepted_when_allowed(true, true)]
+    fn unmapped_templates_respect_allow_unmapped(
+        #[case] allow_unmapped: bool,
+        #[case] expect_accept: bool,
+    ) {
+        let mut counts = TemplateFilterCounts::new();
+        let accepted = filter_template(&unmapped_template(), &config(allow_unmapped), &mut counts);
+
+        assert_eq!(accepted, expect_accept);
+        assert_eq!(
+            counts.rejected_templates(TemplateFilterReason::Unmapped),
+            u64::from(!expect_accept)
+        );
+        assert_eq!(counts.accepted_templates(), u64::from(expect_accept));
+    }
+}

From f36659de7021af97d2461ef56133fcdc5a087d4f Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Tue, 11 Aug 2026 23:47:36 -0700
Subject: [PATCH 8/8] docs(dedup): document the filter metrics columns

The --help text has promised per-reason drop counts since #565 without the
code ever writing them. Correct it to name the actual columns, their unit, and
the reconciliation, and note that total_templates counts templates written
rather than read. Its list of drop reasons was also missing the
no-primary-reads case, which left one filtered_* column with nothing
documenting it.

Metric field doc comments become the Description column of the generated
reference page, so they stay one short line each; the prose about units and
reconciliation lives in the struct doc, which renders as page text.

Also flag in the metrics guide that dedup counts discards in templates while
group counts them in primary records, so the two files are not comparable.

The DeduplicationMetrics reference page is generated by cargo xtask from those
doc comments; that output is gitignored and built in CI, so nothing is
committed for it here.

Two loose ends from reviewing the above: assert passthrough_templates and
filtered_unmapped in test_dedup_include_unmapped, which previously checked
record counts only and passed no --metrics, leaving that column's production
increment unverified; and aim the grouping-logic path instruction at the new
template_filter module, since the existing glob expands to template.rs only.
---
 .coderabbit.yaml                        |  2 +-
 CHANGELOG.md                            | 18 ++++++++
 crates/fgumi-metrics/src/dedup.rs       | 58 ++++++++++++-------------
 docs/src/guide/working-with-metrics.md  | 12 ++++-
 src/lib/commands/dedup.rs               | 52 +++++++++++++---------
 tests/integration/test_dedup_command.rs | 26 ++++++++++-
 6 files changed, 114 insertions(+), 54 deletions(-)

diff --git a/.coderabbit.yaml b/.coderabbit.yaml
index fe94227c9..de5fd8616 100644
--- a/.coderabbit.yaml
+++ b/.coderabbit.yaml
@@ -329,7 +329,7 @@ reviews:
         require it to be called out. Do NOT file wording-only nits on help text
         or doc comments unless the text states a behavior the code does not
         implement.
-    - path: "src/lib/{grouper,template,mi_group,read_info}.rs"
+    - path: "src/lib/{grouper,template,template_filter,mi_group,read_info}.rs"
       instructions: >-
         Core read-grouping and template-assembly logic that sits outside the
         crates but feeds the same fgbio-validated output as `fgumi-umi` and
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ed245d0c5..affd5e53b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,16 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
+- **Breaking:** `dedup --metrics` gains eleven columns: one `filtered_*` column per template
+  filter reason, `filtered_templates` for the total, and `passthrough_templates` for the
+  `--include-unmapped` templates that bypass the filter. Consumers that parse the file
+  positionally must be updated; consumers keyed on column names are unaffected. Note that
+  `fgumi compare metrics` treats a column-set difference as `DIFFER`, so comparing a
+  pre-change dedup metrics file against a post-change one will fail by design.
+
+  These columns count *templates*, whereas the `discarded_*` columns of `group`'s
+  fgbio-shaped `.grouping_metrics.txt` count *primary records*. `group`'s output is unchanged.
+
 - **Breaking:** consensus downsampling now selects which reads to retain by a hash of the read
   name rather than by shuffling a seeded random number generator. This affects `simplex
   --max-reads`, `duplex --max-reads-per-strand`, and `codec --max-reads`.
@@ -28,6 +38,14 @@ All notable changes to this project will be documented in this file.
 
 ### Bug Fixes
 
+- `dedup --metrics` now reports the templates dropped by its template filter, broken out by
+  reason. `dedup` is a read filter as well as a duplicate marker, but the drop counts were
+  collected, merged across workers, and then discarded at the serialization boundary: a run
+  that filtered out every input template wrote a row of zeros and logged only "Deduplication
+  complete: 0 templates", with nothing to indicate records had been dropped or why. A
+  per-reason summary is now also logged, so the drops are visible without `--metrics`
+  ([#739](https://github.com/fulcrumgenomics/fgumi/issues/739)).
+
 - `duplex --max-reads-per-strand 0` is now rejected at startup. It previously exited 0 having
   written an empty BAM, because a cap of zero empties every strand. `simplex` and `codec`
   already validated their equivalents.
diff --git a/crates/fgumi-metrics/src/dedup.rs b/crates/fgumi-metrics/src/dedup.rs
index 42faf266d..351d23a46 100644
--- a/crates/fgumi-metrics/src/dedup.rs
+++ b/crates/fgumi-metrics/src/dedup.rs
@@ -15,63 +15,63 @@ use crate::Metric;
 ///    that `group`'s fgbio-shaped `.grouping_metrics.txt` counts primary
 ///    *records*, so the two files' discard counts are not comparable.
 /// 2. **Deduplication** — `total_templates` through `duplicate_reads`, covering
-///    only what survived filtering.
+///    only what survived filtering. These count what *passed the filter*, not what
+///    reaches the output file: under `--remove-duplicates` the duplicates are
+///    dropped at write time, after they have been counted here.
 /// 3. **Diagnostics** — `secondary_reads`, `supplementary_reads`,
 ///    `missing_tc_tag`.
 ///
 /// Templates read from the input are `filtered_templates + total_templates`; that
 /// sum is not emitted as its own column because it is derivable, matching
-/// [`crate::group::UmiGroupingMetrics`]' treatment of its derivable fields.
+/// `UmiGroupingMetrics`' treatment of its derivable fields.
+// NB: plain code spans above, never intra-doc links — this doc is rendered verbatim
+// into docs/src/metrics/deduplication-metrics.md, where a rustdoc link would come
+// out as literal markdown. Keep field docs to a single short line: they become the
+// Description column of that page's table.
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct DeduplicationMetrics {
-    /// Templates dropped by the filter, for any reason.
+    /// Templates dropped by the filter (any reason)
     pub filtered_templates: u64,
-    /// Dropped because a record was shorter than the minimum BAM record length
-    /// (corrupt input).
+    /// Templates dropped (record shorter than the minimum BAM record length)
     pub filtered_malformed_record: u64,
-    /// Dropped because the template had neither a primary R1 nor a primary R2.
+    /// Templates dropped (no primary R1 or R2)
     pub filtered_no_primary_reads: u64,
-    /// Dropped because no primary read was mapped. Always zero with
-    /// `--include-unmapped`, which routes these to `passthrough_templates`.
+    /// Templates dropped (no mapped primary read)
     pub filtered_unmapped: u64,
-    /// Dropped because a primary read carried the QC-fail flag.
+    /// Templates dropped (QC-fail flag)
     pub filtered_not_passing_filter: u64,
-    /// Dropped because a mapped primary read's mapping quality was below
-    /// `--min-map-q`.
+    /// Templates dropped (mapping quality below `--min-map-q`)
     pub filtered_low_mapping_quality: u64,
-    /// Dropped because a primary read's `MQ` tag was below `--min-map-q`.
+    /// Templates dropped (mate `MQ` below `--min-map-q`)
     pub filtered_low_mate_mapping_quality: u64,
-    /// Dropped because a primary read had no UMI tag.
+    /// Templates dropped (no UMI tag)
     pub filtered_missing_umi: u64,
-    /// Dropped because the UMI contained an `N` base.
+    /// Templates dropped (N base in the UMI)
     pub filtered_ns_in_umi: u64,
-    /// Dropped because the UMI was shorter than `--min-umi-length`.
+    /// Templates dropped (UMI shorter than `--min-umi-length`)
     pub filtered_umi_too_short: u64,
-    /// Templates emitted untouched by `--include-unmapped`: never filtered, never
-    /// marked, never MI-tagged. Counted as unique in the columns below.
+    /// Templates emitted untouched by `--include-unmapped`
     pub passthrough_templates: u64,
-    /// Templates written to the output (accepted by the filter, plus
-    /// pass-throughs) — not the number read from the input.
+    /// Templates that passed the filter
     pub total_templates: u64,
-    /// Templates kept as the representative of their UMI family.
+    /// Templates kept as their family's representative
     pub unique_templates: u64,
-    /// Templates marked as duplicates.
+    /// Templates marked as duplicates
     pub duplicate_templates: u64,
-    /// `duplicate_templates / total_templates`, or 0 when nothing was output.
+    /// `duplicate_templates` / `total_templates`
     #[serde(with = "crate::float")]
     pub duplicate_rate: f64,
-    /// Reads written to the output.
+    /// Reads in templates that passed the filter
     pub total_reads: u64,
-    /// Reads not marked as duplicates.
+    /// Reads not marked as duplicates
     pub unique_reads: u64,
-    /// Reads marked as duplicates.
+    /// Reads marked as duplicates
     pub duplicate_reads: u64,
-    /// Secondary alignments seen in the output.
+    /// Secondary alignments that passed the filter
     pub secondary_reads: u64,
-    /// Supplementary alignments seen in the output.
+    /// Supplementary alignments that passed the filter
     pub supplementary_reads: u64,
-    /// Secondary/supplementary reads lacking the `tc` tag that `fgumi zipper`
-    /// adds and template-coordinate ordering requires.
+    /// Secondary/supplementary reads lacking the `tc` tag
     pub missing_tc_tag: u64,
 }
 
diff --git a/docs/src/guide/working-with-metrics.md b/docs/src/guide/working-with-metrics.md
index 2f814979d..92b6da320 100644
--- a/docs/src/guide/working-with-metrics.md
+++ b/docs/src/guide/working-with-metrics.md
@@ -27,10 +27,18 @@ A header row followed by a single data row. Used by `dedup`, `codec`, `duplex-me
 `simplex-metrics`, and `group`.
 
 ```text
-total_templates	unique_templates	duplicate_templates	duplicate_rate
-25000	18750	6250	0.25
+filtered_templates	filtered_low_mapping_quality	…	total_templates	unique_templates	duplicate_templates	duplicate_rate
+1200	1200	…	25000	18750	6250	0.25
 ```
 
+The example above is abridged; see
+[DeduplicationMetrics](../metrics/deduplication-metrics.md) for the full column list.
+
+Note that `dedup` and `group` count their discards in **different units**. `dedup`'s
+`filtered_*` columns count *templates*, while `group`'s `discarded_*` columns count *primary
+records* — the latter match fgbio's `UmiGroupingMetric` schema exactly, so they are readable
+by fgbio's `Metric.read`. Do not compare the two files' discard counts directly.
+
 ### Vertical Key-Value (Simplex/Duplex)
 
 The `simplex` and `duplex` commands use a three-column format with one metric per row:
diff --git a/src/lib/commands/dedup.rs b/src/lib/commands/dedup.rs
index 1e3581033..e1b1f1ccb 100644
--- a/src/lib/commands/dedup.rs
+++ b/src/lib/commands/dedup.rs
@@ -75,13 +75,16 @@ const DUPLICATE_FLAG: u16 = 0x400;
 /// schema: this is the accumulator, that is the file.
 #[derive(Debug, Default, Clone)]
 pub struct DedupCounts {
-    /// Total templates processed
+    /// Templates that passed the filter (excludes filtered)
+    ///
+    /// Not "written": under `--remove-duplicates` the duplicates are dropped at
+    /// serialization, after this counter has already taken them.
     pub total_templates: u64,
     /// Templates marked as duplicates
     pub duplicate_templates: u64,
     /// Templates kept (not duplicates)
     pub unique_templates: u64,
-    /// Total reads processed
+    /// Reads in templates that passed the filter (excludes filtered)
     pub total_reads: u64,
     /// Reads marked as duplicates
     pub duplicate_reads: u64,
@@ -93,10 +96,9 @@ pub struct DedupCounts {
     pub supplementary_reads: u64,
     /// Secondary/supplementary without `tc` tag
     pub missing_tc_tag: u64,
-    /// Per-reason counts from the template filter.
+    /// Per-reason counts from the template filter
     pub filter_counts: TemplateFilterCounts,
-    /// Templates emitted untouched by `--include-unmapped`, which bypass the
-    /// filter entirely and so appear in no `filter_counts` bucket.
+    /// Templates emitted untouched by `--include-unmapped` (bypass the filter)
     pub passthrough_templates: u64,
 }
 
@@ -824,6 +826,7 @@ discarded (not marked) when:
 
 - Both mates are unmapped (a template with no mapped read), unless --include-unmapped is
   given, in which case such templates are emitted untouched instead of discarded.
+- The template has neither a primary R1 nor a primary R2 record.
 - Any read is flagged QC-fail (unless -n/--include-non-pf-reads is given).
 - A mapped read has mapping quality below -q/--min-map-q (default 0, i.e. no reads are
   dropped for mapping quality unless a threshold is set).
@@ -841,10 +844,19 @@ lets you keep no-mapped-read templates; only truncated/corrupt records are alway
 Pass-through templates are written verbatim: never marked, never MI-tagged, and counted as
 unique in the metrics.
 
-The counts of templates dropped for each reason are reported in the metrics output
-(--metrics). For the templates that remain, representative selection (the duplicate score),
-the 0x400 flag, and --remove-duplicates follow Picard `MarkDuplicates` semantics; the
-grouping key does not — see below.
+The count of templates dropped for each reason is reported in the metrics output
+(--metrics), one `filtered_*` column per reason above, plus `filtered_templates` for the
+total and `passthrough_templates` for the --include-unmapped templates that bypass the
+filter. These count *templates*; the `discarded_*` columns of `fgumi group`'s metrics count
+primary records, so the two files are not directly comparable. Templates read from the input
+are `filtered_templates + total_templates` — note that `total_templates` counts the templates
+that *passed the filter*, not the templates read, and not the templates written either: under
+--remove-duplicates the duplicates are dropped at write time, after they have been counted.
+A per-reason summary is also logged, so the drops are visible even without --metrics.
+
+For the templates that remain, representative selection (the duplicate score), the 0x400
+flag, and --remove-duplicates follow Picard `MarkDuplicates` semantics; the grouping key does
+not — see below.
 
 # Grouping key (strand of origin)
 
@@ -1242,12 +1254,12 @@ impl Command for MarkDuplicates {
         let aggregated = Arc::try_unwrap(collected_metrics)
             .expect("bug: metrics Arc still shared after pipeline join")
             .into_inner();
-        let final_metrics = aggregated.dedup_counts;
+        let final_counts = aggregated.dedup_counts;
         let final_family_sizes = aggregated.family_sizes;
 
         // Write metrics file
         if let Some(metrics_path) = &self.metrics {
-            write_dedup_metrics(&final_metrics, metrics_path)?;
+            write_dedup_metrics(&final_counts, metrics_path)?;
         }
 
         // Write family size histogram
@@ -1258,13 +1270,13 @@ impl Command for MarkDuplicates {
         // Log summary
         info!(
             "Deduplication complete: {} templates ({} unique, {} duplicates, {:.2}% duplicate rate)",
-            final_metrics.total_templates,
-            final_metrics.unique_templates,
-            final_metrics.duplicate_templates,
-            final_metrics.duplicate_rate() * 100.0
+            final_counts.total_templates,
+            final_counts.unique_templates,
+            final_counts.duplicate_templates,
+            final_counts.duplicate_rate() * 100.0
         );
 
-        if final_metrics.missing_tc_tag > 0 {
+        if final_counts.missing_tc_tag > 0 {
             bail!(
                 "{} secondary/supplementary reads are missing the `tc` tag.\n\n\
                 The `tc` tag is required for correct UMI-aware deduplication of \
@@ -1274,7 +1286,7 @@ impl Command for MarkDuplicates {
                 fgumi zipper -i aligned.bam --unmapped unmapped.bam -r reference.fa -o merged.bam\n  \
                 fgumi sort -i merged.bam -o sorted.bam --order template-coordinate\n  \
                 fgumi dedup -i sorted.bam -o deduped.bam",
-                final_metrics.missing_tc_tag
+                final_counts.missing_tc_tag
             );
         }
 
@@ -1282,19 +1294,19 @@ impl Command for MarkDuplicates {
         // dropped templates: a run that filters everything otherwise logs a bare
         // "0 templates" and is indistinguishable from empty input. Reasons are
         // named by their column suffix so the log points at the metrics column.
-        let filtered = final_metrics.filter_counts.total_rejected_templates();
+        let filtered = final_counts.filter_counts.total_rejected_templates();
         if filtered > 0 {
             let reasons: Vec<String> = TemplateFilterReason::ALL
                 .into_iter()
                 .filter_map(|reason| {
-                    let count = final_metrics.filter_counts.rejected_templates(reason);
+                    let count = final_counts.filter_counts.rejected_templates(reason);
                     (count > 0).then(|| format!("{count} {}", reason.column_suffix()))
                 })
                 .collect();
             info!("Filtered out {filtered} templates before marking: {}", reasons.join(", "));
         }
 
-        timer.log_completion(final_metrics.total_reads);
+        timer.log_completion(final_counts.total_reads);
 
         Ok(())
     }
diff --git a/tests/integration/test_dedup_command.rs b/tests/integration/test_dedup_command.rs
index 11c6e067f..96e16d10d 100644
--- a/tests/integration/test_dedup_command.rs
+++ b/tests/integration/test_dedup_command.rs
@@ -302,13 +302,18 @@ fn create_unmapped_pair(name: &str, umi: &str) -> Vec<RawRecord> {
 /// `--include-unmapped` emits templates with no mapped read untouched, while the default
 /// drops them. Input is 3 mapped duplicate pairs (6 reads) + 1 fully-unmapped pair (2 reads);
 /// the default keeps only the 6 mapped reads, and `--include-unmapped` keeps all 8.
+/// `expected_passthrough` / `expected_filtered_unmapped` pin where the no-mapped-read
+/// template is *accounted*, not just whether its reads survive: the two modes must route
+/// it to exactly one of the two columns, never both and never neither.
 #[rstest]
-#[case::default_drops_unmapped(false, 6, 0)]
-#[case::include_unmapped_keeps(true, 8, 2)]
+#[case::default_drops_unmapped(false, 6, 0, 0, 1)]
+#[case::include_unmapped_keeps(true, 8, 2, 1, 0)]
 fn test_dedup_include_unmapped(
     #[case] include_unmapped: bool,
     #[case] expected_total: usize,
     #[case] expected_unmapped: usize,
+    #[case] expected_passthrough: u64,
+    #[case] expected_filtered_unmapped: u64,
 ) {
     use noodles::sam::alignment::record::data::field::Tag;
     use noodles::sam::alignment::record_buf::RecordBuf;
@@ -317,6 +322,7 @@ fn test_dedup_include_unmapped(
     let temp_dir = TempDir::new().unwrap();
     let input_bam = temp_dir.path().join("input.bam");
     let output_bam = temp_dir.path().join("output.bam");
+    let metrics_path = temp_dir.path().join("metrics.txt");
 
     let mut records = create_duplicate_group("dup1", "ACGTACGT", 3, 100);
     records.extend(create_unmapped_pair("unmapped1", "TGCATGCA"));
@@ -332,6 +338,8 @@ fn test_dedup_include_unmapped(
         "identity".into(),
         "--compression-level".into(),
         "1".into(),
+        "--metrics".into(),
+        metrics_path.to_str().unwrap().into(),
     ];
     if include_unmapped {
         args.push("--include-unmapped".into());
@@ -365,6 +373,20 @@ fn test_dedup_include_unmapped(
 
     assert_eq!(total, expected_total, "unexpected output record count");
     assert_eq!(unmapped_seen, expected_unmapped, "unexpected unmapped-read count");
+
+    // The no-mapped-read template must be accounted for in exactly one column: it is
+    // either passed through untouched or filtered as unmapped, never both, never neither.
+    let rows: Vec<DeduplicationMetrics> =
+        DelimFile::default().read_tsv(&metrics_path).expect("failed to read dedup metrics");
+    let metrics = rows.first().expect("one metrics row");
+    assert_eq!(
+        metrics.passthrough_templates, expected_passthrough,
+        "unexpected passthrough_templates"
+    );
+    assert_eq!(
+        metrics.filtered_unmapped, expected_filtered_unmapped,
+        "unexpected filtered_unmapped"
+    );
 }
 
 /// Create a secondary alignment for `name` with no `tc` tag.