feat: Simplify fare transfer logic for 2026 fall fares changes

[joshlarson]

Scope

Asana Ticket: 💸 🗺️ Update Trip Planner fares to reflect fare pilot starting 9/1

Implementation

• I added a struct called %Fares.State{} that keeps track of the rider's journey so far. Each time a new leg is added to the %Fares.State{}, it uses the updated transfer logic to determine whether the new fare should be included in the 2-hour transfer window, when fares should be free (for free buses and free boarding at Logan, for instance), and when in-station transfers occur between routes that are all on the "paid" side of the fare gates.
• Fare calculation is as simple as passing each leg into Fares.State.add_leg/2, and then calling Fares.State.fare/1 to extract the final fare at the end.

Note

🤖 The meat of this PR was human-generated - I wrote the new tests and the %Fares.State{} struct by hand. Much of the follow-on cleanup work was done by Copilot, including adding typespecs and docs.

The commits that include (robot) in the prefix were AI-generated; the others were hand-crafted.

Screenshots

Alewife to Orient Heights

Old: Out-of-station subway transfer: 2x $2.40 = $4.80
New: Infinite subway-to-subway transfer: 1x $2.40

---

Alewife to Charlestown (Navy Yard)

Old: Subway-to-ferry transfer: $2.40 + $2.40 = $4.80
New: Infinite subway-to-ferry transfer: Just $2.40

---

Burlington Mall to Montello

Bus bus ferry bus bus
Old: Three bus fares (I don't actually know why) plus a ferry
New: Most of the bus legs, plus the ferry, are in a 2-hour transfer window, plus one bus trip outside of that: $9.75 + $1.70 = $11.45

Six-legged bus trip
Old: No 2-hour bus transfer window (this is a bug, FYI): $1.70
New: Last two legs are outside the 2-hour window: $1.70 + $1.70 = $3.40

---

Washington St @ Blue Hill Ave to Ashmont

23
Old: Regular bus (this is a bug, FYI): $1.70
New: Free!

19 -> RL
Noting this because that transfer happens at Fields Corner, and if we counted this transfer as a free in-station transfer, then we would incorrectly list a fare of $1.70. Old and new both correctly report $2.40.

---

Boston Logan Airport to Alewife

Flagging this as a fun use case where we need to care about in-station transfers explicitly, and can't just assume that we can ignore in-station transfers because of the infinite-subway-to-subway rule.

---

Boston Logan Airport to Highland Ave @ Tower St

Old: Erroneously counts the trip as free, because it starts out free, and then all of the transfers afterwards are normally free.
New: Correctly shows the transfer to the 90 bus as a regular fare, because boarding the SL1 at Logan and the in-station transfer at South Station are both free, and don't start any kind of transfer window.

How to test

Visit any of the above links, as well as any other complicated trips you can think of! Have fun!

[thecristen]

I think the logic is sound and the documentation is great! A few small comments.