AgentTwin 0.2.2 · discovery and hosted workflow execution · Node.js 22.12+
Worlds, twins, and replicas
These concepts describe the broader product contract. The current runtime uses explicit fixtures, supported operation mappings and reprovisioning. Automatic shared-identity compilation, coordinated snapshots and comprehensive provider conformance are not shipped. See current capabilities.
A useful test environment is not a pile of disconnected mock endpoints. It is a world: services that share the same entities, events, and state.
Core vocabulary
| Term | Meaning |
| World | A set of service twins plus the shared entities and events that link them. |
| Twin | A service stand-in that implements the subset of provider behavior a workflow depends on. |
| Replica | A disposable, isolated test copy of a world, created from a baseline. |
| Baseline | The versioned starting state a run begins from and can be restored to. |
| Fault injection | A deterministic failure applied at a chosen point in a run. |
| Manifest | The declared coverage of a replica: what is verified, modeled, or unsupported. |
| Regression artifact | The saved starting state, fault point, input, and assertions from a reproduced incident. |
Why "world" and not "mock"
One customer should be the same logical person in a billing system, a CRM, an inbox, and a support tool. A refund can update billing state, emit a webhook, change an internal record, and trigger a notification. A world evaluates that whole chain, not a single endpoint in isolation.
What makes a world useful
- Shared state — related records across services represent the same people, accounts, and business events.
- Observable effects — writes and asynchronous events are recorded so a developer can inspect what actually changed.
- Repeatability — a baseline can be restored, a run repeated, and time or randomness controlled so failures can be compared.
- Branching — one baseline can be explored under several independent scenarios without contaminating the others.
- Failure controls — supported faults can occur at meaningful points, including after a service has already applied a write.
- Outcome verification — correctness is checked against final world state and invariants, not only the agent's natural-language explanation.
- Honest fidelity — each twin should state what is supported, what has been verified, what is unknown, and when verification last ran.
These are product goals, not claims about the current prototype. The browser demo shows the intended shape of these behaviors with synthetic data.
The agent should not have to know
The agent should not have to know whether it is talking to production or a test world beyond the configuration boundary. The developer, however, should always be able to tell which world is active and what that world can faithfully simulate.