How we pick what a twin covers

Every digital twin simulates a slice of its upstream API, not the whole thing. GitHub alone exposes hundreds of REST routes; no twin needs all of them to be useful, and building all of them would mean spending fidelity budget on routes agents never call. We pick the slice deliberately, using the same rubric across every twin.

​

The three heat tiers

We sort every upstream endpoint into one of three tiers, ranked by how often an autonomous agent actually reaches for it. This is the same heat axis (hot / warm / cold) that each twin’s FIDELITY.md carries in its Heat column, and that packages/sdk/ENDPOINT-TIERS.md defines the rubric for — this page restates that rubric for readers who haven’t found the engine-level doc yet.

• Hot path — the endpoint sits on a task an agent routinely performs against this API: collecting a payment, triaging an issue, posting a message to a channel. If a hot-path endpoint were shallow, an eval run against the twin would silently diverge from what happens against the real service — the failure mode we care most about avoiding. A twin implements its hot path with full behavior: state changes, side effects, and error semantics that match the live service, backed by tests.
• Warm path — adjacent to a hot path: a context read, an occasional cleanup step, or a real chain that’s too long or too rare to justify full behavioral modeling yet. A warm-path call never fails loudly by surprise, but you shouldn’t build an agent that depends on its side effects. A twin implements its warm path so the response shape matches the live service, without necessarily reproducing every stateful consequence.
• Cold path — not plausibly on an autonomous agent’s task chain: browser redirect flows, admin and enterprise surfaces, or anything outside a twin’s product scope. A twin does not implement its cold path at all. Calling a cold-path route returns a loud, structured error instead of a silent 200 — see what happens if you call an unimplemented endpoint.

We decide which band an endpoint falls in the same way for every twin: enumerate the tasks agents actually run against that API, then cross-check against the upstream vendor’s own default-enabled agent tooling where one exists. Endpoints on a real task chain are hot even if a vendor’s tooling doesn’t expose them; the task chain wins disagreements.

​

This is a different axis from fidelity tiers

Each twin ships a FIDELITY.md in the pome-sh/digital-twins repo that classifies every implemented endpoint into a fidelity tier — semantic, shape, or unsupported — describing how faithfully that endpoint’s behavior reproduces the real service. Heat and fidelity tier answer different questions and should not be read as two names for the same thing: They correlate — a hot-path endpoint is expected to reach semantic fidelity, a warm-path endpoint shape, a cold-path endpoint stays unsupported — but the words aren’t interchangeable. In particular, cold is not a synonym for unsupported: cold describes an endpoint we chose not to model because agents don’t plausibly need it, while unsupported describes the measured fidelity of an endpoint today, whatever its heat. A warm-path endpoint can also be unsupported while work is in flight, and that’s tracked as a gap, not a scope decision. For the endpoint-by-endpoint tier tables, see the FIDELITY.md in that twin’s package directory in pome-sh/digital-twins — for example packages/twin-github/FIDELITY.md.

​

How much of each API is covered

Exact counts change as twins add surface area, so we don’t hand-type them here — they’d go stale the next time a twin ships a new endpoint. status.pome.sh is an uptime page (Operational / Degraded / Down per twin), not a coverage inventory — it doesn’t break endpoint counts out by fidelity tier. For the current per-endpoint tier tables, see the twin’s FIDELITY.md linked above.

​

Calling something outside the hot or warm path

If your agent calls a cold-path (or not-yet-implemented) endpoint, the twin returns a loud 501 instead of a silent success — but the exact envelope shape isn’t universal across twins. Each twin mimics the error shape of the upstream it clones, so the unsupported signal lives in different places:

• GitHub and Slack nest it under a _twin namespace:
  {
    "message": "This endpoint is not supported by this GitHub twin clone.",
    "_twin": {
      "fidelity": "unsupported",
      "supported_surfaces": ["..."]
    }
  }
  
• Stripe nests fidelity and supported_surfaces on its native error object instead of _twin.
• Linear puts a top-level fidelity field alongside its GraphQL-style errors array, with no _twin namespace.
• Gmail mirrors Google’s UNIMPLEMENTED error shape and carries no fidelity marker or supported_surfaces list at all.

Don’t hardcode a check against _twin.fidelity === "unsupported" — it only holds for the GitHub and Slack twins. Check the twin’s own 501 shape (each twin’s FIDELITY.md documents it) or key off the HTTP status code (501) instead, and treat it the way you’d treat a real 404 on a route that doesn’t exist: not retry into it. If the endpoint you need isn’t covered, file it against the twin’s repo (pome-sh/digital-twins) with the route or MCP tool name and the task you’re trying to run — that’s exactly the input we use to move an endpoint onto a warm or hot path, or to raise an existing one’s fidelity tier.