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
{
"name": "acme-web",
"private": true,
"type": "module",
"dependencies": {
"stripe": "17.7.0"
},
"devDependencies": {
"@volter/world": "3.0.63",
"@volter/twin-stripe": "3.0.1"
}
}STRIPE_SECRET_KEY=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: '[email protected]', name: 'Ada' });
assert.equal(customer.name, 'Ada');
console.log('baseline customer: Ada');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: '[email protected]' })).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');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: '[email protected]' })).data[0];
assert.equal(customer.name, 'Ada');
console.log('original branch still has Ada');npm install
npx volter world init --name baseline --twins stripe
npx volter world up
npx volter world clock set 2026-01-15T12:00:00Z
npx volter world run -- node baseline.mjsbaseline customer: AdaReview 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
npx volter world branch reproduce-signup
npx volter world run -- node failure.mjsreproduced: expected Ada, received Unexpectednpx volter world log
npx volter world diff
npx volter world checkout baseline
npx volter world run -- node verify-baseline.mjsoriginal branch still has Adabranch 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.
npx volter world branch
npx volter world downdown 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.
For CI isolation, give workers their own roots and application services using the cookbook. For recorded history shared with another person, use team onboarding.