Advanced

// ── order-taking hexagon ──────────────────────────────────────────────────────
// Package: com.example.ordertaking.domain
// => This package has zero imports from com.example.shipping.*
// => Domain types belong exclusively to order-taking context
record OrderId(String value) {}         // => typed id; not shared with shipping
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
record CustomerId(String value) {}      // => order-taking's own customer concept
// => record CustomerId: immutable value type; equals/hashCode/toString generated by compiler
record Money(long centAmount) {}        // => value object; immutable; no framework
 
// Domain event published by order-taking hexagon
// => Lives in order-taking's application layer; shared only as a DTO on the bus
// => shipping context receives this DTO and maps to its own domain type
record OrderPlacedEvent(String orderId, long totalCents) {}
 
// Output port in order-taking: publishes domain events to the bus
// => Adapter wires to Kafka, RabbitMQ, or in-process; application layer is unaware
interface DomainEventPublisher {
// => interface DomainEventPublisher: contract definition — no implementation details here
    void publish(OrderPlacedEvent event); // => fire-and-forget; bus delivers to shipping
    // => Application service calls this after persisting the order
}
 
// Application service: orchestrates order-taking domain and publishes event
// => Does NOT import any type from com.example.shipping.*
class PlaceOrderService {
// => class PlaceOrderService: implementation — contains field declarations and methods below
    private final DomainEventPublisher publisher; // => injected; adapter provided at boot
    // => publisher: DomainEventPublisher — final field; assigned once in constructor; immutable reference
 
    PlaceOrderService(DomainEventPublisher publisher) {
    // => executes the statement above; continues to next line
        this.publisher = publisher; // => constructor injection; no Spring @Autowired needed
        // => this.publisher stored — field holds injected publisher for method calls below
    }
 
    OrderId placeOrder(CustomerId customer, Money total) {
    // => executes the statement above; continues to next line
        var id = new OrderId(java.util.UUID.randomUUID().toString()); // => generate id
        // => id: holds the result of the expression on the right
        publisher.publish(new OrderPlacedEvent(id.value(), total.centAmount())); // => emit event
        // => shipping hexagon reacts to this event independently
        return id; // => return id to HTTP adapter; no coupling to shipping's response
        // => returns the result to the caller — caller receives this value
    }
}
 
// ── shipping hexagon ──────────────────────────────────────────────────────────
// Package: com.example.shipping.domain
// => Has its own Shipment type; never imports OrderId from order-taking
// => TrackingId is shipping's concept; order-taking knows nothing of it
record TrackingId(String value) {}      // => shipping-specific type
// => record TrackingId: immutable value type; equals/hashCode/toString generated by compiler
record Shipment(TrackingId id, String orderId, String status) {}
// => orderId here is plain String from the event DTO — not order-taking's OrderId type
// => This is intentional: contexts share data values, never shared domain objects
 
// Input adapter in shipping: subscribes to the event bus
// => Receives OrderPlacedEvent DTO; translates to shipping domain command
class OrderPlacedEventHandler {
// => class OrderPlacedEventHandler: implementation — contains field declarations and methods below
    void handle(OrderPlacedEvent event) {
    // => handle: method entry point — see implementation below
        var trackingId = new TrackingId(java.util.UUID.randomUUID().toString()); // => new id
        // => trackingId: holds the result of the expression on the right
        var shipment = new Shipment(trackingId, event.orderId(), "PENDING"); // => create domain object
        // => shipment persisted via shipping's own ShipmentRepository port (not shown)
        System.out.println("Shipping: created shipment " + trackingId.value()); // => Output: Shipping: created shipment <uuid>
        // => output: verification line — shows result in console
    }
}

import java.util.UUID                                                // => UUID for id generation
 
// ── order-taking hexagon ──────────────────────────────────────────────────────
// Package: com.example.ordertaking.domain
// => No import from com.example.shipping; contexts are fully independent
data class OrderId(val value: String)       // => order-taking's own typed id
// => data class OrderId: value type; copy/equals/hashCode/toString auto-generated
data class Money(val centAmount: Long)      // => immutable value object; cents avoids float rounding
 
// Event DTO crossing context boundary via bus
// => Both contexts know this DTO schema; neither imports the other's domain
data class OrderPlacedEvent(val orderId: String, val totalCents: Long)
// => flat DTO; primitive fields only; no domain types crossing context boundary
 
// Output port: order-taking publishes events; adapter wires Kafka or in-memory
fun interface DomainEventPublisher {
// => interface DomainEventPublisher: contract definition — no implementation details here
    fun publish(event: OrderPlacedEvent) // => abstraction hides transport technology
    // => Adapter could be KafkaEventPublisher or InMemoryEventBus in tests
}
 
// Application service: places order and publishes event
// => No reference to shipping package anywhere in this file
class PlaceOrderService(private val publisher: DomainEventPublisher) {
// => class PlaceOrderService: implementation — contains field declarations and methods below
    fun placeOrder(customerId: String, total: Money): OrderId {
    // => placeOrder: method entry point — see implementation below
        val id = OrderId(UUID.randomUUID().toString()) // => fresh order id
        // => id: holds the result of the expression on the right
        publisher.publish(OrderPlacedEvent(id.value, total.centAmount)) // => event to bus
        // => shipping reacts asynchronously; order-taking does not wait
        return id // => return to HTTP adapter
        // => returns the result to the caller — caller receives this value
    }
}
 
// ── shipping hexagon ──────────────────────────────────────────────────────────
// Package: com.example.shipping.domain
// => Imports only OrderPlacedEvent DTO, never order-taking domain types
data class TrackingId(val value: String)   // => shipping's own identity concept
// => data class TrackingId: value type; copy/equals/hashCode/toString auto-generated
data class Shipment(val id: TrackingId, val orderId: String, val status: String)
// => orderId: String (value from event); not order-taking's OrderId type
// => status: String here; production would use enum; simplified for clarity
 
// Event handler adapter in shipping hexagon
class OrderPlacedEventHandler {
// => class OrderPlacedEventHandler: implementation — contains field declarations and methods below
    fun handle(event: OrderPlacedEvent) {
    // => handle: method entry point — see implementation below
        val trackingId = TrackingId(UUID.randomUUID().toString()) // => generate tracking id
        // => trackingId: holds the result of the expression on the right
        val shipment = Shipment(trackingId, event.orderId, "PENDING") // => domain construction
        // => persisted via ShipmentRepository port; handler is adapter calling app port
        println("Shipping: created shipment ${shipment.id.value}") // => Output: Shipping: created shipment <uuid>
        // => no return; side-effect only; persisted via port (not shown)
        // => handler decoupled from order-taking; no import of order-taking domain
    }
}

using System;                                                         // => System for Guid, Console
 
// ── order-taking hexagon ──────────────────────────────────────────────────────
// Namespace: OrderTaking.Domain
// => No using directive for Shipping.*; namespaces enforce context separation
public record OrderId(string Value);           // => typed id; not shared with Shipping
// => executes the statement above; continues to next line
public record Money(long CentAmount);          // => immutable value object; CentAmount avoids float
 
// Event DTO: crosses context boundary on the event bus only
// => Both contexts reference this DTO type; it acts as the shared schema
public sealed record OrderPlacedEvent(string OrderId, long TotalCents);  // => event DTO; flat
// => OrderId: plain string here; shipping doesn't import OrderTaking's OrderId type
 
// Output port: publishes event; adapter wires MassTransit or in-memory
public interface IDomainEventPublisher  // => application zone; no MassTransit import
// => executes the statement above; continues to next line
{
    void Publish(OrderPlacedEvent evt); // => fire-and-forget; bus delivers asynchronously
    // => Application service calls this; knows nothing of Kafka or RabbitMQ
}
 
// Application service: places order and publishes event
// => No using directive for Shipping; zero coupling to shipping namespace
public class PlaceOrderService  // => order-taking application service
// => executes the statement above; continues to next line
{
    private readonly IDomainEventPublisher _publisher; // => injected at boot
    // => executes the statement above; continues to next line
 
    public PlaceOrderService(IDomainEventPublisher publisher) =>    // => constructor injection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
        _publisher = publisher; // => constructor injection; no service locator
        // => executes the statement above; continues to next line
 
    public OrderId PlaceOrder(string customerId, Money total)       // => command handler
    // => executes the statement above; continues to next line
    {
        var id = new OrderId(Guid.NewGuid().ToString()); // => fresh order id
        // => id: holds the result of the expression on the right
        _publisher.Publish(new OrderPlacedEvent(id.Value, total.CentAmount)); // => emit to bus
        // => Shipping reacts to event; PlaceOrderService never calls shipping directly
        return id; // => return to HTTP adapter
        // => returns the result to the caller — caller receives this value
    }
}
 
// ── shipping hexagon ──────────────────────────────────────────────────────────
// Namespace: Shipping.Domain
// => References OrderPlacedEvent DTO only; never OrderTaking.Domain.Order
public record TrackingId(string Value);        // => shipping's own identity type
// => executes the statement above; continues to next line
public record Shipment(TrackingId Id, string OrderId, string Status);  // => shipping aggregate
// => OrderId here is plain string from event; not order-taking's OrderId record
 
// Event handler adapter: subscribes to bus, calls shipping application port
public class OrderPlacedEventHandler  // => inbound adapter; shipping hexagon
// => executes the statement above; continues to next line
{
    public void Handle(OrderPlacedEvent evt)                         // => receives event; translates
    // => executes the statement above; continues to next line
    {
        var trackingId = new TrackingId(Guid.NewGuid().ToString()); // => generate tracking id
        // => trackingId: holds the result of the expression on the right
        var shipment = new Shipment(trackingId, evt.OrderId, "Pending"); // => domain object
        // => ShipmentRepository port called here (omitted for brevity)
        Console.WriteLine($"Shipping: created shipment {shipment.Id.Value}"); // => Output: Shipping: created shipment <guid>
        // => shipment.Id.Value: GUID string; unique per shipment
    }
}

import java.math.BigDecimal;
// => executes the statement above; continues to next line
import java.util.Optional;
 
// ── Shared Kernel: Money used by both order-taking and inventory ───────────────
// => Placed in a shared-kernel module; both contexts depend on it
// => Changes to Money require coordinated agreement between both teams
record Money(BigDecimal amount, String currency) {
// => record Money: immutable value type; equals/hashCode/toString generated by compiler
    Money {
    // => executes the statement above; continues to next line
        if (amount.signum() < 0) throw new IllegalArgumentException("negative money"); // => guard
        // => Shared kernel types carry shared invariants; both contexts enforce them
    }
}
 
// ── Customer/Supplier: order-taking (customer) calls pricing (supplier) ────────
// Pricing upstream publishes its own DTO; order-taking must not share it as-is
// => Anti-Corruption Layer adapter translates pricing response to order-taking types
 
// Pricing supplier's DTO (as-is from pricing context — order-taking cannot change it)
record PricingResponseDto(String itemCode, double priceUsd) {} // => upstream schema; read-only
 
// ACL output port: order-taking's view of what "get price" means
// => Returns Money (order-taking domain type); caller never sees PricingResponseDto
interface PricePort {
// => interface PricePort: contract definition — no implementation details here
    Optional<Money> getPrice(String itemCode); // => domain return type; no pricing DTO leaks
    // => Adapter translates double→BigDecimal, usd→currency string, missing→empty
}
 
// ACL adapter: wraps pricing HTTP client; translates DTO to order-taking domain type
class PricingAclAdapter implements PricePort {
// => PricingAclAdapter implements PricePort — satisfies the port contract
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public Optional<Money> getPrice(String itemCode) {
        // => In production: call pricing HTTP API, deserialise PricingResponseDto
        var dto = new PricingResponseDto(itemCode, 29.99); // => simulated upstream response
        // => dto: holds the result of the expression on the right
        var amount = BigDecimal.valueOf(dto.priceUsd());  // => double→BigDecimal translation
        // => amount: holds the result of the expression on the right
        return Optional.of(new Money(amount, "USD"));     // => wrapped in domain value object
        // => Domain never sees PricingResponseDto; ACL absorbs all schema coupling
    }
}
 
// ── Conformist: reporting conforms to order-taking's published event ───────────
// Reporting uses OrderPlacedEvent exactly as published; no ACL needed
// => Conformist accepts upstream model changes without negotiation
record OrderPlacedEvent(String orderId, BigDecimal total, String currency) {}
// => reporting adapter deserialises this directly; no mapping, no translation layer
// => Risk: if order-taking changes this event, reporting must update immediately
 
class ReportingEventHandler {
// => class ReportingEventHandler: implementation — contains field declarations and methods below
    void handle(OrderPlacedEvent event) {
        // => Direct use of event fields; no translation; this IS the conformist pattern
        System.out.printf("Report: order %s total %s %s%n",
        // => executes the statement above; continues to next line
            event.orderId(), event.total(), event.currency()); // => Output: Report: order <id> total <amt> <ccy>
            // => method call: delegates to collaborator; result captured above
    }
}

import java.math.BigDecimal                                          // => BigDecimal for monetary amounts
 
// ── Shared Kernel ─────────────────────────────────────────────────────────────
// Both order-taking and inventory import this from shared-kernel module
// => Coordinated breaking change required to modify; not owned by one team
data class Money(val amount: BigDecimal, val currency: String) {     // => shared value object
    init { require(amount.signum() >= 0) { "negative money" } } // => shared invariant enforced
    // => Both contexts rely on this invariant; shared kernel keeps logic in one place
}
 
// ── Customer/Supplier ACL ─────────────────────────────────────────────────────
// Pricing upstream DTO: order-taking receives but cannot change this schema
data class PricingResponseDto(val itemCode: String, val priceUsd: Double) // => upstream contract
// => Double (not BigDecimal): legacy pricing API returns IEEE 754 float; ACL converts
 
// Output port: order-taking's own abstraction over "get a price"
fun interface PricePort {                                            // => SAM; application zone
    fun getPrice(itemCode: String): Money? // => returns domain Money; no DTO exposed
    // => null = not found; adapter handles pricing-side 404 transparently
}
 
// ACL adapter: translates upstream DTO to domain type
val pricingAclAdapter = PricePort { itemCode ->                      // => lambda implements SAM
    val dto = PricingResponseDto(itemCode, 29.99) // => simulated upstream call result
    Money(BigDecimal.valueOf(dto.priceUsd), "USD") // => translation: double→BigDecimal
    // => Domain only sees Money; pricing schema evolution is absorbed here
    // => BigDecimal.valueOf: exact conversion; avoids floating-point precision issues
}
 
// ── Conformist ────────────────────────────────────────────────────────────────
// Reporting receives event exactly as published; no mapping
data class OrderPlacedEvent(val orderId: String, val total: BigDecimal, val currency: String)
// => Conformist: reporting team accepts that order-taking owns this schema
// => no ACL, no translation; schema changes in order-taking immediately affect reporting
 
class ReportingEventHandler {                                        // => conformist; no ACL
    fun handle(event: OrderPlacedEvent) {                            // => direct field access; no mapping
        println("Report: order ${event.orderId} total ${event.total} ${event.currency}")
        // => Output: Report: order <id> total <amt> <ccy>
        // => No translation; this IS the conformist pattern — direct consumption
    }
}

using System;                                                         // => ArgumentException
 
// ── Shared Kernel ─────────────────────────────────────────────────────────────
// Placed in SharedKernel project; both OrderTaking and Inventory reference it
// => Breaking change to Money requires both teams to update simultaneously
public sealed record Money(decimal Amount, string Currency)  // => shared value object; sealed; immutable
// => executes the statement above; continues to next line
{
    public Money : this(Amount, Currency) // => primary constructor validation; runs at new()
    // => constructor: receives all dependencies — enables testing with any adapter implementation
    {
        if (Amount < 0) throw new ArgumentException("negative money"); // => shared invariant
        // => Both contexts enforce this rule via shared type — no duplication
        // => ArgumentException thrown at construction; no invalid Money possible
    }
}
 
// ── Customer/Supplier ACL ─────────────────────────────────────────────────────
// Pricing upstream DTO: order-taking cannot change this schema
public record PricingResponseDto(string ItemCode, double PriceUsd); // => upstream shape; read-only
// => double PriceUsd: pricing API uses IEEE 754 float; ACL converts to decimal
 
// Output port: order-taking's abstraction; returns domain Money, not upstream DTO
public interface IPricePort  // => application zone; no HTTP client import
// => executes the statement above; continues to next line
{                                                                     // => application zone interface
// => interface type: contract definition — no implementation details here
    Money? GetPrice(string itemCode); // => null = not found; domain type returned
    // => ACL adapter translates; domain service never knows DTO shape exists
    // => nullable: item not in catalog returns null; not exception
}
 
// ACL adapter: wraps pricing HTTP client, translates to domain types
public class PricingAclAdapter : IPricePort  // => ACL adapter; adapter zone only; no IPricePort knowledge in domain
// => executes the statement above; continues to next line
{
    public Money? GetPrice(string itemCode)  // => translate DTO to domain Money
    // => executes the statement above; continues to next line
    {
        var dto = new PricingResponseDto(itemCode, 29.99m); // => simulated upstream call
        // => dto: holds the result of the expression on the right
        return new Money((decimal)dto.PriceUsd, "USD");     // => double→decimal translation
        // => Domain shielded from upstream schema; ACL absorbs all pricing coupling
        // => (decimal)dto.PriceUsd: explicit cast; precision acceptable for prices
    }
}
 
// ── Conformist ────────────────────────────────────────────────────────────────
// Reporting conforms to order-taking's published event; no ACL, no translation
public sealed record OrderPlacedEvent(string OrderId, decimal Total, string Currency);  // => conformist DTO
// => Conformist accepts event schema owned by order-taking; no negotiation
// => sealed: immutable event; cannot be subclassed; value equality
 
public class ReportingEventHandler  // => conformist; no ACL; direct consumption
// => executes the statement above; continues to next line
{
    public void Handle(OrderPlacedEvent evt)  // => event handler; uses publisher's field names
    // => executes the statement above; continues to next line
    {
        Console.WriteLine($"Report: order {evt.OrderId} total {evt.Total} {evt.Currency}");  // => log/display
        // => Output: Report: order <id> total <amt> <ccy>
        // => No translation layer; conformist uses upstream model directly
        // => evt.OrderId, evt.Total: order-taking's names; conformist accepts without renaming
    }
}

// File: shared-kernel/src/main/java/module-info.java
// => Java module system enforces that only exported packages can be imported
// => shared-kernel exports exactly three packages; nothing else crosses contexts
module com.example.sharedkernel {
// => executes the statement above; continues to next line
    exports com.example.sharedkernel.identity;  // => CustomerId, OrderId types
    // => executes the statement above; continues to next line
    exports com.example.sharedkernel.money;     // => Money value object
    // => executes the statement above; continues to next line
    exports com.example.sharedkernel.address;   // => Address value object
    // => Both order-taking and shipping modules declare: requires com.example.sharedkernel;
    // => They never declare: requires com.example.ordertaking; (cross-context import forbidden)
}
 
// File: shared-kernel/src/main/java/com/example/sharedkernel/money/Money.java
package com.example.sharedkernel.money;
// => executes the statement above; continues to next line
import java.math.BigDecimal;
// => executes the statement above; continues to next line
import java.util.Objects;
 
// Shared kernel type: immutable, framework-free, owned by all participating teams
// => Changes here require coordinated release across order-taking AND shipping
public record Money(BigDecimal amount, String currency) {
// => record Money: immutable value type; equals/hashCode/toString generated by compiler
    public Money {
    // => executes the statement above; continues to next line
        Objects.requireNonNull(amount, "amount required");    // => null guard
        // => method call: delegates to collaborator; result captured above
        Objects.requireNonNull(currency, "currency required"); // => null guard
        // => method call: delegates to collaborator; result captured above
        if (amount.signum() < 0) throw new IllegalArgumentException("negative amount"); // => invariant
        // => Invariant lives here once; all contexts inherit it automatically
    }
    public Money add(Money other) {
    // => add: method entry point — see implementation below
        if (!currency.equals(other.currency)) throw new IllegalArgumentException("currency mismatch"); // => guard
        // => conditional branch: execution path depends on condition above
        return new Money(amount.add(other.amount), currency); // => returns new Money; immutable
        // => returns the result to the caller — caller receives this value
    }
}
 
// File: shared-kernel/src/main/java/com/example/sharedkernel/identity/CustomerId.java
package com.example.sharedkernel.identity;
// => CustomerId: both order-taking and shipping use same customer identity concept
public record CustomerId(String value) {
// => record CustomerId: immutable value type; equals/hashCode/toString generated by compiler
    public CustomerId { if (value == null || value.isBlank()) throw new IllegalArgumentException("blank id"); }
    // => Validation in record compact constructor; runs on every construction
}

// File: shared-kernel/build.gradle.kts
// => Separate Gradle subproject; both order-taking and shipping list it as a dependency
plugins { kotlin("jvm") }                                            // => apply Kotlin JVM plugin
 
// order-taking/build.gradle.kts and shipping/build.gradle.kts both declare:
// dependencies { implementation(project(":shared-kernel")) }
// => Neither context lists the other as a dependency — only shared-kernel
 
// File: shared-kernel/src/main/kotlin/Money.kt
package com.example.sharedkernel                                     // => shared kernel package
 
// data class: structural equality; immutable; no framework annotation
// => All participating contexts import this; changes are coordinated breaking changes
data class Money(val amount: java.math.BigDecimal, val currency: String) {  // => shared value object
// => class Money: implementation — contains field declarations and methods below
    init {                                                           // => validation at construction
    // => executes the statement above; continues to next line
        require(amount.signum() >= 0) { "negative amount" } // => invariant; throws if violated
        // => method call: delegates to collaborator; result captured above
        require(currency.isNotBlank()) { "blank currency" }  // => guard against empty string
        // => Both order-taking and shipping inherit these guards automatically
    }
    operator fun plus(other: Money): Money {                         // => currency-safe addition
    // => plus: method entry point — see implementation below
        require(currency == other.currency) { "currency mismatch" } // => guard
        // => method call: delegates to collaborator; result captured above
        return copy(amount = amount + other.amount)                 // => immutable addition
        // => Returns new Money; original unchanged; functional style
    }
}
 
// File: shared-kernel/src/main/kotlin/CustomerId.kt
package com.example.sharedkernel
// => CustomerId: stable identity; shared by both contexts via this module
data class CustomerId(val value: String) {                           // => shared identity type
// => class CustomerId: implementation — contains field declarations and methods below
    init { require(value.isNotBlank()) { "blank customer id" } } // => guard at construction
    // => Contexts use CustomerId; they do NOT import each other's domain types
}

// File: SharedKernel/SharedKernel.csproj
// => Separate .csproj; OrderTaking.csproj and Shipping.csproj both reference it:
// <ProjectReference Include="../SharedKernel/SharedKernel.csproj" />
// => Neither project references the other — only SharedKernel
// => this pattern: shared kernel as NuGet-style internal package
 
// File: SharedKernel/Money.cs
namespace SharedKernel;                                              // => shared namespace
 
// sealed record: immutable, value equality, cannot be subclassed
// => Changes here are coordinated breaking changes; all teams must agree
public sealed record Money(decimal Amount, string Currency)          // => shared value object
// => executes the statement above; continues to next line
{
    public Money : this(Amount, Currency) // => validate in primary constructor
    // => constructor: receives all dependencies — enables testing with any adapter implementation
    {                                                                 // => validation on construction
    // => executes the statement above; continues to next line
        if (Amount < 0) throw new ArgumentException("negative amount"); // => shared invariant
        // => conditional branch: execution path depends on condition above
        if (string.IsNullOrWhiteSpace(Currency)) throw new ArgumentException("blank currency"); // => guard
        // => Every context constructing Money gets these guards automatically
    }
 
    public Money Add(Money other)                                     // => currency-safe addition
    // => executes the statement above; continues to next line
    {
        if (Currency != other.Currency) throw new InvalidOperationException("currency mismatch"); // => guard
        // => conditional branch: execution path depends on condition above
        return this with { Amount = Amount + other.Amount }; // => non-destructive mutation
        // => Returns new record; original unchanged; immutable pattern
    }
}
 
// File: SharedKernel/CustomerId.cs
namespace SharedKernel;                                              // => same shared namespace
// => Both OrderTaking and Shipping import this type; never each other's types
public sealed record CustomerId(string Value)                        // => shared identity type
// => executes the statement above; continues to next line
{
    public CustomerId : this(Value) // => validation in primary constructor
    // => constructor: receives all dependencies — enables testing with any adapter implementation
    {                                                                 // => validation at construction
    // => executes the statement above; continues to next line
        if (string.IsNullOrWhiteSpace(Value)) throw new ArgumentException("blank id"); // => guard
        // => Stable type; any change requires coordinated update across all contexts
    }
}

import java.util.Optional;
 
// ── Legacy system client types (external; we do not control these) ─────────────
// => These types come from the legacy system's SDK or are deserialized from its API
// => Field names, types, and semantics are all legacy conventions — not ours
class LegacyOrderResponse {
// => class LegacyOrderResponse: implementation — contains field declarations and methods below
    public String order_ref;          // => snake_case; legacy naming convention
    // => executes the statement above; continues to next line
    public int    price_in_cents;     // => integer cents; no currency field
    // => executes the statement above; continues to next line
    public String billing_addr;       // => billing address as flat string
    // => executes the statement above; continues to next line
    public String shipping_addr;      // => may be null if not separately specified
    // => Legacy system returns null shipping_addr when billing = shipping
}
 
// ── Domain types (we own these; no legacy dependency allowed here) ─────────────
record OrderId(String value) {}
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
record Money(long centAmount, String currency) {}  // => our currency-aware type
// => record Money: immutable value type; equals/hashCode/toString generated by compiler
record Address(String formatted) {}               // => our typed address
// => record Address: immutable value type; equals/hashCode/toString generated by compiler
record OrderData(OrderId id, Money total, Address shippingAddress) {} // => domain aggregate DTO
// => record OrderData: immutable value type; equals/hashCode/toString generated by compiler
class OrderNotFound extends RuntimeException {
// => OrderNotFound extends RuntimeException — inherits base behaviour
    OrderNotFound(String ref) { super("order not found: " + ref); } // => domain exception
    // => executes the statement above; continues to next line
}
 
// ── Output port: domain's view of "load order data" ───────────────────────────
// => Returns domain types; caller sees nothing of the legacy world
interface OrderDataPort {
// => interface OrderDataPort: contract definition — no implementation details here
    Optional<OrderData> findByRef(String ref); // => Optional signals possible absence
    // => Throws OrderNotFound on definitive 404; returns empty on transient unavailability
}
 
// ── ACL adapter: wraps legacy client; translates to domain types ───────────────
class LegacyOrderSystemAclAdapter implements OrderDataPort {
// => LegacyOrderSystemAclAdapter implements OrderDataPort — satisfies the port contract
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public Optional<OrderData> findByRef(String ref) {
        // => In production: HTTP call to legacy system; here we simulate a response
        if ("UNKNOWN".equals(ref)) {
        // => conditional branch: execution path depends on condition above
            throw new OrderNotFound(ref); // => HTTP 404 from legacy → domain exception
            // => Domain never sees HTTP status codes; ACL translates them
        }
 
        var legacy = new LegacyOrderResponse();     // => simulated legacy response
        // => legacy: holds the result of the expression on the right
        legacy.order_ref      = ref;                // => snake_case field assignment
        // => executes the statement above; continues to next line
        legacy.price_in_cents = 4999;              // => 49.99 USD in legacy format
        // => executes the statement above; continues to next line
        legacy.billing_addr   = "123 Main St";     // => billing address always present
        // => executes the statement above; continues to next line
        legacy.shipping_addr  = null;               // => null means billing = shipping
 
        // Translation step 1: rename field and type-wrap id
        var id = new OrderId(legacy.order_ref);    // => order_ref → OrderId value object
 
        // Translation step 2: integer cents → Money value object with currency
        var money = new Money(legacy.price_in_cents, "USD"); // => add explicit currency
        // => Legacy has no currency; ACL hardcodes USD as business rule from legacy docs
 
        // Translation step 3: null shipping_addr → fall back to billing address
        var shipping = Optional.ofNullable(legacy.shipping_addr)
        // => shipping: holds the result of the expression on the right
            .orElse(legacy.billing_addr);          // => default rule documented here
            // => method call: delegates to collaborator; result captured above
        var address = new Address(shipping);        // => wrapped in domain type
        // => address: holds the result of the expression on the right
 
        return Optional.of(new OrderData(id, money, address)); // => domain aggregate DTO returned
        // => Caller sees only domain types; legacy schema is fully absorbed by this adapter
    }
}
 
// ── Usage: application service calls port; knows nothing of legacy ─────────────
class GetOrderService {
// => class GetOrderService: implementation — contains field declarations and methods below
    private final OrderDataPort port; // => injected at boot; adapter wired here
    // => port: OrderDataPort — final field; assigned once in constructor; immutable reference
    GetOrderService(OrderDataPort port) { this.port = port; }
    // => method call: delegates to collaborator; result captured above
 
    OrderData getOrder(String ref) {
    // => executes the statement above; continues to next line
        return port.findByRef(ref).orElseThrow(() -> new OrderNotFound(ref));
        // => Application service written purely against domain port
        // => Replacing the legacy system with a modern one = swap the adapter only
    }
}

// ── Legacy types (external; not our naming conventions) ───────────────────────
data class LegacyOrderResponse(
// => data class LegacyOrderResponse: value type; copy/equals/hashCode/toString auto-generated
    val order_ref: String,           // => snake_case; legacy convention
    // => executes the statement above; continues to next line
    val price_in_cents: Int,         // => integer; no currency; ACL adds "USD"
    // => executes the statement above; continues to next line
    val billing_addr: String,        // => always present; flat string
    // => executes the statement above; continues to next line
    val shipping_addr: String?       // => null means same as billing; ACL handles
    // => executes the statement above; continues to next line
)
// => LegacyOrderResponse: read-only from legacy SDK; we never modify this class
 
// ── Domain types ──────────────────────────────────────────────────────────────
data class OrderId(val value: String)                               // => typed identity; our convention
// => data class OrderId: value type; copy/equals/hashCode/toString auto-generated
data class Money(val centAmount: Long, val currency: String) // => we add currency; ACL adds USD
// => data class Money: value type; copy/equals/hashCode/toString auto-generated
data class Address(val formatted: String)                           // => typed address; our convention
// => data class Address: value type; copy/equals/hashCode/toString auto-generated
data class OrderData(val id: OrderId, val total: Money, val shippingAddress: Address)
// => domain aggregate DTO; no legacy field names; no snake_case
class OrderNotFound(ref: String) : RuntimeException("order not found: $ref") // => domain exception
 
// ── Output port ───────────────────────────────────────────────────────────────
fun interface OrderDataPort {
// => interface OrderDataPort: contract definition — no implementation details here
    fun findByRef(ref: String): OrderData? // => null = not found; domain type returned
    // => Throws OrderNotFound on definitive absence; never exposes legacy HTTP codes
    // => SAM interface; lambda adapter or class both work
}
 
// ── ACL adapter ───────────────────────────────────────────────────────────────
val legacyAclAdapter = OrderDataPort { ref ->
// => legacyAclAdapter: holds the result of the expression on the right
    if (ref == "UNKNOWN") throw OrderNotFound(ref) // => legacy 404 → domain exception
    // => ACL translates HTTP status to domain exception; application service unaware
 
    val legacy = LegacyOrderResponse(ref, 4999, "123 Main St", null) // => simulated legacy response
    // => legacy: holds the result of the expression on the right
    val id      = OrderId(legacy.order_ref)                           // => rename: order_ref → id
    // => id: holds the result of the expression on the right
    val money   = Money(legacy.price_in_cents.toLong(), "USD")        // => add currency; Int→Long
    // => money: holds the result of the expression on the right
    val address = Address(legacy.shipping_addr ?: legacy.billing_addr) // => null→billing fallback
    // => Every translation rule is documented inside this adapter; domain is clean
    // => ACL adapter: only class in codebase that knows both legacy and domain schemas
 
    OrderData(id, money, address) // => return domain aggregate DTO
    // => executes the statement above; continues to next line
}
 
// ── Application service: calls port; no legacy knowledge ─────────────────────
class GetOrderService(private val port: OrderDataPort) {
    // => port injected; legacy adapter or modern adapter — service is unaware
    fun getOrder(ref: String): OrderData =
    // => executes the statement above; continues to next line
        port.findByRef(ref) ?: throw OrderNotFound(ref) // => null → domain exception
    // => ?: null coalescing: null from port → throw domain exception
    // => Swapping legacy system for modern API = replace legacyAclAdapter with new impl
}

using System;                                                         // => Exception base class
 
// ── Legacy types (external DTO; not our naming conventions) ──────────────────
public class LegacyOrderResponse  // => external; we cannot change this class; SDK type
// => executes the statement above; continues to next line
{                                                                     // => mutable class; legacy convention
// => class type: implementation — contains field declarations and methods below
    public string order_ref { get; set; } = "";      // => snake_case; legacy naming
    // => executes the statement above; continues to next line
    public int    price_in_cents { get; set; }        // => integer; no currency field
    // => executes the statement above; continues to next line
    public string billing_addr { get; set; } = "";   // => always present in legacy
    // => executes the statement above; continues to next line
    public string? shipping_addr { get; set; }        // => null means billing = shipping
    // => all fields reflect legacy API contract; ACL adapter translates to our types
}
 
// ── Domain types ──────────────────────────────────────────────────────────────
public sealed record OrderId(string Value);                           // => typed identity
// => executes the statement above; continues to next line
public sealed record Money(long CentAmount, string Currency); // => we carry currency; legacy has no currency
// => executes the statement above; continues to next line
public sealed record Address(string Formatted);                       // => our typed address; not legacy string
// => executes the statement above; continues to next line
public sealed record OrderData(OrderId Id, Money Total, Address ShippingAddress);  // => domain DTO
// => all four records: pure C#; no [Table], no EF annotation; domain stays clean
public class OrderNotFoundException : Exception  // => domain exception; not HTTP exception
// => executes the statement above; continues to next line
{                                                                     // => inherits Exception; no HttpException
// => executes the statement above; continues to next line
    public OrderNotFoundException(string r) : base($"order not found: {r}") {} // => domain ex
    // => application layer catches this; HTTP adapter maps to 404
}                                                                     // => simple domain exception; no HTTP status code
 
// ── Output port ───────────────────────────────────────────────────────────────
public interface IOrderDataPort  // => application zone; no legacy types; no HTTP
// => executes the statement above; continues to next line
{                                                                     // => output port interface
// => interface type: contract definition — no implementation details here
    OrderData? FindByRef(string reference); // => null = not found; domain return type
    // => Application layer calls this; never sees legacy types or HTTP status codes
    // => ACL adapter implements; modern adapter could replace it
}
 
// ── ACL adapter: translates legacy to domain ──────────────────────────────────
public class LegacyOrderSystemAclAdapter : IOrderDataPort  // => adapter zone; translation
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    public OrderData? FindByRef(string reference)  // => translate or throw domain exception
    // => executes the statement above; continues to next line
    {
    // => operation completes; execution continues to next statement
        if (reference == "UNKNOWN")               // => legacy 404 → domain exception
        // => conditional branch: execution path depends on condition above
            throw new OrderNotFoundException(reference); // => 404 → domain exception
        // => HTTP status code absorbed here; application layer sees only domain exceptions
 
        var legacy = new LegacyOrderResponse           // => simulated legacy response
        // => legacy: holds the result of the expression on the right
        {                                               // => object initializer; all fields set
        // => executes the statement above; continues to next line
            order_ref      = reference,                 // => string id from legacy
            // => executes the statement above; continues to next line
            price_in_cents = 4999,                     // => 49.99 in integer cents
            // => executes the statement above; continues to next line
            billing_addr   = "123 Main St",             // => always present
            // => executes the statement above; continues to next line
            shipping_addr  = null                       // => null → billing fallback rule
            // => executes the statement above; continues to next line
        };
        // => operation completes; execution continues to next statement
 
        var id      = new OrderId(legacy.order_ref);   // => rename snake_case field; wrap in type
        // => id: holds the result of the expression on the right
        var money   = new Money(legacy.price_in_cents, "USD"); // => add currency; int→long
        // => money: holds the result of the expression on the right
        var addr    = legacy.shipping_addr ?? legacy.billing_addr; // => null→billing fallback
        // => addr: holds the result of the expression on the right
        var address = new Address(addr);                // => wrapped in domain type
        // => address: holds the result of the expression on the right
 
        return new OrderData(id, money, new Address(addr)); // => domain aggregate DTO
        // => Caller receives only domain types; legacy schema entirely hidden
        // => addr: non-null because billing_addr is always present in legacy
    }
    // => operation completes; execution continues to next statement
}
 
// ── Application service ────────────────────────────────────────────────────────
public class GetOrderService  // => application service; no legacy knowledge
// => executes the statement above; continues to next line
{
    private readonly IOrderDataPort _port; // => injected; adapter provided at startup
    // => executes the statement above; continues to next line
    public GetOrderService(IOrderDataPort port) => _port = port;  // => constructor injection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
 
    public OrderData GetOrder(string reference) =>                // => expression body
    // => executes the statement above; continues to next line
        _port.FindByRef(reference) ?? throw new OrderNotFoundException(reference);
        // => ?? throw: C# null-coalescing throw; compact null-safety
        // => Domain service unaware of legacy system; adapter swap = zero service change
}

import java.math.BigDecimal;
// => executes the statement above; continues to next line
import java.util.List;
 
// ── Publisher side: order-taking publishes this as its public language ─────────
// => Version field enables consumers to detect schema evolution
// => All fields are stable; adding optional fields is non-breaking; removing is breaking
record OrderPlacedEventV1(
// => executes the statement above; continues to next line
    int     version,        // => always 1 for this schema generation; consumers check this
    // => executes the statement above; continues to next line
    String  orderId,        // => stable; will not be renamed in v1
    // => executes the statement above; continues to next line
    BigDecimal totalAmount, // => stable; BigDecimal serialises as JSON number
    // => executes the statement above; continues to next line
    String  currency,       // => ISO 4217 currency code; stable
    // => executes the statement above; continues to next line
    List<String> itemIds    // => list of item ids; may grow; consumers must handle additions
    // => executes the statement above; continues to next line
) {}
 
// => order-taking serialises this to JSON and publishes to event bus
// => Schema is documented in OpenAPI or JSON Schema and versioned in a schema registry
 
// ── Consumer side: shipping uses ACL to map event to its own domain types ──────
// Shipping's own domain concept of a received order
record ShippingOrderReceived(
// => executes the statement above; continues to next line
    String      shipmentRef,  // => shipping's own id concept; different from orderId
    // => executes the statement above; continues to next line
    BigDecimal  declaredValue, // => shipping uses "declared value" not "total amount"
    // => executes the statement above; continues to next line
    String      currencyCode  // => same concept, different field name in shipping domain
    // => executes the statement above; continues to next line
) {}
 
// Shipping's ACL port: receives published language event, returns shipping domain type
interface OrderEventPort {
// => interface OrderEventPort: contract definition — no implementation details here
    ShippingOrderReceived toShippingOrder(OrderPlacedEventV1 event);
    // => Mapping is explicit; shipping domain never exposes OrderPlacedEventV1 beyond this layer
}
 
// Shipping's ACL adapter: translates published language to shipping domain type
class OrderPlacedAclAdapter implements OrderEventPort {
// => OrderPlacedAclAdapter implements OrderEventPort — satisfies the port contract
    @Override
    // => @Override: compiler verifies this method signature matches the interface
    public ShippingOrderReceived toShippingOrder(OrderPlacedEventV1 event) {
    // => toShippingOrder: method entry point — see implementation below
        if (event.version() != 1) throw new IllegalArgumentException("unsupported event version: " + event.version());
        // => Version check: adapter rejects unknown versions; consumer is not silently broken
        return new ShippingOrderReceived(
        // => returns the result to the caller — caller receives this value
            "SHIP-" + event.orderId(),    // => orderId → shipmentRef with shipping prefix
            // => method call: delegates to collaborator; result captured above
            event.totalAmount(),           // => totalAmount → declaredValue (renamed concept)
            // => method call: delegates to collaborator; result captured above
            event.currency()               // => currency → currencyCode (renamed field)
            // => method call: delegates to collaborator; result captured above
        );
        // => Shipping domain uses ShippingOrderReceived; never sees OrderPlacedEventV1
    }
}
 
// ── Usage: shipping event handler invokes ACL, works with domain type only ─────
class ShippingEventHandler {
// => class ShippingEventHandler: implementation — contains field declarations and methods below
    private final OrderEventPort acl; // => injected; adapter wired at boot
    // => acl: OrderEventPort — final field; assigned once in constructor; immutable reference
    ShippingEventHandler(OrderEventPort acl) { this.acl = acl; }
    // => method call: delegates to collaborator; result captured above
 
    void handle(OrderPlacedEventV1 event) {
    // => handle: method entry point — see implementation below
        var received = acl.toShippingOrder(event);        // => translate via ACL
        // => received: holds the result of the expression on the right
        System.out.println("Shipping received: " + received.shipmentRef()); // => Output: Shipping received: SHIP-<orderId>
        // => All subsequent processing uses ShippingOrderReceived; ACL boundary maintained
    }
}

import java.math.BigDecimal                                          // => BigDecimal for money amounts
 
// ── Publisher side: order-taking's published language DTO ─────────────────────
data class OrderPlacedEventV1(                                       // => versioned published language DTO
// => data class OrderPlacedEventV1: value type; copy/equals/hashCode/toString auto-generated
    val version: Int,          // => 1 for this generation; consumers validate
    // => executes the statement above; continues to next line
    val orderId: String,       // => stable field; schema guarantee
    // => executes the statement above; continues to next line
    val totalAmount: BigDecimal, // => BigDecimal; serialises cleanly to JSON
    // => executes the statement above; continues to next line
    val currency: String,      // => ISO 4217; stable
    // => executes the statement above; continues to next line
    val itemIds: List<String>  // => may have more items in future; consumers must handle
    // => executes the statement above; continues to next line
)
// => V1 suffix: version in class name signals this is a versioned contract
 
// ── Consumer side: shipping's own domain type ─────────────────────────────────
data class ShippingOrderReceived(                                    // => shipping's own domain type
// => data class ShippingOrderReceived: value type; copy/equals/hashCode/toString auto-generated
    val shipmentRef: String,    // => shipping concept; derived from orderId
    // => executes the statement above; continues to next line
    val declaredValue: BigDecimal, // => shipping term for total
    // => executes the statement above; continues to next line
    val currencyCode: String    // => shipping field name for currency
    // => executes the statement above; continues to next line
)
// => different field names: shipping's ubiquitous language; not order-taking's
 
// ACL port and adapter: translates published language to shipping domain
fun interface OrderEventPort {                                        // => SAM; application zone
// => interface OrderEventPort: contract definition — no implementation details here
    fun toShippingOrder(event: OrderPlacedEventV1): ShippingOrderReceived  // => translation function
    // => Explicit translation; shipping domain stays clean of publisher types
}
 
val orderEventAcl = OrderEventPort { event ->                        // => lambda ACL adapter
// => orderEventAcl: holds the result of the expression on the right
    require(event.version == 1) { "unsupported event version: ${event.version}" }  // => version guard
    // => Version guard: adapter fails fast on unknown schema; no silent breakage
    ShippingOrderReceived(                                           // => construct shipping domain object
    // => executes the statement above; continues to next line
        shipmentRef    = "SHIP-${event.orderId}", // => orderId → shipmentRef with prefix
        // => executes the statement above; continues to next line
        declaredValue  = event.totalAmount,        // => rename: totalAmount → declaredValue
        // => executes the statement above; continues to next line
        currencyCode   = event.currency            // => rename: currency → currencyCode
        // => executes the statement above; continues to next line
    ) // => returns shipping domain type; publisher DTO absorbed at this boundary
    // => executes the statement above; continues to next line
}
 
// Event handler: calls ACL, works with domain type only
class ShippingEventHandler(private val acl: OrderEventPort) {        // => inbound adapter; handler
// => class ShippingEventHandler: implementation — contains field declarations and methods below
    fun handle(event: OrderPlacedEventV1) {                          // => handles published event
    // => handle: method entry point — see implementation below
        val received = acl.toShippingOrder(event)   // => translate at boundary; ACL absorbs schema
        // => received: holds the result of the expression on the right
        println("Shipping received: ${received.shipmentRef}") // => Output: Shipping received: SHIP-<orderId>
        // => Handler works with ShippingOrderReceived; publisher schema fully hidden
        // => ShipmentRepository port would be called here in production
    }
}

using System;                                                         // => InvalidOperationException
// => executes the statement above; continues to next line
using System.Collections.Generic;                                     // => IReadOnlyList
 
// ── Publisher side: order-taking's published language event DTO ───────────────
public sealed record OrderPlacedEventV1(  // => versioned; V1 in name signals schema version
// => executes the statement above; continues to next line
    int Version,             // => always 1; consumers check before mapping
    // => executes the statement above; continues to next line
    string OrderId,          // => stable; guaranteed by publisher
    // => executes the statement above; continues to next line
    decimal TotalAmount,     // => decimal for money; stable type
    // => executes the statement above; continues to next line
    string Currency,         // => ISO 4217; stable
    // => executes the statement above; continues to next line
    IReadOnlyList<string> ItemIds // => list; may grow; consumers handle additions gracefully
    // => executes the statement above; continues to next line
);
// => sealed: no subclassing; schema is the contract; all fields required
// => IReadOnlyList<string> ItemIds: can be empty; future versions may add more
 
// ── Consumer side: shipping's own domain type ─────────────────────────────────
public sealed record ShippingOrderReceived(  // => shipping's domain type; not order-taking's
// => executes the statement above; continues to next line
    string ShipmentRef,      // => shipping concept; derived from OrderId
    // => executes the statement above; continues to next line
    decimal DeclaredValue,   // => shipping term for monetary value
    // => executes the statement above; continues to next line
    string CurrencyCode      // => shipping field name; matches ISO 4217
    // => executes the statement above; continues to next line
);
// => different field names: shipping's ubiquitous language; no orderId, totalAmount
 
// ACL port: translates published language to shipping domain type
public interface IOrderEventPort  // => application zone; no publisher type visible in domain
// => executes the statement above; continues to next line
{
    ShippingOrderReceived ToShippingOrder(OrderPlacedEventV1 evt);  // => translate at boundary
    // => Caller receives ShippingOrderReceived; never touches OrderPlacedEventV1 again
}
 
// ACL adapter implementation
public class OrderPlacedAclAdapter : IOrderEventPort  // => ACL adapter; adapter zone; translation only
// => executes the statement above; continues to next line
{                                                                     // => only class knowing both schemas
// => class knowing: implementation — contains field declarations and methods below
    public ShippingOrderReceived ToShippingOrder(OrderPlacedEventV1 evt)  // => translate V1→shipping
    // => executes the statement above; continues to next line
    {
        if (evt.Version != 1)                           // => version guard; fail fast
        // => conditional branch: execution path depends on condition above
            throw new InvalidOperationException($"unsupported event version: {evt.Version}");  // => fatal
        // => Version check at adapter boundary; consumer fails fast, not silently
        // => throw: not return null; unknown version is fatal, not recoverable
 
        return new ShippingOrderReceived(               // => construct shipping domain type
        // => returns the result to the caller — caller receives this value
            ShipmentRef   : $"SHIP-{evt.OrderId}",  // => orderId → prefixed shipment ref
            // => executes the statement above; continues to next line
            DeclaredValue : evt.TotalAmount,         // => totalAmount → shipping term
            // => executes the statement above; continues to next line
            CurrencyCode  : evt.Currency             // => currency → shipping field name
            // => executes the statement above; continues to next line
        ); // => shipping domain type; publisher DTO absorbed entirely
        // => named args: C# initializer with arg names for clarity
    }
}
 
// Event handler: uses ACL, works only with shipping domain type
public class ShippingEventHandler  // => inbound adapter; shipping hexagon
// => executes the statement above; continues to next line
{                                                                     // => event handler; subscribes to bus
// => executes the statement above; continues to next line
    private readonly IOrderEventPort _acl; // => injected; adapter wired at startup
    // => executes the statement above; continues to next line
    public ShippingEventHandler(IOrderEventPort acl) => _acl = acl;  // => constructor injection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
 
    public void Handle(OrderPlacedEventV1 evt)  // => receives published event; calls ACL
    // => executes the statement above; continues to next line
    {                                                                 // => call ACL then work with domain type
    // => executes the statement above; continues to next line
        var received = _acl.ToShippingOrder(evt);                // => translate at ACL boundary
        // => received: holds the result of the expression on the right
        Console.WriteLine($"Shipping received: {received.ShipmentRef}"); // => Output: Shipping received: SHIP-<orderId>
        // => All downstream processing uses ShippingOrderReceived; schema boundary maintained
        // => received.ShipmentRef: shipping-side name; never evt.OrderId
    }
}

import java.time.Instant;                             // => Instant: UTC timestamp for event occurrence
// => executes the statement above; continues to next line
import java.util.ArrayList;                           // => ArrayList: mutable event list for store
// => executes the statement above; continues to next line
import java.util.HashMap;                             // => HashMap: stream-id to event list mapping
// => executes the statement above; continues to next line
import java.util.List;                                // => List: ordered event collection
// => executes the statement above; continues to next line
import java.util.Map;                                 // => Map: type for streams and versions fields
// => executes the statement above; continues to next line
import java.util.Optional;                            // => Optional: unused here; imported for completeness
 
// ── Domain event base type ────────────────────────────────────────────────────
// => All domain events implement this marker interface
// => Sealing events with sealed interface (Java 17+) lets switch be exhaustive
sealed interface DomainEvent permits OrderPlaced, OrderConfirmed {} // => two permitted subtypes
// => interface DomainEvent: contract definition — no implementation details here
record OrderPlaced(String orderId, long totalCents, Instant occurredAt) implements DomainEvent {} // => creation event
// => OrderPlaced implements DomainEvent — satisfies the port contract
record OrderConfirmed(String orderId, Instant confirmedAt) implements DomainEvent {} // => state-change event
 
// Domain aggregate: rebuilt from event stream
// => No @Entity, no database field; state computed from events
class Order {                                         // => aggregate shell; state rebuilt by apply()
// => class Order: implementation — contains field declarations and methods below
    private String id;                                // => mutable: set by OrderPlaced event
    // => id: String — injected dependency; implementation chosen at wiring time
    private long   totalCents;                        // => mutable: set by OrderPlaced event
    // => totalCents: long — injected dependency; implementation chosen at wiring time
    private String status = "NEW"; // => initial state before any event applied
 
    // Apply each event to rebuild state — called by the event store adapter
    // => Aggregate only reads events; it does not store or query them
    void apply(DomainEvent event) {                   // => mutates state based on event type
    // => apply: method entry point — see implementation below
        switch (event) {
        // => pattern match: exhaustive dispatch on all possible cases
            case OrderPlaced e    -> { id = e.orderId(); totalCents = e.totalCents(); status = "PLACED"; } // => OrderPlaced sets all fields
            // => method call: delegates to collaborator; result captured above
            case OrderConfirmed e -> { status = "CONFIRMED"; }        // => OrderConfirmed advances status
            // => pattern-matching switch; compiler ensures all sealed subtypes handled
        }
    }
 
    String getStatus() { return status; } // => readable state after replay
    // => executes the statement above; continues to next line
}
 
// ── Event store port ───────────────────────────────────────────────────────────
// => Two methods: append (write path) and read (load path)
// => expectedVersion: optimistic concurrency; -1 means "stream must not exist"
interface EventStorePort {                            // => output port; EventStore adapter implements this
// => EventStorePort implements this — satisfies the port contract
    void appendToStream(String streamId, int expectedVersion, List<DomainEvent> events); // => write path
    // => Throws ConcurrencyException if actual version != expectedVersion
    List<DomainEvent> readStream(String streamId);    // => read path; returns full event history
    // => Returns all events in order; empty list if stream does not exist
}
 
// ── In-memory adapter: used in tests and local development ────────────────────
// => InMemoryEventStore: implements EventStorePort; HashMap as backing store; no EventStoreDB needed
class InMemoryEventStore implements EventStorePort {  // => test adapter; zero infrastructure
// => InMemoryEventStore implements EventStorePort — satisfies the port contract
    private final Map<String, List<DomainEvent>> streams = new HashMap<>(); // => stream storage
    // => new HashMap(...): instantiates concrete implementation
    private final Map<String, Integer> versions = new HashMap<>();           // => version tracking
    // => new HashMap(...): instantiates concrete implementation
 
    @Override                                         // => implements appendToStream with optimistic concurrency
    // => @Override: compiler verifies this method signature matches the interface
    public void appendToStream(String streamId, int expectedVersion, List<DomainEvent> events) {
    // => appendToStream: method entry point — see implementation below
        int actual = versions.getOrDefault(streamId, -1); // => -1 if stream does not exist
        // => actual: holds the result of the expression on the right
        if (actual != expectedVersion) throw new IllegalStateException( // => concurrency guard
        // => conditional branch: execution path depends on condition above
            "concurrency conflict: expected " + expectedVersion + " got " + actual); // => guard message
            // => executes the statement above; continues to next line
        streams.computeIfAbsent(streamId, k -> new ArrayList<>()).addAll(events); // => create or append
        // => iteration: processes each element in the collection
        versions.put(streamId, actual + events.size()); // => advance version counter
        // => Version increments by number of events appended, not by 1
    }
 
    @Override                                         // => implements readStream; returns immutable copy
    // => @Override: compiler verifies this method signature matches the interface
    public List<DomainEvent> readStream(String streamId) {
    // => executes the statement above; continues to next line
        return List.copyOf(streams.getOrDefault(streamId, List.of())); // => immutable copy; empty if missing
        // => Returns empty list for unknown stream; callers treat empty as new aggregate
    }
}
 
// ── Application service: load → rebuild → apply command → append ──────────────
// => Two-step command: (1) load history from port; (2) rebuild aggregate; (3) emit new event; (4) append
class PlaceOrderService {
// => class PlaceOrderService: implementation — contains field declarations and methods below
    private final EventStorePort store; // => injected; adapter provided at boot
    // => store: EventStorePort — final field; assigned once in constructor; immutable reference
    PlaceOrderService(EventStorePort store) { this.store = store; } // => constructor injection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
 
    String placeOrder(long totalCents) {              // => creates new order stream
    // => executes the statement above; continues to next line
        var orderId = java.util.UUID.randomUUID().toString(); // => generate new stream id
        // => orderId: holds the result of the expression on the right
        var event = new OrderPlaced(orderId, totalCents, Instant.now()); // => domain event; immutable fact
        // => event: holds the result of the expression on the right
        store.appendToStream(orderId, -1, List.of(event)); // => -1: stream must not exist; creates stream
        // => Appending to version -1 creates the stream; any other version updates it
        return orderId; // => return new stream id to caller
        // => returns the result to the caller — caller receives this value
    }
 
    void confirmOrder(String orderId) {               // => adds OrderConfirmed to existing stream
    // => confirmOrder: method entry point — see implementation below
        var history = store.readStream(orderId);   // => load all events for this stream
        // => history: holds the result of the expression on the right
        var order = new Order();                   // => empty aggregate shell
        // => order: holds the result of the expression on the right
        history.forEach(order::apply);             // => replay events to rebuild state in memory
        // => order.status is now "PLACED" after replay
        var event = new OrderConfirmed(orderId, Instant.now()); // => new domain event
        // => event: holds the result of the expression on the right
        store.appendToStream(orderId, history.size() - 1, List.of(event)); // => optimistic lock version
        // => history.size()-1 is the expected version; prevents concurrent writes
    }
}
 
// ── Usage ──────────────────────────────────────────────────────────────────────
var store   = new InMemoryEventStore();            // => in-memory adapter for demo; no infrastructure
// => store: holds the result of the expression on the right
var service = new PlaceOrderService(store);        // => inject adapter into service
// => service: holds the result of the expression on the right
var id      = service.placeOrder(4999);            // => appends OrderPlaced event; stream created
// => id: holds the result of the expression on the right
service.confirmOrder(id);                          // => loads, rebuilds, appends OrderConfirmed
// => method call: delegates to collaborator; result captured above
System.out.println(store.readStream(id).size());   // => Output: 2 (two events in stream)
// => two events: [OrderPlaced, OrderConfirmed]; aggregate rebuilt by replaying both

import java.time.Instant                                             // => Instant for timestamps
// => executes the statement above; continues to next line
import java.util.UUID                                                // => UUID for id generation
 
// ── Domain events ─────────────────────────────────────────────────────────────
sealed interface DomainEvent                             // => sealed: compiler-enforced exhaustion
// => executes the statement above; continues to next line
data class OrderPlaced(val orderId: String, val totalCents: Long, val occurredAt: Instant) : DomainEvent
// => event carries all data needed; no aggregate loading required for replay
// => occurredAt: timestamp of occurrence; immutable historical fact
data class OrderConfirmed(val orderId: String, val confirmedAt: Instant) : DomainEvent
// => separate event type; different subscribers react differently
 
// Domain aggregate: rebuilt from events
// => No JPA, no database; state is a function of event history
class Order {                                                         // => mutable aggregate; rebuilt via apply
// => class Order: implementation — contains field declarations and methods below
    var status = "NEW"; private set // => private setter; only apply() mutates state
    // => status: holds the result of the expression on the right
    fun apply(event: DomainEvent) = when (event) {                   // => event sourcing pattern
    // => apply: method entry point — see implementation below
        is OrderPlaced    -> { status = "PLACED" }    // => state after OrderPlaced
        // => executes the statement above; continues to next line
        is OrderConfirmed -> { status = "CONFIRMED" } // => state after OrderConfirmed
        // => executes the statement above; continues to next line
    } // => when is exhaustive over sealed interface; compiler error if new event type added
    // => executes the statement above; continues to next line
}
 
// ── Event store port ───────────────────────────────────────────────────────────
interface EventStorePort {                                            // => application zone; no EventStore SDK
// => interface EventStorePort: contract definition — no implementation details here
    fun appendToStream(streamId: String, expectedVersion: Int, events: List<DomainEvent>)
    // => Throws IllegalStateException on concurrency conflict
    // => expectedVersion: current version before append; -1 for new stream
    fun readStream(streamId: String): List<DomainEvent>
    // => Empty list for unknown stream
    // => All events in order; caller rebuilds aggregate by folding
}
 
// ── In-memory adapter ─────────────────────────────────────────────────────────
class InMemoryEventStore : EventStorePort {                           // => test adapter; no EventStoreDB
// => class InMemoryEventStore: implementation — contains field declarations and methods below
    private val streams  = mutableMapOf<String, MutableList<DomainEvent>>() // => per-stream events list
    // => streams: val — injected dependency; implementation chosen at wiring time
    private val versions = mutableMapOf<String, Int>()                      // => per-stream version counter
    // => versions: val — injected dependency; implementation chosen at wiring time
 
    override fun appendToStream(streamId: String, expectedVersion: Int, events: List<DomainEvent>) {
    // => appendToStream: method entry point — see implementation below
        val actual = versions.getOrDefault(streamId, -1) // => -1 if stream does not exist
        // => actual: holds the result of the expression on the right
        check(actual == expectedVersion) { "concurrency conflict: expected $expectedVersion got $actual" }
        // => check: Kotlin assertion; throws IllegalStateException on mismatch
        streams.getOrPut(streamId) { mutableListOf() }.addAll(events) // => append all events
        // => iteration: processes each element in the collection
        versions[streamId] = actual + events.size // => advance version by event count
        // => Version tracks total events appended; enables optimistic concurrency
    }
 
    override fun readStream(streamId: String): List<DomainEvent> =   // => returns snapshot copy
    // => executes the statement above; continues to next line
        streams[streamId]?.toList() ?: emptyList() // => immutable copy; empty for unknown stream
        // => iteration: processes each element in the collection
}
 
// ── Application service ────────────────────────────────────────────────────────
class PlaceOrderService(private val store: EventStorePort) {         // => store injected; no EventStoreDB
// => class PlaceOrderService: implementation — contains field declarations and methods below
    fun placeOrder(totalCents: Long): String {                        // => command; appends event
    // => placeOrder: method entry point — see implementation below
        val id    = UUID.randomUUID().toString()                          // => new stream id
        // => id: holds the result of the expression on the right
        val event = OrderPlaced(id, totalCents, Instant.now())           // => domain event
        // => event: holds the result of the expression on the right
        store.appendToStream(id, -1, listOf(event))                      // => create new stream
        // => expectedVersion -1: stream must not exist; guard against duplicate placement
        return id                                                         // => return stream/order id
        // => returns the result to the caller — caller receives this value
    }
 
    fun confirmOrder(orderId: String) {                                // => command; loads and appends
    // => confirmOrder: method entry point — see implementation below
        val history = store.readStream(orderId)            // => load full event history
        // => history: holds the result of the expression on the right
        val order   = Order().also { o -> history.forEach(o::apply) } // => rebuild aggregate
        // => order.status == "PLACED" after replay; fold events into aggregate
        val event   = OrderConfirmed(orderId, Instant.now())           // => new event to append
        // => event: holds the result of the expression on the right
        store.appendToStream(orderId, history.size - 1, listOf(event)) // => optimistic lock
        // => history.size-1 is current version; concurrent write at same version fails
    }
}
 
// ── Usage ──────────────────────────────────────────────────────────────────────
val store   = InMemoryEventStore()                                   // => in-memory; no EventStoreDB
// => store: holds the result of the expression on the right
val service = PlaceOrderService(store)                               // => inject store
// => service: holds the result of the expression on the right
val id      = service.placeOrder(4999)             // => appends OrderPlaced; id = stream id
// => id: holds the result of the expression on the right
service.confirmOrder(id)                           // => loads stream; appends OrderConfirmed
// => method call: delegates to collaborator; result captured above
println(store.readStream(id).size)                 // => Output: 2; two events in stream
// => output: verification line — shows result in console

using System;                                                         // => Guid, DateTimeOffset
// => executes the statement above; continues to next line
using System.Collections.Generic;                                     // => Dictionary, List
// => executes the statement above; continues to next line
using System.Linq;                                                    // => AsReadOnly
 
// ── Domain events ─────────────────────────────────────────────────────────────
public abstract record DomainEvent;                                          // => base type; sealed subtype only
// => executes the statement above; continues to next line
public sealed record OrderPlaced(string OrderId, long TotalCents, DateTimeOffset OccurredAt) : DomainEvent;  // => placed
// => event carries all data; no aggregate loading needed for subscribers
public sealed record OrderConfirmed(string OrderId, DateTimeOffset ConfirmedAt) : DomainEvent;  // => confirmed
// => two event types; sealed prevents unintended subtypes
 
// Domain aggregate: rebuilt from event stream
// => No EF Core, no database attributes; state is computed from events
public class Order  // => mutable aggregate; rebuilt via Apply(); no EF attribute
// => executes the statement above; continues to next line
{                                                                     // => stateful; Apply() is the only mutator
// => executes the statement above; continues to next line
    public string Status { get; private set; } = "New"; // => initial state; private set
    // => executes the statement above; continues to next line
    public void Apply(DomainEvent evt) => evt switch    // => switch expression; pattern match
    // => executes the statement above; continues to next line
    {                                                   // => exhaustive; _ covers unknown events
    // => executes the statement above; continues to next line
        OrderPlaced    _ => Status = "Placed",          // => state after OrderPlaced
        // => _: holds the result of the expression on the right
        OrderConfirmed _ => Status = "Confirmed",       // => state after OrderConfirmed
        // => _: holds the result of the expression on the right
        _ => throw new InvalidOperationException($"unknown event {evt.GetType().Name}") // => guard
        // => method call: delegates to collaborator; result captured above
    };
    // => operation completes; execution continues to next statement
}
 
// ── Event store port ───────────────────────────────────────────────────────────
public interface IEventStorePort  // => application zone; no EventStoreDB SDK
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    void AppendToStream(string streamId, int expectedVersion, IReadOnlyList<DomainEvent> events);  // => write
    // => Throws InvalidOperationException on concurrency conflict
    // => expectedVersion: -1 for new streams; current version for existing
    IReadOnlyList<DomainEvent> ReadStream(string streamId);  // => read all events for stream
    // => Returns empty list for unknown stream; never null
}
 
// ── In-memory adapter ─────────────────────────────────────────────────────────
public class InMemoryEventStore : IEventStorePort  // => test adapter; no EventStoreDB; no network
// => executes the statement above; continues to next line
{                                                                     // => two maps: events and versions
// => executes the statement above; continues to next line
    private readonly Dictionary<string, List<DomainEvent>> _streams  = new(); // => per-stream events list
    // => executes the statement above; continues to next line
    private readonly Dictionary<string, int>               _versions = new(); // => per-stream version counter
    // => executes the statement above; continues to next line
 
    public void AppendToStream(string streamId, int expectedVersion, IReadOnlyList<DomainEvent> events)  // => write
    // => executes the statement above; continues to next line
    {                                                                 // => validate then append
    // => executes the statement above; continues to next line
        var actual = _versions.GetValueOrDefault(streamId, -1); // => -1 for new streams
        // => actual: holds the result of the expression on the right
        if (actual != expectedVersion)  // => optimistic concurrency check; mismatch = conflict
        // => conditional branch: execution path depends on condition above
            throw new InvalidOperationException($"concurrency conflict: expected {expectedVersion} got {actual}");  // => 409
        // => Optimistic concurrency guard; prevents two writers clobbering each other
        // => same semantics as EventStoreDB; test adapter is faithful
 
        if (!_streams.ContainsKey(streamId)) _streams[streamId] = new List<DomainEvent>(); // => init stream on first append
        // => conditional branch: execution path depends on condition above
        _streams[streamId].AddRange(events);                             // => append all events; order preserved
        // => method call: delegates to collaborator; result captured above
        _versions[streamId] = actual + events.Count;                    // => advance version by count
        // => executes the statement above; continues to next line
    }
    // => operation completes; execution continues to next statement
 
    public IReadOnlyList<DomainEvent> ReadStream(string streamId) =>   // => snapshot copy
    // => executes the statement above; continues to next line
        _streams.TryGetValue(streamId, out var evts) ? evts.AsReadOnly() : Array.Empty<DomainEvent>();  // => read-only
        // => Immutable view; empty array for unknown stream; no null return
}
 
// ── Application service ────────────────────────────────────────────────────────
public class PlaceOrderService  // => command handlers; no business logic beyond domain calls
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    private readonly IEventStorePort _store; // => injected at boot; no EventStoreDB import
    // => executes the statement above; continues to next line
    public PlaceOrderService(IEventStorePort store) => _store = store;  // => constructor injection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
 
    public string PlaceOrder(long totalCents)  // => command; appends event; returns stream id
    // => executes the statement above; continues to next line
    {
    // => operation completes; execution continues to next statement
        var id    = Guid.NewGuid().ToString();                              // => new stream id
        // => id: holds the result of the expression on the right
        var evt   = new OrderPlaced(id, totalCents, DateTimeOffset.UtcNow); // => domain event; UtcNow timestamp
        // => evt: holds the result of the expression on the right
        _store.AppendToStream(id, -1, new[] { evt });                      // => create stream; new[] literal
        // => expectedVersion -1: stream must not exist; creates fresh aggregate
        return id;                                                          // => return stream/order id
        // => returns the result to the caller — caller receives this value
    }
 
    public void ConfirmOrder(string orderId)  // => command; loads, replays, appends
    // => executes the statement above; continues to next line
    {
        var history = _store.ReadStream(orderId);          // => load all events; full stream
        // => history: holds the result of the expression on the right
        var order   = new Order();                         // => fresh aggregate; Status="New"
        // => order: holds the result of the expression on the right
        foreach (var e in history) order.Apply(e);        // => replay → rebuild aggregate; Status="Placed"
        // => order.Status == "Placed" after replay; ready for Confirm invariant check
        var evt = new OrderConfirmed(orderId, DateTimeOffset.UtcNow); // => new event; timestamp now
        // => evt: holds the result of the expression on the right
        _store.AppendToStream(orderId, history.Count - 1, new[] { evt }); // => optimistic lock
        // => history.Count-1 is current version; concurrent write at same version rejected
    }
}
 
// ── Usage ──────────────────────────────────────────────────────────────────────
var store   = new InMemoryEventStore();                              // => test adapter; no network
// => store: holds the result of the expression on the right
var service = new PlaceOrderService(store);                          // => inject
// => service: holds the result of the expression on the right
var id      = service.PlaceOrder(4999);          // => appends OrderPlaced; total=4999 cents
// => id: holds the result of the expression on the right
service.ConfirmOrder(id);                        // => loads stream; appends OrderConfirmed
// => method call: delegates to collaborator; result captured above
Console.WriteLine(store.ReadStream(id).Count);   // => Output: 2; two events in stream
// => output: verification line — shows result in console

import java.math.BigDecimal;                          // => BigDecimal: monetary amounts
// => executes the statement above; continues to next line
import java.time.Instant;                             // => Instant: event occurrence timestamp
// => executes the statement above; continues to next line
import java.util.ArrayList;                           // => ArrayList: mutable event log
// => executes the statement above; continues to next line
import java.util.HashMap;                             // => HashMap: projection backing store
// => executes the statement above; continues to next line
import java.util.List;                                // => List: event collection type
// => executes the statement above; continues to next line
import java.util.Map;                                 // => Map: type for viewStore
// => executes the statement above; continues to next line
import java.util.Optional;                            // => Optional: no-null for query result
 
// ── Shared event type (crossing command→query boundary via bus) ───────────────
// => OrderPlacedEvent: crosses the command→query bus boundary; flat DTO, no aggregate
record OrderPlacedEvent(String orderId, BigDecimal total, Instant placedAt) {} // => three fields
 
// ── Command-side ports ─────────────────────────────────────────────────────────
interface EventStorePort {                            // => command-side output port
// => interface EventStorePort: contract definition — no implementation details here
    void append(String streamId, OrderPlacedEvent event); // => write event to store
    // => Production: EventStoreDB or PostgreSQL events table
}
interface DomainEventPublisher {                      // => command-side output port for bus
// => interface DomainEventPublisher: contract definition — no implementation details here
    void publish(OrderPlacedEvent event); // => deliver event to bus; query side subscribes
    // => Production: Kafka topic or RabbitMQ exchange
}
 
// ── Command-side application service: writes event, publishes to bus ───────────
// => Depends only on command-side ports; knows nothing of query side
class PlaceOrderService {                             // => command service; write path only
// => class PlaceOrderService: implementation — contains field declarations and methods below
    private final EventStorePort       store;     // => injected command-side port
    // => store: EventStorePort — final field; assigned once in constructor; immutable reference
    private final DomainEventPublisher publisher; // => injected command-side port
    // => publisher: DomainEventPublisher — final field; assigned once in constructor; immutable reference
 
    PlaceOrderService(EventStorePort store, DomainEventPublisher publisher) { // => both injected
    // => executes the statement above; continues to next line
        this.store = store; this.publisher = publisher; // => constructor injection
        // => this.store stored — field holds injected store for method calls below
    }
 
    String placeOrder(BigDecimal total) {             // => write command; returns new id
    // => executes the statement above; continues to next line
        var id    = java.util.UUID.randomUUID().toString(); // => new order id
        // => id: holds the result of the expression on the right
        var event = new OrderPlacedEvent(id, total, Instant.now()); // => immutable domain event
        // => event: holds the result of the expression on the right
        store.append(id, event);      // => persist to event store first; source of truth
        // => method call: delegates to collaborator; result captured above
        publisher.publish(event);     // => then publish to bus; query side reacts asynchronously
        // => Transactional outbox pattern recommended in production to avoid loss
        return id; // => return to HTTP adapter; caller may use to query projection
        // => returns the result to the caller — caller receives this value
    }
}
 
// ── Query-side read model ──────────────────────────────────────────────────────
// => OrderView: flat DTO; never the same object as domain aggregate; query-optimised
record OrderView(String orderId, BigDecimal total, String status, Instant placedAt) {}
// => Flat DTO; denormalised; optimised for display; never used on command side
 
// ── Query-side ports ───────────────────────────────────────────────────────────
interface OrderViewRepository {                       // => query-side output port; separate from command ports
// => interface OrderViewRepository: contract definition — no implementation details here
    void save(OrderView view);        // => write projection; called by event handler on bus
    // => executes the statement above; continues to next line
    Optional<OrderView> findById(String orderId); // => read projection; called by query service
    // => executes the statement above; continues to next line
}
 
// ── Query-side event handler: subscribes to bus, updates projection ────────────
// => This is an inbound adapter on the query side
class OrderProjectionHandler {                        // => query-side adapter: subscribes to bus events
// => class OrderProjectionHandler: implementation — contains field declarations and methods below
    private final OrderViewRepository repo; // => injected query-side port
    // => repo: OrderViewRepository — final field; assigned once in constructor; immutable reference
    OrderProjectionHandler(OrderViewRepository repo) { this.repo = repo; } // => constructor injection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
 
    void handle(OrderPlacedEvent event) {             // => called by bus delivery; no command coupling
    // => handle: method entry point — see implementation below
        var view = new OrderView(event.orderId(), event.total(), "PLACED", event.placedAt()); // => translate to flat DTO
        // => Translate event to flat view; projection stores only what queries need
        repo.save(view); // => write to projection store; query side reads from here
        // => Projection handler knows only OrderViewRepository; not EventStorePort
    }
}
 
// ── Query-side application service: reads projection only ─────────────────────
// => Depends only on query-side ports; knows nothing of event store
class GetOrderService {                               // => query service; read path only
// => class GetOrderService: implementation — contains field declarations and methods below
    private final OrderViewRepository repo; // => injected query-side port
    // => repo: OrderViewRepository — final field; assigned once in constructor; immutable reference
    GetOrderService(OrderViewRepository repo) { this.repo = repo; } // => constructor injection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
 
    Optional<OrderView> getOrder(String id) {         // => read query; returns flat projection
    // => executes the statement above; continues to next line
        return repo.findById(id); // => read flat projection; no aggregate rebuild needed
        // => Query side is fast: reads one row from projection table, no event replay
    }
}
 
// ── In-memory adapters (wired together for demo) ──────────────────────────────
var viewStore = new HashMap<String, OrderView>();     // => projection backing store; empty initially
// => viewStore: holds the result of the expression on the right
OrderViewRepository viewRepo = new OrderViewRepository() { // => anonymous adapter; implements port
// => viewRepo: holds the result of the expression on the right
    public void save(OrderView v) { viewStore.put(v.orderId(), v); } // => upsert by orderId
    // => save: method entry point — see implementation below
    public Optional<OrderView> findById(String id) { return Optional.ofNullable(viewStore.get(id)); } // => lookup
    // => method call: delegates to collaborator; result captured above
};
var projectionHandler = new OrderProjectionHandler(viewRepo); // => query-side handler; wired to viewRepo
// => projectionHandler: holds the result of the expression on the right
var eventLog = new ArrayList<OrderPlacedEvent>();     // => in-memory event store; records appended events
// => eventLog: holds the result of the expression on the right
 
EventStorePort      storeAdapter   = (id, evt) -> eventLog.add(evt);       // => lambda adapter; records events
// => storeAdapter: holds the result of the expression on the right
DomainEventPublisher busAdapter    = projectionHandler::handle;              // => method ref adapter; delivers to handler
// => busAdapter: holds the result of the expression on the right
var commandService = new PlaceOrderService(storeAdapter, busAdapter); // => command side wired
// => commandService: holds the result of the expression on the right
var queryService   = new GetOrderService(viewRepo);                   // => query side wired
// => queryService: holds the result of the expression on the right
 
var id = commandService.placeOrder(new BigDecimal("49.99")); // => command: writes + publishes; returns id
// => id: holds the result of the expression on the right
var view = queryService.getOrder(id);                        // => query: reads projection; returns Optional
// => view: holds the result of the expression on the right
System.out.println(view.map(OrderView::status).orElse("not found")); // => Output: PLACED
// => PLACED: projection was updated synchronously by busAdapter; real bus would be async

import java.math.BigDecimal                                          // => BigDecimal for amounts
// => 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 stream id
 
// ── Shared event type ─────────────────────────────────────────────────────────
data class OrderPlacedEvent(val orderId: String, val total: BigDecimal, val placedAt: Instant)
// => shared event type; crosses command→query boundary via bus; flat DTO
 
// ── Command-side ports ─────────────────────────────────────────────────────────
fun interface EventStorePort     { fun append(streamId: String, event: OrderPlacedEvent) }  // => SAM
// => SAM; append to event stream; EventStoreDB in production
fun interface DomainEventPublisher { fun publish(event: OrderPlacedEvent) }  // => SAM
// => SAM; publish to bus; Kafka or RabbitMQ in production
// => fun interface: Kotlin SAM; allows lambda wiring at boot
 
// ── Command-side application service ─────────────────────────────────────────
class PlaceOrderService(                                             // => command-side only
// => executes the statement above; continues to next line
    private val store: EventStorePort,         // => command-side port only
    // => executes the statement above; continues to next line
    private val publisher: DomainEventPublisher // => command-side port only
    // => executes the statement above; continues to next line
) {
    fun placeOrder(total: BigDecimal): String {                      // => returns stream/order id
    // => placeOrder: method entry point — see implementation below
        val id    = UUID.randomUUID().toString()                    // => fresh stream id
        // => id: holds the result of the expression on the right
        val event = OrderPlacedEvent(id, total, Instant.now())     // => domain event
        // => event: holds the result of the expression on the right
        store.append(id, event)    // => persist first; then publish
        // => method call: delegates to collaborator; result captured above
        publisher.publish(event)   // => notify query side via bus
        // => Command service knows nothing of OrderViewRepository or projection
        return id                                                   // => return stream id to adapter
        // => returns the result to the caller — caller receives this value
    }
}
 
// ── Query-side read model ──────────────────────────────────────────────────────
data class OrderView(val orderId: String, val total: BigDecimal, val status: String, val placedAt: Instant)  // => read model
// => flat DTO; denormalised; optimised for query; no domain aggregate
 
// ── Query-side ports ───────────────────────────────────────────────────────────
interface OrderViewRepository {                                      // => query-side; application zone
// => interface OrderViewRepository: contract definition — no implementation details here
    fun save(view: OrderView)               // => write projection; called by handler
    // => executes the statement above; continues to next line
    fun findById(orderId: String): OrderView? // => read projection; null if not found
    // => separate from command-side ports; query never writes event store
}
 
// ── Query-side event handler: inbound adapter on query side ───────────────────
class OrderProjectionHandler(private val repo: OrderViewRepository) {  // => query-side adapter
// => class OrderProjectionHandler: implementation — contains field declarations and methods below
    fun handle(event: OrderPlacedEvent) {                              // => reacts to event
    // => handle: method entry point — see implementation below
        repo.save(OrderView(event.orderId, event.total, "PLACED", event.placedAt))  // => upsert view
        // => Translate event to flat view and persist to projection store
        // => Handler only depends on OrderViewRepository; no coupling to command side
    }
}
 
// ── Query-side application service ────────────────────────────────────────────
class GetOrderService(private val repo: OrderViewRepository) {       // => query-side; repo only
// => class GetOrderService: implementation — contains field declarations and methods below
    fun getOrder(id: String): OrderView? = repo.findById(id) // => read projection; no replay
    // => Fast: one SELECT from projection table; no event sourcing replay required
    // => Returns null if order not yet projected; eventual consistency
}
 
// ── In-memory wiring ──────────────────────────────────────────────────────────
val viewStore   = mutableMapOf<String, OrderView>()                 // => projection backing map
// => viewStore: holds the result of the expression on the right
val viewRepo    = object : OrderViewRepository {                    // => anonymous adapter; in-memory
// => type: implements port contract — dependency is on abstraction, not concretion
    override fun save(view: OrderView) { viewStore[view.orderId] = view }  // => upsert projection
    // => save: method entry point — see implementation below
    override fun findById(id: String) = viewStore[id]              // => lookup; null if not found
    // => executes the statement above; continues to next line
}
val projHandler = OrderProjectionHandler(viewRepo)                  // => query-side handler
// => projHandler: holds the result of the expression on the right
val cmdService  = PlaceOrderService(
// => cmdService: holds the result of the expression on the right
    store     = { _, evt -> /* event log */ },                      // => lambda store adapter; no-op
    // => executes the statement above; continues to next line
    publisher = projHandler::handle                                  // => method ref; wires cmd→query
    // => executes the statement above; continues to next line
)
val qryService  = GetOrderService(viewRepo)                         // => query-side service
// => qryService: holds the result of the expression on the right
 
val id   = cmdService.placeOrder(BigDecimal("49.99")) // => command: append + publish
// => id: holds the result of the expression on the right
val view = qryService.getOrder(id)                    // => query: read projection
// => view: holds the result of the expression on the right
println(view?.status)                                 // => Output: PLACED
// => ?.status: safe access; view is non-null because command just created it

using System;                                                         // => Guid, DateTimeOffset
// => executes the statement above; continues to next line
using System.Collections.Generic;                                     // => Dictionary
 
// ── Shared event type ─────────────────────────────────────────────────────────
public sealed record OrderPlacedEvent(string OrderId, decimal Total, DateTimeOffset PlacedAt);  // => crosses boundary
// => sealed record: immutable; value equality; crosses command→query via bus
 
// ── Command-side ports ─────────────────────────────────────────────────────────
public interface IEventStorePort      { void Append(string streamId, OrderPlacedEvent evt); }  // => write
// => command-side only; persist to event store before publishing
public interface IDomainEventPublisher { void Publish(OrderPlacedEvent evt); }  // => publish
// => Both ports: command side only; query side never sees these interfaces
// => command service imports both; query service imports neither
 
// ── Command-side application service ─────────────────────────────────────────
public class PlaceOrderService  // => command-side only; no query ports; no IOrderViewRepository
// => executes the statement above; continues to next line
{                                                                     // => command-side; append + publish
// => executes the statement above; continues to next line
    private readonly IEventStorePort       _store;     // => command port; persist events
    // => executes the statement above; continues to next line
    private readonly IDomainEventPublisher _publisher; // => command port; publish to bus
    // => executes the statement above; continues to next line
 
    public PlaceOrderService(IEventStorePort store, IDomainEventPublisher publisher)  // => two command ports
    // => constructor: receives all dependencies — enables testing with any adapter implementation
    { _store = store; _publisher = publisher; } // => constructor injection; two command ports
    // => executes the statement above; continues to next line
 
    public string PlaceOrder(decimal total)  // => command handler; returns stream id
    // => executes the statement above; continues to next line
    {
    // => operation completes; execution continues to next statement
        var id  = Guid.NewGuid().ToString();                              // => new stream id
        // => id: holds the result of the expression on the right
        var evt = new OrderPlacedEvent(id, total, DateTimeOffset.UtcNow); // => domain event; timestamp now
        // => evt: holds the result of the expression on the right
        _store.Append(id, evt);    // => persist to event store first
        // => method call: delegates to collaborator; result captured above
        _publisher.Publish(evt);   // => publish to bus; query side reacts asynchronously
        // => Command service knows only its two ports; zero coupling to query side
        return id;                 // => stream/order id returned to HTTP adapter
        // => returns the result to the caller — caller receives this value
    }
    // => operation completes; execution continues to next statement
}
 
// ── Query-side read model ──────────────────────────────────────────────────────
public sealed record OrderView(string OrderId, decimal Total, string Status, DateTimeOffset PlacedAt);  // => flat DTO
// => denormalised; no domain aggregate; optimised for display; sealed record; immutable
 
// ── Query-side ports ───────────────────────────────────────────────────────────
public interface IOrderViewRepository  // => query-side; no event store import; no command types
// => executes the statement above; continues to next line
{                                                                     // => query zone interface
// => interface type: contract definition — no implementation details here
    void Save(OrderView view);              // => upsert projection row; called by handler only
    // => executes the statement above; continues to next line
    OrderView? FindById(string orderId);    // => null if not found; query returns flat DTO
    // => two-method contract; command-side ports are completely separate
}
 
// ── Query-side event handler adapter ─────────────────────────────────────────
public class OrderProjectionHandler  // => inbound adapter; query side
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    private readonly IOrderViewRepository _repo; // => query port; write projection
    // => executes the statement above; continues to next line
    public OrderProjectionHandler(IOrderViewRepository repo) => _repo = repo;  // => inject
    // => constructor: receives all dependencies — enables testing with any adapter implementation
 
    public void Handle(OrderPlacedEvent evt)  // => event handler; translate to projection
    // => executes the statement above; continues to next line
    {
        _repo.Save(new OrderView(evt.OrderId, evt.Total, "Placed", evt.PlacedAt));  // => upsert view
        // => Translate event to flat projection and persist; no command-side types used
        // => "Placed": hardcoded initial status; domain state machine would evolve this
    }
}
 
// ── Query-side application service ────────────────────────────────────────────
public class GetOrderService  // => query-side only; no event store port
// => executes the statement above; continues to next line
{
    private readonly IOrderViewRepository _repo; // => query port only; no IEventStorePort
    // => executes the statement above; continues to next line
    public GetOrderService(IOrderViewRepository repo) => _repo = repo;  // => inject
    // => constructor: receives all dependencies — enables testing with any adapter implementation
 
    public OrderView? GetOrder(string id) => _repo.FindById(id); // => read projection directly
    // => Fast read path; no event replay; no aggregate loading
    // => returns null if not projected yet; eventual consistency
}
 
// ── In-memory wiring ──────────────────────────────────────────────────────────
var viewStore = new Dictionary<string, OrderView>();    // => projection backing store; keyed by OrderId
// => viewStore: holds the result of the expression on the right
var viewRepo  = new InMemoryViewRepo(viewStore);         // => adapter backed by dictionary
// => viewRepo: holds the result of the expression on the right
 
class InMemoryViewRepo : IOrderViewRepository {                       // => test adapter; no DB
// => class InMemoryViewRepo: implementation — contains field declarations and methods below
    private readonly Dictionary<string, OrderView> _store;            // => backing dictionary
    // => executes the statement above; continues to next line
    public InMemoryViewRepo(Dictionary<string, OrderView> store) => _store = store;  // => inject
    // => constructor: receives all dependencies — enables testing with any adapter implementation
    public void Save(OrderView v) => _store[v.OrderId] = v; // => upsert; OrderId as key
    // => method call: delegates to collaborator; result captured above
    public OrderView? FindById(string id) => _store.GetValueOrDefault(id); // => nullable; null if absent
    // => method call: delegates to collaborator; result captured above
}
 
var projHandler = new OrderProjectionHandler(viewRepo);              // => query-side handler
// => projHandler: holds the result of the expression on the right
var cmdService  = new PlaceOrderService(                             // => inject command ports
// => cmdService: holds the result of the expression on the right
    new LambdaEventStore(),                            // => inline store adapter (not shown)
    // => executes the statement above; continues to next line
    new LambdaPublisher(projHandler.Handle)            // => inline publisher wired to handler
    // => method call: delegates to collaborator; result captured above
);
var qryService  = new GetOrderService(viewRepo);                     // => inject query port
// => qryService: holds the result of the expression on the right
 
var id   = cmdService.PlaceOrder(49.99m);              // => command: append + publish; 49.99m USD
// => id: holds the result of the expression on the right
var view = qryService.GetOrder(id);                    // => query: read projection; may be null
// => view: holds the result of the expression on the right
Console.WriteLine(view?.Status);                       // => Output: Placed
// => view.Status == "Placed"; projection handler set it when event arrived

import java.util.Optional;                            // => Optional: no-null contract for findById
 
// ── Domain types ──────────────────────────────────────────────────────────────
record OrderId(String value) {}                       // => typed identity; not raw String
// => record OrderId: immutable value type; equals/hashCode/toString generated by compiler
record Order(OrderId id, String status) {}  // => simplified aggregate for demo
 
// ── Output port: application service depends only on this interface ────────────
// => OrderRepository: no tracing, no metrics — just the domain contract
interface OrderRepository {
// => interface OrderRepository: contract definition — no implementation details here
    Optional<Order> findById(OrderId id); // => load order; empty = not found
    // => executes the statement above; continues to next line
    void save(Order order);               // => persist order
    // => No tracing, no metrics, no logging in this interface definition
}
 
// ── Simulated OpenTelemetry span API (mirrors real SDK surface) ────────────────
// => In production: import io.opentelemetry.api.trace.Tracer
interface Tracer {                                    // => tracer abstraction; real OTel has same surface
// => interface Tracer: contract definition — no implementation details here
    Span spanBuilder(String name); // => create span builder; name appears in trace UI
    // => executes the statement above; continues to next line
}
// => operation completes; execution continues to next statement
interface Span {                                      // => span lifecycle; mirrors OTel SDK
// => interface Span: contract definition — no implementation details here
    Span start();                          // => begin timing; returns self for chaining
    // => executes the statement above; continues to next line
    void end();                            // => stop timing; record to backend
    // => executes the statement above; continues to next line
    void setAttribute(String k, String v); // => add metadata to span; key-value tags
    // => executes the statement above; continues to next line
    void recordException(Throwable t);     // => mark span as failed; exception still propagates
    // => executes the statement above; continues to next line
}
// => operation completes; execution continues to next statement
class NoopTracer implements Tracer {       // => no-op for demo compilation; prints for visibility
// => NoopTracer implements Tracer — satisfies the port contract
    public Span spanBuilder(String name) { // => returns anonymous Span that logs to console
    // => spanBuilder: method entry point — see implementation below
        return new Span() {
        // => returns the result to the caller — caller receives this value
            public Span start() { System.out.println("span started: " + name); return this; } // => Output: span started: <name>
            // => start: method entry point — see implementation below
            public void end()   { System.out.println("span ended: "   + name); }              // => Output: span ended: <name>
            // => end: method entry point — see implementation below
            public void setAttribute(String k, String v) {} // => no-op; real OTel records tag
            // => setAttribute: method entry point — see implementation below
            public void recordException(Throwable t)     {} // => no-op; real OTel records exception
            // => recordException: method entry point — see implementation below
        };
        // => operation completes; execution continues to next statement
    }
    // => operation completes; execution continues to next statement
}
 
// ── Tracing decorator: wraps real OrderRepository adapter ─────────────────────
// => Implements same OrderRepository interface; application service sees no difference
class TracingOrderRepository implements OrderRepository { // => decorator; adds spans transparently
// => TracingOrderRepository implements OrderRepository — satisfies the port contract
    private final OrderRepository delegate; // => wrapped real adapter (JPA, Mongo, etc.)
    // => delegate: OrderRepository — final field; assigned once in constructor; immutable reference
    private final Tracer          tracer;   // => OpenTelemetry tracer injected here
    // => tracer: Tracer — final field; assigned once in constructor; immutable reference
 
    TracingOrderRepository(OrderRepository delegate, Tracer tracer) { // => both injected; no static
    // => executes the statement above; continues to next line
        this.delegate = delegate; this.tracer = tracer; // => both injected; no static access
        // => this.delegate stored — field holds injected delegate for method calls below
    }
    // => operation completes; execution continues to next statement
 
    @Override                                         // => implements findById with span wrapping
    // => @Override: compiler verifies this method signature matches the interface
    public Optional<Order> findById(OrderId id) {
    // => executes the statement above; continues to next line
        var span = tracer.spanBuilder("order.findById").start(); // => begin span; name: "order.findById"
        // => span: holds the result of the expression on the right
        span.setAttribute("order.id", id.value());               // => tag with order id for filtering in UI
        // => method call: delegates to collaborator; result captured above
        try {
        // => exception handling: wraps operation that may fail
            var result = delegate.findById(id);                  // => delegate to real adapter; may throw
            // => result: holds the result of the expression on the right
            span.setAttribute("order.found", String.valueOf(result.isPresent())); // => tag result
            // => method call: delegates to collaborator; result captured above
            return result; // => return domain result; caller unaware of tracing
            // => returns the result to the caller — caller receives this value
        } catch (RuntimeException ex) {
        // => executes the statement above; continues to next line
            span.recordException(ex);  // => mark span failed; exception propagates
            // => method call: delegates to collaborator; result captured above
            throw ex;                  // => re-throw; application service handles it
            // => throws exception — guard condition failed; caller must handle this error path
        } finally {
        // => executes the statement above; continues to next line
            span.end(); // => always end span; finally ensures even on exception path
            // => method call: delegates to collaborator; result captured above
        }
    }
 
    @Override                                         // => implements save with span wrapping
    // => @Override: compiler verifies this method signature matches the interface
    public void save(Order order) {
    // => save: method entry point — see implementation below
        var span = tracer.spanBuilder("order.save").start(); // => begin span; name: "order.save"
        // => span: holds the result of the expression on the right
        span.setAttribute("order.id", order.id().value());   // => tag with order id
        // => method call: delegates to collaborator; result captured above
        try {
        // => exception handling: wraps operation that may fail
            delegate.save(order); // => delegate save to real adapter; may throw
            // => method call: delegates to collaborator; result captured above
        } catch (RuntimeException ex) {
        // => executes the statement above; continues to next line
            span.recordException(ex); throw ex; // => record exception; re-throw to caller
            // => method call: delegates to collaborator; result captured above
        } finally {
        // => executes the statement above; continues to next line
            span.end(); // => always end span; finally guarantees this on all paths
            // => method call: delegates to collaborator; result captured above
        }
    }
}
 
// ── In-memory real adapter (delegate) ─────────────────────────────────────────
// => InMemoryOrderRepository: real (non-tracing) adapter; wrapped by TracingOrderRepository
class InMemoryOrderRepository implements OrderRepository { // => implements port; no tracing here
// => InMemoryOrderRepository implements OrderRepository — satisfies the port contract
    private final java.util.Map<String, Order> store = new java.util.HashMap<>(); // => backing map
    // => new java(...): instantiates concrete implementation
    public Optional<Order> findById(OrderId id) { return Optional.ofNullable(store.get(id.value())); } // => lookup
    // => method call: delegates to collaborator; result captured above
    public void save(Order order) { store.put(order.id().value(), order); } // => upsert by string key
    // => save: method entry point — see implementation below
}
 
// ── Wiring: application service receives TracingOrderRepository ────────────────
var realRepo    = new InMemoryOrderRepository();                    // => real (inner) adapter
// => realRepo: holds the result of the expression on the right
var tracer      = new NoopTracer();                                 // => tracing adapter (demo noop)
// => tracer: holds the result of the expression on the right
var tracingRepo = new TracingOrderRepository(realRepo, tracer);     // => decorator wraps real adapter
 
// Application service — injected with tracingRepo; calls OrderRepository interface
// => Application service source code has no import of Tracer or Span
var order = new Order(new OrderId("ord-1"), "PLACED");              // => test domain object
// => order: holds the result of the expression on the right
tracingRepo.save(order);                                            // => Output: span started: order.save / span ended: order.save
// => method call: delegates to collaborator; result captured above
var found = tracingRepo.findById(new OrderId("ord-1"));            // => Output: span started: order.findById / span ended: order.findById
// => found: holds the result of the expression on the right
System.out.println(found.map(o -> o.status()).orElse("not found")); // => Output: PLACED; tracing transparent
// => output: verification line — shows result in console

// ── Domain types ──────────────────────────────────────────────────────────────
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 status: String)               // => domain aggregate; minimal
 
// ── Output port ───────────────────────────────────────────────────────────────
interface OrderRepository {                                          // => application zone; no OTel import
// => interface OrderRepository: contract definition — no implementation details here
    fun findById(id: OrderId): Order?  // => null = not found; no exception
    // => executes the statement above; continues to next line
    fun save(order: Order)             // => persist; idempotent
    // => No OpenTelemetry import here; port stays framework-free
    // => TracingOrderRepository wraps this; application service unaware of tracing
    // => contract: two methods; any implementation must satisfy both
}
 
// ── Minimal span API (mirrors real OpenTelemetry Kotlin SDK) ──────────────────
interface Tracer { fun spanBuilder(name: String): Span }  // => tracer abstraction; OTel mirror
// => interface Tracer: contract definition — no implementation details here
interface Span   { fun start(): Span; fun end(); fun setAttribute(k: String, v: String); fun recordException(t: Throwable) }  // => span lifecycle
// => Span: four methods; real OTel SDK has same surface; easy to swap
val noopTracer = object : Tracer {                                   // => no-op; for tests; prints to console
// => type: implements port contract — dependency is on abstraction, not concretion
    override fun spanBuilder(name: String) = object : Span {        // => anonymous Span implementation
    // => type: implements port contract — dependency is on abstraction, not concretion
        override fun start() = also { println("span started: $name") } // => Output: span started: <name>
        // => start: method entry point — see implementation below
        override fun end()         { println("span ended: $name") }     // => Output: span ended: <name>
        // => end: method entry point — see implementation below
        override fun setAttribute(k: String, v: String) {}           // => no-op; test adapter; ignores tags
        // => setAttribute: method entry point — see implementation below
        override fun recordException(t: Throwable) {}                // => no-op; test adapter; ignores exceptions
        // => recordException: method entry point — see implementation below
    }                                                                // => inner Span object complete
    // => executes the statement above; continues to next line
}                                                                    // => noopTracer: deterministic; suitable for tests
 
// ── Tracing decorator ─────────────────────────────────────────────────────────
class TracingOrderRepository(                                        // => decorator; wraps delegate; transparent
// => executes the statement above; continues to next line
    private val delegate: OrderRepository, // => real adapter wrapped; any OrderRepository impl
    // => executes the statement above; continues to next line
    private val tracer: Tracer             // => OpenTelemetry tracer; noopTracer in tests
    // => executes the statement above; continues to next line
) : OrderRepository {                                                // => implements same port; swap with any impl
// => executes the statement above; continues to next line
 
    override fun findById(id: OrderId): Order? {                     // => trace findById; OTel span wraps delegate
    // => findById: method entry point — see implementation below
        val span = tracer.spanBuilder("order.findById").start() // => begin span; OTel creates context
        // => span: holds the result of the expression on the right
        span.setAttribute("order.id", id.value)                 // => tag id for searchability
        // => method call: delegates to collaborator; result captured above
        return try {                                                 // => try block; captures exceptions
        // => returns the result to the caller — caller receives this value
            delegate.findById(id).also { result ->              // => delegate call; also attaches to result
            // => method call: delegates to collaborator; result captured above
                span.setAttribute("order.found", (result != null).toString()) // => tag result
                // => method call: delegates to collaborator; result captured above
            }
            // => operation completes; execution continues to next statement
        } catch (ex: RuntimeException) {                         // => catch transient errors
        // => executes the statement above; continues to next line
            span.recordException(ex); throw ex // => record error in span; re-throw for caller
            // => method call: delegates to collaborator; result captured above
        } finally {                                              // => always runs; span must end
        // => executes the statement above; continues to next line
            span.end() // => always end span in finally; even on exception
            // => method call: delegates to collaborator; result captured above
        }
        // => operation completes; execution continues to next statement
    }
 
    override fun save(order: Order) {                                // => trace save
    // => save: method entry point — see implementation below
        val span = tracer.spanBuilder("order.save").start() // => begin span
        // => span: holds the result of the expression on the right
        span.setAttribute("order.id", order.id.value)       // => tag id
        // => method call: delegates to collaborator; result captured above
        try { delegate.save(order) }                        // => delegate save; adapter handles I/O
        // => exception handling: wraps operation that may fail
        catch (ex: RuntimeException) { span.recordException(ex); throw ex } // => record + rethrow
        // => record type: immutable value type; equals/hashCode/toString generated by compiler
        finally { span.end() }                              // => always end; try/finally pattern
        // => exception handling: wraps operation that may fail
    }
}  // => TracingOrderRepository: transparent to application service; swap with plain repo at no cost
 
// ── Wiring and usage ───────────────────────────────────────────────────────────
val realRepo    = object : OrderRepository {                         // => in-memory real adapter; no JPA
// => type: implements port contract — dependency is on abstraction, not concretion
    val store = mutableMapOf<String, Order>()                        // => backing map; public for assertions
    // => store: holds the result of the expression on the right
    override fun findById(id: OrderId) = store[id.value]             // => lookup; null if absent
    // => method call: delegates to collaborator; result captured above
    override fun save(order: Order) { store[order.id.value] = order } // => upsert
    // => save: method entry point — see implementation below
}  // => realRepo: no tracing; just persistence; directly implements OrderRepository
// => executes the statement above; continues to next line
val tracingRepo = TracingOrderRepository(realRepo, noopTracer) // => decorator wraps real; adds spans
// => tracingRepo: holds the result of the expression on the right
tracingRepo.save(Order(OrderId("ord-1"), "PLACED"))             // => Output: span started/ended: order.save
// => application service calls tracingRepo; unaware of tracing
val found = tracingRepo.findById(OrderId("ord-1"))              // => Output: span started/ended: order.findById
// => found: holds the result of the expression on the right
println(found?.status)                                          // => Output: PLACED
// => output: verification line — shows result in console