Improve Agreement Router reliability, validation consistency, and template handling

[muralimadhava96-ui]

Overview
This PR refactors the Agreement router to improve code structure, validation robustness, and execution safety. It also introduces comprehensive test coverage for agreement execution, template handling, and error scenarios.

The goal is to align the implementation with production-grade backend practices while ensuring reliability and maintainability.

---

Key Improvements

-->Architecture & Maintainability

• Introduced service-level abstractions (e.g., resolveAgreement, template resolution)
• Reduced duplication in template lookup logic
• Simplified control flow and improved readability

--> Validation Enhancements

• Combined schema validation with domain-level validation (Concerto)
• Added strict ID parsing to prevent invalid database queries
• Improved validation for trigger request types

--> Safer Execution

• Avoided full object mutation during database updates (partial state updates only)
• Ensured agreement state is initialized safely before trigger execution
• Improved error handling with consistent response structure

--> Template Handling

• Simplified template URI normalization
• Added hash-based template caching to avoid duplicate inserts
• Improved external template fetching and storage flow

--> Logging

• Replaced console logs with structured logging for better debugging and observability

---

Test Coverage

-->Added comprehensive tests covering:

• ✅ Successful agreement trigger execution
• ✅ State persistence across multiple triggers
• ✅ Validation failures (invalid request types and malformed payloads)
• ✅ Error scenarios (missing agreement, missing template, DB failures)
• ✅ External template fetching and database insertion
• ✅ Request parsing edge cases (invalid JSON)

-->Test improvements:

• Removed duplicate test definitions
• Introduced structured test organization (Trigger, Errors, Creation)
• Replaced unsafe mocks with partial mocks
• Improved type safety for mocked database layer

---

--> Behavior Changes

• More consistent HTTP responses (clear distinction between 400 and 500 errors)
• Safer handling of invalid IDs and malformed inputs
• More predictable and reliable trigger execution flow

---

--> Performance

• Reduced redundant database queries via centralized template resolution
• Improved caching efficiency using template hash lookup

---

--> Compatibility

• No breaking API changes introduced
• Existing routes and response formats remain unchanged

---

--> Future Work

• Add authentication and authorization middleware
• Introduce rate limiting for trigger endpoints
• Replace remaining any types with strict typings
• Expand test coverage (edge cases, performance scenarios)
• Support additional template retrievers (e.g., IPFS, GitHub)

---

--> Motivation
This refactor improves reliability, maintainability, and developer experience while preparing the codebase for future scalability and extensibility. The addition of strong test coverage ensures confidence in agreement execution and template processing workflows.

[muralimadhava96-ui]

Hi maintainers 👋

This PR focuses on improving Agreement API reliability by:

• reducing over-mocking in tests
• improving error visibility
• making validation responses consistent

I’d really appreciate your feedback on whether this direction aligns with the project’s testing and API design approach.

Especially curious about:
👉 preferred balance between mocking vs real template execution in tests

Thanks!