feat: add ORM relationships, collections, and query specifications

[markshust]

Summary

• Added relationship attributes (#[HasOne], #[HasMany], #[BelongsTo], #[BelongsToMany]) for declaring entity relationships via PHP attributes
• Added explicit eager loading via with() on Repository and RepositoryQueryBuilder — no lazy loading, no proxies, no N+1 by design
• Added nested eager loading with dot notation ('comments.author')
• Added first-class pivot entities for many-to-many relationships (real Entity classes, not magic pivot accessors)
• Added EntityCollection — typed, chainable collection with filter, map, sort, group, chunk, pluck
• Added QuerySpecification interface and matching() for composable, named query logic (replaces Eloquent scopes)
• Changed findAll()/findBy() return types from array to EntityCollection
• Added relationship validation with loud, helpful error messages following Marko's error philosophy
• Updated docs guides and package reference with new relationship, collection, and specification documentation

Test plan

• All 565 database package tests passing (1791 assertions)
• EntityCollection — 26 tests covering construction, filtering, sorting, grouping, chunking
• Relationship attributes — 18 tests covering all 4 attribute types
• RelationshipMetadata — 17 tests covering value object and type enum
• EntityMetadataFactory — 26 tests covering relationship parsing
• QuerySpecification — 10 tests covering interface, matching, composition
• RelationshipLoader — 16 tests covering BelongsTo, HasOne, HasMany batch loading
• BelongsToMany loading — 11 tests covering pivot entity resolution
• Nested eager loading — 10 tests covering dot notation and multi-level loading
• Repository with() — 16 tests covering eager loading integration and validation
• RepositoryQueryBuilder — 11 tests covering with() and matching() on query builder
• Return type migration — 9 tests covering EntityCollection return types
• Relationship validation — 13 tests covering error messages for misconfigurations
• Standards enforcement pass completed
• Documentation updated (guides, package reference, README)

Closes #24

🤖 Generated with Claude Code