Ensure dispute-driven Agreement changes trigger notifications & activity logs

[Kalchaqui]

Issue: Ensure dispute-driven Agreement changes trigger notifications & activity logs

Depends on: —

Task Description

Improve the reliability and consistency of Agreement data by making sure that every Agreement state change produces the same side effects, regardless of where it originates. Today, dispute-related state changes silently skip the notifications and activity logs that normal Agreement updates generate — so users are not notified and the audit trail is incomplete when a dispute changes an Agreement. This issue closes that gap so disputes behave like a first-class Agreement event.

This is a consistency and observability improvement, not a rewrite: existing endpoints and behaviors are preserved; we are adding the missing side effects and unifying how they fire.

Background / Current State

• DisputesService writes Agreement state changes directly to the agreements table in several places.
• Those direct writes bypass the central Agreement update path, so they do not emit the activity logs and notifications that the normal flow emits (dispute_opened, dispute_resolved, and related status changes).
• Result: when a dispute changes an Agreement's status, participants receive no notification and the activity history has gaps — a real data-consistency and user-experience problem.
• logActivity() currently exists in multiple copies across services, which makes it easy for a code path to log inconsistently or not at all.

Goals

• Every dispute-driven Agreement change emits the correct notification(s) and activity log entry, matching the normal update flow.
• A single, shared way to record Agreement activity so no code path can silently skip it.
• No user-facing behavior is lost; disputes keep working exactly as before, but now with complete notifications and audit history.

Non-Goals

• No new public endpoints.
• No changes to authorization or who can perform dispute actions.
• No change to the on-chain / Trustless Work dispute logic.

Deliverable

• Dispute-driven Agreement state changes route through the same side-effect path (notifications + activity logging) as normal Agreement updates.
• A single shared logActivity() used by all services (the duplicate copies are consolidated into one).

Requirements

• Dispute status changes (e.g. dispute opened, dispute resolved) produce the corresponding notification events, consistent with existing event types.
• Dispute-driven Agreement status changes produce activity log entries identical in shape to the normal flow.
• All services use one shared logActivity() implementation.
• GET /agreements/by-wallet must be preserved, not rewritten — this endpoint already exists with its own scoping/authorization; keep its behavior and access rules exactly as-is. Any interaction with it here is read-only reuse.

Validation System

• Open a dispute that changes an Agreement's status → confirm the participants receive the expected notification AND an activity log entry is created.
• Resolve a dispute → confirm the resolution notification and activity log entry are created.
• Compare a dispute-driven status change against an equivalent normal status change → confirm the activity log entries and notifications match in shape and coverage.
• Confirm GET /agreements/by-wallet returns the same results and respects the same scope as before this change.

Technical Requirements

• Reuse the existing notification event types and activity-log schema — do not invent new formats.
• Consolidate logActivity() into a single shared utility/service and update all call sites (remove usage before removing the now-dead copies).
• Keep the dispute flow's existing inputs/outputs stable so no caller breaks.

Additional Notes

Framed as an improvement: the value is complete, consistent notifications and audit history for disputes, plus a single logging path that prevents this class of gap from recurring. Keep the scope tight — this should be a low-risk change that makes an existing feature more trustworthy, not a structural overhaul.

Testing (required)

• Unit test: dispute-driven status change invokes the shared logging + notification path.
• Integration test (end-to-end): open dispute → status change → notification sent + activity log written; resolve dispute → same.
• Parity test: dispute-driven change produces activity/notification output equivalent to a normal Agreement status change.
• Regression test: GET /agreements/by-wallet behavior and scoping are unchanged.

Proof of Completion (required)

• Link the merged PR.
• Paste passing test output for the cases above.
• Attach evidence (logs/screenshots) showing a dispute event producing both a notification and an activity log entry.
• Attach evidence that GET /agreements/by-wallet returns identical, correctly-scoped results before and after the change.

[iyanumajekodunmi756]

Hi maintainer, I would love to work on this issue. I have studied the details of the issue description and I understood the requirements. I shall deliver with qualitative feedback and promptly.

[samjay8]

Hi maintainer,

I would love to apply and take on this issue. I have reviewed the task description and requirements for refactoring the AgreementService. I am confident in my ability to centralize the business logic cleanly, remove the duplicated controller validations, and ensure strict backward compatibility for the existing signatures (updateAgreementStatus and logAgreementActivity).

I am ready to get started and will ensure a high-quality, well-documented pull request.

Thanks for the opportunity!

[naninu123]

Hi! I'd like to take this on — Agreement Service refactoring to centralize business logic.

My approach:

• Extract validation + state transitions into AgreementService class
• Map endpoints to clean methods: createAgreement, listAgreements, getAgreement, updateStatus, updateMilestones, getActivity, findByContract
• Preserve current signatures (updateAgreementStatus, logAgreementActivity) for compatibility
• Add internal docs (docs/agreement-service.md) explaining the layer and usage

No breaking changes — only internal restructuring. Ready after assignment.

cc @naninu123

[grantfox-oss]

🦊 GrantFox — @naninu123 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #58)
2. Your PR will be reviewed by the Thalos-Infrastructure maintainers

Good luck! Track your progress on GrantFox.

[ManuelJG1999]

🎉 Congratulations @naninu123 ! This issue has been assigned to you.

Before you start, make sure you understand the requirements. If you have any questions, ask us in our community chat:
https://t.me/ThalosOSSCommunity

Please keep us updated on your progress. If there's no activity or communication within 48 hours, the issue may be reassigned to another contributor.

Happy coding, and thanks for contributing to Thalos! 🐉

[naninu123]

Proof of Work — Issue #58

PR: #100

What changed

1. Extracted shared AgreementActivityService (single agreement_activity writer)
2. Added AgreementsService.applyStatusChange — status update + activity log + domain events
3. DisputesService open/resolve/cancel now routes Agreement status through that path
4. WebhooksService uses the same activity helper (no more private logActivity copies)

Verification

npm test          → 280 passed
npx tsc --noEmit  → clean
npm run lint      → 0 errors

AC coverage

• Unit: dispute open/resolve → events + activity logs ✅
• Integration: dispute flows still green ✅
• Parity: dispute-driven status_changed_to_* matches normal updateStatus shape ✅
• Regression: listByWallet scoping unchanged ✅

Ready for review.