Volter World

Branch a World

Preserve a known vendor history, reproduce a failure on a variant, then return to the baseline. Branches record parent positions; there is no staging or commit step. Node 22.6 or newer and npm are required in an empty directory.

Create the baseline

package.json
{
  "name": "acme-web",
  "private": true,
  "type": "module",
  "dependencies": {
    "stripe": "17.7.0"
  },
  "devDependencies": {
    "@volter/world": "3.0.169",
    "@volter/twin-stripe": "3.0.2",
    "@volter/world-core": "3.0.156",
    "@volter/world-runtime": "3.0.166",
    "@volter/world-console": "3.0.152",
    "@volter/world-ui": "1.0.156"
  }
}
.env.example
STRIPE_SECRET_KEY=
baseline.mjs
import Stripe from 'stripe';
import assert from 'node:assert/strict';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const customer = await stripe.customers.create({ email: 'branch-repro@example.com', name: 'Ada' });
assert.equal(customer.name, 'Ada');
console.log('baseline customer: Ada');
failure.mjs
import Stripe from 'stripe';
import assert from 'node:assert/strict';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const customer = (await stripe.customers.list({ email: 'branch-repro@example.com' })).data[0];
assert.ok(customer);
await stripe.customers.update(customer.id, { name: 'Unexpected' });
const read = await stripe.customers.retrieve(customer.id);
assert.throws(() => assert.equal(read.name, 'Ada'), { name: 'AssertionError' });
console.log('reproduced: expected Ada, received Unexpected');
verify-baseline.mjs
import Stripe from 'stripe';
import assert from 'node:assert/strict';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const customer = (await stripe.customers.list({ email: 'branch-repro@example.com' })).data[0];
assert.equal(customer.name, 'Ada');
console.log('original branch still has Ada');
npm install
./node_modules/.bin/volter world init --name baseline --twins stripe
./node_modules/.bin/volter world up
./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
./node_modules/.bin/volter world run -- node baseline.mjs
baseline customer: Ada

Review the detected vendor and generated source before booting. This example deliberately creates the faulty mutation on a separate branch; the script asserts that the expected-name check fails rather than exiting unexpectedly.

Fork, reproduce, return

./node_modules/.bin/volter world branch reproduce-signup
./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
./node_modules/.bin/volter world run -- node failure.mjs
reproduced: expected Ada, received Unexpected
./node_modules/.bin/volter world log
./node_modules/.bin/volter world diff
./node_modules/.bin/volter world checkout baseline
./node_modules/.bin/volter world run -- node verify-baseline.mjs
original branch still has Ada

branch switches to the variant, stopping the previous branch. checkout stops that variant and resumes the baseline. Stop app consumers before switching. The child's write is retained; it has not changed the parent's customer. Restore the frozen clock explicitly on each child; a branch's parent position does not capture the caller's clock setup.

./node_modules/.bin/volter world branch
./node_modules/.bin/volter world down

down stops compute and retains state. Keep the baseline's history while the child references it. Purge refuses to erase a referenced parent; ordinary down is the way to stop it.

Reproduce the actual application's failure

Keep its exact packages and lockfile, seed, frozen clock, handler and failing assertion together. A history branch does not snapshot app cookies, application database files outside declared services or process-local handler counters. Restart the relevant owned services and restore those conditions explicitly. Shape a test gives a complete one-time fault/retry example; reproduce a failure explains sharing the reproduction.

A baseline can be forked at an earlier instant with world branch <name> --at <instant>, or at per-vendor positions such as github@12,jira@7. Read positions from world log --json, then consult the CLI reference for replay and as-of syntax. A branch records its parent position; it is not a separate copy of all history.

A native database can have different state rules. The managed SQL example branches stopped PGlite data, changes a row and returns to the unchanged baseline. That is a copy of current database bytes, with one branch running at a time; it has no vendor-log position for historical --at branching, push or deploy. Read the database's scope for your configuration.

For CI isolation, give workers their own roots and application services using the cookbook. For recorded history shared with another person, use team onboarding.

View Markdown source

On this page