Cloud relay admission and continuity
The cloud relay gives each paired host and phone a current home. It assigns that home, admits control and data connections, and moves the pair in a controlled way when a cell or edge home drains or changes region. Durable assignment state and connection checks prevent an old home from acting as current while allowing clients to reconnect after a short outage. See Cloud services, Push notification delivery, and Cloud operational deployment controls for related views.
Relay service role
The relay has two linked roles. A director chooses and records a host home. A cell or edge home proves that assignment and carries the host control connection and phone data connections. The assignment epoch identifies the current move and lets both sides reject an old path.
Assignment authority
The director is the authority for a host's home, region, assignment epoch, and lease. A new epoch means that the host moved. A cell or edge home can then reject a connection that names an older home. The director checks liveness and capacity before it issues an assignment. Durable assignment state remains the source of truth while signed lease checks can be compared during rollout. cloud/…/app.ts• L448-481, cloud/…/assignment-lease-shadow.ts• L44-65
The assignment store also bounds work for one host and limits waits on shared cell inventory. A storage or row-lock fault becomes a retryable result instead of an unbounded queue. cloud/…/assignment-identity-queue.ts• L1-23, cloud/…/assignment-store.ts• L948-1110
References: cloud/…/app.ts• L448-481 cloud/…/assignment-lease-shadow.ts• L44-65 cloud/…/assignment-identity-queue.ts• L1-23 cloud/…/assignment-store.ts• L948-1110
Paired connection model
The host is the long-lived control peer. A phone reaches the assigned home and asks the host to open a matching data leg. The home joins the two legs only after it checks the assignment, credentials, host session, and connection ticket. cloud/…/host-session-registry.ts• L811-1037
Control and data admission are separate. A returning host can therefore regain control when ordinary phone traffic is full. The home closes a data leg when its host, assignment epoch, control generation, or cell incarnation is no longer current. cloud/…/host-session-registry.ts• L1105-1215
References: cloud/…/host-session-registry.ts• L811-1037 cloud/…/host-session-registry.ts• L1105-1215
Assignment admission
Assignment admission protects shared state and preserves a path for recovery. New placement, known-host reconnect, drain return, reserve lookup, and edge movement use separate capacity so one burst does not block another class of work.
Admission lanes
The public assignment service places requests into bounded lanes. Each lane limits active work, queue length, wait time, and repeat attempts.
| Lane | Purpose | When unavailable |
|---|---|---|
| Placement | Choose a safe home for a new or fallback request | Retryable placement response |
| Sticky | Check and renew a known home during reconnect | Retryable sticky response |
| Drain return | Re-place a host released from an isolated home | Paced retry response |
| Reserved | Resolve a resume credential without using placement capacity | Retryable reserved rejection |
| Edge movement | Move a host into or out of an edge home with its paired state | Deferred result; current home stays authoritative |
The server selects the drain-return lane from durable home state. A client cannot select it with a hint alone. Bounded rejection logs summarize repeated events so retry traffic does not create unbounded log volume. cloud/…/app.ts• L224-306, cloud/…/app.ts• L599-670, cloud/…/assignment-rejection-log-window.ts• L1-53
References: cloud/…/app.ts• L224-306 cloud/…/app.ts• L599-670 cloud/…/assignment-rejection-log-window.ts• L1-53
Reserve admission
Reserve admission is a cell-local path for a controlled rollout. The director books a short-lived seat. The cell checks its own capacity, intake budget, drain state, and current seat before it accepts the booking. The cell makes the final decision. cloud/…/relay-server.ts• L324-387, cloud/…/cell-reserve-contract.ts• L3-48
Reserve mode has a safe return path. A dead-man stops memory admission when director contact is lost. The cell then returns to database admission and re-registers memory-admitted controls in bounded batches. Unknown reserve state fails closed for placement and maintenance. cloud/…/assignment-store.ts• L666-806, cloud/…/host-session-registry.ts• L493-565
References: cloud/…/relay-server.ts• L324-387 cloud/…/cell-reserve-contract.ts• L3-48 cloud/…/assignment-store.ts• L666-806 cloud/…/host-session-registry.ts• L493-565
Edge cohort admission
An edge home is a controlled home for a cohort of hosts. Cohort membership comes from runtime mode, rollout share, region scope, allow lists, and deny lists. The director treats the edge as an existing-only home, so a phone resolve can return it without trying ordinary placement. cloud/…/edge-relay-control.ts• L11-32, cloud/…/edge-relay-cohort.ts• L52-85, cloud/…/edge-relay.ts• L44-48
The host moves to the edge only after the edge is ready and its paired-device state is available there. Repeated assignment asks renew the same edge home without changing its epoch. The cohort grows and shrinks through director control rather than a client claim. cloud/…/app.ts• L482-549, cloud/…/edge-relay.ts• L126-199
References: cloud/…/edge-relay-control.ts• L11-32 cloud/…/edge-relay-cohort.ts• L52-85 cloud/…/edge-relay.ts• L44-48 cloud/…/edge-relay.ts• L126-199 cloud/…/app.ts• L482-549
Edge-native director
The edge-native director is a dark, optional assignment path. When enabled for a dedicated hostname and the object backend, the Worker answers assignment, resume, region-catalog, and invite-move requests from the host's own durable object. When it is unset, malformed, reached through another hostname, or used with another backend, normal edge routing stays unchanged. cloud/…/director-config.ts• L1-9, cloud/…/index.ts• L28-47, cloud/…/director.ts• L97-111
The host object acts as the placement record for this path. A first assignment creates the record with epoch one. A URL change or account change raises the epoch. A host placed by the legacy director is reported as elsewhere rather than taken over. A frozen host returns a temporary result while export is in progress. cloud/…/director-assign.ts• L7-40, cloud/…/host-relay-director.ts• L20-50
Country routing can select a front door for a configured country set and the edge URL for other countries. The region catalog gives clients probe origins. A preferred region is used as a location hint only when the host object is first created; objects do not move because a preference changes. cloud/…/director-config.ts• L36-87, cloud/…/director.ts• L114-139
The edge-native path keeps the client contract small. A host receives its cell URL, assignment epoch, and an opaque lease. A phone resolve checks a resume credential. An invite move checks an invite credential and returns the current host home so the phone can dial it. cloud/…/director.ts• L141-205
References: cloud/…/director-config.ts• L1-9 cloud/…/director-config.ts• L36-87 cloud/…/director.ts• L97-205 cloud/…/director-assign.ts• L7-40 cloud/…/host-relay-director.ts• L20-50 cloud/…/index.ts• L28-47
Reconnect admission
When a request declares a reconnect, the director first checks the durable home in the sticky lane. A usable home is renewed in place. A missing or unusable home falls through to placement. A roll-isolated home enters the paced drain-return lane. cloud/…/app.ts• L599-670
The director also detects a stranded host. This is a host with a recent grant on an existing-only home but no live activity after enough time to attach. It falls through to placement instead of renewing a home that cannot serve it. cloud/…/assignment-store.ts• L1264-1301
An edge phone resolve returns the edge home without moving the host. The host's own assignment request controls entry or exit. This prevents a phone retry from creating a competing placement. cloud/…/app.ts• L787-847, cloud/…/edge-relay.ts• L110-124
References: cloud/…/app.ts• L599-670 cloud/…/app.ts• L787-847 cloud/…/assignment-store.ts• L1264-1301 cloud/…/edge-relay.ts• L110-124
Drain-return pacing
The drain-return lane has a budget apart from sticky and placement work. When that budget is full, the director gives the host a future retry time. This spreads a drain cohort at the rate that replacement homes and durable state can serve it. cloud/…/app.ts• L224-239, cloud/…/drain-return-admission.ts• L13-116
References: cloud/…/app.ts• L224-239 cloud/…/drain-return-admission.ts• L13-116
Assignment flow
This diagram shows how ordinary placement, reconnect, reserve admission, edge movement, and the edge-native director reach a signed or opaque home assignment.
flowchart TD
request[Assignment request] --> route{Assignment path}
route -->|Edge-native hostname| native[Host object assignment]
route -->|Edge cohort move| edge[Edge assignment]
route -->|Reserve mode| reserve[Seat booking or resume]
route -->|Reconnect| sticky[Sticky home check]
route -->|New or fallback| placement[Placement lane]
sticky --> valid{Durable home valid?}
valid -->|Yes| renew[Renew current home]
valid -->|Roll isolated| drain[Drain-return lane]
valid -->|No| placement
reserve -->|Missing or stale seat| placement
native --> result[Home and assignment epoch]
edge --> result
renew --> result
drain --> choose[Choose safe replacement]
placement --> choose
choose --> result
The reserve path answers from a seat map only when the director and cell have live evidence. A partial or stale view returns to durable placement or asks the client to retry. cloud/…/reserve-assignment.ts• L151-229, cloud/…/app.ts• L463-585
References: cloud/…/app.ts• L482-585 cloud/…/app.ts• L599-785 cloud/…/reserve-assignment.ts• L151-229 cloud/…/director.ts• L97-160
Regional placement and rehoming
Regional placement tries to keep a host near its preferred region while preserving a safe fallback. Rehoming is a controlled move for an idle host or an edge cohort change. It does not force every active session to move at once.
Regional preference
An assignment request can carry a preferred region. The director stores that preference separately from the current assignment, so a preference change does not move an active host by itself. If the preferred region has no safe home, placement uses another available region and reports the selected region. cloud/…/app.ts• L441-449, cloud/…/relay-region-placement.test.ts• L48-94
Regional correction is a time-bound report against the current assignment. The first valid report wins. A change in assignment epoch or region makes the report unusable. The report does not create a new assignment. cloud/…/app.ts• L693-721, cloud/…/relay-region-app.test.ts• L236-307
References: cloud/…/app.ts• L441-449 cloud/…/app.ts• L693-721 cloud/…/relay-region-placement.test.ts• L48-94 cloud/…/relay-region-app.test.ts• L236-307
Reserve reconnect rehome
Reserve reconnect rehoming moves an existing host only when its remembered reserve home is outside the requested region. It runs during reconnect placement rather than as a forced disconnect. A fresh operator switch, a stable host cohort, target headroom, and a source rate budget must all allow the move. cloud/…/reserve-rehome.ts• L34-95, cloud/…/reserve-assignment.ts• L490-549
The path stays sticky when it cannot prove a safe move. A stale switch, failed target booking, recent move, or recent peer drop leaves the host on its current home. cloud/…/reserve-rehome.ts• L51-176
References: cloud/…/reserve-rehome.ts• L34-176 cloud/…/reserve-assignment.ts• L490-549
Idle regional rehome
The idle rehome path moves a host only when it has no active connections and both source and target have current health and headroom. Reserve-mode homes are excluded because their host state is held in memory. cloud/…/assignment-store.ts• L4109-4175, cloud/…/host-session-registry.ts• L352-401
The director checks fleet safety, regional control, cohort state, database failure state, and a durable dispatch budget. The commit checks them again and reserves target capacity in the same transaction. A failed reservation rolls the move back. cloud/…/assignment-store.ts• L4177-4282
References: cloud/…/assignment-store.ts• L4109-4175 cloud/…/host-session-registry.ts• L352-401 cloud/…/assignment-store.ts• L4177-4282
Rehome safety gates
Rehoming pauses when monitoring is stale or when the system sees unsafe database failure, high reconnect volume, control recovery failure, or pool pressure. The gates apply during selection and durable commit. A blocked move leaves the host on its current assignment. cloud/…/assignment-store.ts• L4117-4148, cloud/…/assignment-store.ts• L4184-4247
Reviewed director deployment also checks that durable rehome control is disabled before a cohort or traffic change. This keeps deployment movement separate from an in-progress host move. cloud/…/deploy-relay-blue-green.mjs• L874-900, cloud/…/deploy-relay-blue-green.mjs• L1128-1155
References: cloud/…/assignment-store.ts• L4117-4148 cloud/…/assignment-store.ts• L4184-4247 cloud/…/deploy-relay-blue-green.mjs• L874-900 cloud/…/deploy-relay-blue-green.mjs• L1128-1155
Draining and migration
Draining removes a home from new work while giving its paired hosts a controlled route to a replacement. Home-wide pacing and per-host migration state remain separate so operators can spread reconnect load.
Cell drain
An administrative drain marks a cell as draining and sends a drain message to live hosts. An optional pace window spreads those messages. A host then resolves its assignment through the director and reconnects to the selected destination. cloud/…/host-session-registry.ts• L1472-1515
The cell continues to accept hosts that have not received a drain message. After a host receives one, it becomes drain-only and its grace timer closes the old control session. A repeated drain replaces the earlier timer. Reserve bookings clear when drain starts. cloud/…/host-session-registry.ts• L1472-1505, cloud/…/relay-server.ts• L389-412
References: cloud/…/host-session-registry.ts• L1472-1515 cloud/…/relay-server.ts• L389-412
Edge evacuation
Edge evacuation removes hosts that no longer belong to the active cohort. A director sweep sends a signed drain request to the edge. The host asks the director again, exports edge-held device state, and then moves to an ordinary home. Cooldown and bounded concurrency spread the work. cloud/…/edge-relay-evacuation.ts• L11-27, cloud/…/edge-relay-evacuation.ts• L75-103
The edge-native path exposes the same control boundary through signed admin calls. Assign pushes the current assignment and device set. Export freezes a host for movement and returns its state. Drain sends live controls back to the director. Replayed admin tokens are refused, so a copied control request cannot apply twice. cloud/…/admin.ts• L1-22, cloud/…/index.ts• L70-128, cloud/…/host-relay.ts• L31-95
An export that cannot prove edge state after a bounded outage does not restore uncertain credentials. The director places the host without that copy and fences the old edge assignment. Phones then receive a wrong-home result and resolve again. cloud/…/edge-relay.ts• L256-346, cloud/…/edge-relay-fence.ts• L105-179
References: cloud/…/edge-relay-evacuation.ts• L11-27 cloud/…/edge-relay-evacuation.ts• L75-145 cloud/…/edge-relay.ts• L256-346 cloud/…/edge-relay-fence.ts• L105-179 cloud/…/admin.ts• L1-22 cloud/…/index.ts• L70-128 cloud/…/host-relay.ts• L31-95
Migration continuity
An explicit evacuation and an idle regional rehome use the same continuity rule. Durable state changes first. The destination then proves the new epoch and registers the host. Activity leases and connection reservations keep the move visible while the host changes homes. cloud/…/assignment-store.ts• L4750-4864, cloud/…/assignment-store.ts• L4177-4268
The source may serve during the handoff, but it is not authoritative after the durable move. A source or target with a mismatched cell incarnation, host generation, or assignment epoch is rejected. A newer assignment can supersede an unfinished move and release its old reservations. cloud/…/assignment-store.ts• L4038-4187, cloud/…/host-session-registry.ts• L1890-1962
References: cloud/…/assignment-store.ts• L4038-4187 cloud/…/assignment-store.ts• L4177-4268 cloud/…/assignment-store.ts• L4750-4864 cloud/…/host-session-registry.ts• L1890-1962
Persistence coordination
Persistence joins assignment truth with live capacity. A control, phone splice, invite, install, confirmation, or migration holds an activity lease tied to the host's assignment and home. Releasing that activity also releases its capacity. A stale release cannot remove capacity owned by a newer assignment. cloud/…/assignment-store.ts• L3961-4074, cloud/…/assignment-inventory-snapshot.ts• L16-28
Reserve-mode controls are a deliberate exception. They hold live state in the cell while reserve mode is effective. Database readers and sweeps skip that cell. Controls receive leases before the director records the cell as fully returned. cloud/…/assignment-store.ts• L789-867, cloud/…/host-session-registry.ts• L493-565
The edge is another persistence boundary. While a host is on the edge, the edge object holds paired-device state. Moving away exports that state and replaces the director's device rows. If the edge cannot prove its state after a prolonged outage, uncertain ordinary rows are removed instead of being restored. cloud/…/edge-relay.ts• L58-68, cloud/…/edge-relay.ts• L201-240, cloud/…/edge-relay.ts• L291-334
The edge-native director adds a user-host index for account erasure. A host assignment queues an add or account-switch remove before the assignment is stored. An alarm sends the latest wanted state to one user object and retries with capped backoff. The index stores host ids and times, not credentials. cloud/…/host-relay-director.ts• L29-49, cloud/…/host-relay-director.ts• L66-103, cloud/…/user-index.ts• L1-47, cloud/…/user-hosts.ts• L1-18
References: cloud/…/assignment-store.ts• L3961-4074 cloud/…/assignment-inventory-snapshot.ts• L16-28 cloud/…/assignment-store.ts• L789-867 cloud/…/host-session-registry.ts• L493-565 cloud/…/edge-relay.ts• L58-68 cloud/…/edge-relay.ts• L201-240 cloud/…/edge-relay.ts• L291-334 cloud/…/host-relay-director.ts• L29-103 cloud/…/user-index.ts• L1-47 cloud/…/user-hosts.ts• L1-18
Assignment cleanup
Periodic director work removes expired activity, leases, reservations, and abandoned migrations. It also repairs or evacuates dead-home state. Each cleanup class runs independently so one failure does not stop other movement or cleanup. cloud/…/assignment-cleanup-steps.ts• L1-59, cloud/…/index.ts• L79-118
References: cloud/…/assignment-cleanup-steps.ts• L1-59 cloud/…/index.ts• L79-118
Drain flow
This diagram shows the handoff from a source home to a target home while durable state guards each stage.
sequenceDiagram
participant Operator
participant Source as Source home
participant Director
participant Target as Target home
participant Host
Operator->>Source: Start paced drain or rehome
Source->>Host: Send drain with grace period
Host->>Director: Resolve or assign with reconnect hint
Director->>Director: Verify home and reserve target
Director->>Target: Publish new assignment epoch
Host->>Target: Prove identity and epoch
Target-->>Director: Register target control
Source-->>Host: Close old control after grace
Host->>Target: Reconnect phones through new control
References: cloud/…/host-session-registry.ts• L1472-1543 cloud/…/app.ts• L815-864 cloud/…/assignment-store.ts• L4177-4268 cloud/…/edge-relay-evacuation.ts• L75-103
Continuity guarantees
Continuity means that the system can restore the paired relationship and reject stale paths. It does not mean that an active data stream survives a home drain without interruption. The guarantee depends on whether the host control or a phone data leg is changing.
Control reconnect
The host proves identity with its key, control challenge, and assignment epoch. A valid resume secret can bind a new control socket to the existing session. The new socket becomes authoritative. The old socket cannot later close or change the successor session. cloud/…/host-session-registry.ts• L1621-1729, cloud/…/host-session-registry.ts• L1905-1930
If the host does not return before orphan handling ends, the home releases its in-memory session and active splices. Durable assignment remains the source for a later reconnect, subject to home liveness and lease checks. cloud/…/host-session-registry.ts• L1810-1860, cloud/…/host-session-registry.ts• L1979-2049
References: cloud/…/host-session-registry.ts• L1621-1729 cloud/…/host-session-registry.ts• L1810-1860 cloud/…/host-session-registry.ts• L1905-1930 cloud/…/host-session-registry.ts• L1979-2049
Edge control continuity
An edge home keeps one durable host control session and separate phone splice objects. A control rebind within orphan grace keeps the session generation and live splices. A fresh control after grace gets a new generation and closes old splices. This gives a process reset or short network loss a bounded recovery path without allowing two current controls. cloud/…/host-relay-base.ts• L88-101, cloud/…/host-relay-handshake.ts• L89-157
The edge checks durable assignment before proof. It rejects a wrong epoch as a wrong home and treats a slow assignment check as a temporary limit rather than a bad credential. A signed challenge binds host identity, origin, and assignment epoch before activation. cloud/…/host-relay-handshake.ts• L13-85
References: cloud/…/host-relay-base.ts• L88-101 cloud/…/host-relay-handshake.ts• L13-85 cloud/…/host-relay-handshake.ts• L89-157
Assignment lease validation
The director returns a short-lived assignment lease with the home URL, host identity, and assignment epoch. The home can classify that lease against the hello it receives. Durable assignment remains authoritative while lease checks run in shadow mode during rollout. cloud/…/app.ts• L460-481, cloud/…/assignment-lease.ts• L24-62, cloud/…/assignment-lease-shadow.ts• L44-94
References: cloud/…/app.ts• L460-481 cloud/…/assignment-lease.ts• L24-62 cloud/…/assignment-lease-shadow.ts• L44-94
Client data recovery
The home creates a pending phone connection only after it finds the active host control session. It binds the phone leg to a short-lived ticket and control generation. The host data leg must attach before its deadline. The relay persists the connection basis before it reports success. cloud/…/host-session-registry.ts• L811-1037, cloud/…/host-session-registry.ts• L1105-1183
If the host closes, the assignment changes, a drain reaches the host, or the control generation is no longer current, the pending or active data leg closes and its reservation is released. The phone can retry through the current control session. cloud/…/host-session-registry.ts• L1195-1228
References: cloud/…/host-session-registry.ts• L811-1037 cloud/…/host-session-registry.ts• L1105-1183 cloud/…/host-session-registry.ts• L1195-1228
Edge client recovery
The edge keeps host control and phone data paths separate. Each phone path has its own connection object and capacity unit, so a slow or reset phone does not reset the host control or other phones. Pending paths expire and failed paths release their reservations. cloud/…/host-relay-base.ts• L147-176, cloud/…/host-relay.ts• L1-7
When an edge host moves to an ordinary home, the old edge assignment is fenced. Phones using that path receive a wrong-home result and resolve again through the director. A lost fence reply is reconciled from the current assignment. cloud/…/edge-relay.ts• L337-346, cloud/…/edge-relay-fence.ts• L65-179
References: cloud/…/host-relay-base.ts• L147-176 cloud/…/host-relay.ts• L1-7 cloud/…/edge-relay.ts• L337-346 cloud/…/edge-relay-fence.ts• L65-179
Memory resume path
The memory phone path preserves reconnects while a reserve cell avoids database reads for live admission. A device token must match the current or grace credential and must not be revoked or expired. The memory connection basis is tied to the host control generation and a short deadline. cloud/…/host-session-registry.ts• L866-905, cloud/…/credential-store.ts• L114-154
The confirmation result remains available for a retry of the same request and basis. Audit delivery is bounded. A process restart can close live memory splices and lose a small audit backlog, but it cannot make an expired or mismatched confirmation valid. cloud/…/memory-resume-confirmations.ts• L22-89, cloud/…/resume-confirmed-audit-buffer.ts• L4-12
References: cloud/…/host-session-registry.ts• L866-905 cloud/…/credential-store.ts• L114-154 cloud/…/memory-resume-confirmations.ts• L22-89 cloud/…/resume-confirmed-audit-buffer.ts• L4-12
Stale path rejection
The cell checks assignment epoch during host proof and cell incarnation during drain and rehome calls. These checks stop a restarted cell or old host socket from claiming authority for a newer assignment. cloud/…/host-session-registry.ts• L1517-1543, cloud/…/host-session-registry.ts• L1575-1580
The edge checks assignment before proof and keeps the current generation and resume secret in durable object storage. A new assignment closes old edge controls and splices. A rebind must match the stored generation, identity, secret, and grace window. cloud/…/host-relay-handshake.ts• L29-44, cloud/…/host-relay-handshake.ts• L128-157, cloud/…/host-relay.ts• L30-40
The result is a fail-closed handoff. A move can cause a retry or short data interruption, but it does not let two homes own the same current host session. cloud/…/post-proof-close-log.ts• L10-64, cloud/…/control-close-reason-text.ts• L1-7
References: cloud/…/host-session-registry.ts• L1517-1543 cloud/…/host-session-registry.ts• L1575-1580 cloud/…/host-relay-handshake.ts• L29-44 cloud/…/host-relay-handshake.ts• L128-157 cloud/…/host-relay.ts• L30-40 cloud/…/post-proof-close-log.ts• L10-64 cloud/…/control-close-reason-text.ts• L1-7
Dependency outage behavior
A brief database or key-service fault does not need to destroy every live control. Cells can keep cached token keys during a grace period. Local readiness can keep current hosts serving while per-hello checks refuse work that needs an unavailable dependency. Directors use heartbeat and readiness evidence before placement or rehome. cloud/…/relay-server.ts• L177-183, cloud/…/app.ts• L395-407
The edge-native director treats missing assignment data as a temporary failure for assignment and as a non-match for credential lookup. Its edge configuration fails a deployment that lacks the required object-backend or authentication settings. cloud/…/director.ts• L114-160, cloud/…/env.ts• L116-155
Pre-auth limits bound phone, data, health, and resolve work per source. A limiter fault fails open so a limiter outage does not refuse live users. cloud/…/preauth.ts• L26-41
References: cloud/…/relay-server.ts• L177-183 cloud/…/app.ts• L395-407 cloud/…/director.ts• L114-160 cloud/…/env.ts• L116-155 cloud/…/preauth.ts• L26-41
Change checklist
When these files or sections are changed, remember to consider these:
- Keep placement, sticky, drain-return, reserve, reserved resolution, and edge movement lanes aligned with their retry response and
Retry-Afterbehavior. - Keep reserve mode aligned across the cell switch, dead-man contact, seat feed, booking TTL, memory phone path, and flip-back re-registration.
- Keep edge cohort mode, rollout share, region scope, allow and deny lists, leave ceiling, readiness, and evacuation behavior aligned.
- Keep edge assignment, device export, assignment epoch, and fence behavior aligned. A row change without paired-state movement can strand phones.
- Keep assignment epoch changes aligned with signed leases, host proof, target registration, migration state, reserve seats, and edge objects.
- Keep country routing, front-door origin, ingress trust, and origin proof aligned. A route that changes the dialled origin must also change the proof context.
- Keep the edge-native director's object assignment, legacy elsewhere result, frozen export result, and URL-change epoch rule aligned.
- Keep director endpoint schemas aligned with desktop assignment, phone resolve, region catalog, and invite-move clients. These clients reject unexpected response shapes.
- Keep signed admin purpose, audience, body hash, key rotation, and single-use
jtirules aligned across director pushes, export, drain, verify, erase, and index calls. - Keep user-host index updates queued before assignment changes and retried until acknowledged. Account switches must remove the old user and add the new user.
- Keep activity leases, connection bases, migration reservations, memory bases, edge device copies, and release paths tied to the same assignment epoch and control generation.
- Keep edge fence retries tied to the host's current assignment, not the assignment known when the failure occurred.
- Keep blue-green director traffic moves compatible with reserve census, edge cohort control, and placement mode.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Placement work fills its lane | New placement requests receive retryable responses | Separate sticky, placement, drain-return, and resolution budgets |
| A reconnect reaches a roll-isolated home | The host repeats a path that cannot finish | Durable isolation sends it to drain return |
| A host has a grant on an existing-only home but no live activity | The host renews a home that cannot serve it | Stranded-host detection falls through to placement |
| Edge placement starts before the edge is ready | Phones cannot resolve the assigned home | Readiness and existing-only assignment state gate entry |
| Reserve director contact is lost | Hosts remain admitted from memory without a durable lease | The cell dead-man returns to database admission |
| Reserve state is unknown | Readers or sweeps can act on stale ownership | Unknown state fails closed |
| Many drained hosts retry together | Replacement homes or the database overload | Drain pacing and drain-return retry scheduling |
| Edge export fails beyond its skip window | The host leaves without trusted device state | Remove uncertain rows, place the host, and fence the edge |
| A fence reply is lost | Phones can continue to use an old edge path | Retry against the current assignment and return wrong-home |
| Assignment epoch or cell incarnation is stale | The host or administrative action is rejected | Epoch and incarnation checks at proof and control routes |
| A target loses health or headroom during rehome | Durable state can name an unusable target | Final reservation check rolls the move back |
| A rehome reply is lost and the request is retried | Two migrations can compete | Durable attempt identity and reconciliation |
| A memory confirmation follows a mode flip | A valid retry reaches the wrong basis store | Route confirmation by basis ownership |
| An edge-native director config is malformed | Director endpoints turn off or a deploy fails closed | Validate hostname, HTTPS origins, backend, keys, and audience |
| A client reaches an edge-native director through the wrong hostname | The request uses ordinary edge routing instead of assignment routing | Match the trusted dialled hostname |
| A copied admin token is reused | A move or erasure can run twice | Body-bound signed token and durable single-use jti |
| User-host index write fails | Account erasure may miss a host | Queue before assignment and retry from the object alarm |
| Host data attach misses its deadline | The phone leg closes and its capacity is released | Short attach deadline with close cleanup |
| Database pool pressure blocks a control hello | A new control cannot enter while current controls remain useful | Control reserve, hello shedding, and local readiness |
Key files
| File | Why to read it |
|---|---|
| cloud/…/app.ts | Public assignment, reconnect, reserve, edge, drain, regional movement, and migration boundaries |
| cloud/…/assignment-store.ts | Durable assignment, epochs, home state, leases, migration, rehome, and capacity coordination |
| cloud/…/drain-return-admission.ts | Pacing for hosts returning from an isolated or drained home |
| cloud/…/reserve-assignment.ts | Reserve placement, sticky reconnect, reserve rehome, and database fallback |
| cloud/…/regional-rehome-worker.ts | Polling, source dispatch, and durable outcome recovery for idle regional rehome |
| cloud/…/edge-relay.ts | Edge entry, phone resolution, device export, placement fallback, and fencing |
| cloud/…/edge-relay-evacuation.ts | Cohort-leave sweep, drain pacing, cooldown, and edge-down evacuation |
| cloud/…/edge-relay-fence.ts | Current-assignment reconciliation for edge fences |
| cloud/…/host-session-registry.ts | Host proof, control rebind, phone attach, drain state, rehome checks, and cleanup |
| cloud/…/relay-server.ts | Cell admission, connection caps, reserve wiring, and dead-man behavior |
| cloud/…/index.ts | Edge routing, director activation, signed admin calls, and WebSocket forwarding |
| cloud/…/director.ts | Edge-native assignment, resume, region catalog, and invite-move contract |
| cloud/…/director-config.ts | Dark director activation, country routing, probe catalog, and location hints |
| cloud/…/director-assign.ts | Edge-native assignment epochs, account changes, frozen moves, and legacy placement boundaries |
| cloud/…/host-relay-director.ts | Object-backed assignment and credential answers plus user-index queueing |
| cloud/…/admin.ts | Signed director and erasure-job admin contract, key rotation, body binding, and replay rules |
| cloud/…/host-relay.ts | Edge export, drain, assignment push, erasure, and credential verification |
| cloud/…/host-relay-base.ts | Edge session generations, orphan grace, splice capacity, and alarm scheduling |
| cloud/…/host-relay-handshake.ts | Edge assignment proof, control rebind, generation, and resume-secret rules |
| cloud/…/user-hosts.ts | Per-user host index used to find edge-held data for account erasure |
| cloud/…/user-index.ts | Durable pending index updates and capped retry behavior |
| cloud/…/preauth.ts | Source-based admission limits before phone and data authentication |
| cloud/…/env.ts | Backend, director, authentication, liveness, and ingress configuration boundaries |
| cloud/…/director-contract.test.ts | Compatibility between edge-native director responses and shipped desktop and phone clients |
| cloud/…/director-assign.test.ts | Edge-native epoch and legacy-placement rules |
| cloud/…/director-dark.test.ts | Proof that the optional director does not alter normal edge routing when dark |
| cloud/…/user-index-write.test.ts | Queued account-index updates and retry behavior |
| cloud/…/roundtrip.ts | End-to-end movement between a cell and edge with paired phones |
| cloud/…/deploy-relay-blue-green.mjs | Deployment gates for movement and continuity-safe traffic changes |
| docs/push-notification-delivery.md | Client wake-up behavior after a relay path is unavailable |
| docs/cloud-operational-deployment-controls.md | Operator controls for admission, draining, rollout, and movement |