feat: support multiple names per field in an identity

[dragonee]

Summary

Introduces multiple names per field in an identity. A service field may now hold a list of names instead of a single scalar:

-
  slack: U234567
  email:
    - other@example.org
    - new@example.org

• Lookups match any listed name — querying by other@example.org or new@example.org on email resolves the same identity.
• Answers return the whole list — asking for a multi-name field returns the array of names.

Changes

• QueryService::whatIsTheNameOf() and Identity::username() now return string|array|null: a string for single-name fields, an array when the asked service holds several, null for a miss. whatAreTheNamesOf() (batch) returns an index-aligned list of those answers.
• YamlFileRepository::transformIdentityListToIndex() indexes every name under a field (foreach ((array) $value as $name)), so a query by any one of them resolves the identity. A scalar is treated as a one-element list, so single-name data is unchanged.
• The HTTP layer needed no code change: JSON encodes arrays natively and the status logic keys only on null, so both the single (200/404) and batch (200/207) endpoints keep their {"username": ...} envelope; the value simply widens to include a JSON array.
• README updated (intro example, glossary, usage + batch sections) and a new ADL added: docs/adl/2026-07-08-multiple-names-per-field.md.

Compatibility

• Backward compatible for single-name data — existing files, queries, and responses behave exactly as before; a response only becomes an array when the asked field is itself a list.
• ⚠️ Contract widening: username is now string-or-array. String-only clients (e.g. whose-name-client) must be updated before they consume multi-name fields.

Testing

Full suite passes via ./vendor/bin/sail test — 32 passed, 1 skipped (pre-existing filesystem-atime skip). New tests cover the array response and search-by-any-entry across the domain, infrastructure, and application layers.

🤖 Generated with Claude Code