Volter World

The model

Volter is Neon for every SaaS. Neon puts a branching storage layer under Postgres's unmodified wire, so a client that speaks Postgres gets branches, checkpoints, time travel and cheap copies without knowing. Volter puts the same layer under every vendor's API, with the vendor itself as the root. This page is the model in full: what is stored, what a branch is, where the vendor sits, and the rules everything else follows from.

What is stored

A twin keeps a log: every write your app made through the vendor's API, in order, recorded as it happens. One line per write, the same form for every vendor: the operation, the record it touched, the fields, the time, and later the receipt. There is no staging area and nothing to commit; what your app did is what the log says.

A checkpoint is the twin's state written out at a position in the log. Reads reuse it while its inherited snapshot is unchanged and fold subsequent local writes. Refresh, rebase or undo can require rebuilding it; a checkpoint never overrides the history it represents.

A branch is a position, not a copy

A branch is an immutable view of its parent's history plus a position within that view, and its own log from there. It starts in an instant, holds only what happened on it, and diff on a branch is exactly its own entries. A clone is a branch whose parent is at a URL; a branch can start from any position or instant in the history (branch <name> --at), without duplicating a local parent’s history. A URL parent’s history is fetched into a local cache, so remote reads remain available locally. Each fetch reads one fixed view across every page and publishes it only when complete. Cached entries are shared across fetched views. A local parent remains available while branches depend on its history. Fresh boot, reset, purge and prune refuse to remove a referenced parent and name the dependent branch. Stop compute with down; remove dependent branches before removing their parent. This follows Neon's child-branch deletion rule.

Retained views carry durable storage references and generation checks. Worlds created before this view format should be recreated; no migration is provided. Raw filesystem deletion and older binaries bypass the lifecycle protection. Refreshing, landing entries in, or rebasing a parent leaves existing children's history unchanged. The child retains exact log prefixes and the order in which its ancestors' changes apply, without copying their payloads. Raw edits to a retained prefix fail its integrity check.

A durable position is {view, position}. An offset alone selects the current view; branch --at twin@<view>:<position> selects a retained one. Selecting an instant creates a fixed view across the inherited and local history, keeping each observation batch whole. A world runs one branch at a time; checkout switches. The default data every twin ships is the starting state for a fresh local World. reset returns the current branch to that data; the runtime implements this by stopping, purging, booting and seeding, while keeping its origin.

The root is the vendor

Every branch tree has a root: the branch whose storage is the vendor's real account. Its log is the account's history as observed, brought in by webhooks where the vendor sends them, by a scheduled pull where it must be asked, and on demand when someone asks — throttled to what the vendor's rate allows, which the twin knows and the world may override. Its checkpoints are the held copy every other branch reads from, so reads never reach the vendor and never spend its rate limit. The root is the one place a real credential lives, sealed.

On your laptop there is usually no root: the world starts from the default data and stays local. A team's shared world is a world served on a URL, and it is where a twin's root is set to the vendor. The vendor is never something you run and never something you clone from. It is where the root deploys to and what the root observes.

Two ways a write lands

At the head of every log sits one of two state systems, chosen per twin per world. The simulated one appends the write and answers from the twin's own state; that is every local world. The real one performs the write against the vendor with the sealed credential and appends the vendor's answer as the receipt; that is a shared world whose twin has a root. Your app cannot tell them apart. Everything else in the world, the log, branches, changesets, checks, serve, clone, fetch and push, is one code path over both.

Push and deploy are different acts

Push appends a branch's entries to its parent's log and moves the branch's base past them, fast-forward only. A push moves entries between worlds and never touches a vendor. Deploy is what a real-system root does with entries that have landed: perform them against the vendor, by policy. auto deploys on arrival, so an app pointed at that world is pointed at the vendor with its keys hidden and every transaction logged. gated deploys after a changeset is verified and approved. hold deploys when someone runs it.

Drift is the parent having changed from the branch's selected view or position, even if the entry count stayed the same. A push refuses rather than overwrite, and says what to do. fetch brings the parent's new entries into the branch's cache without changing what it reads; rebase moves the branch's position onto them and names each conflict by record and field; pull is both. A conflict is data on the changeset, never a stop.

Checks are CI on deployment

A check is a file in the world's repo, run before any entry is performed. It sees the entry and the state, and returns pass or fail with a reason. A failure answers your app with the vendor's own error shape and lands in the log as refused. Under auto that is a check on every call as it happens, and an entry the vendor did not take, refused or failed, does not stay in the tree: a revert lands behind it, so the world says no exactly where the app was told no. The world ships one, a scan for credential-shaped strings, and a team adds its own the way it adds a CI rule.

The rules

  1. Every write is an entry. Revert is an entry that undoes one. Reset returns to default data.
  2. Push appends and advances the base. Nothing is confirmed or suppressed after the fact; the base position is the one record of where a branch stands.
  3. Refresh writes only a root's log. A write reads only the head. The checkpoint is the only thing that reads both.
  4. Branching a shared world's real twin yields a local, simulated branch at the root's current position. Reality has no branches.
  5. A credential lives sealed beside the world that has a root, and nowhere else. The kernel executor applies it by strategy, and the strategy is a fact about the vendor the twin declares (TwinPack.auth): a header replaced, a query parameter set, or a signature computed per request (hmac-sha256, aws-sigv4) over bytes the twin canonicalizes without ever seeing the secret. A declared strategy with no secret refuses rather than sending an unauthenticated request that looks authenticated. Every performed write and every refusal is an entry, so a root's log is the complete audit of what the account was told; a read is answered from the held copy and is not.

Where the words came from

The vocabulary was settled against a survey of twenty systems that version non-text state, from git and Jujutsu through Dolt, lakeFS and Neon to Pulumi, Argo CD and Salesforce change sets. The storage design is Neon's: a log as the truth, branches as positions, checkpoints instead of snapshots. The verbs are git's. The one word git does not have is changeset, because every system that deploys rather than commits calls the reviewable unit exactly that.