Add DISJOIN operator for splitting intervals at reference breakpoints — Closes #87

[conradbzura]

Summary

Add DISJOIN, a table function that splits a set of target intervals against a reference set of intervals. DISJOIN(target, reference := ref) appears in the FROM clause, like NEAREST, and cuts each target interval at every reference breakpoint strictly interior to it — so no resulting sub-interval partially overlaps a reference interval. The full target row passes through unchanged and the sub-interval is appended as disjoin_chrom, disjoin_start, and disjoin_end; sub-intervals overlapping no reference interval are dropped. When reference is omitted it defaults to the target set, so SELECT DISTINCT disjoin_* FROM DISJOIN(features) reproduces a Bioconductor-style disjoin() partition.

The operator is generator-only — it emits a self-contained WITH-CTE subquery using only UNION, LEAD, and EXISTS (no LATERAL, no generate_series), so it transpiles unchanged to DuckDB, PostgreSQL, and SQLite. Sub-interval boundaries are canonicalized to 0-based half-open coordinates regardless of the target or reference table encoding. The output schema is uniform across all backends: rather than renaming the target's columns (not portable without schema introspection), the target row passes through intact and the sub-interval is appended under distinct disjoin_* names.

A bin_width convenience parameter and a revmap-style array of covering reference identifiers are out of scope here and tracked as possible follow-ups.

Closes #87

Proposed changes

DISJOIN operator

Add the GIQLDisjoin AST node and register DISJOIN with the parser. The generator emits a parenthesized WITH-CTE subquery: it collects distinct reference breakpoints, builds each target's cut list (own endpoints plus interior breakpoints), forms sub-intervals with a LEAD window, and applies an EXISTS coverage filter. Segments join back to target rows on raw geometry, so duplicate target rows split independently with no synthetic row id. The reference resolves from a table, a CTE, or a subquery, defaulting to the target set.

MCP operator catalog

Register DISJOIN in the MCP server operator metadata and documentation path map so it surfaces through list_operators, explain_operator, and search_docs.

Documentation

Add a DISJOIN section to the aggregation operators reference and a new disjoin recipe covering set partitioning and reference-grid splitting, wired into the recipes index and toctree.

Test cases

#	Test Suite	Given	When	Then	Coverage Target
1	TestDisjoinParsing	A DISJOIN(features) call with a positional target	Parsed with GIQLDialect	The GIQLDisjoin node carries the target as this	Positional target mapping
2	TestDisjoinParsing	A DISJOIN(features) call with no reference	Parsed with GIQLDialect	The node has no reference argument	Optional reference
3	TestDisjoinParsing	A reference := refs named argument	Parsed with GIQLDialect	The node carries the reference argument	Named reference via walrus
4	TestDisjoinParsing	A reference => refs named argument	Parsed with GIQLDialect	The node carries the reference argument	Named reference via arrow
5	TestDisjoinParsing	A reference given as a (SELECT ...) subquery	Parsed with GIQLDialect	The reference argument contains a nested SELECT	Subquery reference
6	TestDisjoinTranspilation	A SELECT * FROM DISJOIN(features) query	Transpiled	The output is a WITH-CTE subquery using UNION, LEAD, and EXISTS	Generated SQL shape
7	TestDisjoinTranspilation	A basic DISJOIN query	Transpiled	The sub-interval is appended as disjoin_chrom/disjoin_start/disjoin_end	Output projection
8	TestDisjoinTranspilation	A DISJOIN call with no reference	Transpiled	The reference CTE selects from the target table	Self-mode default
9	TestDisjoinTranspilation	A DISJOIN call with an explicit reference table	Transpiled	The reference CTE selects from that table	Explicit reference
10	TestDisjoinTranspilation	A target with custom genomic column names	Transpiled	The generated SQL references the custom names	Column resolution
11	TestDisjoinTranspilation	A 1-based closed target table	Transpiled	The start is shifted to canonical 0-based coordinates	Coordinate canonicalization
12	TestDisjoinTranspilation	A reference given as a subquery	Transpiled	The subquery is inlined as an aliased derived table	Subquery inlining
13	TestDisjoinExecution	Two overlapping intervals in self-mode	Executed on DuckDB	Each interval splits at the other's interior breakpoint	Split correctness
14	TestDisjoinExecution	Overlapping intervals in self-mode	DISTINCT sub-intervals are selected	The result is the globally non-overlapping partition	Bioconductor disjoin equivalence
15	TestDisjoinExecution	A target and a separate reference set	Executed on DuckDB	The target is cut at the reference breakpoints	Explicit-reference split
16	TestDisjoinExecution	A target spanning a reference coverage gap	Executed on DuckDB	Sub-intervals overlapping no reference are dropped	Coverage filter
17	TestDisjoinExecution	A zero-length point target	Executed on DuckDB	No output rows are produced	Degenerate point input
18	TestDisjoinExecution	Two target rows with identical geometry	Executed on DuckDB	Each duplicate row splits independently	Geometry-keyed join
19	TestDisjoinExecution	Target intervals on different chromosomes	Executed on DuckDB	Sub-intervals never cross a chromosome boundary	Per-chromosome partitioning
20	TestDisjoinExecution	A target carrying a non-interval column	Executed on DuckDB	Every output row carries the intact parent row	Parent passthrough
21	TestDisjoinExecution	A reference supplied as an outer-query CTE	Executed on DuckDB	The target is split at the CTE's breakpoints	CTE reference resolution
22	TestDisjoinExecution	A reference breakpoint at a target boundary	Executed on DuckDB	The target is not split at that boundary	Strict-interior breakpoint rule
23	TestDisjoinCoordinateSpace	The same intervals re-encoded under each of four conventions	DISJOIN runs in self-mode	The canonical partition is identical across encodings	Convention-invariant self-mode
24	TestDisjoinCoordinateSpace	A target and reference under differing conventions	DISJOIN(features, reference := refs) runs	The canonical sub-intervals are identical regardless of encoding	Convention-invariant mixed split

[conradbzura]

It would be nice to have template files for these strings — possibly using Jinja?