[conradbzura]

Summary

Port cherimoya's pileup across eight modules, split along seams that already existed in the 2,652-line module it came from. Output is byte-identical: the same two alignments through cherimoya and through quadrat produce the same Parquet, per contig, at one contig batch and at three, manifests included.

The split resolves a cycle rather than imposing one. Upstream, the planner and the SQL layer import from each other inside function bodies because the module graph would not otherwise admit them. Here plan.py is a leaf, sql.py and alignments.py depend on it, run.py depends on plan, and the four lazy imports that existed to tolerate the cycle are gone — which is the test of whether the seam was real.

Based on quadrat-2-package-skeleton rather than main, since it builds on the packaging in #7. GitHub retargets this to main when that merges.

Closes #3

Proposed changes

Module split

alignments.py reads contigs, indexes and contig batches; tables.py owns the cut-site format and its atomic writer; pileup/sql.py holds the aggregate; pileup/plan.py the memory model; pileup/run.py the backends; pileup/__init__.py the entry point. _engine.py and reference.py carry the session and the reference reader.

Renames that are behaviour

Rename the polars-bio table names and the cache variable to a quadrat_ prefix. The session is process-global, so both packages must be importable into one process during the transition. That same globalness is why a worker runs one pileup at a time, and the reasoning travels with the names.

What deliberately does not change

Keep CUT_SITE_SUFFIX and MANIFEST_VERSION as cherimoya's, so a table either package writes is readable by the other. Keep every heavy import inside the function body that needs it: import quadrat pulls in none of polars, polars-bio, torch, giql or pyfaidx.

Deferred backend

Ship BACKENDS as serial and process. The wool backend dispatches to workers on other machines and is the only part of the pileup needing a dependency outside this package; asking for it raises NotImplementedError naming the alternative, because a caller migrating a working configuration needs to know it is deferred rather than that it never existed.

Fix carried from #7

write_random_bam placed every read on the first contig — the branch meant to spread them indexed the contig list by a value that was zero whenever that branch was taken. The builder's own test only checked sortedness, so a one-contig corpus looked correct; the parity run exposed it. Add the assertion that was missing.

Test cases

43 tests: 34 ported from cherimoya's test_pileup.py, 8 from its test_giql_io.py, 1 new. Summarized by area rather than per test.

#	Test Suite	Given	When	Then	Coverage Target
1	test_pileup	A machine of pinned cores and memory	plan_pileup is called across input sizes	Returns worker and batch counts the memory model admits	Memory envelope
2	test_pileup	A job larger than the scan cap	The planner solves its batch count	Splits it however much memory is free	Scan cap
3	test_pileup	A lopsided job set	pileup_many assigns batch counts	Splits only the large jobs, not the mean	Per-job floor
4	test_pileup	The same jobs under serial and process	Both backends run	Write byte-identical tables in the same order	Backend equivalence
5	test_pileup	An unrecognised backend name	pileup_many is called	Raises ValueError naming the backends that exist	Backend validation
6	test_pileup	A request for the wool backend	pileup_many is called	Raises NotImplementedError naming the alternative	Deferred backend
7	test_pileup_io	A BAM with deletions, soft clips and skips	It is read through the BAM provider	Coordinates equal pysam's	Provider parity
8	test_pileup_io	Two alignments and a reference	pileup_alignments runs	Matches the bam2bw oracle, drops unmapped and off-reference reads	Pileup semantics
9	test_pileup_io	A scale factor and a stranded request	The pileup runs	Applies the scale once and splits strands	Aggregate options
10	test_pileup_io	A cut-site directory	cut_site_contigs lists it	Answers from filenames without reading rows	Contig listing
11	test_pileup_io	The pileup query plan	EXPLAIN is inspected	Places the join above the aggregate	Overflow fix
12	test_builders	Sixty reads over three contigs	write_random_bam places them	Reaches every contig, most on the first	Regression from #7