Workspace model
Snapshots, heads, and overlays: the small set of ideas that let Bowline advance your project state safely.
Bowline builds continuity from a few precise ideas. Once you know them, the rest of the product (sync, conflicts, work views, and agent leases) reads as variations on the same model. This page defines those ideas and how project state moves forward.
The core terms
Bowline tracks project state as durable Workspace Snapshots, a single current Workspace Head per project, and overlays that hold in-progress writes until they're safe to merge.
| Term | What it is |
|---|---|
| Workspace Snapshot | A durable project state that follows authorized machines and agents, including uncommitted, source-like work. |
| Workspace Head | The current canonical Workspace Snapshot for a project. |
| Machine Overlay | Local writes from one machine before they advance the Workspace Head. |
| Agent Overlay | Isolated writes from an agent lease before they advance the Workspace Head or become a conflict. |
| Resolution Overlay | A proposed conflict repair output, before you accept it. |
| Automatic Merge | A proven-safe merge that advances the Workspace Head without any action from you. |
| File Identity | The continuity of a file across path changes, so safe edits can follow a rename. |
A project has exactly one current Workspace Head, and it points to one Workspace Snapshot. Everything else is how Bowline creates a new Workspace Snapshot and moves the Workspace Head to it.
How state advances
Most of the time, state advances without you noticing. As you work, your writes collect in a Machine Overlay based on the current Workspace Snapshot. When those writes don't clash with newer work, Bowline turns them into a new Workspace Snapshot and advances the Workspace Head automatically.
The same is true for agents. An Agent Overlay holds a lease's writes; if they don't conflict, they become a Workspace Snapshot and advance the Workspace Head, with no Git publish required. Publishing to a remote stays your decision and your tool's job.
- You (or an agent) write files. The writes land in an overlay based on the current head.
- Bowline coalesces noisy file events and checks the writes against the latest Workspace Head.
- If the changes are safe, an Automatic Merge advances the Workspace Head to a new Workspace Snapshot.
- If they aren't safe, Bowline opens a Sync Conflict and preserves both sides.
Only a Resolution Overlay needs your acceptance. Ordinary, non-conflicting machine and agent overlays advance the Workspace Head on their own. That's what makes the workspace feel like it just stays in sync.
What Automatic Merge can do safely
Automatic Merge is deliberately conservative. It proves a merge is safe before it advances the Workspace Head, rather than guessing. It handles changes that are mechanically safe to combine:
- Edits to different files.
- Edits to different regions (hunks) of the same text file.
- Safe edits carried across a rename, when File Identity has strong evidence that it's the same file.
For Structured Text, which covers config and manifest files, Automatic Merge applies only when the merged output still parses. If a merge would produce a file that no longer parses, Bowline treats it as a conflict instead of risking a broken config.
Overlays keep work isolated until it's safe
Overlays are how Bowline keeps in-progress writes from corrupting canonical state. A Machine Overlay isolates one machine's pending writes. An Agent Overlay isolates one lease's writes. A Resolution Overlay holds a proposed conflict fix until you accept it.
This is also the basis for work views: an explicit,
review-before-apply overlay under ~/Code/.work that never touches the main
project until you accept it.
Next steps
- Sync and continuity: how writes are captured and synced as you work.
- Conflicts: what happens when work diverges.
- Work views: isolated, review-before-apply project views.
- Agent leases: scoped authority for coding agents.