# 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](../contributing/glossary.md).

**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](./coverage.md).