Bring Sql\Predicate to full Mago compliance

[simon-mundy]

Takes Sql\Predicate out of both Mago baselines entirely, and fixes two bugs found along the way.

Stacked on #229 (analyzer baseline refresh for Mago 1.56.1). Its single commit appears here until that merges.

Bugs fixed

Upper-case magic properties were ignored. Predicate documents AND, OR, NEST and UNNEST next to their lower-case forms, and docs/book/sql/where-having.md called the names case-insensitive. An earlier refactor dropped the strtolower() in __get(), so upper-case names fell through and returned the predicate unchanged:

$where->equalTo('a', 1)->OR->equalTo('b', 2);
// before: a = ? AND b = ?
// after:  a = ? OR b = ?

addPredicates(['a = ?']) threw a TypeError. A keyless string with a placeholder was built as a Sql\Expression, which is not a PredicateInterface. It is now a Predicate\Expression, as it was in laminas-db.

Behaviour changes

• __get() now matches exactly the names its @property tags declare: or/OR, and/AND, nest/NEST and unnest/UNNEST. It no longer lower-cases every name it's given. A mixed-case form of one of those names, such as Or, throws InvalidArgumentException::forMixedCaseMagicProperty() rather than silently leaving the next predicate's combination unchanged. Other unknown names still return the predicate. The where-having guide now documents lower or upper case and the exception.

• A keyless entry that is not a predicate, an expression or a string now throws InvalidArgumentException::forInvalidListPredicate(). It used to throw a TypeError from str_contains().

• A Select bound to a placeholder key (['id IN (?)' => $select]) is wrapped in Argument\Select and reaches the expression as a parameter. It used to throw a TypeError.

Cleanup

• addPredicates() builds entries through two private helpers, one per key type. Both are typed against a PredicateValue alias that the where() and having() docblocks on Select, Update and Delete now share.
• getExpressionData() drops its special cases for zero and one predicate, because the loop gives the same result for both. This clears the halstead and kan-defect findings on PredicateSet.
• The @property tags for unnest and UNNEST now declare ?Predicate, matching the private ?Predicate $unnest property behind them. Mago applies those tags to $this->unnest inside the class, so with a non-null type it reported the "not nested" null guard as impossible and the null assignments as invalid. __get('unnest') still returns the parent predicate or throws when the predicate is not nested.
• Every class and interface in the component is tagged @api. None is made final. Mago's finality check accepts @api, so this settles both class-must-be-final and missing-api-or-internal while leaving the classes open to the platform packages.
• Predicate and the Predicate exception catalogue join the too-many-methods exclusions in mago.toml. It has one fluent method per predicate type, so its method count is the size of its public API.

Result

	Before (#229)	After
Lint baseline (issues)	225	222
Analyzer baseline (issues)	721	697
src/Sql/Predicate in either baseline	33	0
PHPUnit	2135 tests	2154 tests

Typing the predicate arrays moves six findings onto the where() calls in AbstractTableGateway and AbstractRowGateway. They are baselined for the gateway pass.

Line and method coverage of src/Sql/Predicate is 100%. Infection reports 99% covered-code MSI. The two survivors are in untouched code: a protected-to-private visibility mutant on getNextPredicateCombineOperator(), and the ?? in In::getExpressionData().

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

The merge-base changed after approval.