docs: update upgrade guide and message docs for 4.0 breaking changes

Document the breaking changes from the merged 4.0 PRs that were missing
from the upgrade guide:

- stream refactor (#847): Store\Stream interface replaced by the concrete
  Message\Stream class, removed store-specific stream implementations,
  Message\Pipe removed in favor of Stream::transform()
- removed deprecated SubscriberHelper and SubscriberUtil (#805)
- removed SubscriberAccessor / RealSubscriberAccessor interfaces and
  deprecated accessor methods, removed AggregateIdArgumentResolver (#756)
- ArgumentMetadata now carries a symfony/type-info Type (#814)

Also update the message docs Pipe section to use the new Stream API.

Author: DavidBadura

docs/UPGRADE-4.0.md

@@ -86,6 +86,48 @@ $subscriptionEngine = new DefaultSubscriptionEngine(
     RetryStrategyRepository::withDefault($retryStrategy),
 );
 ```
+
+### SubscriberHelper and SubscriberUtil
+
+The deprecated `Patchlevel\EventSourcing\Subscription\Subscriber\SubscriberHelper`
+and the `Patchlevel\EventSourcing\Subscription\Subscriber\SubscriberUtil` trait have been removed.
+
+If you need the subscriber id, read it from the metadata instead:
+
+```php
+use Patchlevel\EventSourcing\Metadata\Subscriber\AttributeSubscriberMetadataFactory;
+
+$metadata = (new AttributeSubscriberMetadataFactory())->metadata($subscriber::class);
+$subscriberId = $metadata->id;
+```
+
+### SubscriberAccessor and RealSubscriberAccessor
+
+The `Patchlevel\EventSourcing\Subscription\Subscriber\SubscriberAccessor` and
+`Patchlevel\EventSourcing\Subscription\Subscriber\RealSubscriberAccessor` interfaces have been removed.
+Use `Patchlevel\EventSourcing\Subscription\Subscriber\MetadataSubscriberAccessor` directly.
+
+Accordingly, `SubscriberAccessorRepository::get()` now returns a `MetadataSubscriberAccessor|null`
+instead of a `SubscriberAccessor|null`.
+
+The deprecated methods `id()`, `group()` and `runMode()` on `MetadataSubscriberAccessor` have been removed.
+Use `->metadata()->id`, `->metadata()->group` and `->metadata()->runMode` instead.
+
+### AggregateIdArgumentResolver
+
+The deprecated `Patchlevel\EventSourcing\Subscription\Subscriber\ArgumentResolver\AggregateIdArgumentResolver`
+has been removed. Automatically resolving the aggregate id in a stream store is not possible.
+Add the aggregate id to your events instead.
+
+### ArgumentMetadata
+
+The subscriber argument resolver now uses `symfony/type-info` to describe argument types.
+
+`Patchlevel\EventSourcing\Metadata\Subscriber\ArgumentMetadata` no longer carries a `string $type`
+and a `bool $allowsNull` property. Instead it now has a single `Symfony\Component\TypeInfo\Type $type` property.
+
+If you implemented a custom `ArgumentResolver`, adjust it to read the type from the new `Type` object.
+
 ## Store
 
 ### StreamStore
@@ -106,6 +148,49 @@ And all the associated classes:
 
 `StreamReadOnlyStore` was been merged in `ReadOnlyStore`.
 
+## Stream
+
+The stream handling has been reworked. Previously the `Stream` was an interface that every store had to
+implement on its own (`ArrayStream`, `StreamDoctrineDbalStoreStream`, `TaggableDoctrineDbalStoreStream`,
+`GeneratorStream`, ...). Now there is a single generic implementation that you can reuse.
+
+### Stream interface
+
+The `Patchlevel\EventSourcing\Store\Stream` interface has been removed and replaced by the concrete final
+class `Patchlevel\EventSourcing\Message\Stream`.
+
+All stores now return a `Patchlevel\EventSourcing\Message\Stream` from their `load()` method.
+The following store specific stream implementations have been removed:
+
+* `Patchlevel\EventSourcing\Store\ArrayStream`
+* `Patchlevel\EventSourcing\Store\StreamDoctrineDbalStoreStream`
+* `Patchlevel\EventSourcing\Store\TaggableDoctrineDbalStoreStream`
+* `Patchlevel\EventSourcing\Subscription\Engine\GeneratorStream`
+
+The new `Stream` class implements `Iterator` and accepts any `iterable<Message>` in its constructor.
+The `index()`, `position()`, `end()` and `close()` methods remain available.
+In addition there are now the helper methods `toList()`, `toArray()`, `transform()` and `chunk()`.
+
+### Pipe
+
+`Patchlevel\EventSourcing\Message\Pipe` has been removed. Use `Stream::transform()` instead.
+
+before:
+
+```php
+use Patchlevel\EventSourcing\Message\Pipe;
+
+$messages = (new Pipe($messages, $translator))->toArray();
+```
+
+after:
+
+```php
+use Patchlevel\EventSourcing\Message\Stream;
+
+$messages = (new Stream($messages))->transform($translator)->toList();
+```
+
 ## Message
 
 ### AggregateHeader

docs/message.md

@@ -97,27 +97,33 @@ use Patchlevel\EventSourcing\Message\Message;
 /** @var Message $message */
 $message->header(ApplicationHeader::class);
 ```
-## Pipe
+## Stream
 
-The `Pipe` is a construct that allows you to chain multiple translators.
+A `Stream` wraps an iterable of messages and allows you to chain multiple translators with `transform`.
 This can be used to manipulate, filter or expand messages or events.
 This can be used for anti-corruption layers, data migration, or to fix errors in the event stream.
 
 ```php
-use Patchlevel\EventSourcing\Message\Pipe;
+use Patchlevel\EventSourcing\Message\Stream;
 use Patchlevel\EventSourcing\Message\Translator\ExcludeEventTranslator;
 use Patchlevel\EventSourcing\Message\Translator\RecalculatePlayheadTranslator;
 
-$messages = new Pipe(
-    $messages,
+$stream = (new Stream($messages))->transform(
     new ExcludeEventTranslator([ProfileCreated::class]),
     new RecalculatePlayheadTranslator(),
 );
 
-foreach ($messages as $message) {
+foreach ($stream as $message) {
     // do something with the message
 }
 ```
+
+:::tip
+A `Stream` is also what every store returns from its `load` method, so you can apply the same
+transformations to the messages you read from the store. Besides iterating, a `Stream` offers
+`toList()`, `toArray()` and `chunk()` to consume the messages.
+:::
+
 ## Translator
 
 Translator can be used to manipulate, filter or expand messages or events.