From 7034a03163db02ffbd6b20389255f4022c7a238f Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Sun, 27 Sep 2026 04:37:04 -0700
Subject: [PATCH 1/3] fix(runall/align): accept bwa's mid-pair -K split and
 keep both halves' tags

With mixed single-end/paired input, bwa's even-read-count -K chunk cut can
land between a pair's two reads; with -p smart pairing bwa then aligns
them as two unpaired reads and emits them back to back under the pair's
name. The subprocess reader failed on that output. It now recognizes the
shape (no record paired, exactly two primaries) and splits the pair's
unmapped template to match, clearing each half's pairing bits so the
zipper merge copies each read's own tags and QC-fail flag.

The split is accepted only from the bwa and bwa-mem3 presets, which run
`mem -p -K`; a free-form --aligner::command keeps the loud "multiple
primaries" error, since the same shape from an aligner that never pairs
would otherwise split every pair silently.

Also cap a preset's --aligner::chunk-size at i32::MAX: bwa parses -K with
atoi into an int. And add a subprocess align/merge guard
(tests/align_subprocess_split_parity.rs) that runs the preset over a
fixture of substitutions, indels, unmappable, chimeric, discordant,
repeat and zero-length reads with RX tags, checks every read keeps its
tags (including across a forced mid-pair split), and that the output is
identical across --threads values; it runs where a bwa-mem3 binary is
available and skips otherwise.
---
 src/lib/aligner.rs                         |  72 ++-
 src/lib/pipeline/steps/align/merge.rs      |  68 ++
 src/lib/pipeline/steps/align/mod.rs        |  60 +-
 src/lib/pipeline/steps/align/subprocess.rs | 328 ++++++++--
 tests/align_common/mod.rs                  | 718 +++++++++++++++++++++
 tests/align_subprocess_split_parity.rs     | 179 +++++
 6 files changed, 1375 insertions(+), 50 deletions(-)
 create mode 100644 tests/align_common/mod.rs
 create mode 100644 tests/align_subprocess_split_parity.rs

diff --git a/src/lib/aligner.rs b/src/lib/aligner.rs
index 14c8d14c7..3095757e0 100644
--- a/src/lib/aligner.rs
+++ b/src/lib/aligner.rs
@@ -707,7 +707,17 @@ impl Default for AlignerOptions {
 pub(crate) enum ResolvedBackend {
     /// `--aligner::preset` or `--aligner::command`: the shell command to spawn
     /// via [`AlignerProcess::spawn`] (already substituted and validated).
-    Subprocess { command: String },
+    Subprocess {
+        command: String,
+        /// Whether the aligner's output may carry bwa's mid-pair split (a
+        /// pair aligned as two unpaired reads because a `-K` chunk cut fell
+        /// between them). `true` only for the presets, which run `mem -p -K`
+        /// and so produce exactly that shape; a free-form `--aligner::command`
+        /// gets the loud "multiple primaries" error instead, because the same
+        /// shape from an aligner that never pairs would otherwise split every
+        /// pair silently.
+        accept_mid_pair_split: bool,
+    },
 }
 
 /// Result of [`AlignerOptions::resolve`] — a ready-to-construct aligner
@@ -751,6 +761,10 @@ pub(crate) enum ResolvedAlignerMode {
     Command,
 }
 
+/// The largest `--aligner::chunk-size` a preset accepts: `i32::MAX`, since bwa
+/// and bwa-mem3 parse `-K` with `atoi` into an `int`.
+const MAX_PRESET_CHUNK_SIZE: u64 = 2_147_483_647;
+
 impl AlignerOptions {
     /// Validate the option combination and produce a [`ResolvedAligner`]
     /// ready for the align stage's `backend_for` to construct.
@@ -766,6 +780,7 @@ impl AlignerOptions {
     ///
     /// # Errors
     ///
+    /// - `--aligner::chunk-size` is zero, or exceeds `i32::MAX` with a preset.
     /// - Neither `--aligner::preset` nor `--aligner::command` was set.
     /// - Both were set (mutual exclusion violation).
     /// - Command mode + a preset-only flag (`--aligner-bin` or
@@ -789,6 +804,17 @@ impl AlignerOptions {
                  aligner's -K batch size and the pipeline's in-flight unmapped budget"
             );
         }
+        // Every preset hands the chunk size to bwa's `-K`, which bwa and
+        // bwa-mem3 parse with `atoi` into an `int`: a larger value overflows
+        // there instead of reaching the aligner as given. Command mode sets its
+        // own `-K` (this flag only sizes its in-flight budget), so it is exempt.
+        if self.preset.is_some() && self.chunk_size > MAX_PRESET_CHUNK_SIZE {
+            bail!(
+                "--aligner::chunk-size must be at most {MAX_PRESET_CHUNK_SIZE} (got {}) with \
+                 --aligner::preset: bwa parses -K as a 32-bit int",
+                self.chunk_size
+            );
+        }
         match (self.preset, self.command) {
             (None, None) => bail!(
                 "--start-from align requires one of `--aligner::preset` \
@@ -811,7 +837,10 @@ impl AlignerOptions {
                 let command =
                     preset.build_command(reference, threads, self.chunk_size, aligner_bin);
                 Ok(ResolvedAligner {
-                    backend: ResolvedBackend::Subprocess { command },
+                    // Both presets run `mem -p -K`, whose smart pairing splits
+                    // a pair across a chunk cut (bwa and bwa-mem3 share
+                    // `bseq_read`'s even-count cut and `bseq_classify`).
+                    backend: ResolvedBackend::Subprocess { command, accept_mid_pair_split: true },
                     chunk_size: self.chunk_size,
                     threads: Some(threads),
                     mode: ResolvedAlignerMode::Preset(preset),
@@ -846,7 +875,7 @@ impl AlignerOptions {
                 // hardcode any thread count).
                 let command = substitute_template(&template, reference, top_threads)?;
                 Ok(ResolvedAligner {
-                    backend: ResolvedBackend::Subprocess { command },
+                    backend: ResolvedBackend::Subprocess { command, accept_mid_pair_split: false },
                     chunk_size: self.chunk_size,
                     threads: None,
                     mode: ResolvedAlignerMode::Command,
@@ -1149,7 +1178,8 @@ mod tests {
             chunk_size: DEFAULT_ALIGNER_CHUNK_SIZE,
         };
         let resolved = opts.resolve(&ref_path, 4, None).unwrap();
-        let ResolvedBackend::Subprocess { command } = resolved.backend;
+        let ResolvedBackend::Subprocess { command, accept_mid_pair_split } = resolved.backend;
+        assert!(!accept_mid_pair_split, "command mode must not accept bwa's mid-pair split");
         assert!(command.contains(&ref_path.display().to_string()));
         assert!(command.contains("-t 4"));
         assert!(matches!(resolved.mode, ResolvedAlignerMode::Command));
@@ -1327,6 +1357,40 @@ mod tests {
         assert_eq!(result, "bwa-mem3 mem -t 8 /data/{threads}/genome.fa /dev/stdin");
     }
 
+    /// `resolve` caps a preset's `--aligner::chunk-size` at `i32::MAX`, since bwa
+    /// and bwa-mem3 parse `-K` with `atoi` into an `int`; the check runs before
+    /// preset validation, so the reference needs no index.
+    #[rstest]
+    #[case::bwa_mem3(AlignerPreset::BwaMem3, 2_147_483_648)]
+    #[case::bwa(AlignerPreset::Bwa, 4_294_967_296)]
+    fn resolve_rejects_preset_chunk_size_past_i32(
+        #[case] preset: AlignerPreset,
+        #[case] chunk_size: u64,
+    ) {
+        let tmp = tempfile::tempdir().unwrap();
+        let ref_path = tmp.path().join("ref.fa");
+        std::fs::write(&ref_path, b">chr1\nACGT\n").unwrap();
+        let opts = AlignerOptions { preset: Some(preset), chunk_size, ..AlignerOptions::default() };
+        let err = opts.resolve(&ref_path, 4, None).unwrap_err().to_string();
+        let needle = format!("--aligner::chunk-size must be at most 2147483647 (got {chunk_size})");
+        assert!(err.contains(&needle), "got: {err}");
+    }
+
+    /// Command mode sets its own `-K`, so a chunk size past `i32::MAX` (which
+    /// only sizes its in-flight budget) is accepted.
+    #[test]
+    fn resolve_accepts_command_mode_chunk_size_past_i32() {
+        let tmp = tempfile::tempdir().unwrap();
+        let ref_path = tmp.path().join("ref.fa");
+        std::fs::write(&ref_path, b">chr1\nACGT\n").unwrap();
+        let opts = AlignerOptions {
+            command: Some("bwa-mem3 mem -t {threads} {ref} /dev/stdin".to_string()),
+            chunk_size: 2_147_483_648,
+            ..AlignerOptions::default()
+        };
+        assert!(opts.resolve(&ref_path, 4, None).is_ok());
+    }
+
     /// `resolve` rejects `--aligner::chunk-size 0` (would reach the aligner as
     /// `-K 0` and zero the in-flight budget) with a flag-attributed error.
     #[test]
diff --git a/src/lib/pipeline/steps/align/merge.rs b/src/lib/pipeline/steps/align/merge.rs
index 33029d60b..68e78942f 100644
--- a/src/lib/pipeline/steps/align/merge.rs
+++ b/src/lib/pipeline/steps/align/merge.rs
@@ -299,6 +299,74 @@ mod tests {
         );
     }
 
+    /// A pair split across a mid-pair `-K` cut zips each half with the aligner's
+    /// unpaired record for that read. Both halves (and the second read's
+    /// supplementary) must receive their own unmapped read's tags, and the
+    /// second read's QC-fail flag must transfer. Before the split halves'
+    /// pairing bits were cleared, the second half (still `PAIRED |
+    /// LAST_SEGMENT`) looked for a mapped R2, found none, and silently copied
+    /// nothing.
+    #[test]
+    fn split_pair_halves_receive_their_own_tags_and_qc_flag() {
+        use fgumi_raw_bam::flags::{
+            FIRST_SEGMENT, LAST_SEGMENT, MATE_UNMAPPED, PAIRED, QC_FAIL, REVERSE, SUPPLEMENTARY,
+            UNMAPPED,
+        };
+        let cfg = make_test_cfg();
+        let tags = ZipperTags::from_tag_info(&cfg.tag_info);
+        let r1 = make_record_with_string_tag(
+            b"pe10",
+            PAIRED | FIRST_SEGMENT | UNMAPPED | MATE_UNMAPPED,
+            crate::sam::SamTag::RX,
+            b"AAAA",
+        );
+        let r2 = make_record_with_string_tag(
+            b"pe10",
+            PAIRED | LAST_SEGMENT | UNMAPPED | MATE_UNMAPPED | QC_FAIL,
+            crate::sam::SamTag::RX,
+            b"CCCC",
+        );
+        let pair = Template::from_records(vec![r1, r2]).expect("unmapped pair");
+        let (first, second) =
+            crate::pipeline::steps::align::split_pair_into_singles(pair).expect("split");
+        let flags_of = |t: &Template| t.records()[0].flags();
+        assert_eq!(flags_of(&first), UNMAPPED, "first half keeps only non-pairing bits");
+        assert_eq!(flags_of(&second), UNMAPPED | QC_FAIL, "second half keeps QC_FAIL");
+
+        // The aligner emitted both reads unpaired; the second has a supplementary.
+        let mapped_first =
+            Template::from_records(vec![make_record(b"pe10", 0)]).expect("mapped first half");
+        let mapped_second = Template::from_records(vec![
+            make_record(b"pe10", REVERSE),
+            make_record(b"pe10", SUPPLEMENTARY),
+        ])
+        .expect("mapped second half");
+
+        let zb = ZipperBatch {
+            serial: 0,
+            mapped: vec![mapped_first, mapped_second],
+            unmapped: BamTemplateBatch::new(0, vec![first, second]),
+        };
+        let out = merge_zipper_batch(zb, &cfg, &tags).expect("merge ok");
+
+        let rx_of = |rec: &fgumi_raw_bam::RawRecord| {
+            fgumi_raw_bam::tags::find_string_tag(
+                fgumi_raw_bam::fields::aux_data_slice(rec),
+                crate::sam::SamTag::RX,
+            )
+            .map(<[u8]>::to_vec)
+        };
+        let first_out = &out.templates()[0].records;
+        let second_out = &out.templates()[1].records;
+        assert_eq!(rx_of(&first_out[0]), Some(b"AAAA".to_vec()), "first half gets R1's RX");
+        assert_eq!(second_out.len(), 2, "second half keeps its supplementary");
+        for rec in second_out {
+            assert_eq!(rx_of(rec), Some(b"CCCC".to_vec()), "second half gets R2's RX");
+            assert_ne!(rec.flags() & QC_FAIL, 0, "second half gets R2's QC-fail flag");
+        }
+        assert_eq!(first_out[0].flags() & QC_FAIL, 0, "first half's QC-pass status is unchanged");
+    }
+
     /// A `ZipperBatch` whose mapped and unmapped halves differ in length is a
     /// structural invariant violation: `merge_zipper_batch` must hard-error
     /// (release-safe) rather than let `zip` silently truncate to the shorter
diff --git a/src/lib/pipeline/steps/align/mod.rs b/src/lib/pipeline/steps/align/mod.rs
index f97725e85..f1d22ab98 100644
--- a/src/lib/pipeline/steps/align/mod.rs
+++ b/src/lib/pipeline/steps/align/mod.rs
@@ -17,7 +17,7 @@
 //!
 //! This module holds the trait, its wiring context/result types, the
 //! backend-agnostic `ZipperBatch`, the subprocess backend's `InFlightGate`
-//! byte-budget gate, and the header helpers (`validate_sq_consistency`,
+//! byte-budget gate, the mid-pair split helper, and the header helpers (`validate_sq_consistency`,
 //! `merge_aligner_header`).
 
 pub(crate) mod merge;
@@ -297,8 +297,12 @@ pub(crate) trait AlignBackend: Send + 'static {
 /// `aligner` module does not depend on the pipeline's align stage.
 pub(crate) fn backend_for(resolved: ResolvedAligner) -> Box<dyn AlignBackend> {
     match resolved.backend {
-        ResolvedBackend::Subprocess { command } => {
-            Box::new(subprocess::SubprocessBackend { command, chunk_size: resolved.chunk_size })
+        ResolvedBackend::Subprocess { command, accept_mid_pair_split } => {
+            Box::new(subprocess::SubprocessBackend {
+                command,
+                chunk_size: resolved.chunk_size,
+                accept_mid_pair_split,
+            })
         }
     }
 }
@@ -354,6 +358,56 @@ pub(crate) fn validate_sq_consistency(partial: &Header, aligner: &Header) -> io:
     Ok(())
 }
 
+/// The pairing bits [`split_pair_into_singles`] clears on each half's unmapped
+/// record: everything that marks it as one segment of a pair. `QC_FAIL`,
+/// `REVERSE` and the rest are kept.
+const SPLIT_HALF_CLEARED_FLAGS: u16 = fgumi_raw_bam::flags::PAIRED
+    | fgumi_raw_bam::flags::PROPER_PAIR
+    | fgumi_raw_bam::flags::MATE_UNMAPPED
+    | fgumi_raw_bam::flags::MATE_REVERSE
+    | fgumi_raw_bam::flags::FIRST_SEGMENT
+    | fgumi_raw_bam::flags::LAST_SEGMENT;
+
+/// Split a two-primary-read template into two single-record templates, in record
+/// order: bwa's mid-pair split. With mixed SE/PE input a `-K`
+/// chunk boundary can fall between a pair's two reads, and bwa then aligns them as
+/// two unpaired reads. The pair's unmapped template is split the same way so each
+/// half zips with its own read's alignment. Errors if the template carries records
+/// beyond its two primaries (secondaries make the split ambiguous — out of
+/// contract for valid unmapped input).
+///
+/// Each half's record has its pairing bits ([`SPLIT_HALF_CLEARED_FLAGS`]) cleared,
+/// so it is an unpaired read like the aligner's record for it. The zipper merge
+/// picks the mapped segment to copy tags and the QC-fail flag onto from the
+/// *unmapped* record's `PAIRED`/`FIRST_SEGMENT` bits; left set, the second half
+/// (still `PAIRED | LAST_SEGMENT`) would look for a mapped R2, find none (the
+/// aligner emitted it unpaired, which files as R1), and silently copy nothing.
+/// The merged record's own flags come from the aligner, so clearing these bits
+/// on the unmapped side changes nothing else in the output.
+pub(crate) fn split_pair_into_singles(template: Template) -> io::Result<(Template, Template)> {
+    // Reject anything but exactly two primaries before consuming the template,
+    // so the error path reads `template.name()` by reference and the success
+    // path never allocates a name copy.
+    if template.records().len() != 2 {
+        return Err(io::Error::other(format!(
+            "align-and-merge: cannot split template '{name}' across a mid-pair -K chunk \
+             boundary: it carries {n} records, not exactly two primaries (secondary/supplementary \
+             records are out of contract for mixed single/paired input).",
+            name = String::from_utf8_lossy(template.name()),
+            n = template.records().len(),
+        )));
+    }
+    let mut records = template.into_records();
+    let second = records.pop().expect("len checked == 2");
+    let first = records.pop().expect("len checked == 2");
+    let to_template = |mut record: fgumi_raw_bam::RawRecord| {
+        record.set_flags(record.flags() & !SPLIT_HALF_CLEARED_FLAGS);
+        Template::from_records(vec![record])
+            .map_err(|e| io::Error::other(format!("align-and-merge: split-half template: {e:#}")))
+    };
+    Ok((to_template(first)?, to_template(second)?))
+}
+
 /// Merge aligner-emitted header lines into the partial output header.
 ///
 /// The aligner contributes:
diff --git a/src/lib/pipeline/steps/align/subprocess.rs b/src/lib/pipeline/steps/align/subprocess.rs
index 7baf199db..67276279c 100644
--- a/src/lib/pipeline/steps/align/subprocess.rs
+++ b/src/lib/pipeline/steps/align/subprocess.rs
@@ -83,7 +83,7 @@ use crate::pipeline::steps::align::merge::MergeAlignedStep;
 use crate::pipeline::steps::align::{
     AlignBackend, AlignWired, AlignWiringCtx, ConsumerGoneGuard, InFlightGate, ZipperBatch,
     in_flight_budget_for_chunk_size, is_primary_for_alignment, merge_aligner_header,
-    no_primary_records_message, validate_sq_consistency,
+    no_primary_records_message, split_pair_into_singles, validate_sq_consistency,
 };
 use crate::pipeline::steps::types::BamTemplateBatch;
 use crate::template::Template;
@@ -156,6 +156,13 @@ pub(crate) struct SubprocessConfig {
     /// unmapped reads in RAM (issue #382). Derive it from the aligner's
     /// `-K` chunk size via [`in_flight_budget_for_chunk_size`].
     pub(crate) in_flight_unmapped_budget: u64,
+
+    /// Whether a same-queryname output group with two unpaired primaries is
+    /// accepted as bwa's mid-pair split (see [`AlignedGroup::MidPairSplit`]).
+    /// Set only for the subprocess presets (`mem -p -K`); otherwise the group
+    /// fails `Template::from_records`'s "multiple primaries" check, as it did
+    /// before the split was recognized.
+    pub(crate) accept_mid_pair_split: bool,
 }
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -580,8 +587,10 @@ fn reader_loop_inner(
             .read_header()
             .map_err(|e| io::Error::other(format!("aligner BAM header: {e}")))?;
         let bgzf = bam_reader.into_inner();
-        let stream =
-            TemplateStream::Bam(BamTemplateStream::new(fgumi_raw_bam::RawBamReader::new(bgzf)));
+        let stream = TemplateStream::Bam(BamTemplateStream::new(
+            fgumi_raw_bam::RawBamReader::new(bgzf),
+            cfg.accept_mid_pair_split,
+        ));
         (stream, aligner_header)
     } else {
         let buffered = BufReader::with_capacity(STDOUT_READER_BUF_BYTES, stdout);
@@ -590,7 +599,11 @@ fn reader_loop_inner(
             .read_header()
             .map_err(|e| io::Error::other(format!("aligner SAM header: {e}")))?;
         let header_arc = Arc::new(aligner_header.clone());
-        let stream = TemplateStream::Sam(SamTemplateStream::new(sam_reader, header_arc));
+        let stream = TemplateStream::Sam(SamTemplateStream::new(
+            sam_reader,
+            header_arc,
+            cfg.accept_mid_pair_split,
+        ));
         (stream, aligner_header)
     };
 
@@ -656,6 +669,9 @@ fn reader_loop_inner(
         }
 
         let mut mapped_templates: Vec<Template> = Vec::with_capacity(token.n_templates);
+        // Unmapped-template indices bwa split mid-pair; their unmapped halves are
+        // split to match after the loop (rare: needs mixed single/paired input).
+        let mut split_indices: Vec<usize> = Vec::new();
 
         for i in 0..token.n_templates {
             let mapped = template_stream.next_template()?;
@@ -690,14 +706,22 @@ fn reader_loop_inner(
                 )));
             }
 
-            mapped_templates.push(mapped);
+            match mapped {
+                AlignedGroup::Template(t) => mapped_templates.push(t),
+                AlignedGroup::MidPairSplit(first, second) => {
+                    mapped_templates.push(first);
+                    mapped_templates.push(second);
+                    split_indices.push(i);
+                }
+            }
         }
 
-        let zb = ZipperBatch {
-            serial: token.serial,
-            mapped: mapped_templates,
-            unmapped: token.unmapped,
+        let unmapped = if split_indices.is_empty() {
+            token.unmapped
+        } else {
+            split_unmapped_pairs(token.unmapped, &split_indices)?
         };
+        let zb = ZipperBatch { serial: token.serial, mapped: mapped_templates, unmapped };
         if out_tx.send(zb).is_err() {
             // Downstream gone — bail. The dispatcher will observe
             // out_rx disconnected on its next try_run.
@@ -733,6 +757,28 @@ fn reader_loop_inner(
     Ok(())
 }
 
+/// Rebuild `unmapped` with each template at `split_indices` (ascending) split
+/// into its two single-read halves, matching the aligner's mid-pair split so the
+/// mapped and unmapped halves still zip one-to-one.
+fn split_unmapped_pairs(
+    unmapped: BamTemplateBatch,
+    split_indices: &[usize],
+) -> io::Result<BamTemplateBatch> {
+    let (serial, templates) = unmapped.into_parts();
+    let mut out = Vec::with_capacity(templates.len() + split_indices.len());
+    let mut splits = split_indices.iter().peekable();
+    for (i, template) in templates.into_iter().enumerate() {
+        if splits.next_if_eq(&&i).is_some() {
+            let (first, second) = split_pair_into_singles(template)?;
+            out.push(first);
+            out.push(second);
+        } else {
+            out.push(template);
+        }
+    }
+    Ok(BamTemplateBatch::new(serial, out))
+}
+
 /// Peek the leading bytes of `stdout` to classify the aligner's output
 /// format. Returns `(is_bgzf, peek_filled, chained_reader)` where:
 /// - `is_bgzf` is true iff the peeked prefix is a valid BGZF block
@@ -803,7 +849,7 @@ enum TemplateStream {
 }
 
 impl TemplateStream {
-    fn next_template(&mut self) -> io::Result<Option<Template>> {
+    fn next_template(&mut self) -> io::Result<Option<AlignedGroup>> {
         match self {
             Self::Bam(s) => s.next_template(),
             Self::Sam(s) => s.next_template(),
@@ -834,19 +880,62 @@ impl TemplateStream {
     }
 }
 
-/// Group consecutive same-queryname records from `read` into one [`Template`].
+/// One group of consecutive same-queryname records from the aligner.
+enum AlignedGroup {
+    /// The template's alignments (the usual case).
+    Template(Template),
+    /// bwa's mid-pair split: with mixed single/paired input a `-K` chunk
+    /// boundary fell between a pair's two reads, so bwa aligned them as two
+    /// unpaired reads and emitted them back to back under the pair's name —
+    /// the first read's records, then the second's. The reader splits the
+    /// pair's unmapped template the same way (see [`split_pair_into_singles`]).
+    /// Produced only when [`SubprocessConfig::accept_mid_pair_split`] is set
+    /// (the subprocess presets).
+    MidPairSplit(Template, Template),
+}
+
+impl AlignedGroup {
+    /// The group's queryname.
+    fn name(&self) -> &[u8] {
+        match self {
+            Self::Template(t) | Self::MidPairSplit(t, _) => t.name(),
+        }
+    }
+}
+
+/// Where a same-queryname record group splits if it is bwa's mid-pair split:
+/// no record is flagged paired and there are exactly two primaries, in which
+/// case the second read's records start at the second primary. `None` for any
+/// other group.
+fn mid_pair_split_point(records: &[fgumi_raw_bam::RawRecord]) -> Option<usize> {
+    use fgumi_raw_bam::flags::{PAIRED, SECONDARY, SUPPLEMENTARY};
+    if records.iter().any(|r| r.flags() & PAIRED != 0) {
+        return None;
+    }
+    let mut primaries =
+        records.iter().enumerate().filter(|(_, r)| r.flags() & (SECONDARY | SUPPLEMENTARY) == 0);
+    let (first, second) = (primaries.next(), primaries.next());
+    match (first, second, primaries.next()) {
+        (Some(_), Some((split_at, _)), None) => Some(split_at),
+        _ => None,
+    }
+}
+
+/// Group consecutive same-queryname records from `read` into one [`AlignedGroup`].
 ///
 /// Shared by [`BamTemplateStream`] and [`SamTemplateStream`]: only the
 /// per-record read primitive differs (zero-copy BAM read vs SAM decode+encode),
 /// so it is injected as the `read` closure. `peeked` carries the first record of
 /// the *next* template (read one past this template's boundary) across calls,
-/// and `name_buf` is a reusable queryname buffer. Returns `Ok(None)` at end of
-/// stream.
+/// and `name_buf` is a reusable queryname buffer. A group is returned as
+/// [`AlignedGroup::MidPairSplit`] only when `accept_mid_pair_split` is set.
+/// Returns `Ok(None)` at end of stream.
 fn assemble_next_template(
     peeked: &mut Option<fgumi_raw_bam::RawRecord>,
     name_buf: &mut Vec<u8>,
+    accept_mid_pair_split: bool,
     mut read: impl FnMut() -> io::Result<Option<fgumi_raw_bam::RawRecord>>,
-) -> io::Result<Option<Template>> {
+) -> io::Result<Option<AlignedGroup>> {
     let mut records: Vec<fgumi_raw_bam::RawRecord> = Vec::with_capacity(2);
 
     if let Some(first) = peeked.take() {
@@ -872,13 +961,22 @@ fn assemble_next_template(
 
     // Build the owned queryname only on the error path — the success path (every
     // template but a malformed-record edge case) is the hot loop.
-    let template = Template::from_records(records).map_err(|e| {
-        io::Error::other(format!(
-            "Template::from_records for aligner-emitted queryname '{name}': {e}",
-            name = String::from_utf8_lossy(name_buf),
-        ))
-    })?;
-    Ok(Some(template))
+    let build = |records| {
+        Template::from_records(records).map_err(|e| {
+            io::Error::other(format!(
+                "Template::from_records for aligner-emitted queryname '{name}': {e}",
+                name = String::from_utf8_lossy(name_buf),
+            ))
+        })
+    };
+    // Without `accept_mid_pair_split`, a two-unpaired-primary group falls
+    // through to `build`, whose "multiple primaries" error is the loud failure
+    // an aligner that never pairs (a free-form `--aligner::command`) needs.
+    if let Some(split_at) = mid_pair_split_point(&records).filter(|_| accept_mid_pair_split) {
+        let second = records.split_off(split_at);
+        return Ok(Some(AlignedGroup::MidPairSplit(build(records)?, build(second)?)));
+    }
+    Ok(Some(AlignedGroup::Template(build(records)?)))
 }
 
 struct BamTemplateStream {
@@ -889,27 +987,35 @@ struct BamTemplateStream {
     /// `next_template` call; avoids ~one `Vec<u8>` allocation
     /// per template (~40 bytes typical) on hot loops.
     name_buf: Vec<u8>,
+    /// See [`SubprocessConfig::accept_mid_pair_split`].
+    accept_mid_pair_split: bool,
 }
 
 impl BamTemplateStream {
-    fn new(reader: AlignerBamReader) -> Self {
+    fn new(reader: AlignerBamReader, accept_mid_pair_split: bool) -> Self {
         Self {
             reader,
             scratch: fgumi_raw_bam::RawRecord::new(),
             peeked: None,
             name_buf: Vec::with_capacity(64),
+            accept_mid_pair_split,
         }
     }
 
-    fn next_template(&mut self) -> io::Result<Option<Template>> {
+    fn next_template(&mut self) -> io::Result<Option<AlignedGroup>> {
         // Disjoint field capture (Rust 2021+): the closure borrows
         // `reader`/`scratch` while `peeked`/`name_buf` pass as sibling args, so
         // there's no whole-`self` aliasing conflict. `scratch` is reused across
         // reads, so we clone it out.
-        assemble_next_template(&mut self.peeked, &mut self.name_buf, || {
-            let n = self.reader.read_record(&mut self.scratch)?;
-            Ok(if n == 0 { None } else { Some(self.scratch.clone()) })
-        })
+        assemble_next_template(
+            &mut self.peeked,
+            &mut self.name_buf,
+            self.accept_mid_pair_split,
+            || {
+                let n = self.reader.read_record(&mut self.scratch)?;
+                Ok(if n == 0 { None } else { Some(self.scratch.clone()) })
+            },
+        )
     }
 
     fn probe_trailing(&mut self) -> io::Result<bool> {
@@ -933,16 +1039,19 @@ struct SamTemplateStream {
     /// template's last record.
     peeked: Option<fgumi_raw_bam::RawRecord>,
     name_buf: Vec<u8>,
+    /// See [`SubprocessConfig::accept_mid_pair_split`].
+    accept_mid_pair_split: bool,
 }
 
 impl SamTemplateStream {
-    fn new(reader: AlignerSamReader, header: Arc<Header>) -> Self {
+    fn new(reader: AlignerSamReader, header: Arc<Header>, accept_mid_pair_split: bool) -> Self {
         Self {
             reader,
             header,
             scratch: noodles::sam::alignment::RecordBuf::default(),
             peeked: None,
             name_buf: Vec::with_capacity(64),
+            accept_mid_pair_split,
         }
     }
 
@@ -962,23 +1071,28 @@ impl SamTemplateStream {
         Ok(Some(raw))
     }
 
-    fn next_template(&mut self) -> io::Result<Option<Template>> {
+    fn next_template(&mut self) -> io::Result<Option<AlignedGroup>> {
         // Disjoint field capture (see BAM sibling): the closure borrows
         // `reader`/`header`/`scratch` while `peeked`/`name_buf` pass as sibling
         // args. The read primitive is inlined here rather than calling
         // `read_next_raw` (which would borrow all of `self` and conflict with
         // the `&mut self.peeked`/`&mut self.name_buf` args); `read_next_raw`
         // remains as the primitive for `probe_trailing`.
-        assemble_next_template(&mut self.peeked, &mut self.name_buf, || {
-            let n = self.reader.read_record_buf(&self.header, &mut self.scratch)?;
-            if n == 0 {
-                Ok(None)
-            } else {
-                fgumi_raw_bam::encode_record_buf_to_raw(&self.scratch, &self.header)
-                    .map(Some)
-                    .map_err(|e| io::Error::other(format!("encode_record_buf_to_raw: {e}")))
-            }
-        })
+        assemble_next_template(
+            &mut self.peeked,
+            &mut self.name_buf,
+            self.accept_mid_pair_split,
+            || {
+                let n = self.reader.read_record_buf(&self.header, &mut self.scratch)?;
+                if n == 0 {
+                    Ok(None)
+                } else {
+                    fgumi_raw_bam::encode_record_buf_to_raw(&self.scratch, &self.header)
+                        .map(Some)
+                        .map_err(|e| io::Error::other(format!("encode_record_buf_to_raw: {e}")))
+                }
+            },
+        )
     }
 
     fn probe_trailing(&mut self) -> io::Result<bool> {
@@ -1321,6 +1435,8 @@ pub(crate) struct SubprocessBackend {
     /// The aligner's `-K` chunk size (bases), used to derive the in-flight
     /// byte budget.
     pub(crate) chunk_size: u64,
+    /// See [`SubprocessConfig::accept_mid_pair_split`].
+    pub(crate) accept_mid_pair_split: bool,
 }
 
 impl SubprocessBackend {
@@ -1352,6 +1468,7 @@ impl AlignBackend for SubprocessBackend {
                 header_handle: ctx.header_handle.clone(),
                 output_byte_limit: ctx.per_step_byte_limit,
                 in_flight_unmapped_budget: in_flight_budget_for_chunk_size(self.chunk_size),
+                accept_mid_pair_split: self.accept_mid_pair_split,
             },
             &self.command,
         )
@@ -1373,7 +1490,7 @@ impl AlignBackend for SubprocessBackend {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use fgumi_raw_bam::flags::{FIRST_SEGMENT, LAST_SEGMENT, PAIRED};
+    use fgumi_raw_bam::flags::{FIRST_SEGMENT, LAST_SEGMENT, PAIRED, REVERSE, SUPPLEMENTARY};
 
     fn make_test_cfg() -> SubprocessConfig {
         SubprocessConfig {
@@ -1381,6 +1498,7 @@ mod tests {
             header_handle: HeaderHandle::new(),
             output_byte_limit: 1024 * 1024,
             in_flight_unmapped_budget: in_flight_budget_for_chunk_size(150_000_000),
+            accept_mid_pair_split: true,
         }
     }
 
@@ -1744,6 +1862,128 @@ mod tests {
         assert!(result.is_ok(), "SAM-text header should resolve handle to Ok: {:?}", result.err(),);
     }
 
+    /// How one group of same-queryname aligner records should assemble: one
+    /// template of `n` records, or bwa's mid-pair split into two halves.
+    #[derive(Debug, PartialEq, Eq)]
+    enum Assembled {
+        One(usize),
+        Split(usize, usize),
+    }
+
+    /// A group of same-name records assembles as one template unless it is bwa's
+    /// mid-pair split: two primaries and no record flagged paired, which happens
+    /// when a `-K` chunk boundary falls between a pair's reads. A split is cut at
+    /// the second primary, so each half keeps its own supplementaries.
+    #[rstest::rstest]
+    #[case::proper_pair(&[PAIRED | FIRST_SEGMENT, PAIRED | LAST_SEGMENT], Assembled::One(2))]
+    #[case::single_with_supplementary(&[0, SUPPLEMENTARY], Assembled::One(2))]
+    #[case::mid_pair_split(&[0, REVERSE], Assembled::Split(1, 1))]
+    #[case::mid_pair_split_with_supplementaries(
+        &[0, SUPPLEMENTARY, REVERSE, SUPPLEMENTARY],
+        Assembled::Split(2, 2)
+    )]
+    #[case::mid_pair_split_first_half_supplementary(&[0, SUPPLEMENTARY, REVERSE], Assembled::Split(2, 1))]
+    fn assemble_next_template_recognizes_a_mid_pair_split(
+        #[case] flags: &[u16],
+        #[case] expected: Assembled,
+    ) {
+        let recs: Vec<_> = flags.iter().map(|&f| make_record(b"pe10", f)).collect();
+        let mut it = recs.into_iter();
+        let mut peeked: Option<fgumi_raw_bam::RawRecord> = None;
+        let mut name_buf: Vec<u8> = Vec::new();
+        let group = assemble_next_template(&mut peeked, &mut name_buf, true, || Ok(it.next()))
+            .expect("group ok")
+            .expect("group present");
+        assert_eq!(group.name(), b"pe10");
+        let assembled = match group {
+            AlignedGroup::Template(t) => Assembled::One(t.records().len()),
+            AlignedGroup::MidPairSplit(a, b) => {
+                Assembled::Split(a.records().len(), b.records().len())
+            }
+        };
+        assert_eq!(assembled, expected);
+    }
+
+    /// `mid_pair_split_point` fires only for bwa's mid-pair split shape — no
+    /// record flagged paired and exactly two primaries — and splits at the
+    /// second primary.
+    #[rstest::rstest]
+    #[case::proper_pair(&[PAIRED | FIRST_SEGMENT, PAIRED | LAST_SEGMENT], None)]
+    #[case::one_mate_paired(&[PAIRED | FIRST_SEGMENT, 0], None)]
+    #[case::two_unpaired_primaries(&[0, REVERSE], Some(1))]
+    #[case::supplementary_between(&[0, SUPPLEMENTARY, REVERSE], Some(2))]
+    #[case::three_unpaired_primaries(&[0, 0, REVERSE], None)]
+    #[case::single_with_supplementary(&[0, SUPPLEMENTARY], None)]
+    fn mid_pair_split_point_matches_only_two_unpaired_primaries(
+        #[case] flags: &[u16],
+        #[case] expected: Option<usize>,
+    ) {
+        let recs: Vec<_> = flags.iter().map(|&f| make_record(b"pe10", f)).collect();
+        assert_eq!(mid_pair_split_point(&recs), expected);
+    }
+
+    /// Without `accept_mid_pair_split` (a free-form `--aligner::command`), two
+    /// unpaired primaries under one name are not reinterpreted as a split: the
+    /// group fails `Template::from_records` loudly, naming the queryname,
+    /// instead of silently splitting a pair an aligner never paired.
+    #[test]
+    fn two_unpaired_primaries_error_when_the_split_is_not_accepted() {
+        let recs = vec![make_record(b"pe10", 0), make_record(b"pe10", REVERSE)];
+        let mut it = recs.into_iter();
+        let mut peeked: Option<fgumi_raw_bam::RawRecord> = None;
+        let mut name_buf: Vec<u8> = Vec::new();
+        let Err(err) = assemble_next_template(&mut peeked, &mut name_buf, false, || Ok(it.next()))
+        else {
+            panic!("two unpaired primaries must error when the split is not accepted");
+        };
+        let msg = err.to_string();
+        assert!(
+            msg.contains("Template::from_records for aligner-emitted queryname 'pe10'"),
+            "error names the queryname: {msg}"
+        );
+    }
+
+    /// `split_unmapped_pairs` splits exactly the templates at `split_indices`,
+    /// in place and in order, so the unmapped halves line up one-to-one with the
+    /// aligner's split output; untouched templates pass through unchanged.
+    #[test]
+    fn split_unmapped_pairs_splits_only_the_listed_templates_in_order() {
+        use crate::pipeline::core::item::Ordered;
+        let single = |name: &[u8]| {
+            Template::from_records(vec![make_record(name, fgumi_raw_bam::flags::UNMAPPED)])
+                .expect("single")
+        };
+        let pair = |name: &[u8]| {
+            Template::from_records(vec![
+                make_record(name, PAIRED | FIRST_SEGMENT | fgumi_raw_bam::flags::UNMAPPED),
+                make_record(name, PAIRED | LAST_SEGMENT | fgumi_raw_bam::flags::UNMAPPED),
+            ])
+            .expect("pair")
+        };
+        let batch = BamTemplateBatch::new(7, vec![single(b"se1"), pair(b"pe2"), pair(b"pe3")]);
+        let out = split_unmapped_pairs(batch, &[1]).expect("split ok");
+        assert_eq!(out.ordinal(), 7, "the batch serial is preserved");
+        let shape: Vec<(Vec<u8>, usize)> =
+            out.templates().iter().map(|t| (t.name().to_vec(), t.records().len())).collect();
+        assert_eq!(
+            shape,
+            vec![
+                (b"se1".to_vec(), 1),
+                (b"pe2".to_vec(), 1),
+                (b"pe2".to_vec(), 1),
+                (b"pe3".to_vec(), 2),
+            ],
+            "only pe2 is split, into two single-record halves, in place"
+        );
+        for half in &out.templates()[1..3] {
+            assert_eq!(
+                half.records()[0].flags() & (PAIRED | FIRST_SEGMENT | LAST_SEGMENT),
+                0,
+                "each split half is an unpaired read"
+            );
+        }
+    }
+
     /// The shared queryname-grouping state machine (delegated to by both
     /// `BamTemplateStream` and `SamTemplateStream`) must group consecutive
     /// same-queryname records into one `Template` and stash the first record of
@@ -1760,20 +2000,22 @@ mod tests {
         let mut peeked: Option<fgumi_raw_bam::RawRecord> = None;
         let mut name_buf: Vec<u8> = Vec::new();
 
-        let t1 = assemble_next_template(&mut peeked, &mut name_buf, || Ok(it.next()))
+        let t1 = assemble_next_template(&mut peeked, &mut name_buf, true, || Ok(it.next()))
             .expect("t1 ok")
             .expect("t1 present");
+        let AlignedGroup::Template(t1) = t1 else { panic!("t1 is not a mid-pair split") };
         assert_eq!(t1.name(), b"readA");
         assert_eq!(t1.read_count(), 2, "readA's R1+R2 group into one template");
 
-        let t2 = assemble_next_template(&mut peeked, &mut name_buf, || Ok(it.next()))
+        let t2 = assemble_next_template(&mut peeked, &mut name_buf, true, || Ok(it.next()))
             .expect("t2 ok")
             .expect("t2 present");
+        let AlignedGroup::Template(t2) = t2 else { panic!("t2 is not a mid-pair split") };
         assert_eq!(t2.name(), b"readB");
         assert_eq!(t2.read_count(), 1, "readB is a solo template");
 
         assert!(
-            assemble_next_template(&mut peeked, &mut name_buf, || Ok(it.next()))
+            assemble_next_template(&mut peeked, &mut name_buf, true, || Ok(it.next()))
                 .expect("t3 ok")
                 .is_none(),
             "stream is exhausted after the last template"
diff --git a/tests/align_common/mod.rs b/tests/align_common/mod.rs
new file mode 100644
index 000000000..710f9f3a9
--- /dev/null
+++ b/tests/align_common/mod.rs
@@ -0,0 +1,718 @@
+//! Fixture + BAM-comparison helpers for the bwa-mem3 align-stage parity suites
+//! (`align_subprocess_split_parity.rs`).
+//!
+//! Included as `mod align_common;` (a directory module, so cargo does not build
+//! it as a test target of its own). A suite may use only a subset of the
+//! helpers, hence the module-wide `dead_code` allow.
+//!
+//! The fixture is built to exercise real alignment behaviour rather than only
+//! exact matches: a seeded-random reference with a duplicated segment (so reads
+//! there multi-map, get MAPQ 0 and an `XA` tag), and reads drawn in nine kinds —
+//! exact, substitutions, a small insertion, a small deletion, unmappable random
+//! sequence, chimeric (two distant loci, so bwa emits a supplementary),
+//! discordant pairs, reads inside the repeat, and zero-length reads (an empty
+//! single, or a pair with one or both mates empty). Every unmapped input record
+//! carries an `RX` tag and some are QC-fail, so tag and flag transfer through the
+//! zipper merge is part of what the suites compare.
+
+#![allow(dead_code)]
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::io::Write as _;
+use std::path::{Path, PathBuf};
+
+use fgumi_raw_bam::flags::{
+    FIRST_SEGMENT, LAST_SEGMENT, PAIRED, QC_FAIL, REVERSE, SECONDARY, SUPPLEMENTARY, UNMAPPED,
+};
+use fgumi_raw_bam::{RawRecord, RawRecordView, RawTagsView, SamBuilder, SamTag};
+use rand::rngs::StdRng;
+use rand::{RngExt, SeedableRng};
+
+#[path = "../integration/helpers/aligner.rs"]
+mod aligner;
+
+// ---------------------------------------------------------------------------
+// Environment gating
+// ---------------------------------------------------------------------------
+
+/// Whether missing tools must fail the test rather than skip it. The CI
+/// e2e-parity job sets `FGUMI_BWA_MEM3_REQUIRE_TOOLS` so a broken environment is
+/// loud instead of a silent no-op; everywhere else the suites skip-as-pass.
+pub fn tools_required() -> bool {
+    std::env::var_os("FGUMI_BWA_MEM3_REQUIRE_TOOLS").is_some()
+}
+
+/// The reference `bwa-mem3` binary from `BWA_MEM3_BIN`, with no `PATH` fallback.
+pub fn bwa_mem3_bin_from_env() -> Option<String> {
+    std::env::var_os("BWA_MEM3_BIN").map(|bin| bin.to_string_lossy().into_owned())
+}
+
+// ---------------------------------------------------------------------------
+// Fixture reference
+// ---------------------------------------------------------------------------
+
+/// Length of every simulated read before any indel (2×150, the production shape).
+pub const READ_LEN: usize = 150;
+/// Length of the fixture reference contig.
+pub const REF_LEN: usize = 24_000;
+/// Start of the segment that is duplicated at [`REPEAT_DST`].
+const REPEAT_SRC: usize = 3_000;
+/// Length of the duplicated segment: longer than the largest simulated insert,
+/// so a whole pair can be drawn from inside it.
+const REPEAT_LEN: usize = 1_200;
+/// Where the copy of `REPEAT_SRC..REPEAT_SRC + REPEAT_LEN` is placed.
+const REPEAT_DST: usize = 15_000;
+/// Offset from a chimeric read's first locus to its second, far enough apart
+/// that bwa reports the second part as a separate (supplementary) alignment.
+const CHIMERA_OFFSET: usize = 9_000;
+/// Offset from a discordant pair's R1 locus to its R2 locus (far beyond any
+/// plausible insert size).
+const DISCORDANT_OFFSET: usize = 6_000;
+
+/// The fixture reference sequence: seeded-random bases with
+/// `REPEAT_SRC..REPEAT_SRC + REPEAT_LEN` copied to `REPEAT_DST`.
+pub fn fixture_reference_seq() -> Vec<u8> {
+    let mut rng = StdRng::seed_from_u64(0x2545_F491_4F6C_DD1D);
+    let mut seq: Vec<u8> = (0..REF_LEN).map(|_| random_base(&mut rng)).collect();
+    seq.copy_within(REPEAT_SRC..REPEAT_SRC + REPEAT_LEN, REPEAT_DST);
+    seq
+}
+
+/// A written, indexed fixture reference.
+pub struct FixtureRef {
+    /// The FASTA path (also the bwa-mem3 index prefix and `runall --ref`).
+    pub fasta: PathBuf,
+    /// The reference bases, for read simulation.
+    pub seq: Vec<u8>,
+}
+
+/// Write the fixture reference (`chr1` on one line) plus its `.fai` and `.dict`
+/// into `dir`, and build its bwa-mem3 index with `bin`. The index must come from
+/// a CLI at the vendored commit so the in-process backend can load it.
+pub fn write_fixture_reference(dir: &Path, bin: &str) -> FixtureRef {
+    let seq = fixture_reference_seq();
+    let fasta = dir.join("ref.fa");
+    let len = seq.len();
+
+    let mut file = std::fs::File::create(&fasta).expect("create reference FASTA");
+    writeln!(file, ">chr1").expect("write FASTA name");
+    file.write_all(&seq).expect("write FASTA seq");
+    writeln!(file).expect("write FASTA newline");
+    file.flush().expect("flush FASTA");
+
+    std::fs::write(dir.join("ref.fa.fai"), format!("chr1\t{len}\t6\t{len}\t{}\n", len + 1))
+        .expect("write .fai");
+    std::fs::write(
+        dir.join("ref.dict"),
+        format!("@HD\tVN:1.6\tSO:unsorted\n@SQ\tSN:chr1\tLN:{len}\n"),
+    )
+    .expect("write .dict");
+
+    aligner::build_aligner_index(&fasta, bin);
+    FixtureRef { fasta, seq }
+}
+
+// ---------------------------------------------------------------------------
+// Read simulation
+// ---------------------------------------------------------------------------
+
+/// The layout of the simulated unmapped input.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Input {
+    /// All paired (FR): R1 forward, R2 reverse-complemented.
+    Paired,
+    /// All single-end, alternating forward / reverse-complement.
+    Single,
+    /// Alternating PE and SE templates (PE at even indices), so the `-K` cut can
+    /// land between a pair's two reads (see [`mid_pair_chunk`]).
+    Mixed,
+}
+
+/// What a simulated read (or pair) is designed to exercise in the aligner.
+#[derive(Debug, Clone, Copy)]
+enum Kind {
+    Exact,
+    Substitutions,
+    Insertion,
+    Deletion,
+    Unmapped,
+    Chimeric,
+    Discordant,
+    Repeat,
+    /// A zero-length SEQ: an empty single, or a pair with one or both mates
+    /// empty. bwa-mem3 emits an empty read as unmapped (placed at its mate when
+    /// the mate maps).
+    Empty,
+}
+
+/// Every [`Kind`], cycled through per template shape.
+const KINDS: [Kind; 9] = [
+    Kind::Exact,
+    Kind::Substitutions,
+    Kind::Insertion,
+    Kind::Deletion,
+    Kind::Unmapped,
+    Kind::Chimeric,
+    Kind::Discordant,
+    Kind::Repeat,
+    Kind::Empty,
+];
+
+/// One simulated template: a name, one (SE) or two (PE) read bodies, and the
+/// `RX` / QC-fail state its unmapped records carry.
+pub struct Template {
+    pub name: String,
+    pub reads: Vec<Vec<u8>>,
+    pub paired: bool,
+    pub rx: String,
+    pub qc_fail: bool,
+}
+
+fn random_base(rng: &mut StdRng) -> u8 {
+    b"ACGT"[rng.random_range(0..4)]
+}
+
+fn random_seq(rng: &mut StdRng, len: usize) -> Vec<u8> {
+    (0..len).map(|_| random_base(rng)).collect()
+}
+
+/// Replace `n` random positions of `read` with a different base.
+fn substitute(rng: &mut StdRng, read: &mut [u8], n: usize) {
+    for _ in 0..n {
+        let at = rng.random_range(0..read.len());
+        let old = read[at];
+        read[at] = loop {
+            let b = random_base(rng);
+            if b != old {
+                break b;
+            }
+        };
+    }
+}
+
+/// A `READ_LEN` read at `start`, drawn with the given kind's mutation (for kinds
+/// that mutate a single read in place). `Unmapped`, `Chimeric`, `Discordant` and
+/// `Repeat` choose their loci before calling this, so they use it unmutated.
+fn draw_read(rng: &mut StdRng, ref_seq: &[u8], start: usize, kind: Kind) -> Vec<u8> {
+    match kind {
+        Kind::Substitutions => {
+            let mut read = ref_seq[start..start + READ_LEN].to_vec();
+            substitute(rng, &mut read, 3);
+            read
+        }
+        Kind::Insertion => {
+            let mut read = ref_seq[start..start + READ_LEN].to_vec();
+            let at = rng.random_range(60..90);
+            let ins = random_seq(rng, 2);
+            read.splice(at..at, ins);
+            read
+        }
+        Kind::Deletion => {
+            // Draw 3 extra bases and delete 3 mid-read, so the read stays READ_LEN.
+            let mut read = ref_seq[start..start + READ_LEN + 3].to_vec();
+            let at = rng.random_range(60..90);
+            read.drain(at..at + 3);
+            read
+        }
+        _ => ref_seq[start..start + READ_LEN].to_vec(),
+    }
+}
+
+/// Simulate `n` templates of the requested [`Input`] shape from `ref_seq`,
+/// cycling through every [`Kind`] for each template shape. Deterministic: the
+/// same input BAM feeds every leg of a comparison.
+pub fn simulate_templates(ref_seq: &[u8], input: Input, n: usize) -> Vec<Template> {
+    assert!(ref_seq.len() >= REF_LEN, "fixture reference is shorter than REF_LEN");
+    let mut rng = StdRng::seed_from_u64(0x9E37_79B9_7F4A_7C15);
+    let (mut pairs_seen, mut singles_seen) = (0usize, 0usize);
+    let mut templates = Vec::with_capacity(n);
+    for i in 0..n {
+        let paired = match input {
+            Input::Paired => true,
+            Input::Single => false,
+            Input::Mixed => i.is_multiple_of(2),
+        };
+        let kind = if paired {
+            KINDS[pairs_seen % KINDS.len()]
+        } else {
+            KINDS[singles_seen % KINDS.len()]
+        };
+        let reads = if paired {
+            pairs_seen += 1;
+            simulate_pair(&mut rng, ref_seq, kind)
+        } else {
+            singles_seen += 1;
+            let mut read = simulate_single(&mut rng, ref_seq, kind);
+            if singles_seen.is_multiple_of(2) {
+                read = fgumi_dna::reverse_complement(&read);
+            }
+            vec![read]
+        };
+        let rx = String::from_utf8(random_seq(&mut rng, 8)).expect("ACGT is UTF-8");
+        let name = if paired { format!("pe{i}") } else { format!("se{i}") };
+        templates.push(Template { name, reads, paired, rx, qc_fail: i % 7 == 3 });
+    }
+    templates
+}
+
+fn simulate_pair(rng: &mut StdRng, ref_seq: &[u8], kind: Kind) -> Vec<Vec<u8>> {
+    let insert = READ_LEN + 50 + rng.random_range(0..150);
+    match kind {
+        Kind::Unmapped => vec![random_seq(rng, READ_LEN), random_seq(rng, READ_LEN)],
+        Kind::Empty => {
+            let start = rng.random_range(0..REF_LEN - insert);
+            let r1 = ref_seq[start..start + READ_LEN].to_vec();
+            let r2 =
+                fgumi_dna::reverse_complement(&ref_seq[start + insert - READ_LEN..start + insert]);
+            match rng.random_range(0..3u8) {
+                0 => vec![Vec::new(), r2],
+                1 => vec![r1, Vec::new()],
+                _ => vec![Vec::new(), Vec::new()],
+            }
+        }
+        Kind::Repeat => {
+            let start = REPEAT_SRC + rng.random_range(0..=REPEAT_LEN - insert);
+            let r1 = ref_seq[start..start + READ_LEN].to_vec();
+            let r2 =
+                fgumi_dna::reverse_complement(&ref_seq[start + insert - READ_LEN..start + insert]);
+            vec![r1, r2]
+        }
+        Kind::Chimeric => {
+            let a = rng.random_range(0..REF_LEN - CHIMERA_OFFSET - READ_LEN);
+            let b = a + CHIMERA_OFFSET;
+            let mut r1 = ref_seq[a..a + 80].to_vec();
+            r1.extend_from_slice(&ref_seq[b..b + 70]);
+            let r2 = fgumi_dna::reverse_complement(&ref_seq[a + insert - READ_LEN..a + insert]);
+            vec![r1, r2]
+        }
+        Kind::Discordant => {
+            let a = rng.random_range(0..REF_LEN - DISCORDANT_OFFSET - READ_LEN);
+            let b = a + DISCORDANT_OFFSET;
+            let r1 = ref_seq[a..a + READ_LEN].to_vec();
+            let r2 = fgumi_dna::reverse_complement(&ref_seq[b..b + READ_LEN]);
+            vec![r1, r2]
+        }
+        _ => {
+            // +3 leaves room for the Deletion kind's extra bases.
+            let start = rng.random_range(0..REF_LEN - insert - 3);
+            let r1 = draw_read(rng, ref_seq, start, kind);
+            let r2_start = start + insert - READ_LEN;
+            let r2 = fgumi_dna::reverse_complement(&draw_read(rng, ref_seq, r2_start, kind));
+            vec![r1, r2]
+        }
+    }
+}
+
+fn simulate_single(rng: &mut StdRng, ref_seq: &[u8], kind: Kind) -> Vec<u8> {
+    match kind {
+        Kind::Unmapped => random_seq(rng, READ_LEN),
+        Kind::Empty => Vec::new(),
+        Kind::Repeat => {
+            let start = REPEAT_SRC + rng.random_range(0..=REPEAT_LEN - READ_LEN);
+            ref_seq[start..start + READ_LEN].to_vec()
+        }
+        Kind::Chimeric => {
+            let a = rng.random_range(0..REF_LEN - CHIMERA_OFFSET - READ_LEN);
+            let mut read = ref_seq[a..a + 80].to_vec();
+            read.extend_from_slice(&ref_seq[a + CHIMERA_OFFSET..a + CHIMERA_OFFSET + 70]);
+            read
+        }
+        // A single read has no mate to be discordant with; draw it exact.
+        _ => {
+            let start = rng.random_range(0..REF_LEN - READ_LEN - 3);
+            draw_read(rng, ref_seq, start, kind)
+        }
+    }
+}
+
+/// Write `templates` to a queryname-grouped unmapped BAM (mates adjacent), each
+/// record carrying its template's `RX` and, for QC-fail templates, the QC-fail
+/// flag — the shape `runall --start-from align` consumes.
+pub fn write_unmapped_bam(path: &Path, templates: &[Template]) {
+    use noodles::sam::alignment::io::Write as _;
+
+    let header = noodles::sam::Header::default();
+    let mut records: Vec<RawRecord> = Vec::new();
+    for template in templates {
+        for (segment_idx, seq) in template.reads.iter().enumerate() {
+            let mut flags = if template.paired {
+                let segment = if segment_idx == 0 { FIRST_SEGMENT } else { LAST_SEGMENT };
+                UNMAPPED | PAIRED | segment
+            } else {
+                UNMAPPED
+            };
+            if template.qc_fail {
+                flags |= QC_FAIL;
+            }
+            let quals = vec![30u8; seq.len()];
+            let mut b = SamBuilder::new();
+            b.read_name(template.name.as_bytes())
+                .flags(flags)
+                .sequence(seq)
+                .qualities(&quals)
+                .add_string_tag(SamTag::RX, template.rx.as_bytes());
+            records.push(b.build());
+        }
+    }
+
+    let mut writer =
+        noodles::bam::io::Writer::new(std::fs::File::create(path).expect("create unmapped BAM"));
+    writer.write_header(&header).expect("write unmapped header");
+    for record in &records {
+        let buf = fgumi_raw_bam::raw_record_to_record_buf(record, &header)
+            .expect("raw_record_to_record_buf");
+        writer.write_alignment_record(&header, &buf).expect("write unmapped record");
+    }
+    writer.try_finish().expect("finish unmapped BAM");
+}
+
+/// A forced mid-pair `-K` cut: the `--aligner::chunk-size` that produces it and
+/// the paired template whose two reads it separates.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MidPairCut {
+    pub chunk_size: u64,
+    pub template: String,
+}
+
+/// A `--aligner::chunk-size` that makes bwa's `-K` cut land between a pair's two
+/// reads: the cumulative bases through the first R1 that sits at an even running
+/// read count. bwa cuts a chunk at the first read where the bases reach `-K`
+/// **and** the read count is even (`bseq_read`), so with this value the first
+/// chunk ends on that R1 and its R2 opens the next chunk — bwa-mem3 then aligns
+/// the two reads as unpaired singles. Bases only grow along the input, so that R1
+/// is the first read to reach the cut and the split pair is exactly
+/// [`MidPairCut::template`]. `None` when no such R1 exists (paired-only input
+/// keeps every pair inside one chunk).
+pub fn mid_pair_chunk(templates: &[Template]) -> Option<MidPairCut> {
+    let (mut n_reads, mut bases) = (0u64, 0u64);
+    for template in templates {
+        for (segment_idx, read) in template.reads.iter().enumerate() {
+            n_reads += 1;
+            bases += u64::try_from(read.len()).expect("read length fits u64");
+            if template.paired && segment_idx == 0 && n_reads.is_multiple_of(2) {
+                return Some(MidPairCut { chunk_size: bases, template: template.name.clone() });
+            }
+        }
+    }
+    None
+}
+
+// ---------------------------------------------------------------------------
+// BAM decoding
+// ---------------------------------------------------------------------------
+
+/// A decoded BAM: header text, the raw reference list, and each record's body
+/// (the bytes after `block_size`).
+pub struct Bam {
+    pub header_text: String,
+    pub refs: Vec<u8>,
+    pub records: Vec<Vec<u8>>,
+}
+
+fn le_i32(bytes: &[u8], at: usize) -> usize {
+    let v = i32::from_le_bytes(bytes[at..at + 4].try_into().expect("4 bytes"));
+    usize::try_from(v).expect("BAM length field is non-negative")
+}
+
+/// Decompress and split a BAM into header text, reference list and records.
+/// BGZF block boundaries differ between writers even for identical content, so
+/// the decompressed stream — not the file bytes — is what is compared.
+pub fn read_bam(path: &Path) -> Bam {
+    let file = std::fs::File::open(path).unwrap_or_else(|e| panic!("open {}: {e}", path.display()));
+    let mut reader = noodles::bgzf::io::Reader::new(std::io::BufReader::new(file));
+    let mut raw = Vec::new();
+    std::io::Read::read_to_end(&mut reader, &mut raw)
+        .unwrap_or_else(|e| panic!("decompress {}: {e}", path.display()));
+    assert!(raw.len() >= 8 && &raw[0..4] == b"BAM\x01", "{} is not a BAM", path.display());
+
+    let text_end = 8 + le_i32(&raw, 4);
+    let header_text = String::from_utf8_lossy(&raw[8..text_end]).into_owned();
+    let mut at = text_end;
+    let n_ref = le_i32(&raw, at);
+    at += 4;
+    for _ in 0..n_ref {
+        at += 4 + le_i32(&raw, at); // l_name + name
+        at += 4; // l_ref
+    }
+    let refs = raw[text_end..at].to_vec();
+
+    let mut records = Vec::new();
+    while at + 4 <= raw.len() {
+        let body = at + 4;
+        let end = body + le_i32(&raw, at);
+        records.push(raw[body..end].to_vec());
+        at = end;
+    }
+    Bam { header_text, refs, records }
+}
+
+/// A record body's FLAG.
+pub fn flags(body: &[u8]) -> u16 {
+    u16::from_le_bytes(body[14..16].try_into().expect("2 bytes"))
+}
+
+/// A record body's read name (without the NUL).
+pub fn name(body: &[u8]) -> &[u8] {
+    let l_read_name = usize::from(body[8]);
+    &body[32..32 + l_read_name - 1]
+}
+
+/// Whether a record is a primary alignment (neither secondary nor supplementary).
+pub fn is_primary(body: &[u8]) -> bool {
+    flags(body) & (SECONDARY | SUPPLEMENTARY) == 0
+}
+
+/// The value bytes of a string tag on a record, if present.
+pub fn string_tag(body: &[u8], tag: SamTag) -> Option<&[u8]> {
+    let tag: [u8; 2] = tag.into();
+    RawTagsView::new(fgumi_raw_bam::aux_data_slice(body))
+        .iter()
+        .find(|entry| entry.tag == tag)
+        .map(|entry| entry.value_bytes.strip_suffix(b"\0").unwrap_or(entry.value_bytes))
+}
+
+// ---------------------------------------------------------------------------
+// Normalized comparison
+// ---------------------------------------------------------------------------
+
+/// Whether a normalization sorts each record's optional tags.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TagOrder {
+    /// Keep the emitted order (runs of one backend must agree exactly).
+    Keep,
+    /// Compare tags as a set (the two backends emit tags in different orders).
+    Sort,
+}
+
+/// One aux tag: identifier, BAM type byte (so an integer's width is compared),
+/// and raw value bytes.
+pub type AuxEntry = ([u8; 2], u8, Vec<u8>);
+
+/// A record split into its fixed/core bytes (everything before the aux data)
+/// and its aux entries.
+#[derive(Debug, PartialEq, Eq)]
+pub struct NormRecord {
+    pub core: Vec<u8>,
+    pub aux: Vec<AuxEntry>,
+}
+
+/// A BAM normalized for comparison; see [`normalize`].
+pub struct NormBam {
+    pub header: String,
+    pub refs: Vec<u8>,
+    pub records: Vec<NormRecord>,
+}
+
+/// Normalize `bam` for comparison. Exactly these differences are removed, as
+/// they carry no alignment meaning:
+///
+/// 1. the `CL:` field of every `@PG` header line (the command line differs
+///    between presets and records a per-run output path);
+/// 2. a git dev suffix on `@PG` `VN:` (see [`without_git_suffix`]): a CLI built
+///    from a git checkout reports e.g. `0.12.0-ea58288`, the vendored build
+///    `0.12.0`; the release version is still compared;
+/// 3. with [`TagOrder::Sort`], the order of each record's optional tags.
+///
+/// Everything else — the rest of the header, the reference list, every core
+/// field and every tag's identifier, type (including integer width) and value —
+/// is compared byte for byte.
+pub fn normalize(bam: &Bam, order: TagOrder) -> NormBam {
+    let header = bam
+        .header_text
+        .lines()
+        .map(|line| {
+            if !line.starts_with("@PG") {
+                return line.to_owned();
+            }
+            line.split('\t')
+                .filter(|f| !f.starts_with("CL:"))
+                // `without_git_suffix` returns a prefix of `vn`, so keep that
+                // much of the field after the `VN:` tag.
+                .map(|f| {
+                    f.strip_prefix("VN:")
+                        .map_or(f, |vn| &f[.."VN:".len() + without_git_suffix(vn).len()])
+                })
+                .collect::<Vec<_>>()
+                .join("\t")
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+    let records = bam
+        .records
+        .iter()
+        .map(|body| {
+            let offset = fgumi_raw_bam::aux_data_offset_from_record(body)
+                .filter(|&o| o <= body.len())
+                .expect("record long enough to hold its aux offset");
+            let mut aux: Vec<AuxEntry> = RawTagsView::new(&body[offset..])
+                .iter()
+                .map(|e| (e.tag, e.type_byte, e.value_bytes.to_vec()))
+                .collect();
+            if order == TagOrder::Sort {
+                aux.sort();
+            }
+            NormRecord { core: body[..offset].to_vec(), aux }
+        })
+        .collect();
+    NormBam { header, refs: bam.refs.clone(), records }
+}
+
+/// `version` without the git dev suffix bwa-mem3's `scripts/version.sh` appends
+/// off the release tag: a trailing `-dirty`, then a trailing `-<7..=40 hex>`
+/// commit.
+pub fn without_git_suffix(version: &str) -> &str {
+    let version = version.strip_suffix("-dirty").unwrap_or(version);
+    match version.rsplit_once('-') {
+        Some((base, sha))
+            if (7..=40).contains(&sha.len()) && sha.bytes().all(|b| b.is_ascii_hexdigit()) =>
+        {
+            base
+        }
+        _ => version,
+    }
+}
+
+/// Assert two normalized BAMs are identical, naming the first differing record
+/// (by index and read name) rather than dumping both files.
+pub fn assert_same_bam(expected: &NormBam, actual: &NormBam, label: &str) {
+    assert_eq!(expected.header, actual.header, "{label}: headers differ");
+    assert_eq!(expected.refs, actual.refs, "{label}: reference lists differ");
+    let first_diff = expected.records.iter().zip(&actual.records).position(|(e, a)| e != a);
+    if let Some(i) = first_diff {
+        let (e, a) = (&expected.records[i], &actual.records[i]);
+        panic!(
+            "{label}: record {i} differs ('{}' vs '{}'):\n  expected {e:?}\n  actual   {a:?}",
+            String::from_utf8_lossy(name(&e.core)),
+            String::from_utf8_lossy(name(&a.core)),
+        );
+    }
+    assert_eq!(
+        expected.records.len(),
+        actual.records.len(),
+        "{label}: record counts differ (all shared records match)"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Fixture sanity + independent expectations
+// ---------------------------------------------------------------------------
+
+/// Counts of the alignment shapes the fixture is designed to produce.
+#[derive(Debug, Default)]
+pub struct Coverage {
+    pub mapped: usize,
+    pub unmapped: usize,
+    pub supplementary: usize,
+    pub xa_tagged: usize,
+}
+
+/// Count the alignment shapes in `bam`.
+pub fn coverage(bam: &Bam) -> Coverage {
+    let xa = SamTag::new(b'X', b'A');
+    let mut c = Coverage::default();
+    for body in &bam.records {
+        let f = flags(body);
+        if f & UNMAPPED == 0 {
+            c.mapped += 1;
+        } else {
+            c.unmapped += 1;
+        }
+        if f & SUPPLEMENTARY != 0 {
+            c.supplementary += 1;
+        }
+        if string_tag(body, xa).is_some() {
+            c.xa_tagged += 1;
+        }
+    }
+    c
+}
+
+/// Assert the output holds every alignment shape the fixture is built to
+/// produce — mapped, unmapped, supplementary and `XA`-tagged records — so the
+/// comparison can never silently degrade into comparing trivial output.
+pub fn assert_fixture_coverage(bam: &Bam, label: &str) {
+    let c = coverage(bam);
+    assert!(
+        c.mapped > 0 && c.unmapped > 0 && c.supplementary > 0 && c.xa_tagged > 0,
+        "{label}: fixture no longer exercises every alignment shape: {c:?}"
+    );
+}
+
+/// Assert the independent contract of the zipper merge against the input: every
+/// template yields exactly one primary record per input read, and every primary
+/// record carries its template's `RX` and, iff the template was QC-fail, the
+/// QC-fail flag. This holds for both halves of a mid-pair split too.
+pub fn assert_tags_transferred(bam: &Bam, templates: &[Template], label: &str) {
+    let by_name: BTreeMap<&[u8], &Template> =
+        templates.iter().map(|t| (t.name.as_bytes(), t)).collect();
+    let mut primaries: BTreeMap<&[u8], usize> = BTreeMap::new();
+    for body in bam.records.iter().filter(|b| is_primary(b)) {
+        let read_name = name(body);
+        let shown = String::from_utf8_lossy(read_name);
+        let template = by_name.get(read_name).unwrap_or_else(|| {
+            panic!("{label}: output record '{shown}' matches no input template")
+        });
+        assert_eq!(
+            string_tag(body, SamTag::RX),
+            Some(template.rx.as_bytes()),
+            "{label}: primary record of '{shown}' lost (or changed) its RX tag"
+        );
+        assert_eq!(
+            flags(body) & QC_FAIL != 0,
+            template.qc_fail,
+            "{label}: primary record of '{shown}' has the wrong QC-fail flag"
+        );
+        *primaries.entry(read_name).or_default() += 1;
+    }
+    for template in templates {
+        assert_eq!(
+            primaries.get(template.name.as_bytes()).copied().unwrap_or(0),
+            template.reads.len(),
+            "{label}: template '{}' should yield one primary record per input read",
+            template.name
+        );
+    }
+}
+
+/// Assert every input read survives the merge as exactly one primary record of
+/// its own template: the multiset of each template's primary `SEQ`s (reverse
+/// complemented back for reverse-strand records) equals its input reads. A merge
+/// that paired a mapped record with the wrong template, duplicated one read of a
+/// pair, or dropped the other fails here even when the tags still match.
+pub fn assert_reads_preserved(bam: &Bam, templates: &[Template], label: &str) {
+    let mut seqs: BTreeMap<&[u8], Vec<Vec<u8>>> = BTreeMap::new();
+    for body in bam.records.iter().filter(|b| is_primary(b)) {
+        let mut seq = RawRecordView::new(body).sequence_vec();
+        if flags(body) & REVERSE != 0 {
+            seq = fgumi_dna::reverse_complement(&seq);
+        }
+        seqs.entry(name(body)).or_default().push(seq);
+    }
+    for template in templates {
+        let mut actual = seqs.remove(template.name.as_bytes()).unwrap_or_default();
+        actual.sort();
+        let mut expected = template.reads.clone();
+        expected.sort();
+        assert!(
+            actual == expected,
+            "{label}: template '{}' primary records do not carry its input reads",
+            template.name
+        );
+    }
+}
+
+/// Names of paired templates that bwa aligned as a mid-pair split: two or more
+/// primary records under one name, none flagged paired.
+pub fn split_names(bam: &Bam) -> BTreeSet<Vec<u8>> {
+    let mut by_name: BTreeMap<&[u8], (usize, bool)> = BTreeMap::new();
+    for body in bam.records.iter().filter(|b| is_primary(b)) {
+        let entry = by_name.entry(name(body)).or_default();
+        entry.0 += 1;
+        entry.1 |= flags(body) & PAIRED != 0;
+    }
+    by_name
+        .into_iter()
+        .filter(|(_, (n, any_paired))| *n >= 2 && !any_paired)
+        .map(|(n, _)| n.to_vec())
+        .collect()
+}
diff --git a/tests/align_subprocess_split_parity.rs b/tests/align_subprocess_split_parity.rs
new file mode 100644
index 000000000..3f8108289
--- /dev/null
+++ b/tests/align_subprocess_split_parity.rs
@@ -0,0 +1,179 @@
+#![deny(unsafe_code)]
+
+//! Guard for the subprocess align+merge path.
+//!
+//! The subprocess align path is a `SubprocessAlignStep` (emits `ZipperBatch`)
+//! plus a shared, `Parallel` `MergeAlignedStep`, behind an `AlignBackend` trait
+//! (formerly a single `AlignAndMergeStep`). This test runs `runall --start-from
+//! align --stop-after zipper --aligner::preset bwa-mem3` over the shared
+//! align-parity fixture (see `align_common`: substitutions, indels, unmapped,
+//! chimeric, discordant and multi-mapping reads, each input record carrying an
+//! `RX` tag, some QC-fail) and asserts:
+//!
+//! - the output holds every alignment shape the fixture is built to produce, so
+//!   the comparisons below never run on trivial output;
+//! - an independent expectation against the input, not just self-consistency:
+//!   every input read yields exactly one primary record carrying its template's
+//!   `RX` and QC-fail state;
+//! - the decompressed records (with the `@PG` `CL` field stripped) are identical
+//!   across `--threads` values and across a re-run. The aligner output is
+//!   `-t`-invariant when `-K` is fixed, and the merge runs on a `Parallel` step
+//!   whose `ByItemOrdinal` output restores input order, so a lost ordinal,
+//!   mis-paired half or dropped batch shows up as a divergence;
+//! - with mixed single/paired input and a `-K` chosen to cut between a pair's
+//!   reads, the targeted pair is the one that splits, both halves keep their `RX`
+//!   and QC-fail state and their own reads, and the output is byte-identical
+//!   across `--threads` at that `-K`.
+//!
+//! ## Environment gating (skip-as-pass, unless tools are required)
+//!
+//! The test needs a real `bwa-mem3`: `BWA_MEM3_BIN` if set, else `bwa-mem3` on
+//! `PATH`. It indexes the fixture reference and is the aligner the preset runs.
+//! When neither is available the test prints a skip line and returns (a pass);
+//! setting `FGUMI_BWA_MEM3_REQUIRE_TOOLS` makes that a hard failure, so the CI
+//! e2e-parity job cannot silently skip it.
+
+mod align_common;
+
+use std::path::PathBuf;
+use std::process::Command;
+
+use align_common::{
+    Bam, Input, TagOrder, Template, assert_fixture_coverage, assert_reads_preserved,
+    assert_same_bam, assert_tags_transferred, bwa_mem3_bin_from_env, mid_pair_chunk, normalize,
+    read_bam, simulate_templates, split_names, tools_required, write_fixture_reference,
+    write_unmapped_bam,
+};
+use rstest::rstest;
+use tempfile::TempDir;
+
+/// Templates simulated per input.
+const N_TEMPLATES: usize = 64;
+
+/// The `bwa-mem3` to use: `BWA_MEM3_BIN`, else `bwa-mem3` on `PATH`.
+fn bwa_mem3_bin() -> Option<String> {
+    bwa_mem3_bin_from_env()
+        .or_else(|| which::which("bwa-mem3").ok().map(|p| p.to_string_lossy().into_owned()))
+}
+
+/// Resolve the `bwa-mem3` binary, or skip (panic under
+/// `FGUMI_BWA_MEM3_REQUIRE_TOOLS`) with a line naming the case.
+macro_rules! bin_or_skip {
+    ($label:expr) => {
+        match bwa_mem3_bin() {
+            Some(bin) => bin,
+            None => {
+                let reason = "no bwa-mem3 (set BWA_MEM3_BIN or put bwa-mem3 on PATH)";
+                assert!(!tools_required(), "{}: required tool missing: {reason}", $label);
+                eprintln!("skip {}: {reason}", $label);
+                return;
+            }
+        }
+    };
+}
+
+/// A prepared reference + unmapped-BAM fixture for the subprocess runs.
+struct TestEnv {
+    dir: TempDir,
+    bin: String,
+    reference: PathBuf,
+    unmapped: PathBuf,
+    templates: Vec<Template>,
+}
+
+impl TestEnv {
+    /// Build and index the fixture reference with `bin`, and write the unmapped
+    /// input BAM of `input`-shaped templates drawn from it.
+    fn setup(bin: String, input: Input) -> Self {
+        let dir = TempDir::new().expect("create temp dir");
+        let fixture = write_fixture_reference(dir.path(), &bin);
+        let templates = simulate_templates(&fixture.seq, input, N_TEMPLATES);
+        let unmapped = dir.path().join("unmapped.bam");
+        write_unmapped_bam(&unmapped, &templates);
+        Self { bin, reference: fixture.fasta, unmapped, templates, dir }
+    }
+
+    /// Runs `runall --start-from align --stop-after zipper --aligner::preset
+    /// bwa-mem3` at `threads` (and `--aligner::chunk-size` when given) and returns
+    /// the decoded output.
+    fn run(&self, threads: usize, chunk_size: Option<u64>) -> Bam {
+        let out = self.dir.path().join(format!("aligned.t{threads}.bam"));
+        let mut cmd = Command::new(env!("CARGO_BIN_EXE_fgumi"));
+        cmd.arg("runall")
+            .args(["--start-from", "align"])
+            .args(["--stop-after", "zipper"])
+            .args(["--aligner::preset", "bwa-mem3"])
+            .arg("--aligner-bin")
+            .arg(&self.bin)
+            .args(["--threads", &threads.to_string()])
+            .arg("--input")
+            .arg(&self.unmapped)
+            .arg("--ref")
+            .arg(&self.reference)
+            .arg("--output")
+            .arg(&out);
+        if let Some(k) = chunk_size {
+            cmd.args(["--aligner::chunk-size", &k.to_string()]);
+        }
+        let status = cmd.status().expect("run `fgumi runall`");
+        assert!(status.success(), "`fgumi runall` (threads={threads}) failed with status {status}");
+        read_bam(&out)
+    }
+}
+
+/// The subprocess `bwa-mem3` align path must merge every read with its own tags
+/// and produce byte-identical output for every `--threads`, and the same bytes
+/// on a re-run.
+#[rstest]
+#[case::t1(1)]
+#[case::t2(2)]
+#[case::t8(8)]
+fn subprocess_align_output_is_thread_invariant(#[case] threads: usize) {
+    let label = format!("subprocess_align_output_is_thread_invariant[threads={threads}]");
+    let bin = bin_or_skip!(label);
+    let env = TestEnv::setup(bin, Input::Paired);
+    let out = env.run(threads, None);
+
+    assert_fixture_coverage(&out, &label);
+    assert_tags_transferred(&out, &env.templates, &label);
+    assert_reads_preserved(&out, &env.templates, &label);
+    let out = normalize(&out, TagOrder::Keep);
+    assert_same_bam(
+        &normalize(&env.run(1, None), TagOrder::Keep),
+        &out,
+        &format!("{label}: diverged from threads=1"),
+    );
+    assert_same_bam(
+        &normalize(&env.run(threads, None), TagOrder::Keep),
+        &out,
+        &format!("{label}: not stable across a re-run"),
+    );
+}
+
+/// With mixed single/paired input and a `-K` that cuts between a pair's two
+/// reads, bwa-mem3 aligns that pair as two unpaired reads. The pair the cut
+/// targets must be the one that splits, both halves must keep the pair's `RX`
+/// and QC-fail state and their own reads after the merge, and the output must be
+/// byte-identical across `--threads` at the same `-K`, since the split path is
+/// where the merge's reordering changes.
+#[test]
+fn subprocess_mid_pair_split_keeps_unmapped_tags() {
+    let label = "subprocess_mid_pair_split_keeps_unmapped_tags";
+    let bin = bin_or_skip!(label);
+    let env = TestEnv::setup(bin, Input::Mixed);
+    let cut = mid_pair_chunk(&env.templates).expect("mixed input has a mid-pair cut point");
+    let out = env.run(1, Some(cut.chunk_size));
+
+    assert!(
+        split_names(&out).contains(cut.template.as_bytes()),
+        "{label}: the forced mid-pair -K cut did not split its target pair '{}'",
+        cut.template
+    );
+    assert_tags_transferred(&out, &env.templates, label);
+    assert_reads_preserved(&out, &env.templates, label);
+    assert_same_bam(
+        &normalize(&out, TagOrder::Keep),
+        &normalize(&env.run(8, Some(cut.chunk_size)), TagOrder::Keep),
+        &format!("{label}: threads=8 diverged from threads=1"),
+    );
+}

From 57aaadee01d5f3fe571507548678ae97adc48f9a Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Sun, 27 Sep 2026 04:38:07 -0700
Subject: [PATCH 2/3] perf(runall/align): emit uncompressed BAM from the
 bwa-mem3 preset; keep mimalloc from purging

- The bwa-mem3 preset now runs `bwa-mem3 mem --bam=0`, so fgumi's single
  reader thread takes records zero-copy instead of parsing SAM text, which
  at 32 threads kept bwa-mem3 blocked on its output (a fused extract ->
  correct -> align ran 36% faster). The merged records are identical.
- With an align stage, runall sets mimalloc's purge delay to -1 (never
  return freed pages to the OS) unless MIMALLOC_PURGE_DELAY or its legacy
  name is set (any case, as mimalloc matches them), and passes the same
  setting to the aligner child through its environment. The per-batch
  buffer churn otherwise costs hundreds of thousands of page faults. The
  setting is process-wide, so later stages keep freed pages too;
  measured end to end (extract through simplex consensus, 1M pairs, 32
  threads, with and without a spilling sort) it is ~4% faster for ~0.4 GB
  more peak RSS. The setter lives next to the existing mimalloc FFI in
  fgumi-sort's memory_probe (CLAUDE.md allowlist updated); the option
  index is pinned by a test against mimalloc v3's 1000 ms default.
---
 CLAUDE.md                                  |  23 ++++-
 crates/fgumi-sort/src/lib.rs               |   4 +
 crates/fgumi-sort/src/memory_probe.rs      |  48 +++++++++-
 src/lib/aligner.rs                         | 100 ++++++++++++++++++---
 src/lib/pipeline/steps/align/mod.rs        |  56 +++++++++++-
 src/lib/pipeline/steps/align/subprocess.rs |  92 +++++++++++++++++++
 6 files changed, 307 insertions(+), 16 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index ddcab8e99..88c1c9e27 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -138,10 +138,25 @@ any new `unsafe` block requires updating this section with a written justificati
 The following external FFI calls are approved because they back core infrastructure:
 
 - **`libmimalloc_sys`** (`crates/fgumi-sort/src/memory_probe.rs`) — mimalloc is the configured
-  global allocator. The FFI wrappers (`force_mi_collect`, `process_rss_bytes`, and the
-  `memory-debug`-gated `print_mi_stats` calling `mi_stats_print_out`) are isolated to
-  a single `#[allow(unsafe_code)]` sub-module. mimalloc synchronizes these calls
-  internally, so they are safe to invoke concurrently.
+  global allocator. The FFI wrappers (`force_mi_collect`, `process_rss_bytes`, the
+  `memory-debug`-gated `print_mi_stats` calling `mi_stats_print_out`, and
+  `retain_freed_memory` / `mi_purge_delay_ms` calling `mi_option_set` /
+  `mi_option_get`) are isolated to a single `#[allow(unsafe_code)]` sub-module.
+  mimalloc synchronizes these calls internally, so they are safe to invoke
+  concurrently. `retain_freed_memory` sets mimalloc's purge delay to -1 (never
+  return freed pages to the OS); the align stage calls it at wiring (via
+  `retain_freed_memory_unless_user_set`) unless `MIMALLOC_PURGE_DELAY` is set,
+  because its per-batch buffer churn otherwise costs hundreds of thousands of page
+  faults. The setting is process-wide and never restored, so it also turns
+  fgumi-sort's `force_mi_collect()` into a no-op for later `runall` stages; measured
+  end to end (extract through consensus, 1M pairs, 32 threads) it is still ~4%
+  faster, sort spills included, for ~0.4 GB more peak RSS.
+  The subprocess route also passes `MIMALLOC_PURGE_DELAY=-1` to the aligner child
+  through its environment, which needs no FFI. A safe alternative does not exist:
+  mimalloc reads its environment only at process start, and `libmimalloc-sys`
+  exports no safe setter.
+  The option index (15) is not exported as a constant; a unit test pins it against
+  the linked mimalloc v3's 1000 ms default.
 - **`mach2`** (`crates/fgumi-sort/src/memory_probe.rs`, macOS only) — `task_info(TASK_VM_INFO)`
   is the only way to read `phys_footprint` (the RSS metric mimalloc reports accurately).
   Isolated to the same sub-module as the mimalloc FFI.
diff --git a/crates/fgumi-sort/src/lib.rs b/crates/fgumi-sort/src/lib.rs
index 7231606bd..d9f8f20a2 100644
--- a/crates/fgumi-sort/src/lib.rs
+++ b/crates/fgumi-sort/src/lib.rs
@@ -101,6 +101,10 @@ pub use memory_probe::print_mi_stats;
 /// pipeline thread-telemetry sampler, which needs an RSS reading on every tick
 /// regardless of whether that feature is enabled.
 pub use memory_probe::process_rss_bytes;
+/// Tune mimalloc to keep freed pages instead of returning them to the OS, and
+/// read the setting back. Re-exported for the align stage, which frees and
+/// reallocates large per-batch buffers on every pool thread.
+pub use memory_probe::{mi_purge_delay_ms, retain_freed_memory};
 /// Background read-ahead record reader, re-exported for `fgumi compare bams`,
 /// which reads two inputs concurrently and needs each decode off the main thread.
 pub use read_ahead::RawReadAheadReader;
diff --git a/crates/fgumi-sort/src/memory_probe.rs b/crates/fgumi-sort/src/memory_probe.rs
index df9ca88e5..30952d8b7 100644
--- a/crates/fgumi-sort/src/memory_probe.rs
+++ b/crates/fgumi-sort/src/memory_probe.rs
@@ -45,7 +45,9 @@ use log::{Level, debug, log_enabled};
 #[allow(unused_imports)]
 // consumed by main fgumi via the crate-root re-export
 pub use platform_ffi::print_mi_stats;
-pub use platform_ffi::{force_mi_collect, process_rss_bytes};
+pub use platform_ffi::{
+    force_mi_collect, mi_purge_delay_ms, process_rss_bytes, retain_freed_memory,
+};
 
 /// Log target for the memory probe.
 ///
@@ -73,6 +75,33 @@ mod platform_ffi {
         }
     }
 
+    /// mimalloc's `mi_option_purge_delay`. `libmimalloc-sys` does not export it
+    /// as a constant, so this is its position in `mi_option_t`, which is 15 in
+    /// both the v2 and v3 `mimalloc.h` enums (deprecated slots keep their
+    /// places). `mi_purge_delay_ms_matches_mimalloc_default` pins it against the
+    /// linked mimalloc v3's default of 1000 ms.
+    const MI_OPTION_PURGE_DELAY: libmimalloc_sys::mi_option_t = 15;
+
+    /// Stop mimalloc returning freed pages to the OS (`purge_delay = -1`), so a
+    /// page that is freed and soon reused is not decommitted and faulted back
+    /// in. Trades a higher peak RSS for fewer page faults and less system time.
+    pub fn retain_freed_memory() {
+        // SAFETY: mi_option_set only stores the option value in mimalloc's
+        // option table; mimalloc reads it on each purge, so setting it after
+        // start-up is supported, and the option index is fixed (see above).
+        unsafe {
+            libmimalloc_sys::mi_option_set(MI_OPTION_PURGE_DELAY, -1);
+        }
+    }
+
+    /// mimalloc's current purge delay in milliseconds (`-1`: never purge).
+    #[must_use]
+    pub fn mi_purge_delay_ms() -> i64 {
+        // SAFETY: mi_option_get only reads mimalloc's option table.
+        #[allow(clippy::useless_conversion)] // `c_long` is `i32` on Windows
+        i64::from(unsafe { libmimalloc_sys::mi_option_get(MI_OPTION_PURGE_DELAY) })
+    }
+
     /// Print mimalloc allocator statistics to stderr via the default output handler.
     ///
     /// `mi_stats_print_out(None, null_mut())` uses mimalloc's internal synchronization,
@@ -533,6 +562,23 @@ impl Default for MergeProbe {
 mod tests {
     use super::*;
 
+    /// Pins [`platform_ffi`]'s purge-delay option index: the linked mimalloc v3
+    /// defaults `mi_option_purge_delay` to 1000 ms (v2 used 10 ms), and retaining
+    /// freed memory sets it to -1. Skipped when the environment overrides it.
+    #[test]
+    fn mi_purge_delay_ms_matches_mimalloc_default() {
+        // mimalloc matches its option names case-insensitively.
+        if std::env::vars_os().any(|(name, _)| {
+            name.eq_ignore_ascii_case("MIMALLOC_PURGE_DELAY")
+                || name.eq_ignore_ascii_case("MIMALLOC_RESET_DELAY")
+        }) {
+            return;
+        }
+        assert_eq!(mi_purge_delay_ms(), 1000);
+        retain_freed_memory();
+        assert_eq!(mi_purge_delay_ms(), -1);
+    }
+
     #[test]
     fn test_fmt_bytes_units() {
         assert_eq!(fmt_bytes(0), "0 B");
diff --git a/src/lib/aligner.rs b/src/lib/aligner.rs
index 3095757e0..a66865544 100644
--- a/src/lib/aligner.rs
+++ b/src/lib/aligner.rs
@@ -74,6 +74,31 @@ pub struct AlignerProcess {
     stderr_thread: Option<JoinHandle<Vec<String>>>,
 }
 
+/// The mimalloc option environment variables (`MIMALLOC_PURGE_DELAY` and its
+/// legacy name) a user can set to choose the purge delay themselves.
+const MIMALLOC_PURGE_ENV: [&str; 2] = ["MIMALLOC_PURGE_DELAY", "MIMALLOC_RESET_DELAY"];
+
+/// Whether the user set mimalloc's purge delay in the environment.
+pub(crate) fn user_set_mimalloc_purge() -> bool {
+    names_set_mimalloc_purge(std::env::vars_os().map(|(name, _)| name))
+}
+
+/// Whether `names` (environment variable names) include either
+/// [`MIMALLOC_PURGE_ENV`] name. The comparison ignores ASCII case because
+/// mimalloc's own lookup does, so `mimalloc_purge_delay=250` is the user's
+/// choice too. Any value counts, including one mimalloc cannot parse: that one
+/// is mimalloc's to reject, not ours to replace.
+fn names_set_mimalloc_purge<I, S>(names: I) -> bool
+where
+    I: IntoIterator<Item = S>,
+    S: AsRef<std::ffi::OsStr>,
+{
+    names.into_iter().any(|name| {
+        let name = name.as_ref();
+        MIMALLOC_PURGE_ENV.iter().any(|option| name.eq_ignore_ascii_case(option))
+    })
+}
+
 impl AlignerProcess {
     /// Spawn an aligner subprocess with the given shell command.
     ///
@@ -97,13 +122,24 @@ impl AlignerProcess {
     /// configuring `Stdio::piped()`, which should never happen in
     /// practice.
     pub fn spawn(command: &str, ring_size: usize) -> Result<Self> {
-        let mut child = Command::new("/bin/bash")
-            .args(["-c", command])
+        let mut cmd = Command::new("/bin/bash");
+        cmd.args(["-c", command])
             .stdin(Stdio::piped())
             .stdout(Stdio::piped())
-            .stderr(Stdio::piped())
-            .spawn()
-            .with_context(|| format!("failed to spawn aligner command: {command}"))?;
+            .stderr(Stdio::piped());
+        // bwa-mem3 links mimalloc, whose default purge decommits freed pages
+        // after 1 s and costs the aligner page faults on every batch: never
+        // purging measured -0.5% wall on the bwa-mem3 CLI alone. A user-set
+        // value (either name, any case) is inherited unchanged; aligners
+        // without mimalloc ignore the variable. The variable reaches every
+        // process in the shell command, so with `--aligner::command` any
+        // mimalloc-linked tool in the user's pipeline also keeps its freed
+        // pages (higher RSS); set `MIMALLOC_PURGE_DELAY` to opt out.
+        if !user_set_mimalloc_purge() {
+            cmd.env("MIMALLOC_PURGE_DELAY", "-1");
+        }
+        let mut child =
+            cmd.spawn().with_context(|| format!("failed to spawn aligner command: {command}"))?;
 
         let stdin = child.stdin.take();
         let stdout = child.stdout.take();
@@ -441,9 +477,13 @@ impl AlignerPreset {
 
     /// Build the aligner shell command for this preset.
     ///
-    /// The command reads FASTQ from `/dev/stdin` and writes SAM to
+    /// The command reads FASTQ from `/dev/stdin` and writes its alignments to
     /// stdout, allowing it to be connected to fgumi's pipeline via
-    /// stdin/stdout pipes.
+    /// stdin/stdout pipes. `bwa-mem3` writes uncompressed BAM (`--bam=0`):
+    /// fgumi's single reader thread then takes records zero-copy instead of
+    /// parsing SAM text, which at 32 threads kept bwa-mem3 blocked on its
+    /// output for most of the run (a fused extract → correct → align ran 36%
+    /// faster). `bwa` has no BAM output and writes SAM.
     ///
     /// # Arguments
     ///
@@ -472,7 +512,11 @@ impl AlignerPreset {
             None => self.binary_name().to_string(),
         };
         let ref_str = reference.display();
-        format!("{binary} mem -p -K {chunk_size} -t {threads} {ref_str} /dev/stdin")
+        let output = match self {
+            Self::BwaMem3 => " --bam=0",
+            Self::Bwa => "",
+        };
+        format!("{binary} mem{output} -p -K {chunk_size} -t {threads} {ref_str} /dev/stdin")
     }
 
     /// Validate that the aligner binary and required index files are present.
@@ -597,7 +641,7 @@ pub fn substitute_template(template: &str, reference: &Path, threads: usize) ->
         bail!(
             "--aligner::command template does not contain `{{ref}}`; \
              the aligner needs a reference path. Example: \
-             \"bwa-mem3 mem -p -K 150000000 -t {{threads}} {{ref}} /dev/stdin\""
+             \"bwa-mem3 mem --bam=0 -p -K 150000000 -t {{threads}} {{ref}} /dev/stdin\""
         );
     }
     // Single left-to-right pass so injected text is never re-scanned. Two
@@ -952,6 +996,22 @@ mod tests {
 
     use super::*;
 
+    #[rstest]
+    #[case::current_name(&["MIMALLOC_PURGE_DELAY"], true)]
+    #[case::legacy_name(&["MIMALLOC_RESET_DELAY"], true)]
+    #[case::lowercase(&["mimalloc_purge_delay"], true)]
+    #[case::mixed_case_legacy(&["Mimalloc_Reset_Delay"], true)]
+    #[case::among_others(&["PATH", "HOME", "mimalloc_purge_delay"], true)]
+    #[case::unset(&["PATH", "HOME"], false)]
+    #[case::other_mimalloc_option(&["MIMALLOC_VERBOSE", "MIMALLOC_ARENA_EAGER_COMMIT"], false)]
+    #[case::prefix_only(&["MIMALLOC_PURGE_DELAY_MS", "X_MIMALLOC_PURGE_DELAY"], false)]
+    fn names_set_mimalloc_purge_matches_like_mimalloc(
+        #[case] names: &[&str],
+        #[case] expected: bool,
+    ) {
+        assert_eq!(names_set_mimalloc_purge(names), expected);
+    }
+
     /// A non-UTF-8 stderr line must NOT halt the relay: draining has to
     /// continue to EOF, otherwise the aligner blocks once its stderr pipe fills
     /// (~64 KiB) and the whole align pipeline deadlocks. Regression test for the
@@ -1083,7 +1143,7 @@ mod tests {
         AlignerPreset::BwaMem3,
         4,
         5_000_000,
-        "bwa-mem3 mem -p -K 5000000 -t 4 /ref/genome.fa /dev/stdin"
+        "bwa-mem3 mem --bam=0 -p -K 5000000 -t 4 /ref/genome.fa /dev/stdin"
     )]
     fn preset_build_command_default_binary(
         #[case] preset: AlignerPreset,
@@ -1250,6 +1310,26 @@ mod tests {
         assert!(msg.contains("bwa-mem3 index"), "expected fix-it hint, got: {msg}");
     }
 
+    /// A preset that passes validation resolves to the subprocess backend with
+    /// bwa's mid-pair split accepted: both presets run `mem -p -K`.
+    #[rstest]
+    #[case::bwa_mem3(AlignerPreset::BwaMem3)]
+    #[case::bwa(AlignerPreset::Bwa)]
+    fn resolve_preset_accepts_mid_pair_split(#[case] preset: AlignerPreset) {
+        let tmp = tempfile::tempdir().unwrap();
+        let ref_path = tmp.path().join("ref.fa");
+        std::fs::write(&ref_path, b">chr1\nACGT\n").unwrap();
+        for ext in preset.index_extensions() {
+            std::fs::write(append_extension(&ref_path, ext), b"x").unwrap();
+        }
+        let bin = make_existing_binary(tmp.path());
+        let opts = AlignerOptions { preset: Some(preset), ..AlignerOptions::default() };
+        let resolved = opts.resolve(&ref_path, 4, Some(&bin)).unwrap();
+        let ResolvedBackend::Subprocess { command, accept_mid_pair_split } = resolved.backend;
+        assert!(accept_mid_pair_split, "preset mode must accept bwa's mid-pair split");
+        assert!(command.starts_with(&bin.display().to_string()), "got: {command}");
+    }
+
     /// `validate` errors out on a nonexistent `--aligner-bin` override path.
     #[test]
     fn test_validate_override_path_missing() {
diff --git a/src/lib/pipeline/steps/align/mod.rs b/src/lib/pipeline/steps/align/mod.rs
index f1d22ab98..751fcbd7b 100644
--- a/src/lib/pipeline/steps/align/mod.rs
+++ b/src/lib/pipeline/steps/align/mod.rs
@@ -17,7 +17,8 @@
 //!
 //! This module holds the trait, its wiring context/result types, the
 //! backend-agnostic `ZipperBatch`, the subprocess backend's `InFlightGate`
-//! byte-budget gate, the mid-pair split helper, and the header helpers (`validate_sq_consistency`,
+//! byte-budget gate, the mimalloc purge-delay setter called at wiring, the
+//! mid-pair split helper, and the header helpers (`validate_sq_consistency`,
 //! `merge_aligner_header`).
 
 pub(crate) mod merge;
@@ -408,6 +409,24 @@ pub(crate) fn split_pair_into_singles(template: Template) -> io::Result<(Templat
     Ok((to_template(first)?, to_template(second)?))
 }
 
+/// Keep mimalloc from returning freed pages to the OS, unless the user set the
+/// purge delay. The align stage frees and reallocates large per-batch buffers
+/// (FASTQ out, BAM in, merge), and mimalloc's default purge (decommit after 1 s)
+/// turns that reuse into hundreds of thousands of page faults.
+///
+/// The setting is process-wide and is never restored, so it covers every stage
+/// of the `runall` process, not just align: fgumi-sort's `force_mi_collect()`
+/// stops returning memory to the OS too. Measured end to end (extract through
+/// simplex consensus, 1M pairs, 32 threads) it is still faster with it,
+/// including when sort spills: wall -4%, CPU -2.5%, page faults ~700k to under
+/// 40k, for ~0.4 GB more peak RSS. Set `MIMALLOC_PURGE_DELAY` to opt out.
+pub(crate) fn retain_freed_memory_unless_user_set() {
+    if !crate::aligner::user_set_mimalloc_purge() {
+        fgumi_sort::retain_freed_memory();
+    }
+    log::debug!("align: mimalloc purge delay {} ms", fgumi_sort::mi_purge_delay_ms());
+}
+
 /// Merge aligner-emitted header lines into the partial output header.
 ///
 /// The aligner contributes:
@@ -479,6 +498,41 @@ pub(crate) fn merge_aligner_header(partial: &Header, aligner: &Header) -> Header
 mod tests {
     use super::*;
 
+    /// Only a template of exactly two records is split: any other count is out
+    /// of contract and errors, naming the template and its record count.
+    #[rstest::rstest]
+    #[case::one_record(&[fgumi_raw_bam::flags::UNMAPPED], 1)]
+    #[case::pair_with_supplementary(
+        &[
+            fgumi_raw_bam::flags::PAIRED | fgumi_raw_bam::flags::FIRST_SEGMENT,
+            fgumi_raw_bam::flags::PAIRED | fgumi_raw_bam::flags::LAST_SEGMENT,
+            fgumi_raw_bam::flags::PAIRED
+                | fgumi_raw_bam::flags::FIRST_SEGMENT
+                | fgumi_raw_bam::flags::SUPPLEMENTARY,
+        ],
+        3
+    )]
+    fn split_pair_into_singles_rejects_other_than_two_records(
+        #[case] flags: &[u16],
+        #[case] n: usize,
+    ) {
+        let records = flags
+            .iter()
+            .map(|&f| {
+                let mut b = fgumi_raw_bam::SamBuilder::new();
+                b.read_name(b"q1").flags(f).sequence(b"ACGT").qualities(b"IIII");
+                b.build()
+            })
+            .collect();
+        let template = Template::from_records(records).expect("template");
+        let err = split_pair_into_singles(template).expect_err("must not split").to_string();
+        assert!(
+            err.contains("cannot split template 'q1'")
+                && err.contains(&format!("carries {n} records")),
+            "got: {err}"
+        );
+    }
+
     /// A `ZipperBatch` sits in a byte-bounded queue, so its `heap_size` must
     /// count both halves' `Vec` backing store, as `BamTemplateBatch` already
     /// does for the unmapped half. Empty `Vec`s with reserved capacity isolate
diff --git a/src/lib/pipeline/steps/align/subprocess.rs b/src/lib/pipeline/steps/align/subprocess.rs
index 67276279c..426ed5626 100644
--- a/src/lib/pipeline/steps/align/subprocess.rs
+++ b/src/lib/pipeline/steps/align/subprocess.rs
@@ -1462,6 +1462,10 @@ impl AlignBackend for SubprocessBackend {
         input: (StepIdx, BranchIdx),
         ctx: &AlignWiringCtx,
     ) -> anyhow::Result<AlignWired> {
+        // fgumi's side of the subprocess route churns the same per-batch
+        // buffers (FASTQ out, BAM in, merge); the aligner child gets the same
+        // setting through its environment (see `AlignerProcess::spawn`).
+        super::retain_freed_memory_unless_user_set();
         let step = SubprocessAlignStep::new(
             SubprocessConfig {
                 partial_output_header: Arc::clone(&ctx.partial_output_header),
@@ -2021,4 +2025,92 @@ mod tests {
             "stream is exhausted after the last template"
         );
     }
+
+    /// Write a BAM (empty header) holding one record per `(qname, flags)` to
+    /// `path`: the staged output of a fake aligner.
+    fn write_bam_fixture(path: &std::path::Path, records: &[(&[u8], u16)]) {
+        use fgumi_bgzf::{BGZF_EOF, InlineBgzfCompressor};
+        use std::fs::File;
+
+        let mut bytes = Vec::new();
+        fgumi_bam_io::write_bam_header(&mut bytes, &Header::default()).expect("write_bam_header");
+        for &(qname, flags) in records {
+            fgumi_raw_bam::write_raw_record(&mut bytes, &make_record(qname, flags))
+                .expect("write record");
+        }
+        let mut c = InlineBgzfCompressor::new(1);
+        c.write_all(&bytes).expect("compress");
+        c.flush().expect("flush");
+        let mut f = File::create(path).expect("create fixture");
+        c.write_blocks_to(&mut f).expect("write compressed blocks");
+        f.write_all(&BGZF_EOF).expect("write BGZF EOF");
+    }
+
+    /// Write a SAM (`@HD` only) holding one unmapped `ACGT` record per
+    /// `(qname, flags)` to `path`: the staged output of a fake aligner.
+    fn write_sam_fixture(path: &std::path::Path, records: &[(&[u8], u16)]) {
+        let mut text = b"@HD\tVN:1.6\n".to_vec();
+        for &(qname, flags) in records {
+            let qname = String::from_utf8_lossy(qname);
+            writeln!(text, "{qname}\t{flags}\t*\t0\t0\t*\t*\t0\t0\tACGT\tIIII").expect("format");
+        }
+        std::fs::write(path, text).expect("write sam fixture");
+    }
+
+    /// End to end through `reader_loop_inner` for both aligner output formats: a
+    /// pair the aligner split mid-pair (two unpaired primaries under one name)
+    /// zips as two single-read mapped templates against its unmapped template
+    /// split to match, a single-end template passes through, and an empty batch
+    /// still yields an (empty) `ZipperBatch` to keep serials contiguous.
+    #[rstest::rstest]
+    fn reader_loop_zips_a_mid_pair_split_from_aligner_output(#[values(false, true)] sam: bool) {
+        use fgumi_raw_bam::flags::UNMAPPED;
+        use std::process::{Command, Stdio};
+        use std::sync::mpsc::sync_channel;
+
+        let tmp = tempfile::TempDir::new().expect("tempdir");
+        let aligned: [(&[u8], u16); 3] =
+            [(b"pe1", UNMAPPED), (b"pe1", UNMAPPED | REVERSE), (b"se1", UNMAPPED)];
+        let fixture = tmp.path().join(if sam { "out.sam" } else { "out.bam" });
+        if sam {
+            write_sam_fixture(&fixture, &aligned);
+        } else {
+            write_bam_fixture(&fixture, &aligned);
+        }
+        let mut cat = Command::new("cat")
+            .arg(&fixture)
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .spawn()
+            .expect("spawn cat");
+        let stdout = cat.stdout.take().expect("cat stdout");
+
+        let (token_tx, token_rx) = channel::<BatchToken>();
+        let (out_tx, out_rx) = sync_channel::<ZipperBatch>(4);
+        let empty = BamTemplateBatch::new(0, Vec::new());
+        token_tx.send(BatchToken { unmapped: empty, n_templates: 0, serial: 0 }).unwrap();
+        let single = Template::from_records(vec![make_record(b"se1", UNMAPPED)]).unwrap();
+        let unmapped = BamTemplateBatch::new(1, vec![make_paired_primary_template(b"pe1"), single]);
+        token_tx.send(BatchToken { unmapped, n_templates: 2, serial: 1 }).unwrap();
+        drop(token_tx);
+
+        let cfg = make_test_cfg();
+        reader_loop_inner(token_rx, &out_tx, stdout, &cfg, &InFlightGate::new(u64::MAX))
+            .expect("reader_loop_inner");
+        drop(out_tx);
+        let _ = cat.wait();
+
+        let batches: Vec<ZipperBatch> = out_rx.iter().collect();
+        assert_eq!(batches.iter().map(|b| b.serial).collect::<Vec<_>>(), vec![0, 1]);
+        assert!(batches[0].mapped.is_empty() && batches[0].unmapped.templates().is_empty());
+        let shape = |ts: &[Template]| {
+            ts.iter().map(|t| (t.name().to_vec(), t.read_count())).collect::<Vec<_>>()
+        };
+        let expected = vec![(b"pe1".to_vec(), 1), (b"pe1".to_vec(), 1), (b"se1".to_vec(), 1)];
+        assert_eq!(shape(&batches[1].mapped), expected, "mapped side");
+        assert_eq!(shape(batches[1].unmapped.templates()), expected, "unmapped side");
+        for half in &batches[1].unmapped.templates()[..2] {
+            assert_eq!(half.records()[0].flags() & PAIRED, 0, "split half is unpaired");
+        }
+    }
 }

From ead718d9f42142bf1e38428bb3add798dca5287a Mon Sep 17 00:00:00 2001
From: Nils Homer <nilshomer@gmail.com>
Date: Sun, 27 Sep 2026 04:41:07 -0700
Subject: [PATCH 3/3] feat(runall/inproc): add the aligner-bwa-mem3 feature,
 cohort math and the AlignEngine abstraction

The foundation of an in-process bwa-mem3 aligner backend, behind a new
off-by-default `aligner-bwa-mem3` cargo feature that pulls bwa-mem3-rs
0.3.0 (the vendored bwa-mem3 C++, C++17 toolchain required; target-gated
to x86_64/aarch64) and makes mimalloc interpose the C allocator for it.

- inproc::cohort: the parity-critical pure logic the steps will need to
  reproduce `bwa-mem3 mem -p -K` exactly: the -K even-read-count cohort
  cut, the per-cohort SE/PE layout that -p smart pairing produces, and
  the per-sub-batch read-id bases, each pinned by a proptest against a
  literal Rust port of the upstream rule.
- inproc::engine: the AlignEngine trait over bwa-mem3-rs's three-phase
  API (seed/extend, per-cohort pestat, pair/emit), the BwaMem3Engine
  implementation, and a test fake; plus an env-gated smoke test against
  a real index.
- inproc::gate: the cohort-granularity in-flight gate and its lease,
  with the refill signal the refill-drain scheduler reads.
- inproc::scratch: the per-pool-thread aligner scratch pool.

Nothing is wired into runall yet (the steps and the backend follow), so
the module carries a scoped dead_code allow. A new `aligner-ffi` CI job
builds the feature on x86_64 and arm64 and runs its tests, pedantic
clippy and rustdoc.
---
 .github/workflows/check.yml                   |  70 ++
 CLAUDE.md                                     |   6 +
 Cargo.lock                                    |  22 +
 Cargo.toml                                    |  21 +
 src/lib/pipeline/steps/align/inproc/cohort.rs | 586 ++++++++++++++
 src/lib/pipeline/steps/align/inproc/engine.rs | 735 ++++++++++++++++++
 src/lib/pipeline/steps/align/inproc/gate.rs   | 415 ++++++++++
 src/lib/pipeline/steps/align/inproc/mod.rs    |  31 +
 .../pipeline/steps/align/inproc/scratch.rs    | 124 +++
 src/lib/pipeline/steps/align/mod.rs           |   9 +
 10 files changed, 2019 insertions(+)
 create mode 100644 src/lib/pipeline/steps/align/inproc/cohort.rs
 create mode 100644 src/lib/pipeline/steps/align/inproc/engine.rs
 create mode 100644 src/lib/pipeline/steps/align/inproc/gate.rs
 create mode 100644 src/lib/pipeline/steps/align/inproc/mod.rs
 create mode 100644 src/lib/pipeline/steps/align/inproc/scratch.rs

diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index 637c0937e..e2c92a755 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -61,6 +61,76 @@ jobs:
       - name: Clippy check
         run: cargo ci-lint
 
+  # Builds and tests the optional in-process bwa-mem3 aligner backend (feature
+  # `aligner-bwa-mem3`, off by default). This is the one feature that pulls a
+  # C++ toolchain into the build (the vendored bwa-mem3 kernels via
+  # `bwa-mem3-sys`'s `cc`-driven build.rs), so it gets its own job rather than
+  # folding into `test`/`lint`: those two stay C-toolchain-free, matching every
+  # other job's fast/portable assumption.
+  #
+  # Matrix covers both architectures the feature compiles on (the dependency is
+  # gated in Cargo.toml to `x86_64`/`aarch64` — see the `bwa-mem3-rs` entry).
+  # `ubuntu-24.04-arm` is a real (not emulated) arm64 GitHub-hosted runner, so
+  # this exercises the NEON build path, not just the x86_64 SIMD-tier ladder.
+  #
+  # Toolchain deps are deliberately minimal: `build-essential` (a C++17-capable
+  # g++) and `zlib1g-dev` (the crate links `z`) are everything `bwa-mem3-sys`'s
+  # build.rs actually needs for a normal build — mirrors fg-labs/bwa-mem3-rs's
+  # own `build`/`lint` jobs. Two toolchain pieces this job deliberately does
+  # NOT install:
+  #   - `libclang-dev`: bindgen only runs under the sys crate's own
+  #     `regenerate-bindings` feature (gated in its build.rs), which this job
+  #     never enables — the committed bindings are used as-is.
+  #   - clang-19 / libomp: bwa-mem3's Makefile compiler floor (clang >= 19 /
+  #     gcc >= 15) applies to building the vendored bwa-mem3 CLI *from
+  #     upstream* (fg-labs/bwa-mem3-rs's own `e2e` job does that, to diff
+  #     against this crate's output byte-for-byte); `cc` enforces no such floor
+  #     on the sys crate itself, and this job never builds the reference CLI
+  #     binary.
+  aligner-ffi:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install build deps (C++17 toolchain for bwa-mem3-sys)
+        run: sudo apt-get update && sudo apt-get install -y build-essential zlib1g-dev
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+        with:
+          components: clippy
+      - name: Set up compilation cache (sccache)
+        uses: mozilla-actions/sccache-action@fc920bf0ec8de6ee65d409111f7ec508035751ba # v0.0.11
+      - name: Install nextest
+        uses: taiki-e/install-action@b20dedce73af6905cdc30d6611090c9b67557c8d # v2.85.12
+        with:
+          tool: nextest
+      - name: Unit tests (aligner-bwa-mem3)
+        run: cargo nextest run --features aligner-bwa-mem3 -p fgumi --locked
+      - name: Clippy (aligner-bwa-mem3, pedantic)
+        # Lints compare,simulate,profile-adjacency,aligner-bwa-mem3 together:
+        # the first three are already part of every default dev/test build's
+        # assumed surface (`cargo ci-lint` compiles them), so linting them
+        # together with the aligner feature catches any interaction between the
+        # two rather than linting the aligner feature in isolation.
+        run: |
+          cargo clippy --workspace --all-targets \
+            --features compare,simulate,profile-adjacency,aligner-bwa-mem3 --locked \
+            -- -D warnings -W clippy::pedantic
+      - name: Rustdoc (aligner-bwa-mem3, -D warnings)
+        # `cargo ci-doc` (the `docs` job) does not enable `aligner-bwa-mem3`, so
+        # the feature-gated in-process backend's docs are rendered only here.
+        # Clippy does not report broken intra-doc links; rustdoc does.
+        env:
+          RUSTDOCFLAGS: "-D warnings"
+        run: cargo doc --no-deps -p fgumi --document-private-items --features aligner-bwa-mem3 --locked
+
   # `merge_slots.rs` swaps `std::sync` for `loom::sync` under `--cfg loom`, and
   # `tests/loom_merge_slots.rs` is `#![cfg(loom)]`. Neither is built by any other
   # job, so without this one a broken model — or a `cfg(loom)` build that stopped
diff --git a/CLAUDE.md b/CLAUDE.md
index 88c1c9e27..c8d755b97 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -39,6 +39,7 @@ cargo bench
 - `compare` - Enable compare subcommand (developer tools)
 - `simulate` - Enable simulate command for test data generation
 - `profile-adjacency` - Enable profiling output for adjacency UMI assigner
+- `aligner-bwa-mem3` - Opt-in in-process bwa-mem3 aligner backend for `runall` (cohort math, engine abstraction; the backend itself is still being wired in); off by default, and compiling it requires a C++17 toolchain (see `Cargo.toml`'s `bwa-mem3-rs` dependency)
 
 Build with features: `cargo build --release --features compare,simulate`
 
@@ -133,6 +134,11 @@ Uses `mimalloc` as global allocator for performance.
 `#[allow(unsafe_code)]` blocks are permitted only at the documented sites listed below;
 any new `unsafe` block requires updating this section with a written justification.
 
+Enabling the optional `aligner-bwa-mem3` feature links `bwa-mem3-sys`/`bwa-mem3-rs`
+(vendored C++ plus its Rust FFI bindings), which contain their own `unsafe` outside
+this workspace's `deny(unsafe_code)`; fgumi's own crates carry no new `unsafe` for it
+and remain `#![deny(unsafe_code)]` regardless of the feature.
+
 ### Approved non-stdlib FFI exceptions
 
 The following external FFI calls are approved because they back core infrastructure:
diff --git a/Cargo.lock b/Cargo.lock
index f2097c8d7..b4b20ddc8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -281,6 +281,27 @@ version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
+[[package]]
+name = "bwa-mem3-rs"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d605c934e6a7dbd00be78d3645335dbe664662f5234c3db3681db6b45167bce"
+dependencies = [
+ "bwa-mem3-sys",
+ "libc",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "bwa-mem3-sys"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "998de3690d2feda385b024c92a8f5f63ecce65fc2cb90f37cab87e5a5dea85ee"
+dependencies = [
+ "cc",
+ "libc",
+]
+
 [[package]]
 name = "bytemuck"
 version = "1.25.2"
@@ -712,6 +733,7 @@ dependencies = [
  "approx",
  "bstr 1.13.1",
  "built",
+ "bwa-mem3-rs",
  "bytemuck",
  "bytes",
  "bytesize",
diff --git a/Cargo.toml b/Cargo.toml
index 5c34e3d36..0d5626049 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -181,6 +181,14 @@ mach2 = { workspace = true }
 [target.'cfg(target_os = "linux")'.dependencies]
 nix = { workspace = true }
 
+# In-process bwa-mem3 aligner backend (feature `aligner-bwa-mem3`). Gated on the
+# only two architectures whose vendored C++ SIMD tiers build (`x86_64`/`aarch64`);
+# enabling the feature elsewhere hits a `compile_error!` in
+# `pipeline::steps::align`. 0.3.0 is the first
+# release with the three-phase (`seed_extend` / `infer_cohort` / `pair_emit`) API.
+[target.'cfg(any(target_arch = "x86_64", target_arch = "aarch64"))'.dependencies]
+bwa-mem3-rs = { version = "0.3.0", optional = true }
+
 [features]
 default = ["consensus"]
 # Single umbrella feature for all consensus calling (simplex + duplex + codec).
@@ -210,6 +218,19 @@ simulate = ["consensus"]
 profile-adjacency = []
 # Enable slow stress tests for concurrency testing
 stress-tests = []
+# In-process bwa-mem3 aligner backend for `fgumi runall` (its steps and the
+# `bwa-mem3-inproc` preset build on this). Off by default: it pulls the
+# optional `bwa-mem3-rs` dependency, which compiles the vendored bwa-mem3 C++ (C++17 toolchain
+# required) and links it statically. Default builds stay pure Rust with no C
+# toolchain. The in-process backend code is `#[cfg(feature = "aligner-bwa-mem3")]`
+# confined to `pipeline::steps::align::inproc`.
+#
+# `mimalloc/override` makes the global mimalloc also interpose the C `malloc`/
+# `free`, so the linked bwa-mem3 C++ uses mimalloc instead of the system
+# allocator (whose per-thread arena contention regresses multithreaded
+# alignment). Scoped to this feature because it is the only build that links the
+# C++ aligner; a pure-Rust fgumi build gains nothing from the C interpose.
+aligner-bwa-mem3 = ["dep:bwa-mem3-rs", "mimalloc/override"]
 # Test-only feature (not part of the supported public API). Its former gated
 # helper (the legacy multi-thread engine's `run_bam_pipeline_with_grouper`) was
 # removed in R6/C6; retained as the self dev-dependency's feature hook. Enabled
diff --git a/src/lib/pipeline/steps/align/inproc/cohort.rs b/src/lib/pipeline/steps/align/inproc/cohort.rs
new file mode 100644
index 000000000..9dfb51267
--- /dev/null
+++ b/src/lib/pipeline/steps/align/inproc/cohort.rs
@@ -0,0 +1,586 @@
+//! Cohort cutter, SE/PE layout, and per-sub-batch id-base arithmetic.
+//!
+//! These are the parity-critical *pure* functions of the in-process aligner:
+//! they reproduce, exactly, three upstream bwa-mem3 rules so that the merged
+//! output is byte-identical to the subprocess `bwa-mem3` preset: the `-K` cohort
+//! cut, the SE/PE layout, and the per-sub-batch read-id bases. Each is pinned
+//! by a proptest against a literal Rust port of the upstream rule in the test
+//! module below.
+//!
+//! Nothing here calls FFI or wires a pipeline step.
+//!
+//! These pure primitives are the foundation the in-process backend is built on:
+//! the pipeline steps that construct and thread the work items through the pool
+//! (`AlignPrepareStep`, `AlignSeedExtendStep`, `CohortPeStatStep`,
+//! `AlignPairEmitStep`) consume the types and functions here.
+
+use std::sync::Arc;
+
+use crate::pipeline::core::item::HeapSize;
+use crate::template::Template;
+
+use super::engine::{AlignEngine, IdBases};
+use super::gate::CohortLease;
+
+/// Reproduces bwa-mem3's `-K` even-parity cohort cut
+/// (`fast_reader_bseq.c:129-137`).
+///
+/// bwa-mem3's fast reader appends reads to the current cohort one at a time,
+/// accumulating `size += l_seq` after each, and closes the cohort as soon as
+/// `size >= chunk_size && (n & 1) == 0` — i.e. the accumulated bases have
+/// reached `-K` **and** an even number of reads has been buffered. The parity
+/// test matters: with `-p` smart pairing an even read count keeps read pairs
+/// together at a cohort boundary in the common all-paired case, but a cut can
+/// still fall *between* the two reads of a pair when the running read count is
+/// odd at the pair's start (a mixed SE/PE input) — bwa then classifies the two
+/// reads as two separate singles in adjacent cohorts.
+///
+/// The cut is therefore evaluated **per read**, not per template, which is why
+/// the cutter's state is a running byte size and read count rather than a
+/// per-template tally.
+pub(crate) struct CohortCutter {
+    /// The `-K` chunk size in bases; a cohort closes once its accumulated read
+    /// bases reach this and the read count is even.
+    chunk_size: u64,
+    /// Accumulated `l_seq` of the reads buffered in the current (open) cohort.
+    size: u64,
+    /// Number of reads buffered in the current (open) cohort.
+    n_reads_in_cohort: u64,
+}
+
+impl CohortCutter {
+    /// Create a cutter for the given `-K` chunk size (bases). Callers pass the
+    /// validated aligner chunk size (`>= 1`), matching the CLI.
+    pub(crate) fn new(chunk_size: u64) -> Self {
+        Self { chunk_size, size: 0, n_reads_in_cohort: 0 }
+    }
+
+    /// Feed one template's surviving reads (1 for single-end, 2 for a pair)
+    /// through the per-read cut rule, in order. Returns `true` iff the cohort
+    /// boundary falls **exactly after this template** — i.e. the template's
+    /// last read triggered the even-parity cut, so the current cohort closes
+    /// here and the next template opens a new one.
+    ///
+    /// A cut that fires *between* a pair's two reads (possible only when the
+    /// running read count is odd at the pair's start, in a mixed SE/PE input)
+    /// leaves the boundary inside the template: the second read correctly opens
+    /// the next cohort in the cutter's state, but this method returns `false`
+    /// because the boundary is not after the template. Splitting such a
+    /// template into two singles across the two cohorts is the caller's concern
+    /// (`AlignPrepareStep` splits it); the cutter's own running state stays exact
+    /// regardless.
+    ///
+    /// Production drives the cutter one read at a time via [`Self::push_read`] (so
+    /// it can observe a mid-pair cut); this whole-template convenience is used
+    /// only by the parity proptest, hence `#[cfg(test)]`.
+    #[cfg(test)]
+    pub(crate) fn push_template(&mut self, l_seqs: impl Iterator<Item = u32>) -> bool {
+        let mut cut_after_last = false;
+        for l_seq in l_seqs {
+            cut_after_last = self.push_read(l_seq);
+        }
+        cut_after_last
+    }
+
+    /// Feed **one** read's `l_seq` through the per-read cut rule and return
+    /// `true` iff the cohort closes **after this read** — i.e. the accumulated
+    /// bases have reached `-K` and the running read count is now even
+    /// (`fast_reader_bseq.c:129-137`). On a cut the running accumulators reset,
+    /// so the next `push_read` opens a fresh cohort.
+    ///
+    /// This per-read granularity is what lets the caller
+    /// (`AlignPrepareStep`) observe a
+    /// **mid-pair cut**: feeding a pair's two reads individually, a `true` after
+    /// the *first* read means the cohort boundary falls between the pair's reads,
+    /// and bwa then classifies them as two separate singles in adjacent cohorts.
+    /// `Self::push_template` cannot express that (its single
+    /// `bool` reports only a cut after the *last* read), so the prepare step
+    /// drives the cutter one read at a time via this method.
+    pub(crate) fn push_read(&mut self, l_seq: u32) -> bool {
+        self.size += u64::from(l_seq);
+        self.n_reads_in_cohort += 1;
+        if self.size >= self.chunk_size && self.n_reads_in_cohort.is_multiple_of(2) {
+            // Close the cohort after this read and open a fresh one.
+            self.size = 0;
+            self.n_reads_in_cohort = 0;
+            true
+        } else {
+            false
+        }
+    }
+}
+
+/// Where one template of a sub-batch sits in bwa-mem3's `-p` SE/PE
+/// classification. `idx` is the template's ordinal **within its group** — its
+/// index into bwa's `pairs[]` or `singles[]` array — which is what the id
+/// formulas and the record-emission origin indices key off.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum TemplateSlot {
+    /// A paired template (two reads with equal names); the `idx`-th pair.
+    Pair { idx: u32 },
+    /// A single-end template (one read); the `idx`-th single.
+    Single { idx: u32 },
+}
+
+/// The SE/PE classification of a sub-batch's templates, in input order.
+///
+/// [`Layout::AllPairs`] is the production shape — every template is a full pair,
+/// so a template's index is exactly its pair index and no per-template vector is
+/// needed. [`Layout::Mixed`] carries one [`TemplateSlot`] per template for the
+/// (rare) SE / mixed inputs.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) enum Layout {
+    /// Every template contributes two reads: template `i` is pair `i`.
+    AllPairs,
+    /// One slot per template, in input order.
+    Mixed(Vec<TemplateSlot>),
+}
+
+impl Layout {
+    /// Classify a sub-batch's templates into bwa-mem3's `-p` SE/PE groups from
+    /// each template's surviving-read count (2 = pair, otherwise single),
+    /// reproducing `bseq_classify` (`bwa.cpp:258-274`).
+    ///
+    /// Upstream pairs two *consecutive equal-named reads*; because
+    /// `GroupByQueryname` never emits two consecutive same-name templates, a
+    /// template is a pair exactly when it contributes two reads and a single
+    /// otherwise. A non-empty sub-batch whose templates are
+    /// all pairs collapses to [`Layout::AllPairs`]; any single (or an empty
+    /// sub-batch) yields [`Layout::Mixed`].
+    pub(crate) fn classify(read_counts: &[u8]) -> Self {
+        if !read_counts.is_empty() && read_counts.iter().all(|&c| c == 2) {
+            return Self::AllPairs;
+        }
+        let mut slots = Vec::with_capacity(read_counts.len());
+        let mut pair_idx: u32 = 0;
+        let mut single_idx: u32 = 0;
+        for &count in read_counts {
+            if count == 2 {
+                slots.push(TemplateSlot::Pair { idx: pair_idx });
+                pair_idx += 1;
+            } else {
+                slots.push(TemplateSlot::Single { idx: single_idx });
+                single_idx += 1;
+            }
+        }
+        Self::Mixed(slots)
+    }
+}
+
+/// Cohort-level facts a sub-batch carries so the barrier can compute its id
+/// bases. Offsets are counts *within this cohort* accumulated
+/// over the earlier sub-batches, in input order.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct CohortPos {
+    /// Global reads before this cohort — bwa's `n_processed` at cohort start.
+    pub(crate) cohort_read_base: u64,
+    /// Single-end reads in earlier sub-batches of this cohort.
+    pub(crate) se_offset: u64,
+    /// Paired templates in earlier sub-batches of this cohort.
+    pub(crate) pe_offset: u64,
+    /// Single-end reads in this sub-batch.
+    pub(crate) n_se: u32,
+    /// Paired templates in this sub-batch.
+    pub(crate) n_pe: u32,
+}
+
+/// Identity of a sub-batch. `serial` is dense from 0 across the whole run and
+/// becomes `BamTemplateBatch::batch_serial`; `(cohort, index_in_cohort)` is for
+/// the cohort barrier.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct SubBatchId {
+    pub(crate) serial: u64,
+    pub(crate) cohort: u32,
+    pub(crate) index_in_cohort: u32,
+}
+
+/// Attached to the **last** sub-batch of a cohort (only known at cut time): the
+/// cohort's sub-batch count and total SE/PE tallies, which the barrier needs to
+/// know a cohort is complete and to compute `pe_n_processed`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct CohortCloser {
+    pub(crate) n_sub_batches: u32,
+    pub(crate) cohort_n_se: u64,
+    pub(crate) cohort_n_pe: u64,
+}
+
+/// Global-ordinal id bases for one sub-batch, reproducing bwa-mem3's `worker_sam`
+/// ids over a `-p` cohort (`fastmap.cpp:908-958` + `bwamem.cpp:2795-2884`).
+///
+/// bwa processes a cohort's SE group with `n_processed = cohort_read_base` and
+/// its PE group with `n_processed = cohort_read_base + cohort_n_se`
+/// (`fastmap.cpp:924-944`); `worker_sam` then assigns single `i` the id
+/// `n_processed + i` and pair `i` the id `(n_processed >> 1) + i`
+/// (`bwamem.cpp:2795-2884`). For a sub-batch that is preceded within its cohort
+/// by `se_offset` singles and `pe_offset` pairs, the *first* single/pair ids are
+/// therefore:
+///
+/// - `first_single_id = cohort_read_base + se_offset`
+/// - `first_pair_id = ((cohort_read_base + cohort_n_se) >> 1) + pe_offset`
+///
+/// and the engine adds the per-read index `i` on top. The `>> 1` is bwa's own
+/// truncating shift on the pair `n_processed`, reproduced verbatim.
+pub(crate) fn id_bases(pos: &CohortPos, cohort_n_se: u64) -> IdBases {
+    IdBases {
+        first_single_id: pos.cohort_read_base + pos.se_offset,
+        first_pair_id: ((pos.cohort_read_base + cohort_n_se) >> 1) + pos.pe_offset,
+    }
+}
+
+/// Heap footprint shared by the in-process work items: the summed
+/// `Template::heap_size` of the moved-out unmapped templates. The C-side read
+/// copies and alignment regions are not charged here: they live in the cohort's
+/// resident state (owned by the [`CohortLease`], freed with its last clone),
+/// not in any one sub-batch, and the lease's gate reservation is what bounds
+/// how many cohorts hold them at once.
+fn work_heap_size(unmapped: &[Template]) -> usize {
+    unmapped.iter().map(Template::heap_size).sum::<usize>()
+}
+
+/// A sub-batch prepared for seeding: its identity, cohort position, SE/PE
+/// layout, and the moved-out unmapped templates in input order, carrying the
+/// cohort's [`CohortLease`]. Produced by `AlignPrepareStep`; consumed by
+/// `AlignSeedExtendStep`.
+pub(crate) struct AlignWork {
+    pub(crate) id: SubBatchId,
+    pub(crate) pos: CohortPos,
+    /// `Some` on the cohort's last sub-batch.
+    pub(crate) closer: Option<CohortCloser>,
+    pub(crate) layout: Layout,
+    pub(crate) unmapped: Vec<Template>,
+    pub(crate) lease: CohortLease,
+}
+
+impl HeapSize for AlignWork {
+    fn heap_size(&self) -> usize {
+        work_heap_size(&self.unmapped)
+    }
+}
+
+/// [`AlignWork`] after seeding + SE-extension: adds the sub-batch's share of its
+/// cohort's resident state ([`AlignEngine::Ranges`]; the reads and alignment
+/// regions themselves stay in the cohort). Produced by
+/// `AlignSeedExtendStep` and consumed
+/// by `CohortPeStatStep`.
+///
+/// Generic over the engine so the parallel seed/extend step and its tests share
+/// one type: production drives it with `BwaMem3Engine`, the scheduling/ordering
+/// tests with `FakeEngine` (`Ranges = Vec<TaggedRead>`). Only [`AlignWork`] stays
+/// non-generic — it carries no ranges.
+pub(crate) struct ExtendedWork<E: AlignEngine> {
+    pub(crate) id: SubBatchId,
+    pub(crate) pos: CohortPos,
+    pub(crate) closer: Option<CohortCloser>,
+    pub(crate) layout: Layout,
+    pub(crate) unmapped: Vec<Template>,
+    pub(crate) lease: CohortLease,
+    pub(crate) ranges: E::Ranges,
+}
+
+impl<E: AlignEngine> HeapSize for ExtendedWork<E> {
+    fn heap_size(&self) -> usize {
+        work_heap_size(&self.unmapped)
+    }
+}
+
+/// A sub-batch past the cohort barrier, ready to pair + emit: carries the
+/// cohort `pestat` (`None` only when the sub-batch has no pairs) and the
+/// computed id bases. Produced by
+/// `CohortPeStatStep`; consumed by
+/// `AlignPairEmitStep`.
+///
+/// Generic over the engine for the same reason as [`ExtendedWork`]: production
+/// drives it with `BwaMem3Engine` (`PeStat = MemPeStat`), the barrier's
+/// scheduling/ordering tests with `FakeEngine`.
+pub(crate) struct PairWork<E: AlignEngine> {
+    pub(crate) id: SubBatchId,
+    pub(crate) layout: Layout,
+    pub(crate) unmapped: Vec<Template>,
+    pub(crate) lease: CohortLease,
+    pub(crate) ranges: E::Ranges,
+    /// The cohort insert-size model, shared read-only across the cohort's
+    /// sub-batches; `None` when this sub-batch classifies no pairs.
+    pub(crate) pestat: Option<Arc<E::PeStat>>,
+    pub(crate) ids: IdBases,
+}
+
+impl<E: AlignEngine> HeapSize for PairWork<E> {
+    fn heap_size(&self) -> usize {
+        work_heap_size(&self.unmapped)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use proptest::prelude::*;
+
+    // -------------------------------------------------------------------------
+    // CohortCutter vs. bseq_read_fast
+    // -------------------------------------------------------------------------
+
+    /// Literal port of bwa-mem3's `bseq_read_fast` inner loop
+    /// (`fast_reader_bseq.c:129-137`): walk the flat read-length stream,
+    /// accumulate `size` per read, and record a cut (by read index) whenever
+    /// `size >= chunk_size && (n & 1) == 0`, resetting the accumulators on each
+    /// cut. The final partial cohort at EOF is *not* a cut here — bwa's reader
+    /// only cuts on the size/parity condition; the tail is closed separately by
+    /// the caller at end-of-input.
+    fn port_bseq_read_fast(reads: &[u32], chunk_size: u64) -> Vec<usize> {
+        let mut cuts = Vec::new();
+        let mut size: u64 = 0;
+        let mut n: u64 = 0;
+        for (i, &l_seq) in reads.iter().enumerate() {
+            size += u64::from(l_seq);
+            n += 1;
+            if size >= chunk_size && n & 1 == 0 {
+                cuts.push(i);
+                size = 0;
+                n = 0;
+            }
+        }
+        cuts
+    }
+
+    /// Drive [`CohortCutter`] one single-read template at a time over `reads`,
+    /// collecting the read indices after which `push_template` reported a cut.
+    /// With one read per template, the per-read rule and the per-template return
+    /// coincide, so the result must equal [`port_bseq_read_fast`].
+    fn run_cutter_over_reads(reads: &[u32], chunk_size: u64) -> Vec<usize> {
+        let mut cutter = CohortCutter::new(chunk_size);
+        let mut cuts = Vec::new();
+        for (i, &l_seq) in reads.iter().enumerate() {
+            if cutter.push_template(std::iter::once(l_seq)) {
+                cuts.push(i);
+            }
+        }
+        cuts
+    }
+
+    proptest! {
+        #[test]
+        fn cutter_matches_bseq_read_fast(
+            reads in prop::collection::vec(1u32..300, 0..5000),
+            chunk in 1u64..2000,
+        ) {
+            let want = port_bseq_read_fast(&reads, chunk);
+            let got = run_cutter_over_reads(&reads, chunk);
+            prop_assert_eq!(got, want);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Layout vs. bseq_classify
+    // -------------------------------------------------------------------------
+
+    /// Group ordinal a template lands in, mirroring [`TemplateSlot`] but without
+    /// the production `AllPairs` collapse, so the port and the impl compare
+    /// element-for-element.
+    #[derive(Debug, PartialEq, Eq)]
+    enum PortSlot {
+        Pair(u32),
+        Single(u32),
+    }
+
+    /// Literal port of bwa-mem3's `bseq_classify` (`bwa.cpp:258-274`): walk the
+    /// flat read-name stream, pairing two consecutive reads iff their names are
+    /// equal, else emitting a single, tracking each group's ordinal.
+    fn port_bseq_classify(names: &[&[u8]]) -> Vec<PortSlot> {
+        let mut out = Vec::new();
+        let mut pair_idx: u32 = 0;
+        let mut single_idx: u32 = 0;
+        let mut i = 0;
+        while i < names.len() {
+            if i + 1 < names.len() && names[i] == names[i + 1] {
+                out.push(PortSlot::Pair(pair_idx));
+                pair_idx += 1;
+                i += 2;
+            } else {
+                out.push(PortSlot::Single(single_idx));
+                single_idx += 1;
+                i += 1;
+            }
+        }
+        out
+    }
+
+    /// Normalize a [`Layout`] to the port's per-template slot list so the two are
+    /// directly comparable (`AllPairs` expands to consecutive `Pair` slots).
+    fn layout_to_port_slots(layout: &Layout, n_templates: usize) -> Vec<PortSlot> {
+        match layout {
+            Layout::AllPairs => {
+                (0..u32::try_from(n_templates).unwrap()).map(PortSlot::Pair).collect()
+            }
+            Layout::Mixed(slots) => slots
+                .iter()
+                .map(|slot| match *slot {
+                    TemplateSlot::Pair { idx } => PortSlot::Pair(idx),
+                    TemplateSlot::Single { idx } => PortSlot::Single(idx),
+                })
+                .collect(),
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn layout_matches_bseq_classify(
+            // `true` = paired template (2 reads), `false` = single (1 read).
+            template_is_pair in prop::collection::vec(any::<bool>(), 1..64),
+        ) {
+            // Each template gets a globally unique name (its index), upholding
+            // the `GroupByQueryname` invariant that no two *consecutive*
+            // templates share a name — so `bseq_classify` pairs exactly the
+            // two-read templates.
+            let names: Vec<Vec<u8>> = (0..template_is_pair.len())
+                .map(|i| i.to_le_bytes().to_vec())
+                .collect();
+
+            // Build the flat read-name stream (each template's name repeated per
+            // surviving read) and the per-template read counts.
+            let mut flat_names: Vec<&[u8]> = Vec::new();
+            let mut read_counts: Vec<u8> = Vec::new();
+            for (i, &is_pair) in template_is_pair.iter().enumerate() {
+                let count: u8 = if is_pair { 2 } else { 1 };
+                read_counts.push(count);
+                for _ in 0..count {
+                    flat_names.push(names[i].as_slice());
+                }
+            }
+
+            let want = port_bseq_classify(&flat_names);
+            let layout = Layout::classify(&read_counts);
+            let got = layout_to_port_slots(&layout, template_is_pair.len());
+            prop_assert_eq!(got, want);
+
+            // The `AllPairs` collapse must fire exactly when every template pairs.
+            let all_pairs = template_is_pair.iter().all(|&p| p);
+            prop_assert_eq!(matches!(layout, Layout::AllPairs), all_pairs);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // id_bases vs. worker_sam / fastmap id assignment
+    // -------------------------------------------------------------------------
+
+    #[derive(Clone, Copy, Debug)]
+    enum Kind {
+        Single,
+        Pair,
+    }
+
+    /// Count the [`Kind::Single`] items in an iterator as a `u64`.
+    fn count_singles<'a>(kinds: impl Iterator<Item = &'a Kind>) -> u64 {
+        u64::try_from(kinds.filter(|k| matches!(k, Kind::Single)).count())
+            .expect("cohort single count fits u64")
+    }
+
+    /// First single/pair ids a sub-batch would be assigned, computed by a
+    /// literal port of the upstream rule (`fastmap.cpp:924-944` +
+    /// `bwamem.cpp:2795-2884`): the cohort's SE group runs at
+    /// `n_processed = base`, its PE group at `n_processed = base + cohort_n_se`,
+    /// and `worker_sam` numbers single `k` as `n_processed + k` and pair `k` as
+    /// `(n_processed >> 1) + k`, where `k` is the group-global ordinal (= the
+    /// count of same-kind items in earlier sub-batches).
+    fn port_id_bases(base: u64, sub_batches: &[Vec<Kind>]) -> Vec<IdBases> {
+        let cohort_n_se = count_singles(sub_batches.iter().flatten());
+        let se_n_processed = base;
+        let pe_n_processed = base + cohort_n_se;
+
+        let mut se_seen: u64 = 0;
+        let mut pe_seen: u64 = 0;
+        let mut out = Vec::with_capacity(sub_batches.len());
+        for sub in sub_batches {
+            out.push(IdBases {
+                first_single_id: se_n_processed + se_seen,
+                first_pair_id: (pe_n_processed >> 1) + pe_seen,
+            });
+            for kind in sub {
+                match kind {
+                    Kind::Single => se_seen += 1,
+                    Kind::Pair => pe_seen += 1,
+                }
+            }
+        }
+        out
+    }
+
+    /// Build a [`CohortPos`] per sub-batch (tracking the same SE/PE offsets the
+    /// prepare step would) and evaluate [`id_bases`] for each.
+    // `n_se`/`n_pe` are the domain terms (they are also the `CohortPos` field
+    // names); the pair reads more clearly as a pair than renamed apart.
+    #[allow(clippy::similar_names)]
+    fn id_bases_over_cohort(base: u64, sub_batches: &[Vec<Kind>]) -> Vec<IdBases> {
+        let cohort_n_se = count_singles(sub_batches.iter().flatten());
+
+        let mut se_offset: u64 = 0;
+        let mut pe_offset: u64 = 0;
+        let mut out = Vec::with_capacity(sub_batches.len());
+        for sub in sub_batches {
+            let n_se = u32::try_from(sub.iter().filter(|k| matches!(k, Kind::Single)).count())
+                .expect("sub-batch single count fits u32");
+            let n_pe = u32::try_from(sub.iter().filter(|k| matches!(k, Kind::Pair)).count())
+                .expect("sub-batch pair count fits u32");
+            let pos = CohortPos { cohort_read_base: base, se_offset, pe_offset, n_se, n_pe };
+            out.push(id_bases(&pos, cohort_n_se));
+            se_offset += u64::from(n_se);
+            pe_offset += u64::from(n_pe);
+        }
+        out
+    }
+
+    proptest! {
+        #[test]
+        fn id_bases_matches_worker_sam_port(
+            // Even base: bwa's `n_processed` at a cohort start is a sum of
+            // earlier (even-parity) cohort read counts. The `>> 1` is exercised
+            // by odd `base + cohort_n_se` values regardless.
+            base_half in 0u64..500_000,
+            sub_batches in prop::collection::vec(
+                prop::collection::vec(
+                    prop_oneof![Just(Kind::Single), Just(Kind::Pair)],
+                    0..12,
+                ),
+                1..25,
+            ),
+        ) {
+            let base = base_half * 2;
+            let want = port_id_bases(base, &sub_batches);
+            let got = id_bases_over_cohort(base, &sub_batches);
+            prop_assert_eq!(got, want);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Item HeapSize
+    // -------------------------------------------------------------------------
+
+    /// The item `HeapSize` is the moved templates' heap footprint alone: the
+    /// C-side reads and regions belong to the cohort's resident state, not to any
+    /// one sub-batch. Tested through the shared `work_heap_size` helper the
+    /// `ExtendedWork`/`PairWork` impls delegate to.
+    #[test]
+    fn work_heap_size_sums_the_templates() {
+        let templates = vec![Template::new(), Template::new()];
+        let templates_bytes: usize = templates.iter().map(Template::heap_size).sum();
+
+        assert_eq!(work_heap_size(&templates), templates_bytes);
+        assert_eq!(work_heap_size(&[]), 0);
+    }
+
+    /// Compile + wiring check for the pure work item: `AlignWork` (which carries
+    /// no regs) is constructible from the pure types and its `HeapSize` is the
+    /// templates' footprint.
+    #[test]
+    fn align_work_heap_size_matches_templates() {
+        let work = AlignWork {
+            id: SubBatchId { serial: 0, cohort: 0, index_in_cohort: 0 },
+            pos: CohortPos { cohort_read_base: 0, se_offset: 0, pe_offset: 0, n_se: 0, n_pe: 0 },
+            closer: Some(CohortCloser { n_sub_batches: 1, cohort_n_se: 0, cohort_n_pe: 1 }),
+            layout: Layout::AllPairs,
+            unmapped: vec![Template::new()],
+            lease: CohortLease::for_test(),
+        };
+        let expected: usize = work.unmapped.iter().map(Template::heap_size).sum();
+        assert_eq!(work.heap_size(), expected);
+    }
+}
diff --git a/src/lib/pipeline/steps/align/inproc/engine.rs b/src/lib/pipeline/steps/align/inproc/engine.rs
new file mode 100644
index 000000000..80555dba8
--- /dev/null
+++ b/src/lib/pipeline/steps/align/inproc/engine.rs
@@ -0,0 +1,735 @@
+//! The alignment engine adapter: the *single* module that names [`bwa_mem3_rs`].
+//!
+//! The scheduling steps of the in-process backend
+//! (`AlignSeedExtendStep`,
+//! `CohortPeStatStep`,
+//! `AlignPairEmitStep`) drive bwa-mem3's
+//! three-phase `seed_extend -> infer_cohort -> pair_emit` pipeline. They do so
+//! through the [`AlignEngine`] trait rather than calling `bwa_mem3_rs` directly,
+//! for two reasons:
+//!
+//! 1. **Testability without FFI.** `FakeEngine` (a `#[cfg(test)]` sibling) is a
+//!    deterministic, allocation-only stand-in that lets the scheduling/ordering
+//!    tests exercise the real pipeline steps at many thread counts
+//!    and sub-batch sizes without loading a bwa-mem3 index or compiling any C++.
+//! 2. **One seam.** Every mention of `bwa_mem3_rs` types the steps need
+//!    ([`RecordSink`], [`RecordOrigin`], [`IdBases`]) is re-exported from here, so
+//!    the rest of the `inproc` module tree is written against this module, not the
+//!    binding crate.
+//!
+//! The real implementation, [`BwaMem3Engine`], is a thin wrapper over
+//! `bwa_mem3_rs`'s [`ResidentCohort`]: one per `-K` cohort keeps every sub-batch's
+//! reads and alignment regions resident from seed/extend to pair/emit, so no
+//! sub-batch copies or frees them. The engine holds the shared, read-only
+//! `Arc<BwaIndex>` and `Arc<MemOpts>` and maps each trait method onto the
+//! corresponding `ResidentCohort` call. That API is entirely safe, so this module
+//! adds no `unsafe`.
+//!
+//! The engine trait and both impls are consumed by the in-process backend's
+//! steps (`seed_extend`, `pestat`, `pair_emit`) and
+//! this module's tests.
+
+use std::io;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::Instant;
+
+use bwa_mem3_rs::{
+    BwaIndex, MemOpts, MemPeStat, PeOrientation, ReadPair as BwaReadPair, ResidentCohort,
+    ResidentRange, SingleRead as BwaSingleRead,
+};
+
+use super::gate::CohortLease;
+
+// Re-exports for the rest of the `inproc` module tree: these are the only
+// `bwa_mem3_rs` names the scheduling steps reference, and they go through here so
+// `engine.rs` stays the sole module that names the binding crate.
+// `RecordOrigin` is first used outside tests by the pair/emit step added in the
+// following change.
+#[allow(unused_imports)]
+pub(crate) use bwa_mem3_rs::{IdBases, RecordOrigin, RecordSink};
+
+// ---------------------------------------------------------------------------
+// Borrowed input batch (fgumi side)
+// ---------------------------------------------------------------------------
+
+/// One read as borrowed name/seq/qual spans, in the exact bytes bwa-mem3 must
+/// see: `name` is the bare queryname (no `/1`, `/2`, no UMI),
+/// `seq` is ASCII `ACGTN`, and `qual` is Phred+33 (or `None` for `'*'`).
+///
+/// The spans borrow storage owned elsewhere — in production a per-worker
+/// `ReadArena` — so building an [`EngineBatch`] and converting it to a
+/// [`bwa_mem3_rs::ReadBatch`] copies no sequence bytes.
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct EngineRead<'a> {
+    pub(crate) name: &'a [u8],
+    pub(crate) seq: &'a [u8],
+    pub(crate) qual: Option<&'a [u8]>,
+}
+
+impl<'a> EngineRead<'a> {
+    /// Construct a read from its borrowed spans.
+    pub(crate) fn new(name: &'a [u8], seq: &'a [u8], qual: Option<&'a [u8]>) -> Self {
+        Self { name, seq, qual }
+    }
+}
+
+/// A paired-end template's two reads (R1, R2), in input order.
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct EnginePair<'a> {
+    pub(crate) r1: EngineRead<'a>,
+    pub(crate) r2: EngineRead<'a>,
+}
+
+/// A sub-batch of reads to seed+extend, already split into bwa-mem3's `-p` SE/PE
+/// groups (the split is computed by [`super::cohort::Layout`] in the prepare
+/// step). This is the fgumi-side, backend-neutral shape; [`BwaMem3Engine`]
+/// converts it to a [`bwa_mem3_rs::ReadBatch`] borrowing the same spans, and
+/// `FakeEngine` reads only the group lengths.
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct EngineBatch<'a> {
+    pub(crate) pairs: &'a [EnginePair<'a>],
+    pub(crate) singles: &'a [EngineRead<'a>],
+}
+
+// ---------------------------------------------------------------------------
+// The engine trait
+// ---------------------------------------------------------------------------
+
+/// The three-phase bwa-mem3 alignment interface the scheduling steps bind to,
+/// over a **resident cohort**: one `-K` cohort's decoded reads and alignment regions stay
+/// resident in a [`Self::Cohort`] from seed/extend through pair/emit, and each
+/// sub-batch owns only its [`Self::Ranges`] of it. Nothing is copied or freed
+/// per sub-batch; the cohort is freed once, when its last work item drops.
+///
+/// The cohort lives in the sub-batches' shared
+/// [`CohortLease`] (see
+/// [`cohort_of`]), so it is shared across pool workers and must be
+/// `Send + Sync`. `Ranges` and `Scratch` are owned by exactly one work item /
+/// worker at a time and only need `Send`. `PeStat` is inferred once per cohort
+/// on a serial step and shared read-only across the cohort's `pair_emit` items.
+pub(crate) trait AlignEngine: Send + Sync + 'static {
+    /// Per-worker scratch, reused across calls. `Send`, not
+    /// `Sync`: exactly one lives on each pool worker. `'static` because it is
+    /// owned by the `'static` `AlignSeedExtendStep` /
+    /// pair-emit steps.
+    type Scratch: Send + 'static;
+    /// One cohort's resident alignment state, shared by all its sub-batches.
+    type Cohort: Send + Sync + 'static;
+    /// One sub-batch's reserved share of its cohort: produced by
+    /// [`Self::seed_extend`], consumed by [`Self::pair_emit`]. `'static` because
+    /// it rides inside the `'static`
+    /// [`ExtendedWork`](super::cohort::ExtendedWork)/`PairWork` pipeline items.
+    type Ranges: Send + 'static;
+    /// The cohort insert-size model. Shared read-only across a cohort's
+    /// `pair_emit` items, hence `Send + Sync`; `'static` because it is `Arc`'d
+    /// into the `'static` `PairWork` items.
+    type PeStat: Send + Sync + 'static;
+
+    /// Allocate a fresh per-worker scratch.
+    ///
+    /// # Errors
+    /// Propagates the engine's allocation failure.
+    fn new_scratch(&self) -> anyhow::Result<Self::Scratch>;
+
+    /// Allocate an empty resident cohort. Called once per cohort, through
+    /// [`cohort_of`].
+    ///
+    /// # Errors
+    /// Propagates the engine's allocation failure.
+    fn new_cohort(&self) -> anyhow::Result<Self::Cohort>;
+
+    /// Phase 1: reserve `batch`'s share of `cohort`, copy its reads in, and
+    /// seed + SE-extend them — the fused `worker_bwt_aln` work, per-read
+    /// independent. Safe to call concurrently for different
+    /// sub-batches of one cohort.
+    ///
+    /// # Errors
+    /// Propagates an invalid batch or an engine failure.
+    fn seed_extend(
+        &self,
+        scratch: &mut Self::Scratch,
+        cohort: &Self::Cohort,
+        batch: EngineBatch<'_>,
+    ) -> anyhow::Result<Self::Ranges>;
+
+    /// Phase 2 (cohort barrier): the `mem_pestat` insert-size model over every
+    /// paired read of `cohort`. Every sub-batch's
+    /// [`Self::seed_extend`] must have completed. The model is a histogram, so
+    /// it does not depend on the order the sub-batches were extended in.
+    ///
+    /// # Errors
+    /// Propagates an engine failure, including a sub-batch not yet extended.
+    fn infer_cohort(&self, cohort: &Self::Cohort) -> anyhow::Result<Self::PeStat>;
+
+    /// Phase 3: pairing + mate rescue + primary marking + emission for one
+    /// sub-batch — the `worker_sam` work. Consumes `ranges`; emits one packed
+    /// BAM record body per output record through `sink`, tagged with its
+    /// sub-batch-local [`RecordOrigin`], in input order: pairs (R1 side then R2
+    /// side, primary then supplementary), then singles.
+    ///
+    /// `pestat` may be `None` only for a sub-batch with no pairs; passing `None`
+    /// for a sub-batch that classifies pairs is an error.
+    ///
+    /// # Errors
+    /// Propagates a missing-pestat misuse or an engine failure.
+    fn pair_emit(
+        &self,
+        scratch: &mut Self::Scratch,
+        cohort: &Self::Cohort,
+        ranges: Self::Ranges,
+        pestat: Option<&Self::PeStat>,
+        ids: IdBases,
+        sink: &mut dyn RecordSink,
+    ) -> anyhow::Result<()>;
+
+    /// The number of PE templates (pairs) `ranges` holds — used by the barrier
+    /// to decide whether a sub-batch needs the cohort pestat.
+    fn n_pairs(ranges: &Self::Ranges) -> usize;
+
+    /// A human-readable summary of `pestat`, logged by the cohort barrier at
+    /// `info` once per cohort it computes a pestat for — the same information
+    /// bwa's `[M::mem_pestat]` stderr lines carry on the subprocess route. The
+    /// real engine reports the FR
+    /// orientation's insert-size mean/std/low/high, matching upstream's log
+    /// line; `FakeEngine` has no real insert-size model to report.
+    fn pestat_summary(pestat: &Self::PeStat) -> String;
+}
+
+/// The resident cohort of the cohort `lease` belongs to, created through
+/// `engine` by whichever of its sub-batches asks first and freed with the
+/// lease's last clone.
+///
+/// # Errors
+/// Returns an error if the cohort could not be created (the failure is kept,
+/// so every sub-batch of that cohort reports it) or if the lease holds another
+/// backend's state.
+pub(crate) fn cohort_of<'l, E: AlignEngine>(
+    engine: &E,
+    lease: &'l CohortLease,
+) -> io::Result<&'l E::Cohort> {
+    let slot: &Result<E::Cohort, String> =
+        lease.resident(|| engine.new_cohort().map_err(|e| format!("{e:#}")))?;
+    slot.as_ref().map_err(|e| {
+        io::Error::other(format!(
+            "align-and-merge (in-process): creating the cohort's resident aligner state: {e}"
+        ))
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Real engine
+// ---------------------------------------------------------------------------
+
+/// The real in-process bwa-mem3 engine: a thin adapter over the merged
+/// `bwa_mem3_rs` three-phase API. The `BwaIndex` and `MemOpts` are loaded/built
+/// once at wire time and shared read-only across every worker (both are
+/// `Send + Sync`).
+pub(crate) struct BwaMem3Engine {
+    idx: Arc<BwaIndex>,
+    opts: Arc<MemOpts>,
+    /// Wall time (ns) spent *inside* the three `bwa_mem3_rs` FFI calls, summed
+    /// across every pool worker (the engine is shared behind an `Arc`, so these
+    /// are atomics). The pipeline stats table already reports each *step's* total
+    /// busy time (`AlignSeedExtend`/`CohortPeStat`/`AlignPairEmit`), which
+    /// includes the fgumi-side arena fill, read-view conversion, and sink/template
+    /// assembly around each FFI call. Subtracting these FFI totals from the step
+    /// totals splits the cost into "bwa-mem3 C++" vs "fgumi-side overhead" — the
+    /// question the `pair_emit`-vs-`seed_extend` finding raised. Reported once at
+    /// [`Drop`] (i.e. pipeline end), at `debug`, so production runs stay quiet.
+    seed_extend_ns: AtomicU64,
+    seed_extend_calls: AtomicU64,
+    infer_cohort_ns: AtomicU64,
+    infer_cohort_calls: AtomicU64,
+    pair_emit_ns: AtomicU64,
+    pair_emit_calls: AtomicU64,
+}
+
+/// Nanoseconds since `start`, saturating into a `u64` (a `u64` of ns is ~584
+/// years, so the cap is only a formality that avoids a `u128`-to-`u64` panic
+/// path on an absurd clock).
+fn elapsed_ns(start: Instant) -> u64 {
+    u64::try_from(start.elapsed().as_nanos()).unwrap_or(u64::MAX)
+}
+
+impl BwaMem3Engine {
+    /// Wrap a loaded index and built options. Both are shared (`Arc`) so worker
+    /// copies of the steps clone the handles, not the data.
+    pub(crate) fn new(idx: Arc<BwaIndex>, opts: Arc<MemOpts>) -> Self {
+        Self {
+            idx,
+            opts,
+            seed_extend_ns: AtomicU64::new(0),
+            seed_extend_calls: AtomicU64::new(0),
+            infer_cohort_ns: AtomicU64::new(0),
+            infer_cohort_calls: AtomicU64::new(0),
+            pair_emit_ns: AtomicU64::new(0),
+            pair_emit_calls: AtomicU64::new(0),
+        }
+    }
+}
+
+impl Drop for BwaMem3Engine {
+    fn drop(&mut self) {
+        let se_ns = self.seed_extend_ns.load(Ordering::Relaxed);
+        let ic_ns = self.infer_cohort_ns.load(Ordering::Relaxed);
+        let pe_ns = self.pair_emit_ns.load(Ordering::Relaxed);
+        if se_ns == 0 && ic_ns == 0 && pe_ns == 0 {
+            return; // never ran (e.g. wiring failed, or a fake-index test path)
+        }
+        // Precision loss is irrelevant for a human-readable seconds display.
+        #[allow(clippy::cast_precision_loss)]
+        let secs = |ns: u64| ns as f64 / 1e9;
+        log::debug!(
+            "in-process bwa-mem3 FFI CPU (summed across workers): \
+             seed_extend {:.2}s ({} calls), infer_cohort {:.3}s ({} calls), \
+             pair_emit {:.2}s ({} calls). Each step's pipeline-stats total minus \
+             this FFI time is fgumi-side overhead (arena fill / read-view build / \
+             sink+template assembly).",
+            secs(se_ns),
+            self.seed_extend_calls.load(Ordering::Relaxed),
+            secs(ic_ns),
+            self.infer_cohort_calls.load(Ordering::Relaxed),
+            secs(pe_ns),
+            self.pair_emit_calls.load(Ordering::Relaxed),
+        );
+    }
+}
+
+/// A [`BwaMem3Engine`] sub-batch's share of its [`ResidentCohort`]: its pairs'
+/// range and its singles' range, each absent when the sub-batch has none.
+pub(crate) struct BwaRanges {
+    pairs: Option<ResidentRange>,
+    singles: Option<ResidentRange>,
+}
+
+impl AlignEngine for BwaMem3Engine {
+    type Scratch = bwa_mem3_rs::AlignScratch;
+    type Cohort = ResidentCohort;
+    type Ranges = BwaRanges;
+    type PeStat = MemPeStat;
+
+    fn new_scratch(&self) -> anyhow::Result<Self::Scratch> {
+        Ok(bwa_mem3_rs::AlignScratch::new()?)
+    }
+
+    fn new_cohort(&self) -> anyhow::Result<Self::Cohort> {
+        Ok(ResidentCohort::new(self.opts.meth())?)
+    }
+
+    fn seed_extend(
+        &self,
+        scratch: &mut Self::Scratch,
+        cohort: &Self::Cohort,
+        batch: EngineBatch<'_>,
+    ) -> anyhow::Result<Self::Ranges> {
+        let t = Instant::now();
+        // The C side copies each read into its resident slot during
+        // `write_*`; the views here copy no sequence bytes.
+        let mut ranges = BwaRanges { pairs: None, singles: None };
+        if !batch.pairs.is_empty() {
+            let mut range = cohort.reserve_pairs(batch.pairs.len())?;
+            // One batch write takes the cohort's range lock once, not per read.
+            // These borrowed views are rebuilt per call (one small allocation per
+            // sub-batch, not per read): they borrow this sub-batch's arena, so
+            // they cannot live in the `'static` per-worker scratch, and
+            // `write_pairs` needs the whole range in one slice. bwa-mem3-rs then
+            // collects its own same-sized Vec of C structs inside the call.
+            let pairs: Vec<BwaReadPair<'_>> = batch
+                .pairs
+                .iter()
+                .map(|p| BwaReadPair {
+                    name_r1: p.r1.name,
+                    seq_r1: p.r1.seq,
+                    qual_r1: p.r1.qual,
+                    name_r2: p.r2.name,
+                    seq_r2: p.r2.seq,
+                    qual_r2: p.r2.qual,
+                })
+                .collect();
+            cohort.write_pairs(&mut range, &pairs)?;
+            cohort.seed_extend(&self.idx, &self.opts, scratch, &mut range)?;
+            ranges.pairs = Some(range);
+        }
+        if !batch.singles.is_empty() {
+            let mut range = cohort.reserve_singles(batch.singles.len())?;
+            let reads: Vec<BwaSingleRead<'_>> = batch
+                .singles
+                .iter()
+                .map(|r| BwaSingleRead { name: r.name, seq: r.seq, qual: r.qual })
+                .collect();
+            cohort.write_singles(&mut range, &reads)?;
+            cohort.seed_extend(&self.idx, &self.opts, scratch, &mut range)?;
+            ranges.singles = Some(range);
+        }
+        self.seed_extend_ns.fetch_add(elapsed_ns(t), Ordering::Relaxed);
+        self.seed_extend_calls.fetch_add(1, Ordering::Relaxed);
+        Ok(ranges)
+    }
+
+    fn infer_cohort(&self, cohort: &Self::Cohort) -> anyhow::Result<Self::PeStat> {
+        let t = Instant::now();
+        let pestat = cohort.infer_cohort(&self.idx, &self.opts)?;
+        self.infer_cohort_ns.fetch_add(elapsed_ns(t), Ordering::Relaxed);
+        self.infer_cohort_calls.fetch_add(1, Ordering::Relaxed);
+        Ok(pestat)
+    }
+
+    fn pair_emit(
+        &self,
+        scratch: &mut Self::Scratch,
+        cohort: &Self::Cohort,
+        ranges: Self::Ranges,
+        pestat: Option<&Self::PeStat>,
+        ids: IdBases,
+        sink: &mut dyn RecordSink,
+    ) -> anyhow::Result<()> {
+        let t = Instant::now();
+        // Pairs then singles, each tagged with its sub-batch-local origin
+        // (`origin_base` 0) — the order and origins the legacy per-sub-batch
+        // `pair_emit` produced.
+        let BwaRanges { pairs, singles } = ranges;
+        for mut range in [pairs, singles].into_iter().flatten() {
+            cohort.pair_emit(
+                &self.idx, &self.opts, scratch, &mut range, pestat, ids, 0, &mut *sink,
+            )?;
+        }
+        self.pair_emit_ns.fetch_add(elapsed_ns(t), Ordering::Relaxed);
+        self.pair_emit_calls.fetch_add(1, Ordering::Relaxed);
+        Ok(())
+    }
+
+    fn n_pairs(ranges: &Self::Ranges) -> usize {
+        ranges.pairs.as_ref().map_or(0, ResidentRange::n_pairs)
+    }
+
+    fn pestat_summary(pestat: &Self::PeStat) -> String {
+        // FR is the orientation `mem_pestat`/`worker_sam` actually uses for
+        // insert-size-aware mate rescue in the common (non-mate-pair) case;
+        // upstream's `[M::mem_pestat]` line reports the same orientation.
+        let fr = pestat.orientation(PeOrientation::Fr);
+        format!(
+            "FR insert mean={mean:.1} std={std:.1} low={low} high={high}{failed}",
+            mean = fr.avg,
+            std = fr.std,
+            low = fr.low,
+            high = fr.high,
+            failed = if fr.failed { " (failed)" } else { "" },
+        )
+    }
+}
+
+#[cfg(test)]
+pub(crate) mod fake {
+    //! A deterministic, FFI-free [`AlignEngine`] for the scheduling/ordering tests.
+    //!
+    //! `seed_extend` records one [`TaggedRead`] per input read, in bwa-mem3's
+    //! emission order — for each pair `i` an R1 then an R2 read tagged
+    //! [`RecordOrigin::Pair(i)`], then for each single `j` one read tagged
+    //! [`RecordOrigin::Single(j)`] (bwa emits pairs, R1 then R2, then singles).
+    //! `pair_emit` replays that recorded order, emitting one
+    //! **minimal-valid packed-BAM record body** per read through the sink tagged
+    //! with its origin, so a scheduling test can assert records come back grouped
+    //! by origin in input order — and, crucially for
+    //! `AlignPairEmitStep`, so
+    //! [`Template::from_records`](crate::template::Template::from_records) can
+    //! actually parse and group them and expose a `read_name()`/`flags()` for the
+    //! name-match guard. Every read of a pair `i` gets the same synthetic name
+    //! ([`fake_record_name`]) so its two records collapse into one template;
+    //! `mate` picks `FIRST_SEGMENT`/`LAST_SEGMENT` so the pair has exactly one
+    //! primary R1 and one primary R2. `infer_cohort` returns a unit `PeStat`; no
+    //! FFI is called anywhere. The fake's cohort only counts the pairs seeded
+    //! into it; its "ranges" are the recorded reads themselves.
+    //!
+    //! The body is a fixed 4-base record, so it is not usable to assert per-pair
+    //! record *counts* (a real engine emits supplementaries; this fake never
+    //! does) — only grouping, ordering, and guard-firing.
+
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    use fgumi_raw_bam::{SamBuilder, flags};
+
+    use super::{AlignEngine, EngineBatch, IdBases, RecordOrigin, RecordSink};
+
+    /// The fake's resident cohort: how many pairs its sub-batches have seeded.
+    #[derive(Debug, Default)]
+    pub(crate) struct FakeCohort {
+        pub(crate) seeded_pairs: AtomicUsize,
+    }
+
+    /// The synthetic queryname [`FakeEngine::pair_emit`] stamps on every record of
+    /// an origin, so a pair's two records share one QNAME and collapse into one
+    /// [`Template`](crate::template::Template) whose `name()` a test can predict
+    /// (to line up — or deliberately mismatch — the unmapped half's name for the
+    /// name-match guard). Both records of `Pair(i)` get the same name; each
+    /// `Single(j)` gets its own.
+    pub(crate) fn fake_record_name(origin: RecordOrigin) -> Vec<u8> {
+        match origin {
+            RecordOrigin::Pair(i) => format!("fakepair{i}").into_bytes(),
+            RecordOrigin::Single(j) => format!("fakesingle{j}").into_bytes(),
+        }
+    }
+
+    /// One recorded input read: its [`RecordOrigin`] (which input pair/single it
+    /// came from) and `mate` (0 for R1 or a single, 1 for R2) so the body is
+    /// deterministic and the R1/R2 order within a pair is inspectable.
+    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+    pub(crate) struct TaggedRead {
+        pub(crate) origin: RecordOrigin,
+        pub(crate) mate: u8,
+    }
+
+    /// The deterministic, FFI-free engine.
+    #[derive(Clone, Copy, Debug, Default)]
+    pub(crate) struct FakeEngine;
+
+    impl AlignEngine for FakeEngine {
+        type Scratch = ();
+        type Cohort = FakeCohort;
+        type Ranges = Vec<TaggedRead>;
+        type PeStat = ();
+
+        fn new_scratch(&self) -> anyhow::Result<Self::Scratch> {
+            Ok(())
+        }
+
+        fn new_cohort(&self) -> anyhow::Result<Self::Cohort> {
+            Ok(FakeCohort::default())
+        }
+
+        fn seed_extend(
+            &self,
+            _scratch: &mut Self::Scratch,
+            cohort: &Self::Cohort,
+            batch: EngineBatch<'_>,
+        ) -> anyhow::Result<Self::Ranges> {
+            cohort.seeded_pairs.fetch_add(batch.pairs.len(), Ordering::Relaxed);
+            // Emission order: every pair (R1 then R2) in pair
+            // index order, then every single in single index order.
+            let mut reads = Vec::with_capacity(batch.pairs.len() * 2 + batch.singles.len());
+            for i in 0..batch.pairs.len() {
+                reads.push(TaggedRead { origin: RecordOrigin::Pair(i), mate: 0 });
+                reads.push(TaggedRead { origin: RecordOrigin::Pair(i), mate: 1 });
+            }
+            for j in 0..batch.singles.len() {
+                reads.push(TaggedRead { origin: RecordOrigin::Single(j), mate: 0 });
+            }
+            Ok(reads)
+        }
+
+        fn infer_cohort(&self, _cohort: &Self::Cohort) -> anyhow::Result<Self::PeStat> {
+            Ok(())
+        }
+
+        fn pair_emit(
+            &self,
+            _scratch: &mut Self::Scratch,
+            _cohort: &Self::Cohort,
+            regs: Self::Ranges,
+            _pestat: Option<&Self::PeStat>,
+            _ids: IdBases,
+            sink: &mut dyn RecordSink,
+        ) -> anyhow::Result<()> {
+            // Replay the recorded reads in emission order, one minimal-valid
+            // packed-BAM record body per read tagged with its origin. Each record
+            // is a real 4-base BAM record (built via `SamBuilder`, whose output is
+            // a body with no `block_size` prefix — exactly a `RecordSink` body), so
+            // `RawRecord::from(body)` + `Template::from_records` parse and group
+            // them: a pair's two records share one name and split R1/R2 by `mate`.
+            for read in &regs {
+                let name = fake_record_name(read.origin);
+                let record_flags = match read.origin {
+                    RecordOrigin::Pair(_) => {
+                        flags::PAIRED
+                            | if read.mate == 0 {
+                                flags::FIRST_SEGMENT
+                            } else {
+                                flags::LAST_SEGMENT
+                            }
+                    }
+                    RecordOrigin::Single(_) => 0,
+                };
+                let mut builder = SamBuilder::new();
+                builder
+                    .read_name(&name)
+                    .flags(record_flags)
+                    .sequence(b"ACGT")
+                    .qualities(&[30u8, 30, 30, 30]);
+                let record = builder.build();
+                sink.emit(read.origin, record.as_ref());
+            }
+            Ok(())
+        }
+
+        fn n_pairs(regs: &Self::Ranges) -> usize {
+            // Each pair contributed two reads; count the R1 side (mate == 0) to
+            // recover the number of PE templates.
+            regs.iter().filter(|r| matches!(r.origin, RecordOrigin::Pair(_)) && r.mate == 0).count()
+        }
+
+        fn pestat_summary(_pestat: &Self::PeStat) -> String {
+            // `PeStat = ()`: no real insert-size model to report.
+            "n/a (FakeEngine)".to_string()
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::fake::FakeEngine;
+    use super::{AlignEngine, EngineBatch, EnginePair, EngineRead, IdBases};
+    use bwa_mem3_rs::{RecordOrigin, RecordVec};
+
+    /// Build a two-pair, one-single [`EngineBatch`] borrowing local buffers.
+    fn sample_batch<'a>(
+        pairs: &'a [EnginePair<'a>],
+        singles: &'a [EngineRead<'a>],
+    ) -> EngineBatch<'a> {
+        EngineBatch { pairs, singles }
+    }
+
+    // `FakeEngine`'s `Scratch` and `PeStat` are the unit type, so binding the
+    // values these driving calls return trips `let_unit_value`. Keeping the
+    // bindings mirrors how a real step drives the engine, which is the point of
+    // the test, so the lint is allowed locally.
+    #[allow(clippy::let_unit_value)]
+    #[test]
+    fn fake_engine_emits_reads_grouped_by_origin_in_input_order() {
+        let engine = FakeEngine;
+        let mut scratch = engine.new_scratch().expect("scratch");
+
+        let pairs = [
+            EnginePair {
+                r1: EngineRead::new(b"pair0", b"ACGT", None),
+                r2: EngineRead::new(b"pair0", b"TGCA", None),
+            },
+            EnginePair {
+                r1: EngineRead::new(b"pair1", b"AACC", None),
+                r2: EngineRead::new(b"pair1", b"GGTT", None),
+            },
+        ];
+        let singles = [EngineRead::new(b"sng0", b"NNNN", None)];
+        let batch = sample_batch(&pairs, &singles);
+
+        let cohort = engine.new_cohort().expect("cohort");
+        let regs = engine.seed_extend(&mut scratch, &cohort, batch).expect("seed_extend");
+
+        // n_pairs counts PE templates (not reads); the ranges hold one entry per read.
+        assert_eq!(FakeEngine::n_pairs(&regs), 2);
+        assert_eq!(regs.len(), 2 * 2 + 1);
+        assert_eq!(cohort.seeded_pairs.load(std::sync::atomic::Ordering::Relaxed), 2);
+
+        let pestat = engine.infer_cohort(&cohort).expect("infer_cohort");
+
+        let ids = IdBases { first_single_id: 100, first_pair_id: 7 };
+        let mut sink = RecordVec::default();
+        engine
+            .pair_emit(&mut scratch, &cohort, regs, Some(&pestat), ids, &mut sink)
+            .expect("pair_emit");
+
+        // Every input read produced exactly one record, in emission order:
+        // pair 0 (R1, R2), pair 1 (R1, R2), then single 0.
+        let origins: Vec<RecordOrigin> = sink.records.iter().map(|(o, _)| *o).collect();
+        assert_eq!(
+            origins,
+            vec![
+                RecordOrigin::Pair(0),
+                RecordOrigin::Pair(0),
+                RecordOrigin::Pair(1),
+                RecordOrigin::Pair(1),
+                RecordOrigin::Single(0),
+            ],
+        );
+        // Bodies are non-empty and deterministic.
+        assert!(sink.records.iter().all(|(_, body)| !body.is_empty()));
+    }
+
+    #[allow(clippy::let_unit_value)] // `FakeEngine::Scratch` is `()`; see the note above.
+    #[test]
+    fn fake_engine_handles_pure_single_and_empty_batches() {
+        let engine = FakeEngine;
+        let mut scratch = engine.new_scratch().expect("scratch");
+
+        // Pure-single batch: no pairs, so a `None` pestat is valid.
+        let singles =
+            [EngineRead::new(b"sng0", b"ACG", None), EngineRead::new(b"sng1", b"GTA", None)];
+        let batch = EngineBatch { pairs: &[], singles: &singles };
+        let cohort = engine.new_cohort().expect("cohort");
+        let regs = engine.seed_extend(&mut scratch, &cohort, batch).expect("seed_extend");
+        assert_eq!(FakeEngine::n_pairs(&regs), 0);
+
+        let mut sink = RecordVec::default();
+        engine
+            .pair_emit(&mut scratch, &cohort, regs, None, IdBases::default(), &mut sink)
+            .expect("emit");
+        let origins: Vec<RecordOrigin> = sink.records.iter().map(|(o, _)| *o).collect();
+        assert_eq!(origins, vec![RecordOrigin::Single(0), RecordOrigin::Single(1)]);
+
+        // Empty batch: no reads, no records.
+        let empty = EngineBatch { pairs: &[], singles: &[] };
+        let regs = engine.seed_extend(&mut scratch, &cohort, empty).expect("seed_extend");
+        assert_eq!(regs.len(), 0);
+        let mut sink = RecordVec::default();
+        engine
+            .pair_emit(&mut scratch, &cohort, regs, None, IdBases::default(), &mut sink)
+            .expect("emit");
+        assert!(sink.records.is_empty());
+    }
+
+    /// Smoke test for the real [`super::BwaMem3Engine`] over the full three-phase
+    /// flow. Requires a prebuilt bwa-mem3 index at `FGUMI_BWA_MEM3_TEST_REF` (the
+    /// index prefix). Skips cleanly when it is unset, unless
+    /// `FGUMI_BWA_MEM3_REQUIRE_TOOLS` is set — as in the e2e-parity CI job — in
+    /// which case a missing index is a hard failure rather than a silent pass.
+    #[test]
+    fn bwa_mem3_engine_smoke_pair_emit() {
+        use std::sync::Arc;
+
+        use super::BwaMem3Engine;
+
+        let Ok(prefix) = std::env::var("FGUMI_BWA_MEM3_TEST_REF") else {
+            assert!(
+                std::env::var_os("FGUMI_BWA_MEM3_REQUIRE_TOOLS").is_none(),
+                "FGUMI_BWA_MEM3_REQUIRE_TOOLS is set but FGUMI_BWA_MEM3_TEST_REF (a bwa-mem3 \
+                 index prefix) is not"
+            );
+            eprintln!("skipping: FGUMI_BWA_MEM3_TEST_REF not set");
+            return;
+        };
+
+        let idx = Arc::new(bwa_mem3_rs::BwaIndex::load(&prefix).expect("load index"));
+        let mut opts = bwa_mem3_rs::MemOpts::new().expect("opts");
+        opts.set_pe(true);
+        let engine = BwaMem3Engine::new(idx, Arc::new(opts));
+
+        let mut scratch = engine.new_scratch().expect("scratch");
+
+        // One PE pair of short reads. The engine emits at least one record
+        // (unmapped if nothing aligns) for each mate, all tagged `Pair(0)`.
+        let pairs = [EnginePair {
+            r1: EngineRead::new(b"read1", b"ACGTACGTACGTACGTACGT", Some(b"IIIIIIIIIIIIIIIIIIII")),
+            r2: EngineRead::new(b"read1", b"TACGTACGTACGTACGTACG", Some(b"IIIIIIIIIIIIIIIIIIII")),
+        }];
+        let batch = EngineBatch { pairs: &pairs, singles: &[] };
+
+        let cohort = engine.new_cohort().expect("cohort");
+        let regs = engine.seed_extend(&mut scratch, &cohort, batch).expect("seed_extend");
+        assert_eq!(BwaMem3Engine::n_pairs(&regs), 1, "one PE template was seeded");
+        let pestat = engine.infer_cohort(&cohort).expect("infer_cohort");
+
+        let ids = IdBases { first_single_id: 0, first_pair_id: 0 };
+        let mut sink = RecordVec::default();
+        engine
+            .pair_emit(&mut scratch, &cohort, regs, Some(&pestat), ids, &mut sink)
+            .expect("pair_emit");
+        assert!(
+            sink.records.len() >= 2,
+            "expected >= 1 record per mate, got {}",
+            sink.records.len()
+        );
+        assert!(
+            sink.records.iter().all(|(origin, _)| *origin == RecordOrigin::Pair(0)),
+            "every record is tagged with the one pair's origin"
+        );
+    }
+}
diff --git a/src/lib/pipeline/steps/align/inproc/gate.rs b/src/lib/pipeline/steps/align/inproc/gate.rs
new file mode 100644
index 000000000..ef9c79697
--- /dev/null
+++ b/src/lib/pipeline/steps/align/inproc/gate.rs
@@ -0,0 +1,415 @@
+//! `CohortGate` — the in-process backend's cohort-granularity byte budget, and
+//! the [`CohortLease`] that reserves one `-K` cohort against it.
+//!
+//! The in-process prepare step admits input one whole cohort at a time: it
+//! reserves the cohort's bytes with a single non-blocking
+//! [`CohortGate::try_acquire_cohort`] (a pool step must never block a worker
+//! inside `try_run`), clones the returned lease into every work item of the
+//! cohort, and the reservation is released exactly once, when the last clone
+//! drops. The gate also drives the pool scheduler's refill signal (see
+//! [`CohortGate::with_refill_signal`]).
+//!
+//! The subprocess backend's blocking writer/reader byte gate is the separate
+//! [`InFlightGate`](super::super::InFlightGate); the two share only the
+//! per-base byte estimate.
+
+use std::any::Any;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, OnceLock};
+
+use parking_lot::Mutex;
+
+use super::super::IN_FLIGHT_BYTES_PER_BASE;
+
+/// Upper bound (bases) a single template can add on top of a `-K` cohort. A
+/// cohort closes only once its accumulated bases have reached `-K` *and* the
+/// read count is even, so it can overshoot `-K` by at most the last template
+/// admitted. A generous constant (covers long-read templates) since the derived
+/// `bound` is only an over-estimate used to size the two-cohort byte budget.
+const MAX_TEMPLATE_BASES: u64 = 1_000_000;
+
+/// Number of `-K` cohorts the in-process backend keeps resident at once: one
+/// pairing/merging while the next seeds, matching bwa's own `kt_pipeline`
+/// double-buffering.
+const IN_PROCESS_COHORTS_IN_FLIGHT: u64 = 2;
+
+/// Byte reservation for one in-process `-K` cohort: `(chunk_size +
+/// MAX_TEMPLATE_BASES) × IN_FLIGHT_BYTES_PER_BASE` — the cohort's `-K` bases
+/// plus a one-template overshoot, priced at the per-base estimate. The
+/// [`CohortGate`] budget is [`IN_PROCESS_COHORTS_IN_FLIGHT`] × this.
+#[must_use]
+pub(crate) fn cohort_bound_for_chunk_size(chunk_size_bases: u64) -> u64 {
+    chunk_size_bases.saturating_add(MAX_TEMPLATE_BASES).saturating_mul(IN_FLIGHT_BYTES_PER_BASE)
+}
+
+/// The in-process backend's two-cohort byte budget for a given per-cohort
+/// `bound` ([`cohort_bound_for_chunk_size`]). Replaces the subprocess
+/// `4×`-slack formula (which existed for FASTQ-pipe buffering that the
+/// in-process path does not have) with an explicit two-cohort budget of the
+/// same magnitude.
+#[must_use]
+pub(crate) fn in_process_gate_budget(cohort_bound: u64) -> u64 {
+    cohort_bound.saturating_mul(IN_PROCESS_COHORTS_IN_FLIGHT)
+}
+
+/// Non-blocking cohort-granularity byte gate for the in-process backend.
+///
+/// Admits a cohort when the gate is empty (an oversized cohort always passes an
+/// empty gate, so a single cohort larger than the whole budget cannot deadlock)
+/// or when its reservation fits under `budget`. Never blocks: a refused
+/// admission returns `None` and the prepare step retries later.
+pub(crate) struct CohortGate {
+    budget: u64,
+    inner: Mutex<CohortGateInner>,
+    /// The pool scheduler's refill signal (see [`Self::with_refill_signal`]).
+    /// `None` for a gate built with [`Self::new`] (tests).
+    refill: Option<RefillSignal>,
+}
+
+struct CohortGateInner {
+    in_flight: u64,
+    /// The prepare step holds an open cohort it is still filling with input.
+    filling: bool,
+}
+
+/// The gate's "refill wanted" signal, read by
+/// [`RefillDrainScheduler`](crate::pipeline::core::runtime::RefillDrainScheduler).
+struct RefillSignal {
+    raised: Arc<AtomicBool>,
+    /// One cohort's reservation, to tell whether another cohort would fit.
+    cohort_bound: u64,
+}
+
+impl CohortGate {
+    /// A gate over `budget` bytes with no refill signal.
+    pub(crate) fn new(budget: u64) -> Self {
+        Self {
+            budget,
+            inner: Mutex::new(CohortGateInner { in_flight: 0, filling: false }),
+            refill: None,
+        }
+    }
+
+    /// A gate that also drives a pool-scheduler refill signal. The signal is
+    /// raised while the prepare step is filling an open cohort, or while the
+    /// gate has room to admit another cohort: in both states the next input must
+    /// be read and decoded, so upstream steps should run. It is lowered only
+    /// when every admitted cohort has been fully read and the gate is full, when
+    /// draining downstream work is all that helps. Without it, drain-first
+    /// dispatch keeps every worker on the heavy downstream steps and never reads
+    /// ahead, so seed/extend later waits on just-in-time decoding.
+    pub(crate) fn with_refill_signal(budget: u64, cohort_bound: u64) -> Self {
+        let raised = Arc::new(AtomicBool::new(true));
+        Self { refill: Some(RefillSignal { raised, cohort_bound }), ..Self::new(budget) }
+    }
+
+    /// The refill signal, if this gate drives one.
+    pub(crate) fn refill_signal(&self) -> Option<Arc<AtomicBool>> {
+        self.refill.as_ref().map(|r| Arc::clone(&r.raised))
+    }
+
+    /// Recompute the refill signal from the gate state `g` (held under the lock,
+    /// so transitions publish in order).
+    fn update_refill(&self, g: &CohortGateInner) {
+        if let Some(r) = &self.refill {
+            let has_room =
+                g.in_flight == 0 || g.in_flight.saturating_add(r.cohort_bound) <= self.budget;
+            r.raised.store(g.filling || has_room, Ordering::Relaxed);
+        }
+    }
+
+    /// The prepare step closed its open cohort: it no longer needs input for it.
+    pub(crate) fn cohort_filled(&self) {
+        let mut g = self.inner.lock();
+        g.filling = false;
+        self.update_refill(&g);
+    }
+
+    /// Reserve `bound` bytes for a whole cohort, returning a [`CohortLease`] on
+    /// success and `None` (never blocking) on refusal.
+    ///
+    /// Admits when the gate is empty (`in_flight == 0`) OR when the reservation
+    /// fits under budget (`in_flight + bound <= budget`). Non-blocking because
+    /// the prepare step is a pool step and must never block a worker inside
+    /// `try_run`.
+    ///
+    /// The returned lease is cloned into every work item of the cohort; the
+    /// reservation is released exactly once, when the last clone drops
+    /// (including on the error path). Takes `&Arc<Self>` so the lease can hold an
+    /// owning handle to the gate for its release-on-drop.
+    pub(crate) fn try_acquire_cohort(self: &Arc<Self>, bound: u64) -> Option<CohortLease> {
+        let mut g = self.inner.lock();
+        if g.in_flight == 0 || g.in_flight.saturating_add(bound) <= self.budget {
+            g.in_flight = g.in_flight.saturating_add(bound);
+            g.filling = true;
+            self.update_refill(&g);
+            drop(g);
+            Some(CohortLease::new(Arc::clone(self), bound))
+        } else {
+            None
+        }
+    }
+
+    /// Release a cohort's `bound` bytes: called exactly once per admitted cohort,
+    /// from [`CohortLeaseInner::drop`].
+    fn release(&self, bound: u64) {
+        let mut g = self.inner.lock();
+        g.in_flight = g.in_flight.saturating_sub(bound);
+        self.update_refill(&g);
+    }
+
+    /// Current in-flight byte reservation. Test-only probe for the cohort-lease
+    /// accounting (production code never reads it — admission uses the check
+    /// inside the lock in [`Self::try_acquire_cohort`]).
+    #[cfg(test)]
+    pub(crate) fn in_flight_bytes(&self) -> u64 {
+        self.inner.lock().in_flight
+    }
+}
+
+/// An `Arc`-refcounted reservation of one in-process `-K` cohort's bytes against
+/// the [`CohortGate`].
+///
+/// [`CohortGate::try_acquire_cohort`] mints one when a cohort opens; the prepare
+/// step clones it into every `AlignWork` of that cohort, and each later stage
+/// moves it forward. The reservation is released exactly once — when the *last*
+/// clone drops (the inner `Arc` reaches zero refcount, running
+/// [`CohortLeaseInner::drop`]). That covers both the normal path (pair/emit
+/// drops each sub-batch's clone once the sub-batch is emitted) and the error
+/// path (a step's `Drop` frees any items it still holds).
+#[derive(Clone)]
+pub(crate) struct CohortLease(Arc<CohortLeaseInner>);
+
+/// The refcounted body of a [`CohortLease`]: it owns a handle to the gate and
+/// the reserved byte count, and releases the reservation in its `Drop` — which
+/// runs exactly once, when the last `CohortLease` clone (hence the last `Arc`)
+/// is dropped.
+struct CohortLeaseInner {
+    gate: Arc<CohortGate>,
+    bound: u64,
+    /// The cohort's resident aligner state (the engine's `ResidentCohort`: every
+    /// sub-batch's decoded reads and alignment regions, kept resident from
+    /// seed/extend through pair/emit). Created by the first sub-batch that needs
+    /// it and freed with the lease, i.e. exactly once, after the cohort's last
+    /// work item drops. Type-erased so the lease does not depend on the engine;
+    /// see [`CohortLease::resident`].
+    resident: OnceLock<Box<dyn Any + Send + Sync>>,
+}
+
+impl CohortLease {
+    /// Wrap a freshly-reserved gate handle. Called only from
+    /// [`CohortGate::try_acquire_cohort`], which has already added `bound` to the
+    /// gate's in-flight total; the matching subtraction happens in
+    /// [`CohortLeaseInner::drop`].
+    fn new(gate: Arc<CohortGate>, bound: u64) -> Self {
+        Self(Arc::new(CohortLeaseInner { gate, bound, resident: OnceLock::new() }))
+    }
+
+    /// This cohort's resident state of type `T`, created by `init` on the first
+    /// call from any clone of the lease (concurrent first calls race to `init`,
+    /// and exactly one result is kept). Every later call, from any clone,
+    /// returns the same value. It lives until the last clone of the lease drops.
+    ///
+    /// # Errors
+    /// Returns an error if the slot already holds a value of a different type,
+    /// which would mean two engines shared one lease.
+    pub(crate) fn resident<T: Any + Send + Sync>(
+        &self,
+        init: impl FnOnce() -> T,
+    ) -> std::io::Result<&T> {
+        self.0.resident.get_or_init(|| Box::new(init())).downcast_ref::<T>().ok_or_else(|| {
+            std::io::Error::other(format!(
+                "cohort lease already holds resident state of a type other than {}",
+                std::any::type_name::<T>()
+            ))
+        })
+    }
+
+    /// A self-contained lease over a throwaway, unbounded gate, for tests that
+    /// need to populate a work item's `lease` field without wiring a real gate.
+    /// It owns its gate, so dropping it is a self-contained no-op.
+    #[cfg(test)]
+    pub(crate) fn for_test() -> Self {
+        Arc::new(CohortGate::new(u64::MAX))
+            .try_acquire_cohort(0)
+            .expect("empty gate admits a test lease")
+    }
+}
+
+impl std::fmt::Debug for CohortLease {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("CohortLease")
+            .field("bound", &self.0.bound)
+            .field("clones", &Arc::strong_count(&self.0))
+            .finish()
+    }
+}
+
+impl Drop for CohortLeaseInner {
+    fn drop(&mut self) {
+        self.gate.release(self.bound);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The gate's refill signal across a cohort's life, with room for two
+    /// cohorts: raised while a cohort is open or another would fit, lowered only
+    /// when both admitted cohorts are filled and the gate is full.
+    #[test]
+    fn refill_signal_follows_cohort_admission_and_release() {
+        let gate = Arc::new(CohortGate::with_refill_signal(200, 100));
+        let signal = gate.refill_signal().expect("the gate has a signal");
+        let raised = || signal.load(Ordering::Relaxed);
+        assert!(raised(), "an empty gate wants input");
+
+        let first = gate.try_acquire_cohort(100).expect("first cohort fits");
+        assert!(raised(), "filling the first cohort");
+        gate.cohort_filled();
+        assert!(raised(), "room for a second cohort");
+
+        let second = gate.try_acquire_cohort(100).expect("second cohort fits");
+        assert!(raised(), "filling the second cohort");
+        gate.cohort_filled();
+        assert!(!raised(), "both cohorts filled and the gate full");
+
+        drop(first);
+        assert!(raised(), "a released cohort makes room again");
+        drop(second);
+        assert!(raised(), "an empty gate wants input");
+    }
+
+    #[test]
+    fn plain_gate_has_no_refill_signal() {
+        assert!(CohortGate::new(100).refill_signal().is_none());
+    }
+
+    #[test]
+    fn try_acquire_cohort_oversized_passes_empty_gate() {
+        // A cohort whose `bound` exceeds the whole budget still admits when the
+        // gate is empty — it can't be split, so refusing it would deadlock.
+        let gate = Arc::new(CohortGate::new(100));
+        let lease = gate.try_acquire_cohort(1000).expect("oversized cohort admits an empty gate");
+        assert_eq!(gate.in_flight_bytes(), 1000, "the full oversized bound is reserved");
+        drop(lease);
+        assert_eq!(gate.in_flight_bytes(), 0, "dropping the lease releases the reservation");
+    }
+
+    #[test]
+    fn try_acquire_cohort_admits_second_only_under_budget() {
+        // Budget = two cohorts. The first admits (empty gate); a second admits
+        // only while `in_flight + bound <= budget`; a third is refused until one
+        // releases.
+        let bound = 100;
+        let gate = Arc::new(CohortGate::new(2 * bound));
+        let first = gate.try_acquire_cohort(bound).expect("first cohort admits");
+        assert_eq!(gate.in_flight_bytes(), bound);
+        let second = gate.try_acquire_cohort(bound).expect("second cohort fits the budget");
+        assert_eq!(gate.in_flight_bytes(), 2 * bound);
+        // Gate is now full and non-empty: a third is refused, no blocking.
+        assert!(gate.try_acquire_cohort(bound).is_none(), "third cohort exceeds budget → None");
+
+        // Releasing the first frees exactly one cohort's worth, admitting a third.
+        drop(first);
+        assert_eq!(gate.in_flight_bytes(), bound);
+        let third = gate.try_acquire_cohort(bound).expect("third admits after a release");
+        assert_eq!(gate.in_flight_bytes(), 2 * bound);
+        drop(second);
+        drop(third);
+        assert_eq!(gate.in_flight_bytes(), 0, "all reservations released");
+    }
+
+    #[test]
+    fn cohort_lease_releases_only_on_last_clone_drop() {
+        // The reservation is released exactly once — when the LAST clone drops —
+        // mirroring a cohort whose sub-batches (each holding a clone) drain one
+        // by one; only the final sub-batch's drop frees the gate.
+        let bound = 100;
+        let gate = Arc::new(CohortGate::new(2 * bound));
+        let lease = gate.try_acquire_cohort(bound).expect("admit");
+        let clone_a = lease.clone();
+        let clone_b = lease.clone();
+        assert_eq!(gate.in_flight_bytes(), bound, "clones share one reservation, not three");
+
+        drop(lease);
+        assert_eq!(gate.in_flight_bytes(), bound, "still reserved: two clones alive");
+        drop(clone_a);
+        assert_eq!(gate.in_flight_bytes(), bound, "still reserved: one clone alive");
+        drop(clone_b);
+        assert_eq!(gate.in_flight_bytes(), 0, "last clone drop releases the reservation");
+    }
+
+    #[test]
+    fn cohort_lease_releases_on_error_path_unwind() {
+        // On an error/panic the pipeline drops the in-flight items (and their
+        // lease clones) while unwinding; the reservation must still be freed so a
+        // stalled Prepare can admit the next cohort. `catch_unwind` stands in for
+        // the framework's error teardown.
+        let bound = 100;
+        let gate = Arc::new(CohortGate::new(2 * bound));
+        let lease = gate.try_acquire_cohort(bound).expect("admit");
+        let clone = lease.clone();
+        drop(lease);
+        assert_eq!(gate.in_flight_bytes(), bound, "one clone still alive");
+
+        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            let _held = clone; // moved in; dropped as the closure unwinds
+            panic!("simulated step error");
+        }));
+        assert!(result.is_err(), "the panic propagates");
+        assert_eq!(gate.in_flight_bytes(), 0, "the lease clone was freed during unwind");
+    }
+
+    /// Counts drops of the resident state it stands in for.
+    struct DropCounted(Arc<std::sync::atomic::AtomicUsize>);
+
+    impl Drop for DropCounted {
+        fn drop(&mut self) {
+            self.0.fetch_add(1, Ordering::SeqCst);
+        }
+    }
+
+    /// The cohort's resident state is created once, shared by every clone of
+    /// the lease, and freed exactly once: when the last clone drops, together
+    /// with the gate reservation, whether that clone drops normally or while a
+    /// failing step unwinds.
+    #[rstest::rstest]
+    #[case::normal_drop(false)]
+    #[case::unwind_drop(true)]
+    fn cohort_lease_frees_resident_state_once_on_last_clone_drop(#[case] unwind: bool) {
+        use std::sync::atomic::AtomicUsize;
+
+        let bound = 100;
+        let gate = Arc::new(CohortGate::new(2 * bound));
+        let lease = gate.try_acquire_cohort(bound).expect("admit");
+        let drops = Arc::new(AtomicUsize::new(0));
+        let inits = AtomicUsize::new(0);
+        let init = || {
+            inits.fetch_add(1, Ordering::SeqCst);
+            DropCounted(Arc::clone(&drops))
+        };
+
+        let clone = lease.clone();
+        let first: *const DropCounted = lease.resident(init).expect("same type");
+        let second: *const DropCounted = clone.resident(init).expect("same type");
+        assert!(std::ptr::eq(first, second), "every clone sees the one resident state");
+        assert_eq!(inits.load(Ordering::SeqCst), 1, "created once");
+        assert!(clone.resident(|| 0u8).is_err(), "a different type is refused, not replaced");
+
+        drop(lease);
+        assert_eq!(drops.load(Ordering::SeqCst), 0, "one clone still alive");
+        if unwind {
+            let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+                let _held = clone;
+                panic!("simulated step error");
+            }));
+            assert!(result.is_err(), "the panic propagates");
+        } else {
+            drop(clone);
+        }
+        assert_eq!(drops.load(Ordering::SeqCst), 1, "freed exactly once, on the last drop");
+        assert_eq!(gate.in_flight_bytes(), 0, "released together with the reservation");
+    }
+}
diff --git a/src/lib/pipeline/steps/align/inproc/mod.rs b/src/lib/pipeline/steps/align/inproc/mod.rs
new file mode 100644
index 000000000..4d9cfd343
--- /dev/null
+++ b/src/lib/pipeline/steps/align/inproc/mod.rs
@@ -0,0 +1,31 @@
+//! In-process bwa-mem3 aligner backend (feature `aligner-bwa-mem3`).
+//!
+//! This module will replace the subprocess `bwa-mem3` invocation with bwa-mem3
+//! linked into the fgumi binary through [`bwa_mem3_rs`], run as work items on
+//! the pipeline's shared work-stealing pool. The whole module tree is compiled
+//! only under `aligner-bwa-mem3`; default builds stay pure Rust with no C
+//! toolchain (the module is gated at its declaration in the parent `align`
+//! module).
+//!
+//! This change adds the foundation the pipeline steps build on:
+//!
+//! - [`cohort`]: the parity-critical pure logic — the `-K` even-parity cohort
+//!   cut, the SE/PE template classification, and the per-sub-batch id-base
+//!   arithmetic — each verified by a proptest against a literal Rust port of the
+//!   corresponding upstream bwa-mem3 rule;
+//! - [`engine`]: the `AlignEngine` abstraction over bwa-mem3-rs's three-phase
+//!   API (seed/extend, per-cohort pestat, pair/emit), with a test fake;
+//! - [`gate`]: the cohort-granularity in-flight gate and its lease;
+//! - [`scratch`]: the per-pool-thread aligner scratch pool.
+//!
+//! The pipeline steps and the backend that wire these into `runall` land in the
+//! following change.
+
+// Wired into the pipeline by the in-process backend in the following change;
+// until then these items are exercised only by their unit tests.
+#![allow(dead_code)]
+
+pub(crate) mod cohort;
+pub(crate) mod engine;
+pub(crate) mod gate;
+pub(crate) mod scratch;
diff --git a/src/lib/pipeline/steps/align/inproc/scratch.rs b/src/lib/pipeline/steps/align/inproc/scratch.rs
new file mode 100644
index 000000000..dde76c7a8
--- /dev/null
+++ b/src/lib/pipeline/steps/align/inproc/scratch.rs
@@ -0,0 +1,124 @@
+//! One aligner scratch per pool thread, shared by the seed/extend and
+//! pair/emit steps.
+//!
+//! A bwa-mem3 scratch holds ~60 MB of kernel buffers (seed/chain windows,
+//! banded-SW and mate-rescue sequence buffers). When each Parallel step's worker
+//! copy owned its own, every pool thread kept two, and the one the other step
+//! last used went cold. The pool keys scratches by OS thread instead, so a pool
+//! worker uses the same warm buffers whichever of the two steps it is running,
+//! and they are all freed with the pool when the align chain drops.
+//!
+//! A pool worker runs one step's `try_run` at a time and pushes never block, so
+//! a thread never asks for its scratch while already holding it; if it did, it
+//! would get a second scratch rather than alias the first.
+
+use std::collections::HashMap;
+use std::io;
+use std::sync::Mutex;
+use std::thread::{self, ThreadId};
+
+/// Scratches keyed by the OS thread that last used them.
+pub(crate) struct ScratchPool<S> {
+    idle: Mutex<HashMap<ThreadId, S>>,
+}
+
+impl<S> ScratchPool<S> {
+    /// An empty pool; scratches are created on first use per thread.
+    pub(crate) fn new() -> Self {
+        Self { idle: Mutex::new(HashMap::new()) }
+    }
+
+    /// Run `f` on this thread's scratch, creating it with `make` on the
+    /// thread's first use. The scratch is taken out of the pool for the
+    /// duration of `f` (so the lock is not held across the aligner call) and
+    /// put back afterwards, whatever `f` returns. A panic in `f` drops it.
+    ///
+    /// # Errors
+    /// Returns `make`'s error, or `f`'s.
+    pub(crate) fn with<R>(
+        &self,
+        make: impl FnOnce() -> io::Result<S>,
+        f: impl FnOnce(&mut S) -> io::Result<R>,
+    ) -> io::Result<R> {
+        let id = thread::current().id();
+        let taken = self.lock().remove(&id);
+        let mut scratch = match taken {
+            Some(scratch) => scratch,
+            None => make()?,
+        };
+        let result = f(&mut scratch);
+        self.lock().insert(id, scratch);
+        result
+    }
+
+    fn lock(&self) -> std::sync::MutexGuard<'_, HashMap<ThreadId, S>> {
+        // A poisoned map only means some `f` panicked; the map itself is intact.
+        self.idle.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
+    }
+}
+
+impl<S> Default for ScratchPool<S> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    use rstest::rstest;
+
+    use super::ScratchPool;
+
+    /// A scratch that records which creation it came from.
+    struct Tagged(u64);
+
+    fn tagged_id(pool: &ScratchPool<Tagged>, created: &AtomicU64) -> u64 {
+        pool.with(|| Ok(Tagged(created.fetch_add(1, Ordering::Relaxed))), |scratch| Ok(scratch.0))
+            .unwrap()
+    }
+
+    #[rstest]
+    #[case::same_thread_reuses_its_scratch(true, true)]
+    #[case::another_thread_gets_its_own(false, false)]
+    fn scratch_is_per_thread(#[case] same_thread: bool, #[case] expect_same: bool) {
+        let pool = Arc::new(ScratchPool::new());
+        let created = Arc::new(AtomicU64::new(0));
+        let first = tagged_id(&pool, &created);
+        let second = if same_thread {
+            tagged_id(&pool, &created)
+        } else {
+            let (pool, created) = (Arc::clone(&pool), Arc::clone(&created));
+            std::thread::spawn(move || tagged_id(&pool, &created)).join().unwrap()
+        };
+        assert_eq!(first == second, expect_same, "first={first} second={second}");
+    }
+
+    /// A nested use on one thread (which the pool's single-`try_run` workers
+    /// never do) gets a scratch of its own rather than aliasing the outer one.
+    #[test]
+    fn nested_use_gets_its_own_scratch() {
+        let pool = ScratchPool::new();
+        let created = AtomicU64::new(0);
+        let make = || Ok(Tagged(created.fetch_add(1, Ordering::Relaxed)));
+        let (outer, inner) = pool
+            .with(make, |outer| {
+                let inner = pool.with(make, |inner| Ok(inner.0))?;
+                Ok((outer.0, inner))
+            })
+            .unwrap();
+        assert_ne!(outer, inner);
+    }
+
+    /// A creation failure is reported to the caller and leaves nothing cached.
+    #[test]
+    fn a_failed_creation_is_an_error() {
+        let pool: ScratchPool<Tagged> = ScratchPool::new();
+        let err = pool.with(|| Err(std::io::Error::other("no memory")), |_| Ok(())).unwrap_err();
+        assert!(err.to_string().contains("no memory"), "{err}");
+        let created = AtomicU64::new(7);
+        assert_eq!(tagged_id(&pool, &created), 7, "the next use creates afresh");
+    }
+}
diff --git a/src/lib/pipeline/steps/align/mod.rs b/src/lib/pipeline/steps/align/mod.rs
index 751fcbd7b..f3fa2f11e 100644
--- a/src/lib/pipeline/steps/align/mod.rs
+++ b/src/lib/pipeline/steps/align/mod.rs
@@ -21,6 +21,15 @@
 //! mid-pair split helper, and the header helpers (`validate_sq_consistency`,
 //! `merge_aligner_header`).
 
+#[cfg(feature = "aligner-bwa-mem3")]
+pub(crate) mod inproc;
+// `bwa-mem3-rs` is a target-gated dependency, so on any other architecture the
+// feature would enable `inproc` without the crate it links; reject it clearly.
+#[cfg(all(
+    feature = "aligner-bwa-mem3",
+    not(any(target_arch = "x86_64", target_arch = "aarch64"))
+))]
+compile_error!("feature `aligner-bwa-mem3` is supported only on x86_64 and aarch64");
 pub(crate) mod merge;
 pub(crate) mod subprocess;