@gmod/bam 8.5.0 → 8.6.0

package/README.md

@@ -21,18 +21,81 @@ const records = await bam.getRecordsForRange('ctgA', 0, 50000)
 ```
 
 Coordinates are 0-based half-open (not the same as `samtools view` inputs).
-`bamPath` reads a local file, so it is node-only; in the browser pass a
-filehandle or URL instead:
+`bamPath` reads a local file, so it is node-only; in the browser pass a URL or a
+generic-filehandle2 filehandle instead:
 
 ```typescript
-import { BamFile } from '@gmod/bam'
-
 const bam = new BamFile({
   bamUrl: 'https://example.com/yourfile.bam',
   baiUrl: 'https://example.com/yourfile.bam.bai',
 })
 ```
 
+Records come back unfiltered, and are shared between overlapping queries — treat
+them as read-only. Filter them yourself with the flag helpers and `getTag`,
+which decodes one tag instead of all of them:
+
+```typescript
+const records = (await bam.getRecordsForRange('chr1', 0, 100000)).filter(
+  r => r.isProperlyPaired() && !r.isSecondary() && r.getTag('RG') === 'rg1',
+)
+```
+
+## Mismatches
+
+`record.getMismatches()` gives every difference between a read and the reference
+— substitutions, insertions, deletions, reference skips and clips — without you
+having to interpret `CIGAR` and `MD` yourself. There is a callback form,
+`record.forEachMismatch(cb, opts?)`, which allocates nothing per difference and
+takes a reference window to report within.
+
+Substitutions need either an `MD` tag on the read or the reference bases, and
+most aligners leave `MD` off. `fetchReferenceSequence` is how you supply them:
+
+```typescript
+const bam = new BamFile({
+  bamPath: 'test.bam',
+  fetchReferenceSequence: async (refName, start, end) =>
+    myGenome.getSequence(refName, start, end),
+})
+
+// one sequence fetch for the whole query, and only if some read needs it
+const records = await bam.getRecordsForRange('ctgA', 0, 50000)
+records[0].getMismatches()
+// [{ code: 88 /* 'X' */, refPos: 188, length: 1, bases: 'A', qual: 17,
+//    refBaseCode: 84 /* 'T' */, clipLength: 0 }, ...]
+```
+
+Without it, a read lacking `MD` still reports its indels and clips, but no
+substitutions — nothing in the record says where they are. See
+[docs/api.md](docs/api.md#mismatches) for the field meanings and for reads
+longer than the region you are looking at.
+
+## Decompressing on a worker pool
+
+BGZF decompression is 70-90% of a cold query, and BGZF blocks are independently
+inflatable. Hand `BamFile` a
+[`@gmod/bgzf-filehandle`](https://github.com/GMOD/bgzf-filehandle) worker pool
+and it inflates chunks there instead of on the calling thread — measured
+2.7-4.1x on the pool's own fixtures.
+
+```typescript
+import { getSharedWorkerPool } from '@gmod/bgzf-filehandle'
+
+const bam = new BamFile({
+  bamUrl: 'https://example.com/yourfile.bam',
+  // the pending promise is fine — it is awaited at the point of use
+  bgzfWorkerPool: getSharedWorkerPool(),
+})
+```
+
+No cross-origin isolation is needed. `getSharedWorkerPool()` gives back
+`undefined` under node, or anywhere Workers cannot be created, which keeps the
+in-process path — so this is safe to pass unconditionally. bam-js never creates
+a pool on its own: the thread budget belongs to the consumer. For worker counts,
+lifecycle and the pool's own benchmarks, see
+[bgzf-filehandle's worker pool docs](https://github.com/GMOD/bgzf-filehandle/blob/main/docs/worker-pool.md).
+
 ## Usage with htsget
 
 ```typescript
@@ -46,10 +109,8 @@ const records = await bam.getRecordsForRange('1', 2000000, 2000001)
 ```
 
 htsget fetches the server's range as-is, so `viewAsPairs`, `pairAcrossChr` and
-`maxInsertSize` are ignored.
-
-For a server that requires authentication, pass a `fetch` that adds the bearer
-token the spec calls for:
+`maxInsertSize` are ignored. For a server that requires authentication, pass a
+`fetch` that adds the bearer token:
 
 ```typescript
 const bam = new HtsgetFile({
@@ -63,227 +124,19 @@ const bam = new HtsgetFile({
 })
 ```
 
-Your `fetch` is called for the ticket request and for the data-block urls the
-ticket points at, so only attach credentials to hosts you trust — data blocks
-may live on a third-party host, and the spec has servers put whatever those need
-in each url's own `headers` field, which is applied either way.
-
-## Documentation
-
-### BamFile constructor
-
-- `bamPath`/`bamUrl`/`bamFilehandle` - local path, remote URL, or a
-  generic-filehandle2 object
-- `baiPath`/`baiUrl`/`baiFilehandle` - BAI index. Defaults to the `.bai` sibling
-  of `bamPath`/`bamUrl`
-- `csiPath`/`csiUrl`/`csiFilehandle` - CSI index, required for chromosomes
-  longer than 2^29
-- `renameRefSeqs` - `(refName: string) => string` applied to header ref names
-- `recordClass` - custom class extending `BamRecord` (see below)
-- `maxCacheBytes` - ceiling for the parsed-chunk cache, in decompressed bytes.
-  default: 1GB, `Infinity` for none. See [Caching](#caching)
-- `cacheIdleTimeoutMs` - drop a cached chunk once nothing has read it for this
-  long. default: 3 minutes; `0` disables it. See [Caching](#caching)
-
-The `path`/`url` forms are convenience wrappers for generic-filehandle2's
-`LocalFile` and `RemoteFile`.
-
-### Caching
-
-Parsed chunks — the unit the BAM index hands out — are cached, so overlapping
-and adjacent queries reuse decompressed records instead of re-fetching them. Two
-options bound that cache, and they answer different questions.
-
-**`maxCacheBytes` is a ceiling under load, not a limit on what you can ask
-for.** Nothing is ever refused for being too large: a chunk bigger than the
-whole budget is still cached, reads in flight are never evicted, and eviction
-only drops a value that has already been returned once. The worst a budget can
-cost you is a re-read. It can make a query slower; it can never make one fail or
-come back short.
-
-**It binds less often than its size suggests.** On the deepest data we measure —
-1000x coverage long reads, 240 windows over six laps — the cache settles at
-573MB across 60 entries and eviction never runs at the 1GB default. Treat it as
-a backstop against a session that pans forever, not as an operating constraint.
-
-**Don't pick a number between one query and several.** Below one query's working
-set the cache inverts: each chunk is evicted before the next pan can reuse it,
-so the hit rate is zero, the full re-decompress is paid every time, and the
-unevictable entries retain the memory anyway. At a 200MB budget on that same
-file the cache holds exactly one entry, because one chunk there decompresses to
-181MB. Either size it above the working set or pass `Infinity` and bound memory
-some other way.
-
-**`cacheIdleTimeoutMs` is the only thing that gives memory back.**
-`maxCacheBytes` is enforced when a read settles, so an idle cache sits at
-whatever it reached and never lowers — and for a page that holds a `BamFile` for
-the life of a track, that resting level is the number that actually matters. The
-idle sweep is what makes a generous ceiling affordable, by turning it into a
-peak under panning rather than a level a parked tab holds indefinitely. The
-clock runs from the last _read_ of a chunk, or from its parse landing if nothing
-has read it since, so panning back and forth over one region never expires it
-and a slow chunk still gets the full timeout to be reused in. Measured on a pan
-that held 331MB: 0MB once idle.
-
-**Neither bounds peak memory**, and on deep data the gap is not small:
-
-- Up to six chunk reads run at once and an in-flight read is never evicted. At
-  181MB a chunk, that is ~476MB in flight before retention holds anything.
-- A query holds every chunk it parsed until it returns, whether or not the cache
-  still does.
-- An entry is weighed once, when its read settles, and records grow after that.
-  `end`, `CIGAR` and `tags` each memoize onto the record the first time they are
-  read, which is what a renderer does to every visible read — measured at +38%
-  over the weighed size.
-
-So these are bounds on retained decompressed bytes, not on the heap. Size
-against what you want to keep, and bound total memory at a level that can see
-the whole process.
-
-### HtsgetFile constructor
-
-- `baseUrl` - htsget reads endpoint, e.g. `https://htsget.example.com/reads`
-- `trackId` - id of the resource under `baseUrl`
-- `fetch` - `fetch` replacement for adding auth headers (see above)
-- `recordClass` - custom class extending `BamRecord` (see below)
-
-### async getRecordsForRange(refName, start, end, opts?)
-
-- `refName` - chromosome to fetch from
-- `start`/`end` - 0-based half-open coordinates
-- `opts.signal` - `AbortSignal` to stop processing
-- `opts.viewAsPairs` - re-dispatch requests to find mate pairs. default: false
-- `opts.pairAcrossChr` - let `viewAsPairs` pair across chromosomes. default:
-  false
-- `opts.maxInsertSize` - distance limit for `viewAsPairs` within a chromosome.
-  default: 200kb
-- `opts.onProgress` - `(bytesDownloaded, totalBytes?) => void`, called per BGZF
-  chunk for a determinate progress bar
-
-Returned records are cached and shared between overlapping queries, so treat
-them as read-only — attaching your own fields to a record mutates it for every
-other query holding it.
-
-Records come back unfiltered. Filter them yourself with the flag helpers and
-`getTag`, which decodes one tag instead of all of them:
+Your `fetch` is called for the ticket request _and_ for the data-block urls the
+ticket points at, which may live on a third-party host — so only attach
+credentials to hosts you trust.
 
-```typescript
-const records = (await bam.getRecordsForRange('chr1', 0, 100000)).filter(
-  r => r.isProperlyPaired() && !r.isSecondary() && r.getTag('RG') === 'rg1',
-)
-```
-
-### async getHeader(opts?)
-
-Returns the parsed SAM header. Called automatically by the query methods and
-cached, so you only need it when you want the header itself.
-`getHeaderText(opts?)` returns the raw header string.
-
-### async indexCov(refName, start?, end?)
-
-Returns `{start, end, score}` features estimating read density over 16kb
-windows, derived from the BAI linear index. CSI has no linear index, so a
-CSI-indexed file returns `[]`.
-
-### async lineCount(refName)
-
-Number of records on `refName` from the index's pseudo-bin (bin 37450 in BAI,
-`n_mapped` in the SAM spec), or 0 if `refName` is absent.
+## Docs
 
-### async hasRefSeq(refName)
-
-Whether `refName` is present in the file.
-
-### async estimatedBytesForRegions(regions, opts?)
-
-Compressed bytes the given `{refName, start, end}[]` would fetch — useful for
-warning before a large query.
-
-### clearFeatureCache()
-
-Drops the parsed-chunk cache immediately, rather than waiting for
-`maxCacheBytes` or `cacheIdleTimeoutMs` to reclaim it. See [Caching](#caching).
-
-### BamRecord
-
-```typescript
-// Core alignment fields
-record.fileOffset // "file offset" based id -- not a true file offset
-record.ref_id // numerical sequence id from SAM header
-record.start // 0-based start coordinate
-record.end // 0-based end coordinate
-record.name // QNAME
-record.seq // sequence string
-record.qual // Uint8Array of quality scores (null if SEQ is empty)
-record.CIGAR // CIGAR string e.g. "50M2I48M"
-record.flags // SAM flags integer
-record.mq // mapping quality (undefined if 255)
-record.strand // 1 or -1
-record.template_length // TLEN
-
-// Mate info
-record.next_refid
-record.next_pos
-
-// Auxiliary data
-record.tags // all aux tags e.g. {MD: "100", NM: 0}
-record.getTag('MD') // one tag, without decoding the rest
-record.getTagRaw('MD') // string tag as Uint8Array, skipping string conversion
-
-// Typed-array views, for rendering without allocating strings
-record.NUMERIC_MD // MD tag as Uint8Array
-record.NUMERIC_CIGAR // Uint32Array of packed CIGAR operations
-record.NUMERIC_SEQ // Uint8Array of 4-bit encoded sequence
-
-// Flag methods
-record.isPaired()
-record.isProperlyPaired()
-record.isSegmentUnmapped()
-record.isMateUnmapped()
-record.isReverseComplemented()
-record.isMateReverseComplemented()
-record.isRead1()
-record.isRead2()
-record.isSecondary()
-record.isFailedQc()
-record.isDuplicate()
-record.isSupplementary()
-
-// Utility
-record.seqAt(idx) // single base at position
-record.toJSON()
-```
-
-### Custom BamRecord class
-
-```typescript
-import { BamFile, BamRecord } from '@gmod/bam'
-
-class CustomBamRecord extends BamRecord {
-  get customProperty() {
-    return `custom-${this.name}`
-  }
-}
-
-const bam = new BamFile<CustomBamRecord>({
-  bamPath: 'test.bam',
-  recordClass: CustomBamRecord,
-})
-
-// records are typed as CustomBamRecord[]
-const records = await bam.getRecordsForRange('ctgA', 0, 50000)
-console.log(records[0].customProperty)
-```
+- [docs/api.md](docs/api.md) — every constructor option, method and `BamRecord`
+  field, plus custom record classes
+- [docs/caching.md](docs/caching.md) — sizing the parsed-chunk cache
+- [agent-docs/adr/](agent-docs/adr/) — the measurements behind the performance
+  and caching decisions
+- [CONTRIBUTING.md](CONTRIBUTING.md) — development and release steps
 
 ## License
 
 MIT © [Colin Diesh](https://github.com/cmdcolin)
-
-## Publishing
-
-[Trusted publishing](https://docs.npmjs.com/about-trusted-publishing) via GitHub
-Actions.
-
-```bash
-pnpm version patch  # or minor/major
-```

package/dist/bamFile.d.ts

@@ -3,6 +3,7 @@ import BAI from './bai.ts';
 import CSI from './csi.ts';
 import BAMFeature from './record.ts';
 import type Chunk from './chunk.ts';
+import type { PackedReference } from './reference.ts';
 import type { BamOpts, BaseOpts } from './util.ts';
 import type { BgzfWorkerPool } from '@gmod/bgzf-filehandle';
 import type { SharedBudget } from '@gmod/shared-read-cache';
@@ -17,7 +18,35 @@ export interface BamRecordLike {
     next_refid: number;
     flags: number;
     tags: Record<string, unknown>;
+    /**
+     * Optional, and read only to decide whether a read needs reference bases at
+     * all — a read with an MD tag carries its own. A `recordClass` without it is
+     * treated as having no MD, i.e. as always wanting the reference.
+     */
+    NUMERIC_MD?: Uint8Array | undefined;
+    /**
+     * Optional; see {@link BamRecord.setReference}. A `recordClass` that does not
+     * implement it simply never gets a reference bound, whatever
+     * `fetchReferenceSequence` returns.
+     */
+    setReference?: (ref: PackedReference) => void;
 }
+/**
+ * Supplies reference bases for a region, so reads with no MD tag can still
+ * report their substitutions. See {@link BamFile}'s option of the same name.
+ *
+ * `refName` is the name the query used, unchanged — `renameRefSeqs` maps the
+ * FILE's names into the caller's namespace, and this callback is on the
+ * caller's side of that. `start`/`end` are 0-based half-open.
+ *
+ * **The bases returned must begin at `start`.** Returning fewer than asked for
+ * is fine and is taken as `[start, start + seq.length)` — the end of a contig,
+ * or a source declining to hand over a huge span — and reads the shorter region
+ * does not cover are then left unresolved. Returning bases from somewhere else,
+ * e.g. clipping the LEFT of the requested range, cannot be detected and
+ * resolves every read against the wrong position.
+ */
+export type ReferenceSequenceFetcher = (refName: string, start: number, end: number, opts?: BaseOpts) => Promise<string>;
 export type BamRecordClass<T extends BamRecordLike = BAMFeature> = new (byteArray: Uint8Array, start: number, end: number, fileOffset: number, dataView: DataView) => T;
 export declare const BAM_MAGIC = 21840194;
 interface ChunkEntry<T> {
@@ -46,7 +75,9 @@ export default class BamFile<T extends BamRecordLike = BAMFeature> {
     private RecordClass;
     /** see the constructor option of the same name */
     private bgzfWorkerPool?;
-    constructor({ bamFilehandle, bamPath, bamUrl, baiPath, baiFilehandle, baiUrl, csiPath, csiFilehandle, csiUrl, htsget, renameRefSeqs, recordClass, maxCacheBytes, cacheIdleTimeoutMs, cacheBudget, bgzfWorkerPool, }: {
+    /** see the constructor option of the same name */
+    fetchReferenceSequence?: ReferenceSequenceFetcher;
+    constructor({ bamFilehandle, bamPath, bamUrl, baiPath, baiFilehandle, baiUrl, csiPath, csiFilehandle, csiUrl, htsget, renameRefSeqs, recordClass, maxCacheBytes, cacheIdleTimeoutMs, cacheBudget, bgzfWorkerPool, fetchReferenceSequence, }: {
         bamFilehandle?: GenericFilehandle;
         bamPath?: string;
         bamUrl?: string;
@@ -135,6 +166,33 @@ export default class BamFile<T extends BamRecordLike = BAMFeature> {
          * in-process path, so this is safe to pass unconditionally.
          */
         bgzfWorkerPool?: BgzfWorkerPool | Promise<BgzfWorkerPool | undefined> | undefined;
+        /**
+         * Reference bases for a region, as `(refName, start, end, opts) =>
+         * Promise<string>`. Only reads that carry no `MD` tag need it, and it is
+         * only what {@link BamRecord.forEachMismatch} uses — nothing else in a
+         * query touches the reference.
+         *
+         * Without it, a read lacking MD still reports its indels and clips but no
+         * substitutions at all: neither the CIGAR nor SEQ says where they are.
+         * That is most aligners' output — minimap2 and bwa both leave MD off unless
+         * asked — so this is the difference between mismatches rendering and not.
+         *
+         * `getRecordsForRange` calls it at most ONCE per query, for the span of the
+         * reads that need it, and binds the result to each of them (see
+         * {@link BamRecord.setReference}). A query whose reads all carry MD does
+         * not call it at all.
+         *
+         * **The span asked for is the reads' union, not the query's**: the query's
+         * range plus however far its edge reads overhang it. Usually that is a few
+         * hundred bases more for Illumina and a couple of Mb for ultra-long ONT,
+         * but a BAM holding whole chromosomes as reads can make it a chromosome.
+         * Nothing here clamps that for you, because only you know what your
+         * sequence source can afford — clamp inside the callback and return the
+         * shorter region; reads it does not cover are then simply left unresolved,
+         * and {@link BamRecord.forEachMismatch}'s `opts.ref` is the windowed way to
+         * handle one of those reads.
+         */
+        fetchReferenceSequence?: ReferenceSequenceFetcher;
     });
     getHeaderPre(opts?: BaseOpts): Promise<{
         tag: string;
@@ -201,6 +259,41 @@ export default class BamFile<T extends BamRecordLike = BAMFeature> {
      * it for every other query still holding that read. See ADR 0006.
      */
     getRecordsForRange(chr: string, min: number, max: number, opts?: BamOpts): Promise<T[]>;
+    /**
+     * Reference bases for a region, packed for
+     * {@link BamRecord.forEachMismatch}'s `opts.ref`, or undefined when no
+     * `fetchReferenceSequence` was configured.
+     *
+     * The way to resolve a read that is longer than the region you are looking at
+     * — a contig or a whole chromosome stored as one BAM read. Those are never
+     * bound to a record automatically, since binding a partial region to a
+     * record shared between queries is the hazard ADR 0006 is about; walking one
+     * with a window and a region of your own choosing has no such problem:
+     *
+     * ```js
+     * const ref = await bam.getReferenceRegion('chr1', start, end)
+     * record.forEachMismatch(cb, { ref, start, end })
+     * ```
+     */
+    getReferenceRegion(refName: string, start: number, end: number, opts?: BaseOpts): Promise<PackedReference | undefined>;
+    /**
+     * Fetch reference bases for the reads in `records` that have no MD tag, and
+     * bind them to those reads so their substitutions resolve. A no-op unless
+     * `fetchReferenceSequence` was configured, and it issues at most one fetch.
+     *
+     * The span fetched is the union of the reads that need it, NOT the queried
+     * range: a read overhanging the range is only bound to a region covering all
+     * of it, because the records are shared between queries and a binding that
+     * varied by query would make one query's reads answer out of another's region
+     * (ADR 0006, ADR 0020). Reads on another reference — `viewAsPairs` mates with
+     * `pairAcrossChr` — are left out for the same reason, and unbound.
+     *
+     * Nothing clamps that union, since only the callback knows what its sequence
+     * source can afford; a callback that returns a shorter region than it was
+     * asked for leaves the reads it does not cover unbound, which is the same
+     * outcome by a route the consumer controls.
+     */
+    protected _applyReferenceSequence(records: T[], chrId: number, refName: string, opts?: BaseOpts): Promise<void>;
     private _cachedChunkFeatures;
     private _fetchChunkFeatures;
     fetchPairs(chrId: number, records: T[], opts: BamOpts): Promise<T[]>;

package/dist/bamFile.js

@@ -12,6 +12,7 @@ const bai_ts_1 = __importDefault(require("./bai.js"));
 const csi_ts_1 = __importDefault(require("./csi.js"));
 const nullFilehandle_ts_1 = __importDefault(require("./nullFilehandle.js"));
 const record_ts_1 = __importDefault(require("./record.js"));
+const reference_ts_1 = require("./reference.js");
 const sam_ts_1 = require("./sam.js");
 const util_ts_1 = require("./util.js");
 exports.BAM_MAGIC = 21840194;
@@ -112,9 +113,12 @@ class BamFile {
     RecordClass;
     /** see the constructor option of the same name */
     bgzfWorkerPool;
-    constructor({ bamFilehandle, bamPath, bamUrl, baiPath, baiFilehandle, baiUrl, csiPath, csiFilehandle, csiUrl, htsget, renameRefSeqs = n => n, recordClass, maxCacheBytes = exports.DEFAULT_MAX_CACHE_BYTES, cacheIdleTimeoutMs = exports.DEFAULT_CACHE_IDLE_TIMEOUT_MS, cacheBudget, bgzfWorkerPool, }) {
+    /** see the constructor option of the same name */
+    fetchReferenceSequence;
+    constructor({ bamFilehandle, bamPath, bamUrl, baiPath, baiFilehandle, baiUrl, csiPath, csiFilehandle, csiUrl, htsget, renameRefSeqs = n => n, recordClass, maxCacheBytes = exports.DEFAULT_MAX_CACHE_BYTES, cacheIdleTimeoutMs = exports.DEFAULT_CACHE_IDLE_TIMEOUT_MS, cacheBudget, bgzfWorkerPool, fetchReferenceSequence, }) {
         this.renameRefSeq = renameRefSeqs;
         this.bgzfWorkerPool = bgzfWorkerPool;
+        this.fetchReferenceSequence = fetchReferenceSequence;
         this.RecordClass = (recordClass ?? record_ts_1.default);
         this.chunkFeatureCache = new shared_read_cache_1.SharedReadCache({
             maxSize: maxCacheBytes,
@@ -269,7 +273,90 @@ class BamFile {
             return [];
         }
         const chunks = await this.index.blocksForRange(chrId, min - 1, max, opts);
-        return this._fetchChunkFeatures(chunks, chrId, min, max, opts);
+        return this._fetchChunkFeatures(chunks, chrId, chr, min, max, opts);
+    }
+    /**
+     * Reference bases for a region, packed for
+     * {@link BamRecord.forEachMismatch}'s `opts.ref`, or undefined when no
+     * `fetchReferenceSequence` was configured.
+     *
+     * The way to resolve a read that is longer than the region you are looking at
+     * — a contig or a whole chromosome stored as one BAM read. Those are never
+     * bound to a record automatically, since binding a partial region to a
+     * record shared between queries is the hazard ADR 0006 is about; walking one
+     * with a window and a region of your own choosing has no such problem:
+     *
+     * ```js
+     * const ref = await bam.getReferenceRegion('chr1', start, end)
+     * record.forEachMismatch(cb, { ref, start, end })
+     * ```
+     */
+    async getReferenceRegion(refName, start, end, opts) {
+        const fetchReferenceSequence = this.fetchReferenceSequence;
+        if (!fetchReferenceSequence) {
+            return undefined;
+        }
+        // Packed once for the region rather than per read — the walk compares two
+        // bases per byte against the read's own packed SEQ, and this is the only
+        // per-base pass in it. Length comes from what came back rather than from
+        // what was asked for, so a callback that clips at the end of the contig
+        // still leaves the bases it did return usable.
+        return (0, reference_ts_1.packReference)(await fetchReferenceSequence(refName, start, end, opts), start);
+    }
+    /**
+     * Fetch reference bases for the reads in `records` that have no MD tag, and
+     * bind them to those reads so their substitutions resolve. A no-op unless
+     * `fetchReferenceSequence` was configured, and it issues at most one fetch.
+     *
+     * The span fetched is the union of the reads that need it, NOT the queried
+     * range: a read overhanging the range is only bound to a region covering all
+     * of it, because the records are shared between queries and a binding that
+     * varied by query would make one query's reads answer out of another's region
+     * (ADR 0006, ADR 0020). Reads on another reference — `viewAsPairs` mates with
+     * `pairAcrossChr` — are left out for the same reason, and unbound.
+     *
+     * Nothing clamps that union, since only the callback knows what its sequence
+     * source can afford; a callback that returns a shorter region than it was
+     * asked for leaves the reads it does not cover unbound, which is the same
+     * outcome by a route the consumer controls.
+     */
+    async _applyReferenceSequence(records, chrId, refName, opts = {}) {
+        const fetchReferenceSequence = this.fetchReferenceSequence;
+        if (!fetchReferenceSequence) {
+            return;
+        }
+        let start = Infinity;
+        let end = 0;
+        for (let i = 0, l = records.length; i < l; i++) {
+            const record = records[i];
+            if (record.ref_id === chrId &&
+                !record.NUMERIC_MD &&
+                record.setReference) {
+                if (record.start < start) {
+                    start = record.start;
+                }
+                if (record.end > end) {
+                    end = record.end;
+                }
+            }
+        }
+        // every read carries MD, or there are no reads: nothing to fetch
+        if (start >= end) {
+            return;
+        }
+        const ref = await this.getReferenceRegion(refName, start, end, opts);
+        if (!ref) {
+            return;
+        }
+        for (let i = 0, l = records.length; i < l; i++) {
+            const record = records[i];
+            if (record.ref_id === chrId &&
+                !record.NUMERIC_MD &&
+                record.setReference &&
+                (0, reference_ts_1.referenceCovers)(ref, record.start, record.end)) {
+                record.setReference(ref);
+            }
+        }
     }
     // Parsed records for a chunk, reading and decompressing it only on a miss.
     // Every path that wants a chunk's features goes through here — mate lookups
@@ -288,7 +375,7 @@ class BamFile {
         const entry = await this.chunkFeatureCache.get(chunk, opts.signal);
         return entry.features;
     }
-    async _fetchChunkFeatures(chunks, chrId, min, max, opts = {}) {
+    async _fetchChunkFeatures(chunks, chrId, chr, min, max, opts = {}) {
         const { viewAsPairs, onProgress } = opts;
         const result = [];
         let totalBytes = 0;
@@ -375,6 +462,10 @@ class BamFile {
                 result.push(pairs[i]);
             }
         }
+        // After the pairs, so a mate fetched from another chunk is resolved on the
+        // same terms as the reads it was fetched for. A no-op without
+        // `fetchReferenceSequence`, which is the default.
+        await this._applyReferenceSequence(result, chrId, chr, opts);
         return result;
     }
     async fetchPairs(chrId, records, opts) {