docs(dlq): document message-validation reason codes and routing contract

[Bolajiomo99]

Documents every DlqReasonCode, the validateAndRoute flow, bondOperationSchema rules, formatZodErrors output, and the replay path in src/services/replayService.ts.

Closes #643

Description

This pull request adds a focused operations document (docs/dlq-message-validation.md) describing every DlqReasonCode, when it is emitted, and how to replay vs discard a quarantined message. The reason-code taxonomy and routing rules were previously undocumented, making it difficult for contributors and on-call engineers to triage poisoned messages in the failed_inbound_events table.

Previously, an operator finding a DLQ entry would see only a raw event_data blob and a free-text failure_reason with no structured reference explaining what each reason code means or what to do next.

Changes Made

• Created docs/dlq-message-validation.md covering:
  • Reason codes — all 4 DlqReasonCode values (SCHEMA_VALIDATION_FAILED, UNKNOWN_MESSAGE_TYPE, PROCESSING_ERROR, MAX_RETRIES_EXCEEDED) with trigger condition, example payload, stored failure_reason format, and operator action.
  • validateAndRoute flow — ASCII diagram of the validation pipeline from raw payload through Zod safeParse → ValidationResult → DlqRouter.route → sink.captureFailure → DB insert.
  • DlqRouter sink behaviour — reason format ([CODE] detail), raw payload preservation, message type labels, error propagation.
  • bondOperationSchema and bondWithdrawalOperationSchema — per-field Zod rules (source_account, id, amount, duration) with Stellar account ID validation and integer-string regex.
  • formatZodErrors output — semicolon-separated path: message pairs with examples for root-level, single, multi-field, and nested path failures.
  • Replay path — ReplayService class, admin REST endpoints (GET /api/admin/events/failed, POST /api/admin/events/replay/:id), replay flow diagram, manual curl commands, and handler registration.
  • Database schema — all columns of failed_inbound_events with types and descriptions.
  • Concrete sample DLQ entry — a real-world row showing every column populated.
• Every documented reason code verified against the DlqReasonCode enum in src/listeners/messageValidator.ts:12.

Closes #643

Type of Change

• Bug Fix (non-breaking change which fixes an issue)
• New Feature (non-breaking change which adds functionality)
• Breaking Change (fix or feature that would cause existing functionality to not work as expected)
• Refactoring / Performance (clean-up or performance optimization without behavioral changes)
• Documentation / CI (changes to docs, workflows, config files)

Verification & Test Plan

Automated Tests

• Documents every DlqReasonCode, the validateAndRoute flow, bondOperationSchema rules, formatZodErrors output, and the replay path in src/services/replayService.ts.

Closes #643

Description

This pull request adds a focused operations document (docs/dlq-message-validation.md) describing every DlqReasonCode, when it is emitted, and how to replay vs discard a quarantined message. The reason-code taxonomy and routing rules were previously undocumented, making it difficult for contributors and on-call engineers to triage poisoned messages in the failed_inbound_events table.

Previously, an operator finding a DLQ entry would see only a raw event_data blob and a free-text failure_reason with no structured reference explaining what each reason code means or what to do next.

Changes Made

• Created docs/dlq-message-validation.md covering:
  • Reason codes — all 4 DlqReasonCode values (SCHEMA_VALIDATION_FAILED, UNKNOWN_MESSAGE_TYPE, PROCESSING_ERROR, MAX_RETRIES_EXCEEDED) with trigger condition, example payload, stored failure_reason format, and operator action.
  • validateAndRoute flow — ASCII diagram of the validation pipeline from raw payload through Zod safeParse → ValidationResult → DlqRouter.route → sink.captureFailure → DB insert.
  • DlqRouter sink behaviour — reason format ([CODE] detail), raw payload preservation, message type labels, error propagation.
  • bondOperationSchema and bondWithdrawalOperationSchema — per-field Zod rules (source_account, id, amount, duration) with Stellar account ID validation and integer-string regex.
  • formatZodErrors output — semicolon-separated path: message pairs with examples for root-level, single, multi-field, and nested path failures.
  • Replay path — ReplayService class, admin REST endpoints (GET /api/admin/events/failed, POST /api/admin/events/replay/:id), replay flow diagram, manual curl commands, and handler registration.
  • Database schema — all columns of failed_inbound_events with types and descriptions.
  • Concrete sample DLQ entry — a real-world row showing every column populated.
• Every documented reason code verified against the DlqReasonCode enum in src/listeners/messageValidator.ts:12.

Closes #643

Type of Change

• Bug Fix (non-breaking change which fixes an issue)
• New Feature (non-breaking change which adds functionality)
• Breaking Change (fix or feature that would cause existing functionality to not work as expected)
• Refactoring / Performance (clean-up or performance optimization without behavioral changes)
• Documentation / CI (changes to docs, workflows, config files)

Verification & Test Plan

Automated Tests

• npm run lint — 0 errors, 27 pre-existing warnings in unrelated files.
• npm run build — pre-existing errors in unrelated files (sorobanStateCache, apiKeysRepository, webhookIntegration, etc.); no new errors introduced.

Manual Verification

• Confirmed all 4 DlqReasonCode values exist in the enum at src/listeners/messageValidator.ts:12 — no invented codes.
• Verified field names, schemas, and line numbers match the source code exactly.
• Cross-referenced src/services/replayService.ts for the replay flow and handler registration.
• Cross-referenced src/routes/admin/index.ts for admin API endpoints.
• Cross-referenced src/db/repositories/failedInboundEventsRepository.ts for the database schema.

Notes

• No .ts files were touched — this is documentation only.
• The pre-existing TypeScript build errors are a codebase-wide issue present on main and are unrelated to this change.

Checklist

• Code follows the project's style guidelines.

• Added comprehensive unit tests.

• Performed a self-review.

• Added inline documentation (TSDoc).

• No new warnings introduced.

• All existing tests continue to pass.

• npm run build — pre-existing errors in unrelated files (sorobanStateCache, apiKeysRepository, webhookIntegration, etc.); no new errors introduced.

Manual Verification

• Confirmed all 4 DlqReasonCode values exist in the enum at src/listeners/messageValidator.ts:12 — no invented codes.
• Verified field names, schemas, and line numbers match the source code exactly.
• Cross-referenced src/services/replayService.ts for the replay flow and handler registration.
• Cross-referenced src/routes/admin/index.ts for admin API endpoints.
• Cross-referenced src/db/repositories/failedInboundEventsRepository.ts for the database schema.

Notes

• No .ts files were touched — this is documentation only.
• The pre-existing TypeScript build errors are a codebase-wide issue present on main and are unrelated to this change.

Checklist

• Code follows the project's style guidelines.
• Added comprehensive unit tests.
• Performed a self-review.
• Added inline documentation (TSDoc).
• No new warnings introduced.
• All existing tests continue to pass.

[drips-wave]

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