Summary

Add generated Psalm @psalm-type array shapes for query filters and aggregation pipeline stages, so that users who pass raw arrays (rather than using the builder) get static type checking via Psalm/PHPStan.

Motivation

Most users write queries and pipelines as flat PHP arrays. Currently these are typed as array|object with no structural validation. The MQL spec YAML files (in generator/mql-specifications/definitions/) already contain all the information needed to generate precise array shapes, using the same generator used for the operator builder classes.

Scope and Limitations

Well covered (non-recursive)

• Query field operators ($gt, $lt, $in, $regex, $exists, etc.) — flat shapes, good coverage
• Aggregation stages — discriminated union list[array{$match:...}|array{$group:...}|...], most stages have flat or shallow argument structures

Limitations

• Recursive operators ($and, $or, $nor, $elemMatch in queries; $add, $cond in expressions) — Psalm does not support self-referencing array shapes; these arguments fall back to array[string, mixed] or mixed
• Targets users passing flat arrays, which is the most common use case; deeply nested recursive structures are better served by the existing builder API

Acceptance Criteria

• The code generator produces Psalm array shapes for query filter operators and pipeline stage arguments
• Collection methods (find(), aggregate(), updateOne(), etc.) reference the generated types
• Psalm validates correct array shapes and rejects invalid ones in CI
• Recursive operator arguments fall back gracefully without false positives