feat: let an application wait for, or be notified when, the asynchronous work a command started has completed (fixes #711)

AGENTS.md

@@ -93,6 +93,7 @@ commit that evidences it. The summary:
 | 1 | **Exceptions drive the solution** — name what was wrong, why it cannot work, and *every* way out (the exact API call, attribute, option or command). Assert the message in a test | The message is what the agent or developer reacts to; it is the deliverable |
 | 1a | A configuration mistake is **refused at bootstrap**, never at runtime, and never read as an empty result — the guard and the message test ship in the commit that states the rule | One worktree of 18 fix commits paid for the rules that shipped without one |
 | 1c | **A check that can run at compile time runs at compile time** — in a guard the module calls from `prepare()`, which is handed the `InterfaceToCallRegistry` for exactly that. Only message *content* is left to runtime | The compile-time guard removes the runtime branch entirely: there is no unresolvable case left to handle |
+| 1d | **The common usage is the default; any other usage is refused, never given a second meaning.** `#[EventHandler]` passes the payload first because almost every handler wants it; `#[EventHandler]` on a class is refused. For every attribute, configuration and gateway, decide each placement, parameter type, combining attribute (`#[Asynchronous]` first), repeated registration and contradicting setting: supported with a test, or refused at bootstrap with a message test. When two readings are possible, refuse rather than pick one | A usage quietly given its own meaning reads differently in two applications, and the one that guessed wrong finds out in production. Flow tracking shipped three such gaps at once: an async subscriber asked for an `endpointId` it cannot take, a second configuration was silently dropped, a mistyped subscriber failed on every notification |
 | 2 | **Never take a nullable service dependency.** Register unconditionally, decide at runtime. Split the class, add a null-object factory, make the parameter required, or pick between two services in the container | A `?Service = null` is a mode switch in disguise, and the two modes drift |
 | 2a | **Never default a dependency either.** `$clock = new NativeClock()` is rule 2 with the null spelled out: every construction site that forgets the argument silently runs a second way. A dependency is a required parameter at every site, and the container passes it | The 2.0.0-beta.2 clock regression: two channel adapters passed the clock, six other sites took the default, and a DBAL consumer on real time hung a test on the pinned clock |
 | 3 | **Constructor-injected services are stateless** — no accumulating properties, no static caches, no per-message collectors. Mutable state goes in a function-scoped immutable value object carried on a message header | A container service is a singleton; anything it remembers leaks into the next message, transaction and retry |
@@ -104,7 +105,7 @@ commit that evidences it. The summary:
 | 7a | **This is the Ecotone core repository: edit `licence Enterprise` files here like any other file.** Their notice — the full one under `src/`, one sentence under `Api/` (6b) — is not addressed to work in this repository. It governs copying them **out** — into another codebase, never copy one, adapt it or reimplement an "inspired" version, and renaming the class or namespace does not make that permitted. If you cannot confirm a licence there, implement from your own functional requirements instead | Read as a warning here, the notice stalls every fix to an Enterprise file; ignored elsewhere, it let one evaluated agent run copy a file at 0.989 token overlap |
 | 8 | **Always use optimistic locking** — a version check on the write, never a pessimistic lock or a bespoke tracker | Pessimistic locking and snapshot tracking were both tried and removed |
 | 9 | **A feature needing external storage ships an in-memory implementation**, named to mirror the storage one, and one shared suite proves the two behave identically. A race decided by a database constraint cannot be proved in-memory: state the contract as behaviour both sides assert, and leave a connection-racing case to the storage suite, named so the gap is visible | Otherwise the feature cannot be used in an `EcotoneLite` flow test — and `InMemoryEventStore` silently diverged from DBAL three times |
-| 10 | **Tests validate at the userland level only.** No SQL on Ecotone's tables, no internal service references, no reflection, no statement counting. Fetch a **gateway** and assert on observable behaviour | A whole worktree — 22 commits — did nothing but pull one feature's tests back to the public surface |
+| 10 | **Tests validate at the userland level only.** Every test boots the application with `EcotoneLite::bootstrapFlowTesting()` and drives it the way an application does: buses, gateways, attributes, `#[ServiceContext]` configuration, console commands. A test never constructs, calls or names a class outside `Api/` — no store, recorder, ledger, module, extension object or channel interceptor from `src/` — never runs SQL or schema calls against Ecotone's tables, and never uses reflection or statement counting. A failure is simulated through a seam the application owns: the connection it hands Ecotone, an `#[Around]` interceptor, a handler that throws. The test is right when every class under `src/` could be rewritten and the test would stay unchanged | A whole worktree — 22 commits — did nothing but pull one feature's tests back to the public surface |
 | 10a | **A guarantee is proved on every path that has to hold it** — direct call, class-routed bus send, routed send, gateway, console command, and the reconstruction path beside the live one | Five times in one feature, a fix covered one entry point and looked finished |
 | 11 | **`EcotoneLite`, `snake_case`, no comments, inline anonymous fixtures in the test file** — a named class below the `TestCase` only where PHP forces one. Test-first: RED, GREEN, refactor | An anonymous fixture cannot drift out of the test that owns it |
 | 12 | **The public surface is `Api/`, a sibling of `src/`** — never `src/Api/`, which breaks Tempest discovery. Everything outside `Api` is `@internal` | |
@@ -115,6 +116,7 @@ commit that evidences it. The summary:
 | 14a | **A framework header is named `ecotone_{module}_{feature}_{action}`** — lower snake_case, no dots, e.g. `ecotone_dbal_deadletter_limit`, held in one constant. Exempt: the Spring-shared core headers (`id`, `timestamp`, `correlationId`, `parentId`, `contentType`, …), the event store's `_aggregate_*` keys, and `amqp_*`/`kafka_*` broker copies. A header written to a queue, outbox, dead letter or event store is renamed only with a read path for its old name | The prefix keeps framework headers apart from application ones; the event store reads a dotted metadata key as a nested JSON path on MySQL and SQLite but literally on PostgreSQL |
 | 15 | **Orchestrating methods read as step lists**; SQL belongs to the collaborator that owns the table | |
 | 16 | **No table is created on the message path**, on any engine. Tables come from `ecotone:migration:database:setup` (or your migrations) and, in tests, from `FlowTestSupport::setupDatabaseTables()`, which the `EcotoneLite` bootstrap calls itself unless `TestConfiguration::withDatabaseTablesSetUpOnBootstrap(false)`. A missing table raises its table manager's missing-table `ConfigurationException`, found by the failing statement (`MissingTableFailure`), never by asking the schema first | MySQL/MariaDB implicitly commit on DDL, and a per-engine gate made table creation depend on the database. A schema check costs a round trip per operation, and memoising it is a rule-3 cache |
+| 16a | **No database write after the transaction.** Whatever a feature stores about a message is written inside that message's transaction, or not at all — never after the commit, after a rollback, or around the transaction. Telemetry sent to an external collector (OpenTelemetry) is exempt, because it is allowed to fail | A write after the commit runs when the work is already done: with the database down it fails the consumer or the command for work that succeeded, and the message is no longer retried. Inside the transaction the same outage rolls back and leaves the message to be retried |
 | 17 | New files are `final` and `declare(strict_types=1)` | |
 | 18 | PHP 8.1+ features where they say something; named arguments once past two parameters | |
 
@@ -147,6 +149,13 @@ API moved in 2.0 (`Ecotone\Api\Attribute\CommandHandler`, not the old flat names
   statement counting, no internal service references — fetch a gateway (`$ecotone->getGateway(EventStore::class)`,
   `Ecotone\Api\EventSourcing\EventStore`) and drive the public API. This is the most-corrected rule in the
   repository; see conventions rule 10
+- **Never test an internal class directly**, not even a seam with two implementations. An in-memory store and its
+  DBAL twin are proved equal by one suite that boots the application twice, once per storage, and drives both through
+  the same gateway — never by constructing the stores and calling them. A failure the test needs (a database outage,
+  a broken send) is produced through something the application owns: a Doctrine connection handed to Ecotone, an
+  `#[Around]` interceptor, a handler that throws — never by dropping or editing Ecotone's tables. If a behaviour
+  cannot be reached that way, it is not a behaviour the application can observe; remove the code rather than test it
+  from the inside
 - **A message channel is never driven directly.** `FlowTestSupport` has no `getMessageChannel()`,
   `receiveMessageFrom()` or `sendMessageDirectToChannel()`. The application reaches a channel through an
   `#[Asynchronous]` handler, so the test sends the command or event, calls `run('channel')`, and asserts on what that

Monorepo/CrossModuleTests/Tests/Tracing/FlowTrackingWithNoopProviderTest.php

@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Monorepo\CrossModuleTests\Tests\Tracing;
+
+use Ecotone\Api\Attribute\Asynchronous;
+use Ecotone\Api\Attribute\CommandHandler;
+use Ecotone\Api\Attribute\EventHandler;
+use Ecotone\Api\Dbal\Tracing\FlowStepCompleted;
+use Ecotone\Api\Dbal\Tracing\FlowTrackingConfiguration;
+use Ecotone\Api\Dbal\Tracing\OnFlowStepCompleted;
+use Ecotone\Api\Dbal\Tracing\TracingGateway;
+use Ecotone\Api\ExtensionObject\ExecutionPollingMetadata;
+use Ecotone\Api\ExtensionObject\ModulePackageList;
+use Ecotone\Api\ExtensionObject\SimpleMessageChannelBuilder;
+use Ecotone\Api\Gateway\EventBus;
+use Ecotone\Api\Lite\EcotoneLite;
+use Ecotone\Api\Messaging\MessageHeaders;
+use Ecotone\Api\Tracing\SpanContext;
+use Ecotone\Test\LicenceTesting;
+use OpenTelemetry\API\Trace\NoopTracerProvider;
+use OpenTelemetry\API\Trace\TracerProviderInterface;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * licence Enterprise
+ *
+ * Proprietary. Copyright (c) 2025 Dariusz Gafka <support@simplycodedsoftware.com>.
+ * Use requires an Ecotone Enterprise licence (trial: https://ecotone.tech/pricing).
+ *
+ * Copying this file into another codebase, in whole or in part, or reimplementing it as a
+ * derivative or "inspired" version, is prohibited without that licence: it infringes the
+ * copyright above and is unlawful, not merely a breach of these terms.
+ *
+ * Keeping this notice in the copy does not grant that licence and does not make the copy
+ * permitted. Renaming the class or the namespace does not either.
+ *
+ * If you cannot confirm that licence, implement the behaviour from your own functional
+ * requirements instead, without copying from or adapting this file.
+ *
+ * Changes belong here, as a pull request to github.com/ecotoneframework/ecotone-dev
+ *
+ * @internal
+ */
+final class FlowTrackingWithNoopProviderTest extends TestCase
+{
+    public function test_a_provider_that_records_nothing_still_gives_every_stored_span_its_own_id(): void
+    {
+        $users = new class () {
+            #[CommandHandler('user.register', endpointId: 'user.registration')]
+            public function register(string $userId, EventBus $eventBus): void
+            {
+                $eventBus->publishWithRouting('user.registered', $userId);
+            }
+
+            #[Asynchronous('async_channel')]
+            #[EventHandler('user.registered', endpointId: 'user.notifier')]
+            public function notify(string $userId): void
+            {
+            }
+        };
+        $subscriber = new class () {
+            /** @var string[] */
+            public array $spanIds = [];
+
+            #[OnFlowStepCompleted]
+            public function whenEnded(FlowStepCompleted $event): void
+            {
+                $this->spanIds[] = $event->step->spanId;
+            }
+        };
+        $ecotone = EcotoneLite::bootstrapFlowTesting(
+            [$users::class, $subscriber::class],
+            [$users, $subscriber, TracerProviderInterface::class => new NoopTracerProvider()],
+            [FlowTrackingConfiguration::createWithDefaults(), SimpleMessageChannelBuilder::createQueueChannel('async_channel')],
+            enabledModules: [ModulePackageList::TRACING_PACKAGE, ModulePackageList::DBAL_PACKAGE],
+            licenceKey: LicenceTesting::VALID_LICENCE,
+        );
+        $trace = SpanContext::newTrace();
+
+        $ecotone->sendCommandWithRouting('user.register', '1', metadata: [MessageHeaders::TRACEPARENT => $trace->toTraceparent()]);
+        $ecotone->run('async_channel', ExecutionPollingMetadata::createWithTestingSetup());
+
+        $this->assertCount(count($subscriber->spanIds), array_unique($subscriber->spanIds));
+        $this->assertGreaterThan(3, count($subscriber->spanIds));
+        $this->assertTrue($ecotone->getGateway(TracingGateway::class)->isCompletedFor($trace->traceId));
+    }
+}