orca/docs/relay-region-correction/RELAY-REGION-CORRECTION-API.md

Idle regional correction contracts

Updated 2026-09-11. The idle-cutover plan is authoritative. This replaces the former retention/restoration protocol.

Desktop measurement and capability

The optional assignment regionCorrection namespace supports issue-window and report. The server issues a generation, fixed expiry, assignment epoch, incumbent region and policy version1. A report supplies measurements for both regions or an inconclusive reason. The first accepted report remains immutable; stale or changed assignment evidence cannot authorize a move. Legacy placement hints remain separate.

Desktop advertises idle-regional-rehome-v1 in its control capability header. There is no new mobile message, retained-control lease, or restoration notification. The cell persists the exact activity, generation, assignment and incarnation with idle_regional_rehome. The obsolete finish_existing database column is always written0 for schema compatibility and is not an eligibility signal.

Director to source cell

POST /v1/admin/host-idle-rehome requires the configured director identity and matching source cell/incarnation. The strict request contains:

• v:1, stable UUID attemptId, userId, relayHostId;
• sourceCellId, sourceCellIncarnation, sourceAssignmentEpoch, sourceGeneration;
• targetCellId, authenticated cohortPercent, and fresh directorSafety.

The strict response is {v:1,outcome} with busy, committed, deferred, or stale. A lost HTTP reply is ambiguous and does not consume a dispatch-failure budget. Repeat delivery retains the same operation identity. Cell status advertises regional protocol3; new selection requires both cells at protocol3 or newer.

Store and source ownership

selectIdleRegionalRehomeCandidates is read-only. It checks fresh evidence, capability, policy, cooldown, telemetry and target capacity; bounded rotating pages allow progress past busy hosts. Selection does not prove physical idleness.

HostSessionRegistry.idleRehome accounts for accepts, attaches, control commands, and activation before their first await. Only an idle source installs its admission gate. New arrivals receive normal retryable routing failure. Conflicting reuse of an operation ID cannot share another authority tuple's result.

commitIdleRegionalRehome rechecks the exact request under existing locks, including policy, cohort, capacity, global rate and concurrency. It atomically reserves the target, advances assignment and records the attempt/source generation. It does not choose a different host or destination. Completion is recorded at the source; ordinary migration refresh, completion and expiry recovery remain responsible for the target-registration lifecycle.

reconcileIdleRegionalRehome locks the assignment before reading the operation. It distinguishes committed, not-committed with unchanged live source authority, and stale authority. Missing data after an unlocked read is never rollback proof. A database error leaves admissions fenced while reconciliation retries. Successful cutover closes/releases the empty source control; the desktop resolves its normal assignment and reconnects. Definite rollback reopens only the same source authority.

Outcome reporting aggregates actual attempts and migrations by cell/state, without host identities or a retained-source table. A completed idle move does not authorize closing future clients attached to the target.