mirror of
https://github.com/stablyai/orca.git
synced 2026-10-01 08:01:56 +00:00
62 lines
3.4 KiB
Markdown
62 lines
3.4 KiB
Markdown
# Idle regional correction contracts
|
|
|
|
Updated 2026-09-11. The [idle-cutover plan](RELAY-REGION-CORRECTION-IDLE-CUTOVER-PLAN.md)
|
|
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.
|