0001 — The spec had no exercise in it

Date: 2026-08-13 Status: accepted

Context

Tom asked for lessons and a coding exercise based on ~/Desktop/Bullion Vault - Java Developer - CS Spec.docx, wanting to be "super confident with the issues described and the java technical work required to make sure that commodities service works as expected."

The document turned out to contain no issues and no commodities service. It is a one-page recruiter brief from Client Server Ltd ("CS" is the agency, not "computer science"): a company paragraph, the tech stack, three responsibility bullets, three requirement bullets. The embedded images are the BullionVault logo and the agency's registered-office footer. Nothing technical.

So the premise of the request — "the issues described" — had no referent.

Decision

Confirmed with Tom, then built the exercise domain from BullionVault's own published trading mechanics rather than inventing a generic Java exercise or guessing at a brief that does not exist.

Grounding it in their real product documentation gave the exercise its actual teeth. These are all sourced, not invented:

Orders are placed in kilograms; balances are quoted in kilograms; clients deal in increments as small as one gram.
Spot counterparties quote per troy ounce; that is converted to a price per kilogram for execution and settlement.
Commission is banded on trailing twelve-month volume per metal — 0.50% / 0.10% / 0.05% at the 75,000 and 825,000 thresholds.
Commission is "charged in whole pennies or cents."
A client may deal at a better price than their limit; unfilled remainder rests on the board as an active limit.

Consequences

Good. The troy-ounce-to-kilogram conversion is 1000 / 31.1034768, which has a non-terminating decimal expansion. That is not a contrived teaching example — it is a real property of the domain, and it makes BigDecimal.divide throw. The lesson's central bug was found in the domain, not bolted onto it.

Also good. "Charged in whole pennies" fixes the scale but not the direction, which turned into the lesson's best interview point: when a spec is silent on rounding, name the ambiguity out loud instead of resolving it quietly.

Cost. The exercise is clean-room. If Tom's actual coding test is on BullionVault's codebase, the specific classes will not match — but the failure modes will.

Watch for. If a real technical brief arrives later, revisit MISSION.md and re-aim lessons 0002–0007 at it. They are currently planned, not written, which was deliberate.

The seeded bugs, and why each

Three failure modes, deliberately different in kind rather than three variants of one idea:

Bug	Failure mode	Teaches
`executionPricePerKilogram`	throws loudly	`divide` needs a rounding rule
`consideration`	wrong, silently	integer division; and green tests that prove nothing
`CommissionSchedule`	missing	rounding direction is a business rule; band boundaries

The second is the important one. The naive implementation uses quantity.grams() / 1000 on a long, so the 1 kg test passes and every other quantity settles at USD 0.00. A developer who wrote only the round-number test would ship a desk that gives gold away below a kilo.

Verification

Per [[blackjack-course-tdd-feedback]], the whole cycle was run before shipping, not reasoned about:

RED, in the shipped exercise: Tests run: 13, Failures: 3, Errors: 9 — 12 failing, 1 passing, and the passing one is the deceptive 1 kg case.
GREEN, in a throwaway copy at /private/tmp/.../scratchpad/solution: Tests run: 13, Failures: 0, Errors: 0.
The rounding claim was tested too. Substituting HALF_UP for CEILING in the commission fails exactly three tests (expected: <USD 24.12> but was: <USD 24.11>), which proves the tests actually discriminate on rounding direction rather than merely asserting a number.
Every figure on the BigDecimal reference card is captured output from Temurin 25.0.3.

The exercise directory was left at RED with target/ removed.