for agents: this page is markdown at https://switchyard.so/docs/guarantees.md; every page is listed in llms.txt.
Guarantees
This page states what Switchyard promises about your code, your main branch and your history, and which part of Switchyard keeps each promise.
You will have: each promise, stated only as strongly as the product keeps it, with the case where it does not apply. Works with: the board, yard, MCP, REST, and plain Git. The promises are the same on every surface.
The architecture page says how the parts work. The tradeoffs page says what these promises cost.
Main only moves through the merge queue
- The merge queue is the only part of Switchyard that moves main. Agents push to their own task, never to main.
- On a project that follows a GitHub repository, a push made directly on GitHub also moves main. Switchyard reads that push and records it in the project's history.
- A task key and its Git key reach one task's copy of the repository only. In that copy, the store refuses a push to any branch other than the task's branch.
- A task merges only after its checks pass on a test build of main with the task, and the tasks ahead of it, merged in. The merge record names the checks that passed on the commit that merged.
A check runs on exactly its commit
- Every check that Switchyard runs starts on a new machine that holds the checkout of one commit: the test build's. This is true whichever way the machine was set up.
- A check can start from a saved disk of main's checkout, where Switchyard turned that on for the project. A saved disk is used only after two proofs. Before a machine starts from it, Switchyard checks that the disk was made for this project, with the machine image, machine size, network setting and checkout that a fresh setup of this check uses now. After the commit's changes are applied, Switchyard checks that the checkout is exactly the commit's tree: every file as the commit has it, and no file that the commit does not have.
- When either proof fails, or the start from the disk does not finish in time, Switchyard destroys that machine and starts the check on a new machine with a fresh setup. The check never runs on a checkout that failed a proof.
- One project's saved disk is never used by another project. A project made again under a deleted project's id never uses the old project's disks.
- A saved disk is made on a machine that runs none of your commands. It holds main's checkout and nothing from a task that has not merged.
- A check is billed for the time its command runs. The time before the command starts is never billed, from a saved disk or from a fresh setup.
On a fresh setup, a file that .gitattributes converts in a way that cannot be compared with the commit byte for byte is named at the top of the check's log.
A push that Git accepted keeps its commits
- Switchyard writes a push's packs to storage before it moves the branch, and moves the branch before Git is told that the push succeeded.
- When two pushes to the same branch arrive at the same time, one push wins. Git tells the other push
fetch first, and Switchyard keeps nothing of the refused push. - A Git engine is a cache. When an engine stops, a new engine fills itself again from storage. The commits stay in storage.
- The project records each push after Git accepts it. If the notice of a push is lost, Switchyard sends it again, and it also reads each task's branch again on a schedule. A lost notice delays the record of a push; it does not remove the commits.
The record of a push is a separate step from storage. In one load run on 6 November 2026, the commits of one push were kept and the project's record of that push was missing.
Actions are recorded
- The project's history has one order. One part of Switchyard numbers every action, so two agents never get the same number.
- A task's actions (a plan, a submit, a sync) are in the project's history before Switchyard answers with success. An error after a timeout can mean that the action was recorded, so read the task's status before you send it again. An answer with
X-Switchyard-Not-Applied: 1means that nothing was done. - A submit that Switchyard cannot analyse within 30 seconds gets one of two answers, depending on the project.
202means that the submit is recorded: the task enters the merge queue by itself when the analysis is done, and only once.503means that nothing is submitted. - Some project settings (such as a pause or a review setting) can be applied first and recorded right after. Such an answer carries
log: "pending". If the history refuses the entry, the answer carrieslog: "not recorded", the setting stays applied, and the entry is not in the history. - Switchyard writes a merge down before main moves. An interrupted merge is finished from that record.
Conflicts do not block
- A conflict becomes an ordinary commit that records every side. The task continues, and the conflict is fixed when its cause goes away.
- Switchyard remembers a fix that a person makes, and applies it again when the same conflict comes back. The conflicts guide has the five steps that fix a conflict.
You can undo actions
- Every action in the project's history says what it changed. You can undo an action, and the undo is also an action.
- Everything is plain Git. Any Git client reads your repositories.
You can check what merged and why
- Every merge has a merge record: the commit and tree that merged, the main it built on, the rules in force, and for each task its goal, agent, plan, the reviews that let each change merge, and the checks that passed.
- Switchyard does not sign commits. It signs the merge record. Merge records are signed with one key for the deployment and kept as Git notes on main under
refs/notes/yard-attest. - Line 1 of a note is the record as one line of JSON. The rest of the note is its signature. A deployment without a signing key writes line 1 only.
- The signature is in OpenSSH's signature format.
yard verifychecks it against the deployment'sallowed_signersline. A project can pin that line in.yard/allowed_signers.ssh-keygen -Y verifychecks it too. - Each check in a merge record has its name, command and status, and its run time when it ran. A check that reused an earlier pass says how, in the signed record.
"reusedBy": "paths"means that none of the files it reads changed since a pass."reusedBy": "same-tree"means that its paths could not be read and this build already passed. A check withoutreusedByran, or reused a pass on exactly this code. A reader that does not knowreusedByignores it.
Agents only reach what they own
- A task key writes only its own task. A read-only key reads main and cannot push. The teams, roles and keys guide has the lifetime of each key.
- Checks never hold a credential from Switchyard. A GitHub Actions job that your workflow sends to a Switchyard machine gets the secrets that GitHub gives any runner for that job, and Switchyard keeps none of them.