Known gaps
This page lists what Lanes does not handle, and what its numbers can and cannot show. Read it before you trust a figure in the README.
The data is synthetic
Every port, carrier, shipment, incident and person is generated from a seed (python -m lanes.world.generate --seed 23 --out data/lanes-seed23.duckdb). Nothing comes from a real forwarder, carrier, terminal or customs system.
What that gives:
- The generator records every incident it plants, so precision and recall can be checked against an answer key. Live freight data has no such key.
- A run is repeatable: the same seed gives the same world.
- The controller, the budgets and the approval queue run at realistic volume (about 12,000 shipments in flight, 77,000 containers, three quarters of a million milestones) without touching anyone's systems.
What it cannot show:
- Real traffic. Volumes, transit times, delays and failure rates follow assumptions about ocean, air and road freight. If an assumption is wrong, the numbers are wrong with it.
- Incidents the world does not contain. The detectors were written against the ten kinds the generator plants. Recall says how many planted incidents were found; it says nothing about kinds nobody planted.
- Right thresholds. "Warn 48 hours before free time ends", "four readings out of band", "four hours without an ETA update" are settings to tune on real data, not findings.
- Real false-alarm rates. The generated baseline is cleaner than a live one: carrier EDI arrives on time and in order, documents are typed once. False alarms are probably undercounted.
- A hold-out in the strict sense. One detector threshold and three noise levels of the world were set on seeds 7 and 11 (
lanes/dictionary/TUNING.md). The README numbers come from seed 23, which was never used for that. A new seed is a new draw from the same generator, not new data.
The world does not react to the operator
The world is generated once, with its whole future. When the operator acts, the tables it touches change (an appointment, a request, a hold, a corrected number), but what follows is not simulated again:
- A pickup the operator books does not produce a gate-out or a delivery later; the original timeline still shows the box leaving when a person booked it in the original history.
- A delivery slot the operator rebooks is kept by the haulier (the tool records the truck arriving 40 minutes into the slot). In the real world a second no-show would be possible.
- A rebooked sailing changes the booking, not the voyage the containers were generated on.
- The people's own late fixes stay in the data. After the operator has asked for a document, the request a person made a day later is still there.
So the numbers measure detection and the first decision, not what the operator's actions would have saved. The ledger shows the money at stake as a projection, never as money saved.
Incidents at the end of the window
Some problems cannot be seen until a grace period has passed: an ETA slip needs four hours without an update, a roll three, a reefer run four readings (nine hours), a customs hold thirty minutes. An incident that starts at 17:00 on the replayed Tuesday cannot be detected by 18:00, and counts against recall.
Detector limits
- HS codes are judged by keywords in the description. "General cargo as per invoice" cannot be judged at all, and a correct code on an unusual description ("solid wood dining sets" for furniture) is a false alarm. This is the weakest detector by precision.
- ETA slips read the notifications log. A customer told by phone is only known once the call is logged.
- Duplicate bookings trust the booking note: a deliberate split of one purchase order over two bookings with the same number of containers, and no note saying so, is flagged.
- Container numbers are checked against the booking, not against a carrier's equipment register.
What a pilot needs first
- A read-only feed from the forwarding system (shipments, containers, milestones, documents), the carriers' EDI (schedules, ETAs, rolls), the terminals (discharge, availability, slots), the customs broker (declarations, holds) and finance (invoices, releases), mapped onto the tables in
lanes/world/schema.sql. - The real free days per terminal and carrier contract, the customer promise rules, and the customs desk's own HS reference.
- Adapters for the calls the ledger names (
POST /shipments/{id}/eta-noticeand the rest). None exist. Shadow mode (LANES_SHADOW=1) needs none: every action is written as "would do". - A plan for labels. In shadow mode there is no answer key; people reviewing a sample of "would do" rows is the substitute.