Spatial Branches
Git for the physical world
Spatial Branches bring version control to the physical world. Branch the live spatial state, design and simulate changes in isolation, review a spatial diff, then merge back into Main — with full history and a complete audit trail. Move fast without ever breaking the world of record.
Core concepts
Spatial designs are not single-shot. A project iterates through dozens of configurations — different pump sizes, different transformer placements, different drone corridors. Without branching, every alternative either overwrites the working design or accumulates as a disconnected copy with no diff history. Branches make iteration first-class.
The model mirrors git exactly, with the same vocabulary.
- Branch. Fork the live spatial state into an isolated copy. The new branch starts identical to its parent; you design, edit, and simulate freely without touching the system of record.
- Main. The canonical branch. Every project has exactly one. Promoting a design to baseline is a merge into Main with the
approveauthority. - Merge. Bring one branch's changes into another. Conflicts surface as Jax-mediated review prompts; you accept, reject, or rewrite each conflicting hunk.
Each branch is a sandboxed copy of the world held in the Nexma DataStore. Run scenarios, let Jax redesign, and throw away what does not work — the live state is untouched until you merge.
How it works
The workflow follows the same five stages whatever the domain.
- Branch the world. Fork the live state into an isolated branch.
- Stage edits. Add, move, and remove entities; every change is tracked against the baseline.
- Open a merge request. Propose the branch for review.
- Review the diff. Inspect the spatial diff — added, moved, and removed entities — and approve.
- Merge to Main. Promote to the live world with full history and an audit trail.
A short example — re-routing a logistics corridor without disturbing the live plan:
1# fork the live state
2branch create "reroute-north-corridor" from Main
3
4# design on the branch (Jax or a human edits the DataStore)
5# move depot, re-run the routing solver, adjust two waypoints
6
7# compare against the baseline
8diff Main..reroute-north-corridor
9 + added waypoint WP-114
10 ~ moved depot DEPOT-3 (1.2 km)
11 - removed waypoint WP-098
12
13# propose, review, and promote
14merge reroute-north-corridor -> Main (requires approve)Operations
- Diff. Compare two commits or two branches. Diffs are spatial — added, modified, and removed features render directly on the globe with a side-by-side toggle.
- Blame. For any feature, show the commit that last modified it and the author who made the change.
- Time-travel. Check out any commit as a read-only view, useful for design reviews and audits.
- Commit. Snapshot the current DataStore state on a branch. Commits carry a message, an author, and a timestamp.
Why editing in place is risky
Traditional GIS edits the system of record in place. There is no safe sandbox to try a change, no way to compare scenarios against the same baseline, and rarely a clean trail of who changed what. Spatial Branches replace each of those gaps.
| Legacy GIS | Spatial Branches |
|---|---|
| Edits hit the live state directly | Work in an isolated branch, merge when proven |
| Scenarios live in separate exports | Branches coexist and diff against one baseline |
| No record of who changed what | Every commit is attributable and reversible |
Working with Jax across branches
Jax operates on the active branch. Switching branches re-points Jax's working context; conversation history is preserved per session, not per branch. Ask Jax to "redo this on a new branch" and it will fork, switch, and replay.
Subagents inherit their parent's branch. A spawned subagent cannot mutate Main unless the parent holds write on Main — see Permissions.
Limits
- Branches are cheap to create but hold a full snapshot of the spatial state. Practical projects keep a working set of single-digit active branches; archived branches stay queryable but do not count against active editing surfaces.
- Cross-project merges are not supported. A branch always exists within one project.
Where to go next
- Nexma DataStore — the versioned filesystem branches operate on.
- Object Explorer — inspect the objects a branch adds, moves, or removes.
- The Ontology — the typed model every branched edit is validated against.
- Permissions — the authorities that gate merges into Main.