Intermediate

import java.math.BigDecimal;                      // => BigDecimal: precise monetary arithmetic
// => executes the statement above; continues to next line
import java.time.Instant;                         // => Instant: UTC timestamp for domain events
// => executes the statement above; continues to next line
import java.util.List;                            // => List: collection for event returns
// => executes the statement above; continues to next line
import java.util.Optional;                        // => Optional: no-null contract for queries
 
// ── Supporting types ──────────────────────────────────────────────────────────
record OrderId(String value) {}                   // => OrderId: typed wrapper; not raw String
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
record CustomerId(String value) {}                // => CustomerId: separate type from OrderId
// => record CustomerId: immutable value type; equals/hashCode/toString generated by compiler
enum OrderStatus { PENDING, CONFIRMED, SHIPPED }  // => domain lifecycle states
 
// Domain aggregate: rich object with behaviour — returned by command port
// => Order is the source of truth for the command side
record Order(OrderId id, CustomerId customerId, BigDecimal total, OrderStatus status) {} // => four components
 
// Domain event: emitted when order is placed — command side output
// => OrderPlaced signals that state has changed; downstream can react
record OrderPlaced(OrderId orderId, BigDecimal total, Instant placedAt) {} // => three event fields
 
// Unvalidated input: raw data arriving from the HTTP adapter
// => raw Strings and List; domain validation converts these to typed values
record UnvalidatedOrder(String customerId, List<String> productIds, BigDecimal total) {}
 
// Read model DTO: flat, denormalised view for the query side
// => OrderView is NOT Order; it has no behaviour, only query-optimised fields
// => String status instead of enum because view crosses JSON boundary easily
record OrderView(String orderId, String customerName, String status, BigDecimal total) {}
 
// ── COMMAND port: state-changing ──────────────────────────────────────────────
// Input port interface lives in application zone; web adapter calls this
// => Returns List<OrderPlaced> on success; callers react to emitted events
// => Result type or Either signals failure without exceptions crossing the boundary
interface PlaceOrderUseCase {                     // => command port: write side only
// => interface PlaceOrderUseCase: contract definition — no implementation details here
    List<OrderPlaced> placeOrder(UnvalidatedOrder order); // => throws on failure (simplified)
    // => In production use Either<PlacingOrderError, List<OrderPlaced>> for explicit errors
}
 
// ── QUERY port: read-only ─────────────────────────────────────────────────────
// Query port is a separate interface; it never touches domain aggregate Order
// => Returns Optional because the order might not exist
// => Returns OrderView (flat DTO), not Order (rich aggregate)
interface GetOrderUseCase {                       // => query port: read-only side; separate from command
// => interface GetOrderUseCase: contract definition — no implementation details here
    Optional<OrderView> getOrder(OrderId id); // => read-only; no state change; no aggregate loaded
    // => Query side may bypass domain and go direct to read-optimised projection
}
 
// ── Command implementation: delegates to domain then repository ────────────────
class PlaceOrderService implements PlaceOrderUseCase { // => implements command port only; not query port
// => PlaceOrderService implements PlaceOrderUseCase — satisfies the port contract
    @Override                                     // => compiler verifies placeOrder signature matches interface
    // => @Override: compiler verifies this method signature matches the interface
    public List<OrderPlaced> placeOrder(UnvalidatedOrder raw) { // => raw input; service validates inside
    // => executes the statement above; continues to next line
        var event = new OrderPlaced(              // => construct domain event
        // => event: holds the result of the expression on the right
            new OrderId(java.util.UUID.randomUUID().toString()), // => new UUID as order id
            // => method call: delegates to collaborator; result captured above
            raw.total(),                          // => carry total from input
            // => method call: delegates to collaborator; result captured above
            Instant.now()                         // => timestamp at placement
            // => method call: delegates to collaborator; result captured above
        );
        return List.of(event);                    // => return event list; caller publishes
        // => Application service does not know about HTTP, JSON, or DB
    }
}
 
// ── Query implementation: returns flat view; bypasses domain aggregate ─────────
class OrderQueryService implements GetOrderUseCase { // => implements query port; bypasses domain aggregate
// => OrderQueryService implements GetOrderUseCase — satisfies the port contract
    @Override                                     // => compiler verifies getOrder signature matches interface
    // => @Override: compiler verifies this method signature matches the interface
    public Optional<OrderView> getOrder(OrderId id) { // => id: typed; no raw String parameter
        // => In production: query read-model table or projection store
        // => Not the same table as the command-side Order aggregate
        return Optional.of(new OrderView(          // => return flat DTO wrapped in Optional
        // => returns the result to the caller — caller receives this value
            id.value(), "Alice Smith",             // => denormalised customer name
            // => method call: delegates to collaborator; result captured above
            "CONFIRMED", new BigDecimal("99.00")   // => flat string status for view
            // => method call: delegates to collaborator; result captured above
        ));
    }                                             // => Optional.of: always present here; production may return empty
    // => executes the statement above; continues to next line
}

import java.math.BigDecimal                                          // => BigDecimal for totals
// => executes the statement above; continues to next line
import java.time.Instant                                             // => Instant for timestamps
// => executes the statement above; continues to next line
import java.util.UUID                                                // => UUID for id generation
 
// ── Supporting types ──────────────────────────────────────────────────────────
data class OrderId(val value: String)              // => typed identity
// => data class OrderId: value type; copy/equals/hashCode/toString auto-generated
data class CustomerId(val value: String)           // => separate from OrderId; no mix-up
// => data class CustomerId: value type; copy/equals/hashCode/toString auto-generated
enum class OrderStatus { PENDING, CONFIRMED, SHIPPED } // => domain lifecycle
// => enum class: closed set of domain values; exhaustive switch/when enforced
 
data class UnvalidatedOrder(val customerId: String, val total: BigDecimal) // => raw input
// => data class UnvalidatedOrder: value type; copy/equals/hashCode/toString auto-generated
data class OrderPlaced(val orderId: OrderId, val total: BigDecimal, val placedAt: Instant) // => event
 
// Read model: flat and denormalised; returned by query side only
// => data class with no domain behaviour; just data for presentation
data class OrderView(val orderId: String, val customerName: String, val status: String, val total: BigDecimal)
// => flat DTO; no domain aggregate loaded; query-optimised
 
// ── Command port: state-mutating ──────────────────────────────────────────────
// fun interface: Kotlin SAM — allows lambda implementation
// => Returns List<OrderPlaced>; signals what happened during the command
fun interface PlaceOrderUseCase {
// => interface PlaceOrderUseCase: contract definition — no implementation details here
    fun placeOrder(order: UnvalidatedOrder): List<OrderPlaced>
    // => Command side; caller must store or publish each OrderPlaced event
}
 
// ── Query port: read-only ─────────────────────────────────────────────────────
// Separate interface; query never calls PlaceOrderUseCase and vice versa
// => Returns OrderView? (nullable) instead of domain Order
fun interface GetOrderUseCase {
// => interface GetOrderUseCase: contract definition — no implementation details here
    fun getOrder(id: OrderId): OrderView? // => null when not found; no exception
    // => Query side optimised for reads; different DB table or projection allowed
}
 
// ── Implementations ───────────────────────────────────────────────────────────
val placeOrder = PlaceOrderUseCase { raw ->
    // => lambda implements SAM; no class needed
    listOf(OrderPlaced(OrderId(UUID.randomUUID().toString()), raw.total, Instant.now()))
    // => Emits event; caller publishes to event bus or stores in outbox
    // => UUID.randomUUID(): fresh id for every order placement
}
 
val getOrder = GetOrderUseCase { id ->
    // => lambda implements SAM; query-side adapter would query read-model table
    OrderView(id.value, "Alice Smith", "CONFIRMED", BigDecimal("99.00"))
    // => Returns flat view; no rich aggregate; query-optimised response
    // => denormalised customer name; avoids join to customers table
}

using System;                                                         // => System namespace
// => executes the statement above; continues to next line
using System.Collections.Generic;                                     // => IReadOnlyList
 
// ── Supporting types ──────────────────────────────────────────────────────────
public record OrderId(string Value);               // => typed identity
// => executes the statement above; continues to next line
public record UnvalidatedOrder(string CustomerId, decimal Total); // => raw input DTO
// => executes the statement above; continues to next line
public record OrderPlaced(OrderId OrderId, decimal Total, DateTimeOffset PlacedAt); // => domain event
 
// Read model: flat DTO returned by query side; not the domain aggregate
// => record with no methods; purely data for the presentation layer
public record OrderView(string OrderId, string CustomerName, string Status, decimal Total);
// => flat read model; no domain methods; purely query-side data
// => CustomerName: denormalised; avoids join; Status: string not enum for JSON simplicity
 
// ── Command port ───────────────────────────────────────────────────────────────
// Interface in Application layer; no ASP.NET, no EF Core on this interface
// => IPlaceOrderUseCase: command side; returns events produced
public interface IPlaceOrderUseCase  // => application zone; no HTTP or EF types
// => executes the statement above; continues to next line
{
    IReadOnlyList<OrderPlaced> PlaceOrder(UnvalidatedOrder order);
    // => Callers iterate events; publish or persist each one
    // => IReadOnlyList: caller can enumerate but not mutate the events
    // => UnvalidatedOrder: raw input from HTTP adapter; validated inside implementation
}
 
// ── Query port ────────────────────────────────────────────────────────────────
// Separate interface; no coupling to command side whatsoever
// => Returns OrderView, not domain Order; nullable for not-found case
public interface IGetOrderUseCase  // => separate from command port; no shared coupling
// => executes the statement above; continues to next line
{
    OrderView? GetOrder(OrderId id); // => null = not found; no exception
    // => Query side may go directly to a read-model database view
}
 
// ── Implementations ───────────────────────────────────────────────────────────
public class PlaceOrderService : IPlaceOrderUseCase  // => command-side implementation
// => executes the statement above; continues to next line
{                                                                     // => command-side service; no EF Core
// => executes the statement above; continues to next line
    public IReadOnlyList<OrderPlaced> PlaceOrder(UnvalidatedOrder order)
    // => executes the statement above; continues to next line
    {                                                                 // => returns events; no void
    // => executes the statement above; continues to next line
        var evt = new OrderPlaced(                 // => construct event
        // => evt: holds the result of the expression on the right
            new OrderId(Guid.NewGuid().ToString()), // => fresh id for the new order
            // => method call: delegates to collaborator; result captured above
            order.Total,                           // => carry total from command input
            // => executes the statement above; continues to next line
            DateTimeOffset.UtcNow                  // => UTC timestamp of placement
            // => executes the statement above; continues to next line
        );
        return new[] { evt };                      // => return event array; caller publishes
        // => array literal wrapped as IReadOnlyList; immutable view for callers
    }
}
 
public class OrderQueryService : IGetOrderUseCase  // => query-side implementation
// => executes the statement above; continues to next line
{                                                                     // => query-side service; no domain aggregate
// => executes the statement above; continues to next line
    public OrderView? GetOrder(OrderId id) =>      // => expression-body method
    // => executes the statement above; continues to next line
        new OrderView(id.Value, "Alice Smith", "Confirmed", 99m);
        // => In production: query read-model table, not aggregate table
        // => denormalised customer name avoids join to customers table
}

import java.math.BigDecimal;
// => executes the statement above; continues to next line
import java.util.Optional;
 
// ── Supporting types ──────────────────────────────────────────────────────────
record OrderId(String value) {}                    // => typed wrapper over String
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
enum OrderStatus { PENDING, CONFIRMED, SHIPPED }   // => domain enum; no framework import
// => enum OrderStatus: closed set of domain values; exhaustive switch/when enforced
record Money(BigDecimal amount, String currency) {} // => value object; carries currency
// => record Money: immutable value type; equals/hashCode/toString generated by compiler
record Order(OrderId id, Money total, OrderStatus status) {} // => rich domain aggregate
// => Order has domain behaviour (validate, confirm, ship) not shown here for brevity
 
// Flat read model: denormalised; optimised for display, not domain logic
// => No domain behaviour; purely data carried to the presentation layer
record OrderView(String orderId, String status, BigDecimal total, String currencyCode) {}
 
// ── Command-side output port: returns domain aggregate ────────────────────────
// Repository lives in application zone; JPA adapter lives in adapter zone
// => findById returns Optional<Order>; not found = Optional.empty()
interface OrderRepository {
// => interface OrderRepository: contract definition — no implementation details here
    Optional<Order> findById(OrderId id); // => loads rich aggregate; command side
    // => executes the statement above; continues to next line
    void save(Order order);               // => persists aggregate; command side only
    // => Never used by query side; query side has its own port
}
 
// ── Query-side output port: returns flat read model ───────────────────────────
// Separate interface; may query a view/projection table in the DB
// => No save(), no delete() — read-only by design
interface OrderQueryPort {
// => interface OrderQueryPort: contract definition — no implementation details here
    Optional<OrderView> findOrderView(OrderId id); // => returns DTO; not domain aggregate
    // => Implementation may use a DB view, materialized view, or separate read DB
}
 
// ── Command-side adapter: JPA against main table ──────────────────────────────
class JpaOrderRepository implements OrderRepository {
    // => In production: @Repository, EntityManager, @Transactional here
    // => This class lives in adapter/out/persistence package
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public Optional<Order> findById(OrderId id) {
        // => JPA query: SELECT * FROM orders WHERE id = ?
        return Optional.of(new Order(id, new Money(new BigDecimal("100"), "USD"), OrderStatus.CONFIRMED));
        // => Maps JPA entity (OrderJpaEntity) to domain Order in this adapter
    }
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public void save(Order order) { /* JPA persist */ } // => persist domain to DB
    // => save: method entry point — see implementation below
}
 
// ── Query-side adapter: queries DB view / projection table ────────────────────
class PostgresOrderViewAdapter implements OrderQueryPort {
    // => In production: JdbcTemplate or plain SQL against a read-optimised view
    // => SELECT order_id, status, total, currency FROM order_summary_view WHERE id = ?
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public Optional<OrderView> findOrderView(OrderId id) {
    // => executes the statement above; continues to next line
        return Optional.of(new OrderView(id.value(), "CONFIRMED", new BigDecimal("100"), "USD"));
        // => Returns flat DTO directly from projection; no domain object created
    }
}

import java.math.BigDecimal                                          // => BigDecimal for amounts
// => executes the statement above; continues to next line
 
data class OrderId(val value: String)              // => typed id
// => data class OrderId: value type; copy/equals/hashCode/toString auto-generated
enum class OrderStatus { PENDING, CONFIRMED }       // => domain enum; no String comparison
// => enum class: closed set of domain values; exhaustive switch/when enforced
data class Money(val amount: BigDecimal, val currency: String) // => value object
// => data class Money: value type; copy/equals/hashCode/toString auto-generated
data class Order(val id: OrderId, val total: Money, val status: OrderStatus) // => aggregate
// => data class Order: value type; copy/equals/hashCode/toString auto-generated
data class OrderView(val orderId: String, val status: String, val total: BigDecimal) // => read model
// => OrderView: flat; no Money value object; query-optimised
 
// ── Command-side output port ──────────────────────────────────────────────────
// Application zone interface; adapter zone provides implementation
// => Returns domain Order; used by PlaceOrderService and other command handlers
interface OrderRepository {
// => interface OrderRepository: contract definition — no implementation details here
    fun findById(id: OrderId): Order?  // => null = not found; command side
    // => executes the statement above; continues to next line
    fun save(order: Order)             // => persist aggregate after domain logic
    // => Never used by query service; query service has its own port
}
 
// ── Query-side output port ────────────────────────────────────────────────────
// Completely separate interface; no overlap with OrderRepository
// => Query service injects this; command service never touches it
interface OrderQueryPort {
// => interface OrderQueryPort: contract definition — no implementation details here
    fun findOrderView(id: OrderId): OrderView? // => flat DTO; null if not found
    // => May query a different schema or a materialized view for performance
}
 
// ── Adapters ──────────────────────────────────────────────────────────────────
class ExposedOrderRepository : OrderRepository {
    // => Uses Kotlin Exposed ORM against orders table; lives in adapter/out/persistence
    override fun findById(id: OrderId): Order? =         // => returns domain Order; maps from JPA entity
    // => executes the statement above; continues to next line
        Order(id, Money(BigDecimal("100"), "USD"), OrderStatus.CONFIRMED)
        // => In production: transaction { Orders.select { Orders.id eq id.value }.singleOrNull()?.toOrder() }
    override fun save(order: Order) { /* Exposed INSERT/UPDATE */ } // => persists domain Order
    // => save: method entry point — see implementation below
}
 
class PostgresOrderViewAdapter : OrderQueryPort {
    // => Uses plain JDBC or Exposed against order_summary_view; adapter/out/persistence
    override fun findOrderView(id: OrderId): OrderView? = // => returns flat DTO; no aggregate loaded
    // => executes the statement above; continues to next line
        OrderView(id.value, "CONFIRMED", BigDecimal("100"))
        // => In production: jdbcTemplate.queryForObject("SELECT ... FROM order_summary_view WHERE id = ?", ...)
        // => Returns flat DTO; no Order aggregate loaded
}

using System;                                                         // => System namespace
// => executes the statement above; continues to next line
using System.Threading.Tasks;                                         // => Task for async (if needed)
// => method call: delegates to collaborator; result captured above
 
public record OrderId(string Value);               // => typed identity wrapper
// => executes the statement above; continues to next line
public enum OrderStatus { Pending, Confirmed }     // => domain lifecycle enum
// => enum OrderStatus: closed set of domain values; exhaustive switch/when enforced
public record Money(decimal Amount, string Currency); // => value object; carries currency
// => executes the statement above; continues to next line
public record Order(OrderId Id, Money Total, OrderStatus Status); // => rich aggregate
// => domain aggregate; no EF annotation; no [Table], no [Key]
public record OrderView(string OrderId, string Status, decimal Total); // => flat read model
// => no domain aggregate; purely query-side; Status is string not enum for JSON simplicity
 
// ── Command-side output port ──────────────────────────────────────────────────
// IOrderRepository: application zone interface; EF Core adapter in adapter zone
// => Returns domain Order; Save() persists after domain logic
public interface IOrderRepository
// => executes the statement above; continues to next line
{
    Order? FindById(OrderId id);   // => returns aggregate; null = not found
    // => executes the statement above; continues to next line
    void Save(Order order);        // => command side only; query port has no Save
    // => executes the statement above; continues to next line
}
 
// ── Query-side output port ────────────────────────────────────────────────────
// IOrderQueryPort: separate interface; returns flat DTO not aggregate
// => Query service injects this; never used by command-side services
public interface IOrderQueryPort
// => executes the statement above; continues to next line
{
    OrderView? FindOrderView(OrderId id); // => flat read model; null if missing
    // => May point at a different database, read replica, or EF view
}
 
// ── Adapters ──────────────────────────────────────────────────────────────────
public class EfOrderRepository : IOrderRepository  // => command-side adapter; EF Core
// => executes the statement above; continues to next line
{                                                                     // => adapter zone; imports DbContext
    // => In production: inject DbContext; map EF entity to/from domain Order
    public Order? FindById(OrderId id) =>          // => returns domain aggregate; null if not found
    // => executes the statement above; continues to next line
        new Order(id, new Money(100m, "USD"), OrderStatus.Confirmed);
        // => Adapter translates EF entity to domain record here; domain stays clean
        // => simulated; production: _context.Orders.Find(id.Value)?.ToDomain()
 
    public void Save(Order order) { /* EF Core SaveChanges() */ }     // => persist aggregate
    // => Save: method entry point — see implementation below
}
 
public class SqlOrderViewAdapter : IOrderQueryPort  // => query-side adapter; Dapper or ADO.NET
// => executes the statement above; continues to next line
{                                                                     // => adapter zone; imports Dapper or ADO.NET
    // => In production: Dapper against a read-model view or separate read DB
    public OrderView? FindOrderView(OrderId id) =>  // => returns flat DTO; null if not found
    // => executes the statement above; continues to next line
        new OrderView(id.Value, "Confirmed", 100m);
        // => Raw SQL query returns flat DTO; no EF model graph loaded
        // => simulated; production: connection.QuerySingleOrDefault<OrderView>(sql, ...)
}

import java.math.BigDecimal;
// => executes the statement above; continues to next line
import java.util.Optional;
// => executes the statement above; continues to next line
import java.util.concurrent.CompletableFuture;
 
// ── Supporting types ──────────────────────────────────────────────────────────
record OrderId(String value) {}                    // => typed identity
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
record Money(BigDecimal amount, String currency) {} // => value object
// => record Money: immutable value type; equals/hashCode/toString generated by compiler
record Order(OrderId id, Money total) {}            // => domain aggregate (minimal)
 
// ── Async output port ─────────────────────────────────────────────────────────
// CompletableFuture as return type: signals non-blocking I/O to callers
// => Application service must chain or join; cannot ignore the future
interface OrderRepository {
// => interface OrderRepository: contract definition — no implementation details here
    CompletableFuture<Optional<Order>> findById(OrderId id);
    // => Non-blocking: adapter submits DB query to thread pool; returns immediately
    // => join() in service turns it back to blocking; .thenApply() keeps it async
}
 
// ── Production adapter: wraps real async DB call ──────────────────────────────
class AsyncJpaOrderRepository implements OrderRepository {
// => AsyncJpaOrderRepository implements OrderRepository — satisfies the port contract
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public CompletableFuture<Optional<Order>> findById(OrderId id) {
    // => executes the statement above; continues to next line
        return CompletableFuture.supplyAsync(() -> {    // => new thread from common pool
            // => In production: R2DBC or async JDBC query here
            var order = new Order(id, new Money(new BigDecimal("99"), "USD")); // => simulate DB row
            // => order: holds the result of the expression on the right
            return Optional.of(order);                 // => wrap in Optional for not-found signalling
            // => returns the result to the caller — caller receives this value
        });
        // => operation completes; execution continues to next statement
    }
    // => operation completes; execution continues to next statement
}
 
// ── In-memory test adapter: wraps sync value in CompletableFuture ─────────────
class InMemoryOrderRepository implements OrderRepository {
// => InMemoryOrderRepository implements OrderRepository — satisfies the port contract
    private final java.util.Map<String, Order> store = new java.util.HashMap<>(); // => in-memory store
    // => Backed by HashMap; no DB needed; runs in microseconds
 
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public CompletableFuture<Optional<Order>> findById(OrderId id) {
    // => executes the statement above; continues to next line
        var order = Optional.ofNullable(store.get(id.value())); // => sync lookup
        // => order: holds the result of the expression on the right
        return CompletableFuture.completedFuture(order);        // => wrap in already-completed future
        // => completedFuture: no thread pool; resolves immediately for tests
    }
}
 
// ── Application service: joins the future ────────────────────────────────────
class FindOrderService {
// => class FindOrderService: implementation — contains field declarations and methods below
    private final OrderRepository repository;                  // => injected; no new here
    // => repository: OrderRepository — final field; assigned once in constructor; immutable reference
    FindOrderService(OrderRepository repository) { this.repository = repository; }
    // => method call: delegates to collaborator; result captured above
 
    Optional<Order> find(OrderId id) {
    // => executes the statement above; continues to next line
        return repository.findById(id).join(); // => join() blocks until future completes
        // => In reactive code: chain with .thenApply() instead of join()
        // => In tests: InMemoryOrderRepository resolves immediately; join() is instant
    }
}

import java.math.BigDecimal                                          // => BigDecimal for amounts
// => executes the statement above; continues to next line
import kotlinx.coroutines.runBlocking                               // => run coroutine in blocking context
// => executes the statement above; continues to next line
import kotlinx.coroutines.CompletableDeferred                       // => completable async value
// => executes the statement above; continues to next line
 
data class OrderId(val value: String)              // => typed identity
// => data class OrderId: value type; copy/equals/hashCode/toString auto-generated
data class Money(val amount: BigDecimal, val currency: String) // => value object
// => data class Money: value type; copy/equals/hashCode/toString auto-generated
data class Order(val id: OrderId, val total: Money) // => domain aggregate
 
// ── Async port with suspend ───────────────────────────────────────────────────
// suspend: Kotlin coroutine-native; compiles to state machine; no thread blocking
// => Callers must be in a coroutine scope or use runBlocking for tests
interface OrderRepository {
// => interface OrderRepository: contract definition — no implementation details here
    suspend fun findById(id: OrderId): Order? // => null = not found; suspend = non-blocking
    // => Ktor, coroutines dispatcher, or test runBlocking supplies the coroutine context
}
 
// ── In-memory test adapter ────────────────────────────────────────────────────
class InMemoryOrderRepository : OrderRepository {
// => class InMemoryOrderRepository: implementation — contains field declarations and methods below
    private val store = mutableMapOf<String, Order>() // => in-memory backing store
    // => store: val — injected dependency; implementation chosen at wiring time
 
    override suspend fun findById(id: OrderId): Order? = store[id.value]
    // => suspend body here is synchronous; coroutine runtime wraps it transparently
    // => Tests call via runBlocking { repo.findById(...) }
 
    fun save(order: Order) { store[order.id.value] = order } // => helper for test setup
    // => save: method entry point — see implementation below
}
 
// ── Application service ───────────────────────────────────────────────────────
class FindOrderService(private val repository: OrderRepository) { // => injected
// => class FindOrderService: implementation — contains field declarations and methods below
    suspend fun find(id: OrderId): Order? = repository.findById(id)
    // => suspend propagates up; callers must be in coroutine scope
    // => Business logic here; no coroutine machinery visible to domain
}
 
// ── Test usage ────────────────────────────────────────────────────────────────
val repo = InMemoryOrderRepository()                           // => create test adapter
// => repo: holds the result of the expression on the right
repo.save(Order(OrderId("O1"), Money(BigDecimal("50"), "USD"))) // => populate store
// => in-memory save for test setup; not via port interface
 
val service = FindOrderService(repo)                           // => inject test adapter
// => service: holds the result of the expression on the right
val result = runBlocking { service.find(OrderId("O1")) }       // => run coroutine in test
// => result is Order(OrderId("O1"), Money(50, "USD")); not null

using System.Collections.Generic;                                     // => Dictionary
// => executes the statement above; continues to next line
using System.Threading.Tasks;                                         // => Task, Task<T>
// => executes the statement above; continues to next line
 
public record OrderId(string Value);               // => typed identity
// => executes the statement above; continues to next line
public record Money(decimal Amount, string Currency); // => value object; carries currency
// => executes the statement above; continues to next line
public record Order(OrderId Id, Money Total);      // => domain aggregate
 
// ── Async port with Task ──────────────────────────────────────────────────────
// Task<Order?> return type: standard .NET async pattern
// => Callers must await; compiler enforces via CS4014 warning if forgotten
public interface IOrderRepository  // => application zone; no EF Core, no Task library import
// => executes the statement above; continues to next line
{                                                                     // => application zone interface
// => interface type: contract definition — no implementation details here
    Task<Order?> FindByIdAsync(OrderId id); // => Async suffix: .NET naming convention
    // => method call: delegates to collaborator; result captured above
    Task SaveAsync(Order order);            // => all I/O methods are async
    // => Interface in Application layer; EF Core adapter in Adapter layer
}
 
// ── In-memory test adapter ────────────────────────────────────────────────────
public class InMemoryOrderRepository : IOrderRepository  // => test adapter; synchronous impl
// => executes the statement above; continues to next line
{                                                                     // => no EF Core; runs in milliseconds
// => executes the statement above; continues to next line
    private readonly Dictionary<string, Order> _store = new(); // => backing store
    // => executes the statement above; continues to next line
 
    public Task<Order?> FindByIdAsync(OrderId id)              // => implement async port
    // => executes the statement above; continues to next line
    {                                                           // => synchronous body; wrapped in completed Task
    // => executes the statement above; continues to next line
        _store.TryGetValue(id.Value, out var order);            // => sync dictionary lookup
        // => method call: delegates to collaborator; result captured above
        return Task.FromResult(order);                          // => wrap in completed Task
        // => Task.FromResult: no thread pool; resolves immediately; perfect for tests
    }
 
    public Task SaveAsync(Order order)
    // => executes the statement above; continues to next line
    {                                                           // => synchronous body; Task.CompletedTask
    // => executes the statement above; continues to next line
        _store[order.Id.Value] = order;                         // => sync store; upsert
        // => executes the statement above; continues to next line
        return Task.CompletedTask;                              // => completed Task with no value
        // => returns the result to the caller — caller receives this value
    }
}
 
// ── Application service ───────────────────────────────────────────────────────
public class FindOrderService(IOrderRepository repository)     // => primary constructor; C# 12
// => constructor: receives all dependencies — enables testing with any adapter implementation
{                                                              // => repository injected; no EF Core import
// => executes the statement above; continues to next line
    public async Task<Order?> FindAsync(OrderId id) =>
    // => executes the statement above; continues to next line
        await repository.FindByIdAsync(id);                    // => await propagates to caller
        // => async/await: state machine generated by compiler; no callback pyramid
}
 
// ── Test usage ────────────────────────────────────────────────────────────────
var repo = new InMemoryOrderRepository();                      // => test adapter; no EF Core
// => repo: holds the result of the expression on the right
await repo.SaveAsync(new Order(new OrderId("O1"), new Money(50m, "USD"))); // => populate store
// => await completes immediately; Task.CompletedTask from in-memory adapter
var service = new FindOrderService(repo);                      // => inject test adapter
// => service: holds the result of the expression on the right
var result = await service.FindAsync(new OrderId("O1"));       // => result is the Order
// => await completes immediately; Task.FromResult from in-memory adapter
// => result is not null; Id.Value == "O1"

import java.math.BigDecimal;
// => executes the statement above; continues to next line
import java.util.List;
// In production: import io.vavr.control.Either;
// => Vavr Either<L, R>: L = failure (left), R = success (right)
// => For this self-contained example we define a minimal Either
 
// ── Minimal Either for self-contained example ─────────────────────────────────
sealed interface Either<L, R> permits Either.Left, Either.Right {  // => sealed: exhaustive pattern match
// => interface Either: contract definition — no implementation details here
    record Left<L, R>(L value) implements Either<L, R> {}          // => Left wraps failure
    // => Left implements Either<L, R> — satisfies the port contract
    record Right<L, R>(R value) implements Either<L, R> {}         // => Right wraps success
    // => Right implements Either<L, R> — satisfies the port contract
    static <L, R> Either<L, R> left(L l)  { return new Left<>(l); }  // => factory
    // => executes the statement above; continues to next line
    static <L, R> Either<L, R> right(R r) { return new Right<>(r); } // => factory
    // => executes the statement above; continues to next line
}
 
// ── Domain types ──────────────────────────────────────────────────────────────
record OrderId(String value) {}                         // => typed identity
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
record OrderPlaced(OrderId orderId, BigDecimal total) {} // => domain event
 
// Error hierarchy: sealed so compiler enforces exhaustive handling
// => Each subtype signals a different kind of failure to callers
sealed interface PlacingOrderError permits
// => executes the statement above; continues to next line
    PlacingOrderError.ValidationError,
    // => executes the statement above; continues to next line
    PlacingOrderError.RepositoryFailure {
    // => executes the statement above; continues to next line
    record ValidationError(String message) implements PlacingOrderError {}    // => bad input
    // => ValidationError implements PlacingOrderError — satisfies the port contract
    record RepositoryFailure(String cause) implements PlacingOrderError {}    // => DB error
    // => RepositoryFailure implements PlacingOrderError — satisfies the port contract
}
 
// ── Port interface using Either ───────────────────────────────────────────────
// Either<PlacingOrderError, List<OrderPlaced>>: left = failure, right = success
// => Callers must switch on Either to access value; no silent swallowing
interface PlaceOrderUseCase {
// => interface PlaceOrderUseCase: contract definition — no implementation details here
    Either<PlacingOrderError, List<OrderPlaced>> placeOrder(String customerId, BigDecimal total);
    // => No unchecked exceptions cross this boundary; failures are typed values
}
 
// ── Application service ───────────────────────────────────────────────────────
class PlaceOrderService implements PlaceOrderUseCase {
// => PlaceOrderService implements PlaceOrderUseCase — satisfies the port contract
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public Either<PlacingOrderError, List<OrderPlaced>> placeOrder(String customerId, BigDecimal total) {
    // => executes the statement above; continues to next line
        if (total.compareTo(BigDecimal.ZERO) <= 0) {              // => validate input
        // => conditional branch: execution path depends on condition above
            return Either.left(new PlacingOrderError.ValidationError("Total must be positive"));
            // => Returns Left; caller gets typed error; no exception thrown
        }
        var event = new OrderPlaced(new OrderId(java.util.UUID.randomUUID().toString()), total);
        // => event: holds the result of the expression on the right
        return Either.right(List.of(event));                      // => Returns Right on success
        // => Right carries the list of domain events produced by this command
    }
}
 
// ── Caller: HTTP adapter pattern-matches Either ───────────────────────────────
var service = new PlaceOrderService();                            // => in production: inject
// => service: holds the result of the expression on the right
var result  = service.placeOrder("CUST-1", new BigDecimal("50")); // => call the port
 
// Pattern match (Java 21 switch expression) — exhaustive: compiler enforces both branches
String httpBody = switch (result) {                               // => switch on Either
// => httpBody: holds the result of the expression on the right
    case Either.Right<PlacingOrderError, List<OrderPlaced>> r ->  // => success branch
    // => executes the statement above; continues to next line
        "201 Created: " + r.value().size() + " events";           // => extract success value
        // => method call: delegates to collaborator; result captured above
    case Either.Left<PlacingOrderError, List<OrderPlaced>> l ->   // => failure branch
    // => executes the statement above; continues to next line
        switch (l.value()) {                                       // => nested switch on error subtype
        // => pattern match: exhaustive dispatch on all possible cases
            case PlacingOrderError.ValidationError e -> "400 Bad Request: " + e.message();
            // => method call: delegates to collaborator; result captured above
            case PlacingOrderError.RepositoryFailure e -> "503 Service Unavailable";
            // => executes the statement above; continues to next line
        };
};
// => httpBody: "201 Created: 1 events" for valid input

import java.math.BigDecimal                                        // => BigDecimal for totals
// In production: import arrow.core.Either, arrow.core.left, arrow.core.right
// => Arrow Either<A, B>: A = error (left), B = success (right)
// => For self-contained example we use Kotlin's built-in Result or a sealed class
 
data class OrderId(val value: String)                              // => typed identity
// => data class OrderId: value type; copy/equals/hashCode/toString auto-generated
data class OrderPlaced(val orderId: OrderId, val total: BigDecimal)// => domain event
// => data class OrderPlaced: value type; copy/equals/hashCode/toString auto-generated
 
sealed class PlacingOrderError {                                   // => sealed: when is exhaustive
// => class PlacingOrderError: implementation — contains field declarations and methods below
    data class ValidationError(val message: String) : PlacingOrderError()
    // => domain validation failure; no adapter involved; message carries human-readable reason
    // => val message: String - human-readable reason for validation failure
    data class RepositoryFailure(val cause: String) : PlacingOrderError()
    // => adapter exception wrapped by application service; cause from exception message
    // => val cause: String - exception message from adapter
}
 
// ── Simple Either using sealed class ─────────────────────────────────────────
sealed class OrderResult {                                         // => discriminated union
// => class OrderResult: implementation — contains field declarations and methods below
    data class Success(val events: List<OrderPlaced>) : OrderResult()  // => right branch; carries events
    // => data class Success: value type; copy/equals/hashCode/toString auto-generated
    data class Failure(val error: PlacingOrderError) : OrderResult()   // => left branch; carries typed error
    // => data class Failure: value type; copy/equals/hashCode/toString auto-generated
}
 
fun interface PlaceOrderUseCase {                                   // => SAM; lambda impl allowed
// => interface PlaceOrderUseCase: contract definition — no implementation details here
    fun placeOrder(customerId: String, total: BigDecimal): OrderResult
    // => Returns OrderResult; caller must when-match; no silent exception swallowing
    // => No try-catch needed at call site; all failures are typed values
    // => SAM: single abstract method; Kotlin allows lambda: PlaceOrderUseCase { ... }
}
 
val service = PlaceOrderUseCase { customerId, total ->             // => lambda implements SAM
// => service: holds the result of the expression on the right
    if (total <= BigDecimal.ZERO) {                                // => validation guard
    // => conditional branch: execution path depends on condition above
        OrderResult.Failure(PlacingOrderError.ValidationError("Total must be positive"))
        // => Returns Failure; caller gets typed error with message; no exception thrown
    } else {                                                       // => valid total: create event
    // => conditional branch: execution path depends on condition above
        val event = OrderPlaced(OrderId(java.util.UUID.randomUUID().toString()), total)
        // => new event with fresh UUID as order id
        OrderResult.Success(listOf(event))                         // => Returns Success with events
        // => method call: delegates to collaborator; result captured above
    }
}
 
val result = service.placeOrder("CUST-1", BigDecimal("50"))        // => invoke port
// => result: holds the result of the expression on the right
val httpBody = when (result) {                                     // => exhaustive when
// => httpBody: holds the result of the expression on the right
    is OrderResult.Success -> "201 Created: ${result.events.size} events" // => success path
    // => executes the statement above; continues to next line
    is OrderResult.Failure -> when (result.error) {                // => nested when on error
    // => method call: delegates to collaborator; result captured above
        is PlacingOrderError.ValidationError -> "400: ${result.error.message}"
        // => bad input: 400 Bad Request; message included in response body
        is PlacingOrderError.RepositoryFailure -> "503: ${result.error.cause}"
        // => DB down: 503 Service Unavailable; cause may be logged server-side
    }
}
// => httpBody: "201 Created: 1 events"

using System;                                                         // => Guid
// => executes the statement above; continues to next line
using System.Collections.Generic;                                     // => IReadOnlyList
// In production: using OneOf; (OneOf NuGet package)
// => For self-contained example we use a custom Result record
 
public record OrderId(string Value);                                  // => typed identity
// => executes the statement above; continues to next line
public record OrderPlaced(OrderId OrderId, decimal Total);            // => domain event; carries order data
// => OrderPlaced: event DTO; subscribers can react without domain aggregate
 
// Error hierarchy: abstract record base; switch expression forces all subtypes
public abstract record PlacingOrderError  // => abstract: cannot instantiate directly; only subtypes
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    public record ValidationError(string Message) : PlacingOrderError;   // => bad input
    // => domain validation failure; caught before any I/O
    public record RepositoryFailure(string Cause) : PlacingOrderError;   // => DB error
    // => adapter exception wrapped by application service into typed error
}
 
// Result union: Success or Failure; callers switch on it
// => No exception thrown across the port boundary; error is a typed value
public record OrderCommandResult  // => abstract base record; switch forces exhaustive handling
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    public record Success(IReadOnlyList<OrderPlaced> Events) : OrderCommandResult;
    // => success variant; carries events produced by the command
    // => IReadOnlyList: caller can enumerate but not mutate
    public record Failure(PlacingOrderError Error) : OrderCommandResult;
    // => failure variant; carries typed error value
    // => PlacingOrderError: abstract base; caller switch forces subtype handling
}
 
public interface IPlaceOrderUseCase  // => application zone; no ASP.NET, no EF Core
// => executes the statement above; continues to next line
{
    OrderCommandResult PlaceOrder(string customerId, decimal total);   // => returns union; never throws
    // => Returns discriminated union; HTTP adapter switch-matches to status codes
    // => No try-catch needed at call site; all failures are typed values
}
 
public class PlaceOrderService : IPlaceOrderUseCase  // => command-side implementation; no EF Core
// => executes the statement above; continues to next line
{                                                                     // => command-side service
// => executes the statement above; continues to next line
    public OrderCommandResult PlaceOrder(string customerId, decimal total)
    // => executes the statement above; continues to next line
    {                                                                 // => returns discriminated union; never throws
    // => executes the statement above; continues to next line
        if (total <= 0)                                           // => validation guard; domain rule
        // => conditional branch: execution path depends on condition above
            return new OrderCommandResult.Failure(               // => return typed failure
            // => returns the result to the caller — caller receives this value
                new PlacingOrderError.ValidationError("Total must be positive"));
        // => no repository call if validation fails
        var evt = new OrderPlaced(new OrderId(Guid.NewGuid().ToString()), total);
        // => create domain event with fresh id
        return new OrderCommandResult.Success(new[] { evt });    // => typed success with events
        // => array wrapped as IReadOnlyList; immutable view for callers
    }
}
 
// ── HTTP adapter: switch expression maps result to HTTP response ──────────────
var service = new PlaceOrderService();                            // => in production: inject via DI
// => service: holds the result of the expression on the right
var result  = service.PlaceOrder("CUST-1", 50m);                  // => call port; returns union
// => result: holds the result of the expression on the right
 
string httpBody = result switch                                   // => exhaustive switch; C# 8+ pattern matching
// => httpBody: holds the result of the expression on the right
{
    OrderCommandResult.Success s => $"201 Created: {s.Events.Count} events",
    // => success: 201 Created; event count in body
    // => s.Events.Count: number of domain events produced by command
    OrderCommandResult.Failure f => f.Error switch               // => nested switch on error
    // => executes the statement above; continues to next line
    {                                                            // => f.Error: PlacingOrderError; further switch
    // => executes the statement above; continues to next line
        PlacingOrderError.ValidationError e => $"400 Bad Request: {e.Message}",
        // => bad input: 400 with error message
        PlacingOrderError.RepositoryFailure e => "503 Service Unavailable",
        // => DB down: 503; Cause available in e.Cause for logging
        _ => "500 Internal Server Error"                         // => exhaustive: safety default
        // => executes the statement above; continues to next line
    },
    _ => "500 Internal Server Error"                             // => exhaustive: safety default
    // => executes the statement above; continues to next line
};
// => httpBody: "201 Created: 1 events" for valid input; total=50 passes validation

import java.math.BigDecimal;
// => executes the statement above; continues to next line
import java.util.List;
// => executes the statement above; continues to next line
import java.util.Optional;
 
// ── Supporting types ──────────────────────────────────────────────────────────
record OrderId(String value) {}                         // => typed identity
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
record OrderPlaced(OrderId orderId, BigDecimal total) {} // => domain event on success
 
// ── Sealed error hierarchy (Java 17+) ─────────────────────────────────────────
// All errors a caller can receive from PlaceOrderUseCase in one sealed type
// => Sealed: compiler enforces exhaustive switch expression over all subtypes
sealed interface PlacingOrderError permits
// => executes the statement above; continues to next line
    PlacingOrderError.ValidationError,
    // => executes the statement above; continues to next line
    PlacingOrderError.ProductNotFound,
    // => executes the statement above; continues to next line
    PlacingOrderError.RepositoryFailure,
    // => executes the statement above; continues to next line
    PlacingOrderError.NotificationFailure {
 
    // Domain errors: arise from business rule violations or missing domain data
    record ValidationError(String field, String message) implements PlacingOrderError {}
    // => e.g. missing customerId, negative total, empty product list
 
    record ProductNotFound(String productId) implements PlacingOrderError {}
    // => Domain policy: cannot place an order for a product that does not exist
 
    // Adapter errors: arise when infrastructure calls fail
    // => Adapter exceptions are caught by the application service and converted here
    record RepositoryFailure(String cause) implements PlacingOrderError {}
    // => DB down, connection pool exhausted, optimistic lock conflict
 
    record NotificationFailure(String cause) implements PlacingOrderError {}
    // => Email or SMS adapter failed; order was saved but customer not notified
}
 
// ── Output port interfaces ────────────────────────────────────────────────────
interface OrderRepository {
// => interface OrderRepository: contract definition — no implementation details here
    void save(OrderId id, BigDecimal total); // => throws RuntimeException on DB failure
    // => Application service catches RuntimeException and converts to RepositoryFailure
}
// => operation completes; execution continues to next statement
 
interface NotificationPort {
// => interface NotificationPort: contract definition — no implementation details here
    void sendConfirmation(OrderId id);       // => throws RuntimeException on failure
    // => executes the statement above; continues to next line
}
 
// ── Application service: catches adapter exceptions, returns typed errors ─────
class PlaceOrderService {
// => class PlaceOrderService: implementation — contains field declarations and methods below
    private final OrderRepository repository;           // => injected; adapter in adapter zone
    // => repository: OrderRepository — final field; assigned once in constructor; immutable reference
    private final NotificationPort notification;        // => injected; adapter in adapter zone
    // => notification: NotificationPort — final field; assigned once in constructor; immutable reference
 
    PlaceOrderService(OrderRepository r, NotificationPort n) {
    // => executes the statement above; continues to next line
        this.repository   = r;                          // => dependency injection; no new
        // => this.repository stored — field holds injected r for method calls below
        this.notification = n;                          // => no concrete class imported here
        // => this.notification stored — field holds injected n for method calls below
    }
 
    // Returns Either-like type; Left = error, Right = events
    Object placeOrder(String customerId, BigDecimal total) {
    // => executes the statement above; continues to next line
        if (total.compareTo(BigDecimal.ZERO) <= 0)      // => domain validation
        // => conditional branch: execution path depends on condition above
            return new PlacingOrderError.ValidationError("total", "must be positive");
            // => ValidationError: domain rule; not from any adapter
 
        var id = new OrderId(java.util.UUID.randomUUID().toString());
        // => id: holds the result of the expression on the right
        try {
        // => exception handling: wraps operation that may fail
            repository.save(id, total);                 // => may throw RuntimeException
            // => method call: delegates to collaborator; result captured above
        } catch (RuntimeException e) {
        // => executes the statement above; continues to next line
            return new PlacingOrderError.RepositoryFailure(e.getMessage());
            // => Converts untyped exception into typed error; domain never sees exception
        }
        // => operation completes; execution continues to next statement
 
        try {
        // => exception handling: wraps operation that may fail
            notification.sendConfirmation(id);          // => may throw RuntimeException
            // => method call: delegates to collaborator; result captured above
        } catch (RuntimeException e) {
        // => executes the statement above; continues to next line
            return new PlacingOrderError.NotificationFailure(e.getMessage());
            // => Order was saved; notification failed — distinct error subtype for caller
        }
 
        return List.of(new OrderPlaced(id, total));     // => success path; returns events
        // => returns the result to the caller — caller receives this value
    }
}
 
// ── HTTP adapter: exhaustive pattern match on error hierarchy ─────────────────
var service = new PlaceOrderService(
// => service: holds the result of the expression on the right
    (id, t) -> {},                                      // => in-memory no-op repository
    // => executes the statement above; continues to next line
    id -> {}                                            // => in-memory no-op notification
    // => executes the statement above; continues to next line
);
var result = service.placeOrder("CUST-1", new BigDecimal("50")); // => invoke
// => result: holds the result of the expression on the right
 
String statusCode = switch (result) {                   // => pattern match on result type
// => statusCode: holds the result of the expression on the right
    case PlacingOrderError.ValidationError e   -> "400";  // => bad input
    // => executes the statement above; continues to next line
    case PlacingOrderError.ProductNotFound e   -> "404";  // => resource missing
    // => executes the statement above; continues to next line
    case PlacingOrderError.RepositoryFailure e -> "503";  // => infrastructure down
    // => executes the statement above; continues to next line
    case PlacingOrderError.NotificationFailure e -> "202"; // => saved but notify failed
    // => executes the statement above; continues to next line
    default                                    -> "201";  // => List<OrderPlaced> = success
    // => executes the statement above; continues to next line
};
// => statusCode: "201" — all adapters no-op; no errors triggered

import java.math.BigDecimal                                         // => BigDecimal for totals
// => executes the statement above; continues to next line
 
data class OrderId(val value: String)                               // => typed identity
// => data class OrderId: value type; copy/equals/hashCode/toString auto-generated
data class OrderPlaced(val orderId: OrderId, val total: BigDecimal) // => domain event
 
// ── Sealed error hierarchy ────────────────────────────────────────────────────
// sealed class: Kotlin guarantees exhaustive when; no default branch needed
sealed class PlacingOrderError {                                     // => sealed: when is exhaustive
// => class PlacingOrderError: implementation — contains field declarations and methods below
    data class ValidationError(val field: String, val message: String) : PlacingOrderError()
    // => Domain validation failure; no adapter involved
    // => field: which field; message: why it's invalid
    data class ProductNotFound(val productId: String) : PlacingOrderError()
    // => Domain policy: product does not exist; cannot place order
    // => productId: which product was not found
    data class RepositoryFailure(val cause: String) : PlacingOrderError()
    // => Adapter exception wrapped into typed error by application service
    // => cause: exception message from DB adapter
    data class NotificationFailure(val cause: String) : PlacingOrderError()
    // => Email/SMS adapter failed; order persisted but user not notified
    // => cause: exception message from notification adapter
}
 
// ── Port interfaces ───────────────────────────────────────────────────────────
interface OrderRepository { fun save(id: OrderId, total: BigDecimal) } // => may throw; service wraps
// => interface OrderRepository: contract definition — no implementation details here
interface NotificationPort { fun sendConfirmation(id: OrderId) }       // => may throw; service wraps
 
// ── Application service: wraps exceptions into typed errors ──────────────────
class PlaceOrderService(
// => executes the statement above; continues to next line
    private val repository: OrderRepository,           // => injected; no concrete class here
    // => executes the statement above; continues to next line
    private val notification: NotificationPort         // => injected; adapter in adapter zone
    // => executes the statement above; continues to next line
) {
    fun placeOrder(customerId: String, total: BigDecimal): Result<List<OrderPlaced>> {
        // => Result<List<OrderPlaced>>: success = events; failure = PlacingOrderError
        if (total <= BigDecimal.ZERO)                  // => domain validation guard
        // => conditional branch: execution path depends on condition above
            return Result.failure(PlacingOrderError.ValidationError("total", "must be positive"))
            // => Kotlin Result.failure wraps the typed error
 
        val id = OrderId(java.util.UUID.randomUUID().toString())
        // => fresh order id; domain type
        runCatching { repository.save(id, total) }     // => catch adapter exception
        // => method call: delegates to collaborator; result captured above
            .onFailure { return Result.failure(PlacingOrderError.RepositoryFailure(it.message ?: "db")) }
            // => Converts Throwable to typed RepositoryFailure; domain stays clean
 
        runCatching { notification.sendConfirmation(id) } // => catch notification exception
        // => method call: delegates to collaborator; result captured above
            .onFailure { return Result.failure(PlacingOrderError.NotificationFailure(it.message ?: "notify")) }
            // => Order already saved; notification failed — distinct error for caller
            // => "notify" fallback: prevents null message propagation
 
        return Result.success(listOf(OrderPlaced(id, total))) // => success path
        // => List with one event; callers publish or persist
    }
}
 
// ── HTTP adapter: exhaustive when on error type ───────────────────────────────
val service = PlaceOrderService({ _, _ -> }, { _ -> })  // => lambda no-op adapters
// => first lambda: OrderRepository.save() no-op; second: NotificationPort.sendConfirmation() no-op
val result  = service.placeOrder("CUST-1", BigDecimal("50"))
// => invokes service; no-op adapters produce no exceptions
 
val status = result.fold(
// => status: holds the result of the expression on the right
    onSuccess = { "201" },                             // => success: 201 Created
    // => executes the statement above; continues to next line
    onFailure = { when (it) {                          // => failure: match error type
    // => executes the statement above; continues to next line
        is PlacingOrderError.ValidationError   -> "400" // => bad input
        // => executes the statement above; continues to next line
        is PlacingOrderError.ProductNotFound   -> "404" // => resource missing
        // => executes the statement above; continues to next line
        is PlacingOrderError.RepositoryFailure -> "503" // => DB down
        // => executes the statement above; continues to next line
        is PlacingOrderError.NotificationFailure -> "202" // => saved; notify failed
        // => executes the statement above; continues to next line
        else -> "500"                                  // => exhaustive safety
        // => executes the statement above; continues to next line
    }}
)
// => status: "201" — no-op adapters; no errors thrown

using System;                                                         // => Exception, Guid
// => executes the statement above; continues to next line
using System.Collections.Generic;                                     // => IReadOnlyList
// => executes the statement above; continues to next line
 
public record OrderId(string Value);                                  // => typed identity
// => executes the statement above; continues to next line
public record OrderPlaced(OrderId OrderId, decimal Total);            // => domain event
 
// ── Error hierarchy ───────────────────────────────────────────────────────────
// Abstract record base: switch expression forces handling of all subtypes
public abstract record PlacingOrderError  // => abstract; subtypes only; switch forces exhaustive handling
// => executes the statement above; continues to next line
{
    public record ValidationError(string Field, string Message) : PlacingOrderError;  // => domain error
    // => Domain error: bad input detected before any I/O
    // => Field: which field; Message: why invalid
    public record ProductNotFound(string ProductId) : PlacingOrderError;  // => domain error
    // => Domain error: product missing from catalog
    // => ProductId: which product was not found
    public record RepositoryFailure(string Cause) : PlacingOrderError;  // => adapter error
    // => Adapter error: DB exception wrapped by application service
    // => Cause: exception message from DB adapter
    public record NotificationFailure(string Cause) : PlacingOrderError;  // => adapter error
    // => Adapter error: email/SMS failed after order was saved
    // => Cause: exception message from notification adapter
}
 
// ── Result union ──────────────────────────────────────────────────────────────
public abstract record CommandResult  // => abstract base; Success or Failure; exhaustive switch
// => executes the statement above; continues to next line
{
    public record Success(IReadOnlyList<OrderPlaced> Events) : CommandResult;  // => success
    // => success variant; events produced by command
    public record Failure(PlacingOrderError Error) : CommandResult;             // => failure
    // => failure variant; typed error; no exception at call site
}
 
public interface IOrderRepository { void Save(OrderId id, decimal total); }  // => output port
// => output port; may throw; service wraps into RepositoryFailure
// => simplified: no FindById or Delete; enough for this example
public interface INotificationPort { void SendConfirmation(OrderId id); }  // => output port
// => output port; may throw; service wraps into NotificationFailure
// => simplified: one method; production might have sendShippingAlert etc.
 
public class PlaceOrderService(IOrderRepository repo, INotificationPort notify)  // => app service
// => executes the statement above; continues to next line
{                                                                     // => all ports injected
    // => all ports injected; no concrete adapter class imported
    public CommandResult PlaceOrder(string customerId, decimal total)  // => returns typed union
    // => executes the statement above; continues to next line
    {
        if (total <= 0)                                           // => validation guard
        // => conditional branch: execution path depends on condition above
            return new CommandResult.Failure(                    // => typed ValidationError
            // => returns the result to the caller — caller receives this value
                new PlacingOrderError.ValidationError("total", "must be positive"));
        // => no I/O; pure domain validation; total must be positive
 
        var id = new OrderId(Guid.NewGuid().ToString());          // => fresh order id
        // => id: holds the result of the expression on the right
        try { repo.Save(id, total); }                            // => adapter call; may throw
        // => exception handling: wraps operation that may fail
        catch (Exception ex)
        // => exception handling: wraps operation that may fail
        {                                                         // => catch adapter exception
        // => executes the statement above; continues to next line
            return new CommandResult.Failure(                    // => wrap in typed error
            // => returns the result to the caller — caller receives this value
                new PlacingOrderError.RepositoryFailure(ex.Message));
            // => exception converted; domain never sees exception
        }
 
        try { notify.SendConfirmation(id); }                     // => notification; may throw
        // => exception handling: wraps operation that may fail
        catch (Exception ex)
        // => exception handling: wraps operation that may fail
        {                                                         // => order saved; notification failed
        // => executes the statement above; continues to next line
            return new CommandResult.Failure(                    // => order saved; notify failed
            // => returns the result to the caller — caller receives this value
                new PlacingOrderError.NotificationFailure(ex.Message));
            // => distinct from RepositoryFailure; maps to different HTTP status
        }
 
        return new CommandResult.Success(new[] { new OrderPlaced(id, total) }); // => success
        // => array literal; IReadOnlyList satisfied; one event per command
    }
}
 
// ── HTTP adapter: switch expression maps to status code ───────────────────────
var service = new PlaceOrderService(                             // => no-op adapters
// => service: holds the result of the expression on the right
    new NoOpRepository(), new NoOpNotification());               // => no-op: no DB, no SMTP
    // => executes the statement above; continues to next line
var result = service.PlaceOrder("CUST-1", 50m); // => invoke service; total=50m passes validation
// => result: holds the result of the expression on the right
 
string status = result switch // => exhaustive switch; C# 8+ pattern matching
// => status: holds the result of the expression on the right
{
    CommandResult.Success s => "201", // => success: 201 Created
    // => executes the statement above; continues to next line
    CommandResult.Failure f => f.Error switch           // => nested switch on error type
    // => executes the statement above; continues to next line
    {
        PlacingOrderError.ValidationError => "400", // => bad input: 400
        // => executes the statement above; continues to next line
        PlacingOrderError.ProductNotFound => "404", // => not found: 404
        // => executes the statement above; continues to next line
        PlacingOrderError.RepositoryFailure => "503", // => DB down: 503
        // => executes the statement above; continues to next line
        PlacingOrderError.NotificationFailure => "202", // => saved; not notified: 202
        // => executes the statement above; continues to next line
        _ => "500" // => safety default
        // => executes the statement above; continues to next line
    },
    _ => "500" // => safety default
    // => executes the statement above; continues to next line
};
// => status: "201" — no-op adapters produce no exceptions
// => "CUST-1" and 50m: both valid; no validation errors; no adapter exceptions
 
// ── No-op test stubs ──────────────────────────────────────────────────────────
class NoOpRepository : IOrderRepository { public void Save(OrderId id, decimal total) {} }
// => no-op; no DB; no exception; simulates successful save
// => {} empty body: no side effects; never throws
class NoOpNotification : INotificationPort { public void SendConfirmation(OrderId id) {} }
// => no-op; no SMTP; no exception; simulates successful notification

import java.math.BigDecimal;
// => executes the statement above; continues to next line
import java.util.List;
// => executes the statement above; continues to next line
import java.util.Optional;
 
// ── Supporting types ──────────────────────────────────────────────────────────
record OrderId(String value) {}                         // => typed identity
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
record Order(OrderId id, BigDecimal total) {}            // => domain aggregate (minimal)
 
// Pagination request: defined in application zone; no Spring dependency
// => pageNumber is 0-based; pageSize is the maximum items per page
record Pageable(int pageNumber, int pageSize) {
// => record Pageable: immutable value type; equals/hashCode/toString generated by compiler
    public static Pageable of(int page, int size) { return new Pageable(page, size); }
    // => factory method for readable call sites: Pageable.of(0, 20)
}
 
// Paginated result: also in application zone; carries content plus metadata
// => total allows the caller to compute totalPages = (int) Math.ceil(total / pageSize)
record Page<T>(List<T> content, long total, int pageNumber, int pageSize) {
// => record Page: immutable value type; equals/hashCode/toString generated by compiler
    public int totalPages() { return (int) Math.ceil((double) total / pageSize); }
    // => totalPages: derived; not stored; computed on read
}
 
// ── Full repository port ──────────────────────────────────────────────────────
// Interface in application zone; no JPA, Exposed, EF Core on this interface
// => All methods use domain types; adapters translate internally
interface OrderRepository {
// => interface OrderRepository: contract definition — no implementation details here
    Optional<Order> findById(OrderId id);          // => null-safe lookup; empty = not found
    // => executes the statement above; continues to next line
    void save(Order order);                        // => insert or update; idempotent by id
    // => executes the statement above; continues to next line
    void delete(OrderId id);                       // => remove from store; no-op if missing
    // => executes the statement above; continues to next line
    boolean existsById(OrderId id);                // => existence check without loading aggregate
    // => executes the statement above; continues to next line
    Page<Order> findAll(Pageable pageable);        // => paginated scan; never load entire table
    // => Application zone owns Pageable and Page; no Spring Data import needed
}
 
// ── In-memory adapter (test / development) ────────────────────────────────────
class InMemoryOrderRepository implements OrderRepository {
// => InMemoryOrderRepository implements OrderRepository — satisfies the port contract
    private final java.util.Map<String, Order> store = new java.util.LinkedHashMap<>();
    // => LinkedHashMap: preserves insertion order for deterministic pagination in tests
 
    @Override public Optional<Order> findById(OrderId id)  { return Optional.ofNullable(store.get(id.value())); }
    // => @Override: compiler verifies this method signature matches the interface
    @Override public void save(Order o)                    { store.put(o.id().value(), o); }
    // => put: insert on first call; replace on subsequent calls — idempotent by design
    @Override public void delete(OrderId id)               { store.remove(id.value()); }
    // => @Override: compiler verifies this method signature matches the interface
    @Override public boolean existsById(OrderId id)        { return store.containsKey(id.value()); }
    // => @Override: compiler verifies this method signature matches the interface
 
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public Page<Order> findAll(Pageable p) {
    // => executes the statement above; continues to next line
        var all   = List.copyOf(store.values());           // => snapshot; avoid concurrent modification
        // => all: holds the result of the expression on the right
        int from  = Math.min(p.pageNumber() * p.pageSize(), all.size()); // => start index; clamped
        // => from: holds the result of the expression on the right
        int to    = Math.min(from + p.pageSize(), all.size());           // => end index; clamped
        // => to: holds the result of the expression on the right
        return new Page<>(all.subList(from, to), all.size(), p.pageNumber(), p.pageSize());
        // => subList: O(1) view over the snapshot; no copy; correct pagination slice
    }
}
 
// ── Usage ─────────────────────────────────────────────────────────────────────
var repo = new InMemoryOrderRepository();                  // => test adapter
// => repo: holds the result of the expression on the right
repo.save(new Order(new OrderId("O1"), new BigDecimal("50")));  // => seed page 0
// => method call: delegates to collaborator; result captured above
repo.save(new Order(new OrderId("O2"), new BigDecimal("80")));  // => seed page 0
// => method call: delegates to collaborator; result captured above
repo.save(new Order(new OrderId("O3"), new BigDecimal("30")));  // => seed page 1 (size=2)
// => method call: delegates to collaborator; result captured above
 
var page0 = repo.findAll(Pageable.of(0, 2));               // => page 0; size 2
// => page0.content() is [O1, O2]; page0.total() is 3; page0.totalPages() is 2
var page1 = repo.findAll(Pageable.of(1, 2));               // => page 1; size 2
// => page1.content() is [O3]; page1.total() is 3

import java.math.BigDecimal                                          // => BigDecimal for total
// => executes the statement above; continues to next line
 
data class OrderId(val value: String)                                // => typed identity
// => data class OrderId: value type; copy/equals/hashCode/toString auto-generated
data class Order(val id: OrderId, val total: BigDecimal)             // => domain aggregate
 
// Application-zone pagination types — no Exposed or Spring dependency
data class Pageable(val pageNumber: Int, val pageSize: Int) {    // => application-owned; no Spring
// => class Pageable: implementation — contains field declarations and methods below
    companion object { fun of(page: Int, size: Int) = Pageable(page, size) }
    // => companion object factory; Pageable.of(0, 20) reads naturally
    // => 0-based page number; adapters translate to Spring's PageRequest or Exposed offset
}
data class Page<T>(val content: List<T>, val total: Long, val pageNumber: Int, val pageSize: Int) {
    // => content: items on current page; total: total count across all pages
    val totalPages: Int get() = Math.ceil(total.toDouble() / pageSize).toInt()
    // => computed property; not stored in primary constructor
    // => total: total items across all pages; used by caller to render pagination UI
}
 
// ── Repository port ───────────────────────────────────────────────────────────
interface OrderRepository {                                          // => application zone interface
// => interface OrderRepository: contract definition — no implementation details here
    fun findById(id: OrderId): Order?            // => nullable return; no Optional needed in Kotlin
    // => executes the statement above; continues to next line
    fun save(order: Order)                       // => insert or update; idempotent
    // => executes the statement above; continues to next line
    fun delete(id: OrderId)                      // => remove; no-op if absent
    // => executes the statement above; continues to next line
    fun existsById(id: OrderId): Boolean         // => existence probe; no aggregate loaded
    // => executes the statement above; continues to next line
    fun findAll(pageable: Pageable): Page<Order> // => paginated; never full table scan
    // => All methods use application-owned types; no JPA or Exposed imports here
    // => InMemoryOrderRepository: test adapter; ExposedOrderRepository: production adapter
}
 
// ── In-memory adapter ─────────────────────────────────────────────────────────
class InMemoryOrderRepository : OrderRepository {                    // => test adapter; no DB
// => class InMemoryOrderRepository: implementation — contains field declarations and methods below
    private val store = linkedMapOf<String, Order>() // => insertion-order map for tests
    // => store: val — injected dependency; implementation chosen at wiring time
 
    override fun findById(id: OrderId): Order?        = store[id.value]     // => null if absent
    // => method call: delegates to collaborator; result captured above
    override fun save(order: Order)                   { store[order.id.value] = order }
    // => upsert; insert on first call; replace on subsequent calls
    // => key = order id string; value = full Order aggregate
    override fun delete(id: OrderId)                  { store.remove(id.value) }
    // => remove; no-op if key absent
    // => null-safe; LinkedHashMap.remove returns null if key not found
    override fun existsById(id: OrderId): Boolean     = store.containsKey(id.value)
    // => existence check without loading aggregate
 
    override fun findAll(pageable: Pageable): Page<Order> {
    // => findAll: method entry point — see implementation below
        val all   = store.values.toList()                // => snapshot copy; avoid concurrent modification
        // => all: holds the result of the expression on the right
        val from  = (pageable.pageNumber * pageable.pageSize).coerceAtMost(all.size)
        // => start index; clamped to list size
        val to    = (from + pageable.pageSize).coerceAtMost(all.size)
        // => coerceAtMost: Kotlin stdlib; clamps to list bounds safely
        return Page(all.subList(from, to), all.size.toLong(), pageable.pageNumber, pageable.pageSize)
        // => returns page slice with total count for caller to compute totalPages
    }
}

using System;                                                         // => Math.Ceiling
// => executes the statement above; continues to next line
using System.Collections.Generic;                                     // => IReadOnlyList, Dictionary
// => executes the statement above; continues to next line
using System.Linq;                                                    // => ToList, GetRange
// => executes the statement above; continues to next line
 
public record OrderId(string Value);                                  // => typed identity; typed wrapper over string
// => executes the statement above; continues to next line
public record Order(OrderId Id, decimal Total);                       // => domain aggregate; minimal for this example
// => Order: no JPA/EF annotation; clean from infrastructure
 
// Application-zone pagination — no EF Core dependency on these types
public record Pageable(int PageNumber, int PageSize);        // => 0-based page number; PageSize = max items per page
// => Pageable: application-owned; no EF Core or Spring.Data dependency
public record Page<T>(IReadOnlyList<T> Content, long Total, int PageNumber, int PageSize)
// => Content: current page items; Total: total across all pages; PageNumber: current page
{                                                                     // => generic; works for any item type
// => executes the statement above; continues to next line
    public int TotalPages => (int)Math.Ceiling((double)Total / PageSize);
    // => computed property; callers use TotalPages to render pagination UI
    // => Total: total count across all pages; not just current page size
    // => (double)Total: prevents integer division; Ceiling rounds up for partial last page
}
 
// ── Repository port ───────────────────────────────────────────────────────────
public interface IOrderRepository  // => application zone; no EF Core import here
// => executes the statement above; continues to next line
{
    Order? FindById(OrderId id);               // => null = not found; no exception
    // => executes the statement above; continues to next line
    void Save(Order order);                    // => upsert semantics; idempotent
    // => executes the statement above; continues to next line
    void Delete(OrderId id);                   // => remove; no-op if absent; safe
    // => executes the statement above; continues to next line
    bool ExistsById(OrderId id);               // => existence check without loading aggregate
    // => executes the statement above; continues to next line
    Page<Order> FindAll(Pageable pageable);    // => paginated; interface owns Pageable
    // => Pageable and Page owned by application zone; no EF Core or Spring import
}
 
// ── In-memory adapter ─────────────────────────────────────────────────────────
public class InMemoryOrderRepository : IOrderRepository  // => test adapter; no DB
// => executes the statement above; continues to next line
{                                                          // => suitable for unit and application tests
// => executes the statement above; continues to next line
    private readonly Dictionary<string, Order> _store = new();  // => backing store; insertion-order not guaranteed
    // => executes the statement above; continues to next line
 
    public Order?       FindById(OrderId id) => _store.TryGetValue(id.Value, out var o) ? o : null;
    // => null-safe lookup; null if not found; no exception
    public void         Save(Order order)    => _store[order.Id.Value] = order;
    // => upsert by id; insert or replace; idempotent
    public void         Delete(OrderId id)   => _store.Remove(id.Value);
    // => remove entry; no-op if absent; Dictionary.Remove is safe
    public bool         ExistsById(OrderId id) => _store.ContainsKey(id.Value);
    // => existence check without loading aggregate; O(1)
 
    public Page<Order> FindAll(Pageable p)
    // => executes the statement above; continues to next line
    {                                                              // => paginated read; never full scan
    // => executes the statement above; continues to next line
        var all   = _store.Values.ToList();                      // => snapshot; avoid mutation during iteration
        // => all: holds the result of the expression on the right
        int from  = Math.Min(p.PageNumber * p.PageSize, all.Count); // => start index; clamped
        // => from: holds the result of the expression on the right
        int count = Math.Min(p.PageSize, all.Count - from);     // => items on this page
        // => count: holds the result of the expression on the right
        return new Page<Order>(all.GetRange(from, count), all.Count, p.PageNumber, p.PageSize);
        // => GetRange: O(n) copy of slice; correct for in-memory adapter
        // => all.Count is total for TotalPages calculation
    }
}

import java.util.ArrayList;
// => executes the statement above; continues to next line
import java.util.Collections;
// => executes the statement above; continues to next line
import java.util.List;
 
// ── Domain notification payloads ──────────────────────────────────────────────
record OrderId(String value) {}                         // => typed identity
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
record OrderConfirmation(OrderId orderId, String email, String total) {}
// => All data the notification adapter needs to send an order confirmation
record ShippingAlert(OrderId orderId, String email, String trackingNumber) {}
// => Shipping notification payload; separate record from OrderConfirmation
 
// ── Notification port ─────────────────────────────────────────────────────────
// Interface in application zone; no javax.mail, no Twilio import here
// => Application service calls sendOrderConfirmation without knowing email vs SMS
interface NotificationPort {
// => interface NotificationPort: contract definition — no implementation details here
    void sendOrderConfirmation(OrderConfirmation confirmation); // => order placed event handler
    // => executes the statement above; continues to next line
    void sendShippingAlert(ShippingAlert alert);                // => shipment event handler
    // => Both methods: fire-and-forget; throw on failure (adapter wraps exception)
}
 
// ── Production adapter: SMTP ──────────────────────────────────────────────────
class SmtpNotificationAdapter implements NotificationPort {
    // => In production: inject JavaMailSender; lives in adapter/out/notification
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public void sendOrderConfirmation(OrderConfirmation c) {
    // => sendOrderConfirmation: method entry point — see implementation below
        System.out.println("SMTP to " + c.email() + ": order " + c.orderId().value() + " confirmed");
        // => In production: build MimeMessage, set To/Subject/Body, send via JavaMailSender
    }
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public void sendShippingAlert(ShippingAlert a) {
    // => sendShippingAlert: method entry point — see implementation below
        System.out.println("SMTP to " + a.email() + ": tracking " + a.trackingNumber());
        // => In production: different email template for shipping notification
    }
}
 
// ── Test adapter: records sent notifications ──────────────────────────────────
class FakeNotificationPort implements NotificationPort {
    // => No SMTP server needed; calls recorded in-memory for assertion in tests
    private final List<OrderConfirmation> confirmations = new ArrayList<>(); // => recorded confirmations
    // => confirmations: List<OrderConfirmation> — final field; assigned once in constructor; immutable reference
    private final List<ShippingAlert>     alerts        = new ArrayList<>(); // => recorded alerts
    // => alerts: List<ShippingAlert> — final field; assigned once in constructor; immutable reference
 
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public void sendOrderConfirmation(OrderConfirmation c) { confirmations.add(c); }
    // => Appends to list; test asserts confirmations.size() == 1 etc.
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public void sendShippingAlert(ShippingAlert a)         { alerts.add(a); }
    // => sendShippingAlert: method entry point — see implementation below
 
    public List<OrderConfirmation> sentConfirmations() { return Collections.unmodifiableList(confirmations); }
    // => Unmodifiable: test can read but not corrupt the recorded list
    public List<ShippingAlert>     sentAlerts()        { return Collections.unmodifiableList(alerts); }
    // => executes the statement above; continues to next line
}
 
// ── Application service: calls port; unaware of email or SMS ─────────────────
class NotifyOnOrderPlaced {
// => class NotifyOnOrderPlaced: implementation — contains field declarations and methods below
    private final NotificationPort notification;              // => injected port
    // => notification: NotificationPort — final field; assigned once in constructor; immutable reference
    NotifyOnOrderPlaced(NotificationPort n) { this.notification = n; }
    // => method call: delegates to collaborator; result captured above
 
    void handle(String orderId, String email, String total) {
    // => handle: method entry point — see implementation below
        notification.sendOrderConfirmation(new OrderConfirmation(new OrderId(orderId), email, total));
        // => Calls port; does not know if SMTP, SMS, or in-memory fake is wired
    }
}
 
// ── Test ──────────────────────────────────────────────────────────────────────
var fake    = new FakeNotificationPort();                     // => test adapter
// => fake: holds the result of the expression on the right
var handler = new NotifyOnOrderPlaced(fake);                  // => inject fake
// => handler: holds the result of the expression on the right
handler.handle("O1", "alice@example.com", "99 USD");          // => trigger notification
// => method call: delegates to collaborator; result captured above
 
assert fake.sentConfirmations().size() == 1;                  // => one confirmation sent
// => method call: delegates to collaborator; result captured above
assert fake.sentConfirmations().get(0).email().equals("alice@example.com"); // => correct recipient
// => method call: delegates to collaborator; result captured above

data class OrderId(val value: String)                                // => typed identity
// => data class OrderId: value type; copy/equals/hashCode/toString auto-generated
data class OrderConfirmation(val orderId: OrderId, val email: String, val total: String)
// => notification payload for order placement; carries all data SMTP adapter needs
// => email: recipient; total: human-readable amount for email body
data class ShippingAlert(val orderId: OrderId, val email: String, val trackingNumber: String)
// => notification payload for shipping event; separate record from OrderConfirmation
// => trackingNumber: carrier-assigned tracking id; not domain concept
 
// ── Port interface ────────────────────────────────────────────────────────────
interface NotificationPort {                                         // => application zone; no SMTP import
// => interface NotificationPort: contract definition — no implementation details here
    fun sendOrderConfirmation(confirmation: OrderConfirmation) // => fire-and-forget; throws on failure
    // => No SMTP, no Twilio, no HTTP on this interface; purely domain payload types
    fun sendShippingAlert(alert: ShippingAlert)               // => shipping event handler
    // => separate method per notification type; each adapter implements both
}
 
// ── Fake adapter ──────────────────────────────────────────────────────────────
class FakeNotificationPort : NotificationPort {                      // => test adapter; no SMTP
// => class FakeNotificationPort: implementation — contains field declarations and methods below
    val sentConfirmations = mutableListOf<OrderConfirmation>()  // => recorded for assertion
    // => sentConfirmations: holds the result of the expression on the right
    val sentAlerts        = mutableListOf<ShippingAlert>()      // => recorded for assertion
    // => sentAlerts: holds the result of the expression on the right
 
    override fun sendOrderConfirmation(confirmation: OrderConfirmation) {
    // => sendOrderConfirmation: method entry point — see implementation below
        sentConfirmations += confirmation                        // => += operator appends to list
        // => No network call; runs in microseconds; safe for unit tests
        // => sentConfirmations.size == 1 after one call; test asserts this
    }
    override fun sendShippingAlert(alert: ShippingAlert) { sentAlerts += alert }
    // => appends to sentAlerts; test asserts sentAlerts.size etc.
}
 
// ── Application service ───────────────────────────────────────────────────────
class NotifyOnOrderPlaced(private val notification: NotificationPort) { // => injected
// => class NotifyOnOrderPlaced: implementation — contains field declarations and methods below
    fun handle(orderId: String, email: String, total: String) {    // => call notification port
    // => handle: method entry point — see implementation below
        notification.sendOrderConfirmation(OrderConfirmation(OrderId(orderId), email, total))
        // => Calls interface; no knowledge of SMTP, Twilio, or in-memory fake
        // => OrderConfirmation constructed with all needed data; adapter decides delivery channel
        // => handle() returns Unit; notification is a side effect, not a return value
    }
}
 
// ── Test ──────────────────────────────────────────────────────────────────────
val fake    = FakeNotificationPort()                                 // => test adapter; no SMTP
// => fake: holds the result of the expression on the right
val handler = NotifyOnOrderPlaced(fake)                              // => inject fake
// => handler: holds the result of the expression on the right
handler.handle("O1", "alice@example.com", "99 USD")                  // => trigger notification
// => method call: delegates to collaborator; result captured above
 
check(fake.sentConfirmations.size == 1)                        // => exactly one confirmation
// => method call: delegates to collaborator; result captured above
check(fake.sentConfirmations[0].email == "alice@example.com")  // => correct recipient
// => method call: delegates to collaborator; result captured above

using System.Collections.Generic;                            // => List
// => executes the statement above; continues to next line
 
public record OrderId(string Value);                         // => typed identity
// => executes the statement above; continues to next line
public record OrderConfirmation(OrderId OrderId, string Email, string Total);
// => notification payload for order placement; all data SMTP adapter needs
// => Email: recipient; Total: human-readable amount string
public record ShippingAlert(OrderId OrderId, string Email, string TrackingNumber);
// => notification payload for shipping event; separate from OrderConfirmation
// => TrackingNumber: carrier-assigned id included in shipping email
 
// ── Port interface ────────────────────────────────────────────────────────────
public interface INotificationPort  // => application zone; no SMTP, no Twilio import
// => executes the statement above; continues to next line
{
    void SendOrderConfirmation(OrderConfirmation confirmation);
    // => fire-and-forget; adapter handles SMTP or SMS; throws on failure
    void SendShippingAlert(ShippingAlert alert);
    // => No SMTP, no Twilio, no HTTP on this interface; purely domain payload types
    // => two separate methods; each notification type has its own method
}
 
// ── Fake adapter ──────────────────────────────────────────────────────────────
public class FakeNotificationPort : INotificationPort  // => test adapter; no SMTP library
// => executes the statement above; continues to next line
{
    public List<OrderConfirmation> SentConfirmations { get; } = new(); // => recorded calls
    // => executes the statement above; continues to next line
    public List<ShippingAlert>     SentAlerts        { get; } = new(); // => recorded calls
    // => executes the statement above; continues to next line
 
    public void SendOrderConfirmation(OrderConfirmation c) => SentConfirmations.Add(c);
    // => Add to list; no network; assertion-ready after each test call
    // => expression body; one line; no side effects other than list append
    public void SendShippingAlert(ShippingAlert a)         => SentAlerts.Add(a);
    // => Add to SentAlerts; test asserts SentAlerts.Count etc.
}
 
// ── Application service ───────────────────────────────────────────────────────
public class NotifyOnOrderPlaced(INotificationPort notification)  // => primary constructor
// => constructor: receives all dependencies — enables testing with any adapter implementation
{                                                            // => notification injected; no SMTP import
// => executes the statement above; continues to next line
    public void Handle(string orderId, string email, string total) =>  // => expression body
    // => executes the statement above; continues to next line
        notification.SendOrderConfirmation(new OrderConfirmation(new OrderId(orderId), email, total));
        // => Calls interface; wiring decides whether SMTP or fake runs
        // => No SMTP import in this class; completely decoupled
}
 
// ── Test ──────────────────────────────────────────────────────────────────────
var fake    = new FakeNotificationPort();                    // => test adapter; no SMTP
// => fake: holds the result of the expression on the right
var handler = new NotifyOnOrderPlaced(fake);                 // => inject fake
// => handler: holds the result of the expression on the right
handler.Handle("O1", "alice@example.com", "99 USD");         // => trigger notification
// => method call: delegates to collaborator; result captured above
 
System.Diagnostics.Debug.Assert(fake.SentConfirmations.Count == 1);  // => one confirmation
// => method call: delegates to collaborator; result captured above
System.Diagnostics.Debug.Assert(fake.SentConfirmations[0].Email == "alice@example.com");
// => correct recipient in captured call

import java.time.Instant;
 
// ── Clock port ────────────────────────────────────────────────────────────────
// Interface in application zone; no java.time.Clock leaking into domain
// => Single method: now() returns the current moment as an Instant
interface ClockPort {
// => interface ClockPort: contract definition — no implementation details here
    Instant now(); // => called by application service; never by domain
    // => Domain is timeless; time is an infrastructure concern injected via this port
}
 
// ── Production adapter: delegates to system clock ─────────────────────────────
class SystemClock implements ClockPort {
// => SystemClock implements ClockPort — satisfies the port contract
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public Instant now() { return Instant.now(); } // => wall-clock time; non-deterministic
    // => In production: Instant.now() reads OS clock; changes every call
}
 
// ── Test adapter: always returns same instant ─────────────────────────────────
class FixedClock implements ClockPort {
// => FixedClock implements ClockPort — satisfies the port contract
    private final Instant fixed;                   // => fixed moment; set at construction
    // => fixed: Instant — final field; assigned once in constructor; immutable reference
    FixedClock(Instant fixed) { this.fixed = fixed; } // => constructor injection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
 
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public Instant now() { return fixed; }         // => always returns same value
    // => Deterministic: test asserts on exact expected timestamp
}
 
// ── Domain event that carries time ───────────────────────────────────────────
record OrderId(String value) {}
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
record OrderPlaced(OrderId orderId, Instant placedAt) {}  // => placedAt from clock port
 
// ── Application service: injects clock port ───────────────────────────────────
class PlaceOrderService {
// => class PlaceOrderService: implementation — contains field declarations and methods below
    private final ClockPort clock;                 // => injected; never calls Instant.now() directly
    // => clock: ClockPort — final field; assigned once in constructor; immutable reference
    PlaceOrderService(ClockPort clock) { this.clock = clock; }
    // => method call: delegates to collaborator; result captured above
 
    OrderPlaced place(String rawOrderId) {
    // => executes the statement above; continues to next line
        var placedAt = clock.now();               // => current time from port; production or test
        // => placedAt: holds the result of the expression on the right
        return new OrderPlaced(new OrderId(rawOrderId), placedAt);
        // => placedAt is exactly what clock.now() returned; no drift, no race condition
    }
}
 
// ── Test: fixed clock makes assertion deterministic ───────────────────────────
var fixedInstant = Instant.parse("2026-01-01T00:00:00Z"); // => known timestamp
// => fixedInstant: holds the result of the expression on the right
var clock        = new FixedClock(fixedInstant);           // => test adapter
// => clock: holds the result of the expression on the right
var service      = new PlaceOrderService(clock);           // => inject fixed clock
// => service: holds the result of the expression on the right
 
var event = service.place("O1");                           // => call service
// => event: holds the result of the expression on the right
 
assert event.placedAt().equals(fixedInstant);              // => deterministic assertion
// => Without fixed clock: assertion must use isAfter/isBefore windows — fragile

import java.time.Instant
 
// ── Port ──────────────────────────────────────────────────────────────────────
fun interface ClockPort { fun now(): Instant }             // => SAM interface; lambda-implementable
 
// ── Adapters ──────────────────────────────────────────────────────────────────
val systemClock: ClockPort = ClockPort { Instant.now() }  // => production: wall-clock
// => Lambda implements fun interface; one-liner for production adapter
// => Instant.now(): reads OS clock; non-deterministic; never used in tests
val fixedClock: ClockPort  = ClockPort { Instant.parse("2026-01-01T00:00:00Z") }
// => Test adapter: always same value; no side effects; deterministic
// => Parse ISO-8601 string; known timestamp for exact equality assertions
 
// ── Domain event ──────────────────────────────────────────────────────────────
data class OrderId(val value: String)                                // => typed identity
// => data class OrderId: value type; copy/equals/hashCode/toString auto-generated
data class OrderPlaced(val orderId: OrderId, val placedAt: Instant)  // => event with timestamp from port
 
// ── Application service ───────────────────────────────────────────────────────
class PlaceOrderService(private val clock: ClockPort) {    // => injected clock port
// => class PlaceOrderService: implementation — contains field declarations and methods below
    fun place(rawId: String): OrderPlaced {
    // => place: method entry point — see implementation below
        val placedAt = clock.now()                         // => from port; deterministic in tests
        // => placedAt: holds the result of the expression on the right
        return OrderPlaced(OrderId(rawId), placedAt)       // => event carries exact timestamp
        // => No Instant.now() in service; all time from clock port
    }
}
 
// ── Test ──────────────────────────────────────────────────────────────────────
val service = PlaceOrderService(fixedClock)                // => inject fixed adapter
// => service: holds the result of the expression on the right
val event   = service.place("O1")                          // => invoke
// => event: holds the result of the expression on the right
 
check(event.placedAt == Instant.parse("2026-01-01T00:00:00Z")) // => exact assertion; not range
// => method call: delegates to collaborator; result captured above

using System;                                                         // => DateTimeOffset, TimeSpan
 
// ── Port ──────────────────────────────────────────────────────────────────────
public interface IClockPort  // => application zone; no System.DateTime direct usage
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    DateTimeOffset Now { get; } // => property rather than method; idiomatic in C#
    // => Returns current moment; production = UtcNow; test = fixed value
}
 
// ── Production adapter ────────────────────────────────────────────────────────
public class SystemClock : IClockPort  // => production adapter; wall-clock
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    public DateTimeOffset Now => DateTimeOffset.UtcNow; // => wall-clock; different each call
    // => UTC: avoids daylight-saving ambiguity in time-sensitive assertions
}
 
// ── Test adapter ──────────────────────────────────────────────────────────────
public class FixedClock(DateTimeOffset Fixed) : IClockPort // => primary constructor C# 12
// => constructor: receives all dependencies — enables testing with any adapter implementation
{                                                          // => Fixed captured at construction
// => executes the statement above; continues to next line
    public DateTimeOffset Now => Fixed;                    // => always same; deterministic
    // => Constructor argument becomes the immutable fixed moment
}
 
// ── Domain event ──────────────────────────────────────────────────────────────
public record OrderId(string Value);                                  // => typed identity
// => executes the statement above; continues to next line
public record OrderPlaced(OrderId OrderId, DateTimeOffset PlacedAt);  // => event with timestamp
 
// ── Application service ───────────────────────────────────────────────────────
public class PlaceOrderService(IClockPort clock)           // => primary constructor; clock injected
// => constructor: receives all dependencies — enables testing with any adapter implementation
{                                                          // => no DateTimeOffset.UtcNow in this class
// => class type: implementation — contains field declarations and methods below
    public OrderPlaced Place(string rawId) =>              // => expression-body; returns event
    // => executes the statement above; continues to next line
        new OrderPlaced(new OrderId(rawId), clock.Now);    // => clock.Now from injected port
        // => No DateTimeOffset.UtcNow in application service; all time from port
}
 
// ── Test ──────────────────────────────────────────────────────────────────────
var fixedMoment = new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero);
// => known timestamp; year=2026, month=1, day=1, hour=0; UTC
// => test can use exact equality assertion
var service     = new PlaceOrderService(new FixedClock(fixedMoment)); // => inject fixed clock
// => service: holds the result of the expression on the right
var evt         = service.Place("O1");                                // => invoke service
// => evt: holds the result of the expression on the right
 
System.Diagnostics.Debug.Assert(evt.PlacedAt == fixedMoment); // => exact comparison; passes every run
// => Without fixed clock: must use approximate range check; can fail under load

import java.util.ArrayList;
// => executes the statement above; continues to next line
import java.util.List;
// => executes the statement above; continues to next line
import java.util.Map;
 
// ── Logger port ───────────────────────────────────────────────────────────────
// Interface in application zone; no SLF4J, no Logback import here
// => Structured: event name + context map; not a printf-style format string
interface LoggerPort {
// => interface LoggerPort: contract definition — no implementation details here
    void info(String event, Map<String, Object> context);  // => informational log entry
    // => executes the statement above; continues to next line
    void warn(String event, Map<String, Object> context);  // => warning; degraded but running
    // => executes the statement above; continues to next line
    void error(String event, Map<String, Object> context); // => error; operation failed
    // => Map<String, Object>: key-value context; adapter serialises to JSON or MDC fields
}
 
// ── Test adapter: records entries as list ─────────────────────────────────────
class RecordingLoggerPort implements LoggerPort {
// => RecordingLoggerPort implements LoggerPort — satisfies the port contract
    record LogEntry(String level, String event, Map<String, Object> context) {} // => captured log call
    // => record LogEntry: immutable value type; equals/hashCode/toString generated by compiler
    private final List<LogEntry> entries = new ArrayList<>(); // => ordered list of all log calls
    // => entries: List<LogEntry> — final field; assigned once in constructor; immutable reference
 
    @Override public void info(String event, Map<String, Object> ctx)  { entries.add(new LogEntry("INFO",  event, ctx)); }
    // => @Override: compiler verifies this method signature matches the interface
    @Override public void warn(String event, Map<String, Object> ctx)  { entries.add(new LogEntry("WARN",  event, ctx)); }
    // => @Override: compiler verifies this method signature matches the interface
    @Override public void error(String event, Map<String, Object> ctx) { entries.add(new LogEntry("ERROR", event, ctx)); }
    // => @Override: compiler verifies this method signature matches the interface
 
    public List<LogEntry> entries() { return List.copyOf(entries); } // => immutable snapshot
    // => Test: assert entries.get(0).event().equals("order.placed")
}
 
// ── Application service: structured logging via port ─────────────────────────
class PlaceOrderService {
// => class PlaceOrderService: implementation — contains field declarations and methods below
    private final LoggerPort logger;               // => injected; no System.out.println ever
    // => logger: LoggerPort — final field; assigned once in constructor; immutable reference
    PlaceOrderService(LoggerPort logger) { this.logger = logger; }
    // => method call: delegates to collaborator; result captured above
 
    void placeOrder(String orderId, String customerId) {
    // => placeOrder: method entry point — see implementation below
        logger.info("order.placing", Map.of(       // => named event + structured context
        // => method call: delegates to collaborator; result captured above
            "orderId",    orderId,                 // => context key/value pairs
            // => executes the statement above; continues to next line
            "customerId", customerId               // => logged as structured fields; searchable
            // => executes the statement above; continues to next line
        ));
        // => Business logic here (omitted for brevity)
        logger.info("order.placed", Map.of("orderId", orderId)); // => success event
        // => No println, no System.out, no Logger.getLogger() in service
    }
}
 
// ── Test ──────────────────────────────────────────────────────────────────────
var logger  = new RecordingLoggerPort();           // => test adapter
// => logger: holds the result of the expression on the right
var service = new PlaceOrderService(logger);       // => inject
// => service: holds the result of the expression on the right
service.placeOrder("O1", "CUST-1");               // => invoke
// => method call: delegates to collaborator; result captured above
 
var entries = logger.entries();
// => entries: holds the result of the expression on the right
assert entries.size() == 2;                        // => two log calls: placing + placed
// => method call: delegates to collaborator; result captured above
assert entries.get(0).event().equals("order.placing"); // => first event name correct
// => method call: delegates to collaborator; result captured above
assert entries.get(1).event().equals("order.placed");  // => second event name correct
// => method call: delegates to collaborator; result captured above
assert entries.get(1).context().get("orderId").equals("O1"); // => context carries orderId
// => method call: delegates to collaborator; result captured above