LEARNING RECORD · BullionVault Java course
14 August 2026
Date: 2026-08-14 Status: accepted
Lesson 0002 covers the order board itself — the part of BullionVault that is the product. Four rules had to be taught: price priority, time priority, price improvement, and partial fills.
The design question was how to seed the bugs so that eight red bars teach three lessons rather than eight disconnected ones.
Assert on one dimension per test. Every test in OrderBookTest checks the counterparty, or the price, or the remaining quantity — never a combination. That is why the eight failures group cleanly:
| Failing tests | Assert on | Bug |
|---|---|---|
| 4 | fill price | fills at the incoming limit, not the resting order's price |
| 2 | counterparty id | resting.addFirst + stable sort ⇒ newest-first among equal prices |
| 2 | quantity | continue skips any resting order bigger than the incoming order |
Had each test asserted on everything, all eight would have failed on whichever assertion happened to run first, and the suite would have said only "matching is broken".
Leave price priority correct. Two of the twelve new tests pass on arrival. That is deliberate — a suite where everything is red teaches nothing about isolating a fault, and it gives Tom something to explain rather than fix.
Time priority can be made green two ways, and I verified both:
resting.addFirst(...) to resting.add(...). Both time-priority tests pass. Confirmed by running it..thenComparingLong(Order::sequence) to the comparator.Fix A works by accident. The business rule first come, first served ends up living inside an accident of list insertion — unnamed, unasserted, and silently broken the moment someone swaps the collection, parallelises the stream, or reloads the book from Oracle in a different row order.
To make the point unmissable, the verified solution deliberately keeps addFirst and still passes all 25 tests. That is the proof that the comparator is carrying the rule.
Filling at incoming.limit() instead of r.limit() means every client always pays their worst acceptable price. In the test fixture a buyer willing to go to 99,000 meets a resting offer at 96,000 and is charged USD 24,750.00 instead of USD 24,000.00 on 250 g — about 3%, silently, on every trade.
Note which test catches the consequence: fillKnowsItsConsideration, which runs lesson 0001's Pricing.consideration over the fill. The money code was correct and was handed the wrong input. Worth saying out loud — correct components do not compose into a correct system on their own.
Good. The lesson reuses lesson 0001 (Pricing.consideration on Fill), so it doubles as spaced retrieval rather than isolated new material.
Good. sequence on Order sets up lesson 0003 directly: something upstream has to hand out those numbers, and that something is shared mutable state.
Cost. Price gained Comparable plus isAtMost/isAtLeast. That edits a file lesson 0001 described as "given and correct". It is additive and does not change any lesson 0001 behaviour, but the lesson-0001 text should not be read as promising those files never change.
Open. Order.withQuantity currently lets quantity go up as well as down. On CME Globex an increase forfeits time priority; here it would silently keep it. Good candidate for a follow-on test.
Run before shipping, per [[blackjack-course-tdd-feedback]]:
Tests run: 25, Failures: 8, Errors: 0 — the 13 from lesson 0001 all still green, 4 of the 12 new ones passing.Tests run: 25, Failures: 0, Errors: 0 with the three fixes applied and addFirst deliberately left in place.OrderBook with only addFirst → add changed, running -Dtest='OrderBookTest$TimePriority' → Tests run: 2, Failures: 0. The claim that the fragile fix passes is measured, not reasoned.macOS revoked Desktop folder access partway through (TCC), so lesson 0002 was built and verified entirely in the session scratchpad against a copy of the solved project, then applied to the workspace afterwards. Everything above was still run — nothing was written from reasoning alone.