A spread is the price of one thing minus the price of another. In crude the family is small and worth knowing by name: a calendar spread is two delivery months of the same contract, a benchmark spread is the same month of two different benchmarks such as Brent minus WTI, a crack spread is crude against its refined products, and a grade differential is one physical stream against its reference.
The reason to trade a spread rather than an outright is that it isolates a mechanism. A long crude position is exposed to everything that moves the level of oil, which includes the dollar, the rate cycle, and every macro shock in the world. A calendar spread is exposed to the cost of time in one market, and very little else. You have not reduced risk so much as replaced a diffuse risk with a specific one you can articulate.
Two mechanical points cause most real errors.
The first is unit compatibility. Crude trades in dollars per barrel; refined products in the US trade in dollars per gallon. Subtracting one from the other without converting produces a number that is neither. Any comparison that crosses the crude-products boundary has to normalise first, which is what `units.ts` exists for.
The second is joining on the right key. A spread's display label such as "WTI (Sep26/Oct26)" is built for humans, and joining two series on that string will eventually fail: the label changes when the roll moves, when a month is renumbered, or when a formatting choice changes. Join on the tenor or the contract key, never on the text.