Routing

stado route operates the fleet’s service routes from the canonical service_directory declaration. A service’s authority, active host, and per-host call endpoints are always read from the registry; the capability has no product, host, or port map of its own.

Invocations

• stado route list [--json]
  • Lists every key in service_directory.services.
  • For each service, shows service_directory.authority, active_host, every endpoints[<host>].url, and the currently open local $HOME/.stado/forwards/<service>.local marker, if any.
  • --json emits one object with authority and services arrays.
• stado route open <SERVICE> [--target <TARGET>] (--local|--remote) [--json]
  • Resolves <SERVICE> from service_directory.services and, by default, its endpoint from endpoints[active_host].url.
  • --target selects any host for which the service directory declares an endpoint; this is how a consumer host materializes the address it is told to call.
  • --local atomically writes the owner-only one-line marker under the invoking account’s $HOME/.stado/forwards/.
  • --remote writes that same marker on the selected endpoint holder through its registry-managed host channel.
  • The direction is mandatory. Stado never guesses whether a real host or the invoking account should change.
  • --json emits the authority, active host, declared endpoint, marker path/location, and status: open.
• stado route close <SERVICE> [--target <TARGET>]
  • Resolves the same directory entry and target endpoint, then removes its open marker. A local marker is removed first; if none exists, the selected remote endpoint holder is checked. Success states that no marker remains.
• stado route capability <SERVICE> [--json]
  • Resolves the service’s active_host and reads that host’s Skarbiec capability route table. It reports route coordinates only; no credential value crosses the channel.
  • --json emits the service, authority, active host, vault location, and Skarbiec route report.
• stado route key <TARGET> [--json]
  • Reads service_directory.authority, establishes TARGET’s resolver public key if needed, and authorizes that public key on the declared authority host. The private key never leaves TARGET.
  • --json emits the directory authority and resolver-key authorization report.
• stado route placement publish [--mobile] [--json]
  • Takes its target set only from service_directory.services.*.active_host, deduplicates it, and publishes each target’s declared weles placement policy.
  • --mobile limits the directory-selected active hosts to targets that declare mobile_runtime.
  • --json emits the authority, mobile filter, and every publication report.

Declaration

The routing declaration lives in the service_directory block of canonical registry.json in the configured storage backend:

• service_directory.authority.target and .command identify the directory authority.
• service_directory.services.<service>.active_host identifies the serving registry target.
• service_directory.services.<service>.endpoints.<host>.url is the endpoint that host is told to call.

Forward markers are materialized caches of that declaration. Their fixed consumer contract remains $HOME/.stado/forwards/<service>.local, one URL plus a trailing newline, mode 0600 inside a mode 0700 directory.

Placement publication additionally reads the selected registry targets’ declared weles.enabled, weles.actions, host identity, and—under --mobile—the presence of mobile_runtime. The generated document is installed at $HOME/.config/weles/placement-policy.json and stamped with _source.by = "stado route placement publish" and the registry generation.

Refusals

The declaration-resolution refusals are exact sentences:

• <service> is not in the service directory; add it to service_directory.services
• the service directory declares no authority; add it to service_directory.authority
• <service> declares no active host; add it to service_directory.services.<service>.active_host
• <service> declares no endpoint for <target>; add it to service_directory.services.<service>.endpoints.<target>
• route open requires --local or --remote; choose where the declared forward marker must live
• <service> has no open forward marker; run stado route open <service> --local or stado route open <service> --remote first
• the service directory has no active host declaring mobile_runtime; add it to the serving target declaration
• the service directory declares no active hosts; add active_host to service_directory.services entries
• <target>: no Skarbiec binary at <path>; install Skarbiec at that path on the declared active host
• "<target>" IS the service-directory authority, so its resolver reads the canonical store directly and opens no session to authorize
• <target>: the target reported no resolver public key; ensure its HOME is writable and run stado route key <target> again

A registry with no directory is refused with: the registry declares no service directory; add service_directory to registry.json.

Replaced host verbs

The routing capability removes all seven incident verbs from stado host:

1. host forward-local
2. host forward-remote
3. host forward-close
4. host capability-route
5. host resolver-key
6. host publish-placement-policy
7. host mobile-placement

No alias or deprecated wrapper remains.

Stado Desktop

The Hosts inspector contains a Routes section backed by stado route list --json. It shows the directory authority, every declared service, its active host, the endpoint the selected host is told to call, and whether a local forward is open. An open row includes the exact URL and marker path; a failed read renders Stado’s refusal rather than an empty route list.