Harden DomainEvent contract and improve aggregate ergonomics.

[gustavofreze]

No description provided.

[Copilot]

Pull request overview

This PR hardens the event-sourcing contracts by making event revision an explicit part of the DomainEvent interface, improves aggregate ergonomics (explicit handler maps, snapshot state extraction), and adds built-in snapshotting conditions with accompanying test coverage and documentation updates.

Changes:

• Require DomainEvent::revision() (with a default via DomainEventBehavior) and wire revision into EventRecord creation automatically.
• Add explicit eventHandlers() support for event-sourced aggregates and introduce getSnapshotState() to control what gets persisted into snapshots.
• Introduce built-in snapshot conditions (SnapshotEvery, SnapshotNever) and update tests/docs accordingly.

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/Snapshot/SnapshotTest.php	Updates snapshot tests to use Snapshot::restore() and verifies snapshot state selection behavior.
tests/Snapshot/SnapshotNeverTest.php	Adds tests for the new SnapshotNever condition.
tests/Snapshot/SnapshotEveryTest.php	Adds tests for the new SnapshotEvery condition and invalid count handling.
tests/Snapshot/SnapshotConditionTest.php	Switches condition tests from a local fixture to SnapshotEvery.
tests/Models/ProductAddedV2.php	Adds a revisioned v2 event fixture for handler/record revision verification.
tests/Models/ProductAdded.php	Adopts DomainEventBehavior to satisfy the new revision() contract.
tests/Models/OrderWithMissingIdentityProperty.php	Updates fixture to match new push() signature (revision now comes from the event).
tests/Models/OrderShipped.php	Adopts DomainEventBehavior to satisfy the new revision() contract.
tests/Models/OrderPlaced.php	Adopts DomainEventBehavior to satisfy the new revision() contract.
tests/Models/Order.php	Aligns identity naming default (id) and updates push() calls to rely on event revision.
tests/Models/ExplicitCart.php	Adds an aggregate fixture demonstrating explicit handler map dispatch.
tests/Models/EveryTwoEvents.php	Removes the ad-hoc snapshot condition fixture (replaced by SnapshotEvery).
tests/Models/CartWithLogger.php	Adds fixture demonstrating overriding snapshot state to exclude infrastructure properties.
tests/Models/Cart.php	Adds withProducts() helper and updates event application to rely on event revision.
tests/Event/DomainEventBehaviorTest.php	Adds tests ensuring default/overridden event revisions behave as expected.
tests/Entity/EntityBehaviorTest.php	Updates identity-name expectations to default to id and verifies override behavior.
tests/Aggregate/EventSourcingRootBehaviorTest.php	Expands tests to cover explicit handler map dispatch and revision propagation.
tests/Aggregate/AggregateRootBehaviorTest.php	Adjusts wording to reflect model version behavior after identity default changes.
src/Snapshot/SnapshotNever.php	Introduces a condition that always returns false.
src/Snapshot/SnapshotEvery.php	Introduces an “every N events” snapshot condition with count validation.
src/Snapshot/Snapshot.php	Makes constructor private, adds restore(), and snapshots via getSnapshotState().
src/Internal/Exceptions/NoEventHandlerRegistered.php	Adds a dedicated exception for missing explicit handler registrations.
src/Internal/Exceptions/MissingIdentityProperty.php	Refactors message construction to a template variable.
src/Internal/Exceptions/InvalidSnapshotCount.php	Adds a dedicated exception for invalid snapshot counts.
src/Internal/Exceptions/InvalidSequenceNumber.php	Refactors message construction to a template variable.
src/Internal/Exceptions/InvalidRevision.php	Refactors message construction to a template variable.
src/Internal/Exceptions/InvalidEventType.php	Refactors message construction to a template variable.
src/Internal/Exceptions/EventHandlerMethodNotFound.php	Adds a dedicated exception for missing implicit handler methods.
src/Event/DomainEventBehavior.php	Provides default revision() implementation (Revision::initial()).
src/Event/DomainEvent.php	Adds revision() to the DomainEvent contract and clarifies documentation.
src/Entity/EntityBehavior.php	Defaults identityName() to id (override remains supported).
src/Aggregate/EventualAggregateRootBehavior.php	Simplifies push() to read revision from the event.
src/Aggregate/EventSourcingRootBehavior.php	Adds explicit handler-map support and default getSnapshotState() implementation.
src/Aggregate/EventSourcingRoot.php	Extends contract to include eventHandlers() and getSnapshotState().
src/Aggregate/AggregateRootBehavior.php	Centralizes recordedEvents() and builds records using event->revision().
README.md	Updates docs to reflect the new DomainEvent revision contract, explicit handlers, and built-in snapshot conditions.
.github/workflows/ci.yml	Improves CI (concurrency, PHP version resolution), but introduces convention violations for action pinning and job ordering.