@jsm-mit/tigi-sharded-package 0.0.0-stage → 0.2.0

package/declarations/coordinator/coordinator.did

@@ -0,0 +1,661 @@
+// WHERE the accounts of a principal are (rule `sharding.md`, "A WHERE answer is a place"):
+// a canister to ask, or a referral to another coordinator to ask the same question (after
+// the core budded into a peer group). The client follows at most 2 referrals.
+type AccountsPlace = variant {
+  // Ask this canister `isUser` (today: the core of the group).
+  canister : principal;
+  // Ask this coordinator `accountsCanisterFor` again.
+  coordinator : principal;
+};
+type AssignPrefixArgs = record { prefix : text; worker : principal };
+type CanisterArgs = record { canister : principal };
+// The chat group's admin methods this coordinator calls for its core (rule `sharding.md`,
+// "Between two groups": the coordinator calls for its group). A fixed list: the core
+// composes the arguments and keeps the logic, the coordinator only forwards. A new
+// method of the chat group is a new case here, never a free method name.
+type ChatAdminMethod = variant { updateRoom; createRoom; deleteRoom };
+type CommitWasmArgs = record {
+  // Of the whole module. The coordinator refuses a module that does not match.
+  sha256 : blob;
+  chunks : nat32;
+};
+// Stored as ONE Candid record. A new field is `Option<…>` with `#[serde(default)]`, or the
+// records stored before the change stop decoding. Never remove or retype a field.
+type Config = record {
+  // The most workers the group may have (KO-7). None = `DEFAULT_MAX_WORKERS`.
+  maxWorkers : opt nat64;
+  // The core wasm, likewise.
+  coreWasm : opt WasmInfo;
+  // The version of the prefix map: one more at every change. A worker keeps the newest
+  // map it got (`setAreaMap`).
+  mapVersion : nat64;
+  // What the coordinator keeps for itself (`own_reserve_cycles`).
+  ownReserve : opt nat;
+  // The core the coordinator owns.
+  core : opt CoreRecord;
+  // Query instructions per minute (from query_stats) at which a worker is at level 1, 2,
+  // 3. The query load only ALARMS — a split for it is a superadmin's order (KO-8). None =
+  // `DEFAULT_QUERY_THRESHOLDS`.
+  queryThresholds : opt LevelThresholds;
+  // The core of the group (`core/`). A worker is installed with it.
+  home : opt principal;
+  mode : Mode;
+  // What every worker of the group is configured with: the superadmin sets it once, the
+  // coordinator gives it to the workers that exist and to every worker it creates.
+  // None = the workers keep the defaults they were built with.
+  workerConfig : opt WorkerConfigArgs;
+  // The worker wasm the superadmin uploaded, once committed.
+  wasm : opt WasmInfo;
+  // Somebody who asked for the superadmin role (LIVE; one request a day for the group).
+  roleRequest : opt RoleRequest;
+  // The UTC day of the last request: a second request the same day is refused in inspect.
+  lastRequestDay : nat64;
+  // What a new worker starts with, and what a worker or the core gets when it reports a
+  // low balance. A worker asks below half of it.
+  cyclesPerWorker : nat;
+  // false (STAGE, local): the coordinator never creates a worker or splits by itself,
+  // whatever the load; the levels are only shown (KO-7). true (prod): it does.
+  spread : bool;
+  nextEventId : nat64;
+  // The ONE superadmin of a LIVE group: a person, who hands the role over on a request.
+  superadmin : opt principal;
+  // The identities of the deploy and of the machines that run seeds and tests: every
+  // right while DEPLOYED and, outside prod, after the claim too; never the handover.
+  deployAdmins : vec principal;
+  lastCreatedAtNs : nat64;
+  // DEPLOYED until somebody claims the superadmin role in the front; LIVE after.
+  groupState : GroupState;
+};
+type CoordinatorError = variant {
+  // The coordinator cannot pay for what was asked.
+  NoCycles : text;
+  // Another canister (the management canister, a worker, the core) refused or did not
+  // answer.
+  RemoteCanisterError : text;
+  NotFound;
+  NotAuthorized : text;
+  InvalidData : text;
+  AlreadyExists;
+};
+// What the core says of itself right now, asked in a composite query — its admins and
+// its wiring — or why it could not be asked.
+type CoreLive = record {
+  wiring : opt CoreWiring;
+  error : opt text;
+  canister : principal;
+  admins : opt vec principal;
+};
+type CoreLoggingArgs = record { enabled : bool };
+// The core of the group, as the coordinator owns it (KO-3, variant A): created by the
+// coordinator, installed and upgraded by it, administered from its front. `home` in the
+// config is this canister's id.
+type CoreRecord = record {
+  moduleSha256 : opt blob;
+  createdAtNs : nat64;
+  // The last report of an outbox that cannot empty itself (`reportOutboxStuck`).
+  outboxStuck : opt OutboxStuck;
+  // What `refreshCore` read last: the balance and the hash of the module.
+  cyclesReported : opt nat;
+  canister : principal;
+  installedAtNs : nat64;
+  // The core asked for cycles and did not get them yet (`reportCoreLowCycles`).
+  lowCycles : opt bool;
+  // The core wasm is installed. False right after a creation that failed half-way,
+  // or for a core handed over at the install until it is installed again.
+  ready : bool;
+};
+// Mirror of the Tigi core's `AT.Wiring` (core/src/ActorTypes.mo).
+type CoreWiring = record {
+  mode : Mode;
+  knownWorkers : vec principal;
+  coordinator : opt principal;
+};
+type DeleteWorkerArgs = record {
+  // Delete a worker WITH its open requests and rides, or with prefixes. Never in prod.
+  force : bool;
+  canister : principal;
+};
+// What `deleteWorker` did.
+type DeletedWorker = record {
+  // What came back to the coordinator with the deletion.
+  cyclesReturned : nat;
+  canister : principal;
+  // Prefixes the map named it for, taken off the map (none without `force`).
+  prefixes : vec text;
+};
+// The dependents of the coordinator: what a reinstall must be handed.
+type Dependents = record { core : opt principal; workers : vec principal };
+// A drain: every prefix of `canister` goes to `target`.
+type DrainWorkerArgs = record { target : principal; canister : principal };
+type Event = record {
+  id : nat64;
+  atNs : nat64;
+  // "alarm" (a worker at level 3, a stuck outbox), "error" (a creation or a top-up that
+  // failed), "warn", "info".
+  kind : text;
+  "text" : text;
+};
+// The arguments of the method are the core's, Candid-encoded (`to_candid` in Motoko) —
+// the coordinator does not read them and keeps no copy of the chat group's types.
+type ForwardChatAdminArgs = record {
+  method : ChatAdminMethod;
+  // The one argument of the method, Candid-encoded.
+  args : blob;
+  // The chat group's COORDINATOR (the core's chat config) — the group's address. The
+  // coordinator asks it where the chat core is.
+  chatCoordinator : principal;
+};
+type GeohashesArgs = record { geohashes : vec text };
+// DEPLOYED: fresh from the deploy, the deploy admins rule, no worker exists or is created.
+// LIVE: a person claimed the superadmin role; the group works.
+type GroupState = variant { deployed; live };
+// A Candid-encodable representation of an HTTP request. This struct is used by
+// the `http_request` method of the HTTP Gateway Protocol's Candid interface.
+// 
+// # Examples
+// 
+// ```
+// use ic_http_certification::{HttpRequest, Method};
+// 
+// let request = HttpRequest::builder()
+// .with_method(Method::GET)
+// .with_url("/")
+// .with_headers(vec![("X-Custom-Foo".into(), "Bar".into())])
+// .with_body(&[1, 2, 3])
+// .with_certificate_version(2)
+// .build();
+// 
+// assert_eq!(request.method(), Method::GET);
+// assert_eq!(request.url(), "/");
+// assert_eq!(request.headers(), &[("X-Custom-Foo".into(), "Bar".into())]);
+// assert_eq!(request.body(), &[1, 2, 3]);
+// assert_eq!(request.certificate_version(), Some(2));
+// ```
+// 
+// # Helpers
+// 
+// There are also a number of convenience methods for quickly creating an [HttpRequest] with
+// commonly used HTTP methods:
+// 
+// - [GET](HttpRequest::get)
+// - [POST](HttpRequest::post)
+// - [PUT](HttpRequest::put)
+// - [PATCH](HttpRequest::patch)
+// - [DELETE](HttpRequest::delete)
+// 
+// ```
+// use ic_http_certification::HttpRequest;
+// 
+// let request = HttpRequest::get("/").build();
+// 
+// assert_eq!(request.method(), "GET");
+// assert_eq!(request.url(), "/");
+// ```
+type HttpRequest = record {
+  // HTTP request URL.
+  url : text;
+  // HTTP request method.
+  method : text;
+  // HTTP request body as an array of bytes.
+  body : blob;
+  // HTTP request headers.
+  headers : vec record { text; text };
+  // The max response verification version to use in the response's
+  // certificate.
+  certificate_version : opt nat16;
+};
+// A Candid-encodable representation of an HTTP response. This struct is used
+// by the `http_request` method of the HTTP Gateway Protocol's Candid interface.
+// 
+// # Examples
+// 
+// ```
+// use ic_http_certification::{HttpResponse, StatusCode};
+// 
+// let response = HttpResponse::builder()
+// .with_status_code(StatusCode::OK)
+// .with_headers(vec![("Content-Type".into(), "text/plain".into())])
+// .with_body(b"Hello, World!")
+// .with_upgrade(false)
+// .build();
+// 
+// assert_eq!(response.status_code(), StatusCode::OK);
+// assert_eq!(response.headers(), &[("Content-Type".into(), "text/plain".into())]);
+// assert_eq!(response.body(), b"Hello, World!");
+// assert_eq!(response.upgrade(), Some(false));
+// ```
+// 
+// # Helpers
+// 
+// There are also a number of convenience methods for quickly creating an [HttpResponse] with
+// commonly used HTTP status codes:
+// 
+// - [OK](HttpResponse::ok)
+// - [CREATED](HttpResponse::created)
+// - [NO_CONTENT](HttpResponse::no_content)
+// - [MOVED_PERMANENTLY](HttpResponse::moved_permanently)
+// - [TEMPORARY_REDIRECT](HttpResponse::temporary_redirect)
+// - [BAD_REQUEST](HttpResponse::bad_request)
+// - [UNAUTHORIZED](HttpResponse::unauthorized)
+// - [FORBIDDEN](HttpResponse::forbidden)
+// - [NOT_FOUND](HttpResponse::not_found)
+// - [METHOD_NOT_ALLOWED](HttpResponse::method_not_allowed)
+// - [TOO_MANY_REQUESTS](HttpResponse::too_many_requests)
+// - [INTERNAL_SERVER_ERROR](HttpResponse::internal_server_error)
+// 
+// ```
+// use ic_http_certification::{HttpResponse, StatusCode};
+// 
+// let response = HttpResponse::ok(b"Hello, World!", vec![("Content-Type".into(), "text/plain".into())]).build();
+// 
+// assert_eq!(response.status_code(), StatusCode::OK);
+// assert_eq!(response.headers(), &[("Content-Type".into(), "text/plain".into())]);
+// assert_eq!(response.body(), b"Hello, World!");
+// ```
+type HttpResponse = record {
+  // HTTP response body as an array of bytes.
+  body : blob;
+  // HTTP response headers.
+  headers : vec record { text; text };
+  // Whether the corresponding HTTP request should be upgraded to an update
+  // call.
+  upgrade : opt bool;
+  // HTTP response status code.
+  status_code : nat16;
+};
+// The arguments of the install: the mode of the group, the deploy admins and the
+// dependents handed over. The deploy admins (the dfx identity that deploys, the
+// identities of the machines that run seeds and tests) have every right while the group
+// is DEPLOYED; after the claim they keep them outside prod and lose them in prod (KO-14).
+// The arguments of an upgrade are ignored: the stable config stays.
+type InitArgs = record {
+  // The dependents of the coordinator that was on this canister before — handed over
+  // at a reinstall, outside prod only (the install traps otherwise): the core and the
+  // workers it created. They are installed again (`resetGroup`) — the same ids, no
+  // create fee.
+  core : opt principal;
+  mode : Mode;
+  workers : vec principal;
+  deployAdmins : vec principal;
+};
+type InjectTestLoadArgs = record { load : TestLoadArgs; canister : principal };
+type LevelThresholds = record { level1 : nat; level2 : nat; level3 : nat };
+// What a worker measured in a minute that crossed a threshold (the worker's
+// `T.LoadReport`). Motoko's `Nat` is Candid `nat`, which is `u128` here.
+type LoadReport = record {
+  updateCalls : nat;
+  minute : nat;
+  instructions : nat;
+  level : nat;
+  maxMessagesPerRound : nat;
+};
+type LoadThresholds = record {
+  messagesPerRound : LevelThresholds;
+  instructionsPerMinute : LevelThresholds;
+};
+// Where the group runs. Given at the install of the coordinator and never changed; every
+// canister it creates is installed with it (KO-13). What a test mode allows (test load
+// injected into a worker) is never allowed on stage or in prod.
+type Mode = variant {
+  // The local replica.
+  localTest;
+  prod;
+  // DEV and the test canisters on mainnet.
+  test;
+  stage;
+};
+// An outbox (of a worker or of the core) that has not emptied itself for a long time:
+// its calls keep failing. Reported every hour while it lasts; it counts as stuck for
+// `OUTBOX_STUCK_TTL_NS` after the last report, so a recovery needs no report of its own.
+type OutboxStuck = record {
+  reportedAtNs : nat64;
+  // Entries waiting at the report.
+  pending : nat64;
+  // Since when the calls fail (the first failed flush).
+  sinceNs : nat64;
+  lastError : opt text;
+};
+// The load a worker counts in one geohash cell (the worker's `getPrefixCounts`): reports,
+// requests and quotes of the last minutes (WO-13).
+type PrefixCount = record { load : nat; prefix : text };
+// One entry of the prefix map: a geohash that starts with `prefix` (and with no longer
+// prefix of the map) is served by `worker`. The empty prefix is the rest of the world.
+type PrefixEntry = record { prefix : text; worker : principal };
+type PrincipalArgs = record { "principal" : principal };
+// The query totals of a worker at one reading, and the rate since the reading before.
+type QueryLoad = record {
+  atNs : nat64;
+  instructionsTotal : nat;
+  instructionsPerMinute : nat;
+  callsTotal : nat;
+  // Since the reading before; 0 at the first one.
+  callsPerMinute : nat;
+};
+type ReportFullArgs = record {
+  heapBytes : nat;
+  // false = the live data fell below the threshold again.
+  full : bool;
+};
+type ReportLowCyclesArgs = record { cycles : nat };
+type ReportOutboxStuckArgs = record {
+  pending : nat64;
+  sinceNs : nat64;
+  lastError : opt text;
+};
+type Result = variant { Ok : vec principal; Err : CoordinatorError };
+type Result_1 = variant { Ok : Roles; Err : CoordinatorError };
+type Result_10 = variant { Ok : vec WorkerLive; Err : CoordinatorError };
+type Result_11 = variant { Ok : bool; Err : CoordinatorError };
+type Result_12 = variant { Ok : vec WorkerRecord; Err : CoordinatorError };
+type Result_13 = variant { Ok : CoreRecord; Err : CoordinatorError };
+type Result_14 = variant { Ok : WorkerStatus; Err : CoordinatorError };
+type Result_15 = variant { Ok : Dependents; Err : CoordinatorError };
+type Result_16 = variant { Ok : Config; Err : CoordinatorError };
+type Result_17 = variant { Ok : SetWorkerConfigResult; Err : CoordinatorError };
+type Result_18 = variant { Ok : WorkerView; Err : CoordinatorError };
+type Result_19 = variant { Ok : SplitResult; Err : CoordinatorError };
+type Result_2 = variant { Ok : vec PrefixEntry; Err : CoordinatorError };
+type Result_20 = variant { Ok : nat; Err : CoordinatorError };
+type Result_21 = variant { Ok : nat64; Err : CoordinatorError };
+type Result_3 = variant { Ok : WasmInfo; Err : CoordinatorError };
+type Result_4 = variant { Ok : principal; Err : CoordinatorError };
+type Result_5 = variant { Ok : DeletedWorker; Err : CoordinatorError };
+type Result_6 = variant { Ok : vec text; Err : CoordinatorError };
+type Result_7 = variant { Ok : blob; Err : CoordinatorError };
+type Result_8 = variant { Ok : CoreLive; Err : CoordinatorError };
+type Result_9 = variant { Ok : Status; Err : CoordinatorError };
+// Somebody asked for the superadmin role.
+type RoleRequest = record { "principal" : principal; atNs : nat64 };
+// Who rules the group — for the front.
+type Roles = record {
+  // Whether the deploy admins still have their rights (DEPLOYED, or LIVE outside prod).
+  deployAdminsActive : bool;
+  roleRequest : opt RoleRequest;
+  // Whether a request may be made today (one a day for the group).
+  requestOpenToday : bool;
+  superadmin : opt principal;
+  deployAdmins : vec principal;
+  groupState : GroupState;
+};
+// What a superadmin may change. Only the fields given are changed.
+type SetConfigArgs = record {
+  maxWorkers : opt nat64;
+  ownReserve : opt nat;
+  queryThresholds : opt LevelThresholds;
+  cyclesPerWorker : opt nat;
+  spread : opt bool;
+};
+type SetWorkerConfigResult = record {
+  // What is stored now: what every worker has, and what a new worker gets.
+  stored : WorkerConfigArgs;
+  workers : vec WorkerConfigOutcome;
+};
+type SetWorkerOpenArgs = record { open : bool; canister : principal };
+type SplitResult = record { worker : principal; prefixes : vec text };
+type Status = record {
+  // The core's outbox reported being stuck within `OUTBOX_STUCK_TTL_NS`.
+  coreOutboxStuckNow : bool;
+  cycles : nat;
+  // Newest first.
+  events : vec Event;
+  workers : vec WorkerView;
+  config : Config;
+  creationInFlight : bool;
+  // The whole prefix map.
+  prefixes : vec PrefixEntry;
+};
+// A load a test puts on a worker (test modes only; the worker's `T.TestLoadArgs`): the
+// counters of these cells grow, and the worker reports `reportLevel` to the coordinator as
+// a real minute would.
+type TestLoadArgs = record { reportLevel : opt nat; cells : vec PrefixCount };
+type WasmChunkArgs = record { bytes : blob; index : nat32 };
+type WasmInfo = record {
+  uploadedAtNs : nat64;
+  sha256 : blob;
+  size : nat64;
+  chunks : nat32;
+};
+type WorkerConfig = record {
+  fullAtHeapBytes : nat;
+  load : LoadThresholds;
+  lowCyclesBelow : nat;
+};
+// What a superadmin sets for the workers of the group. Only the fields given are changed.
+// The memory threshold and the cycles threshold are not a superadmin's: the coordinator
+// computes them.
+type WorkerConfigArgs = record {
+  load : opt LoadThresholds;
+  loggingEnabled : opt bool;
+};
+type WorkerConfigOutcome = record {
+  // None = the worker took the config.
+  error : opt text;
+  canister : principal;
+};
+// What a worker says of itself right now, asked in one composite query over the group —
+// or why it could not be asked (no code, another subnet, unreachable).
+type WorkerLive = record {
+  status : opt WorkerStatus;
+  error : opt text;
+  canister : principal;
+};
+type WorkerRecord = record {
+  // The queries the worker answered, read from `canister_status` (KO-8).
+  queryLoad : opt QueryLoad;
+  heapBytes : opt nat;
+  // The worker's live data is over its threshold: it keeps its prefixes, gets no new one.
+  full : bool;
+  createdAtNs : nat64;
+  // The last report of an outbox that cannot empty itself (`reportOutboxStuck`).
+  outboxStuck : opt OutboxStuck;
+  cyclesReported : opt nat;
+  // The level of the last report, and when it came. It counts for `LEVEL_TTL_NS`.
+  level : nat8;
+  levelAtNs : nat64;
+  canister : principal;
+  // The version of the prefix map the worker confirmed (`setAreaMap`). Behind
+  // `Config.map_version` = the worker gets the map again.
+  areaVersion : opt nat64;
+  // false = a superadmin closed the worker (`drainWorker`, `setWorkerOpen`): it serves
+  // the prefixes it holds and is the target of no split. Stored: an upgrade keeps the
+  // superadmin's will (KO-9).
+  acceptsNewPrefixes : bool;
+  // The level of the last query load reading. Shown and alarmed only — it splits nothing.
+  queryLevel : opt nat8;
+  // The worker asked for cycles and did not get them yet.
+  lowCycles : bool;
+  lastLoad : opt LoadReport;
+  lastReportAtNs : nat64;
+  // false = the canister exists but the code is not installed (a creation that failed
+  // half-way). Such a worker gets no prefix and is not named to anybody.
+  ready : bool;
+};
+// The worker's `T.WorkerStatus`.
+type WorkerStatus = record {
+  heapBytes : nat;
+  lastMinute : opt LoadReport;
+  full : bool;
+  home : principal;
+  activeRides : nat;
+  mode : Mode;
+  cycles : nat;
+  // Driver canisters present (WO-4); they do not move — size zero (WO-14).
+  drivers : nat;
+  // The version of the prefix map the worker holds.
+  areaVersion : nat64;
+  config : WorkerConfig;
+  // Open rider requests and active rides: what a delete would lose.
+  openRequests : nat;
+  coordinator : principal;
+};
+// A worker as the superadmin front shows it: the record, and what counts NOW.
+type WorkerView = record {
+  // Its outbox reported being stuck within `OUTBOX_STUCK_TTL_NS`.
+  outboxStuckNow : bool;
+  levelNow : nat8;
+  // The worker may take prefixes of a split.
+  open : bool;
+  // A split or a drain runs for it right now.
+  draining : bool;
+  // The prefixes of the map that name it.
+  prefixes : vec text;
+  "record" : WorkerRecord;
+};
+service : (InitArgs) -> {
+  // KO-16: WHERE the accounts of a principal are — a place: `canister` (ask it `isUser`) or
+  // `coordinator` (a referral: ask that coordinator again). Asked by the chat core for a
+  // customer of the project whose accounts field names this coordinator. Today `canister` =
+  // the core of the group for every principal (null = no core yet). Never the answer itself.
+  accountsCanisterFor : (principal) -> (opt AccountsPlace) query;
+  // An admin of the core, added by a superadmin through the coordinator.
+  addCoreAdmin : (PrincipalArgs) -> (Result);
+  // A deploy admin more — a machine that runs seeds or tests. Not in a live prod group.
+  addDeployAdmin : (PrincipalArgs) -> (Result_1);
+  // A prefix to a worker, by hand: new reports and requests of the area go there from now
+  // on.
+  assignPrefix : (AssignPrefixArgs) -> (Result_2);
+  // DEPLOYED → LIVE: the caller becomes THE superadmin. In prod the deploy admins lose
+  // their rights here, in the coordinator and in the core.
+  claimSuperadmin : () -> (Result_1);
+  commitCoreWasm : (CommitWasmArgs) -> (Result_3);
+  // The uploaded chunks become THE worker wasm — when they are all there and their hash is
+  // the one the uploader names.
+  commitWorkerWasm : (CommitWasmArgs) -> (Result_3);
+  // Creates the core of the group: a canister this coordinator alone controls, with the core
+  // wasm installed. Once per group.
+  createCore : () -> (Result_4);
+  // A worker by hand: the first one of a group, or one more. Neither `spread` nor the load
+  // of the others is asked; `maxWorkers` and the cycles are.
+  createWorker : () -> (Result_4);
+  // KO-9: deletes a worker: its cycles come back first, then it is stopped, deleted and
+  // taken off the list. A worker that holds prefixes, open requests or rides goes with
+  // `force` only, and never in prod (`logic::may_delete`).
+  deleteWorker : (DeleteWorkerArgs) -> (Result_5);
+  // The superadmin says no to the one who asked.
+  dismissRoleRequest : () -> (Result_1);
+  // KO-9: every prefix of the worker goes to `target`, and the worker is closed. The
+  // emptied worker stays until a superadmin deletes it or opens it again.
+  drainWorker : (DrainWorkerArgs) -> (Result_6);
+  // KO-16: the core only — one admin call on the chat group, made by this coordinator, the
+  // admin of the project there. The core composes the argument (`to_candid`) and reads the
+  // answer (`from_candid`); the coordinator checks the method against its fixed list, finds
+  // the chat core through the chat coordinator, and answers with the chat core's reply as it
+  // came (`Ok`), whatever it says. `Err` = the chat group could not be reached: a rejected
+  // call forgets the chat core, asks the chat coordinator again and tries once more.
+  forwardChatAdmin : (ForwardChatAdminArgs) -> (Result_7);
+  // What the core says of itself right now — one composite query for the front.
+  getCoreStatus : () -> (Result_8) composite_query;
+  // The core of the group.
+  getHomeCanister : () -> (opt principal) query;
+  // The whole prefix map: which worker serves which area.
+  getPrefixMap : () -> (vec PrefixEntry) query;
+  // Who rules — for everybody: the front shows a signed-in stranger whether to claim or to
+  // ask. The principal who asked is for the superadmin only.
+  getRoles : () -> (Roles) query;
+  // Everything the superadmin front shows.
+  getStatus : () -> (Result_9) query;
+  // What every worker says of itself right now — one composite query, the workers' own
+  // `getStatus` queries inside it. A worker that cannot be asked carries the reason instead.
+  getWorkersStatus : () -> (Result_10) composite_query;
+  // The superadmin hands the role over to the one who asked.
+  handOverSuperadmin : () -> (Result_1);
+  // Whether this coordinator still has dependents — the core it owns, or workers, code or
+  // not. A slot is reinstalled only when this answers false, or when the dependents are
+  // handed over (rule "hasDependents").
+  hasDependents : () -> (bool) query;
+  // The superadmin front, for everybody: the page and its files. It shows nothing by
+  // itself — what it shows it asks the methods above for, as the person who signed in.
+  http_request : (HttpRequest) -> (HttpResponse) query;
+  // A test mode only (`prod` and `stage` refuse, and so does the worker): a load put on
+  // ONE worker — its per-prefix counters grow, and it reports the level given to the
+  // coordinator as a real minute would. What a local script uses to force a split.
+  injectWorkerTestLoad : (InjectTestLoadArgs) -> (Result_11);
+  // Installs the core wasm on the core: a core without code, or — outside prod — a core
+  // that has code (handed over at the install, or a reset). A fresh state, the same canister.
+  installCore : () -> (Result_3);
+  // Installs the worker wasm on a canister of this group that has no code — a creation that
+  // failed after the canister was made. Outside prod a reinstall: the same canister, fresh
+  // state, no create fee.
+  installWorker : (CanisterArgs) -> (Result_4);
+  // "Is this canister one of your workers?" — the core asks once per unknown caller.
+  isWorker : (CanisterArgs) -> (bool) query;
+  // The dependents by name — for the handover.
+  listDependents : () -> (Dependents) query;
+  // Every worker that has its code — for reads over the whole network.
+  listWorkers : () -> (vec principal) query;
+  // The workers of many geohashes at once, in the order asked — a rider's request that
+  // reaches the areas of several workers (WO-12).
+  locateGeohashes : (GeohashesArgs) -> (vec opt principal) query;
+  // A superadmin reads the query load of every installed worker now.
+  readQueryLoads : () -> (Result_12);
+  // What the management canister says of the core: its balance and its module.
+  refreshCore : () -> (Result_13);
+  // What a worker says of itself now. The coordinator keeps the memory and the cycles.
+  refreshWorker : (CanisterArgs) -> (Result_14);
+  removeCoreAdmin : (PrincipalArgs) -> (Result);
+  removeDeployAdmin : (PrincipalArgs) -> (Result_1);
+  // KO-10, C-11: the core's balance is below `lowCyclesBelow`: it gets `cyclesPerWorker`,
+  // like a worker. One top-up in flight; a failed one is tried again at the next report.
+  reportCoreLowCycles : (ReportLowCyclesArgs) -> ();
+  // WO-15: the live data of the calling worker crossed its threshold (`full`), or fell below
+  // it again. A full worker keeps its prefixes, takes no new one, and half of them go to a
+  // fresh worker.
+  reportFull : (ReportFullArgs) -> ();
+  // KO-4, KO-5: a minute of the calling worker that crossed a threshold. The level counts
+  // for `LEVEL_TTL_NS`. Level 2: about half of its prefixes go to a low worker (a new one
+  // when there is none); level 3: an alarm and a split to a fresh worker. With `spread` off
+  // the levels are only shown (KO-7).
+  reportLoad : (LoadReport) -> ();
+  // KO-10: the balance of the calling worker is below its threshold. The coordinator tops it
+  // up when it can pay; when it cannot, the superadmin sees why. One top-up in flight.
+  reportLowCycles : (ReportLowCyclesArgs) -> ();
+  // A worker or the core: its outbox has not emptied itself for an hour. Stored on its
+  // record (the front shows it while `OUTBOX_STUCK_TTL_NS` lasts) and kept as an alarm.
+  reportOutboxStuck : (ReportOutboxStuckArgs) -> ();
+  // LIVE: a signed-in person who is not the superadmin asks for the role. One request a
+  // day for the whole group — the inspect refuses the rest of the day.
+  requestSuperadmin : () -> (Result_1);
+  // KO-15: a fresh group on the same canisters (outside prod): the core and every worker are
+  // installed again from scratch — the same ids, the same cycles, no create fee — and the
+  // map starts again: the first worker holds the world. One canister at a time; refused
+  // while a split, a drain or an upgrade runs.
+  resetGroup : () -> (Result_15);
+  // Changes what a superadmin may: `spread`, the cycles of a worker, the own reserve,
+  // `maxWorkers`, the query thresholds. Only the fields given are changed.
+  setConfig : (SetConfigArgs) -> (Result_16);
+  setCoreLoggingEnabled : (CoreLoggingArgs) -> (Result_11);
+  // The config of the workers of the group: the load thresholds, logging. Only the fields
+  // given are changed. The result is stored, given to every worker that has its code, and
+  // to every worker created later.
+  setWorkerConfig : (WorkerConfigArgs) -> (Result_17);
+  // Opens a worker to the prefixes of a split again, or closes it without giving anything
+  // away.
+  setWorkerOpen : (SetWorkerOpenArgs) -> (Result_18);
+  // A superadmin splits a worker now, whatever its load and `spread` (KO-17): a fresh worker
+  // takes about half of its prefixes. Answers with the new worker and the prefixes it got.
+  splitWorker : (CanisterArgs) -> (Result_19);
+  // A worker of the group sends its cycles here before it is deleted (`giveBackCycles`).
+  // The workers only: somebody else's cycles are refused (they go back to the sender).
+  takeCycles : () -> (nat);
+  // Cycles for the core, by hand: `cyclesPerWorker`, like a worker's top-up.
+  topUpCore : () -> (Result_20);
+  // Cycles for a worker, by hand.
+  topUpWorker : (CanisterArgs) -> (Result_20);
+  // KO-11: a new build of the core: stop → upgrade → start; its state stays (C-12).
+  upgradeCore : () -> (Result_3);
+  // KO-11: a new worker build on a worker that runs: stop → upgrade → start. Its state
+  // stays (a Motoko build with enhanced orthogonal persistence keeps its memory). Not while
+  // a split or a drain holds the worker.
+  upgradeWorker : (CanisterArgs) -> (Result_3);
+  // The core wasm, in chunks like the worker's.
+  uploadCoreWasmChunk : (WasmChunkArgs) -> (Result_21);
+  // One chunk of a NEW worker wasm. The first chunk (index 0) drops what was uploaded
+  // before; the module counts only after `commitWorkerWasm`.
+  uploadWorkerWasmChunk : (WasmChunkArgs) -> (Result_21);
+  // KO-1, KO-2: the worker of the area a geohash lies in — the longest prefix of the map
+  // wins. None = no installed worker serves the area (no worker yet, or its worker is being
+  // installed). Uncertified: the package checks the answer against `listWorkers`, and a
+  // worker refuses a geohash outside its area (`notMyArea`). The protocol's form: a bare
+  // geohash (`protocol/tigi-driver.did`).
+  workerFor : (text) -> (opt principal) query;
+}