Start here
Concepts
bay gives each name one meaning, and these pages use each name only in that meaning.
bay is in development. These pages describe bay as it will ship.
Trunk
Trunk is one linear branch that only grows. Each landing adds one child of the checked base. bay never forces a push to trunk.
Change
A change is a stable id for one intended outcome. A new implementation keeps the same id. A change id is a short lower-case base32 string, for example c7k2m4. An intent is an external reference, such as a card, issue or ticket id. One intent claims one change.
View
A view is the sparse checkout of the declared paths for one change. An absent file in a view is not a deletion. Every view on a machine shares one cache, a blob-less partial clone. After bay start, the view works offline.
Candidate
The draft is the work in the view. bay builds the candidate from the draft and the current trunk. The candidate is one snapshot: a Git tree and the commit that carries it. bay checks the candidate and lands that same commit.
Check
A check is a command that tests a candidate and returns JSON. Each check reports pass, product_failure, infra_failure or unknown. Unknown is never a pass. .bay/policy.toml on trunk lists the required checks.
Evidence
Evidence is one record of what one check, review or runtime observation saw on one snapshot. A producer key signs each record. bay keeps evidence in Git notes under refs/notes/bay/evidence/<producer>. Evidence counts only for the exact tree that it names.
Executor
An executor is the process that finishes a landing after the agent leaves. It claims the operation, runs the checks, and lands the candidate. Only an executor key can move trunk. bay executor run is one executor, and a CI system can be another.
Land
To land is to put one checked candidate on trunk. bay land freezes the draft, builds the candidate, checks it, and lands it. The push to trunk is the only commit point. A change has landed only when its commit is on trunk.
Refusal
A refusal is a result with decision set to blocked. It carries one fixed reason code, such as CHECK_FAILED. allowed lists what you can still do. retry_when says when a retry can succeed. A retry with no change in the cause gets the same refusal and does no work.
Keys
Four classes of key sign in bay: agent, executor, producer and registry. An agent key signs a request to land. An executor key signs the commit that lands on trunk. A producer key signs evidence. A registry key adds and revokes keys. One key belongs to exactly one class.