Update a twin

Trial a candidate in a separate fresh World before replacing a working release. A new catalog recommendation does not change an existing World's pin.

Keep the identities separateCopy Anchor Link

Inspect the release's README, support gaps and measured journeys in the catalog. Registry availability alone does not establish catalog admission. A version mismatch is a reason to reconcile the dependency and config, not erase the pin.

Walk a concrete trialCopy Anchor Link

Use Node 22.6 or newer in an empty directory. This teaching trial compares two published Stripe package versions; it does not assert that both are admitted in every catalog snapshot. The real SDK asserts the same customer round trip against each release.

{
  "name": "acme-web",
  "private": true,
  "type": "module",
  "dependencies": {
    "stripe": "17.7.0"
  },
  "devDependencies": {
    "@volter/world": "3.0.63",
    "@volter/twin-stripe": "3.0.0"
  }
}

STRIPE_SECRET_KEY=

import assert from 'node:assert/strict';
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, { maxNetworkRetries: 0 });
const made = await stripe.customers.create({ email: 'ada@example.com', name: 'Ada' });
assert.equal((await stripe.customers.retrieve(made.id)).email, 'ada@example.com');
assert.equal(made.created, Date.parse('2026-01-15T12:00:00Z') / 1000);
console.log('create, read and frozen timestamp passed');

npm install
npx volter world init --name current-release --twins stripe
npx volter world up
npx volter world clock set 2026-01-15T12:00:00Z
npx volter world run -- node check.mjs
npx volter world down

create, read and frozen timestamp passed

The current release is stopped with its state retained. Make a new directory containing only the app's project-owned source and a candidate manifest. Do not copy its running state or replace its dependencies:

import { mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
mkdirSync('candidate');
const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
pkg.name = 'candidate-trial'; pkg.devDependencies['@volter/twin-stripe'] = '3.0.1';
writeFileSync('candidate/package.json', JSON.stringify(pkg, null, 2));
for (const file of ['.env.example', 'check.mjs']) copyFileSync(file, `candidate/${file}`);

node prepare-candidate.mjs
cd candidate
npm install
npx volter world init --name candidate-trial --twins stripe
npx volter world up
npx volter world clock set 2026-01-15T12:00:00Z
npx volter world run -- node check.mjs
npx volter world log
npx volter world down
cd ..

create, read and frozen timestamp passed

Compare the two .volter/world.json files: the original source remains @volter/twin-stripe@3.0.0; the candidate source is @volter/twin-stripe@3.0.1. Each has its own lockfile and independent retained state. This walkthrough proves only the named customer assertions, not broad compatibility or state migration.

Adopt deliberately or retain the current releaseCopy Anchor Link

For your real application, run its own tests, seeded history, faults and callbacks in the candidate directory. Adoption updates the exact dependency, lockfile and service source together. Preserve intentional service definitions; do not overwrite an existing config merely to make startup pass. Stop the World and its consumers before changing packages.

Stored-state compatibility is separate from API compatibility. Ask the publisher before reusing old retained state across versions or publishers. Never run two runtime versions over the same instance. If the candidate is unsuitable, keep the original pin and World.

Revocation removes future catalog selection, without silently replacing historical pins. Read its reason and choose another selectable release deliberately. Manual setup explains explicit publisher selection; coverage explains what the release's measurements establish.