ADR-005: Concurrency Auto-Selection
Status: Accepted | Date: 2026-02-10
Context
Different backend operations require different concurrency control strategies. A simple read operation needs no locking. A single-entity update benefits from optimistic locking. A multi-entity financial transaction demands pessimistic locking to prevent race conditions.
Fascia's target users are non-developers. They cannot be expected to understand the tradeoffs between optimistic and pessimistic concurrency control, nor to choose the correct strategy for each operation they design.
Decision
Fascia automatically selects the concurrency strategy at spec compile time based on static analysis of the Tool's flow graph. The selection follows these rules:
| Flow Pattern | Strategy |
|---|---|
| Read-only (no Write nodes) | No lock |
| Single entity write | Optimistic locking (version field check) |
| Multi-entity write | Pessimistic locking (SELECT FOR UPDATE) |
| Financial operations (Payment node present) | Pessimistic locking |
| High row impact (write affects > 100 rows) | Pessimistic locking |
The selected strategy is displayed in Flow Studio as an informational badge, so technical users can see and understand the choice. In the full vision, advanced users will be able to override the auto-selected strategy.
Alternatives Considered
| Option | Pros | Cons |
|---|---|---|
| Auto-selection (chosen) | Zero user effort, safe defaults, informed by flow analysis | May not always choose the optimal strategy |
| Always optimistic | Simpler implementation | Dangerous for multi-entity writes and financial operations; race conditions |
| Always pessimistic | Safest possible default | Performance overhead for read-heavy or simple write operations |
| User chooses | Maximum flexibility | Non-developers cannot make this decision correctly |
Consequences
Positive
- Zero cognitive load -- Non-developers get safe concurrency behavior without understanding locking concepts.
- Transparency -- The selected strategy is visible in Flow Studio. Technical users can inspect and understand why a particular strategy was chosen.
- Safe defaults -- The auto-selection errs on the side of safety. Financial operations and multi-entity writes always use pessimistic locking.
- Override path -- Advanced users will be able to override the selection in the full vision, providing an escape hatch for edge cases.
Negative
- Conservative choices -- The auto-selection may choose pessimistic locking in cases where optimistic locking would be sufficient, resulting in slightly higher database contention.
- Edge cases -- Static flow analysis may not capture all runtime patterns. Some flows may receive a suboptimal strategy.
Risks
- Optimistic lock failures must be handled gracefully. The Executor automatically retries on version conflicts, with a user-facing error if retries are exhausted.
- Pessimistic locking can cause deadlocks in complex flows with multiple write targets. The Executor implements deadlock detection with configurable timeouts to prevent indefinite blocking.