feat: add pools for resolving groups of names by key

[dragonee]

Summary

Introduces pools — a named list of names sharing one field (service), resolvable as a group.

A pool is defined in a separate pools.yml:

-
  name: Everyone
  field: email
  names:
    - michal@makimo.pl
    - alice@makimo.pl

Given a pool and an asked service, PoolService resolves every member through the existing QueryService.

Domain (domain/WhoseName/)

• Pool — value object: getField(): string, getNames(): array.
• PoolQueryRepository — interface: findByName(string): Pool (empty Pool on a miss, like IdentityQueryRepository).
• PoolService — takes PoolQueryRepository + QueryService:
  • whatAreTheNamesOf($pool, $service) — one answer per member, index-aligned, each string|array|null, mirroring QueryService::whatAreTheNamesOf so nulls are kept and callers get 207 semantics.
  • whoseNamesAreThere($pool, $service) — those answers flattened into a distinct list (arrays spread in, nulls and duplicates dropped).
  • When the asked service is the pool's own field, its names are returned verbatim.

Infrastructure

• PoolYamlFileRepository — replicates YamlFileRepository's mtime-based cache, indexing pools by name.

API

• GET /api/whose-name/pool?p=&q= — per-member: [{"username": ...}, …], 200/207/404 (parallels the batch query endpoint).
• GET /api/whose-name/pool/names?p=&q= — flattened distinct: {"names": [...]}, 200/404.

Both are GET and lenient (empty p/q → 404, not 422), matching the single query endpoint. Route closures stay thin HTTP↔domain maps; all logic lives in PoolService.

Wiring & docs

• WHOSENAME_POOLS_YAML config (default tests/pools.yml) + PoolQueryRepository => PoolYamlFileRepository binding.
• README Pools section; ADL docs/adl/2026-07-08-pool-endpoints-status-and-shape.md records the per-member-vs-flattened split, the lenient 404-on-empty choice, and rejected alternatives.

Testing

Full suite passes via ./vendor/bin/sail test — 51 passed, 2 skipped (pre-existing filesystem-atime skips). New coverage:

• Domain — per-member shape, null kept vs dropped, dedup, same-field shortcut, empty pool.
• Infrastructure — find, empty pool, cache persistence/invalidation, missing file, plus an end-to-end PoolService + real repos test.
• Application — both endpoints (200/207/404, same-field, dedup).

Note

Builds on the merged multi-name feature, so it carries the string|array|null return type. The PHP 8.0-FPM / Laravel-upgrade decision (Laravel 9 doesn't run on PHP 8.5) still applies at deploy time.

🤖 Generated with Claude Code