Build a Distributed Saga Coordinator for Multi-Step Cross-Contract Operations With Compensating Transactions

[Emmyt24]

Description

Some backend-orchestrated operations (e.g. batch token deploy plus governance registration) span multiple independent state machines with no all-or-nothing guarantee — a failure partway through can leave a token deployed but never registered for governance, with no automated way to detect or correct it.

Requirements and Context

• Implement a saga coordinator that models multi-step cross-service operations as an explicit sequence of steps, each with a defined compensating (undo) action
• Persist saga state so an in-flight saga survives a process restart and can be resumed or compensated correctly
• Compensation must run in reverse order and must be idempotent — a compensation action re-run after a partial compensation must not double-undo
• Model the batch-deploy-plus-governance-registration flow as the first real saga using the coordinator
• Proof of work (required): this is a hard/complex issue — the PR description must include (1) a screenshot of the full relevant test suite run showing all tests passing, and (2) a screenshot of a successful project/module build or compile (npm run build) with no errors. PRs missing either screenshot will not be reviewed.

Suggested Execution

Branch: feat/backend-saga-coordinator

Implement Changes

• Add a SagaCoordinator service with a persisted saga_executions table tracking step index, status, and compensation status
• Wire the batch-deploy-plus-governance-registration flow through the coordinator
• Add a recovery job that scans for interrupted sagas on startup and resumes or compensates them
• Add tests for: full success, mid-saga failure triggering full compensation, and a crash-and-resume scenario

Test and Commit

Run npx vitest run src/__tests__/sagaCoordinator.test.ts — full-success, mid-failure-compensation, and crash-resume scenarios all pass. Then run npm run build and confirm it completes with no errors. Attach a screenshot of both the passing test run and the successful build to the PR description as proof of work.

Example Commit Message

feat(backend): distributed saga coordinator with persisted compensation for cross-service operations

Closes #<issue>

Guidelines

• Branch from main, open a PR back to main
• All new code must have corresponding tests
• Run npm run lint and npm run test before pushing
• Follow existing naming conventions and file structure
• PR description must reference this issue number (e.g., Closes #<issue>)
• Keep commits atomic and use conventional commit format
• This is a hard/complex issue: PR must include a screenshot of the test suite passing and a screenshot of a successful build/compile — PRs without both screenshots will be marked incomplete and not merged