[Olabsy19]

Overview

This PR replaces generic Error paths for missing claims and invalid lifecycle transitions with stable, versioned typed domain results and HTTP mappings. It preserves canonical state/phase derivation and idempotent retry semantics, and ensures clients can distinguish not-found, denied, conflict, stale, and unavailable outcomes without leaking internal details.

Related Issue

Changes

🧩 Typed Claim Lifecycle Errors

• [MODIFY] src/claims/claim-resolution.service.ts

  • Replaces generic Error throws for missing claims and invalid transitions with typed domain results.
  • Preserves canonical state/phase resolution and idempotent retry behavior.

• [MODIFY] src/claims/claim-resolution.invariant.ts

  • Adds invariant checks that map ambiguous, stale, or unauthorized states to typed failure results (fail closed).

• [MODIFY] src/claims/claim-lifecycle.controller.ts

  • Maps typed domain results to stable HTTP responses so clients can distinguish not-found, denied, conflict, stale, and unavailable.

• [MODIFY] src/claims/claims.service.ts

  • Propagates typed results through the service layer instead of generic errors.

• [MODIFY] src/claims/claim-projector.service.ts

  • Aligns projection handling with typed results for stale/reorged projections while keeping state transitions contract-derived.

• [MODIFY] src/claims/claims.module.ts

  • Wires the updated providers/invariants into the claims module.

📚 Documentation

• [MODIFY] docs/API_REFERENCE.md
  • Documents the versioned error codes and their HTTP mappings for claim lifecycle outcomes.

Verification Results

npm test -- src/claims
✅ Claim lifecycle tests passed (missing, forbidden, wrong phase, duplicate, stale projection, reorged, invalid transition)

Acceptance Criteria	Status
Clients can distinguish not-found, denied, conflict, stale, and unavailable	✅ Typed domain results mapped to distinct HTTP responses
Error codes are versioned and documented	✅ Versioned codes documented in docs/API_REFERENCE.md
Internal details are not leaked	✅ Responses expose only stable codes/messages
State transitions remain contract-derived	✅ Canonical state/phase resolution preserved; fail closed on stale/ambiguous state

Closes #642

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Repository: DigiNodes/truthbounty-api/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 9261c753-2129-4fba-9c85-094340c0b1fc

📥 Commits

Reviewing files that changed from the base of the PR and between f437c8b and df9fa00.

📒 Files selected for processing: 7

• docs/API_REFERENCE.md
• src/claims/claim-lifecycle.controller.ts
• src/claims/claim-projector.service.ts
• src/claims/claim-resolution.invariant.ts
• src/claims/claim-resolution.service.ts
• src/claims/claims.module.ts
• src/claims/claims.service.ts

+-----------------------------------------------------------------------------------------------------------+
| A CodeRabbit review a day keeps the merge cop away: https://x.com/ThePrimeagen/status/1986151686839116209 |
+-----------------------------------------------------------------------------------------------------------+
  \
   \     /)/)
        ( '')
        /  |
      o(___)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dDevAhmed]

resolve conflicts @Olabsy19