feat(tempest): add ecotone/tempest framework integration package

[dgafka]

Why is this change proposed?

Tempest is a modern PHP framework (v3.x, PHP 8.4+) gaining adoption, and Ecotone had no first-class integration for it. Developers using Tempest had no way to use CQRS, Event Sourcing, Sagas, or messaging patterns without hand-wiring everything from scratch. This PR adds ecotone/tempest — a full framework integration that makes Ecotone available in a Tempest app with zero config, the same way ecotone/laravel does for Laravel and ecotone/symfony-bundle for Symfony.

Description of Changes

New package: packages/Tempest (ecotone/tempest)

• Auto-discovery bootstrap — MessagingSystemInitializer (Tempest Initializer) and EcotoneServiceInitializer (Tempest DynamicInitializer) compile Ecotone lazily on first gateway request. All gateways (CommandBus, QueryBus, EventBus, custom business interfaces) are injectable from Tempest's container with no setup.
• Zero-config handler discovery — When loadAppNamespaces: true (default), Ecotone auto-derives scan namespaces from Tempest's Composer->namespaces (the app's PSR-4 roots), mirroring Laravel's app/ catalog scan. An ecotone.config.php is optional, not required.
• DBAL connection bridge — TempestConnectionReference wraps the app's Tempest DatabaseConfig (Postgres/MySQL/SQLite) as Ecotone's DbalConnectionFactory, enabling outbox, event sourcing, dead-letter queues, and DBAL business interfaces off the app's existing DB config.
• Active-record aggregate repository — TempestRepository lets Tempest IsDatabaseModel models be used directly as Ecotone aggregates (canHandle / findBy / save), with a recursive trait check for detection.
• Multi-tenant DB switching — TempestTenantDatabaseSwitcher + TempestConnectionModule integrate HeaderBasedMultiTenantConnectionFactory so commands/queries route to the correct tenant database via a message header.
• Console commands — EcotoneConsoleCommandDiscovery generates #[ConsoleCommand] proxy classes for every registered Ecotone command (ecotone:list, ecotone:run, ecotone:cache:clear, etc.) so they appear natively in ./tempest with no manual wiring.
• Production hardening — hash-gated proxy regeneration, PSR-3 logger wiring via Tempest's DynamicInitializer, ecotone:cache:clear command, real-boot test proving zero-config works end-to-end.

Also: ModulePackageList::TEMPEST_PACKAGE added to Ecotone core (mirroring LARAVEL_PACKAGE/SYMFONY_PACKAGE, class_exists-guarded).

---

Usage

Install:

composer require ecotone/tempest

Zero-config — handlers in App\ are auto-discovered, gateways are injectable:

final class OrderController
{
    public function __construct(private CommandBus $commandBus) {}
}

Optional ecotone.config.php (service name, licence key, explicit namespaces):

// app/ecotone.config.php — auto-discovered by Tempest
return new EcotoneConfig(
    serviceName: 'order-service',
    licenceKey: env('ECOTONE_LICENCE_KEY'),
);

DBAL connection — wire the app's DB config as Ecotone's default connection:

#[ServiceContext]
public function databaseConnection(): TempestConnectionReference
{
    return TempestConnectionReference::defaultConnection();
}

Active-record aggregate — use a Tempest model as an Ecotone aggregate:

#[Aggregate]
final class Order
{
    use IsDatabaseModel;

    public PrimaryKey $id;
    public string $status;

    #[CommandHandler]
    public static function place(PlaceOrder $command): self
    {
        $order = new self();
        $order->status = 'placed';
        $order->save();
        return $order;
    }

    #[IdentifierMethod('id')]
    public function getId(): int { return $this->id->value; }
}

Multi-tenant routing — route commands to the correct tenant DB via header:

#[ServiceContext]
public function multiTenant(): MultiTenantConfiguration
{
    return MultiTenantConfiguration::create(
        tenantHeaderName: 'tenant',
        tenantToConnectionMapping: [
            'tenant_a' => TempestConnectionReference::create('tenant_a'),
            'tenant_b' => TempestConnectionReference::create('tenant_b'),
        ],
    );
}

$commandBus->send(new RegisterCustomer(1, 'Alice'), metadata: ['tenant' => 'tenant_a']);

---

Integration architecture

flowchart TD
    A[Tempest boot\nFrameworkKernel] -->|InitializerDiscovery| B[EcotoneServiceInitializer\nDynamicInitializer]
    A -->|DiscoveryDiscovery| C[EcotoneConsoleCommandDiscovery\nDiscovery]
    B -->|first get CommandBus| D[MessagingSystemInitializer\ncompile Ecotone]
    D -->|derives from Composer.namespaces| E[App PSR-4 roots\nApp handler scan]
    D -->|LazyInMemoryContainer| F[ConfiguredMessagingSystem]
    F -->|markCompiled| B
    B -->|DynamicInitializer| G[CommandBus / QueryBus\nEventBus / BusinessInterface\nresolvable from container]
    C -->|ConsoleCommandProxyGenerator| H[ConsoleCommand proxies\necotone:list / ecotone:run]
    D -->|TempestConnectionModule| I[TempestConnectionReference\nDbalConnectionFactory]
    D -->|TempestRepositoryBuilder| J[TempestRepository\nIsDatabaseModel as Aggregate]

Loading

---

Use-case scenarios

1. CQRS + Event Sourcing in a Tempest app — Install ecotone/tempest + ecotone/pdo-event-sourcing, define #[EventSourcingAggregate] classes and projections, wire the DB via TempestConnectionReference. See the included quickstart (quickstart-examples/Tempest/Projection/DatabaseReadModel).

2. Tempest active-record model as a DDD aggregate — Use IsDatabaseModel + #[Aggregate] so commands mutate the model through the Command Bus and TempestRepository handles persistence automatically. See quickstart-examples/Tempest/Model.

3. Multi-tenant SaaS — Use MultiTenantConfiguration with TempestConnectionReference per tenant; a tenant message header routes every command/query to the correct database automatically (proven across Postgres + MySQL in tests).

Pull Request Contribution Terms

• I have read and agree to the contribution terms outlined in CONTRIBUTING.