Lanes, storage, and transport

Runlane calls its infrastructure setup a lane. Every runtime has one lane.

A lane answers two questions:

Where does Runlane store task state?
How does a worker find out that work is ready?

Runlane runtime
     |
     v
+--------- lane ---------+
| Storage                |
| - run state            |
| - retries and waits    |
|                        |
| Delivery               |
| - poll storage         |
| - transport wakeup     |
+------------------------+

The short version is:

lane = storage + delivery

Delivery is not always a transport. A worker can poll storage directly. A transport such as SQS is useful when a broker or platform needs to wake the worker.

The lanes Runlane ships

Lane	Storage	Delivery	Best for
`@runlane/lane-local`	Process memory	Poll memory	Development and tests
`@runlane/lane-postgres-polling`	Postgres	Poll Postgres, with a best-effort wake signal	A small production setup with always-on workers
`@runlane/lane-postgres-sqs`	Postgres	SQS wakeups	Lambda or long-running SQS consumers

The Local lane loses its state when the process exits. Both Postgres lanes keep run state across restarts.

Storage holds the truth

Storage keeps the current run state and the history needed to recover it. It also holds leases, schedules, durable steps, wait tokens, queue capacity, and pending delivery records.

When two workers race, storage decides which write wins. The broker does not make that decision.

Delivery wakes or finds workers

With storage polling, a worker asks storage for runnable work:

worker -- poll and claim --> storage

With a transport, the message is only a wakeup:

transport message
        |
        v
worker --> read storage --> run or ignore

The message is not the only copy of the job. Duplicate, late, and stale messages are safe to pass to core because core reads the current stored run before it acts.

The transport provider owns broker details such as receipt handles, offsets, visibility timeouts, and message settlement.

Core still owns the workflow

The lane does not decide how retries, waits, cancellation, leases, or task validation work. Runlane core owns those rules. Providers supply storage and delivery mechanics.

A lane can also include optional operator reads for run lists and event history. The Local and Postgres providers include them. Postgres updates its operator view in the same transaction as the stored records.

Know who owns each connection

Starting the runtime starts lane-owned resources. Closing the runtime closes them.

If your app passes an existing database or provider client into a lane, the app still owns that client unless the provider says otherwise.

Use choose a lane to pick a deployment. If you are adding a database or broker, start with build providers.