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.test.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();
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?, allowUnknown?, force?, out? })`	`volter world init`: detect vendors, 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'` is the sandbox
`down({ purge? })`	stop; `purge` deletes state if no dependent local branch references it
`run(command, { cwd?, verbose? })`	run a command inside the world; returns its exit code; `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 }`: the instant every twin stamps from, or the wall clock when none is set
`setClock(iso)`	set it
`advanceClock(by)`	move a set clock forward: `'30d'`, `'12h'`

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 }`
`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
`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.