The tracking event that matters most is the one that never arrives

Freight visibility products mostly show you what happened. Events land, get placed on a timeline, and the customer watches the dots fill in from left to right.

The problem is that the failures which cost money are absences, and an absence doesn't emit an event.

To see a gap you need something to compare against. Which means the interesting engineering isn't in the event pipeline at all. It's in modelling what was supposed to happen, with enough precision that divergence is computable rather than eyeballed by whoever's looking at the screen.

Plan as data

The plan for a shipment is the chain of steps its lane is expected to follow, each carrying an SLA, expanded at creation time into a set of expected timestamps.

The important design decision is that this is data, not code.

Lanes differ, and they differ in ways that are structural rather than parametric. A corridor routing through a Gulf transhipment has different steps from a direct flight, not just longer ones. A lane into a market with mandatory pre-arrival declaration has a step that other lanes don't have at all. If the expected chain is expressed as configuration attached to a lane, adding a corridor is a row and a review. If it's expressed as conditionals inside the classifier, adding a corridor is a deploy — and eighteen months later nobody can tell you what the system believes "normal" is for any given lane without reading the source.

That second failure is the one worth avoiding, because the plan is the thing operations will argue with. It has to be legible to somebody who doesn't read code, and it has to be editable by them.

Expanding a chain into timestamps needs an anchor per step, and three kinds are worth supporting.

Some steps anchor to shipment creation — the whole clock starts at the order and this step should be done within N hours of it. Some anchor to completion of the previous step, which is the common case and the one that makes the rest of this complicated. And some anchor to an absolute external fact, like a scheduled flight departure, which needs a fallback for the period before that fact is known, because at creation time you generally don't know which flight it's going on.

The cascade is the fiddly part. When a milestone lands two hours late and the steps downstream are anchored to it, the entire remaining plan shifts. If you don't recompute, every subsequent step reads as late, the shipment turns red on the first slip and stays red, and the alerting becomes noise inside a week. If you do recompute, you need to keep the original plan too, or you lose the ability to say the shipment is now four hours behind where it was ever meant to be — because each recomputation forgives the previous slip and the cumulative drift disappears.

So: original plan, current plan, actuals. Three tracks, not two, even though only two get drawn.

Three kinds of gap, and only one is obvious

The first is a time gap. The milestone happened, but not when it should have. Actual minus expected, thresholded into green, amber, red. Everybody builds this one. It's also the least informative of the three, because a two-hour slip on a sixty-hour door-to-door journey usually means precisely nothing and will be absorbed by the next buffer.

The second is a coverage gap. The milestone never arrived, but a later one did. Origin clearance is missing, and yet the freight has departed — so clearance evidently happened, and the event describing it didn't reach us.

That's the interesting failure, and it is completely invisible on any timeline that renders only what arrived. On the screen it looks like a step that hasn't happened yet, indistinguishable from one that genuinely hasn't.

It's also not really an operational problem. It's a data problem wearing an operational costume: a feed dropping messages, an adapter mis-mapping a status code, a party in the chain who simply doesn't report that step and never has. Left undetected it quietly corrupts every metric computed downstream — dwell time at origin, clearance duration, carrier performance — and it does so without ever throwing an error or failing a health check. The pipeline is green. The numbers are wrong.

Detecting it requires the plan, because only the plan knows a step was expected between the two you received. There is no amount of cleverness applied to the event stream alone that recovers this.

The third is a stalled gap. No terminator event, and the last event received is now older than the point at which the shipment should have finished entirely. Nothing is late in the ordinary sense because nothing is happening at all.

Stalls are where the real exceptions live. Freight sitting in a bonded facility waiting for a document. A customs query that went to a shared mailbox nobody reads on Fridays. A consignment offloaded and not rebooked because the person who would have rebooked it doesn't know it was offloaded. These are the three-day silences that turn into a customer complaint, and they are detectable the moment you're willing to treat "nothing has happened for longer than expected" as an event in its own right.

Which is the small conceptual move underneath all of this: the passage of time has to be able to generate a state change. If your system only ever reacts to inbound messages, it cannot notice silence, and silence is the failure mode.

Why this changes the interface

Once you have a plan and three gap classes, the natural rendering stops being a single timeline.

It's two tracks. The plan as a faint upper line, reality solid beneath it, divergence shaded between them.

That sounds cosmetic. It isn't. A single timeline can only answer "where is it." Two tracks answer "where is it relative to where it should be," which is the question the operations team is actually holding when they open the screen. And coverage gaps become visible as holes in the lower track against a filled upper one, instead of being things that were simply never drawn.

It also gives you somewhere to put the uncertainty. A step whose expected time is anchored to a flight you haven't booked yet is genuinely less certain than one anchored to creation, and the interface can say so rather than presenting both with the same confidence.

The uncomfortable part

None of this works if your expected SLAs are dishonest.

The temptation is overwhelming: populate the plan with contractual numbers, or with what the lane is sold as, because those are the numbers that exist in writing and somebody has already agreed them. Do that and amber fires on nearly every shipment, everyone learns within a fortnight to ignore the colour, and you have built an expensive noise generator with a nice interface.

The plan has to encode what the lane actually does, derived from observed history and updated when the operation changes. Which is a harder conversation than it sounds, because it means writing down that a lane sold as four days is a six-day lane, and then having somebody senior look at that.

So the first useful output of a plan-versus-reality system is usually not an alert at all. It's the discovery that your published transit time and your real transit time have disagreed for a very long time, and that until now nobody was in a position to notice.