The build loop
Studio runs one loop for every builder, so no builder has to get claiming, retries or status reporting right on its own. A builder only builds. It claims work, keeps its claim alive while it builds, and reports one outcome. Studio decides everything else.
Who owns what
Section titled “Who owns what”Studio owns the loop. A builder only builds. That split is deliberate. If every builder ran its own loop, each would get claiming, retries and status wrong in its own way, with slices retried forever, two builders working on one slice, or a slice left in progress after a crash.
- Studio decides which slice is offered and when, who may claim it, how long a claim holds, how many attempts a slice gets, and what status the slice has afterward. Nobody can change a slice’s status by hand while a builder holds it.
- The builder decides how to build: which agent, which tools, which files. It reports honestly, including what it assumed and which specifications it could not run.
- Studio’s own generation uses the same contract. It is the first builder and runs through the same loop and statuses, so the built-in path and a third-party builder cannot drift apart.
From ready to settled
Section titled “From ready to settled”- Offered. When a slice becomes Ready for implementation, Studio offers its backend. When a slice is Waiting for its user interface, Studio offers its user interface. When a slice that was built is deleted, Studio offers the removal of what was built for it (see Removing a deleted slice). Offering an offered slice again changes nothing, so a slice is never offered twice for the same attempt.
- Waiting on dependencies. A slice that builds on slices that are not Done yet, such as a view over events another slice in the same module records, is held back until they are. It is offered as soon as they are done.
- Claimed. A builder claims an offered slice for a part it builds, if the slice is its to build: assigned to it, or to its application’s builder (see Choosing a builder). Exactly one builder wins when several claim at once, and the others are refused. The claim starts the slice, which shows as In progress, and carries the attempt number.
- Leased. A claim holds the slice for a short lease, two minutes by default. The builder renews it with a heartbeat while it works, and may report its step, log and tokens used (contract version 2 and later). Once the lease has run out, or the attempt has passed its deadline (an hour by default), heartbeats and outcomes are refused, which tells the builder to stop.
- Settled. Studio sets the slice’s status from the outcome. A builder never sets it itself, and while a builder holds a slice nobody can change its status by hand.
| Outcome | What happens to the slice |
|---|---|
built |
Ready for review. Waiting when the backend of a slice with screens was built and another builder builds its user interface (see Separate builders) |
nothingToDo |
Ready for review |
blocked |
Blocked, with the builder’s reason and questions |
failed, retryable, attempts left |
Back to the status it had, offered again with the next attempt number |
failed, last attempt or not retryable |
Blocked, with the last failure as the reason |
A lease that runs out, or an attempt that passes its deadline, counts as a failed attempt. After three failed attempts, the slice is Blocked.
A removal-only build of a deleted slice settles the same way, except that there is no slice on the board to set a status on. built and nothingToDo carry the removal out, and where a build would block the slice, the removal is blocked instead. A blocked removal is not offered again, and the next build of the feature still lists it.
Nothing is lost
Section titled “Nothing is lost”Every claim, renewal, failure and offer is recorded on the slice as it happens, so attempts survive restarts. Every thirty seconds, a reconcile pass reclaims leases that ran out and makes any offer that was missed. An offer is missed, for example, when the board had not caught up yet at the moment the slice became ready, or when a slice’s dependencies have been built since.
Cancelling a build
Section titled “Cancelling a build”A person can cancel the build running for a slice. The builder loses its lease, so its next heartbeat or outcome is refused, and the slice goes back to the status it had before the build. It is not offered again until its status is set again.
The numbers
Section titled “The numbers”These are Studio’s defaults. They are not settings of your organization.
| What | Default |
|---|---|
| Failed attempts before the slice is Blocked | 3 |
| How long a claim holds without a heartbeat | 2 minutes |
| How long one attempt may run in total | 1 hour |
| How often leases are reclaimed and missed offers made | 30 seconds |
| How long a registration waits for approval | 15 minutes |
| How long a request for work is held open | 20 seconds |
The agreed values for a connected builder are in the answer it gets when it connects, so a builder should read them instead of hard-coding these.
Related
Section titled “Related”- Builders
- Build a builder, where the Cratis CLI takes part in this loop for you
- The builder protocol
- Build orders and outcomes