remove error handling redundant language

Author: kivo2

common/src/main/java/com/example/common/enums/SagaStatus.java

@@ -1,18 +1,5 @@
 package com.example.common.enums;
 
-/**
- * Lifecycle states for a Saga workflow instance.
- *
- * <p>State transitions:
- *
- * <p>STARTED → RUNNING → COMPLETED ↘ FAILED (permanent business failure — no retry) ↘ PENDING_RETRY
- * (transient failure — will retry) ↘ PERMANENTLY_FAILED (max retries exhausted)
- *
- * <p>KEY DISTINCTION: FAILED = business rule prevented completion (out of stock, card declined) No
- * retry — retrying won't help PERMANENTLY_FAILED = transient failure exhausted all retries Needs
- * manual intervention or customer action PENDING_RETRY = transient failure, retry scheduled at
- * next_retry_at
- */
 public enum SagaStatus {
   STARTED,
   RUNNING,

common/src/main/java/com/example/common/exceptions/DuplicateOrderException.java

@@ -2,15 +2,6 @@
 
 import java.util.UUID;
 
-/**
- * Thrown when an order already exists for this saga in a conflicting state.
- *
- * <p>NOTE: This is different from idempotency. Idempotency means: "I already did this work
- * successfully, here's the result." DuplicateOrderException means: "An order exists for this saga
- * but something is wrong."
- *
- * <p>FAILURE SCENARIO: "Order creation fails (duplicate order)"
- */
 public class DuplicateOrderException extends PermanentWorkerException {
 
   public DuplicateOrderException(UUID sagaId) {

common/src/main/java/com/example/common/exceptions/InsufficientStockException.java

@@ -1,16 +1,5 @@
 package com.example.common.exceptions;
 
-/**
- * Thrown when requested quantity exceeds available stock.
- *
- * <p>PERMANENT failure — retrying won't restock the warehouse.
- *
- * <p>FAILURE SCENARIO: "Inventory check fails (out of stock)" FAILURE SCENARIO: "Inventory
- * partially available (some items in stock, some not)"
- *
- * <p>The message should identify which product(s) failed and why. Example: "Insufficient stock for
- * prod_1: requested=5, available=2"
- */
 public class InsufficientStockException extends PermanentWorkerException {
 
   public InsufficientStockException(String productId, int requested, int available) {

common/src/main/java/com/example/common/exceptions/PaymentDeclinedException.java

@@ -1,15 +1,5 @@
 package com.example.common.exceptions;
 
-/**
- * Thrown when a payment is declined by the payment provider.
- *
- * <p>PERMANENT failure — retrying a declined card won't approve it. The customer needs to use a
- * different payment method.
- *
- * <p>FAILURE SCENARIO: "Payment declined (insufficient funds)"
- *
- * <p>Simulate by using token: "tok_declined"
- */
 public class PaymentDeclinedException extends PermanentWorkerException {
 
   public PaymentDeclinedException(String token) {

common/src/main/java/com/example/common/exceptions/PermanentWorkerException.java

@@ -1,13 +1,5 @@
 package com.example.common.exceptions;
 
-/**
- * Permanent failure — retrying will NOT help.
- *
- * <p>When the orchestrator catches this, it marks the saga FAILED immediately. No retry is
- * scheduled. The customer needs to take action.
- *
- * <p>Subclasses: InsufficientStockException, PaymentDeclinedException, DuplicateOrderException
- */
 public class PermanentWorkerException extends WorkerException {
 
   public PermanentWorkerException(String message) {

common/src/main/java/com/example/common/exceptions/TransientWorkerException.java

@@ -1,14 +1,5 @@
 package com.example.common.exceptions;
 
-/**
- * Transient failure — retrying MAY help.
- *
- * <p>When the orchestrator catches this, it schedules a retry with exponential backoff. If max
- * retries are exhausted, the saga moves to PERMANENTLY_FAILED.
- *
- * <p>Use this for: DB timeouts, network blips, service temporarily unavailable, any infrastructure
- * failure that is expected to resolve on its own.
- */
 public class TransientWorkerException extends WorkerException {
 
   public TransientWorkerException(String message) {

inventory-worker/src/main/java/com/example/inventory/domain/InventoryItem.java

@@ -5,16 +5,6 @@
 import lombok.NoArgsConstructor;
 import lombok.Setter;
 
-/**
- * Represents stock levels for a single product.
- *
- * <p>INVARIANT: available_qty + reserved_qty = total physical stock This invariant must hold after
- * every operation.
- *
- * <p>FAILURE SCENARIOS THIS ENABLES: - Out of stock: available_qty = 0 - Partial stock:
- * available_qty < requested for some items - Concurrent reservation: two checkouts race for the
- * same stock
- */
 @Entity
 @Table(name = "inventory_item")
 @Getter

inventory-worker/src/main/java/com/example/inventory/domain/InventoryRepository.java

@@ -12,20 +12,6 @@
 @Repository
 public interface InventoryRepository extends JpaRepository<InventoryItem, String> {
 
-  /**
-   * Load an inventory item with a pessimistic write lock.
-   *
-   * <p>WHY PESSIMISTIC LOCK HERE? Two concurrent checkouts for the same product must not both
-   * succeed if there's only enough stock for one. The pessimistic lock ensures only one transaction
-   * can read-and-modify the row at a time.
-   *
-   * <p>Transaction 1: SELECT ... FOR UPDATE → gets lock, checks qty, reserves Transaction 2: SELECT
-   * ... FOR UPDATE → BLOCKS until TX1 commits Transaction 2 then sees updated qty and may fail with
-   * InsufficientStock.
-   *
-   * <p>FAILURE SCENARIO THIS HANDLES: "Concurrent reservation — two checkouts race for the same
-   * stock"
-   */
   @Lock(LockModeType.PESSIMISTIC_WRITE)
   @Query("SELECT i FROM InventoryItem i WHERE i.productId = :productId")
   Optional<InventoryItem> findByIdForUpdate(String productId);

inventory-worker/src/main/java/com/example/inventory/domain/InventoryReservation.java

@@ -8,21 +8,6 @@
 import lombok.NoArgsConstructor;
 import lombok.Setter;
 
-/**
- * Records that inventory was reserved for a specific saga.
- *
- * <p>PURPOSE: Idempotency.
- *
- * <p>If reserveInventory() is called twice with the same sagaId (e.g. due to a retry), the second
- * call finds this record and returns immediately without modifying inventory quantities again.
- *
- * <p>WITHOUT THIS: A retry would double-reserve stock, corrupting inventory counts. WITH THIS: The
- * second call is a no-op. Safe to retry any number of times.
- *
- * <p>FAILURE SCENARIO THIS PREVENTS: "Inventory service crash mid-reservation — after DB write,
- * before response" On retry, the reservation record exists → skip → return success. No
- * double-reservation.
- */
 @Entity
 @Table(name = "inventory_reservation")
 @Getter

inventory-worker/src/main/java/com/example/inventory/service/InventoryService.java

@@ -18,26 +18,6 @@
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
-/**
- * Real inventory reservation logic.
- *
- * <p>CONTRACTS:
- *
- * <p>1. ATOMICITY: Either ALL items are reserved or NONE are. Check all items first. Only modify
- * quantities if all checks pass. This prevents partial reservations that leave the system
- * inconsistent.
- *
- * <p>2. IDEMPOTENCY: If called twice with the same sagaId, the second call is a no-op. Check
- * InventoryReservation table before doing any work.
- *
- * <p>3. PESSIMISTIC LOCKING: Each product row is locked before reading qty. Prevents concurrent
- * checkouts from both seeing sufficient stock and both succeeding when only one should.
- *
- * <p>FAILURE SCENARIOS IMPLEMENTED: - Out of stock (prod_3): throws InsufficientStockException -
- * Partial stock (prod_2 with qty > 3): throws InsufficientStockException - Concurrent reservation:
- * pessimistic lock serializes access - Transient failure simulation: productId "prod_error" throws
- * TransientWorkerException - Idempotency: second call for same sagaId returns immediately
- */
 @Slf4j
 @Service
 @RequiredArgsConstructor