docs: distribution and reconciliation architecture map (#537)

[sladeoj]

Summary

Author docs/architecture/distribution-reconciliation.md as the single, authoritative end-to-end architecture map of how offerings, revenue reports, the distribution engine, the reconciliation service, and the transactional webhook outbox interlock. Cross-link TSDoc added to every relevant service / route / repository file.

What changed

• New doc: docs/architecture/distribution-reconciliation.md — 10 sections: subsystem map, end-to-end sequence diagrams (distribution run + reconciliation), four state machines (distribution_runs.status, revenue_reports.distribution_status, webhook_outbox.status, reconciliation isBalanced), database table ownership matrix, cross-reference matrix, security assumptions, failure-mode index, CI hooks, maintenance rules. All diagrams rendered from committed Mermaid sources so they diff-review cleanly.
• Cross-link JSDoc headers added to the top of:
  • src/services/distributionEngine.ts
  • src/services/distributionScheduler.ts
  • src/services/revenueReconciliationService.ts
  • src/services/reconciliationScheduler.ts
  • src/services/outboxDispatcher.ts
  • src/db/repositories/distributionRepository.ts
  • src/db/repositories/revenueReportRepository.ts
  • src/db/repositories/outboxRepository.ts
  • src/routes/distributions.ts
  • src/routes/reconciliationRoutes.ts

Behavioural change

None. Only JSDoc @see blocks and one new markdown file. No runtime code paths touched.

Validation

• npx tsc --noEmit — pre-existing TS1005 errors in distributionScheduler.test.ts:763 and statementDataProvider.ts:157 exist on master and are unrelated to this commit (verified by stashing and checking master).
• npx jest against the 9 affected suites — 65 pre-existing failures, 201 passing. Identical on master (verified). No new failures introduced.
• Code-reviewer pass: APPROVED (3 minor non-blocking notes captured as follow-ups).

Security notes

The doc explicitly enumerates the trust boundary (raw Stellar RPC errors never cross the API), the source of truth for payouts (on-chain Stellar tx), the lock ownership invariant (transaction-scoped advisory locks cannot leak), and the outbox atomicity requirement (outbox row + domain row must share a withTransaction block).

Follow-ups (tracked as separate issue suggestions, not in this PR)

1. distribution_runs.status state machine currently lists pending as the initial state, but DistributionEngine.distributeWithBatch creates runs with status: "processing" directly. Either drop pending from the diagram or annotate that it is reserved for direct repository insertion.
2. revenue_reports.distribution_status state machine conflates the status (approval) and distribution_status (distribution progress) columns. Split into two diagrams or annotate the claim query's preconditions.

Issue

Closes #537.

[drips-wave]

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