Intermediate

// >> is the forward composition operator: f >> g means "apply f then g".
// Each step is a pure function; the pipeline is their composition.
 
// Individual pipeline steps — each is a pure function, independently testable
let trimInput (s: string) : string =
    s.Trim()
    // => Removes leading and trailing whitespace
 
let toUpperCase (s: string) : string =
    s.ToUpperInvariant()
    // => Normalises to uppercase for consistent storage
 
let addPrefix (s: string) : string =
    "ORD-" + s
    // => Applies the order ID prefix convention
 
// Composing three steps into one function using >>
let normaliseOrderId: string -> string =
    trimInput >> toUpperCase >> addPrefix
    // => Reads left to right: trim, then uppercase, then prefix
    // => normaliseOrderId : string -> string — three functions become one
 
// Test the composed function
let raw = "  oo1234  "
// => raw : string = "  oo1234  " — has leading/trailing whitespace and lowercase
let normalised = normaliseOrderId raw
// => Step 1: trimInput "  oo1234  " = "oo1234"
// => Step 2: toUpperCase "oo1234" = "OO1234"
// => Step 3: addPrefix "OO1234" = "ORD-OO1234"
// => normalised = "ORD-OO1234"
 
printfn "Raw: '%s'" raw
// => Output: Raw: '  oo1234  '
 
printfn "Normalised: '%s'" normalised
// => Output: Normalised: 'ORD-OO1234'
 
// Each step can be tested independently
printfn "Trim step: '%s'" (trimInput raw)
// => Output: Trim step: 'oo1234'

// |> pipes a value through a series of functions — reads like natural language.
// Eliminates deeply nested function calls and intermediate variable names.
 
// Without pipe — reads inside-out, harder to follow
let withoutPipe =
    List.sum (List.map (fun x -> x * x) (List.filter (fun x -> x % 2 = 0) [1..10]))
    // => Nested calls: filter, then map, then sum — but written innermost-first
    // => withoutPipe = 220 — same result but harder to read
 
// With pipe — reads left to right, matches the order of operations
let withPipe =
    [1..10]
    // => Input: integers 1 through 10
    |> List.filter (fun x -> x % 2 = 0)
    // => [2; 4; 6; 8; 10] — keep even numbers
    |> List.map (fun x -> x * x)
    // => [4; 16; 36; 64; 100] — square each even number
    |> List.sum
    // => 4 + 16 + 36 + 64 + 100 = 220 — sum all squared evens
    // => withPipe = 220
 
printfn "Without pipe: %d" withoutPipe
// => withoutPipe = 220 — same result as withPipe
// => Output: Without pipe: 220
 
printfn "With pipe: %d" withPipe
// => withPipe = 220 — identical result, more readable code
// => Output: With pipe: 220
 
// Domain example: transforming an order ID
let processOrderId (raw: string) =
    raw
    |> fun s -> s.Trim()
    // => Remove whitespace
    |> fun s -> s.ToUpperInvariant()
    // => Normalise case
    |> fun s -> if s.Length > 0 then Some s else None
    // => Return None for blank input
 
printfn "Processed: %A" (processOrderId "  ord-001  ")
// => Output: Processed: Some "ORD-001"
 
printfn "Processed empty: %A" (processOrderId "   ")
// => Output: Processed empty: None

// Every F# function is curried: multi-arg functions are actually one-arg functions
// returning functions. This enables partial application and composition.
 
// A two-argument function
let add (x: int) (y: int) : int =
    x + y
    // => add : int -> int -> int
    // => Read as: "given an int, return a function (int -> int)"
 
// Partially apply: provide only the first argument
let addFive = add 5
// => addFive : int -> int — a new function with x=5 captured
// => addFive y = add 5 y = 5 + y
 
printfn "add 3 4 = %d" (add 3 4)
// => Output: add 3 4 = 7
 
printfn "addFive 10 = %d" (addFive 10)
// => Output: addFive 10 = 15
 
// Domain example: validation function with a product lookup dependency
let validateProductCode (lookupProduct: string -> bool) (code: string) : Result<string, string> =
    // => lookupProduct: injected dependency — checks catalogue
    // => code: the product code to validate
    if lookupProduct code then
        Ok code
        // => Product exists in catalogue — validation passes
    else
        Error (sprintf "Product code '%s' not found in catalogue" code)
        // => Product not found — validation fails
 
// Partially apply the lookup function to create a reusable validator
let validateWithRealLookup = validateProductCode (fun code -> code.StartsWith("W") || code.StartsWith("G"))
// => validateWithRealLookup : string -> Result<string, string>
// => The lookup function is "baked in" — only the code argument remains
 
printfn "%A" (validateWithRealLookup "W1234")
// => Output: Ok "W1234"
 
printfn "%A" (validateWithRealLookup "X999")
// => Output: Error "Product code 'X999' not found in catalogue"

// Partial application as DI: inject dependencies by partially applying functions.
// The result is a function with the same signature as the workflow step type.
 
// Infrastructure function signatures (interfaces as function types)
type CheckProductCodeExists = string -> bool
// => "Given a product code, does it exist?" — a dependency
// => bool return: true = exists, false = not in catalogue
 
type GetProductPrice = string -> Result<decimal, string>
// => "Given a product code, what is the price?" — another dependency
// => Result because price lookup can fail (product in catalogue but no price)
 
// Workflow step that depends on both functions
let validateAndPriceItem
    (checkExists: CheckProductCodeExists)
    // => First argument: the product lookup dependency
    (getPrice: GetProductPrice)
    // => Second argument: the price lookup dependency
    (code: string)
    // => Third argument: the product code to validate and price
    (qty: int)
    // => Fourth argument: the quantity to multiply by
    : Result<decimal, string> =
    // => Returns the line total (Ok) or an error if product not found or price missing
    if not (checkExists code) then
        Error (sprintf "Product '%s' not found" code)
        // => First dependency used — product existence check
        // => Short-circuits: no point looking up price if product doesn't exist
    else
        getPrice code
        // => Second dependency used — price lookup
        |> Result.map (fun unitPrice -> unitPrice * decimal qty)
        // => Result.map: if Ok, multiply unit price by quantity; if Error, propagate
        // => Second dependency used — price lookup, then multiply by quantity
 
// Production partial application — inject real implementations
let realCheckExists : CheckProductCodeExists = fun code ->
    code.StartsWith("W") || code.StartsWith("G")
    // => "W" prefix = Widget; "G" prefix = Gizmo — both are valid product codes
    // => Real implementation: checks code format (simplified)
 
let realGetPrice : GetProductPrice = fun code ->
    if code.StartsWith("W") then Ok 9.99m
    // => Widget price: £9.99
    elif code.StartsWith("G") then Ok 24.99m
    // => Gizmo price: £24.99
    else Error "Unknown product type"
    // => Real implementation: price by product type
 
// Partially apply to create the production version
let validateAndPriceProd = validateAndPriceItem realCheckExists realGetPrice
// => validateAndPriceProd : string -> int -> Result<decimal, string>
// => Dependencies are baked in — only domain arguments remain
// => Calling validateAndPriceProd "W1234" 3 = 9.99 × 3 = Ok 29.97M
 
// Test version with stub dependencies
let validateAndPriceTest = validateAndPriceItem (fun _ -> true) (fun _ -> Ok 5.00m)
// => Stubs: always exists, always £5.00 — simple lambdas, no mocking framework needed
// => Simplified stubs for testing — no mocking framework needed
 
printfn "Prod result: %A" (validateAndPriceProd "W1234" 3)
// => realCheckExists "W1234" = true; realGetPrice "W1234" = Ok 9.99; 9.99 × 3 = 29.97
// => Output: Prod result: Ok 29.97M
 
printfn "Test result: %A" (validateAndPriceTest "ANYTHING" 2)
// => stub exists "ANYTHING" = true; stub price "ANYTHING" = Ok 5.00; 5.00 × 2 = 10.00
// => Output: Test result: Ok 10.00M

// Result.map transforms the Ok value; Result.mapError transforms the Error value.
// Neither function touches the other case.
 
// Result.map: apply a function inside Ok, pass Error through unchanged
let doubled = Result.map (fun x -> x * 2) (Ok 21)
// => doubled : Result<int, 'a> = Ok 42
// => The function (x * 2) was applied to 21 inside the Ok
 
let mapOnError = Result.map (fun x -> x * 2) (Error "something went wrong")
// => mapOnError : Result<int, string> = Error "something went wrong"
// => Error case is passed through — the function is NOT called
 
printfn "map Ok: %A" doubled
// => Output: map Ok: Ok 42
 
printfn "map Error: %A" mapOnError
// => Output: map Error: Error "something went wrong"
 
// Result.mapError: transform the Error value, pass Ok through unchanged
let uppercaseError = Result.mapError (fun e -> e.ToString().ToUpperInvariant()) (Error "invalid input")
// => uppercaseError : Result<'a, string> = Error "INVALID INPUT"
// => The function was applied to the error message
 
let mapErrorOnOk = Result.mapError (fun e -> e.ToString().ToUpperInvariant()) (Ok 42)
// => mapErrorOnOk : Result<int, string> = Ok 42
// => Ok case is passed through — the function is NOT called
 
printfn "mapError Error: %A" uppercaseError
// => Output: mapError Error: Error "INVALID INPUT"
 
printfn "mapError Ok: %A" mapErrorOnOk
// => Output: mapError Ok: Ok 42
 
// Practical: transform a domain error to an API error at the boundary
type DomainError = | ValidationError of string | ProductNotFound of string
type ApiError    = | BadRequest of string | NotFound of string
 
let mapToApiError (e: DomainError) : ApiError =
    match e with
    | ValidationError msg   -> BadRequest msg
    // => Domain validation errors become HTTP 400
    | ProductNotFound code  -> NotFound (sprintf "Product '%s' not found" code)
    // => Domain not-found errors become HTTP 404
 
let domainResult : Result<string, DomainError> = Error (ValidationError "OrderId blank")
// => domainResult : Result<string, DomainError> = Error (ValidationError "OrderId blank")
let apiResult = domainResult |> Result.mapError mapToApiError
// => Result.mapError applies mapToApiError to the Error case
// => ValidationError "OrderId blank" → BadRequest "OrderId blank"
// => apiResult : Result<string, ApiError> = Error (BadRequest "OrderId blank")
 
printfn "API error: %A" apiResult
// => Output: API error: Error (BadRequest "OrderId blank")

// Result.bind: chain a fallible function onto an existing Result.
// Error short-circuits; Ok flows forward.
 
// Three fallible validation steps
let validateOrderId (raw: string) : Result<string, string> =
    // => Returns Ok trimmed id, or Error with a diagnostic message
    if System.String.IsNullOrWhiteSpace(raw) then Error "OrderId must not be blank"
    // => Guard 1: blank or whitespace ID rejected immediately
    elif raw.Length > 50 then Error "OrderId too long"
    // => Guard 2: IDs over 50 chars rejected (domain rule)
    else Ok (raw.Trim())
    // => Returns Ok with the trimmed id, or Error with a message
 
let validateCustomerName (raw: string) : Result<string, string> =
    // => Returns Ok trimmed name, or Error if blank
    if System.String.IsNullOrWhiteSpace(raw) then Error "CustomerName must not be blank"
    // => Guard: blank name is not valid in the domain
    else Ok (raw.Trim())
    // => Returns Ok with the trimmed name, or Error
 
let validateQuantity (qty: int) : Result<int, string> =
    // => Returns Ok with the quantity, or Error if zero or negative
    if qty <= 0 then Error (sprintf "Quantity must be positive (got %d)" qty)
    // => Guard: zero or negative quantity violates the positive-quantity invariant
    else Ok qty
    // => Returns Ok with the quantity, or Error
 
// Chaining with Result.bind — steps execute only if the previous succeeded
let validateOrder orderId customerName quantity =
    validateOrderId orderId
    // => Step 1: validate order ID — if this fails, steps 2 and 3 are skipped
    |> Result.bind (fun validId ->
        // => bind: validId is the unwrapped Ok value from step 1
        validateCustomerName customerName
        // => Step 2: validate customer name — only runs if step 1 returned Ok
        |> Result.map (fun validName -> (validId, validName)))
        // => Result.map pairs validId and validName in a tuple — no failure here
    // => bind: apply the next fallible step only if validateOrderId succeeded
    |> Result.bind (fun (validId, validName) ->
        // => bind: (validId, validName) unwrapped from the tuple in the Ok
        validateQuantity quantity
        // => Step 3: validate quantity — only runs if steps 1 and 2 returned Ok
        |> Result.map (fun validQty -> (validId, validName, validQty)))
        // => Result.map assembles the final triple — all three validated values
    // => bind again: chain the third step
 
let success = validateOrder "ORD-001" "Alice Johnson" 3
// => All three steps returned Ok — the tuple is assembled
// => success : Result<string * string * int, string> = Ok ("ORD-001", "Alice Johnson", 3)
 
let failure = validateOrder "" "Alice Johnson" 3
// => Step 1 failed: empty string → Error "OrderId must not be blank"
// => failure : Result<string * string * int, string> = Error "OrderId must not be blank"
// => Short-circuited after the first Error — later steps were not called
 
printfn "Success: %A" success
// => Output: Success: Ok ("ORD-001", "Alice Johnson", 3)
 
printfn "Failure: %A" failure
// => Output: Failure: Error "OrderId must not be blank"

// Railway-Oriented Programming: two tracks, switch functions, and a full pipeline.
// The "railway" metaphor: Ok track = happy path, Error track = failure path.
// Once on the Error track, all subsequent switches are bypassed automatically.
 
// ── Domain types ─────────────────────────────────────────────────────────
type UnvalidatedInput = { OrderId: string; Qty: int; ProductCode: string }
// => Raw input entering the railway — nothing trusted yet
 
type ValidatedInput   = { OrderId: string; Qty: int; ProductCode: string }
// => Input after validation — same shape, different type guarantees validity
// => If ValidatedInput exists, OrderId was non-blank and Qty was positive
 
type PricedInput      = { OrderId: string; Qty: int; ProductCode: string; Total: decimal }
// => Input after pricing — extended with the calculated total
// => If PricedInput exists, pricing has already been computed
 
// ── Switch functions — each can divert to the Error track ─────────────────
let validateInput (input: UnvalidatedInput) : Result<ValidatedInput, string> =
    // => Returns Ok to stay on the Ok track, or Error to divert to the Error track
    if System.String.IsNullOrWhiteSpace(input.OrderId) then Error "OrderId blank"
    // => Guard 1: blank OrderId — diverts to Error track immediately
    elif input.Qty <= 0 then Error "Quantity must be positive"
    // => Guard 2: non-positive quantity — diverts to Error track
    else Ok { OrderId = input.OrderId.Trim(); Qty = input.Qty; ProductCode = input.ProductCode }
    // => Both guards passed — stay on Ok track with the validated data
 
let priceInput (validated: ValidatedInput) : Result<PricedInput, string> =
    // => Only called if validateInput returned Ok — already on the Ok track
    let unitPrice = if validated.ProductCode.StartsWith "W" then 9.99m else 24.99m
    // => Look up price by product type: Widget £9.99, Gizmo £24.99
    if unitPrice <= 0m then Error "Invalid price"
    // => Safety guard — diverts to Error track (unreachable in this example but shows the pattern)
    else Ok { OrderId = validated.OrderId; Qty = validated.Qty
              ProductCode = validated.ProductCode; Total = unitPrice * decimal validated.Qty }
    // => Stay on Ok track — adds the calculated total to the record
 
let acknowledgeInput (priced: PricedInput) : Result<string, string> =
    // => Only called if both previous steps returned Ok
    Ok (sprintf "Order %s acknowledged — total £%.2f" priced.OrderId priced.Total)
    // => Terminal step — produces the confirmation string and stays on Ok track
 
// ── The full railway pipeline ─────────────────────────────────────────────
let placeOrder (input: UnvalidatedInput) : Result<string, string> =
    // => All three steps are wired together with Result.bind
    input
    |> validateInput
    // => Switch 1: validate or divert to Error track
    |> Result.bind priceInput
    // => Switch 2: price or divert — only executes if switch 1 returned Ok
    |> Result.bind acknowledgeInput
    // => Switch 3: acknowledge or divert — only executes if switch 2 returned Ok
 
// ── Three test cases: happy path and two failure paths ────────────────────
let goodInput   = { OrderId = "ORD-001"; Qty = 3;  ProductCode = "W1234" }
// => Valid input — all three switches will stay on the Ok track
let badOrderId  = { OrderId = "";        Qty = 3;  ProductCode = "W1234" }
// => Invalid: empty OrderId — switch 1 will divert to Error track
let badQuantity = { OrderId = "ORD-002"; Qty = -1; ProductCode = "W1234" }
// => Invalid: negative quantity — switch 1 will divert to Error track
 
printfn "Good:        %A" (placeOrder goodInput)
// => Output: Good:        Ok "Order ORD-001 acknowledged — total £29.97"
 
printfn "Bad orderId: %A" (placeOrder badOrderId)
// => Output: Bad orderId: Error "OrderId blank"
// => Switches 2 and 3 were never called — Error propagated straight through
 
printfn "Bad quantity:%A" (placeOrder badQuantity)
// => Output: Bad quantity:Error "Quantity must be positive"
// => Same short-circuit behaviour — early Error stops the pipeline

// The 'result' computation expression: imperative-looking code that is actually
// a chain of Result.bind calls — syntactic sugar for ROP.
 
// Define a minimal result computation expression builder
type ResultBuilder() =
    member _.Return(x) = Ok x
    // => Wraps a plain value in Ok
    member _.ReturnFrom(x) = x
    // => Passes a Result through as-is
    member _.Bind(x, f) = Result.bind f x
    // => Unwraps Ok and applies f; short-circuits on Error
    member _.Zero() = Ok ()
    // => Default for empty computation expressions
 
let result = ResultBuilder()
// => result : ResultBuilder — our CE builder instance
 
// Smart constructors (simplified)
let validateId (raw: string) =
    // => Returns Ok trimmed id if non-blank; Error if blank
    if System.String.IsNullOrWhiteSpace(raw) then Error "Id must not be blank"
    // => Guard: blank or whitespace strings are not valid IDs
    else Ok raw.Trim()
    // => Ok with trimmed string — normalised
 
let validateQty (qty: int) =
    // => Returns Ok qty if positive; Error if zero or negative
    if qty <= 0 then Error "Quantity must be positive"
    // => Guard: zero and negatives are not valid quantities
    else Ok qty
    // => Ok qty — passes through unchanged
 
let getUnitPrice (code: string) =
    // => Returns Ok price for known product codes; Error for unknown
    if code.StartsWith "W" then Ok 9.99m
    // => Widget codes start with "W" — price is £9.99
    elif code.StartsWith "G" then Ok 24.99m
    // => Gizmo codes start with "G" — price is £24.99
    else Error (sprintf "Unknown product: %s" code)
    // => Unknown code — returns Error with the code for diagnostics
 
// The computation expression — reads like sequential imperative code
let buildOrderTotal orderId qty productCode =
    result {
        let! validId    = validateId orderId
        // => let! desugars to .Bind(validateId orderId, fun validId -> ...)
        // => validId : string = orderId.Trim() if non-blank
        let! validQty   = validateQty qty
        // => Second validation — only reached if first succeeded
        // => validQty : int = qty if positive
        let! unitPrice  = getUnitPrice productCode
        // => Third step — only reached if both validations succeeded
        // => unitPrice : decimal = 9.99 for "W1234"
        let total = unitPrice * decimal validQty
        // => Plain let — no Result unwrapping needed; just arithmetic
        // => total = 9.99 × 3 = 29.97 for validQty=3
        return sprintf "Order %s total: £%.2f" validId total
        // => return desugars to .Return(...) which wraps in Ok
        // => return wraps the final value in Ok
    }
    // => Equivalent to: validateId >> Result.bind (fun id -> ...) >> Result.bind ...
 
printfn "%A" (buildOrderTotal "ORD-001" 3 "W1234")
// => All three validations pass; total = 9.99 × 3 = 29.97
// => Output: Ok "Order ORD-001 total: £29.97"
 
printfn "%A" (buildOrderTotal "" 3 "W1234")
// => Output: Error "Id must not be blank"
 
printfn "%A" (buildOrderTotal "ORD-002" 3 "X999")
// => Output: Error "Unknown product: X999"

// Async<Result<'a,'e>> = an asynchronous operation that can succeed or fail.
// asyncResult CE composes these cleanly.
 
// Simulate async I/O operations
let fetchCustomer (customerId: string) : Async<Result<string, string>> =
    async {
        // => Simulates an async database call
        if customerId = "CUST-42" then
            return Ok "Alice Johnson"
            // => Customer found
        else
            return Error (sprintf "Customer '%s' not found" customerId)
            // => Customer not in the database
    }
 
let fetchProductPrice (code: string) : Async<Result<decimal, string>> =
    async {
        // => Simulates an async price service call
        if code.StartsWith "W" then return Ok 9.99m
        // => Widget codes → £9.99 per unit
        elif code.StartsWith "G" then return Ok 24.99m
        // => Gizmo codes → £24.99 per unit
        else return Error (sprintf "No price for product '%s'" code)
        // => Unknown product code → Error; the workflow will short-circuit here
    }
 
// asyncResult CE builder — composes Async<Result> values with let!
type AsyncResultBuilder() =
    member _.Return(x)       = async { return Ok x }
    // => return: wrap a plain value in Ok and lift into Async
    member _.ReturnFrom(x)   = x
    // => return!: pass an existing Async<Result> through unchanged
    member _.Bind(x, f) =
        async {
            let! result = x
            // => Await the async operation — result : Result<'a, 'e>
            match result with
            | Ok v    -> return! f v
            // => If Ok, apply the next function (which is also Async<Result>)
            // => f v produces another Async<Result> that is awaited recursively
            | Error e -> return Error e
            // => If Error, short-circuit without calling f
            // => Error propagates all the way out of the asyncResult block
        }
 
let asyncResult = AsyncResultBuilder()
// => asyncResult : AsyncResultBuilder — the CE instance used below
// => CE syntax: `asyncResult { let! x = ... }` desugars to .Bind(x, ...) calls
 
// Full async workflow
let placeOrderAsync customerId productCode qty =
    asyncResult {
        let! customerName = fetchCustomer customerId
        // => Await fetchCustomer; customerName is the unwrapped string if Ok
        // => Await and unwrap — short-circuits on Error
        let! unitPrice    = fetchProductPrice productCode
        // => Await fetchProductPrice; only runs if customer fetch succeeded
        // => unitPrice is the unwrapped decimal if Ok
        // => Await and unwrap — only runs if customer fetch succeeded
        let total         = unitPrice * decimal qty
        // => Synchronous arithmetic — no Async or Result wrapping needed here
        // => total = 9.99 × 3 = 29.97 for W1234
        // => Synchronous arithmetic inside the async workflow
        return sprintf "Order for %s: £%.2f" customerName total
        // => return wraps the string in Ok and lifts into Async<Result>
        // => Wraps the result in Async<Result<string, string>>
    }
 
// Run the async workflow synchronously for demonstration
let resultOk = placeOrderAsync "CUST-42" "W1234" 3 |> Async.RunSynchronously
// => fetchCustomer "CUST-42" = Ok "Alice Johnson"
// => fetchProductPrice "W1234" = Ok 9.99
// => total = 9.99 × 3 = 29.97
// => resultOk : Result<string, string> = Ok "Order for Alice Johnson: £29.97"
 
let resultErr = placeOrderAsync "UNKNOWN" "W1234" 3 |> Async.RunSynchronously
// => fetchCustomer "UNKNOWN" = Error "Customer 'UNKNOWN' not found"
// => fetchProductPrice never called — short-circuited by the customer error
// => resultErr : Result<string, string> = Error "Customer 'UNKNOWN' not found"
 
printfn "Success: %A" resultOk
// => Output: Success: Ok "Order for Alice Johnson: £29.97"
 
printfn "Failure: %A" resultErr
// => Output: Failure: Error "Customer 'UNKNOWN' not found"

// AsyncResult module: wraps Async<Result<'a,'e>> with standard operations.
// Provides the building blocks for async workflow pipelines.
 
module AsyncResult =
    // Core operations as standalone functions — usable without a CE
    // => Mirrors the standard monadic operations: map, bind, return, ofResult
 
    let map (f: 'a -> 'b) (ar: Async<Result<'a,'e>>) : Async<Result<'b,'e>> =
        // => Transforms the Ok value; leaves Error unchanged
        async {
            let! r = ar
            // => Await the async operation; r : Result<'a,'e>
            return Result.map f r
            // => Apply f to Ok value, or pass Error through unchanged
            // => Transform the Ok value; leave Error unchanged
        }
 
    let bind (f: 'a -> Async<Result<'b,'e>>) (ar: Async<Result<'a,'e>>) : Async<Result<'b,'e>> =
        // => Chains two async fallible operations — the core of the CE
        async {
            let! r = ar
            // => Await first async operation; r : Result<'a,'e>
            match r with
            | Ok v    -> return! f v
            // => Ok: apply f and await the next async operation
            | Error e -> return Error e
            // => Error: short-circuit without calling f
        }
 
    let retn (x: 'a) : Async<Result<'a,'e>> =
        // => Lifts a pure value into Async<Result> — the "unit" of the monad
        async { return Ok x }
        // => Wrap x in Ok and immediately complete the async workflow
 
    let ofResult (r: Result<'a,'e>) : Async<Result<'a,'e>> =
        // => Lifts a synchronous Result into Async<Result> for uniform composition
        async { return r }
        // => The async computation immediately returns r — no actual I/O
        // => Enables mixing sync validation (via ofResult) with async I/O in the same pipeline
        // => Lift a synchronous Result into Async<Result>
 
// ── Workflow using the AsyncResult module ─────────────────────────────────
let validateAsync (orderId: string) : Async<Result<string, string>> =
    AsyncResult.ofResult (if orderId.Length > 0 then Ok orderId else Error "OrderId blank")
    // => Synchronous validation lifted into Async<Result>
    // => AsyncResult.ofResult wraps a synchronous Result in Async for uniform composition
 
let lookupPriceAsync (code: string) : Async<Result<decimal, string>> =
    async { return (if code.StartsWith "W" then Ok 9.99m else Error "Unknown product") }
    // => Simulated async price lookup
    // => Widget codes starting with "W" get £9.99; others get an error
 
let buildConfirmation (orderId: string) (price: decimal) : Async<Result<string, string>> =
    AsyncResult.retn (sprintf "Confirmed: %s @ £%.2f" orderId price)
    // => AsyncResult.retn lifts a plain string into Async<Result<string, string>>
    // => Simple confirmation lifted into Async<Result>
 
// Pipeline using AsyncResult.bind
let workflow orderId productCode =
    validateAsync orderId
    // => Step 1: validate order ID — produces Async<Result<string, string>>
    |> AsyncResult.bind (fun validId ->
        // => bind awaits and unwraps; validId = the validated order ID string
        // => This is AsyncResult.bind, not Result.bind — handles the Async wrapper
        lookupPriceAsync productCode
        // => Step 2: look up price — only runs if step 1 returned Ok
        |> AsyncResult.bind (fun price ->
            // => price = the decimal price value from the Ok case
            buildConfirmation validId price))
            // => Step 3: build the confirmation message
    // => Three async steps chained with AsyncResult.bind
 
let result1 = workflow "ORD-001" "W1234" |> Async.RunSynchronously
// => All three steps ran; "ORD-001" is valid; "W1234" → £9.99
// => result1 : Result<string, string> = Ok "Confirmed: ORD-001 @ £9.99"
 
printfn "%A" result1
// => Output: Ok "Confirmed: ORD-001 @ £9.99"

// Validation accumulation: collect ALL errors, not just the first.
// Uses an applicative functor pattern, not monadic bind.
 
// Validation type: same as Result but Error is always a list
type Validation<'a, 'e> =
    | Valid   of 'a
    | Invalid of 'e list
    // => Error is a LIST — multiple errors accumulate
 
module Validation =
    // Apply: combines two Validation values, accumulating errors from both
    let apply (vf: Validation<'a -> 'b, 'e>) (va: Validation<'a, 'e>) : Validation<'b, 'e> =
        // => vf: a Validation wrapping a function; va: a Validation wrapping a value
        match vf, va with
        | Valid f,   Valid a   -> Valid (f a)
        // => Both valid: apply the function to the value — produces a Valid result
        | Invalid e1, Invalid e2 -> Invalid (e1 @ e2)
        // => Both invalid: concatenate error lists — KEY difference from bind
        // => e1 @ e2 merges the two error lists — all failures visible at once
        | Invalid e,  Valid _  -> Invalid e
        // => Only function side invalid: propagate its error list unchanged
        | Valid _,    Invalid e -> Invalid e
        // => Only value side invalid: propagate its error list unchanged
 
    let retn (x: 'a) = Valid x
    // => Lift a pure value into Validation — analogous to Result's Ok
    // => Used to wrap the multi-arg constructor before applying values
 
    let map (f: 'a -> 'b) (v: Validation<'a, 'e>) : Validation<'b, 'e> =
        match v with
        | Valid a   -> Valid (f a)
        // => Valid: apply f to the value and re-wrap
        | Invalid e -> Invalid e
        // => Invalid: propagate errors unchanged — same semantics as Result.map
 
// Validation functions returning Validation instead of Result
let validateName (raw: string) : Validation<string, string> =
    // => Returns Valid with the trimmed name, or Invalid with the error in a list
    if System.String.IsNullOrWhiteSpace(raw) then Invalid ["Name must not be blank"]
    // => Guard 1: blank name rejected — error wrapped in a list for accumulation
    elif raw.Length > 50                     then Invalid ["Name must be 50 chars or fewer"]
    // => Guard 2: too long rejected — error wrapped in a list
    else Valid raw.Trim()
    // => Both guards passed — trim and return as Valid
 
let validateEmail (raw: string) : Validation<string, string> =
    // => Returns Valid with the lowercase email, or Invalid with the error in a list
    if System.Text.RegularExpressions.Regex.IsMatch(raw, @"^[^@\s]+@[^@\s]+\.[^@\s]+$")
    then Valid (raw.ToLowerInvariant())
    // => Valid email format — normalise to lowercase and return Valid
    else Invalid [sprintf "'%s' is not a valid email" raw]
    // => Invalid format — error wrapped in a list for accumulation
 
// Apply all validations — errors accumulate
let validateCustomer name email =
    let ctorResult = Validation.retn (fun n e -> (n, e))
    // => Lift the tuple constructor (fun n e -> (n, e)) into Validation
    // => ctorResult : Validation<string -> string -> string * string, string>
    let nameResult = validateName name
    // => nameResult : Validation<string, string> — Valid or Invalid
    let emailResult = validateEmail email
    // => emailResult : Validation<string, string> — Valid or Invalid
    Validation.apply (Validation.apply ctorResult nameResult) emailResult
    // => First apply: (fun n e -> (n, e)) applied to nameResult → Validation<string -> string * string>
    // => Second apply: that function applied to emailResult → Validation<string * string, string>
    // => If both valid: Valid ("Alice", "alice@example.com")
    // => If both invalid: Invalid (nameErrors @ emailErrors) — BOTH errors collected
 
printfn "%A" (validateCustomer "Alice" "alice@example.com")
// => Both validations passed: name is "Alice", email is valid
// => Output: Valid ("Alice", "alice@example.com")
 
printfn "%A" (validateCustomer "" "not-an-email")
// => Both validations failed: name is blank AND email format is wrong
// => Output: Invalid ["Name must not be blank"; "'not-an-email' is not a valid email"]
// => BOTH errors collected — user sees all problems at once

// "Make illegal states unrepresentable" — Wlaschin Ch 6.
// A Contact must have at least one way to be reached.
 
// WRONG: two optional fields allow the "no contact method" state
type BadContact = {
    Email: string option
    // => Email is optional — but if Phone is also None, no contact method exists
    Phone: string option
    // => Both could be None — an invalid state that compiles fine
    // => BadContact {} (empty record) would fail because at least one field is needed;
    // => but BadContact { Email = None; Phone = None } compiles — and represents "unreachable contact"
}
 
// RIGHT: discriminated union captures the three valid cases
type ContactMethod =
    // => Exactly one of three valid cases — "both absent" is impossible
    | EmailOnly  of email: string
    // => Case 1: only email provided
    | PhoneOnly  of phone: string
    // => Case 2: only phone provided
    | EmailAndPhone of email: string * phone: string
    // => Case 3: both provided
 
// Contact now ALWAYS has a way to be reached
type Contact = {
    Name: string
    ContactMethod: ContactMethod
    // => Required — a Contact without a contact method cannot be constructed
}
 
// All valid states — none of them represent "no contact method"
let contact1 = { Name = "Alice"; ContactMethod = EmailOnly "alice@example.com" }
// => contact1 : Contact, ContactMethod = EmailOnly — case 1: email only, valid
 
let contact2 = { Name = "Bob"; ContactMethod = PhoneOnly "+1-555-0100" }
// => contact2 : Contact, ContactMethod = PhoneOnly — case 2: phone only, valid
 
let contact3 = { Name = "Carol"; ContactMethod = EmailAndPhone ("carol@example.com", "+1-555-0200") }
// => contact3 : Contact, ContactMethod = EmailAndPhone — case 3: both present, valid
// => EmailAndPhone carries a (email, phone) tuple — both values available to callers
 
// The compiler enforces exhaustive handling of all three cases
let describeContact (c: Contact) =
    // => match must cover EmailOnly, PhoneOnly, and EmailAndPhone — no wildcard needed
    match c.ContactMethod with
    | EmailOnly e         -> sprintf "%s: email %s" c.Name e
    // => e : string — the email address extracted from EmailOnly case
    | PhoneOnly p         -> sprintf "%s: phone %s" c.Name p
    // => p : string — the phone number extracted from PhoneOnly case
    | EmailAndPhone (e,p) -> sprintf "%s: email %s, phone %s" c.Name e p
    // => e, p : string * string — both extracted from the EmailAndPhone tuple
 
printfn "%s" (describeContact contact1)
// => Matched EmailOnly; e = "alice@example.com"
// => Output: Alice: email alice@example.com
printfn "%s" (describeContact contact2)
// => Matched PhoneOnly; p = "+1-555-0100"
// => Output: Bob: phone +1-555-0100
printfn "%s" (describeContact contact3)
// => Matched EmailAndPhone; e = "carol@example.com", p = "+1-555-0200"
// => Output: Carol: email carol@example.com, phone +1-555-0200

// Before: primitive obsession — all arguments are raw strings.
// After: typed wrappers — distinct types, constraints enforced.
 
// ── BEFORE: primitive obsession ───────────────────────────────────────────
let processOrderBefore (orderId: string) (customerId: string) (productCode: string) (qty: int) =
    // => All arguments are raw primitives — easy to confuse order
    // => processOrderBefore "CUST-1" "ORD-1" "W1234" 3 — wrong arg order, compiles fine
    // => The compiler cannot detect the transposition — both are strings
    sprintf "Processing order %s for customer %s: %s × %d" orderId customerId productCode qty
 
// ── AFTER: typed wrappers ─────────────────────────────────────────────────
type OrderId'    = OrderId'    of string
// => Single-case DU wrapper for order IDs — nominally distinct from all other string types
type CustomerId' = CustomerId' of string
// => Nominally distinct from OrderId' — cannot be accidentally substituted
type ProductCode'= ProductCode'of string
// => Nominally distinct product code — prevents mixing with IDs
type Quantity'   = Quantity'   of int
// => Wraps int — enables constraint validation via the smart constructor below
 
module Quantity' =
    let create (n: int) : Result<Quantity', string> =
        // => Smart constructor: validates the positive-quantity invariant
        if n <= 0 then Error (sprintf "Quantity must be positive (got %d)" n)
        // => n=0 and negatives are rejected — at least 1 unit required
        else Ok (Quantity' n)
        // => n > 0: wrap in the Quantity' DU and return Ok
    let value (Quantity' n) = n
    // => Unwrap accessor: extracts the raw int for arithmetic or persistence
 
let processOrderAfter (OrderId' oid) (CustomerId' cid) (ProductCode' pcode) (Quantity' qty) =
    // => Pattern-matching in parameters unwraps all four wrappers inline
    // => processOrderAfter (CustomerId' "C1") (OrderId' "O1") ... ← compile error
    // => The compiler detects the argument order mistake — protects against transposition
    sprintf "Processing order %s for customer %s: %s × %d" oid cid pcode qty
    // => oid, cid, pcode, qty are the raw unwrapped values — safe to use here
 
// Correct usage
let order    = OrderId'     "ORD-001"
// => order : OrderId' — nominally distinct from CustomerId' and ProductCode'
let customer = CustomerId'  "CUST-42"
// => customer : CustomerId' — cannot be passed where OrderId' is expected
let product  = ProductCode' "W1234"
// => product : ProductCode' — its own type, not interchangeable with order or customer
let quantity = Quantity' 3
// => quantity : Quantity' — wraps int; Quantity'.create would validate > 0
 
// => All arguments are distinct types — cannot be accidentally transposed
printfn "%s" (processOrderAfter order customer product quantity)
// => Output: Processing order ORD-001 for customer CUST-42: W1234 × 3

// ValidatedOrder: the type produced by the ValidateOrder workflow step.
// All fields use constrained types — if a ValidatedOrder exists, it is valid.
 
// Constrained types (abbreviated from earlier examples)
type OrderId    = private OrderId    of string
// => Private constructor: only the OrderId module can create values
type String50   = private String50   of string
// => Private constructor: only values that passed the 50-char check exist
type EmailAddress = private EmailAddress of string
// => Private constructor: only values containing "@" in the right place exist
 
module OrderId    = let create s = if s = "" then Error "blank" else Ok (OrderId s)
                   // => Returns Ok if non-blank; Error "blank" if empty
                   // => Abbreviated: real version uses a longer error message
                   let value (OrderId s) = s
                   // => Unwrap accessor for the raw string
module String50   = let create _ s = if s = "" then Error "blank" else Ok (String50 s)
                   // => Field name parameter for diagnostic messages; validates non-blank
                   // => Abbreviated: real version also checks length ≤50
                   let value (String50 s) = s
                   // => Unwrap accessor — used when writing to the database or UI
module EmailAddress = let create s = if s.Contains "@" then Ok (EmailAddress s) else Error "invalid"
                     // => Minimal "@" check; full validation uses a regex pattern
                     let value (EmailAddress s) = s
                     // => Unwrap accessor
 
// Constrained address type (all validated fields)
type ValidatedAddress = {
    AddressLine1: String50
    // => Non-blank, ≤50 chars — validated via String50.create
    City: String50
    // => Non-blank city name — validated
    ZipCode: String50
    // => Postal code — validated for non-blank (format check would use a ZipCode type)
    Country: String50
    // => Two or three letter country code — validated for non-blank
}
 
// Constrained customer info type
type ValidatedCustomerInfo = {
    FirstName: String50
    // => Non-blank first name — validated on entry
    LastName: String50
    // => Non-blank last name — validated on entry
    EmailAddress: EmailAddress
    // => Valid email address — contains "@" separator; validated on entry
}
 
// ValidatedOrderLine: uses constrained types for all fields
type ValidatedOrderLine = {
    OrderLineId: String50
    // => Non-blank line identifier — validated
    ProductCode: String50
    // => Would use ProductCode DU from Example 15 in the full model
    Quantity: decimal
    // => Would use constrained UnitQuantity or KilogramQuantity in the full model
    // => Positive decimal — enforced by the validator when reading from UnvalidatedOrderLine
}
 
// The validated order — all fields are guaranteed valid by construction
type ValidatedOrder = {
    OrderId: OrderId
    // => Validated, non-blank
    CustomerInfo: ValidatedCustomerInfo
    // => All customer fields validated — FirstName, LastName, EmailAddress
    ShippingAddress: ValidatedAddress
    // => All address fields validated — Line1, City, ZipCode, Country
    BillingAddress: ValidatedAddress
    // => Separate billing address — may differ from shipping address
    OrderLines: ValidatedOrderLine list
    // => Non-empty list — at least one line required (enforced in the validator)
    // => Each line has a valid ProductCode and positive Quantity
}
 
printfn "ValidatedOrder type defined — all fields use constrained types"
// => ValidatedOrder only exists if all fields passed their respective smart constructors
// => Output: ValidatedOrder type defined — all fields use constrained types
printfn "If a ValidatedOrder exists, all its fields passed validation"
// => Compiler-enforced invariant: no way to construct ValidatedOrder with invalid fields
// => Downstream functions can skip defensive validation — the type provides the guarantee
// => Output: If a ValidatedOrder exists, all its fields passed validation
// => This is the "types as proof" principle: the type IS the proof of validity

// PricedOrder: the type produced by the PriceOrder workflow step.
// Extends the validated information with computed prices.
 
// Reuse types from Example 39 (abbreviated)
type OrderId       = OrderId       of string
// => Validated order identifier — non-blank
// => Note: in a compiled project these types would be imported from the domain module
// => These abbreviations omit the private constructor for brevity
type String50      = String50      of string
// => Validated string — non-blank, ≤50 chars
type EmailAddress  = EmailAddress  of string
// => Validated email — contains "@" separator
// => All three wrapper types prevent accidental mixing of IDs and strings
 
type PricedOrderLine = {
    // => Extends ValidatedOrderLine with a calculated price
    OrderLineId:  string
    // => Line identifier — carried through from ValidatedOrderLine
    ProductCode:  string
    // => Product code — unchanged from validation stage
    Quantity:     decimal
    // => Quantity — unchanged from validation stage
    LinePrice:    decimal
    // => LinePrice = unit price × quantity — only available after pricing
    // => This field makes PricedOrderLine distinct from ValidatedOrderLine
}
 
type BillingAmount = {
    // => The total billed amount — a domain concept with its own constraints
    Amount: decimal
    // => Total in the specified currency — sum of all PricedOrderLine.LinePrice values
    Currency: string
    // => Simplified — full version would use constrained types
}
 
type PricedOrder = {
    OrderId:         string
    // => Carried forward from ValidatedOrder
    CustomerName:    string
    // => Carried forward — needed for acknowledgment email
    ShippingAddress: string
    // => Simplified — full version would use ValidatedAddress type
    BillingAddress:  string
    // => May differ from shipping address for corporate orders
    OrderLines:      PricedOrderLine list
    // => Each line now carries its calculated price — distinct from ValidatedOrderLine
    AmountToBill:    BillingAmount
    // => The total — computed from the sum of all line prices
}
 
// Functions that need prices accept PricedOrder
let calculateTotal (order: PricedOrder) : decimal =
    // => Only a PricedOrder can be passed — ValidatedOrder won't compile here
    // => The type system enforces that pricing has already occurred
    order.OrderLines |> List.sumBy (fun line -> line.LinePrice)
    // => Sum all line prices — safe because each line is guaranteed to have a price
    // => List.sumBy: applies the selector to each element and returns the sum
 
// Building a sample PricedOrder
let samplePriced : PricedOrder = {
    // => samplePriced : PricedOrder — all fields set, all prices computed
    // => The type annotation ensures all required fields are present at construction time
    OrderId = "ORD-001"; CustomerName = "Alice"; ShippingAddress = "10 Main St"; BillingAddress = "10 Main St"
    OrderLines = [
        { OrderLineId = "L1"; ProductCode = "W1234"; Quantity = 2m; LinePrice = 19.98m }
        // => Line 1: 2 × £9.99 = £19.98
        { OrderLineId = "L2"; ProductCode = "G456";  Quantity = 1m; LinePrice = 24.99m }
        // => Line 2: 1 × £24.99 = £24.99
    ]
    AmountToBill = { Amount = 44.97m; Currency = "GBP" }
    // => AmountToBill = £19.98 + £24.99 = £44.97
}
 
printfn "Total: £%.2f" (calculateTotal samplePriced)
// => calculateTotal sums LinePrice for L1 (19.98) and L2 (24.99)
// => Output: Total: £44.97

// ValidateOrder: the full signature with injected dependencies and Async<Result> return.
 
// Dependency function types — infrastructure interfaces as function types
type CheckProductCodeExists = string -> bool
// => Synchronous product lookup (could use the catalogue in memory)
// => Returns bool: true if product exists in the catalogue, false otherwise
 
type CheckAddressExists = string -> Async<Result<string, string>>
// => Async address verification service call
// => Returns Async<Result<string, string>>: Ok verified address or Error message
 
// Abbreviated domain types
type UnvalidatedOrder = { OrderId: string; ProductCode: string; Qty: int; Address: string }
// => Raw input — all fields are primitives, none validated yet
type ValidatedOrder   = { OrderId: string; ProductCode: string; Qty: int; Address: string }
// => Same shape here; full model uses constrained types (OrderId, ProductCode DU, etc.)
 
// The workflow function signature with all dependencies
let validateOrder
    (checkProductExists: CheckProductCodeExists)
    // => Dependency 1: synchronous product lookup
    (checkAddressExists: CheckAddressExists)
    // => Dependency 2: async address verification
    (input: UnvalidatedOrder)
    // => The workflow input
    : Async<Result<ValidatedOrder, string list>> =
    // => Async because address check is async; Result because validation can fail
    // => Error is string list for accumulation (cf. Example 36)
    async {
        // Validate product code (synchronous)
        let productOk = checkProductExists input.ProductCode
        // => productOk : bool — true if product exists in the catalogue
        // => Returns bool — no async needed for in-memory catalogue
 
        // Validate address (async)
        let! addressResult = checkAddressExists input.Address
        // => addressResult : Result<string, string> — Ok validated address or Error message
        // => Await the async address service
 
        match productOk, addressResult with
        | true, Ok validAddress ->
            // => Both validations passed — product exists AND address is valid
            return Ok { OrderId = input.OrderId; ProductCode = input.ProductCode
                        Qty = input.Qty; Address = validAddress }
            // => Return ValidatedOrder with the verified address from the service
        | false, Ok _ ->
            // => Product not found but address was valid — only product error
            return Error [ sprintf "Product '%s' not found" input.ProductCode ]
            // => Single-element error list — applicative pattern (Example 36)
        | true, Error e ->
            // => Product exists but address was invalid — only address error
            return Error [ sprintf "Address invalid: %s" e ]
            // => Single-element error list with the address service's error message
        | false, Error e ->
            // => Both failed — accumulate both errors into a list
            return Error [ sprintf "Product '%s' not found" input.ProductCode
                           sprintf "Address invalid: %s" e ]
            // => Accumulate both errors — user sees both problems at once
    }
 
printfn "ValidateOrder signature: UnvalidatedOrder -> Async<Result<ValidatedOrder, string list>>"
// => Async: address check is I/O; Result: validation can fail; string list: all errors collected
// => Output: ValidateOrder signature: UnvalidatedOrder -> Async<Result<ValidatedOrder, string list>>

// PriceOrder: ValidatedOrder -> Async<Result<PricedOrder, PricingError>>
 
// Domain types (abbreviated)
type ValidatedOrderLine = { ProductCode: string; Qty: decimal }
// => Validated line: ProductCode and Qty have been checked; no pricing yet
type PricedOrderLine    = { ProductCode: string; Qty: decimal; Price: decimal }
// => Priced line: extends ValidatedOrderLine with the calculated Price
type ValidatedOrder     = { OrderId: string; Lines: ValidatedOrderLine list }
// => Validated order: all lines validated; ready for pricing step
type PricedOrder        = { OrderId: string; Lines: PricedOrderLine list; Total: decimal }
// => Priced order: all lines have prices; Total is the sum
 
// Error type for the pricing step
type PricingError =
    | ProductPriceNotFound of productCode: string
    // => Product is in the catalogue but has no price
    // => Caller should surface this as a 500-level error — catalogue data issue
    | PriceCalculationError of message: string
    // => Arithmetic issue (e.g. overflow)
    // => Rare but must be handled: very large quantities × very high prices
 
// Dependency: get the price for a product code
type GetProductPrice = string -> Result<decimal, PricingError>
// => Synchronous price lookup (catalogue lives in memory)
// => Returns Ok decimal on success, or Error PricingError on failure
 
// The workflow implementation
let priceOrder
    (getProductPrice: GetProductPrice)
    // => Injected price lookup dependency
    (validatedOrder: ValidatedOrder)
    // => Input: already-validated order — Lines are known to be valid
    : Result<PricedOrder, PricingError> =
    // => Result only — price lookup is synchronous in this design
    // => If any line fails, the whole order fails (short-circuit)
    let priceLine (line: ValidatedOrderLine) =
        // => Prices a single line: lookup price and compute line total
        getProductPrice line.ProductCode
        // => Returns Result<decimal, PricingError> — Ok unit price or Error
        |> Result.map (fun unitPrice -> { ProductCode = line.ProductCode; Qty = line.Qty; Price = unitPrice * line.Qty })
        // => Result.map: if Ok, compute Price = unitPrice × Qty; if Error, propagate
        // => For each line: look up price and compute line total
 
    // Inline implementation of sequenceResults — converts Result list to Result of list.
    // No external packages required; runs on bare dotnet fsi.
    let sequenceResults (results: Result<'a, 'e> list) : Result<'a list, 'e> =
        // => Fold right, accumulating Ok values or short-circuiting on the first Error
        List.foldBack
            (fun r acc ->
                match r, acc with
                | Ok v, Ok vs   -> Ok (v :: vs)
                // => Both Ok: prepend v to the accumulated list
                | Error e, _    -> Error e
                // => Current step failed: short-circuit with its error
                | _, Error e    -> Error e
                // => Accumulator already has an error: propagate it
            )
            results
            (Ok [])
        // => Start with Ok [] and fold each Result into it
 
    validatedOrder.Lines
    // => validatedOrder.Lines : ValidatedOrderLine list — one element per product ordered
    |> List.map priceLine
    // => Map each line through the pricing function — produces Result<PricedOrderLine, PricingError> list
    |> sequenceResults
    // => Convert Result list → Result of list; short-circuits on first Error
    // => If any line's price lookup fails, the whole pricing step fails
    // => sequenceResults: no external packages — pure standard library
    |> Result.map (fun pricedLines ->
        let total = pricedLines |> List.sumBy (fun l -> l.Price)
        // => Total = sum of all line prices — e.g. 19.98 + 24.99 = 44.97
        { OrderId = validatedOrder.OrderId; Lines = pricedLines; Total = total })
    // => Assemble the PricedOrder with all priced lines and their sum
    // => PricedOrder returned as Ok — callers use Result.bind to continue the pipeline
 
printfn "PriceOrder: GetProductPrice -> ValidatedOrder -> Result<PricedOrder, PricingError>"
// => Output: PriceOrder: GetProductPrice -> ValidatedOrder -> Result<PricedOrder, PricingError>

// AcknowledgeOrder: send a confirmation email — failure is logged but not propagated.
// Side effects (email sending) are at the edge; the core produces a pure output.
 
// Domain types
type PricedOrder = { OrderId: string; CustomerEmail: string; Total: decimal }
// => The input — a priced order ready for acknowledgment
 
type OrderAcknowledgment = { EmailAddress: string; Letter: string }
// => The acknowledgment value — email address and content
 
type SendResult = Sent | NotSent
// => Whether the acknowledgment was delivered
 
// Dependency: send the acknowledgment
type SendAcknowledgment = OrderAcknowledgment -> SendResult
// => Infrastructure function — email service, file system, etc.
 
// Pure function: create the acknowledgment content from the order
let createAcknowledgmentLetter (order: PricedOrder) : string =
    // => Pure — no I/O, just string formatting
    sprintf "Dear customer,\nYour order %s for £%.2f has been received.\nThank you!"
        order.OrderId order.Total
 
// Workflow step: create and attempt to send acknowledgment
let acknowledgeOrder
    (sendAcknowledgment: SendAcknowledgment)
    // => Injected dependency — the sending function
    (pricedOrder: PricedOrder)
    // => Input: the priced order
    : OrderAcknowledgment option =
    // => Return type: the acknowledgment if sent, None if not
    // => No Result — a send failure does NOT abort the workflow
    let letter = createAcknowledgmentLetter pricedOrder
    // => Create letter content — pure, no effects
    let acknowledgment = { EmailAddress = pricedOrder.CustomerEmail; Letter = letter }
    // => Assemble the acknowledgment value
    match sendAcknowledgment acknowledgment with
    | Sent    -> Some acknowledgment
    // => Sent successfully — return the acknowledgment for event logging
    | NotSent -> None
    // => Send failed — return None; caller logs but does not abort
 
let stubSend : SendAcknowledgment = fun _ -> Sent
// => Stub: always succeeds — used in tests and happy-path demos
// => In production: replace with a real email service function
 
let order = { OrderId = "ORD-001"; CustomerEmail = "alice@example.com"; Total = 44.97m }
// => order : PricedOrder — a sample order ready for acknowledgment
let result = acknowledgeOrder stubSend order
// => stubSend always returns Sent → acknowledgeOrder returns Some acknowledgment
// => result : OrderAcknowledgment option = Some { EmailAddress = "alice@example.com"; Letter = "..." }
 
printfn "Acknowledgment sent: %b" result.IsSome
// => result.IsSome = true (stubSend returned Sent)
// => Output: Acknowledgment sent: true

// The complete PlaceOrder workflow: validate → price → acknowledge → publish events.
// Three steps composed using the asyncResult CE — readable, typed, individually testable.
 
open System
 
// ── Abbreviated types — one distinct type per lifecycle stage ──────────────
type UnvalidatedOrder = { OrderId: string; ProductCode: string; Qty: int; Email: string }
// => Raw input from the HTTP request — nothing validated
// => All fields are raw primitives: strings and int, no constrained types
 
type ValidatedOrder   = { OrderId: string; ProductCode: string; Qty: int; Email: string }
// => Produced by validateOrder — all fields passed validation
// => Same shape as UnvalidatedOrder here; full model uses constrained types
 
type PricedOrder      = { OrderId: string; ProductCode: string; Qty: int; Email: string; Total: decimal }
// => Produced by priceOrder — extended with the computed total
// => Total is the only new field — the pricing step's output
 
type OrderPlaced      = { OrderId: string; Total: decimal }
// => Domain event emitted when the workflow succeeds
// => Carries just the identifier and total — what downstream contexts need
 
type PlacingOrderError =
    // => Named error union — every failure mode explicit
    | Validation of string
    // => Input data failed validation — user-correctable
    | Pricing    of string
    // => Pricing calculation failed — catalogue/configuration error
 
// ── Step 1: validateOrder — Async<Result<ValidatedOrder, PlacingOrderError>> ─────
let validateOrder (input: UnvalidatedOrder) : Async<Result<ValidatedOrder, PlacingOrderError>> =
    // => Async: real implementation would call an async address-verification service
    // => Result: validation can fail with a named error
    async {
        if input.OrderId = "" then return Error (Validation "OrderId blank")
        // => Short-circuit: empty OrderId diverts to Error track
        else return Ok { OrderId = input.OrderId; ProductCode = input.ProductCode; Qty = input.Qty; Email = input.Email }
        // => All checks passed: return ValidatedOrder on the Ok track
    }
 
// ── Step 2: priceOrder — Result<PricedOrder, PlacingOrderError> ─────────────
let priceOrder (validated: ValidatedOrder) : Result<PricedOrder, PlacingOrderError> =
    // => Synchronous: the product catalogue lives in memory — no async needed
    let unitPrice = if validated.ProductCode.StartsWith "W" then 9.99m else 24.99m
    // => Widget = £9.99, Gizmo = £24.99 — simplified catalogue lookup
    Ok { OrderId = validated.OrderId; ProductCode = validated.ProductCode
         Qty = validated.Qty; Email = validated.Email; Total = decimal validated.Qty * unitPrice }
    // => Returns PricedOrder — Total = unitPrice * Qty = 9.99 * 3 = 29.97
    // => This is the only place in the workflow where money arithmetic occurs
 
// ── Step 3: acknowledgeOrder — side effect only, no Result ─────────────────
let acknowledgeOrder (priced: PricedOrder) : unit =
    // => Unit return: acknowledgment failure is non-critical (see Example 43)
    // => Returning unit (not Result) signals: "failure here does not abort the workflow"
    printfn "Acknowledgment queued for %s" priced.Email
    // => In production: enqueue an email send job — effect at the edge
 
// ── asyncResult CE builder — composes Async<Result> steps ─────────────────
type AsyncResultBuilder() =
    member _.Return x = async { return Ok x }
    // => Lift a plain value into Async<Result>
    member _.ReturnFrom x = x
    // => Pass an Async<Result> through unchanged
    member _.Bind(x: Async<Result<_,_>>, f) =
        async {
            let! r = x
            // => Await the async operation
            match r with Ok v -> return! f v | Error e -> return Error e
            // => Ok: call next step; Error: short-circuit
        }
 
let asyncResult = AsyncResultBuilder()
// => asyncResult : AsyncResultBuilder — the CE instance
 
// ── The composed workflow ─────────────────────────────────────────────────
let placeOrder (input: UnvalidatedOrder) : Async<Result<OrderPlaced list, PlacingOrderError>> =
    // => Returns Async<Result<...>> — async because Step 1 is async; Result because Step 1 or 2 can fail
    asyncResult {
        let! validated = validateOrder input
        // => let! awaits the Async and unwraps Ok; short-circuits on Error (Validation "OrderId blank")
        // => validated : ValidatedOrder = { OrderId = "ORD-001"; ... } if input.OrderId is non-blank
        let! priced    = async { return priceOrder validated }
        // => priceOrder is sync — wrap in async for uniform CE composition
        // => priced : PricedOrder = { ...; Total = 29.97M }
        do acknowledgeOrder priced
        // => do: side effect — acknowledgment email queued; not in the Result chain
        return [ { OrderId = priced.OrderId; Total = priced.Total } ]
        // => return wraps the event list in Ok — workflow complete
        // => The list has one element: OrderPlaced { OrderId = "ORD-001"; Total = 29.97M }
    }
 
// ── Run and inspect ───────────────────────────────────────────────────────
let testInput = { OrderId = "ORD-001"; ProductCode = "W1234"; Qty = 3; Email = "alice@example.com" }
// => testInput : UnvalidatedOrder — a valid input that will flow through all three steps
let result    = placeOrder testInput |> Async.RunSynchronously
// => All three steps executed; acknowledgment side effect fired
// => result : Result<OrderPlaced list, PlacingOrderError> = Ok [{ OrderId = "ORD-001"; Total = 29.97M }]
 
match result with
| Ok events -> printfn "Success — %d events: %A" (List.length events) events
// => events : OrderPlaced list — 1 element with the OrderId and Total
| Error e   -> printfn "Error: %A" e
// => Not reached — testInput is valid
// => Output: Acknowledgment queued for alice@example.com
// => Output: Success — 1 events: [{ OrderId = "ORD-001"; Total = 29.97M }]

// Every workflow failure mode is a named DU case — no generic exceptions.
// Callers must handle each case explicitly.
 
type PlacingOrderError =
    // ── Validation errors (user correctable) ─────────────────────────────
    | OrderIdIsBlank
    // => Client sent an empty order ID — ask them to retry with a valid ID
    | OrderHasNoLines
    // => Client sent an order with zero lines — at least one required
    | ProductCodeNotFound of productCode: string
    // => A referenced product does not exist in the catalogue
    | InvalidQuantity     of productCode: string * qty: decimal
    // => Quantity is out of range for this product type
 
    // ── Pricing errors (system/catalogue errors) ──────────────────────────
    | ProductPriceNotFound of productCode: string
    // => Product exists but has no price — catalogue data issue
    | PriceOverflow
    // => Total price exceeded decimal limits — unusual but must be handled
 
    // ── Remote service errors ─────────────────────────────────────────────
    | AddressCheckFailed   of message: string
    // => External address verification service returned an error
    | AcknowledgmentFailed of orderId: string
    // => Email service could not deliver the acknowledgment (non-fatal by design)
 
// Handling all error cases at the API boundary
let toHttpResponse (error: PlacingOrderError) : int * string =
    // => Maps domain errors to (HTTP status code, message) pairs
    // => Returns (HTTP status code, message body) tuple — all cases must be handled
    match error with
    | OrderIdIsBlank            -> 400, "Order ID must not be blank"
    // => 400 Bad Request: client sent an empty ID — ask them to provide a valid one
    | OrderHasNoLines           -> 400, "Order must have at least one line"
    // => 400 Bad Request: client sent an empty order — at least one line required
    | ProductCodeNotFound code  -> 400, sprintf "Product '%s' not found" code
    // => 400 Bad Request: client referenced an invalid product code
    | InvalidQuantity (code, q) -> 400, sprintf "Invalid quantity %.2f for product '%s'" q code
    // => 400 Bad Request: quantity is out of range for this product type
    | ProductPriceNotFound code -> 500, sprintf "No price for product '%s' — please contact support" code
    // => 500 Internal Error: product exists but has no price — a catalogue data issue, not client's fault
    | PriceOverflow             -> 500, "Order total is too large — please contact support"
    // => 500 Internal Error: arithmetic overflow — rare but must be handled
    | AddressCheckFailed msg    -> 503, sprintf "Address service unavailable: %s" msg
    // => 503 Service Unavailable: external dependency is down — client should retry
    | AcknowledgmentFailed oid  -> 200, sprintf "Order %s placed (acknowledgment delayed)" oid
    // => 200 OK: order succeeded; acknowledgment email delayed — domain decision (cf. Example 43)
    // => AcknowledgmentFailed maps to 200 — domain decision (cf. Example 43)
 
let sampleError = ProductCodeNotFound "X999"
// => sampleError : PlacingOrderError = ProductCodeNotFound "X999"
let (status, message) = toHttpResponse sampleError
// => toHttpResponse ProductCodeNotFound maps to (400, "Product 'X999' not found")
printfn "HTTP %d: %s" status message
// => Output: HTTP 400: Product 'X999' not found

// Map domain errors to API errors at the HTTP boundary.
// Domain model stays clean; API concerns are isolated to the translation function.
 
// ── Domain error type ─────────────────────────────────────────────────────
type DomainError =
    | ValidationError    of field: string * message: string
    // => Input field failed validation — user-correctable error
    | ProductNotFound    of code: string
    // => The referenced product does not exist — also user-correctable
    | ServiceUnavailable of service: string
    // => Infrastructure dependency is down — infrastructure error, not user error
 
// ── API error type ─────────────────────────────────────────────────────────
type ApiErrorResponse = {
    StatusCode: int
    // => HTTP status code: 400 (bad request), 404 (not found), 503 (service unavailable)
    ErrorCode:  string
    // => Machine-readable error code for client error handling (e.g. "PRODUCT_NOT_FOUND")
    Message:    string
    // => Human-readable error description for logging and developer debugging
}
 
// ── Translation function ───────────────────────────────────────────────────
let toApiError (domainError: DomainError) : ApiErrorResponse =
    // => Pure translation function — no side effects, fully testable
    // => Takes a domain error and produces an API-friendly response shape
    match domainError with
    | ValidationError (field, msg) ->
        // => field = the invalid field name; msg = the validation message
        { StatusCode = 400
          // => 400 Bad Request: the client sent invalid data
          ErrorCode  = "VALIDATION_ERROR"
          // => Machine-readable code for client-side error handling
          Message    = sprintf "Field '%s': %s" field msg }
          // => Human-readable message combining field name and reason
        // => Bad Request — client can fix and retry
 
    | ProductNotFound code ->
        // => code = the product code that was not found in the catalogue
        { StatusCode = 400
          // => 400: the client referenced a non-existent product
          ErrorCode  = "PRODUCT_NOT_FOUND"
          // => Distinct error code from VALIDATION_ERROR — clients can handle differently
          Message    = sprintf "Product '%s' does not exist in catalogue" code }
          // => Includes the code so the client knows which product to fix
        // => Also a bad request — client sent an invalid product code
 
    | ServiceUnavailable service ->
        // => service = the name of the unavailable external service
        { StatusCode = 503
          // => 503 Service Unavailable: an upstream dependency is down
          ErrorCode  = "SERVICE_UNAVAILABLE"
          // => Client should implement retry with backoff on 503
          Message    = sprintf "The '%s' service is temporarily unavailable" service }
          // => Includes the service name for operational clarity
        // => Infrastructure error — client should retry after a delay
 
// ── Workflow result mapped at the boundary ─────────────────────────────────
let handleWorkflowResult (result: Result<string, DomainError>) : ApiErrorResponse option =
    // => Converts a workflow Result into an optional API error response
    match result with
    | Ok _    -> None
    // => Success — no error response needed; return None
    | Error e -> Some (toApiError e)
    // => Failure — translate domain error to API error and wrap in Some
 
let domainResult : Result<string, DomainError> = Error (ProductNotFound "X999")
// => domainResult simulates a workflow that failed because product "X999" was not found
let apiError = handleWorkflowResult domainResult
// => handleWorkflowResult matches Error → calls toApiError (ProductNotFound "X999")
// => apiError : ApiErrorResponse option = Some { StatusCode = 400; ErrorCode = "PRODUCT_NOT_FOUND"; ... }
 
match apiError with
| Some e -> printfn "API error %d [%s]: %s" e.StatusCode e.ErrorCode e.Message
// => e.StatusCode = 400; e.ErrorCode = "PRODUCT_NOT_FOUND"; e.Message = "Product 'X999' does not exist in catalogue"
| None   -> printfn "No error"
// => apiError = Some — so this branch prints the error
// => Output: API error 400 [PRODUCT_NOT_FOUND]: Product 'X999' does not exist in catalogue

// Functional core: pure domain logic — no I/O.
// Imperative shell: orchestrates I/O and calls the pure core.
 
// ── Pure domain functions (no I/O, no Async) ──────────────────────────────
let validateOrderPure (orderId: string) (qty: int) : Result<string * int, string> =
    // => Pure — takes data, returns data, no effects
    // => Result<string * int, string>: Ok (trimmedId, qty) or Error message
    if orderId = ""  then Error "OrderId blank"
    // => Guard 1: blank order ID rejected
    elif qty <= 0    then Error "Quantity must be positive"
    // => Guard 2: non-positive quantity rejected
    else Ok (orderId.Trim(), qty)
    // => Both guards passed — return the validated (id, qty) tuple
 
let calculateTotalPure (unitPrice: decimal) (qty: int) : decimal =
    unitPrice * decimal qty
    // => Pure — just arithmetic; result = unitPrice × qty (e.g. 9.99 × 3 = 29.97)
 
let createEventPure (orderId: string) (total: decimal) : string =
    // => Pure — just a record constructor
    sprintf "OrderPlaced:{orderId=%s,total=%.2f}" orderId total
    // => e.g. "OrderPlaced:{orderId=ORD-001,total=29.97}" — the event as a JSON-like string
 
// ── Imperative shell: orchestrates all I/O ────────────────────────────────
let runPlaceOrder (rawOrderId: string) (rawQty: int) =
    // => Shell: performs I/O, then delegates to pure core functions
 
    // Step 1: I/O — read product price from "database" (simulated)
    let unitPrice =
        printfn "[I/O] Reading product price from database..."
        // => Effect: database read
        9.99m
        // => Returns the price
 
    // Step 2: Pure domain logic — no I/O here
    let validationResult = validateOrderPure rawOrderId rawQty
    // => Pure function call — no effects
 
    match validationResult with
    | Error e ->
        printfn "[Shell] Validation failed: %s" e
        // => I/O: logging — at the shell, not in the domain
    | Ok (orderId, qty) ->
        let total = calculateTotalPure unitPrice qty
        // => total = 9.99 × 3 = 29.97 — pure arithmetic, no I/O
        // => Pure: arithmetic
        let event = createEventPure orderId total
        // => event = "OrderPlaced:{orderId=ORD-001,total=29.97}" — pure string construction
        // => Pure: event construction
 
        // Step 3: I/O — publish the event (simulated)
        printfn "[I/O] Publishing event: %s" event
        // => Effect: message bus publish — at the edge
        // => Only I/O happens here; the event itself was created by pure logic above
 
runPlaceOrder "ORD-001" 3
// => Output: [I/O] Reading product price from database...
// => Output: [I/O] Publishing event: OrderPlaced:{orderId=ORD-001,total=29.97}

// Edge wrapper: read → pure core → write. No I/O inside the core.
 
// ── Pure domain types and functions ──────────────────────────────────────
type OrderData    = { OrderId: string; ProductCode: string; Qty: int }
// => Input to the pure domain function — assembled from I/O results at the edge
type ProductPrice = { Code: string; UnitPrice: decimal }
// => The price record — loaded from catalogue/database at the edge
type OrderTotal   = { OrderId: string; Total: decimal }
// => Output of the pure domain function — the computed total
 
let computeTotal (order: OrderData) (price: ProductPrice) : Result<OrderTotal, string> =
    // => Pure: takes data, computes result — no effects
    // => Returns Result: price code mismatch is a domain error, not an exception
    if order.ProductCode <> price.Code then
        Error (sprintf "Price for '%s' does not match order product '%s'" price.Code order.ProductCode)
        // => Pure error — no throwing, no logging inside this function
    else
        Ok { OrderId = order.OrderId; Total = price.UnitPrice * decimal order.Qty }
        // => Pure computation: Total = UnitPrice × Qty
        // => e.g. 9.99 × 3 = 29.97
 
// ── Imperative edge wrapper ───────────────────────────────────────────────
let processOrder (rawOrderId: string) (rawCode: string) (rawQty: int) =
    // ─ READ PHASE: all I/O reads happen here ─────────────────────────────
    printfn "[Edge] Reading price from catalogue..."
    // => Simulate a database/cache read — real implementation would be async
    let productPrice = { Code = rawCode; UnitPrice = 9.99m }
    // => productPrice : ProductPrice — loaded from catalogue; UnitPrice = £9.99 (simplified)
    // => In production: fetch from real data store
 
    let order = { OrderId = rawOrderId; ProductCode = rawCode; Qty = rawQty }
    // => order : OrderData — assembled from raw parameters; no validation here
    // => Assemble the domain input — no validation here, just construction
 
    // ─ PURE CORE: call the domain function ───────────────────────────────
    let result = computeTotal order productPrice
    // => Pure function — fast, testable, no I/O
 
    // ─ WRITE PHASE: all I/O writes happen here ───────────────────────────
    match result with
    | Ok total ->
        printfn "[Edge] Persisting order total: £%.2f for %s" total.Total total.OrderId
        // => Simulate a database write
        printfn "[Edge] Publishing OrderPlaced event"
        // => Simulate a message bus publish
    | Error e ->
        printfn "[Edge] Logging error: %s" e
        // => Simulate error logging
 
processOrder "ORD-001" "W1234" 3
// => Output: [Edge] Reading price from catalogue...
// => Output: [Edge] Persisting order total: £29.97 for ORD-001
// => Output: [Edge] Publishing OrderPlaced event

// Composition root: inject all dependencies via partial application at startup.
// Downstream functions receive dependency-free signatures.
 
// ── Infrastructure function signatures ───────────────────────────────────
type LoadOrderFromDb = string -> string option
// => Load order by ID — returns None if not found
 
type SaveOrderToDb   = string -> string -> unit
// => Save order: first string = ID, second = serialised order
 
// ── Domain functions with dependency parameters ───────────────────────────
let createOrder
    (saveToDb: SaveOrderToDb)
    // => Injected persistence dependency
    (orderId: string)
    (customerName: string)
    : Result<string, string> =
    if orderId = "" || customerName = "" then Error "OrderId and CustomerName are required"
    else
        saveToDb orderId (sprintf "order:%s,customer:%s" orderId customerName)
        // => Calls the injected save function
        Ok (sprintf "Order %s created for %s" orderId customerName)
 
let loadOrder
    (loadFromDb: LoadOrderFromDb)
    // => Injected load dependency
    (orderId: string)
    : Result<string, string> =
    match loadFromDb orderId with
    | Some order -> Ok order
    | None       -> Error (sprintf "Order '%s' not found" orderId)
 
// ── Composition root: inject real dependencies ────────────────────────────
let realDb = System.Collections.Generic.Dictionary<string, string>()
// => In-memory substitute for a real database
// => In production this would be replaced by a SQL or document database connection
// => The same type (Dictionary) satisfies both SaveOrderToDb and LoadOrderFromDb
 
let realSave : SaveOrderToDb   = fun id data -> realDb.[id] <- data; printfn "[DB] Saved %s" id
// => realSave satisfies SaveOrderToDb — stores the serialised order and logs the save
// => type annotation ensures realSave : SaveOrderToDb (not just a plain lambda)
let realLoad : LoadOrderFromDb = fun id -> if realDb.ContainsKey id then Some realDb.[id] else None
// => realLoad satisfies LoadOrderFromDb — returns Some data if found, None if not
// => Real implementations — in production these would call actual database clients
 
// Partially apply to create dependency-free service functions
let createOrderService = createOrder realSave
// => Partially apply createOrder with realSave — bakes in the dependency
// => createOrderService : string -> string -> Result<string, string>
// => The saveToDb dependency is now "baked in" via partial application
// => Callers only see (orderId, customerName) — no visible database dependency
 
let loadOrderService = loadOrder realLoad
// => loadOrderService : string -> Result<string, string>
// => The loadFromDb dependency is baked in — callers only pass the orderId
 
// Use the services — no DI container needed
let created = createOrderService "ORD-001" "Alice Johnson"
// => Calls createOrder with realSave baked in
// => Saves "order:ORD-001,customer:Alice Johnson" to realDb and returns Ok
// => created : Result<string, string> = Ok "Order ORD-001 created for Alice Johnson"
 
let loaded  = loadOrderService "ORD-001"
// => Calls loadOrder with realLoad baked in
// => realDb.["ORD-001"] = "order:ORD-001,customer:Alice Johnson" → Some → Ok
// => loaded : Result<string, string> = Ok "order:ORD-001,customer:Alice Johnson"
 
printfn "Create: %A" created
// => Output: [DB] Saved ORD-001
// => Output: Create: Ok "Order ORD-001 created for Alice Johnson"
 
printfn "Load: %A" loaded
// => Output: Load: Ok "order:ORD-001,customer:Alice Johnson"

// A record of functions replaces an interface for persistence operations.
// Fields are function types — the record IS the interface.
 
// ── The persistence "interface" as a record of functions ─────────────────
type OrderRepository = {
    GetById:  string -> Async<string option>
    // => Load an order by ID; None if not found
    // => Async because real implementations call a database (I/O)
    Save:     string -> string -> Async<Result<unit, string>>
    // => Save an order: ID -> serialised data -> Async<Result>
    Delete:   string -> Async<Result<unit, string>>
    // => Delete an order by ID
    ListAll:  unit   -> Async<string list>
    // => List all order IDs (for admin purposes)
}
 
// ── In-memory implementation ──────────────────────────────────────────────
let inMemoryRepo () : OrderRepository =
    let db = System.Collections.Generic.Dictionary<string, string>()
    // => In-memory store — used in tests and for local development
    // => In production: replace with a real database client; interface is the same
    {
        GetById = fun id -> async { return if db.ContainsKey id then Some db.[id] else None }
        // => Returns Some if found, None otherwise
        // => async: matches the signature even though the lookup is synchronous
 
        Save = fun id data -> async {
            db.[id] <- data
            // => Upsert: insert or replace — same key replaces the previous value
            return Ok ()
            // => Returns Ok unit on success — no meaningful value to return
        }
 
        Delete = fun id -> async {
            if db.Remove id then return Ok ()
            // => Dictionary.Remove returns true if key existed and was removed
            // => Removed successfully
            else return Error (sprintf "Order '%s' not found" id)
            // => Not found — return domain error — caller decides whether to escalate
        }
 
        ListAll = fun () -> async { return db.Keys |> Seq.toList }
        // => db.Keys is a sequence; Seq.toList materialises it as a list
        // => Returns all keys as a list
    }
    // => returns OrderRepository record with all four operations implemented
 
// ── Usage ─────────────────────────────────────────────────────────────────
let testWorkflow () =
    async {
        let repo = inMemoryRepo ()
        // => repo : OrderRepository — the in-memory implementation
        // => Instantiate the in-memory repo
        let! _   = repo.Save "ORD-001" "Alice,W1234,3"
        // => Saves "Alice,W1234,3" under key "ORD-001"
        // => let! awaits the async save and discards the Ok unit result
        let! loaded = repo.GetById "ORD-001"
        // => loaded : string option = Some "Alice,W1234,3"
        // => Load it back
        printfn "Loaded: %A" loaded
        // => Output: Loaded: Some "Alice,W1234,3"
        let! all = repo.ListAll ()
        // => all : string list = ["ORD-001"] — one key in the store
        printfn "All orders: %A" all
        // => Output: All orders: ["ORD-001"]
    }
 
testWorkflow () |> Async.RunSynchronously
// => Async.RunSynchronously blocks the current thread until the async workflow completes
// => Runs the workflow synchronously for demonstration
// => All three operations run: Save, GetById, ListAll
// => The in-memory repo satisfies OrderRepository — same interface as a real database repo

// The repository as a single function type — the simplest possible interface.
// For most workflows, you only need to query or save; a full CRUD interface is overkill.
 
// ── Minimal types ─────────────────────────────────────────────────────────
type OrderId = OrderId of string
// => Wrapper to prevent ID confusion
// => OrderId is distinct from other string types at compile time
 
type OrderData = { OrderId: OrderId; CustomerName: string; Total: decimal }
// => The domain order value
// => Simplified: full model uses constrained types for all fields
 
// ── Repository as a function type ─────────────────────────────────────────
type GetOrder = OrderId -> Async<OrderData option>
// => "Given an OrderId, asynchronously return the order or None"
// => This is the entire read-side interface for many workflows
// => A function type, not an interface — no class needed to implement it
 
// ── In-memory implementation ──────────────────────────────────────────────
let buildInMemoryGetOrder () : GetOrder =
    let store = System.Collections.Generic.Dictionary<string, OrderData>()
    // => In-memory backing store — swap for real DB in production
    store.Add("ORD-001", { OrderId = OrderId "ORD-001"; CustomerName = "Alice"; Total = 29.97m })
    // => Seed with test data — ORD-001 is available for lookup
    fun (OrderId id) ->
        // => Returns a function (the GetOrder implementation)
        async { return if store.ContainsKey id then Some store.[id] else None }
        // => The repository function: looks up by ID, returns option
        // => Some if found, None if not found — no exceptions thrown
 
// ── Using the repository in a workflow ───────────────────────────────────
let getOrder : GetOrder = buildInMemoryGetOrder ()
// => getOrder : GetOrder = a function that looks up orders from the in-memory store
 
let workflow () =
    async {
        let! order = getOrder (OrderId "ORD-001")
        // => Await the async lookup; order : OrderData option
        // => Call the repository function — no interface, no class, just a function call
        match order with
        | Some o -> printfn "Found order for %s, total £%.2f" o.CustomerName o.Total
        // => o.CustomerName = "Alice"; o.Total = 29.97
        | None   -> printfn "Order not found"
        // => Not reached — "ORD-001" was seeded in buildInMemoryGetOrder
    }
 
workflow () |> Async.RunSynchronously
// => Async.RunSynchronously executes the workflow and blocks until complete
// => Output: Found order for Alice, total £29.97

// Save: the write-side repository function type.
// Async because of I/O; Result because saving can fail.
 
// Domain types
type OrderId = OrderId of string
// => Wrapper: prevents mixing order IDs with other strings
type OrderData = { OrderId: OrderId; CustomerName: string; Total: decimal }
// => The full domain order record to be persisted
 
// Persistence error type
type PersistError =
    | DuplicateOrderId of OrderId
    // => An order with this ID already exists — caller should reject or ignore
    | ConnectionFailed of message: string
    // => Database is unreachable — caller should retry with backoff
    | ConstraintViolation of detail: string
    // => A database constraint was violated (e.g. FK violation) — system error
 
// The save function type
type SaveOrder = OrderData -> Async<Result<unit, PersistError>>
// => "Given an OrderData, asynchronously try to save it"
// => unit because there is no meaningful return value on success
// => Result because saving can fail with a named error
// => Async because database writes are I/O operations
 
// In-memory implementation
let buildInMemorySave () : SaveOrder =
    let store = System.Collections.Generic.Dictionary<string, OrderData>()
    // => In-memory backing store — key is the raw order ID string
 
    fun order ->
        async {
            let (OrderId id) = order.OrderId
            // => Unwrap the OrderId wrapper to get the raw string for dictionary lookup
            if store.ContainsKey id then
                return Error (DuplicateOrderId order.OrderId)
                // => ID already in store — return DuplicateOrderId error
                // => Simulate duplicate key error
            else
                store.[id] <- order
                // => Insert the order into the in-memory store
                return Ok ()
                // => Success — returns Ok unit; no data to return on a write
        }
 
let saveOrder : SaveOrder = buildInMemorySave ()
// => saveOrder : SaveOrder = an Async function that saves to the in-memory store
// => In production: replace with a SQL or document database implementation; same interface
 
let testSave () =
    async {
        let order = { OrderId = OrderId "ORD-001"; CustomerName = "Alice"; Total = 29.97m }
        // => order : OrderData — a sample order with ID "ORD-001"
        let! result1 = saveOrder order
        // => First save — "ORD-001" not in store yet → Ok ()
        // => First save — should succeed
        printfn "First save: %A" result1
        // => result1 = Ok () — the order was inserted
        // => Output: First save: Ok null
 
        let! result2 = saveOrder order
        // => Second save — "ORD-001" already in store → DuplicateOrderId error
        // => Second save — should fail with DuplicateOrderId
        printfn "Second save: %A" result2
        // => result2 = Error (DuplicateOrderId (OrderId "ORD-001"))
        // => Output: Second save: Error (DuplicateOrderId (OrderId "ORD-001"))
    }
 
testSave () |> Async.RunSynchronously
// => Runs both saves; first succeeds, second fails with DuplicateOrderId
// => Async.RunSynchronously blocks until the entire testSave workflow completes

// Event store append: a function, not a class — consistent with the rest of the functional model.
 
// Domain event type
type OrderEvent =
    | OrderPlaced   of orderId: string * total: decimal
    // => Raised when a customer successfully places an order
    | OrderCancelled of orderId: string * reason: string
    // => Raised when an order is cancelled — carries the cancellation reason
    | OrderShipped  of orderId: string * trackingNumber: string
    // => Raised when the order is dispatched to the carrier
 
// Error type for event store operations
type AppendError =
    | StreamConcurrencyConflict of streamId: string
    // => Optimistic concurrency: another writer appended first
    // => Caller should reload the stream and retry
    | EventStoreUnavailable     of message: string
    // => Event store is down — caller should retry with backoff
 
// The append function type
type AppendOrderEvents = string -> OrderEvent list -> Async<Result<unit, AppendError>>
// => string = stream ID (typically the OrderId)
// => OrderEvent list = the events to append — one or more at a time
// => Async<Result<unit, AppendError>> = async and fallible
// => unit return: no data returned on success; errors are named explicitly
 
// In-memory event store implementation
let buildInMemoryEventStore () : AppendOrderEvents =
    let streams = System.Collections.Generic.Dictionary<string, OrderEvent list>()
    // => In-memory event streams keyed by stream ID
    // => In production: replace with EventStoreDB or Azure Event Hubs client
 
    fun streamId events ->
        // => Returns a function that appends events to the in-memory stream
        async {
            let existing = if streams.ContainsKey streamId then streams.[streamId] else []
            // => Get existing events for this stream — empty list if first event
            streams.[streamId] <- existing @ events
            // => Append: existing events + new events = complete stream
            // => @ is the F# list concatenation operator
            printfn "[EventStore] Appended %d event(s) to stream '%s'" (List.length events) streamId
            // => Log for observability
            return Ok ()
            // => Success — no data to return on successful append
        }
 
let appendEvents : AppendOrderEvents = buildInMemoryEventStore ()
// => appendEvents : AppendOrderEvents = a function backed by the in-memory store
 
let testAppend () =
    async {
        let events = [ OrderPlaced ("ORD-001", 29.97m); ]
        // => One OrderPlaced event to append — the usual case
        let! result = appendEvents "ORD-001" events
        // => Append to the "ORD-001" stream; result : Result<unit, AppendError>
        // => Append to the "ORD-001" stream
        printfn "Append result: %A" result
        // => result = Ok () on success
    }
 
testAppend () |> Async.RunSynchronously
// => Output: [EventStore] Appended 1 event(s) to stream 'ORD-001'
// => Output: Append result: Ok null