Lanes in ten minutes
Lanes is an exceptions operator for a freight forwarder. A forwarder's desk spends its day on the shipments that are going wrong: a container about to run out of free time with no truck booked, a customs hold nobody has chased, a booking the carrier rolled to next week that the customer has not heard about. Lanes watches every shipment the forwarder moves by sea, air and road, finds those exceptions, fixes the ones it is allowed to fix, asks a person about the rest, and writes every step to a ledger that anyone can audit and undo.
This page is the design in ten minutes. The full design has the data model, every table, the decision model in detail, scale, measurement and failure modes. Known gaps says what Lanes does not do.
The picture
flowchart LR
subgraph Sources["Systems of record (read-only)"]
FWD[Forwarding system<br/>shipments, containers, documents]
EDI[Carrier EDI<br/>schedules, ETAs, rolls]
TERM[Terminals<br/>discharge, availability, slots]
CUS[Customs broker<br/>declarations, holds]
FIN[Finance<br/>invoices, releases]
REEF[Reefer telemetry]
end
Sources --> W[(World tables<br/>one schema)]
W --> D[Detectors<br/>dictionary definitions]
D --> P[Proposal<br/>rule, or model where there is a choice]
P --> C{Controller<br/>policy.yaml}
C -->|tier 0-1| T[Tools<br/>each with undo]
C -->|tier 2| Q[Approval queue<br/>duty manager]
C -->|tier 3 / over budget| X[Declined, with the reason]
T --> L[(Ledger)]
Q --> L
X --> L
L --> UI[Lanes board, ledger, queue]
L --> R[Recal<br/>accuracy against the answer key]
Everything to the right of the world tables is the product. Everything to the left is what a forwarder already has. In this repository the world tables are filled by a generator (lanes/world/) that also plants faults and keeps an answer key, so the operator can be scored.
The loop
The operator runs on a clock. On every tick it does six things.
- Detect. Ten checks look for the ten kinds of exception. Each check is a definition in the dictionary (
lanes/dictionary/definitions/*.yaml): versioned SQL with an owner (the Customs Desk Lead ownscustoms_hold, the Cold Chain Lead ownsreefer_excursion) and tests. Cargo checks run on every tick; paperwork and money checks run hourly, the way broker and finance feeds arrive. - Propose. Each new incident gets one proposed action from its kind's runbook. A fixed rule proposes it when the runbook leaves one sensible move. A model is asked only where there is a real choice: a rolled booking can be told to the customer, rebooked on the next sailing inside the rate card, or re-routed at a higher cost.
- Decide. The controller checks the proposal against the written policy (
lanes/agent/policy.yaml). It is plain code, separate from the model, and the model cannot change it. It checks that the action exists and is in this kind's runbook, that every id in the arguments appears in the evidence, the action's tier, its ask-first conditions (a rebook above the rate card asks first), its cooldown, the shipper's hourly budget and the desk's per-minute limit. - Act, queue or decline. Tier 0 runs. Tier 1 runs and tells the people named (usually the account owner). Tier 2 waits in the approval queue for the duty manager, the customs broker liaison or the finance controller. Tier 3 never runs, whoever asks.
- Record. One ledger row per step: the incident, the evidence rows, the definition and version it ran on, whether rules or the model decided, the call it stands for, the tier, who approved, and how to undo it.
- Measure. Recal scores the ledger against the answer key: precision and recall per incident kind, the share handled without a person, reverts, and time to resolve.
The ten exceptions
| Kind | What the detector sees | Cadence | First move | Tier |
|---|---|---|---|---|
free_time_expiring | A container available at the terminal, free time ending within 48 h, no pickup booked | every tick | Book a pickup slot inside free time | 0 |
customs_hold | A declaration on hold for a missing or wrong document, nobody asked the shipper | every tick | Ask the shipper for the document | 0 |
vessel_rolled | The carrier rolled the booking and the customer was not told | every tick | Tell the customer; rebook on the next sailing inside the rate card | 0, 1 |
eta_slipped | The latest carrier ETA passed the promised date, no notice sent within four hours | every tick | Send the customer the new ETA with the evidence | 0 |
missed_delivery_appointment | A delivery slot passed and the truck never arrived | every tick | Book the next slot with another haulier | 0 |
reefer_excursion | Four reefer readings in a row out of band | every tick | Ask the carrier's reefer desk to check the unit | 1 |
duplicate_booking | Two bookings for one purchase order on one sailing, no note saying it is a split | hourly | Put the copy on hold | 1 |
hs_code_mismatch | An HS code that does not fit the goods description | hourly | Hold the declaration line and note the broker | 1 |
bl_held_unpaid | Cargo arrived, bill of lading held because an invoice is unpaid | hourly | Draft a payment reminder; release once paid | 0, 2 |
container_number_mismatch | A document names a container number one or two characters off the booked one | hourly | Correct it from the matching documents | 0 |
If the first move cannot be made, the runbook's next action is tried: no pickup slot left before free time ends becomes a proposal to accept demurrage, which is tier 2.
Written authority
The policy file is the operator's job description. The rule of thumb in it: asking for paperwork, keeping the customer's ETA honest and booking trucks inside free time run at machine speed (tier 0 and 1). Anything that commits money or changes where cargo goes (accepting a demurrage charge, releasing a bill of lading, re-routing outside the rate card, amending a filed customs entry, cancelling a confirmed booking) is tier 2. Paying anything, changing a rate, waiving a charge and promising a delivery date in writing are tier 3. Anything the file does not list is tier 3 too.
Limits sit next to the actions: at most eight automatic actions on one shipper's shipments in any hour, thirty across the desk in any minute, one handling of the same problem on the same thing per thirty minutes, and a separate budget for finance hand-overs so a burst of payment reminders never starves the cargo desk. A shipper that runs out of budget goes to a person, with the reason.
The ledger
The ledger is append-only. A person's approval, rejection or undo is a new row pointing at the row it answers. Each executed tool records what it changed (before and after) and the function that reverses it; the Ledger screen offers the undo and writes it as another row. In shadow mode (LANES_SHADOW=1) tier 0 and 1 actions are written as "would do" and nothing changes.
People
The approval queue holds every tier-2 proposal with the evidence, the controller's reason and the draft request sent to the duty manager. A person approves, rejects with a note, or approves and asks for the rule to be remembered; that last button writes a policy suggestion and never edits the policy. In a replay, a scripted desk of four synthetic people (duty manager, customs broker liaison, finance controller, night desk) answers the queue on their own hours and with their own delays, so the ledger shows names, times and reasons.
One set of definitions
Free time, demurrage, detention, rolled, on-time delivery, active shipment and document complete are written once in the dictionary. Detectors, the operator and the Ask screen read the same definitions as of the same clock. Two terms have two valid meanings and no canonical one: an active shipment for operations (still moving) and for finance (still open on the books), and on-time delivery against the customer's promise and against the carrier's schedule. Ask returns both, side by side, with the numbers and the SQL, and lets the owner make one canonical.
The board
The main screen is the exceptions board. Each shipment the desk touched today is one lane across a shared timeline, twelve days back to nine days ahead: the origin, port calls and destination as stops, sailed legs solid and the rest dashed, the promised delivery date as a diamond, the time an ETA runs past that promise in red. Containers sitting at a terminal carry a free-time bar that shrinks as the clock runs and turns red when demurrage starts. Exceptions are flags on the lane; the operator's latest action is a receipt pinned to its end. Beside it, a map of the network's five regions shows where each shipment on the board is at the clock.
Play mode runs Tuesday 06:00 to 18:00, the busiest window of the week, on a clock at 30, 120 or 360 times real time. With a replayed ledger it plays the stored rows back as the clock reaches them; on an empty ledger, Play starts the operator itself on the same clock. Either way, lanes, flags and receipts land on the board as they happen.
How well it works
One run on seed 23, rules only, the six days before the Tuesday replayed as history (the command is in the README). Seed 23 was never used for tuning; thresholds and noise levels were set on seeds 7 and 11 (lanes/dictionary/TUNING.md).
| Over the replayed week | |
|---|---|
| Precision | 91% (397 of 437 detections) |
| Recall | 97% (385 of 395 planted incidents) |
| Handled without a person | 90% |
| Reverted by a person | 0 |
| Weakest detector | reefer_excursion, precision 64% (14 of 22) |
The Accuracy screen shows the same numbers per detector and per day, from the ledger in the database. They are scores against a generated answer key, not measurements of a real forwarder.
Plugging into a real forwarder
Lanes needs read-only feeds mapped onto lanes/world/schema.sql, the real free days per terminal and contract, and the forwarder's own promise rules. Shadow mode runs on that alone. Before anything runs for real, each call the ledger names (POST /shipments/{id}/eta-notice, POST /terminals/{id}/pickup-slots and the rest) needs an adapter to the forwarder's systems. The model is optional and pluggable (any OpenAI-compatible endpoint through LANES_LLM_*); without it, Lanes runs on rules and the ledger says so on every row.