feat: deferred distribution scheduling with idempotent dispatch

[BALLUCK004]

Closes #871

Summary

Adds deferred distribution scheduling: operators can queue a specific distribution run at a future settlement window and the DistributionScheduler honors it idempotently.

What was built

• Migration src/db/migrations/021_create_scheduled_distributions.sql – new scheduled_distributions table with (offering_id, period_id, run_at, status) and a UNIQUE (offering_id, period_id) idempotency key, plus a partial index for due rows and a partial index for per-offering listing.
• ScheduledDistributionRepository (src/db/repositories/scheduledDistributionRepository.ts) – create (409 on duplicate), findDueScheduledDistributions(now, leaseMs, limit) (due + stale-processing reclaim), atomic claimScheduledDistribution, markCompleted/markFailed/markCancelled, findById/findByOffering/findAll.
• DistributionScheduler.processScheduledDistributions(now?) (src/services/distributionScheduler.ts) – picks due rows, claims atomically, dispatches through DistributionEngine.distribute(offering_id, period, amount) with the stored snapshot boundary (period_start/period_end, falling back to run_at). Failure is sanitized to Distribution failed: <CLASS> and persisted on the row; per-row failure never aborts the tick. Configured via optional scheduledDistributionRepo / staleLeaseMs options (source-compatible; safe no-op when not configured).
• Admin endpoints (src/routes/distributions.ts, admin-only):
  • POST /distributions/schedule – enqueue (201; 400 validation; 403 non-admin; 404 unknown offering; 409 duplicate)
  • GET /distributions/schedule – list (optional offering_id filter)
  • DELETE /distributions/schedule/:id – cancel a pending run (200; 404 if not cancellable)
• Docs docs/deferred-distribution-scheduling.md – data model, scheduler semantics, idempotency-across-restart rationale, endpoint contracts, security/failure modes.

Acceptance criteria mapping

• Implemented across distributionScheduler.ts + distributionEngine.ts – scheduler drives the engine with the queued snapshot boundary and amount; engine unchanged (existing idempotency findRunByParams short-circuit is what makes restart re-runs safe).
• Security / authorization – all queue endpoints require admin role (403 otherwise); error_message only stores sanitized failure class, never raw DB/provider errors.
• Failure / concurrency / restart behavior – atomic claim (UPDATE ... WHERE status='scheduled'), 15-min lease reclaim for crashed schedulers, in-process skip of already-claimed rows, per-row isolation; completed rows are skipped on backfill after restart.
• Regression coverage – empty due set, duplicate enqueue (409), invalid/zero amounts, past-dated run_at, cancelled/completed not re-picked, missing repo no-op, mark-failed throw, custom lease.
• Compatibility – purely additive: new table, new optional constructor options, new endpoints; existing scheduler API untouched.

Validation

• src/db/repositories/scheduledDistributionRepository.test.ts – 17 tests, 100% statements/branches/functions/lines.
• src/services/distributionScheduler.test.ts – 8 new processScheduledDistributions tests pass.
• src/routes/__tests__/distributions.test.ts – 26 tests pass (13 new).
• New repository added to jest.config.js collectCoverageFrom.
• tsc --noEmit reports no errors in the changed files.

Note: the repo has pre-existing failures unrelated to this change, reproduced on master without this PR: 60 failing tests in src/services/distributionScheduler.test.ts (un-imported validateCronSyntax/STELLAR_MAINTENANCE_WINDOWS) and 6 in src/services/__tests__/distributionScheduler.test.ts (private-member access), plus a repo-wide no-explicit-any lint backlog. Targeted suites for this change are green.

Migration: apply with npm run migrate (filename-unique, tracked in schema_version).

[drips-wave]

@BALLUCK004 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