feat(budgets): add Redis-backed distributed mutex guard for spending limits

[lewistemple22]

Overview

This PR adds a distributed locking mechanism using Redis to prevent race conditions when multiple concurrent AI agent transactions attempt to evaluate and deduct from the same spending budget simultaneously.

Related Issue

Closes #86

Changes

🛡️ Distributed Mutex Guard

• [ADD] src/modules/budgets/services/spending-limit-guard.service.ts — SpendingLimitGuardService wraps the budget check + consume cycle in a single Redis distributed lock (SETNX with TTL) to eliminate the TOCTOU race condition
• [ADD] src/modules/budgets/budget.module.ts — Wire RedisLock and SpendingLimitGuardService into the module providers and exports

🔗 Transaction Pipeline Integration

• [MODIFY] src/modules/transactions/transaction.service.ts — For auto-executable transactions, use SpendingLimitGuardService.guardAndConsume() instead of separate assertWithinBudget() + consume() calls. Approval-required transactions still use the check-only path with consume deferred to execute().

🧪 Unit Tests

• [ADD] src/modules/budgets/services/spending-limit-guard.service.spec.ts — 12 Vitest tests covering:
  • Lock acquisition and atomic check+consume
  • Budget exceeded rejection (no spend recorded)
  • Budget not found handling
  • Redis infrastructure failure → ConflictException
  • Concurrent attempt serialization
  • Custom TTL support

Verification Results

npx tsc --noEmit          ✅ Passed
npx vitest run            ✅ 148/148 passed (0 failed)

Acceptance Criteria

Criteria	Status
Distributed lock utility with TTL	✅ SpendingLimitGuardService with configurable TTL (default 5s)
Lock prevents race conditions in spending pipeline	✅ Atomic check+consume under lock:budget:{id}
Automatic TTL expiration prevents deadlocks	✅ Redis PX + NX flags with Lua-based safe release
Vitest unit tests for concurrent attempts	✅ 12 tests including concurrent serialization scenario
Typecheck and tests pass	✅ tsc --noEmit + vitest run all green

[drips-wave]

@lewistemple22 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[mergekeeper]

MergeKeeper review unavailable

AI provider review response did not contain valid JSON

No approval or merge action was taken.

[mergekeeper]

MergeKeeper review

Scope: in scope for linked issue #86.
Verdict: clean

The PR successfully implements a Redis-backed distributed mutex guard for spending limit evaluation with appropriate tests and transaction pipeline integration.

Reviewed commit: 3eba99161d32b8c56f9301472812893bb3438606.
CI and merge eligibility are checked separately.