Reproduce a failure on a branch
Give a teammate the starting state, exact dependencies and request sequence that make the failure observable. A vendor-history branch is one part of that handoff; clock setup, handlers and application state need their own instructions.
Prepare the reproducible bundle
Keep these files in the application repository, using synthetic data:
| Part | What the teammate needs |
|---|---|
| Dependencies | package.json and lockfile, including exact CLI, core, runtime, console, twin and SDK versions; Node version and install command |
| Selected services | Project-owned .volter/world.json, empty credential names in .env.example, and why each vendor or native database is included |
| Starting records | SDK seed entry and the returned identities needed by the app; never edit a twin's state files |
| Time | Baseline instant, child instant and each explicit clock advance |
| Behavior | Project-owned handler files, their config wiring, matcher grammar and SDK retry policy |
| App outcome | Failing entry command, expected business result, observed refusal and records that survive a partial completion |
| Request sequence | Seed, fork, app calls, retry and readback in order; per-vendor positions from world log --json when referring to retained history |
| Other state | Application database, sessions, cookies, local files and receipt reset instructions, naming which are World-managed and which are outside the World |
Never include real credentials to satisfy a key parser. Use the issued throwaway credentials; review any cloned real records before sharing. A catalog recommendation and its historic measurement are separate from the installed package identity.
Rebuild and reproduce
Branch a World owns a complete source example: it seeds Ada through Stripe, forks the history, changes the customer's name, reads the mismatch and returns to the unchanged baseline. Follow its exact files and commands for the smallest example.
For an existing application, install the handed-off lockfile with npm ci, review the selected vendors, then run its seed through the World. Stop application consumers before creating or switching a branch. Restore the child clock explicitly after the fork. Its parent position preserves vendor history; it does not establish an inherited clock configuration.
Shape the World for a test owns the one-time fault and explicit-retry example. Saving a handler alone is insufficient if the service does not name it: keep the handler's wiring in the bundle. Restart owned compute through World commands after editing a handler. A process restart rearms once; a branch does not snapshot its process-local match counters. Write down SDK retries because an automatic retry can hide the first refusal from application code.
The customer onboarding and workplace handoff examples preserve earlier stored results when email or notification fails. Share the observed partial result and which step to resume. Do not label the entire workflow successful merely because its first mutation succeeded.
Read the same evidence
Use world log --json and the SDK's own reads to identify what happened. A position orders one vendor's history. Two vendors can both have position 12, and a frozen clock can give many calls the same timestamp; neither creates a global causal order. The bundle's explicit request sequence explains the cross-vendor workflow.
World-managed application databases belong to the declared service lifecycle. A branch of SaaS history does not copy a browser session, process memory, or application files outside those services. For the workplace starter, company.json and outcomes/ must match the World being reproduced. Only clear those named application receipts after deliberately resetting the disposable example; keep receipts that explain the failure.
Return without erasing evidence
After stopping app consumers, return to the named baseline:
$ ./node_modules/.bin/volter world checkout baseline
$ ./node_modules/.bin/volter world downcheckout stops the current branch and resumes the named one. The failure branch retains its changes. Keep its parent history available; do not purge a referenced baseline. Ordinary down stops compute and retains state.
A teammate can reconstruct synthetic records from the source bundle without a platform account. To transfer recorded history, use team onboarding and the existing changeset/push workflow. Shared baseline and integration illustrates separate workers and explicit destinations. Rebuilding source and transferring history are different handoff methods; say which one the teammate should use.