1. T - Pure calculation, cannot fail
2. Option - Absence is normal, not an error
3. Result - Parsing can fail with a reason
4. Promise - Remote I/O, can fail asynchronously
5. Result - Validation can fail with a reason
6. Option - Cache miss is normal, not an error

A is wrong: Authentication failure is an error with a reason (wrong password, account locked, user not found). Should be:

public Result<User> authenticate(String email, String password)

B is wrong: “Optional config” implies absence is expected, not an error. Should be:

public Option<Config> getOptionalConfig(String key)

public Promise<UserProfile> loadProfile(String userId) {
    return UserId.userId(userId)
        .async()  // Result -> Promise
        .flatMap(id -> cache.get(id)
            .async(CACHE_MISS)  // Option -> Promise (with cause for empty)
            .recover(cause -> database.fetchProfile(id)));
}

// Alternative: if cache miss should fall through silently
public Promise<UserProfile> loadProfile(String userId) {
    return UserId.userId(userId)
        .async()
        .flatMap(id -> cache.get(id)
            .map(Promise::success)
            .or(() -> database.fetchProfile(id)));
}

public sealed interface RegistrationError extends Cause {

    record EmailExists(String email) implements RegistrationError {
        private static final Fn1<Cause, String> FACTORY =
            Causes.forOneValue("Email already registered: %s");

        @Override
        public String message() {
            return FACTORY.apply(email).message();
        }
    }

    record WeakPassword(String weakness) implements RegistrationError {
        private static final Fn1<Cause, String> FACTORY =
            Causes.forOneValue("Password too weak: %s");

        @Override
        public String message() {
            return FACTORY.apply(weakness).message();
        }
    }

    record InvalidUsername(String invalidChars) implements RegistrationError {
        private static final Fn1<Cause, String> FACTORY =
            Causes.forOneValue("Username contains invalid characters: %s");

        @Override
        public String message() {
            return FACTORY.apply(invalidChars).message();
        }
    }
}

1. 20 - maps 10 to 20, or() returns value
2. 0 - failure skips map, or() returns fallback
3. Result.success(10) - predicate passes
4. Result.failure(Cause("not negative")) - predicate fails
5. Result.failure(Cause("error")) - all() accumulates failure from second

public record PhoneNumber(String value) {
    private static final Pattern DIGITS_ONLY = Pattern.compile("\\d+");
    private static final Cause INVALID_FORMAT =
        Causes.cause("Phone number must contain only digits, dashes, and optional leading +");
    private static final Cause INVALID_LENGTH =
        Causes.cause("Phone number must be 10-15 digits");

    public static Result<PhoneNumber> phoneNumber(String raw) {
        return Verify.ensure(raw, Verify.Is::notBlank)
            .map(PhoneNumber::normalize)
            .filter(INVALID_FORMAT, PhoneNumber::isValidFormat)
            .filter(INVALID_LENGTH, s -> Verify.Is.lenBetween(s, 10, 15))
            .map(PhoneNumber::new);
    }

    private static String normalize(String input) {
        return input.replaceAll("[^0-9]", "");
    }

    private static boolean isValidFormat(String normalized) {
        return DIGITS_ONLY.matcher(normalized).matches();
    }
}

public record DateRange(LocalDate from, LocalDate to) {
    private static final Cause FROM_AFTER_TO =
        Causes.cause("Start date must be before or equal to end date");
    private static final Cause FROM_IN_PAST =
        Causes.cause("Start date cannot be in the past");
    private static final Cause TO_IN_PAST =
        Causes.cause("End date cannot be in the past");

    public static Result<DateRange> dateRange(String fromRaw, String toRaw) {
        var today = LocalDate.now();

        return Result.all(parseAndValidate(fromRaw, today, FROM_IN_PAST),
                         parseAndValidate(toRaw, today, TO_IN_PAST))
                     .flatMap(DateRange::validateOrder);
    }

    private static Result<LocalDate> parseAndValidate(String raw, LocalDate today, Cause pastError) {
        return DateTime.parseLocalDate(raw)
            .filter(pastError, date -> !date.isBefore(today));
    }

    private static Result<DateRange> validateOrder(LocalDate from, LocalDate to) {
        if (from.isAfter(to)) {
            return FROM_AFTER_TO.result();
        }
        return Result.success(new DateRange(from, to));
    }
}

Version A (short-circuit): Returns failure with ONLY the email error. flatMap stops at first failure.

Version B (accumulation): Returns failure with BOTH errors in a CompositeCause. Result.all() collects all failures.

When to use each:

• Use flatMap chain when errors are dependent (later validations need earlier values)
• Use Result.all() when validations are independent and you want to show all errors to user

public Result<User> processUser(UserDto dto) {
    return Result.all(Email.email(dto.email()),
                     processOptionalName(dto.name()),
                     processOptionalAddress(dto.address()))
                 .map(User::new);
}

private Result<Option<Name>> processOptionalName(String raw) {
    return Option.option(raw)
        .map(String::trim)
        .filter(s -> !s.isBlank())
        .map(Name::new)
        .fold(
            () -> Result.success(Option.none()),
            name -> Result.success(Option.some(name))
        );
}

private Result<Option<Address>> processOptionalAddress(AddressDto dto) {
    return Option.option(dto)
        .map(this::validateAddress)
        .fold(
            () -> Result.success(Option.none()),
            result -> result.map(Option::some)
        );
}

// User record accepts Option types
public record User(Email email, Option<Name> name, Option<Address> address) {}

public Promise<Config> loadConfig() {
    return loadFromDatabase()
        .recover(this::recoverFromDatabaseError);
}

private Promise<Config> recoverFromDatabaseError(Cause cause) {
    return switch (cause) {
        case ConnectionError ignored -> loadFromFile()
            .recover(this::recoverFromFileError);
        default -> cause.promise();
    };
}

private Promise<Config> recoverFromFileError(Cause cause) {
    return switch (cause) {
        case FileNotFound ignored -> Promise.success(defaultConfig());
        default -> cause.promise();
    };
}

• A: Sequencer - Linear chain of dependent steps
• B: Fork-Join - Parallel independent operations combined
• C: Condition - Routing based on discriminator
• D: Leaf - Adapter wrapping external I/O

public interface LoadDashboard {
    Promise<Dashboard> load(UserId userId);

    record Dashboard(UserProfile profile, List<Order> orders, List<Product> recommendations) {}

    interface FetchProfile {
        Promise<UserProfile> apply(UserId userId);
    }

    interface FetchOrders {
        Promise<List<Order>> apply(UserId userId);
    }

    interface FetchRecommendations {
        Promise<List<Product>> apply(UserId userId);
    }

    static LoadDashboard create(FetchProfile fetchProfile,
                                FetchOrders fetchOrders,
                                FetchRecommendations fetchRecommendations) {
        return userId -> Promise.all(fetchProfile.apply(userId),
                                    fetchOrders.apply(userId),
                                    fetchRecommendations.apply(userId)
                                        .recover(cause -> Promise.success(List.of())))
                                .map(Dashboard::new);
    }
}

public interface SendNotification {
    Promise<Unit> send(UserId userId, Message message);

    interface GetPreference {
        Promise<NotificationPreference> apply(UserId userId);
    }

    interface SendEmail {
        Promise<Unit> apply(UserId userId, Message message);
    }

    interface SendSms {
        Promise<Unit> apply(UserId userId, Message message);
    }

    interface SendPush {
        Promise<Unit> apply(UserId userId, Message message);
    }

    static SendNotification create(GetPreference getPreference,
                                   SendEmail sendEmail,
                                   SendSms sendSms,
                                   SendPush sendPush) {
        return (userId, message) -> getPreference.apply(userId)
            .flatMap(pref -> routeByPreference(pref, userId, message,
                                               sendEmail, sendSms, sendPush));
    }

    private static Promise<Unit> routeByPreference(NotificationPreference pref,
                                                    UserId userId,
                                                    Message message,
                                                    SendEmail sendEmail,
                                                    SendSms sendSms,
                                                    SendPush sendPush) {
        return switch (pref) {
            case EMAIL -> sendEmail.apply(userId, message);
            case SMS -> sendSms.apply(userId, message);
            case PUSH -> sendPush.apply(userId, message);
            case NONE -> Promise.unitPromise();
        };
    }
}

public interface FetchData {
    Promise<Data> apply(DataId id);

    static FetchData withAspects(FetchData base, Logger log) {
        return id -> withRetry(withTimeout(base, id), id, log, 3);
    }

    private static Promise<Data> withTimeout(FetchData base, DataId id) {
        return base.apply(id)
            .timeout(TimeSpan.timeSpan(5).seconds());
    }

    private static Promise<Data> withRetry(Promise<Data> operation,
                                           DataId id,
                                           Logger log,
                                           int remainingAttempts) {
        return operation.recover(cause -> {
            log.warn("Fetch failed for {}: {}", id, cause.message());

            if (remainingAttempts <= 0) {
                return cause.promise();
            }

            return switch (cause) {
                case TransientError ignored -> {
                    log.info("Retrying fetch for {}, {} attempts remaining",
                             id, remainingAttempts);
                    yield withRetry(operation, id, log, remainingAttempts - 1);
                }
                default -> cause.promise();
            };
        });
    }
}

Issues:

1. processedOrders is mutable and accessed from multiple threads (Promise callbacks)
2. totalAmount is a primitive with non-atomic read-modify-write
3. State mutation in callbacks violates JBCT principles

Fix: Remove shared mutable state, return immutable results

public class OrderProcessor {
    public Promise<OrderResult> process(Order order) {
        return validateOrder(order)
            .flatMap(this::chargePayment)
            .map(payment -> new OrderResult(order, payment));
    }
}

// Track processed orders externally with thread-safe collection if needed
public record OrderResult(Order order, Payment payment) {
    public int amount() {
        return order.amount();
    }
}

// If aggregation is needed, do it at a higher level:
public Promise<BatchResult> processBatch(List<Order> orders) {
    return Promise.allOf(orders.stream()
                               .map(this::process)
                               .toList())
                  .map(this::aggregateResults);
}

private BatchResult aggregateResults(List<Result<OrderResult>> results) {
    // Immutable aggregation
    var successful = results.stream()
        .filter(Result::isSuccess)
        .map(r -> r.fold(cause -> null, identity()))
        .filter(Objects::nonNull)
        .toList();

    int total = successful.stream()
        .mapToInt(OrderResult::amount)
        .sum();

    return new BatchResult(successful, total);
}

class AgeTest {

    @Test
    void age_succeeds_forValidValue() {
        Age.age(25)
           .onFailure(Assertions::fail)
           .onSuccess(age -> assertEquals(25, age.value()));
    }

    @Test
    void age_succeeds_forZero() {
        Age.age(0)
           .onFailure(Assertions::fail)
           .onSuccess(age -> assertEquals(0, age.value()));
    }

    @Test
    void age_succeeds_forMaximum() {
        Age.age(150)
           .onFailure(Assertions::fail)
           .onSuccess(age -> assertEquals(150, age.value()));
    }

    @Test
    void age_fails_forNegative() {
        Age.age(-1)
           .onSuccess(Assertions::fail);
    }

    @Test
    void age_fails_forTooOld() {
        Age.age(151)
           .onSuccess(Assertions::fail);
    }
}

class TransferFundsTest {

    // Success stubs
    private static final ValidateAccounts VALID_ACCOUNTS =
        (from, to) -> Promise.success(new ValidatedAccounts(
            new Account(from, Money.money(1000)),
            new Account(to, Money.money(500))
        ));

    private static final ExecuteTransfer TRANSFER_SUCCESS =
        (accounts, amount) -> Promise.success(new TransferId("TXN-001"));

    // Failure stubs
    private static final ValidateAccounts SOURCE_NOT_FOUND =
        (from, to) -> TransferError.SOURCE_NOT_FOUND.promise();

    private static final ValidateAccounts INSUFFICIENT_FUNDS =
        (from, to) -> TransferError.INSUFFICIENT_FUNDS.promise();

    @Test
    void transfer_succeeds_forValidAccounts() {
        var useCase = TransferFunds.transferFunds(VALID_ACCOUNTS, TRANSFER_SUCCESS);
        var request = new TransferRequest(
            new AccountId("ACC-001"),
            new AccountId("ACC-002"),
            Money.money(100)
        );

        useCase.execute(request)
               .await()
               .onFailure(Assertions::fail)
               .onSuccess(result ->
                   assertEquals("TXN-001", result.transferId().value()));
    }

    @Test
    void transfer_fails_whenSourceNotFound() {
        var useCase = TransferFunds.transferFunds(SOURCE_NOT_FOUND, TRANSFER_SUCCESS);
        var request = new TransferRequest(
            new AccountId("INVALID"),
            new AccountId("ACC-002"),
            Money.money(100)
        );

        useCase.execute(request)
               .await()
               .onSuccess(Assertions::fail);
    }
}

class SlowServiceTest {

    @Test
    void fetch_timesOut_whenServiceTooSlow() {
        // Stub that never resolves
        SlowService neverResolves = id -> {
            Promise<Data> promise = Promise.promise();
            // Never call promise.succeed() or promise.fail()
            return promise;
        };

        var withTimeout = SlowService.withTimeout(
            neverResolves,
            TimeSpan.timeSpan(100).millis()
        );

        withTimeout.fetch(new DataId("test"))
                   .await(TimeSpan.timeSpan(500).millis())
                   .onSuccess(Assertions::fail)
                   .onFailure(cause ->
                       assertTrue(cause instanceof TimeoutError));
    }

    @Test
    void fetch_succeeds_whenServiceFastEnough() {
        SlowService fast = id -> Promise.success(new Data("result"));

        var withTimeout = SlowService.withTimeout(
            fast,
            TimeSpan.timeSpan(1).seconds()
        );

        withTimeout.fetch(new DataId("test"))
                   .await()
                   .onFailure(Assertions::fail)
                   .onSuccess(data ->
                       assertEquals("result", data.value()));
    }
}

public interface CancelOrder {
    Promise<CancellationResult> execute(CancelRequest request);

    record CancelRequest(UserId userId, OrderId orderId) {}
    record CancellationResult(OrderId orderId, Option<RefundId> refundId) {}

    // Step interfaces
    interface FindOrder {
        Promise<Order> apply(OrderId orderId);
    }

    interface ValidateOwnership {
        Promise<Order> apply(Order order, UserId userId);
    }

    interface ValidateCancellable {
        Promise<Order> apply(Order order);
    }

    interface ProcessRefund {
        Promise<Option<RefundId>> apply(Order order);
    }

    interface UpdateOrderStatus {
        Promise<Unit> apply(OrderId orderId, OrderStatus status);
    }

    interface SendNotification {
        Promise<Unit> apply(UserId userId, OrderId orderId);
    }

    static CancelOrder create(FindOrder findOrder,
                              ValidateOwnership validateOwnership,
                              ValidateCancellable validateCancellable,
                              ProcessRefund processRefund,
                              UpdateOrderStatus updateStatus,
                              SendNotification sendNotification) {
        return request -> findOrder.apply(request.orderId())
            .flatMap(order -> validateOwnership.apply(order, request.userId()))
            .flatMap(validateCancellable::apply)
            .flatMap(order -> processRefund.apply(order)
                .flatMap(refundId -> updateStatus.apply(order.id(), OrderStatus.CANCELLED)
                    .map(unit -> new CancellationResult(order.id(), refundId))))
            .onSuccess(result -> sendNotification.apply(request.userId(), request.orderId())
                .onFailure(cause -> log.warn("Notification failed", cause)));
    }
}

public interface BookSeat {
    Promise<Booking> execute(BookingRequest request);

    interface ReserveSeat {
        Promise<ReservationId> apply(SeatId seatId);
    }

    interface ReleaseSeat {
        Promise<Unit> apply(ReservationId reservationId);
    }

    interface ChargePayment {
        Promise<PaymentId> apply(UserId userId, Money amount);
    }

    interface RefundPayment {
        Promise<Unit> apply(PaymentId paymentId);
    }

    interface SendConfirmation {
        Promise<Unit> apply(UserId userId, ReservationId reservationId);
    }

    static BookSeat create(ReserveSeat reserveSeat,
                           ReleaseSeat releaseSeat,
                           ChargePayment chargePayment,
                           RefundPayment refundPayment,
                           SendConfirmation sendConfirmation) {
        return request -> reserveSeat.apply(request.seatId())
            .flatMap(reservationId ->
                chargePayment.apply(request.userId(), request.amount())
                    .recover(cause -> compensateReservation(releaseSeat, reservationId, cause))
                    .flatMap(paymentId ->
                        sendConfirmation.apply(request.userId(), reservationId)
                            .recover(cause -> compensatePayment(
                                releaseSeat, refundPayment,
                                reservationId, paymentId, cause))
                            .map(unit -> new Booking(reservationId, paymentId))));
    }

    private static Promise<PaymentId> compensateReservation(ReleaseSeat releaseSeat,
                                                             ReservationId reservationId,
                                                             Cause originalCause) {
        return releaseSeat.apply(reservationId)
            .flatMap(unit -> originalCause.promise());
    }

    private static Promise<Unit> compensatePayment(ReleaseSeat releaseSeat,
                                                    RefundPayment refundPayment,
                                                    ReservationId reservationId,
                                                    PaymentId paymentId,
                                                    Cause originalCause) {
        return Promise.all(releaseSeat.apply(reservationId),
                          refundPayment.apply(paymentId))
                      .flatMap((u1, u2) -> originalCause.promise());
    }
}

src/main/java/com/example/user/
├── domain/
│   ├── Email.java              # Value object
│   ├── Password.java           # Value object
│   ├── Username.java           # Value object
│   └── RegistrationError.java  # Domain errors
├── usecase/
│   └── RegisterUser.java       # Use case with:
│                               #   - Request record
│                               #   - ValidRegistration record
│                               #   - Response record
│                               #   - Step interfaces (SaveUser, CheckEmailUnique, etc.)
│                               #   - Factory method
├── adapter/
│   ├── persistence/
│   │   └── JpaUserRepository.java  # Implements step interface
│   └── web/
│       ├── UserController.java     # REST controller
│       └── UserDto.java            # API DTO
└── config/
    └── UserConfiguration.java      # Spring wiring

Notes:

• RegisterUserImpl is not needed - factory method in interface creates implementation
• ValidRegistration is nested in RegisterUser as ValidRequest record
• UserRepository doesn’t exist separately - it’s a step interface inside use case

Violations found:

1. Primitive obsession - Using raw String for email and password instead of value objects
2. Validation in wrong place - Controller or service validating instead of value object factory
3. Exceptions for business errors - EmailExistsException should be a Cause in Result
4. Mutable entity - Using setters instead of immutable record
5. Field injection - Using @Autowired instead of constructor injection
6. Missing use case interface - Business logic directly in service

Refactored:

public interface CreateUser {
    Promise<UserId> execute(CreateUserRequest request);

    record CreateUserRequest(String email, String password) {}
    record ValidRequest(Email email, Password password) {}

    interface CheckEmailUnique {
        Promise<Email> apply(Email email);
    }

    interface SaveUser {
        Promise<UserId> apply(ValidRequest request);
    }

    static CreateUser create(CheckEmailUnique checkEmail, SaveUser saveUser) {
        return request -> ValidRequest.validRequest(request)
            .async()
            .flatMap(valid -> checkEmail.apply(valid.email())
                .map(email -> valid))
            .flatMap(saveUser::apply);
    }
}

Phase 1: Value Objects (Week 1)

• Create: OrderId, ProductId, Quantity, Money, CustomerId
• Parallel method: placeOrderValidated(ValidOrderRequest request)
• Keep original method, call validated version internally

Phase 2: Result in New Code (Week 2)

• Extract validation to ValidOrderRequest.validRequest(OrderDto)
• Return Result<Order> instead of throwing
• Create OrderError sealed interface

Phase 3: Extract Use Case (Week 3-4)

• Create PlaceOrder interface with step interfaces:
  • CheckInventory
  • ProcessPayment
  • CreateOrder
  • SendNotification
• Move business logic to factory method
• Service becomes thin wrapper calling use case

Phase 4: Adapter Isolation (Week 5)

• Wrap inventory check in Promise.lift()
• Wrap payment gateway in Promise.lift()
• Wrap repository in Promise.lift()
• Email service as fire-and-forget Promise

Migration commits:

1. Add value objects
2. Add ValidOrderRequest
3. Add OrderError types
4. Extract PlaceOrder interface
5. Implement step interfaces as adapters
6. Convert service to use case wrapper
7. Remove legacy method

public Promise<Report> generateReport(ReportRequest request) {
    return validateRequest(request)
        .onSuccess(r -> log.debug("Validated: {}", r))
        .onFailure(c -> log.error("Validation failed: {}", c.message()))
        .flatMap(this::fetchData)
        .onSuccess(d -> log.debug("Fetched {} records", d.size()))
        .onFailure(c -> log.error("Fetch failed: {}", c.message()))
        .flatMap(this::transformData)
        .onSuccess(t -> log.debug("Transformed to {} items", t.size()))
        .onFailure(c -> log.error("Transform failed: {}", c.message()))
        .flatMap(this::formatReport)
        .onSuccess(r -> log.debug("Report generated: {} pages", r.pageCount()))
        .onFailure(c -> log.error("Format failed: {}", c.message()));
}

Alternative: Extract to named methods for breakpoints:

public Promise<Report> generateReport(ReportRequest request) {
    return validateRequestStep(request)
        .flatMap(this::fetchDataStep)
        .flatMap(this::transformDataStep)
        .flatMap(this::formatReportStep);
}

private Promise<ValidRequest> validateRequestStep(ReportRequest request) {
    log.debug("Validating request");
    return validateRequest(request);  // Breakpoint here
}

// ... similar for other steps