# 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.

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