Transactions Design

Transactions provide atomic multi-operation updates. Single-group transactions commit through the owning Raft log. Cross-group transactions use a two-phase commit coordinator so participating groups record the same decision.

Components

• TransactionHandler dispatches TX_* wire messages.
• TransactionManager owns legacy stateful sessions and rebuilds recoverable state from committed entries and snapshots.
• TransactionExecutor evaluates staged operations against the local registry.
• TransactionKeyLockManager and TX_LOCK_KEY provide transaction-scoped per-key locking.
• TwoPhaseCoordinator and TwoPhaseParticipant implement cross-group prepare/decide flow.
• ReplicatedTransactionCommand and ReplicatedTransactionCodec define the durable command format.

Single-group path

1. The client builds a transaction or batch whose keys resolve to one group.
2. TX_COMMIT is submitted through that group’s Raft write path.
3. The apply path validates locks and preconditions.
4. The result is recorded with idempotency metadata.
5. Retries after a dropped response return the recorded result.

Cross-group path

1. The coordinator splits the command into per-group slices.
2. Each participant group prepares through its own Raft log.
3. The coordinator records the final decision on raft-0.
4. Participants receive COMMIT or ABORT decisions and acknowledge.
5. Recovering participants query the coordinator for the recorded decision.

Invariants

• A committed single-group transaction applies exactly once.
• Participants never commit without a coordinator decision.
• A lost client response does not cause duplicate apply on retry.
• Transaction-scoped locks are released on terminal outcomes or recovery cleanup.

Failure behavior

Leader failover during single-group commit may return an ambiguous outcome; clients should retry with the same transaction identity. Coordinator failover recovers durable prepare/decide state from raft-0. Broader crash-window stress remains tracked in V2_IMPLEMENTATION_GAPS.md; LoomCache does not claim XA semantics.

Verification

Transaction commit/rollback, failover, coordinator durability, cross-group 2PC, idempotent retry, and lock-path tests cover this layer. Operators watch cross-group prepare/decide duration, aborts, recoveries, commit latency, and boundary exceptions.