Add formal FSM for transaction lifecycle with decision points

[pelle]

Summary

This PR introduces a formal Finite State Machine (FSM) for managing TAP transaction lifecycles, replacing ad-hoc state handling with explicit states, transitions, and decision points. The FSM models the complete transaction journey from initiation through authorization to settlement, with clear separation between automatic transitions and decisions requiring external input.

Key Changes

• New FSM module (tap-node/src/state_machine/fsm.rs):

  • TransactionState enum: 8 states covering the full transaction lifecycle (Received, PolicyRequired, PartiallyAuthorized, ReadyToSettle, Settled, Rejected, Cancelled, Reverted)
  • AgentState enum: Per-agent authorization tracking (Pending, Authorized, Rejected, Removed)
  • FsmEvent enum: 10 event types representing incoming TAP messages (TransactionReceived, AuthorizeReceived, RejectReceived, etc.)
  • Decision enum: 3 decision types for external systems (AuthorizationRequired, PolicySatisfactionRequired, SettlementRequired)
  • TransactionFsm engine: Pure-logic state machine with apply() method for processing events
  • DecisionHandler trait: Pluggable handler for decision points with built-in implementations (AutoApproveHandler, LogOnlyHandler)
  • DecisionMode enum: Configuration for how decisions are handled (AutoApprove, EventBus, Custom)

• Updated StandardTransactionProcessor:

  • Integrated FSM context management with in-memory DashMap storage
  • Converts incoming TAP messages to FsmEvents
  • Routes events through the FSM and delegates decisions to configured handler
  • Maintains backward compatibility with auto-approval mode (default behavior)
  • Supports event-bus mode for external decision handling

• New event type (NodeEvent::DecisionRequired):

  • Published when FSM reaches decision points in EventBus mode
  • Includes transaction ID, current state, decision details, and pending agents
  • Enables external systems to subscribe and respond

• Configuration updates (NodeConfig):

  • Added decision_mode field to control FSM decision handling strategy

Implementation Details

• The FSM is pure logic with no I/O — all state changes are in-memory and must be persisted by the caller
• Per-agent tracking: Transactions track individual agent authorization status while maintaining a single top-level transaction state
• Decision points: Three states require external decisions (Received, PolicyRequired, ReadyToSettle); the FSM returns a Decision describing what must be resolved
• Policy handling: Supports policy exchange flow where counterparties can request presentations before authorizing
• Agent management: Supports dynamic agent addition/removal (TAIP-5) with automatic state adjustments
• Terminal states: Rejected, Cancelled, and Reverted states accept no further events
• Backward compatible: Default AutoApprove mode preserves existing behavior of auto-authorizing registered agents and auto-settling

Testing & Integration

• Updated integration tests to use new FSM infrastructure
• Stress test updated with default decision_mode configuration
• Event logger updated to handle DecisionRequired events

https://claude.ai/code/session_01YBT8UQJ3Z4bcVoaZ8V8u82