Make schema validation and error mapping idempotent in `src/utils/validation.ts`

[Jagadeeshftw]

Description

Repeated delivery or retrying the same request can currently produce ambiguous outcomes. src/utils/validation.ts owns schema validation and error mapping, but the current behavior does not yet define the contract tightly enough for safe maintenance. Design the change so the runtime path, tests, and docs all describe the same behavior.

Requirements and context

• Keep the contract specific to src/utils/validation.ts and its existing callers.
• Add coverage for the success path and the failure or boundary path relevant to this issue.
• Preserve compatibility where older callers or existing tests already rely on the current shape.
• Keep the change easy to review and small enough for one focused PR.

Suggested execution

Fork the repo and create a branch

git checkout -b validation-errors-idempotency-199

Implement changes

• Update/Write: src/utils/validation.ts
• Write comprehensive tests: src/utils/validation.test.ts
• Add documentation: docs/utils/validation.md
• Keep any new helper names consistent with the rest of src/

Test and commit

• Run pnpm test
• Run pnpm lint
• Add a note for any edge cases that are intentionally out of scope

Example commit message

fix: add idempotency and duplicate-request protection

Guidelines

• WCAG 2.1 AA is not relevant here; keep the focus on correctness and maintainability.
• Prefer a narrow, well-documented fix over a broad refactor.
• Timeframe: 96 hours

[drips-wave]

@Jagadeeshftw This issue could not be added to the Stellar Wave Program because the per-repo points budget would be exceeded (25000 / 25000 points already used). The label has been automatically removed.

The budget resets at the end of each Wave. You can review the remaining budget for your repos on the Orgs & Repos page.

ℹ️ Learn more about points budgets

[drips-wave]

@Jagadeeshftw This issue could not be added to the Stellar Wave Program because the per-repo points budget would be exceeded (25000 / 25000 points already used). The label has been automatically removed.

The budget resets at the end of each Wave. You can review the remaining budget for your repos on the Orgs & Repos page.

ℹ️ Learn more about points budgets

[drips-wave]

@Jagadeeshftw This issue could not be added to the Stellar Wave Program because the per-repo points budget would be exceeded (25000 / 25000 points already used). The label has been automatically removed.

The budget resets at the end of each Wave. You can review the remaining budget for your repos on the Orgs & Repos page.

ℹ️ Learn more about points budgets