Skip to content
WonderTwin docs

Concepts

WonderTwin is three components composed by a single Go binary. The Registry catalogs what’s available; the Runtime composes the twins your project needs; the Twins themselves are local, stateful, behavioral models of commercial APIs. This section explains each, plus the drift-alignment mechanism that keeps Pro twins faithful to production.

The Registry

Section titled “The Registry”

The Registry is the backend database of every twin available — Pro and OSS — across all supported source systems. It’s the catalog of what could be twinned, not the merchandising of it (that’s /twins). The Registry exposes per-twin metadata (supported workflows, version, license, fixtures, dependencies) so the Runtime can compose the right set for any given project.

The Registry is also the surface that Agent Twin Discovery consumes: wt scan walks your dependency manifest, looks up matches in the Registry, and reports what’s available. wt catalog browses the Registry directly. See the v0.1.0 release notes for the discovery commands.

The Runtime

Section titled “The Runtime”

The Runtime is the single Go binary (wt) that reads your wondertwin.json, pulls the configured twins from the Registry, and launches each on its assigned localhost port. Milliseconds to start; runs on a developer laptop or a CI runner without orchestration overhead.

The Runtime ships in two variants:

  • Community runtime — MIT-licensed, frozen-snapshot twins. Reproduces vendor behavior at the version stamped at release time. No live calibration.
  • Commercial runtime — Pro twins. Continuously calibrated against production behavior (see Drift-alignment below).

Both runtimes speak the same CLI surface and wondertwin.json schema. Customers can mix Pro and OSS twins in a single configuration.

The Twins

Section titled “The Twins”

A WonderTwin is a local, stateful, behavioral simulation of an external service. Not a mock that returns static JSON — a behavioral model that:

  • Maintains state across requests (a Stripe twin tracks balances, customer state, subscription lifecycle)
  • Fires webhooks with real delivery semantics (signing, retry envelope, ordering)
  • Enforces real rate limits, idempotency keys, and authentication patterns
  • Passes compatibility tests against the vendor’s official SDK

Each twin is built to be a drop-in replacement at the base URL level. Your application code keeps using the vendor’s official SDK; only the base URL (stripe.SetBackend, posthog.init({ api_host }), etc.) changes. See the Integrating WonderTwin guide for the canonical substitution pattern.

Drift-alignment

Section titled “Drift-alignment”

Production APIs change. Stripe ships a new fraud signal, Plaid adds a webhook field, Shopify deprecates an endpoint. A snapshot twin (community runtime) reflects the vendor at the version it was published — useful and stable, but it ages.

Pro twins are drift-aligned. The commercial runtime observes production behavior continuously and applies calibrations to the twin so it stays faithful to current vendor behavior. When a vendor introduces a new field, changes a response shape, or shifts rate-limit policy, the Pro twin picks it up. wt status shows when each Pro twin was last calibrated:

$ wt status
2 twins running · drift-aligned · 0 errors
✓  stripe v0.3.4   · calibrated 2h ago
✓  plaid  v2.0.1   · calibrated 47m ago

OSS twins don’t drift-align — they’re the snapshot. If you need always-current vendor parity, you want Pro. If you want a frozen, MIT-licensed reproducible artifact, OSS is the right tier.

What’s next

Section titled “What’s next”