﻿# ADR 0004 — TransactionalExecutor for Cross-Service Consistency (T-F02)

Date: 2026-09-11
Status: Accepted
Refs: T-F02, EXECUTION_ROADMAP.md §9

## Context

Several service methods opened database transactions inline using
`$this->app->db()->beginTransaction()` / `commit()` / `rollback()` directly.
This pattern was duplicated across at least 6 service classes and made it
impossible to compose operations atomically without nesting transactions.

## Decision

A `TransactionalExecutor` service was introduced. All transaction boundaries
are expressed as:

```php
$this->transactional->run(function () {
    // all writes here
});
```

`TransactionalExecutor::run()` handles begin / commit / rollback uniformly,
including nested-transaction detection (uses savepoints when a transaction is
already active).

## Consequences

- Services no longer hold direct transaction logic — they are testable without
  a real database for unit tests.
- Nested transactions are safe: inner `run()` calls use MySQL savepoints.
- All future service code MUST use `TransactionalExecutor`; direct
  `beginTransaction()` calls in service layer are forbidden (enforced by
  PHPStan and architecture tests).
