SDK
@volter/world is the product in a library: World and TwinLog, one method per verb, in the same words
as the command line. The volter command is one client of it and adds nothing.
scripts/docs-reference.ts checks this page against the source: every public method of
World appears here.
import { World } from '@volter/world';
const world = World.open(); // the world of the cwd, on its checked-out branch
await world.up();
await world.run(['npm', 'test']);
for (const change of world.log()) console.log(change.service, change.operation, change.subject.id);
await world.down();World
A world: the twins an app needs, running together, on one branch.
Finding and making
| method | does |
|---|---|
World.open({ root?, name? }) | the world of root (default: walk up from the cwd to .volter/world.json), on name or the checked-out branch. Throws when there is no world |
World.find(from?) | the same, or null |
World.init(app?, { name?, vendors?, sources?, allowUnknown?, force?, out? }) | volter world init: detect or select vendors, choose installed packages with sources: { stripe: '@publisher/twin-stripe' }, write .volter/world.json; returns { world, result } with the plan and the coverage proof |
World.initBare(dir, '<org>/<world>', twins, { install?, force? }) | volter world init --bare: a world with no app over the twins named, installed with bun; served as /<org>/<world>/ |
isMain() | whether this is the main branch |
world.name, world.root | the branch, and the world root |
Lifecycle
| method | does |
|---|---|
up({ mode?, seed?, cwd? }) | start the twins; resume a branch that has run before, seed a fresh one unless seed: false. mode: 'sealed' applies cooperative sandbox refusals to mediated HTTP/Fetch and guarded Node connections (transport coverage); native traffic needs an enforced Machine boundary |
down({ purge? }) | stop; purge deletes state if no dependent local branch references it |
run(command, { cwd?, verbose? }) | run a command inside the world; resolves to its exit code; await completion before reading its changes or stopping the World. verbose: true shows the injector routing banner |
activateScript() | the shell script volter world activate prints |
shell() | a subshell with the world active; resolves to its exit code |
status() | WorldStatus: world, branch, branches, running, origin, unpushed, changesets pushed, each service's URL, the env file |
instance() | the runtime's own record of the branch, or null before the first up |
The twins
| method | does |
|---|---|
repos() | one twin log per twin that has recorded anything: its branch entries and what is unpushed |
repo(service) | the twin log for one twin; throws naming the twins the world has |
The log
| method | does |
|---|---|
log() | every change across the twins, oldest first; a pushed change carries its receipt and the changeset that pushed it |
unpushed() | changes not yet pushed |
diff(base?) | the changes since a mark, grouped by twin |
diffBase() | what diff measures from, as it says it: branch <name>, origin, or the story |
Default data
| method | does |
|---|---|
seed({ entry?, cwd? }) | load the default data |
reset({ entry?, cwd? }) | back to the default data |
Branches
| method | does |
|---|---|
branch(name, { at?: { instant?, positions?, views? } }) | a new branch from here or a selected immutable view; positions and views are keyed by twin. Resolves to its World, checked out. This branch stops |
checkout(name) | switch branches; resolves to the target's World |
branches() | the branch names |
replay(name, into) | feed a changeset's changes into another branch's twins, in order, with the same ids |
The clock
| method | does |
|---|---|
clock() | { at, frozen, running }: the instant every twin stamps from, frozen at a set instant, running (shifted), or the wall clock when none is set |
setClock(iso) | set it, frozen at that instant |
advanceClock(by) | move a set clock forward: '30d', '12h' |
shiftClock(by) | move the World forward while its time keeps running (a World serving an application), from the wall clock or a running clock |
clearClock() | return the World to the machine's time |
Serving and remotes
| method | does |
|---|---|
serve({ port?, host?, announce? }) | volter world serve: this world on a URL under /<org>/<world>/; resolves to { url, base, token, readToken, stop } |
view({ port?, host?, console?, announce?, origins? }) | volter world view: this World, its twins' screens, its branches and the console on one origin |
vendors() | the vendors this world has a twin of, as world.json names them: what volter remote add --create makes a hosted World with |
remotes() | the remotes named in world.json, name → url or path |
addRemote(name, target, { token? }) | volter remote add; origin is the default for fetch and push |
removeRemote(name) | forget a remote |
remote(name?) | the remote a verb uses: { url, namespace } or null |
The twins' roots
| method | does |
|---|---|
twin(vendor) | the twin's URL, root and deploy policy, and whether a credential is sealed |
setTwinRoot(vendor, { url, deploy, scope?, refresh? } | null) | volter twin <vendor> root: the vendor's real account behind the twin, in world.json; null clears it |
sealTwinCredential(vendor, input) | seal a credential (a bare token, or a JSON payload) beside the world under the user's key |
rootCredentialInput(vendor) | the credential to seal when none is given: the signed-in vault's kv/vendors/<vendor>, else the one the repo's .env files hold for the vendor; { input, from, notes }, input null when neither holds one |
refreshTwin(vendor) | observe the root now |
The remote
| method | does |
|---|---|
origin() | the remote this world clones from and pushes to, or null |
clone(url, { token? }) | record the remote, store the token, fetch everything |
fetch({ token?, services? }) | bring what the remote has into this branch's cache of its parent; what it reads does not move until pull or named changeset rebase |
pull({ token?, services? }) | fetch and integrate the origin snapshot, preserving inherited local layers and naming conflicts |
changeset({ name?, message?, base?, verifiers?, overwrite? }) | cut a changeset from the unpushed changes |
changesets() | every changeset on this branch, with its file |
push({ name?, token?, force? }) | push to the remote: the named changeset or every unpushed one; resolves to the outcomes with their receipts |
Review, for a remote or a CI job
| method | does |
|---|---|
mark(id?), marks() | a base position across every twin, and the ones recorded |
verify(name, { into?, ephemeral? }) | replay into a clean target and run the changeset's checks |
approve(name, principal, note?) | sign the changeset's current hash |
readiness(name) | ready or not, with every missing leg named |
rebase(name) | integrate the fetched origin snapshot and re-check the changeset; without an origin, use the local base |
rebaseBranch() | rebase this branch onto its base's current position, every twin; conflicts named per record and field |
deploy(name?) | volter world deploy: perform landed changes against each root twin's vendor, by policy; the named changeset, or every ready one. Automatic on arrival only under auto; gated requires checks and approval, and hold requires explicit deployment |
Helpers
| export | does |
|---|---|
parseOriginUrl(url) | https://host/org/world → { url, namespace } |
worldNameFor(app) | the world name init derives from a directory |
findWorldRoot(from?), requireWorldRoot(from?) | the nearest world root |
currentBranch(root), setCurrentBranch(root, name), mainBranch(root) | the checked-out branch |
worldConfigPath(root), worldEnvPath(root), worldSeedPath(root) | the files |
tokenFor(origin), storeToken(origin, token), requireToken(origin, explicit?), credentialsPath() | the token store |
TwinLog
What world.repos() and world.repo(service) return: one twin's log as the world reads it.
| method | what it answers |
|---|---|
service, stateService, root | the twin's name, the state service it records under, its control root |
state() | the tree: the twin's resources as a read sees them |
log() | this branch's own entries, bookkeeping aside |
unpushed({ pushable? }) | entries the parent does not hold |
change(write) | one write through the kernel's write path; the head performs it when the twin's root says so |
Retained history in the kernel
captureHistory(service, root) returns {view, position, descriptor}. Store the view and
position together for a durable cut. readTree(service, root, {view, at?}) reads that retained
view; forkTwin({service, fromRoot, toRoot, occurredAt, view, at?}) branches from it.
historyAtInstant(service, instant, root) captures an immutable time selection, including
noncontiguous inherited and local history. The numeric helper positionAt refuses an instant
that cannot be represented by one contiguous offset.