Issue #3605789: Add an InstanceStarted event for atomic start-time wiring
Adds a typed InstanceStartedEvent the engine dispatches inside
the start transaction, after the instance is saved (so it has its id) and its
variables are seeded, but before the start token is placed and
the workflow runs.
Why
An integrator that creates an external entity alongside a process (a booking, an order, a transaction) often needs to link the two and have the link committed atomically with the start. This event is the extension point for that: a subscriber wires the external entity to the instance using the now-known instance id, atomically with the start (a subscriber that throws rolls the whole start back), with the link already in place if the run is synchronous.
It is the idiomatic, decoupled alternative to passing a callback into
start(): subscribers depend only on the event, not on the engine
signature. A plain entity insert hook is not enough, because it fires before the
variables are seeded, so a subscriber could not yet tell which entity the run is
for. The matching reverse link is the instance id (the integer primary key),
which an external table holds as a foreign key for a Views relationship.
What is included
src/Event/InstanceStartedEvent.phpcarrying the saved instance and the seeded variables.- The engine dispatches it in
start()after variable seeding, before the start token (the event dispatcher is injected into the engine). - A kernel test: the event carries the saved instance and the seeded variables, fires before any token exists, and a throwing subscriber rolls the start back.
- An "Events" section in the extending guide.
phpcs (Drupal, DrupalPractice) and cspell are clean; the engine test suites pass locally.