Running against production services (no twins)

This section is short because the rule is simple, and load-bearing because the failure mode is real money or real customer data.

The bright line

Twins are never used in production. Period.

In production, your application talks to real external services directly — the same way it would in a world where WonderTwin doesn’t exist. The entire WonderTwin layer (your agents → WonderTwins → Stack) collapses in prod; only the real-services boundary remains.

Why

WonderTwin’s twins are dev-grade infrastructure by design:

• Twins are calibrated against vendor behavior for development workflows, not under production SLAs.
• Twin hosting (whether yours or ours) is not engineered for prod traffic patterns, durability, or recovery posture.
• A twin is a behavioral simulation. Production should hit the system of record.

A team that routes production through a twin is making a positioning error (twins are a dev tool) and an operational error (twin uptime ≠ vendor uptime).

How to enforce it in your build

The substitution pattern from step 2 defaults to real vendor URLs when env vars are unset — which is the right behavior. But “no twin env vars in prod” is something you can verify mechanically rather than trust. Add an explicit check.

// src/services/registry.ts (continued from step 2)

if (import.meta.env.PROD) {
  for (const name of Object.keys(SERVICES) as ServiceName[]) {
    const resolved = serviceUrl(name)
    if (
      resolved.includes('wondertwin.dev/twins') ||
      resolved.includes('localhost') ||
      resolved.includes('127.0.0.1') ||
      /yourco\.com\/twins/.test(resolved)  // your hosted-twins pattern
    ) {
      throw new Error(
        `[services] ${name} resolved to a twin URL in a production build: ${resolved}`,
      )
    }
  }
}

Run this at module load time so it fails the production bundle before any user request ships. The check is a fail-loud guard for the case where someone accidentally leaks a twin URL into a prod deploy environment.

CI equivalent: add a step that builds the production bundle and asserts the guard didn’t throw.

What to do if you find yourself wanting twins in prod

The cases we’ve heard so far that sound like “I want twins in prod” have all turned out to be different problems:

• “I want to canary-test a vendor change.” That’s a vendor-side concern; feature-flag your code’s usage of the vendor instead.
• “The real vendor is flaky and I want a fallback.” Build a circuit breaker / retry / degraded mode against the real vendor; don’t introduce a twin as production infrastructure.
• “I want to twin some endpoints but call others real.” That’s an architectural variant of the substitution pattern that the current layer doesn’t natively support. If you have a real use case, file an issue or talk to us — we’d want to understand the case before bending the layer.

TODO / coming later

• Production-build CI gate (a worked example of the build-fails-if-twin-URL-detected check)
• Reference Go / Python guards
• Production observability: how to confirm in your APM that you’re hitting real vendors
• Disaster scenarios — what to do if a production deploy is found to be hitting a twin URL