# 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

```json file=package.json
{
  "name": "acme-web",
  "private": true,
  "type": "module",
  "dependencies": {
    "stripe": "17.7.0"
  },
  "devDependencies": {
    "@volter/world": "3.0.63",
    "@volter/twin-stripe": "3.0.1"
  }
}
```

```text file=.env.example
STRIPE_SECRET_KEY=
```

```js file=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');
```

```js file=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');
```

```js file=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');
```

```bash
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.mjs
```

```text
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

```bash
npx volter world branch reproduce-signup
npx volter world run -- node failure.mjs
```

```text
reproduced: expected Ada, received Unexpected
```

```bash
npx volter world log
npx volter world diff
npx volter world checkout baseline
npx volter world run -- node verify-baseline.mjs
```

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

```bash
npx volter world branch
npx 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](./shape-the-world-for-a-test.md) gives a complete one-time fault/retry example; [reproduce a failure](./reproduce-a-failure.md) 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](../reference/cli.md) 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](../../cookbook/ci-workers/README.md). For recorded history shared with another person, use [team onboarding](./team-onboarding.md).

<!-- Fenced tutorial executor: packages/cli/src/journeys/tutorial.ts. Execution scope is recorded separately. -->