Lanes freight exceptions
World clock Tue 18:00:00 UTC held · 120×

Architecture

The design in ten minutes. The full design is one click further. docs/architecture.md

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.

  1. 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 owns customs_hold, the Cold Chain Lead owns reefer_excursion) and tests. Cargo checks run on every tick; paperwork and money checks run hourly, the way broker and finance feeds arrive.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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

KindWhat the detector seesCadenceFirst moveTier
free_time_expiringA container available at the terminal, free time ending within 48 h, no pickup bookedevery tickBook a pickup slot inside free time0
customs_holdA declaration on hold for a missing or wrong document, nobody asked the shipperevery tickAsk the shipper for the document0
vessel_rolledThe carrier rolled the booking and the customer was not toldevery tickTell the customer; rebook on the next sailing inside the rate card0, 1
eta_slippedThe latest carrier ETA passed the promised date, no notice sent within four hoursevery tickSend the customer the new ETA with the evidence0
missed_delivery_appointmentA delivery slot passed and the truck never arrivedevery tickBook the next slot with another haulier0
reefer_excursionFour reefer readings in a row out of bandevery tickAsk the carrier's reefer desk to check the unit1
duplicate_bookingTwo bookings for one purchase order on one sailing, no note saying it is a splithourlyPut the copy on hold1
hs_code_mismatchAn HS code that does not fit the goods descriptionhourlyHold the declaration line and note the broker1
bl_held_unpaidCargo arrived, bill of lading held because an invoice is unpaidhourlyDraft a payment reminder; release once paid0, 2
container_number_mismatchA document names a container number one or two characters off the booked onehourlyCorrect it from the matching documents0

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
Precision91% (397 of 437 detections)
Recall97% (385 of 395 planted incidents)
Handled without a person90%
Reverted by a person0
Weakest detectorreefer_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.