Twin declarations start beside the co-located host

Status: Accepted. Date: 2026-10-01. Card t_94bcd252, task t_6e9e0b5f. Amends ADR 0011's ordering of later declarations after the co-located host.

A World that co-locates its twins in one host can still declare a twin as its own process. Dub's planetscale-mysql is one: a MySQL frontend over the planetscale twin's state. The runtime started such a declaration only after the host had published its receipt and every co-located port was admitted. So the frontend's whole process start and readiness sat after the host on every boot.

A co-located twin's address is fixed when its port is allocated, before the host starts. The environment a later declaration consumes, the twin's URL and its templates, is known then. A twin serves: it answers requests and calls no other service while it starts. The planetscale frontend reads its upstream URL from that environment and fetches it per query.

So the runtime records the host's twins and merges their environment as soon as the host is spawned. A later declaration of type twin starts then, beside the host's startup. Any other declaration (an application process, a control-plane service) first waits for the host to be ready, then for every earlier service, as before. up still returns only after the host's receipt and port admission (ADR 0012, ADR 0014) and every declared service's own readiness. A host failure still rolls back every service started so far, including a twin that started beside it.

Measured on Dub's World (32 services), native Node, published runtime 2.0.31 against this branch (with ADR 0014): up took 2.31 and 2.63 s against 1.51, 1.46 and 1.54 s. In the browser tab, probe-instrumented, the time from host admission to the World's env being published was 1.28–5.42 s before and 0.00 s after (the frontend was already ready), in three runs each at load 25–50 (task-evidence/t_94bcd252/f3-diagnostic/final-run/c{0,1,2}-*).

BoundaryCopy Anchor Link

The rule rests on a contract of the twin type: a twin declared outside the host may read a co-located twin's address from its environment, but contacts it only to answer a request, never while it starts. The runtime does not check this. A twin that breaks it finds its upstream's port closed while it starts. If that ends its process, up fails, names the service and rolls back. If it retries until the host is ready, it only starts later. Nothing waits silently on a twin that is not serving. A service that must reach a co-located twin while it starts is declared process, with its own command (for a package twin, the package's bin), and starts after the host is ready.

Evidence boundary: the contract was checked for every twin declared outside a host that this work could find. Dub's World has one, planetscale-mysql. Twin's own example Worlds have none. Planetscale's descriptor names it the twin's nativeTransport, the one such frontend in the catalog. Its server listens without contacting its upstream, and it fetches the upstream per query (read in volter-ai/twin's planetscale package; the planetscale pack this repository runs declares no native frontend). That other twin packages do not call another service while they start is extrapolated from the twin role, not checked package by package.