Core concepts

Deterministic IDs, virtual clock, snapshot/restore, world snapshots, and destructive-call refusal.

Core concepts

Primitives shared across all five deep clones.

Tenant isolation (runId)

All vendor API traffic is scoped under {cloneUrl}/t/{runId}/.... Two runs never share state. In the dashboard this is a Session (/sessions).

PortRole
:8000Vendor-shaped API
:9000Admin — clock, snapshots, chaos (never public ingress)

Deterministic IDs

IDs derive from seed + runId via HKDF-SHA256 → ChaCha20:

seed="checkout-v1" + runId="run-42" → always cus_AbCdEf123... first

Re-runs with the same seed produce byte-identical IDs and webhook references.

Virtual clock

Admin endpointAction
POST /_clone/clock/advance{ duration: "30d" }
POST /_clone/clock/setAbsolute time
POST /_clone/clock/pause / resumeFreeze / resume
await clone.advanceClock("30d"); // trial expiry, dunning, OTP TTL

World snapshots pause all clones before saving.

Snapshot and restore

const blob = await clone.snapshot();
await clone.restore(blob);
  • Format: gzip JSON, schema-versioned (molar/clones-stripe@v1)
  • Chaos rules persist in snapshot state
  • World snapshot: Molar API PAUSE → snapshot each → RESUME
import { world } from "@molar/clones";
const registry = world.localRegistry([stripeClone, emailClone]);
await world.snapshot(registry, runId, "checkpoint");

Destructive-call refusal

The SDK blocks live vendor hosts + live key patterns before network I/O:

  • Hosts: api.stripe.com, api.twilio.com, amazonaws.com, …
  • Keys: sk_live_, production Twilio SIDs, …

Escape hatch (intentional only): MOLAR_DESTRUCTIVE_ALLOW=1

Chaos injection

await clone.injectError({ path: "/v1/charges", method: "POST", status: 402, rate: 1.0 });
await clone.injectLatency({ path: "*", p50: 100, p99: 2000 });

Webhooks

Vendor-correct signing: Stripe HMAC-SHA256, Twilio HMAC-SHA1, Svix for Clerk/Resend. Keys: HKDF(seed, "webhook-secret").

await clone.expectWebhookFired("checkout.session.completed", 30_000);

Next steps