Intermediate

// ── Command port ─────────────────────────────────────────────────────────────
// A command changes state and returns one or more domain events on success.
// The async wrapper acknowledges that persistence and notification are effectful.
// Result carries named error cases so the HTTP adapter can map them precisely.
type PlaceOrderCommand =
    UnvalidatedOrder -> Async<Result<OrderPlaced list, PlacingOrderError>>
// => Input:  raw, unvalidated order DTO from any delivery mechanism
// => Output: list of domain events on Ok, or a named error on Error
// => This is a state-changing operation — every call may write to the database
 
// ── Query port ───────────────────────────────────────────────────────────────
// A query never changes state; it projects data into a flat read model.
// OrderView is NOT the domain aggregate — it is a denormalised DTO
// optimised for read performance (no joins at read time).
type GetOrderQuery =
    OrderId -> Async<Result<OrderView option, QueryError>>
// => Input:  an order identity value
// => Output: Some flat read model, None if not found, or QueryError on failure
// => This is a side-effect-free read — safe to cache, safe to retry
 
// ── Read model ───────────────────────────────────────────────────────────────
// OrderView flattens the aggregate into a single, easily serialisable record.
// No domain logic lives in OrderView — it is purely a projection.
type OrderView = {
    OrderId   : string
    // => Identifies the order in the read model
    CustomerName : string
    // => Denormalised — avoids a join to the Customers table at query time
    TotalAmount  : decimal
    // => Final calculated total — already computed during command processing
    Status       : string
    // => Human-readable status label — not a domain DU, just a display string
    PlacedAt     : System.DateTimeOffset
    // => Audit timestamp — surfaced on every read without re-computing
}
 
// ── Distinct error types ──────────────────────────────────────────────────────
// QueryError is separate from PlacingOrderError: queries fail differently
// (not-found, index timeout) than commands (validation, pricing, constraint).
type QueryError =
    | NotFound  of string
    // => Requested resource does not exist in the read model
    | QueryTimeout of string
    // => Read timed out — caller can safely retry
 
// The HTTP adapter holds two separate injected ports:
// let placeOrder   : PlaceOrderCommand = ...   ← injected at composition root
// let getOrderView : GetOrderQuery     = ...   ← separate injection; different adapter
// => Commands and queries never share the same port type

// ── Domain aggregate port (used by command pipeline) ─────────────────────────
// FindOrder returns the full domain aggregate — a rich type with all domain rules.
// The application service uses this to load state before applying commands.
type FindOrder =
    OrderId -> Async<Result<Order option, RepositoryError>>
// => Returns the DOMAIN type `Order` — the aggregate root used in business logic
// => Lives in the command-side application service; never called from query handlers
 
// ── Domain aggregate ─────────────────────────────────────────────────────────
// Order is the rich aggregate: value objects, domain rules, full encapsulation.
// Rich types make invalid states unrepresentable at compile time.
type Order = {
    OrderId    : OrderId
    // => Strongly-typed identity — not just a string; prevents passing CustomerId where OrderId expected
    CustomerId : CustomerId
    // => Strongly-typed customer reference — distinct type from OrderId
    Lines      : OrderLine list
    // => List of order lines — validated, domain-typed list; empty list may violate a domain rule
    Status     : OrderStatus
    // => Domain DU, not a display string — carries domain semantics; exhaustive match required
    PlacedAt   : System.DateTimeOffset
    // => Immutable timestamp — set once at creation, never mutated by subsequent commands
}
 
// ── Read model port (used by query pipeline) ─────────────────────────────────
// GetOrderView returns the flat view model — a simple, serialisable record.
// The query adapter may serve this from a materialised view or cache.
type GetOrderView =
    OrderId -> Async<Result<OrderView, QueryError>>
// => Returns the READ MODEL type `OrderView` — not the domain aggregate
// => Two separate ports: two implementations, two adapters, two test doubles
 
// ── Two adapter implementations ───────────────────────────────────────────────
// Command-side adapter: queries the normalised Orders table (joins allowed)
// Satisfies FindOrder — the application service cannot tell if this is Postgres or in-memory
let postgresOrderRepo : FindOrder =
    fun orderId ->
        async {
            // In a real system: Npgsql query against the normalised schema
            // For this example: return a stub result to illustrate the port/adapter boundary
            let order : Order = {
                OrderId    = orderId
                // => orderId is the primary key from the SQL WHERE clause
                CustomerId = "CUST-42"
                // => Typed identity value loaded from normalised table
                Lines      = []
                // => Would deserialise JSONB or join to order_lines table
                Status     = Placed
                // => Deserialise discriminated union from a VARCHAR column
                PlacedAt   = System.DateTimeOffset.UtcNow
                // => Loaded from the placed_at TIMESTAMPTZ column
            }
            return Ok (Some order)
            // => Wrap in Some because orderId exists; return None when row is absent
        }
// => Adapter satisfies FindOrder port — replaces in-memory test double in production
 
// Query-side adapter: reads from a materialised view (denormalised, no joins)
// Satisfies GetOrderView — faster than the command-side adapter; no joins needed
let postgresOrderViewRepo : GetOrderView =
    fun orderId ->
        async {
            // In a real system: simple SELECT from the order_views materialised view
            let view : OrderView = {
                OrderId      = orderId
                // => The OrderId is passed through unchanged — primary key of the view
                CustomerName = "Wahidyan K."
                // => Pre-joined from customers table during materialisation
                TotalAmount  = 29.97m
                // => Pre-computed at write time — no aggregation at read time
                Status       = "Placed"
                // => Display string — enum already converted during materialisation
                PlacedAt     = System.DateTimeOffset.UtcNow
                // => Copied from the command side during event projection
            }
            return Ok view
            // => Always Ok in the stub; real adapter returns Error on DB failure
        }
// => Adapter satisfies GetOrderView port — could be replaced with Redis adapter
 
// Distinct error types used by each port
type RepositoryError = DbException of exn | ConnectionFailed of string
// => Command-side errors: infrastructure failures that may affect write consistency
type OrderStatus = | Placed | Confirmed | Shipped | Cancelled
// => Domain DU — the aggregate carries semantic status, not a raw string

// ── Port type ─────────────────────────────────────────────────────────────────
// SaveOrder is an output port — it performs an async I/O operation.
// The Result wrapper carries a named error type so the caller can react.
type SaveOrder = Order -> Async<Result<unit, RepositoryError>>
 
// ── Application service — manual Async + Result composition ──────────────────
// Without FsToolkit.ErrorHandling, composing two async-result calls
// requires explicit bind/match — verbose but shows exactly what is happening.
let manualPipeline (saveOrder: SaveOrder) (sendAck: Order -> Async<Result<unit, NotificationError>>) (order: Order) =
    async {
        // Step 1: call the save port — await and bind the async
        let! saveResult = saveOrder order
        // => saveResult : Result<unit, RepositoryError>
        // => Await completes the async; now we have a Result to inspect
        match saveResult with
        | Error repoErr ->
            // => Save failed — map the port error into the unified error DU
            return Error (RepositoryError repoErr)
        // => Short-circuit: sendAck is never called if save failed
        | Ok () ->
        // Step 2: save succeeded — call the notification port
        let! notifyResult = sendAck order
        // => notifyResult : Result<unit, NotificationError>
        match notifyResult with
        | Error notifyErr ->
            return Error (NotificationError notifyErr)
        // => Notification failed — surface the error on the same track
        | Ok () ->
            return Ok ()
        // => Both ports succeeded — return the happy path
    }
// => The manual pattern makes every bind point explicit and traceable
 
// Port error types (defined per infrastructure concern)
type RepositoryError  = DbException of exn | ConnectionFailed of string
type NotificationError = SmtpError of string | RateLimited
 
// Unified application error DU — wraps all port errors for the HTTP adapter
type AppError =
    | RepositoryError of RepositoryError
    // => Wraps repository failures — maps to 503
    | NotificationError of NotificationError
    // => Wraps notification failures — maps to 202 (saved but not notified)

// NOTE: asyncResult computation expression requires FsToolkit.ErrorHandling NuGet package
// Install: dotnet add package FsToolkit.ErrorHandling
open FsToolkit.ErrorHandling
 
// ── Same pipeline — much less noise ──────────────────────────────────────────
// asyncResult { } desugars to the same Async.bind + Result.bind chain above.
// The CE makes the railway metaphor literal: every let! is a track switch.
let asyncResultPipeline
    (saveOrder : Order -> Async<Result<unit, AppError>>)
    (sendAck   : Order -> Async<Result<unit, AppError>>)
    (order     : Order)
    : Async<Result<unit, AppError>> =
    asyncResult {
        do! saveOrder order
        // => Await save, short-circuit on Error — identical to the manual match above
        do! sendAck order
        // => Await notification, short-circuit on Error
        // => If both succeed, returns Ok () automatically
    }
// => asyncResult { } is syntactic sugar — same semantics, less ceremony
// => Requires FsToolkit.ErrorHandling; NOT part of F# standard library

// NOTE: asyncResult computation expression requires FsToolkit.ErrorHandling NuGet package
open FsToolkit.ErrorHandling
 
// ── Domain types ──────────────────────────────────────────────────────────────
type UnvalidatedOrder = { OrderId: string; ProductCode: string; Quantity: decimal }
type ValidatedOrder   = { OrderId: string; ProductCode: string; Quantity: decimal }
type PricedOrder      = { OrderId: string; TotalAmount: decimal }
type OrderPlaced      = { OrderId: string; TotalAmount: decimal }
 
// ── Unified error DU for the full pipeline ────────────────────────────────────
// Every failure mode — domain or infrastructure — joins this union.
// The HTTP adapter pattern-matches exhaustively to produce the right status code.
type PlacingOrderError =
    | ValidationError  of string
    // => Domain rule violation — maps to HTTP 422
    | PricingError     of string
    // => Pricing failure — maps to HTTP 500
    | RepositoryError  of exn
    // => Infrastructure failure — maps to HTTP 503
    | NotificationError of string
    // => Notification failure — maps to HTTP 202 (saved, not notified)
 
// ── Port types (output ports) ─────────────────────────────────────────────────
type FindProduct  = string -> Async<Result<decimal, PlacingOrderError>>
// => Query the product catalogue for the unit price
type SaveOrder    = PricedOrder -> Async<Result<unit, PlacingOrderError>>
// => Persist the priced order to the repository
type PublishEvent = OrderPlaced -> Async<Result<unit, PlacingOrderError>>
// => Publish the domain event to the message bus
 
// ── Pure domain functions (synchronous, no I/O) ───────────────────────────────
let validateOrder (input: UnvalidatedOrder) : Result<ValidatedOrder, PlacingOrderError> =
    if System.String.IsNullOrWhiteSpace(input.OrderId) then Error (ValidationError "OrderId blank")
    // => Domain rule: blank OrderId rejected immediately
    elif input.Quantity <= 0m then Error (ValidationError "Quantity must be positive")
    // => Domain rule: zero or negative quantity rejected
    else Ok { OrderId = input.OrderId; ProductCode = input.ProductCode; Quantity = input.Quantity }
    // => Validation passed — returns the validated state type
 
let calculatePrice (unitPrice: decimal) (validated: ValidatedOrder) : Result<PricedOrder, PlacingOrderError> =
    if unitPrice <= 0m then Error (PricingError "Unit price must be positive")
    // => Pricing rule: non-positive prices are rejected
    else Ok { OrderId = validated.OrderId; TotalAmount = validated.Quantity * unitPrice }
    // => TotalAmount = quantity × unit price — pure arithmetic, no I/O
 
// ── Full pipeline: pure steps + async port calls ──────────────────────────────
// asyncResult { } stitches synchronous Results and async-Results seamlessly.
// The CE automatically handles the Ok/Error short-circuit at every step.
let buildPlaceOrder (findProduct: FindProduct) (saveOrder: SaveOrder) (publishEvent: PublishEvent) =
    fun (input: UnvalidatedOrder) ->
        asyncResult {
            // Step 1: pure domain validation — lifted into asyncResult with ofResult
            let! validated = validateOrder input |> AsyncResult.ofResult
            // => ofResult lifts a synchronous Result into the async railway
            // => Short-circuits on ValidationError — steps 2-5 are skipped
 
            // Step 2: async port call — fetch the unit price
            let! unitPrice = findProduct validated.ProductCode
            // => findProduct : string -> Async<Result<decimal, PlacingOrderError>>
            // => Awaited and unwrapped by let! — Error short-circuits here
 
            // Step 3: pure domain pricing — lifted into asyncResult
            let! priced = calculatePrice unitPrice validated |> AsyncResult.ofResult
            // => calculatePrice is pure; ofResult bridges sync → async railway
 
            // Step 4: async port call — persist the order
            do! saveOrder priced
            // => do! discards the unit result; Error would short-circuit here
 
            // Step 5: async port call — publish the domain event
            let event = { OrderId = priced.OrderId; TotalAmount = priced.TotalAmount }
            // => Construct the domain event from the priced order
            do! publishEvent event
            // => do! publishes and short-circuits on PublishError
 
            // All five steps succeeded — return the domain event list
            return [ event ]
            // => The HTTP adapter receives Ok [event] and maps to 200 OK
        }
// => Pure steps and port calls compose uniformly — the CE hides the plumbing

// ── Unified error DU — application layer ─────────────────────────────────────
// Every distinct failure mode surfaces as a named DU case.
// This DU is owned by the APPLICATION layer — not domain, not adapters.
// Domain errors bubble up unchanged; port errors are lifted via Result.mapError.
type PlacingOrderError =
    | ValidationError   of string
    // => Emitted by pure domain functions — maps to HTTP 422
    | PricingError      of string
    // => Emitted by pure domain functions — maps to HTTP 500
    | RepositoryError   of exn
    // => Emitted by repository adapter — maps to HTTP 503
    | NotificationError of string
    // => Emitted by notification adapter — maps to HTTP 202 (accepted, not notified)
 
// ── Port-specific error types (infrastructure layer) ─────────────────────────
// Each adapter defines its own error type — narrowly scoped to that adapter.
// The application service maps them into PlacingOrderError via mapError.
type DbError   = ConnectionFailed of string | QueryFailed of exn
type SmtpError = AuthFailed of string | Timeout
 
// ── Lifting port errors into the unified DU ───────────────────────────────────
// mapError transforms the error channel of a Result without touching the Ok path.
// The lambda maps the adapter-specific error type to a PlacingOrderError case.
let liftDbError : Result<'a, DbError> -> Result<'a, PlacingOrderError> =
    Result.mapError (fun dbErr ->
        match dbErr with
        | ConnectionFailed msg -> RepositoryError (System.Exception(msg))
        // => Connection failure wrapped in RepositoryError case
        | QueryFailed ex       -> RepositoryError ex
        // => Query exception lifted directly — preserves the original exception
    )
 
let liftSmtpError : Result<'a, SmtpError> -> Result<'a, PlacingOrderError> =
    Result.mapError (fun smtpErr ->
        match smtpErr with
        | AuthFailed msg -> NotificationError (sprintf "SMTP auth failed: %s" msg)
        // => Auth failure described as a notification error
        | Timeout        -> NotificationError "SMTP timeout"
        // => Timeout case described as a notification error
    )
 
// ── HTTP adapter: exhaustive pattern match on unified DU ──────────────────────
// The HTTP adapter receives PlacingOrderError and maps each case to an HTTP status.
// F# forces exhaustive matching — if a new case is added, compilation fails here.
let toHttpResponse (result: Result<OrderPlaced list, PlacingOrderError>) : string =
    match result with
    | Ok events              -> sprintf "200 OK: %d events" (List.length events)
    // => Happy path — all pipeline steps succeeded
    | Error (ValidationError msg)   -> sprintf "422 Unprocessable Entity: %s" msg
    // => Domain validation failure — client submitted invalid data
    | Error (PricingError msg)      -> sprintf "500 Internal Server Error: %s" msg
    // => Pricing failure — internal pricing rule violated
    | Error (RepositoryError ex)    -> sprintf "503 Service Unavailable: %s" ex.Message
    // => Database unavailable — client may retry after backoff
    | Error (NotificationError msg) -> sprintf "202 Accepted (notification failed): %s" msg
    // => Order saved but notification failed — not a fatal error
 
// ── Demonstration ─────────────────────────────────────────────────────────────
let demo () =
    let outcomes = [
        Ok [ { OrderId = "ORD-1"; TotalAmount = 29.97m } ]
        // => Happy path result
        Error (ValidationError "OrderId blank")
        // => Domain validation failure
        Error (RepositoryError (System.Exception "connection refused"))
        // => Infrastructure failure
        Error (NotificationError "SMTP timeout")
        // => Non-fatal notification failure
    ]
    outcomes |> List.iter (fun r -> printfn "%s" (toHttpResponse r))
    // => Output: 200 OK: 1 events
    // => Output: 422 Unprocessable Entity: OrderId blank
    // => Output: 503 Service Unavailable: connection refused
    // => Output: 202 Accepted (notification failed): SMTP timeout
 
type OrderPlaced = { OrderId: string; TotalAmount: decimal }

open System.Collections.Generic
 
// ── Port type: repository record ─────────────────────────────────────────────
// A record of functions is the idiomatic F# alternative to an interface.
// All four operations are co-located — one value to inject, not four.
// Substitution: test adapter = one record literal; production adapter = another.
type OrderRepository = {
    FindById : OrderId -> Async<Result<Order option, RepositoryError>>
    // => Load by identity — Option signals not-found without raising an exception
    // => Async: I/O required; Result: infrastructure failure is explicit
    Save     : Order   -> Async<Result<unit, RepositoryError>>
    // => Upsert semantics — create or update; caller does not distinguish insert from update
    // => Returns unit on success — the persisted state is what was passed in
    Delete   : OrderId -> Async<Result<unit, RepositoryError>>
    // => Remove by identity — Error if row did not exist (adapter decides whether missing = error)
    // => unit return: deletion has no meaningful success payload
    Exists   : OrderId -> Async<Result<bool, RepositoryError>>
    // => Existence check — cheaper than FindById when full aggregate not needed
    // => bool: true = exists, false = does not exist; Error = infrastructure failure
}
 
// ── In-memory implementation ──────────────────────────────────────────────────
// The in-memory adapter satisfies the same type — same fields, same signatures.
// A mutable Dictionary is acceptable in the adapter zone (outside the domain).
// Factory function: returns a fresh, isolated repo for each test — no shared state.
let makeInMemoryRepo () : OrderRepository =
    let store = Dictionary<OrderId, Order>()
    // => Mutable Dictionary lives in the adapter, never leaks into the domain
    // => Captured in the closure — each call to makeInMemoryRepo gets its own instance
    {
        FindById = fun id ->
            // => id: the OrderId to look up in the in-memory store
            async {
                match store.TryGetValue(id) with
                | true,  order -> return Ok (Some order)
                // => Found — wrap in Some and Ok; type: Async<Result<Order option, RepositoryError>>
                | false, _     -> return Ok None
                // => Not found — return None, not an error; caller decides what to do with None
                // => None is not a failure: caller uses it to check existence without loading
            }
        Save = fun order ->
            // => order: the full Order aggregate to persist (create or replace)
            async {
                store.[order.OrderId] <- order
                // => Dictionary indexer performs both insert and update — upsert semantics
                // => In-memory: always succeeds; Postgres adapter may fail on constraint violation
                return Ok ()
                // => Always succeeds in the in-memory adapter; Postgres adapter may fail here
            }
        Delete = fun id ->
            // => id: the OrderId to remove from the store
            async {
                let removed = store.Remove(id)
                // => Remove returns bool — true if key existed and was removed
                if removed then return Ok ()
                // => Deletion succeeded — the row existed and is now gone
                else return Error (RowNotFound (sprintf "OrderId %s not found" id))
                // => Deletion failed: ID did not exist — error semantics match PostgreSQL DELETE
            }
        Exists = fun id ->
            // => id: the OrderId to check — only identity needed, not the full aggregate
            async {
                return Ok (store.ContainsKey(id))
                // => ContainsKey is O(1) — no need to deserialise the full aggregate
                // => true = exists, false = does not exist; never Error in in-memory adapter
            }
    }
 
// ── Usage in application service ──────────────────────────────────────────────
// The application service receives the record as a single parameter.
// Single injection: replaces four separate function parameters.
let buildUseCase (repo: OrderRepository) =
    // => One injection point — all four operations available via repo.FindById etc.
    // => Compose root passes makeInMemoryRepo() in tests; postgresRepo in production
    fun (orderId: OrderId) ->
        async {
            let! existsResult = repo.Exists orderId
            // => Check existence before loading — cheaper for guards; avoids loading full aggregate
            match existsResult with
            | Error e          -> return Error e
            // => Short-circuit on infrastructure error — propagate without transformation
            | Ok false         -> return Error (RowNotFound "order not found")
            // => Not found — return the domain-appropriate error; caller maps to 404
            | Ok true          ->
            let! findResult = repo.FindById orderId
            // => Now load the full aggregate — existence confirmed above; should not be None
            return findResult
            // => Returns Ok (Some order) or Error on infra failure
        }
 
// Supporting types
type OrderId = string
// => Type alias: prevents passing arbitrary strings as order identifiers
type Order   = { OrderId: OrderId; CustomerId: string; TotalAmount: decimal }
// => Aggregate root — carries domain state; persisted and loaded by the repository
type RepositoryError = RowNotFound of string | DbException of exn
// => Two named cases: missing row (client error) vs infrastructure failure (server error)

// ── Value objects ──────────────────────────────────────────────────────────────
// Single-case DUs wrap primitives — prevents passing a PhoneNumber where EmailAddress expected.
type EmailAddress = EmailAddress of string
// => Validated type: EmailAddress constructor enforces format elsewhere
// => Wrapping: EmailAddress "test@example.com" — not just a bare string
type PhoneNumber  = PhoneNumber  of string
// => Validated type: PhoneNumber constructor enforces E.164 format elsewhere
// => Example: PhoneNumber "+628123456789" — country code required
type OrderId        = string
// => Type alias: identifies an order uniquely within the bounded context
type TrackingNumber = string
// => Type alias: identifies a shipment for the customer-facing tracking system
 
// ── Notification DU — models all notification payloads ────────────────────────
// The DU carries the right payload for each notification kind.
// The adapter inspects the case and routes to the correct delivery mechanism.
type Notification =
    | OrderConfirmation of to_: EmailAddress * orderId: OrderId
    // => Email delivery: sends order confirmation to customer email address
    // => Named tuple fields (to_, orderId) document intent at the call site
    | ShippingAlert     of to_: PhoneNumber  * trackingNumber: TrackingNumber
    // => SMS delivery: sends tracking number to customer mobile number
    // => Different payload shape: phone + tracking — no email address involved
 
// ── Port type ──────────────────────────────────────────────────────────────────
// One port covers all notification types — the application service uses one function.
// Adding a third notification kind (push notification) does not change the port type.
type SendNotification = Notification -> Async<Result<unit, NotificationError>>
// => Input:  a Notification DU case — application service does not know the delivery channel
// => Output: Ok () on success, named error on failure; unit means no response payload
 
type NotificationError = SmtpError of string | SnsError of string | RateLimited
// => Errors scoped to notification delivery — not mixed with repository errors
// => Three cases: SMTP failure, SNS failure, and rate limiting across all channels
 
// ── SMTP adapter (handles OrderConfirmation) ──────────────────────────────────
// In production this opens an SMTP connection; here we stub for illustration.
// This function is NOT the port — it is an internal helper used by the composite adapter.
let smtpSend (email: EmailAddress) (body: string) : Async<Result<unit, NotificationError>> =
    async {
        printfn "[SMTP] Sending to %A: %s" email body
        // => Real adapter: System.Net.Mail.SmtpClient or Mailkit
        // => Stub always returns Ok — production adapter wraps SmtpException in SmtpError
        return Ok ()
    }
 
// ── SNS adapter (handles ShippingAlert) ───────────────────────────────────────
// Internal helper — routes SMS via Amazon SNS (or Twilio in another implementation).
let snsSend (phone: PhoneNumber) (msg: string) : Async<Result<unit, NotificationError>> =
    async {
        printfn "[SNS] Sending SMS to %A: %s" phone msg
        // => Real adapter: AWS SDK PublishAsync to an SNS topic
        // => Stub always returns Ok — production adapter wraps SNS exceptions in SnsError
        return Ok ()
    }
 
// ── Composite adapter — routes by DU case ─────────────────────────────────────
// The composite adapter is still an adapter — it satisfies SendNotification.
// Application service never knows whether SMTP or SNS was called.
// This is the value that the composition root injects as SendNotification.
let compositeNotify : SendNotification =
    fun notification ->
        match notification with
        | OrderConfirmation (email, orderId) ->
            // => Pattern-match on DU case — extract the email address and order ID
            smtpSend email (sprintf "Your order %s has been placed." orderId)
            // => Email route: delegate to SMTP helper — body is constructed here in the adapter
        | ShippingAlert (phone, tracking) ->
            // => Pattern-match on DU case — extract the phone number and tracking number
            snsSend phone (sprintf "Your package is on the way. Tracking: %s" tracking)
            // => SMS route: delegate to SNS helper — message is constructed here in the adapter
 
// ── In-memory test adapter ────────────────────────────────────────────────────
// Records sent notifications for test assertions — no real network calls.
// Factory function: each test gets a fresh instance — no shared mutable state between tests.
let makeInMemoryNotifier () =
    let sent = System.Collections.Generic.List<Notification>()
    // => Mutable list records every notification for assertion in tests
    // => Captured in closure — isolated per test when makeInMemoryNotifier is called fresh
    let send : SendNotification =
        fun n -> async { sent.Add(n); return Ok () }
    // => Satisfies the port type — same signature as composite adapter
    // => Always Ok: in-memory adapter cannot fail unless the test explicitly overrides it
    send, (fun () -> sent |> Seq.toList)
    // => Returns both the port implementation and an accessor for test assertions
    // => Accessor converts List to immutable F# list for safe assertion
 
// ── Application service usage ─────────────────────────────────────────────────
// The application service names the notification kind using the DU — not the channel.
let placeOrderAndNotify (sendNotification: SendNotification) (orderId: OrderId) (email: EmailAddress) =
    async {
        let! result = sendNotification (OrderConfirmation (email, orderId))
        // => Application service names the notification kind — not the delivery channel
        // => Whether SMTP or push or in-memory: the port type is the same
        return result
        // => Propagates Ok () or NotificationError to the caller
    }

// ── Clock port ────────────────────────────────────────────────────────────────
// GetCurrentTime is the smallest possible port: unit in, DateTimeOffset out.
// The application service calls this function whenever it needs the current time.
// It NEVER calls DateTimeOffset.UtcNow directly.
type GetCurrentTime = unit -> DateTimeOffset
// => Input:  unit — no parameters needed; the function encapsulates the time source
// => Output: the current timestamp from whatever source the adapter provides
 
// ── Production clock adapter ──────────────────────────────────────────────────
let systemClock : GetCurrentTime =
    fun () -> DateTimeOffset.UtcNow
// => Delegates to the system clock — correct for production use
// => Non-deterministic: each call returns the actual current wall-clock time
 
// ── Test clock adapter ────────────────────────────────────────────────────────
// Returns a fixed, well-known timestamp — deterministic across all test runs.
let fixedClock (fixedTime: System.DateTimeOffset) : GetCurrentTime =
    fun () -> fixedTime
// => Always returns the same value — tests become reproducible and environment-agnostic
// => Can be set to any value: regression scenarios, daylight-saving edge cases, year 2038
 
let testClock : GetCurrentTime =
    fixedClock (System.DateTimeOffset(2026, 1, 1, 0, 0, 0, System.TimeSpan.Zero))
// => Fixed at 2026-01-01T00:00:00Z — every test run agrees on "now"
 
// ── Domain types using time ───────────────────────────────────────────────────
type Order = {
    OrderId   : string
    PlacedAt  : System.DateTimeOffset
    // => Audit timestamp — must come from the clock port, never from UtcNow
    ExpiresAt : System.DateTimeOffset
    // => Business rule: orders expire 30 days after placement
}
 
// ── Application service using the clock port ──────────────────────────────────
let createOrder (getClock: GetCurrentTime) (orderId: string) : Order =
    let now = getClock ()
    // => Calls the injected clock — could be system clock or fixed test clock
    let expiresAt = now.AddDays(30.0)
    // => 30-day expiry calculated from the injected "now" — deterministic in tests
    { OrderId = orderId; PlacedAt = now; ExpiresAt = expiresAt }
// => Deterministic output when testClock injected; real-time output with systemClock
 
// ── Demonstration ─────────────────────────────────────────────────────────────
let order = createOrder testClock "ORD-001"
printfn "PlacedAt:  %s" (order.PlacedAt.ToString("o"))
// => Output: PlacedAt:  2026-01-01T00:00:00.0000000+00:00
printfn "ExpiresAt: %s" (order.ExpiresAt.ToString("o"))
// => Output: ExpiresAt: 2026-01-31T00:00:00.0000000+00:00
// => Exact output every run — test assertions can use hardcoded expected values
 
open System

// ── Log level DU ──────────────────────────────────────────────────────────────
// LogLevel is owned by the APPLICATION layer — not by Serilog or NLog.
// If the logging library changes, this DU remains stable.
type LogLevel = Debug | Info | Warn | Error
// => Four levels cover the standard semantic range
// => Debug: diagnostic detail; Info: business events; Warn: unexpected recoverable; Error: failures
 
// ── Logger port ───────────────────────────────────────────────────────────────
// LogEvent takes: level, message template, and a key-value property list.
// The key-value list enables structured logging — queryable fields, not just strings.
type LogEvent = LogLevel * string * (string * obj) list -> unit
// => Synchronous — logging calls should not block the application pipeline
// => unit return — logging is a fire-and-forget side effect
 
// ── Production logger adapter (Serilog) ───────────────────────────────────────
// In a real project: open Serilog; delegate to Log.ForContext(...).Information(...)
let serilogAdapter : LogEvent =
    fun (level, template, props) ->
        // => In production: enrich Serilog context with props, call level-specific method
        // => Here: simplified output to demonstrate the adapter pattern
        let propStr = props |> List.map (fun (k, v) -> sprintf "%s=%A" k v) |> String.concat " "
        printfn "[%A] %s | %s" level template propStr
// => Application code calls logEvent (Info, "Order placed", [...]) — never calls Serilog directly
 
// ── In-memory test logger ─────────────────────────────────────────────────────
// Records every log entry for assertion — no I/O, no thread-safety concern in tests.
let makeTestLogger () =
    let entries = System.Collections.Generic.List<LogLevel * string * (string * obj) list>()
    // => Captures all log calls in order
    let logEvent : LogEvent =
        fun entry -> entries.Add(entry)
    // => Satisfies the port type — same signature as serilogAdapter
    logEvent, (fun () -> entries |> Seq.toList)
    // => Returns the port and an accessor for test assertions
 
// ── Application service using the logger port ─────────────────────────────────
let placeOrderWithLogging (logEvent: LogEvent) (orderId: string) (amount: decimal) =
    logEvent (Info, "Order placement started", ["orderId", box orderId])
    // => Structured property "orderId" is queryable in Serilog/ELK — not just text
    if amount <= 0m then
        logEvent (Warn, "Invalid order amount", ["orderId", box orderId; "amount", box amount])
        // => Warn-level with two structured properties — queryable in production
        Error "Invalid amount"
        // => Domain validation failure
    else
        logEvent (Info, "Order placed successfully", ["orderId", box orderId; "amount", box amount])
        // => Audit log — every order placement is recorded with full context
        Ok orderId
 
// ── Test assertion using in-memory logger ─────────────────────────────────────
let logFn, getLogs = makeTestLogger ()
let _ = placeOrderWithLogging logFn "ORD-001" 29.97m
let logs = getLogs ()
printfn "Log count: %d" (List.length logs)
// => Output: Log count: 2
printfn "First entry level: %A" (logs |> List.head |> (fun (level, _, _) -> level))
// => Output: First entry level: Info

// ── Configuration error ───────────────────────────────────────────────────────
// Two distinct error cases: missing key vs present-but-invalid value.
// Separate cases let callers give meaningful error messages (missing vs malformed).
type ConfigError =
    | MissingSetting of key: string
    // => The required key was not found in any configuration source
    // => Suggests operator forgot to set the environment variable
    | InvalidValue   of key: string * value: string
    // => The key exists but its value fails validation (e.g. non-numeric timeout)
    // => Suggests operator set the variable to a wrong value
 
// ── Configuration port ────────────────────────────────────────────────────────
// GetSetting maps a string key to a string value.
// The application service validates and converts the string after reading.
// Result allows the application service to fail fast with a descriptive error.
// Synchronous: config reads should not require async I/O in typical deployments.
type GetSetting = string -> Result<string, ConfigError>
// => Input:  setting key name (e.g. "DB_TIMEOUT_SECONDS")
// => Output: string value on Ok, named config error on Error
// => String output: caller is responsible for parsing/validating the raw string
 
// ── Environment variable adapter ──────────────────────────────────────────────
// Production adapter: reads from the process environment — standard 12-factor app pattern.
let envVarAdapter : GetSetting =
    fun key ->
        // => key: the env var name — e.g. "DB_TIMEOUT_SECONDS" or "FEATURE_FLAG_X"
        match System.Environment.GetEnvironmentVariable(key) with
        | null | "" -> Error (MissingSetting key)
        // => Environment variable absent or empty — fail with descriptive error
        // => null: never set; "": set to empty string — both treated as missing
        | value     -> Ok value
        // => Found — return raw string; caller parses it
 
// ── Dictionary-based test adapter ────────────────────────────────────────────
// Provides hardcoded values — no environment setup required in tests.
// Satisfies the same GetSetting type as envVarAdapter — fully substitutable.
let dictAdapter (settings: Map<string, string>) : GetSetting =
    fun key ->
        // => key: looked up in the immutable F# Map — no mutation possible
        match Map.tryFind key settings with
        | None       -> Error (MissingSetting key)
        // => Key absent in test dictionary — same error shape as env adapter
        | Some value -> Ok value
        // => Found — return the hardcoded test value; no env var lookup needed
 
// ── Application service reading configuration ─────────────────────────────────
// Reads the timeout, validates it is a positive integer, and returns it.
// The caller (composition root) provides the getSetting implementation.
let readTimeoutSeconds (getSetting: GetSetting) : Result<int, ConfigError> =
    getSetting "DB_TIMEOUT_SECONDS"
    // => Port call — does not know whether source is env var, file, or test dict
    |> Result.bind (fun raw ->
        // => Result.bind: if Ok, parse the raw string; if Error, propagate unchanged
        match System.Int32.TryParse(raw) with
        | true,  n when n > 0 -> Ok n
        // => Valid positive integer — use it as the timeout value in seconds
        | true,  n            -> Error (InvalidValue ("DB_TIMEOUT_SECONDS", string n))
        // => Parsed but non-positive — configuration is semantically invalid
        | false, _            -> Error (InvalidValue ("DB_TIMEOUT_SECONDS", raw))
        // => Not parseable as integer — configuration is malformed
    )
 
// ── Test double usage ─────────────────────────────────────────────────────────
let testSettings = dictAdapter (Map.ofList [("DB_TIMEOUT_SECONDS", "30")])
// => Test provides known value — no environment variable needed
// => Map.ofList: immutable F# Map — safe to share across concurrent tests
 
let timeoutResult = readTimeoutSeconds testSettings
// => Result<int, ConfigError> — should be Ok 30
printfn "Timeout: %A" timeoutResult
// => Output: Timeout: Ok 30
 
let missingSettings = dictAdapter (Map.ofList [])
// => Empty dictionary — simulates missing configuration; no keys at all
let missingResult = readTimeoutSeconds missingSettings
printfn "Missing: %A" missingResult
// => Output: Missing: Error (MissingSetting "DB_TIMEOUT_SECONDS")

// ── Domain event DU ───────────────────────────────────────────────────────────
// Domain events are immutable facts — named in past tense, data-carrying.
// The DU lives in the APPLICATION layer — owned by the workflow, not the adapter.
// New event types: add a new DU case; adapter and consumer add new handling.
type DomainEvent =
    | OrderPlaced    of OrderPlacedPayload
    // => Signals a new order was successfully placed
    // => Carries the full payload — consumer does not need to query back
    | OrderCancelled of OrderId
    // => Signals an order was cancelled — carries only the identity
    // => Minimal payload: consumer queries for details if needed
 
type OrderPlacedPayload = { OrderId: OrderId; TotalAmount: decimal; CustomerId: string }
// => Payload is a flat record — no domain aggregate; safe to serialise to JSON
// => Flat structure: no nested aggregates that would create schema coupling
type OrderId = string
// => Type alias — both hexagons use the same primitive for the order identifier
 
// ── Publishing error ───────────────────────────────────────────────────────────
// Two distinct failure modes with different retry semantics.
type PublishError =
    | BrokerUnavailable of string
    // => Message broker unreachable — transient; caller should retry with backoff
    | SerializationError of string
    // => Event could not be serialised — programming error; do not retry; alert
 
// ── Publishing port ────────────────────────────────────────────────────────────
// PublishEvent takes one domain event and publishes it to the message bus.
// The application service does not know about RabbitMQ, Kafka, or any specific broker.
// Async: network I/O required; Result: failure is expected and named.
type PublishEvent = DomainEvent -> Async<Result<unit, PublishError>>
// => Input:  a typed domain event — the adapter serialises it to the wire format
// => Output: Ok () on successful publish, named PublishError on failure
// => unit success payload: no acknowledgment data flows back from the broker
 
// ── In-memory test adapter ────────────────────────────────────────────────────
// Records every published event for test assertions — no real broker needed.
// Factory function: fresh instance per test ensures no cross-test contamination.
let makeInMemoryPublisher () =
    let published = System.Collections.Generic.List<DomainEvent>()
    // => Accumulates events in insertion order — List preserves publish sequence
    let publish : PublishEvent =
        // => publish satisfies the PublishEvent type — identical signature to the RabbitMQ adapter
        fun event ->
            async {
                published.Add(event)
                // => Record the event — synchronous, always succeeds in tests
                // => No serialisation, no network — captures the typed event directly
                return Ok ()
                // => In-memory adapter never fails; production adapter may return BrokerUnavailable
            }
    publish, (fun () -> published |> Seq.toList)
    // => Returns the port implementation and a read accessor for assertions
    // => Seq.toList: creates an immutable snapshot for safe assertion
 
// ── Application service publishing after save ─────────────────────────────────
// The application service calls publishEvent AFTER save succeeds.
// This ensures the event is only published when the state change is durable.
// Save-then-publish ordering: event is a true reflection of persisted state.
let completeOrder
    (saveOrder    : string -> Async<Result<unit, exn>>)
    // => saveOrder: output port — abstracts the persistence mechanism
    (publishEvent : PublishEvent)
    // => publishEvent: output port — abstracts the message broker
    (orderId      : OrderId)
    (amount       : decimal) =
    async {
        let! saveResult = saveOrder orderId
        // => Step 1: persist state — must succeed before publishing the event
        // => await the async save; saveResult : Result<unit, exn>
        match saveResult with
        | Error ex -> return Error (BrokerUnavailable ex.Message)
        // => Save failed — do not publish; event would be a lie about persisted state
        | Ok () ->
        let event = OrderPlaced { OrderId = orderId; TotalAmount = amount; CustomerId = "CUST-1" }
        // => Construct the domain event after successful save — only created here
        let! publishResult = publishEvent event
        // => Step 2: publish — transient failure here is acceptable (event can be re-published)
        // => publishResult : Result<unit, PublishError>
        return publishResult
        // => Surface Ok () or PublishError to the caller
    }
 
// ── Test assertion ─────────────────────────────────────────────────────────────
let publishFn, getPublished = makeInMemoryPublisher ()
// => publishFn: the port implementation; getPublished: the assertion accessor
let stubSave = fun _ -> async { return Ok () }
// => Stub save: always succeeds — we are testing the publish path here
 
let _ = completeOrder stubSave publishFn "ORD-001" 29.97m |> Async.RunSynchronously
// => Run the full pipeline synchronously for demonstration
let events = getPublished ()
// => Retrieve all published events — should contain exactly one event
printfn "Published events: %d" (List.length events)
// => Output: Published events: 1
printfn "First event: %A" (List.head events)
// => Output: First event: OrderPlaced { OrderId = "ORD-001"; TotalAmount = 29.97M; CustomerId = "CUST-1" }

open System
 
// ── Retry configuration ───────────────────────────────────────────────────────
// RetryConfig is a plain record — it is passed to withRetry at the composition root.
// Changing the policy requires only a new config value, not edits to the adapter.
type RetryConfig = {
    MaxAttempts  : int
    // => Total number of attempts including the first try (1 = no retry)
    InitialDelay : TimeSpan
    // => Wait time before the second attempt — usually 100ms–1s for network calls
    BackoffFactor : float
    // => Multiplier applied to delay after each failure (2.0 = exponential backoff)
    // => e.g., 100ms, 200ms, 400ms with BackoffFactor = 2.0
}
 
// ── Higher-order retry wrapper ────────────────────────────────────────────────
// withRetry wraps any async-result function with retry-and-backoff behaviour.
// The wrapped function's signature is unchanged — callers do not know about retry.
// Generic over 'a and 'e: works with any port whose error type is 'e.
let withRetry (config: RetryConfig) (operation: unit -> Async<Result<'a, 'e>>) : unit -> Async<Result<'a, 'e>> =
    // => Returns a new function with the same type — transparent to the caller
    // => withRetry is a combinator: operation in, operation-with-retry out
    fun () ->
        let rec attempt n delay =
            // => n: current attempt number (1-based); delay: TimeSpan before next retry
            async {
                let! result = operation ()
                // => Call the real operation — could be a DB write or HTTP call
                // => result : Result<'a, 'e> — inspect to decide whether to retry
                match result with
                | Ok _ -> return result
                // => Success on any attempt — return immediately, no more retries
                | Error _ when n >= config.MaxAttempts -> return result
                // => All attempts exhausted — surface the final error to the caller
                | Error _ ->
                    do! Async.Sleep (int delay.TotalMilliseconds)
                    // => Wait before retrying — gives the downstream service time to recover
                    let nextDelay = TimeSpan.FromMilliseconds(delay.TotalMilliseconds * config.BackoffFactor)
                    // => Compute next delay: current × backoff factor — grows exponentially
                    return! attempt (n + 1) nextDelay
                    // => Recurse with incremented attempt count and longer delay
            }
        attempt 1 config.InitialDelay
        // => Start first attempt; InitialDelay is ready for use if attempt 1 fails
 
// ── Adapter using withRetry ───────────────────────────────────────────────────
// The application service holds a reference to SaveOrder (the port type).
// The adapter wraps the real implementation BEFORE injecting into the service.
// Composition root wires: let portForService = withRetry config realAdapter
type SaveOrder = unit -> Async<Result<unit, string>>
// => Simplified port type for this example — unit in, unit out, string error
 
let realSave : SaveOrder =
    // => Simulates a flaky database connection for demonstration
    // => mutable: tracks internal attempt count — acceptable in the adapter zone
    let mutable attempt = 0
    fun () ->
        async {
            attempt <- attempt + 1
            // => Increment counter before deciding success/failure
            if attempt < 3 then
                return Error (sprintf "DB connection failed (attempt %d)" attempt)
                // => Simulates transient failure on attempts 1 and 2
            else
                return Ok ()
                // => Succeeds on attempt 3 — simulates service recovery
        }
 
let retryConfig = { MaxAttempts = 3; InitialDelay = TimeSpan.FromMilliseconds(10.0); BackoffFactor = 2.0 }
// => 3 attempts: attempt 1 immediately, attempt 2 after 10ms, attempt 3 after 20ms
 
// Wrap the real save with retry BEFORE injecting into the application service
let saveWithRetry : SaveOrder = withRetry retryConfig realSave
// => saveWithRetry has the same type as realSave — SaveOrder is unchanged
// => Application service calls saveWithRetry() — unaware of retry mechanics
 
// ── Application service — no retry knowledge ──────────────────────────────────
// The application service calls the port as if retry does not exist.
// Whether the port retries once or ten times is invisible here.
let applicationService (saveOrder: SaveOrder) =
    async {
        let! result = saveOrder ()
        // => Calls the port — may internally retry 3 times; service does not know
        // => If all retries fail, result is the final Error from attempt 3
        return result
        // => Propagate result: Ok () or Error string
    }
 
// ── Demonstration ─────────────────────────────────────────────────────────────
let result = applicationService saveWithRetry |> Async.RunSynchronously
// => Async.RunSynchronously: block the current thread until the async completes
printfn "Result after retry: %A" result
// => Output: Result after retry: Ok ()
// => Three attempts were made internally; the service saw one Ok result

open System
 
// ── Circuit breaker state DU ──────────────────────────────────────────────────
// CircuitState models the three states of the circuit breaker pattern.
// This DU lives in the ADAPTER module — not in the domain or application layer.
// Three states cover the full lifecycle: normal, tripped, and probing recovery.
type CircuitState =
    | Closed
    // => Normal operation: all calls pass through to the downstream service
    // => failureCount increments on Error; resets to 0 on Ok
    | Open of openedAt: DateTimeOffset
    // => Tripped: refusing calls to protect the downstream service from overload
    // => Carries openedAt so the adapter can compute when the open duration expires
    | HalfOpen
    // => Probe state: allowing one call through to check if service has recovered
    // => If the probe succeeds, circuit closes; if it fails, circuit re-opens
 
// ── Circuit breaker error ─────────────────────────────────────────────────────
// Two distinct error cases: circuit refused the call vs downstream returned an error.
type CircuitError = CircuitOpen | DownstreamError of string
// => CircuitOpen: call refused because the circuit is open — fast failure, no I/O
// => DownstreamError: call was made but downstream returned an error — I/O occurred
 
// ── Circuit breaker wrapper ───────────────────────────────────────────────────
// withCircuitBreaker wraps any async-result function with circuit breaker logic.
// The application service calls the wrapped function — unaware of circuit state.
// Generic over 'a: works with any port return type (string, unit, Order, etc.).
let withCircuitBreaker
    (failureThreshold  : int)
    // => Open the circuit after this many consecutive failures
    (openDuration      : TimeSpan)
    // => How long the circuit stays open before probing with HalfOpen
    (operation         : unit -> Async<Result<'a, string>>)
    // => The real downstream call — unit in, async result out
    : unit -> Async<Result<'a, CircuitError>> =
    let mutable state        = Closed
    // => Initial state: circuit closed — calls pass through
    let mutable failureCount = 0
    // => Counts consecutive failures since last success; resets on any Ok
    fun () ->
        // => Returns a function with the same shape — transparent to the caller
        async {
            match state with
            | Open openedAt when DateTimeOffset.UtcNow < openedAt + openDuration ->
                // => Circuit still open — reject immediately without calling downstream
                // => Fast failure: no network call, no timeout; microseconds instead of seconds
                return Error CircuitOpen
            | Open _ ->
                // => Open duration elapsed — probe with one call (transition to HalfOpen)
                state <- HalfOpen
                // => HalfOpen: next branch will let one call through
            | _ -> ()
            // => Closed or HalfOpen: proceed with the actual call below
 
            let! result = operation ()
            // => Call the real downstream operation — may fail or succeed
            match result with
            | Ok value ->
                // => Call succeeded — reset circuit to Closed and clear failure count
                state        <- Closed
                // => Circuit is healthy again — all subsequent calls pass through
                failureCount <- 0
                // => Reset consecutive failure counter
                return Ok value
                // => Pass success value through to the caller
            | Error err ->
                failureCount <- failureCount + 1
                // => Count this failure — check against threshold
                if failureCount >= failureThreshold then
                    state <- Open DateTimeOffset.UtcNow
                    // => Threshold exceeded — open the circuit; record the open time
                return Error (DownstreamError err)
                // => Surface the downstream error to the caller regardless of circuit state
        }
 
// ── Adapter using the circuit breaker ─────────────────────────────────────────
// The application service holds the output port type unchanged.
// The adapter wraps the real call with the circuit breaker before injection.
// flakeyDownstream simulates a service that fails 3 times then recovers.
let flakeyDownstream : unit -> Async<Result<string, string>> =
    let mutable callCount = 0
    // => callCount: tracks how many times the downstream has been called
    fun () ->
        async {
            callCount <- callCount + 1
            // => Increment before deciding — first call is attempt 1
            if callCount <= 3 then return Error "downstream unavailable"
            // => First 3 calls fail — simulates a temporarily unavailable service
            else return Ok "data from downstream"
            // => Subsequent calls succeed — simulates service recovery after restart
        }
 
let protectedCall = withCircuitBreaker 2 (TimeSpan.FromSeconds(5.0)) flakeyDownstream
// => Circuit opens after 2 consecutive failures; stays open for 5 seconds
// => protectedCall has the same unit -> Async<Result<string, CircuitError>> shape
 
// ── Demonstration ─────────────────────────────────────────────────────────────
let results =
    [ for _ in 1..4 do
        yield protectedCall () |> Async.RunSynchronously ]
// => Call 1: Error (DownstreamError "downstream unavailable") — failure 1, count = 1
// => Call 2: Error (DownstreamError "downstream unavailable") — failure 2, circuit opens
// => Call 3: Error CircuitOpen — circuit is open, downstream not called at all
// => Call 4: Error CircuitOpen — circuit still open (5s not elapsed)
 
results |> List.iteri (fun i r -> printfn "Call %d: %A" (i+1) r)
// => Output: Call 1: Error (DownstreamError "downstream unavailable")
// => Output: Call 2: Error (DownstreamError "downstream unavailable")
// => Output: Call 3: Error CircuitOpen
// => Output: Call 4: Error CircuitOpen

// ── OrderTaking hexagon ───────────────────────────────────────────────────────
// Completely self-contained: own domain types, own ports, own adapters.
// Does NOT import anything from the Shipping module.
// Zone structure: Domain ← Application ← Adapters — dependency rule enforced.
module OrderTaking =
 
    // Domain layer — inner zone; no external imports
    module Domain =
        type OrderId          = string
        // => Identity type: used only within this hexagon's domain layer
        type UnvalidatedOrder = { OrderId: OrderId; Quantity: decimal }
        // => Raw input from any delivery mechanism — validation has not yet occurred
        type OrderPlaced      = { OrderId: OrderId; TotalAmount: decimal }
        // => Domain event: signals a successful placement — the ONLY coupling point
        // => This type is translated to a wire format by the adapter, not shared directly
 
    // Application layer — middle zone; imports Domain only
    module Application =
        open Domain
        // The PublishEvent port is the ONLY interface between the two hexagons.
        // OrderTaking does not know about Shipping's domain types.
        // Port type: defined in the Application zone, not the Adapter zone.
        type PublishEvent = OrderPlaced -> Async<Result<unit, string>>
        // => Output port: publish the domain event to the message bus
        // => The event bus is the boundary; Shipping subscribes independently
        // => string error: simplified for this example; use a named DU in production
 
    // Adapter layer (illustration only — real adapter would open RabbitMQ SDK)
    // Outer zone: may import Application and infrastructure libraries.
    module Adapters =
        open Application
        // makeRabbitPublisher returns a value of type PublishEvent — the port type.
        // The composition root calls this to get the concrete implementation.
        let makeRabbitPublisher () : PublishEvent =
            fun event ->
                async {
                    printfn "[OrderTaking→Bus] Published: %A" event
                    // => Real adapter: serialize event to JSON, publish to RabbitMQ exchange
                    // => Stub: always Ok; production adapter wraps broker exceptions
                    return Ok ()
                    // => Unit result: no acknowledgment data needed from the bus
                }
 
// ── Shipping hexagon ──────────────────────────────────────────────────────────
// Completely self-contained: own domain types, own ports, own adapters.
// Does NOT import anything from the OrderTaking module.
// Separate hexagon: can be deployed as a separate service or kept in same process.
module Shipping =
 
    // Domain layer — Shipping's own ubiquitous language; no OrderTaking vocabulary
    module Domain =
        type ShipmentId   = string
        // => Identity type: lives only in Shipping's namespace
        type CustomerId   = string
        // => Shipping has its own identity types — not reused from OrderTaking
        // => Even though OrderTaking also has CustomerId, they are separate type aliases
        type ShipmentRequested = { ShipmentId: ShipmentId; ExternalOrderRef: string; Quantity: decimal }
        // => ExternalOrderRef is the ORDER ID from OrderTaking — treated as opaque string
        // => Shipping does not import OrderTaking.Domain.OrderId — loose coupling by design
        // => "External order reference" is Shipping's language, not "order ID"
 
    // Application layer — middle zone
    module Application =
        open Domain
        type CreateShipment = ShipmentRequested -> Async<Result<unit, string>>
        // => Input port: receives shipment commands from the message consumer adapter
        // => Message consumer adapter translates wire event → ShipmentRequested, then calls this
 
    // Adapter layer: Anti-Corruption Layer (ACL) translates the external event
    module Adapters =
        open Domain
        open Application
        // The ACL lives in the ADAPTER zone — it translates external event shapes
        // into Shipping's own domain types. No external type leaks past this point.
        // ACL = last line of defence; Shipping's domain never sees OrderTaking vocabulary.
        let translateExternalEvent (externalOrderId: string) (quantity: decimal) : ShipmentRequested =
            { ShipmentId       = System.Guid.NewGuid().ToString()
              // => Generate new identity in Shipping's own namespace — not the OrderId
              ExternalOrderRef = externalOrderId
              // => Treated as opaque string — no type dependency on OrderTaking
              Quantity         = quantity
              // => Quantity passes through — both contexts agree on decimal precision
            }
        // => ACL ensures Shipping's domain is never polluted with OrderTaking concepts
        // => When OrderTaking renames a field, only this function changes — not Shipping's domain
 
printfn "Two hexagons defined — no cross-module type imports"
// => Output: Two hexagons defined — no cross-module type imports
// => F# module system enforces the boundary at compile time

// ── Shared kernel: only primitive event schema (no domain types) ──────────────
// SharedKernel contains only the serialised event shape — no domain logic.
// Both hexagons reference this module for the wire format only.
// Versioning: when the schema changes, SharedKernel is bumped; each hexagon adapts in its ACL.
module SharedKernel =
    // The event payload is a plain record — no DUs, no domain types.
    // JSON-serialisable: string, decimal, DateTimeOffset only — no F# domain types.
    type OrderPlacedEvent = {
        OrderId     : string
        // => Opaque string identifier — each context interprets it in its own namespace
        // => OrderTaking sees it as an OrderId; Shipping sees it as an ExternalOrderRef
        TotalAmount : decimal
        // => Decimal for precision — both contexts agree on this primitive
        // => Do not use float: precision loss would silently corrupt financial calculations
        PlacedAt    : System.DateTimeOffset
        // => Event timestamp — used by Shipping for SLA tracking and ordering
        // => ISO 8601 serialisation ensures timezone-safe wire format
    }
// => SharedKernel is the ONLY module both hexagons may import — no domain types cross
// => SharedKernel has no functions — it is a pure data contract
 
// ── OrderTaking hexagon: publishing the event ─────────────────────────────────
// OrderTaking translates its own domain event to the SharedKernel wire format.
// The adapter performs the translation — the domain event stays in domain language.
module OrderTaking =
    open SharedKernel
 
    type OrderPlaced = { OrderId: string; TotalAmount: decimal }
    // => OrderTaking's own domain event — NOT the SharedKernel wire format
    // => Naming: past tense (OrderPlaced) — immutable fact about what happened
 
    // Port: accepts the OrderTaking domain event — not the wire format
    type PublishOrderPlaced = OrderPlaced -> Async<Result<unit, string>>
    // => Output port: the application service calls this after a successful save
    // => Application service knows only OrderPlaced; wire format is an adapter concern
 
    // Adapter: translates domain event to SharedKernel wire format then publishes
    // makeEventBusAdapter is a factory — accepts publishToWire, returns the port.
    let makeEventBusAdapter (publishToWire: SharedKernel.OrderPlacedEvent -> Async<unit>) : PublishOrderPlaced =
        fun domainEvent ->
            // => domainEvent: OrderTaking's typed domain event
            async {
                let wireEvent : SharedKernel.OrderPlacedEvent = {
                    OrderId     = domainEvent.OrderId
                    // => Map OrderTaking domain OrderId (string) to wire format OrderId
                    TotalAmount = domainEvent.TotalAmount
                    // => Decimal passes through unchanged — same type in domain and wire format
                    PlacedAt    = System.DateTimeOffset.UtcNow
                    // => Timestamp added at publish time — not stored in the domain event itself
                }
                do! publishToWire wireEvent
                // => Publish the wire format event to the message bus — broker-specific I/O
                return Ok ()
                // => Stub: always Ok; production wraps broker exceptions in named error
            }
 
// ── Shipping hexagon: consuming the event ─────────────────────────────────────
// Shipping subscribes to the bus, applies the ACL, and calls its own input port.
// No type from OrderTaking module is imported here — only SharedKernel wire format.
module Shipping =
    open SharedKernel
 
    // Shipping's own domain types — entirely independent of OrderTaking
    // Different field names signal different ubiquitous language in each context.
    type ShipmentId      = string
    // => Shipping's own identity type — not the same as OrderTaking's OrderId
    type ShipmentRequest = { ShipmentId: ShipmentId; SourceOrderRef: string; Amount: decimal }
    // => SourceOrderRef is an opaque reference — Shipping does not care about OrderTaking types
    // => Amount not TotalAmount — Shipping's language differs from OrderTaking's language
 
    // Input port: the CreateShipment use case
    type CreateShipment = ShipmentRequest -> Async<Result<unit, string>>
    // => Input port: called by the message consumer adapter with a translated request
    // => This is Shipping's inbound port — analogous to the HTTP handler for HTTP adapters
 
    // Anti-Corruption Layer (ACL): translates SharedKernel event to Shipping domain type
    // ACL lives in the ADAPTER zone: shields the domain from external vocabulary changes.
    let translateEvent (event: SharedKernel.OrderPlacedEvent) : ShipmentRequest =
        { ShipmentId     = System.Guid.NewGuid().ToString()
          // => New identity in Shipping's namespace — not the OrderId; Shipping owns this ID
          SourceOrderRef = event.OrderId
          // => Store the external reference as an opaque string — no type import from OrderTaking
          Amount         = event.TotalAmount
          // => Rename TotalAmount → Amount: Shipping's ubiquitous language differs
        }
    // => ACL is the last line of defence: SharedKernel types never reach Shipping's domain
    // => If OrderTaking renames TotalAmount to Price, only translateEvent changes
 
    // Message consumer adapter: subscribes to the event bus, applies ACL, calls input port
    // handleOrderPlacedEvent is the inbound adapter — the message consumer equivalent of an HTTP handler.
    let handleOrderPlacedEvent (createShipment: CreateShipment) (wireEvent: SharedKernel.OrderPlacedEvent) =
        async {
            let request = translateEvent wireEvent
            // => ACL translation: wire format → Shipping domain type
            // => After this line, no SharedKernel types appear in the application logic
            let! result = createShipment request
            // => Call the Shipping input port — same pattern as the HTTP adapter calling a use case
            match result with
            | Ok ()    -> printfn "[Shipping] Shipment created for order %s" wireEvent.OrderId
            // => Happy path — shipment request accepted; log for observability
            | Error e  -> printfn "[Shipping] Failed to create shipment: %s" e
            // => Error path — real system would dead-letter or retry; log for alerting
        }
 
// ── Composition root: wire the two hexagons through the event bus ─────────────
// In-memory event bus for demonstration — real system uses RabbitMQ/Kafka.
// The composition root is the only place both hexagon modules appear together.
let inMemoryBus = System.Collections.Generic.List<SharedKernel.OrderPlacedEvent>()
// => Simulates the message broker — events accumulate here in wire format
 
// Shipping's use case (stub for demonstration)
// Satisfies CreateShipment — the same port type that would be wired to real persistence.
let stubCreateShipment : Shipping.CreateShipment =
    fun req -> async { printfn "[Shipping domain] Processing: %A" req; return Ok () }
// => Stub satisfies the input port type — composition root swaps this for real impl
 
// Wire: OrderTaking publishes to the in-memory bus
let publishToWire = fun event -> async { inMemoryBus.Add(event) }
// => publishToWire: accepts SharedKernel.OrderPlacedEvent, adds to in-memory bus
let orderTakingPublisher = OrderTaking.makeEventBusAdapter publishToWire
// => orderTakingPublisher : OrderTaking.PublishOrderPlaced — ready to inject into app service
 
// Simulate: OrderTaking places an order and publishes the domain event
let domainEvent : OrderTaking.OrderPlaced = { OrderId = "ORD-001"; TotalAmount = 29.97m }
// => Domain event: OrderTaking's own type — not the SharedKernel wire format
orderTakingPublisher domainEvent |> Async.RunSynchronously |> ignore
// => Adapter translates and appends the wire event to inMemoryBus
// => Output: (no console output yet — event is in the bus)
 
// Simulate: Shipping consumer reads from the bus and processes each event
inMemoryBus
|> Seq.iter (fun wireEvent ->
    Shipping.handleOrderPlacedEvent stubCreateShipment wireEvent |> Async.RunSynchronously)
// => ACL translates each wire event; createShipment called for each
// => Output: [Shipping domain] Processing: { ShipmentId = "..."; SourceOrderRef = "ORD-001"; Amount = 29.97M }
// => Output: [Shipping] Shipment created for order ORD-001

// ── External event type (from OrderTaking, received over the wire) ────────────
// This type represents the deserialized wire payload — not Shipping's domain type.
// Shipping's ACL adapter accepts this type; the domain never sees it.
module OrderTaking =
    type OrderPlaced = {
        OrderId      : string
        // => OrderTaking's identity value — opaque to Shipping; treated as a reference string
        CustomerEmail: string
        // => Email as known by OrderTaking — Shipping may or may not use it
        Lines        : {| ProductCode: string; Quantity: decimal |} list
        // => Anonymous record list: product code and quantity per line
        TotalAmount  : decimal
        // => Final order total computed by OrderTaking — Shipping uses this for prioritisation
    }
 
// ── Shipping domain types ──────────────────────────────────────────────────────
module Shipping =
    type ShipmentReference = ShipmentReference of string
    // => Shipping-owned identity — NOT the OrderTaking OrderId
    // => Single-case DU prevents passing arbitrary strings as shipment references
 
    type ShipmentItem = { Sku: string; Quantity: decimal }
    // => Shipping's vocabulary: Sku (not ProductCode), Quantity (same primitive)
    // => Field rename: ProductCode → Sku signals the different ubiquitous language
 
    type Priority = Standard | Express
    // => Shipping adds a domain concept that OrderTaking does not have
    // => ACL sets a default; a richer rule could derive priority from TotalAmount
 
    type CreateShipmentRequest = {
        ShipmentReference : ShipmentReference
        // => New identity generated in Shipping's namespace — not borrowed from OrderTaking
        SourceOrderRef    : string
        // => Opaque external reference — stored but never treated as a typed OrderId
        Items             : ShipmentItem list
        // => Translated from OrderTaking lines using Shipping's vocabulary
        Priority          : Priority
        // => Default assigned here; no equivalent concept exists in OrderTaking
    }
 
// ── Anti-Corruption Layer adapter ─────────────────────────────────────────────
// The ACL is an ADAPTER — lives in the outermost zone.
// It is the only place that imports both external and Shipping types.
// After translation, no OrderTaking type ever reaches Shipping.Application or Shipping.Domain.
module ShippingAclAdapter =
    open Shipping
 
    // translate is the ACL function: external event in, Shipping domain type out.
    // Called by the message consumer adapter before invoking the input port.
    let translate (event: OrderTaking.OrderPlaced) : Shipping.CreateShipmentRequest =
        let ref = ShipmentReference (System.Guid.NewGuid().ToString())
        // => Generate a new Shipping-owned identity — Shipping does not reuse OrderTaking's OrderId
        // => Guid.NewGuid: fresh identity per translation; idempotency handled upstream
        let items =
            event.Lines
            |> List.map (fun line ->
                // => Map each OrderTaking line to a Shipping ShipmentItem
                { Sku      = line.ProductCode
                  // => ProductCode → Sku: field rename expresses Shipping's ubiquitous language
                  Quantity = line.Quantity
                  // => Quantity: same decimal type; no conversion needed
                })
        // => items: ShipmentItem list — all lines translated; no OrderTaking type remains
        { ShipmentReference = ref
          // => Shipping-owned identity — generated above
          SourceOrderRef    = event.OrderId
          // => External reference stored as an opaque string — Shipping does not parse it
          Items             = items
          // => Translated line items — Shipping vocabulary throughout
          Priority          = Standard
          // => Default priority: ACL assigns Standard for all inbound orders
          // => A richer rule could use event.TotalAmount to promote to Express
        }
    // => After translate, Shipping.Application and Shipping.Domain see only Shipping types
    // => If OrderTaking renames Lines to OrderLines, only this function needs updating
 
// ── Demonstration ─────────────────────────────────────────────────────────────
let externalEvent : OrderTaking.OrderPlaced = {
    OrderId       = "ORD-001"
    CustomerEmail = "test@example.com"
    Lines         = [| {| ProductCode = "SKU-42"; Quantity = 3m |} |] |> Array.toList
    TotalAmount   = 89.97m
}
// => Simulated external event arriving from the message bus as a deserialized record
 
let shipmentRequest = ShippingAclAdapter.translate externalEvent
// => ACL translates: OrderTaking.OrderPlaced → Shipping.CreateShipmentRequest
printfn "ShipmentReference: %A" shipmentRequest.ShipmentReference
// => Output: ShipmentReference: ShipmentReference "<new-guid>"
printfn "SourceOrderRef: %s" shipmentRequest.SourceOrderRef
// => Output: SourceOrderRef: ORD-001
printfn "Items: %A"          shipmentRequest.Items
// => Output: Items: [{ Sku = "SKU-42"; Quantity = 3M }]
printfn "Priority: %A"       shipmentRequest.Priority
// => Output: Priority: Standard

// ── Shared Kernel module ──────────────────────────────────────────────────────
// SharedKernel contains ONLY types that are stable across multiple bounded contexts.
// Rule: if a type needs to change often, it does NOT belong in SharedKernel.
// Governance: changes to SharedKernel require coordination with all consuming contexts.
module SharedKernel =
 
    // CustomerId: an identity that both OrderTaking and Shipping must reference.
    // Single-case DU prevents passing arbitrary strings as customer identifiers.
    type CustomerId = CustomerId of string
    // => Both contexts use CustomerId to correlate records across context boundaries
    // => CustomerId("CUST-42") — the DU label documents intent at the call site
 
    // Money: a value object with currency — both contexts perform monetary calculations.
    // Validated: Money constructor should enforce Amount >= 0m and valid Currency code.
    type Money = { Amount: decimal; Currency: string }
    // => Amount: decimal for precision — never float for monetary values
    // => Currency: ISO 4217 code (e.g. "USD", "IDR") — not an int or enum here
    // => Shared because both OrderTaking (pricing) and Shipping (COD) reference monetary values
 
    // Address: a value object representing a physical location.
    // Both contexts need address for different reasons: billing (OrderTaking), delivery (Shipping).
    type Address = {
        Street  : string
        // => Street line: house number and street name combined
        City    : string
        // => City name — used by Shipping for routing zone calculation
        PostCode: string
        // => Postal code — used by both contexts; format varies by country
        Country : string
        // => ISO 3166-1 alpha-2 country code (e.g. "ID", "US")
    }
    // => Address is shared because both contexts validate, store, and display it
 
// ── OrderTaking bounded context ───────────────────────────────────────────────
// Opens SharedKernel to access stable shared types; does NOT import Shipping.
module OrderTaking =
    open SharedKernel
    // => opens SharedKernel: CustomerId, Money, Address available in this scope
    // => Does NOT open Shipping — bounded context independence enforced
 
    type Order = {
        OrderId    : string
        // => OrderTaking's own identity — not shared; owned exclusively by this context
        Customer   : CustomerId
        // => SharedKernel type: references the customer without owning customer data
        TotalAmount: Money
        // => SharedKernel Money: amount + currency — same precision semantics as Shipping
        BillingAddr: Address
        // => SharedKernel Address: billing address — may differ from delivery address
    }
    // => Order uses SharedKernel types for cross-context stable fields
    // => OrderTaking-specific fields (OrderId, line items) are owned exclusively here
 
// ── Shipping bounded context ───────────────────────────────────────────────────
// Opens SharedKernel to access stable shared types; does NOT import OrderTaking.
module Shipping =
    open SharedKernel
    // => opens SharedKernel: same stable types as OrderTaking; no Shipping-specific types
    // => Does NOT open OrderTaking — separate domain model, separate evolution pace
 
    type Shipment = {
        ShipmentId  : string
        // => Shipping's own identity — generated by Shipping; not reused from OrderTaking
        Recipient   : CustomerId
        // => SharedKernel CustomerId: references the same customer without owning the data
        DeliverTo   : Address
        // => SharedKernel Address: delivery address — may be different from billing address
        ShippingCost: Money
        // => SharedKernel Money: cost charged by Shipping — same monetary value object
    }
    // => Shipment uses SharedKernel types for the stable cross-context fields
    // => Shipping-specific fields (ShipmentId, carrier, tracking) are owned exclusively here
 
// ── Demonstration ─────────────────────────────────────────────────────────────
let customerId = SharedKernel.CustomerId "CUST-42"
// => CustomerId constructed once — both contexts reference the same value
let address = { SharedKernel.Street = "Jl. Sudirman 1"; City = "Jakarta"; PostCode = "10220"; Country = "ID" }
// => Shared Address: both contexts can use this value without conversion
 
let order : OrderTaking.Order = {
    OrderId     = "ORD-001"
    Customer    = customerId
    // => SharedKernel CustomerId — no string/type conversion needed between contexts
    TotalAmount = { Amount = 89.97m; Currency = "IDR" }
    BillingAddr = address
}
printfn "Order customer: %A" order.Customer
// => Output: Order customer: CustomerId "CUST-42"
 
let shipment : Shipping.Shipment = {
    ShipmentId   = "SHP-001"
    Recipient    = customerId
    // => Same SharedKernel CustomerId — identity correlates across contexts without coupling
    DeliverTo    = address
    ShippingCost = { Amount = 15000m; Currency = "IDR" }
}
printfn "Shipment recipient: %A" shipment.Recipient
// => Output: Shipment recipient: CustomerId "CUST-42"

// ── Feature flag port ──────────────────────────────────────────────────────────
// IsFeatureEnabled checks whether a named flag is active for the current context.
// Async: flags may be fetched from a remote service (LaunchDarkly, ConfigCat).
// bool: simple on/off flag; a more advanced port could return a variant string.
type IsFeatureEnabled = string -> Async<bool>
// => Input:  flag name — e.g. "new-pricing-algorithm", "checkout-v2"
// => Output: true = flag is on; false = flag is off or not found
// => No Result: flag evaluation should never fail the main pipeline; default to false on error
 
// ── Environment variable adapter ──────────────────────────────────────────────
// Production adapter: reads flag names from environment variables.
// Convention: flag name is upper-cased and prefixed with FEATURE_FLAG_.
// Absent or non-"true" value → flag is off.
let envVarFlagAdapter : IsFeatureEnabled =
    fun flagName ->
        async {
            let envKey = "FEATURE_FLAG_" + flagName.ToUpper().Replace("-", "_")
            // => Normalise: "new-pricing-algorithm" → "FEATURE_FLAG_NEW_PRICING_ALGORITHM"
            let value  = System.Environment.GetEnvironmentVariable(envKey)
            // => Read from process environment — null if not set
            return value = "true"
            // => true only when the env var is literally "true"; absent or "false" → off
        }
 
// ── Map-based test adapter ────────────────────────────────────────────────────
// Returns a predefined map of flags — no environment setup required in tests.
// Each test can enable or disable specific flags independently.
let mapFlagAdapter (flags: Map<string, bool>) : IsFeatureEnabled =
    fun flagName ->
        async {
            return Map.tryFind flagName flags |> Option.defaultValue false
            // => tryFind: returns Some true/false if key present; None if absent
            // => defaultValue false: absent flag defaults to off — safe default
        }
// => mapFlagAdapter: creates an adapter from a plain immutable Map
// => Tests compose: mapFlagAdapter (Map.ofList [("new-pricing-algorithm", true)])
 
// ── Application service using the feature flag port ───────────────────────────
// The application service calls isFeatureEnabled to choose a code path.
// Feature flag guards application behaviour — never domain rules.
// Domain functions are always correct; the flag selects WHICH domain function to call.
let calculateOrderTotal (isFeatureEnabled: IsFeatureEnabled) (quantity: decimal) (unitPrice: decimal) =
    async {
        let! useNewAlgorithm = isFeatureEnabled "new-pricing-algorithm"
        // => Await flag evaluation — may be a remote call in production
        // => useNewAlgorithm: bool — true if the new algorithm should run
        if useNewAlgorithm then
            // => New algorithm: volume discount applied above 10 units
            let discount = if quantity > 10m then 0.9m else 1.0m
            // => discount: 10% off for orders > 10 units; no discount otherwise
            return quantity * unitPrice * discount
            // => Total with optional volume discount
        else
            // => Legacy algorithm: no discount, simple multiplication
            return quantity * unitPrice
            // => Total: simple quantity × unit price, no discounting logic
    }
// => The application service selects the algorithm; both algorithms live in the domain
// => Feature flag is invisible to domain functions — they never call isFeatureEnabled
 
// ── Demonstration with test adapters ──────────────────────────────────────────
let flagOn  = mapFlagAdapter (Map.ofList [("new-pricing-algorithm", true)])
// => flagOn: adapter where new-pricing-algorithm is enabled
let flagOff = mapFlagAdapter (Map.ofList [])
// => flagOff: empty map — all flags off; absent flag defaults to false
 
let totalWithNew   = calculateOrderTotal flagOn  15m 10m |> Async.RunSynchronously
// => 15 units × 10.00 × 0.90 (volume discount) = 135.00
printfn "New algorithm:    %M" totalWithNew
// => Output: New algorithm:    135.0000000000000000000000000
 
let totalWithLegacy = calculateOrderTotal flagOff 15m 10m |> Async.RunSynchronously
// => 15 units × 10.00 (no discount) = 150.00
printfn "Legacy algorithm: %M" totalWithLegacy
// => Output: Legacy algorithm: 150.0000000000000000000000000

open System
 
// ── Cache port ──────────────────────────────────────────────────────────────────
// CachePort is a generic record of two functions — Get and Set.
// Generic over key type 'k and value type 'v: works for products, prices, or any domain value.
// Async: cache backends (Redis, Memcached) require async I/O.
type CachePort<'k, 'v> = {
    Get : 'k -> Async<'v option>
    // => Get: look up by key — returns Some value on hit, None on miss
    // => Option not Result: cache miss is not an error; the caller falls back to the source
    Set : 'k * 'v * TimeSpan -> Async<unit>
    // => Set: store key-value with a TTL — unit return, fire-and-forget semantics
    // => TimeSpan TTL: how long the cached value is valid before expiry
}
// => No error type: cache failures are silent; the application falls back to the source port
// => Silent failure is acceptable: a broken cache causes a performance degradation, not a correctness failure
 
// ── Repository port (the slow source) ─────────────────────────────────────────
// FindProduct is the database-backed port — slow, authoritative source of truth.
// Result: the database may fail with a named error; the cache never surfaces this error.
type FindProduct = string -> Async<Result<decimal, string>>
// => Input: product code (SKU)
// => Output: Ok unitPrice on success, Error message on database failure
 
// ── Cached wrapper using partial application ───────────────────────────────────
// cachedFindProduct checks cache, falls back to repo, and populates cache on miss.
// The wrapper is transparent: callers receive the same FindProduct type.
// Composition: cache port + repo port + TTL → new FindProduct with same signature.
let cachedFindProduct (cache: CachePort<string, decimal>) (repo: FindProduct) (ttl: TimeSpan) : FindProduct =
    fun productCode ->
        // => productCode: the SKU to look up — checked in cache before hitting the repo
        async {
            let! cached = cache.Get productCode
            // => Cache lookup: Async<decimal option> — None on miss, Some price on hit
            match cached with
            | Some price ->
                // => Cache hit: return immediately — no database call made
                // => Latency: microseconds (Redis) vs milliseconds (Postgres)
                return Ok price
            | None ->
                // => Cache miss: fall through to the database-backed repository
                let! repoResult = repo productCode
                // => repoResult: Result<decimal, string> — from the real database adapter
                match repoResult with
                | Ok price ->
                    do! cache.Set (productCode, price, ttl)
                    // => Populate cache for future calls — TTL controls freshness window
                    // => do!: fire-and-forget; a cache write failure does not block the response
                    return Ok price
                    // => Return the price from the database — caller sees Ok price regardless of cache path
                | Error e ->
                    // => Database also failed — surface the error to the caller
                    // => Cache is NOT populated: we do not cache errors
                    return Error e
        }
// => cachedFindProduct returns a FindProduct — same type as the raw repo adapter
// => Application service cannot distinguish: transparent wrapping via partial application
 
// ── In-memory cache adapter ────────────────────────────────────────────────────
// Dictionary-backed cache — correct for single-process use; not distributed.
// Factory function: each test gets a fresh, isolated cache instance.
let makeInMemoryCache<'k, 'v when 'k : comparison> () : CachePort<'k, 'v> =
    let store = System.Collections.Generic.Dictionary<'k, 'v>()
    // => Dictionary: mutable, O(1) lookup — acceptable in the adapter zone
    {
        Get = fun key ->
            async {
                match store.TryGetValue(key) with
                | true,  v -> return Some v
                // => Cache hit: key found in dictionary — return Some value
                | false, _ -> return None
                // => Cache miss: key absent — caller should fall back to source
            }
        Set = fun (key, value, _ttl) ->
            async {
                store.[key] <- value
                // => Store key-value pair — in-memory TTL ignored for simplicity
                // => Real Redis adapter would use SETEX with the TTL
            }
    }
 
// ── Stub repository adapter ────────────────────────────────────────────────────
// Simulates a slow database call — always returns Ok for the demo SKUs.
let stubRepo : FindProduct =
    fun code ->
        async {
            // => Simulates 50ms database latency — replaced by real Postgres adapter in production
            let prices = Map.ofList [("SKU-42", 29.97m); ("SKU-99", 9.99m)]
            // => In-memory price catalogue — real adapter queries the products table
            return
                match Map.tryFind code prices with
                | Some p -> Ok p
                | None   -> Error (sprintf "Product not found: %s" code)
        }
 
// ── Composition root: wire cache + repo ───────────────────────────────────────
let cache = makeInMemoryCache<string, decimal> ()
// => Fresh cache instance — empty at start, populated on first cache miss
let findProduct = cachedFindProduct cache stubRepo (TimeSpan.FromMinutes 5.0)
// => findProduct: FindProduct — application service uses this; unaware of cache
 
// ── Demonstration ─────────────────────────────────────────────────────────────
let price1 = findProduct "SKU-42" |> Async.RunSynchronously
// => First call: cache miss → repo hit → cache populated; returns Ok 29.97M
printfn "First call (miss): %A" price1
// => Output: First call (miss): Ok 29.97M
 
let price2 = findProduct "SKU-42" |> Async.RunSynchronously
// => Second call: cache hit → returns Ok 29.97M without touching the repo
printfn "Second call (hit): %A" price2
// => Output: Second call (hit): Ok 29.97M

// Domain tests call pure domain functions directly.
// No ports, no Async, no database, no mocking framework — just F# values.
// These tests run in microseconds; a suite of 500 domain tests takes under a second.
 
type UnvalidatedOrder = { OrderId: string; Quantity: decimal }
// => Input type: raw data from any delivery mechanism before domain validation
type ValidatedOrder   = { OrderId: string; Quantity: decimal }
// => Output type: validated — structurally identical here but semantically distinct
 
type ValidationError = BlankOrderId | NonPositiveQuantity
// => Domain error DU: each failure mode named — no string messages, no exceptions
 
let validateOrder (input: UnvalidatedOrder) : Result<ValidatedOrder, ValidationError> =
    if System.String.IsNullOrWhiteSpace(input.OrderId) then Error BlankOrderId
    // => Domain rule 1: blank OrderId is always rejected
    elif input.Quantity <= 0m then Error NonPositiveQuantity
    // => Domain rule 2: non-positive quantity violates business invariant
    else Ok { OrderId = input.OrderId; Quantity = input.Quantity }
    // => Validation passed: return validated state
 
// Domain tests — call validateOrder directly, no infrastructure involved
let testValidOrder = validateOrder { OrderId = "ORD-1"; Quantity = 3m }
// => Ok { OrderId = "ORD-1"; Quantity = 3M } — valid input accepted
printfn "Valid:    %A" testValidOrder
// => Output: Valid:    Ok { OrderId = "ORD-1"; Quantity = 3M }
 
let testBlankId = validateOrder { OrderId = "   "; Quantity = 3m }
// => Error BlankOrderId — whitespace-only OrderId rejected
printfn "BlankId:  %A" testBlankId
// => Output: BlankId:  Error BlankOrderId
 
let testZeroQty = validateOrder { OrderId = "ORD-2"; Quantity = 0m }
// => Error NonPositiveQuantity — zero quantity rejected
printfn "ZeroQty:  %A" testZeroQty
// => Output: ZeroQty:  Error NonPositiveQuantity

open FsToolkit.ErrorHandling
 
// Application tests wire the application service with in-memory port adapters.
// No real database, no real SMTP — just dictionary and list adapters.
// These tests run in milliseconds; they verify orchestration logic.
 
type Order       = { OrderId: string; Quantity: decimal; SavedAt: System.DateTimeOffset }
// => Order: application-layer record — carries the domain data plus the timestamp from the clock port
type AppError    = ValidationFailed of string | SaveFailed of string
// => AppError: DU — two failure modes; ValidationFailed from domain, SaveFailed from the output port
type SaveOrder   = Order -> Async<Result<unit, AppError>>
// => SaveOrder: output port type alias — any function matching this signature satisfies the port
type GetCurrentTime = unit -> System.DateTimeOffset
// => GetCurrentTime: clock port — injected so tests can substitute a fixed instant
 
// In-memory save adapter: records saved orders for assertion
let makeInMemorySave () =
    let store = System.Collections.Generic.List<Order>()
    // => Mutable list — captures every saved order in insertion order
    let save : SaveOrder = fun order -> async { store.Add(order); return Ok () }
    // => save: satisfies SaveOrder port — always succeeds in the in-memory adapter
    save, (fun () -> store |> Seq.toList)
    // => Returns both the port and a read accessor for test assertions
 
// Fixed clock adapter: deterministic timestamp for tests
let fixedClock : GetCurrentTime = fun () -> System.DateTimeOffset(2026, 1, 1, 0, 0, 0, System.TimeSpan.Zero)
// => Always returns 2026-01-01T00:00:00Z — every test run agrees on "now"
 
// Application service (simplified): validates, timestamps, saves
let placeOrder (getClock: GetCurrentTime) (saveOrder: SaveOrder) (orderId: string) (qty: decimal) =
    asyncResult {
        if System.String.IsNullOrWhiteSpace(orderId) then
            return! Error (ValidationFailed "OrderId blank") |> async.Return
        // => Domain validation: blank OrderId rejected before saving
        let now = getClock ()
        // => Clock port: deterministic in tests, real-time in production
        let order = { OrderId = orderId; Quantity = qty; SavedAt = now }
        // => Construct the order with the timestamp from the clock port
        do! saveOrder order
        // => Output port: persist; application tests use in-memory adapter
        return order
        // => Return the saved order to the caller
    }
 
// Application test using in-memory adapters
let saveFn, getSaved = makeInMemorySave ()
// => saveFn: the port; getSaved: the assertion accessor
let result = placeOrder fixedClock saveFn "ORD-001" 5m |> Async.RunSynchronously
// => Run synchronously for test simplicity; real tests use Async testing library
printfn "Result:  %A" result
// => Output: Result:  Ok { OrderId = "ORD-001"; Quantity = 5M; SavedAt = 2026-01-01T00:00:00+00:00 }
printfn "Saved:   %d orders" (getSaved () |> List.length)
// => Output: Saved:   1 orders

// Adapter tests use real (or embedded) infrastructure — the only tests that do so.
// In a real project: spin up a PostgreSQL container via TestContainers.
// Here: we illustrate the test shape without a live database.
 
// The adapter test asserts the mapping between domain types and the database schema.
// Real test body would use Npgsql or Dapper to write and read the row.
let runAdapterTest (postgresConnectionString: string) =
    async {
        // Step 1: create the adapter under test using the real connection string
        // let repo = PostgresOrderRepository(postgresConnectionString)
        // => In a real test: connect to the TestContainers Postgres instance
 
        // Step 2: save a domain value through the adapter
        // do! repo.Save { OrderId = "ORD-TEST"; Quantity = 7m; SavedAt = DateTimeOffset.UtcNow }
        // => Real adapter: INSERT INTO orders (order_id, quantity, saved_at) VALUES (...)
 
        // Step 3: load the saved value and assert round-trip fidelity
        // let! found = repo.FindById "ORD-TEST"
        // => Real adapter: SELECT * FROM orders WHERE order_id = 'ORD-TEST'
 
        // Step 4: assert domain type reconstruction
        // assert (found = Ok (Some { OrderId = "ORD-TEST"; Quantity = 7m; ... }))
        // => Verifies the column mapping is correct — no data lost or transformed
 
        printfn "Adapter test shape illustrated — real test requires live Postgres"
        // => In CI: TestContainers starts Postgres before this test and cleans up after
    }
// => Adapter tests are FEW and SLOW — one test covers the full round-trip per adapter
// => All other tests (domain + application) run without any real infrastructure
printfn "Three test levels: domain (fast, pure), application (medium, in-memory), adapter (slow, real infra)"
// => Output: Three test levels: domain (fast, pure), application (medium, in-memory), adapter (slow, real infra)

// ── Domain types ───────────────────────────────────────────────────────────────
type UnvalidatedOrder = { OrderId: string; ProductCode: string; Quantity: decimal }
// => Raw input: no type guarantees; any string is accepted by the record constructor
type ValidatedOrder   = { OrderId: string; ProductCode: string; Quantity: decimal }
// => Post-validation state: same fields but semantically guaranteed by the type transition
 
type DomainError =
    // => Discriminated union — every branch is a named business rule violation
    | BlankOrderId
    // => Business rule: order identity must not be blank or whitespace
    | NonPositiveQuantity
    // => Business rule: quantity must be strictly positive
    | InvalidProductCode of string
    // => Business rule: product code must match the expected format (non-empty for this example)
    | NegativeUnitPrice of decimal
    // => Business rule: unit price must be positive; pricing function rejects zero or negative
 
// ── Pure domain functions ───────────────────────────────────────────────────────
let validateOrder (input: UnvalidatedOrder) : Result<ValidatedOrder, DomainError> =
    // => Pure function: takes UnvalidatedOrder, returns Result — no I/O, no Async
    if System.String.IsNullOrWhiteSpace(input.OrderId) then
        // => Rule 1: OrderId must not be blank
        Error BlankOrderId
        // => Reject: blank or whitespace-only OrderId violates the identity invariant
    elif input.Quantity <= 0m then
        // => Rule 2: Quantity must be strictly positive
        Error NonPositiveQuantity
        // => Reject: zero or negative quantity violates the quantity invariant
    elif System.String.IsNullOrWhiteSpace(input.ProductCode) then
        // => Rule 3: ProductCode must not be blank
        Error (InvalidProductCode input.ProductCode)
        // => Reject: blank product code; real rule might match a regex pattern
    else
        Ok { OrderId = input.OrderId; ProductCode = input.ProductCode; Quantity = input.Quantity }
        // => All rules passed: return the validated state type
 
let priceOrder (unitPrice: decimal) (validated: ValidatedOrder) : Result<decimal, DomainError> =
    // => Pure pricing function: multiplies quantity by unit price
    if unitPrice <= 0m then
        Error (NegativeUnitPrice unitPrice)
        // => Pricing rule: non-positive unit price is a programming error — reject explicitly
    else
        Ok (validated.Quantity * unitPrice)
        // => Total = quantity × unit price — pure arithmetic, no I/O
 
// ── Domain tests — no ports, no Async, no mocking ─────────────────────────────
// Each test is a plain let binding that evaluates a domain function and prints the result.
// In a real project: use Expecto or xUnit with Assert.Equal; no test runner needed here.
 
let case1 = validateOrder { OrderId = "ORD-1"; ProductCode = "SKU-42"; Quantity = 3m }
// => case1 : Result<ValidatedOrder, DomainError>
// => Happy path: all rules satisfied
printfn "Case 1 (valid):           %A" case1
// => Output: Case 1 (valid):           Ok { OrderId = "ORD-1"; ProductCode = "SKU-42"; Quantity = 3M }
 
let case2 = validateOrder { OrderId = "   "; ProductCode = "SKU-42"; Quantity = 3m }
// => BlankOrderId: whitespace-only OrderId — the first rule fires
printfn "Case 2 (blank OrderId):   %A" case2
// => Output: Case 2 (blank OrderId):   Error BlankOrderId
 
let case3 = validateOrder { OrderId = "ORD-2"; ProductCode = "SKU-42"; Quantity = 0m }
// => NonPositiveQuantity: zero quantity — the second rule fires
printfn "Case 3 (zero quantity):   %A" case3
// => Output: Case 3 (zero quantity):   Error NonPositiveQuantity
 
let case4 = validateOrder { OrderId = "ORD-3"; ProductCode = ""; Quantity = 5m }
// => InvalidProductCode: blank product code — the third rule fires
printfn "Case 4 (blank product):   %A" case4
// => Output: Case 4 (blank product):   Error (InvalidProductCode "")
 
let case5 =
    validateOrder { OrderId = "ORD-4"; ProductCode = "SKU-99"; Quantity = 10m }
    |> Result.bind (priceOrder 0m)
    // => Validation passes; priceOrder rejects zero unit price
printfn "Case 5 (zero price):      %A" case5
// => Output: Case 5 (zero price):      Error (NegativeUnitPrice 0M)
 
let case6 =
    // => case6 : Result<decimal, DomainError> — chained validation then pricing
    validateOrder { OrderId = "ORD-5"; ProductCode = "SKU-99"; Quantity = 10m }
    |> Result.bind (priceOrder 29.97m)
    // => Full happy path: validate then price; both succeed
printfn "Case 6 (full happy path): %A" case6
// => Output: Case 6 (full happy path): Ok 299.700000000000000000000000000

open FsToolkit.ErrorHandling
 
// ── Domain and application types ───────────────────────────────────────────────
type OrderId    = string
// => Simple alias — distinguishes order identities from other string fields
type Order      = { OrderId: OrderId; Quantity: decimal; PlacedAt: System.DateTimeOffset }
// => Domain aggregate used by both save port and returned to caller
type AppError   = | ValidationFailed of string | SaveFailed of string | NotifyFailed of string
// => Named failures — each branch corresponds to one distinct failure mode
 
// ── Port types ──────────────────────────────────────────────────────────────────
type SaveOrder        = Order -> Async<Result<unit, AppError>>
// => Output port: persist the order — satisfied by InMemoryOrderRepository or Postgres adapter
type SendConfirmation = OrderId -> Async<Result<unit, AppError>>
// => Output port: notify customer — satisfied by FakeNotificationPort or SMTP adapter
type GetCurrentTime   = unit -> System.DateTimeOffset
// => Output port: injectable clock — satisfied by FixedClock or system clock
 
// ── Application service ─────────────────────────────────────────────────────────
// placeOrder orchestrates: validate → timestamp → save → notify
// All I/O is behind ports — the service has no direct infrastructure calls.
let placeOrder (getClock: GetCurrentTime) (saveOrder: SaveOrder) (sendConfirmation: SendConfirmation) (orderId: OrderId) (qty: decimal) =
    asyncResult {
        if System.String.IsNullOrWhiteSpace(orderId) then
            return! Error (ValidationFailed "OrderId blank") |> async.Return
        // => Domain validation: fail fast before any I/O
        let now = getClock ()
        // => Clock port: 2026-01-01 in tests; DateTimeOffset.UtcNow in production
        let order = { OrderId = orderId; Quantity = qty; PlacedAt = now }
        // => Construct the order with the deterministic timestamp
        do! saveOrder order
        // => Persist via output port — in-memory in tests, Postgres in production
        do! sendConfirmation orderId
        // => Notify via output port — fake list in tests, SMTP in production
        return order
        // => Return the placed order on the Ok track
    }
 
// ── In-memory repository (satisfies SaveOrder) ────────────────────────────────
let makeInMemoryRepo () =
    let store = System.Collections.Generic.Dictionary<OrderId, Order>()
    // => Mutable dictionary — isolated per test via factory function
    let save : SaveOrder =
        fun order -> async { store.[order.OrderId] <- order; return Ok () }
    // => save: upsert semantics; always Ok in the in-memory adapter
    save, (fun () -> store.Values |> Seq.toList)
    // => Returns the port and a read accessor for assertions
 
// ── Fake notification port (satisfies SendConfirmation) ───────────────────────
let makeInMemoryNotifier () =
    let sent = System.Collections.Generic.List<OrderId>()
    // => Records every notified OrderId in insertion order
    let notify : SendConfirmation =
        fun orderId -> async { sent.Add(orderId); return Ok () }
    // => notify: satisfies SendConfirmation — always Ok; no real SMTP
    notify, (fun () -> sent |> Seq.toList)
    // => Returns the port and a read accessor for assertions
 
// ── Fixed clock adapter ────────────────────────────────────────────────────────
let fixedClock : GetCurrentTime =
    fun () -> System.DateTimeOffset(2026, 1, 1, 0, 0, 0, System.TimeSpan.Zero)
// => Always 2026-01-01T00:00:00Z — test assertions can use this literal value
 
// ── Application test ────────────────────────────────────────────────────────────
let saveFn,   getSaved     = makeInMemoryRepo ()
// => saveFn: the port; getSaved: the assertion accessor for repository state
let notifyFn, getNotified  = makeInMemoryNotifier ()
// => notifyFn: the port; getNotified: the assertion accessor for sent notifications
 
// Partially apply all ports and adapters — same pattern as the composition root
let placeOrderWithAdapters = placeOrder fixedClock saveFn notifyFn
// => placeOrderWithAdapters: OrderId -> decimal -> Async<Result<Order, AppError>>
 
let result = placeOrderWithAdapters "ORD-001" 5m |> Async.RunSynchronously
// => Run the full application service pipeline with in-memory adapters
printfn "Result:         %A" result
// => Output: Result:         Ok { OrderId = "ORD-001"; Quantity = 5M; PlacedAt = 2026-01-01T00:00:00+00:00 }
 
printfn "Saved orders:   %d" (getSaved () |> List.length)
// => Output: Saved orders:   1
printfn "Notifications:  %A" (getNotified ())
// => Output: Notifications:  ["ORD-001"]
 
// Assertion: validation failure path
let failResult = placeOrderWithAdapters "  " 5m |> Async.RunSynchronously
// => Blank OrderId: validation fires before any port is called
printfn "Fail result:    %A" failResult
// => Output: Fail result:    Error (ValidationFailed "OrderId blank")
printfn "Saved on fail:  %d" (getSaved () |> List.length)
// => Output: Saved on fail:  1  (still 1 — the failure case did not save)