# The twin

> A simulated copy of your tenant for example data and what-if curves. Never proof.

Source: https://staging.patterna.nl/docs/the-twin

The twin is a simulator that behaves like your tenant: your catalog, your surfaces, simulated users and their responses. It has two jobs. It fills the panel with example data before you have real traffic, and it draws a what-if curve when you simulate a flow. It never produces proof.

## What it is

- **A simulator owned by the jobs.** It runs next to learning and enrichment, not in the serve path.
- **The source of example data.** When a tenant has no real traffic yet, every chart and number in the panel shows the twin's output with an amber "example data" badge. The "Real / Example" switch in the top bar flips the whole workspace. Real views never mix in synthetic rows.
- **A curve in Simulate.** `POST /surfaces/{key}/simulate` returns `twin_curve` when the tenant has a twin: one point per week with a `control` and a `treatment` value. The panel draws it at three truth scales.

Every row the twin produces is flagged `synthetic: true` with source `synthetic`. The API exposes `include_synthetic` so the panel can ask for them on purpose.

## What it is not

- **Not proof.** Synthetic rows are excluded from the ledger. A twin curve that shows a lift says the flow could work under the twin's assumptions, nothing more.
- **Not a forecast.** The twin's users are simulated. Their behaviour comes from assumptions, not from your users' future.
- **Not a replacement for SNIPS.** SNIPS re-weights traffic that really happened. The twin invents traffic. When both are available, trust SNIPS with a large effective sample over the twin, and the holdout over both.
- **Not a copy of your users.** It holds no real user ids and no real events.

## Truth scale

The twin needs an assumption about how strongly simulated users respond to better ranking. That assumption is the truth scale. The panel draws the twin curve at three truth scales so you see a range instead of one line. If the flow only wins at the most optimistic scale, it is a weak candidate. If it wins at all three, it is worth a holdout.

The three scales are 1.0, 0.5 and 0.25. At 1.0 the simulated audience has as much persona structure as the twin's hidden truth model assumes; 0.5 and 0.25 shrink that structure, so personalization has less to find. The twin is calibrated on real distributions only (declared goals and attributes, catalog structure, observed activity), never on invented behaviour. The simulate answer carries the lift at each scale in `lift_by_truth_scale`.

## Status

The simulator is built in the jobs. `twin_weekly` refreshes the curve per surface every day at 05:00 UTC and stores it as a `twin` policy; simulate reads the latest one. A surface without items, or a tenant where the job has not run yet, gets no `twin_curve`.

## Read next

- [Exploration and propensities](https://staging.patterna.nl/docs/exploration-and-propensities)
- [Proof and the ledger](https://staging.patterna.nl/docs/proof-and-the-ledger)