Lanes: the full design
See the ten-minute version for the loop. The world is described in docs/world.md, the limits in known gaps.
Parts
lanes/world/: the synthetic freight forwarder (generator, schema, answer key).lanes/dictionary/: definitions (YAML), their versions, tests, parameters and the append-only history.lanes/agent/: detectors, policy, rules, workers and the optional model client, the controller, tools, the runner, the scripted desk, replay.lanes/ledger/: the append-only audit trail and approvals.lanes/recal/: the operator measured against the answer key.lanes/ask/: plain-English questions answered through the definitions.app/: the screens.
Authority
| tier | actions |
|---|---|
| 0, just do it | request a missing document, send the carrier's ETA to the customer, book a trucking slot, correct a container number from the matching documents, draft a payment reminder |
| 1, do it and tell | rebook a rolled shipment on a sooner sailing inside the rate card, hold a duplicate booking, hold a declaration for the broker, ask the carrier to check a reefer |
| 2, ask first | accept demurrage, release a bill of lading, amend a filed customs entry, cancel a confirmed duplicate, re-route outside the rate card, order a cargo survey |
| 3, never | pay anything, change a rate, waive a charge, promise a delivery date in writing, delete data |
Data model
One DuckDB file holds the world, the ledger and the answer key. The generator (lanes/world/) writes the world tables in dependency order; docs/world.md lists every table and its volume.
- Master data:
regions,locations(ports and airports with free days and detention days),carriers,shippers,rate_card. - Schedules:
services,vessels,voyages,voyage_calls(scheduled and actual times),eta_updates(the latest at or before now is the current ETA),terminal_slots. - Cargo:
shipments,containers(with the free-time clock),milestones,documents,customs_declarationswith their lines,reefer_readings,invoices,bl_releases,appointments,notifications,charges. - Answer key:
incidents_truth, one row per planted incident with kind, subject and the time the problem began. The operator never reads it; only the Accuracy screen does. - Ledger (
lanes/ledger/schema.sql):ledger,approvals,ledger_repeats. Append-only: the API exposes no update or delete. A change of state is a new row whoseparent_idpoints at the row it acts on.
Decision model
- Detect. Each detector is a dictionary definition (
lanes/dictionary/definitions/*.yaml): a query, its parameters, its version and its tests. A detector returns incidents with the evidence rows that triggered it. Realtime kinds run on every tick, paperwork and money kinds hourly (policy.yaml,detectors). - Propose. A rule maps the incident to an action. Where only one action is possible the rule decides and no model is asked. Where there is a choice, or a tier 2 action is possible, a model may be asked; its answer is checked against the runbook before it goes on. With no model configured, the rules run alone, which is how every published number was produced.
- Decide. The controller reads
policy.yaml: tier of the action, the per-shipper hourly budget, the desk's per-minute budget, the dedupe window. Tier 0 and 1 run, tier 2 goes to the approval queue, tier 3 and anything over budget is declined with the reason written down. - Act. A tool performs the action through the forwarder's own API call (named in the ledger row as
endpoint; in this repository the call is recorded, not sent) and registers its undo. - Record. Every step, including declines, repeats and undos, is a ledger row with the evidence, the definition and version used, the model and its cost, and the approver where there is one.
Authority
The tiers above are the written authority in policy.yaml. Anything not listed is tier 3. The operator cannot edit the file; the controller loads it on every decision, and a change is a new version with a note.
Approvals
Tier 2 items wait in the queue with the proposal, the evidence and the stake in USD. A duty manager approves or rejects; the decision is a new ledger row and an approvals row. In the replay a scripted desk (humans.yaml) answers, with a response time per person and a rule per kind, so the queue behaves like a staffed desk.
Measurement
lanes/recal/ compares ledger detections with incidents_truth: a detection counts when a planted incident of the same kind on the same shipment or container started within twenty minutes of it. Precision, recall, the share handled without a person, reverts, time to resolve (from the problem's start) and cost per resolved incident are computed per day and per detector. A drift check compares week on week. Incidents that began before the operator was switched on are not counted.
Interface
app/ is a FastAPI application with server-rendered templates. Every figure is read from the database at request time by the view models in app/real_*.py. The Lanes board draws a lane per shipment across a time axis, with ports as stops, the free-time clock as a shrinking bar, exceptions as flags and each receipt pinned to its lane. Play mode steps the clock through Tuesday 06:00 to 18:00 at 30, 120 or 360 times speed and shows the receipts as they land. Every screen carries the visitor's arm (v, p) on its links.
Scale
The generator builds 62,000 shipments, 775,000 milestones and two million reefer readings in about five seconds. A replay of one busy day with six days of history takes about two minutes on one core; detectors are set-based queries, so cost grows with the shipments in flight, not with history.
Failure modes
- A detector with a wrong threshold floods the queue: budgets and the dedupe window cap the damage, and the Accuracy screen names the weakest detector (reefer excursion today, at 64 percent precision).
- The model returns something outside the runbook: it is discarded and the rule's action stands.
- A tool fails: the ledger row is
failed, nothing else changes, the incident is raised again after the dedupe window. - A person undoes an action: the undo runs, the row is
rolled_back, and the revert counts against the operator. - Carrier data arrives late or out of order: the generated baseline is cleaner than a live one; see known gaps.