Glossary

Every word a user meets, and no other. Each one passes the same test: a user would search for it, and the field uses it for this thing. Build vocabulary lives in the contributing glossary.

twin — a local, stateful replica of one vendor's API. Your real SDK talks to it with a fake key and gets the vendor's answer. One npm package per vendor: @volter/twin-stripe.

world — the twins an app needs, running together, with the env the app is given. Declared in .volter/world.json, run by volter world up. The thing every volter verb acts on.

volter — the tool that runs worlds, and its command.

vendor — the real system: Stripe, Slack, GitHub. Never something you run and never something you clone from. A root deploys to it and observes it.

log — every write your app made through a vendor's API, in order, recorded as it happens. One line per write, the same form for every vendor. volter world log shows it across every twin.

change — one line of the log: the operation, the record it touched, the fields, the time, and later the receipt. There is no staging area; a write is a change the moment it is served.

checkpoint — a twin's state written out at a position in the log. A read is the nearest checkpoint plus the changes since. Cut every so often, at every changeset and at every branch.

view — an immutable selection of a twin's history. Refreshing or rebasing its source does not change it; local branches share the underlying data.

position — an entry offset within a view. Durable references carry both {view, position}. A bare offset selects the current view; an instant can select a view across inherited and local history.

branch — a parent plus a position in the parent's log, and its own log from there. A world runs one branch at a time; checkout switches. diff on a branch is exactly its own changes.

base — the parent view and position a branch reads through. Push advances it past landed entries; rebase moves it to the parent’s current position. Fetch alone leaves it unchanged.

default data — the coherent starting state a twin ships, loaded through the vendor's API the first time a branch comes up. The position every fresh branch starts from. reset returns to it.

seed — load the default data; also the script that does it, .volter/seeds/story.ts.

reset — return the current branch to default data, discarding its current state. The runtime stops and purges the instance, boots it and runs the seed; the origin remains recorded.

root — the branch whose storage is the vendor's real account. Its log is the account's history as observed; its checkpoints are the copy every other branch reads. Set per twin on a shared world with volter twin <vendor> root <url>; the credential is sealed beside it.

shared world — a world with no app in front of it, served on a URL for a team. Everyone clones from it and pushes to it. volter world init --bare makes one, volter world serve serves it.

remote — any other world, at a path or a URL, that this world can clone from, fetch from and push to. Named with volter remote add. origin is the remote a world was cloned from, and the one fetch and push use when no name is given.

clone — create a branch over a remote’s history and record that remote as origin. A local parent is referenced by path; a URL parent’s history is cached when fetched.

fetch — extend the cached history of the parent without moving the branch’s base or changing what it reads. Rebase moves the position; pull performs fetch followed by rebase.

push — send your changes to a remote as a changeset and move your base past them. Fast-forward only; refused on drift.

changeset — the reviewable unit: a named, hashed range of changes with your message. What a push sends and what a reviewer approves.

deploy — what a root does with changes that have landed on it: perform them against the vendor with the sealed credential, by policy. auto on arrival, gated after verify and approve, hold when someone runs volter world deploy.

receipt — the vendor's answer to one deployed change, on the change itself: landed while it waits, deployed with the vendor's id, refused with a check's reason, failed with the vendor's words, skipped after a failure.

refresh — a root observing the vendor: a webhook, a scheduled pull, or an on-demand pull throttled to the vendor's rate; the twin observes resources and the kernel folds only what changed onto the root's log. Reads use the held state and do not trigger vendor requests.

drift — the parent moved past a branch's base. A push refuses until the branch is rebased.

rebase — replay a branch's changes over the moved base; carry what holds, mark what conflicts. A rebased changeset has a new hash and is reviewed again.

conflict — a change whose assumptions no longer hold, named on the changeset by record and field. Data, never a stop.

check — a file under .volter/checks/ run before any change is performed against a vendor. Pass or fail with a reason; a failure is a refused receipt and the vendor's own error to your app. The world ships one that refuses credential-shaped strings.

verify — run a changeset's checks on the world that deploys, and record the result.

approve — sign a changeset's current hash as a reviewer.

revert — undo one change; a line in the log.

diff — the changes since the base, grouped by twin.

handler — a rule in .volter/handlers/<vendor>.json that tells a twin how to answer a request the vendor would use judgment for: a model's reply, a fault, a lookup.

scenario — the handlers in force and the default data together: the world a test runs in.

size — a variant of a scenario by scale: mini, full.

sandbox — a world whose redirected clients refuse any host that is not a twin. volter world up --sandbox. Cooperative, not a network boundary.

injector — the preload that redirects vendor SDKs to the twins inside a Node process, set by run through NODE_OPTIONS.

activate — make every tool in the current shell reach the twins, through the vendor CLIs' own endpoint variables and an ambient proxy.

token — your credential for a shared world, printed by serve. Stored in your config directory by remote add and clone; never in the repo. Distinct from a key, which is only ever the vendor's real credential, sealed beside a root and readable by nothing.

fake key — the credential a world gives your app: twin-fake-…. A twin accepts any bearer token. The only key on your machine.

example — a runnable, copyable demonstration in cookbook/.

coverage — how much of a vendor's spec a twin serves, in the index.