refactor: express dialect capability in types instead of UnsupportedException

[abnegate]

Stacked on #15 — review that first, or read only the commits after c856577.

The problem

A method that exists only to throw is a broken promise. It satisfies the interface, passes instanceof, autocompletes, and then fails at runtime. MySQL::withTotals() was reachable, typed, documented by the GroupByModifiers interface — and unconditionally threw.

Worse, the loud cases were the minority. Auditing all 61 UnsupportedException sites turned up a larger set of silent failures with the same root cause: methods a dialect could not honour, which accepted input and discarded it.

On the MongoDB builder, ten of the twelve raw-SQL methods silently dropped their arguments:

(new MongoDB())->from('t')->selectRaw('a + 1 AS b')->build()->query;
// {"collection":"t","operation":"aggregate","pipeline":[]}   <- expression gone

Same for selectCase(), conflictSetRaw(), orderByRaw(), groupByRaw(), havingRaw(), selectCast(), insertColumnExpression(). On the schema side, MongoDB accepted check(), generatedAs() and stored() and dropped them, and ttl() was accepted by all five dialects while only ClickHouse read it.

The fix

Capability moves into the type. If a dialect cannot do something, the method is not on its class.

Split	Was	Now
GroupByModifiers	one interface, 3 unrelated capabilities	Rollup (MySQL, MariaDB, PostgreSQL, ClickHouse), Cube (PostgreSQL, ClickHouse), Totals (ClickHouse)
FullTextSearch	required filterNotSearch()	negation split to NegatedFullTextSearch; MongoDB keeps search, drops the negation $text cannot express
raw SQL	12 methods on every builder	RawSql, implemented by Builder\SQL + ClickHouse only
Joins	required crossJoin()/naturalJoin()	CrossJoins split out; $lookup always joins on a field pair
Column modifiers	all on the base class	check/generatedAs/stored on MySQL, MariaDB, PostgreSQL, SQLite; virtual excludes PostgreSQL (STORED only); ttl ClickHouse; userType PostgreSQL
Table	serial(), dropColumn(), renameColumn() everywhere	serial factories off ClickHouse; column alterations off MongoDB

61 → 37 throw sites. 18 became unreachable and were deleted, 6 were the wrong exception type.

What UnsupportedException still means

It cannot be removed entirely, and shouldn't be. 37 sites remain, every one driven by an unsupported value arriving through a correctly typed API:

• filter(array $queries) accepts any Query by contract — Query::regex(...) on SQLite has to be rejected somewhere.
• addColumn(string $name, ColumnType $type) accepts any ColumnType — ColumnType::Serial on ClickHouse likewise.
• Runtime combinations of individually valid calls: Nullable(Array(...)), lowCardinality() inside Array, sampleBy() on an engine without ORDER BY.
• Caller-supplied strings: window function names, join operators.

No interface can exclude these, so the exception is now the answer to "you passed a value I can't compile" rather than "this method never worked". Where both paths exist, the message names the value path — e.g. ClickHouse's SERIAL throw now says the serial() factory is gone but addColumn() still reaches it.

I verified all 37 individually; none is reachable by calling a method that exists only to throw.

Notes for review

• Breaking, but only for callers of methods whose sole behaviour was throwing. Pre-1.0 (0.3.3).
• No output change. Every supported combination emits byte-identical SQL/DDL.
• Builder::applyAstOrderBy() and applyAstJoins() went through orderByRaw()/crossJoin(); they now append the Query directly, so the base class no longer depends on a capability its subclasses may lack.
• Absence is asserted with class_implements()/get_class_methods() rather than assertNotInstanceOf, because PHPStan at level max proves the latter statically true and fails the build. That it can prove it is the point.
• Trait\Serial is generic over TColumn, declared at the use site as @use Trait\Serial<Column\MySQL>, matching the existing Trait\ForeignKeys convention.
• The README commit also fixes a pre-existing wrong example: the withCube() snippet used the MySQL builder, which never supported it.

Test plan

• composer test — 5308 tests, 12324 assertions, all pass (was 5299)
• composer check — PHPStan level max, no errors
• composer lint — pass
• New tests assert capability absence per dialect, and that the surviving value-path throws still fire
• All 18 capability claims in the README verified by reflecting over the built classes

Integration tests need Docker and were not run locally; CI covers them.

🤖 Generated with Claude Code

[github-actions]

📊 Coverage

Metric	Covered	Ratio
Lines	91.91%	7454 / 8110
Methods	84.25%	1107 / 1314
Classes	65.26%	139 / 213

Full per-file breakdown in the job summary.

[greptile-apps]

Greptile Summary

This PR replaces runtime-only unsupported dialect operations with capability-specific interfaces and traits while preserving valid dialect behavior.

• Splits raw SQL, cross joins, grouping modifiers, and negated full-text search into independently typed capabilities.
• Moves schema column and table operations onto only the dialect-specific classes that support them.
• Updates AST handling, documentation, and capability-absence tests for the revised API.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/Query/Builder.php	AST cross/natural joins and raw ordering now append their internal query representations directly without relying on optional public capabilities.
src/Query/Builder/Trait/RawSql.php	Consolidates raw SQL methods into a capability trait used by SQL builders and ClickHouse.
src/Query/Builder/MongoDB.php	Removes unsupported public methods and retains explicit rejection for unsupported values entering through typed query APIs.
src/Query/Schema/ForeignKey.php	Removes generic forwarding methods while concrete supported dialects retain them through their dialect-specific forwarder traits.
src/Query/Schema/Table/Trait/Serial.php	Encapsulates serial column factories for only the table dialects that support them.
README.md	Documents the new capability interfaces and dialect-specific method availability.

_{Reviews (2): Last reviewed commit: "test(schema): pin the fluent chain throu..." | Re-trigger Greptile}