Interfaces first, properties second: checking Chaufr's billing rules
Anil Madhavapeddy recently argued that OCaml's module language is the perfect fit for agentic programming: write the interfaces first, let the compiler check the design, then fill in the implementations, whoever or whatever writes them. We agree, and we have been building Chaufr, our chauffeur marketplace, that way. This post asks the next question: once the interfaces are right, what is left that the compiler cannot check, and how do you check it?
Everything below is Chaufr's production code, lightly excerpted: serialisation, display and a few helpers are left out, and some lines are reflowed to fit the page. The logic is unchanged. Every block is run on each build of this site with mdx, so the outputs are real.
The contract
Chaufr bills chauffeur time by the hour within a band Chaufr sets, rounded up to 15-minute blocks, and never for less than the time booked. This is the interface that states those rules, taken from fare.mli:
module type FARE = sig
module Money : sig
type t = private int
val of_naira : int -> t option
val of_kobo : int -> t option
val kobo : t -> int
end
(** Chauffeur time is billed in blocks of this many minutes, rounded up. *)
val block_minutes : int
val billed_minutes : int -> int
(** Chaufr's limits; each chauffeur picks an hourly rate inside them. *)
type band = private {
min_per_hour : Money.t;
max_per_hour : Money.t;
minimum_minutes : int;
maximum_minutes : int;
minimum_offer : Money.t;
}
val band :
min_per_hour:Money.t ->
max_per_hour:Money.t ->
minimum_minutes:int ->
maximum_minutes:int ->
minimum_offer:Money.t ->
(band, string) result
type t = private
| Hourly of { minutes : int; per_hour : Money.t }
| Offered of Money.t
type error =
| Rate_outside_band of Money.t * Money.t
| Too_short of int
| Too_long of int
| Offer_too_low of Money.t
val hourly : band -> per_hour:Money.t -> minutes:int -> (t, error) result
val offer : band -> Money.t -> (t, error) result
val cost : per_hour:Money.t -> minutes:int -> Money.t
(** The longer of the booked and the actual time, at the booked rate. *)
val final : t -> actual_minutes:int -> t
val total : t -> Money.t
end
And the implementation behind it, from fare.ml:
module Fare : FARE = struct
module Money = struct
type t = int
let of_naira n = if n >= 0 then Some (n * 100) else None
let of_kobo k = if k >= 0 then Some k else None
let kobo k = k
end
let block_minutes = 15
let billed_minutes minutes =
(minutes + block_minutes - 1) / block_minutes * block_minutes
type band = {
min_per_hour : Money.t;
max_per_hour : Money.t;
minimum_minutes : int;
maximum_minutes : int;
minimum_offer : Money.t;
}
let band ~min_per_hour ~max_per_hour ~minimum_minutes ~maximum_minutes
~minimum_offer =
if min_per_hour <= 0 then Error "the lowest hourly rate must be above zero"
else if max_per_hour < min_per_hour then
Error "the highest hourly rate must not be below the lowest"
else if minimum_minutes < block_minutes then
Error "the shortest booking is at least 15 minutes"
else if maximum_minutes < minimum_minutes then
Error "the longest booking must not be shorter than the shortest"
else if maximum_minutes > 24 * 60 then
Error "a booking lasts at most 24 hours"
else if minimum_offer <= 0 then Error "the minimum offer must be above zero"
else
Ok { min_per_hour; max_per_hour; minimum_minutes; maximum_minutes; minimum_offer }
type t =
| Hourly of { minutes : int; per_hour : Money.t }
| Offered of Money.t
type error =
| Rate_outside_band of Money.t * Money.t
| Too_short of int
| Too_long of int
| Offer_too_low of Money.t
let check_rate band per_hour =
if per_hour < band.min_per_hour || per_hour > band.max_per_hour then
Error (Rate_outside_band (band.min_per_hour, band.max_per_hour))
else Ok per_hour
let hourly band ~per_hour ~minutes =
match check_rate band per_hour with
| Error _ as refused -> refused
| Ok per_hour ->
if minutes < band.minimum_minutes then Error (Too_short band.minimum_minutes)
else if minutes > band.maximum_minutes then Error (Too_long band.maximum_minutes)
else Ok (Hourly { minutes; per_hour })
let offer band amount =
if amount < band.minimum_offer then Error (Offer_too_low band.minimum_offer)
else Ok (Offered amount)
let cost ~per_hour ~minutes = ((per_hour * billed_minutes minutes) + 59) / 60
let final fare ~actual_minutes =
match fare with
| Hourly { minutes; per_hour } -> Hourly { minutes = max minutes actual_minutes; per_hour }
| Offered _ -> fare
let total = function
| Hourly { minutes; per_hour } -> cost ~per_hour ~minutes
| Offered amount -> amount
end
What the types already guarantee
The private keywords carry most of the weight. Code outside Fare can read a fare, but it cannot build one, so every fare in the system has passed through hourly or offer and therefore through the band:
# let rate = Option.get (Fare.Money.of_naira 8_000);;
val rate : Fare.Money.t = 800000
# let sneaky = Fare.Hourly { minutes = 5; per_hour = rate };;
Line 1, characters 26-58:
Error: Cannot create values of the private type Fare.t.Hourly
The same holds for money: the only way to get a Money.t is a constructor that refuses negatives, and the only way to get a band is band, which refuses an impossible one:
# Fare.Money.of_kobo (-1);;
- : Fare.Money.t option = None
# let n k = Option.get (Fare.Money.of_naira k);;
val n : int -> Fare.Money.t = <fun>
# Fare.band ~min_per_hour:(n 15_000) ~max_per_hour:(n 5_000)
~minimum_minutes:30 ~maximum_minutes:720 ~minimum_offer:(n 2_000);;
- : (Fare.band, string) result =
Error "the highest hourly rate must not be below the lowest"
No test was written for any of this. It cannot happen, so there is nothing to test.
Where properties come in
Types cannot say "the bill is never less than the time worked". That is arithmetic, and the arithmetic is where billing goes wrong: an off-by-one in rounding, an integer division in the wrong place. So we state the rules as properties and let QCheck generate thousands of cases against the real functions:
let holds test = QCheck.Test.check_exn test; "held"
let kobo = Fare.Money.kobo
let money k = Option.get (Fare.Money.of_kobo k)
let band =
Result.get_ok
(Fare.band ~min_per_hour:(money 500_000) ~max_per_hour:(money 1_500_000)
~minimum_minutes:30 ~maximum_minutes:720 ~minimum_offer:(money 200_000))
let whole_blocks_never_less =
QCheck.Test.make ~count:5000 ~name:"billed time is whole blocks, never less, under one block more"
QCheck.(int_range 0 1440)
(fun m ->
let b = Fare.billed_minutes m in
b mod Fare.block_minutes = 0 && b >= m && b < m + Fare.block_minutes)
let never_undercharges =
QCheck.Test.make ~count:5000 ~name:"cost is never below the exact time at the rate"
QCheck.(pair (int_range 500_000 1_500_000) (int_range 0 1440))
(fun (rate, m) -> kobo (Fare.cost ~per_hour:(money rate) ~minutes:m) * 60 >= rate * m)
let final_never_below_booked =
QCheck.Test.make ~count:5000 ~name:"the final fare is never below the booked fare"
QCheck.(triple (int_range 500_000 1_500_000) (int_range 30 720) (int_range 0 1440))
(fun (rate, booked, actual) ->
match Fare.hourly band ~per_hour:(money rate) ~minutes:booked with
| Error _ -> QCheck.assume_fail ()
| Ok f -> kobo (Fare.total (Fare.final f ~actual_minutes:actual)) >= kobo (Fare.total f))
# holds whole_blocks_never_less;;
- : string = "held"
# holds never_undercharges;;
- : string = "held"
# holds final_never_below_booked;;
- : string = "held"
Settlement and earnings
After a trip, the rider and the chauffeur each confirm how the fare was paid, and either can raise a dispute. This is Chaufr's settlement.ml, with timestamps as Ptime.t:
module Settlement = struct
type party = Rider | Chauffeur
type payment_method = Cash | Transfer
type confirmation = { party : party; payment_method : payment_method; noted_at : Ptime.t }
type dispute = { raised_by : party; reason : string; raised_at : Ptime.t }
type status =
| Awaiting_both
| Awaiting_rider
| Awaiting_chauffeur
| Settled
| Disputed of dispute
let status ~confirmations ~disputes =
match disputes with
| first :: _ -> Disputed first
| [] -> (
let confirmed p = List.exists (fun (c : confirmation) -> c.party = p) confirmations in
match (confirmed Rider, confirmed Chauffeur) with
| false, false -> Awaiting_both
| false, true -> Awaiting_rider
| true, false -> Awaiting_chauffeur
| true, true -> Settled)
let waiting_for = function
| Awaiting_both -> [ Rider; Chauffeur ]
| Awaiting_rider -> [ Rider ]
| Awaiting_chauffeur -> [ Chauffeur ]
| Settled | Disputed _ -> []
let may_confirm status party = List.mem party (waiting_for status)
let may_dispute = function
| Awaiting_both | Awaiting_rider | Awaiting_chauffeur | Settled -> true
| Disputed _ -> false
end
And earnings.ml, which shows chauffeurs what they have earned over rolling windows:
module Earnings = struct
type trip = { fare : Fare.Money.t; completed_at : Ptime.t; confirmed : bool }
type t = {
last_7_days : Fare.Money.t;
last_30_days : Fare.Money.t;
all_time : Fare.Money.t;
trips : int;
unconfirmed_trips : int;
unconfirmed : Fare.Money.t;
}
let sum trips =
Option.get
(Fare.Money.of_kobo (List.fold_left (fun kobo t -> kobo + Fare.Money.kobo t.fare) 0 trips))
let within ~now ~days t =
Ptime.Span.compare (Ptime.diff now t.completed_at) (Ptime.Span.of_int_s (days * 86_400)) <= 0
let summarise ~now trips =
let unconfirmed = List.filter (fun t -> not t.confirmed) trips in
{
last_7_days = sum (List.filter (within ~now ~days:7) trips);
last_30_days = sum (List.filter (within ~now ~days:30) trips);
all_time = sum trips;
trips = List.length trips;
unconfirmed_trips = List.length unconfirmed;
unconfirmed = sum unconfirmed;
}
end
The rules we care about here are about consistency: a trip is settled exactly when both sides confirmed and nobody disputed, nobody confirms twice, and the earnings a chauffeur sees always add up.
let now = Option.get (Ptime.of_float_s 1_800_000_000.)
let confirmation =
QCheck.Gen.(oneof_list Settlement.[ Rider; Chauffeur ]
>|= fun party -> { Settlement.party; payment_method = Cash; noted_at = now })
let settled_exactly_when_both_confirm =
QCheck.Test.make ~count:3000 ~name:"settled exactly when both confirmed and nobody disputed"
QCheck.(make Gen.(pair (list_size (int_range 0 4) confirmation) bool))
(fun (cs, disputed) ->
let disputes =
if disputed then [ { Settlement.raised_by = Rider; reason = "x"; raised_at = now } ] else []
in
let has p = List.exists (fun (c : Settlement.confirmation) -> c.party = p) cs in
(Settlement.status ~confirmations:cs ~disputes = Settlement.Settled)
= ((not disputed) && has Rider && has Chauffeur))
let nobody_confirms_twice =
QCheck.Test.make ~count:3000 ~name:"a party that confirmed may not confirm again"
QCheck.(make Gen.(list_size (int_range 0 4) confirmation))
(fun cs ->
let st = Settlement.status ~confirmations:cs ~disputes:[] in
List.for_all (fun (c : Settlement.confirmation) -> not (Settlement.may_confirm st c.party)) cs)
let trip =
QCheck.Gen.(
triple (int_range 0 5_000_000) (int_range (-3600) (90 * 86_400)) bool
>|= fun (fare, age, confirmed) ->
{ Earnings.fare = money fare;
completed_at = Option.get (Ptime.of_float_s (1_800_000_000. -. float_of_int age));
confirmed })
let earnings_add_up =
QCheck.Test.make ~count:3000 ~name:"windows nest and all time is exactly the sum of fares"
QCheck.(make Gen.(list_size (int_range 0 40) trip))
(fun ts ->
let e = Earnings.summarise ~now ts in
kobo e.last_7_days <= kobo e.last_30_days
&& kobo e.last_30_days <= kobo e.all_time
&& kobo e.unconfirmed <= kobo e.all_time
&& kobo e.all_time = List.fold_left (fun a (t : Earnings.trip) -> a + kobo t.fare) 0 ts)
# holds settled_exactly_when_both_confirm;;
- : string = "held"
# holds nobody_confirms_twice;;
- : string = "held"
# holds earnings_add_up;;
- : string = "held"
What we found
Every rule held, across 24,000 generated cases on each build of this page. The billing never undercharges, a final fare never drops below the booked one, and the numbers a chauffeur sees always add up. That is the expected result, and still worth having: these properties now run on every change, so a future refactor, by us or by an agent, cannot quietly break them.
The more useful output was three questions the properties forced us to answer, because they are true of the code but written down nowhere:
Can a settled trip still be disputed? Yes:
# Settlement.may_dispute Settlement.Settled;;
- : bool = true
That is deliberate. Riders pay chauffeurs directly, often by bank transfer, and the commonest problem, paying too much by mistake, only shows up after both sides have confirmed. Chaufr does not try to match payments automatically either: the payer is not always the booker, because a friend may send the money when the booker's phone has no network, so any rule based on the sender's name would misfire. Instead, the dispute email carries what a person needs to settle it by hand: the trip, the fare, when it ended, the reporter's own words and both people's contacts.
The decision was right, but it lived only in a pattern match. It now has its line in settlement.mli, so nobody "fixes" it later.
What happens to a trip stamped in the future? If Chaufr's clock is ever corrected backwards, a trip can end up stamped after now. It counts as earned this week:
# let ahead = { Earnings.fare = money 1_000_000;
completed_at = Option.get (Ptime.add_span now (Ptime.Span.of_int_s 3600));
confirmed = true };;
val ahead : Earnings.trip =
{Earnings.fare = 1000000; completed_at = <abstr>; confirmed = true}
# kobo (Earnings.summarise ~now [ ahead ]).last_7_days;;
- : int = 1000000
Every timestamp is written by Chaufr itself, never by a phone, so this needs Chaufr's own clock to jump backwards. We decided it is not worth code. The difference is that it is now a decision, not an accident nobody had noticed.
Who guarantees one dispute per trip? Settlement.status reports only the first dispute. That is correct only because Chaufr's database refuses a second dispute for the same trip, with a unique constraint added in migration 23. This is deliberate defence in depth: the schema guarantees there is at most one dispute, and the type reads it. The invariant lives in two layers, and each depends on the other. Finding every layer where a wrong state can enter, and closing it there, is most of the work.
Your code, the same way
This is what we do at Invariant Software, on our own production code first: put the rules in the interfaces, state the rest as properties, and let the compiler and thousands of generated cases check every change, whether an engineer or an agent made it.
If your team handles payments, bookings or anything else where a wrong state costs money, we can do the same for one of your critical services in an invariant audit: two weeks, a written report of what holds, what does not, and what nobody had written down. Let's talk.
— Chukwuma